= to_pass

== Transformation of a String to a Password.

Passwords should be easy to remember and hard to guess.  One technique is to
have a sentence which can be easily remembered transformed to a password.

This library encapsulates that and satisfies different usage scenarios.
Currently, only two algorithms are provided. But they are YAML-Files, so it's
extensible.


== Installation

to_pass is distributed as rubygem

  $ gem install to_pass

If you want to install from source, you can download a tarball or zipfile from
github.

  $ curl -L http://github.com/kronn/to_pass/tarball/v0.5.2 -o to_pass.tar.gz
  $ tar -xzf to_pass.tar.gz
  $ cd kronn-to_pass-HASHVALUE
  $ ./setup.rb install

The tarball contains a directory which has a part of the commit hash in its
name. I leave it up to the user to change into the right directory. Shouldn't
be too hard ;-)

The same installation procedure works for git-checkouts, of course.

The setup.rb installation has the additional benefit of installing the manpages
for the gem and the file-formats.

== Usage

=== IRB

ToPass::Integration provides a to_pass Method which transforms a sentence to a
password.

  irb> require 'to_pass'
  irb> String.send(:include, ToPass::Integration)
  irb> "Da steht ein Pferd auf dem Flur".to_pass
  # => "Ds1P@dF"

A more direct approach is the facade provided by ToPass::Base

  irb> require 'to_pass'
  irb> ToPass::Base.new('test', :basic_de).to_s
  # => 't35t'

=== CLI

  $ to_pass "test"   # => t35t
  $ to_pass "there is one problem for us, too" -a basic_en # => ti1p4u2

=== CLI with Pipes

This example is a bit Mac OSX-centric, but you should get the point.

  $ echo "test" | to_pass | pbcopy

== Development

If you want to develop it further, patch something or are just plain curious:
you're welcome.  This should get you started:

  $ git clone git://github.com/kronn/to_pass.git
  $ bundle install
  $ rake

Bundler is only used for installing dependencies. ToPass does not have any
runtime dependencies, so Bundler does not make sense there.

The usual pattern for github-projects applies:

* Fork the project.
* Make your feature addition or bug fix.
* Add tests for it. This is important so I don't break it in a
  future version unintentionally.
* Commit, do not mess with rakefile, version, or history.
  (if you want to have your own version, that is fine but bump version in a
  commit by itself I can ignore when I pull)
* Send me a pull request.

I'll take a look at it and try to integrate it. If I cannot apply your changes
or don't want to, I'll let you know.

== Copyright

Copyright (c) 2009-2010 Matthias Viehweger. See LICENSE for details.