Signing Service

The Signing Service is a key component of the Quantum-Safe PKI project, providing a way to sign software artifacts with hybrid signatures that combine classical and post-quantum cryptography. This ensures that signed artifacts remain verifiable even in the presence of quantum computers.

Key Features

Signs arbitrary artifact hashes using a hybrid ECDSA + EdDilithium2 signature scheme, providing both classical and post-quantum security.
Requires authentication via API Keys (X-API-Key header) for secure access control.
Implements rate limiting for a 'free' tier, with higher limits for paid plans.
Stores signing logs, SBOMs (Software Bill of Materials), and provenance information in a SQLite database for auditability.
Provides endpoints for account creation, signing, and log retrieval.
Supports mutual TLS (mTLS) with CRL checks for enhanced security.
Flexible key storage options: filesystem (fs) or PKCS#11 hardware security modules (pkcs11).

API Endpoints

Endpoint	Method	Description	Authentication
`/v1/accounts`	POST	Creates a new account and returns an API key	None
`/v1/accounts/{accountID}`	GET	Returns account usage information	API Key
`/v1/signatures`	POST	Signs an artifact hash and returns the signature	API Key
`/v1/log/{entryID}`	GET	Returns a specific log entry	None
`/v1/log/{entryID}/sbom`	GET	Returns the SBOM for a specific log entry	None
`/v1/log/{entryID}/provenance`	GET	Returns the provenance for a specific log entry	None
`/v1/log`	GET	Lists log entries with pagination	None
`/metrics`	GET	Prometheus metrics endpoint	None
`/healthz`	GET	Health check endpoint	None
`/readyz`	GET	Readiness check endpoint	None

Configuration

The Signing Service is configured primarily through environment variables:

Variable	Description	Default
`SIGNING_ADDR` / `ADDR`	Listen address for the service	`:7000`
`DB_DSN`	SQLite database file path	`signing.db`
`KEY_DIR`	Directory to store/load cryptographic keys and certificates	`keys`
`KEYSTORE_TYPE`	Method for storing private keys: `fs` or `pkcs11`	`fs`
`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 Signing Service uses the following key files, stored in the directory specified by KEY_DIR:

ecdsa: ECDSA Private Key for classical signatures
pqc-key.bin: EdDilithium2 Private Key for post-quantum signatures
tls: ECDSA Private Key for TLS
tls: Certificate for TLS

Usage Examples

Creating an Account

curl -X POST https://localhost:7000/v1/accounts

Signing an Artifact

curl -X POST \
-H "Content-Type: application/json" \
-H "X-API-Key: your-api-key" \
-d '{"artifactHash": "sha256:1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef", "algorithm": "hybrid"}' \
https://localhost:7000/v1/signatures

Retrieving a Log Entry

curl https://localhost:7000/v1/log/12345

CLI Integration

The Signing Service is designed to be used with the provided CLI tool, which simplifies the process of signing artifacts:

# Sign a file
./bin/cli sign \
--api-key your-api-key \
--file path/to/artifact.bin \
--url https://localhost:7000

# Sign a file with SBOM
./bin/cli sign \
--api-key your-api-key \
--file path/to/artifact.bin \
--sbom path/to/sbom.json \
--url https://localhost:7000

Next Steps

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

Transparency Log: Learn about the Transparency Log that records certificate issuance.
Authentication: Understand how authentication works across the services.
API Endpoints: Review the API endpoints provided by each service.