CA API Gateway 9.1

9.4 9.1

Configure WS-Security Decoration Assertion

The Configure WS-Security Decoration assertion is used to specify or override pending security decorations for a message.
gateway91
The
Configure WS-Security Decoration
 assertion is used to specify or override pending security decorations for a message.
2
This assertion provides a convenient location to set security attributes that were previously configured in other assertions:
Decoration
In tab
Originally set in...
WS-Security Version
[General]
Signature Digest Algorithm
[Signing]
Encryption Algorithm(s)
[Encryption]
Signature Key Reference
[Signing]
Encryption Key Reference
[Signing]
Add Timestamp
[General]
Security Token Signing
[Signing]
Key Encryption Algorithm
[Encryption]
new option
Use DerivedKey Token
[Advanced]
new option
(1) Decorations that were originally set elsewhere can continue to be configured in those other assertions as well. (2) The Configure WS-Security Decoration assertion can be used to remove the timestamp in the policy: add it after the Add Security Token assertion and configure the properties to clear the Add Timestamp check boxes in the [General] and [Signing] tabs.
To learn about selecting the target message for this assertion, see Select a Target Message.
To learn more about selecting a private key for this assertion, see Select a Custom Private Key.
To learn more about changing the WSS Recipient for this assertion, see Change the WSS Assertion Recipient.
Applying WS-Security
If this assertion targets a message other than the response, you must add the Add or Remove WS-Security assertion after the Configure WS-Security Decoration assertion in the policy for the decorations to be applied:
Request: Configure WS-Security Decoration
Request: Apply WS-Security
To learn about selecting the target message for this assertion, see Select a Target Message.
When WS-Security is involved, be sure to specify the appropriate WSS header handling option in the routing assertion's properties. In most instances, the setting "Don't modify the request Security header" is usually appropriate.
Using the Assertion
  1. Do one of the following:
    • To add the assertion to the Policy Development window, see Add an Assertion. 
    • To change the configuration of an existing assertion, proceed to step 2 below.
  2. Right-click
    Configure WS-Security Decoration
     in the policy window and select
    Configure WS-Security Decoration Properties
     or double-click the assertion in the policy window. The assertion properties are displayed. These properties are organized across the following tabs:
    • General
    • Signing
    • Encryption
    • Advanced
  3. Configure each tab as necessary. Refer to the appropriate section below for a complete description of each tab.
    The "<
    Unchanged
    >" setting found in several of the tabs leaves the existing pending decoration requirement setting unchanged—this is not necessarily the same as leaving existing decoration in the message unchanged. Example: Suppose a message is currently signed using SHA-384. One of the pending decorations is a new signature that uses the default digest (which is SHA-1, as specified by the cluster property wss.decorator.digsig.messagedigest). When "<
    Unchanged
    >" is selected in the [
    Signing
    ] tab for Signature Digest Algorithm, the new signature will use SHA-1, not SHA-384.
  4. Click [
    OK]
     when done.
Configuring the [General] Tab
The [
General
] tab is used to request a specific version of WS-Security or to force a timestamp to be included.
  • WS-Security Version
    : Choose the WS-Security version to use: 1.0 or 1.1. The default "<
    Unchanged
    >" setting uses the version of WS-Security in the target message.
    The WS-Security version can also be set in the Add or Remove WS-Security Assertion.
  • Add Timestamp
    : Use this check box to add or remove a time stamp on the target message.
    (1) Timestamps can also be added (but not removed) using the Add Timestamp Assertion. (2) An existing timestamp will only be removed if the [
    Remove and recreate matching security header
    ] setting in the Add or Remove WS-Security Assertion is selected (which is the default).
Configuring the [Signing] Tab
The [
Signing
] tab is used to set signing-related decorations.
  • Signature Digest Algorithm
    : Choose the Signature Digest Algorithm to use:
    SHA-1
    ,
    SHA-256
    ,
    SHA-384
    ,
    SHA-512
    . The default "<
    Unchanged
    >" setting uses the algorithm in the target message's existing decoration requirements. 
The Signature Digest Algorithm can also be set in the Sign Element Assertion.
  • Reference Digest
    : Choose the Reference Digest to use:
    SHA-1
    ,
    SHA-256
    ,
    SHA-384
    ,
    SHA-512
    . The default "<
    Unchanged
    >" setting uses the algorithm in the target message's existing decoration requirements. 
  • Key Reference:
     Choose the signing key reference mechanism to use:
    BinarySecurityToken
    ,
    SubjectKeyIdentifier
    ,
    IssuerSerial
    ,
    StrKeyIdX509Literal
    . The default "<
    Unchanged
    >" setting uses the key reference in the target message's existing decoration requirements. 
  • Include Signed Timestamp
    : Select this check box to add a signed timestamp to SOAP header of the target message.
    (1) Signed timestamps can also be added (but not removed) using the Add Timestamp Assertion. (2) If [
    Include Signed Timestamp
    ] is disabled, but [
    Add Timestamp
    ] in the [
    General
    ] tab is enabled, then an unsigned timestamp will be added to the target message.
  • Sign Security Tokens
    : Select this check box to request that signing tokens be included in the message signature.
  • Encrypt Signature
    : Select this check box to include the signature in the elements to encrypt, marked as requiring whole-element encryption.
  • Sign WS-Addressing Headers
    : Select this check box to sign the WS-Addressing headers and any Layer 7 addressing headers present in the message.
    This option must be enabled to ensure compatibility when the CA API Gateway - XML VPN Client is used.
Configuring the [Encryption] Tab
The [
Encryption
] tab is used to configure encryption-related decorations.
  • Data Encryption Algorithm
    : Choose a symmetric encryption algorithm to use for data encryption. The default "<
    Unchanged
    >" setting uses the algorithm in the target message's pending decoration requirements. 
The data encryption algorithm can also be set in the Encrypt Element assertion.
CA Technologies recommends using one of the GCM algorithms when possible (assuming that the expected recipient can handle it). XML messages encrypted using CBC mode could potentially be decrypted by an adversary who can send multiple modified messages to servers that possess the decryption key and are running WS-Security software released before November 2011.
  • Key Encryption Algorithm
    : 
    Key Encryption Algorithms are public key encryption algorithms especially specified for encrypting and decrypting keys when adding an encrypted key to a message during security decoration. Their identifiers appear as Algorithm attributes to EncryptionMethod elements that are children of EncryptedKey. The following is an example of EncryptedKey with a Key Encryption Algorithm:
<EncryptedKey Id="uuid...">
      <EncryptionMethod Algorithm="http://www.w3.org/2001/04/xmlenc#rsa-oaep-mgf1p"/>
...
</EncryptedKey>
Choose a key encryption algorithm to use. The default "<Unchanged>" setting uses the algorithm in the target message's pending decoration requirements.
CA Technologies strongly recommends using RSA-OAEP whenever possible. Use RSA-1.5 only when absolutely necessary for interoperability.  
More information about RSA Identifiers
RSA 1.5 is the "RSAES-PKCS1-v1_5" algorithm specified in RFC 3447 (aka PKCS#1):
http://www.ietf.org/rfc/rfc3447.txt
RSA OAEP is the "RSAES-OAEP-ENCRYPT" algorithm, also specified in RFC 3447/PKCS#1. This is an implementation of OAEP, the "optimal asymmetric encryption padding" scheme.
RSA OAEP is more resistant to certain cryptographic attacks than RSA 1.5 but may be supported by less third-party software.
  • Key Reference
    : Choose a encryption key reference mechanism to use:
    IssuerSerial
    ,
    BinarySecurityToken
    , 
    KeyName
    ,
    SubjectKeyIdentifier
    , or
    StrKeyIdX509Literal
    . The default "<
    Unchanged
    >" setting uses the mechanism in the target message's pending decoration requirements. 
    The encryption key reference can also be set in the Encrypt Element Assertion.
Configuring the [Advanced] Tab
The [
Advanced
] tab is used to configure derived keys and to optionally select a WS-Secure Conversation Namespace.
  • Use Derived Keys Whenever Possible
    : Select this check box to request that derived keys be created and used whenever possible (that is, derived from the original signing or encryption token using a DerivedKeyToken). Derived keys can be used for signing or encryption if the signing or encryption method is a WS-SC session, an ephemeral EncryptedKey, a Kerberos token, or a SAML token that uses EncryptedKey subject confirmation.
  • WS-Secure Conversation Namespace
    : If using derived keys, you can choose the version or namespace of secure conversation that will be used with the derived keys. The default value "<
    Unchanged
    >" will not configure any value, which results in the default/current namespace being used.

Content feedback and comments