Share via

<security> of <customBinding>

  • Article

Specifies the security options for a custom binding.

<system.serviceModel>

  <bindings>

    <customBinding>

      <binding>

        <security> of <customBinding>

                                    
                                    <security 
                                
                                    
                                       allowSerializedSigningTokenOnReply="Boolean"
                                
                                    
                                       authenticationMode="AuthenticationMode"
                                
                                    
                                           
                                    
                                       defaultAlgorithmSuite="SecurityAlgorithmSuite"
                                
                                    
                                       includeTimestamp="Boolean"
                                
                                    
                                           
                                    
                                       requireDerivedKeys="Boolean"
                                
                                    
                                       keyEntropyMode="ClientEntropy/ServerEntropy/CombinedEntropy" 
                                
                                    
                                    messageProtectionOrder="SignBeforeEncrypt/SignBeforeEncryptAndEncryptSignature/EncryptBeforeSign"
                                
                                    
                                           
                                    
                                       messageSecurityVersion="WSSecurityJan2004/WSSecurityXXX2005"
                                
                                    
                                       requireDerivedKeys="Boolean"
                                
                                    
                                       requireSecurityContextCancellation="Boolean"
                                
                                    
                                       requireSignatureConfirmation="Boolean"
                                
                                    
                                           
                                    
                                       securityHeaderLayout=
                                
                                    
                                               
                                    
                                           "Strict/Lax/LaxTimestampFirst/LaxTimestampLast"
                                
                                    
                                       includeTimestamp="Boolean">
                                
                                    
                                       <issuedTokenParameters />
                                
                                    
                                       <localClientSettings />
                                
                                    
                                       <localServiceSettings />
                                
                                    
                                       <secureConversationBootstrap />
                                
                                    
                                    </security>

Attributes and Elements

The following sections describe attributes, child elements, and parent elements

Attributes

Attribute Description

allowSerializedSigningTokenOnReply

Optional. A Boolean value that specifies if a serialized token can be used on reply.

authenticationMode

Optional. Specifies the authentication mode used between the initiator and the responder. See below for all values.

The default is sspiNegotiated.

defaultAlgorithmSuite

Optional. Sets the message encryption and key-wrap algorithms. The algorithms and the key sizes are determined by the SecurityAlgorithmSuite class. These algorithms map to those specified in the Security Policy Language (WS-SecurityPolicy) specification.

Possible values are shown below. The default value is Basic128.

This attribute is used when working with a different platform that opts for a set of algorithms different than the default. You should be aware of the strengths and weaknesses of the relevant algorithms when making modifications to this setting. This attribute is of type SecurityAlgorithmSuite. The default is Aes256.

includeTimestamp

A Boolean value that specifies whether time stamps are included in each message. The default is true.

keyEntropyMode

Specifies the way that keys for securing messages are computed. Keys can be based on the client key material only, on the service key material only or a combination of both. Valid values are

  • ClientEntropy: The session key is based on key data provided by the client.

  • ServerEntropy: The session key is based on key data provided by the server.

  • CombinedEntropy: The session key is based on the key data provided by the client and service.

The default is CombinedEntropy.

This attribute is of type SecurityKeyEntropyMode.

messageProtectionOrder

Sets the order in which message level security algorithms are applied to the message. Valid values include the following:

  • SignBeforeEncrypt: Sign first, then encrypt.

  • SignBeforeEncryptAndEncryptSignature: Sign first, encrypt, then encrypt the signature.

  • EncryptBeforeSign: Encrypt first, then sign.

The default is SignBeforeEncrypt.

This attribute is of type MessageProtectionOrder.

messageSecurityVersion

Optional. Sets the version of WS-Security that is used. Valid values include the following:

  • WSSecurity11WSTrustFebruary2005WSSecureConversationFebruary2005WSSecurityPolicy11

  • WSSecurity10WSTrustFebruary2005WSSecureConversationFebruary2005WSSecurityPolicy11BasicSecurityProfile10

  • WSSecurity11WSTrustFebruary2005WSSecureConversationFebruary2005WSSecurityPolicy11BasicSecurityProfile10

