--- title: Key Transparency Auditor description: Cloudflare's Key Transparency Auditor aims to secure the distribution of public keys for end-to-end encrypted (E2EE) messaging systems like WhatsApp. It achieves this by building a verifiable append-only data structure called a Log, similar to Certificate Transparency. image: https://developers.cloudflare.com/core-services-preview.png --- [Skip to content](#%5Ftop) Was this helpful? YesNo [ Edit page ](https://github.com/cloudflare/cloudflare-docs/edit/production/src/content/docs/key-transparency/index.mdx) [ Report issue ](https://github.com/cloudflare/cloudflare-docs/issues/new/choose) Copy page # Key Transparency Auditor Secure the distribution of public keys in your end-to-end encrypted (E2EE) messaging systems Cloudflare's Key Transparency Auditor aims to secure the distribution of public keys for end-to-end encrypted (E2EE) messaging systems like [WhatsApp ↗](https://engineering.fb.com/2023/04/13/security/whatsapp-key-transparency/). It achieves this by building a verifiable append-only data structure called a Log, similar to [Certificate Transparency ↗](https://developer.mozilla.org/en-US/docs/Web/Security/Certificate%5FTransparency). Cloudflare acts as an auditor of Key Transparency Logs to ensure the transparency of end-to-end encrypted messaging public keys. Cloudflare provides an API for anyone to monitor the verification work we perform, and verify the state of its associated Logs locally. ## Related products **[Certificate Transparency Monitoring](https://developers.cloudflare.com/ssl/edge-certificates/additional-options/certificate-transparency-monitoring/)** Certificate Transparency (CT) Monitoring is an opt-in feature in public beta that aims to improve security by allowing you to double-check any SSL/TLS certificates issued for your domain. **[Privacy Gateway](https://developers.cloudflare.com/privacy-gateway/)** Privacy Gateway is a managed service deployed on Cloudflare's global network that implements part of the [Oblivious HTTP (OHTTP) IETF ↗](https://www.ietf.org/archive/id/draft-thomson-http-oblivious-01.html) standard. The goal of Privacy Gateway and Oblivious HTTP is to hide the client's IP address when interacting with an application backend. ```json {"@context":"https://schema.org","@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","position":1,"item":{"@id":"/directory/","name":"Directory"}},{"@type":"ListItem","position":2,"item":{"@id":"/key-transparency/","name":"Key Transparency Auditor"}}]} ``` --- --- title: Monitor the Auditor description: Cloudflare's Key Transparency Auditor validates Log audit proofs and provides a signature for them. The Log can then distribute these signatures to its end-users, and provides users with confidence that keys have not been tampered with. image: https://developers.cloudflare.com/core-services-preview.png --- [Skip to content](#%5Ftop) Was this helpful? YesNo [ Edit page ](https://github.com/cloudflare/cloudflare-docs/edit/production/src/content/docs/key-transparency/monitor-the-auditor/index.mdx) [ Report issue ](https://github.com/cloudflare/cloudflare-docs/issues/new/choose) Copy page # Monitor the Auditor Cloudflare's Key Transparency Auditor validates Log audit proofs and provides a signature for them. The Log can then distribute these signatures to its end-users, and provides users with confidence that keys have not been tampered with. In order to verify our work, you can use [Plexi ↗](https://github.com/cloudflare/plexi), a CLI tool that allows anyone to perform proof verification locally via a public [API](https://developers.cloudflare.com/key-transparency/api/). ## Features * Verify authenticity of a signature, to confirm it has been signed by a given public key * Verify the validity of [facebook/akd ↗](https://github.com/facebook/akd) proofs * List Logs an Auditor monitors ## Installation | Environment | CLI Command | | --------------------------------------------------------------- | ------------------- | | [Cargo ↗](https://www.rust-lang.org/tools/install) (Rust 1.81+) | cargo install plexi | ## Usage Use the `--help` option for more details about the commands and their options. Terminal window ``` plexi [OPTIONS] ``` ### Configure your auditor remote `plexi` does not come with a default remote auditor, and you will need to choose your own. You can do so either by passing `--remote-url=` or setting the `PLEXI_REMOTE_URL` environment variable. A common remote is provided below: | Name | Remote | | ---------- | --------------------------------------------- | | Cloudflare | https://plexi.key-transparency.cloudflare.com | If you have deployed your own auditor, you can add a remote by filing a [GitHub issue ↗](https://github.com/cloudflare/plexi/issues). ### List monitored Logs An auditor monitors multiple Logs at once. To discover which Logs an auditor is monitoring, run the following: Terminal window ``` plexi ls --remote-url 'https://plexi.key-transparency.cloudflare.com' whatsapp.key-transparency.v1 ``` ### Audit a signature The Key Transparency Auditor vouches for Log validity by ensuring epoch uniqueness and verifying the associated proof. `plexi audit` provides information about a given epoch and its validity. It can perform a local audit to confirm the auditor behaviour. For instance, to verify WhatsApp Log auditted by Cloudflare Auditor, run the following: Terminal window ``` > plexi audit --remote-url 'https://plexi.key-transparency.cloudflare.com' --namespace 'whatsapp.key-transparency.v1' --long Namespace Name : whatsapp.key-transparency.v1 Ciphersuite : ed25519(protobuf) Signature (2024-09-23T16:53:45Z) Epoch height : 489193 Epoch digest : cbe5097ae832a3ae51ad866104ffd4aa1f7479e873fd18df9cb96a02fc91ebfe Signature : fe94973e19da826487b637c019d3ce52f0c08093ada00b4fe6563e2f8117b4345121342bc33aae249be47979dfe704478e2c18aed86e674df9f934b718949c08 Signature verification: success Proof verification : success ``` ```json {"@context":"https://schema.org","@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","position":1,"item":{"@id":"/directory/","name":"Directory"}},{"@type":"ListItem","position":2,"item":{"@id":"/key-transparency/","name":"Key Transparency Auditor"}},{"@type":"ListItem","position":3,"item":{"@id":"/key-transparency/monitor-the-auditor/","name":"Monitor the Auditor"}}]} ``` --- --- title: Auditor description: The Auditor is designed to sign epoch information, which includes the time at which the request is received by the Auditor, the epoch number, and the epoch digest. The Auditor serializes this information in binary using protobuf or bincode and checks whether the requested inclusion is valid, as in it satisfies publication constraints. image: https://developers.cloudflare.com/core-services-preview.png --- [Skip to content](#%5Ftop) Was this helpful? YesNo [ Edit page ](https://github.com/cloudflare/cloudflare-docs/edit/production/src/content/docs/key-transparency/api/auditor-information.mdx) [ Report issue ](https://github.com/cloudflare/cloudflare-docs/issues/new/choose) Copy page # Auditor The Auditor is designed to sign epoch information, which includes the time at which the request is received by the Auditor, the epoch number, and the epoch digest. The Auditor serializes this information in binary using protobuf or bincode and checks whether the requested inclusion is valid, as in it satisfies [publication constraints](https://developers.cloudflare.com/key-transparency/api/epochs/#constraints). If the Log is setup to provide [AKD ↗](https://github.com/facebook/akd) audit proof, the Auditor verifies them asynchronously. ## Get Auditor information `keys` contain Auditor public keys which allow for key rotation later. Terminal window ``` curl 'https://plexi.key-transparency.cloudflare.com/info' { "keys": [ { "public_key": "d1036a33a8731e82a29dc68210988b32b60b7c1bd22d2341f2e339f4db3a2f4a", "not_before": 1712311441501 } ], "logs": [ "508607faff7cb16be841e901eca41a6239461f239e7e610c9ea2576f334bc144" ] } ``` ```json {"@context":"https://schema.org","@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","position":1,"item":{"@id":"/directory/","name":"Directory"}},{"@type":"ListItem","position":2,"item":{"@id":"/key-transparency/","name":"Key Transparency Auditor"}},{"@type":"ListItem","position":3,"item":{"@id":"/key-transparency/api/","name":"API"}},{"@type":"ListItem","position":4,"item":{"@id":"/key-transparency/api/auditor-information/","name":"Auditor"}}]} ``` --- --- title: Epochs description: Refer to the example below to publish a new epoch by requesting its signature. image: https://developers.cloudflare.com/core-services-preview.png --- [Skip to content](#%5Ftop) Was this helpful? YesNo [ Edit page ](https://github.com/cloudflare/cloudflare-docs/edit/production/src/content/docs/key-transparency/api/epochs.mdx) [ Report issue ](https://github.com/cloudflare/cloudflare-docs/issues/new/choose) Copy page # Epochs ## Get an epoch Terminal window ``` curl 'https://plexi.key-transparency.cloudflare.com/namespaces/{namespace}/audits/1' { "namespace": "your.new.log.com", "timestamp": 1717084639921, "epoch": 1, "digest": "1111111111111111111111111111111111111111111111111111111111111111", "signature": "f6a51443bb6703813b330959d9d97471bc06464142165e59733fa102a18b052782a5307d59c31b8b13c1af7dfff6f6e7bf44e880d44e26e96c50a72f72a30c07" } ``` ## Publish a new epoch Refer to the example below to publish a new epoch by requesting its signature. This API is authenticated via [mTLS ↗](https://www.cloudflare.com/learning/access-management/what-is-mutual-tls/), so that only a Log owner can publish new epochs. Terminal window ``` curl 'https://plexi.key-transparency.cloudflare.com/namespaces/{namespace}/audits' \ --header 'Content-Type: application/json' \ --data '{"epoch": 1, "digest": "1111111111111111111111111111111111111111111111111111111111111111"}' { "namespace": "your.new.log.com", "timestamp": 1717084639921, "epoch": 1, "digest": "1111111111111111111111111111111111111111111111111111111111111111", "signature": "f6a51443bb6703813b330959d9d97471bc06464142165e59733fa102a18b052782a5307d59c31b8b13c1af7dfff6f6e7bf44e880d44e26e96c50a72f72a30c07", "key_id": 74, } ``` ### Constraints * If `root` is defined for the namespace, the first epoch must match it (number and digest). * Epochs must be increasing. Second epoch is 2, third is 3, etc. * Epochs must have a unique digest or it will be rejected. * Epochs cannot be republished. * Digest must be a 32 byte string hex encoded (length 64). If a namespace is disabled, you receive the following error: ``` HTTP 400 Bad Request Namespace is disabled and read-only. ``` ```json {"@context":"https://schema.org","@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","position":1,"item":{"@id":"/directory/","name":"Directory"}},{"@type":"ListItem","position":2,"item":{"@id":"/key-transparency/","name":"Key Transparency Auditor"}},{"@type":"ListItem","position":3,"item":{"@id":"/key-transparency/api/","name":"API"}},{"@type":"ListItem","position":4,"item":{"@id":"/key-transparency/api/epochs/","name":"Epochs"}}]} ``` --- --- title: Namespaces description: The Cloudflare Key Transparency API is organized in namespaces, each one representing a Log monitored by Cloudflare Auditor. If you want to register a namespace, contact us. image: https://developers.cloudflare.com/core-services-preview.png --- [Skip to content](#%5Ftop) Was this helpful? YesNo [ Edit page ](https://github.com/cloudflare/cloudflare-docs/edit/production/src/content/docs/key-transparency/api/namespaces.mdx) [ Report issue ](https://github.com/cloudflare/cloudflare-docs/issues/new/choose) Copy page # Namespaces The Cloudflare Key Transparency API is organized in namespaces, each one representing a Log monitored by Cloudflare Auditor. If you want to register a namespace, contact us. ## Create a namespace The following fields are required when making a `POST` request: * `name` * `public` * `root` * `signature_version`: * 0x0001 for [Protobuf serialisation ↗](https://github.com/cloudflare/plexi/blob/main/plexi%5Fcore/src/proto/specs/types.proto) Ed25519 signature from the Auditor * 0x0002 for [bincode serialisation ↗](https://github.com/bincode-org/bincode/blob/trunk/docs/spec.md) E25519 serialisation by the Auditor The `log_directory` field is optional. If set, Cloudflare will use it to fetch audit proofs and validate them. This API is authenticated via [mTLS ↗](https://www.cloudflare.com/learning/access-management/what-is-mutual-tls/). Terminal window ``` curl 'https://plexi.key-transparency.cloudflare.com/namespaces' \ --header 'Content-Type: application/json' \ --data '{ "name": "your.new.log.com", "root": "1/1111111111111111111111111111111111111111111111111111111111111111", "log_directory": "https://your.new.log.com/path/to/proofs", "signature_version": 1 }' { "name": "your.new.log.com", "log_directory": "https://your.new.log.com/path/to/proofs", "root": "1/1111111111111111111111111111111111111111111111111111111111111111", "status": "Initialization", "reports_uri": "/namespaces/your.new.log.com/reports", "audits_uri": "/namespaces/your.new.log.com/audits", "signature_version": 1 } ``` After publishing the first epoch, `status` will show `Online`. Possible statuses include: * `Online` * `Initialization` * `Disabled` ## List all namespaces Refer to the example below to get information about all public namespaces. Terminal window ``` curl 'https://plexi.key-transparency.cloudflare.com/namespaces' { "namespaces": [ { "name": "your.new.log.com", "root": "1/abc", "reports_uri": "/namespaces/your.new.log.com/reports", "audits_uri": "/namespaces/your.new.log.com/audits", "log_directory": "https://your.new.log.com/path/to/proofs", "status": "online" }, { "name": "my.new.log.com", "reports_uri": "/namespaces/meta-bt-2024/reports", "audits_uri": "/namespaces/meta-bt-2024/audits", "status": "initialization" } ] } ``` ## Disable a namespace If a log state has been corrupted, lost, or needs to be sharded to be maintainable, the Auditor allows the Log operator to mark a namespace as `Disabled`. This API is authenticated via [mTLS ↗](https://www.cloudflare.com/learning/access-management/what-is-mutual-tls/). Terminal window ``` curl -X PATCH 'https://plexi.key-transparency.cloudflare.com/namespaces/{namespace}' \ -H 'Content-Type: application/json' \ -d '{ "status": "Disabled" }' { "name": "your.new.log.com", "log_directory": "https://your.new.log.com/path/to/proofs", "root": "1/1111111111111111111111111111111111111111111111111111111111111111", "status": "Disabled", "reports_uri": "/namespaces/your.new.log.com/reports", "audits_uri": "/namespaces/your.new.log.com/audits", "signature_version": 1 } ``` ```json {"@context":"https://schema.org","@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","position":1,"item":{"@id":"/directory/","name":"Directory"}},{"@type":"ListItem","position":2,"item":{"@id":"/key-transparency/","name":"Key Transparency Auditor"}},{"@type":"ListItem","position":3,"item":{"@id":"/key-transparency/api/","name":"API"}},{"@type":"ListItem","position":4,"item":{"@id":"/key-transparency/api/namespaces/","name":"Namespaces"}}]} ```