summaryrefslogtreecommitdiffstats
path: root/doc/arm/pkcs11.xml
blob: 973845f10c1dfdab881894ed255d245a2e9c5978 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
<!DOCTYPE book [
<!ENTITY mdash "&#8212;">]>
<!--
 - Copyright (C) Internet Systems Consortium, Inc. ("ISC")
 -
 - This Source Code Form is subject to the terms of the Mozilla Public
 - License, v. 2.0. If a copy of the MPL was not distributed with this
 - file, You can obtain one at http://mozilla.org/MPL/2.0/.
 -
 - See the COPYRIGHT file distributed with this work for additional
 - information regarding copyright ownership.
-->

<!-- Converted by db4-upgrade version 1.0 -->
<section xmlns:db="http://docbook.org/ns/docbook" version="5.0" xml:id="pkcs11"><info><title>PKCS#11 (Cryptoki) support</title></info>

  <para>
    PKCS#11 (Public Key Cryptography Standard #11) defines a
    platform-independent API for the control of hardware security
    modules (HSMs) and other cryptographic support devices.
  </para>
  <para>
    BIND 9 is known to work with three HSMs: The AEP Keyper, which has
    been tested with Debian Linux, Solaris x86 and Windows Server 2003;
    the Thales nShield, tested with Debian Linux; and the Sun SCA 6000
    cryptographic acceleration board, tested with Solaris x86.  In
    addition, BIND can be used with all current versions of SoftHSM,
    a software-based HSM simulator library produced by the OpenDNSSEC
    project.
  </para>
  <para>
    PKCS#11 makes use of a "provider library": a dynamically loadable
    library which provides a low-level PKCS#11 interface to drive the HSM
    hardware.  The PKCS#11 provider library comes from the HSM vendor, and
    it is specific to the HSM to be controlled.
  </para>
  <para>
    There are two available mechanisms for PKCS#11 support in BIND 9:
    OpenSSL-based PKCS#11 and native PKCS#11.  When using the first
    mechanism, BIND uses a modified version of OpenSSL, which loads
    the provider library and operates the HSM indirectly; any
    cryptographic operations not supported by the HSM can be carried
    out by OpenSSL instead.  The second mechanism enables BIND to bypass
    OpenSSL completely; BIND loads the provider library itself, and uses
    the PKCS#11 API to drive the HSM directly.
  </para>
  <section><info><title>Prerequisites</title></info>

    <para>
      See the documentation provided by your HSM vendor for
      information about installing, initializing, testing and
      troubleshooting the HSM.
    </para>
  </section>
  <section><info><title>Native PKCS#11</title></info>

    <para>
      Native PKCS#11 mode will only work with an HSM capable of carrying
      out <emphasis>every</emphasis> cryptographic operation BIND 9 may
      need. The HSM's provider library must have a complete implementation
      of the PKCS#11 API, so that all these functions are accessible. As of
      this writing, only the Thales nShield HSM and SoftHSMv2 can be used
      in this fashion.  For other HSMs, including the AEP Keyper, Sun SCA
      6000 and older versions of SoftHSM, use OpenSSL-based PKCS#11.
      (Note: Eventually, when more HSMs become capable of supporting
      native PKCS#11, it is expected that OpenSSL-based PKCS#11 will
      be deprecated.)
    </para>
    <para>
      To build BIND with native PKCS#11, configure as follows:
    </para>
    <screen>
$ <userinput>cd bind9</userinput>
$ <userinput>./configure --enable-native-pkcs11 \
    --with-pkcs11=<replaceable>provider-library-path</replaceable></userinput>
    </screen>
    <para>
      This will cause all BIND tools, including <command>named</command>
      and the <command>dnssec-*</command> and <command>pkcs11-*</command>
      tools, to use the PKCS#11 provider library specified in
      <replaceable>provider-library-path</replaceable> for cryptography.
      (The provider library path can be overridden using the
      <option>-E</option> in <command>named</command> and the
      <command>dnssec-*</command> tools, or the <option>-m</option> in
      the <command>pkcs11-*</command> tools.)
    </para>
    <section><info><title>Building SoftHSMv2</title></info>

      <para>
	SoftHSMv2, the latest development version of SoftHSM, is available
	from
	<link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://github.com/opendnssec/SoftHSMv2">
	  https://github.com/opendnssec/SoftHSMv2
	</link>.
	It is a software library developed by the OpenDNSSEC project
	(<link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.opendnssec.org">
	  http://www.opendnssec.org
	</link>)
	which provides a PKCS#11 interface to a virtual HSM, implemented in
	the form of a SQLite3 database on the local filesystem.  It provides
	less security than a true HSM, but it allows you to experiment with
	native PKCS#11 when an HSM is not available.  SoftHSMv2 can be
	configured to use either OpenSSL or the Botan library to perform
	cryptographic functions, but when using it for native PKCS#11 in
	BIND, OpenSSL is required.
      </para>
      <para>
	By default, the SoftHSMv2 configuration file is
	<replaceable>prefix</replaceable>/etc/softhsm2.conf (where
	<replaceable>prefix</replaceable> is configured at compile time).
	This location can be overridden by the SOFTHSM2_CONF environment
	variable.  The SoftHSMv2 cryptographic store must be installed and
	initialized before using it with BIND.
      </para>
      <screen>
$ <userinput> cd SoftHSMv2 </userinput>
$ <userinput> configure --with-crypto-backend=openssl --prefix=/opt/pkcs11/usr --enable-gost </userinput>
$ <userinput> make </userinput>
$ <userinput> make install </userinput>
$ <userinput> /opt/pkcs11/usr/bin/softhsm-util --init-token 0 --slot 0 --label softhsmv2 </userinput>
      </screen>
    </section>
  </section>
  <section><info><title>OpenSSL-based PKCS#11</title></info>

    <para>
      OpenSSL-based PKCS#11 mode uses a modified version of the
      OpenSSL library; stock OpenSSL does not fully support PKCS#11.
      ISC provides a patch to OpenSSL to correct this.  This patch is
      based on work originally done by the OpenSolaris project; it has been
      modified by ISC to provide new features such as PIN management and
      key-by-reference.
    </para>
    <para>
      There are two "flavors" of PKCS#11 support provided by
      the patched OpenSSL, one of which must be chosen at
      configuration time. The correct choice depends on the HSM
      hardware:
    </para>
    <itemizedlist>
      <listitem>
	<para>
	  Use 'crypto-accelerator' with HSMs that have hardware
	  cryptographic acceleration features, such as the SCA 6000
	  board. This causes OpenSSL to run all supported
	  cryptographic operations in the HSM.
	</para>
      </listitem>
      <listitem>
	<para>
	  Use 'sign-only' with HSMs that are designed to
	  function primarily as secure key storage devices, but lack
	  hardware acceleration. These devices are highly secure, but
	  are not necessarily any faster at cryptography than the
	  system CPU &mdash; often, they are slower. It is therefore
	  most efficient to use them only for those cryptographic
	  functions that require access to the secured private key,
	  such as zone signing, and to use the system CPU for all
	  other computationally-intensive operations. The AEP Keyper
	  is an example of such a device.
	</para>
      </listitem>
    </itemizedlist>
    <para>
      The modified OpenSSL code is included in the BIND 9 release,
      in the form of a context diff against the latest versions of
      OpenSSL.  OpenSSL 0.9.8, 1.0.0, 1.0.1 and 1.0.2 are supported;
      there are separate diffs for each version.  In the examples to
      follow, we use OpenSSL 0.9.8, but the same methods work with
      OpenSSL 1.0.0 through 1.0.2.
    </para>
    <note><simpara>
      The OpenSSL patches as of this writing (January 2016)
      support versions 0.9.8zh, 1.0.0t, 1.0.1q and 1.0.2f.
      ISC will provide updated patches as new versions of OpenSSL
      are released. The version number in the following examples
      is expected to change.
    </simpara></note>
    <para>
      Before building BIND 9 with PKCS#11 support, it will be
      necessary to build OpenSSL with the patch in place, and configure
      it with the path to your HSM's PKCS#11 provider library.
    </para>
    <section><info><title>Patching OpenSSL</title></info>

      <screen>
$ <userinput>wget <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="">http://www.openssl.org/source/openssl-0.9.8zc.tar.gz</link></userinput>
  </screen>
      <para>Extract the tarball:</para>
      <screen>
