Project

General

Profile

Control Interface » History » Version 16

Tobias Wich, 10/11/2012 05:27 PM
Add Status Schema

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
26
*Content-Types*
27
| text/html | Webpage with user evaluatable content. E.g. error page, manual redirect, ... |
28
29
30
*Description*
31
The interface can be used to start the eID application.
32
33
The parameters ifdName, contextHandle, slotHandle and cardType address a particular eCard, or a type of card.
34
There are three meaningful combinations of the optional parameters:
35
* _none_
36
 Use the fist nPa available. Display a "Please insert nPa" dialog if needed. This is the behaviour of the AusweisApp.
37 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.
38 8 Tobias Wich
* _cardType_
39
 Use the fist card of the specified type which is available. Display a "Please insert <cardType>" dialog if needed.
40 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.
41 8 Tobias Wich
* _ifdName_, _contextHandle_, _slotHandle_
42
 Use exactly the card matching the parameters.
43 13 Tobias Wich
  cardType is requested from the selected card directly. If there is no such card, an error is produced.
44 8 Tobias Wich
45
46
*Notes*
47
48 1 Moritz Horsch
<pre>
49
TODO
50
* What happens if the Client Activator cannot start an application?
51
* What happens if the Client Activator cannot fetch a TC Token from the given TCTokenURL? Should that result in a 400 or 404?
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
<complexType name="StatusType">
123
  <sequence>
124
    <element name="ConnectionHandle" type="iso:ConnectionHandleType" maxOccurs="unbounded" minOccurs="0" />
125
    <element name="UserAgent"                                        maxOccurs="1"         minOccurs="0">
126
      <complexType>
127
	<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
      </complexType>
134
    </element>
135
    <element name="SupportedAPIVersions" maxOccurs="unbounded" minOccurs="0">
136
      <complexType>
137
	<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
      </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
  </sequence>
149
</complexType>
150
151
<element name="Status">
152
  <complexType>
153
    <complexContent>
154
      <extension base="oec:StatusType">
155
	<sequence />
156
      </extension>
157
    </complexContent>
158
  </complexType>
159
</element>
160
</code></pre>
161 8 Tobias Wich
162
*Content-Types*
163
| text/xml  | The Status element. |
164 15 Tobias Wich
| text/html | Message in case of an error. |
165 8 Tobias Wich
166
167
*Description*
168
The interface can be used to request information about the eID application and its current state.
169
170
h2. WaitForChange
171
172
*URL*
173
@http://127.0.0.1:24727/waitForChange@
174
175
*Method*
176 1 Moritz Horsch
GET
177 8 Tobias Wich
178
*Query*
179 10 Tobias Wich
| session | The session of a previously set up event queue (see [[Client_Activation#GetStatus1|GetStatus]]). | Mandatory | 
180 8 Tobias Wich
181
*Returns*
182
| 200 OK                    | StatusChange element (see below). |
183 14 Tobias Wich
| 400 Bad Request           | Malformed GET request, e.g. session parameter is too weak. |
184 8 Tobias Wich
| 500 Internal Server Error | Errors in the smartcard stack or the webserver. |
185
186
<pre>TODO: define StatusChange element</pre>
187
188
*Content-Types*
189
| text/xml  | The StatusChange element. |
190 15 Tobias Wich
| text/html | Message in case of an error. |
191 8 Tobias Wich
192
193
*Description*
194
The interface can be used to request status change information after an initial GetStatus call.
195
196
197
---
198
199
fn1. Openecard proposal: This parameter/interface is an Open eCard specific extension. It is not part of the official eCard specification.