Calculate Docker Image Digest from Tar File

A Docker image digest is not calculated as the SHA256 hash of the entire tar file. Instead, it’s computed from the image’s manifest and configuration JSON files within the tar archive. To get the correct digest from a saved tar file, you need to extract and hash the specific JSON content that Docker uses for digest calculation.

Contents

• Understanding Docker Image Structure
• Step-by-Step Digest Calculation Process
• Tools and Methods for Extraction
• Alternative Approaches
• Practical Example

Understanding Docker Image Structure

When you save a Docker image using docker image save, the resulting tar file contains several key components that determine the digest:

• Manifest file: Describes the image structure and references the config file
• Config file: Contains image metadata, environment variables, and layer references
• Layer files: Individual tar archives containing the actual filesystem layers

As explained in the Docker documentation, “Each platform-specific image has its own digest (e.g., sha256:94a0…ea1a for linux/amd64).” The digest is calculated from the content of these specific files, not the entire tar archive.

The digest is a SHA256 (by default) of a JSON string that represents the image configuration. - Stack Overflow

The manifest file typically contains references to:

• The configuration file with its own digest
• Layer files with their individual digests
• Platform-specific metadata

Step-by-Step Digest Calculation Process

To calculate the Docker image digest from a tar file, follow these steps:

1. Extract the tar file to access its contents
2. Locate the manifest file (usually named manifest.json)
3. Extract the config file referenced in the manifest
4. Calculate SHA256 of the config file content
5. Compare with Docker’s reported digest

The actual digest calculation process involves:

• Reading the manifest to find the config file reference
• Extracting the config file content
• Computing SHA256 of the config JSON content
• Using this result as the image digest

According to Maori Geek’s technical explanation, “This layer.tar SHA is referenced inside the config file, and the location of the layer is in the manifest. So this is where the digest comes from.”

Tools and Methods for Extraction

Method 1: Using Command Line Tools

# Extract the tar file
mkdir -p /tmp/extracted
tar -xf /tmp/my-image.tar -C /tmp/extracted

# Find the manifest file
find /tmp/extracted -name "manifest.json"

# Extract the config file reference (example)
cat /tmp/extracted/manifest.json | jq -r '.[0].Config'  # For JSON parsing

# Calculate SHA256 of the config file
sha256sum /tmp/extracted/config.json

Method 2: Using Python Script

import tarfile
import hashlib
import json

def calculate_docker_digest(tar_path):
    with tarfile.open(tar_path, 'r') as tar:
        # Extract manifest
        manifest_file = tar.extractfile('manifest.json')
        manifest = json.load(manifest_file)
        
        # Get config file path from manifest
        config_path = manifest[0]['Config']
        
        # Extract and hash config content
        config_file = tar.extractfile(config_path)
        config_content = config_file.read()
        
        # Calculate SHA256 digest
        digest = hashlib.sha256(config_content).hexdigest()
        return f"sha256:{digest}"

# Usage
print(calculate_docker_digest('/tmp/my-image.tar'))

Method 3: Using Docker Tools

If you have Docker available, you can use:

# Load the image from tar
docker image load -i /tmp/my-image.tar

# Get the digest
docker image inspect --format='{{index .RepoDigests 0}}' my-image

Alternative Approaches

Using Specialized Tools

Several tools exist to help with Docker image digest calculation:

1. skopeo: Can inspect and manipulate container images
2. oras: Open Registry Client for working with OCI artifacts
3. cosign: Container signing tool with digest verification capabilities

Direct Registry Comparison

As mentioned in Remind’s engineering blog, “When we use the digest as the identifier, Docker will not only pull the image with that digest, but also calculate the sha256 digest of what.” You can verify your calculated digest by pulling the image using the digest:

docker pull my-image@sha256:your-calculated-digest

Practical Example

Let’s walk through a complete example:

# Save the image
docker image save nginx:alpine --output /tmp/nginx.tar

# Extract the tar
mkdir /tmp/nginx_extracted
tar -xf /tmp/nginx.tar -C /tmp/nginx_extracted

# Examine the manifest structure
cat /tmp/nginx_extracted/manifest.json | jq .

# Extract and calculate config digest
CONFIG_PATH=$(cat /tmp/nginx_extracted/manifest.json | jq -r '.[0].Config')
sha256sum "/tmp/nginx_extracted/$CONFIG_PATH"

# Compare with Docker's digest
docker image inspect nginx:alpine --format='{{index .RepoDigests 0}}'

The output should match between your calculated digest and Docker’s reported digest.

As noted in Windsock.io’s technical explanation, “The digests that Docker uses for layer ‘diffs’ on a Docker host, contain the sha256 hash of the tar archived content of the diff.” This applies to the config file calculation as well.

Conclusion

To calculate the correct Docker image digest from a saved tar file:

1. Extract the tar file to access its internal structure
2. Locate the manifest file (usually manifest.json)
3. Find the config file path referenced in the manifest
4. Extract and hash the config JSON content using SHA256
5. Prefix with “sha256:” to match Docker’s format

The key insight is that Docker image digests are calculated from the image configuration JSON, not the entire tar file. This approach ensures consistency with Docker’s digest calculation method and allows you to verify image integrity without loading the image into Docker.

For production use, consider implementing automation scripts that follow this process, or use existing tools like skopeo that handle these calculations internally. Always verify your calculated digests against Docker’s official reports to ensure accuracy.

Sources

1. How is digest of Docker image calculated? - Stack Overflow
2. sha256 - get digest of saved docker image (the saved .tar file) - Stack Overflow
3. Image digests | Docker Docs
4. How to Digest a Docker Image | Maori Geek
5. Calculate Docker digests and are they mutable? | Kosli
6. Docker image digests | Remind
7. About container image digests | Google Kubernetes Engine
8. Explaining Docker Image IDs | Windsock.io