2. CDOC2 Client Application Use Case Model¶

CDOC2 Client Application is an abstract component in the CDOC2 System. CDOC2 Client Applications help users to encrypt files to CDOC2 Container, decrypt received CDOC2 Containers. Specific examples of CDOC2 Client Applications include:

DigiDoc4 desktop application for Windows, MacOS and Linux operating systems (https://open-eid.github.io/#desktop-applications, https://www.id.ee/en/rubriik/digidoc4-client/, https://github.com/open-eid/DigiDoc4-Client)
DigiDoc4 mobile application for Android and IOS operating systems (https://open-eid.github.io/#mobile-applications)
CDOC2 Client CLI Application

Use cases specified here are written in generic form, so that they are applicable to all client applications. Client applications will implement specified use cases and their documentation may include additional information (use case models, UX wireframes, ...) about the implemented functions.

2.1 Actors¶

2.1.1 Human actors¶

User: Person, who is using CDOC2 Client Applications for sending encrypted files to somebody else (then as a Sender), or decrypting received CDOC2 Containers (then as a Recipient). In some use cases, the User may encrypt files with symmetric encryption key or password, store the CDOC2 Container for themselves and later decrypt the CDOC2 Container by themself.
Sender: User, who wishes to send encrypted files, which are packaged into a CDOC2 Container, to one or multiple Recipients
Recipient: User, who wishes to decrypt the received CDOC2 Container and has control over necessary cryptographic key material
Administrator: Person, who is managing CDOC2 Client Application for Users and is creating the configuration data for them

2.1.2 System components as actors¶

CDOC2 Client Application (Client): Desktop or mobile application, which encrypts or decrypts CDOC2 Containers and is used by Users
CDOC2 Capsule Server (CCS): CCS mediates CDOC2 Server Capsules between Sender and Recipient. Sender's Client can upload a Server Capsule to one or multiple CCS servers. Recipient's Client can download Server Capsule from CCS server after authentication.
Capsule: Data structure, which contains encryption scheme-specific information (encrypted symmetric keys, public keys, salt, server object references, ...)
which Recipient can use to derive, establish or retrieve decryption keys for decrypting the CDOC2 Container. Capsule can either be a Server Capsule or a Container Capsule.
Server Capsule: A Capsule that is mediated by a CDOC2 Capsule Server.
Container Capsule: A Capsule that is created inside a CDOC2 container and is therefore not sent to a CDOC2 Capsule Server.
LDAP-server: An application used for publishing public keys.

2.2 Use cases for Recipients with hardware security tokens¶

These use cases are useful, when Sender knows that Recipient has specific hardware security token, and knows the public key certificate which correspond to the asymmetric cryptographic key pair on that security token. KC, which can be decrypted only with Recipient's security token, may be transmitted alongside with the CDOC2 Container itself with the encrypted payload, or with the help of CCS server.

2.2.1 UC.Client.01 — Encrypt CDOC2 container for sending to Recipient with a security token¶

Use Case Context: CDOC2 Client Application adds Sender's chosen files into the CDOC2 container and encrypts the container with CEK. CEK is encrypted with KEK, which is generated with key-agreement protocol between Sender and Recipient.
Scope: CDOC2 Client Application (Client)
Use Case Level: User goal
Primary Actor: Sender

Success Guarantees

CDOC2 container is saved into filesystem.
A server capsule is sent for each Recipient to the CDOC2 capsule server.
Client has received a transaction code for each server capsule.

Main Success Scenario

Sender chooses files to be included in CDOC2 container and specifies the target filename and path for CDOC2 container.
Sender enters identifiers for each Recipient.
Client creates a capsule for each Recipient.
Client displays a list of Capsule Servers to Sender.
Sender chooses a CDOC2 Capsule Server.
Client creates a TLS-connection with the chosen CDOC2 Capsule Server and receives the server's certificate.
Client verifies the server's certificate against the configuration.
Client forwards each Recipient's server capsule to the chosen CDOC2 Capsule Server. Client provides a server capsule expiration time from internal application configuration for each capsule. If a Recipient's certificate expiration time is earlier, it uses the certificate expiration time for that Recipient's capsule. Client receives a transaction code for each server capsule.
Client creates a container into filesystem in the chosen target path and adds a header.
Client verifies that the header does not exceed the size limit defined by the specification.
Client verifies technical file correctness and file name safety rules according to the specification. Client creates an archive, compresses it, encrypts the compressed archive with CEK and adds it to the container as payload.
Client saves the CDOC2 container and displays Sender a notification.

Extensions

1a. Sender chose to encrypt from the Windows Explorer / MacOS Finder / Linux folder explorer context dialog: "Encrypt with eID" and "Encrypt with password":

Client asks Sender for the container target name and path.
Sender specifies the target name and path.
Use case continues from step 2.

2a. Client chooses to search for Recipient information in LDAP directory:

Sender inserts Recipient personal code (natural person) or name / business registry code (juridical person).
Client requests corresponding certificates and displays those.
Sender chooses certificate(s).
Use case continues from step 2.

2b. Certificate is not readable or is not in proper format:

Client displays Sender a notification.
Use case ends.

5a. Configuration has no CDOC2 capsule servers:

Client creates a container in the target path and adds a header with container capsules for each recipient.
Use case continues from step 11.

5b. Configuration has a default CDOC2 capsule server:

Use case continues from step 7.

6a. Sender chooses to not use the CDOC2 capsule server:

Client creates a container in the target path and adds a header with container capsules for each recipient.
Use case continues from step 11.

7a. TLS connection cannot be established:

Client displays Sender a notification.
Use case continues from step 5.

8a. Certificate validation against the configuration fails:

Client displays Sender a notification.
Use case continues from step 5.

8b. Client uses a organization-specific external configuration service:

Client first syncs default capsule expiration time from an orgnaization-specific external service.
External configuration service provides a default capsule expiration time.
Client sends a server capsule using the appropriate API service to a CCS using the expiration time from external configuration or when a Recipient's certificate expiration time is earlier, it uses the certificate expiration time for that Recipient's capsule. Client receives a transaction code for each server capsule.
Use case continues from step 9.

8c. The expiration time provided by Client is longer than allowed in the CCS system configuration:

CCS returns Client a error message.
Client notifies Sender.
Use case ends.

9a. Forwarding capsules to a CDOC2 capsule server fails:

Client displays Sender a notification.
Use case ends.

9b. CDOC2 capsule server does not return a transaction identifier for each server capsule:

Client displays Sender a notification.
Use case ends.

10a. Header size is larger than allowed by the specification:

Client displays Sender a notification.
Use case ends.

11a. Files are not correct:

Client displays Sender a notification.
Use case ends.

2.2.2 UC.Client.02 — Decrypt CDOC2 Container with a security token¶

Use Case Context: CDOC2 Client Application (Client) decrypts the archive in the CDOC2 container provided by Recipient, using a server capsule from either CDOC2 Capsule Server or a container capsule from inside the container.

Scope CDOC2 Client Application

Use Case Level: User goal
Primary Actor: Recipient

Preconditions

Recipient's security token is connected.

Success Guarantees

Files from the CDOC2 container are decrypted.

Main Success Scenario

Recipient chooses the CDOC2 Container to be decrypted and specifies the target filename and path for the files.
Client verifies that the header does not exceed the size limit defined by the specification.
Client reads Recipient certificate from the security token.
Client verifies that the container has a record of the Recipient.
Client verifies that the Recipient record has a CDOC2 Capsule Server reference.
Client uses Recipient's eID means to authenticate to CCS.
Client sends the CDOC2 Capsule Server the transaction code from the container.
Client receives a capsule from the CDOC2 Capsule Server.
Client decrypts the encrypted archive in the CDOC2 container using the connected security token.
Continues with UC.Client.P.04 — Re-encrypt existing CDOC2 container for long-term storage.

Extensions 2a. Header size is larger than allowed by the specification:

Client displays Recipient a notification.
Use case ends.

3a. Reading certificate from the security token fails.

Client displays Recipient a notification.
Use case ends.

4a. Recipient record not found in the container.

Client displays Recipient a notification.
Use case ends.

5a. Recipient record does not contain a reference to a CDOC2 Capsule Server.

Client finds a container capsule from the Recipient record.
Use case continues from step 9.

6a. PIN 1 code is required:

Client asks user for a PIN 1 code.
Recipient enters the PIN code.
Client completes the authentication. Use case continues from step 7.

6b. Authentication fails:

Client displays user a notification.
Use case ends.

8a. No capsule returned from CDOC2 Capsule Server:

Client displays user a notification.
Use case ends.

9a. Decryption of the content encryption key fails:

Client displays user a notification.
Use case ends.

2.3 Use cases for password-based encryption¶

These use cases are useful when User wishes to protect confidential files by encrypting them with CEK generated from regular password. User may then store CDOC2 Container for longer period, without worrying that security token may not be usable, or public key certificate might be revoked or expired. CDOC2 Container may be later decrypted by Sender itself or Recipient, who knows the shared password.

This group of UCs also include a special use case, when Recipient re-encrypts the content from received Container with a password.

2.4 UC.Client.P.01 — Encrypt CDOC2 container with password for long-term storage¶

Use Case Context: Encrypt local files for long-term storage using CDOC2 Client Application and password-based cryptography by creating a new CDOC2 Container. This use case is useful for occasions where decryption does not depend on availability of security tokens.
Scope: CDOC2 Client Application (Client)
Use Case Level: User goal
Primary Actor: User

Success Guarantees

A new CDOC2 container is created and it can be decrypted with the user's password.

Main Success Scenario

User chooses the files that are to be encrypted.
Client asks User to specify the target name and path.
User specifies a target name and path in local filesystem.
User enters a password to be used for password-based cryptography.
Client verifies that the password satisfies minimal requirements.
Client creates a container into filesystem in the chosen target path and adds a header.
Client verifies that the header does not exceed the size limit defined by the specification.
Client verifies technical file correctness, creates an archive, compresses it and encrypts the compressed archive.
Client saves the CDOC2 container and displays Sender a notification.

Extensions

1a. Sender chose to encrypt from the Windows Explorer / MacOS Finder / Linux folder explorer context dialog: "Encrypt with eID" and "Encrypt with password":

Client asks Sender for the container target name and path.
Sender specifies the target name and path.
Use case continues from step 2.

5a. Password does not meet minimum requirements:

Client notifies the User with instructions to insert a new password.
Use case continues from step 4.

6a. Container creation fails:

System notifies the User.
Use case ends.

7a. Header size is larger than allowed by the specification:

Client displays Sender a notification.
Use case ends.

8a. Files are not correct:

Client displays Sender a notification.
Use case ends.

9a. Container saving fails:

Client notifies the User.
Use case ends.

2.5 UC.Client.P.02 — Decrypt CDOC2 container with password¶

Use Case Context: CDOC2 Client Application decrypts CDOC2 Container with password-based cryptography.
Scope: CDOC2 Client Application (Client)
Use Case Level: User goal
Primary Actor: User, Recipient

Main Success Scenario

User specifies which CDOC2 container they wish to open.
Client opens the container and retrieves the header information. Client verifies that the header does not exceed the limit defined in the specification.
Client asks User for the password to decrypt the container. Client shows a password hint based on the KeyLabel value set during encryption.
User enters the password.
Client verifies the password and decrypts the CDOC2 container.
Client asks user for the target location where to save the files.
User defines the target location.
Client unpacks the archive contents and saves it to the target location.

Extensions

2a. Header exceed the length limit according to the specification:

Client notifies the user.
Use case ends.

5a. Password is not correct:

Client notifies the user.
Use case continues from step 3.

8a. Saving archive contents to disk fails:

Client notifies the user.
Use case ends.

2.6 UC.Client.P.04 — Re-encrypt existing CDOC2 container for long-term storage¶

Use Case Context: CDOC2 Client Application offers Recipient to re-encrypt all files after CDOC2 container decryption and before extracting and saving files locally.
Scope: CDOC2 Client Application (Client)
Use Case Level: User goal
Primary Actor: User, in a Recipient role

Preconditions

CDOC2 container was just decrypted.

Success Guarantees

Files are re-encrypted.
The re-encrypted container is saved locally.

Main Success Scenario

Client suggests Recipient to re-encrypt the decrypted container contents and displays multiple options for encryption.
Recipient chooses to re-encrypt and chooses to encrypt with a password.
Client asks Recipient to specify the target name and path.
Recipient specifies a target name and path in local filesystem.
Recipient enters a password to be used for password-based cryptography.
Client verifies that the password satisfies minimal requirements.
Client adds the files to an archive and creates a new CDOC2 container, which it saves to the target location.
Client asks Recipient whether to delete the server capsule that was used during the previous decryption process. The purpose is to make it impossible that anybody could ever again decrypt the original message.
Recipient chooses to delete the server capsule.
Client, still having access to the original container decrypted container, reads again the recipient record from it and makes a request to CCS to delete the server capsule by providing the same transaction code.
CCS deletes the server capsule and replies with a confirmation response.
Client notifies the Recipient.

Extensions

2a. Recipient chooses to re-encrypt using a security token:

Client verifies that the security token is connected.
Recipient specifies a target name and path in local filesystem and enters the security token password.
Client verifies the password. If password is not correct, the use case continues from the previous step.
Use case continues from step 7.

5a. Password does not meet minimum requirements.

Client notifies the Recipient with instructions to insert a new password.
Use case continues from step 3.

7a. Container creation or saving fails.

System notifies the Recipient.
Use case ends.

9a. Recipient does not want to delete the server capsule:

Use case ends.

10a. Recipient's authentication has expired:

Client completes the use case UC.KTS.04 Authenticate Recipient.
Use case resumes from step 10.

11a. No non-expired Server Capsules found with the corresponding transaction ID:

Server returns an error message.
Client assumes that the server capsule does no longer exist and notifies the Recipient.
Use case ends.

11a. Establishing a connection to the CCS fails:

Client notifies the Recipient.
Recipient chooses whether to try again. If yes then use case continues from step number 3. Otherwise use case ends.

3. CDOC2 Capsule Server Use Case Model¶

3.1 UC.KTS.01 Forward Capsules¶

Context of Use: CDOC2 Client Application forwards CDOC2 Capsule Server Server Capsules, which contain a content encryption key encrypted for a particular Recipient, which is used for decrypting the archive in CDOC2 container. Server Capsule is saved with an expiration time and a unique transaction code is created and returned to the CDOC2 Client Application.

Scope CDOC2 Capsule Server (CCS)

Use Case Level: User goal
Primary Actor: CDOC2 Client Application (Client)

Success Guarantees

Server Capsules are saved with an expiration time.
Transaction codes are forwarded to the CDOC2 Client Application.

Main Success Scenario

Client sends server capsules using the appropriate API service to a CCS. Client provides a server capsule expiration time from internal application configuration for each capsule. If a Recipient's certificate expiration time is earlier, it uses the certificate expiration time for that Receipient's capsule.
CCS validates the server capsules against specification rules.
CCS generates a universally unique transaction code (UUID).
CCS saves the server capsule, validates the expiration time provided by Client based on its system configuration settings and sets the expiration time of the capsules.
CCS returns Client a transaction code for each capsule.

Extensions 1a. Client uses a orgnaization-specific external configuration service:

Client first syncs default capsule expiration time from an orgnaization-specific external service.
External provides a default capsule expiration time.
Client sends a server capsule using the appropriate API service to a CCS using the expiration time from external configuration or when a Reciepent's certificate expiration time is earlier, it uses the certificate expiration time for that Recipient's capsule.
Use case continues from step 2.

2a. Server capsule exceeds the allowed length limit:

CCS returns Client a error message.
Use case ends.

4a. Client did not provide an expiration time:

CCS calculates the expiration time based on system configuration.
Use case continues from step 5.

4b. The expiration time provided by Client is longer than allowed in the CCS system configuration:

CCS returns Client a error message.
Use case ends.

3.2 UC.KTS.02 Request Capsule¶

Context of Use: CDOC2 Client Application requests a Server Capsule from CDOC2 Capsule Server, which contains an encrypted content encryption key, used for decrypting the archive in CDOC2 container. The Server Capsule is identified by public key in Recipient certificate and the transaction code provided by CDOC2 Client Application.

Scope CDOC2 Capsule Server (CCS)

Use Case Level: User goal
Primary Actor: CDOC2 Client Application (Client)

Preconditions

Recipient is authenticated.

Success guarantees

Server Capsule is forwarded to CDOC2 Client Application.

Main Success Scenario

Client requests a Server Capsule using the appropriate API service, providing a transaction code as input.
CCS validates the transaction code against specification rules.
CCS finds the correct Server Capsule useing the transaction code and validates that the Recipient public key matches with the one in the Capsule.
CCS sends the Client the Capsule.

Extensions 2a. Transaction code is too long:

CCS returns Client an error message.
Use case ends.

3a. Capsule was not found:

CCS returns Client an error message.
Use case ends.

3b. Recipient public key does not match the one in the Capsule:

CCS returns Client an error message.
Use case ends.

3.3 UC.KTS.03 Delete Server Capsules¶

Context of Use: System timer deletes expired Server Capsules.

Scope CDOC2 Capsule Server (CCS)

Use Case Level: User goal
Primary Actor: CDOC2 Client Application (Client)

Success guarantees

Expired Server Capsules are removed from the storing CCS.

Trigger

System timer schedules and initiates the deletion of expired Server Capsules.

Main Success Scenario

CCS identifies expired Server Capsules.
CCS deletes expired Server Capsules.

Extensions

1a. No expired Server Capsules found.

Use case ends.

3.4 UC.KTS.04 Authenticate Recipient¶

Context of Use: CDOC2 Client Application (Client) establishes a TLS-connection to CDOC2 Capsule Server and forwards Recipient certificate.

Scope CDOC2 Capsule Server (CCS)

Use Case Level: Subfunction
Primary Actor: CDOC2 Client Application (Client)

Success guarantees

TLS-connection is established.
Recipient certificate exists and is received.

Main Success Scenario

Client initiates a TLS-connection and forwards Recipient certificate.
CCS verifies certificate validity using an OCSP service.
CCS establishes the TLS connection.

Extensions

2a. Recipient certificate is not valid:

CCS replies to the Client with an error message.
Use case ends.

3.5 UC.KTS.05 Request To Delete Server Capsule¶

Context of Use: Client requests the CSS to delete a server capsule.

Scope CDOC2 Capsule Server (CCS)

Use Case Level: User goal
Primary Actor: CDOC2 Client Application (Client)

Success guarantees

Server capsule is removed from the storage of the CCS.

Preconditions

Recipient has received a server capsule from a CCS.
Recipient has completed the re-encryption flow in the Client.

Main Success Scenario

Client asks Recipient whether to delete server capsule and thus make it impossible that anybody could ever again decrypt the original message.
Recipient chooses to delete the server capsule.
Client makes request to CCS to delete the server capsule by providing the same transaction code as when originally requesting the capsule.
CCS deletes the server capsule.

Extensions 2a. Recipient does not want to delete the server capsule:

Use case ends.

3a. Recipient's authentication has expired:

Client completes the use case UC.KTS.04 Authenticate Recipient.
Use case resumes from step 3.

4a. No non-expired Server Capsules found with the corresponding transaction ID:

Server returns an error message.
Client assumes that the server capsule does no longer exist and notifies the Recipient.
Use case ends.

4a. Establishing a connection to the CCS fails:

Client notifies the Recipient.
Recipient chooses whether to try again. If yes then use case continues from step number 3. Otherwise use case ends.