Package co.ankatech.ankasecure.sdk.operations

Class SignatureOperations

java.lang.Object
co.ankatech.ankasecure.sdk.operations.SignatureOperations
public final class SignatureOperations extends Object
Signature and verification operations facade.

Public facade for digital signature operations. All methods are exposed via AuthenticatedSdk.

Since:
3.0.0
Author:
ANKATech Solutions Inc.

  • Constructor Details

    • SignatureOperations

      public SignatureOperations(InternalServiceFactory svc, co.ankatech.ankasecure.openapi.client.AnkaSecureOpenApiClient openApiClient, org.slf4j.Logger userLogger)

  • Method Details

    • sign

      public SignResult sign(String kid, byte[] data) throws AnkaSecureSdkException
      Signs raw bytes using the key identified by kid.

      Computes a digital signature over the provided data using the signing key's algorithm (ML-DSA, SLH-DSA, ECDSA, RSA-PSS, etc.). The result is a compact JWS (RFC 7515) string containing the signature and metadata needed for verification.

      This method is suitable for in-memory payloads up to ~100 MB. For larger files, use signFileStream(String, Path, Path) to avoid loading the entire payload into memory.

      Parameters:
      kid - key identifier referencing a signing key stored in ANKASecure©; must not be null
      data - the raw bytes to sign; must not be null
      Returns:
      signature result containing the JWS token and operation metadata; never null
      Throws:
      AnkaSecureSdkException - if the key identified by kid does not exist, does not support signing, the authenticated client lacks permission, or the server returns an error
      NullPointerException - if kid or data is null
      Since:
      3.0.0

    • sign

      public SignResult sign(String kid, byte[] data, JwsSerialization serialization) throws AnkaSecureSdkException
      Signs raw bytes with an explicit JWS serialization selection (PRD §60).

      Ergonomic overload of sign(String, byte[]). Passing JwsSerialization.COMPACT or JwsSerialization.JSON requests that representation; a null serialization is equivalent to calling sign(String, byte[]) (the server chooses).

      Parameters:
      kid - key identifier referencing a signing key; must not be null
      data - the raw bytes to sign; must not be null
      serialization - requested serialization, or null to let the server choose
      Returns:
      signature result; never null
      Throws:
      AnkaSecureSdkException - on error, including HTTP 400 when COMPACT is requested but the deployment mandates a qualified timestamp
      NullPointerException - if kid or data is null
      Since:
      3.0.0

    • signFileCompact

      public SignResult signFileCompact(String kid, Path input, Path output) throws AnkaSecureSdkException
      Signs a file using the key identified by kid.

      The entire file is loaded into memory, signed, and the resulting compact JWS (RFC 7515) is written to the output file. This method is suitable for files up to ~100 MB. For larger files, use signFileStream(String, Path, Path) which processes files in chunks without loading them entirely into memory.

      The output file contains a complete compact JWS string that can be verified using verifySignature(Path).

      Parameters:
      kid - key identifier referencing a signing key stored in ANKASecure©; must not be null
      input - path to file to sign; must not be null and file must exist
      output - path where JWS will be written; must not be null
      Returns:
      signature result containing the JWS token and operation metadata; never null
      Throws:
      AnkaSecureSdkException - if the key identified by kid does not exist, does not support signing, the input file cannot be read, the output file cannot be written, or the server returns an error
      NullPointerException - if kid, input, or output is null
      Since:
      3.0.0

    • signFileCompact

      public SignResult signFileCompact(String kid, Path input, Path output, JwsSerialization serialization) throws AnkaSecureSdkException
      Signs a file with an explicit JWS serialization selection (PRD §60).

      Ergonomic overload of signFileCompact(String, Path, Path). A null serialization defers to the server. When the server mandates a qualified timestamp, the written output is a JWS-JSON artifact carrying the JAdES sigTst (never collapsed to a compact string).

      Parameters:
      kid - key identifier for signing; must not be null
      input - input file (max 5MB); must not be null
      output - output file; must not be null
      serialization - requested serialization, or null to let the server choose
      Returns:
      signature result; never null
      Throws:
      AnkaSecureSdkException - on error, including HTTP 400 when COMPACT is requested but the deployment mandates a qualified timestamp
      NullPointerException - if kid, input, or output is null
      Since:
      3.0.0

    • signFileStream

      public SignResult signFileStream(String kid, Path input, Path output) throws AnkaSecureSdkException
      Signs a file in streaming mode (designed for large files >100 MB).

      Streaming variant that processes the file in chunks using multipart upload, minimizing memory consumption. Unlike signFile(String, Path, Path), this method produces a detached JWS (General-JSON header + separate signature) instead of a compact JWS string.

      The detached format separates the JWS header from the signed payload, enabling efficient streaming verification of large files using verifySignatureStream(Path, Path).

      Parameters:
      kid - key identifier referencing a signing key stored in ANKASecure©; must not be null
      input - path to file to sign; must not be null and file must exist
      output - path where detached signature will be written; must not be null
      Returns:
      signature result with operation metadata (JWS token field may be null in streaming mode); never null
      Throws:
      AnkaSecureSdkException - if the key identified by kid does not exist, does not support signing, the input file cannot be read, the output file cannot be written, or the server returns an error
      NullPointerException - if kid, input, or output is null
      Since:
      3.0.0

    • verifySignatureFile

      public VerifySignatureResult verifySignatureFile(Path jwsFile) throws AnkaSecureSdkException
      Verifies a JWS signature from a file (compact or JWS-JSON).

      Reads a JWS token from the file — either an RFC 7515 §7.1 compact string or an RFC 7515 §7.2 JWS-JSON object (which MAY carry a JAdES qualified timestamp) — extracts the signing key identifier, retrieves the public key, and verifies the signature. This method is the inverse of the attached signFileCompact(String, Path, Path).

      The verification checks both the cryptographic signature and the key's current status (revoked, expired, usage limits). A signature is only considered valid if both checks pass. Any embedded qualified timestamp is surfaced informationally via VerifySignatureResult.getQualifiedTimestamp() and NEVER affects valid.

      Parameters:
      jwsFile - path to file containing a compact or JWS-JSON token; must not be null and file must exist
      Returns:
      verification result with validity flag, key used, algorithm, warnings, and optional qualified timestamp; never null
      Throws:
      AnkaSecureSdkException - if the file cannot be read, the JWS is malformed, the signing key does not exist, or the server returns an error
      NullPointerException - if jwsFile is null
      Since:
      3.0.0

    • verifySignature

      public VerifySignatureResult verifySignature(String jws) throws AnkaSecureSdkException
      Verifies a compact JWS signature string.

      Extracts the signing key identifier from the JWS header, retrieves the public key, and verifies the signature. This method is the inverse of sign(String, byte[]). The JWS token must be a valid compact JWS (RFC 7515) as produced by ANKASecure© signing operations.

      The verification checks both the cryptographic signature and the key's current status (revoked, expired, usage limits). A signature is only considered valid if both checks pass.

      Parameters:
      jws - the compact JWS token string (three Base64URL segments separated by dots); must not be null
      Returns:
      verification result with validity flag, key used, algorithm, and warnings; never null
      Throws:
      AnkaSecureSdkException - if the JWS is malformed, the signing key does not exist, or the server returns an error
      NullPointerException - if jws is null
      Since:
      3.0.0

    • verifySignatureStream

      public VerifySignatureResult verifySignatureStream(Path dataFile, Path signatureFile) throws AnkaSecureSdkException
      Verifies a detached signature in streaming mode (designed for large files >100 MB).

      Streaming variant that verifies signatures on large files without loading them entirely into memory. This method is the inverse of signFileStream(String, Path, Path) and expects a detached JWS format where the signature is stored separately from the signed data.

      The verification checks both the cryptographic signature and the key's current status. The data file is read in chunks and verified against the detached signature.

      Parameters:
      dataFile - path to original data file; must not be null and file must exist
      signatureFile - path to detached signature file; must not be null and file must exist
      Returns:
      verification result with validity flag, key used, algorithm, and warnings; never null
      Throws:
      AnkaSecureSdkException - if either file cannot be read, the signature is malformed, the signing key does not exist, or the server returns an error
      NullPointerException - if dataFile or signatureFile is null
      Since:
      3.0.0

    • verifySignatureUtilityStream

      public VerifySignatureResult verifySignatureUtilityStream(String kty, String alg, String publicKeyB64, String signatureB64, Path dataFile) throws AnkaSecureSdkException
      Verifies a signature using an external public key (utility operation).

      Server-side signature verification using a public key provided by the client rather than retrieved from the key store. This utility operation enables verification of signatures created outside ANKASecure© or verification before key import.

      The signature and data are processed in streaming mode, making this suitable for verifying large files without memory constraints.

      Parameters:
      kty - key type; one of "RSA", "EC", "ML-DSA", "SLH-DSA"; must not be null
      alg - algorithm identifier (e.g., "RS256", "ES256", "ML-DSA-87", "SLH-DSA-128s"); must not be null
      publicKeyB64 - Base64-encoded public key material; must not be null
      signatureB64 - Base64-encoded signature bytes; must not be null
      dataFile - path to original data file; must not be null and file must exist
      Returns:
      verification result with validity flag and algorithm used; never null
      Throws:
      AnkaSecureSdkException - if the key type/algorithm combination is unsupported, the public key or signature is malformed, the data file cannot be read, or the server returns an error
      NullPointerException - if any parameter is null
      Since:
      3.0.0