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