1 /* 2 * Copyright (C) 2015 The Android Open Source Project 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17 package android.nfc.cardemulation; 18 19 import android.annotation.SdkConstant; 20 import android.annotation.SdkConstant.SdkConstantType; 21 import android.app.Service; 22 import android.content.Intent; 23 import android.content.pm.PackageManager; 24 import android.os.IBinder; 25 26 /** 27 * <p>OffHostApduService is a convenience {@link Service} class that can be 28 * extended to describe one or more NFC applications that are residing 29 * off-host, for example on an embedded secure element or a UICC. 30 * 31 * <div class="special reference"> 32 * <h3>Developer Guide</h3> 33 * For a general introduction into the topic of card emulation, 34 * please read the <a href="{@docRoot}guide/topics/nfc/ce.html"> 35 * NFC card emulation developer guide.</a></p> 36 * </div> 37 * 38 * <h3>NFC Protocols</h3> 39 * <p>Off-host applications represented by this class are based on the NFC-Forum ISO-DEP 40 * protocol (based on ISO/IEC 14443-4) and support processing 41 * command Application Protocol Data Units (APDUs) as 42 * defined in the ISO/IEC 7816-4 specification. 43 * 44 * <h3>Service selection</h3> 45 * <p>When a remote NFC device wants to talk to your 46 * off-host NFC application, it sends a so-called 47 * "SELECT AID" APDU as defined in the ISO/IEC 7816-4 specification. 48 * The AID is an application identifier defined in ISO/IEC 7816-4. 49 * 50 * <p>The registration procedure for AIDs is defined in the 51 * ISO/IEC 7816-5 specification. If you don't want to register an 52 * AID, you are free to use AIDs in the proprietary range: 53 * bits 8-5 of the first byte must each be set to '1'. For example, 54 * "0xF00102030405" is a proprietary AID. If you do use proprietary 55 * AIDs, it is recommended to choose an AID of at least 6 bytes, 56 * to reduce the risk of collisions with other applications that 57 * might be using proprietary AIDs as well. 58 * 59 * <h3>AID groups</h3> 60 * <p>In some cases, an off-host environment may need to register multiple AIDs 61 * to implement a certain application, and it needs to be sure 62 * that it is the default handler for all of these AIDs (as opposed 63 * to some AIDs in the group going to another service). 64 * 65 * <p>An AID group is a list of AIDs that should be considered as 66 * belonging together by the OS. For all AIDs in an AID group, the 67 * OS will guarantee one of the following: 68 * <ul> 69 * <li>All AIDs in the group are routed to the off-host execution environment 70 * <li>No AIDs in the group are routed to the off-host execution environment 71 * </ul> 72 * In other words, there is no in-between state, where some AIDs 73 * in the group can be routed to this off-host execution environment, 74 * and some to another or a host-based {@link HostApduService}. 75 * <h3>AID groups and categories</h3> 76 * <p>Each AID group can be associated with a category. This allows 77 * the Android OS to classify services, and it allows the user to 78 * set defaults at the category level instead of the AID level. 79 * 80 * <p>You can use 81 * {@link CardEmulation#isDefaultServiceForCategory(android.content.ComponentName, String)} 82 * to determine if your off-host service is the default handler for a category. 83 * 84 * <p>In this version of the platform, the only known categories 85 * are {@link CardEmulation#CATEGORY_PAYMENT} and {@link CardEmulation#CATEGORY_OTHER}. 86 * AID groups without a category, or with a category that is not recognized 87 * by the current platform version, will automatically be 88 * grouped into the {@link CardEmulation#CATEGORY_OTHER} category. 89 * 90 * <h3>Service AID registration</h3> 91 * <p>To tell the platform which AIDs 92 * reside off-host and are managed by this service, a {@link #SERVICE_META_DATA} 93 * entry must be included in the declaration of the service. An 94 * example of a OffHostApduService manifest declaration is shown below: 95 * <pre> <service android:name=".MyOffHostApduService" android:exported="true" android:permission="android.permission.BIND_NFC_SERVICE"> 96 * <intent-filter> 97 * <action android:name="android.nfc.cardemulation.action.OFF_HOST_APDU_SERVICE"/> 98 * </intent-filter> 99 * <meta-data android:name="android.nfc.cardemulation.off_host_apdu_ervice" android:resource="@xml/apduservice"/> 100 * </service></pre> 101 * 102 * This meta-data tag points to an apduservice.xml file. 103 * An example of this file with a single AID group declaration is shown below: 104 * <pre> 105 * <offhost-apdu-service xmlns:android="http://schemas.android.com/apk/res/android" 106 * android:description="@string/servicedesc"> 107 * <aid-group android:description="@string/subscription" android:category="other"> 108 * <aid-filter android:name="F0010203040506"/> 109 * <aid-filter android:name="F0394148148100"/> 110 * </aid-group> 111 * </offhost-apdu-service> 112 * </pre> 113 * 114 * <p>The {@link android.R.styleable#OffHostApduService <offhost-apdu-service>} is required 115 * to contain a 116 * {@link android.R.styleable#OffHostApduService_description <android:description>} 117 * attribute that contains a user-friendly description of the service that may be shown in UI. 118 * 119 * <p>The {@link android.R.styleable#OffHostApduService <offhost-apdu-service>} must 120 * contain one or more {@link android.R.styleable#AidGroup <aid-group>} tags. 121 * Each {@link android.R.styleable#AidGroup <aid-group>} must contain one or 122 * more {@link android.R.styleable#AidFilter <aid-filter>} tags, each of which 123 * contains a single AID. The AID must be specified in hexadecimal format, and contain 124 * an even number of characters. 125 * 126 * <p>This registration will allow the service to be included 127 * as an option for being the default handler for categories. 128 * The Android OS will take care of correctly 129 * routing the AIDs to the off-host execution environment, 130 * based on which service the user has selected to be the handler for a certain category. 131 * 132 * <p>The service may define additional actions outside of the 133 * Android namespace that provide further interaction with 134 * the off-host execution environment. 135 * 136 * <p class="note">Use of this class requires the 137 * {@link PackageManager#FEATURE_NFC_HOST_CARD_EMULATION} to be present 138 * on the device. 139 */ 140 public abstract class OffHostApduService extends Service { 141 /** 142 * The {@link Intent} action that must be declared as handled by the service. 143 */ 144 @SdkConstant(SdkConstantType.SERVICE_ACTION) 145 public static final String SERVICE_INTERFACE = 146 "android.nfc.cardemulation.action.OFF_HOST_APDU_SERVICE"; 147 148 /** 149 * The name of the meta-data element that contains 150 * more information about this service. 151 */ 152 public static final String SERVICE_META_DATA = 153 "android.nfc.cardemulation.off_host_apdu_service"; 154 155 /** 156 * The Android platform itself will not bind to this service, 157 * but merely uses its declaration to keep track of what AIDs 158 * the service is interested in. This information is then used 159 * to present the user with a list of applications that can handle 160 * an AID, as well as correctly route those AIDs either to the host (in case 161 * the user preferred a {@link HostApduService}), or to an off-host 162 * execution environment (in case the user preferred a {@link OffHostApduService}. 163 * 164 * Implementers may define additional actions outside of the 165 * Android namespace that allow further interactions with 166 * the off-host execution environment. Such implementations 167 * would need to override this method. 168 */ 169 public abstract IBinder onBind(Intent intent); 170 } 171
