<mutualCertificate11Security> Element

  • Article

Represents a turnkey security assertion that uses X509SecurityToken security tokens to authenticate the client and protect SOAP messages. WS-Security 1.1 is required for this assertion.

<policies> Element
  <policy> Element (Policy)

<mutualCertificate11Security
  clientActor
  establishSecurityContext="true|false"
  messageProtectionOrder="Signature and encryption order"
  renewExpiredSecurityContext="true|false"
  requireDerivedKeys="true|false"
  requireSignatureConfirmation="true|false"
  serviceActor
  ttlInSeconds >
  <clientToken/>
  <serviceToken/>
  <protection/>
</mutualCertificate11Security >

Microsoft.Web.Services3.Design.MutualCertificate11Assertion

Attributes and Elements

Attributes

Attribute Description

clientActor

Optional attribute. Specifies the actor attribute on the Security SOAP header for a SOAP message that is destined for a Web service client to which this policy assertion applies. When the SOAP message is not routed through an intermediary, such as a SOAP router, the actor attribute is an empty string (""). When the policy assertion applies to an intermediary, specify the URI for the intermediary. The default value is an empty string ("").

establishSecurityContext

Optional attribute. Specifies whether a secure conversation is established using SecurityContextToken security tokens. Possible values are true or false. true specifies that this security assertion secures the security token request and its response (the RST and RSTR) and SOAP messages exchanged between the client and the Web service are secured using SecurityContextToken security tokens. The default value is false.

messageProtectionOrder

Optional attribute. Specifies the order of operation for digital signatures and message encryption. SignBeforeEncrypt specifies that a digital signature is generated for the SOAP message before any portion of the SOAP message is encrypted, but the digital signature is not encrypted. SignBeforeEncryptAndEncryptSignature specifies that a digital signature is generated for the SOAP message before any portion of the SOAP message is encrypted, and the digital signature is encrypted.

renewExpiredSecurityContext

Optional attribute. Specifies that a new SecurityContextToken security token is automatically requested as the current one expires when a secure conversation is established. This is applicable only when the establishSecurityContext attribute for this policy assertion is true.

requireDerivedKeys

Optional attribute. Specifies whether DerivedKeyToken security tokens are used. Possible values are true and false. The default value is false.

requireSignatureConfirmation

Optional attribute. Specifies whether the Web service sends a confirmation that verifies the client's digital signature and whether the client rejects SOAP responses without a signature confirmation. The default value is false.

serviceActor

Optional attribute. Specifies the actor attribute on the Security SOAP header for a SOAP message destined for a Web service to which this policy assertion applies. When the SOAP message is not routed through an intermediary, such as a SOAP router, the actor attribute is an empty string (""). When the policy assertion applies to an intermediary, specify the URI for the intermediary. The default value is an empty string ("").

Note

When the serviceActor attribute is set to a value other than an empty string (""), then the establishSecurityContext attribute must be set to false.

ttlInSeconds

Optional attribute. Specifies the default number of seconds that a SOAP message is valid after its creation. The default value is 5 minutes (300 seconds).

Child Elements

Element Description

<clientToken> Element

Optional element. Specifies the security token that authenticates the client.

<protection> Element

Optional element. Specifies the SOAP message parts that are signed and/or encrypted.

<serviceToken> Element (Policy)

Optional element. Specifies the X509SecurityToken security token that protects the SOAP messages.

If the details of the X509SecurityToken security token are not specified in the policy file, the security token must be specified using code.

Parent Elements

Element Description

<policy> Element

Specifies a SOAP message requirement.

Remarks

A security assertion can have zero or more <protection> elements. Use more than one <protection> element to apply protection requirements for each operation using the requestAction attribute. Each of the <protection> elements must have a unique requestAction attribute unless the requestAction is omitted. Only one of the <protection> elements can omit the requestAction attribute, and that element defines the default protection requirements for the policy.

The mutualCertificate10 turnkey security assertion is similar to this policy assertion, except it is intended to be used with WS-Security 1.0 and the security tokens that are used to digitally sign and encrypt SOAP messages are different. For more details about the mutualCertificate10 turnkey security assertion, see <mutualCertificate10Security> Element.

SOAP requests sent by the client and SOAP responses sent by the Web service are protected as specified in the following table.

SOAP message Protection Description

SOAP request

Digital Signature

The SOAP message parts specified in the <request> child element of the <protection> element are digitally signed using the client's X509SecurityToken security token.

SOAP request

Encryption

The SOAP message parts specified in the <request> child element of the <protection> element are encrypted using a EncryptedKeyToken security token that is created using the Web service's X509SecurityToken security token.

SOAP response

Digital Signature

The SOAP message parts specified in the <response> or <fault> child elements of the <protection> element are digitally signed using the Web service's X509SecurityToken security token.

SOAP response

Encryption

The SOAP message parts specified in the <response> or <fault> child elements of the <protection> element are encrypted using the X509SecurityToken security token that digitally signed the SOAP request.

Example

The following code example demonstrates how to secure a SOAP message exchange using the mutualCertificate11Security turnkey security assertion.

<policies>
  <extensions>
    <extension name="mutualCertificate11Security" type="Microsoft.Web.Services3.Design.MutualCertificate11Assertion, Microsoft.Web.Services3, Version=3.0.0.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35" />
    <extension name="x509" type="Microsoft.Web.Services3.Design.X509TokenProvider, Microsoft.Web.Services3, Version=3.0.0.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35" />
    <extension name="requireActionHeader"
               type="Microsoft.Web.Services3.Design.RequireActionHeaderAssertion, Microsoft.Web.Services3, Version=3.0.0.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35" />
  </extensions>
  <policy name="ClientPolicy">
    <mutualCertificate11Security 
      establishSecurityContext="false" 
      renewExpiredSecurityContext="true" 
      requireSignatureConfirmation="false" 
      messageProtectionOrder="SignBeforeEncrypt" 
      requireDerivedKeys="true" >
      <clientToken>
        <x509 
          storeLocation="CurrentUser"
          storeName="My"
          findValue="CN=WSE2QuickStartClient"
          findType="FindBySubjectDistinguishedName" />
      </clientToken>
      <serviceToken>
        <x509
          storeLocation="CurrentUser"
          storeName="AddressBook"
          findValue="CN=WSE2QuickStartServer"
          findType="FindBySubjectDistinguishedName" />
      </serviceToken>
      <protection>
        <request
          signatureOptions="IncludeAddressing, IncludeTimestamp, IncludeSoapBody"
          encryptBody="true" />
        <response 
          signatureOptions="IncludeAddressing, IncludeTimestamp, IncludeSoapBody"
          encryptBody="true" />
        <fault
          signatureOptions="IncludeAddressing, IncludeTimestamp, IncludeSoapBody"
          encryptBody="false" />
      </protection>
    </mutualCertificate11Security>
    <requireActionHeader />
  </policy>
</policies>

See Also

Tasks

How to: Secure a Web Service Using a Policy File

Reference

<mutualCertificate10Security> Element
<serviceToken> Element (Policy)
<clientToken> Element
<protection> Element
<policy> Element
X509SecurityToken

Concepts

Turnkey Security Assertions

Other Resources

Implementing Message Layer Security with X.509 Certificates in WSE 3.0
X.509 Technical Supplement