From 56b72efe825d4190e0e2fdbc07ebb295cac299df Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Dag-Erling=20Sm=C3=B8rgrav?= Date: Mon, 30 Sep 2013 17:23:45 +0000 Subject: Remove BIND. Approved by: re (gjb) --- contrib/bind9/doc/arm/pkcs11.xml | 443 --------------------------------------- 1 file changed, 443 deletions(-) delete mode 100644 contrib/bind9/doc/arm/pkcs11.xml (limited to 'contrib/bind9/doc/arm/pkcs11.xml') diff --git a/contrib/bind9/doc/arm/pkcs11.xml b/contrib/bind9/doc/arm/pkcs11.xml deleted file mode 100644 index 8a0062f4adb4..000000000000 --- a/contrib/bind9/doc/arm/pkcs11.xml +++ /dev/null @@ -1,443 +0,0 @@ -]> - - - - - - PKCS #11 (Cryptoki) support - 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. - BIND 9 is known to work with two HSMs: The Sun SCA 6000 - 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. - - Prerequisites - See the HSM vendor documentation for information about - installing, initializing, testing and troubleshooting the - HSM. - BIND 9 uses OpenSSL for cryptography, but stock OpenSSL - does not yet fully support PKCS #11. However, a PKCS #11 engine - for OpenSSL is available from the OpenSolaris project. It has - been modified by ISC to work with with BIND 9, and to provide - new features such as PIN management and key by - reference. - The patched OpenSSL depends on a "PKCS #11 provider". - This is a shared library object, providing a low-level PKCS #11 - interface to the HSM hardware. It is dynamically loaded by - OpenSSL at runtime. The PKCS #11 provider comes from the HSM - vendor, and is specific to the HSM to be controlled. - There are two "flavors" of PKCS #11 support provided by - the patched OpenSSL, one of which must be chosen at - configuration time. The correct choice depends on the HSM - hardware: - - - Use 'crypto-accelerator' with HSMs that have hardware - cryptographic acceleration features, such as the SCA 6000 - board. This causes OpenSSL to run all supported - cryptographic operations in the HSM. - - - Use 'sign-only' with HSMs that are designed to - 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 - 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 - other computationally-intensive operations. The AEP Keyper - is an example of such a device. - - - The modified OpenSSL code is included in the BIND 9 release, - in the form of a context diff against the latest verions of - OpenSSL. OpenSSL 0.9.8 and 1.0.0 are both 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. - - - The latest OpenSSL versions at the time of the BIND release - are 0.9.8s and 1.0.0f. - ISC will provide an updated patch as new versions of OpenSSL - are released. The version number in the following examples - is expected to change. - - Before building BIND 9 with PKCS #11 support, it will be - necessary to build OpenSSL with this patch in place and inform - it of the path to the HSM-specific PKCS #11 provider - library. - Obtain OpenSSL 0.9.8s: - -$ wget http://www.openssl.org/source/openssl-0.9.8s.tar.gz - - Extract the tarball: - -$ tar zxf openssl-0.9.8s.tar.gz - - Apply the patch from the BIND 9 release: - -$ patch -p1 -d openssl-0.9.8s \ - < bind9/bin/pkcs11/openssl-0.9.8s-patch - - (Note that the patch file may not be compatible with the - "patch" utility on all operating systems. You may need to - install GNU patch.) - When building OpenSSL, place it in a non-standard - location so that it does not interfere with OpenSSL libraries - 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. - - - Building OpenSSL for the AEP Keyper on Linux - 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 - slower than your system's CPU. Therefore, we choose the - 'sign-only' flavor when building OpenSSL. - The Keyper-specific PKCS #11 provider library is - delivered with the Keyper software. In this example, we place - it /opt/pkcs11/usr/lib: - -$ cp pkcs11.GCC4.0.2.so.4.05 /opt/pkcs11/usr/lib/libpkcs11.so - - This library is only available for Linux as a 32-bit - binary. If we are compiling on a 64-bit Linux system, it is - necessary to force a 32-bit build, by specifying -m32 in the - build options. - Finally, the Keyper library requires threads, so we - must specify -pthread. - -$ cd openssl-0.9.8s -$ ./Configure linux-generic32 -m32 -pthread \ - --pk11-libname=/opt/pkcs11/usr/lib/libpkcs11.so \ - --pk11-flavor=sign-only \ - --prefix=/opt/pkcs11/usr - - After configuring, run "make" - and "make test". If "make - test" fails with "pthread_atfork() not found", you forgot to - add the -pthread above. - - - - Building OpenSSL for the SCA 6000 on Solaris - 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 - 'crypto-accelerator'. - In this example, we are building on Solaris x86 on an - AMD64 system. - -$ cd openssl-0.9.8s -$ ./Configure solaris64-x86_64-cc \ - --pk11-libname=/usr/lib/64/libpkcs11.so \ - --pk11-flavor=crypto-accelerator \ - --prefix=/opt/pkcs11/usr - - (For a 32-bit build, use "solaris-x86-cc" and - /usr/lib/libpkcs11.so.) - After configuring, run - make and - make test. - - - - Building OpenSSL for SoftHSM - 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 - data on the local filesystem. It uses the Botan library for - encryption and SQLite3 for data storage. Though less secure - than a true HSM, it can provide more secure key storage than - traditional key files, and can allow you to experiment with - PKCS#11 when an HSM is not available. - The SoftHSM cryptographic store must be installed and - initialized before using it with OpenSSL, and the SOFTHSM_CONF - environment variable must always point to the SoftHSM configuration - file: - -$ cd softhsm-1.3.0 -$ configure --prefix=/opt/pkcs11/usr -$ make -$ make install -$ export SOFTHSM_CONF=/opt/pkcs11/softhsm.conf -$ echo "0:/opt/pkcs11/softhsm.db" > $SOFTHSM_CONF -$ /opt/pkcs11/usr/bin/softhsm --init-token 0 --slot 0 --label softhsm - - SoftHSM can perform all cryptographic operations, but - since it only uses your system CPU, there is no need to use it - for anything but signing. Therefore, we choose the 'sign-only' - flavor when building OpenSSL. - -$ cd openssl-0.9.8s -$ ./Configure linux-x86_64 -pthread \ - --pk11-libname=/opt/pkcs11/usr/lib/libpkcs11.so \ - --pk11-flavor=sign-only \ - --prefix=/opt/pkcs11/usr - - After configuring, run "make" - and "make test". - - Once you have built OpenSSL, run - "apps/openssl engine pkcs11" to confirm - that PKCS #11 support was compiled in correctly. The output - should be one of the following lines, depending on the flavor - selected: - - (pkcs11) PKCS #11 engine support (sign only) - - Or: - - (pkcs11) PKCS #11 engine support (crypto accelerator) - - Next, run - "apps/openssl engine pkcs11 -t". This will - attempt to initialize the PKCS #11 engine. If it is able to - do so successfully, it will report - [ available ]. - If the output is correct, run - "make install" which will install the - modified OpenSSL suite to - /opt/pkcs11/usr. - - - Building BIND 9 with PKCS#11 - When building BIND 9, the location of the custom-built - OpenSSL library must be specified via configure. - - - Configuring BIND 9 for Linux with the AEP Keyper - To link with the PKCS #11 provider, threads must be - enabled in the BIND 9 build. - The PKCS #11 library for the AEP Keyper is currently - only available as a 32-bit binary. If we are building on a - 64-bit host, we must force a 32-bit build by adding "-m32" to - the CC options on the "configure" command line. - -$ cd ../bind9 -$ ./configure CC="gcc -m32" --enable-threads \ - --with-openssl=/opt/pkcs11/usr \ - --with-pkcs11=/opt/pkcs11/usr/lib/libpkcs11.so - - - - - Configuring BIND 9 for Solaris with the SCA 6000 - To link with the PKCS #11 provider, threads must be - enabled in the BIND 9 build. - -$ cd ../bind9 -$ ./configure CC="cc -xarch=amd64" --enable-threads \ - --with-openssl=/opt/pkcs11/usr \ - --with-pkcs11=/usr/lib/64/libpkcs11.so - - (For a 32-bit build, omit CC="cc -xarch=amd64".) - If configure complains about OpenSSL not working, you - may have a 32/64-bit architecture mismatch. Or, you may have - incorrectly specified the path to OpenSSL (it should be the - same as the --prefix argument to the OpenSSL - Configure). - - - - Configuring BIND 9 for SoftHSM - -$ cd ../bind9 -$ ./configure --enable-threads \ - --with-openssl=/opt/pkcs11/usr \ - --with-pkcs11=/opt/pkcs11/usr/lib/libpkcs11.so - - - After configuring, run - "make", - "make test" and - "make install". - (Note: If "make test" fails in the "pkcs11" system test, you may - have forgotten to set the SOFTHSM_CONF environment variable.) - - - PKCS #11 Tools - BIND 9 includes a minimal set of tools to operate the - HSM, including - pkcs11-keygen to generate a new key pair - within the HSM, - pkcs11-list to list objects currently - available, and - pkcs11-destroy to remove objects. - In UNIX/Linux builds, these tools are built only if BIND - 9 is configured with the --with-pkcs11 option. (NOTE: If - --with-pkcs11 is set to "yes", rather than to the path of the - PKCS #11 provider, then the tools will be built but the - provider will be left undefined. Use the -m option or the - PKCS11_PROVIDER environment variable to specify the path to the - provider.) - - - Using the HSM - First, we must set up the runtime environment so the - OpenSSL and PKCS #11 libraries can be loaded: - -$ export LD_LIBRARY_PATH=/opt/pkcs11/usr/lib:${LD_LIBRARY_PATH} - - 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 - /opt/Keyper/PKCS11Provider/machine, - use: - -$ export KEYPER_LIBRARY_PATH=/opt/Keyper/PKCS11Provider - - - These environment variables must be set whenever running - any tool that uses the HSM, including - pkcs11-keygen, - pkcs11-list, - pkcs11-destroy, - dnssec-keyfromlabel, - dnssec-signzone, - dnssec-keygen(which will use the HSM for - random number generation), and - named. - 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 - "sample-ksk": - -$ pkcs11-keygen -b 2048 -l sample-ksk - - To confirm that the key exists: - -$ pkcs11-list -Enter PIN: -object[0]: handle 2147483658 class 3 label[8] 'sample-ksk' id[0] -object[1]: handle 2147483657 class 2 label[8] 'sample-ksk' id[0] - - Before using this key to sign a zone, we must create a - pair of BIND 9 key files. The "dnssec-keyfromlabel" utility - does this. In this case, we will be using the HSM key - "sample-ksk" as the key-signing key for "example.net": - -$ dnssec-keyfromlabel -l sample-ksk -f KSK example.net - - The resulting K*.key and K*.private files can now be used - to sign the zone. Unlike normal K* files, which contain both - public and private key data, these files will contain only the - public key data, plus an identifier for the private key which - remains stored within the HSM. The HSM handles signing with the - private key. - If you wish to generate a second key in the HSM for use - as a zone-signing key, follow the same procedure above, using a - different keylabel, a smaller key size, and omitting "-f KSK" - from the dnssec-keyfromlabel arguments: - -$ pkcs11-keygen -b 1024 -l sample-zsk -$ dnssec-keyfromlabel -l sample-zsk example.net - - Alternatively, you may prefer to generate a conventional - on-disk key, using dnssec-keygen: - -$ dnssec-keygen example.net - - This provides less security than an HSM key, but since - HSMs can be slow or cumbersome to use for security reasons, it - may be more efficient to reserve HSM keys for use in the less - frequent key-signing operation. The zone-signing key can be - rolled more frequently, if you wish, to compensate for a - reduction in key security. - Now you can sign the zone. (Note: If not using the -S - option to - dnssec-signzone, it will be necessary to add - the contents of both - K*.key files to the zone master file before - signing it.) - -$ dnssec-signzone -S example.net -Enter PIN: -Verifying the zone using the following algorithms: -NSEC3RSASHA1. -Zone signing complete: -Algorithm: NSEC3RSASHA1: ZSKs: 1, KSKs: 1 active, 0 revoked, 0 stand-by -example.net.signed - - - - Specifying the engine on the command line - The OpenSSL engine can be specified in - named and all of the BIND - dnssec-* 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. - 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: - -$ dnssec-signzone -E '' -S example.net - - This causes - dnssec-signzone to run as if it were compiled - without the --with-pkcs11 option. - - - Running named with automatic zone re-signing - If you want - named 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, - /opt/pkcs11/usr/ssl/openssl.cnf). - The location of the openssl.cnf file can be overridden by - setting the OPENSSL_CONF environment variable before running - named. - Sample openssl.cnf: - - openssl_conf = openssl_def - [ openssl_def ] - engines = engine_section - [ engine_section ] - pkcs11 = pkcs11_section - [ pkcs11_section ] - PIN = <PLACE PIN HERE> - - This will also allow the dnssec-* tools to access the HSM - without PIN entry. (The pkcs11-* tools access the HSM directly, - not via OpenSSL, so a PIN will still be required to use - them.) - - - Placing the HSM's PIN in a text file in - this manner may reduce the security advantage of using an - HSM. Be sure this is what you want to do before configuring - OpenSSL in this way. - - - - - -- cgit v1.2.3