#![allow(deprecated)]
use crate::manifest::TdfManifest;
use std::fs::File;
use std::io::{self, Read, Seek, Write};
use std::path::Path;
use zip::write::{FileOptions, SimpleFileOptions};
use zip::{ZipArchive, ZipWriter};
#[cfg(feature = "kas-client")]
use opentdf_protocol::KasError;
#[cfg(feature = "kas-client")]
use crate::kas::KasClient;
use crate::TdfEncryption;
use crate::manifest::IntegrityInformationExt;
#[derive(Debug)]
pub struct TdfArchive<R: Read + Seek> {
zip_archive: ZipArchive<R>,
max_manifest_size: u64,
max_payload_size: u64,
}
pub const DEFAULT_MAX_MANIFEST_SIZE: u64 = 16 * 1024 * 1024;
pub const DEFAULT_MAX_PAYLOAD_SIZE: u64 = 1024 * 1024 * 1024;
fn read_member_bounded<M: Read>(
member: M,
name: &str,
declared_size: u64,
limit: u64,
) -> Result<Vec<u8>, TdfError> {
let too_large = || TdfError::MemberTooLarge {
member: name.to_string(),
limit,
};
if declared_size > limit {
return Err(too_large());
}
let mut bytes = Vec::new();
member
.take(limit.saturating_add(1))
.read_to_end(&mut bytes)?;
if bytes.len() as u64 > limit {
return Err(too_large());
}
Ok(bytes)
}
pub const TDF_MANIFEST_FILE_NAME: &str = "manifest.json";
pub const LEGACY_TDF_MANIFEST_FILE_NAME: &str = "0.manifest.json";
pub const TDF_PAYLOAD_FILE_NAME: &str = "0.payload";
fn manifest_entry_name_for_index(index: usize) -> (String, Option<String>) {
if index == 0 {
(
TDF_MANIFEST_FILE_NAME.to_string(),
Some(LEGACY_TDF_MANIFEST_FILE_NAME.to_string()),
)
} else {
(format!("{}.manifest.json", index), None)
}
}
fn is_safe_entry_name(name: &str) -> bool {
!name.is_empty()
&& !name.starts_with('/')
&& !name.contains('\\')
&& !name.split('/').any(|seg| seg == "..")
}
fn is_manifest_entry_name(name: &str) -> bool {
if name == TDF_MANIFEST_FILE_NAME {
return true;
}
match name.strip_suffix(".manifest.json") {
Some(prefix) => !prefix.is_empty() && prefix.bytes().all(|b| b.is_ascii_digit()),
None => false,
}
}
fn payload_entry_name_for(manifest: &TdfManifest, index: usize) -> Result<String, TdfError> {
let url = manifest.payload.url.as_str();
if url.is_empty() {
return Ok(if index == 0 {
TDF_PAYLOAD_FILE_NAME.to_string()
} else {
format!("{}.payload", index)
});
}
if !is_safe_entry_name(url) {
return Err(TdfError::InvalidStructure {
reason: format!("unsafe payload url in manifest: {url:?}"),
expected: Some("a relative zip member name without '..' or leading '/'".to_string()),
});
}
if is_manifest_entry_name(url) {
return Err(TdfError::InvalidStructure {
reason: format!("payload url collides with the manifest entry name: {url:?}"),
expected: Some("a member name that is not shaped like a manifest entry".to_string()),
});
}
Ok(url.to_string())
}
#[derive(Debug)]
pub struct TdfEntry<'a> {
pub manifest: TdfManifest,
pub payload: Vec<u8>,
pub index: usize,
_lifetime: std::marker::PhantomData<&'a ()>,
}
impl<'a> TdfEntry<'a> {
#[cfg(feature = "kas-client")]
pub async fn decrypt_with_kas(&self, kas_client: &KasClient) -> Result<Vec<u8>, TdfError> {
let payload_key = kas_client.rewrap_standard_tdf(&self.manifest).await?;
self.decrypt_with_key(&payload_key)
}
pub fn decrypt_with_key(&self, payload_key: &[u8]) -> Result<Vec<u8>, TdfError> {
use base64::{Engine as _, engine::general_purpose::STANDARD as BASE64};
let tdf_encryption =
TdfEncryption::with_payload_key(payload_key).map_err(|e| TdfError::CryptoError {
algorithm: "AES-256-GCM".to_string(),
reason: "Invalid payload key".to_string(),
source: Some(Box::new(e)),
})?;
let integrity = &self.manifest.encryption_information.integrity_information;
if !integrity.segments.is_empty() {
let segment_sizes = integrity.segment_sizes();
const SEGMENT_OVERHEAD: u64 = 28;
for (index, (plaintext, encrypted)) in segment_sizes.iter().enumerate() {
let max_plaintext = encrypted.saturating_sub(SEGMENT_OVERHEAD);
if *plaintext > max_plaintext {
return Err(TdfError::CryptoError {
algorithm: "AES-256-GCM-segments".to_string(),
reason: format!(
"integrity: segment {index} declares a {plaintext}-byte plaintext but \
only {encrypted} encrypted bytes (at most {max_plaintext})"
),
source: None,
});
}
}
let described_size = segment_sizes
.iter()
.try_fold(0u64, |total, (_, encrypted)| total.checked_add(*encrypted))
.ok_or_else(|| TdfError::CryptoError {
algorithm: "AES-256-GCM-segments".to_string(),
reason: "integrity: the manifest's segment sizes overflow a 64-bit length"
.to_string(),
source: None,
})?;
if described_size != self.payload.len() as u64 {
return Err(TdfError::CryptoError {
algorithm: "AES-256-GCM-segments".to_string(),
reason: format!(
"integrity: payload is {} bytes but the manifest's segments describe {} bytes",
self.payload.len(),
described_size
),
source: None,
});
}
let (plaintext, gmac_tags) = tdf_encryption
.decrypt_with_segments(&self.payload, &segment_sizes)
.map_err(|e| TdfError::CryptoError {
algorithm: "AES-256-GCM-segments".to_string(),
reason: format!("integrity: segment decryption failed: {}", e),
source: Some(Box::new(e)),
})?;
integrity
.verify_segments_and_root_signature(&gmac_tags, payload_key)
.map_err(|e| {
let reason = e.to_string();
TdfError::CryptoError {
algorithm: "GMAC-SHA256".to_string(),
reason,
source: Some(Box::new(e)),
}
})?;
Ok(plaintext)
} else {
let iv_b64 = &self.manifest.encryption_information.method.iv;
let iv = BASE64
.decode(iv_b64)
.map_err(|e| TdfError::DecryptionFailed {
reason: format!("Invalid IV encoding: {}", e),
algorithm: Some("Base64".to_string()),
})?;
use aes_gcm::{
Aes256Gcm, Nonce,
aead::{Aead, KeyInit},
};
let cipher =
Aes256Gcm::new_from_slice(payload_key).map_err(|_| TdfError::DecryptionFailed {
reason: "Invalid key length".to_string(),
algorithm: Some("AES-256-GCM".to_string()),
})?;
const GCM_NONCE_LENGTH: usize = 12;
if iv.len() != GCM_NONCE_LENGTH {
return Err(TdfError::DecryptionFailed {
reason: format!(
"integrity: method.iv is {} bytes, expected {GCM_NONCE_LENGTH}",
iv.len()
),
algorithm: Some("AES-256-GCM".to_string()),
});
}
let nonce = Nonce::from_slice(&iv);
let plaintext = cipher.decrypt(nonce, self.payload.as_ref()).map_err(|e| {
TdfError::DecryptionFailed {
reason: format!("AES-GCM decryption failed: {}", e),
algorithm: Some("AES-256-GCM".to_string()),
}
})?;
Ok(plaintext)
}
}
}
#[derive(Debug, thiserror::Error)]
pub enum TdfError {
#[error("ZIP error: {0}")]
ZipError(#[from] zip::result::ZipError),
#[error("JSON error: {0}")]
JsonError(#[from] serde_json::Error),
#[error("IO error: {0}")]
IoError(#[from] io::Error),
#[error("Invalid manifest: field '{field}' - {reason}")]
InvalidManifest {
field: String,
reason: String,
suggestion: Option<String>,
},
#[error("Invalid TDF structure: {reason}")]
InvalidStructure {
reason: String,
expected: Option<String>,
},
#[error("TDF archive member '{member}' exceeds the {limit}-byte size limit")]
MemberTooLarge { member: String, limit: u64 },
#[error("Missing required field: {field}")]
MissingRequiredField { field: &'static str },
#[error("Invalid KAS URL: {url} - {reason}")]
InvalidKasUrl { url: String, reason: KasUrlError },
#[error("Cryptographic operation failed: {algorithm} - {reason}")]
CryptoError {
algorithm: String,
reason: String,
#[source]
source: Option<Box<dyn std::error::Error + Send + Sync>>,
},
#[cfg(feature = "kas-client")]
#[error("KAS error: {0}")]
KasError(#[from] KasError),
#[error("Decryption failed: {reason}")]
DecryptionFailed {
reason: String,
algorithm: Option<String>,
},
#[error("Policy validation failed for policy '{policy_id}': {errors:?}")]
PolicyValidationFailed {
policy_id: String,
errors: Vec<String>,
},
}
#[derive(Debug, thiserror::Error)]
pub enum KasUrlError {
#[error("URL must use HTTPS scheme, not HTTP")]
NotHttps,
#[error("Invalid URL scheme: {0}")]
InvalidScheme(String),
#[error("Malformed URL: {0}")]
MalformedUrl(String),
#[error("Missing host in URL")]
MissingHost,
}
impl TdfError {
pub fn is_retryable(&self) -> bool {
match self {
TdfError::IoError(_) => true,
#[cfg(feature = "kas-client")]
TdfError::KasError(kas_err) => kas_err.is_retryable(),
_ => false,
}
}
pub fn suggestion(&self) -> Option<&str> {
match self {
TdfError::InvalidManifest { suggestion, .. } => suggestion.as_deref(),
TdfError::InvalidKasUrl {
reason: KasUrlError::NotHttps,
..
} => Some("Use HTTPS URLs for KAS endpoints (e.g., https://kas.example.com)"),
TdfError::MissingRequiredField { field } if *field == "kas_url" => {
Some("Provide a KAS URL using .kas_url() on the builder")
}
_ => None,
}
}
pub fn error_code(&self) -> &'static str {
match self {
TdfError::ZipError(_) => "OPENTDF_E_ARCHIVE_ZIP",
TdfError::JsonError(_) => "OPENTDF_E_ARCHIVE_JSON",
TdfError::IoError(_) => "OPENTDF_E_IO",
TdfError::InvalidManifest { .. } => "OPENTDF_E_MANIFEST_INVALID",
TdfError::InvalidStructure { .. } => "OPENTDF_E_STRUCTURE_INVALID",
TdfError::MemberTooLarge { .. } => "OPENTDF_E_ARCHIVE_MEMBER_TOO_LARGE",
TdfError::MissingRequiredField { .. } => "OPENTDF_E_FIELD_REQUIRED",
TdfError::InvalidKasUrl { .. } => "OPENTDF_E_KAS_URL_INVALID",
TdfError::CryptoError { .. } => "OPENTDF_E_CRYPTO",
#[cfg(feature = "kas-client")]
TdfError::KasError(_) => "OPENTDF_E_KAS",
TdfError::DecryptionFailed { .. } => "OPENTDF_E_DECRYPTION_FAILED",
TdfError::PolicyValidationFailed { .. } => "OPENTDF_E_POLICY_VALIDATION",
}
}
}
impl TdfArchive<File> {
pub fn open<P: AsRef<Path>>(path: P) -> Result<Self, TdfError> {
Self::new(File::open(path)?)
}
#[cfg(feature = "kas-client")]
pub async fn open_and_decrypt<P: AsRef<Path>>(
path: P,
kas_client: &KasClient,
) -> Result<Vec<u8>, TdfError> {
let mut archive = Self::open(path)?;
let entry = archive.by_index()?;
entry.decrypt_with_kas(kas_client).await
}
}
impl<R: Read + Seek> TdfArchive<R> {
pub fn new(reader: R) -> Result<Self, TdfError> {
let zip_archive = ZipArchive::new(reader)?;
Ok(Self {
zip_archive,
max_manifest_size: DEFAULT_MAX_MANIFEST_SIZE,
max_payload_size: DEFAULT_MAX_PAYLOAD_SIZE,
})
}
#[must_use]
pub fn with_max_manifest_size(mut self, limit: u64) -> Self {
self.max_manifest_size = limit;
self
}
#[must_use]
pub fn with_max_payload_size(mut self, limit: u64) -> Self {
self.max_payload_size = limit;
self
}
pub fn max_manifest_size(&self) -> u64 {
self.max_manifest_size
}
pub fn max_payload_size(&self) -> u64 {
self.max_payload_size
}
pub fn len(&self) -> usize {
let mut count = 0;
let mut saw_index0 = false;
for name in self.zip_archive.file_names() {
let Ok(name) = name else {
continue;
};
if name == TDF_MANIFEST_FILE_NAME || name == LEGACY_TDF_MANIFEST_FILE_NAME {
if !saw_index0 {
saw_index0 = true;
count += 1;
}
} else if is_manifest_entry_name(&name) {
count += 1;
}
}
count
}
pub fn is_empty(&self) -> bool {
self.len() == 0
}
pub fn by_index(&mut self) -> Result<TdfEntry<'_>, TdfError> {
self.get_entry(0)
}
fn has_member(&self, name: &str) -> bool {
self.zip_archive.index_for_name(name).is_some()
}
pub fn get_entry(&mut self, index: usize) -> Result<TdfEntry<'_>, TdfError> {
let (primary, legacy) = manifest_entry_name_for_index(index);
let manifest_name = if self.has_member(&primary) {
primary.clone()
} else if let Some(l) = legacy.filter(|l| self.has_member(l)) {
l
} else {
return Err(TdfError::InvalidStructure {
reason: format!("Missing manifest file: {}", primary),
expected: Some(format!(
"TDF archive should contain {} (or legacy {})",
TDF_MANIFEST_FILE_NAME, LEGACY_TDF_MANIFEST_FILE_NAME
)),
});
};
let manifest: TdfManifest = {
let manifest_file = self.zip_archive.by_name(&manifest_name)?;
let declared_size = manifest_file.size();
let manifest_bytes = read_member_bounded(
manifest_file,
&manifest_name,
declared_size,
self.max_manifest_size,
)?;
serde_json::from_slice(&manifest_bytes)?
};
let payload_name = payload_entry_name_for(&manifest, index)?;
let payload = {
let payload_file = self.zip_archive.by_name(&payload_name).map_err(|_| {
TdfError::InvalidStructure {
reason: format!("Missing payload file: {payload_name:?}"),
expected: Some(
"TDF archive should contain the member named by manifest.payload.url"
.to_string(),
),
}
})?;
let declared_size = payload_file.size();
read_member_bounded(
payload_file,
&payload_name,
declared_size,
self.max_payload_size,
)?
};
Ok(TdfEntry {
manifest,
payload,
index,
_lifetime: std::marker::PhantomData,
})
}
pub fn validate(&mut self) -> Result<(), TdfError> {
for i in 0..self.len() {
self.get_entry(i)?;
}
Ok(())
}
}
pub struct TdfArchiveBuilder {
writer: ZipWriter<File>,
}
impl TdfArchiveBuilder {
pub fn new<P: AsRef<Path>>(path: P) -> io::Result<Self> {
let file = File::create(path)?;
Ok(Self {
writer: ZipWriter::new(file),
})
}
pub fn add_entry(
&mut self,
manifest: &TdfManifest,
payload: &[u8],
index: usize,
) -> Result<(), TdfError> {
let manifest_json = manifest.to_json()?;
let (manifest_name, _) = manifest_entry_name_for_index(index);
let payload_name = payload_entry_name_for(manifest, index)?;
self.writer.start_file::<_, ()>(
manifest_name,
FileOptions::default().compression_method(zip::CompressionMethod::Stored),
)?;
self.writer.write_all(manifest_json.as_bytes())?;
self.writer.start_file::<_, ()>(
payload_name,
FileOptions::default().compression_method(zip::CompressionMethod::Stored),
)?;
self.writer.write_all(payload)?;
Ok(())
}
pub fn add_entry_with_segments(
&mut self,
manifest: &TdfManifest,
segments: &[Vec<u8>],
index: usize,
) -> Result<(), TdfError> {
let manifest_json = manifest.to_json()?;
let (manifest_name, _) = manifest_entry_name_for_index(index);
let payload_name = payload_entry_name_for(manifest, index)?;
self.writer.start_file::<_, ()>(
manifest_name,
FileOptions::default().compression_method(zip::CompressionMethod::Stored),
)?;
self.writer.write_all(manifest_json.as_bytes())?;
self.writer.start_file::<_, ()>(
payload_name,
FileOptions::default().compression_method(zip::CompressionMethod::Stored),
)?;
for segment in segments {
self.writer.write_all(segment)?;
}
Ok(())
}
pub fn finish(self) -> Result<u64, TdfError> {
let result = self.writer.finish()?;
Ok(result.metadata()?.len())
}
}
pub struct TdfArchiveMemoryBuilder {
writer: ZipWriter<io::Cursor<Vec<u8>>>,
}
impl TdfArchiveMemoryBuilder {
pub fn new() -> Self {
Self {
writer: ZipWriter::new(io::Cursor::new(Vec::new())),
}
}
pub fn add_entry(
&mut self,
manifest: &TdfManifest,
payload: &[u8],
index: usize,
) -> Result<(), TdfError> {
let manifest_json = manifest.to_json()?;
let (manifest_name, _) = manifest_entry_name_for_index(index);
let payload_name = payload_entry_name_for(manifest, index)?;
self.writer.start_file::<_, ()>(
manifest_name,
FileOptions::default().compression_method(zip::CompressionMethod::Stored),
)?;
self.writer.write_all(manifest_json.as_bytes())?;
self.writer.start_file::<_, ()>(
payload_name,
FileOptions::default().compression_method(zip::CompressionMethod::Stored),
)?;
self.writer.write_all(payload)?;
Ok(())
}
pub fn add_entry_with_segments(
&mut self,
manifest: &TdfManifest,
segments: &[Vec<u8>],
index: usize,
) -> Result<(), TdfError> {
let manifest_json = manifest.to_json()?;
let (manifest_name, _) = manifest_entry_name_for_index(index);
let payload_name = payload_entry_name_for(manifest, index)?;
self.writer.start_file::<_, ()>(
manifest_name,
FileOptions::default().compression_method(zip::CompressionMethod::Stored),
)?;
self.writer.write_all(manifest_json.as_bytes())?;
self.writer.start_file::<_, ()>(
payload_name,
FileOptions::default().compression_method(zip::CompressionMethod::Stored),
)?;
for segment in segments {
self.writer.write_all(segment)?;
}
Ok(())
}
pub fn finish(self) -> Result<Vec<u8>, TdfError> {
let cursor = self.writer.finish()?;
Ok(cursor.into_inner())
}
}
impl Default for TdfArchiveMemoryBuilder {
fn default() -> Self {
Self::new()
}
}
#[cfg(test)]
mod tests {
use super::*;
use std::io::{Cursor, Write};
use tempfile::NamedTempFile;
use zip::write::FileOptions;
fn manifest_with_url(url: &str) -> TdfManifest {
TdfManifest::new(url.to_string(), "http://kas.example.com".to_string())
}
fn create_test_archive() -> Result<Vec<u8>, TdfError> {
let manifest = manifest_with_url("0.payload");
let payload = b"test payload data".to_vec();
let temp_file = NamedTempFile::new()?;
let mut builder = TdfArchiveBuilder::new(temp_file.path())?;
builder.add_entry(&manifest, &payload, 0)?;
builder.finish()?;
Ok(std::fs::read(temp_file.path())?)
}
fn raw_zip(members: &[(&str, &[u8])]) -> Vec<u8> {
let mut w = ZipWriter::new(Cursor::new(Vec::new()));
for (name, data) in members {
w.start_file::<_, ()>(
*name,
FileOptions::default().compression_method(zip::CompressionMethod::Stored),
)
.unwrap();
w.write_all(data).unwrap();
}
w.finish().unwrap().into_inner()
}
fn names_of(bytes: &[u8]) -> Vec<String> {
let mut z = ZipArchive::new(Cursor::new(bytes.to_vec())).unwrap();
(0..z.len())
.map(|i| z.by_index(i).unwrap().name().unwrap().into_owned())
.collect()
}
#[test]
fn decrypts_segmented_tdf_whose_segments_omit_sizes() -> Result<(), TdfError> {
use crate::manifest::IntegrityInformationExt;
const SEGMENT: usize = 64;
let plaintext: Vec<u8> = (0..(SEGMENT * 3) as u32).map(|i| i as u8).collect();
let enc = TdfEncryption::new().expect("encryption context");
let segmented = enc
.encrypt_with_segments(&plaintext, SEGMENT)
.expect("segment encrypt");
assert_eq!(segmented.segment_info.len(), 3);
let mut manifest = manifest_with_url("0.payload");
manifest.encryption_information.method.iv = String::new();
{
let integrity = &mut manifest.encryption_information.integrity_information;
let first = &segmented.segment_info[0];
integrity.segment_size_default = first.plaintext_size;
integrity.encrypted_segment_size_default = first.encrypted_size;
integrity
.generate_root_signature(&segmented.gmac_tags, enc.payload_key())
.expect("root signature");
}
for seg in &segmented.segment_info {
manifest.add_segment(seg.hash.clone(), None, None);
}
let v: serde_json::Value = serde_json::from_str(&manifest.to_json()?)?;
let seg0 = &v["encryptionInformation"]["integrityInformation"]["segments"][0];
assert!(seg0.get("segmentSize").is_none(), "{seg0}");
assert!(seg0.get("encryptedSegmentSize").is_none(), "{seg0}");
let mut builder = TdfArchiveMemoryBuilder::new();
builder.add_entry_with_segments(&manifest, &segmented.segments, 0)?;
let bytes = builder.finish()?;
let mut archive = TdfArchive::new(Cursor::new(bytes))?;
let entry = archive.by_index()?;
let decrypted = entry.decrypt_with_key(enc.payload_key())?;
assert_eq!(decrypted, plaintext);
Ok(())
}
#[test]
fn builder_writes_spec_manifest_name_and_payload_from_url() -> Result<(), TdfError> {
let bytes = create_test_archive()?;
let names = names_of(&bytes);
assert!(names.contains(&"manifest.json".to_string()), "{names:?}");
assert!(!names.contains(&"0.manifest.json".to_string()), "{names:?}");
assert!(names.contains(&"0.payload".to_string()), "{names:?}");
Ok(())
}
#[test]
fn builder_payload_entry_follows_manifest_url() -> Result<(), TdfError> {
let temp_file = NamedTempFile::new()?;
let mut builder = TdfArchiveBuilder::new(temp_file.path())?;
builder.add_entry(&manifest_with_url("data.bin"), b"abc", 0)?;
builder.finish()?;
let bytes = std::fs::read(temp_file.path())?;
assert_eq!(names_of(&bytes), vec!["manifest.json", "data.bin"]);
let mut archive = TdfArchive::new(Cursor::new(bytes))?;
assert_eq!(archive.by_index()?.payload, b"abc");
Ok(())
}
#[test]
fn memory_builder_matches_file_builder_names() -> Result<(), TdfError> {
let mut b = TdfArchiveMemoryBuilder::new();
b.add_entry(&manifest_with_url("0.payload"), b"x", 0)?;
let bytes = b.finish()?;
assert_eq!(names_of(&bytes), vec!["manifest.json", "0.payload"]);
Ok(())
}
#[test]
fn reader_accepts_legacy_manifest_name() -> Result<(), TdfError> {
let m = manifest_with_url("0.payload").to_json()?;
let bytes = raw_zip(&[("0.manifest.json", m.as_bytes()), ("0.payload", b"legacy")]);
let mut archive = TdfArchive::new(Cursor::new(bytes))?;
assert_eq!(archive.len(), 1);
assert_eq!(archive.by_index()?.payload, b"legacy");
Ok(())
}
#[test]
fn reader_prefers_spec_manifest_name_when_both_present() -> Result<(), TdfError> {
let spec = manifest_with_url("a").to_json()?;
let legacy = manifest_with_url("b").to_json()?;
let bytes = raw_zip(&[
("0.manifest.json", legacy.as_bytes()),
("manifest.json", spec.as_bytes()),
("a", b"A"),
("b", b"B"),
]);
let mut archive = TdfArchive::new(Cursor::new(bytes))?;
assert_eq!(archive.by_index()?.payload, b"A");
Ok(())
}
#[test]
fn reader_falls_back_to_0_payload_when_url_empty() -> Result<(), TdfError> {
let m = manifest_with_url("").to_json()?;
let bytes = raw_zip(&[("manifest.json", m.as_bytes()), ("0.payload", b"fb")]);
let mut archive = TdfArchive::new(Cursor::new(bytes))?;
assert_eq!(archive.by_index()?.payload, b"fb");
Ok(())
}
#[test]
fn reader_errors_when_url_names_missing_entry() -> Result<(), TdfError> {
let m = manifest_with_url("missing.bin").to_json()?;
let bytes = raw_zip(&[("manifest.json", m.as_bytes()), ("0.payload", b"x")]);
let mut archive = TdfArchive::new(Cursor::new(bytes))?;
let err = archive.by_index().unwrap_err();
assert!(err.to_string().contains("missing.bin"), "{err}");
Ok(())
}
#[test]
fn reader_rejects_unsafe_payload_url() -> Result<(), TdfError> {
for bad in ["../x", "/abs", "a\\b", "x/../y"] {
let m = manifest_with_url(bad).to_json()?;
let bytes = raw_zip(&[("manifest.json", m.as_bytes())]);
let mut archive = TdfArchive::new(Cursor::new(bytes))?;
let err = archive.by_index().unwrap_err();
assert!(err.to_string().contains("unsafe"), "{bad}: {err}");
}
Ok(())
}
#[test]
fn reader_rejects_payload_url_shaped_like_manifest_entry() -> Result<(), TdfError> {
let m = manifest_with_url("2.manifest.json").to_json()?;
let bytes = raw_zip(&[("manifest.json", m.as_bytes())]);
let mut archive = TdfArchive::new(Cursor::new(bytes))?;
let err = archive.by_index().unwrap_err();
assert!(err.to_string().contains("manifest"), "{err}");
Ok(())
}
#[test]
fn builder_rejects_payload_url_shaped_like_manifest_entry() -> Result<(), TdfError> {
let temp_file = NamedTempFile::new()?;
let mut builder = TdfArchiveBuilder::new(temp_file.path())?;
let err = builder
.add_entry(&manifest_with_url("2.manifest.json"), b"x", 0)
.unwrap_err();
assert!(err.to_string().contains("manifest"), "{err}");
let bytes = {
builder.finish()?;
std::fs::read(temp_file.path())?
};
assert!(names_of(&bytes).is_empty(), "{:?}", names_of(&bytes));
Ok(())
}
#[test]
fn len_counts_manifests_not_members() -> Result<(), TdfError> {
let m = manifest_with_url("0.payload").to_json()?;
let bytes = raw_zip(&[
("manifest.json", m.as_bytes()),
("0.payload", b"x"),
("extra.txt", b"y"),
]);
let mut archive = TdfArchive::new(Cursor::new(bytes))?;
assert_eq!(archive.len(), 1);
archive.validate()?;
Ok(())
}
#[test]
fn test_tdf_archive_validation() -> Result<(), TdfError> {
let mut archive = TdfArchive::new(Cursor::new(create_test_archive()?))?;
archive.validate()?;
Ok(())
}
#[test]
fn test_get_entry_multi_index_keeps_indexed_names() -> Result<(), Box<dyn std::error::Error>> {
let entries = [
(
manifest_with_url("0.payload"),
b"first payload data".to_vec(),
),
(
manifest_with_url("1.payload"),
b"second payload data".to_vec(),
),
];
let temp_file = NamedTempFile::new()?;
let temp_path = temp_file.path().to_owned();
let mut builder = TdfArchiveBuilder::new(&temp_path)?;
for (index, (manifest, payload)) in entries.iter().enumerate() {
builder.add_entry(manifest, payload, index)?;
}
builder.finish()?;
let bytes = std::fs::read(&temp_path)?;
assert_eq!(
names_of(&bytes),
vec!["manifest.json", "0.payload", "1.manifest.json", "1.payload"]
);
let mut archive = TdfArchive::open(&temp_path)?;
assert_eq!(archive.len(), 2);
assert_eq!(archive.get_entry(0)?.payload, b"first payload data");
assert_eq!(archive.get_entry(1)?.payload, b"second payload data");
assert!(archive.get_entry(2).is_err());
Ok(())
}
fn segmented_tdf(tamper: impl FnOnce(&mut TdfManifest)) -> (Vec<u8>, Vec<u8>, Vec<u8>) {
use crate::manifest::IntegrityInformationExt;
const SEGMENT: usize = 64;
let plaintext: Vec<u8> = (0..(SEGMENT * 3) as u32).map(|i| i as u8).collect();
let enc = TdfEncryption::new().expect("encryption context");
let segmented = enc
.encrypt_with_segments(&plaintext, SEGMENT)
.expect("segment encrypt");
let mut manifest = manifest_with_url("0.payload");
manifest.encryption_information.method.iv = String::new();
{
let integrity = &mut manifest.encryption_information.integrity_information;
let first = &segmented.segment_info[0];
integrity.segment_size_default = first.plaintext_size;
integrity.encrypted_segment_size_default = first.encrypted_size;
integrity
.generate_root_signature(&segmented.gmac_tags, enc.payload_key())
.expect("root signature");
}
for seg in &segmented.segment_info {
manifest.add_segment(
seg.hash.clone(),
Some(seg.plaintext_size),
Some(seg.encrypted_size),
);
}
tamper(&mut manifest);
let mut builder = TdfArchiveMemoryBuilder::new();
builder
.add_entry_with_segments(&manifest, &segmented.segments, 0)
.expect("write segmented entry");
(
builder.finish().expect("finish archive"),
enc.payload_key().to_vec(),
plaintext,
)
}
fn flip_first_b64_char(value: &str) -> String {
let mut chars: Vec<char> = value.chars().collect();
assert!(!chars.is_empty(), "empty base64 value");
chars[0] = if chars[0] == 'A' { 'B' } else { 'A' };
chars.into_iter().collect()
}
fn decrypt_error_message(bytes: Vec<u8>, key: &[u8]) -> String {
let mut archive = TdfArchive::new(Cursor::new(bytes)).expect("open archive");
let entry = archive.by_index().expect("read entry");
let err = entry
.decrypt_with_key(key)
.expect_err("decrypt must abort on an integrity failure");
err.to_string()
}
#[test]
fn untampered_segmented_tdf_decrypts() {
let (bytes, key, plaintext) = segmented_tdf(|_| {});
let mut archive = TdfArchive::new(Cursor::new(bytes)).expect("open archive");
let entry = archive.by_index().expect("read entry");
assert_eq!(entry.decrypt_with_key(&key).expect("decrypt"), plaintext);
}
#[test]
fn oversized_declared_plaintext_is_rejected() {
let (bytes, key, _) = segmented_tdf(|manifest| {
let segment = &mut manifest
.encryption_information
.integrity_information
.segments[0];
segment.segment_size = Some(1 << 60);
});
let err = decrypt_error_message(bytes, &key);
assert!(err.contains("integrity"), "{err}");
assert!(err.contains("segment"), "{err}");
}
#[test]
fn legacy_branch_rejects_short_iv_instead_of_panicking() {
let (bytes, key, _) = segmented_tdf(|manifest| {
manifest
.encryption_information
.integrity_information
.segments
.clear();
manifest.encryption_information.method.iv = String::new();
});
let err = decrypt_error_message(bytes, &key);
assert!(err.contains("method.iv"), "{err}");
assert!(err.contains("integrity"), "{err}");
}
#[test]
fn tampered_segment_hash_aborts_decrypt() {
let (bytes, key, _) = segmented_tdf(|manifest| {
let segment = &mut manifest
.encryption_information
.integrity_information
.segments[1];
segment.hash = flip_first_b64_char(&segment.hash);
});
let msg = decrypt_error_message(bytes, &key);
assert!(msg.contains("segment"), "{msg}");
assert!(msg.contains("signature"), "{msg}");
assert!(
msg.to_lowercase().contains("integrity") || msg.to_lowercase().contains("signature"),
"{msg}"
);
}
#[test]
fn tampered_root_signature_aborts_decrypt() {
let (bytes, key, _) = segmented_tdf(|manifest| {
let root = &mut manifest
.encryption_information
.integrity_information
.root_signature;
root.sig = flip_first_b64_char(&root.sig);
});
let msg = decrypt_error_message(bytes, &key);
assert!(msg.contains("root"), "{msg}");
assert!(
msg.to_lowercase().contains("integrity") || msg.to_lowercase().contains("signature"),
"{msg}"
);
}
fn zip_with_methods(members: &[(&str, &[u8], zip::CompressionMethod)]) -> Vec<u8> {
let mut w = ZipWriter::new(Cursor::new(Vec::new()));
for (name, data, method) in members {
w.start_file::<_, ()>(*name, FileOptions::default().compression_method(*method))
.unwrap();
w.write_all(data).unwrap();
}
w.finish().unwrap().into_inner()
}
fn by_index_error(
bytes: Vec<u8>,
configure: impl FnOnce(TdfArchive<Cursor<Vec<u8>>>) -> TdfArchive<Cursor<Vec<u8>>>,
) -> TdfError {
let mut archive = configure(TdfArchive::new(Cursor::new(bytes)).expect("open archive"));
archive
.by_index()
.expect_err("the entry must be refused, not read")
}
const DEFLATED: zip::CompressionMethod = zip::CompressionMethod::Deflated;
const STORED: zip::CompressionMethod = zip::CompressionMethod::Stored;
#[test]
fn new_reader_uses_the_documented_default_limits() -> Result<(), TdfError> {
let archive = TdfArchive::new(Cursor::new(create_test_archive()?))?;
assert_eq!(archive.max_manifest_size(), DEFAULT_MAX_MANIFEST_SIZE);
assert_eq!(archive.max_payload_size(), DEFAULT_MAX_PAYLOAD_SIZE);
let archive = archive
.with_max_manifest_size(1234)
.with_max_payload_size(5678);
assert_eq!(archive.max_manifest_size(), 1234);
assert_eq!(archive.max_payload_size(), 5678);
Ok(())
}
#[test]
fn deflated_manifest_over_the_default_limit_is_refused() -> Result<(), TdfError> {
let mut manifest = manifest_with_url("0.payload").to_json()?.into_bytes();
manifest.resize(DEFAULT_MAX_MANIFEST_SIZE as usize + 1, b' ');
let bytes = zip_with_methods(&[
("manifest.json", &manifest, DEFLATED),
("0.payload", b"x", STORED),
]);
assert!(
(bytes.len() as u64) < DEFAULT_MAX_MANIFEST_SIZE / 100,
"the archive must be tiny next to what it inflates to: {} bytes",
bytes.len()
);
let err = by_index_error(bytes, |archive| archive);
assert!(
matches!(
&err,
TdfError::MemberTooLarge { member, limit }
if member == "manifest.json" && *limit == DEFAULT_MAX_MANIFEST_SIZE
),
"{err:?}"
);
assert_eq!(err.error_code(), "OPENTDF_E_ARCHIVE_MEMBER_TOO_LARGE");
assert!(!err.is_retryable());
Ok(())
}
#[test]
fn manifest_limit_is_inclusive() -> Result<(), TdfError> {
let manifest = manifest_with_url("0.payload").to_json()?;
let exact = manifest.len() as u64;
for method in [STORED, DEFLATED] {
let bytes = zip_with_methods(&[
("manifest.json", manifest.as_bytes(), method),
("0.payload", b"payload", STORED),
]);
let mut at_limit =
TdfArchive::new(Cursor::new(bytes.clone()))?.with_max_manifest_size(exact);
assert_eq!(at_limit.by_index()?.payload, b"payload");
let err = by_index_error(bytes, |archive| archive.with_max_manifest_size(exact - 1));
assert!(
matches!(
&err,
TdfError::MemberTooLarge { member, limit }
if member == "manifest.json" && *limit == exact - 1
),
"{method:?}: {err:?}"
);
}
Ok(())
}
#[test]
fn deflated_payload_over_a_custom_limit_is_refused() -> Result<(), TdfError> {
const PAYLOAD: usize = 1024 * 1024;
let manifest = manifest_with_url("0.payload").to_json()?;
let payload = vec![0u8; PAYLOAD];
let bytes = zip_with_methods(&[
("manifest.json", manifest.as_bytes(), STORED),
("0.payload", &payload, DEFLATED),
]);
assert!(bytes.len() < PAYLOAD / 100, "{} bytes", bytes.len());
let limit = PAYLOAD as u64 - 1;
let err = by_index_error(bytes.clone(), |archive| {
archive.with_max_payload_size(limit)
});
assert!(
matches!(
&err,
TdfError::MemberTooLarge { member, limit: reported }
if member == "0.payload" && *reported == limit
),
"{err:?}"
);
let mut at_limit =
TdfArchive::new(Cursor::new(bytes.clone()))?.with_max_payload_size(PAYLOAD as u64);
assert_eq!(at_limit.by_index()?.payload, payload);
let mut default_limit = TdfArchive::new(Cursor::new(bytes))?;
assert_eq!(default_limit.by_index()?.payload, payload);
Ok(())
}
#[test]
fn stored_payload_honours_the_limit_and_still_reads() -> Result<(), TdfError> {
let manifest = manifest_with_url("0.payload").to_json()?;
let payload = b"stored payload bytes".to_vec();
let bytes = raw_zip(&[
("manifest.json", manifest.as_bytes()),
("0.payload", &payload),
]);
let exact = payload.len() as u64;
let mut at_limit =
TdfArchive::new(Cursor::new(bytes.clone()))?.with_max_payload_size(exact);
assert_eq!(at_limit.by_index()?.payload, payload);
let err = by_index_error(bytes.clone(), |archive| {
archive.with_max_payload_size(exact - 1)
});
assert!(
matches!(&err, TdfError::MemberTooLarge { member, .. } if member == "0.payload"),
"{err:?}"
);
let mut archive = TdfArchive::new(Cursor::new(bytes))?.with_max_payload_size(exact - 1);
assert!(matches!(
archive.validate(),
Err(TdfError::MemberTooLarge { .. })
));
Ok(())
}
#[test]
fn bounded_read_does_not_trust_the_declared_size() {
let endless = io::repeat(0xAB);
let err = read_member_bounded(endless, "liar", 0, 4096)
.expect_err("an endless member must be refused");
assert!(
matches!(&err, TdfError::MemberTooLarge { member, limit } if member == "liar" && *limit == 4096),
"{err:?}"
);
struct MustNotRead;
impl Read for MustNotRead {
fn read(&mut self, _: &mut [u8]) -> io::Result<usize> {
panic!("an over-limit declared size must be refused without reading");
}
}
assert!(matches!(
read_member_bounded(MustNotRead, "big", 4097, 4096),
Err(TdfError::MemberTooLarge { .. })
));
let all = read_member_bounded(&b"abc"[..], "small", 3, u64::MAX).expect("unbounded read");
assert_eq!(all, b"abc");
}
fn forge_central_directory_sizes(archive: &mut [u8], size: u32) {
const CENTRAL_HEADER_SIGNATURE: &[u8] = b"PK\x01\x02";
let header = archive
.windows(CENTRAL_HEADER_SIGNATURE.len())
.position(|window| window == CENTRAL_HEADER_SIGNATURE)
.expect("central directory header");
archive[header + 20..header + 24].copy_from_slice(&size.to_le_bytes());
archive[header + 24..header + 28].copy_from_slice(&size.to_le_bytes());
}
#[test]
fn member_index_rejects_a_member_larger_than_the_archive() {
let mut bytes = raw_zip(&[("header", &[7u8; 64])]);
let index = TdfMemberIndex::open(Cursor::new(bytes.clone())).expect("honest archive");
assert_eq!(index.get("header").map(|loc| loc.size), Some(64));
forge_central_directory_sizes(&mut bytes, 0x7FFF_FFFF);
let err = TdfMemberIndex::open(Cursor::new(bytes))
.expect_err("a member range past the end of the archive must be refused");
assert!(matches!(err, TdfError::InvalidStructure { .. }), "{err:?}");
}
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct TdfMemberLocation {
pub data_start: u64,
pub size: u64,
}
pub struct TdfMultiEntryBuilder {
writer: ZipWriter<File>,
}
impl TdfMultiEntryBuilder {
pub fn new<P: AsRef<Path>>(path: P) -> io::Result<Self> {
Ok(Self {
writer: ZipWriter::new(File::create(path)?),
})
}
fn options(len: u64) -> SimpleFileOptions {
FileOptions::default()
.compression_method(zip::CompressionMethod::Stored)
.large_file(len > u64::from(u32::MAX))
}
pub fn add_member(&mut self, name: &str, bytes: &[u8]) -> Result<(), TdfError> {
self.writer
.start_file::<_, ()>(name, Self::options(bytes.len() as u64))?;
self.writer.write_all(bytes)?;
Ok(())
}
pub fn finish_with_manifest(
mut self,
name: &str,
manifest: &TdfManifest,
) -> Result<u64, TdfError> {
let json = manifest.to_json()?;
self.writer
.start_file::<_, ()>(name, Self::options(json.len() as u64))?;
self.writer.write_all(json.as_bytes())?;
let file = self.writer.finish()?;
Ok(file.metadata()?.len())
}
}
#[derive(Debug, Clone)]
pub struct TdfMemberIndex {
entries: std::collections::HashMap<String, TdfMemberLocation>,
max_member_size: u64,
max_manifest_size: u64,
}
impl Default for TdfMemberIndex {
fn default() -> Self {
Self {
entries: std::collections::HashMap::new(),
max_member_size: DEFAULT_MAX_PAYLOAD_SIZE,
max_manifest_size: DEFAULT_MAX_MANIFEST_SIZE,
}
}
}
impl TdfMemberIndex {
pub fn open<R: Read + Seek>(mut reader: R) -> Result<Self, TdfError> {
let archive_len = reader.seek(io::SeekFrom::End(0))?;
let mut zip = ZipArchive::new(reader)?;
let mut entries = std::collections::HashMap::with_capacity(zip.len());
for i in 0..zip.len() {
let entry = zip.by_index(i)?;
let name = entry.name()?.into_owned();
if entry.compression() != zip::CompressionMethod::Stored {
return Err(TdfError::InvalidStructure {
reason: format!("member '{name}' is not Stored"),
expected: Some("compression method 0".to_string()),
});
}
let data_start = entry
.data_start()
.ok_or_else(|| TdfError::InvalidStructure {
reason: format!("member '{name}' has no data offset"),
expected: Some("a readable local header".to_string()),
})?;
let size = entry.size();
let in_archive = data_start
.checked_add(size)
.is_some_and(|data_end| data_end <= archive_len);
if !in_archive {
return Err(TdfError::InvalidStructure {
reason: format!(
"member '{name}' declares {size} bytes at offset {data_start}, \
past the end of the {archive_len}-byte archive"
),
expected: Some("a member whose data lies inside the archive".to_string()),
});
}
entries.insert(name, TdfMemberLocation { data_start, size });
}
Ok(Self {
entries,
..Self::default()
})
}
#[must_use]
pub fn with_max_member_size(mut self, limit: u64) -> Self {
self.max_member_size = limit;
self
}
#[must_use]
pub fn with_max_manifest_size(mut self, limit: u64) -> Self {
self.max_manifest_size = limit;
self
}
pub fn max_member_size(&self) -> u64 {
self.max_member_size
}
pub fn max_manifest_size(&self) -> u64 {
self.max_manifest_size
}
pub fn read_member<R: Read + Seek>(
&self,
reader: &mut R,
name: &str,
) -> Result<Vec<u8>, TdfError> {
let mut buf = Vec::new();
self.read_into(reader, name, &mut buf)?;
Ok(buf)
}
pub fn read_into<R: Read + Seek>(
&self,
reader: &mut R,
name: &str,
buf: &mut Vec<u8>,
) -> Result<(), TdfError> {
self.read_bounded_into(reader, name, self.max_member_size, buf)
}
pub fn read_manifest<R: Read + Seek>(&self, reader: &mut R) -> Result<TdfManifest, TdfError> {
let name = [TDF_MANIFEST_FILE_NAME, LEGACY_TDF_MANIFEST_FILE_NAME]
.into_iter()
.find(|name| self.contains(name))
.ok_or_else(|| TdfError::InvalidStructure {
reason: format!("Missing manifest file: {TDF_MANIFEST_FILE_NAME}"),
expected: Some(format!(
"TDF archive should contain {TDF_MANIFEST_FILE_NAME} (or legacy {LEGACY_TDF_MANIFEST_FILE_NAME})"
)),
})?;
let mut bytes = Vec::new();
self.read_bounded_into(reader, name, self.max_manifest_size, &mut bytes)?;
Ok(serde_json::from_slice(&bytes)?)
}
fn read_bounded_into<R: Read + Seek>(
&self,
reader: &mut R,
name: &str,
limit: u64,
buf: &mut Vec<u8>,
) -> Result<(), TdfError> {
buf.clear();
let location = self.get(name).ok_or_else(|| TdfError::InvalidStructure {
reason: format!("Missing member: {name:?}"),
expected: Some("a member with this exact name in the archive".to_string()),
})?;
let too_large = || TdfError::MemberTooLarge {
member: name.to_string(),
limit,
};
if location.size > limit {
return Err(too_large());
}
let len = usize::try_from(location.size).map_err(|_| too_large())?;
reader.seek(io::SeekFrom::Start(location.data_start))?;
buf.resize(len, 0);
if let Err(e) = reader.read_exact(buf) {
buf.clear();
return Err(e.into());
}
Ok(())
}
pub fn get(&self, name: &str) -> Option<TdfMemberLocation> {
self.entries.get(name).copied()
}
pub fn contains(&self, name: &str) -> bool {
self.entries.contains_key(name)
}
pub fn len(&self) -> usize {
self.entries.len()
}
pub fn is_empty(&self) -> bool {
self.entries.is_empty()
}
}