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.

# SDK de cifrado de AWS para Python
<a name="python"></a>

En este tema se explica cómo instalar y utilizar el SDK de cifrado de AWS para Python. Para obtener detalles sobre la programación con SDK de cifrado de AWS para Python, consulte el [aws-encryption-sdk-python](https://github.com/aws/aws-encryption-sdk-python/)repositorio en GitHub. Para obtener documentación de la API, consulte [Leer los documentos](https://aws-encryption-sdk-python.readthedocs.io/en/latest/).

**Topics**
+ [Requisitos previos](#python-prerequisites)
+ [Instalación](#python-installation)
+ [Ejemplos](python-example-code.md)

## Requisitos previos
<a name="python-prerequisites"></a>

Antes de instalarlo SDK de cifrado de AWS para Python, asegúrese de cumplir los siguientes requisitos previos.

**Una versión compatible de Python**  
 SDK de cifrado de AWS para Python Las versiones 3.2.0 y posteriores requieren Python 3.8 o posterior.  
La [biblioteca de proveedores de material AWS criptográfico](https://github.com/aws/aws-cryptographic-material-providers-library) (MPL) es una dependencia opcional de la versión SDK de cifrado de AWS para Python 4. *x.* Si piensa instalar el MPL, debe usar Python 3.11 o posterior.
Las versiones anteriores son AWS Encryption SDK compatibles con Python 2.7 y Python 3.4 y versiones posteriores, pero le recomendamos que utilice la versión más reciente de AWS Encryption SDK.   
Para descargar Python, visite el sitio de [descargas de Python](https://www.python.org/downloads/).

**La herramienta de instalación pip para Python**  
`pip` está incluido en Python 3.6 y versiones posteriores, aunque es posible que desee actualizarlo. Para obtener más información acerca de la actualización o la instalación de `pip`, consulte la sección sobre la [instalación](https://pip.pypa.io/en/latest/installation/) en la documentación de `pip`.

## Instalación
<a name="python-installation"></a>

Instale la versión más reciente de SDK de cifrado de AWS para Python.

**nota**  
Todas las versiones SDK de cifrado de AWS para Python anteriores a la 3.0.0 están en [end-of-supportfase](https://docs.aws.amazon.com/sdkref/latest/guide/maint-policy.html#version-life-cycle).  
Puede actualizar de forma segura desde la versión 2.0.*x* y versiones posteriores a la última versión de AWS Encryption SDK sin cambios en el código ni en los datos. Sin embargo, [nuevas características de seguridad](about-versions.md#version-2) que se introdujeron en la versión 2.0.*x* no son compatibles con versiones anteriores. Para actualizar desde versiones anteriores a la 1.7.*x* a la versión 2.0.*x* y posteriores, primero debe actualizar a la última versión 1.*x* de AWS Encryption SDK. Para obtener más información, consulte [Migrando su AWS Encryption SDK](migration.md).

Se utiliza `pip` para instalar el SDK de cifrado de AWS para Python, como se muestra en los siguientes ejemplos.

**Para instalar la versión más reciente**  

```
pip install "aws-encryption-sdk[MPL]"
```
El `[MPL]` sufijo instala la [biblioteca de proveedores de material AWS criptográfico](https://github.com/aws/aws-cryptographic-material-providers-library) (MPL). La MPL contiene estructuras para cifrar y descifrar los datos. La MPL es una dependencia opcional de la introducida en la SDK de cifrado de AWS para Python versión 4. *x*. Recomendamos encarecidamente instalar el MPL. Sin embargo, si no tiene intención de utilizar el MPL, puede omitir el sufijo. `[MPL]`

Para obtener más información acerca de cómo utilizar pip para instalar y actualizar paquetes, consulte [Instalación de paquetes](https://packaging.python.org/tutorials/installing-packages/).

 SDK de cifrado de AWS para Python Requiere la [biblioteca de criptografía (pyca/cryptography](https://cryptography.io/en/latest/)) en todas las plataformas. Todas las versiones de `pip` instalan y compilan automáticamente la biblioteca de `cryptography` en Windows. La versión 8.1 de `pip` y las versiones posteriores se instalan y compilan automáticamente `cryptography` en Linux. Si utiliza una versión anterior de `pip` y su entorno Linux no dispone de las herramientas necesarias para crear la biblioteca `cryptography`, tiene que instalarlas. Para obtener más información, consulte [Building cryptography on Linux](https://cryptography.io/en/latest/installation.html#building-cryptography-on-linux).

[Las versiones 1.10.0 y 2.5.0 sitúan la dependencia criptográfica entre las versiones 2.5.0 y SDK de cifrado de AWS para Python 3.3.2.](https://cryptography.io/en/latest/) Otras versiones SDK de cifrado de AWS para Python instalan la última versión de la criptografía. Si necesita una versión de criptografía posterior a la 3.3.2, le recomendamos que utilice la última versión principal del SDK de cifrado de AWS para Python.

Para obtener la última versión de desarrollo de SDK de cifrado de AWS para Python, vaya al [aws-encryption-sdk-python](https://github.com/aws/aws-encryption-sdk-python/)repositorio de GitHub.

Después de instalar el SDK de cifrado de AWS para Python, comience consultando el [código de ejemplo de Python](python-example-code.md) en esta guía.

# SDK de cifrado de AWS para Python código de ejemplo
<a name="python-example-code"></a>

Los siguientes ejemplos muestran cómo utilizar el SDK de cifrado de AWS para Python para cifrar y descifrar datos.

Los ejemplos de esta sección muestran cómo utilizar la versión 4. *x* de SDK de cifrado de AWS para Python con la dependencia opcional de la [biblioteca de proveedores de material criptográfico](https://github.com/aws/aws-cryptographic-material-providers-library) (`aws-cryptographic-material-providers`). Para ver ejemplos que utilizan versiones anteriores o instalaciones sin la biblioteca de proveedores de materiales (MPL), busca tu versión en la lista de [versiones](https://github.com/aws/aws-encryption-sdk-python/releases) del [aws-encryption-sdk-python](https://github.com/aws/aws-encryption-sdk-python/)repositorio de. GitHub

Cuando usas la versión 4. *x* SDK de cifrado de AWS para Python con la MPL, utiliza [anillos de claves](choose-keyring.md) para realizar el cifrado de [sobres.](concepts.md#envelope-encryption) AWS Encryption SDK Proporciona anillos de claves que son compatibles con los proveedores de claves maestras que utilizaba en versiones anteriores. Para obtener más información, consulte [Compatibilidad de conjuntos de claves](choose-keyring.md#keyring-compatibility). Para ver ejemplos sobre la migración de proveedores de claves maestras a conjuntos de claves, consulte los [ejemplos de migración](https://github.com/aws/aws-encryption-sdk-python/tree/master/examples/src/migration) en el repositorio de; `aws-encryption-sdk-python` GitHub

**Topics**
+ [Cadenas](#python-example-strings)
+ [Secuencias de bytes](#python-example-streams)

## Cifrado y descifrado de cadenas
<a name="python-example-strings"></a>

El siguiente ejemplo muestra cómo utilizarlos AWS Encryption SDK para cifrar y descifrar cadenas. En este ejemplo, se utiliza un [AWS KMS anillo de claves](use-kms-keyring.md) con una clave KMS de cifrado simétrico.

En este ejemplo, se crea una instancia del AWS Encryption SDK cliente con la política de compromiso [predeterminada](migrate-commitment-policy.md),. `REQUIRE_ENCRYPT_REQUIRE_DECRYPT` Para obtener más información, consulte [Establecer su política de compromiso](migrate-commitment-policy.md).

```
# Copyright Amazon.com Inc. or its affiliates. All Rights Reserved.
# SPDX-License-Identifier: Apache-2.0
"""
This example sets up the KMS Keyring

The AWS KMS keyring uses symmetric encryption KMS keys to generate, encrypt and
decrypt data keys. This example creates a KMS Keyring and then encrypts a custom input EXAMPLE_DATA
with an encryption context. This example also includes some sanity checks for demonstration:
1. Ciphertext and plaintext data are not the same
2. Encryption context is correct in the decrypted message header
3. Decrypted plaintext value matches EXAMPLE_DATA
These sanity checks are for demonstration in the example only. You do not need these in your code.

AWS KMS keyrings can be used independently or in a multi-keyring with other keyrings
of the same or a different type.

"""

import boto3
from aws_cryptographic_material_providers.mpl import AwsCryptographicMaterialProviders
from aws_cryptographic_material_providers.mpl.config import MaterialProvidersConfig
from aws_cryptographic_material_providers.mpl.models import CreateAwsKmsKeyringInput
from aws_cryptographic_material_providers.mpl.references import IKeyring
from typing import Dict  # noqa pylint: disable=wrong-import-order

import aws_encryption_sdk
from aws_encryption_sdk import CommitmentPolicy

EXAMPLE_DATA: bytes = b"Hello World"


def encrypt_and_decrypt_with_keyring(
    kms_key_id: str
):
    """Demonstrate an encrypt/decrypt cycle using an AWS KMS keyring.

    Usage: encrypt_and_decrypt_with_keyring(kms_key_id)
    :param kms_key_id: KMS Key identifier for the KMS key you want to use for encryption and
    decryption of your data keys.
    :type kms_key_id: string
    
    """
    # 1. Instantiate the encryption SDK client.
    # This builds the client with the REQUIRE_ENCRYPT_REQUIRE_DECRYPT commitment policy,
    # which enforces that this client only encrypts using committing algorithm suites and enforces
    # that this client will only decrypt encrypted messages that were created with a committing
    # algorithm suite.
    # This is the default commitment policy if you were to build the client as
    # `client = aws_encryption_sdk.EncryptionSDKClient()`.
    client = aws_encryption_sdk.EncryptionSDKClient(
        commitment_policy=CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT
    )

    # 2. Create a boto3 client for KMS.
    kms_client = boto3.client('kms', region_name="us-west-2")

    # 3. Optional: create encryption context.
    # Remember that your encryption context is NOT SECRET.
    encryption_context: Dict[str, str] = {
        "encryption": "context",
        "is not": "secret",
        "but adds": "useful metadata",
        "that can help you": "be confident that",
        "the data you are handling": "is what you think it is",
    }

    # 4. Create your keyring
    mat_prov: AwsCryptographicMaterialProviders = AwsCryptographicMaterialProviders(
        config=MaterialProvidersConfig()
    )

    keyring_input: CreateAwsKmsKeyringInput = CreateAwsKmsKeyringInput(
        kms_key_id=kms_key_id,
        kms_client=kms_client
    )

    kms_keyring: IKeyring = mat_prov.create_aws_kms_keyring(
        input=keyring_input
    )

    # 5. Encrypt the data with the encryptionContext.
    ciphertext, _ = client.encrypt(
        source=EXAMPLE_DATA,
        keyring=kms_keyring,
        encryption_context=encryption_context
    )

    # 6. Demonstrate that the ciphertext and plaintext are different.
    # (This is an example for demonstration; you do not need to do this in your own code.)
    assert ciphertext != EXAMPLE_DATA, \
        "Ciphertext and plaintext data are the same. Invalid encryption"

    # 7. Decrypt your encrypted data using the same keyring you used on encrypt.
    plaintext_bytes, _ = client.decrypt(
        source=ciphertext,
        keyring=kms_keyring,
        # Provide the encryption context that was supplied to the encrypt method
        encryption_context=encryption_context,
    )

    # 8. Demonstrate that the decrypted plaintext is identical to the original plaintext.
    # (This is an example for demonstration; you do not need to do this in your own code.)
    assert plaintext_bytes == EXAMPLE_DATA, \
        "Decrypted plaintext should be identical to the original plaintext. Invalid decryption"
```

## Cifrado y descifrado de secuencias de bytes
<a name="python-example-streams"></a>

El siguiente ejemplo muestra cómo utilizarla AWS Encryption SDK para cifrar y descifrar secuencias de bytes. En este ejemplo se utiliza un anillo de claves [AES sin procesar.](use-raw-aes-keyring.md)

En este ejemplo, se crea una instancia del AWS Encryption SDK cliente con la política de [compromiso predeterminada](migrate-commitment-policy.md),. `REQUIRE_ENCRYPT_REQUIRE_DECRYPT` Para obtener más información, consulte [Establecer su política de compromiso](migrate-commitment-policy.md).

```
# Copyright Amazon.com Inc. or its affiliates. All Rights Reserved.
# SPDX-License-Identifier: Apache-2.0
"""
This example demonstrates file streaming for encryption and decryption.

File streaming is useful when the plaintext or ciphertext file/data is too large to load into
memory. Therefore, the AWS Encryption SDK allows users to stream the data, instead of loading it
all at once in memory. In this example, we demonstrate file streaming for encryption and decryption
using a Raw AES keyring. However, you can use any keyring with streaming.

This example creates a Raw AES Keyring and then encrypts an input stream from the file
`plaintext_filename` with an encryption context to an output (encrypted) file `ciphertext_filename`.
It then decrypts the ciphertext from `ciphertext_filename` to a new file `decrypted_filename`.
This example also includes some sanity checks for demonstration:
1. Ciphertext and plaintext data are not the same
2. Encryption context is correct in the decrypted message header
3. Decrypted plaintext value matches EXAMPLE_DATA
These sanity checks are for demonstration in the example only. You do not need these in your code.

See raw_aes_keyring_example.py in the same directory for another raw AES keyring example
in the AWS Encryption SDK for Python.
"""
import filecmp
import secrets

from aws_cryptographic_material_providers.mpl import AwsCryptographicMaterialProviders
from aws_cryptographic_material_providers.mpl.config import MaterialProvidersConfig
from aws_cryptographic_material_providers.mpl.models import AesWrappingAlg, CreateRawAesKeyringInput
from aws_cryptographic_material_providers.mpl.references import IKeyring
from typing import Dict  # noqa pylint: disable=wrong-import-order

import aws_encryption_sdk
from aws_encryption_sdk import CommitmentPolicy


def encrypt_and_decrypt_with_keyring(
    plaintext_filename: str,
    ciphertext_filename: str,
    decrypted_filename: str
):
    """Demonstrate a streaming encrypt/decrypt cycle.

    Usage: encrypt_and_decrypt_with_keyring(plaintext_filename
                                            ciphertext_filename
                                            decrypted_filename)
    :param plaintext_filename: filename of the plaintext data
    :type plaintext_filename: string
    :param ciphertext_filename: filename of the ciphertext data
    :type ciphertext_filename: string
    :param decrypted_filename: filename of the decrypted data
    :type decrypted_filename: string
    """
    # 1. Instantiate the encryption SDK client.
    # This builds the client with the REQUIRE_ENCRYPT_REQUIRE_DECRYPT commitment policy,
    # which enforces that this client only encrypts using committing algorithm suites and enforces
    # that this client will only decrypt encrypted messages that were created with a committing
    # algorithm suite.
    # This is the default commitment policy if you were to build the client as
    # `client = aws_encryption_sdk.EncryptionSDKClient()`.
    client = aws_encryption_sdk.EncryptionSDKClient(
        commitment_policy=CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT
    )

    # 2. The key namespace and key name are defined by you.
    # and are used by the Raw AES keyring to determine
    # whether it should attempt to decrypt an encrypted data key.
    key_name_space = "Some managed raw keys"
    key_name = "My 256-bit AES wrapping key"

    # 3. Optional: create encryption context.
    # Remember that your encryption context is NOT SECRET.
    encryption_context: Dict[str, str] = {
        "encryption": "context",
        "is not": "secret",
        "but adds": "useful metadata",
        "that can help you": "be confident that",
        "the data you are handling": "is what you think it is",
    }

    # 4. Generate a 256-bit AES key to use with your keyring.
    # In practice, you should get this key from a secure key management system such as an HSM.

    # Here, the input to secrets.token_bytes() = 32 bytes = 256 bits
    static_key = secrets.token_bytes(32)

    # 5. Create a Raw AES keyring
    # We choose to use a raw AES keyring, but any keyring can be used with streaming.
    mat_prov: AwsCryptographicMaterialProviders = AwsCryptographicMaterialProviders(
        config=MaterialProvidersConfig()
    )

    keyring_input: CreateRawAesKeyringInput = CreateRawAesKeyringInput(
        key_namespace=key_name_space,
        key_name=key_name,
        wrapping_key=static_key,
        wrapping_alg=AesWrappingAlg.ALG_AES256_GCM_IV12_TAG16
    )

    raw_aes_keyring: IKeyring = mat_prov.create_raw_aes_keyring(
        input=keyring_input
    )

    # 6. Encrypt the data stream with the encryptionContext
    with open(plaintext_filename, 'rb') as pt_file, open(ciphertext_filename, 'wb') as ct_file:
        with client.stream(
            mode='e',
            source=pt_file,
            keyring=raw_aes_keyring,
            encryption_context=encryption_context
        ) as encryptor:
            for chunk in encryptor:
                ct_file.write(chunk)

    # 7. Demonstrate that the ciphertext and plaintext are different.
    # (This is an example for demonstration; you do not need to do this in your own code.)
    assert not filecmp.cmp(plaintext_filename, ciphertext_filename), \
        "Ciphertext and plaintext data are the same. Invalid encryption"

    # 8. Decrypt your encrypted data stream using the same keyring you used on encrypt.
    with open(ciphertext_filename, 'rb') as ct_file, open(decrypted_filename, 'wb') as pt_file:
        with client.stream(
            mode='d',
            source=ct_file,
            keyring=raw_aes_keyring,
            encryption_context=encryption_context
        ) as decryptor:
            for chunk in decryptor:
                pt_file.write(chunk)

    # 10. Demonstrate that the decrypted plaintext is identical to the original plaintext.
    # (This is an example for demonstration; you do not need to do this in your own code.)
    assert filecmp.cmp(plaintext_filename, decrypted_filename), \
        "Decrypted plaintext should be identical to the original plaintext. Invalid decryption"
```