Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add recommendations for secure deployment #41

Merged
merged 2 commits into from
Jul 1, 2020
+104 −29
Merged

Add recommendations for secure deployment #41

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
f898833
Add recommendations for secure deployment
hug-dev Jun 26, 2020
78a82ec
Merge branch 'master' into secure_deployment
hug-dev Jul 1, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 3 additions & 2 deletions src/SUMMARY.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,8 @@
- [Service API coverage](service_api_coverage.md)
- [Clients API coverage](clients_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 @@ -38,7 +39,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
View file
Open in desktop
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
View file
Open in desktop
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
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should the config file be in /tmp/parsec/ with permissions 700?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actually, that folder might be volatile 😞

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes! There are other permanent locations where the different files could go, that are used by other services, but the advantage of using the parsec user home folder and /tmp is that the installation steps rely less on using sudo.

```

Create the Parsec socket directory.

```
mkdir /tmp/parsec
```

In a deployment **without an Identity Provider**, create the `parsec-clients` group and set the
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think we need to set a bit of context here around identity provider, which may be an unfamiliar term and could confuse the reader. In fact, since we haven't integrated any identity providers yet, I'm wondering whether we should just assume the absence of it for now, and explain that the socket needs to be protected at deployment time because there is currently no runtime mechanism for Parsec to validate its clients. (We can then explain that future deployments will have more flexible means of protection, and talk about identity providers in that context). Without some context, I think there's a danger that these recommendations could seem arbitrary.

Copy link
Member

@ionut-arm ionut-arm Jun 29, 2020 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Alright! We'll expand on the idea of Identity Provider

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I am personally more in favour of the option where we leave the Identity Provider sections but expand on what it is and the context. To do so, we can point out to the threat model where we make the same distinction of a deployment with and a without an IP:

Parsec could also be deployed in an environment where all clients trust each other and there is no Identity Provider present, and this would lead to some changes to the Threat Model. These changes will be written in italic.

And also point to the System Architecture where we explain what the Identity Provider is.

Having to create a parsec-clients group and adding each and every client that wants to use parsec in it is quite a burden for administrators so it is nice, I think, for them to see "the light at the end of the tunnel" when an IP would exist.

correct permissions on the socket folder. Mutually trusted Parsec Clients will need to be in that
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What is meant by "mutually trusted" Parsec clients? The word "mutually" seems to suggest clients that trust each other. But if we really mean clients that are trusted by the service, then we can probably scrub the word "mutually" here.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, the idea is that the clients trust each other (i.e. they won't use each other's identities) - this is needed because if you have multiple clients and no identity provider, you must have some sort of trust in the other clients

Copy link
Member Author

@hug-dev hug-dev Jun 30, 2020 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

To add to what Ionut said, this is directly coming from operational mitigation 10 of the service TM:

A set of mutually trusted clients has restricted read-write access to the service IPC endpoint.

Since any client in that group can access the keys of the other ones, we seemed to think that the trust should be in between the clients.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Added the following paragraph:

+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**.

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
View file
Open in desktop
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
View file
Open in desktop
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
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -324,18 +324,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.* |
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Again I'm confused by the sense of "mutual" here. Do we mean that the clients trust each other?


*Copyright 2020 Contributors to the Parsec project.*