ipsec(7p) - osol9

1ipsec(7P)                          Protocols                         ipsec(7P)
2
3
4

NAME

6       ipsec - Internet Protocol Security Architecture
7

DESCRIPTION

9       The  IP  Security Architecture (IPsec) provides protection for IP data‐
10       grams. The protection can include confidentiality, strong integrity  of
11       the  data,  partial  sequence  integrity  (replay protection), and data
12       authentication. IPsec is performed inside the IP processing, and it can
13       be applied with or without the knowledge of an Internet application.
14
15
16       IPsec applies to both IPv4 and IPv6. See ip(7P) and ip6(7P).
17
18   Protection Mechanisms
19       IPsec  provides  two mechanisms for protecting data. The Authentication
20       Header (AH) provides strong  integrity,  replay  protection,  and  data
21       authentication.  AH  protects  as much of the IP datagram as it can. AH
22       cannot protect fields that change nondeterministically  between  sender
23       and receiver.
24
25
26       The  Encapsulating Security Payload (ESP) provides confidentiality over
27       what it encapsulates, as well as the services  that  AH  provides,  but
28       only over that which it encapsulates. ESP's authentication services are
29       optional, which allow ESP and AH to be used together on the same  data‐
30       gram without redundancy.
31
32
33       Authentication  and encryption algorithms are used for IPsec. Authenti‐
34       cation algorithms produce an integrity checksum value or  "digest"based
35       on  the  data and a key. Encryption algorithms operate on data in units
36       of a "block size".
37
38   NAT Traversal
39       IPsec's ESP can also encapsulate itself in UDP if IKE (see in.iked(1M))
40       discovers  a Network Address Translator (NAT) between two communicating
41       endpoints.
42
43
44       A UDP socket can be specified as a NAT-Traversal endpoint. See  udp(7P)
45       for details.
46
47   Security Associations
48       AH and ESP use Security Associations (SA). SA's are entities that spec‐
49       ify security properties from one host  to  another.  Two  communicating
50       machines  require  two SAs (at a minimum) to communicate securely. How‐
51       ever, communicating machines that use multicast can share the same mul‐
52       ticast  SA. SAs are managed through the pf_key(7P) interface. For IPv4,
53       automatic SA management is available through the Internet Key  Exchange
54       (IKE),  as  implemented  by  in.iked(1M).  A  command-line front-end is
55       available by means of ipseckey(1M). An IPsec  SA  is  identified  by  a
56       tuple  of  <AH  or  ESP, destination IP address, and SPI>. The Security
57       Parameters Index (SPI) is an arbitrary 32-bit value that is transmitted
58       on  the  wire with an AH or ESP packet. See ipsecah(7P) or ipsecesp(7P)
59       for an explanation about where the SPI falls in a protected packet.
60
61   Protection Policy and Enforcement Mechanisms
62       Mechanism and policy are separate. The policy  for  applying  IPsec  is
63       enforced  on a system-wide or per-socket level. Configuring system-wide
64       policy and per-tunnel policy (see Transport Mode and Tunnel  Mode  sec‐
65       tions)  is  done  via the ipsecconf(1M) command. Configuring per-socket
66       policy is discussed later in this section.
67
68
69       System-wide IPsec policy is applied to incoming and outgoing datagrams.
70       Some  additional  rules can be applied to outgoing datagrams because of
71       the additional data known by  the  system.  Inbound  datagrams  can  be
72       accepted or dropped. The decision to drop or accept an inbound datagram
73       is based on several criteria which sometimes overlap or conflict.  Con‐
74       flict  resolution  is  resolved by which rule is parsed first, with one
75       exception: if a policy entry states  that  traffic  should  bypass  all
76       other  policy,  it is automatically be accepted. Outbound datagrams are
77       sent with or without protection. Protection may (or may  not)  indicate
78       specific  algorithms.  If  policy normally would protect a datagram, it
79       can be bypassed either by an exception  in  system-wide  policy  or  by
80       requesting a bypass in per-socket policy.
81
82
83       Intra-machine traffic policies are enforced, but actual security mecha‐
84       nisms are not applied. Instead, the outbound policy on an intra-machine
85       packet translates into an inbound packet with those mechanisms applied.
86
87
88       IPsec policy is enforced in the ip(7P) driver. Several ndd tunables for
89       /dev/ip affect policy enforcement, including:
90
91       icmp_accept_clear_messages    If equal to 1 (the default),  allow  cer‐
92                                     tain  cleartext  icmp  messages to bypass
93                                     policy.   For    ICMP    echo    requests
94                                     ("ping"messages),  protect  the  response
95                                     like the request.  If  zero,  treat  icmp
96                                     messages like other IP traffic.
97
98
99       igmp_accept_clear_messages    If  1,  allow inbound cleartext IGMP mes‐
100                                     sages to bypass IPsec policy.
101
102
103       pim_accept_clear_messages     If 1, allow inbound  cleartext  PIM  mes‐
104                                     sages to bypass IPsec policy.
105
106
107       ipsec_policy_log_interval     IPsec  logs policy failures and errors to
108                                     /var/adm/messages. To prevent syslog from
109                                     being  overloaded,  the IPsec kernel mod‐
110                                     ules limit the rate at which  errors  can
111                                     be  logged.  You can query/set ipsec_pol‐
112                                     icy_log_interval using ndd(1M). The value
113                                     is  in milliseconds. Only one message can
114                                     be logged per interval.
115
116
117   Transport Mode and Tunnel Mode
118       If IPsec is used on a tunnel, Tunnel Mode IPsec can be used to  protect
119       distinct  flows  within  a tunnel or to cause packets that do not match
120       per-tunnel policy to drop. System-wide policy is always Transport Mode.
121       A tunnel can use Transport Mode IPsec or Tunnel Mode IPsec.
122
123   Per-Socket Policy
124       The  IP_SEC_OPT or IPV6_SEC_OPT socket option is used to set per-socket
125       IPsec policy.  The structure used for an IP_SEC_OPT request is:
126
127         typedef struct ipsec_req {
128             uint_t      ipsr_ah_req;           /* AH request */
129             uint_t      ipsr_esp_req;          /* ESP request */
130             uint_t      ipsr_self_encap_req;   /* Self-Encap request */
131             uint8_t     ipsr_auth_alg;         /* Auth algs for AH */
132             uint8_t     ipsr_esp_alg;          /* Encr algs for ESP */
133             uint8_t     ipsr_esp_auth_alg;     /* Auth algs for ESP */
134         } ipsec_req_t;
135
136
137
138       The IPsec request has fields for both AH and ESP. Algorithms may or may
139       not  be  specified.  The actual request for AH or ESP services can take
140       one of the following values:
141
142       IPSEC_PREF_NEVER       Bypass  all  policy.  Only  the  superuser   may
143                              request this service.
144
145
146       IPSEC_PREF_REQUIRED    Regardless  of  other policy, require the use of
147                              the  IPsec  service.
148
149
150
151       The following value can be logically  ORed  to  an  IPSEC_PREF_REQUIRED
152       value:
153
154       IPSEC_PREF_UNIQUE    Regardless  of  other  policy, enforce a unique SA
155                            for traffic originating from this socket.
156
157
158
159       In the event IP options not normally encapsulated by ESP  need  to  be,
160       the ipsec_self_encap_req is used to add an additional IP header outside
161       the original one. Algorithm values from <net/pfkeyv2.h> are as follows:
162
163       SADB_AALG_MD5HMAC       Uses the MD5-HMAC  (RFC  2403)   algorithm  for
164                               authentication.
165
166
167       SADB_AALG_SHA1HMAC      Uses  the  SHA1-HMAC  (RFC  2404) algorithm for
168                               authentication.
169
170
171       SADB_EALG_DESCBC        Uses the DES (RFC 2405) algorithm  for  encryp‐
172                               tion.
173
174
175       SADB_EALG_3DESCBC       Uses  the  Triple   DES  (RFC 2451)   algorithm
176                               for encryption.
177
178
179       SADB_EALG_BLOWFISH      Uses the  Blowfish  (RFC  2451)  algorithm  for
180                               encryption.
181
182
183       SADB_EALG_AES           Uses   the  Advanced Encryption Standard  algo‐
184                               rithm for encryption.
185
186
187       SADB_AALG_SHA256HMAC    Uses the SHA2 hash algorithms  with  HMAC  (RFC
188       SADB_AALG_SHA384HMAC    4868)for authentication.
189       SADB_AALG_SHA512HMAC
190
191
192       An  application  should  use either the getsockopt(3SOCKET) or the set‐
193       sockopt(3SOCKET) call to manipulate IPsec requests.  For example:
194
195         #include <sys/socket.h>
196         #include <netinet/in.h>
197         #include <net/pfkeyv2.h>   /* For SADB_*ALG_* */
198         /* .... socket setup skipped */
199         rc = setsockopt(s, IPPROTO_IP, IP_SEC_OPT,
200            (const char *)&ipsec_req, sizeof (ipsec_req_t));
201
202

SECURITY

204       While IPsec is an effective tool in securing network traffic,  it  will
205       not make security problems disappear. Security issues beyond the mecha‐
206       nisms that IPsec offers may  be  discussed  in  similar  "Security"  or
207       "Security  Consideration"  sections  within individual reference manual
208       pages.
209
210
211       While a non-root user cannot bypass IPsec, a non-root user can set pol‐
212       icy  to  be  different from the system-wide policy. For ways to prevent
213       this, consult the ndd(1M) variables in /dev/ip.
214

ATTRIBUTES

216       See attributes(5)  for descriptions of the following attributes:
217
218
219
220
221       ┌─────────────────────────────┬─────────────────────────────┐
222       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
223       ├─────────────────────────────┼─────────────────────────────┤
224       │Interface Stability          │Committed                    │
225       └─────────────────────────────┴─────────────────────────────┘
226

NAME

DESCRIPTION

SECURITY

ATTRIBUTES

SEE ALSO