SSL Configuration
The ssl section defines how TDS handles HTTPS encryption. The following options configure the lookup paths of certificates and related files.
| Name | Value type | Default | Behavior |
|---|---|---|---|
use | boolean | true | Recommended: when active uses HTTPS instead of HTTP. |
cert-file | filesystem path (file) | %TDS_DATA_DIR%/tds2/certificate.pem | Path pointing to the SSL certificate file used for the encryption. |
private-key-file | filesystem path (file) | %TDS_DATA_DIR%/tds2/key-file.pem | Path pointing to the private key used for the encryption. |
dh-param-file | filesystem path (file) | %TDS_DATA_DIR%/tds2/dh-params.pe | Path pointing to the Diffie-Hellman parameter file used for the encryption. |
Initially, when opening the TDS web interface, the following message might appear for example:
Reason for Self-Signed Certificate Warning
The above error is displayed because TDS uses so-called self-signed certificates by default. During the first setup, the SSL certificate and the respective files are generated so that an encrypted SSL connection can be established.
Upon opening the site, the browser checks whether the certificate that enables the secure connection is signed by one of the official authorities. If this is not the case, as it is for example with the locally generated default certificates, the browser will display a warning since it cannot verify that the connection partner is really TDS and not someone else pretending to be TDS.
Since the certificate is generated locally and kept within company, it can generally be trusted anyway. However, it is recommended during integration into the company domain to generate a trusted certificate for TDS.
Fixing the Warning
To fix the error, the three file paths: cert-file, private-key-file and dh-param-file from the tds-server.json must be updated to point to your official or domain-wide trusted certificate files.
These files must be provided as .pem files and should be separate files each. cert-file must contain the certificate which looks like this:
-----BEGIN CERTIFICATE-----
MIIC6TCCAdECBHP7QGkwDQYJKoZIhvcNAQEFBQAwOTELMAkGA1UEBhMCQ0ExFjAU
BgNVBAoMDU15Q29tcGFueSBJbmMxEjAQBgNVBAMMCWxvY2FsaG9zdDAeFw0yMjAy
........................ continuing ............................
F02gxT02VNPFe5LarZDfaGYYlnERkJ5T6BBui/2OicOE0qKZ5XScm3NDmmUVbZ3S
Vmxwah09Tyqx8q9j2dP1pZ/KCGO5mm1to2FhCI8=
-----END CERTIFICATE-----
private-key-file is the private key which is generated along with the certificate. Finally, dh-param-file is a set of Diffie-Hellman parameters that need to be generated, additionally.
Alternatively, the SSL encryption can be turned off by setting "use": false. This is not recommended, however, as any network traffic to and from TDS can then be read by anyone on the network!
Obtaining the Files
The procedure to obtain a valid ceritificate for the domain running TDS differs depending on the domain registrar.
Generating or obtaining SSL certificates is a task for the administrators of your domain. Usually you'll have to check with your IT to get these files.
There are services like letsencrypt.org which generate these certificates for you if you can prove the ownership over your domain using different kind of challenges.
Alternatively, your registrar might already be providing SSL certificates for your domain or wildcard certificates if you're hosting TDS on a subdomain.
However, larger companies often run their own certificate authority, which authenticates internal servers to the web-browsers within the company domain. In such a case, a new certificate can be requested at the company's IT department.
Converting from Other Formats
There are different formats which the certificates can be in. TDS requires the .pem file format. However, there is also the PKCS#7 and PKCS#12 format, for example.
Both of these are encrypted containers containing the same information, as the .pem files, just in a different format.
For each of the conversions, the pubicly available OpenSSL software can be used. It's an open-source encryption software that can be used from the command-line. Inexperienced users may call their IT for additional help in installing the software and issuing the correct commands.
To convert from PKCS#12 to PEM the following commands can be used:
# Requests for the container password and extracts the certificate into <target-pem-cert-file>
openssl pkcs12 -in <source-pkcs12-file> -out <target-pem-cert-file> -clcerts -nodes -nokeys
# Requests for the container password and extracts the private key into <target-pem-key-file>
openssl pkcs12 -in <source-pkcs12-file> -out <target-pem-key-file> -nocerts -nodes
The conversion from PKCS#7 or PKCS#8 can be done accordingly by exchanging pkcs12 with pkcs7 or pkcs8.
If no Diffie-Hellman parameters are provided by the company's IT, they can be generated with OpenSSL via the following:
openssl dhparam -out <target-dh-param-file> -outform PEM 2048
This generates the parameters for 2048 bit encryption. If the private key, for example, is provided as AES-4096, the command should be updated accordingly.
Dealing with Certificate Signing Requests (CSR)
Certificate Signing Requests (CSR) are a means to package the information required by the certificate authority along with a desired public key into a request file. This request is then forwarded to the certificate authority which may issue a trusted certificate, if the information and signature of the request prove the server's authenticity.
Which information needs to be included into the CSR is dependant on the targeted certificate authority. The process of procuring a valid certificate from a CSR is company and certificate authority dependant and should be discussed with the company IT.