doc.go 1.6 KB

12345678910111213141516171819202122232425262728293031323334353637383940414243
  1. // Package digest provides a generalized type to opaquely represent message
  2. // digests and their operations within the registry. The Digest type is
  3. // designed to serve as a flexible identifier in a content-addressable system.
  4. // More importantly, it provides tools and wrappers to work with
  5. // hash.Hash-based digests with little effort.
  6. //
  7. // Basics
  8. //
  9. // The format of a digest is simply a string with two parts, dubbed the
  10. // "algorithm" and the "digest", separated by a colon:
  11. //
  12. // <algorithm>:<digest>
  13. //
  14. // An example of a sha256 digest representation follows:
  15. //
  16. // sha256:7173b809ca12ec5dee4506cd86be934c4596dd234ee82c0662eac04a8c2c71dc
  17. //
  18. // In this case, the string "sha256" is the algorithm and the hex bytes are
  19. // the "digest".
  20. //
  21. // Because the Digest type is simply a string, once a valid Digest is
  22. // obtained, comparisons are cheap, quick and simple to express with the
  23. // standard equality operator.
  24. //
  25. // Verification
  26. //
  27. // The main benefit of using the Digest type is simple verification against a
  28. // given digest. The Verifier interface, modeled after the stdlib hash.Hash
  29. // interface, provides a common write sink for digest verification. After
  30. // writing is complete, calling the Verifier.Verified method will indicate
  31. // whether or not the stream of bytes matches the target digest.
  32. //
  33. // Missing Features
  34. //
  35. // In addition to the above, we intend to add the following features to this
  36. // package:
  37. //
  38. // 1. A Digester type that supports write sink digest calculation.
  39. //
  40. // 2. Suspend and resume of ongoing digest calculations to support efficient digest verification in the registry.
  41. //
  42. package digest