# Package com.codename1.vpn.tunnel

package com.codename1.vpn.tunnel

Writing the tunnel itself, rather than asking the system to run one.

`com.codename1.vpn.profile` asks the operating system to run an IKEv2 or IPsec client it already implements, which is what most apps want. This package is the other thing: the app receives raw IP packets and decides what happens to them.

##### Where it runs

`Tunnels.isSupported()` answers true on Android, and on an iOS build that generated the extension. Ask it, and keep a path for the answer being no -- on iOS that is the default.

- Android: `CN1VpnService`, which ships in the port and which the builder declares in the manifest for an app that referenced this package. It is a `VpnService` in the app's own process, needing `BIND_VPN_SERVICE` and the user's consent. The tunnel runs in that process, so the instance passed to `Tunnels.start(VpnTunnel, TunnelSetup)` is the instance that runs and everything it closed over is still there.
- iOS: an `NEPacketTunnelProvider` in a Network Extension, which the build generates for a project that sets `ios.vpn.tunnel=true` and names its tunnel in `ios.vpn.tunnel.class`. That extension is a separate process with a virtual machine of its own: it is translated from the tunnel rather than from the application, so it carries what the tunnel reaches and none of the app -- which is why the rule below is a link error there rather than advice. It also needs `com.apple.developer.networking.networkextension`, which Apple grants case by case, so no iOS build produces one without being asked.
- Simulator and desktop: a loopback transport, so the packet loop can be exercised without a device.

##### Why the API is shaped for another process anyway

`TunnelSetup.data`, `TunnelConfiguration` and the packet pooling in `PacketBuffer` all assume the tunnel may be constructed somewhere the app's statics are not, under a memory budget far below an app's. That is the shape a Network Extension needs, and it costs an Android tunnel nothing to be written that way. A tunnel that takes its configuration from `VpnTunnel.onStart(TunnelConfiguration)` rather than reaching for a static the app set is the one that stays portable.

- Related Packages
  Package
  Description
  com.codename1.vpn
  Installing and controlling a VPN configuration.
  com.codename1.vpn.profile
  Asking the operating system to run a standard VPN tunnel.
  com.codename1.vpn.spi
  The seam between the portable `com.codename1.vpn` API and each platform's native VPN machinery.
- Class
  Description
  PacketBuffer
  One IP packet on its way through the tunnel.
  TunnelConfiguration
  What the tunnel was started with.
  Tunnels
  Starts and stops a packet tunnel this application implements.
  TunnelSetup
  What an application asks the platform to set up before its tunnel runs.
  TunnelStopReason
  Why a tunnel stopped.
  TunnelTransport
  How packets reach the tunnel, which is where the two platforms differ.
  VpnTunnel
  The packet loop, written once for both platforms.