Configuring TLS for the IDIAL REST API

By default, the IDIAL REST API runs without TLS. For production use, HTTPS should be enabled so that API keys and payload data are transmitted encrypted. This guide describes two approaches: uploading a certificate via the API and configuring via environment variables in Docker Compose.

warning

After uploading a new TLS certificate via the API, the IDIAL container must be restarted for the new TLS context to become fully active.

Prerequisites

• A TLS certificate is available (as a PKCS#12 file or as a separate PEM certificate + key)
• An API key is available (for the upload approach)
• Access to the Docker Compose configuration (for the environment variable approach)

Approach A — Upload TLS certificate via API

Step 1 — Check current TLS status

curl -s https://<idial-host>:5000/tls

note

GET /tls requires no authentication.

Example response when TLS is inactive:

{
  "enabled": false,
  "cert_file": "/app/tls/tls_server_cert.pem",
  "key_file": "/app/tls/tls_server_key.pem",
  "tls_server_certificate": null,
  "fingerprint": null,
  "protocols": [],
  "ciphers": [],
  "message": "TLS inactive — certificate or key file not found"
}

Step 2 — Encode PKCS#12 file as Base64

base64 -w 0 mein-zertifikat.p12 > cert_b64.txt

Step 3 — Upload certificate

curl -s -X POST \
  -H "X-API-Key: <api-key>" \
  -H "Content-Type: application/json" \
  -d "{
    \"tls_server_pkcs12_base64\": \"$(cat cert_b64.txt)\",
    \"tls_server_pkcs12_password\": \"<pkcs12-passwort>\"
  }" \
  https://<idial-host>:5000/tls

Parameter	Type	Required	Description
tls_server_pkcs12_base64	string	yes	Base64-encoded content of the PKCS#12 file (.p12 / .pfx)
tls_server_pkcs12_password	string	yes	Password to decrypt the PKCS#12 file

Step 4 — Restart the container

docker compose restart idial

Step 5 — Confirm TLS status

curl -s https://<idial-host>:5000/tls

Expected response when TLS is active:

{
  "enabled": true,
  "cert_file": "/app/tls/tls_server_cert.pem",
  "key_file": "/app/tls/tls_server_key.pem",
  "tls_server_certificate": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----\n",
  "fingerprint": "A1:B2:C3:D4:E5:F6:07:08:09:10:11:12:13:14:15:16:17:18:19:20",
  "protocols": ["TLSv1_2", "TLSv1_3"],
  "ciphers": ["TLS_AES_256_GCM_SHA384", "..."],
  "message": "TLS active"
}

Response fields

Field	Description
enabled	true if certificate and key file are present and readable
cert_file	Absolute path to the certificate file in the container
key_file	Absolute path to the key file in the container
tls_server_certificate	Full PEM certificate
fingerprint	SHA-1 fingerprint, colon-separated
protocols	Supported TLS versions
ciphers	Supported cipher suites
message	Status description

Approach B — Configure TLS via environment variables

Alternatively, the certificate and key can be provided via Docker volumes.

Environment variables

Variable	Default in container	Description
IDIAL_TLS_CERT_FILE	/app/tls/tls_server_cert.pem	Path to the TLS certificate file (PEM)
IDIAL_TLS_KEY_FILE	/app/tls/tls_server_key.pem	Path to the private key file (PEM)

Docker Compose example

services:
  idial:
    image: idial:latest
    volumes:
      - rest_tls:/app/tls:rw
    environment:
      - IDIAL_TLS_CERT_FILE=/app/tls/tls_server_cert.pem
      - IDIAL_TLS_KEY_FILE=/app/tls/tls_server_key.pem
    ports:
      - "${IDIAL_REST_PORT:-5000}:5000"

volumes:
  rest_tls:

Place the PEM files into the volume before starting:

docker run --rm \
  -v rest_tls:/target \
  -v /pfad/zu/certs:/certs:ro \
  alpine sh -c "cp /certs/tls_server_cert.pem /target/ && cp /certs/tls_server_key.pem /target/"

tip

Approach B is particularly suitable for automated deployments where certificates are provided via a secrets management system (e.g. Vault, Kubernetes Secrets).

Summary

GET /tls            → check TLS status (no authentication required)
POST /tls           → upload PKCS#12 certificate (API key required)
Docker restart      → activate new TLS context
Environment vars    → alternatively configure paths to PEM files

Next steps

• GET /tls and POST /tls — API Reference
• Registering a GDS Push Device

Troubleshooting

Symptom	Possible cause	Solution
"enabled": false after restart	Certificate or key file not in volume	Check volume mount and file paths
Upload fails	Incorrect PKCS#12 password	Verify password, test PKCS#12 file with openssl pkcs12 -info
Browser shows certificate warning	Self-signed certificate	Add CA certificate as trusted in the browser/client
HTTP instead of HTTPS after restart	TLS files not readable (permissions)	Check file permissions in the container: docker exec idial ls -la /app/tls/