diff --git a/docs/core/compatibility/10.0.md b/docs/core/compatibility/10.0.md index 6406589933843..73b6d93c8fb92 100644 --- a/docs/core/compatibility/10.0.md +++ b/docs/core/compatibility/10.0.md @@ -97,6 +97,7 @@ If you're migrating an app to .NET 10, the breaking changes listed here might af | [Default workload configuration from 'loose manifests' to 'workload sets' mode](sdk/10.0/default-workload-config.md) | Behavioral change | Preview 2 | | [`dotnet package list` performs restore](sdk/10.0/dotnet-package-list-restore.md) | Behavioral change | Preview 4 | | [`dotnet restore` audits transitive packages](sdk/10.0/nugetaudit-transitive-packages.md) | Behavioral change | Preview 3 | +| [SHA-1 fingerprint support deprecated in `dotnet nuget sign`](sdk/10.0/dotnet-nuget-sign-sha1-deprecated.md) | Behavioral change | Preview 1 | | [MSBUILDCUSTOMBUILDEVENTWARNING escape hatch removed](sdk/10.0/custom-build-event-warning.md) | Behavioral change | Preview 1 | | [MSBuild custom culture resource handling](sdk/10.0/msbuild-custom-culture.md) | Behavioral change | Preview 1 | | [NU1510 is raised for direct references pruned by NuGet](sdk/10.0/nu1510-pruned-references.md) | Source incompatible | Preview 1 | diff --git a/docs/core/compatibility/sdk/10.0/dotnet-nuget-sign-sha1-deprecated.md b/docs/core/compatibility/sdk/10.0/dotnet-nuget-sign-sha1-deprecated.md new file mode 100644 index 0000000000000..00fa7540cca85 --- /dev/null +++ b/docs/core/compatibility/sdk/10.0/dotnet-nuget-sign-sha1-deprecated.md @@ -0,0 +1,48 @@ +--- +title: "Breaking change - SHA-1 fingerprint support deprecated in dotnet nuget sign" +description: "Learn about the breaking change in .NET 10 where SHA-1 fingerprint support is deprecated in dotnet nuget sign command, promoting NU3043 warning to error." +ms.date: 08/11/2025 +ai-usage: ai-assisted +ms.custom: https://github.com/dotnet/docs/issues/47449 +--- + +# SHA-1 fingerprint support deprecated in `dotnet nuget sign` + +Starting in .NET 10, the [NU3043](/nuget/reference/errors-and-warnings/nu3043) warning is promoted to an error when using SHA-1 fingerprints with the [`dotnet nuget sign` command](../../../tools/dotnet-nuget-sign.md). This change enforces the use of only strong, approved hash algorithms (SHA-2 family) for signing operations. + +## Version introduced + +.NET 10 Preview 1 + +## Previous behavior + +In .NET 9 SDK, the `dotnet nuget sign` command accepted certificate fingerprints using SHA-1 and SHA-2 family algorithms (SHA256, SHA384, SHA512). If a SHA-1 fingerprint was used, a warning (NU3043) was issued, indicating the use of an insecure hashing algorithm, but the operation continued successfully. + +## New behavior + +Starting in .NET 10, the NU3043 warning is elevated to an error. This change blocks the use of SHA-1 fingerprints with the `--certificate-fingerprint` option in the `dotnet nuget sign` command, improving overall signing security. + +## Type of breaking change + +This is a [behavioral change](../../categories.md#behavioral-change). + +## Reason for change + +This change was made to enforce stronger security standards by disallowing the use of SHA-1 for certificate fingerprinting. SHA-1 is considered cryptographically weak and vulnerable to collision attacks. + +## Recommended action + +Update the usage of `dotnet nuget sign` to use fingerprints from the SHA-2 family only: + +- SHA256 (recommended) +- SHA384 +- SHA512 + +## Affected APIs + +None. + +## See also + +- [dotnet nuget sign](../../../tools/dotnet-nuget-sign.md) +- [NuGet warning NU3043](/nuget/reference/errors-and-warnings/nu3043) diff --git a/docs/core/compatibility/toc.yml b/docs/core/compatibility/toc.yml index 9f99fed62c5cb..1f9f8bfefdfa0 100644 --- a/docs/core/compatibility/toc.yml +++ b/docs/core/compatibility/toc.yml @@ -462,6 +462,8 @@ items: href: sdk/8.0/rid-graph.md - name: Setting DebugSymbols to false disables PDB generation href: sdk/8.0/debugsymbols.md + - name: "SHA-1 fingerprint support deprecated in 'dotnet nuget sign'" + href: sdk/10.0/dotnet-nuget-sign-sha1-deprecated.md - name: Source Link included in the .NET SDK href: sdk/8.0/source-link.md - name: Trimming can't be used with .NET Standard or .NET Framework diff --git a/docs/core/tools/dotnet-nuget-sign.md b/docs/core/tools/dotnet-nuget-sign.md index bff870f0ceeba..b975e8cb02a02 100644 --- a/docs/core/tools/dotnet-nuget-sign.md +++ b/docs/core/tools/dotnet-nuget-sign.md @@ -2,7 +2,7 @@ title: dotnet nuget sign command description: The dotnet nuget sign command signs all the packages matching the first argument with a certificate. author: heng-liu -ms.date: 07/07/2021 +ms.date: 08/11/2025 --- # dotnet nuget sign @@ -36,8 +36,8 @@ dotnet nuget sign -h|--help The `dotnet nuget sign` command signs all the packages matching the first argument with a certificate. The certificate with the private key can be obtained from a file or from a certificate installed in a certificate store by providing a subject name or a SHA-1 fingerprint. - > [!NOTE] - > This command requires a certificate root store that is valid for both code signing and timestamping. Also, this command may not be supported on some combinations of operating system and .NET SDK. For more information, see [NuGet signed package verification](nuget-signed-package-verification.md). +> [!NOTE] +> This command requires a certificate root store that's valid for both code signing and timestamping. Also, this command might not be supported on some combinations of operating system and .NET SDK. For more information, see [NuGet signed package verification](nuget-signed-package-verification.md). ## Arguments @@ -73,10 +73,9 @@ The `dotnet nuget sign` command signs all the packages matching the first argume Specifies the fingerprint of the certificate used to search a local certificate store for the certificate. - Starting with .NET 9, this option can be used to specify the SHA-1, SHA-256, SHA-384, or SHA-512 fingerprint of the certificate. - However, a `NU3043` warning is raised when a SHA-1 certificate fingerprint is used because it is no longer considered secure. + Starting with .NET 9, this option can be used to specify the SHA-1, SHA-256, SHA-384, or SHA-512 fingerprint of the certificate. However, a `NU3043` warning is raised when a SHA-1 certificate fingerprint is used because it's no longer considered secure. In .NET 10 and later versions, [the warning is elevated to an error](../compatibility/sdk/10.0/dotnet-nuget-sign-sha1-deprecated.md). Only SHA-2 family fingerprints (SHA-256, SHA-384, and SHA-512) are supported. - All the previous versions of the .NET SDK continue to accept only SHA-1 certificate fingerprint. + All pre-.NET 9 versions of the .NET SDK continue to accept only SHA-1 certificate fingerprint. - **`--certificate-password `** @@ -123,10 +122,10 @@ The `dotnet nuget sign` command signs all the packages matching the first argume dotnet nuget sign foo.nupkg --certificate-path cert.pfx --certificate-password password ``` -- Sign *foo.nupkg* with certificate (password protected) matches with the specified SHA-1 fingerprint in the default certificate store (CurrentUser\My): +- Sign *foo.nupkg* with certificate (password protected) matches with the specified SHA-256 fingerprint in the default certificate store (CurrentUser\My): ```dotnetcli - dotnet nuget sign foo.nupkg --certificate-fingerprint 89967D1DD995010B6C66AE24FF8E66885E6E03A8 --certificate-password password + dotnet nuget sign foo.nupkg --certificate-fingerprint B2C40F2F8775D7B7EBEB76BD5A9D3A4BC3F4B8A4D8D7C5F8A4C6B3E7A9E2D5F1 --certificate-password password ``` - Sign *foo.nupkg* with certificate (password protected) matches with the specified subject name :::no-loc text="\"Test certificate for testing signing\""::: in the default certificate store (CurrentUser\My): @@ -135,10 +134,10 @@ The `dotnet nuget sign` command signs all the packages matching the first argume dotnet nuget sign foo.nupkg --certificate-subject-name "Test certificate for testing signing" --certificate-password password ``` -- Sign *foo.nupkg* with certificate (password protected) matches with the specified SHA-1 fingerprint in the certificate store CurrentUser\Root: +- Sign *foo.nupkg* with certificate (password protected) matches with the specified SHA-256 fingerprint in the certificate store CurrentUser\Root: ```dotnetcli - dotnet nuget sign foo.nupkg --certificate-fingerprint 89967D1DD995010B6C66AE24FF8E66885E6E03A8 --certificate-password password --certificate-store-location CurrentUser --certificate-store-name Root + dotnet nuget sign foo.nupkg --certificate-fingerprint B2C40F2F8775D7B7EBEB76BD5A9D3A4BC3F4B8A4D8D7C5F8A4C6B3E7A9E2D5F1 --certificate-password password --certificate-store-location CurrentUser --certificate-store-name Root ``` - Sign multiple NuGet packages - *foo.nupkg* and *all .nupkg files in the directory specified* with certificate *cert.pfx* (not password protected):