6. Skip to content

6. CDOC2 Capsule Server

This section defines the CDOC2 Capsule Server (herein also simply ‘the server’), its external interfaces and rules of use.

6.1 Introduction

The CDOC2 Capsule Server is a subsystem tasked with transmitting the Capsule required for the decryption of the CDOC2 container from the sender to the recipient following the rules set out for specific encryption methods in section CDOC2 encryption schemes.

The communication channel provided by the Capsule Server is more secure than public channels of communication used for the transmission of CDOC2 containers. A properly operating Capsule Server ensures the future-proofness of data transmitted in an encrypted form, as an attacker monitoring the public communication channel will not be able to acquire symmetric cryptographic keys secured with public key encryption algorithms: the keys are securely transmitted via the Capsule Server. The attacker will therefore be unable to break the encryption keys at a later time, after breaking the public key encryption algorithms or the compromising of the private keys. The Capsule Server does not need to transmit large encrypted documents, meaning that its operating costs will be low.

Multiple Capsule Servers may be used in parallel, operated by different organizations. Security requirements established in the implementation process may call for the operation of each individual Capsule Server by organizations independent from each other.

6.2 Server operating principles

In the simplest case, the server operates as follows.

  1. The sender generates a Capsule for a specific recipient during encryption.
  2. The sender chooses a Capsule Server, connects to the server and transmits the Capsule to the server along with a recipient identifier.
  3. The server generates a transaction identifier and saves the generated identifier along with the Capsule and recipient identifier.
  4. The sender adds the selected server’s identifier, transaction identifier, and recipient identifier to the container.
  5. The sender transmits the container to the recipient.
  6. The recipient finds information concerning the Capsule generated for them in the container.
  7. The recipient connects to the server chosen by the sender and authenticates with the server.
  8. The recipient transmits the transaction identifier found in the container to the server.
  9. The server looks up the Capsule based on the transaction identifier and the recipient identifier established during authentication.
  10. The server returns the Capsule to the recipient.
  11. The recipient uses the information found in the Capsule for decrypting the container.

6.3 Server state

Server state consists of the Capsules received by the server for transmission, as well as all relevant information.

  • Capsule: Byte array, meaningless for the server.
  • Transaction ID: UUID generated by the server itself using a cryptographically secure random number generator.
  • Recipient ID: Identifier received by the server as the output of the recipient authentication process.
  • Validity period: The Capsule Server stores the Capsule only for a limited period, collectively specified by the sender and the key management policies used by the Capsule Server. The capsule is deleted after this period.

6.4 Server interfaces

The server provides two interfaces: one for delivery of the Capsule from the sender to the Capsule Server and the other for delivery of the Capsule from the server to the recipient.

The interfaces are formally described in the OpenAPI format (see appendix C).

6.4.1 Sender interface

The Capsule Server sender interface is used by the sender to transmit the Capsule to the server and receive a transaction identifier that they will subsequently add to the container header.

The sender transmits the Capsule and recipient identifier to the server and receives from the server a transaction identifier. The interface is unauthenticated and can be used by all senders.

6.4.2 Recipient interface

The Capsule Server recipient interface is used by the recipient to receive a Capsule from the server.

The recipient authenticates with the server and transmits a transaction identifier. Based on this identifier, the server looks up the Capsule. The capsule must be addressed to the recipient who authenticated with the server – the server thus compares the recipient identifier established during authentication with the recipient identifier transmitted by the sender of the Capsule. The server then returns the Capsule to the recipient.

6.4.3 Interface security

Interface security is ensured using the TLS 1.3 protocol. The server holds a certificate issued by a publicly available and trusted CA. The clients can validate this certificate on each connection using the OCSP protocol.

To ensure protocol security, it is important to make sure that the Capsule is only received by the Capsule Server. This can be achieved via the pinning of server TSL keys. Key pinning ensures that commonly practiced1 use of TLS inspection does not compromise the confidentiality of the keying material.

6.5 Recipient authentication

Each Capsule Server-based Capsule type describes a specific recipient identification and authentication method. This version of the specification defines one Capsule Server-based Capsule type: KeyServerCapsule.

This list may be expanded in future versions of the specification. Various authentication schemes may be used in parallel.

6.5.1 The KeyServerCapsule authentication scheme

In this scheme, the recipient is identified by their public key used for the decryption of the container. The public key is defined by the field RecipientKey in the structure KeyServerCapsule.

The server authenticates the recipient using TLS client authentication (mTLS). The server is configured to validate the client certificate (e.g. using OSCP). Should the recipient lose control of their decryption key and cancel their certificate, the Capsule Server will not issue the Capsule card to the new holder (attacker) and the attacker will be unable to decrypt the container.

After successful authentication, the server reads the client’s public key from the certificate used by the client and compares this public key to the public key tied to the Capsule referenced by the transaction identifier. If the two keys match, the server will return the Capsule. Otherwise, the server will return an error message.

6.6 Server identification and trust

Enhanced security features provided by CDOC2 are only valid if the Capsule is transmitted via servers meeting the requirements of the specific encryption scenario (see section 3). To ensure the recipient and sender’s confidence in the servers they are using, each client using the CDOC2 format must be provided with a list of trusted Capsule Servers either as a part of the DigiDoc software package or in some other form. This list is also used for TLS key pinning. The server list consists of the following elements.

  • Server identifier
  • Capsule type supported by the server.
  • Sender interface URL.
  • Recipient interface URL.
  • Identifier of the organization maintaining the server.
  • Server public keys to enable the client to cryptographically verify the server’s identity. Public keys are provided in the form of certificates.

The sender never transmits the recipient the server’s technical access point but only its identifier in the server list. This is done to prevent attacks seeking mislead the recipient into communicating with an untrusted server.

Should multiple independent Capsule Server infrastructures be set up with no coordination of server identifier assignation between the systems and should the same identifier be assigned to different servers in different systems, this could lead to a situation where a client using the infrastructure of one system creates a container that another client will then attempt to open using the infrastructure of another system.

This would result in the recipient contacting the wrong Capsule Server, authenticating with the server, and transmitting the transaction identifier found in the container to the server. The server will be unable to find the Capsule corresponding to this transaction identifier and will return an error message (Decryption failed).

The Capsule Server used by the recipient will receive a transaction identifier but since it will be unable to authenticate with the correct Capsule Server on the behalf of the recipient, it will also be unable to download the Capsule from the correct server.

The Capsule type supported by the server allows the sender to choose the correct Capsule type and enables the recipient to authenticate with the server using the correct protocol. As the servers are lightweight, an organization seeking to support multiple different recipient types will be able to run multiple separate Capsule Servers. This ensures that the Capsule Servers can be simplified and thus made more secure. This is especially important in the case of the recipient interface, as the authentication protocols used may widely differ in their features, making secure implementation difficult.

The identifier of the organization maintaining the server does not necessarily have to be explicitly tied to the organization’s name, but it must enable the identification of servers controlled by the same organization. This information is required to support future secret sharing-based encryption methods.

Each server may be assigned more than one public key – this helps ensure smooth change of certificates and keys. Upon connection to the server, the client must always verify that the server is using one of the listed certificates. This will help prevent man-in-the-middle attacks.