IPSEC_SET_POLICY 3
ipsec_set_policy create an IPsec policy structure from a human readable string

    #include <netinet6/ipsec.h>

char *`ipsec_set_policy` char * policy int len int `ipsec_get_policylen` char * buf char *`ipsec_dump_policy` char * buf char * delim

## LIBRARY

IPsec Policy Control Library (libipsec, -lipsec)

## DESCRIPTION

The ipsec_set_policy(); function generates an IPsec policy specification structure, `struct` `sadb_x_policy` and/or `struct` `sadb_x_ipsecrequest` from a human-readable policy specification. The policy specification must be given as a C string, passed in the policy argument and the length of the string, given as len. The ipsec_set_policy(); function returns pointer to a buffer which contains a properly formed IPsec policy specification structure. The buffer is dynamically allocated, and must be freed by using the free 3 library function.

The ipsec_get_policylen(); function will returns the of the buffer which is needed when passing the specification structure to the setsockopt 2 system call.

The ipsec_dump_policy(); function converts an IPsec policy structure into a 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. If you set delim to `NULL`, a single white space is assumed. The ipsec_dump_policy(); function returns a pointer to dynamically allocated string. It is the caller's responsibility to free the returned pointer using the free 3 library call.

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.

direction `entrust`

  `entrust` means to consult the security policy database (SPD) in the kernel, as controlled by setkey 8.

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.

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

    The protocol is one of: `ah`, `esp` or `ipcomp` indicating Authentication Header, Encapsulating Security Protocol or IP Compression protocol is used.

    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.

    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 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`.

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.

## 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

## RETURN VALUES

The ipsec_set_policy(); function returns a pointer to the allocated buffer containing a the policy specification if successful; otherwise a NULL pointer is returned.

The ipsec_get_policylen(); function returns a positive value, indicating the buffer size, on success, and a negative value on error.

The ipsec_dump_policy(); function returns a pointer to a dynamically allocated region containing a human readable security policy on success, and `NULL` on error.

## SEE ALSO

ipsec_strerror 3, ipsec 4, setkey 8

## 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