#Apple VAS Template

Optional, restricted functionality - Confidential information

This functionality is available only for customers who have signed a specific license agreement, and its documentation can be provided only to customers who are under NDA with SpringCard and/or with the owner of the technology.

Please contact SpringCard Sales Team for detailed information and pricing options.

#Description

Read data from an iOS mobile phone using ECP and the Apple VAS protocol.

On iOS, the Apple Wallet application allows users to organize their boarding passes, tickets, gift cards, and loyalty cards. Management of the passes is performed through the PassKit framework. NFC-enabled passes could be transmitted to a remote application through NFC, using the Apple Pay Value Added Services protocol (Apple VAS).

Once configured using this template, a SpringCore Smart Reader is able to run the Apple VAS secure transaction on its own, and transmit the data in the plain to the host.

#Remark

As per Apple requirements, Apple VAS should only run on top of a NFC reader that implements the Apple VAS Enhanced Contactless Polling (ECP), which is an Apple-proprietary extension of EMV and ISO/IEC 14443-A (NFC-A).

When configuring the Apple VAS template in the Smart Reader, always enable ECP in the “NFC-A specific options” configuration register and EMV compliance in the “NFC/RFID HF compliance in poller mode” configuration register.

The SpringCore firmware is only suitable to read Apple Pay VAS data, not to run Apple Pay transactions. SpringCore devices are not payment terminals.

#Data, keys, and transaction flow

#Merchant

A service provider or merchant subscribes to the Apple VAS service and develops his identification service (loyalty app, access control, or virtually any other identification scheme).

The service provider is primarily identified by its Merchant Name, which is constructed as an URN (example: "com.springcard.vas-demo").

Inside the Apple VAS NFC transaction, the service provider is identified by its Merchant ID which is the hash of the Merchant Name:

​ Merchant ID = SHA256 ( Merchant Name )

The service provider generates a 256-bit elliptic-curve key-pair over the P-256 curve: { K_PRI:MERCHANT, K_PUB:MERCHANT }.

The key-pair is identified by a 4-byte Key ID which is the beginning of the hash of its public key’s X coordinate:

​ Key ID = SHA256 ( X coordinate of K_PUB:MERCHANT ) [0..3]

#User data

The user of the service (customer of the merchant) receives a unique Apple VAS pass, by the mean of a .pkpass file. The file may be sent to the user either through email, SMS, downloaded from a web site, or provided by an application running in the mobile itself.

The .pkpass file is processed by the smartphone’s Wallet application, and the pass it contains is added to the list of available passes.

Seen from the NFC interface, the only relevant data in the pass are:

• The Merchant Name to compute the Merchant ID,
• The merchant’s public key K_PUB:MERCHANT,
• A plain message that is the identifier of the user, to be transmitted to the compliant readers.

#Configuration of the reader

To run its part of the NFC transaction, the reader has to be configured with:

• The Merchant ID,
• The Key ID,
• The Private key K_PRI:MERCHANT.

#Apple VAS NFC transaction

The mobile sends to the reader its message and its current timestamp in a single cryptogram.

The cryptogram is protected by a cryptographic secret key. Only a reader knowing the right private key may decipher the cryptogram and recover the message and the timestamp. To prevent replay attacks, the host is responsible to verify that the timestamp provided by the mobile is coherent with its current date and time before accepting the message.

#Data transmitted by the Smart Reader to the host

The reader processes the cryptogram and sends to the host:

• message in field TagData,

• timestamp in field TagDetails.

Notes

1. The reader does not check that the timestamp is valid. This is the host’s responsibility, to protect against replay attacks.

2. When the reader is configured for keyboard emulation (RFID Scanner), sending of the timestamp is optional. This configuration doesn’t provide any protection against replay attacks.

#Understanding the configuration

The Apple VAS template is able to support 2 distinct Merchant, or 2 Private keys within the same Merchant.

Therefore, the Merchant-related registers are doubled:

• Data for the 1st Merchant are stored in registers 6 to 8,

• Data for the 2nd Merchant are stored in registers 9 to B.

Just leave registers 9 to B empty if you have a single Merchant configuration.

#Registers

This Template uses 10 configuration registers:

Alias	Offset	Name	Description
LKL	0	Lookup List	Set to D1 to use this Template
ID1	6	Merchant ID	Merchant ID of the 1st (or only) merchant. This is SHA256(Merchant Name).
URL1	7	Merchant URL	Not used.
KEY1	8	Merchant’s Private Key	See details below
ID2	9	Merchant ID (second)	Merchant ID of the 2nd merchant. This is SHA256(Merchant Name).
URL2	A	Merchant URL (second)	Not used.
KEY2	B	Merchant’s Private Key (second)	See details below
TOF	1	Output Size and Format	See details below
OPT	4	Options	Template-specific Options
PFX	2	Prefix	Template-specific Prefix

#ID1 - Merchant ID

Offset : 6

Size : 32

#URL1 - Merchant URL

Offset : 7

Size : 1

#KEY1 - Merchant’s Private Key

Offset : 8

Size : 32

#Byte 0 : Key slot in the internal ATECC

Condition : If the size of the register is 1, this Byte stores the ATECC key slot.

#Bytes 0-31 : Value of ECC Private Key

Condition : If the size of the register is 32, these Bytes store the actual private key.

#ID2 - Merchant ID (second)

Offset : 9

Size : 32

#URL2 - Merchant URL (second)

Offset : A

Size : 1

#KEY2 - Merchant’s Private Key (second)

Offset : B

Size : 32

#Byte 0 : Key slot in the internal ATECC

Condition : If the size of the register is 1, this Byte stores the ATECC key slot.

#Bytes 0-31 : Value of ECC Private Key

Condition : If the size of the register is 32, these Bytes store the actual private key.

#TOF - Output Size and Format

Offset : 1

Size : 2

#Byte 0 : RAW Mode

Condition : When RAW Mode is selected (Bit 6 in Byte 0 is 0)

Bit	Role	Values
7	Invert Data?	0 : Transmit the sequence of bytes as is 1 : Transmit the sequence of bytes in reverse order
6	Mode	0 : RAW Mode (Data is a numerical value) 1 : String Mode (Data is an ASCII string)
5	Padding if Data is shorted than specified length	0 : Padd with 0 on the left 1 : Padd with F on the right
4	Remove leading zeroes?	0 : Keep all digits 1 : Suppress 0 digits on the left of the Data
3-0	Length and Format	0 : Decimal, 10 digits (truncation on 4-B) 1 : Raw (hex), 4 bytes (32 bits) 2 : Raw (hex), 8 bytes (64 bits) 3 : Raw (hex), 5 bytes (40 bits) 4 : Raw (hex), 10 bytes (80 bits) 5 : Raw (hex), 7 bytes (56 bits) 6 : Raw (hex), 11 bytes (88 bits) 7 : RFU 8 : Raw (hex), 16 bytes (128 bits) 9 : Raw (hex), 20 bytes (160 bits) 10 : Raw (hex), 24 bytes (196 bits) 11 : Raw (hex), 32 bytes (256 bits) 12 : Decimal, 12 digits (truncation on 5-B) 13 : Decimal, 13 digits (truncation on 5-B) 14 : Decimal, variable length 15 : Raw (hex), variable length

#Byte 0 : String Mode

Condition : When String Mode is selected (Bit 6 in Byte 0 is 1)

Bit	Role	Values
7	Invert Data?	0 : Transmit the sequence of characters as is 1 : Transmit the sequence of characters in reverse order
6	Mode	0 : RAW Mode (Data is a numerical value) 1 : String Mode (Data is an ASCII string)
5	Padding if Data is shorted than specified length	0 : Variable length (no padding) 1 : Padd with (space characters) on the right until the specified length
4	Short string or Long string?	0 : Short string (truncate to 16 characters or less) 1 : Long string (more than 16 characters)
3-0	Length	0 : 16 characters 1 : 1 character 2 : 2 characters 3 : 3 characters 4 : 4 characters 5 : 5 characters 6 : 6 characters 7 : 7 characters 8 : 8 characters 9 : 9 characters 10 : 10 characters 11 : 11 characters 12 : 12 characters 13 : 13 characters 14 : 14 characters 15 : 15 characters

#Byte 1 : Options for Long String

Condition : When Long String Mode is selected (Bit 6 in Byte 0 is 1 and Bit 4 is 1)

Use this byte to specify the exact length to read from the card. Valid range is 1 to 255.

#OPT - Options

Offset : 4

Size : 1

If this register is set, the Reader adds a token to its output to tell the receiver what kind of credential has been read.

Bit	Role	Values
7-4	RFU
3-2	Position of the Card Type Token	0 : Before the Prefix 1 : After the Prefix, before the Data 2 : After the Data (before the Suffix) 3 : RFU
1-0	Add a Card Type Token to the output stream?	0 : Do not add a Card Type Token 1 : Add D1 hex value as Card Type Token 2 : Add a char as Card Type Token 3 : RFU

#PFX - Prefix

Offset : 2

Size : 8

A Template-specific Prefix, that is added after the Reader’s global Prefix.

Remark : Use \t for a Tab, \n for Enter, \b for Back space, \v for Vertical space.