Add initial support for encoding/decoding cert payloads

[atc0005]

Overview

Add support for generating a certificate metadata payload in JSON format from a specified metadata payload format version.

Add support for support for decoding a given (valid) certificate metadata payload. The format is automatically detected from a list of valid format versions.

The intent is to support all stable format versions indefinitely.

As of this commit / PR, format 0 is still under active development. This format version is an "unstable" metadata format and is not covered by this goal; format version 0 is subject to change often as development continues. Format version 1 is implemented at this time as a stub version for testing purposes; once stable the plan is to promote version 0 content as the initial version 1.

Changes

Primary changes:

• add support for generating a JSON payload from a specified metadata payload format version
  • this can be generated by calling the Encode function from a specific format version or by calling the top-level Encode function and specifying a valid format version number (e.g., 0 or 1)
• add support for decoding a given (valid) certificate metadata payload
  • the intent is to support decoding any given payload matching the set of supported format versions (e.g., 0, 1)
  • the caller provides an instance of a specific format version of the certificate metadata payload and the Decode function for that format version is used
  • once a format version is stable, the intent is to support creating and decoding it using this library indefinitely
    • this should allow the sysadmin using the check_cert plugin to specify what version of the payload format they wish to create
    • this should allow the sysadmin using a reporting tool to consume a certificate metadata payload generated by the check_cert plugin in the same fixed version as the one they asked the check_cert plugin to create
    • this process should continue to work as-is until the sysadmin decides to explicitly change the certificate metadata payload format version they're working with; updating this dependency should not break payload generation or consumption

Other changes:

• add payload format and library design notes
• add formats.md doc file proving backstory, goals and some details regarding initial implementation and where it fell short of the initial (and more ergonomic) goals
• update README.md with minor reference to the design doc and references to current implementation work
• add identification of misordered certificate chains
• add example "test" to illustrate library usage
  • initial example uses format 0; the plan is to update the example once format 1 is released/stable
• documentation updates
• general refactoring work

References

• fixes Add CertificateChainIssues.MisorderedCerts field #19
• fixes Expose payload version #31
• Add support for encoding/decoding cert payloads #46
• Add support for detecting misordered certificate chain entries check-cert#1004