signtool

Node module wrapper around the signtool binary

Usage no npm install needed!

<script type="module">
  import signtool from 'https://cdn.skypack.dev/signtool';
</script>

README

node-signtool

node-signtool is a Node module wrapper around the SignTool binary.

Getting Started

node-signtool works as a wrapper around the SignTool library. It abstracts the commands' switches with JS object abstraction. Options mapping is available below.

Installation

node-signtool can be installed using NPM:

$ npm install node-signtool --save

Usage

First import node-signtool in your project:

var signtool = require("signtool");

Then use signtool's commands:

signtool.sign("path/to/my.exe", { certificate: "path/to/my/cert.pfx", password: "*******" });
signtool.verify("path/to/my.exe");

node-signtool uses native Promise to wrap asynchronous operations and resolves with the result of the command:

signtool.sign("path/to/my.exe", { certificate: "path/to/my/cert.pfx", password: "*******" });
    .then(result => {
        result.code 	// The signtool exit code.
        result.stdout 	// The signtool stdout content.
        result.stderr	// The signtool stderr content.
    });

Documentation

signtool.sign(file: string | string[], [options: SignOptions], [runOptions: RunOptions]): Promise

The sign command allows to digitally signs files. If no options are provided, node-signtool use the default auto behavior.

Switch Option Description
/a auto Selects the best signing certificate automatically.
/as append Appends this signature. If no primary signature is present, this signature is made the primary signature.
/uw verify Specifies using "Windows System Component Verification" (1.3.6.1.4.1.311.10.3.6).
/f certificate Specifies the signing certificate in a file (PFX).
/p password Specifies the password to use when opening a PFX file.
/i issuer Specifies the name of the issuer of the signing certificate.
/n subject Specifies the name of the subject of the signing certificate.
/r rootSubject Specifies the name of the subject of the root certificate that the signing certificate must chain to.
/d description Specifies a description of the signed content.
/du url Specifies a URL for expanded description of the signed content.
/s store Specifies the store to open when searching for the certificate.
/sm computerStore Specifies that a computer store, instead of a user store, be used.
/sha1 sha1 Specifies the SHA1 hash of the signing certificate.
/csp csp Specifies the cryptographic service provider (CSP) that contains the private key container.
/kc key Specifies the key that contains the name of the private key.
/c template Specifies the Certificate Template Name (a Microsoft extension) for the signing certificate.
/ac additional Specifies a file that contains an additional certificate to add to the signature block.
/fd algorithm Specifies the file digest algorithm to use to create file signatures.
/u EKU Specifies the enhanced key usage (EKU) that must be present in the signing certificate.
/t timestamp Specifies the URL of the time stamp server.
/tr rfcTimestamp Specifies the RFC 3161 time stamp server's URL.
/td timestampAlgo Used with the rfcTimestamp switch to request a digest algorithm used by the RFC 3161 time stamp server.
/dg digest Generates the to be signed digest and the unsigned PKCS7 files.
/dxml digestXML When used with the digest option, produces an XML file.
/dmdf digestFunction When used with the digest option, passes the file’s contents to the AuthenticodeDigestSign function without modification.
/dlib digestLib Specifies the DLL implementing the AuthenticodeDigestSign function.
/ds digestOnly Signs the digest only. The input file should be the digest generated by the digest option.
/p7 pkcs Creates the signature by ingesting the signed digest to the unsigned PKCS7 file.
/p7ce pkcsCE Specifies options for the signed PKCS #7 content.
/p7co pkcsOID Specifies the object identifier (OID) that identifies the signed PKCS #7 content.
/ph pageHashes If supported, generates page hashes for executable files.
/nph suppresPageHashes If supported, suppresses page hashes for executable files.

signtool.verify(file: string | string[], [options: VerifyOptions], [runOptions: RunOptions]): Promise

The verify command allows to verify the digital signature of files.

If no options are provided, node-signtool use the default useAllMethods behavior.

The SignTool verify command determines :

  • whether the signing certificate was issued by a trusted authority,
  • whether the signing certificate has been revoked,
  • and, optionally, whether the signing certificate is valid for a specific policy.
Switch Option Description
/a useAllMethods Specifies that all methods can be used to verify the file.
/o os Verifies the file by operating system version. (PlatformID:VerMajor.VerMinor.BuildNumber)
/ds index Verifies the signature at a certain position.
/hash hash Specifies an optional hash algorithm to use when searching for a file in a catalog.
/r rootSubject Specifies the name of the subject of the root certificate that the signing certificate must chain to.
/ag catalogDatabase Finds the catalog in the catalog database identified by the GUID.
/c useDefaultCatalog Specifies the catalog file by name.
/ad useDefaultCatalog Finds the catalog by using the default catalog database.
/as useDriverCatalog Finds the catalog by using the system component (driver) catalog database.
/all verifyAllSignatures Verifies all signatures in a file with multiple signatures.
/kp useX64Kernel Performs the verification by using the x64 kernel-mode driver signing policy.
/ms useMultiSemantics Uses multiple verification semantics.
/p7 verifyPKCS Verify PKCS #7 files.
/ph verifyPageHash Print and verify page hash values.
/tw verifyTimestamp Specifies that a warning is generated if the signature is not time stamped.
/pa defaultAuthPolicy Specifies that the Default Authentication Verification Policy is used.
/pg useAuthPolicy Specifies a verification policy by GUID.
/d showDescription Print the description and description URL.

signtool.timestamp(file: string | string[], [options: TimestampOptions], [runOptions: RunOptions]): Promise

The timestamp command allows to time stamps files.

Switch Option Description
/t url The file being time stamped must have previously been signed.
/tr rfcUrl Specifies the RFC 3161 time stamp server's URL.
/tseal sealUrl Specifies the RFC 3161 timestamp server's URL for timestamping a Sealed file.
/td algorithm Used with the rfcUrl switch to request a digest algorithm used by the RFC 3161 time stamp server.
/tp index Adds a timestamp to the signature at index.
/p7 pkcs Adds a timestamp to PKCS #7 files.

signtool.catdb(file: string | string[], [options: CatDBOptions], [runOptions: RunOptions]): Promise

The catdb command allows to add or remove a catalog file to or from a catalog database.

Switch Option Description
/d default Specifies that the default catalog database be updated.
/g guid Specifies that the catalog database identified by the GUID be updated.
/r remove Removes the specified catalog from the catalog database.
/u unique Specifies that a unique name be automatically generated for the added catalog files.

RunOptions

Run options are optional. It allows to enable some common signtool switches and to specify some child_process.spawn() options.

Common Switches
Switch Option Description
/q quiet No output on success and minimal output on failure.
/v verbose Print verbose success and status messages.
/debug debug Display additional debug information.
Spawn Options
Spawn Option Description
cwd cwd Specifies the Current Working Directory to execute signtool on.
stdio stdio Specifies the spawn stdio option.

Contribute

Install Global Dependencies

node-signtool needs some development dependencies:

$ npm install -g typings

Install Project dependencies

$ npm install && typings install

Build project

$ npm run build