1 /*
2  * Copyright (C) 2019 The Android Open Source Project
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  *      http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16 
17 package android.net.ipsec.ike;
18 
19 import android.annotation.NonNull;
20 import android.annotation.SuppressLint;
21 import android.annotation.SystemApi;
22 import android.net.IpSecManager;
23 import android.net.IpSecManager.IpSecTunnelInterface;
24 import android.net.IpSecTransform;
25 import android.net.ipsec.ike.exceptions.IkeException;
26 
27 import com.android.internal.net.annotations.PolicyDirection;
28 
29 /**
30  * Callback interface for receiving state changes of a Child Session.
31  *
32  * <p>{@link ChildSessionCallback} MUST be unique to each Child Session. It is registered when
33  * callers are requesting a new Child Session. It is automatically unregistered when a Child Session
34  * or the parent IKE Session is closed.
35  *
36  * <p>{@link ChildSessionCallback}s are also used for identifying Child Sessions. It is required
37  * when a caller wants to delete a specific Child Session.
38  *
39  * @see <a href="https://tools.ietf.org/html/rfc7296">RFC 7296, Internet Key Exchange Protocol
40  *     Version 2 (IKEv2)</a>
41  * @see <a href="https://tools.ietf.org/html/rfc4301">RFC 4301, Security Architecture for the
42  *     Internet Protocol (IKEv2)</a>
43  */
44 // Using interface instead of abstract class to indicate this callback does not have any state or
45 // implementation.
46 @SuppressLint("CallbackInterface")
47 public interface ChildSessionCallback {
48     /**
49      * Called when the Child Session setup succeeds.
50      *
51      * <p>This method will be called immediately after {@link
52      * #onIpSecTransformCreated(IpSecTransform, int)} for the created IPsec SA pair is fired.
53      *
54      * @param sessionConfiguration the {@link ChildSessionConfiguration} of Child Session negotiated
55      *     during Child creation.
56      */
onOpened(@onNull ChildSessionConfiguration sessionConfiguration)57     void onOpened(@NonNull ChildSessionConfiguration sessionConfiguration);
58 
59     /**
60      * Called when the Child Session is closed.
61      *
62      * <p>This method will be called immediately after {@link
63      * #onIpSecTransformDeleted(IpSecTransform, int)} for the deleted IPsec SA pair is fired.
64      *
65      * <p>When the closure is caused by a local, fatal error, {@link
66      * #onClosedWithException(IkeException)} will be fired instead of this method.
67      */
onClosed()68     void onClosed();
69 
70     /**
71      * Called if the Child Session setup failed or Child Session is closed because of a fatal error.
72      *
73      * <p>This method will be called immediately after {@link
74      * #onIpSecTransformDeleted(IpSecTransform, int)} for the deleted IPsec SA pair is fired.
75      *
76      * @param exception the detailed error information.
77      * @deprecated Implementers should override {@link #onClosedWithException(IkeException)} to
78      *     handle fatal {@link IkeException}s instead of using this method.
79      * @hide
80      */
81     @SystemApi
82     @Deprecated
onClosedExceptionally(@onNull IkeException exception)83     default void onClosedExceptionally(@NonNull IkeException exception) {}
84 
85     /**
86      * Called if the Child Session setup failed or Child Session is closed because of a fatal error.
87      *
88      * <p>This method will be called immediately after {@link
89      * #onIpSecTransformDeleted(IpSecTransform, int)} for the deleted IPsec SA pair is fired.
90      *
91      * @param exception the detailed error information.
92      */
onClosedWithException(@onNull IkeException exception)93     default void onClosedWithException(@NonNull IkeException exception) {
94         onClosedExceptionally(exception);
95     }
96 
97     /**
98      * Called when an {@link IpSecTransform} is created by this Child Session.
99      *
100      * <p>This method is fired when a Child Session is created or rekeyed.
101      *
102      * <p>The {@link IpSecTransform} must be applied to relevant sockets or interfaces when this
103      * method is called; traffic may otherwise flow over the socket or interface unprotected.
104      *
105      * <p>As this method is fired on an executor, there is an inherent race condition during rekeys
106      * where traffic may be routed through the old transforms while the remote has switched to using
107      * the new set of transforms.
108      *
109      * <p>To avoid the initial startup race condition where the transforms have not yet been
110      * applied, the {@link #onOpened(ChildSessionConfiguration)} callback should be used as the
111      * authoritative signal that the socket or tunnel is ready, as it is fired after both transforms
112      * have had a chance to be applied.
113      *
114      * @param ipSecTransform the created {@link IpSecTransform}.
115      * @param direction the direction of this {@link IpSecTransform}.
116      */
onIpSecTransformCreated( @onNull IpSecTransform ipSecTransform, @PolicyDirection int direction)117     void onIpSecTransformCreated(
118             @NonNull IpSecTransform ipSecTransform, @PolicyDirection int direction);
119 
120     /**
121      * Called when a pair of {@link IpSecTransform}s are migrated by this IKE Session.
122      *
123      * <p>This method is only called when a Child SA is migrated during a MOBIKE-enabled IKE
124      * Session.
125      *
126      * <p>When this method is invoked, the caller MUST re-apply the transforms to their {@link
127      * IpSecTunnelInterface} via {@link IpSecManager#applyTunnelModeTransform(IpSecTunnelInterface,
128      * int, IpSecTransform)}
129      *
130      * @param inIpSecTransform IpSecTransform to be used for traffic with {@link
131      *     IpSecManager#DIRECTION_IN}
132      * @param outIpSecTransform IpSecTransform to be used for traffic with {@link
133      *     IpSecManager#DIRECTION_OUT}
134      * @hide
135      */
136     @SystemApi
onIpSecTransformsMigrated( @onNull IpSecTransform inIpSecTransform, @NonNull IpSecTransform outIpSecTransform)137     default void onIpSecTransformsMigrated(
138             @NonNull IpSecTransform inIpSecTransform, @NonNull IpSecTransform outIpSecTransform) {}
139 
140     /**
141      * Called when an {@link IpSecTransform} is deleted by this Child Session.
142      *
143      * <p>This method is fired when a Child Session is closed or a Child Session has deleted old
144      * IPsec SA during rekey. When this method is fired due to Child Session closure, it will be
145      * followed by {@link #onClosed()} or {@link #onClosedWithException(IkeException)}.
146      *
147      * <p>Users SHOULD remove the {@link IpSecTransform} from the socket or interface when this
148      * method is called. Otherwise the IPsec traffic protected by this {@link IpSecTransform} will
149      * be discarded.
150      *
151      * @param ipSecTransform the deleted {@link IpSecTransform}.
152      * @param direction the direction of this {@link IpSecTransform}.
153      */
onIpSecTransformDeleted( @onNull IpSecTransform ipSecTransform, @PolicyDirection int direction)154     void onIpSecTransformDeleted(
155             @NonNull IpSecTransform ipSecTransform, @PolicyDirection int direction);
156 }
157