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 add only 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
 208 DisableDataBoxExternally
 209 ========================
 210
 211 Make box unaccessible because owner lost ability to use the box for legal
 212 reasons (prisoned person, person with no or weak legal rights).
 213
 214 Input is box description and date when the ability to access box has became
 215 impossible. This can be retroactive.
 216
 217 After success, box changes state to state 2.
 218
 219 Non-normative error codes:
 220     1004    Operation not permitted
 221
 222
 223 DisableOwnDataBox
 224 =================
 225
 226 Make box unaccessable on request of its owner.
 227
 228 Despite name, this does not disable access to the box of currently logged in
 229 user. The box owner must apply for making his box unaccassible off-line on
 230 special off-line meeting point and officer (with permission PRIVIL_OVMPOZAK
 231 | PRIVIL_CZP) call this SOAP service. Result is box state changed to value 2.
 232
 233 Input is box description (box ID ot other criteria).
 234
 235
 236 EnableOwnDataBox
 237 ================
 238
 239 Renew access to box made unaccessible previously.
 240
 241 Disable/enable access period is limited by law and can be charged. See
 242 DisableOwnDataBox for more detail.s
 243
 244
 245 SetEffectiveOVM
 246 ===============
 247
 248 Switch box into mode where the box can on explicit request sent messages as
 249 OVM boxes can. This is suitable for private organisations or persons that
 250 have government delegations.
 251
 252 Input is box ID.
 253
 254
 255 CleareEffectiveOVM
 256 ==================
 257
 258 Remove box priviledge to act as a government or municpality (OVM role).
 259
 260 Input is box ID.
 261
 262
 263 SetOpenAddressing
 264 =================
 265
 266 Switch box into commercial message receiving mode.
 267
 268 Box will be capable to receive commercial messages. This does not imply
 269 permission to send commercial messages.
 270
 271 Input is box ID.
 272
 273
 274 ClearOpenAddressing
 275 ===================
 276
 277 Switch box out of commercial message receiving mode.
 278
 279 Input is box ID.
 280
 281
 282 GetDataBoxUsers
 283 ===============
 284
 285 Get list of users permitted to access given box.
 286
 287 Note: This request is not specified in any verbose document. Following info
 288 has been obtained from XML Schma file [dbTypes.xsd].
 289
 290 Input is type of XSD:tIdDbInput. Only box ID is sufficient probably.
 291
 292 Output is list of box users. Structure:
 293
 294 EnableOwnDataBoxResponse
 295     + dbUsers – optional
 296     |   + dbUserInfo – at least one must present. Type of XSD:tDbUserInfo. See
 297         |           GetUserInfoFromLogin request for more details.
 298     |   + dbUserInfo
 299     |   ⋮
 300     + dbStatus
 301
 302
 303 GetOwnerInfoFromLogin
 304 =====================
 305
 306 Get details about current box that user is logged in.
 307
 308 Input is empty dummy request.
 309
 310 Result is returned in tDbOwnerInfo structure. Some structrure memebers are
 311 undefined or unknown for particular box type.
 312
 313
 314 GetUserInfoFromLogin
 315 ====================
 316
 317 Get details about currently logged in user.
 318
 319 Input is empty dummy request.
 320
 321 Output is returned in tDbUserInfo. Some members can be irrelevant (and thus
 322 undefined) for particular user. Service can fail if user has logged into box
 323 with system certificate.
 324
 325
 326 GetPasswordInfo
 327 ===============
 328
 329 Inquire expiration time of current user password.
 330
 331 By default password expires in 90 days. ISDS can force password change sooner.
 332
 333 Non-normative: If user does not change password after expiration, SOAP server
 334 will return non-SOAP response and client could not continue in work.
 335
 336 Input is empty dummy request.
 337
 338 Output is ISO time of password expiration. Service has no sense if client
 339 authenticates with certifacate only.
 340
 341
 342 ChangeISDSPassword
 343 ==================
 344
 345 Change user password.
 346
 347 Input is current password and new password. Supplied new password must match
 348 password stored in ISDS, otherwise system refuse password update.
 349
 350 Password must meet formal syntax rules assuring strong complexity:
 351
 352     – 8 ≤ length ≤ 32 characters
 353
 354     – Must contains:
 355
 356         * at least 1 upper case letter
 357
 358         * at least 1 lower case letter
 359
 360         * at least 1 digit
 361
 362     – Allowed alphabet is [a-z], [A-Z], [0-9], and "!#$%&()*+,-.:=?@[]_{}|~"
 363     (delimited with double quotations).
 364
 365     – Must differ from last 255 passwords
 366
 367     – Must not equal to user ID, user's last name and phone number
 368
 369 Service is meaningful only when user logs in with password.
 370
 371 After successfull password update, client continue in current sessesion.
 372 Password change takes effect after propagation into whole ISDS cluster (about
 373 15 seconds).
 374
 375 Error codes:
 376     0000    Password chaned successfully
 377     1066    Empty password
 378     1067    New password same as current one
 379     9204    Generic error