diff options
author | Colin Watson <cjwatson@debian.org> | 2008-07-22 19:45:18 +0000 |
---|---|---|
committer | Colin Watson <cjwatson@debian.org> | 2008-07-22 19:45:18 +0000 |
commit | 137d76ba65883aa8143af1fcad83b57e7badef0c (patch) | |
tree | f426e804bb5248ceafedfab7bb78ae6e6752942c /PROTOCOL.agent | |
parent | dac7d049dad31f5f84d421d4eb628a7e13f977d7 (diff) | |
parent | ef94e5613d37bcbf880f21ee6094e4b1c7683a4c (diff) |
* New upstream release (closes: #474301). Important changes not previously
backported to 4.7p1:
- 4.9/4.9p1 (http://www.openssh.com/txt/release-4.9):
+ Added chroot(2) support for sshd(8), controlled by a new option
"ChrootDirectory" (closes: #139047, LP: #24777).
+ Linked sftp-server(8) into sshd(8). The internal sftp server is used
when the command "internal-sftp" is specified in a Subsystem or
ForceCommand declaration. When used with ChrootDirectory, the
internal sftp server requires no special configuration of files
inside the chroot environment.
+ Added a protocol extension method "posix-rename@openssh.com" for
sftp-server(8) to perform POSIX atomic rename() operations; sftp(1)
prefers this if available (closes: #308561).
+ Removed the fixed limit of 100 file handles in sftp-server(8).
+ ssh(8) will now skip generation of SSH protocol 1 ephemeral server
keys when in inetd mode and protocol 2 connections are negotiated.
This speeds up protocol 2 connections to inetd-mode servers that
also allow Protocol 1.
+ Accept the PermitRootLogin directive in a sshd_config(5) Match
block. Allows for, e.g. permitting root only from the local network.
+ Reworked sftp(1) argument splitting and escaping to be more
internally consistent (i.e. between sftp commands) and more
consistent with sh(1). Please note that this will change the
interpretation of some quoted strings, especially those with
embedded backslash escape sequences.
+ Support "Banner=none" in sshd_config(5) to disable sending of a
pre-login banner (e.g. in a Match block).
+ ssh(1) ProxyCommands are now executed with $SHELL rather than
/bin/sh.
+ ssh(1)'s ConnectTimeout option is now applied to both the TCP
connection and the SSH banner exchange (previously it just covered
the TCP connection). This allows callers of ssh(1) to better detect
and deal with stuck servers that accept a TCP connection but don't
progress the protocol, and also makes ConnectTimeout useful for
connections via a ProxyCommand.
+ scp(1) incorrectly reported "stalled" on slow copies (closes:
#140828).
+ scp(1) date underflow for timestamps before epoch.
+ ssh(1) used the obsolete SIG DNS RRtype for host keys in DNS,
instead of the current standard RRSIG.
+ Correctly drain ACKs when a sftp(1) upload write fails midway,
avoids a fatal() exit from what should be a recoverable condition.
+ Fixed ssh-keygen(1) selective host key hashing (i.e. "ssh-keygen -HF
hostname") to not include any IP address in the data to be hashed.
+ Make ssh(1) skip listening on the IPv6 wildcard address when a
binding address of 0.0.0.0 is used against an old SSH server that
does not support the RFC4254 syntax for wildcard bind addresses.
+ Enable IPV6_V6ONLY socket option on sshd(8) listen socket, as is
already done for X11/TCP forwarding sockets (closes: #439661).
+ Fix FD leak that could hang a ssh(1) connection multiplexing master.
+ Make ssh(1) -q option documentation consistent with reality.
+ Fixed sshd(8) PAM support not calling pam_session_close(), or
failing to call it with root privileges (closes: #372680).
+ Fix activation of OpenSSL engine support when requested in configure
(LP: #119295).
- 5.1/5.1p1 (http://www.openssh.com/txt/release-5.1):
+ Introduce experimental SSH Fingerprint ASCII Visualisation to ssh(1)
and ssh-keygen(1). Visual fingerprint display is controlled by a new
ssh_config(5) option "VisualHostKey". The intent is to render SSH
host keys in a visual form that is amenable to easy recall and
rejection of changed host keys.
+ sshd_config(5) now supports CIDR address/masklen matching in "Match
address" blocks, with a fallback to classic wildcard matching.
+ sshd(8) now supports CIDR matching in ~/.ssh/authorized_keys
from="..." restrictions, also with a fallback to classic wildcard
matching.
+ Added an extended test mode (-T) to sshd(8) to request that it write
its effective configuration to stdout and exit. Extended test mode
also supports the specification of connection parameters (username,
source address and hostname) to test the application of
sshd_config(5) Match rules.
+ ssh(1) now prints the number of bytes transferred and the overall
connection throughput for SSH protocol 2 sessions when in verbose
mode (previously these statistics were displayed for protocol 1
connections only).
+ sftp-server(8) now supports extension methods statvfs@openssh.com
and fstatvfs@openssh.com that implement statvfs(2)-like operations.
+ sftp(1) now has a "df" command to the sftp client that uses the
statvfs@openssh.com to produce a df(1)-like display of filesystem
space and inode utilisation (requires statvfs@openssh.com support on
the server).
+ Added a MaxSessions option to sshd_config(5) to allow control of the
number of multiplexed sessions supported over a single TCP
connection. This allows increasing the number of allowed sessions
above the previous default of 10, disabling connection multiplexing
(MaxSessions=1) or disallowing login/shell/subsystem sessions
entirely (MaxSessions=0).
+ Added a no-more-sessions@openssh.com global request extension that
is sent from ssh(1) to sshd(8) when the client knows that it will
never request another session (i.e. when session multiplexing is
disabled). This allows a server to disallow further session requests
and terminate the session in cases where the client has been
hijacked.
+ ssh-keygen(1) now supports the use of the -l option in combination
with -F to search for a host in ~/.ssh/known_hosts and display its
fingerprint.
+ ssh-keyscan(1) now defaults to "rsa" (protocol 2) keys, instead of
"rsa1".
+ Added an AllowAgentForwarding option to sshd_config(8) to control
whether authentication agent forwarding is permitted. Note that this
is a loose control, as a client may install their own unofficial
forwarder.
+ ssh(1) and sshd(8): avoid unnecessary malloc/copy/free when
receiving network data, resulting in a ~10% speedup.
+ ssh(1) and sshd(8) will now try additional addresses when connecting
to a port forward destination whose DNS name resolves to more than
one address. The previous behaviour was to try the only first
address and give up if that failed.
+ ssh(1) and sshd(8) now support signalling that channels are
half-closed for writing, through a channel protocol extension
notification "eow@openssh.com". This allows propagation of closed
file descriptors, so that commands such as "ssh -2 localhost od
/bin/ls | true" do not send unnecessary data over the wire.
+ sshd(8): increased the default size of ssh protocol 1 ephemeral keys
from 768 to 1024 bits.
+ When ssh(1) has been requested to fork after authentication ("ssh
-f") with ExitOnForwardFailure enabled, delay the fork until after
replies for any -R forwards have been seen. Allows for robust
detection of -R forward failure when using -f.
+ "Match group" blocks in sshd_config(5) now support negation of
groups. E.g. "Match group staff,!guests".
+ sftp(1) and sftp-server(8) now allow chmod-like operations to set
set[ug]id/sticky bits.
+ The MaxAuthTries option is now permitted in sshd_config(5) match
blocks.
+ Multiplexed ssh(1) sessions now support a subset of the ~ escapes
that are available to a primary connection.
+ ssh(1) connection multiplexing will now fall back to creating a new
connection in most error cases (closes: #352830).
+ Make ssh(1) deal more gracefully with channel requests that fail.
Previously it would optimistically assume that requests would always
succeed, which could cause hangs if they did not (e.g. when the
server runs out of file descriptors).
+ ssh(1) now reports multiplexing errors via the multiplex slave's
stderr where possible (subject to LogLevel in the mux master).
+ Prevent sshd(8) from erroneously applying public key restrictions
leaned from ~/.ssh/authorized_keys to other authentication methods
when public key authentication subsequently fails (LP: #161047).
+ Fixed an UMAC alignment problem that manifested on Itanium
platforms.
Diffstat (limited to 'PROTOCOL.agent')
-rw-r--r-- | PROTOCOL.agent | 516 |
1 files changed, 516 insertions, 0 deletions
diff --git a/PROTOCOL.agent b/PROTOCOL.agent new file mode 100644 index 000000000..49adbdd5c --- /dev/null +++ b/PROTOCOL.agent | |||
@@ -0,0 +1,516 @@ | |||
1 | This describes the protocol used by OpenSSH's ssh-agent. | ||
2 | |||
3 | OpenSSH's agent supports managing keys for the standard SSH protocol | ||
4 | 2 as well as the legacy SSH protocol 1. Support for these key types | ||
5 | is almost completely disjoint - in all but a few cases, operations on | ||
6 | protocol 2 keys cannot see or affect protocol 1 keys and vice-versa. | ||
7 | |||
8 | Protocol 1 and protocol 2 keys are separated because of the differing | ||
9 | cryptographic usage: protocol 1 private RSA keys are used to decrypt | ||
10 | challenges that were encrypted with the corresponding public key, | ||
11 | whereas protocol 2 RSA private keys are used to sign challenges with | ||
12 | a private key for verification with the corresponding public key. It | ||
13 | is considered unsound practice to use the same key for signing and | ||
14 | encryption. | ||
15 | |||
16 | With a couple of exceptions, the protocol message names used in this | ||
17 | document indicate which type of key the message relates to. SSH_* | ||
18 | messages refer to protocol 1 keys only. SSH2_* messages refer to | ||
19 | protocol 2 keys. Furthermore, the names also indicate whether the | ||
20 | message is a request to the agent (*_AGENTC_*) or a reply from the | ||
21 | agent (*_AGENT_*). Section 3 below contains the mapping of the | ||
22 | protocol message names to their integer values. | ||
23 | |||
24 | 1. Data types | ||
25 | |||
26 | Because of support for legacy SSH protocol 1 keys, OpenSSH's agent | ||
27 | protocol makes use of some data types not defined in RFC 4251. | ||
28 | |||
29 | 1.1 uint16 | ||
30 | |||
31 | The "uint16" data type is a simple MSB-first 16 bit unsigned integer | ||
32 | encoded in two bytes. | ||
33 | |||
34 | 1.2 mpint1 | ||
35 | |||
36 | The "mpint1" type represents an arbitrary precision integer (bignum). | ||
37 | Its format is as follows: | ||
38 | |||
39 | uint16 bits | ||
40 | byte[(bits + 7) / 8] bignum | ||
41 | |||
42 | "bignum" contains an unsigned arbitrary precision integer encoded as | ||
43 | eight bits per byte in big-endian (MSB first) format. | ||
44 | |||
45 | Note the difference between the "mpint1" encoding and the "mpint" | ||
46 | encoding defined in RFC 4251. Also note that the length of the encoded | ||
47 | integer is specified in bits, not bytes and that the byte length of | ||
48 | the integer must be calculated by rounding up the number of bits to the | ||
49 | nearest eight. | ||
50 | |||
51 | 2. Protocol Messages | ||
52 | |||
53 | All protocol messages are prefixed with their length in bytes, encoded | ||
54 | as a 32 bit unsigned integer. Specifically: | ||
55 | |||
56 | uint32 message_length | ||
57 | byte[message_length] message | ||
58 | |||
59 | The following message descriptions refer only to the content the | ||
60 | "message" field. | ||
61 | |||
62 | 2.1 Generic server responses | ||
63 | |||
64 | The following generic messages may be sent by the server in response to | ||
65 | requests from the client. On success the agent may reply either with: | ||
66 | |||
67 | byte SSH_AGENT_SUCCESS | ||
68 | |||
69 | or a request-specific success message. | ||
70 | |||
71 | On failure, the agent may reply with: | ||
72 | |||
73 | byte SSH_AGENT_FAILURE | ||
74 | |||
75 | SSH_AGENT_FAILURE messages are also sent in reply to unknown request | ||
76 | types. | ||
77 | |||
78 | 2.2 Adding keys to the agent | ||
79 | |||
80 | Keys are added to the agent using the SSH_AGENTC_ADD_RSA_IDENTITY and | ||
81 | SSH2_AGENTC_ADD_IDENTITY requests for protocol 1 and protocol 2 keys | ||
82 | respectively. | ||
83 | |||
84 | Two variants of these requests are SSH_AGENTC_ADD_RSA_ID_CONSTRAINED | ||
85 | and SSH2_AGENTC_ADD_ID_CONSTRAINED - these add keys with optional | ||
86 | "constraints" on their usage. | ||
87 | |||
88 | OpenSSH may be built with support for keys hosted on a smartcard | ||
89 | or other hardware security module. These keys may be added | ||
90 | to the agent using the SSH_AGENTC_ADD_SMARTCARD_KEY and | ||
91 | SSH_AGENTC_ADD_SMARTCARD_KEY_CONSTRAINED requests. | ||
92 | |||
93 | 2.2.1 Key constraints | ||
94 | |||
95 | The OpenSSH agent supports some basic optional constraints on key usage. | ||
96 | At present there are two constraints defined. | ||
97 | |||
98 | The first constraint limits the validity duration of a key. It is | ||
99 | encoded as: | ||
100 | |||
101 | byte SSH_AGENT_CONSTRAIN_LIFETIME | ||
102 | uint32 seconds | ||
103 | |||
104 | Where "seconds" contains the number of seconds that the key shall remain | ||
105 | valid measured from the moment that the agent receives it. After the | ||
106 | validity period has expired, OpenSSH's agent will erase these keys from | ||
107 | memory. | ||
108 | |||
109 | The second constraint requires the agent to seek explicit user | ||
110 | confirmation before performing private key operations with the loaded | ||
111 | key. This constraint is encoded as: | ||
112 | |||
113 | byte SSH_AGENT_CONSTRAIN_CONFIRM | ||
114 | |||
115 | Zero or more constraints may be specified when adding a key with one | ||
116 | of the *_CONSTRAINED requests. Multiple constraints are appended | ||
117 | consecutively to the end of the request: | ||
118 | |||
119 | byte constraint1_type | ||
120 | .... constraint1_data | ||
121 | byte constraint2_type | ||
122 | .... constraint2_data | ||
123 | .... | ||
124 | byte constraintN_type | ||
125 | .... constraintN_data | ||
126 | |||
127 | Such a sequence of zero or more constraints will be referred to below | ||
128 | as "constraint[]". Agents may determine whether there are constraints | ||
129 | by checking whether additional data exists in the "add key" request | ||
130 | after the key data itself. OpenSSH will refuse to add a key if it | ||
131 | contains unknown constraints. | ||
132 | |||
133 | 2.2.2 Add protocol 1 key | ||
134 | |||
135 | A client may add a protocol 1 key to an agent with the following | ||
136 | request: | ||
137 | |||
138 | byte SSH_AGENTC_ADD_RSA_IDENTITY or | ||
139 | SSH_AGENTC_ADD_RSA_ID_CONSTRAINED | ||
140 | uint32 ignored | ||
141 | mpint1 rsa_n | ||
142 | mpint1 rsa_e | ||
143 | mpint1 rsa_d | ||
144 | mpint1 rsa_iqmp | ||
145 | mpint1 rsa_q | ||
146 | mpint1 rsa_p | ||
147 | string key_comment | ||
148 | constraint[] key_constraints | ||
149 | |||
150 | Note that there is some redundancy in the key parameters; a key could be | ||
151 | fully specified using just rsa_q, rsa_p and rsa_e at the cost of extra | ||
152 | computation. | ||
153 | |||
154 | "key_constraints" may only be present if the request type is | ||
155 | SSH_AGENTC_ADD_RSA_IDENTITY. | ||
156 | |||
157 | The agent will reply with a SSH_AGENT_SUCCESS if the key has been | ||
158 | successfully added or a SSH_AGENT_FAILURE if an error occurred. | ||
159 | |||
160 | 2.2.3 Add protocol 2 key | ||
161 | |||
162 | The OpenSSH agent supports DSA and RSA keys for protocol 2. DSA keys may | ||
163 | be added using the following request | ||
164 | |||
165 | byte SSH2_AGENTC_ADD_IDENTITY or | ||
166 | SSH2_AGENTC_ADD_ID_CONSTRAINED | ||
167 | string "ssh-dss" | ||
168 | mpint dsa_p | ||
169 | mpint dsa_q | ||
170 | mpint dsa_g | ||
171 | mpint dsa_public_key | ||
172 | mpint dsa_private_key | ||
173 | string key_comment | ||
174 | constraint[] key_constraints | ||
175 | |||
176 | RSA keys may be added with this request: | ||
177 | |||
178 | byte SSH2_AGENTC_ADD_IDENTITY or | ||
179 | SSH2_AGENTC_ADD_ID_CONSTRAINED | ||
180 | string "ssh-rsa" | ||
181 | mpint rsa_n | ||
182 | mpint rsa_e | ||
183 | mpint rsa_d | ||
184 | mpint rsa_iqmp | ||
185 | mpint rsa_p | ||
186 | mpint rsa_q | ||
187 | string key_comment | ||
188 | constraint[] key_constraints | ||
189 | |||
190 | Note that the 'rsa_p' and 'rsa_q' parameters are sent in the reverse | ||
191 | order to the protocol 1 add keys message. As with the corresponding | ||
192 | protocol 1 "add key" request, the private key is overspecified to avoid | ||
193 | redundant processing. | ||
194 | |||
195 | For both DSA and RSA key add requests, "key_constraints" may only be | ||
196 | present if the request type is SSH2_AGENTC_ADD_ID_CONSTRAINED. | ||
197 | |||
198 | The agent will reply with a SSH_AGENT_SUCCESS if the key has been | ||
199 | successfully added or a SSH_AGENT_FAILURE if an error occurred. | ||
200 | |||
201 | 2.2.4 Loading keys from a smartcard | ||
202 | |||
203 | The OpenSSH agent may have optional smartcard support built in to it. If | ||
204 | so, it supports an operation to load keys from a smartcard. Technically, | ||
205 | only the public components of the keys are loaded into the agent so | ||
206 | this operation really arranges for future private key operations to be | ||
207 | delegated to the smartcard. | ||
208 | |||
209 | byte SSH_AGENTC_ADD_SMARTCARD_KEY or | ||
210 | SSH_AGENTC_ADD_SMARTCARD_KEY_CONSTRAINED | ||
211 | string reader_id | ||
212 | string pin | ||
213 | constraint[] key_constraints | ||
214 | |||
215 | "reader_id" is an identifier to a smartcard reader and "pin" | ||
216 | is a PIN or passphrase used to unlock the private key(s) on the | ||
217 | device. "key_constraints" may only be present if the request type is | ||
218 | SSH_AGENTC_ADD_SMARTCARD_KEY_CONSTRAINED. | ||
219 | |||
220 | This operation may load all SSH keys that are unlocked using the | ||
221 | "pin" on the specified reader. The type of key loaded (protocol 1 | ||
222 | or protocol 2) will be specified by the smartcard itself, it is not | ||
223 | client-specified. | ||
224 | |||
225 | The agent will reply with a SSH_AGENT_SUCCESS if one or more keys have | ||
226 | been successfully loaded or a SSH_AGENT_FAILURE if an error occurred. | ||
227 | The agent will also return SSH_AGENT_FAILURE if it does not support | ||
228 | smartcards. | ||
229 | |||
230 | 2.3 Removing multiple keys | ||
231 | |||
232 | A client may request that an agent delete all protocol 1 keys using the | ||
233 | following request: | ||
234 | |||
235 | byte SSH_AGENTC_REMOVE_ALL_RSA_IDENTITIES | ||
236 | |||
237 | This message requests the deletion of all protocol 2 keys: | ||
238 | |||
239 | byte SSH2_AGENTC_REMOVE_ALL_IDENTITIES | ||
240 | |||
241 | On success, the agent will delete all keys of the requested type and | ||
242 | reply with a SSH_AGENT_SUCCESS message. If an error occurred, the agent | ||
243 | will reply with SSH_AGENT_FAILURE. | ||
244 | |||
245 | Note that, to delete all keys (both protocol 1 and 2), a client | ||
246 | must send both a SSH_AGENTC_REMOVE_ALL_RSA_IDENTITIES and a | ||
247 | SSH2_AGENTC_REMOVE_ALL_IDENTITIES request. | ||
248 | |||
249 | 2.4 Removing specific keys | ||
250 | |||
251 | 2.4.1 Removing a protocol 1 key | ||
252 | |||
253 | Removal of a protocol 1 key may be requested with the following message: | ||
254 | |||
255 | byte SSH_AGENTC_REMOVE_RSA_IDENTITY | ||
256 | uint32 key_bits | ||
257 | mpint1 rsa_e | ||
258 | mpint1 rsa_n | ||
259 | |||
260 | Note that key_bits is strictly redundant, as it may be inferred by the | ||
261 | length of rsa_n. | ||
262 | |||
263 | The agent will delete any private key matching the specified public key | ||
264 | and return SSH_AGENT_SUCCESS. If no such key was found, the agent will | ||
265 | return SSH_AGENT_FAILURE. | ||
266 | |||
267 | 2.4.2 Removing a protocol 2 key | ||
268 | |||
269 | Protocol 2 keys may be removed with the following request: | ||
270 | |||
271 | byte SSH2_AGENTC_REMOVE_IDENTITY | ||
272 | string key_blob | ||
273 | |||
274 | Where "key_blob" is encoded as per RFC 4253 section 6.6 "Public Key | ||
275 | Algorithms" for either of the supported key types: "ssh-dss" or | ||
276 | "ssh-rsa". | ||
277 | |||
278 | The agent will delete any private key matching the specified public key | ||
279 | and return SSH_AGENT_SUCCESS. If no such key was found, the agent will | ||
280 | return SSH_AGENT_FAILURE. | ||
281 | |||
282 | 2.4.3 Removing keys loaded from a smartcard | ||
283 | |||
284 | A client may request that a server remove one or more smartcard-hosted | ||
285 | keys using this message: | ||
286 | |||
287 | byte SSH_AGENTC_REMOVE_SMARTCARD_KEY | ||
288 | string reader_id | ||
289 | string pin | ||
290 | |||
291 | "reader_id" the an identifier to a smartcard reader and "pin" is a PIN | ||
292 | or passphrase used to unlock the private key(s) on the device. | ||
293 | |||
294 | When this message is received, and if the agent supports | ||
295 | smartcard-hosted keys, it will delete all keys that are hosted on the | ||
296 | specified smartcard that may be accessed with the given "pin". | ||
297 | |||
298 | The agent will reply with a SSH_AGENT_SUCCESS if one or more keys have | ||
299 | been successfully removed or a SSH_AGENT_FAILURE if an error occurred. | ||
300 | The agent will also return SSH_AGENT_FAILURE if it does not support | ||
301 | smartcards. | ||
302 | |||
303 | 2.5 Requesting a list of known keys | ||
304 | |||
305 | An agent may be requested to list which keys it holds. Different | ||
306 | requests exist for protocol 1 and protocol 2 keys. | ||
307 | |||
308 | 2.5.1 Requesting a list of protocol 1 keys | ||
309 | |||
310 | To request a list of protocol 1 keys that are held in the agent, a | ||
311 | client may send the following message: | ||
312 | |||
313 | byte SSH_AGENTC_REQUEST_RSA_IDENTITIES | ||
314 | |||
315 | The agent will reply with the following message: | ||
316 | |||
317 | byte SSH_AGENT_RSA_IDENTITIES_ANSWER | ||
318 | uint32 num_keys | ||
319 | |||
320 | Followed by zero or more consecutive keys, encoded as: | ||
321 | |||
322 | uint32 bits | ||
323 | mpint1 rsa_e | ||
324 | mpint1 rsa_n | ||
325 | string key_comment | ||
326 | |||
327 | 2.5.2 Requesting a list of protocol 2 keys | ||
328 | |||
329 | A client may send the following message to request a list of | ||
330 | protocol 2 keys that are stored in the agent: | ||
331 | |||
332 | byte SSH2_AGENTC_REQUEST_IDENTITIES | ||
333 | |||
334 | The agent will reply with the following message header: | ||
335 | |||
336 | byte SSH2_AGENT_IDENTITIES_ANSWER | ||
337 | uint32 num_keys | ||
338 | |||
339 | Followed by zero or more consecutive keys, encoded as: | ||
340 | |||
341 | string key_blob | ||
342 | string key_comment | ||
343 | |||
344 | Where "key_blob" is encoded as per RFC 4253 section 6.6 "Public Key | ||
345 | Algorithms" for either of the supported key types: "ssh-dss" or | ||
346 | "ssh-rsa". | ||
347 | |||
348 | 2.6 Private key operations | ||
349 | |||
350 | The purpose of the agent is to perform private key operations, such as | ||
351 | signing and encryption without requiring a passphrase to unlock the | ||
352 | key and without allowing the private key itself to be exposed. There | ||
353 | are separate requests for the protocol 1 and protocol 2 private key | ||
354 | operations. | ||
355 | |||
356 | 2.6.1 Protocol 1 private key challenge | ||
357 | |||
358 | The private key operation used in version 1 of the SSH protocol is | ||
359 | decrypting a challenge that has been encrypted with a public key. | ||
360 | It may be requested using this message: | ||
361 | |||
362 | byte SSH_AGENTC_RSA_CHALLENGE | ||
363 | uint32 ignored | ||
364 | mpint1 rsa_e | ||
365 | mpint1 rsa_n | ||
366 | mpint1 encrypted_challenge | ||
367 | byte[16] session_id | ||
368 | uint32 response_type /* must be 1 */ | ||
369 | |||
370 | "rsa_e" and "rsa_n" are used to identify which private key to use. | ||
371 | "encrypted_challenge" is a challenge blob that has (presumably) | ||
372 | been encrypted with the public key and must be in the range | ||
373 | 1 <= encrypted_challenge < 2^256. "session_id" is the SSH protocol 1 | ||
374 | session ID (computed from the server host key, the server semi-ephemeral | ||
375 | key and the session cookie). | ||
376 | |||
377 | "ignored" and "response_type" exist for compatibility with legacy | ||
378 | implementations. "response_type" must be equal to 1; other response | ||
379 | types are not supported. | ||
380 | |||
381 | On receiving this request, the server decrypts the "encrypted_challenge" | ||
382 | using the private key matching the supplied (rsa_e, rsa_n) values. For | ||
383 | the response derivation, the decrypted challenge is represented as an | ||
384 | unsigned, big-endian integer encoded in a 32 byte buffer (i.e. values | ||
385 | smaller than 2^248 will have leading 0 bytes). | ||
386 | |||
387 | The response value is then calculated as: | ||
388 | |||
389 | response = MD5(decrypted_challenge || session_id) | ||
390 | |||
391 | and returned in the following message | ||
392 | |||
393 | byte SSH_AGENT_RSA_RESPONSE | ||
394 | byte[16] response | ||
395 | |||
396 | If the agent cannot find the key specified by the supplied (rsa_e, | ||
397 | rsa_n) then it will return SSH_AGENT_FAILURE. | ||
398 | |||
399 | 2.6.2 Protocol 2 private key signature request | ||
400 | |||
401 | A client may use the following message to request signing of data using | ||
402 | a protocol 2 key: | ||
403 | |||
404 | byte SSH2_AGENTC_SIGN_REQUEST | ||
405 | string key_blob | ||
406 | string data | ||
407 | uint32 flags | ||
408 | |||
409 | Where "key_blob" is encoded as per RFC 4253 section 6.6 "Public Key | ||
410 | Algorithms" for either of the supported key types: "ssh-dss" or | ||
411 | "ssh-rsa". "flags" is a bit-mask, but at present only one possible value | ||
412 | is defined (see below for its meaning): | ||
413 | |||
414 | SSH_AGENT_OLD_SIGNATURE 1 | ||
415 | |||
416 | Upon receiving this request, the agent will look up the private key that | ||
417 | corresponds to the public key contained in key_blob. It will use this | ||
418 | private key to sign the "data" and produce a signature blob using the | ||
419 | key type-specific method described in RFC 4253 section 6.6 "Public Key | ||
420 | Algorithms". | ||
421 | |||
422 | An exception to this is for "ssh-dss" keys where the "flags" word | ||
423 | contains the value SSH_AGENT_OLD_SIGNATURE. In this case, a legacy | ||
424 | signature encoding is used in lieu of the standard one. In this case, | ||
425 | the DSA signature blob is encoded as: | ||
426 | |||
427 | byte[40] signature | ||
428 | |||
429 | The signature will be returned in the response message: | ||
430 | |||
431 | byte SSH2_AGENT_SIGN_RESPONSE | ||
432 | string signature_blob | ||
433 | |||
434 | If the agent cannot find the key specified by the supplied key_blob then | ||
435 | it will return SSH_AGENT_FAILURE. | ||
436 | |||
437 | 2.7 Locking or unlocking an agent | ||
438 | |||
439 | The agent supports temporary locking with a passphrase to suspend | ||
440 | processing of sensitive operations until it has been unlocked with the | ||
441 | same passphrase. To lock an agent, a client send the following request: | ||
442 | |||
443 | byte SSH_AGENTC_LOCK | ||
444 | string passphrase | ||
445 | |||
446 | Upon receipt of this message and if the agent is not already locked, | ||
447 | it will suspend processing requests and return a SSH_AGENT_SUCCESS | ||
448 | reply. If the agent is already locked, it will return SSH_AGENT_FAILURE. | ||
449 | |||
450 | While locked, the agent will refuse all requests except | ||
451 | SSH_AGENTC_UNLOCK, SSH_AGENTC_REQUEST_RSA_IDENTITIES and | ||
452 | SSH2_AGENTC_REQUEST_IDENTITIES. The "request identities" requests are | ||
453 | treated specially by a locked agent: it will always return an empty list | ||
454 | of keys. | ||
455 | |||
456 | To unlock an agent, a client may request: | ||
457 | |||
458 | byte SSH_AGENTC_UNLOCK | ||
459 | string passphrase | ||
460 | |||
461 | If the passphrase matches and the agent is locked, then it will resume | ||
462 | processing all requests and return SSH_AGENT_SUCCESS. If the agent | ||
463 | is not locked or the passphrase does not match then it will return | ||
464 | SSH_AGENT_FAILURE. | ||
465 | |||
466 | Locking and unlocking affects both protocol 1 and protocol 2 keys. | ||
467 | |||
468 | 3. Protocol message numbers | ||
469 | |||
470 | 3.1 Requests from client to agent for protocol 1 key operations | ||
471 | |||
472 | SSH_AGENTC_REQUEST_RSA_IDENTITIES 1 | ||
473 | SSH_AGENTC_RSA_CHALLENGE 3 | ||
474 | SSH_AGENTC_ADD_RSA_IDENTITY 7 | ||
475 | SSH_AGENTC_REMOVE_RSA_IDENTITY 8 | ||
476 | SSH_AGENTC_REMOVE_ALL_RSA_IDENTITIES 9 | ||
477 | SSH_AGENTC_ADD_RSA_ID_CONSTRAINED 24 | ||
478 | |||
479 | 3.2 Requests from client to agent for protocol 2 key operations | ||
480 | |||
481 | SSH2_AGENTC_REQUEST_IDENTITIES 11 | ||
482 | SSH2_AGENTC_SIGN_REQUEST 13 | ||
483 | SSH2_AGENTC_ADD_IDENTITY 17 | ||
484 | SSH2_AGENTC_REMOVE_IDENTITY 18 | ||
485 | SSH2_AGENTC_REMOVE_ALL_IDENTITIES 19 | ||
486 | SSH2_AGENTC_ADD_ID_CONSTRAINED 25 | ||
487 | |||
488 | 3.3 Key-type independent requests from client to agent | ||
489 | |||
490 | SSH_AGENTC_ADD_SMARTCARD_KEY 20 | ||
491 | SSH_AGENTC_REMOVE_SMARTCARD_KEY 21 | ||
492 | SSH_AGENTC_LOCK 22 | ||
493 | SSH_AGENTC_UNLOCK 23 | ||
494 | SSH_AGENTC_ADD_SMARTCARD_KEY_CONSTRAINED 26 | ||
495 | |||
496 | 3.4 Generic replies from agent to client | ||
497 | |||
498 | SSH_AGENT_FAILURE 5 | ||
499 | SSH_AGENT_SUCCESS 6 | ||
500 | |||
501 | 3.5 Replies from agent to client for protocol 1 key operations | ||
502 | |||
503 | SSH_AGENT_RSA_IDENTITIES_ANSWER 2 | ||
504 | SSH_AGENT_RSA_RESPONSE 4 | ||
505 | |||
506 | 3.6 Replies from agent to client for protocol 2 key operations | ||
507 | |||
508 | SSH2_AGENT_IDENTITIES_ANSWER 12 | ||
509 | SSH2_AGENT_SIGN_RESPONSE 14 | ||
510 | |||
511 | 3.7 Key constraint identifiers | ||
512 | |||
513 | SSH_AGENT_CONSTRAIN_LIFETIME 1 | ||
514 | SSH_AGENT_CONSTRAIN_CONFIRM 2 | ||
515 | |||
516 | $OpenBSD: PROTOCOL.agent,v 1.4 2008/07/01 23:12:47 stevesk Exp $ | ||