1jarsigner(1)                General Commands Manual               jarsigner(1)
2
3
4

NAME

6       jarsigner - JAR Signing and Verification Tool
7
8          Generates  signatures for Java ARchive (JAR) files, and verifies the
9          signatures of signed JAR files.
10

SYNOPSIS

12       jarsigner [ options ] jar-file alias
13       jarsigner -verify [ options ] jar-file
14
15

DESCRIPTION

17       The jarsigner tool is used for two purposes:
18
19          1. to sign Java ARchive (JAR) files, and
20
21          2. to verify the signatures and integrity of signed JAR files.
22
23
24       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
31       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
36          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
40          o It cannot be forged, assuming the private key is kept secret.
41
42          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
45          o The signed data cannot be changed; if it is, the signature will no
46            longer verify as being authentic.
47
48
49       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
55       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
61       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
68       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
74       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
79       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
82   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
89          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
94             o It is possible to import the information from an identity data‐
95               base into a keystore, via the keytool -identitydb command.
96
97             o jarsigner  can  sign  JAR  files  also  previously signed using
98               javakey.
99
100             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
104
105          The following table explains how JAR files that were signed  in  JDK
106          1.1.x are treated in the Java 2 platform.
107
108          Notes:
109
110             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
114             2. The  policy  file/keystore  combination  has precedence over a
115                trusted identity in the identity database.
116
117             3. Untrusted identities are ignored in the Java 2 platform.
118
119             4. Only trusted identities can be imported into Java 2  SDK  key‐
120                stores.
121
122
123   Keystore Aliases
124          All keystore entities are accessed via unique aliases.
125
126          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
134              jarsigner -keystore /working/mystore -storepass myspass
135                -keypass dukekeypasswd MyJARFile.jar duke
136
137
138          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
146   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
153          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
159   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
166          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
171          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
178          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
193          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
201          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
208          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
213          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
222          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
227          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
233              KeyStore keyStore = KeyStore.getInstance(KeyStore.getDefaultType());
234
235
236          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
240              keystore.type=jks
241
242
243          Note: Case doesn't matter in keystore type designations. For exam‐
244          ple, "JKS" would be considered the same as "jks".
245
246          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
252              keystore.type=pkcs12
253
254
255          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
261   Supported Algorithms
262          By default, jarsigner signs a JAR file using either
263
264             o DSA (Digital Signature Algorithm) with the SHA-1 digest algo‐
265               rithm, or
266
267             o the RSA algorithm with the MD5 digest algorithm.
268
269
270          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
275          These default signature algorithms can be overridden using the
276          -sigalg option.
277
278   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
283             o a signature file, with a .SF extension, and
284
285             o a signature block file, with a .DSA extension.
286
287
288          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
291            -sigFile MKSIGN
292
293
294          the files are named "MKSIGN.SF" and "MKSIGN.DSA".
295
296          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
305          The Signature (.SF) File
306
307             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
313                o the file name,
314
315                o the name of the digest algorithm used (SHA), and
316
317                o a SHA digest value.
318
319
320             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
326             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
331          The Signature Block (.DSA) File
332
333             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
339   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
346             o -tsa url
347
348             o -tsacert alias
349
350             o -altsigner class
351
352             o -altsignerpath classpathlist
353
354
355          Each of these options is detailed in the Options section below.
356
357   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
363             1. Verify the signature of the .SF file itself.
364
365             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
373             2. Verify the digest listed in each entry in the .SF file with
374                each corresponding section in the manifest.
375
376             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
382             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
387             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
400             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
406
407          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
411   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
416            jarsigner myBundle.jar susan
417            jarsigner myBundle.jar kevin
418
419
420          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
425            SUSAN.SF
426            SUSAN.DSA
427            KEVIN.SF
428            KEVIN.DSA
429
430
431          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

OPTIONS

