ARPA2 ID library
As of 2019-10-03 development has moved to https://gitlab.com/arpa2/liba2common
This repository contains command-line tools and libraries to work with ARPA2 Identities, Selectors and ACLs.
- liba2id - library to parse and match A2IDs
- a2acl - command-line tool to test if communication between two A2IDs is allowed
- liba2acl - library to work with A2ACLs
- a2idmatch - command-line tool to test if an A2ID matches a selector
- Libraries are POSIX C89 without extra dependencies
- A C89 compiler
- CMake >= 3.3
- Any POSIX-compliant system
$ git clone https://github.com/arpa2/libarpa2service.git $ cd libarpa2service/build $ cmake .. $ make $ sudo make install $ sudo ldconfig
Using the libraries
After the libraries are installed, make sure to include
arpa2/a2acl.h in your source file and hint the compiler to include the a2id or
a2acl library with the -l flag.
$ cc -la2id yourcode.c
For further documentation please refer to ARPA2 Identifier and ACL introduction and the manpages:
NOTE: the following example can be easily replayed by using the docker-demo:git clone https://github.com/arpa2/docker-demo.git cd docker-demo/demo-acl docker build -t a2acl . docker run -it a2acl bash cd /root/arpa2
We are going to define the following policy:
- Whitelist all communication from anyone @ashop.example.com to email@example.com
- Blacklist all communication from anyone @ashop.example.com to firstname.lastname@example.org or any other alias of email@example.com
- Abandon all communication from anyone @.tk to firstname.lastname@example.org (or any alias)
- Blacklist all communication from anyone to email@example.com (or any alias)
The above ACL policy is notated in the text file
demopolicy as follows:
@ashop.example.com firstname.lastname@example.org %W +ashop %B + @.tk email@example.com %A + @. firstname.lastname@example.org %B +
Each line in the file contains one ACL rule. A rule is a triplet of a remote selector, a local ID in core form, and one (or more) ACL segments. So the first rule can be broken down as follows:
- the remote selector:
- the local ID in core form:
- the ACL segments:
Each ACL segment consists of the first letter of the list and an alias,
+ashop, respectively. The alias must be combined with the local ID and would
yield email@example.com. This holds for each ACL segment. The full meaning
of the first rule is that any communication from remote selector
firstname.lastname@example.org is whitelisted and any
communication from remote selector
or any other alias of email@example.com is blacklisted.
A couple of other things to note. Order is significant and the first match wins,
so if a rule matches, subsequent rules are not evaluated. Second,
any user at any subdomain of the
.tk top-level domain. Third,
@. is the
catch-all selector, matching any user at any domain. Fourth, the
+ alias in an
ACL segment matches any alias. And at last, the combination of a remote selector
and the local ID in core form must be unique. As said, for a detailed
explanation see ARPA2 Identifier and ACL introduction.
XXX The current rule syntax closely resembles the internal storage format which is fine for a machine, but not for human beings. At the same time it is vital that no mistakes are made, so expect a new import format somewhere in the future. Possibly something like the following (open for suggestions):
W @ashop.example.com firstname.lastname@example.org B @ashop.example.com email@example.com A @.tk firstname.lastname@example.org B @. email@example.com
The policy can be used with a2acl(1) by testing different combinations of sender and receiver. The first test will check whether communication between firstname.lastname@example.org and email@example.com is allowed according to the above policy.
$ a2acl demopolicy firstname.lastname@example.org email@example.com B
The result of this test is that communication between these two A2IDs is
blacklisted. The first letter of the list this pair is listed on is echoed back,
in this case the
B of blacklist because it matches the second rule.
$ a2acl demopolicy firstname.lastname@example.org email@example.com W
$ a2acl demopolicy firstname.lastname@example.org email@example.com B
This matches the fourth rule and the result is that this communication pair is blacklisted.
$ a2acl demopolicy firstname.lastname@example.org email@example.com A
This matches the third rule and communication between these two IDs is abandoned.
Remember that you can easily execute these examples yourself by using the docker-demo as noted at the beginning of this chapter.
This tool is created to easily experiment with A2IDs and A2ID Selectors. This way you can test whether a selector matches an ID.
For example, test whether the A2ID "firstname.lastname@example.org" matches the A2ID selector "@example.com".
$ a2idmatch email@example.com @example.com MATCH
Or test whether the A2ID "firstname.lastname@example.org" matches the A2ID selector "@.example.com".
$ a2idmatch email@example.com @.example.com MISMATCH
Copyright (c) 2018, 2019 Tim Kuijsten
Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted, provided that the above copyright notice and this permission notice appear in all copies.
THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.