In NuGet, what do dotnet nuget sign and dotnet nuget verify do, and when does restore itself check package signatures on Windows, Linux and macOS?
answer
- X.509 code-signing certificate plus timestamp
- author signature versus repository signature
- verify --all, --certificate-fingerprint
- signatureValidationMode require with trustedSigners
- DOTNET_NUGET_SIGNATURE_VERIFICATION
basics
~20 sdotnet nuget sign adds an author signature to a .nupkg with an X.509 code-signing certificate and a timestamp; dotnet nuget verify checks signatures. Restore verifies signatures by default on Windows and, since the .NET 8 SDK, on Linux; on macOS it is off by default.
solid answer
~40 s`dotnet nuget sign Shared.Validation.2.3.0.nupkg --certificate-path signing.pfx --certificate-password ... --timestamper <RFC 3161 URL>` embeds an **author signature**: proof of who produced the package and that its bytes have not changed since. The timestamp keeps the signature valid after the certificate expires. nuget.org adds a **repository signature** to every package it accepts, author-signed or not. `dotnet nuget verify --all` checks a package's signatures, and `--certificate-fingerprint` requires a specific signer. Restore also verifies implicitly: **always on Windows**, **by default on Linux since the .NET 8 SDK** and **off by default on macOS**, toggled with `DOTNET_NUGET_SIGNATURE_VERIFICATION`. To require trusted signatures, set `signatureValidationMode` to `require` in nuget.config and list `<trustedSigners>` (managed with `dotnet nuget trust`); the default mode is `accept`.
code
bash · 3 linesdotnet nuget verify artifacts/Shared.Validation.2.3.0.nupkg --all
dotnet nuget verify artifacts/Shared.Validation.2.3.0.nupkg \
--certificate-fingerprint "$PLATFORM_SIGNING_CERT_SHA256"go deeper
Recall that packages can be signed with dotnet nuget sign and checked with dotnet nuget verify, and that nuget.org signs every package it hosts.
Explain author versus repository signatures, why the timestamp matters, and the verify options for requiring a specific certificate.
Know the per-OS restore defaults, diagnose NU3018 on Linux, and configure signatureValidationMode require with trustedSigners for a repository.
Decide whether internal packages are author-signed, how certificates are issued and rotated, and whether consumers enforce trusted signers.
## What a signature adds A NuGet package signature is based on an **X.509 certificate** and stored inside the `.nupkg`. It proves two things to a consumer: who signed the package, and that the contents have not changed since. There are two kinds: - **Author signature** — added by the publisher with their own code-signing certificate. - **Repository signature** — added by a feed. nuget.org repository-signs **every** package it accepts, whether or not the author signed it, so integrity holds even when the package is mirrored elsewhere. ## Signing a package ```bash dotnet nuget sign artifacts/Shared.Validation.2.3.0.nupkg \ --certificate-path signing.pfx --certificate-password "$CERT_PASSWORD" \ --timestamper http://timestamp.example.internal ``` The certificate can instead come from a certificate store (`--certificate-store-name`, `--certificate-store-location` with `--certificate-subject-name` or `--certificate-fingerprint`). Other options: | Option | Purpose | |---|---| | `--timestamper` | RFC 3161 timestamp server; keeps the signature valid after the certificate expires | | `--hash-algorithm` / `--timestamp-hash-algorithm` | digest algorithms | | `-o`, `--output` | write the signed package elsewhere | | `--overwrite` | replace an existing signature; by default signing an already-signed package fails | Without a timestamp, the signature becomes invalid once the signing certificate expires, so every release would eventually fail verification. To publish an author-signed package on nuget.org, the certificate must be registered on the publishing account. ## Verifying explicitly `dotnet nuget verify` always performs signature verification: - `dotnet nuget verify Shared.Validation.2.3.0.nupkg --all` runs all checks. - `--certificate-fingerprint <sha256>` checks that the signer certificate matches one of the given SHA256 fingerprints; it can be repeated — a way to require your own signing certificate. - Today the command performs signature verification only; `--all` asks for every verification it supports. - `--configfile` applies the trust settings of a specific nuget.config. ## Verification during restore Restore also verifies signed packages, but the default depends on the operating system: | OS | Default during restore | Notes | |---|---|---| | Windows | always enabled | uses the Windows root store | | Linux | enabled since the .NET 8 SDK | opt out with `DOTNET_NUGET_SIGNATURE_VERIFICATION=false`; uses SDK certificate bundles or a system code-signing bundle | | macOS | disabled | can be opted in with the variable, but the docs recommend leaving it off | On Linux, a system code-signing bundle that lacks nuget.org's roots makes verification fail with an untrusted-root error (NU3018 or NU3028), which is a configuration problem, not a tampered package. ## Requiring trusted signers By default, `signatureValidationMode` is `accept`: valid signatures are checked, but unsigned packages are allowed. A tighter policy in the repository's nuget.config: 1. Set `<add key="signatureValidationMode" value="require" />` in the `config` section. 2. Add `<trustedSigners>` entries — an `author` with certificate fingerprints, or a `repository` such as nuget.org, optionally restricted to listed owners. 3. Manage the list with `dotnet nuget trust` instead of editing XML by hand. With `require`, the trusted signers list may not be empty, and packages that are not signed by a trusted author or repository fail restore. ## Choosing what to do for an internal library 1. Decide whether consumers need to know **who** built the package, or only that it was not altered in transit. Repository signatures and feed controls cover the second; author signing covers the first. 2. If author signing, keep the certificate in a signing service or secret store used only by the release job, and always pass `--timestamper`. 3. Publish the certificate's SHA256 fingerprint so consuming teams can add it to `trustedSigners` or check it with `dotnet nuget verify --certificate-fingerprint`. 4. Remember that `require` mode applies to every package a project restores, nuget.org packages included, so the trusted list must also cover the public repository before turning it on. ## Where this fits For the internal validation library, author signing lets consuming teams require the platform team's certificate fingerprint, which is useful when packages move between feeds. The broader question of signing as a supply-chain defence — what it does and does not prove — belongs with dependency-resolution security; here the point is the mechanics and defaults.
- Why is a timestamp essential when author-signing?A signature is only valid while its certificate is valid unless a trusted timestamp proves it was made during the certificate's lifetime. With `--timestamper`, packages signed today still verify after the certificate expires; without it, every old release would start failing verification.
- A Linux build agent fails restore with NU3018 on nuget.org packages that verify fine on Windows. What is likely wrong?Verification is on by default on Linux since the .NET 8 SDK, and NuGet prefers a system code-signing bundle if one exists. If that bundle lacks the roots nuget.org's signatures chain to, verification reports an untrusted root. Fix the bundle or let NuGet use the SDK's bundled certificates.
- Packages on nuget.org are unsigned unless the author signs them.
- A signature stays valid after the certificate expires even without a timestamp.
- Restore verifies signatures on every operating system by default.
- signatureValidationMode defaults to require, so unsigned packages fail restore.
- dotnet nuget verify only checks the package hash, not the signer.