Provided by: softhsm_1.3.5-1ubuntu3_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)