Apple VAS template

This feature is restricted and subject to a specific license agreement and fees. Please contact SpringCard for detailed information and pricing options.

Overview

Use this template to read Apple VAS data from an iOS mobile.

What is Apple VAS?

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.

Important

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: { KPRI:MERCHANT, KPUB: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 KPUB: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 KPUB: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 KPRI: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.

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 03t6 to 03t8,
  • Data for the 2nd Merchant are stored in registers 03t9 to 03tB.

Just leave registers 03t9 to 03tB empty if you have a single Merchant configuration.

Register t0: select the Apple VAS template

Register 03t0 (1 byte) selects the template. Set it to D1 to select this template.

Register t1: output format

Register 03t1 defines the output format. Refer to Template engine : Data Output Format.

Register t2: output prefix

Register 03t2 defines the output prefix. Refer to Template engine : Output Prefix.

Register t3: P2 Register

Register t4: Capabilities

Register t6 and t9: Merchant ID and Key ID

Register 03t6 or 03t9 (36 bytes) stores the identifier of the merchant and the identifier of the key-pair.

Bytes Field Description
0-31 Merchant ID Merchant ID = SHA256 ( Merchant Name )
32-36 Key ID Key ID = SHA256 ( X coordinate of KPUB:MERCHANT ) [0..3]

Note: the Key ID may be computed from the public key, which in turn may be computed from the private key, which has to be known from the reader (register 0x8 or 0xB, see below). Therefore, the Key ID field may be recovered by the reader if not supplied in this register.

Register t7 and tA : Merchant URL

Register t8 and tB: Private key

The Private key may either be written together with the configuration into the NVM, or stored in the ATECC Secure Element.

Private key stored within the configuration

Register 03t8 or 03tB (32 bytes) stores the private part of the key-pair.

Bytes Field Content
0-31 Private key KPRI:MERCHANT

Private key stored in the ATECC

If the device features a ECC Secure Element, the register 03t8 or 03tB (1 byte) stores only the key entry.

Bytes Field Comment
0 Key entry index Valid values are 00 to 0D