/human_key

Ruby class for human-friendly secret API keys, confirmation links, one-time access codes

Primary LanguageRuby

NOTE
====

This library is no longer maintained.

USAGE
=====

It can be easy to confuse 0 with O, 1 with l etc.

HumanKey generates secret random keys that don't contain these confusing characters.

This reduces human error, especially if the secret key is likely to spoken or transcribed to paper.

*** HumanKey is for disposable, low-value keys or uids. HumanKey should not be used if you require proper secure crypto. ***

Usage
=====

Textgoeshere::HumanKey.generate
# => "4fg7-hkq9-2dfg-m6vx"

Options
=======

HumanKey.generate accepts a hash of options:

length
------

Length of key to return excluding splitter characters. Ignored if :key option is supplied. Default 12.

key
---

By default, HumanKey uses Digest::Sha1.hexdigest to generate a raw key, but you can supply your own via :key. Using a multibyte key in Ruby 1.8 may have nast side effects. 

splitter
--------

To make it easier to read, key can be split into segements joined by a splitter character e.g. "4f67-xx75". Key will not be split if this is false. Default "-"

segment_length
--------------

Length of segment to split key into. Ignored if splitter is false. Key will not be split if segment length is greater than key length. The last segment will contain fewer characters
if segment length is not perfect factor of key length e.g.

Textgoeshere::HumanKey.generate(:length => 5, :segment_length => 2)
# => "x2-69-q"

Default 4.

prefix, suffix
--------------

Pass in a prefix or suffix to the key (insertion takes place after splitting). This is useful if, for example, you want every key to start with a customer reference. Default nil.

Tests
=====

Run the file to execute the small test suite.

License
=======

Copyright (c) 2010 David Nolan

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
THE SOFTWARE.