/share/man/man4/send.4

https://bitbucket.org/freebsd/freebsd-head/ · Forth · 214 lines · 212 code · 0 blank · 2 comment · 12 complexity · 96f78e33dce76d94c549eb23302670c4 MD5 · raw file

  1. .\"-
  2. .\" Copyright (c) 2010 Ana Kukec
  3. .\" All rights reserved.
  4. .\"
  5. .\" Redistribution and use in source and binary forms, with or without
  6. .\" modification, are permitted provided that the following conditions
  7. .\" are met:
  8. .\" 1. Redistributions of source code must retain the above copyright
  9. .\" notice, this list of conditions and the following disclaimer.
  10. .\" 2. Redistributions in binary form must reproduce the above copyright
  11. .\" notice, this list of conditions and the following disclaimer in the
  12. .\" documentation and/or other materials provided with the distribution.
  13. .\"
  14. .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  15. .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  16. .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  17. .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  18. .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  19. .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  20. .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  21. .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  22. .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  23. .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  24. .\" SUCH DAMAGE.
  25. .\"
  26. .\" $FreeBSD$
  27. .\"
  28. .Dd September 19, 2010
  29. .Dt SEND 4
  30. .Os
  31. .Sh NAME
  32. .Nm send
  33. .Nd "Kernel side support for Secure Neighbor Discovery (SeND)"
  34. .Sh SYNOPSIS
  35. .In sys/socket.h
  36. .In netinet/in.h
  37. .In netinet6/send.h
  38. .Ft int
  39. .Fn socket PF_INET6 SOCK_RAW IPPROTO_SEND
  40. .Pp
  41. To load the driver as a module at boot time, place the following line in
  42. .Xr loader.conf 5 :
  43. .Bd -literal -offset indent
  44. send_load="YES"
  45. .Ed
  46. .Sh DESCRIPTION
  47. IPv6 nodes use the Neighbor Discovery Protocol (NDP) to discover other nodes
  48. on the link, to determine their link-layer addresses to find routers, and
  49. to maintain reachability information about the paths to active members.
  50. NDP is vulnerable to various attacks [RFC3756].
  51. Secure Neighbor Discovery is a set of extensions to NDP that counter threats
  52. to NDP [RFC3971].
  53. .Pp
  54. Kernel side support for SeND consists of a kernel module with hooks that
  55. divert relevant packets (Neighbor Solicitations, Neighbor Advertisements,
  56. Router Solicitations, Router Advertisements and Redirects) from the NDP stack,
  57. send them to user space on a dedicated socket and reinject them back for
  58. further processing.
  59. Hooks are triggered only if the
  60. .Nm
  61. module is loaded.
  62. .Pp
  63. The native SeND socket is similar to a raw IP socket, but with its own,
  64. internal pseudo-protocol (IPPROTO_SEND).
  65. Struct sockaddr_send is defined in
  66. .In netinet6/send.h .
  67. It defines the total length of the structure, the address family, packet's
  68. incoming or outgoing direction from the interface's point of view, and the
  69. interface index.
  70. .Bd -literal
  71. struct sockaddr_send {
  72. unsigned char send_len; /* total length */
  73. sa_family_t send_family; /* address family */
  74. int send_direction;
  75. int send_ifidx;
  76. char send_zero[8];
  77. };
  78. .Ed
  79. .Pp
  80. The address family is always
  81. .Va AF_INET6 .
  82. The
  83. .Va send_direction
  84. variable denotes the direction of the packet from the interface's
  85. point of view and has either the value
  86. .Dv SND_IN
  87. or
  88. .Dv SND_OUT .
  89. The
  90. .Va send_ifidx
  91. variable is the interface index of the receiving or sending interface.
  92. The
  93. .Va send_zero
  94. variable is padding and must always be zero.
  95. .Pp
  96. In case that no user space application is connected to the send socket,
  97. processing continues normally as if the module was not loaded.
  98. .Sh INPUT HOOK
  99. The input hook is named after the input path of the incoming or outgoing
  100. NDP packets, on the way from the wire, through the nd6 stack, to user
  101. space.
  102. Relevant packets are identified by adding an mbuf_tag
  103. (see
  104. .Xr mbuf_tags 9 )
  105. to the
  106. .Xr mbuf 9 ,
  107. if the
  108. .Nm
  109. module is loaded.
  110. It is then passed on to the kernel-userland interface
  111. for either cryptographic protection or validation by the SeND application.
  112. The hook takes an argument that describes the direction of the packet, both
  113. in case of incoming and outgoing packets.
  114. .Dv SND_IN
  115. is the direction of the incoming packets that are usually protected
  116. by the SeND options and then sent to user space for cryptographic validation.
  117. .Dv SND_OUT
  118. is the outgoing direction.
  119. It describes both reply and locally
  120. originated outgoing packets that are sent to user space for the addition
  121. of SeND options.
  122. .Sh INCOMING PACKETS
  123. The incoming ND packet from the wire:
  124. .Bd -literal
  125. kernelspace ( userspace
  126. )
  127. incoming SeND/ND packet (
  128. | )
  129. v ( SND_IN ) (
  130. icmp6_input() -> send_input_hook ---> send socket ----+
  131. : ) |
  132. : # # ( |
  133. normal : # # ) v
  134. processing : # send.ko # ( SeND application
  135. path : # # ) |
  136. : # # ( |
  137. v ) |
  138. icmp6/nd6_??_input() <- protocol switch <--- send socket <---+
  139. | structure (IPPPROTO_SEND) )
  140. | ( SND_IN ) (
  141. v )
  142. continue normal ND processing (
  143. .Ed
  144. .Sh OUTGOING PACKETS
  145. Outgoing ND packet (reply or locally triggered):
  146. .Bd -literal
  147. kernelspace ( userspace
  148. )
  149. nd6_na_input() (
  150. +PACKET_TAG_ND_OUTGOING )
  151. | )
  152. | outgoing packet (
  153. | | )
  154. | v (
  155. | icmp6_redirect_output() )
  156. | nd6_ns_output() (
  157. | nd6_na_output() )
  158. | +PACKET_TAG_ND_OUTGOING (
  159. | | )
  160. | +-----------<- rip6_output() <----------)----- rtsol/rtadvd/..
  161. | | +PACKET_TAG_ND_OUTGOING (
  162. | v )
  163. | ip6_output() (
  164. | | )
  165. +-------->-+ (
  166. | )
  167. v ( SND_OUT ) (
  168. nd6_output_lle() -> send_input_hook ---> send socket ----+
  169. -PACKET_TAG_ND_OUTGOING ) |
  170. : # # ( |
  171. normal : # # ) v
  172. processing : # send.ko # ( SeND application
  173. path : # # ) |
  174. : # # ( |
  175. v ) |
  176. (*ifp->if_output)() <- protocol switch <--- send socket <---+
  177. | structure (IPPPROTO_SEND) )
  178. | ( SND_OUT ) (
  179. v )
  180. continue with normal packet output (
  181. .Ed
  182. .Sh ERRORS
  183. A socket operation may fail with one of the following errors returned:
  184. .Bl -tag -width Er
  185. .It Bq Er EEXIST
  186. Another user space SeND application is bound to the socket.
  187. .It Bq Er ENOBUFS
  188. Shortage of space to receive the incoming (SeND-protected) or outgoing
  189. (SeND-validated) packet from the SeND application.
  190. .It Bq Er ENOSYS
  191. A packet received from user space and passed to the NDP stack for further
  192. processing is neither Neighbor Solicitation, Neighbor Advertisement,
  193. Router Solicitation, Router Advertisement nor Redirect.
  194. .It Bq Er ENOENT
  195. Occurs if interface output routines fail to send the packet out of the
  196. interface.
  197. .El
  198. .Sh SEE ALSO
  199. .Xr recvfrom 2
  200. .Xr sendto 2
  201. .Xr socket 2
  202. .Xr loader.conf 5
  203. .Sh HISTORY
  204. The
  205. .Nm
  206. module first appeared in
  207. .Fx 9.0 .
  208. .Sh AUTHORS
  209. .An Ana Kukec Aq anchie@FreeBSD.org ,
  210. University of Zagreb
  211. .Sh BUGS
  212. Due to the lack of NDP locking, it is currently not possible to unload the
  213. .Nm
  214. module.