A reference implementation of a third-party auditor for Signal's key transparency service, based on the key transparency specification.
This service is written in Java using the Micronaut framework. To build and unit test, run
./mvnw clean testin the root directory.
The main class is the Auditor, which runs a scheduled job that requests a
stream of updates from the key transparency service. It maintains a condensed view of the key transparency service's prefix tree
and log tree,
storing just enough information to verify and accept each update sequentially. If the auditor has processed a certain number of updates or a certain amount of time has elapsed, the auditor sends back a
signed tree head
to the key transparency service, indicating that its view of the prefix and log trees up to the given update matches.
If the remote call succeeds, the auditor writes its state data to an AuditorStateRepository,
which it may use to resume from its most recent position in the key transparency log if the auditor is restarted.
If the auditor encounters an inconsistency in verifying an update, it throws an InvalidProofException and stops
sending signed tree heads back to the key transparency service.
The service needs Auditor, KeyTransparencyServiceClient, and AuditorStateRepository beans to run.
The table below describes the configuration properties necessary to instantiate those beans.
| Property | Required? | Description |
|---|---|---|
auditor.private-key |
yes | A PKCS#8-formatted Ed25519 private key encoded in standard base64 and used to sign the tree head sent back to the key transparency service. Can be generated via openssl genpkey -algorithm ed25519 and discarding the PEM header and footer. |
auditor.public-key |
yes | A X509-formatted Ed25519 public key encoded in standard base64 that is the counterpart to auditor.private-key. |
auditor.key-transparency-service-signing-public-key |
yes | A PKCS#8-formatted Ed25519 public key encoded in standard base64 and used by clients to verify the key transparency service's signature over the tree head. |
auditor.key-transparency-service-vrf-public-key |
yes | A PKCS#8-formatted Ed25519 public key encoded in standard base64 and used by clients to verify that the input to a Verifiable Random Function (requested search key) matches the output (commitment index used to traverse the prefix tree). |
auditor.client-certificate |
yes | A PKCS#8-formatted PEM-encoded certificate used to prove the client's identity during mutual TLS. |
auditor.client-private-key |
yes | A PKCS#8-formatted, PEM-encoded private key used to verify ownership of the client certificate during mutual TLS. |
auditor.batch-size |
yes | The maximum number of updates that the key transparency service should return in a single response. This value should be less than or equal to 1000. |
auditor.interval |
no | The time interval at which the auditor job should run to process key transparency updates. Defaults to 1 minute. |
auditor.signature.interval |
no | The interval at which the auditor should send a signed tree head to the key transparency service, in duration. Defaults to 1 hour. |
auditor.signature.page-size |
no | The interval at which the auditor should send a signed tree head to the key transparency service, in number of updates. Defaults to 1,000,000. |
auditor.key-transparency-host |
yes | The hostname of the key transparency service. |
auditor.key-transparency-port |
yes | The port to connect to for the key transparency service. |
storage.dynamodb.region |
Exactly one storage.<type> must be specified |
The AWS region of the DynamoDB table used to store auditor state. |
storage.dynamodb.table-name |
Exactly one storage.<type> must be specified |
The name of the DynamoDB table used to store auditor state. |
storage.file.name |
Exactly one storage.<type> must be specified |
The name of the file used to store auditor state. |
We use GitHub for bug tracking. Security issues should be sent to [email protected].
We cannot provide direct technical support. Get help running this software in your own environment in our unofficial community forum.
Copyright 2025 Signal Messenger, LLC
Licensed under the AGPLv3: https://www.gnu.org/licenses/agpl-3.0.html