Project

General

Profile

Control Interface » History » Revision 30

Revision 29 (Max Tuengerthal, 06/03/2014 11:07 AM) → Revision 30/40 (Max Tuengerthal, 06/03/2014 11:32 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" 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 be present to supply path security parameters such as PSK values. This parameter must be present if PathSecurity-Protocol has the value @urn:ietf:rfc:4279@ or @urn:ietf:rfc:5487@. 

 The following changes are made to the token type defined in [TR-03124-1]: 
 * PathSecurity-Protocol has an additional value. (@urn:ietf:rfc:4346@) 
 * PathSecurity-Parameter is optional because of the additional default TLS protocol (@urn:ietf:rfc:4346@). 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.