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 2023
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

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

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

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

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

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
© ISO/IEC 2023 – All rights reserved

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
© ISO/IEC 2023 – All rights reserved

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).
© ISO/IEC 2023 – All rights reserved

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 .
© ISO/IEC 2023 – All rights reserved

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.
© ISO/IEC 2023 – All rights reserved

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.
© ISO/IEC 2023 – All rights reserved

ISO/IEC TS 23465-2:2023(E)
Table 2 — Security device attributes
Type of in- Security device  Type Aim of information / data Comment
formation attribute
Security  SecuritydeviceID octet [ ] Unique ID of the security device, Identification number,
device infor- e.g. Card identification
Identifier of object of type SecurityDe-
mation number
vice (see 10.4.3). can be absent or occur
once or more times For privacy reasons
this ID can be replaced
with a random number
Security device ca- octet [ ] Comprehensive description and Profile can be used al-
pability_profile_ID abstraction of the capabilities of the se- ternatively to describe
curity device and optionally the device, SE (online availabili-
containing all information below ty), URL or OID can be
possible
Security device integer Type of the security device The types have to be
type defined in a separate
table
Security device octet [ ] Identifier of owner or issuer of the SE, IIN Issuer Identification
owner also integrated-security-device owner number
Security device octet [ ] Information about certification of chip, Data structure, e.g.
certification OS and application (high level) GlobalPlatform DLOA
Open Mobile API octet [ ] Information regarding the support of Array of octet
support OMAPI
NFC support boolean Information regarding support of NFC Yes/no
CSP certification octet [ ] Information about certification of Cryp- Data structure includ-
tographic Service Provider CSP ing version and scheme
Chip infor- Chip certification octet [ ] Information about the certification of Array of octet
mation the chip if other high-level information
is not available
Available chip integer Usable memory on the chip. In GP, this Number of bytes on the
memory information is optional, it shall become security device
mandatory.
OS informa- Available security integer Usable memory in the OS. Number of bytes in the
tion device memory OS
Security device octet [ ] OS-type and -version, TLV structure Java
Card/native OS,
OS type, OS ver- GP-support and -version
OS-specification.
sion, GP version
and support GP specification, in-
cluding version number
SE_OS_Cryptogra- octet [ ] List of supported cryptographic algo- Bit map
phy rithms/protocols
GP informa- Card Recognition octet [ ] Structure defined by GP-Services TLV structure, see [8]
tion Data
Card Capability octet [ ] Structure defined by GP-Services TLV structure, see [8]
Data
Security de- Key-Manage- octet [ ] Information about the used key man- relevant for the elec-
vice support ment-System infor- agement system tronic system
mation
Discretionary Data octet [ ] Any data defined by the issuer Array of octet
The security device attributes contain information derived from the different available security devices
and additional data from the electronic system. The proxy collects the security device attribute from a
security device and exposes it at the API (see Table 3). Security device information may also retrieved
by usage of the Open Mobile API which is outlined in informative Annexes A and B.
© ISO/IEC 2023 – All rights reserved

ISO/IEC TS 23465-2:2023(E)
8.2  Security device entry
In complex systems, an application has the choice to use at least one of several security devices. The
securityDeviceEntry is a structure consisting of the securityDeviceNumber as a unique identification
and numbering element and the descriptive attributes dedicated to the security device (see Table 2).
The securityDeviceNumber assigned by the proxy, allows the selection of the security device for the
further usage within the application. A securityDeviceEntry is defined as structure consisting of
security device ID and the associated SdAttribute, mentioned in Table 3.
Table 3 — securityDeviceEntry
struct securityDeviceEntry {
integer securityDeviceNumber;
octet securityDeviceAttribute [ ];
}
Subclause 10.3.1 describes a generic API function to get the list of available Security device entries in
the electronic system.
9  Data model definition
9.1  General
The API used by a client software acts on instances of objects related to the security device system. In
general, the API functions are methods and functions dealing with, and are assigned to, these objects.
The general data model of a security device application is outlined in the class diagram in Figure 2.
© ISO/IEC 2023 – All rights reserved

ISO/IEC TS 23465-2:2023(E)
Figure 2 — General class diagram
9.2  Attributes and types
This document does not specify the implementation of classes from Figure 2. In general, neither class
attributes nor instance attributes are specified in this document. The API defines getters and setters
for handling relevant information.
9.3  Methods
The methods of each class are outlined in subclause 10.4.
9.4  References/instances
Addressing objects of the security device is achieved by using references to the instances of classes
depicted in Figure 2. Programming languages often uses handles as the references to resources. Instead
of these handles, references to class instances are used in the ISO/IEC 23465 series of standards.
1)
ISO/IEC TS 23465-3 describes the mechanisms of instantiation of the physical objects in the referenced
security device.
1) Under preparation. Stage at the time of publication: ISO/IEC DTS 23465-3.
© ISO/IEC 2023 – All rights reserved

ISO/IEC TS 23465-2:2023(E)
10  API definition
10.1  General
The API functions in this document fulfil the general requirements outlined in ISO/IEC 23465-1:2023,
Annex A. This results in the following:
— In general, each API function has an inverse API function.
— Each API function acting on objects on the security device shall obey the access rules for action on
such object, the application or proxy shall fulfil the access rules in advance.
— An API function acting on an object shall address the object within the function or has already
selected it before.
— A selected area on the security device storing the relevant object for an application is identified and
referenced by a reference to the instance, described in 9.4.
— Most of the API functions outlined in this API description are methods of data classes.
Subclause 10.4 describes the supported classes and also outlines UML diagrams. Each of these diagrams
is separated into three parts describing
— the class name, and
— the public methods usable as API functions.
10.2  List of defined API functions
All defined API functions defined in Clause 10 are listed in Table 4:
Table 4 — Defined API functions
API function name Link to the related subclause
isoIec23465_append 10.4.5.8
isoIec23465_ getSecurityDeviceList 10.3.1
isoIec23465_checkSupportedAlgorithm 10.4.9.3
isoIec23465_clearPWSecurityStatus 10.4.8.2
isoIec23465_clearSecurityStatus 10.4.2.2
isoIec23465_clearSecurityStatus 10.4.7.2
isoIec23465_clearSecurityStatusOfAllApplication 10.4.3.2
isoIec23465_connectSecurityDevice 10.3.2
isoIec23465_decrypt 10.5.3.2.4
isoIec23465_decryptInit 10.5.3.2.3
isoIec23465_deriveKey 10.5.3.5.5
isoIec23465_dhKeyAgreementInit 10.5.3.7.1
isoIec23465_dhSharedSecret 10.5.3.7.2
isoIec23465_digest 10.5.3.6.2
isoIec23465_digestInit 10.5.3.6.1
isoIec23465_disconnect 10.4.3.3
isoIec23465_encrypt 10.5.3.2.2
isoIec23465_encryptInit 10.5.3.2.1
isoIec23465_eraseSensitiveData 10.4.4.4
isoIec23465_generateKeyInstance 10.5.3.5.1
© ISO/IEC 2023 – All rights reserved

ISO/IEC TS 23465-2:2023(E)
TTaabbllee  44  ((ccoonnttiinnueuedd))
API function name Link to the related subclause
isoIec23465_generateKeyPair 10.4.10.2
isoIec23465_getAccessCondition 10.4.1.3
isoIec23465_getAccessRules 10.4.1.2
isoIec23465_getActualSize 10.4.5.2
isoIec23465_getCertificate 10.4.12.2
isoIec23465_getContent 10.4.5.4
isoIec23465_getIdentifier 10.4.1.4
isoIec23465_getIssuerCertificate 10.4.6.2
isoIec23465_getKeyAttributes 10.5.2.2
isoIec23465_getMaximumSize 10.4.5.3
isoIec23465_getPrivateKey 10.4.13.2
isoIec23465_getPublicKey 10.4.12.3
isoIec23465_getRandom 10.5.3.9
isoIec23465_getRetryCounter 10.4.8.3
isoIec23465_getSecurityStatusEvaluationCounter 10.4.7.3
isoIec23465_getStartValueRetryCounter 10.4.8.4
isoIec23465_getStartValueSecurityStatusEvaluationCounter 10.4.7.4
isoIec23465_getSupportedAlgorithm 10.4.9.2
isoIec23465_insert 10.4.5.6
isoIec23465_isErased 10.4.4.2
isoIec23465_remove 10.4.5.9
isoIec23465_selectObject 10.4.2.3
isoIec23465_selectSecurityDeviceApplication 10.4.3.4
isoIec23465_setContent 10.4.5.5
isoIec23465_setPrivateKey 10.4.13.3
isoIec23465_setPublicKey 10.4.12.4
isoIec23465_setPassphrase 10.4.8.5
isoIec23465_setSensitiveData 10.4.4.3
isoIec23465_sign 10.5.3.3.2
isoIec23465_signInit 10.5.3.3.1
isoIec23465_unblock 10.4.8.6
isoIec23465_unWrapKey 10.5.3.5.4
isoIec23465_update 10.4.5.7
isoIec23465_verifyPassword 10.4.8.7
isoIec23465_verifySignature 10.5.3.4.2
isoIec23465_verifySignatureInit 10.5.3.4.1
isoIec23465_erasePrivateKey 10.4.13.4
isoIec23465_wrapKey 10.5.3.5.3
10.3 API function for managing, addressing and identifying security devices
10.3.1 Method isoIec23465_ getSecurityDeviceList
A security device is characterized by its securityDeviceAttribute, specified in subclause 8.1. The
securityDeviceNumber is used as an identification and addressing means. An application requests the
© ISO/IEC 2023 – All rights reserved

