Technology

Logical Architecture

A Peergos client connects only to a Peergos server (which may be in the same process, same machine, or a remote machine over https). The server acts as a proxy and doesn't store any data. All file system data is stored in the Inter-Planetary File System (IPFS), and the public keys, usernames and pending follow requests are stored on the corenode. All access to the corenode will be through Tor. The corenode stores the public key history for each username, any pending encrypted follow requests, and the root multihash for each public key.

Physical Architecture

IPFS forms a global, content addressed, peer-to-peer network. A Peergos server may serve a single user, or multiple users. If it serves multiple users it needs to use different Tor circuits for each user's queries on the corenode. Typically the Peergos server will have IPFS running locally on the same machine, an communicate over http. There is no sensitive information on the Peergos server apart from metadata.

Content and metadata encryption

Peergos gives fine grained control over read access to files and directories. This is done using a slightly simplified version of cryptree to control read access to individual files. All encrpytion is done using TweetNaCl. A cryptree is a tree of symmetric keys, with a link from key A to key B meaning the holder of key A can decrypt key B. A back link is provided for each file to allow a well defined path, which can be deduced by readers of a file, even if they can't read the parent folder.

Decentralized log-in

A Peergos user's private keys are not stored anywhere, but derived everytime they log in from their username and password. The username and password are put through the scrypt hashing algortihm, with configurable parameters, to derive the users identity key pairs (signing and boxing), and symmetric root key. The symmetric root key is used to decrypt the users root directory in the cryptree. The signing keypair is only used to sign updates to the filesystem. The boxing keypair is only used in sending follow requests, which enable files to be shared between users.

The default difficulty of scrypt is tuned to about a few seconds on a mobile device, but also so that a random 12 character alpha-numeric password would cost more than the annual budget of the NSA and take a year to crack by brute force.

Capabilities

Files in Peergos can be accessed using a cryptographic capability made up of a public signing key, a label, and a symmetric base key. The signing key is used to look up the root of a merkle-btree holding all the filesystem it controls. The label (32 random bytes) is used to lookup the file in the btree. After retrieval, it can be decrypted using the base key. Every directory, or up to 5 MiB chunk of a file has a different random label in the btree.

Each user stores a list of capabilities (symmetrically encrypted with their root key) in IPFS. One of these entry points tells the users where their root directory is in their btree. Others may correspond to folders that other users have shared with them.