From c52ab61b2e6244a9cd932bfd01093cf2d3b1ae57 Mon Sep 17 00:00:00 2001 From: Whit Waldo Date: Fri, 12 Jan 2024 21:02:22 -0600 Subject: [PATCH 01/10] Added Crypto API reference documentation. Updated error codes weight so it's last in list. Signed-off-by: Whit Waldo --- .../en/reference/api/cryptography_api.md | 128 ++++++++++++++++++ .../content/en/reference/api/error_codes.md | 2 +- 2 files changed, 129 insertions(+), 1 deletion(-) create mode 100644 daprdocs/content/en/reference/api/cryptography_api.md diff --git a/daprdocs/content/en/reference/api/cryptography_api.md b/daprdocs/content/en/reference/api/cryptography_api.md new file mode 100644 index 00000000000..dbc6b7f0366 --- /dev/null +++ b/daprdocs/content/en/reference/api/cryptography_api.md @@ -0,0 +1,128 @@ +--- +type: docs +title: "Cryptography API reference" +linkTitle: "Cryptography API" +description: "Detailed documentation on the cryptography API" +weight: 1300 +--- + +Dapr provides native, cross-platform, and cross-language support for encryption and decryption support via the +Cryptography building block. Besides the [language specific SDKs]({{}}), a developer can invoke these capabilities using +the gRPC 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:/v1.0/crypto//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 +will return 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//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 will +return 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 +``` \ No newline at end of file diff --git a/daprdocs/content/en/reference/api/error_codes.md b/daprdocs/content/en/reference/api/error_codes.md index 7de8c0a2c3c..19d3b8cc36c 100644 --- a/daprdocs/content/en/reference/api/error_codes.md +++ b/daprdocs/content/en/reference/api/error_codes.md @@ -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. From c3640c8d81bab3054fd4b8b246f2019e5a3a26ee Mon Sep 17 00:00:00 2001 From: Whit Waldo Date: Fri, 12 Jan 2024 21:02:22 -0600 Subject: [PATCH 02/10] Added Crypto API reference documentation. Updated error codes weight so it's last in list. Signed-off-by: Whit Waldo --- .../en/reference/api/cryptography_api.md | 128 ++++++++++++++++++ .../content/en/reference/api/error_codes.md | 2 +- 2 files changed, 129 insertions(+), 1 deletion(-) create mode 100644 daprdocs/content/en/reference/api/cryptography_api.md diff --git a/daprdocs/content/en/reference/api/cryptography_api.md b/daprdocs/content/en/reference/api/cryptography_api.md new file mode 100644 index 00000000000..dbc6b7f0366 --- /dev/null +++ b/daprdocs/content/en/reference/api/cryptography_api.md @@ -0,0 +1,128 @@ +--- +type: docs +title: "Cryptography API reference" +linkTitle: "Cryptography API" +description: "Detailed documentation on the cryptography API" +weight: 1300 +--- + +Dapr provides native, cross-platform, and cross-language support for encryption and decryption support via the +Cryptography building block. Besides the [language specific SDKs]({{}}), a developer can invoke these capabilities using +the gRPC 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:/v1.0/crypto//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 +will return 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//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 will +return 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 +``` \ No newline at end of file diff --git a/daprdocs/content/en/reference/api/error_codes.md b/daprdocs/content/en/reference/api/error_codes.md index 7de8c0a2c3c..19d3b8cc36c 100644 --- a/daprdocs/content/en/reference/api/error_codes.md +++ b/daprdocs/content/en/reference/api/error_codes.md @@ -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. From e1c975de5fea0ca2294ac27d43d3fda68e56d6fe Mon Sep 17 00:00:00 2001 From: Whit Waldo Date: Mon, 22 Jan 2024 07:55:10 -0600 Subject: [PATCH 03/10] Update daprdocs/content/en/reference/api/cryptography_api.md Co-authored-by: Mark Fussell Signed-off-by: Whit Waldo --- daprdocs/content/en/reference/api/cryptography_api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/daprdocs/content/en/reference/api/cryptography_api.md b/daprdocs/content/en/reference/api/cryptography_api.md index dbc6b7f0366..bf1af330970 100644 --- a/daprdocs/content/en/reference/api/cryptography_api.md +++ b/daprdocs/content/en/reference/api/cryptography_api.md @@ -52,7 +52,7 @@ will return an array of bytes with the encrypted payload. |------|-------------------------------------------------------------------------| | 200 | OK | | 400 | Crypto provider not found | -| 500 | Request formatted correctly, error in dapr code or underlying component | +| 500 | Request formatted correctly, error in Dapr code or underlying component | ### Examples ```shell From e6c744ac949962a7be8369d1a86b8ec3c33b2777 Mon Sep 17 00:00:00 2001 From: Whit Waldo Date: Mon, 22 Jan 2024 07:55:26 -0600 Subject: [PATCH 04/10] Update daprdocs/content/en/reference/api/cryptography_api.md Co-authored-by: Mark Fussell Signed-off-by: Whit Waldo --- daprdocs/content/en/reference/api/cryptography_api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/daprdocs/content/en/reference/api/cryptography_api.md b/daprdocs/content/en/reference/api/cryptography_api.md index bf1af330970..7be5748b6ba 100644 --- a/daprdocs/content/en/reference/api/cryptography_api.md +++ b/daprdocs/content/en/reference/api/cryptography_api.md @@ -102,7 +102,7 @@ details the required and optional headers to set with every decryption request. #### Response Body The response to a decryption request will have its content type header to set `application/octet-stream` as it will -return an array of bytes representing the decrypted payload. +returns an array of bytes representing the decrypted payload. #### Response Codes | Code | Description | From 8961b9ad2ad49eff8f7dd015cb18302d23ab4c31 Mon Sep 17 00:00:00 2001 From: Whit Waldo Date: Mon, 22 Jan 2024 07:56:49 -0600 Subject: [PATCH 05/10] Minor text update Signed-off-by: Whit Waldo --- daprdocs/content/en/reference/api/cryptography_api.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/daprdocs/content/en/reference/api/cryptography_api.md b/daprdocs/content/en/reference/api/cryptography_api.md index dbc6b7f0366..cb3f8c3ce04 100644 --- a/daprdocs/content/en/reference/api/cryptography_api.md +++ b/daprdocs/content/en/reference/api/cryptography_api.md @@ -101,8 +101,8 @@ details the required and optional headers to set with every decryption request. ### HTTP Response #### Response Body -The response to a decryption request will have its content type header to set `application/octet-stream` as it will -return an array of bytes representing the decrypted payload. +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 | From 6dc715c58375f3de714262da87e2302a9614822f Mon Sep 17 00:00:00 2001 From: Whit Waldo Date: Mon, 22 Jan 2024 07:59:26 -0600 Subject: [PATCH 06/10] Update daprdocs/content/en/reference/api/cryptography_api.md Co-authored-by: Mark Fussell Signed-off-by: Whit Waldo --- daprdocs/content/en/reference/api/cryptography_api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/daprdocs/content/en/reference/api/cryptography_api.md b/daprdocs/content/en/reference/api/cryptography_api.md index cb3f8c3ce04..756c6c11aca 100644 --- a/daprdocs/content/en/reference/api/cryptography_api.md +++ b/daprdocs/content/en/reference/api/cryptography_api.md @@ -45,7 +45,7 @@ encryption request. #### Response Body The response to an encryption request will have its content type header set to `application/octet-stream` as it -will return an array of bytes with the encrypted payload. +returns an array of bytes with the encrypted payload. #### Response Codes | Code | Description | From 531c48544075986efdb1d2007d3fc130623cc7b8 Mon Sep 17 00:00:00 2001 From: Whit Waldo Date: Mon, 22 Jan 2024 08:01:47 -0600 Subject: [PATCH 07/10] Update daprdocs/content/en/reference/api/cryptography_api.md Co-authored-by: Mark Fussell Signed-off-by: Whit Waldo --- daprdocs/content/en/reference/api/cryptography_api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/daprdocs/content/en/reference/api/cryptography_api.md b/daprdocs/content/en/reference/api/cryptography_api.md index 756c6c11aca..5f2d0e74788 100644 --- a/daprdocs/content/en/reference/api/cryptography_api.md +++ b/daprdocs/content/en/reference/api/cryptography_api.md @@ -6,7 +6,7 @@ description: "Detailed documentation on the cryptography API" weight: 1300 --- -Dapr provides native, cross-platform, and cross-language support for encryption and decryption support via the +Dapr provides cross-platform and cross-language support for encryption and decryption support via the Cryptography building block. Besides the [language specific SDKs]({{}}), a developer can invoke these capabilities using the gRPC API endpoints below. From 9ec4d4d416eab535c565b01bd1667cd6cd776327 Mon Sep 17 00:00:00 2001 From: Whit Waldo Date: Mon, 22 Jan 2024 08:03:50 -0600 Subject: [PATCH 08/10] Update daprdocs/content/en/reference/api/cryptography_api.md Co-authored-by: Mark Fussell Signed-off-by: Whit Waldo --- daprdocs/content/en/reference/api/cryptography_api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/daprdocs/content/en/reference/api/cryptography_api.md b/daprdocs/content/en/reference/api/cryptography_api.md index 5f2d0e74788..5abef9767d8 100644 --- a/daprdocs/content/en/reference/api/cryptography_api.md +++ b/daprdocs/content/en/reference/api/cryptography_api.md @@ -8,7 +8,7 @@ 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]({{}}), a developer can invoke these capabilities using -the gRPC API endpoints below. +the HTTP API endpoints below. ## Encrypt Payload From a9e1a2b6169d2dbd928bd120d4aa9723c74d9dab Mon Sep 17 00:00:00 2001 From: Whit Waldo Date: Mon, 22 Jan 2024 08:03:57 -0600 Subject: [PATCH 09/10] Update daprdocs/content/en/reference/api/cryptography_api.md Co-authored-by: Mark Fussell Signed-off-by: Whit Waldo --- daprdocs/content/en/reference/api/cryptography_api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/daprdocs/content/en/reference/api/cryptography_api.md b/daprdocs/content/en/reference/api/cryptography_api.md index 5abef9767d8..248e8822ec6 100644 --- a/daprdocs/content/en/reference/api/cryptography_api.md +++ b/daprdocs/content/en/reference/api/cryptography_api.md @@ -7,7 +7,7 @@ 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]({{}}), a developer can invoke these capabilities using +cryptography building block. Besides the [language specific SDKs]({{}}), a developer can invoke these capabilities using the HTTP API endpoints below. ## Encrypt Payload From f22027ab7901eb1612bf963314bb23be6f9400db Mon Sep 17 00:00:00 2001 From: Whit Waldo Date: Mon, 22 Jan 2024 08:07:52 -0600 Subject: [PATCH 10/10] Added related link to API reference on Crypto overview page. Signed-off-by: Whit Waldo --- .../building-blocks/cryptography/cryptography-overview.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) 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 48e582a3c37..e8af63f1aaf 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 @@ -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 >}}) \ No newline at end of file +- [Cryptography component specs]({{< ref supported-cryptography >}}) +- [Cryptography API reference doc]({{< ref cryptography_api >}}) \ No newline at end of file