[Spec] NuGet Package Signing Client Policy

Status: Incubation

Issue

Parent spec - Repository-Signatures
Related Spec - Trusted Sources

Problem

As we enable author and repository package signing, we need to enable consumers to be able to control the NuGet package signing client policies. Further, the information needs to be stored into the users machine.

Who is the customer?

All NuGet package consumers.

Scenarios

Enable package consumers to store NuGet package signing client policies.

Solution

• Define NuGet package signing client policies.
• Update the schema for nuget.config file to be able to store NuGet package signing client policies.
• Define a gesture for users to be able to choose NuGet package signing client policies.

NuGet package signing client policies have been outlined in the Repository-Signatures spec. This spec proposes schema changes to nuget.config and user gestures. Further, the spec outlines a rollout plan for the default mode for NuGet clients.

Client Policy Information Location

We should store the selected client policy for the user in a nuget.config file as a configuration.

Client Policy Information Schema

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <config>
    <add key="signatureValidationMode" value="MODE" />
  </config>
</configuration>

The key and value are case insensitive.

For example -

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <packageSources>
    <add key="NuGet.Org" value="https://api.nuget.org/v3/index.json" />
  </packageSources>
  <config>
    <add key="signatureValidationMode" value="accept" />
  </config>
</configuration>

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <packageSources>
    <add key="NuGet.Org" value="https://api.nuget.org/v3/index.json" />
  </packageSources>
  <config>
    <add key="signatureValidationMode" value="require" />
  </config>
</configuration>

Client Policy Information Gesture

To set the NuGet package signing client policy, users can use the existing nuget config command.

Set

NuGet.exe config -set signatureValidationMode=accept

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <packageSources>
    <add key="NuGet.Org" value="https://api.nuget.org/v3/index.json" />
  </packageSources>
  <config>
    <add key="signatureValidationMode" value="accept" />
  </config>
</configuration>

NuGet.exe config -set signatureValidationMode=require

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <packageSources>
    <add key="NuGet.Org" value="https://api.nuget.org/v3/index.json" />
  </packageSources>
  <config>
    <add key="signatureValidationMode" value="require" />
  </config>
</configuration>

Update

NuGet.exe config -set signatureValidationMode=require

Before -

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <packageSources>
    <add key="NuGet.Org" value="https://api.nuget.org/v3/index.json" />
  </packageSources>
  <config>
    <add key="signatureValidationMode" value="accept" />
  </config>
</configuration>

After -

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <packageSources>
    <add key="NuGet.Org" value="https://api.nuget.org/v3/index.json" />
  </packageSources>
  <config>
    <add key="signatureValidationMode" value="require" />
  </config>
</configuration>

Remove

NuGet.exe config -set signatureValidationMode=

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <packageSources>
    <add key="NuGet.Org" value="https://api.nuget.org/v3/index.json" />
  </packageSources>
</configuration>

Default Value -

If signatureValidationMode is not set then NuGet Client should read that as accept mode.

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <packageSources>
    <add key="NuGet.Org" value="https://api.nuget.org/v3/index.json" />
  </packageSources>
</configuration>

The above config should be read as having signatureValidationMode=accept.

Invalid Value -

If signatureValidationMode is set to any value other than the supported modes, then NuGet Client should read that as accept mode and warn the user with a message requesting them to fix the mode value.

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <packageSources>
    <add key="NuGet.Org" value="https://api.nuget.org/v3/index.json" />
  </packageSources>
  <config>
    <add key="signatureValidationMode" value="RANDOM" />
  </config>
</configuration>

The above config should be read as having signatureValidationMode=accept and the following message should be shown to the user -

NUxxxx: Invalid signatureValidationMode found in config file <path>. Defaulting to accept mode. Please set it to one of the supported modes by running the nuget config command. 
For more information, visit http://docs.nuget.org/docs/reference/command-line-reference.

Client Policy in Visual Studio -

We should add support for the following in Visual Studio NuGet options control -

• Add a drop down menu to enable users to choose a NuGet package signing client policy -
  

Impact of repository signing to client policies -

Accept mode -

• By default NuGet client should operate in accept mode where the client will perform author/repository/signedcms signature verification for packages which contain a valid signatures.
• If a user does not have any package sources then NuGet client should write down nuget.org as a package and trusted source and signatureValidationMode as accept into the user nuget.config file.
• NuGet client should respect any trusted source in user settings and perform complete repository signature verification for any package from those sources.

Require mode -

• In require mode NuGet client will only allow packages signed by a list of trusted sources or authors along with all the constraints of accept mode.
• If a package is signed by an author or source that is not trusted, then the operation should fail with an error.

Changing of modes -

1. Starting in a future release, NuGet will operate in accept mode for all users.
2. In a following release NuGet client will allow users to change their NuGet package signing client policy as proposed in this spec.