idnits 2.17.1 draft-miller-ssh-agent-02.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (September 30, 2017) is 2390 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- == Outdated reference: A later version (-12) exists of draft-ietf-curdle-rsa-sha2-10 == Outdated reference: A later version (-02) exists of draft-ietf-curdle-ssh-ed25519-01 ** Obsolete normative reference: RFC 5226 (Obsoleted by RFC 8126) Summary: 1 error (**), 0 flaws (~~), 3 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Internet Engineering Task Force D. Miller 3 Internet-Draft OpenSSH 4 Intended status: Informational September 30, 2017 5 Expires: April 3, 2018 7 SSH Agent Protocol 8 draft-miller-ssh-agent-02 10 Abstract 12 This document describes a key agent protocol for use in the Secure 13 Shell (SSH) protocol. 15 Status of This Memo 17 This Internet-Draft is submitted in full conformance with the 18 provisions of BCP 78 and BCP 79. 20 Internet-Drafts are working documents of the Internet Engineering 21 Task Force (IETF). Note that other groups may also distribute 22 working documents as Internet-Drafts. The list of current Internet- 23 Drafts is at https://datatracker.ietf.org/drafts/current/. 25 Internet-Drafts are draft documents valid for a maximum of six months 26 and may be updated, replaced, or obsoleted by other documents at any 27 time. It is inappropriate to use Internet-Drafts as reference 28 material or to cite them other than as "work in progress." 30 This Internet-Draft will expire on April 3, 2018. 32 Copyright Notice 34 Copyright (c) 2017 IETF Trust and the persons identified as the 35 document authors. All rights reserved. 37 This document is subject to BCP 78 and the IETF Trust's Legal 38 Provisions Relating to IETF Documents 39 (https://trustee.ietf.org/license-info) in effect on the date of 40 publication of this document. Please review these documents 41 carefully, as they describe your rights and restrictions with respect 42 to this document. Code Components extracted from this document must 43 include Simplified BSD License text as described in Section 4.e of 44 the Trust Legal Provisions and are provided without warranty as 45 described in the Simplified BSD License. 47 Table of Contents 49 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 50 2. Requirements Language . . . . . . . . . . . . . . . . . . . . 3 51 3. Protocol Overview . . . . . . . . . . . . . . . . . . . . . . 3 52 4. Protocol Messages . . . . . . . . . . . . . . . . . . . . . . 3 53 4.1. Generic server responses . . . . . . . . . . . . . . . . 3 54 4.2. Adding keys to the agent . . . . . . . . . . . . . . . . 4 55 4.2.1. DSA keys . . . . . . . . . . . . . . . . . . . . . . 4 56 4.2.2. ECDSA keys . . . . . . . . . . . . . . . . . . . . . 5 57 4.2.3. ED25519 keys . . . . . . . . . . . . . . . . . . . . 5 58 4.2.4. RSA keys . . . . . . . . . . . . . . . . . . . . . . 6 59 4.2.5. Adding keys from a token . . . . . . . . . . . . . . 6 60 4.2.6. Key Constraints . . . . . . . . . . . . . . . . . . . 7 61 4.2.6.1. Key lifetime constraint . . . . . . . . . . . . . 7 62 4.2.6.2. Key confirmation constraint . . . . . . . . . . . 8 63 4.2.6.3. Constraint extensions . . . . . . . . . . . . . . 8 64 4.3. Removing keys from the agent . . . . . . . . . . . . . . 8 65 4.4. Requesting a list of keys . . . . . . . . . . . . . . . . 9 66 4.5. Private key operations . . . . . . . . . . . . . . . . . 9 67 4.5.1. Signature flags . . . . . . . . . . . . . . . . . . . 10 68 4.6. Locking and unlocking an agent . . . . . . . . . . . . . 10 69 4.7. Extension mechanism . . . . . . . . . . . . . . . . . . . 11 70 4.7.1. Query extension . . . . . . . . . . . . . . . . . . . 11 71 5. Protocol numbers . . . . . . . . . . . . . . . . . . . . . . 11 72 5.1. Message numbers . . . . . . . . . . . . . . . . . . . . . 12 73 5.1.1. Reserved message numbers . . . . . . . . . . . . . . 12 74 5.2. Constraint identifiers . . . . . . . . . . . . . . . . . 12 75 5.3. Signature flags . . . . . . . . . . . . . . . . . . . . . 13 76 6. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 13 77 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 13 78 7.1. New registry: SSH agent protocol numbers . . . . . . . . 13 79 7.2. New registry: SSH agent key constraint numbers . . . . . 14 80 7.3. New registry: SSH agent signature flags . . . . . . . . . 15 81 8. Security Considerations . . . . . . . . . . . . . . . . . . . 15 82 9. Normative References . . . . . . . . . . . . . . . . . . . . 16 83 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 17 85 1. Introduction 87 Secure Shell (SSH) is a protocol for secure remote connections and 88 login over untrusted networks. It supports multiple authentication 89 mechanisms, including public key authentication. This document 90 describes the protocol for interacting with an agent that holds 91 private keys. Clients (and possibly servers) can use invoke the 92 agent via this protocol to perform operations using public and 93 private keys held in the agent. 95 Holding keys in an agent offers usability and security advantages to 96 loading and unwrapping them at each use. Moreover, the agent 97 implements a simple protocol and presents a smaller attack surface 98 than a key loaded into a full SSH server or client. 100 This agent protocol is already widely used and a de-facto standard, 101 having been implemented by a number of popular SSH clients and 102 servers for many years. The purpose of this document is to describe 103 the protocol as it has been implemented. 105 2. Requirements Language 107 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 108 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 109 document are to be interpreted as described in [RFC2119]. 111 3. Protocol Overview 113 The agent protocol is a packetised request-response protocol, solely 114 driven by the client. It consists of a number of requests sent from 115 the client to the server and a set of reply messages that are sent in 116 response. At no time does the server send messages except in 117 response to a client request. Replies are sent in order. 119 All values in the agent protocol are encoded using the SSH wire 120 representations specified by [RFC4251]. Messages consist of a 121 length, type and contents. 123 uint32 message length 124 byte message type 125 byte[message length - 1] message contents 127 4. Protocol Messages 129 4.1. Generic server responses 131 The following generic messages may be sent by the server in response 132 to requests from the client. On success the agent may reply either 133 with: 135 byte SSH_AGENT_SUCCESS 137 or a request-specific success message. On failure, the agent may 138 reply with: 140 byte SSH_AGENT_FAILURE 142 SSH_AGENT_FAILURE messages are also sent in reply to requests with 143 unknown types. 145 4.2. Adding keys to the agent 147 Keys may be added to the agent using the SSH_AGENTC_ADD_IDENTITY or 148 SSH_AGENTC_ADD_ID_CONSTRAINED messages. The latter variant allows 149 adding keys with optional constraints on their usage. 151 The generic format for the key SSH_AGENTC_ADD_IDENTITY message is: 153 byte SSH_AGENTC_ADD_IDENTITY 154 string key type 155 byte[] key contents 156 string key comment 158 Here "type" is the specified key type name, for example "ssh-rsa" for 159 a RSA key as defined by [RFC4253]. "contents" consists of the public 160 and private components of the key and vary by key type, they are 161 listed below for standard and commonly used key types. "comment" is 162 an optional human-readable key name or comment as a UTF-8 string that 163 may serve to identify the key in user-visible messages. 165 The SSH_AGENTC_ADD_ID_CONSTRAINED is similar, but adds a extra field: 167 byte SSH_AGENTC_ADD_ID_CONSTRAINED 168 string type 169 byte[] contents 170 string comment 171 constraint[] constraints 173 Constraints are used to place limits on the validity or use of keys. 174 Section 4.2.6 details constraint types and their format. 176 An agent should reply with SSH_AGENT_SUCCESS if the key was 177 successfully loaded as a result of one of these messages, or 178 SSH_AGENT_FAILURE otherwise. 180 4.2.1. DSA keys 182 DSA keys have key type "ssh-dss" and are defined in [RFC4253]. They 183 may be added to the agent using the following message. The 184 "constraints" field is only present for the 185 SSH_AGENTC_ADD_ID_CONSTRAINED message. 187 byte SSH_AGENTC_ADD_IDENTITY or 188 SSH_AGENTC_ADD_ID_CONSTRAINED 189 string "ssh-dss" 190 mpint p 191 mpint q 192 mpint g 193 mpint y 194 mpint x 195 string comment 196 constraint[] constraints 198 The "p", "q", "g" values are the DSA domain parameters. "y" and "x" 199 are the public and private keys respectively. These values are as 200 defined by [FIPS.186-4]. 202 4.2.2. ECDSA keys 204 ECDSA keys have key types starting with "ecdsa-sha2-" and are defined 205 in [RFC5656]. They may be added to the agent using the following 206 message. The "constraints" field is only present for the 207 SSH_AGENTC_ADD_ID_CONSTRAINED message. 209 byte SSH_AGENTC_ADD_IDENTITY or 210 SSH_AGENTC_ADD_ID_CONSTRAINED 211 string key type 212 string ecdsa_curve_name 213 string Q 214 mpint d 215 string comment 216 constraint[] constraints 218 The values "Q" and "d" are the ECDSA public and private values 219 respectively. Both are defined by [FIPS.186-4]. 221 4.2.3. ED25519 keys 223 Ed25519 keys have key type "ssh-ed25519" and are defined in 224 [I-D.ietf-curdle-ssh-ed25519]. They may be added to the agent using 225 the following message. The "key constraints" field is only present 226 for the SSH_AGENTC_ADD_ID_CONSTRAINED message. 228 byte SSH_AGENTC_ADD_IDENTITY or 229 SSH_AGENTC_ADD_ID_CONSTRAINED 230 string "ssh-ed25519" 231 string ENC(A) 232 string k || ENC(A) 233 string comment 234 constraint[] constraints 236 The first value is the 32 byte Ed25519 public key "ENC(A)". The 237 second value is a concatenation of the 32 byte private key "k" and 32 238 byte public "ENC(A)" key. The contents and interpretation of the 239 "ENC(A)" and "k" values are defined by [I-D.irtf-cfrg-eddsa]. 241 4.2.4. RSA keys 243 RSA keys have key type "ssh-rsa" and are defined in [RFC4253]. They 244 may be added to the agent using the following message. The "key 245 constraints" field is only present for the 246 SSH_AGENTC_ADD_ID_CONSTRAINED message. 248 byte SSH_AGENTC_ADD_IDENTITY or 249 SSH_AGENTC_ADD_ID_CONSTRAINED 250 string "ssh-rsa" 251 mpint n 252 mpint e 253 mpint d 254 mpint iqmp 255 mpint p 256 mpint q 257 string comment 258 constraint[] constraints 260 "n" is the public composite modulus. "p" and "q" are its constituent 261 private prime factors. "e" is the public exponent. "iqmp" is the 262 inverse of "q" modulo "p". All these values except "iqmp" (which can 263 be calculated from the others) are defined by [FIPS.186-4]. 265 4.2.5. Adding keys from a token 267 Keys hosted on smart-cards or other hardware tokens may be added 268 using the SSH_AGENTC_ADD_SMARTCARD_KEY and 269 SSH_AGENTC_ADD_SMARTCARD_KEY_CONSTRAINED requests. Note that 270 "constraints" field is only included for the 271 SSH_AGENTC_ADD_SMARTCARD_KEY_CONSTRAINED variant of this message. 273 byte SSH_AGENTC_ADD_SMARTCARD_KEY or 274 SSH_AGENTC_ADD_SMARTCARD_KEY_CONSTRAINED 275 string id 276 string PIN 277 constraint[] constraints 279 Here "id" is an opaque identifier for the hardware token and "PIN" is 280 an optional password on PIN to unlock the key. The interpretation of 281 "id" is not defined by the protocol but is left solely up to the 282 agent. 284 Typically only the public components of any keys supported on a 285 hardware token will be loaded into an agent so, strictly speaking, 286 this message really arranges future private key operations to be 287 delegated to the hardware token in question. 289 An agent should reply with SSH_AGENT_SUCCESS if one or more keys were 290 successfully loaded as a result of one of these messages, or 291 SSH_AGENT_FAILURE if no keys were found. The agent should also 292 return SSH_AGENT_FAILURE if the token "id" was not recognised or if 293 the agent doesn't support token-hosted keys at all. 295 4.2.6. Key Constraints 297 A number of constraints and may be used in the constrained variants 298 of the key add messages. Each constraint is represented by a type 299 byte followed by zero or more value bytes. 301 Zero or more constraints may be specified when adding a key with one 302 of the *_CONSTRAINED requests. Multiple constraints are appended 303 consecutively to the end of the request: 305 byte constraint1_type 306 byte[] constraint1_data 307 byte constraint2_type 308 byte[] constraint2_data 309 .... 310 byte constraintN_type 311 byte[] constraintN_data 313 If an agent does not recognise or support a requested constraint it 314 MUST refuse the request and return a SSH_AGENT_FAILURE message to the 315 client. 317 The following constraints are defined. 319 4.2.6.1. Key lifetime constraint 321 This constraint requests that the agent limit the key's lifetime by 322 deleting it after the specified duration (in seconds) has elapsed 323 from the time the key was added to the agent. 325 byte SSH_AGENT_CONSTRAIN_LIFETIME 326 uint32 seconds 328 4.2.6.2. Key confirmation constraint 330 This constraint requests that the agent require explicit user 331 confirmation for each private key operation using the key. For 332 example, the agent could present a confirmation dialog before 333 completing a signature operation. 335 byte SSH_AGENT_CONSTRAIN_CONFIRM 337 4.2.6.3. Constraint extensions 339 Agents may implement experimental or private-use constraints through 340 a extension constraint that supports named constraints. 342 byte SSH_AGENT_CONSTRAIN_EXTENSION 343 string extension name 344 byte[] extension-specific details 346 The extension name MUST consist of a UTF-8 string suffixed by the 347 implementation domain following the naming scheme defined in 348 Section 4.2 of [RFC4251], e.g. "foo@example.com". 350 4.3. Removing keys from the agent 352 A client may request that an agent remove all keys that it stores: 354 byte SSH_AGENTC_REMOVE_ALL_IDENTITIES 356 On receipt of such a message, an agent shall delete all keys that it 357 is holding and reply with SSH_AGENT_SUCCESS. 359 Specific keys may also be removed: 361 byte SSH_AGENTC_REMOVE_IDENTITY 362 string key blob 364 Where "key blob" is the standard public key encoding of the key to be 365 removed. SSH protocol key encodings are defined in [RFC4253] for 366 "ssh-rsa" and "ssh-dss" keys, in [RFC5656] for "ecdsa-sha2-*" keys 367 and in [I-D.ietf-curdle-ssh-ed25519] for "ssh-ed25519" keys. 369 An agent shall reply with SSH_AGENT_SUCCESS if the key was deleted or 370 SSH_AGENT_FAILURE if it was not found. 372 Smartcard keys may be removed using: 374 byte SSH_AGENTC_REMOVE_SMARTCARD_KEY 375 string reader id 376 string PIN 378 Where "reader id" is an opaque identifier for the smartcard reader 379 and "PIN" is an optional password or PIN (not typically used). 380 Requesting deletion of smartcard-hosted keys will cause the agent to 381 remove all keys loaded from that smartcard. 383 An agent shall reply with SSH_AGENT_SUCCESS if the key was deleted or 384 SSH_AGENT_FAILURE if it was not found. 386 4.4. Requesting a list of keys 388 A client may request a list of keys from an agent using the following 389 message: 391 byte SSH_AGENTC_REQUEST_IDENTITIES 393 The agent shall reply with a message with the following preamble. 395 byte SSH_AGENT_IDENTITIES_ANSWER 396 uint32 nkeys 398 Where "nkeys" indicates the number of keys to follow. Following the 399 preamble are zero or more keys, each encoded as: 401 string key blob 402 string comment 404 Where "key blob" is the wire encoding of the public key and "comment" 405 is a human-readable comment encoded as a UTF-8 string. 407 4.5. Private key operations 409 A client may request the agent perform a private key signature 410 operation using the following message: 412 byte SSH_AGENTC_SIGN_REQUEST 413 string key blob 414 string data 415 uint32 flags 417 Where "key blob" is the key requested to perform the signature, 418 "data" is the data to be signed and "flags" is a bitfield containing 419 the bitwise OR of zero or more signature flags (see below). 421 If the agent does not support the requested flags, or is otherwise 422 unable or unwilling to generate the signature (e.g. because it 423 doesn't have the specified key, or the user refused confirmation of a 424 constrained key), it must reply with a SSH_AGENT_FAILURE message. 426 On success, the agent shall reply with: 428 byte SSH_AGENT_SIGN_RESPONSE 429 string signature 431 The signature format is specific to the algorithm of the key type in 432 use. SSH protocol signature formats are defined in [RFC4253] for 433 "ssh-rsa" and "ssh-dss" keys, in [RFC5656] for "ecdsa-sha2-*" keys 434 and in [I-D.ietf-curdle-ssh-ed25519] for "ssh-ed25519" keys. 436 4.5.1. Signature flags 438 Two flags are currently defined for signature request messages: 439 SSH_AGENT_RSA_SHA2_256 and SSH_AGENT_RSA_SHA2_512. These two flags 440 are only valid for "ssh-rsa" keys and request that the agent return a 441 signature using the "rsa-sha2-256" or "rsa-sha2-512" signature 442 methods respectively. These signature schemes are defined in 443 [I-D.ietf-curdle-rsa-sha2]. 445 4.6. Locking and unlocking an agent 447 The agent protocol supports requesting that an agent temporarily lock 448 itself with a pass-phrase. When locked an agent should suspend 449 processing of sensitive operations (private key operations at the 450 very least) until it has been unlocked with the same pass-phrase. 452 The following message requests agent locking 454 byte SSH_AGENTC_LOCK 455 string passphrase 457 The agent shall reply with SSH_AGENT_SUCCESS if locked successfully 458 or SSH_AGENT_FAILURE otherwise (e.g. if the agent was already 459 locked). 461 The following message requests unlocking an agent: 463 byte SSH_AGENTC_UNLOCK 464 string passphrase 466 If the agent is already locked and the pass-phrase matches the one 467 used to lock it then it should unlock and reply with 468 SSH_AGENT_SUCCESS. If the agent is unlocked or if the the pass- 469 phrase does not match it should reply with SSH_AGENT_FAILURE. An 470 agent SHOULD take countermeasures against brute-force guessing 471 attacks against the pass-phrase. 473 4.7. Extension mechanism 475 The agent protocol includes an optional extension mechanism that 476 allows vendor-specific and experimental messages to be sent via the 477 agent protocol. Extension requests from the client consist of: 479 byte SSH_AGENTC_EXTENSION 480 string extension type 481 byte[] extension contents 483 The extension type indicates the type of the extension message as a 484 UTF-8 string. Implementation-specific extensions should be suffixed 485 by the implementation domain following the extension naming scheme 486 defined in Section 4.2 of [RFC4251], e.g. "foo@example.com". 488 An agent that does not support extensions of the supplied type MUST 489 reply with an empty SSH_AGENT_FAILURE message. This reply is also 490 sent by agents that do not support the extension mechanism at all. 492 The contents of successful extension reply messages are specific to 493 the extension type. Extension requests may return SSH_AGENT_SUCCESS 494 on success or some other extension-specific message. 496 Extension failure should be signaled using the 497 SSH_AGENT_EXTENSION_FAILURE code - extensions should not use the 498 standard SSH_AGENT_FAILURE message. This allows failed requests to 499 be distinguished from the extension not being supported. 501 4.7.1. Query extension 503 A single, optional extension request "query" is defined to allow a 504 client to query which, if any, extensions are supported by an agent. 506 If an agent supports the "query" extension is should reply with a 507 list of supported extension names. 509 byte SSH_AGENT_SUCCESS 510 string[] extension type 512 5. Protocol numbers 513 5.1. Message numbers 515 The following numbers are used for requests from the client to the 516 agent. 518 SSH_AGENTC_REQUEST_IDENTITIES 11 519 SSH_AGENTC_SIGN_REQUEST 13 520 SSH_AGENTC_ADD_IDENTITY 17 521 SSH_AGENTC_REMOVE_IDENTITY 18 522 SSH_AGENTC_REMOVE_ALL_IDENTITIES 19 523 SSH_AGENTC_ADD_ID_CONSTRAINED 25 524 SSH_AGENTC_ADD_SMARTCARD_KEY 20 525 SSH_AGENTC_REMOVE_SMARTCARD_KEY 21 526 SSH_AGENTC_LOCK 22 527 SSH_AGENTC_UNLOCK 23 528 SSH_AGENTC_ADD_SMARTCARD_KEY_CONSTRAINED 26 529 SSH_AGENTC_EXTENSION 27 531 The following numbers are used for replies from the agent to the 532 client. 534 SSH_AGENT_FAILURE 5 535 SSH_AGENT_SUCCESS 6 536 SSH_AGENT_EXTENSION_FAILURE 28 537 SSH_AGENT_IDENTITIES_ANSWER 12 538 SSH_AGENT_SIGN_RESPONSE 14 540 5.1.1. Reserved message numbers 542 The following message numbers are reserved for implementations that 543 implement support for the legacy SSH protocol version 1: 1-4, 7-9 and 544 24 (inclusive). These message numbers MAY be used by an 545 implementation supporting the legacy protocol but MUST NOT be reused 546 otherwise. 548 5.2. Constraint identifiers 550 The following numbers are used to identify key constraints. These 551 are only used in key constraints and are not sent as message numbers. 553 SSH_AGENT_CONSTRAIN_LIFETIME 1 554 SSH_AGENT_CONSTRAIN_CONFIRM 2 555 SSH_AGENT_CONSTRAIN_EXTENSION 3 557 5.3. Signature flags 559 The following numbers may be present in signature request 560 (SSH_AGENTC_SIGN_REQUEST) messages. These flags form a bit field by 561 taking the logical OR of zero or more flags. 563 SSH_AGENT_RSA_SHA2_256 2 564 SSH_AGENT_RSA_SHA2_512 4 566 The flag value 1 is reserved for historical implementations. 568 6. Acknowledgements 570 This protocol was designed and first implemented by Markus Friedl, 571 based on a similar protocol for an agent to support the legacy SSH 572 version 1 by Tatu Ylonen. 574 Thanks to Simon Tatham who reviewed and helped improve this document. 576 7. IANA Considerations 578 This protocol requires three registries be established, one for 579 message numbers, one for constraints and one for signature request 580 flags. 582 7.1. New registry: SSH agent protocol numbers 584 This registry, titled "SSH agent protocol numbers" records the 585 message numbers for client requests and agent responses. Its initial 586 state should consist of the following numbers and reservations. 587 Future message number allocations shall require specification in the 588 form of an RFC (RFC REQUIRED as per [RFC5226]). 590 Number Identifier Reference 591 ------ ---------------------------------------- ----------- 592 1 reserved Section 5.1 593 2 reserved Section 5.1 594 3 reserved Section 5.1 595 4 reserved Section 5.1 596 5 SSH_AGENT_FAILURE Section 5.1 597 6 SSH_AGENT_SUCCESS Section 5.1 598 7 reserved Section 5.1 599 8 reserved Section 5.1 600 9 reserved Section 5.1 601 10 reserved Section 5.1 602 11 SSH_AGENTC_REQUEST_IDENTITIES Section 5.1 603 12 SSH_AGENT_IDENTITIES_ANSWER Section 5.1 604 13 SSH_AGENTC_SIGN_REQUEST Section 5.1 605 14 SSH_AGENT_SIGN_RESPONSE Section 5.1 606 15 reserved Section 5.1 607 16 reserved Section 5.1 608 17 SSH_AGENTC_ADD_IDENTITY Section 5.1 609 18 SSH_AGENTC_REMOVE_IDENTITY Section 5.1 610 19 SSH_AGENTC_REMOVE_ALL_IDENTITIES Section 5.1 611 20 SSH_AGENTC_ADD_SMARTCARD_KEY Section 5.1 612 21 SSH_AGENTC_REMOVE_SMARTCARD_KEY Section 5.1 613 22 SSH_AGENTC_LOCK Section 5.1 614 23 SSH_AGENTC_UNLOCK Section 5.1 615 24 reserved Section 5.1 616 25 SSH_AGENTC_ADD_ID_CONSTRAINED Section 5.1 617 26 SSH_AGENTC_ADD_SMARTCARD_KEY_CONSTRAINED Section 5.1 618 27 SSH_AGENTC_EXTENSION Section 5.1 619 28 SSH_AGENT_EXTENSION_FAILURE Section 5.1 621 Initial registry state: SSH agent protocol numbers 623 7.2. New registry: SSH agent key constraint numbers 625 This registry, titled "SSH agent key constraint numbers" records the 626 message numbers for key use constraints. Its initial state should 627 consist of the following numbers. Future constraint number 628 allocations shall require specification in the form of an RFC (RFC 629 REQUIRED as per [RFC5226]). 631 Number Identifier Reference 632 ------ ----------------------------- ----------- 633 1 SSH_AGENT_CONSTRAIN_LIFETIME Section 5.2 634 2 SSH_AGENT_CONSTRAIN_CONFIRM Section 5.2 635 3 SSH_AGENT_CONSTRAIN_EXTENSION Section 5.2 637 Initial registry state: SSH agent key constraint numbers 639 7.3. New registry: SSH agent signature flags 641 This registry, titled "SSH agent signature flags records the values 642 for signature request (SSH_AGENTC_SIGN_REQUEST) flag values. Its 643 initial state should consist of the following numbers. Note that as 644 the flags are combined by bitwise OR, all flag values must be powers 645 of two and the maximum available flag value is 0x80000000. 647 Future constraint number allocations shall require specification in 648 the form of an RFC (RFC REQUIRED as per [RFC5226]). 650 Number Identifier Reference 651 ------ ---------------------- ----------- 652 0x01 reserved Section 5.3 653 0x02 SSH_AGENT_RSA_SHA2_256 Section 5.3 654 0x04 SSH_AGENT_RSA_SHA2_512 Section 5.3 656 Initial registry state: SSH agent signature flags 658 8. Security Considerations 660 The agent is a service that is tasked with retaining and providing 661 controlled access to what are typically long-lived login 662 authentication credentials. It is by nature a sensitive and trusted 663 software component. Moreover, the agent protocol itself does not 664 include any authentication or transport security; ability to 665 communicate with an agent is usually sufficient to invoke it to 666 perform private key operations. 668 Since being able to access an agent is usually sufficient to perform 669 private key operations, it is critically important that the agent 670 only be exposed to its owner. 672 The primary design intention of an agent is that an attacker with 673 unprivileged access to their victim's agent should be prevented from 674 gaining a copy of any keys that have been loaded in to it. This may 675 not preclude the attacker from stealing use of those keys (e.g. if 676 they have been loaded without a confirmation constraint). 678 Given this, the agent should, as far as possible, prevent its memory 679 being read by other processes to direct theft of loaded keys. This 680 typically include disabling debugging interfaces and preventing 681 process memory dumps on abnormal termination. 683 Another, more subtle, means by which keys may be stolen are via 684 cryptographic side-channels. Private key operations may leak 685 information about the contents of keys via differences in timing, 686 power use or by side-effects in the memory subsystems (e.g. CPU 687 caches) of the host running the agent. For the case of a local 688 attacker and an agent holding unconstrained keys, the only limit on 689 the number of private key operations the attacker may be able to 690 observe is the rate at which the CPU can perform signatures. This 691 grants the attacker an almost ideal oracle for side-channel attacks. 692 While a full treatment of side-channel attacks is beyond the scope of 693 this specification, agents SHOULD use cryptographic implementations 694 that are resistant to side-channel attacks. 696 9. Normative References 698 [FIPS.186-4] 699 National Institute of Standards and Technology, "Digital 700 Signature Standard (DSS)", FIPS PUB 186-4, July 2013. 702 [I-D.ietf-curdle-rsa-sha2] 703 bider, d., "Use of RSA Keys with SHA-2 256 and 512 in 704 Secure Shell (SSH)", draft-ietf-curdle-rsa-sha2-10 (work 705 in progress), August 2017. 707 [I-D.ietf-curdle-ssh-ed25519] 708 Harris, B. and L. Velvindron, "Ed25519 public key 709 algorithm for the Secure Shell (SSH) protocol", draft- 710 ietf-curdle-ssh-ed25519-01 (work in progress), August 711 2017. 713 [I-D.irtf-cfrg-eddsa] 714 Josefsson, S. and I. Liusvaara, "Edwards-curve Digital 715 Signature Algorithm (EdDSA)", draft-irtf-cfrg-eddsa-08 716 (work in progress), August 2016. 718 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 719 Requirement Levels", BCP 14, RFC 2119, 720 DOI 10.17487/RFC2119, March 1997, 721 . 723 [RFC4251] Ylonen, T. and C. Lonvick, Ed., "The Secure Shell (SSH) 724 Protocol Architecture", RFC 4251, DOI 10.17487/RFC4251, 725 January 2006, . 727 [RFC4253] Ylonen, T. and C. Lonvick, Ed., "The Secure Shell (SSH) 728 Transport Layer Protocol", RFC 4253, DOI 10.17487/RFC4253, 729 January 2006, . 731 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 732 IANA Considerations Section in RFCs", RFC 5226, 733 DOI 10.17487/RFC5226, May 2008, 734 . 736 [RFC5656] Stebila, D. and J. Green, "Elliptic Curve Algorithm 737 Integration in the Secure Shell Transport Layer", 738 RFC 5656, DOI 10.17487/RFC5656, December 2009, 739 . 741 Author's Address 743 Damien Miller 744 OpenSSH 746 Email: djm@openssh.com 747 URI: http://www.openssh.com/