doc/login

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