Skip to content

Firmar y verificar datos

Firma datos con una clave de tu tenant como un JWS (RFC 7515), y verifica un JWS, 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:

Operación Scope Concesión de capacidad
Firmar en una sola solicitud secure.sign SIGN sobre la clave
Verificar en una sola solicitud secure.verifySignature VERIFY sobre cada clave firmante
Firmar un stream stream.signStream SIGN sobre la clave
Verificar un stream stream.verifySignatureStream VERIFY sobre cada clave firmante

Ningún rol de la consola realiza estas operaciones.

Antes de empezar

  • Existe una clave de firma en el tenant. Consulta Crear una clave.
  • La aplicación puede obtener un token. Consulta Obtener un token de acceso para una aplicación.
  • Si tu tenant exige un sello de tiempo cualificado en las firmas, la firma se produce en la serialización JSON de JWS; no pidas la forma compacta.

Pasos

  1. Firma:
    • SDK de Java: sdk.sign(kid, data) devuelve un SignResult; conserva getJwsToken(). sign(kid, data, serialization) elige la serialización compacta o JSON. Para archivos, sdk.signFile(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 sign-file --kid <kid> --input-file <file> --output-signature-file <file>, con --serialization compact o --serialization json cuando necesites una. sign-file-stream siempre usa streaming.
    • API: POST /api/v3/crypto/sign con {"kid": "<kid>", "data": "<base64 data>"} y, de forma opcional, serialization (COMPACT o JSON) y validityDays. Para un stream, POST /api/v3/crypto/stream/sign con un cuerpo multipart/form-data, metadata antes de file; el resultado es un JWS separado (RFC 7797).
  2. Verifica:
    • SDK de Java: sdk.verifySignature(jws) o sdk.verifySignature(jwsFile) devuelve un VerifySignatureResult; lee isValid() y getSignatureResults(). Para una firma separada, sdk.verifySignatureStream(dataFile, signatureFile).
    • CLI criptográfica: AnkaSecureCLI verify-signature --input-signature-file <file>, o AnkaSecureCLI verify-signature-stream --input-file <file> --input-signature-file <file> para una firma separada.
    • API: POST /api/v3/crypto/verify con {"jwsToken": {...}}; se aceptan tanto la serialización compacta como la JSON. Para un stream, POST /api/v3/crypto/stream/verify con el JWS separado en metadata y los datos firmados en file.
  3. Actúa según el veredicto, no según el código de estado. Una firma que no se verifica es una llamada correcta que responde valid: false.

Qué ves cuando funcionó

Una firma devuelve el JWS con keyRequested, materialVersion y algorithmUsed. Cuando el tenant exige sello de tiempo, el JWS está en serialización JSON y lleva el sello de tiempo cualificado.

Una verificación devuelve valid y una entrada de signatureResults por firma, cada una con su clave, su algoritmo, su versión de material y su veredicto. valid es true solo cuando se verifican todas las firmas. Un JWS firmado por varias claves se comprueba firma por firma, cada una con su propia clave.

Si falla

Qué ves Causa Qué hacer
200 con valid: false La firma no se verifica: se alteraron los datos o la firma, o se hizo con otra clave No confíes en los datos
403 .../errors/forbidden Al token le falta el scope, el actor no tiene ninguna concesión de capacidad activa sobre una de las claves, o el tenant o el actor no está en un estado que permita operaciones criptográficas Pide a un administrador del tenant que revise los roles y las concesiones del actor
400 .../errors/serialization-incompatible-with-timestamp Se pidió la serialización compacta y el tenant exige un sello de tiempo cualificado, que solo lleva la serialización JSON Pide JSON, u omite serialization
400 .../errors/invalid-input Los datos no son Base64 válido, o la clave no puede firmar Corrige la solicitud, o usa una clave de firma
404 .../errors/not-found La clave no existe o no tiene parte privada Revisa el identificador de clave
409 .../errors/conflict La clave está suspendida o revocada Usa una clave activa
409 .../errors/key-material-usage-exhausted El material actual de la clave alcanzó su límite de uso Pide a un gestor de claves que rote la clave; lo que firmó todavía se puede verificar
413 .../errors/payload-too-large Los datos superan el límite de una sola solicitud Usa la operación de streaming, o deja que signFile elija
422 con un extensions.errorCode como JWS_ROOT_MEMBER_FORBIDDEN o JOSE_ACTOR_KID_REPEATED El JWS tiene una forma que la plataforma no acepta Envía el JWS tal como se produjo

Sin la consola

Estas operaciones no tienen pantalla en la consola.

Superficie Cómo
SDK de Java sign, signFile, signFileStream, verifySignature, verifySignatureStream en AuthenticatedSdk
CLI criptográfica AnkaSecureCLI sign-file, verify-signature, sign-file-stream, verify-signature-stream
API POST /api/v3/crypto/sign (signData), POST /api/v3/crypto/verify (verifySignature), POST /api/v3/crypto/stream/sign (signDataStream), POST /api/v3/crypto/stream/verify (verifySignatureStream)

Relacionado

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