Generate new Certificate

The following is an example of a sequence of commands used to generate a new certificate for a user using the same key pair, if the key and certificate was generated key recoverable as described above:

• Mark the generated certificate for keyrecovery:

• Set clear text password for Batch session to use:

• Reissue the certificate:

You can also generate a new certificate using the RA GUI in your browser.

Using the RA UI:

• RA UI → Search > Certificates → View (for a specific certificate).

• RA UI → Recover Key → Enter new enrollment code → Confirm request.

• RA UI → Enroll → Use Username → Enter username and password → Fetch P12 / JKS / PEM.

• Optionally, Enroll → Request ID can be used if the operation requires approval.

Using the WS API:

• keyRecover

• editUser

• pkcs12Req

or, combining it into a single command:

• keyRecoveryEnroll

Auto-generated Passwords

You can use auto-generated passwords for end entities, so when enrolling for a new certificate/keystore, and recovering an old keystore, the user is sent an auto-generated password through email.

To enable auto-generated passwords:

1. Enable the Auto-generated option under Edit End Entity Profile → Password (or Enrollment Code) → Auto-generated.

2. Add a notification for STATUSNEW and STATUSKEYRECOVERY under Edit End Entity Profile → Notifications → Notification Events.

Note that you must ensure that e-mail notifications work in order to use the auto-generated passwords feature.

Local Key Generation

In systems with distributed RA's, using key recovery, it might be desired to store the key pairs used for recovery in a database belonging to another instance than the CA. With local key generation, the keys are stored in the RA's database and are encrypted with a crypto token (e.g. from a HSM) in the RA, so the key material is inaccessible to the operators of the CA (provided that they are restricted from logging in to the RA). The certificates and end-entities, however, remain stored in the CA and can be managed (e.g. revoked) from there.

In order to activate local key generation, the steps below are to be followed (this is performed on the RA which should keep the key recovery data):

• Under System Configuration, set Enable Key Recovery and Force Local Key Generation.

• Select the crypto token to be used for encryption of the key pairs (key recovery data).

• Select the desired key for encryption.

Recovery data entries belonging to certificates enrolled before local key generation was enabled will remain in their initial database. Enabling local key generation doesn't change the way key recovery is performed by an administrator, nor the work flow of approvals, or access rules required. Keep in mind that the role handling the peer connector requires (at least) access to the same set of rules as the administrator of the external RA (for example to perform a key recovery). Since this feature intends to keep key material inaccessible from the CA by generating and storing the key pair on the local instance, it is not possible to use local key generation in combination with auto generated end entity passwords (generated by the CA) .

Technical Details

The operation bin/ejbca.sh ra keyrecovernewest, the recover key option in the CA UI, and the keyRecoverNewest in the WS API all marks the user/certificate for key recovery. This means that the next time you make a call to generate a keystore (p12/jks/pem) for the user the CA will get the private key, held encrypted in the recovery database, and the existing user certificate or a new certificate, and create a keystore for the user with this old key pair. The actual recovery would then happen when you make a call to i.e. pkcs12Req in the WS API, or if keystore type is P12, JKS or PEM in the CA UI.

The keys are stored in the database in the table KeyRecoveryData. The data is stored encrypted in a CMS message, as a serialized Java KeyPair. The certificate is not stored in KeyRecoveryData, but only in CertificateData. The encryption key used for the CMS message encryption is the issuing CAs 'keyEncryptKey', and can thus be a key on the HSM. The actual CMS data encryption is performed with AES256_CBC, using a random generated AES key (for this specific CM message). The AES key is wrapped using the RSA key in keyEncryptKey. This is fully according to the best practices, open, stable, CMS standard.

There are additional columns in the KeyRecoveryData table enabling change of the keyEncryptKey of the issuing CA. The columns cryptoTokenId and keyAlias gives an exact pointer to the Crypto Token, and specific key, used to encrypt the data. When decrypting data this specific key, with this alias, on the CAs Crypto Token, is first tried, and only if that fails the CAs 'keyEncryptKey' is tried. In addition, the public Key Id (as also exists in CertificateData) of the public key used to encrypt the data is stored in the column publicKeyId. This means that even if keys changed it is possible to identify the exact public key used to decrypt the data.

Similarly the column serialNumber column of the table KeyRecoveryData matches the column serialNumber in the table CertificateData.

Importing Key Recovery Data from External Sources

It is possible to import key recovery data from an external source, something that can be very useful when migrating to EJBCA from another PKI product.

Importing key recovery data is done from the command line, which provides online help.