Add timestamp client and verifier

Signed-off-by: Aaron Lew <64337293+aaronlew02@users.noreply.github.com>

Author: aaronlew02

.gitignore

@@ -31,3 +31,6 @@
 # except this icon
 !/.idea/icon.png
 
+# vscode java output directories
+/bin/=
+/**/bin

sigstore-java/src/main/java/dev/sigstore/TrustedRootProvider.java

@@ -24,6 +24,7 @@
 import java.nio.file.Path;
 import java.security.InvalidKeyException;
 import java.security.NoSuchAlgorithmException;
+import java.security.cert.CertificateException;
 import java.security.spec.InvalidKeySpecException;
 
 @FunctionalInterface
@@ -41,7 +42,8 @@ static TrustedRootProvider from(SigstoreTufClient.Builder tufClientBuilder) {
       } catch (IOException
           | NoSuchAlgorithmException
           | InvalidKeySpecException
-          | InvalidKeyException ex) {
+          | InvalidKeyException
+          | CertificateException ex) {
         throw new SigstoreConfigurationException(ex);
       }
     };
@@ -52,7 +54,7 @@ static TrustedRootProvider from(Path trustedRoot) {
     return () -> {
       try (var is = Files.newInputStream(trustedRoot)) {
         return SigstoreTrustedRoot.from(is);
-      } catch (IOException ex) {
+      } catch (IOException | CertificateException ex) {
         throw new SigstoreConfigurationException(ex);
       }
     };

sigstore-java/src/main/java/dev/sigstore/encryption/certificates/Certificates.java

@@ -21,7 +21,11 @@
 import java.io.StringReader;
 import java.io.StringWriter;
 import java.nio.charset.StandardCharsets;
-import java.security.cert.*;
+import java.security.cert.CertPath;
+import java.security.cert.Certificate;
+import java.security.cert.CertificateException;
+import java.security.cert.CertificateFactory;
+import java.security.cert.X509Certificate;
 import java.time.temporal.ChronoUnit;
 import java.util.ArrayList;
 import java.util.Collections;
@@ -142,6 +146,12 @@ public static CertPath toCertPath(Certificate certificate) throws CertificateExc
     return cf.generateCertPath(Collections.singletonList(certificate));
   }
 
