carapace 0.1.0

data/CHANGELOG.md

@@ -0,0 +1,13 @@
+# Carapace Changelog
+
+## 0.1.0: Wednesday 30th May 2012
+
+Initial gem version
+
+Written and tested against Ruby 1.8.6 and Rails 2.0.2
+
+## Origin
+
+The original Carapace code was written on 10th August 2007 for Ruby 1.8.6 and Rails 2.0.2.
+
+

data/LICENSE

@@ -0,0 +1,24 @@
+Copyright (c) 2007, 2012 John Lane
+
+MIT License
+
+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.
+
+http://www.opensource.org/licenses/mit-license.php

data/LICENSE_JSBN

@@ -0,0 +1,40 @@
+Licensing
+---------
+
+This software is covered under the following copyright:
+
+/*
+ * Copyright (c) 2003-2005  Tom Wu
+ * All Rights Reserved.
+ *
+ * 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" AND WITHOUT WARRANTY OF ANY KIND, 
+ * EXPRESS, IMPLIED OR OTHERWISE, INCLUDING WITHOUT LIMITATION, ANY 
+ * WARRANTY OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.  
+ *
+ * IN NO EVENT SHALL TOM WU BE LIABLE FOR ANY SPECIAL, INCIDENTAL,
+ * INDIRECT OR CONSEQUENTIAL DAMAGES OF ANY KIND, OR ANY DAMAGES WHATSOEVER
+ * RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER OR NOT ADVISED OF
+ * THE POSSIBILITY OF DAMAGE, AND ON ANY THEORY OF LIABILITY, ARISING OUT
+ * OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+ *
+ * In addition, the following condition applies:
+ *
+ * All redistributions must retain an intact copy of this copyright notice
+ * and disclaimer.
+ */
+
+Address all questions regarding this license to:
+
+  Tom Wu
+  tjw@cs.Stanford.EDU

data/README.md

