/contrib/bind9/doc/arm/pkcs11.xml

https://bitbucket.org/freebsd/freebsd-head/ · XML · 443 lines · 411 code · 2 blank · 30 comment · 0 complexity · 61b95743ce6b089346bb1a5be31fd9e7 MD5 · raw file

  1. <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
  2. "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
  3. [<!ENTITY mdash "&#8212;">]>
  4. <!--
  5. - Copyright (C) 2010, 2012 Internet Systems Consortium, Inc. ("ISC")
  6. -
  7. - Permission to use, copy, modify, and/or distribute this software for any
  8. - purpose with or without fee is hereby granted, provided that the above
  9. - copyright notice and this permission notice appear in all copies.
  10. -
  11. - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
  12. - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
  13. - AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
  14. - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
  15. - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
  16. - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
  17. - PERFORMANCE OF THIS SOFTWARE.
  18. -->
  19. <!-- $Id$ -->
  20. <sect1 id="pkcs11">
  21. <title>PKCS #11 (Cryptoki) support</title>
  22. <para>PKCS #11 (Public Key Cryptography Standard #11) defines a
  23. platform- independent API for the control of hardware security
  24. modules (HSMs) and other cryptographic support devices.</para>
  25. <para>BIND 9 is known to work with two HSMs: The Sun SCA 6000
  26. cryptographic acceleration board, tested under Solaris x86, and
  27. the AEP Keyper network-attached key storage device, tested with
  28. Debian Linux, Solaris x86 and Windows Server 2003.</para>
  29. <sect2>
  30. <title>Prerequisites</title>
  31. <para>See the HSM vendor documentation for information about
  32. installing, initializing, testing and troubleshooting the
  33. HSM.</para>
  34. <para>BIND 9 uses OpenSSL for cryptography, but stock OpenSSL
  35. does not yet fully support PKCS #11. However, a PKCS #11 engine
  36. for OpenSSL is available from the OpenSolaris project. It has
  37. been modified by ISC to work with with BIND 9, and to provide
  38. new features such as PIN management and key by
  39. reference.</para>
  40. <para>The patched OpenSSL depends on a "PKCS #11 provider".
  41. This is a shared library object, providing a low-level PKCS #11
  42. interface to the HSM hardware. It is dynamically loaded by
  43. OpenSSL at runtime. The PKCS #11 provider comes from the HSM
  44. vendor, and and is specific to the HSM to be controlled.</para>
  45. <para>There are two "flavors" of PKCS #11 support provided by
  46. the patched OpenSSL, one of which must be chosen at
  47. configuration time. The correct choice depends on the HSM
  48. hardware:</para>
  49. <itemizedlist>
  50. <listitem>
  51. <para>Use 'crypto-accelerator' with HSMs that have hardware
  52. cryptographic acceleration features, such as the SCA 6000
  53. board. This causes OpenSSL to run all supported
  54. cryptographic operations in the HSM.</para>
  55. </listitem>
  56. <listitem>
  57. <para>Use 'sign-only' with HSMs that are designed to
  58. function primarily as secure key storage devices, but lack
  59. hardware acceleration. These devices are highly secure, but
  60. are not necessarily any faster at cryptography than the
  61. system CPU &mdash; often, they are slower. It is therefore
  62. most efficient to use them only for those cryptographic
  63. functions that require access to the secured private key,
  64. such as zone signing, and to use the system CPU for all
  65. other computationally-intensive operations. The AEP Keyper
  66. is an example of such a device.</para>
  67. </listitem>
  68. </itemizedlist>
  69. <para>The modified OpenSSL code is included in the BIND 9 release,
  70. in the form of a context diff against the latest verions of
  71. OpenSSL. OpenSSL 0.9.8 and 1.0.0 are both supported; there are
  72. separate diffs for each version. In the examples to follow,
  73. we use OpenSSL 0.9.8, but the same methods work with OpenSSL 1.0.0.
  74. </para>
  75. <note>
  76. The latest OpenSSL versions at the time of the BIND release
  77. are 0.9.8s and 1.0.0f.
  78. ISC will provide an updated patch as new versions of OpenSSL
  79. are released. The version number in the following examples
  80. is expected to change.</note>
  81. <para>
  82. Before building BIND 9 with PKCS #11 support, it will be
  83. necessary to build OpenSSL with this patch in place and inform
  84. it of the path to the HSM-specific PKCS #11 provider
  85. library.</para>
  86. <para>Obtain OpenSSL 0.9.8s:</para>
  87. <screen>
  88. $ <userinput>wget <ulink>http://www.openssl.org/source/openssl-0.9.8s.tar.gz</ulink></userinput>
  89. </screen>
  90. <para>Extract the tarball:</para>
  91. <screen>
  92. $ <userinput>tar zxf openssl-0.9.8s.tar.gz</userinput>
  93. </screen>
  94. <para>Apply the patch from the BIND 9 release:</para>
  95. <screen>
  96. $ <userinput>patch -p1 -d openssl-0.9.8s \
  97. &lt; bind9/bin/pkcs11/openssl-0.9.8s-patch</userinput>
  98. </screen>
  99. <note>(Note that the patch file may not be compatible with the
  100. "patch" utility on all operating systems. You may need to
  101. install GNU patch.)</note>
  102. <para>When building OpenSSL, place it in a non-standard
  103. location so that it does not interfere with OpenSSL libraries
  104. elsewhere on the system. In the following examples, we choose
  105. to install into "/opt/pkcs11/usr". We will use this location
  106. when we configure BIND 9.</para>
  107. <sect3>
  108. <!-- Example 1 -->
  109. <title>Building OpenSSL for the AEP Keyper on Linux</title>
  110. <para>The AEP Keyper is a highly secure key storage device,
  111. but does not provide hardware cryptographic acceleration. It
  112. can carry out cryptographic operations, but it is probably
  113. slower than your system's CPU. Therefore, we choose the
  114. 'sign-only' flavor when building OpenSSL.</para>
  115. <para>The Keyper-specific PKCS #11 provider library is
  116. delivered with the Keyper software. In this example, we place
  117. it /opt/pkcs11/usr/lib:</para>
  118. <screen>
  119. $ <userinput>cp pkcs11.GCC4.0.2.so.4.05 /opt/pkcs11/usr/lib/libpkcs11.so</userinput>
  120. </screen>
  121. <para>This library is only available for Linux as a 32-bit
  122. binary. If we are compiling on a 64-bit Linux system, it is
  123. necessary to force a 32-bit build, by specifying -m32 in the
  124. build options.</para>
  125. <para>Finally, the Keyper library requires threads, so we
  126. must specify -pthread.</para>
  127. <screen>
  128. $ <userinput>cd openssl-0.9.8s</userinput>
  129. $ <userinput>./Configure linux-generic32 -m32 -pthread \
  130. --pk11-libname=/opt/pkcs11/usr/lib/libpkcs11.so \
  131. --pk11-flavor=sign-only \
  132. --prefix=/opt/pkcs11/usr</userinput>
  133. </screen>
  134. <para>After configuring, run "<command>make</command>"
  135. and "<command>make test</command>". If "<command>make
  136. test</command>" fails with "pthread_atfork() not found", you forgot to
  137. add the -pthread above.</para>
  138. </sect3>
  139. <sect3>
  140. <!-- Example 2 -->
  141. <title>Building OpenSSL for the SCA 6000 on Solaris</title>
  142. <para>The SCA-6000 PKCS #11 provider is installed as a system
  143. library, libpkcs11. It is a true crypto accelerator, up to 4
  144. times faster than any CPU, so the flavor shall be
  145. 'crypto-accelerator'.</para>
  146. <para>In this example, we are building on Solaris x86 on an
  147. AMD64 system.</para>
  148. <screen>
  149. $ <userinput>cd openssl-0.9.8s</userinput>
  150. $ <userinput>./Configure solaris64-x86_64-cc \
  151. --pk11-libname=/usr/lib/64/libpkcs11.so \
  152. --pk11-flavor=crypto-accelerator \
  153. --prefix=/opt/pkcs11/usr</userinput>
  154. </screen>
  155. <para>(For a 32-bit build, use "solaris-x86-cc" and
  156. /usr/lib/libpkcs11.so.)</para>
  157. <para>After configuring, run
  158. <command>make</command> and
  159. <command>make test</command>.</para>
  160. </sect3>
  161. <sect3>
  162. <!-- Example 3 -->
  163. <title>Building OpenSSL for SoftHSM</title>
  164. <para>SoftHSM is a software library provided by the OpenDNSSEC
  165. project (http://www.opendnssec.org) which provides a PKCS#11
  166. interface to a virtual HSM, implemented in the form of encrypted
  167. data on the local filesystem. It uses the Botan library for
  168. encryption and SQLite3 for data storage. Though less secure
  169. than a true HSM, it can provide more secure key storage than
  170. traditional key files, and can allow you to experiment with
  171. PKCS#11 when an HSM is not available.</para>
  172. <para>The SoftHSM cryptographic store must be installed and
  173. initialized before using it with OpenSSL, and the SOFTHSM_CONF
  174. environment variable must always point to the SoftHSM configuration
  175. file:</para>
  176. <screen>
  177. $ <userinput> cd softhsm-1.3.0 </userinput>
  178. $ <userinput> configure --prefix=/opt/pkcs11/usr </userinput>
  179. $ <userinput> make </userinput>
  180. $ <userinput> make install </userinput>
  181. $ <userinput> export SOFTHSM_CONF=/opt/pkcs11/softhsm.conf </userinput>
  182. $ <userinput> echo "0:/opt/pkcs11/softhsm.db" > $SOFTHSM_CONF </userinput>
  183. $ <userinput> /opt/pkcs11/usr/bin/softhsm --init-token 0 --slot 0 --label softhsm </userinput>
  184. </screen>
  185. <para>SoftHSM can perform all cryptographic operations, but
  186. since it only uses your system CPU, there is no need to use it
  187. for anything but signing. Therefore, we choose the 'sign-only'
  188. flavor when building OpenSSL.</para>
  189. <screen>
  190. $ <userinput>cd openssl-0.9.8s</userinput>
  191. $ <userinput>./Configure linux-x86_64 -pthread \
  192. --pk11-libname=/opt/pkcs11/usr/lib/libpkcs11.so \
  193. --pk11-flavor=sign-only \
  194. --prefix=/opt/pkcs11/usr</userinput>
  195. </screen>
  196. <para>After configuring, run "<command>make</command>"
  197. and "<command>make test</command>".</para>
  198. </sect3>
  199. <para>Once you have built OpenSSL, run
  200. "<command>apps/openssl engine pkcs11</command>" to confirm
  201. that PKCS #11 support was compiled in correctly. The output
  202. should be one of the following lines, depending on the flavor
  203. selected:</para>
  204. <screen>
  205. (pkcs11) PKCS #11 engine support (sign only)
  206. </screen>
  207. <para>Or:</para>
  208. <screen>
  209. (pkcs11) PKCS #11 engine support (crypto accelerator)
  210. </screen>
  211. <para>Next, run
  212. "<command>apps/openssl engine pkcs11 -t</command>". This will
  213. attempt to initialize the PKCS #11 engine. If it is able to
  214. do so successfully, it will report
  215. <quote><literal>[ available ]</literal></quote>.</para>
  216. <para>If the output is correct, run
  217. "<command>make install</command>" which will install the
  218. modified OpenSSL suite to
  219. <filename>/opt/pkcs11/usr</filename>.</para>
  220. </sect2>
  221. <sect2>
  222. <title>Building BIND 9 with PKCS#11</title>
  223. <para>When building BIND 9, the location of the custom-built
  224. OpenSSL library must be specified via configure.</para>
  225. <sect3>
  226. <!-- Example 4 -->
  227. <title>Configuring BIND 9 for Linux with the AEP Keyper</title>
  228. <para>To link with the PKCS #11 provider, threads must be
  229. enabled in the BIND 9 build.</para>
  230. <para>The PKCS #11 library for the AEP Keyper is currently
  231. only available as a 32-bit binary. If we are building on a
  232. 64-bit host, we must force a 32-bit build by adding "-m32" to
  233. the CC options on the "configure" command line.</para>
  234. <screen>
  235. $ <userinput>cd ../bind9</userinput>
  236. $ <userinput>./configure CC="gcc -m32" --enable-threads \
  237. --with-openssl=/opt/pkcs11/usr \
  238. --with-pkcs11=/opt/pkcs11/usr/lib/libpkcs11.so</userinput>
  239. </screen>
  240. </sect3>
  241. <sect3>
  242. <!-- Example 5 -->
  243. <title>Configuring BIND 9 for Solaris with the SCA 6000</title>
  244. <para>To link with the PKCS #11 provider, threads must be
  245. enabled in the BIND 9 build.</para>
  246. <screen>
  247. $ <userinput>cd ../bind9</userinput>
  248. $ <userinput>./configure CC="cc -xarch=amd64" --enable-threads \
  249. --with-openssl=/opt/pkcs11/usr \
  250. --with-pkcs11=/usr/lib/64/libpkcs11.so</userinput>
  251. </screen>
  252. <para>(For a 32-bit build, omit CC="cc -xarch=amd64".)</para>
  253. <para>If configure complains about OpenSSL not working, you
  254. may have a 32/64-bit architecture mismatch. Or, you may have
  255. incorrectly specified the path to OpenSSL (it should be the
  256. same as the --prefix argument to the OpenSSL
  257. Configure).</para>
  258. </sect3>
  259. <sect3>
  260. <!-- Example 6 -->
  261. <title>Configuring BIND 9 for SoftHSM</title>
  262. <screen>
  263. $ <userinput>cd ../bind9</userinput>
  264. $ <userinput>./configure --enable-threads \
  265. --with-openssl=/opt/pkcs11/usr \
  266. --with-pkcs11=/opt/pkcs11/usr/lib/libpkcs11.so</userinput>
  267. </screen>
  268. </sect3>
  269. <para>After configuring, run
  270. "<command>make</command>",
  271. "<command>make test</command>" and
  272. "<command>make install</command>".</para>
  273. <para>(Note: If "make test" fails in the "pkcs11" system test, you may
  274. have forgotten to set the SOFTHSM_CONF environment variable.)</para>
  275. </sect2>
  276. <sect2>
  277. <title>PKCS #11 Tools</title>
  278. <para>BIND 9 includes a minimal set of tools to operate the
  279. HSM, including
  280. <command>pkcs11-keygen</command> to generate a new key pair
  281. within the HSM,
  282. <command>pkcs11-list</command> to list objects currently
  283. available, and
  284. <command>pkcs11-destroy</command> to remove objects.</para>
  285. <para>In UNIX/Linux builds, these tools are built only if BIND
  286. 9 is configured with the --with-pkcs11 option. (NOTE: If
  287. --with-pkcs11 is set to "yes", rather than to the path of the
  288. PKCS #11 provider, then the tools will be built but the
  289. provider will be left undefined. Use the -m option or the
  290. PKCS11_PROVIDER environment variable to specify the path to the
  291. provider.)</para>
  292. </sect2>
  293. <sect2>
  294. <title>Using the HSM</title>
  295. <para>First, we must set up the runtime environment so the
  296. OpenSSL and PKCS #11 libraries can be loaded:</para>
  297. <screen>
  298. $ <userinput>export LD_LIBRARY_PATH=/opt/pkcs11/usr/lib:${LD_LIBRARY_PATH}</userinput>
  299. </screen>
  300. <para>When operating an AEP Keyper, it is also necessary to
  301. specify the location of the "machine" file, which stores
  302. information about the Keyper for use by PKCS #11 provider
  303. library. If the machine file is in
  304. <filename>/opt/Keyper/PKCS11Provider/machine</filename>,
  305. use:</para>
  306. <screen>
  307. $ <userinput>export KEYPER_LIBRARY_PATH=/opt/Keyper/PKCS11Provider</userinput>
  308. </screen>
  309. <!-- TODO: why not defined at compile time? -->
  310. <para>These environment variables must be set whenever running
  311. any tool that uses the HSM, including
  312. <command>pkcs11-keygen</command>,
  313. <command>pkcs11-list</command>,
  314. <command>pkcs11-destroy</command>,
  315. <command>dnssec-keyfromlabel</command>,
  316. <command>dnssec-signzone</command>,
  317. <command>dnssec-keygen</command>(which will use the HSM for
  318. random number generation), and
  319. <command>named</command>.</para>
  320. <para>We can now create and use keys in the HSM. In this case,
  321. we will create a 2048 bit key and give it the label
  322. "sample-ksk":</para>
  323. <screen>
  324. $ <userinput>pkcs11-keygen -b 2048 -l sample-ksk</userinput>
  325. </screen>
  326. <para>To confirm that the key exists:</para>
  327. <screen>
  328. $ <userinput>pkcs11-list</userinput>
  329. Enter PIN:
  330. object[0]: handle 2147483658 class 3 label[8] 'sample-ksk' id[0]
  331. object[1]: handle 2147483657 class 2 label[8] 'sample-ksk' id[0]
  332. </screen>
  333. <para>Before using this key to sign a zone, we must create a
  334. pair of BIND 9 key files. The "dnssec-keyfromlabel" utility
  335. does this. In this case, we will be using the HSM key
  336. "sample-ksk" as the key-signing key for "example.net":</para>
  337. <screen>
  338. $ <userinput>dnssec-keyfromlabel -l sample-ksk -f KSK example.net</userinput>
  339. </screen>
  340. <para>The resulting K*.key and K*.private files can now be used
  341. to sign the zone. Unlike normal K* files, which contain both
  342. public and private key data, these files will contain only the
  343. public key data, plus an identifier for the private key which
  344. remains stored within the HSM. The HSM handles signing with the
  345. private key.</para>
  346. <para>If you wish to generate a second key in the HSM for use
  347. as a zone-signing key, follow the same procedure above, using a
  348. different keylabel, a smaller key size, and omitting "-f KSK"
  349. from the dnssec-keyfromlabel arguments:</para>
  350. <screen>
  351. $ <userinput>pkcs11-keygen -b 1024 -l sample-zsk</userinput>
  352. $ <userinput>dnssec-keyfromlabel -l sample-zsk example.net</userinput>
  353. </screen>
  354. <para>Alternatively, you may prefer to generate a conventional
  355. on-disk key, using dnssec-keygen:</para>
  356. <screen>
  357. $ <userinput>dnssec-keygen example.net</userinput>
  358. </screen>
  359. <para>This provides less security than an HSM key, but since
  360. HSMs can be slow or cumbersome to use for security reasons, it
  361. may be more efficient to reserve HSM keys for use in the less
  362. frequent key-signing operation. The zone-signing key can be
  363. rolled more frequently, if you wish, to compensate for a
  364. reduction in key security.</para>
  365. <para>Now you can sign the zone. (Note: If not using the -S
  366. option to
  367. <command>dnssec-signzone</command>, it will be necessary to add
  368. the contents of both
  369. <filename>K*.key</filename> files to the zone master file before
  370. signing it.)</para>
  371. <screen>
  372. $ <userinput>dnssec-signzone -S example.net</userinput>
  373. Enter PIN:
  374. Verifying the zone using the following algorithms:
  375. NSEC3RSASHA1.
  376. Zone signing complete:
  377. Algorithm: NSEC3RSASHA1: ZSKs: 1, KSKs: 1 active, 0 revoked, 0 stand-by
  378. example.net.signed
  379. </screen>
  380. </sect2>
  381. <sect2>
  382. <title>Specifying the engine on the command line</title>
  383. <para>The OpenSSL engine can be specified in
  384. <command>named</command> and all of the BIND
  385. <command>dnssec-*</command> tools by using the "-E
  386. &lt;engine&gt;" command line option. If BIND 9 is built with
  387. the --with-pkcs11 option, this option defaults to "pkcs11".
  388. Specifying the engine will generally not be necessary unless
  389. for some reason you wish to use a different OpenSSL
  390. engine.</para>
  391. <para>If you wish to disable use of the "pkcs11" engine &mdash;
  392. for troubleshooting purposes, or because the HSM is unavailable
  393. &mdash; set the engine to the empty string. For example:</para>
  394. <screen>
  395. $ <userinput>dnssec-signzone -E '' -S example.net</userinput>
  396. </screen>
  397. <para>This causes
  398. <command>dnssec-signzone</command> to run as if it were compiled
  399. without the --with-pkcs11 option.</para>
  400. </sect2>
  401. <sect2>
  402. <title>Running named with automatic zone re-signing</title>
  403. <para>If you want
  404. <command>named</command> to dynamically re-sign zones using HSM
  405. keys, and/or to to sign new records inserted via nsupdate, then
  406. named must have access to the HSM PIN. This can be accomplished
  407. by placing the PIN into the openssl.cnf file (in the above
  408. examples,
  409. <filename>/opt/pkcs11/usr/ssl/openssl.cnf</filename>).</para>
  410. <para>The location of the openssl.cnf file can be overridden by
  411. setting the OPENSSL_CONF environment variable before running
  412. named.</para>
  413. <para>Sample openssl.cnf:</para>
  414. <programlisting>
  415. openssl_conf = openssl_def
  416. [ openssl_def ]
  417. engines = engine_section
  418. [ engine_section ]
  419. pkcs11 = pkcs11_section
  420. [ pkcs11_section ]
  421. PIN = <replaceable>&lt;PLACE PIN HERE&gt;</replaceable>
  422. </programlisting>
  423. <para>This will also allow the dnssec-* tools to access the HSM
  424. without PIN entry. (The pkcs11-* tools access the HSM directly,
  425. not via OpenSSL, so a PIN will still be required to use
  426. them.)</para>
  427. <!--
  428. If the PIN is not known, I believe the first time named needs the
  429. PIN to open a key, it'll ask you to type in the PIN, which will be
  430. a problem because it probably won't be running on a terminal
  431. -->
  432. <warning>
  433. <para>Placing the HSM's PIN in a text file in
  434. this manner may reduce the security advantage of using an
  435. HSM. Be sure this is what you want to do before configuring
  436. OpenSSL in this way.</para>
  437. </warning>
  438. </sect2>
  439. <!-- TODO: what is alternative then for named dynamic re-signing? -->
  440. <!-- TODO: what happens if PIN is not known? named will log about it? -->
  441. </sect1>