From 27042ce6375d02ba1d5d9c7ccdcfe754c32f949c Mon Sep 17 00:00:00 2001 From: Dietmar Maurer Date: Sat, 22 Jun 2019 15:45:36 +0200 Subject: [PATCH] src/backup/file_formats.rs: improve docs --- src/backup/data_blob.rs | 18 ------------------ src/backup/data_chunk.rs | 15 --------------- src/backup/file_formats.rs | 39 ++++++++++++++++++++++++++++++++++++++ 3 files changed, 39 insertions(+), 33 deletions(-) diff --git a/src/backup/data_blob.rs b/src/backup/data_blob.rs index 3bf00923..f21f212d 100644 --- a/src/backup/data_blob.rs +++ b/src/backup/data_blob.rs @@ -13,24 +13,6 @@ use super::*; /// them on disk or transfer them over the network. Please use index /// files to store large data files (".fidx" of ".didx"). /// -/// The format start with a 8 byte magic number to identify the type, -/// followed by a 4 byte CRC. This CRC is used on the server side to -/// detect file corruption (computed when upload data), so there is -/// usually no need to compute it on the client side. -/// -/// Encrypted blobs contain a 16 byte IV, followed by a 16 byte AD -/// tag, followed by the encrypted data: -/// -/// (MAGIC || CRC32 || IV || TAG || EncryptedData). -/// -/// Unencrypted blobs simply contain the CRC, followed by the -/// (compressed) data. -/// -/// (MAGIC || CRC32 || Data) -/// -/// This is basically the same format we use for ``DataChunk``, but -/// with other magic numbers so that we can distinguish them. - pub struct DataBlob { raw_data: Vec, // tagged, compressed, encryped data } diff --git a/src/backup/data_chunk.rs b/src/backup/data_chunk.rs index 301da925..e61df592 100644 --- a/src/backup/data_chunk.rs +++ b/src/backup/data_chunk.rs @@ -18,21 +18,6 @@ pub struct ChunkInfo { /// compressed and encrypted. A simply binary format is used to store /// them on disk or transfer them over the network. /// -/// The format start with a 8 byte magic number to identify the type, -/// followed by a 4 byte CRC. This CRC is used on the server side to -/// detect file corruption (computed when upload data), so there is -/// usually no need to compute it on the client side. -/// -/// Encrypted chunks contain a 16 byte IV, followed by a 16 byte AD -/// tag, followed by the encrypted data: -/// -/// (MAGIC || CRC32 || IV || TAG || EncryptedData). -/// -/// Unencrypted blobs simply contain the CRC, followed by the -/// (compressed) data. -/// -/// (MAGIC || CRC32 || Data) -/// /// Please use the ``DataChunkBuilder`` to create new instances. pub struct DataChunk { digest: [u8; 32], diff --git a/src/backup/file_formats.rs b/src/backup/file_formats.rs index c9ecb4ac..3038b039 100644 --- a/src/backup/file_formats.rs +++ b/src/backup/file_formats.rs @@ -30,12 +30,33 @@ pub static FIXED_SIZED_CHUNK_INDEX_1_0: [u8; 8] = [47, 127, 65, 237, 145, 253, 1 // openssl::sha::sha256(b"Proxmox Backup dynamic sized chunk index v1.0")[0..8] pub static DYNAMIC_SIZED_CHUNK_INDEX_1_0: [u8; 8] = [28, 145, 78, 165, 25, 186, 179, 205]; +/// Data blob binary storage format +/// +/// The format start with a 8 byte magic number to identify the type, +/// followed by a 4 byte CRC. This CRC is used on the server side to +/// detect file corruption (computed when upload data), so there is +/// usually no need to compute it on the client side. +/// +/// Unencrypted blobs simply contain the CRC, followed by the +/// (compressed) data. +/// +/// (MAGIC || CRC32 || Data) +/// +/// This is basically the same format we use for chunks, but +/// with other magic numbers so that we can distinguish them. #[repr(C,packed)] pub struct DataBlobHeader { pub magic: [u8; 8], pub crc: [u8; 4], } +/// Encrypted data blob binary storage format +/// +/// The ``DataBlobHeader`` for encrypted blobs additionally contains +/// a 16 byte IV, followed by a 16 byte Authenticated Encyrypten (AE) +/// tag, followed by the encrypted data: +/// +/// (MAGIC || CRC32 || IV || TAG || EncryptedData). #[repr(C,packed)] pub struct EncryptedDataBlobHeader { pub head: DataBlobHeader, @@ -43,12 +64,30 @@ pub struct EncryptedDataBlobHeader { pub tag: [u8; 16], } +/// Data chunk binary storage format +/// +/// The format start with a 8 byte magic number to identify the type, +/// followed by a 4 byte CRC. This CRC is used on the server side to +/// detect file corruption (computed when upload data), so there is +/// usually no need to compute it on the client side. +/// +/// Unencrypted blobs simply contain the CRC, followed by the +/// (compressed) data. +/// +/// (MAGIC || CRC32 || Data) #[repr(C,packed)] pub struct DataChunkHeader { pub magic: [u8; 8], pub crc: [u8; 4], } +/// Encrypted Data chunk binary storage format +/// +/// The ``DataChunkHeader`` for encrypted chunks additionally contains +/// a 16 byte IV, followed by a 16 byte Authenticated Encyrypten (AE) +/// tag, followed by the encrypted data: +/// +/// (MAGIC || CRC32 || IV || TAG || EncryptedData). #[repr(C,packed)] pub struct EncryptedDataChunkHeader { pub head: DataChunkHeader,