iaik.hlapi
Class KeyAndCertificate

java.lang.Object
  iaik.hlapi.KeyAndCertificate

public class KeyAndCertificate
extends Object

This class serves as a container for a private key and the corresponding certificate or the complete certificate chain.

In addition, it provides utility methods for managing private keys, certificates and certificate chains. This includes:

• Reading PKCS#12 files and Java keystores
• Storing keys in PKCS#12 files and Java keystores
• Generating key-pairs and certificates
• Generating certificate signing requests
• Reading certificate chains
• Reading certificates

For example, an application may simply read the private key with certificate chain from a PKCS#12 or PFX file, using

 KeyAndCertificate key =
     KeyAndCertificate.readPkcs12(new FileInputStream(pkcs12file), password);
 

The name (i.e. alias name of a Java KeyStore) of the key inside the keystore is available via the getKeyName method. writeKeyStore and storePkcs12 also use this name for storing the key.

Constructor Summary

KeyAndCertificate(PrivateKey key, X509Certificate userCert)
Create a new object with the given private key and certificate.

KeyAndCertificate(PrivateKey key, X509Certificate[] certChain)
Create a new object with the given private key and certificate chain.

Method Summary

byte[]	generateCertificateRequest() Create a PKCS#10 certificate request that contains the subject DN of the certificate of this object.
static KeyAndCertificate	generateSelfSigned(String algorithm, String provider, int keySize, String subjectDN) Generate a new key-pair and create a self-signed certificate with it.
X509Certificate	getCertificate() Get the certificate.
X509Certificate[]	getCertificateChain() Get the certificate chain.
static String	getEMailAddress(X509Certificate certificate) Get the e-mail address of the subject out of the certificate.
PrivateKey	getKey() Get the private key.
String	getKeyName() Get the name of this key.
String	getProviderName() Get the name of the provider that should be used for the private key of this object, e.g. for signature creation or decryption.
static String	pemEncode(byte[] value, String firstLine, String lastLine) An application may use this method to PEM-encode arbitrary binary data.
static X509Certificate	readCertificate(InputStream fileStream) Read a single certificate.
static X509Certificate[]	readCertificateChain(InputStream fileStream) Read a certificate chain.
static KeyAndCertificate[]	readKeyStore(InputStream stream, String type, String provider, char[] password) Read a Java keystore.
static KeyAndCertificate	readPkcs12(InputStream fileStream, char[] password) Read the the private key with associated certificate chain from a stream, e.g. a file input stream.
void	setKeyName(String name) Set the name of this key.
void	setProviderName(String providerName) Set the name of the provider that should be used for the private key of this object, e.g. for signature creation.
void	storePkcs12(OutputStream out, char[] password) Store this key and certificate (or certificate chain) to the given stream.
String	toString() Get a string representation of this object but omitting the dump of the private key to avoid unintended revealing of private key material.
static void	writeKeyStore(KeyAndCertificate[] keys, OutputStream out, String type, String provider, char[] password) Store the given keys with their certificates (or certificate chains) to the given stream.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

KeyAndCertificate

public KeyAndCertificate(PrivateKey key,
                         X509Certificate[] certChain)

Create a new object with the given private key and certificate chain. The chain must be ordered with the end-entity certificate first, i.e. with the certificate that corresponds to the private key.

Parameters:

key - The private key. May be null.

certChain - The ordered certificate chain with the end-user certificate at index 0. May be null.

KeyAndCertificate

public KeyAndCertificate(PrivateKey key,
                         X509Certificate userCert)

Create a new object with the given private key and certificate. The certificate must correspond to the private key.

Parameters:

key - The private key. May be null.

userCert - The certificate that corresponds to the private key or null.

Method Detail

getKey

public PrivateKey getKey()

Get the private key.

Returns:

The private key or null if unavailable.

getCertificateChain

public X509Certificate[] getCertificateChain()

Get the certificate chain.

Returns:

The certificate chain or null if unavailable.

getCertificate

public X509Certificate getCertificate()

Get the certificate. If this object was constructed with a certificate chain the certificate at index 0 is returned.

Returns:

The certificate or null if unavailable.

getProviderName

public String getProviderName()

Get the name of the provider that should be used for the private key of this object, e.g. for signature creation or decryption.

Returns:

Returns the name of the provider. null means to use defaults.

setProviderName

public void setProviderName(String providerName)

Set the name of the provider that should be used for the private key of this object, e.g. for signature creation.

Parameters:

providerName - The provider name or null to use defaults.

getKeyName

public String getKeyName()

Get the name of this key. It is used as alias name when storing the key.

Returns:

The name of the key or null if unavailable.

Postconditions

setKeyName

public void setKeyName(String name)

Set the name of this key. It is used as alias name when storing the key.

Parameters:

name - The name of the key or null if unavailable.

Preconditions

toString

public String toString()

Get a string representation of this object but omitting the dump of the private key to avoid unintended revealing of private key material.

Overrides:

toString in class Object

Returns:

A string representation of this object.

readCertificate

public static final X509Certificate readCertificate(InputStream fileStream)
                                             throws IOException,
                                                    HlApiException

Read a single certificate.

The supported formats are:

• DER-encoded binary
• PEM-encoded text

Parameters:

fileStream - The stream that provides the certificate chain.

Returns:

The parsed certificate chain.

Throws:

IOException - If reading from the stream fails.

HlApiException - If parsing the certificates fails.

Preconditions

fileStream != null

Postconditions

result != null

readCertificateChain

public static final X509Certificate[] readCertificateChain(InputStream fileStream)
                                                    throws IOException,
                                                           HlApiException

Read a certificate chain.

The supported formats are:

• DER-encoded binary
• PEM-encoded text
• PKCS#7 certificate list binary
• PKCS#7 certificate list in PEM-format text

Parameters:

fileStream - The stream that provides the certificate chain.

Returns:

The parsed certificate chain.

Throws:

IOException - If reading from the stream fails.

HlApiException - If parsing the certificates fails.

Preconditions

fileStream != null

Postconditions

result != null

readKeyStore

public static final KeyAndCertificate[] readKeyStore(InputStream stream,
                                                     String type,
                                                     String provider,
                                                     char[] password)
                                              throws IOException,
                                                     HlApiException

Read a Java keystore. This can be any keystore which is supported via the java.security.KeyStore interface, including JKS and PKCS12.

It returns the private key entries with their associated certificate chains.

Parameters:

stream - The stream that provides the keystore contents.

type - The keystore type, e.g. JKS for Java keystores from SUN.

provider - The name of the JCA provider to use, or null to use defaults.

password - The password that protects the keystore.

Returns:

The private key entries with their associated certificate chains.

Throws:

IOException - If reading from the stream fails.

HlApiException - If reading the keystore content fails.

Preconditions

fileStream != null, type != null

Postconditions

result != null

readPkcs12

public static final KeyAndCertificate readPkcs12(InputStream fileStream,
                                                 char[] password)
                                          throws IOException,
                                                 HlApiException

Read the the private key with associated certificate chain from a stream, e.g. a file input stream.

Use it like this:

  String fileName = ...
  char[] password = ...
  HlApi.readPkcs12(new FileInputStream(fileName), password);
 

Parameters:

fileStream - The stream which provides the content of the PKCS#12 file.

password - The password that protects the PKCS#12 file.

Returns:

The private key and the associated certificate chain.

Throws:

IOException - If reading the file stream fails.

HlApiException - If reading the PKCS#12 content fails.

Preconditions

fileStream != null

Postconditions

result != null

storePkcs12

public void storePkcs12(OutputStream out,
                        char[] password)
                 throws IOException,
                        HlApiException

Store this key and certificate (or certificate chain) to the given stream. The format is PKCS#12 and PFX compatible.

Parameters:

out - The output stream, e.g. a java.io.FileOutputStream.

password - The password for protecting the private key.

Throws:

IOException - If writing to the stream fails.

HlApiException - If this object does not contain a private key or a certificate.

Preconditions

(out != null)

writeKeyStore

public static void writeKeyStore(KeyAndCertificate[] keys,
                                 OutputStream out,
                                 String type,
                                 String provider,
                                 char[] password)
                          throws IOException,
                                 HlApiException

