iaik.pkcs.pkcs11.objects

Class PKCS11Object

java.lang.Object

iaik.pkcs.pkcs11.objects.PKCS11Object

Direct Known Subclasses:

GenericTemplate, HardwareFeature, Mechanism, Storage

public class PKCS11Object
extends Object

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.

Version:

1.0

Author:

Karl Scheibelhofer

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static interface	PKCS11Object.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	PKCS11Object.VendorDefinedObjectBuilder If an application uses vendor defined objects, it must implement this interface and install such an object handler using setVendorDefinedObjectBuilder.

Field Summary

Fields

Modifier and Type	Field and Description
protected Hashtable<Long,Attribute>	attributeTable Contains all attribute objects an object possesses.
protected ObjectClassAttribute	objectClass The class type of this object.
protected static Hashtable<Long,String>	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 PKCS11Object.VendorDefinedObjectBuilder	vendorObjectBuilder The currently set vendor defined object builder, or null.

Constructor Summary

Constructors

Modifier	Constructor and Description
	PKCS11Object() The default constructor.
protected	PKCS11Object(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

Modifier and Type	Method and Description
protected void	allocateAttributes() Allocates the attribute objects for this class and adds them to the attribute table.
boolean	equals(Object otherObject) Compares all member variables of this object with the other object.
Attribute	getAttribute(long attribute) Gets the attribute.
Hashtable<Long,Attribute>	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.
protected static void	getAttributeValues(Session session, long objectHandle, Attribute[] attributes) This method reads the attributes in a similar way as getAttributeValue(iaik.pkcs.pkcs11.Session, long, iaik.pkcs.pkcs11.objects.Attribute), but a complete array at once.
static PKCS11Object	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<sun.security.pkcs11.wrapper.CK_ATTRIBUTE>	getSetAttributes() Returns the PKCS#11 attributes of this object.
static sun.security.pkcs11.wrapper.CK_ATTRIBUTE[]	getSetAttributes(PKCS11Object object, VendorCodeConverter vendorCodeConverter) Returns the PKCS#11 attributes of an object.
protected static PKCS11Object	getUnknownObject(Session session, long objectHandle) Try to create an object which has no or an unknown object class attribute.
static PKCS11Object.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.
void	putAttribute(long attribute, Object value) Allows for putting attributes into the table without knowing the Attribute at compile-time.
protected static void	putAttributesInTable(PKCS11Object 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	removeAttribute(long attribute) Removes the attribute.
void	setObjectHandle(long objectHandle) Sets the object handle of the underlying PKCS#11 object on the token.
static void	setVendorDefinedObjectBuilder(PKCS11Object.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.
String	toString() Returns a string representation of the current object.
String	toString(boolean newline, boolean withName, String indent) Returns a string representation of the current object.

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

vendorObjectBuilder

protected static PKCS11Object.VendorDefinedObjectBuilder vendorObjectBuilder

The currently set vendor defined object builder, or null.

objectClassNames

protected static Hashtable<Long,String> objectClassNames

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

attributeTable

protected Hashtable<Long,Attribute> attributeTable

Contains all attribute objects an object possesses. 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

PKCS11Object

public PKCS11Object()

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

PKCS11Object

protected PKCS11Object(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.

Method Detail

getInstance

public static PKCS11Object 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, 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.

getUnknownObject

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

Try to create an object which has no or an unknown 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 PKCS11Object .

Parameters:

session - The session to use.

objectHandle - The handle of the object

Returns:

A new PKCS11Object.

Throws:

TokenException - If no object could be created.

setVendorDefinedObjectBuilder

public static void setVendorDefinedObjectBuilder(PKCS11Object.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.

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

getVendorDefinedObjectBuilder

public static PKCS11Object.VendorDefinedObjectBuilder getVendorDefinedObjectBuilder()

Get the currently set vendor-defined object builder.

Returns:

The currently set vendor-defined object builder or null if none is set.

putAttributesInTable

protected static void putAttributesInTable(PKCS11Object 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.

Parameters:

object - The object to handle.

allocateAttributes

protected void allocateAttributes()

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

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.

Overrides:

equals in class Object

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.

getAttributeTable

public Hashtable<Long,Attribute> 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.

putAttribute

public void putAttribute(long attribute,
                         Object value)
                  throws UnsupportedAttributeException

Allows for putting attributes into the table without knowing the Attribute at compile-time.

Parameters:

attribute - the attribute identifier as a long value

value - the value

Throws:

UnsupportedAttributeException - the specified attribute identifier is not available for this PKCS11Object instance.

ClassCastException - the given value type is not valid for this Attribute instance.

getAttribute

public Attribute getAttribute(long attribute)

Gets the attribute.

Parameters:

attribute - the attribute identifier as a long value

Returns:

the attribute

removeAttribute

public void removeAttribute(long attribute)

Removes the attribute.

Parameters:

attribute - the attribute identifier as a long value

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.

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.

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.

getSetAttributes

public Vector<sun.security.pkcs11.wrapper.CK_ATTRIBUTE> getSetAttributes()

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.

getSetAttributes

public static sun.security.pkcs11.wrapper.CK_ATTRIBUTE[] getSetAttributes(PKCS11Object object,
                                                                          VendorCodeConverter vendorCodeConverter)
                                                                   throws PKCS11Exception

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.

vendorCodeConverter - The vendor code converter.

Returns:

An array of CK_ATTRIBUTE objects. null, if the given object is null.

Throws:

PKCS11Exception - If setting the attribute values.

hashCode

public int hashCode()

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

Overrides:

hashCode in class Object

Returns:

The hash code of this object.

readAttributes

public void readAttributes(Session session)
                    throws TokenException

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

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.

Throws:

TokenException - If getting the attributes failed.

toString

public String toString()

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

Overrides:

toString in class Object

Returns:

A string presentation of this object for debugging output.

toString

public String toString(boolean newline,
                       boolean withName,
                       String indent)

Returns a string representation of the current object. Some parameters can be set to manipulate the output. The output is only for debugging purposes and should not be used for other purposes.

Parameters:

newline - true if the output should start in a new line

withName - true if the type of the attribute should be returned too

indent - the indent to be used

Returns:

A string presentation of this object for debugging output.

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

getAttributeValues

protected static void getAttributeValues(Session session,
                                         long objectHandle,
                                         Attribute[] attributes)
                                  throws PKCS11Exception

This method reads the attributes in a similar way as getAttributeValue(iaik.pkcs.pkcs11.Session, long, iaik.pkcs.pkcs11.objects.Attribute), but a complete array at once. This can lead to performance improvements. If reading all attributes at once fails, it tries to read each attributes individually.

Parameters:

session - The session to use for reading the attributes.

objectHandle - The handle of the object which contains the attributes.

attributes - The objects specifying the attribute types (see Attribute.getType()) and receiving the attribute values (see Attribute.setCkAttribute(CK_ATTRIBUTE)).

Throws:

PKCS11Exception - If getting the attributes failed.