Martijn Coenen | a1ec958 | 2015-09-07 11:53:59 +0200 | [diff] [blame] | 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 | |
Martijn Coenen | c3178e5 | 2013-07-25 17:43:47 -0700 | [diff] [blame] | 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; |
Martijn Coenen | 35bf628 | 2013-10-14 20:39:59 +0200 | [diff] [blame] | 23 | import android.content.pm.PackageManager; |
Martijn Coenen | c3178e5 | 2013-07-25 17:43:47 -0700 | [diff] [blame] | 24 | import android.os.IBinder; |
| 25 | |
| 26 | /** |
Martijn Coenen | 35bf628 | 2013-10-14 20:39:59 +0200 | [diff] [blame] | 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. |
Martijn Coenen | c3178e5 | 2013-07-25 17:43:47 -0700 | [diff] [blame] | 125 | * |
| 126 | * <p>This registration will allow the service to be included |
Martijn Coenen | 35bf628 | 2013-10-14 20:39:59 +0200 | [diff] [blame] | 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. |
Martijn Coenen | c3178e5 | 2013-07-25 17:43:47 -0700 | [diff] [blame] | 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 | * |
Martijn Coenen | 35bf628 | 2013-10-14 20:39:59 +0200 | [diff] [blame] | 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. |
Martijn Coenen | c3178e5 | 2013-07-25 17:43:47 -0700 | [diff] [blame] | 139 | */ |
| 140 | public abstract class OffHostApduService extends Service { |
| 141 | /** |
Martijn Coenen | 35bf628 | 2013-10-14 20:39:59 +0200 | [diff] [blame] | 142 | * The {@link Intent} action that must be declared as handled by the service. |
Martijn Coenen | c3178e5 | 2013-07-25 17:43:47 -0700 | [diff] [blame] | 143 | */ |
| 144 | @SdkConstant(SdkConstantType.SERVICE_ACTION) |
| 145 | public static final String SERVICE_INTERFACE = |
Martijn Coenen | 5224608 | 2013-08-30 11:14:46 -0700 | [diff] [blame] | 146 | "android.nfc.cardemulation.action.OFF_HOST_APDU_SERVICE"; |
Martijn Coenen | c3178e5 | 2013-07-25 17:43:47 -0700 | [diff] [blame] | 147 | |
| 148 | /** |
| 149 | * The name of the meta-data element that contains |
| 150 | * more information about this service. |
| 151 | */ |
Martijn Coenen | 5224608 | 2013-08-30 11:14:46 -0700 | [diff] [blame] | 152 | public static final String SERVICE_META_DATA = |
| 153 | "android.nfc.cardemulation.off_host_apdu_service"; |
Martijn Coenen | c3178e5 | 2013-07-25 17:43:47 -0700 | [diff] [blame] | 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); |
Martijn Coenen | a739788 | 2013-07-30 20:07:47 -0700 | [diff] [blame] | 170 | } |