Store the given keys with their certificates (or certificate chains) to the given stream. The supported types include PKCS12 (also known as PFX), JKS and PKCS#11 is a PKCS#11 provider like the IAIK PKCS#11 provider is installed.

Parameters:

keys - The list or keys, which must not be empty.

out - The output stream, e.g. a java.io.FileOutputStream.

type - The type of keystore, e.g. JKS or PKCS12.

provider - The name of the JCA provider to use, or null to use defaults.

password - The password for protecting the private key.

Throws:

IOException - If writing to the stream fails.

HlApiException - If this object does not contain a private key or a certificate.

Preconditions

(keys != null) AND (keys.length > 0), (out != null), (type != null)

generateSelfSigned

public static final KeyAndCertificate generateSelfSigned(String algorithm,
                                                         String provider,
                                                         int keySize,
                                                         String subjectDN)
                                                  throws HlApiException

Generate a new key-pair and create a self-signed certificate with it.

Parameters:

algorithm - The JCA/JCE algorithm name for the key-pair, e.g. RSA.

provider - The optional JCA/JCE provider to use for key generation. Set null to use default.

keySize - The key size in bits, e.g. 1024.

subjectDN - The subject distinguished name (DN) as RFC 2253 string, e.g. CN=Karl Scheibelhofer,O=IAIK,C=AT,EMAIL=karl.scheibelhofer@iaik.at

Returns:

The key and self-signed certificate.

Throws:

HlApiException

Preconditions

(algorithm != null), (keySize > 0), (subjectDN != null)

Postconditions

(result != null)

generateCertificateRequest

public byte[] generateCertificateRequest()
                                  throws HlApiException

Create a PKCS#10 certificate request that contains the subject DN of the certificate of this object.

This method is especially useful for objects that have just been created using generateSelfSigned(String, String, int, String). The self-signed certificate acts as a place-holder until the actual certificate or certificate chain is available (i.e. issued by a CA).

The application may need to encode the result using pemEncode(byte[], String, String) before for sending it to the CA. However, this depends on the CA.

Returns:

The DER-encoded PKCS#10 certificate request.

Throws:

HlApiException

Postconditions

(result != null)

pemEncode

public static String pemEncode(byte[] value,
                               String firstLine,
                               String lastLine)

An application may use this method to PEM-encode arbitrary binary data.

For example, it may use it to convert a certificate signing request (CSR) into a text message, e.g.

  KeyAndCertificate keyAndCert = 
    KeyAndCertificate.generateSelfSigned("RSA", 1024, 
      "CN=Karl Scheibelhofer,O=IAIK,C=AT,EMAIL=karl.scheibelhofer@iaik.at");
  byte[] binaryCSR = keyAndCert.createCertificateRequest();
  String textCSR = KeyAndCertificate.pemEncode(
    binaryCSR,
    "-----BEGIN NEW CERTIFICATE REQUEST-----",
    "-----END NEW CERTIFICATE REQUEST-----");
 

Parameters:

value - The binary value.

firstLine - The first line in the encoding, e.g. -----BEGIN NEW CERTIFICATE REQUEST----- for a certificate request.

lastLine - The last line in the encoding, e.g. -----END NEW CERTIFICATE REQUEST----- for a certificate request.

Returns:

The encoded data, e.g. something like

   -----BEGIN CERTIFICATE-----
   MIIEijCCA3KgAwIBAgIBETANBgkqhkiG9w0BAQUFADBBMRAwDgYDVQQKEwdFdXJv
   ...
   QRdSvpib2FjBq57wfHY=
   -----END CERTIFICATE-----
 

Preconditions

(value != null), (firstLine != null), (lastLine != null)

Postconditions

(result != null)

getEMailAddress

public static String getEMailAddress(X509Certificate certificate)
                              throws HlApiException

Get the e-mail address of the subject out of the certificate.

First, it searches in the subject DN for an e-mail address. Second, it looks for an e-mail address in the subject alternative name extension, if present.

Parameters:

certificate - The X.509 certificate containing the subject's e-mail address.

Returns:

The e-mail address string of null if no e-mail address was found.

Throws:

HlApiException - If parsing the certificate fails.