query, activate, unregister, and delete device certificates for apsaramq for mqtt - ApsaraMQ for MQTT

ApsaraMQ for MQTT authenticates client connections using X.509 device certificates issued by a Certificate Authority (CA). This guide covers how to generate RSA and ECC device certificates with OpenSSL, build certificate chains, and manage certificate lifecycle operations in the console.

How it works

A device certificate is a digital certificate that a CA root certificate issues to a client device. When a client connects to an ApsaraMQ for MQTT broker, the broker validates the device certificate against its registered CA certificate:

Validation succeeds: The client and broker establish an encrypted communication channel using the private key in the device certificate.
Validation fails: The broker denies the connection.

The first time a client connects with a valid device certificate, the broker automatically registers that certificate, provided the issuing CA certificate is already registered. To register a CA certificate, see Register a CA certificate.

Limitations

Device certificate management is available only on ApsaraMQ for MQTT Enterprise Platinum Edition instances.
Only device certificates registered with the ApsaraMQ for MQTT broker can be managed through the console.
Each device certificate must have a unique serial number.

Prerequisites

Before you begin, make sure that you have:

A CA certificate. To generate a self-signed CA certificate, see Self-signed CA certificates
OpenSSL v1.1.1i or later installed

Generate a device certificate

ApsaraMQ for MQTT supports both RSA and Elliptic Curve Cryptography (ECC) device certificates. Both types use the same configuration files but require different OpenSSL commands to generate keys and Certificate Signing Requests (CSRs).

Create configuration files

Create two configuration files before generating the certificate.

client.csr.cfg -- Defines the certificate subject fields:

[req]
default_bits = 2048
prompt = no
default_md = sha256
distinguished_name = dn

[dn]
C=CN
ST=ZJ
L=HZ
O=ALI
OU=MQTT
emailAddress=xxx@xxx
CN=client-test

Note

Modify the fields in [dn] to match your organization.

client.crt.cfg -- Defines certificate extensions:

authorityKeyIdentifier=keyid,issuer
basicConstraints=CA:FALSE
keyUsage = digitalSignature, nonRepudiation, keyEncipherment, dataEncipherment, keyCertSign

Generate an RSA device certificate

Generate the private key and CSR:

macOS / Linux:

openssl req -new -sha256 -nodes -out client.csr -newkey rsa:2048 -keyout client.key -config <(cat client.csr.cfg)

Windows:

openssl req -new -sha256 -nodes -out client.csr -newkey rsa:2048 -keyout client.key -config client.csr.cfg

Sign the device certificate with the CA certificate:

openssl x509 -req -in client.csr -CA CA.crt -CAkey CA.key -CAcreateserial -out client.crt -days 500 -sha256 -extfile client.crt.cfg

Generate an ECC device certificate

Generate the ECC private key:

openssl ecparam -out client.key -name prime256v1 -genkey

Generate the CSR:

macOS / Linux:

openssl req -new -sha256 -nodes -out client.csr -key client.key -config <(cat client.csr.cfg)

Windows:

openssl req -new -sha256 -nodes -out client.csr -key client.key -config client.csr.cfg

Sign the device certificate with the CA certificate:

openssl x509 -req -in client.csr -CA CA.crt -CAkey CA.key -CAcreateserial -out client.crt -days 500 -sha256 -extfile client.crt.cfg

Convert the private key to PKCS#8 format:

openssl pkcs8 -topk8 -nocrypt -in client.key -out client_pkcs8.key

Important

When connecting a client to the broker in your code, set the deviceKyPath parameter to the file path of the private key, not to the key content itself.

Build the certificate chain

A certificate chain is required to connect a client to the broker. The chain concatenates the device certificate and its issuing CA certificate, with the device certificate placed first.

Create an empty certificate chain file:
```
touch client_chain.crt
```
Append the device certificate:
```
cat client.crt >> client_chain.crt
```
Append the CA certificate after the device certificate:
```
cat CA.crt >> client_chain.crt
```

To verify the chain, run:

cat client_chain.crt

The output shows the device certificate block first, followed by the CA certificate block.

Note

In a certificate chain, child certificates always precede parent certificates. If your CA has intermediate certificates, append them in order from the most specific (device) to the most general (root CA).

Query device certificates

Log on to the ApsaraMQ for MQTT console. In the left-side navigation pane, click Instances.
In the top navigation bar, select the region of the target instance. Click the instance name to open the Instance Details page.
In the left-side navigation pane, choose Certificates > Device Certificate. The Device Certificate page lists all registered device certificates.

In the search box, enter a serial number to filter results:

Search by	Result
Device certificate serial number	Returns the specific certificate identified by that serial number
CA certificate serial number	Returns all device certificates issued by that CA and registered with the broker

Activate or deregister a device certificate

A device certificate has two states: Activated and Inactivated. By default, a certificate enters the Activated state when the broker registers it.

Current state	Action	Result
Activated	Click Deregister	The certificate enters the Inactivated state. Clients using this certificate can no longer connect.
Inactivated	Click Activate	The certificate returns to the Activated state and can be used for connections again.

In the device certificate list, find the target certificate and click Deregister or Activate in the Actions column.

Delete a device certificate

Deleting a device certificate removes its record from the broker's storage.

Note

If a client later connects with a deleted device certificate and the associated CA certificate is still valid, the broker automatically re-registers the device certificate.

In the device certificate list, find the target certificate and click Delete in the Actions column.
In the confirmation dialog box, click OK.