The Present Document Describes the Design of the Open Ecard App

Open eCard App Design

Version 0.1.1 of 24.11.2011

Abstract The present document describes the design of the Open eCard App. Open eCard App Design Version 0.1.1 of 24.11.2011

Table of Contents

TABLE OF CONTENTS...... 2

LIST OF FIGURES...... 3

1 INTRODUCTION...... 4

2 RELATED WORK...... 4

3 REQUIREMENTS FOR THE OPEN ECARD APP...... 4

4 HIGH LEVEL DESIGN...... 4

5 MODULE AND INTERFACE SPECIFICATION...... 5 5.1 IFD...... 5 5.1.1 Interface...... 5 5.1.1.1.1 Extended IFD-Interface...... 5 5.1.1.1.2 EstablishChannel...... 6 5.1.1.1.3 DestroyChannel...... 7 5.1.1.1.4 PACEInputType and PACEOutputType...... 9 5.1.2 Internal Design...... 11 5.2 GUI...... 11 5.2.1 Interface...... 11 5.2.1.1 ObtainUserConsent...... 11 5.2.2 Internal Design...... 15 REFERENCES...... 16

 2011, Open eCard Team CONFIDENTIAL Page 2 Open eCard App Design Version 0.1.1 of 24.11.2011

List of Figures Figure 1: High Level Design of the eCard-Client...... 4

1 Introduction

2 Related Work

3 Requirements for the Open eCard App

4 High Level Design

Figure 1: High Level Design of the Open eCard App

5 Module and Interface Specification

5.1 IFD

5.1.1 Interface

5.1.1.1.1 Extended IFD-Interface The IFD-module offers the IFD-API as specified in [BSI-TR-03112-6] and the following two additional functions:  EstablishChannel  DestroyChannel

Figure 2: Extended IFD-Interface

While the EstablishChannel function is defined in a protocol independent fashion, it can in particular be used to establish a PACE-based channel. The corresponding data types for this purpose (PACEInputType and PACEOutputType) are defined in Section 5.1.1.1.4.

5.1.1.1.2 EstablishChannel

Name EstablishChannel Description The EstablishChannel function is used to establish a cryptographic channel with an ICC. Similar as the DIDAuthenticate-function in the SAL, the EstablishChannel function may be used with different cryptographic protocols. Invocation parameters

’ Invocation of the EstablishChannel function.

Name Description SlotHandle The SlotHandle addresses the connec- tion to the smart card, which has been established with the Connect function according to [BSI-TR-03112-6]. Authentication Protocol data which are transferred when ProtocolData EstablishChannel is invoked. The DIDAuthenticationDataType is defined as an open type depending on a Protocol attribute so that the detailed structure of this parameter can be defined in a protocol-specific manner. Return

Return of the EstablishChannel function. Name Description dss:Result Contains the status information and the errors of an executed action. This element is described in more detail below. Authentication Protocol data which are returned after ProtocolData EstablishChannel has been invoked.

Status information and errors for EstablishChannel. Name Error codes ResultMajor -/resultmajor#ok -/resultmajor#error

ResultMinor -/resultminor/il/common#parameterError -/resultminor/ifdl/common#invalidSlotHandle -/resultminor/dp#unknownProtocol

Furthermore there MAY be protocol specific return codes. ResultMessage MAY contain more detailed information on the occurred error if required. Precondition In order to establish a cryptographic channel a valid SlotHandle is required.

Postcondition Upon execution of the EstablishChannel function a cryptographic channel with the ICC has been set up, which is subsequently applied for secure messaging purposes. All APDUs, which are transmitted through the given SlotHandle are protected using this key material. Note

5.1.1.1.3 DestroyChannel

Name DestroyChannel Description The DestroyChannel function is used to explicitely destroy the cryptographic channel which previously has been set up with EstablishChannel.

Invocation parameters

’ Invocation of the DestroyChannel function.

