Table of contents

1 General

This document discusses the changes needed to migrate to the next major version of X-Road. The upgrade is possible from version 6.26.0. Please read through the release notes of each version upgrade separately to gain an understanding of the potential breaking changes.

The changes listed under breaking changes require actions from the administrator. The changes listed under notable new features do not require direct action but enable an enhanced X-Road experience. Less important features and bug fixes included in this release are not listed in this guide. They can be found in the X-Road 7.0.0 release notes instead.

2 Breaking changes

2.1 Service configuration changes

2.1.1 General

In the previous versions of X-Road, the service configuration overrides have been stored in /etc/xroad/services/local.conf. The file can contain environment variables and executable code which is a security problem.

In X-Road 7, the service configuration override mechanism is changed. The overrides are stored in non-executable /etc/xroad/services/local.properties. The file may only contain configuration overrides to predefined environment variables and everything else is ignored. 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 customizing memory allocation for proxy in X-Road 6 and X-Road 7:

X-Road 6

PROXY_PARAMS="$PROXY_PARAMS -Xms200m -Xmx2000m "

X-Road 7

XROAD_PROXY_PARAMS=-Xms200m -Xmx2000m

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

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. Security Server user interface and command-line scripts related to backups warn about this.

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. 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 else than modifications to X-Road-related environmental variables, the changes must be handled in some other way since the new configuration override mechanism doesn't support them.

Also, the new and old configuration files can co-exist side by side. When both local.conf and local.properties files exist, local.properties is applied first and local.conf 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 in case 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:

/etc/xroad/services/local.properties

/etc/xroad/services/local.conf

The resulting values for different XROAD_SIGNER_PARAMS related properties are:

• prop1=oldValue1
• prop2=newValue2
• legacy=false

XROAD_SIGNER_PARAMS=-Xms50m -Xmx200m
XROAD_PROXY_PARAMS=-Xms200m -Xmx2000m

XROAD_SIGNER_PARAMS=-Xms50m \
-Xmx200m
XROAD_PROXY_PARAMS=-Xms200m \
-Xmx2000m

2.1.2 Steps to migrate the service configuration

1. After upgrading the Security Server to version 7.0.0, connect to the server using a command-line terminal. Check if there is a file /etc/xroad/services/local.conf. If not, there is nothing to migrate and you can skip the rest of the steps. If there is, check the file contents e.g. cat /etc/xroad/services/local.conf Example output follows.

SIGNER_PARAMS="$SIGNER_PARAMS -Xms50m -Xmx200m"
JAVA_HOME="/usr/lib/jvm/java-1.11.0-openjdk-amd64"

        2. The first SIGNER_PARAMS can be easily migrated to the new properties file, see below. The second line with JAVA_HOME has to be handled outside the X-Road configuration files e.g. move it to an operating system environment variable.

XROAD_SIGNER_PARAMS=-Xms50m -Xmx200m

        3. After the variables have been migrated, delete the old configuration file e.g. rm /etc/xroad/services/local.conf, and restart the xroad-* services or the Security Server host server.

2.2 Old configuration backups not supported on the Security Server

The Security Server configuration backup format has changed to prevent the execution of arbitrary commands during restore.  Permissions for all the restored files are set to safe constant values during the restore which means that permissions in the backup file are ignored.

Unfortunately, the changes in 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 in the Central Server are backward compatible.

Before upgrading Security Server, take a backup using some other means. The method varies depending on your platform. For virtual machines, it is standard to have a possibility to take snapshots. Cloud-based servers usually have a method to snapshot the disk contents. If the security server upgrade fails for some reason, you have a way to restore the old state.

2.3 Message log archiving moved to a separate process

Security Server message log archiving has been moved to a separate process xroad-addon-messagelog.service that logs into /var/log/xroad/messagelog-archiver.log. Monitoring systems need to be configured to take into account the new service and the log file in addition to the old ones.

No separate action is needed due to this change for new installations. After upgrading to 7.0.0 on RHEL platform, the new service needs to enabled (systemctl enable xroad-addon-messagelog) and started (systemctl start xroad-addon-messagelog) separately.

3 Notable new features

3.1 Data encryption at rest

X-Road 7.0.0 will introduce new security features for protecting data at rest on the Security Server. The new features are:

