Installing Client Certificates

Installing Client Certificates

The ICEssl module has support for client authentication using client certificates. In the reference implementation interfaces, this is a file of PEM-encoded X509 certificates followed by the corresponding PKCS#8 PEM formatted private key after each certificate. The private keys may be pkcs#5-encrypted, but then they must all use the same key.

To authenticate yourself, you need to have a private key and a corresponding client certificate. A server may send a certificate request, which contains a list of accepted signers' distinguished names. Then the user must select a certificate that is signed by one of those signers. The selectName( ) method in the installed CertificateCallback is called with an array of accepted signer names every time a certificate request is received from the server.

The certificate manager contains a ClientCertificateList. This list is not used automatically by the SSL classes, but provided for convenience. The certificate manager contains the method matchIssuers( ), which takes an array of distinguished names and returns a list of certificates signed by CAs having one of these names.

By default, an empty list of client certificates is installed. Certificates can be added to this list by adding certificates to the installed list. The restoreListFromPEM( ) method can be used to load certificates.

The following code installs a list of client certificates from an unencrypted file. The variable in is an InputStream that points to a file of client certificates and private keys.
CertificateManager.getCertificateManager().setClientCertificates

(ClientCertificateList.restoreListFromPEM(in,null));
 
To use a file with encrypted certificates, in the following code, encrypted with the string "password", load the list as follows:
byte[] thekey = "password".getBytes();

PKCS8PrivateKeyFactory pkcs8fac = new PKCS8PrivateKeyFactory(passwd);

CertificateManager.getCertificateManager().setClientCertificates

    (ClientCertificateList.restoreListFromPEM(in,pkcs8fac));
 
Client Certificate File

The restoreListFromPEM( ) function reads a list of client certificates and their private key. The client certificate file contains PEM formatted X.509 certificates, each immediately followed by a PKCS#8 or SSLEAY format private key, also in PEM format. This means that certificate files are text files that can be edited in a text editor.

A client certificate may look as follows:
Client certificate for one of our employees:

-----BEGIN CERTIFICATE-----

MIICyzCCAjQCAQYwDQYJKoZIhvcNAQEEBQAwgccxCzAJBgNVBAYTAm5vMRIwEAYD

VQQIEwlIb3JkYWxhbmQxDzANBgNVBAcTBkJlcmdlbjEdMBsGA1UEChMUSUNFc29m

dCB0ZWNobm9sb2dpZXMxJzAlBgNVBAsTHkNsaWVudCBDZXJ0aWZpY2F0aW9uIGF1

dGhvcml0eTEnMCUGA1UEAxMeQ2xpZW50IENlcnRpZmljYXRpb24gYXV0aG9yaXR5

MSIwIAYJKoZIhvcNAQkBFhNpY2Vzb2Z0QGljZXNvZnQuY29tMB4XDTAzMDExMzEw

MjQxOFoXDTA0MDExMzEwMjQxOFowgZMxCzAJBgNVBAYTAm5vMQ8wDQYDVQQIEwZO

b3J3YXkxDzANBgNVBAcTBkJlcmdlbjEQMA4GA1UEChMHSUNFc29mdDEYMBYGA1UE

CxMPVGVzdCBkZXBhcnRtZW50MREwDwYDVQQDEwhKb2huIERvZTEjMCEGCSqGSIb3

DQEJARYUc2hlcnNrZWRAaWNlc29mdC5jb20wgZ8wDQYJKoZIhvcNAQEBBQADgY0A

MIGJAoGBAM+y79NrHT4kBYC78yS06N0M0as+sLs+kRK12Py9c8U4yfOYL+z4TtL1

UNgoXerA1sdZe+NtSxsvDqx8w+j5tBEIsJ8Il6/kc4GZr7SQx+igpX9Te51MQam4

hvPEztNg7kOT65lqNtciHjqcKN7WE2lqJcaJ8edDJB1/75I2lRrdAgMBAAEwDQYJ

KoZIhvcNAQEEBQADgYEA0NlER5vcR25nAqqPltU5ZMQxEOSa9eb+dMTQ9b5x0Yu4

PThjsc9LCDlw+ZfstkPBwRMITCYylpoMZWZcPCO2q9ZH2wHm3Qpzhh19wG6SUliw

AF4myMWzNqwcWOcTr/ao7LZ3Mn10EIbNjOzo/8OZgNWw42bCLRzN6B2xFz3Usqk=

-----END CERTIFICATE-----
 
-----BEGIN PRIVATE KEY-----

MIICdwIBADANBgkqhkiG9w0BAQEFAASCAmEwggJdAgEAAoGBAOumdnHv4IeLAq2P

bUjSNbtsP2EnQ5pBLia97c1RsGmJFuyF6mskLmw7NEwShZDnsP78BEOrfFQc0P33

XZboiM7OMW8hSGpM+fsiKr+OyfTNWzbDnl22Ott0urpkOc/akagZBSzdJtJOXnij

Kxuf58UQZHow6UM/wMi0GbItKArDAgMBAAECgYEAk8AMdcXETtfu9ul9yPHcNMZb

OswGi/ogOLRPHLQCWzlUQTp5z3GhFcVNNgFK858Bj+5tsgwcaRSkSQhHCu6Dj4sf

AMp8hGoFc027I5cS4/ZzIVnUXz1uXinPOaWKO54beiF7MbVww/hlf8Mce9imvUva

WLsz0kYlp8tH8/FVKnkCQQD4Du29UxSHaAzNRRL6Lm/nxZABHFK3/8Jgo+vNhZAs

K3Gq6+5DjlLWgL4DGrSWphWMB1Bfd2+YmA4ogWpsDV3NAkEA8zHWk9QMYmTypEcs

PViYbqVIrgATsQYjfOH8TnLNA7z9ZnVhQpoqPvuNJ4ROm3EPNqomplw3yG2aP70x

LLv6zwJAa8RQlMfbS1hw91zi+b3i8BZskY70gOukTsfoUcmM8SOOpmsJgF/8rSQR

aNfZTPmqssMar977pJeqzv4qdfb4oQJAZ9Epwfeuxb5EWt7LQvD0OZ+zdBwyS8rM

EX7DX5XgcS0Xm8qWF4GKcVKfgnQXvoG4NeTTFQefBJ/NTlJskKU6vwJBAJeXxiun

kOK+rxqaziKY6rlgkiIJRn2fO5E6StSp2z4YMKcwg3SZD5n7qv9CAmx9IDKM4Tqs

94nPzsOHE18ZY+c=

-----END PRIVATE KEY-----


 
Lines that not are between the BEGIN/END lines may be comments, as the 'Client certificate for...' line.

For the Generic RI and the Enhanced AWT RI, the file is stored in ${user.home}/ib6/ssl/clientcerts.crt. The default for user.home on Unix systems is the user's ordinary home directory. On Windows, it depends on the JVM. It is either the C:\ drive or some user directory. You can override this by setting user.home to a different value. If the ib6/ssl directory does not exist, it is created when the RI starts.

The Swing RI specifies its own unique directory structure to store the client certificate.