SA Systems

CardHub
Technical Architecture

V0.1 First Draft Chris Allen 27/09/2019

V0.2 Second Draft Chris Allen 04/10/2019

V0.3 Pre release Chris Allen 23/10/2019

V0.4 Minor updates Chris Allen 08/11/2019

Contents
1. Overview 4

2. CardHub Kiosk 5
2.1 CardHub Kiosk components 5

3. CardHub Server 7
3.1 Overview 7
3.2 CardHub Server Key Components 8

4. CardWizard Suite 9
4.1 CardWizard and CardHub 9
4.2 CardWizard API 9
4.3 CardWizard KGS 10
4.4 CardWizard technical documentation reference 10

5. Bank & Card Issuer Systems 11

5.1 Overview 11
5.2 CardHub Changes to CMS 11
5.2 SAS Test Bank CMS 12

6. Cardhub System APIs 13

6.1 The CardHub Kiosk API 13
6.2 The CardHub Public API 14
6.3 The CardHub Admin API 15
6.4 The Bank API 15
6.5 The CardWizard API 16
6.6 APIs and the issuance user journey 17

7. AWS Architecture 19
7.1 Overview 19
7.2 Authentication and Authorisation 20
7.3 VPC Network Addressing 20
7.3 Scalability 21
7.4 High Availability & Failover 21
7.5 IAS Architecture - Terraform / CloudFormation 21
7.6 Logging & Monitoring - CloudWatch vs DataDog. 21
8.1 OpenVPN Cloud Server 22
8.2 Kiosk VPN management 22
8.3 VPN hardware proposal 23
 8.4 VPN Key/Certificate management 23
8.4 Assigned Kiosk Addresses (to be moved to spreadsheet / db) 24
8.4.1 EDC Development Kiosk - 10.21.0.0/24 24
8.4.2 RUT950 Router - 10.21.1.0/24 25

9. Glossary 26
1. Overview
SA Systems CardHub is a hardware and software platform that allows payment cards to be
created and issued to end users automatically at a variety of locations. The platform is secure,
robust and scalable and is easily integrated into existing banking systems.

CardHub system architecture diagram​.

A CardHub system is made up of four parts:

1. SA Systems CardHub Kiosk (on-location)

2. SA Systemd CardHub Server (cloud-based)
3. Entrust DataCard (EDC) CardWizard software suite (Secure Data centre)
4. Banking and card issuer back-end. (Bank Data centre)

The end-user journey is straightforward and secure and can easily be integrated at an
application level:

1. The user requests a new card from their banking app

2. The banking app issues a QR code and directs them to a CardHub kiosk
3. The user displays the QR code to the kiosk and verifies their identity through their device
4. The kiosk issues a card to the user and activates it.

This document describes the CardHub platform and its associated systems.
2. CardHub Kiosk
The CardHub Kiosk is a secure, remote unit that contains all the equipment necessary
for interaction with a user and issuance of a payment card. It requires only a power
source and a reliable internet connection - wired, WiFi or mobile.

2.1 CardHub Kiosk components

Internally, the kiosk contains a number of linked components.

The components are described in detail below:

Kiosk Control server ● Single-unit industrial PC

● Linux server (Recent Ubuntu or similar) or Windows*
● Will converse with the CardHub Cloud Server
● Will control interaction with the UI components
● Will query the card printer via CardWizard for
status/statistics.

EDC Card Printer ● EDC 875K Card printer

● Initially will need a fixed IP address accessible on an
incoming connection through the VPN
● Once CardWizard 8.x is in use, will poll CardWizard on an
outgoing connection so no VPN connectivity will be
required

QR Scanner ● TBD

Display ● Large Panel LCD

● Will display welcome messages to the user
● Spec TBD

Touch Screen ● Will interact with the user and allow them to choose
options.

VPN Router module ● Teletonika RUT950 VPN Router

