Charger un objet Télécharger un objet Autres options de calcul de la somme de contrôle

Protection de l'intégrité des données avec des checksums

Amazon Simple Storage Service (Amazon S3) permet de spécifier une somme de contrôle lorsque vous chargez un objet. Lorsque vous spécifiez une somme de contrôle, elle est stockée avec l'objet et peut être validée lors du téléchargement de l'objet.

Les checksums fournissent une couche supplémentaire d'intégrité des données lorsque vous transférez des fichiers. Avec les checksums, vous pouvez vérifier la cohérence des données en confirmant que le fichier reçu correspond au fichier d'origine. Pour plus d'informations sur les checksums avec Amazon S3, consultez le guide de l'utilisateur d'Amazon Simple Storage Service, y compris les algorithmes pris en charge.

Vous avez la possibilité de choisir l'algorithme qui répond le mieux à vos besoins et de laisser le SDK calculer le checksum. Vous pouvez également fournir une valeur de somme de contrôle précalculée à l'aide de l'un des algorithmes pris en charge.

Note

À partir de la version 2.30.0 du AWS SDK for Java 2.x, le SDK fournit des protections d'intégrité par défaut en calculant automatiquement une somme de CRC32 contrôle pour les téléchargements. Le SDK calcule cette somme de contrôle si vous ne fournissez pas de valeur de somme de contrôle précalculée ou si vous ne spécifiez pas d'algorithme que le SDK doit utiliser pour calculer une somme de contrôle.

Le SDK fournit également des paramètres globaux pour les protections de l'intégrité des données que vous pouvez définir en externe, que vous pouvez consulter dans le Guide de référence AWS SDKs et sur les outils.

Nous discutons des sommes de contrôle en deux phases de demande : le téléchargement d'un objet et le téléchargement d'un objet.

Charger un objet

Lorsque vous téléchargez un objet avec la putObject méthode et que vous fournissez un algorithme de somme de contrôle, le SDK calcule la somme de contrôle pour l'algorithme spécifié.

L'extrait de code suivant montre une demande de téléchargement d'un objet avec une SHA256 somme de contrôle. Lorsque le SDK envoie la demande, il calcule le SHA256 checksum et télécharge l'objet. Amazon S3 valide l'intégrité du contenu en calculant le checksum et en le comparant au checksum fourni par le SDK. Amazon S3 enregistre ensuite le checksum avec l'objet.


public void putObjectWithChecksum() {
        s3Client.putObject(b -> b
                .bucket(bucketName)
                .key(key)
                .checksumAlgorithm(ChecksumAlgorithm.SHA256),
            RequestBody.fromString("This is a test"));
}

Si vous ne fournissez pas d'algorithme de somme de contrôle avec la demande, le comportement de somme de contrôle varie en fonction de la version du SDK que vous utilisez, comme indiqué dans le tableau suivant.

Comportement de somme de contrôle lorsqu'aucun algorithme de somme de contrôle n'est fourni

Version du SDK Java	Comportement de Checksum
antérieur à 2.30.0	Le SDK ne calcule pas automatiquement une somme de contrôle basée sur le CRC et ne la fournit pas dans la demande.
2.30.0 ou version ultérieure	Le SDK utilise l'`CRC32`algorithme pour calculer le checksum et le fournit dans la demande. Amazon S3 valide l'intégrité du transfert en calculant sa propre somme de `CRC32` contrôle et en la comparant à la somme de contrôle fournie par le SDK. Si les sommes de contrôle correspondent, la somme de contrôle est enregistrée avec l'objet.

Utiliser une valeur de somme de contrôle précalculée

Une valeur de somme de contrôle précalculée fournie avec la demande désactive le calcul automatique par le SDK et utilise la valeur fournie à la place.

L'exemple suivant montre une demande avec une somme de SHA256 contrôle précalculée.


    public void putObjectWithPrecalculatedChecksum(String filePath) {
        String checksum = calculateChecksum(filePath, "SHA-256");

        s3Client.putObject((b -> b
                .bucket(bucketName)
                .key(key)
                .checksumSHA256(checksum)),
            RequestBody.fromFile(Paths.get(filePath)));
    }

Si Amazon S3 détermine que la valeur de la somme de contrôle est incorrecte pour l'algorithme spécifié, le service renvoie une réponse d'erreur.

Chargements partitionnés

Vous pouvez également utiliser des checksums pour les téléchargements partitionnés.

Le SDK pour Java 2.x propose deux options pour utiliser des checksums avec des téléchargements partitionnés. La première option utilise leS3TransferManager.

L'exemple de gestionnaire de transfert suivant indique l' SHA1 algorithme pour le téléchargement.


    public void multipartUploadWithChecksumTm(String filePath) {
        S3TransferManager transferManager = S3TransferManager.create();
        UploadFileRequest uploadFileRequest = UploadFileRequest.builder()
            .putObjectRequest(b -> b
                .bucket(bucketName)
                .key(key)
                .checksumAlgorithm(ChecksumAlgorithm.SHA1))
            .source(Paths.get(filePath))
            .build();
        FileUpload fileUpload = transferManager.uploadFile(uploadFileRequest);
        fileUpload.completionFuture().join();
        transferManager.close();
    }

Si vous ne fournissez pas d'algorithme de somme de contrôle lorsque vous utilisez le gestionnaire de transfert pour les téléchargements, le SDK calcule automatiquement la somme de contrôle en fonction de cet algorithme. CRC32 Le SDK effectue ce calcul pour toutes les versions du SDK.

La deuxième option utilise l'S3ClientAPI (ou l'S3AsyncClientAPI) pour effectuer le téléchargement partitionné. Si vous spécifiez une somme de contrôle avec cette approche, vous devez spécifier l'algorithme à utiliser lors du lancement du téléchargement. Vous devez également spécifier l'algorithme pour chaque demande d'article et fournir la somme de contrôle calculée pour chaque article après son chargement.


    public void multipartUploadWithChecksumS3Client(String filePath) {
        ChecksumAlgorithm algorithm = ChecksumAlgorithm.CRC32;

        // Initiate the multipart upload.
        CreateMultipartUploadResponse createMultipartUploadResponse = s3Client.createMultipartUpload(b -> b
            .bucket(bucketName)
            .key(key)
            .checksumAlgorithm(algorithm)); // Checksum specified on initiation.
        String uploadId = createMultipartUploadResponse.uploadId();

        // Upload the parts of the file.
        int partNumber = 1;
        List<CompletedPart> completedParts = new ArrayList<>();
        ByteBuffer bb = ByteBuffer.allocate(1024 * 1024 * 5); // 5 MB byte buffer

        try (RandomAccessFile file = new RandomAccessFile(filePath, "r")) {
            long fileSize = file.length();
            long position = 0;
            while (position < fileSize) {
                file.seek(position);
                long read = file.getChannel().read(bb);

                bb.flip(); // Swap position and limit before reading from the buffer.
                UploadPartRequest uploadPartRequest = UploadPartRequest.builder()
                    .bucket(bucketName)
                    .key(key)
                    .uploadId(uploadId)
                    .checksumAlgorithm(algorithm) // Checksum specified on each part.
                    .partNumber(partNumber)
                    .build();

                UploadPartResponse partResponse = s3Client.uploadPart(
                    uploadPartRequest,
                    RequestBody.fromByteBuffer(bb));

                CompletedPart part = CompletedPart.builder()
                    .partNumber(partNumber)
                    .checksumCRC32(partResponse.checksumCRC32()) // Provide the calculated checksum.
                    .eTag(partResponse.eTag())
                    .build();
                completedParts.add(part);

                bb.clear();
                position += read;
                partNumber++;
            }
        } catch (IOException e) {
            System.err.println(e.getMessage());
        }

        // Complete the multipart upload.
        s3Client.completeMultipartUpload(b -> b
            .bucket(bucketName)
            .key(key)
            .uploadId(uploadId)
            .multipartUpload(CompletedMultipartUpload.builder().parts(completedParts).build()));
    }

Le code des exemples complets et des tests se trouve dans le référentiel d'exemples de GitHub code.

Télécharger un objet

