Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris.

# AWS Encryption SDK for Python
<a name="python"></a>

Topik ini menjelaskan cara menginstal dan menggunakan AWS Encryption SDK for Python. Untuk detail tentang pemrograman dengan AWS Encryption SDK for Python, lihat [aws-encryption-sdk-python](https://github.com/aws/aws-encryption-sdk-python/)repositori di. GitHub Untuk dokumentasi API, lihat [Membaca Dokumen.](https://aws-encryption-sdk-python.readthedocs.io/en/latest/)

**Topics**
+ [Prasyarat](#python-prerequisites)
+ [Penginstalan](#python-installation)
+ [Contoh](python-example-code.md)

## Prasyarat
<a name="python-prerequisites"></a>

Sebelum Anda menginstal AWS Encryption SDK for Python, pastikan Anda memiliki prasyarat berikut.

**Versi Python yang didukung**  
Python 3.8 atau yang lebih baru diperlukan oleh AWS Encryption SDK for Python versi 3.2.0 dan yang lebih baru.  
[AWS Cryptographic Material Providers Library](https://github.com/aws/aws-cryptographic-material-providers-library) (MPL) adalah dependensi opsional untuk yang AWS Encryption SDK for Python diperkenalkan di versi 4. *x*. Jika Anda berniat menginstal MPL, Anda harus menggunakan Python 3.11 atau yang lebih baru.
Versi sebelumnya dari AWS Encryption SDK dukungan Python 2.7 dan Python 3.4 dan yang lebih baru, tetapi kami menyarankan Anda menggunakan versi terbaru dari versi. AWS Encryption SDK  
Untuk mengunduh Python, lihat [Unduh Python](https://www.python.org/downloads/).

**Alat instalasi pip untuk Python**  
`pip`termasuk dalam Python 3.6 dan versi yang lebih baru, meskipun Anda mungkin ingin memutakhirkannya. Untuk informasi selengkapnya tentang memutakhirkan atau menginstal`pip`, lihat [Instalasi](https://pip.pypa.io/en/latest/installation/) di `pip` dokumentasi.

## Penginstalan
<a name="python-installation"></a>

Instal versi terbaru dari file AWS Encryption SDK for Python.

**catatan**  
[Semua versi yang AWS Encryption SDK for Python lebih awal dari 3.0.0 sedang dalam fase. end-of-support](https://docs.aws.amazon.com/sdkref/latest/guide/maint-policy.html#version-life-cycle)  
Anda dapat memperbarui dengan aman dari versi 2.0. *x* dan yang lebih baru ke versi terbaru AWS Encryption SDK tanpa kode atau perubahan data. Namun, [fitur keamanan baru](about-versions.md#version-2) diperkenalkan di versi 2.0. *x* tidak kompatibel ke belakang. Untuk memperbarui dari versi lebih awal dari 1.7. *x* ke versi 2.0. *x* dan yang lebih baru, Anda harus terlebih dahulu memperbarui ke yang terbaru 1. *x* versi AWS Encryption SDK. Lihat perinciannya di [Migrasi Anda AWS Encryption SDK](migration.md).

Gunakan `pip` untuk menginstal AWS Encryption SDK for Python, seperti yang ditunjukkan dalam contoh berikut.

**Pasang versi terbaru**  

```
pip install "aws-encryption-sdk[MPL]"
```
`[MPL]`Akhiran menginstal [Perpustakaan Penyedia Materi AWS Kriptografi](https://github.com/aws/aws-cryptographic-material-providers-library) (MPL). MPL berisi konstruksi untuk mengenkripsi dan mendekripsi data Anda. MPL adalah dependensi opsional untuk AWS Encryption SDK for Python diperkenalkan di versi 4. *x*. Kami sangat merekomendasikan menginstal MPL. Namun, jika Anda tidak berniat menggunakan MPL, Anda dapat menghilangkan akhiran. `[MPL]`

Untuk detail selengkapnya tentang penggunaan pip untuk menginstal dan memutakhirkan paket, lihat [Menginstal Paket](https://packaging.python.org/tutorials/installing-packages/).

 AWS Encryption SDK for Python Membutuhkan [perpustakaan kriptografi](https://cryptography.io/en/latest/) (pyca/kriptografi) di semua platform. Semua versi menginstal dan membangun `cryptography` perpustakaan `pip` secara otomatis di Windows. `pip`8.1 dan yang lebih baru secara otomatis menginstal dan membangun `cryptography` di Linux. Jika Anda menggunakan versi sebelumnya `pip` dan lingkungan Linux Anda tidak memiliki alat yang diperlukan untuk membangun `cryptography` perpustakaan, Anda perlu menginstalnya. Untuk informasi selengkapnya, lihat [Membangun Kriptografi di Linux](https://cryptography.io/en/latest/installation.html#building-cryptography-on-linux).

Versi 1.10.0 dan 2.5.0 dari AWS Encryption SDK for Python pin ketergantungan [kriptografi](https://cryptography.io/en/latest/) antara 2.5.0 dan 3.3.2. Versi lain dari AWS Encryption SDK for Python menginstal versi terbaru kriptografi. Jika Anda memerlukan versi kriptografi lebih lambat dari 3.3.2, kami sarankan Anda menggunakan versi utama terbaru dari. AWS Encryption SDK for Python

Untuk versi pengembangan terbaru AWS Encryption SDK for Python, buka [aws-encryption-sdk-python](https://github.com/aws/aws-encryption-sdk-python/)repositori di. GitHub

Setelah Anda menginstal AWS Encryption SDK for Python, mulailah dengan melihat [kode contoh Python dalam panduan](python-example-code.md) ini.

# AWS Encryption SDK for Python kode contoh
<a name="python-example-code"></a>

Contoh berikut menunjukkan cara menggunakan untuk mengenkripsi dan AWS Encryption SDK for Python mendekripsi data.

Contoh di bagian ini menunjukkan cara menggunakan versi 4. *x* dari AWS Encryption SDK for Python dengan ketergantungan [Perpustakaan Penyedia Materi Kriptografi](https://github.com/aws/aws-cryptographic-material-providers-library) opsional ()`aws-cryptographic-material-providers`. Untuk melihat contoh yang menggunakan versi sebelumnya, atau penginstalan tanpa pustaka penyedia materi (MPL), temukan rilis Anda di daftar [Rilis [aws-encryption-sdk-python](https://github.com/aws/aws-encryption-sdk-python/)](https://github.com/aws/aws-encryption-sdk-python/releases)repositori di. GitHub

Bila Anda menggunakan versi 4. *x* dari AWS Encryption SDK for Python dengan MPL, ia menggunakan [keyrings](choose-keyring.md) untuk melakukan enkripsi [amplop](concepts.md#envelope-encryption). AWS Encryption SDK Ini menyediakan gantungan kunci yang kompatibel dengan penyedia kunci utama yang Anda gunakan di versi sebelumnya. Untuk informasi selengkapnya, lihat [Kompatibilitas keyring](choose-keyring.md#keyring-compatibility). Untuk contoh tentang migrasi dari penyedia kunci utama ke keyrings, lihat [Contoh Migrasi](https://github.com/aws/aws-encryption-sdk-python/tree/master/examples/src/migration) di `aws-encryption-sdk-python` repositori pada; GitHub

**Topics**
+ [String](#python-example-strings)
+ [Aliran byte](#python-example-streams)

## Mengenkripsi dan mendekripsi string
<a name="python-example-strings"></a>

Contoh berikut menunjukkan cara menggunakan untuk mengenkripsi dan AWS Encryption SDK mendekripsi string. Contoh ini menggunakan [AWS KMS keyring](use-kms-keyring.md) dengan kunci KMS enkripsi simetris.

Contoh ini membuat instance AWS Encryption SDK klien dengan [kebijakan komitmen default](migrate-commitment-policy.md),. `REQUIRE_ENCRYPT_REQUIRE_DECRYPT` Untuk informasi selengkapnya, lihat [Menetapkan kebijakan komitmen Anda](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"
```

## Mengenkripsi dan mendekripsi aliran byte
<a name="python-example-streams"></a>

Contoh berikut menunjukkan cara menggunakan untuk mengenkripsi dan AWS Encryption SDK mendekripsi aliran byte. Contoh ini menggunakan [keyring Raw AES](use-raw-aes-keyring.md).

Contoh ini membuat instance AWS Encryption SDK klien dengan [kebijakan komitmen default](migrate-commitment-policy.md),. `REQUIRE_ENCRYPT_REQUIRE_DECRYPT` Lihat informasi yang lebih lengkap di [Menetapkan kebijakan komitmen Anda](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"
```