Previous section.

Common Security: CDSA and CSSM, Version 2 (with corrigenda)
Copyright © 2000 The Open Group

Data Structures

Object Pointers

Many of the ISL objects form a hierarchical "contains" relationship. The larger, containing object defines an iterator object that enumerates the smaller objects. The smaller object defines a function that returns the larger object that contains it. A table summarizing the relationships among the ISL object types is provided at the end of this section.

Iterator Objects

Iterators are "disposable" objects created from verified objects that contain subordinate objects. They enumerate the manifest sections, or the attributes of the certificate, signature, or manifest section. The set of object references is determined when the iterator is created. Subsequent changes to the object from which it is created do not affect the set, the number of elements, or position in the iterator (this is not a problem in the embedded version of the library, which cannot change objects). Of course, many iterators can be used to traverse the same set of object references independently.

The "get" function for each iterator object varies with each type of subordinate object referenced and returned by the function.

The object is recycled after the "get" function indicates that there are no more subordinate object references to enumerate.

Iterator objects are objects in their own right, but they are documented with their containing object.


typedef const void *ISL_ITERATOR_PTR;


Verified Signature Root Object

A verified signature object is returned as the result of verifying a signature root. (This differs from the object type returned by the EISL_VerifySignatureRoot() function.)

Valid operations on this object are to create an iterator to return manifest sections, or search for a specific signed object. The attributes of the unverified object have been verified, but the object itself has not been verified.

One can also create an iterator to enumerate the verified attributes of the signature itself.


typedef const void *ISL_VERIFIED_SIGNATURE_ROOT_PTR;


Verified Certificate Chain Object

A verified certificate chain object is returned by functions that construct and verify a certificate chain. A certificate chain begins with the trusted signer certificate and ends with the certificate of the signer found in a signature block. Valid operations on this object are to return an array of verified certificate objects. This object can be contained in a Verified Signature Root Object.

typedef const void *ISL_VERIFIED_CERTIFICATE_CHAIN_PTR;


Verified Certificate Object

A verified certificate object is returned as a result of requesting the verified certificates in a certificate chain. Valid operations on this object include obtaining public key and other attributes stored in the certificate. A verified certificate object cannot be modified. This object can be contained in a Verified Certificate Chain Object.

typedef const void *ISL_VERIFIED_CERTIFICATE_PTR;


Manifest Section Object

A manifest section object is returned by an iterator that was created from a verified root signature. For each signed object, there is a manifest section which describes its attributes and how to retrieve and verify it.

Valid operations on this object are to verify the signed object, and to create an iterator which returns attributes of the signed object. Using the iterator, it is possible to check the attributes of a signed object prior to verifying the object itself. The manifest section object is always contained in a Verified Signature Root Object.


typedef const void *ISL_MANIFEST_SECTION_PTR;


Verified Module Object

A verified module object is returned as a result of verifying the credentials for a module. This object is created by any of the following functions:

EISL_SelfCheck()
EISL_VerifyLoadedModule()
EISL_VerifyLoadedModuleAndCredentials()
EISL_VerifyLoadedModuleAndCredentialsWithCertificate()
EISL_VerifyLoadedModuleAndCredentialData()
EISL_VerifyLoadedModuleAndCredentialDataWithCertificate()
EISL_VerifyAndLoadModule()
EISL_VerifyAndLoadModuleAndCredentials()
EISL_VerifyAndLoadModuleAndCredentialsWithCertificate()
EISL_VerifyAndLoadModuleAndCredentialData()
EISL_VerifyAndLoadModuleAndCredentialDataWithCertificate()

This object is always contained in a Verified Signature Root Object.

Valid operations on this object include checking address ranges and obtaining the Manifest Section Object corresponding to the verified module. The verified module object cannot be modified in memory, and libraries must use various techniques to enforce this requirement.


typedef const void *ISL_VERIFIED_MODULE_PTR;


EISL Object Relationships and Life Cycle

This is shown in the following table.




OBJECT
CONTAINING
OBJECT

CREATING FUNCTION(S)

RECYCLING FUNCTION


Verified
Signature
Root

none

