Docs

# Configure TLS/SSL

WARNING

This feature is not available in free trial and shared deployment

EMQ X Cloud Dedicated Deployment provides custom one-way/two-way TLS/SSL configuration, as follows:

Certification ModeWhether to support self-signed certificateServer certificateCertificate chainPrivate keyClient CA certificate
one-way AuthenticationYesrequiredrequiredrequirednot required
two-way AuthenticationYesrequiredrequiredrequiredrequired

# Certificate restrictions

  • The certificate must specify the encryption algorithm and key size. EMQ X Cloud supports the following algorithms:

    • 1024 bit RSA (RSA_1024)
    • 2048 bit RSA (RSA_2048)

  • The certificate must be an SSL/TLS X.509 version 3 certificate. It must contain the public key, the fully qualified domain name (FQDN) or IP address of the website, and information about the publisher. The certificate can be self-signed by your private key or the private key of the issuing CA. If the certificate is signed by a CA, the certificate chain must be included when importing the certificate.

  • The certificate must be valid. The certificate cannot be imported within 60 days before the beginning and end of the validity period.

  • The certificate, private key and certificate chain must use PEM encoding.

  • The private key must be passwordless.

  • The encryption algorithm of the certificate must match the encryption algorithm of the signing CA. For example, if the key type of the signing CA is RSA, the key type of the certificate must also be RSA.

  • Format description:

    • Certificate format.
    -----BEGIN CERTIFICATE-----
Base64–encoded certificate
-----END CERTIFICATE-----
    • The certificate chain format.
    -----BEGIN CERTIFICATE-----
Base64–encoded certificate
-----END CERTIFICATE-----
    • Private key format.
    -----BEGIN CERTIFICATE-----
Base64–encoded certificate
-----END CERTIFICATE-----

# New certificate

  1. Login EMQ X Cloud Console (opens new window).
  2. Go to the deployment details and click on the +TLS/SSL configuration button to configure the certificate contents, either by uploading a file or by filling in the certificate contents directly
    • Type of certification:
      • One-way authentication: only the client verifies the server-side certificate
      • Two-way authentication: the client and the server validate each other's certificates.
    • Certificates: server-side certificates
    • Certificate chain: the certificate chain, which is usually provided when a third party issues a certificate, can be completed by going to Certificate chain completion (opens new window) if it is missing.
    • Private keys: private keys
    • CA certificate: the client's CA certificate is required when selecting two-way certification
  3. When you have completed the form, click on "OK".

tls

# Test connections

Before testing, make sure that you have created authentication information, refer to certification and authentication, you can connect and test using MQTTX (opens new window). In this tutorial we will use MQTTX for testing:

  • To create a new connection, enter the Name, Client ID is randomly generated
  • Select Host and fill in the deployed connection address and port
    • If you select an SSL connection, select ports mqtts:// and 8883
    • If you select Websocket with SSL, select ports wss:// and 8084
  • Enter the authentication information you have created: username and password
  • Select true on SSL/TLS
  • Certificate selection
    • Certificates certified by third-party authorities, no CA certificate required
    • For self-signed certificates, a server-side CA certificate is required or, for two-way certification, a client-side certificate and private key are required
  • Turn on strict mode
  • Connect

mqttx_tls

# Delete the certificate

Deleting the certificate will disconnect the client from 8883 and 8084, please ensure that this does not affect your business.

  1. Login EMQ X Cloud Console (opens new window).
  2. To access the deployment details, click on the delete button for the certificate in the TLS/SSL Configuration section.
  3. Click on "OK" in the dialog to complete the deletion.

# Generate self-signed certificates

Make sure you have installed OpenSSL (opens new window) first.

# Generation of CA certificate

subj adjusted to actual use.

openssl req \
    -new \
    -newkey rsa:2048 \
    -days 3650 \
    -nodes \
    -x509 \
    -subj "/C=CN/O=EMQ Technologies Co., Ltd/CN=EMQ CA" \
    -keyout root-ca.key \
    -out root-ca.crt

# Generation of server-side certificate

  1. Generation of server-side secret key
openssl genrsa -out server.key 2048
  1. Create openssl.cnf file

Replace the DNS.1 address with the current deployment address

cat << EOF > ./openssl.cnf
[policy_match]
countryName             = match
stateOrProvinceName     = optional
organizationName        = optional
organizationalUnitName  = optional
commonName              = supplied
emailAddress            = optional

[req]
default_bits       = 2048
distinguished_name = req_distinguished_name
req_extensions     = req_ext
x509_extensions    = v3_req
prompt             = no

[req_distinguished_name]
commonName          = Server

[req_ext]
subjectAltName = @alt_names

[v3_req]
subjectAltName = @alt_names

[alt_names]
# EMQ X Cloud deployment connections address
DNS.1 = tls.emqx.io
EOF
  1. Generate the server-side certificate request file server.csr
openssl req -new -key server.key -config openssl.cnf -out server.csr
  1. Sign the server-side certificate with a CA certificate
openssl x509 -req \
    -days 3650 \
    -in server.csr \
    -CA root-ca.crt \
    -CAkey root-ca.key \
    -CAcreateserial -out server.crt \
    -extensions v3_req -extfile openssl.cnf
  1. View server-side certificate information
openssl x509 -noout -text -in server.crt
  1. Verify the certificate
openssl verify -CAfile root-ca.crt server.crt

# Generation of client-side certificate

  1. Generation of client-side secret key
openssl genrsa -out client.key 2048
  1. Generate the client-side certificate request file server.csr
openssl req -new -key client.key -out client.csr -subj "/CN=Client"
  1. Sign the server-side certificate with a CA certificate
openssl x509 -req -days 3650 -in client.csr -CA root-ca.crt -CAkey root-ca.key -CAcreateserial -out client.crt
  1. View client-side certificate information
openssl x509 -noout -text -in client.crt
  1. Verify the certificate
openssl verify -CAfile root-ca.crt client.crt

# FAQ

  1. The certificate contains several certificates

    Purchased certificates contain intermediate certificates, which open the certificate in text form, and multiple certificates in the order of User Certificate - Intermediate Certificate - Root Certificate. Generally, a certificate contains a user certificate and several intermediate certificates, you need to separate the user certificate from the intermediate certificate and fill in the certificate chain with the intermediate certificate.

    -----BEGIN CERTIFICATE-----

User Certificate

-----END CERTIFICATE-----

-----BEGIN CERTIFICATE-----

Intermediate Certificate

-----END CERTIFICATE-----

-----BEGIN CERTIFICATE-----

Root Certificate

-----END CERTIFICATE-----

  2. Lack of certificate chain

    Certificate chain completion: https://myssl.com/chain_download.html

← VPC Peering connection settings →

Edit this page
What’s on this page