CIFS Extensions --------------- Author : Luke Kenneth Casson Leighton Created : 16 Jan 98 Version : v0.003 Modified: 20 Jan 98 This document describes cifs extensions for cifs over tcp, and for parallel negotiation or re-negotiation of security for a SMB session. Prior reading: - draft-leach-cifs-v1-spec-01.txt sections 4.1.1, 4.1.2.2 - cifs6.txt sections 4.1.1, 4.1.2 (NT LM 0.12) Aims of this document --------------------- CIFS is evolving. as an internet protocol, the setup time should be as short as possible. it needs to be made independent of NetBIOS, and it needs secure communications to be added. there should be no disruption of existing NetBIOS kernels and legacy SMB servers: one may be beyond the control of the other. the smb protocol needs to have independent messages for the communication of related information. almost every stage should involve negotiation. such as: - what is talking to what (machines, transport, ports -> referral or connection) - protocols - smb level (list of SMB protocols -> protocol to use) - client and server capabilities - encryption (snego -> kerberos etc) - who (user context info) is talking to who/what - what the user wants to access on the server. these are covered at present by: - NetBIOS session request (machines, transport, port -> referral or connection) - SMBnegprot - smb level (list of smb protocols -> index of protocol to use) - client capabilities and server capabilities, including SMB_EXTENDED_SECURITY - SMBsesssetupX (the draft one not the cifs6.txt one) - user context info (username/password/domain) - encryption (security blobs -> return security blobs, repeat) only possible if SMB_EXTENDED_SECURITY is "SMB-negotiated". - SMBtconX - share name, share password. - SMBtdis (opposite of SMBtcon) - SMBulogoff (opposite of SMBsessetup) however, as has been pointed out, and as can be seen, client/server capabilities are tied to the smb level negotiation, and encryption tied in with the user context info. also, microsoft intend to _drop_ the NetBIOS session setup, leaving no means to identify the client or server. the following is proposed, to deal with this: - EITHER NetBIOS session request on port 139 to *SMBSERVER, OR ignore this stage and use direct SMB over TCP, falling back to NetBIOS session request if the direct SMB over TCP connection fails. - SMBsessionreqANDX (machines, transport, ports -> referral or connection) [SMBsessionreq referred connection] - SMBnegprotANDX (list of SMB protocols -> protocol to use, capabilities) - SMBsecuritysetupANDX (client initiates security negotiation) - SMBsesssetup2ANDX (continuation of negotiation: capabilities, domain) - SMBsecuritysetupANDX (security negotiation, for this session user) - SMBtconX (share name, share password). - SMBtdisX (opposite of SMBtconX) - SMBulogoffX (opposite of SMBsecuritysetupANDX) sequence of SMBs, and conditions on their use --------------------------------------------- EITHER ------ an SMB connection should be established in the cifs6.txt manner, (by using the NetBIOS-over-TCP format, as described in draft-cifs-v1-0.1 section 10.1: a NetBIOS session request is sent on port 139, connecting with *SMBSERVER if involvement with NetBIOS name resolution is undesirable). OR -- A connection is established on using the CIFS-over-TCP format in draft-cifs-v1-0.1.txt, Appendix B. If the connection is refused, then the client falls back to establishing a connection using the standard NetBIOS-over-TCP format, as described in draft-cifs-v1-0.1 section 10.1. (see "either" above). once the SMB connection has been established (which also implicitly determines whether the server supports the new SMB-over-TCP format): A SMBsessionsetupANDX chained with a SMBnegprotX chained with a SMBsecuritysetupX is sent. the SMBsessionrequestANDX message. if the response comes back "unsupported" or "unknown" then the client knows that it is talking to a legacy server; maintains the connection and carries on. If a positive SMBsessionrequest response is received, it is expected to be, but not limited to being, a referral to another port number. If the response to the SMB session request is a referral, then the connection is always established using the CIFS-over-TCP format, and the SMB session request is repeated (see SMB_SESSION_REQUEST_AND_X, below). following the SMBsessionrequestANDX, SMBnegprotX and SMBsecuritysetupX, then EITHER: if the response to the SMBsecuritysetupANDX that was chained with the SMBnegprotX did NOT contain a "STATUS_MORE_PROCESSING_REQUIRED" message, then: a SMBsessionsetup2ANDX (optionally) chained with a SMBtconX is sent. OR: if the response to the SMBsecuritysetupANDX that was chained with the SMBnegprotX DID contain a "STATUS_MORE_PROCESSING_REQUIRED", then: a SMBsessionsetup2ANDX chained with an SMBsecuritysetupANDX is sent. IF the client knows (due to the nature of the security protocol negotiated) that the server will not reply to the SMBsecuritysetupANDX with a "STATUS_MORE_PROCESSING_REQUIRED" error, it can also (optionally) chain a SMBtconX. the client must send SMBsecuritysetupANDXs until the server sends a response without "STATUS_MORE_PROCESSING_REQUIRED". SMBsecuritysetupANDX(s) can be sent more than once. the negotiated encryption will apply or reapply to the *whole* session, immediately. SMB security negotiation can happen in parallel with SMB sessions. However, it is advised that clients should wait until the successful completion of the first security negotiation stages before starting SMB SMBtconXs, as the server is likely to reject them with SECURITY_NEGOTIATION_REQUIRED SMB errors (0xC000nnnn, where nnnn is to be allocated). The client should be prepared to have to negotiate or re-negotiate security at *any* time if it supports SMB_EXTENDED_SECURITY capabilities, and to immediately start using the negotiated or re-negotiated security on all SMBs in the session, *without* closing any files it has open on the server, dropping any shares it has connected to or closing the session. The server must be capable of indicating to the client that the security level is insufficient or has expired, with a SECURITY_NEGOTIATION_REQUIRED SMB error on all SMB requests except SMBsecuritysetupANDXs, *without* closing any files, disconnecting any shares or closing the session. SMB_SESSION_REQUEST_ANDX ------------------------ The URL name format is used in the client, server and server referral names. the URL should be of the format: "{proto}://{unc_name}[:{port}]" where: proto = file | cifs | nfs | http... unc_name = ip number v4 | ip number v6 | dns.name | NETBIOS.NAME ... port = tcp/ip port number. examples: "file://server.foo.com" "file://ftp.foo.com:139" "cifs://referral_server.foo.com:3020" "nfs://referral_sun_server.foo.com:2049" "cifs://194.1.1.2:139" better descriptions of the format needed are in rfc2255.txt section 3 and rfc1738.txt section 5. Client Request Description ============================== ===================================== UCHAR WordCount; Count of parameter words = 6 UCHAR AndXCommand; Secondary (X) command; 0xFF = none UCHAR AndXReserved; Reserved (must be 0) USHORT AndXOffset; Offset to next command WordCount USHORT CLIENT_URL_NAME_LEN USHORT CLIENT_URL_VERSION_LEN USHORT SERVER_URL_NAME_LEN USHORT REFERRING_SERVER_URL_NAME_LEN USHORT ByteCount; UCHAR CLIENT_URL_NAME[] UCHAR CLIENT_VERSION[] UCHAR SERVER_URL_NAME[] UCHAR REFERRING_SERVER_URL_NAME[] if a name length is zero, the string it refers to is skipped altogether. client name and server name in the request are not optional. referring server name is not optional if a server has referred the client from another server in a previous SMB session request. the client version string contains context-sensitive or OEM information ("Client for Microsoft Networks - Windows NT 4.0 Build 1381" or "smbclient-1.9.18p1" or "Thursby's DAVE 1.0.1 Macintosh Client"). the client and server URL names can be "nbt://callingname#00:139" and "nbt://calledname#20:139" to support backwards compatibility with the old netbios format, for applications that require netbios names. the referring server URL name is the name of the server that referred the client to this new server, causing the client to make this second SMB session request. a referred SMB session request cannot be re-referred to yet another SMB server. The response is: Server Response Description ================================== ================================= UCHAR WordCount; Count of parameter words = 6 UCHAR AndXCommand; Secondary (X) command; 0xFF = none UCHAR AndXReserved; Reserved (must be 0) USHORT AndXOffset; Offset to next command WordCount USHORT SERVER_URL_NAME_LEN USHORT SERVER_VERSION_LEN USHORT ERROR_CODE_STRING_LEN USHORT SERVER_URL_REFERRAL_NAME_LEN USHORT ByteCount; SERVER_URL_NAME[] SERVER_VERSION[] ERROR_CODE_STRING[] SERVER_URL_REFERRAL_NAME[] if a name length is zero, the string it refers to is skipped altogether. server name in the response is not optional. the server version info may contain context-sensitive or OEM information, e.g "Microsoft Windows NT 4.0 Build 1381 CIFS Server" or "samba-1.9.18p1 root-config-file:/usr/local/samba/lib/smb.conf.%U.%m" or "Thursby's Macintosh SMB Server DAVE 2.0" the server URL referral name is optional, and should be accompanied by a SMB_SESSION_REFERRAL error (0xC000nnnn - nnnn to be arranged) and an optional verbose error string (for debugging / user informational purposes) of "SMB session is being referred to another server / protocol / port number". the client should then issue a new SMB session request using the protocol specified in the URL, to the server specified in the URL, on the port number specified in the URL. regardless of whether the client is capable of doing this, it must drop the TCP connection (and so will the server). the server cannot issue an SMB session referral to a client that has already been referred: it must reject the session. a mechanism for the server to then complain to the referrer is yet to be decided. if the server makes a SMB session referral, then in the interests of security it is suggested that the server verify (or otherwise know or guarantee) that the SMB server it will be referring the client is prepared to receive SMB sessions *before* responding to the client. the exact mechanism used is up to the implementors, and is beyond the scope of this document. The only valid Secondary (X) command after a SMB_SESSION_REQUEST_AND_X is an SMB_NEGOTIATE_PROTOCOL_X command. chaining a session request and a negprot reduces the number of round-trips to establish the smb connection. SMB_NEGOTIATE_PROTOCOL_X ------------------------ Client Request Description ============================ ======================================= UCHAR WordCount; Count of parameter words = 2 UCHAR AndXCommand; Secondary (X) command; must be 0xFF (none) UCHAR AndXReserved; Reserved (must be 0) USHORT AndXOffset; Offset to next command WordCount USHORT ByteCount; Count of data bytes; min = 2 struct { UCHAR BufferFormat; 0x02 -- Dialect UCHAR DialectName[]; ASCII null-terminated string } Dialects[]; If the negotiated dialect is NT LM 0.12, the response format is Server Response Description ===================== ========================================== UCHAR WordCount; Count of parameter words = 19 UCHAR AndXCommand; Secondary (X) command; 0xFF = none UCHAR AndXReserved; Reserved (must be 0) USHORT AndXOffset; Offset to next command WordCount USHORT DialectIndex; Index of selected dialect UCHAR SecurityMode; Security mode: bit 0: 0 = share, 1 = user bit 1: 1 = use challenge/response authentication bit 2: 1 = Security Signatures (SMB integrity check) enabled bit 3: 1 = Security Signatures (SMB integrity check) required USHORT MaxMpxCount; Max pending outstanding requests USHORT MaxNumberVcs; Max VCs between client and server ULONG MaxBufferSize; Max transmit buffer size ULONG MaxRawSize; Maximum raw buffer size ULONG SessionKey; Unique token identifying this session ULONG Capabilities; Server capabilities ULONG SystemTimeLow; System (UTC) time of the server (low). ULONG SystemTimeHigh; System (UTC) time of the server (high). USHORT Time zone of server (minutes from UTC) ServerTimeZone; The only valid Secondary (ANDX) command that can follow a NEGPROT_ANDX is a SMB_SECURITY_SETUP_ANDX command. 4.1.2 SESSION_SETUP2_ANDX: Session Setup This SMB is used to further "Set up" the session normally just established via the negotiate protocol. If the negotiated SMB dialect is "NT LM 0.12" and the server supports ExtendedSecurity i.e. the CAP_EXTENDED_SECURITY flag is set in the Capabilities field of the Negotiate Response SMB, the Extended Security SessionSetup SMB format is: Client Request Description ============================== ===================================== UCHAR WordCount; Count of parameter words = 11 UCHAR AndXCommand; Secondary (X) command; 0xFF = none UCHAR AndXReserved; Reserved (must be 0) USHORT AndXOffset; Offset to next command WordCount USHORT MaxBufferSize; Client's maximum buffer size USHORT MaxMpxCount; Actual maximum multiplexed pending requests USHORT VcNumber; 0 = first (only), nonzero=additional VC number ULONG SessionKey; Session key (valid iff VcNumber != 0) ULONG Reserved; must be 0 ULONG Capabilities; Client capabilities USHORT ByteCount; Count of data bytes; min = 0 STRING NativeOS[]; Client's native operating system, Unicode STRING NativeLanMan[]; Client's native LAN Manager type, Unicode The response is: Server Response Description ================================== ================================= UCHAR WordCount; Count of parameter words = 2 UCHAR AndXCommand; Secondary (X) command; 0xFF = none UCHAR AndXReserved; Reserved (must be 0) USHORT AndXOffset; Offset to next command WordCount USHORT ByteCount; Count of data bytes STRING NativeOS[]; Server's native operating system STRING NativeLanMan[]; Server's native LAN Manager type STRING PrimaryDomain[]; Server's primary domain This SMB should only be chained with an SMB_SECURITY_SETUP_ANDX SMB_SECURITY_SETUP_ANDX ----------------------- Client Request Description ============================== ===================================== UCHAR WordCount; Count of parameter words = 12 UCHAR AndXCommand; Secondary (X) command; 0xFF = none UCHAR AndXReserved; Reserved (must be 0) USHORT AndXOffset; Offset to next command WordCount USHORT SecurityBlobLength; Length of opaque security blob ULONG Reserved; must be 0 USHORT ByteCount; Count of data bytes; min = 0 UCHAR SecurityBlob[] The opaque security blob The response is: Server Response Description ================================== ================================= UCHAR WordCount; Count of parameter words = 3 UCHAR AndXCommand; Secondary (X) command; 0xFF = none UCHAR AndXReserved; Reserved (must be 0) USHORT AndXOffset; Offset to next command WordCount USHORT Action; Request mode: bit0 = logged in as GUEST USHORT SecurityBlobLength length of Security Blob that follows in a later field USHORT ByteCount; Count of data bytes UCHAR GUID[16] A globally unique identifier assigned to the server. UCHAR SecurityBlob[] SecurityBlob of length specified in field SecurityBlobLength There may be multiple round trips involved in the security blob exchange. In that case, the server may return an error STATUS_MORE_PROCESSING_REQUIRED (a value of 0xC0000016) in the SMB status. The client can then repeat the SecuritySetupAndX SMB with the next the security blob. The entire message sent and received including the optional ANDX SMB must fit in the negotiated maximum transfer size. This SMB must only be chained with the SMBs that the SMB_SESSION_SETUP_ANDX can be chained with. The following are therefore the only valid SMB commands for AndXCommand for SMB_COM_SECURITY_SETUP_ANDX SMB_COM_TREE_CONNECT_ANDX SMB_COM_OPEN SMB_COM_OPEN_ANDX SMB_COM_CREATE SMB_COM_CREATE_NEW SMB_COM_CREATE_DIRECTORY SMB_COM_DELETE SMB_COM_DELETE_DIRECTORY SMB_COM_FIND SMB_COM_FIND_UNIQUE SMB_COM_COPY SMB_COM_RENAME SMB_COM_NT_RENAME SMB_COM_CHECK_DIRECTORY SMB_COM_QUERY_INFORMATION SMB_COM_SET_INFORMATION SMB_COM_NO_ANDX_COMMAND SMB_COM_OPEN_PRINT_FILE SMB_COM_GET_PRINT_QUEUE SMB_COM_TRANSACTION Appendix A ---------- The following outlines an "equivalence" between the draft-cifs-v1-0.1 protocol and the SMBs proposed in this document. it is here to demonstrate that the number of round-trips is exactly the same. draft-cifs-v1-0.1 cifs-ext ----------------- -------- NetBIOS session NetBIOS session or CIFS-over-TCP or CIFS-over-TCP SMB_NEGPROT SMB_SESSION_REQUEST_ANDX, SMB_NEGPROT_ANDX, SMB_SECURITY_SETUP_ANDX SMB_SESSION_SETUP_X SMB_SESSION_SETUP_2_ANDX SMB_SECURITY_SETUP_ANDX SMB_SESSION_SETUP_X SMB_SECURITY_SETUP_ANDX (if required. repeat, if required) (if required. repeat, if required). SMB_TCON_X SMB_TCON_X .... file access .... .... file access .... [oops, kerberos or other security package time-out. return an error!] re-start from the beginning, SMB_SECURITY_SETUP_ANDX right from the SMBnegprot, or (repeat, if required.) maybe the SMB_SESSSETUP_X. close all files, sessions, once finished, files remain shares. maybe lose some open open. session remains open. files. no problems expected.