PROTOCOL.agent

   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, ECDSA and RSA keys for protocol 2. DSA
 163 keys 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
 176 DSA 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
 185 ECDSA 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
 198 ECDSA 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
 209 RSA 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
 223 RSA 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
 236 Note that the 'rsa_p' and 'rsa_q' parameters are sent in the reverse
 237 order to the protocol 1 add keys message. As with the corresponding
 238 protocol 1 "add key" request, the private key is overspecified to avoid
 239 redundant processing.
 240
 241 For DSA, ECDSA and RSA key add requests, "key_constraints" may only be
 242 present if the request type is SSH2_AGENTC_ADD_ID_CONSTRAINED.
 243
 244 The agent will reply with a SSH_AGENT_SUCCESS if the key has been
 245 successfully added or a SSH_AGENT_FAILURE if an error occurred.
 246
 247 2.2.4 Loading keys from a smartcard
 248
 249 The OpenSSH agent may have optional smartcard support built in to it. If
 250 so, it supports an operation to load keys from a smartcard. Technically,
 251 only the public components of the keys are loaded into the agent so
 252 this operation really arranges for future private key operations to be
 253 delegated 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
 261 "reader_id" is an identifier to a smartcard reader and "pin"
 262 is a PIN or passphrase used to unlock the private key(s) on the
 263 device. "key_constraints" may only be present if the request type is
 264 SSH_AGENTC_ADD_SMARTCARD_KEY_CONSTRAINED.
 265
 266 This operation may load all SSH keys that are unlocked using the
 267 "pin" on the specified reader. The type of key loaded (protocol 1
 268 or protocol 2) will be specified by the smartcard itself, it is not
 269 client-specified.
 270
 271 The agent will reply with a SSH_AGENT_SUCCESS if one or more keys have
 272 been successfully loaded or a SSH_AGENT_FAILURE if an error occurred.
 273 The agent will also return SSH_AGENT_FAILURE if it does not support
 274 smartcards.
 275
 276 2.3 Removing multiple keys
 277
 278 A client may request that an agent delete all protocol 1 keys using the
 279 following request:
 280
 281         byte                    SSH_AGENTC_REMOVE_ALL_RSA_IDENTITIES
 282
 283 This message requests the deletion of all protocol 2 keys:
 284
 285         byte                    SSH2_AGENTC_REMOVE_ALL_IDENTITIES
 286
 287 On success, the agent will delete all keys of the requested type and
 288 reply with a SSH_AGENT_SUCCESS message. If an error occurred, the agent
 289 will reply with SSH_AGENT_FAILURE.
 290
 291 Note that, to delete all keys (both protocol 1 and 2), a client
 292 must send both a SSH_AGENTC_REMOVE_ALL_RSA_IDENTITIES and a
 293 SSH2_AGENTC_REMOVE_ALL_IDENTITIES request.
 294
 295 2.4 Removing specific keys
 296
 297 2.4.1 Removing a protocol 1 key
 298
 299 Removal 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
 306 Note that key_bits is strictly redundant, as it may be inferred by the
 307 length of rsa_n.
 308
 309 The agent will delete any private key matching the specified public key
 310 and return SSH_AGENT_SUCCESS. If no such key was found, the agent will
 311 return SSH_AGENT_FAILURE.
 312
 313 2.4.2 Removing a protocol 2 key
 314
 315 Protocol 2 keys may be removed with the following request:
 316
 317         byte                    SSH2_AGENTC_REMOVE_IDENTITY
 318         string                  key_blob
 319
 320 Where "key_blob" is encoded as per RFC 4253 section 6.6 "Public Key
 321 Algorithms" for any of the supported protocol 2 key types.
 322
 323 The agent will delete any private key matching the specified public key
 324 and return SSH_AGENT_SUCCESS. If no such key was found, the agent will
 325 return SSH_AGENT_FAILURE.
 326
 327 2.4.3 Removing keys loaded from a smartcard
 328
 329 A client may request that a server remove one or more smartcard-hosted
 330 keys 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
 337 or passphrase used to unlock the private key(s) on the device.
 338
 339 When this message is received, and if the agent supports
 340 smartcard-hosted keys, it will delete all keys that are hosted on the
 341 specified smartcard that may be accessed with the given "pin".
 342
 343 The agent will reply with a SSH_AGENT_SUCCESS if one or more keys have
 344 been successfully removed or a SSH_AGENT_FAILURE if an error occurred.
 345 The agent will also return SSH_AGENT_FAILURE if it does not support
 346 smartcards.
 347
 348 2.5 Requesting a list of known keys
 349
 350 An agent may be requested to list which keys it holds. Different
 351 requests exist for protocol 1 and protocol 2 keys.
 352
 353 2.5.1 Requesting a list of protocol 1 keys
 354
 355 To request a list of protocol 1 keys that are held in the agent, a
 356 client may send the following message:
 357
 358         byte                    SSH_AGENTC_REQUEST_RSA_IDENTITIES
 359
 360 The agent will reply with the following message:
 361
 362         byte                    SSH_AGENT_RSA_IDENTITIES_ANSWER
 363         uint32                  num_keys
 364
 365 Followed 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
 372 2.5.2 Requesting a list of protocol 2 keys
 373
 374 A client may send the following message to request a list of
 375 protocol 2 keys that are stored in the agent:
 376
 377         byte                    SSH2_AGENTC_REQUEST_IDENTITIES
 378
 379 The agent will reply with the following message header:
 380
 381         byte                    SSH2_AGENT_IDENTITIES_ANSWER
 382         uint32                  num_keys
 383
 384 Followed by zero or more consecutive keys, encoded as:
 385
 386         string                  key_blob
 387         string                  key_comment
 388
 389 Where "key_blob" is encoded as per RFC 4253 section 6.6 "Public Key
 390 Algorithms" for any of the supported protocol 2 key types.
 391
 392 2.6 Private key operations
 393
 394 The purpose of the agent is to perform private key operations, such as
 395 signing and encryption without requiring a passphrase to unlock the
 396 key and without allowing the private key itself to be exposed. There
 397 are separate requests for the protocol 1 and protocol 2 private key
 398 operations.
 399
 400 2.6.1 Protocol 1 private key challenge
 401
 402 The private key operation used in version 1 of the SSH protocol is
 403 decrypting a challenge that has been encrypted with a public key.
 404 It 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)
 416 been encrypted with the public key and must be in the range
 417 1 <= encrypted_challenge < 2^256. "session_id" is the SSH protocol 1
 418 session ID (computed from the server host key, the server semi-ephemeral
 419 key and the session cookie).
 420
 421 "ignored" and "response_type" exist for compatibility with legacy
 422 implementations. "response_type" must be equal to 1; other response
 423 types are not supported.
 424
 425 On receiving this request, the server decrypts the "encrypted_challenge"
 426 using the private key matching the supplied (rsa_e, rsa_n) values. For
 427 the response derivation, the decrypted challenge is represented as an
 428 unsigned, big-endian integer encoded in a 32 byte buffer (i.e. values
 429 smaller than 2^248 will have leading 0 bytes).
 430
 431 The response value is then calculated as:
 432
 433         response = MD5(decrypted_challenge || session_id)
 434
 435 and returned in the following message
 436
 437         byte                    SSH_AGENT_RSA_RESPONSE
 438         byte[16]                response
 439
 440 If the agent cannot find the key specified by the supplied (rsa_e,
 441 rsa_n) then it will return SSH_AGENT_FAILURE.
 442
 443 2.6.2 Protocol 2 private key signature request
 444
 445 A client may use the following message to request signing of data using
 446 a protocol 2 key:
 447
 448         byte                    SSH2_AGENTC_SIGN_REQUEST
 449         string                  key_blob
 450         string                  data
 451         uint32                  flags
 452
 453 Where "key_blob" is encoded as per RFC 4253 section 6.6 "Public Key
 454 Algorithms" for any of the supported protocol 2 key types. "flags" is
 455 a bit-mask, but at present only one possible value is defined (see below
 456 for its meaning):
 457
 458         SSH_AGENT_OLD_SIGNATURE         1
 459
 460 Upon receiving this request, the agent will look up the private key that
 461 corresponds to the public key contained in key_blob. It will use this
 462 private key to sign the "data" and produce a signature blob using the
 463 key type-specific method described in RFC 4253 section 6.6 "Public Key
 464 Algorithms".
 465
 466 An exception to this is for "ssh-dss" keys where the "flags" word
 467 contains the value SSH_AGENT_OLD_SIGNATURE. In this case, a legacy
 468 signature encoding is used in lieu of the standard one. In this case,
 469 the DSA signature blob is encoded as:
 470
 471         byte[40]                signature
 472
 473 The signature will be returned in the response message:
 474
 475         byte                    SSH2_AGENT_SIGN_RESPONSE
 476         string                  signature_blob
 477
 478 If the agent cannot find the key specified by the supplied key_blob then
 479 it will return SSH_AGENT_FAILURE.
 480
 481 2.7 Locking or unlocking an agent
 482
 483 The agent supports temporary locking with a passphrase to suspend
 484 processing of sensitive operations until it has been unlocked with the
 485 same passphrase. To lock an agent, a client send the following request:
 486
 487         byte                    SSH_AGENTC_LOCK
 488         string                  passphrase
 489
 490 Upon receipt of this message and if the agent is not already locked,
 491 it will suspend processing requests and return a SSH_AGENT_SUCCESS
 492 reply. If the agent is already locked, it will return SSH_AGENT_FAILURE.
 493
 494 While locked, the agent will refuse all requests except
 495 SSH_AGENTC_UNLOCK, SSH_AGENTC_REQUEST_RSA_IDENTITIES and
 496 SSH2_AGENTC_REQUEST_IDENTITIES. The "request identities" requests are
 497 treated specially by a locked agent: it will always return an empty list
 498 of keys.
 499
 500 To unlock an agent, a client may request:
 501
 502         byte                    SSH_AGENTC_UNLOCK
 503         string                  passphrase
 504
 505 If the passphrase matches and the agent is locked, then it will resume
 506 processing all requests and return SSH_AGENT_SUCCESS. If the agent
 507 is not locked or the passphrase does not match then it will return
 508 SSH_AGENT_FAILURE.
 509
 510 Locking and unlocking affects both protocol 1 and protocol 2 keys.
 511
 512 3. Protocol message numbers
 513
 514 3.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
 523 3.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
 532 3.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
 540 3.4 Generic replies from agent to client
 541
 542         SSH_AGENT_FAILURE                               5
 543         SSH_AGENT_SUCCESS                               6
 544
 545 3.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
 550 3.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
 555 3.7 Key constraint identifiers
 556
 557         SSH_AGENT_CONSTRAIN_LIFETIME                    1
 558         SSH_AGENT_CONSTRAIN_CONFIRM                     2
 559
 560 $OpenBSD: PROTOCOL.agent,v 1.6 2010/08/31 11:54:45 djm Exp $