From b0ac5f559d156cd8791dcd2c6149e9cd953c5371 Mon Sep 17 00:00:00 2001 From: djm Date: Sun, 19 Dec 2021 22:14:12 +0000 Subject: [PATCH] document destination-constrained keys feedback / ok markus@ --- usr.bin/ssh/ssh-add.1 | 84 +++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 82 insertions(+), 2 deletions(-) diff --git a/usr.bin/ssh/ssh-add.1 b/usr.bin/ssh/ssh-add.1 index 2786df51417..83a6b9a3ebe 100644 --- a/usr.bin/ssh/ssh-add.1 +++ b/usr.bin/ssh/ssh-add.1 @@ -1,4 +1,4 @@ -.\" $OpenBSD: ssh-add.1,v 1.81 2020/07/14 23:57:01 djm Exp $ +.\" $OpenBSD: ssh-add.1,v 1.82 2021/12/19 22:14:12 djm Exp $ .\" .\" Author: Tatu Ylonen .\" Copyright (c) 1995 Tatu Ylonen , Espoo, Finland @@ -35,7 +35,7 @@ .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. .\" -.Dd $Mdocdate: July 14 2020 $ +.Dd $Mdocdate: December 19 2021 $ .Dt SSH-ADD 1 .Os .Sh NAME @@ -47,6 +47,8 @@ .Op Fl E Ar fingerprint_hash .Op Fl S Ar provider .Op Fl t Ar life +.Op Fl H Ar hostkey_file +.Op Fl h Ar destination_constraint .Op Ar .Nm ssh-add .Fl s Ar pkcs11 @@ -129,6 +131,84 @@ The default is .It Fl e Ar pkcs11 Remove keys provided by the PKCS#11 shared library .Ar pkcs11 . +.It Fl H Ar hostkey_file +Specifies a known hosts file to lookup hostkeys when using destination- +constained keys via the +.Fl h +flag. +This option may be specified multiple times to allow multiple files to be +searched. +If no files are specified, +.Nm +will use the default +.Xr ssh_config 5 +known hosts files: +.Pa ~/.ssh/known_hosts , +.Pa ~/.ssh/known_hosts2 , +.Pa /etc/ssh/ssh_known_hosts , +and +.Pa /etc/ssh/ssh_known_hosts2 . +.It Fl h Ar destination_constraint +When adding keys, constrain them to be usable only through specific hosts or to +specific destinations. +.Pp +Destination constraints of the form +.Sq [user@]dest-hostname +permit use of the key only from the origin host (the one running +.Xr ssh-agent 1 ) +to the listed destination host, with optional user name. +.Pp +Constraints of the form +.Sq src-hostname>[user@]dst-hostname +allow a key available on a forwarded +.Xr ssh-agent 1 +to be used through a particular host (as specified by +.Sq src-hostname ) +to authenticate to a further host, +specified by +.Sq dst-hostname . +.Pp +Multiple destination constraints may be added when loading keys. +When attempting authentication with a key that has destination constraints, +the whole connection path, including +.Xr ssh-agent 1 +forwarding, is tested against those constraints and each +hop must be permitted for the attempt to succeed. +For example, if key is forwarded to a remote host, +.Sq host-b , +and is attempting authentication to another host, +.Sq host-c , +then the operation will be successful only if +.Sq host-b +was permitted from the origin host and the subsequent +.Sq host-b>host-c +hop is also permitted by destination constraints. +.Pp +Hosts are identified by their host keys, and are looked up from known hosts +files by +.Nm . +Wildcards patterns may be used for hostnames and certificate host +keys are supported. +By default, keys added by +.Nm +are not destination constrained. +.Pp +Destination constraints were added in OpenSSH release 8.9. +Support in both the remote SSH client and server is required when using +destination-constrained keys over a forwarded +.Xr ssh-agent 1 +channel. +.Pp +It is also important to note that destination constraints can only be +enforced by +.Xr ssh-agent 1 +when a key is used, or when it is forwarded by a +.Sy cooperating +.Xr ssh 1 . +Specifically, it does not prevent an attacker with access to a remote +.Ev SSH_AUTH_SOCK +from forwarding it again and using it on a different host (but only to +a permitted destination). .It Fl K Load resident keys from a FIDO authenticator. .It Fl k -- 2.20.1