Checksums on the Media resource

[grispin]

Having an byte array checksum on the Media resource that can used to validate that the media byte stream would be nice to be able to reduce excess media transitions. This would allow clients to avoid pulling the byte stream when modification timestamp has changed for other reasons like photo order as they can check the checksum against their local copy. For the implementers it could reduce the the repetitive fetching of media on their solutions.

A implementation could support multiple checksum algorithms so communicating it as a collection which include the type of checksum would be needed. The checksums should be and documented, open enumerated lookup so that it's easy for the clients to identified the algoithm on their side. The type of checksum and that algorithm's industry-standard, text friendly output format (non-binary) would be each attribute set in each instance of the collection.

It would be good to recommend/require one checksum algorithm to be standard by the RESO to align the implementations for ease of use with other algorithms for advanced cases and future migration as industry standards change.

A checksums on a media record could look something like this:

{


  "checksums": [
    {
      "checksumType": "SHA1",
      "checksumValue": "da39a3ee5e6b4b0d3255bfef95601890afd80709"
    },
    {
      "checksumType": "SHA512",
      "checksumValue": "cf83e1357eefb8bdf1542850d66d8007d620e4050b5715dc83f4a921d36ce9ce47d0d13c5d85f2b0ff8318d2877eec2f63b931bd47417a81a538327af927da3e"
      },
     {
      "checksumType": "MD5",
      "checksumValue": "d41d8cd98f00b204e9800998ecf8427e"
    }
  ]
}

[bryanburgers]

Yes please. We’ve run into a few situations where this would be really valuable.

[EricFiZillow]

I think this is a great idea. We could also have some level of spot checking during the certification process.

[bryanburgers]

The HTML standard has a very similar specification (but with different goals) that we could lean on: Subresource Integrity (SRI) spec, MDN.

In HTML world, it looks like this:

<script
  src="https://example.com/example-framework.js"
  integrity="sha384-oqVuAfXRKap7fdgcCY5uykM6+R9GqQ8K/uxy9rx7HNQlGYl1kPzQho1wx4JwY8wC"
  crossorigin="anonymous"></script>

What I like about this spec is that the algorithm is specified inline to make one logical value. We can use a single field on the media resource instead of introducing a new shape. A media item might look like

{
   "@odata.id": "https://example.com/Property('1')/Media('1-asdf')"
   "Order": 1,
   "MediaURL": "https://cdn.example.com/asdf-original.jpg",
   "MediaKey": "asdf",

   // 👇
   "Checksum": "sha1-wE/JfOePkzSgyUOGJ8x9m9xXtFw="

}

A couple of questions we might need to resolve if we go this route:

1. Should multiple checksums be supported? If so

   1. The SRI spec does support specifying multiple checksums in a single value

      {
          "@odata.id": "https://example.com/Property('1')/Media('1-asdf')",
          //           👇                                👇                                                                                              👇 
          "Checksum": "sha1-wE/JfOePkzSgyUOGJ8x9m9xXtFw= sha512-lKkqXzkMDYQLOjkuFpJHpbYVG9FDTq01z2fgiPzByLve+A1bmiOzuttGP99YK3ApWvtoYctt9g11Ms2yzW67+Q== md5-RtzBJoSyaMA4UDZUtMticg=="
      }

      The positive side is that we still have only introduced a single field to Media, and we're following an existing standard that does the exact same thing.

      The negative side is that we're using a string to hold multiple values.

   2. Or Checksum is an array of strings.

      {
          "@odata.id": "https://example.com/Property('1')/Media('1-asdf')",
          "Checksum": [
              "sha1-wE/JfOePkzSgyUOGJ8x9m9xXtFw=",
              "sha512-lKkqXzkMDYQLOjkuFpJHpbYVG9FDTq01z2fgiPzByLve+A1bmiOzuttGP99YK3ApWvtoYctt9g11Ms2yzW67+Q==",
              "md5-RtzBJoSyaMA4UDZUtMticg=="
          ]
      }

      The HTML spec does not have the luxury of doing this because HTML attributes can't be arrays, but we do have the luxury of doing this because the RESO data model supports arrays of strings.

      We keep the positive side that we've still only introduced a single field to Media, and we're still mostly following an existing standard that does the exact same thing.

      The negative side is that the likely common use case (my personal guess, not grounded in research) will only be a single checksum, but it now always needs to be in an array.

   3. Or we go down the route of adding a new shape.

      The positive side here is that we can extend the shape in the future if we ever need to add new fields to the shape.

      The negative side is that it is added complexity.

2. The SRI spec currently only supports three hashing algorithms.

   The valid SRI hash algorithm token set is the ordered set « "sha256", "sha384", "sha512" » (corresponding to SHA-256, SHA-384, and SHA-512 respectively). The ordering of this set is meaningful, with stronger algorithms appearing later in the set.

   and suggests against using other common hashing algorithms

   Digests are only as strong as the hash function used to generate them. It is recommended that user agents refuse to support known-weak hashing functions and limit supported algorithms to those known to be collision resistant. Examples of hashing functions that are not recommended include MD5 and SHA-1. At the time of writing, SHA-384 is a good baseline.

   The SRI spec has different goals than we do, so we may want to be more flexible and support more algorithms (MD5 and SHA1 are used in Geoff's motivating example). If we would include those, we would have to enumerate the algorithms we want to support and define prefixes that we believe won't conflict with future added algorithms (md5 and sha1 feel pretty safe, as widely used algorithms).

[grispin]

The reason that the type was kept separate from the digest was so that it could easily be supplemented with old (MD5) and new algorithms outside other current specifications without need for a change to the Transport specification. I also dislike mixing data types as the ChecksumType should really be an enumeration while the ChecksumDigest is a string. HTML is not a good standard to look at for data typing.

Their was a new pseudo-digest suggested at the Fall 2024 RESO conference due to the limitations of some implementations. The idea was to have Signature as a checksum type for those systems that do on-request photo rendering (watermarks, sizing, etc.) so that they can provide a value in the checksum that can be compared to what the client received previouly as a has-byte-array-changed check but has no mathematical algorithm behind it for the client to attempt to validate the image itself. It's not as useful as a proper digest but better than nothing at all. This could be a separate field as well but it trying to serve a similar purpose.

I could see flattening the structure to two top level fields: ChecksumType and ChecksumDigest for example. Just need to define the standard naming convention for the digests and the encoding type of the Digest. The array was a nice to have but I don't see many implementing it and it just weighs the payload down.

On that topic, I did the examples using hex encoding and should have recommended base64 just for it's smaller size, especially when we get to larger digests like SHA512 (hex is 128 bytes per image vs 86 for base64). Yes it's only 42 characters but on a listing with 50 photos, thats 2KiB+ and on thousands of listings to thousands of feeds it adds up.

[bryanburgers]

The reason that the type was kept separate from the digest was so that it could easily be supplemented with old (MD5) and new algorithms outside other current specifications without need for a change to the Transport specification. I also dislike mixing data types as the ChecksumType should really be an enumeration while the ChecksumDigest is a string. HTML is not a good standard to look at for data typing.

I mostly disagree on this point. ChecksumType and ChecksumDigest are both meaningless on their own, together they comprise one logical thing.

But more than that, I see a lot of value in using an existing, implemented spec that does exactly what we're trying to do here, rather than trying to write our own. I think we still could support md5/sha1 at the same time, but given the choice between supporting old digest functions or simply pointing to an external well-tested spec, I'd go the other way and say we shouldn't support old digest functions.

An example of a benefit is that there are lots of articles written about SRI on the internet already, and I was very quickly able to find several generator websites (including https://laysent.github.io/sri-hash-generator/, https://sri-gen.henkverlinde.com/) to be able to quickly check if my implementation matches other implementations.

Their was a new pseudo-digest suggested at the Fall 2024 RESO conference due to the limitations of some implementations. The idea was to have Signature as a checksum type for those systems that do on-request photo rendering (watermarks, sizing, etc.) so that they can provide a value in the checksum that can be compared to what the client received previouly as a has-byte-array-changed check but has no mathematical algorithm behind it for the client to attempt to validate the image itself. It's not as useful as a proper digest but better than nothing at all. This could be a separate field as well but it trying to serve a similar purpose.

Yep. And if this is the direction we want to go, I'm on board.

I could see flattening the structure to two top level fields: ChecksumType and ChecksumDigest for example. Just need to define the standard naming convention for the digests and the encoding type of the Digest. The array was a nice to have but I don't see many implementing it and it just weighs the payload down.

Agreement here. I have the feeling most consumers will use the new field more like the identity has-byte-array-changed check. The consumers that do want to actually perform a checksum are likely to implement as many checksum methods as they can, at which point they can verify whichever type is given.

So I don't see a big value in multiple checksums of various types, and I think having multiple checksums adds way more complexity than it's worth, especially if we have to add a new shape.

On that topic, I did the examples using hex encoding and should have recommended base64 just for it's smaller size, especially when we get to larger digests like SHA512 (hex is 128 bytes per image vs 86 for base64). Yes it's only 42 characters but on a listing with 50 photos, thats 2KiB+ and on thousands of listings to thousands of feeds it adds up.

I agree base64 feels like the right choice. FWIW, SRI also uses base64. The examples I gave copy/pasted from your original examples, which is why they use hex strings. I should fix that just to be clear. The original examples I gave used hex, but they have been updated to use base64 according to the SRI spec.

[grispin]

The reason I was leaning towards separate fields (same data, slightly different representation) was to avoid looking like SRI but not being completely compatible. SRI only support the FIPS SHS hashes in the specification and our proposed solution would have additional hash ('md5' and 'Signature') that different SRI libraries may not parse properly.

Rather than trying to appear like the existing SRI standard but not being 100% compatible, I think we should do a representation that is distinct enough to not be mistaken for SRI. With that in mind and looking at how other complex types were flattened for the DD to avoid custom shapes ( area/units, numeric/units, fee/frequency, etc. ), the approach of two fields seems logical.

The other advantage of this approach is we can expose checksum type enumeration as metadata when it is a separate field. This allows clients can know which checksum types are used by a given provider without scanning media records and ensuring compatibility if they want to use this feature. It's highly likely that multiple checksum types could be used by a single vendor over the years and they may not re-hash historical media file when transitions between digests occur.

{
   "@odata.id": "https://example.com/Property('1')/Media('1-asdf')"
   "Order": 1,
   "MediaURL": "https://cdn.example.com/asdf-original.jpg",
   "MediaKey": "asdf",

   // 👇
   "ChecksumType": "signature",
   "ChecksumDigest": "aaabbbcccdddeeefffggg"
}

Something like signature-aaabbbcccdddeeefffggg could/would fail in available SRI parsers. People could always still use an SRI parser for validation after validating the checksum type by concatenating the two fields back together.

[bryanburgers]

This would go a long way to help solve one of our larger pain points! I would love to see this discussed in a workgroup meeting.

(This message brought to you by the request at the last workgroup meeting to review the discussions and comment on anything we think is important.)