Update NU3028/NU3037 documentation (#3131)

dtivel · web-flow · commit 74a3ba18fb65 · 2023-09-05T14:47:54.000-07:00
Resolve https://github.com/NuGet/docs.microsoft.com-nuget/issues/3130.
diff --git a/docs/TOC.md b/docs/TOC.md
@@ -58,7 +58,8 @@
 ### [Create a package with COM interop assemblies](create-packages/author-packages-with-COM-interop-assemblies.md)
 ## Sign packages
 ### [Sign a package](create-packages/sign-a-package.md)
-### [Signed package signatures and requirements](reference/signed-packages-reference.md)
+### [Signed-package signatures and requirements](reference/signed-packages-reference.md)
+### [Signed-package verification options](reference/Signed-Package-Verification-Options.md)
 # Publish packages
 ## Publish to NuGet.org
 ### [Publish a package](nuget-org/publish-a-package.md)
diff --git a/docs/reference/Signed-Package-Verification-Options.md b/docs/reference/Signed-Package-Verification-Options.md
@@ -0,0 +1,33 @@
+---
+title: NuGet Signed-Package Verification Options
+description: Options for NuGet signed-package verification
+author: dtivel
+ms.author: dtivel
+ms.date: 09/01/2023
+ms.topic: reference
+---
+
+# NuGet signed-package verification options
+
+## Retry untrusted root failures
+
+> [!Note]
+> This issue only applies to Windows for root certificates in the [Microsoft Trusted Root Program](https://aka.ms/RootCert).
+
+During certificate chain building, Windows fetches relevant 3rd party root certificates on first use and adds them as locally trusted root certificates.  Internally, Windows initiates this network fetch with an RPC call, and if the system is sufficiently busy, this RPC call may fail.  This failure results in the root certificate not being locally trusted.  This issue may occur the first time a root certificate is observed, but once the root certificate has been locally trusted, the issue will not recur for that certificate.  Typically, chain building will succeed with retries.
+
+For NuGet users, symptoms of this issue are that the NuGet operation will typically succeed on retry and either of the following:
+
+* [NU3028](errors-and-warnings/NU3028.md) with a message like "A certification chain processed correctly but terminated in a root certificate that is not trusted by the trust provider."
+* [NU3037](errors-and-warnings/NU3037.md) with a message like "The repository primary signature validity period has expired."
+
+> [!Note]
+> This option is available starting from NuGet 6.0.0 and only applies to the Windows-specific failure described above.  The option does not apply to any other scenario and has no effect on Linux or macOS.
+
+You can opt-in to an experimental, automatic retry for untrusted root failures on Windows by setting an environment variable named `NUGET_EXPERIMENTAL_CHAIN_BUILD_RETRY_POLICY` with a value consisting of 2 comma-delimited positive integers representing retry count and sleep interval in milliseconds, respectively. There are no default values; you need to pick retry values that are sensible for you.
+
+For example, setting the environment variable to a value of `3,1000` like so:
+
+<pre>set NUGET_EXPERIMENTAL_CHAIN_BUILD_RETRY_POLICY=3,1000</pre>
+
+...would try up to 4 times (initial try plus 3 retries) with 1 second (1,000 ms) between each try.
diff --git a/docs/reference/errors-and-warnings/NU3028.md b/docs/reference/errors-and-warnings/NU3028.md
@@ -17,16 +17,19 @@ f1_keywords:
 <pre>The author primary signature's timestamp found a chain building issue: The revocation function was unable to check revocation because the revocation server could not be reached. For more information, visit https://aka.ms/certificateRevocationMode</pre>
 
 ### Issue
+
 Certificate chain building failed for the timestamp signature. The timestamp signing certificate is untrusted, revoked, or revocation information for the certificate is unavailable.
 
-On Windows only, this issue may occur the first time a root certificate is observed.  During certificate chain building, Windows fetches relevant 3rd party root certificates on first use and adds them as locally trusted root certificates.  Internally, Windows initiates this network fetch with an RPC call, and if the system is sufficiently busy, this RPC call may fail.  This failure results in the root certificate not being locally trusted.  For NuGet users, the resulting error is "A certification chain processed correctly but terminated in a root certificate that is not trusted by the trust provider."
+On Windows only, NU3028 may occur the first time a root certificate is observed and with the message "A certification chain processed correctly but terminated in a root certificate that is not trusted by the trust provider."  If the issue is resolved with retries, [there is an option which may help](../Signed-Package-Verification-Options.md#retry-untrusted-root-failures).
 
 ### Solution
+
 Use a trusted and valid certificate. Check internet connectivity.
 
 For Linux and macOS, see [NuGet signed-package verification](/dotnet/core/tools/nuget-signed-package-verification).  Specifically for untrusted root certificate warnings/errors on Linux and macOS, also see [NU3042](NU3042.md).
 
 #### Revocation check mode
+
 > [!Note]
 > This option is available starting from NuGet 4.8.1.
 
@@ -40,18 +43,6 @@ When the revocation check mode is set to `offline`, the warning will be downgrad
 
 <pre>The author primary signature's timestamp found a chain building issue: The revocation function was unable to check revocation because the certificate is not available in the cached certificate revocation list and NUGET_CERT_REVOCATION_MODE environment variable has been set to offline. For more information, visit https://aka.ms/certificateRevocationMode.</pre>
 
-#### Retry untrusted root failures
-> [!Note]
-> This option is available starting from NuGet 6.0.0 Preview 5 and only applies to the Windows-specific failure described in the [Issue](#issue) section.
-
-Retrying will typically succeed.  You can opt-in to an experimental, automatic retry for untrusted root failures on Windows by setting an environment variable named `NUGET_EXPERIMENTAL_CHAIN_BUILD_RETRY_POLICY` with a value consisting of 2 comma-delimited positive integers representing retry count and sleep interval in milliseconds, respectively. There are no default values; you need to pick retry values that are sensible for you.
-
-For example, setting the environment variable to a value of `3,1000` like so:
-
-<pre>set NUGET_EXPERIMENTAL_CHAIN_BUILD_RETRY_POLICY=3,1000</pre>
-
-...would try up to 4 times (initial try plus 3 retries) with 1 second (1,000 ms) between each try.
-
 > [!Note]
 > NU3028 is raised as an error in most cases. 
-> When NuGet’s [signature validation mode](../../consume-packages/installing-signed-packages.md#configure-package-signature-requirements) is set to accept (default), NU3028 is raised as a warning in some cases.
+> When NuGet’s [signature validation mode](../../consume-packages/installing-signed-packages.md#configure-package-signature-requirements) is set to accept (default), NU3028 is raised as a warning in some cases.
diff --git a/docs/reference/errors-and-warnings/NU3037.md b/docs/reference/errors-and-warnings/NU3037.md
@@ -18,6 +18,7 @@ A NuGet package signature has expired.
 A package signature shares the same validity period as the certificate used to generate the signature. A package signature is invalid outside of that validity period.
 To ensure long-term validity --- even beyond the signing certificate’s validity period --- a package signature should be timestamped with a trusted timestamp. Trusted timestamps must be added while a package signature is still valid and not expired.
 
+On Windows only, NU3037 may occur the first time a root certificate is observed and with the message "The repository primary signature validity period has expired."  If the issue is resolved with retries, [there is an option which may help](../Signed-Package-Verification-Options.md#retry-untrusted-root-failures).
 
 ### Solution
 
