." Copyright (c) 1998, 2011, 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.

."

.TH keytool 1 "10 May 2011"

.LP

.SH "Name"

keytool \- Key and Certificate Management Tool

.LP

.LP

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

.LP

.SH "SYNOPSIS"

.LP

.nf

\f3

.fl

\fP\f3keytool\fP [ commands ]

.fl

.fi

.LP

.LP

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.

.LP

.SH "DESCRIPTION"

.LP

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

.LP

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.

.LP

.LP

\f3keytool\fP also enables users to administer secret keys used in symmetric encryption/decryption (e.g. DES).

.LP

.LP

\f3keytool\fP stores the keys and certificates in a \f2keystore\fP.

.LP

.SH "COMMAND AND OPTION NOTES"

.LP

.LP

The various commands and their options are listed and described below. Note:

.LP

.RS 3

.TP 2

o

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

.TP 2

o

The options for each command may be provided in any order. 

.TP 2

o

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

.TP 2

o

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

.TP 2

o

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

.TP 2

o

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: 

.nf

\f3

.fl

  keytool \-printcert {\-file \fP\f4cert_file\fP\f3} {\-v}

.fl

\fP

.fi

.LP

When specifying a \f2\-printcert\fP command, replace \f2cert_file\fP with the actual file name, as in: 

.nf

\f3

.fl

  keytool \-printcert \-file VScert.cer

.fl

\fP

.fi

.TP 2

o

Option values must be quoted if they contain a blank (space). 

.TP 2

o

The \f2\-help\fP command is the default. Thus, the command line 

.nf

\f3

.fl

  keytool

.fl

\fP

.fi

.LP

is equivalent to 

.nf

\f3

.fl

  keytool \-help

.fl

\fP

.fi

.RE

.LP

.SS 

Option Defaults

.LP

.LP

Below are the defaults for various option values.

.LP

.nf

\f3

.fl

\-alias "mykey"

.fl

.fl

\-keyalg

.fl

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

.fl

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

.fl

.fl

\-keysize

.fl

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

.fl

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

.fl

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

.fl

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

.fl

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

.fl

.fl

.fl

\-validity 90

.fl

.fl

\-keystore the file named \fP\f4.keystore\fP\f3 in the user's home directory

.fl

.fl

\-storetype the value of the "keystore.type" property in the security properties file,

.fl

           which is returned by the static \fP\f4getDefaultType\fP\f3 method in

.fl

           \fP\f4java.security.KeyStore\fP\f3

.fl

.fl

\-file stdin if reading, stdout if writing

.fl

.fl

\-protected false

.fl

\fP

.fi

.LP

.LP

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

.LP

.RS 3

.TP 2

o

If the underlying private key is of type "DSA", the \f2\-sigalg\fP option defaults to "SHA1withDSA" 

.TP 2

o

If the underlying private key is of type "RSA", the \f2\-sigalg\fP option defaults to "SHA256withRSA". 

.TP 2

o

If the underlying private key is of type "EC", the \f2\-sigalg\fP option defaults to "SHA256withECDSA". 

.RE

.LP

.LP

Please consult the 

.na

\f2Java Cryptography Architecture API Specification & Reference\fP @

.fi

http://download.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.

.LP

.SS 

Common Options

.LP

.LP

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.

.LP

.LP

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.

.LP

.LP

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

.LP

.RS 3

.TP 3

\-storetype storetype 

.LP

This qualifier specifies the type of keystore to be instantiated.  

.TP 3

\-keystore keystore 

.LP

The keystore location. 

.LP

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 

.LP

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

.TP 3

\-storepass[:env|:file] argument 

.LP

The password which is used to protect the integrity of the keystore. 

.LP

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: 

.RS 3

.TP 2

o

\f2env\fP: Retrieve the password from the environment variable named \f2argument\fP 

.TP 2

o

\f2file\fP: Retrieve the password from the file named \f2argument\fP 

.RE

.LP

\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).) 

.LP

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. 

.LP

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.  

.TP 3

\-providerName provider_name 

.LP

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

.TP 3

\-providerClass provider_class_name 

.LP

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.  

.TP 3

\-providerArg provider_arg 

.LP

Used in conjunction with \f2\-providerClass\fP. Represents an optional string input argument for the constructor of \f2provider_class_name\fP.  

.TP 3

\-protected 

.LP

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. 

.LP

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.  

.TP 3

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

.LP

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.  

.RE

.LP

.LP

Currently keytool supports these named extensions (case\-insensitive):

.LP

.LP

.if \n+(b.=1 .nr d. \n(.c-\n(c.-1

.de 35

.ps \n(.s

.vs \n(.vu

.in \n(.iu

.if \n(.u .fi

.if \n(.j .ad

.if \n(.j=0 .na

..

.nf

.nr #~ 0

.if n .nr #~ 0.6n

.ds #d .d

.if \(ts\n(.z\(ts\(ts .ds #d nl

.fc

.nr 33 \n(.s

.rm 80 81

.nr 34 \n(.lu

.eo

.am 81

.br

.di a+

.35

.ft \n(.f

.ll \n(34u*1u/3u

.if \n(.l<\n(81 .ll \n(81u

.in 0

The full form: "ca:{true|false}[,pathlen:<len>]"; or, <len>, a shorthand for "ca:true,pathlen:<len>"; or omitted, means "ca:true"

.br

.di

.nr a| \n(dn

.nr a- \n(dl

..

.ec \

.eo

.am 81

.br

.di b+

.35

.ft \n(.f

.ll \n(34u*1u/3u

.if \n(.l<\n(81 .ll \n(81u

.in 0

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.

.br

.di

.nr b| \n(dn

.nr b- \n(dl

..

.ec \

.eo

.am 81

.br

.di c+

.35

.ft \n(.f

.ll \n(34u*1u/3u

.if \n(.l<\n(81 .ll \n(81u

.in 0

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.

.br

.di

.nr c| \n(dn

.nr c- \n(dl

..

.ec \

.eo

.am 80

.br

.di d+

.35

.ft \n(.f

.ll \n(34u*1u/3u

.if \n(.l<\n(80 .ll \n(80u

.in 0

SAN or SubjectAlternativeName

.br

.di

.nr d| \n(dn

.nr d- \n(dl

..

.ec \

.eo

.am 81

.br

.di e+

.35

.ft \n(.f

.ll \n(34u*1u/3u

.if \n(.l<\n(81 .ll \n(81u

.in 0

type:value(,type:value)*, type can be EMAIL, URI, DNS, IP, or OID, value is the string format value for the type.

.br

.di

.nr e| \n(dn

.nr e- \n(dl

..

.ec \

.eo

.am 80

.br

.di f+

.35

.ft \n(.f

.ll \n(34u*1u/3u

.if \n(.l<\n(80 .ll \n(80u

.in 0

IAN or IssuerAlternativeName

.br

.di

.nr f| \n(dn

.nr f- \n(dl

..

.ec \

.eo

.am 81

.br

.di g+

.35

.ft \n(.f

.ll \n(34u*1u/3u

.if \n(.l<\n(81 .ll \n(81u

.in 0

same as SubjectAlternativeName

.br

.di

.nr g| \n(dn

.nr g- \n(dl

..

.ec \

.eo

.am 81

.br

.di h+

.35

.ft \n(.f

.ll \n(34u*1u/3u

.if \n(.l<\n(81 .ll \n(81u

.in 0

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.

.br

.di

.nr h| \n(dn

.nr h- \n(dl

..

.ec \

.eo

.am 80

.br

.di i+

.35

.ft \n(.f

.ll \n(34u*1u/3u

.if \n(.l<\n(80 .ll \n(80u

.in 0

AIA or AuthorityInfoAccess

.br

.di

.nr i| \n(dn

.nr i- \n(dl

..

.ec \

.eo

.am 81

.br

.di j+

.35

.ft \n(.f

.ll \n(34u*1u/3u

.if \n(.l<\n(81 .ll \n(81u

.in 0

same as SubjectInfoAccess. method can be "ocsp","caIssuers" or any OID.

.br

.di

.nr j| \n(dn

.nr j- \n(dl

..

.ec \

.35

.nf

.ll \n(34u

.nr 80 0

.nr 38 \w\f3Name\fP

.if \n(80<\n(38 .nr 80 \n(38

.nr 38 \wBC or BasicConstraints

.if \n(80<\n(38 .nr 80 \n(38

.nr 38 \wKU or KeyUsage

.if \n(80<\n(38 .nr 80 \n(38

.nr 38 \wEKU or ExtendedkeyUsage

.if \n(80<\n(38 .nr 80 \n(38

.nr 38 \wSIA or SubjectInfoAccess

.if \n(80<\n(38 .nr 80 \n(38

.80

.rm 80

.nr 38 \n(d-

.if \n(80<\n(38 .nr 80 \n(38

.nr 38 \n(f-

.if \n(80<\n(38 .nr 80 \n(38

.nr 38 \n(i-

.if \n(80<\n(38 .nr 80 \n(38

.nr 81 0

.nr 38 \w\f3Value\fP

.if \n(81<\n(38 .nr 81 \n(38

.81

.rm 81

.nr 38 \n(a-

.if \n(81<\n(38 .nr 81 \n(38

.nr 38 \n(b-

.if \n(81<\n(38 .nr 81 \n(38

.nr 38 \n(c-

.if \n(81<\n(38 .nr 81 \n(38

.nr 38 \n(e-

.if \n(81<\n(38 .nr 81 \n(38

.nr 38 \n(g-

.if \n(81<\n(38 .nr 81 \n(38

.nr 38 \n(h-

.if \n(81<\n(38 .nr 81 \n(38

.nr 38 \n(j-

.if \n(81<\n(38 .nr 81 \n(38

.35

.nf

.ll \n(34u

.nr 38 1n

.nr 79 0