| .\" Copyright (c) 1998, 2021, 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. |
| .\" |
| .\"t |
| .\" Automatically generated by Pandoc 2.3.1 |
| .\" |
| .TH "JARSIGNER" "1" "2021" "JDK 17" "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. |
| During validation, it checks the revocation status of each certificate |
| in the signer\[aq]s certificate chain when the \f[CB]\-revCheck\f[R] |
| option is specified. |
| 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]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 and block file extensions depending on the type |
| and size of the private key: |
| .PP |
| .TS |
| tab(@); |
| l l l l. |
| T{ |
| keyalg |
| T}@T{ |
| keysize |
| T}@T{ |
| default sigalg |
| T}@T{ |
| block file extension |
| T} |
| _ |
| T{ |
| DSA |
| T}@T{ |
| any size |
| T}@T{ |
| SHA256withDSA |
| T}@T{ |
| \&.DSA |
| T} |
| T{ |
| RSA |
| T}@T{ |
| <= 3072 |
| T}@T{ |
| SHA256withRSA |
| T}@T{ |
| \&.RSA |
| T} |
| T{ |
| T}@T{ |
| <= 7680 |
| T}@T{ |
| SHA384withRSA |
| T}@T{ |
| T} |
| T{ |
| T}@T{ |
| > 7680 |
| T}@T{ |
| SHA512withRSA |
| T}@T{ |
| T} |
| T{ |
| EC |
| T}@T{ |
| < 384 |
| T}@T{ |
| SHA256withECDSA |
| T}@T{ |
| \&.EC |
| T} |
| T{ |
| T}@T{ |
| < 512 |
| T}@T{ |
| SHA384withECDSA |
| T}@T{ |
| T} |
| T{ |
| T}@T{ |
| = 512 |
| T}@T{ |
| SHA512withECDSA |
| T}@T{ |
| T} |
| T{ |
| RSASSA\-PSS |
| T}@T{ |
| <= 3072 |
| T}@T{ |
| RSASSA\-PSS (with SHA\-256) |
| T}@T{ |
| \&.RSA |
| T} |
| T{ |
| T}@T{ |
| <= 7680 |
| T}@T{ |
| RSASSA\-PSS (with SHA\-384) |
| T}@T{ |
| T} |
| T{ |
| T}@T{ |
| > 7680 |
| T}@T{ |
| RSASSA\-PSS (with SHA\-512) |
| T}@T{ |
| T} |
| T{ |
| EdDSA |
| T}@T{ |
| 255 |
| T}@T{ |
| Ed25519 |
| T}@T{ |
| \&.EC |
| T} |
| T{ |
| T}@T{ |
| 448 |
| T}@T{ |
| Ed448 |
| T}@T{ |
| T} |
| .TE |
| .IP \[bu] 2 |
| If an RSASSA\-PSS key is encoded with parameters, then jarsigner will |
| use the same parameters in the signature. |
| Otherwise, jarsigner will use parameters that are determined by the size |
| of the key as specified in the table above. |
| For example, an 3072\-bit RSASSA\-PSS key will use RSASSA\-PSS as the |
| signature algorithm and SHA\-256 as the hash and MGF1 algorithms. |
| .PP |
| These default signature algorithms can be overridden by using the |
| \f[CB]\-sigalg\f[R] option. |
| .PP |
| The \f[CB]jarsigner\f[R] command uses the |
| \f[CB]jdk.jar.disabledAlgorithms\f[R] and |
| \f[CB]jdk.security.legacyAlgorithms\f[R] security properties to determine |
| which algorithms are considered a security risk. |
| If the JAR file was signed with any algorithms that are disabled, it |
| will be treated as an unsigned JAR file. |
| If the JAR file was signed with any legacy algorithms, it will be |
| treated as signed with an informational warning to inform users that the |
| legacy algorithm will be disabled in a future update. |
| For detailed verification output, include |
| \f[CB]\-J\-Djava.security.debug=jar\f[R]. |
| The \f[CB]jdk.jar.disabledAlgorithms\f[R] and |
| \f[CB]jdk.security.legacyAlgorithms\f[R] security properties are defined |
| in the \f[CB]java.security\f[R] file (located in the JDK\[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.RSA\f[R]. |
| In this document, we assume the signer always uses an RSA key. |
| .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 the signature block 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 key algorithm used. |
| See the table in \f[B]Supported Algorithms\f[R]. |
| .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 file was generated using the private key corresponding to the |
| public key whose certificate (or certificate chain) also appears in the |
| signature block 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 it might contain sections for newly added files |
| after the file was signed. |
| For example, suppose one or more files were added to the signed JAR file |
| (using the \f[CB]jar\f[R] tool) that already contains a signature and a |
| \f[CB]\&.SF\f[R] file. |
| If the JAR file is signed again by a different signer, then the manifest |
| file is changed (sections are added to it for the new files by the |
| \f[CB]jarsigner\f[R] tool) and a new \f[CB]\&.SF\f[R] file is created, but |
| the original \f[CB]\&.SF\f[R] file is unchanged. |
| A verification is still considered successful if none of the files that |
| were in the JAR file when the original signature was generated have been |
| changed since then. |
| This is because the hashes in the non\-header sections of the |
| \f[CB]\&.SF\f[R] file equal the hashes of the corresponding sections in |
| the manifest file. |
| .RE |
| .IP "3." 3 |
| Read each file in the JAR file that has an entry in the \f[CB]\&.SF\f[R] |
| file. |
| While reading, compute the file\[aq]s digest and compare the result with |
| the digest for this file in the manifest section. |
| The digests should be the same or verification fails. |
| .RS 4 |
| .PP |
| If any serious verification failures occur during the verification |
| process, then the process is stopped and a security exception is thrown. |
| The \f[CB]jarsigner\f[R] command catches and displays the exception. |
| .RE |
| .IP "4." 3 |
| Check for disabled algorithm usage. |
| See \f[B]Supported Algorithms\f[R]. |
| .PP |
| \f[B]Note:\f[R] |
| .PP |
| You should read any addition warnings (or errors if you specified the |
| \f[CB]\-strict\f[R] option), as well as the content of the certificate (by |
| specifying the \f[CB]\-verbose\f[R] and \f[CB]\-certs\f[R] options) to |
| determine if the signature can be trusted. |
| .SH MULTIPLE SIGNATURES FOR A JAR FILE |
| .PP |
| A JAR file can be signed by multiple people by running the |
| \f[CB]jarsigner\f[R] command on the file multiple times and specifying the |
| alias for a different person each time, as follows: |
| .IP |
| .nf |
| \f[CB] |
| jarsigner\ myBundle.jar\ susan |
| jarsigner\ myBundle.jar\ kevin |
| \f[R] |
| .fi |
| .PP |
| When a JAR file is signed multiple times, there are multiple |
| \f[CB]\&.SF\f[R] and signature block files in the resulting JAR file, one |
| pair for each signature. |
| In the previous example, the output JAR file includes files with the |
| following names: |
| .IP |
| .nf |
| \f[CB] |
| SUSAN.SF |
| SUSAN.RSA |
| KEVIN.SF |
| KEVIN.RSA |
| \f[R] |
| .fi |
| .SH OPTIONS FOR JARSIGNER |
| .PP |
| The following sections describe the options for the \f[CB]jarsigner\f[R]. |
| Be aware of the following standards: |
| .IP \[bu] 2 |
| All option names are preceded by a hyphen sign (\-). |
| .IP \[bu] 2 |
| The options can be provided in any order. |
| .IP \[bu] 2 |
| Items that are in italics or underlined (option values) represent the |
| actual values that must be supplied. |
| .IP \[bu] 2 |
| The \f[CB]\-storepass\f[R], \f[CB]\-keypass\f[R], \f[CB]\-sigfile\f[R], |
| \f[CB]\-sigalg\f[R], \f[CB]\-digestalg\f[R], \f[CB]\-signedjar\f[R], and |
| TSA\-related options are only relevant when signing a JAR file; they |
| aren\[aq]t relevant when verifying a signed JAR file. |
| The \f[CB]\-keystore\f[R] option is relevant for signing and verifying a |
| JAR file. |
| In addition, aliases are specified when signing and verifying a JAR |
| file. |
| .TP |
| .B \f[CB]\-keystore\f[R] \f[I]url\f[R] |
| Specifies the URL that tells the keystore location. |
| This defaults to the file \f[CB]\&.keystore\f[R] in the user\[aq]s home |
| directory, as determined by the \f[CB]user.home\f[R] system property. |
| .RS |
| .PP |
| A keystore is required when signing. |
| You must explicitly specify a keystore when the default keystore |
| doesn\[aq]t exist or if you want to use one other than the default. |
| .PP |
| A keystore isn\[aq]t required when verifying, but if one is specified or |
| the default exists and the \f[CB]\-verbose\f[R] option was also specified, |
| then additional information is output regarding whether or not any of |
| the certificates used to verify the JAR file are contained in that |
| keystore. |
| .PP |
| The \f[CB]\-keystore\f[R] argument can be a file name and path |
| specification rather than a URL, in which case it is treated the same as |
| a file: URL, for example, the following are equivalent: |
| .IP \[bu] 2 |
| \f[CB]\-keystore\f[R] \f[I]filePathAndName\f[R] |
| .IP \[bu] 2 |
| \f[CB]\-keystore\ file:\f[R]\f[I]filePathAndName\f[R] |
| .PP |
| If the Sun PKCS #11 provider was configured in the |
| \f[CB]java.security\f[R] security properties file (located in the |
| JDK\[aq]s \f[CB]$JAVA_HOME/conf/security\f[R] directory), then the |
| \f[CB]keytool\f[R] and \f[CB]jarsigner\f[R] tools can operate on the PKCS |
| #11 token by specifying these options: |
| .RS |
| .PP |
| \f[CB]\-keystore\ NONE\ \-storetype\ PKCS11\f[R] |
| .RE |
| .PP |
| For example, the following command lists the contents of the configured |
| PKCS#11 token: |
| .RS |
| .PP |
| \f[CB]keytool\ \-keystore\ NONE\ \-storetype\ PKCS11\ \-list\f[R] |
| .RE |
| .RE |
| .TP |
| .B \f[CB]\-storepass\f[R] [\f[CB]:env\f[R] | \f[CB]:file\f[R]] \f[I]argument\f[R] |
| Specifies the password that is required to access the keystore. |
| This is only needed when signing (not verifying) a JAR file. |
| In that case, if a \f[CB]\-storepass\f[R] option isn\[aq]t provided at the |
| command line, then the user is prompted for the password. |
| .RS |
| .PP |
| If the modifier \f[CB]env\f[R] or \f[CB]file\f[R] isn\[aq]t specified, then |
| the password has the value \f[CB]argument\f[R]. |
| Otherwise, the password is retrieved as follows: |
| .IP \[bu] 2 |
| \f[CB]env\f[R]: Retrieve the password from the environment variable named |
| \f[I]argument\f[R]. |
| .IP \[bu] 2 |
| \f[CB]file\f[R]: Retrieve the password from the file named |
| \f[I]argument\f[R]. |
| .PP |
| \f[B]Note:\f[R] |
| .PP |
| The password shouldn\[aq]t be specified on the command line or in a |
| script unless it is for testing purposes, or you are on a secure system. |
| .RE |
| .TP |
| .B \f[CB]\-storetype\f[R] \f[I]storetype\f[R] |
| Specifies the type of keystore to be instantiated. |
| The default keystore type is the one that is specified as the value of |
| the \f[CB]keystore.type\f[R] property in the security properties file, |
| which is returned by the static \f[CB]getDefaultType\f[R] method in |
| \f[CB]java.security.KeyStore\f[R]. |
| .RS |
| .PP |
| The PIN for a PKCS #11 token can also be specified with the |
| \f[CB]\-storepass\f[R] option. |
| If none is specified, then the \f[CB]keytool\f[R] and \f[CB]jarsigner\f[R] |
| commands 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 \f[CB]\-protected\f[R] option |
| must be specified and no password options can be specified. |
| .RE |
| .TP |
| .B \f[CB]\-keypass\f[R] [\f[CB]:env\f[R] | \f[CB]:file\f[R]] \f[I]argument\f[R] \f[CB]\-certchain\f[R] \f[I]file\f[R] |
| Specifies the password used to protect the private key of the keystore |
| entry addressed by the alias specified on the command line. |
| The password is required when using \f[CB]jarsigner\f[R] to sign a JAR |
| file. |
| If no password is provided on the command line, and the required |
| password is different from the store password, then the user is prompted |
| for it. |
| .RS |
| .PP |
| If the modifier \f[CB]env\f[R] or \f[CB]file\f[R] isn\[aq]t specified, then |
| the password has the value \f[CB]argument\f[R]. |
| Otherwise, the password is retrieved as follows: |
| .IP \[bu] 2 |
| \f[CB]env\f[R]: Retrieve the password from the environment variable named |
| \f[I]argument\f[R]. |
| .IP \[bu] 2 |
| \f[CB]file\f[R]: Retrieve the password from the file named |
| \f[I]argument\f[R]. |
| .PP |
| \f[B]Note:\f[R] |
| .PP |
| The password shouldn\[aq]t be specified on the command line or in a |
| script unless it is for testing purposes, or you are on a secure system. |
| .RE |
| .TP |
| .B \f[CB]\-certchain\f[R] \f[I]file\f[R] |
| Specifies the certificate chain to be used when the certificate chain |
| associated with the private key of the keystore entry that is addressed |
| by the alias specified on the command line isn\[aq]t complete. |
| This can happen when the keystore is located on a hardware token where |
| there isn\[aq]t enough capacity to hold a complete certificate chain. |
| The file can be a sequence of concatenated X.509 certificates, or a |
| single PKCS#7 formatted data block, either in binary encoding format or |
| in printable encoding format (also known as Base64 encoding) as defined |
| by \f[B]Internet RFC 1421 Certificate Encoding Standard\f[R] |
| [http://tools.ietf.org/html/rfc1421]. |
| .RS |
| .RE |
| .TP |
| .B \f[CB]\-sigfile\f[R] \f[I]file\f[R] |
| Specifies the base file name to be used for the generated \f[CB]\&.SF\f[R] |
| and signature block files. |
| For example, if file is \f[CB]DUKESIGN\f[R], then the generated |
| \f[CB]\&.SF\f[R] and signature block files are named \f[CB]DUKESIGN.SF\f[R] |
| and \f[CB]DUKESIGN.RSA\f[R], and placed in the \f[CB]META\-INF\f[R] |
| directory of the signed JAR file. |
| .RS |
| .PP |
| The characters in the file must come from the set |
| \f[CB]a\-zA\-Z0\-9_\-\f[R]. |
| Only letters, numbers, underscore, and hyphen characters are allowed. |
| All lowercase characters are converted to uppercase for the |
| \f[CB]\&.SF\f[R] and signature block file names. |
| .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 signature block files is 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, then the full alias name |
| is used. |
| If the alias name contains any characters that aren\[aq]t valid in a |
| signature file name, then each such character is converted to an |
| underscore (_) character to form the file name. |
| .RE |
| .TP |
| .B \f[CB]\-signedjar\f[R] \f[I]file\f[R] |
| Specifies the name of signed JAR file. |
| .RS |
| .RE |
| .TP |
| .B \f[CB]\-digestalg\f[R] \f[I]algorithm\f[R] |
| Specifies the name of the message digest algorithm to use when digesting |
| the entries of a JAR file. |
| .RS |
| .PP |
| For a list of standard message digest algorithm names, see Java Security |
| Standard Algorithm Names. |
| .PP |
| If this option isn\[aq]t specified, then \f[CB]SHA256\f[R] is used. |
| There must either be a statically installed provider supplying an |
| implementation of the specified algorithm or the user must specify one |
| with the \f[CB]\-addprovider\f[R] or \f[CB]\-providerClass\f[R] options; |
| otherwise, the command will not succeed. |
| .RE |
| .TP |
| .B \f[CB]\-sigalg\f[R] \f[I]algorithm\f[R] |
| Specifies the name of the signature algorithm to use to sign the JAR |
| file. |
| .RS |
| .PP |
| This algorithm must be compatible with the private key used to sign the |
| JAR file. |
| If this option isn\[aq]t specified, then use a default algorithm |
| matching the private key as described in the \f[B]Supported |
| Algorithms\f[R] section. |
| There must either be a statically installed provider supplying an |
| implementation of the specified algorithm or you must specify one with |
| the \f[CB]\-addprovider\f[R] or \f[CB]\-providerClass\f[R] option; |
| otherwise, the command doesn\[aq]t succeed. |
| .PP |
| For a list of standard message digest algorithm names, see Java Security |
| Standard Algorithm Names. |
| .RE |
| .TP |
| .B \f[CB]\-verify\f[R] |
| Verifies a signed JAR file. |
| .RS |
| .RE |
| .TP |
| .B \f[CB]\-verbose\f[R][\f[CB]:\f[R]\f[I]suboptions\f[R]] |
| When the \f[CB]\-verbose\f[R] option appears on the command line, it |
| indicates that the \f[CB]jarsigner\f[R] use the verbose mode when signing |
| or verifying with the suboptions determining how much information is |
| shown. |
| This causes the , which causes \f[CB]jarsigner\f[R] to output extra |
| information about the progress of the JAR signing or verification. |
| The \f[I]suboptions\f[R] can be \f[CB]all\f[R], \f[CB]grouped\f[R], or |
| \f[CB]summary\f[R]. |
| .RS |
| .PP |
| If the \f[CB]\-certs\f[R] option is also specified, then the default mode |
| (or suboption \f[CB]all\f[R]) displays each entry as it is being |
| processed, and after that, the certificate information for each signer |
| of the JAR file. |
| .PP |
| If the \f[CB]\-certs\f[R] and the \f[CB]\-verbose:grouped\f[R] suboptions |
| are specified, then entries with the same signer info are grouped and |
| displayed together with their certificate information. |
| .PP |
| If \f[CB]\-certs\f[R] and the \f[CB]\-verbose:summary\f[R] suboptions are |
| specified, then entries with the same signer information are grouped and |
| displayed together with their certificate information. |
| .PP |
| Details about each entry are summarized and displayed as \f[I]one entry |
| (and more)\f[R]. |
| See \f[B]Example of Verifying a Signed JAR File\f[R] and \f[B]Example of |
| Verification with Certificate Information\f[R]. |
| .RE |
| .TP |
| .B \f[CB]\-certs\f[R] |
| If the \f[CB]\-certs\f[R] option appears on the command line with the |
| \f[CB]\-verify\f[R] and \f[CB]\-verbose\f[R] options, then the output |
| includes certificate information for each signer of the JAR file. |
| This information includes the name of the type of certificate (stored in |
| the signature block file) that certifies the signer\[aq]s public key, |
| and if the certificate is an X.509 certificate (an instance of the |
| \f[CB]java.security.cert.X509Certificate\f[R]), then the distinguished |
| name of the signer. |
| .RS |
| .PP |
| The keystore is also examined. |
| If no keystore value is specified on the command line, then the default |
| keystore file (if any) is checked. |
| If the public key certificate for a signer matches an entry in the |
| keystore, then the alias name for the keystore entry for that signer is |
| displayed in parentheses. |
| .RE |
| .TP |
| .B \f[CB]\-revCheck\f[R] |
| This option enables revocation checking of certificates when signing or |
| verifying a JAR file. |
| The \f[CB]jarsigner\f[R] command attempts to make network connections to |
| fetch OCSP responses and CRLs if the \f[CB]\-revCheck\f[R] option is |
| specified on the command line. |
| Note that revocation checks are not enabled unless this option is |
| specified. |
| .RS |
| .RE |
| .TP |
| .B \f[CB]\-tsa\f[R] \f[I]url\f[R] |
| If \f[CB]\-tsa\ http://example.tsa.url\f[R] appears on the command line |
| when signing a JAR file then a time stamp is generated for the |
| signature. |
| The URL, \f[CB]http://example.tsa.url\f[R], identifies the location of the |
| Time Stamping Authority (TSA) and overrides any URL found with the |
| \f[CB]\-tsacert\f[R] option. |
| The \f[CB]\-tsa\f[R] option doesn\[aq]t require the TSA public key |
| certificate to be present in the keystore. |
| .RS |
| .PP |
| To generate the time stamp, \f[CB]jarsigner\f[R] communicates with the TSA |
| with the Time\-Stamp Protocol (TSP) defined in RFC 3161. |
| When successful, the time stamp token returned by the TSA is stored with |
| the signature in the signature block file. |
| .RE |
| .TP |
| .B \f[CB]\-tsacert\f[R] \f[I]alias\f[R] |
| When \f[CB]\-tsacert\f[R] \f[I]alias\f[R] appears on the command line when |
| signing a JAR file, a time stamp is generated for the signature. |
| The alias identifies the TSA public key certificate in the keystore that |
| is in effect. |
| The entry\[aq]s certificate is examined for a Subject Information Access |
| extension that contains a URL identifying the location of the TSA. |
| .RS |
| .PP |
| The TSA public key certificate must be present in the keystore when |
| using the \f[CB]\-tsacert\f[R] option. |
| .RE |
| .TP |
| .B \f[CB]\-tsapolicyid\f[R] \f[I]policyid\f[R] |
| Specifies the object identifier (OID) that identifies the policy ID to |
| be sent to the TSA server. |
| If this option isn\[aq]t specified, no policy ID is sent and the TSA |
| server will choose a default policy ID. |
| .RS |
| .PP |
| Object identifiers are defined by X.696, which is an ITU |
| Telecommunication Standardization Sector (ITU\-T) standard. |
| These identifiers are typically period\-separated sets of non\-negative |
| digits like \f[CB]1.2.3.4\f[R], for example. |
| .RE |
| .TP |
| .B \f[CB]\-tsadigestalg\f[R] \f[I]algorithm\f[R] |
| Specifies the message digest algorithm that is used to generate the |
| message imprint to be sent to the TSA server. |
| If this option isn\[aq]t specified, SHA\-256 will be used. |
| .RS |
| .PP |
| See \f[B]Supported Algorithms\f[R]. |
| .PP |
| For a list of standard message digest algorithm names, see Java Security |
| Standard Algorithm Names. |
| .RE |
| .TP |
| .B \f[CB]\-internalsf\f[R] |
| In the past, the signature block file generated when a JAR file was |
| signed included a complete encoded copy of the \f[CB]\&.SF\f[R] file |
| (signature file) also generated. |
| This behavior has been changed. |
| To reduce the overall size of the output JAR file, the signature block |
| file by default doesn\[aq]t contain a copy of the \f[CB]\&.SF\f[R] file |
| anymore. |
| If \f[CB]\-internalsf\f[R] appears on the command line, then the old |
| behavior is utilized. |
| This option is useful for testing. |
| In practice, don\[aq]t use the \f[CB]\-internalsf\f[R] option because it |
| incurs higher overhead. |
| .RS |
| .RE |
| .TP |
| .B \f[CB]\-sectionsonly\f[R] |
| If the \f[CB]\-sectionsonly\f[R] option appears on the command line, then |
| the \f[CB]\&.SF\f[R] file (signature file) generated when a JAR file is |
| signed doesn\[aq]t include a header that contains a hash of the whole |
| manifest file. |
| It contains only the information and hashes related to each individual |
| source file included in the JAR file. |
| See Signature File. |
| .RS |
| .PP |
| By default, this header is added, as an optimization. |
| When the header is present, whenever the JAR file is verified, the |
| verification can first check to see whether the hash in the header |
| matches the hash of the whole manifest file. |
| When there is a match, verification proceeds to the next step. |
| When there is no match, it is necessary to do a less optimized |
| verification 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 \f[B]JAR File Verification\f[R]. |
| .PP |
| The \f[CB]\-sectionsonly\f[R] option is primarily used for testing. |
| It shouldn\[aq]t be used other than for testing because using it incurs |
| higher overhead. |
| .RE |
| .TP |
| .B \f[CB]\-protected\f[R] |
| Values can be either \f[CB]true\f[R] or \f[CB]false\f[R]. |
| Specify \f[CB]true\f[R] when a password must be specified through a |
| protected authentication path such as a dedicated PIN reader. |
| .RS |
| .RE |
| .TP |
| .B \f[CB]\-providerName\f[R] \f[I]providerName\f[R] |
| If more than one provider was configured in the \f[CB]java.security\f[R] |
| security properties file, then you can use the \f[CB]\-providerName\f[R] |
| option to target a specific provider instance. |
| The argument to this option is the name of the provider. |
| .RS |
| .PP |
| For the Oracle PKCS #11 provider, \f[I]providerName\f[R] is of the form |
| \f[CB]SunPKCS11\-\f[R]\f[I]TokenName\f[R], where \f[I]TokenName\f[R] is the |
| name suffix that the provider instance has been configured with, as |
| detailed in the configuration attributes table. |
| For example, the following command lists the contents of the |
| \f[CB]PKCS\ #11\f[R] keystore provider instance with name suffix |
| \f[CB]SmartCard\f[R]: |
| .RS |
| .PP |
| \f[CB]jarsigner\ \-keystore\ NONE\ \-storetype\ PKCS11\ \-providerName\ SunPKCS11\-SmartCard\ \-list\f[R] |
| .RE |
| .RE |
| .TP |
| .B \f[CB]\-addprovider\f[R] \f[I]name\f[R] [\f[CB]\-providerArg\f[R] \f[I]arg\f[R]] |
| Adds a security provider by name (such as SunPKCS11) and an optional |
| configure argument. |
| The value of the security provider is the name of a security provider |
| that is defined in a module. |
| .RS |
| .PP |
| Used with the \f[CB]\-providerArg\ ConfigFilePath\f[R] option, the |
| \f[CB]keytool\f[R] and \f[CB]jarsigner\f[R] tools install the provider |
| dynamically and use \f[CB]ConfigFilePath\f[R] for the path to the token |
| configuration file. |
| The following example shows a command to list a \f[CB]PKCS\ #11\f[R] |
| keystore when the Oracle PKCS #11 provider wasn\[aq]t configured in the |
| security properties file. |
| .RS |
| .PP |
| \f[CB]jarsigner\ \-keystore\ NONE\ \-storetype\ PKCS11\ \-addprovider\ SunPKCS11\ \-providerArg\ /mydir1/mydir2/token.config\f[R] |
| .RE |
| .RE |
| .TP |
| .B \f[CB]\-providerClass\f[R] \f[I]provider\-class\-name\f[R] [\f[CB]\-providerArg\f[R] \f[I]arg\f[R]] |
| Used to specify the name of cryptographic service provider\[aq]s master |
| class file when the service provider isn\[aq]t listed in the |
| \f[CB]java.security\f[R] security properties file. |
| Adds a security provider by fully\-qualified class name and an optional |
| configure argument. |
| .RS |
| .PP |
| \f[B]Note:\f[R] |
| .PP |
| The preferred way to load PKCS11 is by using modules. |
| See \f[CB]\-addprovider\f[R]. |
| .RE |
| .TP |
| .B \f[CB]\-J\f[R]\f[I]javaoption\f[R] |
| Passes through the specified \f[I]javaoption\f[R] string directly to the |
| Java interpreter. |
| The \f[CB]jarsigner\f[R] command is a wrapper around the interpreter. |
| This option shouldn\[aq]t contain any spaces. |
| It is useful for adjusting the execution environment or memory usage. |
| For a list of possible interpreter options, type \f[CB]java\ \-h\f[R] or |
| \f[CB]java\ \-X\f[R] at the command line. |
| .RS |
| .RE |
| .TP |
| .B \f[CB]\-strict\f[R] |
| During the signing or verifying process, the command may issue warning |
| messages. |
| If you specify this option, the exit code of the tool reflects the |
| severe warning messages that this command found. |
| See \f[B]Errors and Warnings\f[R]. |
| .RS |
| .RE |
| .TP |
| .B \f[CB]\-conf\f[R] \f[I]url\f[R] |
| Specifies a pre\-configured options file. |
| Read the \f[B]keytool documentation\f[R] for details. |
| The property keys supported are "jarsigner.all" for all actions, |
| "jarsigner.sign" for signing, and "jarsigner.verify" for verification. |
| \f[CB]jarsigner\f[R] arguments including the JAR file name and alias |
| name(s) cannot be set in this file. |
| .RS |
| .RE |
| .SH DEPRECATED OPTIONS |
| .PP |
| The following \f[CB]jarsigner\f[R] options are deprecated as of JDK 9 and |
| might be removed in a future JDK release. |
| .TP |
| .B \f[CB]\-altsigner\f[R] \f[I]class\f[R] |
| This option specifies an alternative signing mechanism. |
| The fully qualified class name identifies a class file that extends the |
| \f[CB]com.sun.jarsigner.ContentSigner\f[R] abstract class. |
| The path to this class file is defined by the \f[CB]\-altsignerpath\f[R] |
| option. |
| If the \f[CB]\-altsigner\f[R] option is used, then the \f[CB]jarsigner\f[R] |
| command uses the signing mechanism provided by the specified class. |
| Otherwise, the \f[CB]jarsigner\f[R] command uses its default signing |
| mechanism. |
| .RS |
| .PP |
| For example, to use the signing mechanism provided by a class named |
| \f[CB]com.sun.sun.jarsigner.AuthSigner\f[R], use the \f[CB]jarsigner\f[R] |
| option \f[CB]\-altsigner\ com.sun.jarsigner.AuthSigner\f[R]. |
| .RE |
| .TP |
| .B \f[CB]\-altsignerpath\f[R] \f[I]classpathlist\f[R] |
| Specifies the path to the class file and any JAR file it depends on. |
| The class file name is specified with the \f[CB]\-altsigner\f[R] option. |
| If the class file is in a JAR file, then this option specifies the path |
| to that JAR file. |
| .RS |
| .PP |
| An absolute path or a path relative to the current directory can be |
| specified. |
| If \f[I]classpathlist\f[R] contains multiple paths or JAR files, then |
| they should be separated with a: |
| .IP \[bu] 2 |
| Colon (\f[CB]:\f[R]) on Linux and macOS |
| .IP \[bu] 2 |
| Semicolon (\f[CB];\f[R]) on Windows |
| .PP |
| This option isn\[aq]t necessary when the class is already in the search |
| path. |
| .PP |
| The following example shows how to specify the path to a JAR file that |
| contains the class file. |
| The JAR file name is included. |
| .RS |
| .PP |
| \f[CB]\-altsignerpath\ /home/user/lib/authsigner.jar\f[R] |
| .RE |
| .PP |
| The following example shows how to specify the path to the JAR file that |
| contains the class file. |
| The JAR file name is omitted. |
| .RS |
| .PP |
| \f[CB]\-altsignerpath\ /home/user/classes/com/sun/tools/jarsigner/\f[R] |
| .RE |
| .RE |
| .SH ERRORS AND WARNINGS |
| .PP |
| During the signing or verifying process, the \f[CB]jarsigner\f[R] command |
| may issue various errors or warnings. |
| .PP |
| If there is a failure, the \f[CB]jarsigner\f[R] command exits with code 1. |
| If there is no failure, but there are one or more severe warnings, the |
| \f[CB]jarsigner\f[R] command exits with code 0 when the \f[CB]\-strict\f[R] |
| option is \f[B]not\f[R] specified, or exits with the OR\-value of the |
| warning codes when the \f[CB]\-strict\f[R] is specified. |
| If there is only informational warnings or no warning at all, the |
| command always exits with code 0. |
| .PP |
| For example, if a certificate used to sign an entry is expired and has a |
| KeyUsage extension that doesn\[aq]t allow it to sign a file, the |
| \f[CB]jarsigner\f[R] command exits with code 12 (=4+8) when the |
| \f[CB]\-strict\f[R] option is specified. |
| .PP |
| \f[B]Note:\f[R] Exit codes are reused because only the values from 0 to |
| 255 are legal on Linux and OS X. |
| .PP |
| The following sections describes the names, codes, and descriptions of |
| the errors and warnings that the \f[CB]jarsigner\f[R] command can issue. |
| .SH FAILURE |
| .PP |
| Reasons why the \f[CB]jarsigner\f[R] command fails include (but aren\[aq]t |
| limited to) a command line parsing error, the inability to find a |
| keypair to sign the JAR file, or the verification of a signed JAR fails. |
| .TP |
| .B failure |
| Code 1. |
| The signing or verifying fails. |
| .RS |
| .RE |
| .SH SEVERE WARNINGS |
| .PP |
| \f[B]Note:\f[R] |
| .PP |
| Severe warnings are reported as errors if you specify the |
| \f[CB]\-strict\f[R] option. |
| .PP |
| Reasons why the \f[CB]jarsigner\f[R] command issues a severe warning |
| include the certificate used to sign the JAR file has an error or the |
| signed JAR file has other problems. |
| .TP |
| .B hasExpiredCert |
| Code 4. |
| This JAR contains entries whose signer certificate has expired. |
| .RS |
| .RE |
| .TP |
| .B hasExpiredTsaCert |
| Code 4. |
| The timestamp has expired. |
| .RS |
| .RE |
| .TP |
| .B notYetValidCert |
| Code 4. |
| This JAR contains entries whose signer certificate isn\[aq]t yet valid. |
| .RS |
| .RE |
| .TP |
| .B chainNotValidated |
| Code 4. |
| This JAR contains entries whose certificate chain isn\[aq]t validated. |
| .RS |
| .RE |
| .TP |
| .B tsaChainNotValidated |
| Code 64. |
| The timestamp is invalid. |
| .RS |
| .RE |
| .TP |
| .B signerSelfSigned |
| Code 4. |
| This JAR contains entries whose signer certificate is self signed. |
| .RS |
| .RE |
| .TP |
| .B disabledAlg |
| Code 4. |
| An algorithm used is considered a security risk and is disabled. |
| .RS |
| .RE |
| .TP |
| .B badKeyUsage |
| Code 8. |
| This JAR contains entries whose signer certificate\[aq]s KeyUsage |
| extension doesn\[aq]t allow code signing. |
| .RS |
| .RE |
| .TP |
| .B badExtendedKeyUsage |
| Code 8. |
| This JAR contains entries whose signer certificate\[aq]s |
| ExtendedKeyUsage extension doesn\[aq]t allow code signing. |
| .RS |
| .RE |
| .TP |
| .B badNetscapeCertType |
| Code 8. |
| This JAR contains entries whose signer certificate\[aq]s |
| NetscapeCertType extension doesn\[aq]t allow code signing. |
| .RS |
| .RE |
| .TP |
| .B hasUnsignedEntry |
| Code 16. |
| This JAR contains unsigned entries which haven\[aq]t been |
| integrity\-checked. |
| .RS |
| .RE |
| .TP |
| .B notSignedByAlias |
| Code 32. |
| This JAR contains signed entries which aren\[aq]t signed by the |
| specified alias(es). |
| .RS |
| .RE |
| .TP |
| .B aliasNotInStore |
| Code 32. |
| This JAR contains signed entries that aren\[aq]t signed by alias in this |
| keystore. |
| .RS |
| .RE |
| .TP |
| .B tsaChainNotValidated |
| Code 64. |
| This JAR contains entries whose TSA certificate chain is invalid. |
| .RS |
| .RE |
| .SH INFORMATIONAL WARNINGS |
| .PP |
| Informational warnings include those that aren\[aq]t errors but regarded |
| as bad practice. |
| They don\[aq]t have a code. |
| .TP |
| .B extraAttributesDetected |
| The POSIX file permissions and/or symlink attributes are detected during |
| signing or verifying a JAR file. |
| The \f[CB]jarsigner\f[R] tool preserves these attributes in the newly |
| signed file but warns that these attributes are unsigned and not |
| protected by the signature. |
| .RS |
| .RE |
| .TP |
| .B hasExpiringCert |
| This JAR contains entries whose signer certificate expires within six |
| months. |
| .RS |
| .RE |
| .TP |
| .B hasExpiringTsaCert |
| The timestamp will expire within one year on \f[CB]YYYY\-MM\-DD\f[R]. |
| .RS |
| .RE |
| .TP |
| .B legacyAlg |
| An algorithm used is considered a security risk but not disabled. |
| .RS |
| .RE |
| .TP |
| .B noTimestamp |
| This JAR contains signatures that doesn\[aq]t include a timestamp. |
| Without a timestamp, users may not be able to validate this JAR file |
| after the signer certificate\[aq]s expiration date |
| (\f[CB]YYYY\-MM\-DD\f[R]) or after any future revocation date. |
| .RS |
| .RE |
| .SH EXAMPLE OF SIGNING A JAR FILE |
| .PP |
| Use the following command to sign \f[CB]bundle.jar\f[R] with the private |
| key of a user whose keystore alias is \f[CB]jane\f[R] in a keystore named |
| \f[CB]mystore\f[R] in the \f[CB]working\f[R] directory and name the signed |
| JAR file \f[CB]sbundle.jar\f[R]: |
| .RS |
| .PP |
| \f[CB]jarsigner\ \-keystore\ /working/mystore\ \-storepass\f[R] |
| \f[I]keystore_password\f[R] \f[CB]\-keypass\f[R] |
| \f[I]private_key_password\f[R] |
| \f[CB]\-signedjar\ sbundle.jar\ bundle.jar\ jane\f[R] |
| .RE |
| .PP |
| There is no \f[CB]\-sigfile\f[R] specified in the previous command so the |
| generated \f[CB]\&.SF\f[R] and signature block files to be placed in the |
| signed JAR file have default names based on the alias name. |
| They are named \f[CB]JANE.SF\f[R] and \f[CB]JANE.RSA\f[R]. |
| .PP |
| If you want to be prompted for the store password and the private key |
| password, then you could shorten the previous command to the following: |
| .RS |
| .PP |
| \f[CB]jarsigner\ \-keystore\ /working/mystore\ \-signedjar\ sbundle.jar\ bundle.jar\ jane\f[R] |
| .RE |
| .PP |
| If the \f[CB]keystore\f[R] is the default \f[CB]keystore\f[R] |
| (\f[CB]\&.keystore\f[R] in your home directory), then you don\[aq]t need |
| to specify a \f[CB]keystore\f[R], as follows: |
| .RS |
| .PP |
| \f[CB]jarsigner\ \-signedjar\ sbundle.jar\ bundle.jar\ jane\f[R] |
| .RE |
| .PP |
| If you want the signed JAR file to overwrite the input JAR file |
| (\f[CB]bundle.jar\f[R]), then you don\[aq]t need to specify a |
| \f[CB]\-signedjar\f[R] option, as follows: |
| .RS |
| .PP |
| \f[CB]jarsigner\ bundle.jar\ jane\f[R] |
| .RE |
| .SH EXAMPLE OF VERIFYING A SIGNED JAR FILE |
| .PP |
| To verify a signed JAR file to ensure that the signature is valid and |
| the JAR file wasn\[aq]t been tampered with, use a command such as the |
| following: |
| .RS |
| .PP |
| \f[CB]jarsigner\ \-verify\ ButtonDemo.jar\f[R] |
| .RE |
| .PP |
| When the verification is successful, \f[CB]jar\ verified\f[R] is |
| displayed. |
| Otherwise, an error message is displayed. |
| You can get more information when you use the \f[CB]\-verbose\f[R] option. |
| A sample use of \f[CB]jarsigner\f[R] with the \f[CB]\-verbose\f[R] option |
| follows: |
| .IP |
| .nf |
| \f[CB] |
| jarsigner\ \-verify\ \-verbose\ ButtonDemo.jar |
| |
| s\ \ \ \ \ \ \ 866\ Tue\ Sep\ 12\ 20:08:48\ EDT\ 2017\ META\-INF/MANIFEST.MF |
| \ \ \ \ \ \ \ \ 825\ Tue\ Sep\ 12\ 20:08:48\ EDT\ 2017\ META\-INF/ORACLE_C.SF |
| \ \ \ \ \ \ \ 7475\ Tue\ Sep\ 12\ 20:08:48\ EDT\ 2017\ META\-INF/ORACLE_C.RSA |
| \ \ \ \ \ \ \ \ \ \ 0\ Tue\ Sep\ 12\ 20:07:54\ EDT\ 2017\ META\-INF/ |
| \ \ \ \ \ \ \ \ \ \ 0\ Tue\ Sep\ 12\ 20:07:16\ EDT\ 2017\ components/ |
| \ \ \ \ \ \ \ \ \ \ 0\ Tue\ Sep\ 12\ 20:07:16\ EDT\ 2017\ components/images/ |
| sm\ \ \ \ \ \ 523\ Tue\ Sep\ 12\ 20:07:16\ EDT\ 2017\ components/ButtonDemo$1.class |
| sm\ \ \ \ \ 3440\ Tue\ Sep\ 12\ 20:07:16\ EDT\ 2017\ components/ButtonDemo.class |
| sm\ \ \ \ \ 2346\ Tue\ Sep\ 12\ 20:07:16\ EDT\ 2017\ components/ButtonDemo.jnlp |
| sm\ \ \ \ \ \ 172\ Tue\ Sep\ 12\ 20:07:16\ EDT\ 2017\ components/images/left.gif |
| sm\ \ \ \ \ \ 235\ Tue\ Sep\ 12\ 20:07:16\ EDT\ 2017\ components/images/middle.gif |
| sm\ \ \ \ \ \ 172\ Tue\ Sep\ 12\ 20:07:16\ EDT\ 2017\ components/images/right.gif |
| |
| \ \ s\ =\ signature\ was\ verified |
| \ \ m\ =\ entry\ is\ listed\ in\ manifest |
| \ \ k\ =\ at\ least\ one\ certificate\ was\ found\ in\ keystore |
| |
| \-\ Signed\ by\ "CN="Oracle\ America,\ Inc.",\ OU=Software\ Engineering,\ O="Oracle\ America,\ Inc.",\ L=Redwood\ City,\ ST=California,\ C=US" |
| \ \ \ \ Digest\ algorithm:\ SHA\-256 |
| \ \ \ \ Signature\ algorithm:\ SHA256withRSA,\ 2048\-bit\ key |
| \ \ Timestamped\ by\ "CN=Symantec\ Time\ Stamping\ Services\ Signer\ \-\ G4,\ O=Symantec\ Corporation,\ C=US"\ on\ Tue\ Sep\ 12\ 20:08:49\ UTC\ 2017 |
| \ \ \ \ Timestamp\ digest\ algorithm:\ SHA\-1 |
| \ \ \ \ Timestamp\ signature\ algorithm:\ SHA1withRSA,\ 2048\-bit\ key |
| |
| jar\ verified. |
| |
| The\ signer\ certificate\ expired\ on\ 2018\-02\-01.\ However,\ the\ JAR\ will\ be\ valid\ until\ the\ timestamp\ expires\ on\ 2020\-12\-29. |
| \f[R] |
| .fi |
| .SH EXAMPLE OF VERIFICATION WITH CERTIFICATE INFORMATION |
| .PP |
| If you specify the \f[CB]\-certs\f[R] option with the \f[CB]\-verify\f[R] |
| and \f[CB]\-verbose\f[R] options, then the output includes certificate |
| information for each signer of the JAR file. |
| The information includes the certificate type, the signer distinguished |
| name information (when it is an X.509 certificate), and in parentheses, |
| the keystore alias for the signer when the public key certificate in the |
| JAR file matches the one in a keystore entry, for example: |
| .IP |
| .nf |
| \f[CB] |
| jarsigner\ \-keystore\ $JAVA_HOME/lib/security/cacerts\ \-verify\ \-verbose\ \-certs\ ButtonDemo.jar |
| |
| s\ k\ \ \ \ \ 866\ Tue\ Sep\ 12\ 20:08:48\ EDT\ 2017\ META\-INF/MANIFEST.MF |
| |
| \ \ \ \ \ \ >>>\ Signer |
| \ \ \ \ \ \ X.509,\ CN="Oracle\ America,\ Inc.",\ OU=Software\ Engineering,\ O="Oracle\ America,\ Inc.",\ L=Redwood\ City,\ ST=California,\ C=US |
| \ \ \ \ \ \ [certificate\ is\ valid\ from\ 2017\-01\-30,\ 7:00\ PM\ to\ 2018\-02\-01,\ 6:59\ PM] |
| \ \ \ \ \ \ X.509,\ CN=Symantec\ Class\ 3\ SHA256\ Code\ Signing\ CA,\ OU=Symantec\ Trust\ Network,\ O=Symantec\ Corporation,\ C=US |
| \ \ \ \ \ \ [certificate\ is\ valid\ from\ 2013\-12\-09,\ 7:00\ PM\ to\ 2023\-12\-09,\ 6:59\ PM] |
| \ \ \ \ \ \ X.509,\ CN=VeriSign\ Class\ 3\ Public\ Primary\ Certification\ Authority\ \-\ G5,\ OU="(c)\ 2006\ VeriSign,\ Inc.\ \-\ For\ authorized\ use\ only",\ OU=VeriSign\ Trust\ Network,\ O="VeriSign,\ Inc.",\ C=US\ (verisignclass3g5ca\ [jdk]) |
| \ \ \ \ \ \ [trusted\ certificate] |
| \ \ \ \ \ \ >>>\ TSA |
| \ \ \ \ \ \ X.509,\ CN=Symantec\ Time\ Stamping\ Services\ Signer\ \-\ G4,\ O=Symantec\ Corporation,\ C=US |
| \ \ \ \ \ \ [certificate\ is\ valid\ from\ 2012\-10\-17,\ 8:00\ PM\ to\ 2020\-12\-29,\ 6:59\ PM] |
| \ \ \ \ \ \ X.509,\ CN=Symantec\ Time\ Stamping\ Services\ CA\ \-\ G2,\ O=Symantec\ Corporation,\ C=US |
| \ \ \ \ \ \ [certificate\ is\ valid\ from\ 2012\-12\-20,\ 7:00\ PM\ to\ 2020\-12\-30,\ 6:59\ PM] |
| |
| \ \ \ \ \ \ \ \ 825\ Tue\ Sep\ 12\ 20:08:48\ EDT\ 2017\ META\-INF/ORACLE_C.SF |
| \ \ \ \ \ \ \ 7475\ Tue\ Sep\ 12\ 20:08:48\ EDT\ 2017\ META\-INF/ORACLE_C.RSA |
| \ \ \ \ \ \ \ \ \ \ 0\ Tue\ Sep\ 12\ 20:07:54\ EDT\ 2017\ META\-INF/ |
| \ \ \ \ \ \ \ \ \ \ 0\ Tue\ Sep\ 12\ 20:07:16\ EDT\ 2017\ components/ |
| \ \ \ \ \ \ \ \ \ \ 0\ Tue\ Sep\ 12\ 20:07:16\ EDT\ 2017\ components/images/ |
| smk\ \ \ \ \ 523\ Tue\ Sep\ 12\ 20:07:16\ EDT\ 2017\ components/ButtonDemo$1.class |
| |
| \ \ \ \ \ \ [entry\ was\ signed\ on\ 2017\-09\-12,\ 4:08\ PM] |
| \ \ \ \ \ \ >>>\ Signer |
| \ \ \ \ \ \ X.509,\ CN="Oracle\ America,\ Inc.",\ OU=Software\ Engineering,\ O="Oracle\ America,\ Inc.",\ L=Redwood\ City,\ ST=California,\ C=US |
| \ \ \ \ \ \ [certificate\ is\ valid\ from\ 2017\-01\-30,\ 7:00\ PM\ to\ 2018\-02\-01,\ 6:59\ PM] |
| \ \ \ \ \ \ X.509,\ CN=Symantec\ Class\ 3\ SHA256\ Code\ Signing\ CA,\ OU=Symantec\ Trust\ Network,\ O=Symantec\ Corporation,\ C=US |
| \ \ \ \ \ \ [certificate\ is\ valid\ from\ 2013\-12\-09,\ 7:00\ PM\ to\ 2023\-12\-09,\ 6:59\ PM] |
| \ \ \ \ \ \ X.509,\ CN=VeriSign\ Class\ 3\ Public\ Primary\ Certification\ Authority\ \-\ G5,\ OU="(c)\ 2006\ VeriSign,\ Inc.\ \-\ For\ authorized\ use\ only",\ OU=VeriSign\ Trust\ Network,\ O="VeriSign,\ Inc.",\ C=US\ (verisignclass3g5ca\ [jdk]) |
| \ \ \ \ \ \ [trusted\ certificate] |
| \ \ \ \ \ \ >>>\ TSA |
| \ \ \ \ \ \ X.509,\ CN=Symantec\ Time\ Stamping\ Services\ Signer\ \-\ G4,\ O=Symantec\ Corporation,\ C=US |
| \ \ \ \ \ \ [certificate\ is\ valid\ from\ 2012\-10\-17,\ 8:00\ PM\ to\ 2020\-12\-29,\ 6:59\ PM] |
| \ \ \ \ \ \ X.509,\ CN=Symantec\ Time\ Stamping\ Services\ CA\ \-\ G2,\ O=Symantec\ Corporation,\ C=US |
| \ \ \ \ \ \ [certificate\ is\ valid\ from\ 2012\-12\-20,\ 7:00\ PM\ to\ 2020\-12\-30,\ 6:59\ PM] |
| |
| smk\ \ \ \ 3440\ Tue\ Sep\ 12\ 20:07:16\ EDT\ 2017\ components/ButtonDemo.class |
| \&... |
| smk\ \ \ \ 2346\ Tue\ Sep\ 12\ 20:07:16\ EDT\ 2017\ components/ButtonDemo.jnlp |
| \&... |
| smk\ \ \ \ \ 172\ Tue\ Sep\ 12\ 20:07:16\ EDT\ 2017\ components/images/left.gif |
| \&... |
| smk\ \ \ \ \ 235\ Tue\ Sep\ 12\ 20:07:16\ EDT\ 2017\ components/images/middle.gif |
| \&... |
| smk\ \ \ \ \ 172\ Tue\ Sep\ 12\ 20:07:16\ EDT\ 2017\ components/images/right.gif |
| \&... |
| |
| \ \ s\ =\ signature\ was\ verified |
| \ \ m\ =\ entry\ is\ listed\ in\ manifest |
| \ \ k\ =\ at\ least\ one\ certificate\ was\ found\ in\ keystore |
| |
| \-\ Signed\ by\ "CN="Oracle\ America,\ Inc.",\ OU=Software\ Engineering,\ O="Oracle\ America,\ Inc.",\ L=Redwood\ City,\ ST=California,\ C=US" |
| \ \ \ \ Digest\ algorithm:\ SHA\-256 |
| \ \ \ \ Signature\ algorithm:\ SHA256withRSA,\ 2048\-bit\ key |
| \ \ Timestamped\ by\ "CN=Symantec\ Time\ Stamping\ Services\ Signer\ \-\ G4,\ O=Symantec\ Corporation,\ C=US"\ on\ Tue\ Sep\ 12\ 20:08:49\ UTC\ 2017 |
| \ \ \ \ Timestamp\ digest\ algorithm:\ SHA\-1 |
| \ \ \ \ Timestamp\ signature\ algorithm:\ SHA1withRSA,\ 2048\-bit\ key |
| |
| jar\ verified. |
| |
| The\ signer\ certificate\ expired\ on\ 2018\-02\-01.\ However,\ the\ JAR\ will\ be\ valid\ until\ the\ timestamp\ expires\ on\ 2020\-12\-29. |
| \f[R] |
| .fi |
| .PP |
| If the certificate for a signer isn\[aq]t an X.509 certificate, then |
| 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 |
| \f[CB]bob\f[R], then you would get: \f[CB]PGP,\ (bob)\f[R]. |