The Key Certificate Management contains the following packages:

com.ibm.security.certclient

A set of classes to generate a CertificateRequest, submit a request to a CA via Java PKI to sign a certificate and then receive the signed certificate, and revoke a signed certificate.

com.ibm.security.certclient.util

A set of classes to generate a Self-Signed Certificate.

com.ibm.security.keystoreutil

A set of classes that provides utilities for converting between different KeyStore formats and importing and exporting Certificates from and to Input and Output Streams.

com.ibm.security.keystoreski

A set of classes that provides untilites for extracting information from a KeyStore given a Subject Key Identifier. A Subject Key Identifier is specified in RFC 3820 Section 4.2.1.2.

This Key Certificate Management How-To Guide provides examples how to use the most common features of Key Certificate Management. See the javadocs for a complete listing of all apis.

Example: Copy the entire contents of one type of KeyStore to another KeyStore. In this case, we will copy from a PKCS12 type KeyStore to a CMS type KeyStore. The target KeyStore provider is optional. If no provider is specified, then the java security provider list will be used. In this case, all the keys have the same password as the KeyStore itself.

KeyStore source = KeyStore.getInstance("PKCS12");
java.io.FileInputStream fis =
           new java.io.FileInputStream("keyStoreName");

source.load(null, PASSWORD.toCharArray());

// The KeyStore source needs to be loaded.  Example assumes that all
/ the keys have the same password as the KeyStore itself -
// in this case "PASSWORD".
KeyStoreTranslatorParameters parameter =
    KeyStoreUtil.newTranslatorParameters
                  (source, PASSWORD.toCharArray(), null);

// Create a CMS KeyStore translator.  Use provider order to find
// CMSKS provider.
KeyStoreTranslator translator2CMSKS =
                 KeyStoreUtil.newTranslator("IBMCMSKS");

// Copy KeyStore
KeyStore target = translator2CMSKS.translateStore(parameter);

Example: Export the certificate associated with the specified alias from the keystore to the output stream. The keystore is already loaded. The certificate can be exported in BASE64 or DER format.

// Export a certificate to an output stream from a KeyStore in Base64 format
// and the name of the alias is provided.
KeyStore store = KeyStore.getInstance("JKS");
java.io.FileInputStream fis =
             new java.io.FileInputStream("keyStoreName");
store.load(fis, PASSWORD.toCharArray());

ByteArrayOutputStream out1 = new ByteArrayOutputStream();

KeyStoreUtil.exportCertificate(out1, store, "Test User", true);

Example: Import a certicate from an input stream into a KeyStore. The certificate can be imported from input stream in binary or Base64 format. The keystore must be initialized and loaded. An alias name may be provided. If no alias is provided, then the Subject DN's Common Name (CN) will be used.

// Import a certificate from an input stream into a KeyStore in DER format
// and provide the name of the alias.
KeyStore store = KeyStore.getInstance("JKS");
// Create an empty keystore - certificate will be loaded here
store.load(null, PASSWORD.toCharArray());

FileInputStream fis = new FileInputStream("cacert.der");

KeyStoreUtil.importCertificate(fis, store, "MYALIAS");

Example: Import a set of certificates that are encoded in PKCS#7 format, from an input stream into a KeyStore. The Subject DN's Common Name (CN) of the certificate will be used as the corresponding alias of the certificate in the KeyStore. The KeyStore should be loaded and initialized.

KeyStoreUtil.importCertificates(fis, store);

Example: Here we are extracting from the certificate the SKI from the SHA-1 hash of the public key of the certificate.

// Extract the SKI from the certificate by calculating the SKI from the
// SHA-1 hash of the public key of the certificate.
SKIDefinition definition = SKIDefinition.newSHA1PublicKeySKIDefinition();
String ski = definition.getSubjectKeyIdentifier(caCert);

This example shows how to get the alias, certificate and private key from a KeyStore using a composite SKIDefinition.

String filename = "keys.pfx";
KeyStore ks = KeyStore.getInstance("PKCS12");
InputStream in = new FileInputStream(filename);

char[] password = "NEWPASSWORD".toCharArray();
ks.load(in, password);

// Construct a KeyStoreSKI to operate on the KeyStore.
KeyStoreSKI kss = KeyStoreSKIFactory.newKeyStoreSKI(ks);

