diff options
author | gnn <gnn@FreeBSD.org> | 2006-02-14 13:02:00 +0000 |
---|---|---|
committer | gnn <gnn@FreeBSD.org> | 2006-02-14 13:02:00 +0000 |
commit | a3483ac2d7eb6c19372be10483ab7c4303909e84 (patch) | |
tree | 00a1e2b6da9875a2dcb443971b63f0bdee40ebf3 /lib/libipsec | |
parent | f6f0b57cbaf4d31fcc661b3e9d25c3cb1a394bef (diff) | |
download | FreeBSD-src-a3483ac2d7eb6c19372be10483ab7c4303909e84.zip FreeBSD-src-a3483ac2d7eb6c19372be10483ab7c4303909e84.tar.gz |
Clean up some descriptions and remove ambiguities in the language.
Add explanations to the examples.
MFC after: 1 week
Diffstat (limited to 'lib/libipsec')
-rw-r--r-- | lib/libipsec/ipsec_set_policy.3 | 229 | ||||
-rw-r--r-- | lib/libipsec/ipsec_strerror.3 | 14 |
2 files changed, 146 insertions, 97 deletions
diff --git a/lib/libipsec/ipsec_set_policy.3 b/lib/libipsec/ipsec_set_policy.3 index 048aa7f..8be32f5 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 +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 -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). +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 + +.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 -out ipsec esp/tunnel/10.1.1.2-10.1.1.1/use -in ipsec ipcomp/transport//use - esp/transport//use + +.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 982d195..d162fa6 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 |