NuGet Verify Command

Status: Reviewed

Issue

Task for Specing and Task for execution

Problem

Signed packages help with authenticity and integrity of a package when it is being consumed by NuGet users. Currently there is no way to verify that a signature in a package is valid.

Who is the customer?

All NuGet package authors and NuGet package consumers.

Evidence

Part of the larger package signing effort.

Solution

We will add a first level command to NuGet.exe which will allow package authors and package sources to verify NuGet packages, this command will have a flag for signatures verification.

Command Signature

usage: NuGet verify -Signatures <package_path>  [options]

Verifies a NuGet package.

argument:

    -Signatures - Specifies the type of verification to be done. Currently only signatures verification is supported.
    
    package_path -  Path to the package(s) that needs to be verified.

options:

    -Verbosity <level> - Specifies the level of detail displayed in the output: quiet, normal, 

    -CertificateFingerprint "<cert_fingerprint>;..." - Verify that the signer certificate matches with one of the specified fingerprints.
                                     The hashing algorithm used to match the certificate is SHA256 
                                     A certificate fingerprint is a hash of the certificate used to identify the certificate.
                                     If more than one fingerprint is provided, the input should be a string with each fingerprint separated by a semicolon.

    -ConfigFile - Specifies NuGet.Config file for repository signature verification.

Return Value

Verify Command returns one of the following exit codes when it terminates.

Exit code	Description
0	Execution was successful.
1	Execution has failed.

If multiple packages are provided, an error in one package will not be fatal to the verification of the other packages. If multiple errors and warning are present, they will be displayed on the console.

Config file for repository signature verification

"NuGet.exe verify -signature" verifies repository signature if the package have repository signature.

NuGet.Config stores trusted repository for repository signature verification.

• If the NuGet.Config is provided by specifying -ConfigFile, verify command uses only the specified config file to do verification.
• If no specified NuGet.Config file, verify command uses the NuGet.Config chain which includes all NuGet.Config files from working directory to driver root and NuGet.Config in %AppData%\NuGet\NuGet.Config

Verbosity details

The details that should be displayed on each verbosity level are described below. Each level should display the same as the level below plus whatever is specified in that level. In that sense, quiet will be give the less amount of information, while detailed the most.

quiet

• No output on successful execution and minimal output for failed execution.

normal

• Path to package being verified
• For each signature present
  • Type of signature (author or repository)
  • Hashing algorithm used for signature
  • Information about the signing certificate
  • Information about the timestamper certificate

detailed

• Information about signing certificate's chain
• Information about Timestamper certificate's chain

For each certificate show:

• Issued to
• Issued by
• Expires
• Sha1 Fingerprint
• Fingerprint with provided algorithm in -FingerprintAlgorithm option

Warnings are errors should be displayed if present no matter the verbosity level chosen.

Corresponding commands

In future we would like to add support for the following platforms -

• Dotnet CLI - dotnet nuget verify -Signatures <package_path> [Options]

• MSBuild target - msbuild /t:verifypackage -Signaturues <package_path> [Options]

Feedback

Please use the tracking issue to provide feedback or any questions that you might have. Thanks!

---