qualia_core_db/container_10d/section/
opaque_preservation.rs1use super::{
8 table_validation, AlignmentTier, SectionDescriptor, SectionTableError, SectionType,
9 SECTION_DESCRIPTOR_SIZE,
10};
11use crate::container_10d::crc32c::crc32c;
12use crate::container_10d::header::{
13 Container10dHeader, HeaderParseError, FLAG_DEFAULT_DISPOSITION_REFUSE, HEADER_VERSION,
14};
15use crate::container_10d::integrity::{
16 check_whole_file_crc32c, seal_whole_file_crc32c, IntegrityError,
17};
18
19#[derive(Debug, Clone, Copy, PartialEq, Eq)]
22pub struct OpaquePreservationBudget {
23 pub max_bytes: usize,
24 pub max_sections: usize,
25}
26
27#[derive(Debug, Clone, PartialEq, Eq)]
28pub enum OpaquePreservationError {
29 Header(HeaderParseError),
30 Integrity(IntegrityError),
31 Section(SectionTableError),
32 ByteBudget { needed: usize, maximum: usize },
33 SectionBudget { needed: usize, maximum: usize },
34 OutputTooSmall { needed: usize, have: usize },
35 UnsupportedTarget { section_type: u8 },
36 MissingTarget { section_type: u8 },
37 LengthChangeUnsupported { existing: usize, replacement: usize },
38 UnknownHeaderFlags { flags: u16 },
39 ReservedDescriptorMetadata { index: usize, reserved16: u16 },
40 UnresolvedDependencies { section_type: u8 },
41 OpaqueTailBytes { at: usize },
42}
43
44impl From<HeaderParseError> for OpaquePreservationError {
45 fn from(value: HeaderParseError) -> Self {
46 Self::Header(value)
47 }
48}
49impl From<IntegrityError> for OpaquePreservationError {
50 fn from(value: IntegrityError) -> Self {
51 Self::Integrity(value)
52 }
53}
54impl From<SectionTableError> for OpaquePreservationError {
55 fn from(value: SectionTableError) -> Self {
56 Self::Section(value)
57 }
58}
59impl std::fmt::Display for OpaquePreservationError {
60 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
61 write!(f, "10d opaque preservation: {self:?}")
62 }
63}
64impl std::error::Error for OpaquePreservationError {}
65
66#[derive(Debug)]
69pub struct OpaqueContainerView<'a> {
70 bytes: &'a [u8],
71 header: Container10dHeader,
72 sections: &'a [SectionDescriptor],
73}
74impl<'a> OpaqueContainerView<'a> {
75 pub fn bytes(&self) -> &'a [u8] {
76 self.bytes
77 }
78 pub fn header(&self) -> &Container10dHeader {
79 &self.header
80 }
81 pub fn sections(&self) -> &'a [SectionDescriptor] {
82 self.sections
83 }
84 pub fn payload(&self, index: usize) -> Option<&'a [u8]> {
86 let d = self.sections.get(index)?;
87 Some(&self.bytes[d.byte_offset as usize..d.byte_offset as usize + d.byte_length as usize])
88 }
89}
90
91pub fn inspect_opaque_container(
96 data: &[u8],
97 budget: OpaquePreservationBudget,
98) -> Result<OpaqueContainerView<'_>, OpaquePreservationError> {
99 if data.len() > budget.max_bytes {
100 return Err(OpaquePreservationError::ByteBudget {
101 needed: data.len(),
102 maximum: budget.max_bytes,
103 });
104 }
105 let header = Container10dHeader::parse(data)?;
106 let count = header.section_count as usize;
107 if count > budget.max_sections {
108 return Err(OpaquePreservationError::SectionBudget {
109 needed: count,
110 maximum: budget.max_sections,
111 });
112 }
113 check_whole_file_crc32c(data)?;
114 let sections = inspect_table(data, &header)?;
115 Ok(OpaqueContainerView {
116 bytes: data,
117 header,
118 sections,
119 })
120}
121
122fn inspect_table<'a>(
123 data: &'a [u8],
124 header: &Container10dHeader,
125) -> Result<&'a [SectionDescriptor], SectionTableError> {
126 if header.section_count == 0 {
127 return Ok(&[]);
128 }
129 let start = header.section_table_offset as usize;
132 let end = start
133 .checked_add(header.section_count as usize * SECTION_DESCRIPTOR_SIZE)
134 .ok_or(SectionTableError::BadSectionTablePointer {
135 offset: header.section_table_offset,
136 count: header.section_count,
137 })?;
138 let table = data
139 .get(start..end)
140 .ok_or(SectionTableError::InputTooShort {
141 got: data.len(),
142 need: end,
143 })?;
144 let descriptors = table_validation::borrow_table(table)?;
145 for (index, d) in descriptors.iter().enumerate() {
146 if d.section_type == 0 {
147 return Err(SectionTableError::UndefinedSectionType { index, got: 0 });
148 }
149 if descriptors[..index]
150 .iter()
151 .any(|old| old.section_type == d.section_type)
152 {
153 return Err(SectionTableError::DuplicateSectionType {
154 section_type: d.section_type,
155 });
156 }
157 if d.typ() == Some(SectionType::ManifoldIdentityV2) && header.version < HEADER_VERSION {
158 return Err(SectionTableError::SectionRequiresVersion {
159 section_type: d.section_type,
160 minimum_version: HEADER_VERSION,
161 actual_version: header.version,
162 });
163 }
164 let tier = AlignmentTier::from_u8(d.alignment_tier).ok_or(
165 SectionTableError::UndefinedAlignmentTier {
166 index,
167 got: d.alignment_tier,
168 },
169 )?;
170 let offset = d.byte_offset as usize;
171 let length = d.byte_length as usize;
172 if offset % tier.to_bytes() != 0 {
173 return Err(SectionTableError::MisalignedSection {
174 index,
175 offset: d.byte_offset,
176 tier,
177 });
178 }
179 let bounds_error = || SectionTableError::OutOfBounds {
180 index,
181 offset: d.byte_offset,
182 length: d.byte_length,
183 file_len: data.len(),
184 };
185 let payload_end = offset.checked_add(length).ok_or_else(bounds_error)?;
186 let payload = data.get(offset..payload_end).ok_or_else(bounds_error)?;
187 if length != 0
191 && (offset < super::HEADER_BYTE_SIZE || (offset < end && payload_end > start))
192 {
193 return Err(SectionTableError::SectionOverlapsMetadata { index });
194 }
195 if d.stride != 0
196 && u64::from(d.stride) * u64::from(d.element_count) != u64::from(d.byte_length)
197 {
198 return Err(SectionTableError::StrideInconsistentDescriptor {
199 index,
200 stride: d.stride,
201 element_count: d.element_count,
202 byte_length: d.byte_length,
203 });
204 }
205 let actual = crc32c(payload);
206 if actual != d.crc32c {
207 return Err(SectionTableError::CrcMismatch {
208 index,
209 section_type: d.section_type,
210 expected: d.crc32c,
211 got: actual,
212 });
213 }
214 for (previous, old) in descriptors[..index].iter().enumerate() {
215 if length != 0
217 && old.byte_length != 0
218 && offset < old.byte_offset as usize + old.byte_length as usize
219 && (old.byte_offset as usize) < payload_end
220 {
221 return Err(SectionTableError::OverlappingSections {
222 index_a: previous,
223 index_b: index,
224 });
225 }
226 }
227 }
228 table_validation::padding(data, descriptors, start, end)?;
229 Ok(descriptors)
230}
231
232fn capacity(out: &[u8], needed: usize) -> Result<(), OpaquePreservationError> {
233 if out.len() < needed {
234 Err(OpaquePreservationError::OutputTooSmall {
235 needed,
236 have: out.len(),
237 })
238 } else {
239 Ok(())
240 }
241}
242
243pub fn copy_opaque_container_into(
247 data: &[u8],
248 budget: OpaquePreservationBudget,
249 out: &mut [u8],
250) -> Result<usize, OpaquePreservationError> {
251 let view = inspect_opaque_container(data, budget)?;
252 capacity(out, view.bytes.len())?;
253 out[..data.len()].copy_from_slice(data);
254 Ok(data.len())
255}
256
257pub fn replace_known_section_bytes_preserving_layout(
265 data: &[u8],
266 section_type: SectionType,
267 replacement: &[u8],
268 budget: OpaquePreservationBudget,
269 out: &mut [u8],
270) -> Result<usize, OpaquePreservationError> {
271 let view = inspect_opaque_container(data, budget)?;
272 if !section_type.is_implemented() {
273 return Err(OpaquePreservationError::UnsupportedTarget {
274 section_type: section_type as u8,
275 });
276 }
277 let index = view
278 .sections
279 .iter()
280 .position(|d| d.typ() == Some(section_type))
281 .ok_or(OpaquePreservationError::MissingTarget {
282 section_type: section_type as u8,
283 })?;
284 let target = view.sections[index];
285 if replacement.len() != target.byte_length as usize {
286 return Err(OpaquePreservationError::LengthChangeUnsupported {
287 existing: target.byte_length as usize,
288 replacement: replacement.len(),
289 });
290 }
291 let unchanged = view.payload(index) == Some(replacement);
292 if !unchanged {
293 let flags = view.header.flags & !FLAG_DEFAULT_DISPOSITION_REFUSE;
294 if flags != 0 {
295 return Err(OpaquePreservationError::UnknownHeaderFlags { flags });
296 }
297 for (index, d) in view.sections.iter().enumerate() {
298 if d.reserved16 != 0 {
299 return Err(OpaquePreservationError::ReservedDescriptorMetadata {
300 index,
301 reserved16: d.reserved16,
302 });
303 }
304 if !d.typ().is_some_and(SectionType::is_implemented) {
305 return Err(OpaquePreservationError::UnresolvedDependencies {
306 section_type: d.section_type,
307 });
308 }
309 }
310 let occupied_end = view
314 .sections
315 .iter()
316 .filter(|d| d.byte_length != 0)
317 .map(|d| d.byte_offset as usize + d.byte_length as usize)
318 .max()
319 .unwrap_or(0)
320 .max(
321 view.header.section_table_offset as usize
322 + view.sections.len() * SECTION_DESCRIPTOR_SIZE,
323 )
324 .max(crate::container_10d::header::HEADER_BYTE_SIZE);
325 if let Some(relative) = data[occupied_end..].iter().position(|b| *b != 0) {
326 return Err(OpaquePreservationError::OpaqueTailBytes {
327 at: occupied_end + relative,
328 });
329 }
330 }
331 capacity(out, data.len())?;
332 out[..data.len()].copy_from_slice(data);
334 if !unchanged {
335 let offset = target.byte_offset as usize;
336 out[offset..offset + replacement.len()].copy_from_slice(replacement);
337 let crc_offset = view.header.section_table_offset as usize
338 + index * SECTION_DESCRIPTOR_SIZE
339 + std::mem::offset_of!(SectionDescriptor, crc32c);
340 out[crc_offset..crc_offset + 4].copy_from_slice(&crc32c(replacement).to_le_bytes());
341 seal_whole_file_crc32c(&mut out[..data.len()]);
342 }
343 Ok(data.len())
344}