Project

General

Profile

Control Interface » History » Version 33

Hans-Martin Haase, 08/21/2015 09:44 AM

1 8 Tobias Wich
h1. Client Control Interface
2 1 Moritz Horsch
3 8 Tobias Wich
The Client Control Interface is http based. The webserver of the eCard client is available only under http://localhost:24724.
4 1 Moritz Horsch
5 8 Tobias Wich
h2. Activation
6
7
*URL*
8
@http://127.0.0.1:24727/eID-Client@
9
10
*Method*
11
GET
12
13
*Query*
14
| tcTokenURL    | The URL determines where the client can retrieve the TC Token. See TR-03112-7, section 3.2 | Mandatory | 
15
| ifdName       | The ifdName determines the card terminal.|  Optional[1] | 
16 24 Tobias Wich
| slotIndex     | The slotIndex determines the slot in the terminal.| Optional[1] |
17 8 Tobias Wich
| contextHandle | The contextHandle addresses a specific IFD. | Optional[1] | 
18
| slotHandle    | The slotHandle determines a connected eCard. See TR-03112-6, section 3.2.1. | Optional[1] | 
19
| cardType      | The cardType determines the type of card which must be selected. | Optional[1] |
20
21
*Returns*
22
| 200 OK                    | The refresh address is comprised in the Message Body (Hack for Mac OS Safari). |
23
| 303 See Other             | The Location field in the response should contain the refresh address. |
24
| 400 Bad Request           | Malformed GET request, e.g. parameters are missing. |
25
| 500 Internal Server Error | Other errors. |
26 20 Tobias Wich
| 502 Bad Gateway           | Server where the TCToken was requested, didn't answer or returned an invalid response. |
27 8 Tobias Wich
28
*Content-Types*
29
| text/html | Webpage with user evaluatable content. E.g. error page, manual redirect, ... |
30
31
32
*Description*
33
The interface can be used to start the eID application.
34
35
The parameters ifdName, contextHandle, slotHandle and cardType address a particular eCard, or a type of card.
36
There are three meaningful combinations of the optional parameters:
37
* _none_
38
 Use the fist nPa available. Display a "Please insert nPa" dialog if needed. This is the behaviour of the AusweisApp.
39 13 Tobias Wich
 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.
40 8 Tobias Wich
* _cardType_
41
 Use the fist card of the specified type which is available. Display a "Please insert <cardType>" dialog if needed.
42 13 Tobias Wich
 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.
43 8 Tobias Wich
* _ifdName_, _contextHandle_, _slotHandle_
44
 Use exactly the card matching the parameters.
45 13 Tobias Wich
  cardType is requested from the selected card directly. If there is no such card, an error is produced.
46 8 Tobias Wich
47
48
*Notes*
49
50 1 Moritz Horsch
<pre>
51
TODO
52
* What happens if the Client Activator cannot start an application?
53
</pre>
54
55 11 Tobias Wich
During the processing of the activation, a TCToken is fetched from a remote server.
56
The TCToken is defined as follows:
57
<pre><code class="xml">
58 28 Max Tuengerthal
<element name="TCToken" type="TCTokenType" />
59 1 Moritz Horsch
60 11 Tobias Wich
<complexType name="TCTokenType">
61
  <sequence>
62
    <element name="ServerAddress" type="anyURI" />
63
    <element name="SessionIdentifier" type="string" />
64 1 Moritz Horsch
    <element name="RefreshAddress" type="anyURI" />
65 25 Max Tuengerthal
    <element name="CommunicationErrorAddress" type="anyURI" minOccurs="0" />
66
    <element name="Binding" type="anyURI" />
67
    <element name="PathSecurity-Protocol" type="anyURI" minOccurs="0" />
68
    <element name="PathSecurity-Parameters" minOccurs="0">
69 11 Tobias Wich
      <complexType>
70
        <choice>
71
          <element name="PSK" type="hexBinary" />
72
        </choice>
73
      </complexType>
74
    </element>
75
  </sequence>
76
</complexType>
77
</code></pre>
78 1 Moritz Horsch
79 11 Tobias Wich
The contents of the elements are defined as follows:
80
* ServerAddress
81
 Must contain a https-URL which shall be used by the eCA to connect to the authentication server.
82 1 Moritz Horsch
* SessionIdentifier
83
 Must contain a unique identifier of the current authentication session.
