OpenVPN verify-x509-name: subject vs name vs prefix

Read the match type first, then the text: a verify-x509-name directive can look correct and still accept a certificate you did not mean to trust. Two lines with identical expected text but different types are different requirements. Read the type first, then the text. Treat the directive as one more condition on the connection, not as the whole check.

What the option actually asserts

The directive names an identity the peer certificate must carry. When the comparison fails, OpenVPN aborts the handshake and no tunnel comes up. Everything else in the profile still applies: the certificate has to chain to a trusted CA, and the role check has to pass, so this is an extra condition rather than a substitute. A profile that satisfies the name expectation and fails the role check is still broken, and the log usually says so.

It is also unlike the hostname validation a browser performs. A browser matches names against subject alternative names under the rules of its TLS stack, while OpenVPN compares one certificate field using the type you selected. That is why pasting a browser-style hostname into the directive can produce a mismatch even when the certificate genuinely covers the service.

subject: the whole distinguished name, character for character

With subject, the default when no type is written, the expected value must reproduce the certificate's entire subject DN. Field order, separators, spacing and escaping all count, because the comparison runs on the string as encoded. Leave the type out and you have chosen the strictest of the three comparisons. There is no normalisation step to rescue a cosmetic difference. That is worth knowing before the first renewal, not after it.

That strictness is fragile across renewals. A CA that reorders attributes, inserts an extra field or changes how it escapes a value produces a new string for the same machine, and a directive that worked for years starts failing on the next issuance. Keeping the accepted DN in the change record turns the next renewal into a diff. Where the operator publishes a full DN and guarantees its shape, subject is a reasonable choice; elsewhere a narrower field is easier to keep true.

name: one field, usually the common name

The name type compares a single subject field. Unless the profile says otherwise that field is the common name, and the expected value is exactly that field rather than the DN around it.

The catch is that modern certificates do not always put the service name in the CN. Many carry it in a subject alternative name and leave the CN blank or generic, so a certificate a browser accepts can still fail this comparison. Inspect the certificate you were actually issued before writing the expectation, and confirm which field the profile selects. A blank CN compared against a name is a mismatch, not a configuration accident.

name-prefix: broad by design, so scope it

A name-prefix expectation matches the start of the selected field. That is convenient for a naming scheme and dangerous for anything shared.

With vpn.example as the expectation, both vpn.example.com and vpn.example.net would pass, provided the rest of the chain is trusted. The breadth is the feature, and it is also the part to justify in writing. A prefix is reasonable when the CA and the naming scheme are yours, and much weaker when a public CA issues into the same pattern. If the scheme needs flexibility, constrain it at the CA rather than widening the client check.

Choose the type from the identifier, then prove it

Work backwards from the identity the operator intends. If they publish a full DN and keep it stable, subject expresses that. If they name the service by common name, use name. If they own a naming scheme and accept its whole space, name-prefix says so explicitly.

Renewals are where the directive gets tested. Compare the approved identity against the new certificate rather than against the old file, because a new endpoint address does not imply a new certificate identity. Do not delete the directive just because a familiar address answers: reachability and the intended peer are different facts, and the address only proves that something replied. Capture the exact error and the public name details in a sanitised report, since a name mismatch can be shown without any private key material.

After a supported correction, reconnect with every intended check enabled and verify the resource you actually need. Success means the intended server was accepted, not that some certificate was coaxed through. The OpenVPN 2.6 manual documents the three types and their trust notes, and it is the reference to quote when a vendor interface disagrees with the profile.