Skip to content

Secure Key Injection and Management

[!NOTE] For the latest implementation status, please refer to Functional Implementation Status (Remaining Functionality).

Creation date: 2026-03-04

Purpose: Provides recommended steps for safely injecting EVOSPIKENET_DATA_ENCRYPTION_KEY (used for DB/File-at-rest data encryption) into a production environment.

Assumption: The application references the EVOSPIKENET_DATA_ENCRYPTION_KEY environment variable to read the key (32 bytes or more) for AES-256-GCM.

Recommended options:

1) HashiCorp Vault (recommended) - Store the key in the Vault and the application retrieves the secret from the Vault API on startup. - Benefits: dynamic rotation, access control, audit logging. - Simple steps: - Write secrets to Vault:

vault kv put secret/evospikenet data_key=0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef
  • Retrieved from Vault when app starts (e.g. startup script):
export EVOSPIKENET_DATA_ENCRYPTION_KEY=$(vault kv get -field=data_key secret/evospikenet)
uvicorn evospikenet.api:app --port 8000
  • In Kubernetes, use vault-agent or vault-k8s to inject into Pods.

2) AWS Secrets Manager / KMS - Advantages: Managed, KMS-based key management and high availability. - Steps: - Create secrets in Secrets Manager. - Grant SecretsManager:GetSecretValue permission to EC2/ECS/EKS instance profile and IAM role. - Get it using the aws CLI or SDK at startup and set it as an environment variable.

export EVOSPIKENET_DATA_ENCRYPTION_KEY=$(aws secretsmanager get-secret-value --secret-id evospikenet/data_key --query SecretString --output text)

3) GCP Secret Manager - In a GKE environment, use Workload Identity to inject secrets into Pods.

4) Kubernetes Secrets / External Secrets - Kubernetes Secret can be used as a short-term measure. - For long-term operation, it is recommended to link external-secrets or secrets-store-csi-driver with Vault/KMS.

Operational notes: - Use a key of at least 32 bytes (256 bits). - Environment variables remain in process memory in clear text, so if possible, consider a strategy to keep them within the process for a minimal amount of time and then zero them out of memory. - Prepare regular rotations and rotation plans (impact studies, re-encryption, rollout order). - Document operational procedures and avoid embedding secret references directly in CI/CD.

Verification procedure (simple):

  1. Create a local vault and register the key.
  2. Inject EVOSPIKENET_DATA_ENCRYPTION_KEY in the script and start the app.
  3. Save the artifact and check that the data column on the DB is encrypted (binary length has increased, etc.).
  4. Confirm that it can be decrypted using evospikenet.db.load_artifact_data.

If necessary, include this documentation in the appropriate location in docs/ and add a Vault example with a concrete Terraform / Kubernetes manifest.