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 https://github.com/kronn/to_pass/tarball/v1.0.0 -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'
irb> ToPass::Base.new('test', :basic_de).password
# => '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

Customizing¶ ↑

In order to fully utilize to_pass, you need to make your own algorithm.

You can get a list of existing algorithms through the CLI:

$ to_pass --algorithms       # or: to_pass -A

Likewise, you can get a list of existing converters:

$ to_pass --converters       # or: to_pass -C

Configuration¶ ↑

You can customize the default behaviour by adding a configuration file like this

$ mkdir ~/.to_pass
$ echo 'algorithm: basic_de' >> ~/.to_pass/config
$ echo 'pipe_out: false' >> ~/.to_pass/config
$ echo 'pipe_in: false' >> ~/.to_pass/config

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.

Documentation¶ ↑

Most of the Documentation is contained in the doc-directory.

• doc/CHANGELOG

• doc/LICENSE

• doc/RELEASE_NOTES

There is also RDoc API-Documentation inside doc/rdoc.

The Manpages are located in man/ to be compatible with setup.rb. Alongside the roff-version (for ‘man to_pass`) there are HTML-version if you prefer reading docs in the browser.

• man/man1/to_pass.1.html

• man/man5/to_pass-algorithm.5.html

• man/man5/to_pass-converter.5.html

And of course, there is a README, but I think you have found it already…

Copyright¶ ↑

Copyright © 2009-2011 Matthias Viehweger. See doc/LICENSE for details.