Keys & identities

In Secrecy, keys do not belong to users directly: they belong to identities. An identity is anything that holds a key pair and can be given access to data: a public key, that anyone can use to lock something for this identity, and a private key, the only way to unlock it. There are two kinds of identities, and one key above them all, the master key, that keeps their private keys safe.

Each layer locks the one below it: the master key locks the identity keys, and the identity keys lock the data keys that encrypt the data itself.

The master key

Every Secrecy account has one master key. It is derived from the user's password, on the Secrecy sign-in page, each time the user signs in. It is never stored and never sent anywhere: the servers only keep a random salt that goes into the derivation.

The master key has a single job: locking the private keys of the user's identities. It never encrypts data directly, and it never leaves the sign-in page: your application never sees it, even after sign-in.

Users can export their master key from their Secrecy account as a recovery phrase, to keep their keys reachable if they lose their password.

Your identity in an application

A user gets one identity per application, created the first time they sign in to it. It comes with its own key pair:

• the public key is what other users lock data for, when they share with this user in your application;
• the private key is stored by Secrecy locked with the master key. Only the sign-in page can unlock it, and it hands the unlocked key to your application at sign-in.

Because every application has its own identity, the same person has a different public key in each application. Data shared with them in one application does not open in another. This is why secrecyClient.publicKey and secrecyClient.app.userPublicKey always return the key of a user in the current application.

Group identities

A group is an identity of its own, with its own key pair, shared by its members. Groups belong to an application.

• Joining a group is receiving its key. When a member is added, the SDK locks the group's private key for that member's identity. At sign-in, the member unlocks it with their own private key, alongside their application identity. A group can itself be a member of another group.
• Leaving a group is losing that copy. Removing a member deletes their locked copy of the group key.
• Sharing with a group reaches every member. Data is locked once, for the group's public key, and every member can open it through the group key.
• Roles. A group has one owner, and its members are either admins or plain members.

By default, a client acts as the user's application identity. Setting secrecyClient.currentGroup makes it act as one of the user's groups instead: what it creates and shares from then on is encrypted with the group's keys.

What Secrecy stores

To make all of this work across devices, Secrecy stores, for each identity, its public key and its private key, locked. It also stores the salt of each master key. It never stores the master key, or any private key in a readable form, so what it holds is enough to route keys to the right devices, and never enough to open them. See zero-knowledge.