MACPolicyIPAddressJail [FreeBSD WIKI]

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== MACPolicyIPAddressJail ======
  * Student: **[[/ShivankGarg|Shivank Garg]]** (shivank@%%FreeBSD%%.org)
  * Mentor: **[[/BjoernZeeb|Bjoern A. Zeeb]]** (bz@%%FreeBSD%%.org)

===== MAC Policy on IP Address in Jail =====

IP address access control policy - [[https://summerofcode.withgoogle.com/projects/#5191863366057984|Google Summer of Code 2019 project page]]

===== Differential revisions Submitted =====

^  Differential  ^  Title  ^  Status  ^
| [[https://reviews.freebsd.org/D20967|D20967]] | mac_ipacl module, tests and man page | Revision is **Accepted** and Ready to land ✔ |

=== Idea of the project: ===
Using **VNET** in %%FreeBSD%% jails, the root of the jail can set IP addresses of their will, however, sysadmins may need to limit these privileges for different purposes. With a MAC framework, the root of the host can restrict root of the jail to set the desired IP address. Currently, there is no MAC policy module for such restriction, implying these rules are written in the kernel itself. The project is focused on writing a MAC module for **The %%TrustedBSD%% MAC framework** to enable easy management of privilege(configuring the network stack) restriction of jail.

=== Features: mac_ipacl ===
The features of the **mac_ipacl** policy module are-
  * Host is able to limit the restrict the desired jail to particular IP addresses(or subnets).
  * Host can the restrict the certain jail from setting certain IP address or prefixes.
  * Host can enforce the policy for a particular network interface(or all interfaces) for a jail.
  * Policy is applicable on both IPv4 and IPv6 addresses.
  * sysctl interface for tuning the mac_ipacl module.

===== Project description & Implementation =====

The mac_ipacl module is a loadable kernel module. It implements mac checks in netinet/in.c and netinet6/in6.c to check the IP addresses requested by jail. The idea to implement these checks at these places comes from the fact that SIOCAIFADDR(for IPv4) and SIOCAIFADDR_IN6(for IPv6) ioctl handlers are defined for adding the IP addresses to an interface. This is used by ifconfig(in userspace) for setting the IP address.
MAC framework act as multiplexer between the netinet and the module. The requested IP and the credentials are checked with the rules in mac_ipacl and output is returned accordingly to netinet. The module can be tuned with various sysctl and similarly, policy rules are also be defined with sysctl.

===== Using the mac_ipacl policy module =====
For a detailed description on using the mac_ipacl module and the examples, please refer the mac_ipacl(4) man page.
One can also refer to test-framework(in /usr/tests/sys/mac/ipacl) for wide variety of examples on policy defined for ipv4 and ipv6 addresses.

===== Work Done =====

=== Check the Phabricator link for the review ===
  * https://reviews.freebsd.org/D20967

=== Please check this branch for the code ===
  * https://github.com/shivankgarg98/freebsd/tree/shivank_MACPolicyIPAddressJail

=== Comparison of the files changed from FreeBSD Master(for net changes that I have made) ===
  * https://github.com/freebsd/freebsd/compare/master...shivankgarg98:shivank_MACPolicyIPAddressJail

The final deliverables from this project include -

  * A loadable kernel module - [[https://github.com/shivankgarg98/freebsd/tree/shivank_MACPolicyIPAddressJail/sys/security/mac_ipacl|mac_ipacl in sys/security/mac_ipacl]]
  * ATF tests for the module in [[https://github.com/shivankgarg98/freebsd/tree/shivank_MACPolicyIPAddressJail/tests/sys/mac/ipacl|tests/sys/mac/ipacl]]
  * A man for this new mac module - mac_ipacl.4 in [[https://github.com/shivankgarg98/freebsd/blob/shivank_MACPolicyIPAddressJail/share/man/man4/mac_ipacl.4|share/man/man4/mac_ipacl.4]]
Also, for writing the mac_ipacl module, new checks and functions are also introduced at various places in kernel.

Regular weekly status reports were posted to the https://lists.freebsd.org/mailman/listinfo/soc-status list.

**Download the full patch** -  **[[https://reviews.freebsd.org/file/data/fum2molk2rfuyfoauahm/PHID-FILE-4jsp7skwhoc4ltkhosqg/D20967.diff]]**

===== Test Suite =====

The tests for **mac_ipacl** are written using atf-framwork:
Tests(in src code) for ipacl can be found in /usr/src/tests/sys/mac/ipacl
Now, we can generate a test report using kyua report. It parses the result file and generates a plain-text report.  We can also print a detailed report using --verbose flag.

Compile and install tests using:

$ make && make install

Then, Test the module using following command:

$ kyua test -k /usr/tests/sys/mac/ipacl/Kyuafile

$ kyua report --verbose

===== Future Work =====

Ideas I came up with while working on the Google Summer of Code project,
which could be done in the future:

  * Add checks for hardware (ethernet) addresses.
  * Improve the management interface from long sysctl strings to something more user-friendly.
  * If tuned with sysctl, make the ipacl policy also apply to the base system (by default, it should only be applied to jails).

===== Useful links =====
  * [[https://www.freebsd.org/doc/en_US.ISO8859-1/books/arch-handbook/mac-synopsis.html|The TrustedBSD MAC Framework]]