mir/bind
2
0
Fork 0
mirror of https://gitlab.isc.org/isc-projects/bind9 synced 2025-08-31 14:35:26 +00:00
Code Issues Releases Wiki Activity

updated for 9.7.0b1 release

Browse Source
This commit is contained in:
Evan Hunt
2009-10-06 21:44:18 +00:00
parent 246c504f90
commit cd3e5ca69a
1 changed files with 74 additions and 46 deletions
Download Patch File Download Diff File Expand all files Collapse all files

120
README.pkcs11
View File

@@ -20,22 +20,32 @@ 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
ISC to work with with BIND 9, and to provide new features such as
PIN management and key by reference.
The PKCS#11 engine supports two flavors:
- the crypto-accelerator which uses the PKCS#11 device for all crypto
operations it supports. This is the right choice for the SCA 6000.
- the sign-only which was stripped down and provides only the
useful features for a secure key store. The Keyper must use this
flavor.
The modified OpenSSL depends on a "PKCS #11 provider". This is a shared
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
hardware. It is dynamically loaded by OpenSSL at runtime. The PKCS #11
provider comes from the HSM vendor, and 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 operation
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 BIND 9.7.0b1 release in the form
of a context diff against OpenSSL 0.9.8k. Before building BIND 9 with
PKCS #11 support, it will be necessary to build OpenSSL with this patch
@@ -65,12 +75,11 @@ We will use this location when we configure BIND 9.
EXAMPLE 1--BUILDING OPENSSL FOR THE AEP KEYPER ON LINUX:
The AEP Keyper is a highly-secured key storage device, but it does
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, so it is most efficient to use it only for operations
that require the secured private key. This is why the PKCS#11
engine flavor shall be 'sign-only'.
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:
@@ -111,13 +120,19 @@ We will use this location when we configure BIND 9.
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:
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
(pkcs11) PKCS #11 engine support (sign only)
<<"apps/openssl engine -t" to see if initialization is correct (available)>>
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".
@@ -131,9 +146,10 @@ library must be specified via configure.
To link with the PKCS #11 provider, threads must be enabled in the
BIND 9 build.
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.
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 ../bind-9.7.0b1
./configure CC="gcc -m32" --enable-threads \
@@ -159,14 +175,17 @@ Configure).
After configuring, run "make", "make test" and "make install".
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.
The bin/pkcs11 directory contains a set of tools to operate an HSM for
the benefit of BIND 9, 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.
<<<To Finish with 20225 and children about --with-pkcs11>>>
These tools are built 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
@@ -203,16 +222,7 @@ 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".)
<<Something about -E>>
<<Something about bad formatted .private (simply rerun dnssec-keyfromlabel
which by side-effect will fix the smart signing dates too)>>
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
@@ -226,18 +236,19 @@ smaller key size, and omitting "-f KSK" from the dnssec-keyfromlabel
arguments:
pkcs11-keygen -b 1024 -l sample-zsk
dnssec-keyfromlabel -a NSEC3RSASHA1 -l pkcs11:sample-zsk example.net
dnssec-keyfromlabel -l 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
dnssec-keygen 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.
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
@@ -250,6 +261,23 @@ K*.key files to the zone master file before signing it.)
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 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