897e824340 | ||
---|---|---|
.github | ||
Demo | ||
TunnelKit | ||
TunnelKit-iOS | ||
TunnelKit-macOS | ||
TunnelKit.xcodeproj | ||
TunnelKit.xcworkspace | ||
TunnelKitHost | ||
TunnelKitTests | ||
.gitignore | ||
.jazzy.yaml | ||
.swift-version | ||
CLA.rst | ||
CONTRIBUTING.md | ||
LICENSE | ||
Podfile | ||
Podfile.lock | ||
README.md | ||
TunnelKit.podspec |
README.md
Private Internet Access
Private Internet Access is the world's leading consumer VPN service. At Private Internet Access we believe in unfettered access for all, and as a firm supporter of the open source ecosystem we have made the decision to open source our VPN clients. For more information about the PIA service, please visit our website privateinternetaccess.com or check out the Wiki.
Tunnel for Apple platforms
This library provides a simplified Swift/Obj-C implementation of the OpenVPN® protocol for the Apple platforms, while also taking advantage of the Private Internet Access client patch customizations. 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.
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
- Client-initiated renegotiation
- Replay protection (hardcoded window)
- Data encryption
- AES-CBC (128 and 256 bit)
- AES-GCM (128 and 256 bit)
- HMAC digest
- SHA-1
- SHA-256
- TLS CA validation
- RSA (2048, 3072 and 4096 bit)
- ECC (secp256r1, secp521r1, secp256k1)
- Custom certificate
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.5.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 'PIATunnel'
Testing
Download the library codebase locally:
$ git clone https://github.com/pia-foss/tunnel-apple.git
Assuming you have a working CocoaPods environment, setting up the library workspace only requires installing the pod dependencies:
$ pod install
After that, open PIATunnel.xcworkspace
in Xcode and run the unit tests found in the PIATunnelTests
target. A simple CMD+U while on PIATunnel-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 rather than a PIA server, modify the file Demo/BasicTunnel-[iOS|macOS]/ViewController.swift
and make sure to:
- Replace
.pia
with.vanilla
inbuilder.endpointProtocols
. - Set
builder.handshake
to.custom
. - Set
builder.ca
to the PEM formatted certificate of your VPN server's CA.
Example:
builder.endpointProtocols = [PIATunnelProvider.EndpointProtocol(.udp, 1194, .vanilla)]
builder.handshake = .custom
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 PIATunnelProvider
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) here.
For more details please see CONTRIBUTING.
Issues and Pull Requests should use these templates: ISSUE and PULL REQUEST.
Authors
- Davide De Rosa - keeshux
- Steve
License
This project is licensed under the MIT (Expat) license, which can be found here.
Acknowledgements
- SwiftyBeaver - © 2015 Sebastian Kreutzberger
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.