doc/maintanance_web_services

   1 Maintanance 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.6 (2009-11-18)
   7 Source: Webové služby související s přístupem do ISDS, version 1.0
   8     (2010-01-18)
   9
  10
  11 These services are intended for administration of box as such. NONE of the
  12 services MARK incoming messages as delivered.
  13
  14 SOAP web services defined in: db_manipulations.wsdl (Appendix 3),
  15 db_access.wsdl (Appendix 2)
  16
  17 Data types: dbTypes.xsd (Appendix 3)
  18
  19 Documentation: DataBox_ws.pdf (Appendix 3), GetInfo_ws.pdf (Appendix 2)
  20
  21 Note: OVM mode is defined in paragraph 5a of Czech ISDS Act (300/2008 Coll.)
  22
  23 Non-normative: [dbTypes.xsd] augments XSD:gDbReqStatus type with optional
  24 dbStatusRefNumber element carying request serial number assigned by ISDS.
  25
  26 List of SOAP requests follows.
  27
  28
  29 db_manipulations.wsdl
  30 =====================
  31
  32 URL postfix: DsManage
  33
  34 CreateDataBox
  35     Create box
  36 CreateDataBoxPFOInfo
  37     Report PFO/FO insert into registry
  38 DeleteDataBox
  39     Remove box permanently
  40 UpdateDataBoxDescr
  41     Change data about box owner
  42 AddDataBoxUser
  43     Add person permitted to access to the box
  44 DeleteDataBoxUser
  45     Remove person permitted to access to the box
  46 UpdateDataBoxUser
  47     Change data about permitted person
  48 NewAccessData
  49     Reset user credentials (remove old ones and generates new ones)
  50 DisableDataBoxExternally
  51     Make box unaccessible because owner lost ability to use the box for legal
  52     reasons (prisoned person, person with no or weak legal rights)
  53 DisableOwnDataBox
  54     Make box unaccessable on request of its owner
  55 EnableOwnDataBox
  56     Renew access to the box
  57 SetEffectiveOVM
  58     Switch box into OVM mode
  59 CleareEffectiveOVM
  60     Set box off OVM mode
  61 SetOpenAddressing
  62     Switch box into commercial message receiving mode
  63 ClearOpenAddressing
  64     Set box off commercial message receiving mode
  65 GetDataBoxUsers
  66     Get list of users permitted to access a box.
  67
  68
  69 db_access.wsdl
  70 ==============
  71
  72 URL postfix: DsManage
  73
  74 GetOwnerInfoFromLogin
  75     Get data about box of logged in user.
  76 GetUserInfoFromLogin
  77     Get data about logged in user
  78 GetPasswordInfo
  79     Get data about password expiration
  80 ChangeISDSPassword
  81     Change password
  82
  83
  84 CreateDataBox
  85 =============
  86
  87 Create box of any type with complete set of PRIMARY users (i.e. box owners).
  88 Additional users can be assigned by AddDataBoxUser.
  89
  90 Freshly created box has state 3, after first login (or first login time out),
  91 box changes moves to standard state 1.
  92
  93 Credentials will be sent to each PRIMARY user by paper mail. Credentials
  94 postal address is supplied contact address or address obtained from external
  95 government registers (supplied person or firm address must match them).
  96
  97 Different box types can created by users with specific priviledges.
  98
  99 Input structure is:
 100 CreateDataBox
 101     + dbOwnerInfo – describe box and its owner, if only one owner exists (e.g.
 102     |   FO box type)
 103     + dbPrimaryUsers – list of primary users (box type FO has empty list,
 104     |   |   PFO has only one which carries contact address only,
 105     |   |   OVM has only one which describes office manager,
 106     |   |   PO has one or more, even other PO user type is applicable
 107     |   + dbUserInfo – primary user description (not all fields has meaning)
 108     |   + dbUserInfo
 109     |   ⋮
 110     + dbFormerNames – optional, undocumented
 111     + dbUpperDBId – ID of supper box, optional
 112     + dbCEOLabel – title of OVM manager (required for OVM box, optional
 113     |       otherise)
 114     + dbApproved – optional
 115     + dbExternRefNumber – optional
 116
 117 Returns ID of new box.
 118
 119
 120 CreateDataBoxPFOInfo
 121 ====================
 122
 123 Report PFO insert into external registry.
 124
 125 This service is only for sake of legislation. ISDS does use provided data
 126 anyhow.
 127
 128 It does not create a box nor return new box ID. See CreateDataBox for more
 129 details.
 130
 131
 132 DeleteDataBox
 133 =============
 134
 135 Remove box permanently.
 136
 137 If request succeeds, box will moves to state 4, and three years after that to
 138 state 5.
 139
 140 Input is box description and ISO date of owner cancelation
 141 (dbOwnerTerminationDate element).
 142
 143
 144 UpdateDataBoxDescr
 145 ==================
 146
 147 Change data about box or its owner.
 148
 149 Input is current box description and new description. Different fields can
 150 (not) be changed by different box types and differenlty privileged user.
 151
 152
 153 AddDataBoxUser
 154 ==============
 155
 156 Add person permitted to access to the box
 157
 158 Different user types can be added only by users with specific priviledges
 159 (PRIMARY_USER can be added only by PRIVIL_CZP user).
 160
 161 Input is box description and new user definition.
 162
 163
 164 DeleteDataBoxUser
 165 =================
 166
 167 Remove person permitted to access to the box.
 168
 169 Different user types can be removed only by users with specific priviledges
 170 (PRIMARY_USER can be removed only by PRIVIL_CZP user).
 171
 172 Input is box description and user description.
 173
 174
 175 UpdateDataBoxUser
 176 =================
 177
 178 Change data about user assigned to given box.
 179
 180 Input is box description (box ID or other criteria), old user data and new
 181 user data.
 182
 183 Non-normative: old user data are used not only to identify user in ISDS, they
 184 are used by ISDS to recognise data changes. Permission to change data are
 185 tested against these differences. In other words, client must supply complete
 186 old user data, not only user ID.
 187
 188 One can change any data (even user permissions) except user type of PRIMARY
 189 user. However PRIMARY user assigned to PO or OVM box can be removed
 190 (DeleteDataBoxUser) and reacreated (AddDataBoxUser).
 191
 192
 193 NewAccessData
 194 =============
 195
 196 Reset user credentials (remove old ones and generates new ones). This service
 197 is designed to user who forgot his credentials. He must apply for the reset
 198 off-line on dedicated meeting point.
 199
 200 Input is box description, user description, billing flag and optional switch
 201 how to deliver new credentials.
 202
 203 If switch is true, output element dbAccessDataId will contain token that user
 204 will use to authorize web page revealing new credentials. If switch is false,
 205 new credentials will be send by paper mail to user.
 206
 207 Non-normative: The special web page revealing new credentials is
 208 <https://www.czechpoint.cz/aktivacniportal/>. The form requires e-mail address
 209 to match e-mail address provided on meeting point.
 210
 211
 212 DisableDataBoxExternally
 213 ========================
 214
 215 Make box unaccessible because owner lost ability to use the box for legal
 216 reasons (prisoned person, person with no or weak legal rights).
 217
 218 Input is box description and date when the ability to access box has became
 219 impossible. This can be retroactive.
 220
 221 After success, box changes state to state 2.
 222
 223 Non-normative error codes:
 224     1004    Operation not permitted
 225
 226
 227 DisableOwnDataBox
 228 =================
 229
 230 Make box unaccessable on request of its owner.
 231
 232 Despite name, this does not disable access to the box of currently logged in
 233 user. The box owner must apply for making his box unaccassible off-line on
 234 special off-line meeting point and officer (with permission PRIVIL_OVMPOZAK
 235 | PRIVIL_CZP) call this SOAP service. Result is box state changed to value 2.
 236
 237 Input is box description (box ID ot other criteria).
 238
 239
 240 EnableOwnDataBox
 241 ================
 242
 243 Renew access to box made unaccessible previously.
 244
 245 Disable/enable access period is limited by law and can be charged. See
 246 DisableOwnDataBox for more detail.s
 247
 248
 249 SetEffectiveOVM
 250 ===============
 251
 252 Switch box into mode where the box can on explicit request sent messages as
 253 OVM boxes can. This is suitable for private organisations or persons that
 254 have government delegations.
 255
 256 Input is box ID.
 257
 258
 259 CleareEffectiveOVM
 260 ==================
 261
 262 Remove box priviledge to act as a government or municpality (OVM role).
 263
 264 Input is box ID.
 265
 266
 267 SetOpenAddressing
 268 =================
 269
 270 Switch box into commercial message receiving mode.
 271
 272 Box will be capable to receive commercial messages. This does not imply
 273 permission to send commercial messages.
 274
 275 Input is box ID.
 276
 277
 278 ClearOpenAddressing
 279 ===================
 280
 281 Switch box out of commercial message receiving mode.
 282
 283 Input is box ID.
 284
 285
 286 GetDataBoxUsers
 287 ===============
 288
 289 Get list of users permitted to access given box.
 290
 291 Note: This request is not specified in any verbose document. Following info
 292 has been obtained from XML Schma file [dbTypes.xsd].
 293
 294 Input is type of XSD:tIdDbInput. Only box ID is sufficient probably.
 295
 296 Output is list of box users. Structure:
 297
 298 EnableOwnDataBoxResponse
 299     + dbUsers – optional
 300     |   + dbUserInfo – at least one must present. Type of XSD:tDbUserInfo. See
 301         |           GetUserInfoFromLogin request for more details.
 302     |   + dbUserInfo
 303     |   ⋮
 304     + dbStatus
 305
 306
 307 GetOwnerInfoFromLogin
 308 =====================
 309
 310 Get details about current box that user is logged in.
 311
 312 Input is empty dummy request.
 313
 314 Result is returned in tDbOwnerInfo structure. Some structrure memebers are
 315 undefined or unknown for particular box type.
 316
 317
 318 GetUserInfoFromLogin
 319 ====================
 320
 321 Get details about currently logged in user.
 322
 323 Input is empty dummy request.
 324
 325 Output is returned in tDbUserInfo. Some members can be irrelevant (and thus
 326 undefined) for particular user. Service can fail if user has logged into box
 327 with system certificate.
 328
 329
 330 GetPasswordInfo
 331 ===============
 332
 333 Inquire expiration time of current user password.
 334
 335 By default password expires in 90 days. ISDS can force password change sooner.
 336
 337 Non-normative: If user does not change password after expiration, SOAP server
 338 will return non-SOAP response and client could not continue in work.
 339
 340 Input is empty dummy request.
 341
 342 Output is ISO time of password expiration. Service has no sense if client
 343 authenticates with certifacate only.
 344
 345
 346 ChangeISDSPassword
 347 ==================
 348
 349 Change user password.
 350
 351 Input is current password and new password. Supplied new password must match
 352 password stored in ISDS, otherwise system refuse password update.
 353
 354 Password must meet formal syntax rules assuring strong complexity:
 355
 356     – 8 ≤ length ≤ 32 characters
 357
 358     – Must contains:
 359
 360         * at least 1 upper case letter
 361
 362         * at least 1 lower case letter
 363
 364         * at least 1 digit
 365
 366     – Allowed alphabet is [a-z], [A-Z], [0-9], and "!#$%&()*+,-.:=?@[]_{}|~"
 367     (delimited with double quotations).
 368
 369     – Must differ from last 255 passwords
 370
 371     – Must not equal to user ID, user's last name and phone number
 372
 373 Service is meaningful only when user logs in with password.
 374
 375 After successfull password update, client continue in current sessesion.
 376 Password change takes effect after propagation into whole ISDS cluster (about
 377 15 seconds).
 378
 379 Error codes:
 380     0000    Password chaned successfully
 381     1066    Empty password
 382     1067    New password same as current one
 383     9204    Generic error