Perlindungan integritas data dengan checksum - AWS SDK for Java 2.x
Mengunggah objekUnduh objekOpsi perhitungan checksum lainnya

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

Perlindungan integritas data dengan checksum

Amazon Simple Storage Service (Amazon S3) menyediakan kemampuan untuk menentukan checksum saat Anda mengunggah objek. Ketika Anda menentukan checksum, itu disimpan dengan objek dan dapat divalidasi ketika objek diunduh.

Checksum menyediakan lapisan integritas data tambahan saat Anda mentransfer file. Dengan checksum, Anda dapat memverifikasi konsistensi data dengan mengonfirmasi bahwa file yang diterima cocok dengan file asli. Untuk informasi selengkapnya tentang checksum dengan Amazon S3, lihat Panduan Pengguna Layanan Penyimpanan Sederhana Amazon termasuk algoritme yang didukung.

Anda memiliki fleksibilitas untuk memilih algoritma yang paling sesuai dengan kebutuhan Anda dan membiarkan SDK menghitung checksum. Atau, Anda dapat memberikan nilai checksum yang telah dihitung sebelumnya dengan menggunakan salah satu algoritme yang didukung.

catatan

Dimulai dengan versi 2.30.0 AWS SDK for Java 2.x, SDK menyediakan perlindungan integritas default dengan menghitung checksum secara otomatis untuk unggahan. CRC32 SDK menghitung checksum ini jika Anda tidak memberikan nilai checksum yang telah dihitung sebelumnya atau jika Anda tidak menentukan algoritme yang harus digunakan SDK untuk menghitung checksum.

SDK juga menyediakan pengaturan global untuk perlindungan integritas data yang dapat Anda atur secara eksternal, yang dapat Anda baca di Panduan Referensi Alat AWS SDKs dan Alat.

Kami membahas checksum dalam dua fase permintaan: mengunggah objek dan mengunduh objek.

Mengunggah objek

Saat Anda mengunggah objek dengan putObject metode dan menyediakan algoritma checksum, SDK menghitung checksum untuk algoritme yang ditentukan.

Cuplikan kode berikut menunjukkan permintaan untuk mengunggah objek dengan checksum. SHA256 Ketika SDK mengirim permintaan, ia menghitung SHA256 checksum dan mengunggah objek. Amazon S3 memvalidasi integritas konten dengan menghitung checksum dan membandingkannya dengan checksum yang disediakan oleh SDK. Amazon S3 kemudian menyimpan checksum dengan objek.

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

Jika Anda tidak menyediakan algoritma checksum dengan permintaan, perilaku checksum bervariasi tergantung pada versi SDK yang Anda gunakan seperti yang ditunjukkan pada tabel berikut.

Perilaku checksum ketika tidak ada algoritma checksum yang disediakan

Versi Java SDK Perilaku checksum
lebih awal dari 2.30.0 SDK tidak secara otomatis menghitung checksum berbasis CRC dan menyediakannya dalam permintaan.
2.30.0 atau yang lebih baru

SDK menggunakan CRC32 algoritma untuk menghitung checksum dan menyediakannya dalam permintaan. Amazon S3 memvalidasi integritas transfer dengan menghitung checksumnya sendiri dan membandingkannya dengan CRC32 checksum yang disediakan oleh SDK. Jika checksum cocok, checksum disimpan dengan objek.

Gunakan nilai checksum yang telah dihitung sebelumnya

Nilai checksum yang telah dihitung sebelumnya yang disertakan dengan permintaan menonaktifkan komputasi otomatis oleh SDK dan menggunakan nilai yang disediakan sebagai gantinya.

Contoh berikut menunjukkan permintaan dengan SHA256 checksum yang telah dihitung sebelumnya.

    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)));
    }

Jika Amazon S3 menentukan nilai checksum salah untuk algoritme yang ditentukan, layanan akan mengembalikan respons kesalahan.

Unggahan multipart

Anda juga dapat menggunakan checksum dengan unggahan multipart.

SDK for Java 2.x menyediakan dua opsi untuk menggunakan checksum dengan unggahan multipart. Opsi pertama menggunakanS3TransferManager.

Contoh manajer transfer berikut menentukan SHA1 algoritma untuk upload.

    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();
    }

Jika Anda tidak menyediakan algoritma checksum saat menggunakan manajer transfer untuk upload, SDK secara otomatis menghitung dan checksum berdasarkan algoritma. CRC32 SDK melakukan perhitungan ini untuk semua versi SDK.

Opsi kedua menggunakan S3ClientAPI (atau S3AsyncClientAPI) untuk melakukan pengunggahan multibagian. Jika Anda menentukan checksum dengan pendekatan ini, Anda harus menentukan algoritma yang akan digunakan pada inisiasi unggahan. Anda juga harus menentukan algoritma untuk setiap permintaan bagian dan memberikan checksum yang dihitung untuk setiap bagian setelah diunggah.

    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()));
    }

Kode untuk contoh dan tes lengkap ada di repositori contoh GitHub kode.

