upstream: document agent protocol extensions

OpenBSD-Commit-ID: 09e8bb391bbaf24c409b75a4af44e0cac65405a7

1 files changed, 82 insertions, 3 deletions

diff --git a/PROTOCOL.agent b/PROTOCOL.agent
index ed47146a3..41e76c733 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 $