|
| 1 | +<!-- |
| 2 | +SPDX-FileCopyrightText: Copyright 2025 Siemens AG |
| 3 | +
|
| 4 | +SPDX-License-Identifier: Apache-2.0 |
| 5 | +--> |
| 6 | + |
| 7 | +# Mock CA |
| 8 | + |
| 9 | +> **Note:** *This mock CA is a simple tool to generate certificates for testing purposes. It is not a real CA and does not provide sufficient validation.* |
| 10 | +
|
| 11 | +## Overview |
| 12 | + |
| 13 | +Mock CA is a simulated certificate authority designed for testing and |
| 14 | +research purposes, particularly focusing on post-quantum (PQ) cryptography and hybrid certificate |
| 15 | +issuance. The project enables the issuance, management, and revocation of certificates using a |
| 16 | +combination of traditional and PQ cryptographic mechanisms. |
| 17 | + |
| 18 | +## About the Mock CA |
| 19 | + |
| 20 | +- The Mock-CA is currently only supported in |
| 21 | + the LwCMP fashion (one request at a time.) |
| 22 | +- Supports the generation of certificates using various key types, including traditional and post-quantum keys and |
| 23 | + hybrid keys and mechanisms. |
| 24 | + |
| 25 | +### Missing Features |
| 26 | + |
| 27 | +- Does not support **CRS** attributes, beside the one for extensions. |
| 28 | +- Does only support **CA** `ccp` Cross-Certification Response. |
| 29 | +- Does not support Announcement messages yet (python logic is present). |
| 30 | +- Does not support `krr` (key recovery request) messages and |
| 31 | + `krp` (key recovery response) messages (requires new state!) |
| 32 | + |
| 33 | +### Features |
| 34 | + |
| 35 | +- **General Message Handling:** Supports CMP (Certificate Management Protocol) messages with functionalities like key updates, revocation passphrases, and encryption key pair type queries. |
| 36 | +- **Certificate Request Processing:** Handles various certificate request types, including: |
| 37 | + - `ir` (initial registration) |
| 38 | + - `cr` (certificate request) |
| 39 | + - `p10cr` (PKCS#10 certificate request) |
| 40 | + - `kur` (key update request) |
| 41 | + - `ccr` (cross-certification request) |
| 42 | +- **Challenge-Response Mechanism:** Implements a challenge-response system for authentication before issuing certificates, |
| 43 | + both the encrypted `Rand` and the encrypted certificate. |
| 44 | +- **Hybrid Key and Certificate Support:** Enables the use of traditional, post-quantum, and hybrid key mechanisms such as: |
| 45 | + - ECDH (Elliptic Curve Diffie-Hellman) |
| 46 | + - X25519/X448 key exchange |
| 47 | + - Hybrid KEMs (Key Encapsulation Mechanisms) |
| 48 | +- **Nested and Batch Processing:** Supports nested PKI messages and batch processing |
| 49 | + for multiple certificate requests (`ir`, `cr`, `p10cr`, `kur`, `ccr`). |
| 50 | +- **Certificate Revocation Handling:** Manages certificate revocation lists (CRLs) and supports passphrase-based revocation. |
| 51 | +- **Added Protection Requests:** Implements LwCMP (Lightweight CMP) protection mechanisms, including password-based MAC and hybrid protection. |
| 52 | + |
| 53 | +## Endpoints |
| 54 | + |
| 55 | +The Mock CA exposes several HTTP endpoints. Unless noted otherwise, all POST |
| 56 | +routes expect a DER-encoded CMP `PKIMessage` in the request body and return the |
| 57 | +response as a DER-encoded `PKIMessage`. |
| 58 | + |
| 59 | +The server listens on `127.0.0.1:5000` by default and exposes the following routes: |
| 60 | + |
| 61 | +- **`/issuing`** (`POST`) |
| 62 | + – Handle standard CMP requests and return a `PKIMessage` with the issued certificate or an error. |
| 63 | +- **`/chameleon`** (`POST`) |
| 64 | + – Processes requests for chameleon certificates. |
| 65 | +- **`/sun-hybrid`** (`POST`) |
| 66 | + – Issues Sun‑Hybrid certificates using PQ and traditional keys. |
| 67 | +- **`/multi-auth`** (`POST`) |
| 68 | + – Validate hybrid-protected requests using multiple certificates. |
| 69 | +- **`/cert-discovery`** (`POST`) |
| 70 | + – Issues a certificate which includes the `url` of the secondary certificate. |
| 71 | +- **`/related-cert`** (`POST`) |
| 72 | + – Issues a certificate related to an existing one. |
| 73 | +- **`/catalyst-sig`** (`POST`) |
| 74 | + – Issues a certificate signed with a `Catalyst` alternative signature. |
| 75 | +- **`/catalyst-issuing`** (`POST`) |
| 76 | + – Issues a certificate from a catalyst request with an alternative Proof-of-Possession (PoP) signature. |
| 77 | +- **`/ocsp`** (`POST`) |
| 78 | + – Takes an OCSP request and returns the corresponding OCSP response. |
| 79 | +- **`/crl`** (`GET`) |
| 80 | + – Returns the current certificate revocation list. |
| 81 | +- **`/cert/<serial_number>`** (`GET`) |
| 82 | + – Retrieves the certificate with the specified serial number. |
| 83 | +- **`/pubkey/<serial_number>`** (`GET`) |
| 84 | + – Returns the public key for the given certificate. |
| 85 | +- **`/sig/<serial_number>`** (`GET`) |
| 86 | + – Returns the alternative signature for the specified Sun‑Hybrid certificate. |
| 87 | + |
| 88 | +## Debug Error handler: |
| 89 | + |
| 90 | +1. If the Exchange PKIMessage |
| 91 | + The `Exchange PKIMessage` keyword contains the error message is set there. |
| 92 | + Otherwise, the error message is set in the `PKIMessage` itself, it is advised to use the |
| 93 | + `PKIStatus Must Be` keyword to see the logged PKIStatusInfo, in human-readable format. |
| 94 | + |
| 95 | +2. The Mock-CA runs in the `Debug` mode. But there are better not yet |
| 96 | + implemented methods, which are better for logging or debugging. |
| 97 | + |
| 98 | +3. Some tests require a state and will fail, the second time, the tests are executed. |
| 99 | + |
| 100 | +## Getting Started |
| 101 | + |
| 102 | +To start using the Mock CA, ensure you have the necessary dependencies installed (e.g., Python version, OpenSSL, etc.). |
| 103 | +Then follow the instructions in the [Start the CA](#start-the-ca) section below. |
| 104 | + |
| 105 | +- The requirements are the same as for the CMP test cases. |
| 106 | + |
| 107 | +## Example Usage |
| 108 | + |
| 109 | +Examples are defined inside the [client.py](mock_ca/client.py) file. |
| 110 | +If Python is not to be used, the OpenSSL command can be used instead: |
| 111 | + |
| 112 | +```sh |
| 113 | +OUTDIR="data/openssl_out" |
| 114 | +mkdir -p "$OUTDIR" |
| 115 | + |
| 116 | +# Generate key and CSR |
| 117 | +openssl genpkey -algorithm RSA -out "$OUTDIR/new-private-key-rsa.pem" -pkeyopt rsa_keygen_bits:2048 |
| 118 | +openssl req -new -key "$OUTDIR/new-private-key-rsa.pem" -subj "/CN=Hans the Tester" -out "$OUTDIR/csr-rsa.pem" |
| 119 | + |
| 120 | +# Send IR request with OpenSSL CMP; write outputs into $OUTDIR |
| 121 | +openssl cmp -cmd ir \ |
| 122 | + -server http://localhost:5000/issuing \ |
| 123 | + -recipient "/CN=Hans the Tester" \ |
| 124 | + -ref "CN=Hans the Tester" \ |
| 125 | + -subject "/CN=Hans the Tester" \ |
| 126 | + -csr "$OUTDIR/csr-rsa.pem" \ |
| 127 | + -secret pass:SiemensIT \ |
| 128 | + -popo 1 \ |
| 129 | + -certout "$OUTDIR/result-cert.pem" \ |
| 130 | + -newkey "$OUTDIR/new-private-key-rsa.pem" \ |
| 131 | + -reqout "$OUTDIR/req-ir.pkimessage" \ |
| 132 | + -unprotected_errors |
| 133 | +``` |
| 134 | + |
| 135 | + |
| 136 | +### Start the CA |
| 137 | + |
| 138 | +To start the CA, run the following command: |
| 139 | + |
| 140 | +```sh |
| 141 | + make start-mock-ca |
| 142 | +``` |
| 143 | + |
| 144 | +Alternative python command: |
| 145 | + |
| 146 | +```sh |
| 147 | + python3 mock_ca/ca_handler.py |
| 148 | +``` |
| 149 | + |
| 150 | +To test the CMP test cases, run the following command |
| 151 | +in a second shell: |
| 152 | + |
| 153 | +```sh |
| 154 | + make mock-ca-tests |
| 155 | +``` |
0 commit comments