Explaining the support and maintenance policy

Author: juneb

doc_source/about-versions.md

@@ -3,7 +3,7 @@
 The AWS Encryption SDK is designed to make it easy for you to protect your data using industry standards and best practices\. While many best practices are selected for you in default values, some practices are optional but recommended whenever it's practical\.
 
 **Use the latest version**  
-When you start using the AWS Encryption SDK, use the latest version offered in your preferred [programming language](programming-languages.md)\. If you've been using the AWS Encryption SDK, upgrade to each latest version as soon as possible\. This assures that you're using the recommended configuration and taking advantage of new security properties to protect your data\. For details about supported versions, including guidance for migration and deployment, see [Migrating to version 2\.0\.*x*](migration.md)\.  
+When you start using the AWS Encryption SDK, use the latest version offered in your preferred [programming language](programming-languages.md)\. If you've been using the AWS Encryption SDK, upgrade to each latest version as soon as possible\. This assures that you're using the recommended configuration and taking advantage of new security properties to protect your data\. For details about supported versions, including guidance for migration and deployment, see [Support and maintenance](introduction.md#support) and [Versions of the AWS Encryption SDK](about-versions.md)\.  
 If a new version deprecates elements in your code, replace them as soon as you can\. Deprecation warnings and code comments typically recommend a good alternative\.  
 To make significant upgrades easier and less prone to error, we occasionally provide a temporary or transitional release\. Use these releases, and their accompanying documentation, to assure that you can upgrade your application without disrupting your production workflow\.
 

doc_source/best-practices.md

@@ -2,7 +2,7 @@
 
 The following examples show you how to use the AWS Encryption SDK for C to encrypt and decrypt data\. 
 
-The examples in this section show how to use version 2\.0\.*x* and later of the AWS Encryption SDK for C\. For examples that use earlier versions, find your release in the [Releases](https://github.com/aws/aws-encryption-sdk-c/releases) list of the [aws\-encryption\-sdk\-c repository](https://github.com/aws/aws-encryption-sdk-c/) repository on GitHub\.
+The examples in this section show how to use versions 2\.0\.*x* and later of the AWS Encryption SDK for C\. For examples that use earlier versions, find your release in the [Releases](https://github.com/aws/aws-encryption-sdk-c/releases) list of the [aws\-encryption\-sdk\-c repository](https://github.com/aws/aws-encryption-sdk-c/) repository on GitHub\.
 
 When you install and build the AWS Encryption SDK for C, the source code for these and other examples are included in the `examples` subdirectory, and they are compiled and built into the `build` directory\. You can also find them in the [examples](https://github.com/aws/aws-encryption-sdk-c/tree/master/examples) subdirectory of the [aws\-encryption\-sdk\-c](https://github.com/aws/aws-encryption-sdk-c/) repository on GitHub\.
 
@@ -13,9 +13,9 @@ When you install and build the AWS Encryption SDK for C, the source code for the
 
 The following example shows you how to use the AWS Encryption SDK for C to encrypt and decrypt a string\.
 
-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\. 
+This example features the [AWS KMS keyring](use-kms-keyring.md), a type of keyring that uses an AWS KMS key in [AWS Key Management Service \(AWS KMS\)](https://docs.aws.amazon.com/kms/latest/developerguide/) to generate and encrypt data keys\. The example includes code written in C\+\+\. The AWS Encryption SDK for C requires the AWS SDK for C\+\+ to call AWS KMS when using AWS KMS keyrings\. If you're using a keyring that doesn't interact with AWS KMS, such as a raw AES keyring, a raw RSA keyring, or a multi\-keyring that doesn't include an AWS KMS keyring, the AWS SDK for C\+\+ is not required\.
 
-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)
+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)
 
@@ -27,7 +27,16 @@ For help creating an AWS KMS key, see [Creating Keys](https://docs.aws.amazon.co
 
 The first part of this example uses an AWS KMS keyring with one AWS KMS key to encrypt a plaintext string\. 
 
-Step 1: Construct the keyring\.  
+Step 1\. Load error strings\.  
+Call the `aws_cryptosdk_load_error_strings()` method in your C or C\+\+ code\. It loads error information that is very useful for debugging\.  
+You only need to call it once, such as in your `main` method\.  
+
+```
+/* Load error strings for debugging */
+aws_cryptosdk_load_error_strings();
+```
+
+Step 2: 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 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)  
@@ -41,7 +50,7 @@ struct aws_cryptosdk_keyring *kms_keyring =
        Aws::Cryptosdk::KmsKeyring::Builder().Build(key_arn);
 ```
 
-Step 2: Create a session\.  
+Step 3: Create a session\.  
 Create a session using the allocator, a mode enumerator, and the keyring\.  
 Every session requires a mode: either `AWS_CRYPTOSDK_ENCRYPT` to encrypt or `AWS_CRYPTOSDK_DECRYPT` to decrypt\. To change the mode of an existing session, use the `aws_cryptosdk_session_reset` method\.  
 After you create a session with the keyring, you can release your reference to the keyring using the method that the SDK provides\. The session retains a reference to the keyring object during its lifetime\. References to the keyring and session objects are released when you destroy the session\. This [reference counting](c-language-using.md#c-language-using-release) technique helps to prevent memory leaks and to prevent the objects from being released while they are in use\.  
@@ -50,16 +59,16 @@ After you create a session with the keyring, you can release your reference to t
 struct aws_cryptosdk_session *session = 
        aws_cryptosdk_session_new_from_keyring_2(alloc, AWS_CRYPTOSDK_ENCRYPT, kms_keyring);
 
-// When you add the keyring to the session, release the keyring object
+/* When you add the keyring to the session, release the keyring object */
 aws_cryptosdk_keyring_release(kms_keyring);
 ```
 
-Step 3: Set the encryption context\.  
+Step 4: Set the encryption context\.  
 An [encryption context](concepts.md#encryption-context) is arbitrary, non\-secret additional authenticated data\. When you provide an encryption context on encrypt, the AWS Encryption SDK cryptographically binds the encryption context to the ciphertext so that the same encryption context is required to decrypt the data\. Using an encryption context is optional, but we recommend it as a best practice\.  
 First, create a hash table that includes the encryption context strings\.  
 
 ```
-// Allocate a hash table for the encryption context.
+/* Allocate a hash table for the encryption context */
 int set_up_enc_ctx(struct aws_allocator *alloc, struct aws_hash_table *my_enc_ctx) 
 
 // Create encryption context strings
@@ -81,12 +90,12 @@ struct aws_hash_table *session_enc_ctx = aws_cryptosdk_session_get_enc_ctx_ptr_m
 aws_cryptosdk_enc_ctx_clone(alloc, session_enc_ctx, my_enc_ctx)
 ```
 
-Step 4: Encrypt the string\.  
+Step 5: Encrypt the string\.  
 To encrypt the plaintext string, use the `aws_cryptosdk_session_process_full` method with the session in encryption mode\. This method, introduced in AWS Encryption SDK versions 1\.9\.*x* and 2\.2\.*x*, is designed for non\-streaming encryption and decryption\. To handle streaming data, call the `aws_cryptosdk_session_process` in a loop\.  
 When encrypting, the plaintext fields are input fields; the ciphertext fields are output fields\. When the processing is complete, the `ciphertext_output` field contains the [encrypted message](concepts.md#message), including the actual ciphertext, encrypted data keys, and the encryption context\. You can decrypt this encrypted message by using the AWS Encryption SDK for any supported programming language\.  
 
 ```
-// Gets the length of the plaintext that the session processed
+/* Gets the length of the plaintext that the session processed */
 size_t ciphertext_len_output;
 if (AWS_OP_SUCCESS != aws_cryptosdk_session_process_full(session,
                                   ciphertext_output,
@@ -99,15 +108,24 @@ if (AWS_OP_SUCCESS != aws_cryptosdk_session_process_full(session,
 }
 ```
 
-Step 5: Clean up the session\.  
+Step 6: Clean up the session\.  
 The final step destroys the session including references to the CMM and the keyring\.  
 If you prefer, instead of destroying the session, you can reuse the session with the same keyring and CMM to decrypt the string, or to encrypt or decrypt other messages\. To use the session for decrypting, use the `aws_cryptosdk_session_reset` method to change the mode to `AWS_CRYPTOSDK_DECRYPT`\.
 
 ### Decrypt a string<a name="c-example-string-decrypt"></a>
 
 The second part of this example decrypts an encrypted message that contains the ciphertext of the original string\. 
 
-Step 1: Construct the keyring\.  
+Step 1: Load error strings\.  
+Call the `aws_cryptosdk_load_error_strings()` method in your C or C\+\+ code\. It loads error information that is very useful for debugging\.  
+You only need to call it once, such as in your `main` method\.  
+
+```
+/* Load error strings for debugging */
+aws_cryptosdk_load_error_strings();
+```
+
+Step 2: 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](use-kms-keyring.md#kms-keyring-id)\.  
@@ -120,19 +138,19 @@ struct aws_cryptosdk_keyring *kms_keyring =
         Aws::Cryptosdk::KmsKeyring::Builder().Build(key_arn);
 ```
 
-Step 2: Create a session\.  
+Step 3: Create a session\.  
 Create a session using the allocator and the keyring\. To configure the session for decryption, configure the session with the `AWS_CRYPTOSDK_DECRYPT` mode\.   
 After you create a session with a keyring, you can release your reference to the keyring using the method that the SDK provides\. The session retains a reference to the keyring object during its lifetime, and both the session and keyring are released when you destroy the session\. This reference counting technique helps to prevent memory leaks and to prevent the objects from being released while they are in use\.  
 
 ```
 struct aws_cryptosdk_session *session =	
 	aws_cryptosdk_session_new_from_keyring_2(alloc, AWS_CRYPTOSDK_DECRYPT, kms_keyring);
 
-// When you add the keyring to the session, release the keyring object
+/* When you add the keyring to the session, release the keyring object */
 aws_cryptosdk_keyring_release(kms_keyring);
 ```
 
-Step 3: Decrypt the string\.  
+Step 4: Decrypt the string\.  
 To decrypt the string, use the `aws_cryptosdk_session_process_full` method with the session that is configured for decryption\. This method, introduced in AWS Encryption SDK versions 1\.9\.*x* and 2\.2\.*x*, is designed for non\-streaming encryption and decryption\. To handle streaming data, call the `aws_cryptosdk_session_process` in a loop\.  
 When decrypting, the ciphertext fields are input fields and the plaintext fields are output fields\. The `ciphertext_input` field holds the [encrypted message](message-format.md) that the encrypt method returned\. When the processing is complete, the `plaintext_output` field contains the plaintext \(decrypted\) string\.  
 
@@ -150,7 +168,7 @@ if (AWS_OP_SUCCESS != aws_cryptosdk_session_process_full(session,
 }
 ```
 
-Step 4: Verify the encryption context\.  
+Step 5: Verify the encryption context\.  
 Be sure that the actual encryption context — the one that was used to decrypt the message — contains the encryption context that you provided when encrypting the message\. The actual encryption context might include extra pairs, because the [cryptographic materials manager](concepts.md#crypt-materials-manager) \(CMM\) can add pairs to the provided encryption context before encrypting the message\.  
 In the AWS Encryption SDK for C, you are not required to provide an encryption context when decrypting because the encryption context is included in the encrypted message that the SDK returns\. But, before it returns the plaintext message, your decrypt function should verify that all pairs in the provided encryption context appear in the encryption context that was used to decrypt the message\.  
 First, get a read\-only pointer to the hash table in the session\. This hash table contains the encryption context that was used to decrypt the message\.   
@@ -175,8 +193,8 @@ for (struct aws_hash_iter iter = aws_hash_iter_begin(my_enc_ctx); !aws_hash_iter
 }
 ```
 
-Clean up the session\.  
-After you verify the encryption context, you can destroy the session\. As usual, you can reuse the session\. If you need to reconfigure it, use the `aws_cryptosdk_session_reset` method\.  
+Step 6: Clean up the session\.  
+After you verify the encryption context, you can destroy the session, or reuse it\. If you need to reconfigure the session, use the `aws_cryptosdk_session_reset` method\.  
 
 ```
 aws_cryptosdk_session_destroy(session);

doc_source/c-examples.md

@@ -2,6 +2,10 @@
 
 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](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\. 
+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\+\+\. The AWS SDK is required to interact with [AWS Key Management Service](https://docs.aws.amazon.com/kms/latest/developerguide/) \(AWS KMS\)\. When you use AWS KMS keyrings, the AWS Encryption SDK uses AWS KMS to generate and protect the encryption keys that protect your data\. 
+
+You do not need to install the AWS SDK for C\+\+ if you are using another keyring type, such as a raw AES keyring, a raw RSA keyring, or a multi\-keyring that doesn't include an AWS KMS keyring\. However, when using a raw keyring type, you need to generate and protect your own raw wrapping keys\.
+
+For help deciding which keyring types to use, see [Choosing a keyring](which-keyring.md)\.
 
 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\.