NAME

       fitsmd5 - Compute/update the DATAMD5 keyword/value

SYNOPSIS

       fitsmd5 [-u] [-s] [-a] <FITS files...>

DESCRIPTION

       fitsmd5  computes  the  MD5  signature of all data sections in a FITS file, and prints out the results on
       stdout. This command can optionally update the main FITS header in modifying the  value  of  the  DATAMD5
       key.

       This  command is useful to give a unique ID to a FITS file. The algorithm simply browses through all data
       sections in the input file and passes the data blocks to an MD5 hash function.  The  final  result  is  a
       128-bit signature that can be used to uniquely identify the file.

       This approach is meant to provide a tool to tag FITS files with unique IDs, it is not meant to be used as
       a checksum for file integrity (the CKSUM key is the solution for that), although it could be used in that
       spirit.  The  main  point  is  that only data sections are taken into account, leaving the possibility of
       changing the headers without affecting the data signature.

       MD5 hashing is cryptographically strong, which means the probability of having two different  FITS  files
       getting  the  same  ID  is almost zero. It should be good enough to assign a unique ID to several tens of
       thousands of frames. Since there is still a tiny but non-zero possibility that two different  files  will
       get  an  identical  key,  this approach is not recommended to tag very large numbers of files (typically:
       millions of them). If you do have a large database of FITS files, using a timestamp is usually  a  better
       approach.

       The MD5 signature is a good solution to tag a list of FITS files which might have originated from various
       sources  on  which  the  database  maintainer  has  no  control. Typically, calibration databases holding
       calibration frames for a given instrument, receive data from different actors who might not  be  in  sync
       with  unique file naming conventions. This command makes sure it is always possible to assign a unique ID
       to each frame.

       Notice that if the input FITS file has no data section, the returned MD5 key  will  be  non-zero  (it  is
       exactly  d41d8cd98f00b204e9800998ecf8427e).  This  signature also offers the interesting property that if
       two files have exactly the same pixels (bit-wise comparisons) they will get the same ID, this  is  useful
       e.g. for regression tests.

       If  you  want to produce files containing the DATAMD5 key in their main headers, you should use the qfits
       library, which always inserts this key. If you are  working  with  other  FITS-processing  software,  you
       should  allocate  an  empty  DATAMD5  placeholder and apply this command with the -u option to update the
       value.

       Notice that this command can also compute the MD5 sum of a complete file, not just its data sections (see
       -a option). In this mode, the command is completely identical to the GNU md5sum command, which is used to
       compute checksums on files. Input files in that case need not be FITS,  though  they  still  need  to  be
       regular files.

OPTIONS

       -u     Try to update the DATAMD5 keyword in the main header if present.

       -s     Silent mode: run without printing any message.

       -a     Compute the MD5 sum on all bits in the file. In this mode, the command behaves like the GNU md5sum
              command, to be used e.g. as a checksum. This option excludes all others.

FILES

       Input files to fitsmd5 shall comply with the FITS format, except when used with -a option.

                                                   01 Aug 2001                                        fitsmd5(1)