Name Description SlotHandle The SlotHandle addresses the connec- tion to the smart card, which has been established with the Connect function according to [BSI-TR-03112-6]. Return

Return of the DestroyChannel function. Name Description dss:Result Contains the status information and the errors of an executed action. This element is described in more detail below.

Status information and errors for DestroyChannel.

Name Error codes ResultMajor -/resultmajor#ok -/resultmajor#error

ResultMinor -/resultminor/il/common#parameterError -/resultminor/ifdl/common#invalidSlotHandle

Furthermore there MAY be protocol specific return codes.

ResultMessage MAY contain more detailed information on the occurred error if required. Precondition There MAY be a cryptographic channel established with EstablishChannel.

Postcondition If there was an established cryptographic channel it has been destroyed such that subsequent calls with Transmit are not protected with secure messaging anymore. Note

5.1.1.1.4 PACEInputType and PACEOutputType In order to establish a PACE-based channel according to [BSI-TR3110] the Authenti- cationProtocolData-element in EstablishChannel MUST be of type PACEIn- putType. This type has been created based on the parameters of the Establish- PACEChannel-function defined in [BSI-TR03119] and [PC/SC-PACE]1.

This type specifies the structure of the AuthenticationProtocolData element in EstablishedChannel, if a PACE-based channel is to be established. Name Description PinID This element provides the key reference of the pass- word object for which a PACE-based channel is to be established. According to [BSI-TR3110] there are the following possibilities:  0x01: MRZ  0x02: CAN  0x03: PIN  0x04: PUK

1 Note that the CertificateDescription-element is not part of the EstablishPACEChannel-parameters defined in [PC/SC-PACE], but only appears in [BSI-TR03119].

CHAT If the cryptographic channel is to be established within the scope of a full EAC-based authentication procedure, in which Terminal Authentication is used after PACE, this element contains the Certificate Holder Au- thorization Template (CHAT) according to [BSI- TR3110], Annex C.1.5. PIN If the CAN is to be used for PACE it MAY be provided in this element. CertificateDescription This element contains the ASN.1-based Certific- ateDescription as specified in [BSI-TR3110], An- nex C.3.1.

The EstablishChannelResponse returns data of type PACEOutputType in the Au- thenticationProtocolData element:

This type specifies the structure of the PACEOutputType, which is returned in the Au- thenticationProtocolData element of the EstablishChannelResponse. Name Description StatusBytes This element contains the status bytes, which are returned by the card after calling MSE:Set AT. EF_CardAccess This element contains the content of the elementary file EF.Car- dAccess. CAR The Certificate Authority Reference(s) (CAR) are REQUIRED if PACE is used with a CHAT. In this case the present element corresponds to data object 0x87 and contains the most recent CAR with respect to the terminal type indicated in the CHAT. CARprev If present, this element corresponds to data object 0x88 and contains the previous CAR. IDicc If PACE is used with a CHAT, this element contains the identifier

of the chip.

5.1.2 Internal Design

5.2 GUI

5.2.1 Interface

5.2.1.1 ObtainUserConsent The different platform-specific GUI-modules MUST provide the ObtainUserConsent function described in the following.

Name ObtainUserConsent Description The ObtainUserConsent function may be called by the IFD for example to initiate a user consent dialogue. Invocation parameters

’ Invocation of the ObtainUserConsent function. Name Description Title This element provides general information about the user dialogue, which SHOULD be displayed to the user in a window frame for example. gui:Step This element MAY appear multiple times and describes an individual step in the specified user dialogue procedure. Details with respect to this element are described below.

DialogueType This element MAY be present to provide a hint, which indicates that a specific user dialogue is requested. This information MAY be evaluated by specific GUI-implementations to provide an optimised user interface.

Presently there is exactly one specialised user dialogue defined:  http://ws.openecard.org/gui/dt/npa - indicates that an nPA-specific dialogue to obtain user consent is requested.

gui:Step is part of the ObtainUserConsent-function and describes an individual step of the user dialogue. Name Description Name This element provides the name of the step within the user dialogue, which SHOULD be displayed to the user to outline the overall user dialogue and the current state. InfoUnit Each step consists of one or more individual input or output units described by an InfoUnit-element.

The InfoUnit-element may appear one or more times within a step and is a choice of different input and output elements. Name Description Text This element contains textual information, which is displayed to the user.

gui:Hyperlink This element realizes a hyperlink and contains the following attributes:  text – is the textual information, which is displayed to the user. If this attribute is missing, the URL contained in the href-Attribute is displayed to the user.  href – specifies the linked URL. gui:CheckBox This element realizes a system of check- boxes, which consists of a sequence of gui:BoxItem-elements. Such an element contains the following attributes:  text – is the textual information, which is displayed to the user. If this attribute is missing, the name-attribute is displayed to the user.  name – is an identifier for the gui:BoxItem-element.  checked – indicates whether the checkbox item is marked or not.  disabled – indicates whether the checkbox item is editable or not. gui:Radio This element realizes a system of radio buttons, which consists of a sequence of gui:BoxItem-elements, which contain the attributes explained above. gui:TextInput This element realizes an input field for plain text and contains the following attributes:  text – is the textual information, which is displayed to the user. If this attribute is missing, the name-attribute is displayed to the user.  name – is an identifier for the present element.  value – is the value of the input field.  minLength – may be used to specify the minimum length of the requested text input.  maxLength – may be used to specify the maximum length of the requested text input. gui:PasswordInput This element realizes an input field for se- crets. For each entered character an aster- isk (or similar character) is displayed. This element has the same attributes as the gui:TextInput-element above.

Return

Return of the ObtainUserConsent function.

Name Description dss:Result Contains the status information and the errors of an executed action. This element is described in more detail below. Output For each input element of type gui:Check- Box, gui:Radio, gui:TextInput and gui:PasswordInput present in the Obtai- nUserConsent-call there is a corresponding Output-element.

Status information and errors for ObtainUserConsent. Name Error codes ResultMajor -/resultmajor#ok -/resultmajor#error

ResultMinor -/resultminor/il/common#parameterError

ResultMessage MAY contain more detailed information on the occurred error if required. Precondition

Postcondition

5.2.2 Internal Design

References [BSI-TR3110] BSI: Advanced Security Mechanism for Machine Readable Travel Documents – Extended Access Control (EAC), Technical Directive of the Federal Office for Information Security Nr. 03110, BSI TR- 03110, Version 2.05, https://www.bsi.bund.de/ContentBSI/Publika- tionen/TechnischeRichtlinien/tr03110/index_htm.html [BSI-TR-03112-1] BSI: eCard-API-Framework – Part 1 – Overview and Generic Mechanisms, Technical Guideline of the BSI no. 03112-1, v1.1, via https://www.bsi.bund.de/SharedDocs/Downloads/DE/BSI/Publika- tionen/TechnischeRichtlinien/TR03112/API/api1_teil1_pdf.pdf? __blob=publicationFile [BSI-TR-03112-2] BSI: eCard-API-Framework – Part 2 – eCard-Interface, Technical Guideline of the BSI no. 03112-2, v1.1, via https://www.b- si.bund.de/SharedDocs/Downloads/DE/BSI/Publikationen/Technis- cheRichtlinien/TR03112/API/api1_teil2_pdf.pdf?__blob=publica- tionFile [BSI-TR-03112-3] BSI: eCard-API-Framework – Part 3 – Management Interface, Technical Guideline of the BSI no. 03112-3, v1.1, via https://www.bsi.bund.de/SharedDocs/Downloads/DE/BSI/Publika- tionen/TechnischeRichtlinien/TR03112/API/api1_teil3_pdf.pdf? __blob=publicationFile [BSI-TR-03112-4] BSI: eCard-API-Framework – Part 4 – ISO24727-3 Interface, Tech- nical Guideline of the BSI no. 03112-4, via https://www.bsi.bund.de/SharedDocs/Downloads/DE/BSI/Publika- tionen/TechnischeRichtlinien/TR03112/API/api1_teil4_pdf.pdf? __blob=publicationFile [BSI-TR-03112-5] BSI: eCard-API Framework – Part 5 – Support Interface, Technical Guideline of the BSI no. 03112-5, via https://www.bsi.bund.de/SharedDocs/Downloads/DE/BSI/Publika- tionen/TechnischeRichtlinien/TR03112/API/api1_teil5_pdf.pdf? __blob=publicationFile [BSI-TR-03112-6] BSI: eCard-API-Framework – Part 6 – Reader Interface, Technical Guideline of the BSI no. 03112-6, via https://www.bsi.bund.de/SharedDocs/Downloads/DE/BSI/Publika- tionen/TechnischeRichtlinien/TR03112/API/api1_teil6_pdf.pdf? __blob=publicationFile [BSI-TR-03112-7] BSI: eCard-API-Framework – Part 7 – Protocols, Technical Guideline of the BSI no. 03112-7, via https://www.bsi.bund.de/SharedDocs/Downloads/DE/BSI/Publika- tionen/TechnischeRichtlinien/TR03112/API/api1_teil7_pdf.pdf? __blob=publicationFile [BSI-TR03119] BSI: Requirements for Card Terminals with support for the new German eID-card, in German, Technical Directive of the Federal Office for Information Security Nr. 03119, BSI TR-03119, Version

1.2, 27.03.2011, https://www.bsi.bund.de/SharedDocs/Downloads/DE/BSI/Publika- tionen/TechnischeRichtlinien/TR03119/BSI-TR-03119_V1_pdf.pdf? __blob=publicationFile

[EHP+10] D. Eske, D. Hühnlein, S. Paulus, J. Schmölz, T. Wich, T. Wieland: OpeneGK – Benutzerfreundliche und sichere Authentisierung für Mehrwertdienste im Gesundheitswesen, in Tagungsband „perspeGKtive 2010 – Workshop ‚Innovative und sichere Informationstechnologie für das Gesundheitswesen von morgen’“, GI-Edition Lecture Notes in Informatics (LNI) 174, 2010, Seiten 83- 103, via http://www.ecsec.de/pub/openeGK.pdf

[ISO29115-CD] ISO/IEC CD 29115: Information technology – Security techniques – Entity authentication assurance framework, 2010

[NIST-800-63] National Institute of Standards and Technology (NIST): Electronic Authentication Guideline, NIST Special Publication 800-63 Version 1.0.2, http://csrc.nist.gov/publications/nistpubs/800-63/SP800- 63V1_0_2.pdf

[OpenID(v2.0)] OpenID Foundation: OpenID Authentication 2.0. Final, December 5, 2007. http://openid.net/specs/openid-authentication-2_0.html .

[PAuswG] Gesetz über Personalausweise und den elektronischen Identitätsnachweis (Personalausweisgesetz – PAuswG), Artikel 1 des Gesetzes vom 18. Juni 2009, http://www.bmi.bund.de/cae/servlet/contentblob/607490/publication File/34857/eperso.pdf [PC/SC-PACE] PC/SC Workgroup: Interoperability Specification for ICCs and Personal Computer Systems - Part 10 IFDs with Secure PIN Entry Capabilities – Amendment 1, 2011, http://www.pcscworkgroup.com/specifications/files/pcsc10_v2.02.0 8_AMD1.pdf

[SAML(v2.0)] S. Cantor, J. Kemp, R. Philpott, E. Maler: Assertions and Protocol for the OASIS Security Assertion Markup Language (SAML) V2.0. OASIS Standard, 15.03.2005, http://docs.oasis- open.org/security/saml/v2.0/saml-core-2.0-os.pdf , 2005.

 2011, Open eCard Team CONFIDENTIAL Page 17