{"id":"hmac-verify","version":"1.0.0","description":"Recompute an HMAC and compare it, constant-time, to a signature that may carry a literal prefix and be truncated.","supported_operations":["verify a github webhook signature","check hmac signature on a request","validate x-hub-signature-256 header","does this hmac match the payload","verify a truncated hmac","אמת חתימת hmac על webhook"],"unsupported_operations":["computing a fresh HMAC (see hmac-compute)","verifying a JWS/JWT compact token (see the R12 jwt-hmac-verify contract, which parses header/alg rules)"],"semantics":["The tool first computes the full HMAC over message/key/algorithm exactly as hmac-compute would (mac_bytes = the algorithm's native output length). The comparison length L is truncate_to_bytes if given, else mac_bytes.","truncate_to_bytes, when given, must satisfy RFC 2104 section 5's bound: truncate_to_bytes >= max(10, ceil(mac_bytes / 2)) and <= mac_bytes; otherwise invalid_input. When satisfied, comparison uses the leftmost L bytes of the full MAC.","If signature_prefix is given, the raw signature text must start with that exact literal (case-sensitive); if it does not, the result is valid:false, reason:\"prefix_missing\", matched_encoding:null with no decoding attempted. If it does, the prefix is stripped before decoding.","The (post-prefix) signature text is decoded to L bytes the same way hash-digest-verify decodes its \"expected\" field: \"auto\" (default) tries hex, then base64, then base64url, each requiring a decoded length of exactly L; any failure under auto is valid:false, reason:\"signature_not_decodable\". An explicit signature_encoding first checks that encoding's syntax (\"signature_not_decodable\" on failure), then the decoded length (\"signature_wrong_length\" on a mismatch).","Once the signature decodes to exactly L bytes, it is compared with a constant-time comparison to the leftmost L bytes of the computed MAC: a mismatch is valid:false, reason:\"mismatch\"; a match is valid:true, reason:null.","Unlike hash-digest-verify, this tool never returns the computed MAC (in full or truncated form) in its output or in any error's details: echoing the correct value back to a caller who supplied a wrong one would turn the tool into a forgery oracle.","key is never echoed anywhere in the output or in any error's details."],"limits":{"max_key_bytes":4096,"max_message_bytes":65536},"pricing":{"status":"unpriced","charge_usd":null},"input_schema":{"type":"object","additionalProperties":false,"required":["key","message","algorithm","signature"],"properties":{"key":{"type":"string","maxLength":16384},"key_encoding":{"type":"string","enum":["utf8","hex","base64","base64url"],"default":"utf8"},"message":{"type":"string","maxLength":262144},"message_encoding":{"type":"string","enum":["utf8","hex","base64","base64url"],"default":"utf8"},"algorithm":{"type":"string","enum":["md5","sha1","ripemd160","sha224","sha256","sha384","sha512","sha512-224","sha512-256","sha3-224","sha3-256","sha3-384","sha3-512"]},"signature":{"type":"string","minLength":1,"maxLength":512},"signature_encoding":{"type":"string","enum":["auto","hex","base64","base64url"],"default":"auto"},"signature_prefix":{"type":"string","minLength":1,"maxLength":32},"truncate_to_bytes":{"type":"integer","minimum":10,"maximum":64}}},"output_schema":{"type":"object","additionalProperties":false,"required":["valid","reason","algorithm","matched_encoding"],"properties":{"valid":{"type":"boolean"},"reason":{"type":["string","null"],"enum":["mismatch","prefix_missing","signature_not_decodable","signature_wrong_length",null]},"algorithm":{"type":"string","enum":["md5","sha1","ripemd160","sha224","sha256","sha384","sha512","sha512-224","sha512-256","sha3-224","sha3-256","sha3-384","sha3-512"]},"matched_encoding":{"type":["string","null"],"enum":["hex","base64","base64url",null]}}},"examples":[{"input":{"key":"0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b","key_encoding":"hex","message":"Hi There","algorithm":"sha256","signature":"b0344c61d8db38535ca8afceaf0bf12b881dc200c9833da726e9376c2e32cff7"},"output":{"valid":true,"reason":null,"algorithm":"sha256","matched_encoding":"hex"}},{"input":{"key":"0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b","key_encoding":"hex","message":"Hi There","algorithm":"sha256","signature":"b613679a0814d9ec772f95d778c35fc5ff1697c493715653c6c712144292c5ad"},"output":{"valid":false,"reason":"mismatch","algorithm":"sha256","matched_encoding":"hex"}},{"input":{"key":"key","message":"abc","algorithm":"sha256","signature_prefix":"sha256=","signature":"no-prefix-here"},"output":{"valid":false,"reason":"prefix_missing","algorithm":"sha256","matched_encoding":null}}],"execute_url":"/v1/tools/hmac-verify/versions/1.0.0/execute"}