Class UploadChecksum

Namespace

Cloudflare.NET.R2.Models

Assembly

Cloudflare.NET.R2.dll

A digest a presigned upload URL binds the uploaded bytes to: the algorithm, and the base64 text of the digest the bytes must hash to.

public sealed record UploadChecksum : IEquatable<UploadChecksum>

Inheritance

object

UploadChecksum

Implements

IEquatable<UploadChecksum>

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

object.ToString()

Examples

// From raw digest bytes computed locally:
var checksum = UploadChecksum.FromDigestBytes(R2ChecksumAlgorithm.Sha256, SHA256.HashData(fileBytes));

// From untrusted strings a client supplied:
if (!UploadChecksum.TryCreate(request.Algorithm, request.Digest, out var uploadChecksum))
    return BadRequest("Unknown checksum algorithm or malformed digest.");

Remarks

Passing an instance to PresignedPutRequest, PresignedUploadPartRequest or PresignedUploadPartsRequest signs the algorithm's header (HeaderName) into the URL. The client must then send that exact header, or the signature no longer matches and R2 answers 403. When the client does send it, R2 hashes the arriving bytes and rejects the upload with 400 BadDigest if they do not hash to the stated digest, storing nothing.

The constructor rejects a digest whose base64 text is malformed or whose decoded length is not exactly what the algorithm produces, so a URL is never signed for a digest R2 could not possibly accept. Use TryCreate(string?, string?, out UploadChecksum?) to validate untrusted algorithm and digest strings without exceptions, such as values arriving in an API request.

Constructors

UploadChecksum(R2ChecksumAlgorithm, string)

Creates a checksum after validating the digest against the algorithm's exact digest length.

public UploadChecksum(R2ChecksumAlgorithm algorithm, string base64Digest)

Parameters

algorithm R2ChecksumAlgorithm

The algorithm the digest was computed with.

base64Digest string

The base64 text of the digest the uploaded bytes must hash to.

Exceptions

ArgumentException

Thrown when algorithm is the uninitialized default, when base64Digest is not well-formed base64, or when its decoded length differs from the algorithm's DigestByteLength.

Properties

Algorithm

The algorithm the digest was computed with.

public R2ChecksumAlgorithm Algorithm { get; }

Property Value

R2ChecksumAlgorithm

Base64Digest

The base64 text of the digest the uploaded bytes must hash to.

public string Base64Digest { get; }

Property Value

string

Methods

FromDigestBytes(R2ChecksumAlgorithm, ReadOnlySpan<byte>)

Creates a checksum from raw digest bytes, base64-encoding them.

public static UploadChecksum FromDigestBytes(R2ChecksumAlgorithm algorithm, ReadOnlySpan<byte> digestBytes)

Parameters

algorithm R2ChecksumAlgorithm

The algorithm the digest was computed with.

digestBytes ReadOnlySpan<byte>

The raw digest bytes, exactly DigestByteLength of them.

Returns

UploadChecksum

The validated checksum.

Exceptions

ArgumentException

Thrown when the byte count differs from what the algorithm produces.

TryCreate(string?, string?, out UploadChecksum?)

Validates an untrusted algorithm name and digest text, producing a checksum only when the name is an algorithm R2 verifies and the digest decodes to exactly the length that algorithm produces.

public static bool TryCreate(string? algorithmName, string? base64Digest, out UploadChecksum? checksum)

Parameters

algorithmName string

The algorithm name to validate, case-insensitively (for example "sha256").

base64Digest string

The base64 digest text to validate.

checksum UploadChecksum

The validated checksum, when both inputs are acceptable.

Returns

bool

true when both inputs are acceptable.