Package co.ankatech.ankasecure.sdk

Class AnkaSecureSdk

Object
AnkaSecureSdk
public class AnkaSecureSdk extends Object

AnkaSecureSdk is a high-level facade that applications or CLI tools can use to interact with the AnkaSecure REST API. It provides streamlined methods for key management (generate, import, export, remove, revoke), cryptographic operations (encrypt, decrypt, sign, verify, re-encrypt, re-sign), and streaming-based versions of these operations, without exposing internal OpenAPI classes in user-facing code.

Usage Steps:

  1. Construct an instance using AnkaSecureSdk(Properties). Supply the necessary properties (e.g., endpoint URLs, timeouts, etc.).
  2. Authenticate either as an application via authenticateApplication(String, String) or as a user via authenticateUser(String, String).
  3. Use methods like generateKey(GenerateKeySpec), importKey(ImportKeySpec), encryptFile(String, String, String), signFile(String, String, String), etc., passing only SDK model classes (e.g., GenerateKeySpec, ImportKeySpec, ExportedKeySpec, etc.).
  4. Handle exceptions by catching AnkaSecureSdkException, which centralizes HTTP errors, parsing issues, and other failures.

Example: 


 // Example usage in a main() method or another client
 Properties props = new Properties();
 // props.load(...) or set relevant properties like endpoint URL, etc.

 AnkaSecureSdk sdk = new AnkaSecureSdk(props);
 
 // Authenticate as an application
 sdk.authenticateApplication("myClientId", "myClientSecret");

 // Generate a new key
 GenerateKeySpec generateSpec = new GenerateKeySpec();
 generateSpec.setKid("myKeyId");
 generateSpec.setKty("RSA");
 generateSpec.setAlg("RSA-2048");
 sdk.generateKey(generateSpec);

 // Encrypt a file
 sdk.encryptFile("myKeyId", "plaintext.txt", "ciphertext.bin");

 // Decrypt the file
 sdk.decryptFile("myKeyId", "ciphertext.bin", "decrypted.txt");

  • Constructor Details

    • AnkaSecureSdk

      public AnkaSecureSdk(Properties cliProperties)
      Constructs the SDK with the provided CLI properties. These properties are typically loaded from a resource file such as "cli.properties," and may include details like API endpoints, timeouts, or other configuration parameters required to initialize the underlying AnkaSecureOpenApiClient.

      Example:

      
 Properties props = new Properties();
 props.load(new FileInputStream("cli.properties"));
 AnkaSecureSdk sdk = new AnkaSecureSdk(props);
      Parameters:
      cliProperties - loaded properties (e.g., from a file) that configure the SDK

  • Method Details

    • authenticateApplication

      public void authenticateApplication(String clientId, String clientSecret)
      Authenticates an application using client credentials (clientId/clientSecret). After calling this, future operations in the same AnkaSecureSdk instance will include the appropriate authentication token.

      Example:

      
 sdk.authenticateApplication("clientId123", "secretXYZ");
      Parameters:
      clientId - the client ID issued by the Anka Secure platform
      clientSecret - the client secret associated with the client ID
      Throws:
      AnkaSecureSdkException - if authentication fails for any reason

    • authenticateUser

      public void authenticateUser(String username, String password)
      Authenticates a user by username/password. In scenarios where user-level context is required (e.g., user-based roles/permissions), use this method instead of authenticateApplication(String, String).

      Example:

      
 sdk.authenticateUser("[email protected]", "P@ssw0rd");
      Parameters:
      username - the username
      password - the user password
      Throws:
      AnkaSecureSdkException - if authentication fails

    • generateKey

      public void generateKey(GenerateKeySpec spec) throws AnkaSecureSdkException
      Creates a new cryptographic key in the Anka Secure platform using parameters from GenerateKeySpec. Supports classical and PQC algorithms, as well as symmetric keys.

      Example:

      
 GenerateKeySpec spec = new GenerateKeySpec();
 spec.setKid("myKeyId");
 spec.setKty("RSA");
 spec.setAlg("RSA-2048");
 spec.setExportable(true);
 
 // Optionally set usage limits or expiration
 spec.setMaxUsageLimit(10000);
 spec.setSoftUsageLimit(8000);

 sdk.generateKey(spec);
      Parameters:
      spec - the specification object containing kid, kty, alg, optional key operations, exportability, and usage constraints
      Throws:
      AnkaSecureSdkException - if the API call fails (e.g., invalid params, network error)

    • importKey

      public void importKey(ImportKeySpec keyData)
      Imports an existing key by providing its fields in a ImportKeySpec. One can import a public key, private key, or both, along with key usage restrictions, expiration times, and usage limits.

      Example:

      
 ImportKeySpec importSpec = new ImportKeySpec();
 importSpec.setKid("importedKey");
 importSpec.setKty("RSA");
 importSpec.setAlg("RSA-2048");
 importSpec.setPublicKey("BASE64_ENCODED_PUBKEY");
 importSpec.setPrivateKey("BASE64_ENCODED_PRIVKEY"); // optional
 
 sdk.importKey(importSpec);
      Parameters:
      keyData - an ImportKeySpec containing all necessary metadata and key material
      Throws:
      AnkaSecureSdkException - if the API call fails (e.g., invalid format, server error)

    • importPrivateKeyPkcs12

      public void importPrivateKeyPkcs12(Pkcs12ImportSpec p12spec)
      Imports a private key from a PKCS#12 (.p12) file that has been encoded in Base64. Optionally, you can supply a password if the PKCS#12 file is protected.

      Example:

      
 Pkcs12ImportSpec p12spec = new Pkcs12ImportSpec();
 p12spec.setKid("myPkcs12Key");
 p12spec.setP12FileBase64("BASE64_ENCODED_CONTENT_OF_P12");
 p12spec.setP12Password("optionalPassword");

 sdk.importPrivateKeyPkcs12(p12spec);
      Parameters:
      p12spec - a Pkcs12ImportSpec containing kid, Base64-encoded PKCS#12 data, and an optional password
      Throws:
      AnkaSecureSdkException - if the API call fails or the PKCS#12 is invalid

    • listKeys

      public String listKeys()
      Lists all keys (without revealing any private key material) and returns a human-readable string summarizing them.

      Note: If you need structured data instead of a human-readable string, see openApiClient.listKeys() directly or adapt this method.

      Example:

      
 String keyList = sdk.listKeys();
 System.out.println(keyList);
      Returns:
      a String describing all keys and their basic metadata
      Throws:
      AnkaSecureSdkException - if the API call fails

    • exportKey

      public void exportKey(String kid, String outputFile)
      Exports the full key (public portion if asymmetric, plus metadata) to a JSON file on disk. The output includes fields such as kid, kty, alg, key_ops, createdAt, expiresAt, usageCount, etc.

      Example:

      
 sdk.exportKey("myKeyId", "exportedKey.json");
      Parameters:
      kid - the ID of the key to be exported
      outputFile - the path to the file where the JSON output will be stored
      Throws:
      AnkaSecureSdkException - if the API call fails or an I/O error occurs

    • exportKey

      public ExportedKeySpec exportKey(String kid)
      Exports the key from the server in a structured form, returning an ExportedKeySpec instead of writing to disk. This method converts date/time fields into ZonedDateTime to make them easier to use programmatically.

      Example:

      
 ExportedKeySpec eks = sdk.exportKey("myKeyId");
 System.out.println("Public Key Base64: " + eks.getPublicKey());
      Parameters:
      kid - the ID of the key to be exported
      Returns:
      an ExportedKeySpec containing public key material (if any) and additional metadata
      Throws:
      AnkaSecureSdkException - if the API call fails or if parsing fails

    • removeKey

      public void removeKey(String kid)
      Removes a key (by kid) from the keystore. This is irreversible: once removed, the key cannot be recovered or used for cryptographic operations.

      Example:

      
 sdk.removeKey("myKeyId");
      Parameters:
      kid - the key ID to remove
      Throws:
      AnkaSecureSdkException - if the API call fails

    • revokeKey

      public void revokeKey(String kid)
      Revokes a key by kid. Once revoked, the key cannot be used for future encryption/signing, and its status becomes "REVOKED."

      Example:

      
 sdk.revokeKey("myKeyId");
      Parameters:
      kid - the key ID to revoke
      Throws:
      AnkaSecureSdkException - if the API call fails

    • getSupportedAlgorithms

      public List<AlgorithmInfo> getSupportedAlgorithms()
      Retrieves a list of supported algorithms from the server, returning them as a list of AlgorithmInfo (kty+alg).

      Example:

      
 List<AlgorithmInfo> algos = sdk.getSupportedAlgorithms();
 for (AlgorithmInfo ai : algos) {
     System.out.println(ai.getKty() + " / " + ai.getAlg());
 }
      Returns:
      a list of AlgorithmInfo objects
      Throws:
      AnkaSecureSdkException - if the API call fails

    • getLicenseInfo

      public String getLicenseInfo(String clientId)
      Retrieves license information for a given clientId. Returns a human-readable string with details about the contract type, expiry date, and usage.

      Example:

      
 String licenseInfo = sdk.getLicenseInfo("myClientId");
 System.out.println(licenseInfo);
      Parameters:
      clientId - the client ID whose license information you want to retrieve
      Returns:
      a string summarizing license details
      Throws:
      AnkaSecureSdkException - if the API call fails

    • encryptFile

      public void encryptFile(String kid, String inputFile, String outputFile)
      Encrypts a file with the specified key (kid) on the server using the public key portion. Reads plaintext from inputFile, encodes it to Base64 for transmission, and writes raw binary ciphertext to outputFile.

      Example:

      
 sdk.encryptFile("myKeyId", "plaintext.txt", "ciphertext.bin");
      Parameters:
      kid - the key ID
      inputFile - path to the plaintext file
      outputFile - path to write the resulting ciphertext (binary)
      Throws:
      AnkaSecureSdkException - if encryption fails (invalid key, I/O error, etc.)

    • decryptFile

      public void decryptFile(String kid, String inputFile, String outputFile)
      Decrypts a file using the private key (kid) on the server. Expects inputFile to contain the raw binary ciphertext. The method encodes it to Base64, sends it for decryption, and writes the returned plaintext (decoded from Base64) to outputFile.

      Example:

      
 sdk.decryptFile("myKeyId", "ciphertext.bin", "recovered.txt");
      Parameters:
      kid - the key ID
      inputFile - path to the ciphertext file (binary)
      outputFile - path to write plaintext data
      Throws:
      AnkaSecureSdkException - if decryption fails (invalid key, I/O error, etc.)

    • signFile

      public void signFile(String kid, String inputFile, String signatureFile)
      Signs a file with the specified private key (kid). Reads the data from inputFile, encodes it to Base64 for transmission, and writes the raw binary signature to signatureFile.

      Example:

      
 sdk.signFile("myKeyId", "document.pdf", "document.sig");
      Parameters:
      kid - the key ID (private key)
      inputFile - the data file to be signed
      signatureFile - the path to write the signature in binary form
      Throws:
      AnkaSecureSdkException - if signing fails

    • verifySignature

      public boolean verifySignature(String kid, String inputFile, String signatureFile)
      Verifies a signature using the key (kid), which must include a public key portion. Reads both data and signature as binary files, converts them to Base64, and calls the server to verify.

      Example:

      
 boolean valid = sdk.verifySignature("myKeyId", "document.pdf", "document.sig");
 System.out.println("Signature valid? " + valid);
      Parameters:
      kid - the key ID (public key portion is needed for verification)
      inputFile - the data whose signature is being verified
      signatureFile - the binary signature file
      Returns:
      true if the signature is valid, false otherwise
      Throws:
      AnkaSecureSdkException - if verification fails

    • reencryptFile

      public void reencryptFile(String oldKid, String newKid, String inputFile, String outputFile)
      Re-encrypts data originally encrypted by oldKid (private key needed), so that it becomes encrypted under newKid (public key). This is especially useful for rotating keys in a production environment without first decrypting data locally.

      Flow:

      1. Data is decrypted with oldKid.
      2. The resulting plaintext is re-encrypted with newKid.
      3. The new ciphertext is returned and written to outputFile.

      Example:

      
 sdk.reencryptFile("oldKeyId", "newKeyId", "oldCipher.bin", "newCipher.bin");
      Parameters:
      oldKid - the old key ID (private)
      newKid - the new key ID (public)
      inputFile - the existing ciphertext
      outputFile - the new ciphertext after re-encryption
      Throws:
      AnkaSecureSdkException - if the server call fails or I/O error occurs

    • resignFile

      public void resignFile(String oldKid, String newKid, String inputFile, String oldSignatureFile, String newSignatureFile)
      Re-signs data: verifies its signature with oldKid (public key) and then signs again with newKid (private key).

      Flow:

      1. Verifies the old signature with oldKid.
      2. Re-signs the data using newKid.
      3. Writes the new signature to newSignatureFile.

      Example:

      
 sdk.resignFile("oldKeyId", "newKeyId", "document.pdf", "oldSignature.sig", "newSignature.sig");
      Parameters:
      oldKid - the old key ID (public portion for verification)
      newKid - the new key ID (private portion for signing)
      inputFile - the data file that was originally signed
      oldSignatureFile - the old signature file (binary)
      newSignatureFile - the new signature file to create (binary)
      Throws:
      AnkaSecureSdkException - if the re-sign operation fails

    • encryptFileStream

      public void encryptFileStream(String kid, String inputFile, String outputFile)
      Encrypts a file in streaming mode on the server. This method is particularly useful for very large files, as it does not require loading the entire file into memory at once.

      Example:

      
 sdk.encryptFileStream("myKeyId", "largeDocument.pdf", "largeDocument.enc");
      Parameters:
      kid - the key ID
      inputFile - path to the input file
      outputFile - path to the resulting encrypted file

    • decryptFileStream

      public void decryptFileStream(String kid, String inputFile, String outputFile)
      Decrypts a file in streaming mode using the server-side private key. Useful for very large ciphertext files.

      Example:

      
 sdk.decryptFileStream("myKeyId", "largeDocument.enc", "largeDocument.dec");
      Parameters:
      kid - the key ID (private)
      inputFile - path to the ciphertext file
      outputFile - path to the resulting plaintext file

    • signFileStream

      public void signFileStream(String kid, String inputFile, String signatureFile)
      Signs a file in streaming mode with the server-side private key. This allows large files to be processed without loading them entirely into memory.
      Parameters:
      kid - the key ID (private)
      inputFile - path to the file to be signed
      signatureFile - path to store the resulting signature

    • verifySignatureStream

      public boolean verifySignatureStream(String kid, String inputFile, String signatureFile)
      Verifies a signature in streaming mode. Reads the signature as binary, encodes it in Base64, and sends it to the server along with the streaming input file.
      Parameters:
      kid - the key ID (public portion)
      inputFile - path to the data file
      signatureFile - path to the binary signature file
      Returns:
      true if the signature is valid, false otherwise

    • resignFileStream

      public void resignFileStream(String oldKid, String newKid, String oldSignaturePath, String inputFile, String newSignatureFile)
      Re-signs a file in streaming mode. Similar to resignFile(String, String, String, String, String), but for large files.
      Parameters:
      oldKid - the old key ID (public)
      newKid - the new key ID (private)
      oldSignaturePath - path to the binary file containing the old signature
      inputFile - the file to re-sign
      newSignatureFile - the file to write the new signature (binary)

    • reencryptFileStream

      public void reencryptFileStream(String oldKid, String newKid, String inputFile, String outputFile)
      Re-encrypts a file in streaming mode from oldKid to newKid. This allows large files to be processed without loading them entirely into memory at once.
      Parameters:
      oldKid - the old key ID (private)
      newKid - the new key ID (public)
      inputFile - the current ciphertext
      outputFile - the new ciphertext after re-encryption

    • encryptFileUtilityStream

      public void encryptFileUtilityStream(String kty, String alg, String publicKeyBase64, String inputFile, String outputFile)
      Encrypts a file in streaming mode using a provided public key in Base64, without referencing a kid from the keystore. This is useful for ephemeral or external keys not stored in the server's keystore.
      Parameters:
      kty - the key type (e.g. "RSA", "ML-KEM")
      alg - the algorithm (e.g. "RSA-2048", "ML-KEM-768")
      publicKeyBase64 - the public key in Base64
      inputFile - path to the plaintext file
      outputFile - path to the resulting encrypted file

    • verifySignatureUtilityStream

      public boolean verifySignatureUtilityStream(String kty, String alg, String publicKeyBase64, String signatureBase64, String inputFile)
      Verifies a signature in streaming mode using a provided public key in Base64, rather than looking up a key in the server keystore. This is helpful for verifying data from external key material.
      Parameters:
      kty - the key type
      alg - the algorithm
      publicKeyBase64 - the public key in Base64
      signatureBase64 - the signature in Base64
      inputFile - path to the file containing the signed data
      Returns:
      true if the signature is valid