Skip to content

Infisical is the open-source platform for securing secrets, certificates, access, and AI Agents.

6.0 KB
Raw Blame
---
title: "Sign Windows executables with osslsigncode"
sidebarTitle: "osslsigncode"
description: "Use the Infisical PKCS#11 module to sign Windows executables, DLLs, and MSI installers with osslsigncode."
---

<Info>
  This guide assumes your Product Admin has already created a [Signer](/documentation/platform/pki/code-signing/signers) and assigned you to it. If the signer has an approval policy, you'll also need [active access](/documentation/platform/pki/code-signing/approvals#access-lifecycle) before signing.
</Info>

Sign Windows Authenticode artifacts using `osslsigncode` with the Infisical PKCS#11 module. osslsigncode is a cross-platform tool that lets you sign Windows binaries from Linux and macOS, making it ideal for CI/CD pipelines that don't run on Windows.

## Prerequisites

- A [Signer](/documentation/platform/pki/code-signing/signers) created by your Product Admin
- [Active signing access](/documentation/platform/pki/code-signing/approvals#access-lifecycle) (if an approval policy is attached)
- A [machine identity](/documentation/platform/identities/machine-identities) added to the Signer
- The Infisical [PKCS#11 module](/documentation/platform/pki/code-signing/pkcs11-module) installed and configured
- `osslsigncode` 2.5 or later (includes native PKCS#11 support)

## Step 1: Set up authentication

Configure the Infisical PKCS#11 module with your machine identity credentials. Without this, the signing commands below fail with an auth error.

Create `/etc/infisical/pkcs11.conf` (or set `INFISICAL_CONFIG` to point elsewhere):

```yaml
auth:
  method: universal-auth
  universal_auth:
    client_id: "<machine-identity-client-id>"
    client_secret: "<machine-identity-client-secret>"

signer:
  id: "<signer-id>"
```

You can also pass the credentials via environment variables:

```bash
export INFISICAL_UNIVERSAL_AUTH_CLIENT_ID="<machine-identity-client-id>"
export INFISICAL_UNIVERSAL_AUTH_CLIENT_SECRET="<machine-identity-client-secret>"
```

<Note>
  Environment variables override values from the config file.
</Note>

For the full set of options, see the [PKCS#11 module configuration reference](/documentation/platform/pki/code-signing/pkcs11-module#configuration).

## Step 2: Install osslsigncode and dependencies

<Tabs>
  <Tab title="Ubuntu / Debian">
    ```bash
    sudo apt-get update
    sudo apt-get install -y osslsigncode opensc
    ```
  </Tab>
  <Tab title="macOS (Homebrew)">
    ```bash
    brew install osslsigncode opensc
    ```
  </Tab>
  <Tab title="Build from source">
    ```bash
    git clone https://github.com/mtrojnar/osslsigncode.git
    cd osslsigncode
    mkdir build && cd build
    cmake ..
    make
    sudo make install
    ```
  </Tab>
</Tabs>

## Step 3: Identify your signer

Use `pkcs11-tool` to list available signers and note the token label:

```bash
pkcs11-tool --module /usr/local/lib/libinfisical-pkcs11.so --list-slots
```

```
Available slots:
Slot 0 (0x0): release-signer
  token label        : release-signer
  token manufacturer : Infisical
```

## Step 4: Sign a Windows executable

Use `osslsigncode` with the PKCS#11 module to sign your binary:

```bash
osslsigncode sign \
  -pkcs11module /usr/local/lib/libinfisical-pkcs11.so \
  -pkcs11cert "pkcs11:object=release-signer;type=cert" \
  -key "pkcs11:object=release-signer;type=private" \
  -h sha256 \
  -n "My Application" \
  -i "https://example.com" \
  -t http://timestamp.digicert.com \
  -in MyApp.exe \
  -out MyApp-signed.exe
```

<Note>
  - `-pkcs11module`: Path to the Infisical PKCS#11 shared library.
  - `-pkcs11cert` and `-key`: PKCS#11 URI referencing your signer by name. Replace `release-signer` with your signer name.
  - `-h sha256`: Hash algorithm for the signature digest.
  - `-n`: Description embedded in the signature (shown in Windows UAC prompts).
  - `-i`: URL for more information about the publisher.
  - `-t`: Timestamp server URL. Timestamping ensures the signature remains valid after your certificate expires.
</Note>

### Supported file types

osslsigncode can sign the following Windows artifact types:

| Type | Extensions |
|------|-----------|
| Executables | `.exe`, `.dll`, `.sys`, `.ocx` |
| Installers | `.msi`, `.msix`, `.appx` |
| Cabinet files | `.cab` |
| Scripts | `.ps1`, `.vbs` |
| Catalogs | `.cat` |

## Step 5: Verify the signature

Verify the signed binary:

```bash
osslsigncode verify MyApp-signed.exe
```

The output confirms the signature is valid:

```
Signature verification: ok
```

## CI/CD integration

```bash
export INFISICAL_UNIVERSAL_AUTH_CLIENT_ID="${INFISICAL_CLIENT_ID}"
export INFISICAL_UNIVERSAL_AUTH_CLIENT_SECRET="${INFISICAL_CLIENT_SECRET}"
export INFISICAL_CONFIG="/path/to/pkcs11.conf"

osslsigncode sign \
  -pkcs11module /usr/local/lib/libinfisical-pkcs11.so \
  -pkcs11cert "pkcs11:object=release-signer;type=cert" \
  -key "pkcs11:object=release-signer;type=private" \
  -h sha256 \
  -n "My Application" \
  -t http://timestamp.digicert.com \
  -in MyApp.exe \
  -out MyApp-signed.exe
```

## Troubleshooting

For any issue, enable debug logging in your config file (`"log_level": "debug"`, `"log_file": "/tmp/infisical-pkcs11.log"`) to get detailed output.

<AccordionGroup>
  <Accordion title="Key not found or signing errors">
    Verify the object name in the PKCS#11 URI matches your signer name exactly and that you have active signing access. You can list available signers with `pkcs11-tool --module /path/to/lib --list-slots`.
  </Accordion>
  <Accordion title="Certificate not found in PKCS#11">
    The `-pkcs11cert` URI must match your signer name exactly. Use `pkcs11-tool --module /path/to/lib --list-objects --type cert` to verify available certificate labels.
  </Accordion>
</AccordionGroup>

## What's next?

<CardGroup cols={2}>
  <Card title="Sign with OpenSSL" icon="lock" href="/documentation/platform/pki/guides/code-signing/openssl">
    General-purpose signing with OpenSSL
  </Card>
  <Card title="Sign Android APKs" icon="android" iconType="brands" href="/documentation/platform/pki/guides/code-signing/apksigner">
    Sign Android applications with apksigner
  </Card>
</CardGroup>