The default is WSSecurity11WSTrustFebruary2005WSSecureConversationFebruary2005WSSecurityPolicy11 and can be expressed in the XML as simply Default. This attribute is of type MessageSecurityVersion.

requireDerivedKeys

A Boolean value that specifies if keys can be derived from the original proof keys. The default is true.

requireSecurityContextCancellation

Optional. A Boolean value that specifies if security context should be cancelled and terminated when it is no longer needed. The default is true.

requireSignatureConfirmation

Optional. A Boolean value that specifies whether WS-Security signature confirmation is enabled. When set to true, message signatures are confirmed by the responder. The default is false.

Signature confirmation is used to confirm that the service is responding in full awareness of a request.

securityHeaderLayout

Optional. Specifies the ordering of the elements in security header. Valid values are

  • Strict: Items are added to the security header according to the general principle of “declare before use”.

  • Lax: Items are added to the security header in any order that confirms to WSS: SOAP Message security.

  • LaxWithTimestampFirst: Items are added to the security header in any order that confirms to WSS: SOAP Message security except that the first element in the security header must be a wsse:Timestamp element.

  • LaxWithTimestampLast: Items are added to the security header in any order that confirms to WSS: SOAP Message security except that the last element in the security header must be a wsse:Timestamp element.

The default is Strict.

This element is of type SecurityHeaderLayout.

authenticationMode Attribute

Value Description

String

AnonymousForCertificate

AnonymousForSslNegotiated

CertificateOverTransport

IssuedToken

IssuedTokenForCertificate

IssuedTokenForSslNegotiated

IssuedTokenOverTransport

Kerberos

KerberosOverTransport

MutualCertificate

MutualCertificateDuplex

MutualSslNegotiated

SecureConversation

SspiNegotiated

UserNameForCertificate

UserNameForSslNegotiated

UserNameOverTransport

SspiNegotiatedOverTransport

defaultAlgorithm Attribute

Value Description

Basic128

Use Aes128 encryption, Sha1 for message digest, and Rsa-oaep-mgf1p for key wrap.

Basic192

Use Aes192 encryption, Sha1 for message digest, Rsa-oaep-mgf1p for key wrap.

Basic256

Use Aes256 encryption, Sha1 for message digest, Rsa-oaep-mgf1p for key wrap.

Basic256Rsa15

Use Aes256 for message encryption, Sha1 for message digest and Rsa15 for key wrap.

Basic192Rsa15

Use Aes192 for message encryption, Sha1 for message digest and Rsa15 for key wrap.

TripleDes

Use TripleDes encryption, Sha1 for message digest, Rsa-oaep-mgf1p for key wrap.

Basic128Rsa15

Use Aes128 for message encryption, Sha1 for message digest and Rsa15 for key wrap.

TripleDesRsa15

Use TripleDes encryption, Sha1 for message digest and Rsa15 for key wrap.

Basic128Sha256

Use Aes256 for message encryption, Sha256 for message digest and Rsa-oaep-mgf1p for key wrap.

Basic192Sha256

Use Aes192 for message encryption, Sha256 for message digest and Rsa-oaep-mgf1p for key wrap.

Basic256Sha256

Use Aes256 for message encryption, Sha256 for message digest and Rsa-oaep-mgf1p for key wrap.

TripleDesSha256

Use TripleDes for message encryption, Sha256 for message digest and Rsa-oaep-mgf1p for key wrap.

Basic128Sha256Rsa15

Use Aes128 for message encryption, Sha256 for message digest and Rsa15 for key wrap.

Basic192Sha256Rsa15

Use Aes192 for message encryption, Sha256 for message digest and Rsa15 for key wrap.

Basic256Sha256Rsa15

