blob: de94d037d82f064ebe29aac5a182d3973deafcde [file] [log] [blame]
Damien Miller1e18beb2008-06-30 00:07:00 +10001This describes the protocol used by OpenSSH's ssh-agent.
2
3OpenSSH's agent supports managing keys for the standard SSH protocol
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
Darren Tuckerf2e21de2008-07-02 22:35:00 +100019protocol 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.
Damien Miller1e18beb2008-06-30 00:07:00 +100023
241. Data types
25
Darren Tuckerf2e21de2008-07-02 22:35:00 +100026Because of support for legacy SSH protocol 1 keys, OpenSSH's agent
Damien Miller1e18beb2008-06-30 00:07:00 +100027protocol 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
Darren Tuckerf2e21de2008-07-02 22:35:00 +100045Note the difference between the "mpint1" encoding and the "mpint"
Damien Miller1e18beb2008-06-30 00:07:00 +100046encoding defined in RFC 4251. Also note that the length of the encoded
Darren Tuckerf2e21de2008-07-02 22:35:00 +100047integer is specified in bits, not bytes and that the byte length of
Damien Miller1e18beb2008-06-30 00:07:00 +100048the 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
Darren Tuckerf2e21de2008-07-02 22:35:00 +100059The following message descriptions refer only to the content the
Damien Miller1e18beb2008-06-30 00:07:00 +100060"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
Darren Tuckerf2e21de2008-07-02 22:35:00 +100089or other hardware security module. These keys may be added
Damien Miller1e18beb2008-06-30 00:07:00 +100090to the agent using the SSH_AGENTC_ADD_SMARTCARD_KEY and
Darren Tuckerf2e21de2008-07-02 22:35:00 +100091SSH_AGENTC_ADD_SMARTCARD_KEY_CONSTRAINED requests.
Damien Miller1e18beb2008-06-30 00:07:00 +100092
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
Darren Tucker00f00f02008-07-02 22:31:31 +1000120 .... constraint1_data
Damien Miller1e18beb2008-06-30 00:07:00 +1000121 byte constraint2_type
Darren Tucker00f00f02008-07-02 22:31:31 +1000122 .... constraint2_data
Damien Miller1e18beb2008-06-30 00:07:00 +1000123 ....
124 byte constraintN_type
Darren Tucker00f00f02008-07-02 22:31:31 +1000125 .... constraintN_data
Damien Miller1e18beb2008-06-30 00:07:00 +1000126
127Such a sequence of zero or more constraints will be referred to below
128as "constraint[]". Agents may determine whether there are constraints
Darren Tuckerf2e21de2008-07-02 22:35:00 +1000129by checking whether additional data exists in the "add key" request
Damien Miller1e18beb2008-06-30 00:07:00 +1000130after 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_IDENTITY.
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
Damien Millereb8b60e2010-08-31 22:41:14 +1000162The OpenSSH agent supports DSA, ECDSA and RSA keys for protocol 2. DSA
163keys may be added using the following request
Damien Miller1e18beb2008-06-30 00:07:00 +1000164
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
Damien Miller0a80ca12010-02-27 07:55:05 +1100176DSA 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
Damien Millereb8b60e2010-08-31 22:41:14 +1000185ECDSA 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
Damien Miller1e18beb2008-06-30 00:07:00 +1000209RSA keys may be added with this request:
210
211 byte SSH2_AGENTC_ADD_IDENTITY or
212 SSH2_AGENTC_ADD_ID_CONSTRAINED
213 string "ssh-rsa"
214 mpint rsa_n
215 mpint rsa_e
216 mpint rsa_d
217 mpint rsa_iqmp
218 mpint rsa_p
219 mpint rsa_q
220 string key_comment
221 constraint[] key_constraints
222
Damien Miller0a80ca12010-02-27 07:55:05 +1100223RSA certificates may be added with this request:
224
225 byte SSH2_AGENTC_ADD_IDENTITY or
226 SSH2_AGENTC_ADD_ID_CONSTRAINED
227 string "ssh-rsa-cert-v00@openssh.com"
228 string certificate
229 mpint rsa_d
230 mpint rsa_iqmp
231 mpint rsa_p
232 mpint rsa_q
233 string key_comment
234 constraint[] key_constraints
235
Darren Tuckerf2e21de2008-07-02 22:35:00 +1000236Note that the 'rsa_p' and 'rsa_q' parameters are sent in the reverse
Damien Miller1e18beb2008-06-30 00:07:00 +1000237order to the protocol 1 add keys message. As with the corresponding
238protocol 1 "add key" request, the private key is overspecified to avoid
239redundant processing.
240
Damien Millereb8b60e2010-08-31 22:41:14 +1000241For DSA, ECDSA and RSA key add requests, "key_constraints" may only be
Damien Miller1e18beb2008-06-30 00:07:00 +1000242present if the request type is SSH2_AGENTC_ADD_ID_CONSTRAINED.
243
244The agent will reply with a SSH_AGENT_SUCCESS if the key has been
245successfully added or a SSH_AGENT_FAILURE if an error occurred.
246
2472.2.4 Loading keys from a smartcard
248
249The OpenSSH agent may have optional smartcard support built in to it. If
250so, it supports an operation to load keys from a smartcard. Technically,
251only the public components of the keys are loaded into the agent so
252this operation really arranges for future private key operations to be
253delegated to the smartcard.
254
255 byte SSH_AGENTC_ADD_SMARTCARD_KEY or
256 SSH_AGENTC_ADD_SMARTCARD_KEY_CONSTRAINED
257 string reader_id
258 string pin
259 constraint[] key_constraints
260
Darren Tuckerf2e21de2008-07-02 22:35:00 +1000261"reader_id" is an identifier to a smartcard reader and "pin"
Damien Miller1e18beb2008-06-30 00:07:00 +1000262is a PIN or passphrase used to unlock the private key(s) on the
263device. "key_constraints" may only be present if the request type is
264SSH_AGENTC_ADD_SMARTCARD_KEY_CONSTRAINED.
265
266This operation may load all SSH keys that are unlocked using the
267"pin" on the specified reader. The type of key loaded (protocol 1
268or protocol 2) will be specified by the smartcard itself, it is not
269client-specified.
270
271The agent will reply with a SSH_AGENT_SUCCESS if one or more keys have
272been successfully loaded or a SSH_AGENT_FAILURE if an error occurred.
273The agent will also return SSH_AGENT_FAILURE if it does not support
274smartcards.
275
2762.3 Removing multiple keys
277
278A client may request that an agent delete all protocol 1 keys using the
279following request:
280
281 byte SSH_AGENTC_REMOVE_ALL_RSA_IDENTITIES
282
283This message requests the deletion of all protocol 2 keys:
284
285 byte SSH2_AGENTC_REMOVE_ALL_IDENTITIES
286
287On success, the agent will delete all keys of the requested type and
288reply with a SSH_AGENT_SUCCESS message. If an error occurred, the agent
289will reply with SSH_AGENT_FAILURE.
290
291Note that, to delete all keys (both protocol 1 and 2), a client
292must send both a SSH_AGENTC_REMOVE_ALL_RSA_IDENTITIES and a
293SSH2_AGENTC_REMOVE_ALL_IDENTITIES request.
294
2952.4 Removing specific keys
296
2972.4.1 Removing a protocol 1 key
298
299Removal of a protocol 1 key may be requested with the following message:
300
301 byte SSH_AGENTC_REMOVE_RSA_IDENTITY
302 uint32 key_bits
303 mpint1 rsa_e
304 mpint1 rsa_n
305
306Note that key_bits is strictly redundant, as it may be inferred by the
307length of rsa_n.
308
309The agent will delete any private key matching the specified public key
310and return SSH_AGENT_SUCCESS. If no such key was found, the agent will
311return SSH_AGENT_FAILURE.
312
3132.4.2 Removing a protocol 2 key
314
315Protocol 2 keys may be removed with the following request:
316
317 byte SSH2_AGENTC_REMOVE_IDENTITY
318 string key_blob
319
320Where "key_blob" is encoded as per RFC 4253 section 6.6 "Public Key
Damien Millereb8b60e2010-08-31 22:41:14 +1000321Algorithms" for any of the supported protocol 2 key types.
Damien Miller1e18beb2008-06-30 00:07:00 +1000322
323The agent will delete any private key matching the specified public key
324and return SSH_AGENT_SUCCESS. If no such key was found, the agent will
325return SSH_AGENT_FAILURE.
326
3272.4.3 Removing keys loaded from a smartcard
328
329A client may request that a server remove one or more smartcard-hosted
330keys using this message:
331
332 byte SSH_AGENTC_REMOVE_SMARTCARD_KEY
333 string reader_id
334 string pin
335
336"reader_id" the an identifier to a smartcard reader and "pin" is a PIN
337or passphrase used to unlock the private key(s) on the device.
338
339When this message is received, and if the agent supports
340smartcard-hosted keys, it will delete all keys that are hosted on the
341specified smartcard that may be accessed with the given "pin".
342
343The agent will reply with a SSH_AGENT_SUCCESS if one or more keys have
344been successfully removed or a SSH_AGENT_FAILURE if an error occurred.
345The agent will also return SSH_AGENT_FAILURE if it does not support
346smartcards.
347
3482.5 Requesting a list of known keys
349
350An agent may be requested to list which keys it holds. Different
351requests exist for protocol 1 and protocol 2 keys.
352
3532.5.1 Requesting a list of protocol 1 keys
354
355To request a list of protocol 1 keys that are held in the agent, a
356client may send the following message:
357
358 byte SSH_AGENTC_REQUEST_RSA_IDENTITIES
359
360The agent will reply with the following message:
361
362 byte SSH_AGENT_RSA_IDENTITIES_ANSWER
363 uint32 num_keys
364
365Followed by zero or more consecutive keys, encoded as:
366
367 uint32 bits
368 mpint1 rsa_e
369 mpint1 rsa_n
370 string key_comment
371
3722.5.2 Requesting a list of protocol 2 keys
373
Darren Tuckerf2e21de2008-07-02 22:35:00 +1000374A client may send the following message to request a list of
Damien Miller1e18beb2008-06-30 00:07:00 +1000375protocol 2 keys that are stored in the agent:
376
377 byte SSH2_AGENTC_REQUEST_IDENTITIES
378
379The agent will reply with the following message header:
380
381 byte SSH2_AGENT_IDENTITIES_ANSWER
382 uint32 num_keys
383
384Followed by zero or more consecutive keys, encoded as:
385
386 string key_blob
387 string key_comment
388
389Where "key_blob" is encoded as per RFC 4253 section 6.6 "Public Key
Damien Millereb8b60e2010-08-31 22:41:14 +1000390Algorithms" for any of the supported protocol 2 key types.
Damien Miller1e18beb2008-06-30 00:07:00 +1000391
3922.6 Private key operations
393
394The purpose of the agent is to perform private key operations, such as
395signing and encryption without requiring a passphrase to unlock the
396key and without allowing the private key itself to be exposed. There
397are separate requests for the protocol 1 and protocol 2 private key
398operations.
399
4002.6.1 Protocol 1 private key challenge
401
402The private key operation used in version 1 of the SSH protocol is
403decrypting a challenge that has been encrypted with a public key.
404It may be requested using this message:
405
406 byte SSH_AGENTC_RSA_CHALLENGE
407 uint32 ignored
408 mpint1 rsa_e
409 mpint1 rsa_n
410 mpint1 encrypted_challenge
411 byte[16] session_id
412 uint32 response_type /* must be 1 */
413
414"rsa_e" and "rsa_n" are used to identify which private key to use.
415"encrypted_challenge" is a challenge blob that has (presumably)
416been encrypted with the public key and must be in the range
4171 <= encrypted_challenge < 2^256. "session_id" is the SSH protocol 1
418session ID (computed from the server host key, the server semi-ephemeral
Darren Tuckerf2e21de2008-07-02 22:35:00 +1000419key and the session cookie).
Damien Miller1e18beb2008-06-30 00:07:00 +1000420
421"ignored" and "response_type" exist for compatibility with legacy
422implementations. "response_type" must be equal to 1; other response
423types are not supported.
424
425On receiving this request, the server decrypts the "encrypted_challenge"
Darren Tuckerf2e21de2008-07-02 22:35:00 +1000426using the private key matching the supplied (rsa_e, rsa_n) values. For
Damien Miller1e18beb2008-06-30 00:07:00 +1000427the response derivation, the decrypted challenge is represented as an
428unsigned, big-endian integer encoded in a 32 byte buffer (i.e. values
429smaller than 2^248 will have leading 0 bytes).
430
431The response value is then calculated as:
432
433 response = MD5(decrypted_challenge || session_id)
434
435and returned in the following message
436
437 byte SSH_AGENT_RSA_RESPONSE
438 byte[16] response
439
440If the agent cannot find the key specified by the supplied (rsa_e,
441rsa_n) then it will return SSH_AGENT_FAILURE.
442
4432.6.2 Protocol 2 private key signature request
444
445A client may use the following message to request signing of data using
446a protocol 2 key:
447
448 byte SSH2_AGENTC_SIGN_REQUEST
449 string key_blob
450 string data
451 uint32 flags
452
453Where "key_blob" is encoded as per RFC 4253 section 6.6 "Public Key
Damien Millereb8b60e2010-08-31 22:41:14 +1000454Algorithms" for any of the supported protocol 2 key types. "flags" is
455a bit-mask, but at present only one possible value is defined (see below
456for its meaning):
Damien Miller1e18beb2008-06-30 00:07:00 +1000457
458 SSH_AGENT_OLD_SIGNATURE 1
459
460Upon receiving this request, the agent will look up the private key that
461corresponds to the public key contained in key_blob. It will use this
462private key to sign the "data" and produce a signature blob using the
463key type-specific method described in RFC 4253 section 6.6 "Public Key
464Algorithms".
465
466An exception to this is for "ssh-dss" keys where the "flags" word
467contains the value SSH_AGENT_OLD_SIGNATURE. In this case, a legacy
468signature encoding is used in lieu of the standard one. In this case,
469the DSA signature blob is encoded as:
470
471 byte[40] signature
472
473The signature will be returned in the response message:
474
475 byte SSH2_AGENT_SIGN_RESPONSE
476 string signature_blob
477
478If the agent cannot find the key specified by the supplied key_blob then
479it will return SSH_AGENT_FAILURE.
480
4812.7 Locking or unlocking an agent
482
483The agent supports temporary locking with a passphrase to suspend
484processing of sensitive operations until it has been unlocked with the
485same passphrase. To lock an agent, a client send the following request:
486
487 byte SSH_AGENTC_LOCK
488 string passphrase
489
490Upon receipt of this message and if the agent is not already locked,
491it will suspend processing requests and return a SSH_AGENT_SUCCESS
492reply. If the agent is already locked, it will return SSH_AGENT_FAILURE.
493
494While locked, the agent will refuse all requests except
495SSH_AGENTC_UNLOCK, SSH_AGENTC_REQUEST_RSA_IDENTITIES and
496SSH2_AGENTC_REQUEST_IDENTITIES. The "request identities" requests are
497treated specially by a locked agent: it will always return an empty list
498of keys.
499
500To unlock an agent, a client may request:
501
502 byte SSH_AGENTC_UNLOCK
503 string passphrase
504
505If the passphrase matches and the agent is locked, then it will resume
506processing all requests and return SSH_AGENT_SUCCESS. If the agent
507is not locked or the passphrase does not match then it will return
508SSH_AGENT_FAILURE.
509
510Locking and unlocking affects both protocol 1 and protocol 2 keys.
511
5123. Protocol message numbers
513
5143.1 Requests from client to agent for protocol 1 key operations
515
516 SSH_AGENTC_REQUEST_RSA_IDENTITIES 1
517 SSH_AGENTC_RSA_CHALLENGE 3
518 SSH_AGENTC_ADD_RSA_IDENTITY 7
519 SSH_AGENTC_REMOVE_RSA_IDENTITY 8
520 SSH_AGENTC_REMOVE_ALL_RSA_IDENTITIES 9
521 SSH_AGENTC_ADD_RSA_ID_CONSTRAINED 24
522
5233.2 Requests from client to agent for protocol 2 key operations
524
525 SSH2_AGENTC_REQUEST_IDENTITIES 11
526 SSH2_AGENTC_SIGN_REQUEST 13
527 SSH2_AGENTC_ADD_IDENTITY 17
528 SSH2_AGENTC_REMOVE_IDENTITY 18
529 SSH2_AGENTC_REMOVE_ALL_IDENTITIES 19
530 SSH2_AGENTC_ADD_ID_CONSTRAINED 25
531
5323.3 Key-type independent requests from client to agent
533
534 SSH_AGENTC_ADD_SMARTCARD_KEY 20
535 SSH_AGENTC_REMOVE_SMARTCARD_KEY 21
536 SSH_AGENTC_LOCK 22
537 SSH_AGENTC_UNLOCK 23
538 SSH_AGENTC_ADD_SMARTCARD_KEY_CONSTRAINED 26
539
5403.4 Generic replies from agent to client
541
542 SSH_AGENT_FAILURE 5
543 SSH_AGENT_SUCCESS 6
544
5453.5 Replies from agent to client for protocol 1 key operations
546
547 SSH_AGENT_RSA_IDENTITIES_ANSWER 2
548 SSH_AGENT_RSA_RESPONSE 4
549
5503.6 Replies from agent to client for protocol 2 key operations
551
552 SSH2_AGENT_IDENTITIES_ANSWER 12
553 SSH2_AGENT_SIGN_RESPONSE 14
554
5553.7 Key constraint identifiers
556
557 SSH_AGENT_CONSTRAIN_LIFETIME 1
558 SSH_AGENT_CONSTRAIN_CONFIRM 2
559
Damien Millereb8b60e2010-08-31 22:41:14 +1000560$OpenBSD: PROTOCOL.agent,v 1.6 2010/08/31 11:54:45 djm Exp $