Setting up an X-Road Security Server

Security Server Installation, Registration and Configuration

Hardware requirements

• 64-bit dual-core Intel, AMD or compatible CPU; AES instruction set support is highly recommended

• 2 CPU

• 4 GB RAM

• 10 GB free disk space (OS partition) and 20-40 GB free disk space on the “/var” partition

• 100 Mbps network interface card

Operating System Requirements

This guide assumes one of the following:

• Red Hat Enterprise Linux

  • RHEL8+

• Ubuntu

  • 20.04 LTS

  • 22.04 LTS

Note: Installing and configuring an X-Road Security Server requires  sudo permissions on the host.

Running in a container

Running the X-Road Security Server in a container is outside the scope of this guide, but you can refer to the official Security Server Sidecar User Guide for guidance.

Network Configuration

Check the Network Configuration sub-page.

FQDN Requirements

The FQDN of a Security Server should easily identity the Tier and Owner:

Environment	Tier	FQDN Template
IS-DEV	Development	xroad-dev.<member's domain>.is
IS-TEST	Testing / QA / UAT / Staging et.al.	xroad-test.<member's domain>.is
IS	Production	xroad-prod1.<member's domain>.is xroad-prod2.<member's domain>.is

Installing X-Road

Provision the xroad POSIX user

The X-Road Server should be run under a dedicated POSIX user, usually named xroad

Create this user by running the following command:

sudo useradd \
--system \
--home /var/lib/xroad \
--no-create-home \
--shell /bin/bash \
--user-group \
--comment "X-Road system user" \
xroad

If that user will be used for interactive SSH log-ins, then we must ensure that the Security Server PIN (see below) doesn't get cleared (even though auto-login is configured), by running the following command:

loginctl enable-linger xroad

Follow the installation guide

NIIS maintains a guide for setting up Security Servers on Ubuntu and RHEL inside their knowlegebase, which you can find here: How to Set Up a Security Server?

While following the guide above, take care to override the official documentation with specific steps for the Icelandic environment (Straumurinn), outlined at https://github.com/digitaliceland/Straumurinn

Certificate generation

During installation, a dialog will appear asking for host and IP information for certificate generation. The latter set of the dialog will be for configuring certificates for the xroad-proxy-ui-api.

Here it may be desirable to change the value from the auto-detected machine host name to a domain name used for accessing the Admin UI:

Registration

Once a Security Server has been successfully installed, the Admin UI can be accessed by pointing a web browser at https://SECURITYSERVER:4000/ .

Required configuration for registration

Before being able to import a Configuration Anchor, the Security Server IP and FQDN must be whitelisted by the operator of the Straumurinn X-Road Central Services.

To register a Security Server into Straumurinn, the following configuration values are required:

1. Outgoing IP Address of the Security Server

The public outgoing IP address of the server can be found with with the following command from a Security Server terminal session:

$ curl ifconfig.me

2. FQDN of the Security Server

Refer to the section about FQDN Requirements.

3. Member's Kennitala / SSN

Registration contact

To register, an email containing the values listed above the should be sent to the operator of the Straumurinn X-Road Central Server at [email protected]

Example email for registering a Security Server to Central.

Example email for registering a X-Road Security Server to Central

Post-registration steps

Have a look at the Security Server initial configuration guide from X-Road. Some of the next steps are derived from there.

Disable message payload logging

The xroad-securityserver-is variant has the message logging disabled by default, from X-Road version 6.24.0 onwards.

Software Token PIN

Keep the the PIN secret. Keep it safe.

During the Security Server initial configuration, we need to generate a password called the "software token PIN".

The PIN is a 12 digit, alpha-numeric password:

• https://en.wikipedia.org/wiki/Personal_identification_number

• https://en.wikipedia.org/wiki/ISO_9564#PIN_length

You will be asked to supply the PIN during Initial Configuraion (see below).

Configure Auto-Login PIN entry functionality

If Auto-Login is not configured, the server will require manual entry of the Soft Token PIN during startup / restart, which can have implications for the Security Server's reliability.

For the PIN to be entered automatically when starting X-Road services, refer to the X-Road: Autologin User Guide

Test auto-login PIN entry functionality

To verify that auto-login PIN entry works as expected, you can try stopping and starting all the X-Road services like this:

for i in xroad-confclient xroad-proxy xroad-signer xroad-monitor xroad-opmonitor xroad-proxy-ui-api ;\
do \
   echo "stopping $i"; \
   sudo service $i stop; \
done;
sudo systemctl list-units "xroad*"
for i in xroad-confclient xroad-proxy xroad-signer xroad-monitor xroad-opmonitor xroad-proxy-ui-api; \
do \
   echo "starting $i"; \
   sudo service $i start; \
done

Ensure if all services are up and running

sudo systemctl list-units "xroad*"

Enable health check endpoint

Refer to the Health check service configuration for information on enabling the health check endpoints.

Initial Configuration

Configuration Anchors

Start by acquiring the Configuration Anchor for the X-Road network, found here: https://github.com/digitaliceland/Straumurinn/tree/master/Anchor

Next, point your browser at the Security Server, on port 4000 and log in.

The X-Road Security Server Login Screen

Upload the environment's configuration anchor.

Step 1 of the Initial Configuration Wizard, which allows the User to upload a Configuration Anchor

After anchor has been uploaded, it needs to be confirmed.

Ensure that the "Hash Generated" corresponds to the information on the Central Server.

Click [CONFIRM].

Configuration Anchor Confirmation Dialog

The Configuration Anchor has now been configured and should show you something like the following:

A successfully configured Configuration Anchor

Owner Member

In the initial configuration screen input the values as follows.

• Member Class - the Member Class of the organization that maintains the central server.

• Member Code - the Member Code of the organization that maintains the central server.

• Member Name - is auto completed when Member Code is added.

• Security Server Code - unique code identifying the Security Server.

  • Use short-name for Server Code

  • Do not use FQDN, ".", "/" or "".

    • Some extensions use dots as separators, e.g. REST Adapter Service.

  • X-Road Message Protocol imposes some restrictions on the characters that can be used in X-Road identifiers. The following characters SHALL NOT be used in the identifier values:

    • Colon

    • Semicolon

    • Slash

    • Backslash

    • Percent

    • Path identifiers (such as /../)

    • Non-printable characters (tab, newline etc.)

  • https://github.com/nordic-institute/X-Road/blob/6d60774c0b4e5368e70943c17a2ae6dfaa513259/doc/Protocols/pr-mess_x-road_message_protocol.md#27-identifier-character-restrictions

  • https://github.com/nordic-institute/X-Road/blob/6d60774c0b4e5368e70943c17a2ae6dfaa513259/doc/Protocols/pr-rest_x-road_message_protocol_for_rest.md#48-identifier-character-restrictions

Step 2 of the Initial Configuration Wizard, which allows the User to configure the Owner Member of the Security Server

Software Token PIN

• PIN - the password that protects the security server's secret keys.

• Repeat PIN - repeat the above PIN.

Keep the PIN secret. Keep it safe.

Step 3 of the Initial Configuration Wizard, which allows the USer to set the Software Token PIN.

The initial configuration was saved successfully.

CSR certificates

Configuration window for adding members, clients or subsystems

The security server asks for PIN code.

Click the Please enter soft token PIN link.

An X-Road Security Server Admin UI page showing a red banner with the message "Please enter soft token PIN" along with a button for logging in with the PIN

Clicking the link navigates to Keys and Certificates page.

• Click [LOG IN] on the softToken Service.

• Enter PIN Code

• Click [LOG IN] in the modal window.

Logging in with PIN Code

The red error message bar should now disappear.

Final steps

Configure Timestamping Services

Go to: Settings > Timestamping Services and click [ADD]

The Settings -> System Parameters page which shows the empty Timestamping Services.

Pick a time-stamping service from the list and click [OK.]

A modal for adding a Timestamping Service.

The message "Timestamping message added" should appear.

Admin UI: The Settings -> System Parameters page which shows that aTimestamping service has been added

Configure SIGN and AUTH Keys

SIGN Key

Navigate to "KEYS AND CERTIFICATES"

The Keys and Certificate Page

Click [ADD KEY]

The wizard for generating a certificate signing key

Enter ”sign” for the "Key Label" and click [NEXT]

The CSR Details page inside the Add Key wizard.

Fill out the form with the following values:

• Usage: SIGNING

• Client: Select the relevant Client from the dropdown.

• CSR Format: PEM

Click [GENERATE CSR]

The Generate CSR page inside the Add Key wizard

Click [DONE]

Final confirmation page of the Add Key wizard

The CSR should be downloaded to browser's download folder.

An overview of SIGN and AUTH keys, showing that a CSR for the SIGN key has been created.

---

The AUTH key

If you are not already there, start by navigating to "KEYS AND CERTIFICATES"->"SIGN AND AUTH KEYS" of the Admin UI (see above).

Click [ADD KEY]

Enter “auth” and click [NEXT]

Part 1 of the The Add Key wizard, showing "Key Label" being set to "auth"

Choose AUTHENTICATON and change CSR Format to PEM

Fill out the form with the following values:

• Usage: AUTHENTICATION

• Certification Service: Select the appropriate certification service (there should only be 1)

• CSR Format: PEM

Part 2 of the The Add Key wizard: CSR details

Enter your Server DNS name (CN)

Part 3 of the Add Key Wizard: Generate CSR

Press GENERATE CSR

Final confirmation page of the Add Key wizard

The certificate request is downloaded to browser's download folder.

An overview of SIGN and AUTH keys, showing that a CSR for both the SIGN and AUTH keys have been created.

Now you can see that there are two keys in the overview, Sign and Auth.

The certificate request should be sent to [email protected].

Import Certificates

Navigate to KEYS AND CERTIFICATIONS and click [IMPORT CERT].

Import the AUTH Certificate

Navigate to and select the .pem file containing your certificate.

The "KEYS AND CERTIFICATIONS" and screen overlaid by a MacOS File System Browser highlighting a .pem file.

The "SIGN AND AUTH KEYS" showing a successfully imported AUTH Certificate

Activate auth signed certificate

Click the name of the certificate (test.xrd.island.is...) and press Activate

SCREENSHOT NEEDED

Import the SIGN Certificate

Finally press Register on the auth certificate and enter inn the FQDN of the server and press ADD

A "Registration request" modal which accepts the Security Server DNS name

"SIGN AND AUTH KEYS" Screen showing that the status of AUTH Certificate is "Registration in progress"

"SIGN AND AUTH KEYS" Screen showing that both SIGN and AUTH Certificates have been Registered.

Confirm communication between two security servers

curl --insecure -H "X-Road-Client: IS-TEST/COM/5302922079/Origo-client" "
https://origo-staging.xroad.coldcloudlab.com/r1/IS-TEST/GOV/7005942039/VMST-Protected/APIS/company?name=origo
"

IS-DEV

Ísland.is to Skatturinn:

curl -H "X-Road-Client: IS-DEV/GOV/10000/island-is-client" "http://localhost:8080/r1/IS-DEV/GOV/10006/Skatturinn-Protected/APIS-v1/company?name=skatturinn"

IS-TEST

Ísland.is to Skatturinn:

curl -H "X-Road-Client: IS-TEST/GOV/5501692829/island-is-client" "http://localhost:8080/r1/IS-TEST/GOV/5402696029/Skatturinn-Protected/APIS-v1/company?name=skatturinn"

Removal of Security Server

Ubuntu

#!/bin/bash

set -x
sudo apt-get purge xroad-base
sudo apt-get autoremove
sudo rm -rf /etc/xroad
sudo rm -rf /usr/share/xroad
sudo rm -rf /var/lib/xroad
sudo rm -rf /var/log/xroad
sudo rm -rf /var/tmp/xroad
sudo apt-get purge nginx
sudo -u postgres dropdb messagelog
sudo -u postgres dropdb serverconf
sudo -u postgres dropdb op-monitor
sudo -u postgres psql -c "drop user serverconf"
sudo -u postgres psql -c "drop user messagelog"
sudo -u postgres psql -c "drop user opmonitor"
sudo -u postgres psql -c "drop user serverconf_admin"
sudo -u postgres psql -c "drop user messagelog_admin"
sudo -u postgres psql -c "drop user opmonitor_admin"
sudo apt-get --purge remove postgresql\*
sudo rm -rf /etc/postgresql/
sudo rm -rf /var/lib/postgresql
sudo userdel -r postgres

RHEL

#!/bin/bash

set -x

sudo yum remove xroad-base
sudo rm -rf /etc/xroad
sudo rm -rf /usr/share/xroad
sudo rm -rf /var/lib/xroad
sudo rm -rf /var/log/xroad
sudo rm -rf /var/tmp/xroad
sudo yum remove nginx
sudo -u postgres dropdb messagelog
sudo -u postgres dropdb serverconf
sudo -u postgres psql -c "drop user serverconf"
sudo yum remove postgresql