Heading

Document (project) Title: WP7 – 01a – API for Legacy Integration

Version (release): 1.21

Date: 25th March 2004

Document History

Document location:

Date / Location of file / Contact
25th March 2004 / Smart Store

Revision History:

Revision date / Summary of changes / Editor
30th March 2004 / Editing to ensure the document is in line with the look & feel of all output documents. Production of an abstract. Addition of the standard glossary. / PFA Research

Approvals:

Version / Date / Approver Name / Approver Title / Approval date

Distribution – distributed to:

Version / Date / Name / Title

API for Legacy Integration

Report WP7 – 01a

Version 1.122.0

March 2004

© Bolton Metropolitan Borough Council for the National Smart Card Project

WP7-01a - API for Legacy Integration v2.01.2WP7-01a - API for Legacy Integration v1.2 Release 02/11/2018

1.Abstract

WP7 of the National Smart card project This section of the National Smart Card Project (NSCP) defines and pilots a Cross-Regional Local Authority sSmart card sScheme.

Such a scheme includes use of the Smart card for transport across the region (using ITSO Ticketing), use by applications (such as Library and Leisure Systems) that just utilise the Smart card for identification and enrolment, and use by applications (such as School Systems) that require an electronic purse.

This document supports the usage of the Smart card as an identification and enrolment device, by defining an API that Application Developers can use for simple Integration with the LA Smart card for these purposes.

The Smart card can also be used to prove eligibility for concessions without the need for producing paper evidence, and the API supports reading the eligibility data and its expiry dates.

The API is designed to support Web-based applications, PC Win32 applications, and client Java applications., but not Unix dumb terminal character-based applications.

After discussions with Bolton and Blackburn suppliers, only the ActiveX version of the API has been productised. The ActiveX control supports PC Win32 and Web-based applications. There is no productised version of the Java versions of the API, and hence no native support for Java applications. However, a demonstration version of the Java applet version of the API has been produced.

Use cases for typical usage of the Smart card by such applications are described, as well as the detail of the API.

Table of Contents

1.Abstract

2.Introduction

2.1Scope

2.2Terminology

2.3Overview

3.Use Cases

Example Scenario 1 - New User

3.1

3.2Example Scenario 2 – Concessionary Membership

3.3Example User Experience

3.4Change Identifier to LA Smart Card

3.5Identify User

4.API Details

4.1Introduction

4.2Security

4.3API Methods

4.4APIs provided

5.Web-based applications

5.1Architecture for Web application

5.2Control Flow

5.3Scripting Examples

5.4Application Changes for Web applications

6.Client Applications

6.1PC Win32 Applications

6.2Java Client Applications

6.3Application Changes for client applications

7.Appendix 1 – Smart Card APIs

7.1PC/SC

7.2OpenCard Framework Java API

7.3PKCS#11

7.4Microsoft Crypto API (MS CAPI)

8.Appendix 2 – Analysis of different API Styles

8.1Who has Control?

8.2Use of notification events

8.3Contact and Contactless Smart Cards

8.4ActiveX control

8.5Java Bean

8.6Java Applet

8.7Microsoft .NET

8.8Keyboard Emulation

8.9Background application

9.Appendix 3 – Details of ActiveX Control

9.1Get Issuer

9.2Get Authentication Level

9.3Get Data Item

9.4Get Error Code

9.5Test mode

9.6Data Types for other languages

10.Appendix 4 – National Smart Card Project Glossary

1.Abstract...... 3

2.Introduction...... 5

2.1Scope...... 5

2.2Terminology...... 5

2.3Document Cross References...... 65

2.4Overview...... 6

3.Use Cases...... 7

3.1...... 7

3.2Example Scenario 2 – Concessionary Membership...... 8

3.3Example User Experience...... 8

3.4Change Identifier to LA Smart Card...... 9

3.5Identify User...... 12

4.API Details...... 13

4.1Introduction...... 13

4.2Security...... 13

4.3API Methods...... 14

4.4APIs provided...... 14

5.Web-based applications...... 16

5.1Architecture for Web application...... 16

5.2Control Flow...... 17

5.3Scripting Examples...... 17

5.4Application Changes for Web applications...... 17

