.\"t

.\" Copyright (c) 1994, 2019, Oracle and/or its affiliates. All rights reserved.

.\" DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.

.\"

.\" This code is free software; you can redistribute it and/or modify it

.\" under the terms of the GNU General Public License version 2 only, as

.\" published by the Free Software Foundation.

.\"

.\" This code is distributed in the hope that it will be useful, but WITHOUT

.\" ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or

.\" FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License

.\" version 2 for more details (a copy is included in the LICENSE file that

.\" accompanied this code).

.\"

.\" You should have received a copy of the GNU General Public License version

.\" 2 along with this work; if not, write to the Free Software Foundation,

.\" Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.

.\"

.\" Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA

.\" or visit www.oracle.com if you need additional information or have any

.\" questions.

.\"

.\" Automatically generated by Pandoc 2.3.1

.\"

.TH "JARSIGNER" "1" "2019" "JDK 13" "JDK Commands"

.hy

.SH NAME

.PP

jarsigner \- sign and verify Java Archive (JAR) files

.SH SYNOPSIS

.PP

\f[CB]jarsigner\f[R] [\f[I]options\f[R]] \f[I]jar\-file\f[R] \f[I]alias\f[R]

.PP

\f[CB]jarsigner\f[R] \f[CB]\-verify\f[R] [\f[I]options\f[R]]

\f[I]jar\-file\f[R] [\f[I]alias\f[R] ...]

.TP

.B \f[I]options\f[R]

The command\-line options.

See \f[B]Options for jarsigner\f[R].

.RS

.RE

.TP

.B \f[CB]\-verify\f[R]

The \f[CB]\-verify\f[R] option can take zero or more keystore alias names

after the JAR file name.

When the \f[CB]\-verify\f[R] option is specified, the \f[CB]jarsigner\f[R]

command checks 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 \f[CB]\-keystore\f[R]

or the default keystore.

.RS

.PP

If you also specify the \f[CB]\-strict\f[R] option, and the

\f[CB]jarsigner\f[R] command detects severe warnings, the message, "jar

verified, with signer errors" is displayed.

.RE

.TP

.B \f[I]jar\-file\f[R]

The JAR file to be signed.

.RS

.PP

If you also specified the \f[CB]\-strict\f[R] option, and the

\f[CB]jarsigner\f[R] command detected severe warnings, the message, "jar

signed, with signer errors" is displayed.

.RE

.TP

.B \f[I]alias\f[R]

The aliases are defined in the keystore specified by \f[CB]\-keystore\f[R]

or the default keystore.

.RS

.RE

.SH DESCRIPTION

.PP

The \f[CB]jarsigner\f[R] tool has two purposes:

.IP \[bu] 2

To sign Java Archive (JAR) files.

.IP \[bu] 2

To verify the signatures and integrity of signed JAR files.

.PP

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 \f[CB]jar\f[R] enables developers to produce JAR files.

(Technically, any ZIP file can also be considered a JAR file, although

when created by the \f[CB]jar\f[R] command or processed by the

\f[CB]jarsigner\f[R] command, JAR files also contain a

\f[CB]META\-INF/MANIFEST.MF\f[R] file.)

.PP

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, and so on).

Similar to a handwritten signature, a digital signature has many useful

characteristics:

.IP \[bu] 2

Its authenticity can be verified by a computation that uses the public

key corresponding to the private key used to generate the signature.

.IP \[bu] 2

It can\[aq]t be forged, assuming the private key is kept secret.

.IP \[bu] 2

It is a function of the data signed and thus can\[aq]t be claimed to be

the signature for other data as well.

.IP \[bu] 2

The signed data can\[aq]t be changed.

If the data is changed, then the signature can\[aq]t be verified as

authentic.

.PP

To generate an entity\[aq]s signature for a file, the entity must first

have a public/private key pair associated with it and one or more

certificates that authenticate its public key.

A certificate is a digitally signed statement from one entity that says

that the public key of another entity has a particular value.

.PP

The \f[CB]jarsigner\f[R] command 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 that authenticate the corresponding public keys.

The \f[CB]keytool\f[R] command is used to create and administer keystores.

.PP

The \f[CB]jarsigner\f[R] command uses an entity\[aq]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.

The \f[CB]jarsigner\f[R] command can verify the digital signature of the

signed JAR file using the certificate inside it (in its signature block

file).

.PP

The \f[CB]jarsigner\f[R] command can generate signatures that include a

time stamp that enables a systems or deployer to check whether the JAR

file was signed while the signing certificate was still valid.

.PP

In addition, APIs allow applications to obtain the timestamp

information.

.PP

At this time, the \f[CB]jarsigner\f[R] command can only sign JAR files

created by the \f[CB]jar\f[R] command or zip files.

JAR files are the same as zip files, except they also have a

\f[CB]META\-INF/MANIFEST.MF\f[R] file.

A \f[CB]META\-INF/MANIFEST.MF\f[R] file is created when the

\f[CB]jarsigner\f[R] command signs a zip file.

.PP

The default \f[CB]jarsigner\f[R] command behavior is to sign a JAR or zip

file.

Use the \f[CB]\-verify\f[R] option to verify a signed JAR file.

.PP

The \f[CB]jarsigner\f[R] command also attempts to validate the

signer\[aq]s certificate after signing or verifying.

If there is a validation error or any other problem, the command

generates warning messages.

If you specify the \f[CB]\-strict\f[R] option, then the command treats

severe warnings as errors.

See \f[B]Errors and Warnings\f[R].

.SH KEYSTORE ALIASES

.PP

All keystore entities are accessed with unique aliases.

.PP

When you use the \f[CB]jarsigner\f[R] command to sign a JAR file, you must

specify the alias for the keystore entry that contains the private key

needed to generate the signature.

If no output file is specified, it overwrites the original JAR file with

the signed JAR file.

.PP

Keystores are protected with a password, so the store password must be

specified.

You are prompted for it when you don\[aq]t specify it on the command

line.

Similarly, private keys are protected in a keystore with a password, so

the private key\[aq]s password must be specified, and you are prompted

for the password when you don\[aq]t specify it on the command line and

it isn\[aq]t the same as the store password.

.SH KEYSTORE LOCATION

.PP

The \f[CB]jarsigner\f[R] command has a \f[CB]\-keystore\f[R] option for

specifying the URL of the keystore to be used.

The keystore is by default stored in a file named \f[CB]\&.keystore\f[R]

in the user\[aq]s home directory, as determined by the

\f[CB]user.home\f[R] system property.

.PP

\f[B]Oracle Solaris, Linux, and OS X:\f[R] \f[CB]user.home\f[R] defaults to

the user\[aq]s home directory.

.PP

The input stream from the \f[CB]\-keystore\f[R] option is passed to the

\f[CB]KeyStore.load\f[R] method.

If \f[CB]NONE\f[R] is specified as the URL, then a null stream is passed

to the \f[CB]KeyStore.load\f[R] method.

\f[CB]NONE\f[R] should be specified when the \f[CB]KeyStore\f[R] class

isn\[aq]t file based, for example, when it resides on a hardware token

device.

.SH KEYSTORE IMPLEMENTATION

.PP

The \f[CB]KeyStore\f[R] class provided in the \f[CB]java.security\f[R]

package supplies a number of well\-defined interfaces to access and

modify the information in a keystore.

You can have multiple different concrete implementations, where each

implementation is for a particular type of keystore.

.PP

Currently, there are two command\-line tools that use keystore

implementations (\f[CB]keytool\f[R] and \f[CB]jarsigner\f[R]).

.PP

The default keystore implementation is \f[CB]PKCS12\f[R].

This is a cross platform keystore based on the RSA PKCS12 Personal

Information Exchange Syntax Standard.

This standard is primarily meant for storing or transporting a

user\[aq]s private keys, certificates, and miscellaneous secrets.

There is another built\-in implementation, provided by Oracle.

It implements the keystore as a file with a proprietary keystore type

(format) named \f[CB]JKS\f[R].

It protects each private key with its individual password, and also

protects the integrity of the entire keystore with a (possibly

different) password.

.PP

Keystore implementations are provider\-based, which means the

application interfaces supplied by the \f[CB]KeyStore\f[R] class are

implemented in terms of a Service Provider Interface (SPI).

There is a corresponding abstract \f[CB]KeystoreSpi\f[R] class, also in

the \f[CB]java.security\ package\f[R], that 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.

To provide a keystore implementation, clients must implement a provider

and supply a \f[CB]KeystoreSpi\f[R] subclass implementation, as described

in \f[B]How to Implement a Provider in the Java Cryptography

Architecture\f[R]

[https://www.oracle.com/pls/topic/lookup?ctx=en/java/javase/11/tools&id=JSSEC\-GUID\-2BCFDD85\-D533\-4E6C\-8CE9\-29990DEB0190].

.PP

Applications can choose different types of keystore implementations from

different providers, with the \f[CB]getInstance\f[R] factory method in the

\f[CB]KeyStore\f[R] 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 aren\[aq]t compatible.

.PP

The \f[CB]jarsigner\f[R] commands can read file\-based keystores from any

location that can be specified using a URL.

In addition, these commands can read non\-file\-based keystores such as

those provided by MSCAPI on Windows and PKCS11 on all platforms.

.PP

For the \f[CB]jarsigner\f[R] and \f[CB]keytool\f[R] commands, you can

specify a keystore type at the command line with the

\f[CB]\-storetype\f[R] option.

.PP

If you don\[aq]t explicitly specify a keystore type, then the tools

choose a keystore implementation based on the value of the

\f[CB]keystore.type\f[R] property specified in the security properties

file.

The security properties file is called \f[CB]java.security\f[R], and it

resides in the JDK security properties directory,

\f[CB]java.home/conf/security\f[R].

.PP

Each tool gets the \f[CB]keystore.type\f[R] value and then examines all

the installed providers until it finds one that implements keystores of

that type.

It then uses the keystore implementation from that provider.

.PP

The \f[CB]KeyStore\f[R] class defines a static method named

\f[CB]getDefaultType\f[R] that lets applications retrieve the value of the

\f[CB]keystore.type\f[R] property.

The following line of code creates an instance of the default keystore

type as specified in the \f[CB]keystore.type\f[R] property:

.RS

.PP

\f[CB]KeyStore\ keyStore\ =\ KeyStore.getInstance(KeyStore.getDefaultType());\f[R]

.RE

.PP

The default keystore type is \f[CB]pkcs12\f[R], which is a cross platform

keystore based on the RSA PKCS12 Personal Information Exchange Syntax

Standard.

This is specified by the following line in the security properties file:

.RS

.PP

\f[CB]keystore.type=pkcs12\f[R]

.RE

.PP

Case doesn\[aq]t matter in keystore type designations.

For example, \f[CB]JKS\f[R] is the same as \f[CB]jks\f[R].

.PP

To have the tools utilize a keystore implementation other than the

default, you can change that line to specify a different keystore type.

For example, if you want to use the Oracle\[aq]s \f[CB]jks\f[R] keystore

implementation, then change the line to the following:

.RS

.PP

\f[CB]keystore.type=jks\f[R]

.RE

.SH SUPPORTED ALGORITHMS

.PP

By default, the \f[CB]jarsigner\f[R] command signs a JAR file using one of

the following algorithms files depending on the type and size of the

private key:

.PP

.TS

tab(@);

l l l.

T{

keyalg

T}@T{

keysize

T}@T{

default sigalg

T}

_

T{

DSA

T}@T{

any size

T}@T{

SHA256withDSA

T}

T{

RSA \ \ \ 

T}@T{

<= 3072

T}@T{

SHA256withRSA

T}

T{

T}@T{

<= 7680

T}@T{

SHA384withRSA

T}

T{

T}@T{

> 7680

T}@T{

SHA512withRSA

T}

T{

EC

T}@T{

< 384

T}@T{

SHA256withECDSA

T}

T{

T}@T{

< 512

T}@T{

SHA384withECDSA

T}

T{

T}@T{

= 512

T}@T{

SHA512withECDSA

T}

.TE

.PP

These default signature algorithms can be overridden by using the

\f[CB]\-sigalg\f[R] option.

.PP

Signed JAR file algorithms are checked against the

\f[CB]jdk.jar.disabledAlgorithms\f[R] security property during

verification (\f[CB]\-verify\f[R]).

If the JAR file was signed with any algorithms that are disabled, it

will be treated as an unsigned JAR file.

For detailed verification output, include

\f[CB]\-J\-Djava.security.debug=jar\f[R].

The default value for the \f[CB]jdk.jar.disabledAlgorithms\f[R] security

property is defined in the \f[CB]java.security\f[R] file (located in the

JRE\[aq]s \f[CB]$JAVA_HOME/conf/security\f[R] directory).

.PP

\f[B]Note:\f[R]

.PP

In order to improve out of the box security, default key size and

signature algorithm names are periodically updated to stronger values

with each release of the JDK.

If interoperability with older releases of the JDK is important, please

make sure the defaults are supported by those releases, or alternatively

use the \f[CB]\-sigalg\f[R] option to override the default values at your

own risk.

.SH THE SIGNED JAR FILE

.PP

When the \f[CB]jarsigner\f[R] command 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:

.IP \[bu] 2

A signature file with an \f[CB]\&.SF\f[R] extension

.IP \[bu] 2

A signature block file with a \f[CB]\&.DSA\f[R], \f[CB]\&.RSA\f[R], or

\f[CB]\&.EC\f[R] extension

.PP

The base file names for these two files come from the value of the

\f[CB]\-sigfile\f[R] option.

For example, when the option is \f[CB]\-sigfile\ MKSIGN\f[R], the files

are named \f[CB]MKSIGN.SF\f[R] and \f[CB]MKSIGN.DSA\f[R]

.PP

If no \f[CB]\-sigfile\f[R] option appears on the command line, then the

base file name for the \f[CB]\&.SF\f[R] and \f[CB]\&.DSA\f[R] files is the

first 8 characters of the alias name specified on the command line, all

converted to uppercase.

If the alias name has fewer than 8 characters, then the full alias name

is used.

If the alias name contains any characters that aren\[aq]t allowed in a

signature file name, then each such character is converted to an

underscore (_) character in forming the file name.

Valid characters include letters, digits, underscores, and hyphens.

.SH SIGNATURE FILE

.PP

A signature file (\f[CB]\&.SF\f[R] file) looks similar to the manifest

file that is always included in a JAR file when the \f[CB]jarsigner\f[R]

command is used to sign the file.

For each source file included in the JAR file, the \f[CB]\&.SF\f[R] file

has two lines, such as in the manifest file, that list the following:

.IP \[bu] 2

File name

.IP \[bu] 2

Name of the digest algorithm (SHA)

.IP \[bu] 2

SHA digest value

.PP

\f[B]Note:\f[R]

.PP

The name of the digest algorithm (SHA) and the SHA digest value are on

the same line.

.PP

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 \f[CB]\&.SF\f[R] file, the digest value for a specified source file

is the hash of the two lines in the manifest file for the source file.

.PP

The signature file, by default, includes a header with a hash of the

whole manifest file.

The header also contains a hash of the manifest header.

The presence of the header enables verification optimization.

See \f[B]JAR File Verification\f[R].

.SH SIGNATURE BLOCK FILE

.PP

The \f[CB]\&.SF\f[R] file is signed and the signature is placed in the

signature block file.

This file also contains, encoded inside it, the certificate or

certificate chain from the keystore that authenticates the public key

corresponding to the private key used for signing.

The file has the extension \f[CB]\&.DSA\f[R], \f[CB]\&.RSA\f[R], or

\f[CB]\&.EC\f[R], depending on the digest algorithm used.

.SH SIGNATURE TIME STAMP

.PP

The \f[CB]jarsigner\f[R] command used with the following options generates

and stores a signature time stamp when signing a JAR file:

.IP \[bu] 2

\f[CB]\-tsa\f[R] \f[I]url\f[R]

.IP \[bu] 2

\f[CB]\-tsacert\f[R] \f[I]alias\f[R]

.IP \[bu] 2

\f[CB]\-tsapolicyid\f[R] \f[I]policyid\f[R]

.IP \[bu] 2

\f[CB]\-tsadigestalg\f[R] \f[I]algorithm\f[R]

.PP

See \f[B]Options for jarsigner\f[R].

.SH JAR FILE VERIFICATION

.PP

A successful JAR file verification occurs when the signatures are valid,

and none of the files that were in the JAR file when the signatures were

generated have changed since then.

JAR file verification involves the following steps:

.IP "1." 3

Verify the signature of the \f[CB]\&.SF\f[R] file.

.RS 4

.PP

The verification ensures that the signature stored in each signature

block (\f[CB]\&.DSA\f[R]) file was generated using the private key

corresponding to the public key whose certificate (or certificate chain)

also appears in the \f[CB]\&.DSA\f[R] file.

It also ensures that the signature is a valid signature of the

corresponding signature (\f[CB]\&.SF\f[R]) file, and thus the

\f[CB]\&.SF\f[R] file wasn\[aq]t tampered with.

.RE

.IP "2." 3

Verify the digest listed in each entry in the \f[CB]\&.SF\f[R] file with

each corresponding section in the manifest.

.RS 4

.PP

The \f[CB]\&.SF\f[R] file by default includes a header that contains a

hash of the entire manifest file.

When the header is present, the verification can check to see whether or

not the hash in the header matches the hash of the manifest file.

If there is a match, then verification proceeds to the next step.

.PP

If there is no match, then a less optimized verification is required to

ensure that the hash in each source file information section in the

\f[CB]\&.SF\f[R] file equals the hash of its corresponding section in the

manifest file.

See Signature File.

.PP

One reason the hash of the manifest file that is stored in the

\f[CB]\&.SF\f[R] file header might not equal the hash of the current

manifest file is that one or more files were added to the JAR file (with

the \f[CB]jar\f[R] tool) after the signature and \f[CB]\&.SF\f[R] file were

generated.

When the \f[CB]jar\f[R] tool is used to add files, the manifest file is