



= 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.

If not set, then whatever libcurl has as its default will be used, which typically
will be the operating system's set of trusted CAs.  This will be visible in the debug
output when FreeRADIUS starts.



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 IMAP protocols supported by Curl.
i.e. imap, imaps.
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.



connection { .. }:: Configure how connection handles are
managed per thread.


Reusable connection handles are allocated in blocks.  These
parameters allow for tuning how that is done.

Since http requests are performed async, the settings here
represent outstanding http requests per thread.



min:: The minimum number of connection handles to
keep allocated.



max:: The maximum number of reusable connection handles
to allocate.

Any requests to allocate a connection handle beyond
this number will cause a temporary handle to be allocated.
This is less efficient than the block allocation so
`max` should be set to reflect the number of outstanding
requests expected at peak load.


cleanup_interval:: How often to free un-used connection
handles.

Every `cleanup_interval` a cleanup routine runs which
will free any blocks of handles which are not in use,
ensuring that at least `min` handles are kept.



== 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
	connection {
		reuse {
			min = 10
			max = 100
			cleanup_interval = 30s
		}
	}
}
```
