common.go 15 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580
  1. // common.go - Transport common implementation.
  2. // Copyright (C) 2016 Yawning Angel.
  3. //
  4. // This program is free software: you can redistribute it and/or modify
  5. // it under the terms of the GNU Affero General Public License as
  6. // published by the Free Software Foundation, either version 3 of the
  7. // License, or (at your option) any later version.
  8. //
  9. // This program is distributed in the hope that it will be useful,
  10. // but WITHOUT ANY WARRANTY; without even the implied warranty of
  11. // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  12. // GNU Affero General Public License for more details.
  13. //
  14. // You should have received a copy of the GNU Affero General Public License
  15. // along with this program. If not, see <http://www.gnu.org/licenses/>.
  16. // Package basket2 implements the basket2 authenticated/encrypted/obfuscated
  17. // network transport protocol.
  18. //
  19. // Note that the package will block during init() if the system entropy pool
  20. // is not properly initialized on systems where there is support for
  21. // determining this information. This is a feature, and "working around" this
  22. // "bug" will likely totally destroy security.
  23. package basket2
  24. import (
  25. "errors"
  26. "fmt"
  27. "io"
  28. mrand "math/rand"
  29. "net"
  30. "sync"
  31. "time"
  32. "git.schwanenlied.me/yawning/basket2.git/crypto/rand"
  33. "git.schwanenlied.me/yawning/basket2.git/framing"
  34. "git.schwanenlied.me/yawning/basket2.git/framing/tentp"
  35. )
  36. const (
  37. // ProtocolVersion is the transport protocol version.
  38. ProtocolVersion = 0
  39. // PaddingInvalid is a invalid/undefined padding method.
  40. PaddingInvalid PaddingMethod = 0xff
  41. minReqExtDataSize = 1 + 1 + 1 // Version, nrPaddingAlgs, > 1 padding alg.
  42. minRespExtDataSize = 1 + 1 + 1 // Version, authPolicy, padding alg.
  43. tauReadDelay = 5000 // Microseconds.
  44. defaultCopyBufferSize = 32 * 1024
  45. )
  46. var (
  47. // ErrInvalidState is the error returned on an invalid state or transition.
  48. ErrInvalidState = errors.New("basket2: invalid state")
  49. // ErrInvalidCmd is the error returned on decoding a framing packet with
  50. // an invalid command.
  51. ErrInvalidCmd = errors.New("basket2: invalid command")
  52. // ErrInvalidPadding is the error returned when the client requests no
  53. // compatible padding methods, or the server specifies a incompatible
  54. // padding method.
  55. ErrInvalidPadding = errors.New("basket2: invalid padding")
  56. // ErrMsgSize is the error returned on a message size violation.
  57. ErrMsgSize = errors.New("basket2: oversized message")
  58. // ErrInvalidExtData is the error returned when the req/resp handshake
  59. // extData is invalid.
  60. ErrInvalidExtData = errors.New("basket2: invalid ext data")
  61. // ErrInvalidAuth is the error returned when the authentication credentials
  62. // or signature was invalid, or the client authentication otherwise failed.
  63. ErrInvalidAuth = errors.New("basket2: invalid auth")
  64. // ErrNotSupported is the error returned on an unsupported call.
  65. ErrNotSupported = errors.New("basket2: operation not supported")
  66. supportedPaddingMethods = []PaddingMethod{
  67. PaddingTamarawBulk,
  68. PaddingTamaraw,
  69. PaddingObfs4PacketIAT,
  70. PaddingObfs4BurstIAT,
  71. PaddingObfs4Burst,
  72. PaddingNull,
  73. }
  74. )
  75. // PaddingMethod is a given padding algorithm identifier.
  76. type PaddingMethod byte
  77. // AuthPolicy is the server authentication policy.
  78. type AuthPolicy byte
  79. const (
  80. // AuthNone indicates that the client must not authenticate.
  81. AuthNone AuthPolicy = iota
  82. // AuthMust indicates that the client must authenticate.
  83. AuthMust
  84. )
  85. type connState int
  86. const (
  87. stateInit connState = iota
  88. stateHandshaking
  89. stateAuthenticate
  90. stateEstablished
  91. stateError
  92. )
  93. // ToHexString returns the hexdecimal string representation of a padding method.
  94. func (m PaddingMethod) ToHexString() string {
  95. return fmt.Sprintf("%02x", m)
  96. }
  97. // ToString returms the descriptive string representaiton of a padding method.
  98. func (m PaddingMethod) ToString() string {
  99. switch m {
  100. case PaddingNull:
  101. return "Null"
  102. case PaddingObfs4Burst:
  103. return "Obfs4Burst"
  104. case PaddingObfs4BurstIAT:
  105. return "Obfs4BurstIAT"
  106. case PaddingObfs4PacketIAT:
  107. return "Obfs4PacketIAT"
  108. case PaddingTamaraw:
  109. return "Tamaraw"
  110. case PaddingTamarawBulk:
  111. return "TamarawBulk"
  112. default:
  113. return "[Unknown algorithm]"
  114. }
  115. }
  116. // PaddingMethodFromString returns the PaddingMethod corresponding to a given
  117. // string.
  118. func PaddingMethodFromString(s string) PaddingMethod {
  119. switch s {
  120. case "Null":
  121. return PaddingNull
  122. case "Obfs4Burst":
  123. return PaddingObfs4Burst
  124. case "Obfs4BurstIAT":
  125. return PaddingObfs4BurstIAT
  126. case "Obfs4PacketIAT":
  127. return PaddingObfs4PacketIAT
  128. case "Tamaraw":
  129. return PaddingTamaraw
  130. case "TamarawBulk":
  131. return PaddingTamarawBulk
  132. default:
  133. return PaddingInvalid
  134. }
  135. }
  136. // ConnStats contains the per-connection metrics useful for examining the
  137. // overhead/performance of the various padding algorithms.
  138. type ConnStats struct {
  139. RxBytes uint64
  140. RxOverheadBytes uint64
  141. RxPayloadBytes uint64
  142. RxPaddingBytes uint64
  143. TxBytes uint64
  144. TxOverheadBytes uint64
  145. TxPayloadBytes uint64
  146. TxPaddingBytes uint64
  147. }
  148. // ToString returns the descriptive string representation of the connection
  149. // statistics.
  150. func (s *ConnStats) ToString() string {
  151. rxGoodput := float64(s.RxPayloadBytes) / float64(s.RxBytes)
  152. txGoodput := float64(s.TxPayloadBytes) / float64(s.TxBytes)
  153. return fmt.Sprintf("Receive: Total: %v Overhead: %v Payload: %v Padding: %v Goodput: %v Trasmit: Total: %v Overhead: %v Payload: %v Padding: %v Goodput: %v", s.RxBytes, s.RxOverheadBytes, s.RxPayloadBytes, s.RxPaddingBytes, rxGoodput, s.TxBytes, s.TxOverheadBytes, s.TxPayloadBytes, s.TxPaddingBytes, txGoodput)
  154. }
  155. type commonConn struct {
  156. sync.Mutex
  157. mRNG *mrand.Rand
  158. state connState
  159. stats ConnStats
  160. rawConn net.Conn
  161. txEncoder *tentp.Encoder
  162. rxDecoder *tentp.Decoder
  163. impl paddingImpl
  164. paddingMethod PaddingMethod
  165. maxRecordSize int
  166. copyBufferSize int
  167. enforceRecordSize bool
  168. enableReadDelay bool
  169. isClient bool
  170. }
  171. // Stats returns the connection's ConnStats structure.
  172. func (c *commonConn) Stats() *ConnStats {
  173. return &c.stats
  174. }
  175. // SetCopyBufferSize sets the hint used to detect large bulk transfers
  176. // when the connection is the destination side of io.Copy()/io.CopyBuffer().
  177. // By default something sensible for io.Copy() will be used.
  178. func (c *commonConn) SetCopyBufferSize(sz int) {
  179. if sz <= 0 {
  180. panic("basket2: SetCopyBufferSize called with invalid value")
  181. }
  182. c.copyBufferSize = sz
  183. }
  184. // Write writes len(p) bytes to the stream, and returns the number of bytes
  185. // written, or an error. All errors must be considered fatal.
  186. func (c *commonConn) Write(p []byte) (n int, err error) {
  187. defer func() {
  188. if err != nil {
  189. c.setState(stateError)
  190. }
  191. }()
  192. if !c.stateAllowsIO() {
  193. return 0, ErrInvalidState
  194. }
  195. return c.impl.Write(p)
  196. }
  197. // Read reads up to len(p) bytes from the stream, and returns the number of
  198. // bytes read, or an error. All errors must be considered fatal.
  199. func (c *commonConn) Read(p []byte) (n int, err error) {
  200. defer func() {
  201. if err != nil {
  202. c.setState(stateError)
  203. }
  204. }()
  205. if !c.stateAllowsIO() {
  206. return 0, ErrInvalidState
  207. }
  208. n, err = c.impl.Read(p)
  209. if c.enableReadDelay && n > 0 {
  210. // If data payload was received and read delay is enabled,
  211. // delay for a random interval [0, 2 * tau) usec.
  212. //
  213. // This is primarily intended for the server side of the Tor
  214. // Pluggable transport code in an attempt to mitigate delay based
  215. // flow tagging attacks for upstream traffic into the Tor network.
  216. delay := time.Duration(c.mRNG.Intn(tauReadDelay*2)) * time.Microsecond
  217. time.Sleep(delay)
  218. }
  219. return n, err
  220. }
  221. // Close closes the connection and purges cryptographic keying material from
  222. // memory.
  223. func (c *commonConn) Close() error {
  224. err := c.rawConn.Close()
  225. c.setState(stateError)
  226. return err
  227. }
  228. // LocalAddr returns the local address of the connection.
  229. func (c *commonConn) LocalAddr() net.Addr {
  230. return c.rawConn.LocalAddr()
  231. }
  232. // RemoteAddr returns the remote address of the connection.
  233. func (c *commonConn) RemoteAddr() net.Addr {
  234. return c.rawConn.RemoteAddr()
  235. }
  236. // SetDeadline returns ErrNotSupported.
  237. func (c *commonConn) SetDeadline(t time.Time) error {
  238. return ErrNotSupported
  239. }
  240. // SetReadDeadline returns ErrNotSupported.
  241. func (c *commonConn) SetReadDeadline(t time.Time) error {
  242. return ErrNotSupported
  243. }
  244. // SetWriteDeadline returns ErrNotSupported.
  245. func (c *commonConn) SetWriteDeadline(t time.Time) error {
  246. return ErrNotSupported
  247. }
  248. func (c *commonConn) initConn(conn net.Conn) error {
  249. var err error
  250. if err = c.setState(stateHandshaking); err != nil {
  251. return err
  252. }
  253. c.paddingMethod = PaddingInvalid
  254. c.mRNG = rand.New()
  255. if c.copyBufferSize == 0 {
  256. c.copyBufferSize = defaultCopyBufferSize
  257. }
  258. // Derive the "max" record size based off the remote address,
  259. // under the assumption that 1500 byte MTU ethernet is in use.
  260. //
  261. // This value is intended as a hint for the padding algorithms
  262. // when determining how to size records, and may not actually
  263. // resemble what goes out on the wire depending on what the kernel
  264. // does and the state of the TCP/IP stack.
  265. if taddr, ok := conn.RemoteAddr().(*net.TCPAddr); ok {
  266. // For some reason, IP.To16() always returns something, regardless
  267. // of if it's correct or not, so check IPv4 first.
  268. if taddr.IP.To4() != nil {
  269. // Connected to an IPv4 peer.
  270. c.maxRecordSize = tentp.MaxIdealIPv4Size
  271. } else {
  272. // Connected to an IPv6 peer.
  273. c.maxRecordSize = tentp.MaxIdealIPv6Size
  274. }
  275. } else {
  276. // No idea what kind of connection this is, use the IPv4 max frame
  277. // size.
  278. c.maxRecordSize = tentp.MaxIdealIPv4Size
  279. }
  280. c.rawConn = conn
  281. return nil
  282. }
  283. func (c *commonConn) initFraming(kdf io.Reader) error {
  284. var err error
  285. if c.isClient {
  286. if c.txEncoder, err = tentp.NewEncoderFromKDF(kdf); err != nil {
  287. return err
  288. }
  289. if c.rxDecoder, err = tentp.NewDecoderFromKDF(kdf); err != nil {
  290. return err
  291. }
  292. } else {
  293. if c.rxDecoder, err = tentp.NewDecoderFromKDF(kdf); err != nil {
  294. return err
  295. }
  296. if c.txEncoder, err = tentp.NewEncoderFromKDF(kdf); err != nil {
  297. return err
  298. }
  299. }
  300. return nil
  301. }
  302. func (c *commonConn) setState(newState connState) error {
  303. c.Lock()
  304. defer c.Unlock()
  305. switch newState {
  306. case stateInit:
  307. panic("basket2: state transition to Init should NEVER happen")
  308. case stateHandshaking:
  309. if c.state != stateInit {
  310. return ErrInvalidState
  311. }
  312. case stateAuthenticate:
  313. if c.state != stateHandshaking {
  314. return ErrInvalidState
  315. }
  316. case stateEstablished:
  317. if c.state != stateHandshaking && c.state != stateAuthenticate {
  318. return ErrInvalidState
  319. }
  320. case stateError:
  321. // Transition to stateError is always allowed, and will obliterate
  322. // cryptographic material.
  323. if c.txEncoder != nil {
  324. c.txEncoder.Reset()
  325. c.txEncoder = nil
  326. }
  327. if c.rxDecoder != nil {
  328. c.rxDecoder.Reset()
  329. c.rxDecoder = nil
  330. }
  331. // If the padding implementation is present, call the termination
  332. // handler.
  333. if c.impl != nil {
  334. c.impl.OnClose()
  335. c.impl = nil
  336. }
  337. default:
  338. panic(fmt.Sprintf("basket2: state transition to unknown state: %v", newState))
  339. }
  340. c.state = newState
  341. return nil
  342. }
  343. func (c *commonConn) stateAllowsIO() bool {
  344. c.Lock()
  345. defer c.Unlock()
  346. return c.state == stateAuthenticate || c.state == stateEstablished
  347. }
  348. func (c *commonConn) setPadding(method PaddingMethod, params []byte) error {
  349. switch method {
  350. case PaddingNull:
  351. c.impl = newNullPadding(c)
  352. case PaddingObfs4Burst, PaddingObfs4BurstIAT, PaddingObfs4PacketIAT:
  353. var err error
  354. c.impl, err = newObfs4Padding(c, method, params)
  355. if err != nil {
  356. return err
  357. }
  358. case PaddingTamaraw, PaddingTamarawBulk:
  359. c.impl = newTamarawPadding(c, method, c.isClient)
  360. default:
  361. return ErrInvalidPadding
  362. }
  363. c.paddingMethod = method
  364. return nil
  365. }
  366. func (c *commonConn) setNagle(enable bool) {
  367. if tconn, ok := c.rawConn.(*net.TCPConn); ok {
  368. tconn.SetNoDelay(!enable)
  369. }
  370. }
  371. // SendRawRecord sends a raw record to the peer with the specified command,
  372. // payload and padding length. This call should NOT be interleaved/mixed
  373. // with the net.Conn Read/Write interface.
  374. func (c *commonConn) SendRawRecord(cmd byte, msg []byte, padLen int) (err error) {
  375. defer func() {
  376. if err != nil {
  377. c.setState(stateError)
  378. }
  379. }()
  380. // Validate the state.
  381. if !c.stateAllowsIO() {
  382. return ErrInvalidState
  383. }
  384. if !c.isClient {
  385. cmd |= framing.CmdServer
  386. }
  387. // Encode the TENTP record.
  388. var rec []byte
  389. rec, err = c.txEncoder.EncodeRecord(cmd, msg, padLen)
  390. if err != nil {
  391. return
  392. }
  393. // Transmit the record.
  394. var n int
  395. n, err = c.rawConn.Write(rec)
  396. if err != nil {
  397. return
  398. }
  399. if n != len(rec) {
  400. return io.ErrShortWrite
  401. }
  402. c.stats.TxBytes += uint64(len(rec))
  403. c.stats.TxPayloadBytes += uint64(len(msg))
  404. c.stats.TxOverheadBytes += uint64(len(rec) - (len(msg) + padLen))
  405. c.stats.TxPaddingBytes += uint64(padLen)
  406. return
  407. }
  408. // RecvRawRecord receives a raw record from the peer. This call should NOT be
  409. // interleaved/mixed with the net.Conn Read/Write interface.
  410. func (c *commonConn) RecvRawRecord() (cmd byte, msg []byte, err error) {
  411. defer func() {
  412. if err != nil {
  413. cmd = 0
  414. msg = nil
  415. c.setState(stateError)
  416. }
  417. }()
  418. // Validate the state.
  419. if !c.stateAllowsIO() {
  420. return 0, nil, ErrInvalidState
  421. }
  422. // Receive/Decode the TENTP header.
  423. var recHdr [tentp.FramingOverhead]byte
  424. if _, err = io.ReadFull(c.rawConn, recHdr[:]); err != nil {
  425. return
  426. }
  427. var want int
  428. cmd, want, err = c.rxDecoder.DecodeRecordHdr(recHdr[:])
  429. if err != nil {
  430. return
  431. }
  432. c.stats.RxBytes += tentp.FramingOverhead
  433. c.stats.RxOverheadBytes += tentp.FramingOverhead
  434. // Validate the command direction bit.
  435. cmdCtoS := cmd&framing.CmdServer == 0
  436. if c.isClient == cmdCtoS {
  437. return 0, nil, ErrInvalidCmd
  438. }
  439. cmd &= framing.CmdServerMask
  440. if want == 0 {
  441. // Record with no payload, return early.
  442. return
  443. }
  444. if c.enforceRecordSize && want > c.maxRecordSize+tentp.PayloadOverhead {
  445. return 0, nil, ErrMsgSize
  446. }
  447. // Receive/Decode the TENTP record body.
  448. recBody := make([]byte, want)
  449. if _, err = io.ReadFull(c.rawConn, recBody); err != nil {
  450. return
  451. }
  452. if msg, err = c.rxDecoder.DecodeRecordBody(recBody); err != nil {
  453. return
  454. }
  455. c.stats.RxBytes += uint64(want)
  456. c.stats.RxOverheadBytes += tentp.PayloadOverhead
  457. c.stats.RxPayloadBytes += uint64(len(msg))
  458. c.stats.RxPaddingBytes += uint64(want - (tentp.PayloadOverhead + len(msg)))
  459. return
  460. }
  461. // PaddingMethod returns the padding method negotiated with the peer. This
  462. // will only be set to something useful after a Handshake() call completes
  463. // successfully.
  464. func (c *commonConn) PaddingMethod() PaddingMethod {
  465. return c.paddingMethod
  466. }
  467. func paddingOk(needle PaddingMethod, haystack []PaddingMethod) bool {
  468. for _, v := range haystack {
  469. if needle == v {
  470. return true
  471. }
  472. }
  473. return false
  474. }
  475. // DefaultPaddingParams returns "sensible" parameters for each supported
  476. // padding method that requires parameterization.
  477. func DefaultPaddingParams(method PaddingMethod) ([]byte, error) {
  478. switch method {
  479. case PaddingNull, PaddingTamaraw, PaddingTamarawBulk:
  480. return nil, nil
  481. case PaddingObfs4Burst, PaddingObfs4BurstIAT, PaddingObfs4PacketIAT:
  482. return obfs4PaddingDefaultParams(method)
  483. }
  484. return nil, ErrInvalidPadding
  485. }
  486. // SupportedPaddingMethods returns the list of supported padding methods in
  487. // order of preference.
  488. func SupportedPaddingMethods() []PaddingMethod {
  489. var ret []PaddingMethod
  490. ret = append(ret, supportedPaddingMethods...)
  491. return ret
  492. }
  493. func init() {
  494. // This check is here for a reason. If you comment it out, you will
  495. // receive absolutely NO SUPPORT, and bug reports that do not contain
  496. // patches will be IGNORED.
  497. if !isRecentEnoughGo() {
  498. panic("basket2: built with a Go version that is too old")
  499. }
  500. }