How ZITADEL Processes and Stores Secrets

In this chapter you can find information of how ZITADEL processes and stores secrets and credentials in a secure fashion.

<Callout> We use the terms secret and credentials interchangeable to keep this guide lean. </Callout>

Secrets Principles

ZITADEL uses the following principles when handling Secrets across their lifecycle:

• Automate rotation
• Limit lifetime
• Show only once
• Prefer public / private key concepts (FIDO2, U2F, JWT Profile, ...)
• Irreversible hash secrets / passwords
• Encrypt secrets storage
• When sent across unsecure channels (eMail, SMS, ...)
  • Forced changed through receiver
  • Verify that the secret can only be used once

Secrets Storage

By default ZITADEL stores secrets from its users, applications as well as its generated secrets like signing keys in the database. To protect the secrets against extraction from database as well as database dumps they are encrypted with AES256.

<Callout> The key used to encrypt and decrypt the secrets in the ZITADEL database is called `masterkey` and needs to be exactly 32 bytes long. The only secrets stored outside of the Secrets Storage are the masterkey, the TLS Keys, the initial Admin User (including the password) </Callout>

Secrets stored in the Secrets Storage

Public Keys

ZITADEL does handle many different public keys. These include:

• FIDO2
• U2F
• JWT Profile
• Signing Keys

<Callout> Due to the inherent nature of a public key being public we safeguard them against malicious key changes with our unique [eventstore concept](../eventstore/overview). </Callout>

Hashed Secrets

ZITADEL does handle many different passwords and secrets. These include:

• User Authentication
  • Password
• Client / Machine Authentication
  • Client Secrets

<Callout> ZITADEL hashes all Passwords and Client Secrets in an non reversible way to further reduce the risk of a Secrets Storage breach. </Callout>

Passwords and secrets are always hashed with a random salt and stored as an encoded string that contains the Algorithm, its Parameters, Salt and Hash. The storage encoding used by ZITADEL is Modular Crypt Format and a full reference can be found in our Passwap library.

The following hash algorithms are supported:

• argon2i / id¹
• bcrypt (Default)
• md5: implementation of md5Crypt with salt and password shuffling ²
• md5plain: md5 digest of a password without salt ²
• md5salted: md5 digest of a salted password ²
• phpass: md5 digest with PHPass algorithm (used in WordPress) ²
• drupal7: Custom hashing format used in Drupal 7 ²
• sha2: implementation of crypt(3) SHA-256 & SHA-512
• scrypt
• pbkdf2

<Callout> ZITADEL updates stored hashes when the configured algorithm or its parameters are updated, the first time verification succeeds. This allows to increase cost along with growing computing power. ZITADEL allows to import user passwords from systems that use any of the above hashing algorithms.

Note however that by default, only bcrypt is enabled. Further Verifiers must be enabled in the settings by the system administrator. </Callout>

Encrypted Secrets

Some secrets cannot be hashed because they need to be used in their raw form. These include:

• Federation
  • Client Secrets of Identity Providers (IdPs)
• Multi-factor Authentication
  • TOTP Seed Values
• Validation Secrets
  • Verifying contact information like eMail, Phonenumbers
  • Verifying proof of ownership over domain names (DNS)
  • Resting accounts of users (password, MFA reset, ...)
• Private Keys
  • Token Signing (JWT, ...)
  • Token Encryption (Opaque Bearer Tokens)
  • Useragent Cookies (Session Cookies) Encryption
  • CSRF Cookie Encryption
• Mail Provider
  • SMTP Passwords
• SMS Provider
  • Twilio API Keys

<Callout> By default ZITADEL uses `RSA256` for signing purposes and `AES256` for encryption </Callout>

Secrets stored outside the Secrets Storage

Masterkey

Since the Masterkey is used as means of protecting the Secrets Storage it cannot be stored in the storage. You find here the many ways how ZITADEL can consume the Masterkey.

TLS Material

ZITADEL does support end to end TLS as such it can consume TLS Key Material. Please check our TLS Modes documentation for more details.

Admin User

The initial Admin User of ZITADEL can be configured through ZITADELs config options.

<Callout> To prevent elevated breaches ZITADEL forces the Admin Users password to be changed during the first login. </Callout>

Footnotes

1. argon2 algorithms are currently disabled on ZITADEL Cloud due to its steep memory requirements. ↩

2. md5 and drupal7 are insecure and can only be used to import and verify users, not hash new passwords. ↩ ↩² ↩³ ↩⁴ ↩⁵