Specification — Generic Card

Link and Contact

This specification is licensed under the Creative Commons Attribution-NoDerivatives 4.0 International (CC BY-ND 4.0).

You are free to share — copy and redistribute this document in any medium or format for any purpose, even commercially — under the following terms:

Attribution — You MUST give appropriate credit to the Calypso Networks Association, provide a link to the license, and indicate if changes were made. You MAY do so in any reasonable manner, but not in any way that suggests the Calypso Networks Association endorses you or your use.
NoDerivatives — If you remix, transform, or build upon this document, you MAY NOT distribute the modified material.

No additional restrictions — You MAY NOT apply legal terms or technological measures that legally restrict others from doing anything the license permits.

Implementation grant — The NoDerivatives condition above applies to this specification document only — its text, tables and diagrams. It does not restrict the use of the technical information the document contains. The Calypso Networks Association hereby grants everyone an irrevocable, worldwide, royalty-free permission to use the information contained in this specification to design, develop, and distribute software implementations of this API, in any programming language, under the license of their choice.

The full license text is available at https://creativecommons.org/licenses/by-nd/4.0/.

1. Abstract

This document is the official technical specification of the Terminal Generic Card API standardised by the Calypso Networks Association (CNA). It defines, in a language-agnostic way, the interfaces, classes, enumerations, exceptions, structural relationships and behavioural requirements that any conforming implementation of the Terminal Generic Card API MUST satisfy.

The Terminal Generic Card API is part of the broader CNA Terminal API family. It exposes the minimal contract required to exchange raw APDUs with an ISO/IEC 7816-4 card that has been selected through the Terminal Reader API, without prescribing any specific card application model.

Document Status

Reference	YYMMDD-SP-CNATerminalAPI-GenericCard
Short name	CNA-TGC-API
Version	2.0.0-SNAPSHOT
Revision date	2026-07-20
Editor	Calypso Networks Association
Source repository	https://github.com/calypsonet/calypsonet-terminal-genericcard-uml-api
Reference license	Creative Commons Attribution-NoDerivatives 4.0 International (CC BY-ND 4.0)

Reference

YYMMDD-SP-CNATerminalAPI-GenericCard

Short name

CNA-TGC-API

Version

2.0.0-SNAPSHOT

Revision date

2026-07-20

Editor

Calypso Networks Association

Source repository

https://github.com/calypsonet/calypsonet-terminal-genericcard-uml-api

Reference license

Creative Commons Attribution-NoDerivatives 4.0 International (CC BY-ND 4.0)

The present document specifies the 2.0.0-SNAPSHOT of the Terminal Generic Card API. It defines a single, coherent baseline against which conforming implementations are evaluated; the Since column indicates the version in which each member was introduced.

Revision List

This section lists the high-level changes per version. The complete, fine-grained changelog is maintained in the CHANGELOG.md file at the root of the source repository.

Version / Date	Modifications
v2.0.0-SNAPSHOT 2026-07-20	Baseline.

Version / Date

Modifications

v2.0.0-SNAPSHOT
2026-07-20

Baseline.

2. Introduction

2.1. Purpose

The Terminal Generic Card API defines the contract used by terminal applications that need to exchange raw APDUs with an ISO/IEC 7816-4-compliant card without relying on a card-specific application layer (e.g. Calypso). It complements the Terminal Reader API (CNA-TR-API) by providing:

a card-selection extension that allows additional successful status words to be declared for the Select Application APDU,
a minimal transaction manager that prepares APDU commands, attaches an optional command identifier and an optional per-command duration bound (relay-attack countermeasure), and processes them as a single batch, returning the raw responses to the application.

Conforming implementations MUST guarantee interoperability with reader implementations of the CNA-TR-API specification.

2.2. Scope

This specification covers:

the factory used to instantiate the public types of the API,
the card-selection extension used to enrich the selection scenario for generic cards,
the transaction manager used to prepare and exchange APDUs with the selected card, including the per-command identifier and the per-command duration bound,
the property holder exposing the API version.

The following topics are out of scope:

the parsing of APDU payloads — the API exposes raw bytes only,
the application-level dialog with specific card products (covered by dedicated specifications),
the management of secure channels.

2.3. Conformance

A software product conforms to this specification if and only if:

it implements every interface and class defined in Chapter 5 with the operations and semantics prescribed in this document,
it preserves the structural relationships described in Chapter 4.

Throughout this specification, the key words MUST, MUST NOT, SHOULD, SHOULD NOT, RECOMMENDED, MAY and OPTIONAL are to be interpreted as described in RFC 2119 and RFC 8174 when, and only when, they appear in all capitals.

In conformance with RFC 2119, SHALL is equivalent to MUST; this specification uses MUST exclusively in order to avoid ambiguity.

2.4. Document Conventions

2.4.1. Naming

Type names follow UpperCamelCase; operation, parameter and enumeration-member names follow lowerCamelCase except for enumeration values which use UPPER_SNAKE_CASE. Names defined by this specification are reproduced as-is in the UML class diagram (Section 4.3).

2.4.2. Language-agnostic types

The following symbolic type names are used in operation signatures and are mapped, in each binding, to the closest equivalent native type. Implementations MUST preserve the semantic intent rather than the syntactic form.

Symbolic type Description Typical bindings

Symbolic type	Description	Typical bindings
`string`	Sequence of characters, UTF-8 encoded by default.	`String`, `string`, `str`.
`boolean`	Two-state truth value.	`boolean`, `bool`.
`byte`	Signed 8-bit value.	`byte`, `i8`.
`integer`	Signed 32-bit integer.	`int`, `Int32`.
`long`	Signed 64-bit integer.	`long`, `Int64`.
`byte array`	Ordered sequence of octets.	`byte[]`, `[u8]`, `bytes`.
`list<T>`	Ordered collection of `T` values, may contain duplicates.	`List<T>`, `Vec<T>`.
`void`	Indicates that an operation returns no value.	`void`, `Unit`, `None`.

string

Sequence of characters, UTF-8 encoded by default.

String, string, str.

boolean

Two-state truth value.

boolean, bool.

byte

Signed 8-bit value.

byte, i8.

integer

Signed 32-bit integer.

int, Int32.

long

Signed 64-bit integer.

long, Int64.

byte array

Ordered sequence of octets.

byte[], [u8], bytes.

list<T>

Ordered collection of T values, may contain duplicates.

List<T>, Vec<T>.

void

Indicates that an operation returns no value.

void, Unit, None.

2.4.3. Type tables

Each interface, class, enumeration and exception defined in this document is described by a table of the form:

Name	The type’s normalized name.
Kind	The category of the type (interface, class, enumeration, exception, etc.).
Namespace	The namespace in which the type is defined.
Extends	The type extended by this type, when applicable.
Implements	The interface implemented by this type, when applicable.
Since	The version of the API in which the type was introduced.
Purpose	A normative description of the type’s responsibility.
See also	Cross-references to related operations or types, each a hyperlink to the corresponding table. Present only when applicable.

Name

The type’s normalized name.

Kind

The category of the type (interface, class, enumeration, exception, etc.).

Namespace

The namespace in which the type is defined.

Extends

The type extended by this type, when applicable.

Implements

The interface implemented by this type, when applicable.

Since

The version of the API in which the type was introduced.

Purpose

A normative description of the type’s responsibility.

2.4.4. Operation tables

Each operation defined in this document is described by a table of the form:

Signature	The operation’s language-agnostic signature.
Since	The version of the API in which the operation was introduced.
Description	A normative description of the operation’s behaviour.
Parameters	A description of each input parameter.
Returns	A description of the returned value, if any.
Throws	A list of exceptional conditions, each mapped to a specific exception type.
See also	Cross-references to related operations or types, each a hyperlink to the corresponding table. Present only when applicable.

Signature

The operation’s language-agnostic signature.

Since

The version of the API in which the operation was introduced.

Description

A normative description of the operation’s behaviour.

Parameters

A description of each input parameter.

Returns

A description of the returned value, if any.

Throws

A list of exceptional conditions, each mapped to a specific exception type.

2.4.5. Operation contracts

To avoid repetition, the following rules apply to every operation table in Chapter 5 and are therefore not restated for each operation:

Non-null arguments. Unless explicitly stated otherwise, every input parameter MUST be non-null. An implementation MUST raise IllegalArgumentException if a null value is supplied. This implicit null check is not repeated in the Throws row, which states None. when no other exception can occur.
Non-null results. Unless the return type is marked nullable (T?) or the Returns row states otherwise, an operation returns a non-null value.
Collections. Unless the return type is marked nullable (T?), an operation whose return type is a collection (e.g. list, set, map) returns an empty collection rather than null.
Fluent composition. Builder-style operations return the current instance so that calls can be chained.

2.4.6. Concurrency

Unless explicitly stated otherwise, the stateful types defined by this specification are not thread-safe. A given instance MUST be accessed from a single thread at a time; concurrent use of the same instance without external synchronisation results in undefined behaviour. Distinct instances MAY be used concurrently.

2.5. References and Resources

2.5.1. Calypso References

References to CNA Terminal APIs designate the indicated major version; any later release within the same major is backward-compatible per that API’s evolution policy.

Reference	Document
[CNA-TR-API]	CNA Terminal API — Reader (SP-CNATerminalAPI-Reader), version 3.0, Calypso Networks Association.

Reference

Document

[CNA-TR-API]

CNA Terminal API — Reader (SP-CNATerminalAPI-Reader), version 3.0, Calypso Networks Association.

2.5.2. Normative References

Reference	Document
[RFC 2119]	Key words for use in RFCs to Indicate Requirement Levels, S. Bradner, March 1997.
[RFC 8174]	Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words, B. Leiba, May 2017.
[ISO/IEC 7816]	Identification cards — Integrated circuit cards.

Reference

Document

[RFC 2119]

Key words for use in RFCs to Indicate Requirement Levels, S. Bradner, March 1997.

[RFC 8174]

Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words, B. Leiba, May 2017.

[ISO/IEC 7816]

Identification cards — Integrated circuit cards.

2.5.3. External Resources

Resource	Link
Calypso Networks Association	https://calypsonet.org
Terminal APIs website	https://terminal-api.calypsonet.org
Terminal APIs documentation	https://docs.terminal-api.calypsonet.org

Resource

Link

Calypso Networks Association

https://calypsonet.org

Terminal APIs website

https://terminal-api.calypsonet.org

Terminal APIs documentation

https://docs.terminal-api.calypsonet.org

3. Glossary and Acronyms

3.1. Glossary

Term	Definition
APDU	Application Protocol Data Unit, the message format used between the terminal and the card, as defined in ISO/IEC 7816-3.
Card Reader	Hardware or software component capable of detecting cards and exchanging data with them.
Command Identifier	Application-supplied integer attached to a prepared APDU, used to retrieve the corresponding response or to identify the failing command in case of error.
Relay Attack	Software-level attack consisting in interposing a relay between the card and the terminal to redirect APDU exchanges to a distant card.

Term

Definition

APDU

Application Protocol Data Unit, the message format used between the terminal and the card, as defined in ISO/IEC 7816-3.

Card Reader

Hardware or software component capable of detecting cards and exchanging data with them.

Command Identifier

Application-supplied integer attached to a prepared APDU, used to retrieve the corresponding response or to identify the failing command in case of error.

Relay Attack

Software-level attack consisting in interposing a relay between the card and the terminal to redirect APDU exchanges to a distant card.

3.2. Acronyms

Abbreviation	Expansion
AID	Application IDentifier
APDU	Application Protocol Data Unit
CNA	Calypso Networks Association
ISO	International Organization for Standardization
SW	Status Word

Abbreviation

Expansion

AID

Application IDentifier

APDU

Application Protocol Data Unit

CNA

Calypso Networks Association

ISO

International Organization for Standardization

Status Word

4. Architectural Overview

4.1. Functional positioning

Figure 1. Terminal Generic Card API — Architecture Overview

4.2. Logical namespaces

Namespace Role Summary

Namespace	Role	Summary
`genericcard`	Public API	Factory, selection extension and transaction manager. Properties.

genericcard

Public API

Factory, selection extension and transaction manager. Properties.

4.3. UML class diagram

The following UML class diagram provides a visual representation of the types and relationships defined by this specification:

Figure 2. Terminal Generic Card API — UML Class Diagram

5. API Specification

5.1. Classes

5.1.1. Generic Card API Properties

Name	`GenericCardApiProperties`
Kind	Final class
Namespace	`genericcard`
Since	1.0
Purpose	Exposes the immutable properties of the Terminal Generic Card API.

Name

GenericCardApiProperties

Kind

Final class

Namespace

genericcard

Since

1.0

Purpose

Exposes the immutable properties of the Terminal Generic Card API.

Constants

Name Type Since Description

Name	Type	Since	Description
`VERSION`	`string`	1.0	String representation of the version of the API implemented by the conforming binding (e.g. `"2.0"`). The value is a dotted decimal of the form `MAJOR.MINOR`.

VERSION

string

1.0

String representation of the version of the API implemented by the conforming binding (e.g. "2.0"). The value is a dotted decimal of the form MAJOR.MINOR.

The GenericCardApiProperties type cannot be instantiated; it exposes only static properties.

5.2. API Interfaces

5.2.1. Card Transaction Manager

Name	`CardTransactionManager`
Kind	Interface
Namespace	`genericcard`
Extends	`IsoCardTransactionManager` (CNA-TR-API)
Since	1.0
Purpose	Provides the basic operations required to prepare, identify and process APDU exchanges with an ISO/IEC 7816-4 card. The stereotype on `IsoCardTransactionManager` grants access to the multi-channel cast `asMultichannelCardTransactionManager()` defined by CNA-TR-API when the underlying card supports multi-channel. An instance is obtained via `GenericCardApiFactory.createCardTransaction`.

Name

CardTransactionManager

Kind

Interface

Namespace

genericcard

Extends

IsoCardTransactionManager (CNA-TR-API)

Since

1.0

Purpose

Provides the basic operations required to prepare, identify and process APDU exchanges with an ISO/IEC 7816-4 card. The stereotype on IsoCardTransactionManager grants access to the multi-channel cast asMultichannelCardTransactionManager() defined by CNA-TR-API when the underlying card supports multi-channel. An instance is obtained via GenericCardApiFactory.createCardTransaction.

The CardTransactionManager uses a prepare/process model inherited from CNA-TR-API: the application prepares APDU commands with the prepareCommand overloads and processes them through the inherited processCommands() operation. Each prepared command MAY carry an optional command identifier (idCommand) supplied by the application, used to retrieve the corresponding response or to identify the failing command in case of error. Each prepared command MAY also carry an optional maximum duration (maxDuration, in milliseconds) used to detect a relay attack at the individual-command level.

Get Last Execution Response

Signature	`getLastExecutionResponse(idCommand: integer) → byte array?`
Since	2.0
Description	Returns the response of the command identified by `idCommand`. If several prepared commands share the same identifier, the response of the last matching command is returned. The value returned for a given identifier is the same as the corresponding element of `getLastExecutionResponses`.
Parameters	`idCommand` — the application-supplied identifier of the command whose response is requested.
Returns	The non-empty response bytes, or `null` if no command with the supplied identifier produced a response.
Throws	None.

Signature

getLastExecutionResponse(idCommand: integer) → byte array?

Since

2.0

Description

Returns the response of the command identified by idCommand. If several prepared commands share the same identifier, the response of the last matching command is returned. The value returned for a given identifier is the same as the corresponding element of getLastExecutionResponses.

Parameters

idCommand — the application-supplied identifier of the command whose response is requested.

Returns

The non-empty response bytes, or null if no command with the supplied identifier produced a response.

Throws

None.

Get Last Execution Responses

Signature	`getLastExecutionResponses() → list<byte array>`
Since	2.0
Description	Returns the responses collected during the last call to `processCommands()`, in the order in which the commands were prepared. This operation does not alter the internal state of the manager: the list of responses remains available until `processCommands()` is called again, at which point it is replaced by the new set of responses.
Returns	A `list<byte array>` representing the command responses, in the order in which the commands were sent; empty if no command has been executed.
Throws	None.

Signature

getLastExecutionResponses() → list<byte array>

Since

2.0

Description

Returns the responses collected during the last call to processCommands(), in the order in which the commands were prepared.

This operation does not alter the internal state of the manager: the list of responses remains available until processCommands() is called again, at which point it is replaced by the new set of responses.

Returns

A list<byte array> representing the command responses, in the order in which the commands were sent; empty if no command has been executed.

Throws

None.

Prepare Command (APDU)

Signature	`prepareCommand(apdu: byte array) → CardTransactionManager`
Since	2.0
Description	Prepares an APDU command without command identifier nor duration bound.
Parameters	`apdu` — a non-empty `byte array` containing the raw APDU command.
Returns	The current instance (`CardTransactionManager`).
Throws	None.

Signature

prepareCommand(apdu: byte array) → CardTransactionManager

Since

2.0

Description

Prepares an APDU command without command identifier nor duration bound.

Parameters

apdu — a non-empty byte array containing the raw APDU command.

Returns

The current instance (CardTransactionManager).

Throws

None.

Prepare Command (APDU, ID Command)

Signature	`prepareCommand(` `apdu: byte array,` `idCommand: integer` `) → CardTransactionManager`
Since	2.0
Description	Prepares an APDU command with an application-supplied identifier. The identifier MAY later be used to retrieve the corresponding response via `getLastExecutionResponse`.
Parameters	`apdu` — a non-empty `byte array` containing the raw APDU command. `idCommand` — the application-supplied identifier of this command.
Returns	The current instance (`CardTransactionManager`).
Throws	None.

Signature

prepareCommand(
apdu: byte array,
idCommand: integer
) → CardTransactionManager

Since

2.0

Description

Prepares an APDU command with an application-supplied identifier. The identifier MAY later be used to retrieve the corresponding response via getLastExecutionResponse.

Parameters

apdu — a non-empty byte array containing the raw APDU command.
idCommand — the application-supplied identifier of this command.

Returns

The current instance (CardTransactionManager).

Throws

None.

Prepare Command (APDU, ID Command, Max Duration)

Signature	`prepareCommand(` `apdu: byte array,` `idCommand: integer,` `maxDuration: long` `) → CardTransactionManager`
Since	2.0
Description	Prepares an APDU command with an application-supplied identifier and a maximum tolerated exchange duration. The effective duration of the corresponding APDU exchange is measured, and an `InvalidCardResponseException` (CNA-TR-API) is raised if it exceeds the declared bound; the exception message identifies the offending command.
Parameters	`apdu` — a non-empty `byte array` containing the raw APDU command. `idCommand` — the application-supplied identifier of this command. `maxDuration` — the maximum tolerated duration of the APDU exchange, in milliseconds.
Returns	The current instance (`CardTransactionManager`).
Throws	None at preparation time. The duration check is performed at processing time.

Signature

prepareCommand(
    apdu: byte array,
    idCommand: integer,
    maxDuration: long
) → CardTransactionManager

Since

2.0

Description

Prepares an APDU command with an application-supplied identifier and a maximum tolerated exchange duration. The effective duration of the corresponding APDU exchange is measured, and an InvalidCardResponseException (CNA-TR-API) is raised if it exceeds the declared bound; the exception message identifies the offending command.

Parameters

apdu — a non-empty byte array containing the raw APDU command.
idCommand — the application-supplied identifier of this command.
maxDuration — the maximum tolerated duration of the APDU exchange, in milliseconds.

Returns

The current instance (CardTransactionManager).

Throws

None at preparation time. The duration check is performed at processing time.

5.2.2. Generic Card API Factory

Name	`GenericCardApiFactory`
Kind	Interface
Namespace	`genericcard`
Since	1.0
Purpose	Factory used by the application to obtain instances of the public types provided by the API.

Name

GenericCardApiFactory

Kind

Interface

Namespace

genericcard

Since

1.0

Purpose

Factory used by the application to obtain instances of the public types provided by the API.

The GenericCardApiFactory is the single entry point through which the application instantiates the public types of the API. It is provided as a single instance whose accessors each return a fresh, fully initialised object.

Create Card Transaction

Signature	`createCardTransaction(` `reader: CardReader,` `card: SmartCard` `) → CardTransactionManager`
Since	1.0
Description	Returns a new, freshly initialised `CardTransactionManager`, bound to the supplied reader and to the initial card data provided by the selection process.
Parameters	`reader` (`CardReader` (CNA-TR-API)) — the reader through which the card is reached. `card` (`SmartCard` (CNA-TR-API)) — the initial card data provided by the selection process.
Returns	A `CardTransactionManager`.
Throws	None.

Signature

createCardTransaction(
reader: CardReader,
card: SmartCard
) → CardTransactionManager

Since

1.0

Description

Returns a new, freshly initialised CardTransactionManager, bound to the supplied reader and to the initial card data provided by the selection process.

Parameters

reader (CardReader (CNA-TR-API)) — the reader through which the card is reached.
card (SmartCard (CNA-TR-API)) — the initial card data provided by the selection process.

Returns

A CardTransactionManager.

Throws

None.

Create Generic Card Selection Extension

Signature	`createGenericCardSelectionExtension() → GenericCardSelectionExtension`
Since	1.0
Description	Returns a new, freshly initialised `GenericCardSelectionExtension`.
Returns	A `GenericCardSelectionExtension`.
Throws	None.

Signature

createGenericCardSelectionExtension() → GenericCardSelectionExtension

Since

1.0

Description

Returns a new, freshly initialised GenericCardSelectionExtension.

Returns

A GenericCardSelectionExtension.

Throws

None.

5.2.3. Generic Card Selection Extension

Name	`GenericCardSelectionExtension`
Kind	Interface
Namespace	`genericcard`
Extends	`CardSelectionExtension` (CNA-TR-API)
Since	1.0
Purpose	Extends the `CardSelectionExtension` interface defined by the Terminal Reader API to expose a way to declare additional successful status words for the Select Application APDU. An instance is obtained via `GenericCardApiFactory.createGenericCardSelectionExtension`.

Name

GenericCardSelectionExtension

Kind

Interface

Namespace

genericcard

Extends

CardSelectionExtension (CNA-TR-API)

Since

1.0

Purpose

Extends the CardSelectionExtension interface defined by the Terminal Reader API to expose a way to declare additional successful status words for the Select Application APDU. An instance is obtained via GenericCardApiFactory.createGenericCardSelectionExtension.

Add Successful Status Word

Signature	`addSuccessfulStatusWord(statusWord: integer) → GenericCardSelectionExtension`
Since	1.0
Description	Adds a status word to the list of those considered successful for the Select Application APDU. Note: the list initially contains the standard successful status word `9000h`; each call adds to the existing set and never removes that implicit entry.
Parameters	`statusWord` — a positive `integer` lower than or equal to `FFFFh`.
Returns	The current instance (`GenericCardSelectionExtension`).
Throws	None.

Signature

addSuccessfulStatusWord(statusWord: integer) → GenericCardSelectionExtension

Since

1.0

Description

Adds a status word to the list of those considered successful for the Select Application APDU.

Note: the list initially contains the standard successful status word 9000h; each call adds to the existing set and never removes that implicit entry.

Parameters

statusWord — a positive integer lower than or equal to FFFFh.

Returns

The current instance (GenericCardSelectionExtension).

Throws

None.