ECN(9)

NAME
ecn, ip_ecn_ingress, ip_ecn_egress, ip6_ecn_ingress, ip6_ecn_egress - IP ECN interfaces for tunnel encapsulation/decapsulation

SYNOPSIS
#include <sys/netinet/ip_ecn.h>
#include <sys/netinet6/ip6_ecn.h>

  Constants
ECN_COMPLETE ECN_ALLOWED ECN_FORBIDDEN ECN_NOCARE

  ECN Manipulation Functions
void
ip_ecn_ingress(int mode, uint8_t *outer, const uint8_t *inner);
void
ip6_ecn_ingress(int mode, uint32_t *outer, const uint32_t *inner);
int
ip_ecn_egress(int mode, uint8_t *outer, const uint8_t *inner);
int
ip6_ecn_egress(int mode, uint32_t *outer, const uint32_t *inner);

DESCRIPTION
The ip_ecn_ingress() and ip_ecn_egress() interfaces implement Explicit Congestion Notification (ECN) processing for tunnel encapsulation (ingress) and decapsulation (egress). They operate on the ECN bits in the IP Type of Service (TOS) or IPv6 Traffic Class (TCLASS) header field. These functions implements the standard specification of RFC6040 in ECN_ALLOWED mode for ip_ecn_egress() with addition of ECN_FORBIDDEN mode as compatibility mode in ip_ecn_ingress().

  Interface
The functions for manipulating ip_tos and ipv6_flow are as follows:

ip_ecn_ingress() ip6_ecn_ingress()
    Perform ECN processing at encapsulation time (ingress) based on the ECN bits of the ip_tos field in struct ip or the ip6_flow field in struct ip6_hdr as inner to outer. It also copies the DSCP value from inner to outer.

ip_ecn_egress() ip6_ecn_egress()
    Perform ECN processing at decapsulation time (egress) based on the ECN bits of outer to inner. ECN_ALLOWED mode may modify the inner ECN bits or instruct the caller to drop or log by returning ECN_WARN or ECN_ALARM values.

Return codes for ip_ecn_egress() are as follows:

ECN_DROP
    (0) Caller MUST drop the packet.

ECN_SUCCESS
    (1) Processing succeeded; inner ECN bits may have been updated.

ECN_WARN
    (2) Processing succeeded; caller MAY log a warning for an anomalous ECN combination.

ECN_ALARM
    (3) Processing succeeded; caller SHOULD log and MAY raise an alarm for a serious ECN anomaly.

The following modes are handled by functions:

ECN_COMPLETE
    Normal mode as defined in RFC6040. ECN bits are preserved through encapsulation; decapsulation follows RFC6040 rules and it returns ECN_WARN or ECN_ALARM values when a potentially dangerous packet detected.

ECN_ALLOWED
    Normal mode as defined in RFC6040 without security checks. ECN bits are preserved through encapsulation; decapsulation follows RFC6040 rules.

ECN_FORBIDDEN
    Compatibility mode. ECN is stripped on encapsulation and decapsulation will drop packets that carry CE in the outer header. This mode should not be used in ip_ecn_egress() or ip6_ecn_egress() since the ECN_ALLOWED mode already covers all possible scenarios as specified in RFC6040.

ECN_NOCARE
    leave ECN bits unchanged and ignored.

  IPV6 HANDLING
IPv6 interfaces ip6_ecn_ingress() and ip6_ecn_egress() extract the 8-bit DSCP and ECN values from the 32-bit ip6_flow and insert it to IPv4 equivalent interfaces.

SEE ALSO
ip(4), ip6(4), ipsec(4)

HISTORY
Historically ip_ecn_egress() used a boolean-style return. The current API preserves numeric mapping for drop (ECN_DROP == 0) and success (ECN_SUCCESS == 1) but defines additional non-zero status codes (ECN_WARN, ECN_ALARM). Callers that only test for non-zero success will continue to treat WARN/ALARM as success.

AUTHORS
Pouria Mousavizadeh Tehrani <pouria@FreeBSD.org>