├── README.md ├── CONTRIBUTING.md ├── LICENSE └── CONTRIBUTORS_GUIDE.md /README.md: -------------------------------------------------------------------------------- 1 | # Project Status 2 | uTLS was initially developed by Sergey Frolov during an internship at Jigsaw. 3 | 4 | This code is no longer being mainatained, but the Refraction Networking team has forked it and, as of October 2018, appears to be continuing development [here](https://github.com/refraction-networking/utls). 5 | 6 | You can view the last version of this repo's code at [this link](https://github.com/jigsaw-code/uTLS/tree/master) 7 | -------------------------------------------------------------------------------- /CONTRIBUTING.md: -------------------------------------------------------------------------------- 1 | # How to Contribute 2 | 3 | We'd love to accept your patches and contributions to this project. There are 4 | just a few small guidelines you need to follow. 5 | 6 | ## Contributor License Agreement 7 | 8 | Contributions to this project must be accompanied by a Contributor License 9 | Agreement. You (or your employer) retain the copyright to your contribution, 10 | this simply gives us permission to use and redistribute your contributions as 11 | part of the project. Head over to to see 12 | your current agreements on file or to sign a new one. 13 | 14 | You generally only need to submit a CLA once, so if you've already submitted one 15 | (even if it was for a different project), you probably don't need to do it 16 | again. 17 | 18 | ## Code reviews 19 | 20 | All submissions, including submissions by project members, require review. We 21 | use GitHub pull requests for this purpose. Consult 22 | [GitHub Help](https://help.github.com/articles/about-pull-requests/) for more 23 | information on using pull requests. -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | Copyright (c) 2009 The Go Authors. All rights reserved. 2 | 3 | Redistribution and use in source and binary forms, with or without 4 | modification, are permitted provided that the following conditions are 5 | met: 6 | 7 | * Redistributions of source code must retain the above copyright 8 | notice, this list of conditions and the following disclaimer. 9 | * Redistributions in binary form must reproduce the above 10 | copyright notice, this list of conditions and the following disclaimer 11 | in the documentation and/or other materials provided with the 12 | distribution. 13 | * Neither the name of Google Inc. nor the names of its 14 | contributors may be used to endorse or promote products derived from 15 | this software without specific prior written permission. 16 | 17 | THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 18 | "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 19 | LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR 20 | A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT 21 | OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 22 | SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT 23 | LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 24 | DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 25 | THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 26 | (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 27 | OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 28 | -------------------------------------------------------------------------------- /CONTRIBUTORS_GUIDE.md: -------------------------------------------------------------------------------- 1 | # How this package works 2 | ### Chapter 1: [Making private things public](./u_public.go) 3 | There are numerous handshake-related structs in crypto/tls, most of which are either private or have private fields. 4 | One of them — `clientHandshakeState` — has private function `handshake()`, 5 | which is called in the beginning of default handshake. 6 | Unfortunately, user will not be able to directly access this struct outside of tls package. 7 | As a result, we decided to employ following workaround: declare public copies of private structs. 8 | Now user is free to manipulate fields of public `ClientHandshakeState`. 9 | Then, right before handshake, we can shallow-copy public state into private `clientHandshakeState`, 10 | call `handshake()` on it and carry on with default Golang handshake process. 11 | After handshake is done we shallow-copy private state back to public, allowing user to read results of handshake. 12 | 13 | ### Chapter 2: [TLSExtension](./u_tls_extensions.go) 14 | The way we achieve reasonable flexibilty with extensions is inspired by 15 | [ztls'](https://github.com/zmap/zcrypto/blob/master/tls/handshake_extensions.go) design. 16 | However, our design has several differences, so we wrote it from scratch. 17 | This design allows us to have an array of `TLSExtension` objects and then marshal them in order: 18 | ```Golang 19 | type TLSExtension interface { 20 | writeToUConn(*UConn) error 21 | 22 | Len() int // includes header 23 | 24 | // Read reads up to len(p) bytes into p. 25 | // It returns the number of bytes read (0 <= n <= len(p)) and any error encountered. 26 | Read(p []byte) (n int, err error) // implements io.Reader 27 | } 28 | ``` 29 | `writeToUConn()` applies appropriate per-extension changes to `UConn`. 30 | 31 | `Len()` provides the size of marshaled extension, so we can allocate appropriate buffer beforehand, 32 | catch out-of-bound errors easily and guide size-dependent extensions such as padding. 33 | 34 | `Read(buffer []byte)` _writes(see: io.Reader interface)_ marshaled extensions into provided buffer. 35 | This avoids extra allocations. 36 | 37 | ### Chapter 3: [UConn](./u_conn.go) 38 | `UConn` extends standard `tls.Conn`. Most notably, it stores slice with `TLSExtension`s and public 39 | `ClientHandshakeState`. 40 | Whenever `UConn.BuildHandshakeState()` gets called (happens automatically in `UConn.Handshake()` 41 | or could be called manually), config will be applied according to chosen `ClientHelloID`. 42 | From contributor's view there are 2 main behaviors: 43 | * `HelloGolang` simply calls default Golang's [`makeClientHello()`](./handshake_client.go) 44 | and directly stores it into `HandshakeState.Hello`. utls-specific stuff is ignored. 45 | * Other ClientHelloIDs fill `UConn.Hello.{Random, CipherSuites, CompressionMethods}` and `UConn.Extensions` with 46 | per-parrot setup, which then gets applied to appropriate standard tls structs, 47 | and then marshaled by utls into `HandshakeState.Hello`. 48 | 49 | ### Chapter 4: Tests 50 | 51 | Tests exist, but coverage is very limited. What's covered is a conjunction of 52 | * TLS 1.2 53 | * Working parrots without any unsupported extensions (only Android 5.1 at this time) 54 | * Ciphersuites offered by parrot. 55 | * Ciphersuites supported by Golang 56 | * Simple conversation with reference implementation of OpenSSL. 57 | (e.g. no automatic checks for renegotiations, parroting quality and such) 58 | 59 | plus we test some other minor things. 60 | Basically, current tests aim to provide a sanity check. 61 | 62 | # Merging upstream 63 | ```Bash 64 | git remote add -f golang git@github.com:golang/go.git 65 | git checkout -b golang-upstream golang/master 66 | git subtree split -P src/crypto/tls/ -b golang-tls-upstream 67 | git checkout master 68 | git merge --no-commit golang-tls-upstream 69 | ``` 70 | --------------------------------------------------------------------------------