PageRenderTime 56ms CodeModel.GetById 28ms app.highlight 12ms RepoModel.GetById 1ms app.codeStats 1ms

/contrib/bind9/doc/arm/pkcs11.xml

https://bitbucket.org/freebsd/freebsd-head/
XML | 443 lines | 411 code | 2 blank | 30 comment | 0 complexity | 61b95743ce6b089346bb1a5be31fd9e7 MD5 | raw file
  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, 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 &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 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            &lt; 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    &lt;engine&gt;" 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 &mdash;
394    for troubleshooting purposes, or because the HSM is unavailable
395    &mdash; 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>&lt;PLACE PIN HERE&gt;</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>