@@ -0,0 +1,96 @@
+# Carapace
+
+Carapace enables encrypted transfer of HTTP form field values from
+the view (client) to the controller (server).
+
+The data is encrypted by the browser before being posted to the server. The
+server decrypts the data ready for processing.
+
+Example uses are transfer of user passwords or credit card numbers.
+
+## Installation
+
+Install it:
+
+    $ gem install carapace
+
+Configure your rails 2.x application:
+
+    $ script/generate carapace
+
+## Usage
+
+Client-side, Carapace uses Javascript to perform encryption. Include this like so:
+
+    <%= javascript_include_tag 'carapace.js' %>
+    <%= carapace_javascript %>
+
+Use the `carapace_encrypt` Javascript function on any form fields that
+require encryption. For example:
+
+    function onSubmit()
+    {
+        carapace_encrypt(document.getElementById("user_password"));
+    }
+
+Then, configure the form's "submit" button to call it: 
+
+    <%= submit_tag "Add User", :class => "submit", :onclick => "onSubmit()" %>
+
+On the server, mix Carapace into a Rails controller (ApplicationController) class:
+
+    require 'carapace'
+    include Carapace
+    
+Then use Carapace from within action methods:
+
+    def index
+      carapace_session    
+      if request.post?
+        @message=params[:message]
+        carapace_decrypt! @message
+      end 
+    end 
+
+**Warning:** if the controller rejects a post operation and re-displays itself
+the data is not encrypted when sent to the browser. To maintain security,
+such fields should be cleared before rendering the view.
+
+## Testing
+
+Test the gem with `rake test`. There is also a self-contained rails application
+in `test\rails_app` for further testing and education. See `test\rails_app\README.md`
+for more information.
+
+## History
+
+Carapace was originally written as part of a larger application in 2007 that needed
+to provide a degree of security for sensitive data in situations where SSL could
+not be used. 
+
+The Carapace gem was created in 2012 to make it straightforward to re-use the
+original code in new applications. This was done primarily as a learning exercise.
+
+For revision history see CHANGELOG.md
+
+## Acknowledgement
+
+Carapace makes use of the [JSBN Library by Tom Wu](http://www-cs-students.stanford.edu/~tjw/jsbn/)
+under the terms of its license (see file LICENCE\_JSBN).
+
+## About the Name
+
+A _Carapace_ is the protective shell that covers and protects animals
+such as crabs and turtles.
+
+Definitions:
+[Oxford](http://oxforddictionaries.com/definition/carapace?q=carapace)
+[Cambridge](http://dictionary.cambridge.org/dictionary/british/carapace)
+
+In a similar vein, this gem allows a protective shell to surround data sent from
+a browser to a web server.
+
+## License
+
+Carapace is released under the MIT License. See LICENSE for details.
+

data/Rakefile

@@ -0,0 +1,8 @@
+require 'rake/testtask'
+
+Rake::TestTask.new do |t|
+  t.libs << 'test'
+end
+
+desc "Run tests"
+task :default => :test

data/lib/carapace.rb

@@ -0,0 +1,124 @@
+module Carapace
+  
+  require 'openssl'
+  include OpenSSL
+  include PKey
+  include Cipher
+
+  @carapace_javascript_written = false
+
+#  Until I can get the below to work it will need to be done in the contoller
+#  helper_method :carapace_javascript
+
+
+  private
+  
+  HEX = { 'a' => 10, 'b' => 11, 'c' => 12, 'd' => 13, 'e' => 14, 'f' => 15 } #:nodoc:
+
+  # Pass as parameter to carapace_decrypt to ensure decryption occurs or force error
+  CARAPACE_FORCE_DECRYPT = true                                              
+  
+  # Start a Carapace session.
+  #
+  # A Carapace session allows a Rails action to display and process 
+  # an HTML form that returns encrypted fields. The action must start a session 
+  # for both the initial display and the post-processing of the request.
+  # 
+  # Encryption is performed using a 1024 bit RSA key (or other key 
+  # length as specified by the optional parameter)
+  #
+  def carapace_session(key_length=1024) #:doc:
+    unless session[:carapace_private_key]
+      key = RSA.new(key_length)
+      session[:carapace_private_key]     = key.to_s
+      session[:carapace_public_modulus]  = key.public_key.n.to_s(base=16)
+      session[:carapace_public_exponent] = key.public_key.e.to_s(base=16)
+    end
+  end
+
+  # Decrypt a string. The return value is the decrypted string.
+  # If the string was not encrypted by the browser it is returned as-is
+  # unless the force_decrypt parameter is given as CARAPACE_FORCE_DECRYPT
+  # in which case nil is returned
+  #
+  # CARAPACE_FORCE_DECRYPT can be used to protect against accepting plaintext 
+  # transmissions when the user's browser has Javascript disabled.
+  #
+  def carapace_decrypt(string, force_decrypt=false) #:doc:
+    if carapace_enabled? then         # only decrypt if browser was enabled
+      byte = 0                        # the converted byte will go here
+      s = "".rjust(string.length/2)   # string to receive converted bytes
+      0.upto(string.length-1) do |i|  # iterate through string one chr at a time
+        ch = string[i].chr            #   current character
+        nibble = HEX[ch] || ch.to_i   #   converted to its binary value
+        if i%2 == 0 then              
+          byte = nibble << 4          #   most significant nibble is bits 5-8
+        else
+          byte += nibble              #   lease significant nibble is bits 1-4
+          s[i/2] = byte               #   store the converted byte
+        end
+      end
+      RSA.new(session[:carapace_private_key],nil).private_decrypt(s) # perform the decryption
+    else
+      force_decrypt ? nil : string    # input is unencrypted - return input 
+    end                               # return error if decryption was forced 
+
+  end
+  
+  # Decrypt a string. The return value is the decrypted string
+  # The string is decrypted in-situ, meaning its value is modified
+  # (warning, this does not call any customer accessor (e.g. "password=")
+  # so any custom code (such as password hashing) will not execute.)
+  #
+  def carapace_decrypt!(string, force_decrypt=false) #:doc:
+    decrypted_string = carapace_decrypt(string, force_decrypt)
+    string.replace decrypted_string unless !decrypted_string
+  end
+
+    private
+  
+  # Helper method for use in the view rhtml to insert Carapace Javascript
+  # The javascript is added to a page once, no matter how often this is called.
+  #
+  def carapace_javascript #:doc:
+    unless @carapace_javascript_written
+      session[:carapace_nonce] = Time.now.to_i.to_s.reverse.crypt(rand.to_s.reverse[0,2])
+      @carapace_javascript_written = true
+      return "<script type='text/javascript'>
+        carapace_modulus = \"#{session[:carapace_public_modulus]}\" ;
+        carapace_exponent = \"#{session[:carapace_public_exponent]}\" ;
+        document.cookie = \"carapace_nonce=#{session[:carapace_nonce]}; path=/\";
+        //alert(\"Session:#{session[:carapace_nonce]}\\nCookie:\"+document.cookie)
+        rsa = new RSAKey();
+        rsa.setPublic(carapace_modulus, carapace_exponent);
+
+        function carapace_encrypt(field)
+        {
+          field.value = rsa.encrypt(field.value);
+        }
+        </script>"
+    end 
+  end
+  
+  # Returns TRUE if Carapace was enabled on the view. This does not mean that
+  # data was encrypted, just that Carapace Javascript was executed by the
+  # user's browser, making the Carapace encryption services available. This
+  # will be TRUE if everything is set up correctly AND the user's browser has
+  # Javascript enabled
+  #
+  # This can be used to protect against accepting plaintext 
+  # transmissions when the user's browser has Javascript disabled.
+  # 
+  def carapace_enabled? #:doc:
+        cookies["carapace_nonce"]==session[:carapace_nonce]
+  end
+
+  # This is called when Carapace is included in a controller.
+  # It automatically sets upn the Carapace Javascript helper.
+  def self.included(c)
+	  #c.RAILS_DEFAULT_LOGGER.debug "Carapace has been included by #{c.class}"
+    if (c.class == Class)
+      c.helper_method :carapace_javascript
+    end
+  end
+end

data/rails_generators/USAGE

@@ -0,0 +1,7 @@
+Usage:
+
+script/generate carapace
+
+This installs the Carapace javascript into public/javascripts.
+
+For further information see the README 

data/rails_generators/carapace_generator.rb

@@ -0,0 +1,7 @@
+class CarapaceGenerator < Rails::Generator::Base
+  def manifest
+    record do |m|
+      m.file "carapace.js", "public/javascripts/carapace.js"
+    end
+  end
+end