Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà.

Migrazione del client di crittografia Amazon S3 (da V2 a V3) nella versione 3 AWS SDK per PHP

Questo argomento mostra come migrare le applicazioni dalla versione 2 (V2) del client di crittografia Amazon Simple Storage Service (Amazon S3) alla versione 3 (V3) e garantire la disponibilità delle applicazioni durante tutto il processo di migrazione. La versione 3 introduce AES GCM con Key Commitment and Commitment Policies per migliorare la sicurezza e proteggere dalla manomissione delle chiavi di dati.

Panoramica sulla migrazione

Questa migrazione avviene in due fasi:

1. Aggiorna i client esistenti per leggere nuovi formati. Innanzitutto, distribuisci una versione aggiornata di nella AWS SDK per PHP tua applicazione. Ciò consente ai client di crittografia V2 esistenti di decrittografare gli oggetti scritti dai nuovi client V3. Se l'applicazione ne utilizza più AWS SDKs, è necessario aggiornare ogni SDK separatamente.

2. Migra i client di crittografia e decrittografia alla V3. Una volta che tutti i client di crittografia V2 saranno in grado di leggere nuovi formati, sarà possibile migrare i client di crittografia e decrittografia esistenti alle rispettive versioni V3.

Comprensione dei concetti della V3

La versione 3 del client di crittografia Amazon S3 introduce due miglioramenti chiave della sicurezza: Commitment Policies e l'algoritmo AES GCM with Key Commitment. La comprensione di questi concetti è essenziale per una migrazione di successo.

Politica di impegno

Una politica di impegno controlla il modo in cui il client di crittografia gestisce l'impegno delle chiavi durante le operazioni di crittografia e decrittografia. La versione 3 offre tre opzioni politiche:

AES GCM con Key Commitment

L'algoritmo AES GCM with Key Commitment (ALG_AES_256_GCM_HKDF_SHA512_COMMIT_KEY) è un nuovo algoritmo di crittografia introdotto nella V3 che fornisce protezione dagli attacchi di manomissione delle chiavi di dati.

Miglioramento della sicurezza: ALG_AES_256_GCM_HKDF_SHA512_COMMIT_KEY protegge dalla manomissione delle chiavi di dati associando crittograficamente la chiave dati al contenuto crittografato. Ciò impedisce agli aggressori di sostituire una chiave dati diversa durante la decrittografia, il che potrebbe portare alla decrittografia di dati non intenzionali.

Compatibilità delle versioni: gli oggetti crittografati con ALG_AES_256_GCM_HKDF_SHA512_COMMIT_KEY possono essere decrittografati solo da V3 e dalle ultime implementazioni V2 del client di crittografia Amazon S3. I client V1 non possono decrittografare gli oggetti crittografati con questo algoritmo.

Aggiorna i client esistenti per leggere nuovi formati

Il client di crittografia V3 utilizza algoritmi di crittografia e funzionalità di impegno chiave che le versioni precedenti del client non supportano. Il primo passo della migrazione consiste nell'aggiornare i client di decrittografia V2 all'ultima versione dell'SDK. Dopo aver completato questo passaggio, i client V2 dell'applicazione saranno in grado di decrittografare gli oggetti crittografati dai client di crittografia V3. Vedi i dettagli di seguito per ogni metodo di installazione di. AWS SDK per PHP

Creazione e installazione della versione SDK più recente

Per completare questa migrazione, è necessario utilizzare la versione più recente del aws/aws-sdk-php pacchetto che include il supporto del client di crittografia V3.

Installazione da Composer

Per i progetti che sono stati installati utilizzando Composer, nel file Composer, aggiorna il pacchetto SDK alla versione più recente dell'SDK, quindi esegui il comando seguente.

composer update aws/aws-sdk-php

Installazione mediante il file Phar o Zip

Utilizzare uno dei seguenti metodi. Assicurati di inserire il file SDK aggiornato nella posizione richiesta dal codice, determinata dall'istruzione require.

Per i progetti che sono stati installati utilizzando il file Phar, scaricate il file aggiornato:. aws.phar

