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 "—">]>
5 - Copyright (C) 2010 Internet Systems Consortium, Inc. ("ISC")
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.
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.
20 <!-- $Id: pkcs11.xml,v 1.3 2010-02-06 07:42:02 marka Exp $ -->
23 <title>PKCS #11 (Cryptoki) support</title>
24 <para>PKCS #11 (Public Key Cryptography Standard #11) defines a
25 platform- independent API for the control of hardware security
26 modules (HSMs) and other cryptographic support devices.</para>
27 <para>BIND 9 is known to work with two HSMs: The Sun SCA 6000
28 cryptographic acceleration board, tested under Solaris x86, and
29 the AEP Keyper network-attached key storage device, tested with
30 Debian Linux, Solaris x86 and Windows Server 2003.</para>
32 <title>Prerequisites</title>
33 <para>See the HSM vendor documentation for information about
34 installing, initializing, testing and troubleshooting the
36 <para>BIND 9 uses OpenSSL for cryptography, but stock OpenSSL
37 does not yet fully support PKCS #11. However, a PKCS #11 engine
38 for OpenSSL is available from the OpenSolaris project. It has
39 been modified by ISC to work with with BIND 9, and to provide
40 new features such as PIN management and key by
42 <para>The patched OpenSSL depends on a "PKCS #11 provider".
43 This is a shared library object, providing a low-level PKCS #11
44 interface to the HSM hardware. It is dynamically loaded by
45 OpenSSL at runtime. The PKCS #11 provider comes from the HSM
46 vendor, and and is specific to the HSM to be controlled.</para>
47 <para>There are two "flavors" of PKCS #11 support provided by
48 the patched OpenSSL, one of which must be chosen at
49 configuration time. The correct choice depends on the HSM
53 <para>Use 'crypto-accelerator' with HSMs that have hardware
54 cryptographic acceleration features, such as the SCA 6000
55 board. This causes OpenSSL to run all supported
56 cryptographic operations in the HSM.</para>
59 <para>Use 'sign-only' with HSMs that are designed to
60 function primarily as secure key storage devices, but lack
61 hardware acceleration. These devices are highly secure, but
62 are not necessarily any faster at cryptography than the
63 system CPU — often, they are slower. It is therefore
64 most efficient to use them only for those cryptographic
65 functions that require access to the secured private key,
66 such as zone signing, and to use the system CPU for all
67 other computationally-intensive operations. The AEP Keyper
68 is an example of such a device.</para>
71 <para>The modified OpenSSL code is included in the BIND 9.7.0
72 release, in the form of a context diff against the latest OpenSSL.
75 The latest OpenSSL version at the time of the BIND release
77 ISC will provide an updated patch as new versions of OpenSSL
78 are released. The version number in the following examples
79 is expected to change.</note>
81 Before building BIND 9 with PKCS #11 support, it will be
82 necessary to build OpenSSL with this patch in place and inform
83 it of the path to the HSM-specific PKCS #11 provider
85 <para>Obtain OpenSSL 0.9.8l:</para>
87 $ <userinput>wget <ulink>http://www.openssl.org/source/openssl-0.9.8l.tar.gz</ulink></userinput>
89 <para>Extract the tarball:</para>
91 $ <userinput>tar zxf openssl-0.9.8l.tar.gz</userinput>
93 <para>Apply the patch from the BIND 9 release:</para>
95 $ <userinput>patch -p1 -d openssl-0.9.8l \
96 < bind-9.7.0/bin/pkcs11/openssl-0.9.8l-patch</userinput>
98 <note>(Note that the patch file may not be compatible with the
99 "patch" utility on all operating systems. You may need to
100 install GNU patch.)</note>
101 <para>When building OpenSSL, place it in a non-standard
102 location so that it does not interfere with OpenSSL libraries
103 elsewhere on the system. In the following examples, we choose
104 to install into "/opt/pkcs11/usr". We will use this location
105 when we configure BIND 9.</para>
108 <title>Building OpenSSL for the AEP Keyper on Linux</title>
109 <para>The AEP Keyper is a highly secure key storage device,
110 but does not provide hardware cryptographic acceleration. It
111 can carry out cryptographic operations, but it is probably
112 slower than your system's CPU. Therefore, we choose the
113 'sign-only' flavor when building OpenSSL.</para>
114 <para>The Keyper-specific PKCS #11 provider library is
115 delivered with the Keyper software. In this example, we place
116 it /opt/pkcs11/usr/lib:</para>
118 $ <userinput>cp pkcs11.GCC4.0.2.so.4.05 /opt/pkcs11/usr/lib/libpkcs11.so</userinput>
120 <para>This library is only available for Linux as a 32-bit
121 binary. If we are compiling on a 64-bit Linux system, it is
122 necessary to force a 32-bit build, by specifying -m32 in the
123 build options.</para>
124 <para>Finally, the Keyper library requires threads, so we
125 must specify -pthread.</para>
127 $ <userinput>cd openssl-0.9.8l</userinput>
128 $ <userinput>./Configure linux-generic32 -m32 -pthread \
129 --pk11-libname=/opt/pkcs11/usr/lib/libpkcs11.so \
130 --pk11-flavor=sign-only \
131 --prefix=/opt/pkcs11/usr</userinput>
133 <para>After configuring, run "<command>make</command>"
134 and "<command>make test</command>". If "<command>make
135 test</command>" fails with "pthread_atfork() not found", you forgot to
136 add the -pthread above.</para>
140 <title>Building OpenSSL for the SCA 6000 on Solaris</title>
141 <para>The SCA-6000 PKCS #11 provider is installed as a system
142 library, libpkcs11. It is a true crypto accelerator, up to 4
143 times faster than any CPU, so the flavor shall be
144 'crypto-accelerator'.</para>
145 <para>In this example, we are building on Solaris x86 on an
148 $ <userinput>cd openssl-0.9.8l</userinput>
149 $ <userinput>./Configure solaris64-x86_64-cc \
150 --pk11-libname=/usr/lib/64/libpkcs11.so \
151 --pk11-flavor=crypto-accelerator \
152 --prefix=/opt/pkcs11/usr</userinput>
154 <para>(For a 32-bit build, use "solaris-x86-cc" and
155 /usr/lib/libpkcs11.so.)</para>
156 <para>After configuring, run
157 <command>make</command> and
158 <command>make test</command>.</para>
159 <para>Once you have built OpenSSL, run
160 "<command>apps/openssl engine pkcs11</command>" to confirm
161 that PKCS #11 support was compiled in correctly. The output
162 should be one of the following lines, depending on the flavor
165 (pkcs11) PKCS #11 engine support (sign only)
169 (pkcs11) PKCS #11 engine support (crypto accelerator)
172 "<command>apps/openssl engine pkcs11 -t</command>". This will
173 attempt to initialize the PKCS #11 engine. If it is able to
174 do so successfully, it will report
175 <quote><literal>[ available ]</literal></quote>.</para>
176 <para>If the output is correct, run
177 "<command>make install</command>" which will install the
178 modified OpenSSL suite to
179 <filename>/opt/pkcs11/usr</filename>.</para>
183 <title>Building BIND 9 with PKCS#11</title>
184 <para>When building BIND 9, the location of the custom-built
185 OpenSSL library must be specified via configure.</para>
188 <title>Configuring BIND 9 for Linux</title>
189 <para>To link with the PKCS #11 provider, threads must be
190 enabled in the BIND 9 build.</para>
191 <para>The PKCS #11 library for the AEP Keyper is currently
192 only available as a 32-bit binary. If we are building on a
193 64-bit host, we must force a 32-bit build by adding "-m32" to
194 the CC options on the "configure" command line.</para>
196 $ <userinput>cd ../bind-9.7.0</userinput>
197 $ <userinput>./configure CC="gcc -m32" --enable-threads \
198 --with-openssl=/opt/pkcs11/usr \
199 --with-pkcs11=/opt/pkcs11/usr/lib/libpkcs11.so</userinput>
204 <title>Configuring BIND 9 for Solaris</title>
205 <para>To link with the PKCS #11 provider, threads must be
206 enabled in the BIND 9 build.</para>
208 $ <userinput>cd ../bind-9.7.0</userinput>
209 $ <userinput>./configure CC="cc -xarch=amd64" --enable-threads \
210 --with-openssl=/opt/pkcs11/usr \
211 --with-pkcs11=/usr/lib/64/libpkcs11.so</userinput>
213 <para>(For a 32-bit build, omit CC="cc -xarch=amd64".)</para>
214 <para>If configure complains about OpenSSL not working, you
215 may have a 32/64-bit architecture mismatch. Or, you may have
216 incorrectly specified the path to OpenSSL (it should be the
217 same as the --prefix argument to the OpenSSL
220 <para>After configuring, run
221 "<command>make</command>",
222 "<command>make test</command>" and
223 "<command>make install</command>".</para>
226 <title>PKCS #11 Tools</title>
227 <para>BIND 9 includes a minimal set of tools to operate the
229 <command>pkcs11-keygen</command> to generate a new key pair
231 <command>pkcs11-list</command> to list objects currently
233 <command>pkcs11-destroy</command> to remove objects.</para>
234 <para>In UNIX/Linux builds, these tools are built only if BIND
235 9 is configured with the --with-pkcs11 option. (NOTE: If
236 --with-pkcs11 is set to "yes", rather than to the path of the
237 PKCS #11 provider, then the tools will be built but the
238 provider will be left undefined. Use the -m option or the
239 PKCS11_PROVIDER environment variable to specify the path to the
243 <title>Using the HSM</title>
244 <para>First, we must set up the runtime environment so the
245 OpenSSL and PKCS #11 libraries can be loaded:</para>
247 $ <userinput>export LD_LIBRARY_PATH=/opt/pkcs11/usr/lib:${LD_LIBRARY_PATH}</userinput>
249 <para>When operating an AEP Keyper, it is also necessary to
250 specify the location of the "machine" file, which stores
251 information about the Keyper for use by PKCS #11 provider
252 library. If the machine file is in
253 <filename>/opt/Keyper/PKCS11Provider/machine</filename>,
256 $ <userinput>export KEYPER_LIBRARY_PATH=/opt/Keyper/PKCS11Provider</userinput>
258 <!-- TODO: why not defined at compile time? -->
259 <para>These environment variables must be set whenever running
260 any tool that uses the HSM, including
261 <command>pkcs11-keygen</command>,
262 <command>pkcs11-list</command>,
263 <command>pkcs11-destroy</command>,
264 <command>dnssec-keyfromlabel</command>,
265 <command>dnssec-signzone</command>,
266 <command>dnssec-keygen</command>(which will use the HSM for
267 random number generation), and
268 <command>named</command>.</para>
269 <para>We can now create and use keys in the HSM. In this case,
270 we will create a 2048 bit key and give it the label
273 $ <userinput>pkcs11-keygen -b 2048 -l sample-ksk</userinput>
275 <para>To confirm that the key exists:</para>
277 $ <userinput>pkcs11-list</userinput>
279 object[0]: handle 2147483658 class 3 label[8] 'sample-ksk' id[0]
280 object[1]: handle 2147483657 class 2 label[8] 'sample-ksk' id[0]
282 <para>Before using this key to sign a zone, we must create a
283 pair of BIND 9 key files. The "dnssec-keyfromlabel" utility
284 does this. In this case, we will be using the HSM key
285 "sample-ksk" as the key-signing key for "example.net":</para>
287 $ <userinput>dnssec-keyfromlabel -l sample-ksk -f KSK example.net</userinput>
289 <para>The resulting K*.key and K*.private files can now be used
290 to sign the zone. Unlike normal K* files, which contain both
291 public and private key data, these files will contain only the
292 public key data, plus an identifier for the private key which
293 remains stored within the HSM. The HSM handles signing with the
295 <para>If you wish to generate a second key in the HSM for use
296 as a zone-signing key, follow the same procedure above, using a
297 different keylabel, a smaller key size, and omitting "-f KSK"
298 from the dnssec-keyfromlabel arguments:</para>
300 $ <userinput>pkcs11-keygen -b 1024 -l sample-zsk</userinput>
301 $ <userinput>dnssec-keyfromlabel -l sample-zsk example.net</userinput>
303 <para>Alternatively, you may prefer to generate a conventional
304 on-disk key, using dnssec-keygen:</para>
306 $ <userinput>dnssec-keygen example.net</userinput>
308 <para>This provides less security than an HSM key, but since
309 HSMs can be slow or cumbersome to use for security reasons, it
310 may be more efficient to reserve HSM keys for use in the less
311 frequent key-signing operation. The zone-signing key can be
312 rolled more frequently, if you wish, to compensate for a
313 reduction in key security.</para>
314 <para>Now you can sign the zone. (Note: If not using the -S
316 <command>dnssec-signzone</command>, it will be necessary to add
318 <filename>K*.key</filename> files to the zone master file before
321 $ <userinput>dnssec-signzone -S example.net</userinput>
323 Verifying the zone using the following algorithms:
325 Zone signing complete:
326 Algorithm: NSEC3RSASHA1: ZSKs: 1, KSKs: 1 active, 0 revoked, 0 stand-by
331 <title>Specifying the engine on the command line</title>
332 <para>The OpenSSL engine can be specified in
333 <command>named</command> and all of the BIND
334 <command>dnssec-*</command> tools by using the "-E
335 <engine>" command line option. If BIND 9 is built with
336 the --with-pkcs11 option, this option defaults to "pkcs11".
337 Specifying the engine will generally not be necessary unless
338 for some reason you wish to use a different OpenSSL
340 <para>If you wish to disable use of the "pkcs11" engine —
341 for troubleshooting purposes, or because the HSM is unavailable
342 — set the engine to the empty string. For example:</para>
344 $ <userinput>dnssec-signzone -E '' -S example.net</userinput>
347 <command>dnssec-signzone</command> to run as if it were compiled
348 without the --with-pkcs11 option.</para>
351 <title>Running named with automatic zone re-signing</title>
353 <command>named</command> to dynamically re-sign zones using HSM
354 keys, and/or to to sign new records inserted via nsupdate, then
355 named must have access to the HSM PIN. This can be accomplished
356 by placing the PIN into the openssl.cnf file (in the above
358 <filename>/opt/pkcs11/usr/ssl/openssl.cnf</filename>).</para>
359 <para>The location of the openssl.cnf file can be overridden by
360 setting the OPENSSL_CONF environment variable before running
362 <para>Sample openssl.cnf:</para>
364 openssl_conf = openssl_def
366 engines = engine_section
368 pkcs11 = pkcs11_section
370 PIN = <replaceable><PLACE PIN HERE></replaceable>
372 <para>This will also allow the dnssec-* tools to access the HSM
373 without PIN entry. (The pkcs11-* tools access the HSM directly,
374 not via OpenSSL, so a PIN will still be required to use
377 If the PIN is not known, I believe the first time named needs the
378 PIN to open a key, it'll ask you to type in the PIN, which will be
379 a problem because it probably won't be running on a terminal
382 <para>Placing the HSM's PIN in a text file in
383 this manner may reduce the security advantage of using an
384 HSM. Be sure this is what you want to do before configuring
385 OpenSSL in this way.</para>
388 <!-- TODO: what is alternative then for named dynamic re-signing? -->
389 <!-- TODO: what happens if PIN is not known? named will log about it? -->