A sigstore java client for interacting with sigstore infrastructure

You can file issues directly on this project or if you have any questions message us on the sigstore#java slack channel

Minimum Requirements

• Java 11

Usage

Build plugins

For use directly with your java build. See maven or gradle build plugin specifics.

Keyless Signing And Verification

Artifact Signing

Path testArtifact = Paths.get("path/to/my/file.jar")

// sign using the sigstore public instance
var signer = KeylessSigner.builder().sigstorePublicDefaults().build();
Bundle result = signer.signFile(testArtifact);

// sigstore bundle format (serialized as <artifact>.sigstore.json)
String bundleJson = result.toJson();

Artifact Verification

Get artifact and bundle

Path artifact = Paths.get("path/to/my-artifact");

// import a json formatted sigstore bundle
Path bundleFile = Paths.get("path/to/my-artifact.sigstore.json");
Bundle bundle = Bundle.from(bundleFile, StandardCharsets.UTF_8);

Configure verification options

// 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());

Do verification

try {
  // verify using the sigstore public instance
  var verifier = new KeylessVerifier.builder().sigstorePublicDefaults().build();
  verifier.verify(artifact, bundle, verificationOptions);
  // verification passed!
} catch (KeylessVerificationException e) {
  // verification failed
}

Attesting DSSE Payloads (only for testing on staging)

String payload = "<some https://in-toto.io/Statement/v1 statement>"

// sign using the Sigstore stating instance with rekor v2 explicitly enabled
var signer = KeylessSigner.builder().sigstoreStagingDefaults().enableRekorV2(true).build();
var result = signer.attest(payload);

// sigstore bundle format (serialized as <attestation>.sigstore.json)
String bundleJson = result.toJson();

Verifying DSSE Bundles

sigstore-java doesn't create DSSE bundles on the public good infrastructure yet, but it can verify the signatures over them with the same KeylessVerifier workflow detailed above. While sigstore-java inspects the embedded payload to ensure the provided artifact is a subject in the in-toto statement it is not able to make any further assertions about the payload. Consumers of DSSE bundles should inspect the embedded payload to verify extended attestation data using tools like slsa-verifier.

Exploring the API

The public stable API is limited to dev.sigstore.KeylessSigner and dev.sigstore.KeylessVerifier and the classes exposed by those APIs. Other classes in the library are subject to change without notice.

You can browse Javadoc at https://javadoc.io/doc/dev.sigstore/sigstore-java.

To build and view javadoc from the sources, use the following command:

$ ./gradlew javadoc
$ "my-favorite-browser" ./sigstore-java/build/docs/javadoc/index.html

Distribution

Sigstore Java and Sigstore Maven Plugin are signed with both PGP and sigstore.

PGP

Sigstore

Troubleshooting

To ensure maximum compatibility with the public Sigstore infrastructure, ensure you are using the latest release of sigstore-java.

Common issues

1. Cannot verify bundles with timestamp verification material
   

   means an upgrade is necessary to verify this signature bundle as Rekor v2 log entries require external timestamps and can only be verified by sigstore-java 2.0.0 or higher.

2. Cannot verify DSSE signature based bundles
   

   DSSE validation was introduced in sigstore-java 1.3.0, so older versions may throw this error.

3. Returned log entry was inconsistent with request
   

   While this can be a legitimate error stemming from misconfigured infrastructure, it can also happen due to irregularities in handling line endings (\r\n) on Windows for sigstore-java 1.x.x. Upgrading to 2.0.0 or higher should solve this problem.
4. Offline verification is unsupported. By default, sigstore-java checks for updates of the trusted key material when verifying and you may encounter errors like:

   TUF repo failed to update
   

   While this is not recommended when using public sigstore infrastructure, you can configure the KeylessVerifier to run in "offline" mode by programmatically configuring a SigstoreTrustedRoot (cached or custom) to bypass querying the TUF repository.
5. Offline signing is unsupported and there are no workarounds.

My problem is something else

Please open an issue or ask in the #java slack channel.