eiD-Server Component Interaction Diagram

[Christiantyemele]

This is a summary of the interaction involved in a eid based document verification process(soap model with saml interface), this was done with the help of multiple models and based on my own studies, so we have a common understanding of the flow,

[Christiantyemele]

Step-by-step interaction process (standard SOAP model):
The online authentication process, as described in the sources for the SOAP interface, involves several steps of interaction between the eService, the eID-Server and the eID-Client:

1. Initiation by eService ( useID Request): The eService, acting as the web application presented in the user's browser, initializes a new online authentication by calling the useID function on the eID-ServerIn this request, the eService specifies the operations that the eID-Server should perform with the user's eID document (e.g., reading data groups, age/location verification, requesting transaction attestation).
2. eID-Server Response ( useID Response): The eID-Server responds to the useID call by opening a new single session for authenticationThe useID response contains a Session ID that connects the useID and getResult calls .. It can also include the address of the eID-Server for the eCard-API-Framework component ( eCardServerAddress ).
3. Transmission of the TC Token (by the eService to the eID-Client): The eService uses the information received in the useID response (including the session ID and the Server-SAL address) to create a TC TokenThis TC Token contains the connection parameters necessary for the eID-Client to communicate with the eID-Server.The eService then transmits this TC Token to the user's eID-Client.
4. Establishing the secure channel (from the eID-Client to the eID-Server): This is where the "groundwork" begins from the eID-Server's perspective. The eID-Client, after receiving the TC Token, establishes a secure channel (TLS-2) to the eCard-API-Framework interface of the eID-Server (the Server-SAL component) .The eID-Server must verify that the SessionIdentifier of the PSK used by the eID-Client matches a session ID previously negotiated via the eID interface (the useID call ).
5. Execution of operations with the eID document (by the eID-Server): Via the secure TLS-2 channel established by the eID-Client, the eID-Server components work with the user's eID document, guided by the operations requested in the useID call.
   ◦ The Server-SAL (eCard-API-Framework) manages the exchange of SOAP/PAOS commands and data encapsulated in TLS with the eID-Client.
   ◦ The EAC Terminal-Application performs the EAC protocols, including Passive Authentication, la Chip Authenticationand reading the required data.
   ◦ The PKI communication component is requested to check the validity of the eID document (via the Document Security Object), the revocation status via the revocation lists (Black List), and the authenticity of the certificates.
6. Polling Results ( getResult Requests): While the eID-Server performs the operations in step 5 (which may take some time), the eService repeatedly calls the getResult function on the eID-Server. Each getResult request includes the session ID and a request counter ( RequestCounter ).
7. Response to getResult requests :
   ◦ If the eID-Server has not yet completed operations with the eID document, it responds to the getResult request by indicating that the result is not yet ready (implicit in the polling mechanism).
   ◦ Once the eID-Server has completed all requested operations and collected the data and verification results, it responds to the next getResult request with the final response ( getResultResponse )This response contains the data read ( PersonalData ), the results of the checks (age, location, validity of the document, revocation), the list of authorized operations, and potentially a transaction certificate and an assurance level achieved.
8. Session Invalidation: After returning the final response with the results via getResult , the eID-Server invalidates the corresponding authentication session

[Christiantyemele]

@hugoib @Hermann-Core @ndefokou @Ngha-Boris @Blindspot22 reviews from you here will be appreciated

[Christiantyemele]

Flow from TC token to document verification

Here is a step-by-step description, based on the provided sources, of the communication flow and eID document verification actions by the eID server, once the eID client has obtained the server address via the TC Token:

1. The eID client retrieves and processes the TC Token:

   • The user initiates the process, typically by clicking on a link provided by the eService. This link contains the TC Token URL (tcTokenURL).
   • The eID client, activated by the URL, connects to this tcTokenURL using an HTTP GET request.
   • The eService (or a SAML processor acting for the eService in certain cases) responds by sending the TC Token. The TC Token is an XML fragment that contains crucial information, including the ServerAddress of the eID-Server, a SessionIdentifier, the Binding (PAOS v2.0), and potentially path security parameters such as a PSK (Pre-Shared Key).
   • The eID client extracts this information from the TC Token.

