Package co.ankatech.ankasecure.sdk.security

package co.ankatech.ankasecure.sdk.security
The ANKASecure SDK secure-memory layer.

This package is the single sanctioned place in the SDK and CLI for handling sensitive material on the client side: cryptographic keys, passwords, JWT bearer tokens, and any byte[] or char[] that holds secrets after construction.

Public API

  • Zeroization — null-safe overwrite helpers for byte[] and char[], plus best-effort Destroyable.destroy() that swallows DestroyFailedException.
  • SecretBuffer — AutoCloseable wrapper for an owned byte[]. Zeroizes and nulls the field on SecretBuffer.close().
  • SecretChars — same pattern for char[]. Use for password / passphrase / sensitive char material.
  • BearerToken — JWT holder backed by char[] with a redacted toString() (<first6>…[REDACTED]).
  • EnvScrubber — best-effort removal of an env-var entry from the JVM's in-memory ProcessEnvironment map after read.

What this layer CAN guarantee

  • Caller-owned byte[] returned by Cipher.doFinal(...), SecretKey.getEncoded(), etc., is overwritten with 0x00 when wrapped in SecretBuffer and closed.
  • Caller-owned char[] from System.console().readPassword() is space-filled when wrapped in SecretChars and closed.
  • char[] inside PBEKeySpec can be cleared via clearPassword() (used in CLI Slice 5 helpers).
  • Bouncy Castle MLKEMPrivateKeySpec and MLDSAPrivateKey can be passed to destroyIfPossible(Object); both implement Destroyable in BC 1.83.

What this layer CANNOT guarantee

  • Bouncy Castle internal byte-array pools (released to the pool and reused without zeroization).
  • JCA scratch buffers inside Cipher.update / doFinal.
  • JIT register spills and stack-frame retention.
  • OkHttp okio.Buffer segment pool, JVM TLAB / young-gen retention, OS swap / hibernation files, native heap (BC PQC native implementations).
  • String interning and reachability — once secret material is wrapped in a String (e.g., via new String(charArray)), it cannot be reliably erased. The cutover avoids String for all sensitive material.

See SECURE_MEMORY.md at the SDK root for the complete capability matrix and the threat model behind these limits.

ArchUnit enforcement

From Slice 7 onwards, ArchUnit rules in co.ankatech.ankasecure.sdk.architecture.SecurityArchUnitTest fail the build on:

  • String fields with names matching password|secret|token|jwt|bearer| clientSecret outside this package;
  • SecretKey.getEncoded() invocations outside this package not consumed inside a try-with-resources of SecretBuffer;
  • Picocli @Option fields of type String with names matching password|secret|token|key.
  • Classes
    Class
    Description
    BearerToken
    Holder for a JWT bearer token represented as char[] rather than String, with a redacted BearerToken.toString() so accidental log statements do not leak the token verbatim.
    EnvScrubber
    Best-effort removal of an environment variable from the JVM's process environment map after the variable has been read.
    SecretBuffer
    Owning wrapper for a sensitive byte[].
    SecretChars
    Owning wrapper for a sensitive char[] (typically passwords, passphrases, or other character-secret material returned by System.console().readPassword() or by JCA APIs that operate on char[]).
    Zeroization
    Centralized zeroization helpers for the ANKASecure secure-memory layer.