plenigo signature

    Content of this article

    1. Preliminary Remarks
    2. plenigo Signature

    1. Preliminary Remarks

    Each callback from the plenigo system comes with a signature in the header to ensure that the call comes from a trustworthy source and has not not been manipulated.

    2. plenigo Signature

    Each callback is signed with a signature header. 
    The header is called plenigo-signature and looks as follows:
    t=1729583536,s=fdcd0a0ccd0b4db629d35a33c3aada5cf669a28f91adb38abcc9ffcdb1663d38
    The header contains two elements. A time stamp that defines the time (t) at which the callback was generated, and a hash-based message authentication code (HMAC) with SHA-256 (s). 
    In summary:

    plenigo-signature: t=<timestamp>,s=<signature>

    • t = Unix timestamp (seconds since epoch)

    • s = HMAC-SHA256 signature (hex-encoded)

    How the signature is created
    Frisbii Media computes the signature using the following steps:

    1. Get current timestamp as a string

    2. Concatenate the timestamp and the raw body with a dot (.)

    3. Create HMAC using SHA256 and your Frisbii Media callback secret

    4. Set the header: plenigo-signature: t=timestamp,s=signature

    To help you handle version-specific logic, Frisbii Media includes the API version in every callback request using the X-Plenigo-Api-Version HTTP header.

    Verify the header

    Step 1: Extract the time stamp and the signatures from the header
    The content of the header can be separated by "," (comma) to get a list of the elements. By using the "=" (equal sign) as separator, each element can be separated into a data pair containing a prefix and a value.

    Values of the prefixes:
    • "t" = time stamp
    • "s" = a signature or several signatures
    Any other elements can be ignored.

    Step 2: Prepare string "signed_payload"
    The string "signed_payload" is created by a chain: 
    • the time stamp as string
    • the sign "." (dot) 
    • the actual JSON payload (meaning the request content) as string 

    Step 3: Determine expected signature
    A HMAC authentication code with a SHA256 hash function is required. The signature secret of the end point is used as key and the string "signed_payload" is used as message.

    Step 4: Compare signatures using a constant-time comparison function
    The signature (or signatures) in the header are to be compared with the expected signature.
    The difference between the current time stamp and the received time stamp should be calculated to be able to decide if the difference is within an acceptable tolerance.

    Here’s an example how to process the received callback data:

    ⚠️ Security Tips

    To protect against timing attacks (a variant of a side-channel attack) it is recommended to carry out a time-constant string comparison to compare the expected signature with each of the received signatures.

    • Always use hmac.Equal(...) for comparison to prevent timing attacks

    • Reject callbacks where the timestamp is too far from the current time (e.g. >5 min)

    • Never share your callback secret publicly

    Published