Skip to content
Save my spot

Encryption: file content, keys and signatures

Which standard algorithms protect a file sent from device to device, what each one does, and what the profile does not promise.

This describes transfers from device to device, directly or through the relay (server route). Files you keep in pipeit Cloud are stored so the service can work with them and do not use this end-to-end profile; see Security and frequently asked questions.

The file crypto profile combines standard algorithms with different jobs:

AlgorithmJob in the file profile
AES-256-GCM with a 128-bit tagAuthenticated encryption of the content and of the encrypted manifest
RSA-OAEP-3072 with SHA-256Wrapping the random file key for the specific receiving device
ECDSA P-256 with SHA-256Signing the exact envelope bytes and context-bound device and transfer receipts
SHA-256Fingerprints and checking ciphertext and plaintext integrity

Scroll sideways to see the whole table.

Each new file preparation creates a random 256-bit file key and a random 64-bit nonce prefix. For every encryption step a 96-bit GCM nonce is derived from it: prefix plus a 32-bit chunk index in big-endian order. Index 0 is reserved for the encrypted manifest, data starts at index 1. A regular crypto chunk holds up to 4 MiB of plaintext. Profile limits prevent an unbounded index space.

Additional authenticated data (AAD) binds the encryption to the protocol version, the transfer, the devices and the chunk index, among other things. Valid bytes from another transfer therefore cannot simply be inserted as matching chunks. The RSA wrapping also uses a label that fits the job and the receiver. The signature covers the original envelope bytes; parsing and re-serializing JSON would be no substitute for this byte binding.

DiagramHow a file is encrypted for its receiverDiagram: the original file is split into chunks with a plaintext hash. A random file key encrypts the chunks and the manifest with AES-GCM and is wrapped with RSA-OAEP for the receiver. Both results form the envelope with encrypted chunks, and the sender signs the exact envelope bytes.
  1. Original fileSplit into chunks of up to 4 MiBFile dataChunks and plaintext hash
  2. Chunks and plaintext hashEncrypt each chunkFile dataAES-GCM
  3. Random file keyKey for content and manifestControl and permissionsAES-GCM
  4. Name, size and hashEncrypted manifestFile dataAES-GCM
  5. Random file keyWrap the key for the receiving deviceControl and permissionsRSA-OAEP for the receiver
  6. AES-GCMCiphertextFile dataEnvelope and encrypted chunks
  7. RSA-OAEP for the receiverWrapped keyControl and permissionsEnvelope and encrypted chunks
  8. Envelope and encrypted chunksThe sender signs the exact envelope bytesControl and permissionsSender signature

The original file name and the plaintext file hash are in the encrypted manifest. What stays visible for control are metadata such as the parties, sizes, times, profile and status. pipeit clients keep file names and keys out of diagnostics and local logs.

Transport encryption and end-to-end encryption serve different purposes

The relay sees TLS traffic, never file contents. TLS protects a connection. On the HTTPS and WebSocket relay (server route) that TLS connection ends at the platform; the additional file encryption ends only at the receiver. The relay needs no private file key for that. A paired device must, however, really be the intended receiver: an arbitrary public-key string delivered by a server is no substitute for a trustworthy device comparison.

What the profile does not promise

The file profile does not promise forward secrecy or post-compromise security. The properties of a TLS channel must not be carried over to long-lived encrypted file keys. A compromised end device or maliciously delivered web code also lies within a different trust boundary than a passively listening relay server.

Related guides

Under the hoodConnectivity: nearby, WebRTC, TLS, routing and ICMP