SDK de cifrado de AWS para Python - AWS Encryption SDK

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

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-pythonrepositorio en GitHub. Para obtener API documentación, consulte Leer los documentos.

Requisitos previos

Antes de instalar el 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.

nota

La biblioteca de proveedores de material AWS criptográfico (MPL) es una dependencia opcional de la SDK de cifrado de AWS para Python versión 4. x. Si tiene intención de instalar elMPL, 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.

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 en la documentación de pip.

Instalación

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.

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 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 Migrar su AWS Encryption SDK.

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 (). MPL MPLContiene estructuras para cifrar y descifrar los datos. MPLEs una dependencia opcional para la SDK de cifrado de AWS para Python introducida en la versión 4. x. Recomendamos encarecidamente instalar elMPL. Sin embargo, si no tiene intención de utilizar elMPL, puede omitir el [MPL] sufijo.

Para obtener más información acerca de cómo utilizar pip para instalar y actualizar paquetes, consulte Instalación de paquetes.

SDK de cifrado de AWS para Python Requiere la biblioteca de criptografía (pyca/cryptography) 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.

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. 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-pythonrepositorio de GitHub.

Después de instalar el SDK de cifrado de AWS para Python, comience consultando el código de ejemplo de Python en esta guía.

La versión 4.x del SDK de cifrado de AWS para Python

En esta sección se describen las nuevas funciones introducidas por la versión 4. x de SDK de cifrado de AWS para Python cuando se usa con la dependencia opcional de la biblioteca de proveedores de material criptográfico (MPL).

Cuando se utiliza la versión 4. x de SDK de cifrado de AWS para Python con elMPL, puede utilizar anillos de claves para realizar el cifrado de sobres. 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. Para ver ejemplos sobre cómo migrar de proveedores de claves maestras a conjuntos de claves, consulta los ejemplos de migración en el repositorio deaws-encryption-sdk-python. GitHub

Los ejemplos de este tema crean una instancia del AWS Encryption SDK cliente con la política de compromiso predeterminada,. REQUIRE_ENCRYPT_REQUIRE_DECRYPT Para obtener más información, consulte Establecer su política de compromiso.

AWS KMS llaveros en el SDK de cifrado de AWS para Python

Los AWS KMS llaveros básicos SDK de cifrado de AWS para Python tienen una sola KMS tecla. También requieren un AWS KMS cliente, lo que le da la oportunidad de configurar el cliente para Región de AWS la KMS clave.

Para crear un AWS KMS llavero con una o más llaves de embalaje, utilice un llavero múltiple. SDK de cifrado de AWS para Python Tiene un llavero especial con varios llaveros que admite una o más AWS KMS llaves y un llavero estándar con varios llaveros de cualquier tipo compatible. Algunos programadores prefieren usar un método de llaveros múltiples para crear todos sus llaveros, y este método apoya esa estrategia. SDK de cifrado de AWS para Python

SDK de cifrado de AWS para Python Proporciona llaveros básicos de una sola tecla y varios llaveros para todos los casos de uso típicos, incluidas las claves multirregionales. AWS KMS

Por ejemplo, para crear un AWS KMS llavero con una sola AWS KMS tecla, puede utilizar el método. create_aws_kms_keyring()

# Instantiate the AWS Encryption SDK client client = aws_encryption_sdk.EncryptionSDKClient( commitment_policy=CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT ) # Create a boto3 client for AWS KMS kms_client = boto3.client('kms', region_name="us-west-2") # Optional: Create an encryption context 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", } # Instantiate the material providers library mat_prov: AwsCryptographicMaterialProviders = AwsCryptographicMaterialProviders( config=MaterialProvidersConfig() ) # Create the AWS KMS keyring keyring_input: CreateAwsKmsKeyringInput = CreateAwsKmsKeyringInput( kms_key_id=arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab, kms_client=kms_client ) kms_keyring: IKeyring = mat_prov.create_aws_kms_keyring( input=keyring_input )

Para crear un llavero con una o más AWS KMS teclas, utilice el create_aws_kms_multi_keyring() método. En este ejemplo se utilizan dos claves de KMS. Para especificar una KMS clave, utilice únicamente el generator parámetro. El kms_key_ids parámetro que especifica KMS claves adicionales es opcional.

La entrada de este conjunto de claves no requiere un AWS KMS cliente. En su lugar, AWS Encryption SDK utiliza el AWS KMS cliente predeterminado para cada región representado por una KMS clave en el anillo de claves. Por ejemplo, si la KMS clave identificada por el valor del generator parámetro se encuentra en la región EE.UU. Oeste (Oregón) (us-west-2), se AWS Encryption SDK crea un AWS KMS cliente predeterminado para la us-west-2 región. Si necesita personalizar el AWS KMS cliente, utilice el create_aws_kms_keyring() método.

# Instantiate the AWS Encryption SDK client client = aws_encryption_sdk.EncryptionSDKClient( commitment_policy=CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT ) # Optional: Create an encryption context 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", } # Instantiate the material providers library mat_prov: AwsCryptographicMaterialProviders = AwsCryptographicMaterialProviders( config=MaterialProvidersConfig() ) # Create the AWS KMS keyring kms_multi_keyring_input: CreateAwsKmsMultiKeyringInput = CreateAwsKmsMultiKeyringInput( generator=default_region_kms_key_id, kms_key_ids=[second_region_kms_key_id] ) kms_multi_keyring: IKeyring = mat_prov.create_aws_kms_multi_keyring( input=kms_multi_keyring_input )

SDK de cifrado de AWS para Python admite conjuntos de AWS KMS claves que utilizan cifrado simétrico (SYMMETRIC_DEFAULT) o claves RSA KMS asimétricas. AWS KMS los llaveros creados con RSA KMS claves asimétricas solo pueden contener un par de claves.

