Certificate

Manage the TLS certificate of the web interface

The device serves its web interface and this API over HTTPS with a certificate stored on the device. Out of the box, and whenever the stored certificate is missing or invalid, a self-signed certificate is generated. An administrator can upload a certificate issued by a certificate authority or generate a new self-signed one. Either action takes effect immediately: the web server is restarted, so open browser sessions must reconnect.

API

• Import a certificate and key

  • Path: /api/ssl/import

  • Method: POST

  • Minimum user role: admin

  • Request body: multipart/form-data with two file parts, each at most 128 KiB:

    • certificate - the certificate in PEM format
    • key - the matching private key in PEM format, RSA or EC, not password protected

  • Requirements checked before the pair is installed:

    • the private key is valid and its public key matches the certificate;
    • the certificate carries a non-empty subjectAltName extension;
    • the certificate carries a non-empty extendedKeyUsage extension.

  • Response on success (200 OK): {"message": "Successfully saved certificate and key", "data": null}

  • Response on failure:

    • 400 Bad Request, {"message": "Both certificate and key fields must be present on multiform data.", "data": null} when a part is missing or the body is not multipart
    • 413 Payload Too Large, { "response": "The size of the payload (<bytes>) is above the specified limit: 131072." } when a part exceeds 128 KiB
    • 422 Unprocessable Entity, {"message": "Provided certificate-key pair is invalid", "data": null} when any requirement above fails; the previous certificate stays in place

  • Example:

    curl -k -X POST -H "authorization: <token>" -F "certificate=@server.crt" -F "key=@server.key" https://<ip-address>/api/ssl/import

• Generate a self-signed certificate
  • Path: /api/ssl/generate
  • Method: POST
  • Minimum user role: admin
  • Request body: none
  • Response on success (200 OK): {"message": "Successfully generated new certificate", "data": null}
  • Response on failure (500 Internal Server Error): {"message": "Could not generate new certificate", "data": null}
  • Notes: the generated certificate is X.509 v3, valid for one year from the moment of generation, subject and issuer CN = Profitap BV, with subjectAltName DNS:Profitap BV, DNS:iota.profitap.com. The previous certificate and key are replaced immediately.

Back to Index