Property Encryption

[MaxAake]

Property Encryption allows Neo4j properties to be encrypted and decrypted on the driver side.

Property values are encrypted and encoded into bytes. The resulting bytes contain the encrypted value together with the
metadata required to decrypt it. The application is responsible for storing these bytes in a representation supported by
Neo4j property types. To decrypt a value, the application retrieves the stored bytes and provides them to the driver.

The feature is designed to be easy to use, with an opinionated approach to encryption and decryption. All official Neo4j
drivers are expected to support the feature, enabling interoperability between drivers when they are configured to use
compatible encryption settings.

Important

Preview Feature

The preview feature is a new feature that is a candidate for a future GA status.
It enables users to try the feature out and maintainers to refine and update it.
The preview features are not considered to be experimental, temporary or unstable.
However, they may change more rapidly, without following the usual deprecation cycle.
Most preview features are expected to be granted the GA status unless some unexpected conditions arise.

Note

This feature is available from version 6.3.0 onwards.

Note

At present, all encryption and decryption is manual. As an official Neo4j Driver feature, Property Encryption enables:

• Cross-driver and cross-version interoperability: Consistent encryption and decryption of Neo4j Property values across drivers and supported driver versions, including consistent Additional Authenticated Data (AAD) handling. This enables a Neo4j Property encrypted by a driver in one language to be successfully decrypted by a driver in another language.
• Standardized cryptography: The cryptographic algorithms and parameters, including key sizes, initialization vector (IV) sizes, and authentication tag sizes, are defined by the feature and selected with FIPS requirements in mind. Users can optionally configure the driver to use a validated cryptographic provider that satisfies their operational requirements.
• Composable key management: The envelope encryption design separates property encryption from key protection and allows different key encapsulation mechanisms to be integrated through a well-defined API.
• Standardized encrypted-value representation: The driver defines how encrypted property values and the metadata required for their decryption are encoded, providing a common representation that can be stored using Neo4j-supported property types.
• Server version agnostic: Encryption and decryption are performed on the driver side, with encrypted values represented as bytes that can be stored as Neo4j Properties. This allows the feature to be used with any Neo4j server version supported by the driver, without requiring server upgrade.

While Property Encryption API includes a more detailed overview, the following two examples demonstrate the basic usage of the API.

Encryption example:

const encryptedValue = await driver.encryption.encrypt({
  value: "Secret String", // Any value which can be stored as a property in a Neo4j database can be encrypted by the driver
  keyOptions: {alias: "key1"}, // the driver can handle multiple Data Encryption Keys
  encryptionProfile: "profile1", // The driver can have multiple encryption configurations, each one defined by an encryption profile.
  aad: 123 // Encryption is done with AES-GCM-256, which supports Additional Authenticated Data. 
}) //Produces an Int8Array, which the driver will send as a byteArray

Decryption example:

const decryptedValue = await driver.encryption.decrypt({
  ciphertext: result.records[0].get("x"),
  aad: 123
})

Supported types

Property Encryption supports encrypting Neo4j Database Property types, namely:

• BOOLEAN
• DATE
• DURATION
• FLOAT
• INTEGER
• LIST
  • Homogeneous lists of property types can be stored as properties (except VECTOR and LIST types, which cannot be
    stored in lists), although lists in general cannot be stored as properties. Lists stored as properties cannot contain
    null values.
  • POINT values in a list must have the same dimensionality and SRID.
• LOCAL DATETIME
• LOCAL TIME
• POINT
• STRING
• VECTOR
• ZONED DATETIME
• ZONED TIME
• UUID
• BYTES
• NULL

Encryption profile

An encryption profile defines the settings and operating mode used by the driver when encrypting and decrypting values.

Each profile has a unique, user-defined name. The profile name is stored with encrypted values and allows drivers to
identify which profile must be used to decrypt a value.

Multiple profiles can be configured at the same time, providing each has a unique name.

Note

When driver interoperability is required, users are expected to configure each driver with compatible profiles.

EncryptionProfile is the base type for encryption profiles. At present, the driver provides one profile type:
EnvelopeEncryptionProfile. Additional profile types may be introduced in the future.

