Commit 08c67b5b authored by Evan Hunt's avatar Evan Hunt
Browse files

[master] improved native-pkcs11 doc

3728.	[doc]		Expanded native-PKCS#11 documentation,
			specifically pkcs11: URI labels. [RT #35287]
parent e5f9fa7e
3728. [doc] Expanded native-PKCS#11 documentation,
specifically pkcs11: URI labels. [RT #35287]
3727. [func] The isc_bitstring API is no longer used and
has been removed from libisc. [RT #35284]
......
......@@ -151,9 +151,32 @@
<term>-l <replaceable class="parameter">label</replaceable></term>
<listitem>
<para>
Specifies the label of the key pair in the crypto hardware.
The label may be preceded by an optional OpenSSL engine name,
separated by a colon, as in "pkcs11:keylabel".
Specifies the label for a key pair in the crypto hardware.
</para>
<para>
When <acronym>BIND</acronym> 9 is built with OpenSSL-based
PKCS#11 support, the label is an arbitrary string that
identifies a particular key. It may be preceded by an
optional OpenSSL engine name, followed by a colon, as in
"pkcs11:<replaceable>keylabel<replaceable>".
</para>
<para>
When <acronym>BIND</acronym> 9 is built with native PKCS#11
support, the label is a PKCS#11 URI string in the format
"pkcs11:<option>keyword</option>=<replaceable>value</replaceable><optional>;<option>keyword</option>=<replaceable>value</replaceable>;...</optional>"
Keywords include "token", which identifies the HSM; "object", which
identifies the key; and "pin-source", which identifies a file from
which the HSM's PIN code can be obtained. The label will be
stored in the on-disk "private" file.
</para>
<para>
If the label contains a
<option>pin-source</option> field, tools using the generated
key files will be able to use the HSM for signing and other
operations without any need for an operator to manually enter
a PIN. Note: Making the HSM's PIN accessible in this manner
may reduce the security advantage of using an HSM; be sure
this is what you want to do before making use of this feature.
</para>
</listitem>
</varlistentry>
......@@ -437,7 +460,8 @@
<refentrytitle>dnssec-signzone</refentrytitle><manvolnum>8</manvolnum>
</citerefentry>,
<citetitle>BIND 9 Administrator Reference Manual</citetitle>,
<citetitle>RFC 4034</citetitle>.
<citetitle>RFC 4034</citetitle>,
<citetitle>The PKCS#11 URI Scheme (draft-pechanec-pkcs11uri-13)</citetitle>.
</para>
</refsect1>
......
......@@ -485,6 +485,13 @@ $ <userinput>dnssec-keyfromlabel -l sample-ksk -f KSK example.net</userinput>
different keylabel, a smaller key size, and omitting "-f KSK"
from the dnssec-keyfromlabel arguments:
</para>
<para>
(Note: When using OpenSSL-based PKCS#11 the label is an arbitrary
string which identifies the key. With native PKCS#11, the label is
a PKCS#11 URI string which may include other details about the key
and the HSM, including its PIN. See
<xref linkend="man.dnssec-keyfromlabel"/> for details.)
</para>
<screen>
$ <userinput>pkcs11-keygen -b 1024 -l sample-zsk</userinput>
$ <userinput>dnssec-keyfromlabel -l sample-zsk example.net</userinput>
......@@ -595,7 +602,7 @@ $ <userinput>dnssec-signzone -E '' -S example.net</userinput>
<para>
Placing the HSM's PIN in a text file in this manner may reduce the
security advantage of using an HSM. Be sure this is what you want to
do before configuring OpenSSL in this way.
do before configuring the system in this way.
</para>
</warning>
</sect2>
......
This diff is collapsed.
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment