1Copyright (C) Internet Systems Consortium, Inc. ("ISC") 2 3See COPYRIGHT in the source root or https://isc.org/copyright.html for terms. 4 5How to use site.h for the PKCS#11 provider of your HSM 6------------------------------------------------------ 7 8First run "pkcs11-tokens" (in bin/pkcs11). This tool is built when BIND9 9is configured with the --with-pcks11 flag. It prints the addresses of 10selected tokens per algorithm: 11 12 - random number generation 13 - RSA (sign/verify) 14 - DSA (sign/verify) 15 - DH (secret derivation) 16 - digest (hash) 17 - EC (ECDSA, sign/verify) 18 - GOST (Russian hash and sign/verify) 19 - AES (encrypt/decrypt) 20 21...and a summary of PKCS#11 tokens that have been found. 22 23Current well-known HSMs are predefined in site.h according to HSM "flavors": 24 25 - Thales nCipher (default) 26 - OpenDNSSEC SoftHSMv2 27 28...and with experimental status: 29 30 - OpenDNSSEC SoftHSMv1 with SHA224 support added 31 - Cryptech 32 - AEP Keyper 33 34If BIND9 is configured with native PKCS#11 support (--enable-native-pkcs11), 35then pkcs11-tokens will raise an error when a mandatory algorithm is not 36supported. (The usual error is 0x70, or CKR_MECHANISM_INVALID; 0x0 37indicates that a required flag is not available.) The following steps 38may be taken, depending on which algorithms indicate failures: 39 40 - rand or RSA: nothing can be done; native PKCS#11 is not supported 41 in BIND9 with this HSM. 42 43 - DSA or DH: run pkcs11-tokens with the -v (verbose) flag. If the 44 parameter generation mechanism is not supported you can make the token 45 selection to ignore the error. Note DSA and DH are not critical 46 algorithms; you can use BIND9 in production without them. 47 48 - digest: run pkcs11-tokens with the -v (verbose) flag. If the problem is 49 with HMAC mechanisms, use the corresponding REPLACE flags in site.h. 50 If the problem is with MD5, use the corresponding DISABLE flag in 51 site.h. If the problem is with SHA224, contact the implementor of the 52 PKCS#11 provider and ask to have this hash algorithm implemented. For 53 any other problem, nothing can be done; native PKCS#11 is not supported 54 with this HSM. 55 56 - EC: you may wish to configure BIND9 without ECDSA support by adding 57 --without-ecdsa to the "configure" arguments. 58 59 - GOST: you SHOULD configure BIND9 without GOST support by adding 60 --without-gost to the "configure" arguments. 61 62 - AES: you MUST reconfigure bind9 without AES support by adding 63 --without-aes to configure arguments. 64 65You can disable some algorithms (e.g. DSA, DH and MD5) using the 66"disable-algorithms" option in named.conf, and some other algorithms can be 67disabled at compile time (ECDSA, GOST, AES). Note, however, that disabling 68algorithms can have unwanted side effects; for instance, disabling DH breaks 69TKEY support. 70 71A final note: the DISABLE flags in site.h work for OpenSSL code too, but 72this feature is not officially supported yet and should not be relied on. 73