● Will allow Control server and Printer to connect to the
internal LAN
● Will run OpenWRT / OpenVPN to create a secure full
duplex VPN link to the CardHub Cloud service
● Will Connect the internal LAN to the Internet/WAN
● Provides load balancing and automatic redundancy over
Ethernet/WiFi/4G (2 x 4G Sim with failover)
● See section 8.3 for further detail
3. CardHub Server

3.1 Overview

The CardHub server is a software suite and set of APIs that manages the CardHub system.
3.2 CardHub Server Key Components

CardHub Public API ● Secure REST API for querying CardHub functions
○ Hub Locations
○ Card Stock Levels
○ Card production queries
● Microsoft TypeScript
● NodeJS server
● https://cardhub-api-docs.s3.eu-west-2.amazonaws.c
om/index.html

CardHub Kiosk API ● Will maintain a database of active servers

● Will collect metrics from each server, aggregate and
provide reporting.
● Will allow kiosks to be managed remotely.
● Will interact with Kiosk software to provide customer
identifitcation and send tokenised card id.

CardHub Admin API ● Kiosk management functions

● Database management functions

CardWizard Interaction ● Interaction with the CardWizard servers for issuance

of cards.
● Initially will use the KGS library, but planned to move
to direct CardWizard API

VPN Management ● OpenVPN Server

● Will manage and allocate addresses for all Kiosk
locations

Bank System Interaction ● Retrieve tokenenised card id from card issuer.

● Activate payment card once issued
4. CardWizard Suite
CardWizard software supports on-the-spot issuance of plastic cards to customers in an
environment that requires data and card security, for example issuance of Visa® or
MasterCard® credit or debit cards. With a CardWizard system, cards are embossed, encoded,
and/or printed at the time the organization’s customer applies for the card. This is called instant
issuance. CardWizard software provides centralized control over locally issued cards in a
networked environment. Customers of the organization leave with a personalized, permanent
card ready for immediate use. Instant issuance also reduces card inventory and mailing
concerns.

4.1 CardWizard and CardHub

The current edition of CardWizard is tightly integrated with both card issuers and EDC physical
card printers. It will not directly support the features needed by CardHub. Silver Arrow Systems
will work with EDC to develop the features required.

4.2 CardWizard API

The CardWizard Web API is a RESTful (Representational State Transfer) HTTP- based service.
It supports set up, reporting, and common card requests using CardWizard software features.
Clients can use the CardWizard Web API to:

● Build a new graphical user interface component that is used with your financial
institution’s existing application.
● Integrate CardWizard software functionality into an existing application.
● Set up the CardWizard system, generate reports, and otherwise administer CardWizard
software in a production environment.

All communication between the application and the CardWizard Web API uses HTTPS
Requests and Responses. The HTTPS protocol is used to leverage the security features built
into the protocol.
4.3 CardWizard KGS

Link to KGS API Documentation

The Entrust Datacard Kiosk Gateway Service (KGS) is a solution designed to provide all
necessary tools to kiosk vendors wanting to drive card personalization on Entrust
Datacard Solution.It is composed of several components

● The KGS,an IIS hosted,REST based, web service, centralizing all communications
between the Kiosk Application and the EDC environment
● EDC CardWizard solution (including possibly EDC Adaptive Issuance Suite), from
where the card personalization is driven but also configured.
● EDC CardWizard “CMS extensions”, ensuring communication with the bank CMS
to retrieve, if necessary, additional information about the card to personalize

While KGS is a useful and instructive layer atop the CardWizard API it is not considered
sufficiently flexible for long term use in the CardHub project. Early versions of CardHub will use
KGS but later versions will be built directly on top of the main CardWizard API.

The existing version of KGS requires a number of feature changes and bug fixes to allow its
successful use with CardHub even at an early stage. Those changes are listed in ​this
document.

4.4 CardWizard technical documentation reference

● CardWizard API Technical documentation

● CardWizard API calls Visio diagram
● CardWizard API Training presentation
● CardWizard API Java examples
● EDC Security and planning manual
5. Bank & Card Issuer Systems

5.1 Overview

All payment cards issued by CardHub will be created on behalf of a bank or card issuer. That
card issuer is the ultimate provider of the payment card and its associated bank account. In
order to print a card, this action must be authorised by the card issuer.

All interactions with a card issuer take place through its Card Management System (CMS). This
is a suite of software that owns and manages the lifecycle of a payment card. Interaction with a
CMS is carried out using a secure API and only by trusted systems. In the case of CardHub,
almost all interaction will be done through the EDC CardWizard software.

The following touchpoints will exist between CardHub and the card issuer:

Action Source Destination Transaction Owner

Request new card Mobile App CMS Issuer

Issue card request token CMS CardHub Issuer

Retrieve card personalisation data CardWizard CMS CardWizard

Activate card CardWizard CMS CardWizard

5.2 CardHub Changes to CMS

A Card Issuer CMS will not support the CardHub user journey by default and some changes to
its operation will be required. It is expected that the Card Issuer will arrange for the changes to
be implemented as part of the CardHub development process. In particular, these changes will
be required

● Interaction with the CardHub API to supply a token for a requested card
● Activation of a card from a CardHub Kiosk.
5.2 SAS Test Bank CMS

For development purposes, SAS will create a “dummy” Bank CMS that will provide all of the
expected functionality of a live bank system. This will interact with CardWizard and CardHub to
simulate the card issue process.
6. Cardhub System APIs
The CardHub user journey is supported by six APIs. Three of these are built and hosted by
Silver Arrow Systems and three are external.

API Name API Owner Functions

CardHub Kiosk Silver Arrow ● Verify QR / Fetch Token

(CardHub Server) ● Issue card (pass thru to CardWizard)
● Activate card (pass thru to CardWizard)

CardHub Public Silver Arrow ● Issue QR code (called by Bank)

(CardHub Server) ● Fetch QR code (called by APP)
● Locate Kiosk
● Select Kiosk

CardHub Silver Arrow ● Update Kiosk locations

Management (CardHub Server) ● Add Kiosk
● Remove Kiosk
● Configure Kiosk
● Consumables status
● Retrieve metrics

Bank Bank / Card Issuer ● Request new card

● Request card/personalisation data
● Activate card

CardWizard EDS ● Issue Card

● Activate Card

KGS EDS ● Front end to CardWizard API

● Only used in early CardHub versions

6.1 The CardHub Kiosk API

Endpoint: kiosk.sas-cardhub.net

The Kiosk API is an API built by Silver Arrow Systems. It is hosted by the CardHub cloud server
and called only by the CardHub Kiosk. It is a REST API that provides customer verification
functions. It also provides pass-thru functions to CardWizard, removing the need for the Kiosk to
communicate directly with CardWizard

This documentation is an architectural overview. Full documentation and examples can be

found at the API endpoint.

API Call Parameter Returns Description

Verify QR QR Code Card Token Verifies the supplied QR code against

that previously generated. Returns the
card token (CardId) generated by the
bank

Issue Card Card Token - Instructs CardWizard to issue and print a

card

Activate Card Token - Instructs CardWizard to activate a card

Card

6.2 The CardHub Public API

Endpoint: api.sas-cardhub.net

The Public API is an API built by Silver Arrow Systems. It is hosted by the CardHub cloud server
and called by various third parties. It is a REST API that provides external facing QR code and
kiosk location functions.

API Call Parameter Returns Description

Issue QR Card Token - Creates a QR code and stores it locally

Code (Card Id) with the supplied Card Token.

Fetch QR - QR Code The created QR code is returned to the

Code caller (usually the kiosk)

Locate Kiosk GeoLocation List of kiosk Returns a list of CardHub kiosks close to
locations the supplied location

Select Kiosk Kiosk Id - Selects the kiosk that will be used to

 issue a payment card

6.3 The CardHub Admin API

Endpoint: admin.sas-cardhub.net

The Management API is an API built by Silver Arrow Systems. It is hosted by the CardHub cloud
server and called via a web front-end from a secure browser. It is a REST API that allows kiosk
management functions to be performed.

API Call Parameter Returns Description

Update kiosk List of locations - Updates the server’s list of Kiosk locations
locations

Add Kiosk Kiosk Id - Adds a new kiosk to the list

Remove Kiosk Kiosk Id - Removes a kiosk from the list

Configure kiosk Kiosk Id, - Configures a kiosk - updates network

configuration settings, name, internal configuration
data

Consumables Kiosk Id Status Returns the status of consumables for a

status kiosk

Retrieve metrics Kiosk Id Metrics Returns the metrics list for a kiosk.

6.4 The Bank API

The bank API is hosted by the organisation responsible for issuing payment cards. This
document describes the API at a high (architectural) level. Actual implementation may vary
considerably from this description.
 API Call Parameter Returns Description

Request new App credentials Card Generates a new payment card and
card Token assigns a card id (card token) to it. This
request is made by the banking app and
initiates the card issue process. The token
is used to create a Card Request via the
public API.

Request card Card Token Card Returns payment card details and
details details personalisation details. This request is
made only by CardWizard.

Activate card Card Token - Activates a previously issued card. This

request is made by the kiosk although it
uses CardHub server and CardWizard as
intermediaries.

6.5 The CardWizard API

The CardWizard API is hosted by EDS at a secure data centre. CardWizard has a rich and
complex API - the requests described here are a small subset of those available.

API Call Parameter Returns Description

Issue Card Card Token - Instructs CardWizard to retrieve card

details from the bank and print a payment
card on the kiosk printer

Activate card Card Token - Instructs CardWizard to activate an issued

card through the bank API.
6.6 APIs and the issuance user journey

This diagram describes the flow of information when a customer orders a payment card to be
issued through CardHub.

This table shows the flow of API usage in that process.

Id Action Actor Recipient API

1 Request new card App Bank Bank

2 Issue QR Code Bank CardHub CardHub Public

3.1 Fetch QR App CardHub CardHub Public

3.2 Locate Kiosk App CardHub CardHub Public

3.3 Select Kiosk App CardHub CardHub Public

4 Present QR App Kiosk -

5 Verify QR & Fetch token Kiosk CardHub CardHub Kiosk

6.1 Issue card Kiosk CardHub CardHub Kiosk

6.2 Issue Card CardHub CardWizard CardWizard

7 Request card data CardWizard Bank Bank

8 Print card CardWizard Kiosk (via VPN) -

9 Dispense card Kiosk Customer -

10.1 Activate card Kiosk CardHub CardHub Kiosk

10.2 Activate card CardHub CardWizard CardWizard

10.3 Activate card CardWizard Bank Bank

7. AWS Architecture

7.1 Overview
Cardhub Server will be hosted in AWS using a highly commoditized architecture.

● All services will reside in an AWS VPC behind an application load balancer
● A cluster of Docker containers will be managed by AWS Fargate
● Each container will run an individual API service.

The AWS Well-architected framework will be used as a reference architecture guide -

https://aws.amazon.com/architecture/well-architected/
7.2 Authentication and Authorisation
AWS offers two built-in methods for authentication:

● Cognito user pools​ for online authentication

● Lambda authorizers​ for automated API-API access

Each kiosk will be configured with an API key, as will other third parties. Users of the
management API will log in through a Cognito front-end.

7.3 VPC Network Addressing

AWS allows applications to allocate IANA private IP address space to VPC (Virtual Private
Cloud) infrastructure. Each defined VPC offers complete segregation from all others by default
although peering between VPCs is available if required. Care should be taken in the planning of
VPC address space to ensure networks that might need access to each other at a future date
do not overlap.

Address block Proposed usage

10.0.0.0/16 Reserved

10.1.0.0/16 CardHub Server production environment region 1

10.2.0.0/16 CardHub Server production environment region 2

10.3.0.0/16 CardHub Server production environment region 3

10.10.0.0/16 CardHub Server POC environment

10.11.0.0/16 QAC/Staging/Dev/Test environment 1

10.12.0.0/16 QAC/Staging/Dev/Test environment 2

10.13.0.0/16 QAC/Staging/Dev/Test environment 3

10.21.0.0/16 Development / Test kiosks

10.31.0.0/16 Kiosk block 1 (250 units)

 10.32.0.0/16 Kiosk block 2 (250 units)

10.40.0.0/16 CardHub Server POC environment (may be retired)

7.3 Scalability

In order to achieve transparent, reliable scalability, well architected rules should be enforced for
application build and deployment.

● App release feeds into a CI build

● Each build produces a single, unique machine image (AMI)
● AMIs are deployed automatically by AWS.
● Servers are stateless
● Servers may be started or stopped at any time without impact
● All logging is made externally
● There should be no direct login access to servers
● Servers should never be patched or changed once active.

Once such rules are applied, scaling can take place automatically whether a docker-based
(ECS/Fargate) or server-based architecture is used.

7.4 High Availability & Failover

Each service should run in multiple availability zones with the ability to fail over to a different
region (cold spare) if needed.

7.5 IAS Architecture - Terraform / CloudFormation

The CardHub AWS infrastructure should be described, built and maintained using an IAS
service - either Terraform or AWS CloudFormation are preferred. Any updates to the
infrastructure should be carried out using these services.

7.6 Logging & Monitoring - CloudWatch vs DataDog.

All services should log to a central repository - DataDog (​www.datadoghq.com​) is recommended
and is priced reasonably for low-volume sites.
8. Kiosk Network and VPN Architecture

8.1 OpenVPN Cloud Server

CardHub Kiosk units must be individually, reliably, and securely addressable from the central
CardHub server. This is necessary in the short term to allow CardWizard to send data to the
card printer, and in the long term to allow remote management. As an accepted industry
standard, OpenVPN is the first choice for this role. OpenVPN runs on both Linux and Windows
platforms and is supported by most VPN hardware routers.

Each kiosk will be assigned a /24 block of addresses within the 10.0.0.0/8 private address
range, and will be routable from the CardHub VPC (Virtual Private Cloud).

This diagram​ shows a typical end to end CardHub VPN architecture.

8.2 Kiosk VPN management

Within each kiosk, a single IP address will be assigned to each addressable device or service.
These will be directly addressable from the central CardHub server.

Device / Service Local IP address

LAN port management 10.x.x.2

WiFi port management 10.x.x.3

LTE port management 10.x.x.4

Card Printer 10.x.x.10

Kiosk Server 10.x.x.11

Kiosk Camera 10.x.x.12

DHCP dynamic allocation 10.x.x.100-10.x.x.249

Router management 10.x.x.254

8.3 VPN hardware proposal

The TELTONIKA RUT950 LTE 4G Router is proposed to manage communications within the
CardHub Kiosk. This industrial-level unit combines LTE/WiFi/Ethernet connectivity, hardware
VPN management, router, switch and firewall within one robust package.

Feature summary:

● Compact 4G router with SIM slot, 4x ethernet ports, 802.11n wi-fi

● UMTS Frequnces: FDD 800/850/900/1800/1900/2100/2600 MHz
● DC-HSPA+ up to 42 Mbps DL and 5.73 Mbps UL
● LTE up to 100 Mbps DL and 50 Mbps UL
● Multiple LTE FDD bands

Further details:

● http://www.rut950.com/wp-content/uploads/2015/05/RUT950-manual-v1-06.pdf
● https://www.amazon.co.uk/TELTONIKA-RUT950-LTE-4G-Router/dp/B00TKFKLCI

8.4 VPN Key/Certificate management

● VPN security keys will be managed centrally by the CardHub server and stored in AWS
Key Management Service.
● Keys will automatically be updated on a regular basis. Updates should happen without
any manual intervention
● It is proposed that a “lastresort” access is available, accessible only when authorised by
a trusted agent physically at the location of the kiosk.

The following certificate-related items are necessary for OpenVPN operation.

Item Description

Master Certificate Authority (CA) Organisation authorised to issue and manage

VPN certificates. In this case, Silver Arrow
Systems

Certificate Authority (CA) Certificate Certificate that is used to sign all other
 certificates that are used in the VPN
infrastructure to prove the authority of the CA

Certificate authority key Private (secret) key used to sign the CA

Certificate. This key should be stored
securely, ideally offline, and always on a
separate infrastructure to the VPN.

Server Certificate Certificate used to identify the central VPN

server. Must be signed with the CA certificate
to be valid

Server key Key used to sign the server certificate and fix
its identity to the server

Client Certificate Certificate used to identify each client

connecting to the VPN. Must be signed with
the CA certificate to be valid

Client Key Key used to sign the client certificate and fix
its identity to the client.

8.4 Assigned Kiosk Addresses (to be moved to spreadsheet / db)

8.4.1 EDC Development Kiosk - 10.21.0.0/24

VPN Endpoint: 172.21.0.3

WiFi hotspot: CardHub
WiFi password: SilverArrow
Admin password: CardHub875

Device / Service Local IP address

EDC Card Printer 10.21.0.10

Router management 10.21.0.254

8.4.2 RUT950 Router - 10.21.1.0/24

VPN Endpoint: 172.21.0.4

VPN login: cardhub-2101
WiFi hotspot: CardHub
WiFi password: SilverArrow
Admin password: CardHub875

Device / Service Local IP address

EDC Card Printer 10.21.1.10

Router management 10.21.1.254

8.4.3 RUT950 Router - 10.21.3.0/24

VPN Endpoint: 172.21.0.6

VPN login: cardhub-2103
VPN access password: Silver2103
WiFi hotspot: CardHub
WiFi password: SilverArrow
Admin password: CardHub875

Device / Service Local IP address

EDC Card Printer 10.21.2.10

Router management 10.21.2.254

9. Glossary
Glossary of terms used in the CardHub system architecture

Acronym Expansion Description Link

Software suite produced by SA Systems
that interacts with a kiosk and the https://cardhub-api-doc
CardHub Software & CardWizard software to manage the s.s3.eu-west-2.amazon
CardHub API production of credit cards aws.com/index.html
https://www.entrustdata
card.com/products/soft
Cardwizard Software Software suite that manages the ware/financial-instant-is
CardWizard & API production and issuance of credit cards suance-cardwizard
https://en.wikipedia.org/
Primary Account The long (usually 16 digit) number printed wiki/Payment_card_nu
PAN Number on the front of a credit card mber
Hardware Security Hardware module that allows secure
HSM Module encryption and decryption of data
 https://www.pcisecurity
standards.org/documen
ts/PCI_Card_Productio
Physical security requirements standard n_Physical_Security_R
for datacentres handling production of equirements_v2_Nov20
PCI-CP PCI Card production credit cards. 16.pdf
In this context, a CMS is a service/API
Card Management offered by banks that alows for the secure
CMS system issuance and management of credit cards
Provider of credit card issuance software https://www.entrustdata
EDC Entrust DataCard and printing hardware card.com/
Europay/Mastercard/V https://en.wikipedia.org/
EMV isa Technical standard for payment cards wiki/EMV
Internal ID used to refer to a credit card
during issuance/production. This is ​not
Card Id Credit card id the PAN (credit card number)
Remote monitoring API allowing CardWizard software to be
RMM management managed remotely.
Kiosk Gateway Front-end software library offering basic
KGS Service access to the CardWizard API
DTK Data transport key
PTK PIN transport key
KTK Key Transport Key
CBS Core Banking System Bank central software
A Javascript framework for building
NestJS scalable server-side applications https://nestjs.com/
In this context, a private network local to
CardHub and its kiosks allowing secure
Virtual Private and reliable exchange of data between
VPN Network them
Card Personalization Mastercard specification for card https://ims.ul.com/mast
CPV Validation personalisation ercard-cpv
VPA
https://en.wikipedia.org/
wiki/Smart_card_applic
Application Protocol The communication unit between a smart ation_protocol_data_un
APDU Data Unit card reader and a smart card. it
https://www.coalfire.co
CoalFire m/
VPC Virtual Private Cloud Network segregation unit within Amazon https://aws.amazon.co
 AWS. m/vpc/
Organisation trusted to sign secure
CA Certificate Authority certificates.