+  /** Converts a list of X509Certificates to a {@link CertPath}. */
+  public static CertPath toCertPath(List<Certificate> certificate) throws CertificateException {
+    CertificateFactory cf = CertificateFactory.getInstance("X.509");
+    return cf.generateCertPath(certificate);
+  }
+
   /** Appends an CertPath to another {@link CertPath} as children. */
   public static CertPath append(CertPath parent, CertPath child) throws CertificateException {
     CertificateFactory cf = CertificateFactory.getInstance("X.509");

sigstore-java/src/main/java/dev/sigstore/timestamp/client/HashAlgorithm.java

@@ -0,0 +1,42 @@
+/*
+ * Copyright 2025 The Sigstore Authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package dev.sigstore.timestamp.client;
+
+import org.bouncycastle.asn1.ASN1ObjectIdentifier;
+import org.bouncycastle.tsp.TSPAlgorithms;
+
+/** Supported hash algorithms for timestamp requests. */
+public enum HashAlgorithm {
+  SHA256("SHA256", TSPAlgorithms.SHA256),
+  SHA384("SHA384", TSPAlgorithms.SHA384),
+  SHA512("SHA512", TSPAlgorithms.SHA512);
+
+  private final String algorithmName;
+  private final ASN1ObjectIdentifier oid;
+
+  HashAlgorithm(String algorithmName, ASN1ObjectIdentifier oid) {
+    this.algorithmName = algorithmName;
+    this.oid = oid;
+  }
+
+  public String getAlgorithmName() {
+    return algorithmName;
+  }
+
+  public ASN1ObjectIdentifier getOid() {
+    return oid;
+  }
+}

sigstore-java/src/main/java/dev/sigstore/timestamp/client/TimestampClient.java

@@ -0,0 +1,27 @@
+/*
+ * Copyright 2025 The Sigstore Authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package dev.sigstore.timestamp.client;
+
+/** A client to communicate with a timestamp service instance. */
+public interface TimestampClient {
+  /**
+   * Request a timestanp for a timestamp authority.
+   *
+   * @param tsReq a structured request for a timestamp
+   * @return a {@link TimestampResponse} from the timestamp authority
+   */
+  TimestampResponse timestamp(TimestampRequest tsReq) throws TimestampException;
+}

sigstore-java/src/main/java/dev/sigstore/timestamp/client/TimestampClientHttp.java

@@ -0,0 +1,144 @@
+/*
+ * Copyright 2025 The Sigstore Authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package dev.sigstore.timestamp.client;
+
+import com.google.api.client.http.ByteArrayContent;
+import com.google.api.client.http.GenericUrl;
+import com.google.api.client.http.HttpRequestFactory;
+import com.google.api.client.http.HttpResponse;
+import com.google.common.annotations.VisibleForTesting;
+import dev.sigstore.http.HttpClients;
+import dev.sigstore.http.HttpParams;
+import dev.sigstore.http.ImmutableHttpParams;
+import java.io.IOException;
+import java.net.URI;
+import java.util.Locale;
+import java.util.Objects;
+import org.bouncycastle.tsp.TSPException;
+import org.bouncycastle.tsp.TimeStampRequest;
+import org.bouncycastle.tsp.TimeStampRequestGenerator;
+import org.bouncycastle.tsp.TimeStampResponse;
+
+/** A client to communicate with a timestamp service instance. */
+public class TimestampClientHttp implements TimestampClient {
+  private static final URI SIGSTORE_TSA_URI =
+      URI.create("https://timestamp.sigstage.dev/api/v1/timestamp");
+  private static final String CONTENT_TYPE_TIMESTAMP_QUERY = "application/timestamp-query";
+  private static final String ACCEPT_TYPE_TIMESTAMP_REPLY = "application/timestamp-reply";
+
+  private final HttpRequestFactory requestFactory;
+  private final URI uri;
+
+  public static TimestampClientHttp.Builder builder() {
+    return new TimestampClientHttp.Builder();
+  }
+
+  @VisibleForTesting
+  TimestampClientHttp(HttpRequestFactory requestFactory, URI uri) {
+    this.requestFactory = requestFactory;
+    this.uri = uri;
+  }
+
+  public static class Builder {
+    private HttpParams httpParams = ImmutableHttpParams.builder().build();
+    private URI uri = SIGSTORE_TSA_URI;
+
+    private Builder() {}
+
+    /** Configure the http properties, see {@link HttpParams}, {@link ImmutableHttpParams}. */
+    public Builder setHttpParams(HttpParams httpParams) {
+      this.httpParams = httpParams;
+      return this;
+    }
+
+    /** Base url of the timestamp authority. */
+    public Builder setUri(URI uri) {
+      this.uri = uri;
+      return this;
+    }
+
+    public TimestampClientHttp build() throws IOException {
+      var requestFactory = HttpClients.newRequestFactory(httpParams);
+      return new TimestampClientHttp(requestFactory, uri);
+    }
+  }
+
+  @Override
+  public TimestampResponse timestamp(TimestampRequest tsReq) throws TimestampException {
+    TimeStampRequestGenerator bcTsReqGen = new TimeStampRequestGenerator();
+
+    // Prepare and send the timestamp request
+    var bcAlgorithmOid = tsReq.getHashAlgorithm().getOid();
+    var artifactHashBytes = tsReq.getHash();
+    var nonce = tsReq.getNonce();
+    bcTsReqGen.setCertReq(tsReq.requestCertificates());
+    TimeStampRequest bcTsReq;
+    HttpResponse httpTsResp;
+    try {
+      bcTsReq = bcTsReqGen.generate(bcAlgorithmOid, artifactHashBytes, nonce);
+      var requestBytes = bcTsReq.getEncoded();
+      httpTsResp = sendTimestampRequest(uri, requestBytes);
+    } catch (IOException e) {
+      throw new TimestampException("Timestamp request failed: " + e.getMessage(), e);
+    }
+
+    // Parse the timestamp response
+    TimestampResponse tsResp;
+    try {
+      var bcTsResp = getBcTimestampResponse(httpTsResp, bcTsReq);
+      var tsRespBytes = bcTsResp.getEncoded();
+      tsResp = ImmutableTimestampResponse.builder().encoded(tsRespBytes).build();
+    } catch (IOException | TSPException e) {
+      throw new TimestampException(
+          "Timestamp response validation or parsing failed: " + e.getMessage(), e);
+    }
+
+    return tsResp;
+  }
+
+  HttpResponse sendTimestampRequest(URI tsaUri, byte[] requestBytes) throws IOException {
+    Objects.requireNonNull(tsaUri, "tsaUri cannot be null");
+    Objects.requireNonNull(requestBytes, "requestBytes cannot be null");
+    var httpReq =
+        requestFactory.buildPostRequest(
+            new GenericUrl(tsaUri),
+            new ByteArrayContent(CONTENT_TYPE_TIMESTAMP_QUERY, requestBytes));
+    httpReq.getHeaders().setAccept(ACCEPT_TYPE_TIMESTAMP_REPLY);
+    httpReq.setThrowExceptionOnExecuteError(false);
+    // Skip exception thrown by API to manually handle error code below
+    httpReq.setNumberOfRetries(5);
+    var httpResp = httpReq.execute();
+    if (!(httpResp.getStatusCode() >= 200 && httpResp.getStatusCode() < 300)) {
+      throw new IOException(
+          String.format(
+              Locale.ROOT,
+              "bad response from timestamp @ '%s' : %s",
+              tsaUri,
+              httpResp.parseAsString()));
+    }
+    return httpResp;
+  }
+
+  private TimeStampResponse getBcTimestampResponse(
+      HttpResponse httpTsResp, TimeStampRequest bcTsReq) throws IOException, TSPException {
+    Objects.requireNonNull(httpTsResp, "HttpResponse cannot be null");
+    Objects.requireNonNull(bcTsReq, "TimeStampRequest cannot be null");
+
+    var bcTsResp = new TimeStampResponse(httpTsResp.getContent());
+    bcTsResp.validate(bcTsReq);
+    return bcTsResp;
+  }
+}

sigstore-java/src/main/java/dev/sigstore/timestamp/client/TimestampException.java

@@ -0,0 +1,30 @@
+/*
+ * Copyright 2025 The Sigstore Authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package dev.sigstore.timestamp.client;
+
+public class TimestampException extends Exception {
+  public TimestampException(String message) {
+    super(message);
+  }
+
+  public TimestampException(String message, Throwable cause) {
+    super(message, cause);
+  }
+
+  public TimestampException(Throwable cause) {
+    super(cause);
+  }
+}

sigstore-java/src/main/java/dev/sigstore/timestamp/client/TimestampRequest.java

@@ -0,0 +1,45 @@
+/*
+ * Copyright 2025 The Sigstore Authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package dev.sigstore.timestamp.client;
+
+import java.math.BigInteger;
+import java.security.SecureRandom;
+import org.immutables.value.Value;
+import org.immutables.value.Value.Immutable;
+
+@Immutable
+public interface TimestampRequest {
+  /** The hash algorithm used to hash the artifact. */
+  HashAlgorithm getHashAlgorithm();
+
+  /**
+   * The hash of the artifact to be timestamped. For sigstore-java, this typically refers to the
+   * hash of the signature (not the original artifact's hash) in a signing event.
+   */
+  byte[] getHash();
+
+  /** A nonce to prevent replay attacks. Defaults to a 64-bit random number. */
+  @Value.Default
+  default BigInteger getNonce() {
+    return new BigInteger(64, new SecureRandom());
+  }
+
+  /** Whether or not to include certificates in the response. Defaults to {@code false}. */
+  @Value.Default
+  default Boolean requestCertificates() {
+    return false;
+  }
+}

sigstore-java/src/main/java/dev/sigstore/timestamp/client/TimestampResponse.java

@@ -0,0 +1,24 @@
+/*
+ * Copyright 2025 The Sigstore Authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package dev.sigstore.timestamp.client;
+
+import org.immutables.value.Value.Immutable;
+
+@Immutable
+public interface TimestampResponse {
+  /** The ASN.1 encoded representation of the timestamp response. */
+  byte[] getEncoded();
+}