add to overview and concept pages

Signed-off-by: Hannah Hunter <hannahhunter@microsoft.com>
This commit is contained in:
Hannah Hunter 2023-04-04 17:32:44 -04:00
parent fbe0c7e2c2
commit ad6b03c2da
8 changed files with 96 additions and 6 deletions

View File

@ -29,4 +29,5 @@ The following are the building blocks provided by Dapr:
| [**Secrets**]({{< ref "secrets-overview.md" >}}) | `/v1.0/secrets` | Dapr provides a secrets building block API and integrates with secret stores such as public cloud stores, local stores and Kubernetes to store the secrets. Services can call the secrets API to retrieve secrets, for example to get a connection string to a database.
| [**Configuration**]({{< ref "configuration-api-overview.md" >}}) | `/v1.0-alpha1/configuration` | The Configuration API enables you to retrieve and subscribe to application configuration items for supported configuration stores. This enables an application to retrieve specific configuration information, for example, at start up or when configuration changes are made in the store.
| [**Distributed lock**]({{< ref "distributed-lock-api-overview.md" >}}) | `/v1.0-alpha1/lock` | The distributed lock API enables you to take a lock on a resource so that multiple instances of an application can access the resource without conflicts and provide consistency guarantees.
| [**Workflows**]({{< ref "workflow-overview.md" >}}) | `/v1.0-alpha1/workflow` | The Workflow API enables you to define long running, persistent processes or data flows that span multiple microservices using Dapr workflows or workflow components. The Workflow API can be combined with other Dapr API building blocks. For example, a workflow can call another service with service invocation or retrieve secrets, providing flexibility and portability.
| [**Workflows**]({{< ref "workflow-overview.md" >}}) | `/v1.0-alpha1/workflow` | The Workflow API enables you to define long running, persistent processes or data flows that span multiple microservices using Dapr workflows or workflow components. The Workflow API can be combined with other Dapr API building blocks. For example, a workflow can call another service with service invocation or retrieve secrets, providing flexibility and portability.
| [**Cryptography**]({{< ref "cryptography-overview.md" >}}) | `/v1.0-alpha1/crypto` | The Cryptography API enables you to perform operations, such as encrypting and decrypting messages, and calculating and verifying digital signatures. Using different comopnetns, Dapr translates operation calls into the correct format for the supported backend. Dapr uses algorithms configured to forbid the usage of unsafe algorithms and operations.

View File

@ -108,6 +108,13 @@ A [workflow]({{< ref workflow-overview.md >}}) is custom application logic that
<!--- [List of supported workflows]()
- [Workflow implementations](https://github.com/dapr/components-contrib/tree/master/workflows)-->
### Cryptography
[Cryptography]({{< ref cryptography-overview.md >}}) components perform API operations on supported backends, such as encrypting and decrypting messages, and calculating and verifying digital signatures.
- [List of supported cryptography components](todo)
- [Cryptography implementations](todo)
### Middleware
Dapr allows custom [middleware]({{< ref "middleware.md" >}}) to be plugged into the HTTP request processing pipeline. Middleware can perform additional actions on an HTTP request (such as authentication, encryption, and message transformation) before the request is routed to the user code, or the response is returned to the client. The middleware components are used with the [service invocation]({{< ref "service-invocation-overview.md" >}}) building block.

View File

@ -44,7 +44,8 @@ Each of these building block APIs is independent, meaning that you can use one,
| [**Secrets**]({{< ref "secrets-overview.md" >}}) | The secrets management API integrates with public cloud and local secret stores to retrieve the secrets for use in application code.
| [**Configuration**]({{< ref "configuration-api-overview.md" >}}) | The configuration API enables you to retrieve and subscribe to application configuration items from configuration stores.
| [**Distributed lock**]({{< ref "distributed-lock-api-overview.md" >}}) | The distributed lock API enables your application to acquire a lock for any resource that gives it exclusive access until either the lock is released by the application, or a lease timeout occurs.
| [**Workflows**]({{< ref "workflow-overview.md" >}}) | `/v1.0-alpha1/workflow` | The workflow API can be combined with other Dapr building blocks to define long running, persistent processes or data flows that span multiple microservices using Dapr workflows or workflow components.
| [**Workflows**]({{< ref "workflow-overview.md" >}}) | The workflow API can be combined with other Dapr building blocks to define long running, persistent processes or data flows that span multiple microservices using Dapr workflows or workflow components.
| [**Cryptography**]({{< ref "cryptography-overview.md" >}}) | Like with secret stores, Dapr's cryptography API offers an abstraction layer on top of key vaults. This layer allows you to perform operations like encrypting and decrypting messages and calculating and verifying digital signatures.
## Sidecar architecture

View File

@ -1,7 +1,7 @@
---
type: docs
title: "Workflow"
linkTitle: "Workflow"
title: "Cryptography"
linkTitle: "Cryptography"
weight: 110
description: "Orchestrate logic across various microservices"
description: "Perform cryptographic operations without having to access raw key material"
---

View File

@ -0,0 +1,54 @@
---
type: docs
title: Cryptography overview
linkTitle: Overview
weight: 1000
description: "Overview of Dapr Cryptography"
---
With the Cryptography API, you can leverage cryptography in a safe and consistent way. Dapr exposes an API that allows you to ask Dapr to perform operations such as encrypting and decrypting messages, and calculating and verifying digital signatures.
## Why Cryptography?
Modern applications make extensive use of cryptography, which, when implemented correctly, can make solutions safer even when data is compromised. In certain cases, you may be required to use cryptography to comply with industry regulations (banking) or legal requirements (GDPR).
However, leveraging cryptography is difficult; you need to:
- Pick the right algorithms and options
- Learn the proper way to manage and protect keys
- Navigate operational complexities when your team wants limit access to cryptographic key material
Organizations have increasingly used tools and services to perform crypto outside of applications, including:
- Azure Key Vault, AWS KMS, Google Cloud KMS, etc.
- On-prem HSM products like Thales Luna
While those products/services perform the same or very similar operations, their APIs are very different.
## Cryptography in Dapr
Just like how Dapr offers an abstraction on top of secret stores, Dapr offers an abstraction layer on top of key vaults.
With this abstraction layer, you can perform cryptographic operations without having to access raw key material. Dapr provides a selection of correctly configured algorithms that forbid the usage of unsafe algorithms and operations.
Todo: diagram
Using the cryptography in Dapr:
- Makes it easier for you to perform cryptographic operations in a safe way. Dapr provides safeguards against using unsafe algorithms, or using algorithms with unsafe options.
- Keeps keys outside of applications. Applications never see key material, but can request the vault to perform operations with the keys.
- Allows greater separation of concerns. By using external vaults, only authorized teams can access private/shared key materials.
- Simplifies key management and key rotation. Keys are managed in the vault and outside of the application, and they can be rotated without needing the developers to be involved (or even without restarting the apps).
- Enables better audit logging to monitor when operations are performed with keys in the vault.
[Learn more about the cryptography API]({{< ref cryptography_API.md >}})
## Features
Todo: cryptography building block features organized under header 3 sections.
## Next steps
{{< button text="Use the cryptography API >>" page="howto-cryptography.md" >}}
## Related links
- [Cryptography overview]({{< ref cryptography-overview.md >}})
- [Cryptography API reference]({{< ref cryptography_api.md >}})

View File

@ -0,0 +1,9 @@
---
type: docs
title: "How to: Use the cryptography APIs"
linkTitle: "How to: Use cryptography"
weight: 2000
description: "Overview of Dapr Cryptography"
---
Todo.

View File

@ -7,6 +7,8 @@ weight: 900
---
## Component format
Todo: update component format to correct format for cryptography
A Dapr `crypto.yaml` component file has the following structure:
```yaml
apiVersion: dapr.io/v1alpha1
@ -28,3 +30,15 @@ spec:
## Supported workflow methods
Todo: organize the following into the correct format for an API doc.
The new building block would feature 7 APIs:
/encrypt: encrypts arbitrary data using a key stored in the vault. It supports symmetric and asymmetric ciphers, depending on the type of key in use (and the types of keys supported by the vault).
/decrypt: decrypts arbitrary data, performing the opposite of what /encrypt does.
/wrapkey: wraps keys using other keys stored in the vault. This is exactly like encrypting data, but it expects inputs to be formatted as keys (for example formatted as JSON Web Key) and it exposes additional algorithms not available when encrypting general data (like AES-KW)
/unwrapkey: un-wraps (decrypts) keys, performing the opposite of what /wrap does
/sign: signs an arbitrary message using an asymmetric key stored in the vault (we could also consider offering HMAC here, using symmetric keys, although not widely supported by the vault services)
/verify: verifies a digital signature over an arbitrary message, using an asymmetric key stored in the vault (same: we may be able to offer HMAC too)
/getkey: this can be used only with asymmetric keys stored in the vault, and returns the public part of the key

View File

@ -5,4 +5,8 @@ linkTitle: "Cryptography"
weight: 7000
description: The supported cryptography components that interface with Dapr
no_list: true
---
---
<!--Different components would be developed to perform those operations on supported backends such as the products/services listed above. Dapr would "translate" these calls into whatever format the backends require. Dapr never sees the private/shared keys, which remain safely stored inside the vaults.
Additionally, we could offer a "local" crypto component where keys are stored as Kubernetes secrets and cryptographic operations are performed within the Dapr sidecar. Although this is not as secure as using an external key vault, it still offers some benefits such as using standardized APIs and separation of concerns/roles with regards to key management.-->