.\" cassh - Manager for an OpenSSH Certification Authority
.\"
.\" Written in 2022 by Lucas
.\"
.\" To the extent possible under law, the author(s) have dedicated all
.\" copyright and related and neighboring rights to this software to the
.\" public domain worldwide. This software is distributed without any
.\" warranty.
.\"
.\" You should have received a copy of the CC0 Public Domain Dedication
.\" along with this software. If not, see
.\" <http://creativecommons.org/publicdomain/zero/1.0/>.
.\"
.Dd April 20, 2022
.Dt CASSH 1
.Os
.Sh NAME
.Nm cassh
.Nd Manager for an OpenSSH Certification Authority
.Sh SYNOPSIS
.Nm
.Bk -words
.Cm issue
.Op Fl hqv
.Op Fl I Ar key_id
.Op Fl n Ar principals
.Op Fl V Ar validity_interval
.Ek
.Nm
.Bk -words
.Cm mkfile
.Ic authorized_keys
.Op options ...
.Ek
.Nm
.Bk -words
.Cm mkfile
.Ic known_hosts
.Op hostnames ...
.Ek
.Nm
.Bk -words
.Cm revoke
.Op Fl qv
.Ar
.Ek
.Sh DESCRIPTION
.Nm
is a small utility for issuing and revoking OpenSSH Certificates.
It relies on a simple filesystem structure and a running
.Xr ssh-agent 1
instance that is in charge of performing all signing operations.
Additionally,
.Nm
can generate
.Pa authorized_keys
and
.Pa known_hosts
files based on the active Certification Authority.
.Pp
A Certification Authority directory consists of a
.Pa ./ca.pub
file corresponding to the public key of it, a
.Pa ./pubkeys/
directory which holds the public keys to be signed, an optional
.Pa ./krl
file corresponding to the last issued Key Revocation List, and optional
.Pa ./ca_serial.txt
and
.Pa ./krl_serial.txt
files corresponding to the current serial number for the issued certificates
and Key Revocation Lists.
.Pp
The following commands are available to
.Nm :
.Bl -tag -width Ds
.It Xo
.Cm issue
.Op Fl hqv
.Op Fl I Ar key_id
.Op Fl n Ar principals
.Op Fl V Ar validity_interval
.Xc
Issue certificates for all the public keys inside the
.Pa pubkeys/
directory.
Token expansion is performed on arguments
.Ar key_id
and
.Ar principals .
The recognized tokens are:
.Pp
.Bl -tag -width MMMM -offset indent -compact
.It %%
A literal
.Sq % .
.It \&%C
The Certification Authority private key comment field as reported by
.Xr ssh-add 1 ,
or the string
.Sq cassh
if there is no comment reported.
.It %f
The basename of the public key being signed, without
.Sq .pub
suffix.
.El
.Pp
.Ar key_id
accepts the tokens %%, %C, and %f.
It defaults to
.Dq %C/%f .
.Pp
.Ar principals
accepts the tokens %% and %f.
.Pp
After token expansion, all recognized options are passed down to
.Xr ssh-keygen 1
process.
.It Cm mkfile Ic authorized_keys Op Ar options ...
Write an
.Ic authorized_keys
file on standard output corresponding to the current Certification
Authority.
.Ar options
are concatenated with commas and copied verbatim to the output.
.Cm cert-authority
is always added to the options list.
See
.Xr sshd 8 AUTHORIZED_KEYS FILE FORMAT
for details.
.It Cm mkfile Ic known_hosts Op Ar hostnames ...
Write a
.Ic known_hosts
file on standard output corresponding to the current Certification
Authority.
.Ar hostnames
are concatenated with commas and copied verbatim to the output.
See
.Xr sshd 8 SSH_KNOWN_HOSTS FILE FORMAT
for details.
.It Cm revoke Oo Fl qv Oc Ar
Generates a Key Revocation List for the current Certification Authority.
All recognized options are passed down to
.Xr ssh-keygen 1
process.
See
.Xr ssh-keygen 1 KEY REVOCATION LISTS
for details on the file format for input files.
If
.Pa ./krl
exists,
.Cm revoke
will update.
.Pa ./krl
can be synced back with the input files by first removing it.
.El
.Sh FILES
.Bl -tag -width MMMMMMMMMMMMMMMMMM -compact
.It Pa ./ca.pub
Certification Authority public key
.It Pa ./pubkeys/
Directory containing the public keys to be signed
.It Pa ./krl
Key Revocation List
.It Pa ./ca_serial.txt
Last issued serial for certificates
.It Pa ./krl_serial.txt
Last issued serial for KRLs
.El
.Sh EXIT STATUS
.Ex -std
.Sh SEE ALSO
.Xr ssh-agent 1 ,
.Xr ssh-keygen 1 ,
.Xr sshd 8 AUTHORIZED_KEYS FILE FORMAT ,
.Xr sshd 8 SSH_KNOWN_HOSTS FILE FORMAT
.Sh AUTHORS
.An Lucas
.Sh LICENSE
.Nm
is in the public domain.
.Pp
To the extent possible under law, the author(s) have dedicated all
copyright and related and neighboring rights to this software to the
public domain worldwide.
.Pp
.Lk http://creativecommons.org/publicdomain/zero/1.0/
.Sh CAVEATS
Currently, there is no support for revoking certificates.