From b94ffb988b33e5b84482a469d9e94b8a1ea00afe Mon Sep 17 00:00:00 2001 From: Wiebe Cazemier Date: Sat, 4 Nov 2023 10:05:40 +0100 Subject: [PATCH] Add documentation about X509 client verification --- man/flashmq.conf.5 | 22 +++++++++++++++++++++- man/flashmq.conf.5.dbk5 | 41 +++++++++++++++++++++++++++++++++++++++++ man/flashmq.conf.5.html | 41 +++++++++++++++++++++++++++++++++++++++++ 3 files changed, 103 insertions(+), 1 deletion(-) diff --git a/man/flashmq.conf.5 b/man/flashmq.conf.5 index 478d43f3..926f1a4e 100644 --- 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 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 index f691a0cc..bd9f713b 100644 --- a/man/flashmq.conf.5.dbk5 +++ b/man/flashmq.conf.5.dbk5 @@ -572,6 +572,40 @@ + + + /foobar/client_authority.crt + + + 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 will require the listener to be TLS. + + + + + + /foobar/dir_with_certificates + + + 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 will require the listener to be TLS. + + + + + + true/false + + + When using X509 client authentication with or , the username will not be checked with a user database or a plugin by default. Set this option to true to override that. + + + + true/false @@ -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 index 5f203649..2cf32e28 100644 --- a/man/flashmq.conf.5.html +++ b/man/flashmq.conf.5.html @@ -625,6 +625,40 @@

+ + +
client_verification_ca_file /foobar/client_authority.crt#
+
+

+ 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 client_verification_ca_dir will require the listener to be TLS. +

+
+ + + +
client_verification_ca_dir /foobar/dir_with_certificates#
+
+

+ 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 client_verification_ca_file will require the listener to be TLS. +

+
+ + + +
client_verification_still_do_authn true/false#
+
+

+ When using X509 client authentication with client_verification_ca_file or client_verification_ca_dir, the username will not be checked with a user database or a plugin by default. Set this option to true to override that. +

+
+ +
haproxy true/false#
@@ -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