NAME
softhsm - support tool for libsofthsm
SYNOPSIS
softhsm --show-slots
softhsm --init-token --slot number --label text \
[--so-pin PIN --pin PIN]
softhsm --import path [--file-pin PIN] --slot number \
--pin PIN --label text --id hex
softhsm --export path [--file-pin PIN] --slot number \
--pin PIN --id hex
DESCRIPTION
softhsm is a support tool for libsofthsm. Read the sections below to
get more information on the libsofthsm and PKCS#11. Most applications
assumes that the token they want to use is already initialized. It is
then up to the user to initialize the PKCS#11 token. This is done by
using the PKCS#11 interface, but instead of writing your own tool you
can use the softhsm tool.
Keys are usually created directly in the token, but the user may want
to use an existing key pair. Keys can be imported to a token by using
the PKCS#11 interface, but this tool can also be used if the user has
the key pair in a PKCS#8 file. If you need to convert keys from BIND
.private-key format over to PKCS#8, one can use softhsm-keyconv.
A key may not always be exportable through the PKCS#11 interface, but
the export command can pull the key data directly from the token
database.
The libary libsofthsm, known as SoftHSM, provides cryptographic
functionality by using the PKCS#11 API. It was developed as a part of
the OpenDNSSEC project, thus designed to meet the requirements of
OpenDNSSEC, but can also work together with other software that want to
use the functionality of the PKCS#11 API.
SoftHSM is a software implementation of a generic cryptographic device
with a PKCS#11 interface. These devices are often called tokens. Read
in the manual softhsm.conf(5) on how to create these tokens and how
they are added to a slot in SoftHSM.
The PKCS#11 API can be used to handle and store cryptographic keys.
This interface specifies how to communicate with cryptographic devices
such as HSMs (Hardware Security Modules) and smart cards. The purpose
of these devices is, among others, to generate cryptographic keys and
sign information without revealing private-key material to the outside
world. They are often designed to perform well on these specific tasks
compared to ordinary processes in a normal computer.
OPTIONS
--show-slots
Display all the available slots and their current status.
--init-token
Initialize the token at a given slot. If the token is already
initialized then this command will reinitialize it, thus erasing
all the objects in the token. The matching Security Officer
(SO) PIN must also be provided when doing reinitialization.
Use with --slot, --label. --so-pin, and --pin.
--import path
Import a key pair from the given path. The file must be in
PKCS#8-format.
Use with --file-pin, --slot, --pin, --label, and --id.
--export path
Export a key pair to the given path. The file will be written
in PKCS#8-format.
Use with --file-pin, --slot, --pin, and --id.
--file-pin PIN
The PIN will be used to encrypt or decrypt the PKCS#8 file
depending if we are writing or reading. If not given then the
PKCS#8 file is assumed to be unencrypted.
--force
Use this option to override the warnings and force the given
action.
--help, -h
Show the help information.
--id hex
Choose an ID of the key pair. The ID is in hexadecimal with a
variable length. Use with --force when importing a key pair if
the ID already exists.
--label text
Defines the label of the object or the token.
--pin PIN
The PIN for the normal user.
--slot number
The slot where the token is located.
--so-pin PIN
The PIN for the Security Officer (SO).
--version, -v
Show the version info.
EXAMPLES
The token can be initialized using this command:
softhsm --init-token --slot 1 --label "A token"
A key pair can be imported using the softhsm tool where you specify the
path to the key file, slot number, label and ID of the new objects, and
the user PIN. The file must be in PKCS#8 format.
softhsm --import key1.pem --slot 1 --label "My key" \
--id A1B2 --pin 123456
(Add, --file-pin PIN, if the key file is encrypted.)
All keys can be exported from the token database by using the softhsm
tool. The file will be exported in PKCS#8 format.
softhsm --export key2.pem --slot 1 --id A1B2 --pin 123456
(Add, --file-pin PIN, if you want to output an encrypted file.)
A token can be backed up by issuing the command:
sqlite3 <PATH TO TOKEN> .dump | sqlite3 copy.db
Move the file "copy.db" to a secure location. To restore the token,
just copy the file back to the system and add it to a slot in the
configuration (softhsm.conf).
ENVIRONMENT
SOFTHSM_CONF
When defined, the value will be used as path to the
configuration file.
FILES
/etc/softhsm/softhsm.conf
This configuration file handles the slots and the tokens. See
softhsm.conf(5) for more information.
AUTHOR
Written by Rickard Bellgrim.
SEE ALSO
softhsm-keyconv(1), softhsm.conf(5)