Transparency Log

The Transparency Log Service is a critical component of the Quantum-Safe PKI project that provides an immutable, append-only record of all certificates issued by the CA Service. This transparency is essential for auditability and trust in the PKI ecosystem.

Key Features

Implements a Certificate Transparency (CT) log similar to those used in the web PKI ecosystem.
Stores log entries in an append-only file, ensuring that records cannot be modified or deleted once added.
Provides endpoints for adding certificate chains, retrieving log entries, and getting the Signed Tree Head (STH).
Signs the STH using an ECDSA P-256 key for cryptographic verification of log integrity.
Enables public verification of certificate issuance, helping to detect misissued or fraudulent certificates.
Supports Merkle Tree proofs for efficient verification of certificate inclusion in the log.

How Transparency Logs Work

Certificate Transparency logs operate on a simple principle: every certificate issued by a CA is publicly logged in an append-only data structure. This provides several benefits:

Auditability: Anyone can verify which certificates have been issued by the CA.
Accountability: CAs cannot issue certificates secretly, as all certificates must be logged.
Detection: Domain owners can monitor logs to detect unauthorized certificates for their domains.
Trust: The public nature of the log enhances trust in the PKI ecosystem.

Merkle Tree Structure

The Transparency Log uses a Merkle Tree data structure to efficiently prove that a certificate is included in the log:

1
Certificate Submission
When a certificate is issued, it is submitted to the transparency log.
2
Log Entry Creation
The log creates an entry containing the certificate and assigns it a sequence number.
3
Merkle Tree Update
The entry is added to the Merkle Tree, and the tree is updated.
4
Signed Tree Head
The log signs the current root hash of the Merkle Tree, creating a Signed Tree Head (STH).
5
Inclusion Proof
The log can provide a cryptographic proof that a specific certificate is included in the log.

API Endpoints

Endpoint	Method	Description	Authentication
`/ct/v1/add-chain`	POST	Adds a certificate chain to the log	mTLS
`/ct/v1/get-sth`	GET	Returns the current Signed Tree Head	None
`/ct/v1/get-entries`	GET	Returns log entries in the specified range	None
`/ct/v1/get-proof-by-hash`	GET	Returns a Merkle Tree inclusion proof for a certificate	None
`/healthz`	GET	Health check endpoint	None
`/readyz`	GET	Readiness check endpoint	None

Configuration

The Transparency Log Service is configured primarily through environment variables:

Variable	Description	Default
`PORT_CT` / `ADDR`	Listen address for the service	`:6000`
`LOG_FILE`	Path to the append-only log file	`ct-log.dat`
`KEY_DIR`	Directory to store/load cryptographic keys and certificates	`keys`
`CA_CERT_FILE`	Path to the CA root certificate PEM file	`ca-cert.pem`
`CA_CRL_URL`	URL to fetch the Certificate Revocation List from the CA	`https://localhost:5000/crl`

Key Files

The Transparency Log Service uses the following key files, stored in the directory specified by KEY_DIR:

ct-log-key: ECDSA P-256 Private Key for signing the STH
tls: ECDSA Private Key for TLS
tls-cert: Certificate for TLS

Usage Examples

Adding a Certificate Chain

curl -X POST \ --cert client.pem \ --key client-key.pem \ --cacert ca-cert.pem \ -H "Content-Type: application/json" \ -d '{"chain": ["BASE64_CERT_1", "BASE64_CERT_2"]}' \ https://localhost:6000/ct/v1/add-chain

Getting the Signed Tree Head

curl https://localhost:6000/ct/v1/get-sth

Retrieving Log Entries

curl "https://localhost:6000/ct/v1/get-entries?start=0&end=10"

Integration with Other Services

The Transparency Log Service is designed to work with the other components of the Quantum-Safe PKI project:

CA Service: The CA Service can be configured to automatically submit newly issued certificates to the Transparency Log.
ACME Server: The ACME Server can include Signed Certificate Timestamps (SCTs) in issued certificates, proving that they have been logged.
Clients: Certificate verification can include checking that a certificate appears in the Transparency Log, providing an additional layer of security.

Next Steps

Now that you understand the Transparency Log Service, you might want to explore:

CA Service: Learn about the CA Service that issues certificates.
Signing Service: Understand how to sign artifacts with quantum-resistant signatures.
API Endpoints: Review the API endpoints provided by each service.