APIdia Launch Partner
Top Description Inners Fields Constructors Methods
jdk.security.jarsigner

public final Class JarSigner

extends Object
Class Inheritance
Imports
jdk.internal.access.JavaUtilZipFileAccess, .SharedSecrets, sun.security.pkcs.PKCS7, .PKCS9Attribute, .PKCS9Attributes, sun.security.timestamp.HttpTimestamper, sun.security.util.Event, .ManifestDigester, .SignatureFileVerifier, .SignatureUtil, sun.security.x509.AlgorithmId, java.io.*, java.net.SocketTimeoutException, .URI, java.security.*, java.security.cert.CertPath, .Certificate, .CertificateException, .X509Certificate, java.security.spec.InvalidParameterSpecException, java.util.*, java.util.function.BiConsumer, .Function, java.util.jar.Attributes, .JarEntry, .JarFile, .Manifest, java.util.zip.ZipEntry, .ZipFile, .ZipOutputStream
An immutable utility class to sign a jar file.

A caller creates a JarSigner.Builder object, (optionally) sets some parameters, and calls build to create a JarSigner object. This JarSigner object can then be used to sign a jar file.

Unless otherwise stated, calling a method of JarSigner or JarSigner.Builder with a null argument will throw a NullPointerException.

Example:

JarSigner signer = new JarSigner.Builder(key, certPath) .digestAlgorithm("SHA-256") .signatureAlgorithm("SHA256withRSA") .build(); try (ZipFile in = new ZipFile(inputFile); FileOutputStream out = new FileOutputStream(outputFile)) { signer.sign(in, out); } 
JarSigner signer = new JarSigner.Builder(key, certPath)
        .digestAlgorithm("SHA-256")
        .signatureAlgorithm("SHA256withRSA")
        .build();
try (ZipFile  in = new ZipFile(inputFile);
        FileOutputStream out = new FileOutputStream(outputFile)) {
    signer.sign(in, out);
}
Since
9

Nested and Inner Type Summary

Modifier and TypeClass and Description
public static class
JarSigner.Builder

A mutable builder class that can create an immutable JarSigner from various signing-related parameters.

pack-priv static class
JarSigner.SignatureFile

Field Summary

Modifier and TypeField and Description
private final X509Certificate[]
certChain

private final String[]
digestalg

private final Provider
digestProvider

private boolean
externalFileAttributesDetected

private final BiConsumer<String, String>
handler

private final boolean
internalsf

pack-priv static final JavaUtilZipFileAccess
JUZFA

private final PrivateKey
privateKey

private final boolean
sectionsonly

private final String
sigalg

private final String
signerName

private final Provider
sigProvider

private final String
tSADigestAlg

private final String
tSAPolicyID

private final URI
tsaUrl

Constructor Summary

AccessConstructor and Description
private
JarSigner(JarSigner.Builder builder)

Method Summary

Modifier and TypeMethod and Description
public String

Returns:

the digest algorithm.
getDigestAlgorithm()

Returns the digest algorithm for this JarSigner.

private Attributes
getDigestAttributes(ZipEntry ze, ZipFile zf, MessageDigest[] digests)

private String[]
getDigests(ZipEntry ze, ZipFile zf, MessageDigest[] digests)

private ZipEntry
getManifestFile(ZipFile zf)

public String

Returns:

the value for the property.
getProperty(String
the name of the property.
key)

Returns the value of an additional implementation-specific property indicated by the specified key.

public String

Returns:

the signature algorithm.
getSignatureAlgorithm()

Returns the signature algorithm for this JarSigner.

public String

Returns:

the signer name.
getSignerName()

Returns the signer name of this JarSigner.

public URI

Returns:

the URI of the TSA.
getTsa()

Returns the URI of the Time Stamping Authority (TSA).

public void
sign(ZipFile
the file to sign.
file, OutputStream
the output stream.
os)

Signs a file into an OutputStream.

private void
sign0(ZipFile zipFile, OutputStream os)

private void
updateDigests(ZipEntry ze, ZipFile zf, MessageDigest[] digests, Manifest mf)

private void
writeBytes(ZipFile zf, ZipEntry ze, ZipOutputStream os)

