[Docs] [txt|pdf] [Tracker] [Email] [Diff1] [Diff2] [Nits]

Versions: 00 01 02 03 04 05 06 07 08 09 10 11 12

INTERNET-DRAFT                                     Christopher R. Hertel
draft-crhertel-smb-url-03.txt                                 Samba Team
Expires January 8, 2003                                     July 8, 2002


                      SMB Filesharing URL Scheme

Status of this Memo

   This document is an Internet-Draft and is in full conformance with
   all provisions of Section 10 of RFC2026.

   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

   Discussions regarding this document and the SMB URL scheme should
   take place on the jcifs@samba.org mailing list.  Information on
   joining this mailing list can be found at:
   http://lists.samba.org/listinfo/jcifs/.


Abstract

   The Server Message Block (SMB) protocol is one of the most widely
   used network filesystem protocols in existence.  This document
   describes a format for an SMB Uniform Resource Locator.  The SMB URL
   can be used to indicate SMB workgroups, servers, shares, files,
   inter-process communications pipes, print queues, and devices; the
   objects in the SMB network filesystem space.















Hertel                 Expires January 8, 2003                  [Page 1]


INTERNET-DRAFT                   SMB URL                    July 8, 2002

Table of Contents

1. Introduction. . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
   1.1.  Purpose . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
2. URL Definition. . . . . . . . . . . . . . . . . . . . . . . . . . . 4
   2.1  NBT Transport. . . . . . . . . . . . . . . . . . . . . . . . . 4
      2.1.1 nbt_name . . . . . . . . . . . . . . . . . . . . . . . . . 5
      2.1.2 ntdomain . . . . . . . . . . . . . . . . . . . . . . . . . 5
      2.1.3 nbt_context. . . . . . . . . . . . . . . . . . . . . . . . 5
   2.2. Relative SMB URLs. . . . . . . . . . . . . . . . . . . . . . . 6
   2.3. Fragments. . . . . . . . . . . . . . . . . . . . . . . . . . . 7
   2.4. Use of the 'port' Field. . . . . . . . . . . . . . . . . . . . 7
3. Relationship Between the URL and the UNC Formats. . . . . . . . . . 7
4. Authentication and Security Considerations. . . . . . . . . . . . . 7
5. SMB URL Semantics . . . . . . . . . . . . . . . . . . . . . . . . . 8
6. Character Encoding Issues . . . . . . . . . . . . . . . . . . . . . 9
7. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . . 9
8. References. . . . . . . . . . . . . . . . . . . . . . . . . . . . .10
9. Author's Address. . . . . . . . . . . . . . . . . . . . . . . . . .10
Appendix A . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10



































Hertel                 Expires January 8, 2003                  [Page 2]


INTERNET-DRAFT                   SMB URL                    July 8, 2002

1. Introduction

   The Server Message Block protocol (SMB) was created in the 1980's by
   Dr. Barry Feigenbaum at IBM Corporation.  It was later extended by
   IBM, 3Com, Intel, and Microsoft.  SMB is now also known by the name
   CIFS, which stands for Common Internet FileSystem.

   SMB was originally carried via a proprietary network transport, the
   interface to which was called NetBIOS (Network Basic Input Output
   System).  Two Internet RFCs ([RFC1001], [RFC1002]) were published
   which describe a mechanism for implementing the NetBIOS API on top
   of TCP and UDP.  Those RFCs are now known collectively as Internet
   Standard #19 (STD 19), and the protocol they describe is known as
   NBT (for NetBIOS over TCP).

   SMB is intended to be transport independent.  In addition to
   transport via NBT, SMB may be carried directly on TCP/IP without the
   intervening NetBIOS emulation layer.

   Several attempts have been made to document and even standardize the
   SMB protocol ([XOPENSMB], [ONET], [SNIACIFS]), yet the further
   development of SMB remains under the control of Microsoft.  Despite
   its proprietary nature, the workings of SMB are sufficiently well
   known that SMB filesharing has been successfully implemented by
   several third-party commercial vendors, and in Open Source.  SMB
   server and client software is available for a wide variety of
   operating system platforms.  The very large number of systems which
   support this form of filesharing make an SMB URL scheme both
   practical and desirable.


   1.1.  Purpose

   This document does not attempt to describe the implementation of the
   SMB protocol itself.  The goal is to present the syntax of the SMB
   URL, and explain how it maps to the features of SMB.



















Hertel                 Expires January 8, 2003                  [Page 3]


INTERNET-DRAFT                   SMB URL                    July 8, 2002


