December 3, 2007
DNSSEC Enthusiasts-
Here is my second version of modifications to BIND for native PKCS11 HSM (Hardware Security Module) support (first released June 14 2007 on dnssec-deployment@shinkuro.com) along with HSM independent utilities.
For BIND, the vast majority of changes are restricted to one file (lib/dns/opensslrsa_link.c).
I also have a number of PKCS11 based HSM utilities that should also work with any HSM with PKCS11. These include:
- pkcs11-backup: private key backup using C_Wrap/C_Unwrap. Also key listing and deletion.
- pkcs11-changepin: allows changes to the HSM PIN
- pkcs11-random: generate N random numbers using the certified methods inside the HSM.
- pkcs11-encrypt: encrypt and decrypt external files using the HSM.
- opensslrsa_link.c: has sample code for using the HSM to perform signing and key generation.
Feel free to use it or pieces of the code as you please.
I. How to build and test PKCS11 HSM tools:
1. If you have not done so already, install and configure the PKCS11 library for your HSM.
If first time using this HSM this typically includes:
a. copying the pkcs11 library into a directory
b. enable the HSM
c. initialize the HSM
Otherwise:
a. just enable the HSM
2. Set environment variables:
My HSM tools and BIND mods will use PKCS11_LIBRARY_PATH to determine what library to load. So you must set this environment variable appropriately, e.g.,
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$HSM_LIBRARY_DIR
export PKCS11_LIBRARY_PATH=$HSM_LIBRARY_DIR/pkcs11.so.3.10
3. Compile the tools:
$ cc pkcs11-backup.c -o pkcs11-backup -ldl
$ cc pkcs11-changepin.c -o pkcs11-changepin -ldl
$ cc pkcs11-random.c -o pkcs11-random -ldl
$ cc pkcs11-encrypt.c -o pkcs11-encrypt -ldl
4. Test
$ ./pkcs11-backup -l
(after asking for the HSM PIN, this should list the keys in the HSM)
or
$ ./pkcs11-random 10 randombytes
(to use the HSM to put 10 random bytes into a file called "randombytes")
5. PKCS11 key generation and signing.
Code that performs key generation and signing is at the end of opensslrsa_link.c
II. To build pkcs11 modified BIND:
1. Build
$ wget http://ftp.isc.org/isc/bind9/9.4.1-P1/bind-9.4.1-P1.tar.gz
$ tar zxf bind-9.4.1-P1.tar.gz
$ mv bind-9.4.1-P1 bind-9.4.1-P1.pkcs11
$ wget http://www.xtcn.com/~lamb/bind-9.4.1-P1.pkcs11.diff
$ patch -p0 < bind-9.4.1-P1.pkcs11.diff
$ cd bind-9.4.1-P1.pkcs11
$ ./configure
$ make
2. To test:
$ bin/dnssec/dnssec-keygen -P 123456 -a RSASHA1 -b 1024 -n ZONE ip6.arpa
Kip6.arpa.+005+24727
this will generate two (2) files:
Kip6.arpa.+005+24727.key Kip6.arpa.+005+24727.private
(of course the tag id, 24727, will be different for each new key generation)
the contents of Kip6.arpa.+005+24727.key : (the usual dnssec-keygen output)
ip6.arpa. IN DNSKEY 256 3 5 AwEAAeUUHWIG+nkRRKH6mXtrtll7CgIkqDrKCs8WN9By2OZMH5h6J3jn Q8PEKPhkb8TZOi6z2jYMNzXckzEzKPBFYytg03lBRvW1AmzmkZf3nas8 xpUU7cB1hv4xi5Ry9rnV7PZwpPtmujToOCHb3hUhXmby4DQx77byRHVV V9O/stRL
and the contents of Kip6.arpa.+005+24727.private:
Private-key-format: xxx
slot:0
pin:
id:46
label:K24727
this is different from the normal BIND behaviour and contains only the key label within the HSM and other location information. This information will be used by dnssec-signzone to instruct the HSM to sign records while ensuring the private key is never available in unencrypted form.
To continue with testing dnssec-signzone:
$ cp ip6.arpa.zone zonefile
$ cat Kip6.arpa.+005+24727.key >> zonefile
$ bin/dnssec/dnssec-signzone -P 123456 -o ip6.arpa zonefile Kip6.arpa.+005+24727
dnssec-signzone: warning: zonefile:435: using RFC1035 TTL semantics
zonefile.signed
"zonefile.signed" is the ZSK signed zonefile.
Thats it.
III. dnssec-keygen and dnssec-signzone behavior modifications:
1. Addition of "-P PIN" for unattended key generation and signing operation using an HSM. Without it, the programs will ask for a PIN. Small mod to bin/dnssec/dnssec-keygen.c and bin/dnssec/dnssec-signzone.c to accomodate -P option.
2. The PKCS11 HSM will only be used if the environment variable PKCS11_LIBRARY_PATH is defined. Otherwise, dnssec-keygen and dnssec-signzone should behave normally.
Hope this helps demystify using HSMs.
Have fun,
Rick Lamb