In SAML Xml Signature package, we use keytool from jdk1.3.1 (or higher version jdk) to manage private key and its associated X.509 certificate chains authenticating the corresponding public keys.
I. Background knowledge:
What is keytool?
keytool 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.
What is keystore?
keytool stores the keys and certificates in a so-called keystore. The
default keystore implementation implements the keystore as a file. It protects
private keys with a password.
What is keystore Alias?
All keystore entries (key and trusted certificate entries) are accessed
via unique aliases. Aliases are case-insensitive; the aliases Hugo and
hugo would refer to the same keystore entry.
An alias is specified when you add an entity to the keystore using
the -genkey command to generate a key pair (public and private key) or
the -import command to add a certificate or certificate chain to the list
of trusted certificates. Subsequent keytool commands must use this same
alias to refer to the entity.
II. Command:
1.Adding data to the keystore
keytool -genkey {-alias alias} {-keyalg keyalg} {-keysize keysize} {-sigalg
sigalg} [-dname dname] [-keypass keypass] {-validity valDays} {-storetype
storetype} {-keystore keystore} [-storepass storepass] [-provider
provider_class_name] {-v} {-Jjavaoption}
-import {-alias alias} {-file cert_file} [-keypass keypass] {-noprompt}
{-trustcacerts} {-storetype storetype} {-keystore keystore} [-storepass
storepass] [-provider provider_class_name] {-v} {-Jjavaoption}
-selfcert {-alias alias} {-sigalg sigalg} {-dname dname} {-validity
valDays} [-keypass keypass] {-storetype storetype} {-keystore keystore}
[-storepass storepass] [-provider provider_class_name] {-v}
{-Jjavaoption}
-identitydb {-file idb_file} {-storetype storetype} {-keystore keystore}
[-storepass storepass] [-provider provider_class_name] {-v}
{-Jjavaoption}
2. Exporting Data
-certreq {-alias alias} {-sigalg sigalg} {-file certreq_file} [-keypass
keypass] {-storetype storetype} {-keystore keystore} [-storepass
storepass] [-provider provider_class_name] {-v} {-Jjavaoption}
-export {-alias alias} {-file cert_file} {-storetype storetype}
{-keystore keystore} [-storepass storepass] [-provider
provider_class_name] {-rfc} {-v} {-Jjavaoption}
3. Displaying Data:
-list {-alias alias} {-storetype storetype} {-keystore keystore}
[-storepass storepass] [-provider provider_class_name] {-v | -rfc}
{-Jjavaoption}
-printcert {-file cert_file} {-v} {-Jjavaoption}
4. Managing the KeyStore
-keyclone {-alias alias} [-dest dest_alias] [-keypass keypass] [-new
new_keypass] {-storetype storetype} {-keystore keystore} [-storepass
storepass] [-provider provider_class_name] {-v} {-Jjavaoption}
-storepasswd [-new new_storepass] {-storetype storetype} {-keystore
keystore} [-storepass storepass] [-provider provider_class_name] {-v}
{-Jjavaoption}
-keypasswd {-alias alias} [-keypass old_keypass] [-new new_keypass]
{-storetype storetype} {-keystore keystore} [-storepass storepass]
[-provider provider_class_name] {-v} {-Jjavaoption}
-delete [-alias alias] {-storetype storetype} {-keystore keystore}
[-storepass storepass] [-provider provider_class_name] {-v}
{-Jjavaoption}
5. Getting Help:
-help
III. The following descries the detail of key management for SAML:
Please make sure that you use the keytool provided with the java bundled
with
the Access Manager installation. This can be obtained from
<JAVA_HOME>/bin/keytool. JAVA_HOME by default is <IS-install-dir>/SUNWam/java
if JDK is installed by Access Manager. If custom JDK has been used
use keytool from JAVA_HOME accordingly.
<IS-install-dir> by default is /opt.
1.Generate the key pair
keytool -genkey -keyalg dsa -alias test -dname "cn=sun-unix,ou=SUN
Java System Access Manager,o=Sun, c=US" -keypass 11111111 -keystore mykeystore
-storepass 11111111 -validity 180
If you do not specify the store location, a keystore named ".keystore"
will be generated in your home directory. If you do not specify the Alias,
"mykey" is creates as the default alias.
If you prefer to generate an RSA key, please use "-keyalg rsa" in above
command.
2.Requesting a Signed Certificate from a Certification Authority
keytool -certreq -alias test -file request.csr -keypass 11111111 -keystore
mykeystore -storepass 11111111 -storetype JKS
A file "request.csr" will be generated under your current directory
3.Get the cetificate from a CA
Submit this file "request.csr" to a CA, such as SUN Java System Access Manager
CMS. The CA will authenticate you the requester (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.) Save the root CA to a file "myroot.cer" and the server certificate
to a file "mycert.cer"
4.Importing a Certificate for the CA
keytool -import -file myroot.cer -keypass 11111111 -keystore mykeystore
-storepass 11111111
keytool in j2se 1.4.2 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 Internet RFC 1421 standard. 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".
5. Importing the Certificate Reply from the CA
keytool -import -alias test -trustcacerts -file mycert.cer -keypass
11111111 -keystore mykeystore -storepass 11111111
6.cd to <install dir>/SUNWam/bin
ampassword -e <original password>
to encrypt the password before put them into .storepass and .keypass
eg.
ampassword -e 11111111
we will get AQICKuNVNc9WXxiUyd8j9o/BR22szk8u69ME
7.Create a new file named .storepass and put storepass, e.g.put AQICKuNVNc9WXxiUyd8j9o/BR22szk8u69ME
to this file.
8.Create a new file name .keypass and put keypass, e.g put AQICKuNVNc9WXxiUyd8j9o/BR22szk8u69ME
to this file.
9.Copy the keystore file mykeystore to the location specified in AMConfig.properties.
For example, if com.sun.identity.saml.xmlsig.keystore=/etc/opt/SUNWam/lib/keystore.jks
is specified in AMConfig.properties, the user should copy mykeystore
to /etc/opt/SUNWam/lib/ and rename mykeystore to keystore.kjs
10.Copy the .keypass and .storepass files to the location specified
in AMConfig.properties.
For example, if
com.sun.identity.saml.xmlsig.storepass=/etc/opt/SUNWam/config/.storepass
com.sun.identity.saml.xmlsig.keypass=/etc/opt/SUNWam/config/.keypass
defined in AMConfig.properties,
the user should copy .keypass and .storepass created in step 6 and
7 to /etc/opt/SUNWam/config directory.
11. The user should specify the certAlias for signing Assertion, Request,
Response and verifying Assertion in AMConfig.porperties.
For example, define com.sun.identity.saml.xmlsig.certalias=test in
AMConfig.properties.
12. If the private key used for signing is an RSA key, Edit <install
dir>/SUNWam/locale/amSAML.properties
file, change "xmlsigalgorithm=http://www.w3.org/2000/09/xmldsig#dsa-sha1"
to "xmlsigalgorithm=http://www.w3.org/2000/09/xmldsig#rsa-sha1"
13. The user can also change the canonicalization method for signing.
Edit <install dir>/
locale/amSAML.properties file, change
canonicalizationMethod=http://www.w3.org/2001/10/xml-exc-c14n#
to any valid canonicalization method specified in Apache XML security
package Version 1.0.5
If the user delete this entry or leave canonicalMethod to a empty string
or space, we will
use SAMLConstants.ALGO_ID_C14N_OMIT_COMMENTS which is REQUIRED by the
XML Signature
specification instead.
14. The user can also change the transform algorithm for signing. Edit
<install dir>/
locale/amSAML.properties file, change
transformAlgorithm=http://www.w3.org/2001/10/xml-exc-c14n#
to any valid transform algorithm specified in Apache XML security package
Version 1.0.5
If the user delete this entry or leave transformAlgorithm to a empty
string or space, we will not
perform such transform due to performance reason.
15.Restart the amserver
IV: Some useful command
1) print a cert
keytool -printcert -file "mycert.cer"
2)list an alias
keytool -list -alias test
For more information on keytool, please refer to
http://java.sun.com/j2se/1.4.2/docs/tooldocs/solaris/keytool.html