Debian Codegraph @

doc/README.icsf_stdll

raw
1 THE ICSF TOKEN
2
3 Overview
4 --------
5
6 The ICSF token is a clear-key, remote crypto token. The actual crypto operations
7 are performed remotely on a 390x server and all the PKCS#11 key objects are
8 stored remotely on the server.
9
10 openCryptoki's ICSF token sends ICSF service calls to the remote server via
11 LDAP. Extensions to LDAP and the addition of a remote crypto plugin allow the
12 remote LDAP server to receive the request and interface with ICSF to service the
13 request. ICSF interfaces with the crypto hardware and the z/OS keystore to
14 service the request. Upon completion, the result is passed back through the same
15 channels.
16
17 The PKCS#11 key objects are created or generated remotely. The remote z/OS
18 keystore stores all the created or generated key objects, allowing for
19 centralized storage and key management.
20
21 The remote server's configuration is outside the scope of this README.
22
23 Please see the related z/OS documentation for more information on the z/OS
24 LDAP server requirements and remote crypto configuration, as well as on
25 ICSF PKCS#11.
26
27 Pre-requisites:
28 1. ICSF token communicates to the remote via LDAP.
29 On Linux install openldap, openldap-clients, and openldap-devel.
30
31 2. You will also need lex and yacc packages installed.
32
33 For more details about the ICSF token, please also see
34 https://www.ibm.com/docs/en/linux-on-systems?topic=specifications-icsf-token
35
36 -----------------------------------------------------------------------
37
38 CONFIGURING THE ICSF TOKEN
39
40 Some setup of the ICSF token must be done for openCryptoki before initializing
41 it with the pkcsconf utility.
42
43 You will need,
44 - LDAP bind information
45 - The name of an ICSF token created on the remote server.
46
47
48 LDAP Bind Information
49 ---------------------
50 openCryptoki must bind and authenticate to the remote LDAP server. openCryptoki
51 supports the Simple and SASL authentication methods when authenticating with the
52 remote LDAP server to send an ICSF service request.
53
54 You have the option of using,
55 1. existing LDAP config files for the information required to bind and
56 authenticate to the LDAP server.
57
58 OR
59
60 2. you can give the information to openCryptoki to store and use when
61 binding and authenticating to LDAP server. This is done through the
62 pkcsiscf utility.
63
64 The first option involves using an existing LDAP config file to bind and
65 authenticate to the remote server.
66
67 When openCryptoki calls the openldap function to bind and authenticate, the
68 openldap function call will look for the ldaprc config file to acquire the
69 information it needs to bind and authenticate to the server.
70
71 When using this option,
72 - with Simple authentication, you need to specify the authentication
73 mechanism as simple when adding the ICSF token into openCryptoki with the
74 pkcsicsf utility. You will also be prompted for the RACF password, which
75 will be securely stored on disk by openCryptoki for subsequent use.
76
77 - with SASL authentication, you need to specify the authentication mechanism
78 as sasl when adding the ICSF token into opecryptoki with the pkcsicsf
79 utility. SASL does not require an RACF password, so you will not be
80 prompted for this information.
81
82 **Note, when using the first option, users should have the same information in
83 their .ldaprc files.
84
85 The second option, chooses to give openCryptoki the necessary ldap credentials
86 to store in an openCryptoki config file for subsequent use. With this option
87 the credentials are stored in one place for all who access openCryptoki's ICSF
88 token.
89
90 When openCryptoki calls the openldap function to bind and authenticate, it will
91 pass along the information stored in the ICFS config file to the function call.
92 For example, when simple authentication, it will pass the BINDDN and URI found
93 in this config file to the function.
94
95 When using this option,
96 - with Simple authentication, you need to specify the authentication
97 mechanism as simple, along with the BINDDN, and the URI when adding the
98 ICSF token into openCryptoki with the pkcsicsf utility. You will also be
99 prompted for the RACF password, which will be securely stored on disk for
100 subsequent use by openCryptoki.
101
102 - with SASL authentication, you need to specify the authentication mechanism
103 as sasl, along with the CERT, CACERT, and KEY when adding the ICSF token
104 into openCryptoki with the pkcsiscf utility. SASL does not require an RACF
105 password, so you will not be prompted for it.
106
107 When required, the RACF password is stored securely on disk for subsequent use
108 in /prefix/var/lib/opencryptoki/icsf/RACF.
109
110 **Note: Setup of LDAP and SASL are outside the scope of this README.
111
112
113 openCryptoki's ICSF token setup
114 -------------------------------
115 The installed opencryptoki.conf does not contain an entry for the ICSF token. An
116 entry is created upon setting up the ICSF token with the pkcsicsf utility.
117
118 openCryptoki's ICSF token must first be set up with the pkcsiscf utility before
119 the token can be initialized with the pkcsconf utility.
120
121 Setup
122 -----
123 ICSF token(s) originate on the remote server. It is likely that they are created
124 and destroyed by the remote's system administrator. openCryptoki queries the
125 remote server for a list of the available ICSF tokens via the pkcsicsf utility.
126 The list returned may contain more than one remote token. Note, which token(s)
127 returned depend on the caller's SAF authority on the remote server.
128
129 openCryptoki can only handle one remote ICSF token. If a list of tokens are
130 returned from the query, a single token must be chosen and installed into
131 openCryptoki with the pkcsicsf utility.
132
133 Upon adding the token into openCryptoki with the pkcsicsf utility, an ICSF token
134 entry will be created in the openCryptoki.conf file.
135
136 For example,
137 slot 5 {
138 stdll = libpkcs11_icsf.so
139 confname = /usr/local/etc/opencryptoki/JML.conf
140 }
141
142 Also, a separate ICSF token config file will be created,
143 /prefix/etc/opencryptoki/<tokenname>.conf, containing information required to
144 bind to the LDAP server if any was specified. It will also contain information
145 from the remote server about the particular ICSF token that was added.
146
147 In this example, /usr/local/etc/opencryptoki/JML.conf was created. And since I
148 am using .ldaprc file, it only specifies the authentication method.
149 slot 5 {
150 TOKEN_NAME = "JML"
151 TOKEN_MANUFACTURE = "IBM"
152 TOKEN_MODEL = "ICSFModel"
153 TOKEN_SERIAL = "012345"
154 MECH = "SIMPLE"
155 }
156
157 And lastly, when using simple authentication, a secured RACF password file will
158 have been created.
159
160
161 EXAMPLE OF HOW TO CONFIGURE THE ICSF TOKEN
162 ------------------------------------------
163 First, get a list of the available tokens from the remote server. From the list
164 choose one token and add it into openCryptoki. After successfully adding the
165 ICSF token and any relatedinformation into openCryptoki, initialize the ICSF
166 token.
167
168 Examples to get a list of available tokens
169 -------------------------------------------
170 1. Using simple authentication and .ldaprc which has BINDDN and URI set in it,
171 get a list of the available tokens from the remote.
172
173 pkcsicsf -l -m simple
174
175 you will be prompted for the racf passwd and the SO PIN.
176
177 you should get a list of the available tokens from the remote
178
179 2. Using simple authentication and giving openCryptoki the credentials to use to
180 get a list of available tokens from the remote.
181
182 pkcsicsf -l -b <binddn> -u <uri> -m simple
183
184 you will be prompted for the racf passwd and the SO PIN.
185
186 you should get a list of the available tokens from the remote
187
188 3. Using sasl authentication and ldap configuration files, get list of available
189 tokens from the remote.
190
191 pkcsicsf -l -m sasl
192
193 4. Using sasl authentication and giving openCryptoki the credentials to use to
194 get a list of available tokens from the remote.
195
196 (TO DO)
197
198
199 Examples to add a token into openCryptoki
200 ----------------------------------------- 1. Using simple authentication and
201 .ldaprc which has BINDDN and URI set in it, add the token named, Foo.
202
203 pkcsicsf -a Foo -m simple
204
205 you will be prompted for the racf passwd and the SO PIN.
206
207 An entry for the token should have been added in the
208 /usr/local/etc/opencryptoki/opencryptoki.conf file AND
209 /usr/local/etc/opencryptoki/Foo.conf should have been created.
210
211 The racf passwd should have been secured in
212 /usr/local/var/lib/opencryptoki/icsf/RACF.
213
214 2. Using simple authentication and giving openCryptoki the credentials to use,
215 add the ICSF token named, Foo. In this case, the credentials (the BINDDN and
216 URI) will be stored in the Foo.conf file that will be created.
217
218 pkcsicsf -a Foo -b <binddn> -u <uri> -m simple
219
220 pkcsicsf -l -b <binddn> -u <uri> -m simple
221
222 you will be prompted for the racf passwd and the SO PIN.
223
224 An entry for the token should have been added in the
225 /usr/local/etc/opencryptoki/opencryptoki.conf file AND
226 /usr/local/etc/opencryptoki/Foo.conf should have been created.
227
228 The racf passwd should have been secured in
229 /usr/local/var/lib/opencryptoki/icsf/RACF.
230
231 3. Using sasl authentication and ldap configuration files to authenticate, add
232 an ICSF token named, Foo into openCryptoki.
233
234 pkcsicsf -a Foo -m sasl
235
236 4. Using sasl authentication and giving openCryptoki the credentials to use to
237 get a list of available tokens from the remote. (TO DO)
238
239
240 Configure openCryptoki
241 ----------------------
242
243 Now initialize the ICSF token and set the USER and SO PINs using the pkcsconf
244 utility.
245
246 1. Start the pkcsslotd daemon
247 pkcsslotd
248
249 2. List the available tokens in openCryptoki
250 pkcsconf -t
251
252 3. Initialize the ICSF token.
253 NOTE: For this example, my ICSF token is listed in slot 5.
254 pkcsconf -I -c 5
255
256 You will be prompted for the SO PIN. The default SO PIN is 87654321
257
258 You will also be prompted to enter a unique token label. You can press
259 enter since this will be ignored. The label or name has already been
260 created on the remote server.
261
262 4. Set the user pin
263 pkcsconf -u -c 5
264
265 you will be prompted to enter the SO PIN. Enter the default SO PIN,
266 87654321.
267 You will be prompted twice to enter the new user PIN. Enter 8 digits for
268 the new user pin. Remember it so you can use it later.
269
270 6. Set a new SO PIN
271 pkcsconf -P -c 5
272
273 you will be prompted to enter the SO PIN. Enter the default SO PIN,
274 87654321.
275 You will then be prompted to enter the new SO PIN. Enter 8 digits for
276 the new SO PIN. Remember it for later use.
277
278 7. List the token and ensure it is ready.
279 pkcsconf -t -c 5
280
281 Sample output:
282 pkcsconf -t -c 5
283 Token #5 Info:
284 Label: JML
285 Manufacturer: IBM
286 Model: ICSF
287 Model Serial Number: 012345
288 Flags: 0x44D (RNG|LOGIN_REQUIRED|USER_PIN_INITIALIZED|CLOCK_ON_TOKEN|TOKEN_INITIALIZED)
289 Sessions: 0/-2
290 R/W Sessions: -1/-2
291 PIN Length: 4-8
292 Public Memory: 0xFFFFFFFF/0xFFFFFFFF
293 Private Memory: 0xFFFFFFFF/0xFFFFFFFF
294 Hardware Version: 1.0
295 Firmware Version: 1.0
296 Time: 22:09:20
297
298
299 You are now done configuring the ICSF token into openCryptoki and its ready to
300 be used.