# Set Up Zero-Trust

This guide will help you set up a secure, zero-trust environment in Grey Matter to achieve the following:

* Establish trust in user identities
* Enforce adaptive and risk-based policies
* Enable secure access to all apps
* Enforce transaction and data security

Grey Matter uses [SPIRE](https://spiffe.io/spire/) to enable zero-trust security. For more information about how Grey Matter uses SPIRE, see the [security documentation](https://greymatter.gitbook.io/grey-matter-documentation/1.7-beta/usage/security/spire).

Learn more about Grey Matter's approach to zero-trust security here.

## Prerequisites

* Unix shell and Decipher account
* `helm` and `kubectl` installed
* A Kubernetes or OpenShift deployment of Grey Matter with SPIRE enabled
  * To do this, install using the Grey Matter Helm Charts with `global.spire.enabled` true

{% hint style="success" %}
Learn more about the SPIRE configuration on the [SPIRE Server](https://github.com/spiffe/spire/blob/master/doc/spire_agent.md) and [SPIRE Agent](https://github.com/spiffe/spire/blob/master/doc/spire_server.md) documentation.
{% endhint %}

## Step 1: Install

To install Grey Matter using SPIRE, verify that `global.spire.enabled` is true (the default) for your helm charts setup and [install Grey Matter](https://greymatter.gitbook.io/grey-matter-documentation/1.7-beta/installation/installation-kubernetes).

## Step 2: Deploy a new service

For a full walkthrough of an example service deployment in a SPIRE enabled environment, see [the service deployment guide](https://greymatter.gitbook.io/grey-matter-documentation/1.7-beta/guides/launch-service-k8s).

To adapt an existing service deployment to enable SPIRE, add this environment variable to the sidecar container:

```yaml
- name: SPIRE_PATH
  value: "/run/spire/socket/agent.sock"
```

Then add the following to the deployment volumes:

```yaml
volumes:
  - name: spire-socket
    hostPath:
      path: /run/spire/socket
      type: DirectoryOrCreate
```

and mount it into the sidecar container as:

```yaml
volumeMounts:
  - name: spire-socket
    mountPath: /run/spire/socket
    readOnly: false
```

This creates the Unix socket over which the sidecar will communicate with the SPIRE agent.

## Step 3: Mesh configurations

There are several updates to make to the mesh configurations for a new service to enable SPIRE. The following describe updates necessary to configure ingress to the service using SPIRE, if your service also has egress actions, check out the [Deploy Service for Ingress/Egress Actions Guide](https://greymatter.gitbook.io/grey-matter-documentation/1.7-beta/guides/fabric-guides/configure-egress-ingress).

### Domain

If you have existing mesh configurations for this service in a non-SPIRE installation, remove any [`ssl_config`](https://greymatter.gitbook.io/grey-matter-documentation/1.7-beta/reference/api/fabric-api/domain/listener-ssl-config) from the ingress domain object, but keep `force_https` to true. The domain should look like [the example domain here](https://greymatter.gitbook.io/grey-matter-documentation/1.7-beta/launch-service-k8s#domain).

### Listener

The [`secret`](https://greymatter.gitbook.io/grey-matter-documentation/1.7-beta/reference/api/fabric-api/listener/secret) of the listener object is used to configure ingress mTLS using SPIRE.

If you installed Grey Matter using the helm charts, each deployment should have a label with key `greymatter.io/control` and value the name of the service (see [cluster label](https://greymatter.gitbook.io/grey-matter-documentation/1.7-beta/usage/discovery/kubernetes#cluster-label)). This value will be used to indicate the SPIFFE ID for a sidecar.

Let {service-name} be the value of the label `greymatter.io/control` in your service deployment. Add the following `secret` to your listener object:

```javascript
"secret": {
  "secret_key": "{service-name}-secret",
  "secret_name": "spiffe://quickstart.greymatter.io/{service-name}",
  "secret_validation_name": "spiffe://quickstart.greymatter.io",
  "subject_names": [
    "spiffe://quickstart.greymatter.io/edge"
  ],
  "ecdh_curves": [
    "X25519:P-256:P-521:P-384"
  ]
}
```

Once this is configured, the sidecar will use its SPIFFE certificate for ingress traffic on this listener.

### Edge to new service routing

The cluster created for edge to connect to the service will need a similar update for egress traffic to the new service. Remove any `ssl_config` on the `edge-to-{service-name}-cluster` and set the `secret` instead:

```javascript
"secret": {
  "secret_key": "secret-edge-secret",
  "secret_name": "spiffe://quickstart.greymatter.io/edge",
  "secret_validation_name": "spiffe://quickstart.greymatter.io",
  "subject_names": [
    "spiffe://quickstart.greymatter.io/{service-name}"
  ],
  "ecdh_curves": [
    "X25519:P-256:P-521:P-384"
  ]
}
```

[Shared rules](https://greymatter.gitbook.io/grey-matter-documentation/1.7-beta/reference/api/fabric-api/shared_rules) and [routes](https://greymatter.gitbook.io/grey-matter-documentation/1.7-beta/reference/api/fabric-api/route) should be configured as usual.

## Step 4: Test

When you setup services to participate in the mesh, SPIFFE identities are setup for them. This means that the service will get a certificate that is made for that service. As an example of probing into data, you can use openssl to verify that it is setup to use SPIFFE.

In a kubernetes setup, you can find the ip of your deployment with `kubectl describe pod {pod-id} | grep IP`. Copy this ip and use openssl to check the certificate. You can use openssl from within the data container -

```bash
kubectl exec -it data-internal-0 -c data-internal -- /bin/sh
```

and then to check your service:

```bash
openssl s_client --connect {IP}:10808
```

or

```bash
openssl s_client --connect {IP}:10808 | openssl x509 -text --noout
```

You should see from the info that the certificate chain and SAN that the certificate your service is presenting is from SPIRE.

You can also verify that SDS is working for your service by execing into its sidecar pod `kubectl exec -it {pod-id} -c sidecar -- /bin/sh` and running `curl localhost:8001/certs`. If the sidecar is configured properly, its SPIFFE certificate will be listed there.

## Questions

{% hint style="success" %}
**Need help with your installation?**

Create an account at [Grey Matter Support](https://support.greymatter.io/support/home) to reach our team.
{% endhint %}