Unduh objek

Saat Anda menggunakan metode getObject untuk mengunduh objek, SDK secara otomatis memvalidasi checksum nilai kuncinya. ChecksumMode enabled ketika checksumMode metode pembangun untuk GetObjectRequest diatur keChecksumMode.ENABLED.

Permintaan dalam cuplikan berikut mengarahkan SDK untuk memvalidasi checksum dalam respons dengan menghitung checksum dan membandingkan nilainya.

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

Jika objek tidak diunggah dengan checksum, tidak ada validasi yang terjadi.

Opsi perhitungan checksum lainnya

catatan

Untuk memverifikasi integritas data data yang ditransmisikan dan untuk mengidentifikasi kesalahan transmisi, kami mendorong pengguna untuk menjaga pengaturan default SDK untuk opsi perhitungan checksum. Secara default, SDK menambahkan pemeriksaan penting ini untuk banyak operasi S3 termasuk PutObject dan. GetObject

Namun, jika penggunaan Amazon S3 memerlukan validasi checksum minimal, Anda dapat menonaktifkan banyak pemeriksaan dengan mengubah pengaturan konfigurasi default.

Nonaktifkan perhitungan checksum otomatis kecuali diperlukan

Anda dapat menonaktifkan perhitungan checksum otomatis oleh SDK untuk operasi yang mendukungnya, misalnya PutObject dan. GetObject Beberapa operasi S3, bagaimanapun, memerlukan perhitungan checksum; Anda tidak dapat menonaktifkan perhitungan checksum untuk operasi ini.

SDK menyediakan pengaturan terpisah untuk perhitungan checksum untuk muatan permintaan dan untuk muatan respons.

Daftar berikut menjelaskan pengaturan yang dapat Anda gunakan untuk meminimalkan perhitungan checksum pada cakupan yang berbeda.

  • Semua ruang lingkup aplikasi —Dengan mengubah pengaturan dalam variabel lingkungan atau dalam profil di bersama AWS config dan credentials file, semua aplikasi dapat menggunakan pengaturan ini. Pengaturan ini memengaruhi semua klien layanan di semua aplikasi AWS SDK kecuali diganti pada cakupan klien aplikasi atau layanan.

    • Tambahkan pengaturan di profil:

      [default]
request_checksum_calculation = WHEN_REQUIRED
response_checksum_validation = WHEN_REQUIRED

    • Tambahkan variabel lingkungan:

      AWS_REQUEST_CHECKSUM_CALCULATION=WHEN_REQUIRED
AWS_RESPONSE_CHECKSUM_VALIDATION=WHEN_REQUIRED

  • Lingkup aplikasi saat ini —Anda dapat mengatur properti sistem Java aws.requestChecksumCalculation WHEN_REQUIRED untuk membatasi perhitungan checksum. Properti sistem yang sesuai untuk tanggapan adalahaws.responseChecksumValidation.

    Pengaturan ini memengaruhi semua klien layanan SDK dalam aplikasi kecuali diganti selama pembuatan klien layanan.

    Mengatur properti sistem di awal aplikasi Anda:

    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.
    }
}

  • Lingkup klien layanan S3 tunggal —Anda dapat mengonfigurasi satu klien layanan S3 untuk menghitung jumlah minimum checksum menggunakan metode pembangun:

    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. 
    }
// ...
}

Gunakan LegacyMd5Plugin untuk MD5 kompatibilitas yang disederhanakan

Seiring dengan rilis perilaku CRC32 checksum dengan versi 2.30.0, SDK berhenti menghitung MD5 checksum pada operasi yang diperlukan.

Jika Anda memerlukan perilaku MD5 checksum lama untuk operasi S3, Anda dapat menggunakanLegacyMd5Plugin, yang dirilis dengan SDK versi 2.31.32.

LegacyMd5PluginIni sangat berguna ketika Anda perlu mempertahankan kompatibilitas dengan aplikasi yang bergantung pada perilaku MD5 checksum lama, terutama ketika bekerja dengan penyedia penyimpanan pihak ketiga yang kompatibel dengan S3 seperti yang digunakan dengan konektor sistem file S3A (Apache Spark, Iceberg).

Untuk menggunakanLegacyMd5Plugin, tambahkan ke pembuat klien S3 Anda:

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

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

Jika Anda ingin menambahkan MD5 checksum ke operasi yang memerlukan checksum dan ingin melewatkan penambahan checksum default SDK untuk operasi yang mendukung checksum tetapi tidak diperlukan, Anda dapat mengaktifkan opsi dan as. ClientBuilder requestChecksumCalculation responseChecksumValidation WHEN_REQUIRED Ini akan menambahkan checksum default SDK hanya untuk operasi yang memerlukan checksum:

// 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();

Konfigurasi ini sangat berguna ketika bekerja dengan sistem penyimpanan pihak ketiga yang kompatibel dengan S3 yang mungkin tidak sepenuhnya mendukung algoritma checksum yang lebih baru tetapi masih memerlukan MD5 checksum untuk operasi tertentu.