TunnelKit

This library provides 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.0h, which in turn enables support for a certain range of encryption and digest algorithms.

Contacts

Twitter: @keeshux

Website: davidederosa.com

Getting started

The client is known to work with OpenVPN® 2.3+ servers. Key renegotiation and replay protection are also included, but full-fledged configuration files (.ovpn) are not currently supported.

• Handshake and tunneling over UDP or TCP
• Ciphers
  • AES-CBC (128/192/256 bit)
  • AES-GCM (128/192/256 bit, 2.4)
• HMAC digests
  • SHA-1
  • SHA-2 (224/256/384/512 bit)
• NCP (Negotiable Crypto Parameters, 2.4)
  • Server-side
• TLS handshake
  • CA validation
  • Client certificate
• Compression framing
  • Disabled
  • Compress (2.4)
  • LZO (deprecated in 2.4)
• Replay protection (hardcoded window)

The library therefore supports compression framing, just not compression. Remember to match server-side compression framing in order to avoid a confusing loss of data packets. E.g. if server has comp-lzo no, client must use compressionFraming = .compLZO.

Installation

Requirements

• iOS 9.0+ / macOS 10.11+
• Xcode 9+ (Swift 4)
• Git (preinstalled with Xcode Command Line Tools)
• Ruby (preinstalled with macOS)
• CocoaPods 1.4.0
• jazzy (optional, for documentation)

It's highly recommended to use the Git and Ruby packages provided by Homebrew.

CocoaPods

To use with CocoaPods just add this to your Podfile:

pod 'TunnelKit'

Testing

Download the library codebase locally:

$ git clone https://github.com/keeshux/TunnelKit.git

Assuming you have a working CocoaPods environment, setting up the library workspace only requires installing the pod dependencies:

$ pod install

After that, open TunnelKit.xcworkspace in Xcode and run the unit tests found in the TunnelKitTests target. A simple CMD+U while on TunnelKit-iOS should do that as well.

Demo

There is a Demo directory containing a simple app for testing the tunnel, called BasicTunnel. As usual, prepare for CocoaPods:

$ pod install

then open Demo.xcworkspace and run the BasicTunnel-iOS target.

For the VPN to work properly, the BasicTunnel demo requires:

• App Groups and Keychain Sharing capabilities
• App IDs with Packet Tunnel entitlements

both in the main app and the tunnel extension target.

In order to test connection to your own server, modify the file Demo/BasicTunnel-[iOS|macOS]/ViewController.swift and make sure to set builder.ca to the PEM encoded certificate of your VPN server's CA (or nil to skip CA validation, however discouraged).

Example:

builder.endpointProtocols = [TunnelKitProvider.EndpointProtocol(.udp, 1194)]
builder.ca = """
-----BEGIN CERTIFICATE-----
MIIFJDCC...
-----END CERTIFICATE-----
"""

Documentation

The library is split into two modules, in order to decouple the low-level protocol implementation from the platform-specific bridging, namely the NetworkExtension VPN framework.

Full documentation of the public interface is available and can be generated with 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.

Core

Here you will find the low-level entities on top of which the connection is established. Code is mixed Swift and Obj-C, most of it is not exposed to consumers. The Core module depends on OpenSSL and is mostly platform-agnostic.

The entry point is the SessionProxy class. The networking layer is fully abstract and delegated externally with the use of opaque IOInterface (LinkInterface and TunnelInterface) and SessionProxyDelegate protocols.

AppExtension

The goal of this module is packaging up a black box implementation of a NEPacketTunnelProvider, which is the essential part of a Packet Tunnel Provider app extension. You will find the main implementation in the TunnelKitProvider class.

Currently, the extension supports VPN over both UDP and TCP sockets. A debug log snapshot is optionally maintained and shared to host apps via UserDefaults in a shared App Group.

Contributing

By contributing to this project you are agreeing to the terms stated in the Contributor License Agreement (CLA).

For more details please see CONTRIBUTING.

License

This project is licensed under the GPLv3 license, which can be found here. I can provide a different license on request, e.g. if you want to use the library on the App Store. Feel free to contact me in such case.

Credits

• PIATunnel - TunnelKit is a hard fork of PIATunnel that repurposes it substantially. PIATunnel is licensed under the MIT (Expat) license, which can be found here.
• SwiftyBeaver - A convenient logging library.

This product includes software developed by the OpenSSL Project for use in the OpenSSL Toolkit. (https://www.openssl.org/)

© 2002-2018 OpenVPN Inc. - OpenVPN is a registered trademark of OpenVPN Inc.

Donations

TunnelKit is free software, donations are extremely welcome.

Bitcoin address: 16w2AWamiH2SS68NYSMDcrbh5MnZ1c5eju