Project

General

Profile

Control Interface » History » Version 20

Tobias Wich, 10/12/2012 06:08 AM
Add error code when TCToken couldn't be fetched

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