Siqn
Back to documentation

Authentication

This page provides detailed information about the authentication mechanisms used by the Quantum-Safe PKI services. Proper authentication is crucial for securing the PKI infrastructure and ensuring that only authorized users and services can perform sensitive operations.

Authentication Methods

The Quantum-Safe PKI services use several authentication methods, depending on the service and the operation being performed:

  • Mutual TLS (mTLS): Used for service-to-service communication and client authentication.
  • API Keys: Used for authenticating clients to the Signing Service.
  • JSON Web Signatures (JWS): Used for authenticating ACME clients to the ACME Server.

Mutual TLS (mTLS)

Mutual TLS (mTLS) is a two-way authentication process where both the client and server authenticate each other using X.509 certificates. This provides strong authentication and encryption for service-to-service communication.

How mTLS Works

  1. The client initiates a TLS connection to the server and presents its client certificate.
  2. The server verifies the client certificate against its trusted CA certificates and checks the Certificate Revocation List (CRL).
  3. The server presents its server certificate to the client.
  4. The client verifies the server certificate against its trusted CA certificates.
  5. If both verifications succeed, a secure TLS connection is established.

mTLS Configuration

Each service can be configured to require, request, or disable client certificate authentication using the TLS_CLIENT_AUTH environment variable:

  • none: No client certificate is requested.
  • request: A client certificate is requested, but not required.
  • require: A client certificate is required, but not verified against the CA.
  • require_and_verify: A client certificate is required and verified against the CA.
  • require_and_verify_with_crl: A client certificate is required, verified against the CA, and checked against the CRL.

Client Certificate Creation

To create a client certificate for mTLS authentication, you can use the CA Service to sign a Certificate Signing Request (CSR):

# Generate a private key openssl genpkey -algorithm EC -pkeyopt ec_paramgen_curve:P-256 -out client-key.pem # Create a CSR openssl req -new -key client-key.pem -out client.csr -subj "/CN=client" # Sign the CSR with the CA Service curl -X POST --cert admin.pem --key admin-key.pem --cacert ca-cert.pem -H "Content-Type: application/x-pem-file" --data-binary @client.csr https://localhost:5000/sign -o client.pem

API Keys

The Signing Service uses API keys for client authentication. API keys are simple, long-lived tokens that are included in the request headers.

How API Keys Work

  1. A client creates an account with the Signing Service and receives an API key.
  2. The client includes the API key in the X-API-Key header of each request.
  3. The Signing Service verifies the API key against its database of valid keys.
  4. If the API key is valid, the request is processed; otherwise, it is rejected with a 401 Unauthorized response.

Creating an API Key

To create an API key for the Signing Service, you can use the following command:

# Create an account and get an API key curl -X POST https://localhost:7000/v1/accounts # Or use the CLI ./bin/cli account create --url https://localhost:7000

Using an API Key

To use an API key with the Signing Service, include it in the X-API-Key header of your requests:

# Sign an artifact with the API key curl -X POST -H "Content-Type: application/json" -H "X-API-Key: your-api-key" -d 'algorithm": "hybrid' https://localhost:7000/v1/signatures # Or use the CLI ./bin/cli sign --api-key your-api-key --file path/to/file.bin --url https://localhost:7000

JSON Web Signatures (JWS)

The ACME Server uses JSON Web Signatures (JWS) for client authentication, as specified in the ACME protocol (RFC8555). JWS provides a way to digitally sign JSON data, ensuring its integrity and authenticity.

How JWS Works in ACME

  1. The client generates a key pair (RSA, ECDSA, or EdDilithium2) for ACME account authentication.
  2. The client requests a nonce from the ACME Server using the /acme/new-nonce endpoint.
  3. The client creates a JWS by signing a JSON payload with its private key, including the nonce in the protected header.
  4. The client sends the JWS to the ACME Server.
  5. The ACME Server verifies the signature using the client's public key and checks that the nonce is valid and has not been used before.
  6. If the verification succeeds, the request is processed; otherwise, it is rejected.

JWS Structure

A JWS consists of three parts, separated by dots (.):

  • Protected Header: Base64url-encoded JSON object containing metadata about the signature, such as the algorithm used and the key identifier.
  • Payload: Base64url-encoded JSON object containing the data being signed.
  • Signature: Base64url-encoded signature of the protected header and payload.

Post-Quantum JWS Support

The ACME Server in the Quantum-Safe PKI project extends the JWS standard to support post-quantum digital signatures using EdDilithium2. This is done by defining a new JWS algorithm identifier:

  • EdDilithium2: EdDilithium2 signature algorithm

When using EdDilithium2 for JWS, the protected header would include:

{
  "alg": "EdDilithium2",
  "jwk": {
    "kty": "PQ",
    "crv": "EdDilithium2",
    "x": "base64url-encoded-public-key"
  },
  "nonce": "base64url-encoded-nonce",
  "url": "https://acme-server.example.com/acme/new-account"
}

Security Considerations

When implementing authentication for the Quantum-Safe PKI services, consider the following security best practices:

  • Protect Private Keys: Store private keys securely, preferably in a hardware security module (HSM) or a secure key management system.
  • Rotate API Keys: Regularly rotate API keys to limit the impact of key compromise.
  • Use Strong TLS Settings: Configure TLS with strong cipher suites and protocols.
  • Implement Rate Limiting: Protect authentication endpoints from brute force attacks with rate limiting.
  • Monitor Authentication Attempts: Log and monitor authentication attempts to detect suspicious activity.
  • Implement Least Privilege: Grant only the minimum necessary permissions to authenticated clients.

Next Steps

Now that you understand the authentication mechanisms used by the Quantum-Safe PKI services, you can proceed to:

  • Revocation: Learn about certificate revocation and CRL management.
  • API Endpoints: Review the API endpoints provided by each service.