spki: Document how to convert between SubjectPublicKeyInfoRef (or owned) and e.g. p256::PublicKey

[str4d]

As part of migrating age-plugin-yubikey to yubikey 0.8 (using VS Code and rust-analyzer), I encountered SubjectPublicKeyInfo in a certificate. I need to parse this into an Option<p256::PublicKey> (returning None if invalid or not P-256), but there is no documentation anywhere in the spki crate on how to do this.

I found SubjectPublicKeyInfo::from_key which is how to convert any type implementing EncodePublicKey into an SPKI, but there is no equivalent reverse method. A DecodePublicKey trait exists, but there is no reference to it in the documentation of SubjectPublicKeyInfo (or its owned or ref aliases). DecodePublicKey also doesn't document how it should be used either.

I then turned to the p256 crate's documentation:

• p256::EncodedPoint has no documentation of its own and is a type alias for elliptic_curve::sec1::EncodedPoint, so I looked there, and there's nothing helpful.
• p256::PublicKey has no documentation of its own (and therefore no documentation appears in VS Code via rust-analyzer) and is a type alias for elliptic_curve::PublicKey. Finally there, I found the Parsing "SPKI" Keys documentation! But it says to use the DecodePublicKey trait, which has no methods that take a SubjectPublicKeyInfo.

I finally noticed the impl<T> DecodePublicKey for T where T: for<'a> TryFrom<SubjectPublicKeyInfoRef<'a>> at the bottom of the DecodePublicKey documentation, which gave me the idea to just try p256::PublicKey::try_from(spki), and it worked!

The conversion process should be greatly simplified, by way of one or more of the following:

• Have an explicit method on SubjectPublicKeyInfo for converting into a key. This can internally just call through to the TryFrom impl, but the method would then be discoverable via IDE code completion.
• Document in the spki crate how to convert from its types. A single example of the form p256::PublicKey::try_from(spki) would have saved me hours of time and frustration digging through documentation and source code.

[tarcieri]

Would a suggestion to use TryFrom and a adding list to the spki crate's rustdoc of some of the types in various RustCrypto crates which support the conversion be helpful here?

[str4d]

Yes, that's my second suggestion above.