1 // Copyright 2013 The Go Authors. All rights reserved.
2 // Use of this source code is governed by a BSD-style
3 // license that can be found in the LICENSE file.
4 5 // Package ipv6 implements IP-level socket options for the Internet
6 // Protocol version 6.
7 //
8 // The package provides IP-level socket options that allow
9 // manipulation of IPv6 facilities.
10 //
11 // The IPv6 protocol is defined in RFC 8200.
12 // Socket interface extensions are defined in RFC 3493, RFC 3542 and
13 // RFC 3678.
14 // MLDv1 and MLDv2 are defined in RFC 2710 and RFC 3810.
15 // Source-specific multicast is defined in RFC 4607.
16 //
17 // On Darwin, this package requires OS X Mavericks version 10.9 or
18 // above, or equivalent.
19 //
20 // # Unicasting
21 //
22 // The options for unicasting are available for net.TCPConn,
23 // net.UDPConn and net.IPConn which are created as network connections
24 // that use the IPv6 transport. When a single TCP connection carrying
25 // a data flow of multiple packets needs to indicate the flow is
26 // important, Conn is used to set the traffic class field on the IPv6
27 // header for each packet.
28 //
29 // ln, err := net.Listen("tcp6", "[::]:1024")
30 // if err != nil {
31 // // error handling
32 // }
33 // defer ln.Close()
34 // for {
35 // c, err := ln.Accept()
36 // if err != nil {
37 // // error handling
38 // }
39 // go func(c net.Conn) {
40 // defer c.Close()
41 //
42 // The outgoing packets will be labeled DiffServ assured forwarding
43 // class 1 low drop precedence, known as AF11 packets.
44 //
45 // if err := ipv6.NewConn(c).SetTrafficClass(0x28); err != nil {
46 // // error handling
47 // }
48 // if _, err := c.Write(data); err != nil {
49 // // error handling
50 // }
51 // }(c)
52 // }
53 //
54 // # Multicasting
55 //
56 // The options for multicasting are available for net.UDPConn and
57 // net.IPConn which are created as network connections that use the
58 // IPv6 transport. A few network facilities must be prepared before
59 // you begin multicasting, at a minimum joining network interfaces and
60 // multicast groups.
61 //
62 // en0, err := net.InterfaceByName("en0")
63 // if err != nil {
64 // // error handling
65 // }
66 // en1, err := net.InterfaceByIndex(911)
67 // if err != nil {
68 // // error handling
69 // }
70 // group := net.ParseIP("ff02::114")
71 //
72 // First, an application listens to an appropriate address with an
73 // appropriate service port.
74 //
75 // c, err := net.ListenPacket("udp6", "[::]:1024")
76 // if err != nil {
77 // // error handling
78 // }
79 // defer c.Close()
80 //
81 // Second, the application joins multicast groups, starts listening to
82 // the groups on the specified network interfaces. Note that the
83 // service port for transport layer protocol does not matter with this
84 // operation as joining groups affects only network and link layer
85 // protocols, such as IPv6 and Ethernet.
86 //
87 // p := ipv6.NewPacketConn(c)
88 // if err := p.JoinGroup(en0, &net.UDPAddr{IP: group}); err != nil {
89 // // error handling
90 // }
91 // if err := p.JoinGroup(en1, &net.UDPAddr{IP: group}); err != nil {
92 // // error handling
93 // }
94 //
95 // The application might set per packet control message transmissions
96 // between the protocol stack within the kernel. When the application
97 // needs a destination address on an incoming packet,
98 // SetControlMessage of PacketConn is used to enable control message
99 // transmissions.
100 //
101 // if err := p.SetControlMessage(ipv6.FlagDst, true); err != nil {
102 // // error handling
103 // }
104 //
105 // The application could identify whether the received packets are
106 // of interest by using the control message that contains the
107 // destination address of the received packet.
108 //
109 // b := make([]byte, 1500)
110 // for {
111 // n, rcm, src, err := p.ReadFrom(b)
112 // if err != nil {
113 // // error handling
114 // }
115 // if rcm.Dst.IsMulticast() {
116 // if rcm.Dst.Equal(group) {
117 // // joined group, do something
118 // } else {
119 // // unknown group, discard
120 // continue
121 // }
122 // }
123 //
124 // The application can also send both unicast and multicast packets.
125 //
126 // p.SetTrafficClass(0x0)
127 // p.SetHopLimit(16)
128 // if _, err := p.WriteTo(data[:n], nil, src); err != nil {
129 // // error handling
130 // }
131 // dst := &net.UDPAddr{IP: group, Port: 1024}
132 // wcm := ipv6.ControlMessage{TrafficClass: 0xe0, HopLimit: 1}
133 // for _, ifi := range []*net.Interface{en0, en1} {
134 // wcm.IfIndex = ifi.Index
135 // if _, err := p.WriteTo(data[:n], &wcm, dst); err != nil {
136 // // error handling
137 // }
138 // }
139 // }
140 //
141 // # More multicasting
142 //
143 // An application that uses PacketConn may join multiple multicast
144 // groups. For example, a UDP listener with port 1024 might join two
145 // different groups across over two different network interfaces by
146 // using:
147 //
148 // c, err := net.ListenPacket("udp6", "[::]:1024")
149 // if err != nil {
150 // // error handling
151 // }
152 // defer c.Close()
153 // p := ipv6.NewPacketConn(c)
154 // if err := p.JoinGroup(en0, &net.UDPAddr{IP: net.ParseIP("ff02::1:114")}); err != nil {
155 // // error handling
156 // }
157 // if err := p.JoinGroup(en0, &net.UDPAddr{IP: net.ParseIP("ff02::2:114")}); err != nil {
158 // // error handling
159 // }
160 // if err := p.JoinGroup(en1, &net.UDPAddr{IP: net.ParseIP("ff02::2:114")}); err != nil {
161 // // error handling
162 // }
163 //
164 // It is possible for multiple UDP listeners that listen on the same
165 // UDP port to join the same multicast group. The net package will
166 // provide a socket that listens to a wildcard address with reusable
167 // UDP port when an appropriate multicast address prefix is passed to
168 // the net.ListenPacket or net.ListenUDP.
169 //
170 // c1, err := net.ListenPacket("udp6", "[ff02::]:1024")
171 // if err != nil {
172 // // error handling
173 // }
174 // defer c1.Close()
175 // c2, err := net.ListenPacket("udp6", "[ff02::]:1024")
176 // if err != nil {
177 // // error handling
178 // }
179 // defer c2.Close()
180 // p1 := ipv6.NewPacketConn(c1)
181 // if err := p1.JoinGroup(en0, &net.UDPAddr{IP: net.ParseIP("ff02::114")}); err != nil {
182 // // error handling
183 // }
184 // p2 := ipv6.NewPacketConn(c2)
185 // if err := p2.JoinGroup(en0, &net.UDPAddr{IP: net.ParseIP("ff02::114")}); err != nil {
186 // // error handling
187 // }
188 //
189 // Also it is possible for the application to leave or rejoin a
190 // multicast group on the network interface.
191 //
192 // if err := p.LeaveGroup(en0, &net.UDPAddr{IP: net.ParseIP("ff02::114")}); err != nil {
193 // // error handling
194 // }
195 // if err := p.JoinGroup(en0, &net.UDPAddr{IP: net.ParseIP("ff01::114")}); err != nil {
196 // // error handling
197 // }
198 //
199 // # Source-specific multicasting
200 //
201 // An application that uses PacketConn on MLDv2 supported platform is
202 // able to join source-specific multicast groups.
203 // The application may use JoinSourceSpecificGroup and
204 // LeaveSourceSpecificGroup for the operation known as "include" mode,
205 //
206 // ssmgroup := net.UDPAddr{IP: net.ParseIP("ff32::8000:9")}
207 // ssmsource := net.UDPAddr{IP: net.ParseIP("fe80::cafe")}
208 // if err := p.JoinSourceSpecificGroup(en0, &ssmgroup, &ssmsource); err != nil {
209 // // error handling
210 // }
211 // if err := p.LeaveSourceSpecificGroup(en0, &ssmgroup, &ssmsource); err != nil {
212 // // error handling
213 // }
214 //
215 // or JoinGroup, ExcludeSourceSpecificGroup,
216 // IncludeSourceSpecificGroup and LeaveGroup for the operation known
217 // as "exclude" mode.
218 //
219 // exclsource := net.UDPAddr{IP: net.ParseIP("fe80::dead")}
220 // if err := p.JoinGroup(en0, &ssmgroup); err != nil {
221 // // error handling
222 // }
223 // if err := p.ExcludeSourceSpecificGroup(en0, &ssmgroup, &exclsource); err != nil {
224 // // error handling
225 // }
226 // if err := p.LeaveGroup(en0, &ssmgroup); err != nil {
227 // // error handling
228 // }
229 //
230 // Note that it depends on each platform implementation what happens
231 // when an application which runs on MLDv2 unsupported platform uses
232 // JoinSourceSpecificGroup and LeaveSourceSpecificGroup.
233 // In general the platform tries to fall back to conversations using
234 // MLDv1 and starts to listen to multicast traffic.
235 // In the fallback case, ExcludeSourceSpecificGroup and
236 // IncludeSourceSpecificGroup may return an error.
237 package ipv6 // import "golang.org/x/net/ipv6"
238 239 // BUG(mikio): This package is not implemented on JS, NaCl and Plan 9.
240