🔐 Keybase team encrypted file sharing

keybase-team-encrypted-fs.md

🔐 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

1. Install the keybase client (download or for macos brew install --cask keybase)
2. 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)
3. 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)
4. 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)
5. 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
6. 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:baz@baz.com
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

in 2021 brew cask install is now brew install --cask made an edit here https://gist.github.com/todaywasawesome/c865a71628a7eb699a93da67fc27c961

in 2021 brew cask install is now brew install --cask made an edit here https://gist.github.com/todaywasawesome/c865a71628a7eb699a93da67fc27c961

Thanks Dan! Updated the gist ✨

The approach is quite good and can be quite good for seamlessly sharing sensitive data within a team.

Key point to bear into mind is that if KBFS is mapped locally when the user is logged in, effectively anything running at the context of the user would have access to the unencrypted files, which could lead to leakage - (e.g. curl ... | bash or supply chain deps that look for sensitive data and upload somewhere).

Around using/storing sensitive info on bash history, there are a few ways around it. By default (depending on distro) bash commands that start with a space won't be captured. That will still be on the shell buffer for a while, but at least not accessible in plain-text in disk.