Files in the top-level directory from the latest check-in
- example_conf
- src
- build.conf.lua
- build.sh
- license.txt
- mactl.sh
- mailapi.dlh
- mailapi_mod.lua
- mas_dovecot.lua
- mas_exim.lua
- mas_exim_auth.lua
- Readme.txt
- setup.sh
mailapi
=======
The mailapi is a central user management, which is controlled by
http rpc calls and connects dovecot and exim.
A resp (REdis Serialization Protocol) server (>2.0) is used for storage: valkey, redict, ...
Read and write operations can be on different nodes.
Components
==========
- mailapi_mod.lua -> core module
- mailapi.dlh -> web integration for dlh server
- mas_dovecot.lua -> dovecot auth proxy
- mas_exim.lua -> exim socket server
- mas_exim_auth.lua -> exim auth socket server
Requirements
============
- osn -> tcp/socket implementation: https://holmeinbuch.de/repo/osn/
-> can be replaced by other dlh.runServer (luaposix/luasocket/cqueues)
- crcypt -> uses libgcrypt for hash and en/decrypt: https://holmeinbuch.de/repo/crypt/
- cjson (dkjson, ...) -> both work, other json implementations for lua might work as well
- dlh -> dynamic lua hypertext (application server): https://holmeinbuch.de/repo/dlh/
- log -> logger table (e.g. https://holmeinbuch.de/repo/log/)
- resp -> resp module: https://holmeinbuch.de/repo/resp/
- resp server (>2.0)
- apache2/nginx/... in front of dlh -> recommended
- For rebuild of the components build & tool are required
( https://holmeinbuch.de/repo/build/ https://holmeinbuch.de/repo/tool/ )
API authentication
==================
A request is send from a client with a user and contains:
- user: admin@example.com (full email address) / password
-> a user can be restricted to a client
- client: any identifier / password
-> a client can be restriced to an IP address.
- rid: is a numeric counter, that needs to be raised on every request (max. 16bit)
attributes structure
====================
The authenticated user can change attributes, depending on his authorization.
The configuration is split into layers. Each layer has attributes, some are inherited.
- (global) config
- client
- domain
- user
Config attributes (including admin flags)
-----------------------------------------
admin_flag_config_users -> users can edit config attributes
admin_flag_global_domain_users -> users can add/del/manage all domains (and users)
-> mailbox limit is inherited a user limit can not be raised above config or domain level
admin_flag_read_mailbox_data_users -> allows to read (and resolve) mailbox_data
admin_flag_read_only_users -> query only, not allowed to change any data
admin_flag_read_pass_recv_users -> allows to read out password for recieving mail - handle with care (even forbidden to config_users)
admin_flag_read_pass_send_users -> allows to read out password for sending mail - handle with care (even forbidden to config_users)
admin_flag_read_pass_users -> allows to read out password - don't use
admin_flag_read_recipient_data_users -> allows to read (and resolve) recipient_data
case_sensitive_user -> normally users will be converted lowercase (dovecot and others will request lower case),
but as of rfc states, that the local part of the address may be case sensitive...
user_char_pattern -> RFC allows a lot of characters for the user part of the mail, to restrict more add a pattern: "-a-z0-9_."
client_list -> read only list
deny_recv -> deny recv => pass request for admin_flag_read_pass_recv_users will not be set and recipient_data will not be set
deny_send -> deny send => pass request for admin_flag_read_pass_send_users will not be set
domain_list -> read only list of all domains
domain_list_active -> read only list of active domains
domain_list_inactive -> read only list of inactive domains
domain_user_limit -> limit of user, that can be added
enable_request_method_get -> allow GET requests (instead of POST only)
mailbox_delete_command -> command to remove a mailbox from filesystem
mailbox_delete_path_min_length -> security option, so no one can try to delete "/" but has to delete at last "/path_min_length" characters
mailbox_limit -> mailbox size limit - has to be checked and interpreted by mailserver
mailbox_limit_max -> hard limit
mailbox_limit_sender -> mail address for over limit mail
mailbox_limit_subject -> subject for over limit mail
mailbox_limit_subject_warn -> subject for over limit mail in warning state
mailbox_limit_text -> mail body for over limit mail
mailbox_limit_warn -> mailbox warn size limit
mailbox_move_command -> command to move a mailbox to another domain
mailbox_path -> has to be set in config .. base path for mailboxes
mailbox_size_cache_interval -> if size is checked via command (not maildir) it is cached
mailbox_size_check_command -> command to check mailbox size (<FILENAME for file open) -> should return a number of bytes (du -bs)
mailbox_type -> supported: mbox/maildir
online -> "main power switch"
password_condition -> is an array of lua patterns against the passwords ( https://www.lua.org/manual/5.4/manual.html#6.4.1 )
password_gen_charset -> charset of generated password (default set exists)
password_gen_force -> passwords cannot be set, but will be generated (and returned once)
password_gen_length -> lenght of generated password, if set empty or forced
password_min_length -> minimum length of a user/client password
send_auth_fail_reason_ips -> if a client auth request fails, the reason will be logged, but "unknown error" is returned.
client ips in the list will receive the reason in the error message.
Client attributes
-----------------
active -> read only -> active, if pass is set
pass -> client password (write only, if not admin_flag_read_pass_users)
ip -> may be set to restrict the client on a static IP
Domain attributes
-----------------
active -> on/off switch for domain
admin_users -> users, that are allowed to add/del/manage users of this domain
-> in sync with user/admin_domains
alias -> ALL mailboxes will be resolved on this alias domain
catchall -> catch all mailbox name (empty for no catch all)
created -> read_only time of domain creation
deny_recv -> deny recv => pass request for admin_flag_read_pass_recv_users will not be set and recipient_data will not be set
deny_send -> deny send => pass request for admin_flag_read_pass_send_users will not be set
dkim_key -> dkim (private) key > openssl genrsa 2048
dkim_selector -> dkim selector > cat DKIM_KEY | openssl rsa -pubout -outform PEM
domain_user_limit -> limit of user, that can be added
mailbox_limit -> inherited from config, if not set
mailbox_limit_max -> hard limit
mailbox_limit_warn -> inherited from config, if not set
mailbox_path -> path for domain mails - (default, if not set: "/${(config) mailbox_path}/${DOMAIN}")
mailbox_type -> inherited from config, if not set
password_gen_force -> passwords cannot be set, but will be generated (and returned once)
user_list -> read only list of all users
user_list_active -> read only list of active users
user_list_inactive -> read only list of inactive users
User attributes
---------------
active -> on/off switch for user
admin_domains -> domains, on that this user is allowed to add/del/manage users
-> in sync with domain/admin_users
admin_flags -> flag names for config flags
-> in sync with config_admin_flag_*_users
aliases -> array of aliases
autore_active -> read only, if autoresponder is active
autore_end -> end time (%Y%m%d) of autoresponder (empty if no end or not active)
autore_reply_as -> mail sender
autore_start -> start time of autoresponder (set only if not started yet)
autore_subject -> mail subject
autore_text -> mail body
created -> read_only time of user creation
deny_recv -> deny recv => pass request for admin_flag_read_pass_recv_users will not be set and recipient_data will not be set
deny_send -> deny send => pass request for admin_flag_read_pass_send_users will not be set
internal_alias_from_list -> read_only list of alias from
last_access -> read only -> may be set on mailbox access / send mail
mailbox -> 1/0 user has mailbox or alias/api only
mailbox_data -> special attribute (read only mailbox data for imap/pop server) returns mailbox size, (over) limit data and mailbox path
mailbox_limit -> inherited from domain, if not set
mailbox_limit_warn -> inherited from domain, if not set
mailbox_path -> path for user mails - (default, if not set: "/${(domain) mailbox_path}/${USER}")
mailbox_size -> current (cached) size of the mailbox
mailbox_type -> inherited from domain, if not set
pass -> user password (write only, if not admin_flag_read_pass_users - if user is inactive, pass is not set, but pass_raw)
-> on read_pass_recv / read_pass_send pass will only return, if not denied (then pass_raw is added)
recipient_data -> special attribute (read only recipient data for mailserver) returns a full resolved recipient list (combination of mailbox paths and aliases)
-> if user not active or deny_recv no recipient_data will be returned (but recipient_data_raw will be set with the data)
restricted_clients -> restrict api access only from these clients.
API calls
=========
HTTPS (POST) Request
--------------------
request=JSON_OBJECT
hash=HMAC_HASH
(form url encoded)
JSON_OBJECT:
------------
Required:
---------
ruser = "user@domain"
rhash_algo = "sha1|sha256|sha512|blake2s_256|blake2b_256|blake2b_512"
rhash_armor = "x|b|u" (hex|base64|base64url)
rclient = "client_name"
rid = REQUEST_ID => increasing number max 16bit
action = "add|del|get|set|mov"
Optional:
---------
object = "[user@]domain|client@"
-> a client object ends with "@" to be able to differenciate from a domain
attributes = -> see sections above
values = "string" | number | ["+|-", "string", "string", "+|-", ..]
HMCA_HASH:
----------
The hash uses the rhash_algo with the rhash_armor which are
defined in the json object.
hmac: "$client_pass$user_pass" (concatenated without separator)
Example:
--------
User active:
action = get
object = user@example.com
attributes = ["active"]
=> {"status": 1, "data": {}}
-> active may be 1 or 0 (inactive), if exists
FAIL=> {"status": 0, "error": {"message": "ERROR"}}
(no, does not exist, let's create)
Create user:
action = add
object = user@example.com
=> {"status": 1, "data": {}}
FAIL=> {"status": 0, "error": {"message": "ERROR"}}
Set user attributes:
action = set
object = user@example.com
attributes = ["pass", "mailbox", "aliases"]
values = ["eXample01", 1, ["alias1@example.com", "alias2@example.com"]]
=> {"status": 1, "data": {}}
FAIL=> {"status": 0, "error": {"message": "ERROR"}}
Get user attributes:
action = get
object = user@example.com
attributes = ["mailbox", "aliases"]
=> {"status": 1, "data": {"mailbox": 1, "aliases": ["alias1@example.com", "alias2@example.com"]}}
FAIL=> {"status": 0, "error": {"message": "ERROR"}}
Special request move user:
action = mov
object = user@example.com
attributes = ["dest", "redirect_mails"]
values = ["user@example2.com", 1]
Mail server special request
===========================
mail server users should have these admin_flags:
"global_domain" "read_only" "read_data" "read_pass"
smtp server
-----------
action = "get"
attributes = {"recipient_data"} (requires admin_flag "read_recipient_data")
[values = {"limit_mail"}|{"update_last_access"}|{"local_only"}]
returns a complete resolved mailpath:
recipient_data = "/home/user/.Maildir, alias@otherdomain.example.com"
[limit_subject = "Your mailbox gets over limit"] (in case of limit_warn)
[limit_mail = 1] (No user warn limit info was sent yet)
or if mailbox is over limit:
recipient_data = "alias@otherdomain.example.com" (without user mailbox)
limit_over_limit = 1
limit_subject = "Your mailbox is over limit"
[limit_mail = 1] (No user over limit info was sent yet)
if the "limit_mail" value is set, on the first hit of the warn/limit mark
the limit mail data is returned as well:
limit_sender = "postmaster@userdomain.example.com"
limit_text = "Mailbox full body"
--
action = "get"
attributes = {"autore_active"[, "autore_reply_as", "autore_subject", "autore_text"]}
[values = {"sender@example.com"}]
returns:
[autore_active = 1]
--
if "update_last_access" value is given, the "last_access" of the user is set.
if "local_only" value is given, only local mailbox(es) will be returned.
if "sender" value is given, "sender" is added to an internal list and
the next call with these "sender" won't return an "autore_active" result.
(list reset is on reset of "autore_start" or if "autore_end" is reached)
imap/pop3 server
----------------
action = "get"
attributes = {"mailbox_data"} (requires admin_flag "read_mailbox_data")
[values = {"update_last_access"}]
returns:
[mailbox_data = "/home/user/.Maildir"]
[mailbox_data_limit = "1M"]
[mailbox_data_limit_raw = "1024"]
[mailbox_data_type = "%s"]
[limit_over_limit = 1]
[limit_subject = ""]
--
if "update_last_access" value is given, the "last_access" of the user is set.