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