Technical Guideline TR-03112-7 eCard-API-Framework - Protocols - Version 1.1.5 7. April 2015 - BSI
←
→
Page content transcription
If your browser does not render page correctly, please read the page content below
Technical Guideline TR-03112-7 eCard-API-Framework – Protocols Version 1.1.5 7. April 2015
Bundesamt für Sicherheit in der Informationstechnik Postfach 20 03 63 53133 Bonn E-Mail: ecard.api@bsi.bund.de Internet: https://www.bsi.bund.de © Bundesamt für Sicherheit in der Informationstechnik 2015
Contents 1 Overview of the eCard-API-Framework.................................................................................................................................. 6 1.1 Key Words.............................................................................................................................................................................. 6 1.2 XML-Schema........................................................................................................................................................................ 7 2 Connection establishment in distributed systems............................................................................................................. 8 2.1 General security requirements.................................................................................................................................... 8 2.2 Connection establishment for SOAP binding...................................................................................................... 8 2.3 Connection Establishment for PAOS binding...................................................................................................... 9 2.3.1 Setting up a Trusted Channel.............................................................................................................................. 10 2.3.2 PAOS Communication............................................................................................................................................ 10 2.3.3 Session Termination................................................................................................................................................ 11 2.4 TC_API_Open..................................................................................................................................................................... 11 2.4.1 Security mechanisms for the channel established with TC_API_Open...........................................11 2.5 TC_API_Close..................................................................................................................................................................... 13 2.6 StartPAOS............................................................................................................................................................................ 13 3 ISO/IEC 24727 protocols.............................................................................................................................................................. 14 3.1 PIN Compare..................................................................................................................................................................... 14 3.1.1 Marker............................................................................................................................................................................ 15 3.1.2 DIDCreate..................................................................................................................................................................... 23 3.1.3 DIDUpdate.................................................................................................................................................................... 24 3.1.4 DIDGet............................................................................................................................................................................ 24 3.1.5 DIDAuthenticate........................................................................................................................................................ 24 3.1.6 Non-supported functions..................................................................................................................................... 25 3.2 Mutual authentication.................................................................................................................................................. 25 3.2.1 Marker............................................................................................................................................................................ 26 3.2.2 DIDCreate..................................................................................................................................................................... 27 3.2.3 DIDUpdate.................................................................................................................................................................... 28 3.2.4 DIDGet............................................................................................................................................................................ 28 3.2.5 CardApplicationStartSession............................................................................................................................... 28 3.2.6 DIDAuthenticate........................................................................................................................................................ 29 3.2.7 Non-supported functions..................................................................................................................................... 30 3.2.8 Minimum requirements in terms of algorithms........................................................................................30 3.3 Password Authenticated Connection Establishment.....................................................................................31 3.3.1 Marker............................................................................................................................................................................ 31 3.3.2 DIDCreate..................................................................................................................................................................... 32 3.3.3 DIDUpdate.................................................................................................................................................................... 32 3.3.4 DIDGet............................................................................................................................................................................ 32 3.3.5 DIDAuthenticate........................................................................................................................................................ 32 3.3.6 CardApplicationStartSession............................................................................................................................... 35 3.3.7 Non-supported functions..................................................................................................................................... 35 3.4 Chip Authentication....................................................................................................................................................... 35 3.4.1 Marker............................................................................................................................................................................ 35 3.4.2 DIDCreate..................................................................................................................................................................... 36 3.4.3 DIDUpdate.................................................................................................................................................................... 37 3.4.4 DIDGet............................................................................................................................................................................ 37 3.4.5 DIDAuthenticate........................................................................................................................................................ 37 Bundesamt für Sicherheit in der Informationstechnik 3
3.4.6 Non-supported functions..................................................................................................................................... 39 3.5 Terminal Authentication.............................................................................................................................................. 39 3.5.1 Marker............................................................................................................................................................................ 39 3.5.2 DIDCreate..................................................................................................................................................................... 40 3.5.3 DIDUpdate.................................................................................................................................................................... 40 3.5.4 DIDGet............................................................................................................................................................................ 40 3.5.5 DIDAuthenticate........................................................................................................................................................ 40 3.5.6 Non-supported functions..................................................................................................................................... 43 3.6 Extended Access Control.............................................................................................................................................. 43 3.6.1 EAC protocol specification.................................................................................................................................... 43 3.6.2 Marker............................................................................................................................................................................ 44 3.6.3 Call and return of CardApplicationStartSession........................................................................................44 3.6.4 Overview of EAC protocol sequence................................................................................................................ 49 3.6.5 DIDCreate, DIDUpdate and DIDGet................................................................................................................. 56 3.6.6 Non-supported functions..................................................................................................................................... 56 3.7 Restricted Identification............................................................................................................................................... 56 3.7.1 Marker............................................................................................................................................................................ 56 3.7.2 DIDCreate..................................................................................................................................................................... 57 3.7.3 DIDUpdate.................................................................................................................................................................... 57 3.7.4 DIDGet............................................................................................................................................................................ 57 3.7.5 DIDAuthenticate........................................................................................................................................................ 57 3.7.6 Non-supported functions..................................................................................................................................... 58 3.8 RSA Authentication........................................................................................................................................................ 58 3.8.1 Marker............................................................................................................................................................................ 59 3.8.2 DIDCreate..................................................................................................................................................................... 62 3.8.3 DIDUpdate.................................................................................................................................................................... 62 3.8.4 DIDGet............................................................................................................................................................................ 62 3.8.5 CardApplicationStartSession............................................................................................................................... 62 3.8.6 DIDAuthenticate........................................................................................................................................................ 63 3.8.7 Verification of the certificate path..................................................................................................................... 63 3.8.8 Invocation of INTERNAL AUTHENTICATE................................................................................................. 64 3.8.9 Invocation of EXTERNAL AUTHENTICATE................................................................................................. 65 3.8.10 VerifyCertificate......................................................................................................................................................... 65 3.8.11 Non-supported functions..................................................................................................................................... 65 3.8.12 Minimum requirements in terms of algorithms........................................................................................65 3.9 Generic cryptography.................................................................................................................................................... 66 3.9.1 Marker............................................................................................................................................................................ 67 3.9.2 DIDCreate..................................................................................................................................................................... 71 3.9.3 DIDUpdate.................................................................................................................................................................... 71 3.9.4 DIDGet............................................................................................................................................................................ 71 3.9.5 Encipher........................................................................................................................................................................ 71 3.9.6 Decipher........................................................................................................................................................................ 71 3.9.7 GetRandom.................................................................................................................................................................. 71 3.9.8 Hash................................................................................................................................................................................. 71 3.9.9 Sign.................................................................................................................................................................................. 71 3.9.10 VerifySignature........................................................................................................................................................... 72 3.9.11 VerifyCertificate......................................................................................................................................................... 72 3.9.12 DIDAuthenticate........................................................................................................................................................ 72 3.9.13 Non-supported functions..................................................................................................................................... 73 4 Bundesamt für Sicherheit in der Informationstechnik
4 Protocols for GetCertificate......................................................................................................................................................... 73 4.1 GetCertificate by means of Simple Enrollment Protocol..............................................................................73 5 Basic Update Protocol.................................................................................................................................................................... 76 Table of Figures Figure 1: Connection establishment for PAOS binding................................................................................................................. 9 Figure 2: Message Sequence after CardApplicationStartSession(EACSession).................................................................49 Figure 3: Basic Update Protocol.............................................................................................................................................................. 76 Bundesamt für Sicherheit in der Informationstechnik 5
1 Overview of the eCard-API-Framework
The objective of the eCard-API-Framework is the provision of a simple and homogeneous interface to
enable standardised use of the various smart cards (eCards) for different applications.
The eCard-API-Framework is sub-divided into the following layers:
• Application-Layer
• Identity-Layer
• Service-Access-Layer
• Terminal-Layer
The Application-Layer contains the various applications which use the eCard-API-Framework to access the
eCards and their associated functions. Application-specific "convenience interfaces", in which the recurring
invocation sequences may be encapsulated in application-specific calls, may also exist in this layer. However,
these interfaces are currently not within the scope of the e-Card-API-framework.
The Identity-Layer comprises the eCard-Interface and the Management interface, and therefore functions
for the use and management of electronic identities as well as for management of the
eCard-API-Framework.
The eCard-Interface specified in Part 2 of this Guideline allows to request certificates as well as the
encryption, signature and time-stamping of documents.
In the Management-Interface specified in Part 3 of this Guideline, functions for updating the framework and
the management of trusted identities, smart cards, card terminals, and default behaviour are available.
The Service-Access-Layer provides, in particular, functions for cryptographic primitives and biometric
mechanisms in connection with cryptographic tokens, and comprises the ISO24727-3-Interface and the
Support-Interface.
The ISO24727-3-Interface defined in Part 4 of this Guideline is a webservice-based implementation of the
standard of the same name [ISO24727-3]. This interface contains functions to establish (cryptographically
protected) connections to smart cards, to manage card applications, to read or write data, to perform
cryptographic operations and to manage the respective key material (in the form of so-called "differential
identities"). In the process, all functions which use or manage "differential identities" are parameterised by
means of protocol-specific object identifiers so that the different protocols which are defined in the present
document MAY be used with a standardised interface.
The Support-Interface specified in Part 5 of this Guideline contains a range of supporting functions.
The Terminal-Layer primarily contains the IFD-Interface specified in Part 6 of this Guideline. This layer
takes over the generalisation of specific card terminal types and various interfaces as well as communication
with the smart card. For the user it is unimportant whether the card is addressed by PC/SC, a SICCT terminal
or a proprietary interface, or whether it has contacts or is contact-less.
1.1 Key Words
The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”,
“RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in
[RFC2119]. The key word “CONDITIONAL” is to be interpreted as follows:
6 Bundesamt für Sicherheit in der InformationstechnikCONDITIONAL: The usage of an item is dependent on the usage of other items. It is therefore further qualified under which conditions the item is REQUIRED or RECOMMENDED. 1.2 XML-Schema A XML-Schema is provided together with this Technical Guideline. In case of incongruencies, the specifications in this text take precedence. The graphical representations of the XML-Schema illustrate the schema. Note that the text of this Guideline might further restrict the presence or mulitplicity of elements as compared to the schema definition. Bundesamt für Sicherheit in der Informationstechnik 7
2 Connection establishment in distributed systems Some of the protocols specified here involve two instances of the eCard-API-Framework, which run on different systems (Server and Client, which in general both contain a SAL (Server-SAL/Client-SAL, resp.) and additional program logic) and communicate with each other via potentially insecure networks. Therefore, the relevant aspects of security have to be taken into consideration when setting up the transport channel. 2.1 General security requirements To secure the communication between the different modules and instances of the eCard-API-Framework the TLS protocol is used. The cryptographic algorithms and security parameters MUST meet the requirements set out in [TR-03116], part 4. For communication between different modules of the eCard-API-Framework X.509 certificates MAY be used, whereby the associated private keys are to be adequately protected. Alternatively, anonymous TLS cipher suites, such as TLS_DH_anon from [RFC4346] or TLS_ECDH_anon from [RFC4492], MAY be used, although in this case appropriate security measures are necessary in the operational environment in order to avert man-in-the-middle attacks while the connection is being established. In both cases there MUST be an exclusive binding of the communication context at application level to the TLS channel which has been established in this process. This communication context is established on connection to the IFD layer via the function EstablishContext and represented by the ContextHandle (cf. Part 6 of this Guideline, Section 3.1.1). When connecting to the SAL, this communication context corresponds to a connection to the card application established by means of CardApplicationConnect, which is represented by a ConnectionHandle (cf. Part 4 of this Guideline, Section 3.2.1). As such, one single TLS channel is typically sufficient to establish communication between a SAL and the IFD layer — irrespective of the number of card terminals and cards connected — whereas a separate TLS channel is required for every connection to a card application for communication to take place between the Identity-Layer or the Application-Layer and the SAL. 2.2 Connection establishment for SOAP binding When using the SOAP binding [SOAPv1.1], the connection is established simply by setting up a TLS-protected channel between the user of the web service (service consumer) and the provider of the web service (service provider) via which web service messages MAY henceforth be exchanged. In this case the service consumer and service provider take the roles of TLS/http client and TLS/http server, respectively. Activation of this protocol is indicated by the URI urn:ietf:rfc:5246 for version TLS 1.2 or urn:ietf:rfc:4346 for TLS 1.1 in the Protocol-parameter of the PathSecurity element (see alsoPart 4 of this Guideline and Section 2.4.1). 8 Bundesamt für Sicherheit in der Informationstechnik
2.3 Connection Establishment for PAOS binding When using the PAOS binding [PAOSv2.0], however, a more complex process is required to establish the connection as, in this case, the TLS/http server acts as the user of the web service (service consumer), the TLS/http client acts as the provider of the web service (service provider) and the TLS/http client MUST initiate the connection. The general connection sequence is shown in Figure 1. The procedure which enables the Client to establish a connection with the Server is described in the following sections. Figure 1: Connection establishment for PAOS binding Bundesamt für Sicherheit in der Informationstechnik 9
2.3.1 Setting up a Trusted Channel
Server and Client share the following parameters necessary to establish a trusted channel:
• SessionIdentifier (REQUIRED)
A unique identifier of the authentication session.
• PSK (CONDITIONAL)
A cryptographically strong pre-shared key if required by the used TLS-Cipher Suite.
The Trusted Channel is established by two calls to TC_API_Open to the Server-SAL and the Client-SAL,
respectively:
• The Server sends a TC_API_Open call to the Server-SAL with ChannelHandle parameter set as
follows:
◦ ProtocolTerminationPoint is not present or is set to http://127.0.0.1 for localhost.
◦ SessionIdentifier SHALL contain a unique identifier of the authentication session generated
by the Server.
◦ Binding is set to urn:liberty:paos:2006-08 and indicates the need to establish a PAOS
connection according to [PAOSv2.0].
◦ PathSecurity specifies security measures required while establishing the PAOS connection
(cf. Section 2.4.1). If the Protocol-element is set to urn:ietf:rfc:4279, the
Parameters-element SHALL contain the pre-shared key PSK.
• The Client sends a TC_API_Open call to the Client-SAL with the following parameters:
◦ ServerAddress – is REQUIRED and specifies the address of the Server-SAL.
◦ SessionIdentifier – is REQUIRED and specifies the unique identifier of the session, which
has been generated by the Server.
◦ Binding – is OPTIONAL and indicates the web service binding, which is to be used for the
established communication channel. If this parameter is omitted the default value
urn:liberty:paos:2006-08 is assumed and the binding specified in [PAOSv2.0] is used.
◦ PathSecurity specifies security measures required while establishing the PAOS connection
(cf. Section 2.4.1). If the Protocol-element is set to urn:ietf:rfc:4279, the
Parameters-element SHALL contain the pre-shared key PSK.
Note: Both calls may be internal calls if Server/Server-SAL and/or Client/Client-SAL are integrated components.
2.3.2 PAOS Communication
The PAOS connection from the Client-SAL to the Server-SAL is finally established in this step.
The Request-Response Message Exchange Pattern (cf. Section 4 of [PAOSv2.0]) is used for communication
between Client-SAL and Server-SAL. Hence the Client-SAL sends an HTTP POST or GET request with a
PAOS-specific HTTP-header (cf. Section 9.3.1 of [PAOSv2.0]) to the Server-SAL. The information contained in
the PAOS-specific HTTP-header indicates which PAOS version is supported (e.g. urn:liberty:paos:2003-08 or
urn:liberty:paos:2006-08) and which service is to be invoked at the eService indicated by the name space
defined in the corresponding WSDL (e.g. urn:iso:std:iso-iec:24727:tech:schema).
Note: If an error occurs at any point in the chain of Request-Response Pattern, including the user aborting the
procedure, the error MUST be conveyed to the other communication partner before the connection is closed.
10 Bundesamt für Sicherheit in der InformationstechnikThe SessionIdentifier is transmitted as part of a SOAP-enveloped StartPAOS-call (refer to Section
2.6), which SHALL contain information about the card terminals and connected cards available at the client.
2.3.3 Session Termination
In order to terminate the PAOS-connection the Server sends TC_API_Close to the Server -SAL, which
results in an HTTP POST Response to the Client, which SHALL contain a SOAP-enveloped
StartPAOSResponse-element (refer to Section 2.6).
2.4 TC_API_Open
The function TC_API_Open can be used to initiate the establishment of a connection with a specific
binding (e.g. [PAOSv2.0]) and specific security parameters between two systems. If successful, there will be a
communication channel to the specified system which may be used to transmit calls.
Input:
• ChannelHandle [ChannelHandleType] (REQUIRED)
Specifies the system (cf. ProtocolTerminationPoint) with which a connection is to be
established or the system (cf. SessionIdentifier) from which a connection is to be accepted. If
both elements are omitted, the called SAL will generate a SessionIdentifier and return it in
TC_API_OpenResponse. Furthermore the Binding and PathSecurity MAY be specified
within the provided ChannelHandle.
The specific characteristics of the ChannelHandle when establishing a secure PAOS-based
connection, are detailed in Section 2.4.1.
Output:
• ChannelHandle [ChannelHandleType] (CONDITIONAL)
The ChannelHandle is returned if its content has changed.
Error codes:
• /resultminor/al/common#noPermission
• /resultminor/al/common#internalError
• /resultminor/al/common#parameterError
• /resultminor/dp#nodeNotReachable
• /resultminor/dp#timeout
• /resultminor/dp#unknownProtocol
• /resultminor/dp#unknownWebserviceBinding
2.4.1 Security mechanisms for the channel established with TC_API_Open
Depending on the specific purpose for which a communication channel is intended, certain fundamental
security requirements MUST be met when setting one up with TC_API_Open and appropriate security
mechanisms, which are addressed by duly configured PathSecurity elements, MUST be deployed.
Bundesamt für Sicherheit in der Informationstechnik 11Furthermore appropriate security measures MUST be taken on a client system to ensure that a
TC_API_Open invocation to the Client-SAL MUST NOT be accepted directly from a remote system but
only from localhost.
2.4.1.1 TLS
The usage of TLS to set up a secure channel is indicated by the URI urn:ietf:rfc:5246 for version TLS 1.2 or
urn:ietf:rfc:4346 for TLS 1.1. The supported Cipher Suites, certificate verification and handshake MUST
follow the requirements from [TR-03116], part 4.
2.4.1.2 TLS with pre-shared keys
This section details a specific form of the PathSecurity element, which is used to establish a PAOS
connection protected with ”pre-shared keys” via TLS using TC_API_Open.
In this procedure a TLS channel is established between the two SAL instances in accordance with [RFC4279]
(or subsequent RFCs specifying PSK cipher suites), whereby a previously exchanged secret – the “pre-shared
key” – is incorporated in the session key used.
TLS with pre-shared key is indicated by stating the URI urn:ietf:rfc:4279 in the protocol element within
PathSecurity. The SessionIdentifier is used as psk_identity. In this case the (otherwise
optional) Parameters element in PathSecurity MUST be of the type TLS_PSK_ParameterType
which contains the following elements:
• PSK [hexBinary] (REQUIRED)
Contains the value of the pre-shared key which is incorporated, in the manner specified in
[RFC4279], into the session key of the TLS channel being established.
• CipherSuite [string, 0..*] (OPTIONAL)
If present, MUST contain a series of *_PSK_* cipher suites according to [TR-03116], part 4, shown as
a string. Implementations MUST support TLS_RSA_PSK_WITH_AES_256_CBC_SHA. Additional
PSK cipher suites according to [TR-03116], Part 4, MAY be supported.
2.4.1.3 Error codes
The following error messages MAY also occur in addition to the ResultMinor values listed in section 2.4:
• .../dp#trustedChannelEstablishmentFailed
• .../dp#unknownProtocol
• .../dp#unknownCipherSuite
• .../dp#unknownWebserviceBinding
• .../sal#unknownDIDName
• .../sal#securityConditionsNotSatisfied
• …/il/signature#certificateNotFound
• …/il/signature#certificateFormatNotCorrectWarning
• …/il/signature#invalidCertificateReference
• …/il/signature#certificatePathNotValidatedWarning
• …/il/signature#certificateStatusNotCheckedWarning
• …/il/signature#improperRevocationInformationWarning
12 Bundesamt für Sicherheit in der Informationstechnik• …/il/signature#invalidCertificatePath
• …/il/signature#certificateRevoked
• …/il/signature#invalidCertificateExtension
2.5 TC_API_Close
The function TC_API_Close is used to actively close a previously established connection between two
systems. The communication channel may no longer be used; the ChannelHandle looses its validity.
Input:
• ChannelHandle [ChannelHandleType] (REQUIRED)
Specifies the connection which is to be closed down.
This function has no output and uses the following error codes:
• /resultminor/al/common#noPermission
• /resultminor/al/common#internalError
• /resultminor/al/common#parameterError
• /resultminor/dp#communicationError
• /resultminor/dp#unknownChannelHandle
2.6 StartPAOS
The function StartPAOS is used for the establishment of a PAOS connection according to [PAOSv2.0]. In
order to avoid the additional transmission of the otherwise necessary SAL-calls CardApplicationPath
and CardApplicationConnect the Client-SAL SHALL incorporate information about connected card
terminals and card applications in form of ConnectionHandle-elements into the StartPAOS-structure.
Input:
• SessionIdentifier [string] (REQUIRED)
Allows to identify the session between the eService-SAL and the Client-SAL.
• ConnectionHandle [ConnectionHandleType, 1..*] (REQUIRED)
SHALL occur for each connected card application and each empty card terminal slot available at the
client. If the Client supports only one type of card application, the Client MAY send a dummy
ConnectionHandle, containing the CardApplication-element (see Part 4 of this Guideline)
identifying the supported card application and containing no further information.
• UserAgent (REQUIRED)
SHALL contain information identifying the used Client. MUST NOT contain any information about
the user, the computer of the user or any software installed on the computer of the user apart from
the Client.
◦ Name [string] (REQUIRED)
SHALL contain the name of the Client. SHALL NOT contain any version information.
◦ VersionMajor [integer] (REQUIRED)
SHALL contain the major version of the Client.
Bundesamt für Sicherheit in der Informationstechnik 13◦ VersionMinor [integer] (REQUIRED)
SHALL contain the minor version of the Client.
◦ VersionSubminor [integer, 0..1] (OPTIONAL)
If present, SHALL contain the subminor version of the Client.
• SupportedAPIVersions [1..*] (REQUIRED)
SHALL contain version numbers of supported versions of the eCard-API-specification.
◦ Major [integer] (REQUIRED)
◦ Minor [integer, 0..1] (OPTIONAL)
If not present, all minor version corresponding to the given major version are supported.
◦ Subminor [integer, 0..1] (OPTIONAL)
If not present, all subminor version corresponding to the given major/minor version are
supported.
Compliance to this version of the eCard-API-Framework SHALL be indicated by
(Major.Minor.Subminor) = (1.1.5).
• SupportedDIDProtocols [anyURI, 0..*] (OPTIONAL)
If present, SHALL contain a list of supported DIDProtocols.
This function has no output and uses the following error codes:
• /resultminor/al/common#noPermission
• /resultminor/al/common#internalError
• /resultminor/al/common#parameterError
• /resultminor/dp#nodeNotReachable
• /resultminor/dp#timeout
Note: If the Server SAL aborts the process for which the connection was set up (e.g. due to an internal error or
unexpected/incorrect messages from the Client SAL), the Server SAL SHALL send a StartPAOSResponse
indicating the error before closing the connection.
3 ISO/IEC 24727 protocols
This section contains the protocol-specific definitions of the Crypto and Differential Identity Services (cf.
Sections 3.5 and 3.6 of Part 4 of this Guideline) for some authentication protocols in accordance with
[ISO24727-3], as required for the use of typical signature cards, electronic health insurance cards, healthcare
professional ID cards and the planned electronic identity cards.
Note that the protocol identifies the used cryptographic protocol including the used commands as well as
the secure messaging to be used after successful completion of the cryptographic protocol.
3.1 PIN Compare
Authentication of a user is performed by means of a PIN in this protocol, which is also specified in abridged
form in Annex A.9 of [ISO24727-3].
The identifier for this protocol is urn:oid:1.3.162.15480.3.0.9 for iso(1) identified-organization (3) CEN (162)
CEN 15480 (15480) part3(3) annex-a(0) pin-compare(9).
14 Bundesamt für Sicherheit in der InformationstechnikThe following types are used to specify the generic structures from Part 4 of this Guideline for this protocol
in more detail.
3.1.1 Marker
This type specifies the structure of the DID marker for this authentication protocol.
Name Description
PinRef Contains the key reference of the PIN. Details on the KeyRefType are provided below.
PinValue MAY contain the value of the PIN. If this value is missing despite being required, it is
input at the terminal.
The PIN needs to be stated in the following cases:
• When creating the PIN object with DIDCreate (see Sec tion 3.1.2).
• When changing the PIN with DIDUpdate (see Section 3.1.3) and
◦ CHANGE REFERENCE DATA (i.e. unblockingPassword bit in pwdFlags
(cf. Part 6 of this Guideline) is not set)
◦ RESET RETRY COUNTER (i.e. the unblockingPassword bit in pwdFlags
is set) in the following cases:
▪ P1='00' (indicated by the absence of resetRetryCounter1 and
resetRetryCounter2 in the PasswordFlags bit string) or
▪ P1='02' (indicated by the setting of resetRetryCounter1 and the
absence of resetRetryCounter2 in the PasswordFlags bit string)
Password Is an optional element which MAY contain the PasswordAttributes defined in
Attributes [ISO7816-15]. For details please refer to Part 6 of this Guideline.
iso: MAY contain information about the designated states if more than one possible state is
StateInfo defined for the key object. Details on the iso:StateInfo element are provided below.
Bundesamt für Sicherheit in der Informationstechnik 15The KeyRefType is used for the specification of markers (e.g. in the PinCompareMarkerType,
MutualAuthMarkerType, RSAAuthMarkerType and the CryptoMarkerType).
Name Description
KeyRef Contains the reference to the key object.
Protected Is an optional element with which key objects MAY be marked as particularly sensitive
(e.g. private signature key or PIN for qualified electronic signature). If such key objects
exist in a CardInfo file, they MUST be covered by a signature issued by a trustworthy
organisation, and any attempt to access a key object of this type from an unsigned part of
a CardInfo file will result in an error message during import of the CardInfo file (cf.
Part 3 of this Guideline).
The iso:StateInfo -element is of type StateInfoType and is used to specify states of key objects
and a procedure which allows to recognize the current state of the key object. A status is uniquely
identified by the necessary attribute StateName.
Name Description
StateRecog Indicates the sequence of calls to the card through which the current state of the key
nition object can be determined, if the card supports this. The CardCallSequenceType is
explained in greater detail below. The commands in the respective
StateRecognition elements SHOULD be selected in such a way as to permit the clear
identification of the state of the key object.
State This element is present for each state of the key object. More details concerning this
element are provided below (see page 21).
16 Bundesamt für Sicherheit in der InformationstechnikThe CardCallSequenceType contains a sequence of CardCall -elements, which allow to specify a
command and a set of possible response pairs for either APDUs or API-calls as defined in [TR-03112-4] or
[TR-03112-6] for example.
While the CommandAPDU / ResponseAPDU - alternative may be used to identify the card type (cf.
[TR-03112-4]) or send statically defined commands to a smart card, the APICall / APIResponse -
alternative is more powerful and allows to invoke arbitrary API-calls, which may also involve the user (see
ModifyVerificationData defined in [TR-03112-6] for example).
As a CardCall- element contains a request and a sequence of possible responses it MAY be used to
specify a tree structure, which is traversed in order to recognize the state of a key object or a card type (cf.
[TR-03112-4], Annex A.3-A.4).
Name Description
CardCall Defines a call to the smart card which is given by a CommandAPDU/APICall- element
and a sequence of possible ResponseAPDU/APIResponse elements.
The sequence of the CardCall elements is to be understood as an AND operation when
identifying a status or card type.
Command Contains the APDU command which is to be sent to the card (cf. [ISO7816-4], [ISO7816-8]
APDU and [ISO7816-9]).
For security reasons no APDUs with CLA values '0x' or '1x' SHOULD be used, where x is
any half byte, nor should the INS values '20', '21', '24', '2C' and '22' be used, as this would
correspond to the smart card commands VERIFY, CHANGE REFERENCE DATA, RESET
RETRY COUNTER and MANAGE SECURITY ENVIRONMENT (see [ISO7816-4], Sections
7.5.6 - 7.5.11), which an attacker could use to decrement the retry counter in the event of
a malicious "card or status detection" and thereby provoke a denial-of-service attack
under some circumstances.
In each case such APDUs MUST be denied if the CardCall element is not signed by a
trustworthy body (cf. Signature element in [TR-03112-4], Annex A.7).
Response Defines a sequence of valid replies from the smart card for the identification of a certain
APDU status or smart card type.
Bundesamt für Sicherheit in der Informationstechnik 17The sequence of the ResponseAPDU elements allows to traverse a tree structure.
The structure of the ResponseAPDUType is explained in detail below.
APICall Contains an arbitrary API-call, as defined in [TR-03112-4] or [TR-03112-6] for example.
API MAY appear multiple times and contain a corresponding response. Note that the
Response APIResponse -element MAY contain a decision element similar to the
iso:Conclusion -element explained below such that it is possible to construct a
decision tree using API-calls and responses.
The ResponseAPDU element is part of a CardCall element and specifies a possible reply from an eCard
when invoking a CommandAPDU. The ResponseAPDU comprises an (optional) Body, a Trailer (if
successful equal to '9000') and a iso:Conclusion -element, which is present if and only if the
CardCall -element is used to specify a decision tree structure.
The structure of the DataMaskType defined below allows any parts to be filtered out of the body
element and use this information to check for matching data.
Name Description
Body MAY contain information indicating which part of the data returned by the smart
card is relevant to check for matching data. Further details on the DataMaskType
are provided below.
Trailer Contains the expected status of the invocation (if successful '9000').
iso:Conclusion The iso:Conclusion- element represents the leaf of the decision tree and
allows to determine a specific state or card type or conclude that another sequence
of iso:CardCall -elements is necessary. Further details on this element are
provided below.
18 Bundesamt für Sicherheit in der InformationstechnikThe body element is of the type DataMaskType and MAY be part of the ResponseAPDU element and
MAY contain a Tag element and either MatchingData or a structured DataObject of the type
DataMaskType.
Name Description
Tag MAY contain the tag under which the expected value (or another structured data object)
is filed.
Matching Specifies which parts of the returned data are relevant in terms of checking for matching
Data data. The detailed structure of the MatchingData is explained below.
DataObject Is of the type DataMaskType and therefore again contains information on the selective
filtering of a complex data object, thus allowing analysis of TLV-encoded structures
irrespective of how they are nested.
The MatchingData structure makes it possible to specify which parts of a data object returned in the
body are relevant for the comparison.
Name Description
Offset MAY optionally contain an offset which is taken into account when determining
the relevant value. For example, an offset of '03' and a mask xy would have the same
effect as a mask '00 00 00 xy '.
Length MAY contain the length of the value relevant for the comparison.
Bundesamt für Sicherheit in der Informationstechnik 19MatchingValue Contains the value which is either identical to the value returned by the eCard or
contained therein.
The optional attribute MatchingRule of the type MatchingRuleType in the
MatchingDataType determines whether to check if the values are equal or
contained. This type is defined as follows:
If this attribute is omitted then Equals is the default setting.
Mask The OPTIONAL Mask element, which is linked conjunctively with the
MatchingValue element and the data returned by the card, makes it possible to
filter out the significant parts of the data.
The iso:Conclusion- element is part of the ResponseAPDU -element.
Name Description
RecognizedState This element is present, if a state of a key object is recognized in an
unambiguous manner and hence no further iso:CardCall -elements are
necessary.
RecognizedCardType In a similar manner this element is present, if a card type is recognized in an
unambiguous manner (cf. [TR-03112-4], Annex A).
iso:CardCall If the decision process is not finished there will be one or more
iso:CardCall -elements, which imply a recursion.
20 Bundesamt für Sicherheit in der InformationstechnikThe State -element is part of the StateInfo -element (see page 16) and it is present for each state of
the key object.
The State -element has a number of important attributes as explained in the following:
• StateName – is a required identifier of the state.
• StateClass – specifies the type of the state, where the following types are possible:
◦ Operational – means that the key object is usable in this state.
◦ NotOperational – means that the key object is not usable in this state. If the SAL
recognizes that the key object is in such a state it MUST try to determine an appropriate
sequence of StateTransition -elements, which lead to an operational state. If there is no
path to an operational (or at least indetermined) state, the user MUST be informed
accordingly.
◦ RecognitionNecessary – means that the class of the state is indetermined, which means
that it is not clear whether the recognized state is operational or not, and the SAL MUST start
the recognition procedure defined by the set of iso:CardCall -elements.
Name Description
RetryCounter Is an OPTIONAL element which contains the current value of the retry counter for
the key object in accordance with [ISO7816-4], Table 34.
UsageCounter Is an OPTIONAL element which contains the current value of the UsageCounter
for the key object in accordance with [ISO7816-4], Table 34.
StateTransitio Contains information on the various state transitions provided for the key object.
n Further details on the StateTransition element are provided below.
Bundesamt für Sicherheit in der Informationstechnik 21Each State -element defined above may contain an arbitrary number of StateTransition elements,
which describe the possible transitions to other states. The StateTransition element has a mandatory
TargetState attribute, used to refer to the StateName attribute of an existing state (cf. StateType
above).
Transitions between states are triggered by events, which are described by a sequence of
DIDAuthenticationState, RetryCounter, UsageCounter and FixedProcedure elements and
MAY contain additional UpdateCounter -elements to update the values of the RetryCounter and
UsageCounter variables, which MUST be maintained by the SAL to support cards, which do not allow
to retrieve those values from the card.
Name Description
DIDAuthentication Indicates that the transition from one state to another is triggered by using the
State DID stated in this element. Details on the DIDAuthenticationStateType
are provided below.
RetryCounter Indicates that the transition from one state to another is triggered by reaching
the value stated for the RetryCounter of the key object.
Note that some cards do not allow to retrieve the current value of the
RetryCounter of a key object and hence the SAL MUST maintain a
corresponding variable and update it according to the UpdateCounter
element described below.
UsageCounter Indicates that the transition from one state to another is triggered by reaching
the value stated for the UsageCounter of the key object.
Note that some cards do not allow to retrieve the current value of the
UsageCounter of a key object and hence the SAL MUST maintain a
corresponding variable and update it according to the UpdateCounter
element described below.
FixedProcedure Indicates that the transition from one state to another is triggered by executing
a fixed sequence of smart card commands. Details on the
CardCallSequenceType are provided on page 17.
22 Bundesamt für Sicherheit in der InformationstechnikUpdateCounter The UpdateCounter -element is used to manage the RetryCounter
and/or UsageCounter variables, which MUST be maintained by the SAL to
support cards, which do not allow to retrieve those values from the card.
The UpdateCounterType is an extension of the builtin integer type with
two mandatory attributes:
• operation either has the value set or add to indicate, whether the
provided value is to be set or added to the current value
• variable either has the value RetryCounter or UsageCounter
to indicate which variable is to be updated
The DIDAuthenticationStateType is used in the specification of access rights (cf.
SecurityCondition in [TR-03112-4]) and in the specification of state transitions (cf.
StateTransition above).
Name Description
DIDName Specifies the name of the DID required for authentication on transition from
one state to another.
DIDScope MAY, if required, resolve ambiguities between local and global DIDs.
DIDState Specifies the required authentication status and MUST be allocated with the
value True when specifying state transitions.
DIDStateQualifier MAY contain further information which is evaluated when using
certificate-based authentication procedures.
3.1.2 DIDCreate
With DIDCreate use is made of DIDCreationData of the type PinCompareMarkerType.
Bundesamt für Sicherheit in der Informationstechnik 233.1.3 DIDUpdate
This type specifies the structure of the DIDUpdateDataType for the PIN Compare protocol.
Name Description
OldPinOrPUK MAY contain the old PIN or the Personal Unblocking Key (PUK).
If this information is missing despite being required then it is input at the terminal.
This information is needed if the settings in the pwdFlags element (cf. [TR-03112-6])
are as follows:
• The exchangeRefData bit is set but not the unblockingPassword bit
(i.e. it is a normal PIN which can only be changed by entering the old PIN
(CHANGE REFERENCE DATA with P1='00', cf. [ISO7816-4], Section 7.5.7)) or
• The unblockingPassword bit is set but not the resetRetryCounter1
bit (i.e. it is a PUK which MUST be presented upon the RESET RETRY
COUNTER command with P1='00' or P1='01' (cf. [ISO7816-4], Section 7.5.10)).
Marker Contains the new marker for the PinCompare protocol. Details on this element can
be found in Section 3.1.1.
3.1.4 DIDGet
In the case of DIDGet there is a return of DIDDiscoveryData of the type PinCompareMarkerType,
although the PinValue element is omitted, and the current reading of any RetryCounter or Usage
Counter which may be defined is stated in the first StateInfo element which describes the current
status.
3.1.5 DIDAuthenticate
The protocol is processed by a single invocation of DIDAuthenticate with the following entry:
This type specifies the structure of the DIDAuthenticationDataType for the PIN Compare protocol
24 Bundesamt für Sicherheit in der Informationstechnikwhen DIDAuthenticate is called.
Name Description
Pin MAY contain the value of the PIN. If this element is missing, it is input at the terminal.
The return to DIDAuthenticateResponse is as follows:
This type specifies the structure of the DIDAuthenticationDataType for the PIN Compare protocol
when DIDAuthenticate is returned.
Name Description
RetryCounter If user verification failed, this contains the current value of the RetryCounter.
3.1.6 Non-supported functions
The following functions are not supported with this protocol and, when called up, relay an error message to
this effect /resultminor/sal#inappropriateProtocolForAction:
• CardApplicationStartSession
• Encipher
• Decipher
• GetRandom
• Hash
• Sign
• VerifySignature
• VerifyCertificate
3.2 Mutual authentication
This protocol is specified in similar form in Annex A.12 of [ISO24727-3], Section 16.1.1 [eGK-1] and Section
8.8 of [EN14890-1] and provides the framework for mutual authentication with the exchange of keys using
symmetric algorithms.
The identifier for this protocol is urn:oid:1.3.162.15480.3.0.12 for iso(1) identified-organization (3) CEN (162)
CEN 15480 (15480) part3(3) annex-a(0) client-application-mutual-authentication-wke(12).
The generic structures from [TR-03112-4] are more closely specified for this protocol by the following types.
Bundesamt für Sicherheit in der Informationstechnik 25You can also read
