1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
|
Log in specification
=====================
Source: Provozní řád ISDS, version 2011-02-05, Pages 11–13, 17
Source: Vyhláška o stanovení podrobností užívání a provozování ISDS (194/2009
Coll.)
Source: Webové služby ISDS pro manipulaci s datovými zprávami,
version 2 (2009-06-25)
Source: Podpora OTP autentizace v ISDS, version 1.5 (2011-10-14)
Source: Přihlášení bezpečným kódem,
<https://www.mojedatovaschranka.cz/static/pages/prihlasovani_bezp_kod.html>
(2012-01-03)
There are two authentication methods. One is stateless HTTP Basic method
(assured by X.509 client certificate in some cases). The other one is
state-full HTTP non-standard hotp or totpsendsms/totp method.
Stateless HTTP Basic Method
===========================
HTTP client must attach authentication data to each request by Basic method.
Allowed log in methods:
– HTTPS connection, server authenticated using SSL server certificate,
user authenticated using HTTP 1.1 basic authentication with user name and
password.
– SSL connection, user authenticated using `commercial' client
certificate AND user name and password. The client certificate must be
preregistered in web (browser) interface.
– SSL connection, user authenticated using `system' client certificate.
Client certificate must be preregistered to the box.
– SSL connection, user authenticated using `system' client certificate of
third party AND using HTTP 1.1 basic authentication (user name is box ID,
password is empty). This case is intended for hosted software as service
solutions.
Note: Certificate attributes `commercial' and `system' are defined in Czech
Electronic Signature Act.
Once client certificate is registered, user cannot log in with HTTP basic
authentication only.
Client private key must be stored in cryptographic device in non-exportable way.
The device driver must provide any of the APIs in addition:
– Microsoft CryptoAPI
– PKCS#11 API through libp11 library.
Desktop applications accessing ISDS must log in only on manual request of
a user. Daemon implementations can log in automatically, but they are forbidden
to abuse ISDS (e.g. redownloading old messages).
HTTP OTP Methods
================
SOAP services are relocated to
<https://DOMAINNAME/apps/DS/WEB_SERVICE_ENDPOINT> URL.
Server HTTP header `X-Response-message-text' value is encoded according to RFC
2047, method B (Base64) in UTF-8.
Authentication process is sequence of challenge-response HTTP messages that
differ for HMAC-Based One-Time Password (HOTP) and Time-based One-Time Password
(TOTP) methods. They are described bellow.
After successful OTP authentication, client obtains a cookie named
IPCZ-X-COOKIE that must be sent with each subsequent HTTP request. The cookie
is valid for 30 minutes of inactivity.
Client is supposed to ask server to invalidate the cookie before closing
session by sending GET request to
<https://DOMAINNAME/as/processLogout?uri=https://DOMAINNAME/apps/DS/WEB_SERVICE_ENDPOINT>.
The DOMAINNAME variable is one from server locators (e.g.
`www.mojedatovaschranka.cz'). WEB_SERVICE_ENDPOINT is request-URI postfix
specific for family of requested SOAP service (e.g `dz').
Specification requires client to send first POST request without
WWW-Authenticate header and to receive 401 response and to resend the request
with the authentication header delivering credentials again.
HTTP HOTP Method
================
Client sends a POST request to
<https://DOMAINNAME/as/processLogin?type=hotp&uri=https://DOMAINNAME/apps/DS/WEB_SERVICE_ENDPOINT>
with credentials in HTTP Basic header. The credentials are user name, password
and OTP code in form USERNAME ":" PASSWORD OTP_CODE. All four fields are
concatenated and encoded into Base64 as in standard HTTP Basic method. So the
only difference is the password is augmented with OTP code.
If authentication does not succeed, server will return 401 response
with headers like these:
WWW-Authenticate: hotp
X-Response-message-code: authentication.error.userIsNotAuthenticated
X-Response-message-text: =?UTF-
8?B?Q2h5YmEgcMWZaWhsw6HFoWVuw60sIHpub3Z1IHphZGVqdGUgw7pkYWplLg==?=
The X-Response-message-code header carries machine readable code,
X-Response-message-text is user readable text and they have following
meaning:
X-Response-message-Code Meaning
-----------------------------------------------------------------------------
authentication.error.userIsNotAuthenticated Bad log-in, retry
authentication.error.intruderDetected Access blocked for 60 minutes
authentication.error.paswordExpired Password has expired
authentication.error.badRole User name is not permitted to
access requested URI
If authentication succeeds, server will return 302 response:
Set-Cookie:IPCZ-X-COOKIE=01-5c1047cb9f3545f68cf987e6750acac4;
Domain=.mojedatovaschranka.cz; secure, HttpOnly
Location: https://DOMAINNAME/apps/DS/WEB_SERVICE_ENDPOINT
With cookie used to track session and redirects to new URL where client should
resubmit its original POST request.
Non-normative: The HMAC-based code is computed as specified in RFC 4226 (HOTP:
An HMAC-Based One-Time Password Algorithm).
HTTP TOTP Method
================
Client sends POST request to
<https://DOMAINNAME/as/processLogin?type=totp&sendSms=true&uri=https://DOMAINNAME/apps/DS/WEB_SERVICE_ENDPOINT>
with user name and password in standard HTTP Basic authentication header.
If credentials are valid, ISDS generates one-time code and sends it through
SMS GSM gateway to user's predefined phone number (the phone number can be set
on interactive web portal) and returns 302 response with redirect:
302 Found
X-Response-message-code: authentication.info.totpSended
X-Response-message-text: =?UTF-8?B?SmVkbm9yw6F6b3bDvSBrw7NkIG9kZXNsw6FuLg==?=
Location: https://DOMAINNAME/as/processLogin?type=totp&uri=https://DOMAINNAME/apps/DS/WEB_SERVICE_ENDPOINT
Otherwise 401 response is returned:
WWW-Authenticate: totpsendsms
X-Response-message-code: authentication.error.userIsNotAuthenticated
X-Response-message-text: =?UTF-8?B?Q2h5YmEgcMWZaWhsw6HFoWVuw60sIHpub3Z1IHphZGVqdGUgw7pkYWplLg==?=
X-Response-message-code defines machine parsable reason and
X-Response-message-text human readable text:
X-Response-message-code Meaning
-------------------------------------------------------------------------------
authentication.info.totpSended OTP has been sent by ISDS
authentication.error.userIsNotAuthenticated Bad log-in, retry
authentication.error.intruderDetected Access blocked for 60 minutes
authentication.error.paswordExpired Password has expired
authentication.info.cannotSendQuickly OTP cannot be sent repeatedly
at this rate (minimal delay
depends on TOTP window setting)
authentication.error.badRole User name is not permitted to
access requested URI
authentication.info.totpNotSended OTP could not been sent. Retry
later.
If 302 response has been received, then once user receives SMS message with
the OTP code, client can continue by sending POST request with credentials
USERNAME ":" PASSWORD OTP_CODE concatenated into one string and Base64
encoded to new location
<https://DOMAINNAME/as/processLogin?type=totp&uri=https://DOMAINNAME/apps/DS/WEB_SERVICE_ENDPOINT>.
If authentication succeeds, another 302 response with setting IPCZ-X-COOKIE
cookie and redirecting to final SOAP service URL will be sent by server.
Client can resubmit its original SOAP request to the new URL together with
the cookie.
Otherwise 401 response with WWW-Authenticate: totp header and
X-Response-message-code header with one of values defined above in HOTP method
will be delivered to client.
Non-normative: The premium SMS costs CZK 3. The user can send `HELP' text to
get more details or `STOP LOGINDEV' text to disable sending more codes. The
destination SMS phone number is `90201' (available from Czech celular phone
networks only). If the user sends the stop-message or looses his receiver or
capability to receive premium messages, he will lose access to his data box
effectivly and the only remedy will be to ask for reseting credentials on
Czech POINT meeting place.
ISDS unavailability
===================
If server cannot serve clients, it returns SOAP Fault with HTTP code 503:
HTTP/1.1 503 Service Temporarily Unavailable
Content-Length: 645
Connection: close
Content-Type: text/xml; charset=utf-8
<?xml version='1.0' encoding='UTF-8'?>
<SOAP-ENV:Envelope
xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsi="http://www.w3.org/1999/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/1999/XMLSchema">
<SOAP-ENV:Body>
<SOAP-ENV:Fault>
<faultcode xsi:type="xsd:string">Probíhá plánovaná údržba</faultcode>
<faultstring xsi:type="xsd:string">Omlouváme se všem uživatelům datových
schránek za dočasné omezení přístupu do systému datových schránek z důvodu plánované
údržby systému. Děkujeme za pochopení.</faultstring>
</SOAP-ENV:Fault>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
|