// The subject key identifier that is going to be the search criteria.
// It should be in Base64 format.
String ski = ...;
// The definition of how to obtain the Subject Key Identifier from the
// each entry in the key store.
// It is defined by first inspecting the extension field (2.5.29.14),
// and if that fails, generating the
// SHA-1 hash of the public key as specified in RFC 3280 Section
// 4.2.1.2.
SKIDefinition definition1 =
         SKIDefinitionFactory.newX509ExtensionSKIDefinition();
SKIDefinition definition2 =
         SKIDefinitionFactory.newSHA1PublicKeySKIDefinition();

SKIDefinition definition =
       SKIDefinitionFactory.newCompositeSKIDefinition
              (definition1, definition2);

// Obtain the first alias associated with an end entity certificate
// that matches the Subject Key Identifier criteria with the
// given Subject Key Identifier definition.
String alias = kss.getAlias(ski, definition);

// Obtain the first certificate associated with an end entity
// certificate that matches the Subject Key Identifier
// criteria with the given Subject Key Identifier definition.
Certificate certificate = kss.getCertificate(ski, definition);

// Obtain the first private key with an end entity certificate that
// matches the Subject Key Identifier
// criteria with the given Subject Key Identifier definition.
PrivateKey privateKey = kss.getPrivateKey(ski, definition, password);

// Output the alias.
System.out.println(alias);

// Output the public key.
System.out.println(certificate.getPublicKey().toString());

// Output the private key in hexadecimal.
if(privateKey != null){
    System.out.println(privateKey.toString());
}

Example: Create a self-signed certificate with the supplied extensions. The keypair will be created for you.

// Create a self-signed certificate with the requested extensions.
int keysize = 192;                      // size of key
String keyType = "EC"                   // Valid key types are: RSA,DSA,EC. Not used if keyPair is provided.
String signatureAlgorithm = "SHA256withECDSA";   // signature algorithm
int validDays = 365;                    // period of certificate validity
Date notBefore = null;                  // Date that this certificate validity begins.
                                        // Must be no greater  than 3 days prior to the issuing UTC time. If null, 
                                        // current Date will be used.
boolean useSSKid = true;                // if true use short form of
                                        // Subject Key Identifier
                                        // else use long form
String subjectDN = "cn=test,o=Tivoli,c=US";
                                        // Distinguished name which will
                                        // be used for both the subject
                                        // and issuer of this certificate

String[] acceptableUse = {"digital_signature", "non_repudiation",
    "key_encipherment",
    "data_encipherment", "encipher_only", "decipher_only" };
String[] acceptableExtUse = {"ServerAuth_Id", "ClientAuth_Id",
    "CodeSigning_Id", "EmailProtection_Id",
    "IPSecEndSystem_Id", "IPSecTunnel_Id",
    "IPSecUser_Id", "TimeStamping_Id" };
String[] acceptableSan = { "newUser@us.ibm.com", "www.ibm.com",
    "http://www.tivoli.com/index", "192.100.123.251" };


List<String> san = Arrays.asList(acceptableSan);   // (optional) list of
                                                   // subject alternate
                                                   // names.  Specify null
                                                   // to indicate
                                                   //no value is being
                                                   //  specified.
List<String> kuse = Arrays.asList(acceptableUse);  // (optional) list of
                                                   // Key Usage
                                                   // strings.
List<String> extkuse = Arrays.asList(acceptableExtUse);//(optional) list
                                                   // of Extended Key
                                                   // Usage strings.
String provider = "IBMJCE";                        // name of the crypto
                                                   // provider to be used
KeyPair keyPair = null;                            // keypair to use for private/public keys
                                                   // if null, keypair will be generated

boolean isCA =  true;                              // true - create this certificate as a CA with basic constraints
                                                   // false - create this certificate as an end-user without basic constraints

// Create the self-signed certificate with requested extensions
PkSsCertificate sscert = PkSsCertFactory.newSsCert(
                                     keysize,
                                     keyType,
                                     signatureAlgorithm,
                                     subjectDN,
                                     validDays,
                                     notBefore,
                                     useSSKid,
                                     san,
                                     kuse,
                                     extkuse,
                                     provider,
                                     keyPair,
                                     isCA);


PrivateKey key = sscert.getKey();   // Extract the private key for the
                                    // self-signed certificate
PublicKey publicKey = sscert.getPublicKey();  // Extract the public key
X509Certificate cert = sscert.getCertificate();  // Extract the self-signed
                                                 // certificate

// Create keystore
KeyStore store = KeyStore.getInstance("JKS");
store.load(null, PASSWORD.toCharArray());

// Save this self-signed certificate along with the private key
// in the keystore           
sscert.setToKeySTore("alias", "ksPassword", keystore);

Example: Create an X509Certificate from a PKCS10 certificate request using the Pk10CertFactory.newCert( ) method.

// Use the Key Cert Management class "PkEeReqFactory" to create
// a CertificateRequestTransaction from which a PKCS10 certificate request
// can be obtained.
PkEeCertReqTransaction crt = null;
try {
    crt = PkEeCertReqFactory.newCertRequest(
             keysize,    // Size of key.
                         // Not used if a keyPair is provided.
             subject,    // The Relative DN for the subject.
                         // Prepended to the value of "dn" to create the subject DN.
             validDays,  // Period of certificate validity.
             keyType     // valid key types are: RSA/DSA/EC
             signatureAlgorithm, // signature algorithm
             useShortSubjectKeyId,   // If true use short form of Subject Key Id
             san,        // List of subject alternate names.
             kuse,       // List of Key Usage strings.
             extkuse,    // List of Extended Key Usage strings.
             iafile,     // initial authorisation file
             revPwd,     // password to be used when revoking this certificate
             dn,         // domain name for certificate request.
             );  

} catch (Exception ex) {
    System.out.println("Exception thrown while creating PkEeCertReqTransaction.");
}

// Lift the PKCS10 certificate request from the CertificateRequestTransaction object
byte[] derPKCS10 = null;
try {
    derPKCS10 = crt.getPKCS10CertReq();
} catch (Exception ex) {
    System.out.println("Exception thrown while obtaining PKCS10 request.");
}

CertificationRequest cr = null;
try {
    // Create a CertificationRequest object
    cr = new CertificationRequest(derPKCS10);
    // Write the BASE64 encoded PKCS10 request to a file
    cr.writeBASE64(PKCS10CertificateRequestFile);

} catch (Exception ex) {
    System.out.println("Exception thrown while writing PKCS10 request to file.");
}

Pk10Certificate myPk10Certificate = null;
X509Certificate myX509Certificate = null;
try {
    // Create the certificate from the certificate request
    Date notBeforeDate = Date();
    myPk10Certificate = Pk10CertFactory.newCert(PKCS10CertificateRequestFile,
                                                 (Date)notBeforeDate,
                                                 365,
                                                 (X509Certificate)signersCert,
                                                 (PrivateKey)signersPrivateKey);
    // Obtain the X509Certificate created from the Pk10Certificate object
    myX509Certificate = myPk10Certificate.getCertificate();
}
catch (PkRejectionException e)
{
    System.out.println("Exception thrown while creating certificate.");
}

Create a PKCS10 request. In this example, the KeyPair will be created for you. Optionally, the KeyPair can be supplied.

 // Create a PKCS10 request.
 PkEeFactory.setCA_DN("o=IBM,c=US");       // It will be appended to the
                                           // Subject value in
                                           // the newCertRequest to create
                                           // the SubjectDN.

 String subject = "cn=Test Group";
 // Initialize a certificate request with the following defaults:
 // keysize of 1024,
 // valid for 365 days, RSA key with SHA1withRSA signature algorithm,
 // Use the RFC 3280 Long form to create the Subject Key Identifier and
 // create with no Subject Alternate Name, Key Usage or Extended Key Usage.

 PkEeCertReqTransaction crt = PkEeCertReqFactory.newCertRequest
                                 (subject, null, null, null);
                                         // Initialize certificate request.
 byte[] pkcs10req = crt.getPKCS10Req();  // Create DER encoded PKCS10 form
                                         // of the certificate request from
                                         // the parameters provided.

 // Get the KeyPair which was used to create this PKCS10 reqest
 KeyPair keypair = crt.getKeyPair();

Example: Produce a certificate transaction request using an existing PKCS#10 base64 formatted request. Send the request to the CA for signing and get the signed certificate returned.

 // Initialize a certificate request using an already
 // created PKCS#10 request.

 // Initialize the information required in order to access the CA
 // Server which is to sign the certificate request.

 PkEeFactory.setCaDn("example.com"); // Set the DN of the
                                                       // CA host.
                                                  // Default is "localhost".
 PkEeFactory.setCaPort(1077);    // Set the port to be used for
                                 // communication with the
                                 // CA.  Default is 1077
 PkEeFactory.setProvider("IBMJCE");    // Sets the Java Security
                                  // provider.  Defaults to "IBMJCE".

 // certFile is the pathname of the file containing the certificate request
 // in BASE64 format
 // iaFile is the initial authorization file containing the reference
 // number passphrase on consecutive lines
 // revocation-password is the password which will be used if this
 // certificate ever needs to be revoked in the future.

 PkEeReqTransaction crt = PkEeCertReq10Factory.newCertRequestPKCS10
                             (certFile, iaFile, revocation-password);

 // Send the request to the CA via CMP for processing
 crt.actionRequest();

 // Get the signed certificate which was returned from the CA
 X509Certificate cert = crt.getSignedCert();

Example: Initialize and send a certificate request transaction to the CA for signing. Receive the signed certificate and save in the keystore provided. The certificate can be created with or without extensions. The extensions can be supplied when the certificate request is initialially created or any time before the certificate is sent to the CA for signing. Optionally, the private keypair can be supplied or a keypair will be created for you. The signed certificate and the private key can be saved in the keystore provided.

// Initialize a certificate request to the CA for signing.

// Initialize communication information for the CA Server to sign
// the certificate request, the keystore name and password and
// the name of Java Security provider which should be
// used.

PkEeFactory.setCaDn("example.com");// Set DN of CA host.
                                            // Default is "localhost".

PkEeFactory.setCaPort(1077);    // Set the port to be used for
                                // communication with the
                                // CA.  Default is 1077
PkEeFactory.setCA_DN("o=IBM,c=US");       // It will be appended to the
                                          // Subject value in
                                          // the newCertRequest to create
                                          // the SubjectDN.
PkEeFactory.setKeyStoreFilename("eeStore");  // The name of the keystore
                                // to be used
                                // when the signed certificate is
                                // saved into the keystore.  Default
                                // is "eeStore".  If the keystore does not
                                // exist, it will be created.
PkEeFactory.setKeyStorePwd("password".toCharArray());
                                // The KeyStore password.  No Default.
PkEeFactory.setKeyStoreType("jks");          // The KeyStore type.
                                             // Defaults to "jks".
PkEeFactory.setProvider("IBMJCE");           // Sets the Java Security
                                             // provider.  Defaults
                                             // to "IBMJCE".

int keysize = 1024;                        // size of key
String subject = "CN=Test Group";          // relative DN for the subject.
                                           // It will be
                                           // prepended to the value of dn
                                           // to create
                                           // the Subject DN.
int validDays = 365;                       // period of certificate
                                           // validity
String keyType="RSA";                      // RSA key
String sigAlg = "SHA1withRSA"              // signature algorithm
boolean useSSKid = true;                   // if true use short form of
                                           // Subject Key Identifier
                                           // else use long form
String dn = "o=IBM,c=US";                  // Domain name to be used
                                           // in certificate prepended to
                                           // the value of subject.  If
                                           // null, PkEeFactory CA_DN will
                                           // be used.

String[] acceptableUse = {"digital_signature", "non_repudiation",
    "key_encipherment",
    "data_encipherment", "encipher_only", "decipher_only" };
String[] acceptableExtUse = {"ServerAuth_Id", "ClientAuth_Id",
    "CodeSigning_Id",
    "EmailProtection_Id",
    "IPSecEndSystem_Id", "IPSecTunnel_Id","IPSecUser_Id",
    "TimeStamping_Id" };
String[] acceptableSan = { "newUser@us.ibm.com", "www.ibm.com",
    "http://www.tivoli.com/index", "192.100.123.251" };

List<String> san = Arrays.asList(acceptableSan);   // (optional) list of
                                                   // subject alternate
                                                   // names.  Specify null
                                                   // to indicate
                                                   // no value is being
                                                   // specified.
List<String> kuse = Arrays.asList(acceptableUse);  // (optional) list of
                                                   // Key Usage
                                                   // strings.
List<String> extkuse = Arrays.asList(acceptableExtUse);  // (optional)
                                                   // list of Extended Key
                                                   // Usage strings.
String provider = "IBMJCE";                        // name of the crypto
                                                   // provider to be used

// Create the certificate request with the requested extensions.
// The keypair will be created for you.
//
// iaFile is the initial authorization file containing the
// reference number and passphrase on consecutive lines
// revocation-password is the password to be used when revoking
// this certificate after it has been signed.
PkEeCertReqTransaction crt = PkEeCertReqFactory.newCertRequest
                           (keysize, subject, validDays,
                            keyType, sigAlg, useSSKid, san, kuse, extkuse, iaFile,
                            revocation-password, dn);

// Send the request to the CA via CMP for processing
crt.actionRequest();

// Get the signed certificate which was returned from the CA
X509Certificate cert = crt.getSignedCert();

// Get the private key which was created
PrivateKey key = crt.getKey();
// Get the public key which was created
PublicKey publicKey = crt.getPublicKey();

// Save the signed certificate along with the private key in the keystore.
// The keystore to be used is specified by PkEeFactory.  The password to
// be used to open the keystore is specified by PkEeFactory too.  The
// password specified when storing the entry is the password for the
// private key entry.  It may be the same as the password for opening
// the keystore specified by PkEeFactory.setKeyStorePwd.
crt.storeNewEntry("alias", "keypwd");

Example: Revoke a signed certificate. Initiate and send the certificate revocation request to the CA. The certificate that is being revoked must be in EE's keystore.

// Revoke a signed certificate
// Initialize communication information for the CA Server which will
// revoke the certificate request, also
// the Keystore name and password and name of Java Security provider which
// should be used.

PkEeFactory.setCaDn("example.com");// Set DN of CA host.
                                             // Default is "localhost".
PkEeFactory.setCaPort(1077);    // Set the port to be used for
                                // communication with the
                                // CA.  Default is 1077
PkEeFactory.setKeyStoreFileName("eeStore");  // The name of the keystore
                                             // which contains
                                             // the certificate which is
                                             // to be revoked.
                                             // Default is "eeStore".
PkEeFactory.setKeyStorePwd("password".toCharArray()); // KeyStore password.
                                             // No Default.
PkEeFactory.setKeyStoreType("jks");          // The KeyStore type.
                                             // Defaults to "jks".
PkEeFactory.setProvider("IBMJCE");           // Sets the Java Security
                                             // provider.  Defaults
                                             // to "IBMJCE".

// certAlias is the alias of the certificate being revoked.  The EE
//       keystore to be used is defined by PkEeFactory.
// certPwd is the password for the key in the KeyStore being revoked.
// revocation-reason is the reason for this revocation.  The reason must
//       be one of the following:
//         "unspecified", "key compromise", "ca compromise",
//         "affiliation changed",
//         "superseded", "cessation of operation",
//         "certificate hold" and "remove from crl".
// revocation-password is the password to revoke this certificate.
//       This was the password supplied when
//       the certificate request was requested.
PkEeTransaction revoke = PkEeRevokeFactory.newRevoke(certAlias, certPwd,
              revocation-reason, revocation-password);

// Send the certificate revocation request to the CA via CMP for
// processing
revoke.actionRequest();

IBM may have patents or pending patent applications covering subject matter in this document. The furnishing of this document does not give you any license to these patents. You can send license inquiries, in writing, to:

IBM Director of Licensing
IBM Corporation
North Castle Drive, Armonk
NY 10504-1758 U.S.A.

For license inquiries regarding double-byte (DBCS) information, contact the IBM Intellectual Property Department in your country or send inquiries, in writing, to:

Intellectual Property Licensing
Legal and Intellectual Property Law IBM Japan Ltd.
1623-14, Shimotsuruma, Yamato-shi
Kanagawa 242-8502 Japan

Licensees of this program who wish to have information about it for the purpose of enabling (i) the exchange of information between independently created programs and other programs (including this one) and (ii) the mutual use of the information which has been exchanged, should contact:

JIMMAIL@uk.ibm.com
[Hursley Java Technology Center (JTC) contact]