Provided by: softhsm_1.1.4-4_i386 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

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)