Cette opération chiffre un texte clair en texte chiffré à l'aide de la version principale d'une clé symétrique dans une instance de gestion logicielle des clés Key Management Service (KMS).
Description de l'opération
Les opérations AdvanceEncrypt et Encrypt chiffrent toutes deux un texte clair en texte chiffré, mais diffèrent par la version de clé utilisée et par l'opération de déchiffrement compatible :
| AdvanceEncrypt | **Encrypt** | |
|---|---|---|
| Version de clé utilisée | Version principale | Version initiale |
| Opération de déchiffrement compatible | AdvanceDecrypt uniquement | Decrypt ou AdvanceDecrypt |
Si la rotation automatique des clés est activée, utilisez AdvanceEncrypt plutôt que Encrypt pour garantir le bon fonctionnement de la rotation des clés. Pour plus d'informations, consultez la rubrique Configure key rotation.
Cette opération est prise en charge uniquement pour les clés symétriques dans les instances de gestion logicielle des clés KMS. Pour connaître les spécifications de clés, les algorithmes de chiffrement et les versions de clés pris en charge, consultez la rubrique Key types and specifications.
Notes d'utilisation
Le corps de la requête ne doit pas dépasser 3 Mo après encodage avec Protocol Buffers. En cas de dépassement, le serveur renvoie une erreur HTTP 413. Limitez la taille des données à 6 Ko par opération. Pour les charges utiles plus volumineuses, utilisez le envelope encryption.
Des charges utiles volumineuses augmentent le risque d'échecs réseau, prolongent le temps de transmission et ralentissent les opérations de chiffrement et de déchiffrement KMS.
Paramètres de requête
| Paramètre | Type | Obligatoire | Exemple | Description |
|---|---|---|---|---|
| KeyId | string | Oui | key-hzz62f1cb66fa42qo**** | L'ID global unique de la clé, ou un alias lié à la clé. La clé doit être une clé symétrique dans une instance de gestion logicielle des clés KMS. |
| Plaintext | bytes | Oui | Données binaires | Le texte clair à chiffrer. |
| Algorithm | string | Non | AES_GCM | L'algorithme de chiffrement. Par défaut, l'algorithme défini pour la clé est utilisé si ce paramètre n'est pas défini. Pour connaître les valeurs prises en charge, consultez la rubrique Key types and specifications. |
| Iv | bytes | Non | Données binaires | Le vecteur d'initialisation (IV). S'applique uniquement lorsque Algorithm est AES_GCM ou AES_CBC. Si ce paramètre n'est pas défini, KMS génère une valeur aléatoire. Longueurs valides : 12 octets pour AES_GCM, 16 octets pour AES_CBC. Important Nous vous recommandons de ne pas définir ce paramètre. |
| Aad | binary | Non | Données binaires | Les données authentifiées supplémentaires (AAD) pour le mode GCM. S'applique uniquement lorsque Algorithm est AES_GCM, et est facultatif selon vos besoins métier. Si ce paramètre est défini, transmettez la même valeur lors de l'appel à AdvanceDecrypt. |
| PaddingMode | string | Non | PKCS7_PADDING | Le mode de remplissage. Requis uniquement lorsque Algorithm est AES_CBC ou AES_ECB. Valeurs valides : PKCS7_PADDING (par défaut) et NO_PADDING. Avec PKCS7_PADDING, le système remplit l'entrée avec K-(L mod K) octets, où K est la taille du bloc de chiffrement et L la longueur de l'entrée. Avec NO_PADDING, la longueur du texte clair doit être un multiple entier de la taille du bloc de chiffrement. |
Paramètres de réponse
| Paramètre | Type | Exemple | Description |
|---|---|---|---|
| CiphertextBlob | bytes | Données binaires | Le texte chiffré. Contient des métadonnées intégrées pour KeyId, Algorithm, PaddingMode et Iv ; transmettez uniquement CiphertextBlob lors de l'appel à AdvanceDecrypt. |
| Algorithm | string | AES_GCM | L'algorithme de chiffrement utilisé. |
| KeyId | string | key-hzz62f1cb66fa42qo**** | L'ID global unique de la clé. Si vous avez transmis un alias dans la requête, l'ID de la clé à laquelle l'alias est lié est renvoyé. |
| KeyVersionId | string | key-hzz62f1cb66fa42qopd9s-17kedv**** | La version de clé utilisée pour chiffrer les données. Il s'agit toujours de la version principale. |
| Iv | bytes | Données binaires | Le vecteur d'initialisation utilisé. Renvoyé uniquement lorsque Algorithm est AES_GCM ou AES_CBC ; vide sinon. |
| PaddingMode | string | PKCS7_PADDING | Le mode de remplissage utilisé. Renvoyé uniquement lorsque Algorithm est AES_CBC ou AES_ECB ; vide sinon. |
| RequestId | string | c0037a6d-7784-4ef2-a692-288fdefc7b9d | L'ID de la requête, utilisé pour localiser et résoudre les problèmes. |
Codes d'erreur
| Code d'état HTTP | Code d'erreur | Message d'erreur | Description |
|---|---|---|---|
| 404 | Forbidden.OnlySymmetricKeySupported | The key %s is not a symmetric key. The API only supports symmetric keys. | La clé spécifiée n'est pas une clé symétrique. Les clés asymétriques sont utilisées pour le chiffrement de données entre domaines de sécurité ou pour l'échange de clés, où KMS n'est pas impliqué d'un côté. |
Pour obtenir la liste complète des codes d'erreur, consultez la rubrique Service error codes.