High Level Architecture Design¶

Authentication¶

PigeonHole does not store any username/passwords for authentication by design. From the very beginning PigeonHole requires you to authenticate through a third-party Identity Provider like Microsoft (Azure) and Google.

Secret Multi-factor Authentication (MFA)¶

PigeonHole adds MFA on at a secret level. This means when you share a secret with a recipient, you can enable the secret to challenge for an MFA code before it is downloaded by the client.

This is achieved through the industry-standard TOTP algorithm.

Data Encryption¶

All data is encrypted on the sender's workstation and only decrypted at the recipient's workstation.

Data Integrity¶

OpenPGP checksums and signatures are created prior to encrypting and verified at the recipient's workstation once retrieved and decrypted. Should the integrity fail the files would be shredded and the download process retried.

Secure File Shredding¶

Should the sender or recipient require the file to irretrievable (even through data recovery techniques), the file shredding feature will first write randomly-generated bytes at a block level then delete the file.

Encryption Keys¶

Location¶

All the private encryption keys are kept on the sender's machine and there are no master keys on our servers - even encrypted ones! This means PigeonHole cannot decrypt or intercept raw content. PigeonHole only has senders' public keys which are completely safe to share.

Keys are stored in sender's workstation system keyring services;
1. Windows - Windows Credential Store
2. Linux - Secret Service dbus interface (provided by GNOME Keyring)
3. MacOS - Keychain

Inspection¶

If users wish they can inspect their own keys using standard GPG tooling.

Note: The PEM formatted keys are base16 encoded to avoid particular corruption scenarios.

Rotation¶

Users can rotate and upload new keys at any point by performing pigeonhole keys rotate.

Public Keys¶

OpenPGP public keys are created on each user's workstation using the email address provided by their Identity Provider (IdP).

File Encryption¶

Behind the scenes PigeonHole uses the OpenPGP library maintained by ProtonMail to achieve secret sharing you can trust - there is never any man-in-the-middle!

File encryption and decryption always happens within the sender/recipient's command-line.