mirror of
https://gitlab.isc.org/isc-projects/bind9
synced 2025-08-31 14:35:26 +00:00
- new README.pkcs11
- old README.pkcs11 moved to contrib/pkcs11-keygen/PKCS11-NOTES
This commit is contained in:
Evan Hunt
331
README.pkcs11
331
README.pkcs11
@@ -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,
|
||||
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.
|
||||
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.
|
||||
|
||||
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
|
||||
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.
|
||||
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 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
|
||||
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.
|
||||
The OpenSSL code is included in BIND 9.7.0a3 release in the form
|
||||
of a context diff against OpenSSL 0.9.8i. Before building BIND 9
|
||||
PKCS #11 support, it will be necessary to build OpenSSL with this
|
||||
patch in place, and provide it with the path to the HSM-specific
|
||||
PKCS #11 library.
|
||||
|
||||
PKCS#11 tools
|
||||
Obtain OpenSSL 0.9.8i:
|
||||
|
||||
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.
|
||||
wget http://www.openssl.org/source/openssl-0.9.8i.tar.gz
|
||||
|
||||
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.)
|
||||
Extract the tarball:
|
||||
|
||||
Not all tools are supported on AEP Keyper but genkey and dnssec-keyfromlabel
|
||||
are functional.
|
||||
tar zxf openssl-0.9.8i.tar.gz
|
||||
|
||||
PIN management
|
||||
Apply the patch from the BIND 9 release:
|
||||
|
||||
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
|
||||
patch -p1 -d openssl-0.9.8i \
|
||||
< bind-9.7.0a3/contrib/pkcs11-keygen/openssl-0.9.8i-patch
|
||||
|
||||
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
|
||||
to simply use the slot 0 (usual default, meta-slot on Solaris).
|
||||
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.
|
||||
|
||||
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
|
||||
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).
|
||||
The AEP Keyper is a highly-secured key storage device, but it does not
|
||||
provide hardware cryptographic acceleration. It can carry out
|
||||
cryptographic operations, but it is probably slower than your
|
||||
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
|
||||
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).
|
||||
The patched OpenSSL source tree includes two versions of the PKCS #11
|
||||
engine, one of which uses the HSM for all cryptographic operations, and
|
||||
the other only uses it for signing. To build with the signing-only
|
||||
engine:
|
||||
|
||||
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:
|
||||
#define getpassphrase(x) getpass(x)
|
||||
in openssl.../crypto/engine/hw_pk11_pub.c
|
||||
The Keyper-specific PKCS #11 shared library object is provided
|
||||
by AEP. In this example, we place it /opt/pkcs11/usr/lib:
|
||||
|
||||
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
|
||||
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.
|
||||
Note that the 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.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
94
contrib/pkcs11-keygen/PKCS11-NOTES
Normal 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.
|
||||
Reference in New Issue
Block a user