Man Linux: Main Page and Category List

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)