x509-cert: Document (or improve) how to construct Name

[str4d]

The yubikey crate's Certificate::generate_self_signed now takes subject as a Name, instead of &[RelativeDistinguishedName]. While I could migrate to RdnSequence(vec![...]), that makes use of the pub internals that prevent Name from being correct-by-construction per #1486, so I wanted to explore how Name can be constructed by a user who is just trying to use the yubikey crate, and may not be familiar at all with X.509 internals.

The documentation for Name just says "as defined in RFC 5280 Section 4.1.2.4". That section gives no indication about how a user can construct a Name; it instead describes the ASN.1 DER encoding of a Name.

The very first method that shows up on the doc page for Name is RdnSequence::encode_from_string, which:

• Does not produce a Name (or even an RdnSequence).
• Is marked as deprecated.

The only explicit constructor I can find for Name is impl FromStr for RdnSequence. This is documented as "Follows the rules in RFC 4514". Following that URL leads to a rather confusing set of rules, and no visible examples (because the datatracker HTML view does not show the contents at the top, and instead requires finding and clicking on the "Contents" tab on the right). Once I eventually found RFC 4514 Section 4: Examples I was on the right track (although I also had to refer back to the table at the bottom of section 3 for attribute types, which requires navigating past equally confusing specification syntax to find it).

Name should be given significantly more documentation, and more ergonomic constructors. Possibly a builder pattern would help? (That would save the extra allocation from format!(...).parse()?.)

At a minimum, there needs to be an example in the Name documentation of constructing it from a string. It would also be beneficial to describe the general syntax, and copy the table of attribute types, in either the FromStr implementation docs, or on Name itself (and then reference it from the FromStr impl).

(The above problems also apply to construction of RelativeDistinguishedName directly; this issue should address both in the same way.)

[baloo]

This is mostly solved by #1499 which tightened up the type system. We still need to make a builder for names, in the mean time FromStr is the recommended method to build a name.