# API Usage Guide
This guide explains how to use the Hybrid-PKI-Lab API through Swagger UI.
The project supports two API execution modes:
1. **Standard API mode** without liboqs.
2. **Docker PQC API mode** with real liboqs support.
---
## 1. Start the API
### 1.1 Standard API mode
Use this mode for normal development.
$env:HYBRID\_PKI\_DISABLE\_OQS="1"
python -m uvicorn hybrid\_pki.api.main:app --host 127.0.0.1 --port 8000 --reload
Open Swagger UI:
http://127.0.0.1:8000/docs
In this mode:
* Classical PKI endpoints work.
* API endpoints work.
* PQC-dependent endpoints return a clean unavailable status or skip PQC operations.
* No Docker is required.
* No liboqs installation is required.
---
### 1.2 Docker PQC API mode
Use this mode for real post-quantum cryptography experiments.
Build the PQC image:
docker compose --profile pqc build hybrid-pki-pqc
Run the PQC API:
docker compose --profile pqc up hybrid-pki-pqc
Open Swagger UI:
http://127.0.0.1:8001/docs
In this mode:
* liboqs-python is available.
* ML-KEM works.
* ML-DSA works.
* Hybrid X25519 + ML-KEM handshake works.
* PQC benchmarks can run.
---
## 2. General API checks
### 2.1 Root endpoint
Endpoint:
GET /
Expected result:
{
  "project": "Hybrid PKI Lab",
  "status": "running",
  "message": "API is working successfully"
}
---
### 2.2 Health endpoint
Endpoint:
GET /health
Expected result:
{
  "status": "ok"
}
---
## 3. Classical PKI workflow
This workflow demonstrates a classical PKI hierarchy:
Root CA -> Intermediate CA -> Server Certificate
Use Swagger UI and execute the following endpoints in order.
---
### 3.1 Check classical PKI status
Endpoint:
GET /classical/status
Expected result before initialization:
{
  "classical\_module": "available"
}
---
### 3.2 Create a Root CA
Endpoint:
POST /classical/ca/root/init
Example request body:
{
  "common\_name": "Hybrid PKI Lab Root CA",
  "organization": "Hybrid PKI Lab",
  "country": "MA",
  "algorithm": "RSA",
  "days\_valid": 3650
}
Expected result:
{
  "status": "success",
  "message": "Root CA created successfully"
}
Generated files are stored under:
certs/root/
---
### 3.3 Create an Intermediate CA
Endpoint:
POST /classical/ca/intermediate/init
Example request body:
{
  "common\_name": "Hybrid PKI Lab Intermediate CA",
  "organization": "Hybrid PKI Lab",
  "country": "MA",
  "algorithm": "ECDSA",
  "days\_valid": 1825
}
Expected result:
{
  "status": "success",
  "message": "Intermediate CA created successfully"
}
Generated files are stored under:
certs/intermediate/
---
### 3.4 Issue a server certificate
Endpoint:
POST /classical/certificates/server/issue
Example request body:
{
  "common\_name": "server.example.com",
  "organization": "Hybrid PKI Lab",
  "country": "MA",
  "dns\_names": \[
  "server.example.com",
  "www.server.example.com"
  ],
  "algorithm": "ECDSA",
  "days\_valid": 365
}
Expected result:
{
  "status": "success",
  "message": "Server certificate issued successfully"
}
Generated files are stored under:
certs/issued/
---
### 3.5 Verify a server certificate
Endpoint:
POST /classical/certificates/server/verify
Example request body:
{
  "hostname": "server.example.com"
}
Expected result:
{
  "valid": true
}
---
### 3.6 Revoke a server certificate
Endpoint:
POST /classical/certificates/server/revoke
Example request body:
{
  "reason": "keyCompromise"
}
Expected result:
{
  "status": "success",
  "message": "Certificate revoked successfully"
}
---
### 3.7 List revoked certificates
Endpoint:
GET /classical/certificates/revoked
Expected result:
{
  "revoked\_certificates": \[]
}
The list content depends on the certificates revoked during the demo.
---
## 4. PQC status
### 4.1 Standard mode result
Endpoint:
GET /pqc/status
When running without liboqs, the result should indicate that PQC is unavailable or disabled.
Example:
{
  "available": false,
  "message": "OQS support is disabled by HYBRID\_PKI\_DISABLE\_OQS."
}
---
### 4.2 Docker PQC mode result
Endpoint:
GET /pqc/status
When running through Docker PQC mode, the expected result is:
{
  "available": true,
  "message": "liboqs-python is available."
}
This confirms that liboqs-python is correctly loaded inside Docker.
---
## 5. Hybrid PKI workflow
The hybrid workflow requires Docker PQC mode for real post-quantum operations.
---
### 5.1 Check hybrid status
Endpoint:
GET /hybrid/status
Expected result in Docker PQC mode:
{
  "hybrid\_module": "available",
  "pqc\_provider": {
  "available": true,
  "message": "liboqs-python is available."
  }
}
---
### 5.2 Create demo hybrid CA material
Endpoint:
POST /hybrid/ca/create-demo
Expected result:
{
  "status": "success",
  "message": "Hybrid demo CA material created successfully"
}
Generated files are stored under:
certs/hybrid/
---
### 5.3 Verify hybrid CA material
Run again:
GET /hybrid/status
Expected CA material status:
{
  "ca\_material": {
  "classical\_private\_key\_exists": true,
  "classical\_public\_key\_exists": true,
  "pqc\_private\_key\_exists": true,
  "pqc\_public\_key\_exists": true
  }
}
---
### 5.4 Create a demo hybrid certificate
Endpoint:
POST /hybrid/certificates/create-demo
Example request body:
{
  "subject": "CN=hybrid.example.com,O=Hybrid PKI Lab,C=MA",
  "issuer": "CN=Hybrid Root CA,O=Hybrid PKI Lab,C=MA",
  "classical\_algorithm": "ECDSA-P256",
  "pqc\_signature\_algorithm": "ML-DSA-65",
  "days\_valid": 365
}
Expected result:
{
  "status": "success",
  "message": "Hybrid demo certificate created successfully",
  "has\_classical\_signature": true,
  "has\_pqc\_signature": true
}
---
### 5.5 Verify a demo hybrid certificate
Endpoint:
POST /hybrid/certificates/verify-demo
Example request body:
{
  "certificate\_path": "certs/hybrid/hybrid.example.com\_certificate.json",
  "policy": "hybrid-strict"
}
Expected result:
{
  "valid": true,
  "policy": "hybrid-strict",
  "classical\_signature\_valid": true,
  "pqc\_signature\_valid": true,
  "time\_valid": true
}
---
### 5.6 Simulate a real hybrid handshake
Endpoint:
POST /hybrid/handshake/simulate
Example request body:
{
  "pqc\_algorithm": "ML-KEM-768"
}
Expected result:
{
  "status": "success",
  "algorithm": {
  "classical": "X25519",
  "pqc": "ML-KEM-768",
  "kdf": "HKDF-SHA256"
  },
  "secrets\_match": true
}
The most important field is:
{
  "secrets\_match": true
}
This confirms that the classical and post-quantum shared secrets were combined correctly.
---
## 6. Benchmark API workflow
The benchmark API allows running benchmark scripts from Swagger.
---
### 6.1 Check benchmark status
Endpoint:
GET /benchmarks/status
Expected result:
{
  "status": "available"
}
---
### 6.2 Run key generation benchmarks
Endpoint:
POST /benchmarks/run-keygen
Expected result:
{
  "status": "success",
  "message": "Key generation benchmark completed"
}
Results are written to:
benchmarks/results/keygen\_results.json
---
### 6.3 Run signature benchmarks
Endpoint:
POST /benchmarks/run-signatures
Expected result:
{
  "status": "success",
  "message": "Signature benchmark completed"
}
Results are written to:
benchmarks/results/signature\_results.json
---
### 6.4 Run handshake benchmarks
Endpoint:
POST /benchmarks/run-handshake
Expected result:
{
  "status": "success",
  "message": "Handshake benchmark completed"
}
Results are written to:
benchmarks/results/handshake\_results.json
---
### 6.5 Read benchmark results
Endpoint:
GET /benchmarks/results
Expected result:
{
  "status": "success",
  "results": {
  "keygen": {},
  "signatures": {},
  "handshake": {}
  }
}
The exact values depend on the machine and execution mode.
---
## 7. Recommended testing order
For a full API demonstration, use this order:
1\. GET /health
2\. GET /classical/status
3\. POST /classical/ca/root/init
4\. POST /classical/ca/intermediate/init
5\. POST /classical/certificates/server/issue
6\. POST /classical/certificates/server/verify
7\. GET /pqc/status
8\. GET /hybrid/status
9\. POST /hybrid/ca/create-demo
10\. POST /hybrid/certificates/create-demo
11\. POST /hybrid/certificates/verify-demo
12\. POST /hybrid/handshake/simulate
13\. GET /benchmarks/status
14\. POST /benchmarks/run-keygen
15\. POST /benchmarks/run-signatures
16\. POST /benchmarks/run-handshake
17\. GET /benchmarks/results
---
## 8. Important security note
This API is designed for education, experimentation and research.
Do not expose it directly to the public Internet.
Generated material may include:
* Private keys
* Public keys
* Certificates
* Hybrid certificate JSON files
* Benchmark results
* Logs
Generated files under the following directories should not be committed to GitHub:
certs/
logs/
benchmarks/results/
---
## 9. Stop the API
### Standard mode
Use:
CTRL + C
### Docker PQC mode
Use:
CTRL + C
or:
docker compose --profile pqc down