SSL Configuration

When the appliance is imported it contains a default self-signed certificate, so you can use HTTPS to access the appliance via the Management, Monitoring and Speech APIs. However, we recommend replacing this default SSL certificate with your own certificate, signed by your organisation or a trusted third-party certificate authority (CA).

Default behaviour

By default, our appliances allow connections over HTTP. The services on the appliance expose several ports for HTTP access, such as 8080 for the management API and 3000 for the monitoring API.

Since version 3.4.0 of the appliances, we also support HTTPS access to these services over port 443. To use HTTPS simply change the protocol used for API calls from 'http' to 'https', and remove the port from the URL. If you are copying the examples from this document you can set the $APPLIANCE_HOST environment variable like this: export APPLIANCE_HOST=localhost.

Management API Examples

curl -L -X GET "http://${APPLIANCE_HOST}:8080/v1/management/services" \
   -H 'Accept: application/json'

To modify this to use a secure API call, change http:// to https:// and remove the port number :8080 from the URL:

curl -L -X GET "https://${APPLIANCE_HOST}/v1/management/services" \
    -H 'Accept: application/json'

Note: If you are using a self-signed certificate (your own, or the Speechmatics certificate that is used by default), then you will see a warning like this when using the above curl command:

curl: (60) SSL certificate problem: self signed certificate

Warning: The default SSL certificate on the appliance is a self-signed certificate created by Speechmatics, which is not signed by any certificate authority. Your HTTP client or web browser may warn that this is insecure. This warning can be suppressed, for example with cURL by adding the --insecure flag, however customers who are serious about security should not be using the self-signed certificate. We recommend uploading your own SSL certificate to the appliance. Instructions for doing this can be found below.

Important: We have added --insecure to some of them cURL examples in this document so that the command trusts the self signed certificate. You won't need this option once you've uploaded your own certificate and configured your own system to trust it.

Monitoring API Example

With access to the Monitoring API (available on port 3000 if you are using HTTP) you will need to prefix the endpoint with /monitor. For example:

curl --insecure -L -X GET "https://${APPLIANCE_HOST}/monitor/api/2/mem"

Speech API Example

Access to the REST Speech API (available on port 8082 using HTTP), is also possible via HTTPS:

curl --insecure -L -X GET "https://${APPLIANCE_HOST}/v1.0/user/1/jobs/"

Using your own SSL certificate and private key

To use your own SSL certificate you'll need to upload your certificate file as well as the associated private key file.

• The private key file normally has a '.key' extension and should look similar to the example below.

-----BEGIN RSA PRIVATE KEY-----
xqgLwi4gJ9+9Qkavpk3WpPFTTYUfVrCJNviKEn5wA1tuutqLQkRTcxJtrEk8trKI
fCxeZo35yVhYmDGUIuAdAcPRTPj0XZkXQRhkITmD8TYMc/sVlJpFr+TAssGzute8
... 21 lines redacted ...
+bLv4aqI9tZrwpyeziaOuyQRhYodpAjhCyCFMkJjY59BKv/cqMHx8FPDQmaZ9Xs0
SmE9JAknDgF5yLHm1Q6WZ1/L/M4SkgIqEglF7ifLd5M3wskpmHia6/f8Fa2KwbBJ
-----END RSA PRIVATE KEY-----

Note: We do not currently support encrypted/password protected private key files.

• The certificate file should be PEM encoded and normally has a '.crt' or '.pem' extension. It should look similar to this:

-----BEGIN CERTIFICATE-----
MIIGuzCCBaOgAwIBAgIIIHlfyznYUA8wDQYJKoZIhvcNAQELBQAwgbQxCzAJBgNV
BAYTAlVTMRAwDgYDVQQIEwdBcml6b25hMRMwEQYDVQQHEwpTY290dHNkYWxlMRow
... 32 lines redacted ...
P4LMbjCA4mqQvlipibeSAN1E4OrFL47zLcy+H9M0+Rw2CUiwL8QZFq+TAiIZ34tC
UVCh52xpB9/BhO++QbGd1zObqDhcGEg8pJpJIycej9t4GN1eqNSudn0ibsQWev8=
-----END CERTIFICATE-----

Both files should be in PKCS8 format. If you have to upload a certificate chain, then the file you upload should contain the individual certificates concatenated, with your organisation's certificate first.

Uploading the certificate and key to the appliance

To upload your own certificate to the appliance you will need to make a POST request to the /v1/security/sslcertificate endpoint. This can be done using an HTTP client on the command line or with the management interface in a browser.

With the example shown here set APPLIANCE_HOST as appropriate (e.g. export APPLIANCE_HOST=localhost if your appliance is running locally):

curl --insecure -X POST "https://${APPLIANCE_HOST}/v1/security/sslcertificate" \
    -F "keyfile=@appliance.key" -F "certfile=@appliance.crt"

Warning: Do not upload these files over HTTP, or you risk leaking the private key for your certificate.

If the upload succeeds then you should receive an HTTP 200 response with a success message:

{
   "success": true,
   "message": "certificate and private_key applied successfully"
}

Be aware that setting a new certificate will cause the web server in the appliance to restart which can take around five seconds. During this period, requests will still be served, however the old certificate will be used. Existing connections such as job uploads or WebSocket streams will not be interrupted.

You can check the certificate on the appliance by using the openssl tool:

$ openssl s_client -connect ${APPLIANCE_HOST}:443

Disabling HTTP access

If desired, HTTP access may be disabled, which will cause any requests to the appliance using HTTP to fail. To do this, make a POST request to the /v1/security/insecureports endpoint, with a JSON body containing {"enable_insecure_ports": false}:

curl -X POST "https://${APPLIANCE_HOST}/v1/security/insecureports" \
    -H "Content-Type: application/json" \
    -d "{ \"enable_insecure_ports\": false}"

If the request succeeded then you should receive an HTTP 200 response. The web server in the appliance will take around five seconds to restart. Now, when attempting to make an HTTP request to the appliance you should see that no response is returned:

curl -X GET "http://${APPLIANCE_HOST}:8080/v1/management/services"

curl: (52) Empty reply from server

Enable Basic Authentication for Admin

An admin password can be set to enable HTTP basic authentication for an admin user. Note that authentication is only enforced when using HTTPS. If you set an admin password then you must also disable HTTP access as described in the previous section. If you do not do this then it will be possible for someone else to override the admin password by making an unauthorized HTTP request.

To set a password, make a POST request to the /v1/security/adminpassword endpoint. The username for basic auth is always admin.

curl -X POST "https://${APPLIANCE_HOST}/v1/security/adminpassword" \
  -H "Content-Type: application/json" \
  -d "{ \"password\": \"example\" }"

{"success":true,"message":"nginx_restart"}

If this request was successful then you should receive an HTTP 200 response with a success message. The web server in the appliance will take around five seconds to restart. All requests to HTTPS endpoints will now require a valid Authorization header as specified by RFC7617. Unauthenticated requests will fail, for example:

$ curl -X GET "https://${APPLIANCE_HOST}/v1/management/services"
<html>
<head><title>401 Authorization Required</title></head>
<body>
<center><h1>401 Authorization Required</h1></center>
<hr><center>nginx/1.17.6</center>
</body>
</html>

Authenticated requests should succeed. If you are using curl then the --user flag can be used to set the username and password (separated with a colon). If you're using the Management UI in a browser than a prompt will appear for a username and password.

$ curl --insecure -X GET --user "admin:example" "https://${APPLIANCE_HOST}/v1/management/services"

If you have disabled HTTP access then it should now be impossible to make requests to the appliance without knowing the admin password. Please be aware that plain HTTP access does not require the admin password, and should be disabled if you are using a password.

FAQs

How do I reset the SSL settings?

If you have made a mistake in your SSL configuration, it is possible to reset the appliance to it's default settings. This will return it to using the self-signed certificate from Speechmatics, and will delete any configured admin password. If you have disabled HTTP access then you need to know the existing admin password in order to do this.

To do this, make a DELETE request to the /v1/security/reset endpoint:

$ curl -X DELETE --user "admin:$PWD" "https://${APPLIANCE_HOST}/v1/security/reset"
{"success": true, "message": "nginx_restart"}

What if I forget the admin password?

If you have forgotten the admin password you have set, and have disabled HTTP access to the appliance then it will not be possible to interact with the appliance over HTTP/HTTPS. Fortunately there is a way to reset the SSL configuration if you have direct access to the appliance's console (through the hypervisor that you use).

See the 'Administration -> Services -> Console for Advanced Troubleshooting' section for instructions on how to access the console.

Once you have opened the console open the 'Security' menu and select the 'Reset security' option to reset all security settings. It is also possible to toggle HTTP access and set the admin password using this interface.

What versions of SSL/TLS do you support?

We support TLS 1.2 and TLS 1.3. We do not support earlier versions of TLS/SSL as these are considered weak. In general we would recommend you keep your client frameworks up to date with the latest security patches and try to use the strictest TLS configuration that you can.

What cipher suites do you support?

For TLS 1.3 we support the following cipher suites that are considered strong (in server-preferred order):

• TLS_AES_256_GCM_SHA384
• TLS_CHACHA20_POLY1305_SHA256
• TLS_AES_128_GCM_SHA256

For TLS 1.2 we support the following cipher suites that are considered strong (in server-preferred order):

• TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
• TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256
• TLS_ECDHE_RSA_WITH_ARIA_256_GCM_SHA384
• TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
• TLS_ECDHE_RSA_WITH_ARIA_128_GCM_SHA256

Other cipher suites are available for TLS 1.2, but they are considered to be weak. Our recommendation is that you select one of the above cipher suites.