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.SystemApi;
21 import android.net.IpSecTransform;
22 import android.net.annotations.PolicyDirection;
23 import android.net.ipsec.ike.exceptions.IkeException;
24 
25 /**
26  * Callback interface for receiving state changes of a Child Session.
27  *
28  * <p>{@link ChildSessionCallback} MUST be unique to each Child Session. It is registered when
29  * callers are requesting a new Child Session. It is automatically unregistered when a Child Session
30  * or the parent IKE Session is closed.
31  *
32  * <p>{@link ChildSessionCallback}s are also used for identifying Child Sessions. It is required
33  * when a caller wants to delete a specific Child Session.
34  *
35  * @hide
36  */
37 @SystemApi
38 public interface ChildSessionCallback {
39     /**
40      * Called when the Child Session setup succeeds.
41      *
42      * <p>This method will be called immediately after {@link
43      * #onIpSecTransformCreated(IpSecTransform, int)} for the created IPsec SA pair is fired.
44      *
45      * @param sessionConfiguration the {@link ChildSessionConfiguration} of Child Session negotiated
46      *     during Child creation.
47      */
onOpened(@onNull ChildSessionConfiguration sessionConfiguration)48     void onOpened(@NonNull ChildSessionConfiguration sessionConfiguration);
49 
50     /**
51      * Called when the Child Session is closed.
52      *
53      * <p>This method will be called immediately after {@link
54      * #onIpSecTransformDeleted(IpSecTransform, int)} for the deleted IPsec SA pair is fired.
55      *
56      * <p>When the closure is caused by a local, fatal error, {@link
57      * #onClosedExceptionally(IkeException)} will be fired instead of this method.
58      */
onClosed()59     void onClosed();
60 
61     /**
62      * Called if the Child Session setup failed or Child Session is closed because of a fatal error.
63      *
64      * <p>This method will be called immediately after {@link
65      * #onIpSecTransformDeleted(IpSecTransform, int)} for the deleted IPsec SA pair is fired.
66      *
67      * @param exception the detailed error information.
68      */
onClosedExceptionally(@onNull IkeException exception)69     void onClosedExceptionally(@NonNull IkeException exception);
70 
71     /**
72      * Called when an {@link IpSecTransform} is created by this Child Session.
73      *
74      * <p>This method is fired when a Child Session is created or rekeyed.
75      *
76      * <p>The {@link IpSecTransform} must be applied to relevant sockets or interfaces when this
77      * method is called; traffic may otherwise flow over the socket or interface unprotected.
78      *
79      * <p>As this method is fired on an executor, there is an inherent race condition during rekeys
80      * where traffic may be routed through the old transforms while the remote has switched to using
81      * the new set of transforms.
82      *
83      * <p>To avoid the initial startup race condition where the transforms have not yet been
84      * applied, the {@link onOpened(ChildSessionConfiguration)} callback should be used as the
85      * authoritative signal that the socket or tunnel is ready, as it is fired after both transforms
86      * have had a chance to be applied.
87      *
88      * @param ipSecTransform the created {@link IpSecTransform}.
89      * @param direction the direction of this {@link IpSecTransform}.
90      */
onIpSecTransformCreated( @onNull IpSecTransform ipSecTransform, @PolicyDirection int direction)91     void onIpSecTransformCreated(
92             @NonNull IpSecTransform ipSecTransform, @PolicyDirection int direction);
93 
94     /**
95      * Called when an {@link IpSecTransform} is deleted by this Child Session.
96      *
97      * <p>This method is fired when a Child Session is closed or a Child Session has deleted old
98      * IPsec SA during rekey. When this method is fired due to Child Session closure, it will be
99      * followed by {@link #onClosed()} or {@link #onClosedExceptionally(IkeException)}.
100      *
101      * <p>Users SHOULD remove the {@link IpSecTransform} from the socket or interface when this
102      * method is called. Otherwise the IPsec traffic protected by this {@link IpSecTransform} will
103      * be discarded.
104      *
105      * @param ipSecTransform the deleted {@link IpSecTransform}.
106      * @param direction the direction of this {@link IpSecTransform}.
107      */
onIpSecTransformDeleted( @onNull IpSecTransform ipSecTransform, @PolicyDirection int direction)108     void onIpSecTransformDeleted(
109             @NonNull IpSecTransform ipSecTransform, @PolicyDirection int direction);
110 }
111