ISO/IEC TS 23465-2:2023(E)
list of available security devices in the system and retrieves with this functionality the list of available
security devices or (equivalently) a list of smart card readers with a security device inserted.
The API function is shown in Table 5.
Table 5 — Signature of method isoIec23465_ getSecurityDeviceList
API Name isoIec23465_ getSecurityDeviceList
API Return Value struct securityDeviceEntry []
API Parameter(s) —
Exceptions —
The list of securityDeviceEntry is used by the application to select the appropriate security device. The
API function returns an empty list of securityDeviceEntry if no security device entries is available.
10.3.2 Method isoIec23465_connectSecurityDevice — Connection to the security device
The application uses the definite securityDeviceNumber from the list of securityDeviceEntry to
identify and address the security device that shall be used. As shown in Table 6, the method uses
the securityDeviceNumber as the input parameter, addresses the security device and establishes a
connection to the security device. A successful connection is acknowledged with the base reference to
the security device’s RootApplication.
Table 6 — Signature of method isoIec23465_connectSecurityDevice ()
API Name isoIec23465_connectSecurityDevice
API Return Value Object23465 RootApplication
API Parameter(s) in integer securityDeviceNumber
Exceptions ConnectionFailedException
InvalidParameterException
The API function throws ConnectionFailedException if the security device cannot be connected. An
InvalidParameterException is thrown if the given securityDeviceNumber cannot be associated with an
available security device.
10.4 API function derived from data model
10.4.1 Basic Class Object
10.4.1.1 General
The basic class Object23465 is depicted in Figure 3.
Figure 3 — Object23465 class
© ISO/IEC 2023 – All rights reserved

ISO/IEC TS 23465-2:2023(E)
10.4.1.2 Method isoIec23465_getAccessRules
Table 7 shows the method description for retrieving all acess rules by which the object is protected
from unauthorized usage.
Table 7 — Signature of method isoIec23465_getAccessRules
API Name isoIec23465_getAccessRules()
API Return Value struct AccessRules [ ]
API Parameter(s) —
Exceptions SecurityStatusNotSatisfiedException
The attribute AccessRules is related to the definition of security attributes in ISO/IEC 7816-4. An
API function, with dedicated access to the object on the security device, can only be processed if the
corresponding access condition for this access mode is fulfilled. Otherwise the access is denied by the
security device.
The return value of the method is the corresponding list of AccessRules.
The API function throws SecurityStatusNotSatisfiedException if the access rule for this operation is not
fulfilled.
10.4.1.3 Method isoIec23465_getAccessCondition
Table 8 shows the method description for retrieving the access condition for a given access mode by
which anobject is protected from unauthorized usage.
Table 8 — Signature of method isoIec23465_getAccessCondition
API Name isoIec23465_getAccessCondition()
API Return Value string AccessCondition [ ]
API Parameter(s) in string accessMode
Exceptions SecurityStatusNotSatisfiedException
The attributes accessMode and accessCondition are related to the definition of security attributes in
ISO/IEC 7816-4. An API function with dedicated access to the object on the security device can only
processed if the corresponding access condition for this access is fulfilled. Otherwise the access is
prohibited.
The return value of the method is the corresponding AccessCondition related to the addressed object.
The API function throws SecurityStatusNotSatisfiedException if the access rule for this operation is not
fulfilled.
10.4.1.4 Method isoIec23465_getIdentifier
Table 9 shows the method description for retrieving an attribute from implementing classes storing its
identifiers.
Table 9 — Signature of method isoIec23465_getIdentifier
API Name isoIec23465_getIdentifier()
API Return Value struct {
octet identifier[ ]
} identifierList[ ]
API Parameter(s) —
© ISO/IEC 2023 – All rights reserved

ISO/IEC TS 23465-2:2023(E)
TTaabbllee  99  ((ccoonnttiinnueuedd))
Exceptions SecurityStatusNotSatisfiedException
The method returns all available identifiers of an object as a list of Identifier.
The instances of objects have zero, one or more identifier used to identify the object during a selection
process. Each identifier identifying an object is an arbitrary non-empty octet string.
The return value is an array of all identifiers of the instance of this interface, possibly empty if an
instance has no identifier
The method throws SecurityStatusNotSatisfiedException if the access condition for this operation is
not fulfilled.
10.4.2 Class SecurityDeviceApplication
10.4.2.1 General
Class SecurityDeviceApplication, as shown in Figure 4, extends class Object23465 and is the base
for all applications residing in a security device. Typically, a security device hosts one or more
SecurityDeviceApplications. Each SecurityDeviceApplication typically
...