Profiles are configured at the driver level using a driver configuration option:

const driver: Driver = neo4j.driver("neo4j://address", neo4j.auth.basic("user", "password"), {
    encryptionProfiles: [new EnvelopeEncryptionProfile({
        name: "main", //name of the encryption profile, 
        encapsulationService: neo4j.localKeyEncapsulationService(masterkey), //the service responsible for generating, encapsulating and decapsulating Data Encryption Keys (DEKs). The driver provides an implementation that uses a local 256-bit masterkey
        keyRepository: new userImplementedKeyRepo() // The place to store encapsulated DEKs, must be implemented by the user, an example implementation is provided further down.
    })]
})

Key Encapsulation Service

Key Encapsulation Service is responsible for generating, encapsulating, and decapsulating data encryption keys. It
generates a new data encryption key together with its encapsulation, and can later decapsulate the encapsulation to
recover the data encryption key when it is needed for encryption or 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.

The service is represented by KeyEncapsulationService interface that has 2 primary methods:

`encapsulate` - supplies a new AES-256 key and its encapsulation
`decapsulate` - decapsulates an existing encapsulation to AES-256 key

/**
 * A service responsible for encapsulating and decapsulating keys.
 *
 * @see KeyEncapsulationOptions
 * @see KeyEncapsulationResult
 * @since 6.3.0
 * @experimental Part of the Client-Side Encrytion preview feature
 */
export interface KeyEncapsulationService {
  /**
   * Creates a new key, encapsulates it and returns the result.
   *
   * @param {KeyEncapsulationOptions} options the encapsulation options, depends on the implementation
   * @return {Promise<EncapsulationResult>} a promise that resolves to the encapsulation result
   */
  encapsulate: (options: KeyEncapsulationOptions) => Promise<EncapsulationResult>

  /**
   * Decapsulates encapsulated bytes.
   *
   * @param {Int8Array} encapsulation the encapsulated byte}
   * @param {KeyEncapsulationOptions} metadata the key metadata
   * @return {Promise<Uint8Array>} a promise that resolves to the decapsulated key
   */
  decapsulate: (encapsulation: Int8Array, metadata: KeyEncapsulationOptions) => Promise<Uint8Array>
}

Local

The local implementation uses a user-provided AES-256 key in the form of a 32-length Uint8Array as a master key for encapsulating and decapsulating data encryption keys.

The encapsulation uses AES-GCM ("AES/GCM/NoPadding") with the provided master key. The resulting encapsulation
contains a 256-bit AES data encryption key protected by the master key, together with a 96-bit (12-byte) initialization
vector (IV) and a 128-bit (16-byte) authentication tag.

Cloud KMS Providers

Implementations for Google, AWS, and Azure KMS providers will be made available in separate NPM packages following release of the driver implementation

Encapsulated Key Record Repository

An Encapsulated Key Record Repository is a user-provided repository for storing encapsulated data keys and their
associated metadata.

Each encapsulated key record has a globally unique and immutable identifier.

Important

The repository implementation is responsible for assigning globally unique and immutable key identifiers.
In addition, the repository is also responsible for enforcing alias uniqueness.

The repository is represented by EncapsulatedKeyRecordRepository interface that has 5 primary methods:

• create - creates a new key record
• findById - finds key by id
• findByAlias - finds key by alias
• setAliasById - sets key alias by id
• deleteById - deletes key by id

/**
 * A repository for {@link EncapsulatedKeyRecord} data.
 * An implementation of this must be provided to a {@link EncryptionProfile} so that the driver knows where to store and retreive encapsulated keys.
 *
 * @since 6.3.0
 * @experimental Part of the Client-Side Encrytion preview feature
 */
export interface EncapsulatedKeyRecordRepository {
  /**
   * Finds and returns an {@link EncapsulatedKeyRecord} by its id.
   *
   * @param {string} id the key id
   * @return {Promise<EncapsulatedKeyRecord>} a promise that resolves to the key or undefined if no key with the given id exists
   */
  findById: (id: string) => Promise<EncapsulatedKeyRecord>

  /**
   * Finds and returns an {@link EncapsulatedKeyRecord} by its alias.
   *
   * @param {string} alias the key alias
   * @return {Promise<EncapsulatedKeyRecord>} a promise that resolves to the key or undefined if no key with the given alias exists
   */
  findByAlias: (alias: string) => Promise<EncapsulatedKeyRecord>

  /**
   * Creates the encapsulation as a key and assigns it a globally unique id.
   *
   * The generated id MUST be globally unique and immutable. Implementations SHOULD use a mechanism designed to
   * generate globally unique identifiers, such as UUIDs.
   *
   * @param {string} alias the key alias
   * @param {Int8Array} encapsulation the key encapsulation
   * @param {Record<string, string>} metadata the key metadata
   * @return {Promise<EncapsulatedKeyRecord>} a promise that resolves to the created key
   */
  create: (alias: string, encapsulation: Int8Array, metadata: Record<string, string>) => Promise<EncapsulatedKeyRecord>

  /**
   * Sets the alias of an encapsulated key by id. 
   * The alias must not be used by another key and the implementation of this function should throw if it is.. 
   * To assign an alias currently used by another key, it must first be deleted from that key.
   * 
   * @param {string} id the key id
   * @param {string | undefined} alias the key alias, may be null or undefined to remove the alias
   * @return {Promise<void>} promise that resolves when the alias has been set
   */
  setAliasById: (id: string, alias: string | undefined) => Promise<void>

  /**
   * Deletes a key by id.
   *
   * @param {string} id the key id
   * @return {Promise<void>} promise that resolves when the key has been deleted
   */
  deleteById: (id: string) => Promise<void>
}

Property Encryption API

The Property Encryption API is exposed through the encryption property on the Driver
object. This makes the API easy to access, particularly in existing applications where the driver object is already
available.

const encryption: EncryptionService = driver.encryption

keyManager

The Envelope Profile requires data keys to exist before they can be used to encrypt or decrypt property values.

Creating a data key involves obtaining a new data encryption key and its encapsulation from the
Key Encapsulation Service and creating the corresponding record in the Encapsulated Key Record Repository.

Obtain key manager:

const keyManager: EncapsulatedKeyManager = encryption.keyManager("main") // gets the key manager for encryption profile "main".

Note

A data key can be referenced by its globally unique identifier or, if assigned, by an alias. Both are String values.

The key identifier is immutable and globally unique, assigned by the key repository. The alias is a mutable,
application-level reference that can be reassigned to a different key over time.

Aliases allow applications to refer to keys using stable application-level names without having to reference the key's
identifier.

The key manager provides operations to create, find, and delete keys. It also provides operations to set and delete key
aliases. When Caching is enabled, key management operations update the Key Cache and Key Alias Index as necessary.

Create a data key with an alias:

keyManager.create("key1")

Find key by alias:

