Package co.ankatech.ankasecure.sdk.model

Class VerifySignatureResult

java.lang.Object
co.ankatech.ankasecure.sdk.model.VerifySignatureResult
public final class VerifySignatureResult extends Object

VerifySignatureResult

Value object returned by signature verification operations (verifySignature, verifySignature(Path), verifySignatureStream). It conveys the outcome of a detached-signature verification together with exhaustive metadata emitted by the ANKASecure platform.

Detached JWS Structure

The streaming path verifies a detached JWS: the flattened JWS JSON Serialization (RFC 7515 §7.2.2) with no payload member, whose protected header declares an unencoded payload ("b64": false, "crit": ["b64"], RFC 7797). The shape is the same for every key; a composite key differs only in its alg: 


   {"protected":"BASE64URL(Header)","signature":"BASE64URL(Signature)"}
  • Header: JSON object carrying alg (e.g. ML-DSA-65, ES256, or a composite such as ML-DSA-65-ES256 or a private https://ankatech.co/jose/alg/… URI), kid (the Stable KID) and, when the key has versioned material, ank_kv.
  • Payload: omitted (detached); the original file data is supplied separately and verified against the signature.
  • Signature: one value computed over the header and the external payload. For a composite key it is the ML-DSA signature followed by the traditional signature, both over the composite message representative M'; it is valid only if both components verify.

Usage example


 Path payload   = Path.of("data/report.pdf");
 Path signature = Path.of("data/report.pdf.sig");
 VerifySignatureResult result = sdk.verifySignatureStream(payload, signature);
 if (!result.isValid()) {
     // Block the workflow or log warning
 }
 result.getWarnings().forEach(log::warn);

Outcome and Metadata

  • Validity flag – isValid() is true only when every signature of the JWS verified and each signing key's current status permits verification (revocation, expiry, usage caps). A JWS with any failing signature is invalid, never a partial success.
  • Per-signer detail – getSignatureResults() holds one entry per signature, in token order (RFC 7515 §7.2.1): the key it names, that key's catalogue algorithm, the key-material version it resolved to, and whether it verified. A JWS signed by one key yields one entry; a JWS signed by N keys yields N entries.
  • Warnings – non-fatal advisories such as usage caps, nearing expiry or algorithm deprecation notices. May be null or empty if none.

Reading every signer


 VerifySignatureResult result = sdk.verifySignature(jwsJson);
 for (SignatureResult entry : result.getSignatureResults()) {
     System.out.printf("%s %s v%s -> %s%n",
         entry.getKid(), entry.getAlgorithm(), entry.getMaterialVersion(),
         entry.getVerified() ? "VALID" : "INVALID");
 }

Thread-safety

Instances are effectively immutable once created by the SDK. They may be shared across threads safely provided no setter is invoked.

Note: getWarnings() may be null or empty.

See Also:

  • Constructor Details

    • VerifySignatureResult

      public VerifySignatureResult()

  • Method Details

    • isValid

      public boolean isValid()
      Indicates whether verification succeeded both cryptographically and against server-side policy checks.
      Returns:
      true if valid; false otherwise

    • getWarnings

      public List<CryptoWarning> getWarnings()
      Returns structured warnings encountered during signature verification.

      Warnings are type-safe instances allowing pattern matching and programmatic handling: 

      
 VerifySignatureResult result = sdk.verifySignature(jwsToken);

 if (result.isValid()) {
     // Signature cryptographically valid, now check warnings
     if (result.getWarnings() != null && !result.getWarnings().isEmpty()) {
         for (CryptoWarning warning : result.getWarnings()) {
             switch (warning) {
                 case KeyExpirationWarning kew when kew.daysRemaining() <= 7 ->
                     logger.error("CRITICAL: Verification key expires in {} days",
                         kew.daysRemaining());
                 case UsageLimitWarning ulw ->
                     logger.warn("Usage limit approaching: {}", ulw.message());
                 case GenericWarning gw ->
                     logger.info("Warning: {}", gw.rawMessage());
             }
         }
     }
 } else {
     logger.error("Signature verification FAILED");
 }

      Common warning types:

      Returns:
      unmodifiable list of warnings (null if no warnings, never empty if non-null)

    • getSignatureResults

      public List<co.ankatech.secure.client.model.SignatureResult> getSignatureResults()
      Returns the verification detail of every signature of the JWS, in token order - see signatureResults.

      Example:

      
 List<SignatureResult> signers = result.getSignatureResults();
 SignatureResult first = signers.get(0);
 log.info("signer {} ({} v{}) verified={}", first.getKid(),
     first.getAlgorithm(), first.getMaterialVersion(), first.getVerified());
      Returns:
      one entry per signature of the verified JWS (one for a JWS signed by one key, N for a JWS signed by N keys), unmodifiable, and each call returns fresh copies of the entries, so changing one changes nothing in this result; null only when the server response omitted the member

    • getQualifiedTimestamp

      public QualifiedTimestampInfo getQualifiedTimestamp()
      Returns the embedded RFC 3161 qualified timestamp, when present.

      Informational only — never affects isValid(). Returns null when the verified JWS carried no qualified timestamp.

      Returns:
      the qualified-timestamp view, or null when absent

    • toString

      public String toString()
      Overrides:
      toString in class Object

    • equals

      public boolean equals(Object o)
      Overrides:
      equals in class Object

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object