[MS-SSNWS]:
Native Web Services Protocol
Intellectual Property Rights Notice for Open Specifications Documentation
Technical Documentation. Microsoft publishes Open Specifications documentation (“this documentation”) for protocols, file formats, data portability, computer languages, and standards support. Additionally, overview documents cover inter-protocol relationships and interactions.
Copyrights. This documentation is covered by Microsoft copyrights. Regardless of any other terms that are contained in the terms of use for the Microsoft website that hosts this documentation, you can make copies of it in order to develop implementations of the technologies that are described in this documentation and can distribute portions of it in your implementations that use these technologies or in your documentation as necessary to properly document the implementation. You can also distribute in your implementation, with or without modification, any schemas, IDLs, or code samples that are included in the documentation. This permission also applies to any documents that are referenced in the Open Specifications documentation.
No Trade Secrets. Microsoft does not claim any trade secret rights in this documentation.
Patents. Microsoft has patents that might cover your implementations of the technologies described in the Open Specifications documentation. Neither this notice nor Microsoft's delivery of this documentation grants any licenses under those patents or any other Microsoft patents. However, a given Open Specifications document might be covered by the Microsoft Open Specifications Promise or the Microsoft Community Promise. If you would prefer a written license, or if the technologies described in this documentation are not covered by the Open Specifications Promise or Community Promise, as applicable, patent licenses are available by contacting .
License Programs. To see all of the protocols in scope under a specific license program and the associated patents, visit the Patent Map.
Trademarks. The names of companies and products contained in this documentation might be covered by trademarks or similar intellectual property rights. This notice does not grant any licenses under those rights. For a list of Microsoft trademarks, visit
Fictitious Names. The example companies, organizations, products, domain names, email addresses, logos, people, places, and events that are depicted in this documentation are fictitious. No association with any real company, organization, product, domain name, email address, logo, person, place, or event is intended or should be inferred.
Reservation of Rights. All other rights are reserved, and this notice does not grant any rights other than as specifically described above, whether by implication, estoppel, or otherwise.
Tools. The Open Specifications documentation does not require the use of Microsoft programming tools or programming environments in order for you to develop an implementation. If you have access to Microsoft programming tools and environments, you are free to take advantage of them. Certain Open Specifications documents are intended for use in conjunction with publicly available standards specifications and network programming art and, as such, assume that the reader either is familiar with the aforementioned material or has immediate access to it.
Support. For questions and support, please contact .
Revision Summary
Date / Revision History / Revision Class / Comments8/7/2009 / 0.1 / Major / First release.
11/6/2009 / 0.1.1 / Editorial / Changed language and formatting in the technical content.
3/5/2010 / 0.2 / Minor / Clarified the meaning of the technical content.
4/21/2010 / 0.2.1 / Editorial / Changed language and formatting in the technical content.
6/4/2010 / 0.3 / Minor / Clarified the meaning of the technical content.
9/3/2010 / 0.3.1 / Editorial / Changed language and formatting in the technical content.
2/9/2011 / 0.4 / Minor / Clarified the meaning of the technical content.
7/7/2011 / 0.4 / None / No changes to the meaning, language, or formatting of the technical content.
11/3/2011 / 0.4 / None / No changes to the meaning, language, or formatting of the technical content.
1/19/2012 / 0.4 / None / No changes to the meaning, language, or formatting of the technical content.
2/23/2012 / 0.4 / None / No changes to the meaning, language, or formatting of the technical content.
3/27/2012 / 0.4 / None / No changes to the meaning, language, or formatting of the technical content.
5/24/2012 / 0.4 / None / No changes to the meaning, language, or formatting of the technical content.
6/29/2012 / 1.0 / Major / Updated and revised the technical content.
7/16/2012 / 1.0 / None / No changes to the meaning, language, or formatting of the technical content.
10/8/2012 / 1.0 / None / No changes to the meaning, language, or formatting of the technical content.
10/23/2012 / 1.0 / None / No changes to the meaning, language, or formatting of the technical content.
3/26/2013 / 1.0 / None / No changes to the meaning, language, or formatting of the technical content.
6/11/2013 / 1.0 / None / No changes to the meaning, language, or formatting of the technical content.
8/8/2013 / 1.0 / None / No changes to the meaning, language, or formatting of the technical content.
12/5/2013 / 2.0 / Major / Updated and revised the technical content.
2/11/2014 / 2.0 / None / No changes to the meaning, language, or formatting of the technical content.
5/20/2014 / 2.0 / None / No changes to the meaning, language, or formatting of the technical content.
5/10/2016 / 2.0 / None / No changes to the meaning, language, or formatting of the technical content.
8/16/2017 / 2.0 / None / No changes to the meaning, language, or formatting of the technical content.
Table of Contents
1Introduction
1.1Glossary
1.2References
1.2.1Normative References
1.2.2Informative References
1.3Overview
1.4Relationship to Other Protocols
1.5Prerequisites/Preconditions
1.6Applicability Statement
1.7Versioning and Capability Negotiation
1.8Vendor-Extensible Fields
1.9Standards Assignments
2Messages
2.1Transport
2.2Common Message Syntax
2.2.1Namespaces
2.2.2Messages
2.2.2.1sqlbatchSoapIn
2.2.2.1.1sqlbatchSoapIn SOAP Body
2.2.2.1.2sqlbatchSoapIn SOAP Headers
2.2.2.1.2.1applicationName SOAP Header
2.2.2.1.2.2clientInterface SOAP Header
2.2.2.1.2.3clientNetworkID SOAP Header
2.2.2.1.2.4clientPID SOAP Header
2.2.2.1.2.5environmentChangeNotifications SOAP Header
2.2.2.1.2.6hostName SOAP Header
2.2.2.1.2.7initialDatabase SOAP Header
2.2.2.1.2.8initialLanguage SOAP Header
2.2.2.1.2.9notificationRequest SOAP Header
2.2.2.1.2.10sqlSession SOAP Header
2.2.2.2sqlbatchSoapOut
2.2.2.2.1sqlbatchSoapOut SOAP Body
2.2.2.2.1.1sqlbatchResult
2.2.2.2.1.1.1sqlbatchResult.SqlRowSet
2.2.2.2.1.1.2sqlbatchResult.SqlXml
2.2.2.2.1.1.3sqlbatchResult.SqlMessage
2.2.2.2.1.1.4sqlbatchResult.SqlRowCount
2.2.2.2.1.1.5sqlbatchResult.SqlResultCode
2.2.2.2.1.1.6sqlbatchResult.SqlTransaction
2.2.2.2.2sqlbatchSoapOut SOAP Header
2.2.2.2.2.1sqlSession SOAP Header
2.2.3Elements
2.2.4Complex Types
2.2.4.1ArrayOfSqlParameter
2.2.4.1.1SqlParameter
2.2.4.1.2SqlParameter.Value
2.2.5Simple Types
2.2.5.1sqlCompareOptionsList
2.2.5.2sqlTypes
2.2.5.3sqlDbTypeEnum
2.2.6Attributes
2.2.7Groups
2.2.8Attribute Groups
2.3Directory Service Schema Elements
3Protocol Details
3.1Batch_EPSoap Server Details
3.1.1Abstract Data Model
3.1.1.1Session-specific Structures
3.1.2Timers
3.1.3Initialization
3.1.4Message Processing Events and Sequencing Rules
3.1.4.1Single sqlbatch
3.1.4.1.1Messages
3.1.4.1.1.1sqlbatchSoapIn
3.1.4.1.1.2sqlbatchSoapOut
3.1.4.1.2Elements
3.1.4.1.2.1sqlbatch
3.1.4.1.2.2sqlbatchResponse
3.1.4.1.3Complex Types
3.1.4.1.3.1SqlResultStream
3.1.4.1.3.2ArrayOfSqlParameter
3.1.4.1.4Simple Types
3.1.4.1.4.1ParameterDirection
3.1.4.1.5Attributes
3.1.4.1.6Groups
3.1.4.1.7Attribute Groups
3.1.4.2Session-based sqlbatch
3.1.4.2.1Messages
3.1.4.2.1.1sqlbatchSoapIn
3.1.4.2.1.2sqlbatchSoapOut
3.1.4.2.2Elements
3.1.4.2.2.1sqlSession
3.1.4.2.2.2sqlbatch
3.1.4.2.2.3sqlbatchResponse
3.1.4.2.3Complex Types
3.1.4.2.3.1SqlResultStream
3.1.4.2.3.2ArrayOfSqlParameter
3.1.4.2.4Simple Types
3.1.4.2.4.1ParameterDirection
3.1.4.2.5Attributes
3.1.4.2.6Groups
3.1.4.2.7Attribute Groups
3.1.4.3Authentication
3.1.5Timer Events
3.1.6Other Local Events
4Protocol Examples
4.1SOAP Requests
4.1.1SOAP Request with No Parameters
4.1.2SOAP Request with SOAPAction Header
4.1.3SOAP Request with Parameters
4.1.4SOAP Request with Additional Parameter Attributes
4.1.5SOAP Request with sqlSession.initiate
4.1.6SOAP Request with sqlSession.sessionId
4.1.7SOAP Request with sqlSession.terminate
4.2SOAP Responses
4.2.1SOAP Response with No Output Parameters
4.2.2SOAP Response with Output Parameters
4.2.3SOAP Response with Additional Output Parameter Attributes
4.2.4SOAP Response to a Request with sqlSession.initiate
4.2.5SOAP Response to a Request with sqlSession.sessionId
4.2.6SOAP Response to a Request with sqlSession.terminate
4.2.7SOAP Fault Response
5Security
5.1Security Considerations for Implementers
5.2Index of Security Parameters
6Appendix A: Full WSDL
7Appendix B: Product Behavior
8Change Tracking
9Index
1Introduction
The Native Web Services (NWS) protocol is an application layer request/response protocol that facilitates interaction with a database server and provides for specification of requests to SQLServer and the return of data. This protocol is a specific web services implementation that uses the standard Simple Object Access Protocol (SOAP).
Sections 1.5, 1.8, 1.9, 2, and 3 of this specification are normative. All other sections and examples in this specification are informative.
1.1Glossary
This document uses the following terms:
attribute: A characteristic of some object or entity, typically encoded as a name/value pair.
authentication: The act of proving an identity to a server while providing key material that binds the identity to subsequent communications.
Basic: An authentication access type supported by HTTP as defined by [RFC2617].
certificate: A certificate is a collection of attributes and extensions that can be stored persistently. The set of attributes in a certificate can vary depending on the intended usage of the certificate. A certificate securely binds a public key to the entity that holds the corresponding private key. A certificate is commonly used for authentication and secure exchange of information on open networks, such as the Internet, extranets, and intranets. Certificates are digitally signed by the issuing certification authority (CA) and can be issued for a user, a computer, or a service. The most widely accepted format for certificates is defined by the ITU-T X.509 version 3 international standards. For more information about attributes and extensions, see [RFC3280] and [X509] sections 7 and 8.
Digest Access Authentication: A mechanism built on top of HTTP that allows a client program to provide credentials without having to send a user name and password in plaintext when making a request. For more information, see [RFC2617].
globally unique identifier (GUID): A term used interchangeably with universally unique identifier (UUID) in Microsoft protocol technical documents (TDs). Interchanging the usage of these terms does not imply or require a specific algorithm or mechanism to generate the value. Specifically, the use of this term does not imply or require that the algorithms described in [RFC4122] or [C706] must be used for generating the GUID. See also universally unique identifier (UUID).
Kerberos: An authentication access type as defined by [RFC1964].
Negotiate: An authentication access type supported by HTTP as defined by [RFC4559].
NT LAN Manager (NTLM) Authentication Protocol: A protocol using a challenge-response mechanism for authentication in which clients are able to verify their identities without sending a password to the server. It consists of three messages, commonly referred to as Type 1 (negotiation), Type 2 (challenge) and Type 3 (authentication). For more information, see [MS-NLMP].
NWS object: An instance of the Native Web Services (NWS) protocol that is created by receiving a sqlbatch request.
SOAP: A lightweight protocol for exchanging structured information in a decentralized, distributed environment. SOAP uses XML technologies to define an extensible messaging framework, which provides a message construct that can be exchanged over a variety of underlying protocols. The framework has been designed to be independent of any particular programming model and other implementation-specific semantics. SOAP 1.2 supersedes SOAP 1.1. See [SOAP1.2-1/2003].
SOAP action: The HTTP request header field used to indicate the intent of the SOAP request, using a URI value. See [SOAP1.1] section 6.1.1 for more information.
SOAP body: A container for the payload data being delivered by a SOAP message to its recipient. See [SOAP1.2-1/2007] section 5.3 for more information.
SOAP fault: A container for error and status information within a SOAP message. See [SOAP1.2-1/2007] section 5.4 for more information.
SOAP header: A mechanism for implementing extensions to a SOAP message in a decentralized manner without prior agreement between the communicating parties. See [SOAP1.2-1/2007] section 5.2 for more information.
SOAP message: An XML document consisting of a mandatory SOAP envelope, an optional SOAP header, and a mandatory SOAP body. See [SOAP1.2-1/2007] section 5 for more information.
SOAP mustUnderstand attribute: A global, Boolean attribute that is used to indicate whether a header entry is mandatory or optional for the recipient to process. See [SOAP1.2-1/2007] section 5.2.3 for more information.
UTF-16: A standard for encoding Unicode characters, defined in the Unicode standard, in which the most commonly used characters are defined as double-byte characters. Unless specified otherwise, this term refers to the UTF-16 encoding form specified in [UNICODE5.0.0/2007] section 3.9.
UTF-8: A byte-oriented standard for encoding Unicode characters, defined in the Unicode standard. Unless specified otherwise, this term refers to the UTF-8 encoding form specified in [UNICODE5.0.0/2007] section 3.9.
web service: A software system designed to support interoperable machine-to-machine interaction over a network, using XML-based standards and open transport protocols.
Web Services Description Language (WSDL): An XML format for describing network services as a set of endpoints that operate on messages that contain either document-oriented or procedure-oriented information. The operations and messages are described abstractly and are bound to a concrete network protocol and message format in order to define an endpoint. Related concrete endpoints are combined into abstract endpoints, which describe a network service. WSDL is extensible, which allows the description of endpoints and their messages regardless of the message formats or network protocols that are used.
WSDL message: An abstract, typed definition of the data that is communicated during a WSDL operation[WSDL]. Also, an element that describes the data being exchanged between web service providers and clients.
WSDL operation: A single action or function of a web service. The execution of a WSDL operation typically requires the exchange of messages between the service requestor and the service provider.
WSDL port type: A named set of logically-related, abstract Web Services Description Language (WSDL) operations and messages.
XML: The Extensible Markup Language, as described in [XML1.0].
XML namespace: A collection of names that is used to identify elements, types, and attributes in XML documents identified in a URI reference [RFC3986]. A combination of XML namespace and local name allows XML documents to use elements, types, and attributes that have the same names but come from different sources. For more information, see [XMLNS-2ED].
XML schema: A description of a type of XML document that is typically expressed in terms of constraints on the structure and content of documents of that type, in addition to the basic syntax constraints that are imposed by XML itself. An XML schema provides a view of a document type at a relatively high level of abstraction.
MAY, SHOULD, MUST, SHOULD NOT, MUST NOT: These terms (in all caps) are used as defined in [RFC2119]. All statements of optional behavior use either MAY, SHOULD, or SHOULD NOT.
1.2References
Links to a document in the Microsoft Open Specifications library point to the correct section in the most recently published version of the referenced document. However, because individual documents in the library are not updated at the same time, the section numbers in the documents may not match. You can confirm the correct section numbering by checking the Errata.
1.2.1Normative References
We conduct frequent surveys of the normative references to assure their continued availability. If you have any issue with finding a normative reference, please contact . We will assist you in finding the relevant information.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997,
[RFC2616] Fielding, R., Gettys, J., Mogul, J., et al., "Hypertext Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999,
[RFC2617] Franks, J., Hallam-Baker, P., Hostetler, J., et al., "HTTP Authentication: Basic and Digest Access Authentication", RFC 2617, June 1999,
[RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, May 2000,
[RFC4178] Zhu, L., Leach, P., Jaganathan, K., and Ingersoll, W., "The Simple and Protected Generic Security Service Application Program Interface (GSS-API) Negotiation Mechanism", RFC 4178, October 2005,
[RFC4559] Jaganathan, K., Zhu, L., and Brezak, J., "SPNEGO-based Kerberos and NTLM HTTP Authentication in Microsoft Windows", RFC 4559, June 2006,
[SOAP1.1] Box, D., Ehnebuske, D., Kakivaya, G., et al., "Simple Object Access Protocol (SOAP) 1.1", W3C Note, May 2000,
[SOAP1.2-1/2003] Gudgin, M., Hadley, M., Mendelsohn, N., et al., "SOAP Version 1.2 Part 1: Messaging Framework", W3C Recommendation, June 2003,
[SOAP1.2-2/2003] Gudgin, M., Hadley, M., Mendelsohn, N., et al., "SOAP Version 1.2 Part 2: Adjuncts", W3C Recommendation, June 2003,
[WSDL] Christensen, E., Curbera, F., Meredith, G., and Weerawarana, S., "Web Services Description Language (WSDL) 1.1", W3C Note, March 2001,
[WSSUTP] OASIS, "Web Services Security UsernameToken Profile 1.0", OASIS Standard, March 2004,
[XML10/5] Bray, T., Paoli, J., Sperberg-McQueen, C.M., et al., Eds., "Extensible Markup Language (XML) 1.0 (Fifth Edition)", W3C Recommendation, November 2008,
[XMLNS] Bray, T., Hollander, D., Layman, A., et al., Eds., "Namespaces in XML 1.0 (Third Edition)", W3C Recommendation, December 2009,
[XMLSCHEMA1] Thompson, H., Beech, D., Maloney, M., and Mendelsohn, N., Eds., "XML Schema Part 1: Structures", W3C Recommendation, May 2001,
[XMLSCHEMA2] Biron, P.V., Ed. and Malhotra, A., Ed., "XML Schema Part 2: Datatypes", W3C Recommendation, May 2001,
1.2.2Informative References
[MSDN-DEES] Microsoft Corporation, "Database Engine Error Severities",
[MSDN-SQLCollation] Microsoft Corporation, "Selecting a SQL Server Collation",
[MSDN-SSLNXWS] Microsoft Corporation, "Setting the Server to Listen for Native XML Web Services Requests",
[MSDN-TSQL] Microsoft Corporation, "Transact-SQL Overview",
[MSDN-XMLSNET] Microsoft Corporation, "XML Serialization in the .NET Framework",
1.3Overview
The Native Web Services Protocol is an application-level protocol that is used to transfer requests and responses between clients and database server systems. In such systems, the client will typically establish a connection with the server. Once the connection is established using the HTTP ([RFC2616]) or HTTPS ([RFC2818]) protocol, SOAP messages, SOAP1.1 ([SOAP1.1]) or SOAP1.2 ([SOAP1.2-1/2003], [SOAP1.2-2/2003]), are used to communicate between the client and the server.
The NWS protocol uses the security facilities built into HTTP or HTTPS for authentication and identification and also for channel encryption negotiation. The protocol uses the facilities built into SOAP for specification of requests from client to server (including Transact SQL queries; for more information, see [MSDN-TSQL]) and for returning data from server to client. The following diagram depicts a (simplified) typical flow of communication in the protocol.
Figure 1: Communication flow in the Native Web Services protocol
The following example is a high-level description of the messages exchanged between the client and the server to execute a simple client request such as the execution of an [MSDN-TSQL] statement. It is assumed that the client and the server have already established a connection and authentication has succeeded.
Client:SOAP sqlbatch
The server executes the statement and then sends back the results to the client.
Server:SOAP sqlbatchResponse
1.4Relationship to Other Protocols
The NWS protocol uses SOAP over HTTP, or SOAP over HTTPS for network encryption, as shown in the following layering diagram. The protocol depends on the underlying network stacks being established prior to communications with NWS.
Figure 2: SOAP over HTTP
1.5Prerequisites/Preconditions
It is assumed that the client has already discovered the server and established a network transport connection for use with NWS.
No security association is assumed to have been established at the lower layer before NWS begins functioning. For [RFC4178] or [RFC2617]authentication to be used, [RFC4178] or [RFC2617] support needs to be available on both the client and server machines. If channel encryption is to be used, [RFC2818] support needs to be present on both the client and server machines, and acertificate that is suitable for encryption needs to be deployed on the server machine.
1.6Applicability Statement
The NWS protocol is appropriate for use to facilitate request/response communications between an application and a database server in web services application scenarios where network or local connectivity is available.
1.7Versioning and Capability Negotiation
This document covers versioning issues in the following areas:
Supported Transports: This protocol uses multiple transports with SOAP as described in section 2.1.
Protocol Versions: This protocol has only one version and has only one WSDL port type version with a single operation. The use of the operation is described in section 3.1.
Security and Authentication Methods: This protocol supports the following authentication methods: Negotiate, NTLM, Kerberos, Digest Access, and Basic.