@certchip/signer

v0.1.19

Published

a month ago

Cross-platform code and document signing CLI tool

0High
0Medium
0Low

certchip

code-signing digital-signature authenticode pdf-signing document-signing cli cross-platform

@certchip/signer

Cross-platform code and document signing CLI tool with SSH key authentication.

Features

Cross-platform - Windows, Linux, macOS (x64, arm64)
SSH Key Authentication - Ed25519, ECDSA, RSA support
Code Signing - PE executables (EXE, DLL, SYS, OCX), MSI, MSP, CAB
Document Signing - PDF with visual signature (watermark, box, barcode, QR code)
Script Signing - PowerShell, VBScript with Authenticode
Text/Source Signing - JS, Python, Go, Rust, and more
Hash-based Signing - Default mode: only hash sent to server, not the file
Windows KSP - Native Windows crypto integration (Windows only)
Structured Output - JSON, table, or CSV output for scripting and automation

Installation

# Global installation (recommended)
npm install -g @certchip/signer

# Or local installation
npm install @certchip/signer

Quick Start

signercli (Cross-platform: Windows, Linux, macOS)

# Login with SSH key authentication
signercli -login https://signer.example.com username

# Sign a file
signercli myapp.exe

# Verify signature
signercli -verify myapp.exe

# Logout
signercli -logout

signer (Windows only - KSP integration)

# Login (certificate is installed to Windows certificate store)
signer -login https://signer.example.com username

# Sign directly with signer (same options as signercli)
signer myapp.exe                              # Default: hash-only mode
signer myapp.exe -o myapp_signed.exe          # Specify output file
signer myapp.exe -file-upload -save-signed    # Upload file, save with _signed suffix

# Or use Windows signtool.exe (after login)
signtool sign /n "Your Certificate CN" /fd sha256 /tr http://timestamp.digicert.com /td sha256 myapp.exe

# Logout (removes certificate from store)
signer -logout

With local installation (npx)

# signercli (Cross-platform)
npx signercli -login https://signer.example.com username
npx signercli myapp.exe

# signer (Windows only)
npx signer -login https://signer.example.com username
npx signer myapp.exe

CLI Commands

This package provides two CLI tools with different purposes:

| | signercli | signer | |---|-----------|--------| | Purpose | Direct file signing | Direct signing + Windows signtool integration | | Platform | Windows, Linux, macOS | Windows only | | How it works | Signs files directly via server API | Signs files directly OR provides certificates to Windows crypto system | | Best for | CI/CD, cross-platform, simple signing | Windows developers, signtool.exe integration |

When to use which tool?

| Scenario | Recommended | |----------|-------------| | CI/CD pipeline (any platform) | signercli | | Linux/macOS development | signercli | | Simple file signing | signercli or signer | | Windows direct signing | signer or signercli | | Using Windows signtool.exe | signer | | Windows certificate store integration | signer | | Visual Studio post-build signing | signercli or signer |

signercli (Cross-platform)

The main CLI tool for code and document signing. Signs files directly by communicating with the signing server. Works on all platforms without any additional setup.

Authentication

# Auto-detect authentication (SSH key if exists, otherwise password prompt)
signercli -login <url> [username]

# SSH Key Authentication (explicit)
signercli -login <url> -key ~/.ssh/id_ed25519
signercli -login <url> username -key ~/.ssh/id_rsa

# Password Authentication
signercli -login <url> -user <userid>              # Password prompted interactively
signercli -login <url> -user <userid> -pw <password>  # Password on command line

# Login Options
-profile <name>       Use specific config profile
-expires <time>       Token expiration (e.g., 24h, 7d, 1w)
-cert-id <id>         Pre-specify certificate ID
-cert-serial <sn>     Pre-specify certificate serial number
-include-chain        Include certificate chain in token

# Logout
signercli -logout [url]

File Signing

# Basic signing (default: hash-only mode)
signercli <file>

# Signing options
signercli <file> -o <output>              # Specify output file
signercli <file> -save-signed             # Save with _signed suffix (preserve original)
signercli <file> -hash-only               # Hash-based signing (default)
signercli <file> -file-upload             # Upload entire file to server
signercli <file> -hash-algorithm <alg>    # sha256, sha384, sha512
signercli <file> -timestamp-url <url>     # Timestamp server URL
signercli <file> -profile <name>          # Use config profile

Note: Hash-only signing is the default mode. Only the file hash is sent to the server, not the entire file.

Signature Verification

signercli -verify <file>
signercli -verify <file> -signature-id <id>    # Verify specific signature
signercli -verify <file> -profile <name>

Certificate Management

# List available certificates
signercli -codesign-list

# Get/Set certificate ID
signercli -codesign-id                    # Show current certificate ID
signercli -codesign-id <id>               # Set certificate ID

# Get certificate PEM
signercli -codesign-cert                  # Fetch current certificate
signercli -codesign-cert -id <id>         # Fetch specific certificate
signercli -codesign-cert -o cert.pem      # Save to file

# Set private key password (for password-protected keys on server)
signercli -codesign-set <password>

Alternative: -cert commands (compatible with signer.exe)

# List certificates (with purpose filter)
signercli -cert -list                     # List all certificates
signercli -cert -list codesign            # List code signing certificates
signercli -cert -list docsign             # List document signing certificates

# Get/Set certificate ID
signercli -cert -id                       # Show current configuration
signercli -cert -id <cert_id>             # Set certificate ID
signercli -cert -id <cert_id> <label>     # Set with label

# Get certificate PEM
signercli -cert -pem

# Set private key password
signercli -cert -password <password>

Note: The -cert commands use the same API endpoints as signer.exe, ensuring full compatibility between both tools.

Configuration

Profiles store connection settings. The default profile is used when no profile is specified. Other profiles inherit missing settings from default.

# View configuration
signercli -config                         # Show config file
signercli -config list                    # List all profiles
signercli -config show <name>             # Show profile details

# Create/Update profile
signercli -config set <name> [options]

# Delete profile
signercli -config delete <name>

Profile Inheritance Example:

# Set common settings in 'default' profile
signercli -config set default -host https://signer.example.com -username admin

# Create 'production' profile (inherits host and username from default)
signercli -config set production -cert-id prod-cert-001

# Create 'staging' profile with different host (overrides default)
signercli -config set staging -host https://staging.example.com -cert-id staging-cert

# Usage
signercli -login                          # Uses 'default' profile
signercli -login -profile production      # Uses 'production' (inherits from default)
signercli -login -profile staging         # Uses 'staging' (overrides host)

Profile Options:

| Option | Description | |--------|-------------| | -host <url> | Server URL | | -ssh-key-path <path> | SSH private key path | | -username <name> | SSH username | | -user <id> | Password auth user ID | | -cert-id <id> | Default certificate ID | | -cert-serial <sn> | Certificate serial number | | -expires <time> | Token expiration (24h, 7d, 1w) | | -include-chain | Include certificate chain | | -timestamp-url <url> | Timestamp server URL | | -hash-algorithm <alg> | Default hash algorithm | | -output-format <type> | Default output format (classic, json, table, csv) |

Document Signing Options:

| Option | Description | |--------|-------------| | -doc-style <style> | watermark, box, barcode, qrcode | | -doc-position <pos> | bottom-right, bottom-left, top-right, top-left, center | | -doc-sig-position <pos> | left, center, right (for barcode/qrcode) | | -doc-font-size <size> | Font size for signature | | -doc-opacity <value> | Opacity (0.0-1.0 or 0-100) |

Windows DLL Installation

# Install DLLs to System32 (auto-requests UAC elevation)
signercli -install

# Remove DLLs from System32
signercli -uninstall

Help & Debugging

signercli -help
signercli -version

# Log levels (append to any command for debugging)
signercli <file> LOG_DBG                  # Debug output
signercli <file> LOG_INF                  # Info output
# Available: LOG_NON, LOG_ERR, LOG_WRN, LOG_DBG, LOG_INF

Version Output:

The -version command displays comprehensive version information:

# signercli -version
Certchip Signer CLI v0.1.18
Cross-platform code and document signing tool
Copyright (c) 2025 Certchip. All rights reserved.

DLL Versions (Local):
  otpkey.dll:   0.1.18.0
  Certchip.dll: 0.1.18.0

DLL Versions (System32):
  otpkey.dll:   0.1.18.0
  Certchip.dll: 0.1.18.0

| Information | Description | |-------------|-------------| | CLI Version | signercli/signer executable version | | Local DLL | DLL versions in the same directory as the executable | | System32 DLL | DLL versions installed in Windows System32 folder |

