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 Compact JWS Structure

The service returns a Compact JWS in detached form: three Base64URL-encoded segments separated by dots, where the payload segment is empty: 


   BASE64URL(Header) .. BASE64URL(Signature)
  • Header: JSON object containing signature metadata such as alg (e.g. Falcon-512 or hybrid RSA-3072+SHA256) and kid (key identifier).
  • Payload: omitted here (detached); the original file data is supplied separately and verified against the signature.
  • Signature: computed over the header and external payload using the negotiated PQC, classical or hybrid algorithm.

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() reports whether the detached signature matches the supplied payload and the key’s current status permits verification (revocation, expiry, usage caps).
  • Key metadata – the key initially requested by the caller and the key-material version that performed the verification under that Stable KID.
  • Algorithm negotiated – post-quantum, classical or hybrid algorithm chosen by the crypto-engine (e.g. Falcon-512, RSA-3072+SHA256).
  • Warnings – non-fatal advisories such as usage caps, nearing expiry or algorithm deprecation notices. May be null or empty if none.

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. getMaterialVersion() may be null when the server could not resolve the material version (e.g. utility mode).

Since:
3.0.0
Author:
ANKATech Solutions Inc.
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

    • getKeyRequested

      public String getKeyRequested()
      Returns:
      key identifier originally requested by the caller

    • getMaterialVersion

      public Integer getMaterialVersion()
      Returns:
      key-material version (ank_kv) that performed the verification under the requested Stable KID; null when not resolvable (e.g. utility mode) — never 0

    • getAlgorithmUsed

      public String getAlgorithmUsed()
      Returns:
      algorithm negotiated by the crypto-engine

    • 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()
      Per-signature verification results — see signatureResults.
      Returns:
      list with length 1 for SIMPLE keys, length N for COMPOSITE hybrid keys; may be null if the server response omitted the field.

    • 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
      Since:
      3.0.0

    • 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