Appendixes
| Appendix | Title |
|---|---|
| Appendix-1 | Architecture Decision Record (ADR). |
| Appendix-2 | About services. |
| Appendix-3 | About Logger. |
| Appendix-4 | About ICS. |
| Appendix-5 | About ODA. |
ADR
This section documents decisions about architecture and decision to help readers understand how switstack moka is built.
| Decision #1 | EMV Level 2 Certifications |
|---|---|
| Context | EMVCo Books follow a writing pattern that helps to normalized EMV Level 2 implementations. But for a given brand, a C-x book diverges from the payment network's specification which imposes a dual reference complicating code documentation, design, and test plan realization. |
| Decision | switstack moka targets payment networks certifications, excepted for EMVCo contact and EMVCo Book C-8. |
| Consequences | No impact on EMVCo Book C-2 as the payment network aligned their specifications already. For other networks, code documentation will refer to requirements coming from the payment networks specifications if they diverge from corresponding EMVCo Book C-x. |
Services
Each switstack moka's software component is a service that follows the same architecture pattern.
- A service is encapsulated by a proxy that can be reached by any other service through a message broker (the proxy is registered onto the message broker at the setup time);
- A service implements a set of generic services, and a set of functional services that are specific to the service.
- A service runs on top of a data model that rules service's states that generic and functional services navigate;
All services support the following generic services:
| Generic Service | Description |
|---|---|
| GENERIC_SERVICE_GET_NAME | -- |
| GENERIC_SERVICE_GET_IDENTIFIER | -- |
| GENERIC_SERVICE_GET_VERSION | -- |
| GENERIC_SERVICE_GET_CHECKSUM | -- |
| GENERIC_SERVICE_GET_SETUP | -- |
| GENERIC_SERVICE_GET_INITIALIZE | -- |
| GENERIC_SERVICE_SET_PARAMETERS | -- |
| GENERIC_SERVICE_GET_PARAMETERS | -- |
| GENERIC_SERVICE_GET_CLEANUP | -- |
| GENERIC_SERVICE_GET_RELEASE | -- |
Then, each service may expose a series of functional services depending on its purpose. The following sections present each service along with its data model.
HSM
Data model
Functional services
Entry Point
Data model
| Tag | Name | Type | Set | Get | Description |
|---|---|---|---|---|---|
| 0x87 | Priority indicator | Byte value [0..15] |  |
 |
Selected candidate' AID priority |
| 0x96 | Kernel identifer-terminal | TLV | |
|
Selected candidate's kernel identifier-terminal |
| 0xE1 | Combination | TLV string | |
|
Contactless combination for a given {AID - Kernel ID - Transaction Type} triplet |
| 0xE2 | Selected candidate combination | TLV string | |
|
Contactless combination sent by emtry point during kernel activiation |
| 0xE4 | FCI | TLV string | |
|
Selected canddiate's final select response |
| 0xE5 | Transaction related data | TLV string | |
|
Data used to trigger a transaction during start A |
| 0xEB | Kernel Resume Data | TLV string | |
|
If supported by a kernel, data used to perform a start D after an issuer online response |
| 0x9F06 | Matching AID | TLV | |
|
Selected candidate's AID |
| 0x9F0A | ASPRD | TLV | |
|
Not support yet |
| 0x9F29 | Extended selection | TLV | |
|
If exetended selection supported, AID post-fix |
| 0x9F3E | Terminal categories supported list | TLV | |
|
Not support yet |
| 0x9F3F | Selection data object list | TLV | |
|
Not support yet |
| 0x9F66 | TTQ | TLV | |
|
Selected candidate's TTQ |
| 0xBF0C | FCI issuer data | TLV string | |
|
Selected candidate's FCI issuer data |
| 0xDFA021 | Signal mode | Enum{C2=0, Other=1} | |
|
Signal management is not normalized between kernel specifications. Some cases such as Application Not Allowed or Empty Candidate List require to know in which mode the entry point shall formats output signal. Default value: C2 |
| 0xDFA025 | Reference transaction type | Byte value mirroing EMV tag 0x9C | |
|
Shall be defined before adding the first combination to filter combinations corresponding to actual transaction type |
| 0xDFA00A | Entry point pre-procesing indicators | TLV | |
|
Selected candidate's pre-processing indicators |
| 0xDFA00B | Autorun support | Boolean | |
|
Starting condition for entry point, i.e. how a transaction is initiated |
| 0xDFA00C | Skip polling | Boolean | |
|
Skip polling during start B |
| 0xDFA011 | ASPRD support | Boolean | |
|
Support application selection registered proprietary tag 0x9F0A |
| 0xDFA013 | TIDAS support | Boolean | |
|
Support terminal information during application selection tag 9F3E and 9F3F |
| 0xDFA039 | Kernel C-8 support | Boolean | |
|
Entry point supports kernel C8 |
Functional services
| Entry Point Service (see entry_point.h) | Description |
|---|---|
| EMVCO_ENTRY_POINT_SERVICE_START_A | Implements EMVCo start A. |
| EMVCO_ENTRY_POINT_SERVICE_START_B | Implements EMVCo start B. |
| EMVCO_ENTRY_POINT_SERVICE_START_C | Implements EMVCo start C. |
| EMVCO_ENTRY_POINT_SERVICE_START_D | Implements EMVCo start D. |
Card Processing Application (CPA) Service
Data model
Each CPA's data model is specific. Refer to CPA_Name_data_model.h to get how it is structured, However, all CPA all built from the same pattern:
- A CPA is a state machine. A CPA State realizes a card processing step that consists in analyzing the last APDU response, and preparing the next one. For some states, it is a simple implemetation of a processing flow's step. Refer to
CPA_Name_card_processing.c. - A CPA manages an internal dashboard to raise errors under the tags DFA009 and DFA028. These 2 tags are bitmaps similar to TVR. Tag DFA009 is dedicated to ODA whereas DFA028 depends on the CPA. Refer to
CPA_Name_data_model.h to get the list of bits. - A CPA implements procedures. Whereas states represents flow steps and raise outcomes, procedures are standalone algorithms required by steps to implement EMV logic. Refer to CPA/procedures directory.
- A CPA supports a list of tags declared in
CPA_Name_tags.c. Each tag is defined by a rule indicating its source, type, length, ... When a tag is fetched from the configuration, the payment application, or the card, the CPA validates that it is valid against its definition.
Functional services
A CPA is a kernel that implements EMVCo's or payment networks' specifications.
| CPA Service (see cpa_name.h) | Description |
|---|---|
CPA_NAME_SERVICE_PRE_PROCESSING |
Optional. Compute indicators to prepare card processing. |
CPA_NAME_SERVICE_ACTIVATE |
Activate a kernel as per EMVCo definition. |
Logger
Implementation Conformance Statements (ICS)
All ICS presented in this section are a snapshot of moka capabilities. Kernels are always on maintainance and adapted to new needs and specifications versions.
Notation is as followed:
: supported
: not supported
: configurable
Mastercard
Implementation: EMVCo Contactless Book C-2, Kernel 2 Spec v2.11 
Profile = moka COTS |
Option |
|---|---|
| Mastercard CL Selection | |
| Magstripe | |
| SPI | |
| DE/DS | |
Visa
Release date: Q2 2025 
American Express
Implementation: Expresspay Terminal Technical Specification v4.2
Profile = moka COTS |
Option |
|---|---|
| ATM | |
| CASH | |
| CASHBACK | |
| CDA | |
| CDA Fail Detected Prior TAA1 | |
| Check Connection | |
| Delayed Authorization | |
| Exception File | |
| Goods Or Services | |
| Key Revocation | |
| Membership Data | |
| Mobille CVM | |
| No CVM Check Exempt | |
| Offline Only | |
| Online Only | |
| Online PIN | |
| Other Interface | |
| SDA | |
| Signature | |
| Status Check | |
| TVR Display After GenAc | |
| Unable To Go Online | |
| Zero Amount | |
| Attended | |
| All Mode | |
| EMV | |
| EMV Mobile | |
| MPOS | |
| Expresspay | |
| C4 | |
Profile = moka PCI-PTS |
Option |
|---|---|
| ATM | |
| CASH | |
| CASHBACK | |
| CDA | |
| CDA Fail Detected Prior TAA1 | |
| Check Connection | |
| Delayed Authorization | |
| Exception File | |
| Goods Or Services | |
| Key Revocation | |
| Membership Data | |
| Mobille CVM | |
| No CVM Check Exempt | |
| Offline Only | |
| Online Only | |
| Online PIN | |
| Other Interface | |
| SDA | |
| Signature | |
| Status Check | |
| TVR Display After GenAc | |
| Unable To Go Online | |
| Zero Amount | |
| Attended | |
| All Mode | |
| EMV | |
| EMV Mobile | |
| MPOS | |
| Expresspay | |
| C4 | |
Discover
Release date: Q2 2025
Offline Data Authentication
ODA is an EMV mechanism used to authenticate cards offline. It includes SDA, DDA, CDA, and XDA. Along with OMA (Online Mutual Authentication), it realizes the EMV security scheme. Whereas OMA is based on symmetric cryptography, ODA uses RSA and ECC keys to perform offline authentication.
Note
RSA (Rivest, Shamir, Adleman) is the EMV's legacy algorithm. ECC (Elliptic Curve Cryptography) is now proposed from EMVCo Book IV, v4.4 and EMVCo Book C-8.
You may also refer to EMVCo Book II that describes the security scheme and underlying key management.
In line with moka's strategy to protect sensitive data, ODA imlpementation has been addressed with "PCI requirements" in mind. The challenge that ODA offers in regards to data protection is:
- Some ODA certificates contains the card's PAN or a portion of it;
- EMV Level 2 kernels need to manipulate these certificates;
- EMV Level 2 kernels need to sort card's read records containing sensitive data and participating to ODA.
On the other hand, ODA validation may require specific logics beyond the EMV Level 2 standard specifications. So, moka needs to offer maximum flexibility to implement, as an example, transit logic (i.e. for open payment) using contactless EMV acceptance to manage users accesses to transportation networks and the corresponding fees calculation.
So, that's why ODA implementation is supported by 3 different moka services:
- CPA: verifies static signed data certificate (tag 93) and signed dynamic application data (tag 9F4B) in the limits of sensitive data protection;
- Reader: verifies issuer's and icc's certificates. Also, performs all operations involving sensitive data such as signed record hashing, PAN comparison, etc...;
- HSM: stores all ODA keys and manages revocations.
Additionally, these components use an EMV tool box that is a static library. That static library is stateless (doesn't store any data). But, it may see sensitive information during ODA process. So, depending of the physical architecture, that library shall have 2 instances: 1 running alongside CPA services (at application level); 1 running alongside the Reader service.
| Issuer Certificate (tag 90) | ICC Certificate (tag 9F46) | Static Signed Data (tag 93) | Signed Dynamic Application Data (tag 9F4B) | |
|---|---|---|---|---|
| Validated by | Reader Service | Reader Service | CPA Service | CPA Service |
| Require expiration date control | Yes | Yes | No | No |
| Require revocation control | Yes | No | No | No |
| Require PAN Manipulation | Yes (PAN prefix) | Yes | No | No |
| Require Signed Records Manipulation | No | Yes | Yes | No |
| May include Proprietary Format | No | Yes | Yes | Yes |