Keytool and the "Failed to establish chain from reply" Error
by Michelle Cope
(June, 2003)
We want to hear from you! Please send us your
FEEDBACK.
The following technical article may contain actual software programs in source code form.
This source code is made available for developers to use as needed, pursuant to the terms and
conditions of this license.
Introduction
In order to explain the cause of the "Failed to establish chain from Reply"
error message, some background on importing certificate replies is required.
There are a number of terms introduced in this article, most of which are
documented in the glossary. As such, it is advisable that the reader
become familiar with the terms in the glossary before reading the rest of the article.
Commands
The first step in importing a certificate
reply is to generate a private key/public certificate pair using the
-genkey
flag of the Java programming language tool,
keytool (See Command 1.1). Keytool is found
under the java.home/bin directory where java.home points to the
Java 2 runtime environment directory.
| Command 1.1
keytool -genkey -alias <subjectkey> -keypass
<mykeypasswd> -keystore <mykeystore>
-storepass <storepass>
For example:
keytool -genkey -alias joe -keypass joepass -keystore keystore
-storepass password
A new keystore file is created called keystore with the password,
password. In the keystore, a key entry is created that is aliased by
joe, and protected by the password, joepass. |
Command 1.1 will create a
key entry referenced by the alias
<subjectkey>, protected by the password <mykeypasswd>, in
the keystore
<mykeystore>. The key entry password is required every time the
alias <subjectkey> is used. The keystore
<mykeystore> is protected by the store password
<storepass>. In this example, the keystore <mykeystore> is a file of
the same name, located in the current directory. The value of
<mykeystore> can be a pathname to a keystore file. If the
<mykeystore> file exists, then the store password must be the
password protecting that keystore, otherwise Command 1.1 will
create a keystore file, called <mykeystore>, protected by the
password, <storepass>.
A keystore contains a set of key entries. A key entry consists of a private
key and a corresponding public, self-signed certificate.
The self-signed certificate has been signed only by the executer of the key generation
command (that is, Command 1.1). The entity that generates a private/public
key pair is referred to as a subject.
In order for other sources to trust the subject's public self-signed
certificate, it should be certified by a Certificate
Authority (CA). Examples of Certificate Authorities are Verisign,
Entrust, Thawte Consulting, and BelSign. A Certificate Authority will verify the
subject's identity, (usually in an off-line, manual process) and will sign the
subject's public self-signed certificate, if successful. The subject must
generate a Certificate
Signed Request (CSR) from their self-signed certificate, to send to the
CA for authentication. A Certificate Signed Request is created by using
Command 2.1.
| Command 2.1
keytool -certreq -alias <subjectkey> -keypass
<mykeypasswd> -keystore <mykeystore> -storepass
<storepass> -file <myCertificate.cer>
For example:
keytool -certreq -alias joe -keypass joepass -keystore keystore
-storepass password -file joeCertificate.cer |
Command 2.1 will create a CSR for the self-signed certificate in the
key entry aliased by <subjectkey>, which is stored in
<mykeystore>. The generated CSR is placed in the file
<myCertificate.cer>.
In response to a CSR, a CA will return a certificate
reply which needs to be imported into the corresponding key entry of the
keystore. In this example, the certificate reply is imported into the key entry
aliased by <subjectkey>. By importing the certificate reply into
the keystore, it will ultimately replace the public self-signed certificate part
of the corresponding key entry. A certificate reply can be either a single
certificate or a chain of certificates that conforms to the PKCS#7 format (RFC 2315). In the case of a
single certificate, it will be the issuer-signed certificate. The issuer-signed certificate defines a
certificate generated by the CA that authenticated the subject's self-signed
certificate in the CSR. A chain of certificates is a list of certificates
where the next certificate in the chain is the public certificate of the CA that
authenticated the previous certificate in the chain. The chain starts with
the issuer-signed certificate, then a support chain of public
certificates from intermediate CAs, and ends in a root
certificate. A root certificate is a public, self-signed certificate that
is the last link in a certificate chain.
When a certificate reply is being imported into the keystore, keytool will
check that a chain
of trust can be established between the certificate reply and a root
certificate in a keystore. If a chain of trust cannot be established, then a
java.lang.Exception will be thrown with an error message similar to "Failed to
establish chain from reply".
A subject may need to import a root certificate of the CA (that generated the
certificate reply) into a keystore, in order to prevent the above exception from
being thrown. If the certificate reply was generated by VeriSign or Thawte, then
the subject may not need to import any VeriSign root certificates, because all
Java 2 runtime environments are distributed with five root certificates issued from
VeriSign. These root certificates are stored in a special keystore called the
cacerts
file, found under the java.home/lib/security directory, where
java.home is a Java 2 runtime environment's home directory. The
cacerts keystore contains certificates that are considered
trusted by the subject. The cacerts keystore is considered
separate from the subject's keystore that contains the private key/public
certificate chains belonging to the subject. A subject should only place
trusted root CA certificates into the cacerts keystore.
However, if the certificate reply was generated by a certificate authority
whose root certificate is not present in the cacerts file, then the CA's
public certificate will need to be imported into a keystore prior to importing
the certificate reply.
There are a number of ways to import the CA's public root certificate:
OPTION 1
Prepend the CA's root certificate to the file
containing the certificate reply in order to create a file conformant to the
PKCS#7 format. Both the certificate reply and the CA's certificate can be
viewed as text encoded Base64. By prepending the section of the CA's
certificate delimited by the '--BEGIN' and 'END--' tags to the the certificate
reply, the entire file will represent a chain of trust. If you place the root CA
after the certificate reply, then the "Failed to establish a chain of
trust'" exception will be thrown.
The format of the file would look like:
ROOT CA:
-----BEGIN CERTIFICATE-----
lkAJtetLJ?%dggfagneJ%#LJDfd .....
Lfg$^jLfgf.....
aLN^$jLfLK33#.....
.....
.....
.....
-----END CERTIFICATE-----
ISSUER CA SIGNED CERTIFICATE:
-----BEGIN CERTIFICATE-----
kItq$/mdfKhQhJ?.......
ljy;>fgYjklrjRJO/......
fg;lj@;ljfg^ms.....
.....
.....
.....
-----END CERTIFICATE------
This changed file is then imported into the keystore with the same alias as
was used to generate the private key/public certificate pair (See command
3.1). In this case, the CA's certificate is specific for only this alias. In
other words, if we import a second certificate reply from the same CA, the
"Failed to establish chain..." exception will be thrown.
| Command 3.1
keytool -import -alias <subjectkey > -file
<chaincertificate.cer> -keypass <mykeypasswd>
-keystore <mykeystore> -storepass <storepass>
For example:
keytool -import -alias joe -file joeChainCertificate.cer -keypass
joepass -keystore keystore -storepass password
The file, joeChainCertificate.cer stores the certificate reply
returned by the CA. The contents of the certificate reply replace the
self-signed certificate part of the key entry, aliased by
joe. |
Command 3.1 will import the certificate chain in the file
<chaincertificate.cer>, into the key entry aliased by
<subjectkey>, stored in <mykeystore>.
OPTION 2
In order to make the CA's root certificate available to any imported
certificate reply (from the same CA), you can import the CA's certificate as
a trusted
certificate, into the cacerts keystore. When importing a certificate
from a CA, first ensure that the subject has permissions to write to the
cacerts file under the java.home/lib/security, where
java.home is the home directory of a Java 2 runtime environment. Next,
ensure that no certificate is stored in the cacerts keystore with the same alias
that will be used to reference the CA certificate; otherwise the import will fail
(See Command 4.1).
| Command 4.1
keytool -list -alias <alias> -keystore
<keystore> -storepass <store_password>
For example:
keytool -list -alias cakey -keystore
/java.home/lib/security/cacerts -storepass
changeit |
Command 4.1 will display the contents of the key entry aliased by
<alias> in the cacerts keystore. If the <alias>
entry does not reference an existing certificate, then no output will
be returned. The keystore password for cacerts is changeit, by default.
In order to change the default password of the cacerts keystore, use
Command 4.1.1. The cacerts password should be changed prior to
using the cacerts file. Then place the certificate into the
cacerts keystore use Command 4.2.
| Command 4.1.1
keytool -storepasswd -new <new_storepass> -keystore
<Akeystore> -storepass <old_storepassword>
For example:
keytool -storepasswd -new cacertspassword -keystore
/java.home/lib/security/cacerts -storepass changeit
The cacerts keystore's password will be changed from changeit to
cacertspassword. |
| Command 4.2
keytool -import -alias <cacerts_key_entry_alias>
-file <CARootCertificate.cer> -keystore
<cacerts_keystore> -storepass <cacerts_store_password>
For example:
keytool -import -alias cakey -file CARootCertificate.cer -keystore
/java.home/lib/security/cacerts -storepass
cacertspassword |
Command 4.2 will place the CA root certificate, stored in the file
CARootCertificate.cer into an entry aliased by cakey in the
cacerts keystore.
Now, the certificate reply from the CA can be imported (See command
4.3). Note that the certificate reply is imported into the subject's
keystore that contains the key entries - NOT the cacerts keystore. When
importing the certificate reply into the keystore, the
-trustcacerts flag must be used with the import command in order
for certificates in the cacerts file to be used to establish chains of
trust with the certificate reply in the subject's keystore.
| Command 4.3
keytool -import -alias <subjectkey> -file
<chainedcertificate.cer> -keypass
<mykeypasswd> -trustcacerts -keystore <mykeystore>
-storepass <storepass>
For example:
keytool -import -alias joe -file joeChainCertificate.cer -keypass
joepass -trustcacerts -keystore keystore -storepass password
The file, joeChainCertificate.cer contains only the certificate reply
as it was generated by the CA. |
Command 4.3 will import the certificate reply stored in the
file <amended_chaindcertifcate.cer>, into the key entry of
<mykeystore>, aliased by <subjectkey>.
Using these two methods, it should be possible to import a certificate reply
into a keystore without causing a "Failed to establish chain from reply"
message.
References:
Keytool
- Key and Certificate Management Tool - A guide on how to use the Java programming language
keytool.
PKCS#7 Message
Syntax
Enstrust
Verisign
Thawte
Glossary:
| Alias: |
A shorthand name to identify a unique key entry in a keystore. |
| Cacerts file: |
A special keystore that is distributed with the Java 2 runtime
environment. It stores 'trusted' certificates. |
| Certificate Authority (CA): |
Entities that are authorised and trusted to sign certificates created
by subjects. |
| Certificate Reply: |
Contains a signed certificate or certificate chain generated by a CA
in response to a CSR. If a CA generates a certificate reply for a subject,
then the CA has authenticated the subject's identity. |
| Certificate Signed Request
(CSR): |
A subject's self-signed certificate is wrapped in a CSR and sent to a
Certificate Authority for authentication. |
| Chain of Trust: |
A chain of certificates established between an issuer-signed
certificate and a root certificate. |
| Issuer: |
An entity that signs a certificate. A certificate authority is a type
of issuer. |
| Issuer signed certificate: |
A certificate generated by the CA that authenticated the subject's
self-signed certificate. |
| Key Entry: |
A private key and public self-signed certificate pair stored in a
keystore. |
| Keystore: |
A store for a set of key entries. Usually represented in a file. |
| Root Certificate: |
A public self-signed certificate that is the last link in a
certificate chain. |
| Self-signed certificate: |
A certificate that has the same identity for the issuer and
subject. |
| Subject: |
An entity who generates a private/public key pair. |
| Trusted Certificate: |
A certificate from an issuer that the subject has deemed to be
trustworthy. |
|
