<!-- Copyright (c) 2026 defconxt. All rights reserved. -->
<!-- Licensed under AGPL-3.0 — see LICENSE file for details. -->

# API Reference — Implementing PKI Infrastructure

## openssl genpkey

### Synopsis

```bash
openssl genpkey -algorithm <alg> [-pkeyopt <opt>] -out <key.pem>
```

### Algorithms

| Algorithm | Option | Recommended |
|---|---|---|
| RSA-4096 | `-pkeyopt rsa_keygen_bits:4096` | Root CAs |
| ECDSA P-384 | `-pkeyopt ec_paramgen_curve:P-384` | Intermediate CAs |
| ECDSA P-256 | `-pkeyopt ec_paramgen_curve:P-256` | Leaf certificates |
| Ed25519 | (no options) | Signatures only |

## openssl req

### Synopsis

```bash
openssl req -new [-x509] -key <key.pem> -out <csr|cert.pem> -subj <dn>
```

### Key Options

| Option | Description |
|---|---|
| `-new` | Generate new CSR |
| `-x509` | Output self-signed cert instead of CSR |
| `-key` | Private key file |
| `-subj` | Subject DN (e.g., `/C=US/O=Org/CN=Name`) |
| `-addext` | Add X.509 extension inline |
| `-days` | Validity period (with `-x509`) |

## step-ca

### Commands

| Command | Description |
|---|---|
| `step ca init` | Initialize a new CA |
| `step ca certificate <cn> <cert> <key>` | Issue a certificate |
| `step ca renew <cert> <key>` | Renew before expiry |
| `step ca revoke --cert <cert> --key <key>` | Revoke a certificate |
| `step ca provisioner add` | Add ACME/OIDC provisioner |

## CFSSL

### Commands

| Command | Description |
|---|---|
| `cfssl gencert -initca ca-csr.json` | Generate root CA |
| `cfssl gencert -ca ca.pem -ca-key ca-key.pem csr.json` | Sign certificate |
| `cfssl serve` | Run CFSSL API server |

## Agent Script

```bash
# Generate root CA
node agent.js root --subject "/C=US/O=Example/CN=Root CA"

# Generate intermediate CA
node agent.js intermediate --subject "/C=US/O=Example/CN=Issuing CA" \
  --root-cert root-ca.pem --root-key root-ca-key.pem

# Issue leaf certificate
node agent.js leaf --subject "/CN=app.example.com" \
  --ca-cert intermediate.pem --ca-key intermediate-key.pem \
  --san "DNS:app.example.com,DNS:www.example.com"

# Verify chain
node agent.js verify leaf.pem --intermediate intermediate.pem --root root-ca.pem
```
