Network Working Group
S. Suehring Internet-Draft Expires: December 16, 2005J. Salowey Internet-Draft Cisco Systems Expires: December 3, 2005 S. Suehring June 14,2005 SCP/SFTP/SSH URI Format draft-ietf-secsh-scp-sftp-ssh-uri-02.txtUniform Resource Identifier (URI) Scheme for Secure File Transfer Protocol (SFTP) and Secure Shell (SSH) draft-ietf-secsh-scp-sftp-ssh-uri-03.txt Status of this Memo By submitting this Internet-Draft, each author represents that any applicable patent or other IPR claims of which he or she is aware have been or will be disclosed, and any of which he or she becomes aware will be disclosed, in accordance with Section 6 of BCP 79. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF), its areas, and its working groups. Note that other groups may also distribute working documents as Internet- Drafts. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." The list of current Internet-Drafts can be accessed at http://www.ietf.org/ietf/1id-abstracts.txt. The list of Internet-Draft Shadow Directories can be accessed at http://www.ietf.org/shadow.html. This Internet-Draft will expire on December 16,3, 2005. Copyright Notice Copyright (C) The Internet Society (2005). Abstract This document describes the Uniform Resource Identifiers used to locate resources for the SCP, SFTP,Secure File Transfer Protocol (SFTP) and SSHthe Secure Shell (SSH) protocols. The document describes the generic syntax involved in URI definitions as well as specific definitions for each protocol. These specific definitions may include user credentials such as username and password andalso may include other parameters such as host key fingerprint. In addition, security considerations and examples are also provided within this document. Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 2. General Syntax . . . . . . . . . . . . . . . . . . . . . . . . 3 2.1 SSHSecure Shell (SSH) URI . . . . . . . . . . . . . . . . . . 3 2.2 Secure File Transfer Protocol (SFTP) URI . . . . . . . 3 2.2 SCP and SFTP URI. . 4 3. Parameters . . . . . . . . . . . . . . . . . . . 3 3. Parameters. . . . . . . 5 3.1 SSH connection parameters . . . . . . . . . . . . . . . . 5 3.2 SFTP Parameters . . . 4 3.1 SSH connection parameters. . . . . . . . . . . . . . . . 4 3.2 SFTP Parameters. . 5 4. Examples . . . . . . . . . . . . . . . . . . . 5 4. Examples. . . . . . . . 6 5. IANA Considerations . . . . . . . . . . . . . . . . . . . 5 5.. . 6 6. Security Considerations . . . . . . . . . . . . . . . . . . . 6 6.7. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 7 8. References . . . . . . . . . . . . . . . . . . . . . . . . . . 6 6.17 8.1 Normative References . . . . . . . . . . . . . . . . . . . 6 6.27 8.2 Informative References . . . . . . . . . . . . . . . . . . 78 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . 78 Intellectual Property and Copyright Statements . . . . . . . . 810 1. Introduction This document describes the Uniform Resource Identifiers (URIs) to be used with the SSH, SCP,Secure File Transfer Protocol (SFTP) [I-D.ietf-secsh- filexfer] and SFTPSecure Shell (SSH) [I-D.ietf-secsh-architecture] protocols. 2. General Syntax TheA hierarchical URI for each protocolshall consist of the scheme and the scheme specific portion separated by a colon ":",":" followed by the hierarchical part, as discussed in [RFC3986][RFC3986]. This specification shall adoptuses the definitions "port", "host", "scheme", "userinfo", "path- empty", "path-abempty" and "authority" from [RFC3986]. This document follows the ABNF notation defined in [RFC2234]. 2.1 SSHSecure Shell (SSH) URI The SSHSecure Shell (SSH) scheme shall consist of the protocol acronymscheme name "ssh" followed by a colon ":" andfollowed by hier-part defined in [RFC3986]. This URL does not designate a double slashdata object, but rather an interactive service. The SSH URI ABNF definition follows. sshURI = "ssh:" hier-part hier-part = "//" authority ( path-empty / path-abempty ) authority = [ [ userinfo-ssh ] "@" ] host [ ":" port ] host = <as specified in accordance with [RFC2718].[RFC3986]> port = <as specified in [RFC3986]> userinfo-ssh = [ userinfo ] [";" c-param *("," c-param)] userinfo = <as specified in [RFC3986]> path-empty = <as specified in [RFC3986]> path-abempty = <as specified in [RFC3986]> c-param = paramname "=" paramvalue paramname = *( ALPHA / DIGIT / "-" / "." / ":" ) paramvalue = *( ALPHA / DIGIT / "-" / "." / ":" ) The first component of the scheme specific portion MAY include credentials (userinfo)(userinfo-ssh) consisting of a username andfollowed by optional parameters. The convention of optionally alsoincluding a password,the password separated from the username by a colon ":". Including the password":" in the URI is NOT RECOMMENDED and is deprecated in accordance with [RFC3986][RFC3986]. One or more optional connection parameters (conn-parameters) may be specified within the userinfo section of the URI. These conn- parameters are separated from the credentialsuserinfo by a semi-colon ";" and from each other by a comma ",". Following the userinfo, if present, and the conn-parameters, if present the at-sign "@" shall precede";". The only connection parameter defined in this document is for the authority section of the URI. Optionally, the authorityhost- key fingerprint described in section MAY also includeSection 3.1. It is possible that additional parameters be defined in the port preceded by a colon ":".future. If the porta connection parameter is not included,understood it SHOULD be ignored. If the default port is assumed. ssh_URI = "ssh://" [userinfo ] [ ";"conn-parameter=value ] [ "@" ] host [ ":" port ] 2.2 SCP and SFTP URI For SCP and SFTP, the scheme portion (scp: or sftp:) is followed by a double slash "//". Both SCP and SFTP URIs are terminated by a single slash "/" followed by the path information to the requested resource. The first component of the scheme specific portion MAY include credentials (userinfo) consisting of a username and optionally also including a password, separated by a colon ":". Including the password in the URI is NOT RECOMMENDED and is deprecated in accordance with [RFC3986] Oneor more optionalconnection parameters (conn-parameters) may be specified within the userinfo section of the URI. These conn- parametersare separated from the credentials by a semi-colon ";" and from each other by a comma ",". Following the userinfo, if present, and the conn-parameters, ifpresent the at-sign "@" shall precede the authority section of the URI. Optionally, the authority section MAY also include the port preceded by a colon ":". If the port is not included, the default port is assumed. scp_URI = "scp://" [userinfo ] [ ";"conn-parameter=value ] [ "@" ] host [ ":" port ] [abs_path ] Following2.2 Secure File Transfer Protocol (SFTP) URI The SFTP URL scheme is used to designate files and directory listings to retrieve on Internet hosts accessible using the port additional parameters may be specified. These parameters are definedSFTP protocol described in [I-D.ietf-secsh-filexfer]. For Secure File Transfer Protocol (SFTP), the connection parameters section. Followingscheme portion shall consist of the path additional sftp specific parameters may be specified. sftp_URIscheme name "sftp". SFTP URIs ABNF definition is given below. sftpURI = "sftp:" hier-part hier-part = "sftp://""//" authority [ userinfopath ] [ ";"conn-parameter=value]";" s-param *("," s-param)] path = <as specified in [RFC3986]> authority = [ userinfo-ssh "@" ] host [ ":" port ] host = <as specified in [RFC3986]> port = <as specified in [RFC3986]> userinfo-ssh = [ abs_path ] [ ";"sftp-parameter=valueuserinfo ] [";" c-param *("," c-param)] userinfo = <as specified in [RFC3986]> c-param = paramname "=" paramvalue paramname = *( ALPHA / DIGIT / "-" / "." / ":" ) paramvalue = *( ALPHA / DIGIT / "-" / "." / ":" ) s-param = paramname "=" paramvalue The authority portion of the SFTP URL is the same as for the SSH URL defined in section Section 2.1. The URIs for SFTP and SCPare hierarchical URIs where each component of the abs_pathpath consists of path elements separated by a '/'. This formatting is meant to represent the path information as in Section 5 of [I-D.ietf-secsh-filexfer]. If a path starts with a %2F (a URL-encoded "/") then it is relative to the root of the file system. Paths starting with any other character are relative to the user's home or default directory. Note that the characters "/" and ";" are reserved and must be encoded. Path segments SHOULD be represented in the UTF-8 [RFC3629] character set and clients SHOULD NOT disable UTF-8 translation on the server with the filename-translation-control extension. The shortest valid UTF-8 encoding of the UNICODE data MUST be used. Note that dot segments "." and ".." are only interpreted within the URI path hierarchy and are removes as part of the URL resolution process defined in [RFC3986]. Following the path additional sftp specific parameters may be specified. These are described in section Section 3.2. It is possible that additional parameters be defined in the future. If a sftp parameter is not understood it SHOULD be ignored. 3. Parameters 3.1 SSH connection parameters The following parameters are associated with an SSH connection and are applicable to SSH, SFTPSSH and SCP.SFTP. All parameters are optional and MUST NOT overwrite configured defaults. Individual parameters are separated by a comma (","). Additional parameters MAY be used.fingerprint The fingerprint parameter contains the fingerprint of the host key for the host specified in the URL. The fingerprint is encoded as host-key-alg-fingerprint. Host-key-alg is host public key algorithm defined in [I-D.ietf-secsh-transport] and the fingerprint format is [I-D.ietf-secsh-publickeyfile]. For use in a URI, the fingerprint shall use a single dash "-" as a separator instead of the colon ":" as described in [I-D.ietf-secsh- publickeyfile]. This parameter MUST NOT overwrite a key that is already configured for the host. The fingerprint MAY be used to validate the authenticity of the host key if the URL was obtained from an authenticated source with its integrity protected. If this parameter is not included then the validity of the host key is validated using another method. See Security Considerations section for additional considerations. There MUST be only one fingerprint parameter per host-key-alg for a given URL. 3.2 SFTP Parameters The SFTP parameters determine how to handle the file transfer character translation. Additional parameters MAY be used. newline The newline parameter determines how the server translates new line indicators. The default is CRLF and implemented in accordance with Section 4.3 of [I-D.ietf-secsh-filexfer].typecode The typecode identifies the type of file which determines how it will be treated. Possible values are "i"The name for binary files,the typecode attribute is "type". The value "i" indicates that a file should be transmitted without character conversion performed. The value "a" for text files, andindicates that the file should be opened with the SSH_FXF_ACCESS_TEXT_MODE flag set so it is converted to the canonical newline convention in use. The value "d" forindicates that the path is a directory listings.and should be opened using SSH_FXP_OPENDIR. 4. Examples The following section shows basic examples of URLs for each protocol. This section should not be considered to include all possible combinations of URLs for each protocol. ssh://user@host ssh://user@host:2222An SSH connection to the host host.example.com on the standard port using username user. ssh://email@example.com An SSH connection to the host host.example.com on port 2222 using username user. ssh://firstname.lastname@example.org:2222 An SSH connection to the host having the specified host-key fingerprint at host.example.com on the standard port using username user. ssh://user;fingerprint=ssh-dss-c1-b1-30-29-d7-b8-de-6c-97- email@example.com scp://firstname.lastname@example.org/file.txt sftp://user@host/dir/path/file.txt sftp://user;newline=CR,fingerprint=ssh-dss-c1-b1-30-29-d7-b8-de -email@example.com:firstname.lastname@example.org Retrieve file.txt from the user's home directory on the host at host.example.com using SFTP using username user. sftp://email@example.com/file.txt Retrieve file.txt from the absolute path /dir/path on the host at host.example.com using SFTP using username user. sftp://firstname.lastname@example.org/%2Fdir/path/file.txt Retrieve the directory listing of user's home directory on the host having the specified host-key fingerprint at host.example.com using SFTP. sftp://user;fingerprint=ssh-dss-c1-b1-30-29-d7-b8-de-6c-97- email@example.com:2222/;type=d 5. SecurityIANA Considerations In general, URIs themselves have no security considerations. However, sinceThis document provides the password for each scheme can optionallyinformation required in the URL registration template in accordance with [RFC2717]. 6. Security Considerations Passwords SHOULD NOT be included within the URI it should be noted that doing so poses a security risk. Since URIs are usually sent in the clear with no encryption or other security, any password or other credentials (userinfo)included in the userinfo could be seen by a potential attacker. CareAlthough the host-key fingerprint is not confidential information, care must alsobe taken in handling fingerprints associated with URIs because URIs transmitted or stored without protection may be modified by an attacker. In general an implementation cannot determine the source of a URI so a fingerprint received in a URI should have no more trust associated with it than a raw public key received in the SSH protocol itself. If a locally configured key exists for the server already it MUST NOT be automatically overwritten with information from the URI. If the host is unknown then the implementation should treat the fingerprint received with the same caution that it does with any unknown public key. The client MAY offer the fingerprint and URI for external validation before allowing a connection based on this information. If the client chooses to make a connection based on the URI information and it finds that the public key in the URI and the public key offered by the server do not match then it SHOULD provide a warning and provide a means to abort the connection. Sections 4.1 and 9.2.4 of [I-D.ietf-secsh- architecture] provide a good discussion of handling public keys received in the SSH protocol. 6.7. Acknowledgements Ben Harris has provided much useful feedback in the preparation of this document. 8. References 6.18.1 Normative References [I-D.ietf-secsh-architecture] Ylonen, T. and C. Lonvick, "SSH Protocol Architecture", draft-ietf-secsh-architecture-22 (work in progress), March 2005. [I-D.ietf-secsh-filexfer] Galbraith, J., "SSH File Transfer Protocol", draft-ietf-secsh-filexfer-09 (work in progress), June 2005. [I-D.ietf-secsh-publickeyfile] Galbraith, J. and R. Thayer, "SSH Public Key File Format", draft-ietf-secsh-publickeyfile-08draft-ietf-secsh-publickeyfile-09 (work in progress), AprilAugust 2005. [I-D.ietf-secsh-transport] Lonvick, C., "SSH Transport Layer Protocol", draft-ietf-secsh-transport-24 (work in progress), March 2005. [RFC2718] Masinter, L., Alvestrand, H., Zigmond,[RFC2234] Crocker, D., Ed. and R.P. Overell, "Augmented BNF for Syntax Specifications: ABNF", RFC 2234, November 1997. [RFC2717] Petke, "GuidelinesR. and I. King, "Registration Procedures for newURL Schemes",Scheme Names", BCP 35, RFC 2718,2717, November 1999. [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 10646", STD 63, RFC 3629, November 2003. [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform Resource Identifier (URI): Generic Syntax", STD 66, RFC 3986, January 2005. 6.28.2 Informative References [RFC2718] Masinter, L., Alvestrand, H., Zigmond, D., and R. Petke, "Guidelines for new URL Schemes", RFC 2718, November 1999. [RFC3305] Mealling, M. and R. Denenberg, "Report from the Joint W3C/ IETF URI Planning Interest Group: Uniform Resource Identifiers (URIs), URLs, and Uniform Resource Names (URNs): Clarifications and Recommendations", RFC 3305, August 2002. Authors' Addresses Steve Suehring PO BOX 1033 Stevens Point, WI 54481 US Email: firstname.lastname@example.orgJoseph Salowey Cisco Systems 2901 3rd Ave Seattle, WA 98121 US Email: email@example.com Steve Suehring PO BOX 1033 Stevens Point, WI 54481 US Email: firstname.lastname@example.org Intellectual Property Statement The IETF takes no position regarding the validity or scope of any Intellectual Property Rights or other rights that might be claimed to pertain to the implementation or use of the technology described in this document or the extent to which any license under such rights might or might not be available; nor does it represent that it has made any independent effort to identify any such rights. Information on the procedures with respect to rights in RFC documents can be found in BCP 78 and BCP 79. Copies of IPR disclosures made to the IETF Secretariat and any assurances of licenses to be made available, or the result of an attempt made to obtain a general license or permission for the use of such proprietary rights by implementers or users of this specification can be obtained from the IETF on-line IPR repository at http://www.ietf.org/ipr. The IETF invites any interested party to bring to its attention any copyrights, patents or patent applications, or other proprietary rights that may cover technology that may be required to implement this standard. Please address the information to the IETF at email@example.com. Disclaimer of Validity This document and the information contained herein are provided on an "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Copyright Statement Copyright (C) The Internet Society (2005). This document is subject to the rights, licenses and restrictions contained in BCP 78, and except as set forth therein, the authors retain all their rights. Acknowledgment Funding for the RFC Editor function is currently provided by the Internet Society.