Open eCard

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.

*Notes*

<pre>

TODO

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

</pre>

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:4346@

   TLSv1.1 according to [RFC4346].

** @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:4346@, @urn:ietf:rfc:5246@)

* PathSecurity-Parameter is optional because of the additional TLS protocol (@urn:ietf:rfc:4346@).

h2. GetStatus[1]

*URL*

@http://127.0.0.1:24727/getStatus@

or 

@http://127.0.0.1:24727/eID-Client?Status@

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 |

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

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.