TLS and Authentication

Reference·Audience: API consumer·Use: look up the TLS fields, verification values, and certificate rules for a reader endpoint

TLS protects the connection between the reader and your broker. The reader is the TLS client and the broker is the TLS server: certificates and keys that the reader uses are installed on the reader, and the broker's own TLS configuration stays on the broker. For the task of enabling TLS, see Certificate Management.

Turning On TLS for an Endpoint

TLS is a property of each endpoint, not of the reader. Set these fields in the endpoint's configuration:

Field	Value for TLS
protocol	MQTT_TLS. The only other value, MQTT, is plaintext.
port	The broker's TLS port, conventionally 8883. The reader does not check that port matches protocol.
verificationType	How far the reader verifies the broker's certificate. See Verification Levels.
securityParams	The names of the installed certificates and key that this connection uses. See The securityParams Block.

A config_endpoint change to an active endpoint can be refused with code 35. See Changing an Endpoint.

TLS Versions and Cipher Suites

The TLS versions and cipher suites that the reader supports are not specified in the available sources. No endpoint field selects them, and no command or event reports them. The mqttVersion field of mqttConnEVT reports the MQTT version, not the TLS version.

Verification Levels

verificationType sets how much of the broker's identity the reader checks during the TLS handshake. This documentation describes two values:

Value	What the reader verifies
VERIFY_HOST_AND_PEER	The broker's certificate chain, and that the certificate matches the host being contacted
VERIFY_NONE	Nothing. An MQTT_TLS endpoint refuses this value with code 37.

Don't disable verification in production

The contract states that VERIFY_NONE must not be used in production. On an MQTT_TLS endpoint, config_endpoint refuses it with code 37 (Invalid verification type for MQTT TLS); use VERIFY_HOST_AND_PEER.

Send one of these values exactly as shown. What the reader does with any other value is not specified in the available sources. Read-backs from get_endpoint_config report verificationType in the same form.

install_certificate carries its own verificationType, which the contract describes as the verification mode for validating remote endpoints. How it relates to the endpoint's verificationType is not specified in the available sources.

The securityParams Block

securityParams names certificate material that is already installed on the reader. It never carries certificate content. Install the material first, then name it here.

Field	Required	What it names
format	Yes	The certificate format. Only PEM is currently supported.
caCertificateFile	No	The installed CA certificate that the reader uses to verify the broker
clientCert	No	The installed client certificate that the reader presents to the broker for mutual TLS
clientKey	No	The installed private key that matches clientCert
algorithm	No	Reported in read-backs only, as RSA256 or RSA512. The contract's read-back examples show an empty string, which is not one of those values.

• Verifying the broker needs caCertificateFile when verificationType requires chain verification.
• Mutual TLS also needs clientCert and clientKey. See Security Schemes.
• Read-backs: in the contract's examples, an endpoint that uses no certificate material reports empty strings for the three names.

What the reader does when a named certificate is not installed is not specified in the available sources.

Certificate Material

Install certificates and keys with install_certificate. These rules apply:

• Format: PEM only.
• Private keys: PKCS#1 encoding.
• Size: at most 4 KB of certificate content.
• Category: the contract's mutual-TLS scheme uses a certificate installed with type: "mqtt", the category for the MQTT broker connection.
• Completion: install_certificate replies with code 1 when it accepts the request, and reports the outcome later in an alerts event. See Asynchronous Commands.

List installed material with get_installed_certificates, and remove it with delete_certificate.

Clock Dependency

Certificate validity depends on the reader's clock. The reader has no battery-backed real-time clock: after a cold start or a factory reset, its system time starts from a default value until it synchronizes with network time. Until then, time-sensitive operations such as certificate validation can use the default time.

The MQTT API has no command that changes the network time configuration. Set the NTP server, or the reader's time if NTP is unreachable, with 123RFID Desktop. Check deviceStatus.systemTime with get_status.

Related: 📕 Certificate Management · 📕 Broker Connection · 📕 Authentication and Tenancy · 📕 install_certificate · 📕 config_endpoint

Authentication and Tenancy

The reader presents credentials to your broker when it opens an endpoint's session. Your broker decides what each authenticated client may publish and subscribe to. This section covers the reader's side of both.

Security Schemes

The contract declares two security schemes for the broker connection:

Scheme	How the reader authenticates	Configured with
User name and password	The reader sends a user name and password in its MQTT CONNECT packet.	mqttParams.username and mqttParams.password on the endpoint
Client certificate (X.509)	The reader presents a client certificate during a mutual-TLS handshake.	A certificate installed with install_certificate at type: "mqtt", named in the endpoint's securityParams; see TLS and Authentication

Whether an endpoint can use both schemes at once is not specified in the available sources.

Use TLS with passwords

Without TLS, the user name and password travel in plaintext inside the CONNECT packet. The contract requires combining the user name and password scheme with TLS on any untrusted network.

How the Reader Handles Stored Credentials

• Passwords are masked in the contract's read-backs. The get_endpoint_config examples report mqttParams.password as xxxxxx. The password's maximum length is not specified in the available sources.
• Private keys are named, not sent. securityParams.clientKey names an installed key; it never carries key material.
• Configuration payloads can carry secrets. A config_endpoint request that sets mqttParams.password contains the password in plaintext JSON. Keep such payloads out of logs, tickets, and screenshots.

Your Application's Credentials

The MQTT API defines only the reader's credentials. How your applications authenticate to the broker, and who issues their credentials, is set by your broker and is not part of the MQTT API.

Tenant ID

tenantId is the first segment of every topic on an endpoint. It is a field of the endpoint's configuration, beside mqttParams, not inside it.

Property	Value
Length	At most 48 characters. A longer value makes config_endpoint return code 27.
Default	Empty in the reader's default endpoint configuration
Case	Not normalized; ZEBRA and zebra are different tenants
First set	By 123RFID Desktop, when it bootstraps the reader's first endpoint
Changed	Over MQTT, by sending config_endpoint with operation: update

The reader adds tenantId to the front of each topic itself. Don't include it in a configured topic value; see Topics and Channels. What topic the reader uses when tenantId is empty is not specified in the available sources.

Topic Authorization

Every topic on an endpoint begins with its tenant ID. The contract gives this as the reason for the prefix: a broker access-control rule can limit a credential to one tenant's topics. How you write such a rule depends on your broker and is not part of the MQTT API.

The directions that the MQTT API assigns to each topic suggest the least privilege each client needs. This table is a recommendation derived from those directions, not a rule the API enforces:

Client	Publish	Subscribe
Reader, for each endpoint	Its response, event, connection-state, and tag-data topics	Its command topic
Host application	The readers' command topics	The readers' response topics
Consuming application	Nothing	The event, connection-state, and tag-data topics it processes

To address every reader in a tenant, a subscriber can use the MQTT single-level wildcard + in the serial-number position, for example acme/MGMT/clients/resp/+.

Changing Credentials

The available sources do not document a sequence for changing the credentials of an endpoint while it is active. config_endpoint returns code 35 when you modify an active endpoint, and changing the endpoint that carries your own command session can sever it. See Changing an Endpoint.

Related: 📕 TLS and Authentication · 📕 Broker Connection · 📕 Topics and Channels · 📕 config_endpoint