Added in API level 31

Builder

class Builder
kotlin.Any
   ↳ android.net.ipsec.ike.IkeSessionParams.Builder

This class can be used to incrementally construct a IkeSessionParams.

Summary

Public constructors

Construct Builder
Builder(ikeSessionParams: IkeSessionParams)

Construct Builder from the IkeSessionParams object.
Public methods
IkeSessionParams.Builder
addIkeOption(ikeOption: Int)

Sets the specified IKE Option as enabled.
IkeSessionParams.Builder

Adds an IKE SA proposal to the IkeSessionParams being built.
IkeSessionParams

Validates and builds the IkeSessionParams.
IkeSessionParams.Builder
removeIkeOption(ikeOption: Int)

Resets (disables) the specified IKE Option.
IkeSessionParams.Builder
setAuthDigitalSignature(serverCaCert: X509Certificate?, clientEndCert: X509Certificate, clientPrivateKey: PrivateKey)

Configures the IkeSession to use public-key-signature-based authentication.
IkeSessionParams.Builder
setAuthDigitalSignature(serverCaCert: X509Certificate?, clientEndCert: X509Certificate, clientIntermediateCerts: MutableList<X509Certificate!>, clientPrivateKey: PrivateKey)

Configures the IkeSession to use public-key-signature-based authentication.
IkeSessionParams.Builder
setAuthEap(serverCaCert: X509Certificate?, eapConfig: EapSessionConfig)

Configures the IkeSession to use EAP authentication.
IkeSessionParams.Builder
setAuthPsk(sharedKey: ByteArray)

Configures the IkeSession to use pre-shared-key-based authentication.
IkeSessionParams.Builder
setDpdDelaySeconds(dpdDelaySeconds: Int)

Sets the Dead Peer Detection(DPD) delay in seconds.
IkeSessionParams.Builder
setLifetimeSeconds(hardLifetimeSeconds: Int, softLifetimeSeconds: Int)

Sets hard and soft lifetimes.
IkeSessionParams.Builder

Sets local IKE identification for the IkeSessionParams being built.
IkeSessionParams.Builder
setNattKeepAliveDelaySeconds(nattKeepaliveDelaySeconds: Int)

Sets the Network Address Translation Traversal (NATT) keepalive delay in seconds.
IkeSessionParams.Builder
setNetwork(network: Network?)

Sets the Network for the IkeSessionParams being built.
IkeSessionParams.Builder

Sets remote IKE identification for the IkeSessionParams being built.
IkeSessionParams.Builder
setRetransmissionTimeoutsMillis(retransTimeoutMillisList: IntArray)

Sets the retransmission timeout list in milliseconds.
IkeSessionParams.Builder
setServerHostname(serverHostname: String)

Sets the server hostname for the IkeSessionParams being built.

Public constructors

Builder

Added in API level 31
Builder()

Construct Builder

Builder

Added in API level 31
Builder(ikeSessionParams: IkeSessionParams)

Construct Builder from the IkeSessionParams object.

Parameters
ikeSessionParams IkeSessionParams: the object this Builder will be constructed with. This value cannot be null.

Public methods

addIkeOption

Added in API level 31
fun addIkeOption(ikeOption: Int): IkeSessionParams.Builder

Sets the specified IKE Option as enabled.

Parameters
ikeOption Int: the option to be enabled. Value is android.net.ipsec.ike.IkeSessionParams#IKE_OPTION_ACCEPT_ANY_REMOTE_ID, android.net.ipsec.ike.IkeSessionParams#IKE_OPTION_EAP_ONLY_AUTH, android.net.ipsec.ike.IkeSessionParams#IKE_OPTION_MOBIKE, android.net.ipsec.ike.IkeSessionParams#IKE_OPTION_FORCE_PORT_4500, android.net.ipsec.ike.IkeSessionParams#IKE_OPTION_INITIAL_CONTACT, android.net.ipsec.ike.IkeSessionParams.IKE_OPTION_REKEY_MOBILITY, android.net.ipsec.ike.IkeSessionParams.IKE_OPTION_AUTOMATIC_ADDRESS_FAMILY_SELECTION, android.net.ipsec.ike.IkeSessionParams.IKE_OPTION_AUTOMATIC_NATT_KEEPALIVES, android.net.ipsec.ike.IkeSessionParams.IKE_OPTION_AUTOMATIC_KEEPALIVE_ON_OFF, or android.net.ipsec.ike.IkeSessionParams.IKE_OPTION_FORCE_DNS_RESOLUTION
Return
IkeSessionParams.Builder Builder this, to facilitate chaining. This value cannot be null.
Exceptions
java.lang.IllegalArgumentException if the provided option is invalid.

