sigstore-java

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

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

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
}

Verifying DSSE Bundles

sigstore-java doesn't create DSSE bundles 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