1 .\"t
2 .\" Copyright (c) 1994, 2019, Oracle and/or its affiliates. All rights reserved.
3 .\" DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 .\"
5 .\" This code is free software; you can redistribute it and/or modify it
6 .\" under the terms of the GNU General Public License version 2 only, as
7 .\" published by the Free Software Foundation.
8 .\"
9 .\" This code is distributed in the hope that it will be useful, but WITHOUT
10 .\" ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
11 .\" FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
12 .\" version 2 for more details (a copy is included in the LICENSE file that
13 .\" accompanied this code).
14 .\"
15 .\" You should have received a copy of the GNU General Public License version
16 .\" 2 along with this work; if not, write to the Free Software Foundation,
17 .\" Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
18 .\"
19 .\" Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
20 .\" or visit www.oracle.com if you need additional information or have any
21 .\" questions.
22 .\"
23 .\" Automatically generated by Pandoc 2.3.1
24 .\"
25 .TH "KEYTOOL" "1" "2020" "JDK 14" "JDK Commands"
26 .hy
27 .SH NAME
28 .PP
29 keytool \- a key and certificate management utility
30 .SH SYNOPSIS
31 .PP
32 \f[CB]keytool\f[R] [\f[I]commands\f[R]]
33 .TP
34 .B \f[I]commands\f[R]
35 Commands for \f[CB]keytool\f[R] include the following:
36 .RS
37 .IP \[bu] 2
38 \f[CB]\-certreq\f[R]: Generates a certificate request
39 .IP \[bu] 2
40 \f[CB]\-changealias\f[R]: Changes an entry\[aq]s alias
41 .IP \[bu] 2
42 \f[CB]\-delete\f[R]: Deletes an entry
43 .IP \[bu] 2
44 \f[CB]\-exportcert\f[R]: Exports certificate
45 .IP \[bu] 2
46 \f[CB]\-genkeypair\f[R]: Generates a key pair
47 .IP \[bu] 2
48 \f[CB]\-genseckey\f[R]: Generates a secret key
49 .IP \[bu] 2
50 \f[CB]\-gencert\f[R]: Generates a certificate from a certificate request
51 .IP \[bu] 2
52 \f[CB]\-importcert\f[R]: Imports a certificate or a certificate chain
53 .IP \[bu] 2
54 \f[CB]\-importpass\f[R]: Imports a password
55 .IP \[bu] 2
56 \f[CB]\-importkeystore\f[R]: Imports one or all entries from another
57 keystore
58 .IP \[bu] 2
59 \f[CB]\-keypasswd\f[R]: Changes the key password of an entry
60 .IP \[bu] 2
61 \f[CB]\-list\f[R]: Lists entries in a keystore
62 .IP \[bu] 2
63 \f[CB]\-printcert\f[R]: Prints the content of a certificate
64 .IP \[bu] 2
65 \f[CB]\-printcertreq\f[R]: Prints the content of a certificate request
66 .IP \[bu] 2
67 \f[CB]\-printcrl\f[R]: Prints the content of a Certificate Revocation List
68 (CRL) file
69 .IP \[bu] 2
70 \f[CB]\-storepasswd\f[R]: Changes the store password of a keystore
71 .IP \[bu] 2
72 \f[CB]\-showinfo\f[R]: Displays security\-related information
73 .PP
74 See \f[B]Commands and Options\f[R] for a description of these commands
75 with their options.
76 .RE
77 .SH DESCRIPTION
78 .PP
79 The \f[CB]keytool\f[R] command is a key and certificate management
80 utility.
81 It enables users to administer their own public/private key pairs and
82 associated certificates for use in self\-authentication (where a user
83 authenticates themselves to other users and services) or data integrity
84 and authentication services, by using digital signatures.
85 The \f[CB]keytool\f[R] command also enables users to cache the public keys
86 (in the form of certificates) of their communicating peers.
87 .PP
88 A certificate is a digitally signed statement from one entity (person,
89 company, and so on), which says that the public key (and some other
90 information) of some other entity has a particular value.
91 When data is digitally signed, the signature can be verified to check
92 the data integrity and authenticity.
93 Integrity means that the data hasn\[aq]t been modified or tampered with,
94 and authenticity means that the data comes from the individual who
95 claims to have created and signed it.
96 .PP
97 The \f[CB]keytool\f[R] command also enables users to administer secret
98 keys and passphrases used in symmetric encryption and decryption (Data
99 Encryption Standard).
100 It can also display other security\-related information.
101 .PP
102 The \f[CB]keytool\f[R] command stores the keys and certificates in a
103 keystore.
104 .SH COMMAND AND OPTION NOTES
105 .PP
106 The following notes apply to the descriptions in \f[B]Commands and
107 Options\f[R]:
108 .IP \[bu] 2
109 All command and option names are preceded by a hyphen sign
110 (\f[CB]\-\f[R]).
111 .IP \[bu] 2
112 Only one command can be provided.
113 .IP \[bu] 2
114 Options for each command can be provided in any order.
115 .IP \[bu] 2
116 There are two kinds of options, one is single\-valued which should be
117 only provided once.
118 If a single\-valued option is provided multiple times, the value of the
119 last one is used.
120 The other type is multi\-valued, which can be provided multiple times
121 and all values are used.
122 The only multi\-valued option currently supported is the \f[CB]\-ext\f[R]
123 option used to generate X.509v3 certificate extensions.
124 .IP \[bu] 2
125 All items not italicized or in braces ({ }) or brackets ([ ]) are
126 required to appear as is.
127 .IP \[bu] 2
128 Braces surrounding an option signify that a default value is used when
129 the option isn\[aq]t specified on the command line.
130 Braces are also used around the \f[CB]\-v\f[R], \f[CB]\-rfc\f[R], and
131 \f[CB]\-J\f[R] options, which have meaning only when they appear on the
132 command line.
133 They don\[aq]t have any default values.
134 .IP \[bu] 2
135 Brackets surrounding an option signify that the user is prompted for the
136 values when the option isn\[aq]t specified on the command line.
137 For the \f[CB]\-keypass\f[R] option, if you don\[aq]t specify the option
138 on the command line, then the \f[CB]keytool\f[R] command first attempts to
139 use the keystore password to recover the private/secret key.
140 If this attempt fails, then the \f[CB]keytool\f[R] command prompts you for
141 the private/secret key password.
142 .IP \[bu] 2
143 Items in italics (option values) represent the actual values that must
144 be supplied.
145 For example, here is the format of the \f[CB]\-printcert\f[R] command:
146 .RS 2
147 .RS
148 .PP
149 \f[CB]keytool\ \-printcert\f[R] {\f[CB]\-file\f[R] \f[I]cert_file\f[R]}
150 {\f[CB]\-v\f[R]}
151 .RE
152 .PP
153 When you specify a \f[CB]\-printcert\f[R] command, replace
154 \f[I]cert_file\f[R] with the actual file name, as follows:
155 \f[CB]keytool\ \-printcert\ \-file\ VScert.cer\f[R]
156 .RE
157 .IP \[bu] 2
158 Option values must be enclosed in quotation marks when they contain a
159 blank (space).
160 .SH COMMANDS AND OPTIONS
161 .PP
162 The keytool commands and their options can be grouped by the tasks that
163 they perform.
164 .PP
165 \f[B]Commands for Creating or Adding Data to the Keystore\f[R]:
166 .IP \[bu] 2
167 \f[CB]\-gencert\f[R]
168 .IP \[bu] 2
169 \f[CB]\-genkeypair\f[R]
170 .IP \[bu] 2
171 \f[CB]\-genseckey\f[R]
172 .IP \[bu] 2
173 \f[CB]\-importcert\f[R]
174 .IP \[bu] 2
175 \f[CB]\-importpass\f[R]
176 .PP
177 \f[B]Commands for Importing Contents from Another Keystore\f[R]:
178 .IP \[bu] 2
179 \f[CB]\-importkeystore\f[R]
180 .PP
181 \f[B]Commands for Generating a Certificate Request\f[R]:
182 .IP \[bu] 2
183 \f[CB]\-certreq\f[R]
184 .PP
185 \f[B]Commands for Exporting Data\f[R]:
186 .IP \[bu] 2
187 \f[CB]\-exportcert\f[R]
188 .PP
189 \f[B]Commands for Displaying Data\f[R]:
190 .IP \[bu] 2
191 \f[CB]\-list\f[R]
192 .IP \[bu] 2
193 \f[CB]\-printcert\f[R]
194 .IP \[bu] 2
195 \f[CB]\-printcertreq\f[R]
196 .IP \[bu] 2
197 \f[CB]\-printcrl\f[R]
198 .PP
199 \f[B]Commands for Managing the Keystore\f[R]:
200 .IP \[bu] 2
201 \f[CB]\-storepasswd\f[R]
202 .IP \[bu] 2
203 \f[CB]\-keypasswd\f[R]
204 .IP \[bu] 2
205 \f[CB]\-delete\f[R]
206 .IP \[bu] 2
207 \f[CB]\-changealias\f[R]
208 .PP
209 \f[B]Commands for Displaying Security\-related Information\f[R]:
210 .IP \[bu] 2
211 \f[CB]\-showinfo\f[R]
212 .SH COMMANDS FOR CREATING OR ADDING DATA TO THE KEYSTORE
213 .TP
214 .B \f[CB]\-gencert\f[R]
215 The following are the available options for the \f[CB]\-gencert\f[R]
216 command:
217 .RS
218 .IP \[bu] 2
219 {\f[CB]\-rfc\f[R]}: Output in RFC (Request For Comment) style
220 .IP \[bu] 2
221 {\f[CB]\-infile\f[R] \f[I]infile\f[R]}: Input file name
222 .IP \[bu] 2
223 {\f[CB]\-outfile\f[R] \f[I]outfile\f[R]}: Output file name
224 .IP \[bu] 2
225 {\f[CB]\-alias\f[R] \f[I]alias\f[R]}: Alias name of the entry to process
226 .IP \[bu] 2
227 {\f[CB]\-sigalg\f[R] \f[I]sigalg\f[R]}: Signature algorithm name
228 .IP \[bu] 2
229 {\f[CB]\-dname\f[R] \f[I]dname\f[R]}: Distinguished name
230 .IP \[bu] 2
231 {\f[CB]\-startdate\f[R] \f[I]startdate\f[R]}: Certificate validity start
232 date and time
233 .IP \[bu] 2
234 {\f[CB]\-ext\f[R] \f[I]ext\f[R]}*: X.509 extension
235 .IP \[bu] 2
236 {\f[CB]\-validity\f[R] \f[I]days\f[R]}: Validity number of days
237 .IP \[bu] 2
238 [\f[CB]\-keypass\f[R] \f[I]arg\f[R]]: Key password
239 .IP \[bu] 2
240 {\f[CB]\-keystore\f[R] \f[I]keystore\f[R]}: Keystore name
241 .IP \[bu] 2
242 [\f[CB]\-storepass\f[R] \f[I]arg\f[R]]: Keystore password
243 .IP \[bu] 2
244 {\f[CB]\-storetype\f[R] \f[I]type\f[R]}: Keystore type
245 .IP \[bu] 2
246 {\f[CB]\-providername\f[R] \f[I]name\f[R]}: Provider name
247 .IP \[bu] 2
248 {\f[CB]\-addprovider\f[R] \f[I]name\f[R] [\f[CB]\-providerarg\f[R]
249 \f[I]arg\f[R]]}: Adds a security provider by name (such as SunPKCS11)
250 with an optional configure argument.
251 The value of the security provider is the name of a security provider
252 that is defined in a module.
253 .RS 2
254 .PP
255 For example,
256 .RS
257 .PP
258 \f[CB]keytool\ \-addprovider\ SunPKCS11\ \-providerarg\ some.cfg\ ...\f[R]
259 .RE
260 .PP
261 \f[B]Note:\f[R]
262 .PP
263 For compatibility reasons, the SunPKCS11 and OracleUcrypto providers can
264 still be loaded with
265 \f[CB]\-providerclass\ sun.security.pkcs11.SunPKCS11\f[R] and
266 \f[CB]\-providerclass\ com.oracle.security.crypto.UcryptoProvider\f[R]
267 even if they are now defined in modules.
268 These are the only modules included in JDK that need a configuration,
269 and therefore the most widely used with the \f[CB]\-providerclass\f[R]
270 option.
271 For legacy security providers located on classpath and loaded by
272 reflection, \f[CB]\-providerclass\f[R] should still be used.
273 .RE
274 .IP \[bu] 2
275 {\f[CB]\-providerclass\f[R] \f[I]class\f[R] [\f[CB]\-providerarg\f[R]
276 \f[I]arg\f[R]]}: Add security provider by fully qualified class name with
277 an optional configure argument.
278 .RS 2
279 .PP
280 For example, if \f[CB]MyProvider\f[R] is a legacy provider loaded via
281 reflection,
282 .RS
283 .PP
284 \f[CB]keytool\ \-providerclass\ com.example.MyProvider\ ...\f[R]
285 .RE
286 .RE
287 .IP \[bu] 2
288 {\f[CB]\-providerpath\f[R] \f[I]list\f[R]}: Provider classpath
289 .IP \[bu] 2
290 {\f[CB]\-v\f[R]}: Verbose output
291 .IP \[bu] 2
292 {\f[CB]\-protected\f[R]}: Password provided through a protected mechanism
293 .PP
294 Use the \f[CB]\-gencert\f[R] command to generate a certificate as a
295 response to a certificate request file (which can be created by the
296 \f[CB]keytool\ \-certreq\f[R] command).
297 The command reads the request either from \f[I]infile\f[R] or, if
298 omitted, from the standard input, signs it by using the alias\[aq]s
299 private key, and outputs the X.509 certificate into either
300 \f[I]outfile\f[R] or, if omitted, to the standard output.
301 When \f[CB]\-rfc\f[R] is specified, the output format is Base64\-encoded
302 PEM; otherwise, a binary DER is created.
303 .PP
304 The \f[CB]\-sigalg\f[R] value specifies the algorithm that should be used
305 to sign the certificate.
306 The \f[I]startdate\f[R] argument is the start time and date that the
307 certificate is valid.
308 The \f[I]days\f[R] argument tells the number of days for which the
309 certificate should be considered valid.
310 .PP
311 When \f[I]dname\f[R] is provided, it is used as the subject of the
312 generated certificate.
313 Otherwise, the one from the certificate request is used.
314 .PP
315 The \f[CB]\-ext\f[R] value shows what X.509 extensions will be embedded in
316 the certificate.
317 Read \f[B]Common Command Options\f[R] for the grammar of \f[CB]\-ext\f[R].
318 .PP
319 The \f[CB]\-gencert\f[R] option enables you to create certificate chains.
320 The following example creates a certificate, \f[CB]e1\f[R], that contains
321 three certificates in its certificate chain.
322 .PP
323 The following commands creates four key pairs named \f[CB]ca\f[R],
324 \f[CB]ca1\f[R], \f[CB]ca2\f[R], and \f[CB]e1\f[R]:
325 .IP
326 .nf
327 \f[CB]
328 keytool\ \-alias\ ca\ \-dname\ CN=CA\ \-genkeypair\ \-keyalg\ rsa
329 keytool\ \-alias\ ca1\ \-dname\ CN=CA\ \-genkeypair\ \-keyalg\ rsa
330 keytool\ \-alias\ ca2\ \-dname\ CN=CA\ \-genkeypair\ \-keyalg\ rsa
331 keytool\ \-alias\ e1\ \-dname\ CN=E1\ \-genkeypair\ \-keyalg\ rsa
332 \f[R]
333 .fi
334 .PP
335 The following two commands create a chain of signed certificates;
336 \f[CB]ca\f[R] signs \f[CB]ca1\f[R] and \f[CB]ca1\f[R] signs \f[CB]ca2\f[R], all
337 of which are self\-issued:
338 .IP
339 .nf
340 \f[CB]
341 keytool\ \-alias\ ca1\ \-certreq\ |
342 \ \ \ \ keytool\ \-alias\ ca\ \-gencert\ \-ext\ san=dns:ca1\ |
343 \ \ \ \ keytool\ \-alias\ ca1\ \-importcert
344
345 keytool\ \-alias\ ca2\ \-certreq\ |
346 \ \ \ \ keytool\ \-alias\ ca1\ \-gencert\ \-ext\ san=dns:ca2\ |
347 \ \ \ \ keytool\ \-alias\ ca2\ \-importcert
348 \f[R]
349 .fi
350 .PP
351 The following command creates the certificate \f[CB]e1\f[R] and stores it
352 in the \f[CB]e1.cert\f[R] file, which is signed by \f[CB]ca2\f[R].
353 As a result, \f[CB]e1\f[R] should contain \f[CB]ca\f[R], \f[CB]ca1\f[R], and
354 \f[CB]ca2\f[R] in its certificate chain:
355 .RS
356 .PP
357 \f[CB]keytool\ \-alias\ e1\ \-certreq\ |\ keytool\ \-alias\ ca2\ \-gencert\ >\ e1.cert\f[R]
358 .RE
359 .RE
360 .TP
361 .B \f[CB]\-genkeypair\f[R]
362 The following are the available options for the \f[CB]\-genkeypair\f[R]
363 command:
364 .RS
365 .IP \[bu] 2
366 {\f[CB]\-alias\f[R] \f[I]alias\f[R]}: Alias name of the entry to process
367 .IP \[bu] 2
368 \f[CB]\-keyalg\f[R] \f[I]alg\f[R]: Key algorithm name
369 .IP \[bu] 2
370 {\f[CB]\-keysize\f[R] \f[I]size\f[R]}: Key bit size
371 .IP \[bu] 2
372 {\f[CB]\-groupname\f[R] \f[I]name\f[R]}: Group name.
373 For example, an Elliptic Curve name.
374 .IP \[bu] 2
375 {\f[CB]\-sigalg\f[R] \f[I]alg\f[R]}: Signature algorithm name
376 .IP \[bu] 2
377 [\f[CB]\-dname\f[R] \f[I]name\f[R]]: Distinguished name
378 .IP \[bu] 2
379 {\f[CB]\-startdate\f[R] \f[I]date\f[R]}: Certificate validity start date
380 and time
381 .IP \[bu] 2
382 {\f[CB]\-ext\f[R] \f[I]value\f[R]}*: X.509 extension
383 .IP \[bu] 2
384 {\f[CB]\-validity\f[R] \f[I]days\f[R]}: Validity number of days
385 .IP \[bu] 2
386 [\f[CB]\-keypass\f[R] \f[I]arg\f[R]]: Key password
387 .IP \[bu] 2
388 {\f[CB]\-keystore\f[R] \f[I]keystore\f[R]}: Keystore name
389 .IP \[bu] 2
390 [\f[CB]\-storepass\f[R] \f[I]arg\f[R]]: Keystore password
391 .IP \[bu] 2
392 {\f[CB]\-storetype\f[R] \f[I]type\f[R]}: Keystore type
393 .IP \[bu] 2
394 {\f[CB]\-providername\f[R] \f[I]name\f[R]}: Provider name
395 .IP \[bu] 2
396 {\f[CB]\-addprovider\f[R] \f[I]name\f[R] [\f[CB]\-providerarg\f[R]
397 \f[I]arg\f[R]]}: Add security provider by name (such as SunPKCS11) with
398 an optional configure argument.
399 .IP \[bu] 2
400 {\f[CB]\-providerclass\f[R] \f[I]class\f[R] [\f[CB]\-providerarg\f[R]
401 \f[I]arg\f[R]] }: Add security provider by fully qualified class name
402 with an optional configure argument.
403 .IP \[bu] 2
404 {\f[CB]\-providerpath\f[R] \f[I]list\f[R]}: Provider classpath
405 .IP \[bu] 2
406 {\f[CB]\-v\f[R]}: Verbose output
407 .IP \[bu] 2
408 {\f[CB]\-protected\f[R]}: Password provided through a protected mechanism
409 .PP
410 Use the \f[CB]\-genkeypair\f[R] command to generate a key pair (a public
411 key and associated private key).
412 Wraps the public key in an X.509 v3 self\-signed certificate, which is
413 stored as a single\-element certificate chain.
414 This certificate chain and the private key are stored in a new keystore
415 entry that is identified by its alias.
416 .PP
417 The \f[CB]\-keyalg\f[R] value specifies the algorithm to be used to
418 generate the key pair, and the \f[CB]\-keysize\f[R] value specifies the
419 size of each key to be generated.
420 The \f[CB]\-sigalg\f[R] value specifies the algorithm that should be used
421 to sign the self\-signed certificate.
422 This algorithm must be compatible with the \f[CB]\-keyalg\f[R] value.
423 .PP
424 The \f[CB]\-groupname\f[R] value specifies the named group (for example,
425 the standard or predefined name of an Elliptic Curve) of the key to be
426 generated.
427 Only one of \f[CB]\-groupname\f[R] and \f[CB]\-keysize\f[R] can be
428 specified.
429 .PP
430 The \f[CB]\-dname\f[R] value specifies the X.500 Distinguished Name to be
431 associated with the value of \f[CB]\-alias\f[R], and is used as the issuer
432 and subject fields in the self\-signed certificate.
433 If a distinguished name is not provided at the command line, then the
434 user is prompted for one.
435 .PP
436 The value of \f[CB]\-keypass\f[R] is a password used to protect the
437 private key of the generated key pair.
438 If a password is not provided, then the user is prompted for it.
439 If you press the \f[B]Return\f[R] key at the prompt, then the key
440 password is set to the same password as the keystore password.
441 The \f[CB]\-keypass\f[R] value must have at least six characters.
442 .PP
443 The value of \f[CB]\-startdate\f[R] specifies the issue time of the
444 certificate, also known as the "Not Before" value of the X.509
445 certificate\[aq]s Validity field.
446 .PP
447 The option value can be set in one of these two forms:
448 .PP
449 ([\f[CB]+\-\f[R]]\f[I]nnn\f[R][\f[CB]ymdHMS\f[R]])+
450 .PP
451 [\f[I]yyyy\f[R]\f[CB]/\f[R]\f[I]mm\f[R]\f[CB]/\f[R]\f[I]dd\f[R]]
452 [\f[I]HH\f[R]\f[CB]:\f[R]\f[I]MM\f[R]\f[CB]:\f[R]\f[I]SS\f[R]]
453 .PP
454 With the first form, the issue time is shifted by the specified value
455 from the current time.
456 The value is a concatenation of a sequence of subvalues.
457 Inside each subvalue, the plus sign (+) means shift forward, and the
458 minus sign (\-) means shift backward.
459 The time to be shifted is \f[I]nnn\f[R] units of years, months, days,
460 hours, minutes, or seconds (denoted by a single character of \f[CB]y\f[R],
461 \f[CB]m\f[R], \f[CB]d\f[R], \f[CB]H\f[R], \f[CB]M\f[R], or \f[CB]S\f[R]
462 respectively).
463 The exact value of the issue time is calculated by using the
464 \f[CB]java.util.GregorianCalendar.add(int\ field,\ int\ amount)\f[R]
465 method on each subvalue, from left to right.
466 For example, the issue time can be specified by:
467 .IP
468 .nf
469 \f[CB]
470 Calendar\ c\ =\ new\ GregorianCalendar();
471 c.add(Calendar.YEAR,\ \-1);
472 c.add(Calendar.MONTH,\ 1);
473 c.add(Calendar.DATE,\ \-1);
474 return\ c.getTime()
475 \f[R]
476 .fi
477 .PP
478 With the second form, the user sets the exact issue time in two parts,
479 year/month/day and hour:minute:second (using the local time zone).
480 The user can provide only one part, which means the other part is the
481 same as the current date (or time).
482 The user must provide the exact number of digits shown in the format
483 definition (padding with 0 when shorter).
484 When both date and time are provided, there is one (and only one) space
485 character between the two parts.
486 The hour should always be provided in 24\-hour format.
487 .PP
488 When the option isn\[aq]t provided, the start date is the current time.
489 The option can only be provided one time.
490 .PP
491 The value of \f[I]date\f[R] specifies the number of days (starting at the
492 date specified by \f[CB]\-startdate\f[R], or the current date when
493 \f[CB]\-startdate\f[R] isn\[aq]t specified) for which the certificate
494 should be considered valid.
495 .RE
496 .TP
497 .B \f[CB]\-genseckey\f[R]
498 The following are the available options for the \f[CB]\-genseckey\f[R]
499 command:
500 .RS
501 .IP \[bu] 2
502 {\f[CB]\-alias\f[R] \f[I]alias\f[R]}: Alias name of the entry to process
503 .IP \[bu] 2
504 [\f[CB]\-keypass\f[R] \f[I]arg\f[R]]: Key password
505 .IP \[bu] 2
506 \f[CB]\-keyalg\f[R] \f[I]alg\f[R]: Key algorithm name
507 .IP \[bu] 2
508 {\f[CB]\-keysize\f[R] \f[I]size\f[R]}: Key bit size
509 .IP \[bu] 2
510 {\f[CB]\-keystore\f[R] \f[I]keystore\f[R]}: Keystore name
511 .IP \[bu] 2
512 [\f[CB]\-storepass\f[R] \f[I]arg\f[R]]: Keystore password
513 .IP \[bu] 2
514 {\f[CB]\-storetype\f[R] \f[I]type\f[R]}: Keystore type
515 .IP \[bu] 2
516 {\f[CB]\-providername\f[R] \f[I]name\f[R]}: Provider name
517 .IP \[bu] 2
518 {\f[CB]\-addprovider\f[R] \f[I]name\f[R] [\f[CB]\-providerarg\f[R]
519 \f[I]arg\f[R]]}: Add security provider by name (such as SunPKCS11) with
520 an optional configure argument.
521 .IP \[bu] 2
522 {\f[CB]\-providerclass\f[R] \f[I]class\f[R] [\f[CB]\-providerarg\f[R]
523 \f[I]arg\f[R]]}: Add security provider by fully qualified class name with
524 an optional configure argument.
525 .IP \[bu] 2
526 {\f[CB]\-providerpath\f[R] \f[I]list\f[R]}: Provider classpath
527 .IP \[bu] 2
528 {\f[CB]\-v\f[R]}: Verbose output
529 .IP \[bu] 2
530 {\f[CB]\-protected\f[R]}: Password provided through a protected mechanism
531 .PP
532 Use the \f[CB]\-genseckey\f[R] command to generate a secret key and store
533 it in a new \f[CB]KeyStore.SecretKeyEntry\f[R] identified by
534 \f[CB]alias\f[R].
535 .PP
536 The value of \f[CB]\-keyalg\f[R] specifies the algorithm to be used to
537 generate the secret key, and the value of \f[CB]\-keysize\f[R] specifies
538 the size of the key that is generated.
539 The \f[CB]\-keypass\f[R] value is a password that protects the secret key.
540 If a password is not provided, then the user is prompted for it.
541 If you press the \f[B]Return\f[R] key at the prompt, then the key
542 password is set to the same password that is used for the
543 \f[CB]\-keystore\f[R].
544 The \f[CB]\-keypass\f[R] value must contain at least six characters.
545 .RE
546 .TP
547 .B \f[CB]\-importcert\f[R]
548 The following are the available options for the \f[CB]\-importcert\f[R]
549 command:
550 .RS
551 .IP \[bu] 2
552 {\f[CB]\-noprompt\f[R]}: Do not prompt
553 .IP \[bu] 2
554 {\f[CB]\-trustcacerts\f[R]}: Trust certificates from cacerts
555 .IP \[bu] 2
556 {\f[CB]\-protected\f[R]}: Password is provided through protected mechanism
557 .IP \[bu] 2
558 {\f[CB]\-alias\f[R] \f[I]alias\f[R]}: Alias name of the entry to process
559 .IP \[bu] 2
560 {\f[CB]\-file\f[R] \f[I]file\f[R]}: Input file name
561 .IP \[bu] 2
562 [\f[CB]\-keypass\f[R] \f[I]arg\f[R]]: Key password
563 .IP \[bu] 2
564 {\f[CB]\-keystore\f[R] \f[I]keystore\f[R]}: Keystore name
565 .IP \[bu] 2
566 {\f[CB]\-cacerts\f[R]}: Access the cacerts keystore
567 .IP \[bu] 2
568 [\f[CB]\-storepass\f[R] \f[I]arg\f[R]]: Keystore password
569 .IP \[bu] 2
570 {\f[CB]\-storetype\f[R] \f[I]type\f[R]}: Keystore type
571 .IP \[bu] 2
572 {\f[CB]\-providername\f[R] \f[I]name\f[R]}: Provider name
573 .IP \[bu] 2
574 {\f[CB]\-addprovider\f[R] \f[I]name\f[R] [\f[CB]\-providerarg\f[R]
575 \f[I]arg\f[R]]}: Add security provider by name (such as SunPKCS11) with
576 an optional configure argument.
577 .IP \[bu] 2
578 {\f[CB]\-providerclass\f[R] \f[I]class\f[R] [\f[CB]\-providerarg\f[R]
579 \f[I]arg\f[R]]}: Add security provider by fully qualified class name with
580 an optional configure argument.
581 .IP \[bu] 2
582 {\f[CB]\-providerpath\f[R] \f[I]list\f[R]}: Provider classpath
583 .IP \[bu] 2
584 {\f[CB]\-v\f[R]}: Verbose output
585 .PP
586 Use the \f[CB]\-importcert\f[R] command to read the certificate or
587 certificate chain (where the latter is supplied in a PKCS#7 formatted
588 reply or in a sequence of X.509 certificates) from \f[CB]\-file\f[R]
589 \f[I]file\f[R], and store it in the \f[CB]keystore\f[R] entry identified by
590 \f[CB]\-alias\f[R].
591 If \f[CB]\-file\f[R] \f[I]file\f[R] is not specified, then the certificate
592 or certificate chain is read from \f[CB]stdin\f[R].
593 .PP
594 The \f[CB]keytool\f[R] command can import X.509 v1, v2, and v3
595 certificates, and PKCS#7 formatted certificate chains consisting of
596 certificates of that type.
597 The data to be imported must be provided either in binary encoding
598 format or in printable encoding format (also known as Base64 encoding)
599 as defined by the Internet RFC 1421 standard.
600 In the latter case, the encoding must be bounded at the beginning by a
601 string that starts with \f[CB]\-\-\-\-\-BEGIN\f[R], and bounded at the end
602 by a string that starts with \f[CB]\-\-\-\-\-END\f[R].
603 .PP
604 You import a certificate for two reasons: To add it to the list of
605 trusted certificates, and to import a certificate reply received from a
606 certificate authority (CA) as the result of submitting a Certificate
607 Signing Request (CSR) to that CA.
608 See the \f[CB]\-certreq\f[R] command in \f[B]Commands for Generating a
609 Certificate Request\f[R].
610 .PP
611 The type of import is indicated by the value of the \f[CB]\-alias\f[R]
612 option.
613 If the alias doesn\[aq]t point to a key entry, then the \f[CB]keytool\f[R]
614 command assumes you are adding a trusted certificate entry.
615 In this case, the alias shouldn\[aq]t already exist in the keystore.
616 If the alias does exist, then the \f[CB]keytool\f[R] command outputs an
617 error because a trusted certificate already exists for that alias, and
618 doesn\[aq]t import the certificate.
619 If \f[CB]\-alias\f[R] points to a key entry, then the \f[CB]keytool\f[R]
620 command assumes that you\[aq]re importing a certificate reply.
621 .RE
622 .TP
623 .B \f[CB]\-importpass\f[R]
624 The following are the available options for the \f[CB]\-importpass\f[R]
625 command:
626 .RS
627 .IP \[bu] 2
628 {\f[CB]\-alias\f[R] \f[I]alias\f[R]}: Alias name of the entry to process
629 .IP \[bu] 2
630 [\f[CB]\-keypass\f[R] \f[I]arg\f[R]]: Key password
631 .IP \[bu] 2
632 {\f[CB]\-keyalg\f[R] \f[I]alg\f[R]}: Key algorithm name
633 .IP \[bu] 2
634 {\f[CB]\-keysize\f[R] \f[I]size\f[R]}: Key bit size
635 .IP \[bu] 2
636 {\f[CB]\-keystore\f[R] \f[I]keystore\f[R]}: Keystore name
637 .IP \[bu] 2
638 [\f[CB]\-storepass\f[R] \f[I]arg\f[R]]: Keystore password
639 .IP \[bu] 2
640 {\f[CB]\-storetype\f[R] \f[I]type\f[R]}: Keystore type
641 .IP \[bu] 2
642 {\f[CB]\-providername\f[R] \f[I]name\f[R]}: Provider name
643 .IP \[bu] 2
644 {\f[CB]\-addprovider\f[R] \f[I]name\f[R] [\f[CB]\-providerarg\f[R]
645 \f[I]arg\f[R]]}: Add security provider by name (such as SunPKCS11) with
646 an optional configure argument.
647 .IP \[bu] 2
648 {\f[CB]\-providerclass\f[R] \f[I]class\f[R] [\f[CB]\-providerarg\f[R]
649 \f[I]arg\f[R]]}: Add security provider by fully qualified class name with
650 an optional configure argument.
651 .IP \[bu] 2
652 {\f[CB]\-providerpath\f[R] \f[I]list\f[R]}: Provider classpath
653 .IP \[bu] 2
654 {\f[CB]\-v\f[R]}: Verbose output
655 .IP \[bu] 2
656 {\f[CB]\-protected\f[R]}: Password provided through a protected mechanism
657 .PP
658 Use the \f[CB]\-importpass\f[R] command to imports a passphrase and store
659 it in a new \f[CB]KeyStore.SecretKeyEntry\f[R] identified by
660 \f[CB]\-alias\f[R].
661 The passphrase may be supplied via the standard input stream; otherwise
662 the user is prompted for it.
663 The \f[CB]\-keypass\f[R] option provides a password to protect the
664 imported passphrase.
665 If a password is not provided, then the user is prompted for it.
666 If you press the \f[B]Return\f[R] key at the prompt, then the key
667 password is set to the same password as that used for the
668 \f[CB]keystore\f[R].
669 The \f[CB]\-keypass\f[R] value must contain at least six characters.
670 .RE
671 .SH COMMANDS FOR IMPORTING CONTENTS FROM ANOTHER KEYSTORE
672 .TP
673 .B \f[CB]\-importkeystore\f[R]
674 The following are the available options for the
675 \f[CB]\-importkeystore\f[R] command:
676 .RS
677 .IP \[bu] 2
678 \f[CB]\-srckeystore\f[R] \f[I]keystore\f[R]: Source keystore name
679 .IP \[bu] 2
680 {\f[CB]\-destkeystore\f[R] \f[I]keystore\f[R]}: Destination keystore name
681 .IP \[bu] 2
682 {\f[CB]\-srcstoretype\f[R] \f[I]type\f[R]}: Source keystore type
683 .IP \[bu] 2
684 {\f[CB]\-deststoretype\f[R] \f[I]type\f[R]}: Destination keystore type
685 .IP \[bu] 2
686 [\f[CB]\-srcstorepass\f[R] \f[I]arg\f[R]]: Source keystore password
687 .IP \[bu] 2
688 [\f[CB]\-deststorepass\f[R] \f[I]arg\f[R]]: Destination keystore password
689 .IP \[bu] 2
690 {\f[CB]\-srcprotected\f[R]}: Source keystore password protected
691 .IP \[bu] 2
692 {\f[CB]\-destprotected\f[R]}: Destination keystore password protected
693 .IP \[bu] 2
694 {\f[CB]\-srcprovidername\f[R] \f[I]name\f[R]}: Source keystore provider
695 name
696 .IP \[bu] 2
697 {\f[CB]\-destprovidername\f[R] \f[I]name\f[R]}: Destination keystore
698 provider name
699 .IP \[bu] 2
700 {\f[CB]\-srcalias\f[R] \f[I]alias\f[R]}: Source alias
701 .IP \[bu] 2
702 {\f[CB]\-destalias\f[R] \f[I]alias\f[R]}: Destination alias
703 .IP \[bu] 2
704 [\f[CB]\-srckeypass\f[R] \f[I]arg\f[R]]: Source key password
705 .IP \[bu] 2
706 [\f[CB]\-destkeypass\f[R] \f[I]arg\f[R]]: Destination key password
707 .IP \[bu] 2
708 {\f[CB]\-noprompt\f[R]}: Do not prompt
709 .IP \[bu] 2
710 {\f[CB]\-addprovider\f[R] \f[I]name\f[R] [\f[CB]\-providerarg\f[R]
711 \f[I]arg\f[R]]: Add security provider by name (such as SunPKCS11) with an
712 optional configure argument.
713 .IP \[bu] 2
714 {\f[CB]\-providerclass\f[R] \f[I]class\f[R] [\f[CB]\-providerarg\f[R]
715 \f[I]arg\f[R]]}: Add security provider by fully qualified class name with
716 an optional configure argument
717 .IP \[bu] 2
718 {\f[CB]\-providerpath\f[R] \f[I]list\f[R]}: Provider classpath
719 .IP \[bu] 2
720 {\f[CB]\-v\f[R]}: Verbose output
721 .PP
722 \f[B]Note:\f[R]
723 .PP
724 This is the first line of all options:
725 .RS
726 .PP
727 \f[CB]\-srckeystore\f[R] \f[I]keystore\f[R] \f[CB]\-destkeystore\f[R]
728 \f[I]keystore\f[R]
729 .RE
730 .PP
731 Use the \f[CB]\-importkeystore\f[R] command to import a single entry or
732 all entries from a source keystore to a destination keystore.
733 .PP
734 \f[B]Note:\f[R]
735 .PP
736 If you do not specify \f[CB]\-destkeystore\f[R] when using the
737 \f[CB]keytool\ \-importkeystore\f[R] command, then the default keystore
738 used is \f[CB]$HOME/.keystore\f[R].
739 .PP
740 When the \f[CB]\-srcalias\f[R] option is provided, the command imports the
741 single entry identified by the alias to the destination keystore.
742 If a destination alias isn\[aq]t provided with \f[CB]\-destalias\f[R],
743 then \f[CB]\-srcalias\f[R] is used as the destination alias.
744 If the source entry is protected by a password, then
745 \f[CB]\-srckeypass\f[R] is used to recover the entry.
746 If \f[CB]\-srckeypass\f[R] isn\[aq]t provided, then the \f[CB]keytool\f[R]
747 command attempts to use \f[CB]\-srcstorepass\f[R] to recover the entry.
748 If \f[CB]\-srcstorepass\f[R] is not provided or is incorrect, then the
749 user is prompted for a password.
750 The destination entry is protected with \f[CB]\-destkeypass\f[R].
751 If \f[CB]\-destkeypass\f[R] isn\[aq]t provided, then the destination entry
752 is protected with the source entry password.
753 For example, most third\-party tools require \f[CB]storepass\f[R] and
754 \f[CB]keypass\f[R] in a PKCS #12 keystore to be the same.
755 To create a PKCS#12 keystore for these tools, always specify a
756 \f[CB]\-destkeypass\f[R] that is the same as \f[CB]\-deststorepass\f[R].
757 .PP
758 If the \f[CB]\-srcalias\f[R] option isn\[aq]t provided, then all entries
759 in the source keystore are imported into the destination keystore.
760 Each destination entry is stored under the alias from the source entry.
761 If the source entry is protected by a password, then
762 \f[CB]\-srcstorepass\f[R] is used to recover the entry.
763 If \f[CB]\-srcstorepass\f[R] is not provided or is incorrect, then the
764 user is prompted for a password.
765 If a source keystore entry type isn\[aq]t supported in the destination
766 keystore, or if an error occurs while storing an entry into the
767 destination keystore, then the user is prompted either to skip the entry
768 and continue or to quit.
769 The destination entry is protected with the source entry password.
770 .PP
771 If the destination alias already exists in the destination keystore,
772 then the user is prompted either to overwrite the entry or to create a
773 new entry under a different alias name.
774 .PP
775 If the \f[CB]\-noprompt\f[R] option is provided, then the user isn\[aq]t
776 prompted for a new destination alias.
777 Existing entries are overwritten with the destination alias name.
778 Entries that can\[aq]t be imported are skipped and a warning is
779 displayed.
780 .RE
781 .SH COMMANDS FOR GENERATING A CERTIFICATE REQUEST
782 .TP
783 .B \f[CB]\-certreq\f[R]
784 The following are the available options for the \f[CB]\-certreq\f[R]
785 command:
786 .RS
787 .IP \[bu] 2
788 {\f[CB]\-alias\f[R] \f[I]alias\f[R]}: Alias name of the entry to process
789 .IP \[bu] 2
790 {\f[CB]\-sigalg\f[R] \f[I]alg\f[R]}: Signature algorithm name
791 .IP \[bu] 2
792 {\f[CB]\-file\f[R] \f[I]file\f[R]}: Output file name
793 .IP \[bu] 2
794 [ \f[CB]\-keypass\f[R] \f[I]arg\f[R]]: Key password
795 .IP \[bu] 2
796 {\f[CB]\-keystore\f[R] \f[I]keystore\f[R]}: Keystore name
797 .IP \[bu] 2
798 {\f[CB]\-dname\f[R] \f[I]name\f[R]}: Distinguished name
799 .IP \[bu] 2
800 {\f[CB]\-ext\f[R] \f[I]value\f[R]}: X.509 extension
801 .IP \[bu] 2
802 [\f[CB]\-storepass\f[R] \f[I]arg\f[R]]: Keystore password
803 .IP \[bu] 2
804 {\f[CB]\-storetype\f[R] \f[I]type\f[R]}: Keystore type
805 .IP \[bu] 2
806 {\f[CB]\-providername\f[R] \f[I]name\f[R]}: Provider name
807 .IP \[bu] 2
808 {\f[CB]\-addprovider\f[R] \f[I]name\f[R] [\f[CB]\-providerarg\f[R]
809 \f[I]arg\f[R]]}: Add security provider by name (such as SunPKCS11) with
810 an optional configure argument.
811 .IP \[bu] 2
812 {\f[CB]\-providerclass\f[R] \f[I]class\f[R] [\f[CB]\-providerarg\f[R]
813 \f[I]arg\f[R]]}: Add security provider by fully qualified class name with
814 an optional configure argument.
815 .IP \[bu] 2
816 {\f[CB]\-providerpath\f[R] \f[I]list\f[R]}: Provider classpath
817 .IP \[bu] 2
818 {\f[CB]\-v\f[R]}: Verbose output
819 .IP \[bu] 2
820 {\f[CB]\-protected\f[R]}: Password provided through a protected mechanism
821 .PP
822 Use the \f[CB]\-certreq\f[R] command to generate a Certificate Signing
823 Request (CSR) using the PKCS #10 format.
824 .PP
825 A CSR is intended to be sent to a CA.
826 The CA authenticates the certificate requestor (usually offline) and
827 returns a certificate or certificate chain to replace the existing
828 certificate chain (initially a self\-signed certificate) in the
829 keystore.
830 .PP
831 The private key associated with \f[I]alias\f[R] is used to create the
832 PKCS #10 certificate request.
833 To access the private key, the correct password must be provided.
834 If \f[CB]\-keypass\f[R] isn\[aq]t provided at the command line and is
835 different from the password used to protect the integrity of the
836 keystore, then the user is prompted for it.
837 If \f[CB]\-dname\f[R] is provided, then it is used as the subject in the
838 CSR.
839 Otherwise, the X.500 Distinguished Name associated with alias is used.
840 .PP
841 The \f[CB]\-sigalg\f[R] value specifies the algorithm that should be used
842 to sign the CSR.
843 .PP
844 The CSR is stored in the \f[CB]\-file\f[R] \f[I]file\f[R].
845 If a file is not specified, then the CSR is output to \f[CB]\-stdout\f[R].
846 .PP
847 Use the \f[CB]\-importcert\f[R] command to import the response from the
848 CA.
849 .RE
850 .SH COMMANDS FOR EXPORTING DATA
851 .TP
852 .B \f[CB]\-exportcert\f[R]
853 The following are the available options for the \f[CB]\-exportcert\f[R]
854 command:
855 .RS
856 .IP \[bu] 2
857 {\f[CB]\-rfc\f[R]}: Output in RFC style
858 .IP \[bu] 2
859 {\f[CB]\-alias\f[R] \f[I]alias\f[R]}: Alias name of the entry to process
860 .IP \[bu] 2
861 {\f[CB]\-file\f[R] \f[I]file\f[R]}: Output file name
862 .IP \[bu] 2
863 {\f[CB]\-keystore\f[R] \f[I]keystore\f[R]}: Keystore name
864 .IP \[bu] 2
865 {\f[CB]\-cacerts\f[R]}: Access the cacerts keystore
866 .IP \[bu] 2
867 [\f[CB]\-storepass\f[R] \f[I]arg\f[R]]: Keystore password
868 .IP \[bu] 2
869 {\f[CB]\-storetype\f[R] \f[I]type\f[R]}: Keystore type
870 .IP \[bu] 2
871 {\f[CB]\-providername\f[R] \f[I]name\f[R]}: Provider name
872 .IP \[bu] 2
873 {\f[CB]\-addprovider\f[R] \f[I]name\f[R] [\f[CB]\-providerarg\f[R]
874 \f[I]arg\f[R]]}: Add security provider by name (such as SunPKCS11) with
875 an optional configure argument.
876 .IP \[bu] 2
877 {\f[CB]\-providerclass\f[R] \f[I]class\f[R] [\f[CB]\-providerarg\f[R]
878 \f[I]arg\f[R]] }: Add security provider by fully qualified class name
879 with an optional configure argument.
880 .IP \[bu] 2
881 {\f[CB]\-providerpath\f[R] \f[I]list\f[R]}: Provider classpath
882 .IP \[bu] 2
883 {\f[CB]\-v\f[R]}: Verbose output
884 .IP \[bu] 2
885 {\f[CB]\-protected\f[R]}: Password provided through a protected mechanism
886 .PP
887 Use the \f[CB]\-exportcert\f[R] command to read a certificate from the
888 keystore that is associated with \f[CB]\-alias\f[R] \f[I]alias\f[R] and
889 store it in the \f[CB]\-file\f[R] \f[I]file\f[R].
890 When a file is not specified, the certificate is output to
891 \f[CB]stdout\f[R].
892 .PP
893 By default, the certificate is output in binary encoding.
894 If the \f[CB]\-rfc\f[R] option is specified, then the output in the
895 printable encoding format defined by the Internet RFC 1421 Certificate
896 Encoding Standard.
897 .PP
898 If \f[CB]\-alias\f[R] refers to a trusted certificate, then that
899 certificate is output.
900 Otherwise, \f[CB]\-alias\f[R] refers to a key entry with an associated
901 certificate chain.
902 In that case, the first certificate in the chain is returned.
903 This certificate authenticates the public key of the entity addressed by
904 \f[CB]\-alias\f[R].
905 .RE
906 .SH COMMANDS FOR DISPLAYING DATA
907 .TP
908 .B \f[CB]\-list\f[R]
909 The following are the available options for the \f[CB]\-list\f[R] command:
910 .RS
911 .IP \[bu] 2
912 {\f[CB]\-rfc\f[R]}: Output in RFC style
913 .IP \[bu] 2
914 {\f[CB]\-alias\f[R] \f[I]alias\f[R]}: Alias name of the entry to process
915 .IP \[bu] 2
916 {\f[CB]\-keystore\f[R] \f[I]keystore\f[R]}: Keystore name
917 .IP \[bu] 2
918 {\f[CB]\-cacerts\f[R]}: Access the cacerts keystore
919 .IP \[bu] 2
920 [\f[CB]\-storepass\f[R] \f[I]arg\f[R]]: Keystore password
921 .IP \[bu] 2
922 {\f[CB]\-storetype\f[R] \f[I]type\f[R]}: Keystore type
923 .IP \[bu] 2
924 {\f[CB]\-providername\f[R] \f[I]name\f[R]}: Provider name
925 .IP \[bu] 2
926 {\f[CB]\-addprovider\f[R] \f[I]name\f[R] [\f[CB]\-providerarg\f[R]
927 \f[I]arg\f[R]]}: Add security provider by name (such as SunPKCS11) with
928 an optional configure argument.
929 .IP \[bu] 2
930 {\f[CB]\-providerclass\f[R] \f[I]class\f[R] [\f[CB]\-providerarg\f[R]
931 \f[I]arg\f[R]] }: Add security provider by fully qualified class name
932 with an optional configure argument.
933 .IP \[bu] 2
934 {\f[CB]\-providerpath\f[R] \f[I]list\f[R]}: Provider classpath
935 .IP \[bu] 2
936 {\f[CB]\-v\f[R]}: Verbose output
937 .IP \[bu] 2
938 {\f[CB]\-protected\f[R]}: Password provided through a protected mechanism
939 .PP
940 Use the \f[CB]\-list\f[R] command to print the contents of the keystore
941 entry identified by \f[CB]\-alias\f[R] to \f[CB]stdout\f[R].
942 If \f[CB]\-alias\f[R] \f[I]alias\f[R] is not specified, then the contents
943 of the entire keystore are printed.
944 .PP
945 By default, this command prints the SHA\-256 fingerprint of a
946 certificate.
947 If the \f[CB]\-v\f[R] option is specified, then the certificate is printed
948 in human\-readable format, with additional information such as the
949 owner, issuer, serial number, and any extensions.
950 If the \f[CB]\-rfc\f[R] option is specified, then the certificate contents
951 are printed by using the printable encoding format, as defined by the
952 Internet RFC 1421 Certificate Encoding Standard.
953 .PP
954 \f[B]Note:\f[R]
955 .PP
956 You can\[aq]t specify both \f[CB]\-v\f[R] and \f[CB]\-rfc\f[R] in the same
957 command.
958 Otherwise, an error is reported.
959 .RE
960 .TP
961 .B \f[CB]\-printcert\f[R]
962 The following are the available options for the \f[CB]\-printcert\f[R]
963 command:
964 .RS
965 .IP \[bu] 2
966 {\f[CB]\-rfc\f[R]}: Output in RFC style
967 .IP \[bu] 2
968 {\f[CB]\-file\f[R] \f[I]cert_file\f[R]}: Input file name
969 .IP \[bu] 2
970 {\f[CB]\-sslserver\f[R] \f[I]server\f[R][\f[CB]:\f[R]\f[I]port\f[R]]}:: Secure
971 Sockets Layer (SSL) server host and port
972 .IP \[bu] 2
973 {\f[CB]\-jarfile\f[R] \f[I]JAR_file\f[R]}: Signed \f[CB]\&.jar\f[R] file
974 .IP \[bu] 2
975 {\f[CB]\-v\f[R]}: Verbose output
976 .PP
977 Use the \f[CB]\-printcert\f[R] command to read and print the certificate
978 from \f[CB]\-file\f[R] \f[I]cert_file\f[R], the SSL server located at
979 \f[CB]\-sslserver\f[R] \f[I]server\f[R][\f[CB]:\f[R]\f[I]port\f[R]], or the
980 signed JAR file specified by \f[CB]\-jarfile\f[R] \f[I]JAR_file\f[R].
981 It prints its contents in a human\-readable format.
982 When a port is not specified, the standard HTTPS port 443 is assumed.
983 .PP
984 \f[B]Note:\f[R]
985 .PP
986 The \f[CB]\-sslserver\f[R] and \f[CB]\-file\f[R] options can\[aq]t be
987 provided in the same command.
988 Otherwise, an error is reported.
989 If you don\[aq]t specify either option, then the certificate is read
990 from \f[CB]stdin\f[R].
991 .PP
992 When\f[CB]\-rfc\f[R] is specified, the \f[CB]keytool\f[R] command prints the
993 certificate in PEM mode as defined by the Internet RFC 1421 Certificate
994 Encoding standard.
995 .PP
996 If the certificate is read from a file or \f[CB]stdin\f[R], then it might
997 be either binary encoded or in printable encoding format, as defined by
998 the RFC 1421 Certificate Encoding standard.
999 .PP
1000 If the SSL server is behind a firewall, then the
1001 \f[CB]\-J\-Dhttps.proxyHost=proxyhost\f[R] and
1002 \f[CB]\-J\-Dhttps.proxyPort=proxyport\f[R] options can be specified on the
1003 command line for proxy tunneling.
1004 .PP
1005 \f[B]Note:\f[R]
1006 .PP
1007 This option can be used independently of a keystore.
1008 .RE
1009 .TP
1010 .B \f[CB]\-printcertreq\f[R]
1011 The following are the available options for the \f[CB]\-printcertreq\f[R]
1012 command:
1013 .RS
1014 .IP \[bu] 2
1015 {\f[CB]\-file\f[R] \f[I]file\f[R]}: Input file name
1016 .IP \[bu] 2
1017 {\f[CB]\-v\f[R]}: Verbose output
1018 .PP
1019 Use the \f[CB]\-printcertreq\f[R] command to print the contents of a PKCS
1020 #10 format certificate request, which can be generated by the
1021 \f[CB]keytool\ \-certreq\f[R] command.
1022 The command reads the request from file.
1023 If there is no file, then the request is read from the standard input.
1024 .RE
1025 .TP
1026 .B \f[CB]\-printcrl\f[R]
1027 The following are the available options for the \f[CB]\-printcrl\f[R]
1028 command:
1029 .RS
1030 .IP \[bu] 2
1031 {\f[CB]\-file\ crl\f[R]}: Input file name
1032 .IP \[bu] 2
1033 {\f[CB]\-v\f[R]}: Verbose output
1034 .PP
1035 Use the \f[CB]\-printcrl\f[R] command to read the Certificate Revocation
1036 List (CRL) from \f[CB]\-file\ crl\f[R] .
1037 A CRL is a list of the digital certificates that were revoked by the CA
1038 that issued them.
1039 The CA generates the \f[CB]crl\f[R] file.
1040 .PP
1041 \f[B]Note:\f[R]
1042 .PP
1043 This option can be used independently of a keystore.
1044 .RE
1045 .SH COMMANDS FOR MANAGING THE KEYSTORE
1046 .TP
1047 .B \f[CB]\-storepasswd\f[R]
1048 The following are the available options for the \f[CB]\-storepasswd\f[R]
1049 command:
1050 .RS
1051 .IP \[bu] 2
1052 [\f[CB]\-new\f[R] \f[I]arg\f[R]]: New password
1053 .IP \[bu] 2
1054 {\f[CB]\-keystore\f[R] \f[I]keystore\f[R]}: Keystore name
1055 .IP \[bu] 2
1056 {\f[CB]\-cacerts\f[R]}: Access the cacerts keystore
1057 .IP \[bu] 2
1058 [\f[CB]\-storepass\f[R] \f[I]arg\f[R]]: Keystore password
1059 .IP \[bu] 2
1060 {\f[CB]\-storetype\f[R] \f[I]type\f[R]}: Keystore type
1061 .IP \[bu] 2
1062 {\f[CB]\-providername\f[R] \f[I]name\f[R]}: Provider name
1063 .IP \[bu] 2
1064 {\f[CB]\-addprovider\f[R] \f[I]name\f[R] [\f[CB]\-providerarg\f[R]
1065 \f[I]arg\f[R]]}: Add security provider by name (such as SunPKCS11) with
1066 an optional configure argument.
1067 .IP \[bu] 2
1068 {\f[CB]\-providerclass\f[R] \f[I]class\f[R] [\f[CB]\-providerarg\f[R]
1069 \f[I]arg\f[R]]}: Add security provider by fully qualified class name with
1070 an optional configure argument.
1071 .IP \[bu] 2
1072 {\f[CB]\-providerpath\f[R] \f[I]list\f[R]}: Provider classpath
1073 .IP \[bu] 2
1074 {\f[CB]\-v\f[R]}: Verbose output
1075 .PP
1076 Use the \f[CB]\-storepasswd\f[R] command to change the password used to
1077 protect the integrity of the keystore contents.
1078 The new password is set by \f[CB]\-new\f[R] \f[I]arg\f[R] and must contain
1079 at least six characters.
1080 .RE
1081 .TP
1082 .B \f[CB]\-keypasswd\f[R]
1083 The following are the available options for the \f[CB]\-keypasswd\f[R]
1084 command:
1085 .RS
1086 .IP \[bu] 2
1087 {\f[CB]\-alias\f[R] \f[I]alias\f[R]}: Alias name of the entry to process
1088 .IP \[bu] 2
1089 [\f[CB]\-keypass\f[R] \f[I]old_keypass\f[R]]: Key password
1090 .IP \[bu] 2
1091 [\f[CB]\-new\f[R] \f[I]new_keypass\f[R]]: New password
1092 .IP \[bu] 2
1093 {\f[CB]\-keystore\f[R] \f[I]keystore\f[R]}: Keystore name
1094 .IP \[bu] 2
1095 {\f[CB]\-storepass\f[R] \f[I]arg\f[R]}: Keystore password
1096 .IP \[bu] 2
1097 {\f[CB]\-storetype\f[R] \f[I]type\f[R]}: Keystore type
1098 .IP \[bu] 2
1099 {\f[CB]\-providername\f[R] \f[I]name\f[R]}: Provider name
1100 .IP \[bu] 2
1101 {\f[CB]\-addprovider\f[R] \f[I]name\f[R] [\f[CB]\-providerarg\f[R]
1102 \f[I]arg\f[R]]}: Add security provider by name (such as SunPKCS11) with
1103 an optional configure argument.
1104 .IP \[bu] 2
1105 {\f[CB]\-providerclass\f[R] \f[I]class\f[R] [\f[CB]\-providerarg\f[R]
1106 \f[I]arg\f[R]]}: Add security provider by fully qualified class name with
1107 an optional configure argument.
1108 .IP \[bu] 2
1109 {\f[CB]\-providerpath\f[R] \f[I]list\f[R]}: Provider classpath
1110 .IP \[bu] 2
1111 {\f[CB]\-v\f[R]}: Verbose output
1112 .PP
1113 Use the \f[CB]\-keypasswd\f[R] command to change the password (under which
1114 private/secret keys identified by \f[CB]\-alias\f[R] are protected) from
1115 \f[CB]\-keypass\f[R] \f[I]old_keypass\f[R] to \f[CB]\-new\f[R]
1116 \f[I]new_keypass\f[R].
1117 The password value must contain at least six characters.
1118 .PP
1119 If the \f[CB]\-keypass\f[R] option isn\[aq]t provided at the command line
1120 and the \f[CB]\-keypass\f[R] password is different from the keystore
1121 password (\f[CB]\-storepass\f[R] \f[I]arg\f[R]), then the user is prompted
1122 for it.
1123 .PP
1124 If the \f[CB]\-new\f[R] option isn\[aq]t provided at the command line,
1125 then the user is prompted for it.
1126 .RE
1127 .TP
1128 .B \f[CB]\-delete\f[R]
1129 The following are the available options for the \f[CB]\-delete\f[R]
1130 command:
1131 .RS
1132 .IP \[bu] 2
1133 [\f[CB]\-alias\f[R] \f[I]alias\f[R]]: Alias name of the entry to process
1134 .IP \[bu] 2
1135 {\f[CB]\-keystore\f[R] \f[I]keystore\f[R]}: Keystore name
1136 .IP \[bu] 2
1137 {\f[CB]\-cacerts\f[R]}: Access the cacerts keystore
1138 .IP \[bu] 2
1139 [\f[CB]\-storepass\f[R] \f[I]arg\f[R]]: Keystore password
1140 .IP \[bu] 2
1141 {\f[CB]\-storetype\f[R] \f[I]type\f[R]}: Keystore type
1142 .IP \[bu] 2
1143 {\f[CB]\-providername\f[R] \f[I]name\f[R]}: Provider name
1144 .IP \[bu] 2
1145 {\f[CB]\-addprovider\f[R] \f[I]name\f[R] [\f[CB]\-providerarg\f[R]
1146 \f[I]arg\f[R]]}: Add security provider by name (such as SunPKCS11) with
1147 an optional configure argument.
1148 .IP \[bu] 2
1149 {\f[CB]\-providerclass\f[R] \f[I]class\f[R] [\f[CB]\-providerarg\f[R]
1150 \f[I]arg\f[R]]}: Add security provider by fully qualified class name with
1151 an optional configure argument.
1152 .IP \[bu] 2
1153 {\f[CB]\-providerpath\f[R] \f[I]list\f[R]}: Provider classpath
1154 .IP \[bu] 2
1155 {\f[CB]\-v\f[R]}: Verbose output
1156 .IP \[bu] 2
1157 {\f[CB]\-protected\f[R]}: Password provided through a protected mechanism
1158 .PP
1159 Use the \f[CB]\-delete\f[R] command to delete the \f[CB]\-alias\f[R]
1160 \f[I]alias\f[R] entry from the keystore.
1161 When not provided at the command line, the user is prompted for the
1162 \f[CB]alias\f[R].
1163 .RE
1164 .TP
1165 .B \f[CB]\-changealias\f[R]
1166 The following are the available options for the \f[CB]\-changealias\f[R]
1167 command:
1168 .RS
1169 .IP \[bu] 2
1170 {\f[CB]\-alias\f[R] \f[I]alias\f[R]}: Alias name of the entry to process
1171 .IP \[bu] 2
1172 [\f[CB]\-destalias\f[R] \f[I]alias\f[R]]: Destination alias
1173 .IP \[bu] 2
1174 [\f[CB]\-keypass\f[R] \f[I]arg\f[R]]: Key password
1175 .IP \[bu] 2
1176 {\f[CB]\-keystore\f[R] \f[I]keystore\f[R]}: Keystore name
1177 .IP \[bu] 2
1178 {\f[CB]\-cacerts\f[R]}: Access the cacerts keystore
1179 .IP \[bu] 2
1180 [\f[CB]\-storepass\f[R] \f[I]arg\f[R]]: Keystore password
1181 .IP \[bu] 2
1182 {\f[CB]\-storetype\f[R] \f[I]type\f[R]}: Keystore type
1183 .IP \[bu] 2
1184 {\f[CB]\-providername\f[R] \f[I]name\f[R]}: Provider name
1185 .IP \[bu] 2
1186 {\f[CB]\-addprovider\f[R] \f[I]name\f[R] [\f[CB]\-providerarg\f[R]
1187 \f[I]arg\f[R]]}: Add security provider by name (such as SunPKCS11) with
1188 an optional configure argument.
1189 .IP \[bu] 2
1190 {\f[CB]\-providerclass\f[R] \f[I]class\f[R] [\f[CB]\-providerarg\f[R]
1191 \f[I]arg\f[R]]}: Add security provider by fully qualified class name with
1192 an optional configure argument.
1193 .IP \[bu] 2
1194 {\f[CB]\-providerpath\f[R] \f[I]list\f[R]}: Provider classpath
1195 .IP \[bu] 2
1196 {\f[CB]\-v\f[R]}: Verbose output
1197 .IP \[bu] 2
1198 {\f[CB]\-protected\f[R]}: Password provided through a protected mechanism
1199 .PP
1200 Use the \f[CB]\-changealias\f[R] command to move an existing keystore
1201 entry from \f[CB]\-alias\f[R] \f[I]alias\f[R] to a new \f[CB]\-destalias\f[R]
1202 \f[I]alias\f[R].
1203 If a destination alias is not provided, then the command prompts you for
1204 one.
1205 If the original entry is protected with an entry password, then the
1206 password can be supplied with the \f[CB]\-keypass\f[R] option.
1207 If a key password is not provided, then the \f[CB]\-storepass\f[R] (if
1208 provided) is attempted first.
1209 If the attempt fails, then the user is prompted for a password.
1210 .RE
1211 .SH COMMANDS FOR DISPLAYING SECURITY\-RELATED INFORMATION
1212 .TP
1213 .B \f[CB]\-showinfo\f[R]
1214 The following are the available options for the \f[CB]\-showinfo\f[R]
1215 command:
1216 .RS
1217 .IP \[bu] 2
1218 {\f[CB]\-tls\f[R]}: Displays TLS configuration information
1219 .IP \[bu] 2
1220 {\f[CB]\-v\f[R]}: Verbose output
1221 .PP
1222 Use the \f[CB]\-showinfo\f[R] command to display various security\-related
1223 information.
1224 The \f[CB]\-tls\f[R] option displays TLS configurations, such as the list
1225 of enabled protocols and cipher suites.
1226 .RE
1227 .SH COMMANDS FOR DISPLAYING HELP INFORMATION
1228 .PP
1229 You can use \f[CB]\-\-help\f[R] to display a list of \f[CB]keytool\f[R]
1230 commands or to display help information about a specific
1231 \f[CB]keytool\f[R] command.
1232 .IP \[bu] 2
1233 To display a list of \f[CB]keytool\f[R] commands, enter:
1234 .RS 2
1235 .RS
1236 .PP
1237 \f[CB]keytool\ \-\-help\f[R]
1238 .RE
1239 .RE
1240 .IP \[bu] 2
1241 To display help information about a specific \f[CB]keytool\f[R] command,
1242 enter:
1243 .RS 2
1244 .RS
1245 .PP
1246 \f[CB]keytool\ \-<command>\ \-\-help\f[R]
1247 .RE
1248 .RE
1249 .SH COMMON COMMAND OPTIONS
1250 .PP
1251 The \f[CB]\-v\f[R] option can appear for all commands except
1252 \f[CB]\-\-help\f[R].
1253 When the \f[CB]\-v\f[R] option appears, it signifies verbose mode, which
1254 means that more information is provided in the output.
1255 .PP
1256 The \f[CB]\-J\f[R]\f[I]option\f[R] argument can appear for any command.
1257 When the \f[CB]\-J\f[R]\f[I]option\f[R] is used, the specified
1258 \f[I]option\f[R] string is passed directly to the Java interpreter.
1259 This option doesn\[aq]t contain any spaces.
1260 It\[aq]s useful for adjusting the execution environment or memory usage.
1261 For a list of possible interpreter options, enter \f[CB]java\ \-h\f[R] or
1262 \f[CB]java\ \-X\f[R] at the command line.
1263 .PP
1264 These options can appear for all commands operating on a keystore:
1265 .TP
1266 .B \f[CB]\-storetype\f[R] \f[I]storetype\f[R]
1267 This qualifier specifies the type of keystore to be instantiated.
1268 .RS
1269 .RE
1270 .TP
1271 .B \f[CB]\-keystore\f[R] \f[I]keystore\f[R]
1272 The keystore location.
1273 .RS
1274 .PP
1275 If the JKS \f[CB]storetype\f[R] is used and a keystore file doesn\[aq]t
1276 yet exist, then certain \f[CB]keytool\f[R] commands can result in a new
1277 keystore file being created.
1278 For example, if \f[CB]keytool\ \-genkeypair\f[R] is called and the
1279 \f[CB]\-keystore\f[R] option isn\[aq]t specified, the default keystore
1280 file named \f[CB]\&.keystore\f[R] is created in the user\[aq]s home
1281 directory if it doesn\[aq]t already exist.
1282 Similarly, if the \f[CB]\-keystore\ ks_file\f[R] option is specified but
1283 \f[CB]ks_file\f[R] doesn\[aq]t exist, then it is created.
1284 For more information on the JKS \f[CB]storetype\f[R], see the
1285 \f[B]KeyStore Implementation\f[R] section in \f[B]KeyStore aliases\f[R].
1286 .PP
1287 Note that the input stream from the \f[CB]\-keystore\f[R] option is passed
1288 to the \f[CB]KeyStore.load\f[R] method.
1289 If \f[CB]NONE\f[R] is specified as the URL, then a null stream is passed
1290 to the \f[CB]KeyStore.load\f[R] method.
1291 \f[CB]NONE\f[R] should be specified if the keystore isn\[aq]t file\-based.
1292 For example, when the keystore resides on a hardware token device.
1293 .RE
1294 .TP
1295 .B \f[CB]\-cacerts\f[R] \f[I]cacerts\f[R]
1296 Operates on the \f[I]cacerts\f[R] keystore .
1297 This option is equivalent to \f[CB]\-keystore\f[R]
1298 \f[I]path_to_cacerts\f[R] \f[CB]\-storetype\f[R] \f[I]type_of_cacerts\f[R].
1299 An error is reported if the \f[CB]\-keystore\f[R] or \f[CB]\-storetype\f[R]
1300 option is used with the \f[CB]\-cacerts\f[R] option.
1301 .RS
1302 .RE
1303 .TP
1304 .B \f[CB]\-storepass\f[R] [\f[CB]:env\f[R] | \f[CB]:file\f[R] ] \f[I]argument\f[R]
1305 The password that is used to protect the integrity of the keystore.
1306 .RS
1307 .PP
1308 If the modifier \f[CB]env\f[R] or \f[CB]file\f[R] isn\[aq]t specified, then
1309 the password has the value \f[I]argument\f[R], which must contain at
1310 least six characters.
1311 Otherwise, the password is retrieved as follows:
1312 .IP \[bu] 2
1313 \f[CB]env\f[R]: Retrieve the password from the environment variable named
1314 \f[I]argument\f[R].
1315 .IP \[bu] 2
1316 \f[CB]file\f[R]: Retrieve the password from the file named
1317 \f[I]argument\f[R].
1318 .PP
1319 \f[B]Note:\f[R] All other options that require passwords, such as
1320 \f[CB]\-keypass\f[R], \f[CB]\-srckeypass\f[R], \f[CB]\-destkeypass\f[R],
1321 \f[CB]\-srcstorepass\f[R], and \f[CB]\-deststorepass\f[R], accept the
1322 \f[CB]env\f[R] and \f[CB]file\f[R] modifiers.
1323 Remember to separate the password option and the modifier with a colon
1324 (:).
1325 .PP
1326 The password must be provided to all commands that access the keystore
1327 contents.
1328 For such commands, when the \f[CB]\-storepass\f[R] option isn\[aq]t
1329 provided at the command line, the user is prompted for it.
1330 .PP
1331 When retrieving information from the keystore, the password is optional.
1332 If a password is not specified, then the integrity of the retrieved
1333 information can\[aq]t be verified and a warning is displayed.
1334 .RE
1335 .TP
1336 .B \f[CB]\-providername\f[R] \f[I]name\f[R]
1337 Used to identify a cryptographic service provider\[aq]s name when listed
1338 in the security properties file.
1339 .RS
1340 .RE
1341 .TP
1342 .B \f[CB]\-addprovider\f[R] \f[I]name\f[R]
1343 Used to add a security provider by name (such as SunPKCS11) .
1344 .RS
1345 .RE
1346 .TP
1347 .B \f[CB]\-providerclass\f[R] \f[I]class\f[R]
1348 Used to specify the name of a cryptographic service provider\[aq]s
1349 master class file when the service provider isn\[aq]t listed in the
1350 security properties file.
1351 .RS
1352 .RE
1353 .TP
1354 .B \f[CB]\-providerpath\f[R] \f[I]list\f[R]
1355 Used to specify the provider classpath.
1356 .RS
1357 .RE
1358 .TP
1359 .B \f[CB]\-providerarg\f[R] \f[I]arg\f[R]
1360 Used with the \f[CB]\-addprovider\f[R] or \f[CB]\-providerclass\f[R] option
1361 to represent an optional string input argument for the constructor of
1362 \f[I]class\f[R] name.
1363 .RS
1364 .RE
1365 .TP
1366 .B \f[CB]\-protected=true\f[R]|\f[CB]false\f[R]
1367 Specify this value as \f[CB]true\f[R] when a password must be specified by
1368 way of a protected authentication path, such as a dedicated PIN reader.
1369 Because there are two keystores involved in the
1370 \f[CB]\-importkeystore\f[R] command, the following two options,
1371 \f[CB]\-srcprotected\f[R] and \f[CB]\-destprotected\f[R], are provided for
1372 the source keystore and the destination keystore respectively.
1373 .RS
1374 .RE
1375 .TP
1376 .B \f[CB]\-ext\f[R] {\f[I]name\f[R]{\f[CB]:critical\f[R]} {\f[CB]=\f[R]\f[I]value\f[R]}}
1377 Denotes an X.509 certificate extension.
1378 The option can be used in \f[CB]\-genkeypair\f[R] and \f[CB]\-gencert\f[R]
1379 to embed extensions into the generated certificate, or in
1380 \f[CB]\-certreq\f[R] to show what extensions are requested in the
1381 certificate request.
1382 The option can appear multiple times.
1383 The \f[I]name\f[R] argument can be a supported extension name (see
1384 \f[B]Supported Named Extensions\f[R]) or an arbitrary OID number.
1385 The \f[I]value\f[R] argument, when provided, denotes the argument for the
1386 extension.
1387 When \f[I]value\f[R] is omitted, the default value of the extension or
1388 the extension itself requires no argument.
1389 The \f[CB]:critical\f[R] modifier, when provided, means the
1390 extension\[aq]s \f[CB]isCritical\f[R] attribute is \f[CB]true\f[R];
1391 otherwise, it is \f[CB]false\f[R].
1392 You can use \f[CB]:c\f[R] in place of \f[CB]:critical\f[R].
1393 .RS
1394 .RE
1395 .TP
1396 .B \f[CB]\-conf\f[R] \f[I]file\f[R]
1397 Specifies a pre\-configured options file.
1398 .RS
1399 .RE
1400 .SH PRE\-CONFIGURED OPTIONS FILE
1401 .PP
1402 A pre\-configured options file is a Java properties file that can be
1403 specified with the \f[CB]\-conf\f[R] option.
1404 Each property represents the default option(s) for a keytool command
1405 using "keytool.\f[I]command_name\f[R]" as the property name.
1406 A special property named "keytool.all" represents the default option(s)
1407 applied to all commands.
1408 A property value can include \f[CB]${prop}\f[R] which will be expanded to
1409 the system property associated with it.
1410 If an option value includes white spaces inside, it should be surrounded
1411 by quotation marks (" or \[aq]).
1412 All property names must be in lower case.
1413 .PP
1414 When \f[CB]keytool\f[R] is launched with a pre\-configured options file,
1415 the value for "keytool.all" (if it exists) is prepended to the
1416 \f[CB]keytool\f[R] command line first, with the value for the command name
1417 (if it exists) comes next, and the existing options on the command line
1418 at last.
1419 For a single\-valued option, this allows the property for a specific
1420 command to override the "keytool.all" value, and the value specified on
1421 the command line to override both.
1422 For multiple\-valued options, all of them will be used by
1423 \f[CB]keytool\f[R].
1424 .PP
1425 For example, given the following file named \f[CB]preconfig\f[R]:
1426 .IP
1427 .nf
1428 \f[CB]
1429 \ \ \ \ #\ A\ tiny\ pre\-configured\ options\ file
1430 \ \ \ \ keytool.all\ =\ \-keystore\ ${user.home}/ks
1431 \ \ \ \ keytool.list\ =\ \-v
1432 \ \ \ \ keytool.genkeypair\ =\ \-keyalg\ rsa
1433 \f[R]
1434 .fi
1435 .PP
1436 \f[CB]keytool\ \-conf\ preconfig\ \-list\f[R] is identical to
1437 .RS
1438 .PP
1439 \f[CB]keytool\ \-keystore\ ~/ks\ \-v\ \-list\f[R]
1440 .RE
1441 .PP
1442 \f[CB]keytool\ \-conf\ preconfig\ \-genkeypair\ \-alias\ me\f[R] is
1443 identical to
1444 .RS
1445 .PP
1446 \f[CB]keytool\ \-keystore\ ~/ks\ \-keyalg\ rsa\ \-genkeypair\ \-alias\ me\f[R]
1447 .RE
1448 .PP
1449 \f[CB]keytool\ \-conf\ preconfig\ \-genkeypair\ \-alias\ you\ \-keyalg\ ec\f[R]
1450 is identical to
1451 .RS
1452 .PP
1453 \f[CB]keytool\ \-keystore\ ~/ks\ \-keyalg\ rsa\ \-genkeypair\ \-alias\ you\ \-keyalg\ ec\f[R]
1454 .RE
1455 .PP
1456 which is equivalent to
1457 .RS
1458 .PP
1459 \f[CB]keytool\ \-keystore\ ~/ks\ \-genkeypair\ \-alias\ you\ \-keyalg\ ec\f[R]
1460 .RE
1461 .PP
1462 because \f[CB]\-keyalg\f[R] is a single\-valued option and the \f[CB]ec\f[R]
1463 value specified on the command line overrides the preconfigured options
1464 file.
1465 .SH EXAMPLES OF OPTION VALUES
1466 .PP
1467 The following examples show the defaults for various option values:
1468 .IP
1469 .nf
1470 \f[CB]
1471 \-alias\ "mykey"
1472
1473 \-keysize
1474 \ \ \ \ 2048\ (when\ using\ \-genkeypair\ and\ \-keyalg\ is\ "RSA")
1475 \ \ \ \ 2048\ (when\ using\ \-genkeypair\ and\ \-keyalg\ is\ "DSA")
1476 \ \ \ \ 256\ (when\ using\ \-genkeypair\ and\ \-keyalg\ is\ "EC")
1477 \ \ \ \ 56\ (when\ using\ \-genseckey\ and\ \-keyalg\ is\ "DES")
1478 \ \ \ \ 168\ (when\ using\ \-genseckey\ and\ \-keyalg\ is\ "DESede")
1479
1480 \-validity\ 90
1481
1482 \-keystore\ <the\ file\ named\ .keystore\ in\ the\ user\[aq]s\ home\ directory>
1483
1484 \-destkeystore\ <the\ file\ named\ .keystore\ in\ the\ user\[aq]s\ home\ directory>
1485
1486 \-storetype\ <the\ value\ of\ the\ "keystore.type"\ property\ in\ the
1487 \ \ \ \ security\ properties\ file,\ which\ is\ returned\ by\ the\ static
1488 \ \ \ \ getDefaultType\ method\ in\ java.security.KeyStore>
1489
1490 \-file
1491 \ \ \ \ stdin\ (if\ reading)
1492 \ \ \ \ stdout\ (if\ writing)
1493
1494 \-protected\ false
1495 \f[R]
1496 .fi
1497 .PP
1498 When generating a certificate or a certificate request, the default
1499 signature algorithm (\f[CB]\-sigalg\f[R] option) is derived from the
1500 algorithm of the underlying private key to provide an appropriate level
1501 of security strength as follows:
1502 .PP
1503 .TS
1504 tab(@);
1505 l l l.
1506 T{
1507 keyalg
1508 T}@T{
1509 keysize
1510 T}@T{
1511 default sigalg
1512 T}
1513 _
1514 T{
1515 DSA
1516 T}@T{
1517 any size
1518 T}@T{
1519 SHA256withDSA
1520 T}
1521 T{
1522 RSA
1523 T}@T{
1524 <= 3072
1525 T}@T{
1526 SHA256withRSA
1527 T}
1528 T{
1529 T}@T{
1530 <= 7680
1531 T}@T{
1532 SHA384withRSA
1533 T}
1534 T{
1535 T}@T{
1536 > 7680
1537 T}@T{
1538 SHA512withRSA
1539 T}
1540 T{
1541 EC
1542 T}@T{
1543 < 384
1544 T}@T{
1545 SHA256withECDSA
1546 T}
1547 T{
1548 T}@T{
1549 < 512
1550 T}@T{
1551 SHA384withECDSA
1552 T}
1553 T{
1554 T}@T{
1555 = 512
1556 T}@T{
1557 SHA512withECDSA
1558 T}
1559 .TE
1560 .PP
1561 \f[B]Note:\f[R]
1562 .PP
1563 To improve out of the box security, default key size and signature
1564 algorithm names are periodically updated to stronger values with each
1565 release of the JDK.
1566 If interoperability with older releases of the JDK is important, make
1567 sure that the defaults are supported by those releases.
1568 Alternatively, you can use the \f[CB]\-keysize\f[R] or \f[CB]\-sigalg\f[R]
1569 options to override the default values at your own risk.
1570 .SH SUPPORTED NAMED EXTENSIONS
1571 .PP
1572 The \f[CB]keytool\f[R] command supports these named extensions.
1573 The names aren\[aq]t case\-sensitive.
1574 .TP
1575 .B \f[CB]BC\f[R] or \f[CB]BasicContraints\f[R]
1576 Values:
1577 .RS
1578 .PP
1579 The full form is
1580 \f[CB]ca:\f[R]{\f[CB]true\f[R]|\f[CB]false\f[R]}[\f[CB],pathlen:\f[R]\f[I]len\f[R]]
1581 or \f[I]len\f[R], which is short for
1582 \f[CB]ca:true,pathlen:\f[R]\f[I]len\f[R].
1583 .PP
1584 When \f[I]len\f[R] is omitted, the resulting value is \f[CB]ca:true\f[R].
1585 .RE
1586 .TP
1587 .B \f[CB]KU\f[R] or \f[CB]KeyUsage\f[R]
1588 Values:
1589 .RS
1590 .PP
1591 \f[I]usage\f[R](\f[CB],\f[R] \f[I]usage\f[R])*
1592 .PP
1593 \f[I]usage\f[R] can be one of the following:
1594 .IP \[bu] 2
1595 \f[CB]digitalSignature\f[R]
1596 .IP \[bu] 2
1597 \f[CB]nonRepudiation\f[R] (\f[CB]contentCommitment\f[R])
1598 .IP \[bu] 2
1599 \f[CB]keyEncipherment\f[R]
1600 .IP \[bu] 2
1601 \f[CB]dataEncipherment\f[R]
1602 .IP \[bu] 2
1603 \f[CB]keyAgreement\f[R]
1604 .IP \[bu] 2
1605 \f[CB]keyCertSign\f[R]
1606 .IP \[bu] 2
1607 \f[CB]cRLSign\f[R]
1608 .IP \[bu] 2
1609 \f[CB]encipherOnly\f[R]
1610 .IP \[bu] 2
1611 \f[CB]decipherOnly\f[R]
1612 .PP
1613 Provided there is no ambiguity, the \f[I]usage\f[R] argument can be
1614 abbreviated with the first few letters (such as \f[CB]dig\f[R] for
1615 \f[CB]digitalSignature\f[R]) or in camel\-case style (such as \f[CB]dS\f[R]
1616 for \f[CB]digitalSignature\f[R] or \f[CB]cRLS\f[R] for \f[CB]cRLSign\f[R]).
1617 The \f[I]usage\f[R] values are case\-sensitive.
1618 .RE
1619 .TP
1620 .B \f[CB]EKU\f[R] or \f[CB]ExtendedKeyUsage\f[R]
1621 Values:
1622 .RS
1623 .PP
1624 \f[I]usage\f[R](\f[CB],\f[R] \f[I]usage\f[R])*
1625 .PP
1626 \f[I]usage\f[R] can be one of the following:
1627 .IP \[bu] 2
1628 \f[CB]anyExtendedKeyUsage\f[R]
1629 .IP \[bu] 2
1630 \f[CB]serverAuth\f[R]
1631 .IP \[bu] 2
1632 \f[CB]clientAuth\f[R]
1633 .IP \[bu] 2
1634 \f[CB]codeSigning\f[R]
1635 .IP \[bu] 2
1636 \f[CB]emailProtection\f[R]
1637 .IP \[bu] 2
1638 \f[CB]timeStamping\f[R]
1639 .IP \[bu] 2
1640 \f[CB]OCSPSigning\f[R]
1641 .IP \[bu] 2
1642 Any OID string
1643 .PP
1644 Provided there is no ambiguity, the \f[I]usage\f[R] argument can be
1645 abbreviated with the first few letters or in camel\-case style.
1646 The \f[I]usage\f[R] values are case\-sensitive.
1647 .RE
1648 .TP
1649 .B \f[CB]SAN\f[R] or \f[CB]SubjectAlternativeName\f[R]
1650 Values:
1651 .RS
1652 .PP
1653 \f[I]type\f[R]\f[CB]:\f[R]\f[I]value\f[R](\f[CB],\f[R]
1654 \f[I]type\f[R]\f[CB]:\f[R]\f[I]value\f[R])*
1655 .PP
1656 \f[I]type\f[R] can be one of the following:
1657 .IP \[bu] 2
1658 \f[CB]EMAIL\f[R]
1659 .IP \[bu] 2
1660 \f[CB]URI\f[R]
1661 .IP \[bu] 2
1662 \f[CB]DNS\f[R]
1663 .IP \[bu] 2
1664 \f[CB]IP\f[R]
1665 .IP \[bu] 2
1666 \f[CB]OID\f[R]
1667 .PP
1668 The \f[I]value\f[R] argument is the string format value for the
1669 \f[I]type\f[R].
1670 .RE
1671 .TP
1672 .B \f[CB]IAN\f[R] or \f[CB]IssuerAlternativeName\f[R]
1673 Values:
1674 .RS
1675 .PP
1676 Same as \f[CB]SAN\f[R] or \f[CB]SubjectAlternativeName\f[R].
1677 .RE
1678 .TP
1679 .B \f[CB]SIA\f[R] or \f[CB]SubjectInfoAccess\f[R]
1680 Values:
1681 .RS
1682 .PP
1683 \f[I]method\f[R]\f[CB]:\f[R]\f[I]location\-type\f[R]\f[CB]:\f[R]\f[I]location\-value\f[R](\f[CB],\f[R]
1684 \f[I]method\f[R]\f[CB]:\f[R]\f[I]location\-type\f[R]\f[CB]:\f[R]\f[I]location\-value\f[R])*
1685 .PP
1686 \f[I]method\f[R] can be one of the following:
1687 .IP \[bu] 2
1688 \f[CB]timeStamping\f[R]
1689 .IP \[bu] 2
1690 \f[CB]caRepository\f[R]
1691 .IP \[bu] 2
1692 Any OID
1693 .PP
1694 The \f[I]location\-type\f[R] and \f[I]location\-value\f[R] arguments can
1695 be any \f[I]type\f[R]\f[CB]:\f[R]\f[I]value\f[R] supported by the
1696 \f[CB]SubjectAlternativeName\f[R] extension.
1697 .RE
1698 .TP
1699 .B \f[CB]AIA\f[R] or \f[CB]AuthorityInfoAccess\f[R]
1700 Values:
1701 .RS
1702 .PP
1703 Same as \f[CB]SIA\f[R] or \f[CB]SubjectInfoAccess\f[R].
1704 .PP
1705 The \f[I]method\f[R] argument can be one of the following:
1706 .IP \[bu] 2
1707 \f[CB]ocsp\f[R]
1708 .IP \[bu] 2
1709 \f[CB]caIssuers\f[R]
1710 .IP \[bu] 2
1711 Any OID
1712 .RE
1713 .PP
1714 When \f[I]name\f[R] is OID, the value is the hexadecimal dumped Definite
1715 Encoding Rules (DER) encoding of the \f[CB]extnValue\f[R] for the
1716 extension excluding the OCTET STRING type and length bytes.
1717 Other than standard hexadecimal numbers (0\-9, a\-f, A\-F), any extra
1718 characters are ignored in the HEX string.
1719 Therefore, both 01:02:03:04 and 01020304 are accepted as identical
1720 values.
1721 When there is no value, the extension has an empty value field.
1722 .PP
1723 A special name \f[CB]honored\f[R], used only in \f[CB]\-gencert\f[R],
1724 denotes how the extensions included in the certificate request should be
1725 honored.
1726 The value for this name is a comma\-separated list of \f[CB]all\f[R] (all
1727 requested extensions are honored),
1728 \f[I]name\f[R]{\f[CB]:\f[R][\f[CB]critical\f[R]|\f[CB]non\-critical\f[R]]} (the
1729 named extension is honored, but it uses a different \f[CB]isCritical\f[R]
1730 attribute), and \f[CB]\-name\f[R] (used with \f[CB]all\f[R], denotes an
1731 exception).
1732 Requested extensions aren\[aq]t honored by default.
1733 .PP
1734 If, besides the\f[CB]\-ext\ honored\f[R] option, another named or OID
1735 \f[CB]\-ext\f[R] option is provided, this extension is added to those
1736 already honored.
1737 However, if this name (or OID) also appears in the honored value, then
1738 its value and criticality override that in the request.
1739 If an extension of the same type is provided multiple times through
1740 either a name or an OID, only the last extension is used.
1741 .PP
1742 The \f[CB]subjectKeyIdentifier\f[R] extension is always created.
1743 For non\-self\-signed certificates, the \f[CB]authorityKeyIdentifier\f[R]
1744 is created.
1745 .PP
1746 \f[B]CAUTION:\f[R]
1747 .PP
1748 Users should be aware that some combinations of extensions (and other
1749 certificate fields) may not conform to the Internet standard.
1750 See \f[B]Certificate Conformance Warning\f[R].
1751 .SH EXAMPLES OF TASKS IN CREATING A KEYSTORE
1752 .PP
1753 The following examples describe the sequence actions in creating a
1754 keystore for managing public/private key pairs and certificates from
1755 trusted entities.
1756 .IP \[bu] 2
1757 \f[B]Generating the Key Pair\f[R]
1758 .IP \[bu] 2
1759 \f[B]Requesting a Signed Certificate from a CA\f[R]
1760 .IP \[bu] 2
1761 \f[B]Importing a Certificate for the CA\f[R]
1762 .IP \[bu] 2
1763 \f[B]Importing the Certificate Reply from the CA\f[R]
1764 .IP \[bu] 2
1765 \f[B]Exporting a Certificate That Authenticates the Public Key\f[R]
1766 .IP \[bu] 2
1767 \f[B]Importing the Keystore\f[R]
1768 .IP \[bu] 2
1769 \f[B]Generating Certificates for an SSL Server\f[R]
1770 .SH GENERATING THE KEY PAIR
1771 .PP
1772 Create a keystore and then generate the key pair.
1773 .PP
1774 You can enter the command as a single line such as the following:
1775 .RS
1776 .PP
1777 \f[CB]keytool\ \-genkeypair\ \-dname\ "cn=myname,\ ou=mygroup,\ o=mycompany,\ c=mycountry"\ \-alias\ business\ \-keyalg\ rsa\ \-keypass\f[R]
1778 \f[I]password\f[R]
1779 \f[CB]\-keystore\ /working/mykeystore\ \-storepass\ password\ \-validity\ 180\f[R]
1780 .RE
1781 .PP
1782 The command creates the keystore named \f[CB]mykeystore\f[R] in the
1783 working directory (provided it doesn\[aq]t already exist), and assigns
1784 it the password specified by \f[CB]\-keypass\f[R].
1785 It generates a public/private key pair for the entity whose
1786 distinguished name is \f[CB]myname\f[R], \f[CB]mygroup\f[R],
1787 \f[CB]mycompany\f[R], and a two\-letter country code of
1788 \f[CB]mycountry\f[R].
1789 It uses the RSA key generation algorithm to create the keys; both are
1790 2048 bits
1791 .PP
1792 The command uses the default SHA256withRSA signature algorithm to create
1793 a self\-signed certificate that includes the public key and the
1794 distinguished name information.
1795 The certificate is valid for 180 days, and is associated with the
1796 private key in a keystore entry referred to by
1797 \f[CB]\-alias\ business\f[R].
1798 The private key is assigned the password specified by
1799 \f[CB]\-keypass\f[R].
1800 .PP
1801 The command is significantly shorter when the option defaults are
1802 accepted.
1803 In this case, only \f[CB]\-keyalg\f[R] is required, and the defaults are
1804 used for unspecified options that have default values.
1805 You are prompted for any required values.
1806 You could have the following:
1807 .RS
1808 .PP
1809 \f[CB]keytool\ \-genkeypair\ \-keyalg\ rsa\f[R]
1810 .RE
1811 .PP
1812 In this case, a keystore entry with the alias \f[CB]mykey\f[R] is created,
1813 with a newly generated key pair and a certificate that is valid for 90
1814 days.
1815 This entry is placed in your home directory in a keystore named
1816 \f[CB]\&.keystore\f[R] .
1817 \f[CB]\&.keystore\f[R] is created if it doesn\[aq]t already exist.
1818 You are prompted for the distinguished name information, the keystore
1819 password, and the private key password.
1820 .PP
1821 \f[B]Note:\f[R]
1822 .PP
1823 The rest of the examples assume that you responded to the prompts with
1824 values equal to those specified in the first \f[CB]\-genkeypair\f[R]
1825 command.
1826 For example, a distinguished name of
1827 \f[CB]cn=\f[R]\f[I]myname\f[R]\f[CB],\ ou=\f[R]\f[I]mygroup\f[R]\f[CB],\ o=\f[R]\f[I]mycompany\f[R]\f[CB],\ c=\f[R]\f[I]mycountry\f[R]).
1828 .SH REQUESTING A SIGNED CERTIFICATE FROM A CA
1829 .PP
1830 \f[B]Note:\f[R]
1831 .PP
1832 Generating the key pair created a self\-signed certificate; however, a
1833 certificate is more likely to be trusted by others when it is signed by
1834 a CA.
1835 .PP
1836 To get a CA signature, complete the following process:
1837 .IP "1." 3
1838 Generate a CSR:
1839 .RS 4
1840 .RS
1841 .PP
1842 \f[CB]keytool\ \-certreq\ \-file\ myname.csr\f[R]
1843 .RE
1844 .PP
1845 This creates a CSR for the entity identified by the default alias
1846 \f[CB]mykey\f[R] and puts the request in the file named
1847 \f[CB]myname.csr\f[R].
1848 .RE
1849 .IP "2." 3
1850 Submit \f[CB]myname.csr\f[R] to a CA, such as DigiCert.
1851 .PP
1852 The CA authenticates you, the requestor (usually offline), and returns a
1853 certificate, signed by them, authenticating your public key.
1854 In some cases, the CA returns a chain of certificates, each one
1855 authenticating the public key of the signer of the previous certificate
1856 in the chain.
1857 .SH IMPORTING A CERTIFICATE FOR THE CA
1858 .PP
1859 To import a certificate for the CA, complete the following process:
1860 .IP "1." 3
1861 Before you import the certificate reply from a CA, you need one or more
1862 trusted certificates either in your keystore or in the \f[CB]cacerts\f[R]
1863 keystore file.
1864 See \f[CB]\-importcert\f[R] in \f[B]Commands\f[R].
1865 .RS 4
1866 .IP \[bu] 2
1867 If the certificate reply is a certificate chain, then you need the top
1868 certificate of the chain.
1869 The root CA certificate that authenticates the public key of the CA.
1870 .IP \[bu] 2
1871 If the certificate reply is a single certificate, then you need a
1872 certificate for the issuing CA (the one that signed it).
1873 If that certificate isn\[aq]t self\-signed, then you need a certificate
1874 for its signer, and so on, up to a self\-signed root CA certificate.
1875 .PP
1876 The \f[CB]cacerts\f[R] keystore ships with a set of root certificates
1877 issued by the CAs of \f[B]the Oracle Java Root Certificate program\f[R]
1878 [http://www.oracle.com/technetwork/java/javase/javasecarootcertsprogram\-1876540.html].
1879 If you request a signed certificate from a CA, and a certificate
1880 authenticating that CA\[aq]s public key hasn\[aq]t been added to
1881 \f[CB]cacerts\f[R], then you must import a certificate from that CA as a
1882 trusted certificate.
1883 .PP
1884 A certificate from a CA is usually self\-signed or signed by another CA.
1885 If it is signed by another CA, you need a certificate that authenticates
1886 that CA\[aq]s public key.
1887 .PP
1888 For example, you have obtained a \f[I]X\f[R]\f[CB]\&.cer\f[R] file from a
1889 company that is a CA and the file is supposed to be a self\-signed
1890 certificate that authenticates that CA\[aq]s public key.
1891 Before you import it as a trusted certificate, you should ensure that
1892 the certificate is valid by:
1893 .IP "1." 3
1894 Viewing it with the \f[CB]keytool\ \-printcert\f[R] command or the
1895 \f[CB]keytool\ \-importcert\f[R] command without using the
1896 \f[CB]\-noprompt\f[R] option.
1897 Make sure that the displayed certificate fingerprints match the expected
1898 fingerprints.
1899 .IP "2." 3
1900 Calling the person who sent the certificate, and comparing the
1901 fingerprints that you see with the ones that they show or that a secure
1902 public key repository shows.
1903 .PP
1904 Only when the fingerprints are equal is it assured that the certificate
1905 wasn\[aq]t replaced in transit with somebody else\[aq]s certificate
1906 (such as an attacker\[aq]s certificate).
1907 If such an attack takes place, and you didn\[aq]t check the certificate
1908 before you imported it, then you would be trusting anything that the
1909 attacker signed.
1910 .RE
1911 .IP "2." 3
1912 Replace the self\-signed certificate with a certificate chain, where
1913 each certificate in the chain authenticates the public key of the signer
1914 of the previous certificate in the chain, up to a root CA.
1915 .RS 4
1916 .PP
1917 If you trust that the certificate is valid, then you can add it to your
1918 keystore by entering the following command:
1919 .RS
1920 .PP
1921 \f[CB]keytool\ \-importcert\ \-alias\f[R] \f[I]alias\f[R]
1922 \f[CB]\-file\ *X*\f[R].cer`
1923 .RE
1924 .PP
1925 This command creates a trusted certificate entry in the keystore from
1926 the data in the CA certificate file and assigns the values of the
1927 \f[I]alias\f[R] to the entry.
1928 .RE
1929 .SH IMPORTING THE CERTIFICATE REPLY FROM THE CA
1930 .PP
1931 After you import a certificate that authenticates the public key of the
1932 CA that you submitted your certificate signing request to (or there is
1933 already such a certificate in the \f[CB]cacerts\f[R] file), you can import
1934 the certificate reply and replace your self\-signed certificate with a
1935 certificate chain.
1936 .PP
1937 The certificate chain is one of the following:
1938 .IP \[bu] 2
1939 Returned by the CA when the CA reply is a chain.
1940 .IP \[bu] 2
1941 Constructed when the CA reply is a single certificate.
1942 This certificate chain is constructed by using the certificate reply and
1943 trusted certificates available either in the keystore where you import
1944 the reply or in the \f[CB]cacerts\f[R] keystore file.
1945 .PP
1946 For example, if you sent your certificate signing request to DigiCert,
1947 then you can import their reply by entering the following command:
1948 .PP
1949 \f[B]Note:\f[R]
1950 .PP
1951 In this example, the returned certificate is named
1952 \f[CB]DCmyname.cer\f[R].
1953 .RS
1954 .PP
1955 \f[CB]keytool\ \-importcert\ \-trustcacerts\ \-file\ DCmyname.cer\f[R]
1956 .RE
1957 .SH EXPORTING A CERTIFICATE THAT AUTHENTICATES THE PUBLIC KEY
1958 .PP
1959 \f[B]Note:\f[R]
1960 .PP
1961 If you used the \f[CB]jarsigner\f[R] command to sign a Java Archive (JAR)
1962 file, then clients that use the file will want to authenticate your
1963 signature.
1964 .PP
1965 One way that clients can authenticate you is by importing your public
1966 key certificate into their keystore as a trusted entry.
1967 You can then export the certificate and supply it to your clients.
1968 .PP
1969 For example:
1970 .IP "1." 3
1971 Copy your certificate to a file named \f[CB]myname.cer\f[R] by entering
1972 the following command:
1973 .RS 4
1974 .PP
1975 \f[B]Note:\f[R]
1976 .PP
1977 In this example, the entry has an alias of \f[CB]mykey\f[R].
1978 .RS
1979 .PP
1980 \f[CB]keytool\ \-exportcert\ \-alias\ mykey\ \-file\ myname.cer\f[R]
1981 .RE
1982 .RE
1983 .IP "2." 3
1984 With the certificate and the signed JAR file, a client can use the
1985 \f[CB]jarsigner\f[R] command to authenticate your signature.
1986 .SH IMPORTING THE KEYSTORE
1987 .PP
1988 Use the \f[CB]importkeystore\f[R] command to import an entire keystore
1989 into another keystore.
1990 This imports all entries from the source keystore, including keys and
1991 certificates, to the destination keystore with a single command.
1992 You can use this command to import entries from a different type of
1993 keystore.
1994 During the import, all new entries in the destination keystore will have
1995 the same alias names and protection passwords (for secret keys and
1996 private keys).
1997 If the \f[CB]keytool\f[R] command can\[aq]t recover the private keys or
1998 secret keys from the source keystore, then it prompts you for a
1999 password.
2000 If it detects alias duplication, then it asks you for a new alias, and
2001 you can specify a new alias or simply allow the \f[CB]keytool\f[R] command
2002 to overwrite the existing one.
2003 .PP
2004 For example, import entries from a typical JKS type keystore
2005 \f[CB]key.jks\f[R] into a PKCS #11 type hardware\-based keystore, by
2006 entering the following command:
2007 .RS
2008 .PP
2009 \f[CB]keytool\ \-importkeystore\ \-srckeystore\ key.jks\ \-destkeystore\ NONE\ \-srcstoretype\ JKS\ \-deststoretype\ PKCS11\ \-srcstorepass\f[R]
2010 \f[I]password\f[R] \f[CB]\-deststorepass\f[R] \f[I]password\f[R]
2011 .RE
2012 .PP
2013 The \f[CB]importkeystore\f[R] command can also be used to import a single
2014 entry from a source keystore to a destination keystore.
2015 In this case, besides the options you used in the previous example, you
2016 need to specify the alias you want to import.
2017 With the \f[CB]\-srcalias\f[R] option specified, you can also specify the
2018 destination alias name, protection password for a secret or private key,
2019 and the destination protection password you want as follows:
2020 .RS
2021 .PP
2022 \f[CB]keytool\ \-importkeystore\ \-srckeystore\ key.jks\ \-destkeystore\ NONE\ \-srcstoretype\ JKS\ \-deststoretype\ PKCS11\ \-srcstorepass\f[R]
2023 \f[I]password\f[R] \f[CB]\-deststorepass\f[R] \f[I]password\f[R]
2024 \f[CB]\-srcalias\ myprivatekey\ \-destalias\ myoldprivatekey\ \-srckeypass\f[R]
2025 \f[I]password\f[R] \f[CB]\-destkeypass\f[R] \f[I]password\f[R]
2026 \f[CB]\-noprompt\f[R]
2027 .RE
2028 .SH GENERATING CERTIFICATES FOR AN SSL SERVER
2029 .PP
2030 The following are \f[CB]keytool\f[R] commands used to generate key pairs
2031 and certificates for three entities:
2032 .IP \[bu] 2
2033 Root CA (\f[CB]root\f[R])
2034 .IP \[bu] 2
2035 Intermediate CA (\f[CB]ca\f[R])
2036 .IP \[bu] 2
2037 SSL server (\f[CB]server\f[R])
2038 .PP
2039 Ensure that you store all the certificates in the same keystore.
2040 .IP
2041 .nf
2042 \f[CB]
2043 keytool\ \-genkeypair\ \-keystore\ root.jks\ \-alias\ root\ \-ext\ bc:c\ \-keyalg\ rsa
2044 keytool\ \-genkeypair\ \-keystore\ ca.jks\ \-alias\ ca\ \-ext\ bc:c\ \-keyalg\ rsa
2045 keytool\ \-genkeypair\ \-keystore\ server.jks\ \-alias\ server\ \-keyalg\ rsa
2046
2047 keytool\ \-keystore\ root.jks\ \-alias\ root\ \-exportcert\ \-rfc\ >\ root.pem
2048
2049 keytool\ \-storepass\ password\ \-keystore\ ca.jks\ \-certreq\ \-alias\ ca\ |
2050 \ \ \ \ keytool\ \-storepass\ password\ \-keystore\ root.jks
2051 \ \ \ \ \-gencert\ \-alias\ root\ \-ext\ BC=0\ \-rfc\ >\ ca.pem
2052 keytool\ \-keystore\ ca.jks\ \-importcert\ \-alias\ ca\ \-file\ ca.pem
2053
2054 keytool\ \-storepass\ password\ \-keystore\ server.jks\ \-certreq\ \-alias\ server\ |
2055 \ \ \ \ keytool\ \-storepass\ password\ \-keystore\ ca.jks\ \-gencert\ \-alias\ ca
2056 \ \ \ \ \-ext\ ku:c=dig,kE\ \-rfc\ >\ server.pem
2057 cat\ root.pem\ ca.pem\ server.pem\ |
2058 \ \ \ \ keytool\ \-keystore\ server.jks\ \-importcert\ \-alias\ server
2059 \f[R]
2060 .fi
2061 .SH TERMS
2062 .TP
2063 .B Keystore
2064 A keystore is a storage facility for cryptographic keys and
2065 certificates.
2066 .RS
2067 .RE
2068 .TP
2069 .B Keystore entries
2070 Keystores can have different types of entries.
2071 The two most applicable entry types for the \f[CB]keytool\f[R] command
2072 include the following:
2073 .RS
2074 .PP
2075 Key entries: Each entry holds very sensitive cryptographic key
2076 information, which is stored in a protected format to prevent
2077 unauthorized access.
2078 Typically, a key stored in this type of entry is a secret key, or a
2079 private key accompanied by the certificate chain for the corresponding
2080 public key.
2081 See \f[B]Certificate Chains\f[R].
2082 The \f[CB]keytool\f[R] command can handle both types of entries, while the
2083 \f[CB]jarsigner\f[R] tool only handles the latter type of entry, that is
2084 private keys and their associated certificate chains.
2085 .PP
2086 Trusted certificate entries: Each entry contains a single public key
2087 certificate that belongs to another party.
2088 The entry is called a trusted certificate because the keystore owner
2089 trusts that the public key in the certificate belongs to the identity
2090 identified by the subject (owner) of the certificate.
2091 The issuer of the certificate vouches for this, by signing the
2092 certificate.
2093 .RE
2094 .TP
2095 .B Keystore aliases
2096 All keystore entries (key and trusted certificate entries) are accessed
2097 by way of unique aliases.
2098 .RS
2099 .PP
2100 An alias is specified when you add an entity to the keystore with the
2101 \f[CB]\-genseckey\f[R] command to generate a secret key, the
2102 \f[CB]\-genkeypair\f[R] command to generate a key pair (public and private
2103 key), or the \f[CB]\-importcert\f[R] command to add a certificate or
2104 certificate chain to the list of trusted certificates.
2105 Subsequent \f[CB]keytool\f[R] commands must use this same alias to refer
2106 to the entity.
2107 .PP
2108 For example, you can use the alias \f[CB]duke\f[R] to generate a new
2109 public/private key pair and wrap the public key into a self\-signed
2110 certificate with the following command.
2111 See \f[B]Certificate Chains\f[R].
2112 .RS
2113 .PP
2114 \f[CB]keytool\ \-genkeypair\ \-alias\ duke\ \-keyalg\ rsa\ \-keypass\f[R]
2115 \f[I]passwd\f[R]
2116 .RE
2117 .PP
2118 This example specifies an initial \f[I]passwd\f[R] required by subsequent
2119 commands to access the private key associated with the alias
2120 \f[CB]duke\f[R].
2121 If you later want to change Duke\[aq]s private key password, use a
2122 command such as the following:
2123 .RS
2124 .PP
2125 \f[CB]keytool\ \-keypasswd\ \-alias\ duke\ \-keypass\f[R] \f[I]passwd\f[R]
2126 \f[CB]\-new\f[R] \f[I]newpasswd\f[R]
2127 .RE
2128 .PP
2129 This changes the initial \f[I]passwd\f[R] to \f[I]newpasswd\f[R].
2130 A password shouldn\[aq]t be specified on a command line or in a script
2131 unless it is for testing purposes, or you are on a secure system.
2132 If you don\[aq]t specify a required password option on a command line,
2133 then you are prompted for it.
2134 .RE
2135 .TP
2136 .B Keystore implementation
2137 The \f[CB]KeyStore\f[R] class provided in the \f[CB]java.security\f[R]
2138 package supplies well\-defined interfaces to access and modify the
2139 information in a keystore.
2140 It is possible for there to be multiple different concrete
2141 implementations, where each implementation is that for a particular type
2142 of keystore.
2143 .RS
2144 .PP
2145 Currently, two command\-line tools (\f[CB]keytool\f[R] and
2146 \f[CB]jarsigner\f[R]) make use of keystore implementations.
2147 Because the \f[CB]KeyStore\f[R] class is \f[CB]public\f[R], users can write
2148 additional security applications that use it.
2149 .PP
2150 In JDK 9 and later, the default keystore implementation is
2151 \f[CB]PKCS12\f[R].
2152 This is a cross platform keystore based on the RSA PKCS12 Personal
2153 Information Exchange Syntax Standard.
2154 This standard is primarily meant for storing or transporting a
2155 user\[aq]s private keys, certificates, and miscellaneous secrets.
2156 There is another built\-in implementation, provided by Oracle.
2157 It implements the keystore as a file with a proprietary keystore type
2158 (format) named \f[CB]JKS\f[R].
2159 It protects each private key with its individual password, and also
2160 protects the integrity of the entire keystore with a (possibly
2161 different) password.
2162 .PP
2163 Keystore implementations are provider\-based.
2164 More specifically, the application interfaces supplied by
2165 \f[CB]KeyStore\f[R] are implemented in terms of a Service Provider
2166 Interface (SPI).
2167 That is, there is a corresponding abstract \f[CB]KeystoreSpi\f[R] class,
2168 also in the \f[CB]java.security\ package\f[R], which defines the Service
2169 Provider Interface methods that providers must implement.
2170 The term \f[I]provider\f[R] refers to a package or a set of packages that
2171 supply a concrete implementation of a subset of services that can be
2172 accessed by the Java Security API.
2173 To provide a keystore implementation, clients must implement a provider
2174 and supply a \f[CB]KeystoreSpi\f[R] subclass implementation, as described
2175 in Steps to Implement and Integrate a Provider.
2176 .PP
2177 Applications can choose different types of keystore implementations from
2178 different providers, using the \f[CB]getInstance\f[R] factory method
2179 supplied in the \f[CB]KeyStore\f[R] class.
2180 A keystore type defines the storage and data format of the keystore
2181 information, and the algorithms used to protect private/secret keys in
2182 the keystore and the integrity of the keystore.
2183 Keystore implementations of different types aren\[aq]t compatible.
2184 .PP
2185 The \f[CB]keytool\f[R] command works on any file\-based keystore
2186 implementation.
2187 It treats the keystore location that is passed to it at the command line
2188 as a file name and converts it to a \f[CB]FileInputStream\f[R], from which
2189 it loads the keystore information.)The \f[CB]jarsigner\f[R] commands can
2190 read a keystore from any location that can be specified with a URL.
2191 .PP
2192 For \f[CB]keytool\f[R] and \f[CB]jarsigner\f[R], you can specify a keystore
2193 type at the command line, with the \f[CB]\-storetype\f[R] option.
2194 .PP
2195 If you don\[aq]t explicitly specify a keystore type, then the tools
2196 choose a keystore implementation based on the value of the
2197 \f[CB]keystore.type\f[R] property specified in the security properties
2198 file.
2199 The security properties file is called \f[CB]java.security\f[R], and
2200 resides in the security properties directory:
2201 .IP \[bu] 2
2202 \f[B]Oracle Solaris, Linux, and OS X:\f[R]
2203 \f[CB]java.home/lib/security\f[R]
2204 .IP \[bu] 2
2205 \f[B]Windows:\f[R] \f[CB]java.home\\lib\\security\f[R]
2206 .PP
2207 Each tool gets the \f[CB]keystore.type\f[R] value and then examines all
2208 the currently installed providers until it finds one that implements a
2209 keystores of that type.
2210 It then uses the keystore implementation from that provider.The
2211 \f[CB]KeyStore\f[R] class defines a static method named
2212 \f[CB]getDefaultType\f[R] that lets applications retrieve the value of the
2213 \f[CB]keystore.type\f[R] property.
2214 The following line of code creates an instance of the default keystore
2215 type as specified in the \f[CB]keystore.type\f[R] property:
2216 .RS
2217 .PP
2218 \f[CB]KeyStore\ keyStore\ =\ KeyStore.getInstance(KeyStore.getDefaultType());\f[R]
2219 .RE
2220 .PP
2221 The default keystore type is \f[CB]pkcs12\f[R], which is a cross\-platform
2222 keystore based on the RSA PKCS12 Personal Information Exchange Syntax
2223 Standard.
2224 This is specified by the following line in the security properties file:
2225 .RS
2226 .PP
2227 \f[CB]keystore.type=pkcs12\f[R]
2228 .RE
2229 .PP
2230 To have the tools utilize a keystore implementation other than the
2231 default, you can change that line to specify a different keystore type.
2232 For example, if you want to use the Oracle\[aq]s \f[CB]jks\f[R] keystore
2233 implementation, then change the line to the following:
2234 .RS
2235 .PP
2236 \f[CB]keystore.type=jks\f[R]
2237 .RE
2238 .PP
2239 \f[B]Note:\f[R]
2240 .PP
2241 Case doesn\[aq]t matter in keystore type designations.
2242 For example, \f[CB]JKS\f[R] would be considered the same as \f[CB]jks\f[R].
2243 .RE
2244 .TP
2245 .B Certificate
2246 A certificate (or public\-key certificate) is a digitally signed
2247 statement from one entity (the issuer), saying that the public key and
2248 some other information of another entity (the subject) has some specific
2249 value.
2250 The following terms are related to certificates:
2251 .RS
2252 .IP \[bu] 2
2253 Public Keys: These are numbers associated with a particular entity, and
2254 are intended to be known to everyone who needs to have trusted
2255 interactions with that entity.
2256 Public keys are used to verify signatures.
2257 .IP \[bu] 2
2258 Digitally Signed: If some data is digitally signed, then it is stored
2259 with the identity of an entity and a signature that proves that entity
2260 knows about the data.
2261 The data is rendered unforgeable by signing with the entity\[aq]s
2262 private key.
2263 .IP \[bu] 2
2264 Identity: A known way of addressing an entity.
2265 In some systems, the identity is the public key, and in others it can be
2266 anything from an Oracle Solaris UID to an email address to an X.509
2267 distinguished name.
2268 .IP \[bu] 2
2269 Signature: A signature is computed over some data using the private key
2270 of an entity.
2271 The signer, which in the case of a certificate is also known as the
2272 issuer.
2273 .IP \[bu] 2
2274 Private Keys: These are numbers, each of which is supposed to be known
2275 only to the particular entity whose private key it is (that is, it is
2276 supposed to be kept secret).
2277 Private and public keys exist in pairs in all public key cryptography
2278 systems (also referred to as public key crypto systems).
2279 In a typical public key crypto system, such as DSA, a private key
2280 corresponds to exactly one public key.
2281 Private keys are used to compute signatures.
2282 .IP \[bu] 2
2283 Entity: An entity is a person, organization, program, computer,
2284 business, bank, or something else you are trusting to some degree.
2285 .PP
2286 Public key cryptography requires access to users\[aq] public keys.
2287 In a large\-scale networked environment, it is impossible to guarantee
2288 that prior relationships between communicating entities were established
2289 or that a trusted repository exists with all used public keys.
2290 Certificates were invented as a solution to this public key distribution
2291 problem.
2292 Now a Certification Authority (CA) can act as a trusted third party.
2293 CAs are entities such as businesses that are trusted to sign (issue)
2294 certificates for other entities.
2295 It is assumed that CAs only create valid and reliable certificates
2296 because they are bound by legal agreements.
2297 There are many public Certification Authorities, such as DigiCert,
2298 Comodo, Entrust, and so on.
2299 .PP
2300 You can also run your own Certification Authority using products such as
2301 Microsoft Certificate Server or the Entrust CA product for your
2302 organization.
2303 With the \f[CB]keytool\f[R] command, it is possible to display, import,
2304 and export certificates.
2305 It is also possible to generate self\-signed certificates.
2306 .PP
2307 The \f[CB]keytool\f[R] command currently handles X.509 certificates.
2308 .RE
2309 .TP
2310 .B X.509 Certificates
2311 The X.509 standard defines what information can go into a certificate
2312 and describes how to write it down (the data format).
2313 All the data in a certificate is encoded with two related standards
2314 called ASN.1/DER.
2315 Abstract Syntax Notation 1 describes data.
2316 The Definite Encoding Rules describe a single way to store and transfer
2317 that data.
2318 .RS
2319 .PP
2320 All X.509 certificates have the following data, in addition to the
2321 signature:
2322 .IP \[bu] 2
2323 Version: This identifies which version of the X.509 standard applies to
2324 this certificate, which affects what information can be specified in it.
2325 Thus far, three versions are defined.
2326 The \f[CB]keytool\f[R] command can import and export v1, v2, and v3
2327 certificates.
2328 It generates v3 certificates.
2329 .RS 2
2330 .IP \[bu] 2
2331 X.509 Version 1 has been available since 1988, is widely deployed, and
2332 is the most generic.
2333 .IP \[bu] 2
2334 X.509 Version 2 introduced the concept of subject and issuer unique
2335 identifiers to handle the possibility of reuse of subject or issuer
2336 names over time.
2337 Most certificate profile documents strongly recommend that names not be
2338 reused and that certificates shouldn\[aq]t make use of unique
2339 identifiers.
2340 Version 2 certificates aren\[aq]t widely used.
2341 .IP \[bu] 2
2342 X.509 Version 3 is the most recent (1996) and supports the notion of
2343 extensions where anyone can define an extension and include it in the
2344 certificate.
2345 Some common extensions are: KeyUsage (limits the use of the keys to
2346 particular purposes such as \f[CB]signing\-only\f[R]) and AlternativeNames
2347 (allows other identities to also be associated with this public key, for
2348 example.
2349 DNS names, email addresses, IP addresses).
2350 Extensions can be marked critical to indicate that the extension should
2351 be checked and enforced or used.
2352 For example, if a certificate has the KeyUsage extension marked critical
2353 and set to \f[CB]keyCertSign\f[R], then when this certificate is presented
2354 during SSL communication, it should be rejected because the certificate
2355 extension indicates that the associated private key should only be used
2356 for signing certificates and not for SSL use.
2357 .RE
2358 .IP \[bu] 2
2359 Serial number: The entity that created the certificate is responsible
2360 for assigning it a serial number to distinguish it from other
2361 certificates it issues.
2362 This information is used in numerous ways.
2363 For example, when a certificate is revoked its serial number is placed
2364 in a Certificate Revocation List (CRL).
2365 .IP \[bu] 2
2366 Signature algorithm identifier: This identifies the algorithm used by
2367 the CA to sign the certificate.
2368 .IP \[bu] 2
2369 Issuer name: The X.500 Distinguished Name of the entity that signed the
2370 certificate.
2371 This is typically a CA.
2372 Using this certificate implies trusting the entity that signed this
2373 certificate.
2374 In some cases, such as root or top\-level CA certificates, the issuer
2375 signs its own certificate.
2376 .IP \[bu] 2
2377 Validity period: Each certificate is valid only for a limited amount of
2378 time.
2379 This period is described by a start date and time and an end date and
2380 time, and can be as short as a few seconds or almost as long as a
2381 century.
2382 The validity period chosen depends on a number of factors, such as the
2383 strength of the private key used to sign the certificate, or the amount
2384 one is willing to pay for a certificate.
2385 This is the expected period that entities can rely on the public value,
2386 when the associated private key has not been compromised.
2387 .IP \[bu] 2
2388 Subject name: The name of the entity whose public key the certificate
2389 identifies.
2390 This name uses the X.500 standard, so it is intended to be unique across
2391 the Internet.
2392 This is the X.500 Distinguished Name (DN) of the entity.
2393 For example,
2394 .RS 2
2395 .RS
2396 .PP
2397 \f[CB]CN=Java\ Duke,\ OU=Java\ Software\ Division,\ O=Oracle\ Corporation,\ C=US\f[R]
2398 .RE
2399 .PP
2400 These refer to the subject\[aq]s common name (CN), organizational unit
2401 (OU), organization (O), and country (C).
2402 .RE
2403 .IP \[bu] 2
2404 Subject public key information: This is the public key of the entity
2405 being named with an algorithm identifier that specifies which public key
2406 crypto system this key belongs to and any associated key parameters.
2407 .RE
2408 .TP
2409 .B Certificate Chains
2410 The \f[CB]keytool\f[R] command can create and manage keystore key entries
2411 that each contain a private key and an associated certificate chain.
2412 The first certificate in the chain contains the public key that
2413 corresponds to the private key.
2414 .RS
2415 .PP
2416 When keys are first generated, the chain starts off containing a single
2417 element, a self\-signed certificate.
2418 See \-genkeypair in \f[B]Commands\f[R].
2419 A self\-signed certificate is one for which the issuer (signer) is the
2420 same as the subject.
2421 The subject is the entity whose public key is being authenticated by the
2422 certificate.
2423 Whenever the \f[CB]\-genkeypair\f[R] command is called to generate a new
2424 public/private key pair, it also wraps the public key into a
2425 self\-signed certificate.
2426 .PP
2427 Later, after a Certificate Signing Request (CSR) was generated with the
2428 \f[CB]\-certreq\f[R] command and sent to a Certification Authority (CA),
2429 the response from the CA is imported with \f[CB]\-importcert\f[R], and the
2430 self\-signed certificate is replaced by a chain of certificates.
2431 At the bottom of the chain is the certificate (reply) issued by the CA
2432 authenticating the subject\[aq]s public key.
2433 The next certificate in the chain is one that authenticates the CA\[aq]s
2434 public key.
2435 .PP
2436 In many cases, this is a self\-signed certificate, which is a
2437 certificate from the CA authenticating its own public key, and the last
2438 certificate in the chain.
2439 In other cases, the CA might return a chain of certificates.
2440 In this case, the bottom certificate in the chain is the same (a
2441 certificate signed by the CA, authenticating the public key of the key
2442 entry), but the second certificate in the chain is a certificate signed
2443 by a different CA that authenticates the public key of the CA you sent
2444 the CSR to.
2445 The next certificate in the chain is a certificate that authenticates
2446 the second CA\[aq]s key, and so on, until a self\-signed root
2447 certificate is reached.
2448 Each certificate in the chain (after the first) authenticates the public
2449 key of the signer of the previous certificate in the chain.
2450 .PP
2451 Many CAs only return the issued certificate, with no supporting chain,
2452 especially when there is a flat hierarchy (no intermediates CAs).
2453 In this case, the certificate chain must be established from trusted
2454 certificate information already stored in the keystore.
2455 .PP
2456 A different reply format (defined by the PKCS #7 standard) includes the
2457 supporting certificate chain in addition to the issued certificate.
2458 Both reply formats can be handled by the \f[CB]keytool\f[R] command.
2459 .PP
2460 The top\-level (root) CA certificate is self\-signed.
2461 However, the trust into the root\[aq]s public key doesn\[aq]t come from
2462 the root certificate itself, but from other sources such as a newspaper.
2463 This is because anybody could generate a self\-signed certificate with
2464 the distinguished name of, for example, the DigiCert root CA.
2465 The root CA public key is widely known.
2466 The only reason it is stored in a certificate is because this is the
2467 format understood by most tools, so the certificate in this case is only
2468 used as a vehicle to transport the root CA\[aq]s public key.
2469 Before you add the root CA certificate to your keystore, you should view
2470 it with the \f[CB]\-printcert\f[R] option and compare the displayed
2471 fingerprint with the well\-known fingerprint obtained from a newspaper,
2472 the root CA\[aq]s Web page, and so on.
2473 .RE
2474 .TP
2475 .B cacerts Certificates File
2476 A certificates file named \f[CB]cacerts\f[R] resides in the security
2477 properties directory:
2478 .RS
2479 .IP \[bu] 2
2480 \f[B]Oracle Solaris, Linux, and OS X:\f[R]
2481 \f[I]JAVA_HOME\f[R]\f[CB]/lib/security\f[R]
2482 .IP \[bu] 2
2483 \f[B]Windows:\f[R] \f[I]JAVA_HOME\f[R]\f[CB]\\lib\\security\f[R]
2484 .PP
2485 \f[I]JAVA_HOME\f[R] is the runtime environment directory, which is the
2486 \f[CB]jre\f[R] directory in the JDK or the top\-level directory of the
2487 Java Runtime Environment (JRE).
2488 .PP
2489 The \f[CB]cacerts\f[R] file represents a system\-wide keystore with CA
2490 certificates.
2491 System administrators can configure and manage that file with the
2492 \f[CB]keytool\f[R] command by specifying \f[CB]jks\f[R] as the keystore
2493 type.
2494 The \f[CB]cacerts\f[R] keystore file ships with a default set of root CA
2495 certificates.
2496 For Oracle Solaris, Linux, OS X, and Windows, you can list the default
2497 certificates with the following command:
2498 .RS
2499 .PP
2500 \f[CB]keytool\ \-list\ \-cacerts\f[R]
2501 .RE
2502 .PP
2503 The initial password of the \f[CB]cacerts\f[R] keystore file is
2504 \f[CB]changeit\f[R].
2505 System administrators should change that password and the default access
2506 permission of that file upon installing the SDK.
2507 .PP
2508 \f[B]Note:\f[R]
2509 .PP
2510 It is important to verify your \f[CB]cacerts\f[R] file.
2511 Because you trust the CAs in the \f[CB]cacerts\f[R] file as entities for
2512 signing and issuing certificates to other entities, you must manage the
2513 \f[CB]cacerts\f[R] file carefully.
2514 The \f[CB]cacerts\f[R] file should contain only certificates of the CAs
2515 you trust.
2516 It is your responsibility to verify the trusted root CA certificates
2517 bundled in the \f[CB]cacerts\f[R] file and make your own trust decisions.
2518 .PP
2519 To remove an untrusted CA certificate from the \f[CB]cacerts\f[R] file,
2520 use the \f[CB]\-delete\f[R] option of the \f[CB]keytool\f[R] command.
2521 You can find the \f[CB]cacerts\f[R] file in the JRE installation
2522 directory.
2523 Contact your system administrator if you don\[aq]t have permission to
2524 edit this file
2525 .RE
2526 .TP
2527 .B Internet RFC 1421 Certificate Encoding Standard
2528 Certificates are often stored using the printable encoding format
2529 defined by the Internet RFC 1421 standard, instead of their binary
2530 encoding.
2531 This certificate format, also known as Base64 encoding, makes it easy to
2532 export certificates to other applications by email or through some other
2533 mechanism.
2534 .RS
2535 .PP
2536 Certificates read by the \f[CB]\-importcert\f[R] and \f[CB]\-printcert\f[R]
2537 commands can be in either this format or binary encoded.
2538 The \f[CB]\-exportcert\f[R] command by default outputs a certificate in
2539 binary encoding, but will instead output a certificate in the printable
2540 encoding format, when the \f[CB]\-rfc\f[R] option is specified.
2541 .PP
2542 The \f[CB]\-list\f[R] command by default prints the SHA\-256 fingerprint
2543 of a certificate.
2544 If the \f[CB]\-v\f[R] option is specified, then the certificate is printed
2545 in human\-readable format.
2546 If the \f[CB]\-rfc\f[R] option is specified, then the certificate is
2547 output in the printable encoding format.
2548 .PP
2549 In its printable encoding format, the encoded certificate is bounded at
2550 the beginning and end by the following text:
2551 .IP
2552 .nf
2553 \f[CB]
2554 \-\-\-\-\-BEGIN\ CERTIFICATE\-\-\-\-\-
2555
2556 encoded\ certificate\ goes\ here.
2557
2558 \-\-\-\-\-END\ CERTIFICATE\-\-\-\-\-
2559 \f[R]
2560 .fi
2561 .RE
2562 .TP
2563 .B X.500 Distinguished Names
2564 X.500 Distinguished Names are used to identify entities, such as those
2565 that are named by the \f[CB]subject\f[R] and \f[CB]issuer\f[R] (signer)
2566 fields of X.509 certificates.
2567 The \f[CB]keytool\f[R] command supports the following subparts:
2568 .RS
2569 .IP \[bu] 2
2570 commonName: The common name of a person such as Susan Jones.
2571 .IP \[bu] 2
2572 organizationUnit: The small organization (such as department or
2573 division) name.
2574 For example, Purchasing.
2575 .IP \[bu] 2
2576 localityName: The locality (city) name, for example, Palo Alto.
2577 .IP \[bu] 2
2578 stateName: State or province name, for example, California.
2579 .IP \[bu] 2
2580 country: Two\-letter country code, for example, CH.
2581 .PP
2582 When you supply a distinguished name string as the value of a
2583 \f[CB]\-dname\f[R] option, such as for the \f[CB]\-genkeypair\f[R] command,
2584 the string must be in the following format:
2585 .RS
2586 .PP
2587 \f[CB]CN=cName,\ OU=orgUnit,\ O=org,\ L=city,\ S=state,\ C=countryCode\f[R]
2588 .RE
2589 .PP
2590 All the following items represent actual values and the previous
2591 keywords are abbreviations for the following:
2592 .IP
2593 .nf
2594 \f[CB]
2595 CN=commonName
2596 OU=organizationUnit
2597 O=organizationName
2598 L=localityName
2599 S=stateName
2600 C=country
2601 \f[R]
2602 .fi
2603 .PP
2604 A sample distinguished name string is:
2605 .RS
2606 .PP
2607 \f[CB]CN=Mark\ Smith,\ OU=Java,\ O=Oracle,\ L=Cupertino,\ S=California,\ C=US\f[R]
2608 .RE
2609 .PP
2610 A sample command using such a string is:
2611 .RS
2612 .PP
2613 \f[CB]keytool\ \-genkeypair\ \-dname\ "CN=Mark\ Smith,\ OU=Java,\ O=Oracle,\ L=Cupertino,\ S=California,\ C=US"\ \-alias\ mark\ \-keyalg\ rsa\f[R]
2614 .RE
2615 .PP
2616 Case doesn\[aq]t matter for the keyword abbreviations.
2617 For example, CN, cn, and Cn are all treated the same.
2618 .PP
2619 Order matters; each subcomponent must appear in the designated order.
2620 However, it isn\[aq]t necessary to have all the subcomponents.
2621 You can use a subset, for example:
2622 .RS
2623 .PP
2624 \f[CB]CN=Smith,\ OU=Java,\ O=Oracle,\ C=US\f[R]
2625 .RE
2626 .PP
2627 If a distinguished name string value contains a comma, then the comma
2628 must be escaped by a backslash (\\) character when you specify the
2629 string on a command line, as in:
2630 .RS
2631 .PP
2632 \f[CB]cn=Jack,\ ou=Java\\,\ Product\ Development,\ o=Oracle,\ c=US\f[R]
2633 .RE
2634 .PP
2635 It is never necessary to specify a distinguished name string on a
2636 command line.
2637 When the distinguished name is needed for a command, but not supplied on
2638 the command line, the user is prompted for each of the subcomponents.
2639 In this case, a comma doesn\[aq]t need to be escaped by a backslash
2640 (\\).
2641 .RE
2642 .SH WARNINGS
2643 .SH IMPORTING TRUSTED CERTIFICATES WARNING
2644 .PP
2645 \f[B]Important\f[R]: Be sure to check a certificate very carefully before
2646 importing it as a trusted certificate.
2647 .PP
2648 \f[B]Windows Example:\f[R]
2649 .PP
2650 View the certificate first with the \f[CB]\-printcert\f[R] command or the
2651 \f[CB]\-importcert\f[R] command without the \f[CB]\-noprompt\f[R] option.
2652 Ensure that the displayed certificate fingerprints match the expected
2653 ones.
2654 For example, suppose someone sends or emails you a certificate that you
2655 put it in a file named \f[CB]\\tmp\\cert\f[R].
2656 Before you consider adding the certificate to your list of trusted
2657 certificates, you can execute a \f[CB]\-printcert\f[R] command to view its
2658 fingerprints, as follows:
2659 .IP
2660 .nf
2661 \f[CB]
2662 \ \ keytool\ \-printcert\ \-file\ \\tmp\\cert
2663 \ \ \ \ Owner:\ CN=ll,\ OU=ll,\ O=ll,\ L=ll,\ S=ll,\ C=ll
2664 \ \ \ \ Issuer:\ CN=ll,\ OU=ll,\ O=ll,\ L=ll,\ S=ll,\ C=ll
2665 \ \ \ \ Serial\ Number:\ 59092b34
2666 \ \ \ \ Valid\ from:\ Thu\ Jun\ 24\ 18:01:13\ PDT\ 2016\ until:\ Wed\ Jun\ 23\ 17:01:13\ PST\ 2016
2667 \ \ \ \ Certificate\ Fingerprints:
2668
2669 \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ SHA\-1:\ 20:B6:17:FA:EF:E5:55:8A:D0:71:1F:E8:D6:9D:C0:37:13:0E:5E:FE
2670 \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ SHA\-256:\ 90:7B:70:0A:EA:DC:16:79:92:99:41:FF:8A:FE:EB:90:
2671 \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 17:75:E0:90:B2:24:4D:3A:2A:16:A6:E4:11:0F:67:A4
2672 \f[R]
2673 .fi
2674 .PP
2675 \f[B]Oracle Solaris Example:\f[R]
2676 .PP
2677 View the certificate first with the \f[CB]\-printcert\f[R] command or the
2678 \f[CB]\-importcert\f[R] command without the \f[CB]\-noprompt\f[R] option.
2679 Ensure that the displayed certificate fingerprints match the expected
2680 ones.
2681 For example, suppose someone sends or emails you a certificate that you
2682 put it in a file named \f[CB]/tmp/cert\f[R].
2683 Before you consider adding the certificate to your list of trusted
2684 certificates, you can execute a \f[CB]\-printcert\f[R] command to view its
2685 fingerprints, as follows:
2686 .IP
2687 .nf
2688 \f[CB]
2689 \ \ keytool\ \-printcert\ \-file\ /tmp/cert
2690 \ \ \ \ Owner:\ CN=ll,\ OU=ll,\ O=ll,\ L=ll,\ S=ll,\ C=ll
2691 \ \ \ \ Issuer:\ CN=ll,\ OU=ll,\ O=ll,\ L=ll,\ S=ll,\ C=ll
2692 \ \ \ \ Serial\ Number:\ 59092b34
2693 \ \ \ \ Valid\ from:\ Thu\ Jun\ 24\ 18:01:13\ PDT\ 2016\ until:\ Wed\ Jun\ 23\ 17:01:13\ PST\ 2016
2694 \ \ \ \ Certificate\ Fingerprints:
2695
2696 \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ SHA\-1:\ 20:B6:17:FA:EF:E5:55:8A:D0:71:1F:E8:D6:9D:C0:37:13:0E:5E:FE
2697 \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ SHA\-256:\ 90:7B:70:0A:EA:DC:16:79:92:99:41:FF:8A:FE:EB:90:
2698 \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 17:75:E0:90:B2:24:4D:3A:2A:16:A6:E4:11:0F:67:A4
2699 \f[R]
2700 .fi
2701 .PP
2702 Then call or otherwise contact the person who sent the certificate and
2703 compare the fingerprints that you see with the ones that they show.
2704 Only when the fingerprints are equal is it guaranteed that the
2705 certificate wasn\[aq]t replaced in transit with somebody else\[aq]s
2706 certificate such as an attacker\[aq]s certificate.
2707 If such an attack took place, and you didn\[aq]t check the certificate
2708 before you imported it, then you would be trusting anything the attacker
2709 signed, for example, a JAR file with malicious class files inside.
2710 .PP
2711 \f[B]Note:\f[R]
2712 .PP
2713 It isn\[aq]t required that you execute a \f[CB]\-printcert\f[R] command
2714 before importing a certificate.
2715 This is because before you add a certificate to the list of trusted
2716 certificates in the keystore, the \f[CB]\-importcert\f[R] command prints
2717 out the certificate information and prompts you to verify it.
2718 You can then stop the import operation.
2719 However, you can do this only when you call the \f[CB]\-importcert\f[R]
2720 command without the \f[CB]\-noprompt\f[R] option.
2721 If the \f[CB]\-noprompt\f[R] option is specified, then there is no
2722 interaction with the user.
2723 .SH PASSWORDS WARNING
2724 .PP
2725 Most commands that operate on a keystore require the store password.
2726 Some commands require a private/secret key password.
2727 Passwords can be specified on the command line in the
2728 \f[CB]\-storepass\f[R] and \f[CB]\-keypass\f[R] options.
2729 However, a password shouldn\[aq]t be specified on a command line or in a
2730 script unless it is for testing, or you are on a secure system.
2731 When you don\[aq]t specify a required password option on a command line,
2732 you are prompted for it.
2733 .SH CERTIFICATE CONFORMANCE WARNING
2734 .PP
2735 \f[B]Internet X.509 Public Key Infrastructure Certificate and
2736 Certificate Revocation List (CRL) Profile\f[R]
2737 [https://tools.ietf.org/rfc/rfc5280.txt] defined a profile on conforming
2738 X.509 certificates, which includes what values and value combinations
2739 are valid for certificate fields and extensions.
2740 .PP
2741 The \f[CB]keytool\f[R] command doesn\[aq]t enforce all of these rules so
2742 it can generate certificates that don\[aq]t conform to the standard,
2743 such as self\-signed certificates that would be used for internal
2744 testing purposes.
2745 Certificates that don\[aq]t conform to the standard might be rejected by
2746 JRE or other applications.
2747 Users should ensure that they provide the correct options for
2748 \f[CB]\-dname\f[R], \f[CB]\-ext\f[R], and so on.
2749 .SH IMPORT A NEW TRUSTED CERTIFICATE
2750 .PP
2751 Before you add the certificate to the keystore, the \f[CB]keytool\f[R]
2752 command verifies it by attempting to construct a chain of trust from
2753 that certificate to a self\-signed certificate (belonging to a root CA),
2754 using trusted certificates that are already available in the keystore.
2755 .PP
2756 If the \f[CB]\-trustcacerts\f[R] option was specified, then additional
2757 certificates are considered for the chain of trust, namely the
2758 certificates in a file named \f[CB]cacerts\f[R].
2759 .PP
2760 If the \f[CB]keytool\f[R] command fails to establish a trust path from the
2761 certificate to be imported up to a self\-signed certificate (either from
2762 the keystore or the \f[CB]cacerts\f[R] file), then the certificate
2763 information is printed, and the user is prompted to verify it by
2764 comparing the displayed certificate fingerprints with the fingerprints
2765 obtained from some other (trusted) source of information, which might be
2766 the certificate owner.
2767 Be very careful to ensure the certificate is valid before importing it
2768 as a trusted certificate.
2769 The user then has the option of stopping the import operation.
2770 If the \f[CB]\-noprompt\f[R] option is specified, then there is no
2771 interaction with the user.
2772 .SH IMPORT A CERTIFICATE REPLY
2773 .PP
2774 When you import a certificate reply, the certificate reply is validated
2775 with trusted certificates from the keystore, and optionally, the
2776 certificates configured in the \f[CB]cacerts\f[R] keystore file when the
2777 \f[CB]\-trustcacerts\f[R] option is specified.
2778 .PP
2779 The methods of determining whether the certificate reply is trusted are
2780 as follows:
2781 .IP \[bu] 2
2782 If the reply is a single X.509 certificate, then the \f[CB]keytool\f[R]
2783 command attempts to establish a trust chain, starting at the certificate
2784 reply and ending at a self\-signed certificate (belonging to a root CA).
2785 The certificate reply and the hierarchy of certificates is used to
2786 authenticate the certificate reply from the new certificate chain of
2787 aliases.
2788 If a trust chain can\[aq]t be established, then the certificate reply
2789 isn\[aq]t imported.
2790 In this case, the \f[CB]keytool\f[R] command doesn\[aq]t print the
2791 certificate and prompt the user to verify it, because it is very
2792 difficult for a user to determine the authenticity of the certificate
2793 reply.
2794 .IP \[bu] 2
2795 If the reply is a PKCS #7 formatted certificate chain or a sequence of
2796 X.509 certificates, then the chain is ordered with the user certificate
2797 first followed by zero or more CA certificates.
2798 If the chain ends with a self\-signed root CA certificate and
2799 the\f[CB]\-trustcacerts\f[R] option was specified, the \f[CB]keytool\f[R]
2800 command attempts to match it with any of the trusted certificates in the
2801 keystore or the \f[CB]cacerts\f[R] keystore file.
2802 If the chain doesn\[aq]t end with a self\-signed root CA certificate and
2803 the \f[CB]\-trustcacerts\f[R] option was specified, the \f[CB]keytool\f[R]
2804 command tries to find one from the trusted certificates in the keystore
2805 or the \f[CB]cacerts\f[R] keystore file and add it to the end of the
2806 chain.
2807 If the certificate isn\[aq]t found and the \f[CB]\-noprompt\f[R] option
2808 isn\[aq]t specified, the information of the last certificate in the
2809 chain is printed, and the user is prompted to verify it.
2810 .PP
2811 If the public key in the certificate reply matches the user\[aq]s public
2812 key already stored with \f[CB]alias\f[R], then the old certificate chain
2813 is replaced with the new certificate chain in the reply.
2814 The old chain can only be replaced with a valid \f[CB]keypass\f[R], and so
2815 the password used to protect the private key of the entry is supplied.
2816 If no password is provided, and the private key password is different
2817 from the keystore password, the user is prompted for it.
2818 .PP
2819 This command was named \f[CB]\-import\f[R] in earlier releases.
2820 This old name is still supported in this release.
2821 The new name, \f[CB]\-importcert\f[R], is preferred.