passphrase 0.1.0 → 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 04b13682c8ca0850aec87893eacd4e3ef53bcdd8
+  data.tar.gz: e758d10b4ae02a3b76906512fbd545fd21f461dc
+SHA512:
+  metadata.gz: ed1766c82ecf11aab014e0b41fdccb00504f13456671130b5da70f013369d855673a2a4e84548a5c65edda150161b797503e1bcc62e606f99a2d01c29e05e626
+  data.tar.gz: 59d155d31002868739678ddd654ebb2196ebc74e5a852a56afa216f69e18871b8ae311e0194a9de5850fee1dd3329b68b9b1dcc72a2994be83b0442c0cbd8577

checksums.yaml.gz.sig

@@ -0,0 +1 @@
+|��)�VMg�Ų�<R�)�S�MLy�|�9����
/�����ɟ��.�&:��,����<�Kζ�?��7&�t]f��K1�uN��sc���S��I��x<т�׼iBtGo&J�O���~�[�w��ٕ�O�}�I�ˋ��+�Hg��ŅEG{<��~�R|��5p�.�gMn�,���u��z|(����8;w�.��ౙ���w3`]�/.�u��Ѓ��
_��-�Xa�Ϭ�"�u��j	�[��<N�nC

data.tar.gz.sig

@@ -0,0 +1 @@
+

data/CHANGELOG.md

@@ -0,0 +1,35 @@
+# Change Log
+All notable changes to this project will be documented in this file. This
+project adheres to [Semantic Versioning](http://semver.org/).
+
+## Version 1.0.0 - 2015-04-06
+This release is a complete re-write. None of the code from the previous
+release was retained.
+
+### Added
+- Added YARD-style documentation throughout.
+- Added an RSpec test suite using the newer syntax that comes with
+  version ~> 3.0.
+- Added option `--use-random|-r` for specifying RANDOM.ORG as a source of
+  random numbers.
+- The gem is cryptographically signed.
+
+### Changed
+- Absolutely everything!
+- Changed the default source for random numbers from the RANDOM.ORG web site
+  to the SecureRandom standard library.
+- Diceware method selects words from 15 multi-lingual wordlists.
+- Wordlists are stored in an SQLite 3 database file.
+- Code organized to conform to current RubyGems guidelines.
+- Re-designed the library to make it easier to use in client code.
+
+### Removed
+- Removed option `--mix|-m` for mixing in a capital letter, number, and a
+  special character.
+- Removed option `--local|-l` to force the use of the SecureRandom standard
+  library to generate random numbers.
+- Replaced the hash used to store the wordlists with an external SQLite 3
+  database file.
+
+## Version 0.1.0 - 2011-04-25
+No change log was maintained for this and prior versions.

data/LICENSE

@@ -0,0 +1,19 @@
+Copyright (c) 2015 Edmund Sumbar
+
+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.

data/README.md

@@ -0,0 +1,178 @@
+# Passphrase
+Use Passphrase to generate a passphrase for SSH or GPG keys. For example, on
+the command-line, run
+
+    $ passphrase --num-words=4
+    dokusi uolgo allunga totalisa
+
+or programmatically,
+
+    require "passphrase"
+    p = Passphrase::Passphrase.new(number_of_words: 4)
+    p.generate
+    passphrase = p.passphrase
+
+Eliminate the spaces between words to use the result as a potential password.
+
+## Installation
+The Passphrase command-line tool and library can be installed with
+
+    $ gem install passphrase
+
+However, because the gem is cryptographically signed to prevent tampering, the
+preferred installation command should include the `--trust-policy` security
+option, which causes the gem to be verified before being installed. To invoke
+this option, you must first add my public key `esumbar.pem` to your list of
+trusted certificates, as follows.
+
+    $ gem cert --add <(curl -Ls https://raw.githubusercontent.com/esumbar/passphrase/master/certs/esumbar.pem)
+
+Finally, specify the appropriate security level when installing.
+
+    $ gem install passphrase --trust-policy MediumSecurity
+
+Using `MediumSecurity` rather than `HighSecurity` omits dependent gems, in
+this case `sqlite3`, which is not signed, from the verification process.
+
+## Basic usage
+### Command-line tool
+
+    $ passphrase --help
+    Usage: passphrase [options]
+        -n, --num-words=NUM           Number of words in passphrase 3..10
+                                      (default: 5)
+        -r, --[no-]random-org         Use random.org to generate random numbers
+                                      (default: --no-random-org)
+        -h, --help                    Show this message
+        -v, --version                 Show version
+
+    $ passphrase
+    sinmak termyne ismus affidavo recur
+
+    $ passphrase -n 4
+    apaisado vermouth seemag ebelik
+
+### Ruby library
+
+    require "passphrase"
+
+    # generate a passphrase with default options
+    p = Passphrase::Passphrase.new
+    p.generate
+    puts "passphrase: #{p}"
+    puts "passphrase internals: #{p.inspect}"
+
+    # generate three four-word passphrases using RANDOM.ORG
+    options = { number_of_words: 4, use_random_org: true }
+    p = Passphrase::Passphrase.new(options)
+    passphrase1 = p.generate.passphrase
+    passphrase2 = p.generate.passphrase
+    passphrase3 = p.generate.passphrase
+
+    # generate an array of six-word passphrases
+    passphrase_array = Array.new(100)
+    Passphrase::Passphrase.new(number_of_words: 6) do |p|
+      passphrase_array.map! { |e| p.generate.passphrase }
+    end
+
+## Background
+Passphrase implements the [Diceware
+Method](http://world.std.com/~reinhold/diceware.html) which constructs a
+passphrase by randomly selecting words from a predefined list of more-or-less
+meaningful words. Because the words are meaningful, the resulting passphrase
+is easier to remember and type. And because the selection is random, it is
+more secure. The more words in a passphrase, the better. However, four or five
+is optimal.
+
+The original Diceware wordlist from 1995 contained only English words. Since
+then, [Diceware-compatible wordlists in other
+languages](https://blog.agilebits.com/2013/04/16/1password-hashcat-strong-master-passwords/expanded-dicelists/) have been published and are incorporated
+into Passphrase. Unfortunately, the enhanced security of the result comes at
+the expense of having to deal with words from potentially unfamiliar languages.
+_Note that these are not merely translations of the original Diceware
+wordlist._
+
+Passphrase includes wordlists in the following 15 languages (stored in an
+SQLite 3 database file).
+
+1. Afrikaans
+2. Croatian
+3. Czech
+4. Diceware (the original Diceware wordlist)
+5. English
+6. Finnish
+7. French
+8. Italian
+9. Japanese
+10. Latin
+11. Norwegian
+12. Polish
+13. Spanish
+14. Swedish
+15. Turkish
+
+Except in the original Diceware list, all words are lower case, comprised of
+characters from the ascii set `[a-z]`. The original Diceware list includes
+some "words" with numerical and punctuation characters. No word appears more
+than once in this set of wordlists.
+
+The _dice_ in Diceware refers to the act of rolling a die to achieve
+randomness. A sequence of five consecutive rolls has 7776 (6<sup>5</sup>)
+possible outcomes. Each combination maps to one line in a given wordlist, and
+each line, in turn, is composed of between 1 and 15 words (depending on the
+language, the average being 5).
+
+Therefore, to select a word, Passphrase
+
+1. randomly selects one of 15 languages
+2. randomly selects one of 7776 lines from the corresponding wordlist
+3. randomly selects one word from the corresponding line
+
+This leads to roughly 10<sup>28</sup> possible five-word passphrases, for
+example.
+
+Passphrase simulates the rolls of a die by using random numbers from one of
+two sources. The default is to use the standard SecureRandom class. You also
+have the option of requesting random numbers from
+[RANDOM.ORG](http://www.random.org). However, because RANDOM.ORG depends on
+network access, it is susceptible to network problems, and is also slower.
+
+## Contributing to Passphrase
+### Getting started
+After forking the [repository on
+GitHub](https://github.com/esumbar/passphrase), go to your local copy of the
+repository  and execute `bundle install` to ensure that all development gems
+are installed.
+
+Then, run `rake database` to create and populate the wordlist database. Note
+that even though raw data files for Hungarian and Swahili exist, these
+languages are excluded from the database because they do not have a full
+compliment of 7776 entries.
+
+To run the command-line tool within the repository directory, try `ruby -Ilib
+bin/passphrase`. You can also experiment with the library in irb. For example,
+
+    $ irb -Ilib -rpassphrase
+    >> p = Passphrase::Passphrase.new(number_of_words: 3)
+    => {:passphrase=>"", :number_of_words=>0, :word_origins=>{}}
+    >> p.generate
+    => {:passphrase=>"bolt flanella ininaen", :number_of_words=>3,...}
+    >> p.passphrase
+    => "bolt flanella ininaen"
+
+Run the tests with `rake spec`.
+
+### Future enhancements
+In order to make passphrases more acceptable as passwords, a feature could be
+added to the library to upcase a random letter, replace a random alphabetic
+character with a numeric character (if one does not already exist), and mix in
+a special character, like "`$`" or "`%`" etc. The command-line option could be
+called `--passwordize|-p`.
+
+## Changelog
+See {file:CHANGELOG.md} for a list of changes.
+
+## License
+Passphrase &copy; 2011-2015 by [Edmund Sumbar](mailto:esumbar@gmail.com).
+Passphrase is licensed under the MIT license. Please see the {file:LICENSE}
+document for more information.

data/bin/passphrase

@@ -1,12 +1,5 @@
-#! /usr/bin/env ruby
+#!/usr/bin/env ruby
 
-require 'passphrase/generator'
+require "passphrase"
 
-p = Passphrase::Generator.new(ARGV)
-p.run
-if p.mix?
-  puts "unmixed phrase => #{p.unmixed_phrase}"
-  puts "passphrase     => #{p.phrase}"
-else
-  puts "passphrase => #{p.phrase}"
-end
+Passphrase::CLI.parse(ARGV)

data/lib/passphrase.rb

@@ -0,0 +1,11 @@
+require "passphrase/default"
+require "passphrase/diceware_method"
+require "passphrase/diceware_random"
+require "passphrase/language_query"
+require "passphrase/passphrase"
+require "passphrase/version"
+require "passphrase/word_query"
+
+module Passphrase
+  autoload(:CLI, "passphrase/CLI")
+end

data/lib/passphrase/CLI.rb

@@ -0,0 +1,76 @@
+require "optparse"
+
+module Passphrase
+  # The CLI class encapsulates a simple command line interface to the
+  # {Passphrase} library. The class method {parse} merges any given command
+  # line arguments with a hash of default options. The resulting hash is then
+  # used to instantiate a Passphrase object and generate one passphrase, which
+  # is printed on standard output.
+  # @example
+  #   require "passphrase"
+  #   Passphrase::CLI.parse(ARGV)
+  class CLI
+    # @param args [Array<String>] array of command line elements, typically
+    #   given by ARGV (may be empty)
+    # @return [void]
+    def self.parse(args)
+      options = Default.options
+
+      default_number_of_words = Default.options[:number_of_words]
+      default_random_org = Default.options[:use_random_org] ? "--random-org" : "--no-random-org"
+
+      parser = OptionParser.new do |opts|
+        opts.banner = "Usage: passphrase [options]"
+        opts.on(:REQUIRED, "-n NUM", "--num-words=NUM", Integer,
+          "Number of words in passphrase #{Default.number_range}",
+          "(default: #{default_number_of_words})") do |n|
+            options[:number_of_words] = n
+          end
+        opts.on(:NONE, "-r", "--[no-]random-org",
+          "Use random.org to generate random numbers",
+          "(default: #{default_random_org})") do |r|
+            options[:use_random_org] = r
+        end
+        opts.on_tail("-h", "--help", "Show this message") do
+          puts opts
+          exit(0)
+        end
+        opts.on_tail("-v", "--version", "Show version") do
+          puts VERSION
+          exit(0)
+        end
+      end
+
+      begin
+        parser.parse!(args)
+        validate_number_of_words(options)
+        puts Passphrase.new(options).generate
+      rescue OptionParser::InvalidOption => e
+        handle_error(e)
+      rescue OptionParser::MissingArgument => e
+        handle_error(e)
+      # gracefully handle exit(0) from --help and --version options
+      rescue SystemExit => e
+        exit(e.status)
+      rescue Exception => e
+        handle_error(e)
+      end
+    end
+
+    def self.validate_number_of_words(options)
+      number_of_words = options[:number_of_words]
+      unless Default.number_range.include?(number_of_words)
+        raise "number of words out of range #{Default.number_range}"
+      end
+    end
+
+    def self.handle_error(error)
+      STDERR.puts "ERROR: #{error.message}"
+      exit(1)
+    end
+
+    class << self
+      private :validate_number_of_words, :handle_error
+    end
+  end
+end

data/lib/passphrase/default.rb

@@ -0,0 +1,15 @@
+module Passphrase
+  class Default
+    class << self
+      # @return [Hash] the default options that the command line interface
+      #   uses to instantiate a {Passphrase} object in {CLI.parse}
+      attr_reader :options
+      # @return [Range] an arbitrary range specifying the allowable number of
+      #   words in a passphrase, referenced by the {CLI.parse} method
+      attr_reader :number_range
+    end
+
+    @options = { number_of_words: 5, use_random_org: nil }
+    @number_range = (3..10)
+  end
+end

data/lib/passphrase/diceware_method.rb

@@ -0,0 +1,67 @@
+require "sqlite3"
+
+module Passphrase
+  # This class implements the Diceware Method for generating a passphrase. It
+  # selects words from a multi-language wordlist stored in an SQLite 3
+  # database. A special {DicewareRandom} class is provided to work with this
+  # class to simulate rolls of a die.
+  class DicewareMethod
+    # A convenience method for simultaneously creating a new DicewareMethod
+    # object and calling {#run}
+    # @return (see #run)
+    def self.run(options)
+      new(options).run
+    end
+
+    # @param options [Hash] the options passed from the {Passphrase} object
+    def initialize(options)
+      @number_of_words = options[:number_of_words]
+      @random = DicewareRandom.new(options[:use_random_org])
+      setup_database
+      setup_queries
+    end
+
+    # Runs the Diceware method and returns its result to the calling
+    # {Passphrase} object.
+    # @return [Array<Array>] a three element array of the (1) random languages,
+    #   (2) random die rolls, and (3) corresponding random words
+    def run
+      get_random_languages
+      get_random_die_rolls
+      select_words_from_wordlist
+      [@random_languages, @random_die_rolls, @selected_words]
+    end
+
+    private
+
+    def setup_database
+      wordlist_file = "wordlist/words.sqlite3"
+      wordlist_path = File.join(File.dirname(__FILE__), wordlist_file)
+      raise "Wordlist database not found" unless File.exist?(wordlist_path)
+      @db = SQLite3::Database.new(wordlist_path, readonly: true)
+    end
+
+    def setup_queries
+      @languages = LanguageQuery.new(@db)
+      @words = WordQuery.new(@db)
+    end
+
+    def get_random_languages
+      @random_languages = @random.indices(@number_of_words, @languages.count)
+      @random_languages.map! { |index| @languages[index] }
+    end
+
+    def get_random_die_rolls
+      @random_die_rolls = @random.die_rolls(@number_of_words)
+    end
+
+    def select_words_from_wordlist
+      @selected_words = []
+      @random_languages.each_with_index do |language, index|
+        die_rolls = @random_die_rolls[index]
+        selection = @words.where(language: language, die_rolls: die_rolls)
+        @selected_words << selection.split.sample
+      end
+    end
+  end
+end

data/lib/passphrase/diceware_random.rb

@@ -0,0 +1,117 @@
+require "securerandom"
+require "open-uri"
+
+module Passphrase
+  # The DicewareRandom class supplies random numbers in two different formats
+  # through two instance methods {#indices} and {#die_rolls} for use by the
+  # {DicewareMethod} class. Depending on the value of the flag used to
+  # instantiate the DicewareRandom class, the unformatted raw random numbers
+  # are generated either by the standard SecureRandom class or retrieved from
+  # the RANDOM.ORG web site.
+  class DicewareRandom
+    class << self
+      # @return [Integer] the number of times the RANDOM.ORG site is accessed
+      #   by all instances of the DicewareRandom class
+      attr_accessor :random_org_requests
+    end
+
+    @random_org_requests = 0
+
+    # @param use_random_org [Boolean] a flag that triggers the use of
+    #   RANDOM.ORG for generating random numbers
+    def initialize(use_random_org=nil)
+      @random_org_uri = "https://www.random.org"
+      use_random_org ? setup_remote_generator : setup_local_generator
+    end
+
+    # Returns an array of random numbers that can index into the array of
+    # available languages. The number of elements in the array equals the
+    # number of words specified for the passphrase.
+    # @param number_of_words [Integer] the desired number of words in the
+    #   passphrase
+    # @param number_of_languages [Integer] the number of available languages
+    # @return [Array<Integer>] an array of random number indices
+    def indices(number_of_words, number_of_languages)
+      generate_random_numbers(number_of_words, number_of_languages - 1)
+    end
+
+    # Returns an array of strings where each string comprises five numeric
+    # characters, each one representing one roll of a die. The number of
+    # elements in the array equals the number of words specified for the
+    # passphrase.
+    # @param number_of_words [Integer] the desired number of words in the
+    #   passphrase
+    # @return [Array<String>] an array of strings each one of which represents
+    #   five rolls of a die
+    def die_rolls(number_of_words)
+      # The Diceware method specifies five rolls of the die for each word.
+      die_rolls_per_word = 5
+      total_die_rolls = number_of_words * die_rolls_per_word
+      die_roll_sequence = generate_random_numbers(total_die_rolls, 6, 1)
+      group_die_rolls(die_roll_sequence, number_of_words, die_rolls_per_word)
+    end
+
+    private
+    
+    def group_die_rolls(seq, number_of_words, die_rolls_per_word)
+      die_rolls = []
+      number_of_words.times do
+        rolls_per_word = seq.shift(die_rolls_per_word)
+        die_rolls << rolls_per_word.reduce("") { |roll, die| roll << die.to_s }
+      end
+      die_rolls
+    end
+    
+    def setup_remote_generator
+      self.class.class_eval do
+        def generate_random_numbers(count, maximum, minimum=0)
+          # Check quota before proceeding and thereafter every 1000 uses to
+          # comply with random.org guidelines.
+          check_random_org_quota if self.class.random_org_requests % 1000 == 0
+          params = []
+          params << "num=#{count}"
+          params << "min=#{minimum}"
+          params << "max=#{maximum}"
+          params << "col=1"
+          params << "base=10"
+          params << "format=plain"
+          params << "rnd=new"
+          query  = "/integers/?#{params.join('&')}"
+          array_of_random_numbers = []
+          open("#{@random_org_uri}#{query}") do |data|
+            data.each_line do |line|
+              array_of_random_numbers << line.to_i
+            end
+          end
+          self.class.random_org_requests += 1
+          array_of_random_numbers
+        end
+
+        def check_random_org_quota
+          query = "/quota/?format=plain"
+          open("#{@random_org_uri}#{query}") do |data|
+            quota = data.gets.chomp.to_i
+            over_quota_message = "RANDOM.ORG over quota, try again in 10 minutes"
+            raise "ERROR: #{over_quota_message}" if quota < 0
+          end
+        end
+
+        private :generate_random_numbers
+        private :check_random_org_quota
+      end
+    end
+    
+    def setup_local_generator
+      self.class.class_eval do
+        def generate_random_numbers(count, maximum, minimum=0)
+          max = maximum - minimum + 1
+          offset = minimum
+          # array_of_random_numbers
+          Array.new(count).map { |e| SecureRandom.random_number(max) + offset }
+        end
+
+        private :generate_random_numbers
+      end
+    end
+  end
+end