From 1b8e103de942f321df87d965580e6fbfe7e8ffe3 Mon Sep 17 00:00:00 2001 From: IkerLuengo <57146230+IkerLuengo@users.noreply.github.com> Date: Wed, 28 Jul 2021 13:42:53 +0200 Subject: [PATCH 1/6] ROS2 DDS Security PKCS#11 URI support The DDS-Security specification defines the use of Hardware Security Modules (HSM) and PKCS#11 URIs as an alternative to private keys and certificates stored in the file system. Current implementation only supports these tokens to be directly stored in the file system as `.pem` files. This is a design proposal to support PKCS#11 URIs. The changes affect to the RMW implementations, as these are filling the DDS security attributes for the participant. However, it also affects the contents of the enclave directories in the keystore. Although the proposed changes are totally backwards compatible (meaning that current RMW implementations will continue working if no PKCS#11 URIS are used), description of the new enclave contents and the expected RMW behavior seems appropriate. --- articles/ros2_dds_security_pkcs11_support | 69 +++++++++++++++++++++++ 1 file changed, 69 insertions(+) create mode 100644 articles/ros2_dds_security_pkcs11_support diff --git a/articles/ros2_dds_security_pkcs11_support b/articles/ros2_dds_security_pkcs11_support new file mode 100644 index 000000000..839a32dab --- /dev/null +++ b/articles/ros2_dds_security_pkcs11_support @@ -0,0 +1,69 @@ +--- +layout: default +title: ROS2 DDS security PKCS#11 URI support +abstract: + The [DDS-Security specification][dds_security] defines the use of Hardware Security Modules (HSM) and PKCS#11 URIs as an alternative to private keys and certificates stored in the file system. Current implementation only supports these tokens to be directly stored in the file system as `.pem` files. This is a design proposal to support PKCS#11 URIs. +author: '[Iker Luengo](https://github.com/IkerLuengo)' +published: false +--- + +- This will become a table of contents (this text will be scraped). +{:toc} + +# {{ page.title }} + +
+{{ page.abstract }} +
+ +Original Author: {{ page.author }} + +## Scope + +The [DDS-Security specification][dds_security] requires the security documents (private keys, certificates, governance and permissions) to be provided to the DDS implementation within the participant's `properties`. It defines a set of reserved properties, that must hold the URI of the corresponding document. However, it allows different URI schemes to be used. Specifically, in the case of certificates and private keys, it defines the support for: + +- file scheme (`file:/keystore/enclaves/foo/key.pem`). +- PKCS#11 scheme (`pkcs11:object=MyParticipantPrivateKey;type=private`). +- data scheme (`data:,-----BEGIN RSA PRIVATE KEY----- MIIEpAIBAAKCAQEA3HIh...AOBaaqSV37XBUJg== -----END RSA PRIVATE KEY-----`). + +Current RCL impementation only support the `file` scheme. Furthermore, it searches these security files in an enclave subdirectory within the reserved `enclaves` subfolder of the root keystore, corresponding to the fully-qualified path of every enclave. +For example, for the `/foo/bar` enclave, the directory structure would look like: + + + ├── enclaves + │ └── foo + │ └── bar + │ ├── cert.pem + │ ├── key.pem + │ ├── ... + └── public + ├── ... + + +Note that it also requires the names of the files to be the ones expected. Specifically, all certificate and key files must have the `.pem` extension. In order to configure the security properties of a DDS participant, the path of the appropriate file in the enclave directory is added as the `file` URI of the corresponding property. For example, for the private key in the authentication plugin: + + dds.sed.auth.private_key = file:/enclaves/foo/bar/key.pem + +## Proposal + +### Goals + +Support PKCS#11 URIs for certificates and key files. `data` URIs are out of scope of this proposal. + +### Specification + +We want to keep the current keystore structure as much as possible, as this will enable to keep all the current implementation regarding the enclave management and the CLI features that help setting up the keystore. No changes should be needed to systems that do not use the PKCS#11 scheme. + +The problem then is how to let the RMW implementation when we want to use a `file` URI and when a `pkcs11` URI; and how to provide the values of these URIs (i.e., the file path in the case of `file` and the token name in the case of `pkcs11`). + +This can be solved if we allow for the key and certificate files in the enclave to have `.pem` or `.p11` extensions. Files with `.p11` will contain the PKCS#11 URI instead of the actual document data. Then, the RMW can be aware of the file extension and set the security property accordingly. Taking the private key in the authentication plugin as an example: + +1. The RMW will look for a file with name `key.pem` or `key.p11` in the enclave. +1. If there is a `key.pem` file, it keeps the current behavior, and sets the value of the property to the path of the file. +1. Otherwise, if there is a `key.p11` file, it must load the content of the file, and set this content as the value of the property. Some check can be done at this point, e.g., assert that the file contains a PKCS#11 URI (i.e., starts with `pkcs11:`). + +With this proposal, current RMW implementations do not need to be updated if no support for PKCS#11 URIs is planned. Existing use SROS2 projects that do not use PKCS#11 URIs will continue to work with both the legacy or the updated implementation, New projects that want to use PKCS#11 URIs will fail unless the RMW supports `.p11` extension files as described in this proposal. + + + +[dds_security]: https://www.omg.org/spec/DDS-SECURITY/1.1/PDF From 8f0a79b201fa04d6b5babe05a83f603c8ca1a44c Mon Sep 17 00:00:00 2001 From: IkerLuengo <57146230+IkerLuengo@users.noreply.github.com> Date: Wed, 28 Jul 2021 13:53:22 +0200 Subject: [PATCH 2/6] correct file name --- ...ecurity_pkcs11_support => ros2_dds_security_pkcs11_support.md} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename articles/{ros2_dds_security_pkcs11_support => ros2_dds_security_pkcs11_support.md} (100%) diff --git a/articles/ros2_dds_security_pkcs11_support b/articles/ros2_dds_security_pkcs11_support.md similarity index 100% rename from articles/ros2_dds_security_pkcs11_support rename to articles/ros2_dds_security_pkcs11_support.md From 26b6cf6f77fddda8980e46ad36e55ef5f77805a9 Mon Sep 17 00:00:00 2001 From: IkerLuengo <57146230+IkerLuengo@users.noreply.github.com> Date: Tue, 31 Aug 2021 09:19:12 +0200 Subject: [PATCH 3/6] Fix typo Co-authored-by: Miguel Company --- articles/ros2_dds_security_pkcs11_support.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/articles/ros2_dds_security_pkcs11_support.md b/articles/ros2_dds_security_pkcs11_support.md index 839a32dab..77308bb52 100644 --- a/articles/ros2_dds_security_pkcs11_support.md +++ b/articles/ros2_dds_security_pkcs11_support.md @@ -42,7 +42,7 @@ For example, for the `/foo/bar` enclave, the directory structure would look like Note that it also requires the names of the files to be the ones expected. Specifically, all certificate and key files must have the `.pem` extension. In order to configure the security properties of a DDS participant, the path of the appropriate file in the enclave directory is added as the `file` URI of the corresponding property. For example, for the private key in the authentication plugin: - dds.sed.auth.private_key = file:/enclaves/foo/bar/key.pem + dds.sec.auth.private_key = file:/enclaves/foo/bar/key.pem ## Proposal From fda05761bd07ad6ae7a2a3a66c9e310decd02dc5 Mon Sep 17 00:00:00 2001 From: Miguel Company Date: Tue, 10 Jan 2023 07:39:57 +0100 Subject: [PATCH 4/6] Having one sentence per line. Signed-off-by: Miguel Company --- articles/ros2_dds_security_pkcs11_support.md | 35 +++++++++++++++----- 1 file changed, 26 insertions(+), 9 deletions(-) diff --git a/articles/ros2_dds_security_pkcs11_support.md b/articles/ros2_dds_security_pkcs11_support.md index 77308bb52..b1a3327d9 100644 --- a/articles/ros2_dds_security_pkcs11_support.md +++ b/articles/ros2_dds_security_pkcs11_support.md @@ -2,7 +2,9 @@ layout: default title: ROS2 DDS security PKCS#11 URI support abstract: - The [DDS-Security specification][dds_security] defines the use of Hardware Security Modules (HSM) and PKCS#11 URIs as an alternative to private keys and certificates stored in the file system. Current implementation only supports these tokens to be directly stored in the file system as `.pem` files. This is a design proposal to support PKCS#11 URIs. + The [DDS-Security specification][dds_security] defines the use of Hardware Security Modules (HSM) and PKCS#11 URIs as an alternative to private keys and certificates stored in the file system. + Current implementation only supports these tokens to be directly stored in the file system as `.pem` files. + This is a design proposal to support PKCS#11 URIs. author: '[Iker Luengo](https://github.com/IkerLuengo)' published: false --- @@ -20,13 +22,17 @@ Original Author: {{ page.author }} ## Scope -The [DDS-Security specification][dds_security] requires the security documents (private keys, certificates, governance and permissions) to be provided to the DDS implementation within the participant's `properties`. It defines a set of reserved properties, that must hold the URI of the corresponding document. However, it allows different URI schemes to be used. Specifically, in the case of certificates and private keys, it defines the support for: +The [DDS-Security specification][dds_security] requires the security documents (private keys, certificates, governance and permissions) to be provided to the DDS implementation within the participant's `properties`. +It defines a set of reserved properties, that must hold the URI of the corresponding document. +However, it allows different URI schemes to be used. +Specifically, in the case of certificates and private keys, it defines the support for: - file scheme (`file:/keystore/enclaves/foo/key.pem`). - PKCS#11 scheme (`pkcs11:object=MyParticipantPrivateKey;type=private`). - data scheme (`data:,-----BEGIN RSA PRIVATE KEY----- MIIEpAIBAAKCAQEA3HIh...AOBaaqSV37XBUJg== -----END RSA PRIVATE KEY-----`). -Current RCL impementation only support the `file` scheme. Furthermore, it searches these security files in an enclave subdirectory within the reserved `enclaves` subfolder of the root keystore, corresponding to the fully-qualified path of every enclave. +Current RCL impementation only support the `file` scheme. +Furthermore, it searches these security files in an enclave subdirectory within the reserved `enclaves` subfolder of the root keystore, corresponding to the fully-qualified path of every enclave. For example, for the `/foo/bar` enclave, the directory structure would look like: @@ -40,7 +46,10 @@ For example, for the `/foo/bar` enclave, the directory structure would look like ├── ... -Note that it also requires the names of the files to be the ones expected. Specifically, all certificate and key files must have the `.pem` extension. In order to configure the security properties of a DDS participant, the path of the appropriate file in the enclave directory is added as the `file` URI of the corresponding property. For example, for the private key in the authentication plugin: +Note that it also requires the names of the files to be the ones expected. +Specifically, all certificate and key files must have the `.pem` extension. +In order to configure the security properties of a DDS participant, the path of the appropriate file in the enclave directory is added as the `file` URI of the corresponding property. +For example, for the private key in the authentication plugin: dds.sec.auth.private_key = file:/enclaves/foo/bar/key.pem @@ -48,21 +57,29 @@ Note that it also requires the names of the files to be the ones expected. Speci ### Goals -Support PKCS#11 URIs for certificates and key files. `data` URIs are out of scope of this proposal. +Support PKCS#11 URIs for certificates and key files. +`data` URIs are out of scope of this proposal. ### Specification -We want to keep the current keystore structure as much as possible, as this will enable to keep all the current implementation regarding the enclave management and the CLI features that help setting up the keystore. No changes should be needed to systems that do not use the PKCS#11 scheme. +We want to keep the current keystore structure as much as possible, as this will enable to keep all the current implementation regarding the enclave management and the CLI features that help setting up the keystore. +No changes should be needed to systems that do not use the PKCS#11 scheme. The problem then is how to let the RMW implementation when we want to use a `file` URI and when a `pkcs11` URI; and how to provide the values of these URIs (i.e., the file path in the case of `file` and the token name in the case of `pkcs11`). -This can be solved if we allow for the key and certificate files in the enclave to have `.pem` or `.p11` extensions. Files with `.p11` will contain the PKCS#11 URI instead of the actual document data. Then, the RMW can be aware of the file extension and set the security property accordingly. Taking the private key in the authentication plugin as an example: +This can be solved if we allow for the key and certificate files in the enclave to have `.pem` or `.p11` extensions. +Files with `.p11` will contain the PKCS#11 URI instead of the actual document data. +Then, the RMW can be aware of the file extension and set the security property accordingly. +Taking the private key in the authentication plugin as an example: 1. The RMW will look for a file with name `key.pem` or `key.p11` in the enclave. 1. If there is a `key.pem` file, it keeps the current behavior, and sets the value of the property to the path of the file. -1. Otherwise, if there is a `key.p11` file, it must load the content of the file, and set this content as the value of the property. Some check can be done at this point, e.g., assert that the file contains a PKCS#11 URI (i.e., starts with `pkcs11:`). +1. Otherwise, if there is a `key.p11` file, it must load the content of the file, and set this content as the value of the property. + Some check can be done at this point, e.g., assert that the file contains a PKCS#11 URI (i.e., starts with `pkcs11:`). -With this proposal, current RMW implementations do not need to be updated if no support for PKCS#11 URIs is planned. Existing use SROS2 projects that do not use PKCS#11 URIs will continue to work with both the legacy or the updated implementation, New projects that want to use PKCS#11 URIs will fail unless the RMW supports `.p11` extension files as described in this proposal. +With this proposal, current RMW implementations do not need to be updated if no support for PKCS#11 URIs is planned. +Existing use SROS2 projects that do not use PKCS#11 URIs will continue to work with both the legacy or the updated implementation. +New projects that want to use PKCS#11 URIs will fail unless the RMW supports `.p11` extension files as described in this proposal. From ce09e8e6093dd46e9e30c30ecf95690eb818927e Mon Sep 17 00:00:00 2001 From: Miguel Company Date: Tue, 10 Jan 2023 07:47:26 +0100 Subject: [PATCH 5/6] Give p11 files higher priority. Signed-off-by: Miguel Company --- articles/ros2_dds_security_pkcs11_support.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/articles/ros2_dds_security_pkcs11_support.md b/articles/ros2_dds_security_pkcs11_support.md index b1a3327d9..4929f0332 100644 --- a/articles/ros2_dds_security_pkcs11_support.md +++ b/articles/ros2_dds_security_pkcs11_support.md @@ -73,9 +73,9 @@ Then, the RMW can be aware of the file extension and set the security property a Taking the private key in the authentication plugin as an example: 1. The RMW will look for a file with name `key.pem` or `key.p11` in the enclave. -1. If there is a `key.pem` file, it keeps the current behavior, and sets the value of the property to the path of the file. -1. Otherwise, if there is a `key.p11` file, it must load the content of the file, and set this content as the value of the property. - Some check can be done at this point, e.g., assert that the file contains a PKCS#11 URI (i.e., starts with `pkcs11:`). +1. If there is a `key.p11` file, and the RMW supports `pkcs11` URIs, it must load the content of the file, and set this content as the value of the property. + Some check can be done at this point, e.g., assert that the file contains a valid URI (i.e., starts with `pkcs11:`) +1. Otherwise, if there is a `key.pem` file, it keeps the current behavior, and sets the value of the property to the path of the file. With this proposal, current RMW implementations do not need to be updated if no support for PKCS#11 URIs is planned. Existing use SROS2 projects that do not use PKCS#11 URIs will continue to work with both the legacy or the updated implementation. From 9493211a29934b69490c283bae38d7a62d9304f9 Mon Sep 17 00:00:00 2001 From: Miguel Company Date: Fri, 27 Jan 2023 19:48:45 +0100 Subject: [PATCH 6/6] Apply suggestions from code review Signed-off-by: Miguel Company Co-authored-by: Mikael Arguedas --- articles/ros2_dds_security_pkcs11_support.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/articles/ros2_dds_security_pkcs11_support.md b/articles/ros2_dds_security_pkcs11_support.md index 4929f0332..65a986280 100644 --- a/articles/ros2_dds_security_pkcs11_support.md +++ b/articles/ros2_dds_security_pkcs11_support.md @@ -31,7 +31,7 @@ Specifically, in the case of certificates and private keys, it defines the suppo - PKCS#11 scheme (`pkcs11:object=MyParticipantPrivateKey;type=private`). - data scheme (`data:,-----BEGIN RSA PRIVATE KEY----- MIIEpAIBAAKCAQEA3HIh...AOBaaqSV37XBUJg== -----END RSA PRIVATE KEY-----`). -Current RCL impementation only support the `file` scheme. +Current RCL implementation only support the `file` scheme. Furthermore, it searches these security files in an enclave subdirectory within the reserved `enclaves` subfolder of the root keystore, corresponding to the fully-qualified path of every enclave. For example, for the `/foo/bar` enclave, the directory structure would look like: @@ -62,7 +62,7 @@ Support PKCS#11 URIs for certificates and key files. ### Specification -We want to keep the current keystore structure as much as possible, as this will enable to keep all the current implementation regarding the enclave management and the CLI features that help setting up the keystore. +We want to keep the current keystore structure as much as possible, as this will enable to keep all the current implementations regarding the enclave management and the CLI features that help setting up the keystore. No changes should be needed to systems that do not use the PKCS#11 scheme. The problem then is how to let the RMW implementation when we want to use a `file` URI and when a `pkcs11` URI; and how to provide the values of these URIs (i.e., the file path in the case of `file` and the token name in the case of `pkcs11`).