Class: PKCS11::Object

Inherits:
Object
  • Object
show all
Defined in:
lib/pkcs11/object.rb

Overview

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.

Instance Method Summary collapse

Instance Method Details

#[](*attributes) ⇒ String, ...

Get the value of one or several attributes of the object.

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”.

See PKCS#11 for attribute definitions.

Examples:

object[:VALUE] # => "\000\000\000\000\000\000\000\000"
object[:MODULUS_BITS] # => 768
object[:MODULUS_BITS, :LABEL] # => [1024, "MyKey"]

Parameters:

  • attribute (String, Symbol, Integer, Array) —

    can be String or Symbol of the attribute(s) constant or the attribute(s) number as Integer.

Returns:

  • (String, Integer, Boolean, Array, nil) —

    the attribute value as String, Integer or true/false depending on the attribute type. If called with more than one parameter or with an Array, a Array of attribute values is returned.



48
49
50
51
52
53
54
55
 
# File 'lib/pkcs11/object.rb', line 48

def [](*attributes)
  attrs = C_GetAttributeValue( attributes.flatten )
  if attrs.length>1 || attributes.first.kind_of?(Array)
    attrs.map(&:value)
  else
    attrs.first.value unless attrs.empty?
  end
end

#[]=(*attributes) ⇒ Object

Modifies the value of one or several attributes of the object.

Following value conversations are done from Ruby to C:

true   -> 0x01
false  -> 0x00
nil    -> NULL pointer
Integer-> binary encoded unsigned long

See PKCS#11 for attribute definitions.

Examples:

object[:VALUE] = "\000\000\000\000\000\000\000\000"
object[:MODULUS_BITS] = 768
object[:MODULUS_BITS, :LABEL] = 1024, 'MyKey'

Parameters:

  • attribute (String, Symbol, Integer) —

    can be String or Symbol of the attribute constant or the attribute value as Integer.

  • value (String, Integer, Boolean, Array, nil) —

    value(s) the attribute(s) will be set to.

Returns:

  • value

Raises:

  • (ArgumentError) 


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

def []=(*attributes)
  values = attributes.pop
  values = [values] unless values.kind_of?(Array)
  raise ArgumentError, "different number of attributes to set (#{attributes.length}) and given values (#{values.length})" unless attributes.length == values.length
  map = values.each.with_index.inject({}){|s, v| s[attributes[v[1]]] = v[0]; s }
  C_SetAttributeValue( map )
end

#C_CopyObject(template = {}) ⇒ PKCS11::Object Also known as: copy

Copies an object, creating a new object for the copy.

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.

Parameters:

  • template (Hash) (defaults to: {})

Returns:



146
147
148
149
 
# File 'lib/pkcs11/object.rb', line 146

def C_CopyObject(template={})
  handle = @pk.C_CopyObject(@sess, @obj, to_attributes(template))
  Object.new @pk, @sess, handle
end

#C_DestroyObject ⇒ PKCS11::Object Also known as: destroy

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.

Returns:



157
158
159
160
 
# File 'lib/pkcs11/object.rb', line 157

def C_DestroyObject()
  @pk.C_DestroyObject(@sess, @obj)
  self
end

#C_GetAttributeValue(*template) ⇒ Array<PKCS11::CK_ATTRIBUTE> Also known as: attributes

Obtains the value of one or more attributes of the object in a single call.

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.

Examples:

certificate.attributes :VALUE, :CLASS
 => [#<PKCS11::CK_ATTRIBUTE CKA_VALUE (17) value="0\x82...">, #<PKCS11::CK_ATTRIBUTE CKA_CLASS (0) value=1>]

Parameters:

  • attribute (Array<String, Symbol, Integer>, Hash, String, Integer) —

    attribute names whose values should be returned

Returns:



109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
 
# File 'lib/pkcs11/object.rb', line 109

def C_GetAttributeValue(*template)
  case template.length
    when 0
      return @pk.vendor_all_attribute_names.map{|attr|
        begin
          attributes(@pk.vendor_const_get(attr))
        rescue PKCS11::Error
        end
      }.flatten.compact
    when 1
      template = template[0]
  end
  template = to_attributes template
  @pk.C_GetAttributeValue(@sess, @obj, template)
end

#C_GetObjectSize ⇒ Integer Also known as: size

Gets the size of an object in bytes.

Returns:

  • (Integer) 


165
166
167
 
# File 'lib/pkcs11/object.rb', line 165

def C_GetObjectSize()
  @pk.C_GetObjectSize(@sess, @obj)
end

#C_SetAttributeValue(template = {}) ⇒ Object Also known as: attributes=

Modifies the value of one or more attributes of the object in a single call.

Examples:

object.attributes = {SUBJECT:  cert_subject, PKCS11::CKA_VALUE => cert_data}

Returns:

  • template



89
90
91
92
 
# File 'lib/pkcs11/object.rb', line 89

def C_SetAttributeValue(template={})
  @pk.C_SetAttributeValue(@sess, @obj, to_attributes(template))
  template
end

#to_int ⇒ Integer Also known as: to_i

The object handle.

Returns:

  • (Integer) 


19
20
21
 
# File 'lib/pkcs11/object.rb', line 19

def to_int
  @obj
end