From: Evan Hunt Date: Fri, 19 Aug 2016 00:52:49 +0000 (-0700) Subject: [master] clarify README.site X-Git-Tag: v9.12.0a0~79 X-Git-Url: http://git.ipfire.org/gitweb/?a=commitdiff_plain;h=6d2963e4d4c833820e902c54f7dc7ca89b795f3e;p=thirdparty%2Fbind9.git [master] clarify README.site --- diff --git a/lib/isc/include/pk11/README.site b/lib/isc/include/pk11/README.site index 7794fb5a87b..fee867c6282 100644 --- a/lib/isc/include/pk11/README.site +++ b/lib/isc/include/pk11/README.site @@ -1,9 +1,13 @@ +Copyright (C) 2016 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). It is available -when bind9 was configured with the --with-pcks11 flag. -It prints addresses of selected tokens per algorithm: +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) @@ -12,57 +16,55 @@ It prints addresses of selected tokens per algorithm: - EC (ECDSA, sign/verify) - GOST (Russian hash and sign/verify) - AES (encrypt/decrypt) -and a summary of found tokens. -Current some well known HSMs are predefined site.h -by HSM "flavors": - - Thales nCipher (the default) +...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 an experimental status: + +...and with experimental status: + - OpenDNSSEC SoftHSMv1 with SHA224 support added - Cryptech with SHA224 support added -When bind9 was configured with native PKCS#11 support, -pkcs11-tokens (and any bind9 tools using libisc) raises -an error if a mandatory algorithm is not supported, -(usually 0x70 aka CKR_MECHANISM_INVALID, 0x0 means -a required flag was not available) so if there is a -selected token with the 0x0 address: - - rand or RSA: nothing can be done, i.e., - bind9 native PKCS#11 is not supported 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, i.e., you can use bind9 - without DSA or DH in production. - - digest: run pkcs11-tokens with the -v (verbose) flag. - If the problem is with HMAC mechanisms, use the 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 ask to have this hash algorithm implemented - in the PKCS#11 provider. For any other problem there is - nothing to do (for ever: some hash functions return void - so any internal error is fatal, i.e., crashes), bind9 - native PKCS#11 is not supported with this HSM. - - EC: doesn't matter but you should configure bind9 without - ECDSA support, i.e., add --without-ecdsa to configure arguments. - - GOST: doesn't matter but you should really configure bind9 - without GOST support, i.e., add --without-ecdsa to configure - arguments (really because GOST includes a hash algorithm). - - AES: you must reconfigure bind9 without AES support, - i.e., add --without-aes to configure arguments. - -Note you can disable some standard algorithms (DSA, DH and -MD5) and some algorithms are optional (ECDSA, GOST, AES). -If you don't want an optional algorithm you should simply -configure bind9 with it. -Note the proper way to disable DSA is to simply add it -in a "disable-algorithms" clause in the named config file. -Disable removes the support code so can have some -unwanted side effects, for instance to disable DH -deeply breaks TKEY support. -The only algorithm you might want to disable is MD5 -(even HMAC-MD5 is safe). -A final note: disable flags in site.h work for OpenSSL -code too but this feature is not officially supported yet -(i.e., please don't rely on it). +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. diff --git a/lib/isc/include/pk11/site.h b/lib/isc/include/pk11/site.h index 36226c84b89..b837972e098 100644 --- a/lib/isc/include/pk11/site.h +++ b/lib/isc/include/pk11/site.h @@ -24,13 +24,13 @@ /*\brief Put here specific PKCS#11 tweaks * *\li PK11__SKIP: - * don't consider the lack of this mechanism as a fatal error + * Don't consider the lack of this mechanism as a fatal error. * *\li PK11__REPLACE: - * same than skip and implement it using lower level steps + * Same as SKIP, and implement the mechanism using lower-level steps. * *\li PK11__DISABLE: - * same than skip but support of the whole algorithm is disabled + * Same as SKIP, and disable support for the algorithm. */ /* current implemented flags are: