NFC Android Applications Development Guidelines - …info.afscm.org/.../sites/...development-guidelines-v2.0.8-20150130.pdf · take into account the implementation of the binding

AFSCM Android development guidelines v2.0.7 ( p1/39

Copyright © AFSCM 2014

NFC Android Applications

Development Guidelines

RELEASE 2.0.8

Date 30/01/2015

Reference afscm-android-development-guidelines-v2.0.8-20150130.doc


AFSCM Android development guidelines v2.0.8 p2/39


Document management

Name Company

Authors Christian Bernadine Bouygues Telecom

Mathieu Amiel EI Telecom

Nicolas Sollier

Erwan Louët Orange

Jérome Roussel

Eric Le Bomin SFR

Editor Grégoire Fraisse AFSCM

Document history

Version Date Modification

2.0.8 30/01/2015 The following changes have been applied from v2.0.7 to v2.0.8 of the guidelines:

- Merging of Part 1 to 4 of the guide in the present single document ; See history of each part in version 2.0.7 of the guide: o Guide v2.0.7 Part 1 = Section ‘2. General Purpose’ in v2.0.8, o Guide v2.0.7 Part 2 = Section ‘3. How to use NFC and Secure Element’

in v2.0.8, o Guide v2.0.7 Part 3 = Section ‘4. MNO Mobile Application

Interconnection’ in v2.0.8, o Guide v2.0.7 Part 4 = Section ‘5. Appendix: Synthesis of rules’ in v2.0.8

(exhaustive list of the AFSCM Android Rules with detailed status from last version of the guide).

- Introduction of explanations and Rules related to Android 5.0 Lollipop. Particularly: o Sections 3.1.2 & 3.1.4 updated for Android 5.0 compatibility (rules 2.1

and 2.2 now request to target Android 5.0 API Level 21), o New section ‘3.1.6 Android 5.0 Lollipop specificities’ about Android

5.0 Lollipop specificities containing 3 new Rules, o Link to the SIM Alliance specification updated in section ‘3.1.7.1 API

Overview‘, and definition of a new Rule 2.29 for backward compatibility in section ‘3.1.7.4 Access Control’.

- Suppression of some sections and rules not related to security, now considered as obsolete and/or redundant with the Android documentation provided by Google at http://developer.android.com/. E.g.: o Rules (and related examples) simplified in section ‘2. General Purpose’

(e.g. examples suppressed under Rules 1.4, 1.31, 1.39, 1.42, 1.53 and 1.55, rule 1.24 clarified and moved into section 2.2.1, rule 1.41 suppressed in section ‘Alteration of assets’, Rules 1.49, 1.50, 1.51 and 1.52 simplified in a single Rule 1.49, Etc.),

o Description regarding the ‘Encapsulation’ and ‘String encoding management’ deleted in section ‘2.2 Coding Rules’,

o Suppression of the full section ‘Structure of the application and lifecycle’ (section 2.3 in Part 1 of the guide v2.0.7),

o Suppression of section ‘Server Requests’ and of Rule 1.34 (section

http://developer.android.com/



Version Date Modification

2.6.3 in Part 1 of the guide v2.0.7). o Suppression of section ‘Memory usage’ and of Rule 1.38 (section 2.7.3

in Part 1 of the guide v2.0.7), o Suppression of section ‘Personal data: restricted situations’ and of

Rule 1.52 (section 2.7.6.2 in Part 1 of the guide v2.0.7), o Suppression of Rule 2.7 in section ‘SmartCard API management’ (from

section 2.1.6 in Part 2 of the guide v2.0.7), o Suppression on some requirements on the icon sizes in Rule 3.1 (in

section ‘4.1.2 Metadata definition’ of the present guide). o Suppression of the full section ‘Tutorial’ containing some source code

examples (section 3 in Part 2 of the guide v2.0.7)

- Application of improvements to take into account the remarks and questions received from the MNOs, Service Providers, Application Developpers and/or Laboratories since the release of the guide v2.0.7 in March 2014. E.g.: o Clarifications edited in section ‘2.3.3 Mobile Application signature’ (to

take into account the implementation of the ‘binding’ functionality on the MNO TSM platforms),

o Rules 1.16, 1.26, 1.28 and 2.17 now defined as ‘Mandatory’ (instead of ‘Recommended’),

o Clarification of Rules 1.53 to 1.56 in section ‘Secured Transmission’, o Clarification of Rules 1.58 in section ‘Protection of the Environment’, o Clarification/correction of Rules 2.1 and 2.2 in section ‘NFC Features’

(particularly, the sub-rules 1. to 3. of Rule 2.2 have been put in Rule 2.1 as they are not specific to NDEF tags handling),

o Clarification of Rule 2.19, clarification/correction of the code sample in rule 2.23 and 2 new Rules added in section ‘3.1.5 Android 4.4 KitKat specificities’ (particularly to clarify the synchronization between the Mobile App. and the “Tap & pay” menu),

o Correction of the code sample in Rule 2.14 in section ‘3. NFC Application Launch’.

- Simplification of the guide, correction of some editorial errors and rewording of the Rules to be homogeneous (within the guide and with the other AFSCM technical documents). E.g.: o Update of section ‘1.3 Purpose and content of this document, o Rules now simply defined as ‘Mandatory’ or ‘Recommended’, o Update of the external references in section ‘1.4’, o Update of section ‘1.5 Abbrevations’ and new section ‘1.6 Definitions’ o Rules updated to use ‘shall’ (or ‘shall not’) in case of a mandatory req.

and ‘should’ (or ‘should not’) in case of a recommendation, o ‘application’ replaced by ‘Mobile Application’, ‘UPI’ replaced by ‘MNO

Mobile Application’, etc. o Clarification of section ‘2.5 Security Requirements’ (section 2.7in Part

1 of the guide v2.0.7) to use only the word ‘assets’ (instead of ‘ressources’, ‘data’, ‘files’, etc.).

See ‘Appendix: Synthesis of Rules’ at the end of this guide for a detailed status regarding the update the AFSCM Android Rules.



TABLE OF CONTENTS

1 INTRODUCTION ................................................................................................................... 6

1.1 Context ...................................................................................................................................................6

1.2 Copyright license ....................................................................................................................................6

1.3 Purpose and content of this document..................................................................................................7

1.4 References ..............................................................................................................................................8

1.5 Abbreviation ...........................................................................................................................................9

1.6 Definitions ..............................................................................................................................................9

2 GENERAL PURPOSE .............................................................................................................. 10

2.1 Development process .......................................................................................................................... 10 2.1.1 Specification .......................................................................................................................... 10 2.1.2 Dependencies in terms of device properties and features .................................................. 10 2.1.3 Usage of personal data ......................................................................................................... 10 2.1.4 Testing ................................................................................................................................... 11

2.2 Coding rules ......................................................................................................................................... 11 2.2.1 Complement to Java coding conventions ............................................................................. 11 2.2.2 Exception handling rules ....................................................................................................... 11

2.3 Publishing an Android Mobile Application .......................................................................................... 12 2.3.1 Preparing to Publish .............................................................................................................. 12 2.3.2 Publishing on Google Play ..................................................................................................... 12 2.3.3 Mobile Application signature................................................................................................ 13 2.3.4 Mobile Application update ................................................................................................... 13

2.4 Connectivity ......................................................................................................................................... 13 2.4.1 General Requirements .......................................................................................................... 13 2.4.2 Network ................................................................................................................................ 14 2.4.3 Phone numbers ..................................................................................................................... 14

2.5 Security Requirements ........................................................................................................................ 14 2.5.1 Protection of local assets ...................................................................................................... 14 2.5.2 Protection of private user assets .......................................................................................... 14 2.5.3 Alteration of assets ............................................................................................................... 14 2.5.4 Confidential assets ................................................................................................................ 15 2.5.5 Protection of assets among network communications ........................................................ 15

2.5.5.1 Prohibited transmissions ............................................................................................................. 15 2.5.5.2 Secured transmissions ................................................................................................................. 15

2.6 Protection of the Environment ........................................................................................................... 16

3 HOW TO USE NFC AND SECURE ELEMENT .................................................................................. 17

3.1 NFC Features ....................................................................................................................................... 17 3.1.1 NFC management ................................................................................................................. 17 3.1.2 API Levels .............................................................................................................................. 17 3.1.3 API reference ........................................................................................................................ 18 3.1.4 NDEF tag read/write rules .................................................................................................... 18 3.1.5 Android 4.4 KitKat specificities ............................................................................................. 20

3.1.5.1 Generic rules ............................................................................................................................... 20 3.1.5.2 Payment services specific rules ................................................................................................... 21

3.1.6 Android 5.0 Lollipop specificities .......................................................................................... 24 3.1.7 SmartCard API management ................................................................................................ 25

3.1.7.1 API Overview ............................................................................................................................... 25



3.1.7.2 Security Considerations ............................................................................................................... 25 3.1.7.3 SmartCard API System Security ................................................................................................... 25 3.1.7.4 Access Control ............................................................................................................................. 26 3.1.7.5 Cardlet Contactless Self-Activation ............................................................................................. 26

3.1.8 Peer-to-Peer Data Exchange rules ........................................................................................ 26

3.2 Mobile Application Launch .................................................................................................................. 27 3.2.1 Via MNO Mobile Application ................................................................................................ 27 3.2.2 Via the Card Event (HCI) mechanism .................................................................................... 27 3.2.3 Via NFC tags / external RTD .................................................................................................. 28

3.3 Security Requirements ........................................................................................................................ 29 3.3.1 Specific security features ...................................................................................................... 29 3.3.2 Open Mobile API security features ....................................................................................... 29

4 MNO MOBILE APPLICATION INTERCONNECTION ......................................................................... 30

4.1 MNO and Service Provider Mobile Applications interconnection ...................................................... 30 4.1.1 Goal ....................................................................................................................................... 30 4.1.2 Metadata definition .............................................................................................................. 30 4.1.3 Code samples ........................................................................................................................ 31

5 APPENDIX: SYNTHESIS OF RULES.............................................................................................. 32



1 INTRODUCTION

1.1 Context

The Mobile Network Operators Bouygues Telecom, Orange and SFR have founded the AFSCM (Association Française du Sans Contact Mobile) to foster the development of mobile contactless services.

The AFSCM constituency includes all companies involved in the development of a sustainable market for mobile contactless services such as Service Providers, handset makers, smart card manufacturers, Mobile Network Operators, MVNOs.

The AFSCM members include mobile telephony operators, contactless service providers, manufacturers and technical service providers.

The AFSCM objective is to support the inception of new contactless services for mobile phone users. In particular, the AFSCM endeavors: - To support service providers in the definition and deployment of contactless solutions suited for

mobile subscribers to any available mobile network; - To specify technical guidelines for the development of mobile contactless services to ensure

seamless installation and consistent user experience; - To promote the benefits of the mobile phone platform for contactless service providers,

technology providers and end users.

To define a mutually beneficial mobile contactless eco-system, the AFSCM proposes a shared mobile contactless target mark and a shared brand that distinguishes those contactless services that are available to mobile phone users.

Together, the AFSCM members contribute to the definition of innovative industry standards and best practices.

The stated objective of the AFSCM is to facilitate the development of mobile contactless services.

To this end, the founding members recognize the significance of the following success factors: - Virtuous eco-system in which all parties involved can develop a sustainable market position, - Efficient customer support, - Smooth customer experience, - State-of-the art application life cycle management, - Service portability in the event of a mobile equipment swap.

1.2 Copyright license

The following document is a personal, non-exclusive copyright license between you - the Licensee - and the AFSCM founding members (*), regarding the AFSCM specifications, that must be included in any copy of said specifications.

The licensee is authorized to copy, present or communicate the AFSCM specifications on any media without having to pay any license fee under the condition that the following copyright notice be included in any copy or any excerpt of the specifications:

« Copyright © AFSCM 2008-2015 (Association Française du Sans Contact Mobile ; http://www.afscm.org/). All rights reserved. Terms and conditions to copy, display and communicate these Specifications are available at http://info.afscm.org/credits-mentions-legales/ ».

The licensee is NOT authorized to create or disclose modifications or abstracts of the specifications or work derived from the specifications.

The specifications include detailed functional specifications, technical specifications, NFC handset and NFC UICC implementation guidelines, application development guidelines (Mobile Application and Cardlet) and SP-MNO interconnection guidelines.

http://www.afscm.org/

http://info.afscm.org/credits-mentions-legales/



Separate patent licenses and additional materials will be proposed to those wanting to implement solutions compliant with the AFSCM specifications, under licensing conditions to be defined in separate agreements. Information for procuring such patent licenses and additional materials documents is contained in Annex 1.

THE SPECIFICATIONS ARE SUPPLIED "AS IS" AND NEITHER THE AFSCM NOR ITS MEMBERS ARE COMMITTED TO ANY WARRANTY, EXPLICIT OR IMPLICIT, REGARDING THE SPECIFICATIONS, IN PARTICULAR NO WARRANTY IS GIVEN OF QUALITY, SUITABILITY TO ANY USE WHATSOEVER, ABSENCE OF TITLE OR RIGHTS TO THE CONTENT OF THE SPECIFICATIONS, INSURANCE THAT THE USE OF THE SPECIFICATIONS WILL NOT INFRINGE INTELLECTUAL PROPRETY RIGHTS OF A THIRD PARTY SUCH AS PATENTS, TRADE MARKS, COPYRIGHTS. NEITHER THE AFSCM NOR ITS MEMBERS SHALL BE HELD LIABLE FOR ANY DAMAGE INCURRED IN CONNECTION TO THE USE, REPRESENTATION OR COMMUNICATION OF THE SPECIFICATIONS.

Neither the AFSCM name nor its trade marks shall be used under any circumstances, such as to communicate or advertise the specifications without the prior written agreement of the AFSCM.

No rights other than the rights described above are granted under this license and the rights granted under this license cannot be construed as conferring, implicitly or explicitly, any rights (through a licensing agreement or any other means) concerning AFSCM or AFSCM members inventions, know-how or intellectual property, or any of their assets resulting from, based on or required in the specifications.

This copyright license is subject to French law and shall be governed by and interpreted according to French laws. The exclusive place of jurisdiction shall be the Paris Court of Appeal, regardless of the number of claims or defendants.

By downloading the AFSCM specifications, you indicate your acceptance of these terms and conditions.

(*): AFSCM founding members are : Bouygues Telecom, Orange France / France Telecom, SFR

1.3 Purpose and content of this document

The purpose of this document is to provide to Service Providers some security rules and best practice guidelines to develop their service Mobile Application on the Android mobile operating system.

Note: Security rules and best practice guidelines to develop a Cardlet are described in the AFSCM Cardlet Development Guidelines ([R3]).

This document focuses on card emulation application development, which is the more specific, lesser documented topic in the industry.

The mobile network operators members of the AFSCM have agreed on a common set of rules and recommendations regarding the design and the development of Mobile Applications appropriate for the context of NFC services. This document therefore also serves as a reference for the AFSCM NFC Applications Validation Process as described in the corresponding AFSCM guides ([R2]).

This document intends to refer to existing documents and specifications and to highlight the topics that are relevant regarding Mobile Applications development in these documents.

The safety of a Mobile Application is achieved through a variety of factors mentioned throughout this document, ranging from the development process to the correct use of the APIs, and the structure of the Mobile Application. In addition, because these applications are intended to be embedded on mobile handsets they require particular care in the usage of the operators and devices resources.

Throughout the document, the key points are highlighted with the following icons:

Recommended

Mandatory



1.4 References

AFSCM:

The following documents are available for the Service Providers on the AFSCM website (www.afscm.org):

[R1] Interface Specification between Telecom Operators and NFC Service Providers

[R2] NFC Applications Validation Process, Derogation form and Delivery of the Publisher and Acknowledgment to Security Requirements

[R3] Cardlet Development Guide

[R4] Guidelines for interconnection of Service Providers' and MNOs' Information Systems

The AFSCM also specifies high level requirements for both UICC and mobile handset in separate documents.

Google:

http://android-developers.blogspot.com/2010/08/best-practices-for-handling-android.html

http://source.android.com/source/code-style.html

http://developer.android.com/guide/practices/design/performance.html

http://developer.android.com/guide/publishing/preparing.html http://developer.android.com/guide/topics/nfc/index.html

http://developer.android.com/guide/topics/nfc/nfc.html#ext-type

http://developer.android.com/guide/topics/nfc/advanced-nfc.html

http://developer.android.com/guide/topics/connectivity/nfc/hce.html

NFC Forum:

http://www.nfc-forum.org/specs/

GSMA:

GSMA NFC Handset Requirements (TS.26) available at:

http://www.gsma.com/newsroom/technical-documents/

http://www.afscm.org/



http://developer.android.com/guide/practices/design/performance.html

http://developer.android.com/guide/publishing/preparing.html

http://developer.android.com/guide/topics/nfc/index.html




http://www.nfc-forum.org/specs/

http://www.gsma.com/newsroom/technical-documents/



1.5 Abbreviation

AFSCM Association française du sans contact mobile

AID Application (or Applet) IDentifier

APDU Application Protocol Data Unit

API Application Programming Interface

APK Android Application Package

ATR Answer To Reset

GUI Graphical User Interface

MNO Mobile Network Operator

NDEF NFC Data Exchange Format

NFC Near Field Communication

SE Secure Element

SIM Subscriber Identity Module

UICC Universal Integrated Circuit Card (aka SIM)

URL Uniform Resource Locator

URI Uniform Resource Identifier

1.6 Definitions

Acknowledgment to Security Requirements

Declarative document to be provided by the Service Provider for the AFSCM NFC Application Validation Process described in the AFSCM NFC Applications Validation Process guidelines [R2]

Cardlet JavaCard application loaded onto the UICC (also known as UICC application or applet)

Mobile Application Application loaded onto the mobile handset, providing a GUI (may be simply called ‘application’ in the present guide, and also known as MMI)

Service Combination of a Cardlet and a Mobile Application (also known as NFC service or Mobile NFC service)

Service Provider Entity which provides an NFC service

Validation Entity Entity in charge of validating that the security level in the applications meets the security requirements (typically, a laboratory)



2 GENERAL PURPOSE

2.1 Development process

The entire development process needs to be adapted to the specific aspects of Android. In particular, such applications are usually small and difficult to manage, mostly because of portability consideration.

Designing the Mobile Application to minimize the device-specific part of the code, and integrating this issue into the development process (e.g. usage of build directives) requires special attention.

2.1.1 Specification

The most common issue is under specification. For the development of Mobile Application like Android or Windows Phone applications, the specification should particularly take care of:

Define the usage of network resources:

The specification should design the Mobile Application in order to limit the number of network exchanges (e.g. number of request, of SMS …) and the volume of transferred data.

This specification should particularly consider the impact of network exchanges on availability of the network, and consider the cost implied o the end-user.

Define the security assets:

The Mobile Application may define its own secrets or sensitive data and could manipulate end-user personal data. It is the responsibility of the Mobile Application to guarantee that the integrity and/or the confidentiality of the elements are managed by the Mobile Application itself or by the Android environment. The best location for sensitive data remains the UICC or a Secure Element.

Define the behavior of the Mobile Application under abnormal situations:

Only specifying the nominal cases may lead to leave potential vulnerabilities.

Define the usage of handset resources

Check that the needed APIs are those authorized in the current document

2.1.2 Dependencies in terms of device properties and features

Rule 1.1: System properties accessed within method System.getProperty shall be hard-coded.

The list of operating system properties and APIs features accessed by the Mobile Application must be documented and transmitted to the Validation Entity for certification purposes [R2]:

Rule 1.2: The list of all system properties accessed shall be provided. (See System.getProperties at http://developer.android.com/reference/java/lang/System.html#getProperties%28%29).

Rule 1.3: The list of all external APIs imported by the Mobile Application shall be provided (including list of proprietary APIs and device-specific).

Rule 1.4: The list of all external APIs packaged with the Mobile Application’s binary file shall be provided.

2.1.3 Usage of personal data

The list of accessed personal data and the description on their handling must be defined. The following rules thus apply:

Rule 1.5: The list of all personal data accessed by the Mobile Application shall be provided.

Rule 1.6: The type (or category) of each personal data accessed by the Mobile Application shall be provided.

http://developer.android.com/reference/java/lang/System.html#getProperties%28%29



Rule 1.7: The list of all files and folders accessed by the Mobile Application shall be provided.

Rule 1.8: The type of each file accessed by the Mobile Application shall be provided.

Rule 1.9: A description of usage of read/write accesses on existing personal data elements shall be provided.

Rule 1.10: A description of creation/deletion of personal data elements shall be provided.

Rule 1.11: A description of copying, storing and transferring personal data elements and their destination location shall be provided.

More details can be found at http://android-developers.blogspot.com/2010/08/best-practices-for-handling-android.html.

In France, depending on the type of data accessed, the Service Provider may have to declare this information to the CNIL (http://www.cnil.fr).

2.1.4 Testing

Several elements of the mobile handset including the Dalvik Virtual Machine and the screen size are specific to each mobile manufacturer and will result in discrepancies in the Mobile Application behavior.

It is strongly recommended to test the Mobile Applications on each targeted device.

2.2 Coding rules

Since Android is based on Java, many style and good practice rules from Java apply to Android applications as illustrated in the next paragraphs.

Programs are much easier to maintain when all files have a consistent style. The following paragraph is a subset of the Android Code Style (http://source.android.com/source/code-style.html).

2.2.1 Complement to Java coding conventions

Android follows standard Java coding conventions. Android adds a few rules:

Rule 1.12: Finalizers should not be used.

Rule 1.13: Imports shall be fully imported. The ordering of import statements is: 1. Android imports 2. Imports from third parties (com, junit, net, org) 3. java and javax

Rule 1.14: Native interface shall not be used (use of NDK is forbidden).

Rule 1.15: Access qualifier should be used.

Android applications are separated from each other by the standard sandbox model. Thus, developers tend to neglect the strict control of the accessibility of their classes, fields and methods, by making them all public. If this has no direct consequence on security for applications, there are several reasons for which it is interesting to deal with classes, methods or fields attributes.

Rule 1.24: Logging shall be deactivated and debugging options shall be disabled in the released Mobile Application.

2.2.2 Exception handling rules

A Mobile Application should catch all possible exceptions, including runtime exceptions, in order to avoid the handling of exceptions by the platform, whose default action is to display the exception trace to the end-user and kill the Mobile Application.

In order to take the proper action, it is better to use specific exceptions in catch clauses.

Rule 1.17: Exceptions shall be properly caught and handled.

Rule 1.18: Exceptions shall not be caught and ignored without explanation.



http://www.cnil.fr/


http://developer.android.com/guide/topics/security/security.html



Rule 1.19: The generic java.lang.Exception shall not be the first exception caught.

Rule 1.21: Long class and methods should be avoided, and the object oriented programming philosophy should be respected. To the extent that it is feasible, methods should be kept small and focused. It is, however, recognized that long methods are sometimes appropriate, so no hard limit is placed on method length. If a method exceeds 40 lines or so, think about whether it can be broken up without harming the structure of the program.

Rule 1.22: Recursion shall not be used.

Rule 1.23: All switch statements shall include a default rule.

2.3 Publishing an Android Mobile Application

2.3.1 Preparing to Publish

Publishing an Android Mobile Application means testing it, packaging it appropriately, and making it available to users of Android-powered mobile devices. This paragraph highlights the significant checkpoints for preparing an Android Mobile Application for a release.

Before considering the Mobile Application ready for release:

Test the Mobile Application extensively on several actual devices

Consider adding an End User License Agreement in the Mobile Application

Consider adding licensing support

Specify an icon and label in the Mobile Application's manifest

Turn off logging and debugging and clean up data/files

Before doing the final compile of the Mobile Application:

Version the Mobile Application

Obtain a suitable cryptographic key

Register for a Maps API Key, if the Mobile Application is using MapView elements

Compile the Mobile Application.

After compiling the Mobile Application:

Sign the Mobile Application

Test the signed Mobile Application

2.3.2 Publishing on Google Play

To publish an Android Mobile Application on Google Play, the service provider first need to register with the service using a Google account and agree to the terms of service. Then the Mobile Application can be uploaded to the service and published when ready. Once published, users can see the Mobile Application, download it, and rate it using the Play Store application installed on their Android-powered devices.

To publish an Android Mobile Application on Google Play, it has to meet the requirements listed below, which are enforced by the Play Store server when the Mobile Application is uploaded.

Requirements enforced by the Google Play server:

The Mobile Application must be signed with a cryptographic private key whose validity period ends after 22 October 2033.

The Mobile Application must define both an android:versionCode and an android:versionName attribute in the <manifest> element of its manifest. The server uses the android:versionCode as the basis for identifying the Mobile Application internally and handling updates, and it displays the android:versionName to users as the Mobile Application's version.



The Mobile Application must define both an android:icon and an android:label attribute in the <application> element of its manifest.

The service provider must ensure that the Mobile Application will be shown to the user only if the device is NFC ready.

The new version of the Mobile Application has to match the previous version regarding NFC capabilities and backward compatibility

2.3.3 Mobile Application signature

In order to allow access to the Cardlet on the UICC, a signature must be applied on the Mobile Application either by the Service Providers (‘SP self-signing mode’) or the Mobile Network Operators (‘MNO signing mode’).

More information regarding these 2 modes of Mobile Application signature may be found in [R2] and [R4].

A Mobile Application can only be signed once. The format used for the signature can be either MD5 or SHA1, depending on the Service Provider’s needs (by default, the SHA1 format will be provided by the MNOs).

In ‘MNO signing mode’:

Rule 1.26: For Mobile Application deployed in MNO signing mode, since the package identifier must be unique, the Service Provider shall publish as many variants of Mobile Applications as there are MNO supported.

Rule 1.27: For Mobile Application deployed in MNO signing mode, the Mobile Application name should include the MNO name in order to guide the end user the correct Mobile Application.

In ‘SP self-signing mode’:

Since a single variant of the Mobile Application is published on the Google Play Store, the SP should ensure that the description of the Mobile Application on the store clearly indicates which MNOs are concerned by the related service.

Note: the certificate used for signing an MNO or Service Provider Mobile Application must have a validity period ending after November 2033 (MNO certificate in MNO signing mode or SP certificate in SP self-signing mode). This is requested by Google so as to ensure that it will be possible to upgrade the Mobile Application on the Google Play Store when new releases are available.

2.3.4 Mobile Application update

Rule 1.1: When publishing an update to its Mobile Application, the SP shall increment the android:versionCode property.

2.4 Connectivity

Android/Google specification defines a Connectivity Framework (Webkit and Apache HTTP librairies) which gives to the Mobile Applications the possibility to establish data connections with distant server.

2.4.1 General Requirements

Many APIs use URLs to refer to resources. Beyond the connection APIs, URLs are also used in media players, and elsewhere.

It is therefore very important to determine properties about URLs, because they are used by the verification process to determine which protocols – connections – resources are used by the Mobile Application. This information can actually be inferred if the URLs comply with simple constraints such as specifying a determined scheme.

Rule 1.29: The Mobile Application shall only use URLs in which the protocol and destination host are determined.



Rule 1.30: URLs shall not be dynamically built (the Mobile Application shall use fixed host strings).

2.4.2 Network

Rule 1.31: The Mobile Application shall only use HTTP and HTTPS network connections. In particular, the following low-level protocols are prohibited: datagram, socket, ssl and tcpobex.

Rule 1.32: The Mobile Application shall not open connections to numerical IP addresses. This rule simply consists in forbidding the usage of numerical IP addresses to meet both portability and security requirements.

Rule 1.33: The Mobile Application shall not open connections to local host. As previously mentioned, Mobile Applications are not allowed to share data and services with other applications. Opening a connection to localhost or to 127.0.0.1 is therefore strictly prohibited since it can be used to get out of the application’s sandbox, by performing direct exchanges with native code on the platform.

2.4.3 Phone numbers

The following rule must be respected by the Mobile Application when managing phone numbers:

Rule 1.35: The Mobile Application shall only use constant or determined phone numbers. This is particularly important to detect costly calls to premium or international numbers.

2.5 Security Requirements

2.5.1 Protection of local assets

The Mobile Application is responsible for the protection of the local assets (= all the information generated and/or handled by the Mobile Application) during their manipulation.

Depending of the type of manipulated asset, the Mobile Application should take appropriate security measures to ensure its protection.

2.5.2 Protection of private user assets

Rule 1.36: The Mobile Application shall not access any non-public resources of other applications.

Rule 1.37: The Mobile Application shall neither access the user’s MSISDN, nor the IMSI, nor the IMEI.

2.5.3 Alteration of assets

Mobile Applications are not supposed to alter or corrupt the assets managed by the mobile Operating System, mostly because these assets are shared with other applications and this could lead to severe functional issues.

Rule 1.39: The Mobile Application shall not alter user assets without end user approval (e.g. the Mobile Application shall not add new contacts or calendar events without the end user approval).

Rule 1.40: The Mobile Application shall verify the consistency of its database. This rule simply recommends Mobile Applications to perform format verification on the content of the database while inserting or extracting data. This may be useful to detect a record corruption.

Rule 1.43: The Mobile Application shall verify the consistency of its files. This rule simply recommends Mobile Applications to perform format verification on the content of their own files while inserting or extracting data. This may be useful to detect a file’s corruption.



Rule 1.42: The Mobile Application shall preserve RFID tags integrity. The Mobile Application shall make significant effort to preserve the integrity of the RFID tags it writes (e.g., when writing NDEF tags).

2.5.4 Confidential assets

The Mobile Application may be responsible to manage confidential assets. These assets are end-user’s secrets (e.g., service logins and passwords) or application-own asset (e.g., activation or encryption keys).

Rule 1.44: The Mobile Application shall not define default passwords for accessing its services. Most end-users never change the password attributed by the service. Thus, defining default password exposes users to identity theft attacks.

Rule 1.45: Mobile Application’s secrets shall not be hard coded plaintext in the code. On some devices and some provisioning servers, the APK file is not protected against disclosure. Thus, an attacker could disassemble the Mobile Application’s code and retrieve any secret value it contains.

Rule 1.46: Secrets shall not be stored in plaintext format in the local storage. Developers should particularly consider the issue about persistent storage, as files and (on some device) record stores are exposed to data disclosure. As a consequence, the Mobile Application must implement encryption features to protect these secrets.

Rule 1.47: Secrets shall not be decrypted for comparison. When possible, the Mobile Application should prefer to perform the verification of secrets on encrypted values. This will prevent the Mobile Application from involuntary storing the plaintext secret value.

2.5.5 Protection of assets among network communications

Most of the assets manipulated by the Mobile Application are not intended to be transmitted to any remote entity. This is the purpose of this section which defines the security guidelines accordingly.

2.5.5.1 Prohibited transmissions

In order to preserve end user's privacy, the Mobile Applications are not allowed to transmit to remote entities some categories of data.

Rule 1.48: The Mobile Application shall not send Operator and third party data. Usage of Operator data should be restricted to local computations.

Rule 1.49: The Mobile Application shall inform the end user of the usage and storage of end user identification data, end user authentication data, device localization data and device network identification information when these data are sent to a remote server.

2.5.5.2 Secured transmissions

For data that could be exchanged between entities, some of them may require the implementation of specific security mechanisms, especially to prevent social-engineering attacks.

Rule 1.53: The Mobile Application shall implement mutual authentication mechanisms when sending end user personal data or mobile network operator data.

Rule 1.55: The Mobile Application shall use encrypted communications when sending end user personal data or mobile network operator data.

Rule 1.54: The design of the Mobile Application should not permit replay attacks. This is the only server-oriented security requirement mentioned in this document as it has some impact on the implementation of the local agent. In particular requests to remote servers shall be protected against replay attacks, especially authentication requests, as it should not be possible for an attacker to illegally authenticate on servers.



Rule 1.56: The Mobile Application shall be able to handle the cases when the Cardlet is not present on the UICC.

2.6 Protection of the Environment

The security of Mobile Applications does not only concern local features, but also requires considering the global environment. Mobile handset are mobile items in a wide network connecting personal computers, other handsets, other devices (headphone, GPS receiver), through several operating systems and protocols.

Thus, the Mobile Applications are not only the direct target of the attacks: they could be used as communication interfaces, for instance to propagate a malware program.

This is also particularly important to focus on some security guidelines defining how the Mobile Application should behave in such connected environment.

Rule 1.57: The Mobile Application shall not send any executable program to remote entities. A Mobile Application must not be a vector to propagate malware programs among the network. Mobile Applications that send some files are intended to verify these files are not executable among the following non-exhaustive list of extensions: .exe, .cab, .msi, .sis, .jar, .bat, .sh, .pif.

Rule 1.58: The Mobile Application shall not send binary SMS/MMS messages containing executable code. This rule is an extension of the previous requirement, to precise that is also applies to SMS or MMS binary messages: executable code must be prohibited in the body of these messages.

Rule 1.59: The Mobile Application shall not intensively use network resources. In particular, the Mobile Application shall not massively send emails or any kind of data because: - It implies a cost to the end-user; - It could have a significant impact on the bandwidth; - It could be associated to spam operations.



3 HOW TO USE NFC AND SECURE ELEMENT

3.1 NFC Features

3.1.1 NFC management

The NFC controller is the dedicated chipset (with its antenna) which enables the contactless communication. Three modes are supported:

Card/Tag writing/reading

Card emulation

Peer-to-peer

By using the Android NFC APIs, developers can:

Read/write passive contactless device

Exchange APDU with (external) contactless smart card.

Furthermore, the NFC with Android implements the “Push” mechanism. “Push” is a very powerful concept and typically refers to the mechanism or ability to receive and act on information asynchronously, as information becomes available, instead of forcing the Mobile Application to use synchronous polling techniques that increase resource use or latency.

3.1.2 API Levels

The access to Near Field Communication (NFC) functionality is supported only on Android GingerBread (2.3, API Level 9) and higher versions.

From Android Ice Cream Sandwich (4.0.3, API Level 15), the NFC functionality allowing Mobile Applications to read NFC Data Exchange Format (NDEF) messages in NFC tags has been improved. Note: for API Level < 15, Android only supports limited tag dispatch via ACTION_TAG_DISCOVERED, and only gives access to NDEF messages via the EXTRA_NDEF_MESSAGES extra (no other tag properties or I/O operations are accessible).

From Android KitKat (4.4, API Level 19), new APIs related to card emulation have been introduced. The Mobile Application must declare a new off-host APDU service and define the AIDs that it uses in order to stay compatible with devices running Android KitKat (new or updated devices).

Starting with Android Lollipop (5.0, API Level 21), new APIs have been added to support dynamic AID registration at runtime, complementing the static AID definition introduced in Android KitKat.

Rule 2.1: In the Manifest file and in the SDK project properties, minimum API Level shall be set to 9 or above, with a recommended value of 15 or above; and target API Level shall be set to 21 or above (in order to use both the Android 4.4 KitKat and Android 5.0 Lollipop APIs related to card emulation). Therefore, when accessing a device's NFC hardware, the following items shall be declared in the AndroidManifest.xml file:

1. The NFC <uses-permission> element to access the NFC hardware:

<uses-permission android:name="android.permission.NFC" />

2. The minimum SDK version that the Mobile Application can support. The minimum SDK version shall be ≥ 9, but it is recommended to use minimum SDK version ≥ 15 which includes comprehensive reader/writer support.

And the Target SDK version that is used to define the API set against which the Mobile Application is built. Since API Level 21 defines new values that are important in the use of card emulation, target SDK version ≥ 21 shall be used.

<uses-sdk android:minSdkVersion="x" android:targetSdkVersion="y" />



Where x ≥ 9 (x ≥ 15 is recommended) and y ≥ 21.

3. The uses-feature element so that the Mobile Application can show up in the Android Play Store for devices that have NFC hardware: <uses-feature android:name="android.hardware.nfc" android:required="true" />

3.1.3 API reference

A summary of the classes can be found at: http://developer.android.com/reference/android/nfc/package-summary.html

3.1.4 NDEF tag read/write rules

The rules in this paragraph are conditional. They become applicable only when the Mobile Application implements the tag reading/writing feature.

Rule 2.2: To properly handle NFC intents, the following item shall be declared in the AndroidManifest.xml file: The NFC intent filter to tell the Android system the Activity can handle NFC data (specify one or more of these three intents filters in the activity).

<intent-filter>

<action android:name="android.nfc.action.NDEF_DISCOVERED"/>

<data android:mimeType="mime/type" />

</intent-filter>

<intent-filter>

<action android:name="android.nfc.action.TECH_DISCOVERED"/>

<meta-data android:name="android.nfc.action.TECH_DISCOVERED"

android:resource="@xml/nfc_tech_filter.xml" />

</intent-filter>

<intent-filter>

<action android:name="android.nfc.action.TAG_DISCOVERED"/>

</intent-filter>

The three intent filters are prioritized and behave in specific ways. Declare only the ones that the Activity needs to handle.

The Tag Dispatch System

When an Android device scans an NFC tag, the desired behavior is to have the most appropriate Activity handle the intent without asking the user what Mobile Application to use. Because devices scan NFC tags at a very short range, it is likely that making users manually select an Activity forces them to move the device away from the tag and break the connection.

Rule 2.3: The developer shall develop the Activity to only handle the NFC tags that the Activity cares about to prevent the Activity Chooser from appearing.

Android provides two systems to help the developer correctly identify an NFC tag that the Activity should handle:

the Intent dispatch system and

the foreground Activity dispatch system.

The intent dispatch system

The intent dispatch system checks the intent filters of all the Activities along with the types of data that the Activities support to find the best Activity that can handle the NFC tag. If multiple Activities

http://developer.android.com/reference/android/nfc/package-summary.html



specify the same intent filter and data to handle, then the Activity Chooser is presented to the user as a last resort.

The intent dispatch system specifies three intents that each has a priority:

android.nfc.action.NDEF_DISCOVERED

android.nfc.action.TECH_DISCOVERED

android.nfc.action.TAG_DISCOVERED

The intents that start when a device scans a tag depend on the type of tag scanned. In general, the intents are started in the following manner:

android.nfc.action.NDEF_DISCOVERED: This intent starts when a tag that contains an NDEF payload is scanned. This is the highest priority intent. The Android system does not let the developer specify this intent generically to handle all data types.

If the NDEF_DISCOVERED intent is started, the TECH_DISCOVERED and TAG_DISCOVERED intents are not started.

This intent does not start if an unknown tag is scanned or if the tag does not contain an NDEF payload.

android.nfc.action.TECH_DISCOVERED: If the NDEF_DISCOVERED intent does not start or is not filtered by any Activity on the device, this intent starts if the tag is known. The TECH_DISCOVERED intent requires that the developer specifies the technologies that he/she wants to support in an XML resource file.

android.nfc.action.TAG_DISCOVERED: This intent starts if no Activities handle the NDEF_DISCOVERED and TECH_DISCOVERED intents or if the tag that is scanned is unknown.

Rule 2.4: The developer shall specify <data> elements in the AndroidManifest.xml along with this intent to correctly handle NFC tags that start this intent. For instance, to handle a NDEF_DISCOVERED intent that contains plain text, specify the following filter in your AndroidManifest.xml file: <intent-filter>

<action android:name="android.nfc.action.NDEF_DISCOVERED"/>

<data android:mimeType="text/plain" />

</intent-filter>

Rule 2.5: If an Activity declares the android.nfc.action.TECH_DISCOVERED intent in your AndroidManifest.xml file, the developer should create an XML resource file that specifies the technologies that the Activity supports within a tech-list set. The Activity is considered a match if a tech-list set is a subset of the technologies that are supported by the tag, which the developer can obtain by calling getTechList().

The foreground dispatch system

The foreground dispatch system allows an Activity application to override the intent dispatch system and have priority when an NFC tag is scanned. The Activity handling the request must be running in the foreground of the device. When an NFC tag is scanned and matches the intent and data type that the foreground dispatch Activity defines, the intent is immediately sent to the Activity even if another Activity can handle the intent. If the Activity cannot handle the intent, the foreground dispatch system falls back to the intent dispatch system.

The foreground dispatch system allows an Activity to intercept intent and claim priority over other Activities that handle the same intent. The system is easy to use and involves constructing a few data



structures for the Android system to be able to send the appropriate intents to the Mobile Application.

Rule 2.6: When using the foreground dispatch system, the developer should define the MIME that will be handled. Only the ones needed have to be specified.

More details about working with data on NFC Tags, reading an NFC Tag, writing to an NFC Tag are available at:

http://developer.android.com/guide/topics/nfc/nfc.html,

http://developer.android.com/guide/topics/nfc/advanced-nfc.html,

3.1.5 Android 4.4 KitKat specificities

Android 4.4 defines new APIs related to card emulation. These apply to both software-based card emulation (also-called HCE) and UICC card emulation. These are documented on the following website:


In order to stay compatible with devices running Android v4.4 and above, the Mobile Application must define the AIDs that it uses.

3.1.5.1 Generic rules

The rules defined in this section concern all services (including payment).

Rule 2.19: For card emulation based services, in order to be compliant with Android 4.4, the following shall be added to the Mobile Application :

1. The AndroidManifest .xml file’s <application> element shall contain an off-host APDU service, as follows:

<service android:name=".MyOffHostApduService" android:exported="true"

android:icon="@drawable/ic_launcher"

android:label="@string/app_name"

android:permission="android.permission.BIND_NFC_SERVICE">

<intent-filter>

<action android:name="android.nfc.cardemulation.action.OFF_HOST_APDU_SERVICE"/>

</intent-filter>

<meta-data

android:name="android.nfc.cardemulation.off_host_apdu_service"

android:resource="@xml/apduservice"/>

</service>

2. An apduservice.xml file containing the AID list shall be created under res/xml folder (or res/xml-v19). This list shall include all AIDs which are used by the Mobile Application over the contactless interface:

<offhost-apdu-service xmlns:android="http://schemas.android.com/apk/res/android"

android:description="@string/servicedesc">

<aid-group

android:description="@string/subscription"

android:category="other">

<aid-filter android:name="… AID here …"/>

<aid-filter android:name="… AID here …"/>

…

</aid-group>

</offhost-apdu-service>

Note: the hexadecimal letters [a-f] should be upper-cases. Thus a correct AID will be 01B101AE024678.

http://developer.android.com/guide/topics/nfc/nfc.html





In the above example for Rule 2.19 bullet 1 (service xml tag), the class associated to the off-host APDU service is defined within the package name. Whilst this is the default in most implementation, Android allows to define any class name in the android:name field. If not defined within the Mobile Application’s main package name, this class name will not be recognised by the MNO Mobile Application, and therefore might not be identified as a UICC-based Mobile Application. As a consequence, the following rule applies:

Rule 2.25: The OffHostApduService class name shall be defined within the Mobile Application’s primary package name.

3.1.5.2 Payment services specific rules

Since payment services are handled slightly differently in Android, the following applies only to payment services.

Rule 2.20: For card emulation based payment services, the android:category shall be set to “payment” in the aid-group XML definition.

Rule 2.21: For card emulation based payment services, the list of AIDs shall include the PPSE’s AID (325041592E5359532E4444463031).

Rule 2.22: For card emulation based payment services, a drawable (bitmap) logo shall be defined in the Mobile Application that represents the payment service, for all dpi configurations.

Those rules will lead to an XML definition as follows:

<offhost-apdu-service xmlns:android="http://schemas.android.com/apk/res/android"

android:description="@string/servicedesc"

android:apduServiceBanner="@drawable/servicelogo">

<aid-group

android:description="@string/subscription"

android:category="payment">

<aid-filter android:name="325041592E5359532E4444463031"/>

<aid-filter android:name="… payment AID here …"/>

…

</aid-group>

</offhost-apdu-service>

Rule 2.23: For card emulation based payment services, as per the Manifest file definition above, a new Service class extending OffHostApduService shall be implemented as described in the following minimal example (this class will handle the change of default payment, when triggered by the end user directly from the new “Tap & pay” settings menu introduced in Android 4.4) :

package com.myapp.offhost;

import android.content.ComponentName;

import android.content.Intent;

import android.database.ContentObserver;

import android.net.Uri;

import android.nfc.NfcAdapter;

import android.nfc.cardemulation.CardEmulation;

import android.nfc.cardemulation.OffHostApduService;

import android.os.Handler;

import android.os.IBinder;

import android.os.Looper;

import android.provider.Settings;

http://schemas.android.com/apk/res/android



@TargetApi(19)

public class MyOffHostApduService extends OffHostApduService {

@TargetApi(19)

@Override

public IBinder onBind(Intent arg0) {

// Required as the method is abstract in the parent class.

return null;

}

final Handler mHandler = new Handler(Looper.getMainLooper());

/**

* This method will register a ContentObserver, that will be

* notified when this payment application is selected as the

* new default payment from the Android settings.

*/

@Override

public void onCreate() {

SettingsObserver observer = new SettingsObserver(mHandler);

Uri paymentSettingUri = null;

try {

// The NFC_PAYMENT_DEFAULT_COMPONENT String setting is

// public in the Settings.Secure class but is not visible

// in the Android 4.4 SDK (API 19). Reflection is used

// to get its actual value.

String paymentSetting = (String) Settings.Secure.class

.getField("NFC_PAYMENT_DEFAULT_COMPONENT")

.get(new Settings.Secure());

paymentSettingUri = Settings.Secure.getUriFor(paymentSetting);

// Register a ContentObserver to be notified when the

// default payment is changed.

getContentResolver().registerContentObserver(

paymentSettingUri, true, observer);

} catch (IllegalAccessException e) {

} catch (NoSuchFieldException e) {

}

// This service is not launched until the user changes the

// "Tap & pay" settings for a first time. In that case, the

// observer was not set-up yet and onChange needs to

// be called manually.

if (paymentSettingUri != null) {

observer.onChange(true, paymentSettingUri);

}

}

private final class SettingsObserver extends ContentObserver {

public SettingsObserver(Handler handler) {

super(handler);



}

@TargetApi(19)

@Override

public void onChange(boolean selfChange, Uri uri) {

super.onChange(selfChange, uri);

NfcAdapter adapter = NfcAdapter.getDefaultAdapter

(MyOffHostApduService.this);

CardEmulation ce = CardEmulation.getInstance(adapter);

if (ce.isDefaultServiceForCategory(new ComponentName

(MyOffHostApduService.this,

MyOffHostApduService.class.getCanonicalName()),

"payment")) {

// This service becomes the new default payment.

// Implement the required SP-specific code to enable

// the Cardlet in the UICC, such as displaying a UI

// to enter the PIN code.

} else {

// This service is not the default payment anymore, as

// the user has selected another app in "Tap & pay".

// Implement the required SP-specific code to

// deactivate the Cardlet in the UICC (if currently

// enabled) to maintain the consistency between the

// state of the UICC and the new value in the

// "Tap & pay" settings.

// No UI shall be displayed here in that case, since

// the newly selected application could already display

// its own UI. Otherwise it would be very confusing for

// the user to have two applications being launched.

}

}

}

}

More detailed source code examples are published and publicly available at the following address: https://github.com/AFSCM-Android/Samples.

In order to get the correct service activation status, payment services have to check both the payment Cardlet activation status on the UICC and the current default payment (notion introduced in Android 4.4) from an operating system standpoint. The default payment can be displayed and changed by users directly in the “Tap & pay” menu found in the system settings.

Rule 2.28: For card emulation based payment services, to fully know and/or display its actual service activation status to users, the Mobile Application shall check both: - the activation status of its Cardlet(s) on the UICC, as usual - and also its default payment status as set in the Android operating system (boolean value returned by isDefaultServiceForCategory). A payment service is fully active on Android 4.4 (or above) only when both (1.) one Cardlet is

https://github.com/AFSCM-Android/Samples

http://developer.android.com/reference/android/nfc/cardemulation/CardEmulation.html#isDefaultServiceForCategory%28android.content.ComponentName,%20java.lang.String%29



active on the UICC and (2.) the service declaring the corresponding AID(s) is currently set as the default payment service. If (2.) above was not checked properly, the current default payment set in Android could be another Mobile Application (for instance an HCE one). In that case, displaying that the UICC-based payment is active and fully setup would be false information to the end user.

Rule 2.31: For card emulation based payment services, when the Mobile Application detects that it is not the default payment service following a change in the “Tap & pay” menu, it shall deactivate its Cardlet(s) and no UI shall be displayed in that case. This is covered by the code example provided in Rule 2.23.

3.1.6 Android 5.0 Lollipop specificities

Previously in Android 4.4, only static AID definition was available, requiring the listing of all the supported AIDs one by one in an apduservice.xml file, as described in Rule 2.19.

Android 5.0 is extending the framework introduced in Android 4.4 related to card emulation. In particular, it is offering a second way for Mobile Applications to register the AIDs it wants to support: AIDs can now be registered dynamically to cover the specific needs of each user, on his/her respective device.

With Android 4.4, a Mobile Application had no choice but to register all the AIDs potentially used by all its users, whether they were actually needed for a given user or not. Starting with Android 5.0, it is now possible to only register the needed AID(s) per each user, at runtime.

A typical example would be a banking service, using different AIDs for different payment services:

- in Android 4.4, all these AIDs had to be registered statically.

- in Android 5.0, the Mobile Application can now register only the AID(s) of the payment service(s) actually subscribed by the current user.

The number of AIDs that can be registered simultaneously by multiple Mobile Applications installed on a given device can be sometimes limited (depending on the device model, its configuration, its NFC chipset and/or the size of each AID). For this reason, Mobile Application registering many AIDs shall now declare their AIDs dynamically when running on Android 5.0 (or above) devices using the new registerAidsForService method.

Rule 2.26: When running on Android 5.0 devices, the Mobile Application shall register their AIDs dynamically and only the AIDs actually needed for the current user with the following 2 exceptions: - If the Mobile Application registers very few AIDs (only 1 or 2), - or if the registered AIDs are always mandatory for all users of the service. For these 2 exceptions, the Mobile Application can continue to use static AID definition as described in Rule 2.19.

To design a single Mobile Application compatible with both static AID definition on Android 4.4 and dynamic AID registration on Android 5.0 (or above), the Mobile Application has to:

1. register statically all its AIDs to remain compatible with Android 4.4 devices as described in Rule 2.19 in an apduservice.xml file located in the res/xml (or res/xml-v19) directory.

2.a. prevent the above static registration of AIDs from happening on Android 5.0 (or above) devices, by creating a second apduservice.xml file located this time in the res/xml-v21 directory with no aid-filter element defined at all. This second XML resource file stored in res/xml-v21 will be the one loaded on Android 5.0 (or above), as explained in the documentation about “Providing Alternative Resources”,

2.b. and then register only the required AID(s) dynamically as described in Rule 2.26.

http://developer.android.com/reference/android/nfc/cardemulation/CardEmulation.html#registerAidsForService%28android.content.ComponentName,%20java.lang.String,%20java.util.List%3Cjava.lang.String%3E%29

http://developer.android.com/guide/topics/resources/providing-resources.html#AlternativeResources

http://developer.android.com/guide/topics/resources/providing-resources.html#AlternativeResources



Rule 2.27: To create a Mobile Application compatible with both static AID definition on Android 4.4 and dynamic AID registration on Android 5.0 (or above), both Rules 2.19 and 2.26 shall be followed. The static AID definition shall be prevented on Android 5.0 (or above) devices by creating a second apduservice.xml file located this time in the res/xml-v21 directory with no aid-filter element defined at all.

Finally, here is one last comment about some of the new Android 5.0 API methods introduced in the android.nfc.cardemulation.CardEmulation class. The setPreferredService and unsetPreferredService methods shall not be used by payment applications. The purpose of these 2 methods is to override temporarily the default behavior by setting a preferred card emulation service while a specific application is running in the foreground, while still keeping the default behavior totally unmodified once the given application is closed. While it would be possible to override the default payment (for instance to use a specific merchant payment service in specific shops) the UICC-based application would be unable to keep the default behavior unmodified once closed, as it would have changed the default payment Cardlet activation status on the UICC.

Rule 2.30: For card emulation based payment services, the setPreferredService and unsetPreferredService methods introduced in the android.nfc.cardemulation.CardEmulation class shall not be used by the Mobile Application.

3.1.7 SmartCard API management

3.1.7.1 API Overview

The latest SIM Alliance Open Mobile API specification can be found at: http://www.simalliance.org/en/nfc/nfc_technical/

The API documentation can be found at the following URL: http://seek-for-android.googlecode.com/svn/trunk/doc/index.html.

When using services based on the UICC, the SmartCard API allows the Android Mobile Application to communicate with its counterpart in the UICC. For more information about the architecture of SmartCard API refer to the site: http://code.google.com/p/seek-for-android/wiki/SmartcardAPI.

3.1.7.2 Security Considerations

At installation time, the user is asked whether or not the Mobile Application should receive access to his or her secure element.

Access to the lower layer components such as the secure element specific terminal implementation will be protected with the standard Android mechanisms.

The whole Android security scheme is based on standard UID/GID check; therefore Mobile Applications with root access can overcome the security mechanism. For example, it is possible that a root user replaces APKs or native system services with modified versions that contain tracers or hooks for other applications. This means that the security concept of the SmartCard API can be broken on rooted phones but this is not an issue of the API design but a general issue on Linux based systems where root can do everything.

3.1.7.3 SmartCard API System Security

The security considerations for the SmartCard API can be found at: http://code.google.com/p/seek-for-android/wiki/SecurityConcept

The SmartCard API system security discussion explains the mechanism needed so client applications cannot overcome the SmartCard API interface by using the lower level components directly.

In order to protect the low level components, the SmartCard API remote process is installed and registered with a unique UID/GID: smartcard

http://developer.android.com/reference/android/nfc/cardemulation/CardEmulation.html

http://developer.android.com/reference/android/nfc/cardemulation/CardEmulation.html#setPreferredService(android.app.Activity,%20android.content.ComponentName)

http://developer.android.com/reference/android/nfc/cardemulation/CardEmulation.html#unsetPreferredService(android.app.Activity)

http://developer.android.com/reference/android/nfc/cardemulation/CardEmulation.html#setPreferredService(android.app.Activity,%20android.content.ComponentName)

http://developer.android.com/reference/android/nfc/cardemulation/CardEmulation.html#unsetPreferredService(android.app.Activity)

http://developer.android.com/reference/android/nfc/cardemulation/CardEmulation.html

http://www.simalliance.org/en/nfc/nfc_technical/

http://seek-for-android.googlecode.com/svn/trunk/doc/index.html

http://code.google.com/p/seek-for-android/wiki/SmartcardAPI

http://code.google.com/p/seek-for-android/wiki/SecurityConcept



All low level components and methods check for the caller UID and - if not smartcard - throw an exception.

3.1.7.4 Access Control

To access the Smart Card through the APIs, the Mobile Application file (APK) has to be signed. Current devices implement GlobalPlatform compliant access control, which mandates that the Mobile Application signature is checked before access is granted to the UICC.

The Mobile Application must follow the following rules:

Rule 2.8: Method basicChannel shall not be used.

Rule 2.9: For Mobile Application using the Open Mobile API, the connection string of the openLogicalChannel function shall be hard-coded.

Rule 2.10: For Mobile Application using the Open Mobile API, the Mobile Application shall only access its own Cardlets.

Rule 2.29: For Mobile Application using the Open Mobile API, and for backward compatibility reasons, the openLogicalChannel method to use shall be the one with exactly one parameter, whose full signature is openLogicalChannel(byte[] aid). More recent versions of the Open Mobile API specification have introduced a second openLogicalChannel method with two parameters, whose full signature is openLogicalChannel(byte[] aid, Byte P2), and this new method shall not be used.

3.1.7.5 Cardlet Contactless Self-Activation

The Cardlet is responsible to maintain its Contactless Activation state. Under certain circumstances, the Contactless Activation may be lost and it is necessary to permit the Cardlet to restore it.

The Cardlet Contactless Activation may be triggered by sending an APDU OTA or via the Mobile Application to the Cardlet.

Cf. [R3] Cardlet Development Guidelines for more details.

3.1.8 Peer-to-Peer Data Exchange rules

The rules in this paragraph are conditional. They become mandatory only when the Mobile Application implements the peer-to-peer feature.

Android Beam allows simple peer-to-peer data exchange between two Android-powered devices. The Mobile Application that wants to beam data to another device must be in the foreground and the device receiving the data must not be locked. When the beaming device comes in close enough contact with a receiving device, the beaming device displays the "Touch to Beam" UI. The user can then choose whether or not to beam the message to the receiving device.

To use Android Beam, the following general guidelines must be met:

Rule 2.11: The activity that is beaming the data shall be in the foreground. Both devices shall have their screens unlocked.

Rule 2.12: The Mobile Application shall encapsulate the data it is beaming in an NdefMessage object.

Rule 2.13: The NFC device that is receiving the beamed data shall support the com.android.npp NDEF push protocol or NFC Forum's SNEP (Simple NDEF Exchange Protocol). com.android.npp and SNEP are both required on API Level 15 (Android 4.0.3) and later.

If the activity enables Android Beam and is in the foreground, the standard intent dispatch system is disabled. However, if the activity also enables foreground dispatching, then it can still scan tags that match the intent filters set in the foreground dispatching.

More details about Peer-to-Peer are available at: http://developer.android.com/guide/topics/nfc/nfc.html#p2p

http://developer.android.com/guide/topics/nfc/nfc.html#p2p



3.2 Mobile Application Launch

3.2.1 Via MNO Mobile Application

The Service Provider Mobile Application can be launched from the MNO Mobile Application.

MNO Mobile Application will produce a call to startActivity (Intent intent) method where the intent will be created using MNO Mobile Application context and Service Provider defined activity name in the Service Provider manifest file.

3.2.2 Via the Card Event (HCI) mechanism

The card event mechanism enables Mobile Applications to set themselves up to be launched automatically, without user initiation. This kind of notifications is emitted by Cardlets within the UICC (e.g. at the end of the NFC transactions.

There are currently several implementations in the market, which imposes to support two types of events: the legacy style (android.nfc name space) and the new GSMA standard style (com.gsma.services.nfc name space). Therefore in the rules below, and in the source code, two permissions are needed and two intent filters are required for the Mobile Application to correctly work with all devices on the market.

Rule 2.14: When using Card Event mechanism in order to properly handle NFC events, the following items shall be declared in the AndroidManifest.xml file:

1. The NFC <uses-permission> element to use the NFC Event:


<uses-permission android:name="android.permission.NFC_TRANSACTION"/>

<uses-permission

android:name="com.gsma.services.nfc.permission.TRANSACTION_EVENT"/>

2. The NFC intent filter to tell the Android system the Activity can handle NFC Event. Specify one or more of these intents filters in the activity:

<activity

android:name=".EventReceiver"

android:label="@string/activity_name"

android:launchMode="singleTask"

android:screenOrientation="portrait">

<intent-filter>

<action android:name="android.nfc.action.TRANSACTION_DETECTED"></action>

<category android:name="android.intent.category.DEFAULT"></category>

<data

android:scheme="nfc"

android:host="secure"

android:path="/0102030405060708090000"/> 

</intent-filter>

<intent-filter>

<action android:name="com.gsma.services.nfc.action.TRANSACTION_EVENT">

</action>

<category android:name="android.intent.category.DEFAULT">

</category>

<data

android:host="secure"

android:pathPattern="/SIM.*/0102030405060708090000"

android:scheme="nfc"/>

</intent-filter>

</activity>



Notes:

The hexadecimal letters [a-f] shall be lower-cases. Thus a correct AID will be a00101ae024678 while 01B101AE024678 will not work.

If two Mobile Applications register the same AID, one with upper-cases and the other with lower-cases, only the Mobile Application with a lower-cases AID will be launched upon the HCI event

If two Mobile Applications correctly register the same AID, with lower-cases, the only Mobile Application launched will be the one that has been installed first. No error message will be shown to the user upon installation of the second Mobile Application.

3. The Mobile Application has to be launched in single task mode to avoid to start a new activity after a NFC transaction if it has been already launched:

<activity android:name=".EventReceiver" android:label="@string/app_name"

android:launchMode="singleTask" android:screenOrientation="portrait">

Moreover the method onNewIntent(Intent intent) has to be overridden to allow the retrieval of new intents after the NFC Transaction if the Mobile Application has been already launched. The TAP-PIN-TAP scenario is an example of use case.

4. The uses-feature element so that the Mobile Application can show up in the Android Play Store for devices that have NFC hardware:

<uses-feature android:name="android.hardware.nfc" android:required="true" />

Rule 2.24: When registering AIDs for Card Event mechanism, using intent filters, whether statically in manifest or dynamically, the Mobile Application shall not register the PPSE AID.

3.2.3 Via NFC tags / external RTD

The Service Provider Mobile Application can be launched by reading a NFC tag with an external RTD content (The External Type Name is meant for organizations that wish to self-allocate a name space to be used for their own purposes). It look like this: “urn:nfc:ext:example.com:externalType”. The Mobile Application will be launched once the tag has been read by the device.

Rule 2.15: When using this mechanism in order to properly handle NFC external RTD tags, the following items shall be declared in the AndroidManifest.xml file:

1. The NFC <uses-permission> element to use the NFC Event:


2. The NFC intent filter to tell the Android system the Activity can handle NFC Event. Specify one or more of these intents filters in the activity:

<intent-filter>

<action android:name="android.nfc.action.NDEF_DISCOVERED" />

<category android:name="android.intent.category.DEFAULT" />

<data android:scheme="vnd.android.nfc"

android:host="ext"

android:pathPrefix="/example.com:externalType"/>

</intent-filter>

Notes:

The developer SHOULD use TNF_EXTERNAL_TYPE for more generic NFC tag deployments to better support both Android-powered and non-Android-powered devices.

If several Mobile Applications are registered to be launched on the same NDEF external RTD content, the system activity “TechListChooserActivity (inherited from ResolverActivity)” appears to allow the user to choose the Mobile Application to be launched. Thus, the Foreground Dispatch System must be used if the Mobile Application needs to claim the priority over other activities that handle the same intent. BUT if there is more than one Mobile Application using this Foreground Dispatch for the same external RTD content, Android will launch the “TechListChooserActivity”. For more information, see reference:




http://developer.android.com/guide/topics/nfc/advanced-nfc.html#foreground-dispatch

3.3 Security Requirements

3.3.1 Specific security features

Android has its own security and permission mechanism. See: http://developer.android.com/guide/topics/security/security.html

Rule 2.16: Regarding the mandatory Android and Open Mobile APIs, the following permissions shall be requested by SP Mobile Applications: Permissions needed to use NFC capabilities (tag read, peer-to-peer): - android.permission.NFC Permissions needed to launch Mobile Application through card emulation (NFC Push): - android.permission.NFC_TRANSACTION (for legacy support) - com.gsma.services.nfc.permission.TRANSACTION_EVENT (using new GSMA standard) Permissions needed to access Smart Card through Open Mobile API: - android.permission.SMARTCARD (for Seek-for-Android 2.2.1) - org.simalliance.openmobileapi.SMARTCARD (for Seek-for-Android 2.2.2 and later)

Rule 2.17: Because some handset already on the market can implement either seek-for-android 2.2.1, 2.2.2, 2.4.0, 3.0.0 or later and to ensure a retro compatibility, both android.permission.SMARTCARD and org.simalliance.openmobileapi.SMARTCARD permissions shall be requested.

Rule 2.18: In order to make the Mobile Application installable and visible on the Play Store only to handsets supporting the Open Mobile APIs, the Android Manifest.xml should contain the following line: <uses-library android:name="org.simalliance.openmobileapi" android:required="true" />. The uses-library tag must be set in the <application> tag and only in this tag.

If the Mobile Application supports other use cases than NFC card emulation, it is possible to request the permission to use android:required="false". In this case, the Mobile Application shall gracefully handle devices which do not support this API (by catching exceptions and error codes adequately).

More details can be found at: http://code.google.com/p/seek-for-android/wiki/UsingSmartCardAPI

Whatever the security level reached by the Mobile Application, Service Providers are strongly encouraged to constantly inform the end-user of the nature of the operations being processed.

3.3.2 Open Mobile API security features

The SmartCard API uses the Android permission scheme to protect access to secure elements. Therefore it defines permissions (android.permission.SMARTCARD or org.simalliance.openmobileapi.SMARTCARD) that a client Mobile Application must request in its Manifest in order to obtain access to the API.

Additional security features exist specifically for the Open Mobile API. An access control model is designed to achieve the following security objectives:

Protect UICC from malicious Mobile Applications,

Support UICC to specify a fine-grained access control policy within the limitations of the platform,

Allow a Mobile Application to select an UICC object (for example, a Cardlet) for temporary exclusive usage,

Safeguard PINs from improper usage by the Mobile Application.




http://developer.android.com/guide/topics/security/security.html

http://code.google.com/p/seek-for-android/wiki/UsingSmartCardAPI



4 MNO MOBILE APPLICATION INTERCONNECTION

4.1 MNO and Service Provider Mobile Applications interconnection

4.1.1 Goal

As announced in the introduction chapter, the present document should also list the programming requirements allowing service providers to develop Mobile Applications maximizing application portability across MNO environments.

4.1.2 Metadata definition

The MNO Mobile Application will collect the Service Provider Mobile Application’s information from its AndroidManifest.xml file.

Rule 3.1: The following metadata shall be declared in the AndroidManifest.xml file to ensure MNO Mobile Application interconnection:

android:label: ASCII. This is the name the MNO Mobile Application will display to users in the MNO Mobile Application main screen.

android:versionName: ASCII with the following format: x.x.x (x being an integer such that 0<=x<=99);

android:icon: PNG (transparent) file format.

See http://developer.android.com/design/style/iconography.html for more information.

NFC-App-Name: ASCII / Max 10 characters. [A-Za-z0-9] use of the dash character is allowed;

NFC-App-Vendor: ASCII / Max 10 characters. [A-Za-z0-9];

NFC-Service-Nb: integer; Represents the number of services

For each service x (where x is an integer and 0 < x <= NFC-Service-Nb), the following metadata must be included

NFC-Service-Label-x: ASCII / Max 10 characters. [A-Za-z0-9;dash;dot;space]; This is the name of the service, which the MNO Mobile Application will display to users in the MNO Mobile Application main screen

NFC-Service-AID-x: concatenation of the “aid:” string and an hexadecimal string representing the long AIDs of the Cardlets that the APK is using. x is the number of the Cardlet (e.g. 1, 2, …); the length has be 4+10 up to 4+32: e.g. aid:a001020304050607

NFC-Service-Type-x: 1 byte.

0x00: Other

0x01: Loyalty

0x02: Payment

0x03: Transport

0x04->0xFF: TBD

Rule 3.2: MNO Mobile Application interconnection metadata shall be contained in the file that serves as the main entry into the Service Provider Mobile Application (android.intent.action.MAIN).

Rule 3.3: NFC-App-Name and NFC-app-Vendor shall be constant: no dymanic value such as “@string/app_name”.

http://developer.android.com/design/style/iconography.html



4.1.3 Code samples

- Manifest tag attribute: android:versionName <manifest xmlns:android=http://schemas.android.com/apk/res/android

android:versionCode="X"

android:versionName="x.x.x">

</manifest>

- Application tag attibutes: android:icon and android:label and Application tag meta data. <application android:icon="@drawable/icon"

android:label="@string/app_name">

<meta-data android:name="NFC-App-Name" android:value="abcd"></meta-data>

<meta-data android:name="NFC-App-Vendor" android:value="efgh"></meta-

data>

<meta-data android:name="NFC-Service-Nb" android:value="1"></meta-data>

<meta-data android:name="NFC-Service-Label-1"

android:value="ijkl"></meta-data>

<meta-data android:name="NFC-Service-AID-1"

android:value="aid:0102030405060708090000"></meta-data>

<meta-data android:name="NFC-Service-Type-1"

android:value="mnop"></meta-data>

</application>

http://schemas.android.com/apk/res/android



5 APPENDIX: SYNTHESIS OF RULES

The following table lists all the rules defined in the present guide and indicates for each rule if it is a requirement (mandatory) or a recommendation (recommended), and if it is new, updated (or simply reworded), or if it has been suppressed.

Rule ID and description

Man

dat

ory

Re

com

me

nd

ed

Ch

ange

d?

(*)

Rule 1.1: System properties accessed within method System.getProperty shall be hard-coded. X Word.

Rule 1.2: The list of all system properties accessed shall be provided. (See System.getProperties at http://developer.android.com/reference/java/lang/System.html#getProperties%28%29).

X Word.

Rule 1.3: The list of all external APIs imported by the Mobile Application shall be provided (including list of proprietary APIs and device-specific).

X Word.

Rule 1.4: The list of all external APIs packaged with the Mobile Application’s binary file shall be provided.

X Word.

Rule 1.5: The list of all personal data accessed by the Mobile Application shall be provided. X Word.

Rule 1.6: The type (or category) of each personal data accessed by the Mobile Application shall be provided.

X Word.

Rule 1.7: The list of all files and folders accessed by the Mobile Application shall be provided. X Word.

Rule 1.8: The type of each file accessed by the Mobile Application shall be provided. X Word.

Rule 1.9: A description of usage of read/write accesses on existing personal data elements shall be provided.

X Word.

Rule 1.10: A description of creation/deletion of personal data elements shall be provided. X Word.

Rule 1.11: A description of copying, storing and transferring personal data elements and their destination location shall be provided.

X Word.

Rule 1.12: Finalizers should not be used.

Rule 1.13: Imports shall be fully imported. The ordering of import statements is: 1. Android imports 2. Imports from third parties (com, junit, net, org) 3. java and javax

X Word.

Rule 1.14: Native interface shall not be used (use of NDK is forbidden). X Word.

Rule 1.15: Access qualifier should be used. Word.

Rule 1.16: Usage of constant and static attributes is encouraged. X Suppr.

Rule 1.17: Exceptions shall be properly caught and handled. X Word.

Rule 1.18: Exceptions shall not be caught and ignored without explanation. X Word.

Rule 1.19: The generic java.lang.Exception shall not be the first exception caught. X

Rule 1.20: Clear function separation is encouraged. The most important feature is function separation. By clearly separating the different functions of an application, a developer can make the application easier to implement and maintain.

Suppr.




Man

dat

ory

Re

com

me

nd

ed

Ch

ange

d?

(*)

Rule 1.21: Long class and methods should be avoided, and the object oriented programming philosophy should be respected. To the extent that it is feasible, methods should be kept small and focused. It is, however, recognized that long methods are sometimes appropriate, so no hard limit is placed on method length. If a method exceeds 40 lines or so, think about whether it can be broken up without harming the structure of the program.

Word.

Rule 1.22: Recursion shall not be used. X Word.

Rule 1.23: All switch statements shall include a default rule. X Word.

Rule 1.24: Logging shall be deactivated and debugging options shall be disabled in the released Mobile Application.

X Upd.

Rule 1.25: The Mobile Application developer must take care to the encoding format which was used in the Cardlet and build String objects with the related format.

X Suppr.

Rule 1.26: For Mobile Application deployed in MNO signing mode, since the package identifier must be unique, the Service Provider shall publish as many variants of Mobile Applications as there are MNO supported.

X Upd.

Rule 1.27: For Mobile Application deployed in MNO signing mode, the Mobile Application name should include the MNO name in order to guide the end user the correct Mobile Application.

Word.

Rule 1.1: When publishing an update to its Mobile Application, the SP shall increment the android:versionCode property.

X Upd.

Rule 1.29: The Mobile Application shall only use URLs in which the protocol and destination host are determined.

X Word.

Rule 1.30: URLs shall not be dynamically built (the Mobile Application shall use fixed host strings).

X Word.

Rule 1.31: The Mobile Application shall only use HTTP and HTTPS network connections. In particular, the following low-level protocols are prohibited: datagram, socket, ssl and tcpobex.

X Word.

Rule 1.32: The Mobile Application shall not open connections to numerical IP addresses. This rule simply consists in forbidding the usage of numerical IP addresses to meet both portability and security requirements.

X Word.

Rule 1.33: The Mobile Application shall not open connections to local host. As previously mentioned, Mobile Applications are not allowed to share data and services with other applications. Opening a connection to localhost or to 127.0.0.1 is therefore strictly prohibited since it can be used to get out of the application’s sandbox, by performing direct exchanges with native code on the platform.

X Word.

Rule 1.34: File downloading is forbidden, except auto-update use case The use of requests should be limited to Web content browsing. Applications must therefore not use HTTP requests for downloading files, except for the specific purpose of initiating the update of the application. This means that download requests should be limited to URLs pointing to the newest version of this application and this must be done through the package manager of through the Google Play.

X Suppr.

Rule 1.35: The Mobile Application shall only use constant or determined phone numbers. This is particularly important to detect costly calls to premium or international numbers.

X Word.

Rule 1.36: The Mobile Application shall not access any non-public resources of other applications.

X Word.




Man

dat

ory

Re

com

me

nd

ed

Ch

ange

d?

(*)

Rule 1.37: The Mobile Application shall neither access the user’s MSISDN, nor the IMSI, nor the IMEI.

X Word.

Rule 1.38: Explicit usage of garbage collection is strongly discouraged. X Suppr.

Rule 1.39: The Mobile Application shall not alter user assets without end user approval (e.g. the Mobile Application shall not add new contacts or calendar events without the end user approval).

X Upd.

Rule 1.40: The Mobile Application shall verify the consistency of its database. This rule simply recommends Mobile Applications to perform format verification on the content of the database while inserting or extracting data. This may be useful to detect a record corruption.

X Upd.

Rule 1.41: The application should perform verification to preserve system integrity. The application should make significant effort to preserve the integrity of the file system: private user or system folders shall never be accessed or altered. The application must implement safety verifications that restrict destination folders and that ensure only well-identified files are modified, and always after appropriate end-user confirmation for files that were not initially created by the application.

Suppr.

Rule 1.42: The Mobile Application shall preserve RFID tags integrity. The Mobile Application shall make significant effort to preserve the integrity of the RFID tags it writes (e.g., when writing NDEF tags).

X Upd.

Rule 1.43: The Mobile Application shall verify the consistency of its files. This rule simply recommends Mobile Applications to perform format verification on the content of their own files while inserting or extracting data. This may be useful to detect a file’s corruption.

X Upd.

Rule 1.44: The Mobile Application shall not define default passwords for accessing its services. Most end-users never change the password attributed by the service. Thus, defining default password exposes users to identity theft attacks.

X Word.

Rule 1.45: Mobile Application’s secrets shall not be hard coded plaintext in the code. On some devices and some provisioning servers, the APK file is not protected against disclosure. Thus, an attacker could disassemble the Mobile Application’s code and retrieve any secret value it contains.

X Word.

Rule 1.46: Secrets shall not be stored in plaintext format in the local storage. Developers should particularly consider the issue about persistent storage, as files and (on some device) record stores are exposed to data disclosure. As a consequence, the Mobile Application must implement encryption features to protect these secrets.

X Word.

Rule 1.47: Secrets shall not be decrypted for comparison. When possible, the Mobile Application should prefer to perform the verification of secrets on encrypted values. This will prevent the Mobile Application from involuntary storing the plaintext secret value.

X Word.

Rule 1.48: The Mobile Application shall not send Operator and third party data. Usage of Operator data should be restricted to local computations.

X Word.

Rule 1.49: The Mobile Application shall inform the end user of the usage and storage of end user identification data, end user authentication data, device localization data and device network identification information when these data are sent to a remote server.

X Upd.




Man

dat

ory

Re

com

me

nd

ed

Ch

ange

d?

(*)

Rule 1.50: The application does not send identification data without end user approval. It seems quite natural to forbid transmission of device network identification information as it is also strictly forbidden to manipulate them.

X Suppr.

Rule 1.51: The application does not send device configuration data without end user approval. The properties are restricted to local computations, as they could be used for illegal statistics or commercial purposes. They should therefore not be transmitted to any remote entity.

X Suppr.

Rule 1.52: The application ensures personal data cannot be exploited remotely without end user approval. The exploitation of personal data is restricted to local computations and exchanging them is strongly discouraged. When some personal data are exchanged for backup purposes, the application must ensure these data cannot be interpreted remotely, by implementing a dedicated cryptographic mechanism. Data are transmitted enciphered with a key solely known by the end-user or the local agent.

X Suppr.

Rule 1.53: The Mobile Application shall implement mutual authentication mechanisms when sending end user personal data or mobile network operator data.

X Upd.

Rule 1.54: The design of the Mobile Application should not permit replay attacks. This is the only server-oriented security requirement mentioned in this document as it has some impact on the implementation of the local agent. In particular requests to remote servers shall be protected against replay attacks, especially authentication requests, as it should not be possible for an attacker to illegally authenticate on servers.

Upd.

Rule 1.55: The Mobile Application shall use encrypted communications when sending end user personal data or mobile network operator data.

X Upd.

Rule 1.56: The Mobile Application shall be able to handle the cases when the Cardlet is not present on the UICC.

X Upd.

Rule 1.57: The Mobile Application shall not send any executable program to remote entities. A Mobile Application must not be a vector to propagate malware programs among the network. Mobile Applications that send some files are intended to verify these files are not executable among the following non-exhaustive list of extensions: .exe, .cab, .msi, .sis, .jar, .bat, .sh, .pif.

X Word.

Rule 1.58: The Mobile Application shall not send binary SMS/MMS messages containing executable code. This rule is an extension of the previous requirement, to precise that is also applies to SMS or MMS binary messages: executable code must be prohibited in the body of these messages.

X Upd.

Rule 1.59: The Mobile Application shall not intensively use network resources. In particular, the Mobile Application shall not massively send emails or any kind of data because: - It implies a cost to the end-user; - It could have a significant impact on the bandwidth; - It could be associated to spam operations.

X Word.




Man

dat

ory

Re

com

me

nd

ed

Ch

ange

d?

(*)

Rule 2.1: In the Manifest file and in the SDK project properties, minimum API Level shall be set to 9 or above, with a recommended value of 15 or above; and target API Level shall be set to 21 or above (in order to use both the Android 4.4 KitKat and Android 5.0 Lollipop APIs related to card emulation). Therefore, when accessing a device's NFC hardware, the following items shall be declared in the AndroidManifest.xml file: 1. The NFC <uses-permission> element to access the NFC hardware: […] 2. The minimum SDK version that the Mobile Application can support. The minimum SDK version shall be ≥ 9, but it is recommended to use minimum SDK version ≥ 15 which includes comprehensive reader/writer support. And the Target SDK version that is used to define the API set against which the Mobile Application is built. Since API Level 21 defines new values that are important in the use of card emulation, target SDK version ≥ 21 shall be used. […] 3. The uses-feature element so that the Mobile Application can show up in the Android Play Store for devices that have NFC hardware: […]

X Upd.

Rule 2.2: To properly handle NFC intents, the following item shall be declared in the AndroidManifest.xml file: The NFC intent filter to tell the Android system the Activity can handle NFC data (specify one or more of these three intents filters in the activity). […] The three intent filters are prioritized and behave in specific ways. Declare only the ones that the Activity needs to handle.

X Upd.

Rule 2.3: The developer shall develop the Activity to only handle the NFC tags that the Activity cares about to prevent the Activity Chooser from appearing.

X Word.

Rule 2.4: The developer shall specify <data> elements in the AndroidManifest.xml along with this intent to correctly handle NFC tags that start this intent. For instance, to handle a NDEF_DISCOVERED intent that contains plain text, specify the following filter in your AndroidManifest.xml file:[…]

X Word.

Rule 2.5: If an Activity declares the android.nfc.action.TECH_DISCOVERED intent in your AndroidManifest.xml file, the developer should create an XML resource file that specifies the technologies that the Activity supports within a tech-list set. The Activity is considered a match if a tech-list set is a subset of the technologies that are supported by the tag, which the developer can obtain by calling getTechList().

Word.

Rule 2.6: When using the foreground dispatch system, the developer should define the MIME that will be handled. Only the ones needed have to be specified.

Word.

Rule 2.7: [NFC Push - Card Emulation] If dynamic registration is performed, the registration string has to be hard-coded. Else it has to be in the manifest.

X Suppr.

Rule 2.8: Method basicChannel shall not be used. X Word.

Rule 2.9: For Mobile Application using the Open Mobile API, the connection string of the openLogicalChannel function shall be hard-coded.

X Word.

Rule 2.10: For Mobile Application using the Open Mobile API, the Mobile Application shall only access its own Cardlets.

X Word.




Man

dat

ory

Re

com

me

nd

ed

Ch

ange

d?

(*)

Rule 2.11: The activity that is beaming the data shall be in the foreground. Both devices shall have their screens unlocked.

X Word.

Rule 2.12: The Mobile Application shall encapsulate the data it is beaming in an NdefMessage object.

X Word.

Rule 2.13: The NFC device that is receiving the beamed data shall support the com.android.npp NDEF push protocol or NFC Forum's SNEP (Simple NDEF Exchange Protocol). com.android.npp and SNEP are both required on API Level 15 (Android 4.0.3) and later.

X Word.

Rule 2.14: When using Card Event mechanism in order to properly handle NFC events, the following items shall be declared in the AndroidManifest.xml file: 1.The NFC <uses-permission> element to use the NFC Event: […] 2.The NFC intent filter to tell the Android system the Activity can handle NFC Event. Specify one or more of these intents filters in the activity: […] 3.The Mobile Application has to be launched in single task mode to avoid to start a new activity after a NFC transaction if it has been already launched: […] Moreover the method onNewIntent(Intent intent) has to be overridden to allow the retrieval of new intents after the NFC Transaction if the Mobile Application has been already launched. The TAP-PIN-TAP scenario is an example of use case. 4.The uses-feature element so that the Mobile Application can show up in the Android Play Store for devices that have NFC hardware: […]

X Word.

Rule 2.15: When using this mechanism in order to properly handle NFC external RTD tags, the following items shall be declared in the AndroidManifest.xml file: 1.The NFC <uses-permission> element to use the NFC Event: […] 2.The NFC intent filter to tell the Android system the Activity can handle NFC Event. Specify one or more of these intents filters in the activity: […]

X Word.

Rule 2.16: Regarding the mandatory Android and Open Mobile APIs, the following permissions shall be requested by SP Mobile Applications: Permissions needed to use NFC capabilities (tag read, peer-to-peer): - android.permission.NFC Permissions needed to launch Mobile Application through card emulation (NFC Push): - android.permission.NFC_TRANSACTION (for legacy support) - com.gsma.services.nfc.permission.TRANSACTION_EVENT (using new GSMA standard) Permissions needed to access Smart Card through Open Mobile API: - android.permission.SMARTCARD (for Seek-for-Android 2.2.1) - org.simalliance.openmobileapi.SMARTCARD (for Seek-for-Android 2.2.2 and later)

X Word.

Rule 2.17: Because some handset already on the market can implement either seek-for-android 2.2.1, 2.2.2, 2.4.0, 3.0.0 or later and to ensure a retro compatibility, both android.permission.SMARTCARD and org.simalliance.openmobileapi.SMARTCARD permissions shall be requested.

X Upd.




Man

dat

ory

Re

com

me

nd

ed

Ch

ange

d?

(*)

Rule 2.18: In order to make the Mobile Application installable and visible on the Play Store only to handsets supporting the Open Mobile APIs, the Android Manifest.xml should contain the following line: <uses-library android:name="org.simalliance.openmobileapi" android:required="true" />. The uses-library tag must be set in the <application> tag and only in this tag.

Word.

Rule 2.19: For card emulation based services, in order to be compliant with Android 4.4, the following shall be added to the Mobile Application : 1.The AndroidManifest .xml file’s <application> element shall contain an off-host APDU service, as follows: […] 2.An apduservice.xml file containing the AID list shall be created under res/xml folder (or res/xml-v19). This list shall include all AIDs which are used by the Mobile Application over the contactless interface: […]

X Upd.

Rule 2.20: For card emulation based payment services, the android:category shall be set to “payment” in the aid-group XML definition.

X Word.

Rule 2.21: For card emulation based payment services, the list of AIDs shall include the PPSE’s AID (325041592E5359532E4444463031).

X Word.

Rule 2.22: For card emulation based payment services, a drawable (bitmap) logo shall be defined in the Mobile Application that represents the payment service, for all dpi configurations.

X Word.

Rule 2.23: For card emulation based payment services, as per the Manifest file definition above, a new Service class extending OffHostApduService shall be implemented as described in the following minimal example (this class will handle the change of default payment, when triggered by the end user directly from the new “Tap & pay” settings menu introduced in Android 4.4) : […]

X Upd.

Rule 2.24: When registering AIDs for Card Event mechanism, using intent filters, whether statically in manifest or dynamically, the Mobile Application shall not register the PPSE AID.

X Word.

Rule 2.25: The OffHostApduService class name shall be defined within the Mobile Application’s primary package name.

X Word.

Rule 2.26: When running on Android 5.0 devices, the Mobile Application shall register their AIDs dynamically and only the AIDs actually needed for the current user with the following 2 exceptions: - If the Mobile Application registers very few AIDs (only 1 or 2), - or if the registered AIDs are always mandatory for all users of the service. For these 2 exceptions, the Mobile Application can continue to use static AID definition as described in Rule 2.19.

X New

Rule 2.27: To create a Mobile Application compatible with both static AID definition on Android 4.4 and dynamic AID registration on Android 5.0 (or above), both Rules 2.19 and 2.26 shall be followed. The static AID definition shall be prevented on Android 5.0 (or above) devices by creating a second apduservice.xml file located this time in the res/xml-v21 directory with no aid-filter element defined at all.

X New




Man

dat

ory

Re

com

me

nd

ed

Ch

ange

d?

(*)

Rule 2.28: For card emulation based payment services, to fully know and/or display its actual service activation status to users, the Mobile Application shall check both: - the activation status of its Cardlet(s) on the UICC, as usual - and also its default payment status as set in the Android operating system (boolean value returned by isDefaultServiceForCategory). A payment service is fully active on Android 4.4 (or above) only when both (1.) one Cardlet is active on the UICC and (2.) the service declaring the corresponding AID(s) is currently set as the default payment service. If (2.) above was not checked properly, the current default payment set in Android could be another Mobile Application (for instance an HCE one). In that case, displaying that the UICC-based payment is active and fully setup would be false information to the end user.

X New

Rule 2.29: For Mobile Application using the Open Mobile API, and for backward compatibility reasons, the openLogicalChannel method to use shall be the one with exactly one parameter, whose full signature is openLogicalChannel(byte[] aid). More recent versions of the Open Mobile API specification have introduced a second openLogicalChannel method with two parameters, whose full signature is openLogicalChannel(byte[] aid, Byte P2), and this new method shall not be used.

X New

Rule 2.30: For card emulation based payment services, the setPreferredService and unsetPreferredService methods introduced in the android.nfc.cardemulation.CardEmulation class shall not be used by the Mobile Application.

X New

Rule 2.31: For card emulation based payment services, when the Mobile Application detects that it is not the default payment service following a change in the “Tap & pay” menu, it shall deactivate its Cardlet(s) and no UI shall be displayed in that case. This is covered by the code example provided in Rule 2.23

X New

Rule 3.1: The following metadata shall be declared in the AndroidManifest.xml file to ensure MNO Mobile Application interconnection: […]

X Upd.

Rule 3.2: MNO Mobile Application interconnection metadata shall be contained in the file that serves as the main entry into the Service Provider Mobile Application (android.intent.action.MAIN).

X Word.

Rule 3.3: NFC-App-Name and NFC-app-Vendor shall be constant: no dymanic value such as “@string/app_name”.

X Word.

(*) In this column, the rules are marked:

New if this rule is New, compared with the previous version of the specification

Upd. if this rule has been Updated from the previous version of the specification

Word. if this rule has been Reworded (with no impact on the rule) from the previous version of the specification

Suppr. if this rule was in the previous version of the specification and has been Suppressed If a rule has been kept as-is from the previous version of the specification, it is not marked

END OF DOCUMENT

Documents

NFC Android Applications Development Guidelines - …info.afscm.org/.../sites/...development-guidelines-v2.0.8-20150130.pdf · take into account the implementation of the binding