Document TAK authentication flows

2026-08-18 16:02:58 +00:00 · 2026-08-07 14:06:49 -03:00
parent d35ccd58e1
commit 6dee1987bb
1 changed files with 188 additions and 0 deletions
@@ -0,0 +1,188 @@
+# TAK authentication flows
+
+This document describes the authentication and transport flows implemented by the ArmaTAK Rust extension. It is development documentation, not end-user documentation.
+
+## Security model
+
+ArmaTAK currently exposes three TCP connection modes:
+
+| Mode | ArmaTAK entry point | Authentication | Transport protection | Intended use |
+| --- | --- | --- | --- | --- |
+| Plain TCP | `tcp_socket.start` | None | None | Local development or explicitly trusted isolated networks only |
+| Manual mTLS | `tcp_socket.start_mtls` | Client X.509 certificate | TLS with server certificate validation | Production-compatible secure connection |
+| Credential enrollment followed by mTLS | `tcp_socket.start_enroll_mtls` | HTTP Basic credentials during enrollment, then client X.509 certificate | Enrollment HTTPS currently skips certificate validation; the resulting TAK stream uses validated mTLS | Transitional/bootstrap flow; do not treat the enrollment phase as secure until server verification is enabled |
+
+The official TAK Server example enables a TLS input on port `8089`. Its plaintext TCP/streaming examples are anonymous and are shown on ports `8087` and `8088`. ArmaTAK must not infer security from a port number; the selected connection mode controls the client-side security properties.
+
+## Insecure flow: plain TCP
+
+The plain flow is deliberately simple:
+
+```text
+Arma/SQF
+   |
+   | tcp_socket.start("host:port")
+   v
+ConnectionConfig::Plain
+   |
+   v
+TCP connect
+   |
+   | unencrypted CoT bytes
+   v
+TAK Server plaintext/anonymous input
+```
+
+`ConnectionConfig::Plain` resolves the supplied address and opens a normal `TcpStream`. No TLS handshake occurs, there is no server identity verification, and no client identity is established by ArmaTAK.
+
+Consequences:
+
+- CoT payloads can be observed or modified by an on-path attacker.
+- ArmaTAK cannot prove that it connected to the intended TAK Server.
+- The server cannot authenticate ArmaTAK by certificate.
+- Plain TCP must never be the production default.
+
+The official TAK Server `CoreConfig.example.xml` keeps anonymous TCP inputs commented out and enables the TLS input instead. Use plain TCP only when a developer intentionally configures a corresponding non-TLS server input.
+
+## Secure flow: manual mTLS
+
+The manual mTLS flow uses pre-provisioned certificate material:
+
+```text
+Arma/SQF
+   |
+   | tcp_socket.start_mtls(
+   |   address,
+   |   server_name,
+   |   ca_cert_path,
+   |   client_cert_path,
+   |   client_key_path
+   | )
+   v
+ConnectionConfig::Mtls
+   |
+   +--> load trusted CA certificate(s)
+   +--> load client certificate chain
+   +--> load client private key
+   |
+   v
+rustls client configuration
+   |
+   +--> validate server certificate chain
+   +--> validate TLS server name
+   +--> present client certificate
+   v
+Authenticated mTLS TAK stream
+```
+
+The CA file is loaded into a dedicated `rustls::RootCertStore`; the client certificate and private key are used for client authentication. When `server_name` is empty, ArmaTAK derives a name from the target address. A non-empty `server_name` should be preferred when DNS and certificate names are known.
+
+This is the preferred production flow when certificate provisioning is handled outside ArmaTAK.
+
+## Enrollment flow: credentials to client certificate
+
+TAK enrollment converts a username/password bootstrap credential into a short- or medium-lived client certificate, then reconnects using mTLS.
+
+### Protocol contract
+
+ArmaTAK follows the contract visible in the official TAK Server and ATAK implementations:
+
+1. `GET https://HOST:ENROLL_PORT/Marti/api/tls/config`
+2. Authenticate the request with HTTP Basic credentials.
+3. Read `serverPort` and `enrollPath` from the TAK certificate configuration. If the fields are absent, ArmaTAK currently falls back to `8089` and `/Marti/api/tls/signClient/v2`.
+4. Generate a local RSA key pair and PKCS#10 CSR. The private key never needs to be sent to the server.
+5. `POST https://HOST:ENROLL_PORT{enrollPath}?clientUid=CLIENT_UID`
+6. Authenticate the signing request with HTTP Basic credentials, send the CSR as `application/pkcs10`, and request JSON.
+7. Parse `signedCert` and `ca0` from the enrollment response.
+8. Build an in-memory client identity from the returned certificate plus the locally generated private key.
+9. Connect to `HOST:serverPort` with mTLS and validate the TAK streaming server against the returned CA.
+
+The official TAK Server exposes `/tls/config`, `/tls/signClient`, and `/tls/signClient/v2`. The v2 endpoint can return JSON containing `signedCert` plus `ca0`, `ca1`, and additional CA-chain entries. The current ArmaTAK implementation consumes `signedCert` and `ca0`.
+
+### Current ArmaTAK enrollment security caveat
+
+`enrollment_http_client()` currently uses `danger_accept_invalid_certs(true)`. Therefore the HTTPS bootstrap does **not** authenticate the enrollment server certificate.
+
+That means the current enrollment phase is vulnerable to an active man-in-the-middle attacker who can impersonate the HTTPS enrollment endpoint and receive the submitted Basic credentials. The private key remains local, but the username/password bootstrap secret is still exposed to the impersonating endpoint.
+
+The connection established *after* enrollment is mTLS and uses the returned CA, but that does not retroactively secure the bootstrap exchange. Consequently:
+
+- `start_enroll_mtls` is a transitional flow, not the preferred production-secure flow in its current form.
+- `start_mtls` with a trusted CA and pre-provisioned client certificate is the secure production path today.
+- A future secure enrollment implementation must validate the HTTPS server with a trusted CA, certificate pin, or equivalent authenticated trust bootstrap.
+- An explicit insecure/development enrollment switch is preferable to silently disabling verification.
+
+The official ATAK enrollment manager exposes a `verifyHost` choice and records whether host verification is on or off. ArmaTAK should converge on the same explicit distinction.
+
+## Target secure enrollment design
+
+The intended production enrollment flow is:
+
+```text
+username/password
+      |
+      v
+HTTPS enrollment endpoint
+(server certificate MUST validate)
+      |
+      +--> GET /Marti/api/tls/config
+      +--> generate local private key + CSR
+      +--> POST configured signClient endpoint
+      v
+signed client certificate + trusted CA
+      |
+      v
+mTLS TAK streaming connection
+      |
+      +--> server authenticated by CA/name
+      +--> client authenticated by certificate
+      v
+CoT traffic
+```
+
+The development-only insecure variant should be explicit:
+
+```text
+username/password
+      |
+      v
+HTTPS enrollment endpoint
+(certificate verification explicitly disabled)
+      |
+      v
+WARNING / development-only path
+```
+
+Do not silently fall back from verified enrollment to unverified enrollment after a certificate validation failure.
+
+## Secret-handling requirements
+
+- Never include passwords, private keys, certificate payloads, or Authorization headers in logs.
+- `ConnectionConfig::describe()` may include the username and client UID for diagnostics, but it must never include the password.
+- Keep generated private keys in memory unless a future feature explicitly requires persistence.
+- Do not commit development certificates or credentials to the repository.
+- Treat enrollment credentials as bootstrap secrets and rotate/revoke them according to the TAK Server deployment policy.
+
+## Test contract
+
+Unit tests should lock down the protocol-level behavior that does not require a live TAK Server:
+
+- official endpoint paths and default mTLS port;
+- trimming and construction of enrollment URLs;
+- parsing TAK enrollment configuration with explicit values and fallback defaults;
+- PEM normalization;
+- absence of passwords from diagnostic descriptions;
+- TLS server-name derivation and PEM parsing where deterministic;
+- CoT and MAVLink pure serialization logic.
+
+Live certificate signing, TLS handshake behavior, socket reconnect behavior, mDNS, video processes, and Arma callback behavior belong in integration/E2E tests because they depend on operating-system or external-server state.
+
+## Upstream references
+
+The tests and protocol assumptions in this repository are based on these upstream implementations:
+
+- TAK Server, `CertManagerApi.java`: <https://github.com/TAK-Product-Center/Server/blob/5187abd46d827d37cfc5708805eced197a837e49/src/takserver-core/takserver-war/src/main/java/com/bbn/tak/tls/CertManagerApi.java>
+- TAK Server, `CoreConfig.example.xml`: <https://github.com/TAK-Product-Center/Server/blob/5187abd46d827d37cfc5708805eced197a837e49/src/takserver-core/example/CoreConfig.example.xml>
+- ATAK/CommonCommo, `enrollmentmanager.cpp`: <https://github.com/TAK-Product-Center/atak-civ/blob/9f6893dd657feacc35ec5de03dad721c2e44170e/commoncommo/core/impl/enrollmentmanager.cpp>
+
+Pinning the source revisions in this document keeps the development contract reproducible. When the upstream protocol changes, update both the implementation/tests and these references together.