Skip to content

feat(tls): trust a server's own key or CA for WebDAV and FTP - #84

Merged
michvllni merged 1 commit into
mainfrom
feat/trust-own-cert
Nov 9, 2026
Merged

michvllni merged 1 commit into
mainfrom
feat/trust-own-cert

Conversation

@michvllni

Copy link
Copy Markdown
Collaborator

Closes #72.

What

A WebDAV or FTP remote with a certificate of its own (a NAS, self-signed or from a home CA) could only connect with VerifyTLS=false, which leaves the password and every file open to anyone on the network posing as the server. Two new keys say what to trust instead:

  • PinnedKey=: the SHA-256 of the server's public key, or of its certificate. Exactly that key is accepted, however the certificate was signed and whatever name it carries, which covers a self-signed NAS reached by IP. It survives renewals that keep the key. Accepted forms: hex (colons or spaces allowed), and sha256//<base64>. Commas separate several keys, for a key change in progress.
  • CACert=: the home CA's certificate as base64 DER on one line. It replaces the public roots for that remote and survives every renewal of the server's certificate.

When a certificate is refused, the 3DS prints the PinnedKey= line for the key the server presented, in two lines under 50 columns that join with or without the colon. A saved log keeps it.

How

  • utils/certtrust (host-tested): parsing both keys into a TlsTrust, and the fingerprint lines. It also finds an IPv4 address in a certificate's subject alternative names: mbedTLS 2.28 only compares DNS names, so without this CACert= could never work for a server reached by IP.
  • Curl::setTrust(). _sslContext() hands mbedTLS the CACert= chain instead of the bundle, and always installs _verifyCertificate() through mbedtls_ssl_conf_verify(). The callback records the presented key's hash. With a pin, it holds back the chain's flags until the server's own certificate (depth 0, always last), then clears them all on a match, or adds BADCERT_OTHER on a mismatch. This relies on libcurl 8.4 setting MBEDTLS_SSL_VERIFY_OPTIONAL, reading the verify result itself and installing no callback of its own, which I checked with objdump/nm.
  • remoteconfig: a line that doesn't parse leaves the remote out as a startup issue, and never falls back to not checking. Either key overrides VerifyTLS=false, with an issue. With both keys, the pin decides and CACert= is dropped, with an issue. Dropbox, Drive and SMB ignore both keys, with an issue.
  • INI_MAX_LINE goes from 2048 to 16384, so a CA certificate fits on one line. The buffer is on the heap (INI_USE_STACK=0) rather than 16 KB of the main thread's stack. The inih sources are untouched.
  • Configurator: the WebDAV and FTP checkbox becomes a Server certificate select (public authorities / this server's key / my own CA / don't check). Only the chosen mode's line is written. The key field is checked by the same rules as on the 3DS (pinnedKeyProblem() in inifile.js). A CA file (.pem/.crt/.der) is read in the tab, never uploaded, and converted to the line (caCertFromFile()). Import maps the lines back and reports contradicting or broken ones. The preview shortens a CACert=; the download keeps it whole.
  • Docs: README "Server certificates", AGENTS.md, and a certificate test matrix in testinfra/README.md.

Testing

On a 2DS, against vsftpd and Apache WebDAV over HTTPS:

Case Result
No certificate line refused; the PinnedKey= line was shown
Correct PinnedKey= (self-signed) TLS passed, the login and listing worked
PinnedKey= with one digit changed refused
CACert= of a home CA, server reached by IP works, through the IP in the certificate
Server certificate renewed with a new key, same CA, INI unchanged still works
Broken CACert= refused as expected
  • make builds clean, make -C tests passes (336, with the new certtrust suite), and node --test tests/configurator/*.test.js tests/worker/*.test.mjs passes.
  • The configurator's certificate select, key validation and CA file picker were tried in headless Chromium.

Not covered:

  • FTPS uploads through a pin. The pin and login worked, but the test went through VS Code port forwarding, which never passes on the end of an FTP data connection, so uploads hung there.
  • The configurator on a real device.

Found along the way, filed separately: #82 (WebDAV: a 403 for Depth: infinity stops the remote as a failed login) and #83 (a remote whose connection is gone retries every file three times).

🤖 Generated with Claude Code

- PinnedKey= (SHA-256 of the server's public key or certificate) accepts
  exactly that key, self-signed or reached by IP, instead of
  VerifyTLS=false; it survives renewals that keep the key.  A refused
  certificate prints the PinnedKey= line for the key presented.
- CACert= (base64 DER on one line) replaces the public roots for that
  remote; the IP in a certificate is matched too, which mbedTLS 2.28
  never does.
- A line that does not parse leaves the remote out at startup rather than
  falling back to no check.  Dropbox, Drive and SMB ignore both.
- The configurator has a Server certificate choice per WebDAV/FTP remote,
  a key field checked like on the 3DS, and a CA file picker read in the
  tab; import maps the lines back.
- INI_MAX_LINE is 16384 on the heap, so a CA certificate fits on a line.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@michvllni
michvllni merged commit 53526a3 into main Nov 9, 2026
7 checks passed
@michvllni
michvllni deleted the feat/trust-own-cert branch November 9, 2026 21:37
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Trust a server's own certificate instead of turning verification off (WebDAV, FTPS)

1 participant