Package co.ankatech.ankasecure.sdk

Class AnkaSecureSdk

java.lang.Object
co.ankatech.ankasecure.sdk.AnkaSecureSdk
public class AnkaSecureSdk extends Object
Factory for creating authenticated SDK instances.

AnkaSecureSdk serves as the entry point for the ANKASecure© SDK. It handles authentication and returns immutable AuthenticatedSdk instances that provide all cryptographic and key management operations.

New Architecture (v3.0.0)

Unlike previous versions where the SDK was mutable and stateful, the new architecture separates concerns:

  • AnkaSecureSdk (Factory) - Handles authentication only
  • AuthenticatedSdk (Immutable) - Performs all operations
This design enables:
  • Thread-safe concurrent access (10,000+ threads)
  • Clear token lifecycle management
  • Multiple independent sessions from one factory

Basic Usage


 // 1. Load configuration
 Properties props = new Properties();
 try (var in = new FileInputStream("cli.properties")) {
     props.load(in);
 }

 // 2. Create factory (reusable)
 AnkaSecureSdk factory = new AnkaSecureSdk(props);

 // 3. Authenticate and get SDK instance
 AuthenticatedSdk sdk = factory.authenticateApplication("clientId", "secret");

 // 4. Perform operations
 EncryptResult result = sdk.encrypt("my-key", data);

Thread-Safe Concurrent Usage


 AnkaSecureSdk factory = new AnkaSecureSdk(props);
 AuthenticatedSdk sdk = factory.authenticateApplication("clientId", "secret");

 // Share SDK across thousands of threads safely
 try (ExecutorService executor = Executors.newVirtualThreadPerTaskExecutor()) {
     List<CompletableFuture<EncryptResult>> futures = dataList.stream()
         .map(data -> CompletableFuture.supplyAsync(
             () -> sdk.encrypt("key", data),
             executor
         ))
         .toList();

     List<EncryptResult> results = futures.stream()
         .map(CompletableFuture::join)
         .toList();
 }

Multiple Sessions


 AnkaSecureSdk factory = new AnkaSecureSdk(props);

 // Different authenticated sessions from same factory
 AuthenticatedSdk appSdk = factory.authenticateApplication("app", "secret");
 AuthenticatedSdk userSdk = factory.authenticateUser("[email protected]", "pass", "tenant");

 // Each operates independently
 appSdk.encrypt("key1", data1);
 userSdk.listKeys();

Token Lifecycle Management


 AuthenticatedSdk sdk = factory.authenticateApplication("client", "secret");

 // Check expiry before long-running operations
 if (sdk.isTokenExpiredLocally()) {
     sdk = factory.authenticateApplication("client", "secret");
 }

 processBatch(sdk, largeDataset);

Configuration

The SDK is configured via cli.properties file. Key settings for high-concurrency scenarios: 

 # Connection pool (optimized for 10,000+ concurrent threads)
 okhttp.pool.maxIdleConnections=1000
 okhttp.pool.keepAliveDurationMinutes=5

 # Dispatcher limits
 okhttp.dispatcher.maxRequests=10000
 okhttp.dispatcher.maxRequestsPerHost=5000

 # HTTP/2 support (enabled by default)
 okhttp.http2.enabled=true

 # Rate limiting (0 = disabled)
 okhttp.rateLimitPerSecond=1000
Since:
3.0.0
Author:
ANKATech Solutions Inc.
See Also:

  • Constructor Details

    • AnkaSecureSdk

      public AnkaSecureSdk(Properties cliProperties)
      Constructs the SDK factory using the provided CLI properties.

      This constructor creates an unauthenticated SDK factory. To obtain an authenticated instance, call authenticateApplication(String, co.ankatech.ankasecure.sdk.security.SecretChars) or authenticateUser(String, co.ankatech.ankasecure.sdk.security.SecretChars, String).

      Typical properties include:

      • openapi.host – API server hostname
      • openapi.port – API server port
      • openapi.connectTimeoutMs – connection timeout in milliseconds
      • okhttp.pool.maxIdleConnections – connection pool size (default: 1000)
      • okhttp.dispatcher.maxRequests – max concurrent requests (default: 10000)
      • okhttp.http2.enabled – enable HTTP/2 (default: true). Setting it to false makes the true-streaming operations refuse rather than downgrade: they send their request body as a duplex stream, which HTTP/1.1 cannot frame, so a downgrade would deadlock instead of degrading. The refusal is typed and is raised before any request byte is written.

        The same applies to the SCHEME: HTTP/2 is not negotiated over an http:// origin without prior knowledge, so a cleartext deployment (openapi.scheme=http) cannot use the streaming operations at all. Use https.

      
 Properties props = new Properties();
 try (var stream = new FileInputStream("cli.properties")) {
     props.load(stream);
 }
 AnkaSecureSdk factory = new AnkaSecureSdk(props);
 AuthenticatedSdk sdk = factory.authenticateApplication("clientId", "secret");
      Parameters:
      cliProperties - properties loaded from your cli.properties file; must not be null
      Throws:
      NullPointerException - if cliProperties is null
      Since:
      3.0.0

  • Method Details

    • authenticateApplication

      public AuthenticatedSdk authenticateApplication(String clientId, SecretChars clientSecret) throws AnkaSecureSdkException
      Authenticates as an application and returns an authenticated SDK instance.

      This method performs application authentication via client credentials and returns an immutable AuthenticatedSdk instance bound to the JWT access token. The returned instance is thread-safe and can be shared across thousands of concurrent threads.

      Usage Pattern

      
 AnkaSecureSdk factory = new AnkaSecureSdk(props);
 AuthenticatedSdk sdk = factory.authenticateApplication("clientId", "secret");

 // Use sdk for all operations
 EncryptResult result = sdk.encrypt("my-key", data);

 // Share across threads safely
 executor.submit(() -> sdk.encrypt("key1", data1));
 executor.submit(() -> sdk.encrypt("key2", data2));

      Token Lifecycle

      The returned instance remains valid until the JWT token expires. Check AuthenticatedSdk.isTokenExpiredLocally() before long-running operations and re-authenticate if needed.

      Parameters:
      clientId - the client identifier issued by the administration console; must not be null
      clientSecret - the client secret issued by the administration console; must not be null
      Returns:
      an authenticated SDK instance with immutable token; never null
      Throws:
      AnkaSecureSdkException - if the credentials are invalid, the server is unreachable, or authentication fails
      NullPointerException - if clientId or clientSecret is null
      Since:
      3.0.0

    • authenticateUser

      public AuthenticatedSdk authenticateUser(String username, SecretChars password, String tenantId) throws AnkaSecureSdkException
      Authenticates as a user and returns an authenticated SDK instance.

      This method performs user authentication via username/password and returns an immutable AuthenticatedSdk instance bound to the JWT access token. Use this in scenarios where user-level context is required instead of application-level authentication.

      Usage Pattern

      
 AnkaSecureSdk factory = new AnkaSecureSdk(props);
 AuthenticatedSdk sdk = factory.authenticateUser("[email protected]", "password", "tenant-id");

 // Use sdk for all operations with user context
 List<KeyMetadata> keys = sdk.listKeys();
      Parameters:
      username - the username (email format); must not be null
      password - the user password; must not be null
      tenantId - the tenant identifier; must not be null
      Returns:
      an authenticated SDK instance with immutable token; never null
      Throws:
      AnkaSecureSdkException - if the credentials are invalid, the user does not exist, the tenant does not exist, the server is unreachable, or authentication fails
      NullPointerException - if any parameter is null
      Since:
      3.0.0