From 905eaf0558969d0fc669ee6f2702b03ea924de13 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?M=C3=A9lanie=20Marques?= Date: Wed, 14 May 2025 15:15:58 +0200 Subject: [PATCH 1/4] feat(key_manager): add documentation about creating and verify digital signatures --- menu/navigation.json | 8 ++ ...ypt-decrypt-asymmetric-key-with-go-sdk.mdx | 131 ++++++++++++++++++ .../api-cli/sign-verify-key-with-go-sdk.mdx | 124 +++++++++++++++++ 3 files changed, 263 insertions(+) create mode 100644 pages/key-manager/api-cli/encrypt-decrypt-asymmetric-key-with-go-sdk.mdx create mode 100644 pages/key-manager/api-cli/sign-verify-key-with-go-sdk.mdx diff --git a/menu/navigation.json b/menu/navigation.json index 335ac1e083..14d8d13305 100644 --- a/menu/navigation.json +++ b/menu/navigation.json @@ -730,6 +730,14 @@ { "label": "Encrypting and decrypting data streams with Streaming AEAD, Tink and Key Manager", "slug": "encrypt-decrypt-keys-with-streaming-aead-tink" + }, + { + "label": "Encrypting and decrypting data with an asymmetric key", + "slug": "encrypt-decrypt-asymmetric-key-with-go-sdk" + }, + { + "label": "Create and validate signatures using Scaleway Go SDK and Key Manager", + "slug": "sign-verify-key-with-go-sdk" } ], "label": "API/CLI", diff --git a/pages/key-manager/api-cli/encrypt-decrypt-asymmetric-key-with-go-sdk.mdx b/pages/key-manager/api-cli/encrypt-decrypt-asymmetric-key-with-go-sdk.mdx new file mode 100644 index 0000000000..da9140ac54 --- /dev/null +++ b/pages/key-manager/api-cli/encrypt-decrypt-asymmetric-key-with-go-sdk.mdx @@ -0,0 +1,131 @@ +h1: Encrypting and decrypting data with an asymmetric key +paragraph: Learn how to encrypt and decrypt data with an asymmetric key using Key Manager with Scaleway Go SDK. +tags: key sensitive-data encrypt decrypt asymmetric digest +dates: +validation: 2025-02-06 +posted: 2025-02-06 +--- + +Scaleway's Key Manager provides a secure way to manage asymmetric keys, allowing you to offload sensitive cryptographic +operations to a managed service. In this guide, you'll learn how to integrate the Scaleway Go SDK to encrypt and decrypt +data using an rsa_oaep_3072_sha256 key directly through the Key Manager API. + + + + Please note that we do not recommend using asymmetric encryption for anything other than key encryption. + For all other purposes (eg. encrypting large data or files), we recommend using Tink with Scaleway's Key Manager as explained [here.](/key-manager/api-cli/encrypt-decrypt-data-with-km-dek/) + + +## 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. + + ```bash + export SCW_ACCESS_KEY="" + export SCW_SECRET_KEY="" + export SCW_DEFAULT_ORGANIZATION_ID="" + export SCW_DEFAULT_REGION="" + export SCW_API_URL="" + ``` + +## Encrypt data + +This operation takes place locally, ensuring the plaintext message never leaves your environment unprotected. +The public key can be fetched using the Key Manager API, parsed, and used to encrypt data with RSA-OAEP and SHA-256 padding. + +```golang +// encryptAsymmetric encrypts data on your local machine using an 'rsa_oaep_3072_sha256' key retrieved from Scaleway KMS. +// +// Parameters: +// - keyID: The unique identifier of the asymmetric key stored in Scaleway KMS. +// - message: The plaintext message that needs to be encrypted. +// +// Returns: +// - error: An error if the encryption process fails, otherwise nil. +func encryptAsymmetric(keyID string, message string) error { + // Initialize the Scaleway client + client, err := scw.NewClient(scw.WithEnv()) + if err != nil { + panic(err) + } + kmsApi := key_manager.NewAPI(client) + + // Retrieve the public key from Scaleway KMS. + response, err := kmsApi.GetPublicKey(&key_manager.GetPublicKeyRequest{ + KeyID: keyID, + }) + if err != nil { + return fmt.Errorf("failed to get public key: %w", err) + } + + // Parse the public key. Note, this example assumes the public key is in the + // RSA format. + block, _ := pem.Decode([]byte(response.Pem)) + publicKey, err := x509.ParsePKCS1PublicKey(block.Bytes) + if err != nil { + return fmt.Errorf("failed to parse public key: %w", err) + } + + // Convert the message into bytes. Cryptographic plaintexts and + // ciphertexts are always byte arrays. + plaintext := []byte(message) + + // Encrypt data using the RSA public key. + ciphertext, err := rsa.EncryptOAEP(sha256.New(), rand.Reader, publicKey, plaintext, nil) + if err != nil { + return fmt.Errorf("rsa.EncryptOAEP: %w", err) + } + + fmt.Printf("Encrypted ciphertext: %s\n", ciphertext) + return nil +} +``` + + + Please note that : + - Encryption can also be performed using the Scaleway's Key Manager Encrypt method. + - In the case of asymmetric encryption, the maximum payload size allowed depends on the key algo (190 bytes for `RSA_OAEP_2048_SHA256`, 318 bytes for `RSA_OAEP_3072_SHA256` and 446 bytes for `RSA_OAEP_4096_SHA256`). + + +## Decrypt data + +To retrieve the original message, you must send the encrypted ciphertext to Scaleway Key Manager, +which uses the private portion of the asymmetric key to decrypt it. This ensures your private key remains secure within +Scaleway’s infrastructure. + +```golang + +// decryptAsymmetric attempts to decrypt a given ciphertext using an 'rsa_oaep_3072_sha256' key from Scaleway KMS. +// +// Parameters: +// - keyID: The unique identifier of the asymmetric key stored in Scaleway KMS. +// - ciphertext: The encrypted data that needs to be decrypted. +// +// Returns: +// - error: An error if the decryption process fails, otherwise nil. +func decryptAsymmetric(keyID string, ciphertext []byte) error { + // Initialize the Scaleway client + client, err := scw.NewClient(scw.WithEnv()) + if err != nil { + panic(err) + } + kmsApi := key_manager.NewAPI(client) + + // Build the request. + req := &key_manager.DecryptRequest{ + KeyID: keyID, + Ciphertext: ciphertext, + } + + // Call the API. + result, err := kmsApi.Decrypt(req) + if err != nil { + return fmt.Errorf("failed to decrypt ciphertext: %w", err) + } + + fmt.Printf("Decrypted plaintext: %s", result.Plaintext) + return nil +} +``` \ No newline at end of file diff --git a/pages/key-manager/api-cli/sign-verify-key-with-go-sdk.mdx b/pages/key-manager/api-cli/sign-verify-key-with-go-sdk.mdx new file mode 100644 index 0000000000..8a258f54d9 --- /dev/null +++ b/pages/key-manager/api-cli/sign-verify-key-with-go-sdk.mdx @@ -0,0 +1,124 @@ +--- +meta: +title: Create and validate signatures using Scaleway Go SDK and Key Manager +description: Learn how to create and validate signature using Key Manager with Scaleway Go SDK. +content: +h1: Create and validate signatures using Scaleway Go SDK and Key Manager +paragraph: Learn how to create and validate signature using Key Manager with Scaleway Go SDK. +tags: key sensitive-data signature verification sign verify digest +dates: +validation: 2025-02-06 +posted: 2025-02-06 +--- + +This page shows you how to perform asymmetric signing and verification using Scaleway Key Manager (KMS). + +In this tutorial, we will walk you through setting up your environment to interact with the Scaleway API and Key Manager, +and then demonstrate how to sign and verify messages using asymmetric keys. + +## 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. + + ```bash + export SCW_ACCESS_KEY="" + export SCW_SECRET_KEY="" + export SCW_DEFAULT_ORGANIZATION_ID="" + export SCW_DEFAULT_REGION="" + export SCW_API_URL="" + ``` + +## Creating a signature + +```golang +// signAsymmetric signs a plaintext message using a saved asymmetric private key 'ec_p256_sha256' +// stored in Scaleway Key Manager. +// +// Parameters: +// - keyID: The unique identifier of the asymmetric key stored in Scaleway Key Manager. +// - message: The plaintext message that needs to be signed. +// +// Returns: +// - err: An error if the signing process fails, otherwise nil. +func signAsymmetric(keyID string, message string) error { + // Initialize the Scaleway client + client, err := scw.NewClient(scw.WithEnv()) + if err != nil { + panic(err) + } + kmsApi := key_manager.NewAPI(client) + + // Convert the message into bytes. Cryptographic plaintexts and ciphertexts are always byte arrays. + plaintext := []byte(message) + + // Calculate the digest of the message. + // Note: Digest algorithm must match the key algorithm. + // - Use SHA-256 for most algorithms (e.g., RSA_OAEP_3072_SHA256, EC_P256_SHA256). + // - Use SHA-384 **only** for ECC_P384_SHA384. + digest := sha256.New() + if _, err = digest.Write(plaintext); err != nil { + return fmt.Errorf("failed to create digest: %w", err) + } + + // Build the signing request. + req := &key_manager.SignRequest{ + Digest: digest.Sum(nil), + KeyID: keyID, + } + + // Call the API + response, err = kmsApi.Sign(req) + if err != nil { + return fmt.Errorf("failed to sign digest: %w", err) + } + + fmt.Printf("Signed digest: %s", response.Signature) + return nil +} +``` + +## Validating an elliptic curve signature + +```golang +// verifyAsymmetricSignature verifies that an 'ec_p256_sha256' signature is valid for a given message. +// +// Parameters: +// - keyID: The unique identifier of the asymmetric key stored in Scaleway Key Manager. +// - message: The plaintext message that was originally signed. +// - signature: The signature obtained from a previous sign request. +// +// Returns: +// - error: An error if the verification process fails or if the signature is invalid, otherwise nil. +func verifyAsymmetricSignature(keyID string, message, signature []byte) error { + // Initialize the Scaleway client + client, err := scw.NewClient(scw.WithEnv()) + if err != nil { + panic(err) + } + kmsApi := key_manager.NewAPI(client) + + // Verify signature. + // Calculate the digest of the message. + digest := sha256.New() + if _, err = digest.Write(message); err != nil { + return fmt.Errorf("failed to create digest: %w", err) + } + + verify, err := kmsApi.Verify(&key_manager.VerifyRequest{ + KeyID: keyID, + Digest: digest.Sum(nil), + Signature: signature, + }) + if err != nil { + return err + } + + if verify.Valid { + fmt.Printf("Verified signature!") + } + + return nil +} +``` \ No newline at end of file From a1e3d8f267c72c419fc8c77ac2bc53dac9afd300 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?N=C3=A9da?= <87707325+nerda-codes@users.noreply.github.com> Date: Tue, 27 May 2025 13:48:30 +0200 Subject: [PATCH 2/4] docs(review): menu titles --- menu/navigation.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/menu/navigation.json b/menu/navigation.json index 14d8d13305..0139ebfde1 100644 --- a/menu/navigation.json +++ b/menu/navigation.json @@ -736,7 +736,7 @@ "slug": "encrypt-decrypt-asymmetric-key-with-go-sdk" }, { - "label": "Create and validate signatures using Scaleway Go SDK and Key Manager", + "label": "Managing signatures using the Scaleway Go SDK and Key Manager", "slug": "sign-verify-key-with-go-sdk" } ], From c40f42d0ea1ac14de6e480273d5d297243e77ce9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?N=C3=A9da?= <87707325+nerda-codes@users.noreply.github.com> Date: Tue, 27 May 2025 14:01:46 +0200 Subject: [PATCH 3/4] docs(review): review of en/decrypting data with asym key --- ...ypt-decrypt-asymmetric-key-with-go-sdk.mdx | 55 ++++++++++--------- 1 file changed, 29 insertions(+), 26 deletions(-) diff --git a/pages/key-manager/api-cli/encrypt-decrypt-asymmetric-key-with-go-sdk.mdx b/pages/key-manager/api-cli/encrypt-decrypt-asymmetric-key-with-go-sdk.mdx index da9140ac54..f4d6ba0d9b 100644 --- a/pages/key-manager/api-cli/encrypt-decrypt-asymmetric-key-with-go-sdk.mdx +++ b/pages/key-manager/api-cli/encrypt-decrypt-asymmetric-key-with-go-sdk.mdx @@ -1,19 +1,22 @@ -h1: Encrypting and decrypting data with an asymmetric key -paragraph: Learn how to encrypt and decrypt data with an asymmetric key using Key Manager with Scaleway Go SDK. +--- +meta: + title: Encrypting and decrypting data with an asymmetric key + description: Learn how to encrypt and decrypt data with an asymmetric key using Key Manager and the Scaleway Go SDK. +content: + h1: Encrypting and decrypting data with an asymmetric key + paragraph: Learn how to encrypt and decrypt data with an asymmetric key using Key Manager and the Scaleway Go SDK. tags: key sensitive-data encrypt decrypt asymmetric digest dates: -validation: 2025-02-06 -posted: 2025-02-06 + validation: 2025-05-27 + posted: 2025-05-27 --- -Scaleway's Key Manager provides a secure way to manage asymmetric keys, allowing you to offload sensitive cryptographic -operations to a managed service. In this guide, you'll learn how to integrate the Scaleway Go SDK to encrypt and decrypt -data using an rsa_oaep_3072_sha256 key directly through the Key Manager API. +Scaleway's Key Manager provides a secure way to manage asymmetric keys, allowing you to offload sensitive cryptographic operations to a managed service. This documentation page shows you how to integrate the Scaleway Go SDK to encrypt and decrypt data using an `rsa_oaep_3072_sha256` key directly through the [Key Manager API](https://www.scaleway.com/en/developers/api/key-manager/). - - Please note that we do not recommend using asymmetric encryption for anything other than key encryption. - For all other purposes (eg. encrypting large data or files), we recommend using Tink with Scaleway's Key Manager as explained [here.](/key-manager/api-cli/encrypt-decrypt-data-with-km-dek/) + + We do not recommend using asymmetric encryption for anything other than key encryption. + For all other purposes (encrypting large data or files), we recommend using Tink with Scaleway's Key Manager as explained [in the dedicated documentation](/key-manager/api-cli/encrypt-decrypt-data-with-km-dek/). ## Configuring your environment variables @@ -30,16 +33,15 @@ Open a terminal and paste the following commands to export your environment vari export SCW_API_URL="" ``` -## Encrypt data +## Encrypting data -This operation takes place locally, ensuring the plaintext message never leaves your environment unprotected. -The public key can be fetched using the Key Manager API, parsed, and used to encrypt data with RSA-OAEP and SHA-256 padding. +This operation takes place locally, ensuring the plaintext message never leaves your environment unprotected. The public key can be fetched using the Key Manager API, parsed, and used to encrypt data with RSA-OAEP and SHA-256 padding. ```golang -// encryptAsymmetric encrypts data on your local machine using an 'rsa_oaep_3072_sha256' key retrieved from Scaleway KMS. +// encryptAsymmetric encrypts data on your local machine using an 'rsa_oaep_3072_sha256' key retrieved from Scaleway Key Manager. // // Parameters: -// - keyID: The unique identifier of the asymmetric key stored in Scaleway KMS. +// - keyID: The unique identifier of the asymmetric key stored in Key Manager. // - message: The plaintext message that needs to be encrypted. // // Returns: @@ -52,7 +54,7 @@ func encryptAsymmetric(keyID string, message string) error { } kmsApi := key_manager.NewAPI(client) - // Retrieve the public key from Scaleway KMS. + // Retrieve the public key from Key Manager. response, err := kmsApi.GetPublicKey(&key_manager.GetPublicKeyRequest{ KeyID: keyID, }) @@ -60,7 +62,7 @@ func encryptAsymmetric(keyID string, message string) error { return fmt.Errorf("failed to get public key: %w", err) } - // Parse the public key. Note, this example assumes the public key is in the + // Parse the public key. This example assumes the public key is in the // RSA format. block, _ := pem.Decode([]byte(response.Pem)) publicKey, err := x509.ParsePKCS1PublicKey(block.Bytes) @@ -84,23 +86,24 @@ func encryptAsymmetric(keyID string, message string) error { ``` - Please note that : - - Encryption can also be performed using the Scaleway's Key Manager Encrypt method. - - In the case of asymmetric encryption, the maximum payload size allowed depends on the key algo (190 bytes for `RSA_OAEP_2048_SHA256`, 318 bytes for `RSA_OAEP_3072_SHA256` and 446 bytes for `RSA_OAEP_4096_SHA256`). + - Encryption can also be performed using the [encrypt method of the Key Manager API](https://www.scaleway.com/en/developers/api/key-manager/#path-keys-encrypt-a-payload). + - For asymmetric encryption, the maximum payload size allowed depends on the key algorithm used: + - 190 bytes for `RSA_OAEP_2048_SHA256` + - 318 bytes for `RSA_OAEP_3072_SHA256` and + - 446 bytes for `RSA_OAEP_4096_SHA256`) -## Decrypt data +## Decrypting data -To retrieve the original message, you must send the encrypted ciphertext to Scaleway Key Manager, -which uses the private portion of the asymmetric key to decrypt it. This ensures your private key remains secure within +To retrieve the original message, you must send the encrypted ciphertext to Scaleway Key Manager, which uses the private portion of the asymmetric key to decrypt it. This ensures your private key remains secure within Scaleway’s infrastructure. ```golang -// decryptAsymmetric attempts to decrypt a given ciphertext using an 'rsa_oaep_3072_sha256' key from Scaleway KMS. +// decryptAsymmetric attempts to decrypt a given ciphertext using an 'rsa_oaep_3072_sha256' key from Key Manager. // // Parameters: -// - keyID: The unique identifier of the asymmetric key stored in Scaleway KMS. +// - keyID: The unique identifier of the asymmetric key stored in Key Manager. // - ciphertext: The encrypted data that needs to be decrypted. // // Returns: @@ -128,4 +131,4 @@ func decryptAsymmetric(keyID string, ciphertext []byte) error { fmt.Printf("Decrypted plaintext: %s", result.Plaintext) return nil } -``` \ No newline at end of file +``` From 41450042d938be6463ca9d6f7dd8f75e14509185 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?N=C3=A9da?= <87707325+nerda-codes@users.noreply.github.com> Date: Tue, 27 May 2025 14:18:04 +0200 Subject: [PATCH 4/4] Update sign-verify-key-with-go-sdk.mdx --- .../api-cli/sign-verify-key-with-go-sdk.mdx | 27 +++++++++---------- 1 file changed, 12 insertions(+), 15 deletions(-) diff --git a/pages/key-manager/api-cli/sign-verify-key-with-go-sdk.mdx b/pages/key-manager/api-cli/sign-verify-key-with-go-sdk.mdx index 8a258f54d9..45fb4dc21d 100644 --- a/pages/key-manager/api-cli/sign-verify-key-with-go-sdk.mdx +++ b/pages/key-manager/api-cli/sign-verify-key-with-go-sdk.mdx @@ -1,24 +1,21 @@ --- meta: -title: Create and validate signatures using Scaleway Go SDK and Key Manager -description: Learn how to create and validate signature using Key Manager with Scaleway Go SDK. + title: Managing signatures using the Scaleway Go SDK and Key Manager + description: Learn how to create and validate signatures using Key Manager with the Scaleway Go SDK. content: -h1: Create and validate signatures using Scaleway Go SDK and Key Manager -paragraph: Learn how to create and validate signature using Key Manager with Scaleway Go SDK. + h1: Managing signatures using the Scaleway Go SDK and Key Manager + paragraph: Learn how to create and validate signatures using Key Manager with the Scaleway Go SDK. tags: key sensitive-data signature verification sign verify digest dates: -validation: 2025-02-06 -posted: 2025-02-06 + validation: 2025-05-27 + posted: 2025-05-27 --- -This page shows you how to perform asymmetric signing and verification using Scaleway Key Manager (KMS). - -In this tutorial, we will walk you through setting up your environment to interact with the Scaleway API and Key Manager, -and then demonstrate how to sign and verify messages using asymmetric keys. +This page shows you how to perform asymmetric signing and verification using Scaleway Key Manager. This documentation page shows you how to set up your environment to interact with the Scaleway API and Key Manager, and sign and verify messages using asymmetric keys. ## Configuring your environment variables -Configuring your environment variables allows the Go application to authenticate and use Scaleway's API and Key Manager. +Configuring your environment variables allows the Go application to authenticate and use the Scaleway 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. @@ -34,10 +31,10 @@ Open a terminal and paste the following commands to export your environment vari ```golang // signAsymmetric signs a plaintext message using a saved asymmetric private key 'ec_p256_sha256' -// stored in Scaleway Key Manager. +// stored in Key Manager. // // Parameters: -// - keyID: The unique identifier of the asymmetric key stored in Scaleway Key Manager. +// - keyID: The unique identifier of the asymmetric key stored in Key Manager. // - message: The plaintext message that needs to be signed. // // Returns: @@ -79,7 +76,7 @@ func signAsymmetric(keyID string, message string) error { } ``` -## Validating an elliptic curve signature +## Validating the signature ```golang // verifyAsymmetricSignature verifies that an 'ec_p256_sha256' signature is valid for a given message. @@ -121,4 +118,4 @@ func verifyAsymmetricSignature(keyID string, message, signature []byte) error { return nil } -``` \ No newline at end of file +```