TLS Configuration

This page documents the endpoints for querying and configuring the TLS certificate of the IDIAL REST API. TLS secures communication between clients and the API. The endpoints described here allow you to check the current TLS status and upload a new certificate.

GET /tls

Returns the current TLS configuration of the IDIAL REST API. The response contains the certificate status, file paths, the active server certificate in PEM format, its SHA1 fingerprint, and the supported TLS protocols and cipher suites. This endpoint is used to verify the correct TLS configuration before putting IDIAL into production.

Authentication: Not required

Request

curl -X GET http://localhost:5000/tls

Response 200

{
  "enabled": true,
  "cert_file": "/app/certs/server.crt",
  "key_file": "/app/certs/server.key",
  "tls_server_certificate": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----",
  "fingerprint": "A1:B2:C3:D4:E5:F6:78:90:12:34:56:78:90:AB:CD:EF:12:34:56:78",
  "protocols": ["TLSv1_2", "TLSv1_3"],
  "ciphers": ["ECDHE-RSA-AES256-GCM-SHA384", "TLS_AES_256_GCM_SHA384"],
  "message": "TLS active"
}

Response Fields

Field	Type	Description
enabled	boolean	TLS availability status. true: Both the certificate file and the private key file exist and are readable. false: At least one of the files is missing or unreadable. Purpose: Quick TLS status check for applications and monitoring.
cert_file	string	Absolute filesystem path to the TLS certificate file inside the container.
key_file	string	Absolute filesystem path to the TLS private key file inside the container.
tls_server_certificate	string	Full PEM-encoded certificate content of the TLS certificate used by IDIAL. Content: Complete certificate including the -----BEGIN CERTIFICATE----- and -----END CERTIFICATE----- headers. Empty string "" if the certificate file is not available. Purpose: Certificate validation and analysis without filesystem access.
fingerprint	string	SHA1 fingerprint of the TLS certificate in hexadecimal format. Format: Colon-separated hex pairs (e.g., "A1:B2:C3:D4:E5:F6:78:90:12:34:56:78:90:AB:CD:EF:12:34:56:78"). Empty string "" if no certificate is available. Purpose: Certificate identification and verification.
protocols	string[]	List of supported TLS protocol versions available on the system. Examples: ["TLSv1_2", "TLSv1_3"]. Purpose: Protocol compatibility check for client connections.
ciphers	string[]	List of available cipher suites supported by the TLS context. Sorted alphabetically. Examples: ["TLS_AES_256_GCM_SHA384", "TLS_CHACHA20_POLY1305_SHA256", "ECDHE-RSA-AES256-GCM-SHA384"]. Purpose: Security configuration and cipher suite selection.
message	string	Human-readable status description. "TLS active" when both files are available. "TLS inactive (certificate and key required)" when files are missing. May contain specific status information from TLS operations.

---

POST /tls

Uploads a PKCS#12 container to configure TLS for the IDIAL REST API. IDIAL extracts the certificate and private key, validates them, and writes them to the filesystem. TLS is activated immediately after a successful upload. The IDIAL service must be restarted for the TLS context to be fully applied.

Authentication: Required (X-API-Key header)

Request Body

{
  "tls_server_pkcs12_base64": "MIIKxgIBAzCCCoIGCSqGSIb3...",
  "tls_server_pkcs12_password": "your-pkcs12-password"
}

Request Fields

Field	Type	Required	Description
tls_server_pkcs12_base64	string	Yes	Base64-encoded PKCS#12 container with TLS certificate and private key. Format: Standard Base64 encoding without spaces or line breaks. Must contain both the X.509 certificate and the associated private key. No explicit size limit, though practical limits apply due to system resources. Base64 decoding is validated before PKCS#12 processing.
tls_server_pkcs12_password	string	Yes	Password for decrypting the PKCS#12 container. Used exclusively during processing and not stored permanently. An empty string is rejected. UTF-8 string encoding is supported.

Response 200

The response matches the format of GET /tls.

Response 400

{"error": "string"}

Validation failed: missing fields, invalid Base64 format, or incorrect password.

warning

After uploading a new TLS certificate via this endpoint, the IDIAL service should be restarted to ensure the new TLS context is fully loaded. The enabled field in the response confirms that the files were written successfully.

tip

To create a PKCS#12 container from an existing PEM certificate and key:

openssl pkcs12 -export \
  -in server.crt \
  -inkey server.key \
  -out server.p12 \
  -passout pass:your-password

# Convert to base64 for the API request:
base64 -w 0 server.p12

Examples

# GET /tls - Check TLS status
curl -X GET http://localhost:5000/tls

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