DOCSEARCHbyAlgolia
Submit Docs

SoftHSMv2 Documentation

repository·main·Indexed 21 days ago

https://github.com/softhsm/softhsmv2

A software implementation of a generic cryptographic device providing a PKCS#11 interface. SoftHSMv2 allows developers to simulate Hardware Security Modules (HSMs) for cryptographic key generation and signing without physical hardware. It supports multiple cryptographic backends including OpenSSL and Botan, and provides tools for token initialization, migration, and backup.

Tokens
17.2K
Snippets
54
Records
84
Agent score
76%

What's inside SoftHSMv2

  1. View SoftHSMv2 log information

    main
    SoftHSMv2 sends log information to syslog or the Windows event log. The logging level is controlled within the softhsm2.conf file. Each log entry includes the source file name and line number for debugging.

  2. Compare File vs Database object store backends

    main

    SoftHSMv2 supports two primary backends for storing token objects: the File backend and the Database (DB) backend.

    File Backend

    • Performance: Generally exhibits the best performance, typically at least twice as fast as the database backend.
    • Mechanism: Reads the complete contents of the token into memory.
    • Best Use Case: Applications requiring the highest possible speed.

    Database (DB) Backend

    • Mechanism: Uses SQLite to store token objects. It uses transactions for writes and loads object attributes on demand.
    • Advantages:
      • Memory Efficiency: Uses approximately 20% less memory because it only loads attributes when needed.
      • Scalability: Better suited for a very large number of keys (> 100K) as it avoids filesystem limitations regarding the number of files.
    • Disadvantages:
      • Speed: Slower than the file backend due to database round-trips, especially for mutable attributes which must be re-read to ensure consistency.
      • Complexity: Requires managing a database file.

    Performance Tip: For high-speed requirements using the database backend, consider copying the entire token database to a ramdisk. Note that this should only be used if the token is not being modified, as a power cycle will wipe the ramdisk.

  3. Configure SoftHSMv2 runtime settings

    main

    SoftHSMv2 uses a configuration file to define its behavior, such as the location of the token directory.

    • Default config location: /etc/softhsm2.conf
    • Custom config location: Set the SOFTHSM2_CONF environment variable.

    Before using SoftHSM, ensure the token directory defined in your configuration file exists.

    Example: Using a custom configuration file

    export SOFTHSM2_CONF=/home/user/config.file
mkdir <token_dir_from_config>

    For detailed configuration options, use the command man softhsm2.conf.

    export SOFTHSM2_CONF=/home/user/config.file
mkdir <token_dir>

  5. Build SoftHSMv2 for Windows

    main

    To build SoftHSMv2 on Windows, you must prepare your environment with Visual Studio, CMake, and the Microsoft C/C++ dependency manager (vcpkg). This process involves cloning the necessary repositories, bootstrapping vcpkg, installing specific dependencies for both 32-bit (x86) and 64-bit (x64) architectures, and then using CMake to configure and compile the project.

    # Example workflow summary
set VCPKG_HOME=C:\Projects\vcpkg
set SOFTHSM_HOME=C:\Projects\SoftHSMv2
# ... install dependencies via vcpkg ...
# ... configure via cmake ...
# ... build via cmake --build ...

  7. Prepare working directories for Windows build

    main

    Before starting the build process, create the following directory structure on your C: drive:

    • C:\build\bin\ for compiled binaries and installed libraries.
    • C:\build\src\ for source code archives.
    mkdir C:\build\bin\
mkdir C:\build\src\

  9. Build OpenSSL 1.1.0a static library (32-bit and 64-bit)

    main

    OpenSSL 1.1.0a can be used as a crypto backend. Download the archive and signature into C:\build\src\ and verify with gpg.

    32-bit Build

    1. Extract into C:\build\src\openssl-1.1.0a-x86.
    2. In a new command line window, configure with --prefix=C:\build\bin\openssl-1.1.0a-x86 --openssldir=C:\build\bin\openssl-1.1.0a-x86\ssl no-shared.

    64-bit Build

    1. Extract into C:\build\src\openssl-1.1.0a-x64.
    2. In a new command line window, configure with --prefix=C:\build\bin\openssl-1.1.0a-x64 --openssldir=C:\build\bin\openssl-1.1.0a-x64\ssl no-shared and use vcvarsall.bat amd64.
    # 32-bit Example
