# 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:

```shell
$ npm install node-signtool --save
```

### Usage

First import `node-signtool` in your project:

```javascript
var signtool = require("signtool");
```

Then use signtool's commands:

```javascript
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:

```javascript
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<RunResult>

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<RunResult>

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<RunResult>

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<RunResult>

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:

* [typings](https://github.com/typings/typings)

```shell
$ npm install -g typings
```

### Install Project dependencies

```shell
$ npm install && typings install
```

### Build project

```shell
$ npm run build
```