Key Certificate Management
How-To Guide
The Key Certificate Management is a set of packages used to access keys and certificates stored in any format, extract information from a KeyStore given a Subject Key Identifier (SKI), create a self-signed certificate, generate a CertificateRequest to send manually or use Java PKI to send it to a CA and obtain the signed certificate and revoke a certificate.
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.
Package com.ibm.security.keystoreutil
Package com.ibm.security.keystoreutil provides a common interface for converting between different KeyStore formats. This provides the ability to copy the contents of the keys and certificates from one KeyStore format to a different type of KeyStore format. There will be instances where the KeyStore does not allow this. The package also provides the ability to export a specific certificate from a KeyStore to the output stream or import a certficate or a set of certificates from the input stream to a KeyStore.
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);
Package com.ibm.security.keystoreski
This package provides utilities for extracting information from a KeyStore given a Subject Key Identifier (SKI). The Subject Key Identifier is an extension of the X.509 Public Key Infrastructure, which is described in RFC 3280, Section 4.2.1.2 Section 4.2.1.2.
According to RFC 3280, section 4.2.1.2, there are multiple ways in which the Subject Key Identifier may be derived. The class com.ibm.security.keystoreski.SKIDefinition represents this SKI. Before the Subject Key Identifier can be extracted from the certificate, the com.ibm.security.keystoreski.SKIDefinitionFactory must be initialized with which SKIDefinition implementation should be used.
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);
Class com.ibm.security.keystoreski.KeyStoreSKI provides the ability to extract information from a KeyStore given the Subject Key Identifier (SKI). How the SKI is extracted is defined by the SKIDefinition discussed above.
The interface assumes that all entries within a keystore have a unique Subject Key Identifier values. If this is not the case, the first matching SKI will be returned.
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());
}
Package com.ibm.security.certclient.util
This is a package to create a self-signed certificate with no extensions or with the requested extensions. The self-signed certificate and private key can be saved in the supplied keystore. A keypair can be supplied, else a keypair will be created along with the self-signed certificate generation request.
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 = 1024; // size of key
int validDays = 365; // period of certificate validity
boolean useRsa = true; // if true use RSA key with
// SHA1withRSA signature
// algorithm else use DSA with
// SHA1withDSA
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
// Create the self-signed certificate with requested extensions
PkSsCertificate sscert = PkSsCertFactory.newSsCert(keysize, subjectDN,
validDays,
useRSA, useSSKid, san, kuse,
extkuse,
provider);
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);
Package com.ibm.security.certclient
This package provides the classes for certificate request transactions. A certificate request can be requested, and sent to a CA via CMP and the CA signed certificate returned. A certificate request can be requested and the DER encoded PKCS10 form of the PKCS10 request be returned. The PKCS10 request can be sent to the CA via CMP or sent to the CA in another manner, such as email. Lastly, a request can be made to revoke a signed certificate from a CA.
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 = "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
boolean useRsa = true; // if true create RSA key
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,
useRSA, 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();
|