437       The various jarsigner options are listed and described below. Note:
438
439          o All option names are preceded by a minus sign (-).
440
441          o The options may be provided in any order.
442
443          o Items in italics (option values) represent the actual values that
444            must be supplied.
445
446          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
452
453          -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
458          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
462          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
468          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
479             o -keystore NONE
480
481             o -storetype PKCS11
482          For example, this command lists the contents of the configured
483          PKCS#11 token:
484
485
486                jarsigner -keystore NONE -storetype PKCS11 -list
487
488
489          -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
496          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
503          -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
509          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
515          -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
523          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
529          -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
536          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
541          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
549          -sigalg algorithm
550
551
552             Specifies the name of the signature algorithm to use to sign the
553             JAR file.
554
555             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
567          -digestalg algorithm
568             Specifies the name of the message digest algorithm to use when
569             digesting the entries of a jar file.
570
571             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
581          -signedjar file
582             Specifies the name to be used for the signed JAR file.
583
584          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
589          -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
598          It is possible to verify JAR files signed using either jarsigner or
599          the JDK 1.1 javakey tool, or both.
600
601          For further information on verification, see JAR File Verification.
602
603          -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
608             o the name of the type of certificate (stored in the .DSA file)
609               that certifies the signer's public key
610
611             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
615          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
621             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
626          -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
631          -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
642          -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
650          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
659          For further information, see JAR File Verification.
660
661          This option is mainly useful for testing; in practice, it should not
662          be used, since doing so eliminates a useful optimization.
663
664          -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
669          -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
674          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
681
682             jarsigner -keystore NONE -storetype PKCS11 \
683                       -providerClass sun.security.pkcs11.SunPKCS11 \
684                       -providerArg /foo/bar/token.config \
685                       -list
686
687          -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
693          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
702
703             jarsigner -keystore NONE -storetype PKCS11 \
704                     -providerName SunPKCS11-SmartCard \
705                     -list
706
707          -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
715          -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
723          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
729          -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
737          The TSA's public key certificate must be present in the keystore
738          when using -tsacert.
739
740          -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
749          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
753          -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
760          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
766          Example of specifying the path to a jar file that contains the class
767          file:
768
769
770             -altsignerpath /home/user/lib/authsigner.jar
771
772          Note that the JAR file name is included.
773
774          Example of specifying the path to the jar file that contains the
775          class file:
776
777             -altsignerpath /home/user/classes/com/sun/tools/jarsigner/
778
779          Note that the JAR file name is omitted.
780

EXAMPLES

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
790              jarsigner -keystore /working/mystore -storepass myspass
791                -keypass j638klm -signedjar sbundle.jar bundle.jar jane
792
793
794          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
799          If you want to be prompted for the store password and the private
800          key password, you could shorten the above command to
801
802              jarsigner -keystore /working/mystore
803                -signedjar sbundle.jar bundle.jar jane
804
805
806          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
810              jarsigner -signedjar sbundle.jar bundle.jar jane
811
812
813          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
817              jarsigner bundle.jar jane
818
819
820   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
825              jarsigner -verify sbundle.jar
826
827
828          If the verification is successful,
829
830              jar verified.
831
832
833          is displayed. Otherwise, an error message appears.
834
835          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
839              jarsigner -verify -verbose sbundle.jar
840
841                     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
847                s = signature was verified
848                m = entry is listed in manifest
849                k = at least one certificate was found in keystore
850
851              jar verified.
852
853
854   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
862           jarsigner -keystore /working/mystore -verify -verbose -certs myTest.jar
863
864                  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
871             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
874             s = signature was verified
875             m = entry is listed in manifest
876             k = at least one certificate was found in keystore
877
878           jar verified.
879
880
881       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
886             PGP, (bob)
887
888
889   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
896       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
900           jarsigner -keystore /working/mystore -verify -verbose -certs writeFile.jar
901
902                  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
909             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
912             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
917           jar verified.
918
919
920       Note that the alias "duke" is in brackets to denote that it is an iden‐
921       tity database alias, not a keystore alias.
922

SEE ALSO

924          o jar tool documentation
925
926          o keytool tool documentation
927
928          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
934
935                                  07 Aug 2006                     jarsigner(1)
Impressum