Import a key

Importing key material needs a special process to ensure the integrity of the key material. The goal is to not give any information about the key material itself to anything besides the backend it should be imported into.

This utilises the envelope encryption to wrap the key material before uploading it. Therefore before uploading key material a wrapping key has to be created in the target backend to be able to wrap the key material accordingly.

Prerequisites

• You have created a key ring in your project: Create and manage key rings

Import a symmetric key

To see an overview of purposes and algorithms, please visit Concepts.

The key material that will be imported must 32 bytes in raw size.

STACKIT API

1. Create a key to import to

   curl  -X POST \
   'https://kms.api.eu01.stackit.cloud/v1/projects/<project-id>/regions/<region-id>/keyrings/<keyring-id>/keys' \
   --header 'Authorization: Bearer <access-token>' \
   --header 'Content-Type: application/json' \
   --data '{
       "displayName": "sample_key",
       "protection": "software",
       "purpose": "symmetric_encrypt_decrypt",
       "algorithm": "aes_256_gcm",
   }'

   Possible values for purpose:

   • symmetric_encrypt_decrypt
   • message_authentication_code

   Possible values for algorithm:

   • aes_256_gcm (for symmetric_encrypt_decrypt)
   • hmac_sha256 (for message_authentication_code)
   • hmac_sha384 (for message_authentication_code)
   • hmac_sha512 (for message_authentication_code)

2. Create a wrapping key

   curl  -X POST \
   'https://kms.api.eu01.stackit.cloud/v1/projects/<project-id>/regions/<region-id>/keyrings/<keyring-id/wrappingkeys' \
   --header 'Authorization: Bearer <access-token>' \
   --header 'Content-Type: application/json' \
   --data-raw '{
       "displayName": "wrapping-key",
       "description": "wrapping key to wrap the key material to import to",
       "protection": "software",
       "purpose": "wrap_symmetric_key",
       "algorithm": "rsa_2048_oaep_sha256",
   }'

   Possible values for purpose:

   • wrap_symmetric_key

   Possible values for algorithm:

   • rsa_2048_oaep_sha256
   • rsa_3072_oaep_sha256
   • rsa_4096_oaep_sha256
   • rsa_4096_oaep_sha512

3. Download the public key of the wrapping key

   curl  -X GET \
   'https://kms.api.eu01.stackit.cloud/v1/projects/<project-id>/regions/<region-id>/keyrings/<keyring-id/wrappingkeys/<wrapping-key-id>' \
   --header 'Authorization: Bearer <access-token>'

4. Use the wrapping key to encrypt the key material to import

   openssl pkeyutl \
   -encrypt \
   -pubin \
   -inkey <wrapping-key> \
   -in <key-to-import> \
   -pkeyopt rsa_padding_mode:oaep \
   -pkeyopt rsa_oaep_md:sha256 \
   -pkeyopt rsa_mgf1_md:sha256 \
   | base64

   Depending on the hash-algorithm chosen in the first step use sha256 or sha512 for pkeyopt

5. Upload the wrapped key into the target key

   curl  -X POST \
   'https://kms.api.eu01.stackit.cloud/v1/projects/<project-id>/regions/<region-id>/keyrings/<keyring-id>/keys/<key-id>/import' \
   --header 'Authorization: Bearer <access-token>' \
   --header 'Content-Type: application/json' \
   --data-raw '{
       "wrappingKeyId": "<wrapping-key-id>",
       "wrappedKey": "<base64-encoded-wrapped-key>"
   }'

Import an asymmetric key

To see an overview of purposes and algorithms, please visit Concepts.

STACKIT API

1. Create a key to import to

   curl  -X POST \
   'https://kms.api.eu01.stackit.cloud/v1/projects/<project-id>/regions/<region-id>/keyrings/<keyring-id>/keys' \
   --header 'Authorization: Bearer <access-token>' \
   --header 'Content-Type: application/json' \
   --data '{
       "displayName": "sample_key",
       "protection": "software",
       "purpose": "asymmetric_encrypt_decrypt",
       "algorithm": "rsa_2048_oaep_sha256",
   }'

   Possible values for purpose:

   • asymmetric_encrypt_decrypt
   • asymmetric_sign_verify

   Possible_values for algorithm:

   • rsa_2048_oap_sha256 (for asymmetric_encrypt_decrypt)
   • rsa_3072_oap_sha256 (for asymmetric_encrypt_decrypt)
   • rsa_4096_oap_sha256 (for asymmetric_encrypt_decrypt)
   • rsa_4096_oap_sha512 (for asymmetric_encrypt_decrypt)
   • ecdsa_p256_sha256 (for asymmetric_sign_verify)
   • ecdsa_p384_sha384 (for asymmetric_sign_verify)
   • ecdsa_p521_sha512 (for asymmetric_sign_verify)

2. Create a wrapping key

   curl  -X POST \
   'https://kms.api.eu01.stackit.cloud/v1/projects/<project-id>/regions/<region-id>/keyrings/<keyring-id/wrappingkeys' \
   --header 'Authorization: Bearer <access-token>' \
   --header 'Content-Type: application/json' \
   --data-raw '{
       "displayName": "wrapping-key",
       "description": "wrapping key to wrap the key material to import to",
       "protection": "software",
       "purpose": "wrap_asymmetric_key",
       "algorithm": "rsa_2048_oaep_sha256_aes_key_wrap"
   }'

   Possible values for purpose:

   • wrap_asymmetric_key

   Possible values for algorithm:

   • rsa_2048_oaep_sha256_aes_256_key_wrap
   • rsa_3072_oaep_sha256_aes_256_key_wrap
   • rsa_4096_oaep_sha256_aes_256_key_wrap
   • rsa_4096_oaep_sha512_aes_256_key_wrap

3. Retrieve the public key of the wrapping key and store it in a file wrapping_key.pem

   curl  -X GET \
   'https://kms.api.eu01.stackit.cloud/v1/projects/<project-id>/regions/<region-id>/keyrings/<keyring-id>/wrappingkeys/<wrapping-key-id>' \
   --header 'Authorization: Bearer <access-token>'

4. Generate a short-term 256-bit AES key

   openssl rand 32 > key

5. Convert your existing PKCS#1 key to PKCS#8 format and .der encode it

   openssl pkcs8 -topk8 -inform pem -outform der -nocrypt -in <your-key> -out pkcs8.der

6. Encrypt the short-term AES key using the public key of the wrapping key and base64 encode it

   openssl pkeyutl -encrypt -pubin -inkey wrapping_key.pem -in key -pkeyopt rsa_padding_mode:oaep -pkeyopt rsa_oaep_md:sha256 -pkeyopt rsa_mgf1_md:sha256 > wrapped_key.bin

7. Encrypt the RSA private key using the generated AES key

   openssl enc -e -id-aes256-wrap-pad -iv A65959A6 -K $(hexdump -v -e '1/1 "%02x"' key) -in private.der >> wrapped_key.bin

8. Upload the wrapped key into the target key

   curl  -X POST \
   'https://kms.api.eu01.stackit.cloud/v1/projects/<project-id>/regions/<region-id>/keyrings/<keyring-id>/keys/<key-id>/import' \
   --header 'Authorization: Bearer <access-token>' \
   --header 'Content-Type: application/json' \
   --data '{
       "wrappingKeyId": "<wrapping-key-id>",
       "wrappedKey": "<base64-encoded-wrapped-key>"
   }'