hiba-ca.sh.1

.\" Copyright 2021 The HIBA Authors
.\"
.\" Use of this source code is governed by a BSD-style
.\" license that can be found in the LICENSE file or at
.\" https://developers.google.com/open-source/licenses/bsd
.TH HIBA-CHK 1 "Dec, 1 2020"
.SH NAME
hiba-ca - Basic command line Certificate Authority with HIBA support.
.SH SYNOSPSIS
.SS Create a new CA
.B hiba-ca.sh
.RI "-c [-d " "capath" "] -- " "additional ssh-keygen options"
.SS Create a user/host identity
.B hiba-ca.sh
.RI "-c [-d " "capath" "] -u -I " "username" " -- " "additional ssh-keygen options"
.br
.B hiba-ca.sh
.RI "-c [-d " "capath" "] -h -I " "hostname" " -- " "additional ssh-keygen options"
.SS Import a user/host identity
.B hiba-ca.sh
.RI "-i [-d " "capath" "] [-I " "username" "] -u -f " "filename"
.br
.B hiba-ca.sh
.RI "-i [-d " "capath" "] [-I " "hostname" "] -h -f " "filename"
.SS Remove a user/host identity
.B hiba-ca.sh
.RI "-r [-d " "capath" "] -I " "username" " -u "
.br
.B hiba-ca.sh
.RI "-r [-d " "capath" "] -I " "hostname" " -h "
.SS Add policy permissions
.B hiba-ca.sh
.RI "-p [-d " "capath" "] -I " "username" " -H " "grant_name"
.SS Remove policy permissions
.B hiba-ca.sh
.RI "-p -r [-d " "capath" "] -I " "username" " -H " "grant_name"
.SS List CA content (doesn't show any secrets)
.B hiba-ca.sh
.RI "-l [-d " "capath" "] [-u] [-h] [-p] [-k]"
.SS Sign a user/host certificate
.B hiba-ca.sh
.RI "-s [-d " "capath" "] [-n " "principal" "] [-V " "validity" "] [-H " "HIBA" "] -u -I " "username" " -- " "additional ssh-keygen options"
.br
.B hiba-ca.sh
.RI "-s [-d " "capath" "] [-n " "principal" "] [-V " "validity" "] [-H " "HIBA" "] -h -I " "hostname" " -- " "additional ssh-keygen options"
.SS List CA certificate signing log
.B hiba-ca.sh
.RI "-k [-d " "capath" "] [-N " "days" "]"
.SS Clean up old CA certificate signing log
.B hiba-ca.sh
.RI "-k [-d " "capath" "] -c [-N " "days" "]"
.SS Revoke certificate
.B hiba-ca.sh
.RI "-k [-d " "capath" "] -r -z " "revocation_spec"
.SS Revoke HIBA grant
.B hiba-ca.sh
.RI "-k [-d " "capath" "] -r -H " "grant_name"
.SH DESCRIPTION
.B hiba-ca.sh
implements a basic Certificate Authority managed by the command line that supports several operations:
.nr step 1 1
.IP \n[step] 2
Create a CA key pair.
.IP \n+[step]
Create, import or remove a user/host key pair.
.IP \n+[step]
Add or Remove permissions for a user to request HIBA grants.
Note, removing permissions will also revoke all grants that are attached to corresponding known certificates.
.IP \n+[step]
Sign a user/host public key into a certificate, optionally attaching HIBA grants.
.IP \n+[step]
Revoke a user/host certificate or HIBA grant attached to a user certificate.
.PP
The Certificate Authority stores all the keys on disk, following a predefined structure.
This predefined structure allows to reference SSH identities as well as HIBA extensions directly by name.
It expects the HIBA extensions to be generated in the following folders:
.IP \[bu] 2
.IR "capath" "/policy/identities/" "identity_name"
.IP \[bu]
.IR "capath" "/policy/grants/" "grant_name"
.PP
And keeps the SSH identities in the following folders:
.IP \[bu] 2
.IR "capath" "/users/" "username"
.IP \[bu]
.IR "capath" "/users/" "username" ".pub"
.IP \[bu]
.IR "capath" "/users/" "username" "-cert.pub"
.IP \[bu]
.IR "capath" "/hosts/" "hostname"
.IP \[bu]
.IR "capath" "/hosts/" "hostname" ".pub"
.IP \[bu]
.IR "capath" "/hosts/" "hostname" "-cert.pub"
.PP
The policy permissions are managed via symlinks in the following folder:
.IP \[bu] 2
.IR "capath" "/policy/principals/" "username" "/" "grant_name1" " -> "
.IR "capath" "/policy/grants/" "grant_name1"
.IP \[bu]
.IR "capath" "/policy/principals/" "username" "/" "grant_name2" " -> "
.IR "capath" "/policy/grants/" "grant_name2"
.IP \[bu]
.RI ...
.PP
A few special files are also stored at the root of the CA path:
.IP \[bu] 2
.IR "capath" "/logs"
.IP \[bu]
.IR "capath" "/krl"
.IP \[bu]
.IR "capath" "/grl"
.SH OPTIONS
This program only accepts short options.
.TP
.B \-c
Create new identities (CA, user or host). When used with -k, clean up old logs.
.TP
.B \-l
Show the content of the certificate authority (not showing any secrets).
.TP
.B \-i
Import new identities (user or host).
.TP
.B \-r
Remove existing identities (user or host). When used with -p, remove HIBA policy permission.
When used with -k, revoke grants/certificates.
.TP
.B \-p
.RI "Add HIBA policy permission on a " "grant" " for a " "user" ". When used with -r, remove said permission.
.TP
.B \-s
Sign certificates (user or host).
.TP
.B \-k
Display signing logs. When used with -c, clean up old logs. When used with -r, revoke certificates or grants.
.TP
.B \-d
.IR "capath" " of the CA (will be initialized on the first call if it doesn't exist yet). Default to ~/.hiba-ca."
.TP
.B \-u
.RI "Request creating/importing/removing/signing a " "user" " certificate. When used with -l, shows information about users."
.TP
.B \-h
.RI "Request creating/importing/removing/signing a " "host" " certificate. When used with -l, shows information about hosts."
.TP
.B \-I
.RI "The " "name" " of the identity to create/sign. This is also used as the main " "principal" " during the signing operation."
.TP
.B \-n
.RI "Extra " "principal" " to add to the certificate. This flag can be repeated for adding more than one " "principal" "."
.TP
.B \-V
.IR "validity" " to set to the certificate. Default to '+1h'. See " "ssh-keygen(1)" " for the expected syntax."
.TP
.B \-z
.IR "serial" " pointing to a file containing certificate revocation specs or " "-" " for stdin. See " "ssh-keygen(1)" " for the expected syntax."
.TP
.B \-H
.RI "Name of the " "HIBA" " extensions to be attached to the certificate at signing time. This flag can be repeated for adding more than one " "HIBA" " extension. When used with -p this lists extensions to be added/removed. When used with -k, this lists grants to be revoked."
.SH NOTES
.RI "When the " "hiba-ca.sh" " generates the users & hosts private keys, it is for convenience only. It is not required to leave the private keys in the " "capath" ".
.SH EXAMPLE
.SS Creating a new CA
.RS 4
.nf
$ hiba-ca.sh -c -d /tmp/myca
== Generating CA keys in /tmp/myca/ca
Enter passphrase (empty for no passphrase): *******
Enter same passphrase again: *******
== Done
.fi
.SS Creating SSH identities
.RS 4
.nf
$ hiba-ca.sh -c -d /tmp/myca -u -I user1
== Generating user keys in /tmp/myca/users/user1
Enter passphrase (empty for no passphrase): *******
Enter same passphrase again: *******
== Done
Identity created: Private: /tmp/myca/users/user1
                  Public:  /tmp/myca/users/user1.pub
.fi
.SS Adding a HIBA extension to collection
.RS 4
.nf
$ hiba-gen -f /tmp/myca/policy/grants/o:user1 domain google.com owner user1
$ hiba-gen -d -f /tmp/myca/policy/grants/o:user1
grant@hibassh.dev (v1):
 [0] domain = 'google.com'
 [1] owner = 'user1'
.SS Granting user1 permissions to request grant o:user1
.RS 4
.nf
$ hiba-ca.sh -p -d /tmp/myca -I user1 -H o:user1
== Done ==
User user1 is now eligible for [o:user1]
.fi
.SS Signing SSH identities
.RS 4
.nf
$ hiba-ca.sh -s -d /tmp/myca -u -I user1 -H o:user1
== Signing user key ID user1
Signed user key /tmp/myca/users/user1-cert.pub: id "user1" serial 0 for user1 valid from 2020-11-29T19:00:00 to 2020-11-29T20:01:46
== Done
Certificate created: /tmp/myca/users/user1-pub.cert
$ hiba-gen -d -f /tmp/myca/users/user1-cert.pub
certificate 'user1' contains 1 HIBA grants
grant@hibassh.dev (v1):
 [0] domain = 'google.com'
 [1] owner = 'user1'
.fi
.SS Removing HIBA permission
.RS 4
.nf
$ hiba-ca.sh -p -r -d /tmp/myca -I user1 -H o:user1
== Done ==
User user1 is not eligible anymore for [o:user1]
$ hiba-ca.sh -s -d /tmp/myca -u -I user1 -H o:user1
user user1 not eligible for grant o:user1
== ERROR ==
.fi
.SS Revocations
.RS 4
.nf
$ hiba-ca.sh -k -d /tmp/myca
Signed certificates log for the last 90 days:
  [Thu Jan  6 06:20:15 PM CET 2022]: serial 1
  [Thu Jan  6 06:20:17 PM CET 2022]: serial 2
  [Thu Jan  6 06:20:18 PM CET 2022]: serial 3
  [Thu Jan  6 06:20:53 PM CET 2022]: serial 4
  [Fri Jan  7 01:39:24 PM CET 2022]: serial 5
  [Fri Jan  7 01:43:06 PM CET 2022]: serial 6

$ echo "serial: 5" | hiba-ca.sh -k -r -z -

$ hiba-ca.sh -p -d /tmp/myca -r -I user -H grant_to_revoke
== This action will revoke grants in 1 certificate(s).
Do you want to continue? (y|N)
y
== Done ==

$ hiba-ca.sh -l -d /tmp/myca -k
== Certificate Authority location ==
/tmp/myca

== KRL ==
* KRL version 1641575432
* Generated at 20220107T110152
hash: SHA256:SHA256:I0i7+kR3A8oDebXEQn78sH9H7o3ocblcvD7xc0oay+8 * ssh-rsa
* CA key ssh-rsa SHA256:TBOrQxMpZqV9zok9QxanxQuRsJX4aAEy6ALPeCudvDc
serial: 5

== GRL ==
HIBA GRL (v1):
  comment: /tmp/myca 3072 SHA256:TBOrQxMpZqV9zok9QxanxQuRsJX4aAEy6ALPeCudvDc tlelong@tlelong (RSA)
  timestamp: 1641575543
  entries: 1
  [0x0000000000000003]: 20
.SH SEE ALSO
.BR hiba-chk (1),
.BR hiba-gen (1),
.BR hiba-grl (1),
.BR ssh-keygen (1)