Value Added Services Applet Design Proposal Version 1.0 · PDF fileGSM Association...

GSM Association Non-confidential

Official Document NFC.19 - Value Added Services Applet Design Proposal

V1.0 of 66

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 of 66

Table of Contents

1 Introduction 4

1.1 Overview 4

1.2 In Scope 4

1.3 Out of Scope 4

1.4 Guiding Principles 5

1.5 Definitions 6

1.6 Abbreviations 6

1.7 References 7

1.8 Conventions 8

2 Use Cases 8

2.1 VAS Applet – Contactless Reader Communication Use Cases 10

2.2 VAS Applet – VAS Plugin Communication Use Cases 11

3 Requirements 13

4 Assumptions 16

5 Architecture 17

5.1 System Architecture 17

5.2 Applet Architecture 19

6 Data Structure 22

7 Applet Installation and Provisioning 25

7.1 Overall Installation Process 25

7.2 Applet Installation Process 26

7.3 Provisioning Process 27

8 Application Programming Interfaces 28

8.1 Command Management 28

8.2 Applet AID Options 29

8.2.1 AID Option 1 29

8.2.2 AID Option 2 29

8.3 HCI Transaction Event Generation 30

8.4 API 1 31

8.5 API 2 32

9 Security 33

Annex A Overall System Architecture 35

Annex B High-Level Use Cases 36

Annex C Provisioning Options 39

C.1 Provisioning Option 2 39

C.2 Provisioning Option 3 40

Annex D Overall Installation Process 41

Annex E Generic AID Option 42

Annex F Example Applet Structure 1 43

F.1 Installation Parameters for an Instance 43

F.1.1 AID Allocation 43

F.2 Tags 43



V1.0 of 66

F.3 Data Structure Metadata 44

F.3.1 Record Availability 44

F.3.2 Title 45

F.4 API Example 45

F.4.1 Select File API 45

F.4.2 GetVASData/1 API 46

F.4.3 GetVASData/2 API 46

F.4.4 ReadVASData API 47

F.4.5 PutVASData API 47

F.4.6 Status Codes 49

F.5 Example APDU Exchange 50

Annex G Example Applet Structure 2 52

G.1 Installation Parameters 52

G.2 VAS Applet Example Data Structure 52

G.2.1 MerchantID 52

G.2.2 LoyaltyIssuerID 52

G.2.3 CouponIssuerID 53

G.2.4 VASAppletCapabilities 53

G.3 API Example 54

G.3.1 Select File API 54

G.3.2 GetVASData API 54

G.3.3 GetVASInternalErrorCode API 55

G.3.4 PutVASData API 56

G.3.5 Status Codes 56

G.3.6 Custom Status Commands 57

G.4 Example APDU Exchange 57

Annex H Example Applet Structure 3 58

H.1 Installation Parameters 58

H.2 Data Structure 59

H.3 API Example 59

H.3.1 GetData API 59

H.3.2 PutData API 60

H.3.3 OpenSession API 61

H.3.4 CloseSession API 62

H.3.5 FlushBasket API 62

H.3.6 PutBasket API 62

H.3.7 GetBasket API 63

H.3.8 Self-Activation 63

H.3.9 Status Codes 63

H.4 Example APDU Exchange 64

Annex I Document Management 66

I.1 Document History 66

I.2 Other Information 66



V1.0 of 66

1 Introduction

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 of 66

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

shown in ‎Annex C.

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, ‎Annex G

and ‎Annex H.

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 of 66

1.5 Definitions

Term Description

Closed

loop

coupons

Proprietary coupons that are issued and redeemed in a closed ecosystem (the offer

issuer and the offer awarder have a direct relationship).

Open loop

coupons

Coupons issued by one or more offer issuers and redeemable at one or more offer

awarders without there being an explicit relationship between them.

Service

Provider

app

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

(NFC.15 ‎[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

(NFC.15 ‎[2]

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 Description

AID Application Identifier

APDU Application Protocol Data Unit

API Application Programming Interface

EAN International Article Number

ELF Executable Load File

HCE Host Card Emulation

HCI Host Controller Interface

MNO Mobile Network Operator

OTA Over The Air

POS Point of Sale

PPSE Proximity Payment System Environment

RAM Remote Application Management

RFM Remote File Management



V1.0 of 66

Term Description

SCP Secure Channel Protocol

SD Security Domain

SDK Software Development Kit

SE Secure Element

SP Service Provider

SP UI Service Provider User Interface

SS Secure Storage

SW Status Word

TSM Trusted Service Manager

UI User Interface

USD Utility Security Domain

VAS Value Added Service

1.7 References

Ref Doc Number Title

[1] RFC 2119

“Key words for use in RFCs to Indicate Requirement Levels”, S.

Bradner, March 1997

http://www.ietf.org/rfc/rfc2119.txt

[2] NFC.15

GSMA: Mobile Commerce NFC Coupons and Loyalty Acceptance -

Technical Proposal, Version 1.0, 01 July 2014

http://www.gsma.com/digitalcommerce/wp-

content/uploads/2014/07/NFC.15-Version-1.0-Mobile-Commerce-

NFC-Coupons-and-Acceptance-Technical-Proposal.pdf

[3] NFC.17 NFC.17 CR1001 New PRD - Core Wallet API

Confidential document.

[4] ISO/IEC 7816 “Identification cards -- Integrated circuit cards”

http://www.iso.org/ and http://www.iec.ch/

[5] ISO/IEC 14443

ISO 14443 defines a protocol stack from the radio layer up to a

command protocol


[6] SIM-OMA

SIMAlliance Open Mobile API Specification v2.05

http://www.simalliance.org/en/se/se_technical/open-mobile-api-

specification-v205_hrmcp1sq.html

[7] GS1-DCM “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

reference to GS1 specifications. Among those, ISO/IEC 15418 ‎[8] standardises GS1 Application Identifiers (including AI for

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.

http://www.ietf.org/rfc/rfc2119.txt

http://www.gsma.com/digitalcommerce/wp-content/uploads/2014/07/NFC.15-Version-1.0-Mobile-Commerce-NFC-Coupons-and-Acceptance-Technical-Proposal.pdf



http://www.iso.org/

http://www.iec.ch/

http://www.iso.org/

http://www.iec.ch/

http://www.simalliance.org/en/se/se_technical/open-mobile-api-specification-v205_hrmcp1sq.html

http://www.simalliance.org/en/se/se_technical/open-mobile-api-specification-v205_hrmcp1sq.html

http://www.gs1.org/docs/gsmp/b2c/Digital_Coupon_Management_i1.pdf



V1.0 of 66

Ref Doc Number Title

i1.pdf

For the latest GS1 Digital Coupons Standard, please visit

http://www.gs1.org/gsmp/kc/b2c

[8] ISO/IEC 15418

Information technology -- Automatic identification and data capture

techniques -- GS1 Application Identifiers and ASC MH10 Data

Identifiers and maintenance


[9] ITU-T E.212

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

RFC2119 ‎[1].

2 Use Cases

NFC.15 ‎[2] highlighted a broad set of use cases for loyalty and couponing, including open

and closed loop coupons. These use cases serve as the basis of the NFC.15 ‎[2] overall

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.

http://www.gs1.org/docs/gsmp/b2c/Digital_Coupon_Management_i1.pdf

http://www.gs1.org/gsmp/kc/b2c

http://www.iso.org/

http://www.iec.ch/

http://www.itu.int/dms_pub/itu-t/opb/sp/T-SP-E.212B-2013-PDFE.pdf

http://www.itu.int/dms_pub/itu-t/opb/sp/T-SP-E.212B-2013-PDFE.pdf



V1.0 of 66

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

Secure any VAS data stored on a secure element

based applet so that relevant data can be accessed by

the corresponding application.

Read data Read data from a specified record on the applet.

Write data Write data to a specified record on the applet.

VAS plugin

communication

Communication with the VAS plugin, primarily to store VAS data and

provide Host Controller Interface (HCI) event feedback.

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.

MNO / SP TSM

communication

Communication with the TSM Infrastructure for maintenance and the

creation/deletion of new records.

Create records Create records on the VAS applet. One record per

merchant.

Delete records Delete records on the VAS applet.

uc Applet use cases

VAS applet

VAS plugin

communication

Contactless reader

communicationStorage of VAS data

MNO / SP TSM

communication

Create records

HCI ev ents

Read data

Delete records

Write data

Security of VAS data

Read/Write VAS

data

GetVASData



V1.0 of 66

Table 1: Applet functional use case descriptions

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.

Figure 2: Applet – Contactless Reader communication use cases

Component Description

Authentication

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.

Get VAS Data


Target: VAS Applet

Description: Retrieval of data from the VAS applet. Includes the capability

to retrieve coupon data or loyalty data.

uc Applet use cases 1

Establish

communication

Get VAS Data

Put VAS Data

VAS AppletContactless reader

Get Loyalty Data Get Other DataGet Coupon Data

Authentication

Get Basket Data



V1.0 of 66


Get Coupon Data /

Get Loyalty Data /

Get Basket Data /

Get Other Data


Target: VAS Applet

Description: Retrieval of coupon/loyalty data/basket data/other data from

the VAS applet.

Establish

communication


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 of 66

Figure 3: VAS Applet – VAS Plugin communication use cases


Get VAS Data

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.

Get Coupon Data /

Get Loyalty Data /

Get Basket Data /

Get Other Data


Target: VAS Applet

Description: Retrieval of coupon/loyalty data/basket data/other data from

the VAS applet.

Establish Source: VAS Manager/Plugin

uc Applet use cases 2

Establish

communication

Put VAS Data

Get VAS Data

Listen for HCI

ev ents

VAS AppletVAS Manager / Plugin

Get Loyalty Data Get Other DataGet Coupon Data

Authentication

Get Basket Data

Records

management

Applet data

management



V1.0 of 66


communication Target: VAS Applet

Description: Open a communication channel between the Plugin and the

VAS applet.

Authentication


Target: VAS Applet

Description: Enables the plugin to deliver data to the VAS applet following

authentication/security handshake.

Listen for HCI

events

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.

Put VAS Data


Target: VAS Applet

Description: The plugin sends data to a record within the applet instance.

Records

management


Target: VAS Applet

Description: The plugin ensures that VAS data sent by individual UI apps is

transferred to the appropriate record in the applet.

Applet data

management


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 Storage −

CustomerID

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.

REQ 2 Storage −

LoyaltyID

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.

REQ 3 Storage −

MerchantID

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.

REQ 4 Storage − Coupon[] SHOULD be stored on the applet/cardlet. The coupon

format can be proprietary or it can be a serialized Global Coupon



V1.0 of 66

Req.

no.


Coupon[] Number as defined in GS1 DCM ‎[7].

REQ 5 Storage −

OpenField

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 Storage −

Basket[]

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.

REQ 7 Storage −

Status

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].

REQ 8 CustomerID CustomerID MAY be unique to a specific merchant.

REQ 9 CustomerID CustomerID MAY be common to a group of merchants.

REQ 10 CouponID The CouponID MAY be serialized and fully unique per customer.

REQ 11 Open loop

coupons

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 MerchantIDs (so each

CouponID can be associated with any number of MerchantIDs,

though this SHOULD be capped at a certain maximum number due to

VAS applet memory limitations).

REQ 12 Closed loop

coupons

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.

REQ 13 Coupon

activation

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.

REQ 14 MerchantID MerchantID MUST be communicated by the POS to the applet so

the applet can return useful data.

REQ 15 MerchantID

The VAS applet SHOULD categorise all of the data storage by

MerchantID. This is to minimise data duplication, and also to

maintain data abstraction.

REQ 16 Online POS A POS MAY or MAY NOT be online (connected to the internet) to

approve offers.

REQ 17 POS integration The POS SHOULD be integrated with the contactless terminal and

API 1 to communicate effectively with the applet.

REQ 18 API 1 The applet SHOULD support API 1 as defined in NFC.15 ‎[2].

REQ 19 API 2 The applet SHOULD support API 2 as defined in NFC.15 ‎[2].

REQ 20 API framework The applet SHOULD conform to the API framework outlined in

NFC.17 ‎[3].



V1.0 of 66

Req.

no.


REQ 21 HCI events The VAS applet MUST pass all HCI events back to the VAS plugin.

REQ 22 SIM resources The VAS applet implementation SHALL minimise impacts on memory,

storage and processing requirements.

REQ 23 Security The VAS applet MAY provide appropriate security of data to and from

the applet.

REQ 24 Security domain

instance

The VAS applet MUST be instantiated only once and it MUST be

instantiated in a security domain (SD).

REQ 25 Applet pre-

loaded on SIM

The VAS applet MAY be pre-loaded on the SIM. It MAY be

instantiated at a later time.

REQ 26 Applet

ReadWrite

The VAS applet MAY allow both read/write modes to write data back

to the data fields.

REQ 27 VAS applet

SecureStorage

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 Cryptography

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.

REQ 30

Cryptography –

Multi key

management

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.

REQ 31

Cryptography –

Multi crypto

algorithm

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

Simplify

integration of

services

The overall system solution SHOULD simplify the integration of new

services between third parties.

REQ 34 Standard

solution The overall system solution SHOULD be based on standard solutions.

REQ 35 Avoid

fragmentation

The overall system solution SHOULD avoid requiring bespoke

solutions for every merchant i.e. one-to-one integration.

REQ 36 Performance 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 of 66

Req.

no.


customer being at the Point of Sale.

REQ 38 Support multiple

regions The VAS applet MAY be used across multiple regions.

REQ 39 Open market

handsets

The VAS applet, and the overall solution, SHOULD support open

market handsets.

REQ 40 Publication The SP SHOULD be able to publish to the VAS applet the coupons

selected by the user for redemption.

REQ 41 Publication The SP SHOULD be able to publish the LoyaltyID on the VAS

applet.

REQ 42 Publication The SP SHOULD be able to publish the CustomerID on the VAS

applet.

REQ 43 Publication The SP SHOULD be able to define if and which security mechanisms

have to be applied to the publication of coupons.

REQ 44 Publication Coupons/LoyaltyID/CustomerID MAY be unpublished when

explicitly requested by the SP.

REQ 45 Expiry Coupons may expire after a certain date/time has passed.

REQ 46 Coupon burning

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.

REQ 47 Publication 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 of 66

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 ‎[2] (and shown in ‎Annex A).



V1.0 of 66

Figure 4: System architecture


VAS Applet

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).

VAS

Plugin/Manager

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.

VAS SDK

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.

MNO Wallet App

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 of 66


Apps Any app (Service Provider User Interface) residing on the handset that

wishes to interface to the wallet.

MNO Wallet App

Server

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 used by the PED/terminal to extract information from the value added

services applet.

API 2 Application Protocol Data Unit (APDU) level API for access to the applet

from within the handset.

API 3 High-level API/software development kit (SDK) used by UI apps to access

the VAS applet.

API 4 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 of 66

Figure 5: Applet architecture

The architecture consists of the following components:


Communication

Interface

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.

APDU Processing Execution of the incoming APDU request. Request execution only happens if

the appropriate permissions are in place.

Permissions for

Records

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.

Data

Transformation

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 of 66


interface (API 1).

VAS Plugin A background service provided by the applet developer that communicates

with the VAS applet over API 2.

MNO TSM 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,

refer to section ‎8.4.

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 of 66

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

in section ‎8.3.

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 of 66

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

identifiers mentioned within the data structure, NFC.15 ‎[2] highlighted the relevant GS1

numbers that could be used ‎[7]. The use of GS1 fields is continued to be supported, and

other, proprietary fields are also supported for these identifiers.

‎Table 7 provides data structure attributes for each of the records:

Name Description Length

ID The applet SHOULD ensure that this field is unique. 2 bytes

Title User friendly identifier for the record. Optional. 2 – 60

bytes

PERM Permission to access a record for reading and writing data. 4 bytes



V1.0 of 66

Name Description Length

DATA Total payload data of the record. This can store any VAS data to be

sent to the contactless reader (either encrypted or unencrypted).

Flexible

STATUS Status of the data being transmitted. Optional

Possible values: Active, Presented, Burned, Expired.

2 bytes

Table 7: Data structure attributes

‎Table 8 provides example elements within the proposed data structure.

Name Elements Description Length

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

record it seeks. See section ‎8.4 for details.

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.

2 – 60

bytes

Loyalty /

Enterprise

Loyalty identifier for a merchant. Used in special cases of

coalition loyalty.

1 – 30

bytes

Merchant Merchant identifier.

1 – 30

bytes

DATA

Customer

ID

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

Location ID Identifies the location where the coupon/loyalty discount was

redeemed.

8 bytes

Operator

ID

Unique identifier of the end user delivered by the mobile

operator.

2 bytes

Coupon

data

Data stored entitling the holder to a discount off a particular

product or service.

20-100

bytes

Other VAS

data

Other data similar to coupon data, e.g. loyalty data. 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 of 66

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.

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

End user

downloads

and installs

SP application

End user

opens app

Is plugin

installed?

Is applet

installed?

New record is

created for SP

End user

downloads

and installs

plugin

Applet is

downloaded

and installed

on UICC

Applet instance

is created

Service is ready

to be used

No

Yes

Yes

No

Additional checks included:

- Is mobile device NFC compatible?

- Is UICC NFC compatible?

- Is OS version compliant with plugin?

- Is mobile operator compliant with plugin?

Additional check included:

- Are mobile data services available?

Additional check included:

- Is NFC activated on the mobile device?



V1.0 of 66

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 of 66

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”.

sd Applet installation process

Plugin MNO / SP TSM UICC

opt

opt

Package keys()

Push applet()

Eligibil ity check()

Instance creation()

Personalise data()

Send set of commands to

install applet package key()

SP keys for cryptography()

Create Security

Domain and load

package()

Bind to plugin()



V1.0 of 66

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 of 66

Supported Command Interfaces

GRANT

management

OTA CONTACT CONTACTLESS

CREATE Y N N

WRITE/DELETE Y Y N

READ Y Y Y

DELETE ALL Y N N

Table 9: Supported command interfaces

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 of 66

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.

Figure 12: HCI transaction event workflow

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()

Analyse data status()

Send data()

Notification that app data has changed()

Update with data status()

Notification that app

data has changed()



V1.0 of 66

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.

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.

sd API 1 APDU exchange process

EPOS Contactless Reader VAS Applet

Offer User

loop DataTransfer

[length = 0 -> transfer all data]

Offer User presents

phone to Contactless

Reader.

The Contactless

Reader can request a

full AID or a partial

AID (RID) match.

The Contactless

Reader selects a

record or entry.

The length of the

record is requested by

the Contactless

Reader, and returned

by the Applet.

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

Send static

information back

to the applet.

Response(AID/RID, status)

VASTokenList(data)

API 1 Select(AID/RID)

TapPhone()

Response(Data(length(opt)))

GetResponse()

Select(Data(length(opt)))

Response TokenData()

GetVASData(MerchantID,

LocationID (opt), Date/Time (opt))

Response(Success)

Prop API readCoupon()

PutVASData()



V1.0 of 66

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 of 66

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

sd API 2 APDU exchange process

VAS Manager /

SP App

VAS Applet

Response(AID/RID, status)

HCI event transaction()

CreateRecordMerchantID(MerchantID)

GetVASDataStatus(MerchantID)

PutVASData(MerchantID, data)

GetVASData(MerchantID)

API 2 select(AID/RID)

API 2 select(AID/RID)

Response(Record created)

Response(VASDataStatus)

Response(status)

Response(TokenData)



V1.0 of 66

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 of 66

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 of 66

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 of 66

Figure 18: Coupon use case steps

‎Figure 19 provides a high-level overview of the loyalty use case process.



V1.0 of 66

Figure 19: Loyalty use case steps



V1.0 of 66

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 of 66

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 of 66

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.

Figure 22: Overall installation process

Google PlayStoreSP app

End user downloads and installs SP app

from PlayStore

OpenSP app

Is NFC enabled?

Is applet installed?

SP app home screen

Yes

Yes

Yes

Yes

No No No

No No

Sorry, your mobile is not

NFC compatible.

Yes

Yes

Sorry, to use this service, you

need Android v4.1 or above.

Sorry, service available for

‘MNO 1’ customers only.

Yes

Install and persoapplet

No

To finalise the installation of

your NFC services, switch

on 3G/4G network.

NoYes

Yes

NFC is disabled. Do you want to

enable it?

End user activates NFC

If Error = UICC_not_compliant or Handset_not_complaintor Offer_not_compliant

Display recommended

notification message to the

end user

Yes Yes

To use NFC services,

download NFC plugin for apps from PlayStore.

Yes

Google PlayStoreNFC plugin for apps

End user downloads and installs NFC

plugin for apps from PlayStore

NFC Services, Installation successful

NoNo

NoYes No

Success

Error

NoYes

No

NoYes

NoYes

Check device configuration

(If you don’t have filtering enabled on PlayStore.)

Error Cases

Is Android version v4.1 or above?

Has UICC / SIM card changed?

Do you wish to install NFC services?

Is NFC plugin for apps installed?

Is mobile data available?

Is Android v4.1 or above?

Is mobile device NFC?

Does operator support

services?

Notification / SMS

End user activates

3G/4G

YesNo



V1.0 of 66

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 identifier of the mobile operator’s VAS applet. The

encoding of the VASAppAID is defined according to ‎Table 10 taken from NFC.15 ‎[2]:

Meaning AID-Coding

RID

This RID is internationally unique and reserved for applications

according to this proposal.

0xA0:0x00:0x00:0x05:0x59

Application Code 0x00:0x01

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.

0xFX:0xXX

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.

0xFX:0xXX or 0xFF:0xXX

Application Provider Field (optional, length 0-5)

Additional provider specific data.

0xXX:0xXX:0xXX:0xXX:0xXX

Table 10: VAS applet AID



V1.0 of 66

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 Description Parameters Example

Storage Size

Tag: 0x81

Available

storage space

for storing

records.

Allocated in

fixed-size units

called pages.

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].

This

example

asks for a

16kB pool

split into

128-byte

pages:

81 04 40

00 00 80

HCI

Transaction

Tag: 0x84

Enables the

generation of

HCI transaction

events at the

end of

contactless

sessions.

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.

This

example

enables

HCI

events:

84 01 01

Delete

all/Create

availability

Tag: 0x82

These

parameters

dictate which

interfaces will

accept

CREATE/DELE

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



V1.0 of 66


TE ALL

commands.

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

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


Record

availability

Tag: 0x81

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

Example:

81 03 99

0C A8



V1.0 of 66

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 Length Value

82 From 1 to 60 UTF-8 TITLE

Table 13: TITLE structure

F.4 API Example

F.4.1 Select File API

Field

name

Type Length Value Description

CLA Byte 1 0x00 Instruction class: No secure

messaging or no secure

messaging indication

INS Byte 1 0xA4 Select File

P1 Byte 1 0x04 Direct selection by dedicated

file name (Data field =

dedicated file name)

P2 Byte 1 0x00 First record, Return FCI,

optional template

Lc UInt8 1 0x10 Length of the AID

Data Lc 0xF0:0x00:0x00:0x54:0x49

:0xFF:0xF0:0xFF:0x39:0x5

VAS Applet AID

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.



V1.0 of 66

Field

name


9:0x43:0x24:0x20:0x00:0x

20:0x00

Le Byte 1 0x00 No maximum length

Table 14: VAS applet Select File command

Field

name


Status

Code

Short 2 0xXX:0xXX SW1 SW2

e.g. 0x90:0x00 Operation successfully

completed

e.g. 0x6A:0x82 File not found

Table 15: VAS applet Select File response

F.4.2 GetVASData/1 API

Field

name





INS Byte 1 0xA5 Custom instruction:

GetVASData

P1 Byte 1 0x00

P2 Byte 1 0x00

Lc UInt8 1 0x02 Length of Data field

Data TagList Var. 0x00:0x01 List of Tags required. Note:

Specific tag list to be

determined.


Table 16: VAS applet GetVASData/1 command

F.4.3 GetVASData/2 API

Field

name





INS Byte 1 0xCA Custom instruction:

GetVASData

P1 Byte 1 0x00

P2 Byte 1 0x00



V1.0 of 66

Field

name



Table 17: VAS applet GetVASData/2 command

F.4.4 ReadVASData API

Field

name





INS Byte 1 0xCA Custom instruction:

GetVASData

P1 Byte 1 0x01

P2 Byte 1 0x00

Lc UInt8 1 0x20 Length of Data field

Data TagList Var. List of Tags required. Note:


determined.


Table 18: VAS applet ReadVASData command

F.4.5 PutVASData API

This command overwrites the contents of the currently selected record.

Field

name

Value Description

CLA 0x80

INS 0xDA

P1 0x00 or 0x01 or 0x02 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

P2 0x00 or 0x01 Controls the format of the payload. See below for further

info. When P1 != 0, P2 must be 0.

LC Var No maximum length

DATA

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.

LE -

Table 19: VAS applet PutVASData command

The payload can take different forms depending on the value of P1 and P2.



V1.0 of 66

P1 P2 Description

0x00 0x00 Use “Format1” described below.

0x00 0x01 Use “Format2” described below.

0x01 0x00 The payload contains a chunk of data to be written to the record.

0x02 0x00 The payload contains a chunk of data to be written to the record.

0xXX 0xXX 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 to 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 Length Value Presence Description

0x81 2 Size of data M Total size of the data to be written,

expressed as a 2-byte integer in big endian

form.

0x82 4 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 of 66

Tag Length Value 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.

0x83 Var 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.

SW1 SW2 Data

0x90 0x00 Operation completed successfully

0x6E 0x00 Wrong CLA

0x6D 0x00 Wrong INS

0x6A 0x86 Wrong P1/P2

0x67 0x00 The number of payload bytes in a command is

not correct, or the value of Le is too short to

carry the entire response.

0x6A 0x87 LC inconsistent w.r.t. P1/P2

0x69 0x82 Security error

0x68 0x82 Secure messaging not supported. It means that

an APDU related to security was received but

the applet did not expect secured commands.

0x65 0x81 Internal storage error

0x6A 0x88 There is no selected record



V1.0 of 66

SW1 SW2 Data

0x6A 0x80 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.

0x69 0x85 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 block-

aligned).

0x6A 0x84 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.

0x69 0x86 The selected record is not writable over the

current interface

0x6A 0x81 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 of 66

Figure 23: APDU exchange example 1

sd APDU exchange example 1

Step 2 of extracting

data from UICC is

successful.

Step 1 of extracting

data from UICC is

successful.

Read the data in

the APDU

32 bytes of data is

read successfully.

Extract data from

UICC - Step 1.

Extract data from

UICC - Step 2.

Select an applet

upon locating a

matching AID.

Applet is selected

successfully.

Contactless Reader UICC

Overwrites the

contents of the

selected record

Record written over

successfully

Response(xx{N}9000)

Response(xx{N}9000)

Response(xx{32}9000)

ReadVASdata(80CA010020)

Response(00209000)

PutVASdata(80DA0001)

GetVASData2(80CA000002)

Response(00019000)

GetVASData1(80A5000002000102)

Select applet

(00A4040010F000005449FFF0FF395943242000200100)



V1.0 of 66

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 AID-Coding

RID

This RID is internationally unique and reserved for applications

according to this proposal

0xA0:0x00:0x00:0x04:0x85

Application Code 0x10:0x01:0x01:0x01


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 Type Length Value

TAG Byte 2 0xDF:0x31

LEN 1 Max 8 Bytes

VALUE Byte variable Format BCD

Table 25: MerchantID TLV structure

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 of 66

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.



LEN 09 1 Max Length 08 Bytes


Table 26: LoyaltyIssuerID TLV structure

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].



LEN 1 Max Length 09 Bytes


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.

Table 27: CouponIssuerID TLV structure

G.2.4 VASAppletCapabilities

The data packet defining the VAS applet capabilities is defined as follows:



LEN 1 2 bytes fixed length

VALUE Byte variable Format Binary

Table 28: VASAppletCapabilities TLV structure



V1.0 of 66

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

Field

name





INS Byte 1 0xA4 Select File

P1 Byte 1 0x04

Direct selection by dedicated

file name (Data field =

dedicated file name)

P2 Byte 1 0x00 First record, Return FCI,

optional template

Lc UInt8 1 0x09 Length of the AID

Data Lc 0xA0:0x00:0x00:0x04:0x85

:0x10:0x01:0x01:0x01 VAS Applet AID


Table 29: VAS applet Select File command

Field

name


Status

Code

Short 2 0xXX:0xXX SW1 SW2


completed

e.g. 0x6A:0x82 File not found

Table 30: VAS applet Select File response

Any response other than 0x90:0x00 will terminate the select operation to a response

described in ‎Table 30.

G.3.2 GetVASData API

Field

name


CLA Byte 1 0x90

Instruction class: No secure



INS Byte 1 0x50 Custom instruction:

GetVASData



V1.0 of 66

Field

name


P1 Byte 1 0x00

P2 Byte 1 0x00

Lc UInt8 1 0xXX Length of Data field

Data TagList Var.

List of Tags required. Note:


determined.


Table 31: VAS applet GetVASData command

Field

name


Data 0..255

Status

Code Short 2

0xXX:0xXX SW1 SW2


completed

e.g. 0x61:0x00 More data to follow

e.g. 0x67:0x00 Wrong data length

e.g. 0x6A:0x80 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 INS P1 P2 Lc Data Le

90 C0 00 00 00 <none> 00

Table 33: Get Response Data

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


CLA Byte 1 0x90






V1.0 of 66

Field

name



GetVASInternalErrorCode

P1 Byte 1 0x00

P2 Byte 1 0x00

Lc

Data


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


CLA Byte 1 0x90





PutVASData

P1 Byte 1 0x00

P2 Byte 1 0x00

Lc Byte 1 0xXX Length of Data field

Data 0..255 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 SW2 Data

90 00 Successful Execution of Command

61 00 More data to follow



V1.0 of 66

SW1 SW2 Data

67 00 Wrong Data Length

69 09 Internal Error

Table 36: Status codes

G.3.6 Custom Status Commands

SW1 SW2 Data

01 01 Applet not provisioned

02 01 Invalid installation parameter length

03 01 Invalid tag

03 02 Invalid consumerID length

03 02 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 of 66


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) Name Description

9F25 VASappID 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


VAS AppletContactless Reader

Get Response(90C0)

Loyalty & Offers Data SW1 (90) SW2 (00)

Get Response(90C0)

Response(9000)


Get data(Merch ID, Loc ID, Date/Time)

Select applet(A00000048510010101)




V1.0 of 66

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.


H.2 Data Structure

The following table shows additional data objects being used by this implementation:

Name Description

MeHolderId 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 Unique identifier delivered by the merchant (optional).

LoyaltyCardId

(MyLoyalty)

Identifier of the loyalty card.

BasketItemList

(MyBasket)

Contains the list of items the customer has scanned while in the shop (“self

shopping” use case).

NetworkId A unique identifier of the subscriber delivered by the mobile network.

OpenField 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

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).

Ciphered

Retailer Key

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 Value Meaning

CLA ‘00’



V1.0 of 66

Code Value Meaning

INS ‘CB’ GetData command

P1 ‘0X’ P1 parameter 0x00 : Get all or beginning of data

0x01 : Get more data

P2 ‘00’ P2 parameter

Lc/Le ‘XY’ Data length

DATA XX.XX 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

Example of a chained GetData command (GetBasket)

1st command 00 CB 00 00 02 9F 33 00

Response BASKET CONTENT PART 1 + 0x63 0x10 MORE DATA AVAILABLE

2nd command 00 CB 01 00 02 9F 33 00

Response BASKET CONTENT PART 2 + 0x63 0x10 MORE DATA AVAILABLE

Last command 00 CB 01 00 02 9F 33 00

Response 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:

Code Value Meaning

CLA ‘00’

INS ‘DB’ PutData command



Lc/Le ‘XY’ Data length

DATA XX.XX Data

Table 42: VAS applet PutData command



V1.0 of 66

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:

Example of a chained PutData command of a Basket

1st command 00 DB 01 00 09 9F 23 01 00 9F 33 82 01 08

2nd command 00 DB 01 00 lc1 basket_part_1

Last command 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 Value Meaning

CLA ‘00’

INS ‘DB’ PutData



Lc/Le ‘XY’ Length of the following data

DATA TLV sequence stating with optional tag ‘30’ whose contents are given in

the table below:

Tag Length Value Description

9f23 1 ‘15’ Open session command

9f28 4 Retailer Id

9f36 5 Certif ID Not used in RF mode

9f30 20 MeHolderId Not used in RF mode



V1.0 of 66

Table 44: VAS applet OpenSession command

H.3.4 CloseSession API

Code Value Meaning

CLA ‘00’



P2 ‘XX’ HCI Push value Possible values are:

0x00, 0x01, 0x0f


DATA Tag Length Value Description

9f23 1 ‘16’ Close session command

Table 45: VAS applet CloseSession command

H.3.5 FlushBasket API

Code Value Meaning

CLA ‘00’






9f23 1 ‘01’ Delete action command

9f33 0 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 Value Meaning

CLA ‘00’

INS ‘DB’ PUT DATA

P1 ‘0X’ P1 parameter

‘01’ more blocks to come

‘00’ last block





V1.0 of 66

Code Value Meaning

DATA TLV sequence starting with optional tag ‘30’ whose contents are given in

the table below:

Tag Length Value Description

9f23 1 ‘00’ Creation command

9f33 XY Basket Items List

Table 47: VAS applet PutBasket command

H.3.7 GetBasket API

Code Value Meaning

CLA ‘00’

INS ‘CB’ GET DATA

P1 ‘0X’ P1 parameter

‘00’ get first or only block

‘01’ get next block




9f33 XY 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 Value Meaning

CLA ‘00’

INS ‘F2’ Self activation command


P2 ‘XX’ Activation State Btye

GPCLRegistryEntry.STATE_CL_ACTIVATED =

0x01

GPCLRegistryEntry.STATE_CL_DEACTIVATED

= 0x00

Lc/Le ‘00’ 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

specifications ‎[4]:



V1.0 of 66

SW1 SW2 Data

‘90’ ‘00’ Data content of the tag or tag list, concatenated.

‘63 ‘10’ More data available

‘6A’ ‘80’ Incorrect parameters in the data field

‘69’ ‘85’ Conditions of use not satisfied

‘69’ ‘82’ SECURITY_EXCEPTION

‘6A’ ‘88’ NO_MATCHING_TAG

‘6A’ ‘84 MAX_RECORDS_LIMIT_EXCEEDED

‘6A’ ‘88’ RETAILER_NOT_FOUND

‘6A’ ‘81’ 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 of 66



VAS AppletContactless Reader

Flush Basket()

MeHolderId + (9000)

Get data(Basket)

Response (9000)

Get data(LoyaltyId)

Close session()

Open session()

Get data(CustomerId)

Basket + (9000)

Get data(MeHolderId)

LoyaltyId + (9000)

Response (9000)

Response(9000)

CustomerId + (9000)

Select applet()



V1.0 of 66

Annex I Document Management

I.1 Document History

Version Date Brief Description of Change Approval

Authority

Editor /

Company

1.0 28 Feb

2015

New proposed non-binding

permanent reference document.

Digital Commerce

B2B Wallet

Interfaces

Programme /

PSMC

Saurabh Sethi /

GSMA

I.2 Other Information

Type Description

Document Owner Digital Commerce B2B Wallet Interfaces Programme

Editor / Company 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 [email protected].

Your comments, suggestions and questions are always welcome.

mailto:[email protected]

Value Added Services Applet Design Proposal Version 1.0 · PDF fileGSM Association...

Documents

Transcript of Value Added Services Applet Design Proposal Version 1.0 · PDF fileGSM Association...