Class: PKCS11::Library

Inherits:
Object
  • Object
show all
Defined in:
lib/pkcs11/library.rb,
ext/pk11.c

Overview

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 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.(:USER, "password")

Instance Method Summary collapse

Constructor Details

#initialize(*args) ⇒ Library

Load and initialize a pkcs11 dynamic library.

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)

Note: When using RubyInstaller-2.4+ on Windows it might be required to add the path of dependent DLLs to the DLL search path. This can be done by the RUBY_DLL_PATH environment variable. See github.com/oneclick/rubyinstaller2/wiki/For-gem-developers#user-content-dll-loading

Parameters:

  • so_path (String, nil) —

    Path to the *.so or *.dll file to load.

  • args (Hash, CK_C_INITIALIZE_ARGS) —

    A Hash or CK_C_INITIALIZE_ARGS instance with load params.



41
42
43
 
# File 'lib/pkcs11/library.rb', line 41

def initialize(so_path=nil, args={})
  unwrapped_initialize(so_path, args)
end

Instance Method Details

#active_slots ⇒ Array<Slot>

Obtain an array of Slot objects in the system with a token present.

Returns:



86
87
88
 
# File 'lib/pkcs11/library.rb', line 86

def active_slots
  slots(true)
end

#all_slots ⇒ Array<Slot>

Obtain an array of Slot objects in the system regardless if a token is present.

Returns:



92
93
94
 
# File 'lib/pkcs11/library.rb', line 92

def all_slots
  slots(false)
end

#C_GetInfo ⇒ CK_INFO Also known as: info

Returns general information about Cryptoki.

Returns:



63
64
65
 
# File 'lib/pkcs11/library.rb', line 63

def C_GetInfo
  unwrapped_C_GetInfo
end

#C_GetSlotList(tokenPresent = false) ⇒ Array<Slot> Also known as: slots

Obtain an array of Slot objects in the system.

Parameters:

  • tokenPresent (true, false) (defaults to: false) —

    indicates whether the list obtained includes only those slots with a token present (true), or all slots (false);

Returns:



76
77
78
79
80
81
 
# File 'lib/pkcs11/library.rb', line 76

def C_GetSlotList(tokenPresent=false)
  slots = unwrapped_C_GetSlotList(tokenPresent)
  slots.map{|slot|
    Slot.new self, slot
  }
end

#C_Initialize(args = nil) ⇒ Object

Initialize a pkcs11 dynamic library.

Parameters:

  • args (Hash, CK_C_INITIALIZE_ARGS) (defaults to: nil) —

    A Hash or CK_C_INITIALIZE_ARGS instance with load params.



49
50
51
52
53
54
55
56
57
58
 
# File 'lib/pkcs11/library.rb', line 49

def C_Initialize(args=nil)
  case args
    when Hash
      pargs = CK_C_INITIALIZE_ARGS.new
      args.each{|k,v| pargs.send("#{k}=", v) }
    else
      pargs = args
  end
  unwrapped_C_Initialize(pargs)
end

#C_WaitForSlotEvent(flags = 0) ⇒ Slot? Also known as: wait_for_slot_event

Waits for a slot event, such as token insertion or token removal, to occur.

Parameters:

  • flags (Integer) (defaults to: 0) —

    determines whether or not the C_WaitForSlotEvent call blocks (i.e., waits for a slot event to occur); At present, the only flag defined for use in the flags argument is PKCS11::CKF_DONT_BLOCK

Returns:

  • (Slot, nil) —

    the slot that the event occurred in; nil if no event occured (CKR_NO_EVENT)



104
105
106
107
 
# File 'lib/pkcs11/library.rb', line 104

def C_WaitForSlotEvent(flags=0)
  slot = unwrapped_C_WaitForSlotEvent(flags)
  slot ? Slot.new(self, slot) : nil
end

#close ⇒ Object

Finalize and unload the library. If not called explicit, the library is freed by the GC.



111
112
113
114
 
# File 'lib/pkcs11/library.rb', line 111

def close
  self.C_Finalize
  self.unload_library
end

#unwrapped_C_Initialize ⇒ Object 



45
 
# File 'lib/pkcs11/library.rb', line 45

alias unwrapped_C_Initialize C_Initialize

#unwrapped_C_WaitForSlotEvent ⇒ Object 



96
 
# File 'lib/pkcs11/library.rb', line 96

alias unwrapped_C_WaitForSlotEvent C_WaitForSlotEvent

#vendor_all_attribute_names ⇒ Object

Return an array of all known CKA_* attributes as String. This method could be overloaded for vendor specific extensions.



127
128
129
 
# File 'lib/pkcs11/library.rb', line 127

def vendor_all_attribute_names
  return ATTRIBUTES.values
end

#vendor_const_get(name) ⇒ Integer

Return the value of a named constant. Used for CKA_* and CKM_* . This method could be overloaded for vendor specific extensions.

Parameters:

  • name (String) —

    Name of the constant

Returns:

  • (Integer) —

    Value of the constant



121
122
123
 
# File 'lib/pkcs11/library.rb', line 121

def vendor_const_get(name)
  PKCS11.const_get(name)
end

#vendor_mechanism_parameter_struct(mech) ⇒ PKCS11::CStruct

Return the parameter struct of a given mechanism. This method could be overloaded for vendor specific extensions.

Parameters:

  • mech (Integer) —

    Mechanism

Returns:



136
137
138
 
# File 'lib/pkcs11/library.rb', line 136

def vendor_mechanism_parameter_struct(mech)
  Helper::MechanismParameters[mech]
end