feat(key_manager): add documentation about creating and verify digital signatures

Author: Mélanie Marques

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",

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.
+
+
+<Message type="warning">
+    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/)
+</Message>
+
+## 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="<API-ACCESS-KEY>"
+  export SCW_SECRET_KEY="<API-SECRET-KEY>"
+  export SCW_DEFAULT_ORGANIZATION_ID="<Scaleway-Organization-ID>"
+  export SCW_DEFAULT_REGION="<region>"
+  export SCW_API_URL="<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
+}
+```
+
+<Message type="note">
+    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`).
+</Message>
+
+## 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
+}
+```

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="<API-ACCESS-KEY>"
+  export SCW_SECRET_KEY="<API-SECRET-KEY>"
+  export SCW_DEFAULT_ORGANIZATION_ID="<Scaleway-Organization-ID>"
+  export SCW_DEFAULT_REGION="<region>"
+  export SCW_API_URL="<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
+}
+```