Why does OpenConnect reject the gateway after a certificate swap?

Gateways replace certificates, and a client that connected yesterday begins stopping at the first TLS exchange. The message names a verification reason rather than a network fault, and the machine itself has not changed, which is the useful clue. What broke is the relationship between the certificate now presented and the roots the client is willing to consider. Repairing it is a trust decision, so make that decision before you type an option.

Read the failure before you change any trust setting

A missing-signer style error means the chain ends at something the client does not accept. That could be a renewed certificate from an internal authority, a replacement from a public one, or a device in the middle presenting its own certificate. The wording alone cannot distinguish those cases, so look at the issuer before deciding.

Run the connection once in the foreground and let it fail, because the interactive output carries the server name, the issuer chain and the fingerprint the client computed. Compare that issuer with an authority your organisation actually operates. If the fingerprint changed while the issuer did not, treat it as suspicious until a renewal is confirmed through a channel you already trust. Guessing at this point is how a person ends up pinning an interceptor's key.

Record the client version in the same note. A good share of failures that look like trust problems come from an older client meeting a newer gateway exchange.

Choose between trusting the issuer and pinning one key

Both options make the connection succeed. They break in opposite ways later, so the choice belongs to the failure you can tolerate.

Reach for the CA file when the certificate comes from an authority you can verify independently, because renewals then keep working without touching client arguments. Pair it with the switch that disables system roots, otherwise a public authority can satisfy the check on your behalf. Pin instead when the gateway has no CA you can obtain or when the narrowest possible exception is the goal. Neither path is more secure in the abstract: the CA scales across renewals, the pin is easier to review.

Whichever you pick, the trusted value has to arrive through a channel that was trusted before the change happened. An administrator, a console session on the gateway, or a copy taken ahead of time all qualify. Copying whatever fingerprint the prompt displays is convenient and is also precisely what an interceptor is hoping for.

Put the value in the command you actually launch

The pin travels in a server-certificate option, and its prefix decides the encoding: hexadecimal public-key digests under sha1 or sha256, and the base64 key pin under pin-sha256. Supplying it also disables system trust for that run, so the pinned key becomes the whole decision.

sudo openconnect --protocol=gp vpn.example.com --user alice \
  --servercert pin-sha256:AbCdEf...   # single key pin
sudo openconnect vpn.example.com --cafile /etc/ssl/internal-ca.pem --no-system-trust

The client matches a truncated digest, accepting as few as four characters after the prefix, which is a trap rather than a convenience. A shortened value passes locally and still does not identify the gateway you intended. Copy the full string the client printed on the first attempt instead of retyping it from a message. Then move the finished option into the wrapper script, unit file or profile that launches the connection, so the trust decision is reviewable and later edits are deliberate.

Desktop launchers and the NetworkManager plugin store their own copy of the connection arguments. A script edited on disk does not reach a profile imported earlier, so the stored value keeps winning.

Handle a rollover without locking yourself out

The option may be given more than once, so a planned change can accept the outgoing and incoming keys together. Add the new pin before the gateway switches, keep both listed while sessions migrate, and drop the retired one once the old key is gone. That window needs an owner, since a forgotten dual pin leaves a key trusted with nobody watching it. A rebuild that produces a fresh key pair breaks a pure pin, and recovery is the same procedure in the other direction.

Write the change date beside the pin. A pin with no review date is a future outage carrying a confusing error message.

Rule out the client version before editing trust

An dated client can fail while parsing an authentication reply the gateway has since altered, and the surface message still talks about the connection rather than the parser. Compare the installed version with what the gateway documents, and test a current package in a throwaway profile before changing any trust setting.

openconnect --version

After the repair, verify two things rather than one: the portal loads through the tunnel, and an ordinary internal address answers. A completed handshake proves only that the trust decision was accepted.