EISL_CreateVerifiedSignatureRoot
EISL_CreateVerifiedSignatureRootWithCertificate
EISL_CreateVerifiedSignatureRootWithCredentialData
EISL_CreateVerifiedSignatureRootWithCredentialDataAndCertificate

EISL_RecycleVerifiedSignatureRoot


Verified
Module*

Verified
Signature
Root

EISL_SelfCheck
EISL_VerifyLoadedModule
EISL_VerifyAndLoadModuleAndCredentials
EISL_VerifyAndLoadModuleAndCredentialsWithCertificate
EISL_VerifyAndLoadModuleAndCredentialData
EISL_VerifyAndLoadModuleAndCredentialDataWithCertificate
EISL_VerifyAndLoadModule
EISL_VerifyLoadedModuleAndCredentials
EISL_VerifyLoadedModuleAndCredentialsWithCertificate
EISL_VerifyLoadedModuleAndCredentialData
EISL_VerifyLoadedModuleAndCredentialDataWithCertificate
EISL_DuplicateVerifiedModulePtr

ISL_RecycleModuleAndCredentials*


Manifest
Section

Verified
Signature
Root

(implicit)

(implicit)


Verified
Module

Manifest
Section

(implicit)

(implicit)


Verified
Certificate

none

EISL_CreateCertificateChain
EISL_CreateCertificateChainWithCertificate
EISL_CreateCertificateChainWithCredentialData
EISL_CreateCertificateChainWithCredentialDataAnd
Certificate

EISL_RecycleCertificateChain


Verified
Certificate
Chain***

Verified
Signature
Root

(implicit)

(implicit)


Verified
Certificate

Verified
Certificate
Chain

(implicit)

(implicit)


Signature
Root
Attribuite
Iterator

Verified
Signature
Root

EISL_CreateManifestAttributeEnumerator

EISL_RecycleAttributeEnumerator


Manifest
Section
Iterator

Verified
Signature
Root

EISL_CreateManifestSectionEnumerator

EISL_RecycleManifestSectionEnumerator **


Signature
Attribute
Iterator

Verified
Signature
Root

EISL_Create Signature AttributeEnumerator

EISL_RecycleSignatureAttributeEnumerator **


Signer
Info
Attribute
Iterator

Verified
Signature
Root

EISL_CreateSignerInfoAttributeEnumerator

EISL_RecycleAttributeEnumerator


Certificate
Attribute
Iterator

Verified
Certificate

EISL_CreateCertificateAttributeEnumerator

EISL_RecycleCertificateAttributeEnumerator **


Manifest
Section
Attribute
Iterator

Verified
Signature
Root

EISL_CreateManifestSection

EISL_RecycleManifestSectionAttribute


*
A Verified Module object in the API function is used to reference its containing Verified Signature Root in these "simplified API" calls.

**
The iterator is implicitly recycled if its parent object is recycled. The recycle API call is optional.

***
The object is created and recycled implicitly under the "simplified API" calls.

Types and Data Structure

ISL_DATA

The ISL_DATA structure is used to associate a length, in bytes, with an arbitrary block of contiguous memory.

typedef struct isl_data{
    uint32 Length;  /* in bytes */
    uint8 *Data;
} ISL_DATA, *ISL_DATA_PTR;


Definition

Length

Length of the data buffer in bytes.

Data

Points to the start of an arbitrary length data buffer.

ISL_CONST_DATA

The ISL_CONST_DATA structure is used to associate a length, in bytes, with an arbitrary block of contiguous "read-only" memory.
Note:
The data referenced by the ISL_CONST_DATA is read-only, but the ISL_CONST_DATA itself can be modified.

typedef struct isl_const_data{
    uint32 Length;  /* in bytes */
    const uint8 *Data;
} ISL_CONST_DATA, *ISL_CONST_DATA_PTR;


Definition

Length

Length of the data buffer in bytes.

Data

Points to the start of an arbitrary length data buffer.

ISL_STATUS


typedef enum isl_status{
    ISL_OK = 0,
    ISL_FAIL = -1
} ISL_STATUS;


ISL_FUNCTION_PTR

The ISL_FUNCTION_POINTER defines a pointer to an ISL function. This type is returned by several functions that locate ISL services.

typedef void (*ISL_FUNCTION_PTR)(void);


Contents Next section Index