1 \input texinfo @c -*-texinfo-*-
4 @setfilename cp-tools.info
5 @settitle GNU Classpath Tools Guide
10 @c Common macros to support generating man pages:
12 @macro gcctabopt{body}
15 @macro gccoptlist{body}
22 This file documents the Tools included in a standard distribution of the GNU
23 Classpath project deliverables.
25 Copyright (C) 2006, 2007 Free Software Foundation, Inc.
28 @dircategory GNU Libraries
30 * Classpath Tools: (cp-tools). GNU Classpath Tools Guide
36 @title GNU Classpath Tools Guide
37 @author The GNU Classpath Team
40 @vskip 0pt plus 1filll
41 Copyright @copyright{} 2006 Free Software Foundation, Inc.
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.
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.
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.
54 @node Top, Applet Tools, (dir), (dir)
55 @top GNU Classpath Tools Guide
57 This document contains important information you need to know in order to use
58 the tools included in the GNU Classpath project deliverables.
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).
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
73 --- The Detailed Node Listing ---
77 * appletviewer Tool:: Load applets
78 * gcjwebplugin:: Load applets in a web browser
82 * jarsigner Tool:: Sign and verify .JAR files
83 * keytool Tool:: Manage private keys and public certificates
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
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
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
111 * Command -certreq:: Generate Certificate Signing Requests (CSR)
112 * Command -export:: Export a certificate in a Key Store
116 * Command -list:: Display information about one or all Aliases
117 * Command -printcert:: Print a certificate or a certificate fingerprint
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
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
140 * Language Resources:: Where resources are located
141 * Message Formats:: How messages are internationalized
146 @comment ----------------------------------------------------------------------
148 @node Applet Tools, Security Tools, Top, Top
149 @comment node-name, next, previous, up
150 @chapter Applet Tools
152 Two Applet Tools are available with GNU Classpath: @b{appletviewer}
153 and @b{gcjwebplugin}.
155 To avoid conflicts with other implementations, the appletviewer
156 executable is called ``gappletviewer''.
159 * appletviewer Tool:: Load applets
160 * gcjwebplugin:: Load applets in a web browser
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}.
165 @comment ----------------------------------------------------------------------
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
174 @c man begin SYNOPSIS gappletviewer
175 appletviewer [@var{OPTION}]@dots{} @var{URL}@dots{} @var{@*}
177 appletviewer [@var{OPTION}]@dots{} @option{-code} @var{CODE} @var{@*}
179 appletviewer [@var{OPTION}]@dots{} @option{-plugin} @var{INPUT},@var{OUTPUT}
183 @c man begin DESCRIPTION gappletviewer
184 The @command{appletviewer} tool loads and runs an applet.
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.
196 appletviewer http://www.gnu.org/software/classpath/
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
206 appletviewer -code Test.class -param datafile,data.txt
209 @command{gcjwebplugin} uses the third form to communicate with the
210 @command{appletviewer} through named pipes.
213 @c man begin OPTIONS gappletviewer
217 This option is not yet implemented but is provided for compatibility.
219 @item -encoding @var{CHARSET}
220 Use this option to specify an alternate character encoding for the
227 @item -code @var{CODE}
228 Use the @option{-code} option to specify the value of the applet tag
229 @var{CODE} attribute.
231 @item -codebase @var{CODEBASE}
232 Use the @option{-codebase} option to specify the value of the applet tag
233 @var{CODEBASE} attribute.
235 @item -archive @var{ARCHIVE}
236 Use the @option{-archive} option to specify the value of the applet tag
237 @var{ARCHIVE} attribute.
239 @item -width @var{WIDTH}
240 Use the @option{-width} option to specify the value of the applet tag
241 @var{WIDTH} attribute.
243 @item -height @var{HEIGHT}
244 Use the @option{-height} option to specify the value of the applet tag
245 @var{HEIGHT} attribute.
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.
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}).
266 Use the @option{-verbose} option to have the @command{appletviewer} print
275 Use the @option{-help} option to have the @command{appletviewer} print a
276 usage message, then exit.
279 Use the @option{-version} option to have the @command{appletviewer} print
280 its version, then exit.
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}.
290 @comment ----------------------------------------------------------------------
292 @node gcjwebplugin, , appletviewer Tool, Applet Tools
293 @comment node-name, next, previous, up
294 @section The @code{gcjwebplugin} Tool
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).
300 @comment ----------------------------------------------------------------------
302 @node Security Tools, Other Tools, Applet Tools, Top
303 @comment node-name, next, previous, up
304 @chapter Security Tools
306 Two Security Tools are available with GNU Classpath:
307 @command{jarsigner} and @command{keytool}.
309 To avoid conflicts with other implementations, the jarsigner
310 executable is called @command{gjarsigner} and the keytool executable is
311 called @command{gkeytool}.
314 * jarsigner Tool:: Sign and verify .JAR files
315 * keytool Tool:: Manage private keys and public certificates
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}.
320 @comment ----------------------------------------------------------------------
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
327 The @command{jarsigner} tool is invoked from the command line, in one
328 of two forms, as follows:
331 @c man begin SYNOPSIS gjarsigner
332 jarsigner [@var{OPTION}]@dots{} @var{FILE} @var{ALIAS}
334 jarsigner @option{-verify} [@var{OPTION}]@dots{} @var{FILE}
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.
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.
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.
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
352 @comment ----------------------------------------------------------------------
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
359 The following options may be used when the tool is used for either signing, or verifying, a .JAR file.
363 Use this option to force the tool to generate more verbose messages, during its processing.
366 When present, the tool will include --which otherwise it does not-- the @code{.SF} file in the @code{.DSA} generated file.
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.
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.
375 Prints a help text similar to this one.
380 @comment ----------------------------------------------------------------------
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
387 The following options may be specified when using the tool for signing purposes.
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.
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:}.
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}.
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.
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}.
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.
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.
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.
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.
417 @comment ----------------------------------------------------------------------
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
424 The following options may be specified when using the tool for verification purposes.
428 Use this option to indicate that the tool is to be used for verification purposes.
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.
436 @comment ----------------------------------------------------------------------
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
444 @c man begin SYNOPSIS gkeytool
445 keytool [@var{COMMAND}] @dots{}
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.
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.
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.
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}.
458 The @command{keytool} is invoked from the command line as follows:
461 keytool [COMMAND] ...
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
467 keytool -list -- -printcert -alias mykey
471 Here is a summary of the commands supported by the tool:
473 @c man begin OPTIONS gkeytool
475 @item Add/Update commands
477 @item -genkey [@var{OPTION}]@dots{}
478 Generate a new @i{Key Entry}, eventually creating a new key store.
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).
483 @item -selfcert [@var{OPTION}]@dots{}
484 Generate a new self-signed @i{Trusted Certificate}.
486 @item -cacert [@var{OPTION}]@dots{}
487 Import a CA @i{Trusted Certificate}.
489 @item -identitydb [@var{OPTION}]@dots{}
490 @b{NOT IMPLEMENTED YET}.@*
491 Import a JDK 1.1 style Identity Database.
494 @item Export commands
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.
499 @item -export [@var{OPTION}]@dots{}
500 Export a certificate from a key store.
503 @item Display commands
505 @item -list [@var{OPTION}]@dots{}
506 Print one or all certificates in a key store to @code{STDOUT}.
508 @item -printcert [@var{OPTION}]@dots{}
509 Print a human-readable form of a certificate, in a designated file, to @code{STDOUT}.
512 @item Management commands
514 @item -keyclone [@var{OPTION}]@dots{}
515 Clone a @i{Key Entry} in a key store.
517 @item -storepasswd [@var{OPTION}]@dots{}
518 Change the password protecting a key store.
520 @item -keypasswd [@var{OPTION}]@dots{}
521 Change the password protecting a @i{Key Entry} in a key store.
523 @item -delete [@var{OPTION}]@dots{}
524 Delete a @i{Key Entry} or a @i{Trusted Certificate} from a key store.
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
539 @comment ----------------------------------------------------------------------
541 @node Getting Help, Common keytool Options, keytool Tool, keytool Tool
542 @comment node-name, next, previous, up
543 @subsection Getting help
545 To get a general help text about the tool, use the @code{-help} option; e.g.
551 To get more specific help text about one of the tool's command use the @code{-help} option for that command; e.g.
554 @code{keytool -genkey -help}
557 In both instances, the tool will print a help text and then will exit the running JVM.
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.
561 @comment ----------------------------------------------------------------------
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
568 The following @option{OPTION}s are used in more than one @command{COMMAND}. They are described here to reduce redundancy.
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.
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).
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.
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.
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}.
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.
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.
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:}.
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.
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.
611 Unless specified otherwise, use this option to enable more verbose output.
616 @comment ----------------------------------------------------------------------
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
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:
627 The Common Name; e.g.@: @kbd{host.domain.com}
629 The Organizational Unit; e.g.@: @kbd{IT Department}
631 The Organization Name; e.g.@: @kbd{The Sample Company}
633 The Locality Name; e.g.@: @kbd{Sydney}
635 The State Name; e.g.@: @kbd{New South Wales}
637 The 2-letter Country identifier; e.g.@: @kbd{AU}
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:@*
643 CN=host.domain.com, O=The Sample Company, L=Sydney, ST=NSW, C=AU
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.
648 @comment ----------------------------------------------------------------------
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
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
664 @comment ----------------------------------------------------------------------
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
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}.
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.
676 @item -alias @var{ALIAS}
677 For more details @pxref{alias,, ALIAS}.
679 @item -keyalg @var{ALGORITHM}
680 For more details @pxref{keyalg,, ALGORITHM}.
682 @item -keysize @var{KEY_SIZE}
683 For more details @pxref{keysize,, KEY_SIZE}.
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.
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.
691 For more details @pxref{dn,, X.500 DISTINGUISHED NAME}.
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}.
696 If this option is omitted, you will be prompted to provide a password.
698 @item -validity @var{DAY_COUNT}
699 For more details @pxref{validity,, DAY_COUNT}.
701 @item -storetype @var{STORE_TYPE}
702 For more details @pxref{storetype,, STORE_TYPE}.
704 @item -keystore @var{URL}
705 For more details @pxref{keystore,, URL}.
707 @item -storepass @var{PASSWORD}
708 For more details @pxref{storepass,, PASSWORD}.
710 @item -provider @var{PROVIDER_CLASS_NAME}
711 For more details @pxref{provider,, PROVIDER_CLASS_NAME}.
714 For more details @pxref{verbose}.
719 @comment ----------------------------------------------------------------------
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
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.
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.
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.
733 @item -alias @var{ALIAS}
734 For more details @pxref{alias,, ALIAS}.
736 @item -file @var{FILE}
737 For more details @pxref{file,, FILE}.
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.
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.
745 Use this option to prevent the tool from prompting the user.
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.
750 @item -storetype @var{STORE_TYPE}
751 For more details @pxref{storetype,, STORE_TYPE}.
753 @item -keystore @var{URL}
754 For more details @pxref{keystore,, URL}.
756 @item -storepass @var{PASSWORD}
757 For more details @pxref{storepass,, PASSWORD}.
759 @item -provider @var{PROVIDER_CLASS_NAME}
760 For more details @pxref{provider,, PROVIDER_CLASS_NAME}.
763 For more details @pxref{verbose}.
768 @comment ----------------------------------------------------------------------
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
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).
778 @item -alias @var{ALIAS}
779 For more details @pxref{alias,, ALIAS}.
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.
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.
787 For more details @pxref{dn,, X.500 DISTINGUISHED NAME}.
789 @item -validity @var{DAY_COUNT}
790 For more details @pxref{validity,, DAY_COUNT}.
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}.
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.
797 @item -storetype @var{STORE_TYPE}
798 For more details @pxref{storetype,, STORE_TYPE}.
800 @item -keystore @var{URL}
801 For more details @pxref{keystore,, URL}.
803 @item -storepass @var{PASSWORD}
804 For more details @pxref{storepass,, PASSWORD}.
806 @item -provider @var{PROVIDER_CLASS_NAME}
807 For more details @pxref{provider,, PROVIDER_CLASS_NAME}.
810 For more details @pxref{verbose}.
815 @comment ----------------------------------------------------------------------
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
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.
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.
827 @item -file @var{FILE}
828 For more details @pxref{file,, FILE}.
830 @item -storetype @var{STORE_TYPE}
831 For more details @pxref{storetype,, STORE_TYPE}.
833 @item -keystore @var{URL}
834 For more details @pxref{keystore,, URL}.
836 @item -storepass @var{PASSWORD}
837 For more details @pxref{storepass,, PASSWORD}.
839 @item -provider @var{PROVIDER_CLASS_NAME}
840 For more details @pxref{provider,, PROVIDER_CLASS_NAME}.
843 For more details @pxref{verbose}.
848 @comment ----------------------------------------------------------------------
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
855 @b{NOT IMPLEMENTED YET}.
857 Use this command to import a JDK 1.1 style Identity Database.
860 @item -file @var{FILE}
861 For more details @pxref{file,, FILE}.
863 @item -storetype @var{STORE_TYPE}
864 For more details @pxref{storetype,, STORE_TYPE}.
866 @item -keystore @var{URL}
867 For more details @pxref{keystore,, URL}.
869 @item -storepass @var{PASSWORD}
870 For more details @pxref{storepass,, PASSWORD}.
872 @item -provider @var{PROVIDER_CLASS_NAME}
873 For more details @pxref{provider,, PROVIDER_CLASS_NAME}.
876 For more details @pxref{verbose}.
881 @comment ----------------------------------------------------------------------
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
890 * Command -certreq:: Generate Certificate Signing Requests (CSR)
891 * Command -export:: Export a certificate in a Key Store
894 @comment ----------------------------------------------------------------------
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
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:
904 -----BEGIN NEW CERTIFICATE REQUEST-----
905 MI...QAwXzEUMBIGA1UEAwwLcnNuQGdudS5vcmcxGzAZBgNVBAoMElUg
906 Q2...A0GA1UEBwwGU3lkbmV5MQwwCgYDVQQIDANOU1cxCzAJBgNVBACC
908 FC...IVwNVOfQLRX+O5kAhQ/a4RTZme2L8PnpvgRwrf7Eg8D6w==
909 -----END NEW CERTIFICATE REQUEST-----
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.
915 @item -alias @var{ALIAS}
916 For more details @pxref{alias,, ALIAS}.
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.
921 @item -file @var{FILE}
922 For more details @pxref{file,, FILE}.
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}.
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.
929 @item -storetype @var{STORE_TYPE}
930 For more details @pxref{storetype,, STORE_TYPE}.
932 @item -keystore @var{URL}
933 For more details @pxref{keystore,, URL}.
935 @item -storepass @var{PASSWORD}
936 For more details @pxref{storepass,, PASSWORD}.
938 @item -provider @var{PROVIDER_CLASS_NAME}
939 For more details @pxref{provider,, PROVIDER_CLASS_NAME}.
942 For more details @pxref{verbose}.
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.
950 @comment ----------------------------------------------------------------------
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
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).
960 @item -alias @var{ALIAS}
961 For more details @pxref{alias,, ALIAS}.
963 @item -file @var{FILE}
964 For more details @pxref{file,, FILE}.
966 @item -storetype @var{STORE_TYPE}
967 For more details @pxref{storetype,, STORE_TYPE}.
969 @item -keystore @var{URL}
970 For more details @pxref{keystore,, URL}.
972 @item -storepass @var{PASSWORD}
973 For more details @pxref{storepass,, PASSWORD}.
975 @item -provider @var{PROVIDER_CLASS_NAME}
976 For more details @pxref{provider,, PROVIDER_CLASS_NAME}.
979 Use RFC-1421 specifications when encoding the output.
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.
987 @comment ----------------------------------------------------------------------
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
996 * Command -list:: Display information about one or all Aliases
997 * Command -printcert:: Print a certificate or a certificate fingerprint
1000 @comment ----------------------------------------------------------------------
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
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.
1010 @item -alias @var{ALIAS}
1011 If this option is omitted, the tool will print ALL the entries found in the key store.
1013 For more details @pxref{alias,, ALIAS}.
1015 @item -storetype @var{STORE_TYPE}
1016 For more details @pxref{storetype,, STORE_TYPE}.
1018 @item -keystore @var{URL}
1019 For more details @pxref{keystore,, URL}.
1021 @item -storepass @var{PASSWORD}
1022 For more details @pxref{storepass,, PASSWORD}.
1024 @item -provider @var{PROVIDER_CLASS_NAME}
1025 For more details @pxref{provider,, PROVIDER_CLASS_NAME}.
1028 Use RFC-1421 specifications when encoding the output.
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.
1036 @comment ----------------------------------------------------------------------
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
1043 Use this command to read a certificate from a designated input source and print it to @code{STDOUT} in a human-readable form.
1046 @item -file @var{FILE}
1047 For more details @pxref{file,, FILE}.
1050 For more details @pxref{verbose}.
1055 @comment ----------------------------------------------------------------------
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
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
1070 @comment ----------------------------------------------------------------------
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
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.
1080 @item -alias @var{ALIAS}
1081 For more details @pxref{alias,, ALIAS}.
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}.
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}.
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.
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}.
1094 @item -storetype @var{STORE_TYPE}
1095 For more details @pxref{storetype,, STORE_TYPE}.
1097 @item -keystore @var{URL}
1098 For more details @pxref{keystore,, URL}.
1100 @item -storepass @var{PASSWORD}
1101 For more details @pxref{storepass,, PASSWORD}.
1103 @item -provider @var{PROVIDER_CLASS_NAME}
1104 For more details @pxref{provider,, PROVIDER_CLASS_NAME}.
1107 For more details @pxref{verbose}.
1112 @comment ----------------------------------------------------------------------
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
1119 Use this command to change the password protecting a key store.
1122 @item -new @var{PASSWORD}
1123 The new, and different, password which will be used to protect the designated key store.
1125 @item -storetype @var{STORE_TYPE}
1126 For more details @pxref{storetype,, STORE_TYPE}.
1128 @item -keystore @var{URL}
1129 For more details @pxref{keystore,, URL}.
1131 @item -storepass @var{PASSWORD}
1132 For more details @pxref{storepass,, PASSWORD}.
1134 @item -provider @var{PROVIDER_CLASS_NAME}
1135 For more details @pxref{provider,, PROVIDER_CLASS_NAME}.
1138 For more details @pxref{verbose}.
1143 @comment ----------------------------------------------------------------------
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
1150 Use this command to change the password protecting the private key material of a designated @i{Key Entry}.
1153 @item -alias @var{ALIAS}
1154 For more details @pxref{alias,, ALIAS}.
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}.
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.
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}.
1163 @item -storetype @var{STORE_TYPE}
1164 For more details @pxref{storetype,, STORE_TYPE}.
1166 @item -keystore @var{URL}
1167 For more details @pxref{keystore,, URL}.
1169 @item -storepass @var{PASSWORD}
1170 For more details @pxref{storepass,, PASSWORD}.
1172 @item -provider @var{PROVIDER_CLASS_NAME}
1173 For more details @pxref{provider,, PROVIDER_CLASS_NAME}.
1176 For more details @pxref{verbose}.
1181 @comment ----------------------------------------------------------------------
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
1188 Use this command to delete a designated key store entry.
1191 @item -alias @var{ALIAS}
1192 For more details @pxref{alias,, ALIAS}.
1194 @item -storetype @var{STORE_TYPE}
1195 For more details @pxref{storetype,, STORE_TYPE}.
1197 @item -keystore @var{URL}
1198 For more details @pxref{keystore,, URL}.
1200 @item -storepass @var{PASSWORD}
1201 For more details @pxref{storepass,, PASSWORD}.
1203 @item -provider @var{PROVIDER_CLASS_NAME}
1204 For more details @pxref{provider,, PROVIDER_CLASS_NAME}.
1207 For more details @pxref{verbose}.
1212 @comment ----------------------------------------------------------------------
1214 @node Other Tools, I18N Issues, Security Tools, Top
1215 @comment node-name, next, previous, up
1216 @chapter Other Tools
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}
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
1234 @comment ----------------------------------------------------------------------
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
1241 @c man begin DESCRIPTION gjar
1243 @command{gjar} is an implementation of Sun's jar utility that comes with
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.
1253 @c man begin SYNOPSIS gjar
1254 gjar @option{-ctxui} [@var{OPTIONS}] @var{jar-file} [@option{-C} @var{DIR} @var{FILE}] @var{FILE}@dots{}
1258 @c man begin OPTIONS gjar
1267 List table of contents for archive.
1270 Extract named (or all) files from archive.
1273 Update existing archive.
1276 Compute archive index.
1279 Operation modifiers:
1283 Specify archive file name.
1286 Store only; use no ZIP compression.
1289 Generate verbose output on standard output.
1292 Do not create a manifest file for the entries.
1294 @item -m @var{manifest}
1295 Include manifest information from specified @var{manifest} file.
1298 File name selection:
1301 @item -C @var{DIR} @var{FILE}
1302 Change to the @var{DIR} and include the following @var{FILE}.
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.
1314 Print help text, then exit.
1316 Print version number, then exit.
1317 @item -J@var{OPTION}
1318 Pass argument to the Java runtime.
1323 @c man begin SEEALSO gjar
1327 @comment ----------------------------------------------------------------------
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
1334 @c man begin DESCRIPTION gjavah
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.
1344 @c man begin SYNOPSIS gjavah
1349 @c man begin OPTIONS gjavah
1353 Set output directory.
1356 Set output file (only one of @option{-d} or @option{-o} may be used).
1358 @item -cmdfile @var{FILE}
1361 @item -all @var{DIR}
1362 Operate on all class files under directory @var{DIR}.
1365 Emit stub implementation.
1368 Emit JNI stubs or header (default).
1371 Emit CNI stubs or header (default JNI).
1377 Output files should always be written.
1382 @item -classpath @var{PATH}
1386 Add directory to class path.
1388 @item -bootclasspath @var{PATH}
1389 Set the boot class path.
1391 @item -extdirs @var{PATH}
1392 Set the extension directory path.
1398 Print help text, then exit.
1400 Print version number, then exit.
1401 @item -J@var{OPTION}
1402 Pass argument to the Java runtime.
1406 @c man begin SEEALSO gjavah
1410 @comment ----------------------------------------------------------------------
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
1417 @c man begin DESCRIPTION gcjh
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.
1428 @c man begin SYNOPSIS gcjh
1429 gcjh [@var{OPTIONS}]@dots{} @var{CLASS}@dots{}
1433 @c man begin OPTIONS gcjh
1435 See @code{javah} for a full description; this page only lists the
1436 additional options provided by @code{gcjh}.
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.
1450 Compatibility options (unused)
1457 Unused compatibility option.
1464 Print help text, then exit.
1466 Print version number, then exit.
1467 @item -J@var{OPTION}
1468 Pass argument to the Java runtime.
1472 @c man begin SEEALSO gcjh
1473 javac(1), javah(1), @dots{}
1476 @comment ----------------------------------------------------------------------
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
1483 @c man begin DESCRIPTION gnative2ascii
1485 To be written @dots{}
1490 @c man begin SYNOPSIS gnative2ascii
1491 gnative2ascii [@var{OPTIONS}]@dots{} [@var{INPUTFILE} [@var{OUTPUTFILE}]]
1495 @c man begin OPTIONS gnative2ascii
1498 @item -encoding @var{NAME}
1499 Set the encoding to use.
1502 Convert from encoding to native.
1508 Print help text, then exit.
1510 Print version number, then exit.
1511 @item -J@var{OPTION}
1512 Pass argument to the Java runtime.
1517 @c man begin SEEALSO gnative2ascii
1521 @comment ----------------------------------------------------------------------
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
1528 @c man begin DESCRIPTION gorbd
1530 To be written @dots{}
1535 @c man begin SYNOPSIS gorbd
1540 @c man begin OPTIONS gorbd
1543 @item -ORBInitialPort @var{PORT}
1544 Port on which persistent naming service is to be started.
1546 @item -ior @var{FILE}
1547 File in which to store persistent naming service's IOR reference
1549 @item -directory @var{DIR}
1550 Directory in which to store persistent data.
1553 Restart persistent naming service, clearing persistent naming
1560 Print help text, then exit.
1562 Print version number, then exit.
1563 @item -J@var{OPTION}
1564 Pass argument to the Java runtime.
1569 @c man begin SEEALSO gorbd
1573 @comment ----------------------------------------------------------------------
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
1580 @c man begin DESCRIPTION gserialver
1582 Print the serialVersionUID of the specified classes.
1587 @c man begin SYNOPSIS gserialver
1588 gserialver [@var{OPTIONS}]@dots{} @var{CLASS}@dots{}
1592 @c man begin OPTIONS gserialver
1595 @item -classpath @var{PATH}
1596 Class path to use to find classes.
1602 Print help text, then exit.
1604 Print version number, then exit.
1605 @item -J@var{OPTION}
1606 Pass argument to the Java runtime.
1611 @c man begin SEEALSO gserialver
1615 @comment ----------------------------------------------------------------------
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
1622 @c man begin DESCRIPTION grmid
1624 @command{rmiregistry} starts a remote object registry on the current
1625 host. If no port number is specified, then port 1099 is used.
1630 @c man begin SYNOPSIS grmid
1631 grmid [@var{OPTIONS}]@dots{}
1635 @c man begin OPTIONS grmid
1637 Activation process control:
1639 @item -port @var{PORT}
1640 Port on which activation system is to be started.
1643 Restart activation system, clearing persistent naming database, if
1647 Stop activation system.
1653 Make activation system persistent.
1655 @item -directory @var{DIR}
1656 Directory in which to store persistent data.
1662 Log binding events to standard out.
1668 Print help text, then exit.
1670 Print version number, then exit.
1671 @item -J@var{OPTION}
1672 Pass argument to the Java runtime.
1677 @c man begin SEEALSO grmid
1681 @comment ----------------------------------------------------------------------
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
1688 @c man begin DESCRIPTION grmiregistry
1690 @command{grmiregistry} starts a remote object registry on the current
1691 host. If no port number is specified, then port 1099 is used.
1696 @c man begin SYNOPSIS grmiregistry
1697 grmiregistry [@var{OPTIONS}]@dots{} @var{PORT}
1701 @c man begin OPTIONS grmiregistry
1703 Registry process control:
1706 Restart RMI naming service, clearing persistent naming database, if
1710 Stop RMI naming service.
1716 Make RMI naming service persistent.
1718 @item -directory @var{DIR}
1719 Directory in which to store persistent data.
1725 Log binding events to standard out.
1731 Print help text, then exit.
1733 Print version number, then exit.
1734 @item -J@var{OPTION}
1735 Pass argument to the Java runtime.
1740 @c man begin SEEALSO grmiregistry
1744 @comment ----------------------------------------------------------------------
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
1751 @c man begin DESCRIPTION gtnameserv
1753 To be written @dots{}
1758 @c man begin SYNOPSIS gtnameserv
1759 tnameserv [@var{OPTIONS}]
1763 @c man begin OPTIONS gtnameserv
1766 @item -ORBInitialPort @var{PORT}
1767 Port on which naming service is to be started.
1769 @item -ior @var{FILE}
1770 File in which to store naming service's IOR reference.
1776 Print help text, then exit.
1778 Print version number, then exit.
1779 @item -J@var{OPTION}
1780 Pass argument to the Java runtime.
1785 @c man begin SEEALSO gtnameserv
1789 @comment ----------------------------------------------------------------------
1791 @node I18N Issues, , Other Tools, Top
1792 @comment node-name, next, previous, up
1793 @chapter I18N Issues
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.
1798 * Language Resources:: Where resources are located
1799 * Message Formats:: How messages are internationalized
1802 @comment ----------------------------------------------------------------------
1804 @node Language Resources, Message Formats, I18N Issues, I18N Issues
1805 @comment node-name, next, previous, up
1806 @section Language-specific resources
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.
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:
1813 Command.23=A correct key password MUST be provided
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.
1818 For the GNU Classpath Tools described in this Guide, the @i{Resource Bundles} are files named @file{messages[_ll[_CC[_VV]]].properties} where:
1822 Is the 2-letter code for the Language,
1824 Is the 2-letter code for the Region, and
1826 Is the 2-letter code for the Variant of the language.
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)}.
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:
1835 @file{gnu/classpath/tools/jarsigner}
1837 @file{gnu/classpath/tools/keytool}
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:
1843 @item @code{messages.properties}
1844 @item @code{messages_fr.properties}
1845 @item @code{messages_fr_FR.properties}
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.
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.
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}.
1854 @comment ----------------------------------------------------------------------
1856 @node Message Formats, , Language Resources, I18N Issues
1857 @comment node-name, next, previous, up
1858 @section Message formats
1860 If you open any of the @file{messages.properties} described in the previous section, you may see properties that look like so:
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@}
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.
1871 If you are translating a @file{messages.properties} be careful not to alter text between curly braces.
1873 @comment ----------------------------------------------------------------------