Skip to main content

ChecksumStrategy

Struct ChecksumStrategy 

Source
pub struct ChecksumStrategy { /* private fields */ }
Expand description

How an upload’s checksums are chosen.

S3 checks each checksum an upload sends against the bytes it receives, and stores a checksum with the object. See Checking object integrity. A strategy answers three questions:

  1. Which algorithm? S3 stores the object’s checksum in this algorithm, named by a type from checksum.

  2. Should the stored checksum cover the whole object?

    • full_object: the stored checksum equals a checksum of the whole object, so it can be compared with one computed elsewhere. CRC64NVME, CRC32 or CRC32C: the FullObjectAlgorithm types.
    • composite: for a multipart upload, the stored checksum is a checksum of the part checksums. It depends on the part size and doesn’t equal a checksum of the object. CRC32, CRC32C, SHA1 or SHA256: the CompositeAlgorithm types. A single-request upload sends a full object checksum of the same algorithm.

    A constructor called with an algorithm its checksum type doesn’t support doesn’t compile.

  3. Do you know the expected checksum? with_expected_value gives S3 the value to check the uploaded object against; S3 rejects the upload if it doesn’t match. A single-request upload sends the value in place of a checksum calculated from the body. A multipart upload still calculates each part’s checksum and also sends the value with CompleteMultipartUpload. Supply one to check the stored object against its source: the checksums the transfer manager calculates cover only the bytes it sends, so they don’t detect a source that changed or was read incorrectly. For a full object strategy, a PartStream can instead return the value from PartStream::full_object_checksum after its final part.

The transfer manager calculates a checksum of each body it sends: the body of a single-request upload, and each part of a multipart upload. It doesn’t calculate a value you supply, with with_expected_value or through a PartStream. It never calculates the object-level checksum of a multipart upload: that value comes from you, or S3 derives it from the part checksums.

§Default

An upload without a strategy uses ChecksumStrategy::default(), a full object CRC64NVME strategy, when the request checksum policy is the default RequestChecksumCalculation::WhenSupported. Under RequestChecksumCalculation::WhenRequired, an upload without a strategy sends no checksums; S3 still stores a full object CRC64NVME checksum for the object. A strategy set on the upload is used under either policy.

Set the policy through aws_types::SdkConfig::builder. With sdk-v1, it can also be set on the S3 configuration builder before conversion into S3ClientConfig.

§What is sent

A single-request upload sends one checksum of the body: the expected value, or one calculated as the body is sent.

A multipart upload:

  1. CreateMultipartUpload declares the algorithm and the type.
  2. Each UploadPart carries its part’s checksum: the value a PartStream set with PartData::with_checksum, or else one calculated as the part is sent.
  3. CompleteMultipartUpload carries the type, each part’s checksum and, for a full object strategy, the expected value if there is one.
  4. S3 derives the object’s checksum from the part checksums. With an expected value, a mismatch fails the upload.

§Rules

  • A composite strategy with an expected value is valid only for a single-request upload. initiate fails with ErrorKind::InputInvalid before any request is sent when the body’s size has no upper bound, the body is a PartStream, or its upper bound is at least the multipart threshold.
  • Number a PartStream’s parts consecutively from 1. S3 requires it for parts that carry some checksums and fails CompleteMultipartUpload otherwise; see PartData::new.
  • Checksum values are the base64 encoding of the big-endian checksum.

§Downloads

A full object CRC lets a download, including one split into ranges, check the whole object it received. A composite checksum allows checks of responses that align with stored parts, not of the object as a whole. See ChecksumValidation.

Implementations§

Source§

impl ChecksumStrategy

Source

pub fn full_object<A: FullObjectAlgorithm>(algorithm: A) -> Self

Returns a strategy whose stored checksum is a full object checksum in algorithm, for a single-request or multipart upload.

FullObjectAlgorithm lists the supported algorithms.

Source

pub fn composite<A: CompositeAlgorithm>(algorithm: A) -> Self

Returns a strategy whose stored checksum, for a multipart upload, is a composite checksum in algorithm. A single-request upload sends a full object checksum in algorithm.

CompositeAlgorithm lists the supported algorithms.

Source

pub fn with_expected_value(self, value: impl Into<String>) -> Self

Sets the object’s expected checksum: the base64 encoding of the big-endian checksum of the whole object in the strategy’s algorithm.

S3 rejects the upload unless the object matches value. The transfer manager sends value as given and does not check it. A single-request upload sends it in place of a checksum calculated from the body; a multipart upload still calculates each part’s checksum and sends value with CompleteMultipartUpload.

A composite strategy with an expected value is valid only for a single-request upload. initiate fails with ErrorKind::InputInvalid, before any request is sent, for an upload sent as a multipart upload: the body’s size has no upper bound, the body is a PartStream, or its upper bound is at least the multipart threshold.

Source

pub fn algorithm(&self) -> &ChecksumAlgorithm

The algorithm of every checksum the upload sends and of the checksum S3 stores.

Source

pub fn multipart_checksum_type(&self) -> &ChecksumType

The type of the object’s checksum when the upload is sent as a multipart upload: ChecksumType::FullObject or ChecksumType::Composite.

A single-request upload always has a full object checksum.

Source

pub fn expected_value(&self) -> Option<&str>

The expected value set with with_expected_value, if any.

A value returned from PartStream::full_object_checksum is not reported here.

Trait Implementations§

Source§

impl Clone for ChecksumStrategy

Source§

fn clone(&self) -> Self

Returns a duplicate of the value. Read more
1.0.0 (const: unstable) · Source§

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source. Read more
Source§

impl Debug for ChecksumStrategy

Source§

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter. Read more
Source§

impl Default for ChecksumStrategy

Source§

fn default() -> Self

Returns a full object CRC64NVME strategy without an expected value.

Source§

impl Eq for ChecksumStrategy

Source§

impl PartialEq for ChecksumStrategy

Source§

fn eq(&self, other: &Self) -> bool

Equality operator ==. Read more
1.0.0 (const: unstable) · Source§

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=. Read more
Source§

impl StructuralPartialEq for ChecksumStrategy

Auto Trait Implementations§

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<ST, DT> CastableFrom<ST, Initialized, Initialized> for DT
where ST: ?Sized, DT: ?Sized,

Source§

impl<ST, DT> CastableFrom<ST, Uninit, Uninit> for DT
where ST: ?Sized, DT: ?Sized,

Source§

impl<T> CloneToUninit for T
where T: Clone,

Source§

unsafe fn clone_to_uninit(&self, dest: *mut u8)

🔬This is a nightly-only experimental API. (clone_to_uninit)
Performs copy-assignment from self to dest. Read more
Source§

impl<Q, K> Equivalent<K> for Q
where Q: Eq + ?Sized, K: Borrow<Q> + ?Sized,

Source§

fn equivalent(&self, key: &K) -> bool

Compare self to key and return true if they are equal.
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T> Instrument for T

Source§

fn instrument(self, span: Span) -> Instrumented<Self> ⓘ

Instruments this type with the provided Span, returning an Instrumented wrapper. Read more
Source§

fn in_current_span(self) -> Instrumented<Self> ⓘ

Instruments this type with the current Span, returning an Instrumented wrapper. Read more
Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T> IntoEither for T

Source§

fn into_either(self, into_left: bool) -> Either<Self, Self> ⓘ

Converts self into a Left variant of Either<Self, Self> if into_left is true. Converts self into a Right variant of Either<Self, Self> otherwise. Read more
Source§

fn into_either_with<F>(self, into_left: F) -> Either<Self, Self> ⓘ
where F: FnOnce(&Self) -> bool,

Converts self into a Left variant of Either<Self, Self> if into_left(&self) returns true. Converts self into a Right variant of Either<Self, Self> otherwise. Read more
Source§

impl<Unshared, Shared> IntoShared<Shared> for Unshared
where Shared: FromUnshared<Unshared>,

Source§

fn into_shared(self) -> Shared

Creates a shared type from an unshared type.
Source§

impl<T> Pointable for T

Source§

const ALIGN: usize

The alignment of pointer.
Source§

type Init = T

The type for initializers.
Source§

unsafe fn init(init: <T as Pointable>::Init) -> usize

Initializes a with the given initializer. Read more
Source§

unsafe fn deref<'a>(ptr: usize) -> &'a T

Dereferences the given pointer. Read more
Source§

unsafe fn deref_mut<'a>(ptr: usize) -> &'a mut T

Mutably dereferences the given pointer. Read more
Source§

unsafe fn drop(ptr: usize)

Drops the object pointed to by the given pointer. Read more
Source§

impl<T> Read<Exclusive, BecauseExclusive> for T
where T: ?Sized,

Source§

impl<T> Same for T

Source§

type Output = T

Should always be Self
Source§

impl<T> ToOwned for T
where T: Clone,

Source§

type Owned = T

The resulting type after obtaining ownership.
Source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
Source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = !

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, !>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.
Source§

impl<V, T> VZip<V> for T
where V: MultiLane<T>,

Source§

fn vzip(self) -> V

Source§

impl<T> WithSubscriber for T

Source§

fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self> ⓘ
where S: Into<Dispatch>,

Attaches the provided Subscriber to this type, returning a WithDispatch wrapper. Read more
Source§

fn with_current_subscriber(self) -> WithDispatch<Self> ⓘ

Attaches the current default Subscriber to this type, returning a WithDispatch wrapper. Read more