diff --git a/docs/cli-spec.md b/docs/cli-spec.md new file mode 100644 index 00000000..0b54850d --- /dev/null +++ b/docs/cli-spec.md @@ -0,0 +1,117 @@ +# Signing CLI specficiation + +## Inputs + +The parameters to the signing client are as follows: + +```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: +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. +- `-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. +- `-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. +- `-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. +- `-kvm | --azure-key-vault-managed-identity` - Use a Managed Identity to access Azure Key Vault. + +### Sample +```dotnetcli +sign code azure-key-vault [options] +``` + +### 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: + +## 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. + +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] +``` + +### 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" +``` + +- 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" +``` + +- 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