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