API Communication

​

Overview

​

API Endpoints

• Account operations: Create account, login, check expiry, submit vouchers
• Device management: Register devices, rotate WireGuard keys, list/remove devices
• Relay list updates: Download current relay and bridge server lists
• Version checks: Check for app updates and security advisories
• GeoIP lookups: Determine current location and verify tunnel connectivity
• Problem reports: Submit diagnostic logs (with user consent)

​

Access Methods

​

1. Direct TLS Connection

Client --[TLS/HTTPS]--> api.mullvad.net

• Fastest and most reliable when available
• Uses standard TLS 1.3
• No additional overhead
• May be blocked in censored networks

​

2. Mullvad Bridges (Shadowsocks)

Client --[Shadowsocks]--> Mullvad Bridge --[TLS/HTTPS]--> api.mullvad.net

1. Client requests bridge server from relay selector
2. Relay selector chooses Shadowsocks-enabled bridge
3. All API traffic proxied through bridge
4. Bridge forwards to actual API endpoint

message AccessMethod {
  message Bridges {}
  oneof access_method {
    Bridges bridges = 2;
  }
}

message ShadowsocksEndpointData {
  uint32 port = 1;
  string cipher = 2;
  string password = 3;
  TransportProtocol protocol = 4;  // TCP or UDP
}

• Cipher: Encryption algorithm (e.g., chacha20-ietf-poly1305)
• Password: Shared secret for authentication
• Protocol: TCP or UDP transport

​

3. Encrypted DNS Proxy

Client --[DoH/DoT]--> Encrypted DNS Proxy --[TLS/HTTPS]--> api.mullvad.net

1. Client fetches encrypted DNS proxy configs from frakta.eu
2. Connects using DNS-over-HTTPS (DoH) or DNS-over-TLS (DoT)
3. DNS proxy forwards requests to actual API
4. Appears as DNS traffic to network observers

// mullvad-daemon/src/api.rs:64-78
AccessMethod::BuiltIn(BuiltInAccessMethod::EncryptedDnsProxy) => {
    if let Err(error) = self
        .encrypted_dns_proxy_cache
        .fetch_configs("frakta.eu")
        .await
    {
        log::warn!("Failed to fetch new Encrypted DNS Proxy configurations");
    }
    let Some(edp) = self.encrypted_dns_proxy_cache.next_configuration() else {
        return None;
    };
    ApiConnectionMode::Proxied(ProxyConfig::from(edp))
}

​

4. Custom Proxies

message Socks5Local {
  string remote_ip = 1;
  uint32 remote_port = 2;
  TransportProtocol remote_transport_protocol = 3;
  uint32 local_port = 4;
}

message Socks5Remote {
  string ip = 1;
  uint32 port = 2;
  SocksAuth auth = 3;
}

message SocksAuth {
  string username = 1;
  string password = 2;
}

message Shadowsocks {
  string ip = 1;
  uint32 port = 2;
  string password = 3;
  string cipher = 4;
}

​

Access Method Selection

​

Resolution Process

// mullvad-daemon/src/api.rs:47-96
impl AccessMethodResolver for DaemonAccessMethodResolver {
    async fn resolve_access_method_setting(
        &mut self,
        access_method: &AccessMethod,
    ) -> Option<(AllowedEndpoint, ApiConnectionMode)> {
        let connection_mode = match access_method {
            AccessMethod::BuiltIn(BuiltInAccessMethod::Direct) => 
                ApiConnectionMode::Direct,
            AccessMethod::BuiltIn(BuiltInAccessMethod::Bridge) => {
                let bridge = self.relay_selector.get_bridge_forced()?;
                ApiConnectionMode::Proxied(ProxyConfig::from(bridge))
            }
            AccessMethod::BuiltIn(BuiltInAccessMethod::EncryptedDnsProxy) => {
                let edp = self.encrypted_dns_proxy_cache.next_configuration()?;
                ApiConnectionMode::Proxied(ProxyConfig::from(edp))
            }
            AccessMethod::Custom(config) => {
                ApiConnectionMode::Proxied(ProxyConfig::from(config.clone()))
            }
        };
        // ... resolve endpoint ...
    }
}

​

Access Method Priority

message ApiAccessMethodSettings {
  AccessMethodSetting direct = 1;
  AccessMethodSetting mullvad_bridges = 2;
  AccessMethodSetting encrypted_dns_proxy = 3;
  repeated AccessMethodSetting custom = 4;
}

message AccessMethodSetting {
  UUID id = 1;
  string name = 2;
  bool enabled = 3;
  AccessMethod access_method = 4;
}

​

Automatic Failover

1. Current access method is marked as potentially unavailable
2. Next enabled access method is tried
3. Process repeats until success or all methods exhausted
4. Failed requests can trigger access method testing

​

Testing Access Methods

rpc TestCustomApiAccessMethod(CustomProxy) returns (google.protobuf.BoolValue) {}
rpc TestApiAccessMethodById(UUID) returns (google.protobuf.BoolValue) {}

• Proxy connectivity
• API reachability through proxy
• Authentication success

​

API Availability Monitoring

use mullvad_api::availability::ApiAvailability;

• Periodic connectivity checks
• Request success/failure tracking
• Automatic access method switching
• Exponential backoff on repeated failures

​

Firewall Integration

​

Allowed Endpoints

use talpid_types::net::AllowedEndpoint;

pub fn resolve_allowed_endpoint(
    connection_mode: &ApiConnectionMode,
    fallback: SocketAddr,
) -> AllowedEndpoint {
    // Determine which endpoints need firewall exclusions
}

​

Tunnel State Coordination

• In secured states (Connecting, Connected, Error), only API traffic allowed outside tunnel
• In disconnected state, broader internet access may be permitted (depending on lockdown mode)
• API endpoint changes communicated to firewall in real-time

​

Request Management

​

Asynchronous Operations

use mullvad_api::rest::MullvadRestHandle;

let api_handle = MullvadRestHandle::new(/* ... */);
let account_data = api_handle.get_account_data(account_token).await?;

​

Request Cancellation

• When tunnel connects, API connection resets
• Allows switching between access methods
• Ensures API uses current endpoint configuration

​

Offline State Handling

• API requests are blocked/queued
• Prevents wasted connection attempts
• Resumes when connectivity restored

​

Address Caching

use mullvad_api::{AddressCache, FileAddressCacheBacking};

let address_cache = AddressCache::<FileAddressCacheBacking>::new(cache_path)?;
let api_addr = address_cache.get_address().await;

• Reduces DNS lookup failures
• Enables API access when DNS is blocked/unreliable
• Periodically refreshed when DNS is available

​

Connection Modes

​

Direct Mode

enum ApiConnectionMode {
    Direct,
    // ...
}

​

Proxied Mode

enum ApiConnectionMode {
    Proxied(ProxyConfig),
}

enum ProxyConfig {
    Shadowsocks(ShadowsocksConfig),
    Socks(SocksConfig),
}

​

API Client Implementation

mullvad-api/
├── src/
│   ├── lib.rs              # Main API client
│   ├── rest.rs             # REST request handling
│   ├── proxy.rs            # Proxy configuration
│   ├── access_mode.rs      # Access method resolution
│   └── availability.rs     # Availability monitoring

​

Request Flow

1. Daemon initiates request: api_handle.get_relay_list().await
2. Access method resolution: Select appropriate access method
3. Endpoint resolution: Determine IP address and port
4. Firewall configuration: Ensure endpoint is allowed
5. HTTP request: Execute via direct or proxied connection
6. Response processing: Parse and return data
7. Error handling: Retry or failover on errors

​

Censorship Resistance Strategies

​

Traffic Obfuscation

• Direct: Standard TLS - easily identifiable
• Shadowsocks: Encrypted proxy protocol - hard to detect
• Encrypted DNS Proxy: Masquerades as DNS traffic - very hard to block without breaking DNS
• Custom SOCKS5: Depends on proxy configuration

​

Domain Fronting

• TLS SNI shows innocent domain (frakta.eu)
• Actual API requests hidden in encrypted payload
• Difficult to block without blocking entire domain

​

Port Variability

• Shadowsocks: Range of ports from relay list
• UDP2TCP: Ports 80, 443, 5001
• QUIC: Port 443
• Harder to block all ports without false positives

​

Security Considerations

​

TLS Certificate Validation

• Pinned certificate or standard CA validation
• Prevents man-in-the-middle attacks
• Even when using proxies, end-to-end TLS maintained

​

Proxy Trust Model

• Operated by Mullvad
• Same trust as Mullvad relays
• API requests encrypted end-to-end

• User-provided
• TLS still protects API requests
• Proxy sees encrypted traffic only

​

Authentication

• Account tokens (for account operations)
• Device tokens (for device-specific operations)
• OAuth tokens (for web authentication)

​

Management Interface Integration

​

Configuration

rpc AddApiAccessMethod(NewAccessMethodSetting) returns (UUID) {}
rpc RemoveApiAccessMethod(UUID) returns (google.protobuf.Empty) {}
rpc SetApiAccessMethod(UUID) returns (google.protobuf.Empty) {}
rpc UpdateApiAccessMethod(AccessMethodSetting) returns (google.protobuf.Empty) {}
rpc GetCurrentApiAccessMethod(google.protobuf.Empty) returns (AccessMethodSetting) {}

​

Events

message DaemonEvent {
  oneof event {
    AccessMethodSetting new_access_method = 7;
    // ...
  }
}

​

Bridge Server List

message BridgeList {
  repeated Bridge bridges = 1;
  BridgeEndpointData endpoint_data = 2;
}

message Bridge {
  string hostname = 1;
  string ipv4_addr_in = 2;
  optional string ipv6_addr_in = 3;
  bool active = 4;
  fixed64 weight = 5;
  Location location = 6;
}

​

Bridge Endpoint Data

message BridgeEndpointData {
  repeated ShadowsocksEndpointData shadowsocks = 1;
}

​

Debugging and Testing

​

Access Method Testing

mullvad api access-method test <method-id>

• Proxy connectivity
• API reachability
• Authentication

​

Current Access Method

mullvad api access-method get-current

​

Forced Access Method

mullvad api access-method set <method-id>

​

Error Recovery

​

Request Retry Logic

1. Immediate retry with same access method
2. Switch to next access method on repeated failure
3. Exponential backoff between attempts
4. Circuit breaker after extended failures

​

Access Method Rotation

• Dead access methods are discovered
• New methods are tested
• Best-performing method is used

​

Performance Optimization

​

Connection Reuse

• Connection pooling for repeated requests
• Reduced TLS handshake overhead
• Lower latency for consecutive requests

​

Caching

• Relay lists cached locally (refreshed periodically)
• Account data cached (refreshed on access)
• Address cache reduces DNS lookups

​

Parallel Requests

• Relay list updates don’t block account checks
• Version checks run in background
• No artificial serialization

​

Related Documentation

• Management Interface
• Relay Selector
• Mullvad vs Talpid Layers
• Offline Detection
• Architecture Overview (source repository)