annotate src/linux/doc/man/keytool.1 @ 7317:bfae8dda86b1

Added tag jdk7u65-b06 for changeset 7d8e5d907895
author katleman
date Tue, 01 Apr 2014 12:01:47 -0700
parents 23bdcede4e39
children
rev   line source
bpatel@4900 1 ." Copyright (c) 1998-2011 keytool tool, Oracle and/or its affiliates. All rights reserved.
duke@0 2 ." DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
duke@0 3 ."
duke@0 4 ." This code is free software; you can redistribute it and/or modify it
duke@0 5 ." under the terms of the GNU General Public License version 2 only, as
duke@0 6 ." published by the Free Software Foundation.
duke@0 7 ."
duke@0 8 ." This code is distributed in the hope that it will be useful, but WITHOUT
duke@0 9 ." ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
duke@0 10 ." FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
duke@0 11 ." version 2 for more details (a copy is included in the LICENSE file that
duke@0 12 ." accompanied this code).
duke@0 13 ."
duke@0 14 ." You should have received a copy of the GNU General Public License version
duke@0 15 ." 2 along with this work; if not, write to the Free Software Foundation,
duke@0 16 ." Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
duke@0 17 ."
ohair@2362 18 ." Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
ohair@2362 19 ." or visit www.oracle.com if you need additional information or have any
ohair@2362 20 ." questions.
tbell@1178 21 ."
bpatel@4900 22 .TH keytool 1 "16 Mar 2012"
duke@0 23
duke@0 24 .LP
tbell@1178 25 .SH "Name"
duke@0 26 keytool \- Key and Certificate Management Tool
duke@0 27 .LP
duke@0 28 .LP
duke@0 29 Manages a keystore (database) of cryptographic keys, X.509 certificate chains, and trusted certificates.
bpatel@4176 30 .LP
duke@0 31 .SH "SYNOPSIS"
duke@0 32 .LP
duke@0 33 .nf
duke@0 34 \f3
duke@0 35 .fl
duke@0 36 \fP\f3keytool\fP [ commands ]
duke@0 37 .fl
duke@0 38 .fi
duke@0 39
duke@0 40 .LP
duke@0 41 .LP
duke@0 42 The keytool command interface has changed in Java SE 6. See the Changes Section for a detailed description. Note that previously defined commands are still supported.
duke@0 43 .LP
duke@0 44 .SH "DESCRIPTION"
duke@0 45 .LP
duke@0 46 \f3keytool\fP is a key and certificate management utility. It allows users to administer their own public/private key pairs and associated certificates for use in self\-authentication (where the user authenticates himself/herself to other users/services) or data integrity and authentication services, using digital signatures. It also allows users to cache the public keys (in the form of certificates) of their communicating peers.
duke@0 47 .LP
duke@0 48 A \f2certificate\fP is a digitally signed statement from one entity (person, company, etc.), saying that the public key (and some other information) of some other entity has a particular value. (See Certificates.) When data is digitally signed, the signature can be verified to check the data integrity and authenticity. \f2Integrity\fP means that the data has not been modified or tampered with, and \f2authenticity\fP means the data indeed comes from whoever claims to have created and signed it.
duke@0 49 .LP
duke@0 50 .LP
duke@0 51 \f3keytool\fP also enables users to administer secret keys used in symmetric encryption/decryption (e.g. DES).
duke@0 52 .LP
duke@0 53 .LP
bpatel@4176 54 \f3keytool\fP stores the keys and certificates in a \f2keystore\fP.
duke@0 55 .LP
duke@0 56 .SH "COMMAND AND OPTION NOTES"
duke@0 57 .LP
duke@0 58 .LP
bpatel@4176 59 The various commands and their options are listed and described below. Note:
duke@0 60 .LP
duke@0 61 .RS 3
duke@0 62 .TP 2
duke@0 63 o
duke@0 64 All command and option names are preceded by a minus sign (\-).
duke@0 65 .TP 2
duke@0 66 o
duke@0 67 The options for each command may be provided in any order.
duke@0 68 .TP 2
duke@0 69 o
duke@0 70 All items not italicized or in braces or square brackets are required to appear as is.
duke@0 71 .TP 2
duke@0 72 o
duke@0 73 Braces surrounding an option generally signify that a default value will be used if the option is not specified on the command line. Braces are also used around the \f2\-v\fP, \f2\-rfc\fP, and \f2\-J\fP options, which only have meaning if they appear on the command line (that is, they don't have any "default" values other than not existing).
duke@0 74 .TP 2
duke@0 75 o
duke@0 76 Brackets surrounding an option signify that the user is prompted for the value(s) if the option is not specified on the command line. (For a \f2\-keypass\fP option, if you do not specify the option on the command line, \f3keytool\fP will first attempt to use the keystore password to recover the private/secret key, and if this fails, will then prompt you for the private/secret key password.)
duke@0 77 .TP 2
duke@0 78 o
duke@0 79 Items in italics (option values) represent the actual values that must be supplied. For example, here is the format of the \f2\-printcert\fP command:
duke@0 80 .nf
duke@0 81 \f3
duke@0 82 .fl
duke@0 83 keytool \-printcert {\-file \fP\f4cert_file\fP\f3} {\-v}
duke@0 84 .fl
duke@0 85 \fP
duke@0 86 .fi
duke@0 87 .LP
duke@0 88 When specifying a \f2\-printcert\fP command, replace \f2cert_file\fP with the actual file name, as in:
duke@0 89 .nf
duke@0 90 \f3
duke@0 91 .fl
duke@0 92 keytool \-printcert \-file VScert.cer
duke@0 93 .fl
duke@0 94 \fP
duke@0 95 .fi
duke@0 96 .TP 2
duke@0 97 o
duke@0 98 Option values must be quoted if they contain a blank (space).
duke@0 99 .TP 2
duke@0 100 o
duke@0 101 The \f2\-help\fP command is the default. Thus, the command line
duke@0 102 .nf
duke@0 103 \f3
duke@0 104 .fl
duke@0 105 keytool
duke@0 106 .fl
duke@0 107 \fP
duke@0 108 .fi
bpatel@4176 109 .LP
duke@0 110 is equivalent to
duke@0 111 .nf
duke@0 112 \f3
duke@0 113 .fl
duke@0 114 keytool \-help
duke@0 115 .fl
duke@0 116 \fP
duke@0 117 .fi
duke@0 118 .RE
duke@0 119
duke@0 120 .LP
duke@0 121 .SS
duke@0 122 Option Defaults
duke@0 123 .LP
duke@0 124 .LP
bpatel@4176 125 Below are the defaults for various option values.
bpatel@4176 126 .LP
duke@0 127 .nf
duke@0 128 \f3
duke@0 129 .fl
duke@0 130 \-alias "mykey"
duke@0 131 .fl
duke@0 132
duke@0 133 .fl
duke@0 134 \-keyalg
duke@0 135 .fl
duke@0 136 "DSA" (when using \fP\f3\-genkeypair\fP\f3)
duke@0 137 .fl
duke@0 138 "DES" (when using \fP\f3\-genseckey\fP\f3)
duke@0 139 .fl
duke@0 140
duke@0 141 .fl
duke@0 142 \-keysize
duke@0 143 .fl
bpatel@2509 144 2048 (when using \fP\f3\-genkeypair\fP\f3 and \-keyalg is "RSA")
bpatel@2509 145 .fl
bpatel@2509 146 1024 (when using \fP\f3\-genkeypair\fP\f3 and \-keyalg is "DSA")
duke@0 147 .fl
bpatel@4176 148 256 (when using \fP\f3\-genkeypair\fP\f3 and \-keyalg is "EC")
bpatel@4176 149 .fl
duke@0 150 56 (when using \fP\f3\-genseckey\fP\f3 and \-keyalg is "DES")
duke@0 151 .fl
duke@0 152 168 (when using \fP\f3\-genseckey\fP\f3 and \-keyalg is "DESede")
duke@0 153 .fl
duke@0 154
duke@0 155 .fl
bpatel@4176 156
bpatel@4176 157 .fl
duke@0 158 \-validity 90
duke@0 159 .fl
duke@0 160
duke@0 161 .fl
tbell@1178 162 \-keystore the file named \fP\f4.keystore\fP\f3 in the user's home directory
duke@0 163 .fl
duke@0 164
duke@0 165 .fl
tbell@1178 166 \-storetype the value of the "keystore.type" property in the security properties file,
duke@0 167 .fl
bpatel@4176 168 which is returned by the static \fP\f4getDefaultType\fP\f3 method in
tbell@1178 169 .fl
tbell@1178 170 \fP\f4java.security.KeyStore\fP\f3
duke@0 171 .fl
duke@0 172
duke@0 173 .fl
tbell@1178 174 \-file stdin if reading, stdout if writing
duke@0 175 .fl
duke@0 176
duke@0 177 .fl
duke@0 178 \-protected false
duke@0 179 .fl
duke@0 180 \fP
duke@0 181 .fi
duke@0 182
duke@0 183 .LP
bpatel@4176 184 .LP
bpatel@4176 185 In generating a public/private key pair, the signature algorithm (\f2\-sigalg\fP option) is derived from the algorithm of the underlying private key:
bpatel@4176 186 .LP
bpatel@4176 187 .RS 3
bpatel@4176 188 .TP 2
bpatel@4176 189 o
bpatel@4176 190 If the underlying private key is of type "DSA", the \f2\-sigalg\fP option defaults to "SHA1withDSA"
bpatel@4176 191 .TP 2
bpatel@4176 192 o
bpatel@4176 193 If the underlying private key is of type "RSA", the \f2\-sigalg\fP option defaults to "SHA256withRSA".
bpatel@4176 194 .TP 2
bpatel@4176 195 o
bpatel@4176 196 If the underlying private key is of type "EC", the \f2\-sigalg\fP option defaults to "SHA256withECDSA".
bpatel@4176 197 .RE
bpatel@4176 198
bpatel@4176 199 .LP
bpatel@4176 200 .LP
bpatel@4176 201 Please consult the
duke@0 202 .na
duke@0 203 \f2Java Cryptography Architecture API Specification & Reference\fP @
duke@0 204 .fi
bpatel@4900 205 http://docs.oracle.com/javase/7/docs/technotes/guides/security/crypto/CryptoSpec.html#AppA for a full list of \f2\-keyalg\fP and \f2\-sigalg\fP you can choose from.
bpatel@4176 206 .LP
duke@0 207 .SS
duke@0 208 Common Options
duke@0 209 .LP
duke@0 210 .LP
bpatel@4176 211 The \f2\-v\fP option can appear for all commands except \f2\-help\fP. If it appears, it signifies "verbose" mode; more information will be provided in the output.
bpatel@4176 212 .LP
duke@0 213 .LP
duke@0 214 There is also a \f2\-J\fP\f2javaoption\fP option that may appear for any command. If it appears, the specified \f2javaoption\fP string is passed through directly to the Java interpreter. This option should not contain any spaces. It is useful for adjusting the execution environment or memory usage. For a list of possible interpreter options, type \f2java \-h\fP or \f2java \-X\fP at the command line.
duke@0 215 .LP
duke@0 216 .LP
duke@0 217 These options may appear for all commands operating on a keystore:
duke@0 218 .LP
duke@0 219 .RS 3
duke@0 220 .TP 3
duke@0 221 \-storetype storetype
bpatel@4176 222 .LP
bpatel@4176 223 This qualifier specifies the type of keystore to be instantiated.
duke@0 224 .TP 3
duke@0 225 \-keystore keystore
bpatel@4176 226 .LP
duke@0 227 The keystore location.
duke@0 228 .LP
duke@0 229 If the JKS storetype is used and a keystore file does not yet exist, then certain \f3keytool\fP commands may result in a new keystore file being created. For example, if \f2keytool \-genkeypair\fP is invoked and the \f2\-keystore\fP option is not specified, the default keystore file named \f2.keystore\fP in the user's home directory will be created if it does not already exist. Similarly, if the \f2\-keystore \fP\f2ks_file\fP option is specified but \f2ks_file\fP does not exist, then it will be created
duke@0 230 .LP
duke@0 231 Note that the input stream from the \f2\-keystore\fP option is passed to the \f2KeyStore.load\fP method. If \f2NONE\fP is specified as the URL, then a null stream is passed to the \f2KeyStore.load\fP method. \f2NONE\fP should be specified if the \f2KeyStore\fP is not file\-based (for example, if it resides on a hardware token device).
duke@0 232 .TP 3
bpatel@4176 233 \-storepass[:env|:file] argument
bpatel@4176 234 .LP
duke@0 235 The password which is used to protect the integrity of the keystore.
duke@0 236 .LP
bpatel@4176 237 If the modifier \f2env\fP or \f2file\fP is not specified, then the password has the value \f2argument\fP, which must be at least 6 characters long. Otherwise, the password is retrieved as follows:
bpatel@4176 238 .RS 3
bpatel@4176 239 .TP 2
bpatel@4176 240 o
bpatel@4176 241 \f2env\fP: Retrieve the password from the environment variable named \f2argument\fP
bpatel@4176 242 .TP 2
bpatel@4176 243 o
bpatel@4176 244 \f2file\fP: Retrieve the password from the file named \f2argument\fP
bpatel@4176 245 .RE
bpatel@4176 246 .LP
bpatel@4176 247 \f3Note\fP: All other options that require passwords, such as \f2\-keypass\fP, \f2\-srckeypass\fP, \f2\-destkeypass\fP \f2\-srcstorepass\fP, and \f2\-deststorepass\fP, accept the \f2env\fP and \f2file\fP modifiers. (Remember to separate the password option and the modifier with a colon, (\f2:\fP).)
bpatel@4176 248 .LP
bpatel@4176 249 The password must be provided to all commands that access the keystore contents. For such commands, if a \f2\-storepass\fP option is not provided at the command line, the user is prompted for it.
duke@0 250 .LP
duke@0 251 When retrieving information from the keystore, the password is optional; if no password is given, the integrity of the retrieved information cannot be checked and a warning is displayed.
duke@0 252 .TP 3
duke@0 253 \-providerName provider_name
bpatel@4176 254 .LP
bpatel@4176 255 Used to identify a cryptographic service provider's name when listed in the security properties file.
duke@0 256 .TP 3
duke@0 257 \-providerClass provider_class_name
bpatel@4176 258 .LP
bpatel@4176 259 Used to specify the name of cryptographic service provider's master class file when the service provider is not listed in the security properties file.
duke@0 260 .TP 3
duke@0 261 \-providerArg provider_arg
bpatel@4176 262 .LP
bpatel@4176 263 Used in conjunction with \f2\-providerClass\fP. Represents an optional string input argument for the constructor of \f2provider_class_name\fP.
duke@0 264 .TP 3
duke@0 265 \-protected
bpatel@4176 266 .LP
duke@0 267 Either \f2true\fP or \f2false\fP. This value should be specified as \f2true\fP if a password must be given via a protected authentication path such as a dedicated PIN reader.
tbell@1178 268 .LP
tbell@1178 269 Note: Since there are two keystores involved in \f2\-importkeystore\fP command, two options, namely, \f2\-srcprotected\fP and \f2\-destprotected\fP are provided for the source keystore and the destination keystore respectively.
tbell@1178 270 .TP 3
tbell@1178 271 \-ext {name{:critical}{=value}}
bpatel@4176 272 .LP
bpatel@4176 273 Denotes an X.509 certificate extension. The option can be used in \-genkeypair and \-gencert to embed extensions into the certificate generated, or in \f2\-certreq\fP to show what extensions are requested in the certificate request. The option can appear multiple times. name can be a supported extension name (see below) or an arbitrary OID number. value, if provided, denotes the parameter for the extension; if omitted, denotes the default value (if defined) of the extension or the extension requires no parameter. The \f2:critical\fP modifier, if provided, means the extension's isCritical attribute is true; otherwise, false. You may use \f2:c\fP in place of \f2:critical\fP.
bpatel@4176 274 .RE
duke@0 275
duke@0 276 .LP
tbell@1178 277 .LP
tbell@1178 278 Currently keytool supports these named extensions (case\-insensitive):
tbell@1178 279 .LP
tbell@1178 280 .LP
bpatel@4900 281 .TS
tbell@1178 282 .if \n+(b.=1 .nr d. \n(.c-\n(c.-1
tbell@1178 283 .de 35
tbell@1178 284 .ps \n(.s
tbell@1178 285 .vs \n(.vu
tbell@1178 286 .in \n(.iu
tbell@1178 287 .if \n(.u .fi
tbell@1178 288 .if \n(.j .ad
tbell@1178 289 .if \n(.j=0 .na
tbell@1178 290 ..
tbell@1178 291 .nf
tbell@1178 292 .nr #~ 0
tbell@1178 293 .if n .nr #~ 0.6n
tbell@1178 294 .ds #d .d
tbell@1178 295 .if \(ts\n(.z\(ts\(ts .ds #d nl
tbell@1178 296 .fc
tbell@1178 297 .nr 33 \n(.s
tbell@1178 298 .rm 80 81
tbell@1178 299 .nr 34 \n(.lu
tbell@1178 300 .eo
tbell@1178 301 .am 81
tbell@1178 302 .br
tbell@1178 303 .di a+
tbell@1178 304 .35
tbell@1178 305 .ft \n(.f
tbell@1178 306 .ll \n(34u*1u/3u
tbell@1178 307 .if \n(.l<\n(81 .ll \n(81u
tbell@1178 308 .in 0
tbell@1178 309 The full form: "ca:{true|false}[,pathlen:<len>]"; or, <len>, a shorthand for "ca:true,pathlen:<len>"; or omitted, means "ca:true"
tbell@1178 310 .br
tbell@1178 311 .di
tbell@1178 312 .nr a| \n(dn
tbell@1178 313 .nr a- \n(dl
tbell@1178 314 ..
tbell@1178 315 .ec \
tbell@1178 316 .eo
tbell@1178 317 .am 81
tbell@1178 318 .br
tbell@1178 319 .di b+
tbell@1178 320 .35
tbell@1178 321 .ft \n(.f
tbell@1178 322 .ll \n(34u*1u/3u
tbell@1178 323 .if \n(.l<\n(81 .ll \n(81u
tbell@1178 324 .in 0
tbell@1178 325 usage(,usage)*, usage can be one of digitalSignature, nonRepudiation (contentCommitment), keyEncipherment, dataEncipherment, keyAgreement, keyCertSign, cRLSign, encipherOnly, decipherOnly. Usage can be abbreviated with the first few letters (say, dig for digitalSignature) or in camel\-case style (say, dS for digitalSignature, cRLS for cRLSign), as long as no ambiguity is found. Usage is case\-insensitive.
tbell@1178 326 .br
tbell@1178 327 .di
tbell@1178 328 .nr b| \n(dn
tbell@1178 329 .nr b- \n(dl
tbell@1178 330 ..
tbell@1178 331 .ec \
tbell@1178 332 .eo
tbell@1178 333 .am 81
tbell@1178 334 .br
tbell@1178 335 .di c+
tbell@1178 336 .35
tbell@1178 337 .ft \n(.f
tbell@1178 338 .ll \n(34u*1u/3u
tbell@1178 339 .if \n(.l<\n(81 .ll \n(81u
tbell@1178 340 .in 0
tbell@1178 341 usage(,usage)*, usage can be one of anyExtendedKeyUsage, serverAuth, clientAuth, codeSigning, emailProtection, timeStamping, OCSPSigning, or any OID string. Named usage can be abbreviated with the first few letters or in camel\-case style, as long as no ambiguity is found. Usage is case\-insensitive.
tbell@1178 342 .br
tbell@1178 343 .di
tbell@1178 344 .nr c| \n(dn
tbell@1178 345 .nr c- \n(dl
tbell@1178 346 ..
tbell@1178 347 .ec \
tbell@1178 348 .eo
tbell@1178 349 .am 80
tbell@1178 350 .br
tbell@1178 351 .di d+
tbell@1178 352 .35
tbell@1178 353 .ft \n(.f
tbell@1178 354 .ll \n(34u*1u/3u
tbell@1178 355 .if \n(.l<\n(80 .ll \n(80u
tbell@1178 356 .in 0
tbell@1178 357 SAN or SubjectAlternativeName
tbell@1178 358 .br
tbell@1178 359 .di
tbell@1178 360 .nr d| \n(dn
tbell@1178 361 .nr d- \n(dl
tbell@1178 362 ..
tbell@1178 363 .ec \
tbell@1178 364 .eo
tbell@1178 365 .am 81
tbell@1178 366 .br
tbell@1178 367 .di e+
tbell@1178 368 .35
tbell@1178 369 .ft \n(.f
tbell@1178 370 .ll \n(34u*1u/3u
tbell@1178 371 .if \n(.l<\n(81 .ll \n(81u
tbell@1178 372 .in 0
tbell@1178 373 type:value(,type:value)*, type can be EMAIL, URI, DNS, IP, or OID, value is the string format value for the type.
tbell@1178 374 .br
tbell@1178 375 .di
tbell@1178 376 .nr e| \n(dn
tbell@1178 377 .nr e- \n(dl
tbell@1178 378 ..
tbell@1178 379 .ec \
tbell@1178 380 .eo
tbell@1178 381 .am 80
tbell@1178 382 .br
tbell@1178 383 .di f+
tbell@1178 384 .35
tbell@1178 385 .ft \n(.f
tbell@1178 386 .ll \n(34u*1u/3u
tbell@1178 387 .if \n(.l<\n(80 .ll \n(80u
tbell@1178 388 .in 0
tbell@1178 389 IAN or IssuerAlternativeName
tbell@1178 390 .br
tbell@1178 391 .di
tbell@1178 392 .nr f| \n(dn
tbell@1178 393 .nr f- \n(dl
tbell@1178 394 ..
tbell@1178 395 .ec \
tbell@1178 396 .eo
tbell@1178 397 .am 81
tbell@1178 398 .br
tbell@1178 399 .di g+
tbell@1178 400 .35
tbell@1178 401 .ft \n(.f
tbell@1178 402 .ll \n(34u*1u/3u
tbell@1178 403 .if \n(.l<\n(81 .ll \n(81u
tbell@1178 404 .in 0
tbell@1178 405 same as SubjectAlternativeName
tbell@1178 406 .br
tbell@1178 407 .di
tbell@1178 408 .nr g| \n(dn
tbell@1178 409 .nr g- \n(dl
tbell@1178 410 ..
tbell@1178 411 .ec \
tbell@1178 412 .eo
tbell@1178 413 .am 81
tbell@1178 414 .br
tbell@1178 415 .di h+
tbell@1178 416 .35
tbell@1178 417 .ft \n(.f
tbell@1178 418 .ll \n(34u*1u/3u
tbell@1178 419 .if \n(.l<\n(81 .ll \n(81u
tbell@1178 420 .in 0
tbell@1178 421 method:location\-type:location\-value (,method:location\-type:location\-value)*, method can be "timeStamping", "caRepository" or any OID. location\-type and location\-value can be any type:value supported by the SubjectAlternativeName extension.
tbell@1178 422 .br
tbell@1178 423 .di
tbell@1178 424 .nr h| \n(dn
tbell@1178 425 .nr h- \n(dl
tbell@1178 426 ..
tbell@1178 427 .ec \
tbell@1178 428 .eo
tbell@1178 429 .am 80
tbell@1178 430 .br
tbell@1178 431 .di i+
tbell@1178 432 .35
tbell@1178 433 .ft \n(.f
tbell@1178 434 .ll \n(34u*1u/3u
tbell@1178 435 .if \n(.l<\n(80 .ll \n(80u
tbell@1178 436 .in 0
tbell@1178 437 AIA or AuthorityInfoAccess
tbell@1178 438 .br
tbell@1178 439 .di
tbell@1178 440 .nr i| \n(dn
tbell@1178 441 .nr i- \n(dl
tbell@1178 442 ..
tbell@1178 443 .ec \
tbell@1178 444 .eo
tbell@1178 445 .am 81
tbell@1178 446 .br
tbell@1178 447 .di j+
tbell@1178 448 .35
tbell@1178 449 .ft \n(.f
tbell@1178 450 .ll \n(34u*1u/3u
tbell@1178 451 .if \n(.l<\n(81 .ll \n(81u
tbell@1178 452 .in 0
tbell@1178 453 same as SubjectInfoAccess. method can be "ocsp","caIssuers" or any OID.
tbell@1178 454 .br
tbell@1178 455 .di
tbell@1178 456 .nr j| \n(dn
tbell@1178 457 .nr j- \n(dl
tbell@1178 458 ..
tbell@1178 459 .ec \
tbell@1178 460 .35
tbell@1178 461 .nf
tbell@1178 462 .ll \n(34u
tbell@1178 463 .nr 80 0
tbell@1178 464 .nr 38 \w\f3Name\fP
tbell@1178 465 .if \n(80<\n(38 .nr 80 \n(38
tbell@1178 466 .nr 38 \wBC or BasicConstraints
tbell@1178 467 .if \n(80<\n(38 .nr 80 \n(38
tbell@1178 468 .nr 38 \wKU or KeyUsage
tbell@1178 469 .if \n(80<\n(38 .nr 80 \n(38
tbell@1178 470 .nr 38 \wEKU or ExtendedkeyUsage
tbell@1178 471 .if \n(80<\n(38 .nr 80 \n(38
tbell@1178 472 .nr 38 \wSIA or SubjectInfoAccess
tbell@1178 473 .if \n(80<\n(38 .nr 80 \n(38
tbell@1178 474 .80
tbell@1178 475 .rm 80
tbell@1178 476 .nr 38 \n(d-
tbell@1178 477 .if \n(80<\n(38 .nr 80 \n(38
tbell@1178 478 .nr 38 \n(f-
tbell@1178 479 .if \n(80<\n(38 .nr 80 \n(38
tbell@1178 480 .nr 38 \n(i-
tbell@1178 481 .if \n(80<\n(38 .nr 80 \n(38
tbell@1178 482 .nr 81 0
tbell@1178 483 .nr 38 \w\f3Value\fP
tbell@1178 484 .if \n(81<\n(38 .nr 81 \n(38
tbell@1178 485 .81
tbell@1178 486 .rm 81
tbell@1178 487 .nr 38 \n(a-
tbell@1178 488 .if \n(81<\n(38 .nr 81 \n(38
tbell@1178 489 .nr 38 \n(b-
tbell@1178 490 .if \n(81<\n(38 .nr 81 \n(38
tbell@1178 491 .nr 38 \n(c-
tbell@1178 492 .if \n(81<\n(38 .nr 81 \n(38
tbell@1178 493 .nr 38 \n(e-
tbell@1178 494 .if \n(81<\n(38 .nr 81 \n(38
tbell@1178 495 .nr 38 \n(g-
tbell@1178 496 .if \n(81<\n(38 .nr 81 \n(38
tbell@1178 497 .nr 38 \n(h-
tbell@1178 498 .if \n(81<\n(38 .nr 81 \n(38
tbell@1178 499 .nr 38 \n(j-
tbell@1178 500 .if \n(81<\n(38 .nr 81 \n(38
tbell@1178 501 .35
tbell@1178 502 .nf
tbell@1178 503 .ll \n(34u
tbell@1178 504 .nr 38 1n
tbell@1178 505 .nr 79 0
tbell@1178 506 .nr 40 \n(79+(0*\n(38)
tbell@1178 507 .nr 80 +\n(40
tbell@1178 508 .nr 41 \n(80+(3*\n(38)
tbell@1178 509 .nr 81 +\n(41
tbell@1178 510 .nr TW \n(81
bpatel@4176 511 .if t .if \n(TW>\n(.li .tm Table at line 319 file Input is too wide - \n(TW units
tbell@1178 512 .fc  
tbell@1178 513 .nr #T 0-1
tbell@1178 514 .nr #a 0-1
tbell@1178 515 .eo
tbell@1178 516 .de T#
tbell@1178 517 .ds #d .d
tbell@1178 518 .if \(ts\n(.z\(ts\(ts .ds #d nl
tbell@1178 519 .mk ##
tbell@1178 520 .nr ## -1v
tbell@1178 521 .ls 1
tbell@1178 522 .ls
tbell@1178 523 ..
tbell@1178 524 .ec
tbell@1178 525 .ta \n(80u \n(81u
tbell@1178 526 .nr 31 \n(.f
tbell@1178 527 .nr 35 1m
tbell@1178 528 \&\h'|\n(40u'\f3Name\fP\h'|\n(41u'\f3Value\fP
tbell@1178 529 .ne \n(a|u+\n(.Vu
tbell@1178 530 .if (\n(a|+\n(#^-1v)>\n(#- .nr #- +(\n(a|+\n(#^-\n(#--1v)
tbell@1178 531 .ta \n(80u \n(81u
tbell@1178 532 .nr 31 \n(.f
tbell@1178 533 .nr 35 1m
tbell@1178 534 \&\h'|\n(40u'BC or BasicConstraints\h'|\n(41u'
tbell@1178 535 .mk ##
tbell@1178 536 .nr 31 \n(##
tbell@1178 537 .sp |\n(##u-1v
tbell@1178 538 .nr 37 \n(41u
tbell@1178 539 .in +\n(37u
tbell@1178 540 .a+
tbell@1178 541 .in -\n(37u
tbell@1178 542 .mk 32
tbell@1178 543 .if \n(32>\n(31 .nr 31 \n(32
tbell@1178 544 .sp |\n(31u
tbell@1178 545 .ne \n(b|u+\n(.Vu
tbell@1178 546 .if (\n(b|+\n(#^-1v)>\n(#- .nr #- +(\n(b|+\n(#^-\n(#--1v)
tbell@1178 547 .ta \n(80u \n(81u
tbell@1178 548 .nr 31 \n(.f
tbell@1178 549 .nr 35 1m
tbell@1178 550 \&\h'|\n(40u'KU or KeyUsage\h'|\n(41u'
tbell@1178 551 .mk ##
tbell@1178 552 .nr 31 \n(##
tbell@1178 553 .sp |\n(##u-1v
tbell@1178 554 .nr 37 \n(41u
tbell@1178 555 .in +\n(37u
tbell@1178 556 .b+
tbell@1178 557 .in -\n(37u
tbell@1178 558 .mk 32
tbell@1178 559 .if \n(32>\n(31 .nr 31 \n(32
tbell@1178 560 .sp |\n(31u
tbell@1178 561 .ne \n(c|u+\n(.Vu
tbell@1178 562 .if (\n(c|+\n(#^-1v)>\n(#- .nr #- +(\n(c|+\n(#^-\n(#--1v)
tbell@1178 563 .ta \n(80u \n(81u
tbell@1178 564 .nr 31 \n(.f
tbell@1178 565 .nr 35 1m
tbell@1178 566 \&\h'|\n(40u'EKU or ExtendedkeyUsage\h'|\n(41u'
tbell@1178 567 .mk ##
tbell@1178 568 .nr 31 \n(##
tbell@1178 569 .sp |\n(##u-1v
tbell@1178 570 .nr 37 \n(41u
tbell@1178 571 .in +\n(37u
tbell@1178 572 .c+
tbell@1178 573 .in -\n(37u
tbell@1178 574 .mk 32
tbell@1178 575 .if \n(32>\n(31 .nr 31 \n(32
tbell@1178 576 .sp |\n(31u
tbell@1178 577 .ne \n(d|u+\n(.Vu
tbell@1178 578 .ne \n(e|u+\n(.Vu
tbell@1178 579 .if (\n(d|+\n(#^-1v)>\n(#- .nr #- +(\n(d|+\n(#^-\n(#--1v)
tbell@1178 580 .if (\n(e|+\n(#^-1v)>\n(#- .nr #- +(\n(e|+\n(#^-\n(#--1v)
tbell@1178 581 .ta \n(80u \n(81u
tbell@1178 582 .nr 31 \n(.f
tbell@1178 583 .nr 35 1m
tbell@1178 584 \&\h'|\n(40u'\h'|\n(41u'
tbell@1178 585 .mk ##
tbell@1178 586 .nr 31 \n(##
tbell@1178 587 .sp |\n(##u-1v
tbell@1178 588 .nr 37 \n(40u
tbell@1178 589 .in +\n(37u
tbell@1178 590 .d+
tbell@1178 591 .in -\n(37u
tbell@1178 592 .mk 32
tbell@1178 593 .if \n(32>\n(31 .nr 31 \n(32
tbell@1178 594 .sp |\n(##u-1v
tbell@1178 595 .nr 37 \n(41u
tbell@1178 596 .in +\n(37u
tbell@1178 597 .e+
tbell@1178 598 .in -\n(37u
tbell@1178 599 .mk 32
tbell@1178 600 .if \n(32>\n(31 .nr 31 \n(32
tbell@1178 601 .sp |\n(31u
tbell@1178 602 .ne \n(f|u+\n(.Vu
tbell@1178 603 .ne \n(g|u+\n(.Vu
tbell@1178 604 .if (\n(f|+\n(#^-1v)>\n(#- .nr #- +(\n(f|+\n(#^-\n(#--1v)
tbell@1178 605 .if (\n(g|+\n(#^-1v)>\n(#- .nr #- +(\n(g|+\n(#^-\n(#--1v)
tbell@1178 606 .ta \n(80u \n(81u
tbell@1178 607 .nr 31 \n(.f
tbell@1178 608 .nr 35 1m
tbell@1178 609 \&\h'|\n(40u'\h'|\n(41u'
tbell@1178 610 .mk ##
tbell@1178 611 .nr 31 \n(##
tbell@1178 612 .sp |\n(##u-1v
tbell@1178 613 .nr 37 \n(40u
tbell@1178 614 .in +\n(37u
tbell@1178 615 .f+
tbell@1178 616 .in -\n(37u
tbell@1178 617 .mk 32
tbell@1178 618 .if \n(32>\n(31 .nr 31 \n(32
tbell@1178 619 .sp |\n(##u-1v
tbell@1178 620 .nr 37 \n(41u
tbell@1178 621 .in +\n(37u
tbell@1178 622 .g+
tbell@1178 623 .in -\n(37u
tbell@1178 624 .mk 32
tbell@1178 625 .if \n(32>\n(31 .nr 31 \n(32
tbell@1178 626 .sp |\n(31u
tbell@1178 627 .ne \n(h|u+\n(.Vu
tbell@1178 628 .if (\n(h|+\n(#^-1v)>\n(#- .nr #- +(\n(h|+\n(#^-\n(#--1v)
tbell@1178 629 .ta \n(80u \n(81u
tbell@1178 630 .nr 31 \n(.f
tbell@1178 631 .nr 35 1m
tbell@1178 632 \&\h'|\n(40u'SIA or SubjectInfoAccess\h'|\n(41u'
tbell@1178 633 .mk ##
tbell@1178 634 .nr 31 \n(##
tbell@1178 635 .sp |\n(##u-1v
tbell@1178 636 .nr 37 \n(41u
tbell@1178 637 .in +\n(37u
tbell@1178 638 .h+
tbell@1178 639 .in -\n(37u
tbell@1178 640 .mk 32
tbell@1178 641 .if \n(32>\n(31 .nr 31 \n(32
tbell@1178 642 .sp |\n(31u
tbell@1178 643 .ne \n(i|u+\n(.Vu
tbell@1178 644 .ne \n(j|u+\n(.Vu
tbell@1178 645 .if (\n(i|+\n(#^-1v)>\n(#- .nr #- +(\n(i|+\n(#^-\n(#--1v)
tbell@1178 646 .if (\n(j|+\n(#^-1v)>\n(#- .nr #- +(\n(j|+\n(#^-\n(#--1v)
tbell@1178 647 .ta \n(80u \n(81u
tbell@1178 648 .nr 31 \n(.f
tbell@1178 649 .nr 35 1m
tbell@1178 650 \&\h'|\n(40u'\h'|\n(41u'
tbell@1178 651 .mk ##
tbell@1178 652 .nr 31 \n(##
tbell@1178 653 .sp |\n(##u-1v
tbell@1178 654 .nr 37 \n(40u
tbell@1178 655 .in +\n(37u
tbell@1178 656 .i+
tbell@1178 657 .in -\n(37u
tbell@1178 658 .mk 32
tbell@1178 659 .if \n(32>\n(31 .nr 31 \n(32
tbell@1178 660 .sp |\n(##u-1v
tbell@1178 661 .nr 37 \n(41u
tbell@1178 662 .in +\n(37u
tbell@1178 663 .j+
tbell@1178 664 .in -\n(37u
tbell@1178 665 .mk 32
tbell@1178 666 .if \n(32>\n(31 .nr 31 \n(32
tbell@1178 667 .sp |\n(31u
tbell@1178 668 .fc
tbell@1178 669 .nr T. 1
tbell@1178 670 .T# 1
tbell@1178 671 .35
tbell@1178 672 .rm a+
tbell@1178 673 .rm b+
tbell@1178 674 .rm c+
tbell@1178 675 .rm d+
tbell@1178 676 .rm e+
tbell@1178 677 .rm f+
tbell@1178 678 .rm g+
tbell@1178 679 .rm h+
tbell@1178 680 .rm i+
tbell@1178 681 .rm j+
bpatel@4900 682 .TE
tbell@1178 683 .if \n-(b.=0 .nr c. \n(.c-\n(d.-38
tbell@1178 684
tbell@1178 685 .LP
tbell@1178 686 .LP
bpatel@4900 687 For name as OID, value is the HEX dumped DER encoding of the extnValue for the extension excluding the OCTET STRING type and length bytes. Any extra character other than standard HEX numbers (0\-9, a\-f, A\-F) are ignored in the HEX string. Therefore, both \f2"01:02:03:04"\fP and \f2"01020304"\fP are accepted as identical values. If there is no value, the extension has an empty value field then.
tbell@1178 688 .LP
tbell@1178 689 .LP
bpatel@4176 690 A special name \f2'honored'\fP, used in \f2\-gencert\fP only, denotes how the extensions included in the certificate request should be honored. The value for this name is a comma separated list of \f2"all"\fP (all requested extensions are honored), \f2"name{:[critical|non\-critical]}"\fP (the named extension is honored, but using a different isCritical attribute) and \f2"\-name"\fP (used with all, denotes an exception). Requested extensions are not honored by default.
tbell@1178 691 .LP
tbell@1178 692 .LP
tbell@1178 693 If, besides the \-ext honored option, another named or OID \-ext option is provided, this extension will be added to those already honored. However, if this name (or OID) also appears in the honored value, its value and criticality overrides the one in the request.
tbell@1178 694 .LP
tbell@1178 695 .LP
tbell@1178 696 The subjectKeyIdentifier extension is always created. For non self\-signed certificates, the authorityKeyIdentifier is always created.
tbell@1178 697 .LP
bpatel@2509 698 .LP
bpatel@2509 699 \f3Note:\fP Users should be aware that some combinations of extensions (and other certificate fields) may not conform to the Internet standard. See Warning Regarding Certificate Conformance for details.
bpatel@2509 700 .LP
duke@0 701 .SH "COMMANDS"
duke@0 702 .LP
duke@0 703 .SS
duke@0 704 Creating or Adding Data to the Keystore
duke@0 705 .LP
duke@0 706 .RS 3
bpatel@4176 707 .TP 3
bpatel@4176 708 \-gencert {\-rfc} {\-infile infile} {\-outfile outfile} {\-alias alias} {\-sigalg sigalg} {\-dname dname} {\-startdate startdate {\-ext ext}* {\-validity valDays} [\-keypass keypass] {\-keystore keystore} [\-storepass storepass] {\-storetype storetype} {\-providername provider_name} {\-providerClass provider_class_name {\-providerArg provider_arg}} {\-v} {\-protected} {\-Jjavaoption}
duke@0 709 .LP
bpatel@4176 710 Generates a certificate as a response to a certificate request file (which can be created by the \f2keytool \-certreq\fP command). The command reads the request from \f2infile\fP (if omitted, from the standard input), signs it using alias's private key, and output the X.509 certificate into \f2outfile\fP (if omitted, to the standard output). If \f2\-rfc\fP is specified, output format is BASE64\-encoded PEM; otherwise, a binary DER is created.
tbell@1178 711 .LP
bpatel@4176 712 \f2sigalg\fP specifies the algorithm that should be used to sign the certificate. \f2startdate\fP is the start time/date that the certificate is valid. \f2valDays\fP tells the number of days for which the certificate should be considered valid.
tbell@1178 713 .LP
bpatel@2509 714 If \f2dname\fP is provided, it's used as the subject of the generated certificate. Otherwise, the one from the certificate request is used.
bpatel@2509 715 .LP
bpatel@4176 716 \f2ext\fP shows what X.509 extensions will be embedded in the certificate. Read Common Options for the grammar of \f2\-ext\fP.
bpatel@4176 717 .LP
bpatel@4176 718 The \f2\-gencert\fP command enables you to create certificate chains. The following example creates a certificate, \f2e1\fP, that contains three certificates in its certificate chain.
bpatel@4176 719 .LP
bpatel@4176 720 The following commands creates four key pairs named \f2ca\fP, \f2ca1\fP, \f2ca2\fP, and \f2e1\fP:
bpatel@4176 721 .nf
bpatel@4176 722 \f3
bpatel@4176 723 .fl
bpatel@4176 724 keytool \-alias ca \-dname CN=CA \-genkeypair
bpatel@4176 725 .fl
bpatel@4176 726 keytool \-alias ca1 \-dname CN=CA \-genkeypair
bpatel@4176 727 .fl
bpatel@4176 728 keytool \-alias ca2 \-dname CN=CA \-genkeypair
bpatel@4176 729 .fl
bpatel@4176 730 keytool \-alias e1 \-dname CN=E1 \-genkeypair
bpatel@4176 731 .fl
bpatel@4176 732 \fP
bpatel@4176 733 .fi
bpatel@4176 734 .LP
bpatel@4176 735 The following two commands create a chain of signed certificates; \f2ca\fP signs ca1 and \f2ca1 signs ca2\fP, all of which are self\-issued:
bpatel@4176 736 .nf
bpatel@4176 737 \f3
bpatel@4176 738 .fl
bpatel@4176 739 keytool \-alias ca1 \-certreq | keytool \-alias ca \-gencert \-ext san=dns:ca1 | keytool \-alias ca1 \-importcert
bpatel@4176 740 .fl
bpatel@4176 741 keytool \-alias ca2 \-certreq | $KT \-alias ca1 \-gencert \-ext san=dns:ca2 | $KT \-alias ca2 \-importcert
bpatel@4176 742 .fl
bpatel@4176 743 \fP
bpatel@4176 744 .fi
bpatel@4176 745 .LP
bpatel@4176 746 The following command creates the certificate \f2e1\fP and stores it in the file \f2e1.cert\fP, which is signed by \f2ca2\fP. As a result, \f2e1\fP should contain \f2ca\fP, \f2ca1\fP, and \f2ca2\fP in its certificate chain:
bpatel@4176 747 .nf
bpatel@4176 748 \f3
bpatel@4176 749 .fl
bpatel@4176 750 keytool \-alias e1 \-certreq | keytool \-alias ca2 \-gencert > e1.cert
bpatel@4176 751 .fl
bpatel@4176 752 \fP
bpatel@4176 753 .fi
tbell@1178 754 .TP 3
bpatel@4176 755 \-genkeypair {\-alias alias} {\-keyalg keyalg} {\-keysize keysize} {\-sigalg sigalg} [\-dname dname] [\-keypass keypass] {\-startdate value} {\-ext ext}* {\-validity valDays} {\-storetype storetype} {\-keystore keystore} [\-storepass storepass] {\-providerClass provider_class_name {\-providerArg provider_arg}} {\-v} {\-protected} {\-Jjavaoption}
duke@0 756 .LP
duke@0 757 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 \f2alias\fP.
duke@0 758 .LP
duke@0 759 \f2keyalg\fP specifies the algorithm to be used to generate the key pair, and \f2keysize\fP specifies the size of each key to be generated. \f2sigalg\fP specifies the algorithm that should be used to sign the self\-signed certificate; this algorithm must be compatible with \f2keyalg\fP.
duke@0 760 .LP
duke@0 761 \f2dname\fP specifies the X.500 Distinguished Name to be associated with \f2alias\fP, and is used as the \f2issuer\fP and \f2subject\fP fields in the self\-signed certificate. If no distinguished name is provided at the command line, the user will be prompted for one.
duke@0 762 .LP
duke@0 763 \f2keypass\fP is a password used to protect the private key of the generated key pair. If no password is provided, the user is prompted for it. If you press RETURN at the prompt, the key password is set to the same password as that used for the keystore. \f2keypass\fP must be at least 6 characters long.
duke@0 764 .LP
tbell@1178 765 \f2startdate\fP specifies the issue time of the certificate, also known as the "Not Before" value of the X.509 certificate's Validity field.
duke@0 766 .LP
bpatel@4176 767 The option value can be set in one of these two forms:
tbell@1178 768 .RS 3
tbell@1178 769 .TP 3
tbell@1178 770 1.
bpatel@4176 771 ([+\-]\f2nnn\fP[ymdHMS])+
tbell@1178 772 .TP 3
tbell@1178 773 2.
bpatel@4176 774 [yyyy/mm/dd] [HH:MM:SS]
bpatel@4176 775 .RE
tbell@1178 776 .LP
bpatel@4176 777 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 sub values. Inside each sub value, the plus sign ("+") means shifting forward, and the minus sign ("\-") means shifting backward. The time to be shifted is \f2nnn\fP units of years, months, days, hours, minutes, or seconds (denoted by a single character of "y", "m", "d", "H", "M", or "S" respectively). The exact value of the issue time is calculated using the \f2java.util.GregorianCalendar.add(int field, int amount)\fP method on each sub value, from left to right. For example, by specifying \f2"\-startdate \-1y+1m\-1d"\fP, the issue time will be:
tbell@1178 778 .nf
tbell@1178 779 \f3
tbell@1178 780 .fl
tbell@1178 781 Calendar c = new GregorianCalendar();
tbell@1178 782 .fl
tbell@1178 783 c.add(Calendar.YEAR, \-1);
tbell@1178 784 .fl
tbell@1178 785 c.add(Calendar.MONTH, 1);
tbell@1178 786 .fl
tbell@1178 787 c.add(Calendar.DATE, \-1);
tbell@1178 788 .fl
tbell@1178 789 return c.getTime()
tbell@1178 790 .fl
tbell@1178 791 \fP
tbell@1178 792 .fi
tbell@1178 793 .LP
bpatel@4176 794 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 may provide only one part, which means the other part is the same as the current date (or time). User must provide the exact number of digits as shown in the format definition (padding with 0 if 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.
tbell@1178 795 .LP
bpatel@4176 796 When the option is not provided, the start date is the current time. The option can be provided at most once.
tbell@1178 797 .LP
tbell@1178 798 \f2valDays\fP specifies the number of days (starting at the date specified by \f2\-startdate\fP, or the current date if \f2\-startdate\fP is not specified) for which the certificate should be considered valid.
tbell@1178 799 .LP
tbell@1178 800 This command was named \f2\-genkey\fP in previous releases. This old name is still supported in this release and will be supported in future releases, but for clarity the new name, \f2\-genkeypair\fP, is preferred going forward.
duke@0 801 .TP 3
duke@0 802 \-genseckey {\-alias alias} {\-keyalg keyalg} {\-keysize keysize} [\-keypass keypass] {\-storetype storetype} {\-keystore keystore} [\-storepass storepass] {\-providerClass provider_class_name {\-providerArg provider_arg}} {\-v} {\-protected} {\-Jjavaoption}
duke@0 803 .LP
duke@0 804 Generates a secret key and stores it in a new \f2KeyStore.SecretKeyEntry\fP identified by \f2alias\fP.
duke@0 805 .LP
duke@0 806 \f2keyalg\fP specifies the algorithm to be used to generate the secret key, and \f2keysize\fP specifies the size of the key to be generated. \f2keypass\fP is a password used to protect the secret key. If no password is provided, the user is prompted for it. If you press RETURN at the prompt, the key password is set to the same password as that used for the keystore. \f2keypass\fP must be at least 6 characters long.
duke@0 807 .TP 3
duke@0 808 \-importcert {\-alias alias} {\-file cert_file} [\-keypass keypass] {\-noprompt} {\-trustcacerts} {\-storetype storetype} {\-keystore keystore} [\-storepass storepass] {\-providerName provider_name} {\-providerClass provider_class_name {\-providerArg provider_arg}} {\-v} {\-protected} {\-Jjavaoption}
duke@0 809 .LP
tbell@1178 810 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 \f2cert_file\fP, and stores it in the keystore entry identified by \f2alias\fP. If no file is given, the certificate or certificate chain is read from stdin.
duke@0 811 .LP
duke@0 812 \f3keytool\fP 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 "\-\-\-\-\-BEGIN", and bounded at the end by a string that starts with "\-\-\-\-\-END".
duke@0 813 .LP
duke@0 814 You import a certificate for two reasons:
duke@0 815 .RS 3
duke@0 816 .TP 3
duke@0 817 1.
duke@0 818 to add it to the list of trusted certificates, or
duke@0 819 .TP 3
duke@0 820 2.
duke@0 821 to import a certificate reply received from a CA as the result of submitting a Certificate Signing Request (see the \-certreq command) to that CA.
duke@0 822 .RE
duke@0 823 .LP
duke@0 824 Which type of import is intended is indicated by the value of the \f2\-alias\fP option:
duke@0 825 .RS 3
duke@0 826 .TP 3
duke@0 827 1.
duke@0 828 \f3If the alias does not point to a key entry\fP, then \f3keytool\fP 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 \f3keytool\fP outputs an error, since there is already a trusted certificate for that alias, and does not import the certificate.
duke@0 829 .TP 3
duke@0 830 2.
duke@0 831 \f3If the alias points to a key entry\fP, then \f3keytool\fP assumes you are importing a certificate reply.
duke@0 832 .RE
duke@0 833 \f3Importing a New Trusted Certificate\fP
duke@0 834 .LP
bpatel@4176 835 Before adding the certificate to the keystore, \f3keytool\fP tries to verify 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.
duke@0 836 .LP
bpatel@4176 837 If the \f2\-trustcacerts\fP option has been specified, additional certificates are considered for the chain of trust, namely the certificates in a file named "cacerts".
duke@0 838 .LP
bpatel@4176 839 If \f3keytool\fP fails to establish a trust path from the certificate to be imported up to a self\-signed certificate (either from the keystore or the "cacerts" file), the certificate information is printed out, and the user is prompted to verify it, e.g., by comparing the displayed certificate fingerprints with the fingerprints obtained from some other (trusted) source of information, which might be the certificate owner himself/herself. Be very careful to ensure the certificate is valid prior to importing it as a "trusted" certificate! \-\- see WARNING Regarding Importing Trusted Certificates. The user then has the option of aborting the import operation. If the \f2\-noprompt\fP option is given, however, there will be no interaction with the user.
bpatel@4176 840 \f3Importing a Certificate Reply\fP
duke@0 841 .LP
bpatel@4176 842 When importing a certificate reply, the certificate reply is validated using trusted certificates from the keystore, and optionally using the certificates configured in the "cacerts" keystore file (if the \f2\-trustcacerts\fP option was specified).
duke@0 843 .LP
bpatel@4176 844 The methods of determining whether the certificate reply is trusted are described in the following:
duke@0 845 .RS 3
duke@0 846 .TP 2
duke@0 847 o
duke@0 848 \f3If the reply is a single X.509 certificate\fP, \f3keytool\fP 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 used to authenticate the certificate reply form the new certificate chain of \f2alias\fP. If a trust chain cannot be established, the certificate reply is not imported. In this case, \f3keytool\fP does not print out the certificate and prompt the user to verify it, because it is very hard (if not impossible) for a user to determine the authenticity of the certificate reply.
duke@0 849 .TP 2
duke@0 850 o
tbell@1178 851 \f3If the reply is a PKCS#7 formatted certificate chain or a sequence of X.509 certificates\fP, 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 \f2\-trustcacerts\fP option was specified, \f3keytool\fP will attempt to match it with any of the trusted certificates in the keystore or the "cacerts" keystore file. If the chain does not end with a self\-signed root CA certificate and the \f2\-trustcacerts\fP option was specified, \f3keytool\fP will try to find one from the trusted certificates in the keystore or the "cacerts" keystore file and add it to the end of the chain. If the certificate is not found and \f2\-noprompt\fP option is not specified, the information of the last certificate in the chain is printed out, and the user is prompted to verify it.
duke@0 852 .RE
duke@0 853 .LP
bpatel@4176 854 If the public key in the certificate reply matches the user's public key already stored with under \f2alias\fP, the old certificate chain is replaced with the new certificate chain in the reply. The old chain can only be replaced if a valid \f2keypass\fP, 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.
duke@0 855 .LP
duke@0 856 This command was named \f2\-import\fP in previous releases. This old name is still supported in this release and will be supported in future releases, but for clarify the new name, \f2\-importcert\fP, is preferred going forward.
duke@0 857 .TP 3
duke@0 858 \-importkeystore \-srckeystore srckeystore \-destkeystore destkeystore {\-srcstoretype srcstoretype} {\-deststoretype deststoretype} [\-srcstorepass srcstorepass] [\-deststorepass deststorepass] {\-srcprotected} {\-destprotected} {\-srcalias srcalias {\-destalias destalias} [\-srckeypass srckeypass] [\-destkeypass destkeypass] } {\-noprompt} {\-srcProviderName src_provider_name} {\-destProviderName dest_provider_name} {\-providerClass provider_class_name {\-providerArg provider_arg}} {\-v} {\-protected} {\-Jjavaoption}
duke@0 859 .LP
duke@0 860 Imports a single entry or all entries from a source keystore to a destination keystore.
duke@0 861 .LP
duke@0 862 When the \f2srcalias\fP 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 \f2destalias\fP, then \f2srcalias\fP is used as the destination alias. If the source entry is protected by a password, \f2srckeypass\fP will be used to recover the entry. If \f2srckeypass\fP is not provided, then \f3keytool\fP will attempt to use \f2srcstorepass\fP to recover the entry. If \f2srcstorepass\fP is either not provided or is incorrect, the user will be prompted for a password. The destination entry will be protected using \f2destkeypass\fP. If \f2destkeypass\fP is not provided, the destination entry will be protected with the source entry password.
duke@0 863 .LP
duke@0 864 If the \f2srcalias\fP option is not provided, then all entries in the source keystore are imported into the destination keystore. Each destination entry will be stored under the alias from the source entry. If the source entry is protected by a password, \f2srcstorepass\fP will be used to recover the entry. If \f2srcstorepass\fP is either not provided or is incorrect, the user will be 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, the user will be prompted whether to skip the entry and continue, or to quit. The destination entry will be protected with the source entry password.
duke@0 865 .LP
duke@0 866 If the destination alias already exists in the destination keystore, the user is prompted to either overwrite the entry, or to create a new entry under a different alias name.
duke@0 867 .LP
duke@0 868 Note that if \f2\-noprompt\fP is provided, the user will not be prompted for a new destination alias. Existing entries will automatically be overwritten with the destination alias name. Finally, entries that can not be imported are automatically skipped and a warning is output.
tbell@1178 869 .TP 3
tbell@1178 870 \-printcertreq {\-file file}
tbell@1178 871 .LP
tbell@1178 872 Prints the content of a PKCS #10 format certificate request, which can be generated by the keytool \-certreq command. The command reads the request from file; if omitted, from the standard input.
duke@0 873 .RE
bpatel@4176 874
bpatel@4176 875 .LP
duke@0 876 .SS
duke@0 877 Exporting Data
duke@0 878 .LP
duke@0 879 .RS 3
duke@0 880 .TP 3
bpatel@2509 881 \-certreq {\-alias alias} {\-dname dname} {\-sigalg sigalg} {\-file certreq_file} [\-keypass keypass] {\-storetype storetype} {\-keystore keystore} [\-storepass storepass] {\-providerName provider_name} {\-providerClass provider_class_name {\-providerArg provider_arg}} {\-v} {\-protected} {\-Jjavaoption}
duke@0 882 .LP
duke@0 883 Generates a Certificate Signing Request (CSR), using the PKCS#10 format.
duke@0 884 .LP
duke@0 885 A CSR is intended to be sent to a certificate authority (CA). The CA will authenticate 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.
duke@0 886 .LP
bpatel@2509 887 The private key associated with \f2alias\fP is used to create the PKCS#10 certificate request. In order to access the private key, the appropriate password must be provided, since private keys are protected in the keystore with a password. If \f2keypass\fP is not provided at the command line, and is different from the password used to protect the integrity of the keystore, the user is prompted for it. If dname is provided, it's used as the subject in the CSR. Otherwise, the X.500 Distinguished Name associated with alias is used.
duke@0 888 .LP
duke@0 889 \f2sigalg\fP specifies the algorithm that should be used to sign the CSR.
duke@0 890 .LP
duke@0 891 The CSR is stored in the file \f2certreq_file\fP. If no file is given, the CSR is output to stdout.
duke@0 892 .LP
duke@0 893 Use the \f2importcert\fP command to import the response from the CA.
duke@0 894 .TP 3
duke@0 895 \-exportcert {\-alias alias} {\-file cert_file} {\-storetype storetype} {\-keystore keystore} [\-storepass storepass] {\-providerName provider_name} {\-providerClass provider_class_name {\-providerArg provider_arg}} {\-rfc} {\-v} {\-protected} {\-Jjavaoption}
duke@0 896 .LP
duke@0 897 Reads (from the keystore) the certificate associated with \f2alias\fP, and stores it in the file \f2cert_file\fP.
duke@0 898 .LP
duke@0 899 If no file is given, the certificate is output to stdout.
duke@0 900 .LP
duke@0 901 The certificate is by default output in binary encoding, but will instead be output in the printable encoding format, as defined by the Internet RFC 1421 standard, if the \f2\-rfc\fP option is specified.
duke@0 902 .LP
duke@0 903 If \f2alias\fP refers to a trusted certificate, that certificate is output. Otherwise, \f2alias\fP 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 \f2alias\fP.
duke@0 904 .LP
duke@0 905 This command was named \f2\-export\fP in previous releases. This old name is still supported in this release and will be supported in future releases, but for clarify the new name, \f2\-exportcert\fP, is preferred going forward.
duke@0 906 .RE
duke@0 907
duke@0 908 .LP
duke@0 909 .SS
duke@0 910 Displaying Data
duke@0 911 .LP
duke@0 912 .RS 3
duke@0 913 .TP 3
duke@0 914 \-list {\-alias alias} {\-storetype storetype} {\-keystore keystore} [\-storepass storepass] {\-providerName provider_name} {\-providerClass provider_class_name {\-providerArg provider_arg}} {\-v | \-rfc} {\-protected} {\-Jjavaoption}
duke@0 915 .LP
duke@0 916 Prints (to stdout) the contents of the keystore entry identified by \f2alias\fP. If no alias is specified, the contents of the entire keystore are printed.
duke@0 917 .LP
tbell@1178 918 This command by default prints the SHA1 fingerprint of a certificate. If the \f2\-v\fP option is specified, the certificate is printed in human\-readable format, with additional information such as the owner, issuer, serial number, and any extensions. If the \f2\-rfc\fP option is specified, certificate contents are printed using the printable encoding format, as defined by the Internet RFC 1421 standard
duke@0 919 .LP
duke@0 920 You cannot specify both \f2\-v\fP and \f2\-rfc\fP.
duke@0 921 .TP 3
bpatel@4176 922 \-printcert {\-file cert_file | \-sslserver host[:port]} {\-jarfile JAR_file {\-rfc} {\-v} {\-Jjavaoption}
duke@0 923 .LP
bpatel@4176 924 Reads the certificate from the file \f2cert_file\fP, the SSL server located at \f2host:port\fP, or the signed JAR file \f2JAR_file\fP (with the option \f2\-jarfile\fP and prints its contents in a human\-readable format. When no port is specified, the standard HTTPS port 443 is assumed. Note that \f2\-sslserver\fP and \f2\-file\fP options cannot be provided at the same time. Otherwise, an error is reported. If neither option is given, the certificate is read from stdin.
duke@0 925 .LP
tbell@1178 926 If \f2\-rfc\fP is specified, keytool prints the certificate in PEM mode as defined by the Internet RFC 1421 standard.
duke@0 927 .LP
tbell@1178 928 If the certificate is read from a file or stdin, it may be either binary encoded or in printable encoding format, as defined by the Internet RFC 1421 standard
tbell@1178 929 .LP
bpatel@4176 930 If the SSL server is behind a firewall, \f2\-J\-Dhttps.proxyHost=proxyhost\fP and \f2\-J\-Dhttps.proxyPort=proxyport\fP can be specified on the command line for proxy tunneling. See the
bpatel@4176 931 .na
bpatel@4176 932 \f2JSSE Reference Guide\fP @
bpatel@4176 933 .fi
bpatel@4900 934 http://docs.oracle.com/javase/7/docs/technotes/guides/security/jsse/JSSERefGuide.html for more information.
bpatel@4176 935 .LP
bpatel@4176 936 \f3Note\fP: This option can be used independently of a keystore.
bpatel@4176 937 .TP 3
bpatel@4176 938 \-printcrl \-file crl_ {\-v}
bpatel@4176 939 .LP
bpatel@4176 940 Reads the certificate revocation list (CRL) from the file \f2crl_file\fP.
bpatel@4176 941 .LP
bpatel@4176 942 A Certificate Revocation List (CRL) is a list of digital certificates which have been revoked by the Certificate Authority (CA) that issued them. The CA generates \f2crl_file\fP.
tbell@1178 943 .LP
tbell@1178 944 \f3Note\fP: This option can be used independently of a keystore.
duke@0 945 .RE
duke@0 946
duke@0 947 .LP
duke@0 948 .SS
duke@0 949 Managing the Keystore
duke@0 950 .LP
duke@0 951 .RS 3
duke@0 952 .TP 3
duke@0 953 \-storepasswd [\-new new_storepass] {\-storetype storetype} {\-keystore keystore} [\-storepass storepass] {\-providerName provider_name} {\-providerClass provider_class_name {\-providerArg provider_arg}} {\-v} {\-Jjavaoption}
duke@0 954 .LP
duke@0 955 Changes the password used to protect the integrity of the keystore contents. The new password is \f2new_storepass\fP, which must be at least 6 characters long.
duke@0 956 .TP 3
duke@0 957 \-keypasswd {\-alias alias} [\-keypass old_keypass] [\-new new_keypass] {\-storetype storetype} {\-keystore keystore} [\-storepass storepass] {\-providerName provider_name} {\-providerClass provider_class_name {\-providerArg provider_arg}} {\-v} {\-Jjavaoption}
duke@0 958 .LP
duke@0 959 Changes the password under which the private/secret key identified by \f2alias\fP is protected, from \f2old_keypass\fP to \f2new_keypass\fP, which must be at least 6 characters long.
duke@0 960 .LP
duke@0 961 If the \f2\-keypass\fP option is not provided at the command line, and the key password is different from the keystore password, the user is prompted for it.
duke@0 962 .LP
duke@0 963 If the \f2\-new\fP option is not provided at the command line, the user is prompted for it.
duke@0 964 .TP 3
duke@0 965 \-delete [\-alias alias] {\-storetype storetype} {\-keystore keystore} [\-storepass storepass] {\-providerName provider_name} {\-providerClass provider_class_name {\-providerArg provider_arg}} {\-v} {\-protected} {\-Jjavaoption}
duke@0 966 .LP
duke@0 967 Deletes from the keystore the entry identified by \f2alias\fP. The user is prompted for the alias, if no alias is provided at the command line.
duke@0 968 .TP 3
duke@0 969 \-changealias {\-alias alias} [\-destalias destalias] [\-keypass keypass] {\-storetype storetype} {\-keystore keystore} [\-storepass storepass] {\-providerName provider_name} {\-providerClass provider_class_name {\-providerArg provider_arg}} {\-v} {\-protected} {\-Jjavaoption}
duke@0 970 .LP
duke@0 971 Move an existing keystore entry from the specified \f2alias\fP to a new alias, \f2destalias\fP. If no destination alias is provided, the command will prompt for one. If the original entry is protected with an entry password, the password can be supplied via the "\-keypass" option. If no key password is provided, the \f2storepass\fP (if given) will be attempted first. If that attempt fails, the user will be prompted for a password.
duke@0 972 .RE
duke@0 973
duke@0 974 .LP
duke@0 975 .SS
duke@0 976 Getting Help
duke@0 977 .LP
duke@0 978 .RS 3
duke@0 979 .TP 3
duke@0 980 \-help
duke@0 981 .LP
bpatel@4176 982 Lists the basic commands and their options.
bpatel@4176 983 .LP
bpatel@4176 984 For more information about a specific command, enter the following, where \f2command_name\fP is the name of the command:
bpatel@4176 985 .nf
bpatel@4176 986 \f3
bpatel@4176 987 .fl
bpatel@4176 988 keytool \-\fP\f4command_name\fP\f3 \-help
bpatel@4176 989 .fl
bpatel@4176 990 \fP
bpatel@4176 991 .fi
duke@0 992 .RE
duke@0 993
duke@0 994 .LP
duke@0 995 .SH "EXAMPLES"
duke@0 996 .LP
duke@0 997 .LP
duke@0 998 Suppose you want to create a keystore for managing your public/private key pair and certificates from entities you trust.
duke@0 999 .LP
duke@0 1000 .SS
duke@0 1001 Generating Your Key Pair
duke@0 1002 .LP
duke@0 1003 .LP
duke@0 1004 The first thing you need to do is create a keystore and generate the key pair. You could use a command such as the following:
duke@0 1005 .LP
duke@0 1006 .nf
duke@0 1007 \f3
duke@0 1008 .fl
bpatel@4176 1009 keytool \-genkeypair \-dname "cn=Mark Jones, ou=Java, o=Oracle, c=US"
duke@0 1010 .fl
bpatel@4176 1011 \-alias business \-keypass \fP\f4<new password for private key>\fP\f3 \-keystore /working/mykeystore
duke@0 1012 .fl
bpatel@4176 1013 \-storepass \fP\f4<new password for keystore>\fP\f3 \-validity 180
duke@0 1014 .fl
duke@0 1015 \fP
duke@0 1016 .fi
duke@0 1017
duke@0 1018 .LP
duke@0 1019 .LP
duke@0 1020 (Please note: This must be typed as a single line. Multiple lines are used in the examples just for legibility purposes.)
duke@0 1021 .LP
duke@0 1022 .LP
bpatel@4176 1023 This command creates the keystore named "mykeystore" in the "working" directory (assuming it doesn't already exist), and assigns it the password specified by \f2<new password for keystore>\fP. 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 1024 bits long.
duke@0 1024 .LP
duke@0 1025 .LP
bpatel@4176 1026 It creates a self\-signed certificate (using the default "SHA1withDSA" signature algorithm) that includes the public key and the distinguished name information. This certificate will be valid for 180 days, and is associated with the private key in a keystore entry referred to by the alias "business". The private key is assigned the password specified by \f2<new password for private key>\fP.
duke@0 1027 .LP
duke@0 1028 .LP
duke@0 1029 The command could be significantly shorter if option defaults were accepted. As a matter of fact, no options are required; defaults are used for unspecified options that have default values, and you are prompted for any required values. Thus, you could simply have the following:
duke@0 1030 .LP
duke@0 1031 .nf
duke@0 1032 \f3
duke@0 1033 .fl
duke@0 1034 keytool \-genkeypair
duke@0 1035 .fl
duke@0 1036 \fP
duke@0 1037 .fi
duke@0 1038
duke@0 1039 .LP
duke@0 1040 .LP
bpatel@4176 1041 In this case, a keystore entry with alias "mykey" 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 ".keystore" in your home directory. (The keystore is created if it doesn't already exist.) You will be prompted for the distinguished name information, the keystore password, and the private key password.
duke@0 1042 .LP
bpatel@4176 1043 .LP
bpatel@4176 1044 The rest of the examples assume you executed the \f2\-genkeypair\fP command without options specified, and that you responded to the prompts with values equal to those given in the first \f2\-genkeypair\fP command, above (for example, a distinguished name of "cn=Mark Jones, ou=Java, o=Oracle, c=US").
bpatel@4176 1045 .LP
duke@0 1046 .SS
duke@0 1047 Requesting a Signed Certificate from a Certification Authority
duke@0 1048 .LP
duke@0 1049 .LP
duke@0 1050 So far all we've got is a self\-signed certificate. A certificate is more likely to be trusted by others if it is signed by a Certification Authority (CA). To get such a signature, you first generate a Certificate Signing Request (CSR), via the following:
duke@0 1051 .LP
duke@0 1052 .nf
duke@0 1053 \f3
duke@0 1054 .fl
duke@0 1055 keytool \-certreq \-file MarkJ.csr
duke@0 1056 .fl
duke@0 1057 \fP
duke@0 1058 .fi
duke@0 1059
duke@0 1060 .LP
bpatel@4176 1061 .LP
duke@0 1062 This creates a CSR (for the entity identified by the default alias "mykey") and puts the request in the file named "MarkJ.csr". Submit this file to a CA, such as VeriSign, Inc. The CA will authenticate you, the requestor (usually off\-line), and then will return a certificate, signed by them, authenticating your public key. (In some cases, they will actually return a chain of certificates, each one authenticating the public key of the signer of the previous certificate in the chain.)
bpatel@4176 1063 .LP
duke@0 1064 .SS
duke@0 1065 Importing a Certificate for the CA
duke@0 1066 .LP
duke@0 1067 .LP
duke@0 1068 You need to replace your 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.
duke@0 1069 .LP
duke@0 1070 .LP
duke@0 1071 Before you import the certificate reply from a CA, you need one or more "trusted certificates" in your keystore or in the \f2cacerts\fP keystore file (which is described in importcert command):
duke@0 1072 .LP
duke@0 1073 .RS 3
duke@0 1074 .TP 2
duke@0 1075 o
duke@0 1076 If the certificate reply is a certificate chain, you just need the top certificate of the chain (that is, the "root" CA certificate authenticating that CA's public key).
duke@0 1077 .TP 2
duke@0 1078 o
duke@0 1079 If the certificate reply is a single certificate, you need a certificate for the issuing CA (the one that signed it), and if that certificate is not self\-signed, you need a certificate for its signer, and so on, up to a self\-signed "root" CA certificate.
duke@0 1080 .RE
duke@0 1081
duke@0 1082 .LP
duke@0 1083 .LP
bpatel@4176 1084 The "cacerts" keystore file ships with several VeriSign root CA certificates, so you probably won't 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 hasn't been added to "cacerts", you will need to import a certificate from the CA as a "trusted certificate".
duke@0 1085 .LP
duke@0 1086 .LP
duke@0 1087 A certificate from a CA is usually either self\-signed, or signed by another CA (in which case you also need a certificate authenticating that CA's public key). Suppose company ABC, Inc., is a CA, and you obtain a file named "ABCCA.cer" that is purportedly a self\-signed certificate from ABC, authenticating that CA's public key.
duke@0 1088 .LP
duke@0 1089 .LP
duke@0 1090 Be very careful to ensure the certificate is valid prior to importing it as a "trusted" certificate! View it first (using the \f3keytool\fP \f2\-printcert\fP command, or the \f3keytool\fP \f2\-importcert\fP command without the \f2\-noprompt\fP option), and make sure that the displayed certificate fingerprint(s) match the expected ones. You can call the person who sent the certificate, and compare the fingerprint(s) that you see with the ones that they show (or that a secure public key repository shows). Only if the fingerprints are equal is it guaranteed that the certificate has not been replaced in transit with somebody else's (for example, an attacker's) certificate. If such an attack took place, and you did not check the certificate before you imported it, you would end up trusting anything the attacker has signed.
duke@0 1091 .LP
duke@0 1092 .LP
duke@0 1093 If you trust that the certificate is valid, then you can add it to your keystore via the following:
duke@0 1094 .LP
duke@0 1095 .nf
duke@0 1096 \f3
duke@0 1097 .fl
duke@0 1098 keytool \-importcert \-alias abc \-file ABCCA.cer
duke@0 1099 .fl
duke@0 1100 \fP
duke@0 1101 .fi
duke@0 1102
duke@0 1103 .LP
bpatel@4176 1104 .LP
duke@0 1105 This creates a "trusted certificate" entry in the keystore, with the data from the file "ABCCA.cer", and assigns the alias "abc" to the entry.
bpatel@4176 1106 .LP
duke@0 1107 .SS
duke@0 1108 Importing the Certificate Reply from the CA
duke@0 1109 .LP
duke@0 1110 .LP
bpatel@4900 1111 Once you've imported a certificate authenticating 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 thereby replace your self\-signed certificate with a certificate chain. This chain is the one returned by the CA in response to your request (if the CA reply is a chain), or one constructed (if 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 "cacerts" keystore file.
duke@0 1112 .LP
duke@0 1113 .LP
duke@0 1114 For example, suppose you sent your certificate signing request to VeriSign. You can then import the reply via the following, which assumes the returned certificate is named "VSMarkJ.cer":
duke@0 1115 .LP
duke@0 1116 .nf
duke@0 1117 \f3
duke@0 1118 .fl
duke@0 1119 keytool \-importcert \-trustcacerts \-file VSMarkJ.cer
duke@0 1120 .fl
duke@0 1121 \fP
duke@0 1122 .fi
duke@0 1123
duke@0 1124 .LP
duke@0 1125 .SS
duke@0 1126 Exporting a Certificate Authenticating Your Public Key
duke@0 1127 .LP
duke@0 1128 .LP
bpatel@4176 1129 Suppose you have used the jarsigner(1) tool to sign a Java ARchive (JAR) file. Clients that want to use the file will want to authenticate your signature.
bpatel@4176 1130 .LP
duke@0 1131 .LP
duke@0 1132 One way they can do this is by first importing your public key certificate into their keystore as a "trusted" entry. You can export the certificate and supply it to your clients. As an example, you can copy your certificate to a file named \f2MJ.cer\fP via the following, assuming the entry is aliased by "mykey":
duke@0 1133 .LP
duke@0 1134 .nf
duke@0 1135 \f3
duke@0 1136 .fl
duke@0 1137 keytool \-exportcert \-alias mykey \-file MJ.cer
duke@0 1138 .fl
duke@0 1139 \fP
duke@0 1140 .fi
duke@0 1141
duke@0 1142 .LP
bpatel@4176 1143 .LP
duke@0 1144 Given that certificate, and the signed JAR file, a client can use the \f3jarsigner\fP tool to authenticate your signature.
bpatel@4176 1145 .LP
duke@0 1146 .SS
duke@0 1147 Importing Keystore
duke@0 1148 .LP
duke@0 1149 .LP
duke@0 1150 The command "importkeystore" 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 \f3keytool\fP has difficulties recover the private keys or secret keys from the source keystore, it will prompt you for a password. If it detects alias duplication, it will ask you for a new one, you can specify a new alias or simply allow \f3keytool\fP to overwrite the existing one.
duke@0 1151 .LP
duke@0 1152 .LP
duke@0 1153 For example, to import entries from a normal JKS type keystore key.jks into a PKCS #11 type hardware based keystore, you can use the command:
duke@0 1154 .LP
duke@0 1155 .nf
duke@0 1156 \f3
duke@0 1157 .fl
bpatel@4176 1158 keytool \-importkeystore
duke@0 1159 .fl
duke@0 1160 \-srckeystore key.jks \-destkeystore NONE
duke@0 1161 .fl
duke@0 1162 \-srcstoretype JKS \-deststoretype PKCS11
duke@0 1163 .fl
bpatel@4176 1164 \-srcstorepass \fP\f4<source keystore password>\fP\f3 \-deststorepass \fP\f4<destination keystore password>\fP\f3
duke@0 1165 .fl
duke@0 1166 \fP
duke@0 1167 .fi
duke@0 1168
duke@0 1169 .LP
duke@0 1170 .LP
bpatel@4176 1171 The importkeystore 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 above example, you need to specify the alias you want to import. With the srcalias option given, 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:
duke@0 1172 .LP
duke@0 1173 .nf
duke@0 1174 \f3
duke@0 1175 .fl
bpatel@4176 1176 keytool \-importkeystore
duke@0 1177 .fl
duke@0 1178 \-srckeystore key.jks \-destkeystore NONE
duke@0 1179 .fl
duke@0 1180 \-srcstoretype JKS \-deststoretype PKCS11
duke@0 1181 .fl
bpatel@4176 1182 \-srcstorepass \fP\f4<source keystore password>\fP\f3 \-deststorepass \fP\f4<destination keystore password>\fP\f3
duke@0 1183 .fl
duke@0 1184 \-srcalias myprivatekey \-destalias myoldprivatekey
duke@0 1185 .fl
bpatel@4176 1186 \-srckeypass \fP\f4<source entry password>\fP\f3 \-destkeypass \fP\f4<destination entry password>\fP\f3
duke@0 1187 .fl
duke@0 1188 \-noprompt
duke@0 1189 .fl
duke@0 1190 \fP
duke@0 1191 .fi
duke@0 1192
duke@0 1193 .LP
tbell@1178 1194 .SS
bpatel@4176 1195 Generating Certificates for a Typical SSL Server
tbell@1178 1196 .LP
tbell@1178 1197 .LP
bpatel@4176 1198 The following are keytool commands to generate keypairs and certificates for three entities, namely, Root CA (root), Intermediate CA (ca), and SSL server (server). Ensure that you store all the certificates in the same keystore. In these examples, it is recommended that you specify RSA as the key algorithm.
tbell@1178 1199 .LP
tbell@1178 1200 .nf
tbell@1178 1201 \f3
tbell@1178 1202 .fl
bpatel@4176 1203 keytool \-genkeypair \-keystore root.jks \-alias root \-ext bc:c
tbell@1178 1204 .fl
bpatel@4176 1205 keytool \-genkeypair \-keystore ca.jks \-alias ca \-ext bc:c
tbell@1178 1206 .fl
bpatel@4176 1207 keytool \-genkeypair \-keystore server.jks \-alias server
tbell@1178 1208 .fl
bpatel@4176 1209
tbell@1178 1210 .fl
bpatel@4176 1211 keytool \-keystore root.jks \-alias root \-exportcert \-rfc > root.pem
tbell@1178 1212 .fl
bpatel@4176 1213
tbell@1178 1214 .fl
bpatel@4176 1215 keytool \-storepass \fP\f4<storepass>\fP\f3 \-keystore ca.jks \-certreq \-alias ca | keytool \-storepass \fP\f4<storepass>\fP\f3 \-keystore root.jks \-gencert \-alias root \-ext BC=0 \-rfc > ca.pem
tbell@1178 1216 .fl
tbell@1178 1217 keytool \-keystore ca.jks \-importcert \-alias ca \-file ca.pem
tbell@1178 1218 .fl
bpatel@4176 1219
tbell@1178 1220 .fl
bpatel@4176 1221 keytool \-storepass \fP\f4<storepass>\fP\f3 \-keystore server.jks \-certreq \-alias server | keytool \-storepass \fP\f4<storepass>\fP\f3 \-keystore ca.jks \-gencert \-alias ca \-ext ku:c=dig,kE \-rfc > server.pem
tbell@1178 1222 .fl
tbell@1178 1223 cat root.pem ca.pem server.pem | keytool \-keystore server.jks \-importcert \-alias server
tbell@1178 1224 .fl
tbell@1178 1225 \fP
tbell@1178 1226 .fi
tbell@1178 1227
tbell@1178 1228 .LP
duke@0 1229 .SH "TERMINOLOGY and WARNINGS"
duke@0 1230 .LP
duke@0 1231 .SS
duke@0 1232 KeyStore
duke@0 1233 .LP
duke@0 1234 .LP
duke@0 1235 A keystore is a storage facility for cryptographic keys and certificates.
bpatel@4176 1236 .LP
duke@0 1237 .RS 3
duke@0 1238 .TP 2
duke@0 1239 o
duke@0 1240 \f3KeyStore Entries\fP
duke@0 1241 .LP
duke@0 1242 Keystores may have different types of entries. The two most applicable entry types for \f3keytool\fP include:
duke@0 1243 .RS 3
duke@0 1244 .TP 3
duke@0 1245 1.
bpatel@4176 1246 \f3key entries\fP \- each 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. The \f3keytool\fP can handle both types of entries, while the \f3jarsigner\fP tool only handle the latter type of entry, that is private keys and their associated certificate chains.
duke@0 1247 .TP 3
duke@0 1248 2.
duke@0 1249 \f3trusted certificate entries\fP \- each contains a single public key certificate belonging to another party. It is called a "trusted certificate" because the keystore owner trusts that the public key in the certificate indeed belongs to the identity identified by the "subject" (owner) of the certificate. The issuer of the certificate vouches for this, by signing the certificate.
duke@0 1250 .RE
duke@0 1251 .TP 2
duke@0 1252 o
duke@0 1253 \f3KeyStore Aliases\fP
duke@0 1254 .LP
bpatel@4176 1255 All keystore entries (key and trusted certificate entries) are accessed via unique \f2aliases\fP.
duke@0 1256 .LP
bpatel@4176 1257 An alias is specified when you add an entity to the keystore using the \-genseckey command to generate a secret key, \-genkeypair command to generate a key pair (public and private key) or the \-importcert command to add a certificate or certificate chain to the list of trusted certificates. Subsequent \f3keytool\fP commands must use this same alias to refer to the entity.
duke@0 1258 .LP
bpatel@4176 1259 For example, suppose you use the alias \f2duke\fP to generate a new public/private key pair and wrap the public key into a self\-signed certificate (see Certificate Chains) via the following command:
duke@0 1260 .nf
duke@0 1261 \f3
duke@0 1262 .fl
duke@0 1263 keytool \-genkeypair \-alias duke \-keypass dukekeypasswd
duke@0 1264 .fl
duke@0 1265 \fP
duke@0 1266 .fi
duke@0 1267 .LP
bpatel@4176 1268 This specifies an initial password of "dukekeypasswd" required by subsequent commands to access the private key associated with the alias \f2duke\fP. If you later want to change duke's private key password, you use a command like the following:
duke@0 1269 .nf
duke@0 1270 \f3
duke@0 1271 .fl
duke@0 1272 keytool \-keypasswd \-alias duke \-keypass dukekeypasswd \-new newpass
duke@0 1273 .fl
duke@0 1274 \fP
duke@0 1275 .fi
duke@0 1276 .LP
duke@0 1277 This changes the password from "dukekeypasswd" to "newpass".
duke@0 1278 .LP
bpatel@4176 1279 Please note: A password should not actually 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 don't specify a required password option on a command line, you will be prompted for it.
duke@0 1280 .TP 2
duke@0 1281 o
duke@0 1282 \f3KeyStore Implementation\fP
bpatel@4176 1283 .LP
duke@0 1284 The \f2KeyStore\fP class provided in the \f2java.security\fP 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 \f2type\fP of keystore.
duke@0 1285 .LP
bpatel@4176 1286 Currently, two command\-line tools (\f3keytool\fP and \f3jarsigner\fP) and a GUI\-based tool named \f3Policy Tool\fP make use of keystore implementations. Since \f2KeyStore\fP is publicly available, users can write additional security applications that use it.
duke@0 1287 .LP
bpatel@4176 1288 There is a built\-in default implementation, provided by Oracle. It implements the keystore as a file, utilizing 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.
duke@0 1289 .LP
tbell@1178 1290 Keystore implementations are provider\-based. More specifically, the application interfaces supplied by \f2KeyStore\fP are implemented in terms of a "Service Provider Interface" (SPI). That is, there is a corresponding abstract \f2KeystoreSpi\fP class, also in the \f2java.security\fP package, which defines the Service Provider Interface methods that "providers" must implement. (The term "provider" 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.) Thus, to provide a keystore implementation, clients must implement a "provider" and supply a KeystoreSpi subclass implementation, as described in
tbell@1178 1291 .na
tbell@1178 1292 \f2How to Implement a Provider for the Java Cryptography Architecture\fP @
tbell@1178 1293 .fi
bpatel@4900 1294 http://docs.oracle.com/javase/7/docs/technotes/guides/security/crypto/HowToImplAProvider.html.
duke@0 1295 .LP
bpatel@4176 1296 Applications can choose different \f2types\fP of keystore implementations from different providers, using the "getInstance" factory method supplied in the \f2KeyStore\fP 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 itself. Keystore implementations of different types are not compatible.
duke@0 1297 .LP
bpatel@4176 1298 \f3keytool\fP works on any file\-based keystore implementation. (It treats the keystore location that is passed to it at the command line as a filename and converts it to a FileInputStream, from which it loads the keystore information.) The \f3jarsigner\fP and \f3policytool\fP tools, on the other hand, can read a keystore from any location that can be specified using a URL.
duke@0 1299 .LP
bpatel@4176 1300 For \f3keytool\fP and \f3jarsigner\fP, you can specify a keystore type at the command line, via the \f2\-storetype\fP option. For \f3Policy Tool\fP, you can specify a keystore type via the "Keystore" menu.
duke@0 1301 .LP
bpatel@4176 1302 If you don't explicitly specify a keystore type, the tools choose a keystore implementation based simply on the value of the \f2keystore.type\fP property specified in the security properties file. The security properties file is called \f2java.security\fP, and it resides in the security properties directory, \f2java.home\fP/lib/security, where \f2java.home\fP is the runtime environment's directory (the \f2jre\fP directory in the SDK or the top\-level directory of the Java 2 Runtime Environment).
duke@0 1303 .LP
bpatel@4176 1304 Each tool gets the \f2keystore.type\fP value and then examines all the currently\-installed providers until it finds one that implements keystores of that type. It then uses the keystore implementation from that provider.
duke@0 1305 .LP
bpatel@4176 1306 The \f2KeyStore\fP class defines a static method named \f2getDefaultType\fP that lets applications and applets retrieve the value of the \f2keystore.type\fP property. The following line of code creates an instance of the default keystore type (as specified in the \f2keystore.type\fP property):
duke@0 1307 .nf
duke@0 1308 \f3
duke@0 1309 .fl
duke@0 1310 KeyStore keyStore = KeyStore.getInstance(KeyStore.getDefaultType());
duke@0 1311 .fl
duke@0 1312 \fP
duke@0 1313 .fi
duke@0 1314 .LP
bpatel@4176 1315 The default keystore type is "jks" (the proprietary type of the keystore implementation provided by Oracle). This is specified by the following line in the security properties file:
duke@0 1316 .nf
duke@0 1317 \f3
duke@0 1318 .fl
duke@0 1319 keystore.type=jks
duke@0 1320 .fl
duke@0 1321 \fP
duke@0 1322 .fi
duke@0 1323 .LP
bpatel@4176 1324 To have the tools utilize a keystore implementation other than the default, you can change that line to specify a different keystore type.
duke@0 1325 .LP
bpatel@4176 1326 For example, if you have a provider package that supplies a keystore implementation for a keystore type called "pkcs12", change the line to
duke@0 1327 .nf
duke@0 1328 \f3
duke@0 1329 .fl
duke@0 1330 keystore.type=pkcs12
duke@0 1331 .fl
duke@0 1332 \fP
duke@0 1333 .fi
bpatel@4176 1334 .LP
bpatel@4176 1335 Note: case doesn't matter in keystore type designations. For example, "JKS" would be considered the same as "jks".
bpatel@4176 1336 .RE
duke@0 1337
duke@0 1338 .LP
duke@0 1339 .SS
duke@0 1340 Certificate
duke@0 1341 .LP
bpatel@4176 1342 A \f3certificate\fP (also known as a \f3public\-key certificate\fP) is a digitally signed statement from one entity (the \f2issuer\fP), saying that the public key (and some other information) of another entity (the \f2subject\fP) has some specific value.
duke@0 1343 .RS 3
duke@0 1344 .TP 2
duke@0 1345 o
duke@0 1346 \f3Certificate Terms\fP
duke@0 1347 .RS 3
duke@0 1348 .TP 3
duke@0 1349 Public Keys
bpatel@4176 1350 .LP
bpatel@4176 1351 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.
duke@0 1352 .TP 3
duke@0 1353 Digitally Signed
bpatel@4176 1354 .LP
bpatel@4176 1355 If some data is \f2digitally signed\fP it has been 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.
duke@0 1356 .TP 3
duke@0 1357 Identity
bpatel@4176 1358 .LP
bpatel@4176 1359 A known way of addressing an entity. In some systems the identity is the public key, in others it can be anything from a Unix UID to an Email address to an X.509 Distinguished Name.
duke@0 1360 .TP 3
duke@0 1361 Signature
bpatel@4176 1362 .LP
bpatel@4176 1363 A signature is computed over some data using the private key of an entity (the \f2signer\fP, which in the case of a certificate is also known as the \f2issuer\fP).
duke@0 1364 .TP 3
duke@0 1365 Private Keys
bpatel@4176 1366 .LP
bpatel@4176 1367 These are numbers, each of which is supposed to be known only to the particular entity whose private key it is (that is, it's 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.
duke@0 1368 .TP 3
duke@0 1369 Entity
bpatel@4176 1370 .LP
bpatel@4176 1371 An entity is a person, organization, program, computer, business, bank, or something else you are trusting to some degree.
duke@0 1372 .RE
duke@0 1373 .LP
duke@0 1374 Basically, 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 have been 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 \f2Certification Authority\fP (CA) can act as a trusted third party. CAs are entities (for example, businesses) that are trusted to sign (issue) certificates for other entities. It is assumed that CAs will only create valid and reliable certificates, as they are bound by legal agreements. There are many public Certification Authorities, such as
duke@0 1375 .na
duke@0 1376 \f2VeriSign\fP @
duke@0 1377 .fi
duke@0 1378 http://www.verisign.com/,
duke@0 1379 .na
duke@0 1380 \f2Thawte\fP @
duke@0 1381 .fi
duke@0 1382 http://www.thawte.com/,
duke@0 1383 .na
duke@0 1384 \f2Entrust\fP @
duke@0 1385 .fi
bpatel@4176 1386 http://www.entrust.com/, and so on. You can also run your own Certification Authority using products such as Microsoft Certificate Server or the Entrust CA product for your organization.
duke@0 1387 .LP
bpatel@4176 1388 Using \f3keytool\fP, it is possible to display, import, and export certificates. It is also possible to generate self\-signed certificates.
duke@0 1389 .LP
bpatel@4176 1390 \f3keytool\fP currently handles X.509 certificates.
duke@0 1391 .TP 2
duke@0 1392 o
duke@0 1393 \f3X.509 Certificates\fP
bpatel@4176 1394 .LP
duke@0 1395 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 using two related standards called ASN.1/DER. \f2Abstract Syntax Notation 1\fP describes data. The \f2Definite Encoding Rules\fP describe a single way to store and transfer that data.
duke@0 1396 .LP
bpatel@4176 1397 All X.509 certificates have the following data, in addition to the signature:
duke@0 1398 .RS 3
duke@0 1399 .TP 3
duke@0 1400 Version
bpatel@4176 1401 .LP
duke@0 1402 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. \f3keytool\fP can import and export v1, v2, and v3 certificates. It generates v3 certificates.
duke@0 1403 .LP
duke@0 1404 \f2X.509 Version 1\fP has been available since 1988, is widely deployed, and is the most generic.
duke@0 1405 .LP
duke@0 1406 \f2X.509 Version 2\fP introduced the concept of subject and issuer unique identifiers to handle the possibility of reuse of subject and/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.
duke@0 1407 .LP
duke@0 1408 \f2X.509 Version 3\fP is the most recent (1996) and supports the notion of extensions, whereby anyone can define an extension and include it in the certificate. Some common extensions in use today are: \f2KeyUsage\fP (limits the use of the keys to particular purposes such as "signing\-only") and \f2AlternativeNames\fP (allows other identities to also be associated with this public key, e.g. DNS names, Email addresses, IP addresses). Extensions can be marked \f2critical\fP to indicate that the extension should be checked and enforced/used. For example, if a certificate has the KeyUsage extension marked critical and set to "keyCertSign" then if this certificate is presented during SSL communication, it should be rejected, as the certificate extension indicates that the associated private key should only be used for signing certificates and not for SSL use.
duke@0 1409 .TP 3
duke@0 1410 Serial Number
bpatel@4176 1411 .LP
bpatel@4176 1412 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).
duke@0 1413 .TP 3
duke@0 1414 Signature Algorithm Identifier
bpatel@4176 1415 .LP
bpatel@4176 1416 This identifies the algorithm used by the CA to sign the certificate.
duke@0 1417 .TP 3
duke@0 1418 Issuer Name
bpatel@4176 1419 .LP
bpatel@4176 1420 The X.500 Distinguished Name of the entity that signed the certificate. This is normally a CA. Using this certificate implies trusting the entity that signed this certificate. (Note that in some cases, such as \f2root or top\-level\fP CA certificates, the issuer signs its own certificate.)
duke@0 1421 .TP 3
duke@0 1422 Validity Period
bpatel@4176 1423 .LP
bpatel@4176 1424 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, if the associated private key has not been compromised.
duke@0 1425 .TP 3
duke@0 1426 Subject Name
bpatel@4176 1427 .LP
duke@0 1428 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, for example,
duke@0 1429 .nf
duke@0 1430 \f3
duke@0 1431 .fl
bpatel@4176 1432 CN=Java Duke, OU=Java Software Division, O=Oracle Corporation, C=US
duke@0 1433 .fl
duke@0 1434 \fP
duke@0 1435 .fi
bpatel@4176 1436 .LP
bpatel@4176 1437 (These refer to the subject's Common Name, Organizational Unit, Organization, and Country.)
duke@0 1438 .TP 3
duke@0 1439 Subject Public Key Information
duke@0 1440 .LP
bpatel@4176 1441 This is the public key of the entity being named, together with an algorithm identifier which specifies which public key crypto system this key belongs to and any associated key parameters.
duke@0 1442 .RE
duke@0 1443 .TP 2
duke@0 1444 o
duke@0 1445 \f3Certificate Chains\fP
duke@0 1446 .LP
bpatel@4176 1447 \f3keytool\fP 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 corresponding to the private key.
duke@0 1448 .LP
bpatel@4176 1449 When keys are first generated (see the \-genkeypair command), the chain starts off containing a single element, a \f2self\-signed certificate\fP. A self\-signed certificate is one for which the issuer (signer) is the same as the subject (the entity whose public key is being authenticated by the certificate). Whenever the \f2\-genkeypair\fP command is called to generate a new public/private key pair, it also wraps the public key into a self\-signed certificate.
duke@0 1450 .LP
bpatel@4176 1451 Later, after a Certificate Signing Request (CSR) has been generated (see the \-certreq command) and sent to a Certification Authority (CA), the response from the CA is imported (see \-importcert), and the self\-signed certificate is replaced by a chain of certificates. 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 \f2CA\fP's public key.
duke@0 1452 .LP
bpatel@4176 1453 In many cases, this is a self\-signed certificate (that is, a certificate from the CA authenticating its own public key) and the last certificate in the chain. In other cases, the CA may 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 \f2different\fP CA, authenticating the public key of the CA you sent the CSR to. Then, the next certificate in the chain will be a certificate authenticating the second CA's key, and so on, until a self\-signed "root" certificate is reached. Each certificate in the chain (after the first) thus authenticates the public key of the signer of the previous certificate in the chain.
duke@0 1454 .LP
bpatel@4176 1455 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.
duke@0 1456 .LP
bpatel@4176 1457 A different reply format (defined by the PKCS#7 standard) also includes the supporting certificate chain, in addition to the issued certificate. Both reply formats can be handled by \f3keytool\fP.
duke@0 1458 .LP
bpatel@4176 1459 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 (anybody could generate a self\-signed certificate with the distinguished name of say, the VeriSign root CA!), but from other sources like a newspaper. 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 (using the \f2\-printcert\fP option) and compare the displayed fingerprint with the well\-known fingerprint (obtained from a newspaper, the root CA's Web page, etc.).
duke@0 1460 .TP 2
duke@0 1461 o
duke@0 1462 \f3The cacerts Certificates File\fP
duke@0 1463 .LP
bpatel@4176 1464 A certificates file named \f3"cacerts"\fP resides in the security properties directory, \f2java.home\fP/lib/security, where \f2java.home\fP is the runtime environment's directory (the \f2jre\fP directory in the SDK or the top\-level directory of the Java 2 Runtime Environment).
duke@0 1465 .LP
bpatel@4176 1466 The "cacerts" file represents a system\-wide keystore with CA certificates. System administrators can configure and manage that file using \f3keytool\fP, specifying "jks" as the keystore type. The "cacerts" keystore file ships with a default set of root CA certificates; list them with the following command:
bpatel@4176 1467 .nf
bpatel@4176 1468 \f3
bpatel@4176 1469 .fl
bpatel@4176 1470 keytool \-list \-keystore \fP\f4java.home\fP\f3/lib/security/cacerts
bpatel@4176 1471 .fl
bpatel@4176 1472 \fP
bpatel@4176 1473 .fi
duke@0 1474 .LP
bpatel@4176 1475 The initial password of the "cacerts" keystore file is "changeit". System administrators should change that password and the default access permission of that file upon installing the SDK.
duke@0 1476 .LP
bpatel@4176 1477 \f3IMPORTANT: Verify Your \fP\f4cacerts\fP\f3 File\fP: Since you trust the CAs in the \f2cacerts\fP file as entities for signing and issuing certificates to other entities, you must manage the \f2cacerts\fP file carefully. The \f2cacerts\fP file should contain only certificates of the CAs you trust. It is your responsibility to verify the trusted root CA certificates bundled in the \f2cacerts\fP file and make your own trust decisions. To remove an untrusted CA certificate from the \f2cacerts\fP file, use the delete option of the \f2keytool\fP command. You can find the \f2cacerts\fP file in the JRE installation directory. Contact your system administrator if you do not have permission to edit this file.
duke@0 1478 .TP 2
duke@0 1479 o
duke@0 1480 \f3The Internet RFC 1421 Certificate Encoding Standard\fP
duke@0 1481 .LP
bpatel@4176 1482 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 "Base 64 encoding", facilitates exporting certificates to other applications by email or through some other mechanism.
duke@0 1483 .LP
bpatel@4176 1484 Certificates read by the \f2\-importcert\fP and \f2\-printcert\fP commands can be in either this format or binary encoded.
duke@0 1485 .LP
bpatel@4176 1486 The \f2\-exportcert\fP command by default outputs a certificate in binary encoding, but will instead output a certificate in the printable encoding format, if the \f2\-rfc\fP option is specified.
duke@0 1487 .LP
bpatel@4176 1488 The \f2\-list\fP command by default prints the SHA1 fingerprint of a certificate. If the \f2\-v\fP option is specified, the certificate is printed in human\-readable format, while if the \f2\-rfc\fP option is specified, the certificate is output in the printable encoding format.
duke@0 1489 .LP
bpatel@4176 1490 In its printable encoding format, the encoded certificate is bounded at the beginning by
duke@0 1491 .nf
duke@0 1492 \f3
duke@0 1493 .fl
duke@0 1494 \-\-\-\-\-BEGIN CERTIFICATE\-\-\-\-\-
duke@0 1495 .fl
duke@0 1496 \fP
duke@0 1497 .fi
duke@0 1498 .LP
bpatel@4176 1499 and at the end by
duke@0 1500 .nf
duke@0 1501 \f3
duke@0 1502 .fl
duke@0 1503 \-\-\-\-\-END CERTIFICATE\-\-\-\-\-
duke@0 1504 .fl
duke@0 1505 \fP
duke@0 1506 .fi
duke@0 1507 .RE
duke@0 1508
duke@0 1509 .LP
duke@0 1510 .SS
duke@0 1511 X.500 Distinguished Names
duke@0 1512 .LP
duke@0 1513 .LP
bpatel@4176 1514 X.500 Distinguished Names are used to identify entities, such as those which are named by the \f2subject\fP and \f2issuer\fP (signer) fields of X.509 certificates. \f3keytool\fP supports the following subparts:
bpatel@4176 1515 .LP
duke@0 1516 .RS 3
duke@0 1517 .TP 2
duke@0 1518 o
duke@0 1519 \f2commonName\fP \- common name of a person, e.g., "Susan Jones"
duke@0 1520 .TP 2
duke@0 1521 o
bpatel@4176 1522 \f2organizationUnit\fP \- small organization (e.g., department or division) name, e.g., "Purchasing"
duke@0 1523 .TP 2
duke@0 1524 o
duke@0 1525 \f2organizationName\fP \- large organization name, e.g., "ABCSystems, Inc."
duke@0 1526 .TP 2
duke@0 1527 o
duke@0 1528 \f2localityName\fP \- locality (city) name, e.g., "Palo Alto"
duke@0 1529 .TP 2
duke@0 1530 o
duke@0 1531 \f2stateName\fP \- state or province name, e.g., "California"
duke@0 1532 .TP 2
duke@0 1533 o
duke@0 1534 \f2country\fP \- two\-letter country code, e.g., "CH"
duke@0 1535 .RE
duke@0 1536
duke@0 1537 .LP
duke@0 1538 .LP
duke@0 1539 When supplying a distinguished name string as the value of a \f2\-dname\fP option, as for the \f2\-genkeypair\fP command, the string must be in the following format:
duke@0 1540 .LP
duke@0 1541 .nf
duke@0 1542 \f3
duke@0 1543 .fl
duke@0 1544 CN=\fP\f4cName\fP\f3, OU=\fP\f4orgUnit\fP\f3, O=\fP\f4org\fP\f3, L=\fP\f4city\fP\f3, S=\fP\f4state\fP\f3, C=\fP\f4countryCode\fP\f3
duke@0 1545 .fl
duke@0 1546 \fP
duke@0 1547 .fi
duke@0 1548
duke@0 1549 .LP
duke@0 1550 .LP
duke@0 1551 where all the italicized items represent actual values and the above keywords are abbreviations for the following:
duke@0 1552 .LP
duke@0 1553 .nf
duke@0 1554 \f3
duke@0 1555 .fl
bpatel@4176 1556 CN=commonName
duke@0 1557 .fl
duke@0 1558 OU=organizationUnit
duke@0 1559 .fl
duke@0 1560 O=organizationName
duke@0 1561 .fl
duke@0 1562 L=localityName
duke@0 1563 .fl
duke@0 1564 S=stateName
duke@0 1565 .fl
duke@0 1566 C=country
duke@0 1567 .fl
duke@0 1568 \fP
duke@0 1569 .fi
duke@0 1570
duke@0 1571 .LP
duke@0 1572 .LP
duke@0 1573 A sample distinguished name string is
duke@0 1574 .LP
duke@0 1575 .nf
duke@0 1576 \f3
duke@0 1577 .fl
bpatel@4176 1578 CN=Mark Smith, OU=Java, O=Oracle, L=Cupertino, S=California, C=US
duke@0 1579 .fl
duke@0 1580 \fP
duke@0 1581 .fi
duke@0 1582
duke@0 1583 .LP
bpatel@4176 1584 .LP
bpatel@4176 1585 and a sample command using such a string is
bpatel@4176 1586 .LP
duke@0 1587 .nf
duke@0 1588 \f3
duke@0 1589 .fl
bpatel@4176 1590 keytool \-genkeypair \-dname "CN=Mark Smith, OU=Java, O=Oracle, L=Cupertino,
duke@0 1591 .fl
duke@0 1592 S=California, C=US" \-alias mark
duke@0 1593 .fl
duke@0 1594 \fP
duke@0 1595 .fi
duke@0 1596
duke@0 1597 .LP
duke@0 1598 .LP
duke@0 1599 Case does not matter for the keyword abbreviations. For example, "CN", "cn", and "Cn" are all treated the same.
duke@0 1600 .LP
duke@0 1601 .LP
duke@0 1602 Order matters; each subcomponent must appear in the designated order. However, it is not necessary to have all the subcomponents. You may use a subset, for example:
duke@0 1603 .LP
duke@0 1604 .nf
duke@0 1605 \f3
duke@0 1606 .fl
bpatel@4176 1607 CN=Steve Meier, OU=Java, O=Oracle, C=US
duke@0 1608 .fl
duke@0 1609 \fP
duke@0 1610 .fi
duke@0 1611
duke@0 1612 .LP
duke@0 1613 .LP
duke@0 1614 If a distinguished name string value contains a comma, the comma must be escaped by a "\\" character when you specify the string on a command line, as in
duke@0 1615 .LP
duke@0 1616 .nf
duke@0 1617 \f3
duke@0 1618 .fl
bpatel@4176 1619 cn=Peter Schuster, ou=Java\\, Product Development, o=Oracle, c=US
duke@0 1620 .fl
duke@0 1621 \fP
duke@0 1622 .fi
duke@0 1623
duke@0 1624 .LP
duke@0 1625 .LP
duke@0 1626 It is never necessary to specify a distinguished name string on a command line. If it 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 "\\".
duke@0 1627 .LP
duke@0 1628 .SS
duke@0 1629 WARNING Regarding Importing Trusted Certificates
duke@0 1630 .LP
duke@0 1631 .LP
bpatel@4176 1632 IMPORTANT: Be sure to check a certificate very carefully before importing it as a trusted certificate!
bpatel@4176 1633 .LP
duke@0 1634 .LP
duke@0 1635 View it first (using the \f2\-printcert\fP command, or the \f2\-importcert\fP command without the \f2\-noprompt\fP option), and make sure that the displayed certificate fingerprint(s) match the expected ones. For example, suppose someone sends or emails you a certificate, and you put it in a file named \f2/tmp/cert\fP. Before you consider adding the certificate to your list of trusted certificates, you can execute a \f2\-printcert\fP command to view its fingerprints, as in
duke@0 1636 .LP
duke@0 1637 .nf
duke@0 1638 \f3
duke@0 1639 .fl
duke@0 1640 keytool \-printcert \-file /tmp/cert
duke@0 1641 .fl
duke@0 1642 Owner: CN=ll, OU=ll, O=ll, L=ll, S=ll, C=ll
duke@0 1643 .fl
duke@0 1644 Issuer: CN=ll, OU=ll, O=ll, L=ll, S=ll, C=ll
duke@0 1645 .fl
duke@0 1646 Serial Number: 59092b34
duke@0 1647 .fl
duke@0 1648 Valid from: Thu Sep 25 18:01:13 PDT 1997 until: Wed Dec 24 17:01:13 PST 1997
duke@0 1649 .fl
duke@0 1650 Certificate Fingerprints:
duke@0 1651 .fl
duke@0 1652 MD5: 11:81:AD:92:C8:E5:0E:A2:01:2E:D4:7A:D7:5F:07:6F
duke@0 1653 .fl
duke@0 1654 SHA1: 20:B6:17:FA:EF:E5:55:8A:D0:71:1F:E8:D6:9D:C0:37:13:0E:5E:FE
duke@0 1655 .fl
bpatel@2509 1656 SHA256: 90:7B:70:0A:EA:DC:16:79:92:99:41:FF:8A:FE:EB:90:
bpatel@2509 1657 .fl
bpatel@2509 1658 17:75:E0:90:B2:24:4D:3A:2A:16:A6:E4:11:0F:67:A4
bpatel@2509 1659 .fl
duke@0 1660 \fP
duke@0 1661 .fi
duke@0 1662
duke@0 1663 .LP
bpatel@4176 1664 .LP
bpatel@4176 1665 Then call or otherwise contact the person who sent the certificate, and compare the fingerprint(s) that you see with the ones that they show. Only if the fingerprints are equal is it guaranteed that the certificate has not been replaced in transit with somebody else's (for example, an attacker's) certificate. If such an attack took place, and you did not check the certificate before you imported it, you would end up trusting anything the attacker has signed (for example, a JAR file with malicious class files inside).
bpatel@4176 1666 .LP
duke@0 1667 .LP
duke@0 1668 Note: it is not required that you execute a \f2\-printcert\fP command prior to importing a certificate, since before adding a certificate to the list of trusted certificates in the keystore, the \f2\-importcert\fP command prints out the certificate information and prompts you to verify it. You then have the option of aborting the import operation. Note, however, this is only the case if you invoke the \f2\-importcert\fP command without the \f2\-noprompt\fP option. If the \f2\-noprompt\fP option is given, there is no interaction with the user.
duke@0 1669 .LP
duke@0 1670 .SS
duke@0 1671 Warning Regarding Passwords
duke@0 1672 .LP
duke@0 1673 .LP
duke@0 1674 Most commands operating on a keystore require the store password. Some commands require a private/secret key password.
duke@0 1675 .LP
duke@0 1676 .LP
duke@0 1677 Passwords can be specified on the command line (in the \f2\-storepass\fP and \f2\-keypass\fP options, respectively). However, 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.
duke@0 1678 .LP
duke@0 1679 .LP
duke@0 1680 If you don't specify a required password option on a command line, you will be prompted for it.
duke@0 1681 .LP
bpatel@2509 1682 .SS
bpatel@2509 1683 Warning Regarding Certificate Conformance
bpatel@2509 1684 .LP
bpatel@2509 1685 .LP
bpatel@2509 1686 The Internet standard
bpatel@2509 1687 .na
bpatel@2509 1688 \f2RFC 5280\fP @
bpatel@2509 1689 .fi
bpatel@2509 1690 http://tools.ietf.org/rfc/rfc5280.txt has defined a profile on conforming X.509 certificates, which includes what values and value combinations are valid for certificate fields and extensions. \f3keytool\fP has not enforced all these rules so it can generate certificates which do not conform to the standard, and these certificates might be rejected by JRE or other applications. Users should make sure that they provide the correct options for \f2\-dname\fP, \f2\-ext\fP, etc.
bpatel@2509 1691 .LP
duke@0 1692 .SH "SEE ALSO"
duke@0 1693 .LP
duke@0 1694 .RS 3
duke@0 1695 .TP 2
duke@0 1696 o
bpatel@4176 1697 jar(1) tool documentation
duke@0 1698 .TP 2
duke@0 1699 o
bpatel@4176 1700 jarsigner(1) tool documentation
duke@0 1701 .TP 2
duke@0 1702 o
duke@0 1703 the
duke@0 1704 .na
duke@0 1705 \f4Security\fP @
duke@0 1706 .fi
bpatel@4900 1707 http://docs.oracle.com/javase/tutorial/security/index.html trail of the
duke@0 1708 .na
duke@0 1709 \f4Java Tutorial\fP @
duke@0 1710 .fi
bpatel@4900 1711 http://docs.oracle.com/javase/tutorial/ for examples of the use of \f3keytool\fP
duke@0 1712 .RE
duke@0 1713
duke@0 1714 .LP
duke@0 1715 .SH "CHANGES"
duke@0 1716 .LP
duke@0 1717 .LP
duke@0 1718 The command interface for keytool changed in Java SE 6.
duke@0 1719 .LP
duke@0 1720 .LP
duke@0 1721 \f3keytool\fP no longer displays password input when entered by users. Since password input can no longer be viewed when entered, users will be prompted to re\-enter passwords any time a password is being set or changed (for example, when setting the initial keystore password, or when changing a key password).
duke@0 1722 .LP
duke@0 1723 .LP
duke@0 1724 Some commands have simply been renamed, and other commands deemed obsolete are no longer listed in this document. All previous commands (both renamed and obsolete) are still supported in this release and will continue to be supported in future releases. The following summarizes all of the changes made to the keytool command interface:
duke@0 1725 .LP
duke@0 1726 .LP
duke@0 1727 Renamed commands:
duke@0 1728 .LP
duke@0 1729 .RS 3
duke@0 1730 .TP 2
duke@0 1731 o
duke@0 1732 \f2\-export\fP, renamed to \f2\-exportcert\fP
duke@0 1733 .TP 2
duke@0 1734 o
duke@0 1735 \f2\-genkey\fP, renamed to \f2\-genkeypair\fP
duke@0 1736 .TP 2
duke@0 1737 o
duke@0 1738 \f2\-import\fP, renamed to \f2\-importcert\fP
duke@0 1739 .RE
duke@0 1740
duke@0 1741 .LP
duke@0 1742 .LP
duke@0 1743 Commands deemed obsolete and no longer documented:
duke@0 1744 .LP
duke@0 1745 .RS 3
duke@0 1746 .TP 2
duke@0 1747 o
duke@0 1748 .na
duke@0 1749 \f2\-keyclone\fP @
duke@0 1750 .fi
bpatel@4176 1751 http://java.sun.com/j2se/1.5.0/docs/tooldocs/windows/keytool.html#keycloneCmd
duke@0 1752 .TP 2
duke@0 1753 o
duke@0 1754 .na
duke@0 1755 \f2\-identitydb\fP @
duke@0 1756 .fi
bpatel@4176 1757 http://java.sun.com/j2se/1.5.0/docs/tooldocs/windows/keytool.html#identitydbCmd
duke@0 1758 .TP 2
duke@0 1759 o
duke@0 1760 .na
duke@0 1761 \f2\-selfcert\fP @
duke@0 1762 .fi
bpatel@4176 1763 http://java.sun.com/j2se/1.5.0/docs/tooldocs/windows/keytool.html#selfcertCmd
duke@0 1764 .RE
duke@0 1765
duke@0 1766 .LP
duke@0 1767