From 95db0972e79bb7bd08802973fc13508d0576b080 Mon Sep 17 00:00:00 2001 From: Appu Goundan Date: Thu, 8 Aug 2024 10:54:43 -0400 Subject: [PATCH] update readmes Signed-off-by: Appu Goundan --- README.md | 44 +++++++++++++++++++-------------- sigstore-gradle/README.md | 15 +++++++---- sigstore-maven-plugin/README.md | 9 +++++-- 3 files changed, 42 insertions(+), 26 deletions(-) diff --git a/README.md b/README.md index 51cd6e32..e813b966 100644 --- a/README.md +++ b/README.md @@ -5,22 +5,28 @@ # sigstore-java A sigstore java client for interacting with sigstore infrastructure -⚠️ This project is not ready for general-purpose use! ⚠️ +## Requirements +* Java 11 (https://github.com/sigstore/sigstore-java requires Java 11) +This project requires a minimum of Java 11 -This project requires a minimum of Java 11 and is current in pre-release, -apis and dependencies are likely to change - -You can files issues directly on this project or if you have any questions -message us on the [sigstore#java](https://sigstore.slack.com/archives/C03239XUL92) slack channel +You can file [issues directly](https://github.com/sigstore/sigstore-java/issues) on this project or +if you have any questions message us on the [sigstore#java](https://sigstore.slack.com/archives/C03239XUL92) +slack channel ## Usage +### Build plugins + +For use directly with your java build. See [maven](https://github.com/sigstore/sigstore-java/tree/main/sigstore-maven-plugin) or [gradle](https://github.com/sigstore/sigstore-java/tree/main/sigstore-gradle) +build plugin specifics. + ### Keyless Signing And Verification #### Signing ```java 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); @@ -30,29 +36,29 @@ String bundleJson = result.toJson(); #### Verification -##### Read bundle +##### Get artifact and bundle ```java -Path bundleFile = // java.nio.Path to a .sigstore.json signature bundle file -Bundle bundle = Bundle.from(Files.newBufferedReader(bundleFile, StandardCharsets.UTF_8)); +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 ```java // add certificate policy to verify the identity of the signer -VerificationOptions verificationOptions = - VerificationOptions.builder() - .addCertificateIdentities( - CertificateIdentity.builder() - .issuer("https://accounts.example.com")) - .subjectAlternativeName("test@example.com") - .build()) - .build(); +VerificationOptions options = VerificationOptions.builder().addCertificateMatchers( + CertificateMatcher.fulcio() + .subjectAlternativeName(StringMatcher.string("test@example.com")) + .issuer(StringMatcher.string("https://accounts.example.com")) + .build()); ``` ##### Do verification ```java -Path artifact = // java.nio.Path to artifact file try { + // verify using the sigstore public instance var verifier = new KeylessVerifier.builder().sigstorePublicDefaults().build(); verifier.verify(artifact, bundle, verificationOptions); // verification passed! @@ -67,7 +73,7 @@ The public stable API is limited to `dev.sigstore.KeylessSigner`(https://javadoc You can browse Javadoc at https://javadoc.io/doc/dev.sigstore/sigstore-java. -To build javadoc from the sources, use the following command: +To build and view javadoc from the sources, use the following command: ```sh $ ./gradlew javadoc diff --git a/sigstore-gradle/README.md b/sigstore-gradle/README.md index a2eb5589..5248ee31 100644 --- a/sigstore-gradle/README.md +++ b/sigstore-gradle/README.md @@ -1,8 +1,9 @@ -## sigstore-gradle +[![Gradle Plugin Portal](https://img.shields.io/maven-metadata/v/https/plugins.gradle.org/m2/dev/sigstore/sigstore-gradle-sign-plugin/maven-metadata.xml.svg?color&label=gradle%20plugin%20portal)](https://plugins.gradle.org/plugin/dev.sigstore.sign/) + +# sigstore-gradle A Gradle plugin for signing artifacts with Sigstore. -`dev.sigstore.sign` is available on the gradle plugin portal. Signature format uses [Sigstore bundle](https://github.com/sigstore/protobuf-specs/blob/main/protos/sigstore_bundle.proto) JSON as the output format. ## Requirements @@ -18,11 +19,14 @@ plugins { id("dev.sigstore.sign") } -// It would automatically sign all Maven publications -// By default, it would use GitHub Actions OIDC when available, -// and it would resort to Web Browser OIDC otherwise. +// Automatically sign all Maven publications, using GitHub Actions OIDC when available, +// and browser based OIDC otherwise. ``` +### Outputs + +For each file to be published an associated `.sigstore.json` signature file will be generated + ### GitHub Actions OIDC support In order for the required environment variables to be available, the workflow requires the following permissions: @@ -35,6 +39,7 @@ permissions: See [GitHub documentation](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/configuring-openid-connect-in-cloud-providers#adding-permissions-settings) for details. + ## Full configuration ```kotlin diff --git a/sigstore-maven-plugin/README.md b/sigstore-maven-plugin/README.md index ae69b3bf..61b23308 100644 --- a/sigstore-maven-plugin/README.md +++ b/sigstore-maven-plugin/README.md @@ -1,9 +1,10 @@ -# sigstore-maven-plugin +[![Maven Central](https://img.shields.io/maven-central/v/dev.sigstore/sigstore-maven-plugin.svg?color&label=maven%20central)](https://central.sonatype.com/artifact/dev.sigstore/sigstore-maven-plugin) -[![Maven Central](https://img.shields.io/maven-central/v/dev.sigstore/sigstore-maven-plugin.svg?label=Maven%20Central)](https://central.sonatype.com/artifact/dev.sigstore/sigstore-maven-plugin) +# sigstore-maven-plugin A Maven plugin for signing artifacts with Sigstore +Signature format uses [Sigstore bundle](https://github.com/sigstore/protobuf-specs/blob/main/protos/sigstore_bundle.proto) JSON as the output format. ## Requirements @@ -27,6 +28,10 @@ A Maven plugin for signing artifacts with Sigstore ``` +### Outputs + +For each file to be published an associated `.sigstore.json` signature file will be generated + ### GitHub Actions OIDC support In order for the required environment variables to be available, the workflow requires the following permissions: