eID Flow¶

This document provides guidance on the flow of the German eID card (and the similar electronic residence permit) within the PID issuance and the related AusweisApp-SDK.

AusweisApp SDK¶

Governikus provides the open source AusweisApp SDK on behalf of the BMI (Ministry of Interior) for reading the German eID Card. Additionally, it is recommended to use the AusweisApp SDK Wrapper for easier integration into the Wallet app.

eID internal state machine¶

The eID has several authentication mechanisms:

mechanism	digits	initial values	changeable	limitations
PIN (Personal Identification Number)	6	PIN letter (5 digits transport PIN)	yes, transport-PIN must be changed before first usage	retry counter = 3
CAN (Card Access Number)	6	printed on the card	no	no limitations
PUK (Personal Unblocking Key)	10	PIN letter	no	usage counter = 10

The eID-PIN and the transport-PIN are actually the same PIN, with the 5 digits on the PIN letter being the initial value. Before the eID is usable, the transport-PIN must be changed to a 6 digit PIN chosen by the user.

The following flow chart summarizes the internal state machine of the German eID card:

Furthermore, there are some limitations, that may lead to confusion. It is not possible to:

find out if the transport-PIN is still active or was already changed
reset the eID-PIN using the PUK, the PUK only resets the retry counter
find out if the card is the German eID or the electronic residence permit before reading the actual eID data

Requirements for eID Client¶

In the PID issuance, the wallet app (WI) is the eID Client and the PID Provider is the eID service provider. The law for the German National ID card (PAusweisG §18) requires specific information to be available and displayable to the user by the eID Client. TR-03124 is the guideline for eID Clients provided by BSI. Part 1 Section 3.8 "User Interface" also lists more detailed requirements. The following is a summary of requirements that apply to our use case and need to be displayed to the user: - the eID attributes (also called access rights) to be read MUST be displayed, using texts from TR-03127 Annex C - as the PID issuance only has required eID attributes and no optional attributes, a selection/restriction through the user can be omitted - this is done using accessRights from onAccessRights - information from the service provider's certificate MUST be displayed to the user - the name and URL of the service provider (also called eService, or Authentication Terminal), this is done using certificateDescription from onCertificate, e.g. subjectName and subjectURL - the name and URL of the certificate issuer (also called Document Verifier), this is done using certificateDescription from onCertificate, e.g. issuerName and issuerURL - the bodies responsible for the service provider that monitor compliance with data protection regulations - expiration day of the service provider's authorization certificate - the user MUST be informed about errors and failures to read the eID card - the user MUST be informed about the retry counter after failed PIN verification

Usage within the Wallet App¶

The Wallet App requires the usage of the German eID Card for initializing the PID. In particular, the calls to the AusweisApp SDK must be aligned with the user flow (UX) and UI screens. The following flow chart summarizes how the AusweisApp Wrapper SDK should be used: - blue boxes represent API calls from the Workflow Controller - yellow boxes represent callbacks from the Workflow Controller - green boxes represent the UI screens that the Wallet App implements

In summary: - the Wallet App does not require to understand the internal state machine of the eID card as the AusweisApp SDK is querying for the correct PIN/CAN/PUK based on reading the card - there is no possibility to determine if the transport-PIN was already set or still active, therefore we need to ask the user about this - the Wallet App should try to avoid presenting/tapping the card twice, therefore the first onInsertCard is ignored and the dialog to let the user enter his eID-PIN is shown first instead - therefore the onEnterPin() dialog can be immediately answered with setPin() - if instead the CAN or PUK is requested, we show the dialog to enter the CAN/PUK and may optionally present/tap twice - this optimizes for the more common happy case - similarly, in case the user needs to change his transport-PIN, we let him enter the transport-PIN first before tapping the eID card

Furthermore, the Wallet App should: - set status on startAuthentication() and startChangePin() to receive onStatus callbacks to display progress to the user - communicate to the user that the eID card must not be removed while the operation is ongoing, use the progress from onStatus callback to indicate an ongoing process - the eID card must not be present while the user is entering PIN/CAN/PUK/new PIN, so any onInsertCard should be ignored until the corresponding setPin(), setNewPin(), setCan() and setPuk() is fired - if onAuthenticationStartFailed, onWrapperError, onBadState or onInternalError is called, the Wallet App should send error reports as these should never occur during normal operation - beware that on Android the onInsertCard callback may not occur if the card is already present on the NFC antenna - evaluate the onReader() callback to have information on PIN retry counter for the PIN screen or get information that the card's eID functionality was deactivated or the card is blocked to show another screen - beware that if the transport-Pin is set after startAuthentication() has been started, it needs to be canceled with cancel - flush all PIN/CAN/PUK values in the code when no longer required, i.e. after the corresponding setPin(), setNewPin(), setCan() and setPuk() functions - treat the transport-PIN as the "normal" PIN and avoid additional code for it

NFC¶

Reading the eID Card requires NFC communication and is therefore a mandatory feature. Devices not supporting NFC should be excluded: - on iOS: since iPhones 7, all devices support NfC, therefore no issues - on Android: utilize uses-feature in Android manifest

Difficulties during eID handling arise from finding the correct position for the eID card due of the NFC Antenna being in different places. The Wallet App should give guidance where to present/tap the eID card: - on iOS: NFC antenna is on all new devices at the top - on Android: NFC antenna varies across all devices - use NfcAntennaInfo API supported since Android 14 (API level 34), unfortunately this is still quite new - use a database of common phones and match the device name to display the antenna information, e.g.: Samsung, Google Pixel and some others, some of these have been compiled to a machine-readable list that we may use