Las traducciones son generadas a través de traducción automática. En caso de conflicto entre la traducción y la version original de inglés, prevalecerá la version en inglés.
# AWS Encryption SDK para.NET
La AWS Encryption SDK para .NET es una biblioteca de cifrado del lado del cliente para desarrolladores que escriben aplicaciones en C\$1 y otros lenguajes de programación.NET. Es compatible con Windows, macOS y Linux.
**nota**
La versión 4.0.0 de para.NET se aparta AWS Encryption SDK de la especificación de mensajes. AWS Encryption SDK En consecuencia, los mensajes cifrados con la versión 4.0.0 solo se pueden descifrar con la versión 4.0.0 o posterior de la versión para .NET. AWS Encryption SDK No se pueden descifrar mediante ninguna otra implementación de lenguaje de programación.
La versión 4.0.1 de .NET escribe AWS Encryption SDK los mensajes de acuerdo con la AWS Encryption SDK especificación de mensajes y es interoperable con otras implementaciones de lenguajes de programación. De forma predeterminada, la versión 4.0.1 puede leer los mensajes cifrados por la versión 4.0.0. Sin embargo, si no desea descifrar los mensajes cifrados con la versión 4.0.0, puede especificar la propiedad de la [https://github.com/aws/aws-encryption-sdk/tree/mainline/AwsEncryptionSDK/runtimes/net/Examples/NetV4_0_0Example.cs](https://github.com/aws/aws-encryption-sdk/tree/mainline/AwsEncryptionSDK/runtimes/net/Examples/NetV4_0_0Example.cs) para impedir que el cliente lea estos mensajes. Para obtener más información, consulte las [notas de la versión 4.0.1](https://github.com/aws/aws-encryption-sdk/releases/tag/v4.0.1) en el repositorio de. aws-encryption-sdk GitHub
La AWS Encryption SDK versión para .NET se diferencia de algunas de las implementaciones de otros lenguajes de programación AWS Encryption SDK en los siguientes aspectos:
+ No se admite el [almacenamiento en caché de claves de datos](data-key-caching.md)
**nota**
Versión 4. *x* de la versión AWS Encryption SDK para .NET es compatible con el [anillo de claves AWS KMS jerárquico](use-hierarchical-keyring.md), una solución alternativa de almacenamiento en caché de materiales criptográficos.
+ No es compatible con el streaming de datos
+ [Sin registros ni seguimientos de pilas](#dot-net-debugging) del AWS Encryption SDK para .NET
+ [Requiere el AWS SDK para .NET](#dot-net-install)
El AWS Encryption SDK para .NET incluye todas las funciones de seguridad introducidas en las versiones 2.0. *x* y versiones posteriores de las implementaciones en otros idiomas de AWS Encryption SDK. Sin embargo, si utiliza para.NET AWS Encryption SDK para descifrar datos cifrados con una versión anterior a la versión 2.0. *x* versión de la implementación en otro idioma de la AWS Encryption SDK, es posible que necesite ajustar su política de [compromisos](concepts.md#commitment-policy). Para obtener más información, consulte [¿Cómo establecer su política de compromiso?](migrate-commitment-policy.md#migrate-commitment-step1).
La AWS Encryption SDK versión para .NET es un producto de AWS Encryption SDK [Dafny](https://github.com/dafny-lang/dafny/blob/master/README.md), un lenguaje de verificación formal en el que se escriben las especificaciones, el código para implementarlas y las pruebas para probarlas. El resultado es una biblioteca que implementa las características del AWS Encryption SDK en una trama que garantiza la corrección funcional.
**Más información**
+ Para ver ejemplos que muestran cómo configurar las opciones del AWS Encryption SDK, como especificar un conjunto de algoritmos alternativo, limitar las claves de datos cifrados y utilizar claves AWS KMS multirregionales, consulte. [Configuración del AWS Encryption SDK](configure.md)
+ Para obtener más información sobre la AWS Encryption SDK programación con para.NET, consulte el [https://github.com/aws/aws-encryption-sdk/tree/mainline/AwsEncryptionSDK/runtimes/net/](https://github.com/aws/aws-encryption-sdk/tree/mainline/AwsEncryptionSDK/runtimes/net/)directorio del aws-encryption-sdk repositorio en GitHub.
**Topics**
+ [Instalar y compilar](#dot-net-install)
+ [Debugging](#dot-net-debugging)
+ [Ejemplos](dot-net-examples.md)
## Instalación del AWS Encryption SDK para .NET
El AWS Encryption SDK para .NET está disponible como [https://www.nuget.org/packages/AWS.Cryptography.EncryptionSDK](https://www.nuget.org/packages/AWS.Cryptography.EncryptionSDK)paquete en NuGet. Para obtener más información sobre la instalación y la creación de AWS Encryption SDK para .NET, consulte el archivo [README.md](https://github.com/aws/aws-encryption-sdk/tree/mainline/AwsEncryptionSDK/runtimes/net/#readme) del repositorio. `aws-encryption-sdk-net`
**Versión 3.x**
Versión 3. *x* de la AWS Encryption SDK para.NET solo es compatible con .NET Framework 4.5.2 — 4.8 en Windows. Es compatible con .NET Core 3.0\$1 y .NET 5.0 y versiones posteriores en todos los sistemas operativos compatibles.
**Versión 4.x**
Versión 4. *x* de la AWS Encryption SDK para.NET es compatible con .NET 6.0 y .NET Framework net48 y versiones posteriores. Versión 4. *x* requiere el AWS SDK para .NET v3.
**Versión 5.x**
Versión 5. *x* de la versión AWS Encryption SDK para .NET es compatible con .NET 6.0 y .NET Framework net48 y versiones posteriores. Versión 5. *x* requiere la versión 2. *x* de la biblioteca de proveedores de materiales (MPL) y el AWS SDK para .NET v4.
AWS Encryption SDK Para .NET se requieren las teclas « SDK para .NET par» si no se utilizan AWS Key Management Service (AWS KMS). Se instala con el NuGet paquete. Sin embargo, a menos que utilice AWS KMS claves, AWS Encryption SDK para .NET no se Cuenta de AWS requieren AWS credenciales ni interacción con ningún AWS servicio. Si necesita ayuda para configurar una AWS cuenta, consulte[Uso del AWS Encryption SDK con AWS KMS](getting-started.md).
## Depurar el AWS Encryption SDK para .NET
El AWS Encryption SDK para .NET no genera ningún registro. Las excepciones AWS Encryption SDK para .NET generan un mensaje de excepción, pero no hay rastros de pila.
Para ayudarle a depurar, asegúrese de activar el inicio de sesión en la SDK para .NET. Los registros y los mensajes de error del SDK para .NET pueden ayudarle a distinguir los errores que se producen en. NET SDK para .NET de los que se AWS Encryption SDK producen en él. Para obtener ayuda con el SDK para .NET registro, consulte [AWSLogging](https://docs.aws.amazon.com/sdk-for-net/v4/developer-guide/net-dg-config-other.html#config-setting-awslogging)la *Guía para AWS SDK para .NET desarrolladores*. (Para ver el tema, amplíe la sección **Abrir para ver la sección de contenido de .NET Framework**).
# AWS Encryption SDK para ver ejemplos de.NET
Los ejemplos siguientes muestran los patrones de codificación básicos que se utilizan al programar con AWS Encryption SDK para.NET. En concreto, se crea una instancia de la biblioteca AWS Encryption SDK y de proveedores de materiales. A continuación, antes de llamar a cada método, se crea una instancia de un objeto que define la entrada del método. Es muy parecido al patrón de codificación que utiliza en la SDK para .NET.
Para ver ejemplos que muestran cómo configurar las opciones de la AWS Encryption SDK, como especificar un conjunto de algoritmos alternativo, limitar las claves de datos cifrados y utilizar claves AWS KMS multirregionales, consulte. [Configuración del AWS Encryption SDK](configure.md)
Para ver más ejemplos de programación con AWS Encryption SDK para.NET, consulte los [ejemplos](https://github.com/aws/aws-encryption-sdk/tree/mainline/AwsEncryptionSDK/runtimes/net/Examples) en el `aws-encryption-sdk-net` directorio del `aws-encryption-sdk` repositorio en GitHub.
## Cifrar datos en el AWS Encryption SDK para .NET
En este ejemplo se muestra el patrón básico de cifrado de datos. Cifra un archivo pequeño con claves de datos que están protegidas por una clave de AWS KMS empaquetado.
Paso 1: Cree una instancia de la biblioteca AWS Encryption SDK y de los proveedores de materiales.
Comience por crear una instancia de la biblioteca AWS Encryption SDK y de los proveedores de materiales. Utilizará los métodos descritos en AWS Encryption SDK para cifrar y descifrar los datos. Utilizará los métodos de la biblioteca de proveedores de materiales para crear los conjuntos de claves que especifican qué claves protegen sus datos.
La forma de instanciar la biblioteca AWS Encryption SDK y la biblioteca de proveedores de materiales difiere entre las versiones 3. *x y 4*. *x* de AWS Encryption SDK para .NET. Todos los pasos siguientes son los mismos para ambas versiones 3. *x* y 4. *x* de AWS Encryption SDK para .NET.
```
// Instantiate the AWS Encryption SDK and material providers
var encryptionSdk = AwsEncryptionSdkFactory.CreateDefaultAwsEncryptionSdk();
var materialProviders =
AwsCryptographicMaterialProvidersFactory.CreateDefaultAwsCryptographicMaterialProviders();
```
```
// Instantiate the AWS Encryption SDK and material providers
var esdk = new ESDK(new AwsEncryptionSdkConfig());
var mpl = new MaterialProviders(new MaterialProvidersConfig());
```
Paso 2: crear un objeto de entrada para el conjunto de claves.
Cada método que crea un conjunto de claves tiene una clase de objeto de entrada correspondiente. Por ejemplo, para crear el objeto de entrada para el método `CreateAwsKmsKeyring()`, cree una instancia de la clase `CreateAwsKmsKeyringInput`.
Aunque la entrada de este conjunto de claves no especifica una [clave generadora](use-kms-keyring.md#kms-keyring-encrypt), la única clave KMS especificada por el parámetro `KmsKeyId` es la clave generadora. Genera y cifra la clave de datos que cifra los datos.
Este objeto de entrada requiere un AWS KMS cliente para Región de AWS la clave KMS. Para crear un AWS KMS cliente, cree una instancia de la `AmazonKeyManagementServiceClient` clase en. SDK para .NET Llamar al constructor de `AmazonKeyManagementServiceClient()` sin parámetros crea un cliente con los valores predeterminados.
En un AWS KMS conjunto de claves utilizado para cifrar con .NET, puede [identificar las claves de KMS mediante el](use-kms-keyring.md#kms-keyring-id) ID de clave, el ARN de clave, el nombre de alias o el alias ARN. AWS Encryption SDK En un conjunto de AWS KMS claves utilizado para descifrar, debe usar un ARN de clave para identificar cada clave de KMS. Si piensa reutilizar su conjunto de claves de cifrado para descifrar, utilice un identificador ARN de clave para todas las claves de KMS.
```
string keyArn = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab";
// Instantiate the keyring input object
var kmsKeyringInput = new CreateAwsKmsKeyringInput
{
KmsClient = new AmazonKeyManagementServiceClient(),
KmsKeyId = keyArn
};
```
Paso 3: crear el conjunto de claves.
Para crear el conjunto de claves, llame al método de conjunto de claves con el objeto de entrada del conjunto de claves. En este ejemplo, se utiliza el método `CreateAwsKmsKeyring()`, que solo necesita una clave de KMS.
```
var keyring = materialProviders.CreateAwsKmsKeyring(kmsKeyringInput);
```
Paso 4: definir un contexto de cifrado.
Un [contexto de cifrado](concepts.md#encryption-context) es un elemento opcional, pero muy recomendable, de las operaciones criptográficas del. AWS Encryption SDK Puede definir uno o varios pares clave-valor no secretos.
Con la versión 4. *x* AWS Encryption SDK para .NET, puede requerir un contexto de cifrado en todas las solicitudes de cifrado con el [contexto de cifrado requerido CMM](configure.md#config-required-encryption-context-cmm).
```
// Define the encryption context
var encryptionContext = new Dictionary()
{
{"purpose", "test"}
};
```
Paso 5: crear el objeto de entrada para cifrar.
Antes de llamar al método `Encrypt()`, cree una instancia de la clase `EncryptInput`.
```
string plaintext = File.ReadAllText("C:\\Documents\\CryptoTest\\TestFile.txt");
// Define the encrypt input
var encryptInput = new EncryptInput
{
Plaintext = plaintext,
Keyring = keyring,
EncryptionContext = encryptionContext
};
```
Paso 6: cifrar el texto no cifrado.
Utilice el `Encrypt()` método de AWS Encryption SDK para cifrar el texto sin formato mediante el conjunto de claves que haya definido.
La `EncryptOutput` que devuelve el método `Encrypt() ` contiene métodos para obtener el mensaje cifrado (`Ciphertext`), el contexto de cifrado y el conjunto de algoritmos.
```
var encryptOutput = encryptionSdk.Encrypt(encryptInput);
```
Paso 7: obtener el mensaje cifrado.
El `Decrypt()` método AWS Encryption SDK para .NET toma el `Ciphertext` miembro de la instancia. `EncryptOutput`
El miembro `Ciphertext` del objeto `EncryptOutput` es el [mensaje cifrado](concepts.md#message), un objeto portátil que incluye los datos cifrados, las claves de datos cifrados y los metadatos, incluido el contexto de cifrado. Puede almacenar de forma segura el mensaje cifrado durante un período prolongado o enviarlo al método de `Decrypt()` para recuperar el texto no cifrado.
```
var encryptedMessage = encryptOutput.Ciphertext;
```
## Descifrar en modo estricto en AWS Encryption SDK para.NET
Las prácticas recomendadas recomiendan especificar las claves que se utilizan para descifrar los datos, una opción conocida como *modo estricto*. AWS Encryption SDK Utiliza únicamente las claves KMS que especifique en su conjunto de claves para descifrar el texto cifrado. Las claves del conjunto de claves de descifrado deben incluir al menos una de las claves que cifraron los datos.
En este ejemplo se muestra el patrón básico de descifrado en modo estricto con la AWS Encryption SDK para .NET.
Paso 1: Cree una instancia de la biblioteca y de los proveedores de materiales. AWS Encryption SDK
```
// Instantiate the AWS Encryption SDK and material providers
var esdk = new ESDK(new AwsEncryptionSdkConfig());
var mpl = new MaterialProviders(new MaterialProvidersConfig());
```
Paso 2: crear un objeto de entrada para el conjunto de claves.
Para especificar los parámetros del método de conjunto de claves, cree un objeto de entrada. Cada método de conjunto de claves de .NET tiene un objeto de entrada correspondiente. AWS Encryption SDK Como en este ejemplo se utiliza el método `CreateAwsKmsKeyring()` para crear el conjunto de claves, se crea una instancia de la clase `CreateAwsKmsKeyringInput` para la entrada.
En un conjunto de claves de descifrado, debe usar el ARN de una clave para identificar claves KMS.
```
string keyArn = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab";
// Instantiate the keyring input object
var kmsKeyringInput = new CreateAwsKmsKeyringInput
{
KmsClient = new AmazonKeyManagementServiceClient(),
KmsKeyId = keyArn
};
```
Paso 3: crear el conjunto de claves.
Para crear el conjunto de claves de descifrado, en este ejemplo se utiliza el método `CreateAwsKmsKeyring()` y el objeto de entrada del conjunto de claves.
```
var keyring = materialProviders.CreateAwsKmsKeyring(kmsKeyringInput);
```
Paso 4: crear el objeto de entrada para descifrar.
Para crear el objeto de entrada para el método `Decrypt()`, cree una instancia de la clase `DecryptInput`.
El parámetro `Ciphertext` del constructor `DecryptInput()` toma el miembro `Ciphertext` del objeto `EncryptOutput` que devolvió el método `Encrypt()`. La propiedad `Ciphertext` representa el [mensaje cifrado](concepts.md#message), que incluye los datos cifrados, las claves de datos cifrados y los metadatos que la AWS Encryption SDK necesita para descifrar el mensaje.
Con la versión 4. *x* del AWS Encryption SDK para.NET, puede utilizar el `EncryptionContext` parámetro opcional para especificar el contexto de cifrado en el `Decrypt()` método.
Utilice el parámetro `EncryptionContext` para comprobar que el contexto de cifrado utilizado para cifrar *está incluido* en el contexto de cifrado utilizado para descifrar el texto cifrado. AWS Encryption SDK Añade pares al contexto de cifrado, incluida la firma digital si utilizas un conjunto de algoritmos con firma, como el conjunto de algoritmos predeterminado.
```
var encryptedMessage = encryptOutput.Ciphertext;
var decryptInput = new DecryptInput
{
Ciphertext = encryptedMessage,
Keyring = keyring,
EncryptionContext = encryptionContext // OPTIONAL
};
```
Paso 5: descifrar el texto cifrado.
```
var decryptOutput = encryptionSdk.Decrypt(decryptInput);
```
Paso 6: verificar el contexto de cifrado; versión 3.*x*
El `Decrypt()` método de la versión 3. *x* del AWS Encryption SDK para .NET no utiliza un contexto de cifrado. Obtiene los valores del contexto de cifrado de los metadatos en el mensaje cifrado. Sin embargo, antes de devolver o utilizar el texto no cifrado, se recomienda comprobar que el contexto de cifrado que se utilizó para descifrar el texto cifrado incluye el contexto de cifrado que proporcionó al cifrar.
Compruebe que el contexto de cifrado utilizado para cifrar *esté incluido* en el contexto de cifrado que se utilizó para descifrar el texto cifrado. AWS Encryption SDK Agrega pares al contexto de cifrado, incluida la firma digital si se utiliza un conjunto de algoritmos con firma, como el conjunto de algoritmos predeterminado.
```
// Verify the encryption context
string contextKey = "purpose";
string contextValue = "test";
if (!decryptOutput.EncryptionContext.TryGetValue(contextKey, out var decryptContextValue)
|| !decryptContextValue.Equals(contextValue))
{
throw new Exception("Encryption context does not match expected values");
}
```
## Descifrar con un anillo de claves de detección en el para.NET AWS Encryption SDK
En lugar de especificar las claves de KMS para el descifrado, puede proporcionar un *conjunto de claves de detección* de AWS KMS , que es un conjunto de claves que no especifica ninguna clave de KMS. Un anillo de claves de detección permite AWS Encryption SDK descifrar los datos utilizando la clave KMS que los haya cifrado, siempre que la persona que llama tenga permiso para descifrar la clave. Como práctica recomendada, añada un filtro de detección que limite las claves de KMS que se pueden usar a las Cuentas de AWS de una partición específica, en particular.
AWS Encryption SDK Para .NET, se proporciona un conjunto de claves de detección básico que requiere un AWS KMS cliente y un conjunto de claves de detección múltiple que requiere la especificación de uno o más. Regiones de AWS Tanto el cliente como las regiones limitan las claves KMS que se pueden usar para descifrar el mensaje cifrado. Los objetos de entrada de ambos conjuntos de claves utilizan el filtro de detección recomendado.
El siguiente ejemplo muestra el patrón de descifrado de datos con un conjunto de claves de detección de AWS KMS y un filtro de detección.
Paso 1: crear una instancia de la biblioteca AWS Encryption SDK y de la biblioteca de proveedores de materiales.
```
// Instantiate the AWS Encryption SDK and material providers
var esdk = new ESDK(new AwsEncryptionSdkConfig());
var mpl = new MaterialProviders(new MaterialProvidersConfig());
```
Paso 2: crear el objeto de entrada para el conjunto de claves.
Para especificar los parámetros del método de conjunto de claves, cree un objeto de entrada. Cada método de conjunto de claves de .NET tiene un objeto de entrada correspondiente. AWS Encryption SDK Como en este ejemplo se utiliza el método `CreateAwsKmsDiscoveryKeyring()` para crear el conjunto de claves, se crea una instancia de la clase `CreateAwsKmsDiscoveryKeyringInput` para la entrada.
```
List accounts = new List { "111122223333" };
var discoveryKeyringInput = new CreateAwsKmsDiscoveryKeyringInput
{
KmsClient = new AmazonKeyManagementServiceClient(),
DiscoveryFilter = new DiscoveryFilter()
{
AccountIds = accounts,
Partition = "aws"
}
};
```
Paso 3: crear el conjunto de claves.
Para crear el conjunto de claves de descifrado, en este ejemplo se utiliza el método `CreateAwsKmsDiscoveryKeyring()` y el objeto de entrada del conjunto de claves.
```
var discoveryKeyring = materialProviders.CreateAwsKmsDiscoveryKeyring(discoveryKeyringInput);
```
Paso 4: crear el objeto de entrada para descifrar.
Para crear el objeto de entrada para el método `Decrypt()`, cree una instancia de la clase `DecryptInput`. El valor del parámetro `Ciphertext` es el miembro `Ciphertext` del objeto `EncryptOutput` que devuelve el método `Encrypt()`.
Con la versión 4. *x* del AWS Encryption SDK para.NET, puede utilizar el `EncryptionContext` parámetro opcional para especificar el contexto de cifrado en el `Decrypt()` método.
Utilice el parámetro `EncryptionContext` para comprobar que el contexto de cifrado utilizado para cifrar *está incluido* en el contexto de cifrado utilizado para descifrar el texto cifrado. AWS Encryption SDK Añade pares al contexto de cifrado, incluida la firma digital si utilizas un conjunto de algoritmos con firma, como el conjunto de algoritmos predeterminado.
```
var ciphertext = encryptOutput.Ciphertext;
var decryptInput = new DecryptInput
{
Ciphertext = ciphertext,
Keyring = discoveryKeyring,
EncryptionContext = encryptionContext // OPTIONAL
};
var decryptOutput = encryptionSdk.Decrypt(decryptInput);
```
Paso 5: verificar el contexto de cifrado; versión 3.*x*
El `Decrypt()` método de la versión 3. *x* del AWS Encryption SDK para .NET no incluye un contexto de cifrado`Decrypt()`. Obtiene los valores del contexto de cifrado de los metadatos en el mensaje cifrado. Sin embargo, antes de devolver o utilizar el texto no cifrado, se recomienda comprobar que el contexto de cifrado que se utilizó para descifrar el texto cifrado incluye el contexto de cifrado que proporcionó al cifrar.
Compruebe que el contexto de cifrado utilizado para cifrar *esté incluido* en el contexto de cifrado que se utilizó para descifrar el texto cifrado. AWS Encryption SDK Añade pares al contexto de cifrado, incluida la firma digital si se utiliza un conjunto de algoritmos con firma, como el conjunto de algoritmos predeterminado.
```
// Verify the encryption context
string contextKey = "purpose";
string contextValue = "test";
if (!decryptOutput.EncryptionContext.TryGetValue(contextKey, out var decryptContextValue)
|| !decryptContextValue.Equals(contextValue))
{
throw new Exception("Encryption context does not match expected values");
}
```