Update README with recent reorg
This commit is contained in:
Davide De Rosa
parent
9e14f33235
commit
4a47eec041
47
README.md
47
README.md
|
|
@ -1,11 +1,10 @@
|
|||
|
||||
|
||||
[](https://www.openssl.org/news/openssl-1.1.1-notes.html)
|
||||
[](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
|
||||
|
|
|
|||
Loading…
Reference in New Issue