Update RFC5280Policy and OCSPVerifierPolicy initializers #276
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
New initializers for `ExpiryPolicy`, `RFC5280Policy`, and `OCSPVerifierPolicy` were introduced in apple#266. These initializers were added to prevent users from specifying `Date.now` as the time to validate certificate expiry against. For context, the problem was that `Date.now` would be evaluated at initialization, but validation could occur at a later stage, at which point the validation time would become stale. These initializers had a `fixedValidationTime: Date? = nil` argument, where a non-`nil` value denoted a *fixed* time to validate against, and a `nil` value denoted that the current time, evaluated at the point of validation, would be used for validation (the common case). Although the dangers of specifying `fixedValidationTime = .now` were documented, in practice, it is very easy for users to miss this and continue using the API in an incorrect way. Given that most users will validate certificate expiry against the current time, we want to default to this and remove the validation time argument from the public initializers entirely. Users who want to specify a fixed predetermined time must explicitly opt-in by using `@_spi(FixedValidationTime)` to access the initializers that have a *non-optional* `fixedValidationTime` argument. Modifications: - Deprecated the initializers of `RFC5280Policy` and `OCSPVerifierPolicy` and introduced two new initializers for each: one without a validation time argument (common case), and one with a *non-optional* validation time argument backed behind an SPI - Updated the initializers of `ExpiryPolicy` (an internal type) - Additional changes: - Updated test cases to use new initializers - Updated examples in documentation to use new initializers Result: `RFC5280Policy` and `OCSPVerifierPolicy` can be used more safely
FranzBusch
reviewed
Oct 8, 2025
Sources/X509/OCSP/OCSPPolicy.swift
Outdated
| /// - Warning: Only use this initializer if you want to validate the certificates against a *fixed* time. Most users | ||
| /// should use ``init()``: the expiry of the certificates will be validated against the current time (evaluated at | ||
| /// the point of validation) when using that initializer. | ||
| @_spi(FixedValidationTime) |
There was a problem hiding this comment.
I am not convinced that we should be using SPI for this. SPI is an undocumented feature and hard to discover. What if we either:
- Make this a factory method instead of an init so it is harder to discover and gets a concrete name
- Use package traits to guard this API
There was a problem hiding this comment.
Making this hard to discover is absolutely intentional. We changed the behaviour, but users continued to misuse it, so we're trying to take this API away from almost everyone.
Lukasa
reviewed
Oct 10, 2025
| /// - Parameter requester: A requester instance conforming to ``OCSPRequester``. | ||
| /// - Parameter fixedValidationTime: The *fixed* time to compare against when determining if the request is recent. A fixed time is a *specific* | ||
| /// time, either in the past or future, but **not** the current time. To compare against the current time *at the point of validation*, pass `nil` to | ||
| /// `fixedValidationTime`. |
There was a problem hiding this comment.
Can we please restore these doc comments to the deprecated methods?
Lukasa
approved these changes
Oct 13, 2025
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Motivation:
New initializers for
ExpiryPolicy,RFC5280Policy, andOCSPVerifierPolicywere introduced in #266. These initializers were added to prevent users from specifyingDate.nowas the time to validate certificate expiry against. For context, the problem was thatDate.nowwould be evaluated at initialization, but validation could occur at a later stage, at which point the validation time would become stale.These initializers had a
fixedValidationTime: Date? = nilargument, where a non-nilvalue denoted a fixed time to validate against, and anilvalue denoted that the current time, evaluated at the point of validation, would be used for validation (the common case). Although the dangers of specifyingfixedValidationTime = .nowwere documented, in practice, it is very easy for users to miss this and continue using the API in an incorrect way.Given that most users will validate certificate expiry against the current time, we want to default to this and remove the validation time argument from the public initializers entirely. Users who want to specify a fixed predetermined time must explicitly opt-in by using
@_spi(FixedExpiryValidationTime)to access the initializers that have a non-optionalfixedExpiryValidationTimeargument.Modifications:
RFC5280PolicyandOCSPVerifierPolicyand introduced two new initializers for each: one without a validation time argument (common case), and one with a non-optional validation time argument guarded behind an SPIExpiryPolicy(an internal type)Result:
RFC5280PolicyandOCSPVerifierPolicycan be used more safely