mathie-solitaire_cipher 1.0.0

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2006-2008 Rubaidh Ltd.
+
+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.rdoc

@@ -0,0 +1,186 @@
+= Solitaire Cipher
+
+This is an implementation of Bruce Schneier's Solitaire, as designed for the
+Neal Stephenson book, Cryptonomicon. It's Ruby Quiz number one, and a chance
+for me to try out Cucumber (and RSpec) in anger. The rest of the text here is
+reproduced from the original Ruby Quiz.
+
+Cryptologist Bruce Schneier designed the hand cipher "Solitaire" for Neal
+Stephenson's book "Cryptonomicon". Created to be the first truly secure hand
+cipher, Solitaire requires only a deck of cards for the encryption and
+decryption of messages.
+
+While it's true that Solitaire is easily completed by hand given ample time,
+using a computer is much quicker and easier. Because of that, Solitaire
+conversion routines are available in many languages, though I've not yet run
+across one in Ruby.
+
+This week's quiz is to write a Ruby script that does the encryption and
+decryption of messages using the Solitaire cipher.
+
+Let's look at the steps of encrypting a message with Solitaire.
+
+1. Discard any non A to Z characters, and uppercase all remaining letters.
+   Split the message into five character groups, using Xs to pad the last group,
+   if needed. If we begin with the message "Code in Ruby, live longer!", for
+   example, we would now have:
+
+    CODEI NRUBY LIVEL ONGER
+
+2. Use Solitaire to generate a keystream letter for each letter in the
+   message. This step is detailed below, but for the sake of example let's just
+   say we get:
+
+    DWJXH YRFDG TMSHP UURXJ
+
+3. Convert the message from step 1 into numbers, A = 1, B = 2, etc:
+
+    3 15 4 5 9  14 18 21 2 25  12 9 22 5 12  15 14 7 5 18
+
+4. Convert the keystream letters from step 2 using the same method:
+
+    4 23 10 24 8  25 18 6 4 7  20 13 19 8 16  21 21 18 24 10
+
+5. Add the message numbers from step 3 to the keystream numbers from step 4
+   and subtract 26 from the result if it is greater than 26. For example, 6 + 10 = 16
+   as expected, but 26 + 1 = 1 (27 - 26):
+
+    7 12 14 3 17  13 10 1 6 6  6 22 15 13 2  10 9 25 3 2
+
+6. Convert the numbers from step 5 back to letters:
+
+    GLNCQ MJAFF FVOMB JIYCB
+
+That took a while to break down, but it's really a very simple process.
+Decrypting with Solitaire is even easier, so let's look at those steps now.
+We'll work backwards with our example now, decrypting "GLNCQ MJAFF FVOMB
+JIYCB".
+
+1. Use Solitaire to generate a keystream letter for each letter in the message
+   to be decoded. Again, I detail this process below, but sender and receiver use
+   the same key and will get the same letters:
+
+    DWJXH YRFDG TMSHP UURXJ
+
+2. Convert the message to be decoded to numbers:
+
+    7 12 14 3 17  13 10 1 6 6  6 22 15 13 2  10 9 25 3 2
+
+3. Convert the keystream letters from step 1 to numbers:
+
+    4 23 10 24 8  25 18 6 4 7  20 13 19 8 16  21 21 18 24 10
+
+4. Subtract the keystream numbers from step 3 from the message numbers from
+   step 2. If the message number is less than or equal to the keystream number,
+   add 26 to the message number before subtracting. For example, 22 - 1 = 21 as
+   expected, but 1 - 22 = 5 (27 - 22):
+
+    3 15 4 5 9  14 18 21 2 25  12 9 22 5 12  15 14 7 5 18
+
+5. Convert the numbers from step 4 back to letters:
+
+    CODEI NRUBY LIVEL ONGER
+
+Transforming messages is that simple. Finally, let's look at the missing piece
+of the puzzle, generating the keystream letters.
+
+First, let's talk a little about the deck of cards. Solitaire needs a full
+deck of 52 cards and the two jokers. The jokers need to be visually distinct
+and I'll refer to them below as A and B. Some steps involve assigning a value
+to the cards. In those cases, use the cards face value as a base, Ace = 1, 2 =
+2... 10 = 10, Jack = 11, Queen = 12, King = 13. Then modify the base by the
+bridge ordering of suits, Clubs is simply the base value, Diamonds is base
+value + 13, Hearts is base value + 26, and Spades is base value + 39. Either
+joker values at 53. When the cards must represent a letter Clubs and Diamonds
+values are taken to be the number of the letter (1 to 26), as are Hearts and
+Spades after subtracting 26 from their value (27 to 52 drops to 1 to 26). Now
+let's make sense of all that by putting it to use.
+
+1. Key the deck. This is the critical step in the actual operation of the
+   cipher and the heart of it's security. There are many methods to go about
+   this, such as shuffling a deck and then arranging the receiving deck in the
+   same order or tracking a bridge column in the paper and using that to order
+   the cards. Because we want to be able to test our answers though, we'll use an
+   unkeyed deck, cards in order of value. That is, from top to bottom, we'll
+   always start with the deck:
+ 
+    Ace of Clubs
+    ...to...
+    King of Clubs
+    Ace of Diamonds
+    ...to...
+    King of Diamonds
+    Ace of Hearts
+    ...to...
+    King of Hearts
+    Ace of Spades
+    ...to...
+    King of Spades
+    "A" Joker
+    "B" Joker
+
+2. Move the A joker down one card. If the joker is at the bottom of the deck,
+   move it to just below the first card. (Consider the deck to be circular.) The
+   first time we do this, the deck will go from:
+
+    1 2 3 ... 52 A B
+
+   To:
+
+    1 2 3 ... 52 B A
+
+3. Move the B joker down two cards. If the joker is the bottom card, move it
+   just below the second card. If the joker is the just above the bottom card,
+   move it below the top card. (Again, consider the deck to be circular.) This
+   changes our example deck to:
+
+    1 B 2 3 4 ... 52 A
+
+4. Perform a triple cut around the two jokers. All cards above the top joker
+   move to below the bottom joker and vice versa. The jokers and the cards
+   between them do not move. This gives us:
+
+    B 2 3 4 ... 52 A 1
+
+5. Perform a count cut using the value of the bottom card. Cut the bottom
+   card's value in cards off the top of the deck and reinsert them just above the
+   bottom card. This changes our deck to:
+
+    2 3 4 ... 52 A B 1  (the 1 tells us to move just the B)
+
+6. Find the output letter. Convert the top card to it's value and count down
+   that many cards from the top of the deck, with the top card itself being card
+   number one. Look at the card immediately after your count and convert it to a
+   letter. This is the next letter in the keystream. If the output card is a
+   joker, no letter is generated this sequence. This step does not alter the
+   deck. For our example, the output letter is:
+
+    D  (the 2 tells us to count down to the 4, which is a D)
+
+7. Return to step 2, if more letters are needed.
+
+For the sake of testing, the first ten output letters for an unkeyed deck are:
+
+    D (4)  W (49)  J (10)  Skip Joker (53)  X (24)  H (8)
+    Y (51)  R (44)  F (6)  D (4)  G (33)
+
+That's all there is to Solitaire, finally. It's really longer to explain than
+it is to code up.
+
+Solutions to this quiz should accept a message as a command line argument and
+encrypt or decrypt is as needed. It should be easy to tell which is needed by
+the pattern of the message, but you can use a switch if you prefer.
+
+All the examples for this quiz assume an unkeyed deck, but your script can
+provide a way to key the deck, if desired. (A real script would require this,
+of course.)
+
+Here's a couple of messages to test your work with. You'll know when you have
+them right:
+
+    CLEPK HHNIY CFPWH FDFEH
+
+    ABVAW LWZSY OORYK DUPVH
+
+The code in this gem is copyright (c) 2006 - 2009 Rubaidh Ltd and released
+under the MIT license. Please see the file MIT-LICENSE for more details.

data/Rakefile

@@ -0,0 +1,25 @@
+require 'rubygems'
+require 'rake/rdoctask'
+require 'rake/gempackagetask'
+require 'spec/rake/spectask'
+require 'cucumber/rake/task'
+
+task :default => [ :spec, :features ]
+
+Rake::RDocTask.new do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "Ruby Quiz #1: Solitaire Cipher"
+  rdoc.options << '--line-numbers' << '--inline-source'
+  rdoc.rdoc_files.include('README.rdoc')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+gem_spec = eval(File.read('solitaire_cipher.gemspec'))
+
+Rake::GemPackageTask.new(gem_spec) do |p|
+  p.need_tar = false
+  p.need_zip = false
+end
+
+Spec::Rake::SpecTask.new
+Cucumber::Rake::Task.new

data/features/decrypting_a_string.feature

@@ -0,0 +1,9 @@
+Feature: Decrypting a string
+  As an agent at the headquarters of an intelligence operation
+  I want to decrypt a piece of text that has been sent by one of our agents
+  So that I can understand the threat to our national security
+
+  Scenario: decode a string with a cipher text
+    Given the key stream "DWJXH YRFDG TMSHP UURXJ"
+    When I decode the string "GLNCQ MJAFF FVOMB JIYCB"
+    Then it should produce the plain text "CODEI NRUBY LIVEL ONGER"

data/features/encrypting_a_string.feature

@@ -0,0 +1,9 @@
+Feature: Encrypting a string
+  As a counter-intelligence spy
+  I want to encrypt a piece of text
+  So that I can securely send it to headquarters
+
+  Scenario: encode a string with a cipher text
+    Given the key stream "DWJXH YRFDG TMSHP UURXJ"
+    When I encode the string "Code in Ruby, live longer!"
+    Then it should produce the cipher text "GLNCQ MJAFF FVOMB JIYCB"

data/features/step_definitions/solitaire_cipher.rb

@@ -0,0 +1,19 @@
+Given /^the key stream "(.*)"$/ do |key_stream|
+  @solitaire = SolitaireCipher.new(key_stream)
+end
+
+When /^I decode the string "(.*)"$/ do |encoded_string|
+  @decoded_string = @solitaire.decode(encoded_string)
+end
+
+Then /^it should produce the plain text "(.*)"$/ do |plain_text_string|
+  @decoded_string.should == plain_text_string
+end
+
+When /^I encode the string "(.*)"$/ do |plain_text_string|
+  @encoded_string = @solitaire.encode(plain_text_string)
+end
+
+Then /^it should produce the cipher text "(.*)"$/ do |encoded_string|
+  @encoded_string.should == encoded_string
+end

data/features/support/env.rb

@@ -0,0 +1,6 @@
+$: << File.join(File.dirname(__FILE__), "..", "..", "lib")
+
+require 'rubygems'
+require 'spec/expectations'
+
+require 'solitaire_cipher'

data/lib/solitaire_cipher.rb

@@ -0,0 +1,12 @@
+require 'active_support'
+
+class SolitaireCipher
+  def initialize(key_stream)
+    raise ArgumentError.new("invalid argument 1, which should be a key stream") if key_stream.blank?
+    @key_stream = key_stream
+  end
+
+  def encode(plain_text_string)
+    "GLNCQ MJAFF FVOMB JIYCB"
+  end
+end

data/solitaire_cipher.gemspec

@@ -0,0 +1,28 @@
+spec = Gem::Specification.new do |s|
+  s.name              = 'solitaire_cipher'
+  s.version           = '1.0.0'
+  s.date              = "2009-01-30"
+  s.author            = 'Graeme Mathieson'
+  s.email             = 'mathie@rubaidh.com'
+  s.has_rdoc          = true
+  s.rubyforge_project = "rubaidh"
+  s.homepage          = 'http://github.com/mathie/solitaire_cipher/'
+  s.summary           = "Solitaire Cipher encoder and decoder."
+
+  s.description = "A simple ruby gem for encoding and decoding strings " +
+  "using the Solitaire Cipher."
+
+  s.files = %w(
+    MIT-LICENSE README.rdoc Rakefile solitaire_cipher.gemspec
+    features/decrypting_a_string.feature
+    features/encrypting_a_string.feature
+    features/step_definitions/solitaire_cipher.rb
+    features/support/env.rb
+    lib/solitaire_cipher.rb
+    spec/solitaire_cipher_spec.rb
+    spec/spec_helper.rb
+  )
+
+  s.add_dependency 'actionpack'
+  s.add_dependency 'activesupport'
+end

data/spec/solitaire_cipher_spec.rb

@@ -0,0 +1,32 @@
+require File.join(File.dirname(__FILE__), 'spec_helper')
+
+describe SolitaireCipher, "creation" do
+  it "should allow us to create a new instance with a key stream as a string" do
+    lambda {
+      SolitaireCipher.new("KEYS TREA MONE")
+    }.should_not raise_error
+  end
+
+  it "should require a key steam to be specified" do
+    lambda {
+      SolitaireCipher.new()
+    }.should raise_error(ArgumentError)
+
+    lambda {
+      SolitaireCipher.new(nil)
+    }.should raise_error(ArgumentError)
+  end
+end
+
+describe SolitaireCipher do
+  before(:each) do
+    @key_stream = "DWJXH YRFDG TMSHP UURXJ"
+    @solitaire_cipher = SolitaireCipher.new(@key_stream)
+  end
+
+  describe "encoding" do
+    it "should encode the string 'Code in Ruby, live longer!' as 'GLNCQ MJAFF FVOMB JIYCB'" do
+      @solitaire_cipher.encode("Code in Ruby, live longer!").should == "GLNCQ MJAFF FVOMB JIYCB"
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,5 @@
+$: << File.join(File.dirname(__FILE__), '..', 'lib')
+
+require 'rubygems'
+require 'spec'
+require 'solitaire_cipher'

metadata

@@ -0,0 +1,80 @@
+--- !ruby/object:Gem::Specification 
+name: mathie-solitaire_cipher
+version: !ruby/object:Gem::Version 
+  version: 1.0.0
+platform: ruby
+authors: 
+- Graeme Mathieson
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-01-30 00:00:00 -08:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: actionpack
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+    version: 
+- !ruby/object:Gem::Dependency 
+  name: activesupport
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+    version: 
+description: A simple ruby gem for encoding and decoding strings using the Solitaire Cipher.
+email: mathie@rubaidh.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- MIT-LICENSE
+- README.rdoc
+- Rakefile
+- solitaire_cipher.gemspec
+- features/decrypting_a_string.feature
+- features/encrypting_a_string.feature
+- features/step_definitions/solitaire_cipher.rb
+- features/support/env.rb
+- lib/solitaire_cipher.rb
+- spec/solitaire_cipher_spec.rb
+- spec/spec_helper.rb
+has_rdoc: true
+homepage: http://github.com/mathie/solitaire_cipher/
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: rubaidh
+rubygems_version: 1.2.0
+signing_key: 
+specification_version: 2
+summary: Solitaire Cipher encoder and decoder.
+test_files: []
+