| .\" 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) |
