How to cite extensions

[pwinckles]

Yesterday, language was added to the spec that introduces "cite-able" extensions. ocfl_layout.json can be used to cite extensions related to storage layout. Where are other types of extensions intended to be cited? For example, where would I cite the use of sha-512/256? Are all extensions intended to be cited in ocfl_layout.json?

[ahankinson]

sha-512 does not need to be cited as part of an extensions, since it is part of the spec. If you wanted to use, for example, blake2s-64 for fixity, however, you would need to be able to refer to this somehow, which is what the cite-ability means.

[pwinckles]

sha-512/256 (truncated sha-512) isn't part of the spec.

you would need to be able to refer to this somehow, which is what the cite-ability means.

That is exactly what I'm asking for clarity on. I don't see the point of citing something if no one knows where to look for the citation.

[ahankinson]

Sorry, I thought you meant "sha-512 OR sha-256" but were using shorthand.

Do you mean where would the extensions be published? https://ocfl.github.io/extensions/

[pwinckles]

Let's say that I have an OCFL repository that adheres to non-normative extensions that are published in https://ocfl.github.io/extensions/, where do I cite them in the repository to let others know what extensions I'm using? For extensions related to storage layout, I can cite them in ocfl_layout.json.

[birkland]

I think there is a bit of nuance here. I think what @pwinckles is getting at here is less "this is the definition of sha512/256 and the hash ID that can be used in OCFL", and more "this repository leverages the extension sha512/256". In other words, is there a general mechanism for advertising that a repository uses a certain set of extensions? ocfl_layout.json can be used for citing a particular kind of extension by URI as it pertains to layout, and can signal to clients that they need to use the layout defined in the extension.

So could there be a way to indicate "this repository uses sha512/256 as defined in this extension", and "clients should use sha512/256 instead of sha512 when they create new objects"

[ahankinson]

I think the intention was that you should be able to use URI values if you were using a non-normative extension mechanism. So you could use sha-512 as the key in a fixity section OR https://ocfl.github.io/extensions/hash-algorithms#sha-512/256.

[pwinckles]

Thanks, that's what was unclear to me.

[ahankinson]

I can raise this with the editors today and see if they concur.

[pwinckles]

Is the intent that the digest algorithm that's used for content-addressing MUST either be sha512 or sha256?

The digest algorithm used for calculating digests within the OCFL Object. This SHOULD be sha512, however sha256 MAY also be used.

Can any of the other controlled values be used? How about extensions? If extensions can be used, how does this impact the inventory sidecar?

Every occurrence of an inventory file MUST have an accompanying sidecar file stating its digest. This sidecar file must be of the form inventory.json.ALGORITHM, where ALGORITHM is the chosen digest algorithm for the object. An example might be inventory.json.sha512.

[ahankinson]

Is the intent that the digest algorithm that's used for content-addressing MUST either be sha512 or sha256?

Yes. No other hash algorithms can be used. This is for digestAlgorithm. For fixity, however, the table given and the extensions provide for virtually limitless hash algorithm choices.

This decision was made because OCFL relies on the digestAlgorithm to function, while fixity is an optional extra. Clients will then only need to implement two hash algorithms in order to be compliant.

[pwinckles]

Thanks for the clarification. I think it would be helpful if that MUST was also in the digest section rather than solely buried in the digestAlgorithm field description.

[ahankinson]

It also removes the possibility that known-broken hash algorithms (CRC, MD5, SHA1) are used for content addressability. Should a collision occur in an OCFL Object, it would break content addressability which would leave the object in an unknown state. (Two files, different content, same hash = lost content).

[ahankinson]

Discussion: Keys will be used instead of URIs. A table of extensions will be created by @zimeon that will give the values of the keys in the fixity section that can be used in addition to those that are available in the spec.