Crockford

Douglas Crockford has described an alternate version of Base32. This is NOT RFC 4648.

It excludes the letters I, L, and O, to avoid confusion with digits. It also excludes the letter U to reduce the likelihood of accidental obscenity.

Instead of rejecting the characters it excludes, it normalizes them. This means that if somebody mistook a 0 for a O, we correct it instead of rejecting it. This makes it great for cases where a person needs to type in the code by hand, like a serial number, or a token sent via SMS.

For more information, see Douglas Crockford's own website.

Note: Crockford's Base32 also allows for a checksum character. This functionality has not been implemented yet.

Requirements

The encoding scheme is required to

  • Be human readable and machine readable.
  • Be compact. Humans have difficulty in manipulating long strings of arbitrary symbols.
  • Be error resistant. Entering the symbols must not require keyboarding gymnastics.
  • Be pronounceable. Humans should be able to accurately transmit the symbols to other humans using a telephone.

Usage

Encoding and decoding numbers:

Crockford.encode_number(1234) # => "16J"
Crockford.decode_number("16J") # => 1234

You can split up longer codes with hyphens. Hyphens are ignored when decoding:

Crockford.encode_number(1234567890, split: 4) # => "14S-C0PJ"
Crockford.decode_number("14S-C0-PJ") # => 1234567890

Codes are automatically normalized (unknown characters will turn into ?):

Crockford.decode_number("oil") # => 33
Crockford.decode_number("011") # => 33
Crockford.normalize("oil") # => "011"
Crockford.normalize("wrong@") # => "WR0NG?"
Crockford.normalize("wrong@", unknown: "_") # => "WR0NG_"

You can encode and decode any string (or any raw bytes):

data = SecureRandom.bytes(10) # => "\x06\x9D\xA5\xC1\x9C8\xA9W\xE9^"
code = Crockford.encode_string(data, split: 4) # => "TET-BGCW-72MN-FTAY"
Crockford.decode_string(code) == data # => true

Generate a code:

Crockford.generate(length: 16, split: 4) # => "H222-WEQ8-RHE3-P707"

Installation

Add this line to your application's Gemfile:

gem 'crockford'

And then execute:

$ bundle install

Or install it yourself as:

$ gem install crockford

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and the created tag, and push the .gem file to rubygems.org.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/iain/crockford. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the code of conduct.

License

The gem is available as open source under the terms of the MIT License.

Code of Conduct

Everyone interacting in the Crockford project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.

Prior art

Some of these haven't been updated in over a decade: