2. 🔑 Key Management

These settings control the key directory, and sealing options for the keys used for data encryption and security.

• auto_key_setup (bool, default: True) This parameter automates the key generation and registration workflow.

  • If True: The SDK handles everything automatically. It checks for keys at the specified path. If they don't exist, it generates a new key set and registers the public keys with the server. This is the recommended mode for most users.

  • If False: This is a manual mode for advanced use cases. The SDK requires a pre-existing key set at the specified path and will raise an error if one is not found. Key generation and registration must be performed separately by the user.

• key_path (str) The base directory where all encryption key sets are stored. Each key set will be in a subdirectory named after its key_id. This path should be considered fixed after the initial client setup.

• key_id (str) A unique identifier for a specific set of encryption keys. While the system is designed to eventually support multiple key IDs for different indexes, the current version only supports using a single key_id per client instance.

• metadata_encryption (bool, default: True) Determines whether to encrypt metadata before sending it to the server. When set to True, a MetadataKey.json is automatically generated and used for this purpose.

• seal_mode (str, default: 'none') Enables at-rest encryption for your most sensitive keys. When set to 'aes', the SecKey.json and MetadataKey.json (if it exists) are "sealed" (encrypted) using a Key Encryption Key (KEK) for secure storage.

  • 'aes': Activates AES256-GCM sealing.

  • 'none': Disables sealing.

• seal_kek_path (str) Required only when seal_mode is set to 'aes'. This parameter specifies the file path to the Key Encryption Key (KEK) that will be used to seal your keys.

• key_store (str, optional) Switch between filesystem-backed keys ("local", default) and AWS-backed storage ("aws"). When set to "aws", the SDK uploads/loads key material directly to/from AWS services instead of using key_path.

• region_name, bucket_name, secret_prefix (str, optional) Required when key_store="aws". Set the AWS region, the S3 bucket that stores encryption/eval keys, and the AWS Secrets Manager prefix for Sec/Metadata keys.

AWS-backed key storage

When the SDK runs with key_store="aws", key generation and retrieval use in-memory streams via KeyManager.generate_keys_stream() so that no files are written to disk. Public key blobs (encryption/eval keys) are uploaded to the configured S3 bucket, while SecKey/MetadataKey blobs are stored as Secrets Manager entries under secret_prefix.

Before calling ev.init() or ev.init_index_config() with AWS storage enabled:

1. Provision the S3 bucket and the Secrets Manager prefix (for example /envector/prod) in the target region.

2. Ensure the IAM role or credentials used by the SDK can perform read/write operations on both the bucket (Put/Get/DeleteObject) and the secrets (Create/Describe/Get/PutSecretValue).

3. Provide key_id, region_name, bucket_name, and secret_prefix. The SDK will auto-generate, upload, register, and load keys when auto_key_setup=True, or fetch the existing blobs if the key already lives in AWS.

This flow keeps secret material out of the local filesystem while maintaining the same ergonomics as the default key_path workflow.