1 /* 2 * Copyright (C) 2022 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 com.android.server.wifi.hal; 18 19 import android.annotation.Nullable; 20 import android.net.MacAddress; 21 import android.net.wifi.aware.ConfigRequest; 22 import android.net.wifi.aware.PublishConfig; 23 import android.net.wifi.aware.SubscribeConfig; 24 import android.net.wifi.aware.WifiAwareDataPathSecurityConfig; 25 26 import com.android.server.wifi.aware.Capabilities; 27 28 /** Abstraction of WifiNanIface */ 29 public interface IWifiNanIface { 30 /** 31 * Enable verbose logging. 32 */ enableVerboseLogging(boolean verbose)33 void enableVerboseLogging(boolean verbose); 34 35 /** 36 * Register a framework callback to receive notifications from the HAL. 37 * 38 * @param callback Instance of {@link WifiNanIface.Callback}. 39 * @return true if successful, false otherwise 40 */ registerFrameworkCallback(WifiNanIface.Callback callback)41 boolean registerFrameworkCallback(WifiNanIface.Callback callback); 42 43 /** 44 * Get the name of this interface. 45 * 46 * @return Name of this interface, or null on error. 47 */ 48 @Nullable getName()49 String getName(); 50 51 /** 52 * Query the firmware's capabilities. 53 * 54 * @param transactionId Transaction ID for the transaction - used in the async callback to 55 * match with the original request. 56 */ getCapabilities(short transactionId)57 boolean getCapabilities(short transactionId); 58 59 /** 60 * Enable and configure Aware. 61 * 62 * @param transactionId Transaction ID for the transaction - used in the 63 * async callback to match with the original request. 64 * @param configRequest Requested Aware configuration. 65 * @param notifyIdentityChange Indicates whether to get address change callbacks. 66 * @param initialConfiguration Specifies whether initial configuration 67 * (true) or an update (false) to the configuration. 68 * @param rangingEnabled Indicates whether to enable ranging. 69 * @param isInstantCommunicationEnabled Indicates whether to enable instant communication 70 * @param instantModeChannel 71 * @param clusterId Indicate which cluster to join. 72 * @param macAddressRandomizationIntervalSec 73 * @param powerParameters Instance of {@link WifiNanIface.PowerParameters} containing the 74 * parameters to use in our config request. 75 */ enableAndConfigure(short transactionId, ConfigRequest configRequest, boolean notifyIdentityChange, boolean initialConfiguration, boolean rangingEnabled, boolean isInstantCommunicationEnabled, int instantModeChannel, int clusterId, int macAddressRandomizationIntervalSec, WifiNanIface.PowerParameters powerParameters)76 boolean enableAndConfigure(short transactionId, ConfigRequest configRequest, 77 boolean notifyIdentityChange, boolean initialConfiguration, boolean rangingEnabled, 78 boolean isInstantCommunicationEnabled, int instantModeChannel, int clusterId, 79 int macAddressRandomizationIntervalSec, WifiNanIface.PowerParameters powerParameters); 80 81 /** 82 * Disable Aware. 83 * 84 * @param transactionId Transaction ID for the transaction - 85 * used in the async callback to match with the original request. 86 */ disable(short transactionId)87 boolean disable(short transactionId); 88 89 /** 90 * Start or modify a service publish session. 91 * @param transactionId Transaction ID for the transaction - 92 * used in the async callback to match with the original request. 93 * @param publishId ID of the requested session - 0 to request a new publish 94 * session. 95 * @param publishConfig Configuration of the discovery session. 96 * @param nanIdentityKey 97 */ publish(short transactionId, byte publishId, PublishConfig publishConfig, byte[] nanIdentityKey)98 boolean publish(short transactionId, byte publishId, PublishConfig publishConfig, 99 byte[] nanIdentityKey); 100 101 /** 102 * Start or modify a service subscription session. 103 * @param transactionId Transaction ID for the transaction - 104 * used in the async callback to match with the original request. 105 * @param subscribeId ID of the requested session - 0 to request a new 106 * subscribe session. 107 * @param subscribeConfig Configuration of the discovery session. 108 * @param nanIdentityKey 109 */ subscribe(short transactionId, byte subscribeId, SubscribeConfig subscribeConfig, byte[] nanIdentityKey)110 boolean subscribe(short transactionId, byte subscribeId, SubscribeConfig subscribeConfig, 111 byte[] nanIdentityKey); 112 113 /** 114 * Send a message through an existing discovery session. 115 * 116 * @param transactionId Transaction ID for the transaction - 117 * used in the async callback to match with the original request. 118 * @param pubSubId ID of the existing publish/subscribe session. 119 * @param requestorInstanceId ID of the peer to communicate with - obtained 120 * through a previous discovery (match) operation with that peer. 121 * @param dest MAC address of the peer to communicate with - obtained 122 * together with requestorInstanceId. 123 * @param message Message. 124 */ sendMessage(short transactionId, byte pubSubId, int requestorInstanceId, MacAddress dest, byte[] message)125 boolean sendMessage(short transactionId, byte pubSubId, int requestorInstanceId, 126 MacAddress dest, byte[] message); 127 128 /** 129 * Terminate a publish discovery session. 130 * 131 * @param transactionId Transaction ID for the transaction - 132 * used in the async callback to match with the original request. 133 * @param pubSubId ID of the publish/subscribe session - obtained when 134 * creating a session. 135 */ stopPublish(short transactionId, byte pubSubId)136 boolean stopPublish(short transactionId, byte pubSubId); 137 138 /** 139 * Terminate a subscribe discovery session. 140 * 141 * @param transactionId transactionId Transaction ID for the transaction - 142 * used in the async callback to match with the original request. 143 * @param pubSubId ID of the publish/subscribe session - obtained when 144 * creating a session. 145 */ stopSubscribe(short transactionId, byte pubSubId)146 boolean stopSubscribe(short transactionId, byte pubSubId); 147 148 /** 149 * Create an Aware network interface. This only creates the Linux interface - it doesn't 150 * actually create the data connection. 151 * 152 * @param transactionId Transaction ID for the transaction - used in the async callback to 153 * match with the original request. 154 * @param interfaceName The name of the interface, e.g. "aware0". 155 */ createAwareNetworkInterface(short transactionId, String interfaceName)156 boolean createAwareNetworkInterface(short transactionId, String interfaceName); 157 158 /** 159 * Deletes an Aware network interface. The data connection can (should?) be torn 160 * down previously. 161 * 162 * @param transactionId Transaction ID for the transaction - used in the async callback to 163 * match with the original request. 164 * @param interfaceName The name of the interface, e.g. "aware0". 165 */ deleteAwareNetworkInterface(short transactionId, String interfaceName)166 boolean deleteAwareNetworkInterface(short transactionId, String interfaceName); 167 168 /** 169 * Initiates setting up a data-path between device and peer. Security is provided by either 170 * PMK or Passphrase (not both) - if both are null then an open (unencrypted) link is set up. 171 * 172 * @param transactionId Transaction ID for the transaction - used in the async callback to 173 * match with the original request. 174 * @param peerId ID of the peer ID to associate the data path with. A value of 0 175 * indicates that not associated with an existing session. 176 * @param channelRequestType Indicates whether the specified channel is available, if available 177 * requested or forced (resulting in failure if cannot be 178 * accommodated). 179 * @param channel The channel on which to set up the data-path. 180 * @param peer The MAC address of the peer to create a connection with. 181 * @param interfaceName The interface on which to create the data connection. 182 * @param isOutOfBand Is the data-path out-of-band (i.e. without a corresponding Aware 183 * discovery 184 * session). 185 * @param appInfo Arbitrary binary blob transmitted to the peer. 186 * @param capabilities The capabilities of the firmware. 187 * @param securityConfig Security config to encrypt the data-path 188 */ initiateDataPath(short transactionId, int peerId, int channelRequestType, int channel, MacAddress peer, String interfaceName, boolean isOutOfBand, byte[] appInfo, Capabilities capabilities, WifiAwareDataPathSecurityConfig securityConfig, byte pubSubId)189 boolean initiateDataPath(short transactionId, int peerId, int channelRequestType, 190 int channel, MacAddress peer, String interfaceName, 191 boolean isOutOfBand, byte[] appInfo, Capabilities capabilities, 192 WifiAwareDataPathSecurityConfig securityConfig, byte pubSubId); 193 194 /** 195 * Responds to a data request from a peer. Security is provided by either PMK or Passphrase (not 196 * both) - if both are null then an open (unencrypted) link is set up. 197 * 198 * @param transactionId Transaction ID for the transaction - used in the async callback to 199 * match with the original request. 200 * @param accept Accept (true) or reject (false) the original call. 201 * @param ndpId The NDP (Aware data path) ID. Obtained from the request callback. 202 * @param interfaceName The interface on which the data path will be setup. Obtained from the 203 * request callback. 204 * @param appInfo Arbitrary binary blob transmitted to the peer. 205 * @param isOutOfBand Is the data-path out-of-band (i.e. without a corresponding Aware 206 * discovery 207 * session). 208 * @param capabilities The capabilities of the firmware. 209 * @param securityConfig Security config to encrypt the data-path 210 */ respondToDataPathRequest(short transactionId, boolean accept, int ndpId, String interfaceName, byte[] appInfo, boolean isOutOfBand, Capabilities capabilities, WifiAwareDataPathSecurityConfig securityConfig, byte pubSubId)211 boolean respondToDataPathRequest(short transactionId, boolean accept, int ndpId, 212 String interfaceName, byte[] appInfo, 213 boolean isOutOfBand, Capabilities capabilities, 214 WifiAwareDataPathSecurityConfig securityConfig, byte pubSubId); 215 216 /** 217 * Terminate an existing data-path (does not delete the interface). 218 * 219 * @param transactionId Transaction ID for the transaction - used in the async callback to 220 * match with the original request. 221 * @param ndpId The NDP (Aware data path) ID to be terminated. 222 */ endDataPath(short transactionId, int ndpId)223 boolean endDataPath(short transactionId, int ndpId); 224 225 /** 226 * Response to a NAN pairing request for this from this session 227 * 228 * @param transactionId Transaction ID for the transaction - used in the 229 * async callback to match with the original request. 230 * @param pairingId The id of the current pairing session 231 * @param accept True if accpect, false otherwise 232 * @param pairingIdentityKey NAN identity key 233 * @param requestType Setup or verification 234 * @param pmk credential for the pairing verification 235 * @param password credential for the pairing setup 236 * @param akm Key exchange method is used for pairing 237 * @return True if the request send succeed. 238 */ respondToPairingRequest(short transactionId, int pairingId, boolean accept, byte[] pairingIdentityKey, boolean enablePairingCache, int requestType, byte[] pmk, String password, int akm, int cipherSuite)239 boolean respondToPairingRequest(short transactionId, int pairingId, boolean accept, 240 byte[] pairingIdentityKey, boolean enablePairingCache, int requestType, byte[] pmk, 241 String password, int akm, int cipherSuite); 242 243 /** 244 * Initiate a NAN pairing request for this publish/subscribe session 245 * 246 * @param transactionId Transaction ID for the transaction - used in the 247 * async callback to match with the original request. 248 * @param peerId ID of the peer. Obtained through previous communication (a 249 * match indication). 250 * @param pairingIdentityKey NAN identity key 251 * @param requestType Setup or verification 252 * @param pmk credential for the pairing verification 253 * @param password credential for the pairing setup 254 * @param akm Key exchange method is used for pairing 255 * @return True if the request send succeed. 256 */ initiateNanPairingRequest(short transactionId, int peerId, MacAddress peer, byte[] pairingIdentityKey, boolean enablePairingCache, int requestType, byte[] pmk, String password, int akm, int cipherSuite)257 boolean initiateNanPairingRequest(short transactionId, int peerId, MacAddress peer, 258 byte[] pairingIdentityKey, boolean enablePairingCache, int requestType, byte[] pmk, 259 String password, int akm, int cipherSuite); 260 261 /** 262 * Terminate an existing pairing setup 263 * 264 * @param transactionId Transaction ID for the transaction - used in the async callback to 265 * match with the original request. 266 * @param pairingId The id of the pairing session 267 */ endPairing(short transactionId, int pairingId)268 boolean endPairing(short transactionId, int pairingId); 269 270 /** 271 * Initiate a bootstrapping request for this publish/subscribe session 272 * 273 * @param transactionId Transaction ID for the transaction - used in the 274 * async callback to match with the original request. 275 * @param peerId ID of the peer. Obtained through previous communication (a 276 * match indication). 277 * @param peer The MAC address of the peer to create a connection with. 278 * @param method the proposed bootstrapping method 279 * @param pubSubId ID of the publish/subscribe session - obtained when creating a session. 280 * @param isComeBack If the request is for a previous comeback response 281 * @return True if the request send succeed. 282 */ initiateNanBootstrappingRequest(short transactionId, int peerId, MacAddress peer, int method, byte[] cookie, byte pubSubId, boolean isComeBack)283 boolean initiateNanBootstrappingRequest(short transactionId, int peerId, MacAddress peer, 284 int method, byte[] cookie, byte pubSubId, boolean isComeBack); 285 286 /** 287 * Respond to a bootstrapping request 288 * 289 * @param transactionId Transaction ID for the transaction - used in the 290 * async callback to match with the original request. 291 * @param bootstrappingId the id of this bootstrapping session 292 * @param accept True if the proposed bootstrapping method is accepted. 293 * @param pubSubId ID of the publish/subscribe session - obtained when creating a 294 * session. 295 * @return True if the request send succeed. 296 */ respondToNanBootstrappingRequest(short transactionId, int bootstrappingId, boolean accept, byte pubSubId)297 boolean respondToNanBootstrappingRequest(short transactionId, int bootstrappingId, 298 boolean accept, byte pubSubId); 299 300 /** 301 * Suspend the specified Aware session. During the suspend state, the Wi-Fi Aware device 302 * must not transmit or receive frames for this Wi-Fi Aware discovery session including any 303 * active NDPs. If all discovery sessions are suspended then the Wi-Fi Aware device must not 304 * transmit or receive any Wi-Fi Aware frames. 305 * 306 * @param transactionId Transaction ID for the transaction - used in the 307 * async callback to match with the original request. 308 * @param pubSubId ID of the existing publish/subscribe session. 309 * @return True if the request sent successfully. 310 */ suspend(short transactionId, byte pubSubId)311 boolean suspend(short transactionId, byte pubSubId); 312 313 /** 314 * Resume the specified (suspended) Aware session. Resume cancels an ongoing suspend for this 315 * Wi-Fi Aware discovery session and automatically resumes the session and any associated 316 * NDPs to the state before they were suspended. The Wi-Fi Aware resume operation should be 317 * faster than recreating the corresponding discovery session and NDPs with the same benefit of 318 * power. 319 * 320 * @param transactionId Transaction ID for the transaction - used in the 321 * async callback to match with the original request. 322 * @param pubSubId ID of the existing publish/subscribe session. 323 * @return True if the request sent successfully. 324 */ resume(short transactionId, byte pubSubId)325 boolean resume(short transactionId, byte pubSubId); 326 } 327