Introduction
This article will describe how you can configure and use an EJBCA to issue a certificate to a credential managed by vSEC:CMS.
In this article we will show you:
- How to setup a connection to EJBCA;
- Configure a template to issue a certificate to a managed credential;
- Issue a credential;
- Renew the certificate using the vSEC self service client.
It will be required that at minimum you have already successfully completed the configuration steps described in the article Setup Evaluation Version of vSEC:CMS. The instructions in this document are applicable regardless of whether you are running the evaluation version or a production version.
It will be required to have an EJBCA available and it is expected that the reader of this article has knowledge in using/configuring EJBCA.
Configure EJBCA Connection
From Options - Connections - Certificate Authorities click Add. Enter a template name and from the drop-down list select EJBCA. In the URL enter the connection URL to your CA.
It is required to have a client certificate that is needed to authenticate to the CA. You should have one already installed in the local user certificate store. It is important that you install this to the Windows user certificate store for the service account that vSEC:CMS service is running under.
The client certificate needs to be fully trusted in the local certificate store.
Select the appropriate options from CA and End Entity Profile. Click the Templates button and Show all and Update to see all available certificate templates. Click Ok to close.
Click the Request fields button. Depending on how your certificate templates are configured and need to be used you may have different requirements here. In this example we will use several fields that we want vSEC:CMS to provide the data for. Click the Fields button. From the left window we will add parameters from the Available list to the right Selected column and click Ok.
It will be necessary to assign values/variables that will be used to populate values to these fields and used when generating the certificate request (CSR). For example, to add/edit what needs to be configured click the whitespace (as circled below) to open a configuration dialog for the field you want to configure.
For example, we will use a variable ${CommonName} that is mapped to AD attribute cn for the user that we are issuing the credential to (see the article Using Variables for details on how to use variables in vSEC:CMS). You can also add static values using the Use free text option. Click Ok to save the configuration.
It is recommended to enable Proxy through server checkbox which will mean that all client certificate requests will be proxied through the server.
Configure Credential Template
The next step is to configure an actual credential template where the certificate that is to be issued to the credential token will be set.
1. From Templates - Credential Templates click the Add button.
Click the Edit link beside General. Enter a template name. Presuming that you are using one of the minidriver credentials that is supported by vSEC:CMS select Minidriver (Generic minidriver credential) for Credential type. Leave all other settings as default and click Ok to close and save.
2. Click the Edit link beside Issue Credential. In the User ID Options section enable Assign user ID and select the AD connection configured earlier in the drop-down list. In the Enroll Certificate Options section enable Enroll certificate(s) checkbox and click the Add button.Select the EJBCA template from the Certificate authority drop-down list and select which CA certificate template you want to use and click Ok. Leave all other settings as is and scroll down to the bottom of the dialog and click Ok to save and close.
3. Click Ok to save and close the template configuration dialog.
Issue Credential
From the Lifecycle page attach a blank credential to your host. If it is a credential that is supported by vSEC:CMS you should see the reader and the credential similar to below.
Depending on the credential that you are testing with it will be necessary to have the appropriate credential drivers installed on your host. Please check with the credential provider that you have the correct credential drivers installed.
Click the Issued oval and select the template from Select credential template drop-down list and click Execute.
You will be prompted to enter your operator token passcode before the issuance will begin. Then you will be prompted to select the user from AD that the credential will be issued to. Select the user and at the end of the process you will get a short summary dialog of what operations were performed.
The credential will now show as Issued. The credential PIN by default will be blocked. You will need to set a PIN before you can use the credential. Click the Active oval followed by the Execute button. You will be prompted to authenticate again and then set a PIN that meets the policy supported on the credential.
Once you complete this then you can use the credential certificate for whatever use case it is intended.
Certificate Template Configuration
It is possible to change/configure the key size and key specification for the certificate(s) that will be managed through vSEC:CMS. On the server where vSEC:CMS is installed a configuration file named CaPluginEjbCA.cfg is installed into the plugins folder on the root of the installation folder (typically here: C:\Program Files\Versasec\vSEC_CMS S-Series\plugins). In order to configure the settings follow the instructions below.
Log into the vSEC:CMS Admin console on the server. Navigate to Options - Connections - Certificate Authorities and select your EJBCA connector. Click the Edit button and click the Templates button. Hold down the Ctrl key and click the Update button at the same time. You should see a popup staying that data has been copied to clipboard. Open Notepad (or a similar text editor) and paste the content into it. You will see something similar to below example. In this case we have 1 certificate available from the EJBCA that we will use to issue Windows logon certificate in our environment.
"Vsec Windows Logon";"2B6F55F0F2061E8671E59F91B121B028";"518522460";"Vsec Windows Logon: \n KeyLen=2048\n KeySpec=1"
The value highlighted in red above is the template ID. Make a note of the value in your environment as we will use this below.
Next open Notepad (or a similar text editor) as Administrator. Open the configuration file CaPluginEjbCA.cfg. Go to the start of the section templates and add a new section similar to below
<templates>
<518522460>
<DispDescription>Vsec Windows Logon: {LF} KeyLen={LEN}{LF} KeySpec={SPEC}</DispDescription>
<KeySpec>1</KeySpec>
<MinKeyLen>2048</MinKeyLen>
</518522460>
The value <518522460> will of course be different in your environment so change this as appropriate.
In the <DispDescription> tag you can enter a descriptive name for the certificate template. Important to note that you should not remove the text : {LF} KeyLen={LEN}{LF} KeySpec={SPEC} when entering a description.
The <KeySpec> can be either 1 or 2. Enter value 1 for AT_KEYEXCHANGE and 2 for AT_SIGNATURE.
The <MinKeyLen> is the key size that will be used when generating the certificate. This depends on what is supported on the credential credential.
Save the configuration file changes and then navigate back to Options - Connections - Certificate Authorities and select your EJBCA connector. Click the Edit button and click the Templates button. Click the Update button to update the changes made in the configuration file. You can now use the certificate template in Templates - Credential Templates in the Issue Credential - Enroll Certificate Options section.
Configure Support for Elliptic Curve Cryptography (ECC)
If is possible to configure support for the issuance of ECC certificates from vSEC:CMS. This can be done through the configuration file CaPluginEjbCA.cfg (see previous section).
<1757527597>
<DispDescription>Vsec Template for ECC: {LF} KeyLen={LEN}{LF} KeySpec={SPEC}</DispDescription>
<KeySpec>6</KeySpec>
<MinKeyLen>0</MinKeyLen>
</1757527597>
Important to note that the <KeySpec> needs to be set to 6 and the <MinKeyLen> needs to be set to 0 (zero).