rqlite 10.2.0 restricts incoming TLS peers by common name

A certificate authority can issue valid certificates for several purposes. Trusting that authority does not necessarily mean every certificate it signs should connect to a database cluster. rqlite 10.2.0, released on 29 May 2026, adds an explicit common-name requirement for incoming mutual TLS peers. The new restriction can narrow admission within the set of certificates that already pass certificate verification.

I value rqlite's relatively small operational model. After a year with the project, my interest in this change is how clearly it separates a trust decision from a deployment-specific identity rule. A small database service still needs a precise answer about which certificate holders may connect to its different listeners.

The restriction applies after certificate verification

The tagged TLS implementation installs a peer-certificate callback when a required common name is configured. It examines verified certificate chains and compares the leaf certificate's subject common name with the configured string. Equality is exact. If no verified chain supplies the expected name, the callback returns an error.

This is an additional condition on an already verified certificate. The callback does not establish trust by finding matching text in an arbitrary unverified certificate. It operates on the verification result supplied by the TLS implementation. That ordering is essential because a string in a certificate is meaningful only within the trust policy that accepted the certificate.

The empty configuration value installs no common-name callback. Existing deployments therefore retain their previous behavior unless they select the new restriction. The feature expresses a deployment policy, rather than guessing which common name a cluster should use.

There is a practical difference between these two configurations. With mutual TLS alone, the relevant certificate trust rules determine which clients qualify. With the new setting, qualifying clients must also carry the expected subject name. The additional test can separate certificates issued by a shared authority for different service roles.

HTTP clients and cluster peers have separate controls

The flag definitions provide -http-verify-common-name for HTTP clients and -node-verify-common-name for incoming node connections. Each requires its corresponding mutual TLS option. This distinction lets an installation express different admission policies for the public API and the cluster transport.

For example, the following command illustrates the HTTP listener configuration. The paths refer to deployment-supplied certificate files, and rqlite-api-client is an example of the exact common name required on accepted client certificates.

rqlited \
  -http-cert /etc/rqlite/server.crt \
  -http-key /etc/rqlite/server.key \
  -http-ca-cert /etc/rqlite/client-ca.crt \
  -http-verify-client \
  -http-verify-common-name rqlite-api-client \
  /var/lib/rqlite

The configuration validation rejects a common-name requirement without the corresponding client-verification setting. A configuration that names an expected identity while omitting mutual TLS would otherwise express a security policy that its listener did not enforce.

This behavior also makes the requirement visible during deployment. Certificate issuance and command-line configuration must agree about the selected common name. Changing one side independently can prevent connections, which is the intended result when the configured identity requirement is no longer satisfied.

A deployment using a shared role name gives every accepted certificate holder that same transport identity condition. The setting does not distinguish individual clients that carry identical names. Applications needing finer distinctions still need a separate identity and permission design above this exact-match admission rule.

Incoming identity is distinct from outbound server identity

For node connections, the common-name setting applies during the handshake performed by the receiving node's multiplexer. Outbound connections continue to use -node-verify-server-name for the server identity check. The flag documentation states that distinction explicitly.

That matters in a mutually connected cluster because a node plays both roles. When accepting a connection it checks the incoming peer under its listener policy. When initiating a connection it verifies the server under its outbound policy. A correct name for one check does not automatically configure the other direction.

The integration changes pass the common-name settings into both the HTTP service and the node multiplexer. They also include the configured requirement in startup logging. The setting therefore reaches the components that terminate the relevant incoming TLS connections.

This design does not turn the subject common name into a universal replacement for server-name verification. Its purpose here is narrower, adding an exact admission rule for incoming clients. Treating both directions as one undifferentiated certificate-name check would obscure which component enforces which requirement.

The development sequence includes transport-level coverage

The release changelog credits hifi and links the common-name work across several pull requests. Development included refactoring the callback and integrating the final flag names. End-to-end cluster tests also exercise encrypted node communication.

The TLS integration tests exercise HTTP behavior with the common-name policy configured. Testing a certificate predicate alone would leave the listener wiring unexplained. A transport-level test addresses whether that predicate actually participates in the connection that a client makes.

The new requirement still leaves application permissions as a separate question. Passing the TLS handshake establishes that a connection satisfies the transport policy. The HTTP service's authorization rules decide which database actions the caller may perform. Combining the two decisions into a vague claim about trusted users would make both harder to reason about.

Console restore is another boundary in this release

Version 10.2.0 also adds restoring SQLite data through the console, as listed in the changelog. That makes a consequential administrative operation more accessible through the existing management interface. It is a separate feature from certificate admission, even though both affect how an operator interacts with the service.

The common-name control is useful because its behavior is explicit and limited. An incoming client must satisfy certificate verification and, when configured, the exact subject-name requirement. Outbound server verification retains its own setting. That division gives a deployment concrete identity rules for each connection direction without changing the relational API.