urlcrypt 0.0.1 → 0.1.0

data/README.md

@@ -1,34 +1,34 @@
 # URLcrypt
 
+[![Build Status](https://travis-ci.org/madrobby/URLcrypt.png?branch=master)](https://travis-ci.org/madrobby/URLcrypt)
+
 Ever wanted to securely transmit (not too long) pieces of arbitrary binary data
-in a URL? *urlencrypt* makes it easy!
+in a URL? **URLcrypt** makes it easy!
 
-This gem is based on the base32 gem from Samuel Tesla.
+This gem is based on the [base32](https://github.com/stesla/base32) gem from Samuel Tesla.
 
-URLcrypt uses a 256-bit AES symmetric encryption to securely encrypt data, and
-and encodes and decodes Base 62 strings that can be used directly in URLs.
+URLcrypt uses **256-bit AES symmetric encryption**
+to securely encrypt data, and encodes and decodes 
+**Base 32 strings that can be used directly in URLs**.
 
-For example, this can be used to securely store user ids and the like when you 
-access a web application from a place that doesn't have other authentication
-mechanisms, like when you load an image in an email.
+This can be used to securely store user ids, download expiration dates and 
+other arbitrary data like that when you access a web application from a place 
+that doesn't have other authentication or persistence mechanisms (like cookies):
+ 
+  * Loading a generated image from your web app in an email
+  * Links that come with an expiration date (à la S3)
+  * Mini-apps that don't persist data on the server
 
-URLcrypt uses a modified Base 32 algorithm that doesn't use padding characters,
-and doesn't use vowels to avoid bad words in the generated string.
-
-The main reason why Base 32 is useful is that Ruby's built-in Base 64 support
-is, IMO, looking ugly in URLs and requires several characters that need to be 
-URL-escaped.
-
-Unfortunately, some other gems out there that in theory could handle this 
-(like the radix gem) fail with strings that start with a "\0" byte.
+Works with Ruby 1.8, 1.9 and 2.0.
 
-*WORD OF WARNING* THERE IS NO GUARANTEE WHATSOEVER THAT THIS GEM IS ACTUALLY
-SECURE AND WORKS. USE AT YOUR OWN RISK.
+**Important**: As a general guideline, URL lengths shouldn't exceed about 2000 
+characters in length, as URLs longer than that will not work in some browsers
+and with some (proxy) servers. This limits the amount of data you can store
+with URLcrypt.
 
-Note: this is version 0.0.1 which doesn't actually come with the encryption part
-just yet. It will only work on Ruby 1.8.7 for now.
+**WORD OF WARNING: THERE IS NO GUARANTEE WHATSOEVER THAT THIS GEM IS ACTUALLY SECURE AND WORKS. USE AT YOUR OWN RISK.**
 
-Patches are welcome, please include tests.
+Patches are welcome; please include tests!
 
 ## Installation
 
@@ -37,16 +37,56 @@ Add the `urlcrypt` gem to your Gemfile.
 ## Simple Example
 
 ```ruby
+# encrypt and encode with 256-bit AES
+# one-time setup, set this to a securely random key with at least 256 bits, see below
+URLcrypt::key = '...' 
+
+# now encrypt and decrypt!
+URLcrypt::encrypt('chunky bacon!')        # => "sgmt40kbmnh1663nvwknxk5l0mZ6Av2ndhgw80rkypnp17xmmg5hy"
+URLcrypt::decrypt('sgmt40kbmnh1663nvwknxk5l0mZ6Av2ndhgw80rkypnp17xmmg5hy')
+  # => "chunky bacon!"
+
+# encoding without encryption (don't use for anything sensitive!), doesn't need key set
 URLcrypt.encode('chunky bacon!')          # => "mnAhk6tlp2qg2yldn8xcc"
 URLcrypt.decode('mnAhk6tlp2qg2yldn8xcc')  # => "chunky bacon!"
 ```
 
+### Generating keys
+
+The easiest way to generate a secure key is to use `rake secret` in a Rails app:
+
+```
+% rake secret
+ba7f56f8f9873b1653d7f032cc474938fd749ee8fbbf731a7c41d698826aca3cebfffa832be7e6bc16eaddc3826602f35d3fd6b185f261ee8b0f01d33adfbe64
+```
+
+To use the key with URLcrypt, you'll need to convert that from a hex string into a real byte array:
+
+```
+URLcrypt::key = ['longhexkeygoeshere'].pack('H*')
+```
+
 ## Running the Test Suite
 
 If you want to run the automated tests for URLcrypt, issue this command from the
 distribution directory.
 
-  % rake test:all
+```
+% rake test:all
+```
+
+## Why not Base 64, or an other radix/base library?
+
+URLcrypt uses a modified Base 32 algorithm that doesn't use padding characters,
+and doesn't use vowels to avoid bad words in the generated string.
+
+The main reason why Base 32 is useful is that Ruby's built-in Base 64 support
+is, IMO, looking ugly in URLs and requires several characters that need to be 
+URL-escaped.
+
+Unfortunately, some other gems out there that in theory could handle this 
+(like the radix gem) fail with strings that start with a "\0" byte.
+
 
 ## References
 

data/Rakefile

@@ -37,7 +37,7 @@ gemspec = Gem::Specification.new do |s|
   s.require_paths << 'lib'
   s.requirements << 'none'
   s.summary = "Securely encode and decode short pieces of arbitrary binary data in URLs."
-  s.version = "0.0.1"
+  s.version = "0.1.0"
 end
 
 Gem::PackageTask.new(gemspec) do |pkg|

data/lib/URLcrypt.rb

@@ -1,9 +1,15 @@
+require 'openssl'
+
 module URLcrypt
   # avoid vowels to not generate four-letter words, etc.
   # this is important because those words can trigger spam 
   # filters when URLs are used in emails
   TABLE = "1bcd2fgh3jklmn4pqrstAvwxyz567890".freeze
 
+  def self.key=(key)
+    @key = key
+  end
+
   class Chunk
     def initialize(bytes)
       @bytes = bytes
@@ -25,6 +31,7 @@ module URLcrypt
       [(0..n-1).to_a.reverse.collect {|i| TABLE[(c >> i * 5) & 0x1f].chr},
        ("=" * (8-n))] # TODO: remove '=' padding generation
     end
+    
   end
 
   def self.chunks(str, size)
@@ -38,11 +45,34 @@ module URLcrypt
   end
 
   # strip '=' padding, because we don't need it
-  def self.encode(str)
-    chunks(str, 5).collect(&:encode).flatten.join.tr('=','')
+  def self.encode(data)
+    chunks(data, 5).collect(&:encode).flatten.join.tr('=','')
   end
 
-  def self.decode(str)
-    chunks(str, 8).collect(&:decode).flatten.join
+  def self.decode(data)
+    chunks(data, 8).collect(&:decode).flatten.join
+  end
+  
+  def self.decrypt(data)
+    parts = data.split('Z').map{|part| decode(part)}
+    decrypter = cipher(:decrypt)
+    decrypter.iv = parts[0]
+    decrypter.update(parts[1]) + decrypter.final 
   end
+    
+  def self.encrypt(data)
+    crypter = cipher(:encrypt)
+    crypter.iv = iv = crypter.random_iv
+    "#{encode(iv)}Z#{encode(crypter.update(data) + crypter.final)}"
+  end
+  
+  private 
+    
+    def self.cipher(mode)
+      cipher = OpenSSL::Cipher.new('aes-256-cbc')
+      cipher.send(mode)
+      cipher.key = @key
+      cipher
+    end
+
 end

data/test/URLcrypt_test.rb

@@ -1,15 +1,22 @@
+# encoding: utf-8
 require 'test/unit'
 require 'URLcrypt'
 
 class TestURLcrypt < Test::Unit::TestCase
+  def assert_bytes_equal(string1, string2)
+    bytes1 = string1.bytes.to_a.join(':')
+    bytes2 = string2.bytes.to_a.join(':')
+    assert_equal(bytes1, bytes2)
+  end
+  
   def assert_decoding(encoded, plain)
     decoded = URLcrypt.decode(encoded)
-    assert_equal(plain, decoded)
+    assert_bytes_equal(plain, decoded)
   end
 
   def assert_encoding(encoded, plain)
     actual = URLcrypt.encode(plain)
-    assert_equal(encoded, actual)
+    assert_bytes_equal(encoded, actual)
   end
 
   def assert_encode_and_decode(encoded, plain)
@@ -38,5 +45,15 @@ class TestURLcrypt < Test::Unit::TestCase
       assert_decoding(encoded, original)
     end
   end
+  
+  def test_encryption
+    # this key was generated via rake secret in a rails app, the pack() converts it into a byte array
+    URLcrypt::key =
+['d25883a27b9a639da85ea7e159b661218799c9efa63069fac13a6778c954fb6d721968887a19bdb01af8f59eb5a90d256bd9903355c20b0b4b39bf4048b9b17b'].pack('H*')
+    
+    original  = "hello world!"
+    encrypted = URLcrypt::encrypt(original)
+    assert_equal(URLcrypt::decrypt(encrypted), original)
+  end
 
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: urlcrypt
 version: !ruby/object:Gem::Version 
-  hash: 29
+  hash: 27
   prerelease: 
   segments: 
   - 0
-  - 0
   - 1
-  version: 0.0.1
+  - 0
+  version: 0.1.0
 platform: ruby
 authors: 
 - Thomas Fuchs