/ 
AWS-Signature-V4-0.001
/ AWS::Signature::V4::Checksum

NAME

AWS::Signature::V4::Checksum - Incremental checksums for S3 trailers

VERSION

This module is part of the AWS::Signature::V4 distribution and shares its version.

SYNOPSIS

use AWS::Signature::V4::Checksum ();

my $sum = AWS::Signature::V4::Checksum->new('crc32c');
$sum->add(\$_) for @pieces;    # or $sum->add(\$data)
my $value = $sum->base64;       # to send as x-amz-checksum-crc32c

my $size = AWS::Signature::V4::Checksum->encoded_size('sha256');   # 44

DESCRIPTION

This module computes, a piece at a time, the checksums that S3 accepts in the x-amz-checksum-* headers and trailers: crc32, crc32c, sha1 and sha256. crc32 comes from Compress::Raw::Zlib, the SHA ones from Digest::SHA, crc32c from String::CRC32C if it is installed. Otherwise crc32c is computed in pure Perl, at roughly 12 MB/s: install String::CRC32C to use it with big data.

crc64nvme is not provided: for that and any other algorithm, first figure out if you really need something that is not provided out of the box with one of the alternatives above, then if still convinced calculate the value yourself and give it to "finish" in AWS::Signature::V4::Chunker.

You normally do not need to use this module: AWS::Signature::V4 uses it on your behalf when you pass checksum to "sign" in AWS::Signature::V4 or "encoded_length" in AWS::Signature::V4, and the chunker feeds it with the data. It is however safe to use it directly, e.g. to compute a checksum in advance and send it as a normal header, because it is self-contained and does not depend on any signing material. Note that it is not tied to the AWS signature in any way.

INTERFACE

new

my $sum = AWS::Signature::V4::Checksum->new($algorithm);

Start a new checksum. $algorithm is one of crc32, crc32c, sha1 and sha256, in lowercase. Other names are not validated here; "sign" in AWS::Signature::V4 checks them before getting to this point, so check against "is_supported_algorithm" if you call this directly.

add

$sum->add(\$bytes);

Update the checksum with a piece of data. The argument is a reference to a byte string, to avoid copying data around. Return the object, so calls can be chained.

It is an error (an Ouch exception with code 400) to pass anything else than a reference to a defined string, or a string with characters that do not fit in a byte: encode them first, e.g. with Encode::encode('UTF-8', $text).

base64

my $value = $sum->base64;

Return the checksum of what was added so far, as base64 of the raw (big-endian) checksum without line breaks, as AWS wants it. It does not consume the object for the CRCs, but for the SHA algorithms it does (Digest::SHA resets after digest): call it once, at the end.

encoded_size

my $length = AWS::Signature::V4::Checksum->encoded_size($algorithm);

Class method returning the length of the base64 value for an algorithm (8 for the CRCs, 28 for sha1, 44 for sha256). It is what "encoded_length" in AWS::Signature::V4 needs to work out the size of the trailer without having the data.

is_supported_algorithm

my $bool = AWS::Signature::V4::Checksum->is_supported_algorithm($name);

Class method returning a (Perl) true/false value indicating whether the provided $name is the name of a supported algorithm or not.

supported_algorithms

my @list = AWS::Signature::V4::Checksum->supported_algorithms;

Class method returning the sorted list of supported checksum algorithms.

AUTHOR

Flavio Poletti <flavio@polettix.it>

COPYRIGHT AND LICENSE

Copyright 2026 by Flavio Poletti <flavio@polettix.it>

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.