diff --git a/docs/core/compatibility/7.0.md b/docs/core/compatibility/7.0.md index 7d3e68fb2a26f..d1a47de263d08 100644 --- a/docs/core/compatibility/7.0.md +++ b/docs/core/compatibility/7.0.md @@ -46,6 +46,7 @@ If you're migrating an app to .NET 7, the breaking changes listed here might aff | Title | Binary compatible | Source compatible | Introduced | | - | :-: | :-: | - | | [Decrypting EnvelopedCms doesn't double unwrap](cryptography/7.0/decrypt-envelopedcms.md) | ❌ | ✔️ | Preview 5 | +| [Dynamic X509ChainPolicy verification time](cryptography/7.0/x509chainpolicy-verification-time.md) | ❌ | ✔️ | Preview 7 | | [X500DistinguishedName parsing of friendly names](cryptography/7.0/x500-distinguished-names.md) | ❌ | ✔️ | Preview 5 | ## Deployment diff --git a/docs/core/compatibility/cryptography/7.0/x509chainpolicy-verification-time.md b/docs/core/compatibility/cryptography/7.0/x509chainpolicy-verification-time.md new file mode 100644 index 0000000000000..6de9f580fe531 --- /dev/null +++ b/docs/core/compatibility/cryptography/7.0/x509chainpolicy-verification-time.md @@ -0,0 +1,65 @@ +--- +title: "Breaking change: Dynamic X509ChainPolicy verification time" +description: Learn about the .NET 7 breaking change in cryptography where the X509ChainPolicy verification time is the time when Build is invoked. +ms.date: 07/20/2022 +--- +# Dynamic X509ChainPolicy verification time + +In previous versions of .NET, the value was assigned to when the object was constructed. Using the same `X509ChainPolicy` object for multiple calls to resulted in all chain builds using that same value as the verification time, no matter how much time had passed since the object was created. + +The new default behavior is to use the value of `DateTime.Now` when `X509Chain.Build()` is invoked as the verification time. This change doesn't affect chain builds that explicitly assign `X509ChainPolicy.VerificationTime`. + +## Previous behavior + +The value was assigned to when the `X509ChainPolicy` object was constructed. This value was used in all subsequent calls (unless or until the value was reassigned at a later time). + +## New behavior + +The value is assigned to when the `X509ChainPolicy` object is constructed, but the new `X509ChainPolicy.VerificationTimeIgnored` property defaults to `true`. When this property has a value of `true`, the method uses `DateTime.Now` as the verification time instead of `X509ChainPolicy.VerificationTime` when building the chain. + +Assigning a value to the `X509ChainPolicy.VerificationTime` property automatically sets `VerificationTimeIgnored` to `false`. + +## Version introduced + +.NET 7 Preview 7 + +## Type of breaking change + +This change can affect [binary compatibility](../../categories.md#binary-compatibility). + +## Reason for change + +Callers who cache configured `X509ChainPolicy` objects were often surprised that their validation was slowly moving further back in time. This change makes long-lived `X509ChainPolicy` objects easier to work with and doesn't significantly impact short-lived objects. + +## Recommended action + +The following callers aren't impacted by the change: + +- Callers that don't have long-lived `X509ChainPolicy` objects. +- Callers that explicitly assign the `X509ChainPolicy.VerificationTime` property. + +Callers that have a long-lived `X509ChainPolicy` object that wish to use the previous behavior can either assign the new `X509ChainPolicy.VerificationTimeIgnored` property to `false` or assign the `X509ChainPolicy.VerificationTime` property to `DateTime.Now`. + +```csharp +var policy = new X509ChainPolicy +{ + // ... + VerificationTime = DateTime.Now, +}; +``` + +or + +```csharp +var policy = new X509ChainPolicy +{ + // ... + VerificationTimeIgnored = false, +}; +``` + +## Affected APIs + +- +- +- `System.Security.Cryptography.X509Certificates.X509ChainPolicy.VerificationTimeIgnored` diff --git a/docs/core/compatibility/toc.yml b/docs/core/compatibility/toc.yml index 60460e8e0ee26..fa1096b4f8351 100644 --- a/docs/core/compatibility/toc.yml +++ b/docs/core/compatibility/toc.yml @@ -63,6 +63,8 @@ items: href: core-libraries/7.0/compressionlevel-validation.md - name: Cryptography items: + - name: Dynamic X509ChainPolicy verification time + href: cryptography/7.0/x509chainpolicy-verification-time.md - name: EnvelopedCms.Decrypt doesn't double unwrap href: cryptography/7.0/decrypt-envelopedcms.md - name: X500DistinguishedName parsing of friendly names @@ -899,6 +901,8 @@ items: items: - name: .NET 7 items: + - name: Dynamic X509ChainPolicy verification time + href: cryptography/7.0/x509chainpolicy-verification-time.md - name: EnvelopedCms.Decrypt doesn't double unwrap href: cryptography/7.0/decrypt-envelopedcms.md - name: X500DistinguishedName parsing of friendly names