Skip to content

Commit

Permalink
minor docs, add socks guide
Browse files Browse the repository at this point in the history
  • Loading branch information
@jpillora
jpillora committed Apr 8, 2017
1 parent 87a8539 commit d7b9d1c
Show file tree
Hide file tree
Showing 2 changed files with 52 additions and 27 deletions.
69 changes: 47 additions & 22 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -32,10 +32,11 @@ $ go get -v github.com/jpillora/chisel

* Easy to use
* [Performant](#performance)*
* [Encrypted connections](#security) using `crypto/ssh`
* [Encrypted connections](#security) using the SSH protocol (via `crypto/ssh`)
* [Authenticated connections](#authentication); authenticated client connections with a users config file, authenticated server connections with fingerprint matching.
* Client auto-reconnects with [exponential backoff](https://github.com/jpillora/backoff)
* Client can create multiple tunnel endpoints over one TCP connection
* Client can optionally pass through HTTP CONNECT proxys
* Server optionally doubles as a [reverse proxy](http://golang.org/pkg/net/http/httputil/#NewSingleHostReverseProxy)

### Demo
Expand Down Expand Up @@ -64,7 +65,7 @@ $ chisel --help
Usage: chisel [command] [--help]
Version: 0.0.0-src
Version: X.Y.Z
Commands:
server - runs chisel in server mode
Expand All @@ -78,7 +79,6 @@ $ chisel --help
```
$ chisel server --help
Usage: chisel server [options]
Options:
Expand All @@ -93,23 +93,25 @@ $ chisel server --help
and private key pair. All commications will be secured using this
key pair. Share the subsequent fingerprint with clients to enable detection
of man-in-the-middle attacks (defaults to the CHISEL_KEY environment
variable, otherwise a new key is generate each run).
--auth, An optional string representing a single user with full
access, in the form of <user:pass>. This is equivalent to creating an
authfile with {"<user:pass>": [""]}.
variable, otherwise a new key is generate each run).
--authfile, An optional path to a users.json file. This file should
be an object with users defined like:
"<user:pass>": ["<addr-regex>","<addr-regex>"]
when <user> connects, their <pass> will be verified and then
each of the remote addresses will be compared against the list
of address regular expressions for a match. Addresses will
always come in the form "<host/ip>:<port>".
{
"<user:pass>": ["<addr-regex>","<addr-regex>"]
}
when <user> connects, their <pass> will be verified and then
each of the remote addresses will be compared against the list
of address regular expressions for a match. Addresses will
always come in the form "<host/ip>:<port>".
--auth, An optional string representing a single user with full
access, in the form of <user:pass>. This is equivalent to creating an
authfile with {"<user:pass>": [""]}.
--proxy, Specifies another HTTP server to proxy requests to when
chisel receives a normal HTTP request. Useful for hiding chisel in
plain sight.
chisel receives a normal HTTP request. Useful for hiding chisel in
plain sight.
--socks5, Allows client to access the internal SOCKS5 proxy. See
chisel client --help for more information.
Expand All @@ -121,7 +123,7 @@ $ chisel server --help
--help, This help text
Version:
0.0.0-src
X.Y.Z
Read more:
https://github.com/jpillora/chisel
Expand Down Expand Up @@ -154,7 +156,7 @@ $ chisel client --help
socks
5000:socks
*When the chisel server enables --socks5, remotes can
*When the chisel server has --socks5 enabled, remotes can
specify "socks" in place of remote-host and remote-port.
The default local host and port for a "socks" remote is
127.0.0.1:1080. Connections to this remote will terminate
Expand All @@ -170,7 +172,7 @@ $ chisel client --help
--auth, An optional username and password (client authentication)
in the form: "<user>:<pass>". These credentials are compared to
the credentials inside the server's --authfile. defaults to the
AUTH environment variable.
AUTH environment variable.
--keepalive, An optional keepalive interval. Since the underlying
transport is HTTP, in many instances we'll be traversing through
Expand All @@ -180,7 +182,7 @@ $ chisel client --help
--proxy, An optional HTTP CONNECT proxy which will be used reach
the chisel server. Authentication can be specified inside the URL.
For example, http://admin:[email protected]:8081
For example, http://admin:[email protected]:8081
--pid Generate pid file in current directory
Expand All @@ -189,15 +191,13 @@ $ chisel client --help
--help, This help text
Version:
0.0.0-src
X.Y.Z
Read more:
https://github.com/jpillora/chisel
```

See also [programmatic usage](https://github.com/jpillora/chisel/wiki/Programmatic-Usage).

### Security

Encryption is always enabled. When you start up a chisel server, it will generate an in-memory ECDSA public/private key pair. The public key fingerprint will be displayed as the server starts. Instead of generating a random key, the server may optionally specify a key seed, using the `--key` option, which will be used to seed the key generation. When clients connect, they will also display the server's public key fingerprint. The client can force a particular fingerprint using the `--fingerprint` option. See the `--help` above for more information.
Expand All @@ -208,6 +208,31 @@ Using the `--authfile` option, the server may optionally provide a `user.json` c

Internally, this is done using the *Password* authentication method provided by SSH. Learn more about `crypto/ssh` here http://blog.gopheracademy.com/go-and-ssh/.

### SOCKS5 Guide

1. Start your chisel server

```sh
docker run \
--name chisel -p 9312 \
-d --restart always \
jpillora/chisel server -p 9312 --socks5 --key supersecret
```

2. Connect your chisel client

```sh
chisel client --fingerprint ab:12:34 server-address:9312 socks
```

3. Point your SOCKS5 clients (e.g. Browsers) to:

```
localhost:1080
```

4. Now you have an encrypted, authenticated SOCKS connection over HTTP

### Performance

With [crowbar](https://github.com/q3k/crowbar), a connection is tunnelled by repeatedly querying the server with updates. This results in a large amount of HTTP and TCP connection overhead. Chisel overcomes this using WebSockets combined with [crypto/ssh](https://golang.org/x/crypto/ssh) to create hundreds of logical connections, resulting in **one** TCP connection per client.
Expand Down
10 changes: 5 additions & 5 deletions main.go
View file
Original file line number Diff line number Diff line change
Expand Up @@ -99,10 +99,6 @@ var serverHelp = `
of man-in-the-middle attacks (defaults to the CHISEL_KEY environment
variable, otherwise a new key is generate each run).
--auth, An optional string representing a single user with full
access, in the form of <user:pass>. This is equivalent to creating an
authfile with {"<user:pass>": [""]}.
--authfile, An optional path to a users.json file. This file should
be an object with users defined like:
{
Expand All @@ -113,6 +109,10 @@ var serverHelp = `
of address regular expressions for a match. Addresses will
always come in the form "<host/ip>:<port>".
--auth, An optional string representing a single user with full
access, in the form of <user:pass>. This is equivalent to creating an
authfile with {"<user:pass>": [""]}.
--proxy, Specifies another HTTP server to proxy requests to when
chisel receives a normal HTTP request. Useful for hiding chisel in
plain sight.
Expand Down Expand Up @@ -219,7 +219,7 @@ var clientHelp = `
--auth, An optional username and password (client authentication)
in the form: "<user>:<pass>". These credentials are compared to
the credentials inside the server's --authfile. defaults to the
AUTH environment variable.
AUTH environment variable.
--keepalive, An optional keepalive interval. Since the underlying
transport is HTTP, in many instances we'll be traversing through
Expand Down

0 comments on commit d7b9d1c

Please sign in to comment.