idnits 2.17.1 draft-ietf-secsh-agent-01.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** Looks like you're using RFC 2026 boilerplate. This must be updated to follow RFC 3978/3979, as updated by RFC 4748. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- ** Missing expiration date. The document expiration date should appear on the first and last page. == No 'Intended status' indicated for this document; assuming Proposed Standard Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack an Introduction section. ** The document seems to lack an IANA Considerations section. (See Section 2.2 of https://www.ietf.org/id-info/checklist for how to handle the case when there are no actions for IANA.) ** The document seems to lack an Authors' Addresses Section. ** The document seems to lack separate sections for Informative/Normative References. All references will be assumed normative when checking for downward references. ** The document seems to lack a both a reference to RFC 2119 and the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. RFC 2119 keyword, line 161: '...t protocol of Secure Shell 1.x, it MAY...' RFC 2119 keyword, line 436: '...Implementations MUST reject these mess...' Miscellaneous warnings: ---------------------------------------------------------------------------- == Line 134 has weird spacing: '... string rem...' == Line 135 has weird spacing: '... string rem...' == Line 144 has weird spacing: '... string ver...' == Line 170 has weird spacing: '... string pri...' == Line 171 has weird spacing: '... string pub...' == (18 more instances...) -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- Couldn't find a document date in the document -- date freshness check skipped. -- Found something which looks like a code comment -- if you have code sections in the document, please surround them with '' and '' lines. Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Missing Reference: 'SSH-CONN' is mentioned on line 412, but not defined == Unused Reference: 'SECSH-CONNECT' is defined on line 499, but no explicit reference was found in the text == Outdated reference: A later version (-25) exists of draft-ietf-secsh-connect-16 Summary: 7 errors (**), 0 flaws (~~), 10 warnings (==), 3 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 1 Network Working Group Tatu Ylonen 2 INTERNET-DRAFT Timo J. Rinne 3 draft-ietf-secsh-agent-01.txt Sami Lehtinen 4 Expires in six months SSH Communications Security 5 20 November, 2002 7 Secure Shell Authentication Agent Protocol 9 Status of This Memo 11 This document is an Internet-Draft and is in full conformance 12 with all provisions of Section 10 of RFC2026. 14 Internet-Drafts are working documents of the Internet Engineering 15 Task Force (IETF), its areas, and its working groups. Note that 16 other groups may also distribute working documents as 17 Internet-Drafts. 19 Internet-Drafts are draft documents valid for a maximum of six 20 months and may be updated, replaced, or obsoleted by other 21 documents at any time. It is inappropriate to use Internet- 22 Drafts as reference material or to cite them other than as 23 "work in progress." 25 The list of current Internet-Drafts can be accessed at 26 http://www.ietf.org/ietf/1id-abstracts.txt 28 The list of Internet-Draft Shadow Directories can be accessed at 29 http://www.ietf.org/shadow.html. 31 Abstract 33 This document describes the Secure Shell authentication agent protocol 34 (i.e., the protocol used between a client requesting authentication and 35 the authentication agent). This protocol usually runs in a machine-spe- 36 cific local channel or over a forwarded authentication channel. It is 37 assumed that the channel is trusted, so no protection for the communica- 38 tions channel is provided by this protocol. 40 Table of Contents 42 1. Authentication Agent Protocol . . . . . . . . . . . . . . . . . 2 43 1.1. Packet Format . . . . . . . . . . . . . . . . . . . . . . . 2 44 1.2. Forwarding Notices . . . . . . . . . . . . . . . . . . . . . 3 45 1.3. Requesting Version Number . . . . . . . . . . . . . . . . . 3 46 1.4. Adding Keys to the Agent . . . . . . . . . . . . . . . . . . 4 47 1.5. Deleting Keys from the Agent . . . . . . . . . . . . . . . . 5 48 1.6. Deleting specific key from the Agent . . . . . . . . . . . . 5 49 1.7. Listing the Keys that the Agent Can Use . . . . . . . . . . 6 50 2. Performing Private Key Operations . . . . . . . . . . . . . . . 6 51 2.1. Signing . . . . . . . . . . . . . . . . . . . . . . . . . . 7 52 2.2. Decrypting . . . . . . . . . . . . . . . . . . . . . . . . . 7 53 2.3. Secure Shell Challenge-Response Authentication . . . . . . . 7 54 3. Administrative Messages . . . . . . . . . . . . . . . . . . . . 7 55 3.1. Locking and unlocking the agent . . . . . . . . . . . . . . 8 56 3.2. Miscellaneous Agent Commands . . . . . . . . . . . . . . . . 8 57 4. Agent Forwarding With Secure Shell . . . . . . . . . . . . . . . 9 58 4.1. Requesting Agent Forwarding . . . . . . . . . . . . . . . . 9 59 4.2. Agent Forwarding Channels . . . . . . . . . . . . . . . . . 9 60 5. Security Considerations . . . . . . . . . . . . . . . . . . . . 9 61 6. Intellectual Property . . . . . . . . . . . . . . . . . . . . . 10 62 7. Additional Information . . . . . . . . . . . . . . . . . . . . . 10 63 8. References . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 64 9. Address of Authors . . . . . . . . . . . . . . . . . . . . . . . 10 66 1. Authentication Agent Protocol 68 The authentication agent is a piece of software that runs in a user's 69 local workstation, laptop, or other trusted device. It is used to 70 implement single sign-on. It holds the user's private keys in its own 71 storage, and can perform requested operations using the private key. It 72 allows the keys to be kept on a smartcard or other special hardware that 73 can perform cryptographic operations. 75 The authentication agent protocol is used to communicate between the 76 authentication agent and clients wanting to authenticate something or 77 wanting to perform private key operations. 79 The actual communication between the client and the agent happens using 80 a machine-dependent trusted communications channel. This channel would 81 typically be a local socket, named pipe, or some kind of secure 82 messaging system that works inside the local machine. 84 The protocol works by the client sending requests to the agent, and the 85 agent responding to these requests. 87 1.1. Packet Format 89 All messages passed to/from the authentication agent have the following 90 format: 92 uint32 length 93 byte type 94 data[length -1] data payload 96 The following packet types are currently defined: 98 /* Messages sent by the client. */ 99 #define SSH_AGENT_REQUEST_VERSION 1 100 #define SSH_AGENT_ADD_KEY 202 101 #define SSH_AGENT_DELETE_ALL_KEYS 203 102 #define SSH_AGENT_LIST_KEYS 204 103 #define SSH_AGENT_PRIVATE_KEY_OP 205 104 #define SSH_AGENT_FORWARDING_NOTICE 206 105 #define SSH_AGENT_DELETE_KEY 207 106 #define SSH_AGENT_LOCK 208 107 #define SSH_AGENT_UNLOCK 209 108 #define SSH_AGENT_PING 212 109 #define SSH_AGENT_RANDOM 213 111 /* Messages sent by the agent. */ 112 #define SSH_AGENT_SUCCESS 101 113 #define SSH_AGENT_FAILURE 102 114 #define SSH_AGENT_VERSION_RESPONSE 103 115 #define SSH_AGENT_KEY_LIST 104 116 #define SSH_AGENT_OPERATION_COMPLETE 105 117 #define SSH_AGENT_RANDOM_DATA 106 118 #define SSH_AGENT_ALIVE 150 120 1.2. Forwarding Notices 122 If the agent connection is forwarded through intermediate hosts (using 123 the SSH Connection Protocol agent forwarding feature (described in 124 Section ``Agent Forwarding With Secure Shell'' of this document), or 125 some other means), each intermediate node (Secure Shell client) should 126 insert the following message into the agent channel before forwarding 127 any other messages. The real agent will then receive these messages in 128 sequence the nearest node first, and can determine whether the 129 connection is from a local machine and if not, can log the path where 130 the connection came from. These messages must be wrapped in the 131 appropriate header. 133 byte SSH_AGENT_FORWARDING_NOTICE 134 string remote host name (as typed by the user, preferably) 135 string remote host ip 136 uint32 remote host port 138 1.3. Requesting Version Number 140 When the client opens a connection, it must send the following message 141 to the server. This must be the first message sent. The real agent 142 will receive this after zero or more forwarding notice messages. 143 byte SSH_AGENT_REQUEST_VERSION 144 string version string of the application sending the request 145 (optional) 147 If the agent follows this protocol, it will respond with 149 byte SSH_AGENT_VERSION_RESPONSE 150 uint32 version number, 2 for this protocol 152 If the version number request is ever sent to the Secure Shell 1.x 153 agent, it will interpret it as a request to list identities. It will 154 then respond with a message whose first byte is 2. This can be used to 155 determine the version of the agent if compatibility with Secure Shell 156 1.x is desired. 158 If the version string query arrives without trailing string identifying 159 the client software version, it can be translated list identities 160 request sent by Secure Shell 1.x and handled accordingly. If agent 161 software does not support the agent protocol of Secure Shell 1.x, it MAY 162 also interpret this query as valid SSH_AGENT_REQUEST_VERSION packet. 164 1.4. Adding Keys to the Agent 166 The client can add a new private key to the agent with the following 167 message. 169 byte SSH_AGENT_ADD_KEY 170 string private key blob with empty passphrase 171 string public key and/or certificates for it 172 string description of the key 173 ... 0, 1 or several constraints follow 175 All constraints are pairs of following format: 177 byte SSH_AGENT_CONSTRAINT_* 178 variable argument for the constraint 180 The type of the argument is dependent on the constraint type. Following 181 constraint types are currently defined: 183 /* Constraints 50-99 have a uint32 argument */ 185 /* Argument is uint32 defining key expiration time-out in 186 seconds. After this timeout expires, the key can't be used. 187 0 == no timeout */ 188 #define SSH_AGENT_CONSTRAINT_TIMEOUT 50 190 /* Argument is uint32 defining the number of operations that can 191 be performed with this key. 0xffffffff == no limit */ 192 #define SSH_AGENT_CONSTRAINT_USE_LIMIT 51 194 /* Argument is uint32 defining the number of forwarding steps that 195 this key can be forwarded. 0xffffffff == no limit */ 196 #define SSH_AGENT_CONSTRAINT_FORWARDING_STEPS 52 197 /* Constraints 100-149 have a string argument */ 199 /* Argument is string defining the allowed forwarding steps for 200 this key. XXX define this. */ 201 #define SSH_AGENT_CONSTRAINT_FORWARDING_PATH 100 203 /* Constraints 150-199 have a boolean argument */ 205 /* Argument is a boolean telling whether the key can be used 206 in Secure Shell 1.x compatibility operations. */ 208 #define SSH_AGENT_CONSTRAINT_SSH1_COMPAT 150 210 /* Argument is a boolean telling whether operations performed 211 with this key should be confirmed interactively by the user 212 or not. */ 213 #define SSH_AGENT_CONSTRAINT_NEED_USER_VERIFICATION 151 215 Message can contain zero, one or multiple constraints. 217 If the operation is successful, the agent will respond with the 218 following message. 220 byte SSH_AGENT_SUCCESS 222 If the operation fails for some reason, the following message will be 223 returned instead. 225 byte SSH_AGENT_FAILURE 226 uint32 error code 228 The error code is one of the following: 230 #define SSH_AGENT_ERROR_TIMEOUT 1 231 #define SSH_AGENT_ERROR_KEY_NOT_FOUND 2 232 #define SSH_AGENT_ERROR_DECRYPT_FAILED 3 233 #define SSH_AGENT_ERROR_SIZE_ERROR 4 234 #define SSH_AGENT_ERROR_KEY_NOT_SUITABLE 5 235 #define SSH_AGENT_ERROR_DENIED 6 236 #define SSH_AGENT_ERROR_FAILURE 7 237 #define SSH_AGENT_ERROR_UNSUPPORTED_OP 8 239 1.5. Deleting Keys from the Agent 241 All keys that are in possession of the agent can be deleted with the 242 following message. (The client is allowed to ignore this for some keys 243 if desired.) 245 byte SSH_AGENT_DELETE_ALL_KEYS 247 The agent responds with either SSH_AGENT_SUCCESS or SSH_AGENT_FAILURE. 249 1.6. Deleting specific key from the Agent 251 The client can delete a specific key with given public key with 252 following message. 254 byte SSH_AGENT_DELETE_KEY 255 string public key and/or certificates for it 256 string description of the key 258 The agent responds with either SSH_AGENT_SUCCESS or SSH_AGENT_FAILURE. 260 1.7. Listing the Keys that the Agent Can Use 262 The following message requests a list of all keys that the agent can 263 use. 265 byte SSH_AGENT_LIST_KEYS 267 The agent will respond with the following message. 269 byte SSH_AGENT_KEY_LIST 270 uint32 number_of_keys 271 repeats number_of_keys times: 272 string public key blob or certificates 273 string description 275 2. Performing Private Key Operations 277 The real purpose of the agent is to perform private key operations. 278 Such operations are performed with the following message. 280 byte SSH_AGENT_PRIVATE_KEY_OP 281 string operation name 282 string key or certificates, as returned in SSH_AGENT_KEY_LIST 283 ... operation-specific data follows 285 The operation to be performed is identified by a name (string). Custom 286 operations can be added by suffixing the operation name by the fully 287 qualified domain name of the person/organization adding the new 288 operation. 290 When the operation is complete, the agent will respond with either 291 SSH_AGENT_FAILURE or with the following message if the operation is 292 successful: 294 byte SSH_AGENT_OPERATION_COMPLETE 295 string resulting data 297 If an operation is attempted that is not supported by the agent, the 298 agent will respond with SSH_AGENT_FAILURE with error code set to 299 SSH_AGENT_ERROR_UNSUPPORTED_OP. 301 The standard operations are defined below. 303 2.1. Signing 305 The agent can be used to create a digital signature using a key held by 306 the agent. The operation name is "sign", and data in is a hash 307 (suitable for the key) that is to be signed. This normally performs the 308 raw private key operation, without hashing data first. The resulting 309 data will be a binary representation of the output of the private key 310 operation. The exact details of the operations to be performed depend 311 on the key being used. 313 The operation-specific data has the following format: 315 string data to be signed 317 Alternatively, it is possible to give the actual data to be signed to 318 the agent. This is done using the operation "hash-and-sign". This is 319 otherwise equal, but performs key-dependent hashing before signing. 321 If the requested operation is not legal for the key, SSH_AGENT_FAILURE 322 will be returned with error code set to 323 SSH_AGENT_ERROR_KEY_NOT_SUITABLE. 325 2.2. Decrypting 327 The agent can be used to decrypt a public key encrypted message with the 328 operation "decrypt". This takes in raw public-key encrypted data, and 329 returns the resulting decrypted data. 331 This may also fail. If the requested operation is not legal for the 332 key, error code is set to SSH_AGENT_ERROR_KEY_NOT_SUITABLE. 334 The operation-specific data has the following format: 336 string data to be decrypted 338 2.3. Secure Shell Challenge-Response Authentication 340 Performs Secure Shell challenge-response authentication. This operation 341 has the name "ssh1-challenge-response". 343 This operation works by first decrypting the challenge, then computing 344 MD5 of the concatenation of the decrypted challenge and the session id 345 (in this order), and returns the resulting 16 byte hash. The operation- 346 specific data is in the following format: 348 string challenge encrypted using the public key 349 string session id 351 Normally, the length of the challenge before encryption will be 32 bytes 352 and the length of the session id 16 bytes. The length of the encrypted 353 challenge depends on the key and algorithm used. 355 3. Administrative Messages 357 There are also a number of messages that are only used to administer the 358 agent. These might e.g. be used by a user interface for the agent. The 359 agent should only allow these messages from local connection (i.e., if 360 no forwarding notice messages were received before the version number 361 request). 363 3.1. Locking and unlocking the agent 365 The agent can be temporarily locked by message: 367 byte SSH_AGENT_LOCK 368 string locking password 370 The agent responds with either SSH_AGENT_SUCCESS or SSH_AGENT_FAILURE. 371 Particularily SSH_AGENT_FAILURE is sent, if agent is already locked. 372 After this message, agent responds to all commands with 373 SSH_AGENT_FAILURE until it receives a following command. 375 byte SSH_AGENT_UNLOCK 376 string locking password 378 The agent responds with either SSH_AGENT_SUCCESS or SSH_AGENT_FAILURE. 379 Particularily SSH_AGENT_FAILURE is sent, if agent is not locked or if 380 the submitted password does not match with one given with SSH_AGENT_LOCK 381 message. 383 3.2. Miscellaneous Agent Commands 385 byte SSH_AGENT_PING 386 ... arbitrary padding data 388 Any agent or client receiving this message, should respond with 390 byte SSH_AGENT_ALIVE 391 ... padding data from the SSH_AGENT_PING request 393 where the padding data is identical to the data sent with 394 SSH_AGENT_PING. 396 byte SSH_AGENT_RANDOM 397 uint32 the length of the requested random buffer 399 Client can request random data from the agent by this message. Agent 400 responds either with SSH_AGENT_RANDOM_DATA or SSH_AGENT_FAILURE message. 402 byte SSH_AGENT_RANDOM_DATA 403 string random data 405 This message is a successful response to SSH_AGENT_RANDOM message. 406 Message contains the random string of requested length. 408 4. Agent Forwarding With Secure Shell 410 The agent connection is typically forwarded over a Secure Shell 411 connection. This requires small additions to the SSH Connection Protocol 412 [SSH-CONN]. 414 4.1. Requesting Agent Forwarding 416 Agent forwarding may be requested for a session by sending 418 byte SSH_MSG_CHANNEL_REQUEST 419 uint32 recipient channel 420 string "auth-agent-req" 421 boolean want reply 423 This will, on success, create an agent listener to the remote end. 425 4.2. Agent Forwarding Channels 427 When a connection comes to the forwarded agent listener, a channel is 428 opened to forward the connection to the other side. 430 byte SSH_MSG_CHANNEL_OPEN 431 string "auth-agent" 432 uint32 sender channel 433 uint32 initial window size 434 uint32 maximum packet size 436 Implementations MUST reject these messages unless they have previously 437 requested agent forwarding. 439 Forwarded agent channels are independent of any sessions, and closing a 440 session channel does not in any way imply that forwarded connections 441 should be closed. 443 5. Security Considerations 445 The authentication agent is used to control security-sensitive 446 operations, and is used to implement single sign-on. 448 Anyone with access to the authentication agent can perform private key 449 operations with the agent. This is a power equivalent to possession of 450 the private key as long as the connection to the key is maintained. It 451 is not possible to retrieve the key from the agent. 453 It is recommended that agent implementations allow and perform some form 454 of logging and access control. This access control may utilize 455 information about the path through which the connection was received (as 456 collected with SSH_AGENT_FORWARDING_NOTICE messages; however, the path 457 is reliable only up to and including the first unreliable machine.). 458 Implementations should also allow restricting the operations that can be 459 performed with keys - e.g., limiting them to challenge-response only. 461 One should note that a local superuser will be able to obtain access to 462 agents running on the local machine. This cannot be prevented; in most 463 operating systems, a user with sufficient privileges will be able to 464 read the keys from the physical memory. 466 The authentication agent should not be run or forwarded to machine whose 467 integrity is not trusted, as security on such machines might be 468 compromised and might allow an attacker to obtain unauthorized access to 469 the agent. 471 6. Intellectual Property 473 The IETF takes no position regarding the validity or scope of any 474 intellectual property or other rights that might be claimed to pertain 475 to the implementation or use of the technology described in this 476 document or the extent to which any license under such rights might or 477 might not be available; neither does it represent that it has made any 478 effort to identify any such rights. Information on the IETF's 479 procedures with respect to rights in standards-track and standards- 480 related documentation can be found in BCP-11. Copies of claims of 481 rights made available for publication and any assurances of licenses to 482 be made available, or the result of an attempt made to obtain a general 483 license or permission for the use of such proprietary rights by 484 implementers or users of this specification can be obtained from the 485 IETF Secretariat. 487 The IETF has been notified of intellectual property rights claimed in 488 regard to some or all of the specification contained in this document. 489 For more information consult the online list of claimed rights. 491 7. Additional Information 493 The current document editor is: Sami Lehtinen . Comments 494 on this Internet-Draft should be sent to the IETF SECSH working group, 495 details at: http://ietf.org/html.charters/secsh-charter.html 497 8. References 499 [SECSH-CONNECT] Ylonen, T., et al: "Secure Shell Connection Protocol", 500 Internet-Draft, draft-ietf-secsh-connect-16.txt 502 9. Address of Authors 504 Tatu Ylonen 505 SSH Communications Security Corp 506 Fredrikinkatu 42 507 FIN-00100 HELSINKI 508 Finland 509 E-mail: ylo@ssh.com 511 Timo J. Rinne 512 SSH Communications Security Corp 513 Fredrikinkatu 42 514 FIN-00100 HELSINKI 515 Finland 516 E-mail: tri@ssh.com 518 Sami Lehtinen 519 SSH Communications Security Corp 520 Fredrikinkatu 42 521 FIN-00100 HELSINKI 522 Finland 523 E-mail: sjl@ssh.com