UICC SE card emulation

The Universal Integrated Circuit Card (UICC) is the smart card used in mobile terminals in wireless networks such as UMTS and GSM. If you have an NFC-enabled UICC in your device, you can use the UICC secure element (SE) to emulate a smart card.

This section describes the configuration options for UICC SE card emulation (UICC SE CE) and how to use them. If an NFC-enabled UICC is in the device and the user turns on the NFC radio, ISO14443A and ISO14443B card emulation is automatically enabled and radio traffic is automatically sent to the UICC. The configuration options allow you to:
  • Enable card emulation while the device backlight is off or while the device is powered off
  • Enable card emulation for other technology types such as ISO14443B Prime

UICC SE CE user settings

User settings for UICC secure element card emulation (UICC SE CE) let you restrict the ability to emulate cards.

You can query and modify these settings on the device Settings menu by clicking Settings > Network Connections > NFC > Allow NFC Card Transactions:
  • When locked or backlight is off
  • When device is turned off
These settings are represented by the following enum definitions in nfc.h: An app can retrieve and change the values of these settings using the following functions:

For example, to keep UICC SE CE enabled when the device is turned off, you need to ensure that either the When device is turned off setting is enabled by the user, or NFC_SETTING_CE_POWERED_OFF is set in your application.

There is a dependency between these two settings. In order to allow card transactions when the device is turned off, card transactions must also be allowed when the backlight is off. Thus, if you request to allow card transactions when the device is turned off or if you request to deny card transactions when the device backlight is off, your request may cause the NFC service to also change the other setting. The table below shows the setting values under various combinations and the effect of enabling or disabling each setting using nfc_set_setting().

Call nfc_set_ setting()... When BACKLIGHT_OFF is: And POWERED_OFF is: Success result: BACKLIGHT_OFF is set to: Success result: POWERED_OFF is set to:
To enable BACKLIGHT_OFF False False True False
To enable POWERED_OFF False False True True
To enable POWERED_OFF True False True True
To disable BACKLIGHT_OFF True False False False
To disable BACKLIGHT_OFF True True False False
To disable POWERED_OFF True True True False

Modify user settings

You can retrieve and modify the values of user settings using the following API functions: Note that the mechanism for changing a setting is asynchronous. You use nfc_set_setting() to request the setting change and receive a return value indicating whether or not the user prompt has been displayed successfully. You use functions in nfc_bps.h to receive a later return value indicating the user's response to the dialog and whether the setting has been changed successfully.
  1. Call nfc_get_setting() to check the status of the user settings.
  2. To change the value of a user setting, call nfc_set_setting(). This call causes a prompt to be displayed on the screen requesting user's permission to modify the setting.
  3. Retrieve BlackBerry Platform Services (BPS) events to determine the user's response and the result of the user setting you changed.

Not applicable

Not applicable

The sample code below demonstrates how to retrieve the current values of the user settings:

#include <nfc/nfc.h> 
bool ceAllowedWhenBacklightOffOrLocked = false; 
bool ceAllowedWhenPoweredOff = false;
if (NFC_RESULT_SUCCESS == 
        nfc_get_setting(NFC_SETTING_CE_BACKLIGHT_OFF,
                  &ceAllowedWhenBacklightOffOrLocked) &&
      NFC_RESULT_SUCCESS == 
        nfc_get_setting(NFC_SETTING_CE_POWERED_OFF,
                        &ceAllowedWhenPoweredOff)) { 
    printf("CE allowed when locked or backlight is off: %s\n",
      ceAllowedWhenBacklightOffOrLocked ? "true" : "false");
    printf("CE allowed when device is turned off: %s\n", 
      ceAllowedWhenPoweredOff ? "true" : "false"); 
} else {
    // Handle error
} 
The sample code below uses nfc_set_setting() to turn on the When device is turned off setting. You can also use this function to turn the setting off, or to modify the When locked or backlight is off setting.
#include <nfc/nfc.h>
nfc_result_t res = 
        nfc_set_setting(NFC_SETTING_CE_POWERED_OFF, true); 
if(res == NFC_RESULT_SUCCESS) { 
    // The dialog is currently on the screen; we need
    // to wait for a BlackBerry Platform Services
    // message with the actual result.
} else if(res == NFC_RESULT_RESOURCE_BUSY) { 
    // The user is already being prompted about a setting 
    // change (by this or another application). We should
    // try again later. 
} else {
    // Handle error
}    
            
Receive the response to your request in a BlackBerry Platform Services event loop such as the following. An NFC_RESULT_SUCCESS event means the setting has been successfully changed. In this code sample, it indicates that card transaction is now enabled when the device is powered off.
 
#include <nfc/nfc_bps.h>
#include <nfc/nfc.h> 
#include <bps/bps.h>
                
bps_initialize(); 
nfc_request_events(); 
                
for (;;) { 
    bps_event_t* event;
    nfc_event_t* nfc_event; 
    nfc_event_type_t event_type; 
    int event_value;
    bps_get_event(&event, -1); 
    if (bps_event_get_domain(event) == nfc_get_domain() 
        && BPS_SUCCESS == 
              nfc_get_nfc_event(event, &nfc_event) 
        && NFC_RESULT_SUCCESS == 
              nfc_get_event_type(nfc_event, &event_type) 
        && NFC_CE_ENABLE_POWERED_OFF_EVENT == event_type 
        && NFC_RESULT_SUCCESS == 
              nfc_get_notification_value(nfc_event, 
                                         &event_value)) {
        switch (event_value) { 
            case NFC_RESULT_SUCCESS: 
                // Handle the case where the setting 
                // was successfully changed 
            case NFC_RESULT_OPERATION_REJECTED: 
                // Handle the case where the user 
                // declined the setting change 
            default:
                // Default error handling
       } 
    } else { 
       // Handle uninteresting or invalid events 
    } 
} 

UICC SE CE technology types

UICC secure element card emulation (UICC SE CE) is enabled by default for technology types ISO14443A and ISO14443B. You can query the enabled technology types and modify them using:
  • nfc_se_reader_get_technology_types()
  • nfc_se_reader_set_technology_types()
Before calling these functions, you must
  • Have an NFC-enabled UICC inserted in the device you plan to use for testing
  • Open a session to the UICC reader. For more information, see Using APDUs.

You must dynamically link to the libnfc.so shared object to use the NFC library.

Query card emulation technology types

The nfc_se_reader_get_technology_types() function takes a battery mode parameter and returns the technology types that are emulated under the specified battery mode setting. The battery mode parameter can be either BATTERY_MODE_ON or BATTERY_MODE_OFF, which indicates that the device is powered on or off respectively.

If a technology type of 0 is returned, then you must call nfc_se_reader_set_technology_types() to configure the card emulation mode you want to use.

The following code demonstrates the use of nfc_se_reader_get_technology_types().

Not applicable

Not applicable

#include <nfc/nfc_se_access.h>
uint32_t session = 0;
   
// Open a session to the UICC reader.
 ...
                 
uint32_t technology_types = 0;
if (NFC_RESULT_SUCCESS != 
        nfc_se_reader_get_technology_types(session, 
                    BATTERY_MODE_ON, 
                    &technology_types)) {
    // Handle error
    ...
}
                    
printf("Technology types emulated when device is powered on:\n");
if (technology_types & TECHNOLOGY_TYPE_ISO14443A) 
    printf("  ISO14443A\n");
if (technology_types & TECHNOLOGY_TYPE_ISO14443B) 
    printf("  ISO14443B\n");
                    
if (NFC_RESULT_SUCCESS != 
        nfc_se_reader_get_technology_types(session, 
                    BATTERY_MODE_OFF, 
                    &technology_types)) {
    // Handle error
    ...
}
printf("Technology types emulated when device is turned off 
       (if the user settings allow it):\n");
if (technology_types & TECHNOLOGY_TYPE_ISO14443A) 
    printf("  ISO14443A\n");
if (technology_types & TECHNOLOGY_TYPE_ISO14443B) 
    printf("  ISO14443B\n");
                

Configure card emulation technology types

UICC secure element card emulation (UICC SE CE) is enabled by default for card types ISO14443A and ISO14443B. You can turn on UICC SE CE for other technology types using nfc_se_reader_set_technology_types(). You can also disable UICC SE CE by passing in the TECHNOLOGY_TYPE_NONE value. The changes you make using this function are persistent.

Not applicable

Not applicable

The following code sample demonstrates how to turn on card emulation for the ISO14443B Prime card.

#include <nfc/nfc_se_access.h>
uint32_t session = 0;
// Open a session to the UICC reader.
...

if (NFC_RESULT_SUCCESS != 
        nfc_se_reader_set_technology_types(session, 
                          TECHNOLOGY_TYPE_ISO14443B_PRIME)) {
    // Handle error
    ...
    
}
            

Configure technology types in a wallet application

A wallet application works with an applet within the secure element (SE) to provide payment features.

  1. Query UICC SE CE technology types to determine if the technology type you need is enabled for the battery mode you want to use.
  2. Call nfc_se_get_active_se_type() to determine if the UICC is the active SE.
  3. If the UICC is not the active SE, call nfc_se_set_uicc_active().
  4. If you want to keep card emulation enabled while the device is powered off, turn on the NFC_SETTING_CE_POWERED_OFF mode.
  5. Set the technology type you want to use by calling nfc_se_reader_set_technology_types(). If your UICC supports card emulation mode only in technology type B, not in technology type A, you may have problems interacting with some payment readers. In that case, set the technology type to B only for your UICC.

Not applicable

Not applicable

The following pseudo code demonstrates how to configure technology types in a wallet application. For simplicity, error handling is not included.

uint32_t currentTechType = 0;
nfc_se_reader_get_technology_types(session, 
				batteryMode, 
				&currentTechType);
				
if(currentTechType != desiredTechType) {
				
    // Make sure the UICC is the Active SE
	secure_element_id_type_t activeSEType = SE_ID_NONE;
	nfc_se_get_active_se_type(&activeSEType);
	if(activeSEType != UICC_SE_ID) {
		nfc_se_set_uicc_active();
		// Wait for NFC_CE_SET_UICC_ACTIVE_SE_TYPE_EVENT.
		...
				
		// Handle error case in which the user cancels 
		// the request to make the UICC the active SE
		...
				
	}
				
	// Turn on battery-off mode if needed
	if(batteryMode == BATTERY_MODE_OFF) {
		nfc_set_setting(NFC_SETTING_CE_POWERED_OFF, true);
		// Wait for NFC_CE_DISABLE_POWERED_OFF_EVENT.
		...
				
		// Handle error case in which the user cancels 
		// the request to enable battery off mode
		...
				
	}
				
	// Set the technology type
	nfc_se_reader_set_technology_types(session, desiredTechType);
}				
			

Contactless registry service (CRS) considerations

GlobalPlatform Card Specification v 2.2 Amendment C defines a UICC with a CRS applet on it. If you are using such a UICC to activate or deactivate applets over the NFC interface, call the nfc_se_enable_swp() function just before opening a logical channel to the CRS applet to update its state.

The following code sample demonstrates the call sequence:

Not applicable

Not applicable

fc_channel_type_t channelType = NFC_CHANNEL_TYPE_SE_UICC;
uint8_t aid[] = { 0xA0, 0x00, 0x00, 0x01, 0x51, 0x43, 0x52, 0x53, 0x00 };
uint32_t aid_len = sizeof(aid);
fcp_type_t fcpResponseType = SATSA_OPEN_EMV_FCP;
uint32_t hSEChannel;
int32_t responseLen;

nfc_se_enable_swp();

nfc_se_open_logical_channel_direct(channelType,
                                   aid,
                                   aid_len,
                                   fcpResponseType,
                                   &hSEChannel,
                                   &responseLen));
    

Last modified: 2015-05-07



Got questions about leaving a comment? Get answers from our Disqus FAQ.

comments powered by Disqus