SHA-256 Support

Starting with version 5.5, Artifactory supports SHA-256 natively. The SHA-256 checksum is calculated at deployment time and stored in the database.

📘

Backward compatibility

The Set Item SHA256 Checksum REST API endpoint (which sets an artifact's SHA-256 checksum as one of its properties) is still supported for backward compatibility. However, this endpoint is no longer needed.

Artifactory SHA-256 support is available across key workflows:

• Use SHA-256 in AQL queries, and receive it in query responses.
• Receive SHA-256 values in download headers.
• Use SHA-256 in the Deploy Artifact and Deploy Artifact by Checksum REST API endpoints.
• Receive SHA-256 values when downloading a folder.
• View SHA-256 in the General Information tab in the Artifact Repository Browser.
• Use SHA-256 in additional REST API search endpoints.

📘

Full SHA-256 coverage after upgrade

Newly uploaded artifacts get SHA-256 automatically. Artifacts that existed before the upgrade may not yet have SHA-256 values in the database.

To use SHA-256 features fully, migrate the database to include SHA-256 so each artifact record contains a SHA-256 value.

Migrate The Database To Include SHA-256

📘

Plan for migration resource usage

Depending on database size, migration can be resource intensive. To control load, tune the system properties listed below or use the REST APIs. Review the full process before running migration in production.

Configure migration in artifactory.system.properties or with the Start SHA256 Migration Task and Stop SHA256 Migration Task REST APIs. The process does the following:

• Find database records that do not have a SHA-256 value.

• For each record, find all records with the same SHA1 value.

  • If one record already has SHA-256, use it to update the others.
  • If none has SHA-256, calculate it once and update the others.

• If no other record has the same SHA1 value, calculate SHA-256 for that record.

👍

Run garbage collection first

Migration completes when all relevant database entries include SHA-256 values. The database may still contain entries for artifacts that were deleted but not yet removed by Garbage Collection. Run garbage collection manually before migration to reduce download volume and total runtime.

Configure The SHA-256 Migration Process

The migration process can be configured through the following system properties or using the Start SHA256 Migration Task and Stop SHA256 Migration Task REST API endpoints.

By default, the migration will run on any node in the cluster (arbitrarily). However, using the forceRunOnNodeId property described below, you can configure it to run on a specific node.

👍

Run migration on a dedicated node

You can dedicate a specific node to run migration and allocate extra resources to complete it faster.

📘

Set forceRunOnNodeId on all HA nodes

To run migration on one specific node, set artifactory.sha2.migration.job.forceRunOnNodeId on every node in the cluster. Artifactory still runs migration only on the matching node ID.

You can paste the following sample snippet into your artifactory.system.properties. Adjust the number of workers as appropriate based on I/O and CPU utilization.

Example artifactory.system.properties snippet

##SHA2 Migration block
artifactory.sha2.migration.job.enabled=true
artifactory.sha2.migration.job.queue.workers=5

📘

Restart required

For migration configuration changes to take effect, restart the instance (or the selected HA node). The default values are tuned to reduce production impact. You can increase throughput by tuning them, but higher values may affect system performance.

Monitor The SHA-256 Migration Process

Migration duration depends on storage size and configured parameters. Monitor status and errors in JFROG_HOME/artifactory/var/log/artifactory-sha256-migration.log. Some events (for example, start and startup errors) are also written to JFROG_HOME/artifactory/var/log/artifactory-service.log.

📘

Post-migration cleanup

After migration completes, it is recommended (though not mandatory) to remove SHA-256-related system properties and restart.