pkcs11 0.1.0 → 0.2.0

data/lib/pkcs11/session.rb

@@ -1,93 +1,69 @@
+require 'pkcs11/helper'
+
 module PKCS11
   # Cryptoki requires that an application open one or more sessions with a token to gain
-  # access to the token’s objects and functions. A session provides a logical connection
+  # access to the token's objects and functions. A session provides a logical connection
   # between the application and the token. A session can be a read/write (R/W) session or a
   # read-only (R/O) session (default).
   class Session
-    class << self
-      def hash_to_attributes(template) # :nodoc:
-        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
+    include Helper
 
-      def string_to_handle(prefix, attribute) # :nodoc:
-        case attribute
-          when String, Symbol
-            PKCS11.const_get("#{prefix}#{attribute}")
-          else
-            attribute
-        end
-      end
-
-      def hash_to_mechanism(hash) # :nodoc:
-        case hash
-          when String, Symbol
-            PKCS11::CK_MECHANISM.new(string_to_handle('CKM_', hash))
-          when Hash
-            raise "only one mechanism allowed" unless hash.length==1
-            PKCS11::CK_MECHANISM.new(string_to_handle('CKM_', hash.keys.first), hash.values.first)
-          else
-            hash.to_int
-        end
-      end
-    end
-    
+    # @private
     def initialize(pkcs11, session) # :nodoc:
       @pk, @sess = pkcs11, session
     end
 
     # The session handle.
+    # @return [Integer]
     def to_int
       @sess
     end
     alias to_i to_int
 
+    # @private
     def inspect # :nodoc:
       "#<#{self.class} #{@sess.inspect}>"
     end
 
     # Logs a user into a token.
-    # user_type:: is the user type CKU_*;
-    # pin:: is the user’s PIN.
+    # @param [Integer, Symbol] user_type  is the user type CKU_*;
+    # @param [String] pin  is the user's PIN.
+    # @return [PKCS11::Session]
     #
     # When the user type is either CKU_SO or CKU_USER, if the call succeeds, each of the
     # application's sessions will enter either the "R/W SO Functions" state, the "R/W User
     # Functions" state, or the "R/O User Functions" state. If the user type is
     # CKU_CONTEXT_SPECIFIC , the behavior of C_Login depends on the context in which
-    # it is called. Improper use of this user type will result in a return value
+    # it is called. Improper use of this user type will raise
     # CKR_OPERATION_NOT_INITIALIZED.
     def C_Login(user_type, pin)
-      @pk.C_Login(@sess, Session::string_to_handle('CKU_', user_type), pin)
+      @pk.C_Login(@sess, string_to_handle('CKU_', user_type), pin)
+      self
     end
     alias login C_Login
 
     # Logs a user out from a token.
     #
-    # Depending on the current user type, if the call succeeds, each of the application’s
-    # sessions will enter either the “R/W Public Session” state or the “R/O Public Session”
+    # Depending on the current user type, if the call succeeds, each of the application's
+    # sessions will enter either the "R/W Public Session" state or the "R/O Public Session"
     # state.
+    # @return [PKCS11::Session]
     def C_Logout()
       @pk.C_Logout(@sess)
+      self
     end
     alias logout C_Logout
 
     # Closes the session between an application and a token.
+    # @return [PKCS11::Session]
     def C_CloseSession()
       @pk.C_CloseSession(@sess)
+      self
     end
     alias close C_CloseSession
 
-    # Obtains information about a session. Returns a CK_SESSION_INFO.
+    # Obtains information about a session.
+    # @return [CK_SESSION_INFO]
     def C_GetSessionInfo()
       @pk.C_GetSessionInfo(@sess)
     end
@@ -96,35 +72,43 @@ module PKCS11
     # Initializes a search for token and session objects that match a
     # template.
     #
-    # find_template:: points to a search template that
+    # See {Session#find_objects} for convenience.
+    # @param [Hash] find_template  points to a search template that
     #                 specifies the attribute values to match
-    #                 The matching criterion is an exact byte-for-byte match with all attributes in the
-    #                 template. Use empty Hash to find all objects.
-
+    # The matching criterion is an exact byte-for-byte match with all attributes in the
+    # template. Use empty Hash to find all objects.
+    # @return [PKCS11::Session]
     def C_FindObjectsInit(find_template={})
-      @pk.C_FindObjectsInit(@sess, Session.hash_to_attributes(find_template))
+      @pk.C_FindObjectsInit(@sess, to_attributes(find_template))
+      self
     end
 
     # Continues a search for token and session objects that match a template,
     # obtaining additional object handles.
     #
-    # Returns an array of Object instances.
+    # See {Session#find_objects} for convenience
+    # @return [Array<PKCS11::Object>] Returns an array of Object instances.
     def C_FindObjects(max_count)
       objs = @pk.C_FindObjects(@sess, max_count)
       objs.map{|obj| Object.new @pk, @sess, obj }
     end
 
     # Terminates a search for token and session objects.
