.\"t

.\" Copyright (c) 1994, 2019, 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.

.\"

.\" Automatically generated by Pandoc 2.3.1

.\"

.TH "KEYTOOL" "1" "2019" "JDK 13" "JDK Commands"

.hy

.SH NAME

.PP

keytool \- a key and certificate management utility

.SH SYNOPSIS

.PP

\f[CB]keytool\f[R] [\f[I]commands\f[R]]

.TP

.B \f[I]commands\f[R]

Commands for \f[CB]keytool\f[R] include the following:

.RS

.IP \[bu] 2

\f[CB]\-certreq\f[R]: Generates a certificate request

.IP \[bu] 2

\f[CB]\-changealias\f[R]: Changes an entry\[aq]s alias

.IP \[bu] 2

\f[CB]\-delete\f[R]: Deletes an entry

.IP \[bu] 2

\f[CB]\-exportcert\f[R]: Exports certificate

.IP \[bu] 2

\f[CB]\-genkeypair\f[R]: Generates a key pair

.IP \[bu] 2

\f[CB]\-genseckey\f[R]: Generates a secret key

.IP \[bu] 2

\f[CB]\-gencert\f[R]: Generates a certificate from a certificate request

.IP \[bu] 2

\f[CB]\-importcert\f[R]: Imports a certificate or a certificate chain

.IP \[bu] 2

\f[CB]\-importpass\f[R]: Imports a password

.IP \[bu] 2

\f[CB]\-importkeystore\f[R]: Imports one or all entries from another

keystore

.IP \[bu] 2

\f[CB]\-keypasswd\f[R]: Changes the key password of an entry

.IP \[bu] 2

\f[CB]\-list\f[R]: Lists entries in a keystore

.IP \[bu] 2

\f[CB]\-printcert\f[R]: Prints the content of a certificate

.IP \[bu] 2

\f[CB]\-printcertreq\f[R]: Prints the content of a certificate request

.IP \[bu] 2

\f[CB]\-printcrl\f[R]: Prints the content of a Certificate Revocation List

(CRL) file

.IP \[bu] 2

\f[CB]\-storepasswd\f[R]: Changes the store password of a keystore

.IP \[bu] 2

\f[CB]\-showinfo\f[R]: Displays security\-related information

.PP

See \f[B]Commands and Options\f[R] for a description of these commands

with their options.

.RE

.SH DESCRIPTION

.PP

The \f[CB]keytool\f[R] 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 a user

authenticates themselves to other users and services) or data integrity

and authentication services, by using digital signatures.

The \f[CB]keytool\f[R] 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), which says that the public key (and some other

information) of some other entity has a particular value.

When data is digitally signed, the signature can be verified to check

the data integrity and authenticity.

Integrity means that the data hasn\[aq]t been modified or tampered with,

and authenticity means that the data comes from the individual who

claims to have created and signed it.

.PP

The \f[CB]keytool\f[R] command also enables users to administer secret

keys and passphrases used in symmetric encryption and decryption (Data

Encryption Standard).

It can also display other security\-related information.

.PP

The \f[CB]keytool\f[R] command stores the keys and certificates in a

keystore.

.SH COMMAND AND OPTION NOTES

.PP

The following notes apply to the descriptions in \f[B]Commands and

Options\f[R]:

.IP \[bu] 2

All command and option names are preceded by a hyphen sign

(\f[CB]\-\f[R]).

.IP \[bu] 2

Only one command can be provided.

.IP \[bu] 2

Options for each command can be provided in any order.

.IP \[bu] 2

There are two kinds of options, one is single\-valued which should be

only provided once.

If a single\-valued option is provided multiple times, the value of the

last one is used.

The other type is multi\-valued, which can be provided multiple times

and all values are used.

The only multi\-valued option currently supported is the \f[CB]\-ext\f[R]

option used to generate X.509v3 certificate extensions.

.IP \[bu] 2

All items not italicized or in braces ({ }) or brackets ([ ]) are

required to appear as is.

.IP \[bu] 2

Braces surrounding an option signify that a default value is used when

the option isn\[aq]t specified on the command line.

Braces are also used around the \f[CB]\-v\f[R], \f[CB]\-rfc\f[R], and

\f[CB]\-J\f[R] options, which have meaning only when they appear on the

command line.

They don\[aq]t have any default values.

.IP \[bu] 2

Brackets surrounding an option signify that the user is prompted for the

values when the option isn\[aq]t specified on the command line.

For the \f[CB]\-keypass\f[R] option, if you don\[aq]t specify the option

on the command line, then the \f[CB]keytool\f[R] command first attempts to

use the keystore password to recover the private/secret key.

If this attempt fails, then the \f[CB]keytool\f[R] command prompts you for

the private/secret key password.

.IP \[bu] 2

Items in italics (option values) represent the actual values that must

be supplied.

For example, here is the format of the \f[CB]\-printcert\f[R] command:

.RS 2

.RS

.PP

\f[CB]keytool\ \-printcert\f[R] {\f[CB]\-file\f[R] \f[I]cert_file\f[R]}

{\f[CB]\-v\f[R]}

.RE

.PP

When you specify a \f[CB]\-printcert\f[R] command, replace

\f[I]cert_file\f[R] with the actual file name, as follows:

\f[CB]keytool\ \-printcert\ \-file\ VScert.cer\f[R]

.RE

.IP \[bu] 2

Option values must be enclosed in quotation marks when they contain a

blank (space).

.SH COMMANDS AND OPTIONS

.PP

The keytool commands and their options can be grouped by the tasks that

they perform.

.PP

\f[B]Commands for Creating or Adding Data to the Keystore\f[R]:

.IP \[bu] 2

\f[CB]\-gencert\f[R]

.IP \[bu] 2

\f[CB]\-genkeypair\f[R]

.IP \[bu] 2

\f[CB]\-genseckey\f[R]

.IP \[bu] 2

\f[CB]\-importcert\f[R]

.IP \[bu] 2

\f[CB]\-importpass\f[R]

.PP

\f[B]Commands for Importing Contents from Another Keystore\f[R]:

.IP \[bu] 2

\f[CB]\-importkeystore\f[R]

.PP

\f[B]Commands for Generating a Certificate Request\f[R]:

.IP \[bu] 2

\f[CB]\-certreq\f[R]

.PP

\f[B]Commands for Exporting Data\f[R]:

.IP \[bu] 2

\f[CB]\-exportcert\f[R]

.PP

\f[B]Commands for Displaying Data\f[R]:

.IP \[bu] 2

\f[CB]\-list\f[R]

.IP \[bu] 2

\f[CB]\-printcert\f[R]

.IP \[bu] 2

\f[CB]\-printcertreq\f[R]

.IP \[bu] 2

\f[CB]\-printcrl\f[R]

.PP

\f[B]Commands for Managing the Keystore\f[R]:

.IP \[bu] 2

\f[CB]\-storepasswd\f[R]

.IP \[bu] 2

\f[CB]\-keypasswd\f[R]

.IP \[bu] 2

\f[CB]\-delete\f[R]

.IP \[bu] 2

\f[CB]\-changealias\f[R]

.PP

\f[B]Commands for Displaying Security\-related Information\f[R]:

.IP \[bu] 2

\f[CB]\-showinfo\f[R]

.SH COMMANDS FOR CREATING OR ADDING DATA TO THE KEYSTORE

.TP

.B \f[CB]\-gencert\f[R]

The following are the available options for the \f[CB]\-gencert\f[R]

command:

.RS

.IP \[bu] 2

{\f[CB]\-rfc\f[R]}: Output in RFC (Request For Comment) style

.IP \[bu] 2

{\f[CB]\-infile\f[R] \f[I]infile\f[R]}: Input file name

.IP \[bu] 2

{\f[CB]\-outfile\f[R] \f[I]outfile\f[R]}: Output file name

.IP \[bu] 2

{\f[CB]\-alias\f[R] \f[I]alias\f[R]}: Alias name of the entry to process

.IP \[bu] 2

{\f[CB]\-sigalg\f[R] \f[I]sigalg\f[R]}: Signature algorithm name

.IP \[bu] 2

{\f[CB]\-dname\f[R] \f[I]dname\f[R]}: Distinguished name

.IP \[bu] 2

{\f[CB]\-startdate\f[R] \f[I]startdate\f[R]}: Certificate validity start

date and time

.IP \[bu] 2

{\f[CB]\-ext\f[R] \f[I]ext\f[R]}*: X.509 extension

.IP \[bu] 2

{\f[CB]\-validity\f[R] \f[I]days\f[R]}: Validity number of days

.IP \[bu] 2

[\f[CB]\-keypass\f[R] \f[I]arg\f[R]]: Key password

.IP \[bu] 2

{\f[CB]\-keystore\f[R] \f[I]keystore\f[R]}: Keystore name

.IP \[bu] 2

[\f[CB]\-storepass\f[R] \f[I]arg\f[R]]: Keystore password

.IP \[bu] 2

{\f[CB]\-storetype\f[R] \f[I]type\f[R]}: Keystore type

.IP \[bu] 2

{\f[CB]\-providername\f[R] \f[I]name\f[R]}: Provider name

.IP \[bu] 2

{\f[CB]\-addprovider\f[R] \f[I]name\f[R] [\f[CB]\-providerarg\f[R]

\f[I]arg\f[R]]}: Adds a security provider by name (such as SunPKCS11)

with an optional configure argument.

The value of the security provider is the name of a security provider

that is defined in a module.

.RS 2

.PP

For example,

.RS

.PP

\f[CB]keytool\ \-addprovider\ SunPKCS11\ \-providerarg\ some.cfg\ ...\f[R]

.RE

.PP

\f[B]Note:\f[R]

.PP

For compatibility reasons, the SunPKCS11 and OracleUcrypto providers can

still be loaded with

\f[CB]\-providerclass\ sun.security.pkcs11.SunPKCS11\f[R] and

\f[CB]\-providerclass\ com.oracle.security.crypto.UcryptoProvider\f[R]

even if they are now defined in modules.

These are the only modules included in JDK that need a configuration,

and therefore the most widely used with the \f[CB]\-providerclass\f[R]

option.

For legacy security providers located on classpath and loaded by

reflection, \f[CB]\-providerclass\f[R] should still be used.

.RE

.IP \[bu] 2

{\f[CB]\-providerclass\f[R] \f[I]class\f[R] [\f[CB]\-providerarg\f[R]

\f[I]arg\f[R]]}: Add security provider by fully qualified class name with

an optional configure argument.

.RS 2

.PP

For example, if \f[CB]MyProvider\f[R] is a legacy provider loaded via

reflection,

.RS

.PP

\f[CB]keytool\ \-providerclass\ com.example.MyProvider\ ...\f[R]

.RE

.RE

.IP \[bu] 2

{\f[CB]\-providerpath\f[R] \f[I]list\f[R]}: Provider classpath

.IP \[bu] 2

{\f[CB]\-v\f[R]}: Verbose output

.IP \[bu] 2

{\f[CB]\-protected\f[R]}: Password provided through a protected mechanism

.PP

Use the \f[CB]\-gencert\f[R] command to generate a certificate as a

response to a certificate request file (which can be created by the

\f[CB]keytool\ \-certreq\f[R] command).

The command reads the request either from \f[I]infile\f[R] or, if

omitted, from the standard input, signs it by using the alias\[aq]s

private key, and outputs the X.509 certificate into either

\f[I]outfile\f[R] or, if omitted, to the standard output.

When \f[CB]\-rfc\f[R] is specified, the output format is Base64\-encoded

PEM; otherwise, a binary DER is created.

.PP

The \f[CB]\-sigalg\f[R] value specifies the algorithm that should be used

to sign the certificate.

The \f[I]startdate\f[R] argument is the start time and date that the

certificate is valid.

The \f[I]days\f[R] argument tells the number of days for which the

certificate should be considered valid.

.PP

When \f[I]dname\f[R] is provided, it is used as the subject of the

generated certificate.

Otherwise, the one from the certificate request is used.

.PP

The \f[CB]\-ext\f[R] value shows what X.509 extensions will be embedded in

the certificate.

Read \f[B]Common Command Options\f[R] for the grammar of \f[CB]\-ext\f[R].

.PP

The \f[CB]\-gencert\f[R] option enables you to create certificate chains.

The following example creates a certificate, \f[CB]e1\f[R], that contains

three certificates in its certificate chain.

.PP

