contrib/bind9/doc/arm/pkcs11.xml

   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 "&#8212;">]>
   4 <!--
   5  - Copyright (C) 2010  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: pkcs11.xml,v 1.3 2010-02-06 07:42:02 marka Exp $ -->
  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 &mdash; 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.7.0
  72     release, in the form of a context diff against the latest OpenSSL.
  73     </para>
  74     <note>
  75       The latest OpenSSL version at the time of the BIND release
  76       is 0.9.8l.
  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>
  80     <para>
  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
  84     library.</para>
  85     <para>Obtain OpenSSL 0.9.8l:</para>
  86     <screen>
  87 $ <userinput>wget <ulink>http://www.openssl.org/source/openssl-0.9.8l.tar.gz</ulink></userinput>
  88 </screen>
  89     <para>Extract the tarball:</para>
  90     <screen>
  91 $ <userinput>tar zxf openssl-0.9.8l.tar.gz</userinput>
  92 </screen>
  93     <para>Apply the patch from the BIND 9 release:</para>
  94     <screen>
  95 $ <userinput>patch -p1 -d openssl-0.9.8l \
  96             &lt; bind-9.7.0/bin/pkcs11/openssl-0.9.8l-patch</userinput>
  97 </screen>
  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>
 106     <sect3>
 107       <!-- Example 1 -->
 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>
 117       <screen>
 118 $ <userinput>cp pkcs11.GCC4.0.2.so.4.05 /opt/pkcs11/usr/lib/libpkcs11.so</userinput>
 119 </screen>
 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>
 126       <screen>
 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>
 132 </screen>
 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>
 137     </sect3>
 138     <sect3>
 139       <!-- Example 2 -->
 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
 146       AMD64 system.</para>
 147       <screen>
 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>
 153 </screen>
 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
 163       selected:</para>
 164       <screen>
 165         (pkcs11) PKCS #11 engine support (sign only)
 166 </screen>
 167       <para>Or:</para>
 168       <screen>
 169         (pkcs11) PKCS #11 engine support (crypto accelerator)
 170 </screen>
 171       <para>Next, run
 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>
 180     </sect3>
 181   </sect2>
 182   <sect2>
 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>
 186     <sect3>
 187       <!-- Example 3 -->
 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>
 195       <screen>
 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>
 200 </screen>
 201     </sect3>
 202     <sect3>
 203       <!-- Example 4 -->
 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>
 207       <screen>
 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>
 212 </screen>
 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
 218       Configure).</para>
 219     </sect3>
 220     <para>After configuring, run
 221     "<command>make</command>",
 222     "<command>make test</command>" and
 223     "<command>make install</command>".</para>
 224   </sect2>
 225   <sect2>
 226     <title>PKCS #11 Tools</title>
 227     <para>BIND 9 includes a minimal set of tools to operate the
 228     HSM, including
 229     <command>pkcs11-keygen</command> to generate a new key pair
 230     within the HSM,
 231     <command>pkcs11-list</command> to list objects currently
 232     available, and
 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
 240     provider.)</para>
 241   </sect2>
 242   <sect2>
 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>
 246     <screen>
 247 $ <userinput>export LD_LIBRARY_PATH=/opt/pkcs11/usr/lib:${LD_LIBRARY_PATH}</userinput>
 248 </screen>
 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>,
 254     use:</para>
 255     <screen>
 256 $ <userinput>export KEYPER_LIBRARY_PATH=/opt/Keyper/PKCS11Provider</userinput>
 257 </screen>
 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
 271     "sample-ksk":</para>
 272     <screen>
 273 $ <userinput>pkcs11-keygen -b 2048 -l sample-ksk</userinput>
 274 </screen>
 275     <para>To confirm that the key exists:</para>
 276     <screen>
 277 $ <userinput>pkcs11-list</userinput>
 278 Enter PIN:
 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]
 281 </screen>
 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>
 286     <screen>
 287 $ <userinput>dnssec-keyfromlabel -l sample-ksk -f KSK example.net</userinput>
 288 </screen>
 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
 294     private key.</para>
 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>
 299     <screen>
 300 $ <userinput>pkcs11-keygen -b 1024 -l sample-zsk</userinput>
 301 $ <userinput>dnssec-keyfromlabel -l sample-zsk example.net</userinput>
 302 </screen>
 303     <para>Alternatively, you may prefer to generate a conventional
 304     on-disk key, using dnssec-keygen:</para>
 305     <screen>
 306 $ <userinput>dnssec-keygen example.net</userinput>
 307 </screen>
 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
 315     option to
 316     <command>dnssec-signzone</command>, it will be necessary to add
 317     the contents of both
 318     <filename>K*.key</filename> files to the zone master file before
 319     signing it.)</para>
 320     <screen>
 321 $ <userinput>dnssec-signzone -S example.net</userinput>
 322 Enter PIN:
 323 Verifying the zone using the following algorithms:
 324 NSEC3RSASHA1.
 325 Zone signing complete:
 326 Algorithm: NSEC3RSASHA1: ZSKs: 1, KSKs: 1 active, 0 revoked, 0 stand-by
 327 example.net.signed
 328 </screen>
 329   </sect2>
 330   <sect2>
 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     &lt;engine&gt;" 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
 339     engine.</para>
 340     <para>If you wish to disable use of the "pkcs11" engine &mdash;
 341     for troubleshooting purposes, or because the HSM is unavailable
 342     &mdash; set the engine to the empty string. For example:</para>
 343     <screen>
 344 $ <userinput>dnssec-signzone -E '' -S example.net</userinput>
 345 </screen>
 346     <para>This causes
 347     <command>dnssec-signzone</command> to run as if it were compiled
 348     without the --with-pkcs11 option.</para>
 349   </sect2>
 350   <sect2>
 351     <title>Running named with automatic zone re-signing</title>
 352     <para>If you want
 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
 357     examples,
 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
 361     named.</para>
 362     <para>Sample openssl.cnf:</para>
 363     <programlisting>
 364         openssl_conf = openssl_def
 365         [ openssl_def ]
 366         engines = engine_section
 367         [ engine_section ]
 368         pkcs11 = pkcs11_section
 369         [ pkcs11_section ]
 370         PIN = <replaceable>&lt;PLACE PIN HERE&gt;</replaceable>
 371 </programlisting>
 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
 375     them.)</para>
 376 <!--
 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
 380 -->
 381     <warning>
 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>
 386     </warning>
 387   </sect2>
 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? -->
 390 </sect1>