Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
IPSEC_SET_POLICY(3)    FreeBSD Library Functions Manual    IPSEC_SET_POLICY(3)

     ipsec_set_policy, ipsec_get_policylen, ipsec_dump_policy -- create an
     IPsec policy structure from a human readable string

     IPsec Policy Control Library (libipsec, -lipsec)

     #include <netinet6/ipsec.h>

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

     ipsec_get_policylen(char *buf);

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

     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 struc-
     ture, struct sadb_x_policy.  delim is a delimiter string, which is usu-
     ally a blank character.  If you set delim to NULL, a single white space
     is assumed.  The ipsec_dump_policy() function returns a pointer to dynam-
     ically 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

                       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 key-
                       word means that a relevant SA is required, and that the
                       kernel must perform IPsec processing on all matching

                       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 identi-
                       fier 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 unin-
                       tended 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), nei-
     ther entrust nor bypass are used.  Refer to setkey(8) for details.

     Set a policy that all inbound packets are discarded.

           in discard

     All outbound packets are required to be processed by IPsec and trans-
     ported using ESP.

           out ipsec esp/transport//require

     All inbound packets are required to be authenticated using the AH proto-

           in ipsec ah/transport//require

     Tunnel packets outbound through the endpoints at and

           out ipsec esp/tunnel/

     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 allo-
     cated region containing a human readable security policy on success, and
     NULL on error.

     ipsec_strerror(3), ipsec(4), setkey(8)

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

     IPv6 and IPsec support based on the KAME Project (
     stack was initially integrated into FreeBSD 4.0

FreeBSD 6.2                    February 14, 2006                   FreeBSD 6.2


Want to link to this manual page? Use this URL:

home | help