Api

Error Codes

ZMQ error responses from uPKI CA.

ZMQ error format

All errors are returned as:

{
  "EVENT": "UPKI ERROR",
  "MSG": "<human-readable error message>"
}

Message pattern	Cause	Resolution
`Unknown task: <task>`	The `TASK` field contains an unrecognised value	Check the task name against the ZMQ protocol reference
`Profile <name> not found`	The requested certificate profile does not exist	Run `list_profiles` to see available profiles
`Certificate not found: <dn>`	No certificate exists with the given DN	Verify the DN with `list_nodes`
`Invalid seed`	The registration seed does not match	Check `UPKI_CA_SEED` matches the seed printed at `init`
`Certificate already exists: <dn>`	A certificate for this CN is already active	Renew the existing certificate with `renew`
`Node is revoked: <dn>`	The target certificate has been revoked	Unrevoke with `unrevoke` or delete and reissue
`Storage error: <detail>`	Filesystem or TinyDB error	Check disk space and permissions on `UPKI_DATA_DIR`
`Key generation failed`	Cryptographic error during key creation	Check key type and length in `ca.config.yml`
`CSR parse error`	The provided CSR is malformed	Ensure the CSR is in valid PEM format

When the RA forwards a request to the CA and the CA returns an error, the RA translates it:

ZMQ error	ACME error type	HTTP status
`Invalid seed`	`urn:ietf:params:acme:error:unauthorized`	403
`Certificate not found`	`urn:ietf:params:acme:error:malformed`	400
`Profile not found`	`urn:ietf:params:acme:error:malformed`	400
Generic CA error	`urn:ietf:params:acme:error:serverInternal`	500

Enable debug output on the CA:

python ca_server.py start --debug

Or check the RA logs — the RA logs every ZMQ request and response it sends to the CA:

docker logs upki-ra --follow

ZMQ Protocol Reference

Complete reference for the ZMQ REQ/REP protocol between uPKI CA and RA/CLI.

Contributing

How to contribute to uPKI CA.