OSDN Git Service

libjava/classpath/
[pf3gnuchains/gcc-fork.git] / libjava / classpath / doc / cp-tools.texinfo
1 \input texinfo @c -*-texinfo-*-
2
3 @c %**start of header
4 @setfilename cp-tools.info
5 @settitle GNU Classpath Tools Guide
6 @c %**end of header
7
8 @setchapternewpage on
9
10 @c Common macros to support generating man pages:
11
12 @macro gcctabopt{body}
13 @code{\body\}
14 @end macro
15 @macro gccoptlist{body}
16 @smallexample
17 \body\
18 @end smallexample
19 @end macro
20
21 @ifinfo
22 This file documents the Tools included in a standard distribution of the GNU
23 Classpath project deliverables.
24
25 Copyright (C) 2006, 2007 Free Software Foundation, Inc.
26
27 @ifnotplaintext
28 @dircategory GNU Libraries
29 @direntry
30 * Classpath Tools: (cp-tools).  GNU Classpath Tools Guide
31 @end direntry
32 @end ifnotplaintext
33 @end ifinfo
34
35 @titlepage
36 @title GNU Classpath Tools Guide
37 @author The GNU Classpath Team
38
39 @page
40 @vskip 0pt plus 1filll
41 Copyright @copyright{} 2006 Free Software Foundation, Inc.
42 @sp 2
43 Permission is granted to make and distribute verbatim copies of this document provided the copyright notice and this permission notice are preserved on all copies.
44
45 Permission is granted to copy and distribute modified versions of this document under the conditions for verbatim copying, provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one.
46
47 Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions, except that this permission notice may be stated in a translation approved by the Free Software Foundation.
48
49 @end titlepage
50
51 @contents
52
53 @ifinfo
54 @node Top, Applet Tools, (dir), (dir)
55 @top GNU Classpath Tools Guide
56
57 This document contains important information you need to know in order to use
58 the tools included in the GNU Classpath project deliverables.
59
60 The Tools aim at providing a free replacement, similar in their behavior, to
61 their counter-parts found in the Reference Implementation (RI) of the Java
62 Software Development Kit (SDK).
63
64 @end ifinfo
65
66 @menu
67 * Applet Tools::               Work with applets
68 * Security Tools::             Work securely with Java applications
69 * Other Tools::                Other tools in classpath
70 * I18N Issues::                How to add support for non-English languages
71
72 @detailmenu
73  --- The Detailed Node Listing ---
74
75 Applet Tools
76
77 * appletviewer Tool::          Load applets
78 * gcjwebplugin::               Load applets in a web browser
79
80 Security Tools
81
82 * jarsigner Tool::             Sign and verify .JAR files
83 * keytool Tool::               Manage private keys and public certificates
84
85 jarsigner Tool
86
87 * Common jarsigner Options::   Options used when signing or verifying a file
88 * Signing Options::            Options only used when signing a .JAR file
89 * Verification Options::       Options only used when verifying a .JAR file
90
91 keytool Tool
92
93 * Getting Help::               How to get help with keytool commands
94 * Common keytool Options::     Options used in more than one command
95 * Distinguished Names::        X.500 Distinguished Names used in certificates
96 * Add/Update Commands::        Commands for adding data to a Key Store
97 * Export Commands::            Commands for exporting data from a Key Store
98 * Display Commands::           Commands for displaying data in a Key Store
99 * Management Commands::        Commands for managing a Key Store
100
101 Add/Update Commands
102
103 * Command -genkey::            Generate private key and self-signed certificate
104 * Command -import::            Import certificates and certificate replies
105 * Command -selfcert::          Generate self-signed certificate
106 * Command -cacert::            Import a CA Trusted Certificate
107 * Command -identitydb::        Import JDK-1 style identities
108
109 Export Commands
110
111 * Command -certreq::           Generate Certificate Signing Requests (CSR)
112 * Command -export::            Export a certificate in a Key Store
113
114 Display Commands
115
116 * Command -list::              Display information about one or all Aliases
117 * Command -printcert::         Print a certificate or a certificate fingerprint
118
119 Management Commands
120
121 * Command -keyclone::          Clone a Key Entry in a Key Store
122 * Command -storepasswd::       Change the password protecting a Key Store
123 * Command -keypasswd::         Change the password protecting a Key Entry
124 * Command -delete::            Remove an entry in a Key Store
125
126 Other Tools
127
128 * jar Tool::                   Archive tool for Java archives
129 * javah Tool::                 A java header compiler
130 * gcjh Tool::                  A java header compiler (old version)
131 * native2ascii Tool::          An encoding converter
132 * orbd Tool::                  An object request broker daemon
133 * serialver Tool::             A serial version command
134 * rmid Tool::                  RMI activation daemon
135 * rmiregistry Tool::           Remote object registry
136 * tnameserv Tool::             Naming service
137
138 I18N Issues
139
140 * Language Resources::         Where resources are located
141 * Message Formats::            How messages are internationalized
142
143 @end detailmenu
144 @end menu
145
146 @comment ----------------------------------------------------------------------
147
148 @node Applet Tools, Security Tools, Top, Top
149 @comment node-name, next, previous, up
150 @chapter Applet Tools
151
152 Two Applet Tools are available with GNU Classpath: @b{appletviewer}
153 and @b{gcjwebplugin}.
154
155 To avoid conflicts with other implementations, the appletviewer
156 executable is called ``gappletviewer''.
157
158 @menu
159 * appletviewer Tool::          Load applets
160 * gcjwebplugin::               Load applets in a web browser
161 @end menu
162
163 If while using these tools you think you found a bug, then please report it at @uref{http://www.gnu.org/software/classpath/bugs.html,classpath-bugs}.
164
165 @comment ----------------------------------------------------------------------
166
167 @node appletviewer Tool, gcjwebplugin, Applet Tools, Applet Tools
168 @comment node-name, next, previous, up
169 @section The @code{appletviewer} Tool
170 @c man title gappletviewer Load and runs an applet
171
172 SYNOPSIS
173
174 @c man begin SYNOPSIS gappletviewer
175 appletviewer [@var{OPTION}]@dots{} @var{URL}@dots{} @var{@*}
176
177 appletviewer [@var{OPTION}]@dots{} @option{-code} @var{CODE} @var{@*}
178
179 appletviewer [@var{OPTION}]@dots{} @option{-plugin} @var{INPUT},@var{OUTPUT}
180 @c man end
181
182 DESCRIPTION
183 @c man begin DESCRIPTION gappletviewer
184 The @command{appletviewer} tool loads and runs an applet.
185
186 Use the first form to test applets specified by tag.  The URL should
187 resolve to an HTML document from which the @command{appletviewer} will
188 extract applet tags.  The APPLET, EMBED and OBJECT tags are supported.
189 If a given document contains multiple applet tags, all the applets
190 will be loaded, with each applet appearing in its own window.
191 Likewise, when multiple URLs are specified, each applet tag instance
192 is given its own window.  If a given document contains no recognized
193 tags the @command{appletviewer} does nothing.
194
195 @smallexample
196 appletviewer http://www.gnu.org/software/classpath/
197 @end smallexample
198
199 Use the second form to test an applet in development.  This form
200 allows applet tag attributes to be supplied on the command line.  Only
201 one applet may be specified using the @option{-code} option.  The
202 @option{-code} option overrides the URL form -- any URLs specified will
203 be ignored.
204
205 @smallexample
206 appletviewer -code Test.class -param datafile,data.txt
207 @end smallexample
208
209 @command{gcjwebplugin} uses the third form to communicate with the
210 @command{appletviewer} through named pipes.
211 @c man end
212
213 @c man begin OPTIONS gappletviewer
214 URL OPTIONS
215 @table @gcctabopt
216 @item -debug
217 This option is not yet implemented but is provided for compatibility.
218
219 @item -encoding @var{CHARSET}
220 Use this option to specify an alternate character encoding for the
221 specified HTML page.
222
223 @end table
224
225 APPLET TAG OPTIONS
226 @table @gcctabopt
227 @item -code @var{CODE}
228 Use the @option{-code} option to specify the value of the applet tag
229 @var{CODE} attribute.
230
231 @item -codebase @var{CODEBASE}
232 Use the @option{-codebase} option to specify the value of the applet tag
233 @var{CODEBASE} attribute.
234
235 @item -archive @var{ARCHIVE}
236 Use the @option{-archive} option to specify the value of the applet tag
237 @var{ARCHIVE} attribute.
238
239 @item -width @var{WIDTH}
240 Use the @option{-width} option to specify the value of the applet tag
241 @var{WIDTH} attribute.
242
243 @item -height @var{HEIGHT}
244 Use the @option{-height} option to specify the value of the applet tag
245 @var{HEIGHT} attribute.
246
247 @item -param @var{NAME},@var{VALUE}
248 Use the @option{-param} option to specify values for the @var{NAME}
249 and @var{VALUE} attributes of an applet PARAM tag.
250
251 @end table
252
253 PLUGIN OPTION
254 @table @gcctabopt
255 @item -plugin @var{INPUT},@var{OUTPUT}
256 @command{gcjwebplugin} uses the @option{-plugin} option to specify the
257 named pipe the @command{appletviewer} should use for receiving commands
258 (@var{INPUT}) and the one it should use for sending commands to
259 @command{gcjwebplugin} (@var{OUTPUT}).
260
261 @end table
262
263 DEBUGGING OPTION
264 @table @gcctabopt
265 @item -verbose
266 Use the @option{-verbose} option to have the @command{appletviewer} print
267 debugging messages.
268
269 @end table
270
271 STANDARD OPTIONS
272
273 @table @gcctabopt
274 @item -help
275 Use the @option{-help} option to have the @command{appletviewer} print a
276 usage message, then exit.
277
278 @item -version
279 Use the @option{-version} option to have the @command{appletviewer} print
280 its version, then exit.
281
282 @item -J@var{OPTION}
283 Use the @option{-J} option to pass @var{OPTION} to the virtual machine that
284 will run the @command{appletviewer}.  Unlike other options, there must
285 not be a space between the @option{-J} and @var{OPTION}.
286
287 @end table
288 @c man end
289
290 @comment ----------------------------------------------------------------------
291
292 @node gcjwebplugin, , appletviewer Tool, Applet Tools
293 @comment node-name, next, previous, up
294 @section The @code{gcjwebplugin} Tool
295
296 @code{gcjwebplugin} is a plugin that adds applet support to web
297 browsers.  Currently @code{gcjwebplugin} only supports Mozilla-based
298 browsers (e.g., Firefox, Galeon, Mozilla).
299
300 @comment ----------------------------------------------------------------------
301
302 @node Security Tools, Other Tools, Applet Tools, Top
303 @comment node-name, next, previous, up
304 @chapter Security Tools
305
306 Two Security Tools are available with GNU Classpath:
307 @command{jarsigner} and @command{keytool}.
308
309 To avoid conflicts with other implementations, the jarsigner
310 executable is called @command{gjarsigner} and the keytool executable is
311 called @command{gkeytool}.
312
313 @menu
314 * jarsigner Tool::             Sign and verify .JAR files
315 * keytool Tool::               Manage private keys and public certificates
316 @end menu
317
318 If while using these tools you think you found a bug, then please report it at @uref{http://www.gnu.org/software/classpath/bugs.html,classpath-bugs}.
319
320 @comment ----------------------------------------------------------------------
321
322 @node jarsigner Tool, keytool Tool, Security Tools, Security Tools
323 @comment node-name, next, previous, up
324 @section The @code{jarsigner} Tool
325 @c man title gjarsigner Java ARchive (JAR) file signing and verification tool
326
327 The @command{jarsigner} tool is invoked from the command line, in one
328 of two forms, as follows:
329
330 @example
331 @c man begin SYNOPSIS gjarsigner
332 jarsigner [@var{OPTION}]@dots{} @var{FILE} @var{ALIAS}
333
334 jarsigner @option{-verify} [@var{OPTION}]@dots{} @var{FILE}
335 @c man end
336 @end example
337
338 @c man begin DESCRIPTION gjarsigner
339 When the first form is used, the tool signs the designated JAR file. The second form, on the other hand, is used to verify a previously signed JAR file.
340
341 @var{FILE} is the .JAR file to process; i.e. to sign if the first syntax form is used, or to verify if the second syntax form is used instead.
342
343 @var{ALIAS} must be a known @i{Alias} of a @i{Key Entry} in the designated @i{Key Store}. The private key material associated with this @i{Alias} is then used for signing the designated .JAR file.
344 @c man end
345
346 @menu
347 * Common jarsigner Options::   Options used when signing or verifying a file
348 * Signing Options::            Options only used when signing a .JAR file
349 * Verification Options::       Options only used when verifying a .JAR file
350 @end menu
351
352 @comment ----------------------------------------------------------------------
353
354 @node Common jarsigner Options, Signing Options, jarsigner Tool, jarsigner Tool
355 @comment node-name, next, previous, up
356 @c man begin OPTIONS gjarsigner
357 @subsection Common options
358
359 The following options may be used when the tool is used for either signing, or verifying, a .JAR file.
360
361 @table @gcctabopt
362 @item -verbose
363 Use this option to force the tool to generate more verbose messages, during its processing.
364
365 @item -internalsf
366 When present, the tool will include --which otherwise it does not-- the @code{.SF} file in the @code{.DSA} generated file.
367
368 @item -sectionsonly
369 When present, the tool will include in the @code{.SF} generated file --which otherwise it does not-- a header containing a hash of the whole manifest file.  When that header is included, the tool can quickly check, during verification, if the hash (in the header) matches or not the manifest file.
370
371 @item -provider PROVIDER_CLASS_NAME
372 A fully qualified class name of a @i{Security Provider} to add to the current list of @i{Security Providers} already installed in the JVM in-use. If a provider class is specified with this option, and was successfully added to the runtime --i.e. it was not already installed-- then the tool will attempt to remove this @i{Security Provider} before exiting.
373
374 @item -help
375 Prints a help text similar to this one.
376
377 @end table
378 @c man end
379
380 @comment ----------------------------------------------------------------------
381
382 @node Signing Options, Verification Options, Common jarsigner Options, jarsigner Tool
383 @comment node-name, next, previous, up
384 @c man begin OPTIONS gjarsigner
385 @subsection Signing options
386
387 The following options may be specified when using the tool for signing purposes.
388
389 @table @gcctabopt
390 @item -keystore @var{URL}
391 Use this option to specify the location of the key store to use. The default value is a file URL referencing the file named @file{.keystore} located in the path returned by the call to @code{java.lang.System#getProperty(String)} using @code{user.home} as argument.
392
393 If a URL was specified, but was found to be malformed --e.g. missing protocol element-- the tool will attempt to use the URL value as a file-name (with absolute or relative path-name) of a key store --as if the protocol was @code{file:}.
394
395 @item -storetype @var{STORE_TYPE}
396 Use this option to specify the type of the key store to use. The default value, if this option is omitted, is that of the property @code{keystore.type} in the security properties file, which is obtained by invoking the static method call @code{getDefaultType()} in @code{java.security.KeyStore}.
397
398 @item -storepass @var{PASSWORD}
399 Use this option to specify the password which will be used to unlock the key store. If this option is missing, the User will be prompted to provide a password.
400
401 @item -keypass @var{PASSWORD}
402 Use this option to specify the password which the tool will use to unlock the @i{Key Entry} associated with the designated @i{Alias}.
403
404 If this option is omitted, the tool will first attempt to unlock the @i{Key Entry} using the same password protecting the key store. If this fails, you will then be prompted to provide a password.
405
406 @item -sigfile @var{NAME}
407 Use this option to designate a literal that will be used to construct file names for both the @code{.SF} and @code{.DSA} signature files. These files  will be generated, by the tool, and placed in the @file{META-INF} directory of the signed JAR.  Permissible characters for @var{NAME} must be in the range "a-zA-Z0-9_-".  All characters will be converted to upper-case ones.
408
409 If this option is missing, the first eight characters of the @var{ALIAS} argument will be used. When this is the case, any character in @var{ALIAS} that is outside the permissible range of characters will be replaced by an underscore.
410
411 @item -signedjar @var{FILE}
412 Use this option to specify the file name of the signed JAR. If this option is omitted, then the signed JAR will be named the same as @var{FILE}; i.e. the input JAR file will be replaced with the signed copy.
413
414 @end table
415 @c man end
416
417 @comment ----------------------------------------------------------------------
418
419 @node Verification Options, , Signing Options, jarsigner Tool
420 @comment node-name, next, previous, up
421 @c man begin OPTIONS gjarsigner
422 @subsection Verification options
423
424 The following options may be specified when using the tool for verification purposes.
425
426 @table @gcctabopt
427 @item -verify
428 Use this option to indicate that the tool is to be used for verification purposes.
429
430 @item -certs
431 This option is used in conjunction with the @option{-verbose} option. When present, along with the @option{-verbose} option, the tool will print more detailed information about the certificates of the signer(s) being processed.
432
433 @end table
434 @c man end
435
436 @comment ----------------------------------------------------------------------
437
438 @node keytool Tool, , jarsigner Tool, Security Tools
439 @comment node-name, next, previous, up
440 @section The @code{keytool} Tool
441 @c man title gkeytool Manage private keys and public certificates
442
443 @ignore
444 @c man begin SYNOPSIS gkeytool
445 keytool [@var{COMMAND}] @dots{}
446 @c man end
447 @end ignore
448
449 @c man begin DESCRIPTION gkeytool
450 Cryptographic credentials, in a Java environment, are usually stored in a @i{Key Store}. The Java SDK specifies a @i{Key Store} as a persistent container of two types of objects: @i{Key Entries} and @i{Trusted Certificates}. The security tool @command{keytool} is a Java-based application for managing those types of objects.
451
452 A @i{Key Entry} represents the private key part of a key-pair used in Public-Key Cryptography, and a signed X.509 certificate which authenticates the public key part for a known entity; i.e. the owner of the key-pair. The X.509 certificate itself contains the public key part of the key-pair.
453
454 A @i{Trusted Certificate} is a signed X.509 certificate issued by a trusted entity. The @i{Trust} in this context is relative to the User of the @command{keytool}. In other words, the existence of a @i{Trusted Certificate} in the @i{Key Store} processed by a @command{keytool} command implies that the User trusts the @i{Issuer} of that @i{Trusted Certificate} to also sign, and hence authenticates, other @i{Subjects} the tool may process.
455
456 @i{Trusted Certificates} are important because they allow the tool to mechanically construct @i{Chains of Trust} starting from one of the @i{Trusted Certificates} in a @i{Key Store} and ending with a certificate whose @i{Issuer} is potentially unknown. A valid chain is an ordered list, starting with a @i{Trusted Certificate} (also called the @i{anchor}), ending with the target certificate, and satisfying the condition that the @i{Subject} of certificate @code{#i} is the @i{Issuer} of certificate @code{#i + 1}.
457
458 The @command{keytool} is invoked from the command line as follows:
459
460 @smallexample
461 keytool [COMMAND] ...
462 @end smallexample
463
464 Multiple @var{COMMAND}s may be specified at once, each complete with its own options. @command{keytool} will parse all the arguments, before processing, and executing, each @code{COMMAND}. If an exception occurs while executing one @var{COMMAND} @command{keytool} will abort. Note however that because the implementation of the tool uses code to parse command line options that also supports GNU-style options, you have to separate each command group with a double-hyphen; e.g
465
466 @smallexample
467 keytool -list -- -printcert -alias mykey
468 @end smallexample
469 @c man end
470
471 Here is a summary of the commands supported by the tool:
472
473 @c man begin OPTIONS gkeytool
474 @enumerate
475 @item Add/Update commands
476 @table @gcctabopt
477 @item -genkey [@var{OPTION}]@dots{}
478 Generate a new @i{Key Entry}, eventually creating a new key store.
479
480 @item -import [@var{OPTION}]@dots{}
481 Add, to a key store, @i{Key Entries} (private keys and certificate chains authenticating the public keys) and @i{Trusted Certificates} (3rd party certificates which can be used as @i{Trust Anchors} when building chains-of-trust).
482
483 @item -selfcert [@var{OPTION}]@dots{}
484 Generate a new self-signed @i{Trusted Certificate}.
485
486 @item -cacert [@var{OPTION}]@dots{}
487 Import a CA @i{Trusted Certificate}.
488
489 @item -identitydb [@var{OPTION}]@dots{}
490 @b{NOT IMPLEMENTED YET}.@*
491 Import a JDK 1.1 style Identity Database.
492 @end table
493
494 @item Export commands
495 @table @gcctabopt
496 @item -certreq [@var{OPTION}]@dots{}
497 Issue a @i{Certificate Signing Request} (CSR) which can be then sent to a @i{Certification Authority} (CA) to issue a certificate signed (by the CA) and authenticating the @i{Subject} of the request.
498
499 @item -export [@var{OPTION}]@dots{}
500 Export a certificate from a key store.
501 @end table
502
503 @item  Display commands
504 @table @gcctabopt
505 @item -list [@var{OPTION}]@dots{}
506 Print one or all certificates in a key store to @code{STDOUT}.
507
508 @item -printcert [@var{OPTION}]@dots{}
509 Print a human-readable form of a certificate, in a designated file, to @code{STDOUT}.
510 @end table
511
512 @item Management commands
513 @table @gcctabopt
514 @item -keyclone [@var{OPTION}]@dots{}
515 Clone a @i{Key Entry} in a key store.
516
517 @item -storepasswd [@var{OPTION}]@dots{}
518 Change the password protecting a key store.
519
520 @item -keypasswd [@var{OPTION}]@dots{}
521 Change the password protecting a @i{Key Entry} in a key store.
522
523 @item -delete [@var{OPTION}]@dots{}
524 Delete a @i{Key Entry} or a @i{Trusted Certificate} from a key store.
525 @end table
526 @end enumerate
527 @c man end
528
529 @menu
530 * Getting Help::               How to get help with keytool commands
531 * Common keytool Options::     Options used in more than one command
532 * Distinguished Names::        X.500 Distinguished Names used in certificates
533 * Add/Update Commands::        Commands for adding data to a Key Store
534 * Export Commands::            Commands for exporting data from a Key Store
535 * Display Commands::           Commands for displaying data in a Key Store
536 * Management Commands::        Commands for managing a Key Store
537 @end menu
538
539 @comment ----------------------------------------------------------------------
540
541 @node Getting Help, Common keytool Options, keytool Tool, keytool Tool
542 @comment node-name, next, previous, up
543 @subsection Getting help
544
545 To get a general help text about the tool, use the @code{-help} option; e.g.
546
547 @example
548 @code{keytool -help}
549 @end example
550
551 To get more specific help text about one of the tool's command use the @code{-help} option for that command; e.g.
552
553 @example
554 @code{keytool -genkey -help}
555 @end example
556
557 In both instances, the tool will print a help text and then will exit the running JVM.
558
559 It is worth noting here that the help messages printed by the tool are I18N-ready. This means that if/when the contents of the tool's @i{Message Bundle} properties file are available in languages other than English, you may see those messages in that language.
560
561 @comment ----------------------------------------------------------------------
562
563 @node Common keytool Options, Distinguished Names, Getting Help, keytool Tool
564 @comment node-name, next, previous, up
565 @c man begin OPTIONS gkeytool
566 @subsection Common options
567
568 The following @option{OPTION}s are used in more than one @command{COMMAND}. They are described here to reduce redundancy.
569
570 @table @gcctabopt
571 @anchor{alias}
572 @item -alias @var{Alias}
573 Every entry, be it a @i{Key Entry} or a @i{Trusted Certificate}, in a key store is uniquely identified by a user-defined @var{Alias} string. Use this option to specify the @var{Alias} to use when referring to an entry in the key store. Unless specified otherwise, a default value of @code{mykey} shall be used when this option is omitted from the command line.
574
575 @anchor{keyalg}
576 @item -keyalg @var{ALGORITHM}
577 Use this option to specify the canonical name of the key-pair generation algorithm. The default value for this option is @code{DSS} (a synonym for the Digital Signature Algorithm also known as DSA).
578
579 @anchor{keysize}
580 @item -keysize @var{SIZE}
581 Use this option to specify the number of bits of the shared modulus (for both the public and private keys) to use when generating new keys. A default value of @code{1024} will be used if this option is omitted from the command line.
582
583 @anchor{validity}
584 @item -validity @var{DAY_COUNT}
585 Use this option to specify the number of days a newly generated certificate will be valid for. The default value is @code{90} (days) if this option is omitted from the command line.
586
587 @anchor{storetype}
588 @item -storetype @var{STORE_TYPE}
589 Use this option to specify the type of the key store to use. The default value, if this option is omitted, is that of the property @code{keystore.type} in the security properties file, which is obtained by invoking the static method call @code{getDefaultType()} in @code{java.security.KeyStore}.
590
591 @anchor{storepass}
592 @item -storepass @var{PASSWORD}
593 Use this option to specify the password protecting the key store. If this option is omitted from the command line, you will be prompted to provide a password.
594
595 @anchor{keystore}
596 @item -keystore @var{URL}
597 Use this option to specify the location of the key store to use. The default value is a file URL referencing the file named @file{.keystore} located in the path returned by the call to @code{java.lang.System#getProperty(String)} using @code{user.home} as argument.
598
599 If a URL was specified, but was found to be malformed --e.g. missing protocol element-- the tool will attempt to use the URL value as a file-name (with absolute or relative path-name) of a key store --as if the protocol was @code{file:}.
600
601 @anchor{provider}
602 @item -provider @var{PROVIDER_CLASS_NAME}
603 A fully qualified class name of a @i{Security Provider} to add to the current list of @i{Security Providers} already installed in the JVM in-use. If a provider class is specified with this option, and was successfully added to the runtime --i.e. it was not already installed-- then the tool will attempt to removed this @i{Security Provider} before exiting.
604
605 @anchor{file}
606 @item -file @var{FILE}
607 Use this option to designate a file to use with a command. When specified with this option, the value is expected to be the fully qualified path of a file accessible by the File System. Depending on the command, the file may be used as input or as output. When this option is omitted from the command line, @code{STDIN} will be used instead, as the source of input, and @code{STDOUT} will be used instead as the output destination.
608
609 @anchor{verbose}
610 @item -v
611 Unless specified otherwise, use this option to enable more verbose output.
612
613 @end table
614 @c man end
615
616 @comment ----------------------------------------------------------------------
617
618 @node Distinguished Names, Add/Update Commands, Common keytool Options, keytool Tool
619 @comment node-name, next, previous, up
620 @subsection X.500 Distinguished Names
621
622 @anchor{dn}
623 A @i{Distinguished Name} (or DN) MUST be supplied with some of the @code{COMMAND}s using a @code{-dname} option. The syntax of a valid value for this option MUST follow RFC-2253 specifications. Namely the following components (with their accepted meaning) will be recognized. Note that the component name is case-insensitive:
624
625 @ftable @var
626 @item CN
627 The Common Name; e.g. @kbd{host.domain.com}
628 @item OU
629 The Organizational Unit; e.g. @kbd{IT Department}
630 @item O
631 The Organization Name; e.g. @kbd{The Sample Company}
632 @item L
633 The Locality Name; e.g. @kbd{Sydney}
634 @item ST
635 The State Name; e.g. @kbd{New South Wales}
636 @item C
637 The 2-letter Country identifier; e.g. @kbd{AU}
638 @end ftable
639
640 When specified with a @code{-dname} option, each pair of component/value will be separated from the other with a comma. Each component and value pair MUST be separated by an equal sign. For example, the following is a valid DN value:@*
641
642 @format
643 CN=host.domain.com, O=The Sample Company, L=Sydney, ST=NSW, C=AU
644 @end format
645 @*
646 If the @i{Distinguished Name} is required, and no valid default value can be used, the tool will prompt you to enter the information through the console.
647
648 @comment ----------------------------------------------------------------------
649
650 @node Add/Update Commands, Export Commands, Distinguished Names, keytool Tool
651 @comment node-name, next, previous, up
652 @c man begin OPTIONS gkeytool
653 @subsection Add/Update commands
654 @c man end
655
656 @menu
657 * Command -genkey::            Generate private key and self-signed certificate
658 * Command -import::            Import certificates and certificate replies
659 * Command -selfcert::          Generate self-signed certificate
660 * Command -cacert::            Import a CA Trusted Certificate
661 * Command -identitydb::        Import JDK-1 style identities
662 @end menu
663
664 @comment ----------------------------------------------------------------------
665
666 @node Command -genkey, Command -import, Add/Update Commands, Add/Update Commands
667 @comment node-name, next, previous, up
668 @c man begin OPTIONS gkeytool
669 @subsubsection The @option{-genkey} command
670
671 Use this command to generate a new key-pair (both private and public keys), and save these credentials in the key store as a @i{Key Entry}, associated with the designated (if was specified with the @option{-alias} option) or default (if the @option{-alias} option is omitted) @i{Alias}.
672
673 The private key material will be protected with a user-defined password (see @option{-keypass} option). The public key on the other hand will be part of a self-signed X.509 certificate, which will form a 1-element chain and will be saved in the key store.
674
675 @table @gcctabopt
676 @item -alias @var{ALIAS}
677 For more details @pxref{alias,, ALIAS}.
678
679 @item -keyalg @var{ALGORITHM}
680 For more details @pxref{keyalg,, ALGORITHM}.
681
682 @item -keysize @var{KEY_SIZE}
683 For more details @pxref{keysize,, KEY_SIZE}.
684
685 @item -sigalg @var{ALGORITHM}
686 The canonical name of the digital signature algorithm to use for signing certificates. If this option is omitted, a default value will be chosen based on the type of the key-pair; i.e. the algorithm that ends up being used by the -keyalg option. If the key-pair generation algorithm is @code{DSA}, the value for the signature algorithm will be @code{SHA1withDSA}. If on the other hand the key-pair generation algorithm is @code{RSA}, then the tool will use @code{MD5withRSA} as the signature algorithm.
687
688 @item -dname @var{NAME}
689 This a mandatory value for the command. If no value is specified --i.e. the @option{-dname} option is omitted-- the tool will prompt you to enter a @i{Distinguished Name} to use as both the @i{Owner} and @i{Issuer} of the generated self-signed certificate.
690
691 For more details @pxref{dn,, X.500 DISTINGUISHED NAME}.
692
693 @item -keypass @var{PASSWORD}
694 Use this option to specify the password which the tool will use to protect the newly created @i{Key Entry}.
695
696 If this option is omitted, you will be prompted to provide a password.
697
698 @item -validity @var{DAY_COUNT}
699 For more details @pxref{validity,, DAY_COUNT}.
700
701 @item -storetype @var{STORE_TYPE}
702 For more details @pxref{storetype,, STORE_TYPE}.
703
704 @item -keystore @var{URL}
705 For more details @pxref{keystore,, URL}.
706
707 @item -storepass @var{PASSWORD}
708 For more details @pxref{storepass,, PASSWORD}.
709
710 @item -provider @var{PROVIDER_CLASS_NAME}
711 For more details @pxref{provider,, PROVIDER_CLASS_NAME}.
712
713 @item -v
714 For more details @pxref{verbose}.
715
716 @end table
717 @c man end
718
719 @comment ----------------------------------------------------------------------
720
721 @node Command -import, Command -selfcert, Command -genkey, Add/Update Commands
722 @comment node-name, next, previous, up
723 @c man begin OPTIONS gkeytool
724 @subsubsection The @option{-import} command
725
726 Use this command to read an X.509 certificate, or a PKCS#7 @i{Certificate Reply} from a designated input source and incorporate the certificates into the key store.
727
728 If the @i{Alias} does not already exist in the key store, the tool treats the certificate read from the input source as a new @i{Trusted Certificate}. It then attempts to discover a chain-of-trust, starting from that certificate and ending at another @i{Trusted Certificate}, already stored in the key store. If the @option{-trustcacerts} option is present, an additional key store, of type @code{JKS} named @file{cacerts}, and assumed to be present in @file{$@{JAVA_HOME@}/lib/security} will also be consulted if found --@code{$@{JAVA_HOME@}} refers to the location of an installed @i{Java Runtime Environment} (JRE). If no chain-of-trust can be established, and unless the @code{-noprompt} option has been specified, the certificate is printed to @code{STDOUT} and the user is prompted for a confirmation.
729
730 If @i{Alias} exists in the key store, the tool will treat the certificate(s) read from the input source as a @i{Certificate Reply}, which can be a chain of certificates, that eventually would replace the chain of certificates associated with the @i{Key Entry} of that @i{Alias}. The substitution of the certificates only occurs if a chain-of-trust can be established between the bottom certificate of the chain read from the input file and the @i{Trusted Certificates} already present in the key store. Again, if the @option{-trustcacerts} option is specified, additional @i{Trusted Certificates} in the same @file{cacerts} key store will be considered. If no chain-of-trust can be established, the operation will abort.
731
732 @table @gcctabopt
733 @item -alias @var{ALIAS}
734 For more details @pxref{alias,, ALIAS}.
735
736 @item -file @var{FILE}
737 For more details @pxref{file,, FILE}.
738
739 @item -keypass @var{PASSWORD}
740 Use this option to specify the password which the tool will use to protect the @i{Key Entry} associated with the designated @i{Alias}, when replacing this @i{Alias}' chain of certificates with that found in the certificate reply.
741
742 If this option is omitted, and the chain-of-trust for the certificate reply has been established, the tool will first attempt to unlock the @i{Key Entry} using the same password protecting the key store. If this fails, you will then be prompted to provide a password.
743
744 @item -noprompt
745 Use this option to prevent the tool from prompting the user.
746
747 @item -trustcacerts
748 Use this option to indicate to the tool that a key store, of type @code{JKS}, named @file{cacerts}, and usually located in @file{lib/security} in an installed @i{Java Runtime Environment} should be considered when trying to establish chain-of-trusts.
749
750 @item -storetype @var{STORE_TYPE}
751 For more details @pxref{storetype,, STORE_TYPE}.
752
753 @item -keystore @var{URL}
754 For more details @pxref{keystore,, URL}.
755
756 @item -storepass @var{PASSWORD}
757 For more details @pxref{storepass,, PASSWORD}.
758
759 @item -provider @var{PROVIDER_CLASS_NAME}
760 For more details @pxref{provider,, PROVIDER_CLASS_NAME}.
761
762 @item -v
763 For more details @pxref{verbose}.
764
765 @end table
766 @c man end
767
768 @comment ----------------------------------------------------------------------
769
770 @node Command -selfcert, Command -cacert, Command -import, Add/Update Commands
771 @comment node-name, next, previous, up
772 @c man begin OPTIONS gkeytool
773 @subsubsection The @option{-selfcert} command
774
775 Use this command to generate a self-signed X.509 version 1 certificate. The newly generated certificate will form a chain of one element which will replace the previous chain associated with the designated @i{Alias} (if @option{-alias} option was specified), or the default @i{Alias} (if @option{-alias} option was omitted).
776
777 @table @gcctabopt
778 @item -alias @var{ALIAS}
779 For more details @pxref{alias,, ALIAS}.
780
781 @item -sigalg @var{ALGORITHM}
782 The canonical name of the digital signature algorithm to use for signing the certificate. If this option is omitted, a default value will be chosen based on the type of the private key associated with the designated @i{Alias}. If the private key is a @code{DSA} one, the value for the signature algorithm will be @code{SHA1withDSA}. If on the other hand the private key is an @code{RSA} one, then the tool will use @code{MD5withRSA} as the signature algorithm.
783
784 @item -dname @var{NAME}
785 Use this option to specify the @i{Distinguished Name} of the newly generated self-signed certificate. If this option is omitted, the existing @i{Distinguished Name} of the base certificate in the chain associated with the designated @i{Alias} will be used instead.
786
787 For more details @pxref{dn,, X.500 DISTINGUISHED NAME}.
788
789 @item -validity @var{DAY_COUNT}
790 For more details @pxref{validity,, DAY_COUNT}.
791
792 @item -keypass @var{PASSWORD}
793 Use this option to specify the password which the tool will use to unlock the @i{Key Entry} associated with the designated @i{Alias}.
794
795 If this option is omitted, the tool will first attempt to unlock the @i{Key Entry} using the same password protecting the key store. If this fails, you will then be prompted to provide a password.
796
797 @item -storetype @var{STORE_TYPE}
798 For more details @pxref{storetype,, STORE_TYPE}.
799
800 @item -keystore @var{URL}
801 For more details @pxref{keystore,, URL}.
802
803 @item -storepass @var{PASSWORD}
804 For more details @pxref{storepass,, PASSWORD}.
805
806 @item -provider @var{PROVIDER_CLASS_NAME}
807 For more details @pxref{provider,, PROVIDER_CLASS_NAME}.
808
809 @item -v
810 For more details @pxref{verbose}.
811
812 @end table
813 @c man end
814
815 @comment ----------------------------------------------------------------------
816
817 @node Command -cacert, Command -identitydb, Command -selfcert, Add/Update Commands
818 @comment node-name, next, previous, up
819 @c man begin OPTIONS gkeytool
820 @subsubsection The @option{-cacert} command
821
822 Use this command to import, a CA certificate and add it to the key store as a @i{Trusted Certificate}. The @i{Alias} for this new entry will be constructed from the FILE's base-name after replacing hyphens and dots with underscores.
823
824 This command is useful when used in a script that recursively visits a directory of CA certificates to populate a @code{cacerts.gkr} @i{Key Store} of trusted certificates which can then be used commands that specify the @option{-trustcacerts} option.
825
826 @table @gcctabopt
827 @item -file @var{FILE}
828 For more details @pxref{file,, FILE}.
829
830 @item -storetype @var{STORE_TYPE}
831 For more details @pxref{storetype,, STORE_TYPE}.
832
833 @item -keystore @var{URL}
834 For more details @pxref{keystore,, URL}.
835
836 @item -storepass @var{PASSWORD}
837 For more details @pxref{storepass,, PASSWORD}.
838
839 @item -provider @var{PROVIDER_CLASS_NAME}
840 For more details @pxref{provider,, PROVIDER_CLASS_NAME}.
841
842 @item -v
843 For more details @pxref{verbose}.
844
845 @end table
846 @c man end
847
848 @comment ----------------------------------------------------------------------
849
850 @node Command -identitydb, , Command -cacert, Add/Update Commands
851 @comment node-name, next, previous, up
852 @c man begin OPTIONS gkeytool
853 @subsubsection The @option{-identitydb} command
854
855 @b{NOT IMPLEMENTED YET}.
856
857 Use this command to import a JDK 1.1 style Identity Database.
858
859 @table @gcctabopt
860 @item -file @var{FILE}
861 For more details @pxref{file,, FILE}.
862
863 @item -storetype @var{STORE_TYPE}
864 For more details @pxref{storetype,, STORE_TYPE}.
865
866 @item -keystore @var{URL}
867 For more details @pxref{keystore,, URL}.
868
869 @item -storepass @var{PASSWORD}
870 For more details @pxref{storepass,, PASSWORD}.
871
872 @item -provider @var{PROVIDER_CLASS_NAME}
873 For more details @pxref{provider,, PROVIDER_CLASS_NAME}.
874
875 @item -v
876 For more details @pxref{verbose}.
877
878 @end table
879 @c man end
880
881 @comment ----------------------------------------------------------------------
882
883 @node Export Commands, Display Commands, Add/Update Commands, keytool Tool
884 @comment node-name, next, previous, up
885 @c man begin OPTIONS gkeytool
886 @subsection Export commands
887 @c man end
888
889 @menu
890 * Command -certreq::           Generate Certificate Signing Requests (CSR)
891 * Command -export::            Export a certificate in a Key Store
892 @end menu
893
894 @comment ----------------------------------------------------------------------
895
896 @node Command -certreq, Command -export, Export Commands, Export Commands
897 @comment node-name, next, previous, up
898 @c man begin OPTIONS gkeytool
899 @subsubsection The @option{-certreq} command
900
901 Use this command to generate a PKCS#10 @i{Certificate Signing Request} (CSR) and write it to a designated output destination. The contents of the destination should look something like the following:
902
903 @example
904 -----BEGIN NEW CERTIFICATE REQUEST-----
905 MI...QAwXzEUMBIGA1UEAwwLcnNuQGdudS5vcmcxGzAZBgNVBAoMElUg
906 Q2...A0GA1UEBwwGU3lkbmV5MQwwCgYDVQQIDANOU1cxCzAJBgNVBACC
907 ...
908 FC...IVwNVOfQLRX+O5kAhQ/a4RTZme2L8PnpvgRwrf7Eg8D6w==
909 -----END NEW CERTIFICATE REQUEST-----
910 @end example
911
912 @b{IMPORTANT}: Some documentation (e.g. RSA examples) claims that the @code{Attributes} field, in the CSR is @code{OPTIONAL} while RFC-2986 implies the opposite. This implementation considers this field, by default, as @code{OPTIONAL}, unless the option @option{-attributes} is specified on the command line.
913
914 @table @gcctabopt
915 @item -alias @var{ALIAS}
916 For more details @pxref{alias,, ALIAS}.
917
918 @item -sigalg @var{ALGORITHM}
919 The canonical name of the digital signature algorithm to use for signing the certificate. If this option is omitted, a default value will be chosen based on the type of the private key associated with the designated @i{Alias}. If the private key is a @code{DSA} one, the value for the signature algorithm will be @code{SHA1withDSA}. If on the other hand the private key is an @code{RSA} one, then the tool will use @code{MD5withRSA} as the signature algorithm.
920
921 @item -file @var{FILE}
922 For more details @pxref{file,, FILE}.
923
924 @item -keypass @var{PASSWORD}
925 Use this option to specify the password which the tool will use to unlock the @i{Key Entry} associated with the designated @i{Alias}.
926
927 If this option is omitted, the tool will first attempt to unlock the @i{Key Entry} using the same password protecting the key store. If this fails, you will then be prompted to provide a password.
928
929 @item -storetype @var{STORE_TYPE}
930 For more details @pxref{storetype,, STORE_TYPE}.
931
932 @item -keystore @var{URL}
933 For more details @pxref{keystore,, URL}.
934
935 @item -storepass @var{PASSWORD}
936 For more details @pxref{storepass,, PASSWORD}.
937
938 @item -provider @var{PROVIDER_CLASS_NAME}
939 For more details @pxref{provider,, PROVIDER_CLASS_NAME}.
940
941 @item -v
942 For more details @pxref{verbose}.
943
944 @item -attributes
945 Use this option to force the tool to encode a @code{NULL} DER value in the CSR as the value of the @code{Attributes} field.
946
947 @end table
948 @c man end
949
950 @comment ----------------------------------------------------------------------
951
952 @node Command -export, , Command -certreq, Export Commands
953 @comment node-name, next, previous, up
954 @c man begin OPTIONS gkeytool
955 @subsubsection The @option{-export} command
956
957 Use this command to export a certificate stored in a key store to a designated output destination, either in binary format (if the @option{-v} option is specified), or in RFC-1421 compliant encoding (if the @option{-rfc} option is specified instead).
958
959 @table @gcctabopt
960 @item -alias @var{ALIAS}
961 For more details @pxref{alias,, ALIAS}.
962
963 @item -file @var{FILE}
964 For more details @pxref{file,, FILE}.
965
966 @item -storetype @var{STORE_TYPE}
967 For more details @pxref{storetype,, STORE_TYPE}.
968
969 @item -keystore @var{URL}
970 For more details @pxref{keystore,, URL}.
971
972 @item -storepass @var{PASSWORD}
973 For more details @pxref{storepass,, PASSWORD}.
974
975 @item -provider @var{PROVIDER_CLASS_NAME}
976 For more details @pxref{provider,, PROVIDER_CLASS_NAME}.
977
978 @item -rfc
979 Use RFC-1421 specifications when encoding the output.
980
981 @item -v
982 Output the certificate in binary DER encoding. This is the default output format of the command if neither @option{-rfc} nor @code{-v} options were detected on the command line. If both this option and the @option{-rfc} option are detected on the command line, the tool will opt for the RFC-1421 style encoding.
983
984 @end table
985 @c man end
986
987 @comment ----------------------------------------------------------------------
988
989 @node Display Commands, Management Commands, Export Commands, keytool Tool
990 @comment node-name, next, previous, up
991 @c man begin OPTIONS gkeytool
992 @subsection Display commands
993 @c man end
994
995 @menu
996 * Command -list::              Display information about one or all Aliases
997 * Command -printcert::         Print a certificate or a certificate fingerprint
998 @end menu
999
1000 @comment ----------------------------------------------------------------------
1001
1002 @node Command -list, Command -printcert, Display Commands, Display Commands
1003 @comment node-name, next, previous, up
1004 @c man begin OPTIONS gkeytool
1005 @subsubsection The @option{-list} command
1006
1007 Use this command to print one or all of a key store entries to @code{STDOUT}. Usually this command will only print a @i{fingerprint} of the certificate, unless either the @option{-rfc} or the @option{-v} option is specified.
1008
1009 @table @gcctabopt
1010 @item -alias @var{ALIAS}
1011 If this option is omitted, the tool will print ALL the entries found in the key store.
1012
1013 For more details @pxref{alias,, ALIAS}.
1014
1015 @item -storetype @var{STORE_TYPE}
1016 For more details @pxref{storetype,, STORE_TYPE}.
1017
1018 @item -keystore @var{URL}
1019 For more details @pxref{keystore,, URL}.
1020
1021 @item -storepass @var{PASSWORD}
1022 For more details @pxref{storepass,, PASSWORD}.
1023
1024 @item -provider @var{PROVIDER_CLASS_NAME}
1025 For more details @pxref{provider,, PROVIDER_CLASS_NAME}.
1026
1027 @item -rfc
1028 Use RFC-1421 specifications when encoding the output.
1029
1030 @item -v
1031 Output the certificate in human-readable format. If both this option and the @option{-rfc} option are detected on the command line, the tool will opt for the human-readable form and will not abort the command.
1032
1033 @end table
1034 @c man end
1035
1036 @comment ----------------------------------------------------------------------
1037
1038 @node Command -printcert, , Command -list, Display Commands
1039 @comment node-name, next, previous, up
1040 @c man begin OPTIONS gkeytool
1041 @subsubsection The @option{-printcert} command
1042
1043 Use this command to read a certificate from a designated input source and print it to @code{STDOUT} in a human-readable form.
1044
1045 @table @gcctabopt
1046 @item -file @var{FILE}
1047 For more details @pxref{file,, FILE}.
1048
1049 @item -v
1050 For more details @pxref{verbose}.
1051
1052 @end table
1053 @c man end
1054
1055 @comment ----------------------------------------------------------------------
1056
1057 @node Management Commands, , Display Commands, keytool Tool
1058 @comment node-name, next, previous, up
1059 @c man begin OPTIONS gkeytool
1060 @subsection Management commands
1061 @c man end
1062
1063 @menu
1064 * Command -keyclone::          Clone a Key Entry in a Key Store
1065 * Command -storepasswd::       Change the password protecting a Key Store
1066 * Command -keypasswd::         Change the password protecting a Key Entry
1067 * Command -delete::            Remove an entry in a Key Store
1068 @end menu
1069
1070 @comment ----------------------------------------------------------------------
1071
1072 @node Command -keyclone, Command -storepasswd, Management Commands, Management Commands
1073 @comment node-name, next, previous, up
1074 @c man begin OPTIONS gkeytool
1075 @subsubsection The @option{-keyclone} command
1076
1077 Use this command to clone an existing @i{Key Entry} and store it under a new (different) @i{Alias} protecting, its private key material with possibly a new password.
1078
1079 @table @gcctabopt
1080 @item -alias @var{ALIAS}
1081 For more details @pxref{alias,, ALIAS}.
1082
1083 @item -dest @var{ALIAS}
1084 Use this option to specify the new @i{Alias} which will be used to identify the cloned copy of the @i{Key Entry}.
1085
1086 @item -keypass @var{PASSWORD}
1087 Use this option to specify the password which the tool will use to unlock the @i{Key Entry} associated with the designated @i{Alias}.
1088
1089 If this option is omitted, the tool will first attempt to unlock the @i{Key Entry} using the same password protecting the key store. If this fails, you will then be prompted to provide a password.
1090
1091 @item -new @var{PASSWORD}
1092 Use this option to specify the password protecting the private key material of the newly cloned copy of the @i{Key Entry}.
1093
1094 @item -storetype @var{STORE_TYPE}
1095 For more details @pxref{storetype,, STORE_TYPE}.
1096
1097 @item -keystore @var{URL}
1098 For more details @pxref{keystore,, URL}.
1099
1100 @item -storepass @var{PASSWORD}
1101 For more details @pxref{storepass,, PASSWORD}.
1102
1103 @item -provider @var{PROVIDER_CLASS_NAME}
1104 For more details @pxref{provider,, PROVIDER_CLASS_NAME}.
1105
1106 @item -v
1107 For more details @pxref{verbose}.
1108
1109 @end table
1110 @c man end
1111
1112 @comment ----------------------------------------------------------------------
1113
1114 @node Command -storepasswd, Command -keypasswd, Command -keyclone, Management Commands
1115 @comment node-name, next, previous, up
1116 @c man begin OPTIONS gkeytool
1117 @subsubsection The @option{-storepasswd} command
1118
1119 Use this command to change the password protecting a key store.
1120
1121 @table @gcctabopt
1122 @item -new @var{PASSWORD}
1123 The new, and different, password which will be used to protect the designated key store.
1124
1125 @item -storetype @var{STORE_TYPE}
1126 For more details @pxref{storetype,, STORE_TYPE}.
1127
1128 @item -keystore @var{URL}
1129 For more details @pxref{keystore,, URL}.
1130
1131 @item -storepass @var{PASSWORD}
1132 For more details @pxref{storepass,, PASSWORD}.
1133
1134 @item -provider @var{PROVIDER_CLASS_NAME}
1135 For more details @pxref{provider,, PROVIDER_CLASS_NAME}.
1136
1137 @item -v
1138 For more details @pxref{verbose}.
1139
1140 @end table
1141 @c man end
1142
1143 @comment ----------------------------------------------------------------------
1144
1145 @node Command -keypasswd, Command -delete, Command -storepasswd, Management Commands
1146 @comment node-name, next, previous, up
1147 @c man begin OPTIONS gkeytool
1148 @subsubsection The @option{-keypasswd} command
1149
1150 Use this command to change the password protecting the private key material of a designated @i{Key Entry}.
1151
1152 @table @gcctabopt
1153 @item -alias @var{ALIAS}
1154 For more details @pxref{alias,, ALIAS}.
1155
1156 Use this option to specify the password which the tool will use to unlock the @i{Key Entry} associated with the designated @i{Alias}.
1157
1158 If this option is omitted, the tool will first attempt to unlock the @i{Key Entry} using the same password protecting the key store. If this fails, you will then be prompted to provide a password.
1159
1160 @item -new @var{PASSWORD}
1161 The new, and different, password which will be used to protect the private key material of the designated @i{Key Entry}.
1162
1163 @item -storetype @var{STORE_TYPE}
1164 For more details @pxref{storetype,, STORE_TYPE}.
1165
1166 @item -keystore @var{URL}
1167 For more details @pxref{keystore,, URL}.
1168
1169 @item -storepass @var{PASSWORD}
1170 For more details @pxref{storepass,, PASSWORD}.
1171
1172 @item -provider @var{PROVIDER_CLASS_NAME}
1173 For more details @pxref{provider,, PROVIDER_CLASS_NAME}.
1174
1175 @item -v
1176 For more details @pxref{verbose}.
1177
1178 @end table
1179 @c man end
1180
1181 @comment ----------------------------------------------------------------------
1182
1183 @node Command -delete, , Command -keypasswd, Management Commands
1184 @comment node-name, next, previous, up
1185 @c man begin OPTIONS gkeytool
1186 @subsubsection The @option{-delete} command
1187
1188 Use this command to delete a designated key store entry.
1189
1190 @table @gcctabopt
1191 @item -alias @var{ALIAS}
1192 For more details @pxref{alias,, ALIAS}.
1193
1194 @item -storetype @var{STORE_TYPE}
1195 For more details @pxref{storetype,, STORE_TYPE}.
1196
1197 @item -keystore @var{URL}
1198 For more details @pxref{keystore,, URL}.
1199
1200 @item -storepass @var{PASSWORD}
1201 For more details @pxref{storepass,, PASSWORD}.
1202
1203 @item -provider @var{PROVIDER_CLASS_NAME}
1204 For more details @pxref{provider,, PROVIDER_CLASS_NAME}.
1205
1206 @item -v
1207 For more details @pxref{verbose}.
1208
1209 @end table
1210 @c man end
1211
1212 @comment ----------------------------------------------------------------------
1213
1214 @node Other Tools, I18N Issues, Security Tools, Top
1215 @comment node-name, next, previous, up
1216 @chapter Other Tools
1217
1218 This is a list of currently undocumented classpath tools: @b{jar},
1219 @b{javah}, @b{gcjh}, @b{native2ascii}, @b{orbd}, @b{serialver}, @b{rmid}, @b{rmiregistry}
1220 and @b{tnameserv}.
1221
1222 @menu
1223 * jar Tool::                   Archive tool for Java archives
1224 * javah Tool::                 A java header compiler
1225 * gcjh Tool::                  A java header compiler (old version)
1226 * native2ascii Tool::          An encoding converter
1227 * orbd Tool::                  An object request broker daemon
1228 * serialver Tool::             A serial version command
1229 * rmid Tool::                  RMI activation daemon
1230 * rmiregistry Tool::           Remote object registry
1231 * tnameserv Tool::             Naming service
1232 @end menu
1233
1234 @comment ----------------------------------------------------------------------
1235
1236 @node jar Tool, javah Tool, , Other Tools
1237 @comment node-name, next, previous, up
1238 @section The @command{jar} Tool
1239 @c man title gjar - Archive tool for Java archives
1240
1241 @c man begin DESCRIPTION gjar
1242
1243 @command{gjar} is an implementation of Sun's jar utility that comes with
1244 the JDK.
1245
1246 If any file is a directory then it is processed recursively.  The
1247 manifest file name and the archive file name needs to be specified in
1248 the same order the @option{-m} and @option{-f} flags are specified.
1249
1250 @c man end
1251
1252 @ignore
1253 @c man begin SYNOPSIS gjar
1254 gjar @option{-ctxui} [@var{OPTIONS}] @var{jar-file} [@option{-C} @var{DIR} @var{FILE}] @var{FILE}@dots{}
1255 @c man end
1256 @end ignore
1257
1258 @c man begin OPTIONS gjar
1259
1260 Operation mode:
1261
1262 @table @gcctabopt
1263 @item -c
1264 Create new archive.
1265
1266 @item -t
1267 List table of contents for archive.
1268
1269 @item -x
1270 Extract named (or all) files from archive.
1271
1272 @item -u
1273 Update existing archive.
1274
1275 @item -i @var{FILE}
1276 Compute archive index.
1277 @end table
1278
1279 Operation modifiers:
1280
1281 @table @gcctabopt
1282 @item -f @var{FILE}
1283 Specify archive file name.
1284
1285 @item -0
1286 Store only; use no ZIP compression.
1287
1288 @item -v
1289 Generate verbose output on standard output.
1290
1291 @item -M
1292 Do not create a manifest file for the entries.
1293
1294 @item -m @var{manifest}
1295 Include manifest information from specified @var{manifest} file.
1296 @end table
1297
1298 File name selection:
1299
1300 @table @gcctabopt
1301 @item -C @var{DIR} @var{FILE}
1302 Change to the @var{DIR} and include the following @var{FILE}.
1303
1304 @item -@@
1305 Read the names of the files to add to the archive from stdin.  This
1306 option is supported only in combination with @option{-c} or @option{-u}.
1307 Non standard option added in the GCC version.
1308 @end table
1309
1310 Standard options:
1311
1312 @table @gcctabopt
1313 @item -help
1314 Print help text, then exit.
1315 @item -version
1316 Print version number, then exit.
1317 @item -J@var{OPTION}
1318 Pass argument to the Java runtime.
1319 @end table
1320
1321 @c man end
1322
1323 @c man begin SEEALSO gjar
1324 java(1), @dots{}
1325 @c man end
1326
1327 @comment ----------------------------------------------------------------------
1328
1329 @node javah Tool, gcjh Tool, jar Tool, Other Tools
1330 @comment node-name, next, previous, up
1331 @section The @command{javah} Tool
1332 @c man title gjavah - generate header files from Java class files
1333
1334 @c man begin DESCRIPTION gjavah
1335
1336 The @command{gjavah} program is used to generate header files from class
1337 files.  It can generate both CNI and JNI header files, as well as stub
1338 implementation files which can be used as a basis for implementing the
1339 required native methods.
1340
1341 @c man end
1342
1343 @ignore
1344 @c man begin SYNOPSIS gjavah
1345 gjavah @dots{}
1346 @c man end
1347 @end ignore
1348
1349 @c man begin OPTIONS gjavah
1350
1351 @table @gcctabopt
1352 @item -d @var{DIR}
1353 Set output directory.
1354
1355 @item -o @var{FILE}
1356 Set output file (only one of @option{-d} or @option{-o} may be used).
1357
1358 @item -cmdfile @var{FILE}
1359 Read command file.
1360
1361 @item -all @var{DIR}
1362 Operate on all class files under directory @var{DIR}.
1363
1364 @item -stubs
1365 Emit stub implementation.
1366
1367 @item -jni
1368 Emit JNI stubs or header (default).
1369
1370 @item -cni
1371 Emit CNI stubs or header (default JNI).
1372
1373 @item -verbose
1374 Set verbose mode.
1375
1376 @item -force
1377 Output files should always be written.
1378 @end table
1379
1380 Class path options:
1381 @table @gcctabopt
1382 @item -classpath @var{PATH}
1383 Set the class path.
1384
1385 @item -I@var{DIR}
1386 Add directory to class path.
1387
1388 @item -bootclasspath @var{PATH}
1389 Set the boot class path.
1390
1391 @item -extdirs @var{PATH}
1392 Set the extension directory path.
1393 @end table
1394
1395 Standard options:
1396 @table @gcctabopt
1397 @item -help
1398 Print help text, then exit.
1399 @item -version
1400 Print version number, then exit.
1401 @item -J@var{OPTION}
1402 Pass argument to the Java runtime.
1403 @end table
1404 @c man end
1405
1406 @c man begin SEEALSO gjavah
1407 javac(1), @dots{}
1408 @c man end
1409
1410 @comment ----------------------------------------------------------------------
1411
1412 @node gcjh Tool, native2ascii Tool, javah Tool, Other Tools
1413 @comment node-name, next, previous, up
1414 @section The @command{gcjh} Tool
1415 @c man title gcjh - generate header files from Java class files
1416
1417 @c man begin DESCRIPTION gcjh
1418
1419 The @code{gcjh} program is used to generate header files from class
1420 files.  It can generate both CNI and JNI header files, as well as stub
1421 implementation files which can be used as a basis for implementing the
1422 required native methods.  It is similar to @code{javah} but has
1423 slightly different command line options, and defaults to CNI.
1424
1425 @c man end
1426
1427 @ignore
1428 @c man begin SYNOPSIS gcjh
1429 gcjh [@var{OPTIONS}]@dots{} @var{CLASS}@dots{}
1430 @c man end
1431 @end ignore
1432
1433 @c man begin OPTIONS gcjh
1434
1435 See @code{javah} for a full description; this page only lists the
1436 additional options provided by @code{gcjh}.
1437
1438 CNI text options
1439 @table @gcctabopt
1440 @item -add @var{text}
1441 Insert @var{text} into class body.
1442 @item -append @var{text}
1443 Append @var{text} after class declaration.
1444 @item -friend @var{text}
1445 Insert @var{text} as a @code{friend} declaration.
1446 @item -prepend @var{text}
1447 Insert @var{text} before start of class.
1448 @end table
1449
1450 Compatibility options (unused)
1451 @table @gcctabopt
1452 @item -td @var{DIR}
1453 @itemx -M
1454 @itemx -MM
1455 @itemx -MD
1456 @itemx -MMD
1457 Unused compatibility option.
1458 @end table
1459
1460
1461 Standard options:
1462 @table @gcctabopt
1463 @item -help
1464 Print help text, then exit.
1465 @item -version
1466 Print version number, then exit.
1467 @item -J@var{OPTION}
1468 Pass argument to the Java runtime.
1469 @end table
1470 @c man end
1471
1472 @c man begin SEEALSO gcjh
1473 javac(1), javah(1), @dots{}
1474 @c man end
1475
1476 @comment ----------------------------------------------------------------------
1477
1478 @node native2ascii Tool, orbd Tool, gcjh Tool, Other Tools
1479 @comment node-name, next, previous, up
1480 @section The @command{native2ascii} Tool
1481 @c man title gnative2ascii - An encoding converter
1482
1483 @c man begin DESCRIPTION gnative2ascii
1484
1485 To be written @dots{}
1486
1487 @c man end
1488
1489 @ignore
1490 @c man begin SYNOPSIS gnative2ascii
1491 gnative2ascii [@var{OPTIONS}]@dots{} [@var{INPUTFILE} [@var{OUTPUTFILE}]]
1492 @c man end
1493 @end ignore
1494
1495 @c man begin OPTIONS gnative2ascii
1496
1497 @table @gcctabopt
1498 @item -encoding @var{NAME}
1499 Set the encoding to use.
1500
1501 @item -reversed
1502 Convert from encoding to native.
1503 @end table
1504
1505 Standard options:
1506 @table @gcctabopt
1507 @item -help
1508 Print help text, then exit.
1509 @item -version
1510 Print version number, then exit.
1511 @item -J@var{OPTION}
1512 Pass argument to the Java runtime.
1513 @end table
1514
1515 @c man end
1516
1517 @c man begin SEEALSO gnative2ascii
1518 javac(1), @dots{}
1519 @c man end
1520
1521 @comment ----------------------------------------------------------------------
1522
1523 @node orbd Tool, serialver Tool, native2ascii Tool, Other Tools
1524 @comment node-name, next, previous, up
1525 @section The @command{orbd} object request broker daemon
1526 @c man title gorbd - An object request broker daemon
1527
1528 @c man begin DESCRIPTION gorbd
1529
1530 To be written @dots{}
1531
1532 @c man end
1533
1534 @ignore
1535 @c man begin SYNOPSIS gorbd
1536 gorbd @dots{}
1537 @c man end
1538 @end ignore
1539
1540 @c man begin OPTIONS gorbd
1541
1542 @table @gcctabopt
1543 @item -ORBInitialPort @var{PORT}
1544 Port on which persistent naming service is to be started.
1545
1546 @item -ior @var{FILE}
1547 File in which to store persistent naming service's IOR reference
1548
1549 @item -directory @var{DIR}
1550 Directory in which to store persistent data.
1551
1552 @item -restart
1553 Restart persistent naming service, clearing persistent naming
1554 database.
1555 @end table
1556
1557 Standard options:
1558 @table @gcctabopt
1559 @item -help
1560 Print help text, then exit.
1561 @item -version
1562 Print version number, then exit.
1563 @item -J@var{OPTION}
1564 Pass argument to the Java runtime.
1565 @end table
1566
1567 @c man end
1568
1569 @c man begin SEEALSO gorbd
1570 java(1), @dots{}
1571 @c man end
1572
1573 @comment ----------------------------------------------------------------------
1574
1575 @node serialver Tool, rmid Tool, orbd Tool, Other Tools
1576 @comment node-name, next, previous, up
1577 @section The @command{serialver} version command
1578 @c man title gserialver version command
1579
1580 @c man begin DESCRIPTION gserialver
1581
1582 Print the serialVersionUID of the specified classes.
1583
1584 @c man end
1585
1586 @ignore
1587 @c man begin SYNOPSIS gserialver
1588 gserialver [@var{OPTIONS}]@dots{} @var{CLASS}@dots{}
1589 @c man end
1590 @end ignore
1591
1592 @c man begin OPTIONS gserialver
1593
1594 @table @gcctabopt
1595 @item -classpath @var{PATH}
1596 Class path to use to find classes.
1597 @end table
1598
1599 Standard options:
1600 @table @gcctabopt
1601 @item -help
1602 Print help text, then exit.
1603 @item -version
1604 Print version number, then exit.
1605 @item -J@var{OPTION}
1606 Pass argument to the Java runtime.
1607 @end table
1608
1609 @c man end
1610
1611 @c man begin SEEALSO gserialver
1612 javac(1), @dots{}
1613 @c man end
1614
1615 @comment ----------------------------------------------------------------------
1616
1617 @node rmid Tool, rmiregistry Tool, serialver Tool, Other Tools
1618 @comment node-name, next, previous, up
1619 @section The @command{rmid} RMI activation system daemon
1620 @c man title grmid - RMI activation system daemon
1621
1622 @c man begin DESCRIPTION grmid
1623
1624 @command{rmiregistry} starts a remote object registry on the current
1625 host.  If no port number is specified, then port 1099 is used.
1626
1627 @c man end
1628
1629 @ignore
1630 @c man begin SYNOPSIS grmid
1631 grmid [@var{OPTIONS}]@dots{}
1632 @c man end
1633 @end ignore
1634
1635 @c man begin OPTIONS grmid
1636
1637 Activation process control:
1638 @table @gcctabopt
1639 @item -port @var{PORT}
1640 Port on which activation system is to be started.
1641
1642 @item -restart
1643 Restart activation system, clearing persistent naming database, if
1644 any.
1645
1646 @item -stop
1647 Stop activation system.
1648 @end table
1649
1650 Persistence:
1651 @table @gcctabopt
1652 @item -persistent
1653 Make activation system persistent.
1654
1655 @item -directory @var{DIR}
1656 Directory in which to store persistent data.
1657 @end table
1658
1659 Debugging:
1660 @table @gcctabopt
1661 @item -verbose
1662 Log binding events to standard out.
1663 @end table
1664
1665 Standard options:
1666 @table @gcctabopt
1667 @item -help
1668 Print help text, then exit.
1669 @item -version
1670 Print version number, then exit.
1671 @item -J@var{OPTION}
1672 Pass argument to the Java runtime.
1673 @end table
1674
1675 @c man end
1676
1677 @c man begin SEEALSO grmid
1678 java(1), @dots{}
1679 @c man end
1680
1681 @comment ----------------------------------------------------------------------
1682
1683 @node rmiregistry Tool, tnameserv Tool, rmid Tool, Other Tools
1684 @comment node-name, next, previous, up
1685 @section The @command{rmiregistry} Tool
1686 @c man title grmiregistry - Remote object registry
1687
1688 @c man begin DESCRIPTION grmiregistry
1689
1690 @command{grmiregistry} starts a remote object registry on the current
1691 host.  If no port number is specified, then port 1099 is used.
1692
1693 @c man end
1694
1695 @ignore
1696 @c man begin SYNOPSIS grmiregistry
1697 grmiregistry [@var{OPTIONS}]@dots{} @var{PORT}
1698 @c man end
1699 @end ignore
1700
1701 @c man begin OPTIONS grmiregistry
1702
1703 Registry process control:
1704 @table @gcctabopt
1705 @item -restart
1706 Restart RMI naming service, clearing persistent naming database, if
1707 any.
1708
1709 @item -stop
1710 Stop RMI naming service.
1711 @end table
1712
1713 Persistence:
1714 @table @gcctabopt
1715 @item -persistent
1716 Make RMI naming service persistent.
1717
1718 @item -directory @var{DIR}
1719 Directory in which to store persistent data.
1720 @end table
1721
1722 Debugging:
1723 @table @gcctabopt
1724 @item -verbose
1725 Log binding events to standard out.
1726 @end table
1727
1728 Standard options:
1729 @table @gcctabopt
1730 @item -help
1731 Print help text, then exit.
1732 @item -version
1733 Print version number, then exit.
1734 @item -J@var{OPTION}
1735 Pass argument to the Java runtime.
1736 @end table
1737
1738 @c man end
1739
1740 @c man begin SEEALSO grmiregistry
1741 java(1), @dots{}
1742 @c man end
1743
1744 @comment ----------------------------------------------------------------------
1745
1746 @node tnameserv Tool, , rmiregistry Tool, Other Tools
1747 @comment node-name, next, previous, up
1748 @section The @command{tnameserv} Tool
1749 @c man title gtnameserv Naming service
1750
1751 @c man begin DESCRIPTION gtnameserv
1752
1753 To be written @dots{}
1754
1755 @c man end
1756
1757 @ignore
1758 @c man begin SYNOPSIS gtnameserv
1759 tnameserv [@var{OPTIONS}]
1760 @c man end
1761 @end ignore
1762
1763 @c man begin OPTIONS gtnameserv
1764
1765 @table @gcctabopt
1766 @item -ORBInitialPort @var{PORT}
1767 Port on which naming service is to be started.
1768
1769 @item -ior @var{FILE}
1770 File in which to store naming service's IOR reference.
1771 @end table
1772
1773 Standard options:
1774 @table @gcctabopt
1775 @item -help
1776 Print help text, then exit.
1777 @item -version
1778 Print version number, then exit.
1779 @item -J@var{OPTION}
1780 Pass argument to the Java runtime.
1781 @end table
1782
1783 @c man end
1784
1785 @c man begin SEEALSO gtnameserv
1786 java(1), @dots{}
1787 @c man end
1788
1789 @comment ----------------------------------------------------------------------
1790
1791 @node I18N Issues, , Other Tools, Top
1792 @comment node-name, next, previous, up
1793 @chapter I18N Issues
1794
1795 Some tools --@pxref{Security Tools}-- allow using other than the English language when prompting the User for input, and outputting messages. This chapter describes the elements used to offer this support and how they can be adapted for use with specific languages.
1796
1797 @menu
1798 * Language Resources::         Where resources are located
1799 * Message Formats::            How messages are internationalized
1800 @end menu
1801
1802 @comment ----------------------------------------------------------------------
1803
1804 @node Language Resources, Message Formats, I18N Issues, I18N Issues
1805 @comment node-name, next, previous, up
1806 @section Language-specific resources
1807
1808 The Tools use Java @code{ResourceBundle}s to store messages, and message templates they use at runtime to generate the message text itself, depending on the locale in use at the time.
1809
1810 The @i{Resource Bundles} these tools use are essentially Java @i{Properties} files consisting of a set of @i{Name/Value} pairs. The @i{Name} is the @i{Property Name} and the @i{Value} is a substitution string that is used when the code references the associated @i{Name}. For example the following is a line in a @i{Resource Bundle} used by the @code{keytool} Tool:
1811
1812 @example
1813 Command.23=A correct key password MUST be provided
1814 @end example
1815
1816 When the tool needs to signal a mandatory but missing key password, it would reference the property named @code{Command.23} and the message "@kbd{A correct key password MUST be provided}" will be used instead. This indirect referencing of "resources" permits replacing, as late as possible, the English strings with strings in other languages, provided of course @i{Resource Bundles} in those languages are provided.
1817
1818 For the GNU Classpath Tools described in this Guide, the @i{Resource Bundles} are files named @file{messages[_ll[_CC[_VV]]].properties} where:
1819
1820 @ftable @var
1821 @item ll
1822 Is the 2-letter code for the Language,
1823 @item CC
1824 Is the 2-letter code for the Region, and
1825 @item VV
1826 Is the 2-letter code for the Variant of the language.
1827 @end ftable
1828
1829 The complete list of language codes can be found at @uref{http://ftp.ics.uci.edu/pub/ietf/http/related/iso639.txt, Code for the representation of names of languages}. A similar list for the region codes can be found at @uref{http://userpage.chemie.fu-berlin.de/diverse/doc/ISO_3166.html, ISO 3166 Codes (Countries)}.
1830
1831 The location of the @i{Resource Bundles} for the GNU Classpath Tools is specific to each tool. The next table shows where these files are found in a standard GNU Classpath distribution:
1832
1833 @ftable @code
1834 @item jarsigner
1835 @file{gnu/classpath/tools/jarsigner}
1836 @item keytool
1837 @file{gnu/classpath/tools/keytool}
1838 @end ftable
1839
1840 The collection of @i{Resource Bundles} in a location act as an inverted tree with a parent-child relationship. For example suppose in the @file{gnu/classpath/tools/keytool} there are 3 message bundles named:
1841
1842 @enumerate
1843 @item @code{messages.properties}
1844 @item @code{messages_fr.properties}
1845 @item @code{messages_fr_FR.properties}
1846 @end enumerate
1847
1848 In the above example, bundle #1 will act as the parent of bundle #2, which in turn will act as the parent for bundle #3. This ordering is used by the Java runtime to choose which file to load based on the set Locale. For example if the Locale is @code{fr_CH}, @code{messages_fr.properties} will be used because (a) @code{messages_fr_CH.properties} does not exist, but (b) @code{messages_fr.properties} is the parent for the required bundle, and it exists. As another example, suppose the Locale was set to @code{en_AU}; then the tool will end up using @code{messages.properties} because (a) @code{messages_en_AU.properties} does not exist, (b) @code{messages_en.properties} which is the parent for the required bundle does not exist, but (c) @code{messages.properties} exists and is the root of the hierarchy.
1849
1850 You can see from the examples above that @file{messages.properties} is the safety net that the Java runtime falls back to when failing to find a specific bundle and its parent(s). This file is always provided with the Tool. In time, more localized versions will be included to cater for other languages.
1851
1852 In the meantime, if you are willing to contribute localized versions of these resources, grab the @file{messages.properties} for a specific tool; translate it; save it with the appropriate language and region suffix and mail it to @code{classpath@@gnu.org}.
1853
1854 @comment ----------------------------------------------------------------------
1855
1856 @node Message Formats, , Language Resources, I18N Issues
1857 @comment node-name, next, previous, up
1858 @section Message formats
1859
1860 If you open any of the @file{messages.properties} described in the previous section, you may see properties that look like so:
1861
1862 @example
1863 Command.67=Issuer: @{0@}
1864 Command.68=Serial number: @{0,number@}
1865 Command.69=Valid from: @{0,date,full@} - @{0,time,full@}
1866 Command.70=\ \ \ \ \ until: @{0,date,full@} - @{0,time,full@}
1867 @end example
1868
1869 These are @i{Message Formats} used by the tools to customize a text string that will then be used either as a prompt for User input or as output.
1870
1871 If you are translating a @file{messages.properties} be careful not to alter text between curly braces.
1872
1873 @comment ----------------------------------------------------------------------
1874
1875 @bye