Summary

Default a default convention for keyAltName for encrypted fields, so applications and frameworks can rely on a consistent reference to a field's Data Encryption Key (DEK) across languages without declaring a keyAltName on every field. When a field in the encryptedFieldsMap carries neither a keyId nor a keyAltName.

Slack discussion: thread

Motivation

Who is the affected end user?

Framework and application developers configuring CSFLE/QE. The goal is to avoid having to think about and write a keyAltName for every encrypted field. Driver or framework integration does not strictly require this default, but it is a developer experience improvement to have one less thing to configure, and a consistent default also helps when a field is shared across applications, for example a Laravel and a Node application accessing the same database.

Is this issue urgent?

No. The drivers maintainers said "yes for future consideration"; this may motivate larger changes to the CSFLE/QE setup.

Is this ticket only for tests?

No.

Open questions

• What convention is chosen? keyAltName is expected to be a unique identifier.
  • <collection>.<field> may risk collisions between apps that share a key vault between databases. But omitting the database keeps the name stable across database renames.
  • <database>.<collection>.<field> may risk collections between apps that share a key vault between MongoDB clusters (via keyVaultClient).
  • <user prefix>.<database>.<collection>.<field> may require an API option to supply a user-chosen prefix.

Considerations

• No immediate security concern: a predictable keyAltName is already possible if an application applies a naming convention.
• API complexity: a default adds behaviour to the spec. It can be applied in createEncryptedCollection when creating keys, but not in createDataKey, which has no knowledge of the target field.
• Opt-in needed: adding a default on key creation may need to be opt-in, so applications already using the convention do not break. For example addKeyAltName may fail on a duplicate when a unique index exists on keyAltNames.

Acceptance Criteria

• A keyAltName default convention is chosen
• A DEK can be created and used without requiring an app specify a keyId or a full keyAltName.
• Applying a default keyAltName does not break existing applications (make it opt-in).