Cifrado de datos Descifrar en modo estricto Descifrar con un conjunto de claves de detección de AWS KMS

Ejemplos de la AWS Encryption SDK para .NET

Los ejemplos siguientes muestran los patrones de codificación básicos que se utilizan al programar con la 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 AWS SDK for .NET.

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 multirregionales de AWS KMS, consulte Configuración del AWS Encryption SDK.

Para ver más ejemplos de programación con la AWS Encryption SDK para .NET, consulte los ejemplos en el directorio de aws-encryption-sdk-net del repositorio aws-encryption-sdk-dafny en GitHub.

Cifrado de datos en la 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 encapsulamiento de AWS KMS.

Paso 1: crear una instancia de la biblioteca AWS Encryption SDK y de proveedores de materiales.

Comience por crear una instancia de la biblioteca AWS Encryption SDK y de proveedores de materiales. Utilizará los métodos en la AWS Encryption SDK para cifrar y descifrar 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 crear instancias de la biblioteca AWS Encryption SDK y de proveedores de materiales difiere entre las versiones 3.x y 4.x de la AWS Encryption SDK para .NET. Todos los pasos siguientes son los mismos para ambas versiones 3.x y 4.x de la AWS Encryption SDK para .NET.

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, 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 cliente de AWS KMS para la Región de AWS de la clave KMS. Para crear un cliente de AWS KMS, cree una instancia de la clase AmazonKeyManagementServiceClient en la AWS SDK for .NET. Llamar al constructor de AmazonKeyManagementServiceClient() sin parámetros crea un cliente con los valores predeterminados.

En un conjunto de claves de AWS KMS utilizado para cifrar con la AWS Encryption SDK para .NET, puede identificar las claves KMS mediante el ID de clave, ARN de clave, nombre de alias o ARN del alias. En un conjunto de claves de AWS KMS que se utiliza para descifrar, debe usar el ARN de una clave para identificar cada clave 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.

El contexto de cifrado es opcional, pero es un elemento de operaciones criptográficas en la AWS Encryption SDK que se recomienda encarecidamente. Puede definir uno o varios pares clave-valor no secretos.

nota

Con la versión 4.x de la AWS Encryption SDK para .NET, puede requerir un contexto de cifrado en todas las solicitudes de cifrado con el CMM de contexto de cifrado requerido.


// Define the encryption context
var encryptionContext = new Dictionary<string, string>()
{
    {"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 método de Encrypt() del AWS Encryption SDK para cifrar el texto no cifrado utilizando 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 método Decrypt() en la AWS Encryption SDK para .NET toma al miembro Ciphertext de la instancia EncryptOutput.

El miembro Ciphertext del objeto EncryptOutput es el mensaje cifrado, 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 la 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. El AWS Encryption SDK utiliza únicamente las claves KMS que especifique en el 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: crear una instancia de la biblioteca AWS Encryption SDK y 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 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 AWS Encryption SDK para .NET tiene un objeto de entrada correspondiente. 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, 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 de la AWS Encryption SDK para .NET, puede utilizar el parámetro EncryptionContext opcional para especificar el contexto de cifrado en el método Decrypt().

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. La AWS Encryption SDK añade pares al contexto de cifrado, incluida la firma digital si utiliza 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 método Decrypt() de la versión 3.x de la 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. La AWS Encryption SDK añade pares al contexto de cifrado, incluida la firma digital si 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 conjunto de claves de detección en el AWS Encryption SDK para .NET

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 conjunto de claves de detección permite al 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 KMS que se pueden usar a las Cuentas de AWS de una partición específica, en particular.

El AWS Encryption SDK para .NET proporciona un conjunto de claves de detección básico que requiere un cliente de AWS KMS y un conjunto de claves múltiple de detección que requiere que especifique 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 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 AWS Encryption SDK para .NET tiene un objeto de entrada correspondiente. 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<string> accounts = new List<string> { "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 de la AWS Encryption SDK para .NET, puede utilizar el parámetro EncryptionContext opcional para especificar el contexto de cifrado en el método Decrypt().


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 método Decrypt() de la versión 3.x de la AWS Encryption SDK para .NET no utiliza un contexto de cifrado en 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.


// 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");
}

Aviso JavaScript está desactivado o no está disponible en su navegador.

Para utilizar la documentación de AWS, debe estar habilitado JavaScript. Para obtener más información, consulte las páginas de ayuda de su navegador.

Convenciones del documento

.NET

Java