Project

General

Profile

VPN Profile Import for the Android VPN Client » History » Version 8

Tobias Brunner, 15.10.2019 17:49
Client identity is now configurable for all authentication types

1 1 Tobias Brunner
h1. VPN Profile Import for the Android VPN Client
2 1 Tobias Brunner
3 2 Tobias Brunner
Since version [[AndroidVPNClient#180-2017-01-20|1.8.0]] of the [[AndroidVPNClient|strongSwan VPN Client for Android]] it is possible to import VPN profiles from JSON files.
4 1 Tobias Brunner
5 1 Tobias Brunner
h2. Deployment
6 1 Tobias Brunner
7 1 Tobias Brunner
The app will open @http(s)://@ URLs to @.sswan@ files. It also opens any file with a media type of @application/vnd.strongswan.profile@ (the file extension doesn't matter in that case). The latter should also work for email attachments if the media type is set accordingly.
8 1 Tobias Brunner
9 1 Tobias Brunner
Whether downloaded files for which the media type is not correct but the extension is @.sswan@ can be opened depends on the app that starts the Intent.  For instance, from Android's default Downloads app it won't work due to the @content://@ URLs that do not contain the original file name (it works if the media type was set correctly by the web server), but when e.g. opening the downloaded file from within Chrome's Downloads view it works as these Intents use @file://@ URLs that contain the complete file name.
10 1 Tobias Brunner
11 4 Tobias Brunner
Since [[AndroidVPNClient#190-2017-07-03|1.9.0]] it is possible to browse for profile files via SAF(Storage Access Framework), which should also work if the file extension and/or media type is not correct.
12 3 Tobias Brunner
13 1 Tobias Brunner
Note that after importing the profile the user is able to edit it freely.
14 1 Tobias Brunner
15 1 Tobias Brunner
h2. File Format
16 1 Tobias Brunner
17 1 Tobias Brunner
The file format is based on "JSON":http://json.org. The expected encoding is UTF-8.
18 1 Tobias Brunner
19 3 Tobias Brunner
The top-level element in the file is an object that may (or must) contain the following keys. Keys of sub-objects are separated with dots.
20 1 Tobias Brunner
21 1 Tobias Brunner
|_<.Required|_<.Key     |_<.Description         |
22 1 Tobias Brunner
|=.*x*      |*uuid*     |Unique identifier to identify the VPN profile. The format is defined in "RFC 4122":https://tools.ietf.org/html/rfc4122. Version 4 UUIDs (random-generated) are recommended (may be created with e.g. @uuid -v4@).
23 1 Tobias Brunner
If a VPN profile with the same UUID already exists its settings are replaced when the profile is imported.|
24 1 Tobias Brunner
|=.*x*      |*name*     |Display name of the profile.|
25 1 Tobias Brunner
|=.*x*      |*type*     |Type of the VPN profile. The following values are currently supported and determine the type of client authentication that's used (the server is always authenticated with a certificate).
26 1 Tobias Brunner
*ikev2-eap*: Username/password-based EAP authentication
27 1 Tobias Brunner
*ikev2-cert*: Certificate authentication
28 1 Tobias Brunner
*ikev2-cert-eap*: Certificate authentication followed by a username/password-based EAP authentication
29 1 Tobias Brunner
*ikev2-eap-tls*: EAP-TLS certificate authentication
30 1 Tobias Brunner
*ikev2-byod-eap*: EAP-TNC with username/password-based EAP authentication
31 1 Tobias Brunner
Some of the keys described below are only relevant for certain types.|
32 5 Tobias Brunner
|\3(level3).|
33 1 Tobias Brunner
|=(level2).*x*|(level2). *remote*|(level2). Object containing information about the server.|
34 1 Tobias Brunner
|=.*x*      |*remote.addr*|The server's hostname or IP address. If no remote identity is configured this has to be contained as _subjectAltName_ extension in the server certificate.|
35 1 Tobias Brunner
|           |remote.port|Optional server port (default is 500).|
36 1 Tobias Brunner
|           |remote.id  |Optional IKE identity of the server. If this is not configured it defaults to _remote.addr_ and no IDr is sent in the IKE_AUTH request.|
37 1 Tobias Brunner
|           |remote.cert|Optional Base64-encoded CA or server certificate. Is imported into the app, not the system keystore. If not set, automatic CA certificate selection is enabled. So it's not necessary, if the server certificate is issued by a CA the client already trusts, or if the PKCS#12-file below contains the complete certificate chain (this might cause warnings on older Android releases, though, see [[AndroidVPNClient#Client-Configuration]] for details).|
38 6 Tobias Brunner
|           |remote.certreq|Whether to send certificate requests for all installed or selected CA certificates. Disabling this may reduce the size of the IKE_AUTH message if the server does not support fragmentation. But it only works if the server doesn't require certificate requests to send back the server certificate. Since [[AndroidVPNClient#190-2017-07-03|1.9.0]].|
39 6 Tobias Brunner
|(level3).  |(level3). remote.revocation|(level3). Optional object that sets the revocation checking policy for the remote certificate.|
40 7 Tobias Brunner
|           |remote.revocation.crl|Whether to use CRL(Certificate Revocation List)s, if available, for revocation checking of the remote certificate. CRLs are only used if OCSP doesn't yield a result. Enabled by default. Since [[AndroidVPNClient#200-2018-07-03|2.0.0]].|
41 7 Tobias Brunner
|           |remote.revocation.ocsp|Whether to use OCSP(Online Certificate Status Protocol), if available, for revocation checking of the remote certificate. Enabled by default. Since [[AndroidVPNClient#200-2018-07-03|2.0.0]].|
42 7 Tobias Brunner
|           |remote.revocation.strict|In strict mode the authentication will fail if the status of the remote certificate is unknown (e.g. because no valid CRL was available). Disabled by default. Since [[AndroidVPNClient#200-2018-07-03|2.0.0]].|
43 1 Tobias Brunner
|\3(level3).|
44 1 Tobias Brunner
|(level2).  |(level2). local|(level2). Object containing information about the client.|
45 1 Tobias Brunner
|           |local.eap_id|Optional identity/username for EAP authentication. If this is required (for username/password-based EAP authentication) but not configured here, the user is prompted for it when importing the profile. If it is set the user is not able to change it while importing (but may later do so). In both cases the user may optionally enter the password while importing the profile.|
46 8 Tobias Brunner
|           |local.id   |Optional IKE identity of the client for certificate authentication and since [[AndroidVPNClient#220-2019-10-15|2.2.0]] also for other authentication types. Typically has to match a _subjectAltName_ contained in the client certificate, if one is used. Must not be configured if the certificate's subject DN shall be used as client identity.|
47 1 Tobias Brunner
|           |local.p12  |Optional Base64-encoded PKCS#12-container with the client certificate and private key and optional certificate chain (the latter might cause warnings on older Android releases, see [[AndroidVPNClient#Client-Configuration]] for details). Not necessary for username/password-based EAP authentication, or if the user already has the certificate/key installed as it may be selected while importing the profile.|
48 7 Tobias Brunner
|           |local.rsa-pss|Whether to use the stronger PSS encoding instead of the classic PKCS#1 encoding for RSA signatures during RFC 7427 signature authentication. Disabled by default, may be enabled if the server supports it. Since [[AndroidVPNClient#200-2018-07-03|2.0.0]].|
49 1 Tobias Brunner
|\3(level3).|
50 3 Tobias Brunner
|(level2).  |(level2). split-tunneling|(level2). Optional object containing split-tunneling settings.|
51 4 Tobias Brunner
|           |split-tunneling.subnets|An array of subnets (in CIDR notation), IP addresses or ranges (IP-IP) to route via VPN. All other traffic is forwarded as if there was no VPN. This is only relevant locally, these subnets are not sent to the server. Since [[AndroidVPNClient#190-2017-07-03|1.9.0]].|
52 4 Tobias Brunner
|           |split-tunneling.excluded|An array of subnets (in CIDR notation), IP addresses or ranges (IP-IP) to exclude from the VPN. Matching traffic is forwarded as if there was no VPN. This is only relevant locally. Since [[AndroidVPNClient#190-2017-07-03|1.9.0]].|
53 3 Tobias Brunner
|           |split-tunneling.block-ipv4|Whether to block IPv4 traffic that's not destined for the VPN. Forces all IPv4 traffic via VPN (traffic that does not match the negotiated traffic selector is then just dropped), so it's basically the same as including @0.0.0.0/0@ in _split-tunneling.subnets_.|
54 3 Tobias Brunner
|           |split-tunneling.block-ipv6|Whether to block IPv6 traffic that's not destined for the VPN. Forces all IPv6 traffic via VPN (traffic that does not match the negotiated traffic selector is then just dropped), so it's basically the same as including @::/0@ in _split-tunneling.subnets_.|
55 1 Tobias Brunner
|\3(level3).|
56 5 Tobias Brunner
|           |apps          |Optional array of package names (e.g. @com.example.app.name@) of apps that are able to use this VPN connection. For all other apps it will look as if there is no VPN. Since [[AndroidVPNClient#190-2017-07-03|1.9.0]]|
57 5 Tobias Brunner
|           |excluded-apps |Optional array of package names (e.g. @com.example.app.name@) of apps that won't be able to use this VPN connection. It will look to them as if there is no VPN. Only relevant if _apps_ is not set. Since [[AndroidVPNClient#190-2017-07-03|1.9.0]]|
58 5 Tobias Brunner
|\3(level3).|
59 5 Tobias Brunner
|           |ike-proposal  |Optional custom IKE proposal, that is, a list of [[IKEv2CipherSuites|algorithm identifiers]] separated by hyphens. For non-AEAD/classic encryption algorithms, an integrity algorithm, a pseudo random function (optional, defaults to one based on the integrity algorithm) and a Diffie-Hellman group are required (e.g. _aes256-sha256-ecp256_). For combined-mode/AEAD algorithms, the integrity algorithm is omitted but a PRF is required (e.g. _aes256gcm16-prfsha256-ecp256_). Since [[AndroidVPNClient#195-2017-11-17|1.9.5]]|
60 5 Tobias Brunner
|           |esp-proposal  |Optional custom ESP proposal, that is, a list of [[IKEv2CipherSuites|algorithm identifiers]] separated by hyphens. For non-AEAD/classic encryption algorithms, an integrity algorithm is required, a Diffie-Hellman group is optional (e.g. _aes256-sha256_ or _aes256-sha256-ecp256_). For combined-mode/AEAD algorithms, the integrity algorithm is omitted (e.g. _aes256gcm16_ or _aes256gcm16-ecp256_). If a DH group is specified IPsec SA rekeying will use a DH key exchange. However, DH groups specified here are not used when the connection is established initially because the keys there are derived from the IKE SA key material. Therefore, any configuration mismatch with the server will only cause errors later during rekeying. Since [[AndroidVPNClient#195-2017-11-17|1.9.5]]|
61 3 Tobias Brunner
|\3(level3).|
62 3 Tobias Brunner
|           |mtu           |Optional MTU to use for the TUN device|
63 4 Tobias Brunner
|           |nat-keepalive |Optional interval for [[NatTraversal|NAT-T keepalive]] packets. Since [[AndroidVPNClient#190-2017-07-03|1.9.0]].|
64 1 Tobias Brunner
65 1 Tobias Brunner
h2. Example
66 1 Tobias Brunner
67 1 Tobias Brunner
{{collapse(Example - Certificate authentication)
68 1 Tobias Brunner
<pre><code class="json">
69 1 Tobias Brunner
{
70 1 Tobias Brunner
	"uuid": "a061d140-d3f9-4db7-b2f8-32d6703f4618",
71 1 Tobias Brunner
	"name": "Test Profile Certificate",
72 1 Tobias Brunner
	"type": "ikev2-cert",
73 1 Tobias Brunner
	"remote": {
74 1 Tobias Brunner
		"addr": "10.0.2.2"
75 1 Tobias Brunner
	},
76 1 Tobias Brunner
	"local": {
77 1 Tobias Brunner
		"p12": "MIIN..."
78 1 Tobias Brunner
	}
79 1 Tobias Brunner
}
80 1 Tobias Brunner
</code></pre>
81 1 Tobias Brunner
}}
82 1 Tobias Brunner
83 1 Tobias Brunner
{{collapse(Example - Username/password-based EAP authentication)
84 1 Tobias Brunner
<pre><code class="json">
85 1 Tobias Brunner
{
86 1 Tobias Brunner
	"uuid": "559eb893-1cee-4196-8b97-67045e029e91",
87 1 Tobias Brunner
	"name": "Test Profile EAP",
88 1 Tobias Brunner
	"type": "ikev2-eap",
89 1 Tobias Brunner
	"remote": {
90 1 Tobias Brunner
		"addr": "10.0.2.2",
91 1 Tobias Brunner
		"id": "vpn.strongswan.org",
92 1 Tobias Brunner
		"cert": "MIID..." 
93 1 Tobias Brunner
	},
94 1 Tobias Brunner
	"local": {
95 1 Tobias Brunner
		"eap_id": "android"
96 1 Tobias Brunner
	}
97 1 Tobias Brunner
}
98 1 Tobias Brunner
</code></pre>
99 1 Tobias Brunner
}}