1 Maintenance web services specification
2 ======================================
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
9 Source: dbTypes.xsd, version 2.11 (2010-11-23)
12 These services are intended for administration of box as such. NONE of the
13 services MARK incoming messages as delivered.
15 SOAP web services defined in: db_manipulations.wsdl (Appendix 3),
16 db_access.wsdl (Appendix 2)
18 Data types: dbTypes.xsd (Appendix 3)
20 Documentation: DataBox_ws.pdf (Appendix 3), GetInfo_ws.pdf (Appendix 2)
22 Note: OVM mode is defined in paragraph 5a of Czech ISDS Act (300/2008 Coll.)
24 Non-normative: [dbTypes.xsd] augments XSD:gDbReqStatus type with optional
25 dbStatusRefNumber element carrying request serial number assigned by ISDS.
27 List of SOAP requests follows.
38 Report PFO/FO insert into registry
40 Remove box permanently
42 Change data about box owner
44 Add person permitted to access to the box
46 Remove person permitted to access to the box
48 Change data about permitted person
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)
55 Make box inaccessible on request of its owner
57 Renew access to the box
59 Switch box into OVM mode
63 Switch box into commercial message receiving mode
65 Set box off commercial message receiving mode
67 Get list of users permitted to access a box
80 Get data about box of logged in user.
82 Get data about logged in user
84 Get data about password expiration
92 URL path: /asws/changePassword
93 Name space: http://isds.czechpoint.cz/v20/asws
96 Change password if one-time password authentication is in use
98 Request delivering time-based OTP code through side channel
104 Create box of any type with complete set of PRIMARY users (i.e. box owners).
105 Additional users can be assigned by AddDataBoxUser.
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.
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).
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.
118 Different box types can created by users with specific privileges.
122 + dbOwnerInfo – describe box and its owner, if only one owner exists (e.g.
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)
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
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
143 Returns ID of new box and token for activation portal if requested by
150 Report PFO insert into external registry.
152 This service is only for sake of legislation. ISDS does use provided data
155 It does not create a box nor return new box ID. See CreateDataBox for more
162 Remove box permanently.
164 If request succeeds, box will moves to state 4, and three years after that to
167 Input is box description and ISO date of owner cancellation
168 (dbOwnerTerminationDate element).
174 Change data about box or its owner.
176 Input is current box description and new description. Different fields can
177 (not) be changed by different box types and differently privileged user.
183 Add person permitted to access to the box
185 Different user types can be added only by users with specific privileges
186 (PRIMARY_USER can be added only by PRIVIL_CZP user).
188 Mandatory input is box description and new user definition. The new user can
189 have AIFOTicket attribute defined.
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.
202 Remove person permitted to access to the box.
204 Different user types can be removed only by users with specific privileges
205 (PRIMARY_USER can be removed only by PRIVIL_CZP user).
207 Input is box description and user description.
213 Change data about user assigned to given box.
215 Input is box description (box ID or other criteria), old user data and new
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.
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).
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.
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.
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.
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
247 This service was removed from specification on 2015-06-08.
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.
254 DisableDataBoxExternally
255 ========================
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).
260 Input is box description and date when the ability to access box has became
261 impossible. This can be retroactive.
263 After success, box changes state to state 2.
265 Non-normative error codes:
266 1004 Operation not permitted
272 Make box inaccessible on request of its owner.
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.
279 Input is box description (box ID or other criteria).
285 Renew access to box made inaccessible previously.
287 Disable/enable access period is limited by law and can be charged. See
288 DisableOwnDataBox for more details.
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.
304 Remove box privilege to act as a government or municipality (OVM role).
312 Switch box into commercial message receiving mode.
314 Box will be capable to receive commercial messages. This does not imply
315 permission to send commercial messages.
323 Switch box out of commercial message receiving mode.
331 Get list of users permitted to access given box.
333 Note: This request is not specified in any verbose document. Following info
334 has been obtained from XML Schema file [dbTypes.xsd].
336 Input is type of XSD:tIdDbInput. Only box ID is sufficient probably.
338 Output is list of box users. Structure:
340 GetDataBoxUsersResponse
342 | + dbUserInfo – zero count is possible. Type of XSD:tDbUserInfo.
343 | | The AIFOTicket attribute can exist. See
344 | | GetUserInfoFromLogin request for more details.
353 This service is not documented. The only mention is in XML Schema.
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).
358 Output is sequence of userId (user identifier), password (non-empty string),
359 and dbStatus (common service return code).
362 DeleteDataBoxPromptly
363 =====================
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.
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).
372 Output is standard dbStatus subtree (error code and message of requested
376 GetOwnerInfoFromLogin
377 =====================
379 Get details about current box that user is logged in.
381 Input is empty dummy request.
383 Result is returned in tDbOwnerInfo structure. Some structure members are
384 undefined or unknown for particular box type.
390 Get details about currently logged in user.
392 Input is empty dummy request.
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.
402 Inquire expiration time of current user password.
404 By default password expires in 90 days. ISDS can force password change sooner.
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.
409 Input is empty dummy request.
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.
419 Change user password.
421 Input is current password and new password. Supplied new password must match
422 password stored in ISDS, otherwise system refuse password update.
424 Password must meet formal syntax rules assuring strong complexity:
426 – 8 ≤ length ≤ 32 characters
430 * at least 1 upper case letter
432 * at least 1 lower case letter
436 – Allowed alphabet is [a-z], [A-Z], [0-9], and "!#$%&()*+,-.:=?@[]_{}|~"
437 (delimited with double quotations).
439 – Must differ from last 255 passwords
441 – Must not contain user ID
443 – Must not contain sequence of 3 or more same characters
445 – Must not start with `qwert', `asdgf', or `12345'
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.
451 After successful password update, client can continue in current session.
452 Password change takes effect after propagation into whole ISDS cluster (about
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
464 1090 Bad current password
465 1091 Password matches one of older passwords
466 9204 LDAP update error
472 Change user password if OTP authentication is enabled and required by server.
474 This service is meaningfull only with OTP authentication. Use
475 `ChangeISDSPassword' instead, if authentication with static password is in
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>.
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.
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.
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.
492 Details of user authentication are described in `login' document, `HTTP OTP
495 Restrictions to new password and response format are the same as in
496 `ChangeISDSPassword' service.
498 Output has schema of `dbStatus' element.
501 1066 Too short or too long
502 1067 Password matches one of older passwords
503 1082 Contains user ID
505 2300 Unexpected error
507 Non-normative: Be ware ChangeISDSPassword case with code 1091 is reported by
508 ChangePasswordOTP as code 1067.
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'
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>.
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.
525 Output has schema of `dbStatus' element.
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.