Maintenance web services specification
======================================

Source: Provozní řád ISDS, version 2010-01-22, Pages 14–15
Source: Webové služby rozhraní ISDS pro správu datových schránek,
    version 2.15 (2010-11-19)
Source: Webové služby související s přístupem do ISDS, version 1.9
    (2011-09-11)
Source: dbTypes.xsd, version 2.11 (2010-11-23)


These services are intended for administration of box as such. NONE of the
services MARK incoming messages as delivered.

SOAP web services defined in: db_manipulations.wsdl (Appendix 3),
db_access.wsdl (Appendix 2)

Data types: dbTypes.xsd (Appendix 3)

Documentation: DataBox_ws.pdf (Appendix 3), GetInfo_ws.pdf (Appendix 2)

Note: OVM mode is defined in paragraph 5a of Czech ISDS Act (300/2008 Coll.)

Non-normative: [dbTypes.xsd] augments XSD:gDbReqStatus type with optional
dbStatusRefNumber element carrying request serial number assigned by ISDS.

List of SOAP requests follows.


db_manipulations.wsdl
=====================

URL postfix: DsManage

CreateDataBox
    Create box
CreateDataBoxPFOInfo
    Report PFO/FO insert into registry
DeleteDataBox
    Remove box permanently
UpdateDataBoxDescr
    Change data about box owner
AddDataBoxUser
    Add person permitted to access to the box
DeleteDataBoxUser
    Remove person permitted to access to the box
UpdateDataBoxUser
    Change data about permitted person
NewAccessData
    Reset user credentials (remove old ones and generates new ones)
DisableDataBoxExternally
    Make box inaccessible because owner lost ability to use the box for legal
    reasons (prisoned person, person with no or weak legal rights)
DisableOwnDataBox
    Make box inaccessible on request of its owner
EnableOwnDataBox
    Renew access to the box
SetEffectiveOVM
    Switch box into OVM mode
CleareEffectiveOVM
    Set box off OVM mode
SetOpenAddressing
    Switch box into commercial message receiving mode
ClearOpenAddressing 
    Set box off commercial message receiving mode
GetDataBoxUsers
    Get list of users permitted to access a box
Activate
    Not documented
DeleteDataBoxPromptly
    Not documented


db_access.wsdl
==============

URL postfix: DsManage

GetOwnerInfoFromLogin
    Get data about box of logged in user.
GetUserInfoFromLogin
    Get data about logged in user
GetPasswordInfo
    Get data about password expiration
ChangeISDSPassword
    Change password


ChangePassword.wsdl
===================

URL path: /asws/changePassword
Name space: http://isds.czechpoint.cz/v20/asws

ChangePasswordOTP
    Change password if one-time password authentication is in use
SendSMSCode
    Request delivering time-based OTP code through side channel


CreateDataBox
=============

Create box of any type with complete set of PRIMARY users (i.e. box owners).
Additional users can be assigned by AddDataBoxUser.

Freshly created box has state 3, after first log-in (or first log-in time out),
box changes moves to standard state 1.

Credentials will be sent to each PRIMARY user by paper mail. Credentials
postal address is supplied contact address or address obtained from external
government registers (supplied person or firm address must match them).

If optional dbVirtual element is true, optional input element email is
required and ISDS will return one-time password that box owner will use to
obtain his credentials. See NewAccessData for more details.

Different box types can created by users with specific privileges.

Input structure is:
CreateDataBox
    + dbOwnerInfo – describe box and its owner, if only one owner exists (e.g.
    |   FO box type)
    + dbPrimaryUsers – list of primary users (box type FO has empty list,
    |   |   PFO has only one which carries contact address only,
    |   |   OVM has only one which describes office manager,
    |   |   PO has one or more, even other PO user type is applicable
    |   + dbUserInfo – primary user description (not all fields has meaning)
    |   + dbUserInfo
    |   ⋮
    + dbFormerNames – former name of the user, optional
    + dbUpperDBId – ID of supper box, optional
    + dbCEOLabel – title of OVM manager (required for OVM box, optional
    |       otherise)
    + dbVirtual – true if user want to get initial credentials on
    |       activation portal. Optional
    + email – address to send notification about new credentials, optional,
    |       required and meaningful only if dbVirtual is true
    + dbApproved – optional
    + dbExternRefNumber – optional

Returns ID of new box and token for activation portal if requested by
dbVirtual.


CreateDataBoxPFOInfo
====================

Report PFO insert into external registry.

This service is only for sake of legislation. ISDS does use provided data
anyhow.

It does not create a box nor return new box ID. See CreateDataBox for more
details. 


DeleteDataBox
=============

Remove box permanently.

If request succeeds, box will moves to state 4, and three years after that to
state 5.

Input is box description and ISO date of owner cancellation
(dbOwnerTerminationDate element).


UpdateDataBoxDescr
==================

Change data about box or its owner.

Input is current box description and new description. Different fields can
(not) be changed by different box types and differently privileged user.


AddDataBoxUser
==============

Add person permitted to access to the box

Different user types can be added only by users with specific privileges
(PRIMARY_USER can be added only by PRIVIL_CZP user).

Mandatory input is box description and new user definition.

If optional input dbVirtual is true, additional input element email specifies
e-mail address to send notificication about new account and link where to get
find initial credentials for created user. Then two output elements are
returned: dbUserID (XSD mistakenly says dbID) and dbAccessDataId for new
user identifier and temporal token to login on the web page linked from
received e-mail. See NewAccessData for more details.


DeleteDataBoxUser
=================

Remove person permitted to access to the box.

Different user types can be removed only by users with specific privileges
(PRIMARY_USER can be removed only by PRIVIL_CZP user).

Input is box description and user description.


UpdateDataBoxUser
=================

Change data about user assigned to given box.

Input is box description (box ID or other criteria), old user data and new
user data.

Non-normative: old user data are used not only to identify user in ISDS, they
are used by ISDS to recognise data changes. Permission to change data are
tested against these differences. In other words, client must supply complete
old user data, not only user ID.

One can change any data (even user permissions) except user type of PRIMARY
user. However PRIMARY user assigned to PO or OVM box can be removed
(DeleteDataBoxUser) and recreated (AddDataBoxUser).


NewAccessData
=============

Reset user credentials (remove old ones and generates new ones). This service
is designed to user who forgot his credentials. He must apply for the reset
off-line on dedicated meeting point.

Input is box description, user description, billing flag and optional switch
how to deliver new credentials and optional user's e-mail address.

If switch is true, e-mail address will be recorded in the ISDS and output
element dbAccessDataId will contain token that user will use to authorize to
web page revealing new credentials and output element dbUserID will contain
new user log-in name.

If switch is false, new credentials will be sent by paper mail to user. Input
e-mail address and output token and new log-in name will not be returned.

Non-normative: The special web page revealing new credentials is
<https://www.czechpoint.cz/aktivacniportal/>. The form requires e-mail address
to match e-mail address provided on meeting point.


DisableDataBoxExternally
========================

Make box inaccessible because owner lost ability to use the box for legal
reasons (prisoned person, person with no or weak legal rights).

Input is box description and date when the ability to access box has became
impossible. This can be retroactive.

After success, box changes state to state 2.

Non-normative error codes:
    1004    Operation not permitted


DisableOwnDataBox
=================

Make box inaccessible on request of its owner.

Despite name, this does not disable access to the box of currently logged in
user. The box owner must apply for making his box inaccessible off-line on
special off-line meeting point and officer (with permission PRIVIL_OVMPOZAK
| PRIVIL_CZP) call this SOAP service. Result is box state changed to value 2.

Input is box description (box ID or other criteria).


EnableOwnDataBox
================

Renew access to box made inaccessible previously.

Disable/enable access period is limited by law and can be charged. See
DisableOwnDataBox for more details.


SetEffectiveOVM
===============

Switch box into mode where the box can on explicit request sent messages as
OVM boxes can. This is suitable for private organisations or persons that
have government delegations.

Input is box ID.


CleareEffectiveOVM
==================

Remove box privilege to act as a government or municipality (OVM role).

Input is box ID.


SetOpenAddressing
=================

Switch box into commercial message receiving mode.

Box will be capable to receive commercial messages. This does not imply
permission to send commercial messages.

Input is box ID.


ClearOpenAddressing
===================

Switch box out of commercial message receiving mode.

Input is box ID.


GetDataBoxUsers
===============

Get list of users permitted to access given box.

Note: This request is not specified in any verbose document. Following info
has been obtained from XML Schema file [dbTypes.xsd].

Input is type of XSD:tIdDbInput. Only box ID is sufficient probably.

Output is list of box users. Structure:

GetDataBoxUsersResponse
    + dbUsers – optional
    |   + dbUserInfo – zero count is possible. Type of XSD:tDbUserInfo. See
        |           GetUserInfoFromLogin request for more details.
    |   + dbUserInfo
    |   ⋮ 
    + dbStatus


Activate
========

This service is not documented. The only mention is in XML Schema.

There are two elements on input: dbAccessDataId (temporary token for user to
get access to his initial credentials probably) and dbID (box identifier).

Output is sequence of userId (user identifier), password (non-empty string),
and dbStatus (common service return code).


DeleteDataBoxPromptly
=====================

This service is not documentd. The only mention is in XML Schema and change
log. Even the SOAP end-point dsManage is not specified.

There are following elements in input: dbOwnerInfo (identifies box by owner
structure) and group of optional elements gExtApproval (sequence of dbApproved
and dbExternRefNumber as used in other services).

Output is standard dbStatus subtree (error code and message of requested
service).


GetOwnerInfoFromLogin
=====================

Get details about current box that user is logged in.

Input is empty dummy request.

Result is returned in tDbOwnerInfo structure. Some structure members are
undefined or unknown for particular box type.


GetUserInfoFromLogin
====================

Get details about currently logged in user.

Input is empty dummy request.

Output is returned in tDbUserInfo. Some members can be irrelevant (and thus
undefined) for particular user. Service can fail if user has logged into box
with system certificate.


GetPasswordInfo
===============

Inquire expiration time of current user password.

By default password expires in 90 days. ISDS can force password change sooner.

Non-normative: If user does not change password after expiration, SOAP server
will return non-SOAP response and client could not continue in work.

Input is empty dummy request.

Output is ISO time of password expiration in pswExpDate element. If password
expiration is disabled, empty element is returned. Service has no sense if client
authenticates with certificate only.


ChangeISDSPassword
==================

Change user password.

Input is current password and new password. Supplied new password must match
password stored in ISDS, otherwise system refuse password update.

Password must meet formal syntax rules assuring strong complexity:

    – 8 ≤ length ≤ 32 characters

    – Must contains:

        * at least 1 upper case letter

        * at least 1 lower case letter

        * at least 1 digit

    – Allowed alphabet is [a-z], [A-Z], [0-9], and "!#$%&()*+,-.:=?@[]_{}|~"
    (delimited with double quotations).

    – Must differ from last 255 passwords

    – Must not contain user ID

    – Must not contain sequence of 3 or more same characters
    
    – Must not start with `qwert', `asdgf', or `12345'

Service is meaningful only when user logs in with password but without
additional one-time password authentication. In case OTP method, use
`ChangePasswordOTP' SOAP service instead.

After successful password update, client can continue in current session.
Password change takes effect after propagation into whole ISDS cluster (about
15 seconds).

Error codes:
    0000    Password changed successfully
    1066    Too short or too long
    1067    New password same as current one
    1079    Password contains forbidden character
    1080    Does not contain lower cased letter, upper cased letter and a digit
    1081    Sequence of repeated character
    1082    Contains user ID
    1083    Too simple
    1090    Bad current password
    1091    Password matches one of older passwords
    9204    LDAP update error


ChangePasswordOTP
=================

Change user password if OTP authentication is enabled and required by server.

This service is meaningfull only with OTP authentication. Use
`ChangeISDSPassword' instead, if authentication with static password is in
use.

This service resides on different URL path, not only on different path suffix.
This service uses different name space <http://isds.czechpoint.cz/v20/asws>.

Input is current password in `dbOldPassword' element, new password in
`dbNewPassword' element, and OTP method in `dbOTPType' element (known values
are: `HOTP', `TOTP'). The selected OTP method must match log-in OTP method.

This service is available without prior statefull log-in. This SOAP request
must be accompanied with HTTP Basic authentication header delivering user
name and current password concatenated with an OTP code.

In case of time-based authentication, client can request delivering new OTP
code through side channel by `SendSMSCode' service prior issuing this request.

Details of user authentication are described in `login' document, `HTTP OTP
Methods' section.

Restrictions to new password and response format are the same as in
`ChangeISDSPassword' service.

Output has schema of `dbStatus' element.

Error codes:
    1066    Too short or too long
    1067    Password matches one of older passwords
    1082    Contains user ID
    1083    Too simple
    2300    Unexpected error

Non-normative: Be ware ChangeISDSPassword case with code 1091 is reported by
ChangePasswordOTP as code 1067.


SendSMSCode
===========

Ask server to send new OTP code through SMS gateway. Delivered code is
intended as input to HTTP Basic authorization header for `ChangePasswordOTP'
service.

This service resides on different URL path, not only on different path suffix.
This service uses different name space <http://isds.czechpoint.cz/v20/asws>.

This service is available without prior statefull log-in. This SOAP request
must be accompanied with HTTP Basic authentication header delivering user
name and current password.

Output has schema of `dbStatus' element.

Error codes:
    0000    Success
    2300    Unexpected error
    2301    One-time code cannot be re-send faster than once a 30 seconds
    2302    One-time code could not been sent. Try later again.