<?php
  require '/path/to/aws.phar';
?>

Per i progetti che sono stati installati utilizzando il file Zip, scarica il file aggiornato: .

<?php
  require '/path/to/aws-autoloader.php';
?>

Creazione, installazione e distribuzione di applicazioni

Dopo aver aggiornato l'SDK, ricostruisci e ridistribuisci l'applicazione per assicurarti che tutti i componenti utilizzino la versione aggiornata. Questo passaggio è fondamentale per garantire che i client V2 possano leggere gli oggetti crittografati dai client V3.

Segui le procedure di distribuzione standard della tua organizzazione per implementare l'applicazione aggiornata. Assicurati che tutte le istanze dell'applicazione siano aggiornate prima di procedere alla migrazione dei client di crittografia e decrittografia alla V3.

Dopo la distribuzione, verificate che l'applicazione sia ancora in grado di decrittografare gli oggetti esistenti e che non si verifichino errori durante le normali operazioni. Ciò conferma che l'aggiornamento dell'SDK ha avuto esito positivo e che l'applicazione è pronta per la fase successiva della migrazione.

Migra i client di crittografia e decrittografia alla V3

Dopo aver aggiornato i client per leggere i nuovi formati di crittografia, è possibile aggiornare le applicazioni ai client di crittografia e decrittografia V3. Gli esempi seguenti mostrano come migrare correttamente il codice da V2 a V3.

Utilizzo dei client di crittografia V3

V3 introduce la S3EncryptionClientV3 classe e sostituisce gli KmsMaterialsProviderV3 equivalenti V2. Le differenze principali in V3 sono:

Esempio: migrazione da V2 a V3 con KMS Encryption

Premigrazione (V2)

use Aws\S3\Crypto\S3EncryptionClientV2;
use Aws\S3\S3Client;
use Aws\Crypto\KmsMaterialsProviderV2;
use Aws\Kms\KmsClient;

$encryptionClient = new S3EncryptionClientV2(
   new S3Client([
      'profile' => 'default',
      'region' => 'us-east-1',
      'version' => 'latest',
   ])
);

$kmsKeyId = 'kms-key-id';
$materialsProvider = new KmsMaterialsProviderV2(
   new KmsClient([
      'profile' => 'default',
      'region' => 'us-east-1',
      'version' => 'latest',
   ]),
   $kmsKeyId
);

$bucket = 'the-bucket-name';
$key = 'the-file-name';
$cipherOptions = [
   'Cipher' => 'gcm',
   'KeySize' => 256,
];

$encryptionClient->putObject([
   '@MaterialsProvider' => $materialsProvider,
   '@CipherOptions' => $cipherOptions,
   '@KmsEncryptionContext' => ['context-key' => 'context-value'],
   'Bucket' => $bucket,
   'Key' => $key,
   'Body' => fopen('file-to-encrypt.txt', 'r'),
]);

$result = $encryptionClient->getObject([
   '@KmsAllowDecryptWithAnyCmk' => true,
   '@SecurityProfile' => 'V2_AND_LEGACY',
   '@CommitmentPolicy' => 'FORBID_ENCRYPT_ALLOW_DECRYPT',
   '@MaterialsProvider' => $materialsProvider,
   '@CipherOptions' => $cipherOptions,
   'Bucket' => $bucket,
   'Key' => $key,
]);

Durante la migrazione (V3 con compatibilità con le versioni precedenti)

use Aws\S3\Crypto\S3EncryptionClientV3;
use Aws\S3\S3Client;
use Aws\Crypto\KmsMaterialsProviderV3;
use Aws\Kms\KmsClient;

// Create V3 encryption client
$encryptionClient = new S3EncryptionClientV3(
   new S3Client([
      'profile' => 'default',
      'region' => 'us-east-1',
      'version' => 'latest',
   ])
);

// Create encryption materials
$kmsKeyId = 'kms-key-id';
$materialsProvider = new KmsMaterialsProviderV3(
   new KmsClient([
      'profile' => 'default',
      'region' => 'us-east-1',
      'version' => 'latest',
   ]),
   $kmsKeyId
);

$bucket = 'the-bucket-name';
$key = 'the-file-name';
$cipherOptions = [
   'Cipher' => 'gcm',
   'KeySize' => 256,
];

$encryptionClient->putObject([
   '@MaterialsProvider' => $materialsProvider,
   '@CipherOptions' => $cipherOptions,
   '@CommitmentPolicy' => 'REQUIRE_ENCRYPT_ALLOW_DECRYPT',
   '@KmsEncryptionContext' => ['context-key' => 'context-value'],
   'Bucket' => $bucket,
   'Key' => $key,
   'Body' => fopen('file-to-encrypt.txt', 'r'),
]);

$result = $encryptionClient->getObject([
   '@SecurityProfile' => 'V3_AND_LEGACY',
   '@CommitmentPolicy' => 'REQUIRE_ENCRYPT_ALLOW_DECRYPT',
   '@MaterialsProvider' => $materialsProvider,
   '@CipherOptions' => $cipherOptions,
   'Bucket' => $bucket,
   'Key' => $key,
]);

Dopo la migrazione (V3 con impegno chiave)

use Aws\S3\Crypto\S3EncryptionClientV3;
use Aws\S3\S3Client;
use Aws\Crypto\KmsMaterialsProviderV3;
use Aws\Kms\KmsClient;
 
// Create V3 encryption client
$encryptionClient = new S3EncryptionClientV3(
   new S3Client([
      'profile' => 'default',
      'region' => 'us-east-1',
      'version' => 'latest',
   ])
);

// Create encryption materials
$kmsKeyId = 'kms-key-id';
$materialsProvider = new KmsMaterialsProviderV3(
   new KmsClient([
      'profile' => 'default',
      'region' => 'us-east-1',
      'version' => 'latest',
   ]),
   $kmsKeyId
);

$bucket = 'the-bucket-name';
$key = 'the-file-name';
$cipherOptions = [
   'Cipher' => 'gcm',
   'KeySize' => 256,
];

$encryptionClient->putObject([
   '@MaterialsProvider' => $materialsProvider,
   '@CipherOptions' => $cipherOptions,
   // Use the commitment policy (REQUIRE_ENCRYPT_REQUIRE_DECRYPT)
   // This encrypts with key commitment and does not decrypt V2 objects
   '@CommitmentPolicy' => 'REQUIRE_ENCRYPT_REQUIRE_DECRYPT',
   '@KmsEncryptionContext' => ['context-key' => 'context-value'],
   'Bucket' => $bucket,
   'Key' => $key,
   'Body' => fopen('file-to-encrypt.txt', 'r'),
]);

$result = $encryptionClient->getObject([
   '@SecurityProfile' => 'V3',
   // Use the commitment policy (REQUIRE_ENCRYPT_REQUIRE_DECRYPT)
   // This encrypts with key commitment and does not decrypt V2 objects
   '@CommitmentPolicy' => 'REQUIRE_ENCRYPT_REQUIRE_DECRYPT',
   '@MaterialsProvider' => $materialsProvider,
   '@CipherOptions' => $cipherOptions,
   'Bucket' => $bucket,
   'Key' => $key,
]);

Principali differenze nella versione V3:

Esempi aggiuntivi

Gli esempi seguenti illustrano le opzioni di configurazione aggiuntive disponibili in V3 che possono aiutarti a gestire il processo di migrazione e controllare il comportamento di crittografia.

Abilitazione del supporto legacy

Durante la migrazione, potrebbe essere necessario decrittografare gli oggetti che sono stati crittografati con la versione 1 o la versione 2 del client di crittografia Amazon S3. Il @SecurityProfile parametro controlla le versioni di crittografia che il client V3 può decrittografare.

Quando utilizzare questa configurazione: utilizza il profilo di 'V3_AND_LEGACY' sicurezza quando l'applicazione deve leggere oggetti crittografati dai client V1 o V2. Questo è comune durante il periodo di migrazione, quando nei bucket è presente una combinazione di oggetti crittografati vecchi e nuovi.

use Aws\S3\Crypto\S3EncryptionClientV3;
use Aws\S3\S3Client;
use Aws\Crypto\KmsMaterialsProviderV3;
use Aws\Kms\KmsClient;

$kmsKeyId = 'kms-key-id';
$materialsProvider = new KmsMaterialsProviderV3(
    new KmsClient([
        'profile' => 'default',
        'region' => 'us-east-1',
        'version' => 'latest',
    ]),
    $kmsKeyId
);

$encryptionClient = new S3EncryptionClientV3(
    new S3Client([
        'profile' => 'default',
        'region' => 'us-east-1',
        'version' => 'latest',
    ])
);

$bucket = 'the-bucket-name';
$key = 'the-file-name';
$cipherOptions = [
    'Cipher' => 'gcm',
    'KeySize' => 256,
];

// Decrypt objects encrypted with V1, V2, or V3
$result = $encryptionClient->getObject([
    '@SecurityProfile' => 'V3_AND_LEGACY',
    '@CommitmentPolicy' => 'REQUIRE_ENCRYPT_ALLOW_DECRYPT',
    '@MaterialsProvider' => $materialsProvider,
    '@CipherOptions' => $cipherOptions,
    'Bucket' => $bucket,
    'Key' => $key,
]);

Il parametro @SecurityProfile accetta i seguenti valori:

Configurazione del metodo di archiviazione

Il client di crittografia Amazon S3 può archiviare i metadati di crittografia in due modi: nelle intestazioni dei metadati dell'oggetto o in un file di istruzioni separato. Il @MetadataStrategy parametro controlla il metodo di archiviazione utilizzato.

Quando utilizzare questa configurazione: utilizzala 'INSTRUCTION_FILE' quando è necessario conservare i metadati dell'oggetto originale o quando si lavora con oggetti con vincoli di dimensione dei metadati. Utilizza 'METADATA' (impostazione predefinita) per implementazioni più semplici in cui i metadati di crittografia possono essere archiviati insieme all'oggetto.

use Aws\S3\Crypto\S3EncryptionClientV3;
use Aws\S3\S3Client;
use Aws\Crypto\KmsMaterialsProviderV3;
use Aws\Kms\KmsClient;

$kmsKeyId = 'kms-key-id';
$materialsProvider = new KmsMaterialsProviderV3(
    new KmsClient([
        'profile' => 'default',
        'region' => 'us-east-1',
        'version' => 'latest',
    ]),
    $kmsKeyId
);

$encryptionClient = new S3EncryptionClientV3(
    new S3Client([
        'profile' => 'default',
        'region' => 'us-east-1',
        'version' => 'latest',
    ])
);

$bucket = 'the-bucket-name';
$key = 'the-file-name';
$cipherOptions = [
    'Cipher' => 'gcm',
    'KeySize' => 256,
];

// Store encryption metadata in a separate instruction file
$encryptionClient->putObject([
    '@MaterialsProvider' => $materialsProvider,
    '@CipherOptions' => $cipherOptions,
    '@CommitmentPolicy' => 'REQUIRE_ENCRYPT_REQUIRE_DECRYPT',
    '@MetadataStrategy' => 'INSTRUCTION_FILE',
    '@KmsEncryptionContext' => ['context-key' => 'context-value'],
    'Bucket' => $bucket,
    'Key' => $key,
    'Body' => fopen('file-to-encrypt.txt', 'r'),
]);

// Store encryption metadata in object headers (default)
$encryptionClient->putObject([
    '@MaterialsProvider' => $materialsProvider,
    '@CipherOptions' => $cipherOptions,
    '@CommitmentPolicy' => 'REQUIRE_ENCRYPT_REQUIRE_DECRYPT',
    '@MetadataStrategy' => 'METADATA',
    '@KmsEncryptionContext' => ['context-key' => 'context-value'],
    'Bucket' => $bucket,
    'Key' => $key,
    'Body' => fopen('file-to-encrypt.txt', 'r'),
]);

Il parametro @MetadataStrategy accetta i seguenti valori: