Skip to content

Commit

Permalink
update readmes
Browse files Browse the repository at this point in the history
Signed-off-by: Appu Goundan <[email protected]>
  • Loading branch information
loosebazooka committed Aug 8, 2024
1 parent 9205a93 commit 95db097
Show file tree
Hide file tree
Showing 3 changed files with 42 additions and 26 deletions.
44 changes: 25 additions & 19 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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);

Expand All @@ -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("[email protected]")
.build())
.build();
VerificationOptions options = VerificationOptions.builder().addCertificateMatchers(
CertificateMatcher.fulcio()
.subjectAlternativeName(StringMatcher.string("[email protected]"))
.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!
Expand All @@ -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
Expand Down
15 changes: 10 additions & 5 deletions sigstore-gradle/README.md
Original file line number Diff line number Diff line change
@@ -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
Expand All @@ -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 `<filename>.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:
Expand All @@ -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
Expand Down
9 changes: 7 additions & 2 deletions sigstore-maven-plugin/README.md
Original file line number Diff line number Diff line change
@@ -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

Expand All @@ -27,6 +28,10 @@ A Maven plugin for signing artifacts with Sigstore
</plugin>
```

### Outputs

For each file to be published an associated `<filename>.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:
Expand Down

0 comments on commit 95db097

Please sign in to comment.