Add raw keyring examples + minor updates

Author: juneb

doc_source/IV-reference.md

@@ -3,7 +3,7 @@
 
 |  | 
 | --- |
-|  The information on this page is a reference for building your own encryption library that is compatible with the AWS Encryption SDK\. If you are not building your own compatible encryption library, you likely do not need this information\. To use the AWS Encryption SDK in one of the supported programming languages, see [Programming languages](programming-languages.md)\. For the specification that defines the elements of a proper AWS Encryption SDK implementation, see the *AWS Encryption SDK Specification* in the [aws\-encryption\-sdk\-specification](https://github.com/awslabs/aws-encryption-sdk-specification/) repository in GitHub\.  | 
+|  The information on this page is a reference for building your own encryption library that is compatible with the AWS Encryption SDK\. If you are not building your own compatible encryption library, you likely do not need this information\. To use the AWS Encryption SDK in one of the supported programming languages, see [Programming languages](programming-languages.md)\. For the specification that defines the elements of a proper AWS Encryption SDK implementation, see the [AWS Encryption SDK Specification](https://github.com/awslabs/aws-encryption-sdk-specification/) in GitHub\.  | 
 
 The AWS Encryption SDK supplies the [initialization vectors](https://en.wikipedia.org/wiki/Initialization_vector) \(IVs\) that are required by all supported [algorithm suites](algorithms-reference.md)\. The SDK uses frame sequence numbers to construct an IV so that no two frames in the same message can have the same IV\. 
 

doc_source/about-versions.md

@@ -47,7 +47,7 @@ The constructors that create earlier versions of AWS KMS master key providers ar
 There are no changes to constructors for AWS KMS master keys\. When encrypting and decrypting, AWS KMS master keys use only the AWS KMS key that you specify\.
 
 **AWS KMS keyring updates \(optional\)**  
-Version 1\.7\.*x* adds a new filter to the AWS Encryption SDK for C and AWS Encryption SDK for JavaScript implementations that limits [AWS KMS discovery keyrings](choose-keyring.md#kms-keyring-discovery) to particular AWS accounts\. This new account filter is optional, but it's a [best practice](best-practices.md) that we recommend\. For details, see [Updating AWS KMS keyrings](migrate-keyrings-v2.md)\.  
+Version 1\.7\.*x* adds a new filter to the AWS Encryption SDK for C and AWS Encryption SDK for JavaScript implementations that limits [AWS KMS discovery keyrings](use-kms-keyring.md#kms-keyring-discovery) to particular AWS accounts\. This new account filter is optional, but it's a [best practice](best-practices.md) that we recommend\. For details, see [Updating AWS KMS keyrings](migrate-keyrings-v2.md)\.  
 There are no changes to constructors for AWS KMS keyrings\. Standard AWS KMS keyrings behave like master key providers in strict mode\. AWS KMS discovery keyrings are created explicitly in discovery mode\. 
 
 **Passing a key ID to AWS KMS Decrypt**  

doc_source/algorithms-reference.md

@@ -3,7 +3,7 @@
 
 |  | 
 | --- |
-|  The information on this page is a reference for building your own encryption library that is compatible with the AWS Encryption SDK\. If you are not building your own compatible encryption library, you likely do not need this information\. To use the AWS Encryption SDK in one of the supported programming languages, see [Programming languages](programming-languages.md)\. For the specification that defines the elements of a proper AWS Encryption SDK implementation, see the *AWS Encryption SDK Specification* in the [aws\-encryption\-sdk\-specification](https://github.com/awslabs/aws-encryption-sdk-specification/) repository in GitHub\.  | 
+|  The information on this page is a reference for building your own encryption library that is compatible with the AWS Encryption SDK\. If you are not building your own compatible encryption library, you likely do not need this information\. To use the AWS Encryption SDK in one of the supported programming languages, see [Programming languages](programming-languages.md)\. For the specification that defines the elements of a proper AWS Encryption SDK implementation, see the [AWS Encryption SDK Specification](https://github.com/awslabs/aws-encryption-sdk-specification/) in GitHub\.  | 
 
 If you are building your own library that can read and write ciphertexts that are compatible with the AWS Encryption SDK, you'll need to understand how the AWS Encryption SDK implements the supported algorithm suites to encrypt raw data\. 
 

doc_source/best-practices.md

@@ -27,8 +27,8 @@ However, when decrypting with AWS KMS keyrings and master key providers, you are
 To support this best practice when working with AWS KMS wrapping keys, we recommend the following:  
 + Use AWS KMS keyrings that specify wrapping keys\. When encrypting and decrypting, these keyrings use only the specified wrapping keys you specify\.
 + When using AWS KMS master keys and master key providers, use the strict mode constructors introduced in [version 1\.7\.*x*](about-versions.md#version-1.7) of the AWS Encryption SDK\. They create providers that encrypt and decrypt only with the wrapping keys you specify\. Constructors for master key providers that always decrypt with any wrapping key are deprecated in version 1\.7\.*x* and deleted in version 2\.0\.*x*\.
-When specifying AWS KMS wrapping keys for decrypting is impractical, you can use discovery providers\. The AWS Encryption SDK in C and JavaScript support [AWS KMS discovery keyrings](choose-keyring.md#kms-keyring-discovery)\. Master key providers with a discovery mode are available for Java and Python in versions 1\.7\.*x* and later\. These discovery providers, which are used only for decrypting with AWS KMS wrapping keys, explicitly direct the AWS Encryption SDK to use any wrapping key that encrypted a data key\.   
-If you must use discovery providers, use their filter features to limit the wrapping keys they use\. For example, the [AWS KMS regional discovery keyring](choose-keyring.md#kms-keyring-regional) uses only the wrapping keys in a particular AWS Region\. You can also configure AWS KMS keyrings and AWS KMS [master key providers](migrate-mkps-v2.md#migrate-mkp-discovery-mode) to use only the [wrapping keys](migrate-keyrings-v2.md) in particular AWS accounts\. Also, as always, use key policies and IAM policies to control access to your AWS KMS wrapping keys\.
+When specifying AWS KMS wrapping keys for decrypting is impractical, you can use discovery providers\. The AWS Encryption SDK in C and JavaScript support [AWS KMS discovery keyrings](use-kms-keyring.md#kms-keyring-discovery)\. Master key providers with a discovery mode are available for Java and Python in versions 1\.7\.*x* and later\. These discovery providers, which are used only for decrypting with AWS KMS wrapping keys, explicitly direct the AWS Encryption SDK to use any wrapping key that encrypted a data key\.   
+If you must use a discovery provider, use its *discovery filter* features to limit the wrapping keys they use\. For example, the [AWS KMS regional discovery keyring](use-kms-keyring.md#kms-keyring-regional) uses only the wrapping keys in a particular AWS Region\. You can also configure AWS KMS keyrings and AWS KMS [master key providers](migrate-mkps-v2.md#migrate-mkp-discovery-mode) to use only the [wrapping keys](migrate-keyrings-v2.md) in particular AWS accounts\. Also, as always, use key policies and IAM policies to control access to your AWS KMS wrapping keys\.
 
 **Use digital signatures**  
 It's a best practice to use an algorithm suite with signing\. [Digital signatures](concepts.md#digital-sigs) verify the message sender was authorized to send the message and protect the integrity of the message\. All versions of the AWS Encryption SDK use algorithm suites with signing by default\.  

doc_source/body-aad-reference.md

@@ -3,7 +3,7 @@
 
 |  | 
 | --- |
-|  The information on this page is a reference for building your own encryption library that is compatible with the AWS Encryption SDK\. If you are not building your own compatible encryption library, you likely do not need this information\. To use the AWS Encryption SDK in one of the supported programming languages, see [Programming languages](programming-languages.md)\. For the specification that defines the elements of a proper AWS Encryption SDK implementation, see the *AWS Encryption SDK Specification* in the [aws\-encryption\-sdk\-specification](https://github.com/awslabs/aws-encryption-sdk-specification/) repository in GitHub\.  | 
+|  The information on this page is a reference for building your own encryption library that is compatible with the AWS Encryption SDK\. If you are not building your own compatible encryption library, you likely do not need this information\. To use the AWS Encryption SDK in one of the supported programming languages, see [Programming languages](programming-languages.md)\. For the specification that defines the elements of a proper AWS Encryption SDK implementation, see the [AWS Encryption SDK Specification](https://github.com/awslabs/aws-encryption-sdk-specification/) in GitHub\.  | 
 
 You must provide additional authenticated data \(AAD\) to the [AES\-GCM algorithm](algorithms-reference.md) for each cryptographic operation\. This is true for both framed and nonframed [body data](message-format.md#body-structure)\. For more information about AAD and how it is used in Galois/Counter Mode \(GCM\), see [Recommendations for Block Cipher Modes of Operations: Galois/Counter Mode \(GCM\) and GMAC](https://nvlpubs.nist.gov/nistpubs/Legacy/SP/nistspecialpublication800-38d.pdf)\.
 

doc_source/c-examples.md

@@ -15,7 +15,7 @@ The following example shows you how to use the AWS Encryption SDK for C to encry
 
 This example features the KMS [keyring](concepts.md#keyring), a type of keyring that uses an AWS KMS key in [AWS Key Management Service \(AWS KMS\)](https://aws.amazon.com/kms/) to generate and encrypt data keys\. The example includes some code written in C\+\+ because the AWS Encryption SDK for C uses the AWS SDK for C\+\+ to call AWS KMS\. 
 
-For help creating an AWS KMS key, see [Creating Keys](https://docs.aws.amazon.com/kms/latest/developerguide/create-keys.html) in the *AWS Key Management Service Developer Guide*\. For help identifying the AWS KMS keys in an AWS KMS keyring, see [Identifying AWS KMS keys in an AWS KMS keyring](choose-keyring.md#kms-keyring-id)
+For help creating an AWS KMS key, see [Creating Keys](https://docs.aws.amazon.com/kms/latest/developerguide/create-keys.html) in the *AWS Key Management Service Developer Guide*\. For help identifying the AWS KMS keys in an AWS KMS keyring, see [Identifying AWS KMS keys in an AWS KMS keyring](use-kms-keyring.md#kms-keyring-id)
 
 **See the complete code sample**: [string\.cpp](https://github.com/aws/aws-encryption-sdk-c/blob/master/examples/string.cpp)
 
@@ -29,8 +29,8 @@ The first part of this example uses an AWS KMS keyring with one AWS KMS key to e
 
 Step 1: Construct the keyring\.  
 Create an AWS KMS keyring for encryption\. The keyring in this example is configured with one AWS KMS key, but you can configure an AWS KMS keyring with multiple AWS KMS keys, including AWS KMS keys in different AWS Regions and different accounts\.   
-To identify an AWS KMS key in an encryption keyring, specify a [key ARN](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-id-key-ARN) or [alias ARN](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-id-alias-arn)\. In a decryption keyring, you must use a key ARN\. For details, see [Identifying AWS KMS keys in an AWS KMS keyring](choose-keyring.md#kms-keyring-id)\.  
-[Identifying AWS KMS keys in an AWS KMS keyring](choose-keyring.md#kms-keyring-id)  
+To identify an AWS KMS key in an encryption keyring in the AWS Encryption SDK for C, specify a [key ARN](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-id-key-ARN) or [alias ARN](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-id-alias-arn)\. In a decryption keyring, you must use a key ARN\. For details, see [Identifying AWS KMS keys in an AWS KMS keyring](use-kms-keyring.md#kms-keyring-id)\.  
+[Identifying AWS KMS keys in an AWS KMS keyring](use-kms-keyring.md#kms-keyring-id)  
 When you create a keyring with multiple AWS KMS keys, you specify the AWS KMS key used to generate and encrypt the plaintext data key, and an optional array of additional AWS KMS keys that encrypt the same plaintext data key\. In this case, you specify only the generator AWS KMS key\.   
 Before running this code, replace the example key ARN with a valid one\.  
 
@@ -110,7 +110,7 @@ The second part of this example decrypts an encrypted message that contains the
 Step 1: Construct the keyring\.  
 When you decrypt data in AWS KMS, you pass in the [encrypted message](concepts.md#message) that the encrypt API returned\. The [Decrypt API](https://docs.aws.amazon.com/kms/latest/APIReference/API_Decrypt.html) doesn't take an AWS KMS key as input\. Instead, AWS KMS uses the same AWS KMS key to decrypt the ciphertext that it used to encrypt it\. However, the AWS Encryption SDK lets you specify an AWS KMS keyring with AWS KMS keys on encrypt and decrypt\.  
 On decrypt, you can configure a keyring with only the AWS KMS keys that you want to use to decrypt the encrypted message\. For example, you might want to create a keyring with only the AWS KMS key that is used by a particular role in your organization\. The AWS Encryption SDK will never use an AWS KMS key unless it appears in the decryption keyring\. If the SDK can't decrypt the encrypted data keys by using the AWS KMS keys in the keyring that you provide, either because none of AWS KMS keys in the keyring were used to encrypt any of the data keys, or because the caller doesn't have permission to use the AWS KMS keys in the keyring to decrypt, the decrypt call fails\.  
-When you specify an AWS KMS key for a decryption keyring, you must use its [key ARN](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-id-key-ARN)\. [Alias ARNs](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-id-alias-arn) are permitted only in encryption keyrings\. For help identifying the AWS KMS keys in an AWS KMS keyring, see [Identifying AWS KMS keys in an AWS KMS keyring](choose-keyring.md#kms-keyring-id)\.  
+When you specify an AWS KMS key for a decryption keyring, you must use its [key ARN](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-id-key-ARN)\. [Alias ARNs](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-id-alias-arn) are permitted only in encryption keyrings\. For help identifying the AWS KMS keys in an AWS KMS keyring, see [Identifying AWS KMS keys in an AWS KMS keyring](use-kms-keyring.md#kms-keyring-id)\.  
 In this example, we specify a keyring configured with the same AWS KMS key used to encrypt the string\. Before running this code, replace the example key ARN with a valid one\.  
 
 ```

doc_source/c-language-installation.md

@@ -2,6 +2,6 @@
 
 You can find detailed instructions for installing and building the AWS Encryption SDK for C in the [README file](https://github.com/aws/aws-encryption-sdk-c/#readme) of the [aws\-encryption\-sdk\-c](https://github.com/aws/aws-encryption-sdk-c/) repository\. It includes instructions for building on Amazon Linux, Ubuntu, macOS, and Windows platforms\. 
 
-Before you begin, decide whether you want to use [AWS KMS keyrings](choose-keyring.md#use-kms-keyring) in the AWS Encryption SDK\. If you use an AWS KMS keyring, you need to install the AWS SDK for C\+\+\. AWS KMS keyrings use [AWS Key Management Service](https://docs.aws.amazon.com/kms/latest/developerguide/) \(AWS KMS\) to generate and protect the encryption keys that protect your data\. Otherwise, you need to generate and protect your own raw wrapping keys\. 
+Before you begin, decide whether you want to use [AWS KMS keyrings](use-kms-keyring.md) in the AWS Encryption SDK\. If you use an AWS KMS keyring, you need to install the AWS SDK for C\+\+\. AWS KMS keyrings use [AWS Key Management Service](https://docs.aws.amazon.com/kms/latest/developerguide/) \(AWS KMS\) to generate and protect the encryption keys that protect your data\. Otherwise, you need to generate and protect your own raw wrapping keys\. 
 
 If you're having trouble with your installation, [file an issue](https://github.com/aws/aws-encryption-sdk-c/issues) in the `aws-encryption-sdk-c` repository or use any of the feedback links on this page\.

doc_source/c-language-using.md

@@ -17,8 +17,8 @@ See also: [Using keyrings](choose-keyring.md)
 When you use the AWS Encryption SDK for C, you follow a pattern similar to this: create a [keyring](concepts.md#keyring), create a [CMM](concepts.md#crypt-materials-manager) that uses the keyring, create a session that uses the CMM \(and keyring\), and then process the session\.
 
 1\. Create a keyring\.  
-Configure your [keyring](concepts.md#keyring) with the wrapping keys that you want to use to encrypt your data keys\. This example uses an [AWS KMS keyring](choose-keyring.md#use-kms-keyring) with one AWS KMS key, but you can use any type of keyring in its place\.  
-To identify an AWS KMS key in an encryption keyring, specify a [key ARN](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-id-key-ARN) or [alias ARN](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-id-alias-arn)\. In a decryption keyring, you must use a key ARN\. For details, see [Identifying AWS KMS keys in an AWS KMS keyring](choose-keyring.md#kms-keyring-id)\.  
+Configure your [keyring](concepts.md#keyring) with the wrapping keys that you want to use to encrypt your data keys\. This example uses an [AWS KMS keyring](use-kms-keyring.md) with one AWS KMS key, but you can use any type of keyring in its place\.  
+To identify an AWS KMS key in an encryption keyring in the AWS Encryption SDK for C, specify a [key ARN](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-id-key-ARN) or [alias ARN](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-id-alias-arn)\. In a decryption keyring, you must use a key ARN\. For details, see [Identifying AWS KMS keys in an AWS KMS keyring](use-kms-keyring.md#kms-keyring-id)\.  
 
 ```
 const char * KEY_ARN = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab"    

doc_source/c-language.md

@@ -6,7 +6,7 @@ Like all implementations of the AWS Encryption SDK, the AWS Encryption SDK for C
 
 All language\-specific implementations of the AWS Encryption SDK are fully interoperable\. For example, you can encrypt data with the AWS Encryption SDK for C and decrypt it with [any supported language implementation](programming-languages.md), including the [AWS Encryption CLI](crypto-cli.md)\.
 
-The AWS Encryption SDK for C uses the AWS SDK for C\+\+ to interact with AWS Key Management Service \(AWS KMS\) so it can support the optional [AWS KMS keyring](choose-keyring.md#use-kms-keyring)\. However, the AWS Encryption SDK doesn't require AWS KMS or any other AWS service\.
+The AWS Encryption SDK for C uses the AWS SDK for C\+\+ to interact with AWS Key Management Service \(AWS KMS\) so it can support the optional [AWS KMS keyring](use-kms-keyring.md)\. However, the AWS Encryption SDK doesn't require AWS KMS or any other AWS service\.
 
 **Learn More**
 + For details about programming with the AWS Encryption SDK for C, see the [C examples](c-examples.md), the [examples](https://github.com/aws/aws-encryption-sdk-c/tree/master/examples) in the [aws\-encryption\-sdk\-c repository](https://github.com/aws/aws-encryption-sdk-c/) on GitHub, and the [AWS Encryption SDK for C API documentation](https://aws.github.io/aws-encryption-sdk-c/html/)\.