X.509 Certificate Authentication

X.509 is a standard public key certificate format widely used in secure internet communication. EMQX supports TLS/SSL connections and client/server two-way authentication using X.509 certificates, offering a higher level of security.

How It Works

EMQX allows clients to establish TLS/SSL connections using X.509 certificates and supports binding certificate information with the client for X.509 certificate authentication. Its usage and workflow are as follows:

1. Issue server certificates, enable TLS/SSL for EMQX, and set it for two-way authentication.
2. Issue client certificates, burn the certificate and private key files into the device, and use them for TLS/SSL connection.
3. The client sends the certificate to the server during the TLS handshake to prove its identity legitimacy.
4. Upon receiving the client's certificate, EMQX validates the certificate to confirm the client's identity.
5. If the validation passes, the server completes the TLS handshake and establishes a secure connection.

After the connection is successful, EMQX supports mapping certificate information to client properties to achieve binding between the certificate and the client. Additionally, it can be combined with other application-layer authentication methods, such as JWT authentication and password-based authentication, to implement a combination of multiple authentication methods.

Features and Advantages

• Security: X.509 offers a secure and reliable authentication mechanism, using digital certificates and public key encryption to ensure confidentiality, integrity, and authentication of communication. It prevents unauthorized devices from accessing the network or performing malicious operations.
• Interoperability: X.509 is a universal standard widely supported and adopted. Many IoT devices support X.509 certificates, making authentication and secure communication between devices simpler and more reliable.
• Scalability: X.509 supports large-scale IoT deployments. It offers flexible certificate chains and management mechanisms, adapting to complex IoT environments and supporting authentication for a large number of devices and entities.
• Trusted third-party verification: X.509 certificates are often issued by trusted Certificate Authorities (CAs) that undergo strict security reviews and validations. Devices can use certificates issued by trusted CAs to ensure their identity and certificate legitimacy.
• Support for robust encryption algorithms: X.509 supports a wide range of encryption algorithms and key lengths, including common symmetric and asymmetric encryption algorithms. This allows IoT devices to use strong cryptographic algorithms to protect communication security.
• Flexible certificate configuration and management: X.509 features flexible certificate configuration and management options. Devices can select appropriate certificate attributes and extension fields according to their needs, meeting specific IoT application requirements. Moreover, certificate revocation and updates can be effectively managed through certificate management mechanisms.

These features make X.509 an ideal choice for IoT security. EMQX provides complete support for X.509 certificate authentication, helping you easily achieve secure access and communication for IoT devices.

Enable X.509 Certificate Authentication

X.509 certificate authentication is essentially TLS/SSL two-way authentication. You can refer to Enable SSL/TLS with Two-Way Authentication for configuration.

TIP

X.509 certificate authentication is executed before password authentication and JWT authentication.

Certificate Information Mapping

EMQX supports mapping X.509 certificate information as a username or client ID to achieve binding between the certificate and the client. You can set this through the Dashboard or configuration files.

You can use fields from the peer certificate like CN, DN, or the entire certificate content as a username. The interpretations of the current supported certificate information are:

• cn: CN field of the certificate
• dn: DN information of the certificate, formatted as CN=xxx,OU=xxx,O=xxx,L=xxx,ST=xxx,C=xxx
• crt: DER format content of the certificate
• pem: DER certificate converted to PEM format content
• md5: MD5 value of the DER or PEM certificate content

Configure via Dashboard

1. Open the Dashboard, go to Management -> MQTT Settings page, and select the General tab.
2. In the MQTT configuration, find and modify the following items:
   • Use Peer Certificate as Username: Map X.509 certificate information as a username.
   • Use Peer Certificate as Client ID: Map X.509 certificate information as a client ID.
3. Click the Save Changes button to complete the configuration. New clients connecting will be mapped according to the set method.

Configure via Configuration File

1. Open the configuration file emqx.conf, which may be located in ./etc or /etc/emqx/etc directory, depending on your installation.
2. By default, MQTT configuration is not in emqx.conf. Add the following configuration to override the default values:

mqtt {
# Use certificate information as a client ID
peer_cert_as_clientid = "disabled" # "disabled" | "cn" | "dn" | "crt" | "pem" | "md5"
# Use certificate information as a username
peer_cert_as_username = "cn" # "disabled" | "cn" | "dn" | "crt" | "pem" | "md5"
}