Migrating from other CAs to EJBCA

This section includes information on CA migration and outlines a general migration procedure as well as case-specific information on migrating from different CAs to EJBCA.

CA Specific Migration Procedures

The following describe case-specific information on how to migrate from other CAs to EJBCA:

Migrating RSA Keon CA with nCipher: Describes how to migrate an RSA Keon CA using nCipher HSM to EJBCA and covers migrating the CA signing keys, importing the CAs to EJBCA and importing issued certificates to EJBCA. The result is a setup in EJBCA that can continue operation transparently.
Migrating Microsoft CA to EJBCA
Migrating OpenSSL CA to EJBCA

Generic Migration Procedure

The following outlines a generic process when migrating a CA to EJBCA. The actual migration may hit roadblocks such as non-supported certificate contents. Such issues are often found during a test migration, performed in order to solve similar issues prior to a final migration in production.

Migration Plan

This generic migration plan can be used as a base for migrating any CA to EJBCA.

Transferring data from another CA involves four different types of data:

HSM key material
CA certificates
End entity certificates
Revocation information

Migration Steps

A complete migration involves a number of steps. The following displays an overview of the steps involved, followed by more detailed information.

Configure Profiles

Before the certificates are imported, all the End Entity Profiles and Certificate Profiles used by the imported CAs and End Entities should be configured.

CA and Certificate Import

Once the key material is on the HSM and ready to be used, the CAs can be imported. Thus importing CA certificates and creating the CA objects in EJBCA, including Crypto Tokens. The import of CAs is performed using command line scripts, requiring information of the HSM slot, the HSM key labels, and the CA certificate.
When the CAs are created, the End Entity certificates and CRL can be imported. The import of End Entity certificates is performed using command line scripts, requiring information of the certificate, the issuing CA, and the 'username' to be used in EJBCA.

Import Process

Once everything is tested, the import process involves the following steps:

Get production data
Validate production data
Import

Configuration After Transfer

Validate the configuration of the following CA Configuration, Certificate Profiles, and End Entity Profiles fields after the transfer:

Set up CDP and AIA in Profiles.
Set CRL validity.
Set CA Certificate Profiles and configure CA settings.
Issue OCSP certificates.
Revoke old OCSP certificates.
Publish to OCSP.
Issue CRL.

Once the configuration has been verified, the EJBCA system can be run in production.

Migration Prerequisites

The following requirements should be checked in order to migrate successfully.

HSM Requirements

Labels on the private keys in the HSM must be used and should have a sane value. The following pattern format is recommended:

<caname>SignKey<date> for example, rootCAG3SignKey20160226 or highAssuranceCASignKey20160226

Do not use special or internalized characters in the labels.

Certificate Requirements

Certificates and CRLs Delivered

The following must be downloaded and made available:

All certificates in the whole CA chain (in PEM or DER format), including external CA certificates, i.e. CA certificates of the previous solution.
All issued certificates (in PEM or DER format).
CRLs, per CA. Only the latest CRL is required unless the revocation history of expired certificates are also needed.

Certificate Technical Requirements

The following are requirements on the certificate content:

