| blob | 385e49722363f418a8369c043cf7fede9fba4e68 |
1 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
2 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
3 [<!ENTITY mdash "—">]>
4 <!--
5 - Copyright (C) 2010, 2012-2015 Internet Systems Consortium, Inc. ("ISC")
6 -
7 - Permission to use, copy, modify, and/or distribute this software for any
8 - purpose with or without fee is hereby granted, provided that the above
9 - copyright notice and this permission notice appear in all copies.
10 -
11 - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
12 - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
13 - AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
14 - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
15 - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
16 - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
17 - PERFORMANCE OF THIS SOFTWARE.
18 -->
20 <sect1 id="pkcs11">
21 <title>PKCS#11 (Cryptoki) support</title>
22 <para>
23 PKCS#11 (Public Key Cryptography Standard #11) defines a
24 platform-independent API for the control of hardware security
25 modules (HSMs) and other cryptographic support devices.
26 </para>
27 <para>
28 BIND 9 is known to work with three HSMs: The AEP Keyper, which has
29 been tested with Debian Linux, Solaris x86 and Windows Server 2003;
30 the Thales nShield, tested with Debian Linux; and the Sun SCA 6000
31 cryptographic acceleration board, tested with Solaris x86. In
32 addition, BIND can be used with all current versions of SoftHSM,
33 a software-based HSM simulator library produced by the OpenDNSSEC
34 project.
35 </para>
36 <para>
37 PKCS#11 makes use of a "provider library": a dynamically loadable
38 library which provides a low-level PKCS#11 interface to drive the HSM
39 hardware. The PKCS#11 provider library comes from the HSM vendor, and
40 it is specific to the HSM to be controlled.
41 </para>
42 <para>
43 There are two available mechanisms for PKCS#11 support in BIND 9:
44 OpenSSL-based PKCS#11 and native PKCS#11. When using the first
45 mechanism, BIND uses a modified version of OpenSSL, which loads
46 the provider library and operates the HSM indirectly; any
47 cryptographic operations not supported by the HSM can be carried
48 out by OpenSSL instead. The second mechanism enables BIND to bypass
49 OpenSSL completely; BIND loads the provider library itself, and uses
50 the PKCS#11 API to drive the HSM directly.
51 </para>
52 <sect2>
53 <title>Prerequisites</title>
54 <para>
55 See the documentation provided by your HSM vendor for
56 information about installing, initializing, testing and
57 troubleshooting the HSM.
58 </para>
59 </sect2>
60 <sect2>
61 <title>Native PKCS#11</title>
62 <para>
63 Native PKCS#11 mode will only work with an HSM capable of carrying
64 out <emphasis>every</emphasis> cryptographic operation BIND 9 may
65 need. The HSM's provider library must have a complete implementation
66 of the PKCS#11 API, so that all these functions are accessible. As of
67 this writing, only the Thales nShield HSM and SoftHSMv2 can be used
68 in this fashion. For other HSMs, including the AEP Keyper, Sun SCA
69 6000 and older versions of SoftHSM, use OpenSSL-based PKCS#11.
70 (Note: Eventually, when more HSMs become capable of supporting
71 native PKCS#11, it is expected that OpenSSL-based PKCS#11 will
72 be deprecated.)
73 </para>
74 <para>
75 To build BIND with native PKCS#11, configure as follows:
76 </para>
77 <screen>
78 $ <userinput>cd bind9</userinput>
79 $ <userinput>./configure --enable-native-pkcs11 \
80 --with-pkcs11=<replaceable>provider-library-path</replaceable></userinput>
81 </screen>
82 <para>
83 This will cause all BIND tools, including <command>named</command>
84 and the <command>dnssec-*</command> and <command>pkcs11-*</command>
85 tools, to use the PKCS#11 provider library specified in
86 <replaceable>provider-library-path</replaceable> for cryptography.
87 (The provider library path can be overridden using the
88 <option>-E</option> in <command>named</command> and the
89 <command>dnssec-*</command> tools, or the <option>-m</option> in
90 the <command>pkcs11-*</command> tools.)
91 </para>
92 <sect3>
93 <title>Building SoftHSMv2</title>
94 <para>
95 SoftHSMv2, the latest development version of SoftHSM, is available
96 from
97 <ulink url="https://github.com/opendnssec/SoftHSMv2">
98 https://github.com/opendnssec/SoftHSMv2
99 </ulink>.
100 It is a software library developed by the OpenDNSSEC project
101 (<ulink url="http://www.opendnssec.org">
102 http://www.opendnssec.org
103 </ulink>)
104 which provides a PKCS#11 interface to a virtual HSM, implemented in
105 the form of a SQLite3 database on the local filesystem. It provides
106 less security than a true HSM, but it allows you to experiment with
107 native PKCS#11 when an HSM is not available. SoftHSMv2 can be
108 configured to use either OpenSSL or the Botan library to perform
109 cryptographic functions, but when using it for native PKCS#11 in
110 BIND, OpenSSL is required.
111 </para>
112 <para>
113 By default, the SoftHSMv2 configuration file is
114 <replaceable>prefix</replaceable>/etc/softhsm2.conf (where
115 <replaceable>prefix</replaceable> is configured at compile time).
116 This location can be overridden by the SOFTHSM2_CONF environment
117 variable. The SoftHSMv2 cryptographic store must be installed and
118 initialized before using it with BIND.
119 </para>
120 <screen>
121 $ <userinput> cd SoftHSMv2 </userinput>
122 $ <userinput> configure --with-crypto-backend=openssl --prefix=/opt/pkcs11/usr --enable-gost </userinput>
123 $ <userinput> make </userinput>
124 $ <userinput> make install </userinput>
125 $ <userinput> /opt/pkcs11/usr/bin/softhsm-util --init-token 0 --slot 0 --label softhsmv2 </userinput>
126 </screen>
127 </sect3>
128 </sect2>
129 <sect2>
130 <title>OpenSSL-based PKCS#11</title>
131 <para>
132 OpenSSL-based PKCS#11 mode uses a modified version of the
133 OpenSSL library; stock OpenSSL does not fully support PKCS#11.
134 ISC provides a patch to OpenSSL to correct this. This patch is
135 based on work originally done by the OpenSolaris project; it has been
136 modified by ISC to provide new features such as PIN management and
137 key-by-reference.
138 </para>
139 <para>
140 There are two "flavors" of PKCS#11 support provided by
141 the patched OpenSSL, one of which must be chosen at
142 configuration time. The correct choice depends on the HSM
143 hardware:
144 </para>
145 <itemizedlist>
146 <listitem>
147 <para>
148 Use 'crypto-accelerator' with HSMs that have hardware
149 cryptographic acceleration features, such as the SCA 6000
150 board. This causes OpenSSL to run all supported
151 cryptographic operations in the HSM.
152 </para>
153 </listitem>
154 <listitem>
155 <para>
156 Use 'sign-only' with HSMs that are designed to
157 function primarily as secure key storage devices, but lack
158 hardware acceleration. These devices are highly secure, but
159 are not necessarily any faster at cryptography than the
160 system CPU — often, they are slower. It is therefore
161 most efficient to use them only for those cryptographic
162 functions that require access to the secured private key,
163 such as zone signing, and to use the system CPU for all
164 other computationally-intensive operations. The AEP Keyper
165 is an example of such a device.
166 </para>
167 </listitem>
168 </itemizedlist>
169 <para>
170 The modified OpenSSL code is included in the BIND 9 release,
171 in the form of a context diff against the latest versions of
172 OpenSSL. OpenSSL 0.9.8, 1.0.0, and 1.0.1 are supported; there are
173 separate diffs for each version. In the examples to follow,
174 we use OpenSSL 0.9.8, but the same methods work with OpenSSL
175 1.0.0 and 1.0.1.
176 </para>
177 <note>
178 The latest OpenSSL versions as of this writing (January 2015)
179 are 0.9.8zc, 1.0.0o, and 1.0.1j.
180 ISC will provide updated patches as new versions of OpenSSL
181 are released. The version number in the following examples
182 is expected to change.
183 </note>
184 <para>
185 Before building BIND 9 with PKCS#11 support, it will be
186 necessary to build OpenSSL with the patch in place, and configure
187 it with the path to your HSM's PKCS#11 provider library.
188 </para>
189 <sect3>
190 <title>Patching OpenSSL</title>
191 <screen>
192 $ <userinput>wget <ulink>http://www.openssl.org/source/openssl-0.9.8zc.tar.gz</ulink></userinput>
193 </screen>
194 <para>Extract the tarball:</para>
195 <screen>
196 $ <userinput>tar zxf openssl-0.9.8zc.tar.gz</userinput>
197 </screen>
198 <para>Apply the patch from the BIND 9 release:</para>
199 <screen>
200 $ <userinput>patch -p1 -d openssl-0.9.8zc \
201 < bind9/bin/pkcs11/openssl-0.9.8zc-patch</userinput>
202 </screen>
203 <note>
204 Note that the patch file may not be compatible with the
205 "patch" utility on all operating systems. You may need to
206 install GNU patch.
207 </note>
208 <para>
209 When building OpenSSL, place it in a non-standard
210 location so that it does not interfere with OpenSSL libraries
211 elsewhere on the system. In the following examples, we choose
212 to install into "/opt/pkcs11/usr". We will use this location
213 when we configure BIND 9.
214 </para>
215 <para>
216 Later, when building BIND 9, the location of the custom-built
217 OpenSSL library will need to be specified via configure.
218 </para>
219 </sect3>
220 <sect3>
221 <!-- Example 1 -->
222 <title>Building OpenSSL for the AEP Keyper on Linux</title>
223 <para>
224 The AEP Keyper is a highly secure key storage device,
225 but does not provide hardware cryptographic acceleration. It
226 can carry out cryptographic operations, but it is probably
227 slower than your system's CPU. Therefore, we choose the
228 'sign-only' flavor when building OpenSSL.
229 </para>
230 <para>
231 The Keyper-specific PKCS#11 provider library is
232 delivered with the Keyper software. In this example, we place
233 it /opt/pkcs11/usr/lib:
234 </para>
235 <screen>
236 $ <userinput>cp pkcs11.GCC4.0.2.so.4.05 /opt/pkcs11/usr/lib/libpkcs11.so</userinput>
237 </screen>
238 <para>
239 This library is only available for Linux as a 32-bit
240 binary. If we are compiling on a 64-bit Linux system, it is
241 necessary to force a 32-bit build, by specifying -m32 in the
242 build options.
243 </para>
244 <para>
245 Finally, the Keyper library requires threads, so we
246 must specify -pthread.
247 </para>
248 <screen>
249 $ <userinput>cd openssl-0.9.8zc</userinput>
250 $ <userinput>./Configure linux-generic32 -m32 -pthread \
251 --pk11-libname=/opt/pkcs11/usr/lib/libpkcs11.so \
252 --pk11-flavor=sign-only \
253 --prefix=/opt/pkcs11/usr</userinput>
254 </screen>
255 <para>
256 After configuring, run "<command>make</command>"
257 and "<command>make test</command>". If "<command>make
258 test</command>" fails with "pthread_atfork() not found", you forgot to
259 add the -pthread above.
260 </para>
261 </sect3>
262 <sect3>
263 <!-- Example 2 -->
264 <title>Building OpenSSL for the SCA 6000 on Solaris</title>
265 <para>
266 The SCA-6000 PKCS#11 provider is installed as a system
267 library, libpkcs11. It is a true crypto accelerator, up to 4
268 times faster than any CPU, so the flavor shall be
269 'crypto-accelerator'.
270 </para>
271 <para>
272 In this example, we are building on Solaris x86 on an
273 AMD64 system.
274 </para>
275 <screen>
276 $ <userinput>cd openssl-0.9.8zc</userinput>
277 $ <userinput>./Configure solaris64-x86_64-cc \
278 --pk11-libname=/usr/lib/64/libpkcs11.so \
279 --pk11-flavor=crypto-accelerator \
280 --prefix=/opt/pkcs11/usr</userinput>
281 </screen>
282 <para>
283 (For a 32-bit build, use "solaris-x86-cc" and /usr/lib/libpkcs11.so.)
284 </para>
285 <para>
286 After configuring, run
287 <command>make</command> and
288 <command>make test</command>.
289 </para>
290 </sect3>
291 <sect3>
292 <!-- Example 3 -->
293 <title>Building OpenSSL for SoftHSM</title>
294 <para>
295 SoftHSM (version 1) is a software library developed by the
296 OpenDNSSEC project
297 (<ulink url="http://www.opendnssec.org">
298 http://www.opendnssec.org
299 </ulink>)
300 which provides a
301 PKCS#11 interface to a virtual HSM, implemented in the form of
302 a SQLite3 database on the local filesystem. SoftHSM uses
303 the Botan library to perform cryptographic functions. Though
304 less secure than a true HSM, it can allow you to experiment
305 with PKCS#11 when an HSM is not available.
306 </para>
307 <para>
308 The SoftHSM cryptographic store must be installed and
309 initialized before using it with OpenSSL, and the SOFTHSM_CONF
310 environment variable must always point to the SoftHSM configuration
311 file:
312 </para>
313 <screen>
314 $ <userinput> cd softhsm-1.3.7 </userinput>
315 $ <userinput> configure --prefix=/opt/pkcs11/usr </userinput>
316 $ <userinput> make </userinput>
317 $ <userinput> make install </userinput>
318 $ <userinput> export SOFTHSM_CONF=/opt/pkcs11/softhsm.conf </userinput>
319 $ <userinput> echo "0:/opt/pkcs11/softhsm.db" > $SOFTHSM_CONF </userinput>
320 $ <userinput> /opt/pkcs11/usr/bin/softhsm --init-token 0 --slot 0 --label softhsm </userinput>
321 </screen>
322 <para>
323 SoftHSM can perform all cryptographic operations, but
324 since it only uses your system CPU, there is no advantage to using
325 it for anything but signing. Therefore, we choose the 'sign-only'
326 flavor when building OpenSSL.
327 </para>
328 <screen>
329 $ <userinput>cd openssl-0.9.8zc</userinput>
330 $ <userinput>./Configure linux-x86_64 -pthread \
331 --pk11-libname=/opt/pkcs11/usr/lib/libsofthsm.so \
332 --pk11-flavor=sign-only \
333 --prefix=/opt/pkcs11/usr</userinput>
334 </screen>
335 <para>
336 After configuring, run "<command>make</command>"
337 and "<command>make test</command>".
338 </para>
339 </sect3>
340 <para>
341 Once you have built OpenSSL, run
342 "<command>apps/openssl engine pkcs11</command>" to confirm
343 that PKCS#11 support was compiled in correctly. The output
344 should be one of the following lines, depending on the flavor
345 selected:
346 </para>
347 <screen>
348 (pkcs11) PKCS #11 engine support (sign only)
349 </screen>
350 <para>Or:</para>
351 <screen>
352 (pkcs11) PKCS #11 engine support (crypto accelerator)
353 </screen>
354 <para>
355 Next, run
356 "<command>apps/openssl engine pkcs11 -t</command>". This will
357 attempt to initialize the PKCS#11 engine. If it is able to
358 do so successfully, it will report
359 <quote><literal>[ available ]</literal></quote>.
360 </para>
361 <para>
362 If the output is correct, run
363 "<command>make install</command>" which will install the
364 modified OpenSSL suite to <filename>/opt/pkcs11/usr</filename>.
365 </para>
366 <sect3>
367 <!-- Example 4 -->
368 <title>Configuring BIND 9 for Linux with the AEP Keyper</title>
369 <para>
370 To link with the PKCS#11 provider, threads must be
371 enabled in the BIND 9 build.
372 </para>
373 <para>
374 The PKCS#11 library for the AEP Keyper is currently
375 only available as a 32-bit binary. If we are building on a
376 64-bit host, we must force a 32-bit build by adding "-m32" to
377 the CC options on the "configure" command line.
378 </para>
379 <screen>
380 $ <userinput>cd ../bind9</userinput>
381 $ <userinput>./configure CC="gcc -m32" --enable-threads \
382 --with-openssl=/opt/pkcs11/usr \
383 --with-pkcs11=/opt/pkcs11/usr/lib/libpkcs11.so</userinput>
384 </screen>
385 </sect3>
386 <sect3>
387 <!-- Example 5 -->
388 <title>Configuring BIND 9 for Solaris with the SCA 6000</title>
389 <para>
390 To link with the PKCS#11 provider, threads must be
391 enabled in the BIND 9 build.
392 </para>
393 <screen>
394 $ <userinput>cd ../bind9</userinput>
395 $ <userinput>./configure CC="cc -xarch=amd64" --enable-threads \
396 --with-openssl=/opt/pkcs11/usr \
397 --with-pkcs11=/usr/lib/64/libpkcs11.so</userinput>
398 </screen>
399 <para>(For a 32-bit build, omit CC="cc -xarch=amd64".)</para>
400 <para>
401 If configure complains about OpenSSL not working, you
402 may have a 32/64-bit architecture mismatch. Or, you may have
403 incorrectly specified the path to OpenSSL (it should be the
404 same as the --prefix argument to the OpenSSL
405 Configure).
406 </para>
407 </sect3>
408 <sect3>
409 <!-- Example 6 -->
410 <title>Configuring BIND 9 for SoftHSM</title>
411 <screen>
412 $ <userinput>cd ../bind9</userinput>
413 $ <userinput>./configure --enable-threads \
414 --with-openssl=/opt/pkcs11/usr \
415 --with-pkcs11=/opt/pkcs11/usr/lib/libsofthsm.so</userinput>
416 </screen>
417 </sect3>
418 <para>
419 After configuring, run
420 "<command>make</command>",
421 "<command>make test</command>" and
422 "<command>make install</command>".
423 </para>
424 <para>
425 (Note: If "make test" fails in the "pkcs11" system test, you may
426 have forgotten to set the SOFTHSM_CONF environment variable.)
427 </para>
428 </sect2>
429 <sect2>
430 <title>PKCS#11 Tools</title>
431 <para>
432 BIND 9 includes a minimal set of tools to operate the
433 HSM, including
434 <command>pkcs11-keygen</command> to generate a new key pair
435 within the HSM,
436 <command>pkcs11-list</command> to list objects currently
437 available,
438 <command>pkcs11-destroy</command> to remove objects, and
439 <command>pkcs11-tokens</command> to list available tokens.
440 </para>
441 <para>
442 In UNIX/Linux builds, these tools are built only if BIND
443 9 is configured with the --with-pkcs11 option. (Note: If
444 --with-pkcs11 is set to "yes", rather than to the path of the
445 PKCS#11 provider, then the tools will be built but the
446 provider will be left undefined. Use the -m option or the
447 PKCS11_PROVIDER environment variable to specify the path to the
448 provider.)
449 </para>
450 </sect2>
451 <sect2>
452 <title>Using the HSM</title>
453 <para>
454 For OpenSSL-based PKCS#11, we must first set up the runtime
455 environment so the OpenSSL and PKCS#11 libraries can be loaded:
456 </para>
457 <screen>
458 $ <userinput>export LD_LIBRARY_PATH=/opt/pkcs11/usr/lib:${LD_LIBRARY_PATH}</userinput>
459 </screen>
460 <para>
461 This causes <command>named</command> and other binaries to load
462 the OpenSSL library from <filename>/opt/pkcs11/usr/lib</filename>
463 rather than from the default location. This step is not necessary
464 when using native PKCS#11.
465 </para>
466 <para>
467 Some HSMs require other environment variables to be set.
468 For example, when operating an AEP Keyper, it is necessary to
469 specify the location of the "machine" file, which stores
470 information about the Keyper for use by the provider
471 library. If the machine file is in
472 <filename>/opt/Keyper/PKCS11Provider/machine</filename>,
473 use:
474 </para>
475 <screen>
476 $ <userinput>export KEYPER_LIBRARY_PATH=/opt/Keyper/PKCS11Provider</userinput>
477 </screen>
478 <para>
479 Such environment variables must be set whenever running
480 any tool that uses the HSM, including
481 <command>pkcs11-keygen</command>,
482 <command>pkcs11-list</command>,
483 <command>pkcs11-destroy</command>,
484 <command>dnssec-keyfromlabel</command>,
485 <command>dnssec-signzone</command>,
486 <command>dnssec-keygen</command>, and
487 <command>named</command>.
488 </para>
489 <para>
490 We can now create and use keys in the HSM. In this case,
491 we will create a 2048 bit key and give it the label
492 "sample-ksk":
493 </para>
494 <screen>
495 $ <userinput>pkcs11-keygen -b 2048 -l sample-ksk</userinput>
496 </screen>
497 <para>To confirm that the key exists:</para>
498 <screen>
499 $ <userinput>pkcs11-list</userinput>
500 Enter PIN:
501 object[0]: handle 2147483658 class 3 label[8] 'sample-ksk' id[0]
502 object[1]: handle 2147483657 class 2 label[8] 'sample-ksk' id[0]
503 </screen>
504 <para>
505 Before using this key to sign a zone, we must create a
506 pair of BIND 9 key files. The "dnssec-keyfromlabel" utility
507 does this. In this case, we will be using the HSM key
508 "sample-ksk" as the key-signing key for "example.net":
509 </para>
510 <screen>
511 $ <userinput>dnssec-keyfromlabel -l sample-ksk -f KSK example.net</userinput>
512 </screen>
513 <para>
514 The resulting K*.key and K*.private files can now be used
515 to sign the zone. Unlike normal K* files, which contain both
516 public and private key data, these files will contain only the
517 public key data, plus an identifier for the private key which
518 remains stored within the HSM. Signing with the private key takes
519 place inside the HSM.
520 </para>
521 <para>
522 If you wish to generate a second key in the HSM for use
523 as a zone-signing key, follow the same procedure above, using a
524 different keylabel, a smaller key size, and omitting "-f KSK"
525 from the dnssec-keyfromlabel arguments:
526 </para>
527 <para>
528 (Note: When using OpenSSL-based PKCS#11 the label is an arbitrary
529 string which identifies the key. With native PKCS#11, the label is
530 a PKCS#11 URI string which may include other details about the key
531 and the HSM, including its PIN. See
532 <xref linkend="man.dnssec-keyfromlabel"/> for details.)
533 </para>
534 <screen>
535 $ <userinput>pkcs11-keygen -b 1024 -l sample-zsk</userinput>
536 $ <userinput>dnssec-keyfromlabel -l sample-zsk example.net</userinput>
537 </screen>
538 <para>
539 Alternatively, you may prefer to generate a conventional
540 on-disk key, using dnssec-keygen:
541 </para>
542 <screen>
543 $ <userinput>dnssec-keygen example.net</userinput>
544 </screen>
545 <para>
546 This provides less security than an HSM key, but since
547 HSMs can be slow or cumbersome to use for security reasons, it
548 may be more efficient to reserve HSM keys for use in the less
549 frequent key-signing operation. The zone-signing key can be
550 rolled more frequently, if you wish, to compensate for a
551 reduction in key security. (Note: When using native PKCS#11,
552 there is no speed advantage to using on-disk keys, as cryptographic
553 operations will be done by the HSM regardless.)
554 </para>
555 <para>
556 Now you can sign the zone. (Note: If not using the -S
557 option to <command>dnssec-signzone</command>, it will be
558 necessary to add the contents of both <filename>K*.key</filename>
559 files to the zone master file before signing it.)
560 </para>
561 <screen>
562 $ <userinput>dnssec-signzone -S example.net</userinput>
563 Enter PIN:
564 Verifying the zone using the following algorithms:
565 NSEC3RSASHA1.
566 Zone signing complete:
567 Algorithm: NSEC3RSASHA1: ZSKs: 1, KSKs: 1 active, 0 revoked, 0 stand-by
568 example.net.signed
569 </screen>
570 </sect2>
571 <sect2>
572 <title>Specifying the engine on the command line</title>
573 <para>
574 When using OpenSSL-based PKCS#11, the "engine" to be used by
575 OpenSSL can be specified in <command>named</command> and all of
576 the BIND <command>dnssec-*</command> tools by using the "-E
577 <engine>" command line option. If BIND 9 is built with
578 the --with-pkcs11 option, this option defaults to "pkcs11".
579 Specifying the engine will generally not be necessary unless
580 for some reason you wish to use a different OpenSSL
581 engine.
582 </para>
583 <para>
584 If you wish to disable use of the "pkcs11" engine —
585 for troubleshooting purposes, or because the HSM is unavailable
586 — set the engine to the empty string. For example:
587 </para>
588 <screen>
589 $ <userinput>dnssec-signzone -E '' -S example.net</userinput>
590 </screen>
591 <para>
592 This causes
593 <command>dnssec-signzone</command> to run as if it were compiled
594 without the --with-pkcs11 option.
595 </para>
596 <para>
597 When built with native PKCS#11 mode, the "engine" option has a
598 different meaning: it specifies the path to the PKCS#11 provider
599 library. This may be useful when testing a new provider library.
600 </para>
601 </sect2>
602 <sect2>
603 <title>Running named with automatic zone re-signing</title>
604 <para>
605 If you want <command>named</command> to dynamically re-sign zones
606 using HSM keys, and/or to to sign new records inserted via nsupdate,
607 then named must have access to the HSM PIN. In OpenSSL-based PKCS#11,
608 this is accomplished by placing the PIN into the openssl.cnf file
609 (in the above examples,
610 <filename>/opt/pkcs11/usr/ssl/openssl.cnf</filename>).
611 </para>
612 <para>
613 The location of the openssl.cnf file can be overridden by
614 setting the OPENSSL_CONF environment variable before running
615 named.
616 </para>
617 <para>Sample openssl.cnf:</para>
618 <programlisting>
619 openssl_conf = openssl_def
620 [ openssl_def ]
621 engines = engine_section
622 [ engine_section ]
623 pkcs11 = pkcs11_section
624 [ pkcs11_section ]
625 PIN = <replaceable><PLACE PIN HERE></replaceable>
626 </programlisting>
627 <para>
628 This will also allow the dnssec-* tools to access the HSM
629 without PIN entry. (The pkcs11-* tools access the HSM directly,
630 not via OpenSSL, so a PIN will still be required to use
631 them.)
632 </para>
633 <para>
634 In native PKCS#11 mode, the PIN can be provided in a file specified
635 as an attribute of the key's label. For example, if a key had the label
636 <userinput>pkcs11:object=local-zsk;pin-source=/etc/hsmpin</userinput>,
637 then the PIN would be read from the file
638 <filename>/etc/hsmpin</filename>.
639 </para>
640 <warning>
641 <para>
642 Placing the HSM's PIN in a text file in this manner may reduce the
643 security advantage of using an HSM. Be sure this is what you want to
644 do before configuring the system in this way.
645 </para>
646 </warning>
647 </sect2>
648 </sect1>