Installing the Keyfactor EJBCA Server

This section provide some guidance as to how to configure the Keyfactor EJBCA server, but you also need to refer to the Keyfactor documentation for more details.

Prerequisites

• The Keyfactor EJBCA server must be up and running.

Note: The Keyfactor EJBCA server is installed from an image provided by Keyfactor.

• Some basic configuration must already be performed:

  • Network configuration

  • Database selection

  • HSM selection

• The following REST API endpoints must be enabled:

  • REST Certificate Management (v1 and v2)

  • REST Crypto Token Management

  • REST End Entity Management (v1 and v2)

  • REST Configdump

Creating the Crypto Token

Create a crypto token with the following requirements:

• Check the Auto-activation option.

• Create a signKey set to RSA-2048 for signing (as recommended).

• Create an encKey (and not "otherKey") set to RSA-2048 for encryption.

• Download the key certificates, and keep them.

Creating the CA in EJBCA

Create the certificate authority (CA) using the crypto token created previously (see Creating the Crypto Token ), with the following requirements:

• Use signKey and encKey where expected.

• Uncheck the Enforce unique DN option (in the Directives section).

If you want to use Windows Logon, you need to perform the following additional steps:

• In the CA Certificate Data section, select the ROOTCA_CRL certificate profile.

• In the CRL Specific Data section, generate default values for the three CRL entries (Default CRL Distribution Point, Default CRL Issuer and Default Freshest CRL Distribution Point).

  Note: There is no need to generate the OCSP service Default URI.

• In the CA Certificate Data section, select the SUBCA_CRL certificate profile signed by the root CA, and generate the default values for the CRL entries in the CRL Specific Data section (as specified previously).

  Note: You can create one or more intermediate CAs using the SUBCA_CRL certificate profile.

• You may also want to create a dedicated root CA for the management of EJBCA itself (SSL and operator certificates).

Enrolling the CMS Agent on the EJBCA Server

• Using the management CA created above, enroll a specific agent for CMS.

• Either use EMPTY / ENDUSER (default values), or a specific End Entity and Certificate profile (respectively, Certificate Type and Certificate Subtype in the RA web screen).

• Key-pair generation must be set to By the CA.

