Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| IAIK PKCS#11 Wrapper version 1.2.16
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## iaik.pkcs.pkcs11.objects
Class Object

    java.lang.Object
      iaik.pkcs.pkcs11.objects.Object

All Implemented Interfaces:
  Cloneable

Direct Known Subclasses:
  GenericTemplate, HardwareFeature, Storage

public class Object
extends Object
implements Cloneable

An object of this class represents an object as defined by PKCS#11. An object is of a specific class: DATA, CERTIFICATE, PUBLIC_KEY, PRIVATE_KEY, SECRET_KEY, HW_FEATURE, DOMAIN_PARAMETERS or VENDOR_DEFINED. If an application needs to use vendor-defined objects, it must set a VendorDefinedObjectBuilder using the setVendorDefinedObjectBuilder method.

Invariants
  (attributeTable_ <> null) and (objectClass_ <> null)

Nested Class Summary
`static interface` | `Object.ObjectClass` This interface defines the available object classes as defined by PKCS#11: DATA, CERTIFICATE, PUBLIC_KEY, PRIVATE_KEY, SECRET_KEY, HW_FEATURE, DOMAIN_PARAMETERS or VENDOR_DEFINED.
`static interface` | `Object.VendorDefinedObjectBuilder` If an application uses vendor defined objects, it must implement this interface and install such an object handler using setVendorDefinedObjectBuilder.

Field Summary
`protected Hashtable` | `attributeTable_` Contains all attribute objects an object posesses.
`protected ObjectClassAttribute` | `objectClass_` The class type of this object.
`protected static Hashtable` | `objectClassNames_` A table holding string representations for all known key types.
`protected long` | `objectHandle_` The object handle as given from the PKCS#11 driver.
`protected static Object.VendorDefinedObjectBuilder` | `vendorObjectBuilder_` The currently set vendor defined object builder, or null.

Constructor Summary
`` | `Object()` The default constructor.
`protected` | `Object(Session session, long objectHandle)` The subclasses that are used to create objects by reading the attributes from the token should call this super-constructor first.

Method Summary
`protected void` | `allocateAttributes()` Allocates the attribute objects for this class and adds them to the attribute table.
`Object` | `clone()` Create a (deep) clone of this object.
`boolean` | `equals(Object otherObject)` Compares all member variables of this object with the other object.
`Hashtable` | `getAttributeTable()` Return the table that contains all attributes of this object.
`protected static void` | `getAttributeValue(Session session, long objectHandle, Attribute attribute)` This method reads the attribute specified by `attribute` from the token using the given `session`.
`static Object` | `getInstance(Session session, long objectHandle)` The object creation mechanism of ObjectAccess uses this method to create an instance of an PKCS#11 object.
`LongAttribute` | `getObjectClass()` Gets the object class attribute of the PKCS#11 object.
`static String` | `getObjectClassName(Long objectClass)` Get the given object class as string.
`long` | `getObjectHandle()` Gets the object handle of the underlying PKCS#11 object on the token.
`Vector` | `getSetAttributes()` This method returns the PKCS#11 attributes of this object.
`static CK_ATTRIBUTE[]` | `getSetAttributes(Object object)` This method returns the PKCS#11 attributes of an object.
`protected static Object` | `getUnknownObject(Session session, long objectHandle)` Try to create an object which has no or an unkown object class attribute.
`static Object.VendorDefinedObjectBuilder` | `getVendorDefinedObjectBuilder()` Get the currently set vendor-defined object builder.
`int` | `hashCode()` The overriding of this method should ensure that the objects of this class work correctly in a hashtable.
`protected static void` | `putAttributesInTable(Object object)` Put all attributes of the given object into the attributes table of this object.
`void` | `readAttributes(Session session)` Read the values of the attributes of this object from the token.
`void` | `setObjectHandle(long objectHandle)` Sets the object handle of the underlying PKCS#11 object on the token.
`static void` | `setVendorDefinedObjectBuilder(Object.VendorDefinedObjectBuilder builder)` Set a vendor-defined object builder that should be called to create an instance of an vendor-defined PKCS#11 object; i.e. an instance of a vendor defined sub-class of this class.
`String` | `toString()` This method returns a string representation of the current object.

Methods inherited from class java.lang.Object
`finalize, getClass, notify, notifyAll, wait, wait, wait`

Field Detail

### vendorObjectBuilder_

    protected static Object.VendorDefinedObjectBuilder vendorObjectBuilder_

  The currently set vendor defined object builder, or null.

### objectClassNames_

    protected static Hashtable objectClassNames_

  A table holding string representations for all known key types. Table key is the key type as Long object.

