Skip to content

Usage

Jump to bottom
Kevin Jones edited this page May 21, 2017 · 7 revisions

Usage

  1. Sign (Certificate) - See for signing a package with a certificate.
  2. Sign (Azure Key Vault) - See for signing a package with a certificate.
  3. Unsign - See for unsigning a package.

Overview

OVST is designed to have commands specified in the structure of OpenVsixSignTool.exe <command name> [<command options>] <vsix package>. For any command, OpenVsixSignTool <command name> --help can be used to get additional information about the command and options.

sign (Certificate)

The sign command is used to sign, or resign, a VSIX package. It can optionally specify a timestamp to the signature if a timestamp server is specified in the options.

Specifying a Certificate

  • --sha1: This command option can be used to specify the SHA1 thumbprint of a certificate in the certificate store to sign the VSIX package with. The certificate must be in the Current User's certificate store in the Personal store. Note that with this option, it is possible that CryptoAPI, CNG, or any additional middleware for the private key of the certificate may require additional user input, such as a pin or password. This should be considered in automated build environments.

  • --certificate This command option specifies a PFX on disk to sign the VSIX with. In some circumstances, a PFX may require additional user input, such as a pin or a password if the private key is not in the PFX itself. This scenario is rather atypical. If a password is required for the PFX itself, use the --password command line option.

These two options are mutually exclusive. Either one must be specified, but not both. The --password option may only be specified with the --certificate option.

Timestamping

OVST may timestamp the signature. Timestamping makes the signature on the VSIX live beyond the date the signing certificate expires. This is important if you want to ensure your VSIX remains correctly signed without having to publish a new VSIX package every time a certificate expires.

Note: Even if -ta is used to specify a SHA1 digest algorithm for the timestamp, the timestamp server must still be an RFC3161 compliant timestamp server. "Authenticode" style time stamp servers are not supported by VSIX signing.

  • --timestamp-algorithm: The timestamp digest algorithm. The default and recommended value is "SHA256" is no value is specified. Possible values:

    • SHA1
    • SHA256
    • SHA384
    • SHA512

    Note that which algorithms are supported may vary by the timestamp server specified. This value is ignored if --timestamp is not specified.

  • --timestamp: The absolute URI of the timestamp server, such as "http://timestamp.example.com".

Digest Algorithm

The default digest algorithm is SHA256, and may be specified with the --file-digest option. Possible values:

  • SHA1
  • SHA256
  • SHA384
  • SHA512

While OVST supports SHA384 and SHA512, no version of Visual Studio currently does. These options exist for future compatibility if Visual Studio ever gains support for these options, or if other software eventually is able to consume VSIX packages with a stronger digest algorithm.

Resigning

By default, OpenVsixSignTool does not sign an already signed package. However, the --force option is used to remove all existing signatures and sign it anew. This option must be used with a valid configuration of sign options.

Short Notation

Each command has a short form available. See OpenVsixSignTool sign --help for all forms.

Exit Codes

  • 0: the operation succeeded without errors.
  • 1: the options specified are incorrect and creating a signature was not attempted. See the output for information about the specific incorrect options.
  • 2: the operation failed. This occurs when the options are valid, but the package could not be signed. In this scenario, the package may have an incorrect or corrupt signature.

Unsign

Unsign may be used to remove all signature from a VSIX package. It has no options and takes a path to the VSIX package to unsign.

Unsign removes all traces of a signature. If a signature is corrupt, this may be used to aide in the removal of all signatures, valid, invalid, or corrupt.

Exit Codes

  • 0: the operation succeeded without errors.
  • 1: the options specified are incorrect and creating a signature was not attempted. See the output for information about the specific incorrect options.
  • 2: the operation failed. This occurs when the options are valid, but the package could not be unsigned. This occurs when the package is not signed.

sign (Azure Key Vault)

Signing operations using certificates in Azure Key Vault is also possible.

Clone this wiki locally