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.ipsec.ike.exceptions.IkeException; 23 import android.net.ipsec.ike.exceptions.IkeProtocolException; 24 25 /** 26 * Callback interface for receiving state changes of an {@link IkeSession}. 27 * 28 * <p>{@link IkeSessionCallback} MUST be unique to each {@link IkeSession}. It is registered when 29 * callers are requesting a new {@link IkeSession}. It is automatically unregistered when an {@link 30 * IkeSession} is closed. 31 * 32 * @see <a href="https://tools.ietf.org/html/rfc7296">RFC 7296, Internet Key Exchange Protocol 33 * Version 2 (IKEv2)</a> 34 */ 35 // Using interface instead of abstract class to indicate this callback does not have any state or 36 // implementation. 37 @SuppressLint("CallbackInterface") 38 public interface IkeSessionCallback { 39 /** 40 * Called when the {@link IkeSession} setup succeeds. 41 * 42 * <p>This method does not indicate the first Child Session has been setup. Caller MUST refer to 43 * the corresponding {@link ChildSessionCallback} for the Child Session setup result. 44 * 45 * @param sessionConfiguration the configuration information of {@link IkeSession} negotiated 46 * during IKE setup. 47 */ onOpened(@onNull IkeSessionConfiguration sessionConfiguration)48 void onOpened(@NonNull IkeSessionConfiguration sessionConfiguration); 49 50 /** 51 * Called when the {@link IkeSession} is closed. 52 * 53 * <p>When the closure is caused by a local, fatal error, {@link 54 * #onClosedWithException(IkeException)} will be fired instead of this method. 55 */ onClosed()56 void onClosed(); 57 58 /** 59 * Called if {@link IkeSession} setup failed or {@link IkeSession} is closed because of a fatal 60 * error. 61 * 62 * @param exception the detailed error information. 63 * @deprecated Implementers should override {@link #onClosedWithException(IkeException)} to 64 * handle fatal {@link IkeException}s instead of using this method. 65 * @hide 66 */ 67 @SystemApi 68 @Deprecated onClosedExceptionally(@onNull IkeException exception)69 default void onClosedExceptionally(@NonNull IkeException exception) {} 70 71 /** 72 * Called if {@link IkeSession} setup failed or {@link IkeSession} is closed because of a fatal 73 * error. 74 * 75 * @param exception the detailed error information. 76 */ onClosedWithException(@onNull IkeException exception)77 default void onClosedWithException(@NonNull IkeException exception) { 78 onClosedExceptionally(exception); 79 } 80 81 /** 82 * Called if a recoverable error is encountered in an established {@link IkeSession}. 83 * 84 * <p>This method may be triggered by protocol errors such as an INVALID_IKE_SPI or 85 * INVALID_MESSAGE_ID. 86 * 87 * @param exception the detailed error information. 88 * @deprecated Implementers should override {@link #onError(IkeException)} to handle {@link 89 * IkeProtocolException}s instead of using this method. 90 * @hide 91 */ 92 @SystemApi 93 @Deprecated onError(@onNull IkeProtocolException exception)94 default void onError(@NonNull IkeProtocolException exception) {} 95 96 /** 97 * Called if a recoverable error is encountered in an established {@link IkeSession}. 98 * 99 * <p>This method may be triggered by protocol errors such as an INVALID_IKE_SPI, or by 100 * non-protocol errors such as the underlying {@link android.net.Network} dying. 101 * 102 * @param exception the detailed error information. 103 */ onError(@onNull IkeException exception)104 default void onError(@NonNull IkeException exception) { 105 if (exception instanceof IkeProtocolException) { 106 onError((IkeProtocolException) exception); 107 return; 108 } 109 110 // do nothing for non-protocol errors by default 111 } 112 113 /** 114 * Called if the IkeSessionConnectionInfo for an established {@link IkeSession} changes. 115 * 116 * <p>This method will only be called for MOBIKE-enabled Sessions, and only after a Mobility 117 * Event occurs. An mobility event can happen in two Network modes: 118 * 119 * <ul> 120 * <li><b>Caller managed:</b> The caller controls the underlying Network for the IKE Session 121 * at all times. The IKE Session will only change underlying Networks if the caller 122 * initiates it through {@link IkeSession#setNetwork(Network)}. If the caller-specified 123 * Network is lost, they will be notified via {@link 124 * IkeSessionCallback#onError(android.net.ipsec.ike.exceptions.IkeException)} with an 125 * {@link android.net.ipsec.ike.exceptions.IkeNetworkLostException} specifying the Network 126 * that was lost. 127 * <li><b>Platform Default:</b> The IKE Session will always track the application default 128 * Network. The IKE Session will start on the application default Network, and any 129 * subsequent changes to the default Network (after the IKE_AUTH exchange completes) will 130 * cause the IKE Session's underlying Network to change. If the default Network is lost 131 * with no replacements, the caller will be notified via {@link 132 * IkeSessionCallback#onError(android.net.ipsec.ike.exceptions.IkeException)} with an 133 * {@link android.net.ipsec.ike.exceptions.IkeNetworkLostException}. The caller can either 134 * wait until for a new default Network to become available or they may close the Session 135 * manually via {@link IkeSession#close()}. Note that the IKE Session's maximum 136 * retransmissions may expire while waiting for a new default Network, in which case the 137 * Session will automatically close and {@link #onClosedWithException(IkeException)} will 138 * be fired. 139 * </ul> 140 * 141 * <p>There are three types of mobility events: 142 * 143 * <ul> 144 * <li>The underlying Network changing, or 145 * <li>The local address disappearing from the current (and unchanged) underlying Network, or 146 * <li>The remote address changing. 147 * </ul> 148 * 149 * @param connectionInfo the updated IkeSessionConnectionInfo for the Session. 150 * @hide 151 */ 152 @SystemApi onIkeSessionConnectionInfoChanged( @onNull IkeSessionConnectionInfo connectionInfo)153 default void onIkeSessionConnectionInfoChanged( 154 @NonNull IkeSessionConnectionInfo connectionInfo) {} 155 } 156