draft-ietf-secsh-scp-sftp-ssh-uri-02.txt   draft-ietf-secsh-scp-sftp-ssh-uri-03.txt 
Network Working Group S. Suehring Network Working Group J. Salowey
Internet-Draft Internet-Draft Cisco Systems
Expires: December 16, 2005 J. Salowey Expires: December 3, 2005 S. Suehring
Cisco Systems June 2005
June 14, 2005
SCP/SFTP/SSH URI Format Uniform Resource Identifier (URI) Scheme for Secure File Transfer
draft-ietf-secsh-scp-sftp-ssh-uri-02.txt Protocol (SFTP) and Secure Shell (SSH)
draft-ietf-secsh-scp-sftp-ssh-uri-03.txt
Status of this Memo Status of this Memo
By submitting this Internet-Draft, each author represents that any By submitting this Internet-Draft, each author represents that any
applicable patent or other IPR claims of which he or she is aware 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 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. aware will be disclosed, in accordance with Section 6 of BCP 79.
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF), its areas, and its working groups. Note that Task Force (IETF), its areas, and its working groups. Note that
skipping to change at page 1, line 35 skipping to change at page 1, line 35
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
The list of current Internet-Drafts can be accessed at The list of current Internet-Drafts can be accessed at
http://www.ietf.org/ietf/1id-abstracts.txt. http://www.ietf.org/ietf/1id-abstracts.txt.
The list of Internet-Draft Shadow Directories can be accessed at The list of Internet-Draft Shadow Directories can be accessed at
http://www.ietf.org/shadow.html. http://www.ietf.org/shadow.html.
This Internet-Draft will expire on December 16, 2005. This Internet-Draft will expire on December 3, 2005.
Copyright Notice Copyright Notice
Copyright (C) The Internet Society (2005). Copyright (C) The Internet Society (2005).
Abstract Abstract
This document describes the Uniform Resource Identifiers used to This document describes the Uniform Resource Identifiers used to
locate resources for the SCP, SFTP, and SSH protocols. The document locate resources for the Secure File Transfer Protocol (SFTP) and the
describes the generic syntax involved in URI definitions as well as Secure Shell (SSH) protocols. The document describes the generic
specific definitions for each protocol. These specific definitions syntax involved in URI definitions as well as specific definitions
may include user credentials such as username and password and also for each protocol. These specific definitions may include user
may include other parameters such as fingerprint. In addition, credentials such as username and also may include other parameters
security considerations and examples are also provided within this such as host key fingerprint. In addition, security considerations
document. and examples are also provided within this document.
Table of Contents Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3
2. General Syntax . . . . . . . . . . . . . . . . . . . . . . . . 3 2. General Syntax . . . . . . . . . . . . . . . . . . . . . . . . 3
2.1 SSH URI . . . . . . . . . . . . . . . . . . . . . . . . . 3 2.1 Secure Shell (SSH) URI . . . . . . . . . . . . . . . . . . 3
2.2 SCP and SFTP URI . . . . . . . . . . . . . . . . . . . . . 3 2.2 Secure File Transfer Protocol (SFTP) URI . . . . . . . . . 4
3. Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . 4 3. Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . 5
3.1 SSH connection parameters . . . . . . . . . . . . . . . . 4 3.1 SSH connection parameters . . . . . . . . . . . . . . . . 5
3.2 SFTP Parameters . . . . . . . . . . . . . . . . . . . . . 5 3.2 SFTP Parameters . . . . . . . . . . . . . . . . . . . . . 5
4. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 4. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
5. Security Considerations . . . . . . . . . . . . . . . . . . . 6 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 6
6. References . . . . . . . . . . . . . . . . . . . . . . . . . . 6 6. Security Considerations . . . . . . . . . . . . . . . . . . . 6
6.1 Normative References . . . . . . . . . . . . . . . . . . . 6 7. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 7
6.2 Informative References . . . . . . . . . . . . . . . . . . 7 8. References . . . . . . . . . . . . . . . . . . . . . . . . . . 7
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . 7 8.1 Normative References . . . . . . . . . . . . . . . . . . . 7
Intellectual Property and Copyright Statements . . . . . . . . 8 8.2 Informative References . . . . . . . . . . . . . . . . . . 8
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . 8
Intellectual Property and Copyright Statements . . . . . . . . 10
1. Introduction 1. Introduction
This document describes the Uniform Resource Identifiers (URIs) to be This document describes the Uniform Resource Identifiers (URIs) to be
used with the SSH, SCP, and SFTP protocols. used with the Secure File Transfer Protocol (SFTP) [I-D.ietf-secsh-
filexfer] and Secure Shell (SSH) [I-D.ietf-secsh-architecture]
protocols.
2. General Syntax 2. General Syntax
The URI for each protocol shall consist of the scheme and the scheme A hierarchical URI shall consist of the scheme and the scheme
specific portion separated by a colon ":", as discussed in [RFC3986] specific portion separated by a colon ":" followed by the
This specification shall adopt the definitions "port", "host", hierarchical part, as discussed in [RFC3986]. This specification
"scheme", "userinfo", and "authority" from [RFC3986]. uses 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 SSH URI 2.1 Secure Shell (SSH) URI
The SSH scheme shall consist of the protocol acronym followed by a The Secure Shell (SSH) scheme shall consist of the scheme name "ssh"
colon ":" and a double slash "//" in accordance with [RFC2718]. followed by a colon ":" followed by hier-part defined in [RFC3986].
This URL does not designate a data 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 [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 The first component of the scheme specific portion MAY include
credentials (userinfo) consisting of a username and optionally also credentials (userinfo-ssh) consisting of a username followed by
including a password, separated by a colon ":". Including the optional parameters. The convention of optionally including the
password in the URI is NOT RECOMMENDED and is deprecated in password separated from the username by a ":" in the URI is NOT
accordance with [RFC3986] RECOMMENDED and is deprecated in accordance with [RFC3986].
One or more optional connection parameters (conn-parameters) may be One or more optional connection parameters (conn-parameters) may be
specified within the userinfo section of the URI. These conn- specified within the userinfo section of the URI. These conn-
parameters are separated from the credentials by a semi-colon ";" and parameters are separated from the userinfo by a semi-colon ";". The
from each other by a comma ",". only connection parameter defined in this document is for the host-
key fingerprint described in section Section 3.1. It is possible
Following the userinfo, if present, and the conn-parameters, if that additional parameters be defined in the future. If a connection
present the at-sign "@" shall precede the authority section of the parameter is not understood it SHOULD be ignored.
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.
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 If the userinfo or connection parameters are present the at-sign "@"
by the path information to the requested resource. 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.
The first component of the scheme specific portion MAY include 2.2 Secure File Transfer Protocol (SFTP) URI
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]
One or more optional connection parameters (conn-parameters) may be The SFTP URL scheme is used to designate files and directory listings
specified within the userinfo section of the URI. These conn- to retrieve on Internet hosts accessible using the SFTP protocol
parameters are separated from the credentials by a semi-colon ";" and described in [I-D.ietf-secsh-filexfer]. For Secure File Transfer
from each other by a comma ",". Protocol (SFTP), the scheme portion shall consist of the scheme name
"sftp". SFTP URIs ABNF definition is given below.
Following the userinfo, if present, and the conn-parameters, if sftpURI = "sftp:" hier-part
present the at-sign "@" shall precede the authority section of the hier-part = "//" authority [ path ] [ ";" s-param *("," s-param)]
URI. Optionally, the authority section MAY also include the port path = <as specified in [RFC3986]>
preceded by a colon ":". If the port is not included, the default authority = [ userinfo-ssh "@" ] host [ ":" port ]
port is assumed. host = <as specified in [RFC3986]>
port = <as specified in [RFC3986]>
userinfo-ssh = [ userinfo ] [";" c-param *("," c-param)]
userinfo = <as specified in [RFC3986]>
c-param = paramname "=" paramvalue
paramname = *( ALPHA / DIGIT / "-" / "." / ":" )
paramvalue = *( ALPHA / DIGIT / "-" / "." / ":" )
s-param = paramname "=" paramvalue
scp_URI = "scp://" [userinfo ] [ ";"conn-parameter=value ] [ "@" ] The authority portion of the SFTP URL is the same as for the SSH URL
host [ ":" port ] [abs_path ] defined in section Section 2.1. The URIs for SFTP are hierarchical
URIs where each component of the path 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 port additional parameters may be specified. These
parameters are defined in the connection parameters section.
Following the path additional sftp specific parameters may be Following the path additional sftp specific parameters may be
specified. specified. These are described in section Section 3.2. It is
possible that additional parameters be defined in the future. If a
sftp_URI = "sftp://" [ userinfo ] [ ";"conn-parameter=value] [ "@" ] sftp parameter is not understood it SHOULD be ignored.
host [ ":" port ] [ abs_path ] [ ";"sftp-parameter=value ]
The URIs for SFTP and SCP are hierarchical URIs where each component
of the abs_path 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].
3. Parameters 3. Parameters
3.1 SSH connection parameters 3.1 SSH connection parameters
The following parameters are associated with an SSH connection and The following parameters are associated with an SSH connection and
are applicable to SSH, SFTP and SCP. All parameters are optional and are applicable to SSH and SFTP. All parameters are optional and MUST
MUST NOT overwrite configured defaults. Individual parameters are NOT overwrite configured defaults. Individual parameters are
separated by a comma (","). Additional parameters MAY be used. separated by a comma (",").
fingerprint fingerprint
The fingerprint parameter contains the fingerprint of the host key The fingerprint parameter contains the fingerprint of the host key
for the host specified in the URL. The fingerprint is encoded as for the host specified in the URL. The fingerprint is encoded as
host-key-alg-fingerprint. Host-key-alg is host public key host-key-alg-fingerprint. Host-key-alg is host public key
algorithm defined in [I-D.ietf-secsh-transport] and the algorithm defined in [I-D.ietf-secsh-transport] and the
fingerprint format is [I-D.ietf-secsh-publickeyfile]. For use in fingerprint format is [I-D.ietf-secsh-publickeyfile]. For use in
a URI, the fingerprint shall use a single dash "-" as a separator a URI, the fingerprint shall use a single dash "-" as a separator
instead of the colon ":" as described in [I-D.ietf-secsh- instead of the colon ":" as described in [I-D.ietf-secsh-
skipping to change at page 5, line 19 skipping to change at page 5, line 40
this parameter is not included then the validity of the host key this parameter is not included then the validity of the host key
is validated using another method. See Security Considerations is validated using another method. See Security Considerations
section for additional considerations. There MUST be only one section for additional considerations. There MUST be only one
fingerprint parameter per host-key-alg for a given URL. fingerprint parameter per host-key-alg for a given URL.
3.2 SFTP Parameters 3.2 SFTP Parameters
The SFTP parameters determine how to handle the file transfer The SFTP parameters determine how to handle the file transfer
character translation. Additional parameters MAY be used. 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 typecode
The typecode identifies the type of file which determines how it The typecode identifies the type of file which determines how it
will be treated. Possible values are "i" for binary files, "a" will be treated. The name for the typecode attribute is "type".
for text files, and "d" for directory listings. The value "i" indicates that a file should be transmitted without
character conversion performed. The value "a" indicates 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" indicates that the path is a directory and should be
opened using SSH_FXP_OPENDIR.
4. Examples 4. Examples
The following section shows basic examples of URLs for each protocol. The following section shows basic examples of URLs for each protocol.
This section should not be considered to include all possible This section should not be considered to include all possible
combinations of URLs for each protocol. combinations of URLs for each protocol.
ssh://user@host An SSH connection to the host host.example.com on the standard port
using username user.
ssh://user@host:2222 ssh://user@host.example.com
An SSH connection to the host host.example.com on port 2222 using
username user.
ssh://user@host.example.com: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- ssh://user;fingerprint=ssh-dss-c1-b1-30-29-d7-b8-de-6c-97-
77-10-d7-46-41-63-87@example.com 77-10-d7-46-41-63-87@host.example.com
scp://user@host.example.com/file.txt Retrieve file.txt from the user's home directory on the host at
host.example.com using SFTP using username user.
sftp://user@host/dir/path/file.txt sftp://user@host.example.com/file.txt
sftp://user;newline=CR,fingerprint=ssh-dss-c1-b1-30-29-d7-b8-de Retrieve file.txt from the absolute path /dir/path on the host at
-6c-97-77-10-d7-46-41-63-87@example.com:2222/ host.example.com using SFTP using username user.
5. Security Considerations sftp://user@host.example.com/%2Fdir/path/file.txt
In general, URIs themselves have no security considerations. Retrieve the directory listing of user's home directory on the host
However, since the password for each scheme can optionally be having the specified host-key fingerprint at host.example.com using
included within the URI it should be noted that doing so poses a SFTP.
security risk. Since URIs are usually sent in the clear with no
encryption or other security, any password or other credentials
(userinfo) included could be seen by a potential attacker.
Care must also be taken in handling fingerprints associated with URIs sftp://user;fingerprint=ssh-dss-c1-b1-30-29-d7-b8-de-6c-97-
77-10-d7-46-41-63-87@host.example.com:2222/;type=d
5. IANA Considerations
This document provides the information 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 included in the userinfo could be seen by a potential
attacker.
Although the host-key fingerprint is not confidential information,
care must be taken in handling fingerprints associated with URIs
because URIs transmitted or stored without protection may be modified because URIs transmitted or stored without protection may be modified
by an attacker. In general an implementation cannot determine the by an attacker. In general an implementation cannot determine the
source of a URI so a fingerprint received in a URI should have no 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 more trust associated with it than a raw public key received in the
SSH protocol itself. If a locally configured key exists for the SSH protocol itself. If a locally configured key exists for the
server already it MUST NOT be automatically overwritten with server already it MUST NOT be automatically overwritten with
information from the URI. If the host is unknown then the information from the URI. If the host is unknown then the
implementation should treat the fingerprint received with the same implementation should treat the fingerprint received with the same
caution that it does with any unknown public key. The client MAY caution that it does with any unknown public key. The client MAY
offer the fingerprint and URI for external validation before allowing offer the fingerprint and URI for external validation before allowing
a connection based on this information. If the client chooses to a connection based on this information. If the client chooses to
make a connection based on the URI information and it finds that the 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 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 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- the connection. Sections 4.1 and 9.2.4 of [I-D.ietf-secsh-
architecture] provide a good discussion of handling public keys architecture] provide a good discussion of handling public keys
received in the SSH protocol. received in the SSH protocol.
6. References 7. Acknowledgements
6.1 Normative References Ben Harris has provided much useful feedback in the preparation of
this document.
8. References
8.1 Normative References
[I-D.ietf-secsh-architecture] [I-D.ietf-secsh-architecture]
Ylonen, T. and C. Lonvick, "SSH Protocol Architecture", Ylonen, T. and C. Lonvick, "SSH Protocol Architecture",
draft-ietf-secsh-architecture-22 (work in progress), draft-ietf-secsh-architecture-22 (work in progress),
March 2005. March 2005.
[I-D.ietf-secsh-filexfer] [I-D.ietf-secsh-filexfer]
Galbraith, J., "SSH File Transfer Protocol", Galbraith, J., "SSH File Transfer Protocol",
draft-ietf-secsh-filexfer-09 (work in progress), draft-ietf-secsh-filexfer-09 (work in progress),
June 2005. June 2005.
[I-D.ietf-secsh-publickeyfile] [I-D.ietf-secsh-publickeyfile]
Galbraith, J. and R. Thayer, "SSH Public Key File Format", Galbraith, J. and R. Thayer, "SSH Public Key File Format",
draft-ietf-secsh-publickeyfile-08 (work in progress), draft-ietf-secsh-publickeyfile-09 (work in progress),
April 2005. August 2005.
[I-D.ietf-secsh-transport] [I-D.ietf-secsh-transport]
Lonvick, C., "SSH Transport Layer Protocol", Lonvick, C., "SSH Transport Layer Protocol",
draft-ietf-secsh-transport-24 (work in progress), draft-ietf-secsh-transport-24 (work in progress),
March 2005. March 2005.
[RFC2718] Masinter, L., Alvestrand, H., Zigmond, D., and R. Petke, [RFC2234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax
"Guidelines for new URL Schemes", RFC 2718, November 1999. Specifications: ABNF", RFC 2234, November 1997.
[RFC2717] Petke, R. and I. King, "Registration Procedures for URL
Scheme Names", BCP 35, RFC 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 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
Resource Identifier (URI): Generic Syntax", STD 66, Resource Identifier (URI): Generic Syntax", STD 66,
RFC 3986, January 2005. RFC 3986, January 2005.
6.2 Informative References 8.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/ [RFC3305] Mealling, M. and R. Denenberg, "Report from the Joint W3C/
IETF URI Planning Interest Group: Uniform Resource IETF URI Planning Interest Group: Uniform Resource
Identifiers (URIs), URLs, and Uniform Resource Names Identifiers (URIs), URLs, and Uniform Resource Names
(URNs): Clarifications and Recommendations", RFC 3305, (URNs): Clarifications and Recommendations", RFC 3305,
August 2002. August 2002.
Authors' Addresses Authors' Addresses
Steve Suehring
PO BOX 1033
Stevens Point, WI 54481
US
Email: suehring@braingia.com
Joseph Salowey Joseph Salowey
Cisco Systems Cisco Systems
2901 3rd Ave 2901 3rd Ave
Seattle, WA 98121 Seattle, WA 98121
US US
Email: jsalowey@cisco.com Email: jsalowey@cisco.com
Steve Suehring
PO BOX 1033
Stevens Point, WI 54481
US
Email: suehring@braingia.com
Intellectual Property Statement Intellectual Property Statement
The IETF takes no position regarding the validity or scope of any The IETF takes no position regarding the validity or scope of any
Intellectual Property Rights or other rights that might be claimed to Intellectual Property Rights or other rights that might be claimed to
pertain to the implementation or use of the technology described in pertain to the implementation or use of the technology described in
this document or the extent to which any license under such rights 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 might or might not be available; nor does it represent that it has
made any independent effort to identify any such rights. Information made any independent effort to identify any such rights. Information
on the procedures with respect to rights in RFC documents can be on the procedures with respect to rights in RFC documents can be
 End of changes. 

This html diff was produced by rfcdiff 1.25, available from http://www.levkowetz.com/ietf/tools/rfcdiff/