2. The eID client establishes a secure connection with the eID-Server:

   • Using the ServerAddress, SessionIdentifier, Binding, and PSK extracted from the TC Token, the eID client establishes a connection with the eID-Server. This connection is made between the Client-SAL of the eID client and the Server-SAL of the eID-Server.
   • A TLS (Transport Layer Security) session is negotiated to secure this communication channel. If a PSK is provided in the TC Token (which comes from the eService or SAML processor, potentially negotiated beforehand with the eID server via the useID function), a PSK cipher suite MUST be used for this TLS session (TLS-2) to ensure session binding.
   • Once the TLS session is established, SOAP/PAOS-based communication is established using the StartPAOS function. The PAOS communication is encapsulated in the secure TLS channel. The eID client sends StartPAOS to the Server-SAL.

3. The eService has already initiated the process via useID:

   • It is important to note that, before the eID-Client requests the TC Token, the eService has generally already initiated the server-side process by calling the useID function of the eID-Server.
   • During the useID call, the eService specifies the operations to be performed with the user's eID document, such as reading data groups (name, address, etc.) and performing specific verifications like age or location verification. The eService may also include transaction information and may have transmitted a PSK for this session.
   • The useIDResponse response from the eID-Server contains information for the eService, including the session ID (Session), the address where the eID client must contact the server (eCardServerAddress, which will be put in the TC Token ServerAddress) and the PSK to include in the TC Token.

4. The eID-Server requests document verification (even if not specifically requested in useID):

   • After establishing the secure channel (TLS/PAOS) with the eID client, control is transferred to the eID-Server. The eID-Server uses the eCard-API to communicate with the eID document via the client.
   • Regardless of the specific operations requested by the eService in the useID function, the eID-Server MUST perform a verification of the eID-Document validity. This is a mandatory part of the online authentication process managed by the eID server.
   • The mandatory validity checks that the eID-Server MUST perform include:
     • Chip Authentication: This is part of the general authentication procedure. The eID-Server sends DIDAuthenticate commands to the eID client, particularly with EAC2InputType, containing information necessary for the card to authenticate the server and establish a secure channel for data reading.
     • Passive Authentication: This involves validating the document security object (Document Security Object) retrieved from the card. The eID-Server verifies the signature of this object using the ICAO PKI and a trust store of CSCA certificates. The eID client transmits the card data in response to server commands.
     • Black Lists Verification: The eID-Server MUST verify the revocation status of the eID document by consulting the black lists it regularly retrieves.
     • Validity date verification: The eID-Server MUST verify that the eID document is not expired.
   • The eID-Server uses eCard-API commands such as Transmit to send APDU (Application Protocol Data Units) to the eID document via the connection with the client in order to perform these authentication protocols and retrieve the data requested by the eService in useID.

5. The eID server collects the results and the eService retrieves them:

   • Once the operations requested by the eService (in useID) and the mandatory document validity verification by the server are completed, the eID-Server prepares the results.
   • The eService retrieves these results by calling the getResult function of the eID-Server, using the previously established session ID. The eService may call getResult multiple times until the result is available.
   • The getResultResponse response from the eID-Server contains the results of the online authentication, including the data read, verification results (age, location) and the document validity status (potentially indicated by an error code or status in the DocumentValidityResultType element if the SAML protocol is used). The eID-Server MUST include the result of the document validity verification in each SAML response.

In summary, after using the TC Token to connect to the eID-Server and establish a secure channel, the eID client serves as a communication bridge. The eID-Server, having been informed of the eService's needs via the useID function, takes control of the interaction. During this phase, the eID-Server uses eCard-API commands to communicate with the eID document (via the client) and MANDATORILY executes the document validity verification steps (Chip Authentication, Passive Authentication, black lists, validity), in addition to reading the data requested by the eService. The results of this verification are part of the information that the eService obtains by calling the getResult function.

