API Reference¶

Core API¶

Stable v4 package facade.

Phase 3 establishes declarations and value models only. Operational cryptography is intentionally unavailable.

exception cryptography_suite.AuthenticationError(code: ErrorCode = ErrorCode.AUTHENTICATION_FAILED, *, retryable: bool = False, details: Mapping[str, str | int | bool | None] | None = None)¶

Bases: CryptographySuiteError

Protected data authentication failure.

exception cryptography_suite.ContextMismatchError(code: ErrorCode = ErrorCode.CONTEXT_MISMATCH, *, retryable: bool = False, details: Mapping[str, str | int | bool | None] | None = None)¶

Bases: CryptographySuiteError

Caller context did not match without identifying the mismatched value.

exception cryptography_suite.CryptographySuiteError(code: ErrorCode = ErrorCode.INTERNAL_ERROR, *, retryable: bool = False, details: Mapping[str, str | int | bool | None] | None = None)¶

Bases: Exception

Base class for stable errors with immutable, redacted fields.

property code: ErrorCode¶

property details: Mapping[str, str | int | bool | None]¶

property retryable: bool¶

class cryptography_suite.EncryptionContext(values: Mapping[str, str | bytes] | None = None, *, purpose: str | None = None, tenant_id: str | None = None)¶

Bases: Mapping[str, str | bytes]

A bounded, immutable context mapping.

Phase 3 bounds retained input storage only. This is not a canonical encoded size guarantee and performs no commitment, hashing, or encoding.

property purpose: str | None¶

property tenant_id: str | None¶

class cryptography_suite.Envelope(data: bytes)¶

Bases: object

An immutable byte container that makes no authentication claim.

data: bytes¶

exception cryptography_suite.EnvelopeError(code: ErrorCode = ErrorCode.FORMAT_INVALID, *, retryable: bool = False, details: Mapping[str, str | int | bool | None] | None = None)¶

Bases: CryptographySuiteError

Envelope structure, format, or resource-limit failure.

class cryptography_suite.EnvelopeMetadata(format_name: str, profile: str, major_version: int, minor_version: int, algorithm_suite: str, recipients: tuple[KeyRef, ...], plaintext_size: int | None, ciphertext_size: int, chunk_count: int, context_commitment_id: str | None, created_at: datetime | None, critical_features: tuple[str, ...], policy_id: str, authentication_status: AuthenticationStatus = AuthenticationStatus.NOT_VERIFIED)¶

Bases: object

A redacted structural view; authentication is explicit.

algorithm_suite: str¶

authentication_status: AuthenticationStatus = 'not_verified'¶

chunk_count: int¶

ciphertext_size: int¶

context_commitment_id: str | None¶

created_at: datetime | None¶

critical_features: tuple[str, ...]¶

format_name: str¶

major_version: int¶

minor_version: int¶

plaintext_size: int | None¶

policy_id: str¶

profile: str¶

recipients: tuple[KeyRef, ...]¶

class cryptography_suite.ErrorCode(value)¶

Bases: str, Enum

Stable machine-readable v4 error codes.

Unknown serialized codes remain representable so operational readers can preserve a code introduced by a newer compatible producer.

AUTHENTICATION_FAILED = 'AUTHENTICATION_FAILED'¶

CANCELLED = 'CANCELLED'¶

CAPABILITY_UNSUPPORTED = 'CAPABILITY_UNSUPPORTED'¶

CONTEXT_MISMATCH = 'CONTEXT_MISMATCH'¶

CRITICAL_FIELD_UNSUPPORTED = 'CRITICAL_FIELD_UNSUPPORTED'¶

FORMAT_INVALID = 'FORMAT_INVALID'¶

FORMAT_UNSUPPORTED = 'FORMAT_UNSUPPORTED'¶

INTERNAL_ERROR = 'INTERNAL_ERROR'¶

IO_FAILED = 'IO_FAILED'¶

KEY_NOT_FOUND = 'KEY_NOT_FOUND'¶

KEY_STATE_DENIED = 'KEY_STATE_DENIED'¶

KEY_VERSION_STALE = 'KEY_VERSION_STALE'¶

LEGACY_DENIED = 'LEGACY_DENIED'¶

LIMIT_EXCEEDED = 'LIMIT_EXCEEDED'¶

MIGRATION_CONFLICT = 'MIGRATION_CONFLICT'¶

MIGRATION_INCOMPLETE = 'MIGRATION_INCOMPLETE'¶

MIGRATION_VERIFY_FAILED = 'MIGRATION_VERIFY_FAILED'¶