$ <userinput>tar zxf openssl-0.9.8zc.tar.gz</userinput>
</screen>
      <para>Apply the patch from the BIND 9 release:</para>
      <screen>
$ <userinput>patch -p1 -d openssl-0.9.8zc \
	      &lt; bind9/bin/pkcs11/openssl-0.9.8zc-patch</userinput>
</screen>
      <note><simpara>
	The patch file may not be compatible with the
	"patch" utility on all operating systems. You may need to
	install GNU patch.
      </simpara></note>
      <para>
	When building OpenSSL, place it in a non-standard
	location so that it does not interfere with OpenSSL libraries
	elsewhere on the system. In the following examples, we choose
	to install into "/opt/pkcs11/usr". We will use this location
	when we configure BIND 9.
      </para>
      <para>
	Later, when building BIND 9, the location of the custom-built
	OpenSSL library will need to be specified via configure.
      </para>
    </section>
    <section><info><title>Building OpenSSL for the AEP Keyper on Linux</title></info>
      <!-- Example 1 -->

      <para>
	The AEP Keyper is a highly secure key storage device,
	but does not provide hardware cryptographic acceleration. It
	can carry out cryptographic operations, but it is probably
	slower than your system's CPU. Therefore, we choose the
	'sign-only' flavor when building OpenSSL.
      </para>
      <para>
	The Keyper-specific PKCS#11 provider library is
	delivered with the Keyper software. In this example, we place
	it /opt/pkcs11/usr/lib:
      </para>
      <screen>
$ <userinput>cp pkcs11.GCC4.0.2.so.4.05 /opt/pkcs11/usr/lib/libpkcs11.so</userinput>
</screen>
      <para>
	The Keyper library requires threads, so we
	must specify -pthread.
      </para>
      <screen>
$ <userinput>cd openssl-0.9.8zc</userinput>
$ <userinput>./Configure linux-x86_64 -pthread \
	    --pk11-libname=/opt/pkcs11/usr/lib/libpkcs11.so \
	    --pk11-flavor=sign-only \
	    --prefix=/opt/pkcs11/usr</userinput>
</screen>
      <para>
	After configuring, run "<command>make</command>"
	and "<command>make test</command>". If "<command>make
	test</command>" fails with "pthread_atfork() not found", you forgot to
	add the -pthread above.
      </para>
    </section>
    <section><info><title>Building OpenSSL for the SCA 6000 on Solaris</title></info>
      <!-- Example 2 -->

      <para>
	The SCA-6000 PKCS#11 provider is installed as a system
	library, libpkcs11. It is a true crypto accelerator, up to 4
	times faster than any CPU, so the flavor shall be
	'crypto-accelerator'.
      </para>
      <para>
	In this example, we are building on Solaris x86 on an
	AMD64 system.
      </para>
      <screen>
$ <userinput>cd openssl-0.9.8zc</userinput>
$ <userinput>./Configure solaris64-x86_64-cc \
	    --pk11-libname=/usr/lib/64/libpkcs11.so \
	    --pk11-flavor=crypto-accelerator \
	    --prefix=/opt/pkcs11/usr</userinput>
</screen>
      <para>
	(For a 32-bit build, use "solaris-x86-cc" and /usr/lib/libpkcs11.so.)
      </para>
      <para>
	After configuring, run
	<command>make</command> and
	<command>make test</command>.
      </para>
    </section>
    <section><info><title>Building OpenSSL for SoftHSM</title></info>
      <!-- Example 3 -->

      <para>
	SoftHSM (version 1) is a software library developed by the
	OpenDNSSEC project
	(<link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.opendnssec.org">
	  http://www.opendnssec.org
	</link>)
	which provides a
	PKCS#11 interface to a virtual HSM, implemented in the form of
	a SQLite3 database on the local filesystem.  SoftHSM uses
	the Botan library to perform cryptographic functions.  Though
	less secure than a true HSM, it can allow you to experiment
	with PKCS#11 when an HSM is not available.
      </para>
      <para>
	The SoftHSM cryptographic store must be installed and
	initialized before using it with OpenSSL, and the SOFTHSM_CONF
	environment variable must always point to the SoftHSM configuration
	file:
      </para>
      <screen>
$ <userinput> cd softhsm-1.3.7 </userinput>
$ <userinput> configure --prefix=/opt/pkcs11/usr </userinput>
$ <userinput> make </userinput>
$ <userinput> make install </userinput>
$ <userinput> export SOFTHSM_CONF=/opt/pkcs11/softhsm.conf </userinput>
$ <userinput> echo "0:/opt/pkcs11/softhsm.db" &gt; $SOFTHSM_CONF </userinput>
$ <userinput> /opt/pkcs11/usr/bin/softhsm --init-token 0 --slot 0 --label softhsm </userinput>
</screen>
      <para>
	SoftHSM can perform all cryptographic operations, but
	since it only uses your system CPU, there is no advantage to using
	it for anything but signing.  Therefore, we choose the 'sign-only'
	flavor when building OpenSSL.
      </para>
      <screen>
$ <userinput>cd openssl-0.9.8zc</userinput>
$ <userinput>./Configure linux-x86_64 -pthread \
	    --pk11-libname=/opt/pkcs11/usr/lib/libsofthsm.so \
	    --pk11-flavor=sign-only \
	    --prefix=/opt/pkcs11/usr</userinput>
</screen>
      <para>
	After configuring, run "<command>make</command>"
	and "<command>make test</command>".
      </para>
    </section>
    <para>
      Once you have built OpenSSL, run
      "<command>apps/openssl engine pkcs11</command>" to confirm
      that PKCS#11 support was compiled in correctly. The output
      should be one of the following lines, depending on the flavor
      selected:
    </para>
    <screen>
	(pkcs11) PKCS #11 engine support (sign only)
</screen>
    <para>Or:</para>
    <screen>
	(pkcs11) PKCS #11 engine support (crypto accelerator)
</screen>
    <para>
      Next, run
      "<command>apps/openssl engine pkcs11 -t</command>". This will
      attempt to initialize the PKCS#11 engine. If it is able to
      do so successfully, it will report
      <quote><literal>[ available ]</literal></quote>.
    </para>
    <para>
      If the output is correct, run
      "<command>make install</command>" which will install the
      modified OpenSSL suite to <filename>/opt/pkcs11/usr</filename>.
    </para>
    <section><info><title>Configuring BIND 9 for Linux with the AEP Keyper</title></info>
      <!-- Example 4 -->

      <para>
	To link with the PKCS#11 provider, threads must be
	enabled in the BIND 9 build.
      </para>
      <screen>
$ <userinput>cd ../bind9</userinput>
$ <userinput>./configure --enable-threads \
	   --with-openssl=/opt/pkcs11/usr \
	   --with-pkcs11=/opt/pkcs11/usr/lib/libpkcs11.so</userinput>
</screen>
    </section>
    <section><info><title>Configuring BIND 9 for Solaris with the SCA 6000</title></info>
      <!-- Example 5 -->

      <para>
	To link with the PKCS#11 provider, threads must be
	enabled in the BIND 9 build.
      </para>
      <screen>
$ <userinput>cd ../bind9</userinput>
$ <userinput>./configure CC="cc -xarch=amd64" --enable-threads \
	    --with-openssl=/opt/pkcs11/usr \
	    --with-pkcs11=/usr/lib/64/libpkcs11.so</userinput>
</screen>
      <para>(For a 32-bit build, omit CC="cc -xarch=amd64".)</para>
      <para>
	If configure complains about OpenSSL not working, you
	may have a 32/64-bit architecture mismatch. Or, you may have
	incorrectly specified the path to OpenSSL (it should be the
	same as the --prefix argument to the OpenSSL
	Configure).
      </para>
    </section>
    <section><info><title>Configuring BIND 9 for SoftHSM</title></info>
      <!-- Example 6 -->

      <screen>
$ <userinput>cd ../bind9</userinput>
$ <userinput>./configure --enable-threads \
	   --with-openssl=/opt/pkcs11/usr \
	   --with-pkcs11=/opt/pkcs11/usr/lib/libsofthsm.so</userinput>
</screen>
    </section>
    <para>
      After configuring, run
      "<command>make</command>",
      "<command>make test</command>" and
      "<command>make install</command>".
    </para>
    <para>
      (Note: If "make test" fails in the "pkcs11" system test, you may
      have forgotten to set the SOFTHSM_CONF environment variable.)
    </para>
  </section>
  <section><info><title>PKCS#11 Tools</title></info>

    <para>
      BIND 9 includes a minimal set of tools to operate the
      HSM, including
      <command>pkcs11-keygen</command> to generate a new key pair
      within the HSM,
      <command>pkcs11-list</command> to list objects currently
      available,
      <command>pkcs11-destroy</command> to remove objects, and
      <command>pkcs11-tokens</command> to list available tokens.
    </para>
    <para>
      In UNIX/Linux builds, these tools are built only if BIND
      9 is configured with the --with-pkcs11 option. (Note: If
      --with-pkcs11 is set to "yes", rather than to the path of the
      PKCS#11 provider, then the tools will be built but the
      provider will be left undefined. Use the -m option or the
      PKCS11_PROVIDER environment variable to specify the path to the
      provider.)
    </para>
  </section>
  <section><info><title>Using the HSM</title></info>

    <para>
      For OpenSSL-based PKCS#11, we must first set up the runtime
      environment so the OpenSSL and PKCS#11 libraries can be loaded:
    </para>
    <screen>
$ <userinput>export LD_LIBRARY_PATH=/opt/pkcs11/usr/lib:${LD_LIBRARY_PATH}</userinput>
</screen>
    <para>
      This causes <command>named</command> and other binaries to load
      the OpenSSL library from <filename>/opt/pkcs11/usr/lib</filename>
      rather than from the default location.  This step is not necessary
      when using native PKCS#11.
    </para>
    <para>
      Some HSMs require other environment variables to be set.
      For example, when operating an AEP Keyper, it is necessary to
      specify the location of the "machine" file, which stores
      information about the Keyper for use by the provider
      library. If the machine file is in
      <filename>/opt/Keyper/PKCS11Provider/machine</filename>,
      use:
    </para>
    <screen>
$ <userinput>export KEYPER_LIBRARY_PATH=/opt/Keyper/PKCS11Provider</userinput>
</screen>
    <para>
      Such environment variables must be set whenever running
      any tool that uses the HSM, including
      <command>pkcs11-keygen</command>,
      <command>pkcs11-list</command>,
      <command>pkcs11-destroy</command>,
      <command>dnssec-keyfromlabel</command>,
      <command>dnssec-signzone</command>,
      <command>dnssec-keygen</command>, and
      <command>named</command>.
    </para>
    <para>
      We can now create and use keys in the HSM. In this case,
      we will create a 2048 bit key and give it the label
      "sample-ksk":
    </para>
    <screen>
$ <userinput>pkcs11-keygen -b 2048 -l sample-ksk</userinput>
</screen>
    <para>To confirm that the key exists:</para>
    <screen>
$ <userinput>pkcs11-list</userinput>
Enter PIN:
object[0]: handle 2147483658 class 3 label[8] 'sample-ksk' id[0]
object[1]: handle 2147483657 class 2 label[8] 'sample-ksk' id[0]
</screen>
    <para>
      Before using this key to sign a zone, we must create a
      pair of BIND 9 key files. The "dnssec-keyfromlabel" utility
      does this. In this case, we will be using the HSM key
      "sample-ksk" as the key-signing key for "example.net":
    </para>
    <screen>
$ <userinput>dnssec-keyfromlabel -l sample-ksk -f KSK example.net</userinput>
</screen>
    <para>
      The resulting K*.key and K*.private files can now be used
      to sign the zone. Unlike normal K* files, which contain both
      public and private key data, these files will contain only the
      public key data, plus an identifier for the private key which
      remains stored within the HSM. Signing with the private key takes
      place inside the HSM.
    </para>
    <para>
      If you wish to generate a second key in the HSM for use
      as a zone-signing key, follow the same procedure above, using a
      different keylabel, a smaller key size, and omitting "-f KSK"
      from the dnssec-keyfromlabel arguments:
    </para>
    <para>
      (Note: When using OpenSSL-based PKCS#11 the label is an arbitrary
      string which identifies the key.  With native PKCS#11, the label is
      a PKCS#11 URI string which may include other details about the key
      and the HSM, including its PIN. See
      <xref linkend="man.dnssec-keyfromlabel"/> for details.)
    </para>
    <screen>
$ <userinput>pkcs11-keygen -b 1024 -l sample-zsk</userinput>
$ <userinput>dnssec-keyfromlabel -l sample-zsk example.net</userinput>
</screen>
    <para>
      Alternatively, you may prefer to generate a conventional
      on-disk key, using dnssec-keygen:
    </para>
    <screen>
$ <userinput>dnssec-keygen example.net</userinput>
</screen>
    <para>
      This provides less security than an HSM key, but since
      HSMs can be slow or cumbersome to use for security reasons, it
      may be more efficient to reserve HSM keys for use in the less
      frequent key-signing operation. The zone-signing key can be
      rolled more frequently, if you wish, to compensate for a
      reduction in key security.  (Note: When using native PKCS#11,
      there is no speed advantage to using on-disk keys, as cryptographic
      operations will be done by the HSM regardless.)
    </para>
    <para>
      Now you can sign the zone. (Note: If not using the -S
      option to <command>dnssec-signzone</command>, it will be
      necessary to add the contents of both <filename>K*.key</filename>
      files to the zone master file before signing it.)
    </para>
    <screen>
$ <userinput>dnssec-signzone -S example.net</userinput>
Enter PIN:
Verifying the zone using the following algorithms:
NSEC3RSASHA1.
Zone signing complete:
Algorithm: NSEC3RSASHA1: ZSKs: 1, KSKs: 1 active, 0 revoked, 0 stand-by
example.net.signed
</screen>
  </section>
  <section><info><title>Specifying the engine on the command line</title></info>

    <para>
      When using OpenSSL-based PKCS#11, the "engine" to be used by
      OpenSSL can be specified in <command>named</command> and all of
      the BIND <command>dnssec-*</command> tools by using the "-E
      &lt;engine&gt;" command line option. If BIND 9 is built with
      the --with-pkcs11 option, this option defaults to "pkcs11".
      Specifying the engine will generally not be necessary unless
      for some reason you wish to use a different OpenSSL
      engine.
    </para>
    <para>
      If you wish to disable use of the "pkcs11" engine &mdash;
      for troubleshooting purposes, or because the HSM is unavailable
      &mdash; set the engine to the empty string. For example:
    </para>
    <screen>
$ <userinput>dnssec-signzone -E '' -S example.net</userinput>
</screen>
    <para>
      This causes
      <command>dnssec-signzone</command> to run as if it were compiled
      without the --with-pkcs11 option.
    </para>
    <para>
      When built with native PKCS#11 mode, the "engine" option has a
      different meaning: it specifies the path to the PKCS#11 provider
      library.  This may be useful when testing a new provider library.
    </para>
  </section>
  <section><info><title>Running named with automatic zone re-signing</title></info>

    <para>
      If you want <command>named</command> to dynamically re-sign zones
      using HSM keys, and/or to to sign new records inserted via nsupdate,
      then <command>named</command> must have access to the HSM PIN. In OpenSSL-based PKCS#11,
      this is accomplished by placing the PIN into the openssl.cnf file
      (in the above examples,
      <filename>/opt/pkcs11/usr/ssl/openssl.cnf</filename>).
    </para>
    <para>
      The location of the openssl.cnf file can be overridden by
      setting the OPENSSL_CONF environment variable before running
      <command>named</command>.
    </para>
    <para>Sample openssl.cnf:</para>
    <programlisting>
	openssl_conf = openssl_def
	[ openssl_def ]
	engines = engine_section
	[ engine_section ]
	pkcs11 = pkcs11_section
	[ pkcs11_section ]
	PIN = <replaceable>&lt;PLACE PIN HERE&gt;</replaceable>
</programlisting>
    <para>
      This will also allow the dnssec-* tools to access the HSM
      without PIN entry. (The pkcs11-* tools access the HSM directly,
      not via OpenSSL, so a PIN will still be required to use
      them.)
    </para>
    <para>
      In native PKCS#11 mode, the PIN can be provided in a file specified
      as an attribute of the key's label.  For example, if a key had the label
      <userinput>pkcs11:object=local-zsk;pin-source=/etc/hsmpin</userinput>,
      then the PIN would be read from the file
      <filename>/etc/hsmpin</filename>.
    </para>
    <warning>
      <para>
	Placing the HSM's PIN in a text file in this manner may reduce the
	security advantage of using an HSM. Be sure this is what you want to
	do before configuring the system in this way.
      </para>
    </warning>
  </section>
</section>