ruby-c2pa 0.5.0 → 0.6.0

data/ext/c2pa_native/src/lib.rs

@@ -2,7 +2,7 @@ use std::fs::File;
 use std::io::Cursor;
 use std::path::Path;
 use std::sync::{Arc, RwLock, OnceLock};
-use c2pa::{create_signer, Builder, BuilderIntent, Context, Reader, SigningAlg};
+use c2pa::{create_signer, format_from_path, Builder, BuilderIntent, Context, Reader, SigningAlg};
 use magnus::{function, prelude::*, Error, RString, Ruby};
 
 // ─── Helpers ─────────────────────────────────────────────────────────────────
@@ -19,11 +19,20 @@ use magnus::{function, prelude::*, Error, RString, Ruby};
 //
 // It currently carries defaults. Exposing settings to Ruby is a separate piece
 // of work; this is the seam that makes it possible.
-// The one place this gem departs from c2pa-rs's defaults. c2pa-rs generates
-// thumbnails when the feature is compiled in, scaling to a 1024px long edge —
-// and it upscales, so a 160x120 source gets a 1024x768 "thumbnail" ten times
-// its size. Off unless asked for; Config::to_json always states the choice.
-const DEFAULT_SETTINGS: &str = r#"{"builder":{"thumbnail":{"enabled":false}}}"#;
+// The two places this gem departs from c2pa-rs's defaults; Config::to_json
+// always states both.
+//
+// Thumbnails: c2pa-rs generates them when the feature is compiled in, scaling
+// to a 1024px long edge — and it upscales, so a 160x120 source gets a
+// 1024x768 "thumbnail" ten times its size. Off unless asked for.
+//
+// verify_after_sign: since 0.91 c2pa-rs validates the manifest before writing
+// and refuses an invalid one. The gem's own guard reads the finished output
+// back, which also checks the hashes on the bytes written (upstream's check
+// skips them by default), and honours verify: false for inspecting an invalid
+// file. Running both would read every output twice, so upstream's is off.
+const DEFAULT_SETTINGS: &str =
+    r#"{"builder":{"thumbnail":{"enabled":false}},"verify":{"verify_after_sign":false}}"#;
 
 fn context_slot() -> &'static RwLock<Arc<Context>> {
     static CONTEXT: OnceLock<RwLock<Arc<Context>>> = OnceLock::new();
@@ -189,6 +198,39 @@ fn do_sign_file(source_path: &str, dest_path: &str, request: &SigningRequest) ->
     Ok(())
 }
 
+// Sign without embedding: the asset is hashed as it is, the output carries no
+// manifest, and the manifest store goes to its own file. Hashing the asset
+// unmodified is what makes the pair valid; stripping an embedded manifest out
+// afterwards does not work, because embedding moves offsets elsewhere in the
+// file (chunk offsets in an MP4's moov, for one).
+fn do_sign_file_detached(source_path: &str, dest_path: &str, sidecar_path: &str, request: &SigningRequest)
+    -> Result<(), BoxError> {
+    let signer = build_signer(request.cert_path, request.key_path, request.alg)?;
+
+    let title = Path::new(source_path)
+        .file_name()
+        .and_then(|n| n.to_str())
+        .unwrap_or("unknown");
+    let mut builder = build_builder(request, title)?;
+    builder.set_no_embed(true);
+
+    let format = format_from_path(source_path)
+        .ok_or_else(|| format!("Signing failed: cannot tell the format of '{}' from its extension", source_path))?;
+    let mut source = File::open(source_path)
+        .map_err(|e| format!("Signing failed: cannot open '{}': {}", source_path, e))?;
+    let mut dest = std::fs::OpenOptions::new().read(true).write(true).create_new(true).open(dest_path)
+        .map_err(|e| format!("Signing failed: cannot create '{}': {}", dest_path, e))?;
+
+    let manifest = builder
+        .sign(&*signer, &format, &mut source, &mut dest)
+        .map_err(|e| format!("Signing failed: {}", e))?;
+
+    std::fs::write(sidecar_path, manifest)
+        .map_err(|e| format!("Signing failed: cannot write '{}': {}", sidecar_path, e))?;
+
+    Ok(())
+}
+
 // Sign bytes held in memory. The source is read through a Cursor, and the
 // destination has to be one too: c2pa-rs writes the asset and then seeks back
 // to hash it and patch the manifest in, so a write-only sink will not do.
@@ -219,6 +261,27 @@ fn do_read_file(path: &str) -> Result<String, Box<dyn std::error::Error>> {
     Ok(reader.json())
 }
 
+// A manifest store kept apart from its asset, as a .c2pa sidecar or fetched
+// from a remote URL. The store is validated against the asset's bytes; read
+// on its own, a store's hard binding hashes the store itself and never
+// matches.
+fn do_read_detached(manifest: &[u8], format: &str, asset: impl std::io::Read + std::io::Seek + Send)
+    -> Result<String, BoxError> {
+    let reader = Reader::from_shared_context(&shared_context())
+        .with_manifest_data_and_stream(manifest, format, asset)
+        .map_err(|e| format!("Failed to read detached manifest: {}", e))?;
+    Ok(reader.json())
+}
+
+fn do_read_file_with_manifest(path: &str, manifest_path: &str) -> Result<String, BoxError> {
+    let manifest = std::fs::read(manifest_path)
+        .map_err(|e| format!("Failed to read manifest file '{}': {}", manifest_path, e))?;
+    let format = format_from_path(path)
+        .ok_or_else(|| format!("Failed to read '{}': cannot tell its format from the extension", path))?;
+    let asset = File::open(path).map_err(|e| format!("Failed to open '{}': {}", path, e))?;
+    do_read_detached(&manifest, &format, asset)
+}
+
 // ─── Running without the GVL ──────────────────────────────────────────────────
 //
 // Signing and reading are CPU-bound Rust with no need of the interpreter, so
@@ -290,6 +353,7 @@ fn sign_file(
     manifest_json: Option<String>,
     intent: Option<String>,
     ingredient_files: Option<String>,
+    sidecar: Option<String>,
 ) -> Result<String, Error> {
     let request = SigningRequest {
         cert_path: &cert,
@@ -300,7 +364,11 @@ fn sign_file(
         ingredient_files_json: ingredient_files.as_deref(),
     };
 
-    without_gvl(|| do_sign_file(&source, &dest, &request)).map_err(runtime_error)?;
+    without_gvl(|| match &sidecar {
+        Some(sidecar) => do_sign_file_detached(&source, &dest, sidecar, &request),
+        None => do_sign_file(&source, &dest, &request),
+    })
+    .map_err(runtime_error)?;
     Ok(dest)
 }
 
@@ -346,6 +414,18 @@ fn read_buffer(data: RString, format: Option<String>) -> Result<String, Error> {
     without_gvl(|| do_read_buffer(&bytes, format)).map_err(runtime_error)
 }
 
+fn read_file_with_manifest(path: String, manifest_path: String) -> Result<String, Error> {
+    without_gvl(|| do_read_file_with_manifest(&path, &manifest_path)).map_err(runtime_error)
+}
+
+// Unlike read_buffer, nothing is sniffed from the asset here, so the format
+// is required.
+fn read_buffer_with_manifest(data: RString, format: String, manifest: RString) -> Result<String, Error> {
+    let bytes = unsafe { data.as_slice() }.to_vec();
+    let manifest = unsafe { manifest.as_slice() }.to_vec();
+    without_gvl(|| do_read_detached(&manifest, &format, Cursor::new(bytes))).map_err(runtime_error)
+}
+
 fn configure(settings_json: String) -> Result<(), Error> {
     do_configure(&settings_json).map_err(runtime_error)
 }
@@ -361,10 +441,12 @@ fn init(ruby: &Ruby) -> Result<(), Error> {
     let c2pa = ruby.define_module("C2PA")?;
     let native = c2pa.define_module("Native")?;
 
-    native.define_singleton_method("sign_file", function!(sign_file, 8))?;
+    native.define_singleton_method("sign_file", function!(sign_file, 9))?;
     native.define_singleton_method("sign_buffer", function!(sign_buffer, 8))?;
     native.define_singleton_method("read_file", function!(read_file, 1))?;
     native.define_singleton_method("read_buffer", function!(read_buffer, 2))?;
+    native.define_singleton_method("read_file_with_manifest", function!(read_file_with_manifest, 2))?;
+    native.define_singleton_method("read_buffer_with_manifest", function!(read_buffer_with_manifest, 3))?;
     native.define_singleton_method("configure", function!(configure, 1))?;
     native.define_singleton_method("sdk_version", function!(sdk_version, 0))?;
 

data/lib/c2pa/config.rb

@@ -38,6 +38,26 @@ module C2PA
     # network requests.
     attr_accessor :ocsp_fetch
 
+    # Whether network requests made while reading and validating (remote
+    # manifests, OCSP, timestamps) may follow HTTP redirects.
+    #
+    # c2pa-rs defaults this to true but refuses a redirect to an internal
+    # address, such as loopback, a private network or a cloud metadata
+    # endpoint, because the URL can come from untrusted content. false stops
+    # redirects altogether. Neither setting affects a URL that names an
+    # internal host directly.
+    attr_accessor :allow_redirects
+
+    # Whether signing an MP4, MOV or other BMFF file leaves its /free and /skip
+    # boxes out of the hash. c2pa-rs defaults this to true: those boxes are
+    # padding that tools commonly rewrite after signing, and the specification
+    # allows excluding them. Set false and any later change to them breaks the
+    # signature, like a change to the media itself.
+    #
+    # It affects signing only. The choice is recorded in the signed file, and
+    # readers follow the file whatever their own setting.
+    attr_accessor :exclude_free_and_skip_boxes
+
     # Whether to embed a thumbnail of the asset in its manifest, and of each
     # ingredient supplied as a file.
     #
@@ -66,6 +86,8 @@ module C2PA
       @verify_trust = nil
       @remote_manifest_fetch = nil
       @ocsp_fetch = nil
+      @allow_redirects = nil
+      @exclude_free_and_skip_boxes = nil
       @thumbnails = false
       @thumbnail_size = nil
       @thumbnail_format = nil
@@ -84,7 +106,9 @@ module C2PA
       trust["trust_anchors"] = read_pem(@trust_list)          unless @trust_list.nil?
       trust["allowed_list"] = read_pem(@allowed_certificates) unless @allowed_certificates.nil?
 
-      verify = {}
+      # verify_after_sign is always sent: C2PA.sign runs its own check on the
+      # finished output, so c2pa-rs's pre-write check stays off.
+      verify = { "verify_after_sign" => false }
       verify["verify_trust"] = @verify_trust                   unless @verify_trust.nil?
       verify["remote_manifest_fetch"] = @remote_manifest_fetch unless @remote_manifest_fetch.nil?
       verify["ocsp_fetch"] = @ocsp_fetch                       unless @ocsp_fetch.nil?
@@ -96,9 +120,15 @@ module C2PA
       thumbnail["format"] = @thumbnail_format.to_s.downcase   unless @thumbnail_format.nil?
       thumbnail["quality"] = @thumbnail_quality.to_s.downcase unless @thumbnail_quality.nil?
 
-      settings = { "builder" => { "thumbnail" => thumbnail } }
+      builder = { "thumbnail" => thumbnail }
+      unless @exclude_free_and_skip_boxes.nil?
+        builder["bmff_hash_exclude_free_and_skip_boxes"] = @exclude_free_and_skip_boxes
+      end
+
+      settings = { "builder" => builder }
+      settings["core"] = { "allow_redirects" => @allow_redirects } unless @allow_redirects.nil?
       settings["trust"] = trust unless trust.empty?
-      settings["verify"] = verify unless verify.empty?
+      settings["verify"] = verify
 
       JSON.generate(settings)
     end

data/lib/c2pa/manifest.rb

@@ -75,6 +75,17 @@ module C2PA
               "intent: :edit to C2PA::Manifest.new instead and the action will be added for you."
       end
 
+      # Same limit as c2pa.opened: each entry is a hashed URI that only c2pa-rs
+      # can compute, and in 0.91 its builder does not compute them, only
+      # checks them when reading. A hand-written hash would pass that check
+      # today while claiming a binding nothing verified.
+      if parameters.is_a?(Hash) && (parameters.key?("relatedAssertions") || parameters.key?(:relatedAssertions))
+        raise InvalidManifestError,
+              "relatedAssertions cannot be set. Each entry must be a hashed URI computed over " \
+              "the assertion as c2pa-rs serialises it, and c2pa-rs #{C2PA.sdk_version} does not " \
+              "compute them when building a manifest, so Ruby cannot produce a genuine one."
+      end
+
       # Required as of c2pa-rs 0.90. Earlier versions accepted its absence, so
       # manifests signed by releases before 0.3.0 are rejected by current
       # verifiers. No default is supplied: c2pa-rs accepts any string here, so
@@ -126,10 +137,9 @@ module C2PA
     # at it, so provenance chains from the original through to this asset. A
     # verifier can then follow and check the whole history.
     #
-    # For a file with no credentials there is nothing to carry forward, and
-    # the result is the same as the description alone. (Thumbnails would be
-    # the other contribution, but they need c2pa-rs's `add_thumbnails`
-    # feature, which this gem does not enable.)
+    # For a file with no credentials there is no manifest to carry forward.
+    # The file still contributes a thumbnail when C2PA::Config#thumbnails is
+    # on.
     #
     # Without `file:`, only the description is recorded. Nothing binds it to
     # any actual bytes. This form is kept for compatibility.
@@ -139,15 +149,23 @@ module C2PA
     # @param instance_id  [String] unique identifier for the ingredient instance
     # @param relationship [String] relationship to this asset; defaults to "parentOf"
     # @param file         [String, nil] path to the ingredient file
+    # @param digital_source_type [String, nil] URI from the C2PA digitalSourceType
+    #   vocabulary, for an ingredient with no content credentials of its own,
+    #   such as a generated image composited into this asset
     # @return [self]
-    # @raise [C2PA::InvalidManifestError] if `file` is given but cannot be read
-    def add_ingredient(title:, format:, instance_id:, relationship: "parentOf", file: nil)
+    # @raise [C2PA::InvalidManifestError] if `file` is given but cannot be read,
+    #   or if `digital_source_type` is given for a file that carries content
+    #   credentials
+    def add_ingredient(title:, format:, instance_id:, relationship: "parentOf", file: nil,
+                       digital_source_type: nil)
       description = {
         "title"        => title,
         "format"       => format,
         "instance_id"  => instance_id,
         "relationship" => relationship
       }
+      digital_source_type = to_s_or_nil(digital_source_type)
+      description["digital_source_type"] = digital_source_type if digital_source_type
 
       if file.nil?
         @ingredients << description
@@ -158,6 +176,16 @@ module C2PA
         raise InvalidManifestError, "ingredient file not readable: #{file.inspect}"
       end
 
+      # The specification forbids a source type alongside an embedded manifest:
+      # an ingredient with credentials already records its own origin. c2pa-rs
+      # refuses the combination only at signing, as "unable to encode assertion
+      # data", so it is caught here where the cause is clear.
+      if digital_source_type && content_credentials?(file)
+        raise InvalidManifestError,
+              "digital_source_type cannot be set for #{file.inspect}: it carries content " \
+              "credentials, which already record where it came from"
+      end
+
       @ingredient_files << {
         "json"   => JSON.generate(description),
         "format" => format,
@@ -198,6 +226,14 @@ module C2PA
 
     private
 
+    # A file with no manifest, or one c2pa-rs cannot read, counts as having no
+    # credentials; if it does carry some, signing still fails upstream.
+    def content_credentials?(file)
+      !C2PA.read(file: file)["active_manifest"].nil?
+    rescue ReadError
+      false
+    end
+
     # Parameters may be keyed with strings or symbols depending on the caller.
     def param_present?(parameters, key)
       return false unless parameters.is_a?(Hash)

data/lib/c2pa/version.rb

@@ -1,3 +1,3 @@
 module C2PA
-  VERSION = "0.5.0"
+  VERSION = "0.6.0"
 end

data/lib/c2pa.rb

@@ -58,6 +58,12 @@ module C2PA
   # @param manifest    [C2PA::Manifest]  the manifest to embed
   # @param verify      [Boolean]         read the signed file back and confirm it
   #                                      validates (default: true)
+  # @param sidecar     [String, nil]     write the manifest to this path as a
+  #                                      .c2pa file instead of embedding it (must
+  #                                      not already exist). The output is the
+  #                                      asset as hashed, usually identical to
+  #                                      the input, and is only valid alongside
+  #                                      the sidecar.
   # @return            [String]          the output path
   # @raise [C2PA::SigningError] if signing fails, or if the signed file does not validate
   #
@@ -72,13 +78,17 @@ module C2PA
   #     key:         "key.pem",
   #     manifest:    manifest
   #   )
-  def self.sign(file:, output:, certificate:, key:, algorithm: "es256", manifest:, verify: true)
+  def self.sign(file:, output:, certificate:, key:, algorithm: "es256", manifest:, verify: true, sidecar: nil)
     manifest_json = manifest.to_json
 
     raise SigningError, "Source file not found: '#{file}'"             unless File.exist?(file)
     raise SigningError, "Certificate file not found: '#{certificate}'" unless File.exist?(certificate)
     raise SigningError, "Key file not found: '#{key}'"                 unless File.exist?(key)
     raise SigningError, "Output file already exists: '#{output}'"      if File.exist?(output)
+    raise SigningError, "Sidecar file already exists: '#{sidecar}'"    if sidecar && File.exist?(sidecar)
+    if sidecar && File.expand_path(sidecar) == File.expand_path(output)
+      raise SigningError, "sidecar and output must be different paths"
+    end
 
     begin
       # to_json is the only thing genuinely required of a manifest, so an
@@ -87,12 +97,12 @@ module C2PA
       files = manifest.respond_to?(:ingredient_files) ? manifest.ingredient_files : []
       ingredient_files = files.empty? ? nil : JSON.generate(files)
       Native.sign_file(file, output, certificate, key, algorithm, manifest_json,
-                       intent, ingredient_files)
+                       intent, ingredient_files, sidecar)
     rescue RuntimeError => e
       raise SigningError, e.message
     end
 
-    verify_signed_output!(output) if verify
+    verify_signed_output!(output, sidecar) if verify
 
     output
   end
@@ -152,32 +162,54 @@ module C2PA
   # Read the C2PA manifest embedded in bytes held in memory.
   #
   # c2pa-rs identifies most formats from the leading bytes and ignores the
-  # hint when the two disagree. The hint matters for formats with no signature
-  # to sniff, such as SVG, which cannot be read without it.
+  # hint when the two disagree. The hint matters for formats it cannot tell
+  # apart by their bytes: SVG, and the ZIP-based documents (EPUB, DOCX, ODT,
+  # OpenXPS), which all begin with the same ZIP header.
+  #
+  # With manifest_data, the manifest store is taken from there, as the
+  # contents of a .c2pa sidecar, and validated against data. The format is
+  # then required, since nothing is sniffed.
   #
-  # @param data   [String]      the asset, as a binary string
-  # @param format [String, nil] MIME type or extension, e.g. "image/svg+xml"
-  # @return       [Hash]        parsed manifest JSON
-  # @raise        [C2PA::ReadError] if the data has no valid manifest
-  def self.read_buffer(data:, format: nil)
+  # @param data          [String]      the asset, as a binary string
+  # @param format        [String, nil] MIME type or extension, e.g. "image/svg+xml"
+  # @param manifest_data [String, nil] a detached manifest store, as a binary string
+  # @return              [Hash]        parsed manifest JSON
+  # @raise               [C2PA::ReadError] if the data has no valid manifest
+  def self.read_buffer(data:, format: nil, manifest_data: nil)
     data = binary!(data, "data")
-    JSON.parse(Native.read_buffer(data, format))
+    return JSON.parse(Native.read_buffer(data, format)) if manifest_data.nil?
+
+    manifest_data = binary!(manifest_data, "manifest_data")
+    raise ArgumentError, "format is required with manifest_data" if format.nil?
+
+    JSON.parse(Native.read_buffer_with_manifest(data, format, manifest_data))
   rescue RuntimeError => e
     raise ReadError, e.message
   end
 
   # Read the C2PA manifest embedded in a signed file.
   #
-  # @param file [String] path to the signed file
-  # @return     [Hash]   parsed manifest JSON
-  # @raise      [C2PA::ReadError] if the file has no valid manifest
+  # A file with no embedded manifest is read against a sidecar beside it with
+  # the same name and a .c2pa extension, if there is one: photo.c2pa for
+  # photo.jpg. Pass manifest_file for a sidecar kept anywhere else.
+  #
+  # Reading a .c2pa file on its own returns the manifest, but with nothing to
+  # check it against its hash never matches and the state is Invalid.
+  #
+  # @param file          [String]      path to the signed file
+  # @param manifest_file [String, nil] path to a detached manifest (.c2pa)
+  #                                    to validate the file against
+  # @return              [Hash]        parsed manifest JSON
+  # @raise               [C2PA::ReadError] if the file has no valid manifest
   #
   # @example
   #   manifest = C2PA.read(file: "photo_signed.jpg")
   #   active = manifest["manifests"][manifest["active_manifest"]]
   #   puts active["title"]
-  def self.read(file:)
-    JSON.parse(Native.read_file(file))
+  def self.read(file:, manifest_file: nil)
+    return JSON.parse(Native.read_file(file)) if manifest_file.nil?
+
+    JSON.parse(Native.read_file_with_manifest(file, manifest_file))
   rescue RuntimeError => e
     raise ReadError, e.message
   end
@@ -201,12 +233,13 @@ module C2PA
   #
   # @param output [String] path to the signed file
   # @raise [C2PA::SigningError] if the file does not validate
-  def self.verify_signed_output!(output)
+  def self.verify_signed_output!(output, sidecar = nil)
     result =
       begin
-        read(file: output)
+        read(file: output, manifest_file: sidecar)
       rescue ReadError => e
         discard(output)
+        discard(sidecar) if sidecar
         raise SigningError, "signed file failed verification: could not read it back: #{e.message}"
       end
 
@@ -218,6 +251,7 @@ module C2PA
     detail = failures.empty? ? "no failure detail reported" : failures.uniq.join(", ")
 
     discard(output)
+    discard(sidecar) if sidecar
     raise SigningError,
           "signed file failed verification: validation_state=#{state.inspect}, #{detail}. " \
           "The output file has been removed. Pass verify: false to keep it for inspection."

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ruby-c2pa
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.6.0
 platform: ruby
 authors:
 - Carlos Rodriguez