Using WSDAPI with a Secure Channel
Other versions of this page are also available for the following:
.gif "A hyphen indicates that the information in this topic is not relevant for this platform, or that the platform does not support the API that is listed.")
.gif "A checkmark indicates that the information in this topic is relevant for this platform, and that any API listed is also supported on this platform.")
8/28/2008
Applies to Windows Embedded CE 6.0 R2
The WSDAPI framework supports the use of a secure channel, which encrypts data transmitted between the client application and the device host. The secure channel also allows the device to authenticate itself to the client, and optionally allows the client to authenticate the device. A secure channel uses the SSL/TLS protocol, and the URL uses the HTTPS scheme, not the HTTP scheme.
Note
Your WSDAPI configuration must not support more than 5 unique device hosts per process and/or 5 unique client-side proxies per process. When you use asynchronous messaging, be aware that the maximum number of connections per remote HTTP 1.1 server is 2 connections, while the maximum number of connections per HTTP 1.0 server is 4 connections. After the connection limit is reached, any new request is not serviced until an outstanding request is completed.
Device Requirements
A device that communicates over a secure channel must meet the following requirements.
- The logical or physical address of a device that uses a secure channel is a URL prefixed by https, not the urn:uuid style of identifier used by other WSDAPI devices or clients.
- The device must advertise an identifier that is an URL prefixed by https.
- The transport address that the device provides in the Discovery message must be the same URL as the device ID.
- The device ID must also match the URL used to obtain the device metadata over the secure channel.
- The device must have server certificates that are trusted by the client. These certificates are used when establishing the secure connection.
- The device must advertise a HTTPS endpoint and not a HTTP endpoint.
Implementation Considerations for Client Application Developers
A client application that uses WSDAPI cannot create a secure channel with a device that advertises both a HTTP and a HTTPS endpoint at the same time. In other words, a device that uses a secure channel must only use a secure channel.
For a client to authenticate the device host, the client must trust the server certificate installed on the device host. That means that the root certificate of the certificate installed on the device host must be stored in the client computer's Trusted Root Certification Authorities store.
When accepting secure connections, it is important that the host name in the URL matches the subject name in the certificate used to accept the connection. For this reason, using a dynamic IP address in the URL is not recommended. Use a host name or a static IP address instead.
If a device requires authentication, the client must have a certificate in the local machine store that will be used as a client certificate when establishing a secure connection to the device. The certificate must be one that the device will trust when the client authenticates to the device. To receive event messages from the device over a secure channel, the client must also have a server certificate that can be used to accept an SSL/TLS connection from the device on the port used for event notifications.
It is possible to have one certificate that is used for both roles.
For more information about addressing and port selection when creating a device proxy for use in you client application, see WSDCreateDeviceProxy and WSDCreateDeviceProxyAdvanced.
Implementation Considerations for Host Application Developers
You can create a DPWS-compliant device using WSDAPI that accepts connections from client applications. You can implement a host application that accepts communication over a secure channel only. In this case, the Windows Embedded CE powered computer on which the host application is installed must have a server certificate that clients trust. When required by the event sink, the computer must also have a certificate that can be used to establish a secure connection when sending events to the client. It is possible to have one certificate for both roles.
If no port is specified in the device identifier advertised by a host application, then secure communication takes place over port 443 if the device ID is an HTTPS URL. It is recommended that the device identifier explicitly specify port 5358, as this port is reserved for secure connections with WSDAPI.
For more information about addressing and port selection when creating a device host, see to WSDCreateDeviceHost and WSDCreateDeviceHostAdvanced.
See Also
Concepts
WSDAPI Client Application and Device Host Development
Configuring WSDAPI Applications to Use a Secure Channel