Ace:V2 IMS

Token Class

Submitting a request for an integrity token to the IMS requires specifying the name of a Token Class. This Token Class defines the hash algorithm, digest service provider, and any additional parameters to be used in constructing the hash tree. Token Classes are defined by the IMS administrator. A request may or may not be bundled into one hash tree using other pending requests. All hash trees for a Token Class are linked to the root node of previous hash tree generated. If no previous hash trees exist, the first tree generated is linked to an arbitrary value. The attributes for a Token Class are as follows:

Attribute	Type	Description
Name	String	Required, Unique. Name used to reference this Token Class.
Algorithm	String	Required. Name of the hash algorithm to be used in generating values in the hash tree
Provider	Registered Provider	Required. The security provider of the hash algorithm implementation. Providers must be registered with the IMS before being used
Tree Order	Integer	Required. Minimum number of children per tree node in the hash tree. Must be greater than or equal to 2. Default value of 2.
Min Hashes Per Round	Integer	Required. Minimum number of tree leaves allowed when building the tree. Must be greater than or equal to 2. If there are fewer than this number of requests, random values will be generated to flush out the tree. Default value of 8.

Registered Provider

A security provider must be registered with the IMS by an administrator before it is available for use in a Token Class. The attributes for a Registered Provider are as follows:

Attribute	Description
Name	String	Required, Unique. Name used to reference this Registered Provider.
Provider Class	String	Required. Fully qualified class name of the security provider.
Default Provider	Boolean	Required. True if this security provider is bundled with the JDK, otherwise false.

On server startup, the IMS will try to instantiate all Registered Providers and will reject any that fail.

Integrity Token Request

Right now, there is only one service for requesting an integrity token. This is a bulk request that uses private hash tree instances that are not shared with other requests. The trees are immediately generated, the root hash values are committed, and tokens are issued back to the client. The format for the request is a list of Hash Requests as defined below:

Hash Request

Attribute	Type	Description
Request Identifier	Integer	Required, Unique. Identifier supplied by the client used to match up to the corresponding response object.
Token Class Name	String	Required. Name of the Token Class to be used in servicing the request.
Hash	byte[]	Required. Hash value to register.

The service should only throw an exception visible to the client if the request has no request objects. The service will return a list of Hash Responses and is guaranteed to contain the same number of responses as there were supplied in the request. The order may not be the same and the identifier specified in the request must be used to match up the corresponding identifier in the response. The format for the Hash Response is as follows:

Hash Response

Attribute	Type	Description
Request Identifier	Integer	Required, Unqiue. Identifies the request object that this object is in response to.
Status Code	Integer	Required. Specifies if the request was successfully fulfilled, and if not, the reason that it was not. See [[ACE2-StatusCodes][Status Codes]] for a list of defined status codes.
Token	Token	Required if Status Code is 100, otherwise empty. The generated integrity token.

The returned Token is defined as follows:

Token

Attribute	Type	Description
Token Class Name	String	Required. Name of the Token Class that serviced this request.
Timestamp	Timestamp	Required. Date and time the hash tree was generated. All tokens in the same hash tree will have the same timestamp, and the committed hash round in the IMS will also have this value.
Round	Integer	Required. The ordinal position of the generated tree in the linked list of all hash rounds generated for this Token Class.
Proof	Proof	Required. Proof object used to validate the supplied hash at a later time.

The Proof is defined as the following:

Proof

Attribute	Type	Description
Hash Algorithm	String	Required. Name of the hash algorithm that was used to build the hash tree.
Hash Provider	String	Required. Name of the security provider that implemented the hash algorithm.
Leaf Hash	byte[]	Required. The hash that was presented to the IMS for this integrity token.
Proof Nodes	List of Proof Node	Required. The partial node values needed to generate the root hash value following the path from the leaf node.

The Proof Node is defined as the following:

Proof Node

Attribute	Type	Description
Index	Integer	Required. Ordinal position of this node in parent's list of children nodes.
Proof Hashes	List of Proof Hash	Required. The children hash values for this node. Does not include nodes of the traversal path.

The Proof Hash is defined as the following:

Proof Hash

Attribute	Type	Description
Index	Integer	Required. Ordinal position of this node in the parent's list of children nodes.
Hash	byte[]	Required. Hash value.

-- Main.MikeMcGann - 10 Oct 2007