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.FlaggedApi;
20 import android.annotation.IntDef;
21 import android.annotation.NonNull;
22 import android.annotation.SuppressLint;
23 import android.annotation.SystemApi;
24 import android.net.ipsec.ike.exceptions.IkeException;
25 import android.net.ipsec.ike.exceptions.IkeProtocolException;
26 
27 import java.lang.annotation.Retention;
28 import java.lang.annotation.RetentionPolicy;
29 
30 /**
31  * Callback interface for receiving state changes of an {@link IkeSession}.
32  *
33  * <p>{@link IkeSessionCallback} MUST be unique to each {@link IkeSession}. It is registered when
34  * callers are requesting a new {@link IkeSession}. It is automatically unregistered when an {@link
35  * IkeSession} is closed.
36  *
37  * @see <a href="https://tools.ietf.org/html/rfc7296">RFC 7296, Internet Key Exchange Protocol
38  *     Version 2 (IKEv2)</a>
39  */
40 // Using interface instead of abstract class to indicate this callback does not have any state or
41 // implementation.
42 @SuppressLint("CallbackInterface")
43 public interface IkeSessionCallback {
44 
45     /**
46      * A new on-demand liveness check has started. Called when a liveness check begins with a new
47      * on-demand task.
48      *
49      * @hide
50      */
51     @SystemApi
52     @FlaggedApi("com.android.ipsec.flags.liveness_check_api")
53     int LIVENESS_STATUS_ON_DEMAND_STARTED = 0;
54 
55     /**
56      * A new on-demand liveness check is running. Called when a liveness check request is already
57      * running in an on-demand task.
58      *
59      * @hide
60      */
61     @SystemApi
62     @FlaggedApi("com.android.ipsec.flags.liveness_check_api")
63     int LIVENESS_STATUS_ON_DEMAND_ONGOING = 1;
64 
65     /**
66      * A new on-demand liveness check has started. Called when a liveness check begins in background
67      * with joining an existing running task.
68      *
69      * @hide
70      */
71     @SystemApi
72     @FlaggedApi("com.android.ipsec.flags.liveness_check_api")
73     int LIVENESS_STATUS_BACKGROUND_STARTED = 2;
74 
75     /**
76      * A background liveness check is running. Called when a liveness check request is already
77      * running in background.
78      *
79      * @hide
80      */
81     @SystemApi
82     @FlaggedApi("com.android.ipsec.flags.liveness_check_api")
83     int LIVENESS_STATUS_BACKGROUND_ONGOING = 3;
84 
85     /**
86      * Success status. Called when the peer's liveness is proven.
87      *
88      * <p>Note that this status is a result status when the peer is proven as alive, regardless of
89      * whether it is started in on-demand or in background.
90      *
91      * @hide
92      */
93     @SystemApi
94     @FlaggedApi("com.android.ipsec.flags.liveness_check_api")
95     int LIVENESS_STATUS_SUCCESS = 4;
96 
97     /**
98      * Failure status. Called when the IKE message retransmission times out.
99      *
100      * <p>This failure status is called when retransmission timeouts have expired. The IkeSession
101      * will be closed immediately by calling {@link IkeSessionCallback#onClosedWithException} with
102      * {@link android.net.ipsec.ike.exceptions.IkeTimeoutException} in the {@link
103      * IkeException#getCause()}.
104      *
105      * <p>Note that this status is a result status when the peer is determined as dead alive,
106      * regardless of whether it is started in on-demand or in background.
107      *
108      * @hide
109      */
110     @SystemApi
111     @FlaggedApi("com.android.ipsec.flags.liveness_check_api")
112     int LIVENESS_STATUS_FAILURE = 5;
113 
114     /** @hide */
115     @Retention(RetentionPolicy.SOURCE)
116     @IntDef({
117         LIVENESS_STATUS_ON_DEMAND_STARTED,
118         LIVENESS_STATUS_ON_DEMAND_ONGOING,
119         LIVENESS_STATUS_BACKGROUND_STARTED,
120         LIVENESS_STATUS_BACKGROUND_ONGOING,
121         LIVENESS_STATUS_SUCCESS,
122         LIVENESS_STATUS_FAILURE,
123     })
124     @interface LivenessStatus {}
125 
126     /**
127      * Called when the {@link IkeSession} setup succeeds.
128      *
129      * <p>This method does not indicate the first Child Session has been setup. Caller MUST refer to
130      * the corresponding {@link ChildSessionCallback} for the Child Session setup result.
131      *
132      * @param sessionConfiguration the configuration information of {@link IkeSession} negotiated
133      *     during IKE setup.
134      */
onOpened(@onNull IkeSessionConfiguration sessionConfiguration)135     void onOpened(@NonNull IkeSessionConfiguration sessionConfiguration);
136 
137     /**
138      * Called when the {@link IkeSession} is closed.
139      *
140      * <p>When the closure is caused by a local, fatal error, {@link
141      * #onClosedWithException(IkeException)} will be fired instead of this method.
142      */
onClosed()143     void onClosed();
144 
145     /**
146      * Called if {@link IkeSession} setup failed or {@link IkeSession} is closed because of a fatal
147      * error.
148      *
149      * @param exception the detailed error information.
150      * @deprecated Implementers should override {@link #onClosedWithException(IkeException)} to
151      *     handle fatal {@link IkeException}s instead of using this method.
152      * @hide
153      */
154     @SystemApi
155     @Deprecated
onClosedExceptionally(@onNull IkeException exception)156     default void onClosedExceptionally(@NonNull IkeException exception) {}
157 
158     /**
159      * Called if {@link IkeSession} setup failed or {@link IkeSession} is closed because of a fatal
160      * error.
161      *
162      * @param exception the detailed error information.
163      */
onClosedWithException(@onNull IkeException exception)164     default void onClosedWithException(@NonNull IkeException exception) {
165         onClosedExceptionally(exception);
166     }
167 
168     /**
169      * Called if a recoverable error is encountered in an established {@link IkeSession}.
170      *
171      * <p>This method may be triggered by protocol errors such as an INVALID_IKE_SPI or
172      * INVALID_MESSAGE_ID.
173      *
174      * @param exception the detailed error information.
175      * @deprecated Implementers should override {@link #onError(IkeException)} to handle {@link
176      *     IkeProtocolException}s instead of using this method.
177      * @hide
178      */
179     @SystemApi
180     @Deprecated
onError(@onNull IkeProtocolException exception)181     default void onError(@NonNull IkeProtocolException exception) {}
182 
183     /**
184      * Called if a recoverable error is encountered in an established {@link IkeSession}.
185      *
186      * <p>This method may be triggered by protocol errors such as an INVALID_IKE_SPI, or by
187      * non-protocol errors such as the underlying {@link android.net.Network} dying.
188      *
189      * @param exception the detailed error information.
190      */
onError(@onNull IkeException exception)191     default void onError(@NonNull IkeException exception) {
192         if (exception instanceof IkeProtocolException) {
193             onError((IkeProtocolException) exception);
194             return;
195         }
196 
197         // do nothing for non-protocol errors by default
198     }
199 
200     /**
201      * Called if the IkeSessionConnectionInfo for an established {@link IkeSession} changes.
202      *
203      * <p>This method will only be called for MOBIKE-enabled Sessions, and only after a Mobility
204      * Event occurs. An mobility event can happen in two Network modes:
205      *
206      * <ul>
207      *   <li><b>Caller managed:</b> The caller controls the underlying Network for the IKE Session
208      *       at all times. The IKE Session will only change underlying Networks if the caller
209      *       initiates it through {@link IkeSession#setNetwork(Network)}. If the caller-specified
210      *       Network is lost, they will be notified via {@link
211      *       IkeSessionCallback#onError(android.net.ipsec.ike.exceptions.IkeException)} with an
212      *       {@link android.net.ipsec.ike.exceptions.IkeNetworkLostException} specifying the Network
213      *       that was lost.
214      *   <li><b>Platform Default:</b> The IKE Session will always track the application default
215      *       Network. The IKE Session will start on the application default Network, and any
216      *       subsequent changes to the default Network (after the IKE_AUTH exchange completes) will
217      *       cause the IKE Session's underlying Network to change. If the default Network is lost
218      *       with no replacements, the caller will be notified via {@link
219      *       IkeSessionCallback#onError(android.net.ipsec.ike.exceptions.IkeException)} with an
220      *       {@link android.net.ipsec.ike.exceptions.IkeNetworkLostException}. The caller can either
221      *       wait until for a new default Network to become available or they may close the Session
222      *       manually via {@link IkeSession#close()}. Note that the IKE Session's maximum
223      *       retransmissions may expire while waiting for a new default Network, in which case the
224      *       Session will automatically close and {@link #onClosedWithException(IkeException)} will
225      *       be fired.
226      * </ul>
227      *
228      * <p>There are three types of mobility events:
229      *
230      * <ul>
231      *   <li>The underlying Network changing, or
232      *   <li>The local address disappearing from the current (and unchanged) underlying Network, or
233      *   <li>The remote address changing.
234      * </ul>
235      *
236      * @param connectionInfo the updated IkeSessionConnectionInfo for the Session.
237      * @hide
238      */
239     @SystemApi
onIkeSessionConnectionInfoChanged( @onNull IkeSessionConnectionInfo connectionInfo)240     default void onIkeSessionConnectionInfoChanged(
241             @NonNull IkeSessionConnectionInfo connectionInfo) {}
242 
243     /**
244      * Called when the status changes for the liveness check request.
245      *
246      * <p>{@link LivenessStatus#LIVENESS_STATUS_ON_DEMAND_STARTED}: This status is called when
247      * liveness checking is started with a new on-demand DPD task.
248      *
249      * <ul>
250      *   <li>Note that when a client requests a liveness check, if no tasks are currently running in
251      *       the session, a new on-demand DPD task is started and notified of {@link
252      *       LivenessStatus#LIVENESS_STATUS_ON_DEMAND_STARTED}.
253      *   <li>Note that a new on-demand DPD task uses retransmission timeouts from {@link
254      *       IkeSessionParams#getLivenessRetransmissionTimeoutsMillis()}.
255      * </ul>
256      *
257      * <p>{@link LivenessStatus#LIVENESS_STATUS_ON_DEMAND_ONGOING}: This status is called when
258      * liveness checking is already running in an on-demand DPD task.
259      *
260      * <ul>
261      *   <li>Note that when a client requests a liveness check, if there is already running in an
262      *       on-demand DPD task, {@link LivenessStatus#LIVENESS_STATUS_ON_DEMAND_ONGOING} is
263      *       notified.
264      * </ul>
265      *
266      * <p>{@link LivenessStatus#LIVENESS_STATUS_BACKGROUND_STARTED}: This status is called when
267      * liveness checking is started with joining an existing running task.
268      *
269      * <ul>
270      *   <li>Note that if there is an existing running task in the session and no liveness check
271      *       request is running in the background, the liveness check request will be joined to the
272      *       existing running task in the background. Then, while joining, {@link
273      *       LivenessStatus#LIVENESS_STATUS_BACKGROUND_STARTED} is notified.
274      *   <li>Note that an existing running task uses retransmission timeouts from {@link
275      *       IkeSessionParams#getRetransmissionTimeoutsMillis()}.
276      * </ul>
277      *
278      * <p>{@link LivenessStatus#LIVENESS_STATUS_BACKGROUND_ONGOING}: This status is called when
279      * liveness checking is already running with joining an existing running task.
280      *
281      * <ul>
282      *   <li>Note that when a client requests a liveness check, if the request is already running in
283      *       the background, {@link LivenessStatus#LIVENESS_STATUS_ON_DEMAND_ONGOING} is notified.
284      * </ul>
285      *
286      * <p>{@link LivenessStatus#LIVENESS_STATUS_SUCCESS}: This status is called when the peer's
287      * liveness is proven. Regardless of whether the request is running in an on-demand task or
288      * running in the background, Success result is reported with this status. Once this status is
289      * called, the liveness check request is done and no further status notifications are made until
290      * the next {@link IkeSession#requestLivenessCheck}.
291      *
292      * <ul>
293      *   <li>Note that if the peer's aliveness is proven in the on-demand DPD task, {@link
294      *       LivenessStatus#LIVENESS_STATUS_SUCCESS} is notified as soon as a valid on-demand DPD
295      *       response is received properly.
296      *   <li>Note that if the peer's liveness is proven in a background liveness check with joining
297      *       an existing running task, it can prove that the peer is alive for a valid incoming
298      *       packet of the joined task. In this case, {@link LivenessStatus#LIVENESS_STATUS_SUCCESS}
299      *       is notified as well.
300      * </ul>
301      *
302      * <p>{@link LivenessStatus#LIVENESS_STATUS_FAILURE}: This state is called when the peer is
303      * determined as dead for a liveness check request. After this status is called, the IkeSession
304      * will be closed immediately by calling {@link IkeSessionCallback#onClosedWithException} with
305      * {@link android.net.ipsec.ike.exceptions.IkeTimeoutException} in the {@link
306      * IkeException#getCause()}. Depending on the type of task for which liveness checking is
307      * performed, the failure result is reported as different retransmission timeouts.
308      *
309      * <ul>
310      *   <li>Note that if an on-demand DPD task is running, This task takes retransmission timeouts
311      *       from {@link IkeSessionParams#getLivenessRetransmissionTimeoutsMillis}, and after all
312      *       timeouts expire, {@link LivenessStatus#LIVENESS_STATUS_FAILURE} is notified and is
313      *       followed by closing session.
314      *   <li>Note that, if the liveness check request is running in the background in the joined
315      *       task, the task takes retransmission timeouts from {@link
316      *       IkeSessionParams#getRetransmissionTimeoutsMillis()}, and after all timeouts expire,
317      *       {@link LivenessStatus#LIVENESS_STATUS_FAILURE} is notified and is followed by closing
318      *       session.
319      * </ul>
320      *
321      * @param status the status of {@link LivenessStatus}
322      * @hide
323      */
324     @SystemApi
325     @FlaggedApi("com.android.ipsec.flags.liveness_check_api")
onLivenessStatusChanged(@ivenessStatus int status)326     default void onLivenessStatusChanged(@LivenessStatus int status) {}
327 }
328