Note: DLL version information is Windows-only. On Linux/macOS, only the CLI version is displayed.

Output Format

Both signercli and signer support structured output formats for scripting and automation.

# JSON format (default for scripting)
signercli -verify myapp.exe -format json
signercli -config list -format json
signercli -logout -format json

# Table format (aligned columns)
signercli -verify myapp.exe -format table

# CSV format (spreadsheet-friendly)
signercli -config list -format csv

# Classic format (default - human-readable)
signercli -verify myapp.exe

Format Options:

| Format | Description | Best for | |--------|-------------|----------| | classic | Human-readable output (default) | Interactive use | | json | JSON structured output | CI/CD, scripting, automation | | table | Aligned table format | Terminal display | | csv | Comma-separated values | Spreadsheets, data processing |

Example: JSON output from verify command

$ signercli -verify myapp.exe -format json

{
    "command": "verify",
    "status": "valid",
    "file": "myapp.exe",
    "method": "AUTHENTICODE",
    "signer": "Example Company",
    "serialNumber": "0123456789abcdef",
    "timestamp": "2025-01-15 10:30:00",
    "success": true
}

Example: JSON output from config list

$ signercli -config list -format json

{
    "command": "config-list",
    "count": 3,
    "profiles": ["default", "production", "staging"],
    "success": true
}

Example: JSON output from login

$ signercli -login https://signer.example.com admin -pw secret -format json

{
    "command": "login",
    "status": "success",
    "username": "admin",
    "expiresIn": 86400,
    "certificate": {
        "cn": "Example Company Code Signing"
    },
    "success": true
}

Note: Interactive authentication (password prompt, SSH key selection) is not available with structured output formats. Use -user and -pw options or -key option for non-interactive login.

signer (Windows only)

Windows-specific tool that integrates with the Windows cryptographic system via KSP (Key Storage Provider). It can both sign files directly (like signercli) and register certificates in the Windows certificate store for use with signtool.exe.

Two signing methods:

Direct signing - Sign files directly with signer <file> (same as signercli)
signtool integration - Login to register certificate, then use Windows signtool.exe

# Authentication (fetches certificate to Windows store)
signer -login <url> [username]            # Login and register certificate
signer -logout                            # Logout and remove certificate

# File Signing (direct - same options as signercli)
signer <file> [options]                   # Sign a file directly
    -o <path>                             # Output file path
    -hash-only                            # Hash-based signing (default)
    -file-upload                          # Upload entire file to server
    -save-signed                          # Save with _signed suffix
    -profile <name>                       # Use specific signing profile

# Certificate Management
signer -cert -list                        # List available certificates
signer -cert -list codesign               # Filter by purpose
signer -cert -id                          # Show current certificate configuration
signer -cert -id <cert_id>                # Set certificate ID
signer -cert -pem                         # Get certificate PEM
signer -cert -password <password>         # Set private key password

# KSP Provider Management
signer -register                          # Register Certchip KSP provider
signer -unregister                        # Unregister KSP provider
signer -enum                              # List all crypto providers
signer -container                         # List key containers

# DLL Installation (auto-requests UAC elevation)
signer -install                           # Install DLLs to System32
signer -uninstall                         # Remove DLLs from System32

# Version & Help
signer -version                           # Show version and DLL info
signer -help                              # Show usage help

# After login, use standard Windows signing tools (signtool integration)
signtool sign /n "Certificate Name" /fd sha256 myapp.exe
signtool sign /sha1 <thumbprint> /fd sha256 /tr http://timestamp.digicert.com myapp.exe

Examples:

# Direct signing with output path
signer myapp.exe -o myapp_signed.exe

# Upload entire file for signing
signer myapp.exe -file-upload -o myapp_signed.exe

# Hash-only signing with _signed suffix
signer myapp.exe -save-signed

Version Output:

# signer -version
Certchip Signer v0.1.18
Windows Key Storage Provider and Code Signing Tool
Copyright (c) 2025 Certchip. All rights reserved.

DLL Versions (Local):
  otpkey.dll:   0.1.18.0
  Certchip.dll: 0.1.18.0

DLL Versions (System32):
  otpkey.dll:   0.1.18.0
  Certchip.dll: 0.1.18.0

The version output helps diagnose DLL version mismatches between local and system-wide installations.

DLL System Installation (Windows)

For system-wide DLL access (required for signtool integration), install DLLs to System32:

# Both tools auto-request UAC elevation when needed
signercli -install
signer -install

# To remove DLLs from System32
signercli -uninstall
signer -uninstall

What gets installed:

otpkey.dll → C:\Windows\System32\otpkey.dll
Certchip.dll → C:\Windows\System32\Certchip.dll

When to use:

When using signtool.exe with the Certchip KSP provider
When other applications need to access the DLLs
For system-wide certificate store integration

Node.js API

const signer = require('@certchip/signer');

// Login
await signer.login('https://signer.example.com', 'username', {
    keyPath: '~/.ssh/id_ed25519',
    expires: '24h',
    certId: 'abc123',
    includeChain: true
});

// Sign a file
await signer.sign('myapp.exe', {
    output: 'myapp_signed.exe',
    hashAlgorithm: 'sha256',
    timestampUrl: 'http://timestamp.digicert.com'
});

// Verify signature
const result = await signer.verify('myapp_signed.exe');
console.log(result.valid ? 'Valid' : 'Invalid');

// Configuration
await signer.config('set', 'production', {
    host: 'https://signer.example.com',
    username: 'john',
    expires: '12h'
});

// List certificates
const certs = await signer.listCertificates();

// Logout
await signer.logout();

Configuration Profiles

Create reusable signing profiles:

# Create a code signing profile
signercli -config set production \
    -host https://signer.example.com \
    -username john \
    -ssh-key-path ~/.ssh/id_ed25519 \
    -expires 24h \
    -cert-id abc123 \
    -include-chain \
    -timestamp-url http://timestamp.digicert.com \
    -hash-algorithm sha256

# Create a document signing profile with visual signature
signercli -config set pdf-signing \
    -host https://signer.example.com \
    -username john \
    -doc-style qrcode \
    -doc-position bottom-right \
    -doc-sig-position center \
    -doc-font-size 12 \
    -doc-opacity 0.8

# Create an automation profile with JSON output
signercli -config set automation \
    -host https://signer.example.com \
    -output-format json

# Use the profile
signercli -login -profile production
signercli myapp.exe -profile production
signercli document.pdf -profile pdf-signing
signercli -verify myapp.exe -profile automation  # Outputs JSON automatically

Supported File Types

| Type | Extensions | Method | |------|------------|--------| | Code | .exe, .dll, .sys, .ocx, .msi, .msp, .cab | Authenticode | | Document | .pdf | Server-based with visual signature | | Script | .ps1, .vbs | Authenticode | | Java | .jar | JAR signing | | Text/Source | .js, .ts, .py, .java, .c, .cpp, .go, .rs, .sh, .yml, .json, .xml, .html, .sql, .md, .txt | Embedded signature |

Package Contents

@certchip/signer/
├── lib/
│   ├── index.js          # Node.js API
│   └── index.d.ts        # TypeScript definitions
└── bin/
    ├── signercli.js      # Cross-platform wrapper
    ├── signer.js         # Windows KSP wrapper
    └── win32-x64/
        ├── signercli.exe # 9.3 MB (static build)
        ├── signer.exe    # 420 KB (static build)
        ├── otpkey.dll    # 6.2 MB (static linked)
        └── Certchip.dll  # 700 KB (KSP provider)

Binary Comparison

| | signercli | signer | |---|-----------|--------| | Platform | Windows, Linux, macOS | Windows only | | Dependencies | None (static build) | otpkey.dll, Certchip.dll | | Size | 9.3 MB | 420 KB + 6.9 MB DLLs | | Signing method | Direct (via server API) | Direct OR via Windows crypto (signtool) | | Windows KSP | No | Yes | | signtool compatible | No | Yes | | UAC auto-elevation | Yes | Yes | | Use case | CI/CD, cross-platform | Windows developers, signtool |

Examples

CI/CD Pipeline

#!/bin/bash
set -e

# Login with JSON output for parsing
result=$(signercli -login "$SIGNER_URL" -user "$SIGNER_USER" -pw "$SIGNER_PW" -format json)
if ! echo "$result" | jq -e '.success' > /dev/null; then
    echo "Login failed: $(echo "$result" | jq -r '.error')"
    exit 1
fi

# Sign all executables
for exe in dist/*.exe; do
    signercli "$exe"
done

# Logout with JSON output
signercli -logout -format json

CI/CD Pipeline with Verification

#!/bin/bash
set -e

# Sign and verify with JSON output
signercli -login "$SIGNER_URL" -user "$SIGNER_USER" -pw "$SIGNER_PW" -format json

for exe in dist/*.exe; do
    signercli "$exe"

    # Verify and parse JSON result
    verify_result=$(signercli -verify "$exe" -format json)
    status=$(echo "$verify_result" | jq -r '.status')

    if [ "$status" != "valid" ]; then
        echo "Verification failed for $exe"
        exit 1
    fi
done

signercli -logout -format json

TypeScript Usage

import * as signer from '@certchip/signer';

async function signRelease() {
    await signer.login('https://signer.example.com', 'username');

    const result = await signer.sign('app.exe', {
        output: 'app_signed.exe',
        hashAlgorithm: 'sha256'
    });

    if (result.success) {
        console.log('Signed:', result.outputPath);
    }

    await signer.logout();
}

Document Signing with Visual Signature

# Login
signercli -login https://signer.example.com username

# Sign PDF with QR code signature
signercli document.pdf \
    -doc-style qrcode \
    -doc-position bottom-right \
    -o document_signed.pdf

# Sign PDF with watermark
signercli contract.pdf \
    -doc-style watermark \
    -doc-position center \
    -doc-opacity 0.3

Windows KSP with signtool

REM First-time setup (run as Administrator):
REM 1. Install DLLs to System32
signercli -install

REM 2. Register KSP provider
signer -register

REM Daily usage:
REM Login to get certificate
signer -login https://signer.example.com username

REM Sign with signtool
signtool sign /n "Your Certificate" /fd sha256 /tr http://timestamp.digicert.com myapp.exe

REM Verify
signtool verify /pa myapp.exe

REM Logout
signer -logout

REM To uninstall:
signer -unregister
signercli -uninstall

Authentication

SSH Key (Recommended)

# Generate Ed25519 key (if needed)
ssh-keygen -t ed25519 -f ~/.ssh/id_ed25519

# Login with default key
signercli -login https://server.com username

# Login with specific key
signercli -login https://server.com username -key ~/.ssh/id_rsa

Password

signercli -login https://server.com -user admin -pw password

Environment Variables

| Variable | Description | |----------|-------------| | SIGNER_URL | Default server URL | | SIGNER_USER | Default username | | SIGNER_KEY_PATH | Default SSH key path | | SIGNER_CERT_ID | Default certificate ID |

Troubleshooting

"signer command is only available on Windows"

The signer command requires Windows KSP integration. Use signercli for cross-platform signing.

"DLL not found"

The signer.exe requires otpkey.dll and Certchip.dll. These are automatically included when installed via npm. No additional MSYS2 or system DLLs are required.

For signtool integration or system-wide access, install DLLs to System32:

signercli -install

"Access denied" during installation

The -install command requires Administrator privileges. Both signercli and signer will automatically request UAC elevation. If the UAC prompt is cancelled, run the command prompt as Administrator.

"Token expired"

signercli -login https://server.com username

"Permission denied"

On Linux/macOS, ensure the binary is executable:

chmod +x node_modules/@certchip/signer/bin/*/signercli

Requirements

Node.js >= 14.0.0
Platforms: Windows x64 (Linux x64/arm64, macOS x64/arm64 coming soon)
Server: Certchip Signer API compatible server

Note: The current npm package includes Windows x64 binaries only. Linux and macOS binaries will be added in a future release.

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

@certchip/signer

Features

Installation

Quick Start

signercli (Cross-platform: Windows, Linux, macOS)

signer (Windows only - KSP integration)

With local installation (npx)

CLI Commands

When to use which tool?

signercli (Cross-platform)

Authentication

File Signing

Signature Verification

Certificate Management

Configuration

Windows DLL Installation

Help & Debugging

Output Format

signer (Windows only)

DLL System Installation (Windows)

Node.js API

Configuration Profiles

Supported File Types

Package Contents

Binary Comparison

Examples

CI/CD Pipeline

CI/CD Pipeline with Verification

TypeScript Usage

Document Signing with Visual Signature

Windows KSP with signtool

Authentication

SSH Key (Recommended)

Password

Environment Variables

Troubleshooting

"signer command is only available on Windows"

"DLL not found"

"Access denied" during installation

"Token expired"

"Permission denied"

Requirements

License

Links