add imap documentation

diff --git a/doc/antora/modules/raddb/pages/mods-available/imap.adoc b/doc/antora/modules/raddb/pages/mods-available/imap.adoc
new file mode 100644 (file)
index 0000000..7a96e38
--- /dev/null
+++ b/doc/antora/modules/raddb/pages/mods-available/imap.adoc
@@ -0,0 +1,193 @@
+
+
+
+
+= IMAP Module
+
+The `imap` module validates a users name and password against an IMAP server.
+It should be called from an `authenticate` section.
+
+The module can optionally perform a tls handshake, enabled with require_cert
+
+
+
+tls { ... }:: Configure the tls related items which control
+how FreeRADIUS connects to an IMAP server.
+
+
+.Certificate validation options
+
+Specifies how the certificate(s) presented by the
+IMAP server are validated, and which certificates
+(if any) to send to that IMAP server.
+
+The options here behave the same as the options in
+other `tls` sections in the server.
+
+
+
+certificate_file:: PEM formatted file containing the certificate we present to the IMAP server
+
+Specifies a certificate and any intermediary CAs we should send to the IMAP server.
+
+This file should usually contain the client certificate file first, then any
+intermediary signing CAs, shallowest (direct signee of the certificate_file)
+to deepest (signed directly by the root CA).
+
+
+
+ca_file:: PEM formatted file containing the chain
+to validate the IMAP server's certificate.
+
+Any certificate chain MUST be in order from server
+certificate (first in the file) to intermediary CAs (second) to
+Root CA (last in the file) as per https://tools.ietf.org/html/rfc4346#section-7.4.2[RFC 4346 Section 7.4.2] (see certificate_list)
+
+Providing a complete certificate chain here is the
+most common way of validating the certificate
+presented by an IMAP server.
+
+
+
+ca_issuer_file:: PEM formatted file containing the
+CA that signed the IMAP server's certificate.
+
+Specifies the certificate which directly signed
+the certificate presented by the IMAPs server.
+
+This configuration option can be used to prevent
+certificates passing validation which were signed
+by other intermediary CAs, or root CAs, in the
+trusted certificate chain.
+
+
+
+ca_path:: A directory containing multiple root CA certs named by their hash.
+
+See the OpenSSL documentation for more details:
+- https://www.openssl.org/docs/man1.1.0/man3/SSL_CTX_set_default_verify_paths.html
+- https://www.openssl.org/docs/man1.1.1/man1/c_rehash.html
+
+This configuration option should only be used when the IMAP server being contacted
+is not known ahead of time (using a URL from an external source), and/or the CA used
+to sign the IMAP server certificate is unknown.
+
+
+
+private_key_file:: PEM formatted file containing the private key for the specified `certificate_file`
+
+This item must be specified if `certificate_file` is being used.
+
+
+
+private_key_password:: Password used to decrypt the `private_key_file`.
+
+
+
+random_file:: Source of random data used for various cryptographic functions.
+
+
+
+check_cert:: Server certificate verification requirements.
+
+May be one of:
+
+[options="header,autowidth"]
+|===
+| Option | Description
+| `no`   | Server certificate can be signed by any CA or be self-signed.
+| `yes`  | Server certificate must be issued by one of the trusted CAs.
+|===
+
+Default is `yes`
+
+
+
+request_cert:: Options for controlling how the
+module requests TLS to the IMAP server.
+
+May be one of:
+
+[options="header,autowidth"]
+|===
+| Option | Description
+| `demand`   | Require ssl validation to accept login
+| `never`  | Do not try to establish ssl connection
+| `allow`  | Try to establish ssl connection, continue even if it cannot
+|===
+
+default is 'allow'
+
+
+
+check_cert_cn:: Server certificate CN verification requirements.
+
+May be one of:
+
+[options="header,autowidth"]
+|===
+| Option | Description
+| `no`   | Server certificate CN can be any value.
+| `yes`  | Server certificate CN matches the host in the URI.
+|===
+
+Default is `yes`
+
+
+
+extract_cert_attrs:: Extract OIDs from presented certificates as OIDs.
+
+Default is `no`
+
+
+
+uri:: URI which will be used for connecting to the IMAP server.
+
+The `imap` module uses Curl (https://curl.haxx.se/libcurl/) to implement
+the underlying mail protocols.  The URI should be in the form of:
+
+`SCHEME://IP:PORT/`
+
+
+`SCHEME` can be one of the protocols supported by Curl.
+i.e. ftp, ftps, gopher, http, https, imap, imaps, ldap, ldaps,
+    pop3, pop3s, rtsp, scp, sftp, smb, smbs, smtp, smtps.
+If no `SCHEME` is given, it defaults to `imap`.
+
+`IP` is the IP address of the server.  It can be an IPv4 address,
+IPv6 address, hostname, etc.
+
+`PORT` is optional, and will normally be chosen to be correct
+for the given `SCHEME`.
+
+For more information, see the CURL documentation at
+
+https://ec.haxx.se/cmdline/cmdline-urls
+
+
+
+timeout:: How long the module will wait before giving up on the response
+from the IMAP server.
+
+
+== Default Configuration
+
+```
+imap {
+       tls {
+#              certificate_file     = /path/to/radius.pem
+#              ca_file              = "${certdir}/cacert.pem"
+#              ca_issuer_file     = "${certdir}/caissuer.pem"
+#              ca_path              = "${certdir}"
+#              private_key_file     = /path/to/radius.key
+#              private_key_password = "supersecret"
+#              random_file          = /dev/urandom
+#              check_cert = no
+#              require_cert = allow
+#              check_cert_cn = no
+#              extract_cert_attrs = no
+       }
+       uri = "imap://192.0.20.1/"
+       timeout = 5s
+}
+```