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 176RSA 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 190Note that the 'rsa_p' and 'rsa_q' parameters are sent in the reverse 191order to the protocol 1 add keys message. As with the corresponding 192protocol 1 "add key" request, the private key is overspecified to avoid 193redundant processing. 194 195For both DSA and RSA key add requests, "key_constraints" may only be 196present if the request type is SSH2_AGENTC_ADD_ID_CONSTRAINED. 197 198The agent will reply with a SSH_AGENT_SUCCESS if the key has been 199successfully added or a SSH_AGENT_FAILURE if an error occurred. 200 2012.2.4 Loading keys from a smartcard 202 203The OpenSSH agent may have optional smartcard support built in to it. If 204so, it supports an operation to load keys from a smartcard. Technically, 205only the public components of the keys are loaded into the agent so 206this operation really arranges for future private key operations to be 207delegated 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" 216is a PIN or passphrase used to unlock the private key(s) on the 217device. "key_constraints" may only be present if the request type is 218SSH_AGENTC_ADD_SMARTCARD_KEY_CONSTRAINED. 219 220This operation may load all SSH keys that are unlocked using the 221"pin" on the specified reader. The type of key loaded (protocol 1 222or protocol 2) will be specified by the smartcard itself, it is not 223client-specified. 224 225The agent will reply with a SSH_AGENT_SUCCESS if one or more keys have 226been successfully loaded or a SSH_AGENT_FAILURE if an error occurred. 227The agent will also return SSH_AGENT_FAILURE if it does not support 228smartcards. 229 2302.3 Removing multiple keys 231 232A client may request that an agent delete all protocol 1 keys using the 233following request: 234 235 byte SSH_AGENTC_REMOVE_ALL_RSA_IDENTITIES 236 237This message requests the deletion of all protocol 2 keys: 238 239 byte SSH2_AGENTC_REMOVE_ALL_IDENTITIES 240 241On success, the agent will delete all keys of the requested type and 242reply with a SSH_AGENT_SUCCESS message. If an error occurred, the agent 243will reply with SSH_AGENT_FAILURE. 244 245Note that, to delete all keys (both protocol 1 and 2), a client 246must send both a SSH_AGENTC_REMOVE_ALL_RSA_IDENTITIES and a 247SSH2_AGENTC_REMOVE_ALL_IDENTITIES request. 248 2492.4 Removing specific keys 250 2512.4.1 Removing a protocol 1 key 252 253Removal 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 260Note that key_bits is strictly redundant, as it may be inferred by the 261length of rsa_n. 262 263The agent will delete any private key matching the specified public key 264and return SSH_AGENT_SUCCESS. If no such key was found, the agent will 265return SSH_AGENT_FAILURE. 266 2672.4.2 Removing a protocol 2 key 268 269Protocol 2 keys may be removed with the following request: 270 271 byte SSH2_AGENTC_REMOVE_IDENTITY 272 string key_blob 273 274Where "key_blob" is encoded as per RFC 4253 section 6.6 "Public Key 275Algorithms" for either of the supported key types: "ssh-dss" or 276"ssh-rsa". 277 278The agent will delete any private key matching the specified public key 279and return SSH_AGENT_SUCCESS. If no such key was found, the agent will 280return SSH_AGENT_FAILURE. 281 2822.4.3 Removing keys loaded from a smartcard 283 284A client may request that a server remove one or more smartcard-hosted 285keys 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 292or passphrase used to unlock the private key(s) on the device. 293 294When this message is received, and if the agent supports 295smartcard-hosted keys, it will delete all keys that are hosted on the 296specified smartcard that may be accessed with the given "pin". 297 298The agent will reply with a SSH_AGENT_SUCCESS if one or more keys have 299been successfully removed or a SSH_AGENT_FAILURE if an error occurred. 300The agent will also return SSH_AGENT_FAILURE if it does not support 301smartcards. 302 3032.5 Requesting a list of known keys 304 305An agent may be requested to list which keys it holds. Different 306requests exist for protocol 1 and protocol 2 keys. 307 3082.5.1 Requesting a list of protocol 1 keys 309 310To request a list of protocol 1 keys that are held in the agent, a 311client may send the following message: 312 313 byte SSH_AGENTC_REQUEST_RSA_IDENTITIES 314 315The agent will reply with the following message: 316 317 byte SSH_AGENT_RSA_IDENTITIES_ANSWER 318 uint32 num_keys 319 320Followed 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 3272.5.2 Requesting a list of protocol 2 keys 328 329A client may send the following message to request a list of 330protocol 2 keys that are stored in the agent: 331 332 byte SSH2_AGENTC_REQUEST_IDENTITIES 333 334The agent will reply with the following message header: 335 336 byte SSH2_AGENT_IDENTITIES_ANSWER 337 uint32 num_keys 338 339Followed by zero or more consecutive keys, encoded as: 340 341 string key_blob 342 string key_comment 343 344Where "key_blob" is encoded as per RFC 4253 section 6.6 "Public Key 345Algorithms" for either of the supported key types: "ssh-dss" or 346"ssh-rsa". 347 3482.6 Private key operations 349 350The purpose of the agent is to perform private key operations, such as 351signing and encryption without requiring a passphrase to unlock the 352key and without allowing the private key itself to be exposed. There 353are separate requests for the protocol 1 and protocol 2 private key 354operations. 355 3562.6.1 Protocol 1 private key challenge 357 358The private key operation used in version 1 of the SSH protocol is 359decrypting a challenge that has been encrypted with a public key. 360It 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) 372been encrypted with the public key and must be in the range 3731 <= encrypted_challenge < 2^256. "session_id" is the SSH protocol 1 374session ID (computed from the server host key, the server semi-ephemeral 375key and the session cookie). 376 377"ignored" and "response_type" exist for compatibility with legacy 378implementations. "response_type" must be equal to 1; other response 379types are not supported. 380 381On receiving this request, the server decrypts the "encrypted_challenge" 382using the private key matching the supplied (rsa_e, rsa_n) values. For 383the response derivation, the decrypted challenge is represented as an 384unsigned, big-endian integer encoded in a 32 byte buffer (i.e. values 385smaller than 2^248 will have leading 0 bytes). 386 387The response value is then calculated as: 388 389 response = MD5(decrypted_challenge || session_id) 390 391and returned in the following message 392 393 byte SSH_AGENT_RSA_RESPONSE 394 byte[16] response 395 396If the agent cannot find the key specified by the supplied (rsa_e, 397rsa_n) then it will return SSH_AGENT_FAILURE. 398 3992.6.2 Protocol 2 private key signature request 400 401A client may use the following message to request signing of data using 402a protocol 2 key: 403 404 byte SSH2_AGENTC_SIGN_REQUEST 405 string key_blob 406 string data 407 uint32 flags 408 409Where "key_blob" is encoded as per RFC 4253 section 6.6 "Public Key 410Algorithms" 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 412is defined (see below for its meaning): 413 414 SSH_AGENT_OLD_SIGNATURE 1 415 416Upon receiving this request, the agent will look up the private key that 417corresponds to the public key contained in key_blob. It will use this 418private key to sign the "data" and produce a signature blob using the 419key type-specific method described in RFC 4253 section 6.6 "Public Key 420Algorithms". 421 422An exception to this is for "ssh-dss" keys where the "flags" word 423contains the value SSH_AGENT_OLD_SIGNATURE. In this case, a legacy 424signature encoding is used in lieu of the standard one. In this case, 425the DSA signature blob is encoded as: 426 427 byte[40] signature 428 429The signature will be returned in the response message: 430 431 byte SSH2_AGENT_SIGN_RESPONSE 432 string signature_blob 433 434If the agent cannot find the key specified by the supplied key_blob then 435it will return SSH_AGENT_FAILURE. 436 4372.7 Locking or unlocking an agent 438 439The agent supports temporary locking with a passphrase to suspend 440processing of sensitive operations until it has been unlocked with the 441same passphrase. To lock an agent, a client send the following request: 442 443 byte SSH_AGENTC_LOCK 444 string passphrase 445 446Upon receipt of this message and if the agent is not already locked, 447it will suspend processing requests and return a SSH_AGENT_SUCCESS 448reply. If the agent is already locked, it will return SSH_AGENT_FAILURE. 449 450While locked, the agent will refuse all requests except 451SSH_AGENTC_UNLOCK, SSH_AGENTC_REQUEST_RSA_IDENTITIES and 452SSH2_AGENTC_REQUEST_IDENTITIES. The "request identities" requests are 453treated specially by a locked agent: it will always return an empty list 454of keys. 455 456To unlock an agent, a client may request: 457 458 byte SSH_AGENTC_UNLOCK 459 string passphrase 460 461If the passphrase matches and the agent is locked, then it will resume 462processing all requests and return SSH_AGENT_SUCCESS. If the agent 463is not locked or the passphrase does not match then it will return 464SSH_AGENT_FAILURE. 465 466Locking and unlocking affects both protocol 1 and protocol 2 keys. 467 4683. Protocol message numbers 469 4703.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 4793.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 4883.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 4963.4 Generic replies from agent to client 497 498 SSH_AGENT_FAILURE 5 499 SSH_AGENT_SUCCESS 6 500 5013.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 5063.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 5113.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 $ 517