+    #
+    # See {Session#find_objects} for convenience
+    # @return [PKCS11::Session]
     def C_FindObjectsFinal
       @pk.C_FindObjectsFinal(@sess)
+      self
     end
 
-    # Convenience method for the C_FindObjectsInit, C_FindObjects, C_FindObjectsFinal cycle.
+    # Convenience method for the {Session#C_FindObjectsInit}, {Session#C_FindObjects}, {Session#C_FindObjectsFinal} cycle.
     #
     # * If called with block, it iterates over all found objects.
     # * If called without block, it returns with an array of all found Object instances.
+    # @return [Array<PKCS11::Object>]
     #
-    # Example (prints subject of all certificates stored in the token):
+    # @example prints subject of all certificates stored in the token:
     #   session.find_objects(:CLASS => PKCS11::CKO_CERTIFICATE) do |obj|
     #     p OpenSSL::X509::Name.new(obj[:SUBJECT])
     #   end
@@ -148,39 +132,61 @@ module PKCS11
     end
 
 
-    # Creates a new Object based on given template. Returns a new object’s handle.
-    # If C_CreateObject is used to create a key object, the key object will have its
+    # Creates a new Object based on given template.
+    #
+    # If {Session#C_CreateObject} is used to create a key object, the key object will have its
     # CKA_LOCAL attribute set to false. If that key object is a secret or private key
     # then the new key will have the CKA_ALWAYS_SENSITIVE attribute set to
     # false, and the CKA_NEVER_EXTRACTABLE attribute set to false.
     #
     # Only session objects can be created during a read-only session. Only public objects can
     # be created unless the normal user is logged in.
+    #
+    # @param [Hash] template  Attributes of the object to create.
+    # @return [PKCS11::Object] the newly created object
+    # @example Creating a 112 bit DES key from plaintext
+    #     secret_key = session.create_object(
+    #       :CLASS=>PKCS11::CKO_SECRET_KEY, :KEY_TYPE=>PKCS11::CKK_DES2,
+    #       :ENCRYPT=>true, :WRAP=>true, :DECRYPT=>true, :UNWRAP=>true,
+    #       :VALUE=>'0123456789abcdef', :LABEL=>'test_secret_key')
     def C_CreateObject(template={})
-      handle = @pk.C_CreateObject(@sess, Session.hash_to_attributes(template))
+      handle = @pk.C_CreateObject(@sess, to_attributes(template))
       Object.new @pk, @sess, handle
     end
     alias create_object C_CreateObject
 
-    # Initializes the normal user’s PIN. This standard
+    # Initializes the normal user's PIN. This standard
     # allows PIN values to contain any valid UTF8 character, but the token may impose subset
     # restrictions.
+    #
+    # @param [String] pin
+    # @return [PKCS11::Session]
     def C_InitPIN(pin)
       @pk.C_InitPIN(@sess, pin)
+      self
     end
     alias init_pin C_InitPIN
 
     # Modifies the PIN of the user that is currently logged in, or the CKU_USER
     # PIN if the session is not logged in.
+    #
+    # @param [String] old_pin
+    # @param [String] new_pin
+    # @return [PKCS11::Session]
     def C_SetPIN(old_pin, new_pin)
       @pk.C_SetPIN(@sess, old_pin, new_pin)
+      self
     end
     alias set_pin C_SetPIN
 
     class Cipher
+      # @private
       def initialize(update_block) # :nodoc:
         @update_block = update_block
       end
+      # Process a data part with the encryption operation.
+      # @param [String] data  data to be processed
+      # @return [String] output data
       def update(data)
         @update_block.call(data)
       end
@@ -188,11 +194,16 @@ module PKCS11
     end
 
     class DigestCipher < Cipher
+      # @private
       def initialize(update_block, digest_key_block) # :nodoc:
         super(update_block)
         @digest_key_block = digest_key_block
       end
       alias digest_update update
+      # Continues a multiple-part message-digesting operation by digesting the
+      # value of a secret key.
+      # @param [PKCS11::Object] key  key to be processed
+      # @return [String] output data
       def digest_key(key)
         @digest_key_block.call(key)
       end
@@ -228,53 +239,81 @@ module PKCS11
 
     # Initializes an encryption operation.
     #
-    # mechanism:: the encryption mechanism, Hash, String or Integer
-    # key:: the object handle of the encryption key.
+    # @param [Hash, Symbol, Integer, PKCS11::CK_MECHANISM] mechanism  the encryption mechanism
+    # @param [PKCS11::Object] key  the object handle of the encryption key.
+    # @return [PKCS11::Session]
     #
