Computing Checksums

When uploading an archive, you must include both the x-amz-sha256-tree-hash and
x-amz-content-sha256 headers. The x-amz-sha256-tree-hash
header is a checksum of the payload in your request body. This topic describes how
to
calculate the x-amz-sha256-tree-hash header. The
x-amz-content-sha256 header is a hash of the entire payload and is required
for authorization. For more information, see Example Signature Calculation for Streaming API.

The payload of your request can be an:

Entire archive— When uploading an archive in a
single request using the Upload Archive API, you send the entire archive in the
request body. In this case, you must include the checksum of the entire archive.

Archive part— When uploading an archive in parts
using the multipart upload API, you send only a part of the archive in the
request body. In this case, you include the checksum of the archive part. And
after you upload all the parts, you send a Complete Multipart Upload request,
which must include the checksum of the entire archive.

The checksum of the payload is a SHA-256 tree hash. It is called a tree hash because
in the
process of computing the checksum you compute a tree of SHA-256 hash values.
The
hash value at the root is the checksum for the entire archive.

Note

This section describes a way to compute the SHA-256 tree hash. However, you may use
any
procedure as long as it produces the same result.

You compute the SHA-256 tree hash as follows:

For each 1 MB chunk of payload data, compute the SHA-256 hash. The last chunk of data
can
be less than 1 MB. For example, if you are uploading a 3.2 MB archive, you
compute the SHA-256 hash values for each of the first three 1 MB chunks of data,
and then compute the SHA-256 hash of the remaining 0.2 MB data. These hash
values form the leaf nodes of the tree.

Build the next level of the tree.

Concatenate two consecutive child node hash values and compute the SHA-256 hash of
the
concatenated hash values. This concatenation and generation of the
SHA-256 hash produces a parent node for the two child nodes.

When only one child node remains, you promote that hash value to the next level in
the
tree.

Repeat step 2 until the resulting tree has a root. The root of the tree provides a
hash of
the entire archive and a root of the appropriate subtree provides the hash for
the part in a multipart upload.

Tree Hash Example 1: Uploading an archive in a
single request

When you upload an archive in a single request using the Upload Archive API (see Upload Archive (POST archive)), the request payload
includes the entire archive. Accordingly, you must include the tree hash of the entire
archive in the x-amz-sha256-tree-hash request header. Suppose you want to
upload a 6.5 MB archive. The following diagram illustrates the process of creating
the
SHA-256 hash of the archive. You read the archive and compute the SHA-256 hash for
each
1 MB chunk. You also compute the hash for the remaining 0.5 MB data and then build
the
tree as outlined in the preceding procedure.

Tree Hash Example 2: Uploading an archive using a
multipart upload

The process of computing the tree hash when uploading an archive using multipart upload
is
the same when uploading the archive in a single request. The only difference is that
in
a multipart upload you upload only a part of the archive in each request (using the
Upload Part (PUT uploadID) API), and therefore
you provide the checksum of only the part in the x-amz-sha256-tree-hash
request header. However, after you upload all parts, you must send the Complete
Multipart Upload (see Complete Multipart Upload (POST uploadID)) request with a tree hash of the entire
archive in the x-amz-sha256-tree-hash request header.

Computing the Tree Hash of a File

The algorithms shown here are selected for demonstration purposes. You can optimize
the code
as needed for your implementation scenario. If you are using an AWS SDK to program
against Amazon Glacier, the tree hash calculation is done for you and you only need
to
provide the file reference.

Example 1: Java Example

The following example shows how to calculate the SHA256 tree hash of a file using
Java. You can run this example by either supplying a file location as an argument
or
you can use the TreeHashExample.computeSHA256TreeHash method directly
from your code.