Skip to content

PKI REST Workflow

Endi S. Dewata edited this page May 7, 2021 · 2 revisions

Enrollment

Workflow Operation Client CA KRA OCSP Notes

Enrollment

Get list of profiles

GET /pki/profiles

Returns list of profiles (name; description; link to profile)

GET /pki/profile/$id

Return details of profile - inputs; outputs; constraints

Client can parse profile to determine required inout parameters

Manual Enrollment

Workflow Operation Client CA KRA OCSP Notes

Manual Enrollment

Create a request

POST-a /pki/request/$profile_id Payload contains all inputs required by the profile

Creates a request. Returns 201 - Created Returns link to request created /pki/request/$rid

Agent gets list of requests

GET /pki/requests

Return collection of requests (some details and request links)

Agent approves request

PUT /pki/request/$rid/status Payload includes request status object (which specifies approved)

Request is modified. Certificate object is created; Returns link to certifcate.

Get request status

GET /pki/request/$rid/status

Returns 200 OK. Returns status object which includes link to request; link to cert; status

Get certificate

GET /pki/certificate/$certid

Return 200 OK. Returns certificate in whatever relevant format (base64; binary?)

Automated Enrollment

Workflow Operation Client CA KRA OCSP Notes

Automated Enrollment

Create a request

POST-a /pki/request/$profile_id Payload contains all inputs required by the profile

Creates a request. Returns 201 - Created Returns link to request created /pki/request/$rid. Also creates certificate object and passes back link to cert /pki/certificate/$certid

Get certificate

GET /pki/certificate/$certid

Return 200 OK. Returns certificate in whatever relevant format (base64; binary?)

How do we account for nonces? CSRF

Automated Enrollment with Key Archival

Workflow Operation Client CA KRA OCSP Notes

Automated Enrollment with Key Archival

Get transport key

GET /pki/config/kra/cert/transport

Returns 200 OK. Payload includes KRA transport cert.

Create a request

POST-a /pki/request/$profile_id Payload contains all inputs required by the profile. This includes a client generated session key wrapped in the KRA transport key and the private key wrapped in the session key

Creates a request.

POST-a /pki/keyrequest/archive with payload including the wrapped sesssion and private keys

Return status 201 - Created. Create key request and mark as approved. Create key object (unwrapping and storing keys). Return link to key archival request - /pki/keyrequest/$rid and link to key /pki/key/$kid

Update cert record. Returns 201 - Created Returns link to request created /pki/request/$rid. Also creates certificate object and passes back link to cert /pki/certificate/$certid

Revoke Certificate

Workflow Operation Client CA KRA OCSP Notes

Revoke cert

Agent revokes cert

PUT /pki/certificate/$id/status with status=revoked and revocation reason

Return 200 OK. Set certificate as revoked and update CRL. Return status or 204 (no content)

Key Recovery

Workflow Operation Client CA KRA OCSP Notes

Key recovery

Get list of keys/ search for relevant keys

GET /pki/keys - including search criteria such as the cert (for example).

Return collection of references to keys

Agent Requests key recovery

POST-a /pki/keyrequest/recovery - payload includes key_id

Return 201 - Created. Returns link to request created - /pki/keyrequest/$rid

Agent gets list of pending requests

GET /pki/keyrequests with relevant search criteria

Return collection of key requests

Agent approves request (for N agents)

PUT /pki/keyrequest/$rid/status with status=approved

Agent is added to list of approvers. Return 200 OK and return request status - number and list of approvers? approvals still needed?

Agent gets status of request

GET /pki/keyrequest/$rid/status

Return request status. If the agent is the requestor; provide link to key

Agent gets key

GET /pki/key/$kid - must include approved $rid and be the requestor for that request; Do $rids expire? Also include wrapping mechanism (pk12 passwords or client generated symmetric key) wrapped in KRA transport key

Return key wrapped in pk12 package or wrapped in symmetric key;

Key Storage

Workflow Operation Client CA KRA OCSP Notes

Key storage

Get transport key

GET /pki/config/kra/cert/transport

Returns 200 OK. Payload includes KRA transport cert.

Agent Requests key archival

POST-a /pki/keyrequest/archive with payload including the key wrapped with the KRA transport key

Return status 201 - Created. Create key request and mark as approved. Create key object (storing private key). Return link to key archival request - /pki/keyrequest/$rid and link to key /pki/key/$kid

Exact wrapping mechanisms depend on whether it is sync/async. We should use the same mechanisms supported by KMIP

Automated Key Recovery (nAgents=1)

Workflow Operation Client CA KRA OCSP Notes

Automated Key recovery (nAgents=1)

Agent Requests key recovery

POST-a /pki/keyrequest/recovery - payload includes key_id, Also include wrapping secret wrapped in KRA transport key

Return 207 - Other. Returns link to request created - /pki/keyrequest/$rid, link to the key, and the relevant wrapped key(s)

This occurs (for example) in the token case. Do we want to do this in one step? CSRF?

Get Generated Key

Workflow Operation Client CA KRA OCSP Notes

Get generated key

Agent requests generated key pair

POST-a /pki/keyrequest/generate/token - payload includes identifiers (cuid, userid etc.), archival choice and wrapping mechanism (symmetric key) wrapped in KRA transport key

Return 207 - Other. Returns link to request created - /pki/keyrequest/$rid. Also returns generated key pair (wrapped in symmetric key) and link to key stored if archival selected.

Server-side keygen in token, but can be extended to general case. Do we want to do this in one step? CSRF?

Manual Enrollment

Manual Enrollment with Archival

Agent-Authenticated Enrollment

Agent-Authenticated Enrollment with Archival

Directory-Authenticated Enrollment

Directory-Authenticated Enrollment with Archival

Clone this wiki locally