The following commands creates four key pairs named \f[CB]ca\f[R],

\f[CB]ca1\f[R], \f[CB]ca2\f[R], and \f[CB]e1\f[R]:

.IP

.nf

\f[CB]

keytool\ \-alias\ ca\ \-dname\ CN=CA\ \-genkeypair

keytool\ \-alias\ ca1\ \-dname\ CN=CA\ \-genkeypair

keytool\ \-alias\ ca2\ \-dname\ CN=CA\ \-genkeypair

keytool\ \-alias\ e1\ \-dname\ CN=E1\ \-genkeypair

\f[R]

.fi

.PP

The following two commands create a chain of signed certificates;

\f[CB]ca\f[R] signs \f[CB]ca1\f[R] and \f[CB]ca1\f[R] signs \f[CB]ca2\f[R], all

of which are self\-issued:

.IP

.nf

\f[CB]

keytool\ \-alias\ ca1\ \-certreq\ |

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

\ \ \ \ keytool\ \-alias\ ca1\ \-importcert

keytool\ \-alias\ ca2\ \-certreq\ |

\ \ \ \ keytool\ \-alias\ ca1\ \-gencert\ \-ext\ san=dns:ca2\ |

\ \ \ \ keytool\ \-alias\ ca2\ \-importcert

\f[R]

.fi

.PP

The following command creates the certificate \f[CB]e1\f[R] and stores it

in the \f[CB]e1.cert\f[R] file, which is signed by \f[CB]ca2\f[R].

As a result, \f[CB]e1\f[R] should contain \f[CB]ca\f[R], \f[CB]ca1\f[R], and

\f[CB]ca2\f[R] in its certificate chain:

.RS

.PP

\f[CB]keytool\ \-alias\ e1\ \-certreq\ |\ keytool\ \-alias\ ca2\ \-gencert\ >\ e1.cert\f[R]

.RE

.RE

.TP

.B \f[CB]\-genkeypair\f[R]

The following are the available options for the \f[CB]\-genkeypair\f[R]

command:

.RS

.IP \[bu] 2

{\f[CB]\-alias\f[R] \f[I]alias\f[R]}: Alias name of the entry to process

.IP \[bu] 2

{\f[CB]\-keyalg\f[R] \f[I]alg\f[R]}: Key algorithm name

.IP \[bu] 2

{\f[CB]\-keysize\f[R] \f[I]size\f[R]}: Key bit size

.IP \[bu] 2

{\f[CB]\-groupname\f[R] \f[I]name\f[R]}: Group name.

For example, an Elliptic Curve name.

.IP \[bu] 2

{\f[CB]\-sigalg\f[R] \f[I]alg\f[R]}: Signature algorithm name

.IP \[bu] 2

[\f[CB]\-dname\f[R] \f[I]name\f[R]]: Distinguished name

.IP \[bu] 2

{\f[CB]\-startdate\f[R] \f[I]date\f[R]}: Certificate validity start date

and time

.IP \[bu] 2

[\f[CB]\-ext\f[R] \f[I]value\f[R]}*: X.509 extension

.IP \[bu] 2

{\f[CB]\-validity\f[R] \f[I]days\f[R]}: Validity number of days

.IP \[bu] 2

[\f[CB]\-keypass\f[R] \f[I]arg\f[R]]: Key password

.IP \[bu] 2

{\f[CB]\-keystore\f[R] \f[I]keystore\f[R]}: Keystore name

.IP \[bu] 2

[\f[CB]\-storepass\f[R] \f[I]arg\f[R]]: Keystore password

.IP \[bu] 2

{\f[CB]\-storetype\f[R] \f[I]type\f[R]}: Keystore type

.IP \[bu] 2

{\f[CB]\-providername\f[R] \f[I]name\f[R]}: Provider name

.IP \[bu] 2

{\f[CB]\-addprovider\f[R] \f[I]name\f[R] [\f[CB]\-providerarg\f[R]

\f[I]arg\f[R]]}: Add security provider by name (such as SunPKCS11) with

an optional configure argument.

.IP \[bu] 2

{\f[CB]\-providerclass\f[R] \f[I]class\f[R] [\f[CB]\-providerarg\f[R]

\f[I]arg\f[R]] }: Add security provider by fully qualified class name

