Signed responses

Verify the signed payload with a trusted public key, then independently check whether its license state permits the requested action.

What you will learn

• Reproduce the exact signed bytes without losing numbers or Unicode.
• Bind a response to your product, environment and installation.
• Handle key changes, expiry, clock changes and replay honestly.

Prerequisites

• Read authentication and the activation flow.
• Retain the original UTF-8 JSON response before a normal parser changes numeric tokens.
• Configure a trusted public key separately from the response being verified.

Envelope and trust boundary

Activation and validation return a license envelope. A successful HTTP request alone is not proof of authenticity or permission. The signed part is only payload; activation_token, success, valid and request_id in the outer API response are not covered by this signature.

The public key is 32 raw bytes, not a PEM file. The signature is 64 raw bytes, not a hex string. Ed25519 signs the message directly; do not pre-hash the payload or use Ed25519ph. See RFC 8032.

Exact signed bytes

The server recursively sorts associative PHP-array keys with ksort using SORT_STRING, preserves list order, then encodes the payload with JSON_UNESCAPED_SLASHES, JSON_UNESCAPED_UNICODE and JSON_PRESERVE_ZERO_FRACTION. The result has no indentation or separating whitespace. Strings and object names use UTF-8 byte ordering; JavaScript and .NET default UTF-16 ordering can differ for non-BMP keys.

Strings use literal Unicode, except U+2028 and U+2029 are escaped. Quotes, backslashes and JSON controls are escaped; forward slashes remain literal. There is no Unicode normalization. A composed character and its decomposed form are different bytes. Duplicate object names are not a supported wire format; reject them before signature checking.

An integral float such as 19.0 remains 19.0. Numeric encoding is PHP-specific and also depends on its serialize_precision setting. This contract is not RFC 8785 / JSON Canonicalization Scheme. Normal JSON.parse followed by JSON.stringify changes some signed numbers; sorting a normal parsed JavaScript object is insufficient. The PHP JSON documentation describes these flags and precision behavior.

The verification samples retain numeric tokens from the original server JSON and canonicalize its keys and strings. They do not reconstruct PHP floating-point formatting from rounded language numbers. Keep those original numeric tokens in any local cache too. An intermediary that changes a numeric representation can cause a safe verification failure. Do not bypass that failure.

Signed payload field reference

Nullable means the field may explicitly contain null. A missing required field is not the same as null. Your application must validate the fields it uses after verifying the signature.

Activation can return empty device-description strings; validation can return null for the same absent descriptions. Null is signed data, not a reason to remove a property before verification. Omitting X-Installation-ID during validation can produce a null installation hash; always send the persisted ID and reject an unbound response in your client.

Fetch and cache the trusted public key

1. Fetch GET /api/v1/public-key from the configured KDPika HTTPS origin, using normal certificate and hostname verification.
2. Read key.algorithm, key.key_id, key.public_key and key.encoding from the successful response.
3. Require Ed25519, base64url and a decoded 32-byte key.
4. Calculate key_id as ed25519_ followed by the first 16 lowercase hexadecimal characters of SHA-256 of those raw public bytes.
5. Pin the approved key in your application or save the HTTPS-fetched key in protected application state according to your trust policy.
6. Cache the current key for at most the endpoint's one-hour cache lifetime before an intentional refresh.

Expected result: a response cannot choose its own key, host or algorithm. An untrusted file beside the application is not a secure pin merely because its filename is key.json.

Trust on first use from HTTPS depends on the origin, certificate validation and the client's local environment. A compiled pin reduces dependence on a later key fetch, but a fully controlled client machine can still replace the program. Do not fetch a key using a URL supplied in an envelope.

Key changes and rotation

The platform currently exposes one configured public key and reads one signing-key pair. There is no public historical key ring, overlapping-signature period, key-validity schedule or rotation-history endpoint.

1. Treat an unknown key_id as untrusted, not as permission to skip verification.
2. If your policy allows refresh, fetch once from the fixed HTTPS public-key endpoint and validate its format and identity.
3. Accept a new key only through your intended trust-update policy; a strictly pinned client needs an application/configuration rollout.
4. Retry verification once with the approved key or return a clear connection/update-required error.
5. Discard old cached signed states according to the rollout and expiry policy.

Expected result: rotation is deliberate and failures remain closed. Any client-managed overlap is your integration policy, not an existing server guarantee. Compromise of a signing key requires a separate coordinated response with KDPika support.

Time, binding and replay

After authenticity succeeds, require the intended product, environment and installation hash, active status, acceptable application version, valid start/expiry and the appropriate signed validation/grace deadlines. Use the official SDK's valid result as the first gate before feature helpers.

Both next_validation_at and offline_grace_until are calculated from server_time. Grace is not automatically added after the validation interval. A valid signature can belong to an expired license: the expired vector intentionally demonstrates this distinction.

The payload contains no signed request nonce, client challenge or monotonic sequence number. A previously valid signed snapshot can be replayed until your time/binding policy rejects it. The SDKs use a five-minute local clock-rollback tolerance, but local files and clocks are mutable. Revocation on the server cannot instantly invalidate a disconnected cached response. Shorter intervals and server-side authorization reduce exposure; they do not make a local binary unpatchable.

The current source has a recorded database-timezone discrepancy for created_at on a non-UTC local database. Do not use created_at as proof of freshness. This documentation does not change stored timestamps or signing behavior.

Expected result

The positive vector verifies. A changed payload or wrong key fails. The expired vector verifies cryptographically but must fail your time-based access decision. A response for another product, environment or installation does not unlock your application.

Common mistakes

• Signing the outer response, or signing an already rounded JavaScript number tree.
• Using a public key embedded in the same untrusted response as the trust anchor.
• Removing nulls, normalizing Unicode or rewriting numbers before checking the signature.
• Treating signature_valid as permission to use an expired or revoked snapshot.

Security notes

The public signature prevents undetected edits under a trusted key. It does not encrypt customer information, confirm a buyer payment, make the local clock trustworthy or prove a response is the newest available state. Keep raw caches private and avoid logging customer payloads or activation tokens.

Troubleshooting

Next steps

Use the complete verification samples, then run every test vector.

Related

• Offline mode and grace
• Entitlements and features
• Threat model