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