Cifra texto sin formato en texto cifrado mediante la versión principal de una clave simétrica en una instancia de gestión de claves de software de Key Management Service (KMS).
Descripción de la operación
Tanto AdvanceEncrypt como Encrypt cifran texto sin formato en texto cifrado, pero difieren en la versión de la clave que utilizan y en la operación de descifrado compatible:
|
AdvanceEncrypt |
**Encrypt** |
|
|
Versión de clave utilizada |
Versión principal |
Versión inicial |
|
Operación de descifrado compatible |
Solo AdvanceDecrypt |
Si la rotación automática de claves está habilitada, utilice AdvanceEncrypt en lugar de Encrypt para garantizar el funcionamiento correcto de esta función. Para obtener más información, consulte Configure key rotation.
Esta operación solo es compatible con claves simétricas en instancias de gestión de claves de software de KMS. Para consultar las especificaciones de clave, los algoritmos de cifrado y las versiones de clave compatibles, consulte Key types and specifications.
Notas de uso
El cuerpo de la solicitud no debe exceder los 3 MB después de codificarse con Protocol Buffers. Si se supera este límite, el servidor devuelve un error HTTP 413. Limite el tamaño de los datos a 6 KB por operación. Para cargas útiles más grandes, utilice envelope encryption.
Las cargas útiles grandes incrementan el riesgo de fallos en la red, prolongan el tiempo de transmisión y ralentizan las operaciones de cifrado y descifrado de KMS.
Parámetros de solicitud
| Parámetro | Tipo | Obligatorio | Ejemplo | Descripción |
|---|---|---|---|---|
| KeyId | string | Sí | key-hzz62f1cb66fa42qo**** | Identificador único global de la clave o alias vinculado a ella. La clave debe ser simétrica y pertenecer a una instancia de gestión de claves de software de KMS. |
| Plaintext | bytes | Sí | Datos binarios | Texto sin formato para cifrar. |
| Algorithm | string | No | AES_GCM | Algoritmo de cifrado. Si no se establece, se utiliza el algoritmo definido para la clave de forma predeterminada. Para consultar los valores compatibles, consulte Key types and specifications. |
| Iv | bytes | No | Datos binarios | Vector de inicialización (IV). Solo aplica cuando Algorithm es AES_GCM o AES_CBC. Si no se establece, KMS genera un valor aleatorio. Longitudes válidas: 12 bytes para AES_GCM y 16 bytes para AES_CBC. Importante Se recomienda no establecer este parámetro. |
| Aad | binary | No | Datos binarios | Datos autenticados adicionales (AAD) para el modo GCM. Solo aplica cuando Algorithm es AES_GCM, y su uso es opcional según sus requisitos empresariales. Si se establece, pase el mismo valor al llamar a AdvanceDecrypt. |
| PaddingMode | string | No | PKCS7_PADDING | Modo de relleno. Es obligatorio solo cuando Algorithm es AES_CBC o AES_ECB. Valores válidos: PKCS7_PADDING (predeterminado) y NO_PADDING. Con PKCS7_PADDING, el sistema agrega K-(L mod K) bytes de relleno a la entrada, donde K es el tamaño del bloque de cifrado y L es la longitud de la entrada. Con NO_PADDING, la longitud del texto sin formato debe ser un múltiplo entero del tamaño del bloque de cifrado. |
Parámetros de respuesta
|
Parámetro |
Tipo |
Ejemplo |
Descripción |
|
CiphertextBlob |
bytes |
Datos binarios |
Texto cifrado. Contiene metadatos integrados para |
|
Algorithm |
string |
AES_GCM |
Algoritmo de cifrado utilizado. |
|
KeyId |
string |
key-hzz62f1cb66fa42qo**** |
Identificador único global de la clave. Si pasó un alias en la solicitud, se devuelve el identificador de la clave a la que está vinculado dicho alias. |
|
KeyVersionId |
string |
key-hzz62f1cb66fa42qopd9s-17kedv**** |
Versión de la clave utilizada para cifrar los datos. Siempre corresponde a la versión principal. |
|
Iv |
bytes |
Datos binarios |
Vector de inicialización utilizado. Se devuelve solo cuando |
|
PaddingMode |
string |
PKCS7_PADDING |
Modo de relleno utilizado. Se devuelve solo cuando |
|
RequestId |
string |
c0037a6d-7784-4ef2-a692-288fdefc7b9d |
Identificador de la solicitud, utilizado para localizar y solucionar problemas. |
Códigos de error
|
Código de estado HTTP |
Código de error |
Mensaje de error |
Descripción |
|
404 |
Forbidden.OnlySymmetricKeySupported |
The key %s is not a symmetric key. The API only supports symmetric keys. |
La clave especificada no es simétrica. Esta API solo admite claves simétricas. Las claves asimétricas se utilizan para el cifrado de datos entre dominios de seguridad o para el intercambio de claves, escenarios en los que KMS no participa en uno de los extremos. |
Para consultar la lista completa de códigos de error, consulte Service error codes.