From a76971c54baa14df7d6895dd402dead7fc5e1dae Mon Sep 17 00:00:00 2001 From: ItalyPaleAle <43508+ItalyPaleAle@users.noreply.github.com> Date: Tue, 6 Jun 2023 13:42:34 -0700 Subject: [PATCH 1/2] Crypto how-to: add JavaScript SDK examples Signed-off-by: ItalyPaleAle <43508+ItalyPaleAle@users.noreply.github.com> --- .../cryptography/howto-cryptography.md | 96 ++++++++++++++----- .../pubsub/howto-publish-subscribe.md | 2 +- .../quickstarts/cryptography-quickstart.md | 3 +- 3 files changed, 74 insertions(+), 27 deletions(-) diff --git a/daprdocs/content/en/developing-applications/building-blocks/cryptography/howto-cryptography.md b/daprdocs/content/en/developing-applications/building-blocks/cryptography/howto-cryptography.md index 7b568c21f..2dc1a0b3f 100644 --- a/daprdocs/content/en/developing-applications/building-blocks/cryptography/howto-cryptography.md +++ b/daprdocs/content/en/developing-applications/building-blocks/cryptography/howto-cryptography.md @@ -15,14 +15,54 @@ Now that you've read about [Cryptography as a Dapr building block]({{< ref crypt ## Encrypt -Using the Dapr gRPC APIs in your project, you can encrypt a stream of data, such as a file. +{{< tabs "JavaScript" "Go" >}} -{{< tabs "Go" >}} +{{% codetab %}} + + + +Using the Dapr SDK in your project, with the gRPC APIs, you can encrypt data in a buffer or a string: + +```js +// When passing data (a buffer or string), `encrypt` returns a Buffer with the encrypted message +const ciphertext = await client.crypto.encrypt(plaintext, { + // Name of the Dapr component (required) + componentName: "mycryptocomponent", + // Name of the key stored in the component (required) + keyName: "mykey", + // Algorithm used for wrapping the key, which must be supported by the key named above. + // Options include: "RSA", "AES" + keyWrapAlgorithm: "RSA", +}); +``` + +The APIs can also be used with streams, to encrypt data more efficiently when it comes from a stream. In the example below, we are encrypting a file, writing to another file, using streams: + +```js +// `encrypt` can be used as a Duplex stream +await pipeline( + fs.createReadStream("plaintext.txt"), + await client.crypto.encrypt({ + // Name of the Dapr component (required) + componentName: "mycryptocomponent", + // Name of the key stored in the component (required) + keyName: "mykey", + // Algorithm used for wrapping the key, which must be supported by the key named above. + // Options include: "RSA", "AES" + keyWrapAlgorithm: "RSA", + }), + fs.createWriteStream("ciphertext.out"), +); +``` + +{{% /codetab %}} {{% codetab %}} +Using the Dapr SDK in your project, you can encrypt a stream of data, such as a file. + ```go out, err := sdkClient.Encrypt(context.Background(), rf, dapr.EncryptOptions{ // Name of the Dapr component (required) @@ -35,18 +75,8 @@ out, err := sdkClient.Encrypt(context.Background(), rf, dapr.EncryptOptions{ }) ``` -{{% /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 // Input file, clear-text rf, err := os.Open("input") @@ -81,18 +111,8 @@ if err != nil { fmt.Println("Written", n, "bytes") ``` -{{% /codetab %}} - -{{< /tabs >}} - The following example uses the `Encrypt` API to encrypt a string. -{{< tabs "Go" >}} - -{{% codetab %}} - - - ```go // Input string rf := strings.NewReader("Amor, ch’a nullo amato amar perdona, mi prese del costui piacer sì forte, che, come vedi, ancor non m’abbandona") @@ -121,15 +141,41 @@ if err != nil { ## Decrypt -To decrypt a file, add the `Decrypt` gRPC API to your project. +{{< tabs "JavaScript" "Go" >}} -{{< tabs "Go" >}} +{{% codetab %}} + + + +Using the Dapr SDK, you can decrypt data in a buffer or using streams. + +```js +// When passing data as a buffer, `decrypt` returns a Buffer with the decrypted message +const plaintext = await client.crypto.decrypt(ciphertext, { + // Only required option is the component name + componentName: "mycryptocomponent", +}); + +// `decrypt` can also be used as a Duplex stream +await pipeline( + fs.createReadStream("ciphertext.out"), + await client.crypto.decrypt({ + // Only required option is the component name + componentName: "mycryptocomponent", + }), + fs.createWriteStream("plaintext.out"), +); +``` + +{{% /codetab %}} {{% codetab %}} -In the following example, `out` is a stream that can be written to file or read in memory, as in the examples above. +To decrypt a file, use the `Decrypt` gRPC API to your project. + +In the following example, `out` is a stream that can be written to file or read in memory, as in the examples above. ```go out, err := sdkClient.Decrypt(context.Background(), rf, dapr.EncryptOptions{ diff --git a/daprdocs/content/en/developing-applications/building-blocks/pubsub/howto-publish-subscribe.md b/daprdocs/content/en/developing-applications/building-blocks/pubsub/howto-publish-subscribe.md index df28559d4..f771a292b 100644 --- a/daprdocs/content/en/developing-applications/building-blocks/pubsub/howto-publish-subscribe.md +++ b/daprdocs/content/en/developing-applications/building-blocks/pubsub/howto-publish-subscribe.md @@ -186,7 +186,7 @@ Place `subscription.yaml` in the same directory as your `pubsub.yaml` component. Below are code examples that leverage Dapr SDKs to subscribe to the topic you defined in `subscription.yaml`. -{{< tabs Dotnet Java Python Go Javascript>}} +{{< tabs Dotnet Java Python Go JavaScript>}} {{% codetab %}} diff --git a/daprdocs/content/en/getting-started/quickstarts/cryptography-quickstart.md b/daprdocs/content/en/getting-started/quickstarts/cryptography-quickstart.md index 3dbcdd3f5..7da6714ce 100644 --- a/daprdocs/content/en/getting-started/quickstarts/cryptography-quickstart.md +++ b/daprdocs/content/en/getting-started/quickstarts/cryptography-quickstart.md @@ -64,8 +64,9 @@ cd ./crypto-quickstart ``` The application code defines two required keys: + - Private RSA key -- A 256-bit symmetric (AES) key +- A 256-bit symmetric (AES) key Generate two keys, an RSA key and and AES key using OpenSSL and write these to two files: From 55fb8db332bd13de15ac755241dbb362656bfdcc Mon Sep 17 00:00:00 2001 From: Mark Fussell Date: Wed, 7 Jun 2023 09:33:08 -0700 Subject: [PATCH 2/2] Update daprdocs/content/en/developing-applications/building-blocks/cryptography/howto-cryptography.md Co-authored-by: Hannah Hunter <94493363+hhunter-ms@users.noreply.github.com> Signed-off-by: Mark Fussell --- .../building-blocks/cryptography/howto-cryptography.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/daprdocs/content/en/developing-applications/building-blocks/cryptography/howto-cryptography.md b/daprdocs/content/en/developing-applications/building-blocks/cryptography/howto-cryptography.md index 2dc1a0b3f..92f3a6710 100644 --- a/daprdocs/content/en/developing-applications/building-blocks/cryptography/howto-cryptography.md +++ b/daprdocs/content/en/developing-applications/building-blocks/cryptography/howto-cryptography.md @@ -36,7 +36,7 @@ const ciphertext = await client.crypto.encrypt(plaintext, { }); ``` -The APIs can also be used with streams, to encrypt data more efficiently when it comes from a stream. In the example below, we are encrypting a file, writing to another file, using streams: +The APIs can also be used with streams, to encrypt data more efficiently when it comes from a stream. The example below encrypts a file, writing to another file, using streams: ```js // `encrypt` can be used as a Duplex stream