Contributing and Additional Info¶
There are two separate binaries built from the code in this repo:
keybaseca¶
keybaseca
is the CA server that exposes an interface through Keybase chat.
This binary is meant to be run in a secure location.
NAME:
keybaseca - An SSH CA built on top of Keybase
USAGE:
keybaseca [global options] command [command options] [arguments...]
VERSION:
0.0.1
COMMANDS:
backup Print the current CA private key to stdout for backup purposes
generate Generate a new CA key
service Start the CA service in the foreground
help, h Shows a list of commands or help for one command
GLOBAL OPTIONS:
--help, -h show help
--version, -v print the version
kssh¶
kssh
is the replacement SSH binary. kssh handles provisioning (via the
keybaseca-bot) new temporary SSH keys and is meant to be installed on each
user’s laptop.
NAME:
kssh - A replacement ssh binary using Keybase SSH CA to provision SSH keys
USAGE:
kssh [kssh options] [ssh arguments...]
VERSION:
0.0.1
GLOBAL OPTIONS:
--help Show help
-v Enable kssh and ssh debug logs
--provision Provision a new SSH key and add it to the ssh-agent. Useful if you need to run another
program that uses SSH auth (eg scp, rsync, etc)
--set-default-bot Set the default bot to be used for kssh. Not necessary if you are only in one team that
is using Keybase SSH CA
--clear-default-bot Clear the default bot
--bot Specify a specific bot to be used for kssh. Not necessary if you are only in one team that
is using Keybase SSH CA
--set-default-user Set the default SSH user to be used for kssh. Useful if you use ssh configs that do not set
a default SSH user
--clear-default-user Clear the default SSH user
--set-keybase-binary Run kssh with a specific keybase binary rather than resolving via $PATH
Architecture¶
Config¶
Keybaseca is configured using environment variables (see docs/env.md for
information on all of the options). When keybaseca starts, it writes a client
config JSON blob to the KV store for
each team in $TEAMS
, at namespace __sshca
, entry key kssh_config
. This
client config is how kssh determines which teams are using kssh and the needed
information about the bot (eg the channel name, the name of the bot, etc). When
keybaseca stops, it deletes all of the client configs.
kssh reads the client config in order to determine how to interact with a
bot. kssh does not have any user controlled configuration. It does have one
local config file stored in ~/.ssh/kssh-config.json
that is used to store a
few settings for kssh. By default, this config file is not used. It is only
created and meant to be interacted with via the --set-default-bot
,
--clear-default-bot
, --set-default-user
, --clear-default-user
flags.
Communication¶
kssh and keybaseca communicate with each other over Keybase chat. If the
CHAT_CHANNEL
environment variable is specified in keybaseca’s environment,
keybaseca will only accept communication in the specified team and channel.
This configuration is passed to kssh clients via the client configs stored in
the KV store. If the CHAT_CHANNEL
environment variable is not specified then keybaseca will accept messages in
any channel of any team listed in the TEAMS
environment variable. All
communication happens via the Go chat bot library.
Prior to sending a SignatureRequest
, kssh sends a series of AckRequest
messages. An AckRequest
message is sent until kssh receives an Ack
from
keybaseca. This is done in order to ensure that kssh has correctly connected to
the chat channel and that the bot is responding to messages. Afterwards, a
SignatureRequest
packet is sent and keybaseca parses it and returns a signed
key. Note that only public keys and signatures are sent over Keybase chat and
private keys never leave the devices they were generated on.
SSH Operations¶
When the ssh-keygen command is available, ssh keys are generated via the ssh-keygen command. In this case, generated SSH keys are ed25519 keys. If the ssh-keygen command is not available, SSH keys are generated in pure go code and are ecdsa keys.
keybaseca uses the ssh-keygen binary in order to complete all key signing operations.
KBFS¶
keybaseca supports logging to a local or KBFS file. In order to ensure that
keybaseca can run inside of docker (which does not support FUSE filesystems
without adding the CAP_SYS_ADMIN permission), all KBFS interactions are done
via keybase fs ...
commands. This makes it so that keybaseca can run in
unprivileged docker containers.
Integration Tests¶
This project contains integration tests that can be run via
./integrationTest.sh
. The integration tests depend on docker and
docker-compose. The first time you run them, they will walk you through
creating two new live keybase accounts to be used in the tests. The credentials
for these accounts will be stored in tests/env.sh
.