Skip to content

ADR: Do not require nonce management for encrypted credentials#

Status#

Implemented

Context#

Nonce-based encryption APIs require callers to generate, store, and later provide the correct nonce for decryption. While this is standard cryptography practice, it creates a sharp edge for a “secure by default” module designed to be used by site builders and developers who may not have cryptography expertise.

The module’s use case is encrypting credentials at rest, not implementing an interactive protocol. There is no need to identify a sender, no need to preserve a sender identity for verification, and no requirement for a caller-controlled nonce lifecycle across multiple systems.

Given the constraints, the design sought to avoid introducing a nonce into the stored format and into the Key provider’s configuration.

Decision#

Do not expose nonce generation, storage, or handling in the module’s API or storage format.

Instead, use libsodium sealed boxes, which allow the module to encrypt values for the recipient using only a public key while avoiding application-level nonce management.

Alternatives#

  • Secret box (crypto_secretbox_easy) with explicit nonce storage:
  • Store a random nonce alongside the ciphertext and ensure it is never reused for the same key.
  • Public-key box (crypto_box_easy) with explicit nonce storage:
  • Store a random nonce alongside ciphertext and manage keypair + nonce rules correctly.

Consequences#

Benefits#

  • Simplifies the storage format for encrypted credentials (no nonce field to manage, store, or migrate).
  • Reduces the likelihood of implementation mistakes such as nonce reuse, nonce loss, or incorrect concatenation/serialization of nonce + ciphertext.
  • Keeps the module aligned with the “encrypt anywhere with public key, decrypt only where private key exists” workflow.

Drawbacks#

  • The ciphertext format is tied to sealed box semantics, so switching to a nonce-based scheme later would require a migration strategy (likely a new provider/plugin ID and re-encryption).
  • Some cryptographic flexibility is traded for simplicity and safety of adoption.

Notes#

The decision does not claim that nonces are “unnecessary” in cryptography. The decision is that nonce management should not be part of this module’s public API because sealed boxes meet the module’s requirements while reducing operational and implementation complexity.

Authors#

  • Dezső Biczó (@mxr576)

Date#

2025-12-10