View source for Honeycomb/IETF-ACL model

= IETF-ACL model =

Honeycomb provides VPP implementation of [https://tools.ietf.org/html/draft-ietf-netmod-acl-model-08 IETF-ACL model draft 08] with following [https://git.fd.io/cgit/honeycomb/tree/v3po/api/src/main/yang/vpp-acl.yang augmentations]:

* possibility to assign ACLs to interfaces and sub-interfaces as ingress/egerss ACLs
* L2 + L3/L4 rules in one ACE, [https://jira.fd.io/browse/HONEYCOMB-233 HONEYCOMB-233]
* default action for list of ACEs (removes ambiguity when mixing deny/permit rules in one ACL, [https://jira.fd.io/browse/HONEYCOMB-246 HONEYCOMB-246])

== Translation to VPP's binary api ==

Honeycomb uses classifier API to for ingress ACLs.
Each ACE is translated to single classify table + session(s).
We plan to minimize number of classify tables [https://jira.fd.io/browse/HONEYCOMB-247 HONEYCOMB-247].

Here is short description how HC translates ACEs to classify tables and sessions.
Details can be found in Honeycomb's [https://docs.fd.io/honeycomb/1.16.12-SNAPSHOT/impl-parent/vpp-impl-parent/v3po2vpp/Readme.html documentation].

=== Configuration data ===

Configuration data for the model is stored in Honeycomb. Corresponding classify tables and sessions
are not created until control access list is assigned to an interface.

Classify tables and sessions are removed from VPP when ACL assignment is deleted.

ACLs can be shared among interfaces, but each time, new instance of classify table chain would be created in VPP.

ACLs that are assigned to an interface have to be unassigned before update/removal.

=== Operational state ===

Operational read in terms of ietf-acl model is not supported (would require storing additional metadata in vpp).
As a consequence, configuration data initialization based on operational state is not possible.

To check how ietf-acl model was translated to classify tables/session, low-level vpp-classfier model can be used.

== Current state ==

=== HC Limitations === 

* support for L4 rules is limited (each port in range mapped to one session)
* vlan tags are supported only for sub-interfaces defined as exact-match

=== VPP classier limitations ===
* uses absolute offsets (correct configuration is not possible if vlan tags or ip4 options/ip6 extensions are present)
* lack of generic api for egress ACLs (could be mirror of input_acl_set_interface + classify_table_by_interface_reply)
** L2 eggress is possible (classify_set_interface_l2_tables, but no api for read)
* L2 rules on L3 interfaces are limited (L2 table is applied in L2 path only, IP4/IP6 table only in IP4/IP6 forwarding path).
* no support for number ranges (would be nice to have for ports - but we need to combine it with all other rules)

== Phase 0 ==

=== Features ===
* ACEs are ordered (translated to classify tables/sessions in a way that preserves the order)
* one or more ACLs can be assigned to single interface (in ordered way)
* ACLs can be shared betwen interfaces
* ACLs can be assigned as ingress/egress on any interface or sub-interface (as long as vpp provides support)
* ACLs can mix deny/permit ACEs, deny is default action if packet does not match any rule defined by ACEs
* single ACE can define mac/ip addresses with masks, tcp/udp port ranges, etc. (full list of features with exact meaning defines the ietf-acl model) or combination of those (ace-eth, ace-ip, ace-eth+ace-ip)
* configuration data tree provides CRUD operations for ACLs (UD only for unassigned acls)

=== Limitations ===
* IPv6 packets with extension headers or IPv4 packets with options might not be properly not filtered
* only plain sub-interfaces and sub-interfaces configred as exact-match are supported
* ACEs are stateless (i.e. not reflexive)
* L2 rules on L3 interfaces are supported only for IP traffic