BWS Client Certificates and Java

event_note January 15, 2013

In the previous blog post we described how the client certificates are installed in the Microsoft Windows certificate store.

If you use certificates with Java the certificate and private key will be fetched from the Java keystore. The keystore is a database for storing certificates and password protected private keys. Thus the keystore is protected by a password itself. The utility keytool can be used to create and manage such a keystore database. Also it is possible to use more than one keystore database so you could create an keystore  exclusively for use with the BioID Web Service.

Beginning with the keytool bundled with Java SE 6 the certificate and private key provided by BioID can be imported in an existing keystore. Also the PFX file you receive from us containing the certificate and private key file can be used as a keystore itself.

The Java Keystore

The Java keystore could be stored on a SmartCard or a HSM but normally it is just a file in the local filesystem. The keytool can manage file-based keystores and we're only discussing such keystores in this blog post.

The default location of the keystore searched by the the keytool is a hidden file in the users home directory, e.g./home/bwsuser/.keystorebut it can be created at any suitable place in the filesystem. A keystore file is created with the keytool by issuing a certificate request or importing another keystore, e.g. the PFX file with the BioID Web Service client certificate.

Also there are two types of keystore: the jks which is an proprietary type provided by Oracle or pkcs12 which is a PKCS#12 file. The default type is defined in the fileJAVA_HOME/jre/lib/security/

but there's no need to change it since the default can be overridden for each keystore with a configuration setting.

Listing the Content of a Keystore

By receiving the BWS client certificate you have already a keystore! You can list the content of the keystore with following keytool command:

keytool -list -v -storetype pkcs12 -keystore <NAME>.pfx

<NAME> has to be replaced with the actual filename of course. All certificates in the PFX file will be listed after providing the password& for the PFX file. The interesting part is in the beginning of the output of the above command:

 Alias name: bws client <NAME>

is the short alias for the certificate which can be used to identify the appropriate certificate for some cryptographic operation if the keystore contains more than one certificate.

Entry type: PrivateKeyEntry

shows that there is a private key present for the certificate. The part

ExtendedKeyUsages [



several lines down indicates that this certificate is used for client authentication.

If you're only intent to use the BioID Web Service client certificate for your application accessing the BioID Web Service you can copy the PFX file to the target directory and you're done with the certificate installation.

Importing the Certificate into the Keystore

If you already have a keystore setup for your application or intending to create a new keystore which could hold several certificates at once you can import the certificate and private key from the PFX file.

With the command

keytool -importkeystore -srckeystore /path/to/<NAME>.pfx -srcstoretype pkcs12 -destkeystore /path/to/keystore.jks

you either create a new keystore if there isn't already one present at/path/to/keystore.jksor you add the certificate and the private key to the present one. In the first case you'll be asked for the keystore password twice since you're setting a new password for the new keystore you create and then for the password of the PFX file you got from BioID. In the latter case you'll only asked once for password of the already existing destination keystore and then for the password of the source keystore which ist the password of the PFX file you received from BioID.

The keystore of default type jks is sufficient and you can omit the keystore type parameter in configuration files or as commandline parameter. However you can also create a keystore of type pkcs12 if you wish:;

keytool -importkeystore -srckeystore /path/to/<NAME>.pfx -srcstoretype pkcs12 -destkeystore /path/to/keystore.p12 -dststoretype pkcs12
Accessing the Certificate

If you plan to use a specific keystore in your Java applicatiuon following VMARGS or command line parameters have to be set: =${keystore_location}${keystore_password}

There's no need to specify the default keystore type which is usually jks. But if you use the PFX file as a keystore or a keystore of the type pkcs12 the parameter

has to be set also.

You can find further information about the keytool (Solaris/GNU Linux) (Microsoft Windows) and the Java Security Documentation in the documentation provided by Oracle.