Module jdk.jartool
Package jdk.security.jarsigner

# Class JarSigner.Builder

java.lang.Object
jdk.security.jarsigner.JarSigner.Builder

Enclosing class:
  `JarSigner`

public static class JarSigner.Builder extends Object
A mutable builder class that can create an immutable `JarSigner` from various signing-related parameters.

Since:
  9

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `Builder(KeyStore.PrivateKeyEntry entry)`
  Creates a `JarSigner.Builder` object with a `KeyStore.PrivateKeyEntry` object.
  `Builder(PrivateKey privateKey, CertPath certPath)`
  Creates a `JarSigner.Builder` object with a private key and a certification path.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `JarSigner`
  `build()`
  Builds a `JarSigner` object from the parameters set by the setter methods.
  `JarSigner.Builder`
  `digestAlgorithm(String algorithm)`
  Sets the digest algorithm.
  `JarSigner.Builder`
  `digestAlgorithm(String algorithm, Provider provider)`
  Sets the digest algorithm from the specified provider.
  `JarSigner.Builder`
  `eventHandler(BiConsumer<String,String> handler)`
  Sets en event handler that will be triggered when a `JarEntry` is to be added, signed, or updated during the signing process.
  `static String`
  `getDefaultDigestAlgorithm()`
  Gets the default digest algorithm.
  `static String`
  `getDefaultSignatureAlgorithm(PrivateKey key)`
  Gets the default signature algorithm for a private key.
  `JarSigner.Builder`
  `setProperty(String key, String value)`
  Sets an additional implementation-specific property indicated by the specified key.
  `JarSigner.Builder`
  `signatureAlgorithm(String algorithm)`
  Sets the signature algorithm.
  `JarSigner.Builder`
  `signatureAlgorithm(String algorithm, Provider provider)`
  Sets the signature algorithm from the specified provider.
  `JarSigner.Builder`
  `signerName(String name)`
  Sets the signer name.
  `JarSigner.Builder`
  `tsa(URI uri)`
  Sets the URI of the Time Stamping Authority (TSA).

  ### Methods declared in class java.lang.Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- ## Constructor Details

  - ### Builder

    public Builder(KeyStore.PrivateKeyEntry entry)
    Creates a `JarSigner.Builder` object with a `KeyStore.PrivateKeyEntry` object.
    Parameters:
      `entry` - the `KeyStore.PrivateKeyEntry` of the signer.

  - ### Builder

    public Builder(PrivateKey privateKey, CertPath certPath)
    Creates a `JarSigner.Builder` object with a private key and a certification path.
    Parameters:
      `privateKey` - the private key of the signer.
      `certPath` - the certification path of the signer.
    Throws:
      `IllegalArgumentException` - if `certPath` is empty, or the `privateKey` algorithm does not match the algorithm of the `PublicKey` in the end entity certificate (the first certificate in `certPath`).

- ## Method Details

  - ### digestAlgorithm

    public JarSigner.Builder digestAlgorithm(String algorithm) throws NoSuchAlgorithmException
    Sets the digest algorithm. If no digest algorithm is specified, the default algorithm returned by `getDefaultDigestAlgorithm()` will be used.
    Parameters:
      `algorithm` - the standard name of the algorithm. See the `MessageDigest` section in the Java Cryptography Architecture Standard Algorithm Name Documentation for information about standard algorithm names.
    Returns:
      the `JarSigner.Builder` itself.
    Throws:
      `NoSuchAlgorithmException` - if `algorithm` is not available.

  - ### digestAlgorithm

    public JarSigner.Builder digestAlgorithm(String algorithm, Provider provider) throws NoSuchAlgorithmException
    Sets the digest algorithm from the specified provider. If no digest algorithm is specified, the default algorithm returned by `getDefaultDigestAlgorithm()` will be used.
    Parameters:
      `algorithm` - the standard name of the algorithm. See the `MessageDigest` section in the Java Cryptography Architecture Standard Algorithm Name Documentation for information about standard algorithm names.
      `provider` - the provider.
    Returns:
      the `JarSigner.Builder` itself.
    Throws:
      `NoSuchAlgorithmException` - if `algorithm` is not available in the specified provider.

  - ### signatureAlgorithm

    public JarSigner.Builder signatureAlgorithm(String algorithm) throws NoSuchAlgorithmException
    Sets the signature algorithm. If no signature algorithm is specified, the default signature algorithm returned by `getDefaultSignatureAlgorithm(java.security.PrivateKey)` for the private key will be used.
    Parameters:
      `algorithm` - the standard name of the algorithm. See the `Signature` section in the Java Cryptography Architecture Standard Algorithm Name Documentation for information about standard algorithm names.
    Returns:
      the `JarSigner.Builder` itself.
    Throws:
      `NoSuchAlgorithmException` - if `algorithm` is not available.
      `IllegalArgumentException` - if `algorithm` is not compatible with the algorithm of the signer's private key.

  - ### signatureAlgorithm

    public JarSigner.Builder signatureAlgorithm(String algorithm, Provider provider) throws NoSuchAlgorithmException
    Sets the signature algorithm from the specified provider. If no signature algorithm is specified, the default signature algorithm returned by `getDefaultSignatureAlgorithm(java.security.PrivateKey)` for the private key will be used.
    Parameters:
      `algorithm` - the standard name of the algorithm. See the `Signature` section in the Java Cryptography Architecture Standard Algorithm Name Documentation for information about standard algorithm names.
      `provider` - the provider.
    Returns:
      the `JarSigner.Builder` itself.
    Throws:
      `NoSuchAlgorithmException` - if `algorithm` is not available in the specified provider.
      `IllegalArgumentException` - if `algorithm` is not compatible with the algorithm of the signer's private key.

  - ### tsa

    public JarSigner.Builder tsa(URI uri)
    Sets the URI of the Time Stamping Authority (TSA).
    Parameters:
      `uri` - the URI.
    Returns:
      the `JarSigner.Builder` itself.

  - ### signerName

    public JarSigner.Builder signerName(String name)
    Sets the signer name. The name will be used as the base name for the signature files. All lowercase characters will be converted to uppercase for signature file names. If a signer name is not specified, the string "SIGNER" will be used.
    Parameters:
      `name` - the signer name.
    Returns:
      the `JarSigner.Builder` itself.
    Throws:
      `IllegalArgumentException` - if `name` is empty or has a size bigger than 8, or it contains characters not from the set "a-zA-Z0-9_-".

  - ### eventHandler

    public JarSigner.Builder eventHandler(BiConsumer<String,String> handler)
    Sets en event handler that will be triggered when a `JarEntry` is to be added, signed, or updated during the signing process.

    The handler can be used to display signing progress. The first argument of the handler can be "adding", "signing", or "updating", and the second argument is the name of the `JarEntry` being processed.

    Parameters:
      `handler` - the event handler.
    Returns:
      the `JarSigner.Builder` itself.

  - ### setProperty

    public JarSigner.Builder setProperty(String key, String value)
    Sets an additional implementation-specific property indicated by the specified key.
    Implementation Note:
      This implementation supports the following properties:
      - "tsaDigestAlg": algorithm of digest data in the timestamping request. The default value is the same as the result of `getDefaultDigestAlgorithm()`.
      - "tsaPolicyId": TSAPolicyID for Timestamping Authority. No default value.
      - "internalsf": "true" if the .SF file is included inside the signature block, "false" otherwise. Default "false".
      - "sectionsonly": "true" if the .SF file only contains the hash value for each section of the manifest and not for the whole manifest, "false" otherwise. Default "false".
      All property names are case-insensitive.
    Parameters:
      `key` - the name of the property.
      `value` - the value of the property.
    Returns:
      the `JarSigner.Builder` itself.
    Throws:
      `UnsupportedOperationException` - if the key is not supported by this implementation.
      `IllegalArgumentException` - if the value is not accepted as a legal value for this key.

  - ### getDefaultDigestAlgorithm

    public static String getDefaultDigestAlgorithm()
    Gets the default digest algorithm.
    Implementation Note:
      This implementation returns "SHA-384". The value may change in the future.
    Returns:
      the default digest algorithm.

  - ### getDefaultSignatureAlgorithm

    public static String getDefaultSignatureAlgorithm(PrivateKey key)
    Gets the default signature algorithm for a private key. For example, SHA384withRSA for a 2048-bit RSA key, and SHA384withECDSA for a 384-bit EC key.
    Implementation Note:
      This implementation makes use of comparable strengths as defined in Tables 2 and 3 of NIST SP 800-57 Part 1-Rev.5 as well as NIST recommendations as appropriate. Specifically, if an RSA key with a key size greater than 7680 bits, or an EC key with a key size greater than or equal to 512 bits, SHA-512 will be used as the hash function for the signature. Otherwise, SHA-384 will be used unless the key size is too small for resulting signature algorithm. As for DSA keys, the SHA256withDSA signature algorithm is returned regardless of key size. The value may change in the future.
    Parameters:
      `key` - the private key.
    Returns:
      the default signature algorithm. Returns null if a default signature algorithm cannot be found. In this case, `signatureAlgorithm(java.lang.String)` must be called to specify a signature algorithm. Otherwise, the `build()` method will throw an `IllegalArgumentException`.

  - ### build

    public JarSigner build()
    Builds a `JarSigner` object from the parameters set by the setter methods.

    This method does not modify internal state of this `Builder` object and can be called multiple times to generate multiple `JarSigner` objects. After this method is called, calling any method on this `Builder` will have no effect on the newly built `JarSigner` object.

    Returns:
      the `JarSigner` object.
    Throws:
      `IllegalArgumentException` - if a signature algorithm is not set and cannot be derived from the private key using the `getDefaultSignatureAlgorithm(java.security.PrivateKey)` method.