-
Notifications
You must be signed in to change notification settings - Fork 2
Architecture
don't invent your own crypto, rely on established frameworks maintained by experts
leverage the dedication of the open-source community to openpgp. leverage the versatility of openpgp, going beyond the browser and webcrypto, to support a wide variety of applications.
in addition to double encryption of sensitive communication with the server (TLS and additional server certificate) personal and sensitive data are additionally encrypted by specific keys, of which the server cannot access the secret component.
the implemented multi-layered key scheme ensures that only users with access to both
- an authorized user agent running on a device owned by the user
- and the secret passphrase
can successfully decrypt the sensitive key material required to access encrypted personal data.
in other words, as long as the threat model assumptions hold, only the owner of the encrypted personal data can decrypt and access that data. in particular, the administration server can not by any means decrypt the encrypted personal data, regardless of its implementation and of the software it runs, nor can any attacker gaining access to that server, as long as the threat model assumptions hold.
the user must never store nor share the master password (MP) with any other party, in any form whatsoever, and must securely preserve it offline at all times. the master password (MP) must remain the user's best kept secret.
a secret passphrase (SP) is securely hashed (PBKDF2) from the user's master password (MP). all private keys are systematically securely encrypted offline by authorized user agents with the same secret passphrase (SP) hashed from the master password (MP).
both the master password (MP) and the secret passphrase (SP) are never stored or shared online or offline, in any form whatsover.
access to sensitive key material is hence strictly limited to its unique owner, the only user who knows the master password (MP).
each authorized user agent (UA) owns a unique UA key pair (UAK).
- the public UA keys (PUAK) of authorized user agents are stored in a dedicated UA key document in the 'agent' database of its user.
- the private UA key (SUAK) of a UA key pair (UAK) is never shared online in any form whatsoever, and is securely stored in the owning UA's private keyring, encrypted with the secret passphrase.
UA key pairs are generated by their owning user agent when first registering.
UA key pairs can be renewed anytime by their owning user agent. the agent renewing a key pair must delete the existing UA key document from the 'agent' database and create a new UA key document in that database for the new key.
all personal data is systematically securely encrypted offline by authorized user agents with the private DB key (SDBK) of a shared DB key pair (DBKP).
- the public DB key (PDBK) is stored in the user's account document in the '_user' database.
- the private DB key (SDBK) is securely stored in the private keyring of each authorized user agent (UA), securely encrypted with the secret passphrase (SP). the private DB key (SDBK) is additionally encrypted offline with each public UA key (PUAK) of authorized user agents exclusively by a user agent with an encrypted copy of the private DB key (SDBK) in its keyring, and is stored thus twice encrypted in the user's account document in the '_user' database.
the shared DB key pair (DBK) is generated at account creation by the user agent from which the account is created.
the shared DB key pair (DBK) can be renewed at any time by any of the authorized user agents. the user agent renewing the shared DB key pair must re-encrypt all personal data accordingly. it must also update all 'agent' documents to share the new key with all other user agents. renewing the shared DB key pair is useful when unregistering a user agent, or on a regular basis (e.g. once a year) for additional security through perfect forward secrecy (PFS).
authorized agents are managed in the 'agent' database
in addition to its central role as encryption key for all personal data, the private DB key (SDBK) also plays a central role as signature key to authenticate documents in the '_user' and 'agent' databases. only user-agents with a copy of the private DB key (SDBK) can authenticate changes to the 'agent' database and their own user account document in the '_user' database. neither the administration server, regardless of its implementation and of the software it runs, nor an attacker gaining access to the server can modify entries in the 'agent' database or user account documents without invalidating these, as long as they do not have a copy of the private DB key (SDBK) and the secret passphrase (SP) required to decrypt that key, in other words, as long as the threat model assumptions hold.
thanks to the distributed nature of couchDB architectures and replication, replay attacks are detected and overwritten during replication by user agents.
the user agent registering a new account is the first to update and authenticate its user account document with the private DB key (SDBK). user agents subsequently registering for access to the account initially do not have access to the private DB key (SDBK). only after being authorized by a registered user agent do the newly registered user agents receive a copy of the the private DB key (SDBK), encrypted with their public UA key (PUAK).
the authorization process is hence exclusively controlled by authorized user-agents. the administration server merely acts as a facilitating communication channel for this process. furthermore, since the secret passphrase (SP) is required to decrypt the private DB key (SDBK), user-agents can only be authorized from user-agents in which the user has entered the main password (MP), providing an additional layer of security in the authorization process.
in particular, user-agents cannot be authorized by the server, nor by an attacker gaining access to that server, because as long as the threat model assumptions hold, neither the private DB key (SDBK) nor the secret passphrase (SP) are available to them.
the current specification supports a future extension for securely sharing personal data between users. revoking shared access is also supported.
the server api is a thin access control layer reduced to a minimal subset of the couchDB functionality requiring admin rights. the server's role is intentionally limited to minimal administration of a couchDB instance, providing a secure api for reliably setting up and deleting user accounts and databases, and for supporting the registration of new user-agents with an existing account.
interaction with administration endpoints from a user-agent is infrequent and does not justify setting up and managing sessions: each security-relevant request to an administration endpoint must be authenticated. this helps minimize the attack surface of administration endpoints. the server implementation should accordingly properly mitigate cross-site attacks. its minimal API facilitates implementation of such protection (CORS/XSS).
in essence, administration endpoints wrap accesses to the '_user' and 'agent' databases, and indexed documents in these database:
| endpoint | database or document |
|---|---|
| /api/cryptobox/:version | '_user' database |
| /api/cryptobox/:version/:uuid | user document in the '_user' database indexed by uuid |
| /api/cryptobox/:version/:uuid/agent | 'agent' database of the uuid user |
| /api/cryptobox/:version/:uuid/agent/:fingerprint | document with '_id' = :fingerprint in the 'agent' database of the uuid user |
exposed access to the '_user' and 'agent' databases and its documents through the api is limited to the bare minimum required for registering new user agents and creating new databases and is securely controlled by the server.
zero-knowledge api: the server only ever manages encrypted personal data that it cannot decrypt.
- the encryption key scheme described in this document imposes the zero-knowledge constraint.
- personal data, including encryption keys, is always encrypted by user agents before being transmitted over the api to the server
PouchDB, the javascript database that syncs.
CouchDB should be configured to hash passwords of user accounts with PBKDF2, 16 iterations. user database passwords should be secure random strings to keep the required PBKDF2 iteration count and hence the processing load on the server to a minimum.
| config parameter | value |
|---|---|
| httpd.require_valid_user | true |
| user_db_public | false |
| CORS.headers array | should contain “authorization” |
| TBD | TBD |
Copyright 2016 Stephane M. Catala
Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and Limitations under the License.