diff --git a/README.md b/README.md index e41c1d9..1731dad 100644 --- a/README.md +++ b/README.md @@ -1,11 +1,10 @@ ![iOS 12+](https://img.shields.io/badge/ios-12+-green.svg) ![macOS 10.15+](https://img.shields.io/badge/macos-10.15+-green.svg) -[![OpenSSL 1.1.1l](https://img.shields.io/badge/openssl-1.1.1l-d69c68.svg)](https://www.openssl.org/news/openssl-1.1.1-notes.html) [![License GPLv3](https://img.shields.io/badge/license-GPLv3-lightgray.svg)](LICENSE) # TunnelKit -This library provides a generic framework for VPN development and a simplified Swift/Obj-C implementation of the OpenVPN® protocol for the Apple platforms. The crypto layer is built on top of [OpenSSL 1.1.1][dep-openssl], which in turn enables support for a certain range of encryption and digest algorithms. +This library provides a generic framework for VPN development and a simplified Swift/Obj-C implementation of the OpenVPN® protocol for the Apple platforms. The crypto layer is built on top of [BoringSSL][dep-boringssl] (as seen in [SwiftNIO SSL][dep-swiftniossl]), which in turn enables support for a certain range of encryption and digest algorithms. ## Getting started @@ -71,10 +70,9 @@ Many other flags are ignored too but it's normally not an issue. ### Requirements -- iOS 12.0+ / macOS 10.15+ -- SwiftPM 5 +- iOS 13.0+ / macOS 10.15+ +- SwiftPM 5.3 - Git (preinstalled with Xcode Command Line Tools) -- [jazzy][dep-jazzy] (optional, for documentation) It's highly recommended to use the Git package provided by [Homebrew][dep-brew]. @@ -84,7 +82,6 @@ Download the library codebase locally: $ git clone https://github.com/passepartoutvpn/tunnelkit.git - There are demo targets containing a simple app for testing the tunnel, called `BasicTunnel`. Open `Demo/TunnelKit.xcodeproject` in Xcode and run it on both iOS and macOS. For the VPN to work properly, the `BasicTunnel` demo requires: @@ -115,15 +112,7 @@ Remember that the App Group on macOS requires a team ID prefix. The library is split into several modules, in order to decouple the low-level protocol implementation from the platform-specific bridging, namely the [NetworkExtension][ne-home] VPN framework. -Full documentation of the public interface is available and can be generated with [jazzy][dep-jazzy]. After installing the jazzy Ruby gem with: - - $ gem install jazzy - -enter the root directory of the repository and run: - - $ jazzy - -The generated output is stored into the `docs` directory in HTML format. +Full documentation of the public interface is available and can be generated by opening the package in Xcode and running "Build Documentation" (Xcode 13). ### TunnelKitCore @@ -134,31 +123,39 @@ Contains the building blocks of a VPN protocol. Eventually, a consumer would imp There are no physical network implementations (e.g. UDP or TCP) in this module. -### TunnelKitAppExtension - -Provides a layer on top of the NetworkExtension framework. Most importantly, bridges native [NWUDPSession][ne-udp] and [NWTCPConnection][ne-tcp] to an abstract `GenericSocket` interface, thus making a multi-protocol VPN dramatically easier to manage. - ### TunnelKitManager This component includes convenient classes to control the VPN tunnel from your app without the NetworkExtension headaches. Have a look at `VPNProvider` implementations: - `MockVPNProvider` (default, useful to test on simulator) -- `NetworkExtensionVPNProvider` (for IPSec/IKEv2) +- `NetworkExtensionVPNProvider` (anything based on NetworkExtension) + +### TunnelKitAppExtension + +Provides a layer on top of the NetworkExtension framework. Most importantly, bridges native [NWUDPSession][ne-udp] and [NWTCPConnection][ne-tcp] to an abstract `GenericSocket` interface, thus making a multi-protocol VPN dramatically easier to manage. ### TunnelKitIKE Here you find `NativeProvider`, a generic way to manage a VPN profile based on the native IPSec/IKEv2 protocols. Just wrap a `NEVPNProtocolIPSec` or `NEVPNProtocolIKEv2` object in a `NetworkExtensionVPNConfiguration` and use it to install or connect to the VPN. -### TunnelKitOpenVPN +### TunnelKitOpenVPN* -Here are the low-level entities on top of which an OpenVPN connection is established. Code is mixed Swift and Obj-C, most of it is not exposed to consumers. The module depends on OpenSSL. +#### Protocol + +Here are the low-level entities on top of which an OpenVPN connection is established. Code is mixed Swift and Obj-C, most of it is not exposed to consumers. The protocol implementation in particular depends on BoringSSL. The entry point is the `OpenVPNSession` class. The networking layer is fully abstract and delegated externally with the use of opaque `IOInterface` (`LinkInterface` and `TunnelInterface`) and `OpenVPNSessionDelegate` protocols. -Another goal of this module is packaging up a black box implementation of a [NEPacketTunnelProvider][ne-ptp], which is the essential part of a Packet Tunnel Provider app extension. You will find the main implementation in the `OpenVPNTunnelProvider` class. On the client side, you manage the VPN profile with the `OpenVPNProvider` class, which is a specific implementation of `NetworkExtensionVPNProvider`. +#### AppExtension + +Another goal of this area is packaging up a black box implementation of a [NEPacketTunnelProvider][ne-ptp], which is the essential part of a Packet Tunnel Provider app extension. You will find the main implementation in the `OpenVPNTunnelProvider` class. A debug log snapshot is optionally maintained and shared by the tunnel provider to host apps via the App Group container. +#### Manager + +On the client side, you manage the VPN profile with the `OpenVPNProvider` class, which is a specific implementation of `NetworkExtensionVPNProvider`. + ### TunnelKitLZO Due to the restrictive license (GPLv2), LZO support is provided as an optional component. @@ -207,9 +204,9 @@ Website: [passepartoutvpn.app][about-website] [openvpn]: https://openvpn.net/index.php/open-source/overview.html -[dep-jazzy]: https://github.com/realm/jazzy [dep-brew]: https://brew.sh/ -[dep-openssl]: https://www.openssl.org/ +[dep-boringssl]: https://boringssl.googlesource.com/boringssl/ +[dep-swiftniossl]: https://github.com/apple/swift-nio-ssl [ne-home]: https://developer.apple.com/documentation/networkextension [ne-ptp]: https://developer.apple.com/documentation/networkextension/nepackettunnelprovider