hiba-chk.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-chk - OpenSSH helper for host identity based authorizations.
.SH SYNOSPSIS
.B hiba-chk
.RI "[-v] [-g " "grl_file" "] -i " "identity_file" " -r " "role" " -p " "principal" " " "grant_file"
.br
.B hiba-chk
.RI "[-v] [-g " "grl_file" "] -i " "host_certificate" " -r " "role" " " "user_certificate"
.SH DESCRIPTION
.B hiba-chk
performs checks between a
.I host_identity
and a
.I user_grant.
.PP
Both can be provided as OpenSSH host and user certificates containing HIBA extensions generated by
.B hiba-gen
and attached to the certificate using
.B hiba-ca.sh
(or any other certificate authority that supports HIBA extensions).
.PP
Alternatively,
.B hiba-chk
accepts direct HIBA extensions, mostly for testing, or debugging authorizations. In this case, the
.I -p principal
option must be provided as it can't be extracted from the
.RI "" "user_certificate" "."
The certificate serial and issued time will be hardcoded, causing revocations to be all or nothing and validity check to always pass.
.PP
.B hiba-chk
also requires the
.I role
to grant access to and optionally a
.I grl_file
that contains the list of revoked grants inside certificates.
.SH OPTIONS
This program only accepts short options (single dash).
.TP
.B \-v
Turn on verbose mode. This flag can be repeated up to 3 times for increased verbosity.
.TP
.B \-g
The path to a grl_file.
.TP
.B \-i
The host identity, either as an openssh host certificate with a HIBA identity extension, or a direct HIBA identity extension.
.TP
.B \-r
The role to grant access to.
.TP
.B \-p
The principal to allow. This option is only necessary when not using certificates.
.SH EXIT STATUS
.B hiba-chk
display the dynamically generated
.I authorized_users
file to stdout, as expected by
.B sshd
(nothing will be printed if access is denied). It will terminate with an exit code set to zero if access is granted. If the access is denied it will set the exit code to a non-zero value representing the authorization error:
.TP 24
.B HIBA_CHECK_NOKEY
(40) One of the key from the HIBA grant cannot be found in the host identity.
.TP
.B HIBA_CHECK_BADVERSION
(41) The HIBA grant and HIBA identity versions are incompatible.
.TP
.B HIBA_CHECK_EXPIRED
(42) The HIBA grant is expired.
.TP
.B HIBA_CHECK_REVOKED
(43) The HIBA grant was revoked.
.TP
.B HIBA_CHECK_NOGRL
(44) The
.I grl_file
is specified but cannot be found.
.TP
.B HIBA_CHECK_BADHOSTNAME
(45) The HIBA grant references another hostname.
.TP
.B HIBA_CHECK_BADROLE
(46) The HIBA grant doesn't allow access as current requested role.
.TP
.B HIBA_CHECK_NOGRANTS
(47) The user certificate doesn't contain any HIBA grants.
.TP
.B HIBA_CHECK_DENIED
(48) The HIBA grant contains a key/pair not matching the host identity.
.SH EXAMPLE
.RS 4
.nf
$ hiba-gen -d -f host.hiba
identity@hibassh.dev (v1):
 [0] domain = 'google.com'
 [1] owner = 'hiba'

$ hiba-gen -d -f user.hiba
grant@hibassh.dev (v1):
 [0] domain = 'google.com'
 [1] role = 'user'

# Test access denied
$ hiba-chk -i host.hiba -r root -p principal user.hiba
$ echo $?
46

# Test access granted
$ hiba-chk -i host.hiba -r user -p principal user.hiba
principal
$ echo $?
0
.fi
.SH SEE ALSO
.BR hiba-ca.sh (1),
.BR hiba-gen (1),
.BR hiba-grl (1),
.BR sshd_config (1),
.BR ssh-keygen (1)