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


                      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 (SMB URL).
   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 July 8, 2003                  [Page 1]


INTERNET-DRAFT                   SMB URL                 January 8, 2003

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 auth_domain. . . . . . . . . . . . . . . . . . . . . . . . 5
      2.1.3 nbt_context. . . . . . . . . . . . . . . . . . . . . . . . 6
   2.2. Relative SMB URLs. . . . . . . . . . . . . . . . . . . . . . . 7
   2.3. Use of the 'port' Field. . . . . . . . . . . . . . . . . . . . 7
3. Relationship Between the URL and the UNC Formats. . . . . . . . . . 7
4. Authentication and Security Considerations. . . . . . . . . . . . . 8
5. SMB URL Semantics . . . . . . . . . . . . . . . . . . . . . . . . . 8
6. Character Encoding Issues . . . . . . . . . . . . . . . . . . . . . 9
7. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . . 9
8. References. . . . . . . . . . . . . . . . . . . . . . . . . . . . .10
9. Author's Address. . . . . . . . . . . . . . . . . . . . . . . . . .10




































Hertel                    Expires July 8, 2003                  [Page 2]


INTERNET-DRAFT                   SMB URL                 January 8, 2003

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 July 8, 2003                  [Page 3]


INTERNET-DRAFT                   SMB URL                 January 8, 2003

2. URL Definition

   An SMB URL is identified by one of two scheme names: "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], and amended
   by [RFC2732].  Refer to those RFCs for any token definitions missing
   from the grammar below.

      smb_URL       = ( SMB_absURL | SMB_relURL )
      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  = [ auth_domain ";" ] userinfo
      auth_domain   = smb_srv_name

      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 July 8, 2003                  [Page 4]


INTERNET-DRAFT                   SMB URL                 January 8, 2003

      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 auth_domain

      The auth_domain 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".















Hertel                    Expires July 8, 2003                  [Page 5]


INTERNET-DRAFT                   SMB URL                 January 8, 2003

      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=WORLDWIDEHQ;NBNS=127.0.0.1

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

      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], and is not described in those documents.

          NTDOMAIN:  A synonym for WORKGROUP.




Hertel                    Expires July 8, 2003                  [Page 6]


INTERNET-DRAFT                   SMB URL                 January 8, 2003


          NODETYPE:  One of "B", "P", "M", or "H".  These represent the
                     different mechanisms by which a NetBIOS name may
                     be resolved to an IP address on an NBT network.
                     The first three types are defined in STD 19.  In
                     "H" mode the NBNS is queried before a broadcast
                     query is sent; the opposite of "M" mode.

         BROADCAST:  The IPv4 broadcast address to which to send
                     broadcast NBT name queries.  This may be used on
                     multi-homed hosts to specify one of the connected
                     subnets.

           SCOPEID:  The syntax allows the NBT Scope to be specified as
                     part of the NBT name.  It is preferable, however,
                     to specify the Scope ID as part of the NBT context.

      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 supported and are resolved according to the
   rules defined in [RFC2396] section 5.2.


   2.3. Use of the 'port' Field

   STD 19 includes a mechanism for retargeting Session Service
   connections to alternate ports (see [RFC1001], section 16.1.1.)
   which means that non-standard ports may be used for SMB transport.
   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 a format known as Universal Naming
   Convention (UNC).  UNC is 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


Hertel                    Expires July 8, 2003                  [Page 7]


INTERNET-DRAFT                   SMB URL                 January 8, 2003

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
   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.

   Some authentication values may also be provided within the SMB URL
   string.  In particular, the following fields may be included in the
   URL:

      auth_domain - The authentication domain (single-signon database
                    server) to use for authorization
      userinfo    - User account identifier (username)

   These fields are all optional.


5. SMB URL Semantics

   The primary purpose of the SMB URL is to specify resources made
   available via the SMB protocol.  One such resource is the list
   of available servers.  Under NBT, SMB Servers are organized into
   Workgroups (also called NT Domains), and the list of available
   Workgroups is also available.

   smb://
     -- No server has been specified.  In this form, the URL should
        interpreted as a request for a list of x Workgroups available
        on the local LAN.

   smb://server
     -- This form provides an SMB server, but no share path.  The
        interpretation of this form is dependant upon the semantics
        of the specified server name.  If the name resolves to an
        NBT Workgroup name, then this is a request for a list of
        servers offering SMB services within the workgroup.  Otherwise,
        the name represents an SMB file server.




Hertel                    Expires July 8, 2003                  [Page 8]


INTERNET-DRAFT                   SMB URL                 January 8, 2003


   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.
        If the path is specified, then the URL cannot represent a
        a request for Workgroup information.


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.  For historical reasons, however,
   implementations generally disallow the use of a nul byte (0x00)
   within a NetBIOS name.  NetBIOS names are interpreted as a string of
   octets, so common mutli-byte character sets cannot be used to form
   NetBIOS names.

   Octet values less than 128 (0x80) in a NetBIOS name are interpreted
   as US-ASCII characters.  Octet values above 127 are created using the
   host's own codepage, and there is no protocol mechanism to specify
   the code page in use.  URL escape sequences should be used to
   represent characters with Octet values above 127.

   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.


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 samba-technical mailing list participants.



Hertel                    Expires July 8, 2003                  [Page 9]


INTERNET-DRAFT                   SMB URL                 January 8, 2003


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














Hertel                    Expires July 8, 2003                 [Page 10]