2. URL Definition

   An SMB URL may begin with one of two protocol prefixes: "smb" or
   "cifs".  Both are considered to be equivalent.

   The following grammar defines the syntax of the SMB URL.  It is
   based upon the grammar given in Appendix A of [RFC2396], as amended
   by [RFC2732].  Refer to those RFCs for any token definitions missing
   from the grammar below.

      smb_URL       = ( SMB_absURL | SMB_relURL ) [ "#" fragment ]
      smb_absURL    = scheme "://"
                      [ smb_net_path ] [ "?" [ nbt_context ] ]
      smb_relURL    = abs_path | rel_path
      scheme        = "smb" | "cifs"

      smb_net_path  = smb_server [ abs_path ]

      smb_server    = [ smb_userinfo "@" ] smb_srv_name [ ":" port ]

      smb_srv_name  = nbt_name | host
      nbt_name      = netbiosname [ "." scope_id ]
      netbiosname   = 1*( netbiosnamec ) *( netbiosnamec | "*" )
      netbiosnamec  = ( alphanum | escaped  | ":" | "=" | "+" | "$" |
                        "," | "-" | "_" | "!" | "~" | "'" | "(" | ")" )
      scope_id      = domainlabel *( "." domainlabel )

      smb_userinfo  = [ ntdomain ";" ] username [ ":" password ]
      ntdomain      = *( unreserved | escaped |
                         "&" | "=" | "+" | "$" | "," )
      username      = *( unreserved | escaped |
                         "&" | "=" | "+" | "$" | "," )
      password      = *( unreserved | escaped |
                         "&" | "=" | "+" | "$" | "," )

      nbt_context   = nbt_param *(";" nbt_param )

      nbt_param     = ( ( "NBNS=" | "WINS=" ) host )
                      | ( "CALLED=" netbiosname )
                      | ( "CALLING=" netbiosname )
                      | ( ( "WORKGROUP=" | "NTDOMAIN=" ) nbt_name )


   2.1  NBT Transport

   Many of the syntax elements given in the above grammar are
   requirements of the NBT transport.  NBT creates a virtual NetBIOS LAN
   on top of TCP and UDP, and provides mechanisms for mapping NetBIOS
   names to IP addresses, but these mechanisms may require some
   additional contextual information.




Hertel                 Expires January 8, 2003                  [Page 4]


INTERNET-DRAFT                   SMB URL                    July 8, 2002

      2.1.1 nbt_name

      The SMB URL supports the use of NetBIOS names and Scope IDs for
      identifying SMB servers.  When included as part of an SMB URL, the
      syntax of the NetBIOS name is a superset of the syntax of a DNS
      domain name label.  For example:

         smb://jcifs/

      Syntactically, the string "jcifs" in the smb_srv_name field of
      the above string may be seen as either a DNS host name
      (unqualified), or as a NetBIOS name.  The underlying SMB
      implementation must determine the namespace of the name.  (This
      is a common problem in SMB implementations and is typically solved
      by first attempting to resolve the name as a NetBIOS name and, if
      that fails, as a DNS host name.)

      Likewise, given:

         smb://jcifs.samba.org/

      the string "jcifs.samba.org" may be interpreted either as a
      qualified DNS name, or as a NetBIOS name with appended Scope ID.

      A NetBIOS name may include many characters which are not permitted
      in a domainlabel, including some non-printing characters.  Octet
      values excluded by the syntax must be escaped.  A NetBIOS name may
      not begin with an asterisk character.  The total length of the
      NetBIOS name (with escape characters translated to their octet
      equivalents) may not exceed 15 octets.

      The mapping of NetBIOS names to IP addresses is described in
      [RFC1001] and [RFC1002].

      2.1.2 ntdomain

      The ntdomain string is passed to the underlying SMB layer for
      interpretation.  It is used to specify the SMB authentication
      authority, which is known as a "Domain Controller".

      2.1.3 nbt_context

      The nbt_context may be used to provide additional information
      about the NBT transport layer and related support servers.
      Client systems implementing the SMB URL will interpret the
      nbt_context entries locally.  The nbt_params are specified as
      key/value pairs.  For example:

         smb://jcifs/?WORKGROUP=OURGROUP;NBNS=127.0.0.1

      In the above example, the WORKGROUP keyword is assigned a value of
      "OURGROUP" and NBNS is assigned a value of "127.0.0.1".



Hertel                 Expires January 8, 2003                  [Page 5]


