doc/maintanance_web_services

   1 Maintenance web services specification
   2 ======================================
   3
   4 Source: Provozní řád ISDS, version 2010-01-22, Pages 14–15
   5 Source: Webové služby rozhraní ISDS pro správu datových schránek,
   6     version 2.15 (2010-11-19)
   7 Source: Webové služby související s přístupem do ISDS, version 1.9
   8     (2011-09-11)
   9 Source: dbTypes.xsd, version 2.11 (2010-11-23)
  10
  11
  12 These services are intended for administration of box as such. NONE of the
  13 services MARK incoming messages as delivered.
  14
  15 SOAP web services defined in: db_manipulations.wsdl (Appendix 3),
  16 db_access.wsdl (Appendix 2)
  17
  18 Data types: dbTypes.xsd (Appendix 3)
  19
  20 Documentation: DataBox_ws.pdf (Appendix 3), GetInfo_ws.pdf (Appendix 2)
  21
  22 Note: OVM mode is defined in paragraph 5a of Czech ISDS Act (300/2008 Coll.)
  23
  24 Non-normative: [dbTypes.xsd] augments XSD:gDbReqStatus type with optional
  25 dbStatusRefNumber element carrying request serial number assigned by ISDS.
  26
  27 List of SOAP requests follows.
  28
  29
  30 db_manipulations.wsdl
  31 =====================
  32
  33 URL postfix: DsManage
  34
  35 CreateDataBox
  36     Create box
  37 CreateDataBoxPFOInfo
  38     Report PFO/FO insert into registry
  39 DeleteDataBox
  40     Remove box permanently
  41 UpdateDataBoxDescr
  42     Change data about box owner
  43 AddDataBoxUser
  44     Add person permitted to access to the box
  45 DeleteDataBoxUser
  46     Remove person permitted to access to the box
  47 UpdateDataBoxUser
  48     Change data about permitted person
  49 NewAccessData
  50     Reset user credentials (remove old ones and generates new ones)
  51 DisableDataBoxExternally
  52     Make box inaccessible because owner lost ability to use the box for legal
  53     reasons (prisoned person, person with no or weak legal rights)
  54 DisableOwnDataBox
  55     Make box inaccessible on request of its owner
  56 EnableOwnDataBox
  57     Renew access to the box
  58 SetEffectiveOVM
  59     Switch box into OVM mode
  60 CleareEffectiveOVM
  61     Set box off OVM mode
  62 SetOpenAddressing
  63     Switch box into commercial message receiving mode
  64 ClearOpenAddressing
  65     Set box off commercial message receiving mode
  66 GetDataBoxUsers
  67     Get list of users permitted to access a box
  68 Activate
  69     Not documented
  70 DeleteDataBoxPromptly
  71     Not documented
  72
  73
  74 db_access.wsdl
  75 ==============
  76
  77 URL postfix: DsManage
  78
  79 GetOwnerInfoFromLogin
  80     Get data about box of logged in user.
  81 GetUserInfoFromLogin
  82     Get data about logged in user
  83 GetPasswordInfo
  84     Get data about password expiration
  85 ChangeISDSPassword
  86     Change password
  87
  88
  89 ChangePassword.wsdl
  90 ===================
  91
  92 URL path: /asws/changePassword
  93
  94 ChangePasswordOTP
  95     Change password if one-time password authentication is in use
  96 SendSMSCode
  97     Request delivering time-based OTP code through side channel
  98
  99
 100 CreateDataBox
 101 =============
 102
 103 Create box of any type with complete set of PRIMARY users (i.e. box owners).
 104 Additional users can be assigned by AddDataBoxUser.
 105
 106 Freshly created box has state 3, after first log-in (or first log-in time out),
 107 box changes moves to standard state 1.
 108
 109 Credentials will be sent to each PRIMARY user by paper mail. Credentials
 110 postal address is supplied contact address or address obtained from external
 111 government registers (supplied person or firm address must match them).
 112
 113 If optional dbVirtual element is true, optional input element email is
 114 required and ISDS will return one-time password that box owner will use to
 115 obtain his credentials. See NewAccessData for more details.
 116
 117 Different box types can created by users with specific privileges.
 118
 119 Input structure is:
 120 CreateDataBox
 121     + dbOwnerInfo – describe box and its owner, if only one owner exists (e.g.
 122     |   FO box type)
 123     + dbPrimaryUsers – list of primary users (box type FO has empty list,
 124     |   |   PFO has only one which carries contact address only,
 125     |   |   OVM has only one which describes office manager,
 126     |   |   PO has one or more, even other PO user type is applicable
 127     |   + dbUserInfo – primary user description (not all fields has meaning)
 128     |   + dbUserInfo
 129     |   ⋮
 130     + dbFormerNames – former name of the user, optional
 131     + dbUpperDBId – ID of supper box, optional
 132     + dbCEOLabel – title of OVM manager (required for OVM box, optional
 133     |       otherise)
 134     + dbVirtual – true if user want to get initial credentials on
 135     |       activation portal. Optional
 136     + email – address to send notification about new credentials, optional,
 137     |       required and meaningful only if dbVirtual is true
 138     + dbApproved – optional
 139     + dbExternRefNumber – optional
 140
 141 Returns ID of new box and token for activation portal if requested by
 142 dbVirtual.
 143
 144
 145 CreateDataBoxPFOInfo
 146 ====================
 147
 148 Report PFO insert into external registry.
 149
 150 This service is only for sake of legislation. ISDS does use provided data
 151 anyhow.
 152
 153 It does not create a box nor return new box ID. See CreateDataBox for more
 154 details.
 155
 156
 157 DeleteDataBox
 158 =============
 159
 160 Remove box permanently.
 161
 162 If request succeeds, box will moves to state 4, and three years after that to
 163 state 5.
 164
 165 Input is box description and ISO date of owner cancellation
 166 (dbOwnerTerminationDate element).
 167
 168
 169 UpdateDataBoxDescr
 170 ==================
 171
 172 Change data about box or its owner.
 173
 174 Input is current box description and new description. Different fields can
 175 (not) be changed by different box types and differently privileged user.
 176
 177
 178 AddDataBoxUser
 179 ==============
 180
 181 Add person permitted to access to the box
 182
 183 Different user types can be added only by users with specific privileges
 184 (PRIMARY_USER can be added only by PRIVIL_CZP user).
 185
 186 Mandatory input is box description and new user definition.
 187
 188 If optional input dbVirtual is true, additional input element email specifies
 189 e-mail address to send notificication about new account and link where to get
 190 find initial credentials for created user. Then two output elements are
 191 returned: dbUserID (XSD mistakenly says dbID) and dbAccessDataId for new
 192 user identifier and temporal token to login on the web page linked from
 193 received e-mail. See NewAccessData for more details.
 194
 195
 196 DeleteDataBoxUser
 197 =================
 198
 199 Remove person permitted to access to the box.
 200
 201 Different user types can be removed only by users with specific privileges
 202 (PRIMARY_USER can be removed only by PRIVIL_CZP user).
 203
 204 Input is box description and user description.
 205
 206
 207 UpdateDataBoxUser
 208 =================
 209
 210 Change data about user assigned to given box.
 211
 212 Input is box description (box ID or other criteria), old user data and new
 213 user data.
 214
 215 Non-normative: old user data are used not only to identify user in ISDS, they
 216 are used by ISDS to recognise data changes. Permission to change data are
 217 tested against these differences. In other words, client must supply complete
 218 old user data, not only user ID.
 219
 220 One can change any data (even user permissions) except user type of PRIMARY
 221 user. However PRIMARY user assigned to PO or OVM box can be removed
 222 (DeleteDataBoxUser) and recreated (AddDataBoxUser).
 223
 224
 225 NewAccessData
 226 =============
 227
 228 Reset user credentials (remove old ones and generates new ones). This service
 229 is designed to user who forgot his credentials. He must apply for the reset
 230 off-line on dedicated meeting point.
 231
 232 Input is box description, user description, billing flag and optional switch
 233 how to deliver new credentials and optional user's e-mail address.
 234
 235 If switch is true, e-mail address will be recorded in the ISDS and output
 236 element dbAccessDataId will contain token that user will use to authorize to
 237 web page revealing new credentials and output element dbUserID will contain
 238 new user log-in name.
 239
 240 If switch is false, new credentials will be sent by paper mail to user. Input
 241 e-mail address and output token and new log-in name will not be returned.
 242
 243 Non-normative: The special web page revealing new credentials is
 244 <https://www.czechpoint.cz/aktivacniportal/>. The form requires e-mail address
 245 to match e-mail address provided on meeting point.
 246
 247
 248 DisableDataBoxExternally
 249 ========================
 250
 251 Make box inaccessible because owner lost ability to use the box for legal
 252 reasons (prisoned person, person with no or weak legal rights).
 253
 254 Input is box description and date when the ability to access box has became
 255 impossible. This can be retroactive.
 256
 257 After success, box changes state to state 2.
 258
 259 Non-normative error codes:
 260     1004    Operation not permitted
 261
 262
 263 DisableOwnDataBox
 264 =================
 265
 266 Make box inaccessible on request of its owner.
 267
 268 Despite name, this does not disable access to the box of currently logged in
 269 user. The box owner must apply for making his box inaccessible off-line on
 270 special off-line meeting point and officer (with permission PRIVIL_OVMPOZAK
 271 | PRIVIL_CZP) call this SOAP service. Result is box state changed to value 2.
 272
 273 Input is box description (box ID or other criteria).
 274
 275
 276 EnableOwnDataBox
 277 ================
 278
 279 Renew access to box made inaccessible previously.
 280
 281 Disable/enable access period is limited by law and can be charged. See
 282 DisableOwnDataBox for more details.
 283
 284
 285 SetEffectiveOVM
 286 ===============
 287
 288 Switch box into mode where the box can on explicit request sent messages as
 289 OVM boxes can. This is suitable for private organisations or persons that
 290 have government delegations.
 291
 292 Input is box ID.
 293
 294
 295 CleareEffectiveOVM
 296 ==================
 297
 298 Remove box privilege to act as a government or municipality (OVM role).
 299
 300 Input is box ID.
 301
 302
 303 SetOpenAddressing
 304 =================
 305
 306 Switch box into commercial message receiving mode.
 307
 308 Box will be capable to receive commercial messages. This does not imply
 309 permission to send commercial messages.
 310
 311 Input is box ID.
 312
 313
 314 ClearOpenAddressing
 315 ===================
 316
 317 Switch box out of commercial message receiving mode.
 318
 319 Input is box ID.
 320
 321
 322 GetDataBoxUsers
 323 ===============
 324
 325 Get list of users permitted to access given box.
 326
 327 Note: This request is not specified in any verbose document. Following info
 328 has been obtained from XML Schema file [dbTypes.xsd].
 329
 330 Input is type of XSD:tIdDbInput. Only box ID is sufficient probably.
 331
 332 Output is list of box users. Structure:
 333
 334 GetDataBoxUsersResponse
 335     + dbUsers – optional
 336     |   + dbUserInfo – zero count is possible. Type of XSD:tDbUserInfo. See
 337         |           GetUserInfoFromLogin request for more details.
 338     |   + dbUserInfo
 339     |   ⋮
 340     + dbStatus
 341
 342
 343 Activate
 344 ========
 345
 346 This service is not documented. The only mention is in XML Schema.
 347
 348 There are two elements on input: dbAccessDataId (temporary token for user to
 349 get access to his initial credentials probably) and dbID (box identifier).
 350
 351 Output is sequence of userId (user identifier), password (non-empty string),
 352 and dbStatus (common service return code).
 353
 354
 355 DeleteDataBoxPromptly
 356 =====================
 357
 358 This service is not documentd. The only mention is in XML Schema and change
 359 log. Even the SOAP end-point dsManage is not specified.
 360
 361 There are following elements in input: dbOwnerInfo (identifies box by owner
 362 structure) and group of optional elements gExtApproval (sequence of dbApproved
 363 and dbExternRefNumber as used in other services).
 364
 365 Output is standard dbStatus subtree (error code and message of requested
 366 service).
 367
 368
 369 GetOwnerInfoFromLogin
 370 =====================
 371
 372 Get details about current box that user is logged in.
 373
 374 Input is empty dummy request.
 375
 376 Result is returned in tDbOwnerInfo structure. Some structure members are
 377 undefined or unknown for particular box type.
 378
 379
 380 GetUserInfoFromLogin
 381 ====================
 382
 383 Get details about currently logged in user.
 384
 385 Input is empty dummy request.
 386
 387 Output is returned in tDbUserInfo. Some members can be irrelevant (and thus
 388 undefined) for particular user. Service can fail if user has logged into box
 389 with system certificate.
 390
 391
 392 GetPasswordInfo
 393 ===============
 394
 395 Inquire expiration time of current user password.
 396
 397 By default password expires in 90 days. ISDS can force password change sooner.
 398
 399 Non-normative: If user does not change password after expiration, SOAP server
 400 will return non-SOAP response and client could not continue in work.
 401
 402 Input is empty dummy request.
 403
 404 Output is ISO time of password expiration in pswExpDate element. If password
 405 expiration is disabled, empty element is returned. Service has no sense if client
 406 authenticates with certificate only.
 407
 408
 409 ChangeISDSPassword
 410 ==================
 411
 412 Change user password.
 413
 414 Input is current password and new password. Supplied new password must match
 415 password stored in ISDS, otherwise system refuse password update.
 416
 417 Password must meet formal syntax rules assuring strong complexity:
 418
 419     – 8 ≤ length ≤ 32 characters
 420
 421     – Must contains:
 422
 423         * at least 1 upper case letter
 424
 425         * at least 1 lower case letter
 426
 427         * at least 1 digit
 428
 429     – Allowed alphabet is [a-z], [A-Z], [0-9], and "!#$%&()*+,-.:=?@[]_{}|~"
 430     (delimited with double quotations).
 431
 432     – Must differ from last 255 passwords
 433
 434     – Must not contain user ID
 435
 436     – Must not contain sequence of 3 or more same characters
 437
 438     – Must not start with `qwert', `asdgf', or `12345'
 439
 440 Service is meaningful only when user logs in with password but without
 441 additional one-time password authentication. In case OTP method, use
 442 `ChangePasswordOTP' SOAP service instead.
 443
 444 After successful password update, client can continue in current session.
 445 Password change takes effect after propagation into whole ISDS cluster (about
 446 15 seconds).
 447
 448 Error codes:
 449     0000    Password changed successfully
 450     1066    Too short or too long
 451     1067    New password same as current one
 452     1079    Password contains forbidden character
 453     1080    Does not contain lower cased letter, upper cased letter and a digit
 454     1081    Sequence of repeated character
 455     1082    Contains user ID
 456     1083    Too simple
 457     1090    Bad current password
 458     1091    Password matches one of older passwords
 459     9204    LDAP update error
 460
 461
 462 ChangePasswordOTP
 463 =================
 464
 465 Change user password if OTP authentication is enabled and required by server.
 466
 467 This service is meaningfull only with OTP authentication. Use
 468 `ChangeISDSPassword' instead, if authentication with static password is in
 469 use.
 470
 471 This service resides on different URL path, not only on different path suffix.
 472
 473 Input is current password in `dbOldPassword' element, new password in
 474 `dbNewPassword' element, and OTP method in `dbOTPType' element (known values
 475 are: `HOTP', `TOTP'). The selected OTP method must match log-in OTP method.
 476
 477 This service is available without prior statefull log-in. This SOAP request
 478 must be accompanied with HTTP Basic authentication header delivering user
 479 name and current password concatenated with an OTP code.
 480
 481 In case of time-based authentication, client can request delivering new OTP
 482 code through side channel by `SendSMSCode' service prior issuing this request.
 483
 484 Details of user authentication are described in `login' document, `HTTP OTP
 485 Methods' section.
 486
 487 Restrictions to new password and response format are the same as in
 488 `ChangeISDSPassword' service.
 489
 490 Output has schema of `dbStatus' element.
 491
 492 There is new error code:
 493     2300    Unexpected error
 494
 495
 496 SendSMSCode
 497 ===========
 498
 499 Ask server to send new OTP code through SMS gateway. Delivered code is
 500 intended as input to HTTP Basic authorization header for `ChangePasswordOTP'
 501 service.
 502
 503 This service resides on different URL path, not only on different path suffix.
 504
 505 This service is available without prior statefull log-in. This SOAP request
 506 must be accompanied with HTTP Basic authentication header delivering user
 507 name and current password.
 508
 509 Output has schema of `dbStatus' element.
 510
 511 Error codes:
 512     0000    Success
 513     2300    Unexpected error
 514     2301    One-time code cannot be re-send faster than once a 30 seconds
 515     2302    One-time code could not been sent. Try later again.