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) nel AWS SDK per PHP Versione 3

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 dell' AWS SDK per PHP applicazione. Ciò consente ai client di crittografia V2 esistenti di decrittografare gli oggetti scritti dai nuovi client V3. Se l'applicazione utilizza più AWS SDK, è necessario aggiornare ciascun SDK separatamente.

2. Esegui la migrazione dei client di crittografia e decrittografia alla V3. Una volta che tutti i client di crittografia V2 sono in grado di leggere i nuovi formati, è possibile migrare i client di crittografia e decrittografia esistenti alle rispettive versioni V3.

Comprensione dei concetti di V3

La versione 3 del client di crittografia Amazon S3 introduce due principali miglioramenti 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 della chiave di dati legando crittograficamente la chiave dati al contenuto crittografato. Ciò impedisce agli aggressori di sostituire una chiave di 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 dalla V3 e dalle più recenti implementazioni V2 del client di crittografia Amazon S3. I client V1 non possono decrittografare 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 passaggio della migrazione consiste nell'aggiornare i client di decrittografia V2 all'ultima versione 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 per i client di crittografia V3.

Installazione da Composer

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

composer update aws/aws-sdk-php

Installazione utilizzando 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 installati utilizzando il file Phar, scarica il file aggiornato:. aws.phar

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

Per i progetti 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 è andato a buon fine e che l'applicazione è pronta per la fase successiva della migrazione.

Esegui la migrazione dei 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 dalla V2 alla V3.

Utilizzo dei client di crittografia V3

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

Esempio: migrazione da V2 a V3 con crittografia KMS

Pre-migration (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,
]);

Post-migration (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,
]);

Differenze chiave in 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 crittografati con la versione V1 o V2 del client di crittografia Amazon S3. Il @SecurityProfile parametro controlla quali versioni di crittografia il tuo 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 hai un mix di vecchi e nuovi oggetti crittografati nei tuoi bucket.

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 usare questa configurazione: da utilizzare 'INSTRUCTION_FILE' quando è necessario conservare i metadati dell'oggetto originale o quando si lavora con oggetti con vincoli di dimensione dei metadati. Usa 'METADATA' (impostazione predefinita) per distribuzioni 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: