Skip to content

Commit

Permalink
Add recommendations for secure deployment
Browse files Browse the repository at this point in the history
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 <hugues.devalon@arm.com>
  • Loading branch information
hug-dev committed Jul 1, 2020
1 parent ece650e commit f898833
Show file tree
Hide file tree
Showing 6 changed files with 104 additions and 29 deletions.
5 changes: 3 additions & 2 deletions src/SUMMARY.md
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down Expand Up @@ -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)
Expand Down
11 changes: 11 additions & 0 deletions src/parsec_service/build_run.md
Original file line number Diff line number Diff line change
Expand Up @@ -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:

```````
Expand Down
55 changes: 45 additions & 10 deletions src/parsec_service/install_parsec_linux.md
Original file line number Diff line number Diff line change
@@ -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
Expand All @@ -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
Expand All @@ -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.*
5 changes: 1 addition & 4 deletions src/parsec_service/listeners.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.*
31 changes: 31 additions & 0 deletions src/threat_model/secure_deployment.md
Original file line number Diff line number Diff line change
@@ -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.*
26 changes: 13 additions & 13 deletions src/threat_model/threat_model.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.*

0 comments on commit f898833

Please sign in to comment.