ISO/IEC TS 23465-2:2023

Card and security devices for personal identification — Programming interface for security devices — Part 2: API definition

This document describes the following aspects of the programming interface between the client application dealing with the security device and the proxy, based on the framework outlined in ISO/IEC 23465-1: — the generic API definition; — state and security models for use cases; — class and API definitions of functionality, defined in other standards, e.g. the ISO/IEC 7816 series.

Cartes et dispositifs de sécurité pour l’identification personnelle — L'interface du logiciel pour dispositifs de sécurité — Partie 2: Definition de API

General Information

• Status: Published
• Publication Date: 14-Feb-2023
• ICS: 35.240.15 - Identification cards. Chip cards. Biometrics
• Technical Committee: ISO/IEC JTC 1/SC 17 - Cards and security devices for personal identification
• Drafting Committee: ISO/IEC JTC 1/SC 17/WG 4 - Generic interfaces and protocols for security devices
• Current Stage: 6060 - International Standard published
• Start Date: 15-Feb-2023
• Due Date: 26-Feb-2023
• Completion Date: 15-Feb-2023

Standards Content (Sample)

TECHNICAL ISO/IEC TS
SPECIFICATION 23465-2
First edition
2023-02
Card and security devices for personal
identification — Programming
interface for security devices —
Part 2:
API definition
Cartes et dispositifs de sécurité pour l’identification personnelle —
L'interface du logiciel pour dispositifs de sécurité —
Partie 2: Definition de API
Reference number
ISO/IEC TS 23465-2:2023(E)
© ISO/IEC 2023

---------------------- Page: 1 ----------------------
ISO/IEC TS 23465-2:2023(E)
COPYRIGHT PROTECTED DOCUMENT
© ISO/IEC 2023
All rights reserved. Unless otherwise specified, or required in the context of its implementation, no part of this publication may
be reproduced or utilized otherwise in any form or by any means, electronic or mechanical, including photocopying, or posting on
the internet or an intranet, without prior written permission. Permission can be requested from either ISO at the address below
or ISO’s member body in the country of the requester.
ISO copyright office
CP 401 • Ch. de Blandonnet 8
CH-1214 Vernier, Geneva
Phone: [phone]
Email: [e-mail]
Website: www.iso.org
Published in Switzerland
ii
  © ISO/IEC 2023 – All rights reserved

---------------------- Page: 2 ----------------------
ISO/IEC TS 23465-2:2023(E)
Contents Page
Foreword .v
Introduction . vi
1  Scope . 1
2  Normative references . 1
3  Terms and definitions . 1
4  Symbols and abbreviated terms.2
5  Graduated APIs for security devices . 3
5.1 General . 3
5.2 Secure credential storage . 3
5.3 Security device supporting cryptography . 4
5.4 Security device supporting secure application . 4
6  API pre-requisite . 4
6.1 Description language . 4
6.2 Format of an API function . . 4
6.2.1 General . 4
6.2.2 Addressing means . 5
6.2.3 Parameters . 5
6.2.4 Return values . 5
6.2.5 Callback functionality . 5
7  API error handling . 6
7.1 General . 6
7.2 Exceptions. 6
8  Security device identification . 6
8.1 Security device attributes . 6
8.2 Security device entry . 8
9  Data model definition .8
9.1 General . 8
9.2 Attributes and types. 9
9.3 Methods . 9
9.4 References/instances . 9
10  API definition . .10
10.1 General . 10
10.2 List of defined API functions . 10
10.3 API function for managing, addressing and identifying security devices . 11
10.3.1 Method isoIec23465_ getSecurityDeviceList . 11
10.3.2 Method isoIec23465_connectSecurityDevice — Connection to the security
device . 12
10.4 API function derived from data model .12
10.4.1 Basic Class Object .12
10.4.2 Class SecurityDeviceApplication . 14
10.4.3 Class RootApplication . 15
10.4.4 Class SensitiveContainer . 17
10.4.5 DataContainer . 19
10.4.6 CertificateContainer . 24
10.4.7 Authenticator. 26
10.4.8 Password . 27
10.4.9 Key . . 31
10.4.10 AsymmetricKey . 32
10.4.11 SecretKey class . 33
10.4.12 PublicKey .34
iii
© ISO/IEC 2023 – All rights reserved

---------------------- Page: 3 ----------------------
ISO/IEC TS 23465-2:2023(E)
10.4.13 PrivateKey .36
10.5 API functions for cryptographic operation .38
10.5.1 General .38
10.5.2 Extension of key class .40
10.5.3 Interface methods related to keys . 41
Annex A (informative) Open Mobile API .50
Annex B (informative) Support of Open Mobile API .53
Annex C (informative) IDL.54
Bibliography .55
iv
  © ISO/IEC 2023 – All rights reserved

---------------------- Page: 4 ----------------------
ISO/IEC TS 23465-2:2023(E)
Foreword
ISO (the International Organization for Standardization) and IEC (the International Electrotechnical
Commission) form the specialized system for worldwide standardization. National bodies that are
members of ISO or IEC participate in the development of International Standards through technical
committees established by the respective organization to deal with particular fields of technical
activity. ISO and IEC technical committees collaborate in fields of mutual interest. Other international
organizations, governmental and non-governmental, in liaison with ISO and IEC, also take part in the
work.
The procedures used to develop this document and those intended for its further maintenance
are described in the ISO/IEC Directives, Part 1. In particular, the different approval criteria
needed for the different types of document should be noted. This document was drafted in
accordance with the editorial rules of the ISO/IEC Directives, Part 2 (see www.iso.org/directives or
www.iec.ch/members_experts/refdocs).
Attention is drawn to the possibility that some of the elements of this document may be the subject
of patent rights. ISO and IEC shall not be held responsible for identifying any or all such patent
rights. Details of any patent rights identified during the development of the document will be in the
Introduction and/or on the ISO list of patent declarations received (see www.iso.org/patents) or the IEC
list of patent declarations received (see https://patents.iec.ch).
Any trade name used in this document is information given for the convenience of users and does not
constitute an endorsement.
For an explanation of the voluntary nature of standards, the meaning of ISO specific terms and
expressions related to conformity assessment, as well as information about ISO's adherence to
the World Trade Organization (WTO) principles in the Technical Barriers to Trade (TBT) see
www.iso.org/iso/foreword.html. In the IEC, see www.iec.ch/understanding-standards.
This document was prepared by Joint Technical Committee ISO/IEC JTC 1, Information technology,
Subcommittee SC 17, Cards and security devices for personal identification.
A list of all parts in the ISO/IEC 23465 series can be found on the ISO and IEC websites.
Any feedback or questions on this document should be directed to the user’s national standards
body. A complete listing of these bodies can be found at www.iso.org/members.html and
www.iec.ch/national-committees.
v
© ISO/IEC 2023 – All rights reserved

---------------------- Page: 5 ----------------------
ISO/IEC TS 23465-2:2023(E)
Introduction
Integrated chip card (ICC) technologies and solutions are widely deployed around the world, but the
system for identity tokens and credentials is quickly changing. In this context, the application protocol
data unit (APDU) protocol outlined in the ISO/IEC 7816 series is becoming in some cases a hindrance to
the integration of ICs in environments such as mobile phones, handheld devices, connected devices (e.g.
M2M, IoT) or other applications using security devices.
In addition, several stakeholders are not familiar with, or not very fond of the APDU protocol because
of its complexity. They would circumvent its constraints by requesting an abstraction layer hiding IC
specifics such as data structures and complexity of the security policies.
A common way to reach this goal in the software development is the definition and application of
application programming interface (API) functions to access the IC within the devices. Specific
knowledge of ADPU protocols and details of the IC implementation is not necessary anymore. Also,
the complexity and details of the implementation of the security model and the security policy can be
shifted from the pure application development into the system design of the whole ID management.
However, even solutions based on those kinds of middleware are perceived as cumbersome in some
systems. The market looks for a middleware memory footprint to be as low as possible and the
acceptance, usage and maintenance of such a system can be simpler.
This document aims to overcome or mitigate those issues by proposing a new approach that preserves
ICC functionality and allows a seamless ICC portability onto new systems.
The ISO/IEC 23465 series focuses on a solution by designing an API and a system with the following
characteristics:
— It offers a set of API calls related to multi-sectorial ICC functionality, derived from the ISO/IEC 7816
series of other ICC related standards.
— It defines the sub-system to perform the conversion from the API function to the interface of the
security device (e.g. APDU-interface), called “proxy”.
— It results in a description of solutions with no middleware or very little middleware memory
footprint (i.e. simplified drivers).
— It defines simplified ICC capabilities, description of the discoverability (i.e. with significantly less
complexity than ISO/IEC 24727) and provides examples of usages.
The present model is static and future revisions are expected to add live cycle functionality.
vi
  © ISO/IEC 2023 – All rights reserved

---------------------- Page: 6 ----------------------
TECHNICAL SPECIFICATION ISO/IEC TS 23465-2:2023(E)
Card and security devices for personal identification —
Programming interface for security devices —
Part 2:
API definition
1  Scope
This document describes the following aspects of the programming interface between the client
application dealing with the security device and the proxy, based on the framework outlined in
ISO/IEC 23465-1:
— the generic API definition;
— state and security models for use cases;
— class and API definitions of functionality, defined in other standards, e.g. the ISO/IEC 7816 series.
2  Normative references
The following documents are referred to in the text in such a way that some or all of their content
constitutes requirements of this document. For dated references, only the edition cited applies. For
undated references, the latest edition of the referenced document (including any amendments) applies.
ISO/IEC 23465-1:2023, Card and security devices for personal identification — Programming interface for
security devices — Part 1: Introduction and architecture description
3  Terms and definitions
For the purposes of this document, the terms and definitions given in ISO/IEC 23465-1 and the following
apply.
ISO and IEC maintain terminology databases for use in standardization at the following addresses:
— ISO Online browsing platform: available at https:// www .iso .org/ obp
— IEC Electropedia: available at https:// www .electropedia .org/
3.1
array
indexed list of any data types with a well-known number of members
3.2
boolean
data type used to denote a data item that can only take one of the values TRUE and FALSE
3.3
char
data type containing an 8-bit quantity that encodes a single-byte character from any byte-oriented
code set with a numerical value between 0 and 255
1
© ISO/IEC 2023 – All rights reserved

---------------------- Page: 7 ----------------------
ISO/IEC TS 23465-2:2023(E)
3.4
credential
set of data presented as evidence of a claimed or asserted identity and/or entitlements
EXAMPLE A user attribute (see ISO/IEC 19286) signed by the issuer as proof of authenticity is a credential
that can be verified by the service provider by validating the electronic signature.
[SOURCE: ISO/IEC 29115:2013, 3.8, modified — Note 1 to entry was deleted. An EXAMPLE was added.]
3.5
integer
data type containing a sequence of digits taken from a number base
Note 1 to entry: Programming languages support integer values as a data type in different flavours, e.g. as signed
integer or unsigned integer and in short or long format. To be programming language agnostic this document
does not specify any of these different definitions and uses the general type integer for different types. This
[6]
approach is different to the used interface description language (IDL). It is the responsibility of the application
programmer to define the type of integer in a relevant API function call according to the need of the function and
the programming language used.
EXAMPLE Digits from the number base 10 (decimal) consisting of 0, 1, 2, 3, 4, 5, 6, 7, 8, 9.
3.6
octet
data type with 8-bit quantity
3.7
string
data type containing a sequence of characters with a definite length
4  Symbols and abbreviated terms
APDU application protocol data unit
API application programming interface
CPLC Card Production Life Cycle
CPS Cryptographic Service Provider
DLOA Digital Letter of Approval
eID electronic identity
eSE embedded secure element
eUICC embedded universal integrated chip card
GP GlobalPlatform
ID identification
IDL interface description language
KMS Key Management System
OMG Object Management Group
OS operating system
OSI open systems interconnection
PII personal identifiable information
PIV Personal Identity Verification
PKCS Public Key Cryptographic Standard
SD secure digital (memory card)
TSM Trusted Service Manager eSE
2
  © ISO/IEC 2023 – All rights reserved

---------------------- Page: 8 ----------------------
ISO/IEC TS 23465-2:2023(E)
5  Graduated APIs for security devices
5.1  General
A security device within an electronic device is characterized by its functionality.
A security device may act as
— a means for secure storage of credentials, without any additional functionality other than to retrieve
the credentials,
— a means with cryptographic capabilities possibly storing credentials and offers in addition to
cryptographic operations with these credentials,
— an eSE-application supporting device, storing the PII and offers eID-application related functionality.
This may include related cryptographic capabilities and/or secure storage capabilities for any type
of credentials.
Depending on the level of the use cases, different usage models and functionalities shall be considered.
This leads to definitions of sub-sets of the full-flavoured APIs.
Figure 1 depicts the situation of an eSE-application supporting security device including the capabilities
of a cryptography supporting device with means of a secure storage.
Figure 1 — Possible incorporated security device variants
5.2  Secure credential storage
In this use case the API functionalities are focused on the handling of the credentials. The administration,
personalisation and usage of credentials are functions of this reduced API:
— Set data (see 10.4.5.5);
— Get data (see 10.4.5.4).
3
© ISO/IEC 2023 – All rights reserved

---------------------- Page: 9 ----------------------
ISO/IEC TS 23465-2:2023(E)
5.3  Security device supporting cryptography
A security device supporting cryptographic functionality supports a client application in addition to
secure credential storage with additional security functionality related to cryptographic operations.
There are a lot of cryptographic functions available, which allows an application to perform extended
security protocols with the support of the security device. An example for such a cryptographic function
[5]
is PKCS#11 functionality.
A cryptographic supporting security device normally includes the creation, retrieval and deletion of
credentials and is, therefore, also a credential storage.
Functions of security device supporting cryptography are e.g.:
— generate a Key (see 10.4.10.2);
— encrypt (see 10.5.3.2.2);
— decrypt (see 10.5.3.2.4).
5.4  Security device supporting secure application
Some client applications use a security device as a separate and secured application storage. An (ID-)
application running on a standalone personal device, e.g. a health card or an ID document can be divided
between a secured and unsecured part and be distributed, e.g. in a mobile application. For example,
the secured part is located in the security device of the mobile device, the unsecured part is running
in the mobile application itself. The combination of both the secured part and the unsecured part are
completely running on the mobile device and can be a fully personalized ID-application communicating
with a terminal.
A security device supporting ID applications may incorporate, in addition, the functionality of a
cryptographic and/or secure storage supporting security device. Examples of functionality of such a
security device are:
— PIV application;
— health application;
— mobile driving license.
6  API pre-requisite
6.1  Description language
The APIs defined in this document are outlined and defined with a generic interface description language
(IDL). The IDL provides means to describe these interfaces in a language independent manner. Usually,
additional language binding appendices are included in the basic descriptions of the IDL outlining how
[6]
the IDL can be applied in the given language. The interface definition language defined in is applied in
this document. Additional information about the IDL is outlined in the informative Annex C.
6.2  Format of an API function
6.2.1  General
A generic API function consists of an explanatory name of the method/function, a list of parameters
arguments and response data/values from the method invoke/function call. The name of a method/
function, i.e. the API name, is typically understandable and self-explanatory. The terminology also
[3]
signals the intent of the function. In this document the naming follows the java convention outlined in
[4]
and .
4
 © ISO/IEC 2023 – All rights reserved

---------------------- Page: 10 ----------------------
ISO/IEC TS 23465-2:2023(E)
6.2.2  Addressing means
Addressing means allow the client application to use and address any security device on board of the
electronic system.
6.2.3  Parameters
Most of method invokes/function calls need their related parameters. The parameters are a sequence
of separated variables and shall be defined in each API separately.
6.2.4  Return values
The result of a method/function is returned to the invoker/caller. The type of the return value is
method/function related and shall be defined for each API function separately.
The general format of an API method/function looks like:
(…)
raises Exeception 1, Exception 2, ….
The description of the API uses the following skeleton, defined in Table 1:
Table 1 — Format of the ISO/IEC 23465 API description
API Name API_Function_Name
API Return value any API_Return_Value
API Parameter(s) in any inputparameter1,
in any inputparameter2,
…
inout any inoutputparameter1
inout any inoutputparameter2
…
out any outputparameter1
out any outputparameter2
…
Exceptions Exception1
Exception2
…
The API function names standardized in this document use the prefix isoIec23465_. The
[3] [4]
case sensitivity follows the rules in conformance with the coding conventions in and .
6.2.5  Callback functionality
To allow a non-blocking programming style or un-performant processing, the callback mechanism can
apply. Synchronous and ansynchronous program processing are supported by many programming
languages. These callback mechanisms may optionally be used.
If this applies, a callback function reference shall be conveyed in the parameter of each method. In the
description tables of the methods in Clause 10, the callback function references in the parameter lists
are not shown but have to be added if callback is used.
5
© ISO/IEC 2023 – All rights reserved

---------------------- Page: 11 ----------------------
ISO/IEC TS 23465-2:2023(E)
7  API error handling
7.1  General
Security devices using the ISO/IEC 7816 series APDUs indicate the processing status with the responses
trailer SW1- SW2, especially for error conditions. In case of the API usage, the more efficient exception
handling applies which is offered by modern programming languages.
The communication with the security device is performed by the API and its implementation. Any
commands and responses to and from the security device are hidden from the application. In case of
ISO/IEC 7816 related security devices, the response trailers are mapped to corresponding exceptions
by the proxy.
7.2  Exceptions
The possible exceptions for each API method/function are outlined and explained in the API definition
of each function.
Exceptions which are not dedicated to a specific method and are thrown, e.g. by the runtime
environment or other components of the software system, are not listed explicitly. An example can be
the exception “FunctionNotImplementedExeception”.
8  Security device identification
8.1  Security device attributes
As outlined in ISO/IEC 23465-1, this series of standards applies to systems where applications make use
of security devices. It is possible that the system has access to more than one security device. A specific
security device is characterized by a set of attributes. These attributes reflect high level information
about the security device and shall allow a calling instance to identify the assigned security device. A
set of attributes is proposed in Table 2.
6
  © ISO/IEC 2023 – All rights reserve
...