Gpeacock/embed_remote_settings (contentauth#460)

* Change settings Manifest to Builder.
* Ensure sign to stream respects options.
* add missing writer for c2pa_io.
* Add streaming bmff and streaming remote_url support.
* PR feedback fixes.

Author: gpeacock

V2_API_NOTES.md renamed to 2024_API_NOTES.md

@@ -1,4 +1,4 @@
-## V2 API Notes
+## 2024 API Notes
 
 ### Goals
 Provide a consistent flexible well tested API focusing on core functionality.
@@ -12,7 +12,7 @@ Provide a consistent flexible well tested API focusing on core functionality.
 - Enable builds for cameras and other embedded environments.
 - Provide a consistent model for setting runtime options.
 - Write unit tests, integration tests and documentation for all the v2 APIs.
-- Keep v1 to v2 porting as simple as possible.
+- Keep porting as simple as possible.
 
 
 ### Resource References
@@ -50,6 +50,19 @@ The source asset is the asset that we will hash and sign. It can the output from
 
 If there is no parent ingredient defined, and the source has a manifest store, the sdk will generate a parent ingredient from the parent.
 
+### Remote URLs and embedding
+The default operation of c2pa signing is to embed a c2pa manifest store into an asset.
+We also return the c2pa manifest store so that it can be written to a sidecar or uploaded to a remote service.
+- The API supports embedding a remote url reference into the asset. 
+- The remote URL is stored in different ways depending on the asset, but is often stored in XMP data.
+- The remote URL must be added to the asset before signing so that it can be hashed along with the asset.
+- Not all file formats support embedding remote URLs or embedding manifests stores.
+- If you embed a manifest or a remote URL, a new asset will be created with the new data embedded.
+- If you don't embed, then the original asset is unmodified and there is no need to write one out.
+- The remote url can be set with builder.remote_url.
+- If embedding is not needed, set the builder.no_embed flag to true.
+
+
 ## Testing
 We need a more comprehensive set of tests for the rust codebase.
 

sdk/src/assertions/bmff_hash.rs

@@ -17,7 +17,7 @@ use std::{
     fmt, fs,
     io::{BufReader, Cursor, SeekFrom},
     ops::Deref,
-    path::{Path, PathBuf},
+    path::Path,
 };
 
 use mp4::*;
@@ -37,8 +37,8 @@ use crate::{
     cbor_types::UriT,
     utils::{
         hash_utils::{
-            concat_and_hash, hash_asset_by_alg, hash_stream_by_alg, vec_compare,
-            verify_stream_by_alg, HashRange, Hasher,
+            concat_and_hash, hash_stream_by_alg, vec_compare, verify_stream_by_alg, HashRange,
+            Hasher,
         },
         merkle::C2PAMerkleTree,
     },
@@ -253,9 +253,6 @@ pub struct BmffHash {
     #[serde(skip_serializing)]
     url: Option<UriT>, // deprecated in V2 and not to be used
 
-    #[serde(skip)]
-    pub path: PathBuf,
-
     #[serde(skip)]
     bmff_version: usize,
 }
@@ -271,7 +268,6 @@ impl BmffHash {
             merkle: None,
             name: Some(name.to_string()),
             url,
-            path: PathBuf::new(),
             bmff_version: ASSERTION_CREATION_VERSION,
         }
     }
@@ -326,22 +322,24 @@ impl BmffHash {
     }
 
     /// Generate the hash value for the asset using the range from the BmffHash.
-    pub fn gen_hash(&mut self, asset_path: &Path) -> crate::error::Result<()> {
-        self.hash = Some(ByteBuf::from(self.hash_from_asset(asset_path)?));
-        self.path = PathBuf::from(asset_path);
+    pub fn gen_hash_from_stream(&mut self, stream: &mut dyn CAIRead) -> crate::error::Result<()> {
+        self.hash = Some(ByteBuf::from(self.hash_from_stream(stream)?));
+        //self.path = PathBuf::from(asset_path);
         Ok(())
     }
 
-    /// Generate the hash again.
-    pub fn regen_hash(&mut self) -> crate::error::Result<()> {
-        let p = self.path.clone();
-        self.hash = Some(ByteBuf::from(self.hash_from_asset(p.as_path())?));
+    /// Generate the hash value for the asset using the range from the BmffHash.
+    #[cfg(feature = "file_io")]
+    pub fn gen_hash(&mut self, asset_path: &Path) -> crate::error::Result<()> {
+        let mut file = std::fs::File::open(asset_path)?;
+        self.hash = Some(ByteBuf::from(self.hash_from_stream(&mut file)?));
+        //self.path = PathBuf::from(asset_path);
         Ok(())
     }
 
-    /// Generate the asset hash from a file asset using the constructed
+    /// Generate the asset hash from an asset stream using the constructed
     /// start and length values.
-    fn hash_from_asset(&mut self, asset_path: &Path) -> crate::error::Result<Vec<u8>> {
+    fn hash_from_stream(&mut self, stream: &mut dyn CAIRead) -> crate::error::Result<Vec<u8>> {
         if self.is_remote_hash() {
             return Err(Error::BadParam(
                 "asset hash is remote, not yet supported".to_owned(),
@@ -356,11 +354,9 @@ impl BmffHash {
         let bmff_exclusions = &self.exclusions;
 
         // convert BMFF exclusion map to flat exclusion list
-        let mut data = fs::File::open(asset_path)?;
-        let exclusions =
-            bmff_to_jumbf_exclusions(&mut data, bmff_exclusions, self.bmff_version > 1)?;
+        let exclusions = bmff_to_jumbf_exclusions(stream, bmff_exclusions, self.bmff_version > 1)?;
 
-        let hash = hash_asset_by_alg(&alg, asset_path, Some(exclusions))?;
+        let hash = hash_stream_by_alg(&alg, stream, Some(exclusions), true)?;
 
         if hash.is_empty() {
             Err(Error::BadParam("could not generate data hash".to_string()))

sdk/src/asset_handlers/c2pa_io.rs

@@ -120,6 +120,10 @@ impl AssetIO for C2paIO {
         self
     }
 
+    fn get_writer(&self, asset_type: &str) -> Option<Box<dyn CAIWriter>> {
+        Some(Box::new(C2paIO::new(asset_type)))
+    }
+
     fn supported_types(&self) -> &[&str] {
         &SUPPORTED_TYPES
     }

sdk/src/builder.rs

@@ -193,6 +193,12 @@ pub struct Builder {
     #[serde(flatten)]
     pub definition: ManifestDefinition,
 
+    /// Optional remote URL for the manifest
+    pub remote_url: Option<String>,
+
+    // If true, the manifest store will not be embedded in the asset on sign
+    pub no_embed: bool,
+
     /// container for binary assets (like thumbnails)
     #[serde(skip)]
     resources: ResourceStore,
@@ -481,14 +487,15 @@ impl Builder {
             claim.add_claim_generator_info(claim_info);
         }
 
-        // if let Some(remote_op) = &self.remote_manifest {
-        //     match remote_op {
-        //         RemoteManifest::NoRemote => (),
-        //         RemoteManifest::SideCar => claim.set_external_manifest(),
-        //         RemoteManifest::Remote(r) => claim.set_remote_manifest(r)?,
-        //         RemoteManifest::EmbedWithRemote(r) => claim.set_embed_remote_manifest(r)?,
-        //     };
-        // }
+        if let Some(remote_url) = &self.remote_url {
+            if self.no_embed {
+                claim.set_remote_manifest(remote_url)?;
+            } else {
+                claim.set_embed_remote_manifest(remote_url)?;
+            }
+        } else if self.no_embed {
+            claim.set_external_manifest()
+        }
 
         if let Some(title) = definition.title.as_ref() {
             claim.set_title(Some(title.to_owned()));
@@ -657,7 +664,9 @@ impl Builder {
     where
         R: Read + Seek + ?Sized,
     {
-        if self.definition.thumbnail.is_none() {
+        // check settings to see if we should auto generate a thumbnail
+        let auto_thumbnail = crate::settings::get_settings_value::<bool>("builder.auto_thumbnail")?;
+        if self.definition.thumbnail.is_none() && auto_thumbnail {
             stream.rewind()?;
             if let Ok((format, image)) =
                 crate::utils::thumbnail::make_thumbnail_from_stream(format, stream)
@@ -778,7 +787,7 @@ mod tests {
     use wasm_bindgen_test::*;
 
     use super::*;
-    use crate::{manifest_store::ManifestStore, utils::test::temp_signer};
+    use crate::{utils::test::temp_signer, Reader};
     #[cfg(target_arch = "wasm32")]
     wasm_bindgen_test::wasm_bindgen_test_configure!(run_in_browser);
 
@@ -826,6 +835,8 @@ mod tests {
         .to_string()
     }
 
+    #[cfg(not(target_arch = "wasm32"))]
+    const TEST_IMAGE_CLEAN: &[u8] = include_bytes!("../tests/fixtures/IMG_0003.jpg");
     const TEST_IMAGE: &[u8] = include_bytes!("../tests/fixtures/CA.jpg");
 
     #[test]
@@ -951,21 +962,20 @@ mod tests {
         zipped.rewind().unwrap();
         let mut _builder = Builder::from_archive(&mut zipped).unwrap();
 
-        // sign the ManifestStoreBuilder and write it to the output stream
+        // sign and write to the output stream
         let signer = temp_signer();
         builder
             .sign(format, &mut source, &mut dest, signer.as_ref())
             .unwrap();
 
         // read and validate the signed manifest store
         dest.rewind().unwrap();
-        let manifest_store =
-            ManifestStore::from_stream(format, &mut dest, true).expect("from_bytes");
+        let manifest_store = Reader::from_stream(format, &mut dest).expect("from_bytes");
 
         println!("{}", manifest_store);
         assert!(manifest_store.validation_status().is_none());
-        assert!(manifest_store.get_active().is_some());
-        let manifest = manifest_store.get_active().unwrap();
+        assert!(manifest_store.active_manifest().is_some());
+        let manifest = manifest_store.active_manifest().unwrap();
         assert_eq!(manifest.title().unwrap(), "Test_Manifest");
         let test_assertion: TestAssertion = manifest.find_assertion("org.life.meaning").unwrap();
         assert_eq!(test_assertion.answer, 42);
@@ -984,17 +994,17 @@ mod tests {
             .add_resource("thumbnail1.jpg", Cursor::new(TEST_IMAGE))
             .unwrap();
 
-        // sign the ManifestStoreBuilder and write it to the output stream
+        // sign and write to the output stream
         let signer = temp_signer();
         builder.sign_file(source, &dest, signer.as_ref()).unwrap();
 
         // read and validate the signed manifest store
-        let manifest_store = ManifestStore::from_file(&dest).expect("from_bytes");
+        let manifest_store = Reader::from_file(&dest).expect("from_bytes");
 
         println!("{}", manifest_store);
         assert!(manifest_store.validation_status().is_none());
         assert_eq!(
-            manifest_store.get_active().unwrap().title().unwrap(),
+            manifest_store.active_manifest().unwrap().title().unwrap(),
             "Test_Manifest"
         );
     }
@@ -1008,15 +1018,14 @@ mod tests {
             "sample1.webp",
             "TUSCANY.TIF",
             "sample1.svg",
-            //"APC_0808.dng",
             "sample1.wav",
             "test.avi",
-            //"sample1.mp3",
-            //"sample1.avif",
-            //"sample1.heic",
-            //"sample1.heif",
-            //"video1.mp4",
-            //"cloud_manifest.c2pa",
+            "sample1.mp3",
+            "sample1.avif",
+            "sample1.heic",
+            "sample1.heif",
+            "video1.mp4",
+            "cloud_manifest.c2pa",
         ];
         for file_name in TESTFILES {
             let extension = file_name.split('.').last().unwrap();
@@ -1036,21 +1045,23 @@ mod tests {
                 .add_resource("thumbnail1.jpg", Cursor::new(TEST_IMAGE))
                 .unwrap();
 
-            // sign the ManifestStoreBuilder and write it to the output stream
+            // sign and write to the output stream
             let signer = temp_signer();
             builder
                 .sign(format, &mut source, &mut dest, signer.as_ref())
                 .unwrap();
 
             // read and validate the signed manifest store
             dest.rewind().unwrap();
-            let manifest_store =
-                ManifestStore::from_stream(format, &mut dest, true).expect("from_bytes");
+            let manifest_store = Reader::from_stream(format, &mut dest).expect("from_bytes");
 
             println!("{}", manifest_store);
-            assert!(manifest_store.validation_status().is_none());
+            if format != "c2pa" {
+                // c2pa files will not validate since they have no associated asset
+                assert!(manifest_store.validation_status().is_none());
+            }
             assert_eq!(
-                manifest_store.get_active().unwrap().title().unwrap(),
+                manifest_store.active_manifest().unwrap().title().unwrap(),
                 "Test_Manifest"
             );
 
@@ -1091,15 +1102,48 @@ mod tests {
 
         // read and validate the signed manifest store
         dest.rewind().unwrap();
-        let manifest_store =
-            ManifestStore::from_stream(format, &mut dest, true).expect("from_bytes");
+        let manifest_store = Reader::from_stream(format, &mut dest).expect("from_bytes");
 
         println!("{}", manifest_store);
         #[cfg(not(target_arch = "wasm32"))] // skip this until we get wasm async signing working
         assert!(manifest_store.validation_status().is_none());
         assert_eq!(
-            manifest_store.get_active().unwrap().title().unwrap(),
+            manifest_store.active_manifest().unwrap().title().unwrap(),
             "Test_Manifest"
         );
     }
+
+    #[test]
+    #[cfg(not(target_arch = "wasm32"))]
+    fn test_builder_remote_url() {
+        let mut source = Cursor::new(TEST_IMAGE_CLEAN);
+        let mut dest = Cursor::new(Vec::new());
+
+        let mut builder = Builder::from_json(&manifest_json()).unwrap();
+        builder.remote_url = Some("http://my_remote_url".to_string());
+        builder.no_embed = true;
+
+        builder
+            .add_resource("thumbnail1.jpg", Cursor::new(TEST_IMAGE))
+            .unwrap();
+
+        // sign the ManifestStoreBuilder and write it to the output stream
+        let signer = temp_signer();
+        let manifest_data = builder
+            .sign("image/jpeg", &mut source, &mut dest, signer.as_ref())
+            .unwrap();
+
+        // check to make sure we have a remote url and no manifest data
+        dest.set_position(0);
+        let _err = c2pa::Reader::from_stream("image/jpeg", &mut dest).expect_err("from_bytes");
+
+        // now validate the manifest against the written asset
+        dest.set_position(0);
+        let reader =
+            c2pa::Reader::from_manifest_data_and_stream(&manifest_data, "image/jpeg", &mut dest)
+                .expect("from_bytes");
+
+        println!("{}", reader.json());
+        assert!(reader.validation_status().is_none());
+    }
 }

sdk/src/claim.rs

@@ -938,15 +938,13 @@ impl Claim {
     }
 
     // Crate private function to allow for patching a BMFF hash with final contents.
-    #[cfg(feature = "file_io")]
     pub(crate) fn update_bmff_hash(&mut self, bmff_hash: BmffHash) -> Result<()> {
         self.replace_assertion(bmff_hash.to_assertion()?)
     }
 
     // Patch an existing assertion with new contents.
     //
     // `replace_with` should match in name and size of an existing assertion.
-    #[cfg(feature = "file_io")]
     pub(crate) fn replace_assertion(&mut self, replace_with: Assertion) -> Result<()> {
         self.update_assertion(
             replace_with,