Update TLS and security docs (#481)

* update tls

* Update README.md

* Update README.md

* Update README.md

* address nits

* fix nits

* update images

* remove DS_Store file

* update image

Co-authored-by: Mark Fussell <mfussell@microsoft.com>

concepts/security/README.md

@@ -1,7 +1,8 @@
 # Security
 
-- [Dapr-to-App Communication](#dapr-to-app-communication)
-- [Dapr-to-Dapr Communication](#dapr-to-dapr-communication)
+- [Sidecar-to-App Communication](#sidecar-to-app-communication)
+- [Sidecar-to-Sidecar Communication](#sidecar-to-sidecar-communication)
+- [Sidecar-to-system-services-communication](#Sidecar-to-system-services-communication)
 - [Component namespace scopes and secrets](#Component-namespace-scopes-and-secrets)
 - [Network Security](#network-security)
 - [Bindings Security](#bindings-security)
@@ -9,22 +10,22 @@
 - [Management Security](#management-security)
 
 
-## Dapr-to-App communication
+## Sidecar-to-App communication
 
-Dapr sidecar runs close to the application through **localhost**. Dapr assumes it runs in the same security domain of the application. So, there are no authentication, authorization or encryption between a Dapr sidecar and the application.
+The Dapr sidecar runs close to the application through **localhost**. Dapr assumes it runs in the same security domain of the application. As a result, there are no authentication, authorization or encryption between a Dapr sidecar and the application.
 
-## Dapr-to-Dapr communication
+## Sidecar-to-Sidecar communication
 
-Dapr includes an on by default, automatic mutual TLS that provides in-transit encryption for traffic between Dapr instances.
-To achieve this, Dapr leverages a system component named `Sentry` which acts as a Certificate Authority (CA) and signs workload certificate requests originating from the Dapr instances.
+Dapr includes an "on by default", automatic mutual TLS that provides in-transit encryption for traffic between Dapr sidecars.
+To achieve this, Dapr leverages a system service named `Sentry` which acts as a Certificate Authority (CA) and signs workload (app) certificate requests originating from the Dapr sidecar.
 
 Dapr also manages workload certificate rotation, and does so with zero downtime to the application.
 
-Sentry, the CA component, automatically creates and persists self signed root certificates valid for one year, unless existing root certs have been provided by the user.
+Sentry, the CA service, automatically creates and persists self signed root certificates valid for one year, unless existing root certs have been provided by the user.
 
-When root certs are replaced (secret in Kubernetes mode and filesystem for self hosted mode), Sentry will pick them up and re-build the trust chain without needing to restart, with zero downtime to Sentry.
+When root certs are replaced (secret in Kubernetes mode and filesystem for self hosted mode), the Sentry picks them up and re-builds the trust chain without needing to restart, with zero downtime to Sentry.
 
-When a new Dapr sidecar initializes, it first checks if mTLS is enabled. If it is, an ECDSA private key and certificate signing request are generated and sent to Sentry via a gRPC interface. The communication between the Dapr sidecar and Sentry is authenticated using the trust chain cert, which is injected into each Dapr instance by the Dapr sidecar injector.
+When a new Dapr sidecar initializes, it first checks if mTLS is enabled. If it is, an ECDSA private key and certificate signing request are generated and sent to Sentry via a gRPC interface. The communication between the Dapr sidecar and Sentry is authenticated using the trust chain cert, which is injected into each Dapr instance by the Dapr Sidecar Injector system service.
 
 In a Kubernetes cluster, the secret that holds the root certificates is scoped to the namespace in which the Dapr components are deployed to and is only accessible by the Dapr system pods.
 
@@ -33,16 +34,34 @@ Dapr also supports strong identities when deployed on Kubernetes, relying on a p
 By default, a workload cert is valid for 24 hours and the clock skew is set to 15 minutes.
 
 Mutual TLS can be turned off/on by editing the default configuration that is deployed with Dapr via the `spec.mtls.enabled` field.
-This can be done for both Kubernetes and self hosted modes.
-Specific details for how to do that can be found [here](../../howto/configure-mtls).
-
-### mTLS in Kubernetes
-
-<a href="https://ibb.co/4VXWJ3d"><img src="https://i.ibb.co/rwzkvNs/Screen-Shot-2020-02-10-at-8-35-59-PM.png" alt="Screen-Shot-2020-02-10-at-8-35-59-PM" border="0"></a>
+This can be done for both Kubernetes and self hosted modes. Details for how to do this can be found [here](../../howto/configure-mtls).
 
 ### mTLS self hosted
+The diagram below shows how the Sentry system service issues certificates for applications based on the root/issuer certificate that is provided by an operator or generated by the Sentry service as stored in a file
 
-<a href="https://ibb.co/XWFYsfY"><img src="https://i.ibb.co/rQ5d6Kd/Screen-Shot-2020-02-10-at-8-34-33-PM.png" alt="Screen-Shot-2020-02-10-at-8-34-33-PM" border="0"></a>
+![mTLS self hosted](../../images/security-mTLS-sentry-selfhosted.png)
+
+### mTLS in Kubernetes
+The diagram below shows how the Sentry system service issues certificates for applications based on the root/issuer certificate that is provided by an operator or generated by the Sentry service as stored as a Kubernetes secret
+
+![mTLS Kubernetes](../../images/security-mTLS-sentry-kubernetes.png)
+
+## Sidecar to system services communication
+
+In addition to automatic mTLS between Dapr sidecars, Dapr offers mandatory mTLS between the Dapr sidecar and the Dapr system services, namely the Sentry service (Certificate Authority), Placement service (actor placement) and the Kubernetes Operator.
+
+When mTLS is enabled, Sentry writes the root and issuer certificates to a Kubernetes secret that is scoped to the namespace where the control plane is installed. In self hosted mode, Sentry writes the certificates to a configurable filesystem path.
+
+In Kubernetes, when the Dapr system services start, they automatically mount the secret containing the root and issuer certs and use those to secure the gRPC server that is used by the Dapr sidecar.  
+
+In self hosted mode, each system service can be mounted to a filesystem path to get the credentials.
+
+When the Dapr sidecars initialize, they authenticate with the system services using the workload cert that was issued to them by Sentry, the Certificate Authority.
+
+### mTLS to system services in Kubernetes
+The diagram below shows secure communication between the Dapr sidecar and the Dapr Sentry (Certificate Authority), Placement (actor placement) and the Kubernetes Operator system services
+
+![mTLS System Services on Kubernetes](../../images/security-mTLS-dapr-system-services.png)
 
 ## Component namespace scopes and secrets
 
@@ -50,11 +69,13 @@ Dapr components are namespaced. That means a Dapr runtime sidecar instance can o
 
 Dapr components uses Dapr's built-in secret management capability to manage secrets. See the [secret topic](../secrets/README.md) for more details.
 
+In addition, Dapr offers application-level scoping for components by allowing users to specify which applications can consume given components.For more information about application level scoping, see [here](../../howto/components-scopes#application-access-to-components-with-scopes)
+
 ## Network security
 
 You can adopt common network security technologies such as network security groups (NSGs), demilitarized zones (DMZs) and firewalls to provide layers of protections over your networked resources.
 
-For example, unless configured to talk to an external binding target, Dapr sidecars don’t open connections to the Internet. And most binding implementations use outbound connections only. You can design your firewall rules to allow outbound connections only through designated ports.
+For example, unless configured to talk to an external binding target, Dapr sidecars don’t open connections to the internet. And most binding implementations use outbound connections only. You can design your firewall rules to allow outbound connections only through designated ports.
 
 ## Bindings security
 
@@ -64,10 +85,12 @@ Authentication with a binding target is configured by the binding’s configurat
 
 Dapr doesn't transform the state data from applications. This means Dapr doesn't attempt to encrypt/decrypt state data. However, your application can adopt encryption/decryption methods of your choice, and the state data remains opaque to Dapr.
 
+Dapr does not store any data at rest.
+
 Dapr uses the configured authentication method to authenticate with the underlying state store. And many state store implementations use official client libraries that generally use secured communication channels with the servers.
 
 ## Management security
 
 When deploying on Kubernetes, you can use regular [Kubernetes RBAC]( https://kubernetes.io/docs/reference/access-authn-authz/rbac/) to control access to management activities.
 
-When deploying on Azure Kubernetes Service (AKS), you can use [Azure Active Directory (AD) service principals]( https://docs.microsoft.com/en-us/azure/active-directory/develop/app-objects-and-service-principals) to control access to management activities and resource management.
+When deploying on Azure Kubernetes Service (AKS), you can use [Azure Active Directory (AD) service principals]( https://docs.microsoft.com/en-us/azure/active-directory/develop/app-objects-and-service-principals) to control access to management activities and resource management.

howto/configure-mtls/README.md

@@ -1,4 +1,4 @@
-# Setup and Configure Mutual TLS
+# Setup and configure mutual TLS
 
 Dapr supports in-transit encryption of communication between Dapr instances using Sentry, a central Certificate Authority.
 
@@ -10,26 +10,25 @@ If custom certificates have not been provided, Dapr will automatically create an
 In Kubernetes, the certs are persisted to a secret that resides in the namespace of the Dapr system pods, accessible only to them.
 In Self Hosted mode, the certs are persisted to disk. More information on that is shown below.
 
-## Sentry Configuration
+## Sentry configuration
 
 mTLS settings reside in a Dapr configuration file.
 The following file shows all the available settings for mTLS in a configuration resource:
 
-```
+```yaml
 apiVersion: dapr.io/v1alpha1
 kind: Configuration
 metadata:
   name: default
 spec:
   mtls:
-    enabled: true
+    enabled: "true"
     workloadCertTTL: "24h"
     allowedClockSkew: "15m"
 ```
 
 The file here shows the default configuration settings. The examples below show you how to change and apply this configuration to Sentry in Kubernetes and Self hosted modes.
 
-
 ## Kubernetes
 
 ### Setting up mTLS with the configuration resource
@@ -49,11 +48,26 @@ To make changes to the configuration resource, you can run the following command
 kubectl edit configurations/default --namespace <DAPR_NAMESPACE>
 ```
 
-Once the changes are saved, you need to restart the Sentry pod in order for the changes to take effect.
-You can restart Sentry using the following command:
+Once the changes are saved, perform a rolling update to the control plane:
 
 ```
-kubectl delete pod --selector=app=dapr-sentry --namespace <DAPR_NAMESPACE>
+kubectl rollout restart deploy/dapr-sentry -n <DAPR_NAMESPACE>
+kubectl rollout restart deploy/dapr-operator -n <DAPR_NAMESPACE>
+kubectl rollout restart deploy/dapr-placement -n <DAPR_NAMESPACE>
+```
+
+*Note: the sidecar injector does not need to be redeployed*
+
+### Disabling mTLS with Helm
+
+```bash
+kubectl create ns dapr-system
+
+helm install \
+  --set global.mtls.enabled=false \
+  --namespace dapr-system \
+  dapr \
+  dapr/dapr
 ```
 
 ### Viewing logs
@@ -86,7 +100,7 @@ This creates the root and issuer certs and keys.
 
 Install Helm and pass the root cert, issuer cert and issuer key to Sentry via configuration:
 
-```
+```bash
 kubectl create ns dapr-system
 
 helm install \
@@ -98,9 +112,32 @@ helm install \
   dapr/dapr
 ```
 
+### Updating Root or Issuer Certs
+
+If the Root or Issuer certs are about to expire, you can update them and restart the required system services.
+
+First, issue new certificates using the step above in [Bringing your own certificates](#bringing-your-own-certificates).
+
+Now that you have the new certificates, you can update the Kubernetes secret that holds them.
+Edit the Kubernetes secret:
+
+```
+kubectl edit secret dapr-trust-bundle -n <DAPR_NAMESPACE>
+```
+
+Replace the `ca.crt`, `issuer.crt` and `issuer.key` keys in the Kubernetes secret with their corresponding values from the new certificates.
+*__Note: The values must be base64 encoded__*
+
+If you signed the new cert root with a different private key, restart all Dapr-enabled pods.
+The recommended way to do this is to perform a rollout restart of your deployment:
+
+```
+kubectl rollout restart deploy/myapp
+```
+
 ## Self-hosted
 
-### Running Sentry System Service
+### Running Sentry system service
 
 In order to run Sentry, you can either build from source, or download a release binary from [here](https://github.com/dapr/dapr/releases).
 
@@ -114,7 +151,7 @@ mkdir -p $HOME/.dapr/certs
 
 Run Sentry locally with the following command:
 
-```
+```bash
 ./sentry --issuer-credentials $HOME/.dapr/certs --trust-domain cluster.local
 ```
 
@@ -134,7 +171,7 @@ metadata:
   name: default
 spec:
   mtls:
-    enabled: true
+    enabled: "true"
 ```
 
 If using the Dapr CLI, point Dapr to the config file above to run the Dapr instance with mTLS enabled:
@@ -145,7 +182,7 @@ dapr run --app-id myapp --config ./config.yaml node myapp.js
 
 If using `daprd` directly, use the following flags to enable mTLS:
 
-```
+```bash
 daprd --app-id myapp --enable-mtls --sentry-address localhost:50001 --config=./config.yaml
 ```
 
@@ -160,7 +197,7 @@ metadata:
   name: default
 spec:
   mtls:
-    enabled: true
+    enabled: "true"
     workloadCertTTL: "25s"
 ```
 
@@ -181,19 +218,30 @@ The next examples creates root and issuer certs and loads them with Sentry.
 
 Create the root certificate:
 
-```
+```bash
 step certificate create cluster.local ca.crt ca.key --profile root-ca --no-password --insecure
 ```
 
 Create the issuer certificate:
 
-```
+```bash
 step certificate create cluster.local issuer.crt issuer.key --ca ca.crt --ca-key ca.key --profile intermediate-ca --not-after 8760h --no-password --insecure
 ```
 
 This creates the root and issuer certs and keys.
 Place `ca.crt`, `issuer.crt` and `issuer.key` in a desired path (`$HOME/.dapr/certs` in the example below), and launch Sentry:
 
-```
+```bash
 ./sentry --issuer-credentials $HOME/.dapr/certs --trust-domain cluster.local
 ```
+
+### Updating Root or Issuer Certs
+
+If the Root or Issuer certs are about to expire, you can update them and restart the required system services.
+
+First, issue new certificates using the step above in [Bringing your own certificates](#bringing-your-own-certificates).
+
+Copy `ca.crt`, `issuer.crt` and `issuer.key` to the filesystem path of every configured system service, and restart the process or container.
+By default, system services will look for the credentials in `/var/run/dapr/credentials`.
+
+*Note:If you signed the cert root with a different private key, restart the Dapr instances.*