with an optional configure argument.

.IP \[bu] 2

{\f[CB]\-providerpath\f[R] \f[I]list\f[R]}: Provider classpath

.IP \[bu] 2

{\f[CB]\-v\f[R]}: Verbose output

.IP \[bu] 2

{\f[CB]\-protected\f[R]}: Password provided through a protected mechanism

.PP

Use the \f[CB]\-genkeypair\f[R] command to generate a key pair (a public

key and associated private key).

Wraps the public key in 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 that is identified by its alias.

.PP

The \f[CB]\-keyalg\f[R] value specifies the algorithm to be used to

generate the key pair, and the \f[CB]\-keysize\f[R] value specifies the

size of each key to be generated.

The \f[CB]\-sigalg\f[R] value specifies the algorithm that should be used

to sign the self\-signed certificate.

This algorithm must be compatible with the \f[CB]\-keyalg\f[R] value.

.PP

The \f[CB]\-groupname\f[R] value specifies the named group (for example,

the standard or predefined name of an Elliptic Curve) of the key to be

generated.

Only one of \f[CB]\-groupname\f[R] and \f[CB]\-keysize\f[R] can be

specified.

.PP

The \f[CB]\-dname\f[R] value specifies the X.500 Distinguished Name to be

associated with the value of \f[CB]\-alias\f[R], and is used as the issuer

and subject fields in the self\-signed certificate.

If a distinguished name is not provided at the command line, then the

user is prompted for one.

.PP

The value of \f[CB]\-keypass\f[R] is a password used to protect the

private key of the generated key pair.

If a password is not provided, then the user is prompted for it.

If you press the \f[B]Return\f[R] key at the prompt, then the key

password is set to the same password as the keystore password.

The \f[CB]\-keypass\f[R] value must have at least six characters.

.PP

The value of \f[CB]\-startdate\f[R] specifies the issue time of the

certificate, also known as the "Not Before" value of the X.509

certificate\[aq]s Validity field.

.PP

The option value can be set in one of these two forms:

.PP

([\f[CB]+\-\f[R]]\f[I]nnn\f[R][\f[CB]ymdHMS\f[R]])+

.PP

[\f[I]yyyy\f[R]\f[CB]/\f[R]\f[I]mm\f[R]\f[CB]/\f[R]\f[I]dd\f[R]]

[\f[I]HH\f[R]\f[CB]:\f[R]\f[I]MM\f[R]\f[CB]:\f[R]\f[I]SS\f[R]]

.PP

With the first form, the issue time is shifted by the specified value

from the current time.

The value is a concatenation of a sequence of subvalues.

Inside each subvalue, the plus sign (+) means shift forward, and the

minus sign (\-) means shift backward.

The time to be shifted is \f[I]nnn\f[R] units of years, months, days,

hours, minutes, or seconds (denoted by a single character of \f[CB]y\f[R],

\f[CB]m\f[R], \f[CB]d\f[R], \f[CB]H\f[R], \f[CB]M\f[R], or \f[CB]S\f[R]

respectively).

The exact value of the issue time is calculated by using the

\f[CB]java.util.GregorianCalendar.add(int\ field,\ int\ amount)\f[R]

method on each subvalue, from left to right.

For example, the issue time can be specified by:

.IP

.nf

\f[CB]

Calendar\ c\ =\ new\ GregorianCalendar();

c.add(Calendar.YEAR,\ \-1);

c.add(Calendar.MONTH,\ 1);

c.add(Calendar.DATE,\ \-1);

return\ c.getTime()

\f[R]

.fi

.PP

With the second form, the user sets the exact issue time in two parts,

year/month/day and hour:minute:second (using the local time zone).

The user can provide only one part, which means the other part is the

same as the current date (or time).

The user must provide the exact number of digits shown in the format

definition (padding with 0 when shorter).

When both 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.

.PP

When the option isn\[aq]t provided, the start date is the current time.

The option can only be provided one time.

.PP

The value of \f[I]date\f[R] specifies the number of days (starting at the

date specified by \f[CB]\-startdate\f[R], or the current date when

\f[CB]\-startdate\f[R] isn\[aq]t specified) for which the certificate

should be considered valid.

.RE