NFC Android Applications

Transcription

1 NFC Android Applications Development Guidelines RELEASE Date 30/01/2015 Reference afscm-android-development-guidelines-v doc AFSCM Android development guidelines v2.0.7 ( p1/39 Copyright AFSCM 2014

2 Document management Name Company Authors Christian Bernadine Bouygues Telecom Mathieu Amiel Nicolas Sollier Erwan Louët Jérome Roussel Eric Le Bomin EI Telecom Orange SFR Editor Grégoire Fraisse AFSCM Document history Version Date Modification /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 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 & 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 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 API Overview, and definition of a new Rule 2.29 for backward compatibility in section 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 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 AFSCM Android development guidelines v2.0.8 p2/39

3 Version Date Modification in Part 1 of the guide v2.0.7). o Suppression of section Memory usage and of Rule 1.38 (section in Part 1 of the guide v2.0.7), o Suppression of section Personal data: restricted situations and of Rule 1.52 (section in Part 1 of the guide v2.0.7), o Suppression of Rule 2.7 in section SmartCard API management (from section in Part 2 of the guide v2.0.7), o Suppression on some requirements on the icon sizes in Rule 3.1 (in section 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 E.g.: o Clarifications edited in section 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 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. AFSCM Android development guidelines v2.0.8 p3/39

4 TABLE OF CONTENTS 1 INTRODUCTION Context Copyright license Purpose and content of this document References Abbreviation Definitions GENERAL PURPOSE Development process Specification Dependencies in terms of device properties and features Usage of personal data Testing Coding rules Complement to Java coding conventions Exception handling rules Publishing an Android Mobile Application Preparing to Publish Publishing on Google Play Mobile Application signature Mobile Application update Connectivity General Requirements Network Phone numbers Security Requirements Protection of local assets Protection of private user assets Alteration of assets Confidential assets Protection of assets among network communications Prohibited transmissions Secured transmissions Protection of the Environment HOW TO USE NFC AND SECURE ELEMENT NFC Features NFC management API Levels API reference NDEF tag read/write rules Android 4.4 KitKat specificities Generic rules Payment services specific rules Android 5.0 Lollipop specificities SmartCard API management API Overview AFSCM Android development guidelines v2.0.8 p4/39

5 Security Considerations SmartCard API System Security Access Control Cardlet Contactless Self-Activation Peer-to-Peer Data Exchange rules Mobile Application Launch Via MNO Mobile Application Via the Card Event (HCI) mechanism Via NFC tags / external RTD Security Requirements Specific security features Open Mobile API security features MNO MOBILE APPLICATION INTERCONNECTION MNO and Service Provider Mobile Applications interconnection Goal Metadata definition Code samples APPENDI: SYNTHESIS OF RULES AFSCM Android development guidelines v2.0.8 p5/39

6 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 (Association Française du Sans Contact Mobile ; All rights reserved. Terms and conditions to copy, display and communicate these Specifications are available at 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. AFSCM Android development guidelines v2.0.8 p6/39

7 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, EPLICIT 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, knowhow 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 AFSCM Android development guidelines v2.0.8 p7/39

8 1.4 References AFSCM: The following documents are available for the Service Providers on the AFSCM website ( [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: NFC Forum: GSMA: GSMA NFC Handset Requirements (TS.26) available at: AFSCM Android development guidelines v2.0.8 p8/39

9 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 Cardlet Mobile Application Service Service Provider Validation Entity 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] JavaCard application loaded onto the UICC (also known as UICC application or applet) Application loaded onto the mobile handset, providing a GUI (may be simply called application in the present guide, and also known as MMI) Combination of a Cardlet and a Mobile Application (also known as NFC service or Mobile NFC service) Entity which provides an NFC service Entity in charge of validating that the security level in the applications meets the security requirements (typically, a laboratory) AFSCM Android development guidelines v2.0.8 p9/39

10 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 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 enduser 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 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 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 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. AFSCM Android development guidelines v2.0.8 p10/39

11 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 In France, depending on the type of data accessed, the Service Provider may have to declare this information to the CNIL ( 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 ( 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 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. AFSCM Android development guidelines v2.0.8 p11/39

12 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 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 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 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. AFSCM Android development guidelines v2.0.8 p12/39

13 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 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 Mobile Application update 2.4 Connectivity Rule 1.1: When publishing an update to its Mobile Application, the SP shall increment the android:versioncode property. 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 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. AFSCM Android development guidelines v2.0.8 p13/39

14 Rule 1.30: URLs shall not be dynamically built (the Mobile Application shall use fixed host strings) 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 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 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 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 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 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. AFSCM Android development guidelines v2.0.8 p14/39

15 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) Confidential assets The Mobile Application may be responsible to manage confidential assets. These assets are enduser 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 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 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 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. AFSCM Android development guidelines v2.0.8 p15/39

16 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 s 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. AFSCM Android development guidelines v2.0.8 p16/39

17 3 HOW TO USE NFC AND SECURE ELEMENT 3.1 NFC Features 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 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 ETRA_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" /> AFSCM Android development guidelines v2.0.8 p17/39

18 Where x 9 (x 15 is recommended) and y 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" /> API reference A summary of the classes can be found at: 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 AFSCM Android development guidelines v2.0.8 p18/39

19 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 ML 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 ML 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 AFSCM Android development guidelines v2.0.8 p19/39

20 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: 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 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" </service> android:resource="@xml/apduservice"/> 2. An apduservice.xml file containing the AID list shall be created under res/xml folder (or res/xmlv19). This list shall include all AIDs which are used by the Mobile Application over the contactless interface: <offhost-apdu-service xmlns: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 01B101AE AFSCM Android development guidelines v2.0.8 p20/39

21 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 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 ML definition. Rule 2.21: For card emulation based payment services, the list of AIDs shall include the PPSE s AID ( E E ). 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 ML definition as follows: <offhost-apdu-service xmlns:android=" android:description="@string/servicedesc" android:apduservicebanner="@drawable/servicelogo"> <aid-group android:description="@string/subscription" android:category="payment"> <aid-filter android:name=" e e "/> <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; AFSCM Android development guidelines v2.0.8 p21/39