From ad6b03c2da6c98c39c681d14b17e6d2486e4750e Mon Sep 17 00:00:00 2001 From: Hannah Hunter Date: Tue, 4 Apr 2023 17:32:44 -0400 Subject: [PATCH] add to overview and concept pages Signed-off-by: Hannah Hunter --- .../en/concepts/building-blocks-concept.md | 3 +- .../content/en/concepts/components-concept.md | 7 +++ daprdocs/content/en/concepts/overview.md | 3 +- .../building-blocks/cryptography/_index.md | 6 +-- .../cryptography/cryptography-overview.md | 54 +++++++++++++++++++ .../cryptography/howto-cryptography.md | 9 ++++ .../en/reference/api/cryptography_api.md | 14 +++++ .../supported-cryptography/_index.md | 6 ++- 8 files changed, 96 insertions(+), 6 deletions(-) diff --git a/daprdocs/content/en/concepts/building-blocks-concept.md b/daprdocs/content/en/concepts/building-blocks-concept.md index 0bdeaed19..ba9fe7b9b 100644 --- a/daprdocs/content/en/concepts/building-blocks-concept.md +++ b/daprdocs/content/en/concepts/building-blocks-concept.md @@ -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. \ No newline at end of file +| [**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. \ No newline at end of file diff --git a/daprdocs/content/en/concepts/components-concept.md b/daprdocs/content/en/concepts/components-concept.md index ae372ec2b..50b2c00df 100644 --- a/daprdocs/content/en/concepts/components-concept.md +++ b/daprdocs/content/en/concepts/components-concept.md @@ -108,6 +108,13 @@ A [workflow]({{< ref workflow-overview.md >}}) is custom application logic that +### 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. diff --git a/daprdocs/content/en/concepts/overview.md b/daprdocs/content/en/concepts/overview.md index 1d19e3aad..7caf78e7a 100644 --- a/daprdocs/content/en/concepts/overview.md +++ b/daprdocs/content/en/concepts/overview.md @@ -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 diff --git a/daprdocs/content/en/developing-applications/building-blocks/cryptography/_index.md b/daprdocs/content/en/developing-applications/building-blocks/cryptography/_index.md index fbbf05c7d..749b89706 100644 --- a/daprdocs/content/en/developing-applications/building-blocks/cryptography/_index.md +++ b/daprdocs/content/en/developing-applications/building-blocks/cryptography/_index.md @@ -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" --- \ No newline at end of file diff --git a/daprdocs/content/en/developing-applications/building-blocks/cryptography/cryptography-overview.md b/daprdocs/content/en/developing-applications/building-blocks/cryptography/cryptography-overview.md index e69de29bb..a92447ddd 100644 --- a/daprdocs/content/en/developing-applications/building-blocks/cryptography/cryptography-overview.md +++ b/daprdocs/content/en/developing-applications/building-blocks/cryptography/cryptography-overview.md @@ -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 >}}) \ No newline at end of file diff --git a/daprdocs/content/en/developing-applications/building-blocks/cryptography/howto-cryptography.md b/daprdocs/content/en/developing-applications/building-blocks/cryptography/howto-cryptography.md index e69de29bb..24723b0d9 100644 --- a/daprdocs/content/en/developing-applications/building-blocks/cryptography/howto-cryptography.md +++ b/daprdocs/content/en/developing-applications/building-blocks/cryptography/howto-cryptography.md @@ -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. \ No newline at end of file diff --git a/daprdocs/content/en/reference/api/cryptography_api.md b/daprdocs/content/en/reference/api/cryptography_api.md index 8a61862a4..4f4c58c0b 100644 --- a/daprdocs/content/en/reference/api/cryptography_api.md +++ b/daprdocs/content/en/reference/api/cryptography_api.md @@ -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 diff --git a/daprdocs/content/en/reference/components-reference/supported-cryptography/_index.md b/daprdocs/content/en/reference/components-reference/supported-cryptography/_index.md index 5d1a3b93a..5b1c30a00 100644 --- a/daprdocs/content/en/reference/components-reference/supported-cryptography/_index.md +++ b/daprdocs/content/en/reference/components-reference/supported-cryptography/_index.md @@ -5,4 +5,8 @@ linkTitle: "Cryptography" weight: 7000 description: The supported cryptography components that interface with Dapr no_list: true ---- \ No newline at end of file +--- + + \ No newline at end of file