NFC.19 Value Added Services Applet Design Proposal
GSM Association
Official Document NFC.19 - Value Added Services Applet Design Proposal
Non-confidential
Value Added Services Applet Design Proposal
Version 1.0
10 March 2015
This is a Non-binding Permanent Reference Document of the GSMA
Security Classification: Non-confidential
Access to and distribution of this document is restricted to the persons permitted by the security classification. This document is confidential to the
Association and is subject to copyright protection. This document is to be used only for the purposes for which it has been supplied and information contained in it must not be disclosed or in any other way made available, in whole or in part, to persons other than those permitted under the security classification without the prior written approval of the Association.
Copyright Notice
Copyright © 2015 GSM Association
Disclaimer
The GSM Association (“Association”) makes no representation, warranty or undertaking (express or implied) with respect to and does not accept any responsibility for, and hereby disclaims liability for the accuracy or completeness or timeliness of the information contained in this document.
The information contained in this document may be subject to change without prior notice.
Antitrust Notice
The information contain herein is in full compliance with the GSM Association’s antitrust compliance policy.
V1.0 Page 1 of 66
GSM Association
Official Document NFC.19 - Value Added Services Applet Design Proposal
Table of Contents
VAS Applet – Contactless Reader Communication Use Cases
VAS Applet – VAS Plugin Communication Use Cases
7 Applet Installation and Provisioning
8 Application Programming Interfaces
HCI Transaction Event Generation
Annex A Overall System Architecture
Annex D Overall Installation Process
Annex F Example Applet Structure 1
Installation Parameters for an Instance
V1.0
Non-confidential
Page 2 of 66
GSM Association
Official Document NFC.19 - Value Added Services Applet Design Proposal
Annex G Example Applet Structure 2
VAS Applet Example Data Structure
Annex H Example Applet Structure 3
V1.0
Non-confidential
Page 3 of 66
GSM Association
Official Document NFC.19 - Value Added Services Applet Design Proposal
1 Introduction
Non-confidential
1.1 Overview
GSMA retail mobile specifications (e.g. NFC.15 [2]) have proposed a standard way of
working for operators to work with the retail ecosystem to develop loyalty and couponing propositions. They specify various elements of the overall end-to-end solution, such as roles that ecosystem players need to develop, coupon data flows, as well as the Application
Programming Interfaces (APIs) needed between external parties in the system.
This document takes a closer look at the some of the components present within the handset that are specifically needed for such propositions to work. These components provide the capability for service providers, merchants and third parties working with operators to deploy value added services (VAS) to a secure element, and then transfer data from the secure element to the merchant Point of Sale (POS). The overall system architecture can support multiple transmission technologies between the handset and the
POS. However, the solution presented in this document uses the NFC technology as a standard way of communication between the handset and the POS.
Specifically, this document provides details about the VAS applet, an application that allows for the storage of VAS data on a secure element. The applet receives the data from User
Interface (UI) apps (mobile operator apps, service provider (SP) apps or third-party consumer apps) and transfers only the relevant information to the POS. The applet design
proposed in this document is in line with SIMalliance Open Mobile specifications [6] and
related APIs.
1.2 In Scope
The overall aim of this document is to provide a high-level design of the VAS applet so applet developers have a baseline reference when developing such applets. Within this scope, the use cases for the applet are based on the applet’s interfaces to the contactless
terminal (API 1 as defined in NFC.15 [2]) and the apps (API 2 as defined in the NFC.15 [2]).
Specifying use cases helps in defining technical requirements, the overall design and architecture, data structures, provisioning options, security, and other considerations. Also included in this proposal are example case studies of deployed applet solutions.
The value added services applet is a critical component within the overall retail technology stack, which helps aggregate data from multiple service providers and then transfers relevant data to the merchant’s point-of-sale terminal. The applet could reside on specific hardware, like the secure element, or could also be software driven, e.g. using Host Card
Emulation (HCE) on Android handsets. The solution provided in this document is based on the assumption that the applet resides on a UICC based secure element. Note that this is not mandated for the given architecture to work.
1.3 Out of Scope
The following items are out of the scope of this document:
Multiple VAS applets: NFC.15 [2] presented two options for the installation and
provisioning of applets. These included a single applet option and a multiple applets option (with a Proximity Payment System Environment (PPSE) like applet serving as
V1.0 Page 4 of 66
GSM Association
Official Document NFC.19 - Value Added Services Applet Design Proposal
Non-confidential a directory structure). To avoid fragmentation and to provide consistency at the POS, a single applet structure is proposed. Use cases for a multiple applet option are
Detailed applet – contactless reader API: This document provides overall design and architecture guidance for the applet. It mentions the contactless reader API (see
section 8.4), but does not aim to provide complete details around its command line
structure. However, an example of this API is present in Annex F,
Online or offline POS for validation: Validation of the coupons or offers is out of scope of this document. VAS data, including loyalty and couponing information, is stored and delivered from the VAS applet to the contactless reader. How the merchant uses this data to validate coupons, loyalty and other VAS information, is out of scope for this document.
Detailed low-level specification: This document is intended as a high-level design specification. It is understood that there is a need for a consistent low-level specification agreeable by all, this will be followed up in future updates.
Ownership of common identifiers: There are many identifiers that will be shared between various external organisations as part of the specification (for example,
MerchantID ). The issuing and maintenance of such identifiers is presently out of scope. It is understood that this is critical to avoid fragmentation, and all necessary identifiers may be clarified in future documents.
1.4 Guiding Principles
This document aims to provide technical consistency and avoid fragmentation at a regional
level, and to an extent, on a global level. Taking the main principles of NFC.15 [2] forward,
simplicity of the ecosystem, including time to market, development and maintenance costs are of prime importance. The following guiding principles were considered when developing this proposal:
Minimise impact at the contactless terminal : Development time at the contactless terminal is one of the key issues when deploying value added services at merchant terminals.
Standardise applet design : By providing consistent and generic solutions, mobile operators and other applet developers can ensure conformation to standard POS integration – thus minimising development at the contactless terminal. This “out of the box” approach will help in scaling the solution across multiple small and large merchants conforming to a standard applet design. A standard design not only minimises development, certification and maintenance costs, but it also simplifies the options presented to various service providers who wish to make use of value added services provided by mobile operators and other applet developers.
Minimise provisioning options
: NFC.15 [2] presented three provisioning options.
As part of standardising the applet design, a single option has been selected that caters to all the major business requirements and helps improve consistency in applet design.
V1.0 Page 5 of 66
GSM Association
Official Document NFC.19 - Value Added Services Applet Design Proposal
Non-confidential
1.5 Definitions
Term
Closed loop coupons
Open loop coupons
Description
Proprietary coupons that are issued and redeemed in a closed ecosystem (the offer issuer and the offer awarder have a direct relationship).
Service
Provider app
Coupons issued by one or more offer issuers and redeemable at one or more offer awarders without there being an explicit relationship between them.
A consumer facing mobile application published by service providers such as individual merchants or manufacturers. There may be many such applications installed on a consumer mobile device, each with its own merchant/manufacturer customised experience. All use the mobile operator VAS applet through the VAS
Software Development Kit (SDK) (NFC.15
[2] specified API 3) or VAS API
[2] specified API 2) to convey VAS data to a POS device.
VAS Applet
VAS applet (may also be referred to as cardlet) hosted within a secure element environment and responsible for facilitating communication between UI apps and the
PED (or other NFC readers).
VAS Plugin
Service component hosted on the mobile device and responsible for presenting a simplified, functional, interface between the secure element VAS applet and UI apps that utilise the VAS applet.
VAS SDK
specified
API 3)
A simplified, functional interface presented by the VAS plugin. The API presented allows UI apps to access and manage VAS content hosted by the mobile operator secure element applet.
UI apps
Any consumer facing application residing on the mobile device. This could be provided by the mobile operator, a service provider (e.g. banks, merchants, etc.), or an independent third party. They are generally available to consumers via application stores.
1.6 Abbreviations
Term
AID
APDU
API
EAN
ELF
HCE
HCI
MNO
OTA
POS
PPSE
RAM
RFM
Description
Application Identifier
Application Protocol Data Unit
Application Programming Interface
International Article Number
Executable Load File
Host Card Emulation
Host Controller Interface
Mobile Network Operator
Over The Air
Point of Sale
Proximity Payment System Environment
Remote Application Management
Remote File Management
V1.0 Page 6 of 66
GSM Association
Official Document NFC.19 - Value Added Services Applet Design Proposal
Term
SCP
SD
SDK
SE
SP
SP UI
SS
SW
TSM
UI
USD
VAS
Description
Secure Channel Protocol
Security Domain
Software Development Kit
Secure Element
Service Provider
Service Provider User Interface
Secure Storage
Status Word
Trusted Service Manager
User Interface
Utility Security Domain
Value Added Service
Non-confidential
1.7 References
Ref Doc Number
[1] RFC 2119
[2] NFC.15
[3] NFC.17
[4] ISO/IEC 7816
[5] ISO/IEC 14443
[6] SIM-OMA
[7] GS1-DCM
Title
“Key words for use in RFCs to Indicate Requirement Levels”, S.
Bradner, March 1997 http://www.ietf.org/rfc/rfc2119.txt
GSMA: Mobile Commerce NFC Coupons and Loyalty Acceptance -
Technical Proposal, Version 1.0, 01 July 2014 http://www.gsma.com/digitalcommerce/wpcontent/uploads/2014/07/NFC.15-Version-1.0-Mobile-Commerce-
NFC-Coupons-and-Acceptance-Technical-Proposal.pdf
NFC.17 CR1001 New PRD - Core Wallet API
Confidential document.
“Identification cards -- Integrated circuit cards” http://www.iso.org/ and http://www.iec.ch/
ISO 14443 defines a protocol stack from the radio layer up to a command protocol http://www.iso.org/ and http://www.iec.ch/
SIMAlliance Open Mobile API Specification v2.05 http://www.simalliance.org/en/se/se_technical/open-mobile-apispecification-v205_hrmcp1sq.html
“Digital Coupon Management” GS1, Issue 1.0, Jun-2012 1 http://www.gs1.org/docs/gsmp/b2c/Digital_Coupon_Management_
1
The GS1 digital coupon standard has no direct ISO equivalent. However, a number of ISO standards make explicit normative
coupons) and ASC MH10 Data Identifiers with a direct reference to the GS1 General Specifications. Licenses provided under the GS1 IP Policy (royalty-free or RAND) are only granted to GS1 Working Group participants on a reciprocal basis and GS1 members. The GS1 IP Policy does not provide for any licensing undertaking to third parties who are neither GS1 Working
Group participants on a reciprocal basis nor GS1 members.
V1.0 Page 7 of 66
GSM Association
Official Document NFC.19 - Value Added Services Applet Design Proposal
Ref Doc Number
[8] ISO/IEC 15418
[9] ITU-T E.212
Non-confidential
Title i1.pdf
For the latest GS1 Digital Coupons Standard, please visit http://www.gs1.org/gsmp/kc/b2c
Information technology -- Automatic identification and data capture techniques -- GS1 Application Identifiers and ASC MH10 Data
Identifiers and maintenance http://www.iso.org/ and http://www.iec.ch/
International Telecommunication Union (ITU) standard: Mobile
Network Codes (MNC) for the international identification plan for public networks and subscriptions http://www.itu.int/dms_pub/itu-t/opb/sp/T-SP-E.212B-2013-PDFE. pdf
1.8 Conventions
The key words “must”, “must not”, “required”, “shall”, “shall not”, “should”, “should not”,
“recommended”, “may”, and “optional” in this document are to be interpreted as described in
2 Use Cases
architecture. This section aims to describe the use cases related to one specific component of that architecture, the applet.
The VAS applet’s primary goal is to store VAS data and pass it to the contactless reader when requested. It also communicates with the VAS plugin to receive that data, and with the
MNO/SP TSM infrastructure for overall permissions management.
V1.0 Page 8 of 66
GSM Association
Official Document NFC.19 - Value Added Services Applet Design Proposal uc Applet use cases
GetVASData
Non-confidential
Security of VAS data
Contactless reader communication
Storage of VAS data Read data
Write data
VAS applet
HCI ev ents
VAS plugin communication
MNO / SP TSM communication
Delete records
Read/Write VAS data
Create records
Figure 1 : Applet functional use cases
VAS applet use cases
Description
Contactless reader communication
Communication between the applet and the contactless reader to transfer
VAS data.
GetVASData The contactless reader obtains VAS data for a specified merchant identified by its MerchantID .
Storage of VAS data
Storing VAS data within the records.
Security of VAS data
Read data
Secure any VAS data stored on a secure element based applet so that relevant data can be accessed by the corresponding application.
Read data from a specified record on the applet.
Write data Write data to a specified record on the applet.
Communication with the VAS plugin, primarily to store VAS data and provide Host Controller Interface (HCI) event feedback.
VAS plugin communication
Read/Write VAS data Read or write VAS data into a record on the applet.
HCI events The VAS applet passes all HCI events back to the VAS plugin.
Communication with the TSM Infrastructure for maintenance and the creation/deletion of new records.
MNO / SP TSM communication
Create records Create records on the VAS applet. One record per merchant.
Delete records Delete records on the VAS applet.
V1.0 Page 9 of 66
GSM Association
Official Document NFC.19 - Value Added Services Applet Design Proposal
Table 1 : Applet functional use case descriptions
Non-confidential
2.1 VAS Applet – Contactless Reader Communication Use Cases
The VAS applet communicates with the contactless reader over the NFC channel to pass
VAS data to it. There are two basic use cases:
1. Establish communication: The contactless reader acts as a master and establishes communication with the VAS applet. This may or may not involve authentication.
2. Transfer of VAS data: The VAS applet transfers necessary data to the contactless reader
– this includes coupons, loyalty, basket, or any other data that the applet holds and is relevant for this contactless reader. uc Applet use cases 1
Get Coupon Data Get Loyalty Data Get Basket Data Get Other Data
Get VAS Data
Establish communication
Contactless reader
VAS Applet
Authentication
Put VAS Data
Figure 2 : Applet – Contactless Reader communication use cases
Component
Authentication
Get VAS Data
Description
Source: Contactless reader
Target: VAS Applet
Description: Enables the contactless reader to deliver data to the VAS applet following authentication/security handshake. This is optional.
Source: Contactless reader
Target: VAS Applet
Description: Retrieval of data from the VAS applet. Includes the capability to retrieve coupon data or loyalty data.
V1.0 Page 10 of 66
GSM Association
Official Document NFC.19 - Value Added Services Applet Design Proposal
Non-confidential
Component
Get Coupon Data /
Get Loyalty Data /
Get Basket Data /
Get Other Data
Establish communication
Description
Source: Contactless reader
Target: VAS Applet
Description: Retrieval of coupon/loyalty data/basket data/other data from the VAS applet.
Source: Contactless reader
Target: VAS Applet
Description: Open a communication channel between the contactless reader and the VAS applet.
Table 2 : Applet – Contactless Reader communication use cases
2.2 VAS Applet – VAS Plugin Communication Use Cases
Communication between the VAS applet and the plugin (or apps) is necessary to load, retrieve and delete data from the applet. Most of the communication occurs from the plugin to the applet for data manipulation. There is a certain “HCI Event” use case that acts as a callback mechanism from the VAS applet to the VAS plugin.
V1.0 Page 11 of 66
GSM Association
Official Document NFC.19 - Value Added Services Applet Design Proposal uc Applet use cases 2
Get Coupon Data Get Loyalty Data Get Basket Data
Non-confidential
Get Other Data
Get VAS Data
Establish communication
VAS Manager / Plugin
VAS Applet
Authentication
Listen for HCI ev ents
Put VAS Data
Records management
Applet data management
Figure 3 : VAS Applet – VAS Plugin communication use cases
Component
Get VAS Data
Get Coupon Data /
Get Loyalty Data /
Get Basket Data /
Get Other Data
Establish
Description
Source: VAS Manager/Plugin
Target: VAS Applet
Description: Retrieval of data from the VAS applet. Includes the capability to retrieve coupon data or loyalty data.
Source: VAS Manager/Plugin
Target: VAS Applet
Description: Retrieval of coupon/loyalty data/basket data/other data from the VAS applet.
Source: VAS Manager/Plugin
V1.0 Page 12 of 66
GSM Association
Official Document NFC.19 - Value Added Services Applet Design Proposal
Non-confidential
Component communication
Authentication
Listen for HCI events
Put VAS Data
Records management
Applet data management
Description
Target: VAS Applet
Description: Open a communication channel between the Plugin and the
VAS applet.
Source: VAS Manager/Plugin
Target: VAS Applet
Description: Enables the plugin to deliver data to the VAS applet following authentication/security handshake.
Source: VAS Applet
Target: VAS Manager/Plugin
Description: The applet sends a notification to the plugin for a change of state in a record. The plugin then uses Get VAS Data to query the record.
Source: VAS Manager/Plugin
Target: VAS Applet
Description: The plugin sends data to a record within the applet instance.
Source: VAS Manager/Plugin
Target: VAS Applet
Description: The plugin ensures that VAS data sent by individual UI apps is transferred to the appropriate record in the applet.
Source: VAS Manager/Plugin
Target: VAS Applet
Description: The plugin controls how much data is transferred to the applet and handles requests from UI apps accordingly.
Table 3 : VAS Applet – VAS Plugin/Apps communication use cases
3 Requirements
Based on the above use cases, a set of requirements has been identified that the applet design should satisfy. These requirements are described in the table below:
Req. no.
Requirement Description
REQ 1
REQ 2
REQ 3
Storage −
CustomerID
Storage −
LoyaltyID
Storage −
MerchantID
REQ 4 Storage −
A customer identifier SHOULD be stored on the applet/cardlet. This
MAY be SP (merchant/brand) specific, but can also be shared with the mobile operator.
A loyalty identifier for the customer SHOULD be stored on the applet/cardlet. This MAY be the same as the CustomerID and is an optional item. There MAY be one or more loyalty identifiers per merchant.
A merchant identifier MUST be stored on the applet/cardlet. It is a required field. This is used to establish communication between the
POS and the applet. The POS sends its MerchantID to the applet and the applet responds by returning data relevant to this specific
MerchantID.
Coupon[] SHOULD be stored on the applet/cardlet. The coupon format can be proprietary or it can be a serialized Global Coupon
V1.0 Page 13 of 66
GSM Association
Official Document NFC.19 - Value Added Services Applet Design Proposal
Non-confidential
Req. no.
Requirement Description
REQ 5
Coupon[]
Storage −
OpenField
Number as defined in GS1 DCM [7].
An extra field of data per customer that can store any item up to a certain length. Where the optional open field is used, it SHOULD be stored on the applet/cardlet.
REQ 6
REQ 7
REQ 8
CustomerID
REQ 9
CustomerID
REQ 10
CouponID
REQ 11
REQ 12
REQ 13
Storage −
Basket[]
Storage −
Status
Open loop coupons
Closed loop coupons
Coupon activation
REQ 14
MerchantID
REQ 15
MerchantID
REQ 16 Online POS
REQ 17 POS integration
REQ 18 API 1
REQ 19 API 2
In case optional basket use cases are in effect, Basket[] SHOULD be stored on the applet/cardlet. It consists of the following members:
ProductID (based on the International Article Number (EAN)),
Quantity , Price.
A Status message for each of the storage data items SHOULD be stored on the applet/cardlet. This will correspond to the applet
response codes as defined in ISO 7816 [4].
CustomerID MAY be unique to a specific merchant.
CustomerID MAY be common to a group of merchants.
The CouponID MAY be serialized and fully unique per customer.
The VAS applet SHOULD support open loop coupons − Multiple merchants can redeem a single coupon. In order to support this, a
CouponID can be associated with multiple MerchantID s (so each
CouponID can be associated with any number of MerchantID s, though this SHOULD be capped at a certain maximum number due to
VAS applet memory limitations).
The VAS applet SHOULD support closed loop coupons − Offers and coupons issued and redeemed by the same company. For example, a merchant issues coupons that only they will accept. In this case, a
CouponID is associated with only one MerchantID .
The VAS applet SHOULD support coupon activation − Ability to enforce coupon activation before they can be used. Though defined separately, acquiring a coupon and activating a coupon can occur concurrently. These can easily be governed by providing a status byte with each coupon identifier.
MerchantID MUST be communicated by the POS to the applet so the applet can return useful data.
The VAS applet SHOULD categorise all of the data storage by
MerchantID . This is to minimise data duplication, and also to maintain data abstraction.
A POS MAY or MAY NOT be online (connected to the internet) to approve offers.
The POS SHOULD be integrated with the contactless terminal and
API 1 to communicate effectively with the applet.
The applet SHOULD support API 1 as defined in NFC.15
The applet SHOULD support API 2 as defined in NFC.15
REQ 20 API framework The applet SHOULD conform to the API framework outlined in
V1.0 Page 14 of 66
GSM Association
Official Document NFC.19 - Value Added Services Applet Design Proposal
Non-confidential
Req. no.
Requirement
REQ 21 HCI events
Description
The VAS applet MUST pass all HCI events back to the VAS plugin.
REQ 22
REQ 36
SIM resources
Performance
The VAS applet implementation SHALL minimise impacts on memory, storage and processing requirements.
REQ 23
REQ 24
Security
Security domain instance
The VAS applet MAY provide appropriate security of data to and from the applet.
The VAS applet MUST be instantiated only once and it MUST be instantiated in a security domain (SD).
REQ 25
REQ 26
REQ 27
Applet preloaded on SIM
Applet
ReadWrite
VAS applet
SecureStorage
The VAS applet MAY be pre-loaded on the SIM. It MAY be instantiated at a later time.
The VAS applet MAY allow both read/write modes to write data back to the data fields.
The VAS applet MAY be based on the SIMalliance Secure Storage
(SS) [6] generic applet concept.
REQ 28
Service
Provider
Trusted Service
Manager (SP
TSM)
The SP SHOULD NOT need to link to the MNO TSM.
REQ 29
REQ 30
REQ 31
Cryptography
Cryptography
Multi key management
–
Cryptography –
Multi crypto algorithm
The VAS applet MAY provide a facility for cryptography via simple data transformation. This helps alleviate security concerns in the case of a single shared applet approach. Cryptographic keys can be exchanged over an OTA channel, however, this exchange is out of scope for this document.
If cryptography is being offered, multi key management SHOULD be provided as it is expected that multiple SPs will use and store data on the applet, via the plugin.
In case cryptography is being offered, the VAS applet MAY offer multiple crypto algorithms to SPs, based on certain risk profiles.
REQ 32 NFC standard
The overall system solution SHOULD be based on NFC standard
technologies (ISO 14443 A/B [5]).
REQ 33
REQ 34
REQ 35
Simplify integration of services
Standard solution
Avoid fragmentation
The overall system solution SHOULD simplify the integration of new services between third parties.
The overall system solution SHOULD be based on standard solutions.
The overall system solution SHOULD avoid requiring bespoke solutions for every merchant i.e. one-to-one integration.
The VAS applet SHOULD be able to perform adequately and within the time limits acceptable within an NFC tap experience.
REQ 37
Data connectivity not present
Support SHOULD be provided for offline handsets. The handset MAY not have data connectivity at the Point of Sale. Hence, coupon data
SHOULD be downloaded to the handset (UI applications) prior to a
V1.0 Page 15 of 66
GSM Association
Official Document NFC.19 - Value Added Services Applet Design Proposal
Non-confidential
Req. no.
Requirement Description customer being at the Point of Sale.
REQ 38
REQ 39
Support multiple regions
The VAS applet MAY be used across multiple regions.
Open market handsets
REQ 40 Publication
REQ 41 Publication
REQ 42 Publication
The VAS applet, and the overall solution, SHOULD support open market handsets.
The SP SHOULD be able to publish to the VAS applet the coupons selected by the user for redemption.
The SP SHOULD be able to publish the LoyaltyID on the VAS applet.
The SP SHOULD be able to publish the CustomerID on the VAS applet.
REQ 43 Publication
REQ 44 Publication
REQ 45 Expiry
REQ 46 Coupon burning
REQ 47 Publication
The SP SHOULD be able to define if and which security mechanisms have to be applied to the publication of coupons.
Coupons/ LoyaltyID / CustomerID MAY be unpublished when explicitly requested by the SP.
Coupons may expire after a certain date/time has passed.
Coupons MAY be removed subsequent to a tap on the POS (HCI event reception).
Note: A poor user experience can follow if this action is not matched to a redemption in online systems, e.g. coupon presented without a valid item being purchased, which is then not accepted.
For publication, coupons/ LoyaltyID / CustomerID SHOULD be concatenated according to a common format.
Table 4 : Applet design requirements
4 Assumptions
The proposed design outlined in this document builds upon the following assumptions:
Applet provisioning is simplified and provided as a service by the applet provider or their partner: This architecture depends on simplifying the overall provisioning and lifecycle management of the applet. Hence, a logical SP TSM or its related components should be provided by the applet provider, such as the mobile operator, to service providers. To an extent, service providers will not be aware of TSM complexity. For service providers, the main use case is the delivery of VAS data to end customers, and receiving it back from them at the Point of Sale.
The applet will be assisted by a VAS Plugin/VAS Manager when communicating with various apps: The applet itself will not control communication with the underlying apps, but will use a lightweight plugin to do so.
Speed at POS: The maximum recommended tap time (time to tap a handset at a contactless terminal for transfer of data) for optimum user experience is generally accepted to be between 600-800ms. Within this architecture, it is proposed that the handshake between the contactless terminal and the applet consist of 3 APDU command exchanges, totalling between 120-200ms. That leaves around 480-600ms
V1.0 Page 16 of 66
GSM Association
Official Document NFC.19 - Value Added Services Applet Design Proposal
Non-confidential of remaining time, enough for 8-12 APDU command exchanges for data transfer. For optimal performance, it is expected that the actual data transfer between the two components will not exceed 3-4 APDU command exchanges, easily within the acceptable bounds.
There will only be a single VAS applet on the Secure Element (SE) for simplification and consistency of integration. Hence, use cases for multiple applets are out of scope of this proposal.
The VAS applet will store the data, have a security policy file, and have links to different interfaces (contact, contactless, and Over The Air).
The applet communicates/responds over the contactless channel (API 1) and the contact channel (API 2) using the same method, i.e. via APDU commands.
5 Architecture
In this section, a simplified architecture is presented, which is based on the guiding
principles outlined in section
1.4 and the overall system architecture defined in NFC.15 [2]
(for details, see Annex A). This architecture is not mandatory or necessary for successful
value added services, however, it is strongly recommended to achieve benefits within requisite timescales and to minimise costs of development.
5.1 System Architecture
The following diagram shows various components that reside on the handset for successful
NFC based value added services. It also shows the interfaces between these components and to external sources. The diagram references the NFC based VAS ecosystem
architecture as defined in NFC.15
V1.0 Page 17 of 66
GSM Association
Official Document NFC.19 - Value Added Services Applet Design Proposal
Non-confidential
Component
VAS Applet
VAS
Plugin/Manager
VAS SDK
MNO Wallet App
Figure 4
: System architecture
Description
VAS applet hosted within a secure element environment and responsible for facilitating communication between UI VAS applications (via the plugin) and the PED (or other NFC readers).
Service component hosted on the mobile device and responsible for presenting a simplified, functional interface between the secure element VAS applet and UI applications that utilise the VAS applet. Capable of performing administration and co-ordination activities, local caching of data where UICC memory is limited, and facilitating and arbitrating between multiple user interface applications that could be contending for VAS applet resources.
A library provided by the mobile operators which is built into the SP User
Interface to interface to the VAS plugin. The API presented allows user interface applications to access and manage VAS content hosted by mobile operator secure element applets.
A consumer facing wallet application published by individual mobile operators. Contains functionality to support loyalty and couponing, and other value added services capabilities.
V1.0 Page 18 of 66
GSM Association
Official Document NFC.19 - Value Added Services Applet Design Proposal
Non-confidential
Component
Apps
MNO Wallet App
Server
Description
Any app (Service Provider User Interface) residing on the handset that wishes to interface to the wallet.
Mobile operator based management suite offering coupon, loyalty, account management, etc.
SP App Server
A back-end service implemented by service provider entities to support loyalty and couponing in their consumer facing mobile applications. Services implement authentication, content management and interfacing with further back-end systems, such as a loyalty service provider, to facilitate the consumer facing service provider application experience.
Contactless Reader
The contactless reader is the merchant device that interacts with the consumer’s handset and VAS applet to perform the transaction, e.g. the
PED.
API 1
API 2
API 3
API 4
API used by the PED/terminal to extract information from the value added services applet.
Application Protocol Data Unit (APDU) level API for access to the applet from within the handset.
High-level API/software development kit (SDK) used by UI apps to access the VAS applet.
Back-end app servers use this API to talk to their apps.
Table 5 : System architecture components
5.2 Applet Architecture
The following standard architecture is proposed for the applet, referencing the generic
SIMalliance Open Mobile API Secure Storage [6] applet.
V1.0 Page 19 of 66
GSM Association
Official Document NFC.19 - Value Added Services Applet Design Proposal
Non-confidential
Figure 5 : Applet architecture
The architecture consists of the following components:
Component
Communication
Interface
APDU Processing
Description
A central communication interface within the applet to exchange data over all three channels. It also contains a Security Policy block to validate the applicable access of each channel.
Execution of the incoming APDU request. Request execution only happens if the appropriate permissions are in place.
Permissions for
Records
Data
Transformation
A local permissions controller to prevent unauthorised access to data and other subsystems of the applet. The APDU processor checks the permissions before modifying/reading data from the records.
Application of any specific data transformation/cryptography needed to the incoming data. The request would specify the transformation required, if any.
Records
Data storage for all the records. Data can only be modified by certain external components depending on their security policy.
Contactless reader A third-party reader that communicates with the applet via a contactless
V1.0 Page 20 of 66
GSM Association
Official Document NFC.19 - Value Added Services Applet Design Proposal
Non-confidential
Component
VAS Plugin
MNO TSM
Description interface (API 1).
A background service provided by the applet developer that communicates with the VAS applet over API 2.
A TSM platform that uses Over the Air (OTA) to communicate directly with the applet.
Table 6
: Applet architecture components
The applet has a few distinct features, which are described here in detail:
Communication interfaces : As highlighted, there are three distinct communication interfaces to the applet: a contactless interface, a contact interface, and an Over The
Air (OTA) interface. Though all use a similar APDU command set, they have distinct roles and also a distinct security policy of what each interface can accomplish. A security policy (e.g. Secure Channel Protocol 02 (SCP02) encryption) selected by the off-card entity identifies the interface and manages APDU command execution. Each
APDU must comply with the policy. Some operations, for example creating a record or deleting all records, can only be performed if the current policy matches a configured global permission for the receiving interface. o Contactless interface (API 1): This interface is used to communicate with external contactless terminals. The contactless terminal always acts as a master and requests certain records from the applet. Based on the incoming request, security and access control settings, the applet releases the relevant record to the contactless terminal. For further details on API 1,
o Contact interface (API 2): This interface allows applications on the handset to communicate with the applet on the UICC. It enables authorised applications with permission to access information stored on the applet instance to manipulate data. Within this architecture, this interface is only designed to be used between a VAS plugin and the VAS applet. The VAS
Plugin, as described in section 5.1, is a lightweight background service that
acts as a communicator between underlying UI apps and the VAS applet.
For further details on API 2, refer to section 8.5.
o OTA interface: This interface is used for remote provisioning, configuration and personalisation of an applet instance. The use of SCP80 over the OTA channel is mandatory. Further details about this interface are out of scope for this document.
Data storage : This refers to an instance accommodating the storage of records.
Each record contains any necessary identifiers as detailed in section 6, permissions /
security policies for access to the record, coupon/loyalty data and the status of the
coupon/loyalty offer. This feature is mandatory. For further details, see section 6.
Data transformation : An optional step to apply encryption to data before it is stored in a record. This feature is used, for example, to apply cryptographic operations needed for the data to be recognised by third-party machinery (validators, gate controllers, etc.) without moving keys and algorithms off-card. Various cryptographic
V1.0 Page 21 of 66
GSM Association
Official Document NFC.19 - Value Added Services Applet Design Proposal
Non-confidential keys and applicable algorithms are stored within the Data Transformation block. The architecture used to implement this is based on two concepts: o Transformation: A transformation is a strategy object that encapsulates the algorithm to be applied to data (for example, calculating a cryptographic digest). o Context: A context carries the information used by a transformation, such as cryptographic keys and sequence counters.
Each transformation defines its own context type. Many context instances may exist for the same type to allow the same transformation to be used in different scenarios with different keys.
Contexts store information such as cryptographic keys and counters, and each type of transformation has its own context type. Many contexts of the same type can exist so that the same transformation can use different keys/counters depending on the selected context. In design pattern terms, transformations are stateless strategy objects, while contexts hold their extrinsic data. Any updates to contexts MUST only be available over the
OTA interface.
HCI transaction : The facility for HCI transaction events is provided as part of API 2
(contacts interface). These events are used to notify the VAS plugin (and hence the underlying UI apps) that an NFC operation has been performed. These events are routed to an application installed on the handset and can be used to initiate interactions with the user. The functionality of an HCI transaction event is described
6 Data Structure
The data structure proposed in this document is based on some of the above-mentioned requirements and high-level use cases. This proposal presently looks optimal to serve all the use cases, however, applet developers and operators could use an alternate data structure to better serve any specific propositions or requirements.
V1.0 Page 22 of 66
GSM Association
Official Document NFC.19 - Value Added Services Applet Design Proposal
Non-confidential
Figure 6 : Applet data structure overview
Records are created by the MNO TSM via the OTA platform, a few are created at the time of applet personalisation.
Each record is a container which can be identified by its ID. A user friendly Title is optionally available to describe the record contents. Within the proposed framework, an operator can use the ID or the Title as their MerchantID (the selection is dependent on the length of the
MerchantID an operator wants to store).
The data segment is a container for VAS data. An example data structure is illustrated
in Figure 6. The data length is flexible and will contain one or more coupons, additional
identifiers, and other appropriate VAS data. For every MerchantID , there will be a maximum of one record only.
A common record can be created to store open loop coupons, which are assigned to multiple merchants. This record will only be managed by the operator application. For all the
other, proprietary fields are also supported for these identifiers.
Table 7 provides data structure attributes for each of the records:
Name
ID
Title
PERM
Description
The applet SHOULD ensure that this field is unique.
User friendly identifier for the record. Optional.
Permission to access a record for reading and writing data.
Length
2 bytes
2 – 60 bytes
4 bytes
V1.0 Page 23 of 66
GSM Association
Official Document NFC.19 - Value Added Services Applet Design Proposal
Non-confidential
Name
DATA
STATUS
Description
Total payload data of the record. This can store any VAS data to be sent to the contactless reader (either encrypted or unencrypted).
Status of the data being transmitted. Optional
Possible values: Active, Presented, Burned, Expired.
Table 7 : Data structure attributes
Length
Flexible
2 bytes
Table 8 provides example elements within the proposed data structure.
Name Elements Description
ID or
Title
Merchant
ID
A MerchantID is considered as an ID issued by the mobile operator. The contactless reader will use this ID to get the
A MerchantID can consist of a Loyalty/Enterprise identifier byte and a Merchant identifier byte. This ensures compatibility for coalition loyalty. If such scheme is used, the
Merchant identifier SHOULD be stored in the least significant
8 bits and the Loyalty/Enterprise identifier SHOULD be stored in the most significant 8 bits.
Loyalty /
Enterprise
Merchant
Customer
ID
Loyalty identifier for a merchant. Used in special cases of coalition loyalty.
Merchant identifier.
Length
2 – 60 bytes
1 – 30 bytes
1 – 30 bytes
8 bytes Unique identifier of the end user delivered by the service provider, enabling service providers to track customer interactions.
Note: If the MSISDN is used as the idenitifier, it is recommended to check any relevant data protection regulation.
8 bytes
DATA
Location ID Identifies the location where the coupon/loyalty discount was redeemed.
Operator
ID
Unique identifier of the end user delivered by the mobile operator.
Coupon data
Other VAS data
Data stored entitling the holder to a discount off a particular product or service.
Other data similar to coupon data, e.g. loyalty data.
2 bytes
20-100 bytes
20-100 bytes
Table 8 : Example data in the data structure attributes
The benefits of the above structure and corresponding elements are:
Simple identification and selection of records.
Computation time is low at the applet level.
Flexible storage ensures that large amounts of data per entry can be stored, and that each record can have a different storage length.
V1.0 Page 24 of 66
GSM Association
Official Document NFC.19 - Value Added Services Applet Design Proposal
Non-confidential
Adherence to the closed loop coupons use case: As each entry is stored per merchant, a closed loop system for coupon redemption can be established easily.
Adherence to the open loop coupons use cases: The data structure caters to storing open loop coupons in a single common record, and also in individual merchant records.
7 Applet Installation and Provisioning
The following sections describe the processes required to install and provision an applet.
The overall installation process starts with the user downloading and installing the SP
application and ends with the plugin and applet both being installed. In section 7.2, the
applet install process is described in more depth, where the plugin sends a set of commands
to the mobile operator via HTTPS. Section 7.3 describes a proposed provisioning option that
ensures that service provider data is protected from unauthorised parties.
7.1 Overall Installation Process
The following diagram shows an ideal scenario within the installation journey assuming that the end customer has compatible hardware. For a more detailed and comprehensive view of
the installation process, refer to Annex D.
End user downloads and installs
SP application
End user opens app
Additional checks included:
- Is mobile device NFC compatible?
- Is UICC NFC compatible?
- Is OS version compliant with plugin?
- Is mobile operator compliant with plugin?
Is plugin installed?
No
Yes
End user downloads and installs plugin
Is applet installed?
No
Yes
Applet is downloaded and installed on UICC
Applet instance is created
Additional check included:
- Are mobile data services available?
New record is created for SP
Additional check included:
- Is NFC activated on the mobile device?
Service is ready to be used
Figure 7 : Installation process
The applet installation process begins with the end user downloading a UI application
(provided by the mobile operator, a service provider or another third party) from the appropriate application store. Upon completion, the end user opens the application on their mobile device. The application will run through a series of steps. If the plugin is not installed
V1.0 Page 25 of 66
GSM Association
Official Document NFC.19 - Value Added Services Applet Design Proposal
Non-confidential on the device, the end user will be prompted to return to the app store to download and install this. If/once the plugin is present on the device, the user will require the installation of an applet on the UICC if not already present. An applet instance is then created, followed by a data record/entry. Note that if the applet already exists on the UICC, an instance will have already been created. The installation process is then complete.
7.2 Applet Installation Process
The installation of the applet is triggered by the plugin when it is unable to find a compatible
VAS applet on the UICC. Figure 8 shows the functional details of the processes involved.
The plugin initially performs compatibility checks on the handset and the UICC and looks for an appropriate VAS applet.
1. If a VAS applet is not found, the plugin sends a message to the MNO/SP TSM
(directly or by a dedicated front-end/back-end system) requesting it to perform the creation of the applet instance with a specific set of commands. This communication occurs over HTTPS.
2. The MNO/SP TSM performs some eligibility checks.
3. The MNO/SP TSM will then carry out a Remote Application Management (RAM) session that will result in the VAS applet instance being created inside the desired security domain. If the UICC/SIM card issuer opted for not pre-loading the VAS applet
Executable Load File (ELF) on the card in the pre-issuance stage, it can be provisioned Over The Air by the MNO/SP TSM (using RAM and Remote File
Management (RFM) commands). Moreover, if the target security domain is not present, it can be created Over The Air by the MNO/SP TSM.
4. Then, the applet instance will be created. The applet will then bind to the plugin.
5. Optional SP specific cryptographic keys can be transferred to the applet.
6. After successful instantiation, the personalisation phase can be performed in order to load any required data to the applet (such as security keys, data record creation, etc.).
V1.0 Page 26 of 66
GSM Association
Official Document NFC.19 - Value Added Services Applet Design Proposal sd Applet installation process
Plugin MNO / SP TSM UICC
Non-confidential
Send set of commands to install applet package key() opt
Eligibility check()
Push applet()
Package keys()
Create Security
Domain and load package()
Instance creation()
Bind to plugin() opt
SP keys for cryptography()
Personalise data()
Figure 8 : Applet installation sequence details
7.3 Provisioning Process
Service providers require protection of their data so that it cannot be accessed or manipulated by unauthorised parties. The mobile operator can fulfil this requirement by facilitating the security of individual SPs’ data within a single VAS instance as illustrated
in Figure 9 . This supports additional use cases of “open loop coupons/loyalty”.
V1.0 Page 27 of 66
GSM Association
Official Document NFC.19 - Value Added Services Applet Design Proposal
Non-confidential
Figure 9 : Provisioning architecture
Note: The Utility Security Domain (USD) shown in the figure is an “authority” security domain where mobile operators load some of the applets. It can be used when creating new security domains for individual applets or when creating an applet instance.
The provisioning process has the following steps:
1. The mobile operator either pre-loads the VAS applet on the UICC, or loads it via
OTA.
2. On first use, the applet is personalised via the MNO TSM and an applet instance is created. This instance will store all the coupons and loyalty information, including the
MerchantID .
3. The POS terminal will need to pass a MerchantID so that the applet can return relevant coupons/loyalty info.
Alternative provisioning options are presented in Annex C.
8 Application Programming Interfaces
The applet can communicate over three interfaces – contactless, contact and OTA. All interfaces communicate via standard APDU commands, but have different grant management options on them for security.
8.1 Command Management
The applet instance responds to a fixed set of APDU commands for extracting or updating stored data. Such commands can be issued over all supported interfaces and it is possible to manage each grant for each interface:
V1.0 Page 28 of 66
GSM Association
Official Document NFC.19 - Value Added Services Applet Design Proposal
Non-confidential
GRANT management
CREATE
OTA
Y
WRITE/DELETE Y
READ Y
DELETE ALL Y
Supported Command Interfaces
CONTACT CONTACTLESS
N
Y
Y
N
Table 9 : Supported command interfaces
N
N
Y
N
8.2 Applet AID Options
There are two options for the contactless reader to establish a connection with a VAS applet.
The contactless reader can connect to the VAS applet using a partial Application Identifier
(AID) match (RID) or a full AID match. Both of these are acceptable but significantly alter the design of the underlying applet architecture and the complexity of integration at the POS.
8.2.1
AID Option 1
The POS has a unique AID match for each mobile operator.
Figure 10 : AID option 1 – Full AID match
Each AID is unique for an applet. A full AID match is required to select the appropriate VAS applet. Mobile operators and other applet developers can register a unique AID with a standards body and get contactless readers to use it. Each contactless reader will need to be configured to look for a specific AID. In case of multiple mobile operators offering this service in a given region, a whitelist of AIDs will be required to be maintained by the contactless reader – and the contactless reader will need to look for each one in a sequence. As such, this method is complex to execute and maintain, and hence may not be preferred in a multi operator scenario.
8.2.2
AID Option 2
The POS has a partial AID match for a group of mobile operators, either per region, per country, or at a global scale.
V1.0 Page 29 of 66
GSM Association
Official Document NFC.19 - Value Added Services Applet Design Proposal
Non-confidential
Figure 11 : AID option 2 – Partial AID match
An AID can be selected through a common AID standardised by the GSMA where a partial
AID is found (RID). The rest of the AID (PIX) is configurable, and the GSMA has a proposal
in this regard within NFC.15
[2]. See Annex E for details.
Given that a single VAS applet based configuration is the preferred choice for the
provisioning of the applet on the UICC (see section 7.3 on provisioning for details), this
method of selection would always result in a single AID match across all mobile operators in a given region. Contactless readers could be configured globally to look for the common RID only, thus making deployment of retail services at new merchants a simpler process.
8.3 HCI Transaction Event Generation
In the event of an HCI transaction, the VAS applet notifies the VAS plugin that an NFC operation has taken place and updates the data status of the appropriate records. The plugin requests the data statuses from the applet to further analyse changes. The plugin works out where data has changed and notifies the corresponding SP application installed on the handset. Specifically on Android, a certain TRANSACTION_EVENT is communicated by the applet with the SE Identifier and AID. sd HCI Transaction ev ent
VAS Applet VAS Manager /
Plugin
SP App 1 SP App 2
HCI: Notification that an NFC operation has been performed()
Update with data status()
Send data()
Analyse data status()
Notification that app data has changed()
Notification that app data has changed()
Figure 12 : HCI transaction event workflow
V1.0 Page 30 of 66
GSM Association
Official Document NFC.19 - Value Added Services Applet Design Proposal
Non-confidential
8.4 API 1
API 1 defines the interface between the VAS applet and the contactless reader. The proposal presented here is based on the GSMA: Mobile Commerce NFC Coupons and
Loyalty Acceptance
− Technical Proposal (Version 1.0) [2]. Optional authentication methods
can be implemented to allow the contactless reader to send data to the VAS applet following a security handshake. sd API 1 APDU exchange process
EPOS Contactless Reader
Prop API readCoupon()
TapPhone()
API 1 Select(AID/RID)
VAS Applet
Offer User presents phone to Contactless
Reader.
Offer User
Response(AID/RID, status)
GetVASData(MerchantID,
LocationID (opt), Date/Time (opt))
The Contactless
Reader can request a full AID or a partial
AID (RID) match.
Response TokenData()
The Contactless
Reader selects a record or entry.
Select(Data(length(opt)))
Response(Data(length(opt)))
The length of the record is requested by the Contactless
Reader, and returned by the Applet.
loop DataTransfer
[length = 0 -> transfer all data]
GetResponse()
VASTokenList(data)
The Contactless
Reader sends over the data in the form of an APDU, and repeats this step if the data is split into multiple
APDUs.
opt
PutVASData()
Response(Success)
Send static information back to the applet.
Figure 13 : API 1 APDU exchange process
Figure 13 shows the APDU exchange process across the API 1 interface between the applet
on the UICC and the contactless reader.
The user taps their mobile device on the contactless reader, which prompts the selection of an AID or RID. An AID/RID match will select the appropriate VAS applet.
V1.0 Page 31 of 66
GSM Association
Official Document NFC.19 - Value Added Services Applet Design Proposal
Non-confidential
Within the applet, a record is selected and the data size is extracted. One APDU command can transfer up to 256 bytes of data. If the data size is below 256 bytes, the contactless reader will request for the data to be sent within one APDU. If the data size exceeds 256 bytes, the rest of the data will be sent via more APDUs until all data is transmitted to the contactless reader. Standard ISO mechanisms will be used to handle data size above 256 bytes.
An optional PutVASData command can be used by the contactless reader to send some static information back to the applet before the end of the session.
8.5 API 2
This API enables APDU communication with the VAS plugin. API 2 is similar to the API 2
defined in NFC.15 [2] as well as API 1 defined above, however, this API 2 has the extra
capability to write records. This document does not intend to provide full API specification details but only lists the commands that can be used:
CreateRecordMerchantID(MerchantID) : Create a new record for a merchant.
This has a compulsory parameter, MerchantID , which is used as an ID within the record data structure. This command will only be used when a new merchant / service provider is being added. There is also a common record that is maintained by the mobile operator.
GetVASData(MerchantID) : Obtain VAS data for an individual MerchantID . This is typically used in HCI event notification use cases or when a compatible app wants to know about the data it has stored on the applet.
PutVASData(MerchantID, data) : Write VAS data for the record with a particular
MerchantID . This is typically used when a compatible app wants to write new data to the applet. This includes writing new data, removing parts of or complete data.
GetVASDataStatus(MerchantID) : Get the status of the VAS data record specified by a MerchantID .
V1.0 Page 32 of 66
GSM Association
Official Document NFC.19 - Value Added Services Applet Design Proposal sd API 2 APDU exchange process
VAS Applet
Non-confidential
VAS Manager /
SP App
API 2 select(AID/RID)
Response(AID/RID, status)
GetVASData(MerchantID)
Response(TokenData)
PutVASData(MerchantID, data)
Response(status)
GetVASDataStatus(MerchantID)
Response(VASDataStatus)
CreateRecordMerchantID(MerchantID)
Response(Record created)
HCI event transaction()
API 2 select(AID/RID)
Figure 14 : API 2 APDU exchange process
9 Security
Security is an integral part of the overall architecture, ensuring that any data stored on a secure element based applet can only be accessed by compatible apps via the VAS plugin.
Security inherent within the system is a better solution than the present day system for value added services such as loyalty and couponing and other retail services, as it satisfies most of the security needs of merchants, brands and third parties. However, there are options for enhanced security that these parties can request from the applet. These are:
Security of data between the applet and the contactless reader : This refers to the encryption of data while storing it on the VAS applet. The applet would release the data back in the encrypted format to the contactless reader. The contactless reader/merchant cloud would have the necessary cryptographic keys to decrypt the
V1.0 Page 33 of 66
GSM Association
Official Document NFC.19 - Value Added Services Applet Design Proposal
Non-confidential
data it is being sent. As per Figure 15, the service provider will issue relevant
cryptographic keys from its back-end system to the MNO TSM platform, which in turn would provide them to the VAS applet. The applet would maintain an encryption key for each record. The back-end server would also provide these keys to the merchant
POS system. VAS data would travel through the apps and into the applet unencrypted. Once in the applet, data is encrypted using the stored keys, and sent over to the contactless terminal on an NFC tap. The merchant POS can then decrypt the data using the same keys from the SP back-end server.
Figure 15 : Securing data between applet and contactless reader
Security of channel : Channel security is a complex topic and has limited applicability for value added services deployments. Hence, it is out of scope of this document.
V1.0 Page 34 of 66
GSM Association
Official Document NFC.19 - Value Added Services Applet Design Proposal
Non-confidential
Annex A Overall System Architecture
The high-level solution architecture that supports retail use cases is shown in Figure 16. This
corresponds to the architecture presented in NFC.15 [2] and only additional/amended items
are discussed in detail here.
Figure 16 : High-level solution architecture
For detailed information on system components, refer to section 3.1 in NFC.15 [2].
V1.0 Page 35 of 66
GSM Association
Official Document NFC.19 - Value Added Services Applet Design Proposal
Non-confidential
Annex B High-Level Use Cases
This proposal seeks to enable high-level coupon use cases and the aim of this section is to provide an overview of them.
Figure 17 describes specific steps involved in the coupon validation process.
Figure 17 : Coupon validation process
Figure 18 describes the coupon use case process involving coupon creation, issuance,
activation, validation, and redemption.
V1.0 Page 36 of 66
GSM Association
Official Document NFC.19 - Value Added Services Applet Design Proposal
Non-confidential
Figure 18 : Coupon use case steps
Figure 19 provides a high-level overview of the loyalty use case process.
V1.0 Page 37 of 66
GSM Association
Official Document NFC.19 - Value Added Services Applet Design Proposal
Non-confidential
Figure 19 : Loyalty use case steps
V1.0 Page 38 of 66
GSM Association
Official Document NFC.19 - Value Added Services Applet Design Proposal
Non-confidential
Annex C Provisioning Options
There are three different provisioning options that a mobile operator can provide to fulfil technical requirements in this regard.
Option 1: The mobile operator provides the facility to secure an individual SP’s data within a single VAS instance – maintained by the mobile operator. This also facilitates additional use cases of “open loop coupons/loyalty”.
Option 2: An individual security domain for the SP. The mobile operator would create this based on a request from the SP. Note that additional technical development may be required from the SP’s end.
Option 3: Individual VAS instances for each SP. The mobile operator loads a single
VAS applet on the UICC, but provides individual VAS instances for each SP.
Additional technical development is required from the SP’s end.
Options 2 and 3 are described below in more detail. Option 1 is the preferred option and has
been described in section 7.3.
C.1
Provisioning Option 2
Figure 20 : Provisioning option 2 – Single security domain for each SP
The service provider requests an individual security domain from the mobile operator. The
SP would like to maintain this SD. While the mobile operator can provide this, they also need to provide a PPSE-like mechanism so discovery of this additional domain is possible.
This solution is complex as the service provider manages more operations than the mobile operator.
The SP requests the creation of a Service Provider Security Domain (SP SD) from the mobile operator via the MNO TSM. Once created, the SP has an option to directly invoke this security domain AID or to use the MNO AID for discovery.
When using the MNO AID, the contactless terminal passes this to the applet’s PPSE-like mechanism. The PPSE returns a list of available AIDs to the contactless terminal, which can then select the most appropriate one.
V1.0 Page 39 of 66
GSM Association
Official Document NFC.19 - Value Added Services Applet Design Proposal
Non-confidential
Alternatively, the SP can get the contactless terminal configured to specifically read the SP
SD AID as well.
C.2
Provisioning Option 3
Figure 21 : Provisioning option 3 – Individual VAS instance per SP
This is similar to Option 2 however, the SP requests an individual VAS instance of the available VAS applet.
Each instance is dedicated to a specific service/service provider, where different instances are isolated from one another so an SP can only access its own data.
The NFC reader can be configured to read from an individual SP instance directly.
V1.0 Page 40 of 66
GSM Association
Official Document NFC.19 - Value Added Services Applet Design Proposal
Non-confidential
Annex D Overall Installation Process
The following figure shows an example of the overall customer journey for the installation of the plugin and the applet.
Google PlayStore
SP app
End user downloads and installs SP app from PlayStore
Open
SP app
Yes
Do you wish to install
NFC services?
No
Yes
Is NFC plugin for apps installed?
Yes
Is applet installed?
Yes
No
No
Has UICC / SIM card changed?
Yes
No
Is mobile data available?
No
Yes
Is NFC enabled?
Yes
Success Install and perso applet
Error
NFC Services, Installation successful
Notification / SMS
No
NFC is disabled.
Do you want to enable it?
Yes No
Yes No
End user activates
3G/4G
End user activates NFC
Is Android version v4.1 or above?
No
Yes
Check device configuration
(If you don’t have filtering enabled on PlayStore.)
Is mobile device
NFC?
Yes
No
Error Cases
Sorry, your mobile is not
NFC compatible.
To finalise the installation of your NFC services, switch on 3G/4G network.
Yes
Yes
No
No
Is Android v4.1 or above?
No
Yes
Does operator support services?
No
Yes
To use NFC services, download NFC plugin for apps from PlayStore.
Yes
Yes
No
Google PlayStore
NFC plugin for apps
End user downloads and installs NFC plugin for apps from
PlayStore
No
Sorry, to use this service, you need Android v4.1 or above.
Sorry, service available for
‘MNO 1’ customers only.
Display recommended notification message to the end user
If Error =
UICC_not_compliant or
Handset_not_complaint or Offer_not_compliant
SP app home screen
Figure 22 : Overall installation process
V1.0 Page 41 of 66
GSM Association
Official Document NFC.19 - Value Added Services Applet Design Proposal
Non-confidential
Annex E Generic AID Option
Like other UICC applets, the VAS applet is identified and selected by its application identifier
(AID). The standard selection command is called by the POS system to make the VAS applet selected and ready for further APDU processing.
The VASAppAID is the application ident ifier of the mobile operator’s VAS applet. The
encoding of the VASAppAID is defined according to
Table 10 taken from NFC.15 [2]:
Meaning
RID
This RID is internationally unique and reserved for applications according to this proposal.
Application Code
Mobile Country Code
Three digit code (as per ITU-T E.212 [9]) as a BCD, right aligned,
padded with F, e.g T-Mobile Deutschland GmbH 0xFF:0x01.
Mobile Network Code
Two or three digit code (as per ITU-T E.212 [9] as a BCD, right
aligned, padded with F, e.g. T-Mobile Deutschland GmbH
0xFF:0x01.
Application Provider Field (optional, length 0-5)
Additional provider specific data.
AID-Coding
0xA0:0x00:0x00:0x05:0x59
0x00:0x01
0xFX:0xXX
0xFX:0xXX or 0xFF:0xXX
0xXX:0xXX:0xXX:0xXX:0xXX
Table 10 : VAS applet AID
V1.0 Page 42 of 66
GSM Association
Official Document NFC.19 - Value Added Services Applet Design Proposal
Non-confidential
Annex F Example Applet Structure 1
This section describes some example parameters and tags that may be considered when developing the structure of a VAS applet. This example has been taken from an active implementation within Europe. A common low-level specification proposal, unifying common elements from this and other implementation examples, is intended to be published in the future to follow this high-level document.
F.1
Installation Parameters for an Instance
In this example, a single AID is specified for communication between the applet and the contactless reader. However, this implementation can also cater to multiple applet instances with individual AIDs.
F.1.1
AID Allocation
This example consists of the following Package and Application module AID:
Package AID: F0 00 00 54 49 FF F0 FF 39 59 43 23 00 00 2F 00
Application Module AID: F0 00 00 54 49 FF F0 FF 39 59 43 23 00 00 2F 01
F.2
Tags
Tag
Storage Size
Tag: 0x81
Description
Available storage space for storing records.
Allocated in fixed-size units called pages.
HCI
Transaction
Tag: 0x84
Delete all/Create availability
Tag: 0x82
Enables the generation of
HCI transaction events at the end of contactless sessions.
These parameters dictate which interfaces will accept
CREATE/DELE
Parameters
Two unsigned, 2-byte integers in big endian form:
Integer 1: Total space available for user data;
Integer 2: Page size, must be greater than or equal to 32.
There are, however, two constraints:
Integer 1 must be evenly divisible by Integer
2;
The ratio Integer 1 : Integer 2 must lay in the range [1,255].
Specifies if HCI transaction events should be generated at the end of a contactless session. If this tag is not specified, no events will be generated.
Payload structure (holding 1 byte):
Bit
7-1
Bit 0 Note
RFU 0 HCI transaction events will not be generated.
RFU 1 HCI transaction events will be generated.
Specifies over which interfaces and under which security policies it is possible to:
Create new records.
Perform DELETE ALL commands.
Note: Usually records can only be deleted via
Example
This example asks for a
16kB pool split into
128-byte pages:
81 04 40
00 00 80
This example enables
HCI events:
84 01 01
V1.0 Page 43 of 66
GSM Association
Official Document NFC.19 - Value Added Services Applet Design Proposal
Non-confidential
Tag Description
TE ALL commands.
Parameters
DELETE commands over any interfaces from which they are writeable, but since DELETE ALL always deletes all records (including those that
DELETE, in the same conditions, would fail to erase) it is treated as a privileged operation and must be explicitly authorised at installation time.
If this tag is missing, all interfaces will accept both operations.
The payload consists of 3 bytes, mapping to (in this order):
1. OTA interface;
2. contact interface;
3. contactless interface; and within each byte, the lower nibble gives the policy for CREATE commands, while the higher nibble gives the policy for DELETE ALL commands.
Table 11 : Tags
Example
F.3
Data Structure Metadata
For each newly created record, it is possible to specify a set of metadata describing extended record features.
Currently, the defined metadata are:
The TITLE.
The access bitmask specifying operations available for the newly created records over each interface.
Metadata are fixed when the record is created. The only way to change them is to delete a record and re-create it.
Each record can be made available, for read and/or write, over just a subset of the supported interfaces. For instance, a record may only be readable over the contact interface for security reasons, while another may be freely readable, but only contactless writes can update it.
Metadata are stored in Type Length Value (TLV) entries.
F.3.1
Record Availability
Tag
Record availability
Tag: 0x81
Description Parameters
Security setting for each record, when it is being accessed over a certain interface.
Payload holds 3 bytes: every byte maps to a different interface and each nibble defines a security constraint for a specify operation.
Tag Length Value
V1.0
Example
Example:
81 03 99
0C A8
Page 44 of 66
GSM Association
Official Document NFC.19 - Value Added Services Applet Design Proposal
Non-confidential
81 03 OTA-byte
Contact-byte
Contactless-byte
The 3 bytes define the security mechanisms that must be applied for a record to be read (lower nibble) or written/deleted (higher nibble) over the specified interface.
If not specified when creating a record, it will be freely accessible over any interfaces for any operations.
Table 12
: Record availability tag
F.3.2
Title
It is contained in a tag ‘82’ and its length must be lower than or equal to 60 [6].
The applet will never interpret the TITLE, it will just treat it like an opaque binary blob.
However, its goal is to be used as a human-readable description, so it is recommended to set it to a meaningful UTF-8 string.
Also, the maximum length is expressed in bytes, not in characters. If characters requiring multi-byte UTF-8 encodings are used, the actual number of available characters will decrease.
If not specified, a TITLE-less record will be created.
Tag
82
Length
From 1 to 60
Value
UTF-8 TITLE
Table 13 : TITLE structure
F.4
API Example
F.4.1
Select File API
Type Length Value Field name
CLA Byte 1 0x00
INS
P1
P2
Lc
Data
Byte
Byte
Byte
UInt8
1
1
1
1
Lc
0xA4
0x04
0x00
0x10
0xF0:0x00:0x00:0x54:0x49
:0xFF:0xF0:0xFF:0x39:0x5
Description
Instruction class: No secure messaging or no secure messaging indication
Select File
Direct selection by dedicated file name (Data field = dedicated file name)
First record, Return FCI, optional template
Length of the AID
VAS Applet AID
V1.0 Page 45 of 66
GSM Association
Official Document NFC.19 - Value Added Services Applet Design Proposal
Field name
Type Length Value Description
Le Byte
Non-confidential
1
9:0x43:0x24:0x20:0x00:0x
20:0x00
0x00 No maximum length
Table 14 : VAS applet Select File command
Field name
Status
Code
Type
Short
Length Value
2 0xXX:0xXX
Description
SW1 SW2 e.g. 0x90:0x00 Operation successfully completed
File not found e.g. 0x6A:0x82
Table 15 : VAS applet Select File response
F.4.2
GetVASData/1 API
Type Length Value Field name
CLA
INS
P1
P2
Lc
Data
Le
Description
Byte
Byte
Byte
Byte
UInt8
1
1
1
TagList Var.
Byte
1
1
0x80
0xA5
0x00
0x00
0x02
0x00:0x01
Instruction class: No secure messaging or no secure messaging indication
Custom instruction:
GetVASData
Length of Data field
List of Tags required. Note:
Specific tag list to be determined.
No maximum length 1 0x00
Table 16 : VAS applet GetVASData/1 command
F.4.3
GetVASData/2 API
Type Length Value Field name
CLA Byte 1 0x80
Description
INS
P1
P2
Byte
Byte
Byte
1
1
1
0xCA
0x00
0x00
Instruction class: No secure messaging or no secure messaging indication
Custom instruction:
GetVASData
V1.0 Page 46 of 66
GSM Association
Official Document NFC.19 - Value Added Services Applet Design Proposal
Non-confidential
Field name
Le
Type Length Value Description
Byte 1 0x00 No maximum length
Table 17
: VAS applet GetVASData/2 command
F.4.4
ReadVASData API
Type Length Value Field name
CLA
INS
P1
P2
Lc
Data
Le
Description
Byte
Byte
Byte
Byte
UInt8
1
1
1
TagList Var.
Byte
1
1
0x80
0xCA
0x01
0x00
0x20
Instruction class: No secure messaging or no secure messaging indication
Custom instruction:
GetVASData
Length of Data field
List of Tags required. Note:
Specific tag list to be determined.
No maximum length 1 0x00
Table 18 : VAS applet ReadVASData command
F.4.5
PutVASData API
This command overwrites the contents of the currently selected record.
Field name
CLA
INS
P1
P2
LC
DATA
LE
Value Description
0x80
0xDA
0x00 or 0x01 or 0x02
0x00 or 0x01
Var
-
0: Declares the total size of the data to be written and an optional data transformation
1: Sends the first chunk of data
2: Sends the next chunk, up to the declared total
Controls the format of the payload. See below for further info. When P1 != 0, P2 must be 0.
No maximum length
If P1 != 0: Payload data is to be written as is.
If P1 == 0: The payload format will change based on the
P2 value. See below for details.
Table 19 : VAS applet PutVASData command
The payload can take different forms depending on the value of P1 and P2.
V1.0 Page 47 of 66
GSM Association
Official Document NFC.19 - Value Added Services Applet Design Proposal
Non-confidential
P1
0x00
0x00
0x01
0x02
0xXX
P2
0x00
0x01
0x00
0x00
0xXX
Description
Use “Format1” described below.
Use “Format2” described below.
The payload contains a chunk of data to be written to the record.
The payload contains a chunk of data to be written to the record.
Any other combination is treated as an error.
Table 20 : PutVASData parameter values
The rationale behind the table above is that when transferring data (cases P1 == 0x01 or P1
== 0x02), the APDU payload simply contains an unadorned chunk of data (that is, no TLV envelopes) that is processed by the applet and stored accordingly.
When P1 takes the value 0x00, however, two formats can be used, and the selection is controlled by P2. “Format1” corresponds to what used to be supported by an earlier version of the applet, only providing the size of the data t o be transferred. “Format2”, introduced in version 2.0 of the applet, extends such format by using a TLV list to include various data, including transformations to be applied to the data as they are written.
It is important to note that when transformations are used, the space actually used to store data may be different (either smaller or larger) than the size of the raw data sent to the card.
For example, adding checksums or encryption is likely to result in an increase of record size: the total data size passed in this command will not necessarily match the record size returned by GetVASData .
Some transformations may update state after each usage. For example, after applying a cryptographic checksum, some counters may be incremented before the next run. If such updates are required, they are performed automatically during the execution of the command having a P1 of 0x00. If the following data transfers fail or need to be re-issued (for example, the client declared a wrong data length), then executing the P1 == 0x00 command again will update those counters again. As a side effect, it is architecturally impossible to implement transformations that depend on the actual data stream to update inter-session state.
Payload Description
Size of data
Total size of the data to be written, expressed as a 2-byte integer in big endian form.
Table 21 : Format 1
Tag
0x81
0x82
Length Value
2
4
Size of data
Presence Description
M Total size of the data to be written, expressed as a 2-byte integer in big endian form.
Transformation selector
O Selects a data transformation to be applied to the incoming data.
The first two bytes represent a big endian integer, called the transformation index . The last two bytes represent a big endian
V1.0 Page 48 of 66
GSM Association
Official Document NFC.19 - Value Added Services Applet Design Proposal
SW1
0x90
0x6E
0x6D
0x6A
0x67
0x6A
0x69
0x68
0x65
0x6A
0x87
0x82
0x82
0x81
0x88
Non-confidential
Tag
0x83
Length Value
Var
Presence Description integer, called the context index .
The transformation index selects one of the supported transformations; the context index selects a security context from where configuration will be loaded and updated, if necessary.
If this TLV is omitted, no transformation will be applied.
Transformation parameters
C Provides transformation-specific parameters used to initialise the transformation selected with tag 0x82. This tag must not be present if tag 0x82 is not present. If tag 0x82 is present, the presence of this tag depends on the specific transformation:
some may not accept parameters
others may accept them but provide a suitable default if nothing is explicitly provided
still others may always require them
The format of this tag, for each transformation, is defined in the sections describing them.
Table 22 : Format 2
F.4.6
Status Codes
The following table lists those status words (SWs) whose meaning is the same for all commands. For each command only those SWs carrying a peculiar meaning will be explicitly listed.
SW2
0x00
0x00
0x00
0x86
0x00
Data
Operation completed successfully
Wrong CLA
Wrong INS
Wrong P1/P2
The number of payload bytes in a command is not correct, or the value of Le is too short to carry the entire response.
LC inconsistent w.r.t. P1/P2
Security error
Secure messaging not supported. It means that an APDU related to security was received but the applet did not expect secured commands.
Internal storage error
There is no selected record
V1.0 Page 49 of 66
GSM Association
Official Document NFC.19 - Value Added Services Applet Design Proposal
Non-confidential
SW1
0x6A
0x69
0x6A
0x69
0x6A
SW2
0x80
0x85
0x84
0x86
0x81
Data
Invalid payload. This SW is returned every time the payload is not well-formed:
a mandatory TLV is missing
a TLV contains unsupported values
For example, specifying a non-existent transformation or context index would cause this error.
Some parts of the command specify policies that cannot work together. For example, specifying a transformation index and a context index that cannot work together, or the amount of data to be transferred is unsuitable for the requested transformation (i.e. the transformation uses a block cipher without padding, and the total data size is not blockaligned).
Space exhausted. When transformations are used, the space actually used for storage may be larger than the raw data stream. For example, a 128-byte data block cannot fit in a
128-byte record if the data is encrypted using
ISO 9797-1 Method 2 padding, due to the additional appended block.
The selected record is not writable over the current interface
A write with P1 != 0 was issued before sending a write with a lower P1
Table 23 : Common status words
F.5
Example APDU Exchange
The following example shows an APDU exchange performed to read 32 bytes of data.
V1.0 Page 50 of 66
GSM Association
Official Document NFC.19 - Value Added Services Applet Design Proposal sd APDU exchange example 1
Contactless Reader UICC
Non-confidential
Select applet
(00A4040010F000005449FFF0FF395943242000200100)
Response(xx{N}9000)
GetVASData1(80A5000002000102)
Response(00019000)
GetVASData2(80CA000002)
Response(00209000)
ReadVASdata(80CA010020)
Response(xx{32}9000)
PutVASdata(80DA0001)
Response(xx{N}9000)
Select an applet upon locating a matching AID.
Applet is selected successfully.
Extract data from
UICC - Step 1.
Step 1 of extracting data from UICC is successful.
Extract data from
UICC - Step 2.
Step 2 of extracting data from UICC is successful.
Read the data in the APDU
32 bytes of data is read successfully.
Overwrites the contents of the selected record
Record written over successfully
Figure 23 : APDU exchange example 1
V1.0 Page 51 of 66
GSM Association
Official Document NFC.19 - Value Added Services Applet Design Proposal
Non-confidential
Annex G Example Applet Structure 2
Another VAS applet example is presented in this section. A common low-level specification proposal, unifying common elements from this and other implementation examples, is intended to be published in the future to follow this high-level document.
This example supports a full AID match only, so NFC readers must select the full 9-byte AID.
In the case where a single matching AID is present within the UICC, it will be returned to the contactless reader and a secure channel will be established. Note that this implementation supports a single AID approach only.
G.1
Installation Parameters
The VASAppAID is the application identifier of the mobile operator’s VAS applet. The encoding of the VASAppAID
is defined according to Table 24:
Meaning
RID
This RID is internationally unique and reserved for applications according to this proposal
Application Code
AID-Coding
0xA0:0x00:0x00:0x04:0x85
0x10:0x01:0x01:0x01
Table 24 : VAS applet AID
G.2
VAS Applet Example Data Structure
G.2.1
MerchantID
MerchantID is the unique identification of a merchant. This ID is used by the VAS applet as the primary filter criteria to transfer the applicable coupon data to the target contactless reader. Note that only the metadata structure of the MerchantID is defined in TLV format.
MerchantID is a mandatory data element for a VAS tap to be valid.
To work across mobile operator boundaries, it must be unique across all implementations.
There should be a MerchantID publishing function built into the solution, possibly similar to the AID administration function performed by ANSI.
Field name
TAG
LEN
VALUE
Type
Byte
Byte
Length
2
1 variable
Table 25 : MerchantID TLV structure
Value
0xDF:0x31
Max 8 Bytes
Format BCD
G.2.2
LoyaltyIssuerID
LoyaltyIssuerID is the unique ID number of a loyalty program. It is used by the VAS applet as one of the filter criteria to transfer the applicable loyalty data to the contactless reader. Note that only the metadata structure of the LoyaltyIssuerID is defined in TLV
V1.0 Page 52 of 66
GSM Association
Official Document NFC.19 - Value Added Services Applet Design Proposal
Non-confidential format, and it is open to adopt any standard for its data. For example, use the Global
Location Number as defined in GS1 Digital Coupon Standards [7].
In this solution, the LoyaltyIssuerID will typically match the MerchantID . If this does not happen, then there may need to be a LoyaltyIssuerID administration function built akin to MerchantID generation.
Field name
TAG
LEN
VALUE
Type
Byte
09
Byte
Length
2
1 variable
Table 26 : LoyaltyIssuerID TLV structure
Value
0xDF:0x41
Max Length 08 Bytes
Format BCD
G.2.3
CouponIssuerID
CouponIssuerID is the unique identification number of a coupon issuer. This ID is used by the VAS applet as one of the filter criteria to transfer the applicable coupon data to the contactless reader. Note that only the metadata structure of the CouponIssuerID is defined in TLV format, and it is open to adopt any standard for its data. For example, use the
Global Location Number as defined in GS1 Digital Coupon Standards [7].
Field name
TAG
LEN
VALUE
Type
Byte
Byte
Length
2
1 variable
Table 27 : CouponIssuerID TLV structure
Value
0xDF:0x54
Max Length 09 Bytes
Format BCD
The first byte tells the applet the type of data to follow. If set to 0x01, the applet will search for merchant coupons associated with the
MerchantID that follows.
G.2.4
VASAppletCapabilities
The data packet defining the VAS applet capabilities is defined as follows:
Field name
TAG
LEN
VALUE
Type
Byte
Byte
Length
2
1 variable
Value
0xDF:0x33
2 bytes fixed length
Format Binary
Table 28 : VASAppletCapabilities TLV structure
V1.0 Page 53 of 66
GSM Association
Official Document NFC.19 - Value Added Services Applet Design Proposal
Non-confidential
Merchant Capability Data will tell the applet what functions and data are supported by the merchant POS system. For example, if the merchant does not support loyalty, the applet can disable the loyalty look-up function and provide faster response times.
G.3
API Example
G.3.1
Select File API
Type Length Value Field name
CLA Byte
INS
P1
P2
Lc
Data
Le
Byte
Byte
Byte
UInt8
Byte
Description
1
1
1
1
1
Lc
1
0x00
0xA4
0x04
0x00
Instruction class: No secure messaging or no secure messaging indication
Select File
Direct selection by dedicated file name (Data field = dedicated file name)
First record, Return FCI, optional template
Length of the AID 0x09
0xA0:0x00:0x00:0x04:0x85
:0x10:0x01:0x01:0x01
0x00
VAS Applet AID
No maximum length
Table 29
: VAS applet Select File command
Field name
Status
Code
Type
Short
Length
2
Value
0xXX:0xXX
Description
SW1 SW2 e.g. 0x90:0x00 Operation successfully completed
File not found e.g. 0x6A:0x82
Table 30 : VAS applet Select File response
Any response other than 0x90:0x00 will terminate the select operation to a response
G.3.2
GetVASData API
Field name
Type Length Value Description
CLA
INS
Byte
Byte
1
1
0x90
0x50
Instruction class: No secure messaging or no secure messaging indication
Custom instruction:
GetVASData
V1.0 Page 54 of 66
GSM Association
Official Document NFC.19 - Value Added Services Applet Design Proposal
Non-confidential
Field name
P1
P2
Lc
Data
Le
Type
Byte
Byte
UInt8
Length
1
1
1
TagList Var.
Byte 1
Value
0x00
0x00
0xXX
Description
Length of Data field
List of Tags required. Note:
Specific tag list to be determined.
No maximum length 0x00
Table 31 : VAS applet GetVASData command
Field name
Data
Status
Code
Type
Short
Length Value Description
0..255
0xXX:0xXX
SW1 SW2
2 e.g. e.g. e.g. e.g.
0x90:0x00
0x61:0x00
0x67:0x00
0x6A:0x80
Operation successfully completed
More data to follow
Wrong data length
Incorrect parameters in the
Data field
Table 32 : VAS applet GetVASData response
In addition to supporting the 0x61 status response, a new command would also need to be added to request the addition of data.
Get Response Data
CLA
90
INS
C0
P1
00
P2
00
Lc
00
Table 33 : Get Response Data
Data
<none>
Le
00
The actual length of the remaining data is variable. Therefore, the Le data length shall be
0x00; allowing the applet to manage a variable length response.
G.3.3
GetVASInternalErrorCode API
The GetVASInternalErrorCode enables the reader or VAS Manager to request the specific status code from the applet after receiving the SW 0x6909 response.
Field name
Type Length Value Description
CLA Byte 1 0x90
Instruction class: No secure messaging or no secure messaging indication
V1.0 Page 55 of 66
GSM Association
Official Document NFC.19 - Value Added Services Applet Design Proposal
Non-confidential
Field name
Type Length Value Description
P1
P2
Lc
Data
Le
INS Byte
Byte
Byte
Byte
1
1
1
1
0x70
0x00
0x00
0x00
Custom instruction:
GetVASInternalErrorCode
No maximum length
Table 34 : VAS applet GetVASInternalErrorCode command
The response will be a 2-byte long internal error code as described in Table 36.
G.3.4
PutVASData API
A PostTransactionData command supports the transmission of data back to the SE.
This command is limited to a single block of data up to 251 bytes of tag data.
This command allows the status of tokens to be updated e.g. a coupon can be marked as redeemed. For this purpose, the tokens have to be referenced by their UniqueID and an
ActionSpecifier has to be given. Using the PutVASData command, the contactless reader has the possibility to update multiple tokens in one step flexibly by simply adding
them to the data field. This is as per ISO 7816-4 [4].
Field name
Type Length Value Description
CLA
INS
P1
P2
Lc
Data
Byte
Byte
Byte
Byte
Byte
1
1
1
1
1
0..255
0x90
0x52
0x00
0x00
0xXX
Instruction class: No secure messaging or no secure messaging indication
Custom instruction:
PutVASData
Length of Data field
Token(s) with their updated status.
Table 35 : VAS applet PutVASData command
G.3.5
Status Codes
The following table defines the possible Status Word values that may be returned by this
command as specified in ISO 7816-4 [4].
SW1
90
61
SW2
00
00
Data
Successful Execution of Command
More data to follow
V1.0 Page 56 of 66
GSM Association
Official Document NFC.19 - Value Added Services Applet Design Proposal
Non-confidential
SW1
67
69
SW2
00
09
Data
Wrong Data Length
Internal Error
Table 36 : Status codes
G.3.6
Custom Status Commands
SW1
01
02
03
03
03
SW2
01
01
01
02
02
Data
Applet not provisioned
Invalid installation parameter length
Invalid tag
Invalid consumerID length
Invalid merchantID length
Table 37 : Custom response codes
G.4
Example APDU Exchange
The following diagram shows communication between the applet and the NFC reader for this example.
V1.0 Page 57 of 66
GSM Association
Official Document NFC.19 - Value Added Services Applet Design Proposal sd APDU exchange example 2
Contactless Reader
Non-confidential
VAS Applet
Select applet(A00000048510010101)
Response(9000)
Get data(Merch ID, Loc ID, Date/Time)
Loyalty & Offers Data SW1 (61) SW2 (00)
Get Response(90C0)
Loyalty & Offers Data SW1 (61) SW2 (00)
Get Response(90C0)
Loyalty & Offers Data SW1 (90) SW2 (00)
Figure 24 : APDU exchange example 2
Annex H Example Applet Structure 3
This is another example for applet installation and some of the APIs used to connect via API
1 to a contactless reader. A common low-level specification proposal, unifying common elements from this and other implementation examples, is intended to be published in the future to follow this high-level document.
H.1
Installation Parameters
Tag (Hex)
9F25
Name
VASappID
Description
Unique identification of the UICC application
“VASappCardlet”. This ID is used by the terminal to select the application.
Like other UICC applets, the VASappCardlet is identified and selected by its application identifier (AID). The standard selection
V1.0 Page 58 of 66
GSM Association
Official Document NFC.19 - Value Added Services Applet Design Proposal
Non-confidential
Tag (Hex) Name Description command 0 is called by the POS system to make the VASappCardlet selected and ready for further APDU processing.
The VASappAID is the application identifier of the GSMA and is related to the mobile operator’s VASappCardlet.
Table 38 : VAS applet AID
H.2
Data Structure
The following table shows additional data objects being used by this implementation:
Name
MeHolderId
Description
Unique identifier of the subscriber as a customer of the merchant. This unique identifier is delivered under the responsibility of the mobile operator and based on the NetworkId and the RetailerId.
CustomerId
LoyaltyCardId
(MyLoyalty)
BasketItemList
(MyBasket)
NetworkId
OpenField
Unique identifier delivered by the merchant (optional).
Identifier of the loyalty card.
Contains the list of items the customer has scanned while in the shop (“self shopping” use case).
A unique identifier of the subscriber delivered by the mobile network.
This is a multi-purpose limited-size field, which is linked to the merchant. The merchant may use this field for any data they want.
This field might be secured (depending on configuration).
RetailerMmiId Unique identifier of the MMI running on top of the service, this value shall be passed to the cardlet during the merchant activation process.
RetailersList This field provides the list of merchants registered within the card concatenated with their current status.
Server Public
Key
Ciphered
Retailer Key
The server wil provide a 2048 bits RSA key to possibly establish a secure channel with the card. This tag will contain sub tags A0 (modulo) and A1 (public exponent).
Contains the value of the symmetric merchant key. This key will be ciphered with the
UICC Public Key.
Ciphered Card
Public Key
Contains the value of the card Public Key used to secure the OpenField key when its access is secured.
Table 39 : Data elements
H.3
API Example
H.3.1
GetData API
The GetData command allows for the retrieving of data stored in the cardlet and can be coded as follows:
Code
CLA
Value
‘00’
Meaning
V1.0 Page 59 of 66
Code
CLA
INS
P1
P2
Lc/Le
DATA
GSM Association
Official Document NFC.19 - Value Added Services Applet Design Proposal
Non-confidential
Code
INS
P1
P2
Lc/Le
DATA
Value
‘CB’
‘0X’
‘00’
‘XY’
XX.XX
Meaning
GetData command
P1 parameter
0x00 : Get all or beginning of data
0x01 : Get more data
P2 parameter
Data length
Tag or Tag List (among 9F30, 9F31, 9F32,
9F33, 9F35, 9F36, 9F37, 9F3A)
Table 40 : VAS applet GetData command
The Tag List shall be wrapped by GP Tag '5C'.
When the GetData response length exceeds 255 bytes, it shall be chained. This is resolved using the following method:
The P1 parameter shall be used to specify whether or not the cardlet must return more data.
P1 shall be coded as defined below:
0x00 if no more data is required
0x01 if more data is required
1st command
Response
2nd command
Response
Last command
Response
Example of a chained GetData command (GetBasket)
00 CB 00 00 02 9F 33 00
BASKET CONTENT PART 1 + 0x63 0x10 MORE DATA AVAILABLE
00 CB 01 00 02 9F 33 00
BASKET CONTENT PART 2 + 0x63 0x10 MORE DATA AVAILABLE
00 CB 01 00 02 9F 33 00
BASKET CONTENT PART 3 + 0x90 0x00 NO MORE DATA AVAILABLE
Table 41 : Example of a chained GetData command (GetBasket)
H.3.2
PutData API
This command allows data transmission to the application.
The PutData command shall be coded according to the following table:
Value
‘00’
‘DB’
‘00’
‘00’
‘XY’
XX.XX
Meaning
PutData command
P1 parameter
P2 parameter
Data length
Data
Table 42 : VAS applet PutData command
V1.0 Page 60 of 66
GSM Association
Official Document NFC.19 - Value Added Services Applet Design Proposal
Non-confidential
When the PutData command length exceeds 255 bytes, it shall be chained. This is resolved using the following method:
The P1 parameter shall be used to specify whether or not the command is chained. P1 shall be coded as defined below:
0x00 if the command is not chained (or last command)
0x01 if the command is chained (meaning not the last command)
Take the following example of a chained PutData command of a basket.
Assumptions:
The basket contains 11 items. For information, an item is coded on 11 bytes.
Basket length = 264 in decimal (0x0108).
The basket is going to be split into two parts: basket_part_1 and basket_part_2. Note that there is no defined rule of how to split the basket. This is up to developer decision.
Lc1 is the length of basket_part_1 and lc2 is the length of basket_part_2.
The resulting APDU command list is as follows:
1st command
2nd command
Last command
Example of a chained PutData command of a Basket
00 DB 01 00 09 9F 23 01 00 9F 33 82 01 08
00 DB 01 00 lc1 basket_part_1
00 DB 00 00 lc2 basket_part_2
Table 43 : Example of a chained PutData command of a Basket – APDU command list
The processing of the complete APDU by the cardlet starts after the reception of the last command.
H.3.3
OpenSession API
Code
CLA
INS
P1
P2
Lc/Le
DATA
Value
‘00’
‘DB’
Meaning
PutData
‘00’ P1 parameter
‘00’
‘XY’
P2 parameter
Length of the following data
TLV sequence stating with optional tag ‘30’ whose contents are given in the table below:
Tag
9f23
9f28
9f36
9f30
4
5
Length Value
1 ‘15’
20
Description
Open session command
Retailer Id
Certif ID Not used in RF mode
MeHolderId Not used in RF mode
V1.0 Page 61 of 66
GSM Association
Official Document NFC.19 - Value Added Services Applet Design Proposal
Table 44 : VAS applet OpenSession command
Non-confidential
H.3.4
CloseSession API
Code
CLA
INS
P1
P2
Lc/Le
DATA
Value
‘00’
‘DB’
‘00’
‘XX’
‘XY’
Tag
9f23
Meaning
PutData
P1 parameter
HCI Push value
Possible values are:
0x00, 0x01, 0x0f
Length of the following data
Length Value
1 ‘16’
Description
Close session command
Table 45 : VAS applet CloseSession command
H.3.5
FlushBasket API
Code
CLA
INS
P1
P2
Lc/Le
DATA
Value
‘00’
‘DB’
‘00’
‘00’
‘XY’
Tag
9f23
9f33
Meaning
PutData
P1 parameter
P2 parameter
Length of the following data
Length Value
1 ‘01’
0
Description
Delete action command
Basket List Item tag
Table 46 : VAS applet FlushBasket command
H.3.6
PutBasket API
This example illustrates a command allowing the creation of a new basket for the retailer identified by RetailerId = 0x1234. The Basket contains 6 articles: 4 water packs identified by bar code 0xFFEEDDCCBBAA (each pack costs 2.37 euros) and 2 milk bottles identified by bar code 0x112233445566 (each bottle costs 1.12 euros). This basket is composed of two items.
Code
CLA
INS
P1
P2
Lc/Le
Value
‘00’
‘DB’
‘0X’
‘00’
‘XY’
Meaning
PUT DATA
P1 parameter
‘01’ more blocks to come
‘00’ last block
P2 parameter
Length of the following data
V1.0 Page 62 of 66
GSM Association
Official Document NFC.19 - Value Added Services Applet Design Proposal
Non-confidential
Code
DATA
Value Meaning
TLV sequence starting with optional tag ‘30’ whose contents are given in the table below:
Tag
9f23
9f33
Length Value
1 ‘00’
XY
Description
Creation command
Basket Items List
Table 47
: VAS applet PutBasket command
H.3.7
GetBasket API
Code
CLA
INS
P1
P2
Lc/Le
DATA
Value
‘00’
‘CB’
‘0X’
‘00’
‘XY’
Tag
9f33
Meaning
GET DATA
P1 parameter
‘00’ get first or only block
‘01’ get next block
P2 parameter
Length of the following data
Length Value
XY
Description
Basket Items List
Table 48 : VAS applet GetBasket command
H.3.8
Self-Activation
A self-activation command is implemented to activate the cardlet on the contactless interface.
The Self Activation command message shall be coded according to the following table:
Code
CLA
INS
P1
P2
Lc/Le
Value
‘00’
‘F2’
‘00’
‘XX’
‘00’
Meaning
Self activation command
P1 parameter
Activation State Btye
GPCLRegistryEntry.STATE_CL_ACTIVATED =
0x01
GPCLRegistryEntry.STATE_CL_DEACTIVATED
= 0x00
Data length
Table 49 : VAS applet Self Activation command
H.3.9
Status Codes
This command could return one of the following status words, according to ISO
V1.0 Page 63 of 66
GSM Association
Official Document NFC.19 - Value Added Services Applet Design Proposal
Non-confidential
SW1
‘90’
‘63
‘6A’
‘69’
‘69’
‘6A’
‘6A’
‘6A’
‘6A’
SW2
‘00’
‘10’
‘80’
‘85’
‘82’
‘88’
‘84
‘88’
‘81’
Data
Data content of the tag or tag list, concatenated.
More data available
Incorrect parameters in the data field
Conditions of use not satisfied
SECURITY_EXCEPTION
NO_MATCHING_TAG
MAX_RECORDS_LIMIT_EXCEEDED
RETAILER_NOT_FOUND
INVALID_ACTION
Table 50 : VAS applet Reponse message
H.4
Example APDU Exchange
The diagram below shows a complete sequence activated by a POS in order to retrieve the three identifiers and the Basket content from the cardlet.
V1.0 Page 64 of 66
GSM Association
Official Document NFC.19 - Value Added Services Applet Design Proposal sd APDU exchange example 3
Contactless Reader
Non-confidential
VAS Applet
Select applet()
Open session()
Response (9000)
Get data(MeHolderId)
MeHolderId + (9000)
Get data(CustomerId)
CustomerId + (9000)
Get data(LoyaltyId)
LoyaltyId + (9000)
Get data(Basket)
Basket + (9000)
Flush Basket()
Response(9000)
Close session()
Response (9000)
Figure 25 : APDU exchange example 3
V1.0 Page 65 of 66
GSM Association
Official Document NFC.19 - Value Added Services Applet Design Proposal
Non-confidential
Annex I Document Management
I.1
Document History
Version Date
1.0 28 Feb
2015
Brief Description of Change Approval
Authority
New proposed non-binding permanent reference document.
Digital Commerce
B2B Wallet
Interfaces
Programme /
PSMC
Editor /
Company
Saurabh Sethi /
GSMA
I.2
Other Information
Type
Document Owner
Editor / Company
Description
Digital Commerce B2B Wallet Interfaces Programme
Saurabh Sethi / GSMA
It is our intention to provide a quality product for your use. If you find any errors or omissions, please contact us with your comments. You may notify us at prd@gsma.com
.
Your comments, suggestions and questions are always welcome.
V1.0 Page 66 of 66
