Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 10 additions & 4 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -47,6 +47,8 @@ source/ C++ application source
timeutil.cpp/h Server clock parsing (RFC 3339 and RFC 7231)
fsutil.cpp/h mkdirs, temp-file + atomic-replace helpers
hash.cpp/h MD5 and the Dropbox content hash
certtrust.cpp/h PinnedKey= / CACert= parsing (TlsTrust), IP names in a
certificate; Curl does the checking
tlsclose.cpp close_notify for libcurl's TLS connections (link-time wrap)
sockopt.cpp SO_ERROR in newlib's numbering, for libsmb2 (link-time wrap)
cancel.cpp/h START as a running transfer sees it (transferCancelled())
Expand Down Expand Up @@ -107,12 +109,12 @@ The Makefile auto-discovers all `.cpp` files under `source/`. Adding a new `.cpp
```bash
arm-none-eabi-g++ -fsyntax-only -std=gnu++11 -Wall \
-march=armv6k -mtune=mpcore -mfloat-abi=hard -mtp=soft -D__3DS__ -DARM11 \
-DINI_MAX_LINE=2048 \
-DINI_MAX_LINE=16384 -DINI_USE_STACK=0 -DINI_INITIAL_ALLOC=16384 \
-I$DEVKITPRO/libctru/include -I$DEVKITPRO/portlibs/3ds/include \
-I$DEVKITPRO/portlibs/armv6k/include source/main.cpp
```

`source/libs/inih/ini.c` and `ini.h` are byte-identical to [benhoyt/inih](https://github.com/benhoyt/inih) `577ae2d` (2026-01-30) and must stay that way, so the next resync is a two-file copy with no patch to re-apply. Compile-time configuration of them therefore belongs in `BUILD_FLAGS` in the Makefile: `INI_MAX_LINE=2048` is set there because upstream's 200 truncates a pasted `Token=`, which is an OAuth access token and can exceed a kilobyte. When bumping, re-check that `ini_parse()` and `ini_parse_string()` keep their signatures and that `INI_HANDLER_LINENO` still defaults to 0 — `INIReader::ValueHandler` is a 4-argument handler.
`source/libs/inih/ini.c` and `ini.h` are byte-identical to [benhoyt/inih](https://github.com/benhoyt/inih) `577ae2d` (2026-01-30) and must stay that way, so the next resync is a two-file copy with no patch to re-apply. Compile-time configuration of them therefore belongs in `BUILD_FLAGS` in the Makefile: `INI_MAX_LINE=16384` is set there because upstream's 200 truncates a pasted `Token=`, which is an OAuth access token and can exceed a kilobyte, and a `CACert=` line is a whole CA certificate in base64. The buffer is on the heap (`INI_USE_STACK=0`, allocated at full size by `INI_INITIAL_ALLOC`) rather than 16 KB of the main thread's stack; `INI_ALLOW_REALLOC` is avoided because its code does not compile as C++, which the host tests build `ini.c` as. `tests/Makefile` repeats the flags. When bumping, re-check that `ini_parse()` and `ini_parse_string()` keep their signatures and that `INI_HANDLER_LINENO` still defaults to 0 — `INIReader::ValueHandler` is a 4-argument handler.

`source/libs/inih/INIReader/` is *not* upstream and cannot be resynced blindly: `GetValues()` is a local addition that `getConfiguredSyncPaths()` depends on, and upstream's `INIReader` exposes no equivalent; `Set()` (sealed credentials) and `GetSpelling()` (a key's name as the file wrote it, see "Path names keep their spelling") are local too.

Expand All @@ -133,9 +135,10 @@ Keep the format `major.minor.micro`: the Makefile splits it on the dots and `mak
- **C++11**, no exceptions, no RTTI.
- Logic worth testing goes in a unit that does not include `<3ds.h>`, libcurl or libsmb2, and gets a test. The providers should stay thin: talk to the network, hand the response to a parser.
- All HTTP goes through the `Curl` wrapper (`source/utils/curl.h`). Never call libcurl directly.
- **Certificates are checked on every TLS connection.** `Curl::_applyDefaults()` sets `VERIFYPEER`/`VERIFYHOST` and hands mbedTLS the roots from `romfs/cacert.pem` through `CURLOPT_SSL_CTX_FUNCTION` (`_sslContext()`), parsed once per run (`caChain()`): libcurl would otherwise reparse the file per connection, and FTPS opens one per transfer. It also clears `CAINFO`/`CAPATH`, because devkitPro's libcurl defaults to `sdmc:/config/ssl/cacert.pem`, which most cards lack. The callback runs after libcurl's own `mbedtls_ssl_conf_ca_chain()` (checked with `objdump` on libcurl 8.4: the indirect call follows it in `mbed_connect_common`), so its chain wins; recheck after a libcurl bump. Only WebDAV and FTP may turn checking off (`VerifyTLS=false` → `Curl::setVerifyTls(false)`, parsed in `remoteconfig.cpp`). A certificate failure (curl 60, or 77 for a missing bundle) is fatal for that remote, never retried, and explained by `Curl::printCertificateHelp()` — including the 3DS date, since an unset clock is the likeliest cause. Update the bundle with curl's published file and checksum (`https://curl.se/ca/cacert.pem` and `.sha256`).
- **Certificates are checked on every TLS connection.** `Curl::_applyDefaults()` sets `VERIFYPEER`/`VERIFYHOST` and hands mbedTLS the roots from `romfs/cacert.pem` through `CURLOPT_SSL_CTX_FUNCTION` (`_sslContext()`), parsed once per run (`caChain()`): libcurl would otherwise reparse the file per connection, and FTPS opens one per transfer. It also clears `CAINFO`/`CAPATH`, because devkitPro's libcurl defaults to `sdmc:/config/ssl/cacert.pem`, which most cards lack. The callback runs after libcurl's own `mbedtls_ssl_conf_ca_chain()` (checked with `objdump` on libcurl 8.4: the indirect call follows it in `mbed_connect_common`), so its chain wins; recheck after a libcurl bump. Only WebDAV and FTP may change what is trusted, through a `TlsTrust` (`utils/certtrust.h`, parsed in `remoteconfig.cpp`, handed to `Curl::setTrust()`) — see the next point. A certificate failure (curl 60, or 77 for a missing bundle or an unreadable `CACert=`) is fatal for that remote, never retried, and explained by `Curl::printCertificateHelp()` — including the 3DS date, since an unset clock is the likeliest cause, and for WebDAV/FTP the `PinnedKey=` line for the key the server presented. Update the bundle with curl's published file and checksum (`https://curl.se/ca/cacert.pem` and `.sha256`).
- **Remote names never leave the sync folder.** `syncEntry()` drops every listed relPath that `isSafeRelativePath()` (`utils/pathutil`) refuses — a `..`, `.` or empty segment, a backslash, a control character — before anything is decided, says so once per remote and entry, and adds a `problems` entry. Providers need not check this themselves, but must not "fix" such a name into something that passes.
- **A transfer that stops receiving gives up after 60 s** (`CURLOPT_LOW_SPEED_LIMIT`/`_TIME` in `Curl::_applyDefaults()`, `STALL_SECONDS`). Wi-Fi dropping mid-file sends no error — the connection just goes quiet — and libcurl's only other limit is the 50 s connect timeout, so a ROM download once waited until START. The timeout is `CURLE_OPERATION_TIMEDOUT`, which every provider retries; a retry must discard what a stalled download already wrote (`rewindDownloadFile()` — FTP did not, and appended to the half file) and FTP opens a fresh connection for it.
- **A WebDAV or FTP remote can trust its own server** (#72). `PinnedKey=` is the SHA-256 of the server's public key (SubjectPublicKeyInfo) or of its certificate, comma-separated for several; `CACert=` is base64 DER on one line (the configurator converts the `.pem`). `parsePinnedKeys()`/`parseCaCerts()` in `utils/certtrust.cpp` are host-tested and mirrored by `pinnedKeyProblem()`/`caCertProblem()` in `inifile.js` — change both together. One that does not parse leaves the remote out (a startup issue), never falls back to not checking; either overrides `VerifyTLS=false`; with both, the pin decides and `CACert=` is dropped with an issue. Dropbox, Drive and SMB ignore both with an issue. On the 3DS `_sslContext()` gives mbedTLS `CACert=`'s chain *instead of* the bundle (parsed once per handle, `ownCaChain()`) and always installs `_verifyCertificate()` with `mbedtls_ssl_conf_verify()`: it records the server's key hash (for the help text) and, with a pin, holds back the chain's flags until depth 0 (always called last) and clears all of them on a match — self-signed, unknown issuer, wrong name, expiry — or adds `MBEDTLS_X509_BADCERT_OTHER` on a mismatch. That relies on libcurl 8.4 setting `MBEDTLS_SSL_VERIFY_OPTIONAL`, reading `mbedtls_ssl_get_verify_result()` afterwards, and setting no verify callback of its own (checked with `objdump`/`nm`); recheck after a libcurl bump. `CURLOPT_PINNEDPUBLICKEY` was not used because it cannot accept a certificate hash nor say which key it saw. The long `CACert=` line is why `INI_MAX_LINE` is 16384, on the heap (`INI_USE_STACK=0`); see "Build".
- `Curl::perform()` returns 0 on network success. **HTTP status is not checked by `perform()`** — callers must call `getStatusCode()`. `CURLOPT_FAILONERROR` is intentionally disabled so error response bodies are captured.
- Every provider owns a `_performWithRetry()` that maps transport errors to *transient* (retry with back-off), *fatal* (`_fatalError`, stop the run) or *per-file* (log and skip). Never call `_curl.perform()` directly from a provider method — the retry helper is also where the server `Date` header is captured.
- libcurl options are sticky on a handle. Providers that issue more than one shape of request call `Curl::reset()` first (via their own `_prepare()`); otherwise `NOBODY`, `UPLOAD`, `WILDCARDMATCH` or a custom method leaks into the next call.
Expand Down Expand Up @@ -330,6 +333,9 @@ Mode=passive ; passive | active
Url=https://host/remote.php/dav/files/user/
User=...
Password=...
PinnedKey=... ; WebDAV and FTP: SHA-256 of the server's key (hex or sha256//base64)
CACert=... ; WebDAV and FTP: own CA certificate(s), base64 DER on one line
VerifyTLS=false ; WebDAV and FTP: don't check the certificate at all

[SMB:Backup] ; a second remote of a type: [<Type>:<Label>], same keys
Server=...
Expand Down Expand Up @@ -372,7 +378,7 @@ CompareConflicts=true ; false: never download to check, always ask
- Every typed value goes through `iniValueProblem()`: inih ends a value at a `;` that follows whitespace and trims both ends, so such a value is refused with a reason rather than silently cut on the 3DS. Optional keys are written only when filled — an empty `User=` overrides the FTP default of `anonymous`, which the app applies only when the key is missing. Pasted forms (`\\nas\share\dir`, `ftps://user@host:port/dir`, a URL without a scheme) are split into the fields on blur.
- A step's title reopens it only when it lies before the open step (`markReachableSteps()` in `index.js`, kept current by a `MutationObserver` on the steps' `active` class). MStepper's own `stepTitleNavigation` stays off: it would also jump forward, past the validation in Continue and Confirm, and step 3's preview is only built by Confirm.
- **Conflicts** in step 2 (`#conflicts-section`, shown only when an SMB, FTP or WebDAV remote is configured, since Drive and Dropbox compare by hash): `#compare-conflicts` is `CompareConflicts=` and `#compare-up-to` is `CompareUpTo=` in KB, blank for the 3DS's default of 4096, `0` for no limit, refused by Confirm unless a whole number. Both live in `config.sync` (`{ compare, compareUpTo, other }`, `other` being the `[Sync]` lines the page has no field for); `toIni()` writes `[Sync]` only when it says something, and `fromIni()` reads it back the way the 3DS does (an unknown `CompareConflicts=` is on, and reported).
- WebDAV and FTP have a "the server uses its own certificate" checkbox (`webdav-insecure`, `ftp-insecure`) that writes `VerifyTLS=false`; `inifile.js` maps the key back to it on import (`CHECKBOX_VALUES`), and keeps a value the box cannot show as it was.
- WebDAV and FTP have a **Server certificate** select (`webdav-cert`, `ftp-cert`: `public`, `key`, `ca`, `off`), and only the chosen mode's line is written (`certEntries()` in `index.js`): `PinnedKey=` from `<type>-pinned-key`, `CACert=` from the hidden `<type>-ca-cert`, which a `.pem`/`.crt`/`.der` file chosen in the tab fills through `IniFile.caCertFromFile()` (read with `FileReader`, never uploaded), or `VerifyTLS=false`. On import `certMode()` in `inifile.js` picks the mode as the 3DS would (pin, then CA, then `VerifyTLS=`, mapped through `MAPPED_VALUES`), keeps a `VerifyTLS=` value the select cannot show as it was, and reports contradicting or unreadable lines. The step 3 preview cuts a `CACert=` to its start; the download keeps it whole.
- **Anonymous FTP needs a base directory.** With User blank, `anonymous` or `ftp`, an empty (or `/`) Path is refused: stock anonymous servers only accept uploads in one folder such as `pub`, and without `Path=` the first sync on the 3DS fails when it cannot create its folder there. A named user may leave it blank.
- A field's error replaces its hint (`index.css`, `.remote-field.invalid ~ .helper-text`); Materialize would otherwise draw the error over the visible white hint.
- Step 3 previews the file with `IniFile.toIni(config, true)`, which masks passwords, secrets and tokens; the download uses `toIni(config, false)`.
Expand Down
7 changes: 6 additions & 1 deletion Makefile
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,12 @@ EXTRA_OUTPUT_FILES :=
# and Google's run past a kilobyte, and an over-long line is cut at the buffer
# with its tail parsed as the next line -- the credential reaches the handler
# truncated, and the only complaint is a syntax error blamed on the fragment.
BUILD_FLAGS := -Wno-format-truncation -DINI_MAX_LINE=2048
# A CACert= line is a CA certificate in base64, about 2.6 KB for an RSA-4096
# one and more for two, so the buffer holds 16 KB, and is on the heap rather
# than taking that much of the main thread's stack. Not INI_ALLOW_REALLOC:
# its code does not compile as C++, which the host tests build ini.c as.
BUILD_FLAGS := -Wno-format-truncation -DINI_MAX_LINE=16384 -DINI_USE_STACK=0 \
-DINI_INITIAL_ALLOC=16384

# Link-time hooks into libcurl's mbedTLS teardown so TLS connections end with
# a close_notify, which libcurl 8.4 never sends and vsftpd requires of a TLS
Expand Down
45 changes: 39 additions & 6 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -193,7 +193,9 @@ Password=<password>
Path= ; optional base directory
TLS=try ; none | try | require | implicit
Mode=passive ; passive | active
VerifyTLS= ; optional, false for a self-signed certificate
PinnedKey= ; optional, see "Server certificates"
CACert= ; optional, see "Server certificates"
VerifyTLS= ; optional, false: don't check the certificate
```

`TLS=try` (the default) encrypts the session when the server offers `AUTH TLS`
Expand Down Expand Up @@ -228,6 +230,9 @@ SFTP is **not** supported: the 3DS build of libcurl has no libssh2.
Url=https://nas.example/remote.php/dav/files/username/
User=<username>
Password=<app password>
PinnedKey= ; optional, see "Server certificates"
CACert= ; optional, see "Server certificates"
VerifyTLS= ; optional, false: don't check the certificate
```

Works with Nextcloud/ownCloud and any NAS with WebDAV enabled. Use an app
Expand All @@ -243,10 +248,37 @@ check stops that remote with an explanation instead of connecting anyway.
- **The 3DS clock** matters: a date that was never set makes every certificate
look not yet valid. The message shows the date the 3DS has.
- **A server with its own certificate** — most NAS out of the box — fails the
check. Add `VerifyTLS=false` to that `[WebDAV]` or `[FTP]` section (the
configurator has a checkbox for it). The connection is still encrypted, but
no longer protected against someone on the network posing as the server.
Dropbox and Google Drive always check.
check. Tell 3DSync what to trust instead, in that `[WebDAV]` or `[FTP]`
section; the configurator's *Server certificate* choice writes each of these.
Dropbox and Google Drive always check against the public roots.

- `PinnedKey=` — **a self-signed certificate**, or a server reached by its IP
address. The SHA-256 of the server's public key: exactly that key is
accepted, whoever signed the certificate and whatever name it carries. To
find it, sync once: the 3DS shows the key the server presented, in two
lines to write after `PinnedKey=` as one, and a saved log keeps it. Chrome
shows it too (the padlock → certificate → *SHA-256 fingerprint, Public
key*), and so does
`openssl s_client -connect nas:443 </dev/null | openssl x509 -pubkey -noout | openssl pkey -pubin -outform der | openssl dgst -sha256`.
Hex with or without colons and curl's `sha256//<base64>` are all read; put
a comma between two keys to accept both while a server changes its key.
The pin stays valid as long as the server keeps its key, which many
renewals do. A *certificate's* SHA-256 fingerprint (what Firefox shows)
works too, but changes with every renewal.
- `CACert=` — **a home or router CA** that signs your servers' certificates.
The CA's certificate, as base64 on one line (several separated by commas);
the configurator writes it from the `.pem` file, so nothing else has to be
copied to the SD card. That remote then trusts only these CAs, not the
public roots, and the server's certificate must still name the host
3DSync connects to. Survives every renewal of the server's certificate.
- `VerifyTLS=false` — don't check at all. The connection is still encrypted,
but no longer protected against someone on the network posing as the
server, who would then see the password and every file.

A `PinnedKey=` or `CACert=` that cannot be read is reported at startup, and
the remote is left out until it is fixed; it never falls back to not
checking. With both, `PinnedKey=` alone decides. Either one overrides
`VerifyTLS=false`.

### Several remotes

Expand Down Expand Up @@ -303,7 +335,8 @@ that remote as new, so its first sync compares every file again.
On startup 3DSync checks the file, and if something is wrong it lists every
problem, with what to do, before the main menu: a remote missing a setting
(`[SMB]` without `Share=`), a remote with no login, a misspelled remote type, a
`Role=`, `Only=`, `TLS=` or `VerifyTLS=` that does not make sense, a
`Role=`, `Only=`, `TLS=`, `VerifyTLS=`, `PinnedKey=` or `CACert=` that does
not make sense, a
`[Filter]` line naming no configured path, a password sealed on another
console, a credential that could not be sealed (written on more than one line,
or too long), or a line the file cannot be read at. Press **A** to continue anyway
Expand Down
Loading
Loading