private void
writeEntry(ZipFile zf, ZipOutputStream os, ZipEntry ze)

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait

Field Detail

certChainback to summary
private final X509Certificate[] certChain
digestalgback to summary
private final String[] digestalg
digestProviderback to summary
private final Provider digestProvider
externalFileAttributesDetectedback to summary
private boolean externalFileAttributesDetected
handlerback to summary
private final BiConsumer<String, String> handler
internalsfback to summary
private final boolean internalsf
JUZFAback to summary
pack-priv static final JavaUtilZipFileAccess JUZFA
privateKeyback to summary
private final PrivateKey privateKey
sectionsonlyback to summary
private final boolean sectionsonly
sigalgback to summary
private final String sigalg
signerNameback to summary
private final String signerName
sigProviderback to summary
private final Provider sigProvider
tSADigestAlgback to summary
private final String tSADigestAlg
tSAPolicyIDback to summary
private final String tSAPolicyID
tsaUrlback to summary
private final URI tsaUrl

Constructor Detail

JarSignerback to summary
private JarSigner(JarSigner.Builder builder)

Method Detail

getDigestAlgorithmback to summary
public String getDigestAlgorithm()

Returns the digest algorithm for this JarSigner.

The return value is never null.

Returns:String

the digest algorithm.

getDigestAttributesback to summary
private Attributes getDigestAttributes(ZipEntry ze, ZipFile zf, MessageDigest[] digests) throws IOException
getDigestsback to summary
private String[] getDigests(ZipEntry ze, ZipFile zf, MessageDigest[] digests) throws IOException
getManifestFileback to summary
private ZipEntry getManifestFile(ZipFile zf)
getPropertyback to summary
public String getProperty(String key)

Returns the value of an additional implementation-specific property indicated by the specified key. If a property is not set but has a default value, the default value will be returned.

Implementation Note

See JarSigner.Builder#setProperty for a list of properties this implementation supports. All property names are case-insensitive.

Parameters
key:String

the name of the property.

Returns:String

the value for the property.

Exceptions
UnsupportedOperationException:
if the key is not supported by this implementation.
getSignatureAlgorithmback to summary
public String getSignatureAlgorithm()

Returns the signature algorithm for this JarSigner.

The return value is never null.

Returns:String

the signature algorithm.

getSignerNameback to summary
public String getSignerName()

Returns the signer name of this JarSigner.

The return value is never null.

Returns:String

the signer name.

getTsaback to summary
public URI getTsa()

Returns the URI of the Time Stamping Authority (TSA).

Returns:URI

the URI of the TSA.

signback to summary
public void sign(ZipFile file, OutputStream os)

Signs a file into an OutputStream. This method will not close file or os.

If an I/O error or signing error occurs during the signing, then it may do so after some bytes have been written. Consequently, the output stream may be in an inconsistent state. It is strongly recommended that it be promptly closed in this case.

Parameters
file:ZipFile

the file to sign.

os:OutputStream

the output stream.

Exceptions
JarSignerException:
if the signing fails.
sign0back to summary
private void sign0(ZipFile zipFile, OutputStream os) throws IOException, CertificateException, NoSuchAlgorithmException, SignatureException, InvalidKeyException, InvalidParameterSpecException
updateDigestsback to summary
private void updateDigests(ZipEntry ze, ZipFile zf, MessageDigest[] digests, Manifest mf) throws IOException
writeBytesback to summary
private void writeBytes(ZipFile zf, ZipEntry ze, ZipOutputStream os) throws IOException
writeEntryback to summary
private void writeEntry(ZipFile zf, ZipOutputStream os, ZipEntry ze) throws IOException
jdk.security.jarsigner back to summary

public Class JarSigner.Builder

extends Object
Class Inheritance
A mutable builder class that can create an immutable JarSigner from various signing-related parameters.
Since
9

Field Summary

Modifier and TypeField and Description
pack-priv final X509Certificate[]
certChain

pack-priv String[]
digestalg

pack-priv Provider
digestProvider

pack-priv BiConsumer<String, String>
handler

pack-priv boolean
internalsf

pack-priv final PrivateKey
privateKey

pack-priv boolean
sectionsonly

pack-priv String
sigalg

pack-priv String
signerName

pack-priv Provider
sigProvider

