Skip to content

Commit 3dc5218

Browse files
WhitWaldomsfussell
WhitWaldo
and
msfussell
authored
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 <[email protected]> * Added Crypto API reference documentation. Updated error codes weight so it's last in list. Signed-off-by: Whit Waldo <[email protected]> * Update daprdocs/content/en/reference/api/cryptography_api.md Co-authored-by: Mark Fussell <[email protected]> Signed-off-by: Whit Waldo <[email protected]> * Update daprdocs/content/en/reference/api/cryptography_api.md Co-authored-by: Mark Fussell <[email protected]> Signed-off-by: Whit Waldo <[email protected]> * Minor text update Signed-off-by: Whit Waldo <[email protected]> * Update daprdocs/content/en/reference/api/cryptography_api.md Co-authored-by: Mark Fussell <[email protected]> Signed-off-by: Whit Waldo <[email protected]> * Update daprdocs/content/en/reference/api/cryptography_api.md Co-authored-by: Mark Fussell <[email protected]> Signed-off-by: Whit Waldo <[email protected]> * Update daprdocs/content/en/reference/api/cryptography_api.md Co-authored-by: Mark Fussell <[email protected]> Signed-off-by: Whit Waldo <[email protected]> * Update daprdocs/content/en/reference/api/cryptography_api.md Co-authored-by: Mark Fussell <[email protected]> Signed-off-by: Whit Waldo <[email protected]> * Added related link to API reference on Crypto overview page. Signed-off-by: Whit Waldo <[email protected]> --------- Signed-off-by: Whit Waldo <[email protected]> Co-authored-by: Mark Fussell <[email protected]>
1 parent 18785e4 commit 3dc5218

File tree

3 files changed

+131
-2
lines changed

3 files changed

+131
-2
lines changed

‎daprdocs/content/en/developing-applications/building-blocks/cryptography/cryptography-overview.md