OUTPUT_EXISTS = 'OUTPUT_EXISTS'¶

POLICY_DENIED = 'POLICY_DENIED'¶

POLICY_INVALID = 'POLICY_INVALID'¶

PROVIDER_AUTH_FAILED = 'PROVIDER_AUTH_FAILED'¶

PROVIDER_RATE_LIMITED = 'PROVIDER_RATE_LIMITED'¶

PROVIDER_TIMEOUT = 'PROVIDER_TIMEOUT'¶

PROVIDER_UNAVAILABLE = 'PROVIDER_UNAVAILABLE'¶

TRAILING_DATA = 'TRAILING_DATA'¶

class cryptography_suite.KeyProvider(*args, **kwargs)¶

Bases: Protocol

describe_key(key: KeyRef, *, request: ProviderRequest) → KeyDescription¶

health_check(*, request: ProviderRequest) → ProviderHealth¶

property provider_id: str¶

unwrap_data_key(wrapped_key: WrappedKey, *, binding: bytes, request: ProviderRequest) → SecretBuffer¶

wrap_data_key(data_key: ReadOnlySecret, *, key: KeyRef, binding: bytes, request: ProviderRequest) → WrappedKey¶

class cryptography_suite.KeyRef(provider_id: 'str', key_id: 'str', version: 'str | None' = None)¶

Bases: object

key_id: str¶

provider_id: str¶

version: str | None = None¶

exception cryptography_suite.MigrationError(code: ErrorCode = ErrorCode.MIGRATION_INCOMPLETE, *, retryable: bool = False, details: Mapping[str, str | int | bool | None] | None = None)¶

Bases: CryptographySuiteError

Explicit migration transaction failure.

class cryptography_suite.Policy(policy_id: str, profile: str = 'custom')¶

Bases: object

An identified policy value without an evaluator.

The caller may carry an already assigned nonsecret policy identifier. Canonical policy serialization, identifier derivation, composition, and authorization are deferred.

classmethod development() → Policy¶

classmethod enterprise(*, approved_providers: Iterable[str]) → Policy¶

classmethod migration(*, deadline: datetime) → Policy¶

policy_id: str¶

profile: str = 'custom'¶

restrict(overlay: Policy) → Policy¶

exception cryptography_suite.PolicyError(code: ErrorCode = ErrorCode.POLICY_INVALID, *, retryable: bool = False, details: Mapping[str, str | int | bool | None] | None = None)¶

Bases: CryptographySuiteError

Policy validation or authorization failure.

class cryptography_suite.Protector(*, provider: KeyProvider, policy: Policy, primary_key: KeyRef, audit_sink: AuditSink | None = None)¶

Bases: object

The stable v4 orchestration object, intentionally non-operational.

inspect(envelope: Envelope | bytes) → EnvelopeMetadata¶

open(envelope: Envelope | bytes, *, context: EncryptionContext) → bytes¶

open_stream(source: BinaryIO, destination: TransactionalSink, *, context: EncryptionContext, cancel: Callable[[], bool] | None = None) → EnvelopeMetadata¶

rewrap(envelope: Envelope | bytes, *, destination_key: KeyRef) → Envelope¶

seal(plaintext: bytes, *, context: EncryptionContext) → Envelope¶

seal_stream(source: BinaryIO, destination: TransactionalSink, *, context: EncryptionContext, cancel: Callable[[], bool] | None = None) → EnvelopeMetadata¶

exception cryptography_suite.ProviderError(code: ErrorCode = ErrorCode.PROVIDER_UNAVAILABLE, *, retryable: bool = False, details: Mapping[str, str | int | bool | None] | None = None)¶

Bases: CryptographySuiteError

Normalized provider failure.

Experimental API¶

Legacy API¶

Explicit, non-operational legacy migration namespace.

class cryptography_suite.legacy.LegacyAdapter(*args, **kwargs)¶

Bases: Protocol

property format: LegacyFormat¶

class cryptography_suite.legacy.LegacyFormat(value)¶

Bases: str, Enum

CSF_V1 = 'csf-v1'¶

CSF_V2 = 'csf-v2'¶

LOCAL_KEYSTORE = 'local-keystore'¶

PEM_DER = 'pem-der'¶

PORTABLE_AES_V3 = 'password-aes-v3'¶

RAW_AES = 'raw-aes'¶

Selecting a backend¶

>>> from cryptography_suite.crypto_backends import use_backend
>>> with use_backend("pyca"):
...     pass
>>> with use_backend("sodium"):
...     pass
>>> with use_backend("rust"):
...     pass