OpenVPN Connect iOS FAQ

Some common errors and solutions

error parsing certificate : X509 - The date tag or value is invalid This is not a bug in OpenVPN but is because of a faulty certificate. See this detailed forum post for more info. certificate verification failed : x509 - certificate verification failed, e.g. crl, ca or signature check failed This is an error that tells you that the certificate could not be verified properly. This can occur for example if you are using an MD5 signed certificate. With such a type of certificate, the security level is so low, that the authenticity of the certificate simply cannot by any reasonable means be assured. In other words, it could very well be a fake certificate. The solution is to use a certificate not signed with MD5, but with SHA256 or better. You can find more information in the MD5 signature algorithm support section. digest_error: NONE: not usable This can occur if you specify auth none and also tls-auth in your client profile. This occurs because tls-auth needs an auth digest, but none was specified. There's a straightforward fix: just remove the tls-auth directive, since it can't be enabled anyway unless you have anything other but 'none' in the auth directive. SSL - Processing of the ServerKeyExchange handshake message failed There's a good chance this may be related to using older versions of OpenVPN/OpenSSL on the server side. Some users have solved this issue by updating their OpenVPN and/or OpenSSL software on the server side. BIO read tls_read_plaintext error: error:1408A0C1:SSL routines:SSL3_GET_CLIENT_HELLO:no shared cipher This is usually remedied by going to the OpenVPN Preferences menu and selecting "Force AES-CBC ciphersuites". Also, makes sure you are not using EC certificates as they are not yet supported.

MD5 signature algorithm support

It has been known for a very long time (since 2005 or so) that using MD5 as an algorithm for signing a certificate is a bad idea. It has been shown that with, at the time standard home computer equipment, it took about 8 hours to falsify a certificate signed this way, and as such the identity of the server could be faked. This could lead to an MiTM attack which could lead to interception of traffic. Therefore, MD5 support has been around only to allow connections to older equipment. We discovered that when we tried to cut support in November of 2017 during a security and functionality upgrade of OpenVPN Connect for Android that a lot of people were still using devices that use MD5 signed certificates. This is extremely insecure. It is recommended that any installations that still use MD5 signed certificates are converted to a setup with SHA256 signed certificates, or better. If the device you are using does not offer you the option to do so, then you should try updating the device to add this function if possible, or replace the device with a solution that does support it. We have therefore decided to implement a transitional period in which we will still allow MD5 signed certificates to function, until May 2018, when we will start cutting support for MD5 out of OpenVPN entirely. You should plan accordingly. We have a list of deprecated options and ciphers here: https://community.openvpn.net/openvpn/wiki/DeprecatedOptions To learn why MD5 signatures are bad, see these articles:

To determine if you are using an MD5 type certificate now using openssl as testing tool:

openssl x509 -in ca.crt -noout -text | grep "Signature Algorithm"

Example result if certificate is using MD5:

Signature Algorithm: md5WithRSAEncryption

If you see this result on the CA certificate or client certificate, then you must convert to a new and properly secure signed certificate set that uses at least SHA256 or better. For our OpenVPN Access Server users, it is good to know that we do not use MD5 certificate signatures at all in Access Server. For open source OpenVPN users, or users that have a third-party device that includes OpenVPN functionality, and you discover you have MD5 type certificates, you should investigate the option to update the software on your device, or to change the signature algorithm type, if possible. If it is not possible, you could try contacting the manufacturer of your device to see if they still support your device, and if they can create a means by which to replace the certificates with a properly secure type certificate. The default settings of a program like EasyRSA 3, which is used by open source OpenVPN for generating client certificates and keys, are pretty secure and will generate certificate that are not signed with MD5.

When I go to the OpenVPN section of the Settings app, the settings have vanished.

The vanishing settings appear to be a known iOS issue. A suggested workaround is to "quit Settings by double-tapping the home button, and then dragging Settings out of the list of apps. The next time you launch Settings, your app's settings ought to show up."

I am getting the error "mbedTLS: error parsing cert certificate : X509 - The date tag or value is invalid"

This is not a bug in OpenVPN or mbedTLS but is actually caused by incorrectly formatted certificates. See this detailed forum post for more info. From version 1.1.1 the format check has been relaxed to accept also those certificates that were previously rejected with this error.

I am getting the error "Client exception in transport_recv_excode: mbedTLS: SSL read error : SSL - Processing of the ServerKeyExchange handshake message failed".

This may be related to using older versions of OpenVPN/OpenSSL on the server side. Some users have solved this issue by updating their OpenVPN server-side software and/or OpenSSL.

I cannot connect to the server (client times out), and the server log file shows "TLS_ERROR: BIO read tls_read_plaintext error: error:1408A0C1:SSL routines:SSL3_GET_CLIENT_HELLO:no shared cipher".

