Merge pull request #10322 from MicrosoftDocs/main638575526900700006sync_temp

For protected branch, push strategy should use PR and merge to target branch method to work around git push error

Author: learn-build-service-prod[bot]

docs/debugger/autos-and-locals-windows.md

@@ -1,7 +1,7 @@
 ---
 title: Inspect variables - Autos and Locals windows
 description: Inspect variables in the Autos and Locals windows while debugging in Visual Studio. The Autos and Locals windows show variable values while you are debugging.
-ms.date: 07/20/2023
+ms.date: 07/25/2024
 ms.topic: how-to
 f1_keywords:
   - vs.debug.autos

docs/extensibility/dotnet-sign-cli-reference-vsix.md

@@ -0,0 +1,193 @@
+---
+title: Sign CLI reference for VSIX packages
+description: The Sign CLI command can sign VSIX packages using certificates from PFX, Windows Certificate Manager (WCM), or Cryptographic Service Providers (CSP).
+ms.topic: reference
+helpviewer_keywords:
+- signature
+- signing
+- sign
+- pfx
+- sha256
+- authenticode
+- vsix
+- packages
+- dotnet
+author: javierdlg
+ms.author: maiak
+manager: mijacobs
+ms.subservice: extensibility-integration
+ms.date: 04/11/2024
+---
+
+# Sign CLI Reference for VSIX Packages
+
+`sign` - Dotnet tool used to sign files and containers using PFX, CER, or P7B certificates on disk or from Windows Certificate Manager (WCM), Cryptographic Service Providers (CSP), or Azure Key Vault.
+
+> [!IMPORTANT]
+> Sign CLI only supports `SHA-256`, `SHA-384`, and `SHA-512` as valid fingerprint algorithms. You can use PowerShell to get fingerprints using: `Get-FileHash -Algorithm SHA256 <path to .cer file> | Format-Table -AutoSize`
+
+## Synopsis
+
+```dotnetcli
+sign code certificate-store [<PATH(s)>]
+    [-cf|--certificate-file <PATH>]
+    [-p|--password <PASSWORD>]
+    [-cfp|--certificate-fingerprint <SHA>]
+    [-csp|--crypto-service-provider <CSPNAME>]
+    [-k|--key-container <HASHALGORITHM>]
+    [-km|--use-machine-key-container]
+    [-d|--description <DESCRIPTION>]
+    [-u|--descriptionUrl <URL>]
+    [-fd|--file-digest <DIGEST>]
+    [-t|--timestamp-url <URL>]
+    [-tr|--timestamp-rfc3161 <URL>]
+    [-td|--timestamp-digest <DIGEST>]
+    [-o|--output <PATH>]
+    [-b|--base-directory <wORKINGDIRECTORY>]
+    [-f|--force]
+    [-m|--max-concurrency <MAXCONCURRENCY>]
+    [-fl|--filelist <FILELISTPATH>]
+
+sign code certificate-store -h|--help
+```
+
+## Description
+
+`Sign CLI` is a Dotnet tool that recursively signs files and containers with a certificate and private. The certificate and private key can be obtained from either a file (PFX, P7B, CER) or from a certificate installed in a certificate store by providing a `SHA-256`, `SHA-384`, or `SHA-512` fingerprint. USB keys can be accessed using a [Cryptographic Service Provider](/windows/win32/seccrypto/cryptographic-service-providers) (CSP) implemented by the manufacturer and accessed from the certificate store.
+
+## Installation
+Install Sign CLI globally using `dotnet tool install sign --version <version> --global`, where `<version>` is the latest available version under [Sign (nuget.org)](https://www.nuget.org/packages/sign).
+
+### Offline Installation of Sign CLI
+For isolated environments you can download a Sign CLI NuGet package and install it using:
+
+```dotnetcli
+dotnet tool install --global --add-source <path-to-folder> <tool-name> --version <version>
+```
+
+## Arguments
+
+- **`VSIX-paths(s)`**
+
+  Specifies the path(s) to the VSIX package to be signed.
+
+## Options
+
+- **`-cf|--certificate-file <PATH>`**
+
+   PFX, P7B, or CER file containing a certificate and potentially a private key.
+
+- **`-p|--password <PASSWORD>`**
+
+   Optional password for certificate file.
+
+- **`-cfp|--certificate-fingerprint <SHA>`**
+
+   SHA-256, SHA-384, or SHA-512 fingerprint used to identify a certificate before signing.
+
+- **`-csp|--crypto-service-provider <CSP NAME>`**
+
+   Cryptographic Service Provider containing a private key.
+
+- **`-k|--key-container <CONTAINER NAME>]`**
+
+   Private key container name.
+
+- **`-km|--use-machine-key-container]`**
+
+   Use a machine-level private key container instead of the default user-level container.
+
+- **`-d|--description <DESCRIPTION>`**
+
+   Description of the signing certificate.
+
+- **`-u|--descriptionUrl <URL>`**
+
+   Description Url of the signing certificate.
+
+- **`-fd | --file-digest <DIGEST>`**
+
+   Digest algorithm to hash the file with.
+   
+- **`-t|--timestamp-url <URL>`**
+
+   RFC 3161 timestamp server URL. [default: http://timestamp.acs.microsoft.com/]
+
+- **`-tr | --timestamp-rfc3161 <URL>`**
+
+   Specifies the RFC 3161 timestamp server's URL.
+
+- **`-td|--timestamp-digest <DIGEST>`**
+
+  Used with `-tr` switch to request a digest algorithm used by the RFC 3161 timestamp server.
+
+- **`-o|--output <PATH>`**
+
+  The output file or folder if multiple files are specified. If omitted, input is overwritten.
+
+- **`-b|--base-directory <PATH>`**
+
+  Base directory for files to override the working directory.
+
+- **`--f|--force`**
+
+  Overwrites a signature if it exists.
+
+- **`-m|--max-concurrency <MAXCONCURRENCY>`**
+
+  Maximum concurrency (default is 4)
+
+- **`-fl | --filelist <PATH>`**
+
+  Path to file containing paths of files to sign or to exclude from signing within the container.
+
+- **`-?|-h|--help`**
+
+  Prints a description of how to use the command.
+
+## Examples
+
+- Sign *contoso.vsix* with a certificate imported to the **user** certificate store:
+
+  ```dotnetcli
+  sign contoso.vsix -cfp 24D589...FB9523B36E -d "Constoso VSIX Signature" -u "http://www.contoso.com"
+  ```
+
+- Sign *contoso.vsix* with certificate *cert.pfx* (not password protected) using a SHA-512 fingerprint:
+
+  ```dotnetcli
+  sign contoso.vsix -cfp A87A6F...894559B981 -cfpa sha512 -cf D:\certificates\cert.pfx -d "Constoso VSIX Signature" -u "http://www.contoso.com"
+  ```
+
+- Sign *contoso.vsix* with certificate *cert.pfx* (password protected):
+
+  ```dotnetcli
+  sign contoso.vsix -s 24D58920B2D24D00A7DF07FB9523B36E -cf cert.pfx -p <password> -d "Constoso VSIX Signature" -u "http://www.contoso.com"
+  ```
+
+- Sign multiple VSIX packages - *contoso.vsix* and *all .vsix files in the directory specified* with certificate *cert.pfx* (not password protected):
+
+  ```dotnetcli
+  sign *.vsix -s 24D58920B2D24D00A7DF07FB9523B36E -cf cert.pfx -d "Constoso VSIX Signature" -u "http://www.contoso.com"
+  ```
+
+- Sign *contoso.vsix* with a certificate stored in a secure USB drive.
+
+  ```dotnetcli
+  sign contoso.vsix -s 24D58920B2D24D00A7DF07FB9523B36E -csp "Microsoft Software Key Storage Provider" -k "NuGetSigning 0B2D249223B36D00A7DF07FB95E24D58" -d "Constoso VSIX Signature" -u "http://www.contoso.com"
+  ```
+
+- Sign *contoso.vsix* with a certificate stored in a secure USB drive and accessed from the **machine** certificate store (-km option).
+
+  ```dotnetcli
+  sign contoso.vsix -s 24D58920B2D24D00A7DF07FB9523B36E -csp "Microsoft Software Key Storage Provider" -k "NuGetSigning 0B2D249223B36D00A7DF07FB95E24D58" -km -d "Constoso VSIX Signature" -u "http://www.contoso.com"
+  ```
+
+  > [!NOTE]
+  > When `-k` option isn't provided, the tool checks all containers in the provided CSP for a matching SHA fingerprint certificate.
+
+- Sign *contoso.vsix* with a certificate stored in a secure USB drive specifying file digest algorithm (-fd), timestamp server (-t), and a custom output path (-o) for the signed VSIX.
+
+  ```dotnetcli
+  sign contoso.vsix -s 24D58920B2D24D00A7DF07FB9523B36E -csp "Microsoft Software Key Storage Provider" -k "NuGetSigning 0B2D249223B36D00A7DF07FB95E24D58" -d "Constoso VSIX Signature" -u "http://www.contoso.com" -t "http://timestamp.acs.microsoft.com/" -fd sha256 -o "ContosoSigned.vsix"
+  ```

docs/extensibility/signing-vsix-packages.md

@@ -1,44 +1,103 @@
 ---
-title: Signing VSIX Packages
+title: Signing VSIX packages
 description: Learn about signing extension assemblies. The VSIX installer displays a message that a VSIX is signed and information about the signature itself.
-ms.date: 11/04/2016
+ms.date: 4/10/2024
 ms.topic: how-to
 helpviewer_keywords:
 - signature
 - signing
 - authenticode
 - vsix
 - packages
-author: maiak
+author: javierdlg
 ms.author: maiak
 manager: mijacobs
 ms.subservice: extensibility-integration
 ---
+
 # Signing VSIX Packages
+Extension assemblies don't need to be signed before they can run in Visual Studio, but it's a good practice to do so.
+
+Adding a digital signature to a VSIX package secures your extension and prevents tampering. During install, the VSIX installer displays the signature and a link to the certificate. If the contents of the VSIX are modified without updating the signature, the installer only warns the user of an invalid package signature. This guide assumes you have already [created a VSIX](../extensibility/getting-started-with-the-vsix-project-template.md).
+
+## Get a code signing certificate
+
+Valid certificates can be obtained from a public certificate authority such as:
+
+- [Certum](https://www.certum.eu/certum/cert,offer_en_open_source_cs.xml)
+- [Comodo](https://www.comodo.com/e-commerce/code-signing/code-signing-certificate.php)
+- [DigiCert](https://www.digicert.com/code-signing/)
+- [GlobalSign](https://www.globalsign.com/en/code-signing-certificate/)
+- [SSL.com](https://www.ssl.com/certificates/code-signing/)
+
+The complete list of certification authorities trusted by Windows can also be obtained from [http://aka.ms/trustcertpartners](/security/trusted-root/participants-list).
+
+You can use self-issued certificates for testing purposes. However, VSIX packages signed using self-issued certificates are not accepted by Visual Studio Marketplace. Learn more about [generating self-signed certificates with the .NET CLI](/dotnet/core/additional-tools/self-signed-certificates-guide).
+
+## Signing a VSIX with Sign CLI
+VSIXSignTool has been deprecated in favor of [Sign CLI (github.com)](https://github.com/dotnet/sign). This tool is published to NuGet as a dotnet tool under [Sign (nuget.org)](https://www.nuget.org/packages/sign) and supports local signing or using Azure Key Vault cloud signing.
 
-Extension assemblies do not need to be signed before they can run in Visual Studio, but it is a good practice to do so.
+For local signing, Sign CLI supports certificates and private keys stored in any combination of these locations:
+- `PFX`, `P7B`, or `CER` files
+- Imported into Windows Certificate Manager
+- Stored in a USB device with access via a [Cryptographic Service Provider](/windows/win32/seccrypto/cryptographic-service-providers) (CSP)
 
- If you want to secure your extension and make sure it hasn't been tampered with, you can add a digital signature to a VSIX package. When a VSIX is signed, the VSIX installer will display a message indicating that it is signed, plus more information about the signature itself. If the contents of the VSIX have been modified, and the VSIX has not been signed again, the VSIX installer will show that the signature is not valid. The installation is not stopped, but the user is warned.
+### Installing Sign CLI
+1. Open a [Developer PowerShell](/visualstudio/ide/reference/command-prompt-powershell) instance.
+
+1. Verify nuget.org is added and enabled as a NuGet source.
+    - Check your sources using `dotnet nuget list source` 
+    - Add NuGet.org as a source using `dotnet nuget add source -n NuGet.org https://api.nuget.org/v3/index.json`
+
+1. Install Sign by running `dotnet tool install sign --version <version> --global`, where `<version>` is the latest available version under [Sign (nuget.org)](https://www.nuget.org/packages/sign).
+    - `--global` is optional and installs the tool in the .NET tools default location that is automatically added to the PATH environment variable.
+
+### Offline Installation of Sign CLI
+For isolated environments you can download the latest Sign CLI NuGet package and install it using:
+
+```dotnetcli
+dotnet tool install --global --add-source <path-to-folder> <tool-name> --version <version>
+```
+
+For example:
+
+```dotnetcli
+dotnet tool install --global --add-source D:\NuGetTools sign --version 99.0
+```
+
+### Using Sign CLI
+Once installed, Sign CLI can be accessed in a Developer PowerShell instance using `sign code <command> <options>`. For a breakdown of the options see [Sign CLI Reference for VSIX Packages](../extensibility/dotnet-sign-CLI-reference-vsix.md).
 
 > [!IMPORTANT]
-> Beginning with Visual Studio 2015, VSIX packages signed using anything other than SHA256 encryption will be identified as having an invalid signature. VSIX installation is not blocked but the user will be warned.
+> Sign CLI only supports `SHA-256`, `SHA-384`, and `SHA-512` as valid fingerprint algorithms. You can use PowerShell to get fingerprints using: `Get-FileHash -Algorithm SHA256 <path to .cer file> | Format-Table -AutoSize`
+
+- Signing using a PFX file with a SHA-256 fingerprint:
 
-## Signing a VSIX with VSIXSignTool
- There is a SHA256 encryption signing tool available from [VisualStudioExtensibility](https://www.nuget.org/profiles/VisualStudioExtensibility) on nuget.org at [VsixSignTool](https://www.nuget.org/packages/Microsoft.VSSDK.Vsixsigntool).
+```dotnetcli
+sign code certificate-store -cfp 80BB567B...52CB95D4C -cf "D:\Certs\f5ec6169345347a7cd2f83af662970d5d0bfc914.pfx" -d "My VSIX Signature" -u "http://timestamp.acs.microsoft.com/" "C:\Users\Contoso\Downloads\FingerSnapper2022.vsix"
+```
 
-#### To use the VSIXSignTool
+> [!NOTE]
+> PFX files contain both certificate and private key used for signing and don't comply with C/A Browser Forum requirements for Extended Validation (EV) and non-EV signing. it's recommended to only use private keys stored in a Hardened Secure Module (HSM) device and access them using a Cryptographic Service Provider (CSP).
 
-1. Add your VSIX to a project.
+- Signing using Microsoft Certificate Manager and a SHA512 fingerprint (-csp option):
 
-2. Right click on the project node in Solution Explorer, selecting **Add &#124; Manage NuGet Packages**.  For more information on NuGet and adding NuGet packages see the [NuGet documentation](/NuGet) and [Package Manager UI](/NuGet/Tools/Package-Manager-UI) topics.
+```dotnetcli
+code certificate-store -cfp A87A60A6F...894559B98 -csp "Microsoft Software Key Storage Provider" -d "My VSIX Signature" -u "http://timestamp.acs.microsoft.com/" "C:\Users\Contoso\Downloads\FingerSnapper2022.vsix"
+```
 
-3. Search for VSIXSignTool from VisualStudioExtensibility and install the NuGet package.
+- Signing using a private key in a USB drive (-csp option):
 
-4. You can now run the VSIXSignTool from the project's local packages location. Consult the tool's command line help for your signing scenario (VSIXSignTool.exe /?).
+```dotnetcli
+code certificate-store -cfp B113E82D...F5CF294BE0B -csp "eToken Base Cryptographic Provider" -d "VSIX Signature" -u "http://timestamp.acs.microsoft.com/" "C:\Users\Contoso\Downloads\FingerSnapper2022.vsix"
+```
 
-   For example to sign with a password protected certificate file:
+- Signing using a USB drive using a specific key container (-csp and -k options):
 
-   VSIXSignTool.exe sign /f \<certfile> /p \<password> \<VSIXfile>
+```dotnetcli
+code certificate-store -s 15BB56B0...1ACB959D0 -csp "eToken Base Cryptographic Provider" -k "NuGet Signing.629c9149345347cd2f83af6f5ec70d5d0a7bf616" -d "VSIX Signature" -u "http://timestamp.acs.microsoft.com/" "C:\Users\Contoso\Downloads\FingerSnapper2022.vsix"
+```
 
 ## Related content
 - [Shipping Visual Studio Extensions](../extensibility/shipping-visual-studio-extensions.md)
+- [Sign CLI Reference for VSIX Packages](../extensibility/dotnet-sign-CLI-reference-vsix.md)

docs/extensibility/toc.yml

@@ -526,6 +526,8 @@
       href: preparing-extensions-for-windows-installer-deployment.md
     - name: Sign VSIX Packages
       href: signing-vsix-packages.md
+    - name: Sign CLI Reference
+      href: dotnet-sign-cli-reference-vsix.md
     - name: Private Galleries
       items:
       - name: Private Galleries