ic_host_artifacts/artifact/
mod.rs

1//! Bounded streams and raw SHA-256 identities for artifact bytes.
2//!
3//! Consumers own trusted paths, admitted digests, and byte limits. An identity
4//! describes the bytes read; it does not freeze a path for later execution or
5//! certify an executable's version. Copying writes only to a caller-owned sink;
6//! paths, confinement, synchronization, publication and cleanup remain local.
7
8use sha2::{Digest, Sha256};
9use std::{
10    fmt,
11    io::{self, Read},
12    str::FromStr,
13};
14
15mod chunks;
16mod copy;
17#[cfg(feature = "gzip")]
18mod gzip;
19mod hashing;
20mod matching;
21#[cfg(test)]
22mod tests;
23mod writer;
24
25pub use chunks::{ChunkDigestError, chunk_digests};
26pub use copy::{CopyError, copy_reader};
27#[cfg(feature = "gzip")]
28pub use gzip::{GzipError, decode_gzip, encode_gzip, gzip_matches, hash_gzip, hash_gzip_or_raw};
29pub use hashing::HashingWriter;
30pub use matching::MatchingWriter;
31pub use writer::{BoundedWriter, WriterError};
32
33/// Raw SHA-256 identity, without a product-specific prefix or wire format.
34#[derive(Clone, Copy, Debug, Eq, Hash, PartialEq)]
35pub struct Sha256Digest([u8; 32]);
36
37impl Sha256Digest {
38    /// Construct an identity from exact digest bytes.
39    #[must_use]
40    pub const fn from_bytes(bytes: [u8; 32]) -> Self {
41        Self(bytes)
42    }
43
44    /// Borrow the digest bytes.
45    #[must_use]
46    pub const fn as_bytes(&self) -> &[u8; 32] {
47        &self.0
48    }
49
50    /// Hash bytes already held by the caller.
51    #[must_use]
52    pub fn compute(bytes: &[u8]) -> Self {
53        Self(Sha256::digest(bytes).into())
54    }
55}
56
57impl fmt::Display for Sha256Digest {
58    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
59        for byte in self.0 {
60            write!(f, "{byte:02x}")?;
61        }
62        Ok(())
63    }
64}
65
66/// Invalid lowercase hexadecimal digest authority.
67#[derive(Clone, Copy, Debug, Eq, PartialEq)]
68pub enum DigestParseError {
69    /// The digest does not contain exactly 64 ASCII bytes.
70    Length {
71        /// Observed byte length.
72        actual: usize,
73    },
74    /// A byte is not a lowercase hexadecimal digit.
75    Digit {
76        /// Offset of the invalid byte.
77        offset: usize,
78    },
79}
80
81impl fmt::Display for DigestParseError {
82    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
83        match self {
84            Self::Length { actual } => {
85                write!(f, "SHA-256 requires 64 hex bytes, received {actual}")
86            }
87            Self::Digit { offset } => write!(f, "invalid lowercase SHA-256 digit at byte {offset}"),
88        }
89    }
90}
91impl std::error::Error for DigestParseError {}
92
93impl FromStr for Sha256Digest {
94    type Err = DigestParseError;
95
96    fn from_str(text: &str) -> Result<Self, Self::Err> {
97        if text.len() != 64 {
98            return Err(DigestParseError::Length { actual: text.len() });
99        }
100        let mut bytes = [0; 32];
101        for (offset, digit) in text.bytes().enumerate() {
102            let nibble = match digit {
103                b'0'..=b'9' => digit - b'0',
104                b'a'..=b'f' => digit - b'a' + 10,
105                _ => return Err(DigestParseError::Digit { offset }),
106            };
107            bytes[offset / 2] |= nibble << if offset % 2 == 0 { 4 } else { 0 };
108        }
109        Ok(Self(bytes))
110    }
111}
112
113/// Exact size and digest of one bounded byte stream.
114#[derive(Clone, Copy, Debug, Eq, PartialEq)]
115pub struct ArtifactIdentity {
116    /// Number of bytes successfully read.
117    pub bytes: u64,
118    /// SHA-256 of those bytes.
119    pub sha256: Sha256Digest,
120}
121
122/// A bounded read or digest verification failed.
123#[derive(Debug)]
124pub enum ArtifactError {
125    /// The reader or filesystem failed. No partial identity is returned.
126    Io(io::Error),
127    /// The selected path is not a regular file.
128    NotRegularFile,
129    /// A stream exceeded the caller's byte allowance.
130    LimitExceeded {
131        /// Maximum permitted bytes.
132        limit: u64,
133    },
134    /// The complete bounded stream does not match the admitted digest.
135    DigestMismatch {
136        /// Caller-selected authority.
137        expected: Sha256Digest,
138        /// Observed size and digest.
139        actual: ArtifactIdentity,
140    },
141    /// Storage could not be allocated for a bounded file read.
142    Allocation(std::collections::TryReserveError),
143}
144
145impl fmt::Display for ArtifactError {
146    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
147        match self {
148            Self::Io(source) => write!(f, "artifact read failed: {source}"),
149            Self::NotRegularFile => f.write_str("artifact path is not a regular file"),
150            Self::LimitExceeded { limit } => write!(f, "artifact exceeds {limit} bytes"),
151            Self::DigestMismatch { expected, actual } => write!(
152                f,
153                "artifact SHA-256 is {}, expected {expected}",
154                actual.sha256
155            ),
156            Self::Allocation(source) => write!(f, "artifact allocation failed: {source}"),
157        }
158    }
159}
160impl std::error::Error for ArtifactError {
161    fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
162        match self {
163            Self::Io(source) => Some(source),
164            Self::Allocation(source) => Some(source),
165            _ => None,
166        }
167    }
168}
169impl From<io::Error> for ArtifactError {
170    fn from(source: io::Error) -> Self {
171        Self::Io(source)
172    }
173}
174
175/// Preserve native I/O identity or retain the typed artifact cause at an I/O boundary.
176impl From<ArtifactError> for io::Error {
177    fn from(error: ArtifactError) -> Self {
178        match error {
179            ArtifactError::Io(source) => source,
180            other => Self::other(other),
181        }
182    }
183}
184
185/// Hash one stream with constant working memory and no reliance on metadata.
186///
187/// Reads at most `max_bytes + 1` bytes, using the extra byte to detect overflow.
188/// Retries interrupted reads only; no subprocess or network retry is performed.
189/// A blocking reader's timeouts remain the caller's responsibility.
190///
191/// # Errors
192/// Returns [`ArtifactError::LimitExceeded`] or the underlying read error.
193/// An impossible reader byte count returns IO [`io::ErrorKind::InvalidData`].
194pub fn hash_reader(
195    mut reader: impl Read,
196    max_bytes: u64,
197) -> Result<ArtifactIdentity, ArtifactError> {
198    let mut hasher = Sha256::new();
199    let bytes = visit_reader::<ArtifactError>(&mut reader, max_bytes, |chunk| {
200        hasher.update(chunk);
201        Ok(())
202    })?;
203    Ok(ArtifactIdentity {
204        bytes,
205        sha256: Sha256Digest(hasher.finalize().into()),
206    })
207}
208
209/// Verify a complete bounded stream before the caller extracts or uses its bytes.
210///
211/// # Errors
212/// Returns read/limit failures or a typed mismatch with the observed identity.
213pub fn verify_reader(
214    reader: impl Read,
215    max_bytes: u64,
216    expected: Sha256Digest,
217) -> Result<ArtifactIdentity, ArtifactError> {
218    let actual = hash_reader(reader, max_bytes)?;
219    if actual.sha256 != expected {
220        return Err(ArtifactError::DigestMismatch { expected, actual });
221    }
222    Ok(actual)
223}
224
225/// Read one stream into bounded, fallibly allocated storage.
226///
227/// Observes at most `max_bytes + 1` bytes to detect overflow. A blocking reader's
228/// deadline remains caller-owned. Only interrupted reads are retried.
229///
230/// # Errors
231/// Returns read, allocation, or byte-limit failures. An impossible reader byte
232/// count returns IO [`io::ErrorKind::InvalidData`].
233pub fn read_reader(mut reader: impl Read, max_bytes: usize) -> Result<Vec<u8>, ArtifactError> {
234    let mut bytes = Vec::new();
235    visit_reader::<ArtifactError>(&mut reader, max_bytes as u64, |chunk| {
236        bytes
237            .try_reserve_exact(chunk.len())
238            .map_err(ArtifactError::Allocation)?;
239        bytes.extend_from_slice(chunk);
240        Ok(())
241    })?;
242    Ok(bytes)
243}
244
245fn visit_reader<E: From<ArtifactError>>(
246    reader: &mut impl Read,
247    limit: u64,
248    mut visit: impl FnMut(&[u8]) -> Result<(), E>,
249) -> Result<u64, E> {
250    let mut bytes = 0_u64;
251    let mut buffer = [0_u8; 16 * 1024];
252    loop {
253        let remaining = usize::try_from(limit - bytes).unwrap_or(usize::MAX);
254        let allowance = remaining.saturating_add(1).min(buffer.len());
255        let count = match reader.read(&mut buffer[..allowance]) {
256            Ok(count) => count,
257            Err(source) if source.kind() == io::ErrorKind::Interrupted => continue,
258            Err(source) => return Err(ArtifactError::Io(source).into()),
259        };
260        if count > allowance {
261            return Err(ArtifactError::Io(io::Error::new(
262                io::ErrorKind::InvalidData,
263                "reader returned more bytes than its buffer can hold",
264            ))
265            .into());
266        }
267        if count == 0 {
268            return Ok(bytes);
269        }
270        if count as u64 > limit - bytes {
271            return Err(ArtifactError::LimitExceeded { limit }.into());
272        }
273        visit(&buffer[..count])?;
274        bytes += count as u64;
275    }
276}
ic_host_artifacts/artifact/mod.rs

ic_host_artifacts/artifact/
mod.rs
