skip to content

How do you bootstrap PGP verification entries, and what does `--write-verification-metadata pgp,sha256` do?

level: middleimportance: must knowfreq 50%

answer

  1. --write-verification-metadata pgp,sha256
  2. order = priority, pgp first
  3. --export-keys -> local keyring
  4. review the diff / fingerprints
  5. re-run on dependency changes

basics

~10 s

Run gradle --write-verification-metadata pgp,sha256 <task>. Gradle resolves dependencies, downloads each .asc, fetches keys, and writes <trusted-keys> plus <sha256> fallbacks into verification-metadata.xml so you don't hand-author every entry.

solid answer

~50 s

You don't hand-write trusted keys — you bootstrap them. Run, e.g., `./gradlew --write-verification-metadata pgp,sha256 build` (often with `--export-keys` and `--dry-run`). Gradle resolves all configurations the task touches, downloads each artifact's `.asc`, fetches the signing public keys, validates the signatures, and **writes** entries into `gradle/verification-metadata.xml`: a `<trusted-key>` for each verified key plus `<sha256>` entries as a fallback for artifacts lacking signatures. Listing `pgp` *before* `sha256` matters — it tells Gradle to prefer signature verification and only record a checksum where no usable signature exists, keeping the file lean. After generation you should **review the diff**: confirm the recorded fingerprints are genuinely the keys you trust (cross-check against publishers), because the bootstrap trusts whatever it finds. With `--export-keys`, the public keys are exported to a local keyring so verification doesn't depend on reaching a key server at build time.

code

bash · 4 lines
bash
# Bootstrap PGP + checksum fallback and export keys to a local keyring
./gradlew --write-verification-metadata pgp,sha256 --export-keys help

# Then: git diff gradle/verification-metadata.xml  -> audit the fingerprints

go deeper

for a junior

Know the command exists and that it auto-generates the trusted-keys/checksum entries rather than hand-writing them.

for a middle

Explain the mechanism-order semantics, --export-keys, and that the output must be reviewed before committing.

for a senior

Cover keyring vs key-server tradeoffs, re-running on dependency changes, and scoping trusted keys to groups.

for a principal

Define org policy: who audits new fingerprints in PR review, committed keyring vs key servers, and CI enforcement of verification.

## Why bootstrapping exists A real project has hundreds of transitive artifacts. Hand-authoring a `<trusted-key>` and checksum for each is infeasible, so Gradle generates the metadata for you with the **`--write-verification-metadata`** command-line flag. You pass it a comma-separated list of the verification mechanisms you want recorded. ## The command ```bash ./gradlew --write-verification-metadata pgp,sha256 \ --export-keys \ help ``` What each part does: - **`pgp,sha256`** — the mechanisms, *in priority order*. `pgp` first means: prefer signature verification; record a `sha256` only for artifacts that have no usable signature. Reversing them (`sha256,pgp`) would record checksums everywhere and bloat the file. You can also write just `sha256` (checksums only) or `pgp` (no checksum fallback — risky). - **`--export-keys`** — exports the encountered public keys into a local keyring (`gradle/verification-keyring.keys` text format and/or `.gpg` binary). This makes verification self-contained: builds no longer need to contact a key server. - The trailing **task** (e.g. `help`, `build`) determines which configurations get resolved; pick one that touches everything you want covered. Adding `--dry-run` lets some tasks resolve without executing. ## What Gradle writes Into `gradle/verification-metadata.xml`: ```xml <verification-metadata> <configuration> <verify-metadata>true</verify-metadata> <verify-signatures>true</verify-signatures> <key-servers> <key-server uri="https://keyserver.ubuntu.com"/> </key-servers> </configuration> <trusted-keys> <trusted-key id="3A5C...full-fingerprint" group="com.fasterxml.jackson.core"/> </trusted-keys> <components> <component group="org.unsigned" name="lib" version="1.2"> <artifact name="lib-1.2.jar"> <sha256 value="..."/> </artifact> </component> </components> </verification-metadata> ``` Note the `<trusted-keys>` block (one entry per key, scoped to the group/module that uses it) and `<sha256>` fallbacks only where no signature applied. ## Key servers vs keyrings During generation and verification Gradle obtains public keys from configured **`<key-servers>`** (default includes `keyserver.ubuntu.com`) or from a committed **local keyring**. Key servers can be slow or unreachable, leaking network dependence into builds and making them non-reproducible; committing an exported keyring (via `--export-keys`) is the hardened choice. You can disable key servers entirely with `<key-servers enabled="false"/>` once you rely on the keyring. ## The mandatory review step Bootstrapping **trusts whatever it downloads** — it is a convenience, not a security oracle. After running it, diff `verification-metadata.xml` in version control and sanity-check the recorded fingerprints against the publishers you expect. Committing a fingerprint you never validated just bakes in an attacker's key. Treat the generated file as a starting point you audit, then commit. ## Updating later When you add or bump a dependency, re-run the same command; Gradle appends new keys/checksums. Because the file is committed, the diff shows exactly which new keys entered your trust set — review each.

  • Why does the order in `pgp,sha256` matter?
    Order is priority. `pgp` first tells Gradle to prefer signatures and only fall back to a sha256 when no usable signature exists, keeping the file minimal. Reversing it records checksums for everything.
  • Why is reviewing the generated file non-negotiable?
    The bootstrap trusts whatever keys it downloads. Without a manual cross-check of fingerprints you could commit an attacker-controlled key into your trust set, defeating the purpose.
  • What does `--export-keys` buy you?
    It writes the public keys into a local keyring committed to the repo, so verification no longer depends on reaching a key server at build time — faster and more reproducible.

saying these in an interview costs you the question

  • Treating the generated metadata as automatically secure without auditing fingerprints.
  • Writing `sha256,pgp` and wondering why every artifact got a checksum entry.
  • Believing you must hand-author each <trusted-key> manually.

context

resolving links…