passepartout-apple/README.md

<p style="text-align: center; padding: 0em 1em"><img src="res/logo.svg" width="300" height="300" /></p>

# [Passepartout][about-website]

![iOS 11+](https://img.shields.io/badge/ios-11+-green.svg)
[![TunnelKit 1.5.x](https://img.shields.io/badge/tunnelkit-1.5-d69c68.svg)][dep-tunnelkit]
[![License GPLv3](https://img.shields.io/badge/license-GPLv3-lightgray.svg)](LICENSE)
[![Join Reddit](https://img.shields.io/badge/discuss-Reddit-orange.svg)][about-reddit]
[![Join Telegram](https://img.shields.io/badge/chat-Telegram-blue.svg)][about-telegram]
[![Tweet](https://img.shields.io/twitter/url/http/shields.io.svg?style=social)](https://twitter.com/intent/tweet?url=https%3A%2F%2Fpassepartoutvpn.app%2F&via=keeshux&text=Passepartout%20is%20an%20user-friendly%2C%20open%20source%20%23OpenVPN%20client%20for%20%23iOS%20and%20%23macOS)
 
Passepartout is a non-official, user-friendly [OpenVPN®][openvpn] client for iOS.

## Beta

Passepartout betas are available for patrons on TestFlight.

<a href="https://www.patreon.com/keeshux"><img src="https://c5.patreon.com/external/logo/become_a_patron_button@2x.png" width="160"></a>

## Overview

### All profiles in one place

Passepartout lets you handle multiple profiles in one single place and quickly switch between them.

[<img src="res/snap-home.png" width="300">](res/snap-home.png)

### Ease of use

With its native look & feel, Passepartout focuses on ease of use. It does so by stripping the .ovpn flags that are today obsolete or rarely used. With good approximation, it mimics the most relevant features you will find in OpenVPN 2.4.x.

[<img src="res/snap-profile.png" width="300">](res/snap-profile.png)

### Trusted networks

Trust cellular or Wi-Fi networks to fine-grain your connectivity. You can then choose to retain a VPN connection when entering a trusted network, or prevent it completely.

[<img src="res/snap-trusted.png" width="300">](res/snap-trusted.png)

### See your connection parameters

Passepartout strives for transparency, by showing a fairly detailed yet understandable resume of your connection parameters.

[<img src="res/snap-parameters.png" width="300">](res/snap-parameters.png)

### Disconnect on sleep

Keeping the VPN active in the background provides smoother operation, but may be tough for the battery. You might want to use this feature if you're concerned about battery life. When the device goes to sleep, the VPN will disconnect to then reconnect on device wake-up.

### No unrequested activity

Passepartout is a VPN client and does absolutely nothing else without your consent. The providers infrastructures are obtained via a [static GitHub API][app-api] if and only if you manually refresh them.

### Presets for major providers

Passepartout can connect to a few well-known VPN providers with an existing account:

- [Private Internet Access][app-net-pia]
- [TunnelBear][app-net-tunnelbear]
- ...more soon!

In preset mode, you can pick pre-resolved IPv4 endpoints when DNS is problematic.

### Import .ovpn profiles

Passepartout can import .ovpn configuration files. This way you can fine-tune encryption without tweaking and reimporting a new configuration. 

You can find details on what may or may not work in the related section of the [TunnelKit README][dep-tunnelkit-ovpn].

## Installation

### Requirements

- iOS 11.0+
- Xcode 10+ (Swift 4.2)
- Git (preinstalled with Xcode Command Line Tools)
- Ruby (preinstalled with macOS)
- [CocoaPods 1.6.0][dep-cocoapods]

It's highly recommended to use the Git and Ruby packages provided by [Homebrew][dep-brew].

### Testing

Download the app codebase locally:

    $ git clone https://github.com/passepartoutvpn/passepartout-ios.git

Assuming you have a [working CocoaPods environment][dep-cocoapods], setting up the app workspace only requires installing the pod dependencies:

    $ pod install

After that, open `Passepartout.xcworkspace` in Xcode and run the `Passepartout-iOS` target.

For the VPN to work properly, the app requires:

- _App Groups_ and _Keychain Sharing_ capabilities
- App IDs with _Packet Tunnel_ entitlements

both in the main app and the tunnel extension target.

## License

This project is licensed under the [GPLv3][license-content].

### Contributing

By contributing to this project you are agreeing to the terms stated in the [Contributor License Agreement (CLA)][contrib-cla]. For more details please see [CONTRIBUTING][contrib-readme].

## Credits

The logo is taken from the awesome Circle Icons set by Nick Roach.

- MBProgressHUD - © 2009-2016 Matej Bukovinski
- PIATunnel - © 2018-Present Private Internet Access
- SwiftGen - © 2018 SwiftGen
- SwiftyBeaver - © 2015 Sebastian Kreutzberger
- lzo - © 1996-2017 Markus F.X.J. Oberhumer

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

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

## Usage

You are strongly encouraged to read carefully both the [disclaimer][web-disclaimer] and [privacy policy][web-privacy] before using this software.

## Contacts

Twitter: [@keeshux][about-twitter]

Website: [passepartoutvpn.app][about-website]

[openvpn]: https://openvpn.net/index.php/open-source/overview.html

[app-api]: https://github.com/passepartoutvpn/passepartout-api
[app-net-pia]: https://www.privateinternetaccess.com/pages/buy-vpn/
[app-net-tunnelbear]: https://click.tunnelbear.com/aff_c?offer_id=2&aff_id=7464

[dep-cocoapods]: https://guides.cocoapods.org/using/getting-started.html
[dep-jazzy]: https://github.com/realm/jazzy
[dep-brew]: https://brew.sh/
[dep-tunnelkit]: https://github.com/keeshux/tunnelkit
[dep-tunnelkit-ovpn]: https://github.com/keeshux/tunnelkit#support-for-ovpn-configuration
[dep-openssl]: https://www.openssl.org/

[license-content]: LICENSE
[contrib-cla]: CLA.rst
[contrib-readme]: CONTRIBUTING.md

[web-disclaimer]: https://passepartoutvpn.app/disclaimer/
[web-privacy]: https://passepartoutvpn.app/privacy/

[about-twitter]: https://twitter.com/keeshux
[about-website]: https://passepartoutvpn.app
[about-patreon]: https://www.patreon.com/keeshux
[about-testflight]: https://testflight.apple.com/join/XHzgXj6m
[about-reddit]: https://www.reddit.com/r/passepartout
[about-telegram]: https://t.me/passepartoutvpn
Use .svg logo 2018-11-01 15:38:03 +00:00			`<p style="text-align: center; padding: 0em 1em"><img src="res/logo.svg" width="300" height="300" /></p>`
Add logo on top 2018-10-19 00:13:20 +00:00
Link header to website 2018-10-19 00:16:10 +00:00			`# [Passepartout][about-website]`
Initial commit 2018-10-11 07:13:19 +00:00
Add dependency badges 2018-10-19 00:16:37 +00:00			`![iOS 11+](https://img.shields.io/badge/ios-11+-green.svg)`
Use versioned TunnelKit 2019-03-20 17:00:14 +00:00			`[![TunnelKit 1.5.x](https://img.shields.io/badge/tunnelkit-1.5-d69c68.svg)][dep-tunnelkit]`
Add dependency badges 2018-10-19 00:16:37 +00:00			`[![License GPLv3](https://img.shields.io/badge/license-GPLv3-lightgray.svg)](LICENSE)`
Add TestFlight badge 2018-10-19 07:33:58 +00:00			`[![Join Reddit](https://img.shields.io/badge/discuss-Reddit-orange.svg)][about-reddit]`
			`[![Join Telegram](https://img.shields.io/badge/chat-Telegram-blue.svg)][about-telegram]`
Replace community links with badges 2018-10-19 00:18:06 +00:00			`[![Tweet](https://img.shields.io/twitter/url/http/shields.io.svg?style=social)](https://twitter.com/intent/tweet?url=https%3A%2F%2Fpassepartoutvpn.app%2F&via=keeshux&text=Passepartout%20is%20an%20user-friendly%2C%20open%20source%20%23OpenVPN%20client%20for%20%23iOS%20and%20%23macOS)`

Add dependency badges 2018-10-19 00:16:37 +00:00			`Passepartout is a non-official, user-friendly [OpenVPN®][openvpn] client for iOS.`
Initial commit 2018-10-11 07:13:19 +00:00
			`## Beta`

Drop disabled TestFlight public beta link 2019-02-28 16:34:07 +00:00			`Passepartout betas are available for patrons on TestFlight.`
Initial commit 2018-10-11 07:13:19 +00:00
Replace Donations with Patreon widget 2018-10-18 23:46:22 +00:00			`<a href="https://www.patreon.com/keeshux"><img src="https://c5.patreon.com/external/logo/become_a_patron_button@2x.png" width="160"></a>`

Initial commit 2018-10-11 07:13:19 +00:00			`## Overview`

			`### All profiles in one place`

			`Passepartout lets you handle multiple profiles in one single place and quickly switch between them.`

Resize screenshots in README 2018-10-14 23:29:30 +00:00			`[<img src="res/snap-home.png" width="300">](res/snap-home.png)`
Initial commit 2018-10-11 07:13:19 +00:00
			`### Ease of use`

			`With its native look & feel, Passepartout focuses on ease of use. It does so by stripping the .ovpn flags that are today obsolete or rarely used. With good approximation, it mimics the most relevant features you will find in OpenVPN 2.4.x.`

Resize screenshots in README 2018-10-14 23:29:30 +00:00			`[<img src="res/snap-profile.png" width="300">](res/snap-profile.png)`
Initial commit 2018-10-11 07:13:19 +00:00
			`### Trusted networks`

			`Trust cellular or Wi-Fi networks to fine-grain your connectivity. You can then choose to retain a VPN connection when entering a trusted network, or prevent it completely.`

Resize screenshots in README 2018-10-14 23:29:30 +00:00			`[<img src="res/snap-trusted.png" width="300">](res/snap-trusted.png)`
Initial commit 2018-10-11 07:13:19 +00:00
			`### See your connection parameters`

			`Passepartout strives for transparency, by showing a fairly detailed yet understandable resume of your connection parameters.`

Resize screenshots in README 2018-10-14 23:29:30 +00:00			`[<img src="res/snap-parameters.png" width="300">](res/snap-parameters.png)`
Initial commit 2018-10-11 07:13:19 +00:00
			`### Disconnect on sleep`

			`Keeping the VPN active in the background provides smoother operation, but may be tough for the battery. You might want to use this feature if you're concerned about battery life. When the device goes to sleep, the VPN will disconnect to then reconnect on device wake-up.`

			`### No unrequested activity`

Fix some wording in README 2018-10-28 08:02:25 +00:00			`Passepartout is a VPN client and does absolutely nothing else without your consent. The providers infrastructures are obtained via a [static GitHub API][app-api] if and only if you manually refresh them.`
Initial commit 2018-10-11 07:13:19 +00:00
			`### Presets for major providers`

			`Passepartout can connect to a few well-known VPN providers with an existing account:`

Replace self-hosted API with static GitHub Pages 2018-10-11 17:47:04 +00:00			`- [Private Internet Access][app-net-pia]`
Refine TunnelBear integration - Mention in README - Promo link 2019-03-07 20:37:04 +00:00			`- [TunnelBear][app-net-tunnelbear]`
Initial commit 2018-10-11 07:13:19 +00:00			`- ...more soon!`

			`In preset mode, you can pick pre-resolved IPv4 endpoints when DNS is problematic.`

			`### Import .ovpn profiles`

Move .ovpn parser to TunnelKit 2018-11-10 09:29:51 +00:00			`Passepartout can import .ovpn configuration files. This way you can fine-tune encryption without tweaking and reimporting a new configuration.`
Initial commit 2018-10-11 07:13:19 +00:00
Move .ovpn parser to TunnelKit 2018-11-10 09:29:51 +00:00			`You can find details on what may or may not work in the related section of the [TunnelKit README][dep-tunnelkit-ovpn].`
Initial commit 2018-10-11 07:13:19 +00:00
			`## Installation`

			`### Requirements`

			`- iOS 11.0+`
			`- Xcode 10+ (Swift 4.2)`
			`- Git (preinstalled with Xcode Command Line Tools)`
			`- Ruby (preinstalled with macOS)`
Work around TunnelKit/OpenSSL linking issue 2019-02-25 21:56:24 +00:00			`- [CocoaPods 1.6.0][dep-cocoapods]`
Initial commit 2018-10-11 07:13:19 +00:00
			`It's highly recommended to use the Git and Ruby packages provided by [Homebrew][dep-brew].`

			`### Testing`

			`Download the app codebase locally:`

Update GitHub URLs in README 2018-11-07 22:42:09 +00:00			`$ git clone https://github.com/passepartoutvpn/passepartout-ios.git`
Initial commit 2018-10-11 07:13:19 +00:00
			`Assuming you have a [working CocoaPods environment][dep-cocoapods], setting up the app workspace only requires installing the pod dependencies:`

			`$ pod install`

			After that, open `Passepartout.xcworkspace` in Xcode and run the `Passepartout-iOS` target.

			`For the VPN to work properly, the app requires:`

			`- _App Groups_ and _Keychain Sharing_ capabilities`
			`- App IDs with _Packet Tunnel_ entitlements`

			`both in the main app and the tunnel extension target.`

			`## License`

			`This project is licensed under the [GPLv3][license-content].`

			`### Contributing`

			`By contributing to this project you are agreeing to the terms stated in the [Contributor License Agreement (CLA)][contrib-cla]. For more details please see [CONTRIBUTING][contrib-readme].`

			`## Credits`

			`The logo is taken from the awesome Circle Icons set by Nick Roach.`

Add SwiftGen to credits 2018-11-26 15:17:45 +00:00			`- MBProgressHUD - © 2009-2016 Matej Bukovinski`
Add missing PIA credit in README 2018-11-01 14:35:26 +00:00			`- PIATunnel - © 2018-Present Private Internet Access`
Add SwiftGen to credits 2018-11-26 15:17:45 +00:00			`- SwiftGen - © 2018 SwiftGen`
Add missing credits 2018-10-11 07:47:40 +00:00			`- SwiftyBeaver - © 2015 Sebastian Kreutzberger`
Set beta release Add missing LZO credit. 2019-03-19 14:24:34 +00:00			`- lzo - © 1996-2017 Markus F.X.J. Oberhumer`
Add missing credits 2018-10-11 07:47:40 +00:00
Add OpenSSL statement in README 2018-11-30 19:39:28 +00:00			`This product includes software developed by the OpenSSL Project for use in the OpenSSL Toolkit. ([https://www.openssl.org/][dep-openssl])`

Initial commit 2018-10-11 07:13:19 +00:00			`© 2002-2018 OpenVPN Inc. - OpenVPN is a registered trademark of OpenVPN Inc.`

Make web the unique source for legal statements 2018-11-01 12:49:42 +00:00			`## Usage`
Initial commit 2018-10-11 07:13:19 +00:00
Make web the unique source for legal statements 2018-11-01 12:49:42 +00:00			`You are strongly encouraged to read carefully both the [disclaimer][web-disclaimer] and [privacy policy][web-privacy] before using this software.`
Initial commit 2018-10-11 07:13:19 +00:00
			`## Contacts`

			`Twitter: [@keeshux][about-twitter]`

			`Website: [passepartoutvpn.app][about-website]`

			`[openvpn]: https://openvpn.net/index.php/open-source/overview.html`

Update GitHub URLs in README 2018-11-07 22:42:09 +00:00			`[app-api]: https://github.com/passepartoutvpn/passepartout-api`
Refine TunnelBear integration - Mention in README - Promo link 2019-03-07 20:37:04 +00:00			`[app-net-pia]: https://www.privateinternetaccess.com/pages/buy-vpn/`
			`[app-net-tunnelbear]: https://click.tunnelbear.com/aff_c?offer_id=2&aff_id=7464`
Initial commit 2018-10-11 07:13:19 +00:00
			`[dep-cocoapods]: https://guides.cocoapods.org/using/getting-started.html`
			`[dep-jazzy]: https://github.com/realm/jazzy`
			`[dep-brew]: https://brew.sh/`
			`[dep-tunnelkit]: https://github.com/keeshux/tunnelkit`
Move .ovpn parser to TunnelKit 2018-11-10 09:29:51 +00:00			`[dep-tunnelkit-ovpn]: https://github.com/keeshux/tunnelkit#support-for-ovpn-configuration`
Initial commit 2018-10-11 07:13:19 +00:00			`[dep-openssl]: https://www.openssl.org/`

			`[license-content]: LICENSE`
			`[contrib-cla]: CLA.rst`
			`[contrib-readme]: CONTRIBUTING.md`

Make web the unique source for legal statements 2018-11-01 12:49:42 +00:00			`[web-disclaimer]: https://passepartoutvpn.app/disclaimer/`
			`[web-privacy]: https://passepartoutvpn.app/privacy/`

Initial commit 2018-10-11 07:13:19 +00:00			`[about-twitter]: https://twitter.com/keeshux`
			`[about-website]: https://passepartoutvpn.app`
Update donations to Patreon 2018-10-13 13:28:19 +00:00			`[about-patreon]: https://www.patreon.com/keeshux`
Initial commit 2018-10-11 07:13:19 +00:00			`[about-testflight]: https://testflight.apple.com/join/XHzgXj6m`
Add support venues to README 2018-10-18 23:29:11 +00:00			`[about-reddit]: https://www.reddit.com/r/passepartout`
			`[about-telegram]: https://t.me/passepartoutvpn`