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.

Notes

TODO
* What happens if the Client Activator cannot start an application?

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

<element name="TCTokenType" 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
• 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: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.

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

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:
  • http://openecard.org/event/terminal_added
  • http://openecard.org/event/terminal_removed
  • http://openecard.org/event/card_inserted
  • http://openecard.org/event/card_removed
  • http://openecard.org/event/card_recognized

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.