external/bsd/bind/dist/bin/pkcs11/OLD-PKCS11-NOTES

   1
   2                         BIND-9 PKCS#11 support
   3
   4 Prerequisite
   5
   6 The PKCS#11 support needs a PKCS#11 OpenSSL engine based on the Solaris one,
   7 released the 2008-12-02 for OpenSSL 0.9.8i, with back port of key by reference
   8 and some improvements, including user friendly PIN management. You may also
   9 use the original engine code.
  10
  11 Compilation
  12
  13 "configure --with-pkcs11 ..."
  14
  15 PKCS#11 Libraries
  16
  17 Tested with Solaris one with a SCA board and with openCryptoki with the
  18 software token. Known to work on Linux and Windows 2003 server so
  19 should work on most operating systems. For AEP Keyper or any device used
  20 only for its protected key store, please switch to the sign-only engine.
  21
  22 OpenSSL Engines
  23
  24 With PKCS#11 support the PKCS#11 engine is statically loaded but at its
  25 initialization it dynamically loads the PKCS#11 objects.
  26 Even the pre commands are therefore unused they are defined with:
  27  SO_PATH:
  28    define: PKCS11_SO_PATH
  29    default: /usr/local/lib/engines/engine_pkcs11.so
  30  MODULE_PATH:
  31    define: PKCS11_MODULE_PATH
  32    default: /usr/lib/libpkcs11.so
  33 Without PKCS#11 support, a specific OpenSSL engine can be still used
  34 by defining ENGINE_ID at compile time.
  35
  36 PKCS#11 tools
  37
  38 The contrib/pkcs11-keygen directory contains a set of experimental tools
  39 to handle keys stored in a Hardware Security Module at the benefit of BIND.
  40
  41 The patch for OpenSSL 0.9.8i is in this directory. Read its README.pkcs11
  42 for the way to use it (these are the original notes so with the original
  43 path, etc. Define HAVE_GETPASSPHRASE if you have getpassphrase() on
  44 a operating system which is not Solaris.)
  45
  46 Not all tools are supported on AEP Keyper but genkey and dnssec-keyfromlabel
  47 are functional.
  48
  49 PIN management
  50
  51 With the just fixed PKCS#11 OpenSSL engine, the PIN should be entered
  52 each time it is required. With the improved engine, the PIN should be
  53 entered the first time it is required or can be configured in the
  54 OpenSSL configuration file (aka. openssl.cnf) by adding in it:
  55  - at the beginning:
  56         openssl_conf = openssl_def
  57  - at any place these sections:
  58         [ openssl_def ]
  59         engines = engine_section
  60         [ engine_section ]
  61         pkcs11 = pkcs11_section
  62         [ pkcs11_section ]
  63         PIN = put__your__pin__value__here
  64
  65 Slot management
  66
  67 The engine tries to use the first best slot but it is recommended
  68 to simply use the slot 0 (usual default, meta-slot on Solaris).
  69
  70 Sign-only engine
  71
  72 openssl.../crypto/engine/hw_pk11-kp.c and hw_pk11_pub-kp.c contain
  73 a stripped down version of hw_pk11.c and hw_pk11_pub.c files which
  74 has only the useful functions (i.e., signature with a RSA private
  75 key in the device protected key store and key loading).
  76
  77 This engine should be used with a device which provides mainly
  78 a protected store and no acceleration. AEP Keyper is an example
  79 of such a device (BTW with the fully capable engine, key export
  80 must be enabled on this device and this configuration is not yet
  81 supported).
  82
  83 Original engine
  84
  85 If you are using the original engine and getpassphrase() is not defined, add:
  86 #define getpassphrase(x) getpass(x)
  87 in openssl.../crypto/engine/hw_pk11_pub.c
  88
  89 Notes
  90
  91 Some names here are registered trademarks, at least Solaris is a trademark
  92 of Sun Microsystems Inc...
  93 Include files are from RSA Labs., PKCS#11 version is 2.20 amendment 3.
  94 The PKCS#11 support is compatible with the forthcoming FIPS 140-2 support.