sequenceDiagram
    participant User as User
    participant eService as eService
    participant eIDClient as eID Client
    participant eIDServer as eID Server
    participant eIDCard as eID Card/Document

    Note over eService, eIDServer: Phase 1: Initial Setup
    eService->>eIDServer: 1. useID() call
    Note right of eService: Specifies operations:<br/>- Data groups to read<br/>- Age/location verification<br/>- Transaction info<br/>- PSK (optional)
    eIDServer->>eService: 2. useIDResponse
    Note left of eIDServer: Returns:<br/>- Session ID<br/>- eCardServerAddress<br/>- PSK for TC Token

    Note over User, eIDCard: Phase 2: TC Token Process
    User->>eService: 3. Click authentication link
    eService->>User: 4. Redirect to tcTokenURL
    User->>eIDClient: 5. Activate eID Client via URL
    eIDClient->>eService: 6. HTTP GET tcTokenURL
    eService->>eIDClient: 7. TC Token (XML)
    Note right of eService: Contains:<br/>- ServerAddress<br/>- SessionIdentifier<br/>- Binding (PAOS v2.0)<br/>- PSK

    Note over eIDClient, eIDServer: Phase 3: Secure Connection
    eIDClient->>eIDServer: 8. Establish TLS connection
    Note right of eIDClient: Uses PSK cipher suite<br/>if PSK provided
    eIDClient->>eIDServer: 9. StartPAOS (SOAP/PAOS)
    Note right of eIDClient: Encapsulated in TLS

    Note over eIDServer, eIDCard: Phase 4: Mandatory Document Verification
    rect rgb(240, 240, 240)
        Note over eIDServer, eIDCard: MANDATORY VERIFICATION STEPS
        eIDServer->>eIDClient: 10. DIDAuthenticate (EAC2InputType)
        eIDClient->>eIDCard: 11. Chip Authentication
        eIDCard->>eIDClient: 12. Authentication Response
        eIDClient->>eIDServer: 13. Authentication Result
        
        eIDServer->>eIDClient: 14. Transmit (APDU commands)
        eIDClient->>eIDCard: 15. Passive Authentication
        eIDCard->>eIDClient: 16. Document Security Object
        eIDClient->>eIDServer: 17. Security Object Data
        
        Note over eIDServer: 18. Verify signature using<br/>ICAO PKI & CSCA certificates
        Note over eIDServer: 19. Check Black Lists<br/>(revocation status)
        Note over eIDServer: 20. Verify expiration date
    end

    Note over eIDServer, eIDCard: Phase 5: Data Operations (if requested)
    alt Data reading requested in useID
        eIDServer->>eIDClient: 21. Read data groups
        eIDClient->>eIDCard: 22. Data retrieval commands
        eIDCard->>eIDClient: 23. Personal data
        eIDClient->>eIDServer: 24. Retrieved data
    end

    alt Age/Location verification requested
        Note over eIDServer: 25. Perform verification<br/>based on retrieved data
    end

    Note over eService, eIDServer: Phase 6: Result Collection
    eService->>eIDServer: 26. getResult() (polling)
    alt Results not ready
        eIDServer->>eService: 27. Not ready response
        eService->>eIDServer: 26. getResult() (retry)
    end
    
    eIDServer->>eService: 28. getResultResponse
    Note left of eIDServer: Contains:<br/>- Authentication results<br/>- Retrieved data<br/>- Verification results<br/>- Document validity status<br/>- Error codes (if any)

    Note over User, eIDCard: Process Complete
    eService->>User: 29. Authentication complete<br/>(success/failure)

Loading

[Ngha-Boris]

Hello @Christiantyemele thank you for your research, I just have a part to point out, I cannot find the part that talks about the transmit channel in the diagram that you have above. Is this intentional or is there a reason you did not include it as one of the phases?