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