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