Skip to content

Key Store Providers

This document describes how ANKA Secure manages cryptographic keys, including: - BouncyCastle (BKS) Keystore usage - Dynamic Key Providers (e.g., environment, HSM) - Alternate Providers (AWS KMS, Azure Vault) for future flexibility - Key Management Endpoints referencing the keystore

1. Overview

ANKA Secure supports multiple ways of storing and managing keys:

  1. Local Keystore (BouncyCastle) using .bks files
  2. AWS KMS (dummy example in the code, can be extended for real usage)
  3. Other Cloud Providers (Azure Key Vault, HSM, etc.) planned for future integration

This modular approach is powered by interfaces like KeyStoreProvider, allowing you to switch storage mechanisms without changing core application code.

2. BouncyCastle (BKS) Keystore

By default, the application uses a local BouncyCastle (BKS) keystore. This keystore: - Stores keys and certificates in a file (e.g., config/keys/keystore.bks). - Is password-protected, with the password itself (or an encrypted version) retrieved at runtime via the dynamic key.

2.1 How It Works

1.Configuration: 

keystore:
  type: ${KEYSTORE_TYPE:BKS}
  filename: ${KEYSTORE_FILENAME:config/keys/keystore.bks}
  password:
    encrypted: ${KEYSTORE_PASSWORD_ENCRYPTED:AXvX5YS5m3ng2kwbKA7sYQ==}
    salt: ${KEYSTORE_SALT:6edkdkesCiy7Y+RqypHUrg==}
    iv: ${KEYSTORE_IV:3qSdEK/py4fn7TeURPQUrw==}

  • keystore.type: BKS (file-based using BouncyCastle).
  • keystore.filename: Path to the .bks file.
  • keystore.password.encrypted, salt, and iv: Used to decrypt the actual keystore password at runtime.

2.Loading the Keystore

  • BcKeyStoreProvider checks if the keystoreFilename file exists.
    • If yes, it loads the BKS file using the decrypted password.
    • If no, it creates a new keystore from scratch and saves it immediately.

3.Accessing & Modifying Entries

  • The KeyStoreProvider interface defines methods like getEntry, setEntry, containsAlias, etc.

  • BcKeyStoreProvider implements these methods by calling the underlying BouncyCastle KeyStore.

  • After adding or removing entries, BcKeyStoreProvider saves changes back to the .bks file.

4.Persisting Changes

  • After adding or removing entries, BcKeyStoreProvider saves changes back to the .bks file.

2.2 SecureCoreConfig: Reading Keystore Settings from application.yaml

Beyond just having these properties in application.yaml, SecureCoreConfig (shown below) is the central configuration class that reads those properties, decrypts the keystore password, and initializes the appropriate KeyStoreProvider.

Key Steps:

  1. Property Injection Property Injection: 

    @Value("${keystore.filename}")
private String keystoreFilename;

@Value("${keystore.password.encrypted}")
private String encryptedPassword;

@Value("${keystore.salt}")
private String saltBase64;

@Value("${keystore.iv}")
private String ivBase64;

@Value("${keystore.type:BKS}")
private String keystoreType;

    • These fields pull in the YAML values (e.g., keystore.filename, keystore.password.encrypted, etc.).
    • Defaults are specified where needed (e.g., BKS if none is provided).

  2. Decrypting the Keystore Password

    • SecureCoreConfig uses a DynamicKeyProvider to retrieve the dynamic password at runtime (e.g., from an environment variable).
    • It then calls KeyEncryptionUtil.deriveKey(...) and decrypts the Base64-encoded password.
    • Result: A plaintext keystore password is available for loading the .bks file.

  3. Selecting the Provider 

        if ("AWSKMS".equalsIgnoreCase(providerType)) {
        return new AwsKmsKeyStoreProvider();
    } else {
        return new BcKeyStoreProvider(keystoreFilename, keystorePassword);
    }

    • If the YAML says "AWSKMS", we instantiate an AWS provider (dummy in current code).
    • Otherwise (default), use BcKeyStoreProvider to manage a BouncyCastle .bks file.

  4. Bean Creation

    • Methods like @Bean public KeyStoreProvider keyStoreProvider() produce the Spring-managed bean.
    • Other beans (SymmetricEncryptionService, KeyManagementService, etc.) receive the KeyStoreProvider to load and store keys as needed.

Why Is This Important?

  • It bridges the gap between your YAML config and the actual KeyStoreProvider logic.
  • Every time you start ANKA Secure, it reads these properties, decrypts the password if necessary, and instantiates the correct provider.
  • If you change keystore.type to "AWSKMS", SecureCoreConfig automatically sets up the AwsKmsKeyStoreProvider instead of BcKeyStoreProvider.

3. Dynamic Key Provider

In addition to the keystore's own password, you can have an encrypted keystore password in YAML, which is decrypted at runtime using a dynamic key. The dynamic key itself can come from different sources:

dynamic:
  key:
  provider: ${DYNAMIC_KEY_PROVIDER:env}
  env: ${DYNAMIC_KEY_ENV:DYNAMIC_KEY_PASSWORD}
  • provider: Determines the source of the key used to decrypt the actual keystore password.
    • env → EnvironmentDynamicKeyProvider (reads from an environment variable)
    • hsm → HsmDynamicKeyProvider (a stub for now, can integrate with an HSM)
  • env: The name of the system property or environment variable (e.g., DYNAMIC_KEY_PASSWORD).

