1$NetBSD: PROTOCOL.agent,v 1.15 2023/12/20 17:15:20 christos Exp $
2The SSH agent protocol is described in
3https://tools.ietf.org/html/draft-miller-ssh-agent
4
5This file documents OpenSSH's extensions to the agent protocol.
6
71. session-bind@openssh.com extension
8
9This extension allows a ssh client to bind an agent connection to a
10particular SSH session identifier as derived from the initial key
11exchange (as per RFC4253 section 7.2) and the host key used for that
12exchange. This binding is verifiable at the agent by including the
13initial KEX signature made by the host key.
14
15The message format is:
16
17	byte		SSH_AGENTC_EXTENSION (0x1b)
18	string		session-bind@openssh.com
19	string		hostkey
20	string		session identifier
21	string		signature
22	bool		is_forwarding
23
24Where 'hostkey' is the encoded server host public key, 'session
25identifier' is the exchange hash derived from the initial key
26exchange, 'signature' is the server's signature of the session
27identifier using the private hostkey, as sent in the final
28SSH2_MSG_KEXDH_REPLY/SSH2_MSG_KEXECDH_REPLY message of the initial key
29exchange. 'is_forwarding' is a flag indicating whether this connection
30should be bound for user authentication or forwarding.
31
32When an agent received this message, it will verify the signature and
33check the consistency of its contents, including refusing to accept
34a duplicate session identifier, or any attempt to bind a connection
35previously bound for authentication. It will then record the
36binding for the life of the connection for use later in testing per-key
37destination constraints.
38
392. restrict-destination-v00@openssh.com key constraint extension
40
41The key constraint extension supports destination- and forwarding path-
42restricted keys. It may be attached as a constraint when keys or
43smartcard keys are added to an agent.
44
45	byte		SSH_AGENT_CONSTRAIN_EXTENSION (0xff)
46	string		restrict-destination-v00@openssh.com
47	constraint[]	constraints
48
49Where a constraint consists of:
50
51	string		from_username (must be empty)
52	string		from_hostname
53	keyspec[]	from_hostkeys
54	string		to_username
55	string		to_hostname
56	keyspec[]	to_hostkeys
57
58And a keyspec consists of:
59
60	string		keyblob
61	bool		is_ca
62
63When receiving this message, the agent will ensure that the
64'from_username' field is empty, and that 'to_hostname' and 'to_hostkeys'
65have been supplied (empty 'from_hostname' and 'from_hostkeys' are valid
66and signify the initial hop from the host running ssh-agent). The agent
67will then record the constraint against the key.
68
69Subsequent operations on this key including add/remove/request
70identities and, in particular, signature requests will check the key
71constraints against the session-bind@openssh.com bindings recorded for
72the agent connection over which they were received.
73
743. SSH_AGENT_CONSTRAIN_MAXSIGN key constraint
75
76This key constraint allows communication to an agent of the maximum
77number of signatures that may be made with an XMSS key. The format of
78the constraint is:
79
80	byte		SSH_AGENT_CONSTRAIN_MAXSIGN (0x03)
81	uint32		max_signatures
82
83This option is only valid for XMSS keys.
84
853. associated-certs-v00@openssh.com key constraint extension
86
87The key constraint extension allows certificates to be associated
88with private keys as they are loaded from a PKCS#11 token.
89
90	byte		SSH_AGENT_CONSTRAIN_EXTENSION (0xff)
91	string		associated-certs-v00@openssh.com
92	bool		certs_only
93	string		certsblob
94
95Where "certsblob" constists of one or more certificates encoded as public
96key blobs:
97
98	string[]	certificates
99
100This extension is only valid for SSH_AGENTC_ADD_SMARTCARD_KEY_CONSTRAINED
101requests. When an agent receives this extension, it will attempt to match
102each certificate in the request with a corresponding private key loaded
103from the requested PKCS#11 token. When a matching key is found, the
104agent will graft the certificate contents to the token-hosted private key
105and store the result for subsequent use by regular agent operations.
106
107If the "certs_only" flag is set, then this extension will cause ONLY
108the resultant certificates to be loaded to the agent. The default
109behaviour is to load the PKCS#11-hosted private key as well as the
110resultant certificate.
111
112A SSH_AGENTC_ADD_SMARTCARD_KEY_CONSTRAINED will return SSH_AGENT_SUCCESS
113if any key (plain private or certificate) was successfully loaded, or
114SSH_AGENT_FAILURE if no key was loaded.
115
116$OpenBSD: PROTOCOL.agent,v 1.21 2023/12/18 14:46:56 djm Exp $
117