├── LICENSE ├── README.md ├── esni.go └── main.go /LICENSE: -------------------------------------------------------------------------------- 1 | Apache License 2 | Version 2.0, January 2004 3 | http://www.apache.org/licenses/ 4 | 5 | TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION 6 | 7 | 1. Definitions. 8 | 9 | "License" shall mean the terms and conditions for use, reproduction, 10 | and distribution as defined by Sections 1 through 9 of this document. 11 | 12 | "Licensor" shall mean the copyright owner or entity authorized by 13 | the copyright owner that is granting the License. 14 | 15 | "Legal Entity" shall mean the union of the acting entity and all 16 | other entities that control, are controlled by, or are under common 17 | control with that entity. For the purposes of this definition, 18 | "control" means (i) the power, direct or indirect, to cause the 19 | direction or management of such entity, whether by contract or 20 | otherwise, or (ii) ownership of fifty percent (50%) or more of the 21 | outstanding shares, or (iii) beneficial ownership of such entity. 22 | 23 | "You" (or "Your") shall mean an individual or Legal Entity 24 | exercising permissions granted by this License. 25 | 26 | "Source" form shall mean the preferred form for making modifications, 27 | including but not limited to software source code, documentation 28 | source, and configuration files. 29 | 30 | "Object" form shall mean any form resulting from mechanical 31 | transformation or translation of a Source form, including but 32 | not limited to compiled object code, generated documentation, 33 | and conversions to other media types. 34 | 35 | "Work" shall mean the work of authorship, whether in Source or 36 | Object form, made available under the License, as indicated by a 37 | copyright notice that is included in or attached to the work 38 | (an example is provided in the Appendix below). 39 | 40 | "Derivative Works" shall mean any work, whether in Source or Object 41 | form, that is based on (or derived from) the Work and for which the 42 | editorial revisions, annotations, elaborations, or other modifications 43 | represent, as a whole, an original work of authorship. For the purposes 44 | of this License, Derivative Works shall not include works that remain 45 | separable from, or merely link (or bind by name) to the interfaces of, 46 | the Work and Derivative Works thereof. 47 | 48 | "Contribution" shall mean any work of authorship, including 49 | the original version of the Work and any modifications or additions 50 | to that Work or Derivative Works thereof, that is intentionally 51 | submitted to Licensor for inclusion in the Work by the copyright owner 52 | or by an individual or Legal Entity authorized to submit on behalf of 53 | the copyright owner. For the purposes of this definition, "submitted" 54 | means any form of electronic, verbal, or written communication sent 55 | to the Licensor or its representatives, including but not limited to 56 | communication on electronic mailing lists, source code control systems, 57 | and issue tracking systems that are managed by, or on behalf of, the 58 | Licensor for the purpose of discussing and improving the Work, but 59 | excluding communication that is conspicuously marked or otherwise 60 | designated in writing by the copyright owner as "Not a Contribution." 61 | 62 | "Contributor" shall mean Licensor and any individual or Legal Entity 63 | on behalf of whom a Contribution has been received by Licensor and 64 | subsequently incorporated within the Work. 65 | 66 | 2. Grant of Copyright License. Subject to the terms and conditions of 67 | this License, each Contributor hereby grants to You a perpetual, 68 | worldwide, non-exclusive, no-charge, royalty-free, irrevocable 69 | copyright license to reproduce, prepare Derivative Works of, 70 | publicly display, publicly perform, sublicense, and distribute the 71 | Work and such Derivative Works in Source or Object form. 72 | 73 | 3. Grant of Patent License. Subject to the terms and conditions of 74 | this License, each Contributor hereby grants to You a perpetual, 75 | worldwide, non-exclusive, no-charge, royalty-free, irrevocable 76 | (except as stated in this section) patent license to make, have made, 77 | use, offer to sell, sell, import, and otherwise transfer the Work, 78 | where such license applies only to those patent claims licensable 79 | by such Contributor that are necessarily infringed by their 80 | Contribution(s) alone or by combination of their Contribution(s) 81 | with the Work to which such Contribution(s) was submitted. If You 82 | institute patent litigation against any entity (including a 83 | cross-claim or counterclaim in a lawsuit) alleging that the Work 84 | or a Contribution incorporated within the Work constitutes direct 85 | or contributory patent infringement, then any patent licenses 86 | granted to You under this License for that Work shall terminate 87 | as of the date such litigation is filed. 88 | 89 | 4. Redistribution. You may reproduce and distribute copies of the 90 | Work or Derivative Works thereof in any medium, with or without 91 | modifications, and in Source or Object form, provided that You 92 | meet the following conditions: 93 | 94 | (a) You must give any other recipients of the Work or 95 | Derivative Works a copy of this License; and 96 | 97 | (b) You must cause any modified files to carry prominent notices 98 | stating that You changed the files; and 99 | 100 | (c) You must retain, in the Source form of any Derivative Works 101 | that You distribute, all copyright, patent, trademark, and 102 | attribution notices from the Source form of the Work, 103 | excluding those notices that do not pertain to any part of 104 | the Derivative Works; and 105 | 106 | (d) If the Work includes a "NOTICE" text file as part of its 107 | distribution, then any Derivative Works that You distribute must 108 | include a readable copy of the attribution notices contained 109 | within such NOTICE file, excluding those notices that do not 110 | pertain to any part of the Derivative Works, in at least one 111 | of the following places: within a NOTICE text file distributed 112 | as part of the Derivative Works; within the Source form or 113 | documentation, if provided along with the Derivative Works; or, 114 | within a display generated by the Derivative Works, if and 115 | wherever such third-party notices normally appear. The contents 116 | of the NOTICE file are for informational purposes only and 117 | do not modify the License. You may add Your own attribution 118 | notices within Derivative Works that You distribute, alongside 119 | or as an addendum to the NOTICE text from the Work, provided 120 | that such additional attribution notices cannot be construed 121 | as modifying the License. 122 | 123 | You may add Your own copyright statement to Your modifications and 124 | may provide additional or different license terms and conditions 125 | for use, reproduction, or distribution of Your modifications, or 126 | for any such Derivative Works as a whole, provided Your use, 127 | reproduction, and distribution of the Work otherwise complies with 128 | the conditions stated in this License. 129 | 130 | 5. Submission of Contributions. Unless You explicitly state otherwise, 131 | any Contribution intentionally submitted for inclusion in the Work 132 | by You to the Licensor shall be under the terms and conditions of 133 | this License, without any additional terms or conditions. 134 | Notwithstanding the above, nothing herein shall supersede or modify 135 | the terms of any separate license agreement you may have executed 136 | with Licensor regarding such Contributions. 137 | 138 | 6. Trademarks. This License does not grant permission to use the trade 139 | names, trademarks, service marks, or product names of the Licensor, 140 | except as required for reasonable and customary use in describing the 141 | origin of the Work and reproducing the content of the NOTICE file. 142 | 143 | 7. Disclaimer of Warranty. Unless required by applicable law or 144 | agreed to in writing, Licensor provides the Work (and each 145 | Contributor provides its Contributions) on an "AS IS" BASIS, 146 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or 147 | implied, including, without limitation, any warranties or conditions 148 | of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A 149 | PARTICULAR PURPOSE. You are solely responsible for determining the 150 | appropriateness of using or redistributing the Work and assume any 151 | risks associated with Your exercise of permissions under this License. 152 | 153 | 8. Limitation of Liability. In no event and under no legal theory, 154 | whether in tort (including negligence), contract, or otherwise, 155 | unless required by applicable law (such as deliberate and grossly 156 | negligent acts) or agreed to in writing, shall any Contributor be 157 | liable to You for damages, including any direct, indirect, special, 158 | incidental, or consequential damages of any character arising as a 159 | result of this License or out of the use or inability to use the 160 | Work (including but not limited to damages for loss of goodwill, 161 | work stoppage, computer failure or malfunction, or any and all 162 | other commercial damages or losses), even if such Contributor 163 | has been advised of the possibility of such damages. 164 | 165 | 9. Accepting Warranty or Additional Liability. While redistributing 166 | the Work or Derivative Works thereof, You may choose to offer, 167 | and charge a fee for, acceptance of support, warranty, indemnity, 168 | or other liability obligations and/or rights consistent with this 169 | License. However, in accepting such obligations, You may act only 170 | on Your own behalf and on Your sole responsibility, not on behalf 171 | of any other Contributor, and only if You agree to indemnify, 172 | defend, and hold each Contributor harmless for any liability 173 | incurred by, or claims asserted against, such Contributor by reason 174 | of your accepting any such warranty or additional liability. 175 | 176 | END OF TERMS AND CONDITIONS 177 | 178 | APPENDIX: How to apply the Apache License to your work. 179 | 180 | To apply the Apache License to your work, attach the following 181 | boilerplate notice, with the fields enclosed by brackets "[]" 182 | replaced with your own identifying information. (Don't include 183 | the brackets!) The text should be enclosed in the appropriate 184 | comment syntax for the file format. We also recommend that a 185 | file or class name and description of purpose be included on the 186 | same "printed page" as the copyright notice for easier 187 | identification within third-party archives. 188 | 189 | Copyright [yyyy] [name of copyright owner] 190 | 191 | Licensed under the Apache License, Version 2.0 (the "License"); 192 | you may not use this file except in compliance with the License. 193 | You may obtain a copy of the License at 194 | 195 | http://www.apache.org/licenses/LICENSE-2.0 196 | 197 | Unless required by applicable law or agreed to in writing, software 198 | distributed under the License is distributed on an "AS IS" BASIS, 199 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 200 | See the License for the specific language governing permissions and 201 | limitations under the License. 202 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # esnitool 2 | A cmdline tool in golang to query and display TLS ESNI records from DNS 3 | 4 | # Sample Usage 5 | 6 | ``` 7 | $ ./esnitool www.cloudflare.com 8 | domain: _esni.www.cloudflare.com 9 | version : FF 01 (known) 10 | checksum: B7 EF A8 70 (valid) 11 | keys (1): 12 | 0: x25519 [57 51 54 D0 33 EF BF B8 AB 15 26 F5 E9 42 B8 20 F7 1B 9C D4...] 13 | cipher_suites (1): 14 | 0: TLS_AES_128_GCM_SHA256 15 | padded_length: 260 16 | not_before: 2018-11-19 14:00:00 -0500 EST 17 | not_after: 2018-11-25 14:00:00 -0500 EST 18 | extensions: none 19 | ``` 20 | # Version 21 | Currently it supports the lastest [draft (02)](https://tools.ietf.org/html/draft-ietf-tls-esni-02). You can be sure there will be changes before it is finalized. 22 | 23 | # Building 24 | There are no dependencies other than stdlib, so it's just: 25 | ``` 26 | cd $GOPATH 27 | go get github.com/mordyovits/esnitool 28 | ./bin/esnitool www.cloudflare.com 29 | ``` 30 | -------------------------------------------------------------------------------- /esni.go: -------------------------------------------------------------------------------- 1 | package main 2 | 3 | import ( 4 | "bytes" 5 | "crypto/sha256" 6 | "encoding/binary" 7 | "fmt" 8 | "io" 9 | "time" 10 | ) 11 | 12 | var known_version = [2]byte{0xFF, 0x01} 13 | 14 | var suites = map[[2]byte]string{ 15 | [2]byte{0x13, 0x01}: "TLS_AES_128_GCM_SHA256", 16 | [2]byte{0x13, 0x02}: "TLS_AES_256_GCM_SHA384", 17 | [2]byte{0x13, 0x03}: "TLS_CHACHA20_POLY1305_SHA256", 18 | [2]byte{0x13, 0x04}: "TLS_AES_128_CCM_SHA256", 19 | [2]byte{0x13, 0x05}: "TLS_AES_128_CCM_8_SHA256", 20 | } 21 | 22 | func suiteToName(cs [2]byte) string { 23 | s, ok := suites[cs] 24 | if !ok { 25 | return fmt.Sprintf("unknown (% X)", cs) 26 | } 27 | return s 28 | } 29 | 30 | var named_groups = map[[2]byte]string{ 31 | // Elliptic Curve Groups (ECDHE) 32 | [2]byte{0x00, 0x17}: "ecp256r1", 33 | [2]byte{0x00, 0x18}: "secp384r1", 34 | [2]byte{0x00, 0x19}: "secp521r1", 35 | [2]byte{0x00, 0x1D}: "x25519", 36 | [2]byte{0x00, 0x1E}: "x448", 37 | 38 | // Finite Field Groups (DHE) 39 | [2]byte{0x01, 0x00}: "ffdhe2048", 40 | [2]byte{0x01, 0x01}: "ffdhe3072", 41 | [2]byte{0x01, 0x02}: "ffdhe4096", 42 | [2]byte{0x01, 0x03}: "ffdhe6144", 43 | [2]byte{0x01, 0x04}: "ffdhe8192", 44 | } 45 | 46 | func namedgroupToName(ng [2]byte) string { 47 | s, ok := named_groups[ng] 48 | if !ok { 49 | return fmt.Sprintf("unknown (% X)", ng) 50 | } 51 | return s 52 | } 53 | 54 | // returns chunk, rest, ok 55 | func getBytes(n int, data []byte) ([]byte, []byte, bool) { 56 | if n > len(data) { 57 | return nil, nil, false 58 | } 59 | return data[:n], data[n:], true 60 | } 61 | 62 | // returns chunk, rest, ok 63 | func parseUint16Chunk(data []byte) ([]byte, []byte, bool) { 64 | if len(data) < 2 { 65 | return nil, nil, false 66 | } 67 | length := int(data[0])<<8 | int(data[1]) 68 | if len(data) < 2+length { 69 | return nil, nil, false 70 | } 71 | chunk := data[2 : 2+length] 72 | return chunk, data[2+length:], true 73 | } 74 | 75 | type KeyShareEntry struct { 76 | group [2]byte // NamedGroup 77 | key_exchange []byte // opaque 78 | } 79 | 80 | type ESNIKeys struct { 81 | version [2]byte 82 | checksum [4]byte 83 | keys []KeyShareEntry 84 | checksum_valid bool 85 | cipher_suites [][2]byte 86 | padded_length uint16 87 | not_before uint64 88 | not_after uint64 89 | extensions []byte 90 | } 91 | 92 | func (k *ESNIKeys) Print(w io.Writer) { 93 | fmt.Fprintf(w, "version : % X ", k.version) 94 | if k.version == known_version { 95 | fmt.Fprintf(w, "(known)\n") 96 | } else { 97 | fmt.Fprintf(w, "(unknown)\n") 98 | } 99 | fmt.Fprintf(w, "checksum: % X ", k.checksum) 100 | if k.checksum_valid { 101 | fmt.Fprintf(w, "(valid)\n") 102 | } else { 103 | fmt.Fprintf(w, "(invalid)\n") 104 | } 105 | fmt.Fprintf(w, "keys (%d):\n", len(k.keys)) 106 | for i, key := range k.keys { 107 | fmt.Fprintf(w, " %d: %s [% X...]\n", i, namedgroupToName(key.group), key.key_exchange[:20]) 108 | } 109 | fmt.Fprintf(w, "cipher_suites (%d):\n", len(k.cipher_suites)) 110 | for i, cs := range k.cipher_suites { 111 | fmt.Fprintf(w, " %d: %s\n", i, suiteToName(cs)) 112 | } 113 | fmt.Fprintf(w, "padded_length: %d\n", k.padded_length) 114 | fmt.Fprintf(w, "not_before: %s\n", time.Unix(int64(k.not_before), 0)) 115 | fmt.Fprintf(w, "not_after: %s\n", time.Unix(int64(k.not_after), 0)) 116 | if len(k.extensions) > 0 { 117 | fmt.Fprintf(w, "extensions: % X\n", k.extensions) 118 | } else { 119 | fmt.Fprintln(w, "extensions: none") 120 | } 121 | } 122 | 123 | func parseESNIKeys(data []byte) (*ESNIKeys, error) { 124 | k := ESNIKeys{} 125 | b, rest, ok := getBytes(2, data) 126 | if !ok { 127 | return nil, fmt.Errorf("failed to parse version") 128 | } 129 | copy(k.version[:], b) 130 | 131 | c, rest, ok := getBytes(4, rest) 132 | if !ok { 133 | return nil, fmt.Errorf("failed to parse checksum") 134 | } 135 | copy(k.checksum[:], c) 136 | 137 | // now that we imported the checksum. zero it for checksumming 138 | copy(data[2:7], []byte{0, 0, 0, 0}) 139 | sum := sha256.Sum256(data) 140 | if bytes.Equal(sum[0:4], k.checksum[:]) { 141 | k.checksum_valid = true 142 | } 143 | 144 | keys, rest, ok := parseUint16Chunk(rest) 145 | if !ok { 146 | return nil, fmt.Errorf("failed to parse keys") 147 | } 148 | rest_keys := keys 149 | for { 150 | ng, rest_keys, ok := getBytes(2, rest_keys) 151 | if !ok { 152 | return nil, fmt.Errorf("failed to parse NamedGroup") 153 | } 154 | key, rest_keys, ok := parseUint16Chunk(rest_keys) 155 | if !ok { 156 | return nil, fmt.Errorf("failed to parse key_exchange") 157 | } 158 | 159 | kse := KeyShareEntry{} 160 | copy(kse.group[:], ng) 161 | kse.key_exchange = key 162 | k.keys = append(k.keys, kse) 163 | 164 | if len(rest_keys) == 0 { 165 | break 166 | } 167 | } 168 | // TODO: validate that every key belongs to a different group 169 | 170 | cipher_suites, rest, ok := parseUint16Chunk(rest) 171 | if !ok { 172 | return nil, fmt.Errorf("failed to parse cipher_suites") 173 | } 174 | // ciphersuites come in two-byte chunks, so it must be an even number 175 | if len(cipher_suites)%2 != 0 { 176 | return nil, fmt.Errorf("cipher_suites_size must be an even number") 177 | } 178 | 179 | for i := 0; i < (len(cipher_suites) / 2); i++ { 180 | var a [2]byte 181 | copy(a[:], cipher_suites[i*2:i*2+2]) 182 | k.cipher_suites = append(k.cipher_suites, a) 183 | } 184 | 185 | pl_bytes, rest, ok := getBytes(2, rest) 186 | if !ok { 187 | return nil, fmt.Errorf("failed to parse padded_length") 188 | } 189 | k.padded_length = binary.BigEndian.Uint16(pl_bytes) 190 | 191 | nb_bytes, rest, ok := getBytes(8, rest) 192 | if !ok { 193 | return nil, fmt.Errorf("failed to parse not_before") 194 | } 195 | k.not_before = binary.BigEndian.Uint64(nb_bytes) 196 | 197 | na_bytes, rest, ok := getBytes(8, rest) 198 | if !ok { 199 | return nil, fmt.Errorf("failed to parse not_after") 200 | } 201 | k.not_after = binary.BigEndian.Uint64(na_bytes) 202 | 203 | extensions, rest, ok := parseUint16Chunk(rest) 204 | if !ok { 205 | return nil, fmt.Errorf("failed to parse extensions") 206 | } 207 | copy(k.extensions, extensions) 208 | if len(rest) > 0 { 209 | return nil, fmt.Errorf("extra data at end of record") 210 | } 211 | return &k, nil 212 | } 213 | -------------------------------------------------------------------------------- /main.go: -------------------------------------------------------------------------------- 1 | package main 2 | 3 | import ( 4 | "encoding/base64" 5 | "fmt" 6 | "log" 7 | "net" 8 | "os" 9 | ) 10 | 11 | func main() { 12 | if len(os.Args) != 2 { 13 | fmt.Println("Missing hostname argument") 14 | os.Exit(-1) 15 | } 16 | domain := os.Args[1] 17 | if domain[:6] != "_esni." { 18 | domain = "_esni." + domain 19 | } 20 | fmt.Println("domain:", domain) 21 | records, err := net.LookupTXT(domain) 22 | if err != nil { 23 | log.Fatalf("Failed DNS lookup: %v", err) 24 | } 25 | // there can be multiple TXT records 26 | for _, record := range records { 27 | data, err := base64.StdEncoding.DecodeString(record) 28 | if err != nil { 29 | log.Fatalf("Failed to base64 decode TXT record: %v", err) 30 | } 31 | 32 | k, err := parseESNIKeys(data) 33 | if err != nil { 34 | log.Fatal(err) 35 | } 36 | k.Print(os.Stdout) 37 | } 38 | } 39 | --------------------------------------------------------------------------------