Verifying dependencies

Dependency verification is automatically enabled once the configuration file for dependency verification is discovered. This configuration file is located at $PROJECT_ROOT/gradle/verification-metadata.xml. This file minimally consists of the following:

Doing so, Gradle will verify all artifacts using checksums, but will not verify signatures. Gradle will verify any artifact downloaded using its dependency management engine, which includes, but is not limited to:

Gradle will not verify changing dependencies (in particular SNAPSHOT dependencies) nor locally produced artifacts (typically jars produced during the build itself) as by nature their checksums and signatures would always change.

With such a minimal configuration file, a project using any external dependency or plugin would immediately start failing because it doesn’t contain any checksum to verify.

A dependency verification configuration is global: a single file is used to configure verification of the whole build. In particular, the same file is used for both the (sub)projects and buildSrc.

If an included build is used:

An easy way to get started is therefore to generate the minimal configuration for an existing build.

By default, if dependency verification fails, Gradle will generate a small summary about the verification failure as well as an HTML report containing the full information about the failures. If your environment prevents you from reading this HTML report file (for example if you run a build on CI and that it’s not easy to fetch the remote artifacts), Gradle provides a way to opt-in a verbose console report. For this, you need to add this Gradle property to your gradle.properties file:

It’s worth mentioning that while Gradle can generate a dependency verification file for you, you should always check whatever Gradle generated for you because your build may already contain compromised dependencies without you knowing about it. Please refer to the appropriate checksum verification or signature verification section for more information.

If you plan on using signature verification, please also read the corresponding section of the docs.

Bootstrapping can either be used to create a file from the beginning, or also to update an existing file with new information. Therefore, it’s recommended to always use the same parameters once you started bootstrapping.

The dependency verification file can be generated with the following CLI instructions:

The write-verification-metadata flag requires the list of checksums that you want to generate or pgp for signatures.

Executing this command line will cause Gradle to:

As a consequence, the verification-metadata.xml file will be used in subsequent builds to verify dependencies.

The verification file generated by Gradle has a strict ordering for all its content. It also uses the information from the existing state to limit changes to the strict minimum.

This means that generation is actually a convenient tool for updating a verification file:

With the above benefits, it is really easy to account for new dependencies or dependency versions by simply generating the file again and reviewing the changes.

By default, bootstrapping is incremental, which means that if you run it multiple times, information is added to the file and in particular you can rely on your VCS to check the diffs. There are situations where you would just want to see what the generated verification metadata file would look like without actually changing the existing one or overwriting it.

For this purpose, you can just add --dry-run:

Then instead of generating the verification-metadata.xml file, a new file will be generated, called verification-metadata.dryrun.xml.

By default, Gradle will not only verify artifacts (jars, …​) but also the metadata associated with those artifacts (typically POM files). Verifying this ensures the maximum level of security: metadata files typically tell what transitive dependencies will be included, so a compromised metadata file may cause the introduction of undesired dependencies in the graph. However, because all artifacts are verified, such artifacts would in general easily be discovered by you, because they would cause a checksum verification failure (checksums would be missing from verification metadata). Because metadata verification can significantly increase the size of your configuration file, you may therefore want to disable verification of metadata. If you understand the risks of doing so, set the <verify-metadata> flag to false in the configuration file:

External components are identified by GAV coordinates, then each of the artifacts by their file names. To declare the checksums of an artifact, you need to add the corresponding section in the verification metadata file. For example, to declare the checksum for Apache PDFBox. The GAV coordinates are:

Using this dependency will trigger the download of 2 different files:

As a consequence, you need to declare the checksums for both of them (unless you disabled metadata verification):

In general, checksums are published alongside artifacts on public repositories. However, if a dependency is compromised in a repository, it’s likely its checksum will be too, so it’s a good practice to get the checksum from a different place, usually the website of the library itself.

In fact, it’s a good security practice to publish the checksums of artifacts on a different server than the server where the artifacts themselves are hosted: it’s harder to compromise a library both on the repository and the official website.

In the example above, the checksum was published on the website for the JAR, but not the POM file. This is why it’s usually easier to let Gradle generate the checksums and verify by reviewing the generated file carefully.

In this example, not only could we check that the checksum was correct, but we could also find it on the official website, which is why we changed the value of the of origin attribute on the sha512 element from Generated by Gradle to PDFBox Official site. Changing the origin gives users a sense of how trustworthy your build it.

Interestingly, using pdfbox will require much more than those 2 artifacts, because it will also bring in transitive dependencies. If the dependency verification file only included the checksums for the main artifacts you used, the build would fail with an error like this one:

What this indicates is that your build requires commons-logging when executing compileJava, however the verification file doesn’t contain enough information for Gradle to verify the integrity of the dependencies, meaning you need to add the required information to the verification metadata file.

See troubleshooting dependency verification for more insights on what to do in this situation.

If a dependency verification metadata file declares more than one checksum for a dependency, Gradle will verify all of them and fail if any of them fails. For example, the following configuration would check both the md5 and sha1 checksums:

There are multiple reasons why you’d like to do so:

Because verifying signatures is more expensive (both I/O and CPU wise) and harder to check manually, it’s not enabled by default.

Enabling it requires you to change the configuration option in the verification-metadata.xml file:

Signature verification has the advantage that it can make the configuration of dependency verification easier by not having to explicitly list all artifacts like for checksum verification only. In fact, it’s common that the same key can be used to sign several artifacts. If this is the case, you can move the trusted key from the artifact level to the global configuration block:

The configuration above means that for any artifact belonging to the group com.github.javaparser, we trust it if it’s signed with the 8756c4f765c9ac3cb6b85d62379ce192d401ab61 fingerprint.

The trusted-key element works similarly to the trusted-artifact element:

Gradle will automatically download the public keys required to verify a signature. For this it uses a list of well known and trusted key servers (the list may change between Gradle versions, please refer to the implementation to figure out what servers are used by default).

You can explicitly set the list of key servers that you want to use by adding them to the configuration:

Despite this, it’s possible that a key is not available:

In this case, you can ignore a key in the configuration block:

As soon as a key is ignored, it will not be used for verification, even if the signature file mentions it. However, if the signature cannot be verified with at least one other key, Gradle will mandate that you provide a checksum.

Gradle automatically downloads the required keys but this operation can be quite slow and requires everyone to download the keys. To avoid this, Gradle offers the ability to use a local keyring file containing the required public keys. Note that only public key packets and a single userId per key are stored and used. All other information (user attributes, signatures, etc.) is stripped from downloaded or exported keys.

Gradle supports 2 different file formats for keyrings: a binary format (.gpg file) and a plain text format (.keys), also known as ASCII-armored format.

There are pros and cons for each of the formats: the binary format is more compact and can be updated directly via GPG commands, but is completely opaque (binary). On the opposite, the ASCII-armored format is human-readable, can be easily updated by hand and makes it easier to do code reviews thanks to readable diffs.

You can configure which file type would be used by adding the keyring-format configuration option:

Available options for keyring format are armored and binary.

Without keyring-format, if the gradle/verification-keyring.gpg or gradle/verification-keyring.keys file is present, Gradle will search for keys there in priority. The plain text file will be ignored if there’s already a .gpg file (the binary version takes precedence).

You can ask Gradle to export all keys it used for verification of this build to the keyring during bootstrapping:

Unless keyring-format is specified, this command will generate both the binary version and the ASCII-armored file. Use this option to choose the preferred format. You should only pick one for your project.

It’s a good idea to commit this file to VCS (as long as you trust your VCS). If you use git and use the binary version, make sure to make it treat this file as binary, by adding this to your .gitattributes file:

You can also ask Gradle to export all trusted keys without updating the verification metadata file:

Similarly to bootstrapping for checksums, Gradle provides a convenience for bootstrapping a configuration file with signature verification enabled. For this, just add the pgp option to the list of verifications to generate. However, because there might be verification failures, missing keys or missing signature files, you must provide a fallback checksum verification algorithm:

this means that Gradle will verify the signatures and fallback to SHA-256 checksums when there’s a problem.

When bootstrapping, Gradle performs optimistic verification and therefore assumes a sane build environment. It will therefore:

If, for some reason, verification fails during the generation, Gradle will automatically generate an ignored key entry but warn you that you must absolutely check what happens.

This situation is common as explained for this section: a typical case is when the POM file for a dependency differs from one repository to the other (often in a non-meaningful way).

In addition, Gradle will try to group keys automatically and generate the trusted-keys block which reduced the configuration file size as much as possible.

The added key must be ASCII-armored formatted and can be simply added at the end of the file. If you already downloaded the key in the right format, you can simply append it to the file.

Or you can amend an existing KEYS file by issuing the following commands:

Once done, make sure to run the generation command again so that the key is processed by Gradle. This will do the following:

You can add keys to the binary version using GPG, for example issuing the following commands (syntax may depend on the tool you use):

The simplest failure you can have is when verification metadata is missing from the dependency verification file. This is the case for example if you use checksum verification, then you update a dependency and new versions of the dependency (and potentially its transitive dependencies) are brought in.

Gradle will tell you what metadata is missing:

Alternatively, you can ask Gradle to generate the missing information by using the bootstrapping mechanism: existing information in the metadata file will be preserved, Gradle will only add the missing verification metadata.

A more problematic issue is when the actual checksum verification fails:

This time, Gradle tells you what dependency is at fault, what was the expected checksum (the one you declared in the verification metadata file) and the one which was actually computed during verification.

Such a failure indicates that a dependency may have been compromised. At this stage, you must perform manual verification and check what happens. Several things can happen:

Note that a variation of a compromised library is often name squatting, when a hacker would use GAV coordinates which look legit but are actually different by one character, or repository shadowing, when a dependency with the official GAV coordinates is published in a malicious repository which comes first in your build.

If you have signature verification enabled, Gradle will perform verification of the signatures but will not trust them automatically:

In this case it means you need to check yourself if the key that was used for verification (and therefore the signature) can be trusted, in which case refer to this section of the documentation to figure out how to declare trusted keys.

If Gradle fails to verify a signature, you will need to take action and verify artifacts manually because this may indicate a compromised dependency.

If such a thing happens, Gradle will fail with:

There are several options:

The right approach here is to go to the official site of the dependency and see if they publish signatures for their artifacts. If they do, verify that the signature that Gradle downloaded matches the one published.

If you have checked that the dependency is not compromised and that it’s "only" the signature which is wrong, you should declare an artifact level key exclusion:

However, if you only do so, Gradle will still fail because all keys for this artifact will be ignored and you didn’t provide a checksum:

You will likely face a dependency verification failure (either checksum verification or signature verification) and will need to figure out if the dependency has been compromised or not.

In this section we give an example how you can manually check if a dependency was compromised.

For this we will take this example failure:

This error message gives us the GAV coordinates of the problematic dependency, as well as an indication of where the dependency was fetched from. Here, the dependency comes from MyCompany Mirror, which is a repository declared in our build.

The first thing to do is therefore to download the artifact and its signature manually from the mirror:

Then we can use the key information provided in the error message to import the key locally:

And perform verification:

What this tells us is that the problem is not on the local machine: the repository already contains a bad signature.

The next step is to do the same by downloading what is actually on Maven Central:

And we can now check the signature again:

This indicates that the dependency is valid on Maven Central. At this stage, we already know that the problem lives in the mirror, it may have been compromised, but we need to verify.

A good idea is to compare the 2 artifacts, which you can do with a tool like diffoscope.

We then figure out that the intent wasn’t malicious but that somehow a build has been overwritten with a newer version (the version in Central is newer than the one in our repository).

In this case, you can decide to:

It’s worth noting that if you choose to delete the version from your repository, you will also need to remove it from the local Gradle cache.

This is facilitated by the fact the error message tells you were the file is located:

You can safely delete the artifact file as Gradle would automatically re-download it: