How data is encrypted
Encryption relies on the key pair of an identity: the public key locks, the private key unlocks. When your application encrypts something, your key is the key pair of the identity the client acts as — the user's identity in your application, or one of their groups. The SDK receives these keys at sign-in. On top of them, Secrecy encrypts data in two layers.
Two layers: a data key, locked with your key
- The data is encrypted with its own key. Each piece of data — a file, a version of a file, the name of a node — gets a fresh, random data key. The SDK encrypts the content with it, on the device.
- The data key is locked with your public key. The data key itself is then encrypted so that only your private key can open it.
The servers store the encrypted data and the locked data key side by side. Holding both is not enough: without your private key, the data key stays locked, and without the data key, the data stays unreadable.
To read the data back, the SDK does the same in reverse: it unlocks the data key with your private key, then decrypts the content with the data key.
Why two layers
The split between the data and its key is what makes the rest of Secrecy work.
- Sharing does not re-encrypt the data. To give someone access, the SDK locks the same data key again, this time with the recipient's public key — a user's or a group's. A large file is never re-encrypted or re-uploaded to be shared; only its small key is. See sharing models.
- Each piece of data stands on its own. Because every file, version and name has its own key, giving access to one of them reveals nothing about the others.
- The key can travel without the user. A data key can also be locked with a password instead of a public key. That is how a link opens for someone who has no Secrecy account.
Files, names and mails
The same model applies across the SDK, with small variations:
- Files are encrypted as a stream, in chunks, so large files can be uploaded and downloaded with progress reporting. On download, each part is checked against a checksum before being decrypted.
- Names of files and folders are encrypted too: the servers see an encrypted label, not
patient-record.pdf. - Mail subjects and bodies are encrypted separately for each recipient, with the public key of that recipient in your application. Attachments follow the file model: their data key is locked again for each recipient.
What you do in code
Nothing specific. The client does all of the above around each call, and never exposes the keys: your application only sees plain data going in and plain data coming out. The only encryption you ever call directly is the anonymous encryption function, because its sender has no client.