Using Bring Your Own Key with the Scaleway API and CLI

Bring Your Own Key (BYOK) lets you use your own encryption key material with Scaleway Key Manager. Instead of having Key Manager generate a key on your behalf, you generate the key material locally and import it into a Key Manager key. This is useful when you need to keep control over the generation of your key material, for example to meet regulatory or compliance requirements, or to maintain portability of your keys across cloud providers.

With BYOK, the responsibility for generating strong key material lies with you. Keys are not imported directly into Key Manager, as this would violate the principle that keys only exist inside Key Manager and cannot exit it. Instead, only the key material used to create a key is imported. For this reason, only AES keys can be imported, as they are derived from key material. The process of creating asymmetric keys differs, so they cannot be imported.

For more information on how imported key material is processed cryptographically, see the documentation about customer-provided KEKs (BYOK).

Requirements

To import your own key material, you need:

• A Scaleway API token. Refer to the API documentation for information on authentication.
• A Key Manager key created with the external origin and the AES-256-GCM symmetric encryption algorithm. This is required because only externally-originated AES keys can receive imported key material.

To create such a key, call the CreateKey endpoint as follows:

curl -X POST 'https://api.scaleway.com/key-manager/v1alpha1/regions/fr-par/keys' \
    --header 'Content-Type: application/json' \
    --header 'X-Auth-Token: <Scaleway_API_Secret_Key>' \
    --data '{
        "project_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
        "name": "my-byok-key",
        "usage": {
            "symmetric_encryption": "aes_256_gcm"
        },
        "origin": "external"
    }'

The key is created in the pending_key_material state, which means it is not yet ready to be used for cryptographic operations.

Import key material

To import your key material into your Key Manager key, use the ImportKeyMaterial endpoint:

curl -X POST 'https://api.scaleway.com/key-manager/v1alpha1/regions/fr-par/keys/<your_key_id>/import-key-material' \
    --header 'Content-Type: application/json' \
    --header 'X-Auth-Token: <Scaleway_API_Secret_Key>' \
    --data '{
        "key_material": "<your_base64_encoded_key_material>",
        "salt": "<your_base64_encoded_salt>"
    }'

Execute the following steps to import and use a key:

1. Generate random data locally, which will be used as key material.
2. Create a key with the external origin, as described in the Requirements section.
3. Call ImportKeyMaterial with the key_id of the key you created, and pass your key material in the key_material field.
4. Key Manager uses the key material to create the first key rotation. The key is now ready to use.

Delete key material

To delete the key material of a key, use the DeleteKeyMaterial endpoint:

curl -X POST 'https://api.scaleway.com/key-manager/v1alpha1/regions/fr-par/keys/<your_key_id>/delete-key-material' \
    --header 'Content-Type: application/json' \
    --header 'X-Auth-Token: <Scaleway_API_Secret_Key>' \
    --data '{}'

Rotate an imported key

Rotation for keys with the external origin differs from rotation for keys generated by Key Manager. See the key rotation concept and the Rotate keys using the Scaleway CLI and API documentation for more information.

Currently, it is not possible to rotate an imported key by calling ImportKeyMaterial a second time on a key that already has key material. Such a call returns a precondition failed error, because the key is no longer in the pending_key_material state.

The options to "rotate" a BYOK key are:

• Call DeleteKeyMaterial to delete the current key rotation, then call ImportKeyMaterial again with new key material.
  Important

  This is not the same as a regular rotation. In this case, the previous rotation is deleted, and the older ciphertexts can no longer be decrypted with the new key material.

• Create a new key with the external origin and import new key material into it, as described in the Requirements section.