dapr
/
docs
mirror of https://github.com/dapr/docs.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Added Crypto API reference documentation (#3952) 

* Added Crypto API reference documentation. Updated error codes weight so it's last in list.

Signed-off-by: Whit Waldo <whit.waldo@innovian.net>

* Added Crypto API reference documentation. Updated error codes weight so it's last in list.

Signed-off-by: Whit Waldo <whit.waldo@innovian.net>

* Update daprdocs/content/en/reference/api/cryptography_api.md

Co-authored-by: Mark Fussell <markfussell@gmail.com>
Signed-off-by: Whit Waldo <whit.waldo@innovian.net>

* Update daprdocs/content/en/reference/api/cryptography_api.md

Co-authored-by: Mark Fussell <markfussell@gmail.com>
Signed-off-by: Whit Waldo <whit.waldo@innovian.net>

* Minor text update

Signed-off-by: Whit Waldo <whit.waldo@innovian.net>

* Update daprdocs/content/en/reference/api/cryptography_api.md

Co-authored-by: Mark Fussell <markfussell@gmail.com>
Signed-off-by: Whit Waldo <whit.waldo@innovian.net>

* Update daprdocs/content/en/reference/api/cryptography_api.md

Co-authored-by: Mark Fussell <markfussell@gmail.com>
Signed-off-by: Whit Waldo <whit.waldo@innovian.net>

* Update daprdocs/content/en/reference/api/cryptography_api.md

Co-authored-by: Mark Fussell <markfussell@gmail.com>
Signed-off-by: Whit Waldo <whit.waldo@innovian.net>

* Update daprdocs/content/en/reference/api/cryptography_api.md

Co-authored-by: Mark Fussell <markfussell@gmail.com>
Signed-off-by: Whit Waldo <whit.waldo@innovian.net>

* Added related link to API reference on Crypto overview page.

Signed-off-by: Whit Waldo <whit.waldo@innovian.net>

---------

Signed-off-by: Whit Waldo <whit.waldo@innovian.net>
Co-authored-by: Mark Fussell <markfussell@gmail.com>
This commit is contained in:
Whit Waldo 2024-01-22 23:42:35 -06:00 committed by GitHub
parent 18785e4a8e
commit 3dc5218b79
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
3 changed files with 131 additions and 2 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
daprdocs/content/en/developing-applications/building-blocks/cryptography/cryptography-overview.md
View File

