Package co.ankatech.ankasecure.sdk.model

Class SignResult

java.lang.Object

co.ankatech.ankasecure.sdk.model.SignResult

public final class SignResult
extends Object

Immutable result returned by signing operations.

Value object returned by one of the following SDK operations:

• AuthenticatedSdk.sign(String, byte[])
• AuthenticatedSdk.signFile(String, java.nio.file.Path, java.nio.file.Path)
• AuthenticatedSdk.signFileStream(String, java.nio.file.Path, java.nio.file.Path)

This class bundles the full JWS produced by the ANKASecure platform when signing a file, along with exhaustive metadata about the key operations and any non-fatal warnings. It is the Compact JWS described below, or the RFC 7515 §7.2 JWS JSON Serialization when the result carries more than Compact can (a JAdES qualified timestamp).

Compact JWS Structure

A Compact JWS consists of three Base64URL-encoded segments separated by dots:

1. Header: JSON object containing signature metadata such as alg (e.g. Falcon-1024) and kid (key identifier).
2. Payload: the detached or embedded file content, depending on your configuration.
3. Signature: the digital signature computed over the header and payload, using the signing key's PQC or composite algorithm.

Thread Safety

Instances are immutable and thread-safe. All fields are final and collections are unmodifiable. Instances can be safely shared across threads without synchronization.

Usage Example

 SignResult result = sdk.sign("my-signing-key", data);

 // Access immutable data
 String jws = result.getJwsToken();
 Integer materialVersion = result.getMaterialVersion();

 // Inspect the key-material version that performed the operation
 if (materialVersion != null) {
     System.out.println("Signed with material version " + materialVersion);
 }

 // Check warnings
 if (result.getWarnings() != null) {
     result.getWarnings().forEach(System.out::println);
 }
 

Builder Pattern

 SignResult result = SignResult.builder()
     .jwsToken("eyJhbGc...")
     .keyRequested("my-signing-key")
     .materialVersion(2)
     .algorithmUsed("ML-DSA-87")
     .addWarning("KEY_ROTATED")
     .build();
 

See Also:

• AuthenticatedSdk.sign(String, byte[])
• AuthenticatedSdk.signFile(String, java.nio.file.Path, java.nio.file.Path)
• AuthenticatedSdk.signFileStream(String, java.nio.file.Path, java.nio.file.Path)
• VerifySignatureResult

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static final class	SignResult.Builder	Builder for constructing immutable SignResult instances.

Method Summary

Modifier and Type	Method	Description
static SignResult.Builder	builder()	Creates a new builder for constructing SignResult instances.
String	getAlgorithmUsed()	Returns the catalogue algorithm of the key that signed (e.g.
String	getJwsToken()	Returns the JWS as persisted: the Compact Serialization, or the JWS JSON Serialization when the result carries more than Compact can (a JAdES qualified timestamp).
String	getKeyRequested()	Returns the key identifier originally requested by the client.
Integer	getMaterialVersion()	Returns the key-material version (ank_kv) that performed the operation under the requested Stable KID; null when not resolvable (e.g. utility mode) — never 0.
List<CryptoWarning>	getWarnings()	Returns structured warnings encountered during the signing operation.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Details

getJwsToken

public String getJwsToken()

Returns the JWS as persisted: the Compact Serialization, or the JWS JSON Serialization when the result carries more than Compact can (a JAdES qualified timestamp).

Returns:

non-null JWS string

getKeyRequested

public String getKeyRequested()

Returns the key identifier originally requested by the client.

Returns:

requested kid (may be null)

getMaterialVersion

public Integer getMaterialVersion()

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

Returns:

material version (may be null)

getAlgorithmUsed

public String getAlgorithmUsed()

Returns the catalogue algorithm of the key that signed (e.g. ML-DSA-65, FALCON-1024 or Ed25519+ML-DSA-65).

Returns:

algorithm identifier (may be null)

getWarnings

public List<CryptoWarning> getWarnings()

Returns structured warnings encountered during the signing operation.

Warnings are type-safe instances allowing pattern matching:

 for (CryptoWarning warning : result.getWarnings()) {
     switch (warning) {
         case KeyExpirationWarning kew when kew.daysRemaining() <= 7 ->
             System.err.println("CRITICAL: " + kew.message());
         case UsageLimitWarning ulw ->
             logWarning(ulw.message(), ulw.recommendedAction());
         case GenericWarning gw ->
             System.out.println(gw.rawMessage());
     }
 }
 

The returned list is unmodifiable. Attempts to modify it will throw UnsupportedOperationException.

Returns:

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

builder

public static SignResult.Builder builder()

Creates a new builder for constructing SignResult instances.

Returns:

a new Builder instance