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