Protect Against Message Replay Assertion (Threat Protection)

Protect Against Message Replay
assertion is used to protect the
Layer7 API Gateway
against possible replay attacks.Note the following important issues when using this assertion:
  • Depending on the expiry period set in the assertion, using the Protect Against Message Replay assertion in a Gateway cluster may increase request message processing time and require more memory. To mitigate this, place this assertion after a Authenticate User or Group or Authenticate Against Identity Provider assertion to help confine the protection to successfully authenticated messages, thereby reducing system processing and memory requirements.
  • This assertion should not be used in any policy that will process messages from JMS destinations that are configured with the "On completion" acknowledgment mode without a specified failure queue.
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.
Be sure you have configured time synchronization between the Gateway nodes. Correct synchronization is critical for message replay detection. To configure time synchronization, see "Option 1 - Configure Networking and System Time Settings" in Gateway System Settings (Appliance)
Details for Advanced Users
The Protect Against Message Replay assertion uses an internal replay ID. This ID is based on either a WS-Addressing Message ID or the timestamp of the request combined with other information that depends on how the message was signed:
  • For a request message signed with a WS-Security one-shot X.509 signature, the replay ID is comprised of the following:
    • The SHA-1 of the WS-Addressing MessageID, if present, or the timestamp creation date
    • The signing certificate's subject and issuer DNs
    • The signing certificate's subject key identifier
  • For a request message signed with a key derived from a WS-SecureConversation security context, the replay ID is the MessageID or timestamp created date and the security context identifier.
  • For a request message signed with a key derived from an EncryptedKey, the replay ID is the MessageID or timestamp created date and the EncryptedKeySHA1 value.
  • For a request message signed with a WS-Security Kerberos token, the replay ID is the MessageID or timestamp created date and the SHA-1 of the Kerberos token.
In all cases, the granularity of the timestamps is determined by the message sender. While the
Layer7 API Gateway
- XML VPN Client always uses at least millisecond-granular timestamps (with a random count of up to one million nanoseconds, to reduce the chance of an ID collision), many tools will use second-granular timestamps by default, resulting in spurious duplicate IDs if MessageIDs are not used and more than one message is sent per second per signing identity.The Protect Against Message Replay assertion offers two different modes:
Default Mode
The assertion first attempts to use a signed WS-Addressing Message ID in the message as the basis for replay protection. If the
Layer7 API Gateway
- XML VPN Client is deployed, you can enforce the presence of Message IDs by using the Require WS-Addressing Assertion.
A Message ID that is present but not signed will not be used by the Protect Against Message Replay assertion. The assertion will use a signed time stamp instead, if one is available.If no Message ID is present (and the policy is not configured to enforce the presence of one), the message time stamp is used for replay protection. The Gateway rejects a message as a possible replay if detects any of the following:
  • A duplicate creation time stamp in a message
  • An expired time stamp is present
  • The creation time stamp is more than 30 days old.
Custom Mode
In this mode, you may specify a context variable that contains the identifier to check and how long the identifier should be saved. This allows you to verify non-SOAP messages. It will not perform signature verification or validate the timestamp.
The Custom mode only deals with checking for replay of the identifier. The policy administrator is responsible for ensuring that the identifier can be trusted and that the current time is within the time stamp created/expires times.The custom mode allows you to create your own custom replay protection policy fragment when combined with other assertions.
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
    Protect Against Message Replay
    in the policy window and select
    Message Replay Protection Properties
    or double-click the assertion in the policy window. The assertion properties are displayed.
  3. Configure the properties as follows:
    Choose the mode of operation: [
    ] or [
    ]. Refer to the introduction to this topic for a description of each mode.
    The replay scope lets you specify a scope for the uniqueness of the message identifier. For example, a message identifier scheme may be global, or per service, or could use some other granularity.Specify a scope for the uniqueness; context variables are permitted.
    Service scoped:
    Customer scoped:
    Customer 7
    (maximum 250 chars)
    Global scope:
    <leave blank>
    The scoping can be performed by the policy author (for example, by specifying an identifier as
    ) but such an approach risks collisions if other services do not use service-scoped identifiers.
    Identifier Variable
    Specify a context variable containing the Message ID to be processed.You can enter the variable in the format
    Ensure that this Message ID has been signed and is unique.
    Specify how long the identifier should be saved. This expiry time is the lifetime of the message—that is, the amount of time the identifier will be stored in the cache from the time it was received. The default is
    The expiry time should be greater than 0 and less than 25 days.
  4. Click [
    ] when done.