Signals

Issue a client certificate from a CSR

  • Sandbox: available
  • On your own host? Choose https://{host} in the playground.
POST
/v1/signals/certs/issue

Issues a client certificate for your current project from a certificate signing request (CSR), and registers it. Calls into Signals may then present it, and must once SIGNALS_MTLS_ENABLED is on.

Auth: A client credential cannot issue a certificate for itself. Scope: the caller's project (from the token).

Behaviour

  • Make a key and a CSR on your side, and send the CSR as PEM in csr. The private key never leaves your client.
  • The key must be an EC key on P-256 or P-384 that names its curve, or an RSA key of at least 2048 bits, and the CSR's signature must verify. Otherwise 422 CSR_NOT_ACCEPTED, with the reason.
  • Ovok's CA signs a certificate for client authentication only, valid for six months, or until the CA itself expires if that comes first. Its notAfter is in the answer. Its subject is CN=<tenant id> and its subject alternative name urn:ovok:signals-tenant:<tenant id>. Nothing else in the CSR is taken over.
  • The certificate counts towards the project's two: a third answers 409 CERTIFICATE_LIMIT_REACHED.
  • An environment with no CA set up to issue answers 501 FEATURE_NOT_CONFIGURED. If its CA has expired, Ovok registers nothing and answers 500 INTERNAL_ERROR.
  • The answer is 201 with the registered certificate and its PEM in certificate, and Location names it.
  • At 00:00 UTC, 14 days before the certificate expires, Ovok notifies the project's admins in the Console and mails them and its parent project's admins. A certificate registered closer to its expiry is mailed about at once; a removed one is not.
  • To rotate: issue a new certificate, move your clients to it, then remove the old one.

Example

openssl req -new -newkey ec -pkeyopt ec_paramgen_curve:prime256v1 -pkeyopt ec_param_enc:named_curve -nodes \  -keyout client.key -out client.csr -subj "/CN=client"curl -X POST 'https://api.sandbox.ovok.com/v1/signals/certs/issue' \  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk' \  -H 'Content-Type: application/json' \  -d "{ \"csr\": $(jq -Rs . < client.csr) }" | jq -r .certificate > client.crt

Who can call it: a project admin. See roles.

Authorization

bearer
headerAuthorizationBearer <JWT>

Request Body

application/json
  1. body
csr*string

A PKCS#10 certificate signing request, PEM, made with the key your client will present.

Length1 <= length <= 16384

Response Body

The issued certificate, registered already, with its PEM in certificate. Location names it.

application/json
  1. response
sha256*string

SHA-256 fingerprint of the certificate, lowercase hex: its id here.

serialNumber*string
subject*string
notAfter*string

When the certificate expires, ISO 8601. After it, calls with it are refused.

registeredAt*string
certificate*string

The issued client certificate, PEM. Present it with the key the CSR was made with.

Example Request
curl -X POST 'https://api.sandbox.ovok.com/v1/signals/certs/issue' \  -H 'Content-Type: application/json' \  -d '{  "csr": "string"}'
Example Response
{  "sha256": "string",  "serialNumber": "string",  "subject": "string",  "notAfter": "string",  "registeredAt": "string",  "certificate": "string"}

Register a client certificate POST

Registers a client certificate for your current project. Calls into Signals may then present it, and must once `SIGNALS_MTLS_ENABLED` is on. **Auth:** A client credential cannot register a certificate for itself. **Scope:** the caller's project (from the token). ## Behaviour - Send the certificate as PEM in `certificate`. Only its first certificate is read. Never send the private key: it stays with your client. - The certificate must be valid now, not a CA certificate, for client authentication (or have no extended key usage), and issued by a CA your Ovok environment trusts. Otherwise 422 `CERTIFICATE_NOT_ACCEPTED`, with the reason. - An environment with no CA set up for client certificates answers 501 `FEATURE_NOT_CONFIGURED`. - The same certificate twice answers 409 `CERTIFICATE_ALREADY_REGISTERED`; a third certificate 409 `CERTIFICATE_LIMIT_REACHED`. - The answer is 201 with the registered certificate, and `Location` names it. - At 00:00 UTC, 14 days before the certificate expires, Ovok notifies the project's admins in the Console and mails them and its parent project's admins. A certificate registered closer to its expiry is mailed about at once; a removed one is not. - To rotate: register the new certificate, move your clients to it, then remove the old one. ## Example ```bash curl -X POST 'https://api.sandbox.ovok.com/v1/signals/certs' \ -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk' \ -H 'Content-Type: application/json' \ -d "{ \"certificate\": $(jq -Rs . < client.crt) }" ``` **Who can call it:** a project admin. See [roles](/access-policies#who-can-call-a-route).

Remove a client certificate DELETE

Removes one of your current project's client certificates. From then on, calls presenting it are refused. **Scope:** the caller's project (from the token). ## Behaviour - `:sha256` is the certificate's fingerprint as `GET /v1/signals/certs` lists it. - An unknown fingerprint answers 404 `CERTIFICATE_NOT_FOUND`. - While `SIGNALS_MTLS_ENABLED` is on, the project's last certificate cannot be removed: 409 `LAST_CERTIFICATE_IN_USE`. Every call into Signals would be refused without one. Register another certificate, or turn mutual TLS off, first. - The answer is 204 with no body. ## Example ```bash curl -X DELETE 'https://api.sandbox.ovok.com/v1/signals/certs/3f6c0d2a9b8e7f1c4d5a6b7c8d9e0f1a2b3c4d5e6f708192a3b4c5d6e7f80912' \ -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk' ``` **Who can call it:** a project admin. See [roles](/access-policies#who-can-call-a-route).