add sshca.md

1 files changed, 100 insertions, 0 deletions

diff --git a/sshca.md b/sshca.md
new file mode 100644
index 0000000..85a981c
--- /dev/null
+++ b/sshca.md
@@ -0,0 +1,100 @@
+# Abstract
+
+This is a sketch of an idea for a little command line tool for
+managing SSH CA keys and making certificates.
+
+# SSH CA
+
+An SSH CA is an SSH key used to certify host and user keys. When a
+host key is certificate, each user can configure their SSH client to
+trust a host certificated made with a known CA key. They then only
+ever need to verify that the CA key is valid, rather than every new
+host key. The host certificate can specify the host name that it's
+valid for.
+
+Similarly, a sysadmin can configure their SSH server to trust user
+certificate made with a CA key. The user certificate specifies which
+user account on the server it's valid for. This means the user doesn't
+need to have a password so they can log in once to add their SSH
+public key to their `authorized_keys` file on the server.
+
+
+# `sshca` the command line tool
+
+`sshca` is a command line tool for managing SSH CA keys and making
+certificates. It's a wrapper around the `ssh-keygen` tool that aims to
+be easier to use and harder to misuse.
+
+Each certificate has an automatically chosen serial number. `sshca`
+keeps track of the serial numbers that have been used.
+
+Certificates can optionally have a validity period (valid from a time,
+and until a time). The period may be open ended.
+
+
+
+
+## Generate an SSH CA key
+
+To generate a new SSH CA key pair and give is a short name:
+
+```sh
+$ sshca generate NAME
+```
+
+The key pair will be stored in `~/.ssh/sshca` and will by default be
+of type `ed25519` (elliptic curve), for higher security and smaller
+key size. The type can be specified with an option.
+
+
+## List existing SSH CA keys
+
+To list SSH CA keys:
+
+```sh
+$ sshca list
+default ed25519 ....
+```
+
+This lists all the keys in the `~/.ssh/sshca` directory.
+
+
+## Removing an SSH CA key
+
+To remove an SSH CA key:
+
+```sh
+$ sshca remove-key NAME
+```
+
+This removes the named key from the `~/.ssh/sshca` directory.
+
+
+## Create a host certificate
+
+To create a host certificate:
+
+```sh
+$ sshca cert-host KEYNAME HOSTPUB HOSTNAME > FILENAME
+```
+
+This create a host certificate using a named SSH CA key, for a given
+host public key, and ties it a given host name. The certificate is
+written to the standard output, and can be redirected to a file as
+usual on the command line.
+
+
+## Create a user certificate
+
+To create a user certificate:
+
+```sh
+$ ssh ca cert-user KEYNAME USERPUB USERNAME > FILENAME
+```
+
+Similar to a host certificate, but for a user.
+
+
+---
+title: SSH CA helper
+...