Proteção da integridade de dados com somas de verificação - AWS SDK for Java 2.x
Fazer upload de um objetoFazer download de um objetoOutras opções de cálculo da soma de verificação

As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.

Proteção da integridade de dados com somas de verificação

O Amazon Simple Storage Service (Amazon S3) oferece a capacidade de especificar uma soma de verificação ao fazer upload de um objeto. Quando você especifica uma soma de verificação, ela é armazenada com o objeto e pode ser validada quando o objeto é baixado.

As somas de verificação fornecem uma camada adicional de integridade de dados quando você transfere arquivos. Com somas de verificação, você pode verificar a consistência de dados confirmando que o arquivo recebido corresponde ao arquivo original. Consulte mais informações sobre as somas de verificação no Amazon S3 no Guia do usuário do Amazon Simple Storage Service, incluindo os algoritmos compatíveis.

Você tem a flexibilidade de escolher o algoritmo mais adequado às suas necessidades e deixar que o SDK calcule a soma de verificação. Como alternativa, você pode fornecer um valor de soma de verificação pré-computado usando um dos algoritmos compatíveis.

nota

A partir da versão 2.30.0 do AWS SDK for Java 2.x, o SDK fornece proteções de integridade padrão calculando automaticamente uma soma de verificação CRC32 para uploads. O SDK fará o cálculo dessa soma de verificação se você não fornecer um valor correspondente pré-calculado ou se não especificar um algoritmo que o SDK deva usar para esse cálculo.

Ele também fornece configurações globais para proteções de integridade de dados que você pode definir externamente. Leia mais sobre elas no Guia de referência de SDKs e ferramentas da AWS.

Discutimos somas de verificação em duas fases de solicitação: upload de um objeto e download de um objeto.

Fazer upload de um objeto

Quando você faz upload de um objeto com o método putObject e fornece um algoritmo de soma de verificação, o SDK calcula a soma de verificação para o algoritmo especificado.

O trecho de código a seguir mostra uma solicitação para fazer upload de um objeto com uma soma de verificação SHA256. Quando o SDK envia a solicitação, ele calcula a soma de verificação SHA256 e carrega o objeto. O Amazon S3 valida a integridade do conteúdo calculando a soma de verificação e comparando-a com a soma de verificação fornecida pelo SDK. Depois, o Amazon S3 armazena a soma de verificação com o objeto.

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

Se você não fornecer um algoritmo de soma de verificação na solicitação, o comportamento da soma de verificação varia conforme a versão do SDK utilizado, conforme mostrado na tabela a seguir.

Comportamento da soma de verificação quando nenhum algoritmo de soma de verificação é fornecido

Versão do Java SDK Comportamento da soma de verificação
anterior à versão 2.30.0 O SDK não calcula automaticamente uma soma de verificação baseada em CRC e a fornece na solicitação.
2.30.0 ou posterior

O SDK usa o algoritmo CRC32 para calcular a soma de verificação e a fornece na solicitação. O Amazon S3 valida a integridade da transferência computando sua própria soma de verificação CRC32 e a compara com a soma de verificação fornecida pelo SDK. Se as somas de verificação corresponderem, a soma de verificação será salva com o objeto.

Usar um valor de soma de verificação pré-calculado

Um valor de soma de verificação pré-calculado fornecido com a solicitação desabilita a computação automática pelo SDK e, em vez disso, usa o valor fornecido.

O exemplo a seguir mostra uma solicitação com uma soma de verificação SHA256 pré-calculada.

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

Se o Amazon S3 determinar que o valor da soma de verificação está incorreto para o algoritmo especificado, o serviço retornará uma resposta de erro.

Carregamentos fracionados

Você também pode usar somas de verificação com carregamentos fracionados.

O SDK para Java 2.x fornece duas opções para usar somas de verificação com carregamentos fracionados. A primeira opção usa o S3TransferManager.

O exemplo de gerenciador de transferência a seguir especifica o algoritmo SHA1 para o 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();
    }

Se você não fornecer um algoritmo de soma de verificação ao usar o gerenciador de transferências para uploads, o SDK calculará automaticamente a soma de verificação com base no algoritmo CRC32. O SDK executa esse cálculo para todas as versões do SDK.

A segunda opção usa a API S3Client (ou a API S3AsyncClient) para executar o carregamento fracionado. Se você especificar uma soma de verificação com essa abordagem, deverá indicar o algoritmo a ser usado no início do carregamento. Você também deve especificar o algoritmo para a solicitação de cada parte e fornecer a soma de verificação calculada para cada parte após o carregamento.

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

O código para os exemplos e testes completos está no repositório de exemplos de código do GitHub.

Fazer download de um objeto

Quando você usa o método getObject para baixar um objeto, o SDK valida automaticamente a soma de verificação quando o método checksumMode do compilador do GetObjectRequest está definido como ChecksumMode.ENABLED.

A solicitação no trecho a seguir direciona o SDK a validar a soma de verificação na resposta calculando a soma de verificação e comparando os valores.

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

Se o objeto não tiver sido carregado com uma soma de verificação, nenhuma validação ocorrerá.

Outras opções de cálculo da soma de verificação

nota

Para verificar a integridade dos dados transmitidos e identificar quaisquer erros de transmissão, recomendamos que os usuários mantenham as configurações padrão do SDK para as opções de cálculo da soma de verificação. Por padrão, o SDK adiciona essa verificação importante para muitas operações do S3, incluindo PutObject e GetObject.

No entanto, se o uso do Amazon S3 exigir uma validação mínima da soma de verificação, você poderá desativar muitas verificações alterando as configurações padrão.

Desative o cálculo automático da soma de verificação, a menos que seja necessário

É possível desativar o cálculo automático da soma de verificação pelo SDK para operações compatíveis, por exemplo e PutObject e GetObject. No entanto, algumas operações do S3 exigem um cálculo de soma de verificação. e não é possível desativá-lo nessas operações.

O SDK fornece configurações separadas para o cálculo de uma soma de verificação para a carga útil de uma solicitação e para a carga útil de uma resposta.

A lista a seguir descreve as configurações que você pode usar para minimizar os cálculos de soma de verificação nos diferentes escopos.

  • Escopo de todas as aplicações: ao alterar as configurações nas variáveis de ambiente ou em um perfil nos arquivos AWS, config e credentials compartilhados, todas as aplicações podem usar essas configurações. Essas configurações afetam todos os clientes de serviço em todas as aplicações do AWS SDK, a menos que sejam substituídas no escopo da aplicação ou do cliente de serviço.

    • Adicione as configurações em um perfil:

      [default]
request_checksum_calculation = WHEN_REQUIRED
response_checksum_validation = WHEN_REQUIRED

    • Adicione variáveis de ambiente:

      AWS_REQUEST_CHECKSUM_CALCULATION=WHEN_REQUIRED
AWS_RESPONSE_CHECKSUM_VALIDATION=WHEN_REQUIRED

  • Escopo atual da aplicação: é possível definir a propriedade do sistema Java aws.requestChecksumCalculation como WHEN_REQUIRED para limitar o cálculo da soma de verificação. A propriedade do sistema correspondente para respostas é aws.responseChecksumValidation.

    Essas configurações afetam todos os clientes de serviço do SDK em todas as aplicações, a menos que sejam substituídas durante a criação do cliente de serviço.

    Defina a propriedade do sistema no início da aplicação:

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

  • Escopo de cliente de serviço único do S3: é possível configurar um único cliente de serviço do S3 para calcular a quantidade mínima de somas de verificação usando os métodos do compilador:

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

Use o LegacyMd5Plugin para simplificar a compatibilidade com o MD5

Junto com o lançamento do comportamento da soma de verificação CRC32 com a versão 2.30.0, o SDK parou de calcular somas de verificação MD5 nas operações necessárias.

Se precisar de um comportamento de soma de verificação MD5 legado para operações do S3, você poderá usar o LegacyMd5Plugin, que foi lançado com a versão 2.31.32 do SDK.

O LegacyMd5Plugin é útil principalmente quando você precisa manter a compatibilidade com aplicações que dependem do comportamento legado da soma de verificação MD5, ainda mais ao trabalhar com provedores de armazenamento de terceiros compatíveis com o S3, como aqueles usados com conectores de sistema de arquivos S3A (Apache Spark, Iceberg).

Para usar o LegacyMd5Plugin, adicione-o ao compilador de clientes do 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();

Se você quiser adicionar somas de verificação MD5 às operações que as exigem e ignorar a adição de somas de verificação padrão do SDK a operações que são compatíveis com elas, mas não as exigem, ative as opções requestChecksumCalculation e responseChecksumValidation de ClientBuilder como WHEN_REQUIRED. Isso adicionará somas de verificação padrão do SDK somente às operações que as exigem:

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

Essa configuração é útil principalmente ao trabalhar com sistemas de armazenamento de terceiros compatíveis com o S3 que podem não suportar totalmente os algoritmos de soma de verificação mais recentes, mas ainda exigem somas de verificação MD5 para determinadas operações.