BYOC: Update Secrets Manager Keystore

The Secrets Manager (SM) service uses a dedicated keystore to generate and protect platform key material. For Proof of Concepts, you may use the installer-generated alias values. For production, you must regenerate these aliases so they are unique to your environment and do not rely on defaults.

This keystore is used for two related purposes:

CMK storage (primary purpose): SM stores the Customer Master Key (CMK) in the keystore as a SecretKeyEntry. This key is used to encrypt and decrypt data encryption keys (DEKs). Platform data is then encrypted and decrypted using those DEKs.
Key-pair entry (supporting purpose): SM also maintains an asymmetric NIST P-384 key pair in the keystore as a PrivateKeyEntry (certificate subject CN=sm-keystore). This key pair may be used by SM for cryptographic operations such as digital signatures.

Important: Because the CMK is stored in this keystore, replacing sm-service.p12 without a defined key migration/rotation process can make previously protected data unrecoverable.

Secrets Manager Keystore Requirements

The following files are expected on backend-1 in <installer_dir>/certificates/<analytics_internal_domain>/:

sm-service.p12 – SM keystore (PKCS#12)
sm-service-keystore.pass – Keystore password

BYOC Secrets Manager Best Practices

Aliases: The SM service reads the keystore entry aliases from the configuration files. These aliases must match the entries present in keystore sm-service.p12. The aliases sm_service_cmk_alias and sm_service_keypair_alias defined in .env must match entries present in sm-service.p12.

IMPORTANT

If you replace the keystore, ensure the aliases are preserved or update configuration files accordingly.

Sensitive: Treat sm-service.p12 and sm-service-keystore.pass as sensitive secrets.
Do not distribute broadly. Only the SM service and administrators performing maintenance should have access.

IMPORTANT

Back SM files up securely (vault/offline secure storage). Backups are strongly recommended before any upgrade, rotation, or replacement. If sm-service.p12 is lost, all encrypted data will be unrecoverable.

Step 1: Regenerate SM Keystore Aliases and Update Config

For Proof of Concepts, you may use the installer-generated alias values. For production, you must regenerate these aliases so they are unique to your environment and do not rely on defaults.

Recommendation: Regenerate these aliases even for POCs to align with production practices and avoid accidental reuse across environments.

Generate two random identifiers for new alias values (recommended 32 hex characters each):

# Generate New alias for the CMK (SecretKeyEntry)
openssl rand -hex 16
# Generate New alias for the key pair (PrivateKeyEntry)
openssl rand -hex 16

Update .multi_node_config.conf:

sm_service_cmk_alias='<new_hex_value_1>'
sm_service_keypair_alias='<new_hex_value_2>'

Update .env:

cd $INSTALLER_DIR
./generate_envs/generate_envs.sh -t multi-node

Step 2: Generate sm-service.p12 manually

Generate sm-service.p12 manually (same as installer behavior with new randomization for security purposes).

Create Keystore Password File

Create the keystore password file sm-service-keystore.pass:

openssl rand -hex 24 > sm-service-keystore.pass
chmod 0400 sm-service-keystore.pass
SM_PASS="$(cat sm-service-keystore.pass)"

Create the keystore and generate the AES-256 CMK entry

Create the SecretKeyEntry under the alias sm_service_cmk_alias:

$JAVA_PATH/bin/keytool -genseckey \
  -alias "<sm_service_cmk_alias>" \
  -keyalg AES \
  -keysize 256 \
  -keystore sm-service.p12 \
  -storetype PKCS12 \
  -storepass "$SM_PASS" \
  -keypass "$SM_PASS"

Generate the EC P-384 key pair entry

Convert the OpenSSL-style DN (e.g., /C=US/ST=Ohio/O=Keyfactor/OU=Server) into keytool format, then append CN=sm-keystore:

KEYTOOL_DNAME="$(echo "<server_certificate_subject>" \
| sed 's|^/||; s|/|,|g'),CN=sm-keystore"
echo "Using DN: $KEYTOOL_DNAME"

Generate the key pair under the alias sm_service_keypair_alias:

# EC example
$JAVA_PATH/bin/keytool -genkeypair \
  -alias "<sm_service_keypair_alias>" \
  -keyalg EC \
  -keysize 384 \
  -sigalg SHA384withECDSA \
  -keystore sm-service.p12 \
  -storetype PKCS12 \
  -storepass "$SM_PASS" \
  -keypass "$SM_PASS" \
  -dname "$KEYTOOL_DNAME" \
  -validity "<cert_expiry_days>"

# RSA example
$JAVA_PATH/bin/keytool -genkeypair \
  -alias "<sm_service_keypair_alias>" \
  -keyalg RSA \
  -keysize 3072 \
  -sigalg SHA512withRSA \
  -keystore sm-service.p12 \
  -storetype PKCS12 \
  -storepass "$SM_PASS" \
  -keypass "$SM_PASS" \
  -dname "$KEYTOOL_DNAME" \
  -validity "<cert_expiry_days>"

Note: RSA is also supported.

Set file permissions

chmod 0400 sm-service.p12 sm-service-keystore.pass

Install BYOC Secrets Manager Files

For production deployments, replace the Secrets Management Keystore with your new one.

Place Keystore Material into Prepared Certificate Directory

Place the BYOC Secrets Manager Keystore material into the Secrets Manager Keystore location at <installer_dir>/certificates/<analytics_internal_domain>/.

AgileSec required filenames:

sm-service.p12 – SM keystore (PKCS#12)
sm-service-keystore.pass – Keystore password

Deploy to Backend Nodes

Deploy keystore files to <installer_dir>/certificates/<analytics_internal_domain>/ on all backend nodes.

The keystore is only used by sm-service, which is located on backend nodes.

Secrets Manager Keystore Verification

Inspect keystore entries

$JAVA_PATH/bin/keytool -list -v -storetype PKCS12 \
  -keystore sm-service.p12 \
  -storepass "$(cat sm-service-keystore.pass)"

You should see:

Entry type: SecretKeyEntry with alias matching sm_service_cmk_alias
Entry type: PrivateKeyEntry with alias matching sm_service_keypair_alias

Quick alias check (optional)

$JAVA_PATH/bin/keytool -list -v -storetype PKCS12 \
  -keystore sm-service.p12 \
  -storepass "$(cat sm-service-keystore.pass)" | \
  grep -E "Alias name:"