github.com/ttys3/engine@v17.12.1-ce-rc2+incompatible/pkg/tarsum/tarsum_spec.md (about)

     1  page_title: TarSum checksum specification
     2  page_description: Documentation for algorithms used in the TarSum checksum calculation
     3  page_keywords: docker, checksum, validation, tarsum
     4  
     5  # TarSum Checksum Specification
     6  
     7  ## Abstract
     8  
     9  This document describes the algorithms used in performing the TarSum checksum
    10  calculation on filesystem layers, the need for this method over existing
    11  methods, and the versioning of this calculation.
    12  
    13  ## Warning
    14  
    15  This checksum algorithm is for best-effort comparison of file trees with fuzzy logic.
    16  
    17  This is _not_ a cryptographic attestation, and should not be considered secure.
    18  
    19  ## Introduction
    20  
    21  The transportation of filesystems, regarding Docker, is done with tar(1)
    22  archives. There are a variety of tar serialization formats [2], and a key
    23  concern here is ensuring a repeatable checksum given a set of inputs from a
    24  generic tar archive. Types of transportation include distribution to and from a
    25  registry endpoint, saving and loading through commands or Docker daemon APIs,
    26  transferring the build context from client to Docker daemon, and committing the
    27  filesystem of a container to become an image.
    28  
    29  As tar archives are used for transit, but not preserved in many situations, the
    30  focus of the algorithm is to ensure the integrity of the preserved filesystem,
    31  while maintaining a deterministic accountability. This includes neither
    32  constraining the ordering or manipulation of the files during the creation or
    33  unpacking of the archive, nor include additional metadata state about the file
    34  system attributes.
    35  
    36  ## Intended Audience
    37  
    38  This document is outlining the methods used for consistent checksum calculation
    39  for filesystems transported via tar archives.
    40  
    41  Auditing these methodologies is an open and iterative process. This document
    42  should accommodate the review of source code. Ultimately, this document should
    43  be the starting point of further refinements to the algorithm and its future
    44  versions.
    45  
    46  ## Concept
    47  
    48  The checksum mechanism must ensure the integrity and assurance of the
    49  filesystem payload.
    50  
    51  ## Checksum Algorithm Profile
    52  
    53  A checksum mechanism must define the following operations and attributes:
    54  
    55  * Associated hashing cipher - used to checksum each file payload and attribute
    56    information.
    57  * Checksum list - each file of the filesystem archive has its checksum
    58    calculated from the payload and attributes of the file. The final checksum is
    59    calculated from this list, with specific ordering.
    60  * Version - as the algorithm adapts to requirements, there are behaviors of the
    61    algorithm to manage by versioning.
    62  * Archive being calculated - the tar archive having its checksum calculated
    63  
    64  ## Elements of TarSum checksum
    65  
    66  The calculated sum output is a text string. The elements included in the output
    67  of the calculated sum comprise the information needed for validation of the sum
    68  (TarSum version and hashing cipher used) and the expected checksum in hexadecimal
    69  form.
    70  
    71  There are two delimiters used:
    72  * '+' separates TarSum version from hashing cipher
    73  * ':' separates calculation mechanics from expected hash
    74  
    75  Example:
    76  
    77  ```
    78  	"tarsum.v1+sha256:220a60ecd4a3c32c282622a625a54db9ba0ff55b5ba9c29c7064a2bc358b6a3e"
    79  	|         |       \                                                               |
    80  	|         |        \                                                              |
    81  	|_version_|_cipher__|__                                                           |
    82  	|                      \                                                          |
    83  	|_calculation_mechanics_|______________________expected_sum_______________________|
    84  ```
    85  
    86  ## Versioning
    87  
    88  Versioning was introduced [0] to accommodate differences in calculation needed,
    89  and ability to maintain reverse compatibility.
    90  
    91  The general algorithm will be describe further in the 'Calculation'.
    92  
    93  ### Version0
    94  
    95  This is the initial version of TarSum.
    96  
    97  Its element in the TarSum checksum string is `tarsum`.
    98  
    99  ### Version1
   100  
   101  Its element in the TarSum checksum is `tarsum.v1`.
   102  
   103  The notable changes in this version:
   104  * Exclusion of file `mtime` from the file information headers, in each file
   105    checksum calculation
   106  * Inclusion of extended attributes (`xattrs`. Also seen as `SCHILY.xattr.` prefixed Pax
   107    tar file info headers) keys and values in each file checksum calculation
   108  
   109  ### VersionDev
   110  
   111  *Do not use unless validating refinements to the checksum algorithm*
   112  
   113  Its element in the TarSum checksum is `tarsum.dev`.
   114  
   115  This is a floating place holder for a next version and grounds for testing
   116  changes. The methods used for calculation are subject to change without notice,
   117  and this version is for testing and not for production use.
   118  
   119  ## Ciphers
   120  
   121  The official default and standard hashing cipher used in the calculation mechanic
   122  is `sha256`. This refers to SHA256 hash algorithm as defined in FIPS 180-4.
   123  
   124  Though the TarSum algorithm itself is not exclusively bound to the single
   125  hashing cipher `sha256`, support for alternate hashing ciphers was later added
   126  [1]. Use cases for alternate cipher could include future-proofing TarSum
   127  checksum format and using faster cipher hashes for tar filesystem checksums.
   128  
   129  ## Calculation
   130  
   131  ### Requirement
   132  
   133  As mentioned earlier, the calculation is such that it takes into consideration
   134  the lifecycle of the tar archive. In that the tar archive is not an immutable,
   135  permanent artifact. Otherwise options like relying on a known hashing cipher
   136  checksum of the archive itself would be reliable enough. The tar archive of the
   137  filesystem is used as a transportation medium for Docker images, and the
   138  archive is discarded once its contents are extracted. Therefore, for consistent
   139  validation items such as order of files in the tar archive and time stamps are
   140  subject to change once an image is received.
   141  
   142  ### Process
   143  
   144  The method is typically iterative due to reading tar info headers from the
   145  archive stream, though this is not a strict requirement.
   146  
   147  #### Files
   148  
   149  Each file in the tar archive have their contents (headers and body) checksummed
   150  individually using the designated associated hashing cipher. The ordered
   151  headers of the file are written to the checksum calculation first, and then the
   152  payload of the file body.
   153  
   154  The resulting checksum of the file is appended to the list of file sums. The
   155  sum is encoded as a string of the hexadecimal digest. Additionally, the file
   156  name and position in the archive is kept as reference for special ordering.
   157  
   158  #### Headers
   159  
   160  The following headers are read, in this
   161  order ( and the corresponding representation of its value):
   162  * 'name' - string
   163  * 'mode' - string of the base10 integer
   164  * 'uid' - string of the integer
   165  * 'gid' - string of the integer
   166  * 'size' - string of the integer
   167  * 'mtime' (_Version0 only_) - string of integer of the seconds since 1970-01-01 00:00:00 UTC
   168  * 'typeflag' - string of the char
   169  * 'linkname' - string
   170  * 'uname' - string
   171  * 'gname' - string
   172  * 'devmajor' - string of the integer
   173  * 'devminor' - string of the integer
   174  
   175  For >= Version1, the extended attribute headers ("SCHILY.xattr." prefixed pax
   176  headers) included after the above list. These xattrs key/values are first
   177  sorted by the keys.
   178  
   179  #### Header Format
   180  
   181  The ordered headers are written to the hash in the format of
   182  
   183  	"{.key}{.value}"
   184  
   185  with no newline.
   186  
   187  #### Body
   188  
   189  After the order headers of the file have been added to the checksum for the
   190  file, the body of the file is written to the hash.
   191  
   192  #### List of file sums
   193  
   194  The list of file sums is sorted by the string of the hexadecimal digest.
   195  
   196  If there are two files in the tar with matching paths, the order of occurrence
   197  for that path is reflected for the sums of the corresponding file header and
   198  body.
   199  
   200  #### Final Checksum
   201  
   202  Begin with a fresh or initial state of the associated hash cipher. If there is
   203  additional payload to include in the TarSum calculation for the archive, it is
   204  written first. Then each checksum from the ordered list of file sums is written
   205  to the hash.
   206  
   207  The resulting digest is formatted per the Elements of TarSum checksum,
   208  including the TarSum version, the associated hash cipher and the hexadecimal
   209  encoded checksum digest.
   210  
   211  ## Security Considerations
   212  
   213  The initial version of TarSum has undergone one update that could invalidate
   214  handcrafted tar archives. The tar archive format supports appending of files
   215  with same names as prior files in the archive. The latter file will clobber the
   216  prior file of the same path. Due to this the algorithm now accounts for files
   217  with matching paths, and orders the list of file sums accordingly [3].
   218  
   219  ## Footnotes
   220  
   221  * [0] Versioning https://github.com/docker/docker/commit/747f89cd327db9d50251b17797c4d825162226d0
   222  * [1] Alternate ciphers https://github.com/docker/docker/commit/4e9925d780665149b8bc940d5ba242ada1973c4e
   223  * [2] Tar http://en.wikipedia.org/wiki/Tar_%28computing%29
   224  * [3] Name collision https://github.com/docker/docker/commit/c5e6362c53cbbc09ddbabd5a7323e04438b57d31
   225  
   226  ## Acknowledgments
   227  
   228  Joffrey F (shin-) and Guillaume J. Charmes (creack) on the initial work of the
   229  TarSum calculation.
   230