Control Interface » History » Revision 28
Revision 27 (Tobias Wich, 03/10/2014 02:47 PM) → Revision 28/40 (Max Tuengerthal, 06/03/2014 10:52 AM)
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" 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> </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@ 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 May 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]: * PathSecurity-Protocol has an additional value. (@urn:ietf:rfc:4346@) * PathSecurity-Parameter is optional because of the additional default TLS Protocol. h2. GetStatus[1] *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. | <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.