### attributeTable_

    protected Hashtable attributeTable_

  Contains all attribute objects an object posesses. No matter if an attribute is set present or not, it is part of this collection. The key of this table is the attribute type as Long.

### objectClass_

    protected ObjectClassAttribute objectClass_

  The class type of this object. One of ObjectClass, or one that has a bigger value than VENDOR_DEFINED.

### objectHandle_

    protected long objectHandle_

  The object handle as given from the PKCS#11 driver.

Constructor Detail

### Object

    public Object()

  The default constructor. An application use this constructor to instanciate an object that serves as a template. It may also be useful for working with vendor-defined objects.

Preconditions
Postconditions

### Object

    protected Object(Session session,
                     long objectHandle)
              throws TokenException

  The subclasses that are used to create objects by reading the attributes from the token should call this super-constructor first. The getInstance method also uses this constructor, if it can not determine the class type of the object or if the type class is a vendor defined one.

Parameters:
  `session` - The session to use for reading attributes. This session must have the appropriate rights; i.e. it must be a user-session, if it is a private object.
  `objectHandle` - The object handle as given from the PKCS#111 module.
Throws:
  `TokenException` - If getting the attributes failed.
Preconditions
  (session <> null)
Postconditions

Method Detail

### getInstance

    public static Object getInstance(Session session,
                                     long objectHandle)
                              throws TokenException

  The object creation mechanism of ObjectAccess uses this method to create an instance of an PKCS#11 object. This method reads the object class attribute and calls the getInstance method of the according sub-class. If the object class is a vendor defined it uses the VendorDefinedObjectBuilder set by the application. If no object could be constructed, this method returns null.

  Parameters:
    `session` - The session to use for reading attributes. This session must have the appropriate rights; i.e. it must be a user-session, if it is a private object.
    `objectHandle` - The object handle as given from the PKCS#111 module.
  Returns:
    The object representing the PKCS#11 object. The returned object can be casted to the according sub-class.
  Throws:
    `TokenException` - If getting the attributes failed.
  Preconditions
    (session <> null)
  Postconditions
    (result <> null)

### getUnknownObject

    protected static Object getUnknownObject(Session session,
                                             long objectHandle)
                                      throws TokenException

  Try to create an object which has no or an unkown object class attribute. This implementation will try to use a vendor defined object builder, if such has been set. If this is impossible or fails, it will create just a simple `Object` .

  Parameters:
    `session` - The session to use.
    `objectHandle` - The handle of the object
  Returns:
    A new Object.
  Throws:
    `TokenException` - If no object could be created.
  Preconditions
    (session <> null)
  Postconditions
    (result <> null)

### setVendorDefinedObjectBuilder

    public static void setVendorDefinedObjectBuilder(Object.VendorDefinedObjectBuilder builder)

  Set a vendor-defined object builder that should be called to create an instance of an vendor-defined PKCS#11 object; i.e. an instance of a vendor defined sub-class of this class.

  Parameters:
    `builder` - The vendor-defined object builder. Null to clear any previously installed vendor-defined builder.
  Preconditions
  Postconditions

### getObjectClassName

    public static String getObjectClassName(Long objectClass)

  Get the given object class as string.

  Parameters:
    `objectClass` - The object class to get as string.
  Returns:
    A string denoting the object class; e.g. "Private Key".
  Preconditions
    (objectClass <> null)
  Postconditions
    (result <> null)

### getVendorDefinedObjectBuilder

    public static Object.VendorDefinedObjectBuilder getVendorDefinedObjectBuilder()

  Get the currently set vendor-defined object builder.

  Returns:
    The currently set vendor-defined object builder or null if none is set.
  Preconditions
  Postconditions

### putAttributesInTable

    protected static void putAttributesInTable(Object object)

  Put all attributes of the given object into the attributes table of this object. This method is only static to be able to access invoke the implementation of this method for each class separately (see use in clone()).

  Parameters:
    `object` - The object to handle.
  Preconditions
    (object <> null)
  Postconditions

### allocateAttributes

    protected void allocateAttributes()

  Allocates the attribute objects for this class and adds them to the attribute table.

  Preconditions
  Postconditions

### clone

    public Object clone()

  Create a (deep) clone of this object.

  Returns:
    A clone of this object.
  Preconditions
  Postconditions
    (result <> null) and (result instanceof Attribute) and (result.equals(this))

### equals

    public boolean equals(Object otherObject)

  Compares all member variables of this object with the other object. Returns only true, if all are equal in both objects.

  Parameters:
    `otherObject` - The other object to compare to.
  Returns:
    True, if other is an instance of this class and all member variables of both objects are equal. False, otherwise.
  Preconditions
  Postconditions

### getAttributeTable

    public Hashtable getAttributeTable()

  Return the table that contains all attributes of this object. The key to this table is the attribute type as Long object.

  Returns:
    The table of all attributes of this object. Key is the attribute type as Long. This table is unmodifiable.
  Preconditions
  Postconditions
    (result <> null)

### getObjectHandle

    public long getObjectHandle()

  Gets the object handle of the underlying PKCS#11 object on the token.

  Returns:
    The object handle of the corresponding PKCS#11 object.
  Preconditions
  Postconditions

### setObjectHandle

    public void setObjectHandle(long objectHandle)

  Sets the object handle of the underlying PKCS#11 object on the token. An application will rarely need to call this method itself during normal operation.

  Parameters:
    `objectHandle` - The object handle of the corresponding PKCS#11 object.
  Preconditions
  Postconditions

### getObjectClass

    public LongAttribute getObjectClass()

  Gets the object class attribute of the PKCS#11 object. Its value must be one of those defined in the ObjectClass interface or one with an value bigger than ObjectClass.VENDOR_DEFINED.

  Returns:
    The object class attribute.
  Preconditions
  Postconditions

### getSetAttributes

    public Vector getSetAttributes()

  This method returns the PKCS#11 attributes of this object. The collection contains CK_ATTRIBUTE objects, one for each present attribute of this object; e.g. for each attribute that has a set value (which might be sensitive). The array representation of this collection can be used directly as input for the PKCS#11 wrapper. The Session class uses this method for various object operations.

  Returns:
    An collection of CK_ATTRIBUTE objects.
  Preconditions
  Postconditions
    (result <> null)

### hashCode

    public int hashCode()

  The overriding of this method should ensure that the objects of this class work correctly in a hashtable.

  Returns:
    The hash code of this object.
  Preconditions
  Postconditions

### readAttributes

    public void readAttributes(Session session)
                        throws TokenException

  Read the values of the attributes of this object from the token.

  Parameters:
    `session` - The session handle to use for reading attributes. This session must have the appropriate rights; i.e. it must be a user-session, if it is a private object.
  Throws:
    `TokenException` - If getting the attributes failed.
  Preconditions
    (session <> null)
  Postconditions

### toString

    public String toString()

  This method returns a string representation of the current object. The output is only for debugging purposes and should not be used for other purposes.

  Returns:
    A string presentation of this object for debugging output.
  Preconditions
  Postconditions
    (result <> null)

### getSetAttributes

    public static CK_ATTRIBUTE[] getSetAttributes(Object object)
                                           throws PKCS11Exception

  This method returns the PKCS#11 attributes of an object. The array contains CK_ATTRIBUTE objects, one for each set attribute of this object; e.g. for each attribute that is not null. The array can be used directly as input for the PKCS#11 wrapper. The Session class uses this method for various object operations.

  Parameters:
    `object` - The iaik.pkcs.pkcs11.object.Object object to get the attributes from.
  Returns:
    An array of CK_ATTRIBUTE objects. null, if the given object is null.
  Throws:
    `PKCS11Exception` - If setting the attribute values.
  Preconditions
  Postconditions

### getAttributeValue

    protected static void getAttributeValue(Session session,
                                            long objectHandle,
                                            Attribute attribute)
                                     throws PKCS11Exception

  This method reads the attribute specified by `attribute` from the token using the given `session`. The object from which to read the attribute is specified using the `objectHandle`. The `attribute` will contain the results. If the attempt to read the attribute returns `CKR_ATTRIBUTE_TYPE_INVALID`, this will be indicated by setting `Attribute.setPresent(boolean)` to `false`. It CKR_ATTRIBUTE_SENSITIVE is returned, the attribute object is marked as present (by callign `Attribute.setPresent(boolean)` with `true`), and in addition as sensitive by calling `Attribute.setSensitive(boolean)` with `true`.

  Parameters:
    `session` - The session to use for reading the attribute.
    `objectHandle` - The handle of the object which contains the attribute.
    `attribute` - The object specifying the attribute type (see `Attribute.getType()`) and receiving the attribute value (see `Attribute.setCkAttribute(CK_ATTRIBUTE)`).
  Throws:
    `PKCS11Exception` - If getting the attribute failed.
  Preconditions
    (session <> null) and (attribute <> null)
  Postconditions

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| IAIK PKCS#11 Wrapper version 1.2.16
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

IAIK JavaSecurity Website http://jce.iaik.tugraz.at/
IAIK at Graz University of Technology, Austria, Europe
Copyright 2001-2002, IAIK, Graz University of Technology, Inffeldgasse 16a, 8010 Graz, Austria. All Rights Reserved.