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 --free --label text \
12              [--so-pin PIN --pin PIN]
13
14       softhsm2-util --import path [--file-pin PIN] --token label \
15              [--pin PIN --no-public-key] --label text --id hex
16
17       softhsm2-util --import path --aes --token label \
18              [--pin PIN] --label text --id hex
19
20       softhsm2-util --delete-token --token text
21

DESCRIPTION

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

ACTIONS

58       --delete-token
59              Delete the token at a given slot.  Use with --token or --serial.
60              Any content in token will be erased.
61
62       --help, -h
63              Show the help information.
64
65       --import path
66              Import a key pair from the given path.   The  file  must  be  in
67              PKCS#8-format.
68              Use  with  --slot  or  --token  or  --serial, --file-pin, --pin,
69              --no-public-key, --label, and --id.
70              Can also be used with --aes to use file as is and import  it  as
71              AES.
72
73       --init-token
74              Initialize  the  token  at  a  given  slot, token label or token
75              serial.  If the token is already initialized then  this  command
76              will reinitialize it, thus erasing all the objects in the token.
77              The matching Security Officer (SO) PIN  must  also  be  provided
78              when  doing  reinitialization.  Initialized tokens will be reas‐
79              signed to another slot (based on the token serial number).
80              Use with --slot or --token or --serial or --free, --label, --so-
81              pin, and --pin.
82
83       --show-slots
84              Display all the available slots and their current status.
85
86       --version, -v
87              Show the version info.
88

OPTIONS

90       --aes  Used to tell import to use file as is and import it as AES.
91
92       --file-pin PIN
93              The  PIN  will be used to decrypt the PKCS#8 file.  If not given
94              then the PKCS#8 file is assumed to be unencrypted.
95
96       --force
97              Use this option to override the warnings  and  force  the  given
98              action.
99
100       --free Use the first free/uninitialized token.
101
102       --id hex
103              Choose  an  ID of the key pair.  The ID is in hexadecimal with a
104              variable length.  Use with --force when importing a key pair  if
105              the ID already exists.
106
107       --label text
108              Defines the label of the object or the token that will be set.
109
110       --module path
111              Use another PKCS#11 library than SoftHSM.
112
113       --no-public-key
114              Do not import the public key.
115
116       --pin PIN
117              The PIN for the normal user.
118
119       --serial number
120              Will use the token with a matching serial number.
121
122       --slot number
123              The slot where the token is located.
124
125       --so-pin PIN
126              The PIN for the Security Officer (SO).
127
128       --token label
129              Will use the token with a matching token label.
130

EXAMPLES

132       The token can be initialized using this command:
133
134              softhsm2-util --init-token --slot 1 --label "mytoken"
135
136       A key pair can be imported using the softhsm tool where you specify the
137       path to the key file, slot number, label and ID of the new objects, and
138       the user PIN.  The file must be in PKCS#8 format.
139
140              softhsm2-util --import key1.pem --token "mytoken" --label "My key" \
141                     --id A1B2 --pin 123456
142              (Add, --file-pin PIN, if the key file is encrypted.)
143

AUTHORS

145       Written  by Rickard Bellgrim, Francis Dupont, René Post, and Roland van
146       Rijswijk.
147