Cifrar y descifrar datos

Protege datos con una clave de tu tenant y recupéralos más tarde, como un JWE (RFC 7516), en una sola solicitud o en streaming para archivos grandes.

Quién puede hacerlo

Una aplicación autenticada como actor criptográfico de tu tenant. Su token debe llevar el scope de la operación, y el actor debe tener una concesión de capacidad activa para la operación sobre la clave:

Ningún rol de la consola realiza estas operaciones.

Antes de empezar

• Existe una clave de cifrado en el tenant, con un identificador de clave que tu aplicación conoce. Consulta Crear una clave.
• La aplicación puede obtener un token. Consulta Obtener un token de acceso para una aplicación.
• Para archivos grandes, las operaciones de streaming necesitan HTTP/2 sobre https. El SDK se niega a hacer streaming sobre HTTP/1.1 o http sin cifrar antes de enviar nada.

Pasos

1. Cifra:
   • SDK de Java: sdk.encrypt(kid, plaintext) devuelve un EncryptResult; conserva getJweToken(). Para archivos, sdk.encryptFile(kid, input, output) elige la operación de una sola solicitud o la de streaming según el límite de tamaño del servidor.
   • CLI criptográfica: AnkaSecureCLI encrypt-file --kid <kid> --input-file <file> --output-file <file>. Los archivos grandes se envían en streaming automáticamente; encrypt-file-stream siempre usa streaming.
   • API: POST /api/v3/crypto/encrypt con {"kid": "<kid>", "data": "<base64 plaintext>"}. Para un stream, POST /api/v3/crypto/stream/encrypt con un cuerpo multipart/form-data cuya parte metadata va antes de la parte file.
2. Guarda el JWE exactamente como se devolvió. Un JWE hecho con una clave asimétrica o compuesta lleva un miembro de confirmación de clave, ank_kc; la plataforma rechaza un JWE sin él, o uno cuyo identificador de clave del destinatario, versión, algoritmo o tenant se editó.
3. Descifra:
   • SDK de Java: sdk.decrypt(jwe) devuelve un DecryptResult; lee getDecryptedData(). Para archivos, sdk.decryptFile(input, output) elige el camino según el formato de la entrada.
   • CLI criptográfica: AnkaSecureCLI decrypt-file --input-file <file> --output-file <file>, o decrypt-file-stream para un artefacto de streaming.
   • API: POST /api/v3/crypto/decrypt con {"jweToken": {...}}. Para un stream, POST /api/v3/crypto/stream/decrypt con el encabezado multipart/mixed y las partes del texto cifrado.
4. Si el JWE está dirigido a varias claves, nombra aquella con la que descifra tu actor: recipientKid en el cuerpo de la solicitud, el parámetro de consulta recipientKid para un stream, sdk.decrypt(recipientKid, jwe) o --recipient-kid en la CLI. Solo se prueba ese destinatario.
5. En un descifrado en streaming, espera el veredicto. El texto en claro llega en la primera parte de la respuesta, antes de la comprobación de integridad del final del stream; la parte final del veredicto indica si se cumple. Trata la salida como no confiable hasta que el veredicto sea VALID. El SDK y la CLI lo hacen por ti: escriben en <output>.part y le cambian el nombre solo con un veredicto VALID.

Qué ves cuando funcionó

Un cifrado devuelve el JWE en la serialización JSON general (jweToken), con keyRequested, materialVersion, algorithmUsed y cualquier warnings, como una clave cerca de su límite de uso o de su fecha de retiro. El JWE de una clave compuesta lleva un destinatario por componente.

Un descifrado devuelve el texto en claro con la clave y la versión de material que se usaron. Un descifrado en streaming termina con una parte de veredicto cuyo verdict es VALID; con el SDK o la CLI, el archivo de salida existe solo entonces.

Si falla

Sin la consola

Estas operaciones no tienen pantalla en la consola.

Relacionado

• Concesiones de Capacidad: lo que permite que un actor use una clave.

Estas páginas están en inglés:

• Non-streaming encrypt and decrypt with the SDK
• Streaming encrypt and decrypt with the SDK
• Crypto CLI commands