IPSEC_SET_POLICY(3)

🌸 IPSEC_SET_POLICY(3) 🌸

ok so bestie, we're in the Library Functions Manual today, and this one's from the IPsec Policy Control Library (libipsec, -lipsec). Strap in, it's actually so good 💅

---

✨ NAME ✨

ipsec_set_policy, ipsec_get_policylen, ipsec_dump_policy — they literally create an IPsec policy structure out of a human readable string. like, you speak English, it gives you a struct. iconic 🎀

---

🦋 LIBRARY 🦋

IPsec Policy Control Library (libipsec, -lipsec), duh 💖

---

🌈 SYNOPSIS 🌈

#include <netipsec/ipsec.h>

char *
ipsec_set_policy(const char *policy, int len);

int
ipsec_get_policylen(const char *buf);

char *
ipsec_dump_policy(c_caddr_t *buf, const char *delim);

---

💜 DESCRIPTION 💜

🧚 the three functions, one by one

ipsec_set_policy() generates an IPsec policy specification structure — that's struct sadb_x_policy and/or struct sadb_x_ipsecrequest, no cap — from a human-readable policy specification. The policy spec has to be a C string, handed over in the policy argument, plus the length of that string in len. It returns a pointer to a buffer that contains a properly formed IPsec policy specification structure. Heads up though: that buffer is dynamically allocated, so you must free it with the free(3) library function or it's giving leak energy 😭

ipsec_get_policylen() returns the length of the buffer — which is literally the thing you need when you pass that specification structure to the setsockopt(2) system call. so important, don't skip it ✨

ipsec_dump_policy() flips it the other way around: it converts an IPsec policy structure into human readable form. The buf argument points to an IPsec policy structure, struct sadb_x_policy. delim is a delimiter string, which is usually a blank character. And if you set delim to NULL, a single white space is assumed. It returns a pointer to a dynamically allocated string, and it is the caller's responsibility to free that returned pointer using the free(3) library call. your pointer, your problem, bestie 🫶

🌸 how you actually write a policy

A policy is given in the following way:

• direction discard — The direction must be in or out and specifies which direction the policy needs to be applied, either on inbound or outbound packets. When the discard policy is selected, packets will be dropped if they match the policy. goodbye packet 💀
• direction entrust — entrust means to consult the security policy database (SPD) in the kernel, as controlled by setkey(8). let the kernel be the main character 👑
• direction bypass — A direction of bypass indicates that IPsec processing should not occur and that the packet will be transmitted in clear. The bypass option is only available to privileged sockets. (>_<) so not for everyone, sorry!
• direction ipsec request ... — A direction of ipsec means that matching packets are processed by IPsec. ipsec can be followed by one or more request string, which is formatted as:

protocol / mode / src - dst [/level]

so like, let's break that down because it's a lot:

• The protocol is one of: ah, esp or ipcomp — indicating Authentication Header, Encapsulating Security Protocol or IP Compression protocol is used. pick your fighter ⭐
• The mode is either transport or tunnel — the meanings of both modes are described in ipsec(4).
• The src and dst specify the IP address, either v4 or v6, of the source and destination systems. The src always stands for the "sending node" and dst always stands for the "receiving node". When direction is in, dst is this local node and src is the remote node or peer. If mode is transport, both src and dst can be omitted. convenient!
• The level must be set to one of the following: default, use, require or unique.
  • default means that the kernel should consult the default security policies as defined by a set of sysctl(8) variables. The relevant sysctl(8) variables are described in ipsec(4).
  • When use is selected a relevant security association (SA) can be used when available but is not necessary. If the SA is available then packets will be handled by IPsec, i.e., encrypted and/or authenticated, but if an SA is not available then packets will be transmitted in the clear. 🚨 The use option is not recommended because it allows for accidental mis-configurations where an encrypted or authenticated link becomes unencrypted or unauthenticated. The require keyword is recommended instead of use where possible. Using the require keyword means that a relevant SA is required, and that the kernel must perform IPsec processing on all matching packets.
  • The unique keyword has the same effect as require, but adds the restriction that the SA for outbound traffic is used only for this policy. You may need the identifier in order to relate the policy and the SA when you define the SA by manual keying using setkey(8). Put the decimal number as the identifier after the unique keyword in this way: unique: number, where number must be between 1 and 32767.
• If the request string is kept unambiguous, level and the slash prior to level can be omitted, but you are encouraged to specify them explicitly to avoid unintended behaviors. If level is omitted, it will be interpreted as default. (iykyk, just write it out 💅)

⚠️ Note that there is a difference between the specification allowed here and in setkey(8). When specifying security policies with setkey(8), neither entrust nor bypass are used. Refer to setkey(8) for details. don't come for me, that's just how it is 😌

---

🔥 RETURN VALUES 🔥

• ipsec_set_policy() returns a pointer to the allocated buffer containing a the policy specification if successful; otherwise a NULL pointer is returned. (yes, "a the" — that's what the page says, I don't make the rules 🙈)
• ipsec_get_policylen() returns a positive value, indicating the buffer size, on success, and a negative value on error.
• ipsec_dump_policy() returns a pointer to a dynamically allocated region containing a human readable security policy on success, and NULL on error.

---

🍓 EXAMPLES 🍓

Set a policy that all inbound packets are discarded.

in discard

All outbound packets are required to be processed by IPsec and transported using ESP.

out ipsec esp/transport//require

All inbound packets are required to be authenticated using the AH protocol.

in ipsec ah/transport//require

Tunnel packets outbound through the endpoints at 10.1.1.2 and 10.1.1.1.

out ipsec esp/tunnel/10.1.1.2-10.1.1.1/require

---

🎀 SEE ALSO 🎀

ipsec_strerror(3), ipsec(4), setkey(8) — go read them, they're lowkey essential 📚

---

👑 HISTORY 👑

These functions first appeared in WIDE/KAME IPv6 protocol stack kit.

IPv6 and IPsec support based on the KAME Project (http://www.kame.net/) stack was initially integrated into FreeBSD 4.0.

---

and that's the whole page, bestie 💜 it's from Debian, dated February 14, 2006 — yes, Valentine's Day, the most romantic manpage release ever 🌹 periodt.