Digitally Signed HTTP(S) Requests
Audience Manager requires the HTTP(S) server-to-server requests to be digitally signed for validity. This document describes how you can sign HTTP(S) requests with private keys.
Using a private key provided by you and shared with Audience Manager, we can digitally sign the HTTP(S) requests that are sent between IRIS and your HTTP(S) server. This ensures:
- Authenticity : only the sender that has the private key (IRIS) can send valid HTTP(S) messages to the partner.
- Message integrity : with this approach, even on HTTP , you are protected from a man in the middle attack where the messages get distorted.
IRIS has built-in support to rotate the keys with zero downtime, as shown in the Rotating the private key section below.
Information you need to provide
For an HTTP(S) real-time server-to-server destination, contact your Audience Manager consultant and specify:
- The key used to sign the request.
- The name of the HTTP(S) header that will hold the generated signature (X-Signature in the example header below).
- Optional: the type of hash used for the signature (md5, sha1, sha256).
* Connected to partner.website.com (127.0.0.1) port 80 (#0) > POST /webpage HTTP/1.1 > Host: partner.host.com > Accept: */* > Content-Type: application/json > Content-Length: 20 > X-Signature: +wFdR/afZNoVqtGl8/e1KJ4ykPU= POST message content
How it works
- IRIS creates the HTTP(S) message to be sent to the partner.
- IRIS creates a signature based on the HTTP(S) message and the private key communicated by the partner.
- IRIS sends the HTTP(S) request to the partner. This message contains the signature and the actual message, as seen in the example above.
- The partner server receives the HTTP(S) request. It reads the message body and the signature received from IRIS.
- Based on the message body received and the private key, the partner server recalculates the signature. See the How to calculate the signature section just below on how to achieve this.
- Compare the signature created on the partner server (receiver) with the one received from IRIS (sender).
- If the signatures match, then the authenticity and message integrity have been validated. Only the sender, who has the private key, can send a valid signature (authenticity). Moreover, a man in the middle can't modify the message and generate a new valid signature, since they don't have the private key (message integrity).
How to calculate the signature
HMAC (Hash-based message authentication code) is the method used by IRIS for message signing. Implementations and libraries are available basically in every programming language. HMAC has no known extension attacks. See an example in Java below:
// Message to be signed. // For GET type HTTP(S) destinations, the message used for signing will be the REQUEST_PATH + QUERY_STRING // For POST type HTTP(S) destinations, the message used for signing will be the REQUEST_BODY. // String getData = "/from-aam-s2s?sids=1,2,3"; String postData = "POST message content"; // Algorithm used. Currently supported: HmacSHA1, HmacSHA256, HmacMD5. String algorithm = "HmacSHA1"; // Private key shared between the partner and Adobe Audience Manager. String key = "sample_partner_private_key"; // Perform signing. SecretKeySpec signingKey = new SecretKeySpec(key.getBytes(), algorithm); Mac mac = Mac.getInstance(algorithm); mac.init(signingKey); byte result = mac.doFinal(postData.getBytes()); String signature = Base64.encodeBase64String(result).trim(); // signature = +wFdR/afZNoVqtGl8/e1KJ4ykPU=
Rotating the private key
For security reasons, it's recommended to periodically rotate the private key. It is up to you to decide the private key and the rotation period. In order to achieve the key rotation with zero downtime, IRIS supports adding multiple signature headers. One header will contain the signature generated with the old key, another header will contain the signature generated using the new private key. See below the steps in detail:
- Partner communicates the new private key to Adobe Audience Manager.
- IRIS will start sending two signature headers (one using the old key, the other one using the new key).
- Once you start receiving both headers, you can choose to discard the old key and only look at the new signature.
- The old key is removed from Audience Manager and IRIS only sends the new signature header. The keys have been rotated.
Data used for signing
For GET type destinations, the message used for signing will be the REQUEST_PATH + QUERY STRING (e.g. /from-aam-s2s?sids=1,2,3 ). IRIS does not take into account the hostname or HTTP(S) headers - these can be modified / misconfigured along the path or reported incorrectly.
For POST type destinations, the message used for signing is the REQUEST BODY . Again, headers or other request parameters are ignored.