mirror of https://github.com/dapr/docs.git
updates to the cryptography api docs
Signed-off-by: Hannah Hunter <hannahhunter@microsoft.com>
This commit is contained in:
Hannah Hunter
parent
e41371796d
commit
cfb6ac0bbf
|
|
@ -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 >}})
|
||||
|
|
@ -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 >}})
|
||||
|
|
@ -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
|
||||
|
||||
|
|
|
|||
|
|
@ -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 >}})
|
||||
|
|
@ -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" >}}
|
||||
|
|
@ -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 >}})
|
||||
|
|
@ -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 >}})
|
||||
|
|
@ -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 >}})
|
||||
|
|
@ -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 >}})
|
||||
|
|
@ -0,0 +1,5 @@
|
|||
- component: Azure Key Vault
|
||||
link: azure-key-vault
|
||||
state: Alpha
|
||||
version: v1
|
||||
since: "1.11"
|
||||
|
|
@ -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"
|
||||
|
|
@ -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" . }}
|
||||
Loading…
Reference in New Issue