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.	Optional¹
slotIndex	The slotIndex determines the slot in the terminal.	Optional¹
contextHandle	The contextHandle addresses a specific IFD.	Optional¹
slotHandle	The slotHandle determines a connected eCard. See TR-03112-6, section 3.2.1.	Optional¹
cardType	The cardType determines the type of card which must be selected.	Optional¹

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).

GetStatus¹¶

URL
http://127.0.0.1:24727/getStatus

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).
- Name must be set to "Open eCard App" for all client types of the Open eCard App.
- VersionMajor, VersionMinor and VersionSubminor correspond to the major, minor and patch fields in the Version class.
  (see source:common/src/main/java/org/openecard/client/common/Version.java)
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:

ConnectionHandle
The meaning of the ConnectionHandle parameter is exactly as in the StartPAOS call defined in [BSI-TR-03112-7, Section 2.6].
Action
This element contains the URI describing the event. Currently there are the following event types defined:

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.

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

Client Control Interface¶

Activation¶

GetStatus1¶

ShowUI¶

WaitForChange¶

GetStatus¹¶