Breadcrumbs

EJBCA Cloud AWS KMS Configuration Guide

This guide shows how to integrate the EJBCA AWS instance with the AWS Key Management Service (KMS) and create keys in AWS KMS for use with an EJBCA CA.

Limitations

AWS KMS supports two different asymmetric key types: encryption keys and signing keys. AWS KMS does however not support keys having both functionality at the same time. For more information, refer to the AWS documentation on Selecting the key usage. Due to this design decision, the following functions within EJBCA cannot be used when using AWS KMS:

  • SCEP: Per the RFC, SCEP uses the CAs private key to encrypt the SCEP message. Since there is no way to have a key be an encryption key and a signing key at the same time, the signing key type must be chosen to ensure that the CA can sign certificates and CRLS. For more information on SCEP, see the EJBCA Documentation on SCEP.

  • Key Recovery: EJBCA uses the CAs keyEncryptKey, which is an RSA key used to wrap/unwrap keys in a CMS structure (RFC 5652) for stored key recovery data. Currently, using KMS asymmetric keys for decryption does not work with EJBCA. For more information on Key Recovery, see the EJBCA Documentation on Key Recovery.

If you do not plan on using SCEP or Key Recovery within EJBCA, these limitations do not affect you, and your CA will function as expected. 

AWS User Creation

To create a user that can access the KMS from the EJBCA host, do the following:

  1. Sign in to the AWS console, select the Services drop-down, and search for "IAM".

  2. Select Users and then Add User.

  3. Specify the following to add a user:

    1. Add a user with the name of "ejbca_kms" or any name you choose that describes the usage.

    2. In Access type, select Programmatic access to allow the user to access the KMS API, but not log into the AWS console.

    3. Select Attach existing policies directly under Set permissions and then click Create policy.

  4. In the opened browser tab, Create policy, search for KMS in the product search field and select KMS.

  5. Select the following permissions from the Access level selection:

    • List

      • ListAliases

    • Read

      • GetPublicKey

    • Write

      • CreateAlias

      • CreateKey

      • ScheduleKeyDeletion

      • Sign

  6. Under Resources, select Any for both alias and key resources.

  7. Click Review policy.

  8. In the Create policy screen, specify a Name and Description for the policy and click Create policy.

  9. A confirmation message confirms the successful creation of the policy.

  10. Go back to the Add user tab and click the Refresh button on the right.

  11. Search for the policy created above and select it. 

  12. Click Next to add tags if desired through step 5 to Create user. A successful creation message displays the Access key ID and the Shared access key. Note these credentials down or download the .csv file with the credentials since the Access key ID and the Shared access key will later be used in the EJBCA Crypto Token to access the KMS.

EJBCA Configuration

Note that the following configuration is supported as of EJBCA 7.4.0.

To configure EJBCA, do the following:

  1. Edit the /opt/ejbca/conf/web.properties file and uncomment the following property (on EJBCA Enterprise Cloud from the AWS Marketplace this is done for you):

    Bash
    awskms.cryptotoken.enabled=true

  2. If you are running EJBCA Enterprise software, redeploy.

    Bash
    ant clean deployear

  3. Click Create new on the EJBCA Crypto Token screen and select AWS KMS as the Type.

  4. Enter the credentials for the user, including the region the KMS resides in, and use the following attributes:

    • Authentication code: IAM Users Secret access key

    • Region: The region the KMS keys will reside

    • Access KeyID: IAM users Access key ID

  5. Enable Auto-activation to activate the Crypto Token on system restart (for example, for an issuing CA).

  6. When it successfully connects to the KMS, the notification Crypto Token created successfully is displayed at the top of the page.

  7. Generate the following keys for an EJBCA CA:

    • defaultKey

    • signKey

    • testKey

  8. Go to the KMS console and confirm that the keys created in EJBCA are listed.