Testkit tests for property encryption

[RichardIrons-neo4j]

Property encryption

Feature flag: Feature.API_PROPERTY_ENCRYPTION.

There is a python script at tests/stub/property_encryption/generate_decrypt_interop_fixture.py, which will communicate with the backend to generate the a test case for the cross-driver decryption test. If the stub tests are passing then this script will work.

Protocol additions

Throughout this doc, bytes means a bare space-separated lower-case hex string on the wire (e.g. "0a 1b 2c"), the same convention CypherVector's data field uses — not a CypherBytes Cypher-value envelope. This applies to kek, iv, encapsulation, encryptedBytes, and encapsulatedBytes below, since none of them are themselves a Cypher property value. value and aad are the only fields that carry real property values, so they stay full <any Cypher value> envelopes.

NewDriver

NewDriver gains one optional field:

propertyEncryptionProfiles: [{ name: string, kek: bytes | null }]

Each entry configures one property-encryption profile on the driver. The profile is of the Envelope kind, backed by a backend-owned fixture KeyEncapsulationService/EncapsulatedKeyRepository pair; the backend plays the role of the user, who in a real application owns and supplies these objects directly. Profile names must be unique within a driver. If the field is omitted, no encryption profiles are configured.

kek, when given, constructs the profile's fixture key-encapsulation service with that exact key instead of a random one. This exists solely to support the deterministic and cross-driver decrypt tests; ordinary tests omit it.

EncryptToBytes

EncryptToBytes {
  driverId: string
  value: <any Cypher value>
  aad: <any Cypher value> | null
  profileName: string | null   # null => use the sole configured profile
  keyAlias: string | null      # exactly one of keyAlias/keyId must be set
  keyId: string | null
  iv: bytes | null             # null => random IV as normal
}
-> EncryptedValue { encryptedBytes: bytes }
-> Error

Encrypts value, binding aad when supplied. profileName may be omitted only when exactly one profile is configured; see the ambiguous-profile scenario below.

iv, when given, is the exact 12-byte IV the driver must use for this one encrypt call. The backend raises if the IV is not exactly 12 bytes or the operation doesn't consume it. With the data-encryption key pinned via ImportEncapsulatedKey and the IV pinned here, an encrypt is fully deterministic, so tests can assert byte-exact ciphertext instead of only round-tripping. Like kek, this exists solely for tests that ask for determinism; ordinary tests omit it. test_encrypts_to_known_bytes uses it to check the driver's encryption output byte-for-byte against the known-answer fixtures in deterministic_fixtures.py (initially generated with the .NET backend).

Decrypt

Decrypt {
  driverId: string
  value: bytes                 # as returned by EncryptToBytes
  aad: <any Cypher value> | null
  usePersistedAad: bool        # exactly one of aad/usePersistedAad must be set
}
-> DecryptedValue { decryptedValue: <any Cypher value> }
-> Error

The profile is resolved from the encrypted bytes: each encrypted value records which profile produced it, so the caller does not name one.

CreateEncapsulatedKey

CreateEncapsulatedKey {
  driverId: string
  alias: string
  profileName: string | null   # null => use the sole configured profile
}
-> EncapsulatedKey { id: string, alias: string, encapsulatedBytes: bytes, metadata: map<string,string> }
-> Error

Generates a fresh data-encryption key through the profile's KeyEncapsulationService and registers it in the profile's EncapsulatedKeyRepository under alias. A key must exist under a given alias before that alias can be used for encryption.

ImportEncapsulatedKey

ImportEncapsulatedKey {
  driverId: string
  alias: string
  encapsulation: bytes           # the wrapped-DEK bytes
  metadata: map<string,string>   # KES metadata for the encapsulation (e.g. the wrap IV)
  profileName: string
}
-> EncapsulatedKey { id: string, alias: string, encapsulatedBytes: bytes, metadata: map<string,string> }
-> Error

Seeds a profile's repository with a pre-made encapsulated key directly, skipping the key-generation step CreateEncapsulatedKey performs, since the caller already has an encapsulation from elsewhere (a fixture, or a prior CreateEncapsulatedKey response). This corresponds to what a real user would do to import a key obtained elsewhere: call their own repository's save method directly, without going through the driver's PropertyEncryption API at all. Unlike the other messages here, profileName is mandatory; there is no sole-profile default.

[MaxAake]

💬

[injectives]

I think we should add the keyId here as well as the identifier goes into the metadata of the Encrypted Structure and it must be predictable for stub tests asserting on expected encrypted bytes. The message handler should take all of this in import the key directly into its key repository.

[injectives]

encapsulatedBytes and metadata are not public API on DEK creation. I think it would be better if we did not require them here.

[injectives]

@RichardIrons-neo4j, I have been able to make it work with Java Driver, but only when I hardcode "0" key id on import. I think addressing the following will resolve this: https://github.com/neo4j-drivers/testkit/pull/727/changes#r3824978418