pack-priv String
tSADigestAlg

pack-priv String
tSAPolicyID

pack-priv URI
tsaUrl

Constructor Summary

AccessConstructor and Description
public
Builder(KeyStore.PrivateKeyEntry
the KeyStore.PrivateKeyEntry of the signer.
entry)

Creates a JarSigner.Builder object with a KeyStore.PrivateKeyEntry object.

public
Builder(PrivateKey
the private key of the signer.
privateKey, CertPath
the certification path of the signer.
certPath)

Creates a JarSigner.Builder object with a private key and a certification path.

Method Summary

Modifier and TypeMethod and Description
public JarSigner

Returns:

the JarSigner object.
build()

Builds a JarSigner object from the parameters set by the setter methods.

public JarSigner.Builder

Returns:

the JarSigner.Builder itself.
digestAlgorithm(String
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.
algorithm)

Sets the digest algorithm.

public JarSigner.Builder

Returns:

the JarSigner.Builder itself.
digestAlgorithm(String
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.
algorithm, Provider
the provider.
provider)

Sets the digest algorithm from the specified provider.

public JarSigner.Builder

Returns:

the JarSigner.Builder itself.
eventHandler(BiConsumer<String, String>
the event handler.
handler)

Sets en event handler that will be triggered when a JarEntry is to be added, signed, or updated during the signing process.

public static String

Returns:

the default digest algorithm.
getDefaultDigestAlgorithm()

Gets the default digest algorithm.

public static String

Returns:

the default signature algorithm. Returns null if a default signature algorithm cannot be found. In this case, signatureAlgorithm must be called to specify a signature algorithm. Otherwise, the build method will throw an IllegalArgumentException.
getDefaultSignatureAlgorithm(PrivateKey
the private key.
key)

Gets the default signature algorithm for a private key.

private static boolean
parseBoolean(String name, String value)

public JarSigner.Builder

Returns:

the JarSigner.Builder itself.
setProperty(String
the name of the property.
key, String
the value of the property.
value)

Sets an additional implementation-specific property indicated by the specified key.

public JarSigner.Builder

Returns:

the JarSigner.Builder itself.
signatureAlgorithm(String
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.
algorithm)

Sets the signature algorithm.

public JarSigner.Builder

Returns:

the JarSigner.Builder itself.
signatureAlgorithm(String
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.
algorithm, Provider
the provider.
provider)

Sets the signature algorithm from the specified provider.

public JarSigner.Builder

Returns:

the JarSigner.Builder itself.
signerName(String
the signer name.
name)

Sets the signer name.

public JarSigner.Builder

Returns:

the JarSigner.Builder itself.
tsa(URI
the URI.
uri)

Sets the URI of the Time Stamping Authority (TSA).

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait

Field Detail

certChainback to summary
pack-priv final X509Certificate[] certChain
digestalgback to summary
pack-priv String[] digestalg
digestProviderback to summary
pack-priv Provider digestProvider
handlerback to summary
pack-priv BiConsumer<String, String> handler
internalsfback to summary
pack-priv boolean internalsf
privateKeyback to summary
pack-priv final PrivateKey privateKey
sectionsonlyback to summary
pack-priv boolean sectionsonly
sigalgback to summary
pack-priv String sigalg
signerNameback to summary
pack-priv String signerName
sigProviderback to summary
pack-priv Provider sigProvider
tSADigestAlgback to summary
pack-priv String tSADigestAlg
tSAPolicyIDback to summary
pack-priv String tSAPolicyID
tsaUrlback to summary
pack-priv URI tsaUrl

Constructor Detail

Builderback to summary
public Builder(KeyStore.PrivateKeyEntry entry)

Creates a JarSigner.Builder object with a KeyStore.PrivateKeyEntry object.

Parameters
entry:KeyStore.PrivateKeyEntry

the KeyStore.PrivateKeyEntry of the signer.

Builderback to summary
public Builder(PrivateKey privateKey, CertPath certPath)

Creates a JarSigner.Builder object with a private key and a certification path.

Parameters
privateKey:PrivateKey

the private key of the signer.

certPath:CertPath

the certification path of the signer.

Exceptions
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 Detail

buildback to summary
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:JarSigner

