Skip to content

Sign and verify data

Sign data with a key of your tenant as a JWS (RFC 7515), and verify a JWS, either in one request or streamed for large files.

Who can do it

An application authenticated as a cryptographic actor of your tenant. Its token must carry the scope of the operation, and the actor must hold an active Capability Grant for the operation on the key:

Operation Scope Capability Grant
Sign in one request secure.sign SIGN on the key
Verify in one request secure.verifySignature VERIFY on every signing key
Sign a stream stream.signStream SIGN on the key
Verify a stream stream.verifySignatureStream VERIFY on every signing key

No console role performs these operations.

Before you start

  • A signing key exists in the tenant. See Create a key.
  • The application can obtain a token. See Get an access token for an application.
  • If your tenant requires a qualified timestamp on signatures, the signature is produced in JWS JSON serialization; do not ask for the compact form.

Steps

  1. Sign:
    • Java SDK: sdk.sign(kid, data) returns a SignResult; keep getJwsToken(). sign(kid, data, serialization) chooses compact or JSON serialization. For files, sdk.signFile(kid, input, output) chooses the one-request or the streaming operation from the server's size limit.
    • Crypto CLI: AnkaSecureCLI sign-file --kid <kid> --input-file <file> --output-signature-file <file>, with --serialization compact or --serialization json when you need one. sign-file-stream always streams.
    • API: POST /api/v3/crypto/sign with {"kid": "<kid>", "data": "<base64 data>"} and, optionally, serialization (COMPACT or JSON) and validityDays. For a stream, POST /api/v3/crypto/stream/sign with a multipart/form-data body, metadata before file; the result is a detached JWS (RFC 7797).
  2. Verify:
    • Java SDK: sdk.verifySignature(jws) or sdk.verifySignature(jwsFile) returns a VerifySignatureResult; read isValid() and getSignatureResults(). For a detached signature, sdk.verifySignatureStream(dataFile, signatureFile).
    • Crypto CLI: AnkaSecureCLI verify-signature --input-signature-file <file>, or AnkaSecureCLI verify-signature-stream --input-file <file> --input-signature-file <file> for a detached signature.
    • API: POST /api/v3/crypto/verify with {"jwsToken": {...}}; the compact and JSON serializations are both accepted. For a stream, POST /api/v3/crypto/stream/verify with the detached JWS in metadata and the signed data in file.
  3. Act on the verdict, not on the status code. A signature that does not verify is a successful call that answers valid: false.

What you see when it worked

A signature returns the JWS with keyRequested, materialVersion and algorithmUsed. When the tenant requires timestamping, the JWS is in JSON serialization and carries the qualified timestamp.

A verification returns valid and one signatureResults entry per signature, each with its key, algorithm, material version and verdict. valid is true only when every signature verifies. A JWS signed by several keys is checked signature by signature, each under its own key.

If it fails

What you see Cause What to do
200 with valid: false The signature does not verify: the data or the signature was altered, or it was made with another key Do not trust the data
403 .../errors/forbidden The token lacks the scope, the actor holds no active Capability Grant on a key involved, or the tenant or actor is not in a state that permits cryptographic operations Ask a tenant administrator to check the actor's roles and grants
400 .../errors/serialization-incompatible-with-timestamp Compact serialization was requested and the tenant requires a qualified timestamp, which only the JSON serialization carries Request JSON, or omit serialization
400 .../errors/invalid-input The data is not valid Base64, or the key cannot sign Correct the request, or use a signing key
404 .../errors/not-found The key does not exist or lacks a private part Check the key identifier
409 .../errors/conflict The key is suspended or revoked Use an active key
409 .../errors/key-material-usage-exhausted The key's current material reached its usage limit Ask a key manager to rotate the key; what it signed can still be verified
413 .../errors/payload-too-large The data is above the one-request limit Use the streaming operation, or let signFile choose
422 with extensions.errorCode such as JWS_ROOT_MEMBER_FORBIDDEN or JOSE_ACTOR_KID_REPEATED The JWS has a shape the platform does not accept Send the JWS as it was produced

Without the console

These operations have no console screen.

Surface How
Java SDK sign, signFile, signFileStream, verifySignature, verifySignatureStream on AuthenticatedSdk
Crypto CLI 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)