1This 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 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_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 162The OpenSSH agent supports DSA and RSA keys for protocol 2. DSA keys may 163be 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 185RSA keys may be added with this request: 186 187 byte SSH2_AGENTC_ADD_IDENTITY or 188 SSH2_AGENTC_ADD_ID_CONSTRAINED 189 string "ssh-rsa" 190 mpint rsa_n 191 mpint rsa_e 192 mpint rsa_d 193 mpint rsa_iqmp 194 mpint rsa_p 195 mpint rsa_q 196 string key_comment 197 constraint[] key_constraints 198 199RSA certificates may be added with this request: 200 201 byte SSH2_AGENTC_ADD_IDENTITY or 202 SSH2_AGENTC_ADD_ID_CONSTRAINED 203 string "ssh-rsa-cert-v00@openssh.com" 204 string certificate 205 mpint rsa_d 206 mpint rsa_iqmp 207 mpint rsa_p 208 mpint rsa_q 209 string key_comment 210 constraint[] key_constraints 211 212Note that the 'rsa_p' and 'rsa_q' parameters are sent in the reverse 213order to the protocol 1 add keys message. As with the corresponding 214protocol 1 "add key" request, the private key is overspecified to avoid 215redundant processing. 216 217For both DSA and RSA key add requests, "key_constraints" may only be 218present if the request type is SSH2_AGENTC_ADD_ID_CONSTRAINED. 219 220The agent will reply with a SSH_AGENT_SUCCESS if the key has been 221successfully added or a SSH_AGENT_FAILURE if an error occurred. 222 2232.2.4 Loading keys from a smartcard 224 225The OpenSSH agent may have optional smartcard support built in to it. If 226so, it supports an operation to load keys from a smartcard. Technically, 227only the public components of the keys are loaded into the agent so 228this operation really arranges for future private key operations to be 229delegated to the smartcard. 230 231 byte SSH_AGENTC_ADD_SMARTCARD_KEY or 232 SSH_AGENTC_ADD_SMARTCARD_KEY_CONSTRAINED 233 string reader_id 234 string pin 235 constraint[] key_constraints 236 237"reader_id" is an identifier to a smartcard reader and "pin" 238is a PIN or passphrase used to unlock the private key(s) on the 239device. "key_constraints" may only be present if the request type is 240SSH_AGENTC_ADD_SMARTCARD_KEY_CONSTRAINED. 241 242This operation may load all SSH keys that are unlocked using the 243"pin" on the specified reader. The type of key loaded (protocol 1 244or protocol 2) will be specified by the smartcard itself, it is not 245client-specified. 246 247The agent will reply with a SSH_AGENT_SUCCESS if one or more keys have 248been successfully loaded or a SSH_AGENT_FAILURE if an error occurred. 249The agent will also return SSH_AGENT_FAILURE if it does not support 250smartcards. 251 2522.3 Removing multiple keys 253 254A client may request that an agent delete all protocol 1 keys using the 255following request: 256 257 byte SSH_AGENTC_REMOVE_ALL_RSA_IDENTITIES 258 259This message requests the deletion of all protocol 2 keys: 260 261 byte SSH2_AGENTC_REMOVE_ALL_IDENTITIES 262 263On success, the agent will delete all keys of the requested type and 264reply with a SSH_AGENT_SUCCESS message. If an error occurred, the agent 265will reply with SSH_AGENT_FAILURE. 266 267Note that, to delete all keys (both protocol 1 and 2), a client 268must send both a SSH_AGENTC_REMOVE_ALL_RSA_IDENTITIES and a 269SSH2_AGENTC_REMOVE_ALL_IDENTITIES request. 270 2712.4 Removing specific keys 272 2732.4.1 Removing a protocol 1 key 274 275Removal of a protocol 1 key may be requested with the following message: 276 277 byte SSH_AGENTC_REMOVE_RSA_IDENTITY 278 uint32 key_bits 279 mpint1 rsa_e 280 mpint1 rsa_n 281 282Note that key_bits is strictly redundant, as it may be inferred by the 283length of rsa_n. 284 285The agent will delete any private key matching the specified public key 286and return SSH_AGENT_SUCCESS. If no such key was found, the agent will 287return SSH_AGENT_FAILURE. 288 2892.4.2 Removing a protocol 2 key 290 291Protocol 2 keys may be removed with the following request: 292 293 byte SSH2_AGENTC_REMOVE_IDENTITY 294 string key_blob 295 296Where "key_blob" is encoded as per RFC 4253 section 6.6 "Public Key 297Algorithms" for either of the supported key types: "ssh-dss" or 298"ssh-rsa". 299 300The agent will delete any private key matching the specified public key 301and return SSH_AGENT_SUCCESS. If no such key was found, the agent will 302return SSH_AGENT_FAILURE. 303 3042.4.3 Removing keys loaded from a smartcard 305 306A client may request that a server remove one or more smartcard-hosted 307keys using this message: 308 309 byte SSH_AGENTC_REMOVE_SMARTCARD_KEY 310 string reader_id 311 string pin 312 313"reader_id" the an identifier to a smartcard reader and "pin" is a PIN 314or passphrase used to unlock the private key(s) on the device. 315 316When this message is received, and if the agent supports 317smartcard-hosted keys, it will delete all keys that are hosted on the 318specified smartcard that may be accessed with the given "pin". 319 320The agent will reply with a SSH_AGENT_SUCCESS if one or more keys have 321been successfully removed or a SSH_AGENT_FAILURE if an error occurred. 322The agent will also return SSH_AGENT_FAILURE if it does not support 323smartcards. 324 3252.5 Requesting a list of known keys 326 327An agent may be requested to list which keys it holds. Different 328requests exist for protocol 1 and protocol 2 keys. 329 3302.5.1 Requesting a list of protocol 1 keys 331 332To request a list of protocol 1 keys that are held in the agent, a 333client may send the following message: 334 335 byte SSH_AGENTC_REQUEST_RSA_IDENTITIES 336 337The agent will reply with the following message: 338 339 byte SSH_AGENT_RSA_IDENTITIES_ANSWER 340 uint32 num_keys 341 342Followed by zero or more consecutive keys, encoded as: 343 344 uint32 bits 345 mpint1 rsa_e 346 mpint1 rsa_n 347 string key_comment 348 3492.5.2 Requesting a list of protocol 2 keys 350 351A client may send the following message to request a list of 352protocol 2 keys that are stored in the agent: 353 354 byte SSH2_AGENTC_REQUEST_IDENTITIES 355 356The agent will reply with the following message header: 357 358 byte SSH2_AGENT_IDENTITIES_ANSWER 359 uint32 num_keys 360 361Followed by zero or more consecutive keys, encoded as: 362 363 string key_blob 364 string key_comment 365 366Where "key_blob" is encoded as per RFC 4253 section 6.6 "Public Key 367Algorithms" for either of the supported key types: "ssh-dss" or 368"ssh-rsa". 369 3702.6 Private key operations 371 372The purpose of the agent is to perform private key operations, such as 373signing and encryption without requiring a passphrase to unlock the 374key and without allowing the private key itself to be exposed. There 375are separate requests for the protocol 1 and protocol 2 private key 376operations. 377 3782.6.1 Protocol 1 private key challenge 379 380The private key operation used in version 1 of the SSH protocol is 381decrypting a challenge that has been encrypted with a public key. 382It may be requested using this message: 383 384 byte SSH_AGENTC_RSA_CHALLENGE 385 uint32 ignored 386 mpint1 rsa_e 387 mpint1 rsa_n 388 mpint1 encrypted_challenge 389 byte[16] session_id 390 uint32 response_type /* must be 1 */ 391 392"rsa_e" and "rsa_n" are used to identify which private key to use. 393"encrypted_challenge" is a challenge blob that has (presumably) 394been encrypted with the public key and must be in the range 3951 <= encrypted_challenge < 2^256. "session_id" is the SSH protocol 1 396session ID (computed from the server host key, the server semi-ephemeral 397key and the session cookie). 398 399"ignored" and "response_type" exist for compatibility with legacy 400implementations. "response_type" must be equal to 1; other response 401types are not supported. 402 403On receiving this request, the server decrypts the "encrypted_challenge" 404using the private key matching the supplied (rsa_e, rsa_n) values. For 405the response derivation, the decrypted challenge is represented as an 406unsigned, big-endian integer encoded in a 32 byte buffer (i.e. values 407smaller than 2^248 will have leading 0 bytes). 408 409The response value is then calculated as: 410 411 response = MD5(decrypted_challenge || session_id) 412 413and returned in the following message 414 415 byte SSH_AGENT_RSA_RESPONSE 416 byte[16] response 417 418If the agent cannot find the key specified by the supplied (rsa_e, 419rsa_n) then it will return SSH_AGENT_FAILURE. 420 4212.6.2 Protocol 2 private key signature request 422 423A client may use the following message to request signing of data using 424a protocol 2 key: 425 426 byte SSH2_AGENTC_SIGN_REQUEST 427 string key_blob 428 string data 429 uint32 flags 430 431Where "key_blob" is encoded as per RFC 4253 section 6.6 "Public Key 432Algorithms" for either of the supported key types: "ssh-dss" or 433"ssh-rsa". "flags" is a bit-mask, but at present only one possible value 434is defined (see below for its meaning): 435 436 SSH_AGENT_OLD_SIGNATURE 1 437 438Upon receiving this request, the agent will look up the private key that 439corresponds to the public key contained in key_blob. It will use this 440private key to sign the "data" and produce a signature blob using the 441key type-specific method described in RFC 4253 section 6.6 "Public Key 442Algorithms". 443 444An exception to this is for "ssh-dss" keys where the "flags" word 445contains the value SSH_AGENT_OLD_SIGNATURE. In this case, a legacy 446signature encoding is used in lieu of the standard one. In this case, 447the DSA signature blob is encoded as: 448 449 byte[40] signature 450 451The signature will be returned in the response message: 452 453 byte SSH2_AGENT_SIGN_RESPONSE 454 string signature_blob 455 456If the agent cannot find the key specified by the supplied key_blob then 457it will return SSH_AGENT_FAILURE. 458 4592.7 Locking or unlocking an agent 460 461The agent supports temporary locking with a passphrase to suspend 462processing of sensitive operations until it has been unlocked with the 463same passphrase. To lock an agent, a client send the following request: 464 465 byte SSH_AGENTC_LOCK 466 string passphrase 467 468Upon receipt of this message and if the agent is not already locked, 469it will suspend processing requests and return a SSH_AGENT_SUCCESS 470reply. If the agent is already locked, it will return SSH_AGENT_FAILURE. 471 472While locked, the agent will refuse all requests except 473SSH_AGENTC_UNLOCK, SSH_AGENTC_REQUEST_RSA_IDENTITIES and 474SSH2_AGENTC_REQUEST_IDENTITIES. The "request identities" requests are 475treated specially by a locked agent: it will always return an empty list 476of keys. 477 478To unlock an agent, a client may request: 479 480 byte SSH_AGENTC_UNLOCK 481 string passphrase 482 483If the passphrase matches and the agent is locked, then it will resume 484processing all requests and return SSH_AGENT_SUCCESS. If the agent 485is not locked or the passphrase does not match then it will return 486SSH_AGENT_FAILURE. 487 488Locking and unlocking affects both protocol 1 and protocol 2 keys. 489 4903. Protocol message numbers 491 4923.1 Requests from client to agent for protocol 1 key operations 493 494 SSH_AGENTC_REQUEST_RSA_IDENTITIES 1 495 SSH_AGENTC_RSA_CHALLENGE 3 496 SSH_AGENTC_ADD_RSA_IDENTITY 7 497 SSH_AGENTC_REMOVE_RSA_IDENTITY 8 498 SSH_AGENTC_REMOVE_ALL_RSA_IDENTITIES 9 499 SSH_AGENTC_ADD_RSA_ID_CONSTRAINED 24 500 5013.2 Requests from client to agent for protocol 2 key operations 502 503 SSH2_AGENTC_REQUEST_IDENTITIES 11 504 SSH2_AGENTC_SIGN_REQUEST 13 505 SSH2_AGENTC_ADD_IDENTITY 17 506 SSH2_AGENTC_REMOVE_IDENTITY 18 507 SSH2_AGENTC_REMOVE_ALL_IDENTITIES 19 508 SSH2_AGENTC_ADD_ID_CONSTRAINED 25 509 5103.3 Key-type independent requests from client to agent 511 512 SSH_AGENTC_ADD_SMARTCARD_KEY 20 513 SSH_AGENTC_REMOVE_SMARTCARD_KEY 21 514 SSH_AGENTC_LOCK 22 515 SSH_AGENTC_UNLOCK 23 516 SSH_AGENTC_ADD_SMARTCARD_KEY_CONSTRAINED 26 517 5183.4 Generic replies from agent to client 519 520 SSH_AGENT_FAILURE 5 521 SSH_AGENT_SUCCESS 6 522 5233.5 Replies from agent to client for protocol 1 key operations 524 525 SSH_AGENT_RSA_IDENTITIES_ANSWER 2 526 SSH_AGENT_RSA_RESPONSE 4 527 5283.6 Replies from agent to client for protocol 2 key operations 529 530 SSH2_AGENT_IDENTITIES_ANSWER 12 531 SSH2_AGENT_SIGN_RESPONSE 14 532 5333.7 Key constraint identifiers 534 535 SSH_AGENT_CONSTRAIN_LIFETIME 1 536 SSH_AGENT_CONSTRAIN_CONFIRM 2 537 538$OpenBSD: PROTOCOL.agent,v 1.5 2010/02/26 20:29:54 djm Exp $ 539