From 5e694d518eed7138ed737fb44c9d19b95d99760d Mon Sep 17 00:00:00 2001
From: Hayley Denbraver <cook.hayley@gmail.com>
Date: Mon, 18 Nov 2024 18:43:17 -0800
Subject: [PATCH] Java client information. (#346)

* Java client information.

Signed-off-by: hayleycd <cook.hayley@gmail.com>

* Fixing linter issue.

Signed-off-by: hayleycd <cook.hayley@gmail.com>

* Adding version info

Signed-off-by: hayleycd <cook.hayley@gmail.com>

* Addressing linter comment

Signed-off-by: hayleycd <cook.hayley@gmail.com>

* Addressing linter comment

Signed-off-by: hayleycd <cook.hayley@gmail.com>

---------

Signed-off-by: hayleycd <cook.hayley@gmail.com>
---
 content/en/language_clients/java.md           | 107 ++++++++++++++++++
 .../language_client_overview.md               |   3 +-
 2 files changed, 109 insertions(+), 1 deletion(-)
 create mode 100644 content/en/language_clients/java.md

diff --git a/content/en/language_clients/java.md b/content/en/language_clients/java.md
new file mode 100644
index 00000000..643f389f
--- /dev/null
+++ b/content/en/language_clients/java.md
@@ -0,0 +1,107 @@
+---
+type: docs
+category: Language Clients
+title: Java
+weight: 20
+---
+
+[`sigstore-java`](https://github.com/sigstore/sigstore-java#sigstore-java) is a java client for interacting with the Sigstore infrastructure.
+
+## 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)
+
+## 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.
+
+### Maven
+
+Requires Java 11
+
+```java
+      <plugin>
+        <groupId>dev.sigstore</groupId>
+        <artifactId>sigstore-maven-plugin</artifactId>
+        <version>1.0.0</version>
+        <executions>
+          <execution>
+            <id>sign</id>
+            <goals>
+              <goal>sign</goal>
+            </goals>
+          </execution>
+        </executions>
+      </plugin>
+```
+
+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).
+
+### Gradle
+
+Requires Java 11 and Gradle 7.5.
+
+```java
+plugins {
+    id("dev.sigstore.sign") version "1.0.0"
+}
+```
+
+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 Examples
+
+### 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);
+
+// sigstore bundle format (serialized as <artifact>.sigstore.json)
+String bundleJson = result.toJson();
+```
+
+### Verifying
+
+#### Get artifact and bundle
+
+```java
+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 options = VerificationOptions.builder().addCertificateMatchers(
+  CertificateMatcher.fulcio()
+    .subjectAlternativeName(StringMatcher.string("test@example.com"))
+    .issuer(StringMatcher.string("https://accounts.example.com"))
+    .build());
+```
+
+#### Do verification
+
+```java
+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
+}
+```
+
+### Additional examples
+
+[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.
diff --git a/content/en/language_clients/language_client_overview.md b/content/en/language_clients/language_client_overview.md
index d6b88b92..fae0c786 100644
--- a/content/en/language_clients/language_client_overview.md
+++ b/content/en/language_clients/language_client_overview.md
@@ -12,8 +12,9 @@ Language client summaries are available in the main Sigstore documentation, but
 | Language Client Summary                  | Project Repository                                             |
 | ---------------------------------------- | -------------------------------------------------------------- |
 | [Go](../go)                              | [sigstore-go](https://github.com/sigstore/sigstore-go)         |
-| Java (available soon)                    | [sigstore-java](https://github.com/sigstore/sigstore-java)     |
+| [Java](../java)                          | [sigstore-java](https://github.com/sigstore/sigstore-java)     |
 | [Javascript](../javascript)              | [sigstore-js](https://github.com/sigstore/sigstore-js)         |
 | [Python](../python)                      | [sigstore-python](https://github.com/sigstore/sigstore-python) |
 | Ruby (available soon)                    | [sigstore-ruby](https://github.com/sigstore/sigstore-ruby)     |
 | [Rust](../rust)                          | [sigstore-rs](https://github.com/sigstore/sigstore-rs)         |
+