Full README

README.md

@@ -1,12 +1,20 @@
 # Imgproxy
 
-Fast and secure micro-service for resizing and converting remote images.
+Fast and secure microservice for resizing and converting remote images.
+
+<a href="https://evilmartians.com/?utm_source=overmind">
+<img src="https://evilmartians.com/badges/sponsored-by-evil-martians.svg" alt="Sponsored by Evil Martians" width="236" height="54">
+</a>
 
 Imgproxy does one thing, and it does it well: resizing of remote images. It works great when you need to resize some images on the fly to make them look good on your web page. The main principles of Imgproxy are simplicity, speed, and security.
 
-#### Simlicity
+#### Simplicity
+
+One of the things I believe in is: "The best feature is the one you don't need to implement." That's why I implemented only features that most of us need.
 
-One of the things I believe in is: "The best feature is the one you don't need to implement." That's why I implemented only features that most of us need. Rotation, flip, flop, etc. are cool, but I don't think that you want to process your web page images that ways, especially when you can do this with CSS.
+* Rotation, flip, flop, etc. are good, but it's better to do this with CSS;
+* Caching is good, but it's better to use CDN or caching server for this;
+* HTTPS is good, but it's better to use TCP proxy-server like NGINX.
 
 #### Speed
 
@@ -24,75 +32,146 @@ Processing of remote images is a quite vulnerable thing. There are many ways to
 
 * Imgproxy supports authorization by HTTP header. This prevents using imgproxy directly by an attacker but allows to use it through CDN or a caching server.
 
-### How to install
+## Installation
 
-1. Install [vips](https://github.com/jcupitt/libvips). On macOS you can do:
+There are two ways you can currently install imgproxy:
 
-  ```
+#### From the source
+
+1. Install [vips](https://github.com/jcupitt/libvips)
+
+  ```bash
+  # macOS
   $ brew tap homebrew/science
   $ brew install vips
+
+  # Ubintu
+  $ sudo apt-get install libvips
   ```
 
 2. Install imgproxy itself
 
-  ```
+  ```bash
   $ go get github.com/DarthSim/imgproxy
   ```
 
-### How to configure
+#### Docker
+
+```bash
+$ docker build -t imgproxy .
+```
+
+## Configuration
+
+Imgproxy is 12factor-ready and can be configured with env variables.
+
+#### Path signature
 
-Imgproxy is 12factor-ready and can be configured with env variables:
+Imgproxy requires all paths to be signed with key and salt:
+
+* IMGPROXY_KEY - (**required**) hex-encoded key;
+* IMGPROXY_SALT - (**required**) hex-encoded salt;
+
+You can also specify paths to a files with hex-encoded key and salt (useful in a development evironment):
+
+```bash
+$ imgproxy -keypath /path/to/file/with/key -saltpath /path/to/file/with/salt
+```
+
+You can easily generate key and salt with `openssl enc -aes-256-cbc -P -md sha256`.
+
+#### Server
 
 * IMGPROXY_BIND - TCP address to listen on. Default: :8080;
 * IMGPROXY_READ_TIMEOUT - the maximum duration (seconds) for reading the entire request, including the body. Default: 10;
 * IMGPROXY_WRITE_TIMEOUT - the maximum duration (seconds) for writing the response. Default: 10;
+
+#### Security
+
+Imgproxy protects you from image bombs. Here you can specify maximum image dimension which you're ready to process:
+
 * IMGPROXY_MAX_SRC_DIMENSION - the maximum dimension of source image. Images with larger size will be rejected. Default: 4096;
+
+Also you can specify secret to enable authorization with HTTP `Authorization` header:
+
+* IMGPROXY_SECRET - auth token. If specified, request should contain `Authorization: Bearer %secret%` header;
+
+#### Compression
+
 * IMGPROXY_QUALITY - quality of a result image. Default: 80;
 * IMGPROXY_GZIP_COMPRESSION - GZip compression level. Default: 5;
-* IMGPROXY_KEY - hex-encoded key
-* IMGPROXY_SALT - hex-encoded salt
 
-You can also specify paths to a files with hex-encoded key and salt:
+## Generating url
+
+Url path should contain signature and resizing params like this:
 
 ```
-imgproxy -keypath /path/to/file/with/key -salt /path/to/file/with/salt
+/%signature/%resizing_type/%width/%height/%gravity/%enlarge/%encoded_url.%extension
 ```
 
-### How to generate url path
+#### Resizing type
 
-Here is a short ruby sample which shows how to generate url path for imgproxy.
+Imgproxy supports the following resizing types:
 
-```ruby
-require 'openssl'
-require 'base64'
+* `fit` - resizes image keeping aspect ratio to fit given size;
+* `fill` - resizes image keeping aspect ratio to fill given size and crops projecting parts;
+* `crop` - crops image to given size;
+* `force` - resizes image to given size breaking aspect ratio.
 
-# Key and salt. Since they're hex-encoded, we should decode it.
-key = ['943b421c9eb07c830af81030552c86009268de4e532ba2ee2eab8247c6da0881'].pack("H*")
-salt = ['520f986b998545b4785e0defbc4f3c1203f22de2374a3d53cb7a7fe9fea309c5'].pack("H*")
+#### Width and height
 
-# This is remote url with requested image
-url = "http://img.example.com/pretty/image.jpg"
+Width and height define size of the result image. The result dimensions may be not equal to the given depending on what resizing type was applied.
 
-# Url should be encoded with base64 and could be splitted
-encodedUrl = Base64.urlsafe_encode64(url).tr("=", "").scan(/.{1,16}/).join("/")
+#### Gravity
 
-# Allowed values for resize are: fill, fit, crop and resize
-resize = 'fill'
-width = 300
-height = 300
-# Allowed values for gravity are: no (north), so (south), ea (east), we (west)
-# ce (center) and sm (smart). "sm" works correctly only with resize == crop.
-gravity = 'no'
-# Should we enlarge small images? 1 for yes, and 0 for no.
-enlarge = 1
-# Allowed extensions are png and jpg/jpeg.
-extension = 'png'
+When imgproxy needs to cut some parts of the image, it's guided by gravity. The following values are supported:
 
-path = "/#{resize}/#{width}/#{height}/#{gravity}/#{enlarge}/#{encodedUrl}.#{extension}"
+* `no` - north (top edge);
+* `so` - south (bottom edge);
+* `ea` - east (right edge);
+* `we` - west (left edge);
+* `ce` - center;
+* `sm` - smart. Vips detects the most interesting section of the image and considers it as the center of the result image. **Note:** This value applicable only to the crop resizing.
 
-# Now we need to sign path with HMAC (SHA256)
-digest = OpenSSL::Digest.new('sha256')
-hmac = Base64.urlsafe_encode64(OpenSSL::HMAC.digest(digest, key, "#{salt}#{path}")).tr('=', '')
+#### Enlarge
 
-signed_path = "/#{hmac}#{path}"
-```
+This param is `0`, imgproxy won't enlarge image if it's smaller that given size. With any other value imgproxy will enlarge image.
+
+#### Encoded url
+
+The source url should be encoded with url-safe base64. Encoded url can be splitted with `/` for your needs.
+
+#### Extension
+
+Extension specifies the format of the result image. Imgproxy supports only `jpg` and `png` as the most popular web-image formats.
+
+#### Signature
+
+Signature is a url-safe base64-encoded HMAC digest of the rest of the path including leading `/`.
+
+* Take the path after signature - `/%resizing_type/%width/%height/%gravity/%enlarge/%encoded_url.%extension`;
+* Add salt to the beginning;
+* Calc HMAC digest using SHA256;
+* Encode the result with url-secure base64.
+
+You can find code snippets in the `examples` folder.
+
+## Source images formats support
+
+Imgproxy supports only three most popular images formats: PNG, JPEG and GIF.
+
+**Known issue:** Libvips may not support some kinds of JPEG, if you met this issue, you may need to build libvips with ImageMagick or GraphicMagick support. See https://github.com/jcupitt/libvips#imagemagick-or-optionally-graphicsmagick
+
+## Special thanks
+
+Special thanks to [h2non](https://github.com/h2non) and all authors and contributors of [bimg](https://github.com/h2non/bimg).
+
+## Author
+
+Sergey "DarthSim" Aleksandrovich
+
+## License
+
+Imgproxy is licensed under the MIT license.
+
+See LICENSE for the full license text.

examples/signature.go

@@ -0,0 +1,45 @@
+package main
+
+import (
+	"crypto/hmac"
+	"crypto/sha256"
+	"encoding/base64"
+	"encoding/hex"
+	"fmt"
+	"log"
+)
+
+func main() {
+	key := "943b421c9eb07c830af81030552c86009268de4e532ba2ee2eab8247c6da0881"
+	salt := "520f986b998545b4785e0defbc4f3c1203f22de2374a3d53cb7a7fe9fea309c5"
+
+	var keyBin, saltBin []byte
+	var err error
+
+	if keyBin, err = hex.DecodeString(key); err != nil {
+		log.Fatalln("Key expected to be hex-encoded string")
+	}
+
+	if saltBin, err = hex.DecodeString(salt); err != nil {
+		log.Fatalf("Salt expected to be hex-encoded string")
+	}
+
+	resize := "fill"
+	width := 300
+	height := 300
+	gravity := "no"
+	enlarge := 1
+	extension := "png"
+
+	url := "http://img.example.com/pretty/image.jpg"
+	encodedURL := base64.RawURLEncoding.EncodeToString([]byte(url))
+
+	path := fmt.Sprintf("/%s/%d/%d/%s/%d/%s.%s", resize, width, height, gravity, enlarge, encodedURL, extension)
+
+	mac := hmac.New(sha256.New, keyBin)
+	mac.Write(saltBin)
+	mac.Write([]byte(path))
+	signature := base64.RawURLEncoding.EncodeToString(mac.Sum(nil))
+
+	fmt.Printf("/%s%s", signature, path)
+}

examples/signature.rb

@@ -0,0 +1,25 @@
+require "openssl"
+require "base64"
+
+key = ["943b421c9eb07c830af81030552c86009268de4e532ba2ee2eab8247c6da0881"].pack("H*")
+salt = ["520f986b998545b4785e0defbc4f3c1203f22de2374a3d53cb7a7fe9fea309c5"].pack("H*")
+
+url = "http://img.example.com/pretty/image.jpg"
+
+# You can trim padding spaces to get good-looking url
+encoded_url = Base64.urlsafe_encode64(url).tr("=", "").scan(/.{1,16}/).join("/")
+
+resize = "fill"
+width = 300
+height = 300
+gravity = "no"
+enlarge = 1
+extension = "png"
+
+path = "/#{resize}/#{width}/#{height}/#{gravity}/#{enlarge}/#{encoded_url}.#{extension}"
+
+digest = OpenSSL::Digest.new("sha256")
+# You can trim padding spaces to get good-looking url
+hmac = Base64.urlsafe_encode64(OpenSSL::HMAC.digest(digest, key, "#{salt}#{path}")).tr("=", "")
+
+signed_path = "/#{hmac}#{path}"