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
- 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.
- This assertion contains default settings that are appropriate for most instances. To change any of the settings, right-clickGenerate Security Hashin the policy window and selectGenerate Security Hashor double-click the assertion in the policy window. The assertion properties are displayed.
- Configure the properties as follows:SettingDescriptionSource DataEnter 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 asSelect the line break option for the source data entered above:CR LF(carriage return, line feed),LF(line feed),CR(carriage return). The default isCR LF.Output VariableEnter the name of the context variable that will hold the generated signature.TECHNICAL NOTE: Output valuesThe 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:- Keyis the key value bytes (with strings converted to bytes using UTF-8)- Inputis the input value bytes (with strings converted to bytes using UTF-8)-Hash/HMACis the selected transformation (MD5, SHA-1, HMAC-SHA256, etc.)- Base64is the "encode bytes as Base-64" operationNote 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 AlgorithmChoose the algorithm to use from the drop-down list:HMAC-MD5HMAC-SHA1HMAC-SHA256HMAC-SHA384HMAC-SHA512MD5SHA-1SHA-256SHA-384SHA-512Note the following:- Choosing a HMAC algorithm will cause the assertion to produce a HMAC digest with the selected algorithm applied to theSource DataandKey.
- Choosing a non-HMAC algorithm will cause the assertion to produce a generic digest with the selected algorithm applied to theSource 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.
- Click [OK] when done.