• Download the PKCS#12 for the new End Entity.

  Important:
  Keep this .p12 file and its password; it will be used during CMS configuration (specifically, for the PKCS#12 file containing the client certificate and key and Password for the PKCS#12 file containing the client certificate and key fields in step 12 of Configuring the Keyfactor EJBCA Certificate Authority).

• Copy the certificate serial number, and use it to register the user as a Super Administrator.

Creating the Publisher (Optional)

For Windows Logon support, the certificate authorities (CAs) need to publish a certificate revocation list (CRL). You must configure a specific machine to host the URLs for these CRLs. This can be done on the same machine if you use a Docker image, or on another machine if you use a hardened Keyfactor appliance. Keep in mind that this choice affects the URLs of the CRLs, and you must adapt the instructions accordingly.

On the machine hosting the URLs for the CRLs, perform the following commands:

mkdir -p "$HOME/.ssh"
chmod 700 "$HOME/.ssh"
cd "$HOME/.ssh"
ssh-keygen -i -m PKCS8 -f ssh.pem > ssh.pub
touch "$HOME/.ssh/authorized_keys"
chmod 600 "$HOME/.ssh/authorized_keys"
grep -qxF "$(cat ssh.pub)" "$HOME/.ssh/authorized_keys" || cat ssh.pub >> "$HOME/.ssh/authorized_keys"
ssh-keygen -l -f "$HOME/.ssh/authorized_keys"

The machine that serves the CRL files must have:

• a web server (static file support is enough) with at least two file directories: one for the CRLs and one for the certificates,

• an SFTP server (to push the CRL files).

On the EJBCA side, a publisher must be configured for the root and intermediate CAs, but not necessarily for the management CA. In the CA Functions section of the EJBCA console, add a publisher for each CA and update its corresponding configuration. Each publisher should be configured as follows:

• CA to Sign Published Certificate/CRL: the CA that will publish the CRL (root and intermediate CAs, accordingly)

• Username for SSH Connection: depends on your CRL machine configuration

• Port for SSH Connection: depends on your CRL machine configuration

• Destination URL for CRLs: depends on your CRL machine configuration, for example 172.18.0.1:/var/www/html/crl

• Destination URL for Certificates: depends on your CRL machine configuration, for example 172.18.0.1:/var/www/html/certs

• CRL file name pattern: depends on your CRL machine configuration, for example ${CA_NAME}.crl

• Use SFTP: option checked

• Cryptotoken and Keypair for authentication: the encryption key of the CA’s Crypto Token

• SSH Known hosts: generated using ssh tools on the CRL serving machine. For example, use the output of the command: ssh-keyscan -p 22 172.17.0.1

• SSH Public Key used for authentication: the public key generated by ssh-keygen above

Enabling Key Recovery

• In the System Configration section of the EJBCA console, enable key recovery (in the Basic Configuration section) by selecting the Activate option.

• Do Not check the Force Local Key Generation option.

End Entity and Certificate Profiles

This section highlights the basic procedure to integrate an EJBCA with CMS. Specific implementations using PIV and CIV templates are provided below in PIV/CIV Support.

Certificate Profiles

Create the certificate profiles first.

End Entity Profiles

Create dedicated End Entity profiles, according to your needs:

• One for the device-generated certificates (authentication, signature)
  

• One for the CA-generated recoverable certificates (encryption)

Configure the following properties:

Subject DN Attributes

The structure of the Subject DN must be completely described, down to the maximum number of each attribute: CN, DC, OU, etc.

Main Certificate Data

• Select the Certificate profiles that can be issued using the End Entity profile. You may group several certificate profiles in one End Entity profile, provided that they all share the same token configuration (either User Generated or P12 file).

Other Data

• Set the Default value for the Number of allowed requests to "1".

PIV/CIV Support

NACI

Add a Custom Certificate Extension: NACI

Its Object Identifier (OID) is: 2.16.840.1.101.3.6.9.1.

Extended Key Usages

Check that the OID 2.16.840.1.101.3.6.8 already exists: PIV Card Authentication Configuration.

PIV_AUTHENTICATION Certificate Profile

Clone the ENDUSER certificate profile, rename it PIV_AUTHENTICATION, and set the following properties:

Permissions

• Allow Validity Override

• Allow Extension Override: 2.16.840.1.101.3.6.9.1

• Allow Subject DN Override by CSR

• Use Certificate Storage

• Store Certificate Data

X.509v3 Extensions

• Key Usage: Digital Signature

• Extended Key Usage: Any Purpose, Client Authentication, MS Smart Card Logon

• Certificate Policies: 2.16.840.1.101.3.2.1.3.13

Important:
In order for users to be able to authenticate to the CMS Self-Service portal, the Extended Key Usage must be set to use MS Smart Card Logon.

CARD_AUTHENTICATION Certificate Profile

Clone the ENDUSER certificate profile, rename it CARD_AUTHENTICATION, and set the following properties:

Permissions

• Allow Validity Override

• Allow Extension Override: 2.16.840.1.101.3.6.9.1

• Allow Subject DN Override by CSR

• Use Certificate Storage

• Store Certificate Data

X.509v3 Extensions

• Key Usage: Digital Signature

• Extended Key Usage: PIV Card Authentication

• Certificate Policies: 2.16.840.1.101.3.2.1.3.17

PIV_DIGITAL_SIGNATURE Certificate Profile

Clone the ENDUSER certificate profile, rename it PIV_DIGITAL_SIGNATURE, and set the following properties:

Permissions

• Allow Validity Override

• Allow Subject DN Override by CSR

• Use Certificate Storage

• Store Certificate Data

X.509v3 Extensions

• Key Usage: Digital Signature, Non-repudiation

• Extended Key Usage: Client Authentication, Email Protection

• Certificate Policies: 2.16.840.1.101.3.2.1.3.6

PIV_ENCRYPTION Certificate Profile

Clone the ENDUSER certificate profile, rename it PIV_ENCRYPTION, and set the following properties:

Available Key Algorithms

Only allow RSA keys that are 2048 bits or higher.

Permissions

• Allow Validity Override

• Allow Subject DN Override by CSR

• Use Certificate Storage

• Store Certificate Data

X.509v3 Extensions

• Key Usage: Key encipherment, Key agreement

• Extended Key Usage: Email Protection

• Certificate Policies: 2.16.840.1.101.3.2.1.3.6

PIV End Entity Profile for Device-Generated Keys

Create an End Entity profile name "PIV" and configure the following properties:

Subject DN Attributes

The structure of the Subject DN must be completely described, down to the maximum number of each attribute: CN, DC, OU, etc.

Main Certificate Data

• Select the Certificate Profiles that can be issued using the End Entity profile. You may group several certificate profiles in one End Entity profile, provided that they all share the same token configuration. Hence for this specific profile, you can group PIV_AUTHENTICATION, PIV_DIGITAL_SIGNATURE, and CARD_AUTHENTICATION.

• Select PIV_AUTHENTICATION as the Default Certificate Profile.

• The Default Token and the Available Tokens must be set to User Generated.

Other Data

• Set the Default value for the Number of allowed requests to "1".

• Leave all other options unchecked.

PIV End Entity Profile for Escrowed Keys

Create an End Entity profile named "PIV_ENCRYPTION" and configure the following properties:

Subject DN Attributes

The structure of the Subject DN must be completely described, down to the maximum number of each attribute: CN, DC, OU, etc.

Main Certificate Data

• Select the PIV_ENCRYPTION Certificate Profile that can be issued using the End Entity profile.

• Select PIV_ENCRYPTION as the Default Certificate Profile.

• The Default Token and the Available Tokens must be set to P12 file.

Other Data

• Set the Default value for the Number of allowed requests to "1".

• Next to Key Recoverable, check Use, check Default, and check Reuse old certificate.

CIV Support

• For CIV, create the following Certificate Profiles: CIV_AUTHENTICATION, CIV_DIGITAL_SIGNATURE, and CIV_ENCRYPTION.

• Start from the PIV equivalents, and remove:

  • NACI Support from CIV_AUTHENTICATION (2.16.840.1.101.3.6.9.1 Extension Override)

  • PIV-specific OIDs in Certificate Policies

• Create similar CIV and CIV_ENCRYPTION End Entity profiles as well.

Support of Object-Sid Attribute for Authentication Certificates

To enable support for authentication using an Object-Sid attribute, you need to create a custom certificate extension and add it to your authentication certificates.

Creating an Object-Sid Extension

Add a Custom Certificate Extension: objectSid

Its Object Identifier (OID) is: 1.3.6.1.4.1.311.25.2.

Set the Extension Class to Basic Certificate Extension, check the Required option and set the Properties.

Modifying the Certificate Profiles

In the Permissions section, check the Allow Extension Override option and add the OID for the objectSid extension (2.5.29.17) to the Overridable Extension OID list. (This is the Subject Alternative Name extension OID).

In the Other Extensions section, add the objectSid extension to the Used Custom Certificate Extensions list.

Modifying the End-Entity Profile

In the Other Certificate Data section, check the Use option next to Custom certificate extension data.

Windows Logon Support

In order to use Windows Logon, you must create a CA that has a root certificate with certificate revocation list (CRL) support; for details, see Creating the CA in EJBCA.

All the certificate profiles must also have CRL support:

• For each Certificate Profile used by CMS, click Edit.

• In the Validation data section, select the Use… option for both CRL Distribution Points and Use CA defined CRL Distribution Point.

On the Active Directory (AD):

• make sure that the CRL is accessible,

  Important:
  The EJBCA machine must be declared in the domain name system (DNS).

• the root CA must be trusted by the machine,

• the root CA must be available in the Enterprise PKI. To do so, execute the following command on the AD:

  Copy

  certutil -enterprise -addstore NTAuth <root_ca.cer>

• the intermediate CAs must be in the machine's Intermediate Certificate Authoritiesstore.