Introduction

Passbolt, as the open-source credential manager designed for collaboration, has long been a trusted solution for securing and sharing sensitive information. The version 5 of Passbolt will introduce a significant architectural evolution: it will support storing encrypted metadata such as the names of resources, folders, and tags. This change will fundamentally redefine how information can be managed and shared within Passbolt.

This article explores the rationale and high level approach behind this shift toward encrypted metadata, and how these changes aim to strike a balance between conflicting needs: user privacy and administrative auditability. It also introduces the high level options that will be at the disposal of administrators to ensure a smooth transition, especially if you integrate Passbolt with other solutions and systems.

While this article focuses on the big picture, it will be followed by more practical articles to select which configuration would be best for you, how to plan and roll out your content and integration migrations if any.

On Balancing Auditability and Privacy

In Passbolt v4, all data is encrypted in transit and additionally the most sensitive of it is protected with a robust end-to-end encryption (E2EE). This encryption is done once per secret and per user, and is performed “client side”. In simple terms this means it is performed in the browser, the mobile app, the command line app, etc. without the knowledge of the server. 

So while secrets such as passwords, descriptions, and TOTPs are protected, certain sensitive metadata, like resource names and URIs, up to version 4 remain accessible on the server. While this may have been sufficient for many use cases it can create limitations for individuals seeking a stronger privacy model.

The need for user privacy and the need for administrative auditability are often at odds in design. Users expect their data to be protected from unauthorized access, even from administrators. However, administrators in enterprise environments require visibility into system activity for compliance, to perform access request management (when a user loses access to their keys for example), as well as integration and general troubleshooting.

In personal password managers, fully encrypting metadata is not only a logical but often an essential requirement, especially if the solution cannot be self-hosted like Passbolt. This design ensures that no one, not even the cloud service provider, can access information about the stored resources, meeting the privacy expectations of individual users. On a side note: in practice, the reality is that many personal password managers undermine the end-to-end encryption promise by serving the web application from the same service that hosts the data, or by using user selected password derived encryption keys, or break the privacy expectation by introducing in-product analytics.

The strict encryption of metadata that is expected in personal contexts, creates challenges in enterprise environments where operational transparency is key. 

For example, email aliases can enhance personal privacy by obscuring a user's identity, but in enterprise environments, they complicate security monitoring by making user identification more error-prone and less reliable. Similarly group names and user names are often stored in plaintext in LDAP or in other identity and access management systems. Moreover, URLs are often stored in plaintext in SIEM systems or filtering systems to facilitate network monitoring and threat analysis. CI/CD workflows rely on environment variables names or job identifiers that typically need to remain in plaintext to ensure smooth automation and debugging processes.

These examples highlight how operational transparency often requires accessible metadata, creating a tension with strict privacy-first models.

The Core Shift

Passbolt v5 aims to progressively address some of the issues triggered by this dual usage by introducing a flexible solution to support for encrypted metadata both in a personal and a shared context.

Which metadata will be encrypted?

The “raison d'être” of passbolt is secure collaboration for organizations. So all data that is needed by the server to orchestrate authentication and collaboration features in the backend side will remain unencrypted.

Information such as end-user names and email addresses, their permissions, the group names and memberships, or operational information such as whether a resource needs to be rotated (because for example someone who had access left the organization), the creation and modification dates, will remain in cleartext.

Other existing metadata such as names, URI as well as new data fields added to the default resource types (such as icons, multiple URIs, autofill hints, etc.) will be encrypted. We hope that this will create an incentive for everyone to switch to the new and more secure model.

Finally, of course, all existing secrets will remain encrypted. Moreover new secret types such as credit cards, passkeys, certificates, etc. also be encrypted by default.

How will metadata be encrypted?

Passbolt will support the encryption of metadata using two different type of keys:

1. Personal Keys: Metadata is encrypted with the user's personal OpenPGP key, ensuring complete privacy. Only the user can decrypt and access the data.
2. Shared Metadata Keys: Metadata is encrypted with a shared key managed by administrators, allowing authorized users to access the data. This approach balances privacy and administrative oversight.

Passbolt v5 leverages OpenPGP's hybrid encryption model, combining asymmetric and symmetric encryption. Metadata is symmetrically encrypted with a session key, which is then encrypted using either the user's public key (for personal metadata) or a shared metadata key (for shared metadata). The session key is rotated every time the metadata changes.

The shared metadata keys are centrally managed by administrators and can be rotated as needed to enhance security. Administrators can create, distribute, and revoke shared keys without disrupting user workflows.

Both methods enhance security, by providing encryption at rest, and another layer of encryption in transit. The model's flexibility allows organizations to choose a configuration that aligns with their specific threat models and regulations. For example, a financial institution may enforce full auditability by allowing only shared metadata keys, and IT professionals may emphasize security for personal accounts while retaining administrator auditability for shared accounts.

The final choice of encryption method is left to administrators and users, ensuring flexibility in meeting diverse security requirements. This will be defined though settings that can be controlled in the administration workspace (that administrators will be able to lock down via environment variables).

Cryptographic access versus logical access

In Passbolt v5, any metadata encrypted with a shared key can be decrypted by any user of an organization. However logical access protections remain in place to enforce permissions and limit who can view or modify specific resources based on their role.

Furthermore, shared key rotation is supported to enhance security. For example, when a collaborator leaves the organization, administrators can generate and distribute a new shared key, ensuring forward secrecy. This process prevents former users from accessing newly encrypted metadata, even if they previously had access to the shared key.

This combination of cryptographic flexibility and operational safeguards allows Passbolt to balance security with practical administrative needs. This compromise was made in order to keep the API backward compatible on important operations such as adding a user to a group or a share, while also allowing users to be promoted to administrators more easily. This will remain an area which we could further improve with passbolt version 6 for example.

Searchability and Performance

One challenge of encrypting metadata is the potential loss of searchability. In v5, searchability is maintained through client-side decryption. When a user logs in, their client decrypts metadata locally, enabling full-text search while preserving E2EE. This approach ensures that the server retains "zero-knowledge" of metadata content. It also clarifies what is a metadata and what is a secret, e.g. if it’s downloaded right after login and if it’s searchable it’s not a secret.

To mitigate performance impacts, metadata session keys are cached via an end-to-end encrypted registry encrypted with the end-user key that can be reused client-side. This optimization reduces the computational overhead of repeated session key decryption, and is particularly useful for large datasets.

How will the shared key be shared?

As we have seen the shared public/private key pairs will be used by users for shared resources to access resource metadata. These keys can only be shared with new users when they complete the setup, e.g. once they provide their public key.

To accomplish this we propose to build two share strategies with different security properties:

• “Server knowledge mode”: the shared metadata keys are available to the server and can be shared by the server when a user completes the setup. The application can in practice see the shared metadata. There is no “zero-knowledge”, but this is still a nice improvement, since in this case metadata is encrypted additionally at rest (in the database and backups) and in transit (on top of TLS).
• “Zero-knowledge mode”: the shared metadata keys are not available to the server and must be shared with users by the admins. Users are not allowed to create shared content unless they have access to a valid metadata key. This will be a feature that is supported in both modes, to allow administrators to recover from situations for example when sharing a metadata key with a user failed during setup.

Passbolt v5 will support moving from one mode to the other, as well as rotating the shared keys. This will allow for example organizations to use the “server knowledge mode” when initially onboarding users and then, later on, switch to a “zero-knowledge mode” and perform a key rotation.

What does it mean in terms of security?

In terms of security, as we have seen, Passbolt v5 introduces significant improvements in mitigating risks related to metadata exposure. By encrypting metadata, it safeguards against threats such as unencrypted backup access, SQL injection, and man-in-the-middle attacks (MiiM), ensuring that sensitive data remains protected even if the server is compromised. 

In "Zero-Knowledge Mode," or when metadata is encrypted using personal keys, both privacy and security is improved by rendering metadata inaccessible to the server, protecting against remote code injection and server-level access.

However, neither mode addresses risks like complete client-side control or public key injection attacks, emphasizing the importance of robust client-side security practices and trust in the public key infrastructure.

What is the timeline for this migration?

Content migration from Passbolt v4 to v5 is designed with maximum flexibility in mind. Administrators will have the option to enable encrypted metadata and perform partial or full content migration through the UI. Importantly, it will be possible for v4 and v5 content to coexist within the same system, ensuring that the adoption of the new encrypted metadata features can be tested and rolled out step by step without disrupting existing workflows or breaking integrations.

In practice the migration will proceed at a pace set by administrators, affording ample time for planning, as required to make such critical change happen correctly. Transitioning to the new security model also involves ensuring that integrations and clients are fully compatible with v5. To support this, Passbolt has made some v5 encrypted metadata features available for testing behind a feature flag in v4.10, with refinements expected in v4.11 and possible last corrections in v4.12.

The full v5 release, scheduled for Q1, will continue to support v4 operations for the duration of this transition period. By the end of Q2, new installations will default to encrypted metadata being enabled.

Decommissioning of the v4 backward compatibility mode will occur gradually, beginning at the end of 2025, by placing it behind a feature flag disabled by default. There will be an option to re-enable this v4 mode via a feature flag at least until the end of 2026. The final decommissioning date will be decided based on user and customer feedback, most likely concluding by late 2026, ensuring a smooth and well-supported transition for all users.

Moving forward

This article marks the beginning of a series designed to guide you through the transition to Passbolt v5 and help you make the most of its new features.

In the next article, we will focus on the various settings and modes available in v5, providing a clear roadmap for administrators to decide on their preferred configuration. Following that, we will dive into practical examples of how to use the new default content types using the API, showcasing its potential to streamline integrations and workflows.

As always, we welcome your input. Whether you have questions, suggestions, or concerns, we encourage you to share them on our community forum. For those seeking additional technical details, we encourage you to explore the specifications documents for a comprehensive breakdown of the changes.

Your feedback is crucial in ensuring these changes are not only effective but also meet the diverse needs of our community. Together, we can ensure this transition is effective, seamless, and aligned with the needs of everyone.