TLS Configuration

These endpoints manage the TLS certificate used by the IDIAL REST API server itself. Uploading a new certificate requires a service restart to take effect.

GET /tls

Returns the current TLS configuration of the IDIAL container.

Authentication: Required (X-API-Key header)

Request

curl -X GET http://localhost:5000/tls \
  -H "X-API-Key: your-api-key"

Response 200

{
  "enabled": true,
  "cert_file": "/app/tls/tls_server_cert.pem",
  "key_file": "/app/tls/tls_server_key.pem",
  "tls_server_certificate": "-----BEGIN CERTIFICATE-----\nMIID...\n-----END CERTIFICATE-----",
  "fingerprint": "AA:BB:CC:DD:EE:FF:00:11:22:33:44:55:66:77:88:99:AA:BB:CC:DD",
  "protocols": ["TLSv1_2", "TLSv1_3"],
  "ciphers": ["ECDHE-RSA-AES256-GCM-SHA384", "ECDHE-RSA-AES128-GCM-SHA256"],
  "message": "TLS is active"
}

Response Fields

Field	Type	Description
enabled	boolean	Whether TLS is currently configured.
cert_file	string	Path to the TLS certificate file inside the container.
key_file	string	Path to the TLS private key file inside the container.
tls_server_certificate	string | null	PEM-encoded TLS server certificate.
fingerprint	string | null	SHA-1 fingerprint of the certificate (colon-separated hex).
protocols	string[]	Supported TLS protocol versions.
ciphers	string[]	Supported cipher suites.
message	string	Status or info message.

---

POST /tls

Uploads a new TLS server certificate from a PKCS#12 bundle. The certificate and private key are extracted and stored. A service restart is required for the new TLS context to apply.

Authentication: Required (X-API-Key header)

warning

After uploading a new certificate via this endpoint, the IDIAL service must be restarted for the new TLS context to take effect. The old certificate remains active until restart.

Create a PKCS#12 bundle

# Create PKCS#12 from existing certificate and key
openssl pkcs12 -export \
  -in server.crt \
  -inkey server.key \
  -out server.p12 \
  -passout pass:your-password

# Encode as base64 (single line)
base64 -w 0 server.p12

Request

curl -X POST http://localhost:5000/tls \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "tls_server_pkcs12_base64": "MIIJrQIBAzCC...",
    "tls_server_pkcs12_password": "your-password"
  }'

Request Fields

Field	Type	Required	Description
tls_server_pkcs12_base64	string (≥ 160 chars)	Yes	Base64-encoded PKCS#12 file containing certificate and private key.
tls_server_pkcs12_password	string (≤ 1024 chars)	Yes	Password to decrypt the PKCS#12 file.

Response 200

Response matches the format of GET /tls, with an additional message confirming the upload.

Response 400

{"error": "string"}

Returned when the PKCS#12 is invalid, cannot be decrypted, or the extracted certificate is malformed.