INTERNET-DRAFT                   SMB URL                    July 8, 2002


      The following keywords are defined:

              NBNS:  Specifies the NetBIOS Name Server to be used for
                     point-to-point NBT Name Resolution.  The NBNS may
                     be specified using a DNS hostname or an IP address.
                     See [RFC1001] for information on the NBNS.

              WINS:  A synonym for NBNS.

            CALLED:  Specifies the NetBIOS name of the SMB server.  This
                     value is only used with NBT transport.  It is
                     required by the NBT Session Request message (see
                     [RFC1002], Section 4.3.2).

                     If NBT transport is used, and the CALLED name is
                     not specified within the URL string, the underlying
                     SMB implementation must deduce the CALLED name from
                     available information.

           CALLING:  Specifies the NetBIOS name of the client.  This
                     value is only used with NBT transport.  It is
                     required by the NBT Session Request message (see
                     [RFC1002], Section 4.3.2).

                     If NBT transport is used, and the CALLING name is
                     not specified within the URL string, the underlying
                     SMB implementation must generate a suitable name.

         WORKGROUP:  Specifies workgroup membership.  Workgroups are
                     used to organize resources.  By specifying the
                     NetBIOS name of the workgroup, a list of member SMB
                     servers can be obtained.  The workgroup concept was
                     developed after the publication of [RFC1001] and
                     [RFC1002].

          NTDOMAIN:  A synonym for WORKGROUP.

      Although all of the keywords and values are shown in upper case,
      case is not significant.


   2.2. Relative SMB URLs

   Relative SMB URLs are permitted and are resolved according to the
   rules defined in [RFC2396] section 5.2.









Hertel                 Expires January 8, 2003                  [Page 6]


INTERNET-DRAFT                   SMB URL                    July 8, 2002

   2.3. Fragments

   URL fragment references are permitted if the SMB URL resolves to a
   file or file-like object for which fragments have meaning.  The
   meaning depends upon the interpretation of the designated object by
   the client application.  For example, if the SMB URL indicates a
   file with HTML formatting, then the application (a web browser, for
   instance) may make use of fragment indicators.

   Otherwise, fragments are ignored.


   2.4. Use of the 'port' Field

   STD 19 includes a mechanism for retargeting Session Service
   connections to alternate ports.  (See [RFC1001], section 16.1.1.)
   That indicates that non-standard ports may be used.  With that in
   mind, the URL port field may be used to specify an alternate service
   port for SMB over either NBT or native TCP transport.


3. Relationship Between the URL and the UNC Formats.

   Some operating systems support the Universal Naming Convention (UNC)
   as a means for identifying network resources.  SMB is one of the
   protocols supported by UNC.

   In general, a UNC string specifying a resource available via SMB
   protocol can be converted into an SMB URL string by simply adding
   the "smb:" or "cifs:" prefix and reversing the direction of all of
   the separating slashes.  For example:

     UNC form                        URL form
     -----------------------------   ---------------------------------
     \\ubiqx\src\                    smb://ubiqx/src/
     \\ubiqx\src\jcifs\              smb://ubiqx/src/jcifs/
     \\ubiqx\src\jcifs\SmbURL.java   smb://ubiqx/src/jcifs/SmbURL.java


4. Authentication and Security Considerations

   SMB authentication can be categorized as follows:

      o None
      o Share-based
      o User-based
      o Authentication Server-based (NT Domain and Kerberos)

   The authentication mechanism to be used is negotiated during
   client/server session setup.  Client applications, therefore, are
   aware of the server's authentication requirements and may prompt for
   appropriate input (password, username, authentication domain).  By



Hertel                 Expires January 8, 2003                  [Page 7]


INTERNET-DRAFT                   SMB URL                    July 8, 2002

   prompting for authentication information, an application ensures that
   such information is entered by the user in a controlled manner, and
   that security measures (if any) such as password encryption or
   password hash generation are applied by the SMB protocol handler
   before the data are transmitted.

   This specification also provides an authentication shorthand, though
   it does collide rather spectacularly with the warning in [RFC2396],
   section 3.2.2, which recommends against exactly this sort of thing.

   The shorthand mechanism takes the following general form:

      smb://<ntdomain>;<username>:<password>@<smb_srv_name>[:port]

   which allows the specification of:

      ntdomain - The authentication domain (single-signon database
                 server) to use for authorization
      username - User account identifier
      password - Password

   These fields are all optional.

   This syntax is of particular use with command-line applications,
   batch scripts, configuration files, etc.  That is, any situation in
   which a multi-step exchange between a user and an application is
   awkward or impossible.

   It is recommended that application authors consider carefully the
   security implications of providing support for this form.  Likewise,
   authors of documentation in HTML or other formats are advised not to
   include authentication information in such documents, either within a
   URL string or otherwise.


5. SMB URL Semantics

   The primary purpose of the SMB URL is to specify resources made
   available via the SMB protocol.  Ancillary protocols exist, however,
   which make it possible for SMB servers to announce or register the
   service they offer.  The SMB URL provides access to those protocols
   as well as SMB itself.

   smb://
     -- In this form, no SMB server has been specified.  This should be
        taken as a request for a list of available servers.  Under NBT
        transport, it is a request for the local browse list.

   smb://server
     -- Indicates an SMB server, but no share path.  This is a request
        for a list of shared resources available on the specified
        server.



Hertel                 Expires January 8, 2003                  [Page 8]


INTERNET-DRAFT                   SMB URL                    July 8, 2002


   smb://neko@scred/src/jcifs/smb/SmbURL.java
     -- Indicates file /src/jcifs/smb/SmbURL.java on node "scred".  The
        username "neko" is to be used when connecting to the share.


6. Character Encoding Issues

   The only restriction that STD 19 places on the octet values that may
   be used in a NetBIOS name is that the name may not begin with an
   asterisk ('*', ASCII value 0x2A).  No other values are listed as
   excluded in the RFCs.

   Octet values less than 128 (0x80) in a NetBIOS name are commonly
   interpreted as US-ASCII characters.  Unfortunately, there is no
   convention or best practice for octet values 128 and above.

   NetBIOS names, share names, and the directory paths and filenames
   offered by an SMB server may all contain characters from outside the
   7-bit US-ASCII character set.  Applications MUST support the use of
   the URL escape sequence as described in [RFC2396] to accommodate
   octet values that represent non-US-ASCII characters.  Applications
   which support extended character sets provide the end user with a
   means of hand-configuring compatible character sets.


7. Acknowledgments

   The creation of this document would not have been possible without
   the help and guidance of

   Michael B. Allen
   David Farmer
   Roy T. Fielding
   Steven French
   Larry Masinter
   Richard Sharpe

   and the aggregate knowledge and wisdom of

   The Samba Team
   The jCIFS Team
   The Samba-TNG Team
   The SNIA CIFS Work Group
   and the members of the samba-technical mailing list.










Hertel                 Expires January 8, 2003                  [Page 9]


INTERNET-DRAFT                   SMB URL                    July 8, 2002

8. References

   [RFC1001]  Karl Auerbach, et. al., "Protocol Standard For a NetBIOS
              Service on a TCP/UDP Transport: Concepts and Methods", RFC
              1001, March 1987.

   [RFC1002]  Karl Auerbach, et. al., "Protocol Standard For a NetBIOS
              Service on a TCP/UDP Transport: Detailed Specifications",
              RFC 1002, March 1987.

   [RFC2396]  Berners-Lee, T., Fielding, R. and L. Masinter, "Uniform
              Resource Identifiers (URI): Generic Syntax", RFC 2396,
              August 1998.

   [RFC2732]  R. Hinden, B. Carpenter, L. Masinter, "Format for Literal
              IPv6 Addresses in URL's", RFC 2732, December 1999.

   [XOPENSMB] "Protocols for X/Open PC Interworking: SMB, Version 2",
              ISBN 1-872630-45-6, The Open Group, October 1992.

   [ONET]     Microsoft Corporation, Intel Corporation, "Microsoft
              Networks/OpenNET Filesharing Protocol", Document Version
              2, Intel Part No. 138446, November 7, 1988.

   [SNIACIFS] Storage Network Industry Association CIFS Documentation
              Work Group, "Common Internet File System (CIFS) Technical
              Reference", Version: CIFS-TR 1.0, March 1, 2002.


9. Author's Address

    Christopher R. Hertel
    University of Minnesota
    Networking and Telecommunications
    2218 University Avenue SE
    Minneapolis, MN  55414-3029, USA

    E'mail: crh@samba.org
            crh@ubiqx.org



Appendix A.  SMB Implementation Resources

   As of the time of this writing, there is no standard specification
   for the SMB protocol.  An attempt was made to provide such a standard
   in 1996, when a draft specification was submitted to the IETF.  That
   draft have since expired, but the Storage Network Industry
   Association (SNIA) has recently developed a new document based upon
   the earlier work ([SNIACIFS]).





Hertel                 Expires January 8, 2003                 [Page 10]


Html markup produced by rfcmarkup 1.129d, available from https://tools.ietf.org/tools/rfcmarkup/