@ -85,4 +85,5 @@ Watch this [demo video of the Cryptography API from the Dapr Community Call #83]
## Related links
- [Cryptography overview]({{< ref cryptography-overview.md >}})
- [Cryptography component specs]({{< ref supported-cryptography >}})
- [Cryptography component specs]({{< ref supported-cryptography >}})
- [Cryptography API reference doc]({{< ref cryptography_api >}})

128
daprdocs/content/en/reference/api/cryptography_api.md Normal file
View File

@ -0,0 +1,128 @@
---
type: docs
title: "Cryptography API reference"
linkTitle: "Cryptography API"
description: "Detailed documentation on the cryptography API"
weight: 1300
---
Dapr provides cross-platform and cross-language support for encryption and decryption support via the
cryptography building block. Besides the [language specific SDKs]({{<ref sdks>}}), a developer can invoke these capabilities using
the HTTP API endpoints below.
## Encrypt Payload
This endpoint lets you encrypt a value provided as a byte array using a specified key and crypto component.
### HTTP Request
```
PUT http://localhost:<daprPort>/v1.0/crypto/<crypto-store-name>/encrypt
```
#### URL Parameters
| Parameter | Description |
|-------------------|-------------------------------------------------------------|
| daprPort | The Dapr port |
| crypto-store-name | The name of the crypto store to get the encryption key from |
> Note, all URL parameters are case-sensitive.
#### Headers
Additional encryption parameters are configured by setting headers with the appropriate
values. The following table details the required and optional headers to set with every
encryption request.
| Header Key | Description | Allowed Values | Required |
|-------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------|----------------------------------------------------------|
| dapr-key-name | The name of the key to use for the encryption operation | | Yes |
| dapr-key-wrap-algorithm | The key wrap algorithm to use | `A256KW`, `A128CBC`, `A192CBC`, `RSA-OAEP-256` | Yes |
| dapr-omit-decryption-key-name | If true, omits the decryption key name from header `dapr-decryption-key-name` from the output. If false, includes the specified decryption key name specified in header `dapr-decryption-key-name`. | The following values will be accepted as true: `y`, `yes`, `true`, `t`, `on`, `1` | No |
| dapr-decryption-key-name | If `dapr-omit-decryption-key-name` is true, this contains the name of the intended decryption key to include in the output. | | Required only if `dapr-omit-decryption-key-name` is true |
| dapr-data-encryption-cipher | The cipher to use for the encryption operation | `aes-gcm` or `chacha20-poly1305` | No |
### HTTP Response
#### Response Body
The response to an encryption request will have its content type header set to `application/octet-stream` as it
returns an array of bytes with the encrypted payload.
#### Response Codes
| Code | Description |
|------|-------------------------------------------------------------------------|
| 200 | OK |
| 400 | Crypto provider not found |
| 500 | Request formatted correctly, error in dapr code or underlying component |
### Examples
```shell
curl http://localhost:3500/v1.0/crypto/myAzureKeyVault/encrypt \
-X PUT \
-H "dapr-key-name: myCryptoKey" \
-H "dapr-key-wrap-algorithm: aes-gcm" \
-H "Content-Type: application/octet-string" \
--data-binary "\x68\x65\x6c\x6c\x6f\x20\x77\x6f\x72\x6c\x64"
```
> The above command sends an array of UTF-8 encoded bytes representing "hello world" and would return
> a stream of 8-bit values in the response similar to the following containing the encrypted payload:
```bash
gAAAAABhZfZ0Ywz4dQX8y9J0Zl5v7w6Z7xq4jV3cW9o2l4pQ0YD1LdR0Zk7zIYi4n2Ll7t6f0Z4X7r8x9o6a8GyL0X1m9Q0Z0A==
```
## Decrypt Payload
This endpoint lets you decrypt a value provided as a byte array using a specified key and crypto component.
#### HTTP Request
```
PUT curl http://localhost:3500/v1.0/crypto/<crypto-store-name>/decrypt
```
#### URL Parameters
| Parameter | Description |
|-------------------|-------------------------------------------------------------|
| daprPort | The Dapr port |
| crypto-store-name | The name of the crypto store to get the decryption key from |
> Note all parameters are case-sensitive.
#### Headers
Additional decryption parameters are configured by setting headers with the appropriate values. The following table
details the required and optional headers to set with every decryption request.
| Header Key | Description | Required |
|---------------|----------------------------------------------------------|----------|
| dapr-key-name | The name of the key to use for the decryption operation. | Yes |
### HTTP Response
#### Response Body
The response to a decryption request will have its content type header to set `application/octet-stream` as it
returns an array of bytes representing the decrypted payload.
#### Response Codes
| Code | Description |
|------|-------------------------------------------------------------------------|
| 200 | OK |
| 400 | Crypto provider not found |
| 500 | Request formatted correctly, error in dapr code or underlying component |
### Examples
```bash
curl http://localhost:3500/v1.0/crypto/myAzureKeyVault/decrypt \
-X PUT
-H "dapr-key-name: myCryptoKey"\
-H "Content-Type: application/octet-stream" \
--data-binary "gAAAAABhZfZ0Ywz4dQX8y9J0Zl5v7w6Z7xq4jV3cW9o2l4pQ0YD1LdR0Zk7zIYi4n2Ll7t6f0Z4X7r8x9o6a8GyL0X1m9Q0Z0A=="
```
> The above command sends a base-64 encoded string of the encrypted message payload and would return a response with
> the content type header set to `application/octet-stream` returning the response body `hello world`.
```bash
hello world
```

2
daprdocs/content/en/reference/api/error_codes.md
View File

@ -3,7 +3,7 @@ type: docs
title: "Error codes returned by APIs"
linkTitle: "Error codes"
description: "Detailed reference of the Dapr API error codes"
weight: 1300
weight: 1400
---
For http calls made to Dapr runtime, when an error is encountered, an error json is returned in http response body. The json contains an error code and an descriptive error message, e.g.