Cipher algorithm settings

Ory Identities (Kratos) encrypts OIDC provider tokens with a cipher. Configuring it takes two settings:

• secrets.cipher is required. It holds one or more 32-character secrets. Kratos refuses to start without it. See secrets key rotation.
• ciphers.algorithm selects the algorithm. It defaults to [xchacha20-poly1305, noop]: new values are encrypted with XChaCha20 Poly1305, and values that Kratos wrote in plaintext before a cipher was configured stay readable until they are written again. If you set it to an algorithm Kratos doesn't know, it fails closed: any operation that needs to encrypt or decrypt returns an error rather than storing sensitive values without encryption.

XChaCha20 Poly1305

Apply the following configuration to use XChaCha20 Poly1305:

secrets:
  cipher:
    - 32-CHARACTER-LONG-STRING-SECRET
ciphers:
  algorithm: xchacha20-poly1305

AES

Apply the following configuration to use AES:

secrets:
  cipher:
    - 32-CHARACTER-LONG-STRING-SECRET
ciphers:
  algorithm: aes

Noop

Noop doesn't use an algorithm: it encodes values without encryption, so they are stored in plaintext. It provides no confidentiality or integrity and is not recommended. Select it explicitly to opt out of encryption:

secrets:
  cipher:
    - 32-CHARACTER-LONG-STRING-SECRET
ciphers:
  algorithm: noop

Changing the algorithm

ciphers.algorithm also accepts an ordered list. The first algorithm encrypts new values; the rest only decrypt older ones, and each value is re-encrypted with the first algorithm the next time it is written. This works like secrets key rotation, but for the algorithm itself, so you can change algorithms without re-encrypting existing data and without downtime.

This example moves from xchacha20-poly1305 to aes:

secrets:
  cipher:
    - 32-CHARACTER-LONG-STRING-SECRET
ciphers:
  algorithm:
    - aes
    - xchacha20-poly1305

Drop the trailing entry once every value has been written again. Until then, keep it: an instance that no longer knows the old algorithm can't read values still encrypted with it, and that also applies when you roll back to an earlier Kratos version.

noop can only be the last entry in the list, because it decodes any value and would shadow the algorithms after it.