Your suggested change has been received. Thank you.

close

Suggest A Change

https://thales.na.market.dpondemand.io/docs/dpod/services/kmo….

Thales Logo

All

  • All
back

BYOK Integration

BYOK for AWS

search

Please Note:

BYOK for AWS

AWS KMS provides the ability to import keys from Key Manager. You can use the imported keys in all KMS-integrated AWS services and custom applications. This feature gives you greater control over the generation, lifecycle management, and durability of your keys used in the cloud. Key import also help meet compliance requirements to generate and store copies of keys outside of the cloud provider.

You can set an expiration period for your imported keys or delete them on demand. If you need to use your imported keys after expiration or deletion, they can be re-imported.

Prerequisites

To use BYOK for AWS ensure that:

  1. CADP for Java is installed and configured. Refer to Quick start for detailed installation instructions and Configuration Parameters for configuration details.

  2. A javac compiler exits in the path.

  3. Any of the supported Java version is installed on your machine. Refer to General system architecture for details.

The high-level steps involved in using BYOK for AWS with CADP for Java are:

  • Creating a Customer Master Key (CMK) with external key material.

  • Downloading the AWS public key and import token.

  • Creating an AES-256 key on Key Manager and wrapping it with the AWS public key.

  • Uploading the wrapped key and the import token to AWS.

Create CMK

To create a CMK using the AWS account:

  1. Sign in to the AWS account. The AWS Management Console screen is displayed.

  2. In the Find Services search box, enter Key Management Service and click.

  3. In the left pane on the Key Management Services screen, click Customer managed keys.

  4. On the Customer managed keys screen, click Create key.

  5. On the Configure key screen:

    1. Select the region where the customer managed key is to be stored.

    2. Click to expand Advanced options.

      Advanced Option

    3. Select Key material origin as External.

    4. Select the I understand the security, availability, and durability implications of using an imported key check box.

    5. Click Next. The Add labels screen is displayed.

  6. Provide the following details:

    1. Enter the Alias for the key.

    2. (Optional) Enter the Description for the key.

    3. (Optional) Add Tags to the key.

    4. Click Next. The Define key administrative permissions screen is displayed.

  7. Select the key administrators from the list. You can also set the key deletion permission for the key administrators. Click Next. The Define key usage permissions screen is displayed.

  8. Select the users and roles that can use the CMK in cryptographic operations. You can also specify other AWS accounts who can use the CMK. Click Next.

  9. Preview key policy and click Finish. The Download wrapping key and import token screen is displayed. Select wrapping algorithm from the available options.

    Download Wrapping Key

  10. Click Download wrapping key and import token. Save the ImportParameters.zip to any target location.

    Before you download a public key and an import token, you must determine how to encrypt your key material. You must use the RSA PKCS #1 encryption scheme with one of the following three padding options:

    • RSAES_OAEP_SHA_256: The RSA encryption algorithm with Optimal Asymmetric Encryption Padding (OAEP) and the SHA-256 hash function.

    • RSAES_OAEP_SHA_1: The RSA encryption algorithm with Optimal Asymmetric Encryption Padding (OAEP) and the SHA-1 hash function.

    • RSAES_PKCS1_V1_5: The RSA encryption algorithm with the padding format defined in PKCS #1 Version 1.5.1.8.

    The ImportParameters.zip file contains the AWS public key - used to wrap the AES 256-bit key and import token - uploaded along with the wrapped key to the AWS.

Create AES-256 Key

Refer to Create a key for detailed instructions.

Wrap AES Key

Run the ByokSample. This sample is available on github.

Usage


java ByokSample -cloudName [AWS|Salesforce|GoogleCloud] -userName  -password  -aesKeyName  [-publicKeyPath ] -wrappedKeyPath  [ -wrappingKeyName RSA KeyName] [-outputFormat base64] -wrappingAlgo [SHA1|SHA256|PKCS1.5] [-hash256Path filePath]
ParameterDescription
cloudNameName of the cloud where you want to upload your key.
userNameName of the user on Key Manager.
passwordPassword of the user name on Key Manager.
The following special characters, * ‘ “ and | are not allowed in the password.
aesKeyNameName of the AES-256 key created on Key Manager. If the key does not exist on Key Manager, the ByokSample first creates an AES-256 key and then wraps it using AWS public key.
publicKeyPathComplete path including the file name of the public key downloaded from the AWS. If the public key is already imported to Key Manager, you can skip this parameter.
wrappedKeyPathComplete path including the file name of the wrapped key.
wrappingAlgoWrapping algorithm.
Possible options are:
— SHA1
— SHA256
— PKCS1.5
wrappingKeyNameName of the RSA public key used to wrap AES key. If the publicKeyPath parameter is provided, the public key available at this location will be imported to Key Manager with the specified name and will be used to wrap the AES key. Else, already existing key with the specified name on Key Manager will be used to wrap the AES Key.

Example

This example shows how to wrap an AES-256 bit key.


java ByokSample -cloudName aws -userName kmuser -password kmpassword -aesKeyName AES256Key -publicKeyPath /wrappingKey_9c9c923c-ad02-4e97-b991-5a2c658071ba_0519065630 -wrappedKeyPath /wrapperKey.pem -wrappingKeyName AWSPublicKey -wrappingAlgo PKCS1.5

Here, AES256Key is the key to be wrapped, and AWSPublicKey is the wrapping key which wraps the AES key. The successful execution of ByokSample creates wrapperKey.pem.

Upload Wrapped Key and Import Token to AWS

  1. Sign in to the AWS account. The AWS Management Console screen is displayed.

  2. In the Find Services search box, enter Key Management Service and click Find Services. In the left pane on the Key Management Services screen, click Customer managed keys. The list of aliases is displayed on the screen.

  3. Click the alias name of the CMK link for which you want to upload the key material (wrapped key generated using ByokSample).

  4. Click to expand Key Material and then click Upload key material. The Upload your wrapped key material screen is displayed.

    Upload Key Material

  5. Under the Wrapped key material label, click Choose file and select the wrapped key.

  6. Under the Import token label, click Choose file and select the import token file downloaded while creating the CMK.

  7. In the Expiration option section, select the Key material expires check box. At this step, you can decide if you want to set the expiration time for the key material. If this option is selected, specify the date and time at which the key will expire.

  8. Click Upload key material. A confirmation message about successful import of the key material to the CMK is displayed.

On this page