Skip to main content
SoftHSM v2 persists PKCS#11 token objects — keys, certificates, and data objects — using a pluggable storage backend. Two backends are available: file and db (SQLite3). The backend is selected with the objectstore.backend configuration option.

​
File backend

The file backend is the default. Each token is stored as a subdirectory inside directories.tokendir, and each PKCS#11 object within a token is stored as a separate file.

​
Directory layout

tokendir/
└── <token-uuid>/           # one directory per token
    ├── token.object        # token metadata (label, PINs, flags)
    ├── token.lock          # advisory lock file for token.object
    ├── <object-uuid>.object  # one file per PKCS#11 object
    ├── <object-uuid>.lock    # advisory lock file for the object
    └── ...
Token directories are named with a UUID assigned at token creation time. Object files are also UUID-named (generated by UUID::newUUID() at object creation). Each .object file is accompanied by a .lock file used for synchronisation between concurrent accessors.

​
Example

$ ls -l /var/lib/softhsm/tokens/
drwx------ 2 app app 4096 Jan 20 14:00 a3f2c1d0-1234-5678-abcd-000000000001/

$ ls -l /var/lib/softhsm/tokens/a3f2c1d0-1234-5678-abcd-000000000001/
-rw------- 1 app app  312 Jan 20 14:00 token.object
-rw------- 1 app app    0 Jan 20 14:00 token.lock
-rw------- 1 app app 1024 Jan 20 14:01 b7e9f2a1-aaaa-bbbb-cccc-111111111111.object
-rw------- 1 app app    0 Jan 20 14:01 b7e9f2a1-aaaa-bbbb-cccc-111111111111.lock

​
Configuration

objectstore.backend = file
directories.tokendir = /var/lib/softhsm/tokens/

​
Characteristics

  • No additional build dependencies.
  • Human-inspectable on disk (though the file format is binary).
  • Scales well for small to moderate numbers of objects.
  • Concurrent access from multiple processes relies on advisory file locking. Files are flushed before locks are released.

​
SQLite3 database backend

The db backend stores all objects for a token in a single SQLite3 database file (sqlite3.db) inside the token directory. This backend must be enabled at build time.

​
Build requirement

./configure --with-objectstore-backend-db
On Windows, the DB backend is enabled by default since 2.7.0.

​
Directory layout

tokendir/
└── <token-uuid>/           # one directory per token
    └── sqlite3.db          # single SQLite3 database for all objects
Each attribute type (boolean, integer, byte string, etc.) is stored in a dedicated table. Object identity is maintained through a primary-key relationship across tables.

​
Configuration

objectstore.backend = db
directories.tokendir = /var/lib/softhsm/tokens/

​
Characteristics

  • Requires SQLite3 at build time and at runtime.
  • Transactional writes; atomic updates across multiple attributes.
  • SQLite3 busy timeout is set to 3 minutes to handle contention under concurrent access.
  • Generally faster for tokens with a large number of objects, due to indexed lookups.
  • A single database file is easier to back up than a directory tree of individual object files.
If you switch objectstore.backend on an existing installation, the existing tokens will not be readable by the new backend. Initialise new tokens after changing the backend, or migrate data beforehand.

​
Controlling file permissions with objectstore.umask

Regardless of which backend is used, SoftHSM applies an additional umask when creating files and directories in the token store. This is configured with objectstore.umask. 
# Restrict token files to the owner only (default)
objectstore.umask = 0077

# Allow group read access
objectstore.umask = 0027
The value is in octal notation. It is applied on top of the process umask and cannot grant permissions that the process umask has already withdrawn.
Token files contain sensitive key material. The default 0077 mask ensures only the owning user can read or write token data. Relaxing this mask is not recommended unless you have a specific multi-user access requirement and understand the security implications.
Added in: 2.7.0

​
Choosing a backend

FileDB (SQLite3)
Build dependencyNoneSQLite3
Per-object isolationYesNo (single file)
Transactional writesNo (per-file flush)Yes
Large token performanceModerateBetter
Backup simplicityDirectory copySingle file copy
Windows supportYesYes (since 2.7.0)
DefaultYesNo
For most deployments the file backend is sufficient. Use the db backend if you have tokens with hundreds of objects, need atomic multi-attribute updates, or want simpler backup procedures.

Build docs developers (and LLMs) love

Get started for freeTalk to us