/*
* Copyright (C) 2015 The Android Open Source Project
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package android.nfc.cardemulation;
import android.annotation.SdkConstant;
import android.annotation.SdkConstant.SdkConstantType;
import android.app.Service;
import android.content.Intent;
import android.content.pm.PackageManager;
import android.os.Bundle;
import android.os.Handler;
import android.os.IBinder;
import android.os.Message;
import android.os.Messenger;
import android.os.RemoteException;
import android.util.Log;
/**
* <p>HostApduService is a convenience {@link Service} class that can be
* extended to emulate an NFC card inside an Android
* service component.
*
* <div class="special reference">
* <h3>Developer Guide</h3>
* For a general introduction to card emulation, see
* <a href="{@docRoot}guide/topics/connectivity/nfc/hce.html">
* Host-based Card Emulation</a>.</p>
* </div>
*
* <h3>NFC Protocols</h3>
* <p>Cards emulated by this class are based on the NFC-Forum ISO-DEP
* protocol (based on ISO/IEC 14443-4) and support processing
* command Application Protocol Data Units (APDUs) as
* defined in the ISO/IEC 7816-4 specification.
*
* <h3>Service selection</h3>
* <p>When a remote NFC device wants to talk to your
* service, it sends a so-called
* "SELECT AID" APDU as defined in the ISO/IEC 7816-4 specification.
* The AID is an application identifier defined in ISO/IEC 7816-4.
*
* <p>The registration procedure for AIDs is defined in the
* ISO/IEC 7816-5 specification. If you don't want to register an
* AID, you are free to use AIDs in the proprietary range:
* bits 8-5 of the first byte must each be set to '1'. For example,
* "0xF00102030405" is a proprietary AID. If you do use proprietary
* AIDs, it is recommended to choose an AID of at least 6 bytes,
* to reduce the risk of collisions with other applications that
* might be using proprietary AIDs as well.
*
* <h3>AID groups</h3>
* <p>In some cases, a service may need to register multiple AIDs
* to implement a certain application, and it needs to be sure
* that it is the default handler for all of these AIDs (as opposed
* to some AIDs in the group going to another service).
*
* <p>An AID group is a list of AIDs that should be considered as
* belonging together by the OS. For all AIDs in an AID group, the
* OS will guarantee one of the following:
* <ul>
* <li>All AIDs in the group are routed to this service
* <li>No AIDs in the group are routed to this service
* </ul>
* In other words, there is no in-between state, where some AIDs
* in the group can be routed to this service, and some to another.
* <h3>AID groups and categories</h3>
* <p>Each AID group can be associated with a category. This allows
* the Android OS to classify services, and it allows the user to
* set defaults at the category level instead of the AID level.
*
* <p>You can use
* {@link CardEmulation#isDefaultServiceForCategory(android.content.ComponentName, String)}
* to determine if your service is the default handler for a category.
*
* <p>In this version of the platform, the only known categories
* are {@link CardEmulation#CATEGORY_PAYMENT} and {@link CardEmulation#CATEGORY_OTHER}.
* AID groups without a category, or with a category that is not recognized
* by the current platform version, will automatically be
* grouped into the {@link CardEmulation#CATEGORY_OTHER} category.
* <h3>Service AID registration</h3>
* <p>To tell the platform which AIDs groups
* are requested by this service, a {@link #SERVICE_META_DATA}
* entry must be included in the declaration of the service. An
* example of a HostApduService manifest declaration is shown below:
* <pre> <service android:name=".MyHostApduService" android:exported="true" android:permission="android.permission.BIND_NFC_SERVICE">
* <intent-filter>
* <action android:name="android.nfc.cardemulation.action.HOST_APDU_SERVICE"/>
* </intent-filter>
* <meta-data android:name="android.nfc.cardemulation.host_apdu_ervice" android:resource="@xml/apduservice"/>
* </service></pre>
*
* This meta-data tag points to an apduservice.xml file.
* An example of this file with a single AID group declaration is shown below:
* <pre>
* <host-apdu-service xmlns:android="http://schemas.android.com/apk/res/android"
* android:description="@string/servicedesc" android:requireDeviceUnlock="false">
* <aid-group android:description="@string/aiddescription" android:category="other">
* <aid-filter android:name="F0010203040506"/>
* <aid-filter android:name="F0394148148100"/>
* </aid-group>
* </host-apdu-service>
* </pre>
*
* <p>The {@link android.R.styleable#HostApduService <host-apdu-service>} is required
* to contain a
* {@link android.R.styleable#HostApduService_description <android:description>}
* attribute that contains a user-friendly description of the service that may be shown in UI.
* The
* {@link android.R.styleable#HostApduService_requireDeviceUnlock <requireDeviceUnlock>}
* attribute can be used to specify that the device must be unlocked before this service
* can be invoked to handle APDUs.
* <p>The {@link android.R.styleable#HostApduService <host-apdu-service>} must
* contain one or more {@link android.R.styleable#AidGroup <aid-group>} tags.
* Each {@link android.R.styleable#AidGroup <aid-group>} must contain one or
* more {@link android.R.styleable#AidFilter <aid-filter>} tags, each of which
* contains a single AID. The AID must be specified in hexadecimal format, and contain
* an even number of characters.
* <h3>AID conflict resolution</h3>
* Multiple HostApduServices may be installed on a single device, and the same AID
* can be registered by more than one service. The Android platform resolves AID
* conflicts depending on which category an AID belongs to. Each category may
* have a different conflict resolution policy. For example, for some categories
* the user may be able to select a default service in the Android settings UI.
* For other categories, to policy may be to always ask the user which service
* is to be invoked in case of conflict.
*
* To query the conflict resolution policy for a certain category, see
* {@link CardEmulation#getSelectionModeForCategory(String)}.
*
* <h3>Data exchange</h3>
* <p>Once the platform has resolved a "SELECT AID" command APDU to a specific
* service component, the "SELECT AID" command APDU and all subsequent
* command APDUs will be sent to that service through
* {@link #processCommandApdu(byte[], Bundle)}, until either:
* <ul>
* <li>The NFC link is broken</li>
* <li>A "SELECT AID" APDU is received which resolves to another service</li>
* </ul>
* These two scenarios are indicated by a call to {@link #onDeactivated(int)}.
*
* <p class="note">Use of this class requires the
* {@link PackageManager#FEATURE_NFC_HOST_CARD_EMULATION} to be present
* on the device.
*
*/
public abstract class HostApduService extends Service {
/**
* The {@link Intent} action that must be declared as handled by the service.
*/
@SdkConstant(SdkConstantType.SERVICE_ACTION)
public static final String SERVICE_INTERFACE =
"android.nfc.cardemulation.action.HOST_APDU_SERVICE";
/**
* The name of the meta-data element that contains
* more information about this service.
*/
public static final String SERVICE_META_DATA =
"android.nfc.cardemulation.host_apdu_service";
/**
* Reason for {@link #onDeactivated(int)}.
* Indicates deactivation was due to the NFC link
* being lost.
*/
public static final int DEACTIVATION_LINK_LOSS = 0;
/**
* Reason for {@link #onDeactivated(int)}.
*
* <p>Indicates deactivation was due to a different AID
* being selected (which implicitly deselects the AID
* currently active on the logical channel).
*
* <p>Note that this next AID may still be resolved to this
* service, in which case {@link #processCommandApdu(byte[], Bundle)}
* will be called again.
*/
public static final int DEACTIVATION_DESELECTED = 1;
static final String TAG = "ApduService";
/**
* MSG_COMMAND_APDU is sent by NfcService when
* a 7816-4 command APDU has been received.
*
* @hide
*/
public static final int MSG_COMMAND_APDU = 0;
/**
* MSG_RESPONSE_APDU is sent to NfcService to send
* a response APDU back to the remote device.
*
* @hide
*/
public static final int MSG_RESPONSE_APDU = 1;
/**
* MSG_DEACTIVATED is sent by NfcService when
* the current session is finished; either because
* another AID was selected that resolved to
* another service, or because the NFC link
* was deactivated.
*
* @hide
*/
public static final int MSG_DEACTIVATED = 2;
/**
*
* @hide
*/
public static final int MSG_UNHANDLED = 3;
/**
* @hide
*/
public static final String KEY_DATA = "data";
/**
* Messenger interface to NfcService for sending responses.
* Only accessed on main thread by the message handler.
*
* @hide
*/
Messenger mNfcService = null;
final Messenger mMessenger = new Messenger(new MsgHandler());
final class MsgHandler extends Handler {
@Override
public void handleMessage(Message msg) {
switch (msg.what) {
case MSG_COMMAND_APDU:
Bundle dataBundle = msg.getData();
if (dataBundle == null) {
return;
}
if (mNfcService == null) mNfcService = msg.replyTo;
byte[] apdu = dataBundle.getByteArray(KEY_DATA);
if (apdu != null) {
byte[] responseApdu = processCommandApdu(apdu, null);
if (responseApdu != null) {
if (mNfcService == null) {
Log.e(TAG, "Response not sent; service was deactivated.");
return;
}
Message responseMsg = Message.obtain(null, MSG_RESPONSE_APDU);
Bundle responseBundle = new Bundle();
responseBundle.putByteArray(KEY_DATA, responseApdu);
responseMsg.setData(responseBundle);
responseMsg.replyTo = mMessenger;
try {
mNfcService.send(responseMsg);
} catch (RemoteException e) {
Log.e("TAG", "Response not sent; RemoteException calling into " +
"NfcService.");
}
}
} else {
Log.e(TAG, "Received MSG_COMMAND_APDU without data.");
}
break;
case MSG_RESPONSE_APDU:
if (mNfcService == null) {
Log.e(TAG, "Response not sent; service was deactivated.");
return;
}
try {
msg.replyTo = mMessenger;
mNfcService.send(msg);
} catch (RemoteException e) {
Log.e(TAG, "RemoteException calling into NfcService.");
}
break;
case MSG_DEACTIVATED:
// Make sure we won't call into NfcService again
mNfcService = null;
onDeactivated(msg.arg1);
break;
case MSG_UNHANDLED:
if (mNfcService == null) {
Log.e(TAG, "notifyUnhandled not sent; service was deactivated.");
return;
}
try {
msg.replyTo = mMessenger;
mNfcService.send(msg);
} catch (RemoteException e) {
Log.e(TAG, "RemoteException calling into NfcService.");
}
break;
default:
super.handleMessage(msg);
}
}
}
@Override
public final IBinder onBind(Intent intent) {
return mMessenger.getBinder();
}
/**
* Sends a response APDU back to the remote device.
*
* <p>Note: this method may be called from any thread and will not block.
* @param responseApdu A byte-array containing the reponse APDU.
*/
public final void sendResponseApdu(byte[] responseApdu) {
Message responseMsg = Message.obtain(null, MSG_RESPONSE_APDU);
Bundle dataBundle = new Bundle();
dataBundle.putByteArray(KEY_DATA, responseApdu);
responseMsg.setData(dataBundle);
try {
mMessenger.send(responseMsg);
} catch (RemoteException e) {
Log.e("TAG", "Local messenger has died.");
}
}
/**
* Calling this method allows the service to tell the OS
* that it won't be able to complete this transaction -
* for example, because it requires data connectivity
* that is not present at that moment.
*
* The OS may use this indication to give the user a list
* of alternative applications that can handle the last
* AID that was selected. If the user would select an
* application from the list, that action by itself
* will not cause the default to be changed; the selected
* application will be invoked for the next tap only.
*
* If there are no other applications that can handle
* this transaction, the OS will show an error dialog
* indicating your service could not complete the
* transaction.
*
* <p>Note: this method may be called anywhere between
* the first {@link #processCommandApdu(byte[], Bundle)}
* call and a {@link #onDeactivated(int)} call.
*/
public final void notifyUnhandled() {
Message unhandledMsg = Message.obtain(null, MSG_UNHANDLED);
try {
mMessenger.send(unhandledMsg);
} catch (RemoteException e) {
Log.e("TAG", "Local messenger has died.");
}
}
/**
* <p>This method will be called when a command APDU has been received
* from a remote device. A response APDU can be provided directly
* by returning a byte-array in this method. Note that in general
* response APDUs must be sent as quickly as possible, given the fact
* that the user is likely holding his device over an NFC reader
* when this method is called.
*
* <p class="note">If there are multiple services that have registered for the same
* AIDs in their meta-data entry, you will only get called if the user has
* explicitly selected your service, either as a default or just for the next tap.
*
* <p class="note">This method is running on the main thread of your application.
* If you cannot return a response APDU immediately, return null
* and use the {@link #sendResponseApdu(byte[])} method later.
*
* @param commandApdu The APDU that was received from the remote device
* @param extras A bundle containing extra data. May be null.
* @return a byte-array containing the response APDU, or null if no
* response APDU can be sent at this point.
*/
public abstract byte[] processCommandApdu(byte[] commandApdu, Bundle extras);
/**
* This method will be called in two possible scenarios:
* <li>The NFC link has been deactivated or lost
* <li>A different AID has been selected and was resolved to a different
* service component
* @param reason Either {@link #DEACTIVATION_LINK_LOSS} or {@link #DEACTIVATION_DESELECTED}
*/
public abstract void onDeactivated(int reason);
}