| copyright | lastupdated | keywords | subcollection | ||
|---|---|---|---|---|---|
|
2024-05-30 |
import encryption key, upload encryption key, bring your own key, byok, key material, secure import, import tokens |
hs-crypto |
{{site.data.keyword.attribute-definition-list}}
{: #importing-keys}
Encryption keys contain subsets of information, such as the metadata that helps you identify the key, and the key material that is used to encrypt and decrypt data. {: shortdesc}
When you use {{site.data.keyword.cloud}} {{site.data.keyword.hscrypto}} to create keys, the service generates cryptographic key material on your behalf that is rooted in the hardware security modules (HSMs) of your {{site.data.keyword.hscrypto}} instance. But depending on your business requirements, you might need to generate key material from your internal solution, and then extend your on-premises key management infrastructure onto the cloud by importing keys into {{site.data.keyword.hscrypto}}.
| Benefit | Description |
|---|---|
| Keep Your Own Key (KYOK) | If you choose to export symmetric keys from your internal key management infrastructure, you can use {{site.data.keyword.hscrypto}} to securely bring them to the cloud. The KYOK feature ensures that you own the root trust of your key hierarchy and that no one except you have access to your encryption keys. |
| Secure import of root key material | When you export your keys to the cloud, you want assurance that the key material is protected while it's in flight. Mitigate against man-in-the-middle attacks by using an import token to securely import root key material into your {{site.data.keyword.hscrypto}} service instance. |
| {: caption="Table 1. Describes the benefits of importing key material" caption-side="bottom"} |
{: #plan-ahead}
Keep the following considerations in mind when you're ready to import root key material to the service.
Review your options for creating key material : Explore your options for creating 256-bit symmetric encryption keys based on your security needs. For example, you can use your internal key management system, backed by a FIPS-validated, on-premises hardware security module (HSM), to generate key material before you bring keys to the cloud. If you're building a proof of concept, you can also use a cryptography toolkit such as OpenSSL to generate key material that you can import into {{site.data.keyword.hscrypto}} for your testing needs.
Choose an option for importing key material into {{site.data.keyword.hscrypto}} : Choose from two options for importing root keys based on the level of security that is required for your environment or workload. By default, {{site.data.keyword.hscrypto}} encrypts your key material while it's in transit by using the Transport Layer Security (TLS) 1.2 protocol. If you're building a proof of concept or trying out the service for the first time, you can import root key material into {{site.data.keyword.hscrypto}} by using this default option. If your workload requires a security mechanism beyond TLS, you can also use an import token to encrypt and import root key material into the service.
Plan ahead for encrypting your key material : If you choose to encrypt your key material by using an import token, determine a method for running RSA encryption on the key material. You must use the RSAES_OAEP_SHA_1 encryption scheme as specified by the PKCS #1 v2.1 standard for RSA encryption{: external}. Review the capabilities of your internal key management system or on-premises HSM to determine your options.
Plan ahead for encrypting the nonce : If you choose to encrypt your key material by using an import token, you must also determine a method for running AES-GCM encryption on the nonce that is distributed by {{site.data.keyword.hscrypto}}. The nonce serves as a session token that checks the originality of a request to protect against malicious attacks and unauthorized calls. Review the capabilities of your internal key management system or on-premises HSM to determine your options.
Manage the lifecycle of imported key material : After you import key material into the service, keep in mind that you are responsible for managing the complete lifecycle of your key. By using the {{site.data.keyword.hscrypto}} key management service API, you can set an expiration date for the key when you decide to upload it into the service. However, if you want to rotate an imported root key, you must generate and provide new key material to retire and replace the existing key.
{: #using-import-tokens}
If you want to encrypt your key material before you import it into {{site.data.keyword.hscrypto}}, you can create an import token for your service instance by using the {{site.data.keyword.hscrypto}} key management service API.
Import tokens are a resource type in {{site.data.keyword.hscrypto}} that enable the secure import of key material to your service instance. By using the contents of an import token to encrypt your key material on-premises, you protect root keys while they're in flight to {{site.data.keyword.hscrypto}} based on the policies that you specify. For example, you can set a policy on the import token that limits the use based on time and usage count.
{: #how-import-tokens-work}
When you create an import token for your service instance, {{site.data.keyword.hscrypto}} generates a 4096-bit RSA key-pair from the HSMs. When you retrieve the import token, the service supplies the public key that you can use for encrypting and uploading a key to {{site.data.keyword.hscrypto}}.
The following list describes the import token workflow.
- You send a request to create an import token.
- {{site.data.keyword.hscrypto}} generates an RSA key-pair from the crypto units (HSMs).
- The public key becomes available for retrieval based on the policy that you specified at creation time.
- The private key becomes nonextractable and never leaves the crypto unit.
- You send a request to retrieve the import token.
- You receive the import token contents, including:
- A public key for the encrypting key material that you want to import into the service.
- A nonce value that is used to verify the key import request.
- You receive the import token contents, including:
- You prepare the key that you want to import to the service.
- You generate key material by using an on-premises key management mechanism.
- You encrypt the nonce value with the key material by using an AES-GCM encryption method that is compatible with your environment.
- You encrypt the key material with the public key by using an RSA encryption method that is compatible with your environment.
- You send a request to import the key.
- You provide the encrypted key material, the encrypted nonce, and the initialization vector (IV) that was generated by the AES-GCM algorithm.
- {{site.data.keyword.hscrypto}} verifies your request, decrypts the encrypted packet, and stores the key material as a root key in your service instance.
You can create only one import token per service instance at a time. To learn more about retrieval limits for import tokens, see the {{site.data.keyword.hscrypto}} key management service API reference doc{: external}. {: note}
{: #secure-import-api-methods}
Behind the scenes, the {{site.data.keyword.hscrypto}} key management service API drives the import token creation process.
The following table lists the API methods that set up an import token for your service instance.
| Method | Description |
|---|---|
POST api/v2/import_token |
Create an import token |
GET api/v2/import_token |
Retrieve an import token |
| {: caption="Table 2. Describes the key management service API methods" caption-side="bottom"} |
{: #importing-keys-next}
- To learn how to create an import token for your service instance, see Creating an import token.
- To find out more about importing keys to the service, see Importing root keys.
- To find out more about programmatically managing your keys in {{site.data.keyword.hscrypto}}, check out the {{site.data.keyword.hscrypto}} key management service API reference doc{: external}.