CA API Gateway 9.1

9.4 9.1

(Non-SOAP) Verify XML Element Assertion

The (Non-SOAP) Verify XML Element assertion is used to immediately verify one or more Signature elements in an XML message (either request, response, or a message context variable).
gateway90
The (Non-SOAP) Verify XML Element assertion is used to immediately verify one or more Signature elements in an XML message (either request, response, or a message context variable).
This assertion supports the special prefix "local:" in the ID attribute, for matching the namespace URI against the owning element rather than the attribute.
To learn about selecting the target message for this assertion, see Select a Target Message.
Context Variables Created by This Assertion
The (Non-SOAP) Verify XML Element assertion sets the following context variables with details of the verification. Note: The <prefix> is set in the assertion properties and is optional. There is no default.
Variable
Description
<prefix>.
elementsVerified
Lists the elements that were verified.
Detailed technical view
The elementsVerified are the target elements covered by the signature. A ds:Signature element created by third-party software (or by the
API Gateway
 or the CA API Gateway - XML VPN Client, if using WSS) may cover many elements with a single signature. Each covered element has its own row in this table, though the signatureElements column will contain the same ds:Signature element for each such row. Multiple levels of multi-matching are possible:
  • The XPath may match more than one ds:Signature element. Every matching Signature will be verified.
  • Each ds:Signature may have references to more than one covered element. Each covered element will be included in its own row in the results table.
<prefix>.
signatureMethodUris
Lists the signature methods used.
<prefix>.
digestMethodUris
Lists the digest methods used.
<prefix>.
signingCertificates
Lists the X.509 certificates used to sign the elements.
<prefix>.
signatureValues
Lists the signature values in Base-64 format.
<prefix>.s
ignatureElements
Lists the ds:Signature elements for each signature.
Similar to the (Non-SOAP) Decrypt XML Element Assertion, all these context variables will always contain the same number of values. All (except for elementsVerified) may contain duplicate values as needed to ensure that the indexes always line up with the corresponding element.
Use the (Non-SOAP) Check Results from XML Verification Assertion to check that these results contain expected values.
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
    >:
    (Non-SOAP) Verify XML Element [XPath]
     in the policy window and select
    XML Element Verification Properties
     or double-click the assertion in the policy window. The assertion properties are displayed. 
  3. Configure the properties as follows:
  4. Click [
    OK
    ].
Setting
Description
Edit XPath
Click [
Edit XPath
] to specify the dsig:Signature element(s) to verify. For more information, see Select an XPath.
Variable prefix
Optionally, 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.
Signature Settings
Expect KeyInfo in signature element (default)
Choose this option to use the certificate identified by the <ds:keyInfo> element within the signature in the message. This setting is the default.
The certificate is for the default recipient. To override this default recipient, see Change the WSS Assertion Recipient.
Use selected certificate for signature validation
Choose this option to browse for the certificate to use. Click [
Select
] and then locate the certificate. The certificate details will appear in the Name, Subject, and Issued By fields. Examine the details to ensure that it is the correct certificate.
Look up certificate by name
Choose this option to manually specify the certificate to use for validation.
Ensure that the specified certificate exists, otherwise the assertion will fail.
Use certificate from context variable
Choose this option to specify a context variable that will resolve to the certificate name at run time. If more than one certificate matches the name, then the first valid certificate is used.
Always override KeyInfo in signature element with selected certificate
Select this check box to always use the selected certificate, regardless of whether the <ds:keyInfo> element specifies a certificate.
Clear this check box to use the selected certificate only if the <ds:keyInfo> element does not specify a certificate. If it does, it will be used instead of the selected certificate. This setting is the default.
This option is available only when a certificate has been manually selected.
Recognize only the following ID attributes
Select this check box to specify the attribute names to recognize when looking for the elements that a signature may reference.
To add an attribute
:
  1. Click [
    Add
    ].
  2. Enter the ID attribute either as a NAME (e.g., NewAttr) or {URI}NAME (e.g., {urn:oasis:names:tc:SAML:2.0:assertion}NewAttr).
  3. Click [
    OK
    ].
To remove an attribute
:
  1. Select the line to remove.
  2. Click [
    Remove
    ].
Clear this check box to recognize only the default set of ID attributes:
{http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd}Id
{http://schemas.xmlsoap.org/ws/2002/07/utility}Id
{http://schemas.xmlsoap.org/ws/2003/06/utility}Id
{urn:oasis:names:tc:SAML:1.0:assertion}AssertionID
{urn:oasis:names:tc:SAML:2.0:assertion}ID
Id
id
ID
The special prefix "local:" in the ID attribute matches the namespace URI against the owning element rather than the attribute. All other prefixes are ignored.

Content feedback and comments