polarssl 0.0.3 → 0.0.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 1e2f2a763a31b7e4e0aa0fc3b70a1273e718f4fa
-  data.tar.gz: 855e12e10e367de1476934108cd2cf46697f3ada
+  metadata.gz: 3151e14eaa1f68b05092381044fb9300f9ccb927
+  data.tar.gz: a0fa9aa7e512d809ee9b1b6340eca20f3b5721a7
 SHA512:
-  metadata.gz: 82e8c5fe76d0d6f0a7aadc946132b4e2b12985ba0ddad8ba12e7d4e489c758cfa84f0527b51ab0414534fc2890767504728db29e2cf006475c57e6885e6e52e1
-  data.tar.gz: 3dd9cad82e91fce95518486e063d88f9285c2a46dd3c93f5f5b939c5439703b90e12212bfa2afe97086a85f96f11ba7178cd3c25b3f246ed4e40d732ffad840b
+  metadata.gz: 9a9376f1667ad47a5f5797aced7ec84bc597b52d21c90393d644c27fd0879e515556511a510b86ddce3a8ad46291134fb2db13deeea8fb87f72973c1a5d03795
+  data.tar.gz: 957c21527e3ccb2d45b8cf285201e38573a69d93c8bf1eb49b40da24192d577d3dc9cee2fb632944ee821f120689ce3af89a2321f285972770f5057c525e79d9

data/.gitignore

@@ -19,14 +19,6 @@ doc/
 
 .DS_Store
 
-ext/polarssl/mkmf.log
-
-ext/polarssl/polarssl.bundle
-
-ext/polarssl/polarssl.o
-
-ext/polarssl/Makefile
-
 *.o
 
 *.bundle

data/README.md

@@ -20,6 +20,8 @@ gem install polarssl
 
 ## Usage
 
+### Setting up a SSL connection
+
 This gem provides a pretty low level interface to the native PolarSSL C library.
 The core API aims to reflect the PolarSSL library as much as possible. See the
 [full API documentation](http://michiels.github.io/polarssl-ruby/doc/) for all classes and methods.
@@ -55,6 +57,33 @@ socket.close
 ssl.close
 ```
 
+### Encrypting data
+
+The `PolarSSL::Cipher` class lets you encrypt data with a wide range of
+encryption standards like AES, Blowfish and DES.
+
+This sample encrypts a given plaintext with AES128 in CTR mode:
+
+```ruby
+require 'polarssl'
+require 'base64'
+
+cipher = PolarSSL::Cipher.new("AES-128-CTR")
+
+my_iv = SecureRandom.random_bytes(16)
+
+cipher.reset(my_iv)
+cipher.setkey("my16bytekey23456", 128, PolarSSL::Cipher::OPERATION_ENCRYPT)
+cipher.update("some secret message I want to keep")
+encrypted_data = cipher.finish
+
+encoded_encrypted_data = Base64.encode64(encrypted_data)
+encoded_iv = Base64.encode64(my_iv)
+```
+
+See the documentation for the `Cipher` class in the [API documentation](http://michiels.github.io/polarssl-ruby/doc) 
+for all the available options.
+
 ## Contributing
 
 Install PolarSSL from source via https://polarssl.org/download or install it using your operating system. For example:

data/Rakefile

@@ -8,7 +8,7 @@ DLEXT = RbConfig::CONFIG['DLEXT']
 
 CLEAN.include("ext/**/*{.o,.log,.#{DLEXT}}")
 CLEAN.include("ext/**/Makefile")
-CLEAN.include("doc/**")
+CLEAN.include("doc")
 CLOBBER.include("lib/**/*.#{DLEXT}")
 
 Rake::TestTask.new do |t|
@@ -18,7 +18,7 @@ end
 
 task test: :compile
 
-RDOC_FILES = FileList["RDOC_MAIN.rdoc", "ext/polarssl/*.c", "lib/**/*.rb"]
+RDOC_FILES = FileList["RDOC_MAIN.rdoc", "lib/**/*.rb", "ext/polarssl/polarssl.c", "ext/polarssl/*.c"]
 
 RDoc::Task.new do |rd|
   rd.rdoc_dir = "doc"

data/ext/polarssl/cipher.c

@@ -0,0 +1,331 @@
+/*
+ *  Wrapping code for the PolarSSL::Cipher class.
+ *
+ *  Copyright (C) 2013  Michiel Sikkes
+ *
+ *  This file is part of polarssl-ruby (http://github.com/michiels/polarssl-ruby)
+ *
+ *  All rights reserved.
+ *
+ *  This program is free software: you can redistribute it and/or modify
+ *  it under the terms of the GNU Lesser General Public License as published by
+ *  the Free Software Foundation, either version 3 of the License, or
+ *  (at your option) any later version.
+ *
+ *  This program is distributed in the hope that it will be useful,
+ *  but WITHOUT ANY WARRANTY; without even the implied warranty of
+ *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ *  GNU Lesser General Public License for more details.
+ *
+ *  You should have received a copy of the GNU Lesser General Public License
+ *  along with this program.  If not, see <http://www.gnu.org/licenses/>.
+ */
+
+#include "polarssl.h"
+#include "polarssl/cipher.h"
+#include "ruby.h"
+
+VALUE rb_cipher_allocate();
+VALUE rb_cipher_initialize();
+VALUE rb_cipher_setkey();
+VALUE rb_cipher_update();
+VALUE rb_cipher_finish();
+VALUE rb_cipher_reset();
+void  rb_cipher_free();
+
+VALUE e_UnsupportedCipher;
+VALUE e_BadInputData;
+VALUE e_CipherError;
+
+typedef struct
+{
+  cipher_context_t *ctx;
+  unsigned char *output;
+  size_t olen;
+  size_t input_length;
+} rb_cipher_t;
+
+void Init_cipher(void)
+{
+    /** Document-class: PolarSSL::Cipher
+      *
+      * This class lets you encrypt and decrypt data.
+      *
+      * == Example
+      *
+      *   require 'polarssl'
+      *   require 'base64'
+      *
+      *   my_iv = SecureRandom.random_bytes(16)
+      *
+      *   cipher = PolarSSL::Cipher.new("AES-128-CTR")
+      *   cipher.reset(my_iv)
+      *   cipher.setkey("mykey", 128, PolarSSL::Cipher::OPERATION_ENCRYPT)
+      *   cipher.update("secret stuff I want encrypted")
+      *   encrypted_data = cipher.finish()
+      *
+      *   encoded_encrypted_data = Base64.encode64(encrypted_data)
+      *   encoded_iv = Base64.encode64(my_iv)
+      *
+      *   puts encoded_encrypted_data
+      *   puts encoded_iv
+      *
+      * == When you get an exception
+      *
+      * When using the Cipher class, you might get an exception. Some
+      * exeptions return a PolarSSL error code, like PolarSSL::Cipher::Error.
+      *
+      * These error codes are directly passed on from the PolarSSL library
+      * and you can look up what they mean in the PolarSSL API documentation
+      * at: https://polarssl.org/api/.
+      *
+      * == Supported Cipher types:
+      *
+      *   CAMELLIA-128-CBC
+      *   CAMELLIA-192-CBC
+      *   CAMELLIA-256-CBC
+      *
+      *   CAMELLIA-128-CFB128
+      *   CAMELLIA-192-CFB128
+      *   CAMELLIA-256-CFB128
+      *
+      *   CAMELLIA-128-CTR
+      *   CAMELLIA-192-CTR
+      *   CAMELLIA-256-CTR
+      *
+      *   AES-128-CBC
+      *   AES-192-CBC
+      *   AES-256-CBC
+      *
+      *   AES-128-CFB128
+      *   AES-192-CFB128
+      *   AES-256-CFB128
+      *
+      *   AES-128-CTR
+      *   AES-192-CTR
+      *   AES-256-CTR
+      *
+      *   DES-CBC
+      *   DES-EDE-CBC
+      *   DES-EDE3-CBC
+      *
+      *   BLOWFISH-CBC
+      *   BLOWFISH-CFB64
+      *   BLOWFISH-CTR
+      *
+      *   NULL
+      *
+      */
+    VALUE cCipher = rb_define_class_under( rb_mPolarSSL, "Cipher", rb_path2class("Object") );
+
+    /* 1: Use cipher for encryption */
+    rb_define_const( cCipher, "OPERATION_ENCRYPT", INT2NUM(POLARSSL_ENCRYPT) );
+
+    /* 0: Use cipher for decryption */
+    rb_define_const( cCipher, "OPERATION_DECRYPT", INT2NUM(POLARSSL_DECRYPT) );
+
+    /* -1: Don't use cipher for anything */
+    rb_define_const( cCipher, "OPERATION_NONE", INT2NUM(POLARSSL_OPERATION_NONE) );
+
+    /* Document-class: PolarSSL::Cipher::UnsupportedCipher
+     * Raised when you do not pass a supported cipher type to PolarSSL::Cipher.new()
+     */
+    e_UnsupportedCipher = rb_define_class_under( cCipher, "UnsupportedCipher", rb_eStandardError );
+    
+    /* Document-class: PolarSSL::Cipher::BadInputData
+     * Raised when the input data for the cipher was incorrect. If you get 
+     * this exception, please file a bug report.
+     */
+     e_BadInputData = rb_define_class_under( cCipher, "BadInputData", rb_eStandardError );
+
+    /* Document-class: PolarSSL::Cipher::Error
+     * Raised when the PolarSSL library throws a certain Cipher error code
+     */
+    e_CipherError = rb_define_class_under( cCipher, "Error", rb_eStandardError) ;
+
+    rb_define_alloc_func( cCipher, rb_cipher_allocate );
+    rb_define_method( cCipher, "initialize", rb_cipher_initialize, 1 );
+    rb_define_method( cCipher, "setkey", rb_cipher_setkey, 3 );
+    rb_define_method( cCipher, "update", rb_cipher_update, 1 );
+    rb_define_method( cCipher, "finish", rb_cipher_finish, 0 );
+    rb_define_method( cCipher, "reset", rb_cipher_reset, 1 );
+}
+
+VALUE rb_cipher_allocate( VALUE klass )
+{
+    rb_cipher_t *rb_cipher;
+
+    rb_cipher = ALLOC( rb_cipher_t );
+    memset( rb_cipher, 0, sizeof( rb_cipher_t ) );
+
+    rb_cipher->olen = 0;
+    rb_cipher->input_length = 0;
+
+    rb_cipher->ctx = ALLOC( cipher_context_t );
+    memset( rb_cipher->ctx, 0, sizeof( cipher_context_t ) );
+
+    return Data_Wrap_Struct( klass, 0, rb_cipher_free, rb_cipher );
+}
+
+/*
+ *  call-seq: new(cipher_type)
+ *
+ *  Initializes a new Cipher object to encrypt data with. For supported cipher types,
+ *  see: https://github.com/michiels/polarssl-ruby/wiki/Using-PolarSSL::Cipher
+ *
+ */
+VALUE rb_cipher_initialize( VALUE self, VALUE cipher_type )
+{
+    rb_cipher_t *rb_cipher;
+    char *cipher_type_str;
+    const cipher_info_t *cipher_info;
+    int ret;
+    
+    Check_Type( cipher_type, T_STRING );
+
+    cipher_type_str = StringValueCStr( cipher_type );
+
+    Data_Get_Struct( self, rb_cipher_t, rb_cipher );
+
+    cipher_info = cipher_info_from_string( cipher_type_str );
+
+    if (cipher_info == NULL)
+    {
+        rb_raise(e_UnsupportedCipher, "%s is not a supported cipher", cipher_type_str );
+    }
+    else 
+    {
+        ret = cipher_init_ctx( rb_cipher->ctx, cipher_info );
+        if ( ret < 0 )
+            rb_raise( e_CipherError, "PolarSSL error: -0x%x", -ret );
+    }
+
+    return self;
+}
+
+/*
+ *  call-seq: reset(initialization_vector)
+ *
+ *  Sets or resets the initialization vector for the cipher. An initialization
+ *  vector is used to "randomize" the output ciphertext so attackers cannot
+ *  guess your data based on a partially decrypted data.
+ *
+ *  This method needs to be called before you run the first #update.
+ *
+ *  One option to generate a random initialization vector is by using
+ *  SecureRandom.random_bytes. Store this initialization vector with the
+ *  ciphertext and you'll easily able to decrypt the ciphertext.
+ * 
+ */
+VALUE rb_cipher_reset( VALUE self, VALUE initialization_vector )
+{
+    rb_cipher_t *rb_cipher;
+    unsigned char *iv;
+    int ret;
+    
+    Check_Type( initialization_vector, T_STRING );
+    
+    iv = (unsigned char *) StringValueCStr( initialization_vector );
+    
+    Data_Get_Struct( self, rb_cipher_t, rb_cipher );
+    
+    ret = cipher_reset( rb_cipher->ctx, iv );
+    
+    if ( ret < 0 )
+        rb_raise( e_BadInputData, "Either the cipher type, key or initialization vector was not set." );
+    
+    return Qtrue;
+}
+
+/*
+ *  call-seq: setkey(key, key_length, operation)
+ *
+ *  Sets the key to be used for encrypting/decrypting this cipher. The key, key_length and operation
+ *  depend on which cipher you are using. For example, when using AES-128-CTR you would use something like:
+ *
+ *    cipher = PolarSSL::Cipher.new('AES-128-CTR')
+ *    cipher.setkey('mykey', 128, PolarSSL::Cipher::OPERATION_ENCRYPT)
+ *
+ *  for both encryping and decrypting your cipher.
+ *
+ */
+VALUE rb_cipher_setkey( VALUE self, VALUE key, VALUE key_length, VALUE operation )
+{
+    rb_cipher_t *rb_cipher;
+    int ret;
+    
+    Check_Type( key, T_STRING );
+    Check_Type( key_length, T_FIXNUM );
+    Check_Type( operation, T_FIXNUM );
+
+    Data_Get_Struct( self, rb_cipher_t, rb_cipher );
+
+    ret = cipher_setkey( rb_cipher->ctx, (const unsigned char *) StringValueCStr( key ), FIX2INT( key_length ), NUM2INT( operation ) );
+
+    if ( ret < 0 )
+        rb_raise( e_CipherError, "PolarSSL error: -0x%x", -ret );
+
+    return Qtrue;
+}
+
+/*
+ *  call-seq: update(input)
+ *
+ *  Adds input to your cipher.
+ *
+ */
+VALUE rb_cipher_update( VALUE self, VALUE rb_input )
+{
+  rb_cipher_t *rb_cipher;
+  char *input;
+  int ret;
+  
+  Check_Type( rb_input, T_STRING );
+
+  Data_Get_Struct( self, rb_cipher_t, rb_cipher );
+
+  StringValue( rb_input );
+  input = StringValuePtr( rb_input );
+
+  rb_cipher->input_length += RSTRING_LEN( rb_input );
+
+  /* Increases the output buffer so it results into the total input length so far. */
+  REALLOC_N(rb_cipher->output, unsigned char, rb_cipher->input_length);
+
+  ret = cipher_update( rb_cipher->ctx, (const unsigned char *) input, RSTRING_LEN( rb_input ), rb_cipher->output, &rb_cipher->olen );
+
+  if (ret < 0)
+    rb_raise( e_CipherError, "PolarSSL error: -0x%x", -ret );
+
+  return Qtrue;
+}
+
+/*
+ *  call-seq: finish()
+ *
+ *  Finishes encrypting the data added by one or multiple update() calls and returns the encrypted data.
+ *
+ */
+VALUE rb_cipher_finish( VALUE self )
+{
+  rb_cipher_t *rb_cipher;
+  int ret;
+
+  Data_Get_Struct( self, rb_cipher_t, rb_cipher );
+
+  ret = cipher_finish( rb_cipher->ctx, rb_cipher->output, &rb_cipher->olen );
+
+  if (ret < 0)
+    rb_raise( e_CipherError, "PolarSSL error: -0x%x", -ret );
+
+  return rb_str_new( (const char *) rb_cipher->output, rb_cipher->input_length );
+}
+
+void rb_cipher_free( rb_cipher_t *rb_cipher )
+{
+
+  if ( rb_cipher->ctx )
+    cipher_free_ctx(rb_cipher->ctx );
+
+  xfree( rb_cipher );
+}

data/ext/polarssl/cipher.h

@@ -0,0 +1 @@
+void Init_cipher();

data/ext/polarssl/polarssl.c

@@ -21,19 +21,21 @@
  *  along with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
 
-
 #include "ruby.h"
 #include "entropy.h"
 #include "ctr_drbg.h"
 #include "ssl.h"
+#include "cipher.h"
 
 VALUE rb_mPolarSSL;
 
 void Init_polarssl()
 {
+  /* The PolarSSL module */
   rb_mPolarSSL = rb_define_module( "PolarSSL" );
 
   Init_entropy( );
   Init_ctr_drbg( );
   Init_ssl( );
+  Init_cipher( );
 }

data/ext/polarssl/ssl.c

@@ -21,7 +21,6 @@
  *  along with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
 
-
 #include "polarssl.h"
 #include "polarssl/ssl.h"
 #include "polarssl/ctr_drbg.h"

data/lib/polarssl/version.rb

@@ -1,5 +1,5 @@
 module PolarSSL
 
-  VERSION = '0.0.3'
+  VERSION = '0.0.5'
 
 end

data/polarssl.gemspec

@@ -6,7 +6,7 @@ require 'polarssl/version'
 Gem::Specification.new do |s|
   s.name = 'polarssl'
   s.version = PolarSSL::VERSION
-  s.date = '2013-08-20'
+  s.date = '2013-09-17'
   s.summary = 'Use the PolarSSL cryptographic and SSL library in Ruby.'
   s.description = 'A gem that lets you use the PolarSSL cryptography library with Ruby.'
   s.authors = ['Michiel Sikkes']

data/test/cipher_encryption_test.rb

@@ -0,0 +1,74 @@
+require 'test_helper'
+require 'base64'
+require 'securerandom'
+
+class CipherTest < MiniTest::Unit::TestCase
+
+  def test_aes_128_ctr_encrypt
+    # These are hex-formatted strings that come from NIST Special Publication 800-38A 2001 Edition:
+    # Recommendation for Block Cipher Modes of Operation, Methods and Techniques by Morris Dworkin.
+    key = hex_to_bin("2b7e151628aed2a6abf7158809cf4f3c")
+    iv = hex_to_bin("f0f1f2f3f4f5f6f7f8f9fafbfcfdfeff")
+    input = hex_to_bin("6bc1bee22e409f96e93d7e117393172aae2d8a571e03ac9c9eb76fac45af8e51")
+    should_encrypt_as = hex_to_bin("874d6191b620e3261bef6864990db6ce9806f66b7970fdff8617187bb9fffdff")
+    
+    cipher = PolarSSL::Cipher.new("AES-128-CTR")
+    cipher.setkey(key, 128, PolarSSL::Cipher::OPERATION_ENCRYPT)
+    cipher.reset(iv)
+    cipher.update(input)
+    encrypted = cipher.finish
+
+    assert_equal should_encrypt_as, encrypted    
+  end
+  
+  def test_aes_128_ctr_decrypt
+    key = hex_to_bin("2b7e151628aed2a6abf7158809cf4f3c")
+    iv = hex_to_bin("f0f1f2f3f4f5f6f7f8f9fafbfcfdfeff")
+    input = hex_to_bin("874d6191b620e3261bef6864990db6ce")
+    should_decrypt_as = hex_to_bin("6bc1bee22e409f96e93d7e117393172a")
+    
+    cipher = PolarSSL::Cipher.new("AES-128-CTR")
+    cipher.setkey(key, 128, PolarSSL::Cipher::OPERATION_ENCRYPT)
+    cipher.reset(iv)
+    cipher.update(input)
+    decrypted = cipher.finish
+    
+    assert_equal should_decrypt_as, decrypted
+  end
+
+  def test_unsupported_cipher
+
+    assert_raises PolarSSL::Cipher::UnsupportedCipher do
+      PolarSSL::Cipher.new("meh")
+    end
+
+  end
+  
+  def test_initialization_vector_not_a_string
+    cipher = PolarSSL::Cipher.new("AES-128-CTR")
+    
+    assert_raises TypeError do
+      cipher.reset(nil)
+    end
+  end
+
+  def test_unsupported_key
+
+    assert_raises PolarSSL::Cipher::Error do
+      cipher = PolarSSL::Cipher.new("AES-128-CTR")
+      cipher.setkey("1234567890123456", 127, PolarSSL::Cipher::OPERATION_ENCRYPT)
+    end
+
+  end
+  
+  private
+  
+  def hex_to_bin(hex)
+    hex.scan(/../).map { |x| x.hex.chr }.join
+  end
+  
+  def bin_to_hex(data)
+    data.each_byte.map { |b| b.to_s(16).join }
+  end
+
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: polarssl
 version: !ruby/object:Gem::Version
-  version: 0.0.3
+  version: 0.0.5
 platform: ruby
 authors:
 - Michiel Sikkes
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-08-20 00:00:00.000000000 Z
+date: 2013-09-17 00:00:00.000000000 Z
 dependencies: []
 description: A gem that lets you use the PolarSSL cryptography library with Ruby.
 email: michiel.sikkes@gmail.com
@@ -27,6 +27,8 @@ files:
 - RDOC_MAIN.rdoc
 - README.md
 - Rakefile
+- ext/polarssl/cipher.c
+- ext/polarssl/cipher.h
 - ext/polarssl/ctr_drbg.c
 - ext/polarssl/ctr_drbg.h
 - ext/polarssl/entropy.c
@@ -41,6 +43,7 @@ files:
 - lib/polarssl/version.rb
 - polarssl-ruby.sublime-project
 - polarssl.gemspec
+- test/cipher_encryption_test.rb
 - test/ctr_drbg_test.rb
 - test/entropy_test.rb
 - test/ssl_connection_test.rb
@@ -72,6 +75,7 @@ signing_key:
 specification_version: 4
 summary: Use the PolarSSL cryptographic and SSL library in Ruby.
 test_files:
+- test/cipher_encryption_test.rb
 - test/ctr_drbg_test.rb
 - test/entropy_test.rb
 - test/ssl_connection_test.rb