diff --git a/faq/key-manager.mdx b/faq/key-manager.mdx new file mode 100644 index 0000000000..44a4a55a8b --- /dev/null +++ b/faq/key-manager.mdx @@ -0,0 +1,39 @@ +--- +meta: + title: Key Manager FAQ + description: Explore Scaleway Key Manager with our comprehensive FAQ covering security, key types, and more. +content: + h1: Key Manager +dates: + validation: 2025-01-06 +category: identity-and-access-management +productIcon: KeyManagerProductIcon +--- + +## Why should you use Scaleway Key Manager? + +Key Manager helps organizations achieve secure key management by handling low-level and error-prone cryptographic details for you. + +## What features does Scaleway Key Manager include? + +Scaleway Key Manager allows you to create, manage and use cryptographic keys in a centralized and secure service. All your cryptographic operations can be delegated to Key Manager, which in turn ensures the security and availability of your keys. + +## Which management methods can I use with Key Manager? + +Read our [dedicated documentation](/identity-and-access-management/key-manager/reference-content/understanding-key-manager/#management-methods-you-can-use-with-key-manager) to find out about the management methods Key Manager provides. + +## Which cryptographic operations does Key Manager support? + +Key Manager supports the three following cryptographic operations: + +- [Encryption](/identity-and-access-management/key-manager/concepts/#encryption) +- [Decryption](/identity-and-access-management/key-manager/concepts/#decryption) +- [Data encryption key](/identity-and-access-management/key-manager/concepts/#data-encryption-key-dek) generation + +## Which algorithms and key usage does Key Manager support? + + + +Keys with a [key usage](/identity-and-access-management/key-manager/concepts/#key-usage) set to `symmetric_encryption` are **used to encrypt and decrypt data**. + +Refer to our [dedicated documentation](/identity-and-access-management/key-manager/reference-content/understanding-key-manager/) to find out more about Key Manager. \ No newline at end of file diff --git a/identity-and-access-management/key-manager/api-cli/create-dek-api-cli.mdx b/identity-and-access-management/key-manager/api-cli/create-dek-api-cli.mdx new file mode 100644 index 0000000000..05ac1dba97 --- /dev/null +++ b/identity-and-access-management/key-manager/api-cli/create-dek-api-cli.mdx @@ -0,0 +1,79 @@ +--- +meta: + title: Creating a data encryption key using the Scaleway API and the Scaleway CLI + description: Learn how to generate a data encryption key (DEK) using the Scaleway CLI or API, leveraging Key Manager with AES encryption for secure data handling. +content: + h1: Creating a data encryption key using the Scaleway API and the Scaleway CLI + paragraph: Learn how to generate a data encryption key (DEK) using the Scaleway CLI or API, leveraging Key Manager with AES encryption for secure data handling. +tags: key-management dek data-encryption-key cli sdk api encryption +dates: + validation: 2025-01-06 + posted: 2025-01-06 +categories: + - identity-and-access-management +--- + + + +- A Scaleway account logged into the [console](https://console.scaleway.com) +- [Owner](/identity-and-access-management/iam/concepts/#owner) status or [IAM permissions](/identity-and-access-management/iam/concepts/#permission) allowing you to perform actions in the intended Organization +- Created a key encryption key either from the [Scaleway console](/identity-and-access-management/key-manager/how-to/create-km-key) or the [Key Manager API](https://www.scaleway.com/en/developers/api/key-manager/#path-keys-create-a-key) +- Retrieved your key encryption key's ID +- Created an [API key](/identity-and-access-management/iam/how-to/create-api-keys/) +- Downloaded and configured the [Scaleway CLI](https://github.com/scaleway/scaleway-cli?tab=readme-ov-file#getting-started) + +## Generate a DEK using the Scaleway CLI + +1. Open a terminal and paste the following commands to export your environment variables. Make sure that you replace the placeholder values with your own. + ```bash + export SCW_ACCESS_KEY= + export SCW_SECRET_KEY= + export SCW_DEFAULT_ORGANIZATION_ID= + export SCW_PROJECT_ID= + export SCW_DEFAULT_REGION="fr-par" + export SCW_API_URL="https://api.scaleway.com" + ``` + +2. Paste the following command to generate a data encryption key via the Scaleway CLI. Make sure that you replace `` with the ID of your key encryption key. + ```bash + scw keymanager key generate-data-key key-id= algorithm=aes_256_gcm + ``` + +An output similar to the following should display: + ```bash + KeyID + Algorithm + Ciphertext + Plaintext + CreatedAt + ``` + + + For convenience, Key Manager returns the plaintext version of the DEK, but it should never be stored in this form. Storing the decrypted plaintext of your DEK undermines the security provided by Key Manager, rendering it ineffective. + + +## Generate a DEK using the API + +Paste the following command to create your data encryption key via the Key Manager API. Make sure that you replace the placeholder values with your own. + ```bash + curl --location 'https://api.scaleway.com/key-manager/v1alpha1/regions/fr-par/keys//generate-data-key' \ + --header 'Content-Type: application/json' \ + --header 'X-Auth-Token: ' \ + --data '{ + "algorithm": "aes_256_gcm" + }' + ``` + +Key Manager also supports the `GenerateDataKey` request without a plaintext operation, which only returns an encrypted data encryption key. + +If you need to use your DEK, you can decrypt it using the [Decrypt data operation](https://www.scaleway.com/en/developers/api/key-manager/#path-keys-decrypt-data) specifying the `kek_id` parameter used to encrypt it. + +**Key Manager does not handle direct data encryption**. It is specifically designed to **encrypt and decrypt Data Encryption Keys (DEKs) and is limited to processing inputs up to 64KB in size**. + +However, you can use the DEK independently from Key Manager, for example with the [Tink extension](/encrypt-decrypt-dek-/#encrypt-and-decrypt-data-with-tink-and-key-manager) or with [OpenSSL](/encrypt-decrypt-dek/#manually-encrypt-and-decrypt-data-with-a-key-manager-dek). + + + The way the KEK is generated, its length, and the encryption algorithm used, **cannot be changed or customized after creation**. However, unlike the KEK, you have the flexibility to choose any encryption algorithm (cipher) you prefer for encrypting and decrypting your data with the DEK. You are not restricted to a specific encryption method for the data itself. + **We highly recommend that you use standard and well-established ciphers (and the proper mode), as well as a library like Tink, that chooses the right cryptosystem according to your use-case.** + + diff --git a/identity-and-access-management/key-manager/api-cli/encrypt-decrypt-data-with-km-dek.mdx b/identity-and-access-management/key-manager/api-cli/encrypt-decrypt-data-with-km-dek.mdx new file mode 100644 index 0000000000..3719f2003b --- /dev/null +++ b/identity-and-access-management/key-manager/api-cli/encrypt-decrypt-data-with-km-dek.mdx @@ -0,0 +1,283 @@ +--- +meta: + title: Encrypting and decrypting data with a Key Manager data encryption key + description: Learn how to use Tink with Scaleway's Key Manager to securely encrypt and manage keys, including KEKs and DEKs, in Go and Python applications. +content: + h1: Encrypting and decrypting data with a Key Manager data encryption key + paragraph: Learn how to use Tink with Scaleway's Key Manager to securely encrypt and manage keys, including KEKs and DEKs, in Go and Python applications. +tags: key-manager encryption decryption kms dek data-encryption-key +dates: + validation: 2025-01-20 + posted: 2025-01-20 +categories: + - identity-and-access-management +--- + +This page shows you how to encrypt and decrypt data using your Key Manager [data encryption key](/identity-and-access-management/key-manager/concepts/#data-encryption-key-dek) and [Tink](https://github.com/tink-crypto/tink/tree/master). + + + +- A Scaleway account logged into the [console](https://console.scaleway.com) +- [Owner](/identity-and-access-management/iam/concepts/#owner) status or [IAM permissions](/identity-and-access-management/iam/concepts/#permission) allowing you to perform actions in the intended Organization +- Created a key encryption key either from the [Scaleway console](/identity-and-access-management/key-manager/how-to/create-km-key/) or the [Key Manager API](https://www.scaleway.com/en/developers/api/key-manager/#path-keys-create-a-key) +- Retrieved your key encryption key's ID +- A valid [API key](/identity-and-access-management/iam/how-to/create-api-keys/) +- Downloaded and configured the [Scaleway CLI](https://github.com/scaleway/scaleway-cli?tab=readme-ov-file#getting-started) +- [Dowloaded and installed Python](https://www.python.org/downloads/) version >=3.9 or [Go](https://go.dev/doc/install) +- [Created a Key Manager data encryption key](/identity-and-access-management/key-manager/how-to/create-manage-dek/) +- [Installed Poetry](https://python-poetry.org/docs/#installation) +- [Created a project](https://python-poetry.org/docs/basic-usage/#project-setup) in Poetry +- [Set a Python version](https://python-poetry.org/docs/basic-usage/#setting-a-python-version) in your Petry project + +## Encrypt and decrypt data with Tink and Key Manager + +The [Scaleway Tink extension](/identity-and-access-management/key-manager/api-cli/manage-keys-with-tink) generates a unique data encryption key for each piece of data that it encrypts. This method follows the cryptography best practices of using unique data encryption keys for each encryption operation. + +Tink is an open source cryptography library written by cryptographers and security engineers at Google. + +In order to use Tink for data encryption, you need to provide it with a key URI and a configuration file: + +- The key URI points to your key encryption key (KEK) in Scaleway Key Manager. + +- The configuration file grants Tink the necessary permissions to access and use the KEK identified by the Key URI. + +Tink generates a data encryption key (DEK) which will be used to encrypt your data. The DEK itself is then encrypted using the KEK from Key Manager. This ensures that the DEK is securely protected and can only be decrypted by someone with access to the KEK. + +The final output is a single ciphertext that includes both the encrypted data and the encrypted DEK (wrapped DEK). This means that the DEK and the data are both securely packaged together. + +Scaleway supports the **Python and Go Tink providers**. + +### Configuring your environment variables + +Open a terminal and paste the following command to export your environment variables. Make sure that you replace the placeholder values with your own. + +```bash + + export SCW_ACCESS_KEY="" + export SCW_SECRET_KEY="" + export SCW_DEFAULT_ORGANIZATION_ID="" + export SCW_PROJECT_ID="" + export SCW_DEFAULT_REGION="" + export SCW_API_URL="" + export SCW_KMS_KEY_ID="" +``` + +### Using the Python Tink provider + +1. Open a terminal and access your desired Poetry project: + + ``` + cd your-project + ``` + + + Poetry is used to manage dependencies. You can however use any package management tool of your choice. For more information on managing dependencies, refer to the [official Python documentation](https://packaging.python.org/en/latest/tutorials/managing-dependencies/). + +2. Initialize your project: + ``` + poetry init + ``` +3. Add the [Scaleway Tink provider for Python](https://github.com/scaleway/tink-py-scwkms/tree/v0.1.0): + ```bash + poetry add scaleway-tink + ``` +4. Copy the following template: + ```bash + from scaleway_tink.integration.scwkms import clientimport base64 + import base64 + import os + + def main(): + key_uri = f"scw-kms://{os.getenv('SCW_KMS_KEY_ID')}" + aead = client.ScwKmsClient(None, None).get_aead(key_uri) + + plaintext = b'message' + ciphertext = aead.encrypt(plaintext, b'') + + print(f"plaintext: {plaintext.decode()}") + print(f"ciphertext in base64: {base64.b64encode(ciphertext).decode()}") + print(f"decrypt(ciphertext): {aead.decrypt(ciphertext, b'').decode()}") + + main() + ``` +5. Create a file named `example.py` and paste the code from the step above in it. + +6. Run your code: + ```bash + python3 ./example.py + ``` + + +### Using the Go Tink provider + +1. Open a terminal and add the [Scaleway Tink provider for Go](https://github.com/scaleway/tink-go-scwkms/tree/main) to your `go.mod` file. + + ```bash + go get github.com/scaleway/tink-go-scwkms + ``` + +2. Add the Tink library for Go to your `go.mod` file: + ```bash + go get github.com/tink-crypto/tink-go/v2 + go mod tidy + ``` + + The Tink library for Go is a cryptographic library that simplifies encryption, decryption, and key management operations. + +3. Create a Go project with a `test.go` file in it. +4. Copy the following code. + ```bash + package main + + import ( + "fmt" + "github.com/scaleway/tink-go-scwkms/integration/scwkms" + "github.com/tink-crypto/tink-go/v2/aead" + "log" + "os" + ) + + func main() { + const keyURIPrefix = "scw-kms://regions//keys/" + keyURI := keyURIPrefix + os.Getenv("SCW_KMS_KEY_ID") + + client, err := scwkms.NewClient(keyURIPrefix) + if err != nil { + log.Fatal(err) + } + + kekAEAD, err := client.GetAEAD(keyURI) + if err != nil { + log.Fatal(err) + } + + // Get the KMS envelope AEAD primitive. + dekTemplate := aead.AES256GCMKeyTemplate() + primitive := aead.NewKMSEnvelopeAEAD2(dekTemplate, kekAEAD) + if err != nil { + log.Fatal(err) + } + + // Use the primitive. + plaintext := []byte("message") + associatedData := []byte("example KMS envelope AEAD encryption") + + ciphertext, err := primitive.Encrypt(plaintext, associatedData) + if err != nil { + log.Fatal(err) + } + + fmt.Printf("Plaintext: %s\n", plaintext) + fmt.Printf("Ciphertext (base64): %s\n", ciphertext) + + decryptedCiphertext, err := primitive.Decrypt(ciphertext, associatedData) + if err != nil { + log.Fatal(err) + } + + fmt.Printf("Decrypted ciphertext: %s\n", decryptedCiphertext) + } + ``` +5. Paste the code from the step above in your `test.go` file. +6. Replace `` with the region where your key is located and save your changes. +7. Run your code: + ```bash + go run test.go + ``` + + +## Manually encrypt and decrypt data with a Key Manager DEK + +### OpenSSL overview + +OpenSSL is a software library for secure communication over computer networks. It is widely used for cryptographic functions. + +To decrypt or encrypt your data using OpenSSL, you need to send your encrypted DEK to Key Manager using the [Decrypt data operation](https://www.scaleway.com/en/developers/api/key-manager/#path-keys-decrypt-data). + +Scaleway Key Manager then uses your key encryption key (KEK) to decrypt the encrypted DEK, returning it to its plaintext (unencrypted) form, which you can then use to decrypt your actual data. + + + - **We do not recommend that you use OpenSSL in a production environment**. + - You should **never save the plaintext DEK on disk or any permanent storage, as it poses a security risk**. + + + +### Encrypting data with OpenSSL + + +To encrypt your data using OpenSSl, we need to: + +1. Decrypt your encrypted DEK using your Key Manager key (key encryption key) + +2. Create a `plaintext.txt` file in which we will paste your plaintext data. + +3. Encrypt the content of `plaintext.txt` using OpenSSL and the AES-256-CBC cipher encryption algorithm. + +Open a terminal and paste the following command to perform the actions described above. Make sure that you replace `` and `` with the relevant values. +```bash +# Decrypt the encrypted DEK using scw key decrypt +decrypted_data_key=$(scw keymanager key decrypt key-id= ciphertext= | awk '$1 == "Plaintext" {print $2}' | base64 -d) + +# Put your data plaintext into a .txt file +echo -n "Your plaintext here" > plaintext.txt + +# Encrypt your file using OpenSSL and AES-256-CBC +openssl enc -aes-256-cbc -in plaintext.txt -out encrypted.bin -K $(echo -n "$decrypted_data_key" | hexdump -ve '/1 "%02x"') -iv 0 -nosalt -p + +# Remove the plaintext data +rm plaintext.txt +``` + +### Decrypting data with OpenSSL + +To decrypt your encrypted data using OpenSSL, we need to: + +1. Decrypt your encrypted DEK using your Key Manager key (key encryption key) + +2. Decrypt the content of `encrypted.bin` which contains your encrypted data, using OpenSSL and the AES-256-CBC cipher encryption algorithm. + +Open a terminal and paste the following command to perform the actions described above. Make sure that you replace `` and `` with the relevant values. +```bash + # Decrypt the encrypted DEK using scw key decrypt + decrypted_data_key=$(scw keymanager key decrypt key-id= ciphertext= | awk '$1 == "Plaintext" {print $2}' | base64 -d) + + # Decrypt your data using OpenSSL and AES-256-CBC + openssl enc -aes-256-cbc -d -in encrypted.bin -out decrypted.bin -K $(echo -n "$decrypted_data_key" | hexdump -ve '/1 "%02x"') -iv 0 -nosalt -p +``` + + + If you do not wish to use OpenSSL to encrypt and decrypt your data encryption key, you can do it manually using the procedure below, which follows best practices. + + + +### Encrypting a DEK manually + +1. [Generate one data encryption key](/generate-dek-cli-api/) for each plaintext you want to encrypt. + + + This ensures that each encryption operation uses a unique encryption key, enhancing security. + + +2. Use your newly created DEK to encrypt the desired plaintext securely. + + + We recommend using **standard and well-established ciphers** such as `AES` (Advanced Encryption Standard), to perform the encryption operation. + + +3. After encrypting the plaintext using your DEK, concatenate the encrypted DEK with the resulting ciphertext. This ensures that the encrypted DEK is securely associated with the corresponding ciphertext for decryption. + +### Decrypting a DEK manually + +1. Extract the encrypted DEK from the ciphertext. + + + Extracting an encrypted DEK from the ciphertext means that we are separating the encrypted DEK from the ciphertext. + + +2. Decrypt the encrypted DEK using your Key manager key (key encryption key). +3. Use the resulting DEK's plaintext to decrypt the ciphertext. + + + Use the same cryptographic algorithm and decryption mechanism as the ones you used during the encryption process. + +4. Delete the plaintext DEK from permanent storage after using it to enhance security. \ No newline at end of file diff --git a/identity-and-access-management/key-manager/api-cli/encrypt-decrypt-keys-with-streaming-aead-tink.mdx b/identity-and-access-management/key-manager/api-cli/encrypt-decrypt-keys-with-streaming-aead-tink.mdx new file mode 100644 index 0000000000..e53dd17f52 --- /dev/null +++ b/identity-and-access-management/key-manager/api-cli/encrypt-decrypt-keys-with-streaming-aead-tink.mdx @@ -0,0 +1,208 @@ +--- +meta: +title: Encrypting and decrypting data streams with Streaming AEAD, Tink and Key Manager +description: Learn how to use Key Manager with Tink for secure encryption and decryption of large data streams using AEAD in Go. +content: +h1: Encrypting and decrypting data streams with Streaming AEAD, Tink and Key Manager +paragraph: Learn how to use Key Manager with Tink for secure encryption and decryption of large data streams using AEAD in Go. +tags: key sensitive-data tink aead streaming encryption decryption +dates: + validation: 2025-01-06 + posted: 2025-01-06 +categories: + - identity-and-access-management +--- + +This page shows you how to use Scaleway Key Manager with Tink to securely handle large data streams. Specifically, it uses AEAD, which ensures both encryption and authentication of data, along with associated data (like file paths) that is authenticated but not encrypted. This is important for handling large files efficiently, especially in cases where stream processing is necessary (such as video files or large logs). + +Tink is a multi-language cryptographic library that simplifies common cryptographic operations like encryption, decryption, signing, and more. It provides cryptographic primitives, including AEAD. + +Key Manager handles secure storage and management of encryption keys. In this case, it is integrated with Tink to manage a Key Encryption Key (KEK). + +Streaming AEAD: This is the cryptographic primitive that handles secure, authenticated streaming encryption. It ensures that large amounts of data are encrypted on the fly without needing to load everything into memory. + +This page shows you how to use the Key Manager Tink extension to encrypt and decrypt large data streams using Authenticated Encryption with Associated Data (AEAD). + + + +- A Scaleway account logged into the [console](https://console.scaleway.com) +- [Owner](/identity-and-access-management/iam/concepts/#owner) status or [IAM permissions](/identity-and-access-management/iam/concepts/#permission) allowing you to perform actions in the intended Organization +- Created a key encryption key (KEK) in Key Manager +- A working Go environment +- Installed the [Scaleway Go SDK](https://github.com/scaleway/scaleway-sdk-go) and created [credentials](/developer-tools/scaleway-sdk/go-sdk/) + +## Configuring your environment variables + +Configuring your environment variables allows the Go application to authenticate and use Scaleway's API and Key Manager. + +Open a terminal and paste the following commands to export your environment variables. Make sure that you add your **own variables**. You can also use a Scaleway configuration file. + + ``` + export SCW_ACCESS_KEY="" + export SCW_SECRET_KEY="" + export SCW_DEFAULT_ORGANIZATION_ID="" + export SCW_DEFAULT_PROJECT_ID="" + export SCW_DEFAULT_REGION="" + export SCW_API_URL="" + export SCW_KMS_KEY_ID="" + ``` + +## Encrypting and decrypting large data streams using AEAD + + +1. Open a terminal and add the necessary dependencies for your Go project ([Scaleway Tink provider for Go](https://github.com/scaleway/tink-go-scwkms/tree/main) and Tink): + + ``` + go get github.com/scaleway/tink-go-scwkms + go get github.com/tink-crypto/tink-go/v2 + ``` + +2. Create a Go project and paste the following code into a Go file: + + ``` + package main + + import ( + "bytes" + "fmt" + "github.com/scaleway/tink-go-scwkms/integration/scwkms" + "github.com/tink-crypto/tink-go/v2/keyset" + "github.com/tink-crypto/tink-go/v2/streamingaead" + "io" + "log" + "os" + "path/filepath" + ) + + func main() { + const keyURIPrefix = "scw-kms://regions//keys/" + keyURI := keyURIPrefix + os.Getenv("SCW_KMS_KEY_ID") + + client, err := scwkms.NewClient(keyURIPrefix) + if err != nil { + log.Fatal(err) + } + + kekAEAD, err := client.GetAEAD(keyURI) + if err != nil { + log.Fatal(err) + } + + handle, err := keyset.NewHandle(streamingaead.AES256GCMHKDF1MBKeyTemplate()) + if err != nil { + log.Fatal(err) + } + + // Encrypt the keyset and store it in memory (using a bytes buffer) + buf := new(bytes.Buffer) + writer := keyset.NewBinaryWriter(buf) + err = handle.Write(writer, kekAEAD) + if err != nil { + log.Fatalf("Error writing encrypted keyset: %v", err) + } + + // Decrypt the keyset from the buffer + reader := keyset.NewBinaryReader(buf) + decryptedHandle, err := keyset.Read(reader, kekAEAD) + if err != nil { + log.Fatalf("Error reading encrypted keyset: %v", err) + } + + // Create the Streaming AEAD primitive from the decrypted keyset + primitive, err := streamingaead.New(decryptedHandle) + if err != nil { + log.Fatalf("Error creating streaming AEAD primitive: %v", err) + } + + // Create a file with the plaintext. + dir, err := os.MkdirTemp("", "streamingaead") + if err != nil { + log.Fatal(err) + } + defer os.RemoveAll(dir) + plaintextPath := filepath.Join(dir, "plaintext") + if err := os.WriteFile(plaintextPath, []byte("this data needs to be encrypted"), 0666); err != nil { + log.Fatal(err) + } + plaintextFile, err := os.Open(plaintextPath) + if err != nil { + log.Fatal(err) + } + + // AssociatedData defines the context of the encryption. (It is optional) + // Here, we include the path of the plaintext file. + associatedData := []byte("associatedData for " + plaintextPath) + + // Encrypt the plaintext file and write the output to the ciphertext file. + ciphertextPath := filepath.Join(dir, "ciphertext") + ciphertextFile, err := os.Create(ciphertextPath) + if err != nil { + log.Fatal(err) + } + w, err := primitive.NewEncryptingWriter(ciphertextFile, associatedData) + if err != nil { + log.Fatal(err) + } + if _, err := io.Copy(w, plaintextFile); err != nil { + log.Fatal(err) + } + if err := w.Close(); err != nil { + log.Fatal(err) + } + if err := ciphertextFile.Close(); err != nil { + log.Fatal(err) + } + if err := plaintextFile.Close(); err != nil { + log.Fatal(err) + } + + // Print the content of the encrypted file. + c, err := os.ReadFile(ciphertextPath) + if err != nil { + log.Fatal(err) + } + fmt.Println(string(c)) + + // Decrypt the ciphertext file and write the output in the decrypted file. + ciphertextFile, err = os.Open(ciphertextPath) + if err != nil { + log.Fatal(err) + } + decryptedPath := filepath.Join(dir, "decrypted") + decryptedFile, err := os.Create(decryptedPath) + if err != nil { + log.Fatal(err) + } + r, err := primitive.NewDecryptingReader(ciphertextFile, associatedData) + if err != nil { + log.Fatal(err) + } + if _, err := io.Copy(decryptedFile, r); err != nil { + log.Fatal(err) + } + if err := decryptedFile.Close(); err != nil { + log.Fatal(err) + } + if err := ciphertextFile.Close(); err != nil { + log.Fatal(err) + } + + // Print the content of the decrypted file. + b, err := os.ReadFile(decryptedPath) + if err != nil { + log.Fatal(err) + } + fmt.Println(string(b)) + } + ``` + + - The example above shows you how to use the Key Manager remote key encryption key to protect your data encryption key and AEAD stream, you can also protect the data encryption key using another non-remote key. + - Associated data is authenticated but not encrypted + + +3. Save your changes and run the following commands to execute your code: + + ``` + go mod tidy + go run test.go + `` diff --git a/identity-and-access-management/key-manager/api-cli/index.mdx b/identity-and-access-management/key-manager/api-cli/index.mdx new file mode 100644 index 0000000000..ee9c2480bf --- /dev/null +++ b/identity-and-access-management/key-manager/api-cli/index.mdx @@ -0,0 +1,8 @@ +--- +meta: + title: Key Manager - API/CLI Documentation + description: Key Manager API/CLI Documentation +content: + h1: API/CLI Documentation + paragraph: Key Manager API/CLI Documentation +--- diff --git a/identity-and-access-management/key-manager/api-cli/manage-keys-with-tink.mdx b/identity-and-access-management/key-manager/api-cli/manage-keys-with-tink.mdx new file mode 100644 index 0000000000..86ccf4d33b --- /dev/null +++ b/identity-and-access-management/key-manager/api-cli/manage-keys-with-tink.mdx @@ -0,0 +1,266 @@ +--- +meta: + title: Managing your Key Manager keys using Tink + description: Learn how to use Tink with Scaleway's Key Manager to securely encrypt and manage keys, including KEKs and DEKs, in Go applications. +content: + h1: Managing your Key Manager keys using Tink + paragraph: Learn how to use Tink with Scaleway's Key Manager to securely encrypt and manage keys, including KEKs and DEKs, in Go applications. +tags: key-manager encryption kms key-management-service cryptographic +dates: + validation: 2025-01-06 + posted: 2025-01-06 +categories: + - identity-and-access-management +--- + +This documentation page provides information on Key Manager Key Encryption Keys (KEKs) and Data Encryption Keys (DEKs), and how to use them with the Tink Go library. + +Tink is an open-source library that helps you safely perform cryptographic operations, like encrypting data and managing encryption keys. It works well with different platforms and follows best practices for security. Tink also supports using remote keys right away. + +We suggest using Tink when working with Scaleway's Key Manager, especially with Go or Python. + + + +- A Scaleway account logged into the [console](https://console.scaleway.com) +- [Owner](/identity-and-access-management/iam/concepts/#owner) status or [IAM permissions](/identity-and-access-management/iam/concepts/#permission) allowing you to perform actions in the intended Organization +- Created and enabled a data encryption key (DEK) in your Key Manager +- A working Go environment +- Installed the [Scaleway Go SDK](https://github.com/scaleway/scaleway-sdk-go) with [valid credentials](/developer-tools/scaleway-sdk/go-sdk/) + + +## Installing the necessary tools + +Tink is a library that helps you perform encryption (securing data) and manage encryption keys. It can work with various key management services (KMS), including Scaleway's Key Manager. +To use Tink with Scaleway Key Manager, you need to install dependencies that let Tink interact with Key Manager. + +1. Open a terminal and run the following commands: + + ```shell + # Install Tink for Go + go get -u github.com/tink-crypto/tink-go/v2 + + # Install the Scaleway Tink extension + go get -u github.com/scaleway/tink-go-scwkms + ``` +2. Retrieve the ID (UUIDv4 format) of your Key Manager's key (KEK). +3. Copy the following template and paste it into a `.go` file: + + ```go + import ( + "github.com/scaleway/scaleway-sdk-go/scw" // Library that helps your Go program interact with Scaleway + "github.com/tink-crypto/tink-go/v2/aead" // Tink library + "github.com/scaleway/tink-go-scwkms/integration/scwkms" // Scaleway's Tink extension + ) + + const region = "" // Replace the placeholder with the region where your key is created + const keyID = "7f967268-bebb-43b0-9fe2-e13bd23bf421" // Replace the placeholder with the unique ID of your key encryption key + + keyURIPrefix := "scw-kms://regions/" + region + "/keys/" + keyURI := keyURIPrefix + keyID + + // Set up a connection to Scaleway + config, _ := scw.LoadConfig() // Loads your Scaleway configuration + profile, _ := config.GetActiveProfile() // Gets the active profile (your account settings) + + // Set up the connection to use your key in Key Manager + kms, _ := scwkms.NewClientWithOptions( + keyURIPrefix, + scw.WithProfile(profile), // Uses your account profile + scw.WithEnv(), // Uses environment settings + ) + // Prepare the key for encryption and decryption + kekAEAD, _ := kms.GetAEAD(keyURI) + ``` +4. Replace the placeholder values with your own. + + + The `kekAEAD` object represents the key in Scaleway’s Key Manager. It allows you to encrypt payloads and decrypt ciphertexts. + + +## Encrypting and decrypting data + +Paste the following code into a `.go` file. This file contains the data we will encrypt (`"Hello, World!"`), and the code to encrypt and decrypt it. + ```go + associatedData := []byte("") // Read the ## Associated data section for more information + secretData := []byte("Hello, World!") // Data we want to encrypt + + ciphertext, _ := kekAEAD.Encrypt(secretData, associatedData) // Encrypt the data + fmt.Println(ciphertext) // Print the encrypted data + + plaintext, _ := kekAEAD.Decrypt([]byte(ciphertext), associatedData) + fmt.Println(string(plaintext)) // Output: "Hello, World!" + ``` + + + While the code shown above functions as intended, this is not a recommended pattern and the following limitations apply: + - It is slow: since the key resides on Scaleway Key Manager, each encryption or decryption operation translates into a remote API call. + - The payload to encrypt is limited in size: Key Manager only allows up to 64 KiB. As a result, you will not be able to encrypt larger payloads with `kekAEAD`. + - You cannot choose the cipher and the algorithm that suit your use case, Key Manager handles that on your behalf. + + +## Understanding the difference between KEKs and DEKs + +**Key encryption key (KEK)**: This is a key (`kekAEAD`) used to encrypt other keys (DEKs, which protect your data), not the actual data. It stays secure in Scaleway Key Manager. + +**Data Encryption Key (DEK)**: This key is used to encrypt your actual data. Key Manager does not store or manage your DEK. A DEK is usually stored alongside the data it protects, and it is **always** stored encrypted (by the KEK). + +The KEK secures the DEK, and the DEK secures your data. This double-layer approach improves security. + + + - Your application is responsible for storing the encrypted DEKs alongside the encrypted data they protect. + - DEKs must **never** reside in plaintext. They must be encrypted by the remote KEK before being stored. + + +## Using Tink keysets as DEKs + +Tink does not handle single keys, it manages groups of keys called **keysets**, a set of related keys kept together with their metadata. We use the terms `key` and `keyset` interchangeably since we work with keysets containing only one key here. Tink can generate keys to be used with the desired algorithm and cipher. + +1. Run the following code to create a DEK using Tink and store it encrypted with your KEK, using the `AES256-GCM` algorithm. + + ```go + import "github.com/tink-crypto/tink-go/v2/keyset" // Import the package that provides functionalities to create, manage, and store keysets in Tink + + /* ... */ + /* ... */ + + handle, _ := keyset.NewHandle(aead.AES256GCMKeyTemplate()) // Generate an AES256-GCM key + associatedData := []byte("") + + f, _ := os.OpenFile("/path/to/encrypted_dek.tink", os.O_RDWR|os.O_CREATE, 0644) + defer f.Close() + w := keyset.NewBinaryWriter(f) + + // Serialize the keyset and encrypt it with the remote KEK, + handle.WriteWithAssociatedData(w, kekAEAD, associatedData) + ``` + + + + Check out the full list of supported algorithms and ciphers in the [Tink Go reference](https://pkg.go.dev/github.com/tink-crypto/tink-go/v2/aead) if you need to use another algorithm or cipher. We recommend that you stick with the `AES256-GCM` algorithm if you are unsure. + + + + Your encrypted DEK is now stored in `/path/to/encrypted_dek.tink`. + +2. Run the following code to read and use your encrypted DEK: + + ```go + // Load, deserialize, and decrypt the DEK with the remote KEK + f, _ := os.Open("/path/to/encrypted_dek.tink") + defer f.Close() + r := keyset.NewBinaryReader(f) + handle, _ := keyset.ReadWithAssociatedData(r, kekAEAD, associatedData) + + // Use the DEK represented by "primitive" to encrypt data. The primitive created from the DEK is used to encrypt a string ("This is a secret") into a ciphertext (secret1) + primitive, _ := aead.New(handle) + + secret1, _ := primitive.Encrypt([]byte("This is a secret"), dataAssociatedData1) + /* + * Store secret1 somewhere + */ + + secret2, _ := primitive.Encrypt([]byte("This is another secret"), dataAssociatedData2) + /* + * Store secret2 somewhere + */ + ``` + + Tink only provides methods that work on types that comply with `Reader` and `Writer` interfaces. If you need to write and read Tink keysets as direct bytes, you can use `bytes.Buffer`, which is an in-memory buffer used to hold the encrypted keyset. This allows you to serialize and deserialize keysets directly as byte arrays instead of using files. + + +3. Run the following command to store the DEK in memory as bytes: + + ```go + buf := new(bytes.Buffer) + w := keyset.NewBinaryWriter(buf) + handle.WriteWithAssociatedData(w, kekAEAD, associatedData) + encDEK := buf.Bytes() // encrypted DEK in Tink wire format + ``` + +You can then store the bytes of the encrypted DEK in a database for example, with the encrypted data it protects. For example, the encrypted data (enc_data) and the encrypted DEK (enc_dek) might be stored together in a row in a database (base64-encoded in the following example): + + ```console + SELECT id, enc_data, enc_dek FROM sensible_stuff; + + id | enc_data | enc_dek + -----|----------------------------|------------------- + 42 | "7NXIqRms0+TiKj+V0gv1s..." | "vIiYBeypb7Yk..." + 43 | "7X8v0GVrXWwL/ckzfRms0..." | "vIiYBeypb7Yk..." + ... + ... + ... + ``` + + +## Associated Data + +Associated Data (AD) is not encrypted, but it is authenticated. It must be the same when you encrypt and decrypt data, otherwise the decryption fails. This is useful to prevent reading the wrong data in the wrong context. In the table above, the data in both rows 42 and 43 is protected by the same DEK. If we swapped the data, an application would be able to decrypt the data from another row. But, by providing the intended ID as the associated data, the decryption would fail. + +### Encrypt data with AD before inserting it + +Run the following command to encrypt your data with `Associated Data`. In the example below, associated data like `id42` and `id43` is used to ensure that data from row 42 cannot be decrypted in the context of row 43. + + ```go + handle, _ := keyset.ReadWithAssociatedData(r, kekAEAD, dekAD) + primitive, _ := aead.New(handle) // Same DEK for the two payloads + + secret1, _ := primitive.Encrypt([]byte("This is a secret"), []byte("id42")) + // Insert secret1 into row 42 + + secret2, _ := primitive.Encrypt([]byte("This is another secret"), []byte("id43")) + // Insert secret2 into row 43 + ``` + +Associated Data does not need to be stored, as it can be inferred from the context at decryption time. It is also possible to use a unique DEK for each payload. We recommend using Associated Data. + + +## Hierarchy of keys + +Unlike KEKs that reside and are managed by Key Manager, DEKs are free: you can generate and have as many as you want. + +However, your application still needs to call the Key Manager API: + + - At least once to encrypt a newly generated DEK before storing it, and + - Each time a DEK needs to be decrypted before use + +Thus, you can use a hierarchy of keys to minimize calls to the Key Manager API (or any remote key management service), which can slow down your application and incur charges. + +In the example below, the application only needs to call Key Manager once to decrypt the DEK Master Key. All subsequent decryption of DEKs happens locally, which improves efficiency. + +```go +// The DEK Master Key (which protects all other DEKs) is stored and protected by the remote KEK. +masterKeyFile, _ := os.Open("/path/to/encrypted_masterkey.tink") +masterKeyHandle, _ := keyset.ReadWithAssociatedData(masterKeyFile, kekAEAD, []byte("master-key-001")) // Call the API +masterKeyAEAD, _ := aead.New(masterKeyHandle) + +// DEK #1 encrypted and decrypted by the Master Key, rather than by the remote KEK directly. This avoids frequent API calls. +dek1File, _ := os.Open("/path/to/encrypted_dek1.tink") +dekHandle1, _ := keyset.ReadWithAssociatedData(dek1File, masterKeyAEAD, []byte("dek1")) // No call to the API + +// DEK #2 encrypted and decrypted by the Master Key, rather than by the remote KEK directly. This avoids frequent API calls. +dek2File, _ := os.Open("/path/to/encrypted_dek2.tink") +dekHandle2, _ := keyset.ReadWithAssociatedData(dek2File, masterKeyAEAD, []byte("dek2")) // No call to the API + + +// DEKs are used to encrypt and decrypt the actual data + +dek1AEAD, _ := aead.New(dekHandle1) +dek2AEAD, _ := aead.New(dekHandle2) + +ct1, _ := dek1AEAD.Encrypt([]byte("this is a secret"), []byte("id42")) +ct2, _ := dek2AEAD.Encrypt([]byte("this is another secret"), []byte("id43")) + +/* ... */ +/* ... */ +``` + + + Your DEK and KEK do not need to use the same algorithm and cipher. + + +The example above can work for most use cases. However, there is no "one fits all" approach when creating the right key hierarchy. It is up to you to decide on a hierarchy that suits you best, according to your application needs and constraints. + + + + Scaleway does not define keys managed by Key Manager (or any other key management service) as DEKs or KEKs. The context in which you use these keys makes them DEKs or KEKs. We usually assume that keys in Key Manager are only used to protect other keys, hence the use of the terms "KEKs" and "DEKs". + diff --git a/identity-and-access-management/key-manager/api-cli/rotate-keys-api-cli.mdx b/identity-and-access-management/key-manager/api-cli/rotate-keys-api-cli.mdx new file mode 100644 index 0000000000..0aabfc3a84 --- /dev/null +++ b/identity-and-access-management/key-manager/api-cli/rotate-keys-api-cli.mdx @@ -0,0 +1,106 @@ +--- +meta: +title: Perform key rotation using the Scaleway CLI and API +description: Learn why key rotation enhances security and how to configure automated or manual key rotation in Scaleway's Key Manager. +content: +h1: Perform key rotation using the Scaleway CLI and API +paragraph: Learn why key rotation enhances security and how to configure automated or manual key rotation in Scaleway's Key Manager. +tags: key sensitive-data rotation +dates: + validation: 2025-01-06 + posted: 2025-01-06 +categories: + - identity-and-access-management +--- + +Key rotation is a critical security practice that ensures that encryption keys are not reused for extended periods of time. Regularly rotating keys helps limit the number of messages encrypted with the same key version. + +This reduces the risk of exposure if a key is compromised, thus enhancing the overall security and resilience of your system. For symmetric encryption, it is generally recommended to rotate keys every 30 to 90 days. + +However, this may vary based on your specific use-case and risk profile. + + + Rotating a key will not re-encrypt your data encryption key or any data you may have encrypted. When performing a + decryption operation with your key on data encrypted before the rotation, the response will contain the ciphertext of your data + with the latest rotation of the key. You can replace your current ciphertext with the new one. + As long as you do not delete the key, anything that you have encrypted with it will still be decipherable. + + +## Why is key rotation recommended? + +Key rotation offers several important advantages such as: + +- **Mitigating cryptanalysis attacks:** Limiting the amount of messages encrypted with the same key version reduces the risk of +cryptanalysis attacks. The recommended key lifetime varies depending on the key algorithm, the number of messages, and +the total number of bytes encrypted with the same key version. For example, for the symmetric algorithm AES-256-GCM, +keys must be rotated before approximately 2^32 encryptions have been performed, following the guidelines of [NIST +publication 800-38D](https://nvlpubs.nist.gov/nistpubs/Legacy/SP/nistspecialpublication800-38d.pdf). + +- **Minimizing the impact of key compromise:** Regular key rotation limits the amount of messages that could be exposed if +a key is compromised. + +- **Maintaining system resilience against security incidents:** Regular key rotation helps your system stay resilient to +both manual key rotation, whether prompted by a security breach or the need to upgrade to a stronger encryption algorithm. + +- **Complying with regulatory requirements:** Many industry regulations and standards, such as PCI DSS, NIST guidelines, and others, +require or recommend regular key rotation as part of maintaining strong cryptographic controls. + +## Automated key rotation policy + +Copy the following command to configure automatic rotation when creating a key: + +``` + curl -X POST \ + --header 'Content-Type: application/json' \ + --header 'X-Auth-Token: ' \ + 'https://api.scaleway.com/key-manager/v1alpha1/regions/fr-par/keys' \ + --data '{ + "project_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", + "name": "my-key", + "usage": { + "symmetric_encryption": "aes_256_gcm" + }, + "description": "my key with a rotation policy", + "rotation_policy": { + "rotation_period": "2592000s", // 30 days + "next_rotation_at": "2024-10-01T01:00:00Z" + } + }' +``` + +- **rotation_period:** duration between two key rotations (min: 24 hours, max: 100 years). +- **next_rotation_at:** date at which the key will be rotated next. + +To configure automatic rotation on an existing key, use the `UpdateKey` endpoint as follows: + +``` + curl -X PATCH 'https://api.scaleway.com/key-manager/v1alpha1/regions/fr-par/keys/' \ + --header 'Content-Type: application/json' \ + --header 'X-Auth-Token: ' \ + --data '{ + "rotation_policy": { + "rotation_period": "2592000s", // 30 days + "next_rotation_at": "2024-10-01T01:00:00Z" + } + }' +``` + +## Manually rotate your key + +To rotate your key manually, you can use the `RotateKey` endpoint as follows: + +``` + curl -X POST 'https://api.scaleway.com/key-manager/v1alpha1/regions/fr-par/keys//rotate' \ + --header 'X-Auth-Token: ' \ + --data '' +``` + + + Avoid relying on irregular or manual key rotation as the primary security measure for your application. + + +Keep in mind that: + +- Manually rotating a key does not interrupt, modify or affect its existing automatic rotation schedule. +- Key rotation (both manual and automated) is not possible when you import your own key, because a new key material +would be required for each rotation. diff --git a/identity-and-access-management/key-manager/concepts.mdx b/identity-and-access-management/key-manager/concepts.mdx new file mode 100644 index 0000000000..ad6215f5d1 --- /dev/null +++ b/identity-and-access-management/key-manager/concepts.mdx @@ -0,0 +1,152 @@ +--- +meta: + title: Key Manager - Concepts + description: Explore essential cryptographic concepts, including symmetric and asymmetric encryption, data encryption keys (DEKs), key encryption keys (KEKs), and Scaleway Key Manager's robust features for secure key management and encryption operations. +content: + h1: Concepts + paragraph: Explore essential cryptographic concepts, including symmetric and asymmetric encryption, data encryption keys (DEKs), key encryption keys (KEKs), and Scaleway Key Manager's robust features for secure key management and encryption operations. +tags: key-manager key encryption-key +dates: + validation: 2025-01-06 +--- + +## Asymmetric encryption + +Asymmetric encryption is a fundamental type of cryptographic method used to secure data with a pair of keys: a **public key** and a **private key**. + +The public key is used for encryption and can be shared openly, while the private key is used for decryption and must be kept secret. This design eliminates the need to share a single key securely, which is a challenge in symmetric encryption. + +Asymmetric encryption is particularly well-suited for secure communication and authentication, such as encrypting emails or verifying digital signatures. However, it is slower than symmetric encryption. Algorithms like RSA and ECC are common examples of asymmetric encryption. + +## Ciphertext + +Ciphertext refers to data that has been encrypted using a cryptographic algorithm and a key. + +Unlike [plaintext](#plaintext), ciphertext is not human-readable and cannot be understood or used without first decrypting it with the appropriate decryption key. + +## Cryptographic operation + +A cryptographic operation is any action performed using cryptography to secure data, ensure privacy, or authenticate information. + +Key Manager supports the three following cryptographic operations: + +- [Encryption](#encryption) +- [Decryption](#decryption) +- [Data encryption key](#data-encryption-key-dek) generation + + +These operations are designed to protect data from unauthorized access, ensure its integrity, and verify the identities of users or systems. + +## Data encryption key (DEK) + +A data encryption key is a type of key that can be used outside Key Manager to encrypt and decrypt [payloads](#payload). + +Key Manager generates DEKs on-demand. They are then encrypted by a [key encryption key](#key-encryption-key-kek) specified by the user, and forwarded to the recipient. + +DEKs are **not stored in or managed by Key Manager**. Users are responsible for safely storing and managing DEKs. DEKs should have the same lifecycle as the [payload](#payload) they encrypt**. + +## Decryption + +A cryptographic operation used to convert [ciphertext](#ciphertext) back into its original [plaintext](#plaintext) form, using a key encryption key. + +The only way to decrypt an encrypted payload is by using the `Decrypt` [endpoint](https://www.scaleway.com/en/developers/api/key-manager/V1/#path-keys-decrypt-keys). Since key versions never leave Key Manager, there is no other way to decrypt data outside Key Manager.** A payload encrypted with an older key version can still be decrypted. In this case, for convenience, the payload encrypted with the latest key version will be returned, along with the decrypted payload. + +## Encryption + +A cryptographic operation used to encrypt data using the latest version of the Key Manager key. The [encryption algorithm](#encryption-algorithm) used is the one defined when setting the [key usage](#key-usage). + +Only keys with a usage set to `symmetric_encryption` are supported by this method. The input data is arbitrary, but this endpoint should only be used to encrypt **data encryption keys**, not actual [payloads](#payload). + +[Find out how to encrypt and decrypt payloads using The Scaleway Tink provider](/identity-and-access-management/key-manager/api-cli/manage-keys-with-tink) + +## Encryption algorithm + +An encryption algorithm is the specific procedure used to perform encryption and decryption. + +It defines the exact steps to transform plaintext into ciphertext and vice versa using a key. + +As of now, Key Manager supports the following encryption algorithm: + +- AES (Advanced Encryption Standard): A widely used symmetric encryption algorithm. + +## Encryption method + +An encryption method is a broader approach used to convert readable data ([plaintext](#plaintext)) into an unreadable format ([ciphertext](#ciphertext)) which may involve one or more [encryption algorithms](#encryption-algorithm). + +There are three types of encryption methods: + +- [Symmetric encryption](#symmetric-encryption) +- [Asymmetric encrytpion](#asymmetric-encryption) +- Hybrid encryption: An encryption method that combines both symmetric and asymmetric methods + +Key Manager only supports symmetric encryption. + +## Encryption scheme + +An encryption scheme is a structured approach to encryption that specifies the encryption algorithm, key size, and mode of operation for block chiphers. + +For example, in the `AES-256-GCM` encryption scheme: + +- `AES` refers to the Advanced Encryption Standard (AES) encryption algorithm +- `256` refers to the key length in bits +- `GCM` or Galois/Counter Mode, is the mode of operation for block ciphers. GCM encrypts your plaintext data using AES, and authenticates it using a unique "tag". This means that if anyone tampers with your data, you will know because the tag will not match anymore. + +## Key encryption key (KEK) + +A key encryption key (KEK) is a type of key that has a single purpose: encrypting and decrypting [data encryption keys](#data-encryption-key-dek). + +The KEK is permanently stored in Scaleway's Key Manager and never leaves it. It cannot be accessed by anyone, and should be [rotated](/identity-and-access-management/key-manager/api-cli/rotate-keys-api-cli/) regularly. + +## Key management + +Key management is the process of handling keys used in cryptographic systems to ensure the security and integrity of your cryptographic operations. This includes the generation, exchange, storage, usage, and disposal of these keys. +Although strong cipher algorithms allow you to protect your information with secret keys, your data is only protected as long as your encryption keys are kept secret from non-authorized individuals. + +## Key protection + +Key protection allows your key to be used and modified, but not deleted. This provides an additional layer of security. + +## Key rotation + +Key rotation is the process of replacing an old cryptographic key with a new one. It is a critical practice in key management to minimize the risk of exposure if a key is compromised and to enhance the overall security and resilience of your systems. + +When using [symmetric encryption](#symmetric-encryption), it is generally recommended to rotate keys every 30 to 90 days. + +After rotating your Key Manager keys, all cryptographic operations will use the new rotated keys. All data encrypted with former key versions will remain decipherable with the former key. + +## Key usage + +The key usage specifies the **algorithm** used to create subsequent key versions, and the **scope of cryptographic operations** supported by your key encryption key. +You must define a key usage upon key creation. As of now, Key Manager **only supports symmetric encryption**. + +## Key version + +A key version is a a specific iteration of your key encryption key. Each version of your key represents a distinct state or version that may be [rotated](#key-rotation) or replaced over time. + +Key versions allow you to manage and track changes to your data encryption keys. When using key versions, all cryptographic operations will rely on the current key version. + +Data you have encrypted with previous key versions will still be accessible and decipherable using those specific keys, ensuring backward compatibility. + +## Payload + +A payload refers to the core data or message being transmitted, processed, or protected. It is the information of interest that encryption or other security mechanisms aim to secure. + +## Plaintext + +Plaintext refers to unencrypted, readable data. In the context of key management, plaintext often refers to cryptographic keys or sensitive data that are stored or transmitted in an unencrypted form. This term is often used in contrast to ciphertext, which is data that has been encrypted and is not readable without decryption. + +## Region + +A Region refers to the **geographical location** in which your key will be created. **Each region contains multiple Availability Zones**. Your key will be duplicated on **all Availability Zones** of the selected region. Scaleway is available in the Paris, Amsterdam, and Warsaw regions. + +## Root encryption key (REK) + +A root encryption key (REK) is another type of key that has the single purpose of encrypting and decrypting KEKs in order to store them in hard storage. Scaleway's Key Manager has one REK per region, which is securely stored in our facilities. + +## Symmetric encryption + +Symmetric encryption is a fundamental type of cryptographic method where the same key is used to both encrypt and decrypt data. This means that the sender and receiver must have access to the same secret key, which they use to secure their communication. + +Because symmetric encryption relies on a single key, it is generally fast and ideal for encrypting large volumes of data. However, its security depends entirely on keeping the key confidential. + +Symmetric encryption algorithms like AES are widely used in scenarios where speed and efficiency are critical. As of now, Key Manager only supports the `AES_256_GCM` symmetric encryption algorithm. \ No newline at end of file diff --git a/identity-and-access-management/key-manager/how-to/create-km-key.mdx b/identity-and-access-management/key-manager/how-to/create-km-key.mdx new file mode 100644 index 0000000000..f284e7b09a --- /dev/null +++ b/identity-and-access-management/key-manager/how-to/create-km-key.mdx @@ -0,0 +1,38 @@ +--- +meta: + title: Create a Key Manager key + description: Discover how to create a key from the Scaleway console to decrypt your data using Scaleway's Key Manager. +content: + h1: Create a Key Manager key + paragraph: Discover how to create a key from the Scaleway console to decrypt your data using Scaleway's Key Manager. +tags: key-manager encryption data key +dates: + validation: 2025-01-06 + posted: 2025-01-06 +categories: + - identity-and-access-management +--- + +Scaleway's Key Manager allows you to create key encryption keys from the [Scaleway console](https://console.scaleway.com). Key encryption keys can then be used to encrypt and decrypt your encrypted data. + + + +- A Scaleway account logged into the [console](https://console.scaleway.com) +- [Owner](/identity-and-access-management/iam/concepts/#owner) status or [IAM permissions](/identity-and-access-management/iam/concepts/#permission) allowing you to perform actions in the intended Organization + +## How to create a Key Manager key + +1. Click Key Manager in the **Security and Identity section** of the [Scaleway console](https://console.scaleway.com) side menu. +2. Click **+ Create key**. +3. Choose the region in which you want to create your key. +4. Enter a name, a description, and optional tags for your key. +5. Select the [encryption method](/identity-and-access-management/key-manager/concepts/#encryption-method) for your key. + + + Key Manager currently only supports the `AES-256 GCM` [symmetric encryption](/identity-and-access-management/key-manager/concepts/#symmetric-encryption) algorithm. + +6. Switch the icon to disable [key protection](/identity-and-access-management/key-manager/concepts/#key-protection) or leave it enabled. + + Key protection allows you to protect your key from accidental deletion. + +7. Click **Create key**. Your key's **Overview** page displays. \ No newline at end of file diff --git a/identity-and-access-management/key-manager/how-to/create-manage-dek.mdx b/identity-and-access-management/key-manager/how-to/create-manage-dek.mdx new file mode 100644 index 0000000000..41952cf62d --- /dev/null +++ b/identity-and-access-management/key-manager/how-to/create-manage-dek.mdx @@ -0,0 +1,42 @@ +--- +meta: + title: Create and manage a Key Manager data encryption key + description: Discover how to create a data encryption key from the Scaleway console to encrypt and decrypt your payloads using Scaleway's Key Manager. +content: + h1: Create and manage a Key Manager data encryption key + paragraph: Discover how to create a data encryption key from the Scaleway console to encrypt and decrypt your payloads using Scaleway's Key Manager. +tags: key-manager data-encryption-key data key payload encryption +dates: + validation: 2025-01-06 + posted: 2025-01-06 +categories: + - identity-and-access-management +--- +Scaleway's key Manager allows you to create [data encryption keys (DEK)](/identity-and-access-management/key-manager/concepts/#data-encryption-key-dek) to encrypt and decrypt your [payload](/identity-and-access-management/key-manager/concepts/#payload). + +You can then use your Key Manager key to encrypt your DEK. + + + You are responsible for storing your DEKS, as Key Manager does not store them for you. + + + + +- A Scaleway account logged into the [console](https://console.scaleway.com) +- [Owner](/identity-and-access-management/iam/concepts/#owner) status or [IAM permissions](/identity-and-access-management/iam/concepts/#permission) allowing you to perform actions in the intended Organization +- [Created](/identity-and-access-management/key-manager/how-to/create-km-key/) a Key Manager key + +## How to create and manage a data encryption key (DEK) + +1. Click Key Manager in the **Security and Identity section** of the [Scaleway console](https://console.scaleway.com) side menu. Your keys display. +2. Click the key for which to create a data encryption key. +3. Scroll down to the **Generate data encryption key** section. +4. Click **Generate data encryption key**. A pop-up displays with the [ciphertext](/identity-and-access-management/key-manager/concepts/#ciphertext) of your DEK. +5. Copy and store your DEK's ciphertext safely. + + - We recommend that you **always store the ciphertext** of your data encryption key rather than its [plaintext](/identity-and-access-management/key-manager/concepts/#plaintext). + - While Scaleway Key Manager is responsible for generating, encrypting, and decrypting data encryption keys, it does not store, manage, or monitor them, nor does it engage in cryptographic operations with these keys. **You must use and manage data encryption keys outside of Key Manager**. + - Read our [documentation](/identity-and-access-management/key-manager/reference-content/understanding-key-manager/) to understand Key Manager. + +6. Optionally, click **Display plaintext** to make sure that the plaintext does not contain any mistakes. +7. Click **Close**. \ No newline at end of file diff --git a/identity-and-access-management/key-manager/how-to/delete-km-key.mdx b/identity-and-access-management/key-manager/how-to/delete-km-key.mdx new file mode 100644 index 0000000000..05611f4c57 --- /dev/null +++ b/identity-and-access-management/key-manager/how-to/delete-km-key.mdx @@ -0,0 +1,34 @@ +--- +meta: + title: Delete a Key Manager key + description: Discover how to delete a Key Manager key from the Scaleway console. +content: + h1: Delete a Key Manager key + paragraph: Discover how to delete a Key Manager key from the Scaleway console. +tags: key-manager delete key +dates: + validation: 2025-01-06 + posted: 2025-01-06 +categories: + - identity-and-access-management +--- + +This page shows you how to delete a Key Manager key. + + + +- A Scaleway account logged into the [console](https://console.scaleway.com) +- [Owner](/identity-and-access-management/iam/concepts/#owner) status or [IAM permissions](/identity-and-access-management/iam/concepts/#permission) allowing you to perform actions in the intended Organization +- [Created](/identity-and-access-management/key-manager/how-to/create-km-key/) a Key Manager key +- Disabled key protection from the key to delete + +## How to delete a key + +1. Click Key Manager in the **Security and Identity section** of the [Scaleway console](https://console.scaleway.com) side menu. Your keys display. +2. Click the key you want to delete. +3. Scroll down to the **Delete key** section, and click **Delete key**. +4. Type **DELETE** to confirm and click **Delete key**. + + + All data encrypted using this key, including data encryption keys, will become unusable. + \ No newline at end of file diff --git a/identity-and-access-management/key-manager/how-to/disable-km-key.mdx b/identity-and-access-management/key-manager/how-to/disable-km-key.mdx new file mode 100644 index 0000000000..2ac5bd31a5 --- /dev/null +++ b/identity-and-access-management/key-manager/how-to/disable-km-key.mdx @@ -0,0 +1,33 @@ +--- +meta: + title: Disable a Key Manager key + description: Discover how to disable a Key Manager key from the Scaleway console. +content: + h1: Disable a Key Manager key + paragraph: Discover how to disable a Key Manager key from the Scaleway console. +tags: key-manager disable key +dates: + validation: 2025-01-06 + posted: 2025-01-06 +categories: + - identity-and-access-management +--- + +This page shows you how to disable a Key Manager key which is enabled by default. Disabling a key renders it unusable for cryptographic operations by any user and application. + + + + +- A Scaleway account logged into the [console](https://console.scaleway.com) +- [Owner](/identity-and-access-management/iam/concepts/#owner) status or [IAM permissions](/identity-and-access-management/iam/concepts/#permission) allowing you to perform actions in the intended Organization +- [Created](/identity-and-access-management/key-manager/how-to/create-km-key/) a Key Manager key + +## How to disable a key + +1. Click Key Manager in the **Security and Identity section** of the [Scaleway console](https://console.scaleway.com) side menu. Your keys display. +2. Click the key you want to disable. +3. Scroll down to the **Key state** section, and click **Disable key**. + + Your key might be used by third-party programs. Disabling it could cause your services to stop working. You can enable your key again anytime. + +4. Click **Disable key** to confirm. diff --git a/identity-and-access-management/key-manager/how-to/index.mdx b/identity-and-access-management/key-manager/how-to/index.mdx new file mode 100644 index 0000000000..d0c2aa1fbc --- /dev/null +++ b/identity-and-access-management/key-manager/how-to/index.mdx @@ -0,0 +1,8 @@ +--- +meta: + title: Key Manager - How Tos + description: Key Manager How Tos +content: + h1: How Tos + paragraph: Key Manager How Tos +--- diff --git a/identity-and-access-management/key-manager/how-to/rotate-km-keys.mdx b/identity-and-access-management/key-manager/how-to/rotate-km-keys.mdx new file mode 100644 index 0000000000..70990beca3 --- /dev/null +++ b/identity-and-access-management/key-manager/how-to/rotate-km-keys.mdx @@ -0,0 +1,34 @@ +--- +meta: + title: Perform key rotation using the Scaleway console + description: Discover how to rotate a key from the Scaleway console to decrypt your data using Scaleway's Key Manager. +content: + h1: Perform key rotation using the Scaleway console + paragraph: Discover how to rotate a key from the Scaleway console to decrypt your data using Scaleway's Key Manager. +tags: key-manager encryption data key +dates: + validation: 2025-01-06 + posted: 2025-01-06 +categories: + - identity-and-access-management +--- + +Key rotation is a critical security practice that ensures that encryption keys are not reused for extended periods of time. Regularly rotating keys helps limit the number of messages encrypted with the same key version. + +This reduces the risk of exposure if a key is compromised, thus enhancing the overall security and resilience of your system. For symmetric encryption, it is generally recommended to rotate keys every 30 to 90 days. + + + +- A Scaleway account logged into the [console](https://console.scaleway.com) +- [Owner](/identity-and-access-management/iam/concepts/#owner) status or [IAM permissions](/identity-and-access-management/iam/concepts/#permission) allowing you to perform actions in the intended Organization +- [Created](/identity-and-access-management/key-manager/how-to/create-km-key/) a Key Manager key + +## How to perform key rotation + +1. Click Key Manager in the **Security and Identity section** of the [Scaleway console](https://console.scaleway.com) side menu. Your keys display. +2. Click the key you want to rotate. Your key's **Overview** tab displays. +3. Scroll down to the **Key rotation** section, and click **Rotate key**. A tooltip displays to confirm the rotation was performed. + + Rotating your key creates a new version of it. All cryptographic operations will use the new key rotation. All data encrypted with former key versions will remain decipherable with the former key. + +4. Check that your key was rotated under the **Current rotation** field in the **Key information** section. diff --git a/identity-and-access-management/key-manager/index.mdx b/identity-and-access-management/key-manager/index.mdx new file mode 100644 index 0000000000..7ca3a6d550 --- /dev/null +++ b/identity-and-access-management/key-manager/index.mdx @@ -0,0 +1,81 @@ +--- +meta: + title: Key Manager Documentation + description: Dive into Scaleway Key Manager with our quickstart guides, how-tos, and more. +--- + + + +## Getting Started + + + + + + + + +## API/CLI + + + + + + + + + +## Changelog + + diff --git a/identity-and-access-management/key-manager/quickstart.mdx b/identity-and-access-management/key-manager/quickstart.mdx new file mode 100644 index 0000000000..88631f22c2 --- /dev/null +++ b/identity-and-access-management/key-manager/quickstart.mdx @@ -0,0 +1,57 @@ +--- +meta: + title: Key Manager - Quickstart + description: Learn how to quickly set up and manage keys with Scaleway's Key Manager. Follow our step-by-step guide to create and manage keys. +content: + h1: Quickstart + paragraph: Learn how to quickly set up and manage keys with Scaleway's Key Manager. Follow our step-by-step guide to create and manage keys. +dates: + validation: 2025-01-06 + posted: 2025-01-06 +categories: + - identity-and-access-management +--- + +Scaleway's Key Manager allows you to create key encryption keys from the [Scaleway console](https://console.scaleway.com). Key encryption keys can then be used to encrypt and decrypt your encrypted data. + + + +- A Scaleway account logged into the [console](https://console.scaleway.com) +- [Owner](/identity-and-access-management/iam/concepts/#owner) status or [IAM permissions](/identity-and-access-management/iam/concepts/#permission) allowing you to perform actions in the intended Organization + +## How to create a Key Manager key + +1. Click Key Manager in the **Security and Identity section** of the [Scaleway console](https://console.scaleway.com) side menu. +2. Click **+ Create key**. +3. Choose the region in which you want to create your key. +4. Enter a name, a description, and optional tags for your key. +5. Select the [encryption method](/identity-and-access-management/key-manager/concepts/#encryption-method) for your key. + + + Key Manager currently only supports the `AES-256 GCM` [symmetric encryption](/identity-and-access-management/key-manager/concepts/#symmetric-encryption) algorithm. + +6. Switch the icon to disable [key protection](/identity-and-access-management/key-manager/concepts/#key-protection) or leave it enabled. + + Key protection allows you to protect your key from accidental deletion. + +7. Click **Create key**. Your key's **Overview** page displays. + +## How to create and manage a data encryption key (DEK) + + +1. Click Key Manager in the **Security and Identity section** of the [Scaleway console](https://console.scaleway.com) side menu. Your keys display. +2. Click the key for which to create a data encryption key. +3. Scroll down to the **Generate data encryption key** section. +4. Click **Generate data encryption key**. A pop-up displays with the [ciphertext](/identity-and-access-management/key-manager/concepts/#ciphertext) of your DEK. +5. Copy and store your DEK's ciphertext safely. + + - We recommend that you **always store the ciphertext** of your data encryption key rather than its [plaintext](/identity-and-access-management/key-manager/concepts/#plaintext). + - While Scaleway Key Manager is responsible for generating, encrypting, and decrypting data encryption keys, it does not store, manage, or monitor them, nor does it engage in cryptographic operations with these keys. **You must use and manage data encryption keys outside of Key Manager**. + - Read our [documentation](/identity-and-access-management/key-manager/reference-content/understanding-key-manager/) to understand Key Manager. + +6. Optionally, click **Display plaintext** to make sure that the plaintext does not contain any mistakes. +7. Click **Close**. + + + You are responsible for storing your DEKS, as Key Manager does not store them for you. + \ No newline at end of file diff --git a/identity-and-access-management/key-manager/reference-content/assets/scaleway-key-manager-schema.webp.png b/identity-and-access-management/key-manager/reference-content/assets/scaleway-key-manager-schema.webp.png new file mode 100644 index 0000000000..d1a9219d69 Binary files /dev/null and b/identity-and-access-management/key-manager/reference-content/assets/scaleway-key-manager-schema.webp.png differ diff --git a/identity-and-access-management/key-manager/reference-content/differences-key-and-secret-manager.mdx b/identity-and-access-management/key-manager/reference-content/differences-key-and-secret-manager.mdx new file mode 100644 index 0000000000..44529905c8 --- /dev/null +++ b/identity-and-access-management/key-manager/reference-content/differences-key-and-secret-manager.mdx @@ -0,0 +1,65 @@ +--- +meta: + title: Understanding the difference between Key Manager and Secret Manager + description: Discover the differences between Secret Manager and Key Manager, and learn which security tool best fits your data protection needs. +content: + h1: Understanding the difference between Key Manager and Secret Manager + paragraph: Discover the differences between Secret Manager and Key Manager, and learn which security tool best fits your data protection needs. +tags: key-manager secret-manager security +dates: + validation: 2025-01-06 + posted: 2025-01-06 +categories: + - identity-and-access-management +--- + + + +Secret Manager and Key Manager are both security-focused products aiming to help you protect your data and improve the security of your infrastructure. +The difference between the two of them is not always clear, and you may be unsure which one is most appropriate for your use-case. + +This page helps you answer that question. + + +## Secret Manager + +Secret Manager stores various secrets that your applications might need to access at some point. For example, when your application needs to call an external API service or connect to a database, it fetches the API token +or the credentials from Secret Manager before proceeding. + +Secrets can be largely anything you want: API tokens, credentials to connect to a database or simply sensitive data. There are no limits, other than the size of the secrets which is limited to 64 KiB. + + +## Key Manager + +In contrast, Key Manager only stores cryptographic keys. At first, Key Manager may seem to be just a limited version of Secret Manager, for keys only. + +It is indeed true that Secret Manager could also store cryptographic keys and hand them over to applications that need to perform cryptographic operations. + +However, this approach can lead to serious security problems such as: + + - inadvertently storing your keys in plaintext, or exposing them (e.g. in logs) + - incorrect (re-)use of keys: your application would be responsible for using the key correctly, + which is harder than it first seems. + - not disposing of the key properly after use (e.g. letting it reside in the swap disk) + +These are typical key management problems that are not effectively solved by Secret Manager, hence the need for Key Manager. + +Key Manager does **not** simply give you any requested key. All keys residing in Key Manager never (and never will) leave Key Manager, since +there is no way to extract them by design. + +Since you cannot extract keys, Key Manager performs the cryptographic operations for you. This means that your application supplies the plaintext to be encrypted, or +the ciphertext to be decrypted. Your application is no longer responsible for managing the keys and using them properly as Key Manager takes care of it. + +Last, but not least, Key Manager provides another way of authorizing certain actions. You might want to authorize some principals only to encrypt data, and others +only to decrypt data. + +Let us take the example of an application that receives sensitive health data that needs to be encrypted before being inserted into a database. The application would be able to ask Key Manager +to carry out encryption operations, but not decryption operations, so it cannot read the sensitive data already stored. + +This would not be possible to achieve with Secret Manager, since both writing and reading applications would need permissions to read the key from Secret Manager, which is sufficient to both encrypt and decrypt the data. + + +## Additional note + +Cryptographic keys are secrets that need special care, and Key Manager is an effective tool to help you manage them securely. Key Manager allows your applications to offload all sensitive cryptographic +operations and keep keys out-of-band for extra security. diff --git a/identity-and-access-management/key-manager/reference-content/security-recommendations.mdx b/identity-and-access-management/key-manager/reference-content/security-recommendations.mdx new file mode 100644 index 0000000000..ef55ec8e5c --- /dev/null +++ b/identity-and-access-management/key-manager/reference-content/security-recommendations.mdx @@ -0,0 +1,48 @@ +--- +meta: + title: Understanding security measures when using Key Manager + description: Learn best practices for secure key storage, DEK usage, and cost-efficient encryption with Scaleway Key Manager to protect your data effectively. +content: + h1: Understanding security measures when using Key Manager + paragraph: Learn best practices for secure key storage, DEK usage, and cost-efficient encryption with Scaleway Key Manager to protect your data effectively. +tags: key-manager security-measures security encryption decryption +dates: + validation: 2025-01-06 + posted: 2025-01-06 +categories: + - identity-and-access-management +--- + +## Key storage + +We strongly advise that you **never store data encryption keys (DEKs) in plaintext**. + +**Storing DEKs in plaintext poses a significant security risk** and defeats the purpose of using Key Manager or any key management service in the first place. + +You should always use your key encryption key (KEK) [created via Key Manager](/create-a-kek/) to encrypt and decrypt your DEKs. + + +## Key deletion + +Always **delete the plaintext version of your DEKs** after use. The key you should use to encrypt your DEKs securely is your KEK. + + +This practice is crucial for **maintaining the security of the encrypted data** by minimizing the time during which the plaintext DEKs are exposed and vulnerable to unauthorized access. + +## Use DEKs only once + +For **each piece of plaintext data that you want to encrypt**, you should generate a new, **unique DEK**, through Scaleway's Key Manager. + +Using a unique DEK for each piece of plaintext ensures that even if one DEK is compromised, it does not affect the security of other encrypted data. + +## Use Key Manger to encrypt your DEKs only + +While it is technically possible to encrypt and decrypt data directly in Key Manager (with a size limitation of up to 64 KB), **we do not advise that you use Key Manager this way**. + +Instead of using Key Manager for data encryption and decryption, you should use a data encryption key (DEK). + +This is recommended for two main reasons: + +- Performance: Encrypting and decrypting data directly with Key Manager can be less efficient compared to using a DEK, especially for larger volumes of data. + +- Economic: **Scaleway charges for each operation involving KEKs**. Using a DEK minimizes the number of operations you need to perform with the KEK, reducing costs. diff --git a/identity-and-access-management/key-manager/reference-content/understanding-key-manager.mdx b/identity-and-access-management/key-manager/reference-content/understanding-key-manager.mdx new file mode 100644 index 0000000000..ee656f10d3 --- /dev/null +++ b/identity-and-access-management/key-manager/reference-content/understanding-key-manager.mdx @@ -0,0 +1,101 @@ +--- +meta: + title: Understanding Scaleway Key Manager + description: Learn how Scaleway Key Manager secures your data with encryption hierarchies, key lifecycle management, and support for advanced cryptographic operations. +content: + h1: Understanding Scaleway Key Manager + paragraph: Learn how Scaleway Key Manager secures your data with encryption hierarchies, key lifecycle management, and support for advanced cryptographic operations. +tags: key-manager encryption data key +dates: + validation: 2025-01-15 + posted: 2025-01-15 +categories: + - identity-and-access-management +--- + +## How to use Key Manager? + +We recommend using the keys you store in Key Manager as [key encryption keys (KEK)](/identity-and-access-management/key-manager/concepts/#key-encryption-key-kek), and use them to encrypt and decrypt your [data encryption keys (DEK)](/identity-and-access-management/key-manager/concepts/#data-encryption-key-dek). We do not recommend storing your data encryption keys in Key Manager. + + + +## Why use data encryption keys? + +Unlike key encryption keys (KEK), which cannot be accessed, you can use data encryption keys (DEK) to encrypt your data. You can also use data encryption keys outside of Scaleway Key Manager. + +The main benefit of using DEKs is that you do not have to re-encrypt your data at each rotation performed in Key Manager. Only the DEK needs to be re-encrypted with a new KEK. + +By rotating solely the KEK, the security of data-at-rest is reinforced without needing heavy encryption operations. + +When Key Manager generates data encryption keys, a [plaintext](/identity-and-access-management/key-manager/concepts/#plaintext) version of your key is returned for immediate use, and a [ciphertext](/identity-and-access-management/key-manager/concepts/#ciphertext), which is an encrypted copy of the data encryption key, that you can safely store. + + + - Never store your data encryption key's plaintext. When you want to decrypt your data, you need to go through Key Manager to decrypt the encrypted DEK. Find out [how to decrypt your data with Tink](/identity-and-access-management/key-manager/api-cli/manage-keys-with-tink/). + - While Scaleway Key Manager is responsible for **generating, encrypting, and decrypting data encryption keys**, it **does not store, manage, or monitor them**, nor does it engage in cryptographic operations with these keys. **You must use and manage data encryption keys outside of Scaleway's Key Manager**. + + +## What is the difference between ciphertext and plaintext? + +[Ciphertext](/identity-and-access-management/key-manager/concepts/#ciphertext) and [plaintext](/identity-and-access-management/key-manager/concepts/#plaintext) are two fundamental terms in encryption. + +Plaintext refers to data in its original, readable form, such as a message, document, or file, that has not been encrypted. + +It is the information as it appears before any encryption process or after decryption. + +Ciphertext is the result of applying an encryption algorithm to plaintext. It is the scrambled, unreadable version of the data that is secure from unauthorized access. + +While plaintext can be understood directly by humans or computers, ciphertext requires a decryption key to convert it back into plaintext. This transformation between plaintext and ciphertext ensures the confidentiality of information during storage or transmission, protecting it from being intercepted or read by unauthorized parties. + +## Which cryptographic operations does Key Manager support? + +Key Manager supports the three following cryptographic operations: + +- [Encryption](/identity-and-access-management/key-manager/concepts/#encryption) +- [Decryption](/identity-and-access-management/key-manager/concepts/#decryption) +- [Data encryption key](/identity-and-access-management/key-manager/concepts/#data-encryption-key-dek) generation + +## Management methods you can use with Key Manager + +Key Manager allows you to create and manage the complete lifecycle of your keys. Below are all the ways you can use Key Manager to manage your data. + +- Create a key: You must specify a [key usage](/identity-and-access-management/key-manager/concepts/#key-usage), which defines the **purpose of the key** (encryption, signing, etc.) and which [encryption algorithm](/identity-and-access-management/key-manager/concepts/#encryption-algorithm) will be used to derive the key. + +Upon key creation, Key Manager automatically creates a first key version. + +- Retrieve a key: Retrieving a key **only returns the metadata associated with the key**, not the [key versions](/identity-and-access-management/key-manager/concepts/#key-version). + +- List keys: You can retrieve a subset of your keys according to filters such as "name", "description", "tags", etc. + +- Update a key: You can update the key's name, description or tags at any time. + +- Enable and disable key protection: **Enabling key protection prevents accidental deletion of a key**. You must disable key protection before deleting a key to which key protection is applied. + +- Rotate a key: Rotating a key **creates a new key version and makes all previous versions obsolete**. + +- Delete a key: Deleting a key also **deletes all its versions**. All data encrypted using the key, including data encryption keys, will become unusable. + +## Key usage and algorithms + +The key usage specifies the [encryption algorithm](/identity-and-access-management/key-manager/concepts/#encryption-algorithm) used to create subsequent key versions, and the **scope of cryptographic operations** supported by the key. + +Keys with a key usage set to `symmetric_encryption` are **used to encrypt and decrypt data**. + + + +The following parameters, in compliance with the [recommendations of ANSSI](https://cyber.gouv.fr/publications/mecanismes-cryptographiques), are used when creating and using a key with the `AES-256 GCM` [encryption scheme](/identity-and-access-management/key-manager/concepts/#encryption-scheme). + +### Key derivation algorithm + +Key Manager uses HMAC-based Extract-and-Expand Key Derivation Function (HKDF) as defined in [RFC 5869](https://datatracker.ietf.org/doc/html/rfc5869) with [SHA-256](https://www.rfc-editor.org/rfc/rfc4868.html#section-2) as the hash function. + +### Key material + +Key Manager generates a 256-bit key using a cryptographically secure random number generator that draws entropy from the `/dev/urandom` source. This key is then used in a key derivation algorithm to generate a new key version. + +### Key version length + +The key version has a length of 256 bits, ensuring strong cryptographic security. + +### Block cipher + +For encryption, Key Manager uses the Galois/Counter Mode (GCM), which is a mode of operation for block ciphers, with a block size of 128 bits. GCM encrypts your plaintext data using AES, and authenticates it using a unique "tag". This means that if anyone tampers with your data, you will know because the tag will not match anymore. diff --git a/macros/key-manager/encryption.mdx b/macros/key-manager/encryption.mdx new file mode 100644 index 0000000000..51b88c08cb --- /dev/null +++ b/macros/key-manager/encryption.mdx @@ -0,0 +1,5 @@ +--- +macro: key-manager-encryption +--- + +**Key Manager only supports the `AES-256-GCM` [encryption scheme](/identity-and-access-management/key-manager/concepts/#encryption-scheme).** \ No newline at end of file diff --git a/menu/navigation.json b/menu/navigation.json index 878229680e..421ab3b016 100644 --- a/menu/navigation.json +++ b/menu/navigation.json @@ -493,6 +493,102 @@ "label": "Audit Trail", "slug": "audit-trail" }, + { + "items": [ + { + "label": "Overview", + "slug": "../key-manager" + }, + { + "label": "Concepts", + "slug": "concepts" + }, + { + "label": "Quickstart", + "slug": "quickstart" + }, + { + "label": "FAQ", + "slug": "../../faq/key-manager" + }, + { + "items": [ + { + "label": "Create a Key Manager key", + "slug": "create-km-key" + }, + { + "label": "Create and manage a Key Manager data encryption key", + "slug": "create-manage-dek" + }, + { + "label": "Perform key rotation on Key Manager keys", + "slug": "rotate-km-keys" + }, + { + "label": "Disable Key Manager keys", + "slug": "disable-km-key" + }, + { + "label": "Delete Key Manager keys", + "slug": "delete-km-key" + } + ], + "label": "How to", + "slug": "how-to" + }, + { + "items": [ + { + "label": "Understanding security measures when using Key Manager", + "slug": "security-recommendations" + }, + { + "label": "Understanding Key Manager", + "slug": "understanding-key-manager" + }, + { + "label": "Understanding the difference between Key Manager and Secret Manager", + "slug": "differences-key-and-secret-manager" + } + ], + "label": "Additional Content", + "slug": "reference-content" + }, + { + "items": [ + { + "label": "Key Manager API Reference", + "slug": "https://www.scaleway.com/en/developers/api/key-manager/" + }, + { + "label": "Creating a data encryption key using the Scaleway API and the Scaleway CLI", + "slug": "create-dek-api-cli" + }, + { + "label": "Managing your Key Manager keys using Tink", + "slug": "manage-keys-with-tink" + }, + { + "label": "Perform key rotation using the Scaleway CLI and API", + "slug": "rotate-keys-api-cli" + }, + { + "label": "Encrypting and decrypting data with a Key Manager data encryption key", + "slug": "encrypt-decrypt-data-with-km-dek" + }, + { + "label": "Encrypting and decrypting data streams with Streaming AEAD, Tink and Key Manager", + "slug": "encrypt-decrypt-keys-with-streaming-aead-tink" + } + ], + "label": "API/CLI", + "slug": "api-cli" + } + ], + "label": "Key Manager", + "slug": "key-manager" + }, { "items": [ {