Add documentation about X509 client verification

halfgaar · Nov 4, 2023 · b94ffb9 · b94ffb9
1 parent de2aa39
commit b94ffb9
Show file tree

Hide file tree

Showing 3 changed files with 103 additions and 1 deletion.
diff --git a/man/flashmq.conf.5 b/man/flashmq.conf.5
@@ -5,7 +5,7 @@
 \\$2 \(la\\$1\(ra\\$3
 ..
 .if \n(.g .mso www.tmac
-.TH flashmq.conf 5 "8 September 2023" "" ""
+.TH flashmq.conf 5 "4 November 2023" "" ""
 .SH NAME
 flashmq.conf \- FlashMQ configuration file format
 .SH SYNOPSIS
@@ -275,6 +275,19 @@ Specifying a chain makes the listener SSL, and also requires the \*(T<\fBprivkey
 \*(T<\fBprivkey\fR\*(T> \fI/foobar/server.key\fR 
 Specifying a private key makes the listener SSL, and also requires the \*(T<\fBfullchain\fR\*(T> to be set.
 .TP 
+\*(T<\fBclient_verification_ca_file\fR\*(T> \fI/foobar/client_authority.crt\fR 
+Clients can be authenticated using X509 certificates, and the username taken from the CN (common name) field. Use this directive to specify the certificate authority you trust.
+
+Specifying this or \*(T<\fBclient_verification_ca_dir\fR\*(T> will require the listener to be TLS.
+.TP 
+\*(T<\fBclient_verification_ca_dir\fR\*(T> \fI/foobar/dir_with_certificates\fR 
+Clients can be authenticated using X509 certificates, and the username taken from the CN (common name) field. Use this directive to specify the dir containing certificate authorities you trust.
+
+Specifying this or \*(T<\fBclient_verification_ca_file\fR\*(T> will require the listener to be TLS.
+.TP 
+\*(T<\fBclient_verification_still_do_authn\fR\*(T> \fItrue/false\fR 
+When using X509 client authentication with \*(T<\fBclient_verification_ca_file\fR\*(T> or \*(T<\fBclient_verification_ca_dir\fR\*(T>, the username will not be checked with a user database or a plugin by default. Set this option to \*(T<true\*(T> to override that.
+.TP 
 \*(T<\fBhaproxy\fR\*(T> \fItrue/false\fR 
 Setting the listener to haproxy makes it expect the PROXY protocol and set client source address to the original client. Make sure this listener is private / firewalled, otherwise anybody can set a different source address.
 
@@ -298,6 +311,13 @@ listen {
   # default = 8883
   port 8883
 }
+listen {
+  protocol mqtt
+  fullchain /foobar/server.crt
+  privkey /foobar/server.key
+  client_verification_ca_file /foobar/client_authority.crt
+  client_verification_still_do_authn false
+}
 listen {
   protocol mqtt
   inet_protocol ip4

diff --git a/man/flashmq.conf.5.dbk5 b/man/flashmq.conf.5.dbk5
@@ -572,6 +572,40 @@
           </para>
         </listitem>
       </varlistentry>
+
+      <varlistentry xml:id="client_verification_ca_file">
+        <term><option>client_verification_ca_file</option> <replaceable>/foobar/client_authority.crt</replaceable></term>
+        <listitem>
+          <para>
+            Clients can be authenticated using X509 certificates, and the username taken from the CN (common name) field. Use this directive to specify the certificate authority you trust.
+          </para>
+          <para>
+            Specifying this or <option>client_verification_ca_dir</option> will require the listener to be TLS.
+          </para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry xml:id="client_verification_ca_dir">
+        <term><option>client_verification_ca_dir</option> <replaceable>/foobar/dir_with_certificates</replaceable></term>
+        <listitem>
+          <para>
+            Clients can be authenticated using X509 certificates, and the username taken from the CN (common name) field. Use this directive to specify the dir containing certificate authorities you trust.
+          </para>
+          <para>
+            Specifying this or <option>client_verification_ca_file</option> will require the listener to be TLS.
+          </para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry xml:id="client_verification_still_do_authn">
+        <term><option>client_verification_still_do_authn</option> <replaceable>true/false</replaceable></term>
+        <listitem>
+          <para>
+            When using X509 client authentication with <option>client_verification_ca_file</option> or <option>client_verification_ca_dir</option>, the username will not be checked with a user database or a plugin by default. Set this option to <literal>true</literal> to override that.
+          </para>
+        </listitem>
+      </varlistentry>
+
       <varlistentry xml:id="haproxy">
         <term><option>haproxy</option> <replaceable>true/false</replaceable></term>
         <listitem>
@@ -606,6 +640,13 @@
   # default = 8883
   port 8883
 }
+listen {
+  protocol mqtt
+  fullchain /foobar/server.crt
+  privkey /foobar/server.key
+  client_verification_ca_file /foobar/client_authority.crt
+  client_verification_still_do_authn false
+}
 listen {
   protocol mqtt
   inet_protocol ip4

diff --git a/man/flashmq.conf.5.html b/man/flashmq.conf.5.html
@@ -625,6 +625,40 @@
           </p>
         </dd>
 
+
+
+        <dt id="client_verification_ca_file"><code class="option">client_verification_ca_file</code> <code class="replaceable">/foobar/client_authority.crt</code><a class="hash-anchor" href="#client_verification_ca_file">#</a></dt>
+        <dd>
+          <p>
+            Clients can be authenticated using X509 certificates, and the username taken from the CN (common name) field. Use this directive to specify the certificate authority you trust.
+          </p>
+          <p>
+            Specifying this or <code class="option">client_verification_ca_dir</code> will require the listener to be TLS.
+          </p>
+        </dd>
+
+
+
+        <dt id="client_verification_ca_dir"><code class="option">client_verification_ca_dir</code> <code class="replaceable">/foobar/dir_with_certificates</code><a class="hash-anchor" href="#client_verification_ca_dir">#</a></dt>
+        <dd>
+          <p>
+            Clients can be authenticated using X509 certificates, and the username taken from the CN (common name) field. Use this directive to specify the dir containing certificate authorities you trust.
+          </p>
+          <p>
+            Specifying this or <code class="option">client_verification_ca_file</code> will require the listener to be TLS.
+          </p>
+        </dd>
+
+
+
+        <dt id="client_verification_still_do_authn"><code class="option">client_verification_still_do_authn</code> <code class="replaceable">true/false</code><a class="hash-anchor" href="#client_verification_still_do_authn">#</a></dt>
+        <dd>
+          <p>
+            When using X509 client authentication with <code class="option">client_verification_ca_file</code> or <code class="option">client_verification_ca_dir</code>, the username will not be checked with a user database or a plugin by default. Set this option to <code class="literal">true</code> to override that.
+          </p>
+        </dd>
+
+
 
         <dt id="haproxy"><code class="option">haproxy</code> <code class="replaceable">true/false</code><a class="hash-anchor" href="#haproxy">#</a></dt>
         <dd>
@@ -657,6 +691,13 @@
   # default = 8883
   port 8883
 }
+listen {
+  protocol mqtt
+  fullchain /foobar/server.crt
+  privkey /foobar/server.key
+  client_verification_ca_file /foobar/client_authority.crt
+  client_verification_still_do_authn false
+}
 listen {
   protocol mqtt
   inet_protocol ip4