diff options
Diffstat (limited to 'doc/arm/pkcs11.xml')
| -rw-r--r-- | doc/arm/pkcs11.xml | 152 |
1 files changed, 74 insertions, 78 deletions
diff --git a/doc/arm/pkcs11.xml b/doc/arm/pkcs11.xml index d5a841295a5a3..86a7305e36b07 100644 --- a/doc/arm/pkcs11.xml +++ b/doc/arm/pkcs11.xml @@ -1,8 +1,5 @@ -<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" - "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" - [<!ENTITY mdash "—">]> <!-- - - Copyright (C) 2010, 2012-2014 Internet Systems Consortium, Inc. ("ISC") + - Copyright (C) 2010, 2012-2016 Internet Systems Consortium, Inc. ("ISC") - - Permission to use, copy, modify, and/or distribute this software for any - purpose with or without fee is hereby granted, provided that the above @@ -17,10 +14,9 @@ - PERFORMANCE OF THIS SOFTWARE. --> -<!-- $Id: pkcs11.xml,v 1.7 2012/01/16 22:50:12 each Exp $ --> +<!-- Converted by db4-upgrade version 1.0 --> +<section xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="pkcs11"><info><title>PKCS #11 (Cryptoki) support</title></info> -<sect1 id="pkcs11"> - <title>PKCS #11 (Cryptoki) support</title> <para>PKCS #11 (Public Key Cryptography Standard #11) defines a platform- independent API for the control of hardware security modules (HSMs) and other cryptographic support devices.</para> @@ -28,8 +24,8 @@ cryptographic acceleration board, tested under Solaris x86, and the AEP Keyper network-attached key storage device, tested with Debian Linux, Solaris x86 and Windows Server 2003.</para> - <sect2> - <title>Prerequisites</title> + <section><info><title>Prerequisites</title></info> + <para>See the HSM vendor documentation for information about installing, initializing, testing and troubleshooting the HSM.</para> @@ -60,7 +56,7 @@ function primarily as secure key storage devices, but lack hardware acceleration. These devices are highly secure, but are not necessarily any faster at cryptography than the - system CPU — often, they are slower. It is therefore + system CPU — often, they are slower. It is therefore most efficient to use them only for those cryptographic functions that require access to the secured private key, such as zone signing, and to use the system CPU for all @@ -71,15 +67,15 @@ <para> The modified OpenSSL code is included in the BIND 9 release, in the form of a context diff against the latest versions of - OpenSSL. OpenSSL 0.9.8, 1.0.0, and 1.0.1 are supported; there are - separate diffs for each version. In the examples to follow, - we use OpenSSL 0.9.8, but the same methods work with OpenSSL - 1.0.0 and 1.0.1. + OpenSSL. OpenSSL 0.9.8, 1.0.0, 1.0.1 and 1.0.2 are supported; + there are separate diffs for each version. In the examples to + follow, we use OpenSSL 0.9.8, but the same methods work with + OpenSSL 1.0.0 through 1.0.2. </para> <note> - The latest OpenSSL versions at the time of the BIND release - are 0.9.8y, 1.0.0k and 1.0.1e. - ISC will provide an updated patch as new versions of OpenSSL + The OpenSSL patches as of this writing (January 2016) + support versions 0.9.8zh, 1.0.0t, 1.0.1q and 1.0.2f. + ISC will provide updated patches as new versions of OpenSSL are released. The version number in the following examples is expected to change.</note> <para> @@ -89,7 +85,7 @@ library.</para> <para>Obtain OpenSSL 0.9.8s:</para> <screen> -$ <userinput>wget <ulink>http://www.openssl.org/source/openssl-0.9.8s.tar.gz</ulink></userinput> +$ <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> </screen> <para>Extract the tarball:</para> <screen> @@ -108,9 +104,9 @@ $ <userinput>patch -p1 -d openssl-0.9.8s \ elsewhere on the system. In the following examples, we choose to install into "/opt/pkcs11/usr". We will use this location when we configure BIND 9.</para> - <sect3> + <section><info><title>Building OpenSSL for the AEP Keyper on Linux</title></info> <!-- Example 1 --> - <title>Building OpenSSL for the AEP Keyper on Linux</title> + <para>The AEP Keyper is a highly secure key storage device, but does not provide hardware cryptographic acceleration. It can carry out cryptographic operations, but it is probably @@ -139,10 +135,10 @@ $ <userinput>./Configure linux-generic32 -m32 -pthread \ and "<command>make test</command>". If "<command>make test</command>" fails with "pthread_atfork() not found", you forgot to add the -pthread above.</para> - </sect3> - <sect3> + </section> + <section><info><title>Building OpenSSL for the SCA 6000 on Solaris</title></info> <!-- Example 2 --> - <title>Building OpenSSL for the SCA 6000 on Solaris</title> + <para>The SCA-6000 PKCS #11 provider is installed as a system library, libpkcs11. It is a true crypto accelerator, up to 4 times faster than any CPU, so the flavor shall be @@ -158,13 +154,13 @@ $ <userinput>./Configure solaris64-x86_64-cc \ </screen> <para>(For a 32-bit build, use "solaris-x86-cc" and /usr/lib/libpkcs11.so.)</para> - <para>After configuring, run - <command>make</command> and + <para>After configuring, run + <command>make</command> and <command>make test</command>.</para> - </sect3> - <sect3> + </section> + <section><info><title>Building OpenSSL for SoftHSM</title></info> <!-- Example 3 --> - <title>Building OpenSSL for SoftHSM</title> + <para>SoftHSM is a software library provided by the OpenDNSSEC project (http://www.opendnssec.org) which provides a PKCS#11 interface to a virtual HSM, implemented in the form of encrypted @@ -183,7 +179,7 @@ $ <userinput> configure --prefix=/opt/pkcs11/usr </userinput> $ <userinput> make </userinput> $ <userinput> make install </userinput> $ <userinput> export SOFTHSM_CONF=/opt/pkcs11/softhsm.conf </userinput> -$ <userinput> echo "0:/opt/pkcs11/softhsm.db" > $SOFTHSM_CONF </userinput> +$ <userinput> echo "0:/opt/pkcs11/softhsm.db" > $SOFTHSM_CONF </userinput> $ <userinput> /opt/pkcs11/usr/bin/softhsm --init-token 0 --slot 0 --label softhsm </userinput> </screen> <para>SoftHSM can perform all cryptographic operations, but @@ -199,7 +195,7 @@ $ <userinput>./Configure linux-x86_64 -pthread \ </screen> <para>After configuring, run "<command>make</command>" and "<command>make test</command>".</para> - </sect3> + </section> <para>Once you have built OpenSSL, run "<command>apps/openssl engine pkcs11</command>" to confirm that PKCS #11 support was compiled in correctly. The output @@ -219,16 +215,16 @@ $ <userinput>./Configure linux-x86_64 -pthread \ <quote><literal>[ available ]</literal></quote>.</para> <para>If the output is correct, run "<command>make install</command>" which will install the - modified OpenSSL suite to + modified OpenSSL suite to <filename>/opt/pkcs11/usr</filename>.</para> - </sect2> - <sect2> - <title>Building BIND 9 with PKCS#11</title> + </section> + <section><info><title>Building BIND 9 with PKCS#11</title></info> + <para>When building BIND 9, the location of the custom-built OpenSSL library must be specified via configure.</para> - <sect3> + <section><info><title>Configuring BIND 9 for Linux with the AEP Keyper</title></info> <!-- Example 4 --> - <title>Configuring BIND 9 for Linux with the AEP Keyper</title> + <para>To link with the PKCS #11 provider, threads must be enabled in the BIND 9 build.</para> <para>The PKCS #11 library for the AEP Keyper is currently @@ -241,10 +237,10 @@ $ <userinput>./configure CC="gcc -m32" --enable-threads \ --with-openssl=/opt/pkcs11/usr \ --with-pkcs11=/opt/pkcs11/usr/lib/libpkcs11.so</userinput> </screen> - </sect3> - <sect3> + </section> + <section><info><title>Configuring BIND 9 for Solaris with the SCA 6000</title></info> <!-- Example 5 --> - <title>Configuring BIND 9 for Solaris with the SCA 6000</title> + <para>To link with the PKCS #11 provider, threads must be enabled in the BIND 9 build.</para> <screen> @@ -259,32 +255,32 @@ $ <userinput>./configure CC="cc -xarch=amd64" --enable-threads \ incorrectly specified the path to OpenSSL (it should be the same as the --prefix argument to the OpenSSL Configure).</para> - </sect3> - <sect3> + </section> + <section><info><title>Configuring BIND 9 for SoftHSM</title></info> <!-- Example 6 --> - <title>Configuring BIND 9 for SoftHSM</title> + <screen> $ <userinput>cd ../bind9</userinput> $ <userinput>./configure --enable-threads \ --with-openssl=/opt/pkcs11/usr \ --with-pkcs11=/opt/pkcs11/usr/lib/libpkcs11.so</userinput> </screen> - </sect3> + </section> <para>After configuring, run "<command>make</command>", "<command>make test</command>" and "<command>make install</command>".</para> <para>(Note: If "make test" fails in the "pkcs11" system test, you may have forgotten to set the SOFTHSM_CONF environment variable.)</para> - </sect2> - <sect2> - <title>PKCS #11 Tools</title> + </section> + <section><info><title>PKCS #11 Tools</title></info> + <para>BIND 9 includes a minimal set of tools to operate the - HSM, including + HSM, including <command>pkcs11-keygen</command> to generate a new key pair - within the HSM, + within the HSM, <command>pkcs11-list</command> to list objects currently - available, and + available, and <command>pkcs11-destroy</command> to remove objects.</para> <para>In UNIX/Linux builds, these tools are built only if BIND 9 is configured with the --with-pkcs11 option. (NOTE: If @@ -293,9 +289,9 @@ $ <userinput>./configure --enable-threads \ provider will be left undefined. Use the -m option or the PKCS11_PROVIDER environment variable to specify the path to the provider.)</para> - </sect2> - <sect2> - <title>Using the HSM</title> + </section> + <section><info><title>Using the HSM</title></info> + <para>First, we must set up the runtime environment so the OpenSSL and PKCS #11 libraries can be loaded:</para> <screen> @@ -304,7 +300,7 @@ $ <userinput>export LD_LIBRARY_PATH=/opt/pkcs11/usr/lib:${LD_LIBRARY_PATH}</user <para>When operating an AEP Keyper, it is also necessary to specify the location of the "machine" file, which stores information about the Keyper for use by PKCS #11 provider - library. If the machine file is in + library. If the machine file is in <filename>/opt/Keyper/PKCS11Provider/machine</filename>, use:</para> <screen> @@ -312,14 +308,14 @@ $ <userinput>export KEYPER_LIBRARY_PATH=/opt/Keyper/PKCS11Provider</userinput> </screen> <!-- TODO: why not defined at compile time? --> <para>These environment variables must be set whenever running - any tool that uses the HSM, including - <command>pkcs11-keygen</command>, - <command>pkcs11-list</command>, - <command>pkcs11-destroy</command>, - <command>dnssec-keyfromlabel</command>, - <command>dnssec-signzone</command>, + any tool that uses the HSM, including + <command>pkcs11-keygen</command>, + <command>pkcs11-list</command>, + <command>pkcs11-destroy</command>, + <command>dnssec-keyfromlabel</command>, + <command>dnssec-signzone</command>, <command>dnssec-keygen</command>(which will use the HSM for - random number generation), and + random number generation), and <command>named</command>.</para> <para>We can now create and use keys in the HSM. In this case, we will create a 2048 bit key and give it the label @@ -367,9 +363,9 @@ $ <userinput>dnssec-keygen example.net</userinput> rolled more frequently, if you wish, to compensate for a reduction in key security.</para> <para>Now you can sign the zone. (Note: If not using the -S - option to + option to <command>dnssec-signzone</command>, it will be necessary to add - the contents of both + the contents of both <filename>K*.key</filename> files to the zone master file before signing it.)</para> <screen> @@ -381,35 +377,35 @@ Zone signing complete: Algorithm: NSEC3RSASHA1: ZSKs: 1, KSKs: 1 active, 0 revoked, 0 stand-by example.net.signed </screen> - </sect2> - <sect2> - <title>Specifying the engine on the command line</title> - <para>The OpenSSL engine can be specified in - <command>named</command> and all of the BIND + </section> + <section><info><title>Specifying the engine on the command line</title></info> + + <para>The OpenSSL engine can be specified in + <command>named</command> and all of the BIND <command>dnssec-*</command> tools by using the "-E <engine>" command line option. If BIND 9 is built with the --with-pkcs11 option, this option defaults to "pkcs11". Specifying the engine will generally not be necessary unless for some reason you wish to use a different OpenSSL engine.</para> - <para>If you wish to disable use of the "pkcs11" engine — + <para>If you wish to disable use of the "pkcs11" engine — for troubleshooting purposes, or because the HSM is unavailable - — set the engine to the empty string. For example:</para> + — set the engine to the empty string. For example:</para> <screen> $ <userinput>dnssec-signzone -E '' -S example.net</userinput> </screen> - <para>This causes + <para>This causes <command>dnssec-signzone</command> to run as if it were compiled without the --with-pkcs11 option.</para> - </sect2> - <sect2> - <title>Running named with automatic zone re-signing</title> - <para>If you want + </section> + <section><info><title>Running named with automatic zone re-signing</title></info> + + <para>If you want <command>named</command> to dynamically re-sign zones using HSM keys, and/or to to sign new records inserted via nsupdate, then named must have access to the HSM PIN. This can be accomplished by placing the PIN into the openssl.cnf file (in the above - examples, + examples, <filename>/opt/pkcs11/usr/ssl/openssl.cnf</filename>).</para> <para>The location of the openssl.cnf file can be overridden by setting the OPENSSL_CONF environment variable before running @@ -428,7 +424,7 @@ $ <userinput>dnssec-signzone -E '' -S example.net</userinput> without PIN entry. (The pkcs11-* tools access the HSM directly, not via OpenSSL, so a PIN will still be required to use them.)</para> -<!-- +<!-- If the PIN is not known, I believe the first time named needs the PIN to open a key, it'll ask you to type in the PIN, which will be a problem because it probably won't be running on a terminal @@ -439,7 +435,7 @@ a problem because it probably won't be running on a terminal HSM. Be sure this is what you want to do before configuring OpenSSL in this way.</para> </warning> - </sect2> + </section> <!-- TODO: what is alternative then for named dynamic re-signing? --> <!-- TODO: what happens if PIN is not known? named will log about it? --> -</sect1> +</section> |