1$NetBSD: PROTOCOL.agent,v 1.18 2025/04/09 15:49:31 christos Exp $
2The SSH agent protocol is described in
3https://datatracker.ietf.org/doc/draft-ietf-sshm-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          string              reserved
54          keyspec[] from_hostkeys
55          string              to_username
56          string              to_hostname
57          string              reserved
58          keyspec[] to_hostkeys
59          string              reserved
60
61And a keyspec consists of:
62
63          string              keyblob
64          bool                is_ca
65
66When receiving this message, the agent will ensure that the
67'from_username' field is empty, and that 'to_hostname' and 'to_hostkeys'
68have been supplied (empty 'from_hostname' and 'from_hostkeys' are valid
69and signify the initial hop from the host running ssh-agent). The agent
70will then record the constraint against the key.
71
72Subsequent operations on this key including add/remove/request
73identities and, in particular, signature requests will check the key
74constraints against the session-bind@openssh.com bindings recorded for
75the agent connection over which they were received.
76
773. SSH_AGENT_CONSTRAIN_MAXSIGN key constraint
78
79This key constraint allows communication to an agent of the maximum
80number of signatures that may be made with an XMSS key. The format of
81the constraint is:
82
83          byte                SSH_AGENT_CONSTRAIN_MAXSIGN (0x03)
84          uint32              max_signatures
85
86This option is only valid for XMSS keys.
87
883. associated-certs-v00@openssh.com key constraint extension
89
90The key constraint extension allows certificates to be associated
91with private keys as they are loaded from a PKCS#11 token.
92
93          byte                SSH_AGENT_CONSTRAIN_EXTENSION (0xff)
94          string              associated-certs-v00@openssh.com
95          bool                certs_only
96          string              certsblob
97
98Where "certsblob" consists of one or more certificates encoded as public
99key blobs:
100
101          string[]  certificates
102
103This extension is only valid for SSH_AGENTC_ADD_SMARTCARD_KEY_CONSTRAINED
104requests. When an agent receives this extension, it will attempt to match
105each certificate in the request with a corresponding private key loaded
106from the requested PKCS#11 token. When a matching key is found, the
107agent will graft the certificate contents to the token-hosted private key
108and store the result for subsequent use by regular agent operations.
109
110If the "certs_only" flag is set, then this extension will cause ONLY
111the resultant certificates to be loaded to the agent. The default
112behaviour is to load the PKCS#11-hosted private key as well as the
113resultant certificate.
114
115A SSH_AGENTC_ADD_SMARTCARD_KEY_CONSTRAINED will return SSH_AGENT_SUCCESS
116if any key (plain private or certificate) was successfully loaded, or
117SSH_AGENT_FAILURE if no key was loaded.
118
119$OpenBSD: PROTOCOL.agent,v 1.24 2024/11/27 13:27:34 djm Exp $
120