1jarsigner(1) General Commands Manual jarsigner(1)
2
6 jarsigner - JAR Signing and Verification Tool
7 Generates signatures for Java ARchive (JAR) files, and verifies the
9 signatures of signed JAR files.
10
12 jarsigner [ options ] jar-file alias
13 jarsigner -verify [ options ] jar-file
14
17 The jarsigner tool is used for two purposes:
18 1. to sign Java ARchive (JAR) files, and
20 2. to verify the signatures and integrity of signed JAR files.
22 The JAR feature enables the packaging of class files, images, sounds,
25 and other digital data in a single file for faster and easier distribu‐
26 tion. A tool named jar enables developers to produce JAR files. (Tech‐
27 nically, any zip file can also be considered a JAR file, although when
28 created by jar or processed by jarsigner, JAR files also contain a
29 META-INF/MANIFEST.MF file.)
30 A digital signature is a string of bits that is computed from some data
32 (the data being "signed") and the private key of an entity (a person,
33 company, etc.). Like a handwritten signature, a digital signature has
34 many useful characteristics:
35 o Its authenticity can be verified, via a computation that uses the
37 public key corresponding to the private key used to generate the
38 signature.
39 o It cannot be forged, assuming the private key is kept secret.
41 o It is a function of the data signed and thus can't be claimed to
43 be the signature for other data as well.
44 o The signed data cannot be changed; if it is, the signature will no
46 longer verify as being authentic.
47 In order for an entity's signature to be generated for a file, the
50 entity must first have a public/private key pair associated with it,
51 and also one or more certificates authenticating its public key. A cer‐
52 tificate is a digitally signed statement from one entity, saying that
53 the public key of some other entity has a particular value.
54 jarsigner uses key and certificate information from a keystore to gen‐
56 erate digital signatures for JAR files. A keystore is a database of
57 private keys and their associated X.509 certificate chains authenticat‐
58 ing the corresponding public keys. The keytool utility is used to cre‐
59 ate and administer keystores.
60 jarsigner uses an entity's private key to generate a signature. The
62 signed JAR file contains, among other things, a copy of the certificate
63 from the keystore for the public key corresponding to the private key
64 used to sign the file. jarsigner can verify the digital signature of
65 the signed JAR file using the certificate inside it (in its signature
66 block file).
67 Starting in J2SE 5.0, jarsigner can generate signatures that include a
69 timestamp, thus enabling systems/deployer (including Java Plug-in) to
70 check whether the JAR file was signed while the signing certificate was
71 still valid. In addition, APIs were added in J2SE 5.0 to allow applica‐
72 tions to obtain the timestamp information.
73 At this time, jarsigner can only sign JAR files created by the SDK jar
75 tool or zip files. (JAR files are the same as zip files, except they
76 also have a META-INF/MANIFEST.MF file. Such a file will automatically
77 be created when jarsigner signs a zip file.)
78 The default jarsigner behavior is to sign a JAR (or zip) file. Use the
80 -verify option to instead have it verify a signed JAR file.
81 Compatibility with JDK 1.1
83 The keytool and jarsigner tools completely replace the javakey tool
84 provided in JDK 1.1. These new tools provide more features than
85 javakey, including the ability to protect the keystore and private
86 keys with passwords, and the ability to verify signatures in addi‐
87 tion to generating them.
88 The new keystore architecture replaces the identity database that
90 javakey created and managed. There is no backwards compatibility
91 between the keystore format and the database format used by javakey
92 in 1.1. However,
93 o It is possible to import the information from an identity data‐
95 base into a keystore, via the keytool -identitydb command.
96 o jarsigner can sign JAR files also previously signed using
98 javakey.
99 o jarsigner can verify JAR files signed using javakey. Thus, it
101 recognizes and can work with signer aliases that are from a JDK
102 1.1 identity database rather than a Java 2 SDK keystore.
103 The following table explains how JAR files that were signed in JDK
106 1.1.x are treated in the Java 2 platform.
107 Notes:
109 1. If an identity/alias is mentioned in the policy file, it must
111 be imported into the keystore for the policy file to have any
112 effect on privileges granted.
113 2. The policy file/keystore combination has precedence over a
115 trusted identity in the identity database.
116 3. Untrusted identities are ignored in the Java 2 platform.
118 4. Only trusted identities can be imported into Java 2 SDK key‐
120 stores.
121 Keystore Aliases
124 All keystore entities are accessed via unique aliases.
125 When using jarsigner to sign a JAR file, you must specify the alias
127 for the keystore entry containing the private key needed to generate
128 the signature. For example, the following will sign the JAR file
129 named "MyJARFile.jar", using the private key associated with the
130 alias "duke" in the keystore named "mystore" in the "working" direc‐
131 tory. Since no output file is specified, it overwrites MyJARFile.jar
132 with the signed JAR file.
133 jarsigner -keystore /working/mystore -storepass myspass
135 -keypass dukekeypasswd MyJARFile.jar duke
136 Keystores are protected with a password, so the store password (in
139 this case "myspass") must be specified. You will be prompted for it
140 if you don't specify it on the command line. Similarly, private keys
141 are protected in a keystore with a password, so the private key's
142 password (in this case "dukekeypasswd") must be specified, and you
143 will be prompted for it if you don't specify it on the command line
144 and it isn't the same as the store password.
145 Keystore Location
147 jarsigner has a -keystore option for specifying the URL of the key‐
148 store to be used. The keystore is by default stored in a file named
149 .keystore in the user's home directory, as determined by the
150 user.home system property. On Solaris systems user.home defaults to
151 the user's home directory.
152 Note that the input stream from the -keystore option is passed to
154 the KeyStore.load method. If NONE is specified as the URL, then a
155 null stream is passed to the KeyStore.load method. NONE should be
156 specified if the KeyStore is not file-based, for example, if it
157 resides on a hardware token device.
158 Keystore Implementation
160 The KeyStore class provided in the java.security package supplies
161 well-defined interfaces to access and modify the information in a
162 keystore. It is possible for there to be multiple different concrete
163 implementations, where each implementation is that for a particular
164 type of keystore.
165 Currently, there are two command-line tools that make use of key‐
167 store implementations (keytool and jarsigner), and also a GUI-based
168 tool named Policy Tool. Since KeyStore is publicly available, Java 2
169 SDK users can write additional security applications that use it.
170 There is a built-in default implementation, provided by Sun
172 Microsystems. It implements the keystore as a file, utilizing a pro‐
173 prietary keystore type (format) named "JKS". It protects each pri‐
174 vate key with its individual password, and also protects the
175 integrity of the entire keystore with a (possibly different) pass‐
176 word.
177 Keystore implementations are provider-based. More specifically, the
179 application interfaces supplied by KeyStore are implemented in terms
180 of a "Service Provider Interface" (SPI). That is, there is a corre‐
181 sponding abstract KeystoreSpi class, also in the java.security pack‐
182 age, which defines the Service Provider Interface methods that
183 "providers" must implement. (The term "provider" refers to a package
184 or a set of packages that supply a concrete implementation of a sub‐
185 set of services that can be accessed by the Java Security API.)
186 Thus, to provide a keystore implementation, clients must implement a
187 provider and supply a KeystoreSpi subclass implementation, as
188 described in How to Implement a Provider for the Java Cryptography
189 Architecture @
190 http://java.sun.com/javase/6/docs/technotes/guides/security/HowToIm‐
191 plAProvider.html.
192 Applications can choose different types of keystore implementations
194 from different providers, using the "getInstance" factory method
195 supplied in the KeyStore class. A keystore type defines the storage
196 and data format of the keystore information, and the algorithms used
197 to protect private keys in the keystore and the integrity of the
198 keystore itself. Keystore implementations of different types are not
199 compatible.
200 keytool works on any file-based keystore implementation. (It treats
202 the keytore location that is passed to it at the command line as a
203 filename and converts it to a FileInputStream, from which it loads
204 the keystore information.) The jarsigner and policytool tools, on
205 the other hand, can read a keystore from any location that can be
206 specified using a URL.
207 For jarsigner and keytool, you can specify a keystore type at the
209 command line, via the -storetype option. For Policy Tool, you can
210 specify a keystore type via the "Change Keystore" command in the
211 Edit menu.
212 If you don't explicitly specify a keystore type, the tools choose a
214 keystore implementation based simply on the value of the key‐
215 store.type property specified in the security properties file. The
216 security properties file is called java.security, and it resides in
217 the SDK security properties directory, java.home/lib/security, where
218 java.home is the runtime environment's directory (the jre directory
219 in the SDK or the top-level directory of the Java 2 Runtime Environ‐
220 ment).
221 Each tool gets the keystore.type value and then examines all the
223 currently-installed providers until it finds one that implements
224 keystores of that type. It then uses the keystore implementation
225 from that provider.
226 The KeyStore class defines a static method named getDefaultType that
228 lets applications and applets retrieve the value of the key‐
229 store.type property. The following line of code creates an instance
230 of the default keystore type (as specified in the keystore.type
231 property):
232 KeyStore keyStore = KeyStore.getInstance(KeyStore.getDefaultType());
234 The default keystore type is "jks" (the proprietary type of the key‐
237 store implementation provided by Sun). This is specified by the fol‐
238 lowing line in the security properties file:
239 keystore.type=jks
241 Note: Case doesn't matter in keystore type designations. For exam‐
244 ple, "JKS" would be considered the same as "jks".
245 To have the tools utilize a keystore implementation other than the
247 default, change that line to specify a different keystore type. For
248 example, if you have a provider package that supplies a keystore
249 implementation for a keystore type called "pkcs12", change the line
250 to
251 keystore.type=pkcs12
253 Note that if you us the PKCS#11 provider package, you should refer
256 to the KeyTool and JarSigner @
257 http://java.sun.com/javase/6/docs/technotes/guides/secu‐
258 rity/p11guide.html#keytooljarsigner section of the Java PKCS#11 Ref‐
259 erence Guide for details.
260 Supported Algorithms
262 By default, jarsigner signs a JAR file using either
263 o DSA (Digital Signature Algorithm) with the SHA-1 digest algo‐
265 rithm, or
266 o the RSA algorithm with the MD5 digest algorithm.
268 That is, if the signer's public and private keys are DSA keys, jar‐
271 signer will sign the JAR file using the "SHA1withDSA" algorithm. If
272 the signer's keys are RSA keys, jarsigner will attempt to sign the
273 JAR file using the "MD5withRSA" algorithm.
274 These default signature algorithms can be overridden using the
276 -sigalg option.
277 The Signed JAR File
279 When jarsigner is used to sign a JAR file, the output signed JAR
280 file is exactly the same as the input JAR file, except that it has
281 two additional files placed in the META-INF directory:
282 o a signature file, with a .SF extension, and
284 o a signature block file, with a .DSA extension.
286 The base file names for these two files come from the value of the
289 -sigFile option. For example, if the option appears as
290 -sigFile MKSIGN
292 the files are named "MKSIGN.SF" and "MKSIGN.DSA".
295 If no -sigfile option appears on the command line, the base file
297 name for the .SF and .DSA files will be the first 8 characters of
298 the alias name specified on the command line, all converted to upper
299 case. If the alias name has fewer than 8 characters, the full alias
300 name is used. If the alias name contains any characters that are not
301 allowed in a signature file name, each such character is converted
302 to an underscore ("_") character in forming the file name. Legal
303 characters include letters, digits, underscores, and hyphens.
304 The Signature (.SF) File
306 A signature file (the .SF file) looks similar to the manifest
308 file that is always included in a JAR file when jarsigner is used
309 to sign the file. That is, for each source file included in the
310 JAR file, the .SF file has three lines, just as in the manifest
311 file, listing the following:
312 o the file name,
314 o the name of the digest algorithm used (SHA), and
316 o a SHA digest value.
318 In the manifest file, the SHA digest value for each source file
321 is the digest (hash) of the binary data in the source file. In
322 the .SF file, on the other hand, the digest value for a given
323 source file is the hash of the three lines in the manifest file
324 for the source file.
325 The signature file also, by default, includes a header containing
327 a hash of the whole manifest file. The presence of the header
328 enables verification optimization, as described in JAR File Veri‐
329 fication.
330 The Signature Block (.DSA) File
332 The .SF file is signed and the signature is placed in the .DSA
334 file. The .DSA file also contains, encoded inside it, the cer‐
335 tificate or certificate chain from the keystore which authenti‐
336 cates the public key corresponding to the private key used for
337 signing.
338 Signature Timestamp
340 As of the J2SE 5.0 release, the jarsigner tool can now generate and
341 store a signature timestamp when signing a JAR file. In addition,
342 jarsigner supports alternative signing mechanisms. This behavior is
343 optional and is controlled by the user at the time of signing
344 through these options:
345 o -tsa url
347 o -tsacert alias
349 o -altsigner class
351 o -altsignerpath classpathlist
353 Each of these options is detailed in the Options section below.
356 JAR File Verification
358 A successful JAR file verification occurs if the signature(s) are
359 valid, and none of the files that were in the JAR file when the sig‐
360 natures were generated have been changed since then. JAR file veri‐
361 fication involves the following steps:
362 1. Verify the signature of the .SF file itself.
364 That is, the verification ensures that the signature stored in
366 each signature block (.DSA) file was in fact generated using the
367 private key corresponding to the public key whose certificate (or
368 certificate chain) also appears in the .DSA file. It also ensures
369 that the signature is a valid signature of the corresponding sig‐
370 nature (.SF) file, and thus the .SF file has not been tampered
371 with.
372 2. Verify the digest listed in each entry in the .SF file with
374 each corresponding section in the manifest.
375 The .SF file by default includes a header containing a hash of
377 the entire manifest file. When the header is present, then the
378 verification can check to see whether or not the hash in the
379 header indeed matches the hash of the manifest file. If that is
380 the case, verification proceeds to the next step.
381 If that is not the case, a less optimized verification is
383 required to ensure that the hash in each source file information
384 section in the .SF file equals the hash of its corresponding sec‐
385 tion in the manifest file (see The Signature (.SF) File).
386 One reason the hash of the manifest file that is stored in the
388 .SF file header may not equal the hash of the current manifest
389 file would be because one or more files were added to the JAR
390 file (using the jar tool) after the signature (and thus the .SF
391 file) was generated. When the jar tool is used to add files, the
392 manifest file is changed (sections are added to it for the new
393 files), but the .SF file is not. A verification is still consid‐
394 ered successful if none of the files that were in the JAR file
395 when the signature was generated have been changed since then,
396 which is the case if the hashes in the non-header sections of the
397 .SF file equal the hashes of the corresponding sections in the
398 manifest file.
399 3. Read each file in the JAR file that has an entry in the .SF
401 file. While reading, compute the file's digest, and then com‐
402 pare the result with the digest for this file in the manifest
403 section. The digests should be the same, or verification
404 fails.
405 If any serious verification failures occur during the verification
408 process, the process is stopped and a security exception is thrown.
409 It is caught and displayed by jarsigner.
410 Multiple Signatures for a JAR File
412 A JAR file can be signed by multiple people simply by running the
413 jarsigner tool on the file multiple times, specifying the alias for
414 a different person each time, as in:
415 jarsigner myBundle.jar susan
417 jarsigner myBundle.jar kevin
418 When a JAR file is signed multiple times, there are multiple .SF and
421 .DSA files in the resulting JAR file, one pair for each signature.
422 Thus, in the example above, the output JAR file includes files with
423 the following names:
424 SUSAN.SF
426 SUSAN.DSA
427 KEVIN.SF
428 KEVIN.DSA
429 Note: It is also possible for a JAR file to have mixed signatures,
432 some generated by the JDK 1.1 javakey tool and others by jarsigner.
433 That is, jarsigner can be used to sign JAR files already previously
434 signed using javakey.
435
437 The various jarsigner options are listed and described below. Note:
438 o All option names are preceded by a minus sign (-).
440 o The options may be provided in any order.
442 o Items in italics (option values) represent the actual values that
444 must be supplied.
445 o The -keystore, -storepass, -keypass, -sigfile, -sigalg,
447 -digestalg, and -signedjar options are only relevant when signing
448 a JAR file, not when verifying a signed JAR file. Similarly, an
449 alias is only specified on the command line when signing a JAR
450 file.
451 -keystore url
454 Specifies the URL that tells the keystore location. This defaults
455 to the file .keystore in the user's home directory, as determined
456 by the "user.home" system property.
457 A keystore is required when signing, so you must explicitly specify
459 one if the default keystore does not exist (or you want to use one
460 other than the default).
461 A keystore is not required when verifying, but if one is specified,
463 or the default exists, and the -verbose option was also specified,
464 additional information is output regarding whether or not any of the
465 certificates used to verify the JAR file are contained in that key‐
466 store.
467 Note: the -keystore argument can actually be a file name (and path)
469 specification rather than a URL, in which case it will be treated
470 the same as a "file:" URL. That is,
471 -keystore filePathAndName
472 is treated as equivalent to
473 -keystore file:filePathAndName
474 If the Sun PKCS#11 provider has been configured in the java.security
475 security properties file (located in the JRE's $JAVA_HOME/lib/secu‐
476 rity directory), then keytool and jarsigner can operate on the
477 PKCS#11 token by specifying these options:
478 o -keystore NONE
480 o -storetype PKCS11
482 For example, this command lists the contents of the configured
483 PKCS#11 token:
484 jarsigner -keystore NONE -storetype PKCS11 -list
487 -storetype storetype
490 Specifies the type of keystore to be instantiated. The default
491 keystore type is the one that is specified as the value of the
492 "keystore.type" property in the security properties file, which
493 is returned by the static getDefaultType method in java.secu‐
494 rity.KeyStore.
495 The PIN for a PCKS#11 token can also be specified using the
497 -storepass option. If none has been specified, keytool and jarsigner
498 will prompt for the token PIN. If the token has a protected authen‐
499 tication path (such as a dedicated PIN-pad or a biometric reader),
500 then the -protected option must be specified and no password options
501 can be specified.
502 -storepass password
504 Specifies the password which is required to access the keystore.
505 This is only needed when signing (not verifying) a JAR file. In
506 that case, if a -storepass option is not provided at the command
507 line, the user is prompted for the password.
508 Note: The password shouldn't be specified on the command line or in
510 a script unless it is for testing purposes, or you are on a secure
511 system. Also, when typing in a password at the password prompt, the
512 password is echoed (displayed exactly as typed), so be careful not
513 to type it in front of anyone.
514 -keypass password
516 Specifies the password used to protect the private key of the
517 keystore entry addressed by the alias specified on the command
518 line. The password is required when using jarsigner to sign a JAR
519 file. If no password is provided on the command line, and the
520 required password is different from the store password, the user
521 is prompted for it.
522 Note: The password shouldn't be specified on the command line or in
524 a script unless it is for testing purposes, or you are on a secure
525 system. Also, when typing in a password at the password prompt, the
526 password is echoed (displayed exactly as typed), so be careful not
527 to type it in front of anyone.
528 -sigfile file
530 Specifies the base file name to be used for the generated .SF and
531 .DSA files. For example, if file is "DUKESIGN", the generated .SF
532 and .DSA files will be named "DUKESIGN.SF" and "DUKESIGN.DSA",
533 and will be placed in the "META-INF" directory of the signed JAR
534 file.
535 The characters in file must come from the set "a-zA-Z0-9_-". That
537 is, only letters, numbers, underscore, and hyphen characters are
538 allowed. Note: All lowercase characters will be converted to upper‐
539 case for the .SF and .DSA file names.
540 If no -sigfile option appears on the command line, the base file
542 name for the .SF and .DSA files will be the first 8 characters of
543 the alias name specified on the command line, all converted to upper
544 case. If the alias name has fewer than 8 characters, the full alias
545 name is used. If the alias name contains any characters that are not
546 legal in a signature file name, each such character is converted to
547 an underscore ("_") character in forming the file name.
548 -sigalg algorithm
550 Specifies the name of the signature algorithm to use to sign the
553 JAR file.
554 See Appendix A @
556 http://java.sun.com/javase/6/docs/technotes/guides/secu‐
557 rity/crypto/CryptoSpec.html#appa of the Java Cryptography Archi‐
558 tecture for a list of standard signature algorithm names. This
559 algorithm must be compatible with the private key used to sign
560 the JAR file. If this option is not specified, SHA1withDSA or
561 MD5withRSA will be used depending on the type of private key.
562 There must either be a statically installed provider supplying an
563 implementation of the specified algorithm or the user must spec‐
564 ify one with the -providerClass option, otherwise the command
565 will not succeed.
566 -digestalg algorithm
568 Specifies the name of the message digest algorithm to use when
569 digesting the entries of a jar file.
570 See Appendix A @
572 http://java.sun.com/javase/6/docs/technotes/guides/secu‐
573 rity/crypto/CryptoSpec.html#appa of the Java Cryptography Archi‐
574 tecture for a list of standard message digest algorithm names. If
575 this option is not specified, SHA-1 will be used. There must
576 either be a statically installed provider supplying an implemen‐
577 tation of the specified algorithm or the user must specify one
578 with the -providerClass option, otherwise the command will not
579 succeed.
580 -signedjar file
582 Specifies the name to be used for the signed JAR file.
583 If no name is specified on the command line, the name used is the
585 same as the input JAR file name (the name of the JAR file to be
586 signed); in other words, that file is overwritten with the signed
587 JAR file.
588 -verify
590 If this appears on the command line, the specified JAR file will
591 be verified, not signed. If the verification is successful, "jar
592 verified" will be displayed. If you try to verify an unsigned JAR
593 file, or a JAR file signed with an unsupported algorithm (e.g.,
594 RSA when you don't have an RSA provider installed), the following
595 is displayed: "jar is unsigned. (signatures missing or not
596 parsable)"
597 It is possible to verify JAR files signed using either jarsigner or
599 the JDK 1.1 javakey tool, or both.
600 For further information on verification, see JAR File Verification.
602 -certs
604 If this appears on the command line, along with the -verify and
605 -verbose options, the output includes certificate information for
606 each signer of the JAR file. This information includes
607 o the name of the type of certificate (stored in the .DSA file)
609 that certifies the signer's public key
610 o if the certificate is an X.509 certificate (more specifically,
612 an instance of java.security.cert.X509Certificate): the distin‐
613 guished name of the signer
614 The keystore is also examined. If no keystore value is specified on
616 the command line, the default keystore file (if any) will be
617 checked. If the public key certificate for a signer matches an entry
618 in the keystore, then the following information will also be dis‐
619 played:
620 o in parentheses, the alias name for the keystore entry for that
622 signer. If the signer actually comes from a JDK 1.1 identity
623 database instead of from a keystore, the alias name will appear
624 in brackets instead of parentheses.
625 -verbose
627 If this appears on the command line, it indicates "verbose" mode,
628 which causes jarsigner to output extra information as to the
629 progress of the JAR signing or verification.
630 -internalsf
632 In the past, the .DSA (signature block) file generated when a JAR
633 file was signed used to include a complete encoded copy of the
634 .SF file (signature file) also generated. This behavior has been
635 changed. To reduce the overall size of the output JAR file, the
636 .DSA file by default doesn't contain a copy of the .SF file any‐
637 more. But if -internalsf appears on the command line, the old
638 behavior is utilized. This option is mainly useful for testing;
639 in practice, it should not be used, since doing so eliminates a
640 useful optimization.
641 -sectionsonly
643 If this appears on the command line, the .SF file (signature
644 file) generated when a JAR file is signed does not include a
645 header containing a hash of the whole manifest file. It just con‐
646 tains information and hashes related to each individual source
647 file included in the JAR file, as described in The Signature
648 (.SF) File .
649 By default, this header is added, as an optimization. When the
651 header is present, then whenever the JAR file is verified, the veri‐
652 fication can first check to see whether or not the hash in the
653 header indeed matches the hash of the whole manifest file. If so,
654 verification proceeds to the next step. If not, it is necessary to
655 do a less optimized verification that the hash in each source file
656 information section in the .SF file equals the hash of its corre‐
657 sponding section in the manifest file.
658 For further information, see JAR File Verification.
660 This option is mainly useful for testing; in practice, it should not
662 be used, since doing so eliminates a useful optimization.
663 -protected
665 Either true or false. This value should be specified as true if a
666 password must be given via a protected authentication path such
667 as a dedicated PIN reader.
668 -provider provider-class-name
670 Used to specify the name of cryptographic service provider's mas‐
671 ter class file when the service provider is not listed in the
672 security properties file, java.security.
673 Used in conjunction with the -providerArg ConfigFilePath option,
675 keytool and jarsigner will install the provider dynamically (where
676 ConfigFilePath is the path to the token configuration file). Here's
677 an example of a command to list a PKCS#11 keystore when the Sun
678 PKCS#11 provider has not been configured in the security properties
679 file.
680 jarsigner -keystore NONE -storetype PKCS11 \
683 -providerClass sun.security.pkcs11.SunPKCS11 \
684 -providerArg /foo/bar/token.config \
685 -list
686 -providerName providerName
688 If more than one provider has been configured in the java.secu‐
689 rity security properties file, you can use the -providerName
690 option to target a specific provider instance. The argument to
691 this option is the name of the provider.
692 For the Sun PKCS#11 provider, providerName is of the form
694 SunPKCS11-TokenName, where TokenName is the name suffix that the
695 provider instance has been configured with, as detailed in the con‐
696 figuration attributes table @
697 http://java.sun.com/javase/6/docs/technotes/guides/secu‐
698 rity/p11guide.html#KeyToolJarSigner#ATTRS. For example, the follow‐
699 ing command lists the contents of the PKCS#11 keystore provider
700 instance with name suffix SmartCard:
701 jarsigner -keystore NONE -storetype PKCS11 \
704 -providerName SunPKCS11-SmartCard \
705 -list
706 -Jjavaoption
708 Passes through the specified javaoption string directly to the
709 Java interpreter. (jarsigner is actually a "wrapper" around the
710 interpreter.) This option should not contain any spaces. It is
711 useful for adjusting the execution environment or memory usage.
712 For a list of possible interpreter options, type java -h or java
713 -X at the command line.
714 -tsa url
716 If "-tsa http://example.tsa.url" appears on the command line when
717 signing a JAR file then a timestamp is generated for the signa‐
718 ture. The URL, http://example.tsa.url, identifies the location of
719 the Time Stamping Authority (TSA). It overrides any URL found via
720 the -tsacert option. The -tsa option does not require the TSA's
721 public key certificate to be present in the keystore.
722 To generate the timestamp, jarsigner communicates with the TSA using
724 the Time-Stamp Protocol (TSP) defined in RFC 3161 @
725 http://www.ietf.org/rfc/rfc3161.txt. If successful, the timestamp
726 token returned by the TSA is stored along with the signature in the
727 signature block file.
728 -tsacert alias
730 If "-tsacert alias" appears on the command line when signing a
731 JAR file then a timestamp is generated for the signature. The
732 alias identifies the TSA's public key certificate in the keystore
733 that is currently in effect. The entry's certificate is examined
734 for a Subject Information Access extension that contains a URL
735 identifying the location of the TSA.
736 The TSA's public key certificate must be present in the keystore
738 when using -tsacert.
739 -altsigner class
741 Specifies that an alternative signing mechanism be used. The
742 fully-qualified class name identifies a class file that extends
743 the com.sun.jarsigner.ContentSigner abstract class. The path to
744 this class file is defined by the -altsignerpath option. If the
745 -altsigner option is used, jarsigner uses the signing mechanism
746 provided by the specified class. Otherwise, jarsigner uses its
747 default signing mechanism.
748 For example, to use the signing mechanism provided by a class named
750 com.sun.sun.jarsigner.AuthSigner, use the jarsigner option "-alt‐
751 signer com.sun.jarsigner.AuthSigner"
752 -altsignerpath classpathlist
754 Specifies the path to the class file (the class file name is
755 specified with the -altsigner option described above) and any JAR
756 files it depends on. If the class file is in a JAR file, then
757 this specifies the path to that JAR file, as shown in the example
758 below.
759 An absolute path or a path relative to the current directory may be
761 specified. If classpathlist contains multiple paths or JAR files,
762 they should be separated with a colon (:) on Solaris and a
763 semi-colon (;) on Windows. This option is not necessary if the class
764 is already in the search path.
765 Example of specifying the path to a jar file that contains the class
767 file:
768 -altsignerpath /home/user/lib/authsigner.jar
771 Note that the JAR file name is included.
773 Example of specifying the path to the jar file that contains the
775 class file:
776 -altsignerpath /home/user/classes/com/sun/tools/jarsigner/
778 Note that the JAR file name is omitted.
780
782 Signing a JAR File
783 Suppose you have a JAR file named "bundle.jar" and you'd like to
784 sign it using the private key of the user whose keystore alias is
785 "jane" in the keystore named "mystore" in the "working" directory.
786 Suppose the keystore password is "myspass" and the password for
787 jane's private key is "j638klm". You can use the following to sign
788 the JAR file and name the signed JAR file "sbundle.jar":
789 jarsigner -keystore /working/mystore -storepass myspass
791 -keypass j638klm -signedjar sbundle.jar bundle.jar jane
792 Note that there is no -sigfile specified in the command above, so
795 the generated .SF and .DSA files to be placed in the signed JAR file
796 will have default names based on the alias name. That is, they will
797 be named JANE.SF and JANE.DSA.
798 If you want to be prompted for the store password and the private
800 key password, you could shorten the above command to
801 jarsigner -keystore /working/mystore
803 -signedjar sbundle.jar bundle.jar jane
804 If the keystore to be used is the default keystore (the one named
807 ".keystore" in your home directory), you don't need to specify a
808 keystore, as in:
809 jarsigner -signedjar sbundle.jar bundle.jar jane
811 Finally, if you want the signed JAR file to simply overwrite the
814 input JAR file (bundle.jar), you don't need to specify a -signedjar
815 option:
816 jarsigner bundle.jar jane
818 Verifying a Signed JAR File
821 To verify a signed JAR file, that is, to verify that the signature
822 is valid and the JAR file has not been tampered with, use a command
823 such as the following:
824 jarsigner -verify sbundle.jar
826 If the verification is successful,
829 jar verified.
831 is displayed. Otherwise, an error message appears.
834 You can get more information if you use the -verbose option. A sam‐
836 ple use of jarsigner with the -verbose option is shown below, along
837 with sample output:
838 jarsigner -verify -verbose sbundle.jar
840 198 Fri Sep 26 16:14:06 PDT 1997 META-INF/MANIFEST.MF
842 199 Fri Sep 26 16:22:10 PDT 1997 META-INF/JANE.SF
843 1013 Fri Sep 26 16:22:10 PDT 1997 META-INF/JANE.DSA
844 smk 2752 Fri Sep 26 16:12:30 PDT 1997 AclEx.class
845 smk 849 Fri Sep 26 16:12:46 PDT 1997 test.class
846 s = signature was verified
848 m = entry is listed in manifest
849 k = at least one certificate was found in keystore
850 jar verified.
852 Verification with Certificate Information
855 If you specify the -certs option when verifying, along with the -verify
856 and -verbose options, the output includes certificate information for
857 each signer of the JAR file, including the certificate type, the signer
858 distinguished name information (iff it's an X.509 certificate), and, in
859 parentheses, the keystore alias for the signer if the public key cer‐
860 tificate in the JAR file matches that in a keystore entry. For example,
861 jarsigner -keystore /working/mystore -verify -verbose -certs myTest.jar
863 198 Fri Sep 26 16:14:06 PDT 1997 META-INF/MANIFEST.MF
865 199 Fri Sep 26 16:22:10 PDT 1997 META-INF/JANE.SF
866 1013 Fri Sep 26 16:22:10 PDT 1997 META-INF/JANE.DSA
867 208 Fri Sep 26 16:23:30 PDT 1997 META-INF/JAVATEST.SF
868 1087 Fri Sep 26 16:23:30 PDT 1997 META-INF/JAVATEST.DSA
869 smk 2752 Fri Sep 26 16:12:30 PDT 1997 Tst.class
870 X.509, CN=Test Group, OU=Java Software, O=Sun Microsystems, L=CUP, S=CA, C=US (javatest)
872 X.509, CN=Jane Smith, OU=Java Software, O=Sun, L=cup, S=ca, C=us (jane)
873 s = signature was verified
875 m = entry is listed in manifest
876 k = at least one certificate was found in keystore
877 jar verified.
879 If the certificate for a signer is not an X.509 certificate, there is
882 no distinguished name information. In that case, just the certificate
883 type and the alias are shown. For example, if the certificate is a PGP
884 certificate, and the alias is "bob", you'd get
885 PGP, (bob)
887 Verification of a JAR File that Includes Identity Database Signers
890 If a JAR file has been signed using the JDK 1.1 javakey tool, and thus
891 the signer is an alias in an identity database, the verification output
892 includes an "i" symbol. If the JAR file has been signed by both an
893 alias in an identity database and an alias in a keystore, both "k" and
894 "i" appear.
895 When the -certs option is used, any identity database aliases are shown
897 in square brackets rather than the parentheses used for keystore
898 aliases. For example:
899 jarsigner -keystore /working/mystore -verify -verbose -certs writeFile.jar
901 198 Fri Sep 26 16:14:06 PDT 1997 META-INF/MANIFEST.MF
903 199 Fri Sep 26 16:22:10 PDT 1997 META-INF/JANE.SF
904 1013 Fri Sep 26 16:22:10 PDT 1997 META-INF/JANE.DSA
905 199 Fri Sep 27 12:22:30 PDT 1997 META-INF/DUKE.SF
906 1013 Fri Sep 27 12:22:30 PDT 1997 META-INF/DUKE.DSA
907 smki 2752 Fri Sep 26 16:12:30 PDT 1997 writeFile.html
908 X.509, CN=Jane Smith, OU=Java Software, O=Sun, L=cup, S=ca, C=us (jane)
910 X.509, CN=Duke, OU=Java Software, O=Sun, L=cup, S=ca, C=us [duke]
911 s = signature was verified
913 m = entry is listed in manifest
914 k = at least one certificate was found in keystore
915 i = at least one certificate was found in identity scope
916 jar verified.
918 Note that the alias "duke" is in brackets to denote that it is an iden‐
921 tity database alias, not a keystore alias.
922
924 o jar tool documentation
925 o keytool tool documentation
927 o the Security @
929 http://java.sun.com/docs/books/tutorial/security1.2/index.html
930 trail of the Java Tutorial @
931 http://java.sun.com/docs/books/tutorial/trailmap.html for examples
932 of the use of the jarsigner tool
933 07 Aug 2006 jarsigner(1)