Ace:V2 IMS
From Adapt
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