xtrace_sdk.x_vec.crypto.key_provider¶

Key provider abstractions for AES key management.

Defines a KeyProvider protocol and concrete implementations:

PassphraseKeyProvider: derives a 256-bit AES key from a passphrase using scrypt.
AWSKMSKeyProvider: envelope encryption via AWS KMS — the data encryption key (DEK) is generated or unwrapped by KMS and never persisted in plaintext.

Attributes¶

`_SCRYPT_N`
`_SCRYPT_R`
`_SCRYPT_P`
`_KEY_LEN`
`_DEFAULT_SALT`

Classes¶

`KeyProvider`	Protocol for objects that supply a 256-bit AES key and can wrap/unwrap it for storage.
`PassphraseKeyProvider`	Derives a 256-bit AES key from a passphrase using scrypt.
`AWSKMSKeyProvider`	Envelope encryption via AWS KMS.

Module Contents¶

xtrace_sdk.x_vec.crypto.key_provider._SCRYPT_N = 16384¶

xtrace_sdk.x_vec.crypto.key_provider._SCRYPT_R = 8¶

xtrace_sdk.x_vec.crypto.key_provider._SCRYPT_P = 1¶

xtrace_sdk.x_vec.crypto.key_provider._KEY_LEN = 32¶

xtrace_sdk.x_vec.crypto.key_provider._DEFAULT_SALT = b'xtrace-aes-gcm-v1'¶

class xtrace_sdk.x_vec.crypto.key_provider.KeyProvider¶

Bases: Protocol

Protocol for objects that supply a 256-bit AES key and can wrap/unwrap it for storage.

get_key()¶

Return the raw 256-bit AES key.

Return type:: bytes

wrap_key()¶

Return an opaque blob that can be stored alongside ciphertext to recover the key later.

Return type:: bytes

classmethod from_wrapped(wrapped, **kwargs)¶

Reconstruct a provider from a blob previously returned by wrap_key().

Parameters:

wrapped (bytes)
kwargs (Any)

Return type:

KeyProvider

provider_id()¶

Return a short identifier for the provider type (used in serialization).

Return type:: str

class xtrace_sdk.x_vec.crypto.key_provider.PassphraseKeyProvider(passphrase, salt=None)¶

Derives a 256-bit AES key from a passphrase using scrypt.

This is the default key provider and preserves backwards-compatible behavior. The passphrase is never stored — only the derived key is kept in memory.

Parameters:

passphrase (str)
salt (bytes | None)

_salt = b'xtrace-aes-gcm-v1'¶

_key¶

get_key()¶

Return type:: bytes

wrap_key()¶

Return type:: bytes

classmethod from_wrapped(wrapped, **kwargs)¶

Re-derive the key from the passphrase and stored salt.

Parameters:

wrapped (bytes) – The salt bytes returned by wrap_key().
passphrase – The original passphrase (passed via kwargs).
kwargs (Any)

Return type:

PassphraseKeyProvider

provider_id()¶

Return type:: str

class xtrace_sdk.x_vec.crypto.key_provider.AWSKMSKeyProvider(kms_client, key_id)¶

Envelope encryption via AWS KMS.

On creation, generates a random 256-bit DEK and wraps it with KMS. On load, unwraps a previously wrapped DEK using KMS.

Requires boto3 at runtime. The KMS key must grant the caller kms:Encrypt and kms:Decrypt permissions.

Parameters:

kms_client (object) – A boto3 KMS client (boto3.client("kms")).
key_id (str) – KMS key ID, ARN, or alias (e.g. "alias/xtrace").

_kms¶

_key_id¶

_key: bytes | None = None¶

_edek: bytes | None = None¶

classmethod create(kms_client, key_id)¶

Generate a fresh DEK via KMS GenerateDataKey.

Parameters:

kms_client (object) – A boto3 KMS client.
key_id (str) – KMS key ID, ARN, or alias.

Return type:

AWSKMSKeyProvider

classmethod from_wrapped(wrapped, **kwargs)¶

Unwrap a previously stored EDEK using KMS Decrypt.

Parameters:

wrapped (bytes) – The EDEK bytes returned by wrap_key().
kms_client – A boto3 KMS client (passed via kwargs).
key_id – KMS key ID, ARN, or alias (passed via kwargs).
kwargs (Any)

Return type:

AWSKMSKeyProvider

get_key()¶

Return type:: bytes

wrap_key()¶

Return type:: bytes

provider_id()¶

Return type:: str