include/smartcard.h

   1 /*
   2  * Copyright (c) 2012, 2013 Samsung Electronics Co., Ltd.
   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 #ifndef __smartcard_h__
  18 #define __smartcard_h__
  19
  20 #include <tizen.h>
  21
  22 #ifdef __cplusplus
  23 extern "C" {
  24 #endif
  25
  26 /**
  27  * @file smartcard.h
  28  * @brief This file contains the smartcard api
  29  * @since_tizen 2.3.1
  30  */
  31 #ifndef SMARTCARD_API
  32 #define SMARTCARD_API
  33 #endif
  34
  35 #define SMARTCARD_ERROR_CLASS TIZEN_ERROR_SMARTCARD
  36
  37 /**
  38  * @brief Error codes reported by the smartcard API.
  39  * @since_tizen 2.3.1
  40  * @ingroup CAPI_NETWORK_SMARTCARD_SE_SERVICE_MODULE
  41  */
  42 typedef enum {
  43         SMARTCARD_ERROR_NONE = TIZEN_ERROR_NONE, /**< Successful */
  44         SMARTCARD_ERROR_GENERAL = SMARTCARD_ERROR_CLASS | 0x01, /**< A general error occurred */
  45         SMARTCARD_ERROR_IO_ERROR = TIZEN_ERROR_IO_ERROR, /**< I/O error */
  46         SMARTCARD_ERROR_NO_SUCH_ELEMENT = SMARTCARD_ERROR_CLASS | 0x02, /**< No such element error */
  47         SMARTCARD_ERROR_ILLEGAL_STATE = SMARTCARD_ERROR_CLASS | 0x03, /**< Illegal state of execution error */
  48         SMARTCARD_ERROR_INVALID_PARAMETER = TIZEN_ERROR_INVALID_PARAMETER, /**< Invalid function parameter */
  49         SMARTCARD_ERROR_ILLEGAL_REFERENCE = SMARTCARD_ERROR_CLASS | 0x04, /**< Illegal reference */
  50         SMARTCARD_ERROR_OPERATION_NOT_SUPPORTED = SMARTCARD_ERROR_CLASS | 0x05, /**< Operation not supported from SE */
  51         SMARTCARD_ERROR_PERMISSION_DENIED = TIZEN_ERROR_PERMISSION_DENIED, /**< Permission denied  */
  52         SMARTCARD_ERROR_CHANNEL_NOT_AVAILABLE = SMARTCARD_ERROR_CLASS | 0x06, /**< No channel available */
  53         SMARTCARD_ERROR_NOT_INITIALIZED = SMARTCARD_ERROR_CLASS | 0x07, /**< Smartcard service not initialized */
  54         SMARTCARD_ERROR_NOT_SUPPORTED = TIZEN_ERROR_NOT_SUPPORTED, /**< Not supported */
  55         SMARTCARD_ERROR_OUT_OF_MEMORY = TIZEN_ERROR_OUT_OF_MEMORY, /**< Out of memory */
  56 } smartcard_error_e;
  57
  58 /**
  59  * @brief Enumerations for Smartcard reader event type
  60  * @since_tizen 3.0
  61  * @ingroup CAPI_NETWORK_SMARTCARD_READER_MODULE
  62  */
  63 typedef enum {
  64         SMARTCARD_READER_EVENT_TYPE_IO_ERROR = 0, /**< This event notifies the application that I/O error occurs on smartcard reader */
  65         SMARTCARD_READER_EVENT_TYPE_INSERTED = 1, /**< This event notifies the application that smartcard reader is inserted */
  66         SMARTCARD_READER_EVENT_TYPE_REMOVED = 2, /**< This event notifies the application that smartcard reader is removed */
  67 } smartcard_reader_event_type_e;
  68
  69 /**
  70  * @brief Called when a smartcard reader event occurs.
  71  * @since_tizen 3.0
  72  * @ingroup CAPI_NETWORK_SMARTCARD_READER_MODULE
  73  *
  74  * @param [in] reader The reader handle
  75  * @param [in] event_type The reader event type
  76  * @param [in] user_data The user data passed from the callback registration function
  77  *
  78  * @see smartcard_reader_set_event_cb()
  79  * @see smartcard_reader_unset_event_cb()
  80  */
  81 typedef void (*smartcard_reader_event_cb)(int reader, smartcard_reader_event_type_e event_type, void *user_data);
  82
  83 /**
  84  * @brief Initializes smartcard service
  85  * @since_tizen 2.3.1
  86  * @privlevel public
  87  * @privilege %http://tizen.org/privilege/secureelement
  88  * @ingroup CAPI_NETWORK_SMARTCARD_SE_SERVICE_MODULE
  89  *
  90  * @remarks This function must be called before proceeding any other smartcard function
  91  *
  92  * @return 0 on success, otherwise a negative error value.
  93  * @retval #SMARTCARD_ERROR_NONE Successful
  94  * @retval #SMARTCARD_ERROR_GENERAL     A general error occurred
  95  * @retval #SMARTCARD_ERROR_NOT_SUPPORTED Not supported
  96  * @retval #SMARTCARD_ERROR_PERMISSION_DENIED Permission denied
  97  *
  98  * @see smartcard_deinitialize()
  99  */
 100 SMARTCARD_API int smartcard_initialize(void);
 101
 102 /**
 103  * @brief Deinitializes smartcard service
 104  * @details Releases all the resource of the smartcard service
 105  * @since_tizen 2.3.1
 106  * @privlevel public
 107  * @privilege %http://tizen.org/privilege/secureelement
 108  * @ingroup CAPI_NETWORK_SMARTCARD_SE_SERVICE_MODULE
 109  *
 110  * @return 0 on success, otherwise a negative error value.
 111  * @retval #SMARTCARD_ERROR_NONE Successful
 112  * @retval #SMARTCARD_ERROR_GENERAL     A general error occurred
 113  * @retval #SMARTCARD_ERROR_NOT_INITIALIZED Smartcard service not initialized
 114  * @retval #SMARTCARD_ERROR_NOT_SUPPORTED Not supported
 115  * @retval #SMARTCARD_ERROR_PERMISSION_DENIED Permission denied
 116  *
 117  * @see smartcard_initialize()
 118  */
 119 SMARTCARD_API int smartcard_deinitialize(void);
 120
 121 /**
 122  * @brief Gets the version of SIMAlliance OpenMobileAPI specification
 123  * @since_tizen 3.0
 124  * @ingroup CAPI_NETWORK_SMARTCARD_SE_SERVICE_MODULE
 125  *
 126  * @remarks The @a version must be released using free().
 127  *
 128  * @param [out] version The version of SIMAlliance OpenMobileAPI specification
 129  *
 130  * @return 0 on success, otherwise a negative error value.
 131  * @retval #SMARTCARD_ERROR_NONE Successful
 132  * @retval #SMARTCARD_ERROR_INVALID_PARAMETER Invalid function parameter
 133  * @retval #SMARTCARD_ERROR_NOT_INITIALIZED Smartcard service not initialized
 134  * @retval #SMARTCARD_ERROR_NOT_SUPPORTED Not supported
 135  * @retval #SMARTCARD_ERROR_OUT_OF_MEMORY Out of memory
 136  *
 137  */
 138 SMARTCARD_API int smartcard_get_version(char **version);
 139
 140 /**
 141  * @brief Gets the list of available Secure Element readers.
 142  * @since_tizen 2.3.1
 143  * @ingroup CAPI_NETWORK_SMARTCARD_SE_SERVICE_MODULE
 144  *
 145  * @remarks readers must be released using free().
 146  *
 147  * @param [out] readers List of readers
 148  * @param [out] length The number of readers
 149  *
 150  * @return 0 on success, otherwise a negative error value.
 151  * @retval #SMARTCARD_ERROR_NONE Successful
 152  * @retval #SMARTCARD_ERROR_GENERAL     A general error occurred
 153  * @retval #SMARTCARD_ERROR_INVALID_PARAMETER Invalid function parameter
 154  * @retval #SMARTCARD_ERROR_NOT_INITIALIZED Smartcard service not initialized
 155  * @retval #SMARTCARD_ERROR_NOT_SUPPORTED Not supported
 156  *
 157  */
 158 SMARTCARD_API int smartcard_get_readers(int **readers, int *length);
 159
 160 /**
 161  * @brief Returns the name of the given reader.
 162  * @since_tizen 2.3.1
 163  * @ingroup CAPI_NETWORK_SMARTCARD_READER_MODULE
 164  *
 165  * @remarks reader_name must be released using free().
 166  *      @remarks If the reader is a SIM reader, then its name must be "SIM[Slot]"
 167  *      @remarks If the reader is a SD or micro SD reader, then its name must be "SD[slot]"
 168  *      @remarks If the reader is a embedded SE reader, then its name must be "eSE[slot]"
 169  *
 170  * @param [in] reader Handle to the reader
 171  * @param [out] reader_name The name of reader
 172  *
 173  * @return 0 on success, otherwise a negative error value.
 174  * @retval #SMARTCARD_ERROR_NONE Successful
 175  * @retval #SMARTCARD_ERROR_GENERAL     A general error occurred
 176  * @retval #SMARTCARD_ERROR_INVALID_PARAMETER Invalid function parameter
 177  * @retval #SMARTCARD_ERROR_NOT_INITIALIZED Smartcard service not initialized
 178  * @retval #SMARTCARD_ERROR_NOT_SUPPORTED Not supported
 179  *
 180  * @see smartcard_get_readers()
 181  */
 182 SMARTCARD_API int smartcard_reader_get_name(int reader, char **reader_name);
 183
 184 /**
 185  * @brief Checks if a Secure Element is present in the given reader.
 186  * @since_tizen 2.3.1
 187  * @ingroup CAPI_NETWORK_SMARTCARD_READER_MODULE
 188  *
 189  * @param [in] reader Handle to the reader
 190  * @param [out] is_present True or false depending whether a secure element is present in the
 191 reader - undefined when an error is returned
 192  *
 193  * @return 0 on success, otherwise a negative error value.
 194  * @retval #SMARTCARD_ERROR_NONE Successful
 195  * @retval #SMARTCARD_ERROR_GENERAL     A general error occurred
 196  * @retval #SMARTCARD_ERROR_INVALID_PARAMETER Invalid function parameter
 197  * @retval #SMARTCARD_ERROR_NOT_INITIALIZED Smartcard service not initialized
 198  * @retval #SMARTCARD_ERROR_NOT_SUPPORTED Not supported
 199  *
 200  * @see smartcard_get_readers()
 201  */
 202 SMARTCARD_API int smartcard_reader_is_secure_element_present(int reader, bool *is_present);
 203
 204 /**
 205  * @brief Connects to a Secure Element in the given reader.
 206  * @since_tizen 2.3.1
 207  * @privlevel public
 208  * @privilege %http://tizen.org/privilege/secureelement
 209  * @ingroup CAPI_NETWORK_SMARTCARD_READER_MODULE
 210  *
 211  * @param [in] reader Handle to the reader
 212  * @param [out] session Handle to the session created for the given reader
 213  *
 214  * @return 0 on success, otherwise a negative error value.
 215  * @retval #SMARTCARD_ERROR_NONE Successful
 216  * @retval #SMARTCARD_ERROR_GENERAL     A general error occurred
 217  * @retval #SMARTCARD_ERROR_INVALID_PARAMETER Invalid function parameter
 218  * @retval #SMARTCARD_ERROR_IO_ERROR I/O error
 219  * @retval #SMARTCARD_ERROR_NOT_INITIALIZED Smartcard service not initialized
 220  * @retval #SMARTCARD_ERROR_NOT_SUPPORTED Not supported
 221  * @retval #SMARTCARD_ERROR_PERMISSION_DENIED Permission denied
 222  *
 223  * @see smartcard_get_readers()
 224  */
 225 SMARTCARD_API int smartcard_reader_open_session(int reader, int *session);
 226
 227 /**
 228  * @brief Closes all the sessions opened on the given reader.
 229  * @details All the channels opened by all these sessions will be closed.
 230  * @since_tizen 2.3.1
 231  * @privlevel public
 232  * @privilege %http://tizen.org/privilege/secureelement
 233  * @ingroup CAPI_NETWORK_SMARTCARD_READER_MODULE
 234  *
 235  * @param [in] reader Handle to the reader
 236  *
 237  * @return 0 on success, otherwise a negative error value.
 238  * @retval #SMARTCARD_ERROR_NONE Successful
 239  * @retval #SMARTCARD_ERROR_GENERAL     A general error occurred
 240  * @retval #SMARTCARD_ERROR_INVALID_PARAMETER Invalid function parameter
 241  * @retval #SMARTCARD_ERROR_IO_ERROR I/O error
 242  * @retval #SMARTCARD_ERROR_NOT_INITIALIZED Smartcard service not initialized
 243  * @retval #SMARTCARD_ERROR_NOT_SUPPORTED Not supported
 244  * @retval #SMARTCARD_ERROR_PERMISSION_DENIED Permission denied
 245  *
 246  * @see smartcard_get_readers()
 247  */
 248 SMARTCARD_API int smartcard_reader_close_sessions(int reader);
 249
 250 /**
 251  * @brief Sets a callback function for receiving reader event.
 252  * @since_tizen 3.0
 253  * @ingroup CAPI_NETWORK_SMARTCARD_READER_MODULE
 254  *
 255  * @param [in] cb The reader event callback
 256  * @param [in] user_data The user data
 257  *
 258  * @return 0 on success, otherwise a negative error value.
 259  * @retval #SMARTCARD_ERROR_NONE Successful
 260  * @retval #SMARTCARD_ERROR_INVALID_PARAMETER Invalid function parameter
 261  * @retval #SMARTCARD_ERROR_NOT_INITIALIZED Smartcard service not initialized
 262  * @retval #SMARTCARD_ERROR_NOT_SUPPORTED Not supported
 263  *
 264  * @see smartcard_reader_unset_event_cb()
 265  */
 266 SMARTCARD_API int smartcard_reader_set_event_cb(smartcard_reader_event_cb cb, void *user_data);
 267
 268 /**
 269  * @brief Unsets the reader event callback function.
 270  * @since_tizen 3.0
 271  * @ingroup CAPI_NETWORK_SMARTCARD_READER_MODULE
 272  *
 273  * @return 0 on success, otherwise a negative error value.
 274  * @retval #SMARTCARD_ERROR_NONE Successful
 275  * @retval #SMARTCARD_ERROR_NOT_INITIALIZED Smartcard service not initialized
 276  * @retval #SMARTCARD_ERROR_NOT_SUPPORTED Not supported
 277  *
 278  * @see smartcard_reader_set_event_cb()
 279  */
 280 SMARTCARD_API int smartcard_reader_unset_event_cb(void);
 281
 282 /**
 283  * @brief Gets the reader that provides the given session.
 284  * @since_tizen 2.3.1
 285  * @ingroup CAPI_NETWORK_SMARTCARD_SESSION_MODULE
 286  *
 287  * @param [in] session Handle to the session
 288  * @param [out] reader Reader handle that provides the given session
 289  *
 290  * @return 0 on success, otherwise a negative error value.
 291  * @retval #SMARTCARD_ERROR_NONE Successful
 292  * @retval #SMARTCARD_ERROR_GENERAL     A general error occurred
 293  * @retval #SMARTCARD_ERROR_INVALID_PARAMETER Invalid function parameter
 294  * @retval #SMARTCARD_ERROR_NOT_INITIALIZED Smartcard service not initialized
 295  * @retval #SMARTCARD_ERROR_NOT_SUPPORTED Not supported
 296  *
 297  * @see smartcard_reader_open_session()
 298  */
 299 SMARTCARD_API int smartcard_session_get_reader(int session, int *reader);
 300
 301 /**
 302  * @brief Gets the Answer to Reset(ATR) of this Secure Element.
 303  * @since_tizen 2.3.1
 304  * @privlevel public
 305  * @privilege %http://tizen.org/privilege/secureelement
 306  * @ingroup CAPI_NETWORK_SMARTCARD_SESSION_MODULE
 307  *
 308  * @remarks atr must be released using free().
 309  * @remarks If the Answer to Reset(ATR) for this Secure Element is not available the returned length is set to zero and return value is Success.
 310  *
 311  * @param [in] session Handle to the session
 312  * @param [out] atr Byte array to retrieve the Answer to Reset(ATR)
 313  * @param [out] length The length of atr
 314  *
 315  * @return 0 on success, otherwise a negative error value.
 316  * @retval #SMARTCARD_ERROR_NONE Successful
 317  * @retval #SMARTCARD_ERROR_GENERAL     A general error occurred
 318  * @retval #SMARTCARD_ERROR_INVALID_PARAMETER Invalid function parameter
 319  * @retval #SMARTCARD_ERROR_NOT_INITIALIZED Smartcard service not initialized
 320  * @retval #SMARTCARD_ERROR_NOT_SUPPORTED Not supported
 321  * @retval #SMARTCARD_ERROR_PERMISSION_DENIED Permission denied
 322  *
 323  * @see smartcard_reader_open_session()
 324  */
 325 SMARTCARD_API int smartcard_session_get_atr(int session, unsigned char **atr, int *length);
 326
 327 /**
 328  * @brief Closes the connection with the Secure Element.
 329  * @details This will close any channels opened by this application with this Secure Element.
 330  * @since_tizen 2.3.1
 331  * @privlevel public
 332  * @privilege %http://tizen.org/privilege/secureelement
 333  * @ingroup CAPI_NETWORK_SMARTCARD_SESSION_MODULE
 334  *
 335  * @param [in] session handle to the session
 336  *
 337  * @return 0 on success, otherwise a negative error value.
 338  * @retval #SMARTCARD_ERROR_NONE Successful
 339  * @retval #SMARTCARD_ERROR_GENERAL     A general error occurred
 340  * @retval #SMARTCARD_ERROR_INVALID_PARAMETER Invalid function parameter
 341  * @retval #SMARTCARD_ERROR_IO_ERROR I/O error
 342  * @retval #SMARTCARD_ERROR_NOT_INITIALIZED Smartcard service not initialized
 343  * @retval #SMARTCARD_ERROR_NOT_SUPPORTED Not supported
 344  * @retval #SMARTCARD_ERROR_PERMISSION_DENIED Permission denied
 345  *
 346  * @see smartcard_reader_open_session()
 347  */
 348 SMARTCARD_API int smartcard_session_close(int session);
 349
 350 /**
 351  * @brief Checks if the given session is closed.
 352  * @since_tizen 2.3.1
 353  * @ingroup CAPI_NETWORK_SMARTCARD_SESSION_MODULE
 354  *
 355  * @param [in] session Handle to the session
 356  * @param [out] is_closed True or false depending on the session state
 357  *
 358  * @return 0 on success, otherwise a negative error value.
 359  * @retval #SMARTCARD_ERROR_NONE Successful
 360  * @retval #SMARTCARD_ERROR_GENERAL     A general error occurred
 361  * @retval #SMARTCARD_ERROR_INVALID_PARAMETER Invalid function parameter
 362  * @retval #SMARTCARD_ERROR_NOT_INITIALIZED Smartcard service not initialized
 363  * @retval #SMARTCARD_ERROR_NOT_SUPPORTED Not supported
 364  *
 365  * @see smartcard_reader_open_session()
 366  */
 367 SMARTCARD_API int smartcard_session_is_closed(int session, bool *is_closed);
 368
 369 /**
 370  * @brief Closes any channel opened on the given session.
 371  * @since_tizen 2.3.1
 372  * @privlevel public
 373  * @privilege %http://tizen.org/privilege/secureelement
 374  * @ingroup CAPI_NETWORK_SMARTCARD_SESSION_MODULE
 375  *
 376  * @param [in] session Handle to the session
 377  *
 378  * @return 0 on success, otherwise a negative error value.
 379  * @retval #SMARTCARD_ERROR_NONE Successful
 380  * @retval #SMARTCARD_ERROR_GENERAL     A general error occurred
 381  * @retval #SMARTCARD_ERROR_INVALID_PARAMETER Invalid function parameter
 382  * @retval #SMARTCARD_ERROR_IO_ERROR I/O error
 383  * @retval #SMARTCARD_ERROR_NOT_INITIALIZED Smartcard service not initialized
 384  * @retval #SMARTCARD_ERROR_NOT_SUPPORTED Not supported
 385  * @retval #SMARTCARD_ERROR_PERMISSION_DENIED Permission denied
 386  *
 387  * @see smartcard_reader_open_session()
 388  */
 389 SMARTCARD_API int smartcard_session_close_channels(int session);
 390
 391 /**
 392  * @brief Gets an access to the basic channel, as defined in the ISO/IEC 7816-4 specification (the one that has number 0).
 393  * @since_tizen 2.3.1
 394  * @privlevel public
 395  * @privilege %http://tizen.org/privilege/secureelement
 396  * @ingroup CAPI_NETWORK_SMARTCARD_SESSION_MODULE
 397  *
 398  * @remarks ex) unsigned char aid[] = {0xA0, 0x00, 0x00, 0x00, 0x63, 0x50, 0x4B, 0x43, 0x53, 0x2D, 0x31, 0x35};
 399  * @remarks If the Application ID(AID) is null, it means no Applet is to be selected on this channel and the default Applet is used.
 400  * @remarks Opening of the basic channel to a specific applet is NOT allowed for UICC.
 401  *
 402  * @param [in] session Handle to the session
 403  * @param [in] aid Byte array containing the Application ID(AID) to be selected on the given channel
 404  * @param [in] aid_len Size of byte array or 0 when no SELECT should be executed
 405  * @param [in] P2 P2 byte of the SELECT command if executed
 406  * @param [out] channel Handle of the basic channel
 407  *
 408  * @return 0 on success, otherwise a negative error value.
 409  * @retval #SMARTCARD_ERROR_NONE Successful
 410  * @retval #SMARTCARD_ERROR_CHANNEL_NOT_AVAILABLE No channel available
 411  * @retval #SMARTCARD_ERROR_GENERAL     A general error occurred
 412  * @retval #SMARTCARD_ERROR_INVALID_PARAMETER Invalid function parameter
 413  * @retval #SMARTCARD_ERROR_NO_SUCH_ELEMENT No such element error
 414  * @retval #SMARTCARD_ERROR_IO_ERROR I/O error
 415  * @retval #SMARTCARD_ERROR_NOT_INITIALIZED Smartcard service not initialized
 416  * @retval #SMARTCARD_ERROR_NOT_SUPPORTED Not supported
 417  * @retval #SMARTCARD_ERROR_PERMISSION_DENIED Permission denied
 418  *
 419  * @see smartcard_reader_open_session()
 420  */
 421 SMARTCARD_API int smartcard_session_open_basic_channel(int session, unsigned char *aid, int aid_len, unsigned char P2, int *channel);
 422
 423 /**
 424  * @brief Open a logical channel with the Secure Element, selecting the Applet represented by the given Application ID(AID).
 425  * @since_tizen 2.3.1
 426  * @privlevel public
 427  * @privilege %http://tizen.org/privilege/secureelement
 428  * @ingroup CAPI_NETWORK_SMARTCARD_SESSION_MODULE
 429  *
 430  * @remarks ex) unsigned char aid[] = {0xA0, 0x00, 0x00, 0x00, 0x63, 0x50, 0x4B, 0x43, 0x53, 0x2D, 0x31, 0x35};
 431  * @remarks If the Application ID(AID) is null, it means no Applet is to be selected on this channel and the default Applet is used.
 432  *
 433  * @param [in] session Handle to the session
 434  * @param [in] aid Byte array containing the Application ID(AID) to be selected on the given channel
 435  * @param [in] aid_len Size of byte array or 0 when no SELECT should be executed
 436  * @param [in] P2 P2 byte of the SELECT command if executed
 437  * @param [out] channel Handle of the new logical channel
 438  *
 439  * @return 0 on success, otherwise a negative error value.
 440  * @retval #SMARTCARD_ERROR_NONE Successful
 441  * @retval #SMARTCARD_ERROR_CHANNEL_NOT_AVAILABLE No channel available
 442  * @retval #SMARTCARD_ERROR_GENERAL     A general error occurred
 443  * @retval #SMARTCARD_ERROR_INVALID_PARAMETER Invalid function parameter
 444  * @retval #SMARTCARD_ERROR_NO_SUCH_ELEMENT No such element error
 445  * @retval #SMARTCARD_ERROR_IO_ERROR I/O error
 446  * @retval #SMARTCARD_ERROR_NOT_INITIALIZED Smartcard service not initialized
 447  * @retval #SMARTCARD_ERROR_NOT_SUPPORTED Not supported
 448  * @retval #SMARTCARD_ERROR_PERMISSION_DENIED Permission denied
 449  *
 450  * @see smartcard_reader_open_session()
 451  */
 452 SMARTCARD_API int smartcard_session_open_logical_channel(int session, unsigned char *aid, int aid_len, unsigned char P2, int *channel);
 453
 454 /**
 455  * @brief Closes the given channel to the Secure Element.
 456  * @since_tizen 2.3.1
 457  * @privlevel public
 458  * @privilege %http://tizen.org/privilege/secureelement
 459  * @ingroup CAPI_NETWORK_SMARTCARD_CHANNEL_MODULE
 460  *
 461  * @param [in] channel Handle to the channel
 462  *
 463  * @return 0 on success, otherwise a negative error value.
 464  * @retval #SMARTCARD_ERROR_NONE Successful
 465  * @retval #SMARTCARD_ERROR_GENERAL     A general error occurred
 466  * @retval #SMARTCARD_ERROR_INVALID_PARAMETER Invalid function parameter
 467  * @retval #SMARTCARD_ERROR_IO_ERROR I/O error
 468  * @retval #SMARTCARD_ERROR_NOT_INITIALIZED Smartcard service not initialized
 469  * @retval #SMARTCARD_ERROR_NOT_SUPPORTED Not supported
 470  * @retval #SMARTCARD_ERROR_PERMISSION_DENIED Permission denied
 471  *
 472  * @see smartcard_session_open_basic_channel()
 473  * @see smartcard_session_open_logical_channel()
 474  */
 475 SMARTCARD_API int smartcard_channel_close(int channel);
 476
 477 /**
 478  * @brief Checks if the given channel is the basic channel.
 479  * @since_tizen 2.3.1
 480  * @ingroup CAPI_NETWORK_SMARTCARD_CHANNEL_MODULE
 481  *
 482  * @param [in] channel Handle to the channel
 483  * @param [out] is_basic_channel True or false depending on the channel type
 484  *
 485  * @return 0 on success, otherwise a negative error value.
 486  * @retval #SMARTCARD_ERROR_NONE Successful
 487  * @retval #SMARTCARD_ERROR_GENERAL     A general error occurred
 488  * @retval #SMARTCARD_ERROR_INVALID_PARAMETER Invalid function parameter
 489  * @retval #SMARTCARD_ERROR_NOT_INITIALIZED Smartcard service not initialized
 490  * @retval #SMARTCARD_ERROR_NOT_SUPPORTED Not supported
 491  *
 492  * @see smartcard_session_open_basic_channel()
 493  * @see smartcard_session_open_logical_channel()
 494  */
 495 SMARTCARD_API int smartcard_channel_is_basic_channel(int channel, bool *is_basic_channel);
 496
 497 /**
 498  * @brief Checks if the given channel is closed.
 499  * @since_tizen 2.3.1
 500  * @ingroup CAPI_NETWORK_SMARTCARD_CHANNEL_MODULE
 501  *
 502  * @param [in] channel Handle to the channel
 503  * @param [out] is_closed True or false depending on the channel state
 504  *
 505  * @return 0 on success, otherwise a negative error value.
 506  * @retval #SMARTCARD_ERROR_NONE Successful
 507  * @retval #SMARTCARD_ERROR_GENERAL     A general error occurred
 508  * @retval #SMARTCARD_ERROR_INVALID_PARAMETER Invalid function parameter
 509  * @retval #SMARTCARD_ERROR_NOT_INITIALIZED Smartcard service not initialized
 510  * @retval #SMARTCARD_ERROR_NOT_SUPPORTED Not supported
 511  *
 512  * @see smartcard_session_open_basic_channel()
 513  * @see smartcard_session_open_logical_channel()
 514  */
 515 SMARTCARD_API int smartcard_channel_is_closed(int channel, bool *is_closed);
 516
 517 /**
 518  * @brief Gets the response to the select command.
 519  * @since_tizen 2.3.1
 520  * @ingroup CAPI_NETWORK_SMARTCARD_CHANNEL_MODULE
 521  *
 522  * @remarks select_resp must be released using free().
 523  *
 524  * @param [in] channel Handle to the channel
 525  * @param [out] select_resp Byte array to retrieve the SELECT response
 526  * @param [out] length The length of select_resp
 527  *
 528  * @return 0 on success, otherwise a negative error value.
 529  * @retval #SMARTCARD_ERROR_NONE Successful
 530  * @retval #SMARTCARD_ERROR_GENERAL     A general error occurred
 531  * @retval #SMARTCARD_ERROR_INVALID_PARAMETER Invalid function parameter
 532  * @retval #SMARTCARD_ERROR_NOT_INITIALIZED Smartcard service not initialized
 533  * @retval #SMARTCARD_ERROR_NOT_SUPPORTED Not supported
 534  *
 535  * @see smartcard_session_open_basic_channel()
 536  * @see smartcard_session_open_logical_channel()
 537  */
 538 SMARTCARD_API int smartcard_channel_get_select_response(int channel, unsigned char **select_resp, int *length);
 539
 540 /**
 541  * @brief Gets the session that has opened the given channel.
 542  * @since_tizen 2.3.1
 543  * @ingroup CAPI_NETWORK_SMARTCARD_CHANNEL_MODULE
 544  *
 545  * @param [in] channel Handle to the channel
 546  * @param [out] session Session handle of the given channel
 547  *
 548  * @return 0 on success, otherwise a negative error value.
 549  * @retval #SMARTCARD_ERROR_NONE Successful
 550  * @retval #SMARTCARD_ERROR_GENERAL     A general error occurred
 551  * @retval #SMARTCARD_ERROR_INVALID_PARAMETER Invalid function parameter
 552  * @retval #SMARTCARD_ERROR_NOT_INITIALIZED Smartcard service not initialized
 553  * @retval #SMARTCARD_ERROR_NOT_SUPPORTED Not supported
 554  *
 555  * @see smartcard_session_open_basic_channel()
 556  * @see smartcard_session_open_logical_channel()
 557  */
 558 SMARTCARD_API int smartcard_channel_get_session(int channel, int *session);
 559
 560 /**
 561  * @brief Transmits an APDU command (as per ISO/IEC 7816-4) to the Secure Element.
 562  * @since_tizen 2.3.1
 563  * @privlevel public
 564  * @privilege %http://tizen.org/privilege/secureelement
 565  * @ingroup CAPI_NETWORK_SMARTCARD_CHANNEL_MODULE
 566  *
 567  * @remarks resp must be released using free().
 568  * @remarks MANAGE_CHANNEL commands are not allowed.
 569  * @remarks SELECT by DF Name (P1=04) are not allowed.
 570  * @remarks bytes with channel numbers are de-masked.
 571
 572  * @param [in] channel Handle to the channel
 573  * @param [in] cmd Command APDU to be send to the secure element
 574  * @param [in] cmd_len Size of command APDU
 575  * @param [out] resp Byte array for the response APDU plus status words
 576  * @param [out] length The length of resp
 577  *
 578  * @return 0 on success, otherwise a negative error value.
 579  * @retval #SMARTCARD_ERROR_NONE Successful
 580  * @retval #SMARTCARD_ERROR_GENERAL     A general error occurred
 581  * @retval #SMARTCARD_ERROR_INVALID_PARAMETER Invalid function parameter
 582  * @retval #SMARTCARD_ERROR_ILLEGAL_STATE Illegal state of execution error
 583  * @retval #SMARTCARD_ERROR_IO_ERROR I/O error
 584  * @retval #SMARTCARD_ERROR_NOT_INITIALIZED Smartcard service not initialized
 585  * @retval #SMARTCARD_ERROR_NOT_SUPPORTED Not supported
 586  * @retval #SMARTCARD_ERROR_PERMISSION_DENIED Permission denied
 587  *
 588  * @see smartcard_session_open_basic_channel()
 589  * @see smartcard_session_open_logical_channel()
 590  */
 591 SMARTCARD_API int smartcard_channel_transmit(int channel, unsigned char *cmd, int cmd_len, unsigned char **resp, int *length);
 592
 593 /**
 594  * @brief Helper function to retrieves the response APDU of the previous transmit() call
 595  * @since_tizen 2.3.1
 596  * @ingroup CAPI_NETWORK_SMARTCARD_CHANNEL_MODULE
 597  *
 598  * @remarks resp must be released using free().
 599  *
 600  * @param [in] channel Handle to the channel
 601  * @param [out] resp Byte array for the response APDU plus status words
 602  * @param [out] length The length of resp
 603  *
 604  * @return 0 on success, otherwise a negative error value.
 605  * @retval #SMARTCARD_ERROR_NONE Successful
 606  * @retval #SMARTCARD_ERROR_GENERAL     A general error occurred
 607  * @retval #SMARTCARD_ERROR_INVALID_PARAMETER Invalid function parameter
 608  * @retval #SMARTCARD_ERROR_ILLEGAL_STATE Illegal state of execution error
 609  * @retval #SMARTCARD_ERROR_NOT_INITIALIZED Smartcard service not initialized
 610  * @retval #SMARTCARD_ERROR_NOT_SUPPORTED Not supported
 611  *
 612  * @see smartcard_session_open_basic_channel()
 613  * @see smartcard_session_open_logical_channel()
 614  */
 615 SMARTCARD_API int smartcard_channel_transmit_retrieve_response(int channel, unsigned char **resp, int *length);
 616
 617 /**
 618  * @brief Performs a selection of the next Applet on the given channel that matches to the partial Application ID(AID)
 619  * @since_tizen 2.3.1
 620  * @privlevel public
 621  * @privilege %http://tizen.org/privilege/secureelement
 622  * @ingroup CAPI_NETWORK_SMARTCARD_CHANNEL_MODULE
 623  *
 624  * @param [in] channel Handle to the channel
 625  * @param [out] is_success True or false depending whether another applet with the partial Application ID(AID)
 626 could be selected on the given channel
 627
 628  * @return 0 on success, otherwise a negative error value.
 629  * @retval #SMARTCARD_ERROR_NONE Successful
 630  * @retval #SMARTCARD_ERROR_GENERAL     A general error occurred
 631  * @retval #SMARTCARD_ERROR_INVALID_PARAMETER Invalid function parameter
 632  * @retval #SMARTCARD_ERROR_ILLEGAL_STATE Illegal state of execution error
 633  * @retval #SMARTCARD_ERROR_OPERATION_NOT_SUPPORTED Operation not supported from SE
 634  * @retval #SMARTCARD_ERROR_IO_ERROR I/O error
 635  * @retval #SMARTCARD_ERROR_NOT_INITIALIZED Smartcard service not initialized
 636  * @retval #SMARTCARD_ERROR_NOT_SUPPORTED Not supported
 637  * @retval #SMARTCARD_ERROR_PERMISSION_DENIED Permission denied
 638  *
 639  * @see smartcard_session_open_basic_channel()
 640  * @see smartcard_session_open_logical_channel()
 641  */
 642 SMARTCARD_API int smartcard_channel_select_next(int channel, bool *is_success);
 643
 644 #ifdef __cplusplus
 645 }
 646 #endif
 647
 648 #endif