Class ExampleUtil

java.lang.Object
co.ankatech.ankasecure.sdk.examples.ExampleUtil
public final class ExampleUtil extends Object
Utility class providing shared support for all ANKASecure SDK example scenarios.

This class centralizes common functionality used by the Example* programs, including:

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

All methods are static and intended for one-off use by the ExampleScenario classes.

  • Field Details

    • TEMP_DIR

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

  • Method Details

    • loadProperties

      public static Properties loadProperties()
      Loads properties from a configuration file. The method checks for a local "cli.properties" file, a file specified by the "cli.config" system property, and a default "cli.properties" file on the classpath. If none of these are found, an exception is thrown.
      Returns:
      a Properties object containing the key-value pairs from the loaded configuration file

    • authenticateWithToken

      public static AnkaSecureSdk authenticateWithToken(Properties props) throws AnkaSecureSdkException
      Creates an AnkaSecureSdk instance using a manually provided JWT token.

      This method bypasses the authentication flow entirely. It is useful for debugging or trusted execution environments where the token is issued externally (e.g. from a deployed auth-service).

      Requires the presence of a property client.accessToken in the cli.properties file.

      Warning: It is your responsibility to ensure the token is valid and not expired.

      Parameters:
      props - CLI properties loaded via loadProperties()
      Returns:
      a token-initialized AnkaSecureSdk instance
      Throws:
      AnkaSecureSdkException

    • authenticate

      public static AnkaSecureSdk authenticate(Properties props)
      Authenticates and initializes an instance of AnkaSecureSdk using the provided properties. The method retrieves client-specific credentials (UUID, salt, encrypted client ID, and encrypted client secret) from the given Properties object, derives a cryptographic key, decrypts the credentials, and performs application authentication. On successful authentication, it returns an instance of AnkaSecureSdk.
      Parameters:
      props - The Properties containing the necessary authentication information: - `client.uuid`: The unique identifier for the client. - `client.salt`: The salt value for key derivation. - `clientIdEnc`: The encrypted client ID. - `clientSecretEnc`: The encrypted client secret. All four properties must be non-null and properly initialized.
      Returns:
      An instance of AnkaSecureSdk if authentication is successful. Returns null in case of authentication or decryption errors (execution will halt with a fatal error log).

    • toJson

      public static String toJson(Object o)
      Converts a given object into its JSON string representation.
      Parameters:
      o - the object to be converted into JSON format
      Returns:
      a JSON string representation of the given object
      Throws:
      UncheckedIOException - if the JSON serialization process fails

    • ensureTempDir

      public static void ensureTempDir(Path dir)
      Ensures that the specified temporary directory exists. If it does not exist, it attempts to create it.
      Parameters:
      dir - The path to the directory that needs to be checked or created.

    • fatal

      public static void fatal(String msg, Throwable t)
      Logs a fatal error message to the standard error stream, provides additional context if the error is related to the SDK, and terminates the application with exit code 1.
      Parameters:
      msg - The error message to be logged.
      t - The exception causing the fatal error, which may be an instance of AnkaSecureSdkException or another Throwable. Can be null.

    • printEncryptionMeta

      public static void printEncryptionMeta(EncryptResult r)
      Logs metadata associated with an encryption operation in a human-readable format. This includes information about the requested key, actual key used, algorithm utilized, and any warnings generated during the process.
      Parameters:
      r - the EncryptResult containing encryption metadata, which includes: - the key ID originally requested by the client, - the key ID actually used by the server, - the algorithm used for encryption, - and any warnings or informational messages associated with the operation.

    • printDecryptionMeta

      public static void printDecryptionMeta(DecryptResultMetadata r)
      Logs decryption metadata in a human-readable format. The metadata includes details about the key requested, the actual key used, the algorithm used in the decryption process, and any non-fatal warnings encountered.
      Parameters:
      r - the DecryptResultMetadata containing decryption-related information, including: - the key ID originally requested, - the key ID actually used, - the algorithm utilized, - and any warnings, if present.

    • printWarnings

      public static void printWarnings(List<String> warnings)
      Prints a list of warning messages to the console in a formatted manner. Each warning is indented and prefixed with a bullet point.
      Parameters:
      warnings - a list of strings representing warning messages to be displayed. If the list is null or empty, no output will be generated.

    • nullSafe

      public static String nullSafe(String s)
      Returns a non-null, safe string representation of the provided input. If the input string is null or blank, the method returns the string "(none)".
      Parameters:
      s - the input string that may be null or blank
      Returns:
      the input string if it is not null or blank; otherwise, the string "(none)"

    • ensureTempDir

      public static void ensureTempDir()
      Ensures that the temporary directory represented by the constant `TEMP_DIR` exists. Creates the directory, including any necessary but nonexistent parent directories. If the operation fails, this method terminates the JVM with an error message. Any issues encountered during the creation process are handled by invoking the fatal(String, Throwable) method, which outputs the error message and exits the application. This method is typically used to guarantee the existence of a directory for temporary file storage required by the application.
      Throws:
      UncheckedIOException - if the directory cannot be created

    • printSignMeta

      public static void printSignMeta(SignResult r)
      Logs metadata associated with the signing operation in a human-readable format. Includes details such as the requested key, actual key used, algorithm, and any warnings.
      Parameters:
      r - the SignResult containing metadata about the signing operation, which includes: - the key ID originally requested by the client, - the key ID actually used by the server, - the algorithm used during the signing process, - and any non-fatal warnings, if present.

    • printVerifyMeta

      public static void printVerifyMeta(VerifySignatureResult r)
      Logs metadata associated with the verification operation in a human-readable format. Includes details about the requested key, actual key used, algorithm utilized, and any warnings generated.
      Parameters:
      r - the VerifySignatureResult containing verification metadata, which includes: - the key ID originally requested by the client, - the key ID actually used by the server, - the algorithm used during the verification process, - and any non-fatal warnings, if present.

    • printEncryptMeta

      public static void printEncryptMeta(EncryptResult m)
      Logs metadata associated with an encryption operation in a human-readable format. Includes details about the key requested, actual key used, algorithm utilized, and any warnings generated.
      Parameters:
      m - the EncryptResult containing encryption metadata, which includes: - the key ID originally requested by the client, - the key ID actually used by the server, - the algorithm used during the encryption process, - and any non-fatal warnings, if present.

    • printDecryptMeta

      public static void printDecryptMeta(DecryptResultMetadata m)
      Logs decryption metadata in a human-readable format, including information about the requested key, actual key used, algorithm used, and any warnings.
      Parameters:
      m - the DecryptResultMetadata containing the metadata for the decryption process. It includes: - the key ID originally requested by the client, - the key ID actually used by the server, - the algorithm negotiated by the crypto engine, - and non-fatal warnings, if any.

    • streamsAreEqual

      public static boolean streamsAreEqual(InputStream a, InputStream b) throws IOException
      Compares two InputStream objects to determine if they have identical content. This method reads both streams concurrently and compares their data byte by byte.
      Parameters:
      a - the first InputStream to compare
      b - the second InputStream to compare
      Returns:
      true if both InputStreams have identical content and reach EOF simultaneously; false otherwise
      Throws:
      IOException - if an I/O error occurs while reading from either InputStream

    • printReencryptMeta

      public static void printReencryptMeta(ReencryptResult m)
      Logs metadata associated with the re-encryption operation in a human-readable format, including information about keys and algorithms used during the process, as well as any warnings.
      Parameters:
      m - the ReencryptResult containing metadata related to the re-encryption operation, including details such as the old key requested, old key used, old algorithm, new key requested, new key used, new algorithm, and any warnings associated.

    • printSignMeta

      public static void printSignMeta(String heading, SignResult m)
      Logs metadata associated with the signing operation in a human-readable format, including a descriptive heading for context.
      Parameters:
      heading - a contextual or descriptive heading to prepend to the logged output
      m - the SignResult containing metadata about the signing process

    • printResignMeta

      public static void printResignMeta(ResignResult m)
      Logs metadata associated with the re-signing operation in a human-readable format.
      Parameters:
      m - the ResignResult containing metadata about the re-signing process

    • printVerifyMeta

      public static void printVerifyMeta(String heading, VerifySignatureResult m)
      Logs metadata associated with the verification operation in a human-readable format, including information about validation, keys used, algorithm, and warnings if any.
      Parameters:
      heading - a descriptive heading or context label for the logged output
      m - the VerifySignatureResult containing verification metadata

    • printDecryptMeta

      public static void printDecryptMeta(DecryptResult r)
      Logs decryption-side metadata in a human-readable format.
      Parameters:
      r - the DecryptResult containing the decryption metadata and decrypted data. Its metadata includes: - the key ID originally requested by the client, - the key ID actually used by the server (or null if identical to the requested key), - the algorithm negotiated by the crypto-engine, - and non-fatal warnings, if any.