From 47b9687fc7b284ba5b418a44cb5a8ab80e5bb27e Mon Sep 17 00:00:00 2001 From: Caitlin Tibbetts Date: Fri, 14 Jun 2019 13:12:07 -0700 Subject: [PATCH 1/8] example-node Readme.md update --- modules/example-node/Readme.md | 32 +++++++++---------- .../src/kms_regional_discovery.ts | 15 --------- modules/example-node/src/kms_simple.ts | 15 --------- modules/example-node/src/rsa_simple.ts | 15 --------- 4 files changed, 16 insertions(+), 61 deletions(-) diff --git a/modules/example-node/Readme.md b/modules/example-node/Readme.md index b4f1c6c8c..4e526e49a 100644 --- a/modules/example-node/Readme.md +++ b/modules/example-node/Readme.md @@ -1,32 +1,32 @@ # AWS Encryption SDK for Javascript Node.js examples This repository holds examples for encrypt and decrypt in Node.js. -These examples are intended to work so you can experiment with functional code. +These examples are intended to work in such a way that you can experiment with functional code. These are not for production use. -# NOTE -The CMK's in these examples *are only* for example. They *are public*. -Replace these CMK's with your own. +> The CMK's in these examples *are only* for example. They *are public*. *Replace these CMK's with your own*. ## KMS Simple -This is the simples example. -It encrypts and decrypts a simple string with KMS. +This is an example of using KMS to encrypt and decrypt a simple string. See `kms_simple.ts` for a more detailed explanation. ## KMS Stream -An example of encrypting a file stream with KMS. +This is an example of using KMS to encrypt and decrypt a file stream. See `kms_stream.ts` for a more detailed explanation. ## KMS Regional Discovery -KMS Keyrings can be put in `discovery` mode. -This means that it will attempt to connect to any region. -This is not always what you want. -Perhapses for performance you want to limit attempts to a set of "close" regions. -Perhapses for policy reason you want to exclude some regions. +KMS Keyrings can be put in `discovery` mode, which means that, on decrypt, it will attempt to connect to any region represented in the KMS Keyring by using the `clientProvider`. However, perhaps for performance, you may want to limit attempts to a set of "close" regions, or, for policy reasons, you want to exclude some regions, which can be done with the `limitRegions` and `excludeRegions` functions, respectively. See `kms_regional_discovery.ts` for a more detailed explanation. ## RSA Simple -Sometimes you may want to use an RSA key to exchange secrets. -This has some advantages, but comes with a heaved key management cost. -If you can use KMS, the context guaranties are generally worth it. -However, I still want to provide an example incase this fits your use case. +This is an example of using RSA to encrypt and decrypt a simple string. This has some advantages for certain use-cases, but the key management costs are higher than using KMS, which means KMS is generally the best option. See `rsa_simple.ts` for a more detailed explanation. + +## How to Use + +Run `npm test` to see these examples in action. + +## License + +This SDK is distributed under the +[Apache License, Version 2.0](http://www.apache.org/licenses/LICENSE-2.0), +see LICENSE.txt and NOTICE.txt for more information. diff --git a/modules/example-node/src/kms_regional_discovery.ts b/modules/example-node/src/kms_regional_discovery.ts index ef293066d..d89f44b70 100644 --- a/modules/example-node/src/kms_regional_discovery.ts +++ b/modules/example-node/src/kms_regional_discovery.ts @@ -13,21 +13,6 @@ * limitations under the License. */ -/* - * Copyright 2019 Amazon.com, Inc. or its affiliates. All Rights Reserved. - * - * Licensed under the Apache License, Version 2.0 (the "License"). You may not use - * this file except in compliance with the License. A copy of the License is - * located at - * - * http://aws.amazon.com/apache2.0/ - * - * or in the "license" file accompanying this file. This file is distributed on an - * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or - * implied. See the License for the specific language governing permissions and - * limitations under the License. - */ - import { KmsKeyringNode, limitRegions, excludeRegions, getKmsClient, decrypt } from '@aws-crypto/client-node' export async function kmsRegionalDiscoveryLimitTest (ciphertext: string|Buffer) { diff --git a/modules/example-node/src/kms_simple.ts b/modules/example-node/src/kms_simple.ts index b2acff2cf..f04dbdccf 100644 --- a/modules/example-node/src/kms_simple.ts +++ b/modules/example-node/src/kms_simple.ts @@ -13,21 +13,6 @@ * limitations under the License. */ -/* - * Copyright 2019 Amazon.com, Inc. or its affiliates. All Rights Reserved. - * - * Licensed under the Apache License, Version 2.0 (the "License"). You may not use - * this file except in compliance with the License. A copy of the License is - * located at - * - * http://aws.amazon.com/apache2.0/ - * - * or in the "license" file accompanying this file. This file is distributed on an - * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or - * implied. See the License for the specific language governing permissions and - * limitations under the License. - */ - import { KmsKeyringNode, encrypt, decrypt } from '@aws-crypto/client-node' export async function kmsSimpleTest () { diff --git a/modules/example-node/src/rsa_simple.ts b/modules/example-node/src/rsa_simple.ts index 43b199bbb..a0f84d997 100644 --- a/modules/example-node/src/rsa_simple.ts +++ b/modules/example-node/src/rsa_simple.ts @@ -13,21 +13,6 @@ * limitations under the License. */ -/* - * Copyright 2019 Amazon.com, Inc. or its affiliates. All Rights Reserved. - * - * Licensed under the Apache License, Version 2.0 (the "License"). You may not use - * this file except in compliance with the License. A copy of the License is - * located at - * - * http://aws.amazon.com/apache2.0/ - * - * or in the "license" file accompanying this file. This file is distributed on an - * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or - * implied. See the License for the specific language governing permissions and - * limitations under the License. - */ - import { RawRsaKeyringNode, encrypt, decrypt } from '@aws-crypto/client-node' import { generateKeyPair } from 'crypto' From bba3e85cad31910d49e08d647a8e83b5451ea324 Mon Sep 17 00:00:00 2001 From: Caitlin Tibbetts Date: Sun, 16 Jun 2019 22:49:03 -0700 Subject: [PATCH 2/8] Update Readme.md --- modules/example-node/Readme.md | 13 ++++++------- 1 file changed, 6 insertions(+), 7 deletions(-) diff --git a/modules/example-node/Readme.md b/modules/example-node/Readme.md index 4e526e49a..878c47f57 100644 --- a/modules/example-node/Readme.md +++ b/modules/example-node/Readme.md @@ -1,25 +1,24 @@ # AWS Encryption SDK for Javascript Node.js examples -This repository holds examples for encrypt and decrypt in Node.js. -These examples are intended to work in such a way that you can experiment with functional code. These are not for production use. +This repository includes examples for encrypting and decrypting in Node.js. These are not for production use. -> The CMK's in these examples *are only* for example. They *are public*. *Replace these CMK's with your own*. +>To run this example, the reader must have an AWS account with at least one customer managed CMK. To encrypt CMK must have kms:GenerateDataKey permission. To decrypt, the CMK must have kms:Decrypt permission. The CMKs in these examples *are only* for example. *Replace these CMK's with your own*. ## KMS Simple -This is an example of using KMS to encrypt and decrypt a simple string. See `kms_simple.ts` for a more detailed explanation. +This is an example of using KMS to encrypt and decrypt a simple string. See kms_simple.ts for a more detailed explanation. ## KMS Stream -This is an example of using KMS to encrypt and decrypt a file stream. See `kms_stream.ts` for a more detailed explanation. +This is an example of using KMS to encrypt and decrypt a file stream. See kms_stream.ts for a more detailed explanation. ## KMS Regional Discovery -KMS Keyrings can be put in `discovery` mode, which means that, on decrypt, it will attempt to connect to any region represented in the KMS Keyring by using the `clientProvider`. However, perhaps for performance, you may want to limit attempts to a set of "close" regions, or, for policy reasons, you want to exclude some regions, which can be done with the `limitRegions` and `excludeRegions` functions, respectively. See `kms_regional_discovery.ts` for a more detailed explanation. +This is an example of using a KMS Regional Discovery Keyring that limits the AWS Encryption SDK to CMKs in a particular AWS Region(s), as opposed to a KMS Discovery Keyring that doesn't specify any CMKs and will therefore use CMKs from any region available. See kms_regional_discovery.ts for a more detailed explanation. ## RSA Simple -This is an example of using RSA to encrypt and decrypt a simple string. This has some advantages for certain use-cases, but the key management costs are higher than using KMS, which means KMS is generally the best option. See `rsa_simple.ts` for a more detailed explanation. +This is an example of using RSA to encrypt and decrypt a simple string. This has some advantages for certain use cases, but we recommend that you use a keyring that protects your wrapping keys and performs cryptographic operations within a secure boundary, such as the KMS keyring, which uses AWS Key Management Service (AWS KMS) customer master keys (CMKs) that never leave AWS KMS unencrypted, rather than RSA. See rsa_simple.ts for a more detailed explanation. ## How to Use From 2f318fd952c4717c62d1d17184028499a9114985 Mon Sep 17 00:00:00 2001 From: Caitlin Tibbetts Date: Tue, 18 Jun 2019 11:25:12 -0700 Subject: [PATCH 3/8] Update modules/example-node/Readme.md Co-Authored-By: seebees --- modules/example-node/Readme.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/example-node/Readme.md b/modules/example-node/Readme.md index 878c47f57..7ce6235e7 100644 --- a/modules/example-node/Readme.md +++ b/modules/example-node/Readme.md @@ -2,7 +2,7 @@ This repository includes examples for encrypting and decrypting in Node.js. These are not for production use. ->To run this example, the reader must have an AWS account with at least one customer managed CMK. To encrypt CMK must have kms:GenerateDataKey permission. To decrypt, the CMK must have kms:Decrypt permission. The CMKs in these examples *are only* for example. *Replace these CMK's with your own*. +To run this example, the reader must have an AWS account with at least one customer managed CMK. To encrypt CMK must have kms:GenerateDataKey permission. To decrypt, the CMK must have kms:Decrypt permission. The CMKs in these examples *are only* for example. *Replace these CMK's with your own*. ## KMS Simple From b849532fd0d4b7f09aa7b2c3508e26605be25949 Mon Sep 17 00:00:00 2001 From: Caitlin Tibbetts Date: Tue, 18 Jun 2019 11:46:28 -0700 Subject: [PATCH 4/8] Update Readme.md --- modules/example-node/Readme.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/modules/example-node/Readme.md b/modules/example-node/Readme.md index 7ce6235e7..d1d916e2b 100644 --- a/modules/example-node/Readme.md +++ b/modules/example-node/Readme.md @@ -6,23 +6,23 @@ To run this example, the reader must have an AWS account with at least one custo ## KMS Simple -This is an example of using KMS to encrypt and decrypt a simple string. See kms_simple.ts for a more detailed explanation. +This is an example of using KMS to encrypt and decrypt a simple string. For a more detailed explanation, see kms_simple.ts. ## KMS Stream -This is an example of using KMS to encrypt and decrypt a file stream. See kms_stream.ts for a more detailed explanation. +This is an example of using KMS to encrypt and decrypt a file stream. For a more detailed explanation, see kms_stream.ts. ## KMS Regional Discovery -This is an example of using a KMS Regional Discovery Keyring that limits the AWS Encryption SDK to CMKs in a particular AWS Region(s), as opposed to a KMS Discovery Keyring that doesn't specify any CMKs and will therefore use CMKs from any region available. See kms_regional_discovery.ts for a more detailed explanation. +This is an example of using a KMS Regional Discovery Keyring that limits the AWS Encryption SDK to CMKs in a particular AWS Region(s), as opposed to a KMS Discovery Keyring that doesn't specify any CMKs and will therefore use CMKs from any region available. For a more detailed explanation, see kms_regional_discovery.ts. ## RSA Simple -This is an example of using RSA to encrypt and decrypt a simple string. This has some advantages for certain use cases, but we recommend that you use a keyring that protects your wrapping keys and performs cryptographic operations within a secure boundary, such as the KMS keyring, which uses AWS Key Management Service (AWS KMS) customer master keys (CMKs) that never leave AWS KMS unencrypted, rather than RSA. See rsa_simple.ts for a more detailed explanation. +This is an example of using RSA to encrypt and decrypt a simple string. This has some advantages for certain use cases, but we recommend that you use a keyring that protects your wrapping keys and performs cryptographic operations within a secure boundary, such as the KMS keyring, which uses AWS Key Management Service (AWS KMS) customer master keys (CMKs) that never leave AWS KMS unencrypted, rather than RSA. For a more detailed explanation, see rsa_simple.ts. ## How to Use -Run `npm test` to see these examples in action. +To see these examples in action, run `npm test`. ## License From c3beefcdd151f60adf16739dee10a9e60a23f37e Mon Sep 17 00:00:00 2001 From: Caitlin Tibbetts Date: Tue, 18 Jun 2019 11:50:30 -0700 Subject: [PATCH 5/8] Update Readme.md --- modules/example-node/Readme.md | 18 +++++++++++++----- 1 file changed, 13 insertions(+), 5 deletions(-) diff --git a/modules/example-node/Readme.md b/modules/example-node/Readme.md index d1d916e2b..4ca064bc5 100644 --- a/modules/example-node/Readme.md +++ b/modules/example-node/Readme.md @@ -2,23 +2,31 @@ This repository includes examples for encrypting and decrypting in Node.js. These are not for production use. -To run this example, the reader must have an AWS account with at least one customer managed CMK. To encrypt CMK must have kms:GenerateDataKey permission. To decrypt, the CMK must have kms:Decrypt permission. The CMKs in these examples *are only* for example. *Replace these CMK's with your own*. +To run this example, you must have an AWS account with at least one AWS Key Management Service (AWS KMS) customer managed CMK. +To encrypt CMK must have kms:GenerateDataKey permission. +To decrypt, the CMK must have kms:Decrypt permission. +The CMKs in these examples *are only* for example. *Replace these CMK's with your own*. ## KMS Simple -This is an example of using KMS to encrypt and decrypt a simple string. For a more detailed explanation, see kms_simple.ts. +This is an example of using KMS to encrypt and decrypt a simple string. +For a more detailed explanation, see kms_simple.ts. ## KMS Stream -This is an example of using KMS to encrypt and decrypt a file stream. For a more detailed explanation, see kms_stream.ts. +This is an example of using KMS to encrypt and decrypt a file stream. +For a more detailed explanation, see kms_stream.ts. ## KMS Regional Discovery -This is an example of using a KMS Regional Discovery Keyring that limits the AWS Encryption SDK to CMKs in a particular AWS Region(s), as opposed to a KMS Discovery Keyring that doesn't specify any CMKs and will therefore use CMKs from any region available. For a more detailed explanation, see kms_regional_discovery.ts. +This is an example of using a KMS Regional Discovery Keyring that limits the AWS Encryption SDK to CMKs in a particular AWS Region(s), as opposed to a KMS Discovery Keyring that doesn't specify any CMKs and will therefore use CMKs from any region available. +For a more detailed explanation, see kms_regional_discovery.ts. ## RSA Simple -This is an example of using RSA to encrypt and decrypt a simple string. This has some advantages for certain use cases, but we recommend that you use a keyring that protects your wrapping keys and performs cryptographic operations within a secure boundary, such as the KMS keyring, which uses AWS Key Management Service (AWS KMS) customer master keys (CMKs) that never leave AWS KMS unencrypted, rather than RSA. For a more detailed explanation, see rsa_simple.ts. +This is an example of using RSA to encrypt and decrypt a simple string. +This has some advantages for certain use cases, but we recommend that you use a keyring that protects your wrapping keys and performs cryptographic operations within a secure boundary, such as the KMS keyring, which uses AWS Key Management Service (AWS KMS) customer master keys (CMKs) that never leave AWS KMS unencrypted, rather than RSA. +For a more detailed explanation, see rsa_simple.ts. ## How to Use From 8f98f71f53d865b3b0460c8c4b43c453f0d9ddeb Mon Sep 17 00:00:00 2001 From: Caitlin Tibbetts Date: Tue, 18 Jun 2019 11:57:33 -0700 Subject: [PATCH 6/8] Update Readme.md --- modules/example-node/Readme.md | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/modules/example-node/Readme.md b/modules/example-node/Readme.md index 4ca064bc5..e36bf804a 100644 --- a/modules/example-node/Readme.md +++ b/modules/example-node/Readme.md @@ -3,29 +3,30 @@ This repository includes examples for encrypting and decrypting in Node.js. These are not for production use. To run this example, you must have an AWS account with at least one AWS Key Management Service (AWS KMS) customer managed CMK. -To encrypt CMK must have kms:GenerateDataKey permission. +To encrypt, CMK must have kms:GenerateDataKey permission. To decrypt, the CMK must have kms:Decrypt permission. -The CMKs in these examples *are only* for example. *Replace these CMK's with your own*. +The CMKs in these examples are only for *example*. *Replace these CMK's with your own*. ## KMS Simple -This is an example of using KMS to encrypt and decrypt a simple string. +This is an example of using the AWS Encryption SDK to encrypt and decrypt a simple string. For a more detailed explanation, see kms_simple.ts. ## KMS Stream -This is an example of using KMS to encrypt and decrypt a file stream. +This is an example of using a KMS keyring to encrypt and decrypt a file stream. For a more detailed explanation, see kms_stream.ts. ## KMS Regional Discovery -This is an example of using a KMS Regional Discovery Keyring that limits the AWS Encryption SDK to CMKs in a particular AWS Region(s), as opposed to a KMS Discovery Keyring that doesn't specify any CMKs and will therefore use CMKs from any region available. +This is an example of using a KMS Regional Discovery Keyring that limits the AWS Encryption SDK to CMKs in a particular AWS Region(s). +This is different from a KMS Discovery Keyring that doesn't specify any CMKs and will therefore use CMKs from any region available. For a more detailed explanation, see kms_regional_discovery.ts. ## RSA Simple -This is an example of using RSA to encrypt and decrypt a simple string. -This has some advantages for certain use cases, but we recommend that you use a keyring that protects your wrapping keys and performs cryptographic operations within a secure boundary, such as the KMS keyring, which uses AWS Key Management Service (AWS KMS) customer master keys (CMKs) that never leave AWS KMS unencrypted, rather than RSA. +This is an example of using a RSA key pair to encrypt and decrypt a simple string. +This has some advantages for certain use cases, but we recommend that you use a keyring that protects your wrapping keys and performs cryptographic operations within a secure boundary. This is how a KMS keyring works: it uses AWS Key Management Service (AWS KMS) customer master keys (CMKs) that never leave AWS KMS unencrypted. For a more detailed explanation, see rsa_simple.ts. ## How to Use From 456adac80863c972c17e616a0b03365367317404 Mon Sep 17 00:00:00 2001 From: Caitlin Tibbetts Date: Tue, 18 Jun 2019 13:06:06 -0700 Subject: [PATCH 7/8] Update Readme.md --- modules/example-node/Readme.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/modules/example-node/Readme.md b/modules/example-node/Readme.md index e36bf804a..0cd88b1f0 100644 --- a/modules/example-node/Readme.md +++ b/modules/example-node/Readme.md @@ -3,7 +3,7 @@ This repository includes examples for encrypting and decrypting in Node.js. These are not for production use. To run this example, you must have an AWS account with at least one AWS Key Management Service (AWS KMS) customer managed CMK. -To encrypt, CMK must have kms:GenerateDataKey permission. +To encrypt, the CMK must have kms:GenerateDataKey permission. To decrypt, the CMK must have kms:Decrypt permission. The CMKs in these examples are only for *example*. *Replace these CMK's with your own*. @@ -26,7 +26,7 @@ For a more detailed explanation, see kms_regional_discovery.ts. ## RSA Simple This is an example of using a RSA key pair to encrypt and decrypt a simple string. -This has some advantages for certain use cases, but we recommend that you use a keyring that protects your wrapping keys and performs cryptographic operations within a secure boundary. This is how a KMS keyring works: it uses AWS Key Management Service (AWS KMS) customer master keys (CMKs) that never leave AWS KMS unencrypted. +This has some advantages for certain use cases, but we recommend that you use a keyring that protects your wrapping keys and performs cryptographic operations within a secure boundary. A KMS keyring uses AWS Key Management Service (AWS KMS) customer master keys (CMKs) that never leave AWS KMS unencrypted. For a more detailed explanation, see rsa_simple.ts. ## How to Use From c5bd278bf3e7fe880df5f0aef2b410d31ed4477f Mon Sep 17 00:00:00 2001 From: June Blender Date: Tue, 18 Jun 2019 14:27:09 -0700 Subject: [PATCH 8/8] Update modules/example-node/Readme.md --- modules/example-node/Readme.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/example-node/Readme.md b/modules/example-node/Readme.md index 0cd88b1f0..61ebca744 100644 --- a/modules/example-node/Readme.md +++ b/modules/example-node/Readme.md @@ -5,7 +5,7 @@ This repository includes examples for encrypting and decrypting in Node.js. Thes To run this example, you must have an AWS account with at least one AWS Key Management Service (AWS KMS) customer managed CMK. To encrypt, the CMK must have kms:GenerateDataKey permission. To decrypt, the CMK must have kms:Decrypt permission. -The CMKs in these examples are only for *example*. *Replace these CMK's with your own*. +The CMKs in these examples are only for *example*. *Replace these CMKs with your own*. ## KMS Simple