1341 lines
80 KiB
HTML
1341 lines
80 KiB
HTML
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
|
||
<html>
|
||
<head>
|
||
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
|
||
<title>keytool-Key and Certificate Management Tool</title>
|
||
<style type="text/css">
|
||
body {
|
||
background-color: #FFFFFF;
|
||
color: #000000;
|
||
}
|
||
</style>
|
||
</head>
|
||
<body>
|
||
<h1>keytool - Key and Certificate Management Tool</h1>
|
||
<blockquote>
|
||
<p>Manages a keystore (database) of private keys and their associated X.509
|
||
certificate chains authenticating the corresponding public keys. Also manages
|
||
certificates from trusted entities. </p>
|
||
</blockquote>
|
||
<h2>SYNOPSIS</h2>
|
||
<blockquote>
|
||
<pre><strong>keytool</strong> [ <a href="http://download.oracle.com/javase/1.3/docs/tooldocs/win32/keytool.html#Commands">commands</a> ]
|
||
</pre>
|
||
</blockquote>
|
||
<h2>DESCRIPTION</h2>
|
||
<blockquote>
|
||
<p><b>keytool</b> 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/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. </p>
|
||
<p>A <i>certificate</i> 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
|
||
<a href="http://download.oracle.com/javase/1.3/docs/tooldocs/win32/keytool.html#Certificates">
|
||
Certificates</a>.) When data is digitally signed, the signature can be
|
||
verified to check the data integrity and authenticity. <i>Integrity</i> means
|
||
that the data has not been modified or tampered with, and <i>authenticity</i>
|
||
means the data indeed comes from whoever claims to have created and signed it.
|
||
</p>
|
||
<p><b>keytool</b> stores the keys and certificates in a so-called <i>keystore</i>.
|
||
The default
|
||
<a href="http://download.oracle.com/javase/1.3/docs/tooldocs/win32/keytool.html#KeystoreImplementation">
|
||
keystore implementation</a> implements the keystore as a file. It protects
|
||
private keys with a password. </p>
|
||
<p>The
|
||
<a href="http://download.oracle.com/javase/1.3/docs/tooldocs/win32/jarsigner.html">
|
||
<b>jarsigner</b></a> tool uses information from a keystore to generate or
|
||
verify digital signatures for Java ARchive (JAR) files. (A JAR file packages
|
||
class files, images, sounds, and/or other digital data in a single file). <b>
|
||
jarsigner</b> verifies the digital signature of a JAR file, using the
|
||
certificate that comes with it (it is included in the signature block file of
|
||
the JAR file), and then checks whether or not the public key of that
|
||
certificate is "trusted", i.e., is contained in the specified keystore. </p>
|
||
<p>Please note: the <b>keytool</b> and <b>jarsigner</b> tools completely
|
||
replace the <b>javakey</b> tool provided in JDK 1.1. These new tools provide
|
||
more features than <b>javakey</b>, including the ability to protect the
|
||
keystore and private keys with passwords, and the ability to verify signatures
|
||
in addition to generating them. The new keystore architecture replaces the
|
||
identity database that <b>javakey</b> created and managed. It is possible to
|
||
import the information from an identity database into a keystore, via the
|
||
<code>-identitydb</code> <b>keytool</b> command. </p>
|
||
<h3>Keystore Entries</h3>
|
||
<blockquote>
|
||
<p>There are two different types of entries in a keystore: </p>
|
||
<ol>
|
||
<li><b>key entries</b> - 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
|
||
<a href="http://download.oracle.com/javase/1.3/docs/tooldocs/win32/keytool.html#CertChains">
|
||
certificate "chain"</a> for the corresponding public key. The <b>keytool</b>
|
||
and <b>jarsigner</b> tools only handle the latter type of entry, that is
|
||
private keys and their associated certificate chains.<p> </li>
|
||
<li><b>trusted certificate entries</b> - 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. </li>
|
||
</ol>
|
||
</blockquote>
|
||
<h3>Keystore Aliases</h3>
|
||
<blockquote>
|
||
<p>All keystore entries (key and trusted certificate entries) are accessed
|
||
via unique <i>aliases</i>. Aliases are case-insensitive; the aliases <code>
|
||
Hugo</code> and <code>hugo</code> would refer to the same keystore entry.
|
||
</p>
|
||
<p>An alias is specified when you add an entity to the keystore using the
|
||
<a href="http://download.oracle.com/javase/1.3/docs/tooldocs/win32/keytool.html#genkeyCmd">
|
||
-genkey</a> command to generate a key pair (public and private key) or the
|
||
<a href="http://download.oracle.com/javase/1.3/docs/tooldocs/win32/keytool.html#importCmd">
|
||
-import</a> command to add a certificate or certificate chain to the list of
|
||
trusted certificates. Subsequent <b>keytool</b> commands must use this same
|
||
alias to refer to the entity. </p>
|
||
<p>For example, suppose you use the alias <tt>duke</tt> to generate a new
|
||
public/private key pair and wrap the public key into a self-signed
|
||
certificate (see
|
||
<a href="http://download.oracle.com/javase/1.3/docs/tooldocs/win32/keytool.html#CertChains">
|
||
Certificate Chains</a>) via the following command: </p>
|
||
<pre> keytool -genkey -alias duke -keypass dukekeypasswd
|
||
</pre>
|
||
<p>This specifies an inital password of "dukekeypasswd" required by
|
||
subsequent commands to access the private key assocated with the alias <code>
|
||
duke</code>. If you later want to change duke's private key password, you
|
||
use a command like the following: </p>
|
||
<pre> keytool -keypasswd -alias duke -keypass dukekeypasswd -new newpass
|
||
</pre>
|
||
<p>This changes the password from "dukekeypasswd" to "newpass". </p>
|
||
<p>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. When typing in a password at the password
|
||
prompt, the password is currently echoed (displayed exactly as typed), so be
|
||
careful not to type it in front of anyone. </p>
|
||
</blockquote>
|
||
<h3><a name="KeystoreLoc">Keystore Location</a></h3>
|
||
<blockquote>
|
||
<p>Each <b>keytool</b> command has a <code>-keystore</code> option for
|
||
specifying the name and location of the persistent keystore file for the
|
||
keystore managed by <b>keytool</b>. The keystore is by default stored in a
|
||
file named <i>.keystore</i> in the user's home directory, as determined by
|
||
the "user.home" system property. Given user name <i>uName</i>, the "user.home"
|
||
property value defaults to </p>
|
||
<pre>C:\Winnt\Profiles\uName on multi-user Windows NT systems
|
||
C:\Windows\Profiles\uName on multi-user Windows 95 systems
|
||
C:\Windows on single-user Windows 95 systems
|
||
</pre>
|
||
<p>Thus, if the user name is "cathy", "user.home" defaults to </p>
|
||
<pre>C:\Winnt\Profiles\cathy on multi-user Windows NT systems
|
||
C:\Windows\Profiles\cathy on multi-user Windows 95 systems
|
||
</pre>
|
||
</blockquote>
|
||
<h3>Keystore Creation</h3>
|
||
<blockquote>
|
||
<p>A keystore is created whenever you use a
|
||
<a href="http://download.oracle.com/javase/1.3/docs/tooldocs/win32/keytool.html#genkeyCmd">
|
||
-genkey</a>,
|
||
<a href="http://download.oracle.com/javase/1.3/docs/tooldocs/win32/keytool.html#importCmd">
|
||
-import</a>, or
|
||
<a href="http://download.oracle.com/javase/1.3/docs/tooldocs/win32/keytool.html#identitydbCmd">
|
||
-identitydb</a> command to add data to a keystore that doesn't yet exist.
|
||
</p>
|
||
<p>More specifically, if you specify, in the <code>-keystore</code> option,
|
||
a keystore that doesn't yet exist, that keystore will be created. </p>
|
||
<p>If you don't specify a <code>-keystore</code> option, the default
|
||
keystore is a file named <code>.keystore</code> in your home directory. If
|
||
that file does not yet exist, it will be created. </p>
|
||
</blockquote>
|
||
<h3><a name="KeystoreImplementation">Keystore Implementation</a></h3>
|
||
<blockquote>
|
||
<p>The <code>KeyStore</code> class provided in the <code>java.security</code>
|
||
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
|
||
<i>type</i> of keystore. </p>
|
||
<p>Currently, two command-line tools (<b>keytool</b> and <b>jarsigner</b>)
|
||
and a GUI-based tool named <b>Policy Tool</b> make use of keystore
|
||
implementations. Since <code>KeyStore</code> is publicly available, JDK
|
||
users can write additional security applications that use it. </p>
|
||
<p>There is a built-in default implementation, provided by Sun Microsystems.
|
||
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. </p>
|
||
<p>Keystore implementations are provider-based. More specifically, the
|
||
application interfaces supplied by <code>KeyStore</code> are implemented in
|
||
terms of a "Service Provider Interface" (SPI). That is, there is a
|
||
corresponding abstract <code>KeystoreSpi</code> class, also in the <code>
|
||
java.security</code> 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
|
||
<a href="http://download.oracle.com/javase/1.3/docs/guide/security/HowToImplAProvider.html">
|
||
How to Implement a Provider for the Java Cryptography Architecture</a>. </p>
|
||
<p>Applications can choose different <i>types</i> of keystore
|
||
implementations from different providers, using the "getInstance" factory
|
||
method supplied in the <code>KeyStore</code> class. A keystore type defines
|
||
the storage and data format of the keystore information, and the algorithms
|
||
used to protect private keys in the keystore and the integrity of the
|
||
keystore itself. Keystore implementations of different types are not
|
||
compatible. </p>
|
||
<p><b>keytool</b> works on any file-based keystore implementation. (It
|
||
treats the keytore 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 <b>jarsigner</b> and <b>policytool</b> tools, on
|
||
the other hand, can read a keystore from any location that can be specified
|
||
using a URL. </p>
|
||
<p>For <b>keytool</b> and <b>jarsigner</b>, you can specify a keystore type
|
||
at the command line, via the <i>-storetype</i> option. For <b>Policy Tool</b>,
|
||
you can specify a keystore type via the "Change Keystore" command in the
|
||
Edit menu. </p>
|
||
<p>If you don't explicitly specify a keystore type, the tools choose a
|
||
keystore implementation based simply on the value of the <code>keystore.type</code>
|
||
property specified in the security properties file. The security properties
|
||
file is called <tt>java.security</tt>, and it resides in the JDK security
|
||
properties directory, <code><i>java.home</i>\lib\security</code>, where <i>
|
||
java.home</i> is the runtime environment's directory (the <tt>jre</tt>
|
||
directory in the SDK or the top-level directory of the Java 2 Runtime
|
||
Environment). </p>
|
||
<p>Each tool gets the <code>keystore.type</code> 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. </p>
|
||
<p>The <code>KeyStore</code> class defines a static method named <code>
|
||
getDefaultType</code> that lets applications and applets retrieve the value
|
||
of the <code>keystore.type</code> property. The following line of code
|
||
creates an instance of the default keystore type (as specified in the <code>
|
||
keystore.type</code> property): </p>
|
||
<pre> KeyStore keyStore = KeyStore.getInstance(KeyStore.getDefaultType());
|
||
</pre>
|
||
<p>The default keystore type is "jks" (the proprietary type of the keystore
|
||
implementation provided by Sun). This is specified by the following line in
|
||
the security properties file: </p>
|
||
<pre> keystore.type=jks
|
||
</pre>
|
||
<p>To have the tools utilize a keystore implementation other than the
|
||
default, you can change that line to specify a different keystore type. </p>
|
||
<p>For example, if you have a provider package that supplies a keystore
|
||
implementation for a keystore type called "pkcs12", change the line to </p>
|
||
<pre> keystore.type=pkcs12
|
||
</pre>
|
||
<p>Note: case doesn't matter in keystore type designations. For example, "JKS"
|
||
would be considered the same as "jks". </p>
|
||
</blockquote>
|
||
<h3><a name="DefaultAlgs">Supported Algorithms and Key Sizes</a></h3>
|
||
<blockquote>
|
||
<p><b>keytool</b> allows users to specify any key pair generation and
|
||
signature algorithm supplied by any of the registered cryptographic service
|
||
providers. That is, the <i>keyalg</i> and <i>sigalg</i> options for various
|
||
commands must be supported by a provider implementation. The default key
|
||
pair generation algorithm is "DSA". The signature algorithm is derived from
|
||
the algorithm of the underlying private key: If the underlying private key
|
||
is of type "DSA", the default signature algorithm is "SHA1withDSA", and if
|
||
the underlying private key is of type "RSA", the default signature algorithm
|
||
is "MD5withRSA". </p>
|
||
<p>When generating a DSA key pair, the key size must be in the range from
|
||
512 to 1024 bits, and must be a multiple of 64. The default key size for any
|
||
algorithm is 1024 bits. </p>
|
||
</blockquote>
|
||
<h3><a name="Certificates">Certificates</a></h3>
|
||
<blockquote>
|
||
<p>A <b>certificate</b> (also known as a <b>public-key certificate</b>) is a
|
||
digitally signed statement from one entity (the <i>issuer</i>), saying that
|
||
the public key (and some other information) of another entity (the <i>
|
||
subject</i>) has some specific value. </p>
|
||
<p>Let us expand on some of the key terms used in this sentence: </p>
|
||
<dl>
|
||
<dt><i>Public Keys</i> </dt>
|
||
<dd>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. </dd>
|
||
<dt><i>Digitally Signed</i> </dt>
|
||
<dd>If some data is <i>digitally signed</i> 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. </dd>
|
||
<dt><i>Identity</i> </dt>
|
||
<dd>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. </dd>
|
||
<dt><i>Signature</i> </dt>
|
||
<dd>A signature is computed over some data using the private key of an
|
||
entity (the <i>signer</i>, which in the case of a certificate is also
|
||
known as the <i>issuer</i>). </dd>
|
||
<dt><i>Private Keys</i> </dt>
|
||
<dd>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.
|
||
</dd>
|
||
<dt><i>Entity</i> </dt>
|
||
<dd>An entity is a person, organization, program, computer, business,
|
||
bank, or something else you are trusting to some degree. </dd>
|
||
</dl>
|
||
<p>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
|
||
<i>Certification Authority</i> (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
|
||
<a href="http://www.verisign.com">VeriSign</a>,
|
||
<a href="http://www.thawte.com">Thawte</a>, <a href="http://www.entrust.com">
|
||
Entrust</a>, and so on. You can also run your own Certification Authority
|
||
using products such as the Netscape/Microsoft Certificate Servers or the
|
||
Entrust CA product for your organization. </p>
|
||
<p>Using <b>keytool</b>, it is possible to display, import, and export
|
||
certificates. It is also possible to generate self-signed certificates. </p>
|
||
<p><b>keytool</b> currently handles X.509 certificates. </p>
|
||
<h3><a name="DName">X.509 Certificates</a></h3>
|
||
<blockquote>
|
||
<p>The X.509 standard defines what information can go into a certificate,
|
||
and describes how to write it down (the data format). All X.509
|
||
certificates have the following data, in addition to the signature: </p>
|
||
<dl>
|
||
<dt><b>Version</b> </dt>
|
||
<dd>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. <b>keytool</b> can import and export
|
||
v1, v2, and v3 certificates. It generates v1 certificates. </dd>
|
||
<dt><b>Serial Number</b> </dt>
|
||
<dd>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). </dd>
|
||
<dt><b>Signature Algorithm Identifier</b> </dt>
|
||
<dd>This identifies the algorithm used by the CA to sign the
|
||
certificate. </dd>
|
||
<dt><b>Issuer Name</b> </dt>
|
||
<dd>The
|
||
<a href="http://download.oracle.com/javase/1.3/docs/tooldocs/win32/keytool.html#DName">
|
||
X.500 Distinguished Name</a> 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
|
||
<i>root or top-level</i> CA certificates, the issuer signs its own
|
||
certificate.) </dd>
|
||
<dt><b>Validity Period</b> </dt>
|
||
<dd>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. </dd>
|
||
<dt><b>Subject Name</b> </dt>
|
||
<dd>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
|
||
<a href="http://download.oracle.com/javase/1.3/docs/tooldocs/win32/keytool.html#DName">
|
||
X.500 Distinguished Name</a> (DN) of the entity, for example,
|
||
<pre> CN=Java Duke, OU= Division, O=Sun Microsystems Inc, C=US
|
||
</pre>
|
||
<p>(These refer to the subject's Common Name, Organizational Unit,
|
||
Organization, and Country.) </dd>
|
||
<dt><b>Subject Public Key Information</b> </dt>
|
||
<dd>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. </dd>
|
||
</dl>
|
||
<p><i>X.509 Version 1</i> has been available since 1988, is widely
|
||
deployed, and is the most generic. </p>
|
||
<p><i>X.509 Version 2</i> 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. </p>
|
||
<p><i>X.509 Version 3</i> 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: <i>
|
||
KeyUsage</i> (limits the use of the keys to particular purposes such as
|
||
"signing-only") and <i>AlternativeNames</i> (allows other identities to
|
||
also be associated with this public key, e.g. DNS names, Email addresses,
|
||
IP addresses). Extensions can be marked <i>critical</i> 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. </p>
|
||
<p>All the data in a certificate is encoded using two related standards
|
||
called ASN.1/DER. <i>Abstract Syntax Notation 1</i> describes data. The <i>
|
||
Definite Encoding Rules</i> describe a single way to store and transfer
|
||
that data. </p>
|
||
</blockquote>
|
||
<h4><a name="DName">X.500 Distinguished Names</a></h4>
|
||
<blockquote>
|
||
<p>X.500 Distinguished Names are used to identify entities, such as those
|
||
which are named by the <code>subject</code> and <code>issuer</code>
|
||
(signer) fields of X.509 certificates. <b>keytool</b> supports the
|
||
following subparts: </p>
|
||
<ul>
|
||
<li><i>commonName</i> - common name of a person, e.g., "Susan Jones"<p> </li>
|
||
<li><i>organizationUnit</i> - small organization (e.g, department or
|
||
division) name, e.g., "Purchasing"<p> </li>
|
||
<li><i>organizationName</i> - large organization name, e.g., "ABCSystems,
|
||
Inc."<p> </li>
|
||
<li><i>localityName</i> - locality (city) name, e.g., "Palo Alto"<p> </li>
|
||
<li><i>stateName</i> - state or province name, e.g., "California"<p> </li>
|
||
<li><i>country</i> - two-letter country code, e.g., "CH"<p> </li>
|
||
</ul>
|
||
<p>When supplying a distinguished name string as the value of a <code>-dname</code>
|
||
option, as for the <code>-genkey</code> or <code>-selfcert</code>
|
||
commands, the string must be in the following format: </p>
|
||
<pre>CN=<i>cName</i>, OU=<i>orgUnit</i>, O=<i>org</i>, L=<i>city</i>, S=<i>state</i>, C=<i>countryCode</i>
|
||
</pre>
|
||
<p>where all the italicized items represent actual values and the above
|
||
keywords are abbreviations for the following: </p>
|
||
<pre> CN=commonName
|
||
OU=organizationUnit
|
||
O=organizationName
|
||
L=localityName
|
||
S=stateName
|
||
C=country
|
||
</pre>
|
||
<p>A sample distinguished name string is </p>
|
||
<pre>CN=Mark Smith, OU=JavaSoft, O=Sun, L=Cupertino, S=California, C=US
|
||
</pre>
|
||
<p>and a sample command using such a string is </p>
|
||
<pre>keytool -genkey -dname "CN=Mark Smith, OU=JavaSoft, O=Sun, L=Cupertino,
|
||
S=California, C=US" -alias mark
|
||
</pre>
|
||
<p>Case does not matter for the keyword abbreviations. For example, "CN",
|
||
"cn", and "Cn" are all treated the same. </p>
|
||
<p>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: </p>
|
||
<pre>CN=Steve Meier, OU=SunSoft, O=Sun, C=US
|
||
</pre>
|
||
<p>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 </p>
|
||
<pre> cn=peter schuster, o=Sun Microsystems\, Inc., o=sun, c=us
|
||
</pre>
|
||
<p>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 "\". </p>
|
||
</blockquote>
|
||
<h4><a name="EncodeCertificate">The Internet RFC 1421 Certificate Encoding
|
||
Standard</a></h4>
|
||
<blockquote>
|
||
<p>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. </p>
|
||
<p>Certificates read by the <code>-import</code> and <code>-printcert</code>
|
||
commands can be in either this format or binary encoded. </p>
|
||
<p>The <code>-export</code> command by default outputs a certificate in
|
||
binary encoding, but will instead output a certificate in the printable
|
||
encoding format, if the <code>-rfc</code> option is specified. </p>
|
||
<p>The <code>-list</code> command by default prints the MD5 fingerprint of
|
||
a certificate. If the <code>-v</code> option is specified, the certificate
|
||
is printed in human-readable format, while if the <code>-rfc</code> option
|
||
is specified, the certificate is output in the printable encoding format.
|
||
</p>
|
||
<p>In its printable encoding format, the encoded certificate is bounded at
|
||
the beginning by </p>
|
||
<pre>-----BEGIN CERTIFICATE-----
|
||
</pre>
|
||
<p>and at the end by </p>
|
||
<pre>-----END CERTIFICATE-----
|
||
</pre>
|
||
</blockquote>
|
||
<h3><a name="CertChains">Certificate Chains</a></h3>
|
||
<blockquote>
|
||
<p><b>keytool</b> 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. </p>
|
||
<p>When keys are first generated (see the
|
||
<a href="http://download.oracle.com/javase/1.3/docs/tooldocs/win32/keytool.html#genkeyCmd">
|
||
-genkey</a> command), the chain starts off containing a single element, a
|
||
<i>self-signed certificate</i>. 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 <code>-genkey</code>
|
||
command is called to generate a new public/private key pair, it also wraps
|
||
the public key into a self-signed certificate. </p>
|
||
<p>Later, after a Certificate Signing Request (CSR) has been generated
|
||
(see the
|
||
<a href="http://download.oracle.com/javase/1.3/docs/tooldocs/win32/keytool.html#certreqCmd">
|
||
-certreq</a> command) and sent to a Certification Authority (CA), the
|
||
response from the CA is imported (see
|
||
<a href="http://download.oracle.com/javase/1.3/docs/tooldocs/win32/keytool.html#importCmd">
|
||
-import</a>), 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 <i>CA</i>'s public key. </p>
|
||
<p>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 <i>different</i> 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. </p>
|
||
<p>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. </p>
|
||
<p>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 <b>keytool</b>. </p>
|
||
<p>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 <code>-printcert</code>
|
||
option) and compare the displayed fingerprint with the well-known
|
||
fingerprint (obtained from a newspaper, the root CA's webpage, etc.). </p>
|
||
</blockquote>
|
||
<h4><a name="ImportCertificate">Importing Certificates</a></h4>
|
||
<blockquote>
|
||
<p>To import a certificate from a file, use the
|
||
<a href="http://download.oracle.com/javase/1.3/docs/tooldocs/win32/keytool.html#importCmd">
|
||
-import</a> command, as in </p>
|
||
<pre> keytool -import -alias joe -file jcertfile.cer
|
||
</pre>
|
||
<p>This sample command imports the certificate(s) in the file <i>
|
||
jcertfile.cer</i> and stores it in the keystore entry identified by the
|
||
alias <i>joe</i>. </p>
|
||
<p>You import a certificate for two reasons: </p>
|
||
<ol>
|
||
<li>to add it to the list of trusted certificates, or<p> </li>
|
||
<li>to import a certificate reply received from a CA as the result of
|
||
submitting a Certificate Signing Request (see the
|
||
<a href="http://download.oracle.com/javase/1.3/docs/tooldocs/win32/keytool.html#certreqCmd">
|
||
-certreq</a> command) to that CA. </li>
|
||
</ol>
|
||
<p>Which type of import is intended is indicated by the value of the <code>
|
||
-alias</code> option. If the alias exists in the database, and identifies
|
||
an entry with a private key, then it is assumed you want to import a
|
||
certificate reply. <b>keytool</b> checks whether the public key in the
|
||
certificate reply matches the public key stored with the alias, and exits
|
||
if they are different. If the alias identifies the other type of keystore
|
||
entry, the certificate will not be imported. If the alias does not exist,
|
||
then it will be created and associated with the imported certificate. </p>
|
||
<h4><a name="TrustedCertWarning">WARNING Regarding Importing Trusted
|
||
Certificates</a></h4>
|
||
<blockquote>
|
||
<p>IMPORTANT: Be sure to check a certificate very carefully before
|
||
importing it as a trusted certificate! </p>
|
||
<p>View it first (using the <code>-printcert</code> command, or the
|
||
<code>-import command</code> without the <code>-noprompt</code> 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 <code>/tmp/cert</code>.
|
||
Before you consider adding the certificate to your list of trusted
|
||
certificates, you can execute a <code>-printcert</code> command to view
|
||
its fingerprints, as in </p>
|
||
<pre> keytool -printcert -file /tmp/cert
|
||
Owner: CN=ll, OU=ll, O=ll, L=ll, S=ll, C=ll
|
||
Issuer: CN=ll, OU=ll, O=ll, L=ll, S=ll, C=ll
|
||
Serial Number: 59092b34
|
||
Valid from: Thu Sep 25 18:01:13 PDT 1997 until: Wed Dec 24 17:01:13 PST 1997
|
||
Certificate Fingerprints:
|
||
MD5: 11:81:AD:92:C8:E5:0E:A2:01:2E:D4:7A:D7:5F:07:6F
|
||
SHA1: 20:B6:17:FA:EF:E5:55:8A:D0:71:1F:E8:D6:9D:C0:37:13:0E:5E:FE
|
||
</pre>
|
||
<p>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). </p>
|
||
<p>Note: it is not required that you execute a <code>-printcert</code>
|
||
command prior to importing a certificate, since before adding a
|
||
certificate to the list of trusted certificates in the keystore, the
|
||
<code>-import</code> 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
|
||
<code>-import</code> command without the <code>-noprompt</code> option.
|
||
If the <code>-noprompt</code> option is given, there is no interaction
|
||
with the user. </p>
|
||
</blockquote>
|
||
</blockquote>
|
||
<h4><a name="ExportCertificate">Exporting Certificates</a></h4>
|
||
<blockquote>
|
||
<p>To export a certificate to a file, use the
|
||
<a href="http://download.oracle.com/javase/1.3/docs/tooldocs/win32/keytool.html#exportCmd">
|
||
-export</a> command, as in </p>
|
||
<pre> keytool -export -alias jane -file janecertfile.cer
|
||
</pre>
|
||
<p>This sample command exports <code>jane</code>'s certificate to the file
|
||
<i>janecertfile.cer</i>. That is, if <code>jane</code> is the alias for a
|
||
key entry, the command exports the certificate at the bottom of the
|
||
certificate chain in that keystore entry. This is the certificate that
|
||
authenticates <code>jane</code>'s public key. </p>
|
||
<p>If, instead, <code>jane</code> is the alias for a trusted certificate
|
||
entry, then that trusted certificate is exported. </p>
|
||
</blockquote>
|
||
<h4><a name="DisplayCertificate">Displaying Certificates</a></h4>
|
||
<blockquote>
|
||
<p>To print out the contents of a keystore entry, use the
|
||
<a href="http://download.oracle.com/javase/1.3/docs/tooldocs/win32/keytool.html#listCmd">
|
||
-list</a> command, as in </p>
|
||
<pre> keytool -list -alias joe
|
||
</pre>
|
||
<p>If you don't specify an alias, as in </p>
|
||
<pre> keytool -list
|
||
</pre>
|
||
<p>the contents of the entire keystore are printed. </p>
|
||
<p>To display the contents of a certificate stored in a file, use the
|
||
<a href="http://download.oracle.com/javase/1.3/docs/tooldocs/win32/keytool.html#printcertCmd">
|
||
-printcert</a> command, as in </p>
|
||
<pre> keytool -printcert -file certfile.cer
|
||
</pre>
|
||
<p>This displays information about the certificate stored in the file
|
||
<code>certfile.cer</code>. </p>
|
||
<p>Note: This works independently of a keystore, i.e., you do <i>not</i>
|
||
need a keystore in order to display a certificate that's stored in a file.
|
||
</p>
|
||
</blockquote>
|
||
<h4><a name="CertificateGeneration">Generating a self-signed certificate</a></h4>
|
||
<blockquote>
|
||
<p>A <i>self-signed certificate</i> 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 <code>-genkey</code>
|
||
command is called to generate a new public/private key pair, it also wraps
|
||
the public key into a self-signed certificate. </p>
|
||
<p>You may occasionally wish to generate a new self-signed certificate.
|
||
For example, you may want to use the same key pair under a different
|
||
identity (distinguished name). For example, suppose you change
|
||
departments. You can then: </p>
|
||
<ol>
|
||
<li>copy (clone) the original key entry. See
|
||
<a href="http://download.oracle.com/javase/1.3/docs/tooldocs/win32/keytool.html#keycloneCmd">
|
||
-keyclone</a>.<p> </li>
|
||
<li>generate a new self-signed certificate for the cloned entry, using
|
||
your new distinguished name. See below.<p> </li>
|
||
<li>generate a Certificate Signing Requests for the cloned entry, and
|
||
import the reply certificate or certificate chain. See the
|
||
<a href="http://download.oracle.com/javase/1.3/docs/tooldocs/win32/keytool.html#-certreqCmd">
|
||
-certreq</a> and
|
||
<a href="http://download.oracle.com/javase/1.3/docs/tooldocs/win32/keytool.html#importCmd">
|
||
-import</a> commands.<p> </li>
|
||
<li>delete the original (now obsolete) entry. See
|
||
<a href="http://download.oracle.com/javase/1.3/docs/tooldocs/win32/keytool.html#deleteCmd">
|
||
-delete</a>.<p> </li>
|
||
</ol>
|
||
<p>To generate a self-signed certificate, use the
|
||
<a href="http://download.oracle.com/javase/1.3/docs/tooldocs/win32/keytool.html#selfcertCmd">
|
||
-selfcert</a> command, as in </p>
|
||
<pre> keytool -selfcert -alias dukeNew -keypass b92kqmp
|
||
-dname "cn=Duke Smith, ou=Purchasing, o=BlueSoft, c=US"
|
||
</pre>
|
||
<p>The generated certificate is stored as a single-element certificate
|
||
chain in the keystore entry identified by the specified alias (in this
|
||
case "dukeNew"), where it replaces the existing certificate chain. </p>
|
||
</blockquote>
|
||
</blockquote>
|
||
</blockquote>
|
||
<h2><a name="CommandNotes">COMMAND AND OPTION NOTES</a></h2>
|
||
<blockquote>
|
||
<p>The various commands and their options are listed and described
|
||
<a href="http://download.oracle.com/javase/1.3/docs/tooldocs/win32/keytool.html#Commands">
|
||
below</a> . Note: </p>
|
||
<ul>
|
||
<li>All command and option names are preceded by a minus sign (-).<p> </li>
|
||
<li>The options for each command may be provided in any order.<p> </li>
|
||
<li>All items not italicized or in braces or square brackets are required to
|
||
appear as is.<p> </li>
|
||
<li>Braces surrounding an option generally signify that a
|
||
<a href="http://download.oracle.com/javase/1.3/docs/tooldocs/win32/keytool.html#OptionDefaults">
|
||
default</a> value will be used if the option is not specified on the command
|
||
line. Braces are also used around the <code>-v</code>, <code>-rfc</code>,
|
||
and <code>-J</code> 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).<p> </li>
|
||
<li>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 <code>-keypass</code>
|
||
option, if you do not specify the option on the command line, <b>keytool</b>
|
||
will first attempt to use the keystore password to recover the private key,
|
||
and if this fails, will then prompt you for the private key password.)<p> </li>
|
||
<li>Items in italics (option values) represent the actual values that must
|
||
be supplied. For example, here is the format of the <code>-printcert</code>
|
||
command:
|
||
<pre> keytool -printcert {-file <i>cert_file</i>} {-v}
|
||
</pre>
|
||
<p>When specifying a <code>-printcert</code> command, replace <i>cert_file</i>
|
||
with the actual file name, as in: </p>
|
||
<pre> keytool -printcert -file VScert.cer
|
||
</pre>
|
||
<p> </li>
|
||
<li>Option values must be quoted if they contain a blank (space).<p> </li>
|
||
<li>The <code>-help</code> command is the default. Thus, the command line
|
||
<pre> keytool
|
||
</pre>
|
||
<p>is equivalent to </p>
|
||
<pre> keytool -help
|
||
</pre>
|
||
</li>
|
||
</ul>
|
||
<h3><a name="OptionDefaults">Option Defaults</a></h3>
|
||
<blockquote>
|
||
<p>Below are the defaults for various option values. </p>
|
||
<pre>-alias "mykey"
|
||
|
||
-keyalg "DSA"
|
||
|
||
-keysize 1024
|
||
|
||
-validity 90
|
||
|
||
-keystore <i>the file named .keystore in the user's home directory</i>
|
||
|
||
-file <i>stdin if reading, stdout if writing</i>
|
||
|
||
</pre>
|
||
<p>The signature algorithm (<i>-sigalg</i> option) is derived from the
|
||
algorithm of the underlying private key: If the underlying private key is of
|
||
type "DSA", the <i>-sigalg</i> option defaults to "SHA1withDSA", and if the
|
||
underlying private key is of type "RSA", <i>-sigalg</i> defaults to
|
||
"MD5withRSA". </p>
|
||
</blockquote>
|
||
<h3><a name="OptionsInAll">Options that Appear for Most Commands</a></h3>
|
||
<blockquote>
|
||
<p>The <code>-v</code> option can appear for all commands except <code>-help</code>.
|
||
If it appears, it signifies "verbose" mode; detailed certificate information
|
||
will be output. </p>
|
||
<p>There is also a <code>-J<i>javaoption</i></code> option that may appear
|
||
for any command. If it appears, the specified <i>javaoption</i> string is
|
||
passed through directly to the Java interpreter. (<b>keytool</b> is actually
|
||
a "wrapper" around the 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 <code>java -h</code>
|
||
or <code>java -X</code> at the command line. </p>
|
||
<p>These options may appear for all commands operating on a keystore: </p>
|
||
<dl>
|
||
<dt><code>-storetype <i>storetype</i></code> </dt>
|
||
<dd>This qualifier specifies the type of keystore to be instantiated. The
|
||
default keystore type is the one that is specified as the value of the "keystore.type"
|
||
property in the security properties file, which is returned by the static
|
||
<code>getDefaultType</code> method in <code>java.security.KeyStore</code>.
|
||
<p> </dd>
|
||
<dt><code>-keystore <i>keystore</i></code> </dt>
|
||
<dd>The keystore (database file) location. Defaults to the file <em>.keystore</em>
|
||
in the user's home directory, as determined by the "user.home" system
|
||
property, whose value is described in
|
||
<a href="http://download.oracle.com/javase/1.3/docs/tooldocs/win32/keytool.html#KeystoreLoc">
|
||
Keystore Location</a>.
|
||
<p> </dd>
|
||
<dt><code>-storepass <i>storepass</i></code> </dt>
|
||
<dd>The password which is used to protect the integrity of the keystore.
|
||
<p><em>storepass</em> must be at least 6 characters long. It must be
|
||
provided to all commands that access the keystore contents. For such
|
||
commands, if a <code>-storepass</code> option is not provided at the
|
||
command line, the user is prompted for it. </p>
|
||
<p>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. </p>
|
||
<p>Be careful with passwords - see
|
||
<a href="http://download.oracle.com/javase/1.3/docs/tooldocs/win32/keytool.html#PasswordWarning">
|
||
Warning Regarding Passwords</a>. </p>
|
||
<p> </dd>
|
||
<dt><code>-provider <i>provider-class-name</i></code> </dt>
|
||
<dd>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.<p> </dd>
|
||
</dl>
|
||
</blockquote>
|
||
<h3><a name="PasswordWarning">Warning Regarding Passwords</a></h3>
|
||
<blockquote>
|
||
<p>Most commands operating on a keystore require the store password. Some
|
||
commands require a private key password. </p>
|
||
<p>Passwords can be specified on the command line (in the <code>-storepass</code>
|
||
and <code>-keypass</code> 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. </p>
|
||
<p>If you don't specify a required password option on a command line, you
|
||
will be prompted for it. When typing in a password at the password prompt,
|
||
the password is currently echoed (displayed exactly as typed), so be careful
|
||
not to type it in front of anyone. </p>
|
||
</blockquote>
|
||
</blockquote>
|
||
<h2><a name="Commands">COMMANDS</a></h2>
|
||
<blockquote>
|
||
<p>See also the
|
||
<a href="http://download.oracle.com/javase/1.3/docs/tooldocs/win32/keytool.html#CommandNotes">
|
||
Command and Option Notes</a>. </p>
|
||
<h3>Adding Data to the Keystore</h3>
|
||
<blockquote>
|
||
<dl>
|
||
<dt><code><b><font size="+1"><a name="genkeyCmd">-genkey </a></font></b>
|
||
{-alias <i>alias</i>} {-keyalg <i>keyalg</i>} {-keysize <i>keysize</i>} {-sigalg
|
||
<i>sigalg</i>} [-dname <i>dname</i>] [-keypass <i>keypass</i>] {-validity
|
||
<i>valDays</i>} {-storetype <i>storetype</i>} {-keystore <i>keystore</i>}
|
||
[-storepass <i>storepass</i>] [-provider <i>provider_class_name</i>] {-v}
|
||
{-J<i>javaoption</i>}</code> </dt>
|
||
<dd>Generates a key pair (a public key and associated private key). Wraps
|
||
the public key into an X.509 v1 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 <em>alias</em>.
|
||
<p><em>keyalg</em> specifies the algorithm to be used to generate the key
|
||
pair, and <em>keysize</em> specifies the size of each key to be generated.
|
||
<em>sigalg</em> specifies the algorithm that should be used to sign the
|
||
self-signed certificate; this algorithm must be compatible with <em>keyalg</em>.
|
||
See
|
||
<a href="http://download.oracle.com/javase/1.3/docs/tooldocs/win32/keytool.html#DefaultAlgs">
|
||
Supported Algorithms and Key Sizes</a>. </p>
|
||
<p><em>dname</em> specifies the
|
||
<a href="http://download.oracle.com/javase/1.3/docs/tooldocs/win32/keytool.html#DName">
|
||
X.500 Distinguished Name</a> to be associated with <em>alias</em>, and is
|
||
used as the <code>issuer</code> and <code>subject</code> fields in the
|
||
self-signed certificate. If no distinguished name is provided at the
|
||
command line, the user will be prompted for one. </p>
|
||
<p><em>keypass</em> 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. <em>keypass</em> must be at least
|
||
6 characters long. Be careful with passwords - see
|
||
<a href="http://download.oracle.com/javase/1.3/docs/tooldocs/win32/keytool.html#PasswordWarning">
|
||
Warning Regarding Passwords</a>. </p>
|
||
<p><em>valDays</em> tells the number of days for which the certificate
|
||
should be considered valid.</p>
|
||
<p> </dd>
|
||
<dt><code><b><font size="+1"><a name="importCmd">-import </a></font></b>
|
||
{-alias <i>alias</i>} {-file <i>cert_file</i>} [-keypass <i>keypass</i>]
|
||
{-noprompt} {-trustcacerts} {-storetype <i>storetype</i>} {-keystore <i>
|
||
keystore</i>} [-storepass <i>storepass</i>] [-provider <i>
|
||
provider_class_name</i>] {-v} {-J<i>javaoption</i>}</code> </dt>
|
||
<dd>Reads the certificate or certificate chain (where the latter is
|
||
supplied in a PKCS#7 formatted reply) from the file <i>cert_file</i>, and
|
||
stores it in the keystore entry identified by <i>alias</i>. If no file is
|
||
given, the certificate or PKCS#7 reply is read from stdin. <b>keytool</b>
|
||
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
|
||
<a href="http://download.oracle.com/javase/1.3/docs/tooldocs/win32/keytool.html#EncodeCertificate">
|
||
Internet RFC 1421 standard</a>. 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".
|
||
<p>When importing a <b>new trusted certificate</b>, <i>alias</i> must not
|
||
yet exist in the keystore. Before adding the certificate to the keystore,
|
||
<b>keytool</b> 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. </p>
|
||
<p>If the <code>-trustcacerts</code> option has been specified, additional
|
||
certificates are considered for the chain of trust, namely the
|
||
certificates in a file named <b>"cacerts"</b>, which resides in the JDK
|
||
security properties directory, <code><i>java.home</i>\lib\security</code>,
|
||
where <i>java.home</i> is the runtime environment's directory (the <tt>jre</tt>
|
||
directory in the SDK or the top-level directory of the Java 2 Runtime
|
||
Environment). The "cacerts" file represents a system-wide keystore with CA
|
||
certificates. System administrators can configure and manage that file
|
||
using <b>keytool</b>, specifying "jks" as the keystore type. The "cacerts"
|
||
keystore file ships with five VeriSign root CA certificates with the
|
||
following X.500 distinguished names: </p>
|
||
<pre>1. OU=Class 1 Public Primary Certification Authority, O="VeriSign, Inc.",
|
||
C=US
|
||
|
||
2. OU=Class 2 Public Primary Certification Authority, O="VeriSign,
|
||
Inc.", C=US
|
||
|
||
3. OU=Class 3 Public Primary Certification Authority,
|
||
O="VeriSign, Inc.", C=US
|
||
|
||
4. OU=Class 4 Public Primary Certification
|
||
Authority, O="VeriSign, Inc.", C=US
|
||
|
||
5. OU=Secure Server Certification
|
||
Authority, O="RSA Data Security, Inc.", C=US
|
||
</pre>
|
||
<p>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 JDK. </p>
|
||
<p>If <b>keytool</b> 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
|
||
<a href="http://download.oracle.com/javase/1.3/docs/tooldocs/win32/keytool.html#TrustedCertWarning">
|
||
WARNING Regarding Importing Trusted Certificates</a>. The user then has
|
||
the option of aborting the import operation. If the <code>-noprompt</code>
|
||
option is given, however, there will be no interaction with the user. </p>
|
||
<p>When importing a <b>certificate reply</b>, the certificate reply is
|
||
validated using trusted certificates from the keystore, and optionally
|
||
using the certificates configured in the "cacerts" keystore file (if the
|
||
<code>-trustcacerts</code> option was specified). </p>
|
||
<p>If the reply is a single X.509 certificate, <b>keytool</b> 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 <i>alias</i>. </p>
|
||
<p>If the reply is a PKCS#7 formatted certificate chain, the chain is
|
||
first ordered (with the user certificate first and the self-signed root CA
|
||
certificate last), before <b>keytool</b> attempts to match the root CA
|
||
certificate provided in the reply with any of the trusted certificates in
|
||
the keystore or the "cacerts" keystore file (if the <code>-trustcacerts</code>
|
||
option was specified). If no match can be found, the information of the
|
||
root CA certificate 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 root CA itself. The user then has the option of
|
||
aborting the import operation. If the <code>-noprompt</code> option is
|
||
given, however, there will be no interaction with the user. </p>
|
||
<p>The new certificate chain of <i>alias</i> replaces the old certificate
|
||
chain associated with this entry. The old chain can only be replaced if a
|
||
valid <i>keypass</i>, 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. Be careful with passwords - see
|
||
<a href="http://download.oracle.com/javase/1.3/docs/tooldocs/win32/keytool.html#PasswordWarning">
|
||
Warning Regarding Passwords</a>. </p>
|
||
<p> </dd>
|
||
<dt><code><b><font size="+1"><a name="selfcertCmd">-selfcert </a></font>
|
||
</b>{-alias <i>alias</i>} {-sigalg <i>sigalg</i>} {-dname <i>dname</i>}
|
||
{-validity <i>valDays</i>} [-keypass <i>keypass</i>] {-storetype <i>
|
||
storetype</i>} {-keystore <i>keystore</i>} [-storepass <i>storepass</i>]
|
||
[-provider <i>provider_class_name</i>] {-v} {-J<i>javaoption</i>}</code>
|
||
</dt>
|
||
<dd>Generates an X.509 v1 self-signed certificate, using keystore
|
||
information including the private key and public key associated with <em>
|
||
alias</em>. If <i>dname</i> is supplied at the command line, it is used as
|
||
the
|
||
<a href="http://download.oracle.com/javase/1.3/docs/tooldocs/win32/keytool.html#DName">
|
||
X.500 Distinguished Name</a> for both the <code>issuer</code> and <code>
|
||
subject</code> of the certificate. Otherwise, the X.500 Distinguished Name
|
||
associated with <em>alias</em> (at the bottom of its existing certificate
|
||
chain) is used.
|
||
<p>The generated certificate is stored as a single-element certificate
|
||
chain in the keystore entry identified by <em>alias</em>, where it
|
||
replaces the existing certificate chain. </p>
|
||
<p><em>sigalg</em> specifies the algorithm that should be used to sign the
|
||
certificate. See
|
||
<a href="http://download.oracle.com/javase/1.3/docs/tooldocs/win32/keytool.html#DefaultAlgs">
|
||
Supported Algorithms and Key Sizes</a>. </p>
|
||
<p>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 <em>keypass</em> 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. Be careful with passwords - see
|
||
<a href="http://download.oracle.com/javase/1.3/docs/tooldocs/win32/keytool.html#PasswordWarning">
|
||
Warning Regarding Passwords</a>. </p>
|
||
<p><em>valDays</em> tells the number of days for which the certificate
|
||
should be considered valid.</p>
|
||
<p> </dd>
|
||
<dt><code><b><font size="+1"><a name="identitydbCmd">-identitydb </a>
|
||
</font></b>{-file <i>idb_file</i>} {-storetype <i>storetype</i>} {-keystore
|
||
<i>keystore</i>} [-storepass <i>storepass</i>] [-provider <i>
|
||
provider_class_name</i>] {-v} {-J<i>javaoption</i>}</code> </dt>
|
||
<dd>Reads the JDK 1.1.x-style identity database from the file <em>idb_file</em>,
|
||
and adds its entries to the keystore. If no file is given, the identity
|
||
database is read from stdin. If a keystore does not exist, it is created.
|
||
<p>Only identity database entries ("identities") that were marked as
|
||
trusted will be imported in the keystore. All other identities will be
|
||
ignored. For each trusted identity, a keystore entry will be created. The
|
||
identity's name is used as the "alias" for the keystore entry. </p>
|
||
<p>The private keys from trusted identities will all be encrypted under
|
||
the same password, <i>storepass</i>. This is the same password that is
|
||
used to protect the keystore's integrity. Users can later assign
|
||
individual passwords to those private keys by using the "-keypasswd" <b>
|
||
keytool</b> command option. </p>
|
||
<p>An identity in an identity database may hold more than one certificate,
|
||
each certifying the same public key. But a keystore key entry for a
|
||
private key has that private key and a single "certificate chain"
|
||
(initially just a single certificate), where the first certificate in the
|
||
chain contains the public key corresponding to the private key. When
|
||
importing the information from an identity, only the first certificate of
|
||
the identity is stored in the keystore. This is because an identity's name
|
||
in an identity database is used as the alias for its corresponding
|
||
keystore entry, and alias names are unique within a keystore, </dd>
|
||
</dl>
|
||
<p> </p>
|
||
</blockquote>
|
||
<h3>Exporting Data</h3>
|
||
<blockquote>
|
||
<dl>
|
||
<dt><code><b><font size="+1"><a name="certreqCmd">-certreq </a></font></b>
|
||
{-alias <i>alias</i>} {-sigalg <i>sigalg</i>} {-file <i>certreq_file</i>}
|
||
[-keypass <i>keypass</i>] {-storetype <i>storetype</i>} {-keystore <i>
|
||
keystore</i>} [-storepass <i>storepass</i>] [-provider <i>
|
||
provider_class_name</i>] {-v} {-J<i>javaoption</i>}</code> </dt>
|
||
<dd>Generates a Certificate Signing Request (CSR), using the PKCS#10
|
||
format.
|
||
<p>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. </p>
|
||
<p>The private key and X.500 Distinguished Name associated with <em>alias</em>
|
||
are 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 <em>keypass</em> 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.</p>
|
||
<p>Be careful with passwords - see
|
||
<a href="http://download.oracle.com/javase/1.3/docs/tooldocs/win32/keytool.html#PasswordWarning">
|
||
Warning Regarding Passwords</a>. </p>
|
||
<p><em>sigalg</em> specifies the algorithm that should be used to sign the
|
||
CSR. See
|
||
<a href="http://download.oracle.com/javase/1.3/docs/tooldocs/win32/keytool.html#DefaultAlgs">
|
||
Supported Algorithms and Key Sizes</a>. </p>
|
||
<p>The CSR is stored in the file <em>certreq_file</em>. If no file is
|
||
given, the CSR is output to stdout. </p>
|
||
<p>Use the <em>import</em> command to import the response from the CA.</p>
|
||
<p> </dd>
|
||
<dt><code><b><font size="+1"><a name="exportCmd">-export </a></font></b>
|
||
{-alias <i>alias</i>} {-file <i>cert_file</i>} {-storetype <i>storetype</i>}
|
||
{-keystore <i>keystore</i>} [-storepass <i>storepass</i>] [-provider <i>
|
||
provider_class_name</i>] {-rfc} {-v} {-J<i>javaoption</i>}</code> </dt>
|
||
<dd>Reads (from the keystore) the certificate associated with <em>alias</em>,
|
||
and stores it in the file <em>cert_file</em>.
|
||
<p>If no file is given, the certificate is output to stdout. </p>
|
||
<p>The certificate is by default output in binary encoding, but will
|
||
instead be output in the printable encoding format, as defined by the
|
||
<a href="http://download.oracle.com/javase/1.3/docs/tooldocs/win32/keytool.html#EncodeCertificate">
|
||
Internet RFC 1421 standard</a>, if the <code>-rfc</code> option is
|
||
specified. </p>
|
||
<p>If <i>alias</i> refers to a trusted certificate, that certificate is
|
||
output. Otherwise, <i>alias</i> 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 <i>alias</i>.</p>
|
||
<p> </dd>
|
||
</dl>
|
||
</blockquote>
|
||
<h3>Displaying Data</h3>
|
||
<blockquote>
|
||
<dl>
|
||
<dt><code><b><font size="+1"><a name="listCmd">-list </a></font></b>
|
||
{-alias <i>alias</i>} {-storetype <i>storetype</i>} {-keystore <i>keystore</i>}
|
||
[-storepass <i>storepass</i>] [-provider <i>provider_class_name</i>] {-v |
|
||
-rfc} {-J<i>javaoption</i>}</code> </dt>
|
||
<dd>Prints (to stdout) the contents of the keystore entry identified by <i>
|
||
alias</i>. If no alias is specified, the contents of the entire keystore
|
||
are printed.
|
||
<p>This command by default prints the MD5 fingerprint of a certificate. If
|
||
the <code>-v</code> option is specified, the certificate is printed in
|
||
human-readable format, with additional information such as the owner,
|
||
issuer, and serial number. If the <code>-rfc</code> option is specified,
|
||
certificate contents are printed using the printable encoding format, as
|
||
defined by the
|
||
<a href="http://download.oracle.com/javase/1.3/docs/tooldocs/win32/keytool.html#EncodeCertificate">
|
||
Internet RFC 1421 standard</a> </p>
|
||
<p>You cannot specify both <code>-v</code> and <code>-rfc</code>. </p>
|
||
<p> </dd>
|
||
<dt><code><b><font size="+1"><a name="printcertCmd">-printcert </a></font>
|
||
</b><a name="printcertCmd">{-file <i>cert_file</i>} {-v} {-J<i>javaoption</i>}</a></code>
|
||
</dt>
|
||
<dd><a name="printcertCmd">Reads the certificate from the file <em>
|
||
cert_file</em>, and prints its contents in a human-readable format. If no
|
||
file is given, the certificate is read from stdin. </a>
|
||
<p><a name="printcertCmd">The certificate may be either binary encoded or
|
||
in printable encoding format, as defined by the </a>
|
||
<a href="http://download.oracle.com/javase/1.3/docs/tooldocs/win32/keytool.html#EncodeCertificate">
|
||
Internet RFC 1421 standard</a>. </p>
|
||
<p>Note: This option can be used independently of a keystore.</p>
|
||
<p> </dd>
|
||
</dl>
|
||
</blockquote>
|
||
<h3>Managing the Keystore</h3>
|
||
<blockquote>
|
||
<dl>
|
||
<dt><code><b><font size="+1"><a name="keycloneCmd">-keyclone </a></font>
|
||
</b>{-alias <i>alias</i>} [-dest <i>dest_alias</i>] [-keypass <i>keypass</i>]
|
||
[-new <i>new_keypass</i>] {-storetype <i>storetype</i>} {-keystore <i>
|
||
keystore</i>} [-storepass <i>storepass</i>] [-provider <i>
|
||
provider_class_name</i>] {-v} {-J<i>javaoption</i>}</code> </dt>
|
||
<dd>Creates a new keystore entry, which has the same private key and
|
||
certificate chain as the original entry.
|
||
<p>The original entry is identified by <em>alias</em> (which defaults to "mykey"
|
||
if not provided). The new (destination) entry is identified by <em>
|
||
dest_alias</em>. If no destination alias is supplied at the command line,
|
||
the user is prompted for it. </p>
|
||
<p>If the private key password is different from the keystore password,
|
||
then the entry will only be cloned if a valid <i>keypass</i> is supplied.
|
||
This is the password used to protect the private key associated with <i>
|
||
alias</i>. If no key password is supplied at the command line, and the
|
||
private key password is different from the keystore password, the user is
|
||
prompted for it. The private key in the cloned entry may be protected with
|
||
a different password, if desired. If no <code>-new</code> option is
|
||
supplied at the command line, the user is prompted for the new entry's
|
||
password (and may choose to let it be the same as for the cloned entry's
|
||
private key). </p>
|
||
<p>Be careful with passwords - see
|
||
<a href="http://download.oracle.com/javase/1.3/docs/tooldocs/win32/keytool.html#PasswordWarning">
|
||
Warning Regarding Passwords</a>. </p>
|
||
<p>This command can be used to establish multiple certificate chains
|
||
corresponding to a given key pair, or for backup purposes.</p>
|
||
<p> </dd>
|
||
<dt><code><b><font size="+1">-storepasswd </font></b>[-new <i>
|
||
new_storepass</i>] {-storetype <i>storetype</i>} {-keystore <i>keystore</i>}
|
||
[-storepass <i>storepass</i>] [-provider <i>provider_class_name</i>] {-v}
|
||
{-J<i>javaoption</i>}</code> </dt>
|
||
<dd>Changes the password used to protect the integrity of the keystore
|
||
contents. The new password is <em>new_storepass</em>, which must be at
|
||
least 6 characters long.<p>Be careful with passwords - see
|
||
<a href="http://download.oracle.com/javase/1.3/docs/tooldocs/win32/keytool.html#PasswordWarning">
|
||
Warning Regarding Passwords</a>.</p>
|
||
<p> </dd>
|
||
<dt><code><b><font size="+1">-keypasswd </font></b>{-alias <i>alias</i>}
|
||
[-keypass <i>old_keypass</i>] [-new <i>new_keypass</i>] {-storetype <i>
|
||
storetype</i>} {-keystore <i>keystore</i>} [-storepass <i>storepass</i>]
|
||
[-provider <i>provider_class_name</i>] {-v} {-J<i>javaoption</i>}</code>
|
||
</dt>
|
||
<dd>Changes the password under which the private key identified by <em>
|
||
alias</em> is protected, from <em>old_keypass</em> to <em>new_keypass</em>.
|
||
<p>If the <code>-keypass</code> option is not provided at the command
|
||
line, and the private key password is different from the keystore
|
||
password, the user is prompted for it. </p>
|
||
<p>If the <code>-new</code> option is not provided at the command line,
|
||
the user is prompted for it.</p>
|
||
<p> </p>
|
||
<p>Be careful with passwords - see
|
||
<a href="http://download.oracle.com/javase/1.3/docs/tooldocs/win32/keytool.html#PasswordWarning">
|
||
Warning Regarding Passwords</a>.</p>
|
||
<p> </dd>
|
||
<dt><code><b><font size="+1"><a name="deleteCmd">-delete </a></font></b>
|
||
[-alias <i>alias</i>] {-storetype <i>storetype</i>} {-keystore <i>keystore</i>}
|
||
[-storepass <i>storepass</i>] [-provider <i>provider_class_name</i>] {-v}
|
||
{-J<i>javaoption</i>}</code> </dt>
|
||
<dd>Deletes from the keystore the entry identified by <em>alias</em>. The
|
||
user is prompted for the alias, if no alias is provided at the command
|
||
line.<p> </dd>
|
||
</dl>
|
||
</blockquote>
|
||
<h3>Getting Help</h3>
|
||
<blockquote>
|
||
<dl>
|
||
<dt><code><b><font size="+1">-help </font></b></code></dt>
|
||
<dd>Lists all the commands and their options.<p> </dd>
|
||
</dl>
|
||
</blockquote>
|
||
</blockquote>
|
||
<h2><a name="EXAMPLES">EXAMPLES</a></h2>
|
||
<blockquote>
|
||
<p>Suppose you want to create a keystore for managing your public/private key
|
||
pair and certificates from entities you trust. </p>
|
||
<h3>Generating Your Key Pair</h3>
|
||
<blockquote>
|
||
<p>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: </p>
|
||
<pre> keytool -genkey -dname "cn=Mark Jones, ou=JavaSoft, o=Sun, c=US"
|
||
-alias business -keypass kpi135 -keystore C:\working\mykeystore
|
||
-storepass ab987c -validity 180
|
||
</pre>
|
||
<p>(Please note: This must be typed as a single line. Multiple lines are
|
||
used in the examples just for legibility purposes.) </p>
|
||
<p>This command creates the keystore named "mykeystore" in the "working"
|
||
directory on the C drive (assuming it doesn't already exist), and assigns it
|
||
the password "ab987c". It generates a public/private key pair for the entity
|
||
whose "distinguished name" has a common name of "Mark Jones", organizational
|
||
unit of "JavaSoft", organization of "Sun" and two-letter country code of
|
||
"US". It uses the default "DSA" key generation algorithm to create the keys,
|
||
both 1024 bits long. </p>
|
||
<p>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 "kpi135". </p>
|
||
<p>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: </p>
|
||
<pre> keytool -genkey
|
||
</pre>
|
||
<p>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. </p>
|
||
<p>The rest of the examples assume you executed the <code>-genkey</code>
|
||
command without options specified, and that you responded to the prompts
|
||
with values equal to those given in the first <code>-genkey</code> command,
|
||
above (a private key password of "kpi135", etc.) </p>
|
||
</blockquote>
|
||
<h3>Requesting a Signed Certificate from a Certification Authority</h3>
|
||
<blockquote>
|
||
<p>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: </p>
|
||
<pre> keytool -certreq -file MarkJ.csr
|
||
</pre>
|
||
<p>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.) </p>
|
||
</blockquote>
|
||
<h3>Importing a Certificate for the CA</h3>
|
||
<blockquote>
|
||
<p>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. </p>
|
||
<p>Before you import the certificate reply from a CA, you need one or more
|
||
"trusted certificates" in your keystore or in the <code>cacerts</code>
|
||
keystore file (which is described in
|
||
<a href="http://download.oracle.com/javase/1.3/docs/tooldocs/win32/keytool.html#importCmd">
|
||
import command</a>): </p>
|
||
<ul>
|
||
<li>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).<p> </li>
|
||
<li>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. </li>
|
||
</ul>
|
||
<p>The "cacerts" keystore file ships with five 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". </p>
|
||
<p>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. </p>
|
||
<p>Be very careful to ensure the certificate is valid prior to importing it
|
||
as a "trusted" certificate! View it first (using the <b>keytool</b> <code>-printcert</code>
|
||
command, or the <b>keytool</b> <code>-import</code> command without the
|
||
<code>-noprompt</code> 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. </p>
|
||
<p>If you trust that the certificate is valid, then you can add it to your
|
||
keystore via the following: </p>
|
||
<pre> keytool -import -alias abc -file ABCCA.cer
|
||
</pre>
|
||
<p>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. </p>
|
||
</blockquote>
|
||
<h3>Importing the Certificate Reply from the CA</h3>
|
||
<blockquote>
|
||
<p>Once you've imported a certificate authenticating the public key of the
|
||
CA you submitted your certificate signing request to (or there's 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. </p>
|
||
<p>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": </p>
|
||
<pre> keytool -import -trustcacerts -file VSMarkJ.cer
|
||
</pre>
|
||
</blockquote>
|
||
<h3>Exporting a Certificate Authenticating Your Public Key</h3>
|
||
<blockquote>
|
||
<p>Suppose you have used the
|
||
<a href="http://download.oracle.com/javase/1.3/docs/tooldocs/win32/jarsigner.html">
|
||
jarsigner</a> tool to sign a Java ARchive (JAR) file. Clients that want to
|
||
use the file will want to authenticate your signature. </p>
|
||
<p>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 <code>MJ.cer</code> via the following, assuming
|
||
the entry is aliased by "mykey": </p>
|
||
<pre> keytool -export -alias mykey -file MJ.cer
|
||
</pre>
|
||
<p>Given that certificate, and the signed JAR file, a client can use the <b>
|
||
jarsigner</b> tool to authenticate your signature. </p>
|
||
</blockquote>
|
||
<h3>Changing Your Distinguished Name but Keeping your Key Pair</h3>
|
||
<blockquote>
|
||
<p>Suppose your distinguished name changes, for example because you have
|
||
changed departments or moved to a different city. If desired, you may still
|
||
use the public/private key pair you've previously used, and yet update your
|
||
distinguished name. For example, suppose your name is Susan Miller, and you
|
||
created your initial key entry with the alias <code>sMiller</code> and the
|
||
distinguished name </p>
|
||
<pre> "cn=Susan Miller, ou=Finance Department, o=BlueSoft, c=us"
|
||
</pre>
|
||
<p>Suppose you change from the Finance Department to the Accounting
|
||
Department. You can still use the previously-generated public/private key
|
||
pair and yet update your distinguished name by doing the following. First,
|
||
copy (clone) your key entry: </p>
|
||
<pre> keytool -keyclone -alias sMiller -dest sMillerNew
|
||
</pre>
|
||
<p>(This prompts for the store password and for the initial and destination
|
||
private key passwords, since they aren't provided at the command line.) Now
|
||
you need to change the certificate chain associated with the copy, so that
|
||
the first certificate in the chain uses your different distinguished name.
|
||
Start by generating a self-signed certificate with the appropriate name: </p>
|
||
<pre> keytool -selfcert -alias sMillerNew
|
||
-dname "cn=Susan Miller, ou=Accounting Department, o=BlueSoft, c=us"
|
||
</pre>
|
||
<p>Then generate a Certificate Signing Request based on the information in
|
||
this new certificate: </p>
|
||
<pre> keytool -certreq -alias sMillerNew
|
||
</pre>
|
||
<p>When you get the CA certificate reply, import it: </p>
|
||
<pre> keytool -import -alias sMillerNew -file VSSMillerNew.cer
|
||
</pre>
|
||
<p>After importing the certificate reply, you may want to remove the initial
|
||
key entry that used your old distinguished name: </p>
|
||
<pre> keytool -delete -alias sMiller
|
||
</pre>
|
||
</blockquote>
|
||
</blockquote>
|
||
<h2>SEE ALSO</h2>
|
||
<blockquote>
|
||
<ul>
|
||
<li>
|
||
<a href="http://download.oracle.com/javase/1.3/docs/tooldocs/win32/jar.html">
|
||
jar</a> tool documentation</li>
|
||
<li>
|
||
<a href="http://download.oracle.com/javase/1.3/docs/tooldocs/win32/jarsigner.html">
|
||
jarsigner</a> tool documentation</li>
|
||
<li>the
|
||
<a href="http://java.sun.com/docs/books/tutorial/security1.2/index.html"><b>
|
||
Security</b></a> trail of the
|
||
<a href="http://java.sun.com/docs/books/tutorial/index.html"><b>Java
|
||
Tutorial</b></a> for examples of the use of <b>keytool</b> </li>
|
||
</ul>
|
||
</blockquote>
|
||
<hr noshade="noshade" size="3">
|
||
<table border="0" width="100%">
|
||
<tr valign="top">
|
||
<td><font size="-2">
|
||
<a href="http://download.oracle.com/javase/1.3/docs/relnotes/SMICopyright.html">
|
||
Copyright <20></a> 1995, 2010 <a href="http://www.oracle.com">Oracle and/or its
|
||
affiliates.</a> All rights reserved.</font></td>
|
||
<td align="right">
|
||
<img src="sunlogo64x30.gif" alt="Sun" border="0" width="100" height="29">
|
||
<br>
|
||
</td>
|
||
</tr>
|
||
</table>
|
||
</body>
|
||
</html> |