You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
description: Describes the process of installing signed NuGet packages and configuring package signature trust settings.
4
+
author: karann-msft
5
+
ms.author: karann
6
+
ms.date: 11/29/2018
7
+
ms.topic: conceptual
8
+
---
9
+
10
+
# Install a signed package
11
+
12
+
Signed packages don't require any specific action to be installed; however, if the content has been modified since it was signed, the installation is blocked with error [NU3008](../reference/errors-and-warnings/NU3008.md).
13
+
14
+
> [!Warning]
15
+
> Packages signed with untrusted certificates are considered as unsigned and are installed without any warnings or errors like any other unsigned package.
16
+
17
+
## Configure package signature requirements
18
+
19
+
> [!Note]
20
+
> Requires NuGet 4.9.0+ and Visual Studio version 15.9 and later on Windows
21
+
22
+
You can configure how NuGet clients validate package signatures by setting the `signatureValidationMode` to `require` in the [nuget.config](../reference/nuget-config-file) file using the [`nuget config`](../tools/cli-ref-config) command.
This mode will verify that all packages are signed by any of the certificates trusted in the `nuget.config` file. This file allows you to specify which authors and/or repositories are trusted based on the certificate's fingerprint.
35
+
36
+
### Trust package author
37
+
38
+
To trust packages based on the author signature use the [`trusted-signers`](..tools/cli-ref-trusted-signers) command to set the `author` property in the nuget.config.
>Use the `nuget.exe`[verify command](https://docs.microsoft.com/en-us/nuget/tools/cli-ref-verify) to get the `SHA256` value of the certificate's fingerprint.
54
+
55
+
56
+
### Trust all packages from a repository
57
+
58
+
To trust packages based on the repository signature use the `repository` element:
Repository signatures include additional metadata to determine the owners of the package at the time of submission. You can restrict packages from a repository based on a list of owners:
If a package has multiple owners, and any one of those owners is in the trusted list, the package installation will succeed.
86
+
87
+
### Untrusted Root certificates
88
+
89
+
In some situations you may want to enable verification using certificates that do not chain to a trusted root in the local machine. You can use the `allowUntrustedRoot` attribute to customize this behavior.
90
+
91
+
### Sync repository certificates
92
+
93
+
Package repositories should announce the certificates they use in their [service index](https://docs.microsoft.com/en-us/nuget/api/service-index). Eventually the repository will update these certificates, e.g. when the certificate expires. When that happens, clients with specific policies will require an update to the configuration to include the newly added certificate. You can easily upgrade the trusted signers associated to a repository by using the `nuget.exe`[trusted-signers sync command](/nuget/tools/cli-ref-trusted-signers.md#nuget-trusted-signers-sync--name-).
94
+
95
+
### Schema reference
96
+
97
+
The complete schema reference for the client policies can be found in the [nuget.config reference](/nuget/reference/nuget-config-file#trustedsigners-section)
98
+
99
+
## Related articles
100
+
101
+
-[Different ways to install a NuGet Package](ways-to-install-a-package.md)
Copy file name to clipboardExpand all lines: docs/create-packages/Sign-a-Package.md
+65-26Lines changed: 65 additions & 26 deletions
Original file line number
Diff line number
Diff line change
@@ -10,51 +10,90 @@ ms.reviewer: anangaur
10
10
11
11
# Signing NuGet Packages
12
12
13
-
Signing a package is a process that makes sure the package has not been modified since its creation.
13
+
Signed packages allows for content integrity verification checks which provides protection against content tampering. The package signature also serves as the single source of truth about the actual origin of the package and bolsters package authenticity for the consumer. This guide assumes you have already [created a package](creating-a-package.md).
14
14
15
-
## Prerequisites
15
+
## Get a code signing certificate
16
16
17
-
1. The package (a `.nupkg` file) to sign. See [Creating a package](creating-a-package.md).
17
+
Valid certificates may be obtained from a public certificate authority such as [Symantec](https://trustcenter.websecurity.symantec.com/process/trust/productOptions?productType=SoftwareValidationClass3), [DigiCert](https://www.digicert.com/code-signing/), [Go Daddy](https://www.godaddy.com/web-security/code-signing-certificate), [Global Sign](https://www.globalsign.com/en/code-signing-certificate/), [Comodo](https://www.comodo.com/e-commerce/code-signing/code-signing-certificate.php), [Certum](https://www.certum.eu/certum/cert,offer_en_open_source_cs.xml), etc. The complete list of certification authorities trusted by Windows can be obtained from [http://aka.ms/trustcertpartners](http://aka.ms/trustcertpartners).
18
18
19
-
1. nuget.exe 4.6.0 or later. See how to [Install NuGet CLI](../install-nuget-client-tools.md#nugetexe-cli).
19
+
You can use self-issued certificates for testing purposes. However, packages signed using self-issued certificates are not accepted by NuGet.org. Learn more about [creating a test certificate](#create-a-test-certificate)
As described in the command reference, you can use a certificate available in the certificate store or use a certificate from a file.
40
+
* You can use a certificate available in the certificate store or use a certificate from a file. See CLI reference for [nuget sign](../tools/cli-ref-sign.md).
41
+
* Signed packages should include a timestamp to make sure the signature remains valid when the signing certificate has expired. Else the sign operation will produce a [warning](../reference/errors-and-warnings/NU3002.md).
42
+
* You can see the signature details of a given package using [nuget verify](../tools/cli-ref-verify.md).
32
43
33
-
### Common problems when signing a package
44
+
##Register the certificate on NuGet.org
34
45
35
-
- The certificate is not valid for code signing. You must ensure the certificate specified has the appropriate extended key usage (EKU 1.3.6.1.5.5.7.3.3).
36
-
- The certificate does not satisfy the basic requirements such as the RSA SHA-256 signature algorithm or a public key 2048 bits or greater.
37
-
- The certificate has expired or has been revoked.
38
-
- The timestamp server does not satisfy the certificate requirements.
46
+
To publish a signed package, you must first register the certificate with NuGet.org. You need the certificate as a `.cer` file in a binary DER format.
39
47
40
-
> [!Note]
41
-
> Signed packages should include a timestamp to make sure the signature remains valid when the signing certificate has expired. The sign operation produce a [warning NU3002](../reference/errors-and-warnings/NU3002.md) when signing without a timestamp.
48
+
1.[Sign in](https://www.nuget.org/users/account/LogOn?returnUrl=%2F) to NuGet.org.
49
+
1. Go to `Account settings` (or `Manage Organization`**>**`Edit Organziation` if you would like to register the certificate with an Organization account).
50
+
1. Expand the `Certificates` section and select `Register new`.
51
+
1. Browse and select the certficate file that was exported earlier.
* One user can submit multiple certificates and the same certificate can be registered by multiple users.
56
+
* Once a user has a certificate registered, all future package submissions **must** be signed with one of the certificates. See [Manage signing requirements for your package on NuGet.org](#manage-signing-requirements-for-your-package-on-nugetorg)
57
+
* Users can also remove a registered certificate from the account. Once a certificate is removed, new packages signed with that certificate will fail at submission. Existing packages aren't affected.
44
58
45
-
Use [nuget verify](../tools/cli-ref-verify.md) to see the signature details of a given package:
59
+
## Publish the package
46
60
47
-
```cli
48
-
nuget verify -signature MyPackage.nupkg
49
-
```
61
+
You are now ready to publish the package to NuGet.org. See [Publishing packages](Publish-a-package.md).
62
+
63
+
## Create a test certificate
50
64
51
-
## Install a signed package
65
+
You can use self-issued certificates for testing purposes. To create a self-issued certificate, use the [New-SelfSignedCertificate PowerShell command](/powershell/module/pkiclient/new-selfsignedcertificate.md).
52
66
53
-
Signed packages don't require any specific action to be installed; however, if the content has been modified since it was signed, the installation is blocked and produces an [error NU3008](../reference/errors-and-warnings/NU3008.md).
67
+
```ps
68
+
New-SelfSignedCertificate -Subject "CN=NuGet Test Developer, OU=Use for testing purposes ONLY" `
69
+
-FriendlyName "NuGetTestDeveloper" `
70
+
-Type CodeSigning `
71
+
-KeyUsage DigitalSignature `
72
+
-KeyLength 2048 `
73
+
-KeyAlgorithm RSA `
74
+
-HashAlgorithm SHA256 `
75
+
-Provider "Microsoft Enhanced RSA and AES Cryptographic Provider" `
76
+
-CertStoreLocation "Cert:\CurrentUser\My"
77
+
```
78
+
79
+
This command creates a testing certificate available in the current user's personal certificate store. You can open the certificate store by running `certmgr.msc` to see the newly created certificate.
54
80
55
81
> [!Warning]
56
-
> Packages signed with untrusted certificates are considered as unsigned and are installed without any warnings or errors like any other unsigned package.
82
+
> NuGet.org does not accept packages signed with self-issued certificates.
83
+
84
+
## Manage signing requirements for your package on NuGet.org
85
+
1.[Sign in](https://www.nuget.org/users/account/LogOn?returnUrl=%2F) to NuGet.org.
* If you are the sole owner of a package, you are the required signer i.e. you can use any of the registered certificates to sign and publish your packages to NuGet.org.
91
+
92
+
* If a package has multiple owners, by default, "Any" owner's certificates can be used to sign the package. As a co-owner of the package, you can override "Any" with yourself or any other co-owner to be the required signer. If you make an owner who does not have any certificate registered, then unsigned packages will be allowed.
93
+
94
+
* Similarly, if the default "Any" option is selected for a package where one owner has a certificate registered and another owner does not have any certificate registered, then NuGet.org accepts either a signed package with a signature registered by one of its owners or an unsigned package (because one of the owners does not have any certificate registered).
Copy file name to clipboardExpand all lines: docs/reference/Signed-Packages-Reference.md
+6-63Lines changed: 6 additions & 63 deletions
Original file line number
Diff line number
Diff line change
@@ -27,47 +27,13 @@ For details on creating an author signed package, see [Signing Packages](../crea
27
27
28
28
Package signing requires a code signing certificate, which is a special type of certificate that is valid for the `id-kp-codeSigning` purpose [[RFC 5280 section 4.2.1.12](https://tools.ietf.org/html/rfc5280#section-4.2.1.12)]. Additionally, the certificate must have an RSA public key length of 2048 bits or higher.
29
29
30
-
## Get a code signing certificate
31
-
32
-
Valid certificates may be obtained from a public certificate authority like:
The complete list of certification authorities trusted by Windows can be obtained from [http://aka.ms/trustcertpartners](http://aka.ms/trustcertpartners).
42
-
43
-
## Create a test certificate
44
-
45
-
You can use self-issued certificates for testing purposes. To create a self-issued certificate, use the [New-SelfSignedCertificate PowerShell command](/powershell/module/pkiclient/new-selfsignedcertificate.md).
46
-
47
-
```ps
48
-
New-SelfSignedCertificate -Subject "CN=NuGet Test Developer, OU=Use for testing purposes ONLY" `
49
-
-FriendlyName "NuGetTestDeveloper" `
50
-
-Type CodeSigning `
51
-
-KeyUsage DigitalSignature `
52
-
-KeyLength 2048 `
53
-
-KeyAlgorithm RSA `
54
-
-HashAlgorithm SHA256 `
55
-
-Provider "Microsoft Enhanced RSA and AES Cryptographic Provider" `
56
-
-CertStoreLocation "Cert:\CurrentUser\My"
57
-
```
58
-
59
-
This command creates a testing certificate available in the current user's personal certificate store. You can open the certificate store by running `certmgr.msc` to see the newly created certificate.
60
-
61
-
> [!Warning]
62
-
> nuget.org does not accept packages signed with self-issued certificates.
63
-
64
30
## Timestamp requirements
65
31
66
32
Signed packages should include an RFC 3161 timestamp to ensure signature validity beyond the package signing certificate's validity period. The certificate used to sign the timestamp must be valid for the `id-kp-timeStamping` purpose [[RFC 5280 section 4.2.1.12](https://tools.ietf.org/html/rfc5280#section-4.2.1.12)]. Additionally, the certificate must have an RSA public key length of 2048 bits or higher.
67
33
68
34
Additional technical details can be found in the [package signature technical specs](https://github.com/NuGet/Home/wiki/Package-Signatures-Technical-Details) (GitHub).
69
35
70
-
## Signature requirements on nuget.org
36
+
## Signature requirements on NuGet.org
71
37
72
38
nuget.org has additional requirements for accepting a signed package:
73
39
@@ -81,32 +47,9 @@ nuget.org has additional requirements for accepting a signed package:
81
47
- The author signing certificate must be valid for code signing.
82
48
- The timestamp certificate must be valid for timestamping.
83
49
- Must not be revoked at signing time. (This may not be knowable at submission time, so nuget.org periodically rechecks revocation status).
50
+
51
+
52
+
## Related articles
84
53
85
-
## Register certificate on nuget.org
86
-
87
-
To submit a signed package, you must first register the certificate with nuget.org. You need the certificate as a `.cer` file in a binary DER format. You can export an existing certificate to a binary DER format by using the Certificate Export Wizard.
Advanced users can export the certificate using the [Export-Certificate PowerShell command](/powershell/module/pkiclient/export-certificate.md).
92
-
93
-
To register the certificate with nuget.org, go to `Certificates` section on `Account settings` page (or the Organization's settings page) and select `Register new certificate`.
> One user can submit multiple certificates and the same certificate can be registered by multiple users.
99
-
100
-
Once a user has a certificate registered, all future package submissions **must** be signed with one of the certificates.
101
-
102
-
Users can also remove a registered certificate from the account. Once a certificate is removed, packages signed with that certificate fail at submission. Existing packages aren't affected.
103
-
104
-
## Configure package signing requirements
105
-
106
-
If you are the sole owner of a package, you are the required signer. That is, you can use any of the registered certificates to sign your packages and submit to nuget.org.
107
-
108
-
If a package has multiple owners, by default, "Any" owner's certificates can be used to sign the package. As a co-owner of the package, you can override "Any" with yourself or any other co-owner to be the required signer. If you make an owner who does not have any certificate registered, then unsigned packages will be allowed.
109
-
110
-
Similarly, if the default "Any" option is selected for a package where one owner has a certificate registered and another owner does not have any certificate registered, then nuget.org accepts either a signed package with a signature registered by one of its owners or an unsigned package (because one of the owners does not have any certificate registered).
0 commit comments