addIkeSaProposal

Added in API level 31
fun addIkeSaProposal(proposal: IkeSaProposal): IkeSessionParams.Builder

Adds an IKE SA proposal to the IkeSessionParams being built.

Parameters
proposal IkeSaProposal: IKE SA proposal. This value cannot be null.
Return
IkeSessionParams.Builder Builder this, to facilitate chaining. This value cannot be null.

build

Added in API level 31
fun build(): IkeSessionParams

Validates and builds the IkeSessionParams.

Return
IkeSessionParams IkeSessionParams the validated IkeSessionParams. This value cannot be null.

removeIkeOption

Added in API level 31
fun removeIkeOption(ikeOption: Int): IkeSessionParams.Builder

Resets (disables) the specified IKE Option.

Parameters
ikeOption Int: the option to be disabled. Value is android.net.ipsec.ike.IkeSessionParams#IKE_OPTION_ACCEPT_ANY_REMOTE_ID, android.net.ipsec.ike.IkeSessionParams#IKE_OPTION_EAP_ONLY_AUTH, android.net.ipsec.ike.IkeSessionParams#IKE_OPTION_MOBIKE, android.net.ipsec.ike.IkeSessionParams#IKE_OPTION_FORCE_PORT_4500, android.net.ipsec.ike.IkeSessionParams#IKE_OPTION_INITIAL_CONTACT, android.net.ipsec.ike.IkeSessionParams.IKE_OPTION_REKEY_MOBILITY, android.net.ipsec.ike.IkeSessionParams.IKE_OPTION_AUTOMATIC_ADDRESS_FAMILY_SELECTION, android.net.ipsec.ike.IkeSessionParams.IKE_OPTION_AUTOMATIC_NATT_KEEPALIVES, android.net.ipsec.ike.IkeSessionParams.IKE_OPTION_AUTOMATIC_KEEPALIVE_ON_OFF, or android.net.ipsec.ike.IkeSessionParams.IKE_OPTION_FORCE_DNS_RESOLUTION
Return
IkeSessionParams.Builder Builder this, to facilitate chaining. This value cannot be null.
Exceptions
java.lang.IllegalArgumentException if the provided option is invalid.

setAuthDigitalSignature

Added in API level 31
fun setAuthDigitalSignature(
    serverCaCert: X509Certificate?, 
    clientEndCert: X509Certificate, 
    clientPrivateKey: PrivateKey
): IkeSessionParams.Builder

Configures the IkeSession to use public-key-signature-based authentication.

The public key included by the client end certificate and the private key used for signing MUST be a matching key pair.

The IKE library will use the strongest signature algorithm supported by both sides.

Currenly only RSA digital signature is supported.

Parameters
serverCaCert X509Certificate?: the CA certificate for validating the received server certificate(s). If a certificate is provided, it MUST be the root CA used by the server, or authentication will fail. If no certificate is provided, any root CA in the system's truststore is considered acceptable. This value may be null.
clientEndCert X509Certificate: the end certificate for remote server to verify the locally generated signature. This value cannot be null.
clientPrivateKey PrivateKey: private key to generate outbound digital signature. The PrivateKey MUST be an instance of RSAKey. This value cannot be null.
Return
IkeSessionParams.Builder Builder this, to facilitate chaining. This value cannot be null.

setAuthDigitalSignature

Added in API level 31
fun setAuthDigitalSignature(
    serverCaCert: X509Certificate?, 
    clientEndCert: X509Certificate, 
    clientIntermediateCerts: MutableList<X509Certificate!>, 
    clientPrivateKey: PrivateKey
): IkeSessionParams.Builder

Configures the IkeSession to use public-key-signature-based authentication.

The public key included by the client end certificate and the private key used for signing MUST be a matching key pair.

The IKE library will use the strongest signature algorithm supported by both sides.

Currenly only RSA digital signature is supported.

Parameters
serverCaCert X509Certificate?: the CA certificate for validating the received server certificate(s). If a null value is provided, IKE library will try all default CA certificates stored in Android system to do the validation. Otherwise, it will only use the provided CA certificate.
clientEndCert X509Certificate: the end certificate for remote server to verify locally generated signature. This value cannot be null.
clientIntermediateCerts MutableList<X509Certificate!>: intermediate certificates for the remote server to validate the end certificate. This value cannot be null.
clientPrivateKey PrivateKey: private key to generate outbound digital signature. The PrivateKey MUST be an instance of RSAKey. This value cannot be null.
Return
IkeSessionParams.Builder Builder this, to facilitate chaining. This value cannot be null.

setAuthEap

Added in API level 31
fun setAuthEap(
    serverCaCert: X509Certificate?, 
    eapConfig: EapSessionConfig
): IkeSessionParams.Builder

Configures the IkeSession to use EAP authentication.

Not all EAP methods provide mutual authentication. As such EAP MUST be used in conjunction with a public-key-signature-based authentication of the remote server, unless EAP-Only authentication is enabled.

Callers may enable EAP-Only authentication by setting IKE_OPTION_EAP_ONLY_AUTH, which will make IKE library request the remote to use EAP-Only authentication. The remote may opt to reject the request, at which point the received certificates and authentication payload WILL be validated with the provided root CA or system's truststore as usual. Only safe EAP methods as listed in RFC 5998 will be accepted for EAP-Only authentication.

If IKE_OPTION_EAP_ONLY_AUTH is set, callers MUST configure EAP as the authentication method and all EAP methods set in EAP Session configuration MUST be safe methods that are accepted for EAP-Only authentication. Otherwise callers will get an exception when building the IkeSessionParams

Callers MUST declare only one authentication method. Calling this function will override the previously set authentication configuration.

Parameters
serverCaCert X509Certificate?: the CA certificate for validating the received server certificate(s). If a certificate is provided, it MUST be the root CA used by the server, or authentication will fail. If no certificate is provided, any root CA in the system's truststore is considered acceptable. This value may be null.
eapConfig EapSessionConfig: This value cannot be null.
Return
IkeSessionParams.Builder Builder this, to facilitate chaining. This value cannot be null.

See Also

    setAuthPsk

    Added in API level 31
    fun setAuthPsk(sharedKey: ByteArray): IkeSessionParams.Builder

    Configures the IkeSession to use pre-shared-key-based authentication.

    Both client and server MUST be authenticated using the provided shared key. IKE authentication will fail if the remote peer tries to use other authentication methods.

    Callers MUST declare only one authentication method. Calling this function will override the previously set authentication configuration.

    Callers SHOULD NOT use this if any other authentication methods can be used; PSK-based authentication is generally considered insecure.

    Parameters
    sharedKey ByteArray: the shared key. This value cannot be null.
    Return
    IkeSessionParams.Builder Builder this, to facilitate chaining. This value cannot be null.

    setDpdDelaySeconds

    Added in API level 31
    fun setDpdDelaySeconds(dpdDelaySeconds: Int): IkeSessionParams.Builder

    Sets the Dead Peer Detection(DPD) delay in seconds.

    Parameters
    dpdDelaySeconds Int: number of seconds after which IKE SA will initiate DPD if no inbound cryptographically protected IKE message was received. Defaults to 120 seconds. MUST be a value greater than or equal to than 20 seconds. Setting the value to IkeSessionParams#IKE_DPD_DELAY_SEC_DISABLED will disable DPD. Value is IKE_DPD_DELAY_SEC_MIN or greater
    Return
    IkeSessionParams.Builder Builder this, to facilitate chaining. This value cannot be null.

    setLifetimeSeconds

    Added in API level 31
    fun setLifetimeSeconds(
        hardLifetimeSeconds: Int, 
        softLifetimeSeconds: Int
    ): IkeSessionParams.Builder

    Sets hard and soft lifetimes.

    Lifetimes will not be negotiated with the remote IKE server.

    Parameters
    hardLifetimeSeconds Int: number of seconds after which IKE SA will expire. Defaults to 14400 seconds (4 hours). MUST be a value from 300 seconds (5 minutes) to 86400 seconds (24 hours), inclusive. Value is between IKE_HARD_LIFETIME_SEC_MINIMUM and IKE_HARD_LIFETIME_SEC_MAXIMUM inclusive
    softLifetimeSeconds Int: number of seconds after which IKE SA will request rekey. Defaults to 7200 seconds (2 hours). MUST be at least 120 seconds (2 minutes), and at least 60 seconds (1 minute) shorter than the hard lifetime. Value is between IKE_SOFT_LIFETIME_SEC_MINIMUM and IKE_HARD_LIFETIME_SEC_MAXIMUM inclusive
    Return
    IkeSessionParams.Builder Builder this, to facilitate chaining. This value cannot be null.

    setLocalIdentification

    Added in API level 31
    fun setLocalIdentification(identification: IkeIdentification): IkeSessionParams.Builder

    Sets local IKE identification for the IkeSessionParams being built.

    It is not allowed to use KEY ID together with digital-signature-based authentication as per RFC 7296.

    Parameters
    identification IkeIdentification: the local IKE identification. This value cannot be null.
    Return
    IkeSessionParams.Builder Builder this, to facilitate chaining. This value cannot be null.

    setNattKeepAliveDelaySeconds

    Added in API level 31
    fun setNattKeepAliveDelaySeconds(nattKeepaliveDelaySeconds: Int): IkeSessionParams.Builder

    Sets the Network Address Translation Traversal (NATT) keepalive delay in seconds.

    Parameters
    nattKeepaliveDelaySeconds Int: number of seconds between keepalive packet transmissions. Defaults to 10 seconds. MUST be a value from 10 seconds to 3600 seconds, inclusive. Value is between IKE_NATT_KEEPALIVE_DELAY_SEC_MIN and IKE_NATT_KEEPALIVE_DELAY_SEC_MAX inclusive
    Return
    IkeSessionParams.Builder Builder this, to facilitate chaining. This value cannot be null.

    setNetwork

    Added in API level 31
    fun setNetwork(network: Network?): IkeSessionParams.Builder

    Sets the Network for the IkeSessionParams being built.

    If no Network is provided, the default Network (as per android.net.ConnectivityManager#getActiveNetwork()) will be used when constructing an IkeSession.

    Parameters
    network Network?: the Network that IKE Session will use, or null to clear the previously set Network
    Return
    IkeSessionParams.Builder Builder this, to facilitate chaining. This value cannot be null.

    setRemoteIdentification

    Added in API level 31
    fun setRemoteIdentification(identification: IkeIdentification): IkeSessionParams.Builder

    Sets remote IKE identification for the IkeSessionParams being built.

    Parameters
    identification IkeIdentification: the remote IKE identification. This value cannot be null.
    Return
    IkeSessionParams.Builder Builder this, to facilitate chaining. This value cannot be null.

    setRetransmissionTimeoutsMillis

    Added in API level 31
    fun setRetransmissionTimeoutsMillis(retransTimeoutMillisList: IntArray): IkeSessionParams.Builder

    Sets the retransmission timeout list in milliseconds.

    Configures the retransmission by providing an array of relative retransmission timeouts in milliseconds. After sending out a request and before receiving the response, the IKE Session will iterate through the array and wait for the relative timeout before the next retry. If the last timeout is exceeded, the IKE Session will be terminated.

    Each element in the array MUST be a value from 500 ms to 1800000 ms (30 minutes). The length of the array MUST NOT exceed 10. This retransmission timeout list defaults to {0.5s, 1s, 2s, 4s, 8s}

    Parameters
    retransTimeoutMillisList IntArray: the array of relative retransmission timeout in milliseconds. This value cannot be null.
    Return
    IkeSessionParams.Builder Builder this, to facilitate chaining. This value cannot be null.

    setServerHostname

    Added in API level 31
    fun setServerHostname(serverHostname: String): IkeSessionParams.Builder

    Sets the server hostname for the IkeSessionParams being built.

    Parameters
    serverHostname String: the hostname of the IKE server, such as "ike.android.com". This value cannot be null.
    Return
    IkeSessionParams.Builder Builder this, to facilitate chaining. This value cannot be null.