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

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.
• cardType
  Use the fist card of the specified type which is available. Display a "Please insert <cardType>" dialog if needed.
• ifdName, contextHandle, slotHandle
  Use exactly the card matching the parameters.

Notes

TODO
* What happens if the Client Activator cannot start an application?
* What happens if the Client Activator cannot fetch a TC Token from the given TCTokenURL? Should that result in a 400 or 404?

GetStatus¹¶

URL
http://127.0.0.1:24727/getStatus

Method
GET

Query

session

The session parameter establishes an event queue for further requests with waitforChange.

Optional

Returns

200 OK	Status element (see below).
500 Internal Server Error	Errors in the smartcard stack or the webserver.

TODO: define Status element

Content-Types

text/xml	The Status element.
text/html	Error message in case of a 500 status code.

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

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).
500 Internal Server Error	Errors in the smartcard stack or the webserver.

TODO: define StatusChange element

Content-Types

text/xml	The StatusChange element.
text/html	Error message in case of a 500 status code.

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.