Skip to content

Commit

Permalink
feat(SS): EC key support for signing/authentication
Browse files Browse the repository at this point in the history 
update documentation

Refs: XRDDEV-2694
  • Loading branch information
@ovidijusnortal
ovidijusnortal committed Nov 8, 2024
1 parent 28dc9c7 commit 6c83c38
Show file tree
Hide file tree
Showing 3 changed files with 100 additions and 61 deletions.
46 changes: 27 additions & 19 deletions doc/Manuals/ig-ss_x-road_v6_security_server_installation_guide.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

**X-ROAD 7**

Version: 2.53
Version: 2.54
Doc. ID: IG-SS

---
Expand Down Expand Up @@ -73,6 +73,7 @@ Doc. ID: IG-SS
| 12.06.2024 | 2.51 | Add ACME server to the network diagram, add a section about enabling ACME support | Petteri Kivimäki |
| 25.06.2024 | 2.52 | Add global configuration download port 443 to the network diagram | Petteri Kivimäki |
| 24.09.2024 | 2.53 | Add mail server to the network diagram | Mikk-Erik Bachmann |
| 08.11.2024 | 2.54 | Update for configurable parameters in the `/etc/xroad/devices.ini` after added support for ECDSA keys | Ovidijus Narkevicius |

## License

Expand Down Expand Up @@ -433,24 +434,26 @@ If you are running a high availability (HA) hardware token setup (such as a clus

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.

| Parameter | Type | Default Value | Explanation |
|-----------------------------------------|-------------|------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| *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*. |
| Parameter | Type | Default Value | Explanation |
|-----------------------------------------|-------------|------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| *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 different for the token replicas). |
| *sign_mechanism* | STRING | *CKM_RSA_PKCS* | Specifies the signing mechanism. Supported values: *CKM_RSA_PKCS*, *CKM_RSA_PKCS_PSS*. |
| *rsa_sign_mechanism* | STRING | *CKM_RSA_PKCS* | Specifies the signing mechanism. Supported values: *CKM_RSA_PKCS*, *CKM_RSA_PKCS_PSS*. If value isn't provided then defaults to value of *sign_mechanism* if present. |
| *ec_sign_mechanism* | STRING | *CKM_ECDSA* | Specifies the signing mechanism for EC keys. Supported values: *CKM_ECDSA*. |
| *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*, *CKM_ECDSA*, *CKM_ECDSA_SHA256*, *CKM_ECDSA_SHA384*, *CKM_ECDSA_SHA512*. |
| *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*, *CKM_ECDSA*, *CKM_ECDSA_SHA256*, *CKM_ECDSA_SHA384*, *CKM_ECDSA_SHA512*. |

**Note 1:** Only parameter *library* is mandatory, all the others are optional.
**Note 2:** The item separator of the type STRING LIST is ",".
Expand Down Expand Up @@ -566,6 +569,11 @@ The key can then be moved to an external host and imported to GPG keyring with t
Automated Certificate Management Environment (ACME) protocol enables automated certificate management of the authentication and sign
certificates on the Security Server. More information about the required configuration is available in the [Security Server User Guide](ug-ss_x-road_6_security_server_user_guide.md#24-configuring-acme).

### 3.7 Enabling EC keys for authentication and signing certificates

Security server supports EC based authentication and signing certificates since version 7.6.0.
More information about the required configuration is available in the [Security Server User Guide](ug-ss_x-road_6_security_server_user_guide.md#25-migrating-to-ec-based-authentication-and-signing-certificates).

## 4 Installation Error handling


Expand Down
Loading

0 comments on commit 6c83c38

Please sign in to comment.