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

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?

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="Binding" type="anyURI" maxOccurs="1" minOccurs="0"/>
    <element name="PathSecurity-Protocol" type="anyURI" />
    <element name="PathSecurity-Parameter" maxOccurs="1" 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.
• Binding
  May 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
• 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:4346
    TLS according to [RFC4346].
  • urn:ietf:rfc:4279
    TLS-PSK according to [RFC4279].
  • urn:ietf:rfc:5487
    TLS-PSK with a cipher suite according to [RFC5487].
• PathSecurity-Parameter
  Must be present to supply path security parameters such as PSK values.

The following changes are made to the token type defined in [eCard-7]:

• Binding is optional to use solely the transport protocol for authentication.
• PathSecurity-Protocol has an additional value. (urn:ietf:rfc:4346)
• PathSecurity-Parameter is optional because of the additional default TLS Protocol.

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

TODO: define Status element

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.

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.

TODO: define StatusChange element

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.