pkcs11 0.1.0-x86-mswin32 → 0.2.0-x86-mswin32

data/.yardopts

@@ -0,0 +1,2 @@
+--no-private lib/**/*.rb ext/*.c ext/*.doc
+

data/History.txt

@@ -1,3 +1,26 @@
+=== 0.2.0 / 2011-01-18
+
+* switch API documentation to YARD instead of RDOC
+* add Ruby classes for all PKCS#11 structures
+* add CopyObject
+* add Get/SetOperationState
+* use distinct Exception classes for different error codes
+* PKCS#11 function calls don't block other ruby threads any more (only Ruby 1.9, Rubinius)
+* don't wrap mechanisms any more (GetMechanismList returns plain Integers now)
+* choose structs as mechanism parameter based on the given mechanism
+* autogenerate many constants from C header files
+* finer graded control over library loading
+* several bug fixes
+* more unit tests
+* more documentation
+
+
 === 0.1.0 / 2010-05-03
 
 * first rubygem version
+* Most functions and operations of PKCS#11 v2.2 are implemented.
+* The library is based on the work of Ryosuke Kutsuna and GOTOU Yuuzou, but extended in the following ways:
+  - running on Unix and Windows OS
+  - downloadable as rubygem in source and win32 binary version
+  - new API, it's more ruby-like and well documented
+  - most functions are unit tested with help of softokn library

data/Manifest.txt

@@ -1,10 +1,13 @@
 .autotest
+.yardopts
 History.txt
 MIT-LICENSE
 Manifest.txt
 README.rdoc
 Rakefile
 ext/extconf.rb
+ext/generate_structs.rb
+ext/generate_thread_funcs.rb
 ext/include/cryptoki.h
 ext/include/ct-kip.h
 ext/include/otp-pkcs11.h
@@ -17,6 +20,7 @@ ext/pk11.h
 ext/pk11_const.c
 lib/pkcs11.rb
 lib/pkcs11/extensions.rb
+lib/pkcs11/helper.rb
 lib/pkcs11/library.rb
 lib/pkcs11/object.rb
 lib/pkcs11/session.rb
@@ -32,3 +36,5 @@ test/test_pkcs11_crypt.rb
 test/test_pkcs11_object.rb
 test/test_pkcs11_session.rb
 test/test_pkcs11_slot.rb
+test/test_pkcs11_structs.rb
+test/test_pkcs11_thread.rb

data/README.rdoc

@@ -1,7 +1,6 @@
 = PKCS #11/Ruby Interface
 
 * Homepage: http://github.com/larskanis/pkcs11
-* older SVN repository: http://coderepos.org/share/log/lang/ruby/pkcs11-ruby
 * API documentation: http://pkcs11.rubyforge.org/pkcs11/
 
 This module allows Ruby programs to interface with "RSA Security Inc.
@@ -20,12 +19,14 @@ This module works on the Unix like operating systems and win32.
 
   gem install pkcs11
 
+This installs the PKCS#11 extension either by compiling (Unix) or by using the precompiled gem for Win32.
 
 == Usage
 Cryptoki has a reputation to be complicated to implement and use.
-While this seems to be true for C it isn't for Ruby.
+While this seems to be true for C it shouldn't for Ruby.
 
-PKCS11.open requires suitable PKCS #11 implementation as UN*X *.so file or Windows-DLL.
+{PKCS11.open} opens a PKCS#11 Unix *.so file or Windows-DLL. It requires
+a suitable PKCS #11 implementation.
 
   require "rubygems"
   require "pkcs11"
@@ -33,19 +34,23 @@ PKCS11.open requires suitable PKCS #11 implementation as UN*X *.so file or Windo
 
   pkcs11 = PKCS11.open("/path/to/pkcs11.so")
   p pkcs11.info
-  slot = pkcs11.active_slots.first
-  session = slot.open
+  session = pkcs11.active_slots.first.open
   session.login(:USER, "1234")
-  ...
+  # ... crypto operations
   session.logout
   session.close
 
-See PKCS11::Library for API documentation. See unit tests in the <tt>test</tt>
-directory of the project or gem for further examples of the usage.
+This opens a {PKCS11::Session} to the first active slot of the device.
+A {PKCS11::Session} can be used for all cryptographic operations
+on the device.
 
 Detail information for the API specification is provided by RSA Security Inc.
 Please refer the URL: http://www.rsa.com/rsalabs/node.asp?id=2133.
 
+Many usage examples can be found in the unit tests of the <tt>test</tt>
+directory of the project or gem.
+
+
 
 == Cross compiling for mswin32
 
@@ -78,18 +83,18 @@ directory.
 
 == ToDo
 
-* unit testing (with mozilla softoken)
-* implement all functions/structs
-* sample code
+* encoding support for Ruby 1.9
+* support for proprietary extensions of different vendors
+* PKCS#11 v2.3
 
 == Development Status
 
   STATE   FUNCTION               NOTE
   ------  ---------------------  ----------------------------------------
-  N/A     C_Initialize           called in PKCS11#initialize("/path/to/pk11lib")
-  DONE    C_Finalize             called in GC
+  DONE    C_Initialize
+  DONE    C_Finalize
   DONE    C_GetInfo
-  N/A     C_GetFunctionList      internal use only
+  DONE    C_GetFunctionList
   DONE    C_GetSlotList
   DONE    C_GetSlotInfo
   DONE    C_GetTokenInfo
@@ -107,7 +112,7 @@ directory.
   DONE    C_Login
   DONE    C_Logout
   DONE    C_CreateObject
-  N/A     C_CopyObject           use C_GetAttributeValue and C_CreateObject
+  DONE    C_CopyObject
   DONE    C_DestroyObject
   DONE    C_GetObjectSize
   DONE    C_GetAttributeValue
@@ -154,3 +159,11 @@ directory.
   N/A     C_GetFunctionStatus    legacy function
   N/A     C_CancelFunction       legacy function
   DONE    C_WaitForSlotEvent
+
+== Authors
+* Ryosuke Kutsuna <ryosuke@deer-n-horse.jp>
+* GOTOU Yuuzou <gotoyuzo@notwork.org>
+* Lars Kanis <kanis@comcard.de>
+
+== Copying
+See MIT-LICENSE included in the package.

data/Rakefile

@@ -4,19 +4,40 @@
 require 'rubygems'
 require 'hoe'
 require 'rake/extensiontask'
+require 'rbconfig'
+
+CLEAN.include 'ext/pk11_struct_def.inc'
+CLEAN.include 'ext/pk11_struct_impl.inc'
+CLEAN.include 'ext/pk11_const_def.inc'
+CLEAN.include 'ext/pk11_thread_funcs.h'
+CLEAN.include 'ext/pk11_thread_funcs.c'
+CLEAN.include 'lib/pkcs11_ext.so'
+CLEAN.include 'tmp'
 
 hoe = Hoe.spec 'pkcs11' do
   developer('Ryosuke Kutsuna', 'ryosuke@deer-n-horse.jp')
   developer('GOTOU Yuuzou', 'gotoyuzo@notwork.org')
   developer('Lars Kanis', 'kanis@comcard.de')
+  extra_dev_deps << ['yard', '>= 0.6']
+  extra_dev_deps << ['rake-compiler', '>= 0.7']
+
   self.url = 'http://github.com/larskanis/pkcs11'
-  
+  self.summary = 'PKCS#11 binding for Ruby'
+  self.description = 'This module allows Ruby programs to interface with "RSA Security Inc. PKCS #11 Cryptographic Token Interface (Cryptoki)".'
+
   self.readme_file = 'README.rdoc'
   self.extra_rdoc_files << self.readme_file << 'ext/pk11.c'
   spec_extras[:extensions] = 'ext/extconf.rb'
+  spec_extras[:files] = File.read_utf("Manifest.txt").split(/\r?\n\r?/)
+  spec_extras[:files] << 'ext/pk11_struct_impl.inc'
+  spec_extras[:files] << 'ext/pk11_struct_def.inc'
+  spec_extras[:files] << 'ext/pk11_const_def.inc'
+  spec_extras[:files] << 'ext/pk11_thread_funcs.h'
+  spec_extras[:files] << 'ext/pk11_thread_funcs.c'
+  spec_extras[:has_rdoc] = 'yard'
 end
 
-ENV['RUBY_CC_VERSION'] = '1.8.6:1.9.1'
+ENV['RUBY_CC_VERSION'] ||= '1.8.6:1.9.2'
 
 Rake::ExtensionTask.new('pkcs11_ext', hoe.spec) do |ext|
   ext.ext_dir = 'ext'
@@ -24,6 +45,34 @@ Rake::ExtensionTask.new('pkcs11_ext', hoe.spec) do |ext|
   ext.cross_platform = ['i386-mswin32', 'i386-mingw32']     # forces the Windows platform instead of the default one
 end
 
+file 'ext/extconf.rb' => ['ext/pk11_struct_def.inc', 'ext/pk11_thread_funcs.c']
+file 'ext/pk11_struct_def.inc' => 'ext/generate_structs.rb' do
+  sh "#{Config::CONFIG['ruby_install_name']} ext/generate_structs.rb --def ext/pk11_struct_def.inc --impl ext/pk11_struct_impl.inc --const ext/pk11_const_def.inc --doc ext/pk11_struct.doc ext/include/pkcs11t.h"
+end
+file 'ext/pk11_struct_impl.inc' => 'ext/pk11_struct_def.inc'
+file 'ext/pk11.c' => 'ext/pk11_struct_def.inc'
+file 'ext/pk11_const.c' => 'ext/pk11_struct_def.inc'
+
+file 'ext/pk11_thread_funcs.h' => 'ext/generate_thread_funcs.rb' do
+  sh "#{Config::CONFIG['ruby_install_name']} ext/generate_thread_funcs.rb --impl ext/pk11_thread_funcs.c --decl ext/pk11_thread_funcs.h ext/include/pkcs11f.h"
+end
+file 'ext/pk11_thread_funcs.c' => 'ext/pk11_thread_funcs.h'
+file 'ext/pk11.h' => 'ext/pk11_thread_funcs.h'
+
+desc "Generate static HTML documentation with YARD"
+task :yardoc do
+  sh "yardoc"
+end
+
+desc "Publish YARD to wherever you want."
+task :publish_yard => [:yardoc] do
+  rdoc_locations = hoe.rdoc_locations
+  warn "no rdoc_location values" if rdoc_locations.empty?
+  rdoc_locations.each do |dest|
+    sh %{rsync -av --delete doc/ #{dest}}
+  end
+end
+
 # RDoc-upload task for github (currently on rubyforge)
 #
 # require 'grancher/task'

data/ext/extconf.rb

@@ -3,4 +3,5 @@ require "mkmf"
 basedir = File.dirname(__FILE__)
 $CPPFLAGS += " -I \"#{basedir}/include\""
 have_func("rb_str_set_len")
+have_func("rb_thread_blocking_region")
 create_makefile("pkcs11_ext");

data/ext/generate_structs.rb

@@ -0,0 +1,157 @@
+#!/usr/bin/env ruby
+# Quick and dirty parser for PKCS#11 structs and
+# generator for Ruby wrapper classes.
+
+require 'optparse'
+
+options = Struct.new(:verbose, :def, :impl, :const, :doc).new
+OptionParser.new do |opts|
+	opts.banner = "Usage: #{$0} [options] <header-file.h>*"
+
+	opts.on("-v", "--[no-]verbose", "Run verbosely", &options.method(:verbose=))
+	opts.on("--def FILE", "Write struct definitions to this file", &options.method(:def=))
+  opts.on("--impl FILE", "Write struct implementations to this file", &options.method(:impl=))
+  opts.on("--const FILE", "Write const implementations to this file", &options.method(:const=))
+  opts.on("--doc FILE", "Write documentation to this file", &options.method(:doc=))
+	opts.on_tail("-h", "--help", "Show this message") do
+		puts opts
+		exit
+	end
+end.parse!
+
+Attribute = Struct.new(:type, :name, :qual)
+IgnoreStructs = %w[CK_ATTRIBUTE CK_MECHANISM]
+OnlyAllocatorStructs = %w[CK_MECHANISM_INFO CK_C_INITIALIZE_ARGS CK_INFO CK_SLOT_INFO CK_TOKEN_INFO CK_SESSION_INFO]
+
+structs = {}
+File.open(options.def, "w") do |fd_def|
+File.open(options.impl, "w") do |fd_impl|
+File.open(options.doc, "w") do |fd_doc|
+ARGV.each do |file_h|
+	c_src = IO.read(file_h)
+	c_src.scan(/struct\s+([A-Z_0-9]+)\s*\{(.*?)\}/m) do |struct|
+		struct_name, struct_text = $1, $2
+		
+		attrs = {}
+		struct_text.scan(/^\s+([A-Z_0-9]+)\s+([\w_]+)\s*(\[\s*(\d+)\s*\])?/) do |elem|
+			attr = Attribute.new($1, $2, $4)
+			attrs[$1+" "+$2] = attr
+# 			puts attr.inspect
+		end
+    structs[struct_name] = attrs
+
+    next if IgnoreStructs.include?(struct_name)
+
+    if OnlyAllocatorStructs.include?(struct_name)
+      fd_impl.puts "PKCS11_IMPLEMENT_ALLOCATOR(#{struct_name});"
+    else
+      fd_impl.puts "PKCS11_IMPLEMENT_STRUCT_WITH_ALLOCATOR(#{struct_name});"
+    end
+    fd_def.puts "PKCS11_DEFINE_STRUCT(#{struct_name});"
+    fd_doc.puts"class PKCS11::#{struct_name} < PKCS11::CStruct"
+    fd_doc.puts"# Size of corresponding C struct in bytes\nSIZEOF_STRUCT=Integer"
+    fd_doc.puts"# @return [String] Binary copy of the C struct\ndef to_s; end"
+    fd_doc.puts"# @return [Array<String>] Attributes of this struct\ndef members; end"
+    
+		# try to find attributes belonging together
+		attrs.select{|key, attr| ['CK_BYTE_PTR', 'CK_VOID_PTR', 'CK_UTF8CHAR_PTR'].include?(attr.type) }.each do |key, attr|
+			if len_attr=attrs["CK_ULONG #{attr.name.gsub(/^p/, "ul")}Len"]
+				fd_impl.puts "PKCS11_IMPLEMENT_STRING_PTR_LEN_ACCESSOR(#{struct_name}, #{attr.name}, #{len_attr.name});"
+				fd_def.puts "PKCS11_DEFINE_MEMBER(#{struct_name}, #{attr.name});"
+        fd_doc.puts"# @return [String, nil] accessor for #{attr.name} and #{len_attr.name}\nattr_accessor :#{attr.name}"
+				attrs.delete_if{|k,v| v==len_attr}
+			elsif attr.name=='pData' && (len_attr = attrs["CK_ULONG length"] || attrs["CK_ULONG ulLen"])
+				fd_impl.puts "PKCS11_IMPLEMENT_STRING_PTR_LEN_ACCESSOR(#{struct_name}, #{attr.name}, #{len_attr.name});"
+				fd_def.puts "PKCS11_DEFINE_MEMBER(#{struct_name}, #{attr.name});"
+        fd_doc.puts"# @return [String, nil] accessor for #{attr.name} and #{len_attr.name}\nattr_accessor :#{attr.name}"
+				attrs.delete_if{|k,v| v==len_attr}
+			else
+				fd_impl.puts "PKCS11_IMPLEMENT_STRING_PTR_ACCESSOR(#{struct_name}, #{attr.name});"
+				fd_def.puts "PKCS11_DEFINE_MEMBER(#{struct_name}, #{attr.name});"
+        fd_doc.puts"# @return [String, nil] accessor for #{attr.name}\nattr_accessor :#{attr.name}"
+			end
+			attrs.delete_if{|k,v| v==attr}
+		end
+		
+		# standalone attributes
+		attrs.each do |key, attr|
+      if attr.qual
+        # Attributes with qualifier
+        case attr.type
+        when 'CK_BYTE', 'CK_UTF8CHAR', 'CK_CHAR'
+          fd_impl.puts "PKCS11_IMPLEMENT_STRING_ACCESSOR(#{struct_name}, #{attr.name});"
+          fd_def.puts "PKCS11_DEFINE_MEMBER(#{struct_name}, #{attr.name});"
+          fd_doc.puts"# @return [String] accessor for #{attr.name} (max #{attr.qual} bytes)\nattr_accessor :#{attr.name}"
+        else
+          fd_impl.puts "/* unimplemented attr #{attr.type} #{attr.name} #{attr.qual} */"
+          fd_def.puts "/* unimplemented attr #{attr.type} #{attr.name} #{attr.qual} */"
+        end
+      else
+        case attr.type
+        when 'CK_BYTE'
+          fd_impl.puts "PKCS11_IMPLEMENT_BYTE_ACCESSOR(#{struct_name}, #{attr.name});"
+          fd_def.puts "PKCS11_DEFINE_MEMBER(#{struct_name}, #{attr.name});"
+          fd_doc.puts"# @return [Integer] accessor for #{attr.name} (CK_BYTE)\nattr_accessor :#{attr.name}"
+        when 'CK_ULONG', 'CK_FLAGS', 'CK_SLOT_ID', 'CK_STATE', /CK_[A-Z_0-9]+_TYPE/
+          fd_impl.puts "PKCS11_IMPLEMENT_ULONG_ACCESSOR(#{struct_name}, #{attr.name});"
+          fd_def.puts "PKCS11_DEFINE_MEMBER(#{struct_name}, #{attr.name});"
+          fd_doc.puts"# @return [Integer] accessor for #{attr.name} (CK_ULONG)\nattr_accessor :#{attr.name}"
+        when 'CK_OBJECT_HANDLE'
+          fd_impl.puts "PKCS11_IMPLEMENT_HANDLE_ACCESSOR(#{struct_name}, #{attr.name});"
+          fd_def.puts "PKCS11_DEFINE_MEMBER(#{struct_name}, #{attr.name});"
+          fd_doc.puts"# @return [Integer, PKCS11::Object] Object handle (CK_ULONG)\nattr_accessor :#{attr.name}"
+        when 'CK_BBOOL'
+          fd_impl.puts "PKCS11_IMPLEMENT_BOOL_ACCESSOR(#{struct_name}, #{attr.name});"
+          fd_def.puts "PKCS11_DEFINE_MEMBER(#{struct_name}, #{attr.name});"
+          fd_doc.puts"# @return [Boolean]  Bool value\nattr_accessor :#{attr.name}"
+        when 'CK_ULONG_PTR'
+          fd_impl.puts "PKCS11_IMPLEMENT_ULONG_PTR_ACCESSOR(#{struct_name}, #{attr.name});"
+          fd_def.puts "PKCS11_DEFINE_MEMBER(#{struct_name}, #{attr.name});"
+          fd_doc.puts"# @return [Integer, nil] accessor for #{attr.name} (CK_ULONG_PTR)\nattr_accessor :#{attr.name}"
+        else
+          # Struct attributes
+          if structs[attr.type]
+            fd_impl.puts "PKCS11_IMPLEMENT_STRUCT_ACCESSOR(#{struct_name}, #{attr.type}, #{attr.name});"
+            fd_def.puts "PKCS11_DEFINE_MEMBER(#{struct_name}, #{attr.name});"
+            fd_doc.puts"# @return [PKCS11::#{attr.type}] inline struct\nattr_accessor :#{attr.name}"
+          elsif structs[attr.type.gsub(/_PTR$/,'')]
+            fd_impl.puts "PKCS11_IMPLEMENT_STRUCT_PTR_ACCESSOR(#{struct_name}, #{attr.type.gsub(/_PTR$/,'')}, #{attr.name});"
+            fd_def.puts "PKCS11_DEFINE_MEMBER(#{struct_name}, #{attr.name});"
+            fd_doc.puts"# @return [PKCS11::#{attr.type.gsub(/_PTR$/,'')}, nil] pointer to struct\nattr_accessor :#{attr.name}"
+          else
+            fd_impl.puts "/* unimplemented attr #{attr.type} #{attr.name} #{attr.qual} */"
+            fd_def.puts "/* unimplemented attr #{attr.type} #{attr.name} #{attr.qual} */"
+          end
+        end
+      end
+		end
+	
+		fd_impl.puts
+		fd_def.puts
+    fd_doc.puts"end"
+	end
+end
+end
+end
+end
+
+ConstTemplate = Struct.new :regexp, :def
+ConstGroups = [
+  ConstTemplate.new(/#define\s+(CKM_[A-Z_0-9]+)\s+(\w+)/, 'PKCS11_DEFINE_MECHANISM'),
+  ConstTemplate.new(/#define\s+(CKA_[A-Z_0-9]+)\s+(\w+)/, 'PKCS11_DEFINE_ATTRIBUTE'),
+  ConstTemplate.new(/#define\s+(CKO_[A-Z_0-9]+)\s+(\w+)/, 'PKCS11_DEFINE_OBJECT_CLASS'),
+  ConstTemplate.new(/#define\s+(CKR_[A-Z_0-9]+)\s+(\w+)/, 'PKCS11_DEFINE_RETURN_VALUE'),
+]
+
+File.open(options.const, "w") do |fd_const|
+ARGV.each do |file_h|
+  c_src = IO.read(file_h)
+  ConstGroups.each do |const_group|
+    c_src.scan(const_group.regexp) do
+      const_name, const_value = $1, $2
+      
+      fd_const.puts "#{const_group.def}(#{const_name}); /* #{const_value} */"
+    end
+  end
+end
+end

data/ext/generate_thread_funcs.rb

@@ -0,0 +1,72 @@
+#!/usr/bin/env ruby
+# This quick and dirty parser for PKCS#11 functions generates
+# wrapper functions for using rb_thread_blocking_region()
+# of Ruby 1.9.
+
+require 'optparse'
+
+options = Struct.new(:verbose, :impl, :decl).new
+OptionParser.new do |opts|
+	opts.banner = "Usage: #{$0} [options] <header-file.h>*"
+
+	opts.on("-v", "--[no-]verbose", "Run verbosely", &options.method(:verbose=))
+  opts.on("--decl FILE", "Write declarations to this file", &options.method(:decl=))
+  opts.on("--impl FILE", "Write implementations to this file", &options.method(:impl=))
+	opts.on_tail("-h", "--help", "Show this message") do
+		puts opts
+		exit
+	end
+end.parse!
+
+Attribute = Struct.new(:type, :name)
+
+File.open(options.decl, "w") do |fd_decl|
+File.open(options.impl, "w") do |fd_impl|
+fd_decl.puts <<-EOT
+  #ifndef #{options.decl.gsub(/[^\w]/, "_").upcase}
+  #define #{options.decl.gsub(/[^\w]/, "_").upcase}
+  #include "pk11.h"
+  #ifdef HAVE_RB_THREAD_BLOCKING_REGION
+EOT
+fd_impl.puts <<-EOT
+  #include #{File.basename(options.decl).inspect}
+  #ifdef HAVE_RB_THREAD_BLOCKING_REGION
+EOT
+ARGV.each do |file_h|
+  c_src = IO.read(file_h)
+  c_src.scan(/CK_PKCS11_FUNCTION_INFO\((.+?)\).*?\((.*?)\);/m) do
+    func_name, func_param_list = $1, $2
+    func_params = []
+    func_param_list.scan(/^\s+([A-Z_0-9]+)\s+([\w_]+)/) do |elem|
+      func_params << Attribute.new($1, $2)
+    end
+    puts "func_name:#{func_name.inspect} func_params: #{func_params.inspect}" if options.verbose
+
+    fd_decl.puts <<-EOT
+      struct tbr_#{func_name}_params {
+        CK_#{func_name} func;
+        struct { #{ func_params.map{|f| f.type+" "+f.name+";"}.join } } params;
+        CK_RV retval;
+      };
+      VALUE tbf_#{func_name}( void *data );
+      
+    EOT
+    fd_impl.puts <<-EOT
+      VALUE tbf_#{func_name}( void *data ){
+        struct tbr_#{func_name}_params *p = (struct tbr_#{func_name}_params*)data;
+        p->retval = p->func( #{func_params.map{|f| "p->params."+f.name}.join(",") } );
+        return Qnil;
+      }
+
+    EOT
+  end
+end
+fd_impl.puts <<-EOT
+  #endif
+EOT
+fd_decl.puts <<-EOT
+  #endif
+  #endif
+EOT
+end
+end