Die vorliegende Übersetzung wurde maschinell erstellt. Im Falle eines Konflikts oder eines Widerspruchs zwischen dieser übersetzten Fassung und der englischen Fassung (einschließlich infolge von Verzögerungen bei der Übersetzung) ist die englische Fassung maßgeblich.

Migration des Amazon S3-Verschlüsselungsclients (V2 auf V3) im AWS SDK für PHP Version 3

In diesem Thema wird gezeigt, wie Sie Ihre Anwendungen von Version 2 (V2) des Amazon Simple Storage Service (Amazon S3) -Verschlüsselungsclients auf Version 3 (V3) migrieren und die Anwendungsverfügbarkeit während des gesamten Migrationsprozesses sicherstellen. Version 3 führt AES GCM mit Key Commitment und Commitment Policies ein, um die Sicherheit zu erhöhen und vor Manipulation von Datenschlüsseln zu schützen.

Überblick über die Migration

Diese Migration erfolgt in zwei Phasen:

1. Aktualisieren Sie bestehende Clients, damit sie neue Formate lesen können. Stellen Sie zunächst eine aktualisierte Version von AWS SDK für PHP in Ihrer Anwendung bereit. Auf diese Weise können bestehende V2-Verschlüsselungsclients Objekte entschlüsseln, die von den neuen V3-Clients geschrieben wurden. Wenn Ihre Anwendung mehrere AWS SDKs verwendet, müssen Sie jedes SDK separat aktualisieren.

2. Migrieren Sie die Verschlüsselungs- und Entschlüsselungsclients auf Version 3. Sobald alle Ihre V2-Verschlüsselungsclients neue Formate lesen können, können Sie Ihre vorhandenen Verschlüsselungs- und Entschlüsselungsclients auf ihre jeweiligen V3-Versionen migrieren.

V3-Konzepte verstehen

Version 3 des Amazon S3-Verschlüsselungsclients führt zwei wichtige Sicherheitsverbesserungen ein: Commitment Policies und den AES-GCM mit Key Commitment-Algorithmus. Das Verständnis dieser Konzepte ist für eine erfolgreiche Migration unerlässlich.

Politik des Engagements

Eine Verpflichtungsrichtlinie steuert, wie der Verschlüsselungsclient bei Verschlüsselungs- und Entschlüsselungsvorgängen mit der Schlüsselbindung umgeht. Version 3 bietet drei Richtlinienoptionen:

AES GCM mit Key Commitment

Der AES-GCM mit Key Commitment (ALG_AES_256_GCM_HKDF_SHA512_COMMIT_KEY) -Algorithmus ist ein neuer Verschlüsselungsalgorithmus, der in Version 3 eingeführt wurde und Schutz vor Angriffen mit der Manipulation von Datenschlüsseln bietet.

Sicherheitsverbesserung: ALG_AES_256_GCM_HKDF_SHA512_COMMIT_KEY Schützt vor Manipulation von Datenschlüsseln, indem der Datenschlüssel kryptografisch an den verschlüsselten Inhalt gebunden wird. Dadurch wird verhindert, dass Angreifer bei der Entschlüsselung einen anderen Datenschlüssel verwenden, was zur Entschlüsselung unbeabsichtigter Daten führen könnte.

Versionskompatibilität: Mit verschlüsselte Objekte ALG_AES_256_GCM_HKDF_SHA512_COMMIT_KEY können nur mit Version 3 und den neuesten V2-Implementierungen des Amazon S3-Verschlüsselungsclients entschlüsselt werden. V1-Clients können mit diesem Algorithmus verschlüsselte Objekte nicht entschlüsseln.

Aktualisieren Sie bestehende Clients so, dass sie neue Formate lesen

Der V3-Verschlüsselungsclient verwendet Verschlüsselungsalgorithmen und wichtige Commitment-Funktionen, die ältere Versionen des Clients nicht unterstützen. Der erste Schritt der Migration besteht darin, Ihre V2-Entschlüsselungsclients auf die neueste SDK-Version zu aktualisieren. Nach Abschluss dieses Schritts können die V2-Clients Ihrer Anwendung Objekte entschlüsseln, die mit V3-Verschlüsselungsclients verschlüsselt wurden. Im Folgenden finden Sie Einzelheiten zu den einzelnen Installationsmethoden von. AWS SDK für PHP

Erstellen und Installieren der neuesten SDK-Version

Um diese Migration abzuschließen, müssen Sie die neueste Version des aws/aws-sdk-php Pakets verwenden, das die Unterstützung des V3-Verschlüsselungsclients enthält.

Installation über Composer

Aktualisieren Sie für Projekte, die mit Composer installiert wurden, in der Composer-Datei das SDK-Paket auf die neueste Version des SDK und führen Sie dann den folgenden Befehl aus.

composer update aws/aws-sdk-php

Installation mithilfe der Phar- oder Zip-Datei

Verwenden Sie eine der folgenden Methoden: Stellen Sie sicher, dass Sie die aktualisierte SDK-Datei an dem Ort platzieren, der für Ihren Code erforderlich ist. Dieser wird in der Requre-Anweisung festgelegt.

Laden Sie für Projekte, die mithilfe der Phar-Datei installiert wurden, die aktualisierte Datei herunter: aws.phar.

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

Laden Sie für Projekte, die mithilfe der Zip-Datei installiert wurden, die aktualisierte Datei herunter: .

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

Anwendungen erstellen, installieren und bereitstellen

Nachdem Sie das SDK aktualisiert haben, erstellen Sie Ihre Anwendung neu und stellen Sie sie erneut bereit, um sicherzustellen, dass alle Komponenten die aktualisierte Version verwenden. Dieser Schritt ist wichtig, um sicherzustellen, dass Ihre V2-Clients Objekte lesen können, die von V3-Clients verschlüsselt wurden.

Folgen Sie den standardmäßigen Bereitstellungsverfahren Ihres Unternehmens, um die aktualisierte Anwendung bereitzustellen. Stellen Sie sicher, dass alle Instanzen Ihrer Anwendung aktualisiert sind, bevor Sie mit der Migration Ihrer Verschlüsselungs- und Entschlüsselungsclients auf Version 3 fortfahren.

Stellen Sie nach der Bereitstellung sicher, dass Ihre Anwendung immer noch vorhandene Objekte entschlüsseln kann und dass während des normalen Betriebs keine Fehler auftreten. Dies bestätigt, dass das SDK-Update erfolgreich war und Ihre Anwendung für die nächste Phase der Migration bereit ist.

Migrieren Sie Verschlüsselungs- und Entschlüsselungsclients auf Version 3

Nachdem Sie Ihre Clients auf die neuen Verschlüsselungsformate aktualisiert haben, können Sie Ihre Anwendungen auf die V3-Verschlüsselungs- und Entschlüsselungsclients aktualisieren. Die folgenden Beispiele zeigen Ihnen, wie Sie Ihren Code erfolgreich von V2 auf V3 migrieren.

Verwenden von V3 Encryption Clients

V3 führt die S3EncryptionClientV3 Klasse ein und ersetzt KmsMaterialsProviderV3 die V2-Äquivalente. Die wichtigsten Unterschiede in V3 sind:

Beispiel: Migration von V2 auf V3 mit KMS-Verschlüsselung

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

Während der Migration (V3 mit Abwärtskompatibilität)

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 mit wichtiger Verpflichtung)

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

Die wichtigsten Unterschiede in V3:

Weitere Beispiele

Die folgenden Beispiele zeigen zusätzliche Konfigurationsoptionen, die in Version 3 verfügbar sind und Ihnen helfen können, den Migrationsprozess zu verwalten und das Verschlüsselungsverhalten zu kontrollieren.

Aktivieren des Legacy-System--Supports

Während der Migration müssen Sie möglicherweise Objekte entschlüsseln, die mit V1 oder V2 des Amazon S3-Verschlüsselungsclients verschlüsselt wurden. Der @SecurityProfile Parameter steuert, welche Verschlüsselungsversionen Ihr V3-Client entschlüsseln kann.

Wann Sie diese Konfiguration verwenden sollten: Verwenden Sie das 'V3_AND_LEGACY' Sicherheitsprofil, wenn Ihre Anwendung Objekte lesen muss, die von V1- oder V2-Clients verschlüsselt wurden. Dies ist häufig während der Migrationsphase der Fall, wenn Sie eine Mischung aus alten und neuen verschlüsselten Objekten in Ihren Buckets haben.

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

Der Parameter @SecurityProfile akzeptiert die folgenden Werte:

Speichermethode konfigurieren

Der Amazon S3-Verschlüsselungsclient kann Verschlüsselungsmetadaten auf zwei Arten speichern: in den Metadaten-Headern des Objekts oder in einer separaten Anweisungsdatei. Der @MetadataStrategy Parameter steuert, welche Speichermethode verwendet wird.

Wann Sie diese Konfiguration verwenden sollten: Verwenden Sie 'INSTRUCTION_FILE' sie, wenn Sie die ursprünglichen Objektmetadaten beibehalten müssen oder wenn Sie mit Objekten arbeiten, für die Metadatengrößenbeschränkungen gelten. Verwenden Sie 'METADATA' (die Standardeinstellung) für einfachere Bereitstellungen, bei denen Verschlüsselungsmetadaten zusammen mit dem Objekt gespeichert werden können.

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'),
]);

Der Parameter @MetadataStrategy akzeptiert die folgenden Werte: