diff --git a/documentation/docs/pages/developers/clients/socks5.mdx b/documentation/docs/pages/developers/clients/socks5.mdx index e0a70f0164d..75104482016 100644 --- a/documentation/docs/pages/developers/clients/socks5.mdx +++ b/documentation/docs/pages/developers/clients/socks5.mdx @@ -1,8 +1,8 @@ # Socks5 Client (Standalone) -> This client can also be utilised via the [Rust SDK](/developers/rust). +> This proxy is also available embedded in a Rust application via the [nym-sdk SOCKS5 module](/developers/rust/socks5). -Many existing applications are able to use either the SOCKS4, SOCKS4A, or SOCKS5 proxy protocols. If you want to send such an application's traffic through the mixnet, you can use the `nym-socks5-client` to bounce network traffic through the Nym network, like this: +Many existing applications are able to use either the SOCKS4, SOCKS4a, or SOCKS5 proxy protocols. If you want to send such an application's traffic through the mixnet, you can use the `nym-socks5-client` to bounce network traffic through the Nym network, like this: ```mermaid --- diff --git a/documentation/docs/pages/developers/concepts/exit-security.mdx b/documentation/docs/pages/developers/concepts/exit-security.mdx index fb56aa678e1..ee38e38a350 100644 --- a/documentation/docs/pages/developers/concepts/exit-security.mdx +++ b/documentation/docs/pages/developers/concepts/exit-security.mdx @@ -1,75 +1,81 @@ --- title: "Exit Security: What the Mixnet Protects and What It Doesn't" -description: "The canonical security model for traffic that leaves the Nym mixnet at an IPR exit gateway. Applies to smolmix, mix-tunnel, mix-fetch, mix-dns, and mix-websocket alike." +description: "The security model for traffic that exits the Nym Mixnet at an Exit Gateway, via the IP Packet Router or the SOCKS-based Network Requester, and how it changes for end-to-end traffic that never exits. Applies to smolmix, the SOCKS5 module, mix-tunnel, mix-fetch, mix-dns, and mix-websocket." schemaType: "TechArticle" section: "Developers" -lastUpdated: "2026-06-03" +lastUpdated: "2026-06-29" --- # Exit security import { Callout } from 'nextra/components' -Every tool that reaches an external service through the Nym mixnet shares the same security model, whether it's the Rust [`smolmix`](/developers/smolmix) crate or the mix-* packages built on [`mix-tunnel`](/developers/mix-tunnel) ([`mix-fetch`](/developers/mix-fetch), [`mix-dns`](/developers/mix-dns), [`mix-websocket`](/developers/mix-websocket)). They all exit the mixnet at an [IPR (Internet Packet Router)](/network/infrastructure/exit-services#ip-packet-router) gateway, so they inherit the same properties and the same single caveat. This page is the canonical statement of that model; the package pages link here rather than restating it. +Every tool that reaches an external service through the Nym Mixnet shares the same exit security model, whether it's the Rust [`smolmix`](/developers/smolmix) crate, the [SOCKS5 module](/developers/rust/socks5), or the mix-* packages built on [`mix-tunnel`](/developers/mix-tunnel) ([`mix-fetch`](/developers/mix-fetch), [`mix-dns`](/developers/mix-dns), [`mix-websocket`](/developers/mix-websocket)). They leave the Mixnet at an [Exit Gateway](/network/infrastructure/exit-services), either through the [IP Packet Router](/network/infrastructure/exit-services#ip-packet-router) (which forwards raw IP packets) or the SOCKS-based [Network Requester](/network/infrastructure/exit-services#network-requester) (which makes the request from a SOCKS stream), so they share the same properties and the same caveat. Tools where both ends run a Nym client ([`nym-sdk`](/developers/rust), the [TypeScript SDK](/developers/typescript)) never exit the Mixnet at all; the [end-to-end case](#proxy-mode-or-end-to-end) is covered below. This page is the canonical statement of the model; the package pages link here rather than restating it. ## The one-sentence version -The mixnet hides **who** you are from the destination and **where** you're going from the network, but the exit gateway sees your **destination** and any payload you didn't encrypt yourself. +In **proxy mode** the Mixnet hides **who** you are from the destination and **where** you're going from the network, but the Exit Gateway sees your **destination** and any payload you didn't encrypt yourself. In **end-to-end** mode there is no Exit Gateway: traffic stays Sphinx-encrypted the whole way. ## Proxy mode or end-to-end? -This page is about **proxy mode**: your traffic leaves the mixnet at an IPR exit and continues to a third-party server over clearnet, where the security trade-offs apply. +Most of this page is about **proxy mode**: your traffic leaves the Mixnet at an Exit Gateway, via either the IP Packet Router (raw IP packets) or the SOCKS-based Network Requester (which sees the destination hostname), and continues to a third-party server over clearnet, where the security trade-offs apply. -If both ends run a Nym client (**end-to-end**), traffic never exits the mixnet. It stays Sphinx-encrypted from your client to the other client, there is no IPR, and the [encrypt-your-own-payload](#encrypt-your-own-payload) concern below does not arise: the mixnet is the encrypted channel. What still applies to end-to-end traffic is everything that is not exit-specific: the [trust boundaries](#trust-boundaries) (unlinkability is statistical, not absolute) and [what the mixnet does not protect](#what-the-mixnet-does-not-protect) (application identity, fingerprinting, traffic analysis). For the end-to-end wiring itself, see [`nym-sdk`](/developers/rust) and the [TypeScript SDK](/developers/typescript). +If both ends run a Nym client (**end-to-end**), traffic never exits the Mixnet. It stays Sphinx-encrypted from your client to the other client, there is no Exit Gateway, and the [encrypt-your-own-payload](#encrypt-your-own-payload) concern below does not arise: the Mixnet is the encrypted channel. What still applies to end-to-end traffic is everything that is not exit-specific: the [trust boundaries](#trust-boundaries) (unlinkability is statistical, not absolute) and [what the Mixnet does not protect](#what-the-mixnet-does-not-protect) (application identity, fingerprinting, traffic analysis). For the end-to-end wiring itself, see [`nym-sdk`](/developers/rust) and the [TypeScript SDK](/developers/typescript). ## What each hop sees +**Proxy mode**: only your side runs Nym, and traffic exits to a third party: + +```text +you → entry gateway → 3 mix layers → exit gateway → destination +└─────────────── Sphinx-encrypted ──────────────┘└─ clearnet ─┘ + exit gateway strips Sphinx here +``` + +**End-to-end**: both sides run Nym, and traffic never leaves the Mixnet: + ```text - you - │ Sphinx - ▼ - entry gateway - │ Sphinx - ▼ - 3 mix layers - │ Sphinx - ▼ - IPR exit gateway - │ plain IP (Sphinx removed here) - ▼ - destination +you → entry gateway → 3 mix layers → peer's gateway → peer Nym client +└────────────────── Sphinx-encrypted the whole way ─────────────────┘ ``` +The table below is the proxy-mode path. In end-to-end mode there is no exit and no clearnet hop, so only the first two rows apply and the far end is another Nym client rather than a remote host. + | Segment | Mixnet encryption | What's visible | |---|---|---| -| Your machine → mixnet entry | Sphinx (layered) | Entry gateway sees your IP but not the destination | -| Inside the mixnet (entry gateway + 3 mix layers) | Sphinx (layered) | Each node only knows its previous and next hop | -| Exit gateway (IPR) | Sphinx removed, raw IP packet exposed | IPR sees destination IP + port. Payload depends on your application layer (see below). | -| IPR → remote host | None (Sphinx is mixnet-only; your own TLS, if any, still applies) | Remote host sees the IPR's IP, not yours | +| Your machine → Mixnet entry | Sphinx (layered) | Entry gateway sees your IP but not the destination | +| Inside the Mixnet (entry gateway + 3 mix layers) | Sphinx (layered) | Each node only knows its previous and next hop | +| Exit Gateway (IPR or NR) | Sphinx removed; raw IP packet (IPR) or SOCKS request (NR) exposed | The IPR sees the destination IP and port; the NR sees the destination hostname. Either way the payload depends on your application layer (see below). | +| Exit Gateway → remote host | None (Sphinx is Mixnet-only; your own TLS, if any, still applies) | Remote host sees the Exit Gateway's IP, not yours | -The Sphinx encryption is the **mixnet transport layer**: it protects packets as they traverse the mix nodes. At the exit gateway the Sphinx layers are stripped and the original IP packet is forwarded to the destination. This is analogous to how a Tor exit node or VPN endpoint unwraps its tunnel. +The Sphinx encryption is the **Mixnet transport layer**: it protects packets as they traverse the mix nodes. In proxy mode the Exit Gateway strips the Sphinx layers and forwards the request to the destination, analogous to how a Tor exit node or VPN endpoint unwraps its tunnel. In end-to-end mode the Sphinx layers are only removed at the receiving Nym client, so nothing is ever exposed on clearnet. ## Encrypt your own payload -Because the IPR removes the Sphinx layers, whatever is inside that IP packet is visible to the exit unless you encrypted it yourself. +Because the Exit Gateway removes the Sphinx layers, whatever is inside is visible to the exit unless you encrypted it yourself. -- **Application-layer encryption closes the gap.** TLS, the Noise Protocol, or any authenticated encryption keeps the payload as ciphertext to the IPR. It still sees the destination IP and port, but not the content. Over TLS the IPR only ever handles ciphertext bound for that destination; the bytes inside stay opaque to it. -- **Unencrypted payloads are fully visible.** Plain HTTP, unencrypted WebSocket (`ws://`), and plain UDP DNS are readable in full at the exit. The mixnet still hides your identity, so the exit reads the content without being able to attribute it to you. +- **Application-layer encryption closes the gap.** TLS, the Noise Protocol, or any authenticated encryption keeps the payload as ciphertext to the exit. It still sees the destination, but not the content. Over TLS the exit only ever handles ciphertext bound for that destination; the bytes inside stay opaque to it. +- **Unencrypted payloads are fully visible.** Plain HTTP, unencrypted WebSocket (`ws://`), and plain UDP DNS are readable in full at the exit. The Mixnet still hides your identity, so the exit reads the content without being able to attribute it to you. ## Trust boundaries -- You trust the mixnet to provide unlinkability between sender and receiver. Sphinx provides this cryptographically at the per-packet level: a node cannot read addressing beyond its own hop. Unlinkability of your *traffic pattern* over time is weaker, and statistical rather than absolute. It comes from mixing and cover traffic, and degrades with low network traffic, with cover traffic or Poisson timing disabled, and against an adversary that can observe a large fraction of the network. -- You trust the IPR exit gateway in the same way you trust a VPN exit or Tor exit node: it can inspect your raw IP packets. The difference is that the IPR doesn't know who is sending the traffic (the mixnet hides your identity). +- You trust the Mixnet to provide unlinkability between sender and receiver. Sphinx provides this cryptographically at the per-packet level: a node cannot read addressing beyond its own hop. Unlinkability of your *traffic pattern* over time is weaker, and statistical rather than absolute. It comes from mixing and cover traffic, and degrades with low network traffic, with cover traffic or Poisson timing disabled, and against an adversary that can observe a large fraction of the network. +- You trust the Exit Gateway in the same way you trust a VPN exit or Tor exit node: it can inspect whatever leaves the Mixnet, but it does not know who is sending the traffic (the Mixnet hides your identity). What it can inspect, and the shape of the trust, differs between the two exit types: + - **IP Packet Router (IPR).** A packet forwarder, like a VPN exit. It receives raw IP packets, so it sees the destination IP and port and reads any packet payload you did not encrypt. It works at the network layer and does not parse your application protocol. This is the exit used by `smolmix` and the `mix-*` packages ([`mix-tunnel`](/developers/mix-tunnel), [`mix-fetch`](/developers/mix-fetch), [`mix-dns`](/developers/mix-dns), [`mix-websocket`](/developers/mix-websocket)). + - **Network Requester (NR).** A SOCKS proxy that makes the request on your behalf, so your trust in it is exactly the trust you place in any SOCKS5 proxy. With the `socks5h` URL the SDK hands it the destination *hostname* (not just an IP) plus the byte stream, and the NR opens the TCP connection itself and relays bytes back. It therefore sees the destination hostname and port, and any payload you did not encrypt. This is the exit used by the [SOCKS5 module](/developers/rust/socks5) and the standalone [`nym-socks5-client`](/developers/clients/socks5). -Treat the IPR exactly as you would a VPN exit or a Tor exit node: it can inspect your raw IP packets. The difference Nym adds is that the IPR doesn't know who's sending the traffic. Protect the payload with TLS or equivalent, and pin a trusted exit (`preferredIpr`) if the exit operator matters to you. +Protect the payload with TLS or equivalent. If the exit operator matters to you, pin one; the control depends on the exit type: + +- **IPR-backed clients** (`smolmix` and the `mix-*` packages): set the preferred IPR (`preferredIpr` in the TypeScript and wasm packages; see each package page for the native equivalent). +- **SOCKS5 module** (Network Requester): pin a specific requester with `NetworkRequesterSelector::exact(...)`, or constrain the jurisdiction with `NetworkRequesterSelector::in_countries([...])`, passing either to `Socks5MixnetClient::connect_with(...)`. -## What the mixnet does not protect +## What the Mixnet does not protect -The mixnet operates at the **network layer**: it hides your IP and unlinks sender from receiver. It does nothing at the **application layer**, so anything you reveal in the content of your traffic is yours to manage: +The Mixnet operates at the **network layer**: it hides your IP and unlinks sender from receiver. It does nothing at the **application layer**, so anything you reveal in the content of your traffic is yours to manage: -- **Application identity.** If you log in, send a cookie, or include an API token, the destination knows who you are regardless of the network path. The mixnet anonymises the pipe, not what you put through it. +- **Application identity.** If you log in, send a cookie, or include an API token, the destination knows who you are regardless of the network path. The Mixnet anonymises the pipe, not what you put through it. - **Fingerprinting.** A stable request pattern, a distinctive TLS or HTTP fingerprint, or a recognisable account correlates your traffic across sessions. `mix-fetch`'s [default headers](/developers/mix-fetch/guides#default-request-headers) reduce trivial fingerprinting but do not make you indistinguishable from a real browser. Separately, the network-layer guarantee itself is not absolute: @@ -80,10 +86,10 @@ If you need anonymity at the application layer too, design for it explicitly: fr ## Comparison with other privacy tools -| | Nym (mixnet) | Tor | VPN | +| | Nym (Mixnet) | Tor | VPN | |---|---|---|---| | **Exit node sees traffic?** | Yes (encrypt it) | Yes (encrypt it) | Yes (encrypt it) | -| **Exit node knows sender?** | No (mixnet hides identity) | No (onion routing) | Yes (VPN provider knows) | +| **Exit node knows sender?** | No (Mixnet hides identity) | No (onion routing) | Yes (VPN provider knows) | | **Timing analysis resistance** | Strong with defaults (mixing, cover traffic) | Weak (low-latency) | None | | **UDP support** | Yes | No (TCP only) | Yes | @@ -91,7 +97,5 @@ The timing-analysis rating assumes the defaults. Cover traffic and Poisson timin ## Read more -The package pages add the parts specific to their transport (where TLS terminates, what the resolver sees, WSS vs `ws://`): - -- [Exit Gateway Services](/network/infrastructure/exit-services#ip-packet-router): how the IPR allocates addresses and routes raw IP packets, and how it differs from the SOCKS-based Network Requester. -- The per-package "Security model" section on [mix-fetch](/developers/mix-fetch/concepts#security-model), [mix-dns](/developers/mix-dns/guides#security-model), and [mix-websocket](/developers/mix-websocket/concepts#security-model) for the transport-specific exposure. +- [Exit Gateway Services](/network/infrastructure/exit-services): how the SOCKS-based Network Requester and the IP Packet Router each route traffic past the exit, and how they differ. +- Per-transport exposure (where TLS terminates, what the resolver sees, `wss://` vs `ws://`) lives on each package's own page: [smolmix](/developers/smolmix), the [SOCKS5 module](/developers/rust/socks5), [mix-fetch](/developers/mix-fetch), [mix-dns](/developers/mix-dns), and [mix-websocket](/developers/mix-websocket). diff --git a/documentation/docs/pages/developers/index.mdx b/documentation/docs/pages/developers/index.mdx index b441f391773..a1a57a3a3ea 100644 --- a/documentation/docs/pages/developers/index.mdx +++ b/documentation/docs/pages/developers/index.mdx @@ -21,7 +21,7 @@ The table below maps those two answers to a package. | Runtime | End-to-end (both sides run Nym) | Proxy (exit to clearnet) | |---|---|---| -| **Native Rust** (desktop / CLI / server) | [`nym-sdk`](/developers/rust): Mixnet, Stream, Client Pool | [`smolmix`](/developers/smolmix): `TcpStream` / `UdpSocket` · [`nym-sdk` SOCKS](/developers/rust) | +| **Native Rust** (desktop / CLI / server) | [`nym-sdk`](/developers/rust): Mixnet, Stream, Client Pool | [`smolmix`](/developers/smolmix): `TcpStream` / `UdpSocket` · [`nym-sdk` SOCKS5](/developers/rust/socks5) | | **Browser / WebView** (JS + WASM) | [TypeScript SDK](/developers/typescript): `@nymproject/sdk` raw messaging | [`mix-fetch`](/developers/mix-fetch) HTTP/S · [`mix-dns`](/developers/mix-dns) DNS · [`mix-websocket`](/developers/mix-websocket) WS/WSS | diff --git a/documentation/docs/pages/developers/rust.mdx b/documentation/docs/pages/developers/rust.mdx index 04229f6175e..a6142dadedf 100644 --- a/documentation/docs/pages/developers/rust.mdx +++ b/documentation/docs/pages/developers/rust.mdx @@ -37,6 +37,7 @@ For an overview of what the SDK can do, see the **[Tour](./rust/tour)**. For set |---|---|---| | [**Stream**](./rust/stream) | Multiplexed `AsyncRead + AsyncWrite` byte streams over the Mixnet, the closest analogue to TCP sockets. | Recommended | | [**Mixnet**](./rust/mixnet) | Raw message payloads, independently routed, no connections or ordering. Full control over the communication model. | Stable | +| [**SOCKS5**](./rust/socks5) | Local SOCKS5 proxy that routes any SOCKS-capable application through the Mixnet to a Network Requester (proxy mode, exits to clearnet). | Stable | | [**Client Pool**](./rust/client-pool) | Keeps ready-to-use `MixnetClient` instances warm for bursty workloads. | Stable | | [**TcpProxy**](./rust/tcpproxy) | TCP socket proxying with session management and message ordering. | Deprecated | | [**FFI**](./rust/ffi) | Go and C/C++ bindings. | Stable | @@ -50,4 +51,4 @@ For an overview of what the SDK can do, see the **[Tour](./rust/tour)**. For set For proxy-mode integrations (reaching third-party services through an Exit Gateway), see also: - [**`smolmix`**](/developers/smolmix): `TcpStream` and `UdpSocket` over the Mixnet via a userspace IP stack. Compatible with `tokio-rustls`, `hyper`, `tokio-tungstenite`, and the rest of the async Rust ecosystem. -- [**SOCKS Client**](./rust/mixnet): SOCKS4/4a/5 proxy via the Exit Gateway's Network Requester. Works with any SOCKS-capable application without code changes. +- [**SOCKS5 module**](./rust/socks5): SOCKS4/4a/5 proxy via the Exit Gateway's Network Requester. Works with any SOCKS-capable application without code changes. diff --git a/documentation/docs/pages/developers/rust/_meta.json b/documentation/docs/pages/developers/rust/_meta.json index d00e161c61d..d9344078c4a 100644 --- a/documentation/docs/pages/developers/rust/_meta.json +++ b/documentation/docs/pages/developers/rust/_meta.json @@ -3,6 +3,7 @@ "importing": "Installation", "mixnet": "Mixnet Module", "stream": "Stream Module", + "socks5": "SOCKS5 Module", "tcpproxy": "TcpProxy Module (Deprecated)", "client-pool": "Client Pool Module", "ffi": "FFI" diff --git a/documentation/docs/pages/developers/rust/mixnet.mdx b/documentation/docs/pages/developers/rust/mixnet.mdx index 8614a6a8399..56beb8a2bb9 100644 --- a/documentation/docs/pages/developers/rust/mixnet.mdx +++ b/documentation/docs/pages/developers/rust/mixnet.mdx @@ -1,6 +1,6 @@ --- title: "Nym Rust SDK: Mixnet Messaging Module" -description: "Use the Nym Rust SDK Mixnet module to send messages through the mixnet. Covers builder patterns, custom topologies, SOCKS proxy, and anonymous replies." +description: "Use the Nym Rust SDK Mixnet module to send messages through the mixnet. Covers builder patterns, custom topologies, and anonymous replies." schemaType: "TechArticle" section: "Developers" lastUpdated: "2026-03-13" diff --git a/documentation/docs/pages/developers/rust/socks5.mdx b/documentation/docs/pages/developers/rust/socks5.mdx new file mode 100644 index 00000000000..cda28d08e20 --- /dev/null +++ b/documentation/docs/pages/developers/rust/socks5.mdx @@ -0,0 +1,133 @@ +--- +title: "Nym Rust SDK: SOCKS5 Proxy Module" +description: "Use the Nym Rust SDK SOCKS5 module to route any SOCKS4/4a/5-capable application through the Mixnet. Covers Socks5MixnetClient, the socks5h proxy URL, automatic Network Requester discovery, country-based selection, and a reqwest example." +schemaType: "TechArticle" +section: "Developers" +lastUpdated: "2026-06-29" +--- + +# SOCKS5 Module + +import { Callout } from 'nextra/components' + +The `socks5` module provides [`Socks5MixnetClient`](https://docs.rs/nym-sdk/latest/nym_sdk/mixnet/struct.Socks5MixnetClient.html): a local SOCKS5 proxy that routes any SOCKS4, SOCKS4a, or SOCKS5-capable application's traffic through the Mixnet. Your application connects to a standard SOCKS5 proxy on `localhost`; the client forwards that traffic over the Mixnet to a [**Network Requester**](/network/infrastructure/exit-services#network-requester) running on an Exit Gateway, which makes the real request on your behalf. + + +This is a **proxy-mode** integration, not end-to-end. Unlike the [Mixnet](./mixnet) and [Stream](./stream) modules (where both sides run a Nym client), traffic here leaves the Mixnet at an Exit Gateway and continues to the destination over the public internet. The Mixnet anonymises the sender; protecting the payload (TLS) is your application's job. See [Exit security](/developers/concepts/exit-security) for the full model: what each hop sees, the trust boundaries, and how it compares with Tor and VPNs. + + +## How it works + +```text +Your machine + Application (reqwest, curl, a browser, ...) + │ SOCKS5 (socks5h://127.0.0.1:1080) + ▼ + Socks5MixnetClient (local listener + MixnetClient) + │ Sphinx packets + ▼ + Entry Gateway → 3 mix layers → Exit Gateway + │ Network Requester + ▼ makes the real request + Destination (clearnet) +``` + +The client chops the TCP stream into Sphinx packets, sends them through the Mixnet, and the Network Requester at the exit reassembles the stream and performs the request, returning the response the same way. The application never has to know the Mixnet exists. + +## Quick example + +You need the Nym address of a **Network Requester** (a service running on an Exit Gateway), or you can let the SDK discover one ([Automatic discovery](#automatic-discovery)). Point an HTTP client at the SOCKS5 URL the client exposes, and every request travels through the Mixnet: + +```rust +use nym_sdk::mixnet::Socks5MixnetClient; + +#[tokio::main] +async fn main() -> Result<(), Box> { + nym_bin_common::logging::setup_tracing_logger(); + + // Connect to a Network Requester service provider over the Mixnet. + // This opens a local SOCKS5 listener (default 127.0.0.1:1080). + let client = Socks5MixnetClient::connect_new("provider_nym_address...").await?; + + // Point any SOCKS5-capable HTTP client at the proxy URL. + let proxy = reqwest::Proxy::all(client.socks5_url())?; + let http = reqwest::Client::builder().proxy(proxy).build()?; + + // This request now travels through the Mixnet and exits at the requester. + let body = http.get("https://nymtech.net").send().await?.text().await?; + println!("{body}"); + + client.disconnect().await; + Ok(()) +} +``` + +`reqwest` must be built with its `socks` feature enabled, or `Proxy::all` will reject the `socks5h://` URL at runtime. The `setup_tracing_logger()` call is optional logging from the `nym-bin-common` crate; drop it if you do not want the dependency. + + +`socks5_url()` returns a **`socks5h://`** URL, not `socks5://`. The trailing `h` tells the HTTP client to hand the hostname to the proxy and let the Network Requester resolve DNS at the exit, rather than resolving locally and leaking the destination through a local DNS query. + + +To combine the SOCKS5 proxy with other builder options (persistent keys via `StoragePaths`, custom configuration), attach a `Socks5` config to `MixnetClientBuilder` instead of using `connect_new`: + +```rust +use nym_sdk::mixnet; + +let socks5_config = mixnet::Socks5::new("provider_nym_address...".to_string()); +let client = mixnet::MixnetClientBuilder::new_ephemeral() + .socks5_config(socks5_config) + .build()? + .connect_to_mixnet_via_socks5() + .await?; +``` + +## Automatic discovery + +You do not have to hardcode a Network Requester address. [`connect_with`](https://docs.rs/nym-sdk/latest/nym_sdk/mixnet/struct.Socks5MixnetClient.html#method.connect_with) takes a `NetworkRequesterSelector` describing how to pick one plus an optional listener address, and connects in a single call. There are three selectors; the third, country-restricted discovery, has [its own section below](#selecting-by-country): + +```rust +use nym_sdk::mixnet::{NetworkRequesterSelector, Socks5MixnetClient}; + +// Any available requester, weighted by performance (None = default 127.0.0.1:1080): +let client = Socks5MixnetClient::connect_with(NetworkRequesterSelector::any(), None).await?; + +// A specific requester you already know: +let client = Socks5MixnetClient::connect_with(NetworkRequesterSelector::exact("address...")?, None).await?; +``` + +For `any`, discovery queries the mainnet directory for Exit Gateways that advertise a Network Requester and selects one weighted by performance. Discovery always queries mainnet, regardless of the network the client itself is configured for. + +### Selecting by country + +To constrain where your traffic leaves the Mixnet, build the requester with [ISO 3166 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) country codes. The chosen requester must have declared a location in one of them (see the warning below): + +```rust +use nym_sdk::mixnet::{NetworkRequesterSelector, Socks5MixnetClient}; + +let requester = NetworkRequesterSelector::in_countries(["CH", "DE"])?; // Switzerland or Germany + +// Listen on 127.0.0.1:1081 instead of the default 1080: +let client = Socks5MixnetClient::connect_with(requester, Some("127.0.0.1:1081".parse()?)).await?; +``` + +Codes are case-insensitive and validated up front, so a typo fails immediately rather than at connect time. Passing more than one code means "any of these". + + +A requester's location is **self-reported by its operator and optional**. Requesters that have not declared a location are excluded once you set a country filter, so a narrow filter can return `NoGatewayInCountries` even when requesters exist there but have not advertised one. Discovery does not silently fall back to another country: an empty result is an error, since routing through an unintended jurisdiction would defeat the point of asking. + + +## SDK module or standalone binary + +The same proxy logic ships two ways. They are interchangeable on the wire; choose by how you want to run it: + +| | Use it when | +|---|---| +| **`socks5` module** (this page) | You want the proxy embedded in a Rust application and managed in-process, alongside other SDK clients. | +| [**Standalone `nym-socks5-client`**](/developers/clients/socks5) | You want a language-agnostic local proxy binary that any application (in any language) can point at, with no code changes. | + +## Further reading + +- [API reference on docs.rs](https://docs.rs/nym-sdk/latest/nym_sdk/mixnet/struct.Socks5MixnetClient.html): all methods, configuration, and types +- [Example: SOCKS5 proxy](https://github.com/nymtech/nym/blob/develop/sdk/rust/nym-sdk/examples/socks5.rs): select a requester (auto-discover, pin by country, or a known address) and proxy a request +- [Standalone SOCKS5 client](/developers/clients/socks5): the language-agnostic binary form +- [Exit security](/developers/concepts/exit-security): what an Exit Gateway can observe in proxy mode diff --git a/documentation/docs/pages/network/infrastructure/exit-services.mdx b/documentation/docs/pages/network/infrastructure/exit-services.mdx index 73b2c62c6ad..653bdbf6ecc 100644 --- a/documentation/docs/pages/network/infrastructure/exit-services.mdx +++ b/documentation/docs/pages/network/infrastructure/exit-services.mdx @@ -32,7 +32,7 @@ Because it operates at the application layer, the NR: - Can enforce allow/deny lists on destination hosts and ports - Sees the destination hostname and port, but not the contents if TLS is used -**Used by:** the [SDK's SOCKS client](/developers/rust/mixnet), [standalone SOCKS5 client](/developers/clients/socks5), and [mixFetch](/developers/mix-fetch) (which wraps SOCKS requests in a browser-friendly `fetch` API). +**Used by:** the [SDK's SOCKS5 module](/developers/rust/socks5) and the [standalone SOCKS5 client](/developers/clients/socks5). ## IP Packet Router @@ -59,7 +59,7 @@ Because it operates at the IP layer, the IPR: In both services, traffic between the Exit Gateway and the destination travels over the public internet, exactly as it would from any other server. The mixnet protects sender anonymity (the destination sees the gateway's IP, not yours), but does not encrypt the payload past the gateway. Use TLS or another application-layer cipher to protect payload confidentiality, just as you would on a direct connection. -**Used by:** [NymVPN anonymous mode](/network/dvpn-mode/protocol) (5-hop mixnet routing to the IPR), and [`smolmix`](/developers/smolmix) (programmatic `TcpStream`/`UdpSocket` access to the IPR via the Rust SDK). +**Used by:** [NymVPN anonymous mode](/network/dvpn-mode/protocol) (5-hop mixnet routing to the IPR), [`smolmix`](/developers/smolmix) (programmatic `TcpStream`/`UdpSocket` access to the IPR via the Rust SDK), and the browser `mix-*` packages built on `smolmix`: [`mix-tunnel`](/developers/mix-tunnel), [`mix-fetch`](/developers/mix-fetch), [`mix-dns`](/developers/mix-dns), and [`mix-websocket`](/developers/mix-websocket). ## Comparison @@ -70,7 +70,7 @@ In both services, traffic between the Exit Gateway and the destination travels o | **DNS** | Resolved by the NR | Client resolves its own | | **Client gets** | Proxied connections | An allocated IP address | | **Connection model** | Per-request | Persistent tunnel | -| **Used by** | SDK SOCKS client, mixFetch | NymVPN (anonymous mode), smolmix | +| **Used by** | SDK SOCKS5 module, standalone SOCKS5 client | NymVPN (anonymous mode), smolmix, mix-* packages | ## Trust model