You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/core/compatibility/core-libraries/9.0/obsolete-apis-with-custom-diagnostics.md
+38-1Lines changed: 38 additions & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -2,7 +2,7 @@
2
2
title: "Breaking change: .NET 9 obsoletions with custom IDs"
3
3
titleSuffix: ""
4
4
description: Learn about the .NET 9 breaking change in core .NET libraries where some APIs have been marked as obsolete with a custom diagnostic ID.
5
-
ms.date: 05/09/2024
5
+
ms.date: 08/01/2024
6
6
---
7
7
# API obsoletions with non-default diagnostic IDs (.NET 9)
8
8
@@ -19,6 +19,7 @@ The following table lists the custom diagnostic IDs and their corresponding warn
19
19
|[SYSLIB0009](../../../../fundamentals/syslib-diagnostics/syslib0009.md)|<xref:System.Net.AuthenticationManager> is not supported. Methods will no-op or throw <xref:System.PlatformNotSupportedException>. | Warning |
20
20
|[SYSLIB0054](../../../../fundamentals/syslib-diagnostics/syslib0054.md)|<xref:System.Threading.Thread.VolatileRead%2A?displayProperty=nameWithType> and <xref:System.Threading.Thread.VolatileWrite%2A?displayProperty=nameWithType> are obsolete. Use <xref:System.Threading.Volatile.Read%2A?displayProperty=nameWithType> or <xref:System.Threading.Volatile.Write%2A?displayProperty=nameWithType> instead. | Warning |
21
21
|[SYSLIB0055](../../../../fundamentals/syslib-diagnostics/syslib0055.md)|`AdvSimd.ShiftRightLogicalRoundedNarrowingSaturate*` methods with signed parameters are obsolete. Use the unsigned overloads instead. | Warning |
22
+
|[SYSLIB0057](../../../../fundamentals/syslib-diagnostics/syslib0057.md)|`X509Certificate2` and `X509Certificate` constructors for binary and file content are obsolete. | Warning |
22
23
23
24
## Version introduced
24
25
@@ -57,6 +58,42 @@ These obsoletions can affect [source compatibility](../../categories.md#source-c
title: "Breaking change: SafeEvpPKeyHandle.DuplicateHandle up-refs the handle"
3
+
description: Learn about the .NET 9 breaking change in cryptography where SafeEvpPKeyHandle.DuplicateHandle now increments the reference count of the EVP_PKEY handle instead of creating a new instance.
4
+
ms.date: 08/05/2024
5
+
---
6
+
# SafeEvpPKeyHandle.DuplicateHandle up-refs the handle
7
+
8
+
Along with work to enable OpenSSL providers support, a change was made to the <xref:System.Security.Cryptography.SafeEvpPKeyHandle.DuplicateHandle?displayProperty=nameWithType> method that impacts the <xref:System.Security.Cryptography.ECDsaOpenSsl> and <xref:System.Security.Cryptography.RSAOpenSsl> constructors that take a <xref:System.Security.Cryptography.SafeEvpPKeyHandle>. External modifications of the passed handle now also affect the handle stored in instances of those classes.
9
+
10
+
## Previous behavior
11
+
12
+
<xref:System.Security.Cryptography.SafeEvpPKeyHandle.DuplicateHandle> created a new `EVP_PKEY` instance. Modifications to the duplicated key (that is, through direct calls to OpenSSL APIs) did not impact the original key. `SafeEvpPKeyHandle.DuplicateHandle` was called by the constructors of <xref:System.Security.Cryptography.ECDsaOpenSsl> and <xref:System.Security.Cryptography.RSAOpenSsl> that take a <xref:System.Security.Cryptography.SafeEvpPKeyHandle>.
13
+
14
+
## New behavior
15
+
16
+
<xref:System.Security.Cryptography.SafeEvpPKeyHandle.DuplicateHandle> increments the reference count of the existing `EVP_PKEY` and returns a handle to the same key. That means external calls to OpenSSL APIs that modify `EVP_PKEY` now also affect instances of the duplicated <xref:System.Security.Cryptography.SafeEvpPKeyHandle>. Those APIs include <xref:System.Security.Cryptography.ECDsaOpenSsl> and <xref:System.Security.Cryptography.RSAOpenSsl> instances created from such handles.
17
+
18
+
## Version introduced
19
+
20
+
.NET 9 Preview 7
21
+
22
+
## Type of breaking change
23
+
24
+
This change is a [behavioral change](../../categories.md#behavioral-change).
25
+
26
+
## Reason for change
27
+
28
+
This change was made to enable OpenSSL providers support. As a side effect, there are also some performance improvements.
29
+
30
+
## Recommended action
31
+
32
+
Avoid modifications of `EVP_PKEY` passed in to .NET APIs. If you can't avoid modifications to `EVP_PKEY`, create a copy of `EVP_PKEY` yourself (that is, copy parameters into the new `EVP_PKEY` instance).
Every API that accepts an <Xref:System.Security.Cryptography.RSA> or <Xref:System.Security.Cryptography.ECDsa> instance that originates from <xref:System.Security.Cryptography.SafeEvpPKeyHandle> is also affected.
title: "Some X509Certificate2 and X509Certificate constructors are obsolete"
3
+
description: Learn about the .NET 9 breaking change in cryptography where X509Certificate2 and X509Certificate constructors for binary and file content are obsolete.
4
+
ms.date: 08/01/2024
5
+
---
6
+
# Some X509Certificate2 and X509Certificate constructors are obsolete
7
+
8
+
The constructors on <xref:System.Security.Cryptography.X509Certificates.X509Certificate> and <xref:System.Security.Cryptography.X509Certificates.X509Certificate2> that accept content as a `byte[]`, `ReadOnlySpan<byte>`, or a `string` file path are obsolete, starting in .NET 9. The <xref:System.Security.Cryptography.X509Certificates.X509Certificate2Collection.Import%2A> methods on X509Certificate2Collection are also obsolete. Calling them in code generates warning `SYSLIB0057` at compile time.
9
+
10
+
## Previous behavior
11
+
12
+
Developers could use the affected APIs without an obsolete warning.
13
+
14
+
## New behavior
15
+
16
+
Affected APIs will receive an obsolete compilation warning with ID [SYSLIB0057](../../../../fundamentals/syslib-diagnostics/syslib0057.md).
17
+
18
+
## Version introduced
19
+
20
+
.NET 9 Preview 7
21
+
22
+
## Type of breaking change
23
+
24
+
This change can affect [source compatibility](../../categories.md#source-compatibility).
25
+
26
+
## Reason for change
27
+
28
+
The affected APIs supported loading certificates in multiple formats. For example, `new X509Certificate2(data)` loaded a certificate from a `byte[]` called `data`. `data` could be one of any supported format, including X.509, PKCS7, or PKCS12/PFX.
29
+
30
+
While this method was easy to use, it created issues where user-supplied data was passed with a different format than intended. This might allow loading PKCS12 where only X.509 content was intended to be loaded. Or it might create interoperability issues from handling the data in different ways.
31
+
32
+
## Recommended action
33
+
34
+
For workarounds, see [Workaround](../../../../fundamentals/syslib-diagnostics/syslib0057.md#workaround).
35
+
36
+
## Affected APIs
37
+
38
+
For affected APIs, see [SYSLIB0057](../../core-libraries/9.0/obsolete-apis-with-custom-diagnostics.md#syslib0057).
Copy file name to clipboardExpand all lines: docs/fundamentals/syslib-diagnostics/obsoletions-overview.md
+2-1Lines changed: 2 additions & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -2,7 +2,7 @@
2
2
title: Obsolete features in .NET 5+
3
3
titleSuffix: ""
4
4
description: Learn about APIs that are marked as obsolete in .NET 5 and later versions that produce SYSLIB compiler warnings.
5
-
ms.date: 05/09/2024
5
+
ms.date: 08/01/2024
6
6
---
7
7
8
8
# Obsolete features in .NET 5+
@@ -76,6 +76,7 @@ The following table provides an index to the `SYSLIB0XXX` obsoletions in .NET 5+
76
76
|[SYSLIB0053](syslib0053.md)| Warning |<xref:System.Security.Cryptography.AesGcm> should indicate the required tag size for encryption and decryption. Use a constructor that accepts the tag size. |
77
77
|[SYSLIB0054](syslib0054.md)| Warning |<xref:System.Threading.Thread.VolatileRead%2A?displayProperty=nameWithType> and <xref:System.Threading.Thread.VolatileWrite%2A?displayProperty=nameWithType> are obsolete. Use <xref:System.Threading.Volatile.Read%2A?displayProperty=nameWithType> or <xref:System.Threading.Volatile.Write%2A?displayProperty=nameWithType> instead. |
78
78
|[SYSLIB0055](syslib0055.md)| Warning |`AdvSimd.ShiftRightLogicalRoundedNarrowingSaturate*` methods with signed parameters are obsolete. Use the unsigned overloads instead. |
79
+
|[SYSLIB0057](syslib0057.md)| Warning |`X509Certificate2` and `X509Certificate` constructors for binary and file content are obsolete. |
title: SYSLIB0057 warning - X509Certificate2 and X509Certificate constructors for binary and file content are obsolete
3
+
description: Learn about the obsoletion of some X509Certificate2 and X509Certificate constructors that generates compile-time warning SYSLIB0057.
4
+
ms.date: 08/01/2024
5
+
f1_keywords:
6
+
- SYSLIB0057
7
+
---
8
+
# SYSLIB0057: X509Certificate2 and X509Certificate constructors for binary and file content are obsolete
9
+
10
+
The constructors on <xref:System.Security.Cryptography.X509Certificates.X509Certificate> and <xref:System.Security.Cryptography.X509Certificates.X509Certificate2> that accept content as a `byte[]`, `ReadOnlySpan<byte>`, or a `string` file path are obsolete, starting in .NET 9. The <xref:System.Security.Cryptography.X509Certificates.X509Certificate2Collection.Import%2A> methods on X509Certificate2Collection are also obsolete. Calling them in code generates warning `SYSLIB0057` at compile time.
11
+
12
+
## Reason for obsoletion
13
+
14
+
The affected APIs supported loading certificates in multiple formats. For example, `new X509Certificate2(data)` loaded a certificate from a `byte[]` called `data`. `data` could be one of any supported format, including X.509, PKCS7, or PKCS12/PFX.
15
+
16
+
While this method was easy to use, it created issues where user-supplied data was passed with a different format than intended. This might allow loading PKCS12 where only X.509 content was intended to be loaded. Or it might create interoperability issues from handling the data in different ways.
17
+
18
+
## Workaround
19
+
20
+
Use a different API to load certificate content, depending on the intended content type.
21
+
22
+
A new class called `X509CertificateLoader`<!--<xref:System.Security.Cryptography.X509Certificates.X509CertificateLoader>--> can be used to load X.509 or PKCS12 content:
23
+
24
+
- If you're loading X.509 content, use `X509CertificateLoader.LoadCertificate` or `X509CertificateLoader.LoadCertificateFromFile`.
25
+
- If you're loading PKCS12 content, use `X509CertificateLoader.LoadPkcs12`, `X509CertificateLoader.LoadPkcs12FromFile`, `X509CertificateLoader.LoadPkcs12Collection`, or `X509CertificateLoader.LoadPkcs12CollectionFromFile`.
26
+
- If you're loading PKCS7 content, use <xref:System.Security.Cryptography.Pkcs.SignedCms > from the System.Security.Cryptography.Pkcs package to inspect certificates in PKCS7 content.
27
+
- If you're uncertain about the content type you're loading, use <xref:System.Security.Cryptography.X509Certificates.X509Certificate2.GetCertContentType%2A> to determine the content type and call the appropriate API.
28
+
29
+
The [Microsoft.Bcl.Cryptography package](https://www.nuget.org/packages/Microsoft.Bcl.Cryptography/) supplies `X509CertificateLoader` for .NET Framework and .NET Standard.
30
+
31
+
## Suppress a warning
32
+
33
+
If you must use the obsolete APIs, you can suppress the warning in code or in your project file.
34
+
35
+
To suppress only a single violation, add preprocessor directives to your source file to disable and then re-enable the warning.
36
+
37
+
```csharp
38
+
// Disable the warning.
39
+
#pragmawarningdisable SYSLIB0057
40
+
41
+
// Code that uses obsolete API.
42
+
// ...
43
+
44
+
// Re-enable the warning.
45
+
#pragmawarningrestore SYSLIB0057
46
+
```
47
+
48
+
To suppress all the `SYSLIB0057` warnings in your project, add a `<NoWarn>` property to your project file.
49
+
50
+
```xml
51
+
<ProjectSdk="Microsoft.NET.Sdk">
52
+
<PropertyGroup>
53
+
...
54
+
<NoWarn>$(NoWarn);SYSLIB0057</NoWarn>
55
+
</PropertyGroup>
56
+
</Project>
57
+
```
58
+
59
+
For more information, see [Suppress warnings](obsoletions-overview.md#suppress-warnings).
0 commit comments