Generate Security Hash Assertion

The Generate Security Hash assertion is used to generate a signature or hash using a configurable hash algorithm .
gateway90
The 
Generate Security Hash
 assertion is used to generate a signature or hash using a configurable hash algorithm .
This assertion is configurable for specific HMAC+SHA algorithms or simply an SHA or MD5 algorithm.
CA Technologies
highly
recommends using HMAC algorithms, as non-HMAC algorithms produce weak hashing that can be exploited.
Examples
The following are examples of security hashes that are generated based on different inputs.
Using plain ASCII input:
Source data: ${var} Value of context variable named "var": a String type: "fred" Input characters: 4 characters: { f, r, e, d } Chars converted to bytes using UTF-8: 4 bytes: { 66, 72, 65, 64 } MD5 hash of these 4 bytes: 16 bytes: { 57, 0a, 90, bf, bf, 8c, 7e, ab, 5d, c5, d4, e2, 68, 32, d5, b1 } Base-64 encoding of MD5 hash 16 bytes: "VwqQv7+MfqtdxdTiaDLVsQ=="
Using UTF-8 character input:
Source data: ${var} Value of context variable named "var": a String type: "fr?d" Input characters: 4 characters: { f, r, ?, d } Chars converted to bytes using UTF-8: 5 bytes: { 66, 72, c3, aa, 64 } MD5 hash of these 5 bytes: 16 bytes: { 4e, bb, c0, c6, f7, 12, f6, 86, 97, 56, 9e, 99, 03, 9e, b0, 65 } Base-64 encoding of MD5 hash 16 bytes: "TrvAxvcS9oaXVp6ZA56wZQ=="
Using binary input:
Source data: ${var} Value of context variable named "var": a Message type: application/octet-stream: containing 6 body bytes: { 2E, 00, FF, 1F, 7E, 01 } Input bytes: 6 bytes: { 2e, 00, ff, 1f, 7e, 01 } MD5 hash of these 6 bytes: 16 bytes: { 0b, 93, 3c, df, f1, df, 80, 04, f5, f8, 4e, 75, e8, 51, 7c, 11 } Base-64 encoding of MD5 hash 16 bytes: "C5M83/HfgAT1+E516FF8EQ=="
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. This assertion contains default settings that are appropriate for most instances. To change any of the settings, right-click 
    Generate Security Hash
     in the policy window and select
     Generate Security Hash
     or double-click the assertion in the policy window. The assertion properties are displayed. 
  3. Configure the properties as follows:
    Setting
    Description
    Source Data
    Enter the data that will have the Signature Algorithm applied to it. You may enter text or specify a context variable. You may also enter an expression that combines static text with context variables.
    Save line breaks as
    Select the line break option for the source data entered above:
    CR LF
    (carriage return, line feed),
    LF
    (line feed),
    CR
    (carriage return). The default is
    CR LF
    .
    Output Variable
    Enter the name of the context variable that will hold the generated signature.
    TECHNICAL NOTE: Output values
    The output value is:
         Base64( Hash( Input ) ) 
    if using a non-keyed hash (such as MD5, SHA-1, etc.)
         Base64( HMAC( Key, Input ) ) 
    if using keyed hash (such as HMAC-SHA1, HMAC-SHA256, etc.)
    Where:
     
    - Key
    is the key value bytes (with strings converted to bytes using UTF-8)
     
    - Input
    is the input value bytes (with strings converted to bytes using UTF-8)
     
    -
    Hash/HMAC
    is the selected transformation (MD5, SHA-1, HMAC-SHA256, etc.)
     
    - Base64
    is the "encode bytes as Base-64" operation
    Note the following:
    • To obtain the raw binary value of the hash, use the Encode/Decode Data Assertion to decode the Base64-encoded hash.
    • To obtain a hex encoded version of the value, use the Encode/Decode Data Assertion to Base64-decode it to Message data type, then Base16-encode it to String.
    Signature Algorithm
    Choose the algorithm to use from the drop-down list: 
    HMAC-MD5HMAC-SHA1
    HMAC-SHA256
    HMAC-SHA384
    HMAC-SHA512
    MD5
    SHA-1
    SHA-256
    SHA-384
    SHA-512
    Note the following:
    • Choosing a HMAC algorithm will cause the assertion to produce a HMAC digest with the selected algorithm applied to the
      Source Data
      and
      Key
      .
    • Choosing a non-HMAC algorithm will cause the assertion to produce a generic digest with the selected algorithm applied to the
      Source Data
      .
    Avoid non-HMAC algorithms, as they produce weak hashing that can be exploited.
    Key
    (Enabled only for HMAC signature algorithms)
    Enter the key that will be used to generate the hash when a HMAC algorithm is selected. You may enter text or specify a context variable. You may also enter an expression that combines static text with context variables.
    • For text keys, type it directly into this field.
    • For Base64 and hexadecimal keys, you must first use the Encode/Decode Data Assertion to decode from Base64/hex to binary. (In the policy, it is presented as a message with application/octet-stream.) The resulting context variable from the Encode/Decode Data assertion is placed in this Key field.
    • For any other type of binary key, first set it as a context variable of type 'Message', then enter that variable in this Key field.
    Observe the following tips about the key:
    • Keep the key in a secure location.
    • Never transmit the key over the network for any reason.
    • If you suspect the key has been compromised, regenerate a new key and rebuild the policy.
    • Longer keys produce a stronger hash.
  4. Click [
    OK
    ] when done.