Package co.ankatech.ankasecure.sdk.model

Class KeyMetadata

java.lang.Object
co.ankatech.ankasecure.sdk.model.KeyMetadata
public final class KeyMetadata extends Object
Metadata for a cryptographic key in the ANKASecure platform.

This class provides a complete view of a key's identity, configuration, lifecycle, and usage statistics. It is returned by the read-only key query operations (listKeys / getKeyMetadata).

Key Type Detection:

  • Simple key: kty is "ML-KEM", "ML-DSA", "RSA", "EC", "oct", etc., and compositeMode is null
  • Composite key: kty is the single coarse token "COMPOSITE" for every pairing; alg names the pairing and compositeMode names the construction
  • Composite KEM: compositeMode is COMPOSITE_KEM_COMBINE
  • Composite Signature: compositeMode is COMPOSITE_SIGNATURE
  • Destroyed key (getStatus() is deleted_logical): no shape is reported. kty, alg and compositeMode are all null, so isComposite(), isCompositeKem() and isCompositeSignature() answer false whatever the destroyed key's shape was. Read the status first.

Destroyed keys (Deleted view)

The key list returns destroyed keys only when the status filter is deleted_logical (new KeyFilters(null, null, null, "deleted_logical")); every other listing, and KeyFilters.none(), holds only keys the tenant still has. A destroyed-key row is built from the key identity alone. It carries getKid(), getUuid(), getStatus() (deleted_logical), getCreatedAt() and getDeletedAt(). It reports no key type, algorithm, composite mode, KDF, exportability, origin, restriction, expiry or usage: each of those is null, never a default. getKeyOps() is an empty list on such a row, because the generated client materialises an absent list as an empty one.

A kid can be taken again after its key is destroyed, so a destroyed-key row can share its kid with a live key, and several destroyed-key rows can share one kid. getUuid() is the key's own identity, never reused, and is the member that tells such rows apart.

Usage Examples

Check Key Type


 KeyMetadata metadata = sdk.getKeyMetadata(kid);

 if (metadata.isComposite()) {
     System.out.println("Composite key: " + metadata.getKty());
     if (metadata.isCompositeKem()) {
         System.out.println("KDF used: " + metadata.getKdf());
     }
 } else {
     System.out.println("Simple key: " + metadata.getKty());
 }

Check Lifecycle Status


 System.out.println("Status: " + metadata.getStatus());
 System.out.println("Created: " + metadata.getCreatedAt());
 System.out.println("Expires: " + metadata.getExpiresAt());
 System.out.println("Usage: " + metadata.getUsageCount() + " / " + metadata.getMaxUsageLimit());

Lifecycle States

The getStatus() field carries the published key-status token. The vocabulary is closed and is exactly the enum the crypto specification publishes for KeySummaryResponse.status — the same token the ?status= filter of the key-list endpoint accepts:

  • active: Key is operational and can be used for cryptographic operations
  • pending_rotation: Rotation is scheduled but has not executed yet
  • rotated: Key material superseded by a newer version under the same kid
  • expired: Key past getExpiresAt() or its usage limit, cannot be used
  • revoked: Key explicitly revoked due to compromise or policy
  • archived: Retained for compliance and audit only, read-only
  • suspended: Temporarily blocked for incident investigation; reversible
  • pending_destruction: In a mandatory cooling-off period before logical deletion; reversible back to archived
  • deleted_logical: Logically deleted and hidden from standard queries

A status token this SDK release does not know is reported as STATUS_UNKNOWN. It names no lifecycle state: treat such a key as not usable, and upgrade the SDK to interpret it.

Thread Safety

Instances are immutable value objects safe to share across threads.

See Also:

  • Field Details

    • STATUS_UNKNOWN

      public static final String STATUS_UNKNOWN
      The getStatus() token for a status the server returned that this SDK release does not know. Upgrade the SDK to interpret it. It is not a published token, so KeyFilters refuses it as a status filter.
      See Also:

  • Constructor Details

  • Method Details

    • getKid

      public String getKid()
      Returns the key identifier (kid) the key is addressed by.

      A kid can be taken again after its key is destroyed, so on a destroyed-key row (deleted_logical) it does not identify the row on its own: use getUuid().

      Returns:
      key identifier (never null)

    • getUuid

      public String getUuid()
      Returns the key's own identity.

      Assigned when the key is created, kept across every rotation of its kid, and never reused: a kid taken again after its key is destroyed belongs to a key with a new identity. It is the only member that tells apart rows sharing a kid: a live key and the destroyed-key row of a key that once held the same kid, or two destroyed-key rows of a kid reused twice.

      Returns:
      the key identity as a UUID string; the server states it on every row of the key list and on the key-metadata read

    • getKty

      public String getKty()
      Returns the key type.

      Examples: "ML-KEM", "ML-DSA", "RSA", "EC", "oct", and the single coarse token "COMPOSITE" for every hybrid pairing. A composite key's construction is reported by getCompositeMode() and its exact pairing by getAlg().

      Returns:
      key type, or null on a destroyed-key row (deleted_logical), which reports no shape

    • getCompositeMode

      public CompositeMode getCompositeMode()
      Returns how a composite key's components are combined.

      Every composite key publishes the coarse key type COMPOSITE, so this value — not getKty() — is what distinguishes a hybrid KEM from a hybrid signature. It is null for a simple key, where that absence means "not composite". It is also null on a destroyed-key row (deleted_logical), where it means "no shape reported", not "simple".

      Returns:
      the composite construction, or null for a simple key and for a destroyed-key row

    • getAlg

      public String getAlg()
      Returns the algorithm identifier.

      For simple keys: Single algorithm (e.g., "ML-KEM-768", "RSA-4096")
      For composite keys: Combined algorithms (e.g., "X25519+ML-KEM-768", "Ed25519+ML-DSA-44")

      Returns:
      algorithm identifier, or null on a destroyed-key row (deleted_logical)

    • getKdf

      public String getKdf()
      Returns the key derivation function for composite KEM keys.

      Only present when getCompositeMode() is COMPOSITE_KEM_COMBINE. Common values: "HKDF-SHA256", "HKDF-SHA512"

      Returns:
      KDF identifier, or null if not a composite KEM key and on a destroyed-key row (deleted_logical)

    • getKeyOps

      public List<String> getKeyOps()
      Returns the permitted key operations.

      Common values: "encrypt", "decrypt", "sign", "verify", "wrapKey", "unwrapKey"

      Returns:
      unmodifiable list of operations; an empty list on a destroyed-key row (deleted_logical), which states no operations (the generated client materialises the absent member as an empty list)

    • getExportable

      public Boolean getExportable()
      Returns whether the key can be exported.
      Returns:
      true if exportable, false otherwise; null on a destroyed-key row (deleted_logical), which has no exportability to report

    • getOrigin

      public KeyOrigin getOrigin()
      Returns the key origin.
      Returns:
      key origin (GENERATED, IMPORTED); null on a destroyed-key row (deleted_logical), which states no provenance

    • getRestricted

      public Boolean getRestricted()
      Returns whether the key is restricted (legacy format).
      Returns:
      true if restricted, false otherwise; null on a destroyed-key row (deleted_logical)

    • getStatus

      public String getStatus()
      Returns the current lifecycle status, as the published key-status token.

      The vocabulary is closed and is exactly the enum the crypto specification publishes for KeySummaryResponse.status: active, pending_rotation, rotated, expired, revoked, archived, suspended, pending_destruction, deleted_logical. It is the same token the ?status= filter of the key-list endpoint accepts, so a listed status can be passed back as a filter. deleted_logical marks a destroyed-key row, the one row that reports no shape, material or usage.

      Returns:
      the published status token (never null)

    • getCreatedAt

      public ZonedDateTime getCreatedAt()
      Returns the key creation timestamp.
      Returns:
      creation timestamp (never null)

    • getExpiresAt

      public ZonedDateTime getExpiresAt()
      Returns the hard expiration timestamp.
      Returns:
      expiration timestamp, or null if no expiration is set and on a destroyed-key row (deleted_logical)

    • getSoftLimitExpiration

      public ZonedDateTime getSoftLimitExpiration()
      Returns the soft expiration (warning threshold) timestamp.
      Returns:
      soft limit timestamp, or null if no soft limit is set and on a destroyed-key row (deleted_logical)

    • getDeletedAt

      public ZonedDateTime getDeletedAt()
      Returns when the key was destroyed.
      Returns:
      destruction timestamp on a destroyed-key row (deleted_logical); null on every key the tenant still holds

    • getUsageCount

      public Integer getUsageCount()
      Returns the current usage counter.
      Returns:
      usage count, or null on a destroyed-key row (deleted_logical)

    • getSoftUsageLimit

      public Integer getSoftUsageLimit()
      Returns the soft usage limit (warning threshold).
      Returns:
      soft usage limit, or null if no soft limit is set and on a destroyed-key row (deleted_logical)

    • getMaxUsageLimit

      public Integer getMaxUsageLimit()
      Returns the hard usage limit.
      Returns:
      maximum usage limit, or null if no limit is set and on a destroyed-key row (deleted_logical)

    • isComposite

      public boolean isComposite()
      Checks if this is a composite key.

      A destroyed-key row (getStatus() is deleted_logical) reports no key type, so this answers false there even when the destroyed key was composite: false on such a row means "shape not reported", not "simple".

      Returns:
      true if kty is the coarse composite token COMPOSITE

    • isCompositeKem

      public boolean isCompositeKem()
      Checks if this is a composite KEM key.

      Decided by getCompositeMode(), never by the key type: every composite key publishes the same coarse kty, so a key-type comparison could only answer "composite", never "which construction". A destroyed-key row reports no construction, so this answers false there (see isComposite()).

      Returns:
      true if the composite construction is COMPOSITE_KEM_COMBINE

    • isCompositeSignature

      public boolean isCompositeSignature()
      Checks if this is a composite signature key.

      Decided by getCompositeMode(), for the same reason as isCompositeKem(), and false on a destroyed-key row for the same reason as isComposite().

      Returns:
      true if the composite construction is COMPOSITE_SIGNATURE