• Encrypt backup files
• Verify integrity of backup files on backup file upload and before running restore
• Encrypted message payload in message log database
• Encrypted message log archives
• Group message log archives by member or subsystem
• Message logging can be fully disabled

Data exported and imported to/from Security Server can be encrypted and/or signed using GnuPG. Signing and encryption are optional - it is possible to configure the Security Server so that no encryption takes place.

Data encryption, signing, decrypting, and verification are performed by launching an external GnuPG process and interpreting the generated output.  The database encryption is implemented in Java code instead.

The required keys are stored in GPG key rings. Security Server's internal keys that are used by default are generated automatically. Member-specific keys are manually managed by the administrator.

All the encryption-related configuration operations require shell access to the Security Server. 

New encryption keys on the Security Server

1. Internal GPG key pair

• Created automatically during Security Server initialization process or version upgrade.
• The private key is used to:
  • sign backup files
  • sign message log archive files when message log archive encryption is enabled
  • decrypt backup files during restore
• The public key is used to:
  • encrypt backup files when backup encryption is enabled
  • encrypt message log archive files when message log archive encryption is enabled and archives are not encrypted with a per-member key
  • verify the integrity of a backup file during restore
• To externally verify backup or message log archive file integrity, the administrator has to manually export the public key
  • Verification can then be done using any standard PGP tools
• Not included in the Security Server backups

2. Backup/restore GPG keys

• Additional public keys that are used to encrypt backup files when backup encryption is enabled
  • The creation of additional keys is recommended to protect against the loss of internal GPG key pair
• Created manually by the Security Server administrator
• The corresponding private keys:
  • are managed externally by the Security Server administrator
  • can be used to decrypt the backups outside of the Security Server, e.g., in case the Security Server's internal key pair is lost.
• Included in the Security Server backups by default

3. Database encryption key

• The encryption key that is used to encrypt message body in the message log database when database encryption is enabled
  • Encrypted message body is stored in the new ciphermessage column and the message column is left empty
• Created manually by the Security Server administrator
• Included in the Security Server backups if stored under /etc/xroad, but not in /etc/xroad/gpghome
  • The location is defined by the Security Server administrator when enabling database encryption

4. Archive GPG keys

• Additional per-member public keys that are used to encrypt message log archive files when message log archive encryption and grouping are enabled
• The keys are member-specific and they are used to encrypt archives owned by a specific member
• The corresponding private keys are managed externally by the Security Server administrator
  • The private keys can be used to decrypt the message log archive files outside of the Security Server
• Not included in the Security Server backups by default.

3.1.1 Encrypt backup files and verify their integrity

Security Server configuration backups are always signed, but backup encryption is initially turned off. When encryption is enabled, backup files are encrypted when they are created and they are stored on disk encrypted. This 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.

Security Server verifies the backup archive consistency during the restore operation. The integrity verification requires that the original Security Server internal key pair is available. In case the internal key pair is lost, the restore operation can't be performed in the user interface or through the API, but has to be executed from the command line with appropriate options that enable skipping integrity verifications.

The backup encryption configuration is described in the Security Server User Guide.

3.1.2 Encrypted message payload in message log database

The message body can be optionally encrypted, but it is switched off by default. The encryption is fully transparent to all the external interfaces, e.g., the signed document download service.

There are two separate columns in the database for plain text (message) and encrypted (ciphermessage) message body. The message body is always stored in one of the two columns depending on the configuration. The other column 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 after the change will be encrypted and stored in the ciphermessage column. Instead, all the records stored before the change will remain in plain text in the message column.

During message log archiving, the message body is decrypted and it's written to the archive file in plain text. Message log archive file encryption is configured separately, and when it's enabled, the whole archive file is signed and encrypted.

For step by step instructions on how to activate messagelog encryption, see Security Server User Guide.

3.1.3 Message log archive encryption and grouping

Message log archive encryption and grouping can be configured separately. By default, both 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 or subsystems only.

Message grouping can be configured by 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. However, chains may have holes in them in case grouping is turned on and off, or the grouping level (none/member/subsystem) is changed.

Encryption can be combined with grouping so that each member's messages are stored in separate files encrypted with separate member-specific keys.

When message log archive encryption is enabled, the signed document download service returns log records encrypted.

The message log archive encryption is described in the Security Server User Guide.

3.1.4 Message logging can be fully disabled

Security Server can now be installed with the message log addon disabled. When the message log addon is disabled, no messages are logged and no timestamping service is needed. This is an optional step during the installation, but default the addon is still installed. 

Information on how to disable the addon is available at:

• Ubuntu: https://github.com/nordic-institute/X-Road/blob/develop/doc/Manuals/ig-ss_x-road_v6_security_server_installation_guide.md#27-disable-the-messagelog-addon-before-installation-optional
• RHEL 7/8: https://github.com/nordic-institute/X-Road/blob/develop/doc/Manuals/ig-ss_x-road_v6_security_server_installation_guide_for_rhel.md#27-disable-the-messagelog-addon-before-installation-optional

3.2 Update Central Server BDR support

X-Road 7 gives more control to the administrators over the Central Server installation/upgrade process. Although BDR is not a direct dependency of X-Road anymore, the changes enable using the latest versions of BDR to implement the Central Server's high availability.

3.2.1 Remove references to BDR1

X-Road 6.26.0 had some direct references to BDR version 1 making it difficult to use later BDR releases. The references have now been removed making the Central Server high-availability solution more technology agnostic.

3.2.2 Possibility to skip database restoration when restoring configuration backup

When restoring configuration backup on the Central Server it's now possible to skip the database restoration and handle it manually. The restoration option is available on the command line and is described in the Central Server User Guide.

3.2.3 Possibility to skip automatic database migrations and run them manually on the command line

When the Central Server is installed or upgraded, it's possible to skip the automatic database migrations performed by the installer. Additionally, the instructions guide how the migrations can be run manually when needed. See Central Server Installation Guide.

3.3 Possibility to install Security Server without a local PostgreSQL server

Starting from X-Road 7.0.0, it is possible to install a security server without a local PostgreSQL server. It has been possible to configure a security server to use a remote database earlier but the locally installed PostgreSQL database server remained installed in any case. This optimizes the security server's resource usage further.

Installing Security Server with a remote database is described in the installation guides for Ubuntu and RHEL.

3.4 Possibility to change PIN code on the Security Server

Security Server makes it possible to change the PIN code that was chosen during the initial configuration. The change needs to be performed on the command line using the signer-console tool. The Signer Console User Guide describes the operation.

3.5 Run security server on Java 11 by default

The security server now runs on Java 11 platform by default. To migrate an existing installation to Java 11, see the following steps described in X-Road Knowledge Base. Security Server 7.0.0 also displays the used Java version in the user interface's diagnostics view.

3.6 Improvements to diagnostics

The new Security Server improves the diagnostics view of the user interface. 

• Diagnostics now shows Java version information
• Diagnostics status now shows whether TSA is able to process timestamping requests. Previously status only indicated whether TCP connections to TSA succeeded.

3.7 Version upgrade is possible only from the two previous versions

The official support policy for X-Road installations is that upgrades from the previous two versions are tested by the core development team and guaranteed to work. X-Road 7 enforces this policy in the installation packages so that upgrades over three or more versions are not directly allowed but have to be done in steps. For example, an upgrade from 6.24.0 to 7.0.0 does not work directly. The supported path is to first upgrade to 6.26.0 and from there to 7.0.0. There's more information about this in the installation guide.

3.8 Production level Docker support for Security Server

With the previous X-Road releases, NIIS has published Central Server and Security Server Docker images for testing and development use. See the following links:

• X-Road Central Server Docker image
• X-Road Security Server Docker image
• Standalone Security Server Docker image

X-Road Security Server Sidecar is a containerized version of the Security Server that supports production use. The Sidecar is a Docker container that runs in the same virtual context (virtual host, Kubernetes Pod, etc.) with an information system. The Sidecar can be used for both consuming and producing services. Full documentation and source code are available on GitHub.

3.9 Return REST API type and API endpoints in REST metaservice responses

Security Server's REST metadata services listMethods and allowedMethods have been updated to include more information in their responses. The responses now include also the REST API type (REST or OPENAPI) and the list of endpoints.

Related articles

• Page:
  How to Set Up a Local Test Environment Using Docker Compose?
• Page:
  What Is a Certificate Profile?
• Page:
  What Is a Country-Specific Meta Package?
• Page:
  What Are the Technical Requirements for Trust Service Providers?
• Page:
  What Is a Certification Authority (CA)?