'\" t

.\" Copyright (c) 1998, 2015, Oracle and/or its affiliates. All rights reserved.

.\" DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.

.\"

.\" This code is free software; you can redistribute it and/or modify it

.\" under the terms of the GNU General Public License version 2 only, as

.\" published by the Free Software Foundation.

.\"

.\" This code is distributed in the hope that it will be useful, but WITHOUT

.\" ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or

.\" FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License

.\" version 2 for more details (a copy is included in the LICENSE file that

.\" accompanied this code).

.\"

.\" You should have received a copy of the GNU General Public License version

.\" 2 along with this work; if not, write to the Free Software Foundation,

.\" Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.

.\"

.\" Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA

.\" or visit www.oracle.com if you need additional information or have any

.\" questions.

.\"

.\"     Arch: generic

.\"     Software: JDK 8

.\"     Date: 03 March 2015

.\"     SectDesc: Security Tools

.\"     Title: keytool.1

.\"

.if n .pl 99999

.TH keytool 1 "03 March 2015" "JDK 8" "Security Tools"

.\" -----------------------------------------------------------------

.\" * Define some portability stuff

.\" -----------------------------------------------------------------

.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.\" http://bugs.debian.org/507673

.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html

.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.ie \n(.g .ds Aq \(aq

.el       .ds Aq '

.\" -----------------------------------------------------------------

.\" * set default formatting

.\" -----------------------------------------------------------------

.\" disable hyphenation

.nh

.\" disable justification (adjust text to left margin only)

.ad l

.\" -----------------------------------------------------------------

.\" * MAIN CONTENT STARTS HERE *

.\" -----------------------------------------------------------------

.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:

.sp     

.nf     

\f3keytool \-printcert {\-file \fIcert_file\fR} {\-v}\fP

.fi     

.sp     

When you specify a \f3-printcert\fR command, replace \fIcert_file\fR with the actual file name, as follows: \f3keytool -printcert -file VScert\&.cer\fR

.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    

.TP     

-gencert

.sp     

.nf     

\f3{\-rfc} {\-infile \fIinfile\fR} {\-outfile \fIoutfile\fR} {\-alias \fIalias\fR} {\-sigalg \fIsigalg\fR}\fP

.fi     

.sp     

.sp     

.nf     

\f3{\-dname \fIdname\fR} {\-startdate \fIstartdate\fR {\-ext \fIext\fR}* {\-validity \fIvalDays\fR}\fP

.fi     

.sp     

.sp     

.nf     

\f3[\-keypass \fIkeypass\fR] {\-keystore \fIkeystore\fR} [\-storepass \fIstorepass\fR]\fP

.fi     

.sp     

.sp     

.nf     

\f3{\-storetype \fIstoretype\fR} {\-providername \fIprovider_name\fR}\fP

.fi     

.sp     

.sp     

.nf     

\f3{\-providerClass \fIprovider_class_name\fR {\-providerArg \fIprovider_arg\fR}}\fP

.fi     

.sp     

.sp     

.nf     

\f3{\-v} {\-protected} {\-Jjavaoption}\fP

.fi     

.sp     

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