Skip to content

Commit

Permalink
feat(CS): EC key support for global configuration
Browse files Browse the repository at this point in the history 
docs fixes and some refactoring

Refs: XRDDEV-2695
  • Loading branch information
@ovidijusnortal
ovidijusnortal committed Nov 7, 2024
1 parent cadf02c commit a599d1e
Show file tree
Hide file tree
Showing 28 changed files with 187 additions and 163 deletions.
6 changes: 5 additions & 1 deletion doc/Manuals/ig-cs_x-road_6_central_server_installation_guide.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -58,7 +58,7 @@ Doc. ID: IG-CS
| 02.01.2024 | 2.38 | Loopback ports added | Justas Samuolis |
| 25.04.2024 | 2.39 | Updated for Ubuntu 24.04 | Madis Loitmaa |
| 12.06.2024 | 2.40 | Update network diagram | Petteri Kivimäki |
| 21.10.2024 | 2.41 | Update for configurable parameters in the `/etc/xroad/devices.ini` after added support for ECDSA keys | Ovidijus Narkevicius |
| 21.10.2024 | 2.41 | Update for configurable parameters in the `/etc/xroad/devices.ini` after added support for ECDSA Configuration signing keys | Ovidijus Narkevicius |


## Table of Contents <!-- omit in toc -->
Expand Down Expand Up @@ -521,6 +521,10 @@ The Central Server produces global configuration version V2. Version V2 is suppo

The Central Server produces global configuration version V3. Version V3 is supported by Security Servers from version 7.4.0 and up.

### 4.3 Use EC Algorithm in Configuration Signing keys

Since version 7.6.0, the Central Server supports EC algorithm for configuration signing keys. Refer to [UG-CS](#Ref_UG-CS) section „Migrating to EC based Configuration Signing keys“.

## 5 Installation Error Handling

### 5.1 Cannot Set LC_ALL to Default Locale
Expand Down
44 changes: 20 additions & 24 deletions doc/Manuals/ig-ss_x-road_v6_security_server_installation_guide.md
View file

Large diffs are not rendered by default.

33 changes: 17 additions & 16 deletions doc/Manuals/ug-cp_x-road_v6_configuration_proxy_manual.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -26,8 +26,7 @@ Doc. ID: UG-CP
| 26.09.2022 | 2.10 | Remove Ubuntu 18.04 support | Andres Rosenthal |
| 30.10.2023 | 2.11 | Configuring TLS Certificates | Madis Loitmaa |
| 25.04.2024 | 2.12 | Updated for Ubuntu 24.04 | Madis Loitmaa |
| 21.10.2024 | 2.13 | Update for configurable parameters in the `/etc/xroad/devices.ini` after added support for ECDSA keys | Ovidijus Narkevicius |

| 21.10.2024 | 2.13 | Update for configurable parameters in the `/etc/xroad/devices.ini` after added support for ECDSA keys and addtinal arguments for `confproxy-add-signing-key` to enable EC key creation | Ovidijus Narkevicius |


## Table of Contents
Expand Down Expand Up @@ -298,14 +297,14 @@ 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](#34-proxy-instance-configuration). 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:

| Parameter | Default value | Explanation |
|------------------------|----------------------------------------|-------------|
| 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/ | Absolute path to the directory containing the configuration files of the proxy instance. The format of the configuration directory is described in [3.2.1](#321-configuration-structure-of-the-instances). |
| 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:<br>http://www.w3.org/2001/04/xmlenc#sha256,<br>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. |
| Parameter | Default value | Explanation |
|-------------------------------|-------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| 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/ | Absolute path to the directory containing the configuration files of the proxy instance. The format of the configuration directory is described in [3.2.1](#321-configuration-structure-of-the-instances). |
| 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:<br>http://www.w3.org/2001/04/xmlenc#sha256,<br>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.

Expand Down Expand Up @@ -341,11 +340,11 @@ The configuration of proxy instances is described in [3.4](#34-proxy-instance-co

**ATTENTION:** The names in the angle brackets&lt;&gt; are chosen by the X-Road configuration proxy administrator.

| Ref | | Explanation |
|-----|----------------------------|-------------|
| 2.1 | &lt;PROXY_NAME&gt; | Name of the proxy instance being configured |
| 2.2 | &lt;SECURITY_TOKEN_ID&gt; | ID of a security token (as defined by prerequisites [3.1](#31-prerequisites)) |
| 2.3 | &lt;ANCHOR_FILENAME&gt; | Filename of the generated anchor .xml file that the configuration proxy clients will need to use for downloading the global configuration |
| Ref | | Explanation |
|-----|---------------------------|-------------------------------------------------------------------------------------------------------------------------------------------|
| 2.1 | &lt;PROXY_NAME&gt; | Name of the proxy instance being configured |
| 2.2 | &lt;SECURITY_TOKEN_ID&gt; | ID of a security token (as defined by prerequisites [3.1](#31-prerequisites)) |
| 2.3 | &lt;ANCHOR_FILENAME&gt; | Filename of the generated anchor .xml file that the configuration proxy clients will need to use for downloading the global configuration |


### 3.4 Proxy Instance Configuration
Expand Down Expand Up @@ -378,9 +377,11 @@ active-signing-key-id:
2) Generate a signing key and a self signed certificate for the newly created proxy instance using the following command:

```bash
confproxy-add-signing-key -p <PROXY_NAME> -t <SECURITY_TOKEN_ID>
confproxy-add-signing-key -p <PROXY_NAME> -t <SECURITY_TOKEN_ID> [-a <RSA|EC>]
```

Note: **-a** parameter is optional and can be used to specify the key algorithm(since version 7.6.0). If not provided, the default value is RSA. If keys are using EC algorithm and consumers of the configuration proxy are using older X-Road instances then they will fail to verify global configuration signatures.

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):

```bash
Expand Down
22 changes: 22 additions & 0 deletions doc/Manuals/ug-cs_x-road_6_central_server_user_guide.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -179,6 +179,7 @@ Doc. ID: UG-CS
- [18 Migrating to Remote Database Host](#18-migrating-to-remote-database-host)
- [19 Additional Security Hardening](#19-additional-security-hardening)
- [20 Passing additional parameters to psql](#20-passing-additional-parameters-to-psql)
- [21 Migrating to EC based Configuration Signing keys](#21-migrating-to-ec-based-configuration-signing-keys)
<!-- tocstop -->

# License
Expand Down Expand Up @@ -1757,3 +1758,24 @@ This example shows how SSL configurations for _psql_ could look like. List of po
Some of the variables like `PGOPTIONS`, `PGDATABASE`, `PGUSER`, `PGPASSWORD` are already used by scripts(created and initialized with values from `/etc/xroad/db.properties` file) so adding same variables to `db_libpq.env` won't have any effect on script behaviour.
In case it is needed to pass additional flags to internally initialized `PGOPTIONS` variable, then `PGOPTIONS_EXTRA` variable can be used. It will be appended to `PGOPTIONS` variable.
# 21 Migrating to EC based Configuration Signing keys
Since version 7.6.0 Central Server supports ECDSA based Configuration Signing keys. By default, both internal and external configuration signing keys will use RSA algorithm as in previous versions. EC algorithm can be enabled separately for internal and external keys so migration can be done steps first internal and then external keys or vice versa.
The instructions how to start using internal and external signing EC keys are listed below.
Prerequisites
* If internal key will use EC then all dependant security servers should be also of at least version 7.6.0. If not, they must be upgraded first otherwise they will not be able to verify the configuration signatures.
* If external key will use EC then all dependant security servers in federations should be also of at least version 7.6.0. If not, they must be upgraded first otherwise they will not be able to verify the configuration signatures.
1. Update the configuration to use EC based keys. This can be done by updating the configuration file `/etc/xroad/conf.d/local.ini` and adding the following lines:
```ini
[admin-service]
internal-key-algorithm = EC
external-key-algorithm = EC
```
2. Restart the `xroad-center` service to apply the changes made to the configuration file.
3. Follow the instructions in the [Generating a Configuration Signing Key](#541-generating-a-configuration-signing-key) to generate new keys, which will be using EC algorithm now.
37 changes: 19 additions & 18 deletions doc/Manuals/ug-sc_x-road_signer-console_user_guide.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -10,24 +10,25 @@ Doc. ID: UG-SC

## Version history <!-- omit in toc -->

| Date | Version | Description | Author |
|------------|---------|---------------------------------------------------------------------------|------------------|
| 20.11.2014 | 0.1 | First draft | |
| 20.11.2014 | 0.2 | Some improvements done | |
| 01.12.2014 | 1.0 | Minor corrections done | |
| 19.01.2015 | 1.1 | License information added | |
| 02.04.2015 | 1.2 | "sdsb" changed to "xroad" | |
| 30.06.2015 | 1.3 | Minor corrections done | |
| 09.09.2015 | 2.0 | Editorial changes made | |
| 14.09.2015 | 2.1 | Audit log added | |
| 20.09.2015 | 2.2 | Editorial changes made | |
| 06.09.2015 | 2.3 | Added certificate request format argument | |
| 03.11.2015 | 2.4 | Added label parameter for key generation command | |
| 10.12.2015 | 2.5 | Editorial changes made | |
| 26.02.2021 | 2.6 | Convert documentation to markdown | Caro Hautamäki |
| 01.03.2021 | 2.7 | Added [2.4.19 update-software-token-pin](#2419-update-software-token-pin) | Caro Hautamäki |
| 25.08.2021 | 2.8 | Update X-Road references from version 6 to 7 | Caro Hautamäki |
| 01.06.2023 | 2.9 | Update references | Petteri Kivimäki |
| Date | Version | Description | Author |
|------------|---------|---------------------------------------------------------------------------|----------------------|
| 20.11.2014 | 0.1 | First draft | |
| 20.11.2014 | 0.2 | Some improvements done | |
| 01.12.2014 | 1.0 | Minor corrections done | |
| 19.01.2015 | 1.1 | License information added | |
| 02.04.2015 | 1.2 | "sdsb" changed to "xroad" | |
| 30.06.2015 | 1.3 | Minor corrections done | |
| 09.09.2015 | 2.0 | Editorial changes made | |
| 14.09.2015 | 2.1 | Audit log added | |
| 20.09.2015 | 2.2 | Editorial changes made | |
| 06.09.2015 | 2.3 | Added certificate request format argument | |
| 03.11.2015 | 2.4 | Added label parameter for key generation command | |
| 10.12.2015 | 2.5 | Editorial changes made | |
| 26.02.2021 | 2.6 | Convert documentation to markdown | Caro Hautamäki |
| 01.03.2021 | 2.7 | Added [2.4.19 update-software-token-pin](#2419-update-software-token-pin) | Caro Hautamäki |
| 25.08.2021 | 2.8 | Update X-Road references from version 6 to 7 | Caro Hautamäki |
| 01.06.2023 | 2.9 | Update references | Petteri Kivimäki |
| 06.11.2024 | 2.10 | Added key algorithm argument | Ovidijus Narkevicius |

## Table of Contents <!-- omit in toc -->

Expand Down
Loading

0 comments on commit a599d1e

Please sign in to comment.