man samba-tool: user keytrust

This documentation anticipates changes that will occur over the next
~20 commits.

Signed-off-by: Douglas Bagnall <douglas.bagnall@catalyst.net.nz>
Reviewed-by: Gary Lockyer <gary@catalyst.net.nz>

diff --git a/docs-xml/manpages/samba-tool.8.xml b/docs-xml/manpages/samba-tool.8.xml
index 1189ca4e27aa277876195e306fdc8106d5424e6d..922b7884d4713fb850c4ac866fd3a8bb0f6d8181 100644 (file)
--- a/docs-xml/manpages/samba-tool.8.xml
+++ b/docs-xml/manpages/samba-tool.8.xml
@@ -4303,6 +4303,96 @@ in use.</para>
        <para>View the assigned authentication silo for user.</para>
 </refsect3>
 
+<refsect2>
+       <title>user keytrust</title>
+       <para>Manage Key Credential Links for a user.</para>
+       <para>This can populate, describe or delete  msDS-KeyCredentialLink attributes.</para>
+</refsect2>
+
+
+<refsect3>
+<title>user keytrust add <replaceable>username</replaceable>  <replaceable>public-key-or-certificate</replaceable>[options]</title>
+<para>Add a key-credential-link, which is a linked attribute that holds a public key in a binary field.
+</para>
+<para>
+  The second argument is a filename that should refer to a 2048 bit RSA key (or a certificate containing that key) in PEM or DER format. By default the encoding format will be detected automatically, but you can attempt to override this with <constant>--encoding</constant> option. Other types of public key are not supported, though the <constant>--force</constant> option can be used to add a non-2048 bit key.
+</para>
+
+<variablelist>
+<!--Options-->
+         <varlistentry>
+           <term>--link-target=DN</term>
+           <listitem><para>link to this DN (default: the user's DN)</para></listitem>
+         </varlistentry>
+         <varlistentry>
+           <term>--encoding=ENCODING</term>
+           <listitem><para>Key format, either <constant>pem</constant>,  <constant>der</constant>, or  <constant>auto</constant>. The default is  <constant>auto</constant>, which is likely to detect the correct format in all circumstances.</para></listitem>
+         </varlistentry>
+         <varlistentry>
+           <term>--force</term>
+           <listitem><para>proceed with operations that seems ill-fated</para></listitem>
+         </varlistentry>
+</variablelist>
+</refsect3>
+
+<refsect3>
+
+<title>user keytrust delete <replaceable>username</replaceable> [options]</title>
+<para>Delete a key-credential-link.
+</para>
+<para>The link to be deleted can be selected in a number of ways. <constant>--all</constant> will delete all key credential links for the user (often there will only be one). The  <constant>--link-target</constant> option selects a key credential link based on the DN targeted by the link. The <constant>--fingerprint</constant> option selects a link to delete based on the key fingerprint. This is the SHA256 of the DER-encoded  key material, expressed as hex-pairs separated by colons. See <constant>user keytrust view</constant> to get a list of links and their fingerprints.
+</para>
+
+<para>If more than one of <constant>--link-target</constant>, <constant>--fingerprint</constant>, and <constant>--all</constant> are used, links matched by any of them will be deleted.
+</para>
+
+<para>The <constant>--dry-run</constant> option will prevent links from being deleted, and instead indicate what would happen if it was omitted.
+</para>
+
+<variablelist>
+<!--Options-->
+         <varlistentry>
+           <term>--link-target=DN</term>
+           <listitem><para>Delete this key credential link (a DN)</para></listitem>
+         </varlistentry>
+         <varlistentry>
+           <term>--fingerprint=HH:HH:..</term>
+           <listitem><para>Delete the key credential link with this key fingerprint</para></listitem>
+         </varlistentry>
+         <varlistentry>
+           <term>--all</term>
+           <listitem><para>Delete all key credential links</para></listitem>
+         </varlistentry>
+         <varlistentry>
+           <term>-n, --dry-run</term>
+           <listitem><para>Do nothing but print what would happen</para></listitem>
+         </varlistentry>
+</variablelist>
+
+</refsect3>
+<refsect3>
+
+<title>user keytrust view <replaceable>username</replaceable> [options]</title>
+
+<para>View a user's key credential links. This can be used to find a link's fingerprint and target DN for <title>user keytrust delete</title>.
+
+The <constant>--verbose</constant> includes more, probably useless, information.
+</para>
+
+<variablelist>
+<!--Options-->
+         <varlistentry>
+           <term>-h, --help</term>
+           <listitem><para>show this help message and exit</para></listitem>
+         </varlistentry>
+         <varlistentry>
+           <term>-v, --verbose</term>
+           <listitem><para>Be verbose</para></listitem>
+         </varlistentry>
+</variablelist>
+</refsect3>
+
+
 <refsect2>
        <title>vampire [options] <replaceable>domain</replaceable></title>
        <para>Join and synchronise a remote AD domain to the local server.