diff --git a/modules/example-node/Readme.md b/modules/example-node/Readme.md index b4f1c6c8c..61ebca744 100644 --- a/modules/example-node/Readme.md +++ b/modules/example-node/Readme.md @@ -1,32 +1,40 @@ # 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. +This repository includes examples for encrypting and decrypting in Node.js. 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. +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 CMKs 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 the AWS Encryption SDK to encrypt and decrypt a simple string. +For a more detailed explanation, see kms_simple.ts. ## KMS Stream -An example of encrypting a file stream with KMS. +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 -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. +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 -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 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. 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 + +To see these examples in action, run `npm test`. + +## 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'