Go version of Camo server.
Camo is a special type of image proxy that proxies non-secure images over SSL/TLS. This prevents mixed content warnings on secure pages.
It works in conjunction with back-end code to rewrite image URLs and sign them with an HMAC.
First you parse the original URL, generate an HMAC signature of it, then hex encode it, and then place the pieces into the expected format replacing the original image URL.
The client requests the URL to Go-Camo. Go-Camo validates the HMAC, decodes the URL, requests the content and streams it to the client.
Go-Camo supports both hex and base64 encoded urls at the same time. Base64 urls are shorter, but a bit more computationally expensive to decode. Hex urls are longer, but are case insensitive.
Here is some example python code that demonstrates generating an encoded URL in both hex and base64:
import hashlib
import hmac
import base64
def hex_camo_url(hmac_key, image_url, camo_host):
if image_url.startswith("https:"):
return image_url
hexdigest = hmac.new(hmac_key, image_url, hashlib.sha1).hexdigest()
hexurl = image_url.encode('hex')
requrl = 'https://%s/%s/%s' % (camo_host, hexdigest, hexurl)
return requrl
>>> hex_camo_url("test", "http://golang.org/doc/gopher/frontpage.png", "img.example.org")
'https://img.example.org/0f6def1cb147b0e84f39cbddc5ea10c80253a6f3/687474703a2f2f676f6c616e672e6f72672f646f632f676f706865722f66726f6e74706167652e706e67'
def b64_camo_url(hmac_key, image_url, camo_host):
if image_url.startswith("https:"):
return image_url
b64digest = base64.urlsafe_b64encode(
hmac.new(hmac_key, image_url, hashlib.sha1).digest()).strip('=')
b64url = base64.urlsafe_b64encode(image_url).strip('=')
requrl = 'https://%s/%s/%s' % (camo_host, b64digest, b64url)
return requrl
>>> b64_camo_url("test", "http://golang.org/doc/gopher/frontpage.png", "img.example.org")
'https://img.example.org/D23vHLFHsOhPOcvdxeoQyAJTpvM/aHR0cDovL2dvbGFuZy5vcmcvZG9jL2dvcGhlci9mcm9udHBhZ2UucG5n'
While Go-Camo will support proxying HTTPS images as well, for performance reasons you may choose to filter HTTPS requests out from proxying, and let the client simply fetch those as they are. The code example above does this.
Note that it is recommended to front Go-Camo with a CDN when possible.
- Go-Camo supports 'Path Format' url format only. Camo's "Query String Format" is not supported.
- Go-Camo supports "allow regex host filters".
- Go-Camo supports client http keep-alives.
- Go-Camo provides native SSL support.
- Go-Camo supports using more than one os thread (via GOMAXPROCS) without the need of multiple instances or additional proxying.
- Go-Camo builds to a static binary. This makes deploying to large numbers of servers a snap.
- Go-Camo supports both Hex and Base64 urls. Base64 urls are smaller, but case sensitive.
Building requires git and make. Optional requirements are pod2man (to
build man pages), and fpm (to build rpms). A functional Go installation
is also required.
# show make targets
$ make
Available targets:
help this help
clean clean up
all build binaries and man pages
build build all
build-go-camo build go-camo
build-url-tool build url tool
build-simple-server build simple server
test run tests
man build all man pages
man-go-camo build go-camo man pages
man-url-tool build url-tool man pages
man-simple-server build simple-server man pages
rpm build rpm
# build all binaries and man pages. results will be in build/ dir
$ make all
# as an alternative to the previous command, build and strip debug symbols.
# this is useful for production, and reduces the resulting file size.
$ make all GOBUILD_OPTS="-ldflags '-s'"
$ $GOPATH/bin/go-camo -c config.json
Go-Camo does not daemonize on its own. For production usage, it is recommended to launch in a process supervisor, and drop privileges as appropriate.
Examples of supervisors include: daemontools, runit, upstart, launchd, and many more.
For the reasoning behind lack of daemonization, see daemontools/why. In addition, the code is much simpler because of it.
In order to use this on Heroku with the provided Procfile, you need to:
- Create an app specifying the https://github.com/kr/heroku-buildpack-go buildpack
- Set
HMAC_KEYto the key you are using
$ $GOPATH/bin/go-camo -h
Usage:
go-camo [OPTIONS]
Application Options:
-c, --config= JSON Config File
-k, --key= HMAC key
--stats Enable Stats
--max-size= Max response image size (KB) (5120)
--timeout= Upstream request timeout (4s)
--max-redirects= Maximum number of redirects to follow (3)
--listen= Address:Port to bind to for HTTP (0.0.0.0:8080)
--ssl-listen= Address:Port to bind to for HTTPS/SSL/TLS
--ssl-key= ssl private key (key.pem) path
--ssl-cert= ssl cert (cert.pem) path
-v, --verbose Show verbose (debug) log level output
-V, --version print version and exit
Help Options:
-h, --help Show this help message
$ cat config.json
{
"HmacKey": "Some long string here...",
"AllowList": []
}
HmacKeyis a secret key seed to the HMAC used for signing and validation.Allowlistis a list of regex host matches to allow.
If an AllowList is defined, and a request does not match one of the listed host regex, then the request is denied. Default is all requests pass the Allowlist if none is specified.
Option flags, if provided, override those in the config file.
If stats flag is provided, then the service will track bytes and clients
served, and offer them up at an http endpoint /status via HTTP GET request.
Go-Camo includes a couple of additional tools.
The url-tool utility provides a simple way to generate signed URLs from the command line.
$ $GOPATH/bin/url-tool -h
Usage:
url-tool [OPTIONS] <decode | encode>
Application Options:
-k, --key= HMAC key
-p, --prefix= Optional url prefix used by encode output
Help Options:
-h, --help Show this help message
Available commands:
decode Decode a url and print result
encode Encode a url and print result
Example usage:
# hex
$ $GOPATH/bin/url-tool -k "test" -p "https://img.example.org" encode "http://golang.org/doc/gopher/frontpage.png"
https://img.example.org/0f6def1cb147b0e84f39cbddc5ea10c80253a6f3/687474703a2f2f676f6c616e672e6f72672f646f632f676f706865722f66726f6e74706167652e706e67
$ $GOPATH/bin/url-tool -k "test" decode "https://img.example.org/0f6def1cb147b0e84f39cbddc5ea10c80253a6f3/687474703a2f2f676f6c616e672e6f72672f646f632f676f706865722f66726f6e74706167652e706e67"
http://golang.org/doc/gopher/frontpage.png
# base64
$ $GOPATH/bin/url-tool -k "test" -p "https://img.example.org" encode -b base64 "http://golang.org/doc/gopher/frontpage.png"
https://img.example.org/D23vHLFHsOhPOcvdxeoQyAJTpvM/aHR0cDovL2dvbGFuZy5vcmcvZG9jL2dvcGhlci9mcm9udHBhZ2UucG5n
$ $GOPATH/bin/url-tool -k "test" decode "https://img.example.org/D23vHLFHsOhPOcvdxeoQyAJTpvM/aHR0cDovL2dvbGFuZy5vcmcvZG9jL2dvcGhlci9mcm9udHBhZ2UucG5n"
http://golang.org/doc/gopher/frontpage.png
The simple-server utility is useful for testing. It serves the contents of a
given directory over http. Nothing more.
$ $GOPATH/bin/simple-server -h
Usage:
simple-server [OPTIONS] DIR
Application Options:
-l, --listen= Address:Port to bind to for HTTP (0.0.0.0:8000)
Help Options:
-h, --help Show this help message
See CHANGELOG.md
Released under the MIT
license. See LICENSE.md
file for details.