From 1414fe1d98132818bfedef168f84cbc4bf824575 Mon Sep 17 00:00:00 2001 From: Damon Tivel Date: Fri, 9 Dec 2022 13:50:18 -0800 Subject: [PATCH 1/2] Draft CLI specification --- docs/cli-spec.md | 47 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 47 insertions(+) create mode 100644 docs/cli-spec.md diff --git a/docs/cli-spec.md b/docs/cli-spec.md new file mode 100644 index 00000000..832459d2 --- /dev/null +++ b/docs/cli-spec.md @@ -0,0 +1,47 @@ +# Signing CLI specficiation + +### Inputs + +The parameters to the signing client are as follows: + +`sign code AzureKeyVault [options] ` + +Options: + +- `-o | --output` - The output file. If omitted, overwrites input. Must be a directory if multiple files are specified. +- `-b | --base-directory` - Base directory for files to override the working directory. +- `-f | --force` - Overwrites a signature if it exists. +- `-m | --max-concurrency` - Maximum concurrency (default is 4) +- `-fl | --filelist` - Path to file containing paths of files to sign within an archive +- `-fd | --file-digest` - The digest algorithm to hash the file with. +- `-tr | --timestamp-rfc3161` - Specifies the RFC 3161 timestamp server's URL. +- `-d | --description` - Description +- `-u | --descriptionUrl` - Description Url +- `-td | --timestamp-digest` - Used with the -tr switch to request a digest algorithm used by the RFC 3161 timestamp server. +- `-kvu | --azure-key-vault-url` - The URL to an Azure Key Vault. +- `-kvt | --azure-key-vault-tenant-id` - The Tenant Id to authenticate to the Azure Key Vault.. +- `-kvi | --azure-key-vault-client-id` - The Client ID to authenticate to the Azure Key Vault. +- `-kvs | --azure-key-vault-client-secret` - The Client Secret to authenticate to the Azure Key Vault. +- `-kvc | --azure-key-vault-certificate` - The name of the certificate in Azure Key Vault. +- `-kvm | --azure-key-vault-managed-identity` - Use a Managed Identity to access Azure Key Vault. + +Signing an archive type (`.zip`, `.nupkg`, `.vsix`) will open up the archive and sign any supported file types. It is strongly recommended to use the `filelist` parameter to explicitly list the files inside the archive that should be signed. Signing is recursive; it will sign contents of any detectected `Zip`, `NuPkg` or `VSIX` files inside the uploaded one. After signing contents of the archive, the archive itself is signed if supported (currently `VSIX`). + +### File list + +When specified, only files that match patterns in the list will be signed. This is critical as only first party files should be signed. Files that are third party should not be signed. + +The format for the file contains one file path/pattern per line and does support globs. + +``` +**/MyLibrary.* +**/MyOtherLibrary.dll +``` + +## ClickOnce +ClickOnce files can be signed with this tool, but it requires an extra step -- you must zip up the `publish` directory containing the `setup.exe`, `foo.application` or `foo.vsto` files along with the `Application Files` directory. The `Application Files` must only have a single subdirectory (version you want to sign). Zip these and then rename the extension to `.clickonce` before submitting to the tool. Once done, you can extract the signed files wherever you'd like for publication. If the `name` parameter is supplied, it's used in the `Mage` name to update the `Product` in the manifests. If the `descriptionUrl` parameter is supplied, it's used as the `supportUrl` in the manifests. You should also use the `filter` parameter with the file list to sign, something like this: + +``` +**/ProjectAddIn1.* +**/setup.exe +``` \ No newline at end of file From b3e8b8c29e6dc34e8d39667c1f18971f128b3d28 Mon Sep 17 00:00:00 2001 From: Javier De la Garza Sanchez Date: Wed, 10 Apr 2024 14:13:31 -0500 Subject: [PATCH 2/2] Added certificate store and VSIX signing documentation --- docs/cli-spec.md | 104 +++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 87 insertions(+), 17 deletions(-) diff --git a/docs/cli-spec.md b/docs/cli-spec.md index 832459d2..0b54850d 100644 --- a/docs/cli-spec.md +++ b/docs/cli-spec.md @@ -1,13 +1,23 @@ # Signing CLI specficiation -### Inputs +## Inputs The parameters to the signing client are as follows: -`sign code AzureKeyVault [options] ` +```dotnetcli +sign code [command] [options] +``` + +### Commands +- `azure-key-vault` - Use Azure Key Vault to acquire a private key for signing. +- `certificate-store` - Use a certificate and private key stored in a PFX file, under Windows Certificate Manager, or in a USB device with a Cryprographic Service Provider. -Options: +### Options: +Required: +- `-d | --description` - Description of the signing certificate. +- `-u | --descriptionUrl` - Description Url of the signing certificate. +Optional: - `-o | --output` - The output file. If omitted, overwrites input. Must be a directory if multiple files are specified. - `-b | --base-directory` - Base directory for files to override the working directory. - `-f | --force` - Overwrites a signature if it exists. @@ -15,33 +25,93 @@ Options: - `-fl | --filelist` - Path to file containing paths of files to sign within an archive - `-fd | --file-digest` - The digest algorithm to hash the file with. - `-tr | --timestamp-rfc3161` - Specifies the RFC 3161 timestamp server's URL. -- `-d | --description` - Description -- `-u | --descriptionUrl` - Description Url - `-td | --timestamp-digest` - Used with the -tr switch to request a digest algorithm used by the RFC 3161 timestamp server. + +Signing an archive type (`.zip`, `.nupkg`, `.vsix`) will open up the archive and sign any supported file types. It is strongly recommended to use the `filelist` parameter to explicitly list the files inside the archive that should be signed. Signing is recursive; it will sign contents of any detectected `Zip`, `NuPkg` or `VSIX` files inside the uploaded one. After signing contents of the archive, the archive itself is signed if supported (currently `VSIX`). + +### File list + +Although the tool recursively signs supported file types if within a container, the `-fl` option allows for specifying which files to sign. This is critical as only first party files should be signed. Files that are third party should not be signed. +The format for the file contains one file path/pattern per line and does support globs: +``` +**/MyLibrary.* +**/MyOtherLibrary.dll +``` + + +## Sign Using Azure Key Vault +Sign requires a vault URL and certificate name as a minimum to sign, although additional options are available. + +```dotnetcli +sign code azure-key-vault [options] +``` + +### Options: +Required: - `-kvu | --azure-key-vault-url` - The URL to an Azure Key Vault. -- `-kvt | --azure-key-vault-tenant-id` - The Tenant Id to authenticate to the Azure Key Vault.. +- `-kvc | --azure-key-vault-certificate` - The name of the certificate in Azure Key Vault. +- `-d | --description` - Description of the signing certificate. +- `-u | --descriptionUrl` - Description Url of the signing certificate. + +Optional: +- `-kvt | --azure-key-vault-tenant-id` - The Tenant Id to authenticate to the Azure Key Vault. - `-kvi | --azure-key-vault-client-id` - The Client ID to authenticate to the Azure Key Vault. - `-kvs | --azure-key-vault-client-secret` - The Client Secret to authenticate to the Azure Key Vault. -- `-kvc | --azure-key-vault-certificate` - The name of the certificate in Azure Key Vault. - `-kvm | --azure-key-vault-managed-identity` - Use a Managed Identity to access Azure Key Vault. -Signing an archive type (`.zip`, `.nupkg`, `.vsix`) will open up the archive and sign any supported file types. It is strongly recommended to use the `filelist` parameter to explicitly list the files inside the archive that should be signed. Signing is recursive; it will sign contents of any detectected `Zip`, `NuPkg` or `VSIX` files inside the uploaded one. After signing contents of the archive, the archive itself is signed if supported (currently `VSIX`). +### Sample +```dotnetcli +sign code azure-key-vault [options] +``` -### File list +### ClickOnce Special Case +ClickOnce files can be signed with this tool, but it requires an extra step -- you must zip up the `publish` directory containing the `setup.exe`, `foo.application` or `foo.vsto` files along with the `Application Files` directory. The `Application Files` must only have a single subdirectory (version you want to sign). Zip these and then rename the extension to `.clickonce` before submitting to the tool. Once done, you can extract the signed files wherever you'd like for publication. If the `name` parameter is supplied, it's used in the `Mage` name to update the `Product` in the manifests. If the `descriptionUrl` parameter is supplied, it's used as the `supportUrl` in the manifests. You should also use the `filter` parameter with the file list to sign, something like this: -When specified, only files that match patterns in the list will be signed. This is critical as only first party files should be signed. Files that are third party should not be signed. +## Sign Using Certificate Store or USB Device +Only VSIX packages can be signed using a certificate store or USB device, with more adding support in the future. -The format for the file contains one file path/pattern per line and does support globs. +We support 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 (CSP) +```dotnetcli +sign code certificate-store [options] ``` -**/MyLibrary.* -**/MyOtherLibrary.dll + +### Options: +Includes [General Options](#general-options). + +Required: +- `-s | --sha1` - SHA-1 thumbprint used to identify a certificate. +- `-d | --description` - Description of the signing certificate. +- `-u | --descriptionUrl` - Description Url of the signing certificate. + +Optional: +- `-cf | --certificate-file` - PFX, P7B, or CER file containing a certificate and potentially a private key. +- `-p | --password` - Optional password for certificate file. +- `-csp | --crypto-service-provider` - Cryptographic Service Provider containing the private key. +- `-k | --key-container` - Private key container name. +- `-km | --use-machine-key-container` - Use a machine-level private key container. (The default is user-level.) [default: False] + +### VSIX Sample + +- Signing using a PFX file with certificate and private key: +```shell +sign code certificate-store -s f5ec6169345347a7cd2f83af662970d5d0bfc914 -cf "D:\Certs\f5ec6169345347a7cd2f83af662970d5d0bfc914.pfx" -d "VSIX Signature" -u "http://timestamp.acs.microsoft.com/" "C:\Users\Contoso\Downloads\FingerSnapper2022.vsix" ``` -## ClickOnce -ClickOnce files can be signed with this tool, but it requires an extra step -- you must zip up the `publish` directory containing the `setup.exe`, `foo.application` or `foo.vsto` files along with the `Application Files` directory. The `Application Files` must only have a single subdirectory (version you want to sign). Zip these and then rename the extension to `.clickonce` before submitting to the tool. Once done, you can extract the signed files wherever you'd like for publication. If the `name` parameter is supplied, it's used in the `Mage` name to update the `Product` in the manifests. If the `descriptionUrl` parameter is supplied, it's used as the `supportUrl` in the manifests. You should also use the `filter` parameter with the file list to sign, something like this: +- Signing using Microsoft Certificate Manager: +```shell +code certificate-store -s f5ec6169345347a7cd2f83af662970d5d0bfc914 -csp "Microsoft Software Key Storage Provider" -d "VSIX Signature" -u "http://timestamp.acs.microsoft.com/" "C:\Users\Contoso\Downloads\FingerSnapper2022.vsix" +``` +- Signing using a private key in a USB drive: +```shell +code certificate-store -s f5ec6169345347a7cd2f83af662970d5d0bfc914 -csp "eToken Base Cryptographic Provider" -d "VSIX Signature" -u "http://timestamp.acs.microsoft.com/" "C:\Users\Contoso\Downloads\FingerSnapper2022.vsix" ``` -**/ProjectAddIn1.* -**/setup.exe + +- Signing using a USB drive using a specific key container: +```shell +code certificate-store -s f5ec6169345347a7cd2f83af662970d5d0bfc914 -csp "eToken Base Cryptographic Provider" -k "NuGet Signing.629c9149345347cd2f83af6f5ec70d5d0a7bf616" -d "VSIX Signature" -u "http://timestamp.acs.microsoft.com/" "C:\Users\Contoso\Downloads\FingerSnapper2022.vsix" ``` \ No newline at end of file