the JarSigner object.

Exceptions
IllegalArgumentException:
if a signature algorithm is not set and cannot be derived from the private key using the getDefaultSignatureAlgorithm method.
digestAlgorithmback to summary
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:String

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:JarSigner.Builder

the JarSigner.Builder itself.

Exceptions
NoSuchAlgorithmException:
if algorithm is not available.
External Specification
Java Security Standard Algorithm Names
digestAlgorithmback to summary
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:String

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:Provider

the provider.

Returns:JarSigner.Builder

the JarSigner.Builder itself.

Exceptions
NoSuchAlgorithmException:
if algorithm is not available in the specified provider.
External Specification
Java Security Standard Algorithm Names
eventHandlerback to summary
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:BiConsumer<String, String>

the event handler.

Returns:JarSigner.Builder

the JarSigner.Builder itself.

getDefaultDigestAlgorithmback to summary
public static String getDefaultDigestAlgorithm()

Gets the default digest algorithm.

Implementation Note

This implementation returns "SHA-384". The value may change in the future.

Returns:String

the default digest algorithm.

getDefaultSignatureAlgorithmback to summary
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:PrivateKey

the private key.

Returns:String

the default signature algorithm. Returns null if a default signature algorithm cannot be found. In this case, signatureAlgorithm must be called to specify a signature algorithm. Otherwise, the build method will throw an IllegalArgumentException.

parseBooleanback to summary
private static boolean parseBoolean(String name, String value)
setPropertyback to summary
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:String

the name of the property.

value:String

the value of the property.

Returns:JarSigner.Builder

the JarSigner.Builder itself.

Exceptions
UnsupportedOperationException:
if the key is not supported by this implementation.
IllegalArgumentException:
if the value is not accepted as a legal value for this key.
signatureAlgorithmback to summary
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 for the private key will be used.

Parameters
algorithm:String

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:JarSigner.Builder

the JarSigner.Builder itself.

Exceptions
NoSuchAlgorithmException:
if algorithm is not available.
IllegalArgumentException:
if algorithm is not compatible with the algorithm of the signer's private key.
External Specification
Java Security Standard Algorithm Names
signatureAlgorithmback to summary
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 for the private key will be used.

Parameters
algorithm:String

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:Provider

the provider.

Returns:JarSigner.Builder

the JarSigner.Builder itself.

Exceptions
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.
External Specification
Java Security Standard Algorithm Names
signerNameback to summary
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:String

the signer name.

Returns:JarSigner.Builder

the JarSigner.Builder itself.

Exceptions
IllegalArgumentException:
if name is empty or has a size bigger than 8, or it contains characters not from the set "a-zA-Z0-9_-".
tsaback to summary
public JarSigner.Builder tsa(URI uri)

Sets the URI of the Time Stamping Authority (TSA).

Parameters
uri:URI

the URI.

Returns:JarSigner.Builder

the JarSigner.Builder itself.

jdk.security.jarsigner back to summary

pack-priv Class JarSigner.SignatureFile

extends Object
Class Inheritance

Field Summary

Modifier and TypeField and Description
pack-priv String
baseName

.SF base name

pack-priv Manifest
sf

SignatureFile

Constructor Summary

AccessConstructor and Description
public
SignatureFile(MessageDigest[] digests, Manifest mf, ManifestDigester md, String baseName, boolean sectionsonly)

Method Summary

Modifier and TypeMethod and Description
private static String
getBaseSignatureFilesName(String baseName)

public String
getBlockName(PrivateKey privateKey)

public String
getMetaName()

public void
write(OutputStream out)

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait

Field Detail

baseNameback to summary
pack-priv String baseName

.SF base name

sfback to summary
pack-priv Manifest sf

SignatureFile

Constructor Detail

SignatureFileback to summary
public SignatureFile(MessageDigest[] digests, Manifest mf, ManifestDigester md, String baseName, boolean sectionsonly)

Method Detail

getBaseSignatureFilesNameback to summary
private static String getBaseSignatureFilesName(String baseName)
getBlockNameback to summary
public String getBlockName(PrivateKey privateKey)
getMetaNameback to summary
public String getMetaName()
writeback to summary
public void write(OutputStream out) throws IOException