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