xenial (1) softhsm.1.gz

Provided by: softhsm_1.3.7-4_amd64 bug

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
       softhsm --optimize --slot number --pin PIN
       softhsm --trusted bool --slot number [--so-pin PIN] \
              --type text [--label text || --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. Cannot be used in
              combination with --module, since the keys are extracted from the SoftHSM database, thus not  using
              PKCS#11.
              Use with --file-pin, --slot, --pin, and --id.

       --optimize
              Clean  up  leftovers  (session objects in the database) from applications that haven't closed down
              properly. Cannot be used in combination with --module.
              Use with --slot and --pin.

       --trusted bool
              Mark the object as trusted. true or false.
              Use with --slot, --so-pin, --type, and ( --id, or --label).

       --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.

       --module path
              Use another PKCS#11 library than SoftHSM.

       --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).

       --type text
              The type of object. CKO_PUBLIC_KEY or CKO_CERTIFICATE.

       --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 YOUR TOKEN> ".backup 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)