SpringCard contactless PC/SC couplers (NFC/RFID HF) can be used to read contactless passes carried by NFC smartphones.
In particular, the Prox’N’Roll HSP PC/SC and the PUCK configured as PC/SC have been certified :
- by Apple for reading NFC passes stored in the Apple Wallet application (“Apple VAS” protocol, formerly branded as “PassKit”),
- by Google for reading NFC passes stored in the Google Pay application (“Google VAS” protocol, still branded as “Smart Tap” or now “Google Wallet”).
To read these NFC passes, you need :
- respect the radio protocol (ISO/IEC 14443, EMV CL),
- respect the Apple VAS or Google VAS application protocol,
- master the application parameters: identifier to search, the cryptographic key to use.
Point 1. is purely the role of the coupler. All contactless PC/SC couplers can logically be used to read passes (modulo the specificity of the Apple ECP protocol – Enhanced Contactless Polling – which allows to wake up the iPhone when its screen is locked, and which is only implemented by products authorized by Apple, including those from SpringCard).
Point 2. is purely software. To help its customers exploit NFC pass reading in their own applications, SpringCard has developed two .NET libraries (usable under Windows and all systems that support .NET Core) that provide a high-level implementation of the Apple VAS and Google VAS application protocols.
These two libraries are not free of charge; a license must be purchased from SpringCard. Evaluation versions are available: they are 100% functional but stop every 10 minutes.
Point 3. is the most straightforward part technically, but it is not necessarily the most obvious for the integrator who has to discover everything.
The role of this document is to guide the integrator in setting up a first demonstration of NFC pass reading through a contactless PC/SC coupler.
Preparation
This procedure assumes the use of Windows 10 or Windows 11.
Installation of the PC/SC coupler
SpringCard contactless PC/SC couplers are supported by the Microsoft CCID driver, which is integrated with Windows, but this driver has a lot of limitations that do not allow to fully exploit the coupler.
So you have to install the SpringCard PC/SC driver before connecting the coupler to the PC (otherwise the Microsoft driver is installed instead).
To do this, download and install the latest version of the SD16055 package: https://www.springcard.com/en/download/find/file/sd16055
In case of error (coupler plugged too early), go to the device manager, identify the coupler (group Smart card readers) and force an update of the driver from Windows Update. The procedure is described in this tutorial.
Installation of PassKitRdr software
PassKitRdr is the software to read NFC Apple VAS passes.
Getting a license for PassKitRdr
TODO :
Installing SmartTapRdr software
SmartTapRdr is the software to read Google Smart Tap NFC passes.
Getting a license for SmartTapRdr
TODO :
These two software in evaluation version are available in our PC/SC QuickStart. After every 10 minutes, you will have to restart the application to make it work. Download and install from this link.
Reading Apple VAS passes
Getting a SpringCard test pass
You have the possibility to create your own free pass via our platform: https://playground.springpass.prod.springcard.com
You will receive an email with Apple Pass attached and in the content of the email you will have a link to open to add the Android Pass to your wallet.
On your iPhone, the file has a .PKPASS extension. You have to open this file directly on the iPhone so that the pass is automatically added to Apple Wallet.
If you want us to create an NFC/RFID pass for you, you can contact us at sales@springcard.com
Warning: nothing prevents you from adding several passes from the same issuer (e.g. SpringPass) in Apple Wallet. However, the automatic selection of “the right” NFC pass fails when there are several “right” passes. To keep the iPhone and Apple Wallet nominal, delete a possible SpringPass test pass already present in your smartphone before adding a new one.
Setting up PassKitRdr to read SpringCard test passes
- Start PassKitRdr
- Click on Edit configuration
- Click on Use test configuration to load the default SpringPass configuration
- Click on Close
- If necessary, click on Refresh reader list
- Choose the Contactless SpringCard coupler
- Click on the Play button
- Present the iPhone on the coupler; observe the appearance of data in the field Pass message and Timestamp (UTC)
The Pass message field is the “useful” content of the NFC pass. For test passes issued by the SpringPass server, it is a string made up of :
- identifier (pseudo-random) on 4 bytes expressed in hexadecimal
- “pipe” separator (|)
- the email address provided at pass creation
In a “client” implementation, other data can obviously be transmitted, but it is necessary to limit the total length of the ASCII string to 64 characters.
The UTC Timestamp field provides the date/time of the iPhone. This information is necessary to ensure anti-replay, as the Apple VAS protocol does not feature dynamic authentication. The application compares the provided date/time with the PC one and displays a check if the pass is acceptable (less than ± 5 seconds offset).
Configuration of PassKitRdr for ‘customer’ passes
The Apple VAS configuration is very simple as it requires only two parameters :
- The Merchant Name (passTypeIdentifier field in the PKPASS file); the Merchant ID is calculated automatically,
- The merchant’s ECC P-256 private key. The Key ID and the public key are calculated automatically. The public key goes into the encryptionPublicKey field of the PKPASS file.
Note: this screenshot shows the private key of the SpringPass demo system. This is not a problem only because it is a demo! To ensure the privacy of your Apple VAS implementation, only your reading devices (Smart Reader or application + PC/SC coupler) should know your private key.
Debugging with PassKitRdr
It is possible to run PassKitRdr in debug mode (console visible, traces visible in the console) by running the command PassKitRdr.exe -c – q -v6
This allows to see all the application exchanges (APDUs) and cryptographic calculations, in order to isolate possible problems.
Integration of the .NET SpringCard.AppleVas.dll library in your own application
Contact us for a quote!
Reading Google VAS passes
Getting a SpringCard test pass
Go to : https://playground.springpass.prod.springcard.com
You will receive the Google pass as a clicking link in an email.
It is not necessary to be on the Android smartphone to click on this link; on an external web browser, it will ask for a Google account authentication and will send the pass “OTA” (other the air) as when you ask for the installation of a new application through the Play Store.
Warning : there is nothing to prevent you from adding in Google Pay several passes from the same issuer (e.g. SpringPass). However, the automatic selection of the “right” NFC pass fails when there are several “right” passes. To keep Google Pay nominal, you should delete any SpringPass test pass already present in your smartphone before adding a new one.
SmartTapRdr configuration to read SpringCard test passes
- Start SmartTapRdr
- Click on Edit configuration
- Click on SpringCard demo to load the configuration corresponding to the default SpringPass
- Click on Close
- If necessary, click on Refresh reader list
- Choose the SpringCard Contactless coupler
- Click on the Play button
- Present the Android smartphone on the coupler; observe the appearance of data in the Smart Tap data field
The Smart Tap data field is built by the library in JSON format (“in real life”, the Android smartphone sends its data in a message according to the NDEF encoding of NFC, which allows a much more compact transmission).
We find in the JSON an array of everything that the NFC message contained.
The order of the two elements of the table is not systematic. Sometimes the pass comes in the first position, sometimes the pass comes in the second position.
We recognize “the right” record (the one that corresponds to the pass) by the IssuerType= Merchant value, and by the IssuerId that corresponds to the one requested by the application from the smartphone.
The IssuerId is in fact the Collector ID in Google Pay & Wallet Console, but in hexadecimal :
Collector ID = 50888355 (décimal) → IssuerId = 03087EA3 (hexadécimal)
The Message corresponds to the “useful” content of the NFC pass. For test passes issued by the SpringPass server and in order to be consistent, it uses the same format as PassKit messages (ID, pipe, email), but Smart Tap does not have the same 64 characters limitation. It is the value of the smartTapRedemptionValue field of the object associated with the pass (document for test passes which are offers: https://developers.google.com/wallet/retail/offers/rest/v1/offerobject)
The other record is added by Google Pay. It indicates the language of the smartphone, a unique transaction identifier (TapId) which is not usable, and a unique user identifier (CustomerId) which is systematically 00…00 in Europe (RGPD constraint).
SmartTapRdr configuration for ‘customer’ passes
The configuration of the Google VAS application is much more complex than the Apple VAS application.
General tab
The normal settings are as follows :
Checking the Allow skipping Smart Tap 2 select box saves some time on the transaction but can be problematic with smartphones with “complicated” NFC configuration (typically, EMV VAS app in the SIM card or in an OS, in addition to the Google VAS app running in HCE mode).
Only the v2.1 version has been validated by the Google test tooling.
SpringCard products are not approved for payment, so you should not check the Request payment box.
Merchant tab
This is where you have to fill in the Collector ID found in Google Pay & Wallet Console.
You can enter it in hexadecimal (left) or decimal (right); both fields are linked.
The same value is found in the smartTapMerchantId field of the Issuer object provided by the API (https://developers.google.com/wallet/retail/offers/rest/v1/issuer)
Be careful not to confuse it with the issuerId field, in the same Issuer object, which is completely different!
The other fields (Merchant Name, Location ID, …) can remain empty.
Cryptography and security tab
Note : this screenshot shows the private key of the SpringPass demo system. This is not a problem just because it is a demo! To ensure the privacy of your Google VAS implementation, only your reading devices (Smart Reader or application + PC/SC coupler) should know your private key.
You must provide the ECC P-256 private key in the Merchant Long Term Private Key field. The entry is made in hexadecimal (32 bytes or 64 characters).
By clicking on Show public key you access a screen that provides the public key in hexadecimal (X component only), and in PEM format.
It is this PEM value (saved in a file) that you will need to provide to Google via the console or via the API.
(remember to specify the same version as the one entered in the Version of the Long Term Key field)
We must find the same values in the Issuer object provided by the API (https://developers.google.com/wallet/retail/offers/rest/v1/issuer)
The Use device’s Secure Element box must not be checked.
The other fields (Terminal Nonce, Terminal Ephemeral Private Key, …) are only used for certification tests and must remain empty.
Requested data tab
Check Send GET DATA command and All valuables.
Push back data tab
This part is not implemented.
Terminal capabilities tab
Check that only the box Tap capabilities → VAS Only is checked.
Debugging with SmartTapRdr
It is possible to run SmartTapRdr in debug mode (console visible, traces visible in the console) by running the command SmartTapRdr.exe -c – q -v6
This allows to see all the application exchanges (APDUs) and cryptographic calculations, in order to isolate possible problems.
Integration of the .NET SpringCard.GoogleVas.dll library in your own application
Contact us for a quote!