+2-1
Original file line numberDiff line numberDiff line change
@@ -85,4 +85,5 @@ Watch this [demo video of the Cryptography API from the Dapr Community Call #83]
8585

8686
## Related links
8787
- [Cryptography overview]({{< ref cryptography-overview.md >}})
88-
- [Cryptography component specs]({{< ref supported-cryptography >}})
88+
- [Cryptography component specs]({{< ref supported-cryptography >}})
89+
- [Cryptography API reference doc]({{< ref cryptography_api >}})

‎daprdocs/content/en/reference/api/cryptography_api.md

+128
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,128 @@
1+
---
2+
type: docs
3+
title: "Cryptography API reference"
4+
linkTitle: "Cryptography API"
5+
description: "Detailed documentation on the cryptography API"
6+
weight: 1300
7+
---
8+
9+
Dapr provides cross-platform and cross-language support for encryption and decryption support via the
10+
cryptography building block. Besides the [language specific SDKs]({{<ref sdks>}}), a developer can invoke these capabilities using
11+
the HTTP API endpoints below.
12+
13+
## Encrypt Payload
14+
15+
This endpoint lets you encrypt a value provided as a byte array using a specified key and crypto component.
16+
17+
### HTTP Request
18+
19+
```
20+
PUT http://localhost:<daprPort>/v1.0/crypto/<crypto-store-name>/encrypt
21+
```
22+
23+
#### URL Parameters
24+
| Parameter | Description |
25+
|-------------------|-------------------------------------------------------------|
26+
| daprPort | The Dapr port |
27+
| crypto-store-name | The name of the crypto store to get the encryption key from |
28+
29+
> Note, all URL parameters are case-sensitive.
30+
31+
#### Headers
32+
Additional encryption parameters are configured by setting headers with the appropriate
33+
values. The following table details the required and optional headers to set with every
34+
encryption request.
35+
36+
| Header Key | Description | Allowed Values | Required |
37+
|-------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------|----------------------------------------------------------|
38+
| dapr-key-name | The name of the key to use for the encryption operation | | Yes |
39+
| dapr-key-wrap-algorithm | The key wrap algorithm to use | `A256KW`, `A128CBC`, `A192CBC`, `RSA-OAEP-256` | Yes |
40+
| 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 |
41+
| 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 |
42+
| dapr-data-encryption-cipher | The cipher to use for the encryption operation | `aes-gcm` or `chacha20-poly1305` | No |
43+
44+
### HTTP Response
45+
46+
#### Response Body
47+
The response to an encryption request will have its content type header set to `application/octet-stream` as it
48+
returns an array of bytes with the encrypted payload.
49+
50+
#### Response Codes
51+
| Code | Description |
52+
|------|-------------------------------------------------------------------------|
53+
| 200 | OK |
54+
| 400 | Crypto provider not found |
55+
| 500 | Request formatted correctly, error in dapr code or underlying component |
56+
57+
### Examples
58+
```shell
59+
curl http://localhost:3500/v1.0/crypto/myAzureKeyVault/encrypt \
60+
-X PUT \
61+
-H "dapr-key-name: myCryptoKey" \
62+
-H "dapr-key-wrap-algorithm: aes-gcm" \
63+
-H "Content-Type: application/octet-string" \
64+
--data-binary "\x68\x65\x6c\x6c\x6f\x20\x77\x6f\x72\x6c\x64"
65+
```
66+
67+
> The above command sends an array of UTF-8 encoded bytes representing "hello world" and would return
68+
> a stream of 8-bit values in the response similar to the following containing the encrypted payload:
69+
70+
```bash
71+
gAAAAABhZfZ0Ywz4dQX8y9J0Zl5v7w6Z7xq4jV3cW9o2l4pQ0YD1LdR0Zk7zIYi4n2Ll7t6f0Z4X7r8x9o6a8GyL0X1m9Q0Z0A==
72+
```
73+
74+
## Decrypt Payload
75+
76+
This endpoint lets you decrypt a value provided as a byte array using a specified key and crypto component.
77+
78+
#### HTTP Request
79+
80+
```
81+
PUT curl http://localhost:3500/v1.0/crypto/<crypto-store-name>/decrypt
82+
```
83+
84+
#### URL Parameters
85+
86+
| Parameter | Description |
87+
|-------------------|-------------------------------------------------------------|
88+
| daprPort | The Dapr port |
89+
| crypto-store-name | The name of the crypto store to get the decryption key from |
90+
91+
> Note all parameters are case-sensitive.
92+
93+
#### Headers
94+
Additional decryption parameters are configured by setting headers with the appropriate values. The following table
95+
details the required and optional headers to set with every decryption request.
96+
97+
| Header Key | Description | Required |
98+
|---------------|----------------------------------------------------------|----------|
99+
| dapr-key-name | The name of the key to use for the decryption operation. | Yes |
100+
101+
### HTTP Response
102+
103+
#### Response Body
104+
The response to a decryption request will have its content type header to set `application/octet-stream` as it
105+
returns an array of bytes representing the decrypted payload.
106+
107+
#### Response Codes
108+
| Code | Description |
109+
|------|-------------------------------------------------------------------------|
110+
| 200 | OK |
111+
| 400 | Crypto provider not found |
112+
| 500 | Request formatted correctly, error in dapr code or underlying component |
113+
114+
### Examples
115+
```bash
116+
curl http://localhost:3500/v1.0/crypto/myAzureKeyVault/decrypt \
117+
-X PUT
118+
-H "dapr-key-name: myCryptoKey"\
119+
-H "Content-Type: application/octet-stream" \
120+
--data-binary "gAAAAABhZfZ0Ywz4dQX8y9J0Zl5v7w6Z7xq4jV3cW9o2l4pQ0YD1LdR0Zk7zIYi4n2Ll7t6f0Z4X7r8x9o6a8GyL0X1m9Q0Z0A=="
121+
```
122+
123+
> The above command sends a base-64 encoded string of the encrypted message payload and would return a response with
124+
> the content type header set to `application/octet-stream` returning the response body `hello world`.
125+
126+
```bash
127+
hello world
128+
```

‎daprdocs/content/en/reference/api/error_codes.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@ type: docs
33
title: "Error codes returned by APIs"
44
linkTitle: "Error codes"
55
description: "Detailed reference of the Dapr API error codes"
6-
weight: 1300
6+
weight: 1400
77
---
88

99
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.

0 commit comments

Comments
 (0)