Trusted notary keys

vlayer runs notary servers which notarize HTTP requests performed by calling /prove. The notary signs the Web Proof with its key. Thus, in order to trust given Web Proof, the identity of the notary - fingerprint of the key returned by /verify - needs to be verified.

Trusted identities of vlayer notary servers are specified by the authoritative notary key list. Its format is defined by the JSON schema.

Treat a proof as trusted only when its notaryKeyFingerprint returned by /verify matches an entry in the list and:

validFrom <= tlsTimestamp < validUntil

When validUntil is null, there is no upper bound. tlsTimestamp is the Unix timestamp from the verified TLS session returned by /verify.

The list can contain concurrent keys during a rotation and retired keys needed to verify older proofs. Do not select only the newest entry: select the matching fingerprint, then apply that entry's validity window. Fields under meta, including notaryUrls, are informational and must not be used as trust inputs.

Fetching and caching

Fetch the list over HTTPS and follow its Cache-Control header. When the cached response expires, refresh it with If-None-Match so the server can return 304 Not Modified when the list is unchanged. Treat a copy that you could not refresh as stale.

For more information, see the notary-keys repository README.

Trusted notary keys

Trusted notary keys

Fetching and caching

On this page