'\" t

.\"     Arch: generic

.\"     Software: JDK 8

.\"     SectDesc: Security Tools

.\"     Title: keytool.1

.\"

.if n .pl 99999

.SH NAME    

keytool \- Manages a keystore (database) of cryptographic keys, X\&.509 certificate chains, and trusted certificates\&.

.SH SYNOPSIS    

.sp     

.nf     

\fBkeytool\fR [\fIcommands\fR]

.fi     

.sp     

.TP     

\fIcommands\fR

See Commands\&. These commands are categorized by task as follows:

.RS     

.TP 0.2i    

\(bu

Create or Add Data to the Keystore

.RS     

.TP 0.2i    

\(bu

-gencert

.TP 0.2i    

\(bu

-genkeypair

.TP 0.2i    

\(bu

-genseckey

.TP 0.2i    

\(bu

-importcert

.TP 0.2i    

\(bu

-importpassword

.RE     

.TP 0.2i    

\(bu

Import Contents From Another Keystore

.RS     

.TP 0.2i    

\(bu

-importkeystore

.RE     

.TP 0.2i    

\(bu

Generate Certificate Request

.RS     

.TP 0.2i    

\(bu

-certreq

.RE     

.TP 0.2i    

\(bu

Export Data

.RS     

.TP 0.2i    

\(bu

-exportcert

.RE     

.TP 0.2i    

\(bu

Display Data

.RS     

.TP 0.2i    

\(bu

-list

.TP 0.2i    

\(bu

-printcert

.TP 0.2i    

\(bu

-printcertreq

.TP 0.2i    

\(bu

-printcrl

.RE     

.TP 0.2i    

\(bu

Manage the Keystore

.RS     

.TP 0.2i    

\(bu

-storepasswd

.TP 0.2i    

\(bu

-keypasswd

.TP 0.2i    

\(bu

-delete

.TP 0.2i    

\(bu

-changealias

.RE     

.TP 0.2i    

\(bu

Get Help

.RS     

.TP 0.2i    

\(bu

-help

.RE     

.RE     

.SH DESCRIPTION    

The \f3keytool\fR command is a key and certificate management utility\&. It enables users to administer their own public/private key pairs and associated certificates for use in self-authentication (where the user authenticates himself or herself to other users and services) or data integrity and authentication services, using digital signatures\&. The \f3keytool\fR command also enables users to cache the public keys (in the form of certificates) of their communicating peers\&.

.PP

A certificate is a digitally signed statement from one entity (person, company, and so on\&.), that says that the public key (and some other information) of some other entity has a particular value\&. (See Certificate\&.) When data is digitally signed, the signature can be verified to check the data integrity and authenticity\&. Integrity means that the data has not been modified or tampered with, and authenticity means the data comes from whoever claims to have created and signed it\&.

.PP

The \f3keytool\fR command also enables users to administer secret keys and passphrases used in symmetric encryption and decryption (DES)\&.

.PP

The \f3keytool\fR command stores the keys and certificates in a keystore\&. See KeyStore aliases\&.

.SH COMMAND\ AND\ OPTION\ NOTES    

See Commands for a listing and description of the various commands\&.

.TP 0.2i    

\(bu

All command and option names are preceded by a minus sign (-)\&.

.TP 0.2i    

\(bu

The options for each command can be provided in any order\&.

.TP 0.2i    

\(bu

All items not italicized or in braces or brackets are required to appear as is\&.

.TP 0.2i    

\(bu

Braces surrounding an option signify that a default value will be used when the option is not specified on the command line\&. See Option Defaults\&. Braces are also used around the \f3-v\fR, \f3-rfc\fR, and \f3-J\fR options, which only have meaning when they appear on the command line\&. They do not have any default values other than not existing\&.

.TP 0.2i    

\(bu

Brackets surrounding an option signify that the user is prompted for the values when the option is not specified on the command line\&. For the \f3-keypass\fR option, if you do not specify the option on the command line, then the \f3keytool\fR command first attempts to use the keystore password to recover the private/secret key\&. If this attempt fails, then the \f3keytool\fR command prompts you for the private/secret key password\&.

.TP 0.2i    

\(bu

Items in italics (option values) represent the actual values that must be supplied\&. For example, here is the format of the \f3-printcert\fR command:

.TP 0.2i    

\(bu

Option values must be put in quotation marks when they contain a blank (space)\&.

.TP 0.2i    

\(bu

The \f3-help\fR option is the default\&. The \f3keytool\fR command is the same as \f3keytool -help\fR\&.

.SH OPTION\ DEFAULTS    

The following examples show the defaults for various option values\&.

.sp     

.nf     

\f3\-alias "mykey"\fP

.fi     

.nf     

\f3\fP

.fi     

.nf     

\f3\-keyalg\fP

.fi     

.nf     

\f3    "DSA" (when using \-genkeypair)\fP

.fi     

.nf     

\f3    "DES" (when using \-genseckey)\fP

.fi     

.nf     

\f3\fP

.fi     

.nf     

\f3\-keysize\fP

.fi     

.nf     

\f3    2048 (when using \-genkeypair and \-keyalg is "RSA")\fP

.fi     

.nf     

\f3    1024 (when using \-genkeypair and \-keyalg is "DSA")\fP

.fi     

.nf     

\f3    256 (when using \-genkeypair and \-keyalg is "EC")\fP

.fi     

.nf     

\f3    56 (when using \-genseckey and \-keyalg is "DES")\fP

.fi     

.nf     

\f3    168 (when using \-genseckey and \-keyalg is "DESede")\fP

.fi     

.nf     

\f3\fP

.fi     

.nf     

\f3\-validity 90\fP

.fi     

.nf     

\f3\fP

.fi     

.nf     

\f3\-keystore <the file named \&.keystore in the user\&'s home directory>\fP

.fi     

.nf     

\f3\fP

.fi     

.nf     

\f3\-storetype <the value of the "keystore\&.type" property in the\fP

.fi     

.nf     

\f3    security properties file, which is returned by the static\fP

.fi     

.nf     

\f3    getDefaultType method in java\&.security\&.KeyStore>\fP

.fi     

.nf     

\f3\fP

.fi     

.nf     

\f3\-file\fP

.fi     

.nf     

\f3    stdin (if reading)\fP

.fi     

.nf     

\f3    stdout (if writing)\fP

.fi     

.nf     

\f3\fP

.fi     

.nf     

\f3\-protected false\fP

.fi     

.nf     

\f3\fP

.fi     

.sp     

In generating a public/private key pair, the signature algorithm (\f3-sigalg\fR option) is derived from the algorithm of the underlying private key:

.TP 0.2i    

\(bu

If the underlying private key is of type DSA, then the \f3-sigalg\fR option defaults to SHA1withDSA\&.

.TP 0.2i    

\(bu

If the underlying private key is of type RSA, then the \f3-sigalg\fR option defaults to SHA256withRSA\&.

.TP 0.2i    

\(bu

If the underlying private key is of type EC, then the \f3-sigalg\fR option defaults to SHA256withECDSA\&.

.PP

For a full list of \f3-keyalg\fR and \f3-sigalg\fR arguments, see Java Cryptography Architecture (JCA) Reference Guide at http://docs\&.oracle\&.com/javase/8/docs/technotes/guides/security/crypto/CryptoSpec\&.html#AppA

.SH COMMON\ OPTIONS    

The \f3-v\fR option can appear for all commands except \f3-help\fR\&. When the \f3-v\fR option appears, it signifies verbose mode, which means that more information is provided in the output\&.

.PP

There is also a \f3-Jjavaoption\fR argument that can appear for any command\&. When the \f3-Jjavaoption\fR appears, the specified \f3javaoption\fR string is passed directly to the Java interpreter\&. This option does not contain any spaces\&. It is useful for adjusting the execution environment or memory usage\&. For a list of possible interpreter options, type \f3java -h\fR or \f3java -X\fR at the command line\&.

.PP

These options can appear for all commands operating on a keystore:

.TP

-storetype \fIstoretype\fR

.br

This qualifier specifies the type of keystore to be instantiated\&.

.TP

-keystore \fIkeystore\fR

.br

The keystore location\&.

If the JKS \f3storetype\fR is used and a keystore file does not yet exist, then certain \f3keytool\fR commands can result in a new keystore file being created\&. For example, if \f3keytool -genkeypair\fR is called and the \f3-keystore\fR option is not specified, the default keystore file named \f3\&.keystore\fR in the user\&'s home directory is created when it does not already exist\&. Similarly, if the \f3-keystore ks_file\fR option is specified but ks_file does not exist, then it is created\&. For more information on the JKS \f3storetype\fR, see the \fIKeyStore Implementation\fR section in KeyStore aliases\&.

Note that the input stream from the \f3-keystore\fR option is passed to the \f3KeyStore\&.load\fR method\&. If \f3NONE\fR is specified as the URL, then a null stream is passed to the \f3KeyStore\&.load\fR method\&. \f3NONE\fR should be specified if the keystore is not file-based\&. For example, when it resides on a hardware token device\&.

.TP

-storepass[:\fIenv\fR| :\fIfile\fR] argument

.br

The password that is used to protect the integrity of the keystore\&.

If the modifier \f3env\fR or \f3file\fR is not specified, then the password has the \f3value\fR argument, which must be at least 6 characters long\&. Otherwise, the password is retrieved as follows:

.RS     

.TP 0.2i    

\(bu

\f3env\fR: Retrieve the password from the environment variable named \f3argument\fR\&.

.TP 0.2i    

\(bu

\f3file\fR: Retrieve the password from the file named argument\&.

.RE     

\fINote:\fR All other options that require passwords, such as \f3-keypass\fR, \f3-srckeypass\fR, -\f3destkeypass\fR, \f3-srcstorepass\fR, and \f3-deststorepass\fR, accept the \fIenv\fR and \fIfile\fR modifiers\&. Remember to separate the password option and the modifier with a colon (:)\&.

The password must be provided to all commands that access the keystore contents\&. For such commands, when the \f3-storepass\fR option is not provided at the command line, the user is prompted for it\&.

When retrieving information from the keystore, the password is optional\&. If no password is specified, then the integrity of the retrieved information cannot be verified and a warning is displayed\&.

.TP

-providerName \fIprovider_name\fR

.br

Used to identify a cryptographic service provider\&'s name when listed in the security properties file\&.

.TP

-providerClass \fIprovider_class_name\fR

.br

Used to specify the name of a cryptographic service provider\&'s master class file when the service provider is not listed in the security properties file\&.

.TP

-providerArg \fIprovider_arg\fR

.br

Used with the \f3-providerClass\fR option to represent an optional string input argument for the constructor of \f3provider_class_name\fR\&.

.TP

-protected

.br

Either \f3true\fR or \f3false\fR\&. This value should be specified as \f3true\fR when a password must be specified by way of a protected authentication path such as a dedicated PIN reader\&.Because there are two keystores involved in the \f3-importkeystore\fR command, the following two options \f3-srcprotected\fR and -\f3destprotected\fR are provided for the source keystore and the destination keystore respectively\&.

.TP

-ext \fI{name{:critical} {=value}}\fR

.br

Denotes an X\&.509 certificate extension\&. The option can be used in \f3-genkeypair\fR and \f3-gencert\fR to embed extensions into the certificate generated, or in \f3-certreq\fR to show what extensions are requested in the certificate request\&. The option can appear multiple times\&. The \f3name\fR argument can be a supported extension name (see Named Extensions) or an arbitrary OID number\&. The \f3value\fR argument, when provided, denotes the argument for the extension\&. When \fIvalue\fR is omitted, that means that the default value of the extension or the extension requires no argument\&. The \f3:critical\fR modifier, when provided, means the extension\&'s \f3isCritical\fR attribute is \f3true\fR; otherwise, it is \f3false\fR\&. You can use \f3:c\fR in place of \f3:critical\fR\&.

.SH NAMED\ EXTENSIONS    

The \f3keytool\fR command supports these named extensions\&. The names are not case-sensitive)\&.

.TP     

BC or BasicContraints

\fIValues\fR: The full form is: \f3ca:{true|false}[,pathlen:<len>]\fR or \f3<len>\fR, which is short for \f3ca:true,pathlen:<len>\fR\&. When <\f3len\fR> is omitted, you have \f3ca:true\fR\&.

.TP     

KU or KeyUsage

\fIValues\fR: \f3usage\fR(,\f3usage\fR)*, where \fIusage\fR can be one of \f3digitalSignature\fR, \f3nonRepudiation\fR (contentCommitment), \f3keyEncipherment\fR, \f3dataEncipherment\fR, \f3keyAgreement\fR, \f3keyCertSign\fR, \f3cRLSign\fR, \f3encipherOnly\fR, \f3decipherOnly\fR\&. The \fIusage\fR argument can be abbreviated with the first few letters (\f3dig\fR for \f3digitalSignature\fR) or in camel-case style (\f3dS\fR for \f3digitalSignature\fR or \f3cRLS\fR for \f3cRLSign\fR), as long as no ambiguity is found\&. The \f3usage\fR values are case-sensitive\&.

.TP     

EKU or ExtendedKeyUsage

\fIValues\fR: \f3usage\fR(,\f3usage\fR)*, where \fIusage\fR can be one of \f3anyExtendedKeyUsage\fR, \f3serverAuth\fR, \f3clientAuth\fR, \f3codeSigning\fR, \f3emailProtection\fR, \f3timeStamping\fR, \f3OCSPSigning\fR, or any \fIOID string\fR\&. The \fIusage\fR argument can be abbreviated with the first few letters or in camel-case style, as long as no ambiguity is found\&. The \f3usage\fR values are case-sensitive\&.

.TP     

SAN or SubjectAlternativeName

\fIValues\fR: \f3type\fR:\f3value\fR(,t\f3ype:value\fR)*, where \f3type\fR can be \f3EMAIL\fR, \f3URI\fR, \f3DNS\fR, \f3IP\fR, or \f3OID\fR\&. The \f3value\fR argument is the string format value for the \f3type\fR\&.

.TP     

IAN or IssuerAlternativeName

\fIValues\fR: Same as \f3SubjectAlternativeName\fR\&.

.TP     

SIA or SubjectInfoAccess

\fIValues\fR: \f3method\fR:\f3location-type\fR:\f3location-value\fR (,\f3method:location-type\fR:\f3location-value\fR)*, where \f3method\fR can be \f3timeStamping\fR, \f3caRepository\fR or any OID\&. The \f3location-type\fR and \f3location-value\fR arguments can be any \f3type\fR:\f3value\fR supported by the \f3SubjectAlternativeName\fR extension\&.

.TP     

AIA or AuthorityInfoAccess

\fIValues\fR: Same as \f3SubjectInfoAccess\fR\&. The \f3method\fR argument can be \f3ocsp\fR,\f3caIssuers\fR, or any OID\&.

.PP

When \f3name\fR is OID, the value is the hexadecimal dumped DER encoding of the \f3extnValue\fR for the extension excluding the OCTET STRING type and length bytes\&. Any extra character other than standard hexadecimal numbers (0-9, a-f, A-F) are ignored in the HEX string\&. Therefore, both 01:02:03:04 and 01020304 are accepted as identical values\&. When there is no value, the extension has an empty value field\&.

.PP

A special name \f3honored\fR, used in \f3-gencert\fR only, denotes how the extensions included in the certificate request should be honored\&. The value for this name is a comma separated list of \f3all\fR (all requested extensions are honored), \f3name{:[critical|non-critical]}\fR (the named extension is honored, but using a different \f3isCritical\fR attribute) and \f3-name\fR (used with \f3all\fR, denotes an exception)\&. Requested extensions are not honored by default\&.

.PP

If, besides the\f3-ext honored\fR option, another named or OID \f3-ext\fR option is provided, this extension is added to those already honored\&. However, if this name (or OID) also appears in the honored value, then its value and criticality overrides the one in the request\&.

.PP

The \f3subjectKeyIdentifier\fR extension is always created\&. For non-self-signed certificates, the \f3authorityKeyIdentifier\fR is created\&.

.PP

\fINote:\fR Users should be aware that some combinations of extensions (and other certificate fields) may not conform to the Internet standard\&. See Certificate Conformance Warning\&.

.SH COMMANDS    

-gencert

Generates a certificate as a response to a certificate request file (which can be created by the \f3keytool\fR\f3-certreq\fR command)\&. The command reads the request from \fIinfile\fR (if omitted, from the standard input), signs it using alias\&'s private key, and outputs the X\&.509 certificate into \fIoutfile\fR (if omitted, to the standard output)\&. When\f3-rfc\fR is specified, the output format is Base64-encoded PEM; otherwise, a binary DER is created\&.

The \f3sigalg\fR value specifies the algorithm that should be used to sign the certificate\&. The \f3startdate\fR argument is the start time and date that the certificate is valid\&. The \f3valDays\fR argument tells the number of days for which the certificate should be considered valid\&.

When \f3dname\fR is provided, it is used as the subject of the generated certificate\&. Otherwise, the one from the certificate request is used\&.

The \f3ext\fR value shows what X\&.509 extensions will be embedded in the certificate\&. Read Common Options for the grammar of \f3-ext\fR\&.

The \f3-gencert\fR option enables you to create certificate chains\&. The following example creates a certificate, \f3e1\fR, that contains three certificates in its certificate chain\&.

The following commands creates four key pairs named \f3ca\fR, \f3ca1\fR, \f3ca2\fR, and \f3e1\fR:

.sp     

.nf     

\f3keytool \-alias ca \-dname CN=CA \-genkeypair\fP

.fi     

.nf     

\f3keytool \-alias ca1 \-dname CN=CA \-genkeypair\fP

.fi     

.nf     

\f3keytool \-alias ca2 \-dname CN=CA \-genkeypair\fP

.fi     

.nf     

\f3keytool \-alias e1 \-dname CN=E1 \-genkeypair\fP

.fi     

.nf     

\f3\fP

.fi     

.sp     

The following two commands create a chain of signed certificates; \f3ca\fR signs \f3ca1\fR and \f3ca1\fR signs \f3ca2\fR, all of which are self-issued:

.sp     

.nf     

\f3keytool \-alias ca1 \-certreq |\fP

.fi     

.nf     

\f3    keytool \-alias ca \-gencert \-ext san=dns:ca1 |\fP

.fi     

.nf     

\f3    keytool \-alias ca1 \-importcert\fP

.fi     

.nf     

\f3\fP

.fi     

.nf     

\f3keytool \-alias ca2 \-certreq |\fP

.fi     

.nf     

\f3    $KT \-alias ca1 \-gencert \-ext san=dns:ca2 |\fP

.fi     

.nf     

\f3    $KT \-alias ca2 \-importcert\fP

.fi     

.nf     

\f3\fP

.fi     

.sp     

The following command creates the certificate \f3e1\fR and stores it in the file \f3e1\&.cert\fR, which is signed by \f3ca2\fR\&. As a result, \f3e1\fR should contain \f3ca\fR, \f3ca1\fR, and \f3ca2\fR in its certificate chain:

.sp     

.nf     

\f3keytool \-alias e1 \-certreq | keytool \-alias ca2 \-gencert > e1\&.cert\fP

.fi     

.nf     

\f3\fP

.fi