{"id":129,"date":"2026-11-20T09:20:00","date_gmt":"2026-11-20T09:20:00","guid":{"rendered":"https:\/\/www.masters-tool.com\/blog\/?p=129"},"modified":"2026-11-11T03:39:06","modified_gmt":"2026-11-11T03:39:06","slug":"query-param-order-before-signing-hmac","status":"publish","type":"post","link":"https:\/\/www.masters-tool.com\/blog\/query-param-order-before-signing-hmac\/","title":{"rendered":"Sort Query Params Before You HMAC-Sign Them"},"content":{"rendered":"<p><strong>TL;DR \/ Summary:<\/strong> HMAC signatures over query strings fail when two sides serialize parameters in different orders. Sort keys with a documented rule, encode values the same way both clients do, then hash the canonical string. Pretty printers and \u201chelpful\u201d URL cleaners that reorder params will invalidate a signature that was correct five minutes earlier.<\/p>\n<h2>Why order becomes part of the secret contract<\/h2>\n<p>An HMAC does not understand HTTP. It understands bytes. If one client builds <code>a=1&amp;b=2<\/code> and the server rebuilds <code>b=2&amp;a=1<\/code>, the digests diverge even when the logical map is identical. Teams discover this only after a \u201charmless\u201d refactor that swapped map iteration order.<\/p>\n<p>Language runtimes differ. Some hashes preserve insertion order. Older ones do not. Mobile SDKs may sort; browser URLSearchParams may not match your backend\u2019s Go map walk. Treat order as an explicit step, never as an accident of the dictionary type. Write the rule into the partner onboarding PDF so the next engineer does not \u201cimprove\u201d the client into intermittent 401s.<\/p>\n<p>When onboarding a second mobile platform, port the canonicalization tests before the first production traffic. A Kotlin Map and a Swift Dictionary will not invent the same iteration order just because both teams read the same prose spec. Shared fixtures beat shared optimism.<\/p>\n<h2>Canonicalization rules worth writing down<\/h2>\n<p>Common rules: sort keys lexicographically by Unicode code point, join with <code>&amp;<\/code>, use <code>key=value<\/code> with a single equals, and percent-encode using a named RFC. Document whether empty values appear as <code>key=<\/code> or are omitted. Document whether keys are case-sensitive. Decide whether absent optional fields are dropped or serialized empty; a client that drops nulls and a server that emits <code>coupon=<\/code> will disagree forever.<\/p>\n<p>Boolean false and numeric zero are values, not absences, unless the spec says otherwise. When a new optional field ships behind a feature flag, both sides must agree whether unsigned extras are ignored or whether any extra key invalidates the signature. Strict APIs prefer a fixed allowlist of keys in the signed set so surprise parameters cannot be injected after the digest is computed.<\/p>\n<h2>Encoding traps that look like order bugs<\/h2>\n<p>Space as <code>%20<\/code> versus <code>+<\/code> changes the byte string. So does encoding a slash inside a value, or double-encoding a value that was already escaped. Before you blame sort order, dump the exact preimage both sides hashed. A <a href=\"https:\/\/www.masters-tool.com\/\">URL encode utility<\/a> is useful for comparing one value at a time, but the signature preimage is the whole joined string.<\/p>\n<p>Arrays are another silent fork: <code>tag=a&amp;tag=b<\/code> versus <code>tag[]=a&amp;tag[]=b<\/code> versus a comma-joined single key. If the API allows repeated keys, define the repeat order after key sort\u2014usually stable by original sequence among equals. Include an unsorted fixture in CI so deleting the sort call fails a test immediately.<\/p>\n<h2>A failing case with three parameters and a nonce<\/h2>\n<p>Client sends timestamp, user id, and action. Insertion order on the phone was action, timestamp, user. Server sorted lexicographically and matched by luck. A later release inserted <code>nonce<\/code>. Phone still appended; server sorted. Signatures broke only for requests that included nonce.<\/p>\n<p>The fix was not \u201cmore retries.\u201d It was logging the canonical string behind a redacted flag in staging, then forcing both sides through one shared sort helper. Once the helper owned ordering, feature flags that add parameters stopped being signature events. Ship that helper as a versioned package so mobile, web, and backend cannot drift one merge at a time.<\/p>\n<h2>Body signatures, gateways, and rewritten URLs<\/h2>\n<p>Some APIs sign the body only. Others sign method plus path plus sorted query plus body hash. Copying a query-signing routine onto a JSON body without clarifying separators creates a hybrid nobody else can reproduce. Keep query canonicalization in one function and body hashing in another, then compose them to match the vendor diagram exactly.<\/p>\n<p>API gateways, WAFs, and link cleaners sometimes drop empty parameters or reorder query keys for cache efficiency. That is fine for cache keys and fatal for HMAC preimages. Sign before any normalizing proxy, or configure the proxy to leave the query string byte-stable. Locally, avoid pasting a signed URL into a browser bar that auto-encodes characters again; prefer curl with a single-quoted URL.<\/p>\n<h2>Clock skew is adjacent, not identical<\/h2>\n<p>Timestamp fields inside the signed payload stop replay, but they do not fix order bugs. A skew window of five minutes can make a correctly ordered signature look dead if devices drift. Check NTP on both ends after you have proven the canonical strings match. Mixing the two incident classes in one ticket doubles mean time to repair.<\/p>\n<p>Log the received timestamp beside a hash of the canonical string in staging. Failures that cluster around minute boundaries point to clocks; failures that cluster around deploys point to serializers. That split keeps cryptography tickets from absorbing every auth failure.<\/p>\n<h2>Practical checklist before you blame the secret key<\/h2>\n<p>Compare canonical strings first, then hex versus base64 digest formatting, then clocks, and only then rotate keys. Key mismatch is real, but order and encoding cause more \u201cit used to work\u201d tickets than silent key corruption. When two environments disagree, paste both preimages into a <a href=\"https:\/\/www.masters-tool.com\/\">text diff or hash helper<\/a> and look at the first differing character.<\/p>\n<p>The fix is usually a sort, an encoding alphabet, or a stray <code>?<\/code> included in one preimage and not the other\u2014not a new cryptography library. Store golden fixtures: input map, canonical string, hex digest for a fixed key. Run them on every client language you ship so the next encoder change fails in CI instead of in a customer dashboard at lunch.<\/p>\n","protected":false},"excerpt":{"rendered":"<p>TL;DR \/ Summary: HMAC signatures over query strings fail when two sides serialize parameters in different orders. Sort keys with a documented rule, encode values the same way both clients do, then hash the canonical string. Pretty printers and \u201chelpful\u201d URL cleaners that reorder params will invalidate a signature that was correct five minutes earlier. [&hellip;]<\/p>\n","protected":false},"author":1,"featured_media":38,"comment_status":"closed","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[3],"tags":[],"class_list":["post-129","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-converters-codecs","entry","has-media"],"_links":{"self":[{"href":"https:\/\/www.masters-tool.com\/blog\/wp-json\/wp\/v2\/posts\/129","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/www.masters-tool.com\/blog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/www.masters-tool.com\/blog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/www.masters-tool.com\/blog\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/www.masters-tool.com\/blog\/wp-json\/wp\/v2\/comments?post=129"}],"version-history":[{"count":1,"href":"https:\/\/www.masters-tool.com\/blog\/wp-json\/wp\/v2\/posts\/129\/revisions"}],"predecessor-version":[{"id":130,"href":"https:\/\/www.masters-tool.com\/blog\/wp-json\/wp\/v2\/posts\/129\/revisions\/130"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/www.masters-tool.com\/blog\/wp-json\/wp\/v2\/media\/38"}],"wp:attachment":[{"href":"https:\/\/www.masters-tool.com\/blog\/wp-json\/wp\/v2\/media?parent=129"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/www.masters-tool.com\/blog\/wp-json\/wp\/v2\/categories?post=129"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/www.masters-tool.com\/blog\/wp-json\/wp\/v2\/tags?post=129"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}