🔐 Keybase team encrypted file sharing

Keybase is a cryptographically secure, popular tool to verify identities, and provide secure groups, files and chats.

We are using keybase filesystem (KBFS) for securely sharing encrypted files (containing keys, passwords, etc). This announcement explains the high-level, this documentation page goes into further detail, and the KBFS Crypto Spec explains how their cryptography works (see the link to Saltpack, which is used for the encryption format).

Team file sharing directories are mounted to /Volumes/Keybase/team/TEAM.NAME. For example, the helm_project file sharing would be mounted to /Volumes/Keybase/team/helm_project (see Known issues and workarounds below).

Prerequisites

Install the keybase client (download or for macos brew install --cask keybase)
Create a keybase account (it's a good idea to create a keybase name that's specific to you, and have only one account. For this reason it's not a good idea to include an organization in your username. Keybase discourages multiple accounts)
Authorize your device(s) (on CLI keybase device -h or Keybase client at at Settings > Devices > Add Device or Paper Key and select Add a computer or Add a phone)
Download a "paper key". This is your backup in case you loose your authorized devices (on the command line see keybase paperkey -h, or in Keybase client at Settings > Devices > Add Device or Paper Key and select Create a paper key). It's a good idea to keep this "paper key" somewhere secure and accessible outside your device (like in a personal LastPass account)
Add your PGP key to your keybase account (on the command line, see keybase pgp import help, or use the keybase app UI to add your PGP key). This is necessary for encryption and decryption
Enable KBFS (for macos, in Keybase client at Settings > Files > Enable Keybase in Finder. Enabling on a Linux machine takes a bit more work).

Process

⚠️ Never store sensitive information in unencrypted files on your machine or in the keybase file system. Always use encryption.

Example encryption

$ TEAM=team.name
$ ACCOUNT=foo.com
$ UNSAFE='username:bar
email:[email protected]
password:qux'
$ keybase encrypt --team $TEAM -m "$UNSAFE" -o /Volumes/Keybase/team/$TEAM/$ACCOUNT.saltpack
$ unset UNSAFE

Example decryption

$ ACCOUNT=foo.com
$ keybase decrypt -i /Volumes/Keybase/team/$TEAM/$ACCOUNT.saltpack

Alternatively use Vim

To bypass concerns about storing sensitive data in Bash history, alternatively use Vim with an autocommand group like the one below. Adding this to your ~/.vimrc will auto-encrypt/decrypt files with .saltpack extension, drawing the Keybase team name from the file's directory:

" Adapted from: https://vim.fandom.com/wiki/Edit_gpg_encrypted_files
" Note the keybase team name is derived from the directory containing the file.
" See https://vim.fandom.com/wiki/Get_the_name_of_the_current_file
"
" Don't save backups of *.saltpack files
set backupskip+=*.saltpack
" To avoid that parts of the file is saved to .viminfo when yanking or
" deleting, empty the 'viminfo' option.
set viminfo=
"
augroup encrypted
  au!
  " Disable swap files, and set binary file format before reading the file
  autocmd BufReadPre,FileReadPre *.saltpack
    \ setlocal noswapfile bin
  " Decrypt the contents after reading the file, reset binary file format
  " and run any BufReadPost autocmds matching the file name without the .saltpack
  " extension
  autocmd BufReadPost,FileReadPost *.saltpack
    \ execute "'[,']!keybase decrypt 2> /dev/null" |
    \ setlocal nobin |
    \ execute "doautocmd BufReadPost " . expand("%:r")
  " Set binary file format and encrypt the contents before writing the file
  autocmd BufWritePre,FileWritePre *.saltpack
    \ setlocal bin |
    \ execute "'[,']!keybase encrypt --team" expand('%:p:h:t')
  " After writing the file, do an :undo to revert the encryption in the
  " buffer, and reset binary file format
  autocmd BufWritePost,FileWritePost *.saltpack
    \ silent u |
    \ setlocal nobin
augroup END

Also see

Command ref: https://keybase.io/docs/command_line
Encryption info: https://saltpack.org/

Known issues and workarounds

💡If you're unable to "Enable Keyabse in Finder", you may not have direct access to /Volumes/Keybase/team/*. The following suite of keybase fs commands have been used as a successful workaround:

$ keybase fs ls /Volumes/Keybase/team/$TEAM/
foo.com.saltpack
$ keybase fs read /Volumes/Keybase/team/$TEAM/foo.com.saltpack | keybase decrypt

todaywasawesome/keybase-team-encrypted-fs.md