6.Client Applications...... 18

6.1PC Win32 Applications...... 18

6.2Java Client Applications...... 18

6.3Application Changes for client applications...... 18

7.Appendix 1 – Smart Card APIs...... 19

7.1PC/SC...... 19

7.2OpenCard Framework Java API...... 19

7.3PKCS#11...... 19

7.4Microsoft Crypto API (MS CAPI)...... 19

8.Appendix 2 – Analysis of different API Styles...... 20

8.1Who has Control?...... 20

8.2Use of notification events...... 20

8.3Contact and Contactless Smart Cards...... 21

8.4ActiveX control...... 21

8.5Java Bean...... 21

8.6Java Applet...... 21

8.7Microsoft .NET...... 21

8.8Keyboard Emulation...... 22

8.9Background application...... 22

9.Appendix 3 – Details of ActiveX Control...... 23

9.1Get Issuer...... 23

9.2Get Authentication Level...... 23

9.3Get Data Item...... 23

9.4Get Error Code...... 26

9.5Test mode...... 26

9.6Data Types for other languages...... 26

10.Appendix 4 – Glossary...... 27

2.Introduction

2.1Scope

This document ent, which is part of deliverable 7.1v2 of WP7 of the National Smart Card Project:

Ddescribes an API that:

  • Makes it simple for Application Developers to use a Local Authority smart card as identification token and to support enrolment of the citizen using the data on the card.
  • Supports reading entitlement data (with corresponding expiry dates) from the card, so that the card can be used as evidence of eligibility for concessions.
  • Gives Use Cases of how the API will typically be used by Applications, such as Library Systems, Leisure Systems and School Systems.

This version of the document does not cover usage of electronic purse on the card.

After discussions with Bolton and Blackburn suppliers, only the ActiveX version of the API has been productised, but a demonstration Java applet version is also available. The ActiveX version is described in section 4.

2.2Terminology

LALocal Authority

CMSCard Management System

CRMCustomer Relationship Management

CCDACommon Cardholder Data Application

PC/SCStandard API for PC access to ISO 7816 Standard smartcards

Cardholder numberThe first 14 digits of the card number (without the issue number). This is a visible (printed on the card) unique identifier of the citizen that does not change when a card is reissued.

ITSOIntegrated Transport Smart Card organisation

PINPersional Identification Number

OCFOpenCard Framework. A Java API for smartcard access.

Trust Level 1UK Government defined authentication level that requires that the citizen’s real world identity is verified, but only on the balance of probabilities. Minimal damage is done if the citizen is not who they claim to be.

eURIExtended User-Related Information. A European standard. See CWA 13987: 2003 Part 1.

MiFarePhilips productstandards for storing and accessing data on Type A contactless card. This is supported by the NSCP JCOP30 cards.

NSCPNational Smart Card Project

2.3 Document Cross References

[1]WP7National Smart Card Project Work Package Seven Definition

[2]WP9National Smart Card Project Work Package Nine Definition

[3]The Strategic Local Authority Smart Card Architecture

[4]BMBC Pilot Specification

2.42.3Overview

This API is for use by applications such as library systems, leisure systems and school systems, to allow enrolment of new users, and identification of existing users using an LA smartcard.

It requires the application to be able to use the cardholder number on the LA card as the customer identifier. The cardholder number is read from the card using the standard PC/SC API.

For functions such as registration of new users, the customer details (name, address, contact details, etc.) are read from the card using the PC/SC API. Eligibility data can also be read from the card and can be used as proof of eligibility for concessions and mapped onto the concession types by the specific application.

The Integration API is designed for simple integration with existing Web or PC applications. The API will work identically with all Contact readers and Contactless readers that have PC/SC drivers.

Although application developers could use the underlying PC/SC API themselves to access the data on an LA smartcard, this high-level API makes the task much simpler, and standardises the way that different applications work. The PC/SC API is a low-level complex API. This high-level API hides the detail of how to identify the LA smartcard, and how to access data using the CCDA applet. It also allows details of the implementation of LA smartcards to change in the future without impact on the Legacy Applications.

Note that the LA smartcards also allow the card number to be read using the MiFare interface, and identification can be done using MiFare readers directly, without using this API.

3.Use Cases

The following Use Cases are supported by this API:

  • New User (including concessionary membership)
  • Change identifier to LA smartcard
  • Identify User

Note that in the scenarios below a contact or a contactless smartcard reader may be used, but the Use cases are written as if it is a contact reader. Only contactless readers that support the PC/SC API could be used for enrolment.

Example Scenario 1- New User

3.1

A citizen with an LA smartcard attends a library in the same or a neighbouring LA. He or she is not a member of the library. The data on the smartcard is used to enrol the citizen.

3.1.1Example User Experience

  1. The citizen asks to join the library and presents their LA smartcard.
  2. The librarian checks the photograph on the card matches the citizen and confirms their name.
  3. A check that the card is not on a hotlist is made. An entry in the system could have been made when the hotlist entry was received, and marked as invalid, so that attempting to use the card fails.
  4. The librarian inserts the smartcard in the reader and selects the “Enrol using smartcard” option from the library application.
  5. The application checks that the card is an LA card from one of the LAs whose cards it supports, and that the trust level of the card is at least 1 to confirm that the LA has checked the citizen’s details.
  6. The application reads the required data items (name, address, etc.) from the smartcard and presents them on an enrolment screen for the librarian to check. The details include the cardholder number, which will be used as the citizen’s library reference number. The various address fields should be mapped onto the address format supported by the application
  7. The librarian checks that the citizen is eligible to be a member of the library from their address and other details.
  8. The librarian checks the details on the form with the citizen and makes any minor changes that the citizen requires (e.g. a new mobile phone number). If such changes are made, the librarian encourages the citizen to contact the LA help desk, so that changes are made to the customer account and will be written to the card, when it is presented at a suitable access point (when the Card Management System supports this).
  1. The librarian presses the “Enrol” button.
  2. The library application checks that the card number is not in use as a reference number, and optionally searches for duplicate entries to ensure that the citizen is not already registered with a different library reference number.
  3. If all checks succeed the citizen is registered as a library member, and can use their LA card to identify themselves in the future.

Note that the application may have its own internal customer reference number, and may need to implement a link table to cross-reference the LA cardholder number, to enable it to be used to identify the customer.

3.2Example Scenario 2 – Concessionary Membership

A citizen with an LA smartcard attends a Leisure Centre in the same or a neighbouring LA. He or she is not a member of the Leisure Centre. The data on the smartcard is used to enrol the citizen and to prove eligibility for a particular level of concessionary membership.

3.3Example User Experience

  1. The citizen asks to join the Leisure Centre at a particular concessionary level and presents their LA smartcard.
  2. The Leisure Centre staff member checks the photograph on the card matches the citizen and confirms their name.
  3. A check that the card is not on a hotlist is made. An entry in the system could have been made when the hotlist entry was received, and marked as invalid, so that attempting to use the card fails.
  4. The Leisure Centre staff member inserts the smartcard in the reader and selects the “Enrol using smartcard” option from the leisure centre application.
  5. The application checks that the card is an LA card from one of the LAs whose cards it supports, and that the trust level of the card is at least 1 to confirm that the LA has checked the citizen’s details.
  6. The application reads the required data items and expiry dates and maps them onto the evidence required for the concession. For example the concession could be for students, unemployed people and people on low incomes. For this the fields “Student”, “StudentExpDate”, “Unemployed”, “UmemployedExpDate”, “Income Level Code” and “IncomeLevelExpDate” would be checked.
  7. If the smartcard evidence has expired, the citizen is asked to get it updated or bring paper evidence in.
  1. If the check succeeds, the application reads the required data items (name, address, etc.) from the smartcard and presents them on an enrolment screen for the Leisure Centre staff member to check. The details include the cardholder number, which will be used as the citizen’s leisure centre reference number. The various address fields should be mapped onto the address format supported by the application.
  2. The Leisure Centre staff member checks that the citizen is eligible to be a member of the leisure centre from their address and other details.
  3. The Leisure Centre staff member checks the details on the form with the citizen and makes any minor changes that the citizen requires (e.g. a new mobile phone number). If such changes are made, the Leisure Centre staff member encourages the citizen to contact the LA help desk, so that changes are made in the customer account and will be written to the card, when it is presented at a suitable access point (when the Card Management System supports this).
  4. The Leisure Centre staff member presses the “Enrol” button.
  5. The application checks that the card number is not in use as a reference number, and optionally searches for duplicate entries to ensure that the citizen is not already registered with a different leisure centre reference number.
  6. If all checks succeed the citizen is registered as a leisure centre member, and can use their LA card to identify themselves in the future.

