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