Builder
class Builder
kotlin.Any | |
↳ | android.net.Ikev2VpnProfile.Builder |
A incremental builder for IKEv2 VPN profiles
Summary
Public constructors | |
---|---|
Creates a new builder with the basic parameters of an IKEv2/IPsec VPN. |
|
Builder(ikeTunConnParams: IkeTunnelConnectionParams) Creates a new builder from a |
Public methods | |
---|---|
Ikev2VpnProfile |
build() Validates, builds and provisions the VpnProfile. |
Ikev2VpnProfile.Builder |
setAllowedAlgorithms(algorithmNames: MutableList<String!>) Sets the allowable set of IPsec algorithms |
Ikev2VpnProfile.Builder |
setAuthDigitalSignature(userCert: X509Certificate, key: PrivateKey, serverRootCa: X509Certificate?) Set the IKEv2 authentication to use Digital Signature Authentication with the given key. |
Ikev2VpnProfile.Builder |
setAuthPsk(psk: ByteArray) Set the IKEv2 authentication to use Preshared keys. |
Ikev2VpnProfile.Builder |
setAuthUsernamePassword(user: String, pass: String, serverRootCa: X509Certificate?) Set the IKEv2 authentication to use the provided username/password. |
Ikev2VpnProfile.Builder |
setAutomaticIpVersionSelectionEnabled(isEnabled: Boolean) Sets the enabled state of the automatic IP version selection |
Ikev2VpnProfile.Builder |
setAutomaticNattKeepaliveTimerEnabled(isEnabled: Boolean) Sets the enabled state of the automatic NAT-T keepalive timers Note that if this builder was constructed with a |
Ikev2VpnProfile.Builder |
setBypassable(isBypassable: Boolean) Sets whether apps can bypass this VPN connection. |
Ikev2VpnProfile.Builder |
setLocalRoutesExcluded(excludeLocalRoutes: Boolean) Sets whether the local traffic is exempted from the VPN. |
Ikev2VpnProfile.Builder |
Set the upper bound of the maximum transmission unit (MTU) of the VPN interface. |
Ikev2VpnProfile.Builder |
setMetered(isMetered: Boolean) Marks the VPN network as metered. |
Ikev2VpnProfile.Builder |
Sets a proxy for the VPN network. |
Ikev2VpnProfile.Builder |
setRequiresInternetValidation(requiresInternetValidation: Boolean) Request that this VPN undergoes Internet validation. |
Public constructors
Builder
Builder(
serverAddr: String,
identity: String)
Creates a new builder with the basic parameters of an IKEv2/IPsec VPN.
Requires the PackageManager#FEATURE_IPSEC_TUNNELS
feature which can be detected using PackageManager.hasSystemFeature(String)
.
Parameters | |
---|---|
serverAddr |
String: the server that the VPN should connect to This value cannot be null . |
identity |
String: the identity string to be used for IKEv2 authentication This value cannot be null . |
Builder
Builder(ikeTunConnParams: IkeTunnelConnectionParams)
Creates a new builder from a IkeTunnelConnectionParams
Requires the PackageManager#FEATURE_IPSEC_TUNNELS
feature which can be detected using PackageManager.hasSystemFeature(String)
.
Parameters | |
---|---|
ikeTunConnParams |
IkeTunnelConnectionParams: the IkeTunnelConnectionParams contains IKEv2 configurations This value cannot be null . |
Public methods
build
fun build(): Ikev2VpnProfile
Validates, builds and provisions the VpnProfile.
Requires the PackageManager#FEATURE_IPSEC_TUNNELS
feature which can be detected using PackageManager.hasSystemFeature(String)
.
Return | |
---|---|
Ikev2VpnProfile |
This value cannot be null . |
Exceptions | |
---|---|
java.lang.IllegalArgumentException |
if any of the required keys or values were invalid |
setAllowedAlgorithms
fun setAllowedAlgorithms(algorithmNames: MutableList<String!>): Ikev2VpnProfile.Builder
Sets the allowable set of IPsec algorithms
If set, this will constrain the set of algorithms that the IPsec tunnel will use for integrity verification and encryption to the provided list.
The set of allowed IPsec algorithms is defined in IpSecAlgorithm
. Adding of algorithms that are considered insecure (such as AUTH_HMAC_MD5 and AUTH_HMAC_SHA1) is not permitted, and will result in an IllegalArgumentException being thrown.
The provided algorithm list must contain at least one algorithm that provides Authentication, and one that provides Encryption. Authenticated Encryption with Associated Data (AEAD) algorithms provide both Authentication and Encryption.
If this Builder
is constructed with an IkeTunnelConnectionParams
, authentication details should be configured there, and calling this method will result in an exception being thrown.
By default, this profile will use any algorithm defined in IpSecAlgorithm
, with the exception of those considered insecure (as described above).
Requires the PackageManager#FEATURE_IPSEC_TUNNELS
feature which can be detected using PackageManager.hasSystemFeature(String)
.
Parameters | |
---|---|
algorithmNames |
MutableList<String!>: the list of supported IPsec algorithms This value cannot be null . |
Return | |
---|---|
Ikev2VpnProfile.Builder |
this Builder object to facilitate chaining of method calls This value cannot be null . |
See Also
setAuthDigitalSignature
fun setAuthDigitalSignature(
userCert: X509Certificate,
key: PrivateKey,
serverRootCa: X509Certificate?
): Ikev2VpnProfile.Builder
Set the IKEv2 authentication to use Digital Signature Authentication with the given key.
Setting this will configure IKEv2 authentication using a Digital Signature scheme. Only one authentication method may be set. This method will overwrite any previously set authentication method.
If this Builder
is constructed with an IkeTunnelConnectionParams
, authentication details should be configured there, and calling this method will result in an exception being thrown.
Requires the PackageManager#FEATURE_IPSEC_TUNNELS
feature which can be detected using PackageManager.hasSystemFeature(String)
.
Parameters | |
---|---|
userCert |
X509Certificate: the username to be used for RSA Digital signiture authentication This value cannot be null . |
key |
PrivateKey: the PrivateKey instance associated with the user ceritificate, used for constructing the signature This value cannot be null . |
serverRootCa |
X509Certificate?: the root certificate to be used for verifying the identity of the server This value may be null . |
Return | |
---|---|
Ikev2VpnProfile.Builder |
this Builder object to facilitate chaining of method calls This value cannot be null . |
Exceptions | |
---|---|
java.lang.IllegalArgumentException |
if any of the certificates were invalid or of an unrecognized format |
setAuthPsk
fun setAuthPsk(psk: ByteArray): Ikev2VpnProfile.Builder
Set the IKEv2 authentication to use Preshared keys.
Setting this will configure IKEv2 authentication using a Preshared Key. Only one authentication method may be set. This method will overwrite any previously set authentication method.
If this Builder
is constructed with an IkeTunnelConnectionParams
, authentication details should be configured there, and calling this method will result in an exception being thrown.
Requires the PackageManager#FEATURE_IPSEC_TUNNELS
feature which can be detected using PackageManager.hasSystemFeature(String)
.
Parameters | |
---|---|
psk |
ByteArray: the key to be used for Pre-Shared Key authentication This value cannot be null . |
Return | |
---|---|
Ikev2VpnProfile.Builder |
this Builder object to facilitate chaining of method calls This value cannot be null . |
setAuthUsernamePassword
fun setAuthUsernamePassword(
user: String,
pass: String,
serverRootCa: X509Certificate?
): Ikev2VpnProfile.Builder
Set the IKEv2 authentication to use the provided username/password.
Setting this will configure IKEv2 authentication using EAP-MSCHAPv2. Only one authentication method may be set. This method will overwrite any previously set authentication method.
If this Builder
is constructed with an IkeTunnelConnectionParams
, authentication details should be configured there, and calling this method will result in an exception being thrown.
Requires the PackageManager#FEATURE_IPSEC_TUNNELS
feature which can be detected using PackageManager.hasSystemFeature(String)
.
Parameters | |
---|---|
user |
String: the username to be used for EAP-MSCHAPv2 authentication This value cannot be null . |
pass |
String: the password to be used for EAP-MSCHAPv2 authentication This value cannot be null . |
serverRootCa |
X509Certificate?: the root certificate to be used for verifying the identity of the server This value may be null . |
Return | |
---|---|
Ikev2VpnProfile.Builder |
this Builder object to facilitate chaining of method calls This value cannot be null . |
Exceptions | |
---|---|
java.lang.IllegalArgumentException |
if any of the certificates were invalid or of an unrecognized format |
setAutomaticIpVersionSelectionEnabled
fun setAutomaticIpVersionSelectionEnabled(isEnabled: Boolean): Ikev2VpnProfile.Builder
Sets the enabled state of the automatic IP version selection
Requires the PackageManager#FEATURE_IPSEC_TUNNELS
feature which can be detected using PackageManager.hasSystemFeature(String)
.
Parameters | |
---|---|
isEnabled |
Boolean: true to enable automatic IP version selection, based on internal platform signals. Defaults to false . |
Return | |
---|---|
Ikev2VpnProfile.Builder |
this Builder object to facilitate chaining of method calls This value cannot be null . |
setAutomaticNattKeepaliveTimerEnabled
fun setAutomaticNattKeepaliveTimerEnabled(isEnabled: Boolean): Ikev2VpnProfile.Builder
Sets the enabled state of the automatic NAT-T keepalive timers Note that if this builder was constructed with a IkeTunnelConnectionParams
, but this is called with true
, the framework will automatically choose the appropriate keepalive timer and ignore the settings in the session params embedded in the connection params.
Requires the PackageManager#FEATURE_IPSEC_TUNNELS
feature which can be detected using PackageManager.hasSystemFeature(String)
.
Parameters | |
---|---|
isEnabled |
Boolean: true to enable automatic keepalive timers, based on internal platform signals. Defaults to false . |
Return | |
---|---|
Ikev2VpnProfile.Builder |
this Builder object to facilitate chaining of method calls This value cannot be null . |
setBypassable
fun setBypassable(isBypassable: Boolean): Ikev2VpnProfile.Builder
Sets whether apps can bypass this VPN connection.
By default, all traffic from apps are forwarded through the VPN interface and it is not possible for unprivileged apps to side-step the VPN. If a VPN is set to bypassable, apps may use methods such as Network#getSocketFactory
or android.net.Network#openConnection to instead send/receive directly over the underlying network or any other network they have permissions for.
Requires the PackageManager#FEATURE_IPSEC_TUNNELS
feature which can be detected using PackageManager.hasSystemFeature(String)
.
Parameters | |
---|---|
isBypassable |
Boolean: Whether or not the VPN should be considered bypassable. Defaults to false . |
Return | |
---|---|
Ikev2VpnProfile.Builder |
this Builder object to facilitate chaining of method calls This value cannot be null . |
setLocalRoutesExcluded
fun setLocalRoutesExcluded(excludeLocalRoutes: Boolean): Ikev2VpnProfile.Builder
Sets whether the local traffic is exempted from the VPN. When this is set, the system will not use the VPN network when an app tries to send traffic for an IP address that is on a local network. Note that there are important security implications. In particular, the networks that the device connects to typically decides what IP addresses are part of the local network. This means that for VPNs setting this flag, it is possible for anybody to set up a public network in such a way that traffic to arbitrary IP addresses will bypass the VPN, including traffic to services like DNS. When using this API, please consider the security implications for your particular case. Note that because the local traffic will always bypass the VPN, it is not possible to set this flag on a non-bypassable VPN.
Requires the PackageManager#FEATURE_IPSEC_TUNNELS
feature which can be detected using PackageManager.hasSystemFeature(String)
.
Return | |
---|---|
Ikev2VpnProfile.Builder |
This value cannot be null . |
setMaxMtu
fun setMaxMtu(mtu: Int): Ikev2VpnProfile.Builder
Set the upper bound of the maximum transmission unit (MTU) of the VPN interface.
If it is not set, a safe value will be used. Additionally, the actual link MTU will be dynamically calculated/updated based on the underlying link's mtu.
Requires the PackageManager#FEATURE_IPSEC_TUNNELS
feature which can be detected using PackageManager.hasSystemFeature(String)
.
Parameters | |
---|---|
mtu |
Int: the MTU (in bytes) of the VPN interface |
Return | |
---|---|
Ikev2VpnProfile.Builder |
this Builder object to facilitate chaining of method calls This value cannot be null . |
Exceptions | |
---|---|
java.lang.IllegalArgumentException |
if the value is not at least the minimum IPv6 MTU (1280) |
setMetered
fun setMetered(isMetered: Boolean): Ikev2VpnProfile.Builder
Marks the VPN network as metered.
A VPN network is classified as metered when the user is sensitive to heavy data usage due to monetary costs and/or data limitations. In such cases, you should set this to true
so that apps on the system can avoid doing large data transfers. Otherwise, set this to false
. Doing so would cause VPN network to inherit its meteredness from the underlying network.
Requires the PackageManager#FEATURE_IPSEC_TUNNELS
feature which can be detected using PackageManager.hasSystemFeature(String)
.
Parameters | |
---|---|
isMetered |
Boolean: true if the VPN network should be treated as metered regardless of underlying network meteredness. Defaults to true . |
Return | |
---|---|
Ikev2VpnProfile.Builder |
this Builder object to facilitate chaining of method calls This value cannot be null . |
setProxy
fun setProxy(proxy: ProxyInfo?): Ikev2VpnProfile.Builder
Sets a proxy for the VPN network.
Note that this proxy is only a recommendation and it may be ignored by apps.
Requires the PackageManager#FEATURE_IPSEC_TUNNELS
feature which can be detected using PackageManager.hasSystemFeature(String)
.
Parameters | |
---|---|
proxy |
ProxyInfo?: the ProxyInfo to be set for the VPN network This value may be null . |
Return | |
---|---|
Ikev2VpnProfile.Builder |
this Builder object to facilitate chaining of method calls This value cannot be null . |
setRequiresInternetValidation
fun setRequiresInternetValidation(requiresInternetValidation: Boolean): Ikev2VpnProfile.Builder
Request that this VPN undergoes Internet validation. If this is true, the platform will perform basic validation checks for Internet connectivity over this VPN. If and when they succeed, the VPN network capabilities will reflect this by gaining the NetworkCapabilities#NET_CAPABILITY_VALIDATED
capability. If this is false, the platform assumes the VPN either is always capable of reaching the Internet or intends not to. In this case, the VPN network capabilities will always gain the NetworkCapabilities#NET_CAPABILITY_VALIDATED
capability immediately after it connects, whether it can reach public Internet destinations or not.
Requires the PackageManager#FEATURE_IPSEC_TUNNELS
feature which can be detected using PackageManager.hasSystemFeature(String)
.
Parameters | |
---|---|
requiresInternetValidation |
Boolean: true if the framework should attempt to validate this VPN for Internet connectivity. Defaults to false . |
Return | |
---|---|
Ikev2VpnProfile.Builder |
This value cannot be null . |