Introduce the .NET language implementation

Author: juneb

doc_source/about-versions.md

@@ -8,6 +8,7 @@ When upgrades include new features that require special configuration to avoid e
 
 For a detailed description of the changes for each version your programming language, see the Changelog for each repository\. 
 + AWS Encryption SDK for C — [CHANGELOG\.md](https://github.com/aws/aws-encryption-sdk-c/blob/master/CHANGELOG.md)
++ C\# / \.NET — [CHANGELOG\.md](https://github.com/aws/aws-encryption-sdk-dafny/blob/mainline/aws-encryption-sdk-net/CHANGELOG.md)
 + AWS Encryption CLI — [Versions of the AWS Encryption CLI](crypto-cli-versions.md) and [CHANGELOG\.rst](https://github.com/aws/aws-encryption-sdk-cli/blob/master/CHANGELOG.rst)
 + AWS Encryption SDK for Java — [CHANGELOG\.md](https://github.com/aws/aws-encryption-sdk-java/blob/master/CHANGELOG.md)
 + AWS Encryption SDK for JavaScript — [CHANGELOG\.md](https://github.com/aws/aws-encryption-sdk-javascript/blob/master/CHANGELOG.md)
@@ -159,4 +160,6 @@ For details, see [Prerequisites](java.md#java-prerequisites)\.
 **Note**  
 For information about [support and maintenance](introduction.md#support) of this AWS Encryption SDK version in your preferred programming language, see the `SUPPORT_POLICY.rst` file in its [GitHub repository](introduction.md#esdk-repos)\.
 
-AWS Encryption CLI version 3\.0\.*x* adds support for AWS KMS multi\-Region keys\. For details, see in the *AWS Key Management Service Developer Guide*\. \(Other AWS Encryption SDK programming languages support multi\-Region keys beginning in [version 2\.3\.*x*](#version2.3)\.\)
+AWS Encryption CLI version 3\.0\.*x* adds support for AWS KMS multi\-Region keys\. For details, see in the *AWS Key Management Service Developer Guide*\. \(Other AWS Encryption SDK programming languages support multi\-Region keys beginning in [version 2\.3\.*x*](#version2.3)\.\)
+
+Introduced the AWS Encryption SDK for \.NET\.

doc_source/best-practices.md

@@ -21,7 +21,7 @@ Use wrapping keys that are protected by a secure key infrastructure, such as [AW
 Use the authorization mechanisms of your key infrastructure to limit access to your wrapping keys to only the users that require it\. Implement best practice principles, such as least privilege\. When using AWS KMS keys, use key policies and IAM policies that implement [best practice principles](https://docs.aws.amazon.com/kms/latest/developerguide/iam-policies.html#iam-policies-best-practices)\.
 
 **Specify your wrapping keys**  <a name="strict-discovery-mode"></a>
-It's always a best practice to specify your wrapping keys explicitly when decrypting, as well as encrypting\. When you do, the AWS Encryption SDK uses only the keys that you specify\. This practice assures that you only use the encryption keys that you intend\. For AWS KMS wrapping keys, it also improves performance by preventing you from inadvertently using keys in a different AWS account or Region, or attempting to decrypt with keys that you don't have permission to use\.  
+It's always a best practice to [specify your wrapping keys](configure.md#config-keys) explicitly when decrypting, as well as encrypting\. When you do, the AWS Encryption SDK uses only the keys that you specify\. This practice assures that you only use the encryption keys that you intend\. For AWS KMS wrapping keys, it also improves performance by preventing you from inadvertently using keys in a different AWS account or Region, or attempting to decrypt with keys that you don't have permission to use\.  
 When encrypting, the keyrings and master key providers that the AWS Encryption SDK supplies require that you specify wrapping keys\. They use all and only the wrapping keys you specify\. You are also required to specify wrapping keys when encrypting and decrypting with raw AES keyrings, raw RSA keyrings, and JCEMasterKeys\.  
 However, when decrypting with AWS KMS keyrings and master key providers, you are not required to specify wrapping keys\. The AWS Encryption SDK can get the key identifier from the metadata of the encrypted data key\. But specifying wrapping keys is a best practice that we recommend\.  
 To support this best practice when working with AWS KMS wrapping keys, we recommend the following:  
@@ -40,6 +40,6 @@ The AWS Encryption SDK provides full support for encrypting and decrypting with
 Support for key commitment includes [new algorithm suites](supported-algorithms.md) and a [new message format](message-format.md) that produces a ciphertext only 30 bytes larger than a ciphertext without key commitment\. The design minimizes its impact on performance so most users can enjoy the benefits of key commitment\. If your application is very sensitive to size and performance, you might decide to use the [commitment policy](concepts.md#commitment-policy) setting to disable key commitment or allow the AWS Encryption SDK to decrypt messages without commitment, but do so only if you must\.
 
 **Limit the number of encrypted data keys**  
-It's a best practice to limit the number of encrypted data keys in messages that you decrypt, especially messages from untrusted sources\. Decrypting a message with numerous encrypted data keys that you can't decrypt can cause extended delays, run up expenses, throttle your application and others that share your account, and potentially exhaust your key infrastructure\. Without limits, an encrypted message can have up to 65,535 \(2^16 \- 1\) encrypted data keys\. For details, see [Limit encrypted data keys](configure.md#config-limit-keys)\.
+It's a best practice to [limit the number of encrypted data keys](configure.md#config-limit-keys) in messages that you decrypt, especially messages from untrusted sources\. Decrypting a message with numerous encrypted data keys that you can't decrypt can cause extended delays, run up expenses, throttle your application and others that share your account, and potentially exhaust your key infrastructure\. Without limits, an encrypted message can have up to 65,535 \(2^16 \- 1\) encrypted data keys\. For details, see [Limit encrypted data keys](configure.md#config-limit-keys)\.
 
 For more information about the AWS Encryption SDK security features that underlie these best practices, see [Improved client\-side encryption: Explicit KeyIds and key commitment](http://aws.amazon.com/blogs/security/improved-client-side-encryption-explicit-keyids-and-key-commitment/) in the *AWS Security Blog*\.

doc_source/c-language.md

@@ -13,6 +13,6 @@ The AWS Encryption SDK for C requires the AWS SDK for C\+\+ to interact with AWS
 + For a discussion about how to use the AWS Encryption SDK for C to encrypt data so that you can decrypt it in multiple AWS Regions, see [How to decrypt ciphertexts in multiple regions with the AWS Encryption SDK in C](http://aws.amazon.com/blogs/security/how-to-decrypt-ciphertexts-multiple-regions-aws-encryption-sdk-in-c/) in the AWS Security Blog\.
 
 **Topics**
-+ [Install and build](c-language-installation.md)
++ [Installing](c-language-installation.md)
 + [Using the C SDK](c-language-using.md)
 + [Examples](c-examples.md)

doc_source/choose-keyring.md

@@ -1,6 +1,6 @@
 # Using keyrings<a name="choose-keyring"></a>
 
-The AWS Encryption SDK for C and AWS Encryption SDK for JavaScript use *keyrings* to perform [envelope encryption](https://docs.aws.amazon.com/crypto/latest/userguide/cryptography-concepts.html#define-envelope-encryption)\. Keyrings generate, encrypt, and decrypt the unique data keys that encrypt your data\. Keyrings also define the wrapping keys that are used to encrypt and decrypt the data keys\. You can use the keyrings that the AWS Encryption SDK provides or write your own compatible custom keyrings\.
+The AWS Encryption SDK for C, the AWS Encryption SDK for JavaScript, and the AWS Encryption SDK for \.NET use *keyrings* to perform [envelope encryption](https://docs.aws.amazon.com/crypto/latest/userguide/cryptography-concepts.html#define-envelope-encryption)\. Keyrings generate, encrypt, and decrypt data keys\. Keyrings determine the source of the unique data keys that protect each message, and the [wrapping keys](concepts.md#master-key) that encrypt that data key\. You specify a keyring when encrypting and the same or a different keyring when decrypting\. You can use the keyrings that the SDK provides or write your own compatible custom keyrings\. 
 
 You can use each keyring individually or combine keyrings into a [multi\-keyring](use-multi-keyring.md)\. Although most keyrings can generate, encrypt, and decrypt data keys, you might create a keyring that performs only one particular operation, such as a keyring that only generates data keys, and use that keyring in combination with others\.
 

doc_source/concepts.md

@@ -59,12 +59,12 @@ Each encrypted data key includes metadata, including the identifier of the wrapp
 
 ## Wrapping key<a name="master-key"></a>
 
-A *wrapping key* \(or *master key*\) is a key\-encryption key that the AWS Encryption SDK uses to encrypt the [data key](#DEK) that encrypts your data\. Each plaintext data key can be encrypted under one or more wrapping keys\. You determine which wrapping keys are used to protect your data when you configure a [keyring](#keyring) or [master key provider](#master-key-provider)\.
+A *wrapping key* is a key\-encryption key that the AWS Encryption SDK uses to encrypt the [data key](#DEK) that encrypts your data\. Each plaintext data key can be encrypted under one or more wrapping keys\. You determine which wrapping keys are used to protect your data when you configure a [keyring](#keyring) or [master key provider](#master-key-provider)\.
 
 **Note**  
 *Wrapping key* refers to the keys in a keyring or master key provider\. *Master key* is typically associated with the `MasterKey` class that you instantiate when you use a master key provider\.
 
-The AWS Encryption SDK supports several commonly used wrapping keys, such as AWS Key Management Service \(AWS KMS\) symmetric [AWS KMS keys](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#master_keys), raw AES\-GCM \(Advanced Encryption Standard/Galois Counter Mode\) keys, and raw RSA keys\. You can also extend or implement your own wrapping keys\. 
+The AWS Encryption SDK supports several commonly used wrapping keys, such as AWS Key Management Service \(AWS KMS\) symmetric [AWS KMS keys](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#master_keys) \(including [multi\-Region KMS keys](configure.md#config-mrks)\), raw AES\-GCM \(Advanced Encryption Standard/Galois Counter Mode\) keys, and raw RSA keys\. You can also extend or implement your own wrapping keys\. 
 
 When you use envelope encryption, you need to protect your wrapping keys from unauthorized access\. You can do this in any of the following ways:
 + Use a web service designed for this purpose, such as [AWS Key Management Service \(AWS KMS\)](https://aws.amazon.com/kms/)\.
@@ -75,9 +75,9 @@ If you don't have a key management system, we recommend AWS KMS\. The AWS Encryp
 
 ## Keyrings and master key providers<a name="keyring"></a>
 
-To specify the wrapping keys you use for encryption and decryption, you use a keyring \(C and JavaScript\) or a master key provider \(Java, Python, CLI\)\. You can use the keyrings and master key providers that the AWS Encryption SDK provides or design your own implementations\. The AWS Encryption SDK provides keyrings and master key providers that are compatible with each other subject to language constraints\. For details, see [Keyring compatibility](keyring-compatibility.md)\. 
+To specify the wrapping keys you use for encryption and decryption, you use a keyring \(C, C\# / \.NET, and JavaScript\) or a master key provider \(Java, Python, CLI\)\. You can use the keyrings and master key providers that the AWS Encryption SDK provides or design your own implementations\. The AWS Encryption SDK provides keyrings and master key providers that are compatible with each other subject to language constraints\. For details, see [Keyring compatibility](keyring-compatibility.md)\. 
 
-A *keyring* generates, encrypts, and decrypts data keys\. When you define a keyring, you can specify the [wrapping keys](#master-key) that encrypt your data keys\. Most keyrings specify at least one wrapping key or a service that provides and protects wrapping keys\. You can also define a keyring with no wrapping keys or a more complex keyring with additional configuration options\. For help choosing and using the keyrings that the AWS Encryption SDK defines, see [Using keyrings](choose-keyring.md)\. Keyrings are supported in C and JavaScript\.
+A *keyring* generates, encrypts, and decrypts data keys\. When you define a keyring, you can specify the [wrapping keys](#master-key) that encrypt your data keys\. Most keyrings specify at least one wrapping key or a service that provides and protects wrapping keys\. You can also define a keyring with no wrapping keys or a more complex keyring with additional configuration options\. For help choosing and using the keyrings that the AWS Encryption SDK defines, see [Using keyrings](choose-keyring.md)\. Keyrings are supported in C, C\# / \.NET, and JavaScript\.
 
 A *master key provider* is an alternative to a keyring\. The master key provider returns the wrapping keys \(or master keys\) you specify\. Each master key is associated with one master key provider, but a master key provider typically provides multiple master keys\. Master key providers are supported in Java, Python, and the AWS Encryption CLI\. 
 
@@ -101,7 +101,7 @@ The following example encryption context consists of two encryption context pair
 
 To decrypt the data, you pass in the encrypted message\. Because the AWS Encryption SDK can extract the encryption context from the encrypted message header, you are not required to provide the encryption context separately\. However, the encryption context can help you to confirm that you are decrypting the correct encrypted message\. 
 + In the [AWS Encryption SDK Command Line Interface](crypto-cli.md) \(CLI\), if you provide an encryption context in a decrypt command, the CLI verifies that the values are present in the encryption context of the encrypted message before it returns the plaintext data\. 
-+ In other languages, the decrypt response includes the encryption context and the plaintext data\. The decrypt function in your application should always verify that the encryption context in the decrypt response includes the encryption context in the encrypt request \(or a subset\) before it returns the plaintext data\.
++ In other programming language implementations, the decrypt response includes the encryption context and the plaintext data\. The decrypt function in your application should always verify that the encryption context in the decrypt response includes the encryption context in the encrypt request \(or a subset\) before it returns the plaintext data\.
 
 When choosing an encryption context, remember that it is not a secret\. The encryption context is displayed in plaintext in the header of the [encrypted message](#message) that the AWS Encryption SDK returns\. If you are using AWS Key Management Service, the encryption context also might appear in plaintext in audit records and logs, such as AWS CloudTrail\.