Generates signatures for Java ARchive (JAR) files, and verifies the signatures of signed JAR files.
jarsigner [ options ] jar-file alias jarsigner -verify [ options ] jar-file [alias...]
The jarsigner -verify command can take zero or more keystore alias names after the jar filename. When specified, jarsigner will check that the certificate used to verify each signed entry in the jar file matches one of the keystore aliases. The aliases are defined in the keystore specified by -keystore, or the default keystore.
The jarsigner tool is used for two purposes:
The JAR feature enables the packaging of class files, images, sounds, and other digital data in a single file for faster and easier distribution. A tool named jar enables developers to produce JAR files. (Technically, any zip file can also be considered a JAR file, although when created by jar or processed by jarsigner, JAR files also contain a META-INF/MANIFEST.MF file.)
A digital signature is a string of bits that is computed from some data (the data being "signed") and the private key of an entity (a person, company, etc.). Like a handwritten signature, a digital signature has many useful characteristics:
In order for an entity's signature to be generated for a file, the entity must first have a public/private key pair associated with it, and also one or more certificates authenticating its public key. A certificate is a digitally signed statement from one entity, saying that the public key of some other entity has a particular value.
jarsigner uses key and certificate information from a keystore to generate digital signatures for JAR files. A keystore is a database of private keys and their associated X.509 certificate chains authenticating the corresponding public keys. The keytool utility is used to create and administer keystores.
jarsigner uses an entity's private key to generate a signature. The signed JAR file contains, among other things, a copy of the certificate from the keystore for the public key corresponding to the private key used to sign the file. jarsigner can verify the digital signature of the signed JAR file using the certificate inside it (in its signature block file).
jarsigner can generate signatures that include a timestamp, thus enabling systems/deployer (including Java Plug-in) to check whether the JAR file was signed while the signing certificate was still valid. In addition, APIs will allow applications to obtain the timestamp information.
At this time, jarsigner can only sign JAR files created by the SDK jar tool or zip files. (JAR files are the same as zip files, except they also have a META-INF/MANIFEST.MF file. Such a file will automatically be created when jarsigner signs a zip file.)
The default jarsigner behavior is to sign a JAR
(or zip) file. Use the -verify option to instead have
it verify a signed JAR file.
All keystore entities are accessed via unique aliases.
When using jarsigner to sign a JAR file, you must specify the alias for the keystore entry containing the private key needed to generate the signature. For example, the following will sign the JAR file named "MyJARFile.jar", using the private key associated with the alias "duke" in the keystore named "mystore" in the "working" directory. Since no output file is specified, it overwrites MyJARFile.jar with the signed JAR file.
jarsigner -keystore /working/mystore -storepass <keystore password>
-keypass <private key password> MyJARFile.jar duke
Keystores are protected with a password, so the store password must be specified. You will be prompted for it if you don't specify it on the command line. Similarly, private keys are protected in a keystore with a password, so the private key's password must be specified, and you will be prompted for it if you don't specify it on the command line and it isn't the same as the store password.
jarsigner has a -keystore option for
specifying the URL of the keystore to be used. The keystore is by
default stored in a file named .keystore in the user's
home directory, as determined by the user.home system
property. On Solaris systems user.home defaults to the
user's home directory.
Note that the input stream from the -keystore
option is passed to the KeyStore.load method. If
NONE is specified as the URL, then a null stream is
passed to the KeyStore.load method. NONE
should be specified if the KeyStore is not file-based,
for example, if it resides on a hardware token device.
The KeyStore class provided in the
java.security package supplies well-defined interfaces
to access and modify the information in a keystore. It is possible
for there to be multiple different concrete implementations, where
each implementation is that for a particular type of
keystore.
Currently, there are two command-line tools that make use of
keystore implementations (keytool and jarsigner), and
also a GUI-based tool named Policy Tool. Since
KeyStore is publicly available, Java 2 SDK users can
write additional security applications that use it.
There is a built-in default implementation, provided by Sun Microsystems. It implements the keystore as a file, utilizing a proprietary keystore type (format) named "JKS". It protects each private key with its individual password, and also protects the integrity of the entire keystore with a (possibly different) password.
Keystore implementations are provider-based. More specifically,
the application interfaces supplied by KeyStore are
implemented in terms of a "Service Provider Interface" (SPI). That
is, there is a corresponding abstract KeystoreSpi
class, also in the java.security package, which
defines the Service Provider Interface methods that "providers"
must implement. (The term "provider" refers to a package or a set
of packages that supply a concrete implementation of a subset of
services that can be accessed by the Java Security API.) Thus, to
provide a keystore implementation, clients must implement a
provider and supply a KeystoreSpi subclass implementation, as
described in How to
Implement a Provider for the Java Cryptography
Architecture.
Applications can choose different types of keystore
implementations from different providers, using the "getInstance"
factory method supplied in the KeyStore class. A
keystore type defines the storage and data format of the keystore
information, and the algorithms used to protect private keys in the
keystore and the integrity of the keystore itself. Keystore
implementations of different types are not compatible.
keytool works on any file-based keystore implementation. (It treats the keystore location that is passed to it at the command line as a filename and converts it to a FileInputStream, from which it loads the keystore information.) The jarsigner and policytool tools, on the other hand, can read a keystore from any location that can be specified using a URL.
For jarsigner and keytool, you can specify a keystore type at the command line, via the -storetype option. For Policy Tool, you can specify a keystore type via the "Change Keystore" command in the Edit menu.
If you don't explicitly specify a keystore type, the tools
choose a keystore implementation based simply on the value of the
keystore.type property specified in the security
properties file. The security properties file is called
java.security, and it resides in the SDK security
properties directory, java.home/lib/security,
where java.home is the runtime environment's directory (the
jre directory in the SDK or the top-level directory of the
Java 2 Runtime Environment).
Each tool gets the keystore.type value and then
examines all the currently-installed providers until it finds one
that implements keystores of that type. It then uses the keystore
implementation from that provider.
The KeyStore class defines a static method named
getDefaultType that lets applications and applets
retrieve the value of the keystore.type property. The
following line of code creates an instance of the default keystore
type (as specified in the keystore.type property):
KeyStore keyStore = KeyStore.getInstance(KeyStore.getDefaultType());
The default keystore type is "jks" (the proprietary type of the keystore implementation provided by Sun). This is specified by the following line in the security properties file:
keystore.type=jks
Note: Case doesn't matter in keystore type designations. For example, "JKS" would be considered the same as "jks".
To have the tools utilize a keystore implementation other than the default, change that line to specify a different keystore type. For example, if you have a provider package that supplies a keystore implementation for a keystore type called "pkcs12", change the line to
keystore.type=pkcs12
Note that if you us the PKCS#11 provider package, you should refer to the KeyTool and JarSigner section of the Java PKCS#11 Reference Guide for details.
By default, jarsigner signs a JAR file using one of the following:
That is, if the signer's public and private keys are DSA keys, jarsigner will sign the JAR file using the "SHA1withDSA" algorithm. If the signer's keys are RSA keys, jarsigner will attempt to sign the JAR file using the "SHA256withRSA" algorithm. If the signer's keys are EC keys, jarsigner will sign the JAR file using the "SHA256withECDSA" algorithm.
These default signature algorithms can be overridden using the -sigalg option.
When jarsigner is used to sign a JAR file, the output signed JAR file is exactly the same as the input JAR file, except that it has two additional files placed in the META-INF directory:
The base file names for these two files come from the value of
the -sigFile option. For example, if the option
appears as
-sigFile MKSIGN
The files are named "MKSIGN.SF" and "MKSIGN.DSA".
If no -sigfile option appears on the command line,
the base file name for the .SF and .DSA files will be the first 8
characters of the alias name specified on the command line, all
converted to upper case. If the alias name has fewer than 8
characters, the full alias name is used. If the alias name contains
any characters that are not allowed in a signature file name, each
such character is converted to an underscore ("_") character in
forming the file name. Legal characters include letters, digits,
underscores, and hyphens.
A signature file (the .SF file) looks similar to the manifest file that is always included in a JAR file when jarsigner is used to sign the file. That is, for each source file included in the JAR file, the .SF file has three lines, just as in the manifest file, listing the following:
In the manifest file, the SHA digest value for each source file is the digest (hash) of the binary data in the source file. In the .SF file, on the other hand, the digest value for a given source file is the hash of the three lines in the manifest file for the source file.
The signature file also, by default, includes a header containing a hash of the whole manifest file. The presence of the header enables verification optimization, as described in JAR File Verification.
jarsigner tool can generate and store a signature
timestamp when signing a JAR file. In addition,
jarsigner supports alternative signing mechanisms.
This behavior is optional and is controlled by the user at the time
of signing through these options:
Each of these options is detailed in the Options section below.
A successful JAR file verification occurs if the signature(s) are valid, and none of the files that were in the JAR file when the signatures were generated have been changed since then. JAR file verification involves the following steps:
jar tool) after the signature (and thus the
.SF file) was generated. When the jar tool is used to
add files, the manifest file is changed (sections are added to it
for the new files), but the .SF file is not. A verification is
still considered successful if none of the files that were in the
JAR file when the signature was generated have been changed since
then, which is the case if the hashes in the non-header sections of
the .SF file equal the hashes of the corresponding sections in the
manifest file.
If any serious verification failures occur during the verification process, the process is stopped and a security exception is thrown. It is caught and displayed by jarsigner.
A JAR file can be signed by multiple people simply by running the jarsigner tool on the file multiple times, specifying the alias for a different person each time, as in:
jarsigner myBundle.jar susan jarsigner myBundle.jar kevin
When a JAR file is signed multiple times, there are multiple .SF and .DSA files in the resulting JAR file, one pair for each signature. Thus, in the example above, the output JAR file includes files with the following names:
SUSAN.SF SUSAN.DSA KEVIN.SF KEVIN.DSA
Note: It is also possible for a JAR file to have mixed signatures, some generated by the JDK 1.1 javakey tool and others by jarsigner. That is, jarsigner can be used to sign JAR files already previously signed using javakey.
The various jarsigner options are listed and described below. Note:
-keystore, -storepass,
-keypass, -sigfile, -sigalg,
-digestalg, and -signedjar options are
only relevant when signing a JAR file, not when verifying a signed
JAR file. Similarly, an alias is only specified on the command line
when signing a JAR file.-keystore url-verbose
option was also specified, additional information is output
regarding whether or not any of the certificates used to verify the
JAR file are contained in that keystore.
-keystore argument can actually be a file
name (and path) specification rather than a URL, in which case it
will be treated the same as a "file:" URL. That is,
-keystore filePathAndNameis treated as equivalent to
-keystore file:filePathAndNameIf the Sun PKCS#11 provider has been configured in the java.security security properties file (located in the JRE's $JAVA_HOME/lib/security directory), then keytool and jarsigner can operate on the PKCS#11 token by specifying these options:
-keystore NONE-storetype PKCS11jarsigner -keystore NONE -storetype PKCS11 -list
-storetype storetypegetDefaultType method in
java.security.KeyStore.
-storepass option. If none has been specified, keytool
and jarsigner will prompt for the token PIN. If the token has a
protected authentication path (such as a dedicated PIN-pad or a
biometric reader), then the -protected option must be
specified and no password options can be specified.
-storepass[:env |
:file] argument-storepass option is not provided at
the command line, the user is prompted for the password.
env or file is not
specified, then the password has the value argument.
Otherwise, the password is retrieved as follows:
env: Retrieve the password from the environment
variable named argumentfile: Retrieve the password from the file named
argument-keypass[:env |
:file] argumentenv or file is not
specified, then the password has the value argument.
Otherwise, the password is retrieved as follows:
env: Retrieve the password from the environment
variable named argumentfile: Retrieve the password from the file named
argument-sigfile file-sigfile option appears on the command line,
the base file name for the .SF and .DSA files will be the first 8
characters of the alias name specified on the command line, all
converted to upper case. If the alias name has fewer than 8
characters, the full alias name is used. If the alias name contains
any characters that are not legal in a signature file name, each
such character is converted to an underscore ("_") character in
forming the file name.
-sigalg algorithm-digestalg algorithm-signedjar file-verify-certs-verify and -verbose options, the output
includes certificate information for each signer of the JAR file.
This information includes
java.security.cert.X509Certificate):
the distinguished name of the signer-certchain file-verbose-internalsf-internalsf appears on the command
line, the old behavior is utilized. This option is mainly useful
for testing; in practice, it should not be used, since doing so
eliminates a useful optimization.-sectionsonly-protectedtrue or false. This value
should be specified as true if a password must be
given via a protected authentication path such as a dedicated PIN
reader.-providerClass
provider-class-name-providerArg
ConfigFilePath option, keytool and jarsigner will install
the provider dynamically (where ConfigFilePath is the path
to the token configuration file). Here's an example of a command to
list a PKCS#11 keystore when the Sun PKCS#11 provider has not been
configured in the security properties file.
jarsigner -keystore NONE -storetype PKCS11 \
-providerClass sun.security.pkcs11.SunPKCS11 \
-providerArg /foo/bar/token.config \
-list
-providerName providerName
jarsigner -keystore NONE -storetype PKCS11 \
-providerName SunPKCS11-SmartCard \
-list
-Jjavaoptionjava
-h or java -X at the command line.
-tsa url"-tsa http://example.tsa.url" appears on the
command line when signing a JAR file then a timestamp is generated
for the signature. The URL, http://example.tsa.url,
identifies the location of the Time Stamping Authority (TSA). It
overrides any URL found via the -tsacert option. The
-tsa option does not require the TSA's public key
certificate to be present in the keystore.
jarsigner communicates
with the TSA using the Time-Stamp Protocol (TSP) defined in
RFC 3161. If
successful, the timestamp token returned by the TSA is stored along
with the signature in the signature block file.
-tsacert alias"-tsacert alias" appears on the command line
when signing a JAR file then a timestamp is generated for the
signature. The alias identifies the TSA's public key
certificate in the keystore that is currently in effect. The
entry's certificate is examined for a Subject Information Access
extension that contains a URL identifying the location of the TSA.
-tsacert.
-altsigner classcom.sun.jarsigner.ContentSigner abstract class. The
path to this class file is defined by the
-altsignerpath option. If the -altsigner
option is used, jarsigner uses the signing mechanism
provided by the specified class. Otherwise, jarsigner
uses its default signing mechanism.
com.sun.sun.jarsigner.AuthSigner, use the
jarsigner option "-altsigner
com.sun.jarsigner.AuthSigner"
-altsignerpath classpathlist-altsigner option described above)
and any JAR files it depends on. If the class file is in a JAR
file, then this specifies the path to that JAR file, as shown in
the example below.
classpathlist contains multiple paths
or JAR files, they should be separated with a colon
(:) on Solaris and a semi-colon (;) on
Windows. This option is not necessary if the class is already in
the search path.
-altsignerpath /home/user/lib/authsigner.jarNote that the JAR file name is included.
-altsignerpath /home/user/classes/com/sun/tools/jarsigner/Note that the JAR file name is omitted.
-strict-verbose:sub-options-verbose option
takes sub-options to determine how much information will be shown.
If -certs is also specified, the default mode (or
sub-option all) displays each entry as it is being processed and
following that, the certificate information for each signer of the
JAR file. If -certs and the
-verbose:grouped sub-option are specified, entries
with the same signer info are grouped and displayed together along
with their certificate information. If -certs and the
-verbose:summary sub-option are specified, then
entries with the same signer info are grouped and displayed
together along with their certificate information but details about
each entry are summarized and displayed as "one entry (and more)".
See the examples section for more information.Suppose you have a JAR file named "bundle.jar" and you'd like to sign it using the private key of the user whose keystore alias is "jane" in the keystore named "mystore" in the "working" directory. You can use the following to sign the JAR file and name the signed JAR file "sbundle.jar":
jarsigner -keystore /working/mystore -storepass <keystore password>
-keypass <private key password> -signedjar sbundle.jar bundle.jar jane
Note that there is no -sigfile specified in the
command above, so the generated .SF and .DSA files to be placed in
the signed JAR file will have default names based on the alias
name. That is, they will be named JANE.SF and
JANE.DSA.
If you want to be prompted for the store password and the private key password, you could shorten the above command to
jarsigner -keystore /working/mystore
-signedjar sbundle.jar bundle.jar jane
If the keystore to be used is the default keystore (the one named ".keystore" in your home directory), you don't need to specify a keystore, as in:
jarsigner -signedjar sbundle.jar bundle.jar jane
Finally, if you want the signed JAR file to simply overwrite the
input JAR file (bundle.jar), you don't need to specify
a -signedjar option:
jarsigner bundle.jar jane
To verify a signed JAR file, that is, to verify that the signature is valid and the JAR file has not been tampered with, use a command such as the following:
jarsigner -verify sbundle.jar
If the verification is successful,
jar verified.
is displayed. Otherwise, an error message appears.
You can get more information if you use the
-verbose option. A sample use of jarsigner with
the -verbose option is shown below, along with sample
output:
jarsigner -verify -verbose sbundle.jar
198 Fri Sep 26 16:14:06 PDT 1997 META-INF/MANIFEST.MF
199 Fri Sep 26 16:22:10 PDT 1997 META-INF/JANE.SF
1013 Fri Sep 26 16:22:10 PDT 1997 META-INF/JANE.DSA
smk 2752 Fri Sep 26 16:12:30 PDT 1997 AclEx.class
smk 849 Fri Sep 26 16:12:46 PDT 1997 test.class
s = signature was verified
m = entry is listed in manifest
k = at least one certificate was found in keystore
jar verified.
If you specify the -certs option when verifying,
along with the -verify and -verbose
options, the output includes certificate information for each
signer of the JAR file, including the certificate type, the signer
distinguished name information (if and only if it's an X.509
certificate), and, in parentheses, the keystore alias for the
signer if the public key certificate in the JAR file matches that
in a keystore entry. For example,
jarsigner -keystore /working/mystore -verify -verbose -certs myTest.jar
198 Fri Sep 26 16:14:06 PDT 1997 META-INF/MANIFEST.MF
199 Fri Sep 26 16:22:10 PDT 1997 META-INF/JANE.SF
1013 Fri Sep 26 16:22:10 PDT 1997 META-INF/JANE.DSA
208 Fri Sep 26 16:23:30 PDT 1997 META-INF/JAVATEST.SF
1087 Fri Sep 26 16:23:30 PDT 1997 META-INF/JAVATEST.DSA
smk 2752 Fri Sep 26 16:12:30 PDT 1997 Tst.class
X.509, CN=Test Group, OU=Java Software, O=Sun Microsystems, L=CUP, S=CA, C=US (javatest)
X.509, CN=Jane Smith, OU=Java Software, O=Sun, L=cup, S=ca, C=us (jane)
s = signature was verified
m = entry is listed in manifest
k = at least one certificate was found in keystore
jar verified.
If the certificate for a signer is not an X.509 certificate, there is no distinguished name information. In that case, just the certificate type and the alias are shown. For example, if the certificate is a PGP certificate, and the alias is "bob", you'd get
PGP, (bob)
If a JAR file has been signed using the JDK 1.1 javakey tool, and thus the signer is an alias in an identity database, the verification output includes an "i" symbol. If the JAR file has been signed by both an alias in an identity database and an alias in a keystore, both "k" and "i" appear.
When the -certs option is used, any identity
database aliases are shown in square brackets rather than the
parentheses used for keystore aliases. For example:
jarsigner -keystore /working/mystore -verify -verbose -certs writeFile.jar
198 Fri Sep 26 16:14:06 PDT 1997 META-INF/MANIFEST.MF
199 Fri Sep 26 16:22:10 PDT 1997 META-INF/JANE.SF
1013 Fri Sep 26 16:22:10 PDT 1997 META-INF/JANE.DSA
199 Fri Sep 27 12:22:30 PDT 1997 META-INF/DUKE.SF
1013 Fri Sep 27 12:22:30 PDT 1997 META-INF/DUKE.DSA
smki 2752 Fri Sep 26 16:12:30 PDT 1997 writeFile.html
X.509, CN=Jane Smith, OU=Java Software, O=Sun, L=cup, S=ca, C=us (jane)
X.509, CN=Duke, OU=Java Software, O=Sun, L=cup, S=ca, C=us [duke]
s = signature was verified
m = entry is listed in manifest
k = at least one certificate was found in keystore
i = at least one certificate was found in identity scope
jar verified.
Note that the alias "duke" is in brackets to denote that it is an identity database alias, not a keystore alias.
hasExpiringCert 2
This jar contains entries whose signer certificate will expire within six months
hasExpiredCert 4
This jar contains entries whose signer certificate has expired.
notYetValidCert 4
This jar contains entries whose signer certificate is not yet valid.
chainNotValidated 4
This jar contains entries whose certificate chain cannot be correctly validated.
badKeyUsage 8
This jar contains entries whose signer certificate's KeyUsage extension doesn't allow code signing.
badExtendedKeyUsage 8
This jar contains entries whose signer certificate's ExtendedKeyUsage extension
doesn't allow code signing.
badNetscapeCertType 8
This jar contains entries whose signer certificate's NetscapeCertType extension
doesn't allow code signing.
hasUnsignedEntry 16
This jar contains unsigned entries which have not been integrity-checked.
notSignedByAlias 32
This jar contains signed entries which are not signed by the specified alias(es)
aliasNotInStore 32
This jar contains signed entries that are not signed by alias in this keystore
When the -strict option is provided, an OR-value of
warnings detected will be returned as the exit code of the tool.
For example, if a certificate used to sign an entry is expired and
has a keyUsage extension that does not allow it to sign a file, an
exit code 12 (=4+8) will be returned.
Note: Exit codes are reused because only 0-255 is legal for Unix. In any case, if the signing/verifying process fails, the following exit code will be returned:
failure 1
The keytool and jarsigner tools completely replace the javakey tool provided in JDK 1.1. These new tools provide more features than javakey, including the ability to protect the keystore and private keys with passwords, and the ability to verify signatures in addition to generating them.
The new keystore architecture replaces the identity database that javakey created and managed. There is no backwards compatibility between the keystore format and the database format used by javakey in 1.1. However,
-identitydb command.The following table explains how JAR files that were signed in JDK 1.1.x are treated in the Java 2 platform.
| JAR File Type | Identity in 1.1 database | Trusted Identity imported into Java 2 Platform keystore from 1.1 database (4) | Policy File grants privileges to Identity/Alias | Privileges Granted |
|---|---|---|---|---|
|
Signed JAR |
NO |
NO |
NO |
Default privileges granted to all code. |
|
Unsigned JAR |
NO |
NO |
NO |
Default privileges granted to all code. |
|
Signed JAR |
NO |
YES |
NO |
Default privileges granted to all code. |
|
Signed JAR |
YES/Untrusted |
NO |
NO |
Default privileges granted to all code. (3) |
|
Signed JAR |
YES/Untrusted |
NO |
YES |
Default privileges granted to all code. (1,3) |
|
Signed JAR |
NO |
YES |
YES |
Default privileges granted to all code plus privileges granted in policy file. |
|
Signed JAR |
YES/Trusted |
YES |
YES |
Default privileges granted to all code plus privileges granted in policy file. (2) |
|
Signed JAR |
YES/Trusted |
NO |
NO |
All privileges |
|
Signed JAR |
YES/Trusted |
YES |
NO |
All privileges (1) |
|
Signed JAR |
YES/Trusted |
NO |
YES |
All privileges (1) |
Notes:
