Skip to content

trailofbits/uthenticode

Repository files navigation

uthenticode

Tests

uthenticode (stylized as μthenticode) is a small cross-platform library for partially verifying Authenticode digital signatures.

Warning

This is not a full implementation of Authenticode; you must not use it in a way that assumes that its results are equivalent to verification on a Windows machine. See the caveats below for more details.

Read our blog post on verifying Windows binaries without Windows!

What?

Authenticode is Microsoft's code signing technology, designed to allow signing and verification of programs.

μthenticode is a cross-platform reimplementation of the verification side of Authenticode. It doesn't attempt to provide the signing side.

Why?

Because the official APIs (namely, the Wintrust API) for interacting with Authenticode signatures are baked deeply into Windows, making it difficult to verify signed Windows executables on non-Windows hosts.

Other available solutions are deficient:

  • WINE implements most of Wintrust, but is a massive (and arguably non-native) dependency for a single task.
  • osslsigncode can add signatures and check timestamps, but is CLI-focused.

Caveats

μthenticode is not identical to the Wintrust API. Crucially, it cannot perform full-chain verifications of Authenticode signatures, as it lacks access to the Trusted Publishers store.

You can use μthenticode to cryptographically verify the embedded chain. You must not assume that a "verified" binary from μthenticode's perspective will run on an unmodified Windows system. We make no claim that μthenticode's implementation of the Authenticode certificate policy is complete.

Building

μthenticode depends on pe-parse and OpenSSL 3.0 or higher, which are installed via vcpkg by following these steps:

cmake -B build -S . -DCMAKE_TOOLCHAIN_FILE=<vcpkg-path>/scripts/buildsystems/vcpkg.cmake
cmake --build build
# the default install prefix is the build directory;
# use CMAKE_INSTALL_PREFIX to modify it
cmake --build build --target install

If you have doxygen installed, you can build μthenticode's documentation with the top-level Makefile:

make doc

Pre-built (master) documentation is hosted here.

You can build the (gtest-based) unit tests with -DBUILD_TESTS=1.

Usage

μthenticode's public API is documented in uthenticode.h and in the Doxygen documentation (see above).

The svcli utility also provides a small example of using μthenticode's APIs. You can build it by passing -DBUILD_SVCLI=1 to cmake:

cmake -DBUILD_SVCLI=1 -B build -S . -DCMAKE_TOOLCHAIN_FILE=<vcpkg-path>/scripts/buildsystems/vcpkg.cmake
cmake --build build
./build/src/svcli/svcli /path/to/some.exe

Resources

The following resources were essential to uthenticode's development: