1use sha2::{Digest, Sha256};
14use std::{
15 fs::{self, File},
16 io::Read,
17 path::Path,
18};
19
20const DIGEST_BUFFER_BYTES: usize = 64 * 1024;
25
26#[derive(Debug, Clone, Copy, PartialEq, Eq)]
31pub enum DigestError {
32 Unavailable,
34 NotRegularFile,
36 Empty,
38 OpenFailed,
40 ReadFailed,
42 SizeOverflow,
44 ChangedDuringRead,
46}
47
48impl DigestError {
49 pub fn reason(self) -> &'static str {
55 match self {
56 Self::Unavailable => "is unavailable",
57 Self::NotRegularFile => "is not a regular non-symlink file",
58 Self::Empty => "must be non-empty",
59 Self::OpenFailed => "cannot be opened",
60 Self::ReadFailed => "read failed",
61 Self::SizeOverflow => "size overflow",
62 Self::ChangedDuringRead => "changed during read",
63 }
64 }
65}
66
67impl std::fmt::Display for DigestError {
68 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
69 write!(f, "digest input {}", self.reason())
70 }
71}
72
73impl std::error::Error for DigestError {}
74
75pub fn file_digest(path: &Path) -> Result<(u64, String), DigestError> {
111 let before = fs::symlink_metadata(path).map_err(|_| DigestError::Unavailable)?;
112 if before.file_type().is_symlink() || !before.is_file() {
113 return Err(DigestError::NotRegularFile);
114 }
115 if before.len() == 0 {
116 return Err(DigestError::Empty);
117 }
118 let mut file = File::open(path).map_err(|_| DigestError::OpenFailed)?;
119 let (size, digest) = hash_stream(&mut file)?;
120 if size == 0 {
121 return Err(DigestError::Empty);
122 }
123 post_read_check(path, size)?;
124 Ok((size, digest))
125}
126
127fn hash_stream(file: &mut File) -> Result<(u64, String), DigestError> {
129 let mut hasher = Sha256::new();
130 let mut size = 0u64;
131 let mut buffer = [0u8; DIGEST_BUFFER_BYTES];
132 loop {
133 let count = file
134 .read(&mut buffer)
135 .map_err(|_| DigestError::ReadFailed)?;
136 if count == 0 {
137 break;
138 }
139 size = add_size(size, count as u64)?;
140 hasher.update(&buffer[..count]);
141 }
142 let digest = hasher.finalize();
143 Ok((
144 size,
145 digest.iter().map(|byte| format!("{byte:02x}")).collect(),
146 ))
147}
148
149fn add_size(size: u64, count: u64) -> Result<u64, DigestError> {
151 size.checked_add(count).ok_or(DigestError::SizeOverflow)
152}
153
154fn post_read_check(path: &Path, size: u64) -> Result<(), DigestError> {
156 let after = fs::symlink_metadata(path).map_err(|_| DigestError::ChangedDuringRead)?;
157 if !post_read_stable(&after, size) {
158 return Err(DigestError::ChangedDuringRead);
159 }
160 Ok(())
161}
162
163fn post_read_stable(after: &fs::Metadata, size: u64) -> bool {
165 !after.file_type().is_symlink() && after.is_file() && after.len() == size
166}
167
168#[cfg(test)]
169mod tests {
170 use super::*;
171 use crate::test_temp_dir;
172 use std::path::PathBuf;
173
174 fn write_file(root: &Path, name: &str, bytes: &[u8]) -> PathBuf {
175 let path = root.join(name);
176 fs::write(&path, bytes).unwrap();
177 path
178 }
179
180 #[test]
181 fn regular_file_digest_is_the_lowercase_hex_sha256_of_its_bytes() {
182 let root = test_temp_dir("digest-regular");
183 let path = write_file(&root, "artifact", b"abc");
184 let (size, sha256) = file_digest(&path).unwrap();
185 assert_eq!(size, 3);
186 assert_eq!(
187 sha256,
188 "ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad"
189 );
190 assert_eq!(sha256.len(), 64);
191 assert_eq!(sha256, sha256.to_lowercase());
192 fs::remove_dir_all(root).unwrap();
193 }
194
195 #[test]
196 fn identical_bytes_digest_identically_and_different_bytes_differ() {
197 let root = test_temp_dir("digest-determinism");
198 let first = write_file(&root, "first", b"payload");
199 let second = write_file(&root, "second", b"payload");
200 let third = write_file(&root, "third", b"payload!");
201 let first_digest = file_digest(&first).unwrap();
202 let second_digest = file_digest(&second).unwrap();
203 let third_digest = file_digest(&third).unwrap();
204 assert_eq!(first_digest, second_digest);
205 assert_ne!(first_digest, third_digest);
206 assert_ne!(first_digest.0, third_digest.0);
207 fs::remove_dir_all(root).unwrap();
208 }
209
210 #[test]
211 fn empty_file_is_refused_before_it_is_read() {
212 let root = test_temp_dir("digest-empty");
213 let path = write_file(&root, "empty", b"");
214 assert_eq!(file_digest(&path).unwrap_err(), DigestError::Empty);
215 fs::remove_dir_all(root).unwrap();
216 }
217
218 #[test]
219 fn a_zero_length_read_is_refused_even_when_the_file_grew_empty_after_the_check() {
220 let root = test_temp_dir("digest-truncated");
226 let path = write_file(&root, "artifact", b"0123456789");
227 let (size, _) = hash_stream(&mut File::open(&path).unwrap()).unwrap();
228 assert_eq!(size, 10);
229 fs::write(&path, b"").unwrap();
230 assert_eq!(file_digest(&path).unwrap_err(), DigestError::Empty);
231 assert_eq!(
232 post_read_check(&path, size).unwrap_err(),
233 DigestError::ChangedDuringRead
234 );
235 fs::remove_dir_all(root).unwrap();
236 }
237
238 #[test]
239 fn directory_is_refused() {
240 let root = test_temp_dir("digest-directory");
241 assert_eq!(file_digest(&root).unwrap_err(), DigestError::NotRegularFile);
242 fs::remove_dir_all(root).unwrap();
243 }
244
245 #[test]
246 fn missing_path_is_refused() {
247 let root = test_temp_dir("digest-missing");
248 let path = root.join("absent");
249 assert_eq!(file_digest(&path).unwrap_err(), DigestError::Unavailable);
250 fs::remove_dir_all(root).unwrap();
251 }
252
253 #[cfg(unix)]
254 #[test]
255 fn symlink_is_refused() {
256 let root = test_temp_dir("digest-symlink");
257 let target = write_file(&root, "target", b"payload");
258 let link = root.join("link");
259 std::os::unix::fs::symlink(&target, &link).unwrap();
260 assert_eq!(file_digest(&link).unwrap_err(), DigestError::NotRegularFile);
261 fs::remove_dir_all(root).unwrap();
262 }
263
264 #[test]
265 fn post_read_length_change_is_refused() {
266 let root = test_temp_dir("digest-length-change");
273 let path = write_file(&root, "artifact", b"0123456789");
274 let (size, _) = hash_stream(&mut File::open(&path).unwrap()).unwrap();
275 assert_eq!(size, 10);
276 fs::write(&path, b"0123456789abcd").unwrap();
277 assert_eq!(
278 post_read_check(&path, size).unwrap_err(),
279 DigestError::ChangedDuringRead
280 );
281 fs::remove_dir_all(root).unwrap();
282 }
283
284 #[test]
285 fn post_read_type_change_is_refused() {
286 let root = test_temp_dir("digest-type-change");
289 let path = write_file(&root, "artifact", b"0123456789");
290 let (size, _) = hash_stream(&mut File::open(&path).unwrap()).unwrap();
291 fs::remove_file(&path).unwrap();
292 fs::create_dir(&path).unwrap();
293 assert_eq!(
294 post_read_check(&path, size).unwrap_err(),
295 DigestError::ChangedDuringRead
296 );
297 fs::remove_dir_all(root).unwrap();
298 }
299
300 #[cfg(unix)]
301 #[test]
302 fn post_read_symlink_change_is_refused() {
303 let root = test_temp_dir("digest-symlink-change");
305 let path = write_file(&root, "artifact", b"0123456789");
306 let (size, _) = hash_stream(&mut File::open(&path).unwrap()).unwrap();
307 fs::remove_file(&path).unwrap();
308 let target = write_file(&root, "target", b"0123456789");
309 std::os::unix::fs::symlink(&target, &path).unwrap();
310 assert_eq!(
311 post_read_check(&path, size).unwrap_err(),
312 DigestError::ChangedDuringRead
313 );
314 fs::remove_dir_all(root).unwrap();
315 }
316
317 #[test]
318 fn size_overflow_is_an_error_not_a_wrapped_value() {
319 assert_eq!(
320 add_size(u64::MAX, 1).unwrap_err(),
321 DigestError::SizeOverflow
322 );
323 assert_eq!(add_size(10, 5).unwrap(), 15);
324 }
325}