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 inherited from 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.

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.

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.

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.