From f8988332cf653f7f2705248fb0c3effeee847f6c Mon Sep 17 00:00:00 2001 From: Hugues de Valon Date: Fri, 26 Jun 2020 13:06:50 +0100 Subject: [PATCH] Add recommendations for secure deployment The recommendations list what an admin must do to install the service securely. Also modifies the installation guide to make it a secure deployment guide using systemd. Updates the guide to remove socket activation. Signed-off-by: Hugues de Valon --- src/SUMMARY.md | 5 +- src/parsec_service/build_run.md | 11 +++++ src/parsec_service/install_parsec_linux.md | 55 ++++++++++++++++++---- src/parsec_service/listeners.md | 5 +- src/threat_model/secure_deployment.md | 31 ++++++++++++ src/threat_model/threat_model.md | 26 +++++----- 6 files changed, 104 insertions(+), 29 deletions(-) create mode 100644 src/threat_model/secure_deployment.md diff --git a/src/SUMMARY.md b/src/SUMMARY.md index a1e11d4..b05af22 100644 --- a/src/SUMMARY.md +++ b/src/SUMMARY.md @@ -4,7 +4,8 @@ - [Overview](overview.md) - [API coverage](api_coverage.md) - [Parsec Threat Model](threat_model/threat_model.md) -- [Parsec Rust client Threat Model](threat_model/rust_client_threat_model.md) + - [Recommendations for Secure Deployment](threat_model/secure_deployment.md) +- [Parsec Rust Client Threat Model](threat_model/rust_client_threat_model.md) - [Parsec for users](parsec_users.md) - [Parsec for client developers](parsec_client/README.md) - [Operations](parsec_client/operations/README.md) @@ -37,7 +38,7 @@ - [Key Info Managers](parsec_service/key_info_managers.md) - [Adding a new Parsec Provider](parsec_service/adding_provider.md) - [How to build and run Parsec](parsec_service/build_run.md) - - [How to install Parsec on Linux](parsec_service/install_parsec_linux.md) + - [How to securely install Parsec on Linux](parsec_service/install_parsec_linux.md) - [Parsec Configuration](parsec_service/configuration.md) - [How to test Parsec](parsec_service/test.md) - [Contributing](contributing.md) diff --git a/src/parsec_service/build_run.md b/src/parsec_service/build_run.md index fccfb10..8a4d57e 100644 --- a/src/parsec_service/build_run.md +++ b/src/parsec_service/build_run.md @@ -20,6 +20,17 @@ replaced by a subset of the features mentioned above, space or comma separated. test the TPM or PKCS check the [related guides](test.md#testing-the-tpm-provider-using-the-software-tpm). +For the `DomainSocket` listener, the socket folder needs to be created: + +``````` +mkdir /tmp/parsec +``````` + +On a real deployment (as explained in our [installation guide](install_parsec_linux.md)) specific +owners and permissions need to be set up on this folder. Those security settings will be checked by +the clients for them to make sure they are communicating with a trusted Parsec service. For testing +only, it is fine to keep the folder as it is. + To build and run Parsec from source: ``````` diff --git a/src/parsec_service/install_parsec_linux.md b/src/parsec_service/install_parsec_linux.md index 4235ce1..1d9b132 100644 --- a/src/parsec_service/install_parsec_linux.md +++ b/src/parsec_service/install_parsec_linux.md @@ -1,8 +1,14 @@ -# How to install Parsec on Linux +# How to securely install Parsec on Linux -Parsec can be built and installed as a Linux daemon using systemd. The Parsec daemon uses socket -activation which means that the daemon will be automatically started when a client request is made -on the socket. The daemon is a systemd user daemon run by the `parsec` user. +Parsec can be built and installed as a Linux daemon using systemd. The daemon is a systemd user +daemon run by the `parsec` user. Some manual steps are needed to make sure that permissions are set +up correctly so that Parsec is installed respecting the operational mitigations of our [threat +model](../threat_model/threat_model.md). Similarly to the threat model, this guide proposes +different alternatives in case an Identity Provider is available or not. The role and description of +an Identity Provider in Parsec is described in the [System +Architecture](https://parallaxsecond.github.io/parsec-book/parsec_service/system_architecture.html) +page. Currently, Parsec does not support integration with any Identity Provider. To securely install +Parsec, please follow the steps of deployment **without an Identity Provider**. If your Linux system uses systemd to manage daemons, you can follow these steps. `$DESIRED_FEATURES` can be a space or comma-separated subset of: `mbed-crypto-provider`, `pkcs11-provider`, and @@ -24,23 +30,46 @@ git clone https://github.com/parallaxsecond/parsec.git cargo install --features $DESIRED_FEATURES --path parsec ``` -Copy and adapt the [configuration](configuration.md) you want to use. +Copy and adapt the [configuration](configuration.md) you want to use. For a secure deployment, make +sure to activate the `log_error_details` option and to use a `trace` log level. ``` cp parsec/config.toml config.toml ``` +Create the Parsec socket directory. + +``` +mkdir /tmp/parsec +``` + +In a deployment **without an Identity Provider**, create the `parsec-clients` group and set the +correct permissions on the socket folder. Mutually trusted Parsec Clients will need to be in that +group. + +``` +sudo groupadd parsec-clients +sudo chown :parsec-clients /tmp/parsec +sudo chmod 750 /tmp/parsec +``` + +In a deployment **with an Identity Provider**, set the correct permissions on the socket folder. + +``` +sudo chmod 755 /tmp/parsec +``` + Install the systemd unit files and activate the Parsec socket. ``` mkdir -p ~/.config/systemd/user -cp -r parsec/systemd-daemon/parsec.service parsec/systemd-daemon/parsec.socket ~/.config/systemd/user -systemctl --user enable parsec.socket -systemctl --user start parsec.socket +cp -r parsec/systemd-daemon/parsec.service ~/.config/systemd/user +systemctl --user enable parsec +systemctl --user start parsec ``` -Every user on the system can now use Parsec! You can test it going inside the `parsec/e2e_tests` -directory and: +`parsec-clients` users (with no IP) or every one (with IP) can now use Parsec! You can test it going +inside the `parsec/e2e_tests` directory and: ``` cargo test normal_tests @@ -52,4 +81,10 @@ Check the Parsec logs with: journalclt --user -u parsec ``` +Reload the service: + +``` +systemctl --user kill -s HUP parsec +``` + *Copyright 2019 Contributors to the Parsec project.* diff --git a/src/parsec_service/listeners.md b/src/parsec_service/listeners.md index 779ddf8..4c46e3d 100644 --- a/src/parsec_service/listeners.md +++ b/src/parsec_service/listeners.md @@ -5,9 +5,6 @@ This listener communicates with its client using a [Unix domain socket](https://en.wikipedia.org/wiki/Unix_domain_socket). -When running the service executable directly, the socket path is fixed to -`/tmp/security-daemon-socket`. When launched as a daemon by systemd, the socket is at -`/home/parsec/parsec.sock`. Clients communicating with a Parsec service configured with that -listener must connect to that socket path. +The socket path is: `/tmp/parsec/parsec.sock`. *Copyright 2020 Contributors to the Parsec project.* diff --git a/src/threat_model/secure_deployment.md b/src/threat_model/secure_deployment.md new file mode 100644 index 0000000..dc5bb5c --- /dev/null +++ b/src/threat_model/secure_deployment.md @@ -0,0 +1,31 @@ +# Recommendations on a Secure Parsec Deployment + +The following recommendations should be applied in order for Parsec to respect some of the +operational mitigations. These recommendations have been thought of for a Linux system and should be +modified/ported for other operating systems. The linked [operational +mitigations](threat_model.md#operational-mitigations) are noted with `O-n`. + +- The service must be running as the `parsec` user (O-0). +- Key mappings must only be read/write by the `parsec` user (O-3). +- The logs must be redirected to a file only readable by the `parsec` user (O-5). +- The configuration file must only be read/write by the `parsec` user (O-6). +- For the Domain Socket Listener, the socket must be in a folder with specific permissions (O-9). + The folder must be owned by the `parsec` user which must have read, write and execute rights on + it. + - In a deployment **without Identity Provider**, the folder must be group owned by the + `parsec-clients` group which has only read and execute permission on it (O-10). Everyone else + must have no permission on the folder. The `parsec-clients` group is composed of mutually + trusted clients only. + - In a deployment **with Identity Provider**, everyone else can have read and execute permission + on the folder. +- Before accessing the service, clients must check the permissions of the folder containing the + socket (O-2). The owner, group owner and permissions must be the same as the previous point, + depending on an Identity Provider is available or not. + +# Using systemd + +Installing Parsec using systemd with the unit files provided and [following the +guide](../parsec_service/install_parsec_linux.md) will make sure that the recommendations above are +respected. + +*Copyright 2020 Contributors to the Parsec project.* diff --git a/src/threat_model/threat_model.md b/src/threat_model/threat_model.md index 1d9c078..a4a8975 100644 --- a/src/threat_model/threat_model.md +++ b/src/threat_model/threat_model.md @@ -325,18 +325,18 @@ cleared. ## Operational mitigations -| ID | Justification | -|------|------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| 0 | A trusted administrator should start the service in such a way that un-privileged processes cannot send signals to the service. | -| 1 | A trusted administrator should check the validity of the providers and hardware modules written in the service's configuration before starting/reloading it. | -| 2 | Clients need to know from a trusted source that a trusted Parsec service is running on their machine so that they can trust the Listener endpoint. | -| 3 | Mappings should be put in a location that only the Parsec service and the trusted administrator can access. | -| 4 | The trusted administrator needs to be notified when any kind of resource is running out. | -| 5 | Parsec logs coming from the service binary should be redirected to a file that is only writable by the service and readable by the trusted administrator. | -| 6 | Parsec configuration file should be only writable by the trusted administrator and readable by the service. | -| 7 | The trusted administrator needs to check that during the boot process the trusted identity provider has successfully given the root trust bundle to the service. | -| 8 | The hardware descriptors should only be accessible by trusted privileged processes. | -| 9 | The Listener endpoint should be put in a location that only the Parsec service and the trusted administrator can access. | -| *10* | *A set of mutually trusted clients has restricted read-write access to the service IPC endpoint.* | +| ID | Justification | +|------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| 0 | A trusted administrator should start the service in such a way that un-privileged processes cannot send signals to the service. | +| 1 | A trusted administrator should check the validity of the providers and hardware modules written in the service's configuration before starting/reloading it. | +| 2 | Clients need to know from a trusted source that a trusted Parsec service is running on their machine so that they can trust the Listener endpoint. | +| 3 | Mappings should be put in a location that only the Parsec service and the trusted administrator can access. | +| 4 | The trusted administrator needs to be notified when any kind of resource is running out. | +| 5 | Parsec logs coming from the service binary should be redirected to a file that is only writable by the service and readable by the trusted administrator. | +| 6 | Parsec configuration file should be only writable by the trusted administrator and readable by the service. | +| 7 | The trusted administrator needs to check that during the boot process the trusted identity provider has successfully given the root trust bundle to the service. | +| 8 | The hardware descriptors should only be accessible by trusted privileged processes. | +| 9 | The Listener endpoint should be contained in a location that only the Parsec service and the trusted administrator can access (only they can create the endpoint). | +| *10* | *A set of mutually trusted clients has restricted read-write access to the service IPC endpoint.* | *Copyright 2020 Contributors to the Parsec project.*