1/* 2 * Copyright (c) 2023 Huawei Device Co., Ltd. 3 * Licensed under the Apache License, Version 2.0 (the "License"); 4 * you may not use this file except in compliance with the License. 5 * You may obtain a copy of the License at 6 * 7 * http://www.apache.org/licenses/LICENSE-2.0 8 * 9 * Unless required by applicable law or agreed to in writing, software 10 * distributed under the License is distributed on an "AS IS" BASIS, 11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 * See the License for the specific language governing permissions and 13 * limitations under the License. 14 */ 15 16/** 17 * @file 18 * @kit ConnectivityKit 19 */ 20 21import type { AsyncCallback, Callback } from './@ohos.base'; 22 23/** 24 * Provides APIs for mobile applications to access different SEs in mobile devices, such as SIMs or embedded SEs. 25 * See "Open Mobile API Specification". 26 * 27 * @namespace omapi 28 * @syscap SystemCapability.Communication.SecureElement 29 * @since 10 30 */ 31declare namespace omapi { 32 /** 33 * Establish a new connection that can be used to connect to all the SEs available in the system. 34 * The connection process can be quite long, so it happens in an asynchronous way. It is usable only 35 * if the specified callback is called or if isConnected() returns true. 36 * 37 * @param { 'serviceState' } type nfc serviceState 38 * @param { Callback<ServiceState> } callback - The callback to return the service. 39 * @returns { SEService } The new SEService instance. 40 * @throws { BusinessError } 401 - The parameter check failed. 41 * @throws { BusinessError } 801 - Capability not supported. 42 * @syscap SystemCapability.Communication.SecureElement 43 * @since 10 44 */ 45 function newSEService(type: 'serviceState', callback: Callback<ServiceState>): SEService; 46 47 /** 48 * SEService realizes the communication to available SEs on the device. 49 * 50 * @typedef SEService 51 * @syscap SystemCapability.Communication.SecureElement 52 * @since 10 53 */ 54 export interface SEService { 55 /** 56 * Returns the list of available SE readers. There must be no duplicated objects in the returned list. 57 * All available readers SHALL be listed even if no card is inserted. 58 * 59 * @returns { Reader[] } The list of available SE readers. 60 * @throws { BusinessError } 801 - Capability not supported. 61 * @syscap SystemCapability.Communication.SecureElement 62 * @since 10 63 */ 64 getReaders(): Reader[]; 65 66 /** 67 * Checks whether or not the service is connected. 68 * 69 * @returns { boolean } True if the service is connected. 70 * @throws { BusinessError } 801 - Capability not supported. 71 * @syscap SystemCapability.Communication.SecureElement 72 * @since 10 73 */ 74 isConnected(): boolean; 75 76 /** 77 * Releases all SE resources allocated by this SEService. As a result isConnected() will return false. 78 * 79 * @throws { BusinessError } 801 - Capability not supported. 80 * @syscap SystemCapability.Communication.SecureElement 81 * @since 10 82 */ 83 shutdown(): void; 84 85 /** 86 * Returns the version of the Open Mobile API Specification this implementation is based on. 87 * 88 * @returns { string } The Open Mobile API version (e.g. “3.3” for Open Mobile API Specification version 3.3). 89 * @throws { BusinessError } 801 - Capability not supported. 90 * @syscap SystemCapability.Communication.SecureElement 91 * @since 10 92 */ 93 getVersion(): string; 94 } 95 96 /** 97 * Reader represents the SE readers supported by this device. 98 * 99 * @typedef Reader 100 * @syscap SystemCapability.Communication.SecureElement 101 * @since 10 102 */ 103 export interface Reader { 104 /** 105 * Returns the name of this reader. 106 * If this reader is a SIM reader, then its name must be "SIM[slot]". 107 * If the reader is an embedded SE reader, then its name must be "eSE[slot]". 108 * 109 * @returns { string } The reader name, as a String. 110 * @throws { BusinessError } 801 - Capability not supported. 111 * @syscap SystemCapability.Communication.SecureElement 112 * @since 10 113 */ 114 getName(): string; 115 116 /** 117 * Checks if a SE is present in this reader. 118 * 119 * @returns { boolean } True if the SE is present, false otherwise. 120 * @throws { BusinessError } 801 - Capability not supported. 121 * @throws { BusinessError } 3300101 - IllegalStateError, service state exception. 122 * @syscap SystemCapability.Communication.SecureElement 123 * @since 10 124 */ 125 isSecureElementPresent(): boolean; 126 127 /** 128 * Connects to a SE in this reader. 129 * This method prepares (initializes) the SE for communication before the session object is returned. 130 * There might be multiple sessions opened at the same time on the same reader. 131 * 132 * @returns { Session } A Session object to be used to create channels. 133 * @throws { BusinessError } 801 - Capability not supported. 134 * @throws { BusinessError } 3300101 - IllegalStateError, service state exception. 135 * @throws { BusinessError } 3300104 - IOError, there is a communication problem to the reader or the SE. 136 * @syscap SystemCapability.Communication.SecureElement 137 * @since 10 138 */ 139 openSession(): Session; 140 141 /** 142 * Close all the sessions opened on this reader. All the channels opened by all these sessions will be closed. 143 * 144 * @throws { BusinessError } 801 - Capability not supported. 145 * @throws { BusinessError } 3300101 - IllegalStateError, service state exception. 146 * @syscap SystemCapability.Communication.SecureElement 147 * @since 10 148 */ 149 closeSessions(): void; 150 } 151 152 /** 153 * Session represent a connection session to one of the SEs available on the device. These objects 154 * can be used to get a communication channel with an applet in the SE. This channel can be the basic channel 155 * or a logical channel. 156 * 157 * @typedef Session 158 * @syscap SystemCapability.Communication.SecureElement 159 * @since 10 160 */ 161 export interface Session { 162 /** 163 * Get the reader that provides this session. 164 * 165 * @returns { Reader } The Reader object. 166 * @throws { BusinessError } 801 - Capability not supported. 167 * @syscap SystemCapability.Communication.SecureElement 168 * @since 10 169 */ 170 getReader(): Reader; 171 172 /** 173 * Get the ATR of this SE. 174 * A empty array SHALL be returned if the ATR for this SE is not available. 175 * 176 * @returns { number[] } The ATR as a number array or empty array. 177 * @throws { BusinessError } 801 - Capability not supported. 178 * @throws { BusinessError } 3300101 - IllegalStateError, service state exception. 179 * @syscap SystemCapability.Communication.SecureElement 180 * @since 10 181 */ 182 getATR(): number[]; 183 184 /** 185 * Close the connection with the SE. This will close any channels opened by this application with this SE. 186 * 187 * @throws { BusinessError } 801 - Capability not supported. 188 * @throws { BusinessError } 3300101 - IllegalStateError, service state exception. 189 * @syscap SystemCapability.Communication.SecureElement 190 * @since 10 191 */ 192 close(): void; 193 194 /** 195 * Check if this session is closed. 196 * 197 * @returns { boolean } True if the session is closed, false otherwise. 198 * @throws { BusinessError } 801 - Capability not supported. 199 * @syscap SystemCapability.Communication.SecureElement 200 * @since 10 201 */ 202 isClosed(): boolean; 203 204 /** 205 * Close any channels opened on this session. 206 * 207 * @throws { BusinessError } 801 - Capability not supported. 208 * @throws { BusinessError } 3300101 - IllegalStateError, service state exception. 209 * @syscap SystemCapability.Communication.SecureElement 210 * @since 10 211 */ 212 closeChannels(): void; 213 214 /** 215 * This method is provided to ease the development of mobile applications and for backward compatibility with 216 * existing applications. This method is equivalent to openBasicChannel(aid, P2=0x00). 217 * 218 * @param { number[] } aid - The AID of the applet to be selected on this channel, as a byte array, 219 * or Null if no applet is to be selected. 220 * @returns { Promise<Channel> } An instance of channel if available. Null if the SE is unable to provide. 221 * @throws { BusinessError } 401 - The parameter check failed. 222 * @throws { BusinessError } 801 - Capability not supported. 223 * @throws { BusinessError } 3300101 - IllegalStateError, an attempt is made to use an SE session that has been closed. 224 * @throws { BusinessError } 3300102 - NoSuchElementError, the AID on the SE is not available or cannot be selected. 225 * @throws { BusinessError } 3300103 - SecurityError, the calling application cannot be granted access to this AID or the default applet on this session. 226 * @throws { BusinessError } 3300104 - IOError, there is a communication problem to the reader or the SE. 227 * @syscap SystemCapability.Communication.SecureElement 228 * @since 10 229 */ 230 openBasicChannel(aid: number[]): Promise<Channel>; 231 232 /** 233 * This method is provided to ease the development of mobile applications and for backward compatibility with 234 * existing applications. This method is equivalent to openBasicChannel(aid, P2=0x00). 235 * 236 * @param { number[] } aid - The AID of the applet to be selected on this channel, as a byte array, 237 * or Null if no applet is to be selected. 238 * @param { AsyncCallback<Channel> } callback - The callback to return the Channel object. Null if the SE is unable to provide. 239 * @throws { BusinessError } 401 - The parameter check failed. 240 * @throws { BusinessError } 801 - Capability not supported. 241 * @throws { BusinessError } 3300101 - IllegalStateError, an attempt is made to use an SE session that has been closed. 242 * @throws { BusinessError } 3300102 - NoSuchElementError, the AID on the SE is not available or cannot be selected. 243 * @throws { BusinessError } 3300103 - SecurityError, the calling application cannot be granted access to this AID or the default applet on this session. 244 * @throws { BusinessError } 3300104 - IOError, there is a communication problem to the reader or the SE. 245 * @syscap SystemCapability.Communication.SecureElement 246 * @since 10 247 */ 248 openBasicChannel(aid: number[], callback: AsyncCallback<Channel>): void; 249 250 /** 251 * Get access to the basic channel, as defined in [ISO 7816-4] (the one that has number 0). The obtained object 252 * is an instance of the channel class. 253 * Once this channel has been opened by a device application, it is considered as ‘locked’ by this device 254 * application, and other calls to this method SHALL return Null, until the channel is closed. 255 * Some SE plug-ins, such as those handling UICC, may prevent the use of the Basic Channel. In these cases, 256 * a Null value SHALL be returned. 257 * P2 is normally 0x00. The device SHOULD allow any value for P2 and SHALL allow the following values: 258 * 0x00, 0x04, 0x08, 0x0C (as defined in [ISO 7816-4]). 259 * 260 * @param { number[] } aid - The AID of the applet to be selected on this channel, as a byte array, 261 * or Null if no applet is to be selected. 262 * @param { number } p2 - The P2 parameter of the SELECT APDU executed on this channel. 263 * @returns { Promise<Channel> } An instance of channel if available. Null if the SE is unable to provide. 264 * @throws { BusinessError } 401 - The parameter check failed. 265 * @throws { BusinessError } 801 - Capability not supported. 266 * @throws { BusinessError } 3300101 - IllegalStateError, an attempt is made to use an SE session that has been closed. 267 * @throws { BusinessError } 3300102 - NoSuchElementError, the AID on the SE is not available or cannot be selected. 268 * @throws { BusinessError } 3300103 - SecurityError, the calling application cannot be granted access to this AID or the default applet on this session. 269 * @throws { BusinessError } 3300104 - IOError, there is a communication problem to the reader or the SE. 270 * @syscap SystemCapability.Communication.SecureElement 271 * @since 10 272 */ 273 openBasicChannel(aid: number[], p2: number): Promise<Channel>; 274 275 /** 276 * Get access to the basic channel, as defined in [ISO 7816-4] (the one that has number 0). The obtained object 277 * is an instance of the channel class. 278 * Once this channel has been opened by a device application, it is considered as ‘locked’ by this device 279 * application, and other calls to this method SHALL return Null, until the channel is closed. 280 * Some SE plug-ins, such as those handling UICC, may prevent the use of the Basic Channel. In these cases, 281 * a Null value SHALL be returned. 282 * P2 is normally 0x00. The device SHOULD allow any value for P2 and SHALL allow the following values: 283 * 0x00, 0x04, 0x08, 0x0C (as defined in [ISO 7816-4]). 284 * 285 * @param { number[] } aid - The AID of the applet to be selected on this channel, as a byte array, 286 * or Null if no applet is to be selected. 287 * @param { number } p2 - The P2 parameter of the SELECT APDU executed on this channel. 288 * @param { AsyncCallback<Channel> } callback - The callback to return the Channel object. Null if the SE is unable to provide. 289 * @throws { BusinessError } 401 - The parameter check failed. 290 * @throws { BusinessError } 801 - Capability not supported. 291 * @throws { BusinessError } 3300101 - IllegalStateError, an attempt is made to use an SE session that has been closed. 292 * @throws { BusinessError } 3300102 - NoSuchElementError, the AID on the SE is not available or cannot be selected. 293 * @throws { BusinessError } 3300103 - SecurityError, the calling application cannot be granted access to this AID or the default applet on this session. 294 * @throws { BusinessError } 3300104 - IOError, there is a communication problem to the reader or the SE. 295 * @syscap SystemCapability.Communication.SecureElement 296 * @since 10 297 */ 298 openBasicChannel(aid: number[], p2: number, callback: AsyncCallback<Channel>): void; 299 300 /** 301 * This method is provided to ease the development of mobile applications and for backward compatibility with 302 * existing applications. This method is equivalent to openLogicalChannel(aid, P2=0x00). 303 * 304 * @param { number[] } aid - The AID of the applet to be selected on this channel, as a byte array. 305 * @returns { Promise<Channel> } An instance of channel if available. Null if the SE is unable to provide. 306 * A new logical channel or is unable to retrieve Access Control rules due to the lack of an available logical channel. 307 * @throws { BusinessError } 401 - The parameter check failed. 308 * @throws { BusinessError } 801 - Capability not supported. 309 * @throws { BusinessError } 3300101 - IllegalStateError, an attempt is made to use an SE session that has been closed. 310 * @throws { BusinessError } 3300102 - NoSuchElementError, the AID on the SE is not available or cannot be selected or 311 * a logical channel is already open to a non-multi-selectable applet. 312 * @throws { BusinessError } 3300103 - SecurityError, the calling application cannot be granted access to this AID or the default applet on this session. 313 * @throws { BusinessError } 3300104 - IOError, there is a communication problem to the reader or the SE. 314 * @syscap SystemCapability.Communication.SecureElement 315 * @since 10 316 */ 317 openLogicalChannel(aid: number[]): Promise<Channel>; 318 319 /** 320 * This method is provided to ease the development of mobile applications and for backward compatibility with 321 * existing applications. This method is equivalent to openLogicalChannel(aid, P2=0x00). 322 * 323 * @param { number[] } aid - The AID of the applet to be selected on this channel, as a byte array. 324 * @param { AsyncCallback<Channel> } callback - The callback to return the Channel object. Null if the SE is unable to provide. 325 * A new logical channel or is unable to retrieve Access Control rules due to the lack of an available logical channel. 326 * @throws { BusinessError } 401 - The parameter check failed. 327 * @throws { BusinessError } 801 - Capability not supported. 328 * @throws { BusinessError } 3300101 - IllegalStateError, an attempt is made to use an SE session that has been closed. 329 * @throws { BusinessError } 3300102 - NoSuchElementError, the AID on the SE is not available or cannot be selected or 330 * a logical channel is already open to a non-multi-selectable applet. 331 * @throws { BusinessError } 3300103 - SecurityError, the calling application cannot be granted access to this AID or the default applet on this session. 332 * @throws { BusinessError } 3300104 - IOError, there is a communication problem to the reader or the SE. 333 * @syscap SystemCapability.Communication.SecureElement 334 * @since 10 335 */ 336 openLogicalChannel(aid: number[], callback: AsyncCallback<Channel>): void; 337 338 /** 339 * Open a logical channel with the SE, selecting the applet represented by the given AID (when the AID is not 340 * Null and the length of the AID is not 0). 341 * If the length of the AID is 0, the method will select the Issuer Security Domain of the SE by sending a SELECT 342 * command with 0 length AID as defined in [GPCS]. 343 * If the AID is Null, the method SHALL only send a MANAGE CHANNEL Open and SHALL NOT send a 344 * SELECT command. In this case, the default applet associated to the logical channel will be selected by default. 345 * P2 is normally 0x00. The device SHOULD allow any value for P2 and SHALL allow the following values: 346 * 0x00, 0x04, 0x08, 0x0C (as defined in [ISO 7816-4]). 347 * 348 * @param { number[] } aid - The AID of the applet to be selected on this channel, as a byte array. 349 * @param { number } p2 - The P2 parameter of the SELECT APDU executed on this channel. 350 * @returns { Promise<Channel> } An instance of channel if available. Null if the SE is unable to provide. 351 * A new logical channel or is unable to retrieve Access Control rules due to the lack of an available logical channel. 352 * @throws { BusinessError } 401 - The parameter check failed. 353 * @throws { BusinessError } 801 - Capability not supported. 354 * @throws { BusinessError } 3300101 - IllegalStateError, an attempt is made to use an SE session that has been closed. 355 * @throws { BusinessError } 3300102 - NoSuchElementError, the AID on the SE is not available or cannot be selected or 356 * a logical channel is already open to a non-multi-selectable applet. 357 * @throws { BusinessError } 3300103 - SecurityError, the calling application cannot be granted access to this AID or the default applet on this session. 358 * @throws { BusinessError } 3300104 - IOError, there is a communication problem to the reader or the SE. 359 * @syscap SystemCapability.Communication.SecureElement 360 * @since 10 361 */ 362 openLogicalChannel(aid: number[], p2: number): Promise<Channel>; 363 364 /** 365 * Open a logical channel with the SE, selecting the applet represented by the given AID (when the AID is not 366 * Null and the length of the AID is not 0). 367 * If the length of the AID is 0, the method will select the Issuer Security Domain of the SE by sending a SELECT 368 * command with 0 length AID as defined in [GPCS]. 369 * If the AID is Null, the method SHALL only send a MANAGE CHANNEL Open and SHALL NOT send a 370 * SELECT command. In this case, the default applet associated to the logical channel will be selected by default. 371 * P2 is normally 0x00. The device SHOULD allow any value for P2 and SHALL allow the following values: 372 * 0x00, 0x04, 0x08, 0x0C (as defined in [ISO 7816-4]). 373 * 374 * @param { number[] } aid - The AID of the applet to be selected on this channel, as a byte array. 375 * @param { number } p2 - The P2 parameter of the SELECT APDU executed on this channel. 376 * @param { AsyncCallback<Channel> } callback - The callback to return the instance of channel. Null if the SE is unable to provide. 377 * @throws { BusinessError } 401 - The parameter check failed. 378 * @throws { BusinessError } 801 - Capability not supported. 379 * @throws { BusinessError } 3300101 - IllegalStateError, an attempt is made to use an SE session that has been closed. 380 * @throws { BusinessError } 3300102 - NoSuchElementError, the AID on the SE is not available or cannot be selected or 381 * a logical channel is already open to a non-multi-selectable applet. 382 * @throws { BusinessError } 3300103 - SecurityError, the calling application cannot be granted access to this AID or the default applet on this session. 383 * @throws { BusinessError } 3300104 - IOError, there is a communication problem to the reader or the SE. 384 * @syscap SystemCapability.Communication.SecureElement 385 * @since 10 386 */ 387 openLogicalChannel(aid: number[], p2: number, callback: AsyncCallback<Channel>): void; 388 } 389 390 /** 391 * Channel represents an [ISO 7816-4] channel opened to a SE. It can be either a logical channel or the basic channel. 392 * 393 * @typedef Channel 394 * @syscap SystemCapability.Communication.SecureElement 395 * @since 10 396 */ 397 export interface Channel { 398 /** 399 * Get the session that has opened this channel. 400 * 401 * @returns { Session } The Session object this channel is bound to. 402 * @throws { BusinessError } 801 - Capability not supported. 403 * @syscap SystemCapability.Communication.SecureElement 404 * @since 10 405 */ 406 getSession(): Session; 407 408 /** 409 * Closes this channel to the SE. 410 * If the method is called when the channel is already closed, this method SHALL be ignored. 411 * 412 * @throws { BusinessError } 801 - Capability not supported. 413 * @syscap SystemCapability.Communication.SecureElement 414 * @since 10 415 */ 416 close(): void; 417 418 /** 419 * Checks whether this channel is the basic channel. 420 * 421 * @returns { boolean } True if this channel is a basic channel, false otherwise. 422 * @throws { BusinessError } 801 - Capability not supported. 423 * @syscap SystemCapability.Communication.SecureElement 424 * @since 10 425 */ 426 isBasicChannel(): boolean; 427 428 /** 429 * Checks if this channel is closed. 430 * 431 * @returns { boolean } True if the channel is closed, false otherwise. 432 * @throws { BusinessError } 801 - Capability not supported. 433 * @syscap SystemCapability.Communication.SecureElement 434 * @since 10 435 */ 436 isClosed(): boolean; 437 438 /** 439 * Returns the data as received from the application select command, including the status word received 440 * at applet selection. 441 * 442 * @returns { number[] } The data as returned by the application select command inclusive of the status word. 443 * @throws { BusinessError } 801 - Capability not supported. 444 * @syscap SystemCapability.Communication.SecureElement 445 * @since 10 446 */ 447 getSelectResponse(): number[]; 448 449 /** 450 * Transmit an APDU command (as per ISO/IEC 7816) to the SE. 451 * 452 * @param { number[] } command - The APDU command to be transmitted, as a byte array. 453 * @returns { Promise<number[]> } The response received, as a byte array. 454 * @throws { BusinessError } 401 - The parameter check failed. 455 * @throws { BusinessError } 801 - Capability not supported. 456 * @throws { BusinessError } 3300101 - IllegalStateError, an attempt is made to use an SE session or channel that has been closed. 457 * @throws { BusinessError } 3300103 - SecurityError, the command is filtered by the security policy. 458 * @throws { BusinessError } 3300104 - IOError, there is a communication problem to the reader or the SE. 459 * @syscap SystemCapability.Communication.SecureElement 460 * @since 10 461 */ 462 transmit(command: number[]): Promise<number[]>; 463 464 /** 465 * Transmit an APDU command (as per ISO/IEC 7816) to the SE. 466 * 467 * @param { number[] } command - The APDU command to be transmitted, as a byte array. 468 * @param { AsyncCallback<number[]> } callback - The callback to return the response received, as a byte array. 469 * @throws { BusinessError } 401 - The parameter check failed. 470 * @throws { BusinessError } 801 - Capability not supported. 471 * @throws { BusinessError } 3300101 - IllegalStateError, an attempt is made to use an SE session or channel that has been closed. 472 * @throws { BusinessError } 3300103 - SecurityError, the command is filtered by the security policy. 473 * @throws { BusinessError } 3300104 - IOError, there is a communication problem to the reader or the SE. 474 * @syscap SystemCapability.Communication.SecureElement 475 * @since 10 476 */ 477 transmit(command: number[], callback: AsyncCallback<number[]>): void; 478 } 479 480 /** 481 * Secure Element service state definition. 482 * 483 * @enum { number } 484 * @syscap SystemCapability.Communication.SecureElement 485 * @since 10 486 */ 487 enum ServiceState { 488 /** 489 * Service is disconnected. 490 * 491 * @syscap SystemCapability.Communication.SecureElement 492 * @since 10 493 */ 494 DISCONNECTED = 0, 495 496 /** 497 * Service is connected. 498 * 499 * @syscap SystemCapability.Communication.SecureElement 500 * @since 10 501 */ 502 CONNECTED = 1 503 } 504} 505export default omapi;