Certificate Lifecycle

States

A certificate in uPKI CA goes through the following states:

[not issued] → issued → revoked → unrevoked → issued
                  └──────────────────────────► deleted

Generation methods

generate — full key generation

The CA generates both the private key and the certificate. The private key is stored inside the CA's data directory.

Use when: You control the endpoint and are comfortable with the CA holding the private key.

{
  "TASK": "generate",
  "params": {
    "cn": "server.example.internal",
    "profile": "server",
    "sans": ["server.example.internal", "192.168.1.10"]
  }
}

sign — external CSR

The caller generates the private key locally and submits a PKCS#10 CSR. The CA signs it and returns the certificate. The private key never leaves the caller.

Use when: Private key must not leave the client (mTLS, HSM scenarios).

{
  "TASK": "sign",
  "params": {
    "csr": "-----BEGIN CERTIFICATE REQUEST-----\n...",
    "profile": "server"
  }
}

register — node self-registration

Used by RA nodes during their initial registration. Combines key generation and certificate issuance in one step, authenticated by a shared seed.

Renewal

Renewing a certificate extends its validity without changing the key pair. The dn (Distinguished Name) uniquely identifies the certificate to renew.

{
  "TASK": "renew",
  "params": {
    "dn": "/CN=server.example.internal"
  }
}

An optional duration parameter (in days) overrides the profile's default validity period.

Revocation

Revoke

{
  "TASK": "revoke",
  "params": {
    "dn": "/CN=compromised.example.internal",
    "reason": "keyCompromise"
  }
}

Valid reason values: unspecified, keyCompromise, cACompromise, affiliationChanged, superseded, cessationOfOperation, certificateHold, removeFromCRL, privilegeWithdrawn, aACompromise.

Revoked certificates are added to the CRL on the next generate_crl call.

Unrevoke

{
  "TASK": "unrevoke",
  "params": {
    "dn": "/CN=previously-revoked.example.internal"
  }
}

Removes the certificate from the CRL and marks it as valid again.

CRL management

The CRL must be regenerated manually (or on a schedule) after revocations:

{
  "TASK": "generate_crl",
  "params": {}
}

The CRL is returned as a base64-encoded DER blob and stored in crl.pem in the data directory.