BWS Client Certificate Installation
The BioID Web Service utilizes client certificates for access control. Those certificates are similar to certificates used for securing web sites like online banks or online shops. But there are also certain differences in installation and usage of those certificates.
What are Client Certificates
Client certificates are not stored on the server but on the client computer, i.e. the system accessing the BioID Web Service. If the client submits a SOAP call to the web service API it also sends the certificate to the BWS instance. The certificate is checked for validity then and if it is eligible to connect to this specific instance of the BWS. Since the certificate handling is widely supported in common development frameworks and programming language libraries it is very easy to implement access control relying on certificates. An access control system setup with a user database and passwords or API keys would need much more effort and be prone to errors.
Getting a BWS Client Certificate
If you request for the API access to the BioID Web Service we'll issue you a certificate and a private key for accessing the BWS instance assigned to you. In the following we describe how to install those certificates.
The Windows Certificate Store
Let's start with Microsoft Windows. On Windows a certificate store is used for handling the certificates. It is a common layer for all certificate storage options used by a Windows cryptographic service provider CSP) so you don't have to care where the certificate is stored physically.
As an ordinary user you can only install the certificate in the current user certificate store which is ok for desktop applications and developing software. On production systems the local computer store or a service account would be used instead. For example if you write an application running on the Internet Information Server (IIS) the certificate should be installed in the local computer store since IIS accesses his store for using certificates. You need administrative rights on the system you intend to install the certificate in the local computer store!
Installing the Certificate
You'll receive the certificate along with the private key as a PFX file from us. We also issue you a pass phrase to install the certificate and the private key since both are password protected in the PFX file. This is a Personal Information Exchange format file (PKCS#12) which is used to securely exchange the certificate and the private key.
The simplest way to install the certifificate and key just to double-click the PFX file in the Windows Explorer and use the Certificate Import Wizard. By default you just have to follow the instructions of the wizard, provide the pass phrase and the certificate will be installed in your Current User certificate store.
In Microsoft Windows 8 you can select if you want to install the certificate in the Local Computer certificate store instead. On other systems the best method is to use the Certificate Manager of the Microsoft Management Console. A good source for more information about the Certificate Manager is the TechNet article How to Use the Certificate Console.
Checking the Certificate with Microsoft Management Console
Just run certmgr.msc to open the certificate manager in the Microsoft Management Console. In the left column the certificate store of the current user is shown. Navigate to Personal and then to Certificates to display all certificates installed for the current Windows user in the right column of the management console.
The certificates installed by the Administrator for the local computer can be displayed by using the certificate manager for the local machine with the command certlm.msc.
Checking the Certificate with Microsoft PowerShell
Or start a PowerShell and use the command get-childitem Cert:\CurrentUser\My to display the certificates installed in the current user store as two columns.
The left column shows the Thumbprint (or Fingerprint) of each certificate. This is an unique identifier for a certificate. Of course the thumbprint on your system will differ to the example above. In the column on the right there is the subject shown for each certificate.
The subject of BWS client certificates have always a canonical name (CN) starting with the term BWS Client. By using the thumbprint of the BWS certificate with the following Microsoft PowerShell command you can show further information about a specific certificate in the certificate store of the current user:
The field NotAfter is of special interest here. It's the date your access to the BWS will be denied even if you provide the certificate with the API call since it is expired.
To display the certificates installed for the local computer modify the path in the Windows PowerShell Cert:\CurrentUser\My command to
Determine Certificate Usage
X.509 client certificates differ from other certificate types like SSL/TLS server certificates. To determine if a certificate us used for client authentication you have to check the certificate extension Enhanced Key Usage for the appropriate extension.
In the certificate management in the Microsoft Management Console select the certificate you want to examine and open it (double-click or select the Open menu item with the right mouse button). On the tab details select Enhanced Key Usage and verify that the property Client Authentication (22.214.171.124.126.96.36.199.2) is shown. An other way to display all certificates used for Client Authentication is to change the View Options in the certificates console to Certificate purpose.
With Windows PowerShell you can use the following commands to display the Enhanced Key Usage property:
There's an article in the MSDN Magazine Support Certificates In Your Applications With The .NET Framework 2.0 going more into detail how to access certificates in .NET.
In the next blog post we will explain how the certificate is used in the Java keystore.