Additional Building Blocks of an X-Road Ecosystem

X-Road® is open-source software and ecosystem solution that provides unified and secure data exchange between organisations. X-Road is based on a distributed model, and it enables decentralised data management and data sovereignty within the ecosystem. Every organization is in full control of its data and services, and data is always exchanged directly between two trusted members without third parties having access to it.

X-Road operator is the owner of the X-Road ecosystem and is responsible for all the aspects of the operations. The responsibilities include defining regulations and practices, accepting new members, providing support for members, and operating the central components of the X-Road software. X-Road members are organizations that have joined the ecosystem and produce and/or consume services with other members. A member organization can be a service provider, a service consumer, or both. Also, a functioning X-Road ecosystem requires two types of trust services: 1) time-stamping authority (TSA) and 2) certification authority (CA). Trust service providers are organizations providing these services.

Technically, the X-Road core consists of a Central Server and Security Server that are the foundational building blocks of the ecosystem. These components are required together with the trust services to establish a trusted network of organisations and enable secure data exchange between its members.

Besides the core and trust services, building a functional and scalable ecosystem requires some additional building blocks that support the operations and use of the ecosystem. These building blocks provide member management and onboarding capabilities, service discovery, metrics collection and reporting, and technical monitoring. The X-Road core doesn't currently offer the capabilities, and therefore, additional building blocks are required. In general, implementing and maintaining these building blocks is the responsibility of the X-Road operator. Next, let's take a closer look at these building blocks.

Service management portal

A service management portal or a self-service portal is a web portal for managing the administrative details of the ecosystem membership. The administrative tasks related to the membership and its management are usually completed using the portal. For example, new members must first send a membership application and, once it has been approved, sign a membership agreement where they agree to follow the terms and conditions of the ecosystem. Also, the portal doesn't have to be limited to the administrative level, and it may cover some technical configuration steps, e.g., requesting certificates, and provide ecosystem-specific documentation and instructions. Depending on the implementation, some parts of the process may be automated, while others require manual input. Also, the portal may provide separate interfaces for the representatives of the member organisations and the X-Road operator.

The Central Server contains a registry of X-Road member organisations and their Security Servers. The information managed by the Central Server is technical and doesn't overlap with the data managed by the service management portal. Also, the service management portal may support the technical onboarding process by automating parts that are not directly covered by the Central Server, e.g., requesting certificates. Since there's a strong connection between the technical and administrative information, the portal and Central Server may be connected. However, a management REST API for the Central Server that enables a seamless integration is a work in progress currently.

An alternative to the service management portal is to manage the membership information in a system that members cannot access directly and use email (or some other channel) for communications. For example, maintain the member information in an Excel file or an internal wiki page, and receive service requests by email. It is a quick and easy way to get started with the ecosystem, but it doesn't scale very well, provides little support for automation, and is not very user-friendly. Therefore, implementing a service management portal is highly recommended.

Currently, there’s no off-the-shelf open-source component available that could be used as a service management portal for X-Road. In general, a service management portal is a custom component, and it may also support a broader range of digital services. Also, it is often connected to ecosystem-specific backend services and registries, such as business registry, service catalog, authorisation service, etc. The Estonian and Finnish service management portals are good examples of how the portal can be implemented.

Service catalog

A service catalog is a web portal that contains descriptions of all the services available in the ecosystem. The primary purpose of the service catalog is to provide a user-friendly channel to search and discover available services. Also, the catalog may provide additional features to support the use of the services, e.g., request access to a service, sign a service agreement, etc. The service catalog is targeted at both business and technical users.

When services are connected to X-Road, their service descriptions are published on the Security Server by the Security Server administrator. The service descriptions can then be accessed using a service discovery mechanism provided by X-Road. However, the mechanism is very technical and requires direct access to the Security Server's messaging interface. Also, getting a list of all services available in the ecosystem would require querying each Security Server separately. Therefore, a more user-friendly service catalog is needed.

When implementing the service catalog, collecting the service descriptions from the Security Servers can be automated. In that way, the descriptions need to be maintained in a single place only, and all the changes in the source are automatically updated to the catalog. Nevertheless, additional metadata must be manually added and maintained on the catalog by a service administrator representing the organisation owning the service. The metadata may include any information related to the service and its use, e.g., a more detailed description of the data set, terms and conditions, contact information, pricing information, SLAs, etc.  

The Estonian, Finnish and Icelandic (only in Icelandic) service catalogs serve as examples of how the catalog can be implemented. The source code of the Finnish catalog is freely available on GitHub, and it consists of two separate components: a service catalog portal and a collector to read the service descriptions from Security Servers and store them centrally. Currently, NIIS doesn’t provide a service catalog component for X-Road.

Reporting and metrics

Reporting and metrics mean collecting usage statistics and metrics from an X-Road ecosystem. The metrics include service usage statistics, response times, request sizes, service health data, etc. The metrics can be used to measure the size and activity of the ecosystem, and they also provide interesting information about the relationships between different member organisations and their services. The information enables the X-Road operator to overview the ecosystem's state and measure its growth. Thanks to the data, the X-Road operator can make informed decisions on the development and governance of the ecosystem.

To get an overview of the whole ecosystem, the raw metrics must first be read from all Security Servers and then stored and analysed centrally. However, it’s important to remember that the metrics do not contain data that is exchanged by the members, only metadata about the use of the services. Collecting the information requires installing the operational monitoring add-on on the Security Servers. The add-on collects the raw metrics data locally and makes it available through a query interface. Nevertheless, access to the interface is restricted so that only the X-Road operator can access the data of all member organisations. Regular members can access their data only.

X-Road Metrics is an open-source component maintained by NIIS to centrally collect, store, process, and publish the data provided by the operational monitoring add-on. X-Road Metrics consists of multiple modules, and its features include but are not limited to publishing the data as open data (from the Estonian ecosystem), generating a dependency graph of member organisations (from the Estonian ecosystem), and providing statistical reports to members. However, making other implementations that utilise the operational monitoring data is also possible since all the documentation and source code are publicly available. Of course, member organisations are free to use the data in their reporting and monitoring systems.

Technical monitoring

Technical monitoring means collecting technical monitoring and health data from an X-Road ecosystem. The data can be used to monitor the Security Server's health. The data includes system metrics (CPU load, free memory, available disk space, etc.), running processes list, X-Road version information, certificated details, etc. Also, the data can be used to recognise potential future problems and maintenance needs before they affect the operations of the Security Server, e.g., detect certificates that are about to expire, detect Security Server versions that are no longer supported. The information enables the X-Road operator to get an overview of the ecosystem’s health and monitor the maintenance of individual Security Servers.

At first, technical and operational monitoring may sound like the same thing or very similar. The difference is that technical monitoring concentrates on the Security Server while operational monitoring is about monitoring services connected to X-Road. However, the way how data is recorded on the Security Server and then collected and analyzed centrally is very similar.

To technically monitor the whole ecosystem, the raw monitoring data must first be read from all Security Servers and then stored and analysed centrally. The technical monitoring data doesn’t include sensitive information, only technical monitoring data. Also, the Security Server administrator can configure the data set that can be collected centrally. Collecting the information requires installing the environmental monitoring add-on on the Security Servers. The add-on collects the raw data locally and makes it available through a query interface. Like with operational monitoring, access to the interface is restricted so that only the X-Road operator can access the data of all Security Servers. Regular members can access their own Security Servers’ data only.

A common approach is to use existing monitoring tools and platforms to centrally store, analyse and visualize the technical monitoring data, e.g., Elasticsearch and Kibana. However, an X-Road-specific component is needed to read raw data from Security Servers. The Finnish Digital Agency has implemented such a component, and they've published it on GitHub under the MIT license. Currently, NIIS doesn’t provide a central environmental monitoring component for X-Road that could be used to monitor the ecosystem's health.

