Api
ZMQ Protocol Reference
Complete reference for the ZMQ REQ/REP protocol between uPKI CA and RA/CLI.
ZMQ Protocol Reference
The uPKI CA exposes two ZMQ REP sockets. Clients communicate using ZMQ REQ sockets with JSON payloads.
Transport
| Property | Value |
|---|---|
| Protocol | ZMQ REQ/REP (zmq.REP) |
| Serialization | JSON strings (UTF-8) |
| Timeout | 5000 ms |
| Port 5000 | CA operations (all registered nodes) |
| Port 5001 | RA registration (first-boot only, clear mode) |
Message format
Request
{
"TASK": "<task_name>",
"params": {
"<param>": "<value>"
}
}
Success response
{
"EVENT": "ANSWER",
"DATA": <result>
}
Error response
{
"EVENT": "UPKI ERROR",
"MSG": "<error_message>"
}
Port 5000 — CA operations
Certificate tasks
| Task | Required params | Optional params | Response |
|---|---|---|---|
get_ca | — | — | PEM cert string |
get_crl | — | — | Base64 CRL |
generate_crl | — | — | Base64 CRL |
generate | cn | profile, sans, local | {dn, certificate, serial} |
sign | csr | profile | {certificate, serial} |
register | seed, cn | profile, sans | {dn, certificate, serial} |
renew | dn | duration | {certificate, serial} |
revoke | dn | reason | boolean |
unrevoke | dn | — | boolean |
delete | dn | — | boolean |
view | dn | — | certificate details dict |
ocsp_check | cert | — | OCSP status dict |
Profile tasks
| Task | Required params | Response |
|---|---|---|
list_profiles | — | list of profile names |
get_profile | profile | profile details dict |
Admin tasks
| Task | Required params | Response |
|---|---|---|
list_admins | — | list of admin DNs |
add_admin | dn | boolean |
remove_admin | dn | boolean |
list_nodes | — | list of node dicts |
get_node | cn | node details dict |
ACME sync tasks
| Task | Required params | Optional params | Response |
|---|---|---|---|
acme_sync_account | account_id, jwk | contact, status, created_at | boolean |
acme_get_account | account_id | — | account dict |
acme_list_accounts | — | — | list of account dicts |
acme_deactivate_account | account_id | — | boolean |
acme_sync_order | order_id, account_id, identifiers | status, not_before, not_after | boolean |
acme_get_order | order_id | — | order dict |
acme_list_orders | account_id | — | list of order dicts |
acme_sync_authorization | auth_id, order_id, identifier_type, identifier_value | status | boolean |
acme_get_authorization | auth_id | — | authorization dict |
acme_deactivate_authorization | auth_id | — | boolean |
acme_issue_certificate | order_id, csr | profile | {certificate, serial} |
acme_get_certificate | cert_id | — | certificate dict |
acme_revoke_certificate | certificate | reason | boolean |
Port 5001 — RA registration
Registration is a one-shot operation. The RA presents its seed and CN; the CA issues a certificate.
{
"TASK": "register",
"params": {
"seed": "registration-seed",
"cn": "upki-ra",
"profile": "ra",
"sans": [{ "type": "DNS", "value": "upki-ra" }]
}
}
Examples
Get the CA certificate
import zmq
import json
ctx = zmq.Context()
sock = ctx.socket(zmq.REQ)
sock.connect("tcp://127.0.0.1:5000")
sock.send_string(json.dumps({"TASK": "get_ca", "params": {}}))
reply = json.loads(sock.recv_string())
ca_pem = reply["DATA"]
Issue a server certificate
sock.send_string(json.dumps({
"TASK": "generate",
"params": {
"cn": "api.example.internal",
"profile": "server",
"sans": [{"type": "DNS", "value": "api.example.internal"}]
}
}))
result = json.loads(sock.recv_string())
# result["DATA"] = {"dn": "...", "certificate": "...", "serial": "..."}
Revoke a certificate
sock.send_string(json.dumps({
"TASK": "revoke",
"params": {
"dn": "/CN=api.example.internal",
"reason": "keyCompromise"
}
}))
result = json.loads(sock.recv_string())
# result["DATA"] = True