Interface EnvelopePropertyEncryptionProfile

All Superinterfaces:
PropertyEncryptionProfile
All Known Implementing Classes:
InternalEnvelopePropertyEncryptionProfile
@Preview(name="Property Encryption") public sealed interface EnvelopePropertyEncryptionProfile extends PropertyEncryptionProfile permits InternalEnvelopePropertyEncryptionProfile
An encryption profile that enables Envelope Encryption for Neo4j Property Encryption.

Envelope encryption separates encryption of data from protection of the key used to encrypt that data. Property values are encrypted using a 256-bit data encryption key with AES-GCM ("AES/GCM/NoPadding" specifically). The key and its corresponding encapsulation are produced by a user-provided BaseKeyEncapsulationService implementation. Both synchronous and asynchronous implementations are supported.

Each encryption operation uses a 96-bit (12-byte) initialization vector (IV). AES-GCM uses a 128-bit (16-byte) authentication tag to provide integrity and authenticity of the encrypted data and any associated authenticated data (AAD).

AAD is optional and is supplied explicitly when encrypting a value. The AAD is stored with the encrypted value and is used during decryption unless AAD is explicitly supplied by the caller.

Both the Provider used for AES-GCM and the SecureRandom from which IVs are sourced are configurable. If neither is explicitly provided, the Java runtime determines and provides them according to its configuration.

The encapsulation and associated metadata are stored in a user-provided BaseEncapsulatedKeyRecordRepository. When a property is encrypted, the driver obtains the corresponding encapsulated key from the repository and uses the key encapsulation service to decapsulate the data key. The key is then used for AES-GCM encryption. When a property is decrypted, the driver similarly obtains the encapsulated key and uses the service to decapsulate the key required for decryption.

The key encapsulation mechanism is implementation-specific. It may use key wrapping, symmetric or asymmetric cryptography, a key management service (KMS), or a post-quantum key encapsulation mechanism such as ML-KEM. For example, the driver provides a local KeyEncapsulationServices.local(SecretKey) implementation that encapsulates and decapsulates data keys using the provided AES-256 master key. Additionally, three optional modules are available that provide implementations using Google Cloud KMS, AWS KMS and Azure Key Vault.

A key can be referenced by its globally unique identifier or, if assigned, by its alias. An alias is a mutable application-level reference and may be reassigned to a different key over time.

By default, the driver caches decapsulated data encryption keys to avoid repeated key resolution. Depending on the BaseKeyEncapsulationService and BaseEncapsulatedKeyRecordRepository implementations, resolving a key may also require network exchanges. The cache is keyed by the key's globally unique identifier and is subject to a configurable maximum size and time-to-live (TTL).

Aliases are resolved separately through a key alias index that maps aliases to key identifiers. The alias index does not contain key material and has its own configurable size and TTL. This allows alias mappings to expire independently of cached keys and limits the period for which a driver may use a stale alias after it has been reassigned, providing predictability during alias reassignment.

Both caches are bounded and use a least-recently-used (LRU) eviction policy when their configured maximum size is reached. Entries that have exceeded their configured TTL are treated as cache misses and are not used.

The key cache may be disabled. When the key cache is disabled, the key alias index is also disabled. The key alias index may also be disabled independently.

Since:
6.3.0