Where do I find the specifications?

Service management portal, service catalog, reporting and metrics, and technical monitoring building blocks offer capabilities that aren’t currently provided by the X-Road core. Those capabilities are not required when setting up a new X-Road ecosystem, but they certainly make operating and developing the ecosystem easier. First and foremost, they provide the X-Road operator with additional tools for informed decision-making and automating management processes.

The building blocks mentioned in this blog post are described on a conceptual level, and there's no formal specification for them. Therefore, every implementation of the building blocks is different and may not always provide the same set of features. However, how the building blocks are technically connected to X-Road must be based on the X-Road protocols and interfaces. Therefore, replacing one implementation with another should be possible if connections to other backend systems are ignored.

Currently, NIIS provides the implementation of the reporting and metrics building block in the form of X-Road Metrics. Also, implementations of the service catalog and technical monitoring building blocks are available as open-source. The service management portal is the only building block that doesn’t have open-source implementations available. More implementations are likely to become available in the future, and the technical specifications of the concepts will be defined in more detail.

The Message Room Concept in Practise

This is a series of blog posts about the Message Room concept. The first part provides an introduction to synchronous and asynchronous data exchange. The second part concentrates on life-event-based services and potential implementation alternatives. Three alternative implementation approaches are discussed in more detail in the third part.

In my previous blog post, I covered five different ways how the Message Room concept could be implemented. In this blog post, I will explain in more detail how NIIS has approached three of the five alternatives at a more practical level. During the last two years, NIIS has conducted multiple research and development activities that have concentrated on alternatives 1-3 (built-in, integrated, connected).

Integrating Apache Kafka into X-Road (integrated)

In collaboration with the University of Tartu, NIIS conducted a research project on supporting event-driven architecture in the context of X-Road. The study consisted of two parts that were completed in 2020-2021. The final report is available in the X-Road Document Library.

The first part of the project produced a report (requirement analysis and feasibility study) and a proof-of-concept implementation which brought a subset of Apache Kafka's capabilities into X-Road. The second part studied Apache Kafka's integration into X-Road further and explored topics that must be covered in a production level integration, for example, high availability, authentication, access rights management, and service discovery. Implementing Kafka management operations in X-Road was out of the project’s scope.

Image 1. Integrating Apache Kafka into X-Road (integrated).

The integration is based on the idea that the existing X-Road protocols are used for a handshake to establish an asynchronous communication channel between the message exchange parties. The asynchronous communication is implemented by the new XGate add-on developed in the project. First, the service consumer sends a regular X-Road request to the service provider using the X-Road Message Protocol for REST (1.). The request is transmitted between the Security Servers using the X-Road Message Transport Protocol. The service provider receives the message, instantiates an interface for asynchronous communication, and adds routing information in the response (2.). The service consumer reads the routing information from the response, establishes a connection to the interface (3.), and reads data from it (4.). More detailed description of the implementation is available in the final report.

The adapter service approach (connected)

X-Road-Kafka Adapter is an adapter component that connects Apache Kafka topics to X-Road. The Adapter supports both producing and consuming data over a simple REST API. The producers publish data to a topic, and the consumers poll the topic and pull data from it. The Adapter sits between the Security Server and Apache Kafka and converts messages between the X-Road message protocol for REST and Kafka protocol. However, the Adapter doesn’t support streaming. 

Image 2. The adapter service approach (connected).

In practice, both producers and consumers may use Kafka's native API directly, or alternatively, they can use a REST API provided by the Adapter over X-Road. In real life, producers and consumers owned by the organisation running Kafka would probably use the native API, whereas external producers and consumers would connect to Kafka through X-Road. However, all the Kafka management and maintenance operations must be done using the native API since the Adapter only supports a limited subset of operations for producing and consuming messages.

More detailed information about the Adapter is available on GitHub. The Adapter is currently on a proof-of-concept level and requires further development before it can be used to run production workloads. The source code is licensed under the MIT open-source license and anyone interested in the Adapter is welcome to contribute to its development.

The X-Road way (built-in)

NIIS is currently working on a proof-of-concept (PoC) level implementation of the built-in approach. The goal of the PoC is to implement the Message Room concept as a Security Server proxy add-on (like messagelog, metaservice, op-monitoring, etc.). In that way, the implementation is modular and can be installed on selected Security Servers only. However, the add-on needs to be installed only on Security Servers that are acting as publishers. No code changes are required on Security Servers acting as subscribers, which means that all existing supported Security Server versions can act as subscribers.

It must be noted that the features included in the PoC are just a narrow subset of potential features of a production-level implementation. The PoC aims to test the concept with minimum viable features, and therefore, many features and functionalities are left out on purpose. The PoC implementation covers the following functionality:

• Push-push publish/subscribe model.

  • Publishers push messages to a Message Room.

  • A Message Room pushes messages to subscribers - subscribers don't need to poll the Message Room.

• One publisher per Message Room.

• One publisher Security Server per Message Room.

• Multiple subscribers per Message Room.

• Message Rooms are public - anyone can subscribe to them.

• Security Server provides the required interfaces to:

  • Publish messages to a Message Room.

  • Subscribe to a Message Room.

  • Unsubscribe from a Message Room.

• Support for federation.

• Message Rooms are content-type and payload agnostic.

  • Messages that are published to a Message Room can be of any content-type, e.g., XML, JSON, text, binary, etc.

• All X-Road security guarantees (except access control for Message Rooms) are supported.

The following restrictions apply to the PoC implementation:

• Pulling data from a Message Room is not supported.

  • In push-pull model publishers push messages to a Message Room, and subscribers pull the messages from the Message Room.

• Private Message Rooms are not supported.

  • It's not possible to control who's allowed to subscribe to a Message Room.

• Internal load-balancing is not supported.

  • It's not possible to publish messages to a Message Room from multiple Security Servers.

  • A Message Room is coupled with a single Security Server.

• No error handling.

  • If the recipient is not available, the message is lost.

  • If publisher's Security Server crashes, (some) messages are lost.

• No support for service discovery.

  • There's no automated way to discover what Message Rooms are available.

  • Potential subscribers must know the subsystem code of the Message Room when subscribing to it.

• No changes to the Security Server UI and management REST API.

  • If new configuration items are introduced, they're values are configured using configuration files or database queries.

• Subscribe and unsubscribe interfaces support only REST. SOAP is not supported.

The Message Room add-on

The Message Room PoC is implemented as a Security Server add-on.

Image 3. The X-Road way (built-in).

The add-on includes three new interfaces:

• Publish - publish messages to a Message Room.

• Subscribe - subscribe to a Message Room.

• Unsubscribe - unsubscribe from a Message Room. 

The publish interface is used by internal clients to publish messages to a Message Room. The publisher of the message is defined using the "X-Road-Client" HTTP header. The message body is fully data format-agnostic, just like the REST interface. The Message Room where the message is published is the same as the client subsystem. However, only subsystems with a special Message Room status can be used as a Message Room. 

The subscribe and unsubscribe interfaces are used by external clients to manage their subscriptions to a Message Room. The subscribe interface is used to subscribe to a Message Room. Similarly, the unsubscribe interface is used to unsubscribe from a Message Room. In the PoC implementation, the interfaces are accessible by anyone, and there's no access control to them. For example, listMethods and listAllowedMethods metaservices work in the same way.

The message body of the subscribe interface must contain the service ID where messages published to the Message Room are sent. Also, the service must be owned by the same client who sends the subscribe message. The same applies to unsubscribe requests, too - the sender of the request must be the owner of the service specified in the request body. Also, subscribers must allow the publisher to send messages to the service specified in the subscribe message.

Image 4. The message flow using the built-in approach.

The basic message flow for publishing messages is explained in the diagram above:

1. A publisher publishes a message to a Message Room using the publish endpoint.

2. The proxy stores the message in memory and returns an acknowledgment message to the publisher.

3. A scheduled Message Room Processor reads new unprocessed messages from memory and reads the subscriber service IDs from the serverconf database.

4. The Message Room Processor sends the message to the subscribers as a regular X-Road message. For example, if there are 5  subscribers, 5 messages - one for each subscriber - are sent. The Message Room subsystem is used as the sending client, and the messages are signed with the publisher member's signing key. Each message is logged independently by the proxy. Steps 6-9 are repeated for each subscriber. If there are no subscribers, the message is removed without further processing.

5. The proxy sends the message to a subscriber.

6. The subscriber's Security Server processes the message and forwards it to the service (subscriber) defined in the request.

7. The service returns a confirmation that it has received the message.

8. The confirmation is returned as a regular X-Road response.

9. The Message Room Processor receives the response. The content of the response is ignored. However, if the response contains an error, the error is logged in the proxy log.

What’s next?

Based on the results provided by different approaches, the built-in approach has proven to be the most prominent. It can offer the same security guarantees that X-Road currently provides, including authentication, identity management, message logging, signing, and timestamping. Also, it can be expanded to a decentralized publish-subscribe implementation that enables many-to-many communication without a centralized message broker. Therefore, the next step is to test the PoC implementation of the built-in approach with a couple of selected use cases in Estonia and Finland during the first half of 2022. More information about the potential use cases is available in the previous blog post by Petri Kettunen.

Nevertheless, the NIIS members have not decided whether a production-level implementation of the Message Room concept will be included in X-Road. The PoC use cases implemented in Estonia and Finland will provide valuable information to support the decision-making. Once the PoC use case implementations have been completed, a decision regarding the production level implementation will be taken by the NIIS members. Meanwhile, NIIS participates in the implementation of the PoC use-cases and continues to develop the concept further.

The Message Room Concept Implementation Alternatives

This is a series of blog posts about the Message Room concept. The first part provides an introduction to synchronous and asynchronous data exchange. The second part concentrates on life-event-based services and potential implementation alternatives. Three alternative implementation approaches are discussed in more detail in the third part.

The Message Room concept was first introduced by Kristo Vaher, the government CTO of Estonia, in his paper Next Generation Digital Government Architecture in 2020. However, in the paper, the name X-Room was also used about the concept. In the latter design work conducted by NIIS, the name Message Room has been used, and therefore, I'm going to use it from here on.

According to the Next Generation Digital Government Architecture paper, the Message Room concept provides different administration sectors with an asynchronous communication channel that is the technical enabler for implementing life event-based services. In practice, the implementation would follow the publish-subscribe pattern, and it would be based on X-Road, including all X-Road's existing security guarantees. In that way, the existing infrastructure and data exchange ecosystem are utilized instead of reinventing the wheel and building everything from scratch.

What are life event-based services?

The idea behind life event-based services is that an event happens in a person's life and is registered by an information system. Then the information system notifies other information systems about the event that have registered their interest to receive updates on that specific event type. Based on the event, various processes are then triggered to provide the citizen with services related to the event. In this way, it is possible to offer or suggest services to citizens automatically instead of the citizens having to apply for them separately. For example, social benefits could be automatically offered to parents when a child is born.

What is a Message Room?

Generally, Message Room is an asynchronous messaging concept that decouples message producers and consumers and enables publishing messages and events to multiple consumers. Instead of sending messages directly between two information systems, message producers publish their messages to a Message Room with any number of consumers. The number of message publishers is not limited either, and a single Message Room can have one or more publishers.

Image 1. The Message Room concept.

A Message Room can be public or private. Anyone can publish and/or consume messages from public rooms, but private rooms can be accessed by authorized parties only. It is also possible that only authorized parties can publish messages, but consuming is allowed for anyone or vice versa.

Technically, a Message Room is an implementation of the publish-subscribe communication pattern. In other words, a Message Room can be considered a topic with multiple subscribers. A Message Room enables one-to-many and many-to-many communication.

Implementation alternatives

From a technical perspective, there are different ways to implement the Message Room concept. Every alternative has its pros and cons, and also the constraints and supported features vary between the alternatives. The implementation alternatives can be divided into five high-level categories:

• built-in

• integrated

• connected

• standalone

• standardization.

It must be noted that the categories are not mutually exclusive, and they're partly overlapping. A potential outcome might very well be a combination of multiple categories. 

Built-in

The idea of the built-in approach is that required features are implemented around the existing X-Road concepts, components, and protocols. In practice, it means extending the current protocols, introducing new entities, and expanding the functionalities of different components. Everything is designed and implemented using the "X-Road way," which means that the implementation provides all the same security guarantees that are provided to synchronous messages. At the same time, the implementation also has to deal with the constraints caused by the same security guarantees.

Integrated

Integrated means taking an existing open-source messaging solution (e.g., Apache Kafka, RabbitMQ) and integrating it into X-Road. In this way, the existing solution provides most of the messaging features, and there's no need to implement them separately. Some changes/additions to the X-Road protocols are likely to be required, but the data exchange inside a message room is based on the protocol(s) supported by the selected solution. Also, the integration covers most of the management-related tasks so that they can be completed using X-Road provided components, e.g., the Security Server UI and management API.

However, integrating the solution into X-Road requires potentially a significant effort, and there's a tight coupling between X-Road and the selected solution. Another downside is that X-Road becomes highly dependent on an external solution which future development and roadmap are out of NIIS's control. Also, it's very likely that providing all the same security guarantees provided by synchronous messages isn't possible, e.g., signing and timestamping all the data processed by a Message Room.

Connected

The connected approach uses X-Road to establish a connection between the data exchange parties and implement the actual data exchange through an external channel outside of X-Road. In this case, X-Road provides a secure channel for the initial handshake that includes exchanging the details of the external channel.

The handshake is a regular X-Road message in which headers and/or body include the required details. The external channel doesn't directly connect with X-Road, so it may use any data exchange protocol. In this way, the approach is not coupled with any specific solution or technology, and it can be used to support multiple different solutions and use cases. For example, different messaging solutions like Apache Kafka, Rabbit MQ, and Apache ActiveMQ could all be supported. However, the external solution is managed independent of X-Road, and all configuration tasks must be done using the native interfaces and tools provided by the solution. Also, the X-Road security guarantees are provided for the handshake but not for the data exchange.

Standalone

Standalone means implementing Message Rooms as a standalone, fully independent solution that can be connected to X-Road. In this way, the solution can be used together with X-Road, but also without it. Connecting the solution to X-Road could be done using the integrated or connected approach.

An existing open-source messaging platform, such as Apache Kafka, could be taken as a basis and developed further if needed. No additional development is required in the best case, and an existing solution can be used as-is. Also, the solution could be implemented using an existing standard or a set of standards that would support interoperability on a broader scale.

Standardization

Standardization is about creating a protocol stack based on a standard or a set of standards that define all the aspects of the communications required by a Message Room. In practice, it means leveraging existing standards and creating new ones in case they are needed. This approach would make Message Rooms both technology and solution agnostic. The first step would be to study whether suitable standards that meet the requirements already exist and participate in their development. For example, the Message Room concept could be connected to data spaces, e.g., an asynchronous communication method within a data space and across different data spaces.

Requirements for the implementation

In theory, all the described implementation alternatives are technically feasible, but there are various differences when looking into them in more detail. Eventually, the choice between the alternatives boils down to the expectations, requirements, and constraints for the Message Room implementation.

One of the recognized requirements for the implementation is a reuse of existing infrastructure and X-Road principles. In practice, it means utilizing X-Road's existing security mechanisms, including authentication, identity management, message logging, signing, and timestamping. Also, the Message Room concept implementation should be based on a decentralized architecture, and therefore, it must not include any centralized components.

All the Message Room-related research and development activities conducted by NIIS have concentrated on categories 1-3 (built-in, integrated, connected) since they directly include X-Road and, therefore, provide the most logical starting point for the implementation. The different activities will be covered in more detail in my next blog post.

Synchronous or Asynchronous Messaging?

The previous blog post by Petri Kettunen provided insights on the Message Room use case study conducted by the University of Helsinki. This is the first part of a series of blog posts about the Message Room concept, and it provides an introduction to synchronous and asynchronous data exchange. The second part concentrates on life-event-based services and potential implementation alternatives. Three alternative implementation approaches are discussed in more detail in the third part.

In 2020, NIIS conducted an X-Road feature study to identify the needs and challenges of X-Road operators and members in Estonia, Finland, and Iceland. Information was gathered via 20 interviews (26 participants) and supplemented with an online questionnaire in Estonia (29 respondents). In addition, two innovation workshops were organized to collect further details on selected topics. 

Messaging patterns were one of the topics included in the study. Currently, X-Road only supports synchronous request-response messaging. Still, the need for asynchronous messaging had been recognized based on user feedback and some new use cases, such as proactive life event-based services. Therefore, additional information and insights on the actual needs and requirements were needed to make more concrete plans regarding the next steps.

Synchronous and asynchronous messaging

An excellent way to understand the difference between synchronous and asynchronous messaging is to compare a phone and an email. A phone call is synchronous – both parties must be available for it, and you have to wait for an answer when asking questions on the call. Instead, an email is asynchronous – you can send an email when you want, and the recipient is free to choose when to read it and respond.

Currently, X-Road is based on synchronous communication suited for real-time data and document exchange. Synchronous data is exchanged via request-response pairs. On a simplified level, a service consumer sends out a request and then waits for a service provider's response. When the request is sent, the service consumer waits for the response until it is received or a timeout occurs. Synchronous messaging creates a tight coupling between the data exchange parties since the consumer is always dependent on the availability and performance of the provider. Also, changes on either side easily break down the connection.

In the case of asynchronous messages, a service consumer sends a request and continues processing other tasks. The service provider sends a response later once it has processed the request or, depending on the type of asynchronous messaging pattern, it may not send a response at all. Asynchronous messaging creates only a loose coupling between the data exchange parties, making them less dependent on each other.

From message exchange patterns to communication patterns

In practice, there are several message exchange patterns how asynchronous messaging can be implemented. Asynchronous messaging can be one-way or two-way, and it can be based on different combinations of push and pull, for example:

• send a message with no response (push)

• send a message with no response (pull)

• send a message with an asynchronous response (push and pull)

• send a message with an asynchronous response (pull and push).

The asynchronous message exchange patterns and their different combinations are used in various communication patterns. The publish-subscribe and message queue communication patterns were included in the X-Road feature study together with the asynchronous request-response message exchange pattern.

Asynchronous request-response

A service consumer sends a request and continues processing with other tasks. The service provider sends a response later once it has processed the request. The consumer may include in the request a destination for the provider to send a message with the response.

Publish-subscribe

A service provider publishes messages (publisher), and any number of service consumers will receive them (subscribers). Service consumers that are interested in a publisher’s messages “subscribe” to a predefined channel that they know publishers will be sending messages to. When an event happens, a message is sent to all the service consumers who have subscribed to the channel. Many publishers and subscribers can use the channel, and each message is delivered to all the subscribers.

Message queue

A message queue is an asynchronous communication channel where service producers and consumers do not interact simultaneously. Service producers push messages onto a queue, and consumers read the messages from the queue. Only one consumer gets a particular message, no matter how many consumers read messages from that queue. Many producers and consumers can use the queue, but each message is processed only once by a single consumer.

What do the users truly desire?

According to the X-Road feature study results, the publish-subscribe pattern is the most preferred option for implementing life-event-based services. Also, according to the MoSCoW methodology, it’s a MUST together with asynchronous messaging. Instead, message queues and data streaming were mentioned in the study as well, and they were considered essential by many participants. According to the MoSCoW methodology, they were both SHOULD.

After the feature study, interactive innovation workshops were organized with participants from Estonia, Finland, and Iceland. According to the results, the publish-subscribe pattern got the highest priority in expanding X-Road's current message exchange capabilities. Also, the results strengthen the image of the pattern's role in implementing the proactive life event-based services. Therefore, it is logical to concentrate on the publish-subscribe communication pattern. However, it doesn't mean that the other alternatives are forgotten or mutually exclusive. In the long term, different options remain open even if the publish-subscribe pattern is prioritized first.

Also, the goal is not to replace the currently supported synchronous request-response pattern with asynchronous messaging. Instead, the aim is to extend X-Road’s messaging capabilities with asynchronous messaging.

Message Rooms Use Case Study: Should X-Road Support Asynchronous Messaging?

Message Rooms is a proposed X-Road publish/subscribe concept that decouples message producers and consumers for data exchange in interconnected information systems. In the University of Helsinki (Department of Computer Science) contract research project, the need and feasibility of asynchronous messaging with the Message Rooms concept were analyzed with respect to its potential benefits and implementation realization. The analysis was based on selected use cases.

This research project aimed to recognize, document, and analyze the intended use cases in Estonia, Finland, and Iceland. Initial sources of the use cases included in the study were the X-Road Feature Study (2020), the Estonian KrattAI, and the Finnish AuroraAI. The expected result of the research was to provide to the NIIS members information for informed decision-making regarding the further steps and the potential continuation of the Message Rooms related work. The implementation of the Message Rooms had not been decided yet, but several implementation alternatives were under comparative discussion.

Background

In the prior X-Road Feature Study (2020), synchronous request-response messaging was suggested to be a MUST. However, also asynchronous messaging was a MUST. In general, the publish and subscribe pattern was a MUST since it is the most preferred option for implementing life event-based services.

In the Feature Study, particular business/use cases were not analyzed in detail. “Message Rooms” or “X-Rooms” were not explicitly mentioned. Overall, asynchronous messaging was concluded to mean a paradigm shift in the context of X-Road.

This Use Case research started with getting an overall understanding of the X-Road context and the Message Room problem space. As a result, a (partial) Message Rooms concept map was compiled. It includes such key concepts as Service capabilities, Data exchange capabilities, Asynchronous loosely coupled communication, Asynchronous messaging, Synchronous communication between services, Publish/subscribe messaging model, Event-driven architectures, Service endpoints, Registry-based data exchange, Cross-border data exchange, and Flexible distributed government service architecture. The wide, even partial concept map suggested that the overall decision-making space has many technical and organizational interrelationships, dependencies, and constraints.

Considering the X-Road usage in the participating countries, Estonia was considered to be "fully X-Road". In Finland, the Suomi.fi Data Exchange Layer ("Suomi.fi-palveluväylä") was noted to be mandatory (obligation to use) for public administration organizations ("Palveluväylän käyttövelvoite"). Notably, Finland's and Estonia's data exchange layers were interconnected in 2018. Iceland was not applicable, and the country was excluded from further analysis.

Use Cases Exploration

In the X-Road Feature Study, most interviewees reported seeing the value of asynchronous communication. However, their organisations did not have specific business cases for asynchronous message exchange at that time.

With that heading, the research problem was defined as to justify implementing the Message Rooms by discovering asynchronous data exchange use cases between certain public sector agencies based on the proposed Message Rooms concept. The context was the X- Road users in Estonia and Finland.

As for the research approach, two different angles to the use case discovery was recognized:

1. Examine some existing service information systems identifying such information exchanges, which could, in principle, have Message Rooms based implementations.

2. Identify opportunities for Message Rooms based on implementations in some new service information systems designs.

In practice, the first alternative was seen as more appropriate for the time being – given the limited schedule and resources allowed for the contractual research work.

For the data collection, several expert stakeholder interviews were conducted (in September–November 2021). The Estonian interviewees were governmental digitalization experts. In Finland, they represented the Tax Administration, the Digital and Population Data Services Agency, and the governmental AuroraAI program.

For initial probing, an architectural design scenario was presented. The scenario was as follows:

1. Some change occurs in some information systems (service) (e.g., a citizen moves to a new home town).

2. Interested information systems (information producers/consumers) receive event notifications about the change.

The following points were then interrogated: How typical is this scenario? What particular cases are there now / in the (near) future? What are the Information Provider(s) and the Information Consumers/Users?

Several prospective use cases were examined in Estonia and Finland. The Death Of a Closely Related Person was acknowledged as the most viable case that could, in principle, be implemented based on Message Rooms. It was indicated to be so both in Finland and Estonia.

In that use case, a doctor determines the death and registers it to the Population Information System with an application. Government officials and different organizations then receive the information immediately. With respect to asynchronous messaging, this maps into the following:

1. The hospital information system will announce the fact (i.e., publish).

2. Population registry, employment registry (n+1) will listen (i.e., subscribe and receive notifications).

Potential Use Cases & Clues

All in all, we recognized a range of potential use cases and prospective avenues for other cases. These include the other citizen life events similar to the Death Of a Closely Related Person case, such as “Birth of a child”. Such cases may be equal with respect to asynchronous information exchanges.

In Estonia, there are many needs for the state's central event service to communicate with the local government event service. The local government finds out that an event (e.g., a death, birth, etc.) has occurred. Subsequently, they could immediately provide services accordingly based on this event information. The forthcoming Government Virtual Assistant #bürokratt will initially involve three agencies (Police and border control, National library, Consumer protection agency) and at least eight more agencies planned with probably thousands of daily users. It also provides services.

Another Estonian case candidate is related to drugs prescription. In that, a need for new drugs prescription is first notified. A consent to other people to purchase the drugs is then granted, and they are then notified of the consent.

In Finland, one of the services where X-Road is being utilised, is Suomi.fi Messages (”Suomi.fi-viestit”) – a service provided for citizens to communicate with authorities. It was opened in 2017, and currently, it has some 750 000 users. Public administration organizations in Finland are obliged to support the service.

In the Suomi.fi Messages message exchange system, when a new message is sent from government agencies to the message box of a citizen, a notification is sent to the citizen's email address. However, currently, such notification messages are only sent by the Tax Administration.

Another potential area in Finland is the search service of the Population Information System (VTJ). Currently, the VTJ query interface is synchronous. The consumer organization gets information (e.g., personal data) from the Population Information System in real-time forms on a continuous (not on a one-off) basis and individually (not in large batches).

In Finland, one more prospect is the Tax Administration Suomi.fi service interface vero_tipa_server_prod ("Veron tietopalvelurajapinnat"). That subsystem provides query services for tax information. However, currently, the services are intended only for certain organizations.

Furthermore, in the Finnish AuroraAI program, additional needs for asynchronous messaging have been recognized: Events trigger activities in the service network. Such new developments are planned for Q1–Q2/2022.

In addition, there are many ongoing and emerging large-scale governmental information systems development projects in Finland. For example, in the new centralized national digital register and data platform for the built environment ("RYTJ"), the information producers send (push) information from their own systems, and the information users retrieve it. Additional asynchronous notification support could be considered.

Conclusions

Overall Findings and Observations

Based on the research work described above, we have drawn the following overall inferences and propositions:

• What are their really essential, fundamental questions (problem definition)? Is it more about data/information or services?

• What level(s) of the technology stack(s) are most critical (problem-solution)? When is it the transport layer?

• What/where are the most significant needs and most considerable constraints? Do they concern about the messaging technology or more about the information systems, services, and business processes?

Suggestions for Future work

For further (research) work, we suggest the following:

• How typical are certain data exchange patterns in current and forthcoming systems? Such patterns could be recognized, for example, from different chatbot services. If such typical patterns can be recognized, useful common asynchronous communication design patterns could be developed for reuse.

• Identify and describe systematically relevant (future) data exchange scenarios. Assess whether message rooms (asynchronous communication) would be appropriate architectural realizations for the scenarios. For example, the Architecture Tradeoff Analysis Method (ATAM) could be used.

Considering use case discovery and analysis, there are two spheres: current X-Road-based information/service systems and new ones. For the former, would they be willing and able to change to asynchronous communications (Message Rooms) based implementation? For the latter ones, what asynchronous communications (Message Rooms) based solution opportunities would there be in the IS under development / planned?

In more general, considering (governmental) IS analysis and design, the following factors and issues should be assessed and taken into account:

• In which service/information systems would asynchronous data exchanges be needed and be useful? What are the information and data processing needs?

• Would asynchronous communications (Message Rooms) based design be the most fitting (even optimal) choice? What is the feasibility (e.g., cost of modifying existing implementations)? What specific constraints are there (e.g., legal limitations such as SSN policies in different X-Road countries)?

---

The author Petri Kettunen (Docent, University Researcher) joined the University of Helsinki, Department of Computer Science in January 2010. Since then he has been working on a wide range of software engineering research topics in different industry-academia collaboration programs and projects.

Towards a sustainable digital future with X-Road

The EU is fighting climate change and has planned to further cut emissions by 2030. By 2050, Europe aims to become the world's first climate-neutral continent.

NIIS internal primary goal is to achieve carbon neutrality by 2030. With our flagship product, X-Road®, we follow the UN 17 Sustainable Development Goals, and X-Road contributes to specific goals directly or indirectly. X-Road also fulfils the criteria of a Digital Public Good, and it's approved as such by the Digital Public Goods Alliance.

NIIS aims to reduce the environmental impact of X-Road ecosystems and has an ambitious goal that X-Road is the most sustainable data exchange solution by 2030.

Let's look into the steps taken so far and the subsequent phases towards the goals.

How could NIIS become carbon neutral by 2030?

NIIS develops software, so electricity is required for our operations and using the end products. Currently, this involves non-renewable fossil fuels, but we aim to move towards renewable energy at NIIS and decrease the energy consumption of our organisation.

The impacts and dependencies on environmental sustainability happen in both primary and support activities of the NIIS value chain. Software development and procurement are the most efficient functions for NIIS in reducing harmful effects. Our value chain support activities include more aspects such as our office premises, travelling, and other procurement and consumption subjects, which require a mitigation strategy.

Our focus so far has been on assessing impacts on environmental sustainability. To improve our performance in social sustainability, we consider selecting tools and frameworks such as KPIs for linking impacts and dependencies to human and social capital.

Sustainability is included in NIIS values. Our sustainability goals shall be embedded in our strategic objectives during this year. Consequently, incentives for achieving the strategic objectives cover also our sustainability goals.

NIIS can better recognise the planetary boundaries and become carbon neutral by 2030. Generally, we must not prioritise mitigation or adaptation strategy but rather look into the NIIS value chain and identify the possible actions.

How could X-Road become the most sustainable data exchange solution?

We develop software for digital governance infrastructure, which is highly dependent on electricity. The rise in electricity production by renewals, climate change and other contributing factors in the energy sector will increase overall electricity costs also in the future. NIIS shall continue to support reducing electricity consumption in our users’ infrastructures.

X-Road users consume natural resources also through the hardware utilised for running software. The manufacturing of hardware involves mining minerals and metals that are becoming difficult to find. Reducing the number of hardware required to operate the software is another way to impact positively. Therefore, running X-Road on the cloud is the first step for any X-Road operator willing to reduce negative impacts.

NIIS recently completed the first project in which we assessed the energy consumption of the access point component (Security Server) of X-Road. We aim to significantly reduce energy consumption by covering the whole X-Road ecosystem and operations. We have an ambitious goal of making X-Road the most sustainable data exchange solution in digital government by 2030. It's worth adding that this goal is not limited to environmental sustainability only.

We have identified specific SDG's with X-Road contributions to various areas of sustainability. These include SDG's for which we have evidence about direct contribution in the form of a project, platform, network, ecosystem, policy or feature, that involves X-Road. We don't aim to increase the number of contributed SDG's – unless it happens naturally – but rather strengthen the activities in the existing SDG's. We aim to work long-term and support the initiatives utilising X-Road.

From 2022 onwards, NIIS will incrementally introduce new methods for reducing energy consumption in X-Road environments. We cannot guarantee any schedule for the software's sustainability enhancements at this early research phase. Still, we will do our best to advance sustainability and engage different stakeholders in work.

Ville Sirviö is the CEO of NIIS. He studied leading sustainable organisations at the Saïd Business School, University of Oxford, in 2021.

There’s No Distributed Ledger Technology (DLT) in X-Road

In 2018 I wrote a blog post about blockchain and X-Road. The aim of the post was to explain that there's no blockchain technology in X-Road, unlike multiple writings had been claiming. Despite the facts provided in the post, still today, X-Road is often called a blockchain or distributed ledger technology (DLT) based solution. X-Road has experienced several major changes since 2018, but its relationship to blockchain hasn’t changed – there’s still no blockchain technology in X-Road.

My earlier blog post already explained the difference between X-Road and blockchain. But what is DLT, and how does it differ from blockchain? And most importantly, what’s the relationship between DLT and X-Road? Let’s find out!

Distributed ledgers

Essentially, DLT or a distributed ledger is a distributed database spread across multiple nodes that all hold an identical copy of the data stored in the ledger. The data is replicated, shared, and synchronized across all the nodes, and the nodes update themselves independently. When the ledger is updated, the nodes use a consensus algorithm to agree on which copy is correct. Once the nodes reach a consensus, they all update themselves with the new copy. In other words, the consensus algorithm enables the nodes to agree on the state of the ledger.

Typically, distributed ledgers are decentralized since they are based on a distributed architecture and don't have centralized governance. However, there are distributed ledgers that have some level of central administration. Therefore, it can be argued not all the distributed ledgers are entirely decentralized.

A distributed ledger may be permissionless, permissioned, or hybrid. Permissionless ledgers are public, and everyone can participate in the network and access the data stored in the ledger. Instead, permissioned ledgers are private, and they only allow trusted nodes to join the network. In private ledgers, the information is available to a specific group of permitted participants, and a network operator decides who is allowed to join the network. In addition, there are also hybrid ledgers that are a combination of permissionless and permissioned networks, e.g., anyone can read data from the ledger, but only authorized nodes are allowed to write data to the ledger.

Distributed ledgers typically have several properties, including but not limited to immutability, transparency, and trust. All the transactions in the ledger are immutable since once a transaction exists in the ledger, nobody can change it. Distributed ledgers are transparent because all the nodes have the same copy of the data. Also, distributed ledgers enable direct trust between parties that don't necessarily trust each other. Immutability and trust are accomplished through cryptography and digital signatures.

There are various types of distributed ledgers that implement the properties differently and have their characteristics. Different kinds of ledgers include blockchain, Directed Acyclic Graph (DAG), Hashgraph, and Holochain.

Sometimes distributed ledger or DLT and blockchain are used as synonyms. However, as we have just seen, there are different types of distributed ledgers, and blockchain is just one type of distributed ledger. Blockchain is a data structure of blocks linked to one another via cryptographic hashes, but distributed ledgers don’t require such a structure or chain.

In general, blockchains are distributed ledgers, but not all distributed ledgers are blockchains. Therefore, distributed ledger and blockchain shouldn’t be used as synonyms.

Is X-Road a distributed ledger?

X-Road and distributed ledgers are both based on decentralized architecture. Distributed ledgers don't typically have central administration, which means that they're entirely decentralized. Instead, X-Road is technically decentralized, but an X-Road ecosystem is always built around a centralized governance model managed by the X-Road operator.

A fundamental difference between X-Road and distributed ledgers is that distributed ledgers are decentralized databases for storing data, while X-Road is a decentralized solution to exchange data. All the distributed ledger nodes hold the same copy of the data, and they agree on the latest version using a consensus algorithm. Instead, in X-Road, data is exchanged between two data exchange parties, and other parties do not have access to it. Also, X-Road nodes do not permanently store data - they only act as secure proxies. All the nodes of an X-Road network have their own sequence of transactions that are not shared with any other nodes – not even in a Security Server cluster. Therefore, there’s no need for a consensus algorithm in X-Road.

Based on the above reasoning, it's evident that X-Road is not a distributed ledger. Comparing X-Road and distributed ledgers is like comparing apples to oranges. However, under the hood, both distributed ledgers and X-Road use the same mechanisms, cryptography and digital signatures, to secure their operations – they’re just applied differently.

Is distributed ledger technology used in X-Road?

Distributed ledger technology is not currently used in any areas of X-Road. The data exchange always happens between two parties, and the data is not shared with other parties of the X-Road ecosystem. Even in a Security Server cluster with an external load balancer where all the nodes share the same identity, the exchanged messages are Security Server specific. Only configuration is shared between the nodes. Consequently, the logs produced by different nodes of the cluster are unique since each message is processed by one node in the cluster only. Also, the logs are stored on the nodes only temporarily - once they’ve been archived, they are removed. Therefore, there aren't currently features that would directly benefit from distributed ledgers when it comes to data exchange. Although, that doesn't mean that some additional features that aren't directly related to data exchange couldn't be implemented using distributed ledgers.

However, some other aspects of X-Road could potentially benefit from distributed ledger technology in the future. For example, how configuration details are managed on the Central Server and distributed to the X-Road ecosystem through global configuration is a potential topic to study further. Also, when thinking about X-Road’s trust model and how organizational identities of X-Road members are managed, self-sovereign identity (SSI) together with decentralized identifiers (DIDs) and verifiable credentials could provide some exciting alternatives in the future. But that’s a topic for another blog post.

All in all, X-Road’s isn’t currently based on distributed ledger technology nor blockchain. When it comes to using distributed ledger technology in X-Road, even if something can be done using distributed ledger technology, it doesn't automatically mean that it should be used. A common principle in the X-Road development is to choose the technology that’s the best fit for the job instead of selecting the most popular alternative.

Protecting Data at Rest in X-Road 7

One of the core features of X-Road is to protect data in transit, and X-Road includes several mechanisms to protect data when it travels between the data exchange parties. Even if X-Road is not a data storage solution, it doesn’t mean that the Security Server wouldn’t store any sensitive data, at least temporarily. Therefore, X-Road 7.0.0 will introduce new security features to protect data at rest on the Security Server. The new features are:

• encrypt backup files (opt-in)

• verify the integrity of backup files before running a restore

• encrypted message payload in message log database (opt-in)

• encrypted message log archives (opt-in)

• group message log archives by member or subsystem (opt-in).

 This blog post gives an overview of the new security features and their key characteristics.

Common design principles

The new data protection features provide the possibility to encrypt and sign specific data stored on the Security Server. By default, encryption is turned off, and the Security Server administrator can manually enable it. All the encryption-related configuration operations require shell access to the Security Server.

The new data protection features have been implemented using the GNU Privacy Guard (GnuPG) – an open-source implementation of the OpenPGP standard as defined by RFC4880. All operations related to backup files and message log archive files have been implemented in an external GnuPG process. Instead, the message log database encryption has been implemented in Java code.

Image 1. Encryption keys that are used to protect data at rest on the Security Server.

The required keys are stored in GPG keyrings, and Security Server's internal key (1) used by default is generated automatically. The Security Server administrators can manually configure additional and member-specific keys (2, 3, 4). All the new encryption keys are illustrated in image 1.

Configuration backup encryption

Security Server configuration backups contain sensitive information, such as database connection credentials, private keys, etc., and therefore, they should be protected from unauthorized access. Starting from version 7.0.0, the Security Server supports signing and encrypting the backup files.

The backups are always signed, but backup encryption is initially disabled. When encryption is enabled, backup files are encrypted when they are created and stored on disk encrypted. It applies to both automatically created and user-created backups. When it comes to user-created backups, the configuration applies to Security Server UI and REST management API.

When backup encryption is enabled, the backups are signed and encrypted using the Security Server’s automatically generated internal key pair (1). In addition, the Security Server administrator can upload additional keys (2) to the Security Server that are used to encrypt the backups together with the internal key. In practice, the backups are encrypted with the internal key and all additional keys. The backups are always signed with the internal key.

During restore, the Security Server verifies the consistency of backup files automatically. However, if the Security Server’s internal key pair is lost, automatic verification is no longer possible. In that case, the Security Server administrator can restore the decrypted backups from the command line with appropriate options that enable skipping integrity verification.

Configuring additional encryption keys is strongly recommended since the Security Server administrator can use them to decrypt configuration backup files in a situation where the internal key pair is lost. Without additional keys, the encrypted configuration backups are unusable in such a situation.

Message log archive grouping and encryption

Message log archive files may contain sensitive information that different organizations can own if multiple members share a single Security Server. Therefore, in version 7, message log archive files can be encrypted and grouped by member or subsystem.

Message log archive encryption and grouping can be configured separately. For example, the archives can be encrypted but not grouped (or vice versa). By default, both features are disabled. Grouping and encryption are enabled/disabled on a Security Server level - they are either enabled or disabled for all the members and subsystems. It's not possible to enable/disable neither of them for selected members nor subsystems only. When encryption and grouping are combined, each member's messages are stored in separate files encrypted with member-specific keys (4). In addition, when message log archive encryption is enabled, the signed document download service returns log records encrypted.

Message grouping can be configured by a member or subsystem. By default, grouping is disabled, and all archive files go to the same default group. Message log archive files that belong to the same group are chained using cryptographic hashes. The implementation is not based on blockchain. However, there may be holes in the chains if grouping is turned on and off or the grouping level (none/member/subsystem) changes. Every time grouping is turned on/off or the grouping level changes, the chains start from zero.

When message log archive encryption is enabled, the archive files are encrypted and signed using the Security Server’s internal key (1) by default. Instead, when archive encryption and grouping are combined, the Security Server administrator must configure one or more member-specific encryption keys (4) for each member. The member-specific keys are used to encrypt the archive files belonging to the member. If the Security Server administrator configures no member-specific key, the Security Server's internal key is used as a fallback.

Also, the format of the message log archives' filenames depends on the configuration of the Security Server. The format varies between encrypted and plain text archives and between different grouping levels. If the archive files are automatically processed based on the file name, the matching rules may have to be adjusted. More information about the filename format is available in the Security Server user guide.

Message log database encryption

Just like the message log archive files, the message log database may contain sensitive information. Starting from version 7.0.0, the message body stored in the message log database can be optionally encrypted, but the default is no encryption. The database encryption is fully transparent to all the external interfaces, e.g., the signed document download service. The Security Server administrator is responsible for configuring the database encryption key (3) before enabling database encryption.

In the message log database, there are two separate columns for plaintext ("message") and encrypted ("ciphermessage") message body. The message body is always stored in one of the two columns depending on the configuration. Instead, the other column that is not used is left empty. When message log database encryption is enabled/disabled, the change doesn't affect already existing records in the database. For example, when message log database encryption is enabled, all the records created after the configuration change will be encrypted and stored in the "ciphermessage" column. Instead, all the records stored before the change will remain in plaintext in the "message" column.

Thanks to the way how the message body encryption in the message log database has been implemented, the change doesn't affect any external integrations. For example, suppose message logs are exported directly from the message log database to some centralized logging system. In that case, the integration doesn't need to be changed if the message log database encryption continues to be disabled.

During message log archiving, the message body is decrypted and written to the archive file in plaintext. Message log archive encryption is configured separately, and when it's enabled, the whole archive file is signed and encrypted. In practice, the message log database encryption may be enabled while the message log archive encryption is disabled (or vice versa). However, if the message log contains sensitive information, it's recommended to enable both the message log database encryption and the message log archive encryption.

Future enhancements

The new data protection features introduced in version 7.0.0 will be developed further in the upcoming releases. For example, one of the potential enhancements is to provide information on the statutes of different encryption configuration options in the Security Server UI to detect the current state and possible configuration errors. Also, making various encryption-related configuration options available through the Security Server UI and REST management API is part of the future development plans.

We’re glad to receive feedback about the new features and contributions regarding further enhancements.

Message Logging in X-Road 7

One of X-Road’s key features is to provide undeniable and tamper-proof evidence of data exchange. X-Road does this by digitally signing, timestamping, and logging all the messages processed by the Security Server. The logs can be used in a court proceeding as evidence. This logging feature is known as the message log. These previous blog posts provide additional information about the message log:

• X-Road Logs Explained - Part 1

• X-Road Logs Explained - Part 2

• X-Road Logs Explained - Part 3

Depending on the data exchange use case, indisputable proof that can be used as legal evidence may be required. On the other hand, regular application logs provide enough information in many cases, and no additional guarantees are needed. In the latter case, X-Road message logs may not be required, or it's enough to log only the metadata. To better support different kinds of use cases and logging requirements, message logging has been made more configurable in X-Road 7. This blog post provides more information about different configuration alternatives available in X-Road 7.

Supported alternatives in X-Road 7

Starting from X-Road 7.0.0, the Security Server supports three options for configuring message logging:

• Full logging

  • The whole message, including both message body and metadata, is logged.

  • The log records can be verified afterward, and they can be used as evidence.

  • Timestamping service is required.

• Metadata logging

  • Only metadata which includes X-Road-specific message headers is logged while the message body is not logged.

  • Verifying the log records afterward is not possible, and they cannot be used as evidence.

  • Timestamping service is required.

• No message logging

  • Message logging is fully disabled. Neither message body nor metadata is logged.

  • No log records are generated.

  • Timestamping service is not required.

Regardless of how logging is configured, messages exchanged between Security Servers are always signed and encrypted. Also, when full logging or metadata logging is enabled, the Security Server produces a signed and timestamped document (Associated Signature Container - ASiC) for each request and response. 

Is it possible to combine different alternatives? 

Full logging and metadata logging can be configured on Security Server and subsystem level. When the Security Server level configuration is used, the same configuration is applied to all the subsystems. Instead, when the subsystem level configuration is used, the configuration is applied to specific subsystems only. In addition, combining the Security Server and subsystem level configurations is also possible, e.g., set metadata logging on the Security Server level and enable full logging for specific subsystems only (or vice versa). Instead, message logging is fully disabled on a Security Server level and it cannot be combined with the other alternatives. Therefore, a subsystem that requires full or metadata logging should not be registered on the Same Security server with a subsystem that requires entirely disabling message logging.

Which alternative should I use?

Multiple factors should be considered when selecting the logging configuration for a data exchange use case. First, there may be legal requirements regarding logging and retention period of the logs. Second,  some logging-related requirements that all the member organisations must follow may have been set by the X-Road operator. Third, there may be some organization-specific requirements for different kinds of use cases. Fourth, the other data exchange party of a specific data exchange use case may have requirements for logging. It's essential to be aware of the different requirements and configure logging accordingly.

To make the decision easier for member organisations, X-Road operators may define a default value for logging-related configuration in a country-specific meta-package. Without any country-specific configuration, the Security Server uses full logging by default. For example, suppose the operator requires using metadata logging by default. In that case, the operator can set the configuration in the country-specific meta-package so that all member organisations use metadata logging by default. The configuration must be updated manually only if some other logging alternative should be used. However, fully disabling message logging is not possible using country-specific meta-packages. Instead, it must be configured separately by the Security Server administrator.

How does the logging configuration affect the Security Server in general?

The logging configuration has some direct and indirect effects on the other features of the Security Server. Fully disabling logging increases the overall performance, reduces disk space consumption, and doesn't require a timestamping service to be configured. Also, moving the message log archives to external long-term storage is not needed since, without the message logging, there are no archive files either. Overall, fully disabling message logging improves the performance and decreases the environmental footprint of the Security Server. If logging is disabled in the whole X-Road ecosystem, running the ecosystem without a timestamping service is possible. However, even if performance and environmental reasons are essential, legal and administrative requirements must not be forgotten.

All the changes related to the message log encryption and archive grouping will be covered in a separate blog post together with other new encryption features.

Configuration Changes in X-Road 7

X-Road 7 will be backward compatible on the interface level with X-Road 6 since there are no changes in the Message Protocol for SOAP and the Message Protocol for REST. Upgrading the Security Server software is enough, and no changes to the connected information systems are required. However, the Service Metadata Protocol for REST and the Security Server REST management API have some changes that might not be fully backward compatible depending on the client application. Also, some Security Server's configuration changes are not backward compatible, and manual actions may be necessary depending on the current configuration. This blog post provides more information about the backward-incompatible changes in the configuration.

A new configuration file for overrides

X-Road 7 will change how some configuration overrides are handled by X-Road system services, e.g., proxy, signer, etc. The changes make the configuration more secure and more consistent. Besides the Security Server, the changes affect the Central Server and Configuration Proxy too.

In version 6, the "/etc/xroad/services/local.conf" file is used to override the environment variables for X-Road system services, e.g., memory allocation for proxy and signer. The problem with the implementation is that the configuration file is an executable that may also contain scripts and code in addition to the configuration overrides. Since the file is executed during restore, it enables code execution as a part of the restore process.

In X-Road 7, the configuration override mechanism will be changed to define the overrides in a non-executable properties file. Starting from X-Road 7.0.0., the properties file "/etc/xroad/services/local.properties" is used to override X-Road's environment variables. The file may contain configuration overrides only to predefined environment variables, and everything else is ignored.

Changes in environment variable names

Also, the format and the names of X-Road's environment variables will be different. Starting from version 7.0.0, all the variables are prefixed with "XROAD_". For example, the difference in customising memory allocation for proxy in X-Road 6 and X-Road 7:

X-Road 6

File "/etc/xroad/services/local.conf":

PROXY_PARAMS="$PROXY_PARAMS -Xms200m -Xmx2000m "

X-Road 7

File "/etc/xroad/services/local.properties":

XROAD_PROXY_PARAMS=-Xms200m -Xmx2000m

Here's a list of the X-Road-related environment variables and their names in different X-Road versions.

X-Road 6	X-Road 7
XROAD_PARAMS	XROAD_PARAMS
SIGNER_PARAMS	XROAD_SIGNER_PARAMS
ADDON_PARAMS	XROAD_ADDON_PARAMS
CONFCLIENT_PARAMS	XROAD_CONFCLIENT_PARAMS
CONFPROXY_PARAMS	XROAD_CONFPROXY_PARAMS
JETTY_PARAMS	XROAD_JETTY_PARAMS
MONITOR_PARAMS	XROAD_MONITOR_PARAMS
OPMON_PARAMS	XROAD_OPMON_PARAMS
PROXY_PARAMS	XROAD_PROXY_PARAMS
PROXY_UI_API_PARAMS	XROAD_PROXY_UI_API_PARAMS
SIGNER_CONSOLE_PARAMS	XROAD_SIGNER_CONSOLE_PARAMS

Other changes that affect configuration

In addition, there are some changes in the backup and restore features that affect the configuration too. Permissions for all the restored files are set to safe, constant values during a restore which means that permissions in the backup file are ignored. Also, the Security Server database backup format has changed, and the new format prevents the execution of arbitrary commands during restore. All the changes related to the Security Server backup encryption will be covered in a separate blog post together with other new encryption features.

What happens when I upgrade to X-Road 7?

Unfortunately, the changes on the Security Server are backward incompatible. It means that backup files generated on X-Road 6 Security Server cannot be restored on X-Road 7 Security Server. However, the changes on the Central Server are backward compatible.

Despite the changes, when upgrading from version 6 to 7, all overrides defined in "/etc/xroad/services/local.conf" will continue to work as before, including the old environmental variable names. However, starting from X-Road 7.0.0, the backups no longer contain the "/etc/xroad/services/local.conf" file, but instead the "/etc/xroad/services/local.properties" file will be included. It means that in case a Central Server or Security Server is restored from a backup, all local configuration overrides defined in "/etc/xroad/services/local.conf" are lost.

Also, in version 7, the backups no longer contain other ".conf" files located in the "/etc/xroad/services" directory. Those files are system configuration files that should never be manually modified since X-Road version upgrades always overwrite them. In case they're lost or corrupted, it's enough to re-install the X-Road packages. However, if the files have been manually modified, all the modifications are lost in case of restore.

It is strongly recommended to migrate all configuration overrides to the new "/etc/xroad/services/local.properties" file when upgrading from version 6 to 7. There's no automation in the migration, and therefore, migrating the configuration overrides must be done manually by the administrator. However, if the "/etc/xroad/services/local.conf" configuration file isn't used in X-Road 6, no actions are required.The migration includes changing the variable names to the new "XROAD_" prefixed format and updating the values according to the new properties format. In case the old "/etc/xroad/services/local.conf" configuration file contains something other than modifications to X-Road-related environmental variables, the changes must be handled in some other way. The new configuration override mechanism doesn't support additional configuration changes.

When both old and new configuration files exist

Also, the new and old configuration files can coexist side by side. When both "local.conf" and "local.properties" files exist, "local.properties" is applied first, and "local.conf" is applied second. However, "local.properties" can only append to the new variables ("XROAD_*"), while "local.conf" can change any parts of the configuration. As a result, values defined in "local.conf" overwrite values defined in "local.properties" if the same property is defined in both files. However, non-overlapping values defined in "local.properties" are still applied. Also, in case both old and new variable names (e.g., "SIGNER_PARAMS", "XROAD_SIGNER_PARAMS") are used in "local.conf", the new variable is applied. For example:

When "/etc/xroad/services/local.properties" contains:

XROAD_SIGNER_PARAMS=-Dprop1=newValue1 -Dprop2=newValue2

And "/etc/xroad/services/local.conf" contains:

SIGNER_PARAMS="$SIGNER_PARAMS -Dlegacy=true"

XROAD_SIGNER_PARAMS="$XROAD_SIGNER_PARAMS -Dprop1=oldValue1   -Dlegacy=false"

The resulting values for different "XROAD_SIGNER_PARAMS" related properties are:

• prop1=oldValue1

• prop2=newValue2

• legacy=false

More detailed instructions for the migration are provided in the X-Road 7 Migration Guide.