Project

General

Profile

Client Control Interface

The Client Control Interface is http based. The webserver of the eCard client is available only under http://localhost:24724.

Activation

URL
http://127.0.0.1:24727/eID-Client

Method
GET

Query
tcTokenURL The URL determines where the client can retrieve the TC Token. See TR-03112-7, section 3.2 Mandatory
ifdName The ifdName determines the card terminal. Optional1
slotIndex The slotIndex determines the slot in the terminal. Optional1
contextHandle The contextHandle addresses a specific IFD. Optional1
slotHandle The slotHandle determines a connected eCard. See TR-03112-6, section 3.2.1. Optional1
cardType The cardType determines the type of card which must be selected. Optional1
Returns
200 OK The refresh address is comprised in the Message Body (Hack for Mac OS Safari).
303 See Other The Location field in the response should contain the refresh address.
400 Bad Request Malformed GET request, e.g. parameters are missing.
500 Internal Server Error Other errors.
502 Bad Gateway Server where the TCToken was requested, didn't answer or returned an invalid response.
Content-Types
text/html Webpage with user evaluatable content. E.g. error page, manual redirect, ...

Description
The interface can be used to start the eID application.

The parameters ifdName, contextHandle, slotHandle and cardType address a particular eCard, or a type of card.
There are three meaningful combinations of the optional parameters:
  • none
    Use the fist nPa available. Display a "Please insert nPa" dialog if needed. This is the behaviour of the AusweisApp.
    In other words the lack of the cardType parameter sets it to the default value http://bsi.bund.de/cif/npa.xml, and thus the next rule becomes effective.
  • cardType
    Use the fist card of the specified type which is available. Display a "Please insert <cardType>" dialog if needed.
    A special case must be made when software certificates (cardType=http://openecard.org/cif/soft-credential) are used. In that case no dialog is shown, when there is no certificate. Instead an error is produced.
  • ifdName, contextHandle, slotHandle
    Use exactly the card matching the parameters.
    cardType is requested from the selected card directly. If there is no such card, an error is produced.

During the processing of the activation, a TCToken is fetched from a remote server.
The TCToken is defined as follows:

<element name="TCToken" type="TCTokenType" />

<complexType name="TCTokenType">
  <sequence>
    <element name="ServerAddress" type="anyURI" />
    <element name="SessionIdentifier" type="string" />
    <element name="RefreshAddress" type="anyURI" />
    <element name="CommunicationErrorAddress" type="anyURI" minOccurs="0" />
    <element name="Binding" type="anyURI" />
    <element name="PathSecurity-Protocol" type="anyURI" minOccurs="0" />
    <element name="PathSecurity-Parameters" minOccurs="0">
      <complexType>
        <choice>
          <element name="PSK" type="hexBinary" />
        </choice>
      </complexType>
    </element>
  </sequence>
</complexType>

The contents of the elements are defined as follows:
  • ServerAddress
    Must contain a https-URL which shall be used by the eCA to connect to the authentication server.
  • SessionIdentifier
    Must contain a unique identifier of the current authentication session.
  • RefreshAddress
    Must be a https-URL. The eCA redirects the browser to this URL (or the URL retrieved by following redirects starting from this URL) after conclusion of the online authentication.
  • CommunicationErrorAddress
    If present, the eID-Client redirects the browser to this URL if an communication error occurred and no valid refreshURL could be determined. The URL MAY contain a session ID.
  • Binding
    Must be used to indicate that an authentication protocol according to [ISO24727-3] is to be performed over the session between eCA and the authentication server.
    Currently the following values are defined:
    • urn:liberty:paos:2006-08
    • urn:ietf:rfc:2616
  • PathSecurity-Protocol
    This element specifies the security protocol, which is to be used for securing the connection between eCA and AS.
    Currently the following values are defined:
    • urn:ietf:rfc:5246
      TLSv1.2 according to [RFC5246].
    • urn:ietf:rfc:4279
      TLS-PSK according to [RFC4279].
  • PathSecurity-Parameter
    May be present to supply path security parameters such as PSK values. Must be present if PathSecurity-Protocol is urn:ietf:rfc:4279.
The following changes are made to the token type defined in [TR-03124-1]:
  • PathSecurity-Protocol has additional values. (urn:ietf:rfc:5246)
  • PathSecurity-Parameter is optional because of the additional TLS protocol (urn:ietf:rfc:5246).

 

GetStatus1

URL
http://127.0.0.1:24727/getStatus

or

http://127.0.0.1:24727/eID-Client

The second URL was made available later to be conform to the newest version of BSI-TR03124.

Method
GET

Query
session The session parameter establishes an event queue for further requests with waitforChange. Optional
Status The Status parameter is restricted to be used with the second URL and indicates that the status is requested from the eID-Client resource. Mandatory for second URL
Returns
200 OK Status element (see below).
400 Bad Request Malformed GET request, e.g. session parameter is too weak.
500 Internal Server Error Errors in the smartcard stack or the webserver.
<complexType name="StatusType" xmlns:oec="http://ws.openecard.org/schema" targetNamespace="http://ws.openecard.org/schema">
  <sequence>
    <element name="ConnectionHandle" type="iso:ConnectionHandleType" maxOccurs="unbounded" minOccurs="0" />
    <element name="UserAgent"                                        maxOccurs="1"         minOccurs="0">
      <complexType>
        <sequence>
          <element name="Name"            type="string" />
          <element name="VersionMajor"    type="integer" />
          <element name="VersionMinor"    type="integer" maxOccurs="1" minOccurs="0" />
          <element name="VersionSubminor" type="integer" maxOccurs="1" minOccurs="0" />
        </sequence>
      </complexType>
    </element>
    <element name="SupportedAPIVersions" maxOccurs="unbounded" minOccurs="0">
      <complexType>
        <sequence>
          <element name="Name"            type="string" />
          <element name="VersionMajor"    type="integer" />
          <element name="VersionMinor"    type="integer" maxOccurs="1" minOccurs="0"/>
          <element name="VersionSubminor" type="integer" maxOccurs="1" minOccurs="0"/>
        </sequence>
      </complexType>
    </element>
    <element name="SupportedCards" maxOccurs="unbounded" minOccurs="0">
      <complexType>
        <sequence>
          <element name="CardType" type="anyURI" maxOccurs="1" minOccurs="1" />
          <element name="DIDProtocols" type="anyURI" maxOccurs="unbounded" minOccurs="0" />
        </sequence>
      </complexType>
    </element>
    <element name="SupportedDIDProtocols" type="anyURI" maxOccurs="unbounded" minOccurs="0" />
    <element name="AdditionalFeatures"    type="anyURI" maxOccurs="unbounded" minOccurs="0" />
  </sequence>
</complexType>

<element name="Status">
  <complexType>
    <complexContent>
      <extension base="oec:StatusType">
        <sequence />
      </extension>
    </complexContent>
  </complexType>
</element>
The contents of the Status element are defined as follows:
  • ConnectionHandle
    List of ConnectionHandles reflecting the currently available terminals, cards and their types.
  • UserAgent
    Description of the user agent (client).
  • SupportedAPIVersions
    This element names and describes all supported API versions. At the moment, this is solely the eCard-API.
    • Name and the version elements are one of
      • http://www.bsi.bund.de/ecard/api, 1, 1, not set
  • SupportedCards
    List of supported DIDProtocols per card type. That means the list of DIDProtocols, for which an implementation exists and which are listed in the respective CardInfo file.
  • SupportedDIDProtocols
    List of supported DID protocols. That means the list of SAL modules' DID protocol URIs registered in the client.
  • AdditionalFeatures
    Not yet defined, but could be further stuff like a Signature plugin etc.
Content-Types
text/xml The Status element.
text/html Message in case of an error.

Description
The interface can be used to request information about the eID application and its current state.

 

ShowUI

URL
http://127.0.0.1:24727/eID-Client

Method
GET

Query
ShowUI The query parameter has to have a module name as value indicating the GUI component to open. Mandatory
Returns
200 OK The GUI was opened successfully there are no other status codes.

Content Types
none

Description
The interface opens an GUI component which is specified by the components name in the ShowUI query parameter. The following components are currently accessible:

PINManagement Opens the UI for the PIN management
Settings Opens the Settings dialog

If the parameter ShowUI does not contain a module name or contains a unknown module name the default UI is opened. In case of the Swing GUI this is the About dialog.

 

WaitForChange

URL
http://127.0.0.1:24727/waitForChange

Method
GET

Query
session The session of a previously set up event queue (see GetStatus). Mandatory
Returns
200 OK StatusChange element (see below).
400 Bad Request Malformed GET request, e.g. session parameter is too weak.
500 Internal Server Error Errors in the smartcard stack or the webserver.
<complexType name="StatusChangeType" xmlns:oec="http://ws.openecard.org/schema" targetNamespace="http://ws.openecard.org/schema">
  <sequence>
    <element name="ConnectionHandle" type="iso:ConnectionHandleType" maxOccurs="1" minOccurs="1" />
    <element name="Action"           type="anyURI"                   maxOccurs="1" minOccurs="1" />
  </sequence>
</complexType>

<element name="StatusChange">
  <complexType>
    <complexContent>
      <extension base="oec:StatusChangeType">
        <sequence />
      </extension>
    </complexContent>
  </complexType>
</element>

The contents of the StatusChange element are defined as follows:

Content-Types
text/xml The StatusChange element.
text/html Message in case of an error.

Description
The interface can be used to request status change information after an initial GetStatus call.


1 Openecard proposal: This parameter/interface is an Open eCard specific extension. It is not part of the official eCard specification.

Also available in: PDF HTML TXT