h2s

= h2s
Equim <https://github.com/Equim-chan[@Equim-chan]>

image:http://img.shields.io/badge/godoc-reference-5272B4.svg[GoDoc, link=https://godoc.org/ekyu.moe/h2s]
image:https://img.shields.io/github/release/Equim-chan/h2s.svg[Release, link=https://github.com/Equim-chan/h2s/releases/latest]
image:https://img.shields.io/circleci/project/github/Equim-chan/h2s.svg[CircleCI, link=https://circleci.com/gh/Equim-chan/h2s]
image:https://goreportcard.com/badge/github.com/Equim-chan/h2s[Go Report Card, link=https://goreportcard.com/report/github.com/Equim-chan/h2s]
image:https://img.shields.io/github/license/Equim-chan/h2s.svg[License, link=https://github.com/Equim-chan/h2s/blob/master/LICENSE]

h2s is a tiny CLI tool that wraps one or multiple HTTPS proxies into a SOCKS5 proxy. It does something like https://www.irif.fr/~jch/software/polipo/[polipo] and http://www.privoxy.org/[privoxy] do, but in a reversed way.

There are already some SOCKS to HTTPS tools out there, but I can hardly find a reversed one (HTTPS to SOCKS), so I decided to make one on my own.

== Install
You can view the https://github.com/Equim-chan/h2s/releases[release] page for handy prebuilt binaries.

== Build from Source
h2s relies on stadard libs only.

[source,bash]
----
$ go get -u ekyu.moe/h2s/cmd/h2s
----

== Configure
An example config file:

[source,js]
----
{
  // bind is the address h2s will listen to.
  // Note that since HTTPS proxy support only TCP, the h2s wrapped SOCKS5
  // proxy consequently support only TCP as well.
  "bind": "127.0.0.1:1080",

  // upstreams are HTTPS proxy upstreams.
  // h2s will do a simple round-robin load balance.
  "upstreams": [{
    // If no port is specified, 80 is assumed by default.
    "address": "proxy1.example.com",
  }, {
    "address": "proxy2.example.com:3128",

    // username and password are optional for proxy authentication.
    "username": "Alice",
    "password": "secret here"
  }, {
    // An HTTPS proxy over TLS upstream.
    // You have to specify port explicitly (usually 443), and set the tls field.
    "address": "secure.proxy.example.com:443",
    "username": "Secure",
    "password": "Yeah!",

    // h2s only provides some basic TLS settings. If you are an advanced user and
    // looking for other settings, you may use stunnel(1) to handle TLS instead,
    // and simply leave a naive TCP interface to h2s.
    "tlsConfig": {
      // If empty, serverName is set to the hostname from address.
      // Most users could just leave it empty.
      "serverName": "secure.proxy.example.com",

      // If you prefer to set a fingerprint instead of providing certs, you can
      // set this to true.
      // Do not set to true unless you know what you are doing.
      "insecureSkipVerify": false,
      // Server's SHA256 fingerprint, used to verify as an alternative to providing
      // the whole server certs, should be used with insecureSkipVerify to true.
      // If both rootCA and sha256Fingerprint are provided, they will both be
      // verified.
      //
      // An example to get fingerprint of a given cert:
      //     openssl x509 -fingerprint -sha256 -noout -in cert.cer | cut -f2 -d'=' | sed s/://g
      // or of a server with TLS enabled:
      //      openssl s_client -showcerts -connect example.com:443 < /dev/null | \
      //        openssl x509 -fingerprint -sha256 -noout | cut -f2 -d'=' | sed s/://g
      "sha256fingerprint": "22B975A1409850EF7F4522183E9C5A8955758FC899D70FE257112DA2FC430CCC",

      // rootCA is useful for self-signed certs. Be careful with it.
      // If the server has a trusted cert, you don't have to set it.
      "rootCA": "/path/to/the/ca/cert",

      // certFile and keyFile are advanced options for client authentication.
      // Most users could just leave it empty.
      "certFile": "/path/to/the/client/cert",
      "keyFile": "/path/to/the/client/key"
    }
  }],

  // accounts is an optional array of accounts for SOCKS5 authentication
  // with no accounts, authentication is disabled
  "accounts": [{
    "username": "test server",
    "password": "test"
  }],

  // timeout optionally sets timeout value when dialing to a upstream
  // default "20s"
  "timeout": "20s",
  // retries optionally specifies the max retries count of dialing to upstreams
  // default 3.
  "retries": 3
}
----

== Usage
[source,bash]
----
$ h2s [-config h2s.json]
----

== References
* https://tools.ietf.org/html/rfc1928[RFC 1928 - SOCKS Protocol Version 5]
* https://tools.ietf.org/html/rfc1929[RFC 1929 - Username/Password Authentication for SOCKS V5]
* https://tools.ietf.org/html/rfc7231[RFC 7231 - Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content]

== License
https://github.com/Equim-chan/h2s/blob/master/LICENSE[MIT]