84 11 Tobias Wich
* RefreshAddress
85
 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.
86 25 Max Tuengerthal
* CommunicationErrorAddress
87 27 Tobias Wich
 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.
88 11 Tobias Wich
* Binding
89 25 Max Tuengerthal
 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.
90 11 Tobias Wich
 Currently the following values are defined:
91
** @urn:liberty:paos:2006-08@
92 23 Tobias Wich
** @urn:ietf:rfc:2616@
93 11 Tobias Wich
* PathSecurity-Protocol
94
 This element specifies the security protocol, which is to be used for securing the connection between eCA and AS.
95
 Currently the following values are defined:
96 12 Tobias Wich
** @urn:ietf:rfc:4346@
97 32 Tobias Wich
   TLSv1.1 according to [RFC4346].
98
** @urn:ietf:rfc:5246@
99
   TLSv1.2 according to [RFC5246].
100 11 Tobias Wich
** @urn:ietf:rfc:4279@
101
   TLS-PSK according to [RFC4279].
102
* PathSecurity-Parameter
103 32 Tobias Wich
   May be present to supply path security parameters such as PSK values. Must be present if PathSecurity-Protocol is @urn:ietf:rfc:4279@.
104 11 Tobias Wich
105 29 Max Tuengerthal
The following changes are made to the token type defined in [TR-03124-1]:
106 32 Tobias Wich
* PathSecurity-Protocol has additional values. (@urn:ietf:rfc:4346@, @urn:ietf:rfc:5246@)
107 30 Max Tuengerthal
* PathSecurity-Parameter is optional because of the additional TLS protocol (@urn:ietf:rfc:4346@).
108 8 Tobias Wich
109
h2. GetStatus[1]
110
111
*URL*
112
@http://127.0.0.1:24727/getStatus@
113
114
*Method*
115
GET
116
117
*Query*
118
| session | The session parameter establishes an event queue for further requests with waitforChange. | Optional | 
119
120
*Returns*
121
| 200 OK                    | Status element (see below). |
122 14 Tobias Wich
| 400 Bad Request           | Malformed GET request, e.g. session parameter is too weak. | 
123 8 Tobias Wich
| 500 Internal Server Error | Errors in the smartcard stack or the webserver. |
124
125 16 Tobias Wich
<pre><code class="xml">
126 18 Tobias Wich
<complexType name="StatusType" xmlns:oec="http://ws.openecard.org/schema" targetNamespace="http://ws.openecard.org/schema">
127 16 Tobias Wich
  <sequence>
128
    <element name="ConnectionHandle" type="iso:ConnectionHandleType" maxOccurs="unbounded" minOccurs="0" />
129
    <element name="UserAgent"                                        maxOccurs="1"         minOccurs="0">
130
      <complexType>
131 17 Tobias Wich
        <sequence>
132
          <element name="Name"            type="string" />
133
          <element name="VersionMajor"    type="integer" />
134
          <element name="VersionMinor"    type="integer" maxOccurs="1" minOccurs="0" />
135
          <element name="VersionSubminor" type="integer" maxOccurs="1" minOccurs="0" />
136
        </sequence>
137 16 Tobias Wich
      </complexType>
138
    </element>
139
    <element name="SupportedAPIVersions" maxOccurs="unbounded" minOccurs="0">
140
      <complexType>
141 17 Tobias Wich
        <sequence>
142
          <element name="Name"            type="string" />
143
          <element name="VersionMajor"    type="integer" />
144
          <element name="VersionMinor"    type="integer" maxOccurs="1" minOccurs="0"/>
145
          <element name="VersionSubminor" type="integer" maxOccurs="1" minOccurs="0"/>
146
        </sequence>
147 16 Tobias Wich
      </complexType>
148
    </element>
149 22 Tobias Wich
    <element name="SupportedCards" maxOccurs="unbounded" minOccurs="0">
150
      <complexType>
151
        <sequence>
152
          <element name="CardType" type="anyURI" maxOccurs="1" minOccurs="1" />
153
          <element name="DIDProtocols" type="anyURI" maxOccurs="unbounded" minOccurs="0" />
154
        </sequence>
155
      </complexType>
156
    </element>
157 16 Tobias Wich
    <element name="SupportedDIDProtocols" type="anyURI" maxOccurs="unbounded" minOccurs="0" />
158
    <element name="AdditionalFeatures"    type="anyURI" maxOccurs="unbounded" minOccurs="0" />
159 1 Moritz Horsch
  </sequence>
160
</complexType>
161
162
<element name="Status">
163
  <complexType>
164
    <complexContent>
165
      <extension base="oec:StatusType">
166 17 Tobias Wich
        <sequence />
167 1 Moritz Horsch
      </extension>
168
    </complexContent>
169
  </complexType>
170
</element>
171
</code></pre>
172 17 Tobias Wich
173
The contents of the Status element are defined as follows:
174
* ConnectionHandle
175
  List of ConnectionHandles reflecting the currently available terminals, cards and their types.
176
* UserAgent
177
  Description of the user agent (client). 
178
** Name must be set to "Open eCard App" for all client types of the Open eCard App.
179
** VersionMajor, VersionMinor and VersionSubminor correspond to the major, minor and patch fields in the Version class.
180
   (see source:common/src/main/java/org/openecard/client/common/Version.java)
181
* SupportedAPIVersions
182 1 Moritz Horsch
  This element names and describes all supported API versions. At the moment, this is solely the eCard-API.
183
** Name and the version elements are one of
184 17 Tobias Wich
*** @http://www.bsi.bund.de/ecard/api@, 1, 1, @not set@
185 22 Tobias Wich
* SupportedCards
186
  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.
187 17 Tobias Wich
* SupportedDIDProtocols
188
  List of supported DID protocols. That means the list of SAL modules' DID protocol URIs registered in the client.
189
* AdditionalFeatures
190
  Not yet defined, but could be further stuff like a Signature plugin etc.
191 8 Tobias Wich
192
*Content-Types*
193
| text/xml  | The Status element. |
194 15 Tobias Wich
| text/html | Message in case of an error. |
195 8 Tobias Wich
196
197
*Description*
198
The interface can be used to request information about the eID application and its current state.
199
200
h2. WaitForChange
201
202
*URL*
203
@http://127.0.0.1:24727/waitForChange@
204
205
*Method*
206 1 Moritz Horsch
GET
207 8 Tobias Wich
208
*Query*
209 10 Tobias Wich
| session | The session of a previously set up event queue (see [[Client_Activation#GetStatus1|GetStatus]]). | Mandatory | 
210 8 Tobias Wich
211
*Returns*
212
| 200 OK                    | StatusChange element (see below). |
213 14 Tobias Wich
| 400 Bad Request           | Malformed GET request, e.g. session parameter is too weak. |
214 8 Tobias Wich
| 500 Internal Server Error | Errors in the smartcard stack or the webserver. |
215
216 19 Tobias Wich
<pre><code class="xml">
217
<complexType name="StatusChangeType" xmlns:oec="http://ws.openecard.org/schema" targetNamespace="http://ws.openecard.org/schema">
218
  <sequence>
219
    <element name="ConnectionHandle" type="iso:ConnectionHandleType" maxOccurs="1" minOccurs="1" />
220
    <element name="Action"           type="anyURI"                   maxOccurs="1" minOccurs="1" />
221
  </sequence>
222
</complexType>
223
224
<element name="StatusChange">
225
  <complexType>
226
    <complexContent>
227
      <extension base="oec:StatusChangeType">
228
        <sequence />
229
      </extension>
230
    </complexContent>
231
  </complexType>
232
</element>
233
</code></pre>
234
235
The contents of the StatusChange element are defined as follows:
236
237
* ConnectionHandle
238
  The meaning of the ConnectionHandle parameter is exactly as in the StartPAOS call defined in [BSI-TR-03112-7, Section 2.6].
239
* Action
240
  This element contains the URI describing the event. Currently there are the following event types defined:
241
** http://openecard.org/event/terminal_added
242
** http://openecard.org/event/terminal_removed
243
** http://openecard.org/event/card_inserted
244
** http://openecard.org/event/card_removed
245
** http://openecard.org/event/card_recognized
246
247 8 Tobias Wich
248
*Content-Types*
249
| text/xml  | The StatusChange element. |
250 15 Tobias Wich
| text/html | Message in case of an error. |
251 8 Tobias Wich
252
253
*Description*
254
The interface can be used to request status change information after an initial GetStatus call.
255
256
257
---
258
259
fn1. Openecard proposal: This parameter/interface is an Open eCard specific extension. It is not part of the official eCard specification.