Red Hat DocumentationFuse ESBToggle FramesPrintFeedback

Specifying an AsymmetricBinding Policy

Overview

The asymmetric binding policy implements SOAP message protection using asymmetric key algorithms (public/private key combinations) and does so at the SOAP layer. The encryption and signing algorithms used by the asymmetric binding are similar to the encryption and signing algorithms used by SSL/TLS. A crucial difference, however, is that SOAP message protection enables you to select particular parts of a message to protect (for example, individual headers, body, or attachments), whereas transport layer security can operate only on the whole message.

Policy subject

An asymmetric binding policy must be applied to an endpoint policy subject (see Endpoint policy subject). For example, given the asymmetric binding policy with ID, MutualCertificate10SignEncrypt_IPingService_policy, you could apply the policy to an endpoint binding as follows:

<wsdl:binding name="MutualCertificate10SignEncrypt_IPingService" type="i0:IPingService">
  <wsp:PolicyReference URI="#MutualCertificate10SignEncrypt_IPingService_policy"/>
  ...
</wsdl:binding>

Syntax

The AsymmetricBinding element has the following syntax:

<sp:AsymmetricBinding xmlns:sp="..." ... >
  <wsp:Policy xmlns:wsp="...">
  (
   <sp:InitiatorToken>
     <wsp:Policy> ... </wsp:Policy>
   </sp:InitiatorToken>
  ) | (
   <sp:InitiatorSignatureToken>
     <wsp:Policy> ... </wsp:Policy>
   </sp:InitiatorSignatureToken>
   <sp:InitiatorEncryptionToken>
     <wsp:Policy> ... </wsp:Policy>
   </sp:InitiatorEncryptionToken>
  )
  (
   <sp:RecipientToken>
     <wsp:Policy> ... </wsp:Policy>
   </sp:RecipientToken>
  ) | (
   <sp:RecipientSignatureToken>
     <wsp:Policy> ... </wsp:Policy>
   </sp:RecipientSignatureToken>
   <sp:RecipientEncryptionToken>
     <wsp:Policy> ... </wsp:Policy>
   </sp:RecipientEncryptionToken>
  )
   <sp:AlgorithmSuite ... > ... </sp:AlgorithmSuite>
   <sp:Layout ... > ... </sp:Layout> ?
   <sp:IncludeTimestamp ... /> ?
   <sp:EncryptBeforeSigning ... /> ?
   <sp:EncryptSignature ... /> ?
   <sp:ProtectTokens ... /> ?
   <sp:OnlySignEntireHeadersAndBody ... /> ?
   ...
  </wsp:Policy>
  ...
</sp:AsymmetricBinding>

Sample policy

Example 13 shows an example of an asymmetric binding that supports message protection with signatures and encryption, where the signing and encryption is done using pairs of public/private keys (that is, using asymmetric cryptography). This example does not specify which parts of the message should be signed and encrypted, however. For details of how to do that, see Specifying Parts of Message to Encrypt and Sign.

Example 13. Example of an Asymmetric Binding

<wsp:Policy wsu:Id="MutualCertificate10SignEncrypt_IPingService_policy">
  <wsp:ExactlyOne>
    <wsp:All>
      <sp:AsymmetricBinding
          xmlns:sp="http://schemas.xmlsoap.org/ws/2005/07/securitypolicy">
        <wsp:Policy>
          <sp:InitiatorToken>
            <wsp:Policy>
              <sp:X509Token
                  sp:IncludeToken="http://schemas.xmlsoap.org/ws/2005/07/securitypolicy/IncludeToken/AlwaysToRecipient">
                <wsp:Policy>
                  <sp:WssX509V3Token10/>
                </wsp:Policy>
              </sp:X509Token>
            </wsp:Policy>
          </sp:InitiatorToken>
          <sp:RecipientToken>
            <wsp:Policy>
              <sp:X509Token
                  sp:IncludeToken="http://schemas.xmlsoap.org/ws/2005/07/securitypolicy/IncludeToken/Never">
                <wsp:Policy>
                  <sp:WssX509V3Token10/>
                </wsp:Policy>
              </sp:X509Token>
            </wsp:Policy>
          </sp:RecipientToken>
          <sp:AlgorithmSuite>
            <wsp:Policy>
              <sp:Basic256/>
            </wsp:Policy>
          </sp:AlgorithmSuite>
          <sp:Layout>
            <wsp:Policy>
              <sp:Lax/>
            </wsp:Policy>
          </sp:Layout>
          <sp:IncludeTimestamp/>
          <sp:EncryptSignature/>
          <sp:OnlySignEntireHeadersAndBody/>
        </wsp:Policy>
      </sp:AsymmetricBinding>
      <sp:Wss10 xmlns:sp="http://schemas.xmlsoap.org/ws/2005/07/securitypolicy">
        <wsp:Policy>
          <sp:MustSupportRefKeyIdentifier/>
          <sp:MustSupportRefIssuerSerial/>
        </wsp:Policy>
      </sp:Wss10>
    </wsp:All>
  </wsp:ExactlyOne>
</wsp:Policy>

sp:InitiatorToken

The initiator token refers to the public/private key-pair owned by the initiator. This token is used as follows:

  • The token's private key signs messages sent from initiator to recipient.

  • The token's public key verifies signatures received by the recipient.

  • The token's public key encrypts messages sent from recipient to initiator.

  • The token's private key decrypts messages received by the initiator.

Confusingly, this token is used both by the initiator and by the recipient. However, only the initiator has access to the private key so, in this sense, the token can be said to belong to the initiator. In Basic Signing and Encryption Scenario, the initiator token is the certificate, Alice.

This element should contain a nested wsp:Policy element and sp:X509Token element as shown. The sp:IncludeToken attribute is set to AlwaysToRecipient, which instructs the runtime to include Alice's public key with every message sent to the recipient. This option is useful, in case the recipient wants to use the initiator's certificate to perform authentication. The most deeply nested element, WssX509V3Token10 is optional. It specifies what specification version the X.509 certificate should conform to. The following alternatives (or none) can be specified here:

sp:WssX509V3Token10

This optional element is a policy assertion that indicates that an X509 Version 3 token should be used.

sp:WssX509Pkcs7Token10

This optional element is a policy assertion that indicates that an X509 PKCS7 token should be used.

sp:WssX509PkiPathV1Token10

This optional element is a policy assertion that indicates that an X509 PKI Path Version 1 token should be used.

sp:WssX509V1Token11

This optional element is a policy assertion that indicates that an X509 Version 1 token should be used.

sp:WssX509V3Token11

This optional element is a policy assertion that indicates that an X509 Version 3 token should be used.

sp:WssX509Pkcs7Token11

This optional element is a policy assertion that indicates that an X509 PKCS7 token should be used.

sp:WssX509PkiPathV1Token11

This optional element is a policy assertion that indicates that an X509 PKI Path Version 1 token should be used.

sp:RecipientToken

The recipient token refers to the public/private key-pair owned by the recipient. This token is used as follows:

  • The token's public key encrypts messages sent from initiator to recipient.

  • The token's private key decrypts messages received by the recipient.

  • The token's private key signs messages sent from recipient to initiator.

  • The token's public key verifies signatures received by the initiator.

Confusingly, this token is used both by the recipient and by the initiator. However, only the recipient has access to the private key so, in this sense, the token can be said to belong to the recipient. In Basic Signing and Encryption Scenario, the recipient token is the certificate, Bob.

This element should contain a nested wsp:Policy element and sp:X509Token element as shown. The sp:IncludeToken attribute is set to Never, because there is no need to include Bob's public key in the reply messages.

Note

In Fuse Services Framework, there is never a need to send Bob's or Alice's token in a message, because both Bob's certificate and Alice's certificate are provided at both ends of the connection—see Providing Encryption Keys and Signing Keys.

sp:AlgorithmSuite

This element specifies the suite of cryptographic algorithms to use for signing and encryption. For details of the available algorithm suites, see Specifying the Algorithm Suite.

sp:Layout

This element specifies whether to impose any conditions on the order in which security headers are added to the SOAP message. The sp:Lax element specifies that no conditions are imposed on the order of security headers. The alternatives to sp:Lax are sp:Strict, sp:LaxTimestampFirst, or sp:LaxTimestampLast.

sp:IncludeTimestamp

If this element is included in the policy, the runtime adds a wsu:Timestamp element to the wsse:Security header. By default, the timestamp is not included.

sp:EncryptBeforeSigning

If a message part is subject to both encryption and signing, it is necessary to specify the order in which these operations are performed. The default order is to sign before encrypting. But if you include this element in your asymmetric policy, the order is changed to encrypt before signing.

Note

Implicitly, this element also affects the order of the decryption and signature verification operations. For example, if the sender of a message signs before encrypting, the receiver of the message must decrypt before verifying the signature.

sp:EncryptSignature

This element specifies that the message signature must be encrypted (by the encryption token, specified as described in Providing Encryption Keys and Signing Keys). Default is false.

Note

The message signature is the signature obtained directly by signing various parts of the message, such as message body, message headers, or individual elements (see Specifying Parts of Message to Encrypt and Sign). Sometimes the message signature is referred to as the primary signature, because the WS-SecurityPolicy specification also supports the concept of an endorsing supporting token, which is used to sign the primary signature. Hence, if an sp:EndorsingSupportingTokens element is applied to an endpoint, you can have a chain of signatures: the primary signature, which signs the message itself, and the secondary signature, which signs the primary signature.

For more details about the various kinds of endorsing supporting token, see SupportingTokens assertions.

sp:ProtectTokens

This element specifies that signatures must cover the token used to generate that signature. Default is false.

sp:OnlySignEntireHeadersAndBody

This element specifies that signatures can be applied only to an entire body or to entire headers, not to sub-elements of the body or sub-elements of a header. When this option is enabled, you are effectively prevented from using the sp:SignedElements assertion (see Specifying Parts of Message to Encrypt and Sign).

Comments powered by Disqus