[Java] Enhancements for HTTP message signature (#6090)

* Add code comments

* Change 'setup' method to setPrivateKey

* Add support for configuring digest algorithm

* run script in bin directory

* format generated code

* Revert "format generated code"

This reverts commit 3b52778.

Author: sebastien-rosset

modules/openapi-generator/src/main/resources/Java/libraries/jersey2-experimental/auth/HttpSignatureAuth.mustache

@@ -19,42 +19,110 @@ import java.util.List;
 
 import org.tomitribe.auth.signatures.*;
 
+/**
+ * A Configuration object for the HTTP message signature security scheme.
+ */
 public class HttpSignatureAuth implements Authentication {
 
   private Signer signer;
 
-  private String name;
+  // An opaque string that the server can use to look up the component they need to validate the signature.
+  private String keyId;
 
+  // The HTTP signature algorithm.
   private Algorithm algorithm;
 
+  // The list of HTTP headers that should be included in the HTTP signature.
   private List<String> headers;
 
-  public HttpSignatureAuth(String name, Algorithm algorithm, List<String> headers) {
-    this.name = name;
+  // The digest algorithm which is used to calculate a cryptographic digest of the HTTP request body.
+  private String digestAlgorithm;
+
+  /**
+   * Construct a new HTTP signature auth configuration object.
+   *
+   * @param keyId An opaque string that the server can use to look up the component they need to validate the signature.
+   * @param algorithm The signature algorithm.
+   * @param headers The list of HTTP headers that should be included in the HTTP signature.
+   */
+  public HttpSignatureAuth(String keyId, Algorithm algorithm, List<String> headers) {
+    this.keyId = keyId;
     this.algorithm = algorithm;
     this.headers = headers;
+    this.digestAlgorithm = "SHA-256";
   }
 
-  public String getName() {
-    return name;
+  /**
+   * Returns the opaque string that the server can use to look up the component they need to validate the signature.
+   *
+   * @return The keyId.
+   */
+  public String getKeyId() {
+    return keyId;
   }
 
-  public void setName(String name) {
-    this.name = name;
+  /**
+   * Set the HTTP signature key id.
+   *
+   * @param keyId An opaque string that the server can use to look up the component they need to validate the signature.
+   */
+  public void setKeyId(String keyId) {
+    this.keyId = keyId;
   }
 
+  /**
+   * Returns the HTTP signature algorithm which is used to sign HTTP requests.
+   */
   public Algorithm getAlgorithm() {
     return algorithm;
   }
 
+  /**
+   * Sets the HTTP signature algorithm which is used to sign HTTP requests.
+   *
+   * @param algorithm The HTTP signature algorithm.
+   */
   public void setAlgorithm(Algorithm algorithm) {
     this.algorithm = algorithm;
   }
 
+  /**
+   * Returns the digest algorithm which is used to calculate a cryptographic digest of the HTTP request body.
+   *
+   * @see java.security.MessageDigest
+   */
+  public String getDigestAlgorithm() {
+    return digestAlgorithm;
+  }
+
+  /**
+   * Sets the digest algorithm which is used to calculate a cryptographic digest of the HTTP request body.
+   *
+   * The exact list of supported digest algorithms depends on the installed security providers.
+   * Every implementation of the Java platform is required to support "MD5", "SHA-1" and "SHA-256".
+   * Do not use "MD5" and "SHA-1", they are vulnerable to multiple known attacks.
+   * By default, "SHA-256" is used.
+   *
+   * @param digestAlgorithm The digest algorithm.
+   *
+   * @see java.security.MessageDigest
+   */
+  public void setDigestAlgorithm(String digestAlgorithm) {
+    this.digestAlgorithm = digestAlgorithm;
+  }
+
+  /**
+   * Returns the list of HTTP headers that should be included in the HTTP signature.
+   */
   public List<String> getHeaders() {
     return headers;
   }
 
+  /**
+   * Sets the list of HTTP headers that should be included in the HTTP signature.
+   *
+   * @param headers The HTTP headers.
+   */
   public void setHeaders(List<String> headers) {
     this.headers = headers;
   }
@@ -67,12 +135,17 @@ public class HttpSignatureAuth implements Authentication {
     this.signer = signer;
   }
 
-  public void setup(Key key) throws ApiException {
+  /**
+   * Set the private key used to sign HTTP requests using the HTTP signature scheme.
+   *
+   * @param key The private key.
+   */
+  public void setPrivateKey(Key key) throws ApiException {
     if (key == null) {
-      throw new ApiException("key (java.security.Key) cannot be null");
+      throw new ApiException("Private key (java.security.Key) cannot be null");
     }
 
-    signer = new Signer(key, new Signature(name, algorithm, null, headers));
+    signer = new Signer(key, new Signature(keyId, algorithm, null, headers));
   }
 
   @Override
@@ -88,11 +161,13 @@ public class HttpSignatureAuth implements Authentication {
       }
 
       if (headers.contains("digest")) {
-        headerParams.put("digest", "SHA-256=" + new String(Base64.getEncoder().encode(MessageDigest.getInstance("SHA-256").digest(payload.getBytes()))));
+        headerParams.put("digest",
+          this.digestAlgorithm + "=" +
+            new String(Base64.getEncoder().encode(MessageDigest.getInstance(this.digestAlgorithm).digest(payload.getBytes()))));
       }
 
       if (signer == null) {
-        throw new ApiException("Signer cannot be null. Please run the method `setup` to set it up correctly");
+        throw new ApiException("Signer cannot be null. Please call the method `setPrivateKey` to set it up correctly");
       }
 
       // construct the path with the URL query string