IBM Cloud Docs
Importing standard keys

Importing standard keys

You can add your existing encryption keys with the UI, or programmatically with the Hyper Protect Crypto Services key management service API.

Importing standard keys with the UI

After you create an instance of the service, complete the following steps to enter your existing standard key with the Hyper Protect Crypto Services GUI.

  1. Log in to the UI.

  2. Go to Menu > Resource list to view a list of your resources.

  3. From your IBM Cloud resource list, select your provisioned instance of Hyper Protect Crypto Services.

  4. To import a key, select the KMS keys tab in the side menu.

  5. In the Keys table, click Add key and select Import a key.

    Specify the key's details:

    Table 1. Describes the settings to import a standard key
    Setting Description
    Key type The type of key that you would like to manage in Hyper Protect Crypto Services. From the list of key types, select Standard key.
    Key name A unique, human-readable alias for easy identification of your key. To protect your privacy, ensure that the key name does not contain personally identifiable information (PII), such as your name or location.
    Key alias (Optional) One or more unique, human-readable aliases that you want to assign to your key for easy recognition. Alias size can be 2 - 90 characters. You can set up to five key aliases for the key, with each separated by a comma.

    Note: Each alias must be alphanumeric, case-sensitive, and cannot contain spaces or special characters other than dashes (-) or underscores (_). The alias cannot be a version 4 UUID and must not be a Hyper Protect Crypto Services reserved name: allowed_ip, key, keys, metadata, policy, policies, registration, registrations, ring, rings, rotate, wrap, unwrap, rewrap, version, versions.

    Key ring ID Select a key ring from the list that contains the existing key rings. If you don't assign a key ring, the key is added to the default key ring. For more information about key rings, see Managing key rings.
    Key material

    The base64 encoded key material, such as a symmetric key, that you want to manage in the service. For more information, see Base64 encoding your key material. Ensure that the key material meets the following requirements:

    • The key can be up to 7,500 bytes.
    • The key must be base64-encoded.
    Expiration date (Optional) Set the date and time when the key gets expired. After the expiration date, the key moves into the Deactivated state. For more information about key state, see Monitoring the lifecycle of encryption keys.
    Description (Optional) Add an extended description for your key. It needs to be two to 240 characters in length.
  6. When you finish filling out the key's details, click Import key to confirm.

Importing standard keys with the API

Import a standard key by making a POST call to the following endpoint:

https://<instance_ID>.api.<region>.hs-crypto.appdomain.cloud/api/v2/keys
  1. Retrieve your service and authentication credentials to work with keys in the service.

  2. Call the Hyper Protect Crypto Services key management service API with the following cURL command.

    curl -X POST \
      https://<instance_ID>.api.<region>.hs-crypto.appdomain.cloud/api/v2/keys \
      -H 'authorization: Bearer <IAM_token>' \
      -H 'bluemix-instance: <instance_ID>' \
      -H 'content-type: application/vnd.ibm.kms.key+json' \
      -H 'correlation-id: <correlation_ID>' \
      -H 'prefer: <return_preference>' \
      -d '{
     "metadata": {
       "collectionType": "application/vnd.ibm.kms.key+json",
       "collectionTotal": 1
     },
     "resources": [
       {
       "type": "application/vnd.ibm.kms.key+json",
       "name": "<key_alias>",
       "description": "<key_description>",
       "expirationDate": "<YYYY-MM-DDTHH:MM:SS.SSZ>",
       "payload": "<key_material>",
       "extractable": <key_type>
       }
     ]
    }'
    

    Replace the variables in the example request according to the following table.

    Table 2. Describes the variables needed to add a standard key with the Hyper Protect Crypto Services key management service API.
    Variable Description
    region The region abbreviation, such as us-south or au-syd, that represents the geographic area where your Hyper Protect Crypto Services service instance resides. For more information, see Regional service endpoints.
    port Required. The port number of the API endpoint.
    IAM_token Your IBM Cloud access token. Include the full contents of the IAM token, including the Bearer value, in the cURL request. For more information, see Retrieving an access token.
    instance_ID The unique identifier that is assigned to your Hyper Protect Crypto Services service instance. For more information, see Retrieving an instance ID.
    correlation_ID The unique identifier that is used to track and correlate transactions.
    return_preference Optional: A header that alters server behavior for POST and DELETE operations. When you set the return_preference variable to return=minimal, the service returns only the key metadata, such as the key name and ID value, in the response entity-body. When you set the variable to return=representation, the service returns both the key material and the key metadata.
    key_alias A unique, human-readable name for easy identification of your key.

    Important: To protect your privacy, do not store your personal data as metadata for your key.
    key_description Optional: An extended description of your key.

    Important: To protect your privacy, do not store your personal data as metadata for your key.
    YYYY-MM-DD

    HH:MM:SS.SS

    Optional: The date and time that the key expires in the system, in RFC 3339 format. If the expirationDate attribute is omitted, the key does not expire.
    key_material The base64 encoded key material, such as a symmetric key, that you want to manage in the service. For more information, see Base64 encoding your key material.

    Ensure that the key material meets the following requirements:

    * The key can be up to 7,500 bytes.
    * The key must be base64-encoded.
    key_type A boolean value that determines whether the key material can leave the service.

    When you set the extractable attribute to true, the service designates the key as a standard key that you can store in your apps or services.

    To protect the confidentiality of your personal data, avoid entering personally identifiable information (PII), such as your name or location, when you add keys to the service. For more examples of PII, see section 2.2 of the NIST Special Publication 800-122.

    A successful POST /v2/keys response returns the ID value for your key, along with other metadata. The ID is a unique identifier that is assigned to your key and is used for subsequent calls to the Hyper Protect Crypto Services key management service API.

  3. Optional: Verify that the key was added by running the following call to get the keys in your Hyper Protect Crypto Services service instance.

    curl -X GET \
      https://<instance_ID>.api.<region>.hs-crypto.appdomain.cloud/api/v2/keys \
      -H 'accept: application/vnd.ibm.collection+json' \
      -H 'authorization: Bearer <IAM_token>' \
      -H 'bluemix-instance: <instance_ID>' \
      -H 'correlation-id: <correlation_ID>' \
    

Importing standard keys with the CLI

Complete the following steps to import standard keys that use the Key Protect CLI, which is integrated in Hyper Protect Crypto Services:

  1. Set up the Key Protect CLI.

  2. Import a standard key with the following command:

    ibmcloud kp key create
    

    You can find extra parameters for this command in the Key Protect CLI reference.

Base64 encoding your key material

When you import an existing standard key, it is required to include the encrypted key material that you want to store and manage in the service.

Using OpenSSL to encode existing key material

  1. Download and install OpenSSL.

  2. Base64 encode your key material string by running the following command:

    $ openssl base64 -in <infile> -out <outfile>
    

    Replace the variables in the example request according to the following table.

    Table 3. Describes the variables needed to base64 encode your key material
    Variable Description
    infile The name of the file where your key material string resides.
    outfile The name of the file where your base64-encoded key material is created when the command is run.

    If you want to output the base64 material in the command line directly rather than a file, run the command openssl enc -base64 <<< '<key_material_string>', where key_material_string is the key material input for your imported key.

Using OpenSSL to create and encode new key material

  1. Download and install OpenSSL.

  2. Base64 encode your key material string by running the following command:

    $ openssl rand <byte_length> -base64
    

    Replace the byte_length variable in the example request with the length of your key, which is measured in bytes. Acceptable byte length can be up to 7,500 bytes.

What's next

To find out more about programmatically managing your keys, check out the Hyper Protect Crypto Services key management service API reference doc.