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/.keystore but 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 file JAVA_HOME/jre/lib/security/java.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
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.jks or 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:
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.