Security Overview

The security framework in Windows Web Services API (WWSAPI) provides:

  • Message integrity, confidentiality, replay detection and server authentication using transport security.
  • Client authentication such as security token validation, certificate trust and revocation checks, etc using SOAP message security or transport security.

The Security Programming Model

Security is associated with communication channels. Securing a channel consists of the following steps.

  • Create and initialize one or more security bindings appropriate for the application's security requirements.
  • Create a security description containing those security bindings.
  • Create a channel or service proxy (on the client side), or create a listener or service host (on the server side) passing in that security description.
  • Do the normal channel programming steps of Open, Accept, Send, Receive, Close etc.
Messages sent and received on the channel are secured automatically by the runtime according the supplied security description. Optionally, these steps can be fine-tuned by specifying one or more channel-wide security settings in the security description or binding-wide security settings in a security binding.

Any required authorization of sender identities must be done by the application using the security processing results attached to each received message. Authorization steps are not specified in the security description, nor are performed automatically by the runtime.

Errors in the security description, such as unsupported bindings, inapplicable properties/fields, lack of required properties/fields or invalid property/field values, will cause channel or listener creation to fail.

Selecting Security Bindings

When designing security for an application, the primary decision is the selection of the security bindings to be included in the security description. The following are some guidelines for choosing security bindings suitable for an application's security scenario. A useful heuristic is to first understand what security credential types (such as X.509 certificates, Windows domain username/passwords, application defined username/passwords) will be available to the application, and to then choose a security binding that can use that credential type.

Channels and Security

As noted above, security is scoped to channels. Moreover, channel operations map to security steps consistently across all security bindings.

  • Channel create: The set of security bindings specified in the security description is validated and remains fixed for the channel thereafter. The shape of the channel stack, including any side-channels to be used for WS-Trust based negotiations, is also determined.
  • Channel open: Any credentials that are supplied as part of security bindings are loaded, and security sessions are established. In general, an open channel contains 'live' security state. Opening a client channel also specifies the server's endpoint address against which server authentication will be done by the runtime.
  • Between channel open and close: Messages can be securely sent and received during this phase.
  • Message send: Security context tokens are obtained or renewed as needed and security is applied to each transmitted message according to the security description. Errors that are encountered when applying security are returned to the application as send errors.
  • Message receive: Security is verified on each received message according to the security description. Any message security verification errors are returned to the application as receive errors. These per-message errors do not affect the channel state or subsequent receives. The application may discard a failed receive and restart a receive for another message.
  • Channel abort: The channel may be aborted at any time to halt all I/O on the channel. On abort, the channel will go into a faulted state and will not allow any more sends or receives. However, the channel may still retain some 'live' security state, so a subsequent channel close will be necessary to dispose all state cleanly.
  • Channel close: The security state created at open is disposed and sessions are torn down. Security context tokens are cancelled. The channel stack remains, but contains no 'live' security state or loaded credentials.
  • Channel free: The channel stack built at create, together with all security resources, are freed.

Security APIs

The API documentation for security is grouped into the following topics.


When using the WWSAPI Security API, applications face several security risks:

Accidental misconfiguration

WWSAPI supports a range of security-related configuration options. See for example WS_SECURITY_BINDING_PROPERTY_ID. Some of these options, such as WS_SECURITY_BINDING_PROPERTY_ALLOW_ANONYMOUS_CLIENTS allow the application to lower the default level of security provided by the various Security Bindings. The use of such options should be carefully evaluated to ensure that there are no resulting attack vectors.

Additionally, as described above, WWSAPI allows an application to deliberately disable certain steps required to fully secure a message exchange, such as allowing to disable encryption even though security credentials are transmitted. This is allowed to enable certain specific scenarios and should not be used for general communication. The WS_PROTECTION_LEVEL must be specifically lowered to enable this scenarios, and applications should not change that value unless absolutely necessary, as doing so will disable many checks that are designed to ensure a secure configuration.

Storing confidential information in memory

Confidential information, such as passwords, that is stored in memory is vulnerable to being extracted by a privileged attacker by means of, for example, the page file. WWSAPI makes a copy of provided credentials and encrypts that copy, leaving the original data unprotected. It is the application's responsibility to protect the original instance. Additionally, the encrypted copy is briefly decrypted while being used, opening up a window to extract it.

Denial of service

Security processing can consume significant resources. Every additional security binding increases those costs. WWSAPI aborts security processing as soon as a security verification failure is encountered, but certain checks such as authorization decisions may not take place until after significant work has been performed.

While a message is processed on the server, security state is stored on the message heap. The application can limit the memory consumption during security processing by reducing the size of that heap through WS_MESSAGE_PROPERTY_HEAP_PROPERTIES. Additionally, certain security bindings such as the WS_SECURITY_CONTEXT_MESSAGE_SECURITY_BINDING can cause the server to allocate resources on behalf of the client. The limits for those resources can be configured by way of the following WS_SECURITY_BINDING_PROPERTY_ID values:

Setting those limits to low values reduces the maximum memory consumption but can lead to legitimate clients being rejected when the quota is reached.



Community Additions