This is usually remedied by going to the OpenVPN section of the iOS Settings app and selecting "Force AES-CBC ciphersuites". Another reason why this may happen is that you are using EC (Ecliptic Cryptography) certificates. OpenVPN Connect does not support the ECDSA algorithm at the moment, therefore those kind of certificates can't be used.

I am getting the error "digest_error: NONE: not usable"

This can occur if you specify auth none and also tls-auth in your client profile. This occurs because tls-auth needs an auth digest, but none was specified. There's a straightforward fix: just remove the tls-auth directive, since it can't be enabled anyway unless you have a non-none auth directive.

Can OpenVPN profiles be connected from the Settings App?

A: Yes, starting with iOS 8. Note that, if you are using 1.2.5 or older, only autologin profiles (i.e. profiles that don't require credential entry) can be launched using this mechanism. Starting with version 1.2.6, also profiles using a PKCS#12 bundle stored in the iOS keychain can be connected from the Settings.

Is OpenVPN Connect for iOS vulnerable to Heartbleed?

A: No, all versions of OpenVPN Connect for iOS use the mbedTLS library, which is immune to Heartbleed.

Does OpenVPN Connect support the tls-crypt option?

A: Yes, OpenVPN Connect supports the tls-crypt option starting with version 1.2.5

Are CRLs (certificate revocation lists) supported?

A: Yes, CRLs are supported starting with version 1.0.5 for iOS. To use a CRL, it must be added to the .ovpn profile, such as:

<crl-verify>
 -----BEGIN X509 CRL-----
 MIHxMFwwDQYJKoZIhvcNAQEEBQAwFTETMBEGA1UEAxMKT3BlblZQTiBDQRcNMTQw
 NDIyMDQzOTI3WhcNMjQwNDE5MDQzOTI3WjAWMBQCAQEYDzIwMTQwNDIyMDQzOTI3
 WjANBgkqhkiG9w0BAQQFAAOBgQBQXzbNjXkx8+/TeG8qbFQD5wd6wOTe8HnypQTt
 eELsI7eyNtiRRhJD3qKfawPVUabSijnwhAPHfhoIOLKe67RLfzOwAsFKPNJAVdmq
 rYw1t2eucHvGjH8PnTh0aJPJaI67jmNbSI4CnHNcRgZ+1ow1GS+RAK7kotS+dZz9
 0tc7Qw==
 -----END X509 CRL-----
 </crl-verify>

Multiple CRLs may be concatenated together within the crl-verify block above. If you are importing a .ovpn file using iTunes that references an external CRL file such as

crl-verify crl.pem

make sure to drop the file crl.pem into the same place as the .ovpn file during import, so the profile parser can access it.

I am having trouble importing my .ovpn file.

A: Here are some basic pointers for importing .ovpn files:

Recent versions of iTunes hide the left sidebar where tethered iOS devices are shown. To fix, go to View / Show Sidebar.
When you import a .ovpn file using iTunes, make sure that all files referenced by the .ovpn file such as ca, cert, and key files are dropped at the same time into the iTunes file sharing window for the OpenVPN app.
Profiles must be UTF-8 (or ASCII) and under 256 KB in size.
Consider using the unified format for OpenVPN profiles which allows all certs and keys to be embedded into the .ovpn file. This eases management of the OpenVPN configuration because it integrates all elements of the configuration into a single file.For example, a traditional OpenVPN profile might specify certs and keys as follows:
```
ca ca.crt
cert client.crt
key client.key
tls-auth ta.key 1
```
You can convert this usage to unified form by pasting the content of the certificate and key files directly into the OpenVPN profile as follows using an XML-like syntax:
```
<ca>
-----BEGIN CERTIFICATE-----
MIIBszCCARygAwIBAgIE...
. . .
/NygscQs1bxBSZ0X3KRk...
Lq9iNBNgWg==
-----END CERTIFICATE-----
</ca>
```
```
<cert>
-----BEGIN CERTIFICATE-----
. . .
</cert>
```
```
<key>
-----BEGIN RSA PRIVATE KEY-----
. . .
</key>
```
```
key-direction 1
<tls-auth>
-----BEGIN OpenVPN Static key V1-----
. . .
</tls-auth>
```
Another approach to eliminate certificates and keys from the OpenVPN profile is to use the iOS Keychain as described below. NOTE: when converting tls-auth to unified format, check if there is a second parameter after the filename (usually a 0 or 1). This parameter is known as the key-direction parameter and must be specified as a standalone directive when tls-auth is converted to unified format. For example if the parameter is 1, add this line to the profile:
```
key-direction 1
```
If there is no second parameter to tls-auth, you must add this line to the profile:
```
key-direction bidirectional
```

My profile that worked fine in 1.0.0 stopped working in 1.0.1 or higher, causing "TLS Error: incoming packet authentication failed from [....]" errors on the server. How to fix?

A: In 1.0.1, the default value for the key-direction directive was changed to "bidirectional" for compatibility with the OpenVPN 2.x branch (in 1.0.0, the default was "1"). In general, profiles imported before upgrading should continue to work, because the previous default is retained for such profiles, however if you are importing a new profile in unified format, be sure to follow the updated FAQ entry above for setting the key-direction directive. Also note that for iOS VPN-on-Demand profiles, it is necessary to specify the key-direction as a key-value setting, if it is "0" or "1". This could potentially cause breakage in VPN-on-Demand profiles previously imported with 1.0.0 if they don't declare a key-direction key/value pair on the assumption that it defaults to "1". The solution is to explicitly declare key-direction in VPN-on-Demand profiles if the OpenVPN configuration file they are derived from declares it as well.

Where are the support forums for OpenVPN Connect?

A: https://forums.openvpn.net/

Is IPv6 supported?

A: Yes. The OpenVPN app supports IPv6 transport and IPv6 tunnels as long as the server supports them as well.

How to make IPv6 routing work on iOS 7?

There is a known issue where IPv6 tunnel routes may not be added to the routing table on iOS 7.0.x. This issue was fixed in iOS 7.1 Workaround: use redirect-gateway instead of pushing specific IPv6 routes. For example, in the server configuration file:

push "redirect-gateway ipv6"

Or the client configuration file:

redirect-gateway ipv6

Note that iOS 7 and higher requires that if redirect-gateway is used, that it is used for both IPv4 and IPv6 as the above directive accomplishes.

Why does the VPN disconnect when I make or receive a voice call?

A: Some cellular networks are incapable of maintaining a data connection during a voice call. If iOS detects this as a loss of network connectivity, the VPN should enter a pause state during the duration of the call, and automatically resume after the call is complete. However if the loss of data connectivity isn't detected by iOS, the VPN connection may time out and disconnect.

Given that mobile devices are easily lost or stolen, how best to secure VPN profiles against compromise if the device falls into the wrong hands?

A: The most sensitive piece of data in a profile is the private key. Consider removing the client certificate and private key from the profile and save them in the device Keychain instead (this is discussed below).
Use a strong device-level password. This is critical to protect data stored in the device Keychain.

Is it safe to save passwords?

A: Yes, if you have set up a strong device-level password. The app stores authentication and private key passwords in the iOS Keychain, which in turn is protected by the device-level password. Note that the iOS Keychain is accessible by the app only after the user has unlocked the device at least once after restart. For this reason a profile requiring a password to connect won't be able to do so automatically after restart.

After updating my app the certificate list is empty! Why?

A: Starting with OpenVPN Connect v1.2.5, the app has restricted access to the iOS keychain. This is a policy enforced by Apple in order to improve security and avoid a generic app to access unauthorized key/certificates. For this reason PKCS#12 bundles have to be re-imported by OpenVPN Connect directly. Please refer to the FAQ "How do I use a client certificate and private key from the iOS Keychain?" for detailed instructions about how to do so.

Why is the save password switch sometimes disabled?

A: The save password switch on the authentication password field is normally enabled, but can be disabled by the following:

The following OpenVPN directive, if present in a profile, will disable the password save switch:
```
setenv ALLOW_PASSWORD_SAVE 0
```
Note however that the above directive only applies to the authentication password. The private key password, if it exists, can always be saved.

If my OpenVPN profile uses redirect-gateway, does that guarantee that all of my network traffic will be routed through the VPN tunnel?

A: Yes, but with some important exceptions:

Many Apple services such as Push Notifications and FaceTime are never routed through the VPN tunnel, as per Apple policy.
During pause, resume, and reconnect states (for example when transitioning between WiFi and Cellular data), the VPN tunnel may temporarily disengage, allowing network traffic to bypass the tunnel and route directly to the internet. If you are running iOS 8 or higher, consider enabling the Seamless Tunnel Setting in the OpenVPN section of the Settings App. It will make a best-effort to keep the tunnel active during pause, resume, and reconnect states to prevent packet leakage to the internet.

How to make the app work with profiles that lack a client certificate/key?

A: If you have a profile that connects to a server without a client certificate/key, you will need to add the following directive to your profile:

setenv CLIENT_CERT 0

This is necessary to resolve an ambiguity when the profile contains no client certificate or key, because otherwise the client app can't know whether an external certificate/key pair should be obtained from the iOS Keychain, or whether the server actually doesn't require a client certificate/key (for example if the server is configured with the client-cert-not-required directive). The option is given as a "setenv" to avoid breaking other OpenVPN clients that might not recognize it.

Why doesn't the app support tap-style tunnels?

A: The iOS VPN API supports only tun-style tunnels at the moment. This is a limitation of the iOS platform. If you try to connect a profile that uses a tap-based tunnel, you will get an error that only layer 3 tunnels are currently supported.

Are there any OpenVPN directives not supported by the app?

A: While most OpenVPN client directives are supported by the app, we have made an effort to reduce bloat and improve maintainability by eliminating what we believe to be obsolete or rarely-used directives. Please email us at ios@openvpn.net if you believe that a specific directive that is not included should be reconsidered for inclusion. Here is a partial list of directives not currently supported:

dev tap — This directive is not supported because the underlying iOS VPN API doesn't support tap-style tunnels.
fragment — The fragment directive is not supported due to the complexity it adds to the OpenVPN implementation and the fact that it is usually better to leave fragmentation up to the lower-level transport protocols. Note as well that the client does not support connecting to a server that uses the fragment directive.
mssfix — This directive will be added in a future release. Since the functionality of mssfix can be achieved on either the client or server side, specifying it on the server side will enable it even if the client doesn't support the directive.
secret — Static key encryption mode (non-TLS) is not supported.
socks-proxy — Socks proxy support is currently not supported.
Ciphers other than AES, Blowfish, and DES family — Currently, only AES, Blowfish, and DES family ciphers are supported. This is done to reduce bloat and improve energy efficiency. The AES cipher algorithm, in particular, is well-suited for the ARM processor generally used in iOS devices.
proxy directives — While proxy directives are currently supported (http-proxy and http-proxy-option), they are currently NOT supported in <connection> profiles.

Additional not supported options can be seen in the connection log under the section "UNUSED OPTIONS", where OpenVPN Connect will print all those directives specified in the profile that are not used by the app.

Can I have multiple profiles?

A: Yes, you can import any number of profiles using iTunes, Safari, or Mail as described in the previous help page. Keep in mind that OpenVPN will assign a name to a profile based on the server that the profile connects to. You can always change the name by renaming it after import. Touch the Profile row to select, rename, or delete a specific profile.

How do I delete a profile?

A: Touch the Profile row to bring up the Select Profile page. Touch the Delete link in the upper-right corner. This will cause red "-" icons to appear to the left of all profiles. Touch the "-" icon to actually delete a profile.

How do I rename a profile?

A: Touch the Profile row to bring up the Select Profile page, then select the profile you wish to rename by touching it. Touch the Rename link in the upper-right corner. This will cause the profile name to become editable. Pressing "Done" on the soft keyboard will save the change.

How do I configure OpenVPN to connect via an HTTP proxy?

A: Go to the Settings App and select OpenVPN in the left pane. All proxy options are available here. Proxy options can also be specified in the OpenVPN profile itself using the http-proxy and http-proxy-option directives.

How do I use a client certificate and private key from the iOS Keychain?

A: Using the iOS keychain to store your private key has the added security advantage of leveraging on the hardware-backed keystores that exist on many iOS devices, allowing the key to be protected by the iOS-level device password, and preventing key compromise even if the device is rooted. If you already have your client certificate and private key bundled into a PKCS#12 file (extension .p12 or .pfx), you can import it into the app private section of the iOS Keychain using Mail, Safari or iTunes. Note sure that the file extension has to be changed to .ovpn12 for the file to be picked up by the OpenVPN Connect App (and not by iOS). Note that on iOS, when you import a PKCS#12 file into the Keychain, only the client certificate and private key are imported. The CA (certificate authority) certificates are NOT imported (unless you manually extract the CA certificates and import them separately, one-at-a-time). Therefore, the CA list must be given in the profile using the ca directive. If you already have a PKCS#12 file, the CA list may be extracted from the file using this openssl command, where the CA certs in client.p12 are written to ca.crt:

openssl pkcs12 -in client.p12 -cacerts -nokeys -out ca.crt

Then add a reference to ca.crt to your profile:

ca ca.crt

or paste the contents of ca.crt directly into your profile:

<ca>
paste contents of ca.crt here
</ca>

If you don't have a PKCS#12 file, you can convert your certificate and key files into PKCS#12 form using this openssl command (where cert, key, and ca are your client certificate, client key, and root CA files).

openssl pkcs12 -export -in cert -inkey key -certfile ca -name MyClient -out client.ovpn12

Then import the client.ovpn12 file from the previous step into the app using Mail or Safari. Once this is done, remove the cert and key directives from your .ovpn file and re-import it, making sure that the ca directive remains. Once imported, any profile that lacks cert and key directives will cause a Certificate row to appear on the main view, allowing the profile to be linked with an Identity from the iOS Keychain (on iOS, an Identity refers to a certificate/private-key pair that was previously imported using a PKCS#12 file). Touch the Certificate row and select the MyClient certificate. At this point, you should be able to connect normally. Note that the iOS Keychain is accessible by the app only after the user has unlocked the device at least once after restart. For this reason a profile requiring a certificate stored in the Keychain to connect won't be able to do so automatically after restart. This is a security measure to prevent an unknown person to access a VPN network using a device that was previously switched off.

How do I delete an imported PKCS#12 file?

Starting with 1.2.6 PKCS#12 files are now imported in the iOS keychain as OpenVPN Connect specific key material. For this reason they are not visible in the iOS Settings. To delete an imported PKCS#12 file touch Manage Certificates (or Certs on iPhones/iPods) at the top of the main app screen and then touch Delete. This will cause red "-" icons to appear to the left of all PKCS#12 files. Touch the "-" icon to actually delete a file.

When I try to import a PKCS#12 file, why am I being asked for a password?

A: When you generate a PKCS#12 file, you will always be asked for an "export password" to encrypt the file. This password must again be presented when the PKCS#12 file is imported into the iOS Keychain. This is to prevent interception and recovery of the private key during transport.

When I try to import a PKCS#12 file, why am I being asked for a password even if I haven't set any?

A: When you import a PKCS#12 a password must always be specified. If you have set an empty password, just tap OK without entering any text.

Why doesn't the PKCS#12 file in my OpenVPN configuration file work the same as on desktop systems?

A: PKCS#12 files on iOS are used somewhat differently than on desktop versions of OpenVPN. In desktop versions, PKCS#12 files can be bundled or referenced in the OpenVPN profile. On iOS, however, PKCS#12 management is built into the iOS Keychain. This approach is much better from a security perspective, because the Keychain can then leverage on hardware features in the device such as hardware-backed keystores. However, it does require that the PKCS#12 file is loaded into the iOS Keychain as a separate step from importing the OpenVPN profile. It also moves the responsibility for managing PKCS#12 files to the iOS Keychain, and away from OpenVPN, so it can potentially introduce compatibility issues. To use a PKCS#12 file on iOS, see the FAQ item above: How do I use a client certificate and private key from the iOS Keychain?

After importing my PKCS#12 file into the iOS Keychain, I am getting an error when I try to connect: "mbedTLS: ca certificate is undefined"

A: This error can occur if you don't include a ca directive in your profile, since the iOS Keychain does not provide the CA list from the PKCS#12 file to OpenVPN. The solution is to extract the CA list from the PKCS#12 file and add it to your profile via the ca directive. This is discussed in detail in the FAQ item above: How do I use a client certificate and private key from the iOS Keychain?

Can an OpenVPN server push proxy settings to an iOS device?

A: Yes. An OpenVPN server can push HTTP and HTTPS proxy settings to an iOS client such that these settings will be used by Safari (or other iOS browsers) during the duration of the VPN session. For example, suppose that you are managing an OpenVPN Server and want iOS clients, after they connect, to use an HTTP/HTTPS proxy at 10.144.5.14 port 3128. You could add the following directives to the OpenVPN server-side configuration to push these settings to clients:

push "dhcp-option PROXY_HTTP 10.144.5.14 3128"
push "dhcp-option PROXY_HTTPS 10.144.5.14 3128"

Suppose also that you want several web domains to connect directly (example1.tld, example2.tld, and example3.tld), without going through the proxy:

push "dhcp-option PROXY_BYPASS example1.tld example2.tld example3.tld"

If your site uses a Proxy Autoconfiguration URL, you can specify the URL as follows:

push "dhcp-option PROXY_AUTO_CONFIG_URL http://example.tld/proxy.pac"

If you don't want to (or can't) modify the OpenVPN server configuration, you can also add proxy directives directly to the client .ovpn profile, by simply removing the enclosing push "..." from the directive:

dhcp-option PROXY_HTTP 10.144.5.14 3128
dhcp-option PROXY_HTTPS 10.144.5.14 3128

In some cases, if you push proxy options, it may also be necessary to push a DNS server address as well:

push "dhcp-option DNS 1.2.3.4"

Note that this feature controls application proxy use over the VPN tunnel and is not related to the connection proxy capability of OpenVPN to connect to a server through an HTTP proxy. The connection proxy capability is a separate feature that is accessed through the Settings App under OpenVPN or by using the http-proxy and http-proxy-option directives.

How does iOS interpret pushed DNS servers and search domains?

A: On a split-tunnel, where redirect-gateway is not pushed by the server, and at least one pushed DNS server is present:

route all DNS requests through pushed DNS server(s) if no added search domains.
route DNS requests for added search domains only, if at least one added search domain.

For example, the following directive on the server will tell the client to route all DNS requests to 172.16.0.23:

push "dhcp-option DNS 172.16.0.23"

while these directives on the server will only route foo.tld and bar.tld DNS requests to 172.16.0.23:

push "dhcp-option DNS 172.16.0.23"
push "dhcp-option DOMAIN foo.tld"
push "dhcp-option DOMAIN bar.tld"

Note that with redirect-gateway, the above discussion is moot, since all DNS requests are always routed through the VPN regardless of the presence or absence of added search domains.

Can I push IPv6 DNS servers to my clients?

A: Yes, you can push an IPv6 DNS by using the same format used for IPv4 ones. For Example:

push "dhcp-option DNS 2001:abde::1"

How do I set my own local domain for automatic resolution?

A: when trying to resolve a PQDN (Partly Qualified Domain Name), the iOS DNS subsystem first tries to solve the hostname as provided and, in case of failure, concatenates it with the system domain prefix (normally assigned by your uplink gateway, for example: ".lan"). In order to specify a different domain to append, the server can push a special directive including the new name:

push "dhcp-option ADAPTER_DOMAIN_PREFIX foo.tld"

Note that this can work only when redirect-gateway or a VPN specific DNS has been configured. See the previous FAQ "How does iOS interpret pushed DNS servers and search domains?" to learn how to specify a DNS.

How do I set up my profile for server failover?

A: You can provide OpenVPN with a list of servers to connect to. On connection failure, OpenVPN will rotate through the list until it finds a responsive server. For example, the following entries in the profile will first try to connect to server A via UDP port 1194, then TCP port 443, then repeat the process with server B. OpenVPN will continue to retry until it successfully connects or hits the Connection Timeout, which can be configured in the Preferences.

remote server-a.example.tld 1194 udp
remote server-a.example.tld 443 tcp
remote server-b.example.tld 1194 udp
remote server-b.example.tld 443 tcp

What is the meaning of the various OpenVPN settings in the iOS Settings App?

UI Settings

Raise Keyboard — When ON, the app will try to raise the iOS soft keyboard whenever an input field is selected.

Connection Settings

Seamless tunnel (requires iOS 8 or higher) — Make a best-effort to keep the tunnel active during pause, resume, and reconnect states. Typically, during VPN pause, resume, or reconnect (for example when transitioning between WiFi and Cellular data), the VPN tunnel may disengage for a short period of time, normally on the order of seconds or less. During this time, network traffic can potentially bypass the tunnel and route directly to the internet. This option can reduce the incidence of packet leakage by keeping the tunnel continuously engaged until it is manually disconnected, even across sleep/wakeup or network reconfiguration events. Consider also enabling the Layer 2 reachability setting (below) when using Seamless Tunnel.
Connect via — Connect to the VPN server by WiFi, Cellular Data, or either.
Reconnect on wakeup — Automatically reconnect a VPN profile if it was active prior to device sleep.
Protocol — Force a particular transport protocol (UDP or TCP).
Compression — Select tunnel compression options.
Connection timeout — How long should OpenVPN try to connect before giving up? If set to None, OpenVPN will retry indefinitely.
Network state detection — How should OpenVPN handle network state changes or network reconfiguration events where the network comes up, goes down, or transitions between WiFi and Cellular data?
- Active (default) : When connected, always attempt to reconnect after network reconfiguration events.
- Lazy : When connected, attempt to preserve existing connection during network reconfiguration events.
- Disabled : Don't consider network state when initially connecting, and don't use network state changes to trigger pause/reconnect/disconnect behaviour.

Advanced Settings

Force AES-CBC ciphersuites — When ON, the connection MUST use one of the following two ciphersuites:
- TLS_DHE_RSA_WITH_AES_256_CBC_SHA, or
- TLS_DHE_RSA_WITH_AES_128_CBC_SHA
When OFF, no specific ciphersuites are forced.
Minimum TLS version — Set the minimum TLS version. If a specific TLS version is selected it will override any profile setting. If Profile Default is selected, the app will use the tls-version-min profile directive if it exists, or TLS 1.0 otherwise. If Disabled is selected AND Force AES-CBC ciphersuites (above) is enabled, the app will NOT require a minimum TLS version from the server, which means that the SSL version negotiated could be as low as SSL 3.
Google DNS fallback — If ON, use Google DNS servers (8.8.8.8 and 8.8.4.4) as a fallback for connections that route all internet traffic through the VPN tunnel but don't define any VPN DNS servers.
Layer 2 reachability — If ON, and if Seamless Tunnel (above) is also ON, use a more robust test of network reachability when transitioning between WiFi and Cellular networks.

Proxy Settings and Credentials

Enable Proxy — When ON, connect to the VPN server via an HTTP proxy.
Host — HTTP proxy hostname or IP address.
Port — HTTP proxy port number.
Allow Basic auth — If ON, allow authentication methods that transmit the proxy password in cleartext.
Username — HTTP proxy username. OpenVPN supports NTLMv2, Digest, and Basic authentication.
Password — HTTP proxy password.

Can I import an OpenVPN profile via an iOS .mobileconfig file?

A: Yes, OpenVPN profiles can be created using the iPhone Configuration utility and exported to a .mobileconfig file, which in turn can be imported onto one or more iOS devices. Unfortunately, the process is a bit cumbersome at the moment because the directives of the OpenVPN profile must be manually entered as key/value pairs into the iPhone Configuration utility UI. To create a .mobileconfig-based profile, open the iPhone Configuration utility, go to the File menu, and select "New Configuration Profile" (note that these directions were tested with version 3.5 of the iPhone Configuration utility on a Mac tethered to an iPad Air running iOS 7.0.4). Next, edit the newly created Configuration Profile. Click on General in the left pane and fill out the fields such as Name, Identifier, Organization, etc. Click on VPN in the left pane and a "Configure VPN" dialog box should appear in the main window. Click the "Configure" button. Fill out the VPN settings as described below:

Connection Name should be set to a name that will identity this profile on the device.
Connection Type should be set to Custom SSL.
Identifier should be set to "net.openvpn.connect.app". (on older versions this used to be net.openvpn.OpenVPN-Connect.vpnplugin)
Server must be set to "DEFAULT". The actual server hostname will be configured via OpenVPN remote directives in the Custom Data section.
User Authentication should be set to Password, and the password field should be left blank.

Parameters normally given in the OpenVPN client configuration file must be defined using key/value pairs in the Custom Data section:

Define each OpenVPN directive as a key, with arguments specified as the value. As in the OpenVPN configuration file, arguments are space-delimited and may be quoted.
Key value pairs for remote, ca, cert, key, tls-auth, key-direction, auth-user-pass, comp-lzo, cipher, auth, ns-cert-type, remote-cert-tls must be defined if the server requires them.
If your server doesn't require clients to authenticate with a client certificate and private key, you can omit key/value pairs for ca and cert, but be sure to add the key/value pair "setenv" : "CLIENT_CERT 0".
The client certificate and private key can be separately imported onto the iOS device using a PKCS#12 file, in which case you can omit key/value pairs for ca and cert.
If you are attaching a private key to the configuration using the key directive, consider encrypting the key with a password to protect it while in transit to the target iOS device.
You must add a special key/value pair "vpn-on-demand" : "0" so that OpenVPN can distinguish this profile from an iOS VPN-On-Demand profile.
For OpenVPN directives with no arguments, use "NOARGS" as the value.
If multiple instances of the same directive are present, when entering the directive as a key, number the directives in the order they should be given to OpenVPN by appending .n to the directive, where n is an integer, such as remote.1 or remote.2
For multi-line directives such as ca, cert, key and tls-auth, where the argument is a multi-line file, an escaping model has been provided to allow the file content to be specified as a single-line value. The procedure is to convert the multi-line data to a single line by replacing line breaks with "\n" (without the quotes). Note that because of this escaping model, you must use "\\" to pass backslash itself.
For OpenVPN Access Server meta-directives such as "OVPN_ACCESS_SERVER_USERNAME", remove the OVPN_ACCESS_SERVER_ prefix, giving USERNAME as the directive.

Once the profile has been defined, you have two options for exporting it to an iOS device:

If your device is currently tethered, click on your device name in the left pane. Then in the main window, click on the Configuration Profiles tab. You should see the name of your Configuration Profile and a button to install it on the device.
You can also save the Configuration Profile as a .mobileconfig file, and make it available to iOS clients via email or the web. To do this, select your Configuration Profile, go to the File menu, and select "Export...". An Export Configuration Profile dialog box will appear. Select a Security option -- "Sign configuration profile" is a reasonable choice. Press the Export button and save the profile.

When an iOS device receives an OpenVPN .mobileconfig profile (via Mail attachment, Safari download, or pushed by the iPhone Configuration utility), it will raise a dialog box to facilitate import of the profile. After import, the profile will be visible in OpenVPN.

Can I use iOS 6+ VPN-On-Demand with OpenVPN?

A: Yes. VPN-On-Demand (VoD) is a new technology introduced by Apple in iOS 6 that allows a VPN profile to specify the conditions under which it will automatically connect. In addition, using a VoD profile on iOS 7 allows OpenVPN to be connected and disconnected using the iOS Settings App under the VPN tab (although note that on iOS 8 and higher, ordinary OpenVPN profiles can be connected using the Settings App, as long as they don't require credential entry). OpenVPN on iOS fully supports VoD, with the following features:

The iPhone Configuration Utility can be used to create an OpenVPN VoD profile by entering OpenVPN configuration file parameters as key/value pairs.
The OpenVPN app supports connect and disconnect actions triggered by the iOS VoD subsystem.
The OpenVPN app recognizes VoD profiles and will show them in the UI and allow them to be monitored and controlled like other OpenVPN profiles (with the exception that VoD profiles cannot be manually connected from the app UI, they can only be disconnected -- this is because a VoD profile is designed to be connected automatically by iOS).

OpenVPN VoD profiles can be created using the iPhone Configuration utility. Unfortunately, the process is a bit cumbersome at the moment because the directives of the OpenVPN profile must be manually entered as key/value pairs into the iPhone Configuration utility UI. For now, to create a VoD profile, open the iPhone Configuration utility (these directions were tested with version 3.5 on a Mac tethered to an iPad running iOS 6.0.1), go to the File menu, and select "New Configuration Profile". Next, edit the newly created Configuration Profile. Click on General in the left pane and fill out the fields such as Name, Identifier, Organization, etc. Click on VPN in the left pane and a "Configure VPN" dialog box should appear in the main window. Click the "Configure" button. Fill out the VPN settings as described below:

Connection Name should be set to a name that will identity this profile on the device.
Connection Type should be set to Custom SSL.
Identifier should be set to "net.openvpn.connect.app". (on older versions this used to be net.openvpn.OpenVPN-Connect.vpnplugin).
Server can be set to a hostname, or "DEFAULT" to use the hostname(s) from the OpenVPN configuration.
User Authentication should be set to Certificate, and the client certificate+key should be attached as a PKCS#12 file.
VPN On Demand should be enabled and match entries should be defined to instruct iOS under which conditions the VPN profile should be automatically connected.

In addition, parameters normally given in the OpenVPN client configuration file may instead be defined using key/value pairs in the Custom Data section:

VoD requires an OpenVPN autologin profile, i.e. a profile that authenticates using only a client certificate and key, without requiring a connection password.
Define each OpenVPN directive as a key, with arguments specified as the value. As in the OpenVPN configuration file, arguments are space-delimited and may be quoted.
At a minimum, key/value pairs for ca and remote must be defined (Note that OpenVPN cannot get the CA list from the VoD profile, therefore it must be provided using a ca key/value pair).
Key value pairs for tls-auth, key-direction, comp-lzo, cipher, ns-cert-type, and remote-cert-tls must be defined if the server requires them.
For OpenVPN directives with no arguments, use "NOARGS" as the value.
If multiple instances of the same directive are present, when entering the directive as a key, number the directives in the order they should be given to OpenVPN by appending .n to the directive, where n is an integer, such as remote.1 or remote.2
For multi-line directives such as ca and tls-auth, where the argument is a multi-line file, an escaping model has been provided to allow the file content to be specified as a single-line value. The procedure is to convert the multi-line data to a single line by replacing line breaks with "\n" (without the quotes). Note that because of this escaping model, you must use "\\" to pass backslash itself.
For OpenVPN Access Server meta-directives such as "OVPN_ACCESS_SERVER_USERNAME", remove the OVPN_ACCESS_SERVER_ prefix, giving USERNAME as the directive.

Once the VoD profile has been defined, you have two options for exporting it to an iOS device:

If your device is currently tethered, click on your device name in the left pane. Then in the main window, click on the Configuration Profiles tab. You should see the name of your Configuration Profile and a button to install it on the device.
You can also save the Configuration Profile as a .mobileconfig file, and make it available to iOS clients via email or the web. To do this, select your Configuration Profile, go to the File menu, and select "Export...". An Export Configuration Profile dialog box will appear. Select a Security option -- "Sign configuration profile" is a reasonable choice. Press the Export button and save the profile.

When an iOS device receives a VoD profile (via Mail attachment, Safari download, or pushed by the iPhone Configuration utility), it will raise a dialog box to facilitate import of the profile. After import, the profile will be visible in the Settings App under General / Profiles. It will also be visible as a profile in the OpenVPN app. Note that the profile must be the currently-enabled VPN profile in order for the VoD functionality to work.

I am a developer. How can I detect if OpenVPN Connect is installed?

OpenVPN Connect 1.0.6 and higher installs the openvpn:// URL scheme and can be detected with the following code:

BOOL installed = [application canOpenURL:[NSURL URLWithString:@"openvpn://"]];

How can I contact the developers about bugs or feature requests?

A: Send email to ios@openvpn.net or open a ticket on our bug tracker (registration required). When opening a ticket, please select "OpenVPN Connect" in the component drop-down menu.