A Backend Checklist for Imou Signatures: Time, Nonce, id and SN1005

#camera #automation

Stop most signature failures in code by synchronizing UTC time, generating a 32-bit nonce that never repeats inside the documented five-minute window, sending a unique non-empty request id, pairing appId with appSecret, posting to the assigned regional host, and matching the live HMAC procedure including the official test vector. Nonce reuse in that window currently returns SN1005. Do not restate a forked algorithm in a wiki; implement the development specification page.

Why it matters

Production incidents often mix four bugs: clock drift on Kubernetes nodes, a shared nonce in a retry helper, an empty id, and the wrong data center. A checklist that runs in CI and in the HTTP client prevents “it worked on my laptop.”

Approach / architecture

Keep a SignAndSend function that always allocates a fresh envelope:

for each attempt:
  time = utc_epoch_seconds()
  nonce = unique_32bit()
  id = unique_nonempty()
  sign = official_algorithm(appId, secret, time, nonce, params)
  POST assigned_host /openapi/method

Retries that copy system fields cause SN1005. Architecture recommendation: retry at this envelope boundary, and keep a separate internal correlation id for logs.

Seven implementation steps

NTP or equivalent on every worker that signs. Stay comfortably inside the five-minute window; do not skim the edge.
Centralize nonce generation with a uniqueness store or cryptographically strong RNG plus a short-lived seen-set shared across replicas.
Always set id. Empty or duplicate ids fail independently of HMAC.
Lock algorithm to the live page. Use the official Java sample and fixed expected value as a unit test. Never commit the sample secret as production config.
Separate host selection from signing. Wrong openapi-sg versus openapi-fk versus openapi-or is not a HMAC bug.
Log fingerprints only: time, nonce hash, id, appId suffix, region, result code.
On SN1005, inspect retries and cloned HTTP clients before rotating appSecret.

APIs / SDKs

HTTP development specification

Do not duplicate the byte-level sign string in this article; it drifts. The live page is the contract.

Limits & pitfalls

Milliseconds versus seconds for time is a common defect.
Multi-thread nonce collisions look like random production-only failures.
Do not claim all auth errors are SN1005.
Recheck the five-minute rule, nonce width, and test vector on publication day.

Test harness and multi-worker reality

Unit-test the signer with the official vector on every build. Integration-test against the assigned regional host in staging with a dedicated appId. Never point CI at production secrets.

In Kubernetes, clock skew between nodes is enough to flake signatures near the five-minute boundary. Use an NTP sidecar or node-level time sync, and fail health checks if skew exceeds a conservative threshold you choose—without claiming that threshold is Imou’s.

Nonce uniqueness across replicas needs a shared store or a generator with collision resistance plus TTL keys. A local HashSet is not enough for two pods.

When reproducing a customer failure, ask for request id, UTC time, region, and result code. Re-running their exact nonce is the wrong lesson; you want to know whether they reused it.

Do not wrap the official algorithm in a “simplified” library that omits id or changes encoding. Language ports should be checked against the same vector.

Put the official test vector in CI, then ship a signer that mints a new time, nonce, and id on every attempt using the development specification from Imou Open Platform.

DEV Community