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     |   + 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 generate new ones). This service
 230 is designed to the user who forgot his credentials. He must apply for the
 231 credentials reset off-line on a dedicated meeting point.
 232
 233 Input is a 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 the switch is true, the e-mail address will be recorded in the ISDS and
 237 output element dbAccessDataId will contain a token that the user will use to
 238 authorize to a web page revealing his new credentials and output element
 239 dbUserID will contain new user log-in name.
 240
 241 If the switch is false, new credentials will be sent through paper mail to the
 242 user. The input e-mail address and the output token and new log-in name will
 243 not be returned.
 244
 245 This service was removed from specification on 2015-06-08.
 246
 247 Non-normative: The special web page revealing new credentials is
 248 <https://www.czechpoint.cz/aktivacniportal/>. The form requires an e-mail
 249 address matching the e-mail address provided on the meeting point.
 250
 251
 252 DisableDataBoxExternally
 253 ========================
 254
 255 Make box inaccessible because owner lost ability to use the box for legal
 256 reasons (prisoned person, person with no or weak legal rights).
 257
 258 Input is box description and date when the ability to access box has became
 259 impossible. This can be retroactive.
 260
 261 After success, box changes state to state 2.
 262
 263 Non-normative error codes:
 264     1004    Operation not permitted
 265
 266
 267 DisableOwnDataBox
 268 =================
 269
 270 Make box inaccessible on request of its owner.
 271
 272 Despite name, this does not disable access to the box of currently logged in
 273 user. The box owner must apply for making his box inaccessible off-line on
 274 special off-line meeting point and officer (with permission PRIVIL_OVMPOZAK
 275 | PRIVIL_CZP) call this SOAP service. Result is box state changed to value 2.
 276
 277 Input is box description (box ID or other criteria).
 278
 279
 280 EnableOwnDataBox
 281 ================
 282
 283 Renew access to box made inaccessible previously.
 284
 285 Disable/enable access period is limited by law and can be charged. See
 286 DisableOwnDataBox for more details.
 287
 288
 289 SetEffectiveOVM
 290 ===============
 291
 292 Switch box into mode where the box can on explicit request sent messages as
 293 OVM boxes can. This is suitable for private organisations or persons that
 294 have government delegations.
 295
 296 Input is box ID.
 297
 298
 299 CleareEffectiveOVM
 300 ==================
 301
 302 Remove box privilege to act as a government or municipality (OVM role).
 303
 304 Input is box ID.
 305
 306
 307 SetOpenAddressing
 308 =================
 309
 310 Switch box into commercial message receiving mode.
 311
 312 Box will be capable to receive commercial messages. This does not imply
 313 permission to send commercial messages.
 314
 315 Input is box ID.
 316
 317
 318 ClearOpenAddressing
 319 ===================
 320
 321 Switch box out of commercial message receiving mode.
 322
 323 Input is box ID.
 324
 325
 326 GetDataBoxUsers
 327 ===============
 328
 329 Get list of users permitted to access given box.
 330
 331 Note: This request is not specified in any verbose document. Following info
 332 has been obtained from XML Schema file [dbTypes.xsd].
 333
 334 Input is type of XSD:tIdDbInput. Only box ID is sufficient probably.
 335
 336 Output is list of box users. Structure:
 337
 338 GetDataBoxUsersResponse
 339     + dbUsers – optional
 340     |   + dbUserInfo – zero count is possible. Type of XSD:tDbUserInfo. See
 341         |           GetUserInfoFromLogin request for more details.
 342     |   + dbUserInfo
 343     |   ⋮
 344     + dbStatus
 345
 346
 347 Activate
 348 ========
 349
 350 This service is not documented. The only mention is in XML Schema.
 351
 352 There are two elements on input: dbAccessDataId (temporary token for user to
 353 get access to his initial credentials probably) and dbID (box identifier).
 354
 355 Output is sequence of userId (user identifier), password (non-empty string),
 356 and dbStatus (common service return code).
 357
 358
 359 DeleteDataBoxPromptly
 360 =====================
 361
 362 This service is not documentd. The only mention is in XML Schema and change
 363 log. Even the SOAP end-point dsManage is not specified.
 364
 365 There are following elements in input: dbOwnerInfo (identifies box by owner
 366 structure) and group of optional elements gExtApproval (sequence of dbApproved
 367 and dbExternRefNumber as used in other services).
 368
 369 Output is standard dbStatus subtree (error code and message of requested
 370 service).
 371
 372
 373 GetOwnerInfoFromLogin
 374 =====================
 375
 376 Get details about current box that user is logged in.
 377
 378 Input is empty dummy request.
 379
 380 Result is returned in tDbOwnerInfo structure. Some structure members are
 381 undefined or unknown for particular box type.
 382
 383
 384 GetUserInfoFromLogin
 385 ====================
 386
 387 Get details about currently logged in user.
 388
 389 Input is empty dummy request.
 390
 391 Output is returned in tDbUserInfo. Some members can be irrelevant (and thus
 392 undefined) for particular user. Service can fail if user has logged into box
 393 with system certificate.
 394
 395
 396 GetPasswordInfo
 397 ===============
 398
 399 Inquire expiration time of current user password.
 400
 401 By default password expires in 90 days. ISDS can force password change sooner.
 402
 403 Non-normative: If user does not change password after expiration, SOAP server
 404 will return non-SOAP response and client could not continue in work.
 405
 406 Input is empty dummy request.
 407
 408 Output is ISO time of password expiration in pswExpDate element. If password
 409 expiration is disabled, empty element is returned. Service has no sense if client
 410 authenticates with certificate only.
 411
 412
 413 ChangeISDSPassword
 414 ==================
 415
 416 Change user password.
 417
 418 Input is current password and new password. Supplied new password must match
 419 password stored in ISDS, otherwise system refuse password update.
 420
 421 Password must meet formal syntax rules assuring strong complexity:
 422
 423     – 8 ≤ length ≤ 32 characters
 424
 425     – Must contains:
 426
 427         * at least 1 upper case letter
 428
 429         * at least 1 lower case letter
 430
 431         * at least 1 digit
 432
 433     – Allowed alphabet is [a-z], [A-Z], [0-9], and "!#$%&()*+,-.:=?@[]_{}|~"
 434     (delimited with double quotations).
 435
 436     – Must differ from last 255 passwords
 437
 438     – Must not contain user ID
 439
 440     – Must not contain sequence of 3 or more same characters
 441
 442     – Must not start with `qwert', `asdgf', or `12345'
 443
 444 Service is meaningful only when user logs in with password but without
 445 additional one-time password authentication. In case OTP method, use
 446 `ChangePasswordOTP' SOAP service instead.
 447
 448 After successful password update, client can continue in current session.
 449 Password change takes effect after propagation into whole ISDS cluster (about
 450 15 seconds).
 451
 452 Error codes:
 453     0000    Password changed successfully
 454     1066    Too short or too long
 455     1067    New password same as current one
 456     1079    Password contains forbidden character
 457     1080    Does not contain lower cased letter, upper cased letter and a digit
 458     1081    Sequence of repeated character
 459     1082    Contains user ID
 460     1083    Too simple
 461     1090    Bad current password
 462     1091    Password matches one of older passwords
 463     9204    LDAP update error
 464
 465
 466 ChangePasswordOTP
 467 =================
 468
 469 Change user password if OTP authentication is enabled and required by server.
 470
 471 This service is meaningfull only with OTP authentication. Use
 472 `ChangeISDSPassword' instead, if authentication with static password is in
 473 use.
 474
 475 This service resides on different URL path, not only on different path suffix.
 476 This service uses different name space <http://isds.czechpoint.cz/v20/asws>.
 477
 478 Input is current password in `dbOldPassword' element, new password in
 479 `dbNewPassword' element, and OTP method in `dbOTPType' element (known values
 480 are: `HOTP', `TOTP'). The selected OTP method must match log-in OTP method.
 481
 482 This service is available without prior statefull log-in. This SOAP request
 483 must be accompanied with HTTP Basic authentication header delivering user
 484 name and current password concatenated with an OTP code.
 485
 486 In case of time-based authentication, client can request delivering new OTP
 487 code through side channel by `SendSMSCode' service prior issuing this request.
 488
 489 Details of user authentication are described in `login' document, `HTTP OTP
 490 Methods' section.
 491
 492 Restrictions to new password and response format are the same as in
 493 `ChangeISDSPassword' service.
 494
 495 Output has schema of `dbStatus' element.
 496
 497 Error codes:
 498     1066    Too short or too long
 499     1067    Password matches one of older passwords
 500     1082    Contains user ID
 501     1083    Too simple
 502     2300    Unexpected error
 503
 504 Non-normative: Be ware ChangeISDSPassword case with code 1091 is reported by
 505 ChangePasswordOTP as code 1067.
 506
 507
 508 SendSMSCode
 509 ===========
 510
 511 Ask server to send new OTP code through SMS gateway. Delivered code is
 512 intended as input to HTTP Basic authorization header for `ChangePasswordOTP'
 513 service.
 514
 515 This service resides on different URL path, not only on different path suffix.
 516 This service uses different name space <http://isds.czechpoint.cz/v20/asws>.
 517
 518 This service is available without prior statefull log-in. This SOAP request
 519 must be accompanied with HTTP Basic authentication header delivering user
 520 name and current password.
 521
 522 Output has schema of `dbStatus' element.
 523
 524 Error codes:
 525     0000    Success
 526     2300    Unexpected error
 527     2301    One-time code cannot be re-send faster than once a 30 seconds
 528     2302    One-time code could not been sent. Try later again.