This version of this document is no longer maintained. For the latest documentation, see http://www.qnx.com/developers/docs.

ipsec_set_policy()

Generate an IPsec policy specification structure from a readable string

Synopsis:

#include <netinet6/ipsec.h>

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

Arguments:

len: The length of the policy string.
policy: A string that describes a struct sadb_x_policy and optionally a struct sadb_x_ipsecrequest, formatted as described below.

Library:

libipsec

Use the -l ipsec option to qcc to link against this library.

The function ipsec_set_policy() generates an IPsec policy specification structure, namely a struct sadb_x_policy and potentially a struct sadb_x_ipsecrequest from a human-readable policy specification. This function returns a pointer to the IPsec policy specification structure.

You should release the buffer returned by ipsec_set_policy() by calling free(). See the example below.

The policy is formatted as one of the following:

direction discard

The direction must be in or out. It specifies which direction the policy needs to be applied. With the discard policy, packets are dropped if they match the policy.

direction entrust

Consultation to SPD -- defined by setkey.

direction bypass

Bypass the IPsec processing, i.e. packets are transmitted in clear. This is for privileged sockets.

direction ipsec request ...

The matching packets are subject to IPsec processing. The ipsec string can be followed by one or more request strings, which are formatted as below:

protocol / mode / src - dst [/level]

protocol

Either ah, esp, or ipcomp.

mode

Either transport or tunnel.

src and dst

The IPsec endpoints; src is the sending node and dst is the receiving node. Therefore, when direction is in, dst is this node and src is the other node (peer).

level

Either default, use, require or unique.

default -- the kernel should consult the system default policy defined by sysctl().
use -- a relevant SA (security association) is used when available, since the kernel may perform IPsec operation against packets when possible. In this case, packets are transmitted in clear (when SA is not available), or encrypted (when SA is available).
require -- a relevant SA is required, since the kernel must perform IPsec operation against packets.
unique is the same as require. However, it 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. You put the decimal number as the identifier like:
unique: number
where number must be between 1 and 32767. If the request string is kept unambiguous, you can omit the level and the slash ("/") prior to level. However, you should specify them explicitly to avoid unintended behavior. If level is omitted, it will be interpreted as default.

Here's an example of policy information:

in discard
out ipsec esp/transport//require
in ipsec ah/transport//require
out ipsec esp/tunnel/10.1.1.2-10.1.1.1/use
in ipsec ipcom/transport//use esp/transport//use

It differs from the specification of setkey, where both entrust and bypass are not used. Please refer to setkey for detail.

Returns:

A pointer to the allocated policy specification, or NULL if an error occurs.

Examples:

#include <netinet6/ipsec.h>
#include <sys/socket.h>
#include <stdio.h>
#include <malloc.h>
#include <string.h>

int   
main(void)
{
   char *sadb;
   char *policy = "in discard";
   int len;
   
   sadb = ipsec_set_policy(policy, strlen(policy));

   if (sadb == NULL) {
      fprintf(stderr, "ipsec_set_policy: %s\n", ipsec_strerror());
      return 1;
   }
   
   len = ipsec_get_policylen(sadb);
   printf("len: %d\n", len);

   policy = NULL;
   policy = ipsec_dump_policy(sadb, NULL);

   if (policy == NULL) {
      fprintf(stderr, "ipsec_dump_policy: %s\n", ipsec_strerror());
      return 1;
   }

   printf("policy: %s\n", policy);

   free(policy);
   free(sadb);

   return 0;
}

Classification:

Unix

Safety:
Cancellation point	No
Interrupt handler	No
Signal handler	No
Thread	Yes