h1. Client Control Interface

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

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

*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:
<pre><code class="xml">
<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>
</code></pre>

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

&nbsp;

h2. GetStatus[1]

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

<pre><code class="xml">
<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>
</code></pre>

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.

&nbsp;

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

&nbsp;

h2. WaitForChange

*URL*
@http://127.0.0.1:24727/waitForChange@

*Method*
GET

*Query*
| session | The session of a previously set up event queue (see [[Client_Activation#GetStatus1|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. |

<pre><code class="xml">
<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>
</code></pre>

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.


---

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