RustCrypto / RustCrypto/formats
spki: Document how to convert between `SubjectPublicKeyInfoRef` (or owned) and e.g. `p256::PublicKey`
Nobody has claimed this yet.
- Dominant language
- Rust
- Stars
- 338
- Forks
- 188
- Avg merge
- 4d 6h
- Merged PRs (30d)
- 15
Description
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::EncodedPointhas no documentation of its own and is a type alias forelliptic_curve::sec1::EncodedPoint, so I looked there, and there's nothing helpful.p256::PublicKeyhas no documentation of its own (and therefore no documentation appears in VS Code viarust-analyzer) and is a type alias forelliptic_curve::PublicKey. Finally there, I found the Parsing "SPKI" Keys documentation! But it says to use theDecodePublicKeytrait, which has no methods that take aSubjectPublicKeyInfo.
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
SubjectPublicKeyInfofor converting into a key. This can internally just call through to theTryFromimpl, but the method would then be discoverable via IDE code completion. - Document in the
spkicrate how to convert from its types. A single example of the formp256::PublicKey::try_from(spki)would have saved me hours of time and frustration digging through documentation and source code.
Contributor guide
No contributing guide indexed for this repository
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with the spki SubjectPublicKeyInfo and DecodePublicKey documentation, then compare it with the p256 and elliptic-curve parsing guidance mentioned in the issue. Done means the supported conversion path is discoverable, with a clear example such as p256::PublicKey::try_from(spki), and the relevant documentation or API is updated accordingly.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- rust
- Domain
- cryptography, documentation
- Issue type
- Documentation
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 42/100