cassh/cassh.1

.\" 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 March 01, 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
.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, and an optional
.Pa ./serial.txt
file holding the current serial number for the issued certificates.
.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.
.It %f
The basename of the public key being signed.
.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
is copied verbatim to the output, and
.Cm cert-authority
is always added.
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
is copied verbatim to the output.
See
.Xr sshd 8 SSH_KNOWN_HOSTS FILE FORMAT
for details.
.El
.Sh FILES
.Bl -tag -width MMMMMMMMMMMMMM -compact
.It Pa ./ca.pub
Certification Authority public key
.It Pa ./pubkeys/
Directory containing the public keys to be signed
.It Pa ./serial.txt
Last issued serial
.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.