From 3d00024b3b156aa9bbd05d105f1deb9cb088f6f7 Mon Sep 17 00:00:00 2001 From: "djm@openbsd.org" Date: Sun, 19 Dec 2021 22:15:21 +0000 Subject: upstream: document agent protocol extensions OpenBSD-Commit-ID: 09e8bb391bbaf24c409b75a4af44e0cac65405a7 --- PROTOCOL.agent | 85 +++++++++++++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 82 insertions(+), 3 deletions(-) (limited to 'PROTOCOL.agent') diff --git a/PROTOCOL.agent b/PROTOCOL.agent index ed47146a..41e76c73 100644 --- a/PROTOCOL.agent +++ b/PROTOCOL.agent @@ -1,5 +1,84 @@ -This file used to contain a description of the SSH agent protocol -implemented by OpenSSH. It has since been superseded by +The SSH agent protocol is described in https://tools.ietf.org/html/draft-miller-ssh-agent-04 -$OpenBSD: PROTOCOL.agent,v 1.14 2020/10/06 07:12:04 dtucker Exp $ +This file document's OpenSSH's extensions to the agent protocol. + +1. session-bind@openssh.com extension + +This extension allows a ssh client to bind an agent connection to a +particular SSH session identifier as derived from the initial key +exchange (as per RFC4253 section 7.2) and the host key used for that +exchange. This binding is verifiable at the agent by including the +initial KEX signature made by the host key. + +The message format is: + + byte SSH_AGENTC_EXTENSION (0x1b) + string session-bind@openssh.com + string hostkey + string session identifier + string signature + bool is_forwarding + +Where 'hostkey' is the encoded server host public key, 'session +identfier' is the exchange hash derived from the initial key +exchange, 'signature' is the server's signature of the session +identifier using the private hostkey, as sent in the final +SSH2_MSG_KEXDH_REPLY/SSH2_MSG_KEXECDH_REPLY message of the initial key +exchange. 'is_forwarding' is a flag indicating whether this connection +should be bound for user authentication or forwarding. + +When an agent received this message, it will verify the signature and +check the consistency of its contents, including refusing to accept +a duplicate session identifier, or any attempt to bind a connection +previously bound for authentication. It will then then record the +binding for the life of the connection for use later in testing per-key +destination constraints. + +2. restrict-destination-v00@openssh.com key constraint extension + +The key constraint extension supports destination- and forwarding path- +restricted keys. It may be attached as a constraint when keys or +smartcard keys are added to an agent. + + byte SSH_AGENT_CONSTRAIN_EXTENSION (0xff) + string restrict-destination-v00@openssh.com + constraint[] constraints + +Where a constraint consists of: + + string from_username (must be empty) + string from_hostname + keyspec[] from_hostkeys + string to_username + string to_hostname + keyspec[] to_hostkeys + +An a keyspec consists of: + + string keyblob + bool is_ca + +When receiving this message, the agent will ensure that the +'from_username' field is empty, and that 'to_hostname' and 'to_hostkeys' +have been supplied (empty 'from_hostname' and 'from_hostkeys' are valid +and signify the inital hop from the host running ssh-agent). The agent +will then record the constraint against the key. + +Subsequent operations on this key including add/remove/request +identities and, in particular, signature requests will check the key +constraints agains the session-bind@openssh.com bindings recorded for +the agent connection over which they were received. + +3. SSH_AGENT_CONSTRAIN_MAXSIGN key constraint + +This key constraint allows communication to an agent of the maximum +number of signatures that may be made with an XMSS key. The format of +the constraint is: + + byte SSH_AGENT_CONSTRAIN_MAXSIGN (0x03) + uint32 max_signatures + +This option is only valid for XMSS keys. + +$OpenBSD: PROTOCOL.agent,v 1.15 2021/12/19 22:15:21 djm Exp $ -- cgit v1.2.1