WS-Discovery_Remote_Extensions_in_Win7

Document Sample
WS-Discovery_Remote_Extensions_in_Win7 Powered By Docstoc
					WS-Discovery Remote Extensions
Jun. 18, 2008


Contents
1.     Introduction .......................................................................................................................................... 1
2.     Glossary ................................................................................................................................................. 2
3.     Prefixes and XML Namespaces used in this specification..................................................................... 2
4.     Model .................................................................................................................................................... 3
     4.2.     Deployment and behavior ............................................................................................................ 3
     4.3.     How this model differs from the model in WS-Discovery ............................................................ 4
5.     Provisioning........................................................................................................................................... 4
     5.2.     Provisioning via ad-hoc WS-Discovery .......................................................................................... 5
     5.3.     Manual configuration.................................................................................................................... 5
6.     Communicating with a proxy ................................................................................................................ 5
     6.2.     Common requirements ................................................................................................................. 6
     6.3.     Messages issued by clients ........................................................................................................... 6
       6.3.1.         Probe ..................................................................................................................................... 6
       6.3.2.         ProbeMatches ....................................................................................................................... 6
       6.3.3.         Resolve .................................................................................................................................. 6
       6.3.4.         ResolveMatches .................................................................................................................... 7
     6.4.     Messages issued by services ......................................................................................................... 7
       6.4.1.         Hello ...................................................................................................................................... 7
       6.4.2.         Bye......................................................................................................................................... 8
7.     Security model ...................................................................................................................................... 8
8.     References ............................................................................................................................................ 9
Appendix I: WSDL .......................................................................................................................................... 9




1. Introduction
Microsoft’s implementation of WS-Discovery and Devices Profile for Web Services (DPWS) in Windows,
WSDAPI, will support an extension of the WS-Discovery protocol to allow discovery clients to search for
devices and services spanning different physical subnets by sending requests to centralized proxies
instead of to the services themselves. This support includes a mechanism for sending proxy locations to
clients and services, extensions to WS-Discovery messages, and behavioral rules for clients and services.

This protocol extension is designed to augment, not replace, traditional ad-hoc multicast WS-Discovery.
It is expected that clients and services will continue to participate in multicast WS-Discovery even if they
can communicate using these extensions. These extensions are suitable only for direct connections
between a client and a proxy, or between a service and a proxy.

These extensions are different from the Discovery Proxy protocol as defined in section 2.1 (and
described in section 3) of WS-Discovery. The proxy described in WS-Discovery involves a unicast
implementation of the WS-Discovery protocol, and describes multicast suppression behavior so the
proxy can respond on behalf of local services. In contrast, this document describes extensions designed
for searching remote subnets for services, which include enhancements for provisioning, and which
clearly define the request and response patterns for two-way operations. Both documents use the term
“proxy” to describe the service that receives discovery requests; but, this document uses “proxy” solely
to describe a service capable of understanding the extensions described herein.


