How to use cryptographic suites

[silverpill]

The specification makes use of term "cryptographic suite" but I don't quite understand what it is.

Some examples include strings like ecdsa-2022 but their meaning is not explained. Section 2.1 Proofs contains a block named Issue: Avoid signature format proliferation by using text-based suite value where several cryptographic suites are listed:

The following signature suites are currently being contemplated: eddsa-2022, nist-ecdsa-2022, koblitz-ecdsa-2022, rsa-2022, pgp-2022, bbs-2022, eascdsa-2022, ibsa-2022, and jws-2022.

Section 5.1 Versioning Cryptography Suites contains a similar block named Issue 38: Determine how cryptographic suites are versioned with the following sentence:

All cryptographic suites that follow this specification are intended to be registered [VC-EXTENSION-REGISTRY] in a way that clearly signal which cryptosuites are deprecated, standardized, or experimental.

The VC-EXTENSION-REGISTRY document contains a list of "proof methods" but there is no mention of cryptographic suites.

Also, it's not clear what proof type should be used. What's the difference between DataIntegrityProof type (being used along with cryptosuite property) and other types like Ed25519Signature2020?

[msporny]

@silverpill wrote:

The specification makes use of term "cryptographic suite" but I don't quite understand what it is.

Yes, and my apologies, the spec is horribly confusing at present on how all of this stuff fits together. To briefly try to answer your question, there are other specs for other signature algorithms:

https://w3c.github.io/vc-di-eddsa/ https://w3c-ccg.github.io/vc-di-ecdsa/

We plan to cross-link those specs, once they're fully published, to the main Data Integrity spec. There is also a directory of data integrity specs that will be cross-linked to here (perhaps we should only link to the directory?):

https://w3c.github.io/vc-specs-dir/#proof

There are also some older ones that are going to get big changes applied to them (so, don't copy anything in them, or presume they're right... they're legacy):

https://w3c-ccg.github.io/ld-cryptosuite-registry/#signature-suites

Also, it's not clear what proof type should be used. What's the difference between DataIntegrityProof type (being used along with cryptosuite property) and other types like Ed25519Signature2020?

Ed25519Signature2020 is legacy, but deployed in the wild. DataIntegrityProof is what we're hoping the communities using this technology will adopt as they move forward.

The reason for DataIntegrityProof is so that there is a single JSON-LD type for most Data Integrity Proofs instead of the path we were headed down, which would require an entirely new JSON-LD Context for every type of Data Integrity Proof AND would require the inclusion of that context whenever you did a signature of that type. Instead, what we're trying to do is reduce the number of JSON-LD Contexts an implementation has to pull in, ideally to 1 base context (ActivityPub or Verifiable Credentials), plus maybe a market vertical specific JSON-LD Context... and that's it. Ideally, the DataIntegrityProof goes in the base context, and by doing that, you're future-proofed against having to include new JSON-LD Contexts just because you want to use a new cryptosuite. It also simplifies the base contexts that include Data Integrity quite a bit.

Compare the cryptosuites included in the Verifiable Credentials v1.0 JSON-LD Context (4 cryptosuites, possibly growing to 8-10 in v2.0):

https://github.com/w3c/vc-data-model/blob/main/contexts/credentials/v1#L85-L237

vs. the Verifiable Credentials v2.0 JSON-LD Context (1 cryptosuite):

https://github.com/w3c/vc-data-model/blob/main/contexts/credentials/v2#L101-L164

Does that help explain the improvements we're trying to make?

If so, what text could we write or include in the specs to make all of the above more clear? What would have helped you find the new cryptosuite docs?

[silverpill]

Thank you, this is very helpful explanation.

I would add a note about reducing the number of contexts to "3.1 DataIntegrityProof" section to indicate that DataIntegrityProof proof type is recommended. Other proof types can be marked as legacy. And, as you said, cross-references are needed. I think a list of existing cryptosuite specs is preferable to a directory link (this list can be added to "3. Cryptographic Suites" section).

[msporny]

Thank you, this is very helpful explanation.

Thank you for the feedback, it's now far more clear what we can add/modify in the spec to address your concerns... and really, your concerns are generally shared by a number of people in the group... it's just that you've been the first one to articulate them in an actionable way, so thank you for that. :)

I would add a note about reducing the number of contexts to "3.1 DataIntegrityProof" section to indicate that DataIntegrityProof proof type is recommended.

Ok, will do.

Other proof types can be marked as legacy.

Yes, we plan to do that for the cryptosuites we control... and will urge other cryptosuite authors to do the same. We're trying to strike the right balance between allowing the technologies to be decentralized, but not to the degree that someone is going to end up picking a legacy/out of date crytposuite.

And, as you said, cross-references are needed.

Ok, I will do that as well.

I think a list of existing cryptosuite specs is preferable to a directory link (this list can be added to "3. Cryptographic Suites" section).

This is the only one where the end result might end up being not what you intend. Keep in mind that we're an official W3C Working Group, with a limited charter that expires next summer. Once that's done, the spec is published, and there is no guarantee that we'll be re-chartered to pick it up, revise, or maintain it. That said, it's rare that this doesn't happen, but when we publish, we have to go in with a mindset of "We might not be able to touch this specification for another 5 years or more". That's why we end up pointing to directories and registries, which we can update and maintain. The did-spec-dir directory that I pointed at is one such thing we'll be able to continuously maintain vs. the spec, which we're not allowed to touch in any significant way after it is published (because it's a global standard and governments start writing those standards into their regulations, in some cases).

That said, I think the outcome will be the same as what you'd like -- an up-to-date place where you can look for other cryptosuites.

Ok, I have a clear direction, thank you for that! I've marked this issue as "ready for pr" and will put it in my Editors queue and reference the PR once it's ready. Feel free to put additional thoughts in here in the meantime if you think other additions or changes to the specification might help you or other implementers.

[msporny]

PR #117 has been raised to address this issue. This issue will be closed if PR #117 is merged.

@silverpill, I've tried to address your concerns by:

1. Cross-linking the other cryptosuite specifications and placing those links at the top of the specification.
2. Adding a section providing an explanation of the legacy cryptosuites and guidance on what should be used by specification authors for new cryptosuites.
3. Referencing other cryptosuite specifications in-line in the section that provides guidance to specification authors.

Let me know if you'd like me to add anything further to address your concerns.

[msporny]

PR #117 has been merged to address this issue, closing.