usr/src/man/man7p/ipsec.7p

   1 '\" te
   2 .\" Copyright (C) 2009, Sun Microsystems, Inc. All Rights Reserved
   3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License. You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.
   4 .\"  See the License for the specific language governing permissions and limitations under the License. When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with
   5 .\" the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   6 .TH IPSEC 7P "Sep 25, 2009"
   7 .SH NAME
   8 ipsec \- Internet Protocol Security Architecture
   9 .SH DESCRIPTION
  10 .sp
  11 .LP
  12 The \fBIP\fR Security Architecture (IPsec) provides protection for \fBIP\fR
  13 datagrams. The protection can include confidentiality, strong integrity of the
  14 data, partial sequence integrity  (replay protection), and data authentication.
  15 \fBIPsec\fR is performed inside the \fBIP\fR processing, and it can be applied
  16 with or without the knowledge of an Internet application.
  17 .sp
  18 .LP
  19 IPsec applies to both IPv4 and IPv6. See \fBip\fR(7P) and \fBip6\fR(7P).
  20 .SS "Protection Mechanisms"
  21 .sp
  22 .LP
  23 IPsec provides two mechanisms for protecting data. The Authentication Header
  24 (\fBAH\fR) provides strong integrity, replay protection, and data
  25 authentication. \fBAH\fR protects as much of the \fBIP\fR datagram as it can.
  26 \fBAH\fR cannot protect fields that change nondeterministically between sender
  27 and receiver.
  28 .sp
  29 .LP
  30 The Encapsulating Security Payload (\fBESP\fR) provides confidentiality over
  31 what it encapsulates, as well as the services that \fBAH\fR provides, but only
  32 over that which it encapsulates. \fBESP\fR's authentication services are
  33 optional, which allow \fBESP\fR and \fBAH\fR to be used together on the same
  34 datagram without redundancy.
  35 .sp
  36 .LP
  37 Authentication and encryption algorithms are used for IPsec. Authentication
  38 algorithms produce an integrity checksum value or "digest"based on the data and
  39 a key. Encryption algorithms operate on data in units of a "block size".
  40 .SS "NAT Traversal"
  41 .sp
  42 .LP
  43 IPsec's ESP can also encapsulate itself in UDP if IKE (see \fBin.iked\fR(1M))
  44 discovers a Network Address Translator (NAT) between two communicating
  45 endpoints.
  46 .sp
  47 .LP
  48 A UDP socket can be specified as a NAT-Traversal endpoint. See \fBudp\fR(7P)
  49 for details.
  50 .SS "Security Associations"
  51 .sp
  52 .LP
  53 \fBAH\fR and \fBESP\fR use Security Associations (\fBSA\fR). SA's are entities
  54 that specify security properties from one host to another. Two communicating
  55 machines require two \fBSA\fRs (at a minimum) to communicate securely. However,
  56 communicating machines that use multicast can share the same multicast
  57 \fBSA\fR. \fBSA\fRs are managed through the \fBpf_key\fR(7P) interface. For
  58 IPv4, automatic \fBSA\fR management is available through the Internet Key
  59 Exchange (IKE), as implemented by \fBin.iked\fR(1M). A command-line front-end
  60 is available by means of \fBipseckey\fR(1M). An IPsec \fBSA\fR is identified by
  61 a tuple of <\fBAH\fR or \fBESP\fR, destination \fBIP\fR address, and
  62 \fBSPI\fR>. The Security Parameters Index (\fBSPI\fR) is an arbitrary 32-bit
  63 value that is transmitted on the wire with an \fBAH\fR or \fBESP\fR packet. See
  64 \fBipsecah\fR(7P) or \fBipsecesp\fR(7P)  for an explanation about where the
  65 \fBSPI\fR falls in a protected packet.
  66 .SS "Protection Policy and Enforcement Mechanisms"
  67 .sp
  68 .LP
  69 Mechanism and policy are separate. The policy for applying IPsec is enforced on
  70 a system-wide or per-socket level. Configuring system-wide policy and
  71 per-tunnel policy (see Transport Mode and Tunnel Mode sections) is done via the
  72 \fBipsecconf\fR(1M) command. Configuring per-socket policy is discussed later
  73 in this section.
  74 .sp
  75 .LP
  76 System-wide IPsec policy is applied to incoming and outgoing datagrams. Some
  77 additional rules can be applied to outgoing datagrams because of the additional
  78 data known by the system. Inbound datagrams can be accepted or dropped. The
  79 decision to drop or accept an inbound datagram is based on several criteria
  80 which sometimes overlap or conflict. Conflict resolution is resolved by which
  81 rule is parsed first, with one exception: if a policy entry states that traffic
  82 should bypass all other policy, it is automatically be accepted. Outbound
  83 datagrams are sent with or without protection. Protection may (or may not)
  84 indicate specific algorithms. If policy normally would protect a datagram, it
  85 can be bypassed either by an exception in system-wide policy or by requesting a
  86 bypass in per-socket policy.
  87 .sp
  88 .LP
  89 Intra-machine traffic policies are enforced, but actual security mechanisms are
  90 not applied. Instead, the outbound policy on an intra-machine packet translates
  91 into an inbound packet with those mechanisms applied.
  92 .sp
  93 .LP
  94 IPsec policy is enforced in the \fBip\fR(7P) driver. Several \fBndd\fR tunables
  95 for \fB/dev/ip\fR affect policy enforcement, including:
  96 .sp
  97 .ne 2
  98 .na
  99 \fBicmp_accept_clear_messages\fR
 100 .ad
 101 .RS 30n
 102 If equal to 1 (the default), allow certain cleartext icmp messages to bypass
 103 policy. For ICMP echo requests ("ping"messages), protect the response like the
 104 request. If zero, treat icmp messages like other IP traffic.
 105 .RE
 106
 107 .sp
 108 .ne 2
 109 .na
 110 \fBigmp_accept_clear_messages\fR
 111 .ad
 112 .RS 30n
 113 If 1, allow inbound cleartext IGMP messages to bypass IPsec policy.
 114 .RE
 115
 116 .sp
 117 .ne 2
 118 .na
 119 \fBpim_accept_clear_messages\fR
 120 .ad
 121 .RS 30n
 122 If 1, allow inbound cleartext PIM messages to bypass IPsec policy.
 123 .RE
 124
 125 .sp
 126 .ne 2
 127 .na
 128 \fBipsec_policy_log_interval\fR
 129 .ad
 130 .RS 30n
 131 IPsec logs policy failures and errors to \fB/var/adm/messages\fR. To prevent
 132 syslog from being overloaded, the IPsec kernel modules limit the rate at which
 133 errors can be logged. You can query/set ipsec_policy_log_interval using
 134 \fBndd\fR(1M). The value is in milliseconds. Only one message can be logged per
 135 interval.
 136 .RE
 137
 138 .SS "Transport Mode and Tunnel Mode"
 139 .sp
 140 .LP
 141 If IPsec is used on a tunnel, Tunnel Mode IPsec can be used to protect distinct
 142 flows within a tunnel or to cause packets that do not match per-tunnel policy
 143 to drop. System-wide policy is always Transport Mode.  A tunnel can use
 144 Transport Mode IPsec or Tunnel Mode IPsec.
 145 .SS "Per-Socket Policy"
 146 .sp
 147 .LP
 148 The \fBIP_SEC_OPT\fR or \fBIPV6_SEC_OPT\fR socket option is used to set
 149 per-socket IPsec policy.  The structure used for an \fBIP_SEC_OPT\fR request
 150 is:
 151 .sp
 152 .in +2
 153 .nf
 154 typedef struct ipsec_req {
 155     uint_t      ipsr_ah_req;           /* AH request */
 156     uint_t      ipsr_esp_req;          /* ESP request */
 157     uint_t      ipsr_self_encap_req;   /* Self-Encap request */
 158     uint8_t     ipsr_auth_alg;         /* Auth algs for AH */
 159     uint8_t     ipsr_esp_alg;          /* Encr algs for ESP */
 160     uint8_t     ipsr_esp_auth_alg;     /* Auth algs for ESP */
 161 } ipsec_req_t;
 162 .fi
 163 .in -2
 164
 165 .sp
 166 .LP
 167 The IPsec request has fields for both \fBAH\fR and \fBESP\fR. Algorithms may or
 168 may not be specified. The actual request for \fBAH\fR or \fBESP\fR services can
 169 take one of the following values:
 170 .sp
 171 .ne 2
 172 .na
 173 \fB\fBIPSEC_PREF_NEVER\fR\fR
 174 .ad
 175 .RS 23n
 176 Bypass all policy. Only the superuser may request this service.
 177 .RE
 178
 179 .sp
 180 .ne 2
 181 .na
 182 \fB\fBIPSEC_PREF_REQUIRED\fR\fR
 183 .ad
 184 .RS 23n
 185 Regardless of other policy, require the use of the  IPsec  service.
 186 .RE
 187
 188 .sp
 189 .LP
 190 The following value can be logically ORed to an \fBIPSEC_PREF_REQUIRED\fR
 191 value:
 192 .sp
 193 .ne 2
 194 .na
 195 \fB\fBIPSEC_PREF_UNIQUE\fR\fR
 196 .ad
 197 .RS 21n
 198 Regardless of other policy, enforce a unique \fBSA\fR for traffic originating
 199 from this socket.
 200 .RE
 201
 202 .sp
 203 .LP
 204 In the event \fBIP\fR options not normally encapsulated by \fBESP\fR need to
 205 be, the \fBipsec_self_encap_req\fR is used to add an additional \fBIP\fR header
 206 outside the original one. Algorithm values from <\fBnet/pfkeyv2.h\fR> are as
 207 follows:
 208 .sp
 209 .ne 2
 210 .na
 211 \fB\fBSADB_AALG_MD5HMAC\fR\fR
 212 .ad
 213 .RS 24n
 214 Uses the MD5-HMAC (\fIRFC 2403\fR)  algorithm for authentication.
 215 .RE
 216
 217 .sp
 218 .ne 2
 219 .na
 220 \fB\fBSADB_AALG_SHA1HMAC\fR\fR
 221 .ad
 222 .RS 24n
 223 Uses the SHA1-HMAC (\fIRFC 2404)\fR algorithm for authentication.
 224 .RE
 225
 226 .sp
 227 .ne 2
 228 .na
 229 \fB\fBSADB_EALG_DESCBC\fR\fR
 230 .ad
 231 .RS 24n
 232 Uses the \fBDES\fR (\fIRFC 2405\fR) algorithm for encryption.
 233 .RE
 234
 235 .sp
 236 .ne 2
 237 .na
 238 \fB\fBSADB_EALG_3DESCBC\fR\fR
 239 .ad
 240 .RS 24n
 241 Uses the Triple  \fBDES \fR (\fIRFC 2451\fR)   algorithm for encryption.
 242 .RE
 243
 244 .sp
 245 .ne 2
 246 .na
 247 \fB\fBSADB_EALG_BLOWFISH\fR\fR
 248 .ad
 249 .RS 24n
 250 Uses the Blowfish (\fIRFC 2451\fR) algorithm for encryption.
 251 .RE
 252
 253 .sp
 254 .ne 2
 255 .na
 256 \fB\fBSADB_EALG_AES\fR\fR
 257 .ad
 258 .RS 24n
 259 Uses  the  Advanced Encryption Standard  algorithm for encryption.
 260 .RE
 261
 262 .sp
 263 .ne 2
 264 .na
 265 \fB\fBSADB_AALG_SHA256HMAC\fR\fR
 266 .ad
 267 .br
 268 .na
 269 \fB\fBSADB_AALG_SHA384HMAC\fR\fR
 270 .ad
 271 .br
 272 .na
 273 \fB\fBSADB_AALG_SHA512HMAC\fR\fR
 274 .ad
 275 .RS 24n
 276 Uses the SHA2 hash algorithms with HMAC (\fIRFC 4868\fR)for authentication.
 277 .RE
 278
 279 .sp
 280 .LP
 281 An application should use either the \fBgetsockopt\fR(3SOCKET) or the
 282 \fBsetsockopt\fR(3SOCKET) call to manipulate IPsec requests.  For example:
 283 .sp
 284 .in +2
 285 .nf
 286 #include <sys/socket.h>
 287 #include <netinet/in.h>
 288 #include <net/pfkeyv2.h>   /* For SADB_*ALG_* */
 289 /* .... socket setup skipped */
 290 rc = setsockopt(s, IPPROTO_IP, IP_SEC_OPT,
 291    (const char *)&ipsec_req, sizeof (ipsec_req_t));
 292 .fi
 293 .in -2
 294
 295 .SH SECURITY
 296 .sp
 297 .LP
 298 While IPsec is an effective tool in securing network traffic, it will not make
 299 security problems disappear. Security issues beyond the mechanisms that IPsec
 300 offers may be discussed in similar "Security" or "Security Consideration"
 301 sections within individual reference manual pages.
 302 .sp
 303 .LP
 304 While a non-root user cannot bypass IPsec, a non-root user can set policy to be
 305 different from the system-wide policy. For ways to prevent this, consult the
 306 \fBndd\fR(1M) variables in \fB/dev/ip\fR.
 307 .SH ATTRIBUTES
 308 .sp
 309 .LP
 310 See \fBattributes\fR(5)  for descriptions of the following attributes:
 311 .sp
 312
 313 .sp
 314 .TS
 315 box;
 316 c | c
 317 l | l .
 318 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 319 _
 320 Interface Stability     Committed
 321 .TE
 322
 323 .SH SEE ALSO
 324 .sp
 325 .LP
 326 \fBin.iked\fR(1M), \fBipsecconf\fR(1M), \fBipseckey\fR(1M), \fBndd\fR(1M),
 327 \fBgetsockopt\fR(3SOCKET), \fBsetsockopt\fR(3SOCKET), \fBattributes\fR(5),
 328 \fBinet\fR(7P), \fBip\fR(7P), \fBip6\fR(7P), \fBipsecah\fR(7P),
 329 \fBipsecesp\fR(7P), \fBpf_key\fR(7P), \fBudp\fR(7P)
 330 .sp
 331 .LP
 332 Kent, S., and Atkinson, R., \fIRFC 2401, Security Architecture for the Internet
 333 Protocol\fR, The Internet Society, 1998.
 334 .sp
 335 .LP
 336 Kent, S. and Atkinson, R., \fIRFC 2406, IP Encapsulating Security Payload
 337 (ESP)\fR, The Internet Society, 1998.
 338 .sp
 339 .LP
 340 Madson, C., and Doraswamy, N., \fIRFC 2405, The ESP DES-CBC Cipher Algorithm
 341 with Explicit IV\fR, The Internet Society, 1998.
 342 .sp
 343 .LP
 344 Madsen, C. and Glenn, R., \fIRFC 2403, The Use of HMAC-MD5-96 within ESP and
 345 AH\fR, The Internet Society, 1998.
 346 .sp
 347 .LP
 348 Madsen, C. and Glenn, R., \fIRFC 2404, The Use of HMAC-SHA-1-96 within ESP and
 349 AH\fR, The Internet Society, 1998.
 350 .sp
 351 .LP
 352 Pereira, R. and Adams, R., \fIRFC 2451, The ESP CBC-Mode Cipher Algorithms\fR,
 353 The Internet Society, 1998.
 354 .sp
 355 .LP
 356 Kelly, S. and Frankel, S., \fIRFC 4868, Using HMAC-SHA-256, HMAC-SHA-384, and
 357 HMAC-SHA-512 with IPsec\fR, 2007.
 358 .sp
 359 .LP
 360 Huttunen, A., Swander, B., Volpe, V., DiBurro, L., Stenberg, \fIM., RFC 3948,
 361 UDP Encapsulation of IPsec ESP Packets\fR, The Internet Society, 2005.