Only standard subject DN attributes. RFC5280 and CABForum.
Only standard subject altNames. RFC5280 with the additional restrictions.
- No OtherName, except MS UPN, as these are usually custom
- No x400Address
- No ediPartyName
- No registeredID
Only standard certificate extensions. RFC5280.
The following special characters are not allowed to be used in the subject or issuer DN.
- \n (newline)
- \r (carriage return)
- \0 (null)
- ;
- !
- %
- ` (backtick)
- ?
- $
- ~

CRLs and Revocation Information

CRLs are used to transfer the revocation information.

Expired Certificates

Expired certificates can be imported and CRLs are used for revocation information. If only the latest CRL is downloaded, expired certificates may not be marked as revoked, even if they were., since expired certificates are not included in CRLs (following RFC5280).

Certificate Delivery Format

Certificates should be downloaded and made available in a directory layout, per CA, per certificate profile.

CAName/CertificateProfileName/uid.pem (…)

The uid can be any identifier used as 'username' in EJBCA if such information exists.

Audit Logs

Audit logs should be exported securely and stored off-line to be available in an audit.

Questions and Notes

Questions to consider prior to a migration:

Expected certificate volumes?
Consider exporting data from the old CA in order to test validity.
Will the migration be the first CAs created (except for the Management CA)? i.e. the CA import will be the “key ceremony”.
Will the systems be running in parallel? If so, it is necessary to do a kind of “delta migration”.
What will be used as 'username' in EJBCA?

A rather extensive testing of import can be performed without private keys (provided we have all the certs/CRLs). The CAs will all get imported as externals and the profile conformance of provided data can be validated.

Test Migration Process

The process should be tested thoroughly before migration.

Get test data.
Validate test data.
If using an HSM, make an HSM slot plan, which slot is used for which CA.
Import HSM slots according to the slot plan.
Generate new keys for a Management CA and install EJBCA. Now a Management CA is created.
Import CAs.
Import end entity certificates.
Import CRLs.

After testing, the system should be validated and test certificates issued.

Example HSM-based CA import procedure

When the keys of your previous CA (for example, an OpenSSL CA) are stored on an HSM, importing the CA requires additional steps. The following is an example procedure for importing a CA using existing keys stored on an HSM. The exact steps and commands depend on the HSM and PKCS#11 implementation.

Step 1 - Verify that EJBCA can read the keys on the HSM

There are many PKCS#11 attributes, and different implementations may handle them differently.
For a Pkcs11NgCryptoToken, the alias of the key is the string interpretation of its CKA_ID, and the CKA_ID on the public and private key must be the same. For a key not created in EJBCA, CKA_ID may be a hash of a public key or blank, and you may want to change it. The p11ng-cli tool is useful for viewing objects and their attributes and verifying that EJBCA can read them.

First, view the key object ID, label, and numeric identifier on the HSM.

The exact details differ between HSMs. For example, when using an nShield HSM, the slot label can be the name of an Operator Card Set (OCS), while for other HSMs it is commonly a label set by the crypto officer when initializing the slot. For example, with an EJBCA-generated key:

> p11ng-cli.sh listobjects --lib-file /opt/nfast/toolkits/pkcs11/libcknfast.so --slot-ref SLOT_LABEL --slot MyProtectiveOCS

Private Key Objects: [1120] 
Object 1120
   CKA_ID:    0x7369676e4b6579 "signKey"
   CKA_LABEL: 0x707269762d7369676e4b6579 "priv-signKey" 
Public Key Objects: [1121] 
Object 1121
   CKA_ID:    0x7369676e4b6579 "signKey"
   CKA_LABEL: 0x7075622d7369676e4b6579 "pub-signKey"

It is possible for the label to be the same for both the public and private key objects. This is fine.

Step 2 - Ensure the public and private keys have matching CKA_ID values

If the string after CKA_ID does not match the alias you want to use, is missing, or is not shown as a readable string, it must be corrected for EJBCA to be able to use the key. For a key that was not created in EJBCA, CKA_ID may, for example, be a hash of the public key rather than a readable string.

If you need to modify the key CKA_ID to match the desired alias, the open-source pkcs11-tool is an easy way to do this. Make sure that the private and public key objects have the same CKA_ID.

For example, the following commands change the CKA_ID of the signKey key pair from the previous example to signKeyy. The hexadecimal value 79 represents the character y, so the new CKA_ID is the hexadecimal representation of signKeyy. When passing the ID to pkcs11-tool, omit the initial 0x.

> pkcs11-tool --module /opt/nfast/toolkits/pkcs11/libcknfast.so --label pub-signKey --type pubkey --set-id 7369676e4b657979
> pkcs11-tool --module /opt/nfast/toolkits/pkcs11/libcknfast.so --label priv-signKey --type privkey --set-id 7369676e4b657979

If you want the CKA_ID to match a CKA_LABEL, you can use the CKA_LABEL value shown by p11ng-cli and convert the label string to hexadecimal. For example, 7075622d7369676e4b6579 represents pub-signKey.

Step 3 - Verify that the keys are readable by EJBCA

Use p11ng-cli to verify that EJBCA can read the keys as a usable key pair.

> p11ng-cli.sh listkeypairs --lib-file /opt/nfast/toolkits/pkcs11/libcknfast.so --slot-ref SLOT_LABEL --slot MyProtectiveOCS
Found 8 usable key pairs on the token.
Reading public keys (if private key exists)...
Reading public keys took 254 ms.
Total time (excluding initialization): 309 ms.
Alias: signKeyy
    Key algorithm: ML-DSA-87
    Key specification: ML-DSA-87
    Key ID (SKID): 3dfe6f320ccb366ef14aaac023c51eda8c0aee2a
    Key Usage: null
...

In this example, signKeyy is listed as a usable key pair, which means that EJBCA can read and use the key pair.

Step 4 - Create the EJBCA crypto token

Create a crypto token in EJBCA for the target HSM using ejbca.sh cryptotoken create. The command and required parameters vary depending on the HSM and its implementation. Use --help to list the available parameters.

For example:

bin/ejbca.sh cryptotoken create --autoactivate false --token MytokenName --type Pkcs11NgCryptoToken --lib /opt/nfast/toolkits/pkcs11/libcknfast.so --slotlabeltype SLOT_LABEL --slot MyProtectiveOCS

Step 5 - Verify the crypto token

Verify that the crypto token was created with the expected settings by running:

> ejbca.sh cryptotoken list

Example output:

"Accelerator_test" (73980125) Pkcs11NgCryptoToken, active, auto,
library=/opt/nfast/toolkits/pkcs11/libcknfast.so, Slot Label=loadshared
accelerator, Slot Label Type=Slot Label, attributes= 

"OCS_test" (653142051) Pkcs11NgCryptoToken, active, auto,
library=/opt/nfast/toolkits/pkcs11/libcknfast.so, Slot
Label=MyProtectiveOCS, Slot Label Type=Slot Label, attributes=

In this example, OCS_test is the crypto token configured to use the target OCS.

Step 6 - Create the CA properties file

When importing a CA, you need a properties file that specifies the key aliases the CA will use.

For example:

> cat > ca.properties
defaultKey defaultKey
certSignKey signKeyy
crlSignKey signKeyy
testKey testKey

Step 7 - Verify that the CA keys are available

Use cryptotoken listkeys to verify that EJBCA can see the key that you intend to use for the CA.

> ejbca.sh cryptotoken listkeys "OCS_test"
CryptoToken id:   73980125
ALIAS   ALGORITHM SPECIFICATION SUBJECTKEYID
signKeyy ML-DSA-87 ML-DSA-87 3dfe6f320ccb366ef14aaac023c51eda8c0aee2a

In this example, the signKeyy key is available on the OCS_test crypto token and can be referenced by the CA properties file.

Step 8 - Import the CA

Import the CA using its certificate, the key aliases defined in the properties file, the crypto token name, and the properties file.

ejbca.sh ca importca ImportedTestCA --hard --tokenname "OCS_test" --ctpassword <crypto token password> --prop ca.properties --cert ca_certificate.pem

After the import completes successfully, the CA is available in EJBCA. Review the CA configuration and update settings such as CRL publishing and certificate issuance before using the CA.