cd C:\build\src\openssl-1.1.0a-x86
set PATH=%PATH%;C:\nasm
"C:\Program Files (x86)\Microsoft Visual Studio 14.0\VC\vcvarsall.bat"
perl Configure VC-WIN32 --prefix=C:\build\bin\openssl-1.1.0a-x86 --openssldir=C:\build\bin\openssl-1.1.0a-x86\ssl no-shared
nmake
nmake test
nmake install

# 64-bit Example
cd C:\build\src\openssl-1.1.0a-x64
set PATH=%PATH%;C:\nasm
"C:\Program Files (x86)\Microsoft Visual Studio 14.0\VC\vcvarsall.bat" amd64
perl Configure VC-WIN64A --prefix=C:\build\bin\openssl-1.1.0a-x64 --openssldir=C:\build\bin\openssl-1.1.0a-x64\ssl no-shared
nmake
nmake test
nmake install

  10. Build and test SoftHSMv2 on macOS

    main

    After cloning the repository and installing dependencies, follow these steps to build and verify the installation.

    1. Clone the repository:
    git clone https://github.com/opendnssec/SoftHSMv2.git
cd SoftHSMv2
    1. Generate configuration files:
    sh ./autogen.sh
    1. Configure the build: Use the --with-objectstore-backend-db flag to enable the SQLite database backend. It is recommended to use brew --prefix to ensure compatibility across Intel and Apple Silicon architectures:
    ./configure --with-objectstore-backend-db \
    --with-openssl=$(brew --prefix openssl@3) \
    --with-sqlite3=$(brew --prefix sqlite)

    Troubleshooting: If you encounter "Can't find OpenSSL headers", verify that the path provided to --with-openssl contains include/openssl/ssl.h.

    Compiler issues: If compilers are not found, explicitly export the Xcode paths:

    export CC="xcrun gcc"
export CPP="xcrun cpp"
export CXX="xcrun g++"
./configure --with-objectstore-backend-db --with-openssl=$(brew --prefix openssl@3) --with-sqlite3=$(brew --prefix sqlite)
    1. Compile:
    make
    1. Run tests: To run all tests:
    make check

    To run only the PKCS#11 test cases:

    make -C src/lib/test check
    make
make check

  11. Build SoftHSMv2 from the repository

    main

    To build SoftHSMv2 from source, you must first prepare the configuration scripts using Autotools.

    Prerequisites:

    • Install automake, autoconf, libtool, libtool-ltdl-devel (on RHEL/CentOS/Fedora), and pkg-config.
    • Ensure a cryptographic library is installed: Botan (>= 2.6.0 recommended for performance) or OpenSSL (>= 1.0.0).
    • If building the migration tool (--with-migrate) or using the database object store (--with-objectstore-backend-db), SQLite3 (>= 3.4.2) is required.
    • For unit tests, CppUnit is required.

    Steps:

    1. Run sh autogen.sh to generate configuration scripts.
    2. Run ./configure with desired options.
    3. Run make to compile.
    4. Run sudo make install to install the library.
    sh autogen.sh
./configure
make
sudo make install

  12. Configure SoftHSMv2 with CMake

    main

    Use CMake to configure the build environment. You must specify the generator, architecture, the vcpkg toolchain file, and the installation prefix. You can choose between different crypto backends (openssl or botan) and object store backends.

    # Configure 32-bit build
mkdir %SOFTHSM_HOME%\tmp32
cd %SOFTHSM_HOME%\tmp32
cmake .. -G "Visual Studio 15 2017" -A Win32 -DCMAKE_TOOLCHAIN_FILE=%VCPKG_HOME%\scripts\buildsystems\vcpkg.cmake -DCMAKE_INSTALL_PREFIX=%SOFTHSM_HOME%\out32 -DBUILD_TESTS=ON -DWITH_CRYPTO_BACKEND=openssl -DWITH_OBJECTSTORE_BACKEND_DB=OFF

# Configure 64-bit build
mkdir %SOFTHSM_HOME%\tmp64
cd %SOFTHSM_HOME%\tmp64
cmake .. -G "Visual Studio 15 2017" -A x64 -DCMAKE_TOOLCHAIN_FILE=%VCPKG_HOME%\scripts\buildsystems\vcpkg.cmake -DCMAKE_INSTALL_PREFIX=%SOFTHSM_HOME%\out64 -DBUILD_TESTS=ON -DWITH_CRYPTO_BACKEND=botan -DWITH_OBJECTSTORE_BACKEND_DB=ON