/*
* Copyright (C) 2019 The Android Open Source Project
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package android.net.ipsec.ike;
import static android.net.ipsec.ike.IkeSessionParams.ESP_ENCAP_TYPE_NONE;
import static android.net.ipsec.ike.IkeSessionParams.ESP_ENCAP_TYPE_UDP;
import static android.net.ipsec.ike.IkeSessionParams.ESP_IP_VERSION_IPV4;
import static android.net.ipsec.ike.IkeSessionParams.ESP_IP_VERSION_IPV6;
import static android.net.ipsec.ike.IkeSessionParams.IKE_NATT_KEEPALIVE_DELAY_SEC_MAX;
import static android.net.ipsec.ike.IkeSessionParams.IKE_NATT_KEEPALIVE_DELAY_SEC_MIN;
import android.annotation.FlaggedApi;
import android.annotation.IntRange;
import android.annotation.NonNull;
import android.annotation.SuppressLint;
import android.annotation.SystemApi;
import android.content.Context;
import android.content.pm.PackageManager;
import android.net.IpSecManager;
import android.net.Network;
import android.net.ipsec.ike.exceptions.IkeException;
import android.os.HandlerThread;
import android.os.Looper;
import android.util.CloseGuard;
import com.android.internal.annotations.VisibleForTesting;
import com.android.internal.net.ipsec.ike.IkeSessionStateMachine;
import java.io.PrintWriter;
import java.util.Objects;
import java.util.concurrent.Executor;
/**
* This class represents an IKE Session management object that allows for keying and management of
* {@link android.net.IpSecTransform}s.
*
* <p>An IKE/Child Session represents an IKE/Child SA as well as its rekeyed successors. A Child
* Session is bounded by the lifecycle of the IKE Session under which it is set up. Closing an IKE
* Session implicitly closes any remaining Child Sessions under it.
*
* <p>An IKE procedure is one or multiple IKE message exchanges that are used to create, delete or
* rekey an IKE Session or Child Session.
*
* <p>This class provides methods for initiating IKE procedures, such as the Creation and Deletion
* of a Child Session, or the Deletion of the IKE session. All procedures (except for IKE deletion)
* will be initiated sequentially after IKE Session is set up.
*
* @see <a href="https://tools.ietf.org/html/rfc7296">RFC 7296, Internet Key Exchange Protocol
* Version 2 (IKEv2)</a>
*/
public final class IkeSession implements AutoCloseable {
private final CloseGuard mCloseGuard = new CloseGuard();
private final Context mContext;
/**
* Attribution tag for IWLAN callers
*
* @hide
*/
public static final String CONTEXT_ATTRIBUTION_TAG_IWLAN = "IWLAN";
/**
* Attribution tag for VCN callers
*
* @hide
*/
public static final String CONTEXT_ATTRIBUTION_TAG_VCN = "VCN";
/**
* Attribution tag for VPN callers
*
* @hide
*/
public static final String CONTEXT_ATTRIBUTION_TAG_VPN = "VPN_MANAGER";
@VisibleForTesting final IkeSessionStateMachine mIkeSessionStateMachine;
/**
* Constructs a new IKE session.
*
* <p>This method will immediately return an instance of {@link IkeSession} and asynchronously
* initiate the setup procedure of {@link IkeSession} as well as its first Child Session.
* Callers will be notified of these two setup results via the callback arguments.
*
* <p>FEATURE_IPSEC_TUNNELS is required for setting up a tunnel mode Child SA.
*
* @param context a valid {@link Context} instance.
* @param ikeSessionParams the {@link IkeSessionParams} that contains a set of valid {@link
* IkeSession} configurations.
* @param firstChildSessionParams the {@link ChildSessionParams} that contains a set of valid
* configurations for the first Child Session.
* @param userCbExecutor the {@link Executor} upon which all callbacks will be posted. For
* security and consistency, the callbacks posted to this executor MUST be executed serially
* and in the order they were posted, as guaranteed by executors such as {@link
* java.util.concurrent.Executors#newSingleThreadExecutor()}
* @param ikeSessionCallback the {@link IkeSessionCallback} interface to notify callers of state
* changes within the {@link IkeSession}.
* @param firstChildSessionCallback the {@link ChildSessionCallback} interface to notify callers
* of state changes within the first Child Session.
* @return an instance of {@link IkeSession}.
*/
public IkeSession(
@NonNull Context context,
@NonNull IkeSessionParams ikeSessionParams,
@NonNull ChildSessionParams firstChildSessionParams,
@NonNull Executor userCbExecutor,
@NonNull IkeSessionCallback ikeSessionCallback,
@NonNull ChildSessionCallback firstChildSessionCallback) {
this(
context,
(IpSecManager) context.getSystemService(Context.IPSEC_SERVICE),
ikeSessionParams,
firstChildSessionParams,
userCbExecutor,
ikeSessionCallback,
firstChildSessionCallback);
}
/** Package private */
@VisibleForTesting
IkeSession(
Context context,
IpSecManager ipSecManager,
IkeSessionParams ikeSessionParams,
ChildSessionParams firstChildSessionParams,
Executor userCbExecutor,
IkeSessionCallback ikeSessionCallback,
ChildSessionCallback firstChildSessionCallback) {
this(
IkeThreadHolder.IKE_WORKER_THREAD.getLooper(),
context,
ipSecManager,
ikeSessionParams,
firstChildSessionParams,
userCbExecutor,
ikeSessionCallback,
firstChildSessionCallback);
}
/** Package private */
@VisibleForTesting
IkeSession(
Looper looper,
Context context,
IpSecManager ipSecManager,
IkeSessionParams ikeSessionParams,
ChildSessionParams firstChildSessionParams,
Executor userCbExecutor,
IkeSessionCallback ikeSessionCallback,
ChildSessionCallback firstChildSessionCallback) {
mContext = context;
if (firstChildSessionParams instanceof TunnelModeChildSessionParams) {
checkTunnelFeatureOrThrow(mContext);
}
mIkeSessionStateMachine =
new IkeSessionStateMachine(
looper,
context,
ipSecManager,
ikeSessionParams,
firstChildSessionParams,
userCbExecutor,
ikeSessionCallback,
firstChildSessionCallback);
mIkeSessionStateMachine.openSession();
mCloseGuard.open("open");
}
/** @hide */
@Override
public void finalize() {
if (mCloseGuard != null) {
mCloseGuard.warnIfOpen();
}
}
private void checkTunnelFeatureOrThrow(Context context) {
// TODO(b/157754168): Also check if OP_MANAGE_IPSEC_TUNNELS is granted when it is exposed
if (!context.getPackageManager().hasSystemFeature(PackageManager.FEATURE_IPSEC_TUNNELS)) {
throw new IllegalStateException(
"Cannot set up tunnel mode Child SA due to FEATURE_IPSEC_TUNNELS missing");
}
}
/** Initialization-on-demand holder */
private static class IkeThreadHolder {
static final HandlerThread IKE_WORKER_THREAD;
static {
IKE_WORKER_THREAD = new HandlerThread("IkeWorkerThread");
IKE_WORKER_THREAD.start();
}
}
// TODO: b/133340675 Destroy the worker thread when there is no more alive {@link IkeSession}.
/**
* Request a new Child Session.
*
* <p>Users MUST provide a unique {@link ChildSessionCallback} instance for each new Child
* Session.
*
* <p>Upon setup, {@link ChildSessionCallback#onOpened(ChildSessionConfiguration)} will be
* fired.
*
* <p>FEATURE_IPSEC_TUNNELS is required for setting up a tunnel mode Child SA.
*
* @param childSessionParams the {@link ChildSessionParams} that contains the Child Session
* configurations to negotiate.
* @param childSessionCallback the {@link ChildSessionCallback} interface to notify users the
* state changes of the Child Session. It will be posted to the callback {@link Executor} of
* this {@link IkeSession}.
* @throws IllegalArgumentException if the ChildSessionCallback is already in use.
*/
// The childSessionCallback will be called on the same executor as was passed in the constructor
// for security reasons.
@SuppressLint("ExecutorRegistration")
public void openChildSession(
@NonNull ChildSessionParams childSessionParams,
@NonNull ChildSessionCallback childSessionCallback) {
if (childSessionParams instanceof TunnelModeChildSessionParams) {
checkTunnelFeatureOrThrow(mContext);
}
mIkeSessionStateMachine.openChildSession(childSessionParams, childSessionCallback);
}
/**
* Delete a Child Session.
*
* <p>Upon closure, {@link ChildSessionCallback#onClosed()} will be fired.
*
* @param childSessionCallback The {@link ChildSessionCallback} instance that uniquely identify
* the Child Session.
* @throws IllegalArgumentException if no Child Session found bound with this callback.
*/
// The childSessionCallback will be called on the same executor as was passed in the constructor
// for security reasons.
@SuppressLint("ExecutorRegistration")
public void closeChildSession(@NonNull ChildSessionCallback childSessionCallback) {
mIkeSessionStateMachine.closeChildSession(childSessionCallback);
}
/**
* Close the IKE session gracefully.
*
* <p>Implements {@link AutoCloseable#close()}
*
* <p>Upon closure, {@link IkeSessionCallback#onClosed()} or {@link
* IkeSessionCallback#onClosedWithException(IkeException)} will be fired.
*
* <p>Closing an IKE Session implicitly closes any remaining Child Sessions negotiated under it.
* Users SHOULD stop all outbound traffic that uses these Child Sessions ({@link
* android.net.IpSecTransform} pairs) before calling this method. Otherwise IPsec packets will
* be dropped due to the lack of a valid {@link android.net.IpSecTransform}.
*
* <p>Closure of an IKE session will take priority over, and cancel other procedures waiting in
* the queue (but will wait for ongoing locally initiated procedures to complete). After sending
* the Delete request, the IKE library will wait until a Delete response is received or
* retransmission timeout occurs.
*/
@Override
public void close() {
mCloseGuard.close();
mIkeSessionStateMachine.closeSession();
}
/**
* Terminate (forcibly close) the IKE session.
*
* <p>Upon closing, {@link IkeSessionCallback#onClosed()} will be fired.
*
* <p>Closing an IKE Session implicitly closes any remaining Child Sessions negotiated under it.
* Users SHOULD stop all outbound traffic that uses these Child Sessions ({@link
* android.net.IpSecTransform} pairs) before calling this method. Otherwise IPsec packets will
* be dropped due to the lack of a valid {@link android.net.IpSecTransform}.
*
* <p>Forcible closure of an IKE session will take priority over, and cancel other procedures
* waiting in the queue. It will also interrupt any ongoing locally initiated procedure.
*/
public void kill() {
mCloseGuard.close();
mIkeSessionStateMachine.killSession();
}
/**
* Update the IkeSession's underlying Network to use the specified Network.
*
* @see #setNetwork(Network, int, int)
* @hide
*/
@SystemApi
public void setNetwork(@NonNull Network network) {
setNetwork(network, IkeSessionParams.ESP_IP_VERSION_AUTO,
IkeSessionParams.ESP_ENCAP_TYPE_AUTO,
IkeSessionParams.NATT_KEEPALIVE_INTERVAL_AUTO);
}
/**
* Update the IkeSession's underlying Network, protocol preference and keepalive delay.
*
* <p>Updating the IkeSession's Network also updates the Network for any Child Sessions created
* with this IkeSession. To perform the update, callers must implement:
*
* <ul>
* <li>{@link IkeSessionCallback#onIkeSessionConnectionInfoChanged(IkeSessionConnectionInfo)}:
* This call will be triggered once the IKE Session has been updated. The implementation
* MUST migrate all IpSecTunnelInterface instances associated with this IkeSession via
* {@link android.net.IpSecManager.IpSecTunnelInterface#setUnderlyingNetwork(Network)}
* <li>{@link ChildSessionCallback#onIpSecTransformsMigrated(android.net.IpSecTransform,
* android.net.IpSecTransform)}: This call will be triggered once a Child Session has been
* updated. The implementation MUST re-apply the migrated transforms to the {@link
* android.net.IpSecManager.IpSecTunnelInterface} associated with this
* ChildSessionCallback, via {@link android.net.IpSecManager#applyTunnelModeTransform(
* android.net.IpSecManager.IpSecTunnelInterface, int, android.net.IpSecTransform)}.
* </ul>
*
* <p>In order for Network migration to be possible, the following must be true:
*
* <ul>
* <li>the {@link IkeSessionParams} for this IkeSession must be configured with {@link
* IkeSessionParams#IKE_OPTION_MOBIKE} (set via {@link
* IkeSessionParams.Builder#addIkeOption(int)}), and
* <li>the IkeSession must have been started with the Network specified via {@link
* IkeSessionParams.Builder#setNetwork(Network)}.
* </ul>
*
* <p>As MOBIKE support is negotiated, callers are advised to check for MOBIKE support in {@link
* IkeSessionConfiguration} before calling this method to update the network. Failure to do so
* may cause this call to be ignored.
*
* @see <a href="https://tools.ietf.org/html/rfc4555">RFC 4555, IKEv2 Mobility and Multihoming
* Protocol (MOBIKE)</a>
* @param network the Network to use for this IkeSession
* @param ipVersion the IP version to use for ESP packets
* @param encapType the encapsulation type to use for ESP packets
* @param keepaliveDelaySeconds the keepalive delay in seconds, or NATT_KEEPALIVE_INTERVAL_AUTO
* to choose the value automatically based on the network.
* @throws IllegalStateException if {@link IkeSessionParams#IKE_OPTION_MOBIKE} is not configured
* in IkeSessionParams, or if the Network was not specified in IkeSessionParams.
* @throws UnsupportedOperationException if the provided option is not supported.
* @see IkeSessionParams#getNattKeepAliveDelaySeconds()
* @hide
*/
@SystemApi(client = SystemApi.Client.MODULE_LIBRARIES)
public void setNetwork(
@NonNull Network network,
@IkeSessionParams.EspIpVersion int ipVersion,
@IkeSessionParams.EspEncapType int encapType,
// Is there a way to specify an intrange + a sentinel value ?
@IntRange(
from = IKE_NATT_KEEPALIVE_DELAY_SEC_MIN,
to = IKE_NATT_KEEPALIVE_DELAY_SEC_MAX)
int keepaliveDelaySeconds) {
if ((ipVersion == ESP_IP_VERSION_IPV4 && encapType == ESP_ENCAP_TYPE_NONE)
|| (ipVersion == ESP_IP_VERSION_IPV6 && encapType == ESP_ENCAP_TYPE_UDP)) {
throw new UnsupportedOperationException("Sending packets with IPv4 ESP or IPv6 UDP"
+ " are not supported");
}
mIkeSessionStateMachine.setNetwork(Objects.requireNonNull(network),
ipVersion, encapType, keepaliveDelaySeconds);
}
/**
* Inform the session that it is used to supply the passed network.
*
* This will be used by the session when it needs to perform actions that depend on what
* network this session is underpinning. In particular, this can be used to turn off
* keepalives when there are no connections open on the underpinned network, if the
* {@link IkeSessionParams#IKE_OPTION_AUTOMATIC_KEEPALIVE_ON_OFF} option is turned on.
*
* @param underpinnedNetwork the network underpinned by this session.
* @hide
*/
@SystemApi(client = SystemApi.Client.MODULE_LIBRARIES)
public void setUnderpinnedNetwork(@NonNull Network underpinnedNetwork) {
mIkeSessionStateMachine.setUnderpinnedNetwork(Objects.requireNonNull(underpinnedNetwork));
}
/**
* Request to check liveness of peer.
*
* <p>This method returns immediately and asynchronously,
*
* <p>The liveness check determines whether a peer is alive by executing a new on-demand DPD
* task or joining an existing running task depending on the situation.
*
* <ul>
* <li>If there is no running task when a liveness check request is called, a new on-demand
* DPD task is started. The on-demand DPD (Dead Peer Detection) is used for checking
* liveness of peer in this case. This method adds an on-demand DPD request to the work
* queue to check that the peer is alive. The on-demand DPD uses retransmit timeouts from
* {@link IkeSessionParams#getLivenessRetransmissionTimeoutsMillis}.
* <li>If any IKE message is already in progress when a client requests a liveness check, the
* liveness check request is joined to an existing running task. And then the liveness
* check runs in the background. When a running task receives a valid IKE message packet
* from a peer, it can verify that the peer is alive in the background without triggering
* an on-demand DPD task. A running task uses retransmit timeouts from {@link
* IkeSessionParams#getRetransmissionTimeoutsMillis}.
* </ul>
*
* <p>The client is notified of the progress or result statuses of the liveness check via {@link
* IkeSessionCallback#onLivenessStatusChanged}. These statuses are notified after a liveness
* check request is started. By notifying {@link
* IkeSessionCallback.LivenessStatus#LIVENESS_STATUS_SUCCESS} or {@link
* IkeSessionCallback.LivenessStatus#LIVENESS_STATUS_FAILURE}, the liveness check request is
* done and no further status notification is made until the next {@link
* IkeSession#requestLivenessCheck}. The status notifications to the client are as follows.
*
* <ul>
* <li>{@link IkeSessionCallback.LivenessStatus#LIVENESS_STATUS_ON_DEMAND_STARTED}: This
* status is called when liveness checking is started with a new on-demand DPD task.
* <li>{@link IkeSessionCallback.LivenessStatus#LIVENESS_STATUS_ON_DEMAND_ONGOING}: This
* status is called when liveness checking is already running in an on-demand DPD task.
* <li>{@link IkeSessionCallback.LivenessStatus#LIVENESS_STATUS_BACKGROUND_STARTED}: This
* status is called when liveness checking is started in the background and has joined an
* existing running task.
* <li>{@link IkeSessionCallback.LivenessStatus#LIVENESS_STATUS_BACKGROUND_ONGOING}: This
* status is called when liveness checking is already running in the background by joining
* an existing running task.
* <li>{@link IkeSessionCallback.LivenessStatus#LIVENESS_STATUS_SUCCESS}: This status is
* called when the peer's liveness is proven. Once this status is notified, the liveness
* check request is done and no further status notification is made until the next {@link
* IkeSession#requestLivenessCheck}.
* <li>{@link IkeSessionCallback.LivenessStatus#LIVENESS_STATUS_FAILURE}: This state is called
* when the peer is determined as dead for a liveness check request. After this status is
* notified, the IkeSession will be closed immediately by calling {@link
* IkeSessionCallback#onClosedWithException} with {@link
* android.net.ipsec.ike.exceptions.IkeTimeoutException} in the {@link
* IkeException#getCause()}.
* </ul>
*
* <p>If a valid IKE message response is received from the peer, the IkeSession remains as
* connected and periodic DPD reschedules by {@link IkeSessionParams#getDpdDelaySeconds}
*
* <p>If the liveness check request couldn't get any a peer's valid response in retransmission
* timeout, The IkeSession will be closed. Session closing is also notified to {@link
* IkeSessionCallback#onClosedWithException} with {@link
* android.net.ipsec.ike.exceptions.IkeTimeoutException} cause.
*
* @hide
*/
@SystemApi
@FlaggedApi("com.android.ipsec.flags.liveness_check_api")
public void requestLivenessCheck() {
mIkeSessionStateMachine.requestLivenessCheck();
}
/**
* Dumps the state of {@link IkeSession} information for the clients
*
* @param pw Print writer
*/
@FlaggedApi("com.android.ipsec.flags.dumpsys_api")
public void dump(@NonNull PrintWriter pw) {
// TODO(b/336409878): Add @RequiresPermission annotation.
mContext.enforceCallingOrSelfPermission(
android.Manifest.permission.DUMP, mContext.getAttributionTag());
// Please make sure that the dump is thread-safe
// so the client won't get a crash or exception when adding codes to the dump.
pw.println();
pw.println("IkeSession:");
pw.println("------------------------------");
// Dump ike state machine.
if (mIkeSessionStateMachine != null) {
pw.println();
mIkeSessionStateMachine.dump(pw);
}
pw.println("------------------------------");
}
}