Lorsque vous utilisez la méthode GetObject pour télécharger un objet, le SDK valide automatiquement la somme de contrôle la valeur de la clé est. ChecksumMode enabled lorsque la checksumMode méthode du générateur pour le GetObjectRequest est définie surChecksumMode.ENABLED.

La demande contenue dans l'extrait suivant demande au SDK de valider la somme de contrôle dans la réponse en calculant la somme de contrôle et en comparant les valeurs.


    public GetObjectResponse getObjectWithChecksum() {
        return s3Client.getObject(b -> b
                        .bucket(bucketName)
                        .key(key)
                        .checksumMode(ChecksumMode.ENABLED))
                .response();
    }

Note

Si l'objet n'a pas été chargé avec une somme de contrôle, aucune validation n'a lieu.

Autres options de calcul de la somme de contrôle

Note

Pour vérifier l'intégrité des données transmises et identifier toute erreur de transmission, nous encourageons les utilisateurs à conserver les paramètres par défaut du SDK pour les options de calcul de la somme de contrôle. Par défaut, le SDK ajoute cette vérification importante pour de nombreuses opérations S3, notamment PutObject etGetObject.

Toutefois, si votre utilisation d'Amazon S3 nécessite une validation minimale par somme de contrôle, vous pouvez désactiver de nombreux contrôles en modifiant les paramètres de configuration par défaut.

Désactiver le calcul automatique de la somme de contrôle sauf si cela est nécessaire

Vous pouvez désactiver le calcul automatique de la somme de contrôle par le SDK pour les opérations qui le prennent en charge, par exemple PutObject et. GetObject Certaines opérations S3 nécessitent toutefois un calcul de somme de contrôle ; vous ne pouvez pas désactiver le calcul de somme de contrôle pour ces opérations.

Le SDK fournit des paramètres distincts pour le calcul d'une somme de contrôle pour la charge utile d'une demande et pour la charge utile d'une réponse.

La liste suivante décrit les paramètres que vous pouvez utiliser pour minimiser les calculs de somme de contrôle dans les différentes étendues.

Champ d'application de toutes les applications : en modifiant les paramètres des variables d'environnement ou d'un profil dans AWS config les credentials fichiers partagés, toutes les applications peuvent utiliser ces paramètres. Ces paramètres affectent tous les clients de service dans toutes les applications du AWS SDK, sauf s'ils sont remplacés au niveau de l'application ou du client de service.
- Ajoutez les paramètres dans un profil :
```
[default]
request_checksum_calculation = WHEN_REQUIRED
response_checksum_validation = WHEN_REQUIRED
```
- Ajoutez des variables d'environnement :
```
AWS_REQUEST_CHECKSUM_CALCULATION=WHEN_REQUIRED
AWS_RESPONSE_CHECKSUM_VALIDATION=WHEN_REQUIRED
```

Champ d'application actuel : vous pouvez définir la propriété système Java sur pour limiter le aws.requestChecksumCalculation calcul WHEN_REQUIRED de la somme de contrôle. La propriété système correspondante pour les réponses estaws.responseChecksumValidation.

Ces paramètres affectent tous les clients du service SDK de l'application, sauf s'ils sont remplacés lors de la création du client de service.

Définissez la propriété du système au début de votre application :


import software.amazon.awssdk.core.SdkSystemSetting;
import software.amazon.awssdk.core.checksums.RequestChecksumCalculation;
import software.amazon.awssdk.core.checksums.ResponseChecksumValidation;
import software.amazon.awssdk.services.s3.S3Client;

class DemoClass {
    public static void main(String[] args) {

        System.setProperty(SdkSystemSetting.AWS_REQUEST_CHECKSUM_CALCULATION.property(), // Resolves to "aws.requestChecksumCalculation".
                "WHEN_REQUIRED");
        System.setProperty(SdkSystemSetting.AWS_RESPONSE_CHECKSUM_VALIDATION.property(), // Resolves to "aws.responseChecksumValidation".
                "WHEN_REQUIRED");

        S3Client s3Client = S3Client.builder().build();

        // Use s3Client.
    }
}

Champ d'application du client de service S3 unique : vous pouvez configurer un seul client de service S3 pour calculer le montant minimum de checksums à l'aide des méthodes de création :


import software.amazon.awssdk.core.checksums.RequestChecksumCalculation;
import software.amazon.awssdk.services.s3.S3Client;

public class RequiredChecksums {
    public static void main(String[] args) {
        S3Client s3 = S3Client.builder()
                .requestChecksumCalculation(RequestChecksumCalculation.WHEN_REQUIRED)
                .responseChecksumValidation(ResponseChecksumValidation.WHEN_REQUIRED)
                .build();

        // Use s3Client. 
    }
// ...
}

Utilisez le `LegacyMd5Plugin` pour une MD5 compatibilité simplifiée

Parallèlement à la publication du comportement des CRC32 checksum avec la version 2.30.0, le SDK a cessé de calculer les MD5 checksums pour les opérations requises.

Si vous avez besoin d'un ancien comportement de MD5 somme de contrôle pour les opérations S3, vous pouvez utiliser leLegacyMd5Plugin, qui a été publié avec la version 2.31.32 du SDK.

Cela LegacyMd5Plugin est particulièrement utile lorsque vous devez maintenir la compatibilité avec des applications qui dépendent du comportement de MD5 somme de contrôle existant, en particulier lorsque vous travaillez avec des fournisseurs de stockage tiers compatibles S3, tels que ceux utilisés avec les connecteurs de système de fichiers S3A (Apache Spark, Iceberg).

Pour l'utiliserLegacyMd5Plugin, ajoutez-le à votre générateur de clients S3 :


// For synchronous S3 client.
S3Client s3Client = S3Client.builder()
                           .addPlugin(LegacyMd5Plugin.create())
                           .build();

// For asynchronous S3 client.
S3AsyncClient asyncClient = S3AsyncClient.builder()
                                       .addPlugin(LegacyMd5Plugin.create())
                                       .build();

Si vous souhaitez ajouter des sommes de MD5 contrôle aux opérations qui nécessitent des sommes de contrôle et que vous souhaitez éviter d'ajouter des sommes de contrôle par défaut du SDK pour les opérations qui prennent en charge les sommes de contrôle mais ne sont pas obligatoires, vous pouvez activer les options et comme. ClientBuilder requestChecksumCalculation responseChecksumValidation WHEN_REQUIRED Cela ajoutera les sommes de contrôle par défaut du SDK uniquement aux opérations nécessitant des sommes de contrôle :


// Use the `LegacyMd5Plugin` with `requestChecksumCalculation` and `responseChecksumValidation` set to WHEN_REQUIRED.
S3AsyncClient asyncClient = S3AsyncClient.builder()
                                       .addPlugin(LegacyMd5Plugin.create())
                                       .requestChecksumCalculation(RequestChecksumCalculation.WHEN_REQUIRED)
                                       .responseChecksumValidation(ResponseChecksumValidation.WHEN_REQUIRED)
                                       .build();

Cette configuration est particulièrement utile lorsque vous travaillez avec des systèmes de stockage tiers compatibles S3 qui ne prennent peut-être pas entièrement en charge les nouveaux algorithmes de somme de contrôle, mais qui nécessitent tout de même des MD5 sommes de contrôle pour certaines opérations.

Avertissement JavaScript est désactivé ou n'est pas disponible dans votre navigateur.

Pour que vous puissiez utiliser la documentation AWS, Javascript doit être activé. Vous trouverez des instructions sur les pages d'aide de votre navigateur.

Conventions de rédaction

Accès interrégional

Utilisez un client S3 performant

Protection de l'intégrité des données avec des checksums

Note

Charger un objet

Utiliser une valeur de somme de contrôle précalculée

Chargements partitionnés

Télécharger un objet

Note

Autres options de calcul de la somme de contrôle

Note

Désactiver le calcul automatique de la somme de contrôle sauf si cela est nécessaire

Utilisez le LegacyMd5Plugin pour une MD5 compatibilité simplifiée

Utilisez le `LegacyMd5Plugin` pour une MD5 compatibilité simplifiée