class PKCS11::Object

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.

Public Instance Methods

C_CopyObject(template={}) click to toggle source

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

# 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
Also aliased as: copy
C_DestroyObject() click to toggle source

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]

# File lib/pkcs11/object.rb, line 157
def C_DestroyObject()
  @pk.C_DestroyObject(@sess, @obj)
  self
end
Also aliased as: destroy
C_GetAttributeValue(*template) click to toggle source

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.

@return [Array<PKCS11::CK_ATTRIBUTE>] Requested attributes with values.

@example

certificate.attributes :VALUE, :CLASS
 => [#<PKCS11::CK_ATTRIBUTE CKA_VALUE (17) value="0\x82...">, #<PKCS11::CK_ATTRIBUTE CKA_CLASS (0) value=1>]
# 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
Also aliased as: attributes
C_GetObjectSize() click to toggle source

Gets the size of an object in bytes. @return [Integer]

# File lib/pkcs11/object.rb, line 165
def C_GetObjectSize()
  @pk.C_GetObjectSize(@sess, @obj)
end
Also aliased as: size
C_SetAttributeValue(template={}) click to toggle source

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

@example

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

@return template

# File lib/pkcs11/object.rb, line 89
def C_SetAttributeValue(template={})
  @pk.C_SetAttributeValue(@sess, @obj, to_attributes(template))
  template
end
Also aliased as: attributes=
[](*attributes) click to toggle source

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

@param [String, Symbol, Integer, Array] attribute can be String or Symbol

of the attribute(s) constant or the attribute(s) number as Integer.

@return [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.

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
object[:MODULUS_BITS, :LABEL] # => [1024, "MyKey"]

See PKCS#11 for attribute definitions.

# 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) click to toggle source

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

@param [String, Symbol, Integer] attribute can be String or Symbol of the attribute constant

or the attribute value as Integer.

@param [String, Integer, Boolean, Array, nil] value value(s) the attribute(s) will be set to.

Following value conversations are done from Ruby to C:

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

@example

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

See PKCS#11 for attribute definitions. @return value

# 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
attributes(*template)
Alias for: C_GetAttributeValue
attributes=(template={})
Alias for: C_SetAttributeValue
copy(template={})
Alias for: C_CopyObject
destroy()
Alias for: C_DestroyObject
size()
Alias for: C_GetObjectSize
to_i()
Alias for: to_int
to_int() click to toggle source

The object handle. @return [Integer]

# File lib/pkcs11/object.rb, line 19
def to_int
  @obj
end
Also aliased as: to_i