Use Aes256 for message encryption, Sha256 for message digest and Rsa15 for key wrap.

TripleDesSha256Rsa15

Use TripleDes for message encryption, Sha256 for message digest and Rsa15 for key wrap.

Child Elements

Element Description

<issuedTokenParameters>

Specifies a current issued token. This element is of type IssuedTokenParametersElement.

localClientSettings element

Specifies the security settings of a local client for this binding. This element is of type LocalClientSecuritySettingsElement.

localServiceSettings element

Specifies the security settings of a local service for this binding. This element is of type LocalServiceSecuritySettingsElement.

<secureConversationBootstrap>

Specifies the default values used for initiating a secure conversation service.

Parent Elements

Element Description

<binding>

Defines all binding capabilities of the custom binding.

Example

The following example demonstrates how to configure security using a custom binding. It shows how to use a custom binding to enable message-level security together with a secure transport. This is useful when a secure transport is required to transmit the messages between client and service and simultaneously the messages must be secure on the message level. This configuration is not supported by system-provided bindings.

The service configuration defines a custom binding that supports TCP communication protected using TLS/SSL protocol, and Windows message security. The custom binding uses a service certificate to authenticate the service on the transport level and to protect the messages during the transmission between client and service. This is accomplished by the <sslStreamSecurity> binding element. The service's certificate is configured using a service behavior.

Additionally, the custom binding uses message security with Windows credential type - this is the default credential type. This is accomplished by the <security> of <customBinding> binding element. Both client and service are authenticated using message-level security if Kerberos authentication mechanism is available. If the Kerberos authentication mechanism is not available, NTLM authentication is used. NTLM authenticates the client to the service but does not authenticate service to the client. The <security> of <customBinding> binding element is configured to use SecureConversation authenticationType, which results in the creation of a security session on both the client and the service. This is required to enable the service's duplex contract to work. For more information on running this example, see Custom Binding Security

<configuration>
  <system.serviceModel>
    <services>
      <service 
          name="Microsoft.ServiceModel.Samples.CalculatorService"
          behaviorConfiguration="CalculatorServiceBehavior">
        <host>
          <baseAddresses>
            <!-- use following base address -->
            <add baseAddress="net.tcp://localhost:8000/ServiceModelSamples/Service"/>
          </baseAddresses>
        </host>
        <endpoint address=""
                    binding="customBinding"
                    bindingConfiguration="Binding1" 
                    contract="Microsoft.ServiceModel.Samples.ICalculatorDuplex" />
        <!-- the mex endpoint is exposed at net.tcp://localhost:8000/ServiceModelSamples/service/mex -->
        <endpoint address="mex"
                  binding="mexTcpBinding"
                  contract="IMetadataExchange" />
      </service>
    </services>

    <bindings>
      <!-- configure a custom binding -->
      <customBinding>
        <binding name="Binding1">
          <security authenticationMode="SecureConversation"
                     requireSecurityContextCancellation="true">
          </security>
          <textMessageEncoding messageVersion="Soap12WSAddressing10" writeEncoding="utf-8"/>
          <sslStreamSecurity requireClientCertificate="false"/>
          <tcpTransport/>
        </binding>
      </customBinding>
    </bindings>

    <!--For debugging purposes set the includeExceptionDetailInFaults attribute to true-->
    <behaviors>
      <serviceBehaviors>
        <behavior name="CalculatorServiceBehavior">
          <serviceMetadata />
          <serviceDebug includeExceptionDetailInFaults="False" />
          <serviceCredentials>
            <serviceCertificate findValue="localhost" storeLocation="LocalMachine" storeName="My" x509FindType="FindBySubjectName"/>
          </serviceCredentials>
        </behavior>
      </serviceBehaviors>
    </behaviors>
  </system.serviceModel>
</configuration>

See Also

Reference

SecurityElement

Footer image

Send comments about this topic to Microsoft.
© Microsoft Corporation. All rights reserved.