softhsm2-util(1)

1SOFTHSM2-UTIL(1)            General Commands Manual           SOFTHSM2-UTIL(1)
2
3
4

NAME

6       softhsm2-util - support tool for libsofthsm2
7

SYNOPSIS

9       softhsm2-util --show-slots
10
11       softhsm2-util --init-token --slot number --label text \
12              [--so-pin PIN --pin PIN]
13
14       softhsm2-util --import path [--file-pin PIN] --slot number \
15              [--pin PIN --no-public-key] --label text --id hex
16

DESCRIPTION

18       softhsm2-util  is a support tool mainly for libsofthsm2. It can also be
19       used with other PKCS#11 libraries by using the option --module
20
21       Read the sections below to get more information on the libsofthsm2  and
22       PKCS#11.   Most applications assumes that the token they want to use is
23       already initialized.  It is then up  to  the  user  to  initialize  the
24       PKCS#11  token.   This  is  done  by  using  the PKCS#11 interface, but
25       instead of writing your own tool you can use the softhsm2-util tool.
26
27       Keys are usually created directly in the token, but the user  may  want
28       to  use an existing key pair.  Keys can be imported to a token by using
29       the PKCS#11 interface, but this tool can also be used if the  user  has
30       the  key  pair in a PKCS#8 file.  If you need to convert keys from BIND
31       .private-key format over to PKCS#8, one can use softhsm2-keyconv.
32
33       The libary libsofthsm2, known as SoftHSM, provides cryptographic  func‐
34       tionality  by using the PKCS#11 API.  It was developed as a part of the
35       OpenDNSSEC  project,  thus  designed  to  meet  the   requirements   of
36       OpenDNSSEC, but can also work together with other software that want to
37       use the functionality of the PKCS#11 API.
38
39       SoftHSM is a software implementation of a generic cryptographic  device
40       with a PKCS#11 interface.  These devices are often called tokens.  Read
41       in the manual softhsm2.conf(5) on how to create these  tokens  and  how
42       they are added to a slot in SoftHSM.
43
44       The  PKCS#11  API  can  be used to handle and store cryptographic keys.
45       This interface specifies how to communicate with cryptographic  devices
46       such  as HSMs (Hardware Security Modules) and smart cards.  The purpose
47       of these devices is, among others, to generate cryptographic  keys  and
48       sign  information without revealing private-key material to the outside
49       world.  They are often designed to perform well on these specific tasks
50       compared to ordinary processes in a normal computer.
51

ACTIONS

53       --help, -h
54              Show the help information.
55
56       --import path
57              Import  a  key  pair  from  the given path.  The file must be in
58              PKCS#8-format.
59              Use with --file-pin, --slot,  --pin,  --no-public-key,  --label,
60              and --id.
61
62       --init-token
63              Initialize  the  token at a given slot.  If the token is already
64              initialized then this command will reinitialize it, thus erasing
65              all  the  objects  in  the token.  The matching Security Officer
66              (SO) PIN must also be provided when doing reinitialization.
67              Use with --slot or --free, --label, --so-pin, and --pin.
68
69       --show-slots
70              Display all the available slots and their current status.
71
72       --version, -v
73              Show the version info.
74

OPTIONS

76       --file-pin PIN
77              The PIN will be used to decrypt the PKCS#8 file.  If  not  given
78              then the PKCS#8 file is assumed to be unencrypted.
79
80       --force
81              Use  this  option  to  override the warnings and force the given
82              action.
83
84       --free Initialize the first free token.
85
86       --id hex
87              Choose an ID of the key pair.  The ID is in hexadecimal  with  a
88              variable  length.  Use with --force when importing a key pair if
89              the ID already exists.
90
91       --label text
92              Defines the label of the object or the token.
93
94       --module path
95              Use another PKCS#11 library than SoftHSM.
96
97       --no-public-key
98              Do not import the public key.
99
100       --pin PIN
101              The PIN for the normal user.
102
103       --slot number
104              The slot where the token is located.
105
106       --so-pin PIN
107              The PIN for the Security Officer (SO).
108

EXAMPLES

110       The token can be initialized using this command:
111
112              softhsm2-util --init-token --slot 1 --label "A token"
113
114       A key pair can be imported using the softhsm tool where you specify the
115       path to the key file, slot number, label and ID of the new objects, and
116       the user PIN.  The file must be in PKCS#8 format.
117
118              softhsm2-util --import key1.pem --slot 1 --label "My key" \
119                     --id A1B2 --pin 123456
120              (Add, --file-pin PIN, if the key file is encrypted.)
121

AUTHORS

123       Written by Rickard Bellgrim, Francis Dupont, René Post, and Roland  van
124       Rijswijk.
125