Para cifrar con un RSA AWS KMS anillo de claves asimétrico, no necesita kms: GenerateDataKey ni KMS:Encrypt, ya que debe especificar el material de clave pública que desea utilizar para el cifrado al crear el anillo de claves. No se realizan llamadas a AWS KMS al cifrar con este conjunto de claves. Para descifrar con un anillo de claves asimétrico, necesita el permiso KMS:Decrypt. RSA AWS KMS

Para crear un conjunto de claves asimétrico, debe proporcionar la RSA AWS KMS clave pública y la clave privada de su clave asimétrica. ARN RSA KMS La clave pública debe estar codificada. PEM En el siguiente ejemplo, se crea un AWS KMS llavero con un par de RSA claves asimétricas.

# Instantiate the AWS Encryption SDK client client = aws_encryption_sdk.EncryptionSDKClient( commitment_policy=CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT ) # Optional: Create an encryption context 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", } # Instantiate the material providers library mat_prov: AwsCryptographicMaterialProviders = AwsCryptographicMaterialProviders( config=MaterialProvidersConfig() ) # Create the AWS KMS keyring keyring_input: CreateAwsKmsRsaKeyringInput = CreateAwsKmsRsaKeyringInput( public_key=public_key, kms_key_id=kms_key_id, encryption_algorithm="RSAES_OAEP_SHA_256", kms_client=kms_client ) kms_rsa_keyring: IKeyring = mat_prov.create_aws_kms_rsa_keyring( input=keyring_input )

Contextos de cifrado obligatorio en la versión 4.x

Cuando se utiliza la versión 4. x de SDK de cifrado de AWS para Python con laMPL, puede usar el contexto de cifrado requerido CMM para requerir contextos de cifrado en sus operaciones criptográficas. Un contexto de cifrado es un conjunto de pares de clave-valor no secretos. El contexto de cifrado se vincula criptográficamente a los datos cifrados, de tal forma que se requiere el mismo contexto de cifrado para descifrar los datos. Si utiliza el contexto de cifrado requeridoCMM, puede especificar una o más claves de contexto de cifrado necesarias (claves obligatorias) que deben incluirse en todas las llamadas de cifrado y descifrado.

nota

El contexto de cifrado necesario solo CMM es compatible con las siguientes versiones:

  • Versión 3. x del SDK de cifrado de AWS para Java

  • Versión 4. x del AWS Encryption SDK formulario. NET

  • Versión 4. x de SDK de cifrado de AWS para Python, cuando se usa con la dependencia opcional de la biblioteca de proveedores de material criptográfico (MPL).

Si cifra los datos con el contexto de cifrado requeridoCMM, solo podrá descifrarlos con una de estas versiones compatibles.

Al cifrar, AWS Encryption SDK comprueba que todas las claves de contexto de cifrado necesarias estén incluidas en el contexto de cifrado que especificó. Firma AWS Encryption SDK los contextos de cifrado que especificó. Solo los pares clave-valor que no son claves obligatorias se serializan y almacenan en texto no cifrado en el encabezado del mensaje cifrado que devuelve la operación de cifrado.

Al descifrar, debe proporcionar un contexto de cifrado que contenga todos los pares clave-valor que representan las claves necesarias. AWS Encryption SDK Utiliza este contexto de cifrado y los pares clave-valor almacenados en el encabezado del mensaje cifrado para reconstruir el contexto de cifrado original que especificó en la operación de cifrado. Si AWS Encryption SDK no se puede reconstruir el contexto de cifrado original, se produce un error en la operación de descifrado. Si proporciona un par clave-valor que contiene la clave requerida con un valor incorrecto, el mensaje cifrado no se puede descifrar. Debe proporcionar el mismo par clave-valor que se especificó al cifrar.

importante

Considere detenidamente qué valores elige para las claves requeridas en su contexto de cifrado. Debe poder volver a proporcionar las mismas claves y sus valores correspondientes al descifrar. Si no puede reproducir las claves requeridas, el mensaje cifrado no se podrá descifrar.

El siguiente ejemplo inicializa un conjunto de AWS KMS claves con el contexto de cifrado requerido. CMM

# Instantiate the AWS Encryption SDK client client = aws_encryption_sdk.EncryptionSDKClient( commitment_policy=CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT ) # Create your encryption context encryption_context: Dict[str, str] = { "key1": "value1", "key2": "value2", "requiredKey1": "requiredValue1", "requiredKey2": "requiredValue2" } # Create a list of required encryption context keys required_encryption_context_keys: List[str] = ["requiredKey1", "requiredKey2"] # Instantiate the material providers library mpl: AwsCryptographicMaterialProviders = AwsCryptographicMaterialProviders( config=MaterialProvidersConfig() ) # Create the AWS KMS keyring keyring_input: CreateAwsKmsKeyringInput = CreateAwsKmsKeyringInput( kms_key_id=kms_key_id, kms_client=boto3.client('kms', region_name="us-west-2") ) kms_keyring: IKeyring = mpl.create_aws_kms_keyring(keyring_input) # Create the required encryption context CMM underlying_cmm: ICryptographicMaterialsManager = \ mpl.create_default_cryptographic_materials_manager( CreateDefaultCryptographicMaterialsManagerInput( keyring=kms_keyring ) ) required_ec_cmm: ICryptographicMaterialsManager = \ mpl.create_required_encryption_context_cmm( CreateRequiredEncryptionContextCMMInput( required_encryption_context_keys=required_encryption_context_keys, underlying_cmm=underlying_cmm, ) )