Use Maven checksums

When a Maven artifact is published to an AWS CodeArtifact repository, the checksum associated with each asset or file in the package is used to validate the upload. Examples of assets are jar, pom, and war files. For each asset, the Maven artifact contains multiple checksum files that use the asset name with an additional extension, such as md5 or sha1. For example, the checksum files for a file named my-maven-package.jar might be my-maven-package.jar.md5 and my-maven-package.jar.sha1.

Note

Maven uses the term artifact. In this guide, a Maven package is the same as a Maven artifact. For more information, see AWS CodeArtifact package.

Checksum storage

CodeArtifact does not store Maven checksums as assets. This means that checksums do not appear as individual assets in the output of the ListPackageVersionAssets API. Instead, checksums computed by CodeArtifact are available for each asset in all supported checksum types. For example, part of the response of calling ListPackageVersionAssets on the Maven package version commons-lang:commons-lang 2.1 is:

{
    "name": "commons-lang-2.1.jar",
    "size": 207723,
    "hashes": {
        "MD5": "51591549f1662a64543f08a1d4a0cf87",
        "SHA-1": "4763ecc9d78781c915c07eb03e90572c7ff04205",
        "SHA-256": "2ded7343dc8e57decd5e6302337139be020fdd885a2935925e8d575975e480b9",
        "SHA-512": "a312a5e33b17835f2e82e74ab52ab81f0dec01a7e72a2ba58bb76b6a197ffcd2bb410e341ef7b3720f3b595ce49fdd9994ea887ba08ff6fe21b2c714f8c405af"
    }
},
{
    "name": "commons-lang-2.1.pom",
    "size": 9928,
    "hashes": {
        "MD5": "8e41bacdd69de9373c20326d231c8a5d",
        "SHA-1": "a34d992202615804c534953aba402de55d8ee47c",
        "SHA-256": "f1a709cd489f23498a0b6b3dfbfc0d21d4f15904791446dec7f8a58a7da5bd6a",
        "SHA-512": "1631ce8fe4101b6cde857f5b1db9b29b937f98ba445a60e76cc2b8f2a732ff24d19b91821a052c1b56b73325104e9280382b2520edda4e7696698165c7e09161"
    }
},
        {
    "name": "maven-metadata.xml",
    "size": 121,
    "hashes": {
        "MD5": "11bb3d48d984f2f49cea1e150b6fa371",
        "SHA-1": "7ef872be17357751ce65cb907834b6c5769998db",
        "SHA-256": "d04d140362ea8989a824a518439246e7194e719557e8d701831b7f5a8228411c",
        "SHA-512": "001813a0333ce4b2a47cf44900470bc2265ae65123a8c6b5ac5f2859184608596baa4d8ee0696d0a497755dade0f6bf5e54667215a06ceae1effdfb7a8d30f88"
    }
}

Even though checksums are not stored as assets, Maven clients can still publish and download checksums at the expected locations. For example, if commons-lang:commons-lang 2.1 was in a repository called maven-repo, the URL path for the SHA-256 checksum of the JAR file would be:

/maven/maven-repo/commons-lang/commons-lang/2.1/commons-lang-2.1.jar.sha256

If you're uploading existing Maven packages (for example, packages previously stored in Amazon S3) to CodeArtifact using a generic HTTP client such as curl, it's not necessary to upload the checksums. CodeArtifact will generate them automatically. If you want to verify that the assets have been uploaded correctly, you can use the ListPackageVersionAssets API operation to compare the checksums in the response to the original checksum values for each asset.

Checksum mismatches during publishing

Apart from assets and checksums, Maven artifacts also contain a maven-metadata.xml file. The normal publishing sequence for a Maven package is for all assets and checksums to be uploaded first, followed by maven-metadata.xml. For example, the publishing sequence for the Maven package version commons-lang 2.1 described previously, assuming the client was configured to publish SHA-256 checksum files, would be:

PUT commons-lang-2.1.jar
PUT commons-lang-2.1.jar.sha256
PUT commons-lang-2.1.pom
PUT commons-lang-2.1.pom.sha256
PUT maven-metadata.xml
PUT maven-metadata.xml.sha256

When uploading the checksum file for an asset, such as a JAR file, the checksum upload request will fail with a 400 (Bad Request) response if there's a mismatch between the uploaded checksum value and the checksum value calculated by CodeArtifact. If the corresponding asset doesn't exist, the request will fail with a 404 (Not Found) response. To avoid this error, you must first upload the asset, and then upload the checksum.

When maven-metadata.xml is uploaded, CodeArtifact normally changes the status of the Maven package version from Unfinished to Published. If a checksum mismatch is detected for any asset, CodeArtifact will return a 400 (Bad Request) in response to the maven-metadata.xml publishing request. This error may cause the client to stop uploading files for that package version. If this occurs, and the maven-metadata.xml file is not uploaded, any assets of the package version already uploaded cannot be downloaded. This is because the package version’s status is not set to Published and remains Unfinished.

CodeArtifact allows adding further assets to a Maven package version even after maven-metadata.xml has been uploaded and the package version status has been set to Published. In this status, a request to upload a mismatched checksum file will also fail with a 400 (Bad Request) response. However, because the package version status has already been set to Published, you can download any asset from the package, including those for which the checksum file upload failed. When downloading a checksum for an asset where the checksum file upload failed, the checksum value that the client receives will be the checksum value calculated by CodeArtifact based on the uploaded asset data.

CodeArtifact checksum comparisons are case sensitive, and the checksums calculated by CodeArtifact are formatted in lowercase. Therefore, if the checksum 909FA780F76DA393E992A3D2D495F468 is uploaded, it will fail with a checksum mismatch because CodeArtifact does not treat it as equal to 909fa780f76da393e992a3d2d495f468.

Recovering from checksum mismatches

If a checksum upload fails as a result of a checksum mismatch, try one of the following to recover:

• Run the command that publishes the Maven artifact again. This might work if a network issue corrupted the checksum file. If this resolves the network issue, the checksum matches and the download is successful.

• Delete the package version and then republish it. For more information, see DeletePackageVersions in the AWS CodeArtifact API Reference.