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 and RSA keys for protocol 2. DSA keys may
 163 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 RSA 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
 199 RSA 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
 212 Note that the 'rsa_p' and 'rsa_q' parameters are sent in the reverse
 213 order to the protocol 1 add keys message. As with the corresponding
 214 protocol 1 "add key" request, the private key is overspecified to avoid
 215 redundant processing.
 216
 217 For both DSA and RSA key add requests, "key_constraints" may only be
 218 present if the request type is SSH2_AGENTC_ADD_ID_CONSTRAINED.
 219
 220 The agent will reply with a SSH_AGENT_SUCCESS if the key has been
 221 successfully added or a SSH_AGENT_FAILURE if an error occurred.
 222
 223 2.2.4 Loading keys from a smartcard
 224
 225 The OpenSSH agent may have optional smartcard support built in to it. If
 226 so, it supports an operation to load keys from a smartcard. Technically,
 227 only the public components of the keys are loaded into the agent so
 228 this operation really arranges for future private key operations to be
 229 delegated 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"
 238 is a PIN or passphrase used to unlock the private key(s) on the
 239 device. "key_constraints" may only be present if the request type is
 240 SSH_AGENTC_ADD_SMARTCARD_KEY_CONSTRAINED.
 241
 242 This operation may load all SSH keys that are unlocked using the
 243 "pin" on the specified reader. The type of key loaded (protocol 1
 244 or protocol 2) will be specified by the smartcard itself, it is not
 245 client-specified.
 246
 247 The agent will reply with a SSH_AGENT_SUCCESS if one or more keys have
 248 been successfully loaded or a SSH_AGENT_FAILURE if an error occurred.
 249 The agent will also return SSH_AGENT_FAILURE if it does not support
 250 smartcards.
 251
 252 2.3 Removing multiple keys
 253
 254 A client may request that an agent delete all protocol 1 keys using the
 255 following request:
 256
 257         byte                    SSH_AGENTC_REMOVE_ALL_RSA_IDENTITIES
 258
 259 This message requests the deletion of all protocol 2 keys:
 260
 261         byte                    SSH2_AGENTC_REMOVE_ALL_IDENTITIES
 262
 263 On success, the agent will delete all keys of the requested type and
 264 reply with a SSH_AGENT_SUCCESS message. If an error occurred, the agent
 265 will reply with SSH_AGENT_FAILURE.
 266
 267 Note that, to delete all keys (both protocol 1 and 2), a client
 268 must send both a SSH_AGENTC_REMOVE_ALL_RSA_IDENTITIES and a
 269 SSH2_AGENTC_REMOVE_ALL_IDENTITIES request.
 270
 271 2.4 Removing specific keys
 272
 273 2.4.1 Removing a protocol 1 key
 274
 275 Removal 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
 282 Note that key_bits is strictly redundant, as it may be inferred by the
 283 length of rsa_n.
 284
 285 The agent will delete any private key matching the specified public key
 286 and return SSH_AGENT_SUCCESS. If no such key was found, the agent will
 287 return SSH_AGENT_FAILURE.
 288
 289 2.4.2 Removing a protocol 2 key
 290
 291 Protocol 2 keys may be removed with the following request:
 292
 293         byte                    SSH2_AGENTC_REMOVE_IDENTITY
 294         string                  key_blob
 295
 296 Where "key_blob" is encoded as per RFC 4253 section 6.6 "Public Key
 297 Algorithms" for either of the supported key types: "ssh-dss" or
 298 "ssh-rsa".
 299
 300 The agent will delete any private key matching the specified public key
 301 and return SSH_AGENT_SUCCESS. If no such key was found, the agent will
 302 return SSH_AGENT_FAILURE.
 303
 304 2.4.3 Removing keys loaded from a smartcard
 305
 306 A client may request that a server remove one or more smartcard-hosted
 307 keys 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
 314 or passphrase used to unlock the private key(s) on the device.
 315
 316 When this message is received, and if the agent supports
 317 smartcard-hosted keys, it will delete all keys that are hosted on the
 318 specified smartcard that may be accessed with the given "pin".
 319
 320 The agent will reply with a SSH_AGENT_SUCCESS if one or more keys have
 321 been successfully removed or a SSH_AGENT_FAILURE if an error occurred.
 322 The agent will also return SSH_AGENT_FAILURE if it does not support
 323 smartcards.
 324
 325 2.5 Requesting a list of known keys
 326
 327 An agent may be requested to list which keys it holds. Different
 328 requests exist for protocol 1 and protocol 2 keys.
 329
 330 2.5.1 Requesting a list of protocol 1 keys
 331
 332 To request a list of protocol 1 keys that are held in the agent, a
 333 client may send the following message:
 334
 335         byte                    SSH_AGENTC_REQUEST_RSA_IDENTITIES
 336
 337 The agent will reply with the following message:
 338
 339         byte                    SSH_AGENT_RSA_IDENTITIES_ANSWER
 340         uint32                  num_keys
 341
 342 Followed 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
 349 2.5.2 Requesting a list of protocol 2 keys
 350
 351 A client may send the following message to request a list of
 352 protocol 2 keys that are stored in the agent:
 353
 354         byte                    SSH2_AGENTC_REQUEST_IDENTITIES
 355
 356 The agent will reply with the following message header:
 357
 358         byte                    SSH2_AGENT_IDENTITIES_ANSWER
 359         uint32                  num_keys
 360
 361 Followed by zero or more consecutive keys, encoded as:
 362
 363         string                  key_blob
 364         string                  key_comment
 365
 366 Where "key_blob" is encoded as per RFC 4253 section 6.6 "Public Key
 367 Algorithms" for either of the supported key types: "ssh-dss" or
 368 "ssh-rsa".
 369
 370 2.6 Private key operations
 371
 372 The purpose of the agent is to perform private key operations, such as
 373 signing and encryption without requiring a passphrase to unlock the
 374 key and without allowing the private key itself to be exposed. There
 375 are separate requests for the protocol 1 and protocol 2 private key
 376 operations.
 377
 378 2.6.1 Protocol 1 private key challenge
 379
 380 The private key operation used in version 1 of the SSH protocol is
 381 decrypting a challenge that has been encrypted with a public key.
 382 It 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)
 394 been encrypted with the public key and must be in the range
 395 1 <= encrypted_challenge < 2^256. "session_id" is the SSH protocol 1
 396 session ID (computed from the server host key, the server semi-ephemeral
 397 key and the session cookie).
 398
 399 "ignored" and "response_type" exist for compatibility with legacy
 400 implementations. "response_type" must be equal to 1; other response
 401 types are not supported.
 402
 403 On receiving this request, the server decrypts the "encrypted_challenge"
 404 using the private key matching the supplied (rsa_e, rsa_n) values. For
 405 the response derivation, the decrypted challenge is represented as an
 406 unsigned, big-endian integer encoded in a 32 byte buffer (i.e. values
 407 smaller than 2^248 will have leading 0 bytes).
 408
 409 The response value is then calculated as:
 410
 411         response = MD5(decrypted_challenge || session_id)
 412
 413 and returned in the following message
 414
 415         byte                    SSH_AGENT_RSA_RESPONSE
 416         byte[16]                response
 417
 418 If the agent cannot find the key specified by the supplied (rsa_e,
 419 rsa_n) then it will return SSH_AGENT_FAILURE.
 420
 421 2.6.2 Protocol 2 private key signature request
 422
 423 A client may use the following message to request signing of data using
 424 a protocol 2 key:
 425
 426         byte                    SSH2_AGENTC_SIGN_REQUEST
 427         string                  key_blob
 428         string                  data
 429         uint32                  flags
 430
 431 Where "key_blob" is encoded as per RFC 4253 section 6.6 "Public Key
 432 Algorithms" 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
 434 is defined (see below for its meaning):
 435
 436         SSH_AGENT_OLD_SIGNATURE         1
 437
 438 Upon receiving this request, the agent will look up the private key that
 439 corresponds to the public key contained in key_blob. It will use this
 440 private key to sign the "data" and produce a signature blob using the
 441 key type-specific method described in RFC 4253 section 6.6 "Public Key
 442 Algorithms".
 443
 444 An exception to this is for "ssh-dss" keys where the "flags" word
 445 contains the value SSH_AGENT_OLD_SIGNATURE. In this case, a legacy
 446 signature encoding is used in lieu of the standard one. In this case,
 447 the DSA signature blob is encoded as:
 448
 449         byte[40]                signature
 450
 451 The signature will be returned in the response message:
 452
 453         byte                    SSH2_AGENT_SIGN_RESPONSE
 454         string                  signature_blob
 455
 456 If the agent cannot find the key specified by the supplied key_blob then
 457 it will return SSH_AGENT_FAILURE.
 458
 459 2.7 Locking or unlocking an agent
 460
 461 The agent supports temporary locking with a passphrase to suspend
 462 processing of sensitive operations until it has been unlocked with the
 463 same passphrase. To lock an agent, a client send the following request:
 464
 465         byte                    SSH_AGENTC_LOCK
 466         string                  passphrase
 467
 468 Upon receipt of this message and if the agent is not already locked,
 469 it will suspend processing requests and return a SSH_AGENT_SUCCESS
 470 reply. If the agent is already locked, it will return SSH_AGENT_FAILURE.
 471
 472 While locked, the agent will refuse all requests except
 473 SSH_AGENTC_UNLOCK, SSH_AGENTC_REQUEST_RSA_IDENTITIES and
 474 SSH2_AGENTC_REQUEST_IDENTITIES. The "request identities" requests are
 475 treated specially by a locked agent: it will always return an empty list
 476 of keys.
 477
 478 To unlock an agent, a client may request:
 479
 480         byte                    SSH_AGENTC_UNLOCK
 481         string                  passphrase
 482
 483 If the passphrase matches and the agent is locked, then it will resume
 484 processing all requests and return SSH_AGENT_SUCCESS. If the agent
 485 is not locked or the passphrase does not match then it will return
 486 SSH_AGENT_FAILURE.
 487
 488 Locking and unlocking affects both protocol 1 and protocol 2 keys.
 489
 490 3. Protocol message numbers
 491
 492 3.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
 501 3.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
 510 3.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
 518 3.4 Generic replies from agent to client
 519
 520         SSH_AGENT_FAILURE                               5
 521         SSH_AGENT_SUCCESS                               6
 522
 523 3.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
 528 3.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
 533 3.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 $