RustCrypto / RustCrypto/formats

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

Open
#1,604 2 comments 0 reactions 0 assignees View on GitHub

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::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.

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.