From 5a8839bd7602c660eba1c89f4326d6d7f5274580 Mon Sep 17 00:00:00 2001 From: Patrick Smyth Date: Thu, 23 Apr 2026 16:31:28 -0400 Subject: [PATCH 1/2] Refresh Java language client docs for sigstore-java 2.0.0 Generated via mill crank doc_refresh. Changes: - Bump Maven/Gradle plugin versions 1.0.0 -> 2.0.0 - Add Requirements section (Java 11+, Gradle 7.5+) - Add DSSE attestation section with Rekor V2 example - Add TUF integration and GitHub Actions OIDC to features - Add 'Signing individual files' subsection with sign-base plugin - Add stable-API note (only KeylessSigner / KeylessVerifier guaranteed) - Add Known Limitations section - Fix compile errors in API Usage examples (missing .build(), incorrect 'new' keyword on builder, missing semicolons) - Complete imports in all Java snippets - Switch Maven code fence from java to xml - Introduce OIDC/DSSE/TUF/Rekor with definitions and links on first mention; trim marketing fluff Signed-off-by: Patrick Smyth --- content/en/language_clients/java.md | 142 +++++++++++++++++++--------- 1 file changed, 97 insertions(+), 45 deletions(-) diff --git a/content/en/language_clients/java.md b/content/en/language_clients/java.md index 79d3f44a..0d70b8a4 100644 --- a/content/en/language_clients/java.md +++ b/content/en/language_clients/java.md @@ -5,65 +5,89 @@ title: Java weight: 20 --- -[`sigstore-java`](https://github.com/sigstore/sigstore-java#sigstore-java) is a java client for interacting with the Sigstore infrastructure. +[`sigstore-java`](https://github.com/sigstore/sigstore-java) is a Java client for signing and verifying artifacts with Sigstore. It supports keyless signing — signing without managing long-lived private keys, using short-lived certificates tied to an [OIDC](https://openid.net/developers/how-connect-works/) (OpenID Connect) identity — via build plugins for Maven and Gradle, and a direct Java API. ## Features -- [Maven](https://github.com/sigstore/sigstore-java/tree/main/sigstore-maven-plugin) and [Gradle](https://github.com/sigstore/sigstore-java/tree/main/sigstore-gradle) signing plugins -- Keyless signing and verifying -- Java native signing and verifying [API](https://javadoc.io/doc/dev.sigstore/sigstore-java) +* [Maven](https://github.com/sigstore/sigstore-java/tree/main/sigstore-maven-plugin) and [Gradle](https://github.com/sigstore/sigstore-java/tree/main/sigstore-gradle) signing plugins +* Keyless signing and verification +* Java API ([Javadoc](https://javadoc.io/doc/dev.sigstore/sigstore-java)) +* [DSSE](https://github.com/secure-systems-lab/dsse) (Dead Simple Signing Envelope) attestation signing and verification +* [TUF](https://theupdateframework.io) (The Update Framework) integration for trusted root management +* GitHub Actions OIDC support for CI/CD pipelines + +## Requirements + +* Java 11 or higher +* Gradle 7.5 or higher (for the Gradle plugin) ## Installation -Release information for the Java client is available [here](https://github.com/sigstore/sigstore-java/releases). We recommend using the latest version for your install. +Release information is available on the [releases page](https://github.com/sigstore/sigstore-java/releases). Use the latest version for your install. ### Maven -Requires Java 11 - -```java - - dev.sigstore - sigstore-maven-plugin - 1.0.0 - - - sign - - sign - - - - +```xml + + dev.sigstore + sigstore-maven-plugin + 2.0.0 + + + sign + + sign + + + + ``` -More information on the Maven build plugin is available in the [project repository](https://github.com/sigstore/sigstore-java/tree/main/sigstore-maven-plugin#sigstore-maven-plugin). +More information on the Maven plugin is available in the [project repository](https://github.com/sigstore/sigstore-java/tree/main/sigstore-maven-plugin#sigstore-maven-plugin). ### Gradle -Requires Java 11 and Gradle 7.5. +```kotlin +plugins { + id("dev.sigstore.sign") version "2.0.0" +} +``` -```java +This automatically signs all Maven publications. More information is available in the [project repository](https://github.com/sigstore/sigstore-java/tree/main/sigstore-gradle#sigstore-gradle). + +#### Signing individual files + +Use the `sign-base` plugin to sign individual files without tying into Maven publication: + +```kotlin plugins { - id("dev.sigstore.sign") version "1.0.0" + id("dev.sigstore.sign-base") +} + +val signHelloProps by tasks.registering(SigstoreSignFilesTask::class) { + signFile(/* File or Provider */) } ``` -More information on the Gradle build plugin is available in the [project repository](https://github.com/sigstore/sigstore-java/tree/main/sigstore-gradle#sigstore-gradle). +## API Usage -## API Usage Examples +The stable public API consists of [`KeylessSigner`](https://javadoc.io/doc/dev.sigstore/sigstore-java) and [`KeylessVerifier`](https://javadoc.io/doc/dev.sigstore/sigstore-java). Other library classes may change between releases without notice. ### Signing ```java -Path testArtifact = Paths.get("path/to/my/file.jar") +import dev.sigstore.KeylessSigner; +import dev.sigstore.bundle.Bundle; +import java.nio.file.Path; +import java.nio.file.Paths; + +Path artifact = Paths.get("path/to/my/file.jar"); -// sign using the Sigstore public instance var signer = KeylessSigner.builder().sigstorePublicDefaults().build(); -Bundle result = signer.signFile(testArtifact); +Bundle bundle = signer.signFile(artifact); -// Sigstore bundle format (serialized as .sigstore.json) -String bundleJson = result.toJson(); +// serialized as .sigstore.json +String bundleJson = bundle.toJson(); ``` ### Verifying @@ -71,9 +95,12 @@ String bundleJson = result.toJson(); #### Get artifact and bundle ```java -Path artifact = Paths.get("path/to/my-artifact"); +import dev.sigstore.bundle.Bundle; +import java.nio.charset.StandardCharsets; +import java.nio.file.Path; +import java.nio.file.Paths; -// import a json formatted Sigstore bundle +Path artifact = Paths.get("path/to/my-artifact"); Path bundleFile = Paths.get("path/to/my-artifact.sigstore.json"); Bundle bundle = Bundle.from(bundleFile, StandardCharsets.UTF_8); ``` @@ -81,27 +108,52 @@ Bundle bundle = Bundle.from(bundleFile, StandardCharsets.UTF_8); #### Configure verification options ```java -// add certificate policy to verify the identity of the signer -VerificationOptions options = VerificationOptions.builder().addCertificateMatchers( - CertificateMatcher.fulcio() - .subjectAlternativeName(StringMatcher.string("test@example.com")) - .issuer(StringMatcher.string("https://accounts.example.com")) - .build()); +import dev.sigstore.verification.VerificationOptions; +import dev.sigstore.strings.StringMatcher; + +VerificationOptions verificationOptions = VerificationOptions.builder() + .addCertificateMatchers( + VerificationOptions.CertificateMatcher.fulcio() + .subjectAlternativeName(StringMatcher.string("test@example.com")) + .issuer(StringMatcher.string("https://accounts.example.com")) + .build()) + .build(); ``` #### Do verification ```java +import dev.sigstore.KeylessVerifier; +import dev.sigstore.KeylessVerificationException; + try { - // verify using the Sigstore public instance - var verifier = new KeylessVerifier.builder().sigstorePublicDefaults().build(); + var verifier = KeylessVerifier.builder().sigstorePublicDefaults().build(); verifier.verify(artifact, bundle, verificationOptions); - // verification passed! + // verification passed } catch (KeylessVerificationException e) { // verification failed } ``` -### Additional examples +### DSSE Attestation Signing + +DSSE attestation signing requires [Rekor](https://docs.sigstore.dev/logging/overview/) V2, Sigstore's append-only transparency log. The following example uses the staging instance, which has Rekor V2 enabled: + +```java +import dev.sigstore.KeylessSigner; +import dev.sigstore.bundle.Bundle; + +String payload = ""; +var signer = KeylessSigner.builder().sigstoreStagingDefaults().enableRekorV2(true).build(); +Bundle bundle = signer.attest(payload); +String bundleJson = bundle.toJson(); +``` + +[Additional examples](https://github.com/sigstore/sigstore-java/tree/main/examples/hello-world#sigstore-examples) are available in the project repository. + +## Known Limitations + +* **Offline signing** is not supported. +* **Multi-module Maven builds**: each module that signs artifacts requires its own OIDC authentication step. +* **Long-running builds**: the OIDC token has a 10-minute validity window. Builds that take longer than 10 minutes may require re-authentication partway through. -[Additional](https://github.com/sigstore/sigstore-java/tree/main/examples/hello-world#sigstore-examples) [examples](https://github.com/sigstore/sigstore-java/tree/main/examples/pgp#pgp-test-keys-for-examples) are available in the project repository. From 0859810839da86a814790e654ae5987fd011a483 Mon Sep 17 00:00:00 2001 From: Patrick Smyth Date: Sat, 25 Apr 2026 09:31:13 -0400 Subject: [PATCH 2/2] Address review findings on Java client docs Independent review (codex agent against the live PR diff) caught real factual issues that the doc_refresh chain's accuracy stage missed. Cross-checked each finding against sigstore-java v2.0.0 source before applying. Blocker fixes: - Fix VerificationOptions import: dev.sigstore.verification.VerificationOptions -> dev.sigstore.VerificationOptions (the snippet would not compile as written; verified against sigstore-java/src/main/java/dev/sigstore/VerificationOptions.java) - Fix sign-base SigstoreSignFilesTask reference: use FQCN dev.sigstore.sign.tasks.SigstoreSignFilesTask::class so the Gradle snippet works without an import (verified against sigstore-gradle/sigstore-gradle-sign-base-plugin) - Soften stable API note to match upstream README: '... and the classes exposed by those APIs' (was overstated as only KeylessSigner / KeylessVerifier) Additions and clarifications: - Add GitHub Actions section with required OIDC permissions block (permissions: id-token: write, contents: read), matching the snippet in upstream Maven and Gradle READMEs - Add Gradle plugin version to the sign-base snippet - Expand the offline limitation to cover both signing and verification, noting that verification supports a custom trusted root for restricted environments Signed-off-by: Patrick Smyth --- content/en/language_clients/java.md | 22 +++++++++++++++++----- 1 file changed, 17 insertions(+), 5 deletions(-) diff --git a/content/en/language_clients/java.md b/content/en/language_clients/java.md index 0d70b8a4..bf1c25ef 100644 --- a/content/en/language_clients/java.md +++ b/content/en/language_clients/java.md @@ -61,17 +61,29 @@ Use the `sign-base` plugin to sign individual files without tying into Maven pub ```kotlin plugins { - id("dev.sigstore.sign-base") + id("dev.sigstore.sign-base") version "2.0.0" } -val signHelloProps by tasks.registering(SigstoreSignFilesTask::class) { +val signHelloProps by tasks.registering(dev.sigstore.sign.tasks.SigstoreSignFilesTask::class) { signFile(/* File or Provider */) } ``` +### GitHub Actions + +To use keyless signing in a GitHub Actions workflow, the workflow must request an OIDC token. Grant the necessary permissions on the job or workflow: + +```yaml +permissions: + id-token: write + contents: read +``` + +See [GitHub's documentation on OIDC permissions](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/configuring-openid-connect-in-cloud-providers#adding-permissions-settings) for details. + ## API Usage -The stable public API consists of [`KeylessSigner`](https://javadoc.io/doc/dev.sigstore/sigstore-java) and [`KeylessVerifier`](https://javadoc.io/doc/dev.sigstore/sigstore-java). Other library classes may change between releases without notice. +The stable public API consists of [`KeylessSigner`](https://javadoc.io/doc/dev.sigstore/sigstore-java) and [`KeylessVerifier`](https://javadoc.io/doc/dev.sigstore/sigstore-java) and the classes exposed by those APIs. Other library classes may change between releases without notice. ### Signing @@ -108,7 +120,7 @@ Bundle bundle = Bundle.from(bundleFile, StandardCharsets.UTF_8); #### Configure verification options ```java -import dev.sigstore.verification.VerificationOptions; +import dev.sigstore.VerificationOptions; import dev.sigstore.strings.StringMatcher; VerificationOptions verificationOptions = VerificationOptions.builder() @@ -153,7 +165,7 @@ String bundleJson = bundle.toJson(); ## Known Limitations -* **Offline signing** is not supported. +* **Offline signing and verification** are not supported by default — the client expects to reach Sigstore infrastructure (Fulcio, Rekor, the TUF root mirror). Verification can be configured against a custom trusted root for restricted environments. * **Multi-module Maven builds**: each module that signs artifacts requires its own OIDC authentication step. * **Long-running builds**: the OIDC token has a 10-minute validity window. Builds that take longer than 10 minutes may require re-authentication partway through.