pkcs11 0.1.0 → 0.2.0

data/lib/pkcs11.rb

@@ -1,12 +1,9 @@
 #!/usr/bin/env ruby
 
-# Load the correct version if it's a Windows binary gem
-if RUBY_PLATFORM =~/(mswin|mingw)/i
-  major_minor = RUBY_VERSION[ /^(\d+\.\d+)/ ] or
-    raise "Oops, can't extract the major/minor version from #{RUBY_VERSION.dump}"
-  require "#{major_minor}/pkcs11_ext"
-else
-  require 'pkcs11_ext'
-end
+# Extend the search path for Windows binary gem, depending of the current ruby version
+major_minor = RUBY_VERSION[ /^(\d+\.\d+)/ ] or
+  raise "Oops, can't extract the major/minor version from #{RUBY_VERSION.dump}"
+$: << File.join(File.dirname(__FILE__), major_minor)
 
+require 'pkcs11_ext'
 require 'pkcs11/extensions'

data/lib/pkcs11/extensions.rb

@@ -7,14 +7,13 @@ require 'pkcs11/object'
 #
 # This library allowes to use PKCS#11 librarys in Ruby MRI.
 #
-# Example usage:
-#
+# @example
 #   pkcs11 = PKCS11.open("/path/to/pkcs11.so")
 #   slot = pkcs11.active_slots.first
 #   p slot.info
 #   session = slot.open(PKCS11::CKF_SERIAL_SESSION|PKCS11::CKF_RW_SESSION)
 #   session.login(:USER, "1234")
-#   ...
+#   # ... crypto operations
 #   session.logout
 #   session.close
 #
@@ -25,136 +24,45 @@ module PKCS11
     # Open a PKCS#11 library file.
     alias new open
   end
-  
-  module InspectableStruct
-    # Array of the InspectableStruct's attribute names.
-    def members
-      (self.methods - ::Object.new.methods - InspectableStruct.instance_methods).grep(/[^=]$/).sort
-    end
-    # Array of the InspectableStruct's attribute values.
+
+  # Base class of all PKCS#11 structs.
+  class CStruct
+    # @return [Array<String>] attribute names
     def values
       members.inject([]){|a,v| a << send(v) }
     end
-    # Hash with the InspectableStruct's attribute names and values.
+    # @return [Hash] with attribute names and current values
     def to_hash
       members.inject({}){|h,v| h[v.intern] = send(v); h }
     end
-    def inspect # :nodoc:
+    def inspect
       "#<#{self.class} #{to_hash.map{|k,v| "#{k}=#{v.inspect}"}.join(", ") }>"
     end
   end
 
-  module InspectableAttribute
-    # Array of the InspectableStruct's attribute names.
+  # Struct to hold an attribute type and it's value.
+  #
+  # @see PKCS11::Object
+  class CK_ATTRIBUTE
+    # @return [Array<String>] attribute names
     def members
       ['type', 'value']
     end
-    # Array of the InspectableStruct's attribute values.
+    # @return [Array<String, Boolean, Integer>] attribute values
     def values
       members.inject([]){|a,v| a << send(v) }
     end
-    # Hash with the InspectableStruct's attribute names and values.
+    # @return [Hash] with attribute names and current values
     def to_hash
       members.inject({}){|h,v| h[v.intern] = send(v); h }
     end
     # Get the constant name as String of the given value.
-    # Returns <tt>nil</tt> if value is unknown.
+    # @return [String, nil]  Returns <tt>nil</tt> if value is unknown
     def to_s
       ATTRIBUTES[type]
     end
-    def inspect # :nodoc:
-      "#<#{self.class} #{ to_s ? "#{to_s} (#{type})" : type} value=#{value.inspect}>"
-    end
-  end
-
-  # See InspectableStruct.
-  class CK_INFO
-    include InspectableStruct
-  end
-  # See InspectableStruct.
-  class CK_C_INITIALIZE_ARGS
-    include InspectableStruct
-  end
-  # See InspectableStruct.
-  class CK_ATTRIBUTE
-    include InspectableAttribute
-  end
-  # See InspectableStruct.
-  class CK_TOKEN_INFO
-    include InspectableStruct
-  end
-  # See InspectableStruct.
-  class CK_SLOT_INFO
-    include InspectableStruct
-  end
-  # See InspectableStruct.
-  class CK_MECHANISM_INFO
-    include InspectableStruct
-  end
-  # See InspectableStruct.
-  class CK_SESSION_INFO
-    include InspectableStruct
-  end
-  # See InspectableStruct.
-  class CK_MECHANISM
-    include InspectableStruct
-  end
-
-  class ConstValue
-    def initialize(enum_hash, value) # :nodoc:
-      @enum_hash, @value = enum_hash, value
-    end
-
-    # Get the constant name as String of the given value.
-    # Returns <tt>nil</tt> if value is unknown.
-    def to_s
-      @enum_hash[@value]
-    end
     def inspect
-#       "#<#{self.class} #{ to_s ? "#{to_s} (#{@value})" : @value}>"
-      @value.inspect
-    end
-
-    # The value of the constant.
-    def to_int
-      @value
-    end
-    alias to_i to_int
-  end
-
-  module ConstValueHash # :nodoc:
-    def [](value)
-      super(value.to_int)
-    end
-  end
-
-  class << self
-    def extend_ConstValueHash(hash_symb) # :nodoc:
-      # The MECHANISMS, ATTRIBUTES, etc. Hashs are freezed.
-      # So, we have make a copy, to extend the class.
-      my_HASH = const_get(hash_symb).dup
-      my_HASH.extend ConstValueHash
-      my_HASH.freeze
-      const_set("UNWRAPPED_#{hash_symb}", hash_symb)
-      remove_const(hash_symb)
-      const_set(hash_symb, my_HASH)
+      "#<#{self.class} #{ to_s ? "#{to_s} (#{type})" : type} value=#{value.inspect}>"
     end
-    private :extend_ConstValueHash
-  end
-
-  extend_ConstValueHash(:OBJECT_CLASSES)
-  class ObjectClass < ConstValue
   end
-
-  extend_ConstValueHash(:ATTRIBUTES)
-  class Attribute < ConstValue
-  end
-
-  extend_ConstValueHash(:MECHANISMS)
-  class Mechanism < ConstValue
-  end
-
-#   extend_ConstValueHash(:RETURN_VALUES)
-#   class ReturnValue < ConstValue
-#   end
 end

data/lib/pkcs11/helper.rb

@@ -0,0 +1,151 @@
+module PKCS11
+  # Some functions internaly used to make the API more convenient.
+  # @private
+  module Helper  # :nodoc:
+    private
+
+    MechanismParameters = {
+      CKM_RSA_PKCS_OAEP => CK_RSA_PKCS_OAEP_PARAMS,
+      CKM_RSA_PKCS_PSS => CK_RSA_PKCS_PSS_PARAMS,
+      CKM_SHA1_RSA_PKCS_PSS => CK_RSA_PKCS_PSS_PARAMS,
+      CKM_SHA256_RSA_PKCS_PSS => CK_RSA_PKCS_PSS_PARAMS,
+      CKM_SHA384_RSA_PKCS_PSS => CK_RSA_PKCS_PSS_PARAMS,
+      CKM_SHA512_RSA_PKCS_PSS => CK_RSA_PKCS_PSS_PARAMS,
+      CKM_ECDH1_DERIVE => CK_ECDH1_DERIVE_PARAMS,
+      CKM_ECDH1_COFACTOR_DERIVE => CK_ECDH1_DERIVE_PARAMS,
+      CKM_ECMQV_DERIVE => CK_ECMQV_DERIVE_PARAMS,
+      CKM_X9_42_DH_DERIVE => CK_X9_42_DH1_DERIVE_PARAMS,
+# 			CKM_X9_42_MQV_DERIVE => CK_X9_42_DH2_DERIVE_PARAMS,
+      CKM_X9_42_DH_HYBRID_DERIVE => CK_X9_42_DH2_DERIVE_PARAMS,
+      CKM_X9_42_MQV_DERIVE => CK_X9_42_MQV_DERIVE_PARAMS,
+      CKM_KEA_KEY_DERIVE => CK_KEA_DERIVE_PARAMS,
+      CKM_RC2_CBC => CK_RC2_CBC_PARAMS,
+      CKM_RC2_CBC_PAD => CK_RC2_CBC_PARAMS,
+      CKM_RC2_MAC_GENERAL => CK_RC2_MAC_GENERAL_PARAMS,
+      CKM_RC5_MAC => CK_RC5_PARAMS,
+      CKM_RC5_ECB => CK_RC5_PARAMS,
+      CKM_RC5_CBC => CK_RC5_CBC_PARAMS,
+      CKM_RC5_CBC_PAD => CK_RC5_CBC_PARAMS,
+      CKM_RC5_MAC_GENERAL => CK_RC5_MAC_GENERAL_PARAMS,
+
+      CKM_SKIPJACK_PRIVATE_WRAP => CK_SKIPJACK_PRIVATE_WRAP_PARAMS,
+      CKM_SKIPJACK_RELAYX => CK_SKIPJACK_RELAYX_PARAMS,
+      CKM_PBE_MD2_DES_CBC => CK_PBE_PARAMS,
+      CKM_PBE_MD5_DES_CBC => CK_PBE_PARAMS,
+      CKM_PBE_MD5_CAST_CBC => CK_PBE_PARAMS,
+      CKM_PBE_MD5_CAST3_CBC => CK_PBE_PARAMS,
+      CKM_PBE_MD5_CAST5_CBC => CK_PBE_PARAMS,
+      CKM_PBE_MD5_CAST128_CBC => CK_PBE_PARAMS,
+      CKM_PBE_SHA1_CAST5_CBC => CK_PBE_PARAMS,
+      CKM_PBE_SHA1_CAST128_CBC => CK_PBE_PARAMS,
+      CKM_PBE_SHA1_RC4_128 => CK_PBE_PARAMS,
+      CKM_PBE_SHA1_RC4_40 => CK_PBE_PARAMS,
+      CKM_PBE_SHA1_DES3_EDE_CBC => CK_PBE_PARAMS,
+      CKM_PBE_SHA1_DES2_EDE_CBC => CK_PBE_PARAMS,
+      CKM_PBE_SHA1_RC2_128_CBC => CK_PBE_PARAMS,
+      CKM_PBE_SHA1_RC2_40_CBC => CK_PBE_PARAMS,
+      CKM_PBA_SHA1_WITH_SHA1_HMAC => CK_PBE_PARAMS,
+      CKM_PKCS5_PBKD2 => CK_PKCS5_PBKD2_PARAMS,
+      CKM_KEY_WRAP_SET_OAEP => CK_KEY_WRAP_SET_OAEP_PARAMS,
+      CKM_SSL3_MASTER_KEY_DERIVE => CK_SSL3_RANDOM_DATA,
+      CKM_SSL3_KEY_AND_MAC_DERIVE => CK_SSL3_RANDOM_DATA,
+      CKM_SSL3_MASTER_KEY_DERIVE => CK_SSL3_MASTER_KEY_DERIVE_PARAMS,
+      CKM_SSL3_KEY_AND_MAC_DERIVE => CK_SSL3_KEY_MAT_OUT,
+      CKM_SSL3_KEY_AND_MAC_DERIVE => CK_SSL3_KEY_MAT_PARAMS,
+      CKM_TLS_MASTER_KEY_DERIVE => CK_SSL3_MASTER_KEY_DERIVE_PARAMS,
+      CKM_TLS_PRF => CK_TLS_PRF_PARAMS,
+      CKM_WTLS_MASTER_KEY_DERIVE => CK_WTLS_RANDOM_DATA,
+      CKM_WTLS_MASTER_KEY_DERIVE => CK_WTLS_MASTER_KEY_DERIVE_PARAMS,
+      CKM_WTLS_PRF => CK_WTLS_PRF_PARAMS,
+      CKM_WTLS_SERVER_KEY_AND_MAC_DERIVE => CK_WTLS_KEY_MAT_PARAMS,
+      CKM_WTLS_CLIENT_KEY_AND_MAC_DERIVE => CK_WTLS_KEY_MAT_PARAMS,
+      CKM_CMS_SIG => CK_CMS_SIG_PARAMS,
+
+      CKM_DES_ECB_ENCRYPT_DATA => CK_KEY_DERIVATION_STRING_DATA,
+      CKM_DES_CBC_ENCRYPT_DATA => CK_DES_CBC_ENCRYPT_DATA_PARAMS,
+      CKM_DES3_ECB_ENCRYPT_DATA => CK_KEY_DERIVATION_STRING_DATA,
+      CKM_DES3_CBC_ENCRYPT_DATA => CK_DES_CBC_ENCRYPT_DATA_PARAMS,
+      CKM_AES_ECB_ENCRYPT_DATA => CK_KEY_DERIVATION_STRING_DATA,
+      CKM_AES_CBC_ENCRYPT_DATA => CK_AES_CBC_ENCRYPT_DATA_PARAMS,
+      CKM_CONCATENATE_BASE_AND_DATA => CK_KEY_DERIVATION_STRING_DATA,
+      CKM_CONCATENATE_DATA_AND_BASE => CK_KEY_DERIVATION_STRING_DATA,
+      CKM_XOR_BASE_AND_DATA => CK_KEY_DERIVATION_STRING_DATA,
+
+      CKM_ARIA_ECB_ENCRYPT_DATA => CK_KEY_DERIVATION_STRING_DATA,
+      CKM_ARIA_CBC_ENCRYPT_DATA => CK_ARIA_CBC_ENCRYPT_DATA_PARAMS,
+
+      CKM_SSL3_PRE_MASTER_KEY_GEN => CK_VERSION,
+      CKM_TLS_PRE_MASTER_KEY_GEN => CK_VERSION,
+=begin
+      # for PKCS#11 v2.30
+      CKM_SEED_ECB_ENCRYPT_DATA => CK_KEY_DERIVATION_STRING_DATA,
+      CKM_SEED_CBC_ENCRYPT_DATA => CK_CBC_ENCRYPT_DATA_PARAMS,
+      CKM_GOSTR3410_KEY_WRAP => CK_GOSTR3410_KEY_WRAP_PARAMS,
+      CKM_GOSTR3410_DERIVE => CK_GOSTR3410_DERIVE_PARAMS,
+      CKM_GOSTR3410_KEY_WRAP => CK_GOSTR3410_KEY_WRAP_PARAMS,
+=end
+    }
+
+    def to_attributes(template)
+      case template
+        when Array
+          template.map{|v| PKCS11::CK_ATTRIBUTE.new(string_to_handle('CKA_', v), nil) }
+        when Hash
+          template.map{|k,v| PKCS11::CK_ATTRIBUTE.new(string_to_handle('CKA_', k), v) }
+        when String, Symbol
+          [PKCS11::CK_ATTRIBUTE.new(string_to_handle('CKA_', template), nil)]
+        when Integer
+          [PKCS11::CK_ATTRIBUTE.new(template, nil)]
+        else
+          template
+      end
+    end
+
+    def string_to_handle(prefix, attribute) # :nodoc:
+      case attribute
+        when String, Symbol
+          PKCS11.const_get("#{prefix}#{attribute}")
+        else
+          attribute
+      end
+    end
+
+    def to_mechanism(mechanism) # :nodoc:
+      case mechanism
+        when String, Symbol
+          PKCS11::CK_MECHANISM.new(string_to_handle('CKM_', mechanism))
+        when Hash
+          raise "only one mechanism allowed" unless mechanism.length==1
+
+          mech = string_to_handle('CKM_', mechanism.keys.first)
+          param = mechanism.values.first
+          case param
+          when Hash
+            param_class = MechanismParameters[mech]
+            raise ArgumentError, "unknown mechanism - please use mechanism parameter as String" unless param_class
+
+            pa = param_class.new
+            param.each do |k, v|
+              pa.send "#{k}=", v
+            end
+            param = pa
+          end
+
+          PKCS11::CK_MECHANISM.new(mech, param)
+        when Fixnum
+          PKCS11::CK_MECHANISM.new(mechanism)
+        else
+          mechanism
+      end
+    end
+
+    def to_mechanism_int(mechanism) # :nodoc:
+      case mechanism
+        when String, Symbol
+          PKCS11::MECHANISMS[string_to_handle('CKM_', mechanism)]
+        else
+          mechanism
+      end
+    end
+  end
+end

data/lib/pkcs11/library.rb

@@ -1,13 +1,40 @@
 module PKCS11
   # A Library instance holds a handle to the opened PKCS#11 - dll or so file.
+  #
+  # == Low layer API
+  # The API of the binding consists of a lower layer, which
+  # is near to the PKCS#11 C interface, and a higher layer, which
+  # is more Ruby like and more comfortable. The low layer is currently
+  # not explicitly documented and is not recommented to use.
+  #
+  # All low layer PKCS#11 functions can be called on the {PKCS11::Library} object.
+  # Example for starting a session:
+  #   pkcs11 = PKCS11.open("/path/to/pkcs11.so")
+  #   slot = pkcs11.C_GetSlotList(true).first
+  #   session = pkcs11.C_OpenSession(slot, PKCS11::CKF_SERIAL_SESSION | PKCS11::CKF_RW_SESSION)
+  #   pkcs11.C_Login(session, PKCS11::CKU_USER, "password")
+  #
+  # The same on the high layer:
+  #   pkcs11 = PKCS11.open("/path/to/pkcs11.so")
+  #   session = pkcs11.active_slots.first.open
+  #   session.login(:USER, "password")
   class Library
+    # @private
     alias unwrapped_initialize initialize # :nodoc:
 
     # Load and initialize a pkcs11 dynamic library.
     #
-    # so_path:: Path to the *.so or *.dll file to load.
-    # args:: A Hash or CK_C_INITIALIZE_ARGS instance with load params.
-    def initialize(so_path, args={})
+    # @param [String, nil] so_path  Path to the *.so or *.dll file to load.
+    # @param [Hash, CK_C_INITIALIZE_ARGS] args  A Hash or CK_C_INITIALIZE_ARGS instance with load params.
+    #
+    # If so_path is +nil+ no library is loaded or initialized.
+    # In this case the calls to {#load_library}, {#C_GetFunctionList} and
+    # {#C_Initialize} have to be done manually, before using other methods:
+    #   pkcs11 = PKCS11::Library.new
+    #   pkcs11.load_library(so_path)
+    #   pkcs11.C_GetFunctionList
+    #   pkcs11.C_Initialize(args)
+    def initialize(so_path=nil, args={})
       case args
         when Hash
           pargs = CK_C_INITIALIZE_ARGS.new
@@ -20,6 +47,7 @@ module PKCS11
 
     alias unwrapped_C_GetInfo C_GetInfo
     # Returns general information about Cryptoki.
+    # @return [CK_INFO]
     def C_GetInfo
       unwrapped_C_GetInfo
     end
@@ -27,9 +55,12 @@ module PKCS11
 
     alias unwrapped_C_GetSlotList C_GetSlotList
     
-    # Obtain an array of Slot objects in the system. tokenPresent indicates
-    # whether the list obtained includes only those slots with a token present (true), or
-    # all slots (false);
+    # Obtain an array of Slot objects in the system.
+    #
+    # @param [true, false] tokenPresent  indicates whether the list
+    #    obtained includes only those slots with a token present (true), or
+    #    all slots (false);
+    # @return [Array<Slot>]
     def C_GetSlotList(tokenPresent=true)
       slots = unwrapped_C_GetSlotList(tokenPresent)
       slots.map{|slot|
@@ -39,25 +70,25 @@ module PKCS11
     alias slots C_GetSlotList
 
     # Obtain an array of Slot objects in the system with a token present.
+    # @return [Array<Slot>]
     def active_slots
       slots(true)
     end
     
     # Obtain an array of Slot objects in the system regardless if a token is present.
+    # @return [Array<Slot>]
     def all_slots
       slots(false)
     end
-    
-    alias unwrapped_C_Finalize C_Finalize
-    # Close and unload library. If not called, the library is freed by the GC.
-    def C_Finalize
-      unwrapped_C_Finalize
+
+    # Finalize and unload the library. If not called explicit, the library is freed by the GC.
+    def close
+      self.C_Finalize
+      self.unload_library
     end
-    alias close C_Finalize
     
     private :unwrapped_initialize
     private :unwrapped_C_GetSlotList
-    private :unwrapped_C_Finalize
     private :unwrapped_C_GetInfo
   end
 end

data/lib/pkcs11/object.rb

@@ -1,33 +1,47 @@
+require 'pkcs11/helper'
+
 module PKCS11
-  # Cryptoki’s logical view of a token is a device that stores objects and can perform
+  # Cryptoki's logical view of a token is a device that stores objects and can perform
   # cryptographic functions. Cryptoki defines three classes of object: data, certificates, and
   # keys.
   #
   # Attributes are characteristics that distinguish an instance of an object.
   class Object
+    include Helper
+
+    # @private
     def initialize(pkcs11, session, object) # :nodoc:
       @pk, @sess, @obj = pkcs11, session, object
     end
 
     # The object handle.
+    # @return [Integer]
     def to_int
       @obj
     end
     alias to_i to_int
 
+    # @private
     def inspect # :nodoc:
       "#<#{self.class} #{@obj.inspect}>"
     end
 
-    # Returns the value of one attribute of the object.
+    # Get the value of one attribute of the object.
     #
-    # attribute:: can be String or Symbol of the attribute constant
+    # @param [String, Symbol, Integer] attribute can be String or Symbol of the attribute constant
     #             or the attribute number as Integer.
     #
-    # Returns the attribute value as String, Integer or true/false
-    # depending on the attribute type.
-    # Unknown attributes (out of PKCS#11 v2.2) are not converted but returned as String.
+    # @return [String, Integer, Boolean, nil] the attribute value as String, Integer or true/false
+    #   depending on the attribute type.
+    # Unknown attributes (out of PKCS#11 v2.2) are not converted to adequate
+    # ruby objects but returned as String.
     # That is true/false will be returned as "\\001" respectively "\\000".
+    #
+    # @example
+    #     object[:VALUE] # => "\000\000\000\000\000\000\000\000"
+    #     object[:MODULUS_BITS] # => 768
+    #
+    # See PKCS#11 for attribute definitions.
     def [](attribute)
       attrs = C_GetAttributeValue( [attribute] )
       attrs.first.value unless attrs.empty?
@@ -35,39 +49,52 @@ module PKCS11
 
     # Modifies the value of one attribute the object.
     #
-    # attribute:: can be String or Symbol of the attribute constant
+    # @param [String, Symbol, Integer] attribute can be String or Symbol of the attribute constant
     #             or the attribute value as Integer.
-    # value:: String value the attribute will be set to.
+    # @param [String, Integer, Boolean, nil] value value the attribute will be set to.
     #
-    # Following value conversations are done:
+    # Following value conversations are done from Ruby to C:
     #   true   -> 0x01
     #   false  -> 0x00
     #   nil    -> NULL pointer
     #   Fixnum -> binary encoded unsigned long
+    #
+    # @example
+    #     object[:VALUE] = "\000\000\000\000\000\000\000\000"
+    #     object[:MODULUS_BITS] = 768
+    #
+    # See PKCS#11 for attribute definitions.
+    # @return value
     def []=(attribute, value)
       C_SetAttributeValue( attribute => value )
+      value
     end
 
     # Modifies the value of one or more attributes of the object in a single call.
     #
-    # Examples:
+    # @example
     #   object.attributes = {:SUBJECT => cert_subject, PKCS11::CKA_VALUE => cert_data}
+    # @return template
     def C_SetAttributeValue(template={})
-      template = Session.hash_to_attributes template
-      @pk.C_SetAttributeValue(@sess, @obj, template)
+      @pk.C_SetAttributeValue(@sess, @obj, to_attributes(template))
+      template
     end
     alias attributes= C_SetAttributeValue
     
     # Obtains the value of one or more attributes of the object in a single call.
     #
+    # @param [Array<String, Symbol, Integer>, Hash, String, Integer] attribute attribute names
+    #    whose values should be returned
+    #
     # Without params all known attributes are tried to read from the Object.
     # This is significant slower then naming the needed attributes and should
     # be used for debug purposes only.
     #
-    # Returns an Array of PKCS11::CK_ATTRIBUTE's.
+    # @return [Array<PKCS11::CK_ATTRIBUTE>] Requested attributes with values.
     #
-    # Example:
-    #   certificate.attributes :ID, :VALUE
+    # @example
+    #   certificate.attributes :VALUE, :CLASS
+    #    => [#<PKCS11::CK_ATTRIBUTE CKA_VALUE (17) value="0\x82...">, #<PKCS11::CK_ATTRIBUTE CKA_CLASS (0) value=1>]
     def C_GetAttributeValue(*template)
       case template.length
         when 0
@@ -80,21 +107,50 @@ module PKCS11
         when 1
           template = template[0]
       end
-      template = Session.hash_to_attributes template
+      template = to_attributes template
       @pk.C_GetAttributeValue(@sess, @obj, template)
     end
     alias attributes C_GetAttributeValue
-    
+
+    # Copies an object, creating a new object for the copy.
+    #
+    # @param [Hash] template
+    #
+    # The template may specify new values for any attributes of the object that can ordinarily
+    # be modified (e.g., in the course of copying a secret key, a key's CKA_EXTRACTABLE
+    # attribute may be changed from true to false, but not the other way around.
+    # If this change is made, the new key's CKA_NEVER_EXTRACTABLE attribute will
+    # have the value false. Similarly, the template may specify that the new key's
+    # CKA_SENSITIVE attribute be true; the new key will have the same value for its
+    # CKA_ALWAYS_SENSITIVE attribute as the original key). It may also specify new
+    # values of the CKA_TOKEN and CKA_PRIVATE attributes (e.g., to copy a session
+    # object to a token object). If the template specifies a value of an attribute which is
+    # incompatible with other existing attributes of the object, the call fails with exception
+    # CKR_TEMPLATE_INCONSISTENT.
+    #
+    # Only session objects can be created during a read-only session. Only public objects can
+    # be created unless the normal user is logged in.
+    #
+    # @return [PKCS11::Object] the newly created object
+    def C_CopyObject(template={})
+      handle = @pk.C_CopyObject(@sess, @obj, to_attributes(template))
+      Object.new @pk, @sess, handle
+    end
+    alias copy C_CopyObject
+
     # Destroys the object.
     #
     # Only session objects can be destroyed during a read-only session. Only public objects
     # can be destroyed unless the normal user is logged in.
+    # @return [PKCS11::Object]
     def C_DestroyObject()
       @pk.C_DestroyObject(@sess, @obj)
+      self
     end
     alias destroy C_DestroyObject
     
     # Gets the size of an object in bytes.
+    # @return [Integer]
     def C_GetObjectSize()
       @pk.C_GetObjectSize(@sess, @obj)
     end