-    # See Session#encrypt for convenience.
+    # See {Session#encrypt} for convenience
     #
     # The CKA_ENCRYPT attribute of the encryption key, which indicates whether the key
     # supports encryption, must be true.
     #
-    # After calling C_EncryptInit, the application can either call C_Encrypt to encrypt data
-    # in a single part; or call C_EncryptUpdate zero or more times, followed by
-    # C_EncryptFinal, to encrypt data in multiple parts. The encryption operation is active
-    # until the application uses a call to C_Encrypt or C_EncryptFinal to actually obtain the
+    # After calling {Session#C_EncryptInit}, the application can either call {Session#C_Encrypt} to encrypt data
+    # in a single part; or call {Session#C_EncryptUpdate} zero or more times, followed by
+    # {Session#C_EncryptFinal}, to encrypt data in multiple parts. The encryption operation is active
+    # until the application uses a call to {Session#C_Encrypt} or {Session#C_EncryptFinal} to actually obtain the
     # final piece of ciphertext. To process additional data (in single or multiple parts), the
-    # application must call C_EncryptInit again.
+    # application must call {Session#C_EncryptInit} again.
     def C_EncryptInit(mechanism, key)
-      @pk.C_EncryptInit(@sess, Session.hash_to_mechanism(mechanism), key)
+      @pk.C_EncryptInit(@sess, to_mechanism(mechanism), key)
+      self
     end
     # Encrypts single-part data.
+    #
+    # See {Session#encrypt} for convenience
+    # @param [Integer, nil] out_size  The buffer size for output data provided to the
+    #    library. If nil, size is determined automatically.
+    # @return [String]
     def C_Encrypt(data, out_size=nil)
       @pk.C_Encrypt(@sess, data, out_size)
     end
     # Continues a multiple-part encryption operation, processing another
     # data part.
+    #
+    # See {Session#encrypt} for convenience
+    # @param [Integer, nil] out_size  The buffer size for output data provided to the
+    #    library. If nil, size is determined automatically.
+    # @return [String]
     def C_EncryptUpdate(data, out_size=nil)
       @pk.C_EncryptUpdate(@sess, data, out_size)
     end
     # Finishes a multiple-part encryption operation.
+    #
+    # See {Session#encrypt} for convenience
+    # @param [Integer, nil] out_size  The buffer size for output data provided to the
+    #    library. If nil, size is determined automatically.
+    # @return [String]
     def C_EncryptFinal(out_size=nil)
       @pk.C_EncryptFinal(@sess, out_size)
     end
 
-    # Convenience method for the C_EncryptInit, C_EncryptUpdate, C_EncryptFinal call flow.
+    # Convenience method for the {Session#C_EncryptInit}, {Session#C_EncryptUpdate}, {Session#C_EncryptFinal} call flow.
     #
-    # If no block is given, the single part operation C_EncryptInit, C_Encrypt is called.
-    # If a block is given, the multi part operation (C_EncryptInit, C_EncryptUpdate, C_EncryptFinal)
+    # If no block is given, the single part operation {Session#C_EncryptInit}, {Session#C_Encrypt} is called.
+    # If a block is given, the multi part operation ({Session#C_EncryptInit}, {Session#C_EncryptUpdate}, {Session#C_EncryptFinal})
     # is used. The given block is called once with a cipher object. There can be any number of
-    # Cipher#update calls within the block, each giving the encryption result of this part as String.
+    # {Cipher#update} calls within the block, each giving the encryption result of this part as String.
     #
-    # Returns the final part of the encryption operation.
+    # @param [Hash, Symbol, Integer, PKCS11::CK_MECHANISM] mechanism  used mechanism
+    # @param [PKCS11::Object] key  used key
+    # @param [String] data  data to encrypt
+    # @yield [PKCS11::Session::Cipher]  Cipher object for processing data parts
+    # @return [String]  the final part of the encryption operation.
     #
-    # Example:
+    # @example for using single part operation
+    #   iv = "12345678"
+    #   cryptogram = session.encrypt( {:DES_CBC_PAD=>iv}, key, "block 1block 2" )
+    #
+    # @example for using multi part operation
     #   iv = "12345678"
     #   cryptogram = ''
     #   cryptogram << session.encrypt( {:DES_CBC_PAD=>iv}, key ) do |cipher|
     #     cryptogram << cipher.update("block 1")
     #     cryptogram << cipher.update("block 2")
     #   end
+    #
+    # @example Calculating a key check value to a secret key
+    #     key_kcv = session.encrypt( :DES3_ECB, key, "\0"*8)
     def encrypt(mechanism, key, data=nil, &block)
       common_crypt(:C_EncryptInit, :C_EncryptUpdate, :C_EncryptFinal, :C_Encrypt,
                    mechanism, key, data, &block)
@@ -282,27 +321,50 @@ module PKCS11
 
     # Initializes a decryption operation.
     #