By doing this:

  1. Keystore Password is stored encrypted in application.yaml.
  2. Dynamic Key is retrieved from an environment variable or HSM at startup.
  3. The application decrypts keystore.password.encrypted using this dynamic key to get the final BKS password.
  4. The BouncyCastle keystore is then unlocked.

3.1 Generating an Encrypted Keystore Password

To secure your keystore password, ANKA Secure provides a standalone utility class called co.ankatech.secure.api.util.GenerateEncryptedKey.java This utility demonstrates how to produce the salt, IV, and encrypted keystore password you place into application.yaml. At runtime, the dynamic password (from an environment variable or HSM) decrypts it.

Steps to Use:

  1. Run:

    • java co.ankatech.secure.api.util.GenerateEncryptedKey

  2. Copy the Outputs

    • Base64-encoded Salt
    • Base64-encoded IV
    • Encrypted keystore password (Base64)

  3. Paste

into the YAML: 

keystore:
  password:
    encrypted: <EncryptedKeystorePasswordBase64>
    salt: <SaltBase64>
    iv: <IVBase64>`

4.Dynamic Password - Provide the "real" password at runtime via an environment variable, e.g., DYNAMIC_KEY_PASSWORD.

5.Decryption at Startup - The application derives a key from DYNAMIC_KEY_PASSWORD + salt, uses the IV, and decrypts the keystore password behind the scenes.

Security Note: The fixed keystore password in GenerateEncryptedKey should not remain hardcoded for production. Instead, replace it with your actual keystore password only in a local or secure environment, then store the generated encrypted, salt, and iv in your configuration.

4. Alternate Providers

4.1 AWS KMS

A dummy provider, AwsKmsKeyStoreProvider, showcases how you can integrate with AWS KMS. In a real-world scenario, the methods would:

  • Call AWS KMS APIs to retrieve keys, sign/encrypt data, or manage aliases.
  • Possibly store a reference to the key in KMS, rather than retrieving raw key material.

When keystore.type is set to AWSKMS:

  1. The application instantiates AwsKmsKeyStoreProvider instead of BcKeyStoreProvider.
  2. All calls to the KeyStoreProvider interface methods either:
    • Perform real KMS operations (if fully implemented), or
    • Throw UnsupportedOperationException (in the dummy version).

4.2 Azure Vault / Others

You can add more provider classes (e.g., AzureKeyVaultProvider) that implement KeyStoreProvider. By switching the keystore.type, you can direct the application to:

  • Use a local BKS file,
  • Use AWS KMS,
  • Use Azure Key Vault,\ ... or any other secure store.

5. Key Management Endpoints

Key Management Endpoints in the ANKA Secure API (e.g., /api/key-management/**) rely on a KeyStoreProvider to:

  • Import keys/certificates,
  • Generate new keys,
  • Retrieve and export keys,
  • Delete or rotate keys.

Because the endpoints call the KeyStoreProvider interface, they remain agnostic to whether the keys are in a local .bks file, AWS KMS, or another provider.

Example Flow

  1. Client calls POST /api/key-management/asymmetric to generate an asymmetric key pair.
  2. Service Layer checks the configured keystore.type:
    • If BKS, it delegates to BcKeyStoreProvider → stores the key pair in the local .bks file.
    • If AWSKMS, it would call the KMS provider → real or stub logic in AwsKmsKeyStoreProvider.
  3. Response indicates success or any error.

6. Switching to a Different Keystore

  1. Update application.yaml (or environment variables): 
    keystore:
  type: AWSKMS

This instructs the application to use the AWS KMS provider instead of the local BKS keystore.

  1. Implement the provider if it's not a dummy example (e.g., AzureKeyVaultProvider, HsmDynamicKeyProvider).

  2. Redeploy the application with new settings. The KeyStoreProvider injection ensures your existing logic (e.g., Key Management Endpoints) continues to work without code changes outside the provider.

7. Future Extensibility

  • Cloud HSM: If you have a hardware security module (HSM) on-premise or in a cloud environment, you could implement a HsmKeyStoreProvider.
  • Additional Dynamic Keys: For advanced scenarios (e.g., short-lived ephemeral keys), you could expand dynamic.key.provider to fetch from a remote vault or KMS rotation logic.
  • Multi-Provider Setup: If certain keys live in BKS and others in KMS, you might expand your configuration to route calls dynamically based on alias or usage type.

8. Summary

ANKA Secure's key management is modular and extensible:

  • By default, a BouncyCastle keystore (.bks file) is used, but you can switch to AWS KMS or future providers with minimal changes.
  • The dynamic key approach allows the application to decrypt keystore passwords at runtime, enhancing security and flexibility.
  • Key Management Endpoints remain provider-agnostic, calling KeyStoreProvider methods that handle storing and retrieving cryptographic material.

This design ensures that as your infrastructure evolves---e.g., migrating from a local keystore to a cloud service---ANKA Secure can adapt quickly without requiring a full rewrite of your cryptographic logic.

9. References