diff --git a/lib/libipsec/ipsec_set_policy.3 b/lib/libipsec/ipsec_set_policy.3 index 048aa7fe2d35..8be32f535107 100644 --- a/lib/libipsec/ipsec_set_policy.3 +++ b/lib/libipsec/ipsec_set_policy.3 @@ -29,14 +29,14 @@ .\" .\" $FreeBSD$ .\" -.Dd May 5, 1998 +.Dd February 14, 2006 .Dt IPSEC_SET_POLICY 3 .Os .Sh NAME .Nm ipsec_set_policy , .Nm ipsec_get_policylen , .Nm ipsec_dump_policy -.Nd manipulate IPsec policy specification structure from readable string +.Nd create an IPsec policy structure from a human readable string .\" .Sh LIBRARY .Lb libipsec @@ -51,38 +51,37 @@ .Sh DESCRIPTION The .Fn ipsec_set_policy -function generates IPsec policy specification structure, namely +function generates an IPsec policy specification structure, .Li struct sadb_x_policy and/or .Li struct sadb_x_ipsecrequest -from human-readable policy specification. -Policy specification must be given as C string +from a human-readable policy specification. +The policy specification must be given as a C string, +passed in the .Fa policy -and length -.Fa len -of -.Fa policy . +argument and the length of the string, given as +.Fa len . The .Fn ipsec_set_policy -function will return the buffer of IPsec policy specification structure. -The buffer is dynamically allocated, and must be freed by the caller by calling -.Xr free 3 . +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 +.Xr free 3 +library function. .Pp -You may want the length of the generated buffer such when calling -.Xr setsockopt 2 . The .Fn ipsec_get_policylen -function will return the length. +function will returns the of the buffer which is needed when passing +the specification structure to the +.Xr setsockopt 2 +system call. .Pp The .Fn ipsec_dump_policy -function converts IPsec policy structure into readable form. -Therefore, -.Fn ipsec_dump_policy -can be regarded as inverse conversion of -.Fn ipsec_set_policy . +function converts an IPsec policy structure into a human readable form. +The .Fa buf -points to an IPsec policy structure, +argument points to an IPsec policy structure, .Li struct sadb_x_policy . .Fa delim is a delimiter string, which is usually a blank character. @@ -90,47 +89,55 @@ If you set .Fa delim to .Dv NULL , -single whitespace is assumed. +a single white space is assumed. The .Fn ipsec_dump_policy function returns a pointer to dynamically allocated string. -It is caller's responsibility to reclaim the region, by using -.Xr free 3 . +It is the caller's responsibility to free the returned pointer using the +.Xr free 3 +library call. .Pp +A .Fa policy -is formatted as either of the following: +is given in the following way: .Bl -tag -width "discard" .It Ar direction Li discard +The .Ar direction must be .Li in or -.Li out . -.Ar direction -specifies which direction the policy needs to be applied. -With +.Li out +and +specifies which direction the policy needs to be applied, either on +inbound or outbound packets. +When the .Li discard -policy, packets will be dropped if they match the policy. +policy is selected, packets will be dropped if they match the policy. .It Ar direction Li entrust .Li entrust -means to consult to SPD defined by +means to consult the security policy database +(SPD) +in the kernel, as controlled by .Xr setkey 8 . .It Ar direction Li bypass +A direction of .Li bypass -means to be bypassed the IPsec processing. -(packet will be transmitted in clear). -This is for privileged socket. +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. .It Xo .Ar direction .Li ipsec .Ar request ... .Xc +A direction of .Li ipsec -means that the matching packets are subject to IPsec processing. +means that matching packets are processed by IPsec. .Li ipsec can be followed by one or more .Ar request -string, which is formatted as below: +string, which is formatted as: .Bl -tag -width "discard" .It Xo .Ar protocol @@ -142,95 +149,118 @@ string, which is formatted as below: .Ar dst .Op Ar /level .Xc +The .Ar protocol -is either +is one of: .Li ah , .Li esp or -.Li ipcomp . +.Li ipcomp +indicating Authentication Header, Encapsulating Security Protocol or +IP Compression protocol is used. .Pp +The .Ar mode is either .Li transport or -.Li tunnel . +.Li tunnel +the meanings of both modes are described in +.Xr ipsec 4 . .Pp +The .Ar src and .Ar dst -specifies IPsec endpoint. +specify the IP address, either v4 or v6, of the source and destination systems. +The .Ar src -always means +always stands for the .Dq sending node and .Ar dst -always means +always stands for the .Dq receiving node . -Therefore, when +When .Ar direction is .Li in , .Ar dst -is this node +is this local node and .Ar src -is the other node -(peer). +is the remote node or peer. If .Ar mode is .Li transport , -Both +both .Ar src and .Ar dst can be omitted. .Pp +The .Ar level must be set to one of the following: .Li default , use , require or .Li unique . .Li default -means that the kernel should consult the system default policy -defined by +means that the kernel should consult the default security policies as +defined by a set of .Xr sysctl 8 , -such as -.Li net.inet.ipsec.esp_trans_deflev . -See -.Xr ipsec 4 -regarding the system default. +variables. The relevant +.Xr sysctl 8 +variables are described in +.Xr ipsec 4 . +.Pp +When .Li use -means that a relevant SA can be used when available, -since the kernel may perform IPsec operation against packets when possible. -In this case, packets can be transmitted in clear -(when SA is not available), -or encrypted -(when SA is available). +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 +.Li use +option is not recommended because it allows for accidental +mis-configurations where encrypted or authenticated link becomes +unencrypted or unauthenticated, the .Li require -means that a relevant SA is required, -since the kernel must perform IPsec operation against packets. +keyword is recommended instead of +.Li use +where possible. +Using the +.Li require +keyword means that a relevant SA is required, +and that the kernel must perform IPsec processing on all matching +packets. +.Pp +The .Li unique -is the same as +keyword has the same effect as .Li 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. -You can put the decimal number as the identifier after +when you define the SA by manual keying using +.Xr setkey 8 . +Put the decimal number as the identifier after the .Li unique -like -.Li unique : number . +keyword in this way: +.Li unique : number , +where .Li number -must be between 1 and 32767 . +must be between 1 and 32767. +.Pp If the .Ar request string is kept unambiguous, .Ar level -and slash prior to +and the slash prior to .Ar level -can be omitted. -However, it is encouraged to specify them explicitly +can be omitted but you are encouraged to specify them explicitly to avoid unintended behaviors. If .Ar level @@ -239,47 +269,66 @@ is omitted, it will be interpreted as .El .El .Pp -Note that there is a bit difference of specification from +Note that there is a difference between the specification allowed here +and in .Xr setkey 8 . -In specification by +When specifying security policies with .Xr setkey 8 , -both entrust and bypass are not used. +neither entrust nor bypass are used. Refer to .Xr setkey 8 -for detail. -.Pp -Here are several examples -(long lines are wrapped for readability): +for details. +.Sh EXAMPLES +Set a policy that all inbound packets are discarded. .Bd -literal -offset indent 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 ipcomp/transport//use - esp/transport//use + .Ed +.\" +All outbound packets are required to be processed by IPsec and +transported using ESP. +.Bd -literal -offset indent +out ipsec esp/transport//require + +.Ed +.\" +All inbound packets are required to be authenticated using the AH protocol. +.Bd -literal -offset indent +in ipsec ah/transport//require + +.Ed +.\" +Tunnel packets outbound through the endpoints at 10.1.1.2 and 10.1.1.1. +.Bd -literal -offset indent +out ipsec esp/tunnel/10.1.1.2-10.1.1.1/require + +.Ed +.\" .Sh RETURN VALUES The .Fn ipsec_set_policy -function returns a pointer to the allocated buffer of policy specification if -successful; otherwise a NULL pointer is returned. +function returns a pointer to the allocated buffer containing a the +policy specification if successful; otherwise a NULL pointer is +returned. +.Pp The .Fn ipsec_get_policylen -function returns with positive value -(meaning the buffer size) -on success, and negative value on errors. +function returns a positive value, +indicating the buffer size, +on success, and a negative value on error. +.Pp The .Fn ipsec_dump_policy -function returns a pointer to dynamically allocated region on success, -and +function returns a pointer to a dynamically allocated region +containing a human readable security policy on success, and .Dv NULL -on errors. +on error. .Sh SEE ALSO .Xr ipsec_strerror 3 , .Xr ipsec 4 , .Xr setkey 8 .Sh HISTORY -The functions first appeared in WIDE/KAME IPv6 protocol stack kit. +These functions first appeared in WIDE/KAME IPv6 protocol stack kit. .Pp IPv6 and IPsec support based on the KAME Project (http://www.kame.net/) stack was initially integrated into diff --git a/lib/libipsec/ipsec_strerror.3 b/lib/libipsec/ipsec_strerror.3 index 982d1959ed03..d162fa63eb2a 100644 --- a/lib/libipsec/ipsec_strerror.3 +++ b/lib/libipsec/ipsec_strerror.3 @@ -29,13 +29,13 @@ .\" .\" $FreeBSD$ .\" -.Dd May 6, 1998 +.Dd February 14, 2006 .Dt IPSEC_STRERROR 3 .Os .\" .Sh NAME .Nm ipsec_strerror -.Nd error message for IPsec policy manipulation library +.Nd error messages for the IPsec policy manipulation library .\" .Sh SYNOPSIS .In netinet6/ipsec.h @@ -49,7 +49,7 @@ declares .Dl extern int ipsec_errcode; .Pp which is used to pass an error code from IPsec policy manipulation library -to an user program. +to a user program. The .Fn ipsec_strerror function can be used to obtain the error message string for the error code. @@ -59,19 +59,19 @@ Since .Fn ipsec_strerror uses .Xr strerror 3 -as underlying function, calling +as an underlying function, calling .Xr strerror 3 after .Fn ipsec_strerror -would make the return value from +would overwrite the the return value from .Fn ipsec_strerror -invalid, or overwritten. +and make it invalid. .\" .Sh RETURN VALUES The .Fn ipsec_strerror function always returns a pointer to C string. -The C string must not be overwritten by user programs. +The C string must not be overwritten by the caller. .\" .Sh SEE ALSO .Xr ipsec_set_policy 3 diff --git a/share/man/man4/ipsec.4 b/share/man/man4/ipsec.4 index 1593a21a19c2..547977662142 100644 --- a/share/man/man4/ipsec.4 +++ b/share/man/man4/ipsec.4 @@ -41,42 +41,44 @@ .In netinet6/ipsec.h .Sh DESCRIPTION .Nm -is a security protocol in Internet Protocol layer. +is a security protocol implemented within the Internet Protocol layer +of the TCP/IP stack. .Nm is defined for both IPv4 and IPv6 .Xr ( inet 4 and .Xr inet6 4 ) . .Nm -consists of two sub-protocols, namely -ESP -(encapsulated security payload) -and AH -(authentication header). -ESP protects IP payload from wire-tapping by encrypting it by +contains two protocols, +ESP, the encapsulated security payload protocol and +AH, the authentication header protocol. +ESP prevents unauthorized parties from reading the payload of an IP packet +by encrypting it using secret key cryptography algorithms. -AH guarantees integrity of IP packet -and protects it from intermediate alteration or impersonation, -by attaching cryptographic checksum computed by one-way hash functions. +AH both authenticates guarantees the integrity of an IP packet +by attaching a cryptographic checksum computed using one-way hash functions. .Nm -has two operation modes: transport mode and tunnel mode. -Transport mode is for protecting peer-to-peer communication between end nodes. -Tunnel mode includes IP-in-IP encapsulation operation -and is designed for security gateways, like VPN configurations. +has operates in one of two modes: transport mode or tunnel mode. +Transport mode is used to protect peer-to-peer communication between end nodes. +Tunnel mode encapsulates IP packets within other IP packets +and is designed for security gateways such as VPN endpoints. .\" .Ss Kernel interface .Nm -is controlled by key management engine and policy engine, -in the operating system kernel. +is controlled by a key management and policy engine, +that reside in the operating system kernel. Key management +is the process of associating keys with security associations, also +know as SAs. Policy management dictates when new security +associations created or destroyed. .Pp -Key management engine can be accessed from the userland by using +The key management engine can be accessed from userland by using .Dv PF_KEY sockets. The .Dv PF_KEY socket API is defined in RFC2367. .Pp -Policy engine can be controlled by extended part of +The policy engine is controlled by an extension to the .Dv PF_KEY API, .Xr setsockopt 2 @@ -84,48 +86,41 @@ operations, and .Xr sysctl 3 interface. The kernel implements -extended version of +an extended version of the .Dv PF_KEY -interface, and allows you to define IPsec policy like per-packet filters. +interface, and allows the programmer to define IPsec policies +which are similar to the per-packet filters. The .Xr setsockopt 2 interface is used to define per-socket behavior, and .Xr sysctl 3 interface is used to define host-wide default behavior. .Pp -The kernel code does not implement dynamic encryption key exchange protocol -like IKE +The kernel code does not implement a dynamic encryption key exchange protocol +such as IKE (Internet Key Exchange). -That should be implemented as userland programs -(usually as daemons), -by using the above described APIs. +Key exchange protocols are beyond what is necessary in the kernel and +should be implemented as daemon processes which call the +.Nm APIs. .\" .Ss Policy management -The kernel implements experimental policy management code. -You can manage the IPsec policy in two ways. -One is to configure per-socket policy using -.Xr setsockopt 2 . -The other is to configure kernel packet filter-based policy using +IPSec policies can be managed in one of two ways, either by +configuring per-socket policies using the +.Xr setsockopt 2 +system calls, or by configuring kernel level packet filter-based +policies using the .Dv PF_KEY -interface, via -.Xr setkey 8 . -In both cases, IPsec policy must be specified with syntax described in +interface, via the +.Xr setkey 8 +command. +In either cases, IPsec policies must be specified using the syntax described in .Xr ipsec_set_policy 3 . -.Pp -With -.Xr setsockopt 2 , -you can define IPsec policy in per-socket basis. -You can enforce particular IPsec policy onto packets that go through -particular socket. -.Pp -With +Please refer to the .Xr setkey 8 -you can define IPsec policy against packets, -using sort of packet filtering rule. -Refer to -.Xr setkey 8 -on how to use it. +man page for instructionson its use. .Pp -In the latter case, +When setting policies using the +.Xr setkey 8 +command the .Dq Li default policy is allowed for use with .Xr setkey 8 .