contrib/bind9/doc/arm/pkcs11.xml

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