Metadata Key
This page configures how metadata encryption keys are managed and distributed in your organisation. For an overview of what metadata encryption is and how it works, see Encrypted Metadata.
Key Management
Passbolt encrypts metadata using OpenPGP keys. There are two options:
Personal key: The user's own OpenPGP private key encrypts metadata. Only that user can decrypt it. The server cannot access this metadata.
Shared metadata key: One OpenPGP key pair exists for the organisation. Its private key is encrypted separately for each user using their public key. All users who have been given a copy can decrypt metadata encrypted with this key.
Why both exist:
Shared resources require a shared key. When multiple users access a resource, they need to decrypt the same metadata. Each user decrypts their copy of the shared private key, then uses it to decrypt the resource metadata.
Personal resources can use either. You can allow personal (non-shared) resources to use the user's own key for maximum privacy, or enforce the shared key for all resources so administrators can audit metadata.
This page configures:
- Which key is used for personal resources
- How the shared key is distributed to users
Configuration Options
Metadata Key Policy
Choose one of the following modes:
Allow the use of personal keys (recommended)
Personal (non-shared) resources metadata are encrypted with the user's OpenPGP key. Shared content uses the shared key.
Use these settings if you want to:
- Allow users to encrypt personal resources with their own keys
- Prevent administrators from accessing personal resource metadata
Note that with these settings, the personal resources of the users won't be auditable.
Enforce the use of shared metadata keys
All metadata is encrypted using the shared metadata key. Personal keys are not used for metadata encryption under this policy.
Use these settings if you need administrators to be able to decrypt and audit all resource metadata.
If you try to save the page with "Enforce use of shared metadata keys" set but haven't generated a metadata key yet, you'll receive an error message.
Zero-Knowledge Key Distribution
Controls how the shared metadata key is distributed to users.
Navigate to Organisation settings > Content types > Metadata key to configure.
User-Friendly Mode (Default)
The API has access to the shared metadata key and distributes it automatically when users complete setup.
Security:
- Protects metadata if the database is compromised
- An attacker with full API access can access the shared metadata key
- Passwords remain encrypted with user personal keys
Zero-Knowledge Mode
The API does not have access to the shared metadata key. Administrators must share it manually with each user after setup.
Security:
- Protects metadata if the database or API is compromised
- Passwords remain encrypted with user personal keys
Operational requirements:
- Administrators must share the key with each new user
- Users cannot create or share resources until they receive the key
- Key rotation recommended when switching to this mode
New users will not receive the shared metadata key until an administrator shares it. See Sharing Missing Metadata Keys below.
Sharing Missing Metadata Keys
To share the metadata key with users:
- Navigate to the Users workspace
- Locate users with missing metadata keys (indicated by a warning or badge)
- Click "Share metadata keys" in the action bar
- Enter your passphrase
Users without the shared metadata key cannot create resources in shared folders or share existing resources.
Rotating the Shared Metadata Key
To rotate the shared metadata key:
- Navigate to Organisation settings > Content types > Metadata key
- In the "Shared metadata keys" section, click "Rotate key"
- Review the rotation details in the modal
- Click "Rotate key" to confirm, or "Cancel" to abort
- Click "Save" to apply the changes
Key rotation will generate a new shared metadata key. All existing encrypted metadata will need to be re-encrypted with the new key. This process may take time depending on the amount of data.
Key Information
The shared metadata key is generated automatically on installation. User-friendly mode is enabled by default.
Key details:
| Property | Example |
|---|---|
| Fingerprint | DC6A 4B28 58CF 2C58 6859 C505 7DEB 3F99 EE06 979B |
| Algorithm | eddsa ed25519 |
| Key length | 256 |
| Created | 30 days ago |
Related Documentation
- Encrypted Metadata - Configure encryption settings
- Allow Content Types - Enable content types
- Migrate Metadata - Migrate existing resources