NuGet.Home/accepted/archive/DotNetSignCommands.md

Spec Name

• Status: In Review
• Author(s): Kat Marchán
• Issue: 9010 Signing: Design dotnet package signing commands

Problem Background

We recently released cross-platform signature verification during restore for dotnet.exe. This means dotnet.exe users are going to start relying on this feature during restore for security. Unfortunately, nuget.exe has some signing-related commands that are not yet available in dotnet.exe, making the experience essentially incomplete for these customers.

Who are the customers

This feature is for dotnet.exe users who want to take advantage of more package signing-related features of nuget without needing to install nuget.exe.

Goals

Design and implement equivalent commands for the following nuget.exe commands:

• nuget.exe sign
• nuget.exe verify
• nuget.exe trusted-signers

These commands should have dotnet.exe-compatible syntax and ergonomics, and feel like proper dotnet.exe commands.

Non-Goals

Adding additional signing-related commands, or significantly changing/improving the behavior of the commands as currently designed.

Solution

The following commands will be implemented in the dotnet.exe CLI.

Options marked with * indicate a notable change in behavior/naming.

dotnet nuget sign

Signs a NuGet package at <package-path> with the specified certificate.

USAGE:
    dotnet nuget sign [OPTIONS] <package-path>

OPTIONS:
    -o, --output* <output-directory>    Directory where the signed package should be saved. By default, the original package is overwritten by the signed package.
        --certificate-path              File path to the certificate to be used while signing the package.
        --certificate-store-name        Name of the X.509 certificate store. (...)
        --certificate-store-location    Name of the X.509 certificate store to use to search for the certificate.
        --certificate-subject-name      Subject name of the certificate used to search a local certificate store for the certificate.
        --certificate-fingerprint       SHA-1 fingerprint of the certificate used to search a local certificate store for the certificate.
        --certificate-password          Password for the certificate, if needed.
        --hash-algorithm                Hash algorithm to be used to sign the package. Defaults to SHA256.
        --timestamper                   URL to an RFC 3161 timestamping server.
        --timestamp-hash-algorithm      Hash algorithm to be used by the RFC 3161 timestamping server. Defaults to SHA256.
        --overwrite                     Switch to indicate if the current signature should be overwritten.
    -h, --help                          Prints help information.
    -v, --verbosity* <LEVEL>            Set the MSBuild verbosity level. Allowed values are q[uiet], m[inimal], n[ormal], d[etailed], and diag[nostic].
        --interactive*                  Allows command to stop and wait for user input or action.
        --configfile                    The NuGet configuration file. If specified, only the settings from this file will be used. If not specified, the hierarchy of configuration files from the current directory will be used.

EXAMPLES:

    dotnet nuget sign --timestamper https://foo.bar MyPackage.nupkg

    dotnet nuget sign --timestamper https://foo.bar --output ../signed ../MyPackage.nupkg

Notable deviations from nuget.exe version:

• No -ForceEnglishOutput equivalent. dotnet.exe doesn't seem to do this at all.
• Use MSBuild verbosity levels for --verbosity instead of NuGet levels.
• Use --interactive instead of --non-interactive, because that's how dotnet.exe does it.
• Use --output instead of --output-directory for consistency with dotnet.exe.

dotnet nuget verify

Verifies a signed NuGet package at <package-path>.

USAGE:
    dotnet nuget verify [OPTIONS] <package-path>...*

OPTIONS:
        --all*                                  Specifies that all verifications possible should be performed on the package(s). By default, only signatures are verified.
        --certificate-fingerprint <fingerprint> Verify that the signer certificate matches with one of the specified SHA256 fingerprints. This option may be supplied multiple times to provide multiple fingerprints.
    -h, --help                                  Prints help information.
        --interactive*                          Allows command to stop and wait for user input or action.
        --configfile                    The NuGet configuration file. If specified, only the settings from this file will be used. If not specified, the hierarchy of configuration files from the current directory will be used.

Notable deviations from nuget.exe version:

• -Signatures has been removed and is now default. Use --all to perform -All.
• Multiple position arguments can be passed in to verify multiple packages, instead of only supporting globbing.
• No -ForceEnglishOutput equivalent. dotnet.exe doesn't seem to do this at all.
• Use MSBuild verbosity levels for --verbosity instead of NuGet levels.
• Use --interactive instead of --non-interactive, because that's how dotnet.exe does it.

Future Work

For now, we're not doing trusted-signer, and specifying all the behavior probably deserves its own spec because of the complexity of the command and the ergonomic expectations of dotnet.exe. Below is an initial stab at a design that should NOT be considered normative, but establishes some direction. Most notably, it splits the very complicated add, which has multiple gestures, into multiple, more specific subcommands with their own options and behavior.

dotnet nuget trusted-signer

Provides the ability to manage the list of trusted signers.

USAGE:
    dotnet nuget trusted-signer [OPTIONS] [COMMAND]

COMMANDS:
    list (default)
    add-repository <name> <repository> [<package>...]
    add-author <name> <author> [<package>...]
    add-service-index <name> <index>
    add-certificate <name> <fingerprint>
    remove <name>
    sync <name>

Open Questions

Is there any precedent at all in dotnet.exe for a --config-file option? Anywhere?

Considerations

References