From 555768324cfd7113a5391c328dbe11e122fc510a Mon Sep 17 00:00:00 2001 From: Daniel LaCosse <3759828+daniellacosse@users.noreply.github.com> Date: Wed, 23 Oct 2024 14:41:57 -0400 Subject: [PATCH 01/16] add readme for smart dialer JSON config --- x/smart/README.md | 132 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 132 insertions(+) create mode 100644 x/smart/README.md diff --git a/x/smart/README.md b/x/smart/README.md new file mode 100644 index 00000000..114274c5 --- /dev/null +++ b/x/smart/README.md @@ -0,0 +1,132 @@ +# Smart Dialer + +## JSON config for the Smart Dialer + +The Smart Dialer uses a JSON config to dynamically find serverless strategies for circumvention. The config is used to search for a strategy that unblocks DNS and TLS for a given list of test domains. + +Here is an example of a JSON config: + +```json +{ + "dns": [ + { + "https": { + "name": "doh.sb" + } + } + ], + "tls": [ + "override:host=cloudflare.net|tlsfrag:1" + ] +} + +``` + +### DNS Configuration + +* The `dns` field specifies a list of DNS resolvers to test. +* Each DNS resolver can be one of the following types: + * `system`: Use the system resolver. + * `https`: Use an encrypted DNS over HTTPS (DoH) resolver. + * `tls`: Use an encrypted DNS over TLS (DoT) resolver. + * `udp`: Use a UDP resolver. + * `tcp`: Use a TCP resolver. + +#### HTTPS Resolver + +```json +{ + "https": { + "name": "doh.sb", + "address": "doh.sb:443" + } +} + +``` + +* `name`: The domain name of the DoH server. +* `address`: The host:port of the DoH server. Defaults to `name`:443. + +#### TLS Resolver + +```json +{ + "tls": { + "name": "dns.google", + "address": "dns.google:853" + } +} + +``` + +* `name`: The domain name of the DoT server. +* `address`: The host:port of the DoT server. Defaults to `name`:853. + +#### UDP Resolver + +```json +{ + "udp": { + "address": "8.8.8.8:53" + } +} + +``` + +* `address`: The host:port of the UDP resolver. + +#### TCP Resolver + +```json +{ + "tcp": { + "address": "1.1.1.1:53" + } +} + +``` + +* `address`: The host:port of the TCP resolver. + +### TLS Configuration + +* The `tls` field specifies a list of TLS transports to test. +* Each TLS transport is a string that specifies the transport to use. +* For example, `override:host=cloudflare.net|tlsfrag:1` specifies a transport that uses domain fronting with Cloudflare and TLS fragmentation. The available transports are defined in the `outline-sdk/x/configurl` package. + +### Using the Smart Dialer + +To use the Smart Dialer, create a `StrategyFinder` object and call the `NewDialer` method, passing in the list of test domains and the JSON config. The `NewDialer` method will return a `transport.StreamDialer` that can be used to create connections using the found strategy. For example: + +```go +finder := &smart.StrategyFinder{ + TestTimeout: 5 * time.Second, + LogWriter: os.Stdout, + StreamDialer: &transport.TCPDialer{}, + PacketDialer: &transport.UDPDialer{}, +} + +configBytes := []byte(` +{ + "dns": [ + { + "https": { + "name": "doh.sb" + } + } + ], + "tls": [ + "override:host=cloudflare.net|tlsfrag:1" + ] +} +`) + +dialer, err := finder.NewDialer(context.Background(), []string{"www.google.com"}, configBytes) +if err != nil { + // Handle error. +} + +// Use dialer to create connections. +``` + +Please note that this is a basic example and may need to be adapted for your specific use case. From 02d2c7801419e5c0f5c4061624eff5ac2ffda03c Mon Sep 17 00:00:00 2001 From: Daniel LaCosse <3759828+daniellacosse@users.noreply.github.com> Date: Wed, 23 Oct 2024 14:49:16 -0400 Subject: [PATCH 02/16] tweaks --- x/smart/README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/x/smart/README.md b/x/smart/README.md index 114274c5..d7cee3f9 100644 --- a/x/smart/README.md +++ b/x/smart/README.md @@ -26,7 +26,7 @@ Here is an example of a JSON config: * The `dns` field specifies a list of DNS resolvers to test. * Each DNS resolver can be one of the following types: - * `system`: Use the system resolver. + * `system`: Use the system resolver. Specify with an empty object. * `https`: Use an encrypted DNS over HTTPS (DoH) resolver. * `tls`: Use an encrypted DNS over TLS (DoT) resolver. * `udp`: Use a UDP resolver. @@ -92,7 +92,7 @@ Here is an example of a JSON config: * The `tls` field specifies a list of TLS transports to test. * Each TLS transport is a string that specifies the transport to use. -* For example, `override:host=cloudflare.net|tlsfrag:1` specifies a transport that uses domain fronting with Cloudflare and TLS fragmentation. The available transports are defined in the `outline-sdk/x/configurl` package. +* For example, `override:host=cloudflare.net|tlsfrag:1` specifies a transport that uses domain fronting with Cloudflare and TLS fragmentation. The available transports are defined in the `outline-sdk/x/configurl` package. ### Using the Smart Dialer From f05ff0107787af94752b29268e46c210bbb99dcc Mon Sep 17 00:00:00 2001 From: Daniel LaCosse <3759828+daniellacosse@users.noreply.github.com> Date: Wed, 23 Oct 2024 16:07:07 -0400 Subject: [PATCH 03/16] Update README.md --- x/smart/README.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/x/smart/README.md b/x/smart/README.md index d7cee3f9..8e677728 100644 --- a/x/smart/README.md +++ b/x/smart/README.md @@ -1,5 +1,7 @@ # Smart Dialer +The **Smart Dialer** is a dialer that **automatically chooses the best way to connect** to the internet from a list of configured options. + ## JSON config for the Smart Dialer The Smart Dialer uses a JSON config to dynamically find serverless strategies for circumvention. The config is used to search for a strategy that unblocks DNS and TLS for a given list of test domains. From 32a4f6346536550fb60ce0e18e43f170994a83ad Mon Sep 17 00:00:00 2001 From: Daniel LaCosse <3759828+daniellacosse@users.noreply.github.com> Date: Wed, 23 Oct 2024 16:08:01 -0400 Subject: [PATCH 04/16] Update README.md --- x/smart/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/x/smart/README.md b/x/smart/README.md index 8e677728..3e51c4ca 100644 --- a/x/smart/README.md +++ b/x/smart/README.md @@ -94,7 +94,7 @@ Here is an example of a JSON config: * The `tls` field specifies a list of TLS transports to test. * Each TLS transport is a string that specifies the transport to use. -* For example, `override:host=cloudflare.net|tlsfrag:1` specifies a transport that uses domain fronting with Cloudflare and TLS fragmentation. The available transports are defined in the `outline-sdk/x/configurl` package. +* For example, `override:host=cloudflare.net|tlsfrag:1` specifies a transport that uses domain fronting with Cloudflare and TLS fragmentation. [The available transports are documented here.](https://pkg.go.dev/github.com/Jigsaw-Code/outline-sdk/x/config#hdr-Config_Format) ### Using the Smart Dialer From a4fce6bde39958a31c4fb438f4f0178ddf21c631 Mon Sep 17 00:00:00 2001 From: Daniel LaCosse <3759828+daniellacosse@users.noreply.github.com> Date: Thu, 24 Oct 2024 11:00:06 -0400 Subject: [PATCH 05/16] Update x/smart/README.md Co-authored-by: Vinicius Fortuna --- x/smart/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/x/smart/README.md b/x/smart/README.md index 3e51c4ca..5fadce1d 100644 --- a/x/smart/README.md +++ b/x/smart/README.md @@ -1,6 +1,6 @@ # Smart Dialer -The **Smart Dialer** is a dialer that **automatically chooses the best way to connect** to the internet from a list of configured options. +The **Smart Dialer** searches for a strategy that unblocks DNS and TLS for a given list of test domains. It takes a config describing multiple strategies, which is used to pick from. ## JSON config for the Smart Dialer From d53487a4fa5693b5c35998d1102bda38e65900ab Mon Sep 17 00:00:00 2001 From: Daniel LaCosse <3759828+daniellacosse@users.noreply.github.com> Date: Thu, 24 Oct 2024 11:00:12 -0400 Subject: [PATCH 06/16] Update x/smart/README.md Co-authored-by: Vinicius Fortuna --- x/smart/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/x/smart/README.md b/x/smart/README.md index 5fadce1d..a491894b 100644 --- a/x/smart/README.md +++ b/x/smart/README.md @@ -34,7 +34,7 @@ Here is an example of a JSON config: * `udp`: Use a UDP resolver. * `tcp`: Use a TCP resolver. -#### HTTPS Resolver +#### DNS-over-HTTPS Resolver (DoH) ```json { From fdc64989c44f1ffa972e46d54bd35ef8458ecc51 Mon Sep 17 00:00:00 2001 From: Daniel LaCosse <3759828+daniellacosse@users.noreply.github.com> Date: Thu, 24 Oct 2024 11:00:18 -0400 Subject: [PATCH 07/16] Update x/smart/README.md Co-authored-by: Vinicius Fortuna --- x/smart/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/x/smart/README.md b/x/smart/README.md index a491894b..4ccfd825 100644 --- a/x/smart/README.md +++ b/x/smart/README.md @@ -49,7 +49,7 @@ Here is an example of a JSON config: * `name`: The domain name of the DoH server. * `address`: The host:port of the DoH server. Defaults to `name`:443. -#### TLS Resolver +#### DNS-over-TLS Resolver (DoT) ```json { From 08d0c04e498ea44d49107b165bab46f250dfda1a Mon Sep 17 00:00:00 2001 From: Daniel LaCosse <3759828+daniellacosse@users.noreply.github.com> Date: Thu, 24 Oct 2024 11:00:28 -0400 Subject: [PATCH 08/16] Update x/smart/README.md Co-authored-by: Vinicius Fortuna --- x/smart/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/x/smart/README.md b/x/smart/README.md index 4ccfd825..64e8c004 100644 --- a/x/smart/README.md +++ b/x/smart/README.md @@ -94,7 +94,7 @@ Here is an example of a JSON config: * The `tls` field specifies a list of TLS transports to test. * Each TLS transport is a string that specifies the transport to use. -* For example, `override:host=cloudflare.net|tlsfrag:1` specifies a transport that uses domain fronting with Cloudflare and TLS fragmentation. [The available transports are documented here.](https://pkg.go.dev/github.com/Jigsaw-Code/outline-sdk/x/config#hdr-Config_Format) +* For example, `override:host=cloudflare.net|tlsfrag:1` specifies a transport that uses domain fronting with Cloudflare and TLS fragmentation. See the [config documentation](https://pkg.go.dev/github.com/Jigsaw-Code/outline-sdk/x/config#hdr-Config_Format) for details. ### Using the Smart Dialer From ca95510117b0dbfcf635ec61d9f99dab3ee31e66 Mon Sep 17 00:00:00 2001 From: Daniel LaCosse <3759828+daniellacosse@users.noreply.github.com> Date: Thu, 24 Oct 2024 11:02:08 -0400 Subject: [PATCH 09/16] Update README.md --- x/smart/README.md | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/x/smart/README.md b/x/smart/README.md index 64e8c004..0beafd0a 100644 --- a/x/smart/README.md +++ b/x/smart/README.md @@ -1,12 +1,10 @@ # Smart Dialer -The **Smart Dialer** searches for a strategy that unblocks DNS and TLS for a given list of test domains. It takes a config describing multiple strategies, which is used to pick from. +The **Smart Dialer** searches for a strategy that unblocks DNS and TLS for a given list of test domains. It takes a config describing multiple strategies to pick from. ## JSON config for the Smart Dialer -The Smart Dialer uses a JSON config to dynamically find serverless strategies for circumvention. The config is used to search for a strategy that unblocks DNS and TLS for a given list of test domains. - -Here is an example of a JSON config: +The config that the Smart Dialer takes is in a JSON format. Here is an example: ```json { From 671845b75b5fe8c5e177e458cfe912493675a967 Mon Sep 17 00:00:00 2001 From: Daniel LaCosse <3759828+daniellacosse@users.noreply.github.com> Date: Thu, 24 Oct 2024 12:22:11 -0400 Subject: [PATCH 10/16] Update x/smart/README.md Co-authored-by: Vinicius Fortuna --- x/smart/README.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/x/smart/README.md b/x/smart/README.md index 0beafd0a..33ef55df 100644 --- a/x/smart/README.md +++ b/x/smart/README.md @@ -109,14 +109,14 @@ finder := &smart.StrategyFinder{ configBytes := []byte(` { "dns": [ - { - "https": { - "name": "doh.sb" - } - } + {"system": {}}, + {"https": {"name": "8.8.8.8"}}, + {"https": {"name": "9.9.9.9"}} ], "tls": [ - "override:host=cloudflare.net|tlsfrag:1" + "", + "split:2", + "tlsfrag:1" ] } `) From 5df4e8fe0472d95d1759d0da9724f1c20c235c8c Mon Sep 17 00:00:00 2001 From: Daniel LaCosse <3759828+daniellacosse@users.noreply.github.com> Date: Thu, 24 Oct 2024 12:22:22 -0400 Subject: [PATCH 11/16] Update x/smart/README.md Co-authored-by: Vinicius Fortuna --- x/smart/README.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/x/smart/README.md b/x/smart/README.md index 33ef55df..0f9193de 100644 --- a/x/smart/README.md +++ b/x/smart/README.md @@ -80,12 +80,10 @@ The config that the Smart Dialer takes is in a JSON format. Here is an example: ```json { "tcp": { - "address": "1.1.1.1:53" + "address": "8.8.8.8" } } -``` - * `address`: The host:port of the TCP resolver. ### TLS Configuration From d2daa669553f06f8ebaf71b147f252e7a73d88b9 Mon Sep 17 00:00:00 2001 From: Daniel LaCosse <3759828+daniellacosse@users.noreply.github.com> Date: Thu, 24 Oct 2024 12:22:29 -0400 Subject: [PATCH 12/16] Update x/smart/README.md Co-authored-by: Vinicius Fortuna --- x/smart/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/x/smart/README.md b/x/smart/README.md index 0f9193de..e856ff20 100644 --- a/x/smart/README.md +++ b/x/smart/README.md @@ -67,7 +67,7 @@ The config that the Smart Dialer takes is in a JSON format. Here is an example: ```json { "udp": { - "address": "8.8.8.8:53" + "address": "8.8.8.8" } } From cdff4d392a8885b4b7d5c9aabe71f0525620e69f Mon Sep 17 00:00:00 2001 From: Daniel LaCosse <3759828+daniellacosse@users.noreply.github.com> Date: Thu, 24 Oct 2024 12:22:34 -0400 Subject: [PATCH 13/16] Update x/smart/README.md Co-authored-by: Vinicius Fortuna --- x/smart/README.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/x/smart/README.md b/x/smart/README.md index e856ff20..171c29c6 100644 --- a/x/smart/README.md +++ b/x/smart/README.md @@ -53,12 +53,10 @@ The config that the Smart Dialer takes is in a JSON format. Here is an example: { "tls": { "name": "dns.google", - "address": "dns.google:853" + "address": "8.8.8.8" } } -``` - * `name`: The domain name of the DoT server. * `address`: The host:port of the DoT server. Defaults to `name`:853. From 281178c2bcf2f5631e7841a314a347c61560cb97 Mon Sep 17 00:00:00 2001 From: Daniel LaCosse <3759828+daniellacosse@users.noreply.github.com> Date: Thu, 24 Oct 2024 12:22:40 -0400 Subject: [PATCH 14/16] Update x/smart/README.md Co-authored-by: Vinicius Fortuna --- x/smart/README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/x/smart/README.md b/x/smart/README.md index 171c29c6..10ff29a3 100644 --- a/x/smart/README.md +++ b/x/smart/README.md @@ -37,8 +37,8 @@ The config that the Smart Dialer takes is in a JSON format. Here is an example: ```json { "https": { - "name": "doh.sb", - "address": "doh.sb:443" + "name": "dns.google", + "address": "8.8.8.8" } } From 0f4b6a072a94e9710c344a31491d3631a7739431 Mon Sep 17 00:00:00 2001 From: Daniel LaCosse <3759828+daniellacosse@users.noreply.github.com> Date: Thu, 24 Oct 2024 12:22:47 -0400 Subject: [PATCH 15/16] Update x/smart/README.md Co-authored-by: Vinicius Fortuna --- x/smart/README.md | 13 ++++++------- 1 file changed, 6 insertions(+), 7 deletions(-) diff --git a/x/smart/README.md b/x/smart/README.md index 10ff29a3..14320a73 100644 --- a/x/smart/README.md +++ b/x/smart/README.md @@ -9,17 +9,16 @@ The config that the Smart Dialer takes is in a JSON format. Here is an example: ```json { "dns": [ - { - "https": { - "name": "doh.sb" - } - } + {"system": {}}, + {"https": {"name": "8.8.8.8"}}, + {"https": {"name": "9.9.9.9"}} ], "tls": [ - "override:host=cloudflare.net|tlsfrag:1" + "", + "split:2", + "tlsfrag:1" ] } - ``` ### DNS Configuration From 82f3e4f3aee4d120443e82122b36392bfbfff026 Mon Sep 17 00:00:00 2001 From: Daniel LaCosse <3759828+daniellacosse@users.noreply.github.com> Date: Thu, 24 Oct 2024 12:24:13 -0400 Subject: [PATCH 16/16] Update README.md --- x/smart/README.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/x/smart/README.md b/x/smart/README.md index 14320a73..f4886b00 100644 --- a/x/smart/README.md +++ b/x/smart/README.md @@ -55,6 +55,7 @@ The config that the Smart Dialer takes is in a JSON format. Here is an example: "address": "8.8.8.8" } } +``` * `name`: The domain name of the DoT server. * `address`: The host:port of the DoT server. Defaults to `name`:853. @@ -67,7 +68,6 @@ The config that the Smart Dialer takes is in a JSON format. Here is an example: "address": "8.8.8.8" } } - ``` * `address`: The host:port of the UDP resolver. @@ -80,6 +80,7 @@ The config that the Smart Dialer takes is in a JSON format. Here is an example: "address": "8.8.8.8" } } +``` * `address`: The host:port of the TCP resolver.