Update docs to mention sha256 etc.
authorSteve McIntyre <steve@einval.com>
Thu, 31 Oct 2019 19:03:43 +0000 (19:03 +0000)
committerSteve McIntyre <steve@einval.com>
Thu, 31 Oct 2019 19:03:43 +0000 (19:03 +0000)
doc/TechDetails.txt
doc/jigdo-file.sgml

index e7d0063..041c887 100644 (file)
@@ -34,11 +34,11 @@ looked up in a hash table which contains the checksums of the input
 files.
 
 As soon as the first blockLen bytes of a file have been seen in the
-image this way, the program starts calculating the MD5 sum of blocks
-of length md5BlockLength (where blockLen < md5BlockLength; the
-defaults are 1k, 64k resp.). These MD5 checksums are compared to
-pre-calculated MD5 sums of md5BlockLength-sized chunks of the file
-that matched, until one doesn't match, or the last one matched.
+image this way, the program starts calculating the checksums of blocks
+of length csumBlockLength (where blockLen < csumBlockLength; the
+defaults are 1k, 64k resp.). These checksums are compared to
+pre-calculated sums of md5BlockLength-sized chunks of the file that
+matched, until one doesn't match, or the last one matched.
 
 Unfortunately, having to deal with situations like overlapping matches
 in the image, and output of the .template to stdout, lead to quite
@@ -57,15 +57,14 @@ The jigdo-file file cache
 
 Even without --cache specified, jigdo-file uses an internal cache for
 holding information about files. This information includes at least:
-file length, rsync sum of head of file, MD5 sums of chunks of file,
-MD5 sum of the entire file.
+file length, rsync sum of head of file, checksums of chunks of file,
+checksums of the entire file.
 
 When files are first entered into the cache, the entire file is *not*
 yet read, only enough of it to generate the rsync sum and the first
-chunk's MD5 sum. (If this is also the last MD5 sum because the file is
-small, everything is generated.) The rest of the file is only read "on
-demand" if/when necessary.
-
+chunk's checksums. (If this is also the last block checksum because
+the file is small, everything is generated.) The rest of the file is
+only read "on demand" if/when necessary.
 
 
 File format of .template and .tmp files
@@ -75,7 +74,7 @@ The image template files consist of three types of parts:
 
  - Header: Short ASCII header identifying the file as a jigdo template
  - Raw data: those parts of the image that were not matched,
-   compressed with zlib
+   compressed with zlib/bzip2
  - Description: A description of the image, saying which parts were
    matched by files and are thus not included in the template
 
@@ -130,10 +129,10 @@ Description
 This is binary data. Integer values are little-endian. File lengths
 are 6 bytes long - 256TB ought to be enough for everybody...
 
-The order of entries with type==2 or type==6 corresponds to how
-matched files and areas of unmatched data appear in the image file.
-There must only be one entry of type==5 in the list [which must
-probably be the last entry].
+The order of entries with type==2 or type==6/9 corresponds to how
+matched files and areas of unmatched data appear in the image
+file. There must only be one entry of type==5/8 in the list [which
+must probably be the last entry].
 
 The pseudo program below would be suitable for decoding the
 description data.
@@ -147,6 +146,10 @@ description data.
                     case 5: "Information about the image file"
  6      imgLen        "Length in bytes of the original image"
 16      imgMD5        "MD5 checksum of the original image"
+ 4      blockLen      "Nr of bytes used for calculating RsyncSums below"
+                    case 8: "Information about the image file, using SHA256"
+ 6      imgLen        "Length in bytes of the original image"
+32      imgSHA256     "SHA256 checksum of the original image"
  4      blockLen      "Nr of bytes used for calculating RsyncSums below"
                     case 2: "Unmatched data, contained in 'Raw data'"
  6      skipLen       "Length in bytes of area of unmatched data"
@@ -155,9 +158,16 @@ description data.
  8      fileRsync     "RsyncSum64 of first blockLen bytes of the file.
                        fileLen < blockLen never happens."
 16      fileMD5       "MD5 checksum of the file"
+                    case 9: "Information about matched file, using SHA256"
+ 6      fileLen       "Length in bytes of file contained in image"
+ 8      fileRsync     "RsyncSum64 of first blockLen bytes of the file.
+                       fileLen < blockLen never happens."
+32      fileSHA256    "SHA256 checksum of the file"
                   }
                 }
  6      descLen "Length of part - identical to descLen at start of part"
+
+
 ----------------------------------------------------------------------
 The following types are obsolete:
 
@@ -184,8 +194,8 @@ available at the end of template creation.]
 
 Note: In the DESC part appended to a *temporary image file*,
 jigdo-file uses another type of entry: Once the type of a type==6
-entry changes to type==7, that entry's data has successfully been
-written to the image.
+entry changes to type==7 (or type==7 to type==10), that entry's data
+has successfully been written to the image.
 
 
 Raw data
@@ -198,7 +208,7 @@ For each type==2 entry in the description data, the uncompressed
 stream contains skipLen bytes of data. This is data that did not match
 any of the files presented to the creator of the template.
 
-For each type==6 entry in the description data, the raw data stream
+For each type==6/7 entry in the description data, the raw data stream
 contains _nothing_at_all_ - in other words, the raw data is just a
 number of concatenated type==2 data chunks.
 
@@ -233,7 +243,6 @@ ranges.
 Note that the data of one type==2 entry in the description data may be
 distributed over more than one raw data part.
 
-
 File format version history
 ---------------------------
 
@@ -243,3 +252,4 @@ File format version history
 1.2 (jigdo-file/0.7.2): Format change in template files: In addition
     to raw data that is gzipped ("DATA"), allow bzip2 ("BZIP") raw
     data.
+1.3 (jigdo-file/0.8.0): Addition of sha256 data to augment/replace md5
index 25317fe..d9667b3 100644 (file)
       </varlistentry>
 
       <varlistentry>
-        <term><option>--md5-block-size=<replaceable
-          >BYTES</replaceable></option></term>
+        <term><option>--checksum-block-size</option>
+          <option>--md5-block-size=<replaceable>BYTES</replaceable></option></term>
         <listitem>
           <para><emphasis>Uninteresting internal parameter.</emphasis>
           Set size of blocks into which files are subdivided. The
             <para>When <emphasis>adding</emphasis> new information to
             the supplied file, <command>jigdo-file</command> will not
             insert new lines into the `<literal>[Parts]</literal>'
-            section if an entry for the same MD5 checksum (but not
+            section if an entry for the same checksum (but not
             necessarily with the same URI!) already exists, and it
             will not insert new lines into the
             `<literal>[Servers]</literal>' section if a completely
                 >lNVdUSqbo2yqm33webrhnw</literal>" - The md5sum of the
                 matched file, in Base64-like format.</para></listitem>
 
+                <listitem><para><envar>SHA256SUM</envar>="<literal
+                >QXBJ8VZKeh0NXH0uOhdhgguPPE5tT1wvYO27sLx9Fsc</literal>" - The sha256sum of the
+                matched file, in Base64-like format.</para></listitem>
+
                 <listitem><para><envar>FILE</envar>="<literal
                 >/path//a/b/file</literal>" - For convenience, the
                 complete path of the file. The variable is always set
       <para>If the checksum cannot be found in the
       `<literal>[Parts]</literal>' section (this Should Not Happen
       unless you deleted that section), a lookup is instead made for
-      `MD5Sum:<replaceable>&lt;checksum&gt;</replaceable>', just like
-      with <command>jigdo</command>. (Thus, if you want to get rid of
-      the `<literal>[Parts]</literal>' section, you can do so if you
-      rename each part to its own checksum.)</para>
+      `MD5Sum:<replaceable>&lt;checksum&gt;</replaceable>' and
+      `SHA256Sum:<replaceable>&lt;checksum&gt;</replaceable>', just
+      like with <command>jigdo</command>. (Thus, if you want to get
+      rid of the `<literal>[Parts]</literal>' section, you can do so
+      if you rename each part to its own checksum.)</para>
 
       <variablelist>
         <varlistentry>
           <listitem>
 
             <para><emphasis>This is the default.</emphasis> This only
-            causes the first <option>--md5-block-size</option> bytes
+            causes the first <option>--checksum-block-size</option> bytes
             of each file to be read. If the cache is used later by
             <command>jigdo-file make-image</command>, the rest of the
             file will be read once these first bytes are recognized in
       <option>--cache</option> will be used for querying files' MD5
       checksums and/or writing the checksums of scanned files.</para>
 
+    </refsect2>
+    <!-- ========================================= -->
+    <refsect2 id="sha256sum">
+      <title><command>sha256sum</command>, <command>sha256</command></title>
+
+      <para>Reads all the <replaceable>FILES</replaceable> and prints
+      out SHA256 checksums of their contents. This command is quite
+      similar to <citerefentry>
+        <refentrytitle>sha256sum</refentrytitle><manvolnum>1</manvolnum>
+      </citerefentry>, except that the checksum is output in the
+      Base64-like encoding which is also used elsewhere by
+      <command>jigdo-file</command>.</para>
+
+      <para>The <replaceable>FILES</replaceable> arguments are
+      processed in the same way as with the other commands, which
+      means that recursion automatically takes place for any arguments
+      that are directories, and that symbolic links are not listed
+      except when the file(s) they point to are not reachable
+      directly.</para>
+
+      <para>In the checksum list printed on standard output, only the
+      part of the filename following any `<literal>//</literal>' (or
+      `<literal>\.\</literal>' on Windows) is printed. Any
+      <option>--cache</option> will be used for querying files' SHA256
+      checksums and/or writing the checksums of scanned files.</para>
+
+
     </refsect2>
     <!-- ========================================= -->
     <refsect2 id="list-template">
       already been successfully written to the temporary file:</para>
 
       <screen
->in-template  <replaceable>offset-in-image  length</replaceable>
-need-file    <replaceable>offset-in-image  length  file-md5sum  filestart-rsyncsum</replaceable>
-have-file    <replaceable>offset-in-image  length  file-md5sum  filestart-rsyncsum</replaceable>
-image-info   <replaceable>image-length  image-md5sum  rsyncsum-size</replaceable>
+>in-template      <replaceable>offset-in-image  length</replaceable>
+need-file-md5     <replaceable>offset-in-image  length  file-md5sum  filestart-rsyncsum</replaceable>
+have-file-sha256  <replaceable>offset-in-image  length  file-sha256sum  filestart-rsyncsum</replaceable>
+image-info-sha256 <replaceable>image-length  rsyncsum-size image-sha1sum  </replaceable>
 </screen>
 
     </refsect2>
@@ -998,7 +1030,7 @@ image-info   <replaceable>image-length  image-md5sum  rsyncsum-size</replaceable
     of the image could not be matched (e.g. it was directory
     information), the data is compressed and written directly to the
     template. However, if a matching file was found, its data is
-    omitted from the template. Instead, only a reference (an MD5
+    omitted from the template. Instead, only a reference (an MD5 or SHA256
     checksum of the file) is inserted in the template.</para>
 
     <para>Note that the template data only contains binary data, it
@@ -1006,10 +1038,10 @@ image-info   <replaceable>image-length  image-md5sum  rsyncsum-size</replaceable
     edited in case any of these values need to be changed. All that
     information is stored in the `<filename>.jigdo</filename>' file, a
     text file to which you can add URLs for your server(s). The jigdo
-    file provides a mapping for each MD5 checksum to one or more
+    file provides a mapping for each MD5/SHA256 checksum to one or more
     alternative download locations for the corresponding part.</para>
 
-    <para>Apart from the mapping of MD5 sums to URIs, the jigdo file
+    <para>Apart from the mapping of MD5/SHA256 sums to URIs, the jigdo file
     also contains an URI pointing to a download location for the
     template file. This way, the <command>jigdo</command> download
     tool only needs to be given one URI (that of the
@@ -1096,6 +1128,7 @@ Generator=jigdo-file/1.0.0</screen>
 Filename=<replaceable>"filename for saving on user's disc"</replaceable>
 Template=<replaceable>"URI where to fetch template file"</replaceable>
 Template-MD5Sum=OQ8riqT1BuyzsrT9964A7g
+Template-SHA256Sum=MVJIxGifflRF9K8ERdbqoyns4Ucw9Xy1ubdnE6CtMbo
 ShortInfo=<replaceable>single-line description of the image (200 characters max.)</replaceable>
 Info=<replaceable>long description (5000 characters max.)</replaceable></screen>
 
@@ -1105,9 +1138,10 @@ Info=<replaceable>long description (5000 characters max.)</replaceable></screen>
       >pathname</replaceable>' (<emphasis>UNIMPLEMENTED</emphasis>),
       as described below.</para>
 
-      <para>The `Template-MD5Sum' entry is added by
-      <command>jigdo-file</command> and specifies the MD5 checksum of
-      the generated `<filename>.template</filename>' file. It is used
+      <para>The `Template-MD5Sum' and/or `Template-MD5Sum' entries are
+      added by
+      <command>jigdo-file</command> and specify the checksum of the
+      generated `<filename>.template</filename>' file. It is used
       by <command>jigdo</command> to detect cases where the downloaded
       template data is corrupted or belongs to a different
       image.</para>
@@ -1156,7 +1190,7 @@ kyfebwu6clbYqqWUdFIyaw=LabelB:some/path/part2
 -J9UAimo0Bqg9c0oOXI1mQ=http://some.where.com/part3</screen>
 
       <para>All lines in the section, which provides the mapping from
-      MD5 checksums to URIs, have the same format: On the left side of
+      checksums to URIs, have the same format: On the left side of
       the `<literal>=</literal>' the checksum (encoded with a
       Base64-like encoding) is given, and on the right a string
       corresponding to the part with this checksum; either a complete
@@ -1166,20 +1200,21 @@ kyfebwu6clbYqqWUdFIyaw=LabelB:some/path/part2
       <replaceable>Label</replaceable> in the
       `<literal>[Servers]</literal>' section.</para>
 
-      <para>In case a particular MD5 checksum cannot be found in any
+      <para>In case a particular checksum cannot be found in any
       `<literal>[Parts]</literal>' section by
       <command>jigdo</command>, the program will perform a lookup for
-      `<literal>MD5Sum:</literal><replaceable
-      >&lt;checksum&gt;</replaceable>', e.g. for
-      `<literal>MD5Sum:xJNkjrq8NYMraeGavUpllw</literal>' if you
-      deleted the line for `part0' above.</para>
+      `<literal>MD5Sum:</literal><replaceable >&lt;checksum&gt;</replaceable>'
+      and
+      `<literal>SHA256Sum:</literal><replaceable >&lt;checksum&gt;</replaceable>',
+      e.g. for `<literal>MD5Sum:xJNkjrq8NYMraeGavUpllw</literal>' if
+      you deleted the line for `part0' above.</para>
 
       <para>A checksum appearing multiple times in this section
       indicates alternative download locations for the part.</para>
 
       <para>There may be any number of `<literal>[Parts]</literal>'
       sections in the file; they are all considered when looking up
-      MD5 checksums.</para>
+      checksums.</para>
 
       <para><command>jigdo-file</command> always puts the
       `<literal>[Parts]</literal>' section at the end of the file, and
@@ -1505,6 +1540,12 @@ Any text, except that lines must not begin with `['.</screen>
       </citerefentry>,
       <citerefentry>
         <refentrytitle>md5sum</refentrytitle><manvolnum>1</manvolnum>
+      </citerefentry>,
+      <citerefentry>
+        <refentrytitle>sha256sum</refentrytitle><manvolnum>1</manvolnum>
+      </citerefentry>,
+      <citerefentry>
+        <refentrytitle>jigit-mkimage</refentrytitle><manvolnum>1</manvolnum>
       </citerefentry>
     </para>
 
@@ -1518,6 +1559,11 @@ Any text, except that lines must not begin with `['.</screen>
     <email>jigdo atterer.org</email>, to make downloading of CD ROM
     images for the Debian Linux distribution more convenient.</para>
 
+    <para>Steve McIntyre <email>steve einval.com</email> picked up
+    later development of jigdo after Richard had moved on - see
+    the <ulink url="https://git.einval.com/cgi-bin/gitweb.cgi?p=jigdo.git;a=summary">git
+    repo work</ulink> or packages in Debian for more recent releases.
+
   </refsect1>
 </refentry>