Item Property HMAC

Introduction

Creates a deterministic HMAC from an expanded value and a secret key, and writes the result to an item property. Use it for keyed pseudonyms of identifiers. Item Property Hash provides ordinary, unkeyed hashes.

Configuration

Note

Valve name: ItemPropertyHmac

Properties

Name	Description	Default	Mandatory	Expanded
name	Non-blank destination property name. Existing values are replaced.
value	Input text. An empty string is valid; an unresolved reference causes an error.
secret	Non-empty key as UTF-8 text. It is not decoded from hex or Base64.
algorithm	HmacSHA256, HmacSHA384 or HmacSHA512.	HmacSHA256
encoding	hex for lowercase hexadecimal without a prefix, or base64 for standard Base64 with padding and no line breaks.	hex

Example

{
  "name": "ItemPropertyHmac",
  "config": {
    "name": "pseudonym",
    "value": "${item.identifier}",
    "secret": "${globals.hmac_key}",
    "algorithm": "HmacSHA256",
    "encoding": "base64"
  }
}

Define hmac_key in the existing globals configuration, sourcing its value through your deployment's secret mechanism. For example, the following fragment uses configuration-time environment expansion; supply PIPES_HMAC_KEY securely outside the configuration file:

{
  "globals": {
    "hmac_key": "${env.PIPES_HMAC_KEY}"
  }
}

Globals are resolved during configuration/deployment. Expressions such as ${item.identifier}, ${request.input} and ${state.key} are evaluated at runtime. See Valve expansion for the available scopes.

Input and output

Both the input and key use UTF-8 without trimming or Unicode normalization. The same input bytes, key and algorithm produce the same HMAC. encoding only changes how those HMAC bytes are represented.

value and secret support ${...} expressions, including expressions embedded in text. Every referenced value must exist. Input must expand to a string; an existing empty string is valid input, while an empty key is rejected.

The result replaces all values in name. The source and destination may be the same property. If the flow has no items, the valve creates an item named item, allowing input from request or state scopes.

Missing required parameters, wrong parameter types and unsupported algorithms or encodings cause configuration errors. Expansion or HMAC errors fail the operation without changing that item's destination property. Items already processed earlier in a flow are not rolled back.

Key handling

Use a securely generated secret key with sufficient entropy, stored separately from the identifiers. Reuse the same key only where identifiers are intended to be comparable. Changing the key changes the pseudonyms; plan migration of stored values before rotation.

HMAC does not encrypt the identifier and does not make the data anonymous. Protect both the key and the resulting pseudonyms. The valve does not log its input or key, and its errors omit those values. Other valves, explicit debug dumps and expressions that log data must be configured separately to avoid exposing sensitive values.