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 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--> 19 20<!-- $Id$ --> 21 22<sect1 id="pkcs11"> 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> 31 <sect2> 32 <title>Prerequisites</title> 33 <para>See the HSM vendor documentation for information about 34 installing, initializing, testing and troubleshooting the 35 HSM.</para> 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 41 reference.</para> 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 50 hardware:</para> 51 <itemizedlist> 52 <listitem> 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> 57 </listitem> 58 <listitem> 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> 69 </listitem> 70 </itemizedlist> 71 <para>The modified OpenSSL code is included in the BIND 9 release, 72 in the form of a context diff against the latest verions of 73 OpenSSL. OpenSSL 0.9.8 and 1.0.0 are both supported; there are 74 separate diffs for each version. In the examples to follow, 75 we use OpenSSL 0.9.8, but the same methods work with OpenSSL 1.0.0. 76 </para> 77 <note> 78 The latest OpenSSL versions at the time of the BIND release 79 are 0.9.8s and 1.0.0f. 80 ISC will provide an updated patch as new versions of OpenSSL 81 are released. The version number in the following examples 82 is expected to change.</note> 83 <para> 84 Before building BIND 9 with PKCS #11 support, it will be 85 necessary to build OpenSSL with this patch in place and inform 86 it of the path to the HSM-specific PKCS #11 provider 87 library.</para> 88 <para>Obtain OpenSSL 0.9.8s:</para> 89 <screen> 90$ <userinput>wget <ulink>http://www.openssl.org/source/openssl-0.9.8s.tar.gz</ulink></userinput> 91</screen> 92 <para>Extract the tarball:</para> 93 <screen> 94$ <userinput>tar zxf openssl-0.9.8s.tar.gz</userinput> 95</screen> 96 <para>Apply the patch from the BIND 9 release:</para> 97 <screen> 98$ <userinput>patch -p1 -d openssl-0.9.8s \ 99 < bind9/bin/pkcs11/openssl-0.9.8s-patch</userinput> 100</screen> 101 <note>(Note that the patch file may not be compatible with the 102 "patch" utility on all operating systems. You may need to 103 install GNU patch.)</note> 104 <para>When building OpenSSL, place it in a non-standard 105 location so that it does not interfere with OpenSSL libraries 106 elsewhere on the system. In the following examples, we choose 107 to install into "/opt/pkcs11/usr". We will use this location 108 when we configure BIND 9.</para> 109 <sect3> 110 <!-- Example 1 --> 111 <title>Building OpenSSL for the AEP Keyper on Linux</title> 112 <para>The AEP Keyper is a highly secure key storage device, 113 but does not provide hardware cryptographic acceleration. It 114 can carry out cryptographic operations, but it is probably 115 slower than your system's CPU. Therefore, we choose the 116 'sign-only' flavor when building OpenSSL.</para> 117 <para>The Keyper-specific PKCS #11 provider library is 118 delivered with the Keyper software. In this example, we place 119 it /opt/pkcs11/usr/lib:</para> 120 <screen> 121$ <userinput>cp pkcs11.GCC4.0.2.so.4.05 /opt/pkcs11/usr/lib/libpkcs11.so</userinput> 122</screen> 123 <para>This library is only available for Linux as a 32-bit 124 binary. If we are compiling on a 64-bit Linux system, it is 125 necessary to force a 32-bit build, by specifying -m32 in the 126 build options.</para> 127 <para>Finally, the Keyper library requires threads, so we 128 must specify -pthread.</para> 129 <screen> 130$ <userinput>cd openssl-0.9.8s</userinput> 131$ <userinput>/Configure linux-generic32 -m32 -pthread \ 132 --pk11-libname=/opt/pkcs11/usr/lib/libpkcs11.so \ 133 --pk11-flavor=sign-only \ 134 --prefix=/opt/pkcs11/usr</userinput> 135</screen> 136 <para>After configuring, run "<command>make</command>" 137 and "<command>make test</command>". If "<command>make 138 test</command>" fails with "pthread_atfork() not found", you forgot to 139 add the -pthread above.</para> 140 </sect3> 141 <sect3> 142 <!-- Example 2 --> 143 <title>Building OpenSSL for the SCA 6000 on Solaris</title> 144 <para>The SCA-6000 PKCS #11 provider is installed as a system 145 library, libpkcs11. It is a true crypto accelerator, up to 4 146 times faster than any CPU, so the flavor shall be 147 'crypto-accelerator'.</para> 148 <para>In this example, we are building on Solaris x86 on an 149 AMD64 system.</para> 150 <screen> 151$ <userinput>cd openssl-0.9.8s</userinput> 152$ <userinput>/Configure solaris64-x86_64-cc \ 153 --pk11-libname=/usr/lib/64/libpkcs11.so \ 154 --pk11-flavor=crypto-accelerator \ 155 --prefix=/opt/pkcs11/usr</userinput> 156</screen> 157 <para>(For a 32-bit build, use "solaris-x86-cc" and 158 /usr/lib/libpkcs11.so.)</para> 159 <para>After configuring, run 160 <command>make</command> and 161 <command>make test</command>.</para> 162 </sect3> 163 <sect3> 164 <!-- Example 3 --> 165 <title>Building OpenSSL for SoftHSM</title> 166 <para>SoftHSM is a software library provided by the OpenDNSSEC 167 project (http://www.opendnssec.org) which provides a PKCS#11 168 interface to a virtual HSM, implemented in the form of encrypted 169 data on the local filesystem. It uses the Botan library for 170 encryption and SQLite3 for data storage. Though less secure 171 than a true HSM, it can provide more secure key storage than 172 traditional key files, and can allow you to experiment with 173 PKCS#11 when an HSM is not available.</para> 174 <para>The SoftHSM cryptographic store must be installed and 175 initialized before using it with OpenSSL, and the SOFTHSM_CONF 176 environment variable must always point to the SoftHSM configuration 177 file:</para> 178 <screen> 179$ <userinput> cd softhsm-1.3.0 </userinput> 180$ <userinput> configure --prefix=/opt/pkcs11/usr </userinput> 181$ <userinput> make </userinput> 182$ <userinput> make install </userinput> 183$ <userinput> export SOFTHSM_CONF=/opt/pkcs11/softhsm.conf </userinput> 184$ <userinput> echo "0:/opt/pkcs11/softhsm.db" > $SOFTHSM_CONF </userinput> 185$ <userinput> /opt/pkcs11/usr/bin/softhsm --init-token 0 --slot 0 --label softhsm </userinput> 186</screen> 187 <para>SoftHSM can perform all cryptographic operations, but 188 since it only uses your system CPU, there is no need to use it 189 for anything but signing. Therefore, we choose the 'sign-only' 190 flavor when building OpenSSL.</para> 191 <screen> 192$ <userinput>cd openssl-0.9.8s</userinput> 193$ <userinput>/Configure linux-x86_64 -pthread \ 194 --pk11-libname=/opt/pkcs11/usr/lib/libpkcs11.so \ 195 --pk11-flavor=sign-only \ 196 --prefix=/opt/pkcs11/usr</userinput> 197</screen> 198 <para>After configuring, run "<command>make</command>" 199 and "<command>make test</command>".</para> 200 </sect3> 201 <para>Once you have built OpenSSL, run 202 "<command>apps/openssl engine pkcs11</command>" to confirm 203 that PKCS #11 support was compiled in correctly. The output 204 should be one of the following lines, depending on the flavor 205 selected:</para> 206 <screen> 207 (pkcs11) PKCS #11 engine support (sign only) 208</screen> 209 <para>Or:</para> 210 <screen> 211 (pkcs11) PKCS #11 engine support (crypto accelerator) 212</screen> 213 <para>Next, run 214 "<command>apps/openssl engine pkcs11 -t</command>". This will 215 attempt to initialize the PKCS #11 engine. If it is able to 216 do so successfully, it will report 217 <quote><literal>[ available ]</literal></quote>.</para> 218 <para>If the output is correct, run 219 "<command>make install</command>" which will install the 220 modified OpenSSL suite to 221 <filename>/opt/pkcs11/usr</filename>.</para> 222 </sect2> 223 <sect2> 224 <title>Building BIND 9 with PKCS#11</title> 225 <para>When building BIND 9, the location of the custom-built 226 OpenSSL library must be specified via configure.</para> 227 <sect3> 228 <!-- Example 4 --> 229 <title>Configuring BIND 9 for Linux with the AEP Keyper</title> 230 <para>To link with the PKCS #11 provider, threads must be 231 enabled in the BIND 9 build.</para> 232 <para>The PKCS #11 library for the AEP Keyper is currently 233 only available as a 32-bit binary. If we are building on a 234 64-bit host, we must force a 32-bit build by adding "-m32" to 235 the CC options on the "configure" command line.</para> 236 <screen> 237$ <userinput>cd /bind9</userinput> 238$ <userinput>/configure CC="gcc -m32" --enable-threads \ 239 --with-openssl=/opt/pkcs11/usr \ 240 --with-pkcs11=/opt/pkcs11/usr/lib/libpkcs11.so</userinput> 241</screen> 242 </sect3> 243 <sect3> 244 <!-- Example 5 --> 245 <title>Configuring BIND 9 for Solaris with the SCA 6000</title> 246 <para>To link with the PKCS #11 provider, threads must be 247 enabled in the BIND 9 build.</para> 248 <screen> 249$ <userinput>cd /bind9</userinput> 250$ <userinput>/configure CC="cc -xarch=amd64" --enable-threads \ 251 --with-openssl=/opt/pkcs11/usr \ 252 --with-pkcs11=/usr/lib/64/libpkcs11.so</userinput> 253</screen> 254 <para>(For a 32-bit build, omit CC="cc -xarch=amd64".)</para> 255 <para>If configure complains about OpenSSL not working, you 256 may have a 32/64-bit architecture mismatch. Or, you may have 257 incorrectly specified the path to OpenSSL (it should be the 258 same as the --prefix argument to the OpenSSL 259 Configure).</para> 260 </sect3> 261 <sect3> 262 <!-- Example 6 --> 263 <title>Configuring BIND 9 for SoftHSM</title> 264 <screen> 265$ <userinput>cd /bind9</userinput> 266$ <userinput>/configure --enable-threads \ 267 --with-openssl=/opt/pkcs11/usr \ 268 --with-pkcs11=/opt/pkcs11/usr/lib/libpkcs11.so</userinput> 269</screen> 270 </sect3> 271 <para>After configuring, run 272 "<command>make</command>", 273 "<command>make test</command>" and 274 "<command>make install</command>".</para> 275 <para>(Note: If "make test" fails in the "pkcs11" system test, you may 276 have forgotten to set the SOFTHSM_CONF environment variable.)</para> 277 </sect2> 278 <sect2> 279 <title>PKCS #11 Tools</title> 280 <para>BIND 9 includes a minimal set of tools to operate the 281 HSM, including 282 <command>pkcs11-keygen</command> to generate a new key pair 283 within the HSM, 284 <command>pkcs11-list</command> to list objects currently 285 available, and 286 <command>pkcs11-destroy</command> to remove objects.</para> 287 <para>In UNIX/Linux builds, these tools are built only if BIND 288 9 is configured with the --with-pkcs11 option. (NOTE: If 289 --with-pkcs11 is set to "yes", rather than to the path of the 290 PKCS #11 provider, then the tools will be built but the 291 provider will be left undefined. Use the -m option or the 292 PKCS11_PROVIDER environment variable to specify the path to the 293 provider.)</para> 294 </sect2> 295 <sect2> 296 <title>Using the HSM</title> 297 <para>First, we must set up the runtime environment so the 298 OpenSSL and PKCS #11 libraries can be loaded:</para> 299 <screen> 300$ <userinput>export LD_LIBRARY_PATH=/opt/pkcs11/usr/lib:${LD_LIBRARY_PATH}</userinput> 301</screen> 302 <para>When operating an AEP Keyper, it is also necessary to 303 specify the location of the "machine" file, which stores 304 information about the Keyper for use by PKCS #11 provider 305 library. If the machine file is in 306 <filename>/opt/Keyper/PKCS11Provider/machine</filename>, 307 use:</para> 308 <screen> 309$ <userinput>export KEYPER_LIBRARY_PATH=/opt/Keyper/PKCS11Provider</userinput> 310</screen> 311 <!-- TODO: why not defined at compile time? --> 312 <para>These environment variables must be set whenever running 313 any tool that uses the HSM, including 314 <command>pkcs11-keygen</command>, 315 <command>pkcs11-list</command>, 316 <command>pkcs11-destroy</command>, 317 <command>dnssec-keyfromlabel</command>, 318 <command>dnssec-signzone</command>, 319 <command>dnssec-keygen</command>(which will use the HSM for 320 random number generation), and 321 <command>named</command>.</para> 322 <para>We can now create and use keys in the HSM. In this case, 323 we will create a 2048 bit key and give it the label 324 "sample-ksk":</para> 325 <screen> 326$ <userinput>pkcs11-keygen -b 2048 -l sample-ksk</userinput> 327</screen> 328 <para>To confirm that the key exists:</para> 329 <screen> 330$ <userinput>pkcs11-list</userinput> 331Enter PIN: 332object[0]: handle 2147483658 class 3 label[8] 'sample-ksk' id[0] 333object[1]: handle 2147483657 class 2 label[8] 'sample-ksk' id[0] 334</screen> 335 <para>Before using this key to sign a zone, we must create a 336 pair of BIND 9 key files. The "dnssec-keyfromlabel" utility 337 does this. In this case, we will be using the HSM key 338 "sample-ksk" as the key-signing key for "example.net":</para> 339 <screen> 340$ <userinput>dnssec-keyfromlabel -l sample-ksk -f KSK example.net</userinput> 341</screen> 342 <para>The resulting K*.key and K*.private files can now be used 343 to sign the zone. Unlike normal K* files, which contain both 344 public and private key data, these files will contain only the 345 public key data, plus an identifier for the private key which 346 remains stored within the HSM. The HSM handles signing with the 347 private key.</para> 348 <para>If you wish to generate a second key in the HSM for use 349 as a zone-signing key, follow the same procedure above, using a 350 different keylabel, a smaller key size, and omitting "-f KSK" 351 from the dnssec-keyfromlabel arguments:</para> 352 <screen> 353$ <userinput>pkcs11-keygen -b 1024 -l sample-zsk</userinput> 354$ <userinput>dnssec-keyfromlabel -l sample-zsk example.net</userinput> 355</screen> 356 <para>Alternatively, you may prefer to generate a conventional 357 on-disk key, using dnssec-keygen:</para> 358 <screen> 359$ <userinput>dnssec-keygen example.net</userinput> 360</screen> 361 <para>This provides less security than an HSM key, but since 362 HSMs can be slow or cumbersome to use for security reasons, it 363 may be more efficient to reserve HSM keys for use in the less 364 frequent key-signing operation. The zone-signing key can be 365 rolled more frequently, if you wish, to compensate for a 366 reduction in key security.</para> 367 <para>Now you can sign the zone. (Note: If not using the -S 368 option to 369 <command>dnssec-signzone</command>, it will be necessary to add 370 the contents of both 371 <filename>K*.key</filename> files to the zone master file before 372 signing it.)</para> 373 <screen> 374$ <userinput>dnssec-signzone -S example.net</userinput> 375Enter PIN: 376Verifying the zone using the following algorithms: 377NSEC3RSASHA1. 378Zone signing complete: 379Algorithm: NSEC3RSASHA1: ZSKs: 1, KSKs: 1 active, 0 revoked, 0 stand-by 380example.net.signed 381</screen> 382 </sect2> 383 <sect2> 384 <title>Specifying the engine on the command line</title> 385 <para>The OpenSSL engine can be specified in 386 <command>named</command> and all of the BIND 387 <command>dnssec-*</command> tools by using the "-E 388 <engine>" command line option. If BIND 9 is built with 389 the --with-pkcs11 option, this option defaults to "pkcs11". 390 Specifying the engine will generally not be necessary unless 391 for some reason you wish to use a different OpenSSL 392 engine.</para> 393 <para>If you wish to disable use of the "pkcs11" engine — 394 for troubleshooting purposes, or because the HSM is unavailable 395 — set the engine to the empty string. For example:</para> 396 <screen> 397$ <userinput>dnssec-signzone -E '' -S example.net</userinput> 398</screen> 399 <para>This causes 400 <command>dnssec-signzone</command> to run as if it were compiled 401 without the --with-pkcs11 option.</para> 402 </sect2> 403 <sect2> 404 <title>Running named with automatic zone re-signing</title> 405 <para>If you want 406 <command>named</command> to dynamically re-sign zones using HSM 407 keys, and/or to to sign new records inserted via nsupdate, then 408 named must have access to the HSM PIN. This can be accomplished 409 by placing the PIN into the openssl.cnf file (in the above 410 examples, 411 <filename>/opt/pkcs11/usr/ssl/openssl.cnf</filename>).</para> 412 <para>The location of the openssl.cnf file can be overridden by 413 setting the OPENSSL_CONF environment variable before running 414 named.</para> 415 <para>Sample openssl.cnf:</para> 416 <programlisting> 417 openssl_conf = openssl_def 418 [ openssl_def ] 419 engines = engine_section 420 [ engine_section ] 421 pkcs11 = pkcs11_section 422 [ pkcs11_section ] 423 PIN = <replaceable><PLACE PIN HERE></replaceable> 424</programlisting> 425 <para>This will also allow the dnssec-* tools to access the HSM 426 without PIN entry. (The pkcs11-* tools access the HSM directly, 427 not via OpenSSL, so a PIN will still be required to use 428 them.)</para> 429<!-- 430If the PIN is not known, I believe the first time named needs the 431PIN to open a key, it'll ask you to type in the PIN, which will be 432a problem because it probably won't be running on a terminal 433--> 434 <warning> 435 <para>Placing the HSM's PIN in a text file in 436 this manner may reduce the security advantage of using an 437 HSM. Be sure this is what you want to do before configuring 438 OpenSSL in this way.</para> 439 </warning> 440 </sect2> 441 <!-- TODO: what is alternative then for named dynamic re-signing? --> 442 <!-- TODO: what happens if PIN is not known? named will log about it? --> 443</sect1> 444