Copyright (C) 2016, 2017 Internet Systems Consortium, Inc. ("ISC")

This Source Code Form is subject to the terms of the Mozilla Public

License, v. 2.0. If a copy of the MPL was not distributed with this

file, You can obtain one at http://mozilla.org/MPL/2.0/.

How to use site.h for the PKCS#11 provider of your HSM

------------------------------------------------------

First run "pkcs11-tokens" (in bin/pkcs11). This tool is built when BIND9

is configured with the --with-pcks11 flag. It prints the addresses of

selected tokens per algorithm:

- random number generation

- RSA (sign/verify)

- DSA (sign/verify)

- DH (secret derivation)

- digest (hash)

- EC (ECDSA, sign/verify)

- GOST (Russian hash and sign/verify)

- AES (encrypt/decrypt)

...and a summary of PKCS#11 tokens that have been found.

Current well-known HSMs are predefined in site.h according to HSM "flavors":

- Thales nCipher (default)

- OpenDNSSEC SoftHSMv2

...and with experimental status:

- OpenDNSSEC SoftHSMv1 with SHA224 support added

- Cryptech

- AEP Keyper

If BIND9 is configured with native PKCS#11 support (--enable-native-pkcs11),

then pkcs11-tokens will raise an error when a mandatory algorithm is not

supported. (The usual error is 0x70, or CKR_MECHANISM_INVALID; 0x0

indicates that a required flag is not available.) The following steps

may be taken, depending on which algorithms indicate failures:

- rand or RSA: nothing can be done; native PKCS#11 is not supported

in BIND9 with this HSM.

- DSA or DH: run pkcs11-tokens with the -v (verbose) flag. If the

parameter generation mechanism is not supported you can make the token

selection to ignore the error. Note DSA and DH are not critical

algorithms; you can use BIND9 in production without them.

- digest: run pkcs11-tokens with the -v (verbose) flag. If the problem is

with HMAC mechanisms, use the corresponding REPLACE flags in site.h.

If the problem is with MD5, use the corresponding DISABLE flag in

site.h. If the problem is with SHA224, contact the implementor of the

PKCS#11 provider and ask to have this hash algorithm implemented. For

any other problem, nothing can be done; native PKCS#11 is not supported

with this HSM.

- EC: you may wish to configure BIND9 without ECDSA support by adding

--without-ecdsa to the "configure" arguments.

- GOST: you SHOULD configure BIND9 without GOST support by adding

--without-gost to the "configure" arguments.

- AES: you MUST reconfigure bind9 without AES support by adding

--without-aes to configure arguments.

You can disable some algorithms (e.g. DSA, DH and MD5) using the

"disable-algorithms" option in named.conf, and some other algorithms can be

disabled at compile time (ECDSA, GOST, AES). Note, however, that disabling

algorithms can have unwanted side effects; for instance, disabling DH breaks

TKEY support.

A final note: the DISABLE flags in site.h work for OpenSSL code too, but

this feature is not officially supported yet and should not be relied on.