updates to the cryptography api docs

Signed-off-by: Hannah Hunter <hannahhunter@microsoft.com>
This commit is contained in:
Hannah Hunter 2023-05-01 17:22:42 -04:00
parent e41371796d
commit cfb6ac0bbf
12 changed files with 360 additions and 18 deletions

View File

@ -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 >}})
- [Cryptography API reference]({{< ref cryptography_api.md >}})
- [Cryptography component specs]({{< ref supported-cryptography >}})

View File

@ -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.
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-->
```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-->
```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-->
```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 >}})

View File

@ -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]({{<ref "components-concept#pluggable-components" >}})| 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

View File

@ -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: <NAME>
value: <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 >}})

View File

@ -7,6 +7,6 @@ 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.
{{< partial "components/description.html" >}}
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.-->
{{< partial "components/cryptography.html" >}}

View File

@ -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 >}})

View File

@ -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 >}})

View File

@ -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: <NAME>
spec:
type: crypto.<TYPE>
version: v1.0-alpha1
metadata:
- name: <NAME>
value: <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 >}})

View File

@ -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 >}})

View File

@ -0,0 +1,5 @@
- component: Azure Key Vault
link: azure-key-vault
state: Alpha
version: v1
since: "1.11"

View File

@ -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"

View File

@ -0,0 +1,28 @@
{{- $groups := dict
" Generic" $.Site.Data.components.cryptography.generic
"Microsoft Azure" $.Site.Data.components.cryptography.azure
}}
{{ range $group, $components := $groups }}
<h3>{{ $group }}</h3>
<table width="100%">
<tr>
<th>Component</th>
<th>Status</th>
<th>Component version</th>
<th>Since runtime version</th>
</tr>
{{ range sort $components "component" }}
<tr>
<td><a href="/reference/components-reference/supported-locks/{{ .link }}/">{{ .component }}</a>
</td>
<td>{{ .state }}</td>
<td>{{ .version }}</td>
<td>{{ .since }}</td>
</tr>
{{ end }}
</table>
{{ end }}
{{ partial "components/componenttoc.html" . }}