Key Import

Key Import allows you to migrate keys from external Certificate Authorities (CAs) into EJBCA, regardless of whether the CA that issued the certificate exists in the EJBCA system.

Use Case Example

A common use case involves customers migrating user encryption key history from their CA environment to EJBCA while not importing the CA, which may be decommissioned. This requires the ability to import the user key history, select the CA to use to issue the migrated key and wrap this key in the database. This functionality is provided through EJBCA Certificate Management REST API keyimport endpoint.

The endpoint requires the issuer_dn parameter in the URI, representing the Subject DN of the CA that will manage the imported keys.

Example Request Body

The request body must be a JSON object containing key import details. The following displays an example request body:

{
   "certificate_profile_name":"ENDUSER",
   "end_entity_profile_name":"EMPTY",
   "keystores":[
      {
         "username":"foo"
         "base64_keystore":"MIACAQMwgAYJKoZIhvcNAQcBo...v51tueSN+rcyybMaDJAgMBkAAAAA==",
         "password":"foo123"
      },
      {
         "username":"foo"
         "base64_keystore":"MIBCAQMwgAYJKoZIhvcNAQcBo...v51tueSN+rcyybMaDJAgMBkAAAAB==",
         "password":"foo123"
      }
   ]
}

The format of the keys exported from the Non EJBCA CAs are P12. The requirement is that the certificates in the P12 format must be included in the request body. Otherwise, there is no way to tie key pair history to a user/end entity. Key algorithms used by the certificate which are going to be imported will be checked against the associated certificate profile’s available key algorithms for the sake of compatibility.

Key Import Workflow

The following outlines a high level key import workflow:

• The endpoint iterates through each keystore entry in the request body.

• For each entry:

  • It creates a new end entity given the input username or it relies on the existing end entity if one already exists.

  • If a keystore has multiple key and certificate pairs, for each pair:

    • It will write the “old” certificate to CertificateData table with the username and profile references from the input and populates additional fields such as subjectDN with information from the certificate itself. (This certificate is not issued by a CA known to EJBCA)

    • It wraps the keys to be imported with the new CA’s keyEncryptKey

    • It writes it to the KeyRecoveryData table in the database (with reference to the crypto token, the new issuer, and the old certificate).

  • If any imports from a keystore fail, all of the imports from that keystore have to fail. No partial importing of a P12.

• Populate response body.

Import and Verify Keys

To test the REST endpoint and verify the key import functionality, follow the steps outlined below.

Step 1 - Import the keys

First, import the keys from the third-party CA environment into the EJBCA ecosystem.

1. Use the v2/certificate/{issuer_dn}/keyimport endpoint to import the keys. Every key should be imported with a corresponding certificate.
   For testing purposes, you can use the attached sample JSON file input.json, containing sample test P12s, one with one key and another with three keys.

2. Optionally, verify that the database contains all expected keys, certificates, and end entities expected. If you used the sample input file, two end entities, four keys, and four certificates, should be correctly imported.

For testing purposes, you can use the attached sample JSON file input.json, containing sample test P12s, one with one key and another with three keys. In the case of input.json, after importing, we expect 2 end entities, 4 keys and 4 certificates.

Step 2 - Verify the imported data

To verify that the keys and their corresponding data are successfully imported into the EJBCA environment, follow these steps:

1. Navigate to one of the imported certificates in the RA UI (Search > Certificates > View (for a specific certificate)).

2. Verify that the CA name and issuer DN reference the new CA, not the original one.

Step 3 - Recover the imported keys

The last step is to recover the imported keys to verify the recovery process:

1. Click Recover Key to mark the key under the certificate for recovery, enter the expected credentials, and confirm the request.

2. Go to to Enroll > Use Username and complete the recovery process. Open the new certificate to verify.

Important notes

• The End Entity Profile must include all of the Subject DN Attribute fields of the imported certificates in order for the import of those keys and certificates to be successful. For example, the EMPTY profile cannot be used to import the example keystores from the sample JSON file input.json, since the example certificates have two Common Names. If the imported certificate contains two Common Names, the selected End Entity Profile must also support two Common Names.

• P12 files must be Base64-encoded before being included in the request.

• If Force Local Key Generation is enabled on the EJBCA RA machine, then the key import process will fail, cause it is only valid when keys are handled on the CA side.

• Currently the approval is not supported with Key Import, so if it is been set as required for end entity creation/edition, the key import process will fail.

• If the CA which is going to take control of the imported P12s, is not available in the end entities associated certificate profile or end entity profile, then the import process will fail.

• If the end entity profile associated with the end entities, does not have certificate profile available, then the process will fail.

• If the CA associated with the imported P12s is not of type X509 then the import process will fail.

For more general information on key recovery in EJBCA, see Key Recovery.