Class Signatures

java.lang.Object
com.fortemate.dicechess.runtime.Signatures
public final class Signatures extends Object
HMAC-SHA256 signing and verification for the DiceChess webhook delivery protocol.

The signed payload is timestamp + "." + body, hex-encoded. A delivery is accepted only if its timestamp falls within REPLAY_WINDOW_SECONDS of the verifier's clock, and the comparison is constant-time to avoid leaking the secret through timing.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final String
    ACTIVATION_PROOF_PREFIX
    Domain separation prefix prepended to the raw body when computing a version-2 activation response proof.
    static final long
    REPLAY_WINDOW_SECONDS
    The signature is only accepted within this many seconds of the current time, either side.

  • Method Summary

    Modifier and Type
    Method
    Description
    static String
    activationProof(String secret, String rawBody)
    Computes the lowercase-hex HMAC-SHA256 response proof for a version-2 verification challenge.
    static String
    sign(String secret, long timestampEpochSeconds, String body)
    Computes the hex-encoded HMAC-SHA256 signature for a delivery.
    static boolean
    verify(WebhookKeys keys, long timestampEpochSeconds, String body, String signature, long nowEpochSeconds)
    Verifies a delivery's signature and freshness against configured active and/or pending keys.
    static boolean
    verify(String secret, long timestampEpochSeconds, String body, String signature, long nowEpochSeconds)
    Verifies a delivery's signature and freshness against a single secret.

    Methods inherited from class Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Field Details

    • REPLAY_WINDOW_SECONDS

      public static final long REPLAY_WINDOW_SECONDS
      The signature is only accepted within this many seconds of the current time, either side.
      See Also:

    • ACTIVATION_PROOF_PREFIX

      public static final String ACTIVATION_PROOF_PREFIX
      Domain separation prefix prepended to the raw body when computing a version-2 activation response proof.
      See Also:

  • Method Details

    • sign

      public static String sign(String secret, long timestampEpochSeconds, String body)
      Computes the hex-encoded HMAC-SHA256 signature for a delivery.
      Parameters:
      secret - the webhook secret issued by the platform
      timestampEpochSeconds - the delivery timestamp, Unix epoch seconds
      body - the raw request body, exactly as transmitted
      Returns:
      the lowercase hex signature

    • activationProof

      public static String activationProof(String secret, String rawBody)
      Computes the lowercase-hex HMAC-SHA256 response proof for a version-2 verification challenge.
      Parameters:
      secret - the pending webhook secret issued by the platform
      rawBody - the exact raw request body received from the platform
      Returns:
      the lowercase hex proof string

    • verify

      public static boolean verify(String secret, long timestampEpochSeconds, String body, String signature, long nowEpochSeconds)
      Verifies a delivery's signature and freshness against a single secret.
      Parameters:
      secret - the webhook secret issued by the platform
      timestampEpochSeconds - the delivery's claimed timestamp, Unix epoch seconds
      body - the raw request body, exactly as received
      signature - the hex signature supplied with the delivery
      nowEpochSeconds - the verifier's current time, Unix epoch seconds
      Returns:
      true if the timestamp is within REPLAY_WINDOW_SECONDS and the signature matches

    • verify

      public static boolean verify(WebhookKeys keys, long timestampEpochSeconds, String body, String signature, long nowEpochSeconds)
      Verifies a delivery's signature and freshness against configured active and/or pending keys.

      When both keys are configured, both signatures are evaluated using constant-time comparisons without early return to eliminate timing oracles.

      Parameters:
      keys - the active and/or pending webhook keys
      timestampEpochSeconds - the delivery's claimed timestamp, Unix epoch seconds
      body - the raw request body, exactly as received
      signature - the hex signature supplied with the delivery
      nowEpochSeconds - the verifier's current time, Unix epoch seconds
      Returns:
      true if the timestamp is within REPLAY_WINDOW_SECONDS and either key matches the signature