How to: Create a Secure Session

With the exception of the basicHttpBinding Element binding, the system-provided bindings in Windows Communication Foundation (WCF) automatically use secure sessions when message security is enabled.

By default, secure sessions do not survive a Web server that is recycled. When a secure session is established, the client and the service cache the key that is associated with the secure session. As the messages are exchanged, only an identifier to the cached key is exchanged. If the Web server is recycled, the cache is also recycled, such that the Web server cannot retrieve the cached key for the identifier. If this happens, an exception is thrown back to the client. Secure sessions that use a stateful security context token (SCT) can survive a Web server being recycled. For more information about using a stateful SCT in a secure session, see How to: Create a Security Context Token for a Secure Session.

To specify that a service uses secure sessions by using one of the system-provided bindings

• Configure a service to use a system-provided binding that supports message security.

  With the exception of the basicHttpBinding Element binding, when the system-provided bindings are configured to use message security, WCF automatically uses secure sessions. The following table lists the system-provided bindings that support message security and whether message security is the default security mechanism.

  System-provided binding	Configuration element	Message security on by default
  BasicHttpBinding	basicHttpBinding Element	No
  WSHttpBinding	wsHttpBinding Element	Yes
  WSDualHttpBinding	wsDualHttpBinding Element	Yes
  WSFederationHttpBinding	wsFederationHttpBinding element	Yes
  NetTcpBinding	netTcpBinding Element	No
  NetMsmqBinding	netMsmqBinding Element	No

  The following code example uses configuration to specify a binding named wsHttpBinding_Calculator that uses the wsHttpBinding Element, message security, and secure sessions.

  <bindings>
    <WSHttpBinding>
     <binding name = "wsHttpBinding_Calculator">
       <security mode="Message">
         <message clientCredentialType="Windows"/>
       </security>
      </binding>
    </WSHttpBinding>
  </bindings>
  

  The following code example specifies that the wsHttpBinding Element, message security, and secure sessions are used to secure the secureCalculator service.

  Dim myBinding As New WSHttpBinding()
  myBinding.Security.Mode = SecurityMode.Message
  myBinding.Security.Message.ClientCredentialType = MessageCredentialType.Windows
  
  ' Create the Type instances for later use and the URI for 
  ' the base address.
  Dim contractType As Type = GetType(ICalculator)
  Dim serviceType As Type = GetType(Calculator)
  Dim baseAddress As New Uri("https://localhost:8036/serviceModelSamples/")
  
  ' Create the ServiceHost and add an endpoint, then start
  ' the service.
  Dim myServiceHost As New ServiceHost(serviceType, baseAddress)
  myServiceHost.AddServiceEndpoint(contractType, myBinding, "secureCalculator")
  myServiceHost.Open()
  

  WSHttpBinding myBinding = new WSHttpBinding();
  myBinding.Security.Mode = SecurityMode.Message;
  myBinding.Security.Message.ClientCredentialType =
      MessageCredentialType.Windows;
  
  // Create the Type instances for later use and the URI for 
  // the base address.
  Type contractType = typeof(ICalculator);
  Type serviceType = typeof(Calculator);
  Uri baseAddress = new
      Uri("https://localhost:8036/serviceModelSamples/");
  
  // Create the ServiceHost and add an endpoint, then start
  // the service.
  ServiceHost myServiceHost =
      new ServiceHost(serviceType, baseAddress);
  myServiceHost.AddServiceEndpoint
      (contractType, myBinding, "secureCalculator");
  myServiceHost.Open();
  

  Note

  Secure sessions can be turned off for the wsHttpBinding Element by setting the establishSecurityContext attribute to false. For the other system-provided bindings, secure sessions can only be turned off by creating a custom binding.

To specify that a service uses secure sessions by using a custom binding

• Create a custom binding that specifies that SOAP messages are protected by a secure session.

  For more information about creating a custom binding, see How to: Customize a System-Provided Binding.

  The following code example uses configuration to specify a custom binding that messages using a secure session.

  <bindings>
    <!-- configure a custom binding -->
    <customBinding>
      <binding name="customBinding_Calculator">
        <security authenticationMode="SecureConversation" />
        <secureConversationBootstrap authenticationMode="SspiNegotiated" />
        <textMessageEncoding messageVersion="Soap12WSAddressing10" writeEncoding="utf-8"/>
        <httpTransport/>
      </binding>
    </customBinding>
  </bindings>
  

  The following code example creates a custom binding that uses the MutualCertificate authentication mode to bootstrap a secure session.

  Dim security As SecurityBindingElement = SecurityBindingElement.CreateMutualCertificateBindingElement()
  
  ' Use a secure session.
  security = SecurityBindingElement.CreateSecureConversationBindingElement(security, True)
  
  ' Specify whether derived keys are required.
  security.SetKeyDerivation(True)
  
  ' Create the custom binding.
  Dim myBinding As New CustomBinding(security, New HttpTransportBindingElement())
  
  ' Create the Type instances for later use and the URI for 
  ' the base address.
  Dim contractType As Type = GetType(ICalculator)
  Dim serviceType As Type = GetType(Calculator)
  Dim baseAddress As New Uri("https://localhost:8036/serviceModelSamples/")
  
  ' Create the ServiceHost and add an endpoint, then start
  ' the service.
  Dim myServiceHost As New ServiceHost(serviceType, baseAddress)
  myServiceHost.AddServiceEndpoint(contractType, myBinding, "secureCalculator")
  myServiceHost.Open()
  

  SecurityBindingElement security = SecurityBindingElement.CreateMutualCertificateBindingElement();
  
  // Use a secure session.
  security = SecurityBindingElement.CreateSecureConversationBindingElement(security, true);
  
  // Specify whether derived keys are required.
  security.SetKeyDerivation(true);
  
  // Create the custom binding.
  CustomBinding myBinding = new CustomBinding(security, new HttpTransportBindingElement());
  
  // Create the Type instances for later use and the URI for 
  // the base address.
  Type contractType = typeof(ICalculator);
  Type serviceType = typeof(Calculator);
  Uri baseAddress = new
      Uri("https://localhost:8036/serviceModelSamples/");
  
  // Create the ServiceHost and add an endpoint, then start
  // the service.
  ServiceHost myServiceHost =
      new ServiceHost(serviceType, baseAddress);
  myServiceHost.AddServiceEndpoint
      (contractType, myBinding, "secureCalculator");
  myServiceHost.Open();
  

See Also

Concepts

Windows Communication Foundation Bindings Overview