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.9 (2010-05-03)
Source: Webové služby související s přístupem do ISDS, version 1.2
    (2010-05-12)


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.


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


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).

Non-normative: If dbUseActPortal element is true, ISDS will return one-time
password that box owner will use to obtain 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 – optional, undocumented
    + dbUpperDBId – ID of supper box, optional
    + dbCEOLabel – title of OVM manager (required for OVM box, optional
    |       otherise)
    + dbUseActPortal – true if user want to get initial credintials on
            activation portal. optional
    + dbApproved – optional
    + dbExternRefNumber – optional

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


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).

Input is box description and new user definition.


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.

If switch is true, output element dbAccessDataId will contain token that user
will use to authorize web page revealing new credentials. If switch is false,
new credentials will be send by paper mail to user.

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 detail.s


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:

EnableOwnDataBoxResponse
    + dbUsers – optional
    |   + dbUserInfo – at least one must present. Type of XSD:tDbUserInfo. See
        |           GetUserInfoFromLogin request for more details.
    |   + dbUserInfo
    |   ⋮ 
    + dbStatus


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. 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.

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
    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
    9204    LDAP update error