1 files changed, 72 insertions, 0 deletions
diff --git a/lib/isc/include/pk11/README.site b/lib/isc/include/pk11/README.site
new file mode 100644
index 0000000..6c49891
--- /dev/null
+++ b/lib/isc/include/pk11/README.site
@@ -0,0 +1,72 @@
+Copyright (C) Internet Systems Consortium, Inc. ("ISC")
+
+See COPYRIGHT in the source root or http://isc.org/copyright.html for terms.
+
+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.