keyManger.findByAlias("key1)

Set alias by id:

keyManager.findById("some-unique-uuid")

Delete alias by id:

keyManager.deleteAliasById("some-unique-uuid")

Delete key by id:

keyManager.deleteById("some-unique-uuid")

encrypt

Property values can be encrypted using the asynchronous encrypt function, which takes a parameter object.

Encrypt value:

const encryptedValue = await driver.encryption.encrypt({
  value: "Secret String", // Any value which can be stored as a property in a Neo4j database can be encrypted by the driver
  keyOptions: {alias: "key1"}, // the driver can handle multiple Data Encryption Keys
  encryptionProfile: "profile1", // The driver can have multiple encryption configurations, each one defined by an encryption profile.
  aad: "user1" // Encryption is done with AES-GCM-256, which supports Additional Authenticated Data. 
}) //Produces an Int8Array, which the driver will send as a byteArray

value should be the value to be encrypted.
keyOptions should be an object with a field alias or id, which is the key to be used when encrypting. It can alternatively be a string, which will be interpreted as the id of the key.
encryptionProfile should be a string, which is the name of the profile to be used. If the driver is configured with only one profile this field can be omitted, and the sole profile will be used. If there are multiple profiles, it must be provided.
aad should be an associated value to use for additional authentication, details are below.

The returned value will be an Int8Array, which will be stored as a byte blob in the server if sent as a query parameter.

Important

The encrypted value always references the encryption key identifier, which is expected to be immutable and globally
unique. This ensures that the identifier used by the encrypted value is stable, even when a key alias is used in the
encryption request.

Additional Authenticated Data (AAD) is optional, non-secret data that is authenticated together with the encrypted
value but is not itself encrypted. The same AAD must be provided during decryption. Otherwise, decryption fails.

Important

It is recommended to use AAD to bind an encrypted value to application-specific context where possible, such as a user
identifier. This ensures that the context is authenticated when the value is later decrypted.

AAD should not contain confidential information.

Only the following Neo4j property types are supported as AAD:

• DATE
• INTEGER
• LOCAL TIME
• POINT
• STRING - consider normalizing values using something like NFC before providing them to the driver when both
  encrypting and decrypting values
• ZONED TIME
• UUID
• BYTES

decrypt

The decrypting function decrypt functions similarly to encrypt

Decrypt value:

const decryptedValue = await driver.encryption.decrypt({
  ciphertext: record.get("accountBalance"),
  usePersistedAad: false, // can be omitted rather than set false, included for illustration purposes
  aad: "user1"
})

ciphertext should be a Int8Array produced by a driver's encryption function.
usePersistedAad is optional, and should be a boolean if set, if set to true the decryption will use the stored AAD value, effectively skipping the extra validation that AAD provides.
aad is optional, and should be the AAD value used in encryption if set.

If AAD was set in encryption, then either usePersistedAad must be true or aad must be set, else decryption will fail. Both should not be set at once.

Important

It is recommended to provide AAD externally when possible, especially when the encrypted value was bound to
application-specific context during encryption. The externally provided AAD must match the AAD used during encryption.

Caching

The Envelope Profile supports 2 related caches:

• Key Cache
• Key Alias Index

Note

Each profile instance maintains its own dedicated caches.

Key Cache

The driver caches decapsulated data encryption keys by default to avoid repeatedly resolving and decapsulating the same
key.

Depending on the Envelope Profile and Encapsulated Key Record Repository implementations, resolving a
key may require network exchanges. Caching can therefore reduce the number of repeated key resolution operations.

The key cache is keyed by the key's globally unique identifier and has a configurable maximum size and time-to-live
(TTL). The default size is 100 and TTL is 15 minutes.

The key cache can be configured when creating an Envelope Profile:

Configure Key Cache:

                new EnvelopeEncryptionProfile({
                    name: "main",
                    encapsulationService: encapsService,
                    keyRepository: new KeyRepo(),
                    keyCacheTTL: 10 * 60 * 1000 // TTL in ms, defaults to 15 minutes
                    keyCacheMaxSize: 10 // max size of cache, defaults to 100, disables caching if set to 0
                })

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

The key cache can also be disabled by setting it's max size to 0

Key Alias Index

Aliases are resolved through a key alias index that maps aliases to key identifiers. The alias index does not contain
key material.

The alias index has its own configurable maximum size and TTL. The default size is 100 and TTL is 15 seconds.

Note

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.

The alias index can be configured when creating an Envelope Profile:

Customize Key Alias Index:

                new EnvelopeEncryptionProfile({
                    name: "main",
                    encapsulationService: encapsService,
                    keyRepository: new KeyRepo(),
                    keyAliasIndexTTL: 10 * 1000 // TTL in ms, defaults to 15 seconds
                    keyAliasIndexMaxSize: 10 // max size of index, defaults to 100, disables caching if set to 0
                })

Like the key cache, the alias index is bounded and uses a least-recently-used (LRU) eviction policy when its configured
maximum size is reached. Entries that have exceeded their configured TTL are treated as cache misses and are not used.

The key alias index is disabled when the key cache is disabled. It can also be disabled independently by setting index max size to 0:

FIPS compliant cryptography provider in Node

Encryption is performed using the WebCrypto API, when using node this API is called through the Node crypto implementation.

If you wish to ensure that the cryptographic provider used by the driver is FIPS compliant, you will need to ensure your JS runtime is correctly configured to use these providers. For node, this means following the [Node Crypto Fips Mode Guide)[https://nodejs.org/api/crypto.html#fips-mode].