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 (External link) 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 (External link) 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 (External link):

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.

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.

You can rotate an imported key by calling the ImportKeyMaterial endpoint (External link) again with new key material on a key that already has key material:

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_new_base64_encoded_key_material>",
        "salt": "<your_base64_encoded_salt>"
    }'

Each call to ImportKeyMaterial with new key material creates a new key rotation for the key. Data that was encrypted with previous key material can still be decrypted using the corresponding older rotations. New data is encrypted with the latest rotation.

List key rotations

To retrieve the key rotations of an imported key and their indexes, use the ListKeyRotations endpoint (External link):

curl -X GET 'https://api.scaleway.com/key-manager/v1alpha1/regions/fr-par/keys/<your_key_id>/rotations' \
    --header 'X-Auth-Token: <Scaleway_API_Secret_Key>'

The response returns a list of rotations for the key, each with an index field. Use this index to target a specific rotation, for example when calling DeleteKeyMaterial.

Delete key material

To delete the key material of a specific key rotation, use the DeleteKeyMaterial endpoint (External link) and specify the rotation to delete with the key_rotation_index field:

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 '{
        "key_rotation_index": 1
    }'

If you do not specify the key_rotation_index field, the latest rotation is deleted.