summaryrefslogtreecommitdiff
path: root/PROTOCOL.agent
diff options
context:
space:
mode:
Diffstat (limited to 'PROTOCOL.agent')
-rw-r--r--PROTOCOL.agent585
1 files changed, 4 insertions, 581 deletions
diff --git a/PROTOCOL.agent b/PROTOCOL.agent
index 60d36f912..da3381942 100644
--- a/PROTOCOL.agent
+++ b/PROTOCOL.agent
@@ -1,582 +1,5 @@
1This describes the protocol used by OpenSSH's ssh-agent. 1This file used to contain a description of the SSH agent protocol
2implemented by OpenSSH. It has since been superseded by an Internet-
3draft that is available from:
2 4
3OpenSSH's agent supports managing keys for the standard SSH protocol 5https://tools.ietf.org/html/draft-miller-ssh-agent-02
42 as well as the legacy SSH protocol 1. Support for these key types
5is almost completely disjoint - in all but a few cases, operations on
6protocol 2 keys cannot see or affect protocol 1 keys and vice-versa.
7
8Protocol 1 and protocol 2 keys are separated because of the differing
9cryptographic usage: protocol 1 private RSA keys are used to decrypt
10challenges that were encrypted with the corresponding public key,
11whereas protocol 2 RSA private keys are used to sign challenges with
12a private key for verification with the corresponding public key. It
13is considered unsound practice to use the same key for signing and
14encryption.
15
16With a couple of exceptions, the protocol message names used in this
17document indicate which type of key the message relates to. SSH_*
18messages refer to protocol 1 keys only. SSH2_* messages refer to
19protocol 2 keys. Furthermore, the names also indicate whether the
20message is a request to the agent (*_AGENTC_*) or a reply from the
21agent (*_AGENT_*). Section 3 below contains the mapping of the
22protocol message names to their integer values.
23
241. Data types
25
26Because of support for legacy SSH protocol 1 keys, OpenSSH's agent
27protocol makes use of some data types not defined in RFC 4251.
28
291.1 uint16
30
31The "uint16" data type is a simple MSB-first 16 bit unsigned integer
32encoded in two bytes.
33
341.2 mpint1
35
36The "mpint1" type represents an arbitrary precision integer (bignum).
37Its 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
43eight bits per byte in big-endian (MSB first) format.
44
45Note the difference between the "mpint1" encoding and the "mpint"
46encoding defined in RFC 4251. Also note that the length of the encoded
47integer is specified in bits, not bytes and that the byte length of
48the integer must be calculated by rounding up the number of bits to the
49nearest eight.
50
512. Protocol Messages
52
53All protocol messages are prefixed with their length in bytes, encoded
54as a 32 bit unsigned integer. Specifically:
55
56 uint32 message_length
57 byte[message_length] message
58
59The following message descriptions refer only to the content the
60"message" field.
61
622.1 Generic server responses
63
64The following generic messages may be sent by the server in response to
65requests from the client. On success the agent may reply either with:
66
67 byte SSH_AGENT_SUCCESS
68
69or a request-specific success message.
70
71On failure, the agent may reply with:
72
73 byte SSH_AGENT_FAILURE
74
75SSH_AGENT_FAILURE messages are also sent in reply to unknown request
76types.
77
782.2 Adding keys to the agent
79
80Keys are added to the agent using the SSH_AGENTC_ADD_RSA_IDENTITY and
81SSH2_AGENTC_ADD_IDENTITY requests for protocol 1 and protocol 2 keys
82respectively.
83
84Two variants of these requests are SSH_AGENTC_ADD_RSA_ID_CONSTRAINED
85and SSH2_AGENTC_ADD_ID_CONSTRAINED - these add keys with optional
86"constraints" on their usage.
87
88OpenSSH may be built with support for keys hosted on a smartcard
89or other hardware security module. These keys may be added
90to the agent using the SSH_AGENTC_ADD_SMARTCARD_KEY and
91SSH_AGENTC_ADD_SMARTCARD_KEY_CONSTRAINED requests.
92
932.2.1 Key constraints
94
95The OpenSSH agent supports some basic optional constraints on key usage.
96At present there are two constraints defined.
97
98The first constraint limits the validity duration of a key. It is
99encoded as:
100
101 byte SSH_AGENT_CONSTRAIN_LIFETIME
102 uint32 seconds
103
104Where "seconds" contains the number of seconds that the key shall remain
105valid measured from the moment that the agent receives it. After the
106validity period has expired, OpenSSH's agent will erase these keys from
107memory.
108
109The second constraint requires the agent to seek explicit user
110confirmation before performing private key operations with the loaded
111key. This constraint is encoded as:
112
113 byte SSH_AGENT_CONSTRAIN_CONFIRM
114
115Zero or more constraints may be specified when adding a key with one
116of the *_CONSTRAINED requests. Multiple constraints are appended
117consecutively 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
127Such a sequence of zero or more constraints will be referred to below
128as "constraint[]". Agents may determine whether there are constraints
129by checking whether additional data exists in the "add key" request
130after the key data itself. OpenSSH will refuse to add a key if it
131contains unknown constraints.
132
1332.2.2 Add protocol 1 key
134
135A client may add a protocol 1 key to an agent with the following
136request:
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
150Note that there is some redundancy in the key parameters; a key could be
151fully specified using just rsa_q, rsa_p and rsa_e at the cost of extra
152computation.
153
154"key_constraints" may only be present if the request type is
155SSH_AGENTC_ADD_RSA_ID_CONSTRAINED.
156
157The agent will reply with a SSH_AGENT_SUCCESS if the key has been
158successfully added or a SSH_AGENT_FAILURE if an error occurred.
159
1602.2.3 Add protocol 2 key
161
162The OpenSSH agent supports DSA, ECDSA and RSA keys for protocol 2. DSA
163keys may 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
176DSA certificates may be added with:
177 byte SSH2_AGENTC_ADD_IDENTITY or
178 SSH2_AGENTC_ADD_ID_CONSTRAINED
179 string "ssh-dss-cert-v00@openssh.com"
180 string certificate
181 mpint dsa_private_key
182 string key_comment
183 constraint[] key_constraints
184
185ECDSA keys may be added using the following request
186
187 byte SSH2_AGENTC_ADD_IDENTITY or
188 SSH2_AGENTC_ADD_ID_CONSTRAINED
189 string "ecdsa-sha2-nistp256" |
190 "ecdsa-sha2-nistp384" |
191 "ecdsa-sha2-nistp521"
192 string ecdsa_curve_name
193 string ecdsa_public_key
194 mpint ecdsa_private
195 string key_comment
196 constraint[] key_constraints
197
198ECDSA certificates may be added with:
199 byte SSH2_AGENTC_ADD_IDENTITY or
200 SSH2_AGENTC_ADD_ID_CONSTRAINED
201 string "ecdsa-sha2-nistp256-cert-v01@openssh.com" |
202 "ecdsa-sha2-nistp384-cert-v01@openssh.com" |
203 "ecdsa-sha2-nistp521-cert-v01@openssh.com"
204 string certificate
205 mpint ecdsa_private_key
206 string key_comment
207 constraint[] key_constraints
208
209ED25519 keys may be added using the following request
210 byte SSH2_AGENTC_ADD_IDENTITY or
211 SSH2_AGENTC_ADD_ID_CONSTRAINED
212 string "ssh-ed25519"
213 string ed25519_public_key
214 string ed25519_private_key || ed25519_public_key
215 string key_comment
216 constraint[] key_constraints
217
218ED25519 certificates may be added with:
219 byte SSH2_AGENTC_ADD_IDENTITY or
220 SSH2_AGENTC_ADD_ID_CONSTRAINED
221 string "ssh-ed25519-cert-v01@openssh.com"
222 string certificate
223 string ed25519_public_key
224 string ed25519_private_key || ed25519_public_key
225 string key_comment
226 constraint[] key_constraints
227
228For both ssh-ed25519 and ssh-ed25519-cert-v01@openssh.com keys, the private
229key has the public key appended (for historical reasons).
230
231RSA keys may be added with this request:
232
233 byte SSH2_AGENTC_ADD_IDENTITY or
234 SSH2_AGENTC_ADD_ID_CONSTRAINED
235 string "ssh-rsa"
236 mpint rsa_n
237 mpint rsa_e
238 mpint rsa_d
239 mpint rsa_iqmp
240 mpint rsa_p
241 mpint rsa_q
242 string key_comment
243 constraint[] key_constraints
244
245RSA certificates may be added with this request:
246
247 byte SSH2_AGENTC_ADD_IDENTITY or
248 SSH2_AGENTC_ADD_ID_CONSTRAINED
249 string "ssh-rsa-cert-v00@openssh.com"
250 string certificate
251 mpint rsa_d
252 mpint rsa_iqmp
253 mpint rsa_p
254 mpint rsa_q
255 string key_comment
256 constraint[] key_constraints
257
258Note that the 'rsa_p' and 'rsa_q' parameters are sent in the reverse
259order to the protocol 1 add keys message. As with the corresponding
260protocol 1 "add key" request, the private key is overspecified to avoid
261redundant processing.
262
263For DSA, ECDSA and RSA key add requests, "key_constraints" may only be
264present if the request type is SSH2_AGENTC_ADD_ID_CONSTRAINED.
265
266The agent will reply with a SSH_AGENT_SUCCESS if the key has been
267successfully added or a SSH_AGENT_FAILURE if an error occurred.
268
2692.2.4 Loading keys from a smartcard
270
271The OpenSSH agent may have optional smartcard support built in to it. If
272so, it supports an operation to load keys from a smartcard. Technically,
273only the public components of the keys are loaded into the agent so
274this operation really arranges for future private key operations to be
275delegated to the smartcard.
276
277 byte SSH_AGENTC_ADD_SMARTCARD_KEY or
278 SSH_AGENTC_ADD_SMARTCARD_KEY_CONSTRAINED
279 string reader_id
280 string pin
281 constraint[] key_constraints
282
283"reader_id" is an identifier to a smartcard reader and "pin"
284is a PIN or passphrase used to unlock the private key(s) on the
285device. "key_constraints" may only be present if the request type is
286SSH_AGENTC_ADD_SMARTCARD_KEY_CONSTRAINED.
287
288This operation may load all SSH keys that are unlocked using the
289"pin" on the specified reader. The type of key loaded (protocol 1
290or protocol 2) will be specified by the smartcard itself, it is not
291client-specified.
292
293The agent will reply with a SSH_AGENT_SUCCESS if one or more keys have
294been successfully loaded or a SSH_AGENT_FAILURE if an error occurred.
295The agent will also return SSH_AGENT_FAILURE if it does not support
296smartcards.
297
2982.3 Removing multiple keys
299
300A client may request that an agent delete all protocol 1 keys using the
301following request:
302
303 byte SSH_AGENTC_REMOVE_ALL_RSA_IDENTITIES
304
305This message requests the deletion of all protocol 2 keys:
306
307 byte SSH2_AGENTC_REMOVE_ALL_IDENTITIES
308
309On success, the agent will delete all keys of the requested type and
310reply with a SSH_AGENT_SUCCESS message. If an error occurred, the agent
311will reply with SSH_AGENT_FAILURE.
312
313Note that, to delete all keys (both protocol 1 and 2), a client
314must send both a SSH_AGENTC_REMOVE_ALL_RSA_IDENTITIES and a
315SSH2_AGENTC_REMOVE_ALL_IDENTITIES request.
316
3172.4 Removing specific keys
318
3192.4.1 Removing a protocol 1 key
320
321Removal of a protocol 1 key may be requested with the following message:
322
323 byte SSH_AGENTC_REMOVE_RSA_IDENTITY
324 uint32 key_bits
325 mpint1 rsa_e
326 mpint1 rsa_n
327
328Note that key_bits is strictly redundant, as it may be inferred by the
329length of rsa_n.
330
331The agent will delete any private key matching the specified public key
332and return SSH_AGENT_SUCCESS. If no such key was found, the agent will
333return SSH_AGENT_FAILURE.
334
3352.4.2 Removing a protocol 2 key
336
337Protocol 2 keys may be removed with the following request:
338
339 byte SSH2_AGENTC_REMOVE_IDENTITY
340 string key_blob
341
342Where "key_blob" is encoded as per RFC 4253 section 6.6 "Public Key
343Algorithms" for any of the supported protocol 2 key types.
344
345The agent will delete any private key matching the specified public key
346and return SSH_AGENT_SUCCESS. If no such key was found, the agent will
347return SSH_AGENT_FAILURE.
348
3492.4.3 Removing keys loaded from a smartcard
350
351A client may request that a server remove one or more smartcard-hosted
352keys using this message:
353
354 byte SSH_AGENTC_REMOVE_SMARTCARD_KEY
355 string reader_id
356 string pin
357
358"reader_id" the an identifier to a smartcard reader and "pin" is a PIN
359or passphrase used to unlock the private key(s) on the device.
360
361When this message is received, and if the agent supports
362smartcard-hosted keys, it will delete all keys that are hosted on the
363specified smartcard that may be accessed with the given "pin".
364
365The agent will reply with a SSH_AGENT_SUCCESS if one or more keys have
366been successfully removed or a SSH_AGENT_FAILURE if an error occurred.
367The agent will also return SSH_AGENT_FAILURE if it does not support
368smartcards.
369
3702.5 Requesting a list of known keys
371
372An agent may be requested to list which keys it holds. Different
373requests exist for protocol 1 and protocol 2 keys.
374
3752.5.1 Requesting a list of protocol 1 keys
376
377To request a list of protocol 1 keys that are held in the agent, a
378client may send the following message:
379
380 byte SSH_AGENTC_REQUEST_RSA_IDENTITIES
381
382The agent will reply with the following message:
383
384 byte SSH_AGENT_RSA_IDENTITIES_ANSWER
385 uint32 num_keys
386
387Followed by zero or more consecutive keys, encoded as:
388
389 uint32 bits
390 mpint1 rsa_e
391 mpint1 rsa_n
392 string key_comment
393
3942.5.2 Requesting a list of protocol 2 keys
395
396A client may send the following message to request a list of
397protocol 2 keys that are stored in the agent:
398
399 byte SSH2_AGENTC_REQUEST_IDENTITIES
400
401The agent will reply with the following message header:
402
403 byte SSH2_AGENT_IDENTITIES_ANSWER
404 uint32 num_keys
405
406Followed by zero or more consecutive keys, encoded as:
407
408 string key_blob
409 string key_comment
410
411Where "key_blob" is encoded as per RFC 4253 section 6.6 "Public Key
412Algorithms" for any of the supported protocol 2 key types.
413
4142.6 Private key operations
415
416The purpose of the agent is to perform private key operations, such as
417signing and encryption without requiring a passphrase to unlock the
418key and without allowing the private key itself to be exposed. There
419are separate requests for the protocol 1 and protocol 2 private key
420operations.
421
4222.6.1 Protocol 1 private key challenge
423
424The private key operation used in version 1 of the SSH protocol is
425decrypting a challenge that has been encrypted with a public key.
426It may be requested using this message:
427
428 byte SSH_AGENTC_RSA_CHALLENGE
429 uint32 ignored
430 mpint1 rsa_e
431 mpint1 rsa_n
432 mpint1 encrypted_challenge
433 byte[16] session_id
434 uint32 response_type /* must be 1 */
435
436"rsa_e" and "rsa_n" are used to identify which private key to use.
437"encrypted_challenge" is a challenge blob that has (presumably)
438been encrypted with the public key and must be in the range
4391 <= encrypted_challenge < 2^256. "session_id" is the SSH protocol 1
440session ID (computed from the server host key, the server semi-ephemeral
441key and the session cookie).
442
443"ignored" and "response_type" exist for compatibility with legacy
444implementations. "response_type" must be equal to 1; other response
445types are not supported.
446
447On receiving this request, the server decrypts the "encrypted_challenge"
448using the private key matching the supplied (rsa_e, rsa_n) values. For
449the response derivation, the decrypted challenge is represented as an
450unsigned, big-endian integer encoded in a 32 byte buffer (i.e. values
451smaller than 2^248 will have leading 0 bytes).
452
453The response value is then calculated as:
454
455 response = MD5(decrypted_challenge || session_id)
456
457and returned in the following message
458
459 byte SSH_AGENT_RSA_RESPONSE
460 byte[16] response
461
462If the agent cannot find the key specified by the supplied (rsa_e,
463rsa_n) then it will return SSH_AGENT_FAILURE.
464
4652.6.2 Protocol 2 private key signature request
466
467A client may use the following message to request signing of data using
468a protocol 2 key:
469
470 byte SSH2_AGENTC_SIGN_REQUEST
471 string key_blob
472 string data
473 uint32 flags
474
475Where "key_blob" is encoded as per RFC 4253 section 6.6 "Public Key
476Algorithms" for any of the supported protocol 2 key types. "flags" is
477a bit-mask, but at present only one possible value is defined (see below
478for its meaning):
479
480 SSH_AGENT_OLD_SIGNATURE 1
481
482Upon receiving this request, the agent will look up the private key that
483corresponds to the public key contained in key_blob. It will use this
484private key to sign the "data" and produce a signature blob using the
485key type-specific method described in RFC 4253 section 6.6 "Public Key
486Algorithms".
487
488An exception to this is for "ssh-dss" keys where the "flags" word
489contains the value SSH_AGENT_OLD_SIGNATURE. In this case, a legacy
490signature encoding is used in lieu of the standard one. In this case,
491the DSA signature blob is encoded as:
492
493 byte[40] signature
494
495The signature will be returned in the response message:
496
497 byte SSH2_AGENT_SIGN_RESPONSE
498 string signature_blob
499
500If the agent cannot find the key specified by the supplied key_blob then
501it will return SSH_AGENT_FAILURE.
502
5032.7 Locking or unlocking an agent
504
505The agent supports temporary locking with a passphrase to suspend
506processing of sensitive operations until it has been unlocked with the
507same passphrase. To lock an agent, a client send the following request:
508
509 byte SSH_AGENTC_LOCK
510 string passphrase
511
512Upon receipt of this message and if the agent is not already locked,
513it will suspend processing requests and return a SSH_AGENT_SUCCESS
514reply. If the agent is already locked, it will return SSH_AGENT_FAILURE.
515
516While locked, the agent will refuse all requests except
517SSH_AGENTC_UNLOCK, SSH_AGENTC_REQUEST_RSA_IDENTITIES and
518SSH2_AGENTC_REQUEST_IDENTITIES. The "request identities" requests are
519treated specially by a locked agent: it will always return an empty list
520of keys.
521
522To unlock an agent, a client may request:
523
524 byte SSH_AGENTC_UNLOCK
525 string passphrase
526
527If the passphrase matches and the agent is locked, then it will resume
528processing all requests and return SSH_AGENT_SUCCESS. If the agent
529is not locked or the passphrase does not match then it will return
530SSH_AGENT_FAILURE.
531
532Locking and unlocking affects both protocol 1 and protocol 2 keys.
533
5343. Protocol message numbers
535
5363.1 Requests from client to agent for protocol 1 key operations
537
538 SSH_AGENTC_REQUEST_RSA_IDENTITIES 1
539 SSH_AGENTC_RSA_CHALLENGE 3
540 SSH_AGENTC_ADD_RSA_IDENTITY 7
541 SSH_AGENTC_REMOVE_RSA_IDENTITY 8
542 SSH_AGENTC_REMOVE_ALL_RSA_IDENTITIES 9
543 SSH_AGENTC_ADD_RSA_ID_CONSTRAINED 24
544
5453.2 Requests from client to agent for protocol 2 key operations
546
547 SSH2_AGENTC_REQUEST_IDENTITIES 11
548 SSH2_AGENTC_SIGN_REQUEST 13
549 SSH2_AGENTC_ADD_IDENTITY 17
550 SSH2_AGENTC_REMOVE_IDENTITY 18
551 SSH2_AGENTC_REMOVE_ALL_IDENTITIES 19
552 SSH2_AGENTC_ADD_ID_CONSTRAINED 25
553
5543.3 Key-type independent requests from client to agent
555
556 SSH_AGENTC_ADD_SMARTCARD_KEY 20
557 SSH_AGENTC_REMOVE_SMARTCARD_KEY 21
558 SSH_AGENTC_LOCK 22
559 SSH_AGENTC_UNLOCK 23
560 SSH_AGENTC_ADD_SMARTCARD_KEY_CONSTRAINED 26
561
5623.4 Generic replies from agent to client
563
564 SSH_AGENT_FAILURE 5
565 SSH_AGENT_SUCCESS 6
566
5673.5 Replies from agent to client for protocol 1 key operations
568
569 SSH_AGENT_RSA_IDENTITIES_ANSWER 2
570 SSH_AGENT_RSA_RESPONSE 4
571
5723.6 Replies from agent to client for protocol 2 key operations
573
574 SSH2_AGENT_IDENTITIES_ANSWER 12
575 SSH2_AGENT_SIGN_RESPONSE 14
576
5773.7 Key constraint identifiers
578
579 SSH_AGENT_CONSTRAIN_LIFETIME 1
580 SSH_AGENT_CONSTRAIN_CONFIRM 2
581
582$OpenBSD: PROTOCOL.agent,v 1.11 2016/05/19 07:45:32 djm Exp $
generated by cgit v1.2.3 (git 2.39.1) at 2024-10-31 00:11:53 +0000