idnits 2.17.1 draft-galb-secsh-publickey-subsystem-02.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: ---------------------------------------------------------------------------- == No 'Intended status' indicated for this document; assuming Proposed Standard == The page length should not exceed 58 lines per page, but there was 2 longer pages, the longest (page 7) being 164 lines Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack a Security Considerations 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 separate sections for Informative/Normative References. All references will be assumed normative when checking for downward references. ** There are 15 instances of too long lines in the document, the longest one being 5 characters in excess of 72. ** There are 46 instances of lines with control characters in the document. ** The abstract seems to contain references ([4]), which it shouldn't. Please replace those with straight textual mentions of the documents in question. ** 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 102: '... servers SHOULD provide a configurat...' RFC 2119 keyword, line 139: '... implementations SHOULD reject this re...' RFC 2119 keyword, line 142: '... is TRUE, the server MUST respond with...' RFC 2119 keyword, line 147: '... The server SHOULD respond with SSH_...' RFC 2119 keyword, line 151: '... It is RECOMMENDED that clients requ...' (30 more instances...) Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the RFC 3978 Section 5.4 Copyright Line does not match the current year == Line 136 has weird spacing: '...boolean want...' == Line 159 has weird spacing: '... string req...' == Line 175 has weird spacing: '... string res...' == Line 186 has weird spacing: '... string des...' == Line 187 has weird spacing: '... string lan...' == (12 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.) -- The document date (June 23, 2003) is 7610 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) -- Looks like a reference, but probably isn't: 'RFC-2279' on line 186 -- Looks like a reference, but probably isn't: 'RFC-1766' on line 187 -- Looks like a reference, but probably isn't: 'SSH-ARCH' on line 254 -- Looks like a reference, but probably isn't: 'RFC1766' on line 277 == Unused Reference: '5' is defined on line 435, but no explicit reference was found in the text == Outdated reference: A later version (-22) exists of draft-ietf-secsh-architecture-13 == Outdated reference: A later version (-24) exists of draft-ietf-secsh-transport-15 == Outdated reference: A later version (-27) exists of draft-ietf-secsh-userauth-16 == Outdated reference: A later version (-25) exists of draft-ietf-secsh-connect-16 ** Obsolete normative reference: RFC 2279 (ref. '5') (Obsoleted by RFC 3629) Summary: 9 errors (**), 0 flaws (~~), 14 warnings (==), 6 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Secure Shell Working Group J. Galbraith 3 Internet-Draft J. Van Dyke 4 Expires: December 22, 2003 B. McClure 5 VanDyke Software 6 June 23, 2003 8 Secure Shell Public-Key Subsystem 9 draft-galb-secsh-publickey-subsystem-02.txt 11 Status of this Memo 13 This document is an Internet-Draft and is in full conformance with 14 all provisions of Section 10 of RFC2026. 16 Internet-Drafts are working documents of the Internet Engineering 17 Task Force (IETF), its areas, and its working groups. Note that other 18 groups may also distribute working documents as Internet-Drafts. 20 Internet-Drafts are draft documents valid for a maximum of six months 21 and may be updated, replaced, or obsoleted by other documents at any 22 time. It is inappropriate to use Internet-Drafts as reference 23 material or to cite them other than as "work in progress." 25 The list of current Internet-Drafts can be accessed at http:// 26 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 This Internet-Draft will expire on December 22, 2003. 33 Copyright Notice 35 Copyright (C) The Internet Society (2003). All Rights Reserved. 37 Abstract 39 SECSH defines an authentication mechanism that is based on public 40 keys, but does not define any mechanism for key distribution. No 41 common key management solution exists in current implementations. 42 This document describes a protocol that can be used to configure 43 public keys in an implementation-independent fashion, allowing client 44 software to take on the burden of this configuration. 46 This protocol is intended to be used from the Secure Shell Connection 47 Protocol [4] as a subsystem, as described in Section ``Starting a 48 Shell or a Command''. The subsystem name used with this protocol is 49 "publickey@vandyke.com". 51 The public-key subsystem provides a server-independent mechanism for 52 clients to add public keys, remove public keys, and list the current 53 public keys known by the server. Rights to manage public keys are 54 specific and limited to the authenticated user. 56 A public key may also be associated with a mandatory command. 58 Table of Contents 60 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 61 2. Public-Key Subsystem Overview . . . . . . . . . . . . . . . 4 62 2.1 Opening the Public-Key Subsystem . . . . . . . . . . . . . . 4 63 2.2 Requests . . . . . . . . . . . . . . . . . . . . . . . . . . 5 64 2.3 Responses . . . . . . . . . . . . . . . . . . . . . . . . . 5 65 2.3.1 The Status Response . . . . . . . . . . . . . . . . . . . . 5 66 3. Public-Key Subsystem Operations . . . . . . . . . . . . . . 7 67 3.1 Version Packet . . . . . . . . . . . . . . . . . . . . . . . 7 68 3.2 Adding a public key . . . . . . . . . . . . . . . . . . . . 7 69 3.3 Removing a public key . . . . . . . . . . . . . . . . . . . 7 70 3.4 Listing public keys . . . . . . . . . . . . . . . . . . . . 8 71 3.5 Associate public key with a mandatory command . . . . . . . 8 72 References . . . . . . . . . . . . . . . . . . . . . . . . . 9 73 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . 9 74 Intellectual Property and Copyright Statements . . . . . . . 11 76 1. Introduction 78 SECSH is a protocol for secure remote login and other secure network 79 services over an insecure network. SECSH defines an authentication 80 mechanism that is based on public keys, but does not define any 81 mechanism for key distribution. Common practice is to authenticate 82 once with password authentication and transfer the public key to the 83 server. However, to date no two implementations use the same 84 mechanism to configure a public key for use. 86 This document describes a subsystem that can be used to configure 87 public keys in an implementation-independent fashion. This approach 88 allows client software to take on the burden of this configuration. 89 The public-key subsystem protocol is designed for extreme simplicity 90 in implementation. It is not intended as a PKIX replacement. 92 The Secure Shell Public-Key subsystem has been designed to run on top 93 of the SECSH transport layer [2] and user authentication protocols 94 [3]. It provides a simple mechanism for the client to manage public 95 keys on the server. 97 This document should be read only after reading the SECSH 98 architecture [1] and SECSH connection [4] documents. 100 This protocol requires that the user be able to authenticate in some 101 fashion before it can be used. If password authentication is used, 102 servers SHOULD provide a configuration option to disable the use of 103 password authentication after the first public key is added. 105 2. Public-Key Subsystem Overview 107 The public-key subsystem provides a server-independent mechanism for 108 clients to add public keys, remove public keys, and list the current 109 public keys known by the server. The subsystem name is 110 "publickey@vandyke.com". 112 The public keys added, removed, and listed using this protocol are 113 specific and limited to those of the authenticated user. 115 The operations to add, remove and list the authenticated user's 116 public keys are performed as request packets sent to the server. The 117 server sends response packets that indicate success or failure as 118 well as provide specific response data. 120 The format of public-key blobs are detailed in the SSH Transport 121 Protocol document [2]. 123 2.1 Opening the Public-Key Subsystem 125 The public-key subsystem is opened when the clients sends a 126 SSH_MSG_CHANNEL_REQUEST over an existing session. 128 The details of how a session is opened are described in the SSH 129 Connection Protocol document [4] in the section "Opening a Session". 131 To open the public-key subsystem, the client sends: 133 byte SSH_MSG_CHANNEL_REQUEST 134 uint32 recipient channel 135 string "subsystem" 136 boolean want reply 137 string "publickey@vandyke.com" 139 Client implementations SHOULD reject this request; it is normally 140 only sent by the client. 142 If want reply is TRUE, the server MUST respond with 143 SSH_MSG_CHANNEL_SUCCESS if the public-key subsystem was successfully 144 started or SSH_MSG_CHANNEL_FAILURE if the server failed to start or 145 does not support the public-key subsystem. 147 The server SHOULD respond with SSH_MSG_CHANNEL_FAILURE if the user 148 authenticated with a restricted public key that does not allow access 149 to the publickey subsystem. 151 It is RECOMMENDED that clients request and check the reply for this 152 request. 154 2.2 Requests 156 All public-key subsystem requests are sent in the following form: 158 uint32 length 159 string request-name 160 ... request specific data follows 162 The length field describes the length of the request-name field and 163 the request-specific data, but not of the length field itself. The 164 client MUST receive a response to each request prior to sending a 165 new request. 167 All requests described in Section 3 are a description of the 168 'request-name' and 'data' portions of the packet. 170 2.3 Responses 172 All public-key subsystem responses are sent in the following form: 174 uint32 length 175 string response-name 176 ... response specific data follows 178 2.3.1 The Status Response 180 A request is acknowledged by sending a status packet. If there is 181 data in response to the request, the status packet is sent after all 182 data has been sent. 184 string "status" 185 uint32 status code 186 string description [RFC-2279] 187 string language tag [RFC-1766] 189 A status message MUST be sent for any unrecognized packets and the 190 request SHOULD NOT close the subsystem. 192 2.3.1.1 Status Codes 194 The status code gives the status in a more machine-readable format 195 (suitable for localization), and can have the following values: 197 SSH_PUBLICKEY_SUCCESS 0 198 SSH_PUBLICKEY_ACCESS_DENIED 1 199 SSH_PUBLICKEY_STORAGE_EXCEEDED 2 200 SSH_PUBLICKEY_REQUEST_NOT_SUPPORTED 3 201 SSH_PUBLICKEY_KEY_NOT_FOUND 4 202 SSH_PUBLICKEY_KEY_NOT_SUPPORTED 5 203 SSH_PUBLICKEY_KEY_ALREADY_PRESENT 6 205 SSH_PUBLICKEY_GENERAL_FAILURE 7 207 3. Public-Key Subsystem Operations 209 The public-key subsystem currently defines four operations: add, 210 remove, list, and command. 212 3.1 Version Packet 214 Both sides MUST start by sending a version packet that indicates the 215 version of the protocol they are using. 217 string "version" 218 uint32 protocol-version-number 220 The version of the protocol described by this document is version 1. 222 Both sides send the highest version that they implement. The lower of 223 the version numbers is the version of the protocol to use. If either 224 side can't support the lower version, it should close the subsystem 225 and notify the other side by sending an SSH_MSG_CHANNEL_CLOSE message. 227 Both sides MUST wait to receive this version before continuing. 229 3.2 Adding a public key 231 If the client wishes to add a public key, the client sends: 233 string "add" 234 string public-key algorithm name 235 string public-key blob 236 boolean overwrite 237 uint32 attribute-count 238 string attrib-name 239 string attrib-value 240 bool mandatory 241 repeated attribute-count times 243 The server MUST attempt to store the public key for the user in the 244 appropriate location so the public key can be used for subsequent 245 public-key authentications. If the overwrite field is false and the 246 specified key already exists, the server MUST return 247 SSH_PUBLICKEY_KEY_ALREADY_PRESENT. If the server returns this, the 248 client SHOULD provide an option to the user to overwrite the key. 249 If the overwrite field is true and the specified key already exists 250 but cannot be overwritten, the server MUST return 251 SSH_PUBLICKEY_ACCESS_DENIED. 253 Attribute names are defined following the same scheme laid out for 254 algorithm names in [SSH-ARCH] (section 5). If the server does not 255 implement a mandatory attribute, it MUST fail the add. For the 256 purposes of a mandatory attribute, storage of the attribute is not 257 sufficient, but requires that the server understand and implement 258 the intent of the attribute. 260 The following attributes are currently defined: 262 "comment" 263 The comment field contains user-specified text about the 264 public key. The server SHOULD make every effort to preserve 265 this value and return it with the key during a list operation. 266 The server MUST NOT attempt to interpret or act upon the content 267 of the comment field in any way. 269 The comment field is useful so the user can identify the key 270 without resorting to comparing its fingerprint. 272 This attribute SHOULD NOT be mandatory. 274 "comment-language" 275 If this attribute is specified, it MUST immediately follow a 276 "comment" attribute and specifies the language for that attribute 277 [RFC1766]. The client MAY specify more than comment if it 278 additionally specifies a different language for each of those 279 comments. The server SHOULD attempt to store each comment, 280 together with that comment's lanuage attribute. 282 This attribute SHOULD NOT be mandatory. 284 "command" 285 "command" bypasses the session channel "exec" and "shell" requests 286 by always executing the specified command (as if it had been 287 executed using an "exec" request). 289 This attribute SHOULD be mandatory. This attribute MUST NOT be 290 specified if the "subsystem" attribute is specified. 292 "subsystem" 293 "subsystem" specifies that the specified subsystem should be started 294 when this key is used (as if it had been started using a "subsystem" 295 request. 297 This attribute SHOULD be mandatory. This attribute MUST NOT be 298 specified if the "command" attribute is specified. 300 "restrict" 301 The value of this attribute contains server functions that may 302 not be performed when this key is used. It is a comma seperated 303 list. Element names are specified in the same way as attribute 304 names, above. The following restrictions are currently defined: 306 Currently defined restrictions are: 308 "x11" 309 "shell" 310 "exec" 311 "agent" 312 "env" 313 "subsystem" 315 The "x11" restriction specifies that X11 forwarding may not be 316 performed when this key is in use. The "shell" restriction 317 specifies that session channel "shell" requests should be denied 318 when this key is in use. The "exec" restriction specifies that 319 session channel "exec" requests should be denied when this key 320 is in use. The "agent" restriction specifies that session channel 321 "auth-agent-req" requests should be denied when this key is in use. 322 The "env" restriction specifies that session channel "env" requests 323 should be denied when this key is in use. The "subsystem" 324 restriction specifies that subsystems may not be started when this 325 public key is in use (if the "subsystem" attribute is also specified, 326 the subsystem specified in that attribute is exempted from this 327 restriction). 329 This attribute SHOULD be mandatory. 331 "port-forward" 332 "port-forward" specifies that no "direct-tcpip" requests should be 333 accepted, except to those hosts specified in the comma-separated 334 list supplied as a value to this attribute. If the value of this 335 attribute is empty, all "direct-tcpip" requests should be refused 336 when using this key. 338 This attribute SHOULD be mandatory. 340 "reverse-forward" 341 "reverse-forward" specifies that no "tcpip-forward" requests should 342 be accepted, accept for the port numbers in the comma-separated 343 list supplied as a value to this attribute. If the value of this 344 attribute is empty, all "tcpip-forward" requests should be refused 345 when using this key. 347 This attribute SHOULD be mandatory. 349 In addition to the attributes and restrictions specified by the client, 350 the server MAY provide a method for administrators to compulsorily enforce 351 certain attributes or restrictions. 353 3.3 Removing a public key 355 If the client wishes to remove a public key, the client sends: 357 string "remove" 358 string public-key algorithm name 359 string public-key blob 361 The server MUST attempt to remove the public key for the user from 362 the appropriate location, so that the public key cannot be used for 363 subsequent authentications. 365 3.4 Listing public keys 367 If the client wishes to list the known public keys, the client sends: 369 string "list" 371 The server will respond with zero or more of the following responses: 373 string "publickey" 374 string public-key algorithm name 375 string public-key blob 376 uint32 attribute-count 377 string attrib-name 378 string attrib-value 379 repeated attribute-count times 381 Following the last "publickey" response, a status packet MUST be 382 sent. 384 An implementation MAY choose not to support this request. 386 3.5 Listing server capabilities 388 If the client wishes to know which restrictions the server supports, 389 it sends: 391 string "listattributes" 393 The server will respond with zero or more of the following responses: 395 string "attribute" 396 string attribute name 397 boolean compulsory 399 The server will then respond with zero or more of the following 400 responses: 402 string "restriction" 403 string restriction name 404 boolean compulsory 406 The server MAY include "restrict" in the list of attributes it supports. 407 The client SHOULD NOT require the server to do so in order to accept 408 that the server supports the list of restrictions returned by the 409 server. 411 Following the last "restriction" response, a status packet MUST be 412 sent. 414 An implementation MAY choose not to support this request. 416 References 418 [1] Ylonen, T., Kivinen, T., Saarinen, M., Rinne, T. and S. 419 Lehtinen, "SSH Protocol Architecture", 420 draft-ietf-secsh-architecture-13 (work in progress), January 421 2002. 423 [2] Ylonen, T., Kivinen, T., Saarinen, M., Rinne, T. and S. 424 Lehtinen, "SSH Transport Layer Protocol", 425 draft-ietf-secsh-transport-15 (work in progress), March 2002. 427 [3] Ylonen, T., Kivinen, T., Saarinen, M., Rinne, T. and S. 428 Lehtinen, "SSH Authentication Protocol", 429 draft-ietf-secsh-userauth-16 (work in progress), February 2002. 431 [4] Ylonen, T., Kivinen, T., Saarinen, M., Rinne, T. and S. 432 Lehtinen, "SSH Connection Protocol", draft-ietf-secsh-connect-16 433 (work in progress), January 2002. 435 [5] Yergeau, F., "UTF-8, a transformation format of ISO 10646", RFC 436 2279, January 1998. 438 Authors' Addresses 440 Joseph Galbraith 441 VanDyke Software 442 4848 Tramway Ridge Blvd 443 Suite 101 444 Albuquerque, NM 87111 445 US 447 Phone: +1 505 332 5700 448 EMail: galb-list@vandyke.com 450 Jeff P. Van Dyke 451 VanDyke Software 452 4848 Tramway Ridge Blvd 453 Suite 101 454 Albuquerque, NM 87111 455 US 457 Phone: +1 505 332 5700 458 EMail: jpv@vandyke.com 459 Brent McClure 460 VanDyke Software 461 4848 Tramway Ridge Blvd 462 Suite 101 463 Albuquerque, NM 87111 464 US 466 Phone: +1 505 332 5700 467 EMail: bdm@vandyke.com 469 Intellectual Property Statement 471 The IETF takes no position regarding the validity or scope of any 472 intellectual property or other rights that might be claimed to 473 pertain to the implementation or use of the technology described in 474 this document or the extent to which any license under such rights 475 might or might not be available; neither does it represent that it 476 has made any effort to identify any such rights. Information on the 477 IETF's procedures with respect to rights in standards-track and 478 standards-related documentation can be found in BCP-11. Copies of 479 claims of rights made available for publication and any assurances of 480 licenses to be made available, or the result of an attempt made to 481 obtain a general license or permission for the use of such 482 proprietary rights by implementors or users of this specification can 483 be obtained from the IETF Secretariat. 485 The IETF invites any interested party to bring to its attention any 486 copyrights, patents or patent applications, or other proprietary 487 rights which may cover technology that may be required to practice 488 this standard. Please address the information to the IETF Executive 489 Director. 491 Full Copyright Statement 493 Copyright (C) The Internet Society (2003). All Rights Reserved. 495 This document and translations of it may be copied and furnished to 496 others, and derivative works that comment on or otherwise explain it 497 or assist in its implementation may be prepared, copied, published 498 and distributed, in whole or in part, without restriction of any 499 kind, provided that the above copyright notice and this paragraph are 500 included on all such copies and derivative works. However, this 501 document itself may not be modified in any way, such as by removing 502 the copyright notice or references to the Internet Society or other 503 Internet organizations, except as needed for the purpose of 504 developing Internet standards in which case the procedures for 505 copyrights defined in the Internet Standards process must be 506 followed, or as required to translate it into languages other than 507 English. 509 The limited permissions granted above are perpetual and will not be 510 revoked by the Internet Society or its successors or assignees. 512 This document and the information contained herein is provided on an 513 "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING 514 TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING 515 BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION 516 HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF 517 MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 519 Acknowledgment 521 Funding for the RFC Editor function is currently provided by the 522 Internet Society.