Configuration Proxy Manual
Last updated
Was this helpful?
Last updated
Was this helpful?
Version: 2.10 Doc. ID: UG-CP
26.11.2014
1.0
Initial version
19.01.2015
1.1
License information added
07.05.2015
1.2
Configuration properties table added
26.05.2015
1.3
Token initialization description added
30.06.2015
1.4
Minor corrections done
09.07.2015
1.5
Repository address updated
20.09.2015
2.0
Editorial changes made
07.06.2017
2.1
System parameter signature-algorithm-id replaced with signature-digest-algorithm-id
Cybernetica AS
05.03.2018
2.2
Added references, terms and abbreviations reference, document link
Tatu Repo
10.04.2018
2.3
Cybernetica AS
14.10.2018
2.4
Update package repository address
Petteri Kivimäki
15.11.2018
2.5
Add Ubuntu 18.04 installation instructions
Jarkko Hyöty
11.09.2019
2.6
Remove Ubuntu 14.04 support
Jarkko Hyöty
24.06.2020
2.7
Petteri Kivimäki
18.02.2021
2.8
Add Ubuntu 20.04 in supported platforms
Petteri Kivimäki
01.07.2021
2.9
Update 3rd party key server
Petteri Kivimäki
26.09.2022
2.10
Remove Ubuntu 18.04 support
Andres Rosenthal
The intended audience of this Manual are X-Road system administrators responsible for installing and using X-Road configuration proxy software.
The document is intended for readers with a moderate knowledge of Linux server management, computer networks, and the X-Road working principles.
See X-Road terms and abbreviations documentation [TA-TERMS].
[TA-TERMS] X-Road Terms and Abbreviations. Document ID: TA-TERMS.
The configuration proxy acts as an intermediary between X-Road servers in the matters of global configuration exchange.
The goal of the configuration proxy is to download an X-Road global configuration from a provided configuration source and further distribute it in a secure way. Optionally, the downloaded global configuration may be modified to suit the requirements of the configuration proxy owner.
The configuration proxy can be configured to mediate several global configurations (from multiple configuration sources).
The configuration proxy runs on the Ubuntu Server 20.04 LTS or 22.04 LTS operating system on a 64-bit platform. The configuration proxy's software is distributed as .deb packages through the official X-Road repository at https://artifactory.niis.org/xroad-release-deb.
The software can be installed both on physical and virtualized hardware (of the latter, Xen and Oracle VirtualBox have been tested).
Note: The information in empty cells has to be determined before the server’s installation, by the person performing the installation.
Caution: Data necessary for the functioning of the operating system is not included.
1.0
Ubuntu 20.04, 64bit 2GB RAM, 3GB free disk space
Minimum requirements.
1.1
https://artifactory.niis.org/xroad-release-deb
X-Road package repository.
1.2
https://artifactory.niis.org/api/gpg/key/public
1.3
TCP 80
Global configuration distribution. Ports for inbound connections (from the external network to the configuration proxy).
1.4
TCP 80
Global configuration download. Ports for outbound connections (from the configuration proxy to the external network).
1.5
Configuration proxy’s public IP address, NAT address.
Minimum recommended hardware parameters:
the server’s hardware (motherboard, CPU, network interface cards, storage system) must be supported by Ubuntu in general;
a 64-bit dual-core Intel, AMD or compatible CPU; AES instruction set support is highly recommended;
2 GB RAM;
a 100 Mbps network interface card;
if necessary, interfaces for the use of hardware tokens.
Requirements to software and settings:
an installed and configured supported version of Ubuntu x86-64 operating system;
if the configuration proxy is separated from other networks by a firewall and/or NAT, the necessary connections to and from the security server must be allowed (reference data: 1.3; 1.4). The enabling of auxiliary services which are necessary for the functioning and management of the operating system (such as DNS, NTP, and SSH) is outside the scope of this guide;
if the configuration proxy has a private IP address, a corresponding NAT record must be created in the firewall (reference data: 1.5).
Set the operating system locale.
Add the following line to the file /etc/environment: LC_ALL=en_US.UTF-8
Ensure that the locale is generated: sudo locale-gen en_US.UTF-8
To install the X-Road configuration proxy software, follow these steps.
Add the X-Road repository’s signing key to the list of trusted keys (reference data: 1.2):
Add X-Road package repository (reference data: 1.1)
Issue the following commands to install the configuration proxy packages:
The installation is successful if the 'xroad-signer' service is started, the 'xroad-confproxy' cron job is added, and the configuration proxy management utilities are available from the command line.
Check from the command line that the 'xroad-signer' service is in the running state (example output follows). Notice that it is normal for the xroad-confclient to be in stopped state on the configuration proxy since it operates in one-shot mode.
Ubuntu 20.04 or 22.04
Check from the command line that the 'xroad-confproxy' cron job is present (example output follows):
Make sure that the following commands are available from the command line:
To configure support for hardware security tokens (smartcard, USB token, Hardware Security Module), act as follows.
Install the hardware token support module using the following command:
Install and configure a PKCS#11 driver for the hardware token according to the manufacturer's instructions.
Add the path to the PKCS#11 driver to the file /etc/xroad/devices.ini (as described in the example given in the file).
After installing and configuring the driver, the xroad-signer service must be restarted:
If you are running a high availability (HA) hardware token setup (such as a cluster with replicated tokens) then you may need to constrain the token identifier format such that the token replicas can be seen as the same token. The token identifier format can be changed in /etc/xroad/devices.ini via the token_id_format property (default value: {moduleType}{slotIndex}{serialNumber}{label}). Removing certain parts of the identifier will allow the HA setup to work correctly when one of the tokens goes down and is replaced by a replica. For example, if the token replicas are reported to be on different slots the {slotIndex} part should be removed from the identifier format.
Depending on the hardware token there may be a need for more additional configuration. All possible configurable parameters in the /etc/xroad/devices.ini are described in the next table.
enabled
BOOLEAN
true
Indicates whether this device is enabled.
library
STRING
The path to the pkcs#11 library of the device driver.
library_cant_create_os_threads
BOOLEAN
false
Indicates whether application threads, which are executing calls to the pkcs#11 library, may not use native operating system calls to spawn new threads (in other words, the library’s code may not create its own threads).
os_locking_ok
BOOLEAN
false
Indicates whether the pkcs#11 library may use the native operation system threading model for locking.
sign_verify_pin
BOOLEAN
false
Indicates whether the PIN should be entered per signing operation.
token_id_format
STRING
{moduleType}{slotIndex}{serialNumber}{label}
Specifies the identifier format used to uniquely identify a token. In certain high availability setups may need be constrained to support replicated tokens (eg. by removing the slot index part which may be diffirent for the token replicas).
sign_mechanism
STRING
CKM_RSA_PKCS
Specifies the signing mechanism. Supported values: CKM_RSA_PKCS, CKM_RSA_PKCS_PSS.
pub_key_attribute_encrypt
BOOLEAN
true
Indicates whether public key can be used for encryption.
pub_key_attribute_verify
BOOLEAN
true
Indicates whether public key can be used for verification.
pub_key_attribute_wrap
BOOLEAN
Indicates whether public key can be used for wrapping other keys.
pub_key_attribute_allowed_mechanisms
STRING LIST
Specifies public key allowed mechanisms. Supported values: CKM_RSA_PKCS, CKM_SHA256_RSA_PKCS, CKM_SHA384_RSA_PKCS, CKM_SHA512_RSA_PKCS, and CKM_RSA_PKCS_PSS, CKM_SHA256_RSA_PKCS_PSS, CKM_SHA384_RSA_PKCS_PSS, CKM_SHA512_RSA_PKCS_PSS.
priv_key_attribute_sensitive
BOOLEAN
true
Indicates whether private key is sensitive.
priv_key_attribute_decrypt
BOOLEAN
true
Indicates whether private key can be used for encryption.
priv_key_attribute_sign
BOOLEAN
true
Indicates whether private key can be used for signing.
priv_key_attribute_unwrap
BOOLEAN
Indicates whether private key can be used for unwrapping wrapped keys.
priv_key_attribute_allowed_mechanisms
STRING LIST
Specifies private key allowed mechanisms. Supported values: CKM_RSA_PKCS, CKM_SHA256_RSA_PKCS, CKM_SHA384_RSA_PKCS, CKM_SHA512_RSA_PKCS, and CKM_RSA_PKCS_PSS, CKM_SHA256_RSA_PKCS_PSS, CKM_SHA384_RSA_PKCS_PSS, CKM_SHA512_RSA_PKCS_PSS.
Note 1: Only parameter library is mandatory, all the others are optional. Note 2: The item separator of the type STRING LIST is ",".
To start using the configuration proxy, a proxy instance configuration needs to be created. Several proxy instances can be configured to mediate multiple global configurations.
3.1.1 Security Token Activation
The configuration proxy uses a security token for storing the key that is used for signing the distributed configuration. The token can be stored either on hard disk (software token) or in hardware. Before the configuration proxy can be used, the security token must be initialized and activated.
Initialization of a software token can be done as follows:
A PIN is prompted, which will be used to log in to the software token afterwards. Initialization of hardware tokens is vendorspecific and is not in scope of this documentation.
Activation of the security token is done by logging in to the token, using the following command:
where <TOKEN_ID> is the identifier of the security token, which can be found with:
Note, that the identifier of a software token is always „0”.
3.1.2 User Access Privileges
The administrator must execute configuration scripts as the 'xroad' user.
Modify '/etc/xroad/conf.d/local.ini' to contain the following:
The configuration of this parameter is necessary for generating a correctly formatted configuration anchor file that will need to be uploaded to central servers that should receive configurations mediated by this proxy, this process is described in detail in 3.4. There are several more system parameters that can be configured in '/etc/xroad/conf.d/local.ini' under the 'configuration-proxy' section, their descriptions and default values can be seen from the following table:
address
0.0.0.0
The public IP or NAT address (reference data: 1.5) which can be accessed for downloading the distributed global configurations.
configuration-path
/etc/xroad/confproxy/
generated-conf-path
/var/lib/xroad/public
Absolute path to the public web server directory where the global configuration files generated by this configuration proxy, should be placed for distribution.
signature-digest-algorithm-id
SHA-512
ID of the digest algorithm the configuration proxy should use when computing global configuration signatures. The possible values are: SHA-256, SHA-384, SHA-512.
hash-algorithm-uri
http://www.w3.org/2001/04/xmlenc#sha512
URI identifying the algorithm the configuration proxy should use to calculate hash values for the global configuration file. The possible values are: http://www.w3.org/2001/04/xmlenc#sha256, http://www.w3.org/2001/04/xmlenc#sha512.
download-script
/usr/share/xroad/scripts/download_instance_configuration.sh
Absolute path to the location of the script that initializes the global configuration download procedure.
The configuration proxy is periodically started by a cron job. It reads the properties described above, from the configuration file before executing each proxy instance configured in 'configuration-path', generating new global configuration directories using algorithms as defined by 'signature-digest-algorithm-id' and 'hash-algorithm-uri'. The generated directories are subsequently placed in 'generated-conf-path' for distribution.
3.2.1 Configuration Structure of the Instances
Each global configuration that is to be mediated by the configuration proxy requires a proxy instance to be configured. The configuration of a proxy instance consists of a set of configuration files, including
a trusted anchor .xml of the configuration being mediated;
a configuration .ini file;
verification certificates for the configured signing keys.
The following example file tree shows configured proxy instances named PROXY1 and PROXY2:
The configuration of proxy instances is described in 3.4.
ATTENTION: The names in the angle brackets<> are chosen by the X-Road configuration proxy administrator.
2.1
<PROXY_NAME>
Name of the proxy instance being configured
2.2
<SECURITY_TOKEN_ID>
2.3
<ANCHOR_FILENAME>
Filename of the generated anchor .xml file that the configuration proxy clients will need to use for downloading the global configuration
Create configuration files for the new proxy instance by invoking the 'confproxy-create-instance -p <PROXY_NAME>' command. Afterwards, use the 'confproxy-view-conf -p <PROXY_NAME>' command to verify that the operation has been successfully completed (example output follows):
Generate a signing key and a self signed certificate for the newly created proxy instance using the following command:
If no active signing key is configured for the proxy instance, then the new key should be set as the currently active key (example output follows):
Alternatively, one may add an existing key using the '–k <KEY_ID>' argument:
To define which global configuration this proxy instance should distribute, download the source anchor from an X-Road central server and save it as '/etc/xroad/confproxy/<PROXY_NAME>/anchor.xml'.
The configuration proxy should be operational at this point. The periodic cron job (once a minute) should download the global configuration defined in '/etc/xroad/confproxy/<PROXY_NAME>/anchor.xml' and generate a directory for distribution. The output of 'confproxy-view-conf -p <PROXY_NAME>' should be similar to the following:
To let clients download the generated global configuration an anchor file needs to be generated using the following command:
If generation was successful the output should be simply:
To make sure that the global configuration is being distributed correctly use the '/usr/share/xroad/scripts/download_instance_configuration.sh' script, giving it <ANCHOR_FILENAME> and the path, which should hold the downloaded files, as arguments (example output follows):
If the proxy instance has been configured correctly, the 'test_download' directory should contain the downloaded global configuration files.
3.5.1 Changing the Validity Interval
There is an additional property in the configuration file of the proxy instance (/etc/xroad/confproxy/<PROXY_NAME>/conf.ini) that determines the validity interval of the generated global configuration for a given instance.
The default value is 10 minutes (600 seconds). The property is set by modifying the following field in the configuration file:
Notice that when the configuration proxy instance is started, it deletes all the previously generated global configuration directories that are older than the currently configured validity interval for that instance.
3.5.2 Deleting the Signing Keys
Should a signing key need to be deleted, the following command can be used:
where <SIGNING_KEY_ID> can be found in the output of 'confproxy-view-conf' (example output follows):
Attempts to delete the active signing key will be unsuccessful.
3.5.3 Changing the Active Signing Key
Additional signing keys can be added with the following command:
Keys added in this manner will be marked as inactive keys ('signing-key-id-*=<KEY_ID>') in the proxy instance configuration file (/etc/xroad/confproxy/<PROXY_NAME>/conf.ini). In case the current active signing key has to be replaced by one of the additional keys, the configuration file of the proxy instance will need to be modified, changing the following lines:
to the following ones:
After the change the key 'QWERTY123' may be deleted if necessary.
Updated chapter "" with configurable parameters described in the configuration file 'devices.ini'
Add repository sign key details in section
The repository key.
Hash: 935CC5E7FA5397B171749F80D6E3973B
Fingerprint: A01B FE41 B9D8 EAF4 872F A3F1 FB0D 532C 10F6 EC5B
3rd party key server:
Absolute path to the directory containing the configuration files of the proxy instance. The format of the configuration directory is described in .
ID of a security token (as defined by prerequisites )
