Authentication

Aurinko Signature Validation Steps

To verify that a request truly came from Aurinko, follow these four steps:

1. Extract the Components

You will need three specific pieces of information from the incoming HTTP request:

• Timestamp: The value of the X-Aurinko-Request-Timestamp header.

• Signature: The value of the X-Aurinko-Signature header (this is your target for comparison).

• Raw Body: The exact, unparsed byte array of the request body.

Note: Do not use a JSON-deserialized object, as whitespace differences will cause the hash to fail.

2. Create the Base String

Concatenate the version, the timestamp, and the raw body using a colon (:) as a delimiter.

• Current Version: v0

• Format: v0:{timestamp}:{raw_body}

3. Compute the HMAC SHA256 Hash

Using your Aurinko Signing Secret as the key, sign the base string created in Step 2.

Java Example:

final byte[] signData = org.apache.commons.lang3.ArrayUtils.addAll(
    ("v0:" + timestampSeconds + ":").getBytes(StandardCharsets.UTF_8),
    payloadBytes
);

Note: Then hash signData using HMAC SHA256 and your Signing Secret.

4. Compare and Verify

Compare your computed hash against the X-Aurinko-Signature header.

• Match: The request is authentic; proceed with processing.

• Mismatch: The request is invalid and should be discarded (return a 401 or 403 status).

Quick Reference Table

Element	Source
Version	Static string v0
Key	Your unique Aurinko Signing Secret
Algorithm	HMAC SHA256
Delimiter	Colon :

Java example:

import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.nio.charset.StandardCharsets;
import org.apache.commons.codec.binary.Hex;
import org.apache.commons.lang3.ArrayUtils;

public class AurinkoValidator {

    private static final String HMAC_ALGO = "HmacSHA256";
    private static final String VERSION = "v0";

    public boolean isValidRequest(String signingSecret, String timestamp, String headerSignature, byte[] rawBody) {
        try {
            // 1. Prepare the prefix: "v0:timestamp:"
            String prefix = VERSION + ":" + timestamp + ":";
            byte[] prefixBytes = prefix.getBytes(StandardCharsets.UTF_8);

            // 2. Concatenate prefix bytes with raw body bytes
            byte[] dataToSign = ArrayUtils.addAll(prefixBytes, rawBody);

            // 3. Initialize HMAC SHA256 with your Secret
            SecretKeySpec secretKeySpec = new SecretKeySpec(
                signingSecret.getBytes(StandardCharsets.UTF_8), 
                HMAC_ALGO
            );
            Mac mac = Mac.getInstance(HMAC_ALGO);
            mac.init(secretKeySpec);

            // 4. Compute the hash
            byte[] computedHashBytes = mac.doFinal(dataToSign);
            String computedSignature = Hex.encodeHexString(computedHashBytes);

            // 5. Compare computed signature with the header
            // Use MessageDigest.isEqual for a time-constant comparison (prevents timing attacks)
            return java.security.MessageDigest.isEqual(
                computedSignature.getBytes(StandardCharsets.UTF_8),
                headerSignature.getBytes(StandardCharsets.UTF_8)
            );

        } catch (Exception e) {
            // Log the error and reject the request
            return false;
        }
    }
}