mir/bind
2
0
Fork 0
mirror of https://gitlab.isc.org/isc-projects/bind9 synced 2025-09-01 15:05:23 +00:00
Code Issues Releases Wiki Activity

- new README.pkcs11

Browse Source 
- old README.pkcs11 moved to contrib/pkcs11-keygen/PKCS11-NOTES
This commit is contained in:
Evan Hunt
2009-09-08 06:54:00 +00:00
parent d7e3784c77
commit d7c15f7c37
2 changed files with 355 additions and 70 deletions
Download Patch File Download Diff File Expand all files Collapse all files

331
README.pkcs11
View File

@@ -1,94 +1,285 @@
BIND-9 PKCS#11 support BIND 9 PKCS #11 (Cryptoki) support
Prerequisite INTRODUCTION
The PKCS#11 support needs a PKCS#11 OpenSSL engine based on the Solaris one, PKCS #11 (Public Key Cryptography Standard #11) defines a platform-
released the 2008-12-02 for OpenSSL 0.9.8i, with back port of key by reference independent API for the control of hardware security modules (HSMs)
and some improvements, including user friendly PIN management. You may also and other cryptographic support devices.
use the original engine code.
Compilation BIND 9 is known to work with two HSMs: The Sun SCA 6000 cryptographic
acceration board, tested under OpenSolaris x86, and the AEP Keyper
network-attached key storage device, tested with a Debian Linux system.
(The Keyper has also been tested with Windows 2003 and found to work,
but with some stability problems that have not yet been resolved.)
"configure --with-pkcs11 ..." PREREQUISITES
PKCS#11 Libraries See the HSM vendor documentation for information about installing,
initializing, testing and troubleshooting the HSM.
Tested with Solaris one with a SCA board and with openCryptoki with the BIND 9 uses OpenSSL for cryptography, but stock OpenSSL does not
software token. Known to work on Linux and Windows 2003 server so yet fully support PKCS #11. However, a PKCS #11 engine for OpenSSL
should work on most operating systems. For AEP Keyper or any device used is available from the OpenSolaris project. It has been modified by
only for its protected key store, please switch to the sign-only engine. ISC to work with with BIND 9, and with further improvements to provide
features such as PIN management.
OpenSSL Engines The modified OpenSSL depends on a PKCS #11 shared library object,
which is provided by the HSM vendor and is specific to the HSM to
be controlled.
With PKCS#11 support the PKCS#11 engine is statically loaded but at its The OpenSSL code is included in BIND 9.7.0a3 release in the form
initialization it dynamically loads the PKCS#11 objects. of a context diff against OpenSSL 0.9.8i. Before building BIND 9
Even the pre commands are therefore unused they are defined with: PKCS #11 support, it will be necessary to build OpenSSL with this
SO_PATH: patch in place, and provide it with the path to the HSM-specific
define: PKCS11_SO_PATH PKCS #11 library.
default: /usr/local/lib/engines/engine_pkcs11.so
MODULE_PATH:
define: PKCS11_MODULE_PATH
default: /usr/lib/libpkcs11.so
Without PKCS#11 support, a specific OpenSSL engine can be still used
by defining ENGINE_ID at compile time.
PKCS#11 tools Obtain OpenSSL 0.9.8i:
The contrib/pkcs11-keygen directory contains a set of experimental tools wget http://www.openssl.org/source/openssl-0.9.8i.tar.gz
to handle keys stored in a Hardware Security Module at the benefit of BIND.
The patch for OpenSSL 0.9.8i is in this directory. Read its README.pkcs11 Extract the tarball:
for the way to use it (these are the original notes so with the original
path, etc. Define HAVE_GETPASSPHRASE if you have getpassphrase() on
a operating system which is not Solaris.)
Not all tools are supported on AEP Keyper but genkey and dnssec-keyfromlabel tar zxf openssl-0.9.8i.tar.gz
are functional.
PIN management Apply the patch from the BIND 9 release:
With the just fixed PKCS#11 OpenSSL engine, the PIN should be entered patch -p1 -d openssl-0.9.8i \
each time it is required. With the improved engine, the PIN should be < bind-9.7.0a3/contrib/pkcs11-keygen/openssl-0.9.8i-patch
entered the first time it is required or can be configured in the
OpenSSL configuration file (aka. openssl.cnf) by adding in it:
- at the beginning:
openssl_conf = openssl_def
- at any place these sections:
[ openssl_def ]
engines = engine_section
[ engine_section ]
pkcs11 = pkcs11_section
[ pkcs11_section ]
PIN = put__your__pin__value__here
Slot management (Note that the patch file may not be compatible with the "patch" utility
on all operating systems. You may need to install GNU patch.)
The engine tries to use the first best slot but it is recommended When building OpenSSL, place it in a non-standard location so that it
to simply use the slot 0 (usual default, meta-slot on Solaris). 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.
Sign-only engine EXAMPLE 1--BUILDING OPENSSL FOR THE AEP KEYPER ON LINUX:
openssl.../crypto/engibe/hw_pk11-kp.c and hw_pk11_pub-kp.c contain The AEP Keyper is a highly-secured key storage device, but it does not
a stripped down version of hw_pk11.c and hw_pk11_pub.c files which provide hardware cryptographic acceleration. It can carry out
has only the useful functions (i.e., signature with a RSA private cryptographic operations, but it is probably slower than your
key in the device protected key store and key loading). system's CPU, so it is most efficient to use it only for operations
that require the secured private key.
This engine should be used with a device which provides mainly The patched OpenSSL source tree includes two versions of the PKCS #11
a protected store and no acceleration. AEP Keyper is an example engine, one of which uses the HSM for all cryptographic operations, and
of such a device (BTW with the fully capable engine, key export the other only uses it for signing. To build with the signing-only
must be enabled on this device and this configuration is not yet engine:
supported).
Original engine cp openssl-0.9.8i/crypto/engine/hw_pk11-kp.c \
openssl-0.9.8i/crypto/engine/hw_pk11.c
cp openssl-0.9.8i/crypto/engine/hw_pk11_pub-kp.c \
openssl-0.9.8i/crypto/engine/hw_pk11_pub.c
If you are using the original engine and getpassphrase() is not defined, add: The Keyper-specific PKCS #11 shared library object is provided
#define getpassphrase(x) getpass(x) by AEP. In this example, we place it /opt/pkcs11/usr/lib:
in openssl.../crypto/engine/hw_pk11_pub.c
Notes cp pkcs11.GCC4.0.2.so.4.05 /opt/pkcs11/usr/lib/libpkcs11.so
Some names here are registered trademarks, at least Solaris is a trademark Note that the this library is only available for Linux as a 32-bit
of Sun Microsystems Inc... binary. If we are compiling on a 64-bit Linux system, it is necessary
Include files are from RSA Labs., PKCS#11 version is 2.20 amendment 3. to force a 32-bit build, by specifying -m32 in the build options.
The PKCS#11 support is compatible with the forthcoming FIPS 140-2 support.
Finally, the Keyper library requires threads, so we must specify -pthread.
cd openssl-0.9.8i
./Configure linux-generic32 -m32 -pthread \
--pk11-libname=/opt/pkcs11/usr/lib/libpkcs11.so \
--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.
EXAMPLE 2--BUILDING OPENSSL FOR THE SCA 6000 ON SOLARIS:
The SCA-6000 PKCS #11 library is provided as a system library, libpkcs11.
In this example, we are building on OpenSolaris x86 on an AMD64 system.
cd openssl-0.9.8i
./Configure solaris64-x86_64-cc -xarch=amd64 \
--pk11-libname=/usr/lib/64/libpkcs11.so \
--prefix=/opt/pkcs11/usr
After configuring, run "make" and "make test".
Once you have built OpenSSL, run "apps/openssl engine" to confirm that
PKCS #11 support was compiled in correctly. The output should include the
line:
(pkcs11) PKCS #11 engine support
If the output is correct, run "make install".
BUILDING BIND 9
When building BIND 9, the location of the custom-built OpenSSL
library must be specified via configure.
EXAMPLE 3--CONFIGURING BIND 9 FOR LINUX
To link with the PKCS #11 library, threads must be enabled in the bind9
build.
Since the PKCS #11 library is 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 ../bind-9.7.0a3
./configure CC="gcc -m32" --enable-threads \
--with-openssl=/opt/pkcs11/usr
EXAMPLE 4--CONFIGURING BIND 9 FOR SOLARIS
To link with the PKCS #11 library, threads must be enabled in the bind9
build.
cd ../bind-9.7.0a3
./configure CC="cc -xarch=adm64" --enable-threads \
--with-openssl=/opt/pkcs11/usr
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).
After configuring, run "make", "make test" and "make install".
PKCS #11 TOOLS
The contrib/pkcs11-keygen directory contains a set of experimental
tools to operate an HSM for the benefit of BIND 9, including "genkey" to
generate a new key pair within the HSM, and "listobjs" to list keys
currently available.
These tools are not yet complete, not documented, and not supported
by ISC. As of BIND 9.7.0a3, they still lack such basic amenities as
a Makefile. Other commercial or open-source PKCS #11 tools may be
available which are better-suited to the job. However, in the
absence of those tools, the ones provided in contrib/pkcs11-keygen
can get you started.
EXAMPLE 5--BUILDING TOOLS ON LINUX:
gcc -m32 -DHAVE_GETPASS -I. -L /opt/pkcs11/usr/lib \
genkey.c -o genkey -lpkcs11
gcc -m32 -DHAVE_GETPASS -I. -L /opt/pkcs11/usr/lib \
listobjs.c -o listobjs -lpkcs11
gcc -m32 -DHAVE_GETPASS -I. -L /opt/pkcs11/usr/lib \
destroyobj.c -o destroyobj -lpkcs11
cd ../..
EXAMPLE 6--BUILDING TOOLS ON SOLARIS:
cc -xarch=amd64 -I. -L /opt/pkcs11/usr/lib \
genkey.c -o genkey -lcrypto -lpkcs11 -lsocket
cc -xarch=amd64 -I. -L /opt/pkcs11/usr/lib \
listobjs.c -o listobjs -lcrypto -lpkcs11 -lsocket
cc -xarch=amd64 -I. -L /opt/pkcs11/usr/lib \
destroyobj.c -o destroyobj -lcrypto -lpkcs11 -lsocket
cd ../..
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 provides information about the
Keyper to the PKCS #11 library. For example, 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
which uses the HSM, including genkey, listobjs, destroyobj,
dnssec-keyfromlabel, dnssec-signzone, 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":
contrib/pkcs11-keygen/genkey -b 2048 -l sample-ksk
To confirm that the key exists:
contrib/pkcs11-keygen/listobjs
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 -a NSEC3RSASHA1 -l pkcs11:sample-ksk -f KSK example.net
(Note: It is necessary to specify "pkcs11:" before the key's label;
otherwise the PCKS #11 engine will look for the key on disk rather than
in the HSM. If you forget to do this, dnssec-keyfromlabel will return
"not found".)
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:
contrib/pkcs11-keygen/genkey -b 1024 -l sample-zsk
dnssec-keyfromlabel -a NSEC3RSASHA1 -l pkcs11:sample-zsk example.net
Alternatively, you may prefer to generate a conventional on-disk key, using
dnssec-keygen:
dnssec-keygen -a NSEC3RSASHA1 -b 1024 example.net
This provides less security than an HSM key, but since HSMs are often
slower at signing than your system's CPU, it may be more efficient to
reserve HSM keys for 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
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>
PLEASE NOTE: 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 BIND 9 in this way.

94
contrib/pkcs11-keygen/PKCS11-NOTES Normal file
View File

@@ -0,0 +1,94 @@
BIND-9 PKCS#11 support
Prerequisite
The PKCS#11 support needs a PKCS#11 OpenSSL engine based on the Solaris one,
released the 2008-12-02 for OpenSSL 0.9.8i, with back port of key by reference
and some improvements, including user friendly PIN management. You may also
use the original engine code.
Compilation
"configure --with-pkcs11 ..."
PKCS#11 Libraries
Tested with Solaris one with a SCA board and with openCryptoki with the
software token. Known to work on Linux and Windows 2003 server so
should work on most operating systems. For AEP Keyper or any device used
only for its protected key store, please switch to the sign-only engine.
OpenSSL Engines
With PKCS#11 support the PKCS#11 engine is statically loaded but at its
initialization it dynamically loads the PKCS#11 objects.
Even the pre commands are therefore unused they are defined with:
SO_PATH:
define: PKCS11_SO_PATH
default: /usr/local/lib/engines/engine_pkcs11.so
MODULE_PATH:
define: PKCS11_MODULE_PATH
default: /usr/lib/libpkcs11.so
Without PKCS#11 support, a specific OpenSSL engine can be still used
by defining ENGINE_ID at compile time.
PKCS#11 tools
The contrib/pkcs11-keygen directory contains a set of experimental tools
to handle keys stored in a Hardware Security Module at the benefit of BIND.
The patch for OpenSSL 0.9.8i is in this directory. Read its README.pkcs11
for the way to use it (these are the original notes so with the original
path, etc. Define HAVE_GETPASSPHRASE if you have getpassphrase() on
a operating system which is not Solaris.)
Not all tools are supported on AEP Keyper but genkey and dnssec-keyfromlabel
are functional.
PIN management
With the just fixed PKCS#11 OpenSSL engine, the PIN should be entered
each time it is required. With the improved engine, the PIN should be
entered the first time it is required or can be configured in the
OpenSSL configuration file (aka. openssl.cnf) by adding in it:
- at the beginning:
openssl_conf = openssl_def
- at any place these sections:
[ openssl_def ]
engines = engine_section
[ engine_section ]
pkcs11 = pkcs11_section
[ pkcs11_section ]
PIN = put__your__pin__value__here
Slot management
The engine tries to use the first best slot but it is recommended
to simply use the slot 0 (usual default, meta-slot on Solaris).
Sign-only engine
openssl.../crypto/engibe/hw_pk11-kp.c and hw_pk11_pub-kp.c contain
a stripped down version of hw_pk11.c and hw_pk11_pub.c files which
has only the useful functions (i.e., signature with a RSA private
key in the device protected key store and key loading).
This engine should be used with a device which provides mainly
a protected store and no acceleration. AEP Keyper is an example
of such a device (BTW with the fully capable engine, key export
must be enabled on this device and this configuration is not yet
supported).
Original engine
If you are using the original engine and getpassphrase() is not defined, add:
#define getpassphrase(x) getpass(x)
in openssl.../crypto/engine/hw_pk11_pub.c
Notes
Some names here are registered trademarks, at least Solaris is a trademark
of Sun Microsystems Inc...
Include files are from RSA Labs., PKCS#11 version is 2.20 amendment 3.
The PKCS#11 support is compatible with the forthcoming FIPS 140-2 support.