2. Glossary
WS-Discovery              2005/04 WS-Discovery specification
                          [http://schemas.xmlsoap.org/ws/2005/04/discovery]
WS-Discovery Remote       The protocol extensions described in this specification
Extensions
WS-Discovery Proxy        “Proxy” as defined in the 2005/04 WS-Discovery specification. This term is
                          used sparingly in this document.
Proxy                     “Proxy” that supports the WS-Discovery Remote Extensions defined in this
                          specification. This team is used heavily in this document.
Client                    A discovery participant querying for the presence of services using WS-
                          Discovery Remote Extensions
Service                   A discovery participant announcing itself for discovery using WS-Discovery
                          Remote Extensions. WS-Discovery uses the term “Target Service” for the WS-
                          Discovery counterpart. DPWS “Devices” are services under this definition.
Provision                 In the context of this document, provisioning refers to the process of supplying
                          one or more proxy addresses to clients and services, automatically or through
                          manual configuration.




3. Prefixes and XML Namespaces used in this specification
Prefix    XML Namespace                                                           Specification
wsa       http://www.w3.org/Submission/2004/SUBM-ws-addressing-20040810/          WS-
                                                                                  Addressing
wsd       http://schemas.xmlsoap.org/ws/2005/04/discovery                         WS-Discovery
dpp       http://schemas.microsoft.com/windows/2008/11/discovery/remoteextensions This
                                                                                           specification


This specification also contains non-normative references to DPWS. These refer to the 2006/02 revision
[http://specs.xmlsoap.org/ws/2006/02/devprof/].


4. Model
This section describes the roles and some possible configurations of each participant in the discovery
outlined in this document.

This section is not intended to be normative or prescriptive, but is designed to illustrate possible
deployments. Nearly all aspects of these protocol extensions are flexible enough to accommodate many
varied subnet topologies, and protocol components that require specific deployment or behavior have
detailed notes in the section of this document that describe that component. This section does not
describe these deployment requirements.



4.2.    Deployment and behavior
In managed networks (those with managed infrastructure) many subnets may be connected in a single
administrative domain. One or more proxies may be centrally located, or one proxy may be deployed
on each subnet. Clients and services may be located on any subnet. Clients on one subnet may use a
proxy to locate a service on another subnet.

Two provisioning mechanisms are defined that allow an administrator to advertise a proxy’s address to
clients and services: ad-hoc WS-Discovery, and manual configuration. Clients and services may be
provisioned with a proxy that exists on a local subnet, or they may be provisioned with a proxy located
on another subnet. Clients and services may be provisioned with multiple proxies, and will typically use
all proxies.

Services may announce themselves to proxies that are provisioned to the service. Services may include
extensible data, and may use the <dpp:PassThrough> element to suggest that the proxy forward the
enclosed data to clients. The proxy may use other mechanisms for determining which services are
available: it may listen for device announcements, it may query an asset database, or it may perform its
own queries. The service may also continue to use ad-hoc multicast discovery to announce itself on the
local subnet. Not all services are required to support the proxy protocol—the proxy may advertise
services even if they only support ad-hoc WS-Discovery, or do not support discovery at all.

Clients may discover services by sending a request directly to one or more provisioned proxies and may
receive responses from each. Clients may also continue to use ad-hoc multicast discovery to find
services on the local subnet.

In all cases, clients and services send requests to the proxy using existing WS-Discovery messages
packaged inside the request/response operations defined in the WSDL in Appendix I. These messages
are sent over HTTP or HTTPS. These messages follow the existing WS-Discovery schema but this
specification supplies overriding requirements, defined in the remainder of the document.

Once a client uses a proxy to discover a service, it may proceed as if it had discovered the service using
ad-hoc WS-Discovery. Typically, the client will connect directly to the service to issue requests.



4.3.    How this model differs from the model in WS-Discovery
WS-Discovery describes a model for connection to a local proxy (WS-Discovery, section 3). The key
differences between this model and the WS-Discovery model are:

       This model provides a mechanism for provisioning proxy addresses to clients not on the same
        subnet; WS-Discovery uses local subnet discovery for clients and services to detect the proxy.
       This model explicitly allows a centrally located proxy; WS-Discovery does not.
       This model explicitly allows multiple proxies on the same subnet; WS-Discovery does not.
       A different portType is used (dpp:DiscoveryProxy instead of wsd:DiscoveryProxy).


5. Provisioning
Proxies are addressed by WS-Addressing Endpoint References. The Address part of the Endpoint
Reference must be an HTTP or HTTPS URL. Examples include:

       <wsa:EndpointReference>
               <wsa:Address>http://192.168.0.1:1234/proxy</wsa:Address>
        </wsa:EndpointReference>

       <wsa:EndpointReference>
               <wsa:Address>http://proxy.fabrikam.com/</wsa:Address>
               <wsa:ReferenceParameters>
                      …
               </wsa:ReferenceParameters>
        </wsa:EndpointReference>

       <wsa:EndpointReference>
               <wsa:Address>
               https://building_a.proxies.contoso.com/2ea99427-331e-4133-88fb-
               ff59ec6f3d4b/
               </wsa:Address>
        </wsa:EndpointReference>

Some provisioning mechanisms support expressing an entire Endpoint Reference; some may only
support the Address field of the Endpoint Reference. It is expected that some environments will involve
multiple proxies, and clients and services should be able to maintain a list of proxies for sending
requests.
Two provisioning mechanisms are defined: ad-hoc WS-Discovery, and manual configuration. More may
be added in the future. Clients and services must support at least one provisioning mechanism, and
they should support as many as possible.

5.2.    Provisioning via ad-hoc WS-Discovery
This mechanism allows the proxy to advertise its presence using ad-hoc, multicast WS-Discovery.

       A proxy can use ad-hoc multicast WS-Discovery to announce its presence to clients and services.
       If this mechanism is used, the proxy must include the dpp:DiscoveryProxy type in
        Hello/Bye/ProbeMatches/ResolveMatches messages.
        If this mechanism is used, the proxy must advertise its Endpoint Reference in the SOAP bodies
        for each WS-Discovery announcement.
       The proxy should not advertise its own presence in the HTTP proxy protocol described in this
        document.
       Clients and services must not enable the multicast suppression behavior described in section 3
        of WS-Discovery in response to announcements of the dpp:DiscoveryProxy type.
       Clients and services should not expect that only one proxy advertising dpp:DiscoveryProxy will
        be advertised on each subnet.
       Clients and services may ignore ad-hoc multicast WS-Discovery announcements from proxies.



5.3.    Manual configuration
This mechanism allows a user or administrator to manually enter one or more proxy address.

       Clients may allow a user to manually specify a proxy Endpoint Reference Address.
       Services should allow an administrator to specify a proxy Endpoint Reference Address.




6. Communicating with a proxy
This section describes the messages and behaviors of a client and service when each issues requests to
(and optionally receives responses from) a proxy.

This section is divided into three subsections:

       Common requirements.
       Requirements for messages issued by clients.
       Requirements for messages issued by services.
6.2.    Common requirements
Messages sent between clients and proxies, and between services and proxies are subject the following
requirements:

       All messages must be sent over HTTP or HTTPS using the HTTP binding described in SOAP 1.2,
        Part 2, Section 7.
       Two-way messages (Probe/ProbeMatches, Resolve/ResolveMatches) can result in a fault. This
        specification does not define any custom faults.



6.3.    Messages issued by clients
Clients may issue Probe and Resolve messages.

6.3.1. Probe
Clients may issue a WS-Discovery Probe message to a proxy. This message must adhere to WS-
Discovery Probe requirements unless otherwise noted below.

       The Probe message must be a request message in the two-way Probe operation described in the
        WSDL in Appendix I.
       Header/To must be the proxy’s Endpoint Reference Address.



6.3.2. ProbeMatches
If the proxy accepts a Probe message, it must return an HTTP 200 code and a ProbeMatches message.
This message must adhere to WS-Discovery ProbeMatches requirements unless otherwise noted below.

       The ProbeMatches message must be a response message in the two-way Probe operation
        described in the WSDL in Appendix I.
       Header/AppSequence should be omitted. Clients must ignore the Header/AppSequence
        element if received from a proxy.
       Body/ProbeMatches will contain zero or more ProbeMatch children
            o Proxies that match no services to a Probe request must issue a ProbeMatches response
                message, although Body/ProbeMatches will contain no ProbeMatch children.
       The proxy should not delay its response to a Probe message using the timer described in WS-
        Discovery. The proxy should respond to a Probe as soon as the response is ready.

If the proxy does not accept a Probe message, the proxy may return a fault.



6.3.3. Resolve
Clients may issue a WS-Discovery Resolve message to a proxy. This message must adhere to WS-
Discovery Resolve requirements unless otherwise noted below.
       The Resolve message must be a request message in the two-way Resolve operation described in
        the WSDL in Appendix I.
       Header/To must be the proxy’s Endpoint Reference Address.



6.3.4. ResolveMatches
If the proxy accepts a Resolve message, it must return an HTTP 200 code and a ResolveMatches
message. This message must adhere to WS-Discovery ResolveMatches requirements unless otherwise
noted below.

       The ResolveMatches message must be a response message in the two-way Resolve operation
        described in the WSDL in Appendix I.
       Header/AppSequence should be omitted. Clients must ignore the Header/AppSequence
        element if received from a proxy.
       Body/ResolveMatches will contain zero or one ResolveMatch children.
            o Proxies that match no services to a Resolve request must issue a ResolveMatches
                response message, although Body/ResolveMatches will contain no ResolveMatch
                children.
       The proxy should not delay its response to a Resolve message using the timer described in WS-
        Discovery. The proxy should respond to a Resolve as soon as the response is ready.

If the proxy does not accept a Resolve message, the proxy may return a fault.



6.4.    Messages issued by services
Services may issue Hello and Bye messages.

6.4.1. Hello
Services must issue a one-way Hello message to a proxy in the following conditions.

       A service must issue a Hello when WS-Discovery requires the service to issue a Hello.
       Additionally, a service must issue a Hello whenever it disconnects from a network, but is still
        connected to other networks.



This message must adhere to the WS-Discovery Hello requirements unless otherwise noted below.

       The Hello message must be the message in the one-way Hello operation described in the WSDL
        in Appendix I.
       Header/To must be the proxy’s Endpoint Reference Address.
       Header/AppSequence must be included (this is unchanged from WS-Discovery).
       Header/RelatesTo should be omitted.
       Body/Types should be included.
       Body/Scopes should be included.
       Body/xAddrs should be included.
       A service may include XML inside the <dpp:PassThrough> element for the proxy to persist for
        distribution to clients. PassThrough is defined in the WSDL in Appendix I.

Additionally,

       A service should not attempt to verify its presence in the proxy by issuing a Probe or Resolve
        request.


6.4.2. Bye
Services should issue a one-way Bye message to a proxy in the following conditions.

       A service should issue a Bye whenever it is preparing to shut down.
       A service should issue a Bye whenever it is leaving all networks to which it is connected.
       A service must not issue a Bye unless it is leaving all networks.



This message must adhere to WS-Discovery Bye requirements unless otherwise noted below.

       The Bye message must be the message in the one-way Bye operation described in the WSDL in
        Appendix I.
       Header/To must be the proxy’s Endpoint Reference Address.
       Header/AppSequence must be included (this is unchanged from WS-Discovery).



Additionally, a service should not attempt to verify if its presence was removed from the proxy by
issuing a Probe or Resolve request.




7. Security model
This document describes connection-level security that allows mutual authentication and channel
encryption between clients and proxies, and between services and proxies.

       Clients, services, and proxies may use HTTPS with x.509 certificates to establish authenticated
        and encrypted channels.
       Clients and services may require proxies to authenticate themselves with x.509 server
        certificates.
       Proxies may require clients and services to authenticate themselves with x.509 client
        certificates.
       Authentication requirements for clients, services, and proxies are out of scope for this
        document.

It is important to note that trust established between a client and a proxy does not extend to the
contents received from the proxy. Even if the client can authenticate a proxy and ensure the channel is
tamper-proof, the proxy may be publishing service information collected through unauthenticated
means.


8. References
[SOAP 1.2, Part 2, Section 7]
       M. Gudgin, et al, “SOAP Version 1.2 Part 2: Adjuncts, Section 7: SOAP HTTP Binding,” June 2003.
       (See http://www.w3.org/TR/soap12-part2/)

[WS-Addressing]
      D. Box, et al, “Web Services Addressing (WS-Addressing),” August 2004. (See
      http://www.w3.org/Submission/2004/SUBM-ws-addressing-20080410/.)

[WS-Discovery]
       J. Schlimmer, et al, “Web Services Dynamic Discovery (WS-Discovery),” April 2005. (See
       http://schemas.xmlsoap.org/ws/2005/04/discovery/)




Appendix I: WSDL
<?xml version="1.0" encoding="UTF-8"?>
<wsdl:definitions
        targetNamespace="http://schemas.microsoft.com/windows/2008/11/discovery/remoteextensions "
        xmlns:tns="http://schemas.microsoft.com/windows/2008/11/discovery/remoteextensions "
        xmlns:wsd="http://schemas.xmlsoap.org/ws/2005/04/discovery"
        xmlns:wsa="http://schemas.xmlsoap.org/ws/2004/08/addressing"
        xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
        xmlns:xs="http://www.w3.org/2001/XMLSchema" >

<wsdl:import
        namespace="http://schemas.xmlsoap.org/ws/2005/04/discovery"
        location="http://schemas.xmlsoap.org/ws/2005/04/discovery/ws-discovery.wsdl" />

<wsdl:types>
        <xs:schema>
                <xs:import
                        namespace="http://schemas.xmlsoap.org/ws/2005/04/discovery"
                        schemaLocation="http://schemas.xmlsoap.org/ws/2005/04/discovery/ws-discovery.xsd"
/>
        </xs:schema>
        <xs:schema
                targetNamespace="http://schemas.microsoft.com/windows/2008/11/discovery/remoteextensions "
                xmlns:tns="http://schemas.microsoft.com/windows/2008/11/discovery/remoteextensions " >
                <xs:complexType name="PassThroughType">
                        <xs:sequence>
                                <xs:any minOccurs="0" maxOccurs="unbounded" />
                        </xs:sequence>
                </xs:complexType>
                <xs:element name="PassThrough" type="tns:PassThroughType" />
        </xs:schema>
</wsdl:types>

<wsdl:portType name="DiscoveryProxy">

        <wsdl:operation name="Hello" >
                <wsdl:input message="wsd:HelloMsg"
                        wsa:Action="http://schemas.xmlsoap.org/ws/2005/04/discovery/Hello" />
        </wsdl:operation>

        <wsdl:operation name="Bye" >
                <wsdl:input message="wsd:ByeMsg"
                        wsa:Action="http://schemas.xmlsoap.org/ws/2005/04/discovery/Bye" />
        </wsdl:operation>

        <wsdl:operation name="Probe" >
                <wsdl:input message="wsd:ProbeMsg"
                        wsa:Action="http://schemas.xmlsoap.org/ws/2005/04/discovery/Probe" />
                <wsdl:output message="wsd:ProbeMatchMsg"
                        wsa:Action="http://schemas.xmlsoap.org/ws/2005/04/discovery/ProbeMatches" />
        </wsdl:operation>

        <wsdl:operation name="Resolve" >
                <wsdl:input message="wsd:ResolveMsg"
                        wsa:Action="http://schemas.xmlsoap.org/ws/2005/04/discovery/Resolve" />
                <wsdl:output message="wsd:ResolveMatchMsg"
                        wsa:Action="http://schemas.xmlsoap.org/ws/2005/04/discovery/ResolveMatches" />
        </wsdl:operation>

</wsdl:portType>
</wsdl:definitions>

				
DOCUMENT INFO
Shared By:
Categories:
Stats:
views:15
posted:4/30/2011
language:English
pages:10