Package co.ankatech.ankasecure.sdk.examples

Class ExampleUtil

java.lang.Object
co.ankatech.ankasecure.sdk.examples.ExampleUtil
public final class ExampleUtil extends Object
Shared utilities for all ANKASecure© SDK example scenarios.

This class centralises common functionality used by the ExampleScenario* programs, including:

  • Loading CLI configuration from files or classpath resources
  • Authenticating via encrypted credentials or a pre-issued JWT token
  • JSON serialisation with ISO-8601 date/time support
  • Deriving and decrypting cryptographic keys (PBKDF2, AES-GCM)
  • Ensuring a temporary working directory for example artefacts
  • Uniform error handling that classifies SDK exceptions (timeout, HTTP, I/O, etc.)
  • Pretty-printing operation metadata (encrypt, decrypt, sign, verify, re-encrypt, re-sign, combined operations)
  • Comparing input streams for byte-level equality

All methods are static. This class cannot be instantiated.

Warning: Several methods in this class call fatal(String, Throwable), which terminates the JVM via System.exit(int). This is acceptable for standalone example programs but must not be adopted in production SDK integrations. Prefer throwing exceptions and letting the caller decide how to handle failures.

Since:
3.0.0
Author:
ANKATech Solutions Inc.
See Also:

  • Field Details

    • TEMP_DIR

      public static final Path TEMP_DIR
      Working directory for the temporary artefacts produced by examples.

  • Method Details

    • loadProperties

      public static Properties loadProperties()
      Loads CLI properties using the following look-up order:
      1. A cli.properties file in the current working directory.
      2. The file pointed to by the cli.config system property.
      3. A /cli.properties resource on the classpath.

      If none of these sources exist, the method calls fatal(String, Throwable) and the JVM terminates.

      Returns:
      a Properties object with the loaded key-value pairs; never null
      Throws:
      UncheckedIOException - if an I/O error occurs while reading the configuration file

    • authenticate

      public static AuthenticatedSdk authenticate(Properties props)
      Authenticates using encrypted credentials stored in cli.properties and returns an AuthenticatedSdk.

      The method reads four mandatory properties, derives an AES key with PBKDF2, decrypts the client credentials, and performs application authentication via AnkaSecureSdk.authenticateApplication(String, co.ankatech.ankasecure.sdk.security.SecretChars).

      Required properties:

      • client.uuid — unique identifier for the client
      • client.salt — hex-encoded salt for key derivation
      • clientIdEnc — AES-GCM-encrypted client ID (Base64)
      • clientSecretEnc — AES-GCM-encrypted client secret (Base64)

      If any property is missing the method calls fatal(String, Throwable) and the JVM terminates.

      Parameters:
      props - CLI properties loaded via loadProperties(); must not be null
      Returns:
      an AuthenticatedSdk instance bound to a valid JWT token; never null under normal operation (the JVM exits on failure)
      See Also:

    • toJson

      public static String toJson(Object o)
      Serialises an object to its JSON string representation using the SDK's internal JSON mapper (ISO-8601 dates, pretty-print).
      Parameters:
      o - the object to serialise; must not be null
      Returns:
      a JSON string; never null
      Throws:
      UncheckedIOException - if serialisation fails

    • fatal

      public static void fatal(String msg, Throwable t)
      Logs a fatal error to stderr and terminates the JVM with exit code 1.

      If the throwable is an AnkaSecureSdkException the message is enriched with the SdkErrorCode category (timeout, HTTP status, I/O). The full stack trace is printed only when the system property ankasecure.debugStack is set to true.

      Warning — JVM termination: this method calls System.exit(int) and never returns. It is designed exclusively for standalone example programs. Production code should throw an appropriate exception instead.

      Parameters:
      msg - the error message to display; must not be null
      t - the causal exception, or null if none

    • ensureTempDir

      public static void ensureTempDir()
      Ensures that the TEMP_DIR directory exists, creating it (and any parent directories) if necessary.

      On failure the method calls fatal(String, Throwable) and the JVM terminates.

      See Also:

    • ensureTempDir

      public static void ensureTempDir(Path dir)
      Ensures that the given directory exists, creating it (and any parent directories) if necessary.

      On failure the method calls fatal(String, Throwable) and the JVM terminates.

      Parameters:
      dir - the directory to create; must not be null
      See Also:

    • streamsAreEqual

      public static boolean streamsAreEqual(InputStream a, InputStream b) throws IOException
      Compares two input streams byte-by-byte to determine whether they contain identical content.

      Both streams are read in 8 KiB chunks until one (or both) reach EOF. The method returns true only if every byte matches and both streams reach EOF at the same position.

      Parameters:
      a - the first stream; must not be null
      b - the second stream; must not be null
      Returns:
      true if the streams are byte-identical; false otherwise
      Throws:
      IOException - if an I/O error occurs while reading either stream

    • nullSafe

      public static String nullSafe(String s)
      Returns the input string if it is non-null and non-blank; otherwise returns the literal "(none)".
      Parameters:
      s - the input string; may be null
      Returns:
      s or "(none)"

    • versionSafe

      public static String versionSafe(Integer v)
      Returns the material version as a string if it is non-null; otherwise returns the literal "n/a" (e.g. utility mode, or streaming flows where the version rides the JOSE artefact).
      Parameters:
      v - the material version; may be null
      Returns:
      v as a string or "n/a"

    • printEncryptMeta

      public static void printEncryptMeta(EncryptResult r)
      Prints encryption operation metadata to stdout.

      Displays the key requested, the key-material version, the algorithm, and any non-fatal warnings returned by the server.

      Parameters:
      r - the encryption result; must not be null
      See Also:

    • printDecryptMeta

      public static void printDecryptMeta(DecryptResultMetadata m)
      Prints decryption operation metadata to stdout.

      Displays the key requested, the key-material version, the algorithm, and any non-fatal warnings.

      Parameters:
      m - the decryption metadata; must not be null
      See Also:

    • printDecryptMeta

      public static void printDecryptMeta(DecryptResult r)
      Prints decryption metadata extracted from a full DecryptResult, preceded by a section header.
      Parameters:
      r - the decryption result containing embedded metadata; must not be null
      See Also:

    • printSignMeta

      public static void printSignMeta(SignResult r)
      Prints signature operation metadata to stdout.
      Parameters:
      r - the signature result; must not be null
      See Also:

    • printSignMeta

      public static void printSignMeta(String heading, SignResult m)
      Prints signature metadata preceded by a contextual heading.
      Parameters:
      heading - a section label displayed before the metadata
      m - the signature result; must not be null
      See Also:

    • printVerifyMeta

      public static void printVerifyMeta(VerifySignatureResult r)
      Prints signature verification metadata to stdout.
      Parameters:
      r - the verification result; must not be null
      See Also:

    • printVerifyMeta

      public static void printVerifyMeta(String heading, VerifySignatureResult m)
      Prints signature verification metadata preceded by a contextual heading and including the validity flag.
      Parameters:
      heading - a section label displayed before the metadata
      m - the verification result; must not be null
      See Also:

    • printReencryptMeta

      public static void printReencryptMeta(ReencryptResult m)
      Prints re-encryption metadata showing both the old and new key and algorithm details.
      Parameters:
      m - the re-encryption result; must not be null
      See Also:

    • printResignMeta

      public static void printResignMeta(ResignResult m)
      Prints re-signature metadata showing both the old and new key and algorithm details.
      Parameters:
      m - the re-signature result; must not be null
      See Also:

    • printSignEncryptMeta

      public static void printSignEncryptMeta(SignEncryptResult r)
      Prints metadata for a sign-then-encrypt combined operation, showing both the signature layer and the encryption layer.
      Parameters:
      r - the combined result; must not be null
      See Also:

    • printDecryptVerifyMeta

      public static void printDecryptVerifyMeta(DecryptVerifyResult r)
      Prints metadata for a decrypt-then-verify combined operation, showing both the decryption layer and the verification layer.
      Parameters:
      r - the combined result; must not be null
      See Also:

    • printWarnings

      public static void printWarnings(List<CryptoWarning> warnings)
      Prints a list of warning messages to stdout. Each warning is indented and prefixed with a bullet. Does nothing if the list is null or empty.
      Parameters:
      warnings - the warning messages; may be null