Guiliano's doc update

MISSING_SUPPORT_TEMPLATE.md

@@ -0,0 +1,51 @@
+<!--
+SPDX-FileCopyrightText: Copyright 2024 Siemens AG
+
+SPDX-License-Identifier: Apache-2.0
+-->
+
+# Missing Support Issue Template (Example: HSS Signatures)
+
+The CMP test suite currently lacks support for Hierarchical Signature System (HSS) signatures as defined in RFC 8554 and RFC 9858. 
+This includes the ability to parse, validate, and generate HSS signatures and keys. Adding this support is essential for testing 
+CMP implementations that utilize HSS for post-quantum security.
+
+## Motivation and Context
+
+- HSS is a widely recognized stateful hash-based signature scheme, offering strong security guarantees.
+- CMP implementations may adopt HSS for enhanced security, necessitating comprehensive test coverage.
+- Supporting HSS aligns with our goal of providing robust post-quantum cryptographic testing capabilities.
+
+## Desired Support
+- Accept, generate, and validate HSS signatures using the parameter sets from RFC 8554, RFC 9858 and NIST SP 800-208.
+- Track the HSS hierarchy depth correctly, enforcing `height < 9` and other constraints defined in NIST SP 800-208.
+
+## Required Work Items
+
+1. Extend parsing/validation logic to recognise HSS signature structures and keys.
+2. Add regression fixtures (minimal + verbose) covering:
+    - Valid signatures across permissible parameter sets.
+    - Rejection cases for height ≥ 9, malformed hierarchies, and truncated signatures.
+    - Mirror existing XMSS test cases where applicable.
+    - Add basic test cases for a slow HSS variant for shake and SHA2 inside [pq_stateful_sig_tests.robot](tests_pq_and_hybrid/pq_stateful_sig_tests.robot).
+3. Create verbose tests for all supported HSS combinations with the `scripts/generate_pq_stfl_test_cases.py` script and add it manually.
+inside [pq_stateful_sig_alg.robot](tests_pq_and_hybrid/pq_stateful_sig_alg.robot).
+4. Update documentation to reflect HSS support.
+
+## Test Coverage
+
+- Update ALGORITHM_TEST_COVERAGE.md to include HSS scenarios.
+
+## Out of Scope/ Should be added later
+
+(if applicable)
+
+## Open Questions / Follow-ups
+
+(if applicable)
+
+## References
+- RFC 8554 — Leighton-Micali Hash-Based Signatures.
+- RFC 9802 — Use of the HSS and XMSS Hash-Based Signature Algorithms in Internet X.509 PKI.
+- RFC 9858 — Additional Parameter Sets for HSS/LMS Hash-Based Signatures.
+- NIST SP 800-208 — Recommendation for Stateful Hash-Based Signature Schemes.

MockCA_readme.md

@@ -0,0 +1,155 @@
+<!--
+SPDX-FileCopyrightText: Copyright 2025 Siemens AG
+
+SPDX-License-Identifier: Apache-2.0
+-->
+
+# Mock CA
+
+> **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.*
+
+## Overview
+
+Mock CA is a simulated certificate authority designed for testing and
+research purposes, particularly focusing on post-quantum (PQ) cryptography and hybrid certificate
+issuance. The project enables the issuance, management, and revocation of certificates using a
+combination of traditional and PQ cryptographic mechanisms.
+
+## About the Mock CA
+
+- The Mock-CA is currently only supported in
+  the LwCMP fashion (one request at a time.)
+- Supports the generation of certificates using various key types, including traditional and post-quantum keys and
+  hybrid keys and mechanisms.
+
+### Missing Features
+
+- Does not support **CRS** attributes, beside the one for extensions.
+- Does only support **CA** `ccp` Cross-Certification Response.
+- Does not support Announcement messages yet (python logic is present).
+- Does not support `krr` (key recovery request) messages and
+  `krp` (key recovery response) messages (requires new state!)
+
+### Features
+
+- **General Message Handling:** Supports CMP (Certificate Management Protocol) messages with functionalities like key updates, revocation passphrases, and encryption key pair type queries.
+- **Certificate Request Processing:** Handles various certificate request types, including:
+  - `ir` (initial registration)
+  - `cr` (certificate request)
+  - `p10cr` (PKCS#10 certificate request)
+  - `kur` (key update request)
+  - `ccr` (cross-certification request)
+- **Challenge-Response Mechanism:** Implements a challenge-response system for authentication before issuing certificates,
+  both the encrypted `Rand` and the encrypted certificate.
+- **Hybrid Key and Certificate Support:** Enables the use of traditional, post-quantum, and hybrid key mechanisms such as:
+  - ECDH (Elliptic Curve Diffie-Hellman)
+  - X25519/X448 key exchange
+  - Hybrid KEMs (Key Encapsulation Mechanisms)
+- **Nested and Batch Processing:** Supports nested PKI messages and batch processing
+  for multiple certificate requests (`ir`, `cr`, `p10cr`, `kur`, `ccr`).
+- **Certificate Revocation Handling:** Manages certificate revocation lists (CRLs) and supports passphrase-based revocation.
+- **Added Protection Requests:** Implements LwCMP (Lightweight CMP) protection mechanisms, including password-based MAC and hybrid protection.
+
+## Endpoints
+
+The Mock CA exposes several HTTP endpoints. Unless noted otherwise, all POST
+routes expect a DER-encoded CMP `PKIMessage` in the request body and return the
+response as a DER-encoded `PKIMessage`.
+
+The server listens on `127.0.0.1:5000` by default and exposes the following routes:
+
+- **`/issuing`** (`POST`)
+  – Handle standard CMP requests and return a `PKIMessage` with the issued certificate or an error.
+- **`/chameleon`** (`POST`)
+  – Processes requests for chameleon certificates.
+- **`/sun-hybrid`** (`POST`)
+  – Issues Sun‑Hybrid certificates using PQ and traditional keys.
+- **`/multi-auth`** (`POST`)
+  – Validate hybrid-protected requests using multiple certificates.
+- **`/cert-discovery`** (`POST`)
+  – Issues a certificate which includes the `url` of the secondary certificate.
+- **`/related-cert`** (`POST`)
+  – Issues a certificate related to an existing one.
+- **`/catalyst-sig`** (`POST`)
+  – Issues a certificate signed with a `Catalyst` alternative signature.
+- **`/catalyst-issuing`** (`POST`)
+  – Issues a certificate from a catalyst request with an alternative Proof-of-Possession (PoP) signature.
+- **`/ocsp`** (`POST`)
+  – Takes an OCSP request and returns the corresponding OCSP response.
+- **`/crl`** (`GET`)
+  – Returns the current certificate revocation list.
+- **`/cert/<serial_number>`** (`GET`)
+  – Retrieves the certificate with the specified serial number.
+- **`/pubkey/<serial_number>`** (`GET`)
+  – Returns the public key for the given certificate.
+- **`/sig/<serial_number>`** (`GET`)
+  – Returns the alternative signature for the specified Sun‑Hybrid certificate.
+
+## Debug Error handler:
+
+1. If the Exchange PKIMessage
+   The `Exchange PKIMessage` keyword contains the error message is set there.
+   Otherwise, the error message is set in the `PKIMessage` itself, it is advised to use the
+   `PKIStatus Must Be` keyword to see the logged PKIStatusInfo, in human-readable format.
+
+2. The Mock-CA runs in the `Debug` mode. But there are better not yet
+   implemented methods, which are better for logging or debugging.
+
+3. Some tests require a state and will fail, the second time, the tests are executed.
+
+## Getting Started
+
+To start using the Mock CA, ensure you have the necessary dependencies installed (e.g., Python version, OpenSSL, etc.).
+Then follow the instructions in the [Start the CA](#start-the-ca) section below.
+
+- The requirements are the same as for the CMP test cases.
+
+## Example Usage
+
+Examples are defined inside the [client.py](mock_ca/client.py) file.
+If Python is not to be used, the OpenSSL command can be used instead:
+
+```sh
+OUTDIR="data/openssl_out"
+mkdir -p "$OUTDIR"
+
+# Generate key and CSR
+openssl genpkey -algorithm RSA -out "$OUTDIR/new-private-key-rsa.pem" -pkeyopt rsa_keygen_bits:2048
+openssl req -new -key "$OUTDIR/new-private-key-rsa.pem" -subj "/CN=Hans the Tester" -out "$OUTDIR/csr-rsa.pem"
+
+# Send IR request with OpenSSL CMP; write outputs into $OUTDIR
+openssl cmp -cmd ir \
+  -server http://localhost:5000/issuing \
+  -recipient "/CN=Hans the Tester" \
+  -ref "CN=Hans the Tester" \
+  -subject "/CN=Hans the Tester" \
+  -csr "$OUTDIR/csr-rsa.pem" \
+  -secret pass:SiemensIT \
+  -popo 1 \
+  -certout "$OUTDIR/result-cert.pem" \
+  -newkey "$OUTDIR/new-private-key-rsa.pem" \
+  -reqout "$OUTDIR/req-ir.pkimessage" \
+  -unprotected_errors
+```
+
+
+### Start the CA
+
+To start the CA, run the following command:
+
+```sh
+    make start-mock-ca
+```
+
+Alternative python command:
+
+```sh
+    python3 mock_ca/ca_handler.py
+```
+
+To test the CMP test cases, run the following command
+in a second shell:
+
+```sh
+    make mock-ca-tests
+```

REFERENCES.md

@@ -0,0 +1,146 @@
+# References
+
+<!--
+SPDX-FileCopyrightText: Copyright 2025 Siemens AG
+
+SPDX-License-Identifier: Apache-2.0
+-->
+
+This section lists external specifications and internal documents that may be helpful
+when working with the Mock CA.
+
+## Table of Contents
+
+- [References](#references)
+  - [Project Documentation](#project-documentation)
+  - [Standards](#standards)
+    - [Transport CMP](#transport-cmp)
+    - [Algorithm Profiles](#algorithm-profiles)
+    - [Drafts](#drafts)
+  - [Software](#software)
+  - [Post-Quantum Key Encapsulation Mechanism (KEM)](#post-quantum-key-encapsulation-mechanism-kem)
+    - [ML-KEM](#ml-kem)
+      - [Related RFCs and Drafts](#related-rfcs-and-drafts)
+  - [Post-Quantum Signature](#post-quantum-signature)
+    - [ML-DSA](#ml-dsa)
+      - [Related RFCs and Drafts](#related-rfcs-and-drafts-1)
+    - [SLH-DSA](#slh-dsa)
+      - [Related RFCs and Drafts](#related-rfcs-and-drafts-2)
+  - [PQ Stateful Signature](#pq-stateful-signature)
+    - [XMSS / XMSSMT](#xmss--xmssmt)
+    - [HSS](#hss)
+  - [Hybrid Key Encapsulation Mechanism (KEM)](#hybrid-key-encapsulation-mechanism-kem)
+  - [Hybrid Signature](#hybrid-signature)
+  - [Hybrid Certificates](#hybrid-certificates)
+
+---
+
+## Project Documentation
+
+- [Server Test Coverage](./SERVER_TEST_COVERAGE.md)
+- [CMP Test Suite README](./readme.md)
+- [Post‑Quantum Integration Details](./about_pq.md)
+- [Test Suite Architecture](./about_suite.md)
+- [CMP Issues and Proposals](./cmp_issues_and_proposals.md)
+- [Mock CA README](./MockCA_readme.md)
+
+## Standards
+
+- [RFC 4210 — Certificate Management Protocol (CMP)](https://datatracker.ietf.org/doc/rfc4210/)
+- [RFC 9480 — Certificate Management Protocol (CMP) Updates](https://datatracker.ietf.org/doc/rfc9480/)
+- [RFC 9483 — Lightweight Certificate Management Protocol (CMP)](https://datatracker.ietf.org/doc/rfc9483/)
+- [RFC 5280 — Internet X.509 Public Key Infrastructure Certificate and Certificate Revocation List (CRL) Profile](https://datatracker.ietf.org/doc/rfc5280/)
+
+### Transport CMP
+
+- [RFC 6712 — CMP over HTTP](https://datatracker.ietf.org/doc/rfc6712/)
+- [RFC 9482 — CMP over CoAP](https://datatracker.ietf.org/doc/rfc9482/)
+
+### Algorithm Profiles
+
+- [RFC 9481 — CMP Algorithms](https://datatracker.ietf.org/doc/rfc9481/)
+
+### Drafts
+
+- [draft-ietf-lamps-rfc4210bis (CMP)](https://datatracker.ietf.org/doc/draft-ietf-lamps-rfc4210bis/)
+
+## Software
+
+- [OpenSSL](https://www.openssl.org/docs/) — command-line tools used for CSR generation and CMP messages
+- [liboqs](https://github.com/open-quantum-safe/liboqs) — post-quantum cryptography library enabling PQ algorithms
+
+## Post-Quantum Key Encapsulation Mechanism (KEM)
+
+### ML-KEM
+
+- [FIPS 203 — Module-Lattice-based Key-Encapsulation Mechanism (ML-KEM)](https://doi.org/10.6028/NIST.FIPS.203)
+
+#### Related RFCs and Drafts
+
+- [draft-ietf-lamps-kyber-certificates](https://datatracker.ietf.org/doc/draft-ietf-lamps-kyber-certificates/) — X.509 certificate profile for ML‑KEM
+- [draft-ietf-lamps-cms-kyber](https://datatracker.ietf.org/doc/draft-ietf-lamps-cms-kyber/) — Using ML‑KEM in CMS
+
+## Post-Quantum Signature
+
+### ML-DSA
+
+- [FIPS 204 — Module-Lattice-based Digital Signature Algorithm (ML‑DSA)](https://doi.org/10.6028/NIST.FIPS.204)
+
+#### Related RFCs and Drafts
+
+- [draft-ietf-lamps-dilithium-certificates](https://datatracker.ietf.org/doc/draft-ietf-lamps-dilithium-certificates/) — X.509 certificate profile for ML‑DSA
+- [draft-ietf-lamps-cms-ml-dsa](https://datatracker.ietf.org/doc/draft-ietf-lamps-cms-ml-dsa/) — Using ML‑DSA in CMS
+
+### SLH-DSA
+
+- [FIPS 205 — Stateless Hash‑Based Digital Signature Algorithm (SLH‑DSA)](https://doi.org/10.6028/NIST.FIPS.205)
+
+#### Related RFCs and Drafts
+
+- [RFC 9814 — Use of the SLH‑DSA Signature Algorithm in CMS](https://datatracker.ietf.org/doc/rfc9814/)
+- X.509 certificate profile for SLH‑DSA:
+  - [draft-ietf-lamps-sphincsplus-certificates](https://datatracker.ietf.org/doc/draft-ietf-lamps-sphincsplus-certificates/)
+
+## PQ Stateful Signature
+
+- NIST Special Publication:
+  - [NIST SP 800‑208 — Recommendation for Stateful Hash‑Based Signature Schemes](https://doi.org/10.6028/NIST.SP.800-208)
+- Defines the use of XMSS and HSS in X.509:
+  - [RFC 9802 — Use of the HSS and XMSS Hash‑Based Signature Algorithms in Internet X.509 Public Key Infrastructure](https://datatracker.ietf.org/doc/rfc9802/)
+
+### XMSS / XMSSMT
+
+- Definition of XMSS and XMSSMT:
+  - [RFC 8391 — XMSS: eXtended Merkle Signature Scheme](https://datatracker.ietf.org/doc/rfc8391/)
+
+### HSS
+
+- Definition of LMS and HSS:
+  - [RFC 8554 — Leighton–Micali Hash‑Based Signatures](https://datatracker.ietf.org/doc/rfc8554/)
+- Using LMS/HSS in CMS:
+  - [RFC 9708 — Use of the HSS/LMS Hash‑Based Signature Algorithm in the Cryptographic Message Syntax (CMS)](https://datatracker.ietf.org/doc/rfc9708/)
+- Additional parameter sets for HSS/LMS hash‑based signatures:
+  - [draft-fluhrer-lms-more-parm-sets](https://datatracker.ietf.org/doc/draft-fluhrer-lms-more-parm-sets/)
+
+## Hybrid Key Encapsulation Mechanism (KEM)
+
+- [draft-connolly-cfrg-xwing-kem](https://datatracker.ietf.org/doc/draft-connolly-cfrg-xwing-kem/)
+- [draft-ietf-lamps-pq-composite-kem](https://datatracker.ietf.org/doc/draft-ietf-lamps-pq-composite-kem/)
+- [draft-josefsson-chempat](https://datatracker.ietf.org/doc/draft-josefsson-chempat/)
+
+## Hybrid Signature
+
+- [draft-ietf-lamps-pq-composite-sigs](https://datatracker.ietf.org/doc/draft-ietf-lamps-pq-composite-sigs/)
+
+## Hybrid Certificates
+
+- [draft-sun-lamps-hybrid-scheme](https://datatracker.ietf.org/doc/draft-sun-lamps-hybrid-scheme/)
+- [RFC 9763 — Related Certificates for Use in Multiple Authentications within a Protocol](https://datatracker.ietf.org/doc/rfc9763/)
+- [draft-lamps-okubo-certdiscovery](https://datatracker.ietf.org/doc/draft-lamps-okubo-certdiscovery/)
+- [draft-bonnell-lamps-chameleon-certs](https://datatracker.ietf.org/doc/draft-bonnell-lamps-chameleon-certs/)
+- Catalyst (Alternative Signature):
+  - [ITU‑T X.509 (10/2019) — Alternative public key and signature extensions](https://www.itu.int/ITU-T/formal-language/itu-t/x/x509/2019/CertificateExtensions.html)
+  - Document:
+    - [ITU‑T X.509 (10/2019)]( https://www.itu.int/ITU-T/recommendations/rec.aspx?id=14033)
+  - Died draft:
+    - [draft-truskovsky-lamps-pq-hybrid-x509 — Multiple Public‑Key Algorithm X.509 Certificates](https://datatracker.ietf.org/doc/draft-truskovsky-lamps-pq-hybrid-x509/)