-    # See Session#decrypt for convenience.
+    # See {Session#decrypt} for convenience and {Session#C_EncryptInit} for description.
     def C_DecryptInit(mechanism, key)
-      @pk.C_DecryptInit(@sess, Session.hash_to_mechanism(mechanism), key)
+      @pk.C_DecryptInit(@sess, to_mechanism(mechanism), key)
     end
     # Decrypts encrypted data in a single part.
+    #
+    # See {Session#decrypt} for convenience.
+    # @param [Integer, nil] out_size  The buffer size for output data provided to the
+    #    library. If nil, size is determined automatically.
+    # @return [String]
     def C_Decrypt(data, out_size=nil)
       @pk.C_Decrypt(@sess, data, out_size)
     end
     # Continues a multiple-part decryption operation, processing another
     # encrypted data part.
+    #
+    # See {Session#decrypt} for convenience.
+    # @param [Integer, nil] out_size  The buffer size for output data provided to the
+    #    library. If nil, size is determined automatically.
+    # @return [String]
     def C_DecryptUpdate(data, out_size=nil)
       @pk.C_DecryptUpdate(@sess, data, out_size)
     end
     # Finishes a multiple-part decryption operation.
+    #
+    # See {Session#decrypt} for convenience.
+    # @param [Integer, nil] out_size  The buffer size for output data provided to the
+    #    library. If nil, size is determined automatically.
+    # @return [String]
     def C_DecryptFinal(out_size=nil)
       @pk.C_DecryptFinal(@sess, out_size)
     end
 
-    # Convenience method for the C_DecryptInit, C_DecryptUpdate, C_DecryptFinal call flow.
+    # Convenience method for the {Session#C_DecryptInit}, {Session#C_DecryptUpdate}, {Session#C_DecryptFinal} call flow.
     #
-    # See Session#encrypt
+    # @see Session#encrypt
+    #
+    # @param [Hash, Symbol, Integer, PKCS11::CK_MECHANISM] mechanism  used mechanism
+    # @param [PKCS11::Object] key  used key
+    # @param [String] data  data to decrypt
+    # @yield [PKCS11::Session::Cipher]  Cipher object for processing data parts
+    # @return [String]  the final part of the encryption operation.
+    # @example Decrypt data previously encrypted with a RSA pulic key
+    #     plaintext2 = session.decrypt( :RSA_PKCS, rsa_priv_key, cryptogram)
     def decrypt(mechanism, key, data=nil, &block)
       common_crypt(:C_DecryptInit, :C_DecryptUpdate, :C_DecryptFinal, :C_Decrypt,
                    mechanism, key, data, &block)
@@ -310,42 +372,67 @@ module PKCS11
 
     # Initializes a message-digesting operation.
     #
-    # See Session#digest for convenience.
+    # See {Session#digest} for convenience.
+    # @return [PKCS11::Session]
     def C_DigestInit(mechanism)
-      @pk.C_DigestInit(@sess, Session.hash_to_mechanism(mechanism))
+      @pk.C_DigestInit(@sess, to_mechanism(mechanism))
+      self
     end
     # Digests data in a single part.
+    #
+    # See {Session#digest} for convenience.
+    # @param [Integer, nil] out_size  The buffer size for output data provided to the
+    #    library. If nil, size is determined automatically.
+    # @return [String]
     def C_Digest(data, out_size=nil)
       @pk.C_Digest(@sess, data, out_size)
     end
     # Continues a multiple-part message-digesting operation, processing
     # another data part.
+    #
+    # See {Session#digest} for convenience.
+    # @return [PKCS11::Session]
     def C_DigestUpdate(data)
       @pk.C_DigestUpdate(@sess, data)
+      self
     end
     # Continues a multiple-part message-digesting operation by digesting the
     # value of a secret key.
     #
-    # The message-digesting operation must have been initialized with C_DigestInit. Calls to
-    # this function and C_DigestUpdate may be interspersed any number of times in any
+    # See {Session#digest} for convenience.
+    #
+    # The message-digesting operation must have been initialized with {Session#C_DigestInit}. Calls to
+    # this function and {Session#C_DigestUpdate} may be interspersed any number of times in any
     # order.
+    # @return [PKCS11::Session]
     def C_DigestKey(key)
       @pk.C_DigestKey(@sess, key)
+      self
     end
     # Finishes a multiple-part message-digesting operation, returning the
     # message digest as String.
+    #
+    # See {Session#digest} for convenience.
+    # @param [Integer, nil] out_size  The buffer size for output data provided to the
+    #    library. If nil, size is determined automatically.
+    # @return [String]
     def C_DigestFinal(out_size=nil)
       @pk.C_DigestFinal(@sess, out_size)
     end
 
-    # Convenience method for the C_DigestInit, C_DigestUpdate, C_DigestKey,
-    # C_DigestFinal call flow.
+    # Convenience method for the {Session#C_DigestInit}, {Session#C_DigestUpdate}, {Session#C_DigestKey},
+    # {Session#C_DigestFinal} call flow.
     #
-    # Example:
+    # @example
     #   digest_string = session.digest( :SHA_1 ) do |cipher|
     #     cipher.update("key prefix")
     #     cipher.digest_key(some_key)
     #   end
+    # @param [Hash, Symbol, Integer, PKCS11::CK_MECHANISM] mechanism  used mechanism
+    # @param [String] data  data to digest
+    # @yield [PKCS11::Session::DigestCipher]  Cipher object for processing data parts
+    # @return [String]  final message digest
+    # @see Session#encrypt
     def digest(mechanism, data=nil, &block)
       C_DigestInit(mechanism)
       if block_given?
@@ -364,27 +451,46 @@ module PKCS11
     # Initializes a signature operation, where the signature is an appendix to the
     # data.
     #
-    # See Session#sign for convenience.
+    # See {Session#sign} for convenience.
+    # @return [PKCS11::Session]
     def C_SignInit(mechanism, key)
-      @pk.C_SignInit(@sess, Session.hash_to_mechanism(mechanism), key)
+      @pk.C_SignInit(@sess, to_mechanism(mechanism), key)
+      self
     end
     # Signs data in a single part, where the signature is an appendix to the data.
+    #
+    # See {Session#sign} for convenience.
+    # @return [String]  message signature
     def C_Sign(data, out_size=nil)
       @pk.C_Sign(@sess, data, out_size)
     end
     # Continues a multiple-part signature operation, processing another data
     # part.
+    #
+    # See {Session#sign} for convenience.
+    # @return [PKCS11::Session]
     def C_SignUpdate(data)
       @pk.C_SignUpdate(@sess, data)
+      self
     end
     # Finishes a multiple-part signature operation, returning the signature.
+    #
+    # See {Session#sign} for convenience.
+    # @return [String]  message signature
     def C_SignFinal(out_size=nil)
       @pk.C_SignFinal(@sess, out_size)
     end
 
-    # Convenience method for the C_SignInit, C_SignUpdate, C_SignFinal call flow.
+    # Convenience method for the {Session#C_SignInit}, {Session#C_SignUpdate}, {Session#C_SignFinal} call flow.
     #
-    # See Session#encrypt
+    # @param [Hash, Symbol, Integer, PKCS11::CK_MECHANISM] mechanism  used mechanism
+    # @param [PKCS11::Object] key  used key
+    # @param [String] data  data to sign
+    # @yield [PKCS11::Session::Cipher]  Cipher object for processing data parts
+    # @return [String]  signature
+    # @see Session#encrypt
+    # @example Sign a text by a RSA private key
+    #     signature = session.sign( :SHA1_RSA_PKCS, rsa_priv_key, "important text")
     def sign(mechanism, key, data=nil, &block)
       common_crypt(:C_SignInit, :C_SignUpdate, :C_SignFinal, :C_Sign,
                    mechanism, key, data, &block)
@@ -394,30 +500,43 @@ module PKCS11
     # Initializes a verification operation, where the signature is an appendix to
     # the data.
     #
-    # See ession#verify for convenience.
+    # See {Session#verify} for convenience.
     def C_VerifyInit(mechanism, key)
-      @pk.C_VerifyInit(@sess, Session.hash_to_mechanism(mechanism), key)
+      @pk.C_VerifyInit(@sess, to_mechanism(mechanism), key)
     end
     # Verifies a signature in a single-part operation, where the signature is an
     # appendix to the data.
+    #
+    # See {Session#verify} for convenience.
     def C_Verify(data, out_size=nil)
       @pk.C_Verify(@sess, data, out_size)
     end
     # Continues a multiple-part verification operation, processing another
     # data part.
+    #
+    # See {Session#verify} for convenience.
     def C_VerifyUpdate(data)
       @pk.C_VerifyUpdate(@sess, data)
     end
     # Finishes a multiple-part verification operation, checking the signature.
     #
-    # Returns <tt>true</tt> for valid signature.
+    # See {Session#verify} for convenience.
+    # @return [Boolean] <tt>true</tt> for valid signature.
     def C_VerifyFinal(out_size=nil)
       @pk.C_VerifyFinal(@sess, out_size)
     end
 
-    # Convenience method for the C_VerifyInit, C_VerifyUpdate, C_VerifyFinal call flow.
+    # Convenience method for the {Session#C_VerifyInit}, {Session#C_VerifyUpdate}, {Session#C_VerifyFinal} call flow.
     #
-    # See Session#encrypt
+    # @see Session#encrypt
+    # @param [Hash, Symbol, Integer, PKCS11::CK_MECHANISM] mechanism  used mechanism
+    # @param [PKCS11::Object] key  used key
+    # @param [String] signature  signature
+    # @param [String] data  data to verify against signature
+    # @yield [PKCS11::Session::Cipher]  Cipher object for processing data parts
+    # @return [Boolean] <tt>true</tt> for valid signature.
+    # @example
+    #     raise("wrong signature") unless session.verify(:SHA1_RSA_PKCS, rsa_pub_key, signature, plaintext)
     def verify(mechanism, key, signature, data=nil, &block)
       common_verify(:C_VerifyInit, :C_VerifyUpdate, :C_VerifyFinal, :C_Verify,
                    mechanism, key, signature, data, &block)
@@ -425,16 +544,27 @@ module PKCS11
 
     # Initializes a signature operation, where the data can be recovered
     # from the signature
+    #
+    # See {Session#sign_recover} for convenience.
     def C_SignRecoverInit(mechanism, key)
-      @pk.C_SignRecoverInit(@sess, Session.hash_to_mechanism(mechanism), key)
+      @pk.C_SignRecoverInit(@sess, to_mechanism(mechanism), key)
+      self
     end
     # Signs data in a single operation, where the data can be recovered from
     # the signature.
+    #
+    # See {Session#sign_recover} for convenience.
     def C_SignRecover(data, out_size=nil)
       @pk.C_SignRecover(@sess, data, out_size)
     end
 
-    # Convenience method for the C_SignRecoverInit, C_SignRecover call flow.
+    # Convenience method for the {Session#C_SignRecoverInit}, {Session#C_SignRecover} call flow.
+    #
+    # @param [Hash, Symbol, Integer, PKCS11::CK_MECHANISM] mechanism  used mechanism
+    # @param [PKCS11::Object] key  signature key
+    # @param [String] data  data to be recovered
+    # @return [String]  signature
+    # @see Session#verify_recover
     def sign_recover(mechanism, key, data)
       C_SignRecoverInit(mechanism, key)
       C_SignRecover(data)
@@ -444,17 +574,24 @@ module PKCS11
     # Initializes a signature verification operation, where the data can be recovered
     # from the signature
     #
-    # See Session#verify_recover for convenience.
+    # See {Session#verify_recover} for convenience.
     def C_VerifyRecoverInit(mechanism, key)
-      @pk.C_VerifyRecoverInit(@sess, Session.hash_to_mechanism(mechanism), key)
+      @pk.C_VerifyRecoverInit(@sess, to_mechanism(mechanism), key)
     end
     # Verifies a signature in a single-part operation, where the data is
     # recovered from the signature.
+    #
+    # See {Session#verify_recover} for convenience.
     def C_VerifyRecover(signature, out_size=nil)
       @pk.C_VerifyRecover(@sess, signature, out_size=nil)
     end
 
-    # Convenience method for the C_VerifyRecoverInit, C_VerifyRecover call flow.
+    # Convenience method for the {Session#C_VerifyRecoverInit}, {Session#C_VerifyRecover} call flow.
+    # 
+    # @param [Hash, Symbol, Integer, PKCS11::CK_MECHANISM] mechanism  used mechanism
+    # @param [PKCS11::Object] key  verification key
+    # @return [String] recovered data
+    # @see Session#sign_recover
     def verify_recover(mechanism, key, signature)
       C_VerifyRecoverInit(mechanism, key)
       C_VerifyRecover(signature)
@@ -464,9 +601,9 @@ module PKCS11
     # processing another data part.
     #
     # Digest and encryption operations must both be active (they must have been initialized
-    # with C_DigestInit and C_EncryptInit, respectively). This function may be called any
-    # number of times in succession, and may be interspersed with C_DigestUpdate,
-    # C_DigestKey, and C_EncryptUpdate calls.
+    # with {Session#C_DigestInit} and {Session#C_EncryptInit}, respectively). This function may be called any
+    # number of times in succession, and may be interspersed with {Session#C_DigestUpdate},
+    # {Session#C_DigestKey}, and {Session#C_EncryptUpdate} calls.
     def C_DigestEncryptUpdate(data, out_size=nil)
       @pk.C_DigestEncryptUpdate(@sess, data, out_size)
     end
@@ -475,9 +612,9 @@ module PKCS11
     # operation, processing another data part.
     #
     # Decryption and digesting operations must both be active (they must have been initialized
-    # with C_DecryptInit and C_DigestInit, respectively). This function may be called any
-    # number of times in succession, and may be interspersed with C_DecryptUpdate,
-    # C_DigestUpdate, and C_DigestKey calls.
+    # with {Session#C_DecryptInit} and {Session#C_DigestInit}, respectively). This function may be called any
+    # number of times in succession, and may be interspersed with {Session#C_DecryptUpdate},
+    # {Session#C_DigestUpdate}, and {Session#C_DigestKey} calls.
     def C_DecryptDigestUpdate(data, out_size=nil)
       @pk.C_DecryptDigestUpdate(@sess, data, out_size)
     end
@@ -486,9 +623,9 @@ module PKCS11
     # operation, processing another data part.
     #
     # Signature and encryption operations must both be active (they must have been initialized
-    # with C_SignInit and C_EncryptInit, respectively). This function may be called any
-    # number of times in succession, and may be interspersed with C_SignUpdate and
-    # C_EncryptUpdate calls.
+    # with {Session#C_SignInit} and {Session#C_EncryptInit}, respectively). This function may be called any
+    # number of times in succession, and may be interspersed with {Session#C_SignUpdate} and
+    # {Session#C_EncryptUpdate} calls.
     def C_SignEncryptUpdate(data, out_size=nil)
       @pk.C_SignEncryptUpdate(@sess, data, out_size)
     end
@@ -497,9 +634,9 @@ module PKCS11
     # verification operation, processing another data part.
     #
     # Decryption and signature operations must both be active (they must have been initialized
-    # with C_DecryptInit and C_VerifyInit, respectively). This function may be called any
-    # number of times in succession, and may be interspersed with C_DecryptUpdate and
-    # C_VerifyUpdate calls.
+    # with {Session#C_DecryptInit} and {Session#C_VerifyInit}, respectively). This function may be called any
+    # number of times in succession, and may be interspersed with {Session#C_DecryptUpdate} and
+    # {Session#C_VerifyUpdate} calls.
     def C_DecryptVerifyUpdate(data, out_size=nil)
       @pk.C_DecryptVerifyUpdate(@sess, data, out_size)
     end
@@ -507,62 +644,122 @@ module PKCS11
     # Generates a secret key Object or set of domain parameters, creating a new
     # Object.
     #
-    # Returns key Object of the new created key.
+    # @param [Hash, Symbol, Integer, PKCS11::CK_MECHANISM] mechanism  used mechanism
+    # @param [Hash] template  Attributes of the key to create.
+    # @return [PKCS11::Object]  key Object of the new created key.
+    # @example generate 112 bit DES key
+    #     key = session.generate_key(:DES2_KEY_GEN,
+    #       {:ENCRYPT=>true, :WRAP=>true, :DECRYPT=>true, :UNWRAP=>true})
     def C_GenerateKey(mechanism, template={})
-      obj = @pk.C_GenerateKey(@sess, Session.hash_to_mechanism(mechanism), Session.hash_to_attributes(template))
+      obj = @pk.C_GenerateKey(@sess, to_mechanism(mechanism), to_attributes(template))
       Object.new @pk, @sess, obj
     end
     alias generate_key C_GenerateKey
 
     # Generates a public/private key pair, creating new key Object instances.
     #
-    # Returns an two-items array of new created public and private key Object.
+    # @param [Hash, Symbol, Integer, PKCS11::CK_MECHANISM] mechanism  used mechanism
+    # @param [Hash] pubkey_template  Attributes of the public key to create.
+    # @param [Hash] privkey_template  Attributes of the private key to create.
+    # @return [Array<PKCS11::Object>]  an two-items array of new created public and private key Object.
+    # @example
+    #     pub_key, priv_key = session.generate_key_pair(:RSA_PKCS_KEY_PAIR_GEN,
+    #       {:ENCRYPT=>true, :VERIFY=>true, :WRAP=>true, :MODULUS_BITS=>768, :PUBLIC_EXPONENT=>3},
+    #       {:SUBJECT=>'test', :ID=>"ID", :DECRYPT=>true, :SIGN=>true, :UNWRAP=>true})
     def C_GenerateKeyPair(mechanism, pubkey_template={}, privkey_template={})
-      objs = @pk.C_GenerateKeyPair(@sess, Session.hash_to_mechanism(mechanism), Session.hash_to_attributes(pubkey_template), Session.hash_to_attributes(privkey_template))
+      objs = @pk.C_GenerateKeyPair(@sess, to_mechanism(mechanism), to_attributes(pubkey_template), to_attributes(privkey_template))
       objs.map{|obj| Object.new @pk, @sess, obj }
     end
     alias generate_key_pair C_GenerateKeyPair
 
     # Wraps (i.e., encrypts) a private or secret key.
     #
-    # Returns the encrypted binary data.
+    # @param [Hash, Symbol, Integer, PKCS11::CK_MECHANISM] mechanism  used mechanism
+    # @param [PKCS11::Object] wrapping_key  wrapping key
+    # @param [PKCS11::Object] wrapped_key  key to wrap
+    # @return [String]  the encrypted binary data.
+    # @see Session#C_UnwrapKey
+    # @example Wrapping a secret key
+    #     wrapped_key_value = session.wrap_key(:DES3_ECB, secret_key, secret_key)
+    # @example Wrapping a private key
+    #     wrapped_key_value = session.wrap_key({:DES3_CBC_PAD=>"\0"*8}, secret_key, rsa_priv_key)
     def C_WrapKey(mechanism, wrapping_key, wrapped_key, out_size=nil)
-      @pk.C_WrapKey(@sess, Session.hash_to_mechanism(mechanism), wrapping_key, wrapped_key, out_size)
+      @pk.C_WrapKey(@sess, to_mechanism(mechanism), wrapping_key, wrapped_key, out_size)
     end
     alias wrap_key C_WrapKey
 
     # Unwraps (i.e. decrypts) a wrapped key, creating a new private key or
     # secret key object.
     #
-    # Returns key Object of the new created key.
+    # @param [Hash, Symbol, Integer, PKCS11::CK_MECHANISM] mechanism  used mechanism
+    # @param [PKCS11::Object] wrapping_key  wrapping key
+    # @param [String] wrapped_key  key data of the wrapped key
+    # @return [PKCS11::Object]  key object of the new created key.
+    # @see Session#C_WrapKey
+    # @example
+    #     unwrapped_key = session.unwrap_key(:DES3_ECB, secret_key, wrapped_key_value,
+    #         :CLASS=>CKO_SECRET_KEY, :KEY_TYPE=>CKK_DES2, :ENCRYPT=>true, :DECRYPT=>true)
     def C_UnwrapKey(mechanism, wrapping_key, wrapped_key, template={})
-      obj = @pk.C_UnwrapKey(@sess, Session.hash_to_mechanism(mechanism), wrapping_key, wrapped_key, Session.hash_to_attributes(template))
+      obj = @pk.C_UnwrapKey(@sess, to_mechanism(mechanism), wrapping_key, wrapped_key, to_attributes(template))
       Object.new @pk, @sess, obj
     end
     alias unwrap_key C_UnwrapKey
 
     # Derives a key from a base key, creating a new key object.
     #
-    # Returns key Object of the new created key.
+    # @param [Hash, Symbol, Integer, PKCS11::CK_MECHANISM] mechanism  used mechanism
+    # @param [PKCS11::Object] base_key  key to derive
+    # @param [Hash] template  Attributes of the object to create.
+    # @return [PKCS11::Object]  key object of the new created key.
+    # @example Derive a AES key by XORing with some derivation data
+    #     deriv_data = "\0"*16
+    #     new_key = session.derive_key( {CKM_XOR_BASE_AND_DATA => {:pData => deriv_data}}, secret_key,
+    #       :CLASS=>CKO_SECRET_KEY, :KEY_TYPE=>CKK_AES, :VALUE_LEN=>16, :ENCRYPT=>true )
     def C_DeriveKey(mechanism, base_key, template={})
-      obj = @pk.C_DeriveKey(@sess, Session.hash_to_mechanism(mechanism), base_key, Session.hash_to_attributes(template))
+      obj = @pk.C_DeriveKey(@sess, to_mechanism(mechanism), base_key, to_attributes(template))
       Object.new @pk, @sess, obj
     end
     alias derive_key C_DeriveKey
 
-    # Mixes additional seed material into the token’s random number
+    # Mixes additional seed material into the token's random number
     # generator.
+    # @param [String] entropy data
+    # @return [PKCS11::Session]
     def C_SeedRandom(data)
       @pk.C_SeedRandom(@sess, data)
+      self
     end
     alias seed_random C_SeedRandom
     
     # Generates random or pseudo-random data.
     #
-    # Returns random or pseudo-random binary data of <tt>out_size</tt> bytes.
+    # @param [Integer] out_size
+    # @return [String]  random or pseudo-random binary data of <tt>out_size</tt> bytes.
     def C_GenerateRandom(out_size)
       @pk.C_GenerateRandom(@sess, out_size)
     end
     alias generate_random C_GenerateRandom
+    
+    # Obtains a copy of the cryptographic operations state of a session,
+    # encoded as a string of bytes.
+    # @return [String]
+    # @see Session#C_SetOperationState
+    def C_GetOperationState
+      @pk.C_GetOperationState(@sess)
+    end
+    alias get_operation_state C_GetOperationState
+
+    # Restores the cryptographic operations state of a session from a
+    # string of bytes obtained with {Session#C_GetOperationState}.
+    #
+    # @param [String] state  previously stored session state
+    # @param [PKCS11::Object]  encryption key for sessions stored without keys
+    # @param [PKCS11::Object]  authentication key for sessions stored without keys
+    # @return [PKCS11::Session]
+    def C_SetOperationState(state, enc_key=nil, auth_key=nil)
+      @pk.C_SetOperationState(@sess, state, enc_key||0, auth_key||0)
+      self
+    end
+    alias set_operation_state C_SetOperationState
   end
 end