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 ba73255a7..f7f6e3c25 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 @@ -51,4 +51,5 @@ Todo: cryptography building block features organized under header 3 sections. ## Related links - [Cryptography overview]({{< ref cryptography-overview.md >}}) -- [Cryptography API reference]({{< ref cryptography_api.md >}}) \ No newline at end of file +- [Cryptography API reference]({{< ref cryptography_api.md >}}) +- [Cryptography component specs]({{< ref supported-cryptography >}}) \ 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 24723b0d9..91a18f54b 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 @@ -3,7 +3,105 @@ type: docs title: "How to: Use the cryptography APIs" linkTitle: "How to: Use cryptography" weight: 2000 -description: "Overview of Dapr Cryptography" +description: "Learn how to encrypt and decrypt files" --- -Todo. \ No newline at end of file +Now that you've read about [Cryptography as a Dapr building block]({{< ref cryptography-overview.md >}}), let's walk through using the [high-level cryptography APIs]({{< ref cryptography_api.md >}}) with the Dapr SDKs. + +{{% alert title="Note" color="primary" %}} +Dapr Cryptography is currently in alpha. +{{% /alert %}} + +## Encrypt + +To read and encrypt a file, add the `Encrypt` gRPC API to your project. + +{{< tabs "Go" >}} + +{{% codetab %}} + + + +```go +out, err := sdkClient.Encrypt(context.Background(), rf, dapr.EncryptOptions{ + // These are the 3 required parameters + ComponentName: "mycryptocomponent", + KeyName: "mykey", + Algorithm: "RSA", +}) +``` + +{{% /codetab %}} + +{{< /tabs >}} + +The following example puts the `Encrypt` API in context, with code that reads the file, encrypts it, then stores the result in another file. + +{{< tabs "Go" >}} + +{{% codetab %}} + + + +```go +// Input file, clear-text +rf, err := os.Open("input") +if err != nil { + panic(err) +} +defer rf.Close() + +// Output file, encrypted +wf, err := os.Create("output.enc") +if err != nil { + panic(err) +} +defer wf.Close() + +// Encrypt the data using Dapr +out, err := sdkClient.Encrypt(context.Background(), rf, dapr.EncryptOptions{ + // These are the 3 required parameters + ComponentName: "mycryptocomponent", + KeyName: "mykey", + Algorithm: "RSA", +}) +if err != nil { + panic(err) +} + +// Read the stream and copy it to the out file +n, err := io.Copy(wf, out) +if err != nil { + panic(err) +} +fmt.Println("Written", n, "bytes") +``` + +{{% /codetab %}} + +{{< /tabs >}} + +## Decrypt + +To decrypt a file, add the `Decrypt` gRPC API to your project. + +{{< tabs "Go" >}} + +{{% codetab %}} + + + +```go +out, err := sdkClient.Decrypt(context.Background(), rf, dapr.EncryptOptions{ + // Only required option is the component name + ComponentName: "mycryptocomponent", +}) +``` + +{{% /codetab %}} + +{{< /tabs >}} + +## Next steps +- [Cryptography API reference]({{< ref cryptography_api.md >}}) +- [Cryptography component specs]({{< ref supported-cryptography >}}) \ No newline at end of file diff --git a/daprdocs/content/en/operations/support/support-preview-features.md b/daprdocs/content/en/operations/support/support-preview-features.md index 71c649fe6..ef8070750 100644 --- a/daprdocs/content/en/operations/support/support-preview-features.md +++ b/daprdocs/content/en/operations/support/support-preview-features.md @@ -21,6 +21,8 @@ For CLI there is no explicit opt-in, just the version that this was first made a | **Pluggable components** | Allows creating self-hosted gRPC-based components written in any language that supports gRPC. The following component APIs are supported: State stores, Pub/sub, Bindings | N/A | [Pluggable components concept]({{}})| v1.9 | | **Multi-App Run** | Configure multiple Dapr applications from a single configuration file and run from a single command | `dapr run -f` | [Multi-App Run]({{< ref multi-app-dapr-run.md >}}) | v1.10 | | **Workflows** | Author workflows as code to automate and orchestrate tasks within your application, like messaging, state management, and failure handling | N/A | [Workflows concept]({{< ref "components-concept#workflows" >}})| v1.10 | +| **Crytpography** | leverage cryptography in a safe and consistent way. | N/A | [Cryptography concept]({{< ref "components-concept#cryptography" >}})| v1.11 | + ### Streaming for HTTP service invocation diff --git a/daprdocs/content/en/reference/api/cryptography_api.md b/daprdocs/content/en/reference/api/cryptography_api.md index 31e1fc3d8..cd2e6a4c3 100644 --- a/daprdocs/content/en/reference/api/cryptography_api.md +++ b/daprdocs/content/en/reference/api/cryptography_api.md @@ -5,11 +5,11 @@ linkTitle: "Cryptography API" description: "Detailed documentation on the cryptography API" 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 kind: Component @@ -22,22 +22,49 @@ spec: - name: value: ``` + | Setting | Description | | ------- | ----------- | -| `metadata.name` | The name of the workflow component. | -| `spec/metadata` | Additional metadata parameters specified by workflow component | +| `metadata.name` | The unique name of the workflow component. | +| `spec.type` | The component type used. Example: `crypto.jwks`, `crypto.azure.keyvault` | +| `spec.metadata` | Additional metadata parameters specified by workflow component | +[Learn more about the available cryptography components.]({{< ref supported-cryptography >}}) +## Supported cryptography APIs -## Supported workflow methods +The cryptography building block supports two high-level APIs: +- `Encrypt` +- `Decrypt` -Todo: organize the following into the correct format for an API doc. +These APIs allow you to encrypt and decrypt files of arbitrary lenght (up to 256TB) while working on a straem of data. -The new building block would feature 7 APIs: +### Encrypt -/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) -/getkey: this can be used only with asymmetric keys stored in the vault, and returns the public part of the key +To encrypt data, implement the `Encrypt` API: + +```go +// Encrypt the data using Dapr +out, err := sdkClient.Encrypt(context.Background(), rf, dapr.EncryptOptions{ + // These are the 3 required parameters + ComponentName: "mycryptocomponent", + KeyName: "mykey", + Algorithm: "RSA", +}) +``` + +### Decrypt + +To decrypt data, implement the `Decrypt` API: + +```go +// Decrypt the data using Dapr +out, err := sdkClient.Decrypt(context.Background(), rf, dapr.EncryptOptions{ + // Only required option is the component name + ComponentName: "mycryptocomponent", +}) +``` + +## Next steps +- [Cryptography building block documentation]({{< ref cryptography >}}) +- [Cryptography components]({{< ref supported-cryptography >}}) \ No newline at end of file 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 5b1c30a00..d042ab10e 100644 --- a/daprdocs/content/en/reference/components-reference/supported-cryptography/_index.md +++ b/daprdocs/content/en/reference/components-reference/supported-cryptography/_index.md @@ -7,6 +7,6 @@ description: The supported cryptography components that interface with Dapr no_list: true --- - \ No newline at end of file +{{< partial "components/cryptography.html" >}} \ No newline at end of file diff --git a/daprdocs/content/en/reference/components-reference/supported-cryptography/azure-key-vault.md b/daprdocs/content/en/reference/components-reference/supported-cryptography/azure-key-vault.md new file mode 100644 index 000000000..48fd11768 --- /dev/null +++ b/daprdocs/content/en/reference/components-reference/supported-cryptography/azure-key-vault.md @@ -0,0 +1,47 @@ +--- +type: docs +title: "Azure Key Vault" +linkTitle: "Azure Key Vault" +description: Detailed information on the Azure Key Vault cryptography component +--- + +## 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 +kind: Component +metadata: + name: azurekeyvault +spec: + type: crypto.azure.keyvault + metadata: + - name: vaultName + value: ${{AzureKeyVaultName}} + - name: azureTenantId + value: ${{AzureKeyVaultTenantId}} + - name: azureClientId + value: ${{AzureKeyVaultServicePrincipalClientId}} + - name: azureClientSecret + value: ${{AzureKeyVaultServicePrincipalClientSecret}} +``` + +{{% alert title="Warning" color="warning" %}} +The above example uses secrets as plain strings. It is recommended to use a secret store for the secrets, as described [here]({{< ref component-secrets.md >}}). +{{% /alert %}} + +## Spec metadata fields + +| Field | Required | Details | Example | +|--------------------|:--------:|---------|---------| +| vaultName | Y | Azure Key Vault name | TODO | +| azureTenantId | Y | Azure Key Vault tenant ID | TODO | +| azureClientId | Y | Azure Key Vault service principal client ID | TODO | +| azureClientSecret | Y | Azure Key Vault service principal client secret | TODO | + +## Related links +- [Cryptography building block]({{< ref cryptography >}}) +- [Cryptography API reference]({{< ref cryptography_api.md >}}) \ No newline at end of file diff --git a/daprdocs/content/en/reference/components-reference/supported-cryptography/json-web-key-sets.md b/daprdocs/content/en/reference/components-reference/supported-cryptography/json-web-key-sets.md new file mode 100644 index 000000000..d95a57db6 --- /dev/null +++ b/daprdocs/content/en/reference/components-reference/supported-cryptography/json-web-key-sets.md @@ -0,0 +1,39 @@ +--- +type: docs +title: "JSON Web Key Sets (JWKS)" +linkTitle: "JSON Web Key Sets (JWKS)" +description: Detailed information on the JWKS cryptography component +--- + +## 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 +kind: Component +metadata: + name: jwks +spec: + type: crypto.jwks + version: v1 + metadata: + - name: jwks + value: fixtures/crypto/jwks/jwks.json +``` + +{{% alert title="Warning" color="warning" %}} +The above example uses secrets as plain strings. It is recommended to use a secret store for the secrets, as described [here]({{< ref component-secrets.md >}}). +{{% /alert %}} + +## Spec metadata fields + +| Field | Required | Details | Example | +|--------------------|:--------:|---------|---------| +| jwks | Y | Connection-string for the JWKS host | `fixtures/crypto/jwks/jwks.json` + +## Related links +- [Cryptography building block]({{< ref cryptography >}}) +- [Cryptography API reference]({{< ref cryptography_api.md >}}) \ No newline at end of file diff --git a/daprdocs/content/en/reference/components-reference/supported-cryptography/kubernetes-secrets.md b/daprdocs/content/en/reference/components-reference/supported-cryptography/kubernetes-secrets.md new file mode 100644 index 000000000..ab1fd0f1e --- /dev/null +++ b/daprdocs/content/en/reference/components-reference/supported-cryptography/kubernetes-secrets.md @@ -0,0 +1,39 @@ +--- +type: docs +title: "Kubernetes Secrets" +linkTitle: "Kubernetes Secrets" +description: Detailed information on the Kubernetes Secret cryptography component +--- + +## 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 +kind: Component +metadata: + name: +spec: + type: crypto. + version: v1.0-alpha1 + metadata: + - name: + value: +``` + +{{% alert title="Warning" color="warning" %}} +The above example uses secrets as plain strings. It is recommended to use a secret store for the secrets, as described [here]({{< ref component-secrets.md >}}). +{{% /alert %}} + +## Spec metadata fields + +| Field | Required | Details | Example | +|--------------------|:--------:|---------|---------| +| redisHost | Y | Connection-string for the redis host | `localhost:6379`, `redis-master.default.svc.cluster.local:6379` + +## Related links +- [Cryptography building block]({{< ref cryptography >}}) +- [Cryptography API reference]({{< ref cryptography_api.md >}}) \ No newline at end of file diff --git a/daprdocs/content/en/reference/components-reference/supported-cryptography/local-storage.md b/daprdocs/content/en/reference/components-reference/supported-cryptography/local-storage.md new file mode 100644 index 000000000..b51460b03 --- /dev/null +++ b/daprdocs/content/en/reference/components-reference/supported-cryptography/local-storage.md @@ -0,0 +1,39 @@ +--- +type: docs +title: "Local storage" +linkTitle: "Local storage" +description: Detailed information on the local storage cryptography component +--- + +## 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 +kind: Component +metadata: + name: mycrypto + namespace: default +spec: + type: crypto.localstorage + metadata: + - name: path + value: fixtures/crypto/localstorage/ +``` + +{{% alert title="Warning" color="warning" %}} +The above example uses secrets as plain strings. It is recommended to use a secret store for the secrets, as described [here]({{< ref component-secrets.md >}}). +{{% /alert %}} + +## Spec metadata fields + +| Field | Required | Details | Example | +|--------------------|:--------:|---------|---------| +| path | Y | Connection-string for the lcoal storage | `fixtures/crypto/localstorage/` + +## Related links +- [Cryptography building block]({{< ref cryptography >}}) +- [Cryptography API reference]({{< ref cryptography_api.md >}}) \ No newline at end of file diff --git a/daprdocs/data/components/cryptography/azure.yaml b/daprdocs/data/components/cryptography/azure.yaml new file mode 100644 index 000000000..52a6943dd --- /dev/null +++ b/daprdocs/data/components/cryptography/azure.yaml @@ -0,0 +1,5 @@ +- component: Azure Key Vault + link: azure-key-vault + state: Alpha + version: v1 + since: "1.11" \ No newline at end of file diff --git a/daprdocs/data/components/cryptography/generic.yaml b/daprdocs/data/components/cryptography/generic.yaml new file mode 100644 index 000000000..54b2bd204 --- /dev/null +++ b/daprdocs/data/components/cryptography/generic.yaml @@ -0,0 +1,17 @@ +- component: JSON Web Key Sets (JWKS) + link: json-web-key-sets + state: Alpha + version: v1 + since: "1.11" +- component: Kubernetes secrets + link: kubernetes-secrets + state: Alpha + version: v1 + since: "1.11" + features: + multipleKeyValuesPerSecret: true +- component: Local storage + link: local-storage + state: Alpha + version: v1 + since: "1.11" \ No newline at end of file diff --git a/daprdocs/layouts/partials/components/cryptography.html b/daprdocs/layouts/partials/components/cryptography.html new file mode 100644 index 000000000..7c90291f5 --- /dev/null +++ b/daprdocs/layouts/partials/components/cryptography.html @@ -0,0 +1,28 @@ +{{- $groups := dict + " Generic" $.Site.Data.components.cryptography.generic + "Microsoft Azure" $.Site.Data.components.cryptography.azure + + }} + + {{ range $group, $components := $groups }} +

{{ $group }}

+ + + + + + + + {{ range sort $components "component" }} + + + + + + + {{ end }} +
ComponentStatusComponent versionSince runtime version
{{ .component }} + {{ .state }}{{ .version }}{{ .since }}
+ {{ end }} + + {{ partial "components/componenttoc.html" . }} \ No newline at end of file