RFC: change high-level API to make key usage explicit

[djc]

Inspired by #119, I was thinking it might make sense to stop having a bunch of different but mostly similar verification functions, and instead provide a single API call that (a) makes the key usage parameter explicit, and in exchange (b) does away with the shallow trust anchor slice wrappers.

As written, this maintains the explicit connection to a particular key usage but does it in a more generic way. I've chosen methods on ExtendedKeyUsage for the common usage values here, but we could alternatively expose these as consts and/or potentially hide the ExtendedKeyUsage enum inside an opaque struct to force callers to go through an explicit API.

cc @sietseringers

[codecov]

Codecov Report

Merging #133 (e7e1b21) into main (d96f6f5) will decrease coverage by 0.58%.
The diff coverage is 91.07%.

@@            Coverage Diff             @@
##             main     #133      +/-   ##
==========================================
- Coverage   95.74%   95.16%   -0.58%     
==========================================
  Files          15       15              
  Lines        3431     3620     +189     
==========================================
+ Hits         3285     3445     +160     
- Misses        146      175      +29     

Files Changed	Coverage Δ
src/trust_anchor.rs	90.27% <ø> (-0.80%)	⬇️
src/end_entity.rs	68.26% <71.42%> (-31.74%)	⬇️
src/verify_cert.rs	95.18% <93.87%> (-0.70%)	⬇️

... and 4 files with indirect coverage changes

📣 We’re building smart automated test selection to slash your CI/CD build times. Learn more

[djc]

This triggers the semver check because we're adding a #[deprecated] attribute which apparently merits a minor version bump. Given that our major is zero, it seems that we should treat minor and patch the same way, so this is fine?

[cpu]

Thanks, this seems like a nice improvement 👍

[djc]

Reduced coverage is mostly about the deprecated functions which we no longer call in tests, I think that's okay?

[ctz]

💯

[djc]

Given that we're going to bump to 0.102 anyway for the optional ring PR, can we pull that in here to avoid the deprecation stuff?

[ctz]

Sorry, yes let's hold this till tomorrow. I would like to release an 0.101.2 (mainly to get #132 out) before moving main to 0.102.x. I think the deprecations require a semver bump anyway -- we can't control downstreams that write deny(warnings)?

[djc]

I think that's what they're opting into anyway if they set deny(warnings)... Would be nice to release this with the deprecations, giving people a chance to migrate with deprecations rather than hard compile failures?

[ctz]

Yeah https://doc.rust-lang.org/cargo/reference/semver.html#minor-introducing-new-lints agrees with that intepretation.

[djc]

Improved the documentation for verify_for_usage() to mention usage and crls, so I think this could just be merged for 0.101.2.

[ctz]

Ah, this isn't merging because ci / Check semver compatibility wants to see the minor version bumped for deprecated items. That's not really ideal :(

[djc]

@ctz we can hit the "Merge without waiting for requirements to be met" for this case?

Or alternatively exclude the semver stuff from the merge queue checks.