Note that the application may have its own internal customer reference number, and may need to implement a link table to cross-reference the LA cardholder number, to enable it to be used to identify the customer.

3.4Change Identifier to LA Smart Card

3.4.1Example Scenario 1

A citizen is already a library member and has a library card, but now has an LA smartcard. They want to use their smartcard as their library card.

3.4.2Example User Experience

  1. The citizen attends the library and presents both their existing library card and their LA smartcard.
  2. The librarian looks the user up using their library card and checks they are an existing member.
  3. If the existing library card was on a hotlist, the existing entry will have been deleted or invalidated, and attempting to use it will fail.
  4. The librarian checks the photograph on the LA smartcard matches the citizen and confirms their name.
  5. The librarian inserts the smartcard in the reader and selects the “Change Identifier to LA smartcard” option from the library application.
  6. The application checks that the card is an LA card from one of the LAs whose cards it supports, and that the trust level of the card is at least 1 to confirm that the LA has checked the citizen’s details.
  7. The application reads the data from the card and presents an “Update Details” screen, which highlights any differences from the known customer details. The card number is used as the new library reference number.
  8. The citizen is asked to confirm the detail changes, and is allowed to make minor changes to the details (such as a new mobile phone number). If such changes are made, the librarian encourages the citizen to contact the LA help desk, so that changes are made in the customer account and will be written to the card, when it is presented at a suitable access point (when the Card Management System supports this).
  9. The librarian presses “Save” and the details are updated. The cardholder number is now the citizen’s library reference number.
  10. The librarian keeps the old library card. (Alternatively, the library application may allow the old card to still be used).

Note that the application may have a mandatory internal customer identifier, which may be the library reference number of the old library card. In this case, the LA cardholder number may be stored in a link table that cross-references the internal customer identifier. Ideally identification by the old library reference number should be invalidated.

3.4.3Example Scenario 2

A citizen is already a library member, but now has an LA smartcard. They want to use their smartcard as their library card. They have lost or forgotten their existing library card.

3.4.4Example User Experience

  1. The citizen attends the library and presents their LA smartcard, but says that he or she is an existing library member, but have lost or forgotten their library card.
  2. The librarian checks the photograph on the card matches the citizen and confirms their name.
  3. The librarian inserts the smartcard in the reader and selects the “Find customer using smartcard” option.
  4. The application checks that the card is an LA card from one of the LAs whose cards it supports, and that the trust level of the card is at least 1 to confirm that the LA has checked the citizen’s details.
  5. The library application presents a search screen, fills it in using details read from the smartcard and searches for the customer.
  6. If the existing library card is on a hotlist, the entry for the citizen will have been invalidated so that it will not be found.
  7. If the customer entry is not found the librarian asks the citizen for possible differences in details and repeats the search until the entry is found, or all possibilities have been exhausted.
  8. The application reads the data from the card and presents an “Update Details” screen, which highlights any differences from the known customer details. The card number is used as the new library reference number.
  9. The citizen is asked to confirm the detail changes, and is allowed to make minor changes to the details (such as a new mobile phone number). If such changes are made, the librarian encourages the citizen to contact the LA help desk, so that changes are made in the customer account and will be written to the card, when it is presented at a suitable access point (when the Card Management System supports this).
  10. The librarian presses “Save” and the details are updated. The cardholder number is now the citizen’s library reference number.
  11. The old library card will no longer be valid. (Alternatively, if the card was just forgotten, not lost, the library application may allow the old card to still be used).

3.5IIdentify User

3.5.1Example Scenario

The citizen has registered to use their LA smartcard as their library card following one of the “New User” or “Change Identifier to LA smartcard” scenarios above.