CA API Gateway 9.1

9.4 9.1

Require Signed Element Assertion

The Require Signed Element assertion is used to enforce that specific message elements in the target message have been signed by the specified identity.
gateway90
The 
Require Signed Element 
assertion is used to enforce that specific message elements in the target message have been signed by the specified identity.
You can add a Require Signed Element assertion for each element of the target message that you want to verify as signed. This assertion supports WS-Security 1.0 and 1.1.
To learn about selecting the target message for this assertion, see Select a Target Message.
To learn more about selecting the target identity for this assertion, see Select a Target Identity.
Setting the WSS recipient to one other than "Default" will cause the Require Signed Element assertion to always succeed. For more information, see Change the WSS Assertion Recipient.
The Require Signed Element assertion is intended for use in web service policies. If the target is the response message, ensure the assertion is placed
after
 the routing assertion. If the target is the request message, the assertion should be placed
before
 the routing assertion and that a credential assertion is present in the policy: Require WS-Security Signature Credentials, Require WS-Secure Conversation, Require WS-Security Kerberos Token Profile Credentials, Require SAML Token Profile, or Require Encrypted UsernameToken Profile Credentials.
Context Variables Created by This Assertion
The Require Signed Element assertion sets the following context variables.
(1) The 
<prefix>
 is defined in the assertion properties. (2) There is no default prefix—if no prefix is specified in the properties, then no context variables will be set by this assertion.
Variable
Description
${
<prefix>
.element}
Contains the signature element.
${
<prefix>
.token.type}
Contains the token type, retrieved from the following sources for each token type:
  • For
    Kerberos
    , from a WSS Kerberos assertion
  • For
    SAML
    , from a version 1.1 or 2.0 SAML token
  • For
    SymmetricKey
    , from an EncryptedUsernameToken or Require WS-Secure Conversation assertion
  • For
    X.509
    , from a BinarySecurityToken, Issuer/Serial reference or SubjectKeyIdentifier reference
${
<prefix>
.token. element}
Contains the security token element, such as a binary security token. May be empty for some token types.
${
<prefix>
.token.attributes.*}
Contains the token attributes; one variable will be created for each attribute. Note that certain attributes may be empty depending on the token type.
  • ${
    <prefix>
    .token.element}:
     .
  • ${
    <prefix>
    .token.attributes.*}:
  • For the X.509 token type, the available attributes are the same as for a certificate.
  • For the SAML token type, the following attributes may be present:
issuer.certificate:
 The certificate of the SAML issuer.
subject.certificate:
 The certificate of the SAML subject.
signing.certificate:
 The certificate used to sign the message.
For each of these certificate attributes, the certificate attributes are available.
To learn more about the certificate attributes, see Certificate Attributes Variables under Context Variables.
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 
    <target>:
     Require Signed Element 
    in the policy window and select 
    Signed Element Properties
     or double-click the assertion in the policy window. The assertion properties are displayed. The title of the dialog will show "Request", "Response", or "${variableName}", depending on the target message.
  3. Specify the XPath and indicate which element from the target message must be signed in the code box. For detailed instructions on using the interface to build your XPath, see Select an XPath.
  4. Under 
    Accepted Signature Digests
    , select which digest algorithms are supported in the signature. By default, all the following signature digests are accepted: 
    SHA-1
    , 
    SHA-256
    , 
    SHA-384
    , 
    SHA-512
    .
  5. For 
    Variable Prefix
    , enter a prefix that will be added to the context variables created by this assertion. This prefix will ensure uniqueness and will prevent the variables from overwriting each other when multiple instances of this assertion appear in a policy.
    For an explanation of the validation messages displayed, see Context Variable Validation.
  6. Click [
    OK
    ].

Content feedback and comments