1a1ec95882901ebf386cc794122b36b18ee845554Martijn Coenen/* 2a1ec95882901ebf386cc794122b36b18ee845554Martijn Coenen * Copyright (C) 2015 The Android Open Source Project 3a1ec95882901ebf386cc794122b36b18ee845554Martijn Coenen * 4a1ec95882901ebf386cc794122b36b18ee845554Martijn Coenen * Licensed under the Apache License, Version 2.0 (the "License"); 5a1ec95882901ebf386cc794122b36b18ee845554Martijn Coenen * you may not use this file except in compliance with the License. 6a1ec95882901ebf386cc794122b36b18ee845554Martijn Coenen * You may obtain a copy of the License at 7a1ec95882901ebf386cc794122b36b18ee845554Martijn Coenen * 8a1ec95882901ebf386cc794122b36b18ee845554Martijn Coenen * http://www.apache.org/licenses/LICENSE-2.0 9a1ec95882901ebf386cc794122b36b18ee845554Martijn Coenen * 10a1ec95882901ebf386cc794122b36b18ee845554Martijn Coenen * Unless required by applicable law or agreed to in writing, software 11a1ec95882901ebf386cc794122b36b18ee845554Martijn Coenen * distributed under the License is distributed on an "AS IS" BASIS, 12a1ec95882901ebf386cc794122b36b18ee845554Martijn Coenen * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13a1ec95882901ebf386cc794122b36b18ee845554Martijn Coenen * See the License for the specific language governing permissions and 14a1ec95882901ebf386cc794122b36b18ee845554Martijn Coenen * limitations under the License. 15a1ec95882901ebf386cc794122b36b18ee845554Martijn Coenen */ 16a1ec95882901ebf386cc794122b36b18ee845554Martijn Coenen 17c3178e5f1c346ad5faa926a6765147840116f4a7Martijn Coenenpackage android.nfc.cardemulation; 18c3178e5f1c346ad5faa926a6765147840116f4a7Martijn Coenen 19c3178e5f1c346ad5faa926a6765147840116f4a7Martijn Coenenimport android.annotation.SdkConstant; 20c3178e5f1c346ad5faa926a6765147840116f4a7Martijn Coenenimport android.annotation.SdkConstant.SdkConstantType; 21c3178e5f1c346ad5faa926a6765147840116f4a7Martijn Coenenimport android.app.Service; 22c3178e5f1c346ad5faa926a6765147840116f4a7Martijn Coenenimport android.content.Intent; 2335bf6288527b177a04100585321a1266f020004aMartijn Coenenimport android.content.pm.PackageManager; 24c3178e5f1c346ad5faa926a6765147840116f4a7Martijn Coenenimport android.os.IBinder; 25c3178e5f1c346ad5faa926a6765147840116f4a7Martijn Coenen 26c3178e5f1c346ad5faa926a6765147840116f4a7Martijn Coenen/** 2735bf6288527b177a04100585321a1266f020004aMartijn Coenen * <p>OffHostApduService is a convenience {@link Service} class that can be 2835bf6288527b177a04100585321a1266f020004aMartijn Coenen * extended to describe one or more NFC applications that are residing 2935bf6288527b177a04100585321a1266f020004aMartijn Coenen * off-host, for example on an embedded secure element or a UICC. 3035bf6288527b177a04100585321a1266f020004aMartijn Coenen * 3135bf6288527b177a04100585321a1266f020004aMartijn Coenen * <div class="special reference"> 3235bf6288527b177a04100585321a1266f020004aMartijn Coenen * <h3>Developer Guide</h3> 3335bf6288527b177a04100585321a1266f020004aMartijn Coenen * For a general introduction into the topic of card emulation, 3435bf6288527b177a04100585321a1266f020004aMartijn Coenen * please read the <a href="{@docRoot}guide/topics/nfc/ce.html"> 3535bf6288527b177a04100585321a1266f020004aMartijn Coenen * NFC card emulation developer guide.</a></p> 3635bf6288527b177a04100585321a1266f020004aMartijn Coenen * </div> 3735bf6288527b177a04100585321a1266f020004aMartijn Coenen * 3835bf6288527b177a04100585321a1266f020004aMartijn Coenen * <h3>NFC Protocols</h3> 3935bf6288527b177a04100585321a1266f020004aMartijn Coenen * <p>Off-host applications represented by this class are based on the NFC-Forum ISO-DEP 4035bf6288527b177a04100585321a1266f020004aMartijn Coenen * protocol (based on ISO/IEC 14443-4) and support processing 4135bf6288527b177a04100585321a1266f020004aMartijn Coenen * command Application Protocol Data Units (APDUs) as 4235bf6288527b177a04100585321a1266f020004aMartijn Coenen * defined in the ISO/IEC 7816-4 specification. 4335bf6288527b177a04100585321a1266f020004aMartijn Coenen * 4435bf6288527b177a04100585321a1266f020004aMartijn Coenen * <h3>Service selection</h3> 4535bf6288527b177a04100585321a1266f020004aMartijn Coenen * <p>When a remote NFC device wants to talk to your 4635bf6288527b177a04100585321a1266f020004aMartijn Coenen * off-host NFC application, it sends a so-called 4735bf6288527b177a04100585321a1266f020004aMartijn Coenen * "SELECT AID" APDU as defined in the ISO/IEC 7816-4 specification. 4835bf6288527b177a04100585321a1266f020004aMartijn Coenen * The AID is an application identifier defined in ISO/IEC 7816-4. 4935bf6288527b177a04100585321a1266f020004aMartijn Coenen * 5035bf6288527b177a04100585321a1266f020004aMartijn Coenen * <p>The registration procedure for AIDs is defined in the 5135bf6288527b177a04100585321a1266f020004aMartijn Coenen * ISO/IEC 7816-5 specification. If you don't want to register an 5235bf6288527b177a04100585321a1266f020004aMartijn Coenen * AID, you are free to use AIDs in the proprietary range: 5335bf6288527b177a04100585321a1266f020004aMartijn Coenen * bits 8-5 of the first byte must each be set to '1'. For example, 5435bf6288527b177a04100585321a1266f020004aMartijn Coenen * "0xF00102030405" is a proprietary AID. If you do use proprietary 5535bf6288527b177a04100585321a1266f020004aMartijn Coenen * AIDs, it is recommended to choose an AID of at least 6 bytes, 5635bf6288527b177a04100585321a1266f020004aMartijn Coenen * to reduce the risk of collisions with other applications that 5735bf6288527b177a04100585321a1266f020004aMartijn Coenen * might be using proprietary AIDs as well. 5835bf6288527b177a04100585321a1266f020004aMartijn Coenen * 5935bf6288527b177a04100585321a1266f020004aMartijn Coenen * <h3>AID groups</h3> 6035bf6288527b177a04100585321a1266f020004aMartijn Coenen * <p>In some cases, an off-host environment may need to register multiple AIDs 6135bf6288527b177a04100585321a1266f020004aMartijn Coenen * to implement a certain application, and it needs to be sure 6235bf6288527b177a04100585321a1266f020004aMartijn Coenen * that it is the default handler for all of these AIDs (as opposed 6335bf6288527b177a04100585321a1266f020004aMartijn Coenen * to some AIDs in the group going to another service). 6435bf6288527b177a04100585321a1266f020004aMartijn Coenen * 6535bf6288527b177a04100585321a1266f020004aMartijn Coenen * <p>An AID group is a list of AIDs that should be considered as 6635bf6288527b177a04100585321a1266f020004aMartijn Coenen * belonging together by the OS. For all AIDs in an AID group, the 6735bf6288527b177a04100585321a1266f020004aMartijn Coenen * OS will guarantee one of the following: 6835bf6288527b177a04100585321a1266f020004aMartijn Coenen * <ul> 6935bf6288527b177a04100585321a1266f020004aMartijn Coenen * <li>All AIDs in the group are routed to the off-host execution environment 7035bf6288527b177a04100585321a1266f020004aMartijn Coenen * <li>No AIDs in the group are routed to the off-host execution environment 7135bf6288527b177a04100585321a1266f020004aMartijn Coenen * </ul> 7235bf6288527b177a04100585321a1266f020004aMartijn Coenen * In other words, there is no in-between state, where some AIDs 7335bf6288527b177a04100585321a1266f020004aMartijn Coenen * in the group can be routed to this off-host execution environment, 7435bf6288527b177a04100585321a1266f020004aMartijn Coenen * and some to another or a host-based {@link HostApduService}. 7535bf6288527b177a04100585321a1266f020004aMartijn Coenen * <h3>AID groups and categories</h3> 7635bf6288527b177a04100585321a1266f020004aMartijn Coenen * <p>Each AID group can be associated with a category. This allows 7735bf6288527b177a04100585321a1266f020004aMartijn Coenen * the Android OS to classify services, and it allows the user to 7835bf6288527b177a04100585321a1266f020004aMartijn Coenen * set defaults at the category level instead of the AID level. 7935bf6288527b177a04100585321a1266f020004aMartijn Coenen * 8035bf6288527b177a04100585321a1266f020004aMartijn Coenen * <p>You can use 8135bf6288527b177a04100585321a1266f020004aMartijn Coenen * {@link CardEmulation#isDefaultServiceForCategory(android.content.ComponentName, String)} 8235bf6288527b177a04100585321a1266f020004aMartijn Coenen * to determine if your off-host service is the default handler for a category. 8335bf6288527b177a04100585321a1266f020004aMartijn Coenen * 8435bf6288527b177a04100585321a1266f020004aMartijn Coenen * <p>In this version of the platform, the only known categories 8535bf6288527b177a04100585321a1266f020004aMartijn Coenen * are {@link CardEmulation#CATEGORY_PAYMENT} and {@link CardEmulation#CATEGORY_OTHER}. 8635bf6288527b177a04100585321a1266f020004aMartijn Coenen * AID groups without a category, or with a category that is not recognized 8735bf6288527b177a04100585321a1266f020004aMartijn Coenen * by the current platform version, will automatically be 8835bf6288527b177a04100585321a1266f020004aMartijn Coenen * grouped into the {@link CardEmulation#CATEGORY_OTHER} category. 8935bf6288527b177a04100585321a1266f020004aMartijn Coenen * 9035bf6288527b177a04100585321a1266f020004aMartijn Coenen * <h3>Service AID registration</h3> 9135bf6288527b177a04100585321a1266f020004aMartijn Coenen * <p>To tell the platform which AIDs 9235bf6288527b177a04100585321a1266f020004aMartijn Coenen * reside off-host and are managed by this service, a {@link #SERVICE_META_DATA} 9335bf6288527b177a04100585321a1266f020004aMartijn Coenen * entry must be included in the declaration of the service. An 9435bf6288527b177a04100585321a1266f020004aMartijn Coenen * example of a OffHostApduService manifest declaration is shown below: 9535bf6288527b177a04100585321a1266f020004aMartijn Coenen * <pre> <service android:name=".MyOffHostApduService" android:exported="true" android:permission="android.permission.BIND_NFC_SERVICE"> 9635bf6288527b177a04100585321a1266f020004aMartijn Coenen * <intent-filter> 9735bf6288527b177a04100585321a1266f020004aMartijn Coenen * <action android:name="android.nfc.cardemulation.action.OFF_HOST_APDU_SERVICE"/> 9835bf6288527b177a04100585321a1266f020004aMartijn Coenen * </intent-filter> 9935bf6288527b177a04100585321a1266f020004aMartijn Coenen * <meta-data android:name="android.nfc.cardemulation.off_host_apdu_ervice" android:resource="@xml/apduservice"/> 10035bf6288527b177a04100585321a1266f020004aMartijn Coenen * </service></pre> 10135bf6288527b177a04100585321a1266f020004aMartijn Coenen * 10235bf6288527b177a04100585321a1266f020004aMartijn Coenen * This meta-data tag points to an apduservice.xml file. 10335bf6288527b177a04100585321a1266f020004aMartijn Coenen * An example of this file with a single AID group declaration is shown below: 10435bf6288527b177a04100585321a1266f020004aMartijn Coenen * <pre> 10535bf6288527b177a04100585321a1266f020004aMartijn Coenen * <offhost-apdu-service xmlns:android="http://schemas.android.com/apk/res/android" 10635bf6288527b177a04100585321a1266f020004aMartijn Coenen * android:description="@string/servicedesc"> 10735bf6288527b177a04100585321a1266f020004aMartijn Coenen * <aid-group android:description="@string/subscription" android:category="other"> 10835bf6288527b177a04100585321a1266f020004aMartijn Coenen * <aid-filter android:name="F0010203040506"/> 10935bf6288527b177a04100585321a1266f020004aMartijn Coenen * <aid-filter android:name="F0394148148100"/> 11035bf6288527b177a04100585321a1266f020004aMartijn Coenen * </aid-group> 11135bf6288527b177a04100585321a1266f020004aMartijn Coenen * </offhost-apdu-service> 11235bf6288527b177a04100585321a1266f020004aMartijn Coenen * </pre> 11335bf6288527b177a04100585321a1266f020004aMartijn Coenen * 11435bf6288527b177a04100585321a1266f020004aMartijn Coenen * <p>The {@link android.R.styleable#OffHostApduService <offhost-apdu-service>} is required 11535bf6288527b177a04100585321a1266f020004aMartijn Coenen * to contain a 11635bf6288527b177a04100585321a1266f020004aMartijn Coenen * {@link android.R.styleable#OffHostApduService_description <android:description>} 11735bf6288527b177a04100585321a1266f020004aMartijn Coenen * attribute that contains a user-friendly description of the service that may be shown in UI. 11835bf6288527b177a04100585321a1266f020004aMartijn Coenen * 11935bf6288527b177a04100585321a1266f020004aMartijn Coenen * <p>The {@link android.R.styleable#OffHostApduService <offhost-apdu-service>} must 12035bf6288527b177a04100585321a1266f020004aMartijn Coenen * contain one or more {@link android.R.styleable#AidGroup <aid-group>} tags. 12135bf6288527b177a04100585321a1266f020004aMartijn Coenen * Each {@link android.R.styleable#AidGroup <aid-group>} must contain one or 12235bf6288527b177a04100585321a1266f020004aMartijn Coenen * more {@link android.R.styleable#AidFilter <aid-filter>} tags, each of which 12335bf6288527b177a04100585321a1266f020004aMartijn Coenen * contains a single AID. The AID must be specified in hexadecimal format, and contain 12435bf6288527b177a04100585321a1266f020004aMartijn Coenen * an even number of characters. 125c3178e5f1c346ad5faa926a6765147840116f4a7Martijn Coenen * 126c3178e5f1c346ad5faa926a6765147840116f4a7Martijn Coenen * <p>This registration will allow the service to be included 12735bf6288527b177a04100585321a1266f020004aMartijn Coenen * as an option for being the default handler for categories. 12835bf6288527b177a04100585321a1266f020004aMartijn Coenen * The Android OS will take care of correctly 12935bf6288527b177a04100585321a1266f020004aMartijn Coenen * routing the AIDs to the off-host execution environment, 13035bf6288527b177a04100585321a1266f020004aMartijn Coenen * based on which service the user has selected to be the handler for a certain category. 131c3178e5f1c346ad5faa926a6765147840116f4a7Martijn Coenen * 132c3178e5f1c346ad5faa926a6765147840116f4a7Martijn Coenen * <p>The service may define additional actions outside of the 133c3178e5f1c346ad5faa926a6765147840116f4a7Martijn Coenen * Android namespace that provide further interaction with 134c3178e5f1c346ad5faa926a6765147840116f4a7Martijn Coenen * the off-host execution environment. 135c3178e5f1c346ad5faa926a6765147840116f4a7Martijn Coenen * 13635bf6288527b177a04100585321a1266f020004aMartijn Coenen * <p class="note">Use of this class requires the 13735bf6288527b177a04100585321a1266f020004aMartijn Coenen * {@link PackageManager#FEATURE_NFC_HOST_CARD_EMULATION} to be present 13835bf6288527b177a04100585321a1266f020004aMartijn Coenen * on the device. 139c3178e5f1c346ad5faa926a6765147840116f4a7Martijn Coenen */ 140c3178e5f1c346ad5faa926a6765147840116f4a7Martijn Coenenpublic abstract class OffHostApduService extends Service { 141c3178e5f1c346ad5faa926a6765147840116f4a7Martijn Coenen /** 14235bf6288527b177a04100585321a1266f020004aMartijn Coenen * The {@link Intent} action that must be declared as handled by the service. 143c3178e5f1c346ad5faa926a6765147840116f4a7Martijn Coenen */ 144c3178e5f1c346ad5faa926a6765147840116f4a7Martijn Coenen @SdkConstant(SdkConstantType.SERVICE_ACTION) 145c3178e5f1c346ad5faa926a6765147840116f4a7Martijn Coenen public static final String SERVICE_INTERFACE = 14652246087f4e2b5ad62b9cd6ea8c2cb58f624d4e7Martijn Coenen "android.nfc.cardemulation.action.OFF_HOST_APDU_SERVICE"; 147c3178e5f1c346ad5faa926a6765147840116f4a7Martijn Coenen 148c3178e5f1c346ad5faa926a6765147840116f4a7Martijn Coenen /** 149c3178e5f1c346ad5faa926a6765147840116f4a7Martijn Coenen * The name of the meta-data element that contains 150c3178e5f1c346ad5faa926a6765147840116f4a7Martijn Coenen * more information about this service. 151c3178e5f1c346ad5faa926a6765147840116f4a7Martijn Coenen */ 15252246087f4e2b5ad62b9cd6ea8c2cb58f624d4e7Martijn Coenen public static final String SERVICE_META_DATA = 15352246087f4e2b5ad62b9cd6ea8c2cb58f624d4e7Martijn Coenen "android.nfc.cardemulation.off_host_apdu_service"; 154c3178e5f1c346ad5faa926a6765147840116f4a7Martijn Coenen 155c3178e5f1c346ad5faa926a6765147840116f4a7Martijn Coenen /** 156c3178e5f1c346ad5faa926a6765147840116f4a7Martijn Coenen * The Android platform itself will not bind to this service, 157c3178e5f1c346ad5faa926a6765147840116f4a7Martijn Coenen * but merely uses its declaration to keep track of what AIDs 158c3178e5f1c346ad5faa926a6765147840116f4a7Martijn Coenen * the service is interested in. This information is then used 159c3178e5f1c346ad5faa926a6765147840116f4a7Martijn Coenen * to present the user with a list of applications that can handle 160c3178e5f1c346ad5faa926a6765147840116f4a7Martijn Coenen * an AID, as well as correctly route those AIDs either to the host (in case 161c3178e5f1c346ad5faa926a6765147840116f4a7Martijn Coenen * the user preferred a {@link HostApduService}), or to an off-host 162c3178e5f1c346ad5faa926a6765147840116f4a7Martijn Coenen * execution environment (in case the user preferred a {@link OffHostApduService}. 163c3178e5f1c346ad5faa926a6765147840116f4a7Martijn Coenen * 164c3178e5f1c346ad5faa926a6765147840116f4a7Martijn Coenen * Implementers may define additional actions outside of the 165c3178e5f1c346ad5faa926a6765147840116f4a7Martijn Coenen * Android namespace that allow further interactions with 166c3178e5f1c346ad5faa926a6765147840116f4a7Martijn Coenen * the off-host execution environment. Such implementations 167c3178e5f1c346ad5faa926a6765147840116f4a7Martijn Coenen * would need to override this method. 168c3178e5f1c346ad5faa926a6765147840116f4a7Martijn Coenen */ 169c3178e5f1c346ad5faa926a6765147840116f4a7Martijn Coenen public abstract IBinder onBind(Intent intent); 170a7397883de67d674970d91f86d46ccf637e5e543Martijn Coenen} 171