Common Security: CDSA and CSSM, Version 2
Copyright © 1999 The Open Group

EISL Functions

Credential and Attribute Verification Services

The functions for credential and attribute verification services provide a simplified verification for the common case where each code object is signed with its own signature file. Previous section.

Click here to return to the publication details.

NAME

EISL_SelfCheck

SYNOPSIS


ISL_VERIFIED_MODULE_PTR EISL_SelfCheck()

DESCRIPTION

This function returns a pointer to the verified module object if the module passed self-check, otherwise NULL. This function checks to see that the return address and the checking code itself are in the checked module.
Note:
The public key used to verify the signature is either embedded in the containing module or can be referenced by it in an implementation-specific manner. The public key is not exposed in the API. The EISL takes additional measures that make it difficult to modify the public key. The self-check function in EISL implicitly knows how to obtain the credentials of the module the instance of EISL is contained within.

EISL also makes it difficult for each module that contains an instance of EISL to bypass the self-check function. After invoking the self-check function, the containing module should verify that the return address and the address of the function itself are within the module being verified using the EISL_CheckAddressWithinModule() function.

PARAMETERS

None.

RETURN VALUE

Pointer to a verified object if verification is successful, or NULL if verification is unsuccessful.

NAME

EISL_VerifyAndLoadModuleAndCredentialData

SYNOPSIS


ISL_VERIFIED_MODULE_PTR EISL_VerifyAndLoadModuleAndCredentialData
    (const ISL_CONST_DATA CredentialsImage,
    const ISL_CONST_DATA ModuleSearchPath,
    const ISL_CONST_DATA Name,
    const ISL_CONST_DATA Signer,
    const ISL_CONST_DATA PublicKey)

DESCRIPTION

The purpose of this function is to verify the integrity of the credentials associated with an object code module and the integrity of the object code itself. If verified, the module is loaded into memory. Verification is accomplished as follows:

Verify the credentials.
The specified PublicKey is used to verify the signature on the specified credentialImage. The ModuleSearchPath parameter specifies a fully-qualified file system path name to locate the target object code module. If the signature has more than one signer, the Signer parameter selects the signer to be verified.

Verify module integrity
If the CredentialImage verifies, the integrity of the object code module referenced by the manifest section with the specified Name is verified. If verification is successful, a verified module object pointer is returned. Otherwise, NULL is returned.

If the object module referenced by ModuleSearchPath is not already loaded, the object code is verified as an object module object using file system reads to obtain the image without loading it. If verification is successful, the module is loaded.
If the module is already loaded, it is verified in memory.
The CredentialImage contains a PKCS#7 signature block as well as free-standing X.509 certificates. These certificates can be used to form a certificate chain used in the verification process.
When the verification result is no longer needed, the returned verified object module reference can be freed using EISL_RecycleVerifiedModuleCredentials().
This function combines many smaller functions into one call for a common use case. If greater flexibility is needed, a series of calls that includes EISL_CreateCertificateChain(), EISL_CopyCertificateChain(), EISL_FindManifestSection(), and EISL_VerifyAndLoadModule() provides the same functionality.

PARAMETERS

CredentialsImage (input)

A pointer to the memory-resident signed manifest credentials to be verified by this function.

ModuleSearchPath (input)

A string containing the fully-qualified path name to locate the object code associated with the signed manifest credentials.

Name (input)

The name of the manifest section containing attributes including a cryptographic digest of the object code referenced by ModueSearchPath.

Signer (input/optional)

The signer information (as a key for directly signed objects) or issuer name (as a certificate for objects signed by the key associated with a certificates) of the entity whose signature is to be verified. If the Signer is NULL, a default value is assumed. For example, it could be the X.509V3 IssuerName in the root certificate, or the SignerID in the PKCS#7 specification if directly signed.

PublicKey (input/optional)

This is the public key of the signer or trusted root certificate authority. The representation for the key must be compatible with the format of public keys in the selected certificate format. If the PublicKey is NULL, a default value is assumed.

RETURN VALUE

Pointer to a verified object if verification is successful, or NULL if verification is unsuccessful.

NAME

EISL_VerifyAndLoadModuleAndCredentialDataWithCertificate

SYNOPSIS


ISL_VERIFIED_MODULE_PTR 
  EISL_VerifyAndLoadModuleAndCredentialDataWithCertificate
    (const ISL_CONST_DATA CredentialsImage,
    const ISL_CONST_DATA ModuleSearchPath,
    const ISL_CONST_DATA Name,
    const ISL_CONST_DATA Signer,
    const ISL_CONST_DATA Certificate)

DESCRIPTION

The purpose of this function is to verify the integrity of the credentials associated with an object code module and the integrity of the object code itself. If verified, the module is loaded into memory. Verification is accomplished as follows:

Verify the credentials
The specified Certificate contains the public key that is used to verify the signature on the specified CredentialsImage. The ModuleSearchPath parameter specifies a fully-qualified file system path name to locate the target object code module. If the signature has more than one signer, the Signer parameter selects the signer to be verified.

Verify module integrity
If the CredentialImage verifies, the integrity of the object code module referenced by the manifest section with the specified Name is verified. If verification is successful, a verified module object pointer is returned. Otherwise, NULL is returned.

If the object module referenced by ModuleSearchPath is not already loaded, the object code is verified as an object module object using file system reads to obtain the image without loading it. If verification is successful, the module is loaded.
If the module is already loaded, it is verified in memory.
The CredentialImage contains a PKCS#7 signature block as well as free-standing X.509 certificates. These certificates can be used to form a certificate chain used in the verification process.
When the verification result is no longer needed, the returned verified object module reference can be freed using EISL_RecycleVerifiedModuleCredentials().
This function combines many smaller functions into one call for a common use case. If greater flexibility is needed, a series of calls that includes EISL_CreateCertificateChain(), EISL_CopyCertificateChain(), EISL_CreateVerifiedSignatureRootWithCertificate(), EISL_FindManifestSection(), and EISL_VerifyAndLoadModule() provides the same functionality.

PARAMETERS

CredentialsImage (input)

A pointer to the memory-resident signed manifest credentials to be verified by this function.

ModuleSearchPath (input)

A string containing the fully-qualified path name to locate the object code associated with the signed manifest credentials.

Name (input)

The name of the manifest section containing attributes including a cryptographic digest of the object code referenced by ModueSearchPath.

Signer (input/optional)

The signer information (as a key for directly signed objects) or issuer name (as a certificate for objects signed by the key associated with a certificates) of the entity whose signature is to be verified. If the Signer is NULL, a default value is assumed. For example, it could be the X.509V3 IssuerName in the root certificate, or the SignerID in the PKCS#7 specification if directly signed.

Certificate (input/optional)

This is a certificate containing the public key of the signer or trusted root certificate authority. If the Certificate is NULL, a default public key value is assumed.

RETURN VALUE

Pointer to a verified object if verification is successful, or NULL if verification is unsuccessful.

NAME

EISL_VerifyAndLoadModuleAndCredentials

SYNOPSIS


ISL_VERIFIED_MODULE_PTR EISL_VerifyAndLoadModuleAndCredentials
    (ISL_CONST_DATA Credentials,
    ISL_CONST_DATA Name,
    ISL_CONST_DATA Signer,
    ISL_CONST_DATA PublicKey)

DESCRIPTION

The purpose of this function is to verify the integrity of the credentials associated with an object code module and the integrity of the object code itself. If verified, the module is loaded into memory. Verification is accomplished as follows:

Verify the credentials-the specified PublicKey is used to verify the signature on the specified Credentials. The Credentials parameter must specify a full file system path name to locate the signature and manifest files associated with the target module. If the signature has more than one signer, the Signer parameter selects the signer to be verified.

Verify module integrity-if the credentials are valid, the integrity of the object code module referenced by the manifest section with the specified Name is verified. If successful, a verified module object pointer is returned. Otherwise, NULL is returned.

If the object module referenced by the manifest section is not already loaded, the object code is verified as an object module object using file system reads to obtain the image without loading it. If verified, the module is loaded.
If the module is already loaded, it is verified in memory.
Certificates embedded in the PKCS#7 signature as well as free-standing X.509 certificates in the credentials directory can be used in the certificate chain.
This function combines many smaller functions into one call for a common use case. If greater flexibility is needed, a series of calls that includes EISL_CreateCertificateChain(), EISL_CopyCertificateChain(), EISL_CreateVerifiedSignatureRootWithCertificate(), EISL_FindManifestSection(), and EISL_VerifyAndLoadModule() provides the same functionality.
Cleanup is done by EISL_RecycleVerifiedModuleCredentials.()

PARAMETERS

Credentials (input)

The full file name to the signature file.

Name (input)

The ame of the manifest section that refers to the object code to be verified.

Signer (input/optional)

The signer information (for directly signed signatures) or issuer name (if signed by certificates). If Signer.Data is NULL, a default value is assumed. For example, it could be the X.509V3 IssuerName in the root certificate, or the SignerID in the PKCS#7 specification if directly signed.

PublicKey (input/optional)

This is the public key of the signer or root certificate authority. The representation for the key must be compatible with the format of public keys in the selected certificate format. If PublicKey.Data is NULL, a default value is assumed.

RETURN VALUE

Pointer to a verified object if verification is successful, or NULL if verification is unsuccessful.

NAME

EISL_VerifyAndLoadModuleAndCredentialsWithCertificate

SYNOPSIS


ISL_VERIFIED_MODULE_PTR 
  EISL_VerifyAndLoadModuleAndCredentialsWithCertificate
    (const ISL_CONST_DATA Credentials,
    const ISL_CONST_DATA Name,
    const ISL_CONST_DATA Signer,
    const ISL_CONST_DATA Certificate)

DESCRIPTION

The purpose of this function is to verify the integrity of the credentials associated with an object code module and the integrity of the object code itself. If verified, the module is loaded into memory. Verification is accomplished as follows:

Verify the credentials
The specified Certificate contains the public key that is used to verify the signature on the specified Credentials The Credentials parameter specifies a fully-qualified file system path name to locate the signed manifest associated with the target object code module. If the signature block in the signed manifest contains more than one signature, the Signer parameter selects the signer to be verified.

Verify module integrity
If the credentials are valid, the Name identifies the manifest section containing a fully-qualified file system path name to locate the object code module. If integrity verification of the object module is successful, a verified module object pointer is returned. Otherwise, NULL is returned.

If the object module referenced by the manifest section is not already loaded, the object code is verified as an object module object using file system reads to obtain the image without loading it. If verified, the module is loaded.
If the module is already loaded, it is verified in memory.
The Credentials contain a PKCS#7 signature block as well as free-standing X.509 certificates. These certificates can be used to form a certificate chain used in the verification process.
When the verification result is no longer needed, the returned verified object module reference can be freed using EISL_RecycleVerifiedModuleCredentials().
This function combines many smaller functions into one call for a common use case. If greater flexibility is needed, a series of calls that includes EISL_CreateCertificateChain(), EISL_CopyCertificateChain(), EISL_CreateVerifiedSignatureRootWithCertificate(), EISL_FindManifestSection(), and EISL_VerifyAndLoadModule() provides the same functionality.

PARAMETERS

Credentials (input)

A string containing the fully-qualified path name to locate the signed manifest credentials associated with the object code.

Name (input)

The name of the manifest section containing attributes including a cryptographic digest and a fully-qualified file

Signer (input/optional)

The signer information (as a key for directly signed objects) or issuer name (as a certificate for objects signed by the key associated with a certificates) of the entity whose signature is to be verified. If Signer.Data is NULL, a default value is assumed. For example, it could be the X.509V3 IssuerName in the root certificate, or the SignerID in the PKCS#7 specification if directly signed.

Certificate (input/optional)

This is a certificate containing the public key of the signer or trusted root certificate authority. If Certificate.Data is NULL, a default public key value is assumed.

RETURN VALUE

Pointer to a verified object if verification is successful, or NULL if verification is unsuccessful.

NAME

EISL_VerifyLoadedModuleAndCredentialData

SYNOPSIS


ISL_VERIFIED_MODULE_PTR EISL_VerifyLoadedModuleAndCredentialData
    (const ISL_CONST_DATA CredentialsImage,
    const ISL_CONST_DATA ModuleSearchPath,
    const ISL_CONST_DATA Name,
    const ISL_CONST_DATA Signer,
    const ISL_CONST_DATA PublicKey)

DESCRIPTION

The purpose of this function is to verify the integrity of the credentials associated with a loaded object code module and the integrity of the object code itself. Verification is accomplished as follows:

Verify the credentials
The specified PublicKey is used to verify the signature on the specified CredentialsImage. The CredentialsImage is a memory-resident signed manifest credential associated with the target object code. If the signature block in the signed manifest contains more than one signer, the Signer parameter selects the signer to be verified.

Verify module integrity
If the credentials are valid, the integrity of the loaded object code module referenced by the manifest section with the specified Name is verified. The ModuleSearchPath is a fully-qualifies file system name locating the object code in the file system. The object code file name is used to locate the loaded object code and verification is performed on the loaded object code. If successful, a verified module object pointer is returned. Otherwise, NULL is returned.

The contains a PKCS#7 signature block as well as free-standing X.509 certificates. These certificates can be used to form a certificate chain used in the verification process.
When the verification result is no longer needed, the returned verified object module reference can be freed using EISL_RecycleVerifiedModuleCredentials().
This function combines many smaller functions into one call for a common case. If greater flexibility is needed, a series of calls that includes EISL_CreateCertificateChain(), EISL_CopyCertificateChain(), EISL_CreateVerifiedSignatureRootWithCertificate(), EISL_FindManifestSection(), and EISL_VerifyLoadedModule() provides the same functionality.

PARAMETERS

CredentialsImage (input)

A pointer to the memory-resident signed manifest credentials to be verified by this function.

ModuleSearchPath (input)

A string containing the fully-qualified path name to locate the object code associated with the signed manifest credentials.

Name (input)

The name of the manifest section containing attributes including a cryptographic digest of the object code referenced by ModuleSearchPath.

Signer (input/optional)

The signer information (as a key for directly signed objects) or issuer name (as a certificate for objects signed by the key associated with a certificates) of the entity whose signature is to be verified. If Signer.Data is NULL, a default value is assumed. For example, it could be the X.509V3 IssuerName in the root certificate, or the SignerID in the PKCS#7 specification if directly signed.

PublicKey (input/optional)

This is the public key of the signer or trusted root certificate authority. The representation for the key must be compatible with the format of public keys in the selected certificate format. If the PublicKey is NULL, a default value is assumed.

RETURN VALUE

Pointer to a verified object if verification is successful, or NULL if verification is unsuccessful.

NAME

EISL_VerifyLoadedModuleAndCredentialDataWithCertificate

SYNOPSIS


ISL_VERIFIED_MODULE_PTR 
EISL_VerifyLoadedModuleAndCredentialDataWithCertificate
    (const ISL_CONST_DATA CredentialsImage,
    const ISL_CONST_DATA ModuleSearchPath,
    const ISL_CONST_DATA Name,
    const ISL_CONST_DATA Signer,
    const ISL_CONST_DATA Certificate)

DESCRIPTION

The purpose of this function is to verify the integrity of the credentials associated with a loaded object code module and the integrity of the object code itself. Verification is accomplished as follows:

Verify the credentials
The specified Certificate contains the public key that is used to verify the signature on the specified CredentialsImage. The CredentialsImage is a memory-resident signed manifest credential associated with the target object code. If the signature block in the signed manifest contains more than one signer, the Signer parameter selects the signer to be verified.

Verify module integrity
If the credentials are valid, the integrity of the loaded object code module referenced by the manifest section with the specified Name is verified. The ModuleSearchPath is a fully-qualifies file system name locating the object code in the file system. The object code file name is used to locate the loaded object code and verification is performed on the loaded object code. If successful, a verified module object pointer is returned. Otherwise, NULL is returned.

The CredentialsImage contains a PKCS#7 signature block as well as free-standing X.509 certificates. These certificates can be used to form a certificate chain used in the verification process.
When the verification result is no longer needed, the returned verified object module reference can be freed using EISL_RecycleVerifiedModuleCredentials().
This function combines many smaller functions into one call for a common case. If greater flexibility is needed, a series of calls that includes EISL_CreateCertificateChain(), EISL_CopyCertificateChain(), EISL_CreateVerifiedSignatureRootWithCertificate(), EISL_FindManifestSection(), and EISL_VerifyLoadedModule() provides the same functionality.

PARAMETERS

CredentialsImage (input)

A pointer to the memory-resident signed manifest credentials to be verified by this function.

ModuleSearchPath (input)

A string containing the fully-qualified path name to locate the object code associated with the signed manifest credentials.

Name (input)

The name of the manifest section containing attributes including a cryptographic digest of the object code referenced by ModueSearchPath.

Signer (input/optional)

The signer information (as a key for directly signed objects) or issuer name (as a certificate for objects signed by the key associated with a certificates) of the entity whose signature is to be verified. If Signer.Data is NULL, a default value is assumed. For example, it could be the X.509V3 IssuerName in the root certificate, or the SignerID in the PKCS#7 specification if directly signed.

Certificate (input/optional)

This is a certificate containing the public key of the signer or trusted root certificate authority. If Certificate.Data is NULL, a default public key value is assumed.

RETURN VALUE

Pointer to a verified object if verification is successful, or NULL if verification is unsuccessful.

NAME

EISL_VerifyLoadedModuleAndCredentials

SYNOPSIS


ISL_VERIFIED_MODULE_PTR EISL_VerifyLoadedModuleAndCredentials
    (ISL_CONST_DATA Credentials,
    ISL_CONST_DATA Name,
    ISL_CONST_DATA Signer,
    ISL_CONST_DATA PublicKey)

DESCRIPTION

The purpose of this function is to verify the integrity of the credentials associated with a loaded object code module and the integrity of the object code itself. Verification is accomplished as follows:

Verify the credentials-the specified PublicKey is used to verify the signature on the specified Credentials. The Credentials parameter must specify a full file system path name to locate the signature and manifest files associated with the target module. If the signature has more than one signer, the Signer parameter selects the signer to be verified.

Verify module integrity-if the credentials are valid, the integrity of the loaded object code module referenced by the manifest section with the specified Name is verified. If successful, a verified module object pointer is returned. Otherwise, NULL is returned.

Certificates embedded in the PKCS#7 signature as well as free-standing X.509 certificates in the credentials directory can be used in the certificate chain.
This function combines many smaller functions into one call for a common case. If greater flexibility is needed, a series of calls that includes EISL_CreateCertificateChain(), EISL_CopyCertificateChain(), EISL_CreateVerifiedSignatureRootWithCertificate(), EISL_FindManifestSection(), and EISL_VerifyLoadedModule() provides the same functionality. Cleanup is done by EISL_RecycleVerifiedModuleCredentials().

PARAMETERS

Credentials (input)

The full file name to the signature file.

Name (input)

The name of the manifest section that refers to the object code to be verified.

Signer (input/optional)

The signer information (for directly signed signatures) or issuer name (if signed by certificates). If Signer.Data is NULL, a default value is assumed.

PublicKey (input/optional)

This is the public key of the signer or root certificate authority. The representation for the key must be compatible with the format of public keys in the selected certificate format. If PublicKey.Data is NULL, a default value is assumed.

RETURN VALUE

Pointer to a verified object if verification is successful, or NULL if verification is unsuccessful.

NAME

EISL_VerifyLoadedModuleAndCredentialsWithCertificate

SYNOPSIS


ISL_VERIFIED_MODULE_PTR 
EISL_VerifyLoadedModuleAndCredentialsWithCertificate
    (const ISL_CONST_DATA Credentials,
    const ISL_CONST_DATA Name,
    const ISL_CONST_DATA Signer,
    const ISL_CONST_DATA Certificate)

DESCRIPTION

The purpose of this function is to verify the integrity of the credentials associated with a loaded object code module and the integrity of the object code itself. Verification is accomplished as follows:

Verify the credentials
The specified Certificate contains the public key that is used to verify the signature on the specified Credentials. The Credentials parameter specifies a fully-qualified file system path name to locate the signed manifest associated with the target object code module. If the signature block in the signed manifest contains more than one signature, the Signer parameter selects the signer to be verified.

Verify module integrity
If the credentials are valid, the Name identifies the manifest section containing a fully-qualified file system path name to locate the object code module. The object code file name is used to locate the loaded object code and verification is performed on the loaded object code. If integrity verification of the loaded object module is successful, a verified module pointer is returned. Otherwise, NULL is returned.

The Credentials contain a PKCS#7 signature block as well as free-standing X.509 certificates. These certificates can be used to form a certificate chain used in the verification process.
When the verification result is no longer needed, the returned verified object module reference can be freed using EISL_RecycleVerifiedModuleCredentials().
This function combines many smaller functions into one call for a common case. If greater flexibility is needed, a series of calls that includes EISL_CreateCertificateChain(), EISL_CopyCertificateChain(), EISL_CreateVerifiedSignatureRootWithCertificate(), EISL_FindManifestSection(), and EISL_VerifyLoadedModule() provides the same functionality.

PARAMETERS

Credentials (input)

A string containing the fully-qualified path name to locate the signed manifest credentials associated with the object code.

Name (input)

The name of the manifest section containing attributes including a cryptographic digest and a fully-qualified file system path name for the object code.

Signer (input/optional)

The signer information (as a key for directly signed objects) or issuer name (as a certificate for objects signed by the key associated with a certificates) of the entity whose signature is to be verified. If Signer.Data is NULL, a default value is assumed. For example, it could be the X.509V3 IssuerName in the root certificate, or the SignerID in the PKCS#7 specification if directly signed.

Certificate (input/optional)

This is a certificate containing the public key of the signer or trusted root certificate authority. If Certificate.Data is NULL, a default public key value is assumed.

RETURN VALUE

Pointer to a verified object if verification is successful, or NULL if verification is unsuccessful.

NAME

EISL_GetCertficateChain

SYNOPSIS


ISL_VERIFIED_CERTIFICATE_CHAIN_PTR EISL_GetCertificateChain
    (ISL_VERIFIED_MODULE_PTR Module)

DESCRIPTION

This function returns a reference to the certificate chain that was constructed and verified by EISL_VerifyLoadedModuleAndCredentials() or EISL_VerifyAndLoadModuleAndCredentials().

PARAMETERS

Module (input)

A verified module object returned by the EISL_SelfCheck(), EISL_VerifyLoadedModuleAndCredentials(), or EISL_VerifyAndLoadModuleAndCredentials() function.
Verified module objects created by EISL_VerifyAndLoadModule(), EISL_VerifyLoadedModule(), and EISL_VerifyData() return a NULL certificate chain.

RETURN VALUE

A pointer to the verified certificate chain object is returned if successful, otherwise NULL.

NAME

EISL_ContinueVerification

SYNOPSIS


uint32 EISL_ContinueVerification
    (ISL_VERIFIED_MODULE_PTR Module,
    uint32 WorkFactor)

DESCRIPTION

The purpose of this function is to permit ongoing verification of an object which has been already verified by the EISL_VerifyAndLoadModuleAndCredentials(), EISL_SelfCheck(), EISL_VerifyLoadedModuleAndCredentials(), EISL_VerifyAndLoadModule(), or EISL_VerifyLoadedModule() functions. The WorkFactor parameter increases the amount of verification for an individual call by an implementation-specific amount proportional to the parameter value. The result variable returns the cummulative number of complete, successful verification passes which have been performed on the verified module, or zero if a failure was ever detected.
The application can dynamically adjust the amount of time spent in verification by adjusting the work factor. The return value permits monitoring the rate at which the entire object is verified.

PARAMETERS

Module (input)

A verified module object returned 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()
EISL_DuplicateVerifiedModulePtr()

WorkFactor (input)

The amount of work spent in the partial verification increases in proportion to the value of this parameter. The actual rate of verification depends on the platform and implementation.

RETURN VALUE

The number of verification passes that have been completed successfully, or zero if verification is unsuccessful.

NAME

EISL_DuplicateVerifiedModulePtr

SYNOPSIS


ISL_VERIFIED_MODULE_PTR EISL_DuplicateVerifiedModulePtr
    (ISL_VERIFIED_MODULE_PTR Module)

DESCRIPTION

This function clones the state information associated with an existing verified module pointer. If necessary a full copy is created, otherwise a reference count is incremented to indicate additional users of the object. The function returns a new verified module pointer referencing the cloned state information.

PARAMETERS

Module (input)

A verified module object to be duplicated. This can be returned 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()

RETURN VALUE

A pointer to the verified module state is returned if successful, otherwise NULL.

NAME

EISL_RecycleVerifiedModuleCredentials

SYNOPSIS


ISL_STATUS EISL_RecycleVerifiedModuleCredentials
    (ISL_VERIFIED_MODULE_PTR Verification)

DESCRIPTION

This function destroys and recycles the memory for the module verification object, its containing Signature Root Object and Certificate Chain Object, and all subordinate objects. Related iterator objects and certificate objects must be recycled before recycling the module verification object. Once recycled, this object must not be referenced. All pointers to certificates, manifest sections, iterators, and the information returned by iterators are invalid after this call has completed.

PARAMETERS

Verification (input)

A verified module object returned 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()
EISL_DuplicateVerifiedModulePtr()

RETURN VALUE

ISL_OK is returned if successful, otherwise ISL_FAIL.

Signature Root Methods

The man-page definitions for Signature Root Methods are presented in this section. Previous section.

NAME

EISL_CreateVerifiedSignatureRootWithCredentialData

SYNOPSIS


ISL_VERIFIED_SIGNATURE_ROOT_PTR 
EISL_CreateVerifiedSignatureRootWithCredentialData
    (const ISL_CONST_DATA CredentialsImage,
    const ISL_CONST_DATA ModuleSearchPath,
    const ISL_CONST_DATA Signer,
    const ISL_CONST_DATA PublicKey)

DESCRIPTION

This function uses the PublicKey to verify a digital signature contained in the CredentialsImage. It does not construct certificate chains, but must use the key directly. If the credentials support multiple signers, the Signer parameter specifies which signature to verify.
This function does not verify the objects referenced in the manifest sections of the CredentialsImage. However, the manifest sections are verified, and the attributes in the sections can be trusted.
The ModuleSearchPath is a colon-separated list of fully-qualified file system path names for locating the object code modules referenced by the manifest sections of the CredentialsImage. The ModuleSearchPath is stored as state information associated with the verified signature root returned by this function. The information is available to subsequent operations on the verified signature root.
The manifest sections can be enumerated using the object created by EISL_CreateManifestSectionEnumerator().

PARAMETERS

CredentialsImage (input)

A pointer to the memory-resident signed manifest credentials to be verified by this function.

ModuleSearchPath (input)

A string containing a colon-separated list of fully-qualified file system path names for locating the object code modules referenced by the manifest sections of the CredentialsImage.

Signer (input/optional)

The signer information (as a key for directly signed objects) or issuer name (as a certificate for objects signed by the key associated with a certificates) of the entity whose signature is to be verified. If Signer.Data is NULL, a default value is assumed. For example, it could be the X.509V3 IssuerName in the root certificate, or the SignerID in the PKCS#7 specification if directly signed.

PublicKey (input/optional)

This is the public key of the signer or trusted root certificate authority. The representation for the key must be compatible with the format of public keys in the selected certificate format. If PublicKey.Data is NULL, a default value is assumed.

RETURN VALUE

Pointer to a verified signature root object if successful, or NULL if unsuccessful.

NAME

EISL_CreateVerifiedSignatureRootWithCredentialDataAndCertificate

SYNOPSIS


ISL_VERIFIED_SIGNATURE_ROOT_PTR 
EISL_CreateVerifiedSignatureRootWithCredentialDataAndCertificate
    (const ISL_CONST_DATA CredentialsImage,
    const ISL_CONST_DATA ModuleSearchPath,
    ISL_VERIFIED_CERTIFICATE_PTR Cert)

DESCRIPTION

This function uses the public key contained in the Cert to verify a digital signature contained in the CredentialsImage. The Cert must be a verified certificate. This function does not construct certificate chains, but must use the signer identification and public key contained in the certificate.
This function does not verify the objects referenced in the manifest sections of the CredentialsImage. However, the manifest sections are verified, and the attributes in the sections can be trusted.
The ModuleSearchPath is a colon-separated list of fully-qualified file system path names for locating the object code modules referenced by the manifest sections of the CredentialsImage. The ModuleSearchPath is stored as state information associated with the verified signature root returned by this function. The information is available to subsequent operations on the verified signature root.
The manifest sections can be enumerated using the object created by EISL_CreateManifestSectionEnumerator().

PARAMETERS

CredentialsImage (input)

A pointer to the memory-resident signed manifest credentials to be verified by this function.

ModuleSearchPath (input)

A string containing a colon-separated list of fully-qualified file system path names for locating the object code modules referenced by the manifest sections of the CredentialsImage.

Cert (input)

This is a verified certificate containing the public key of the signer or trusted root certificate authority.

RETURN VALUE

Pointer to a verified signature root object if successful, or NULL if unsuccessful.

NAME

EISL_CreateVerifiedSignatureRoot

SYNOPSIS


ISL_VERIFIED_SIGNATURE_ROOT_PTR EISL_CreateVerfiedSignatureRoot
    (ISL_CONST_DATA Credentials,
    ISL_CONST_DATA Signer,
    ISL_CONST_DATA PublicKey)

DESCRIPTION

This function uses the PublicKey to verify the digital signature specified by the Credentials. It does not construct certificate chains, but must use the key directly. If the credentials support multiple signers, the Signer parameter can be used to determine which signer to verify.
This function does not verify the objects referenced in the manifest sections. However, the manifest sections are verified, and the attributes in the sections can be trusted.
The manifest sections can be enumerated using the object created by EISL_CreateManifestSectionEnumerator().

PARAMETERS

Credentials (input)

The complete path name to the digital signature file to be verified.

Signer (input)

The signer information for directly signed signatures. If the Signer is NULL, a default value is assumed.

PublicKey (input/optional)

This is the public key of the signer or root certificate authority. The representation for the key must be compatible with the format of public keys in the selected certificate format. If PublicKey.Data is NULL, a default value is assumed.

RETURN VALUE

Pointer to a verified signature root object if successful, or NULL if unsuccessful.

NAME

EISL_CreateVerifiedSignatureRootWithCertificate

SYNOPSIS


ISL_VERIFIED_SIGNATURE_ROOT_PTR 
EISL_CreateVerfiedSignatureRootWithCertificate
    (ISL_CONST_DATA Credentials,
    ISL_VERIFIED_CERTIFICATE_PTR Cert)

DESCRIPTION

This function uses the PublicKey to verify the digital signature specified by the Credentials. It does not construct certificate chains, but must use the signer identification and public key in the certificate directly.
The function does not verify the objects referenced in the manifest sections. However, the manifest sections are verified, and the attributes in the sections can be trusted.
The manifest sections can be enumerated using the object created by EISL_CreateManifestSectionEnumerator().

PARAMETERS

Credentials (input)

The complete path name to the digital signature file to be verified.

Cert (input)

The certificate used to directly verify the digital signature.

RETURN VALUE

Pointer to a verified signature root object if successful, or NULL if unsuccessful.

NAME

EISL_FindManifestSection

SYNOPSIS


ISL_MANIFEST_SECTION_PTR EISL_FindManifestSection
    (ISL_VERIFIED_SIGNATURE_ROOT_PTR Root,
    ISL_CONST_DATA Name)

DESCRIPTION

This function returns a pointer to the Manifest Section Object with the given name, or NULL if there is no such section.

PARAMETERS

Root (input)

A verified signature root explicitly created by EISL_CreateVerifiedSignatureRoot() or EISL_CreateVerifiedSignatureRootWithCertificate(), or implicitly by EISL_SelfCheck(), EISL_VerifyAndLoadModuleAndCredentials(), or EISL_VerifyLoadedModuleAndCredentials().

Name (input)

The name of the manifest section that is requested.

RETURN VALUE

The specified Manifest Section Object is returned, or NULL if no section exists.

NAME

EISL_CreateManifestSectionEnumerator

SYNOPSIS


ISL_ITERATOR_PTR EISL_CreateManifestSectionEnumerator
    (ISL_VERIFIED_SIGNATURE_ROOT_PTR Root)

DESCRIPTION

This function creates a dynamic object whose purpose is to list references to the sections of the manifest referenced by the Root parameter. The resulting iterator object is activated by invoking the EISL_GetNextManifestSection() function. The object should be recycled using the EISL_RecycleManifestSectionEnumerator() call when it is no longer needed.

PARAMETERS

Root (input)

A verified signature root explicitly created by EISL_CreateVerifiedSignatureRoot() or EISL_CreateVerifiedSignatureRootWithCertificate(), or implicitly by EISL_SelfCheck(), EISL_VerifyAndLoadModuleAndCredentials(), or EISL_VerifyLoadedModuleAndCredentials().

RETURN VALUE

Pointer to a manifest section iterator object if successful, or NULL if unsuccessful.

NAME

EISL_GetNextManifestSection

SYNOPSIS


ISL_MANIFEST_SECTION_PTR EISL_GetNextManifestSection
    (ISL_ITERATOR_PTR Iterator)

DESCRIPTION

This function returns a pointer to the next Manifest Section Object, or NULL if there are no more sections. The state of the iterator is updated such that the next call to this function will return the next manifest section object.

PARAMETERS

Iterator (input)

A certificate attribute iterator created by EISL_CreateManifestSectionEnumerator().

RETURN VALUE

The next Manifest Section Object is returned, or NULL if no more sections exist.

NAME

EISL_RecycleManifestSectionEnumerator

SYNOPSIS


ISL_STATUS EISL_RecycleManifestSectionEnumerator
    (ISL_ITERATOR_PTR Iterator)

DESCRIPTION

This function destroys and recycles the memory for the manifest section iterator. It must be the last call that references the iterator.

PARAMETERS

Iterator (input)

A manifest section iterator created by EISL_CreateManifestSectionEnumerator().

RETURN VALUE

ISL_OK is returned if successful, otherwise ISL_FAIL.

NAME

EISL_FindManifestAttribute

SYNOPSIS


ISL_STATUS  EISL_FindManifestAttribute
    (ISL_VERIFIED_SIGNATURE_ROOT_PTR Context,
    ISL_CONST_DATA Name,
    ISL_CONST_DATA_PTR Value)

DESCRIPTION

This function locates a specified signature root attribute. The attribute is a name-value pair. Name identifies the signature root attribute to be located. Value is the output parameter containing the length and pointer to the value of the signature root attribute.
This function returns ISL_FAIL if there is no signature root attribute with the specified Name.

PARAMETERS

Context (input)

A verified signature root reference returned by one of the functions EISL_CreateVerifiedSignatureRoot(), EISL_CreateVerifiedSignatureRootWithCertificate(), or EISL_GetManifestSignatureRoot().

Name (input)

The name of the attribute that is requested. The name" representation must be consistent with the manifest representation. Manifests are human-readable. The attribute name is represented as an alphanumeric (and underscore, minus, and period) ASCII character string.

Value (output)

A pointer to a result variable whose length and pointer are updated to refer to the attribute value.

RETURN VALUE

ISL_OK is returned if the attribute was found, or ISL_FAIL if unsuccessful.

NAME

EISL_CreateManifestAttributeEnumerator

SYNOPSIS


ISL_ITERATOR_PTR  EISL_CreateManifestAttributeEnumerator
    (ISL_VERIFIED_SIGNATURE_ROOT_PTR Context)

DESRIPTION

This function creates a dynamic object whose purpose is to list references to the attributes of the signature root of the signed manifest credential. The iterator object is activated using the function EISL_GetNextAttribute(). The iterator object should be used to retrieve the name-value attribute pairs when the caller does not have prior knowledge of the attribute names. The function EISL_FindManifestAttribute() can be used to directly locate attribute values based on attribute name.
When the iterator object is no longer needed, is must be recycled using the function EISL_RecycleAttributeEnumerator().

PARAMETERS

Context (input)

A verified signature root reference returned by one of the functions EISL_CreateVerifiedSignatureRoot(), EISL_CreateVerifiedSignatureRootWithCertificate(), or EISL_GetManifestSignatureRoot().

RETURN VALUE

Pointer to a signature root attribute-iterator object if successful, or NULL if unsuccessful.

NAME

EISL_FindSignerInfoAttribute

SYNOPSIS


ISL_STATUS  EISL_FindSignerInfoAttribute
    (ISL_VERIFIED_SIGNATURE_ROOT_PTR Context,
    ISL_CONST_DATA Name,
    ISL_CONST_DATA_PTR Value)

DESCRIPTION

This function locates an attribute in the signer information block associated with the verified signature root referenced by Context. The attribute is a name-value pair. Name identifies the signer information attribute to be located. Value is the output parameter containing the length and pointer to the value of the signer information attribute.
This function returns ISL_FAIL if there is no signer information attribute with the specified Name.

PARAMETERS

Context (input)

A verified signature root reference returned by one of the functions EISL_CreateVerifiedSignatureRoot(), EISL_CreateVerifiedSignatureRootWithCertificate(), or EISL_GetManifestSignatureRoot().

Name (input)

The name of the attribute that is requested. The name representation must be consistent with the manifest representation. Manifests are human-readable. The attribute name is represented as an alphanumeric (and underscore, minus, and period) ASCII character string.

Value (output)

A pointer to a result variable whose length and pointer are updated to refer to the attribute value.

RETURN VALUE

ISL_OK is returned if the attribute was found, or ISL_FAIL if unsuccessful.

NAME

EISL_CreateSignerInfoAttributeEnumerator

SYNOPSIS


ISL_ITERATOR_PTR EISL_CreateSignerInfoAttributeEnumerator
    (ISL_VERIFIED_SIGNATURE_ROOT_PTR Context)

DESRIPTION

This function creates a dynamic object whose purpose is to list references to the attributes of the signer information block associated with the verified signature root. The iterator object is activated using the function EISL_GetNextAttribute(). The iterator object should be used to retrieve the name-value attribute pairs when the caller does not have prior knowledge of the attribute names. The function EISL_FindSignerInfoAttribute() can be used to directly locate attribute values based on attribute name.
When the iterator object is no longer needed, is must be recycled using the function EISL_RecycleAttributeEnumerator().

PARAMETERS

Context (input)

A verified signature root reference returned by one of the functions EISL_CreateVerifiedSignatureRoot(), EISL_CreateVerifiedSignatureRootWithCertificate(), or EISL_GetManifestSignatureRoot().

RETURN VALUE

Pointer to a signer info attribute-iterator object if successful, or NULL if unsuccessful.

NAME

EISL_GetNextAttribute

SYNOPSIS


ISL_STATUS EISL_GetNextAttribute
    (ISL_ITERATOR_PTR Iterator,
    ISL_CONST_DATA_PTR Name,
    ISL_CONST_DATA_PTR Value)

DESCRIPTION

This function returns the attribute name and value referenced by the iterator object. The state of the iterator is updated such that the next call to this function will return the next attribute name-value pair. The Name and Value returned by this function cannot be modified by the program. If no more attribute values are present, the function returns ISL_FAIL.

PARAMETERS

Iterator (input)

An iterator object created by EISL_CreateManifestAttributeEnumerator() or EISL_CreateSignerInfoAttributeEnumerator().

Name (output)

A pointer to a result variable that is updated to refer to the attribute name. The name representation must be consistent with the manifest representation. Manifests are human-readable. The attribute name is represented as an alphanumeric (and underscore, minus, and period) ASCII character string.

Value (output)

A pointer to a result variable that is updated to refer to the attribute value. The value is an arbitrary binary object.

RETURN VALUE

The function result is ISL_OK if successful in returning a name and value pair, otherwise ISL_FAIL.

NAME

EISL_RecycleAttributeEnumerator

SYNOPSIS


ISL_STATUS  EISL_RecycleAttributeEnumerator
    (ISL_ITERATOR_PTR Iterator)

DESCRIPTION

This function destroys and recycles the memory for the attribute iterator. It must be the last call referencing the iterator.

PARAMETERS

Iterator (input)A

A attribute iterator created by EISL_CreateManifestAttributeEnumerator() or EISL_CreateSignerInfoAttributeEnumerator().

RETURN VALUE

ISL_OK is returned if successful, otherwise ISL_FAIL.

NAME

EISL_FindSignatureAttribute

SYNOPSIS


ISL_STATUS EISL_FindSignatureAttribute
    (ISL_VERIFIED_SIGNATURE_ROOT_PTR Root,
    ISL_CONST_DATA Name,
    ISL_CONST_DATA_PTR Value)

DESCRIPTION

This function returns the value associated with the signature attribute specified by Name. The value and its length are returned in the Value pointer. The function returns ISL_FAIL if the specified attribute does not exist.

PARAMETERS

Root (input)

A verified signature root explicitly created by EISL_CreateVerifiedSignatureRoot() or EISL_CreateVerifiedSignatureRootWithCertificate(), or implicitly by EISL_SelfCheck(), EISL_VerifyAndLoadModuleAndCredentials(), or EISL_VerifyLoadedModuleAndCredentials().

Name (input)

The name of the attribute that is requested. The representation of the attribute name must be consistent with the representation of certificates. For example, attribute names for signatures associated with X.509V3 certificates would be DER-encoded object identifiers.

Value (input/output)

The data pointer and length are updated to point to a read-only copy of the attribute.

RETURN VALUE

ISL_OK is returned if the attribute is found, otherwise ISL_FAIL.

NAME

EISL_CreateSignatureAttributeEnumerator

SYNOPSIS


ISL_ITERATOR_PTR EISL_CreateSignatureAttributeEnumerator
    (ISL_VERIFIED_SIGNATURE_ROOT_PTR Root)

DESCRIPTION

This function creates a dynamic object whose purpose is to list references to the attributes of the signature referenced by the Verification parameter. The resulting iterator object is activated by invoking the EISL_GetNextSignatureAttribute() function. The object should be recycled using the EISL_RecycleSignatureEnumerator() function when it is no longer needed.

PARAMETERS

Root (input)

A verified signature root explicitly created by EISL_CreateVerifiedSignatureRoot() or EISL_CreateVerifiedSignatureRootWithCertificate(), or implicitly by EISL_SelfCheck(), EISL_VerifyAndLoadModuleAndCredentials(), or EISL_VerifyLoadedModuleAndCredentials().

RETURN VALUE

Pointer to a signature attribute iterator object if successful, or NULL if unsuccessful.

NAME

EISL_GetNextSignatureAttribute

SYNOPSIS


ISL_STATUS EISL_GetNextSignatureAttribute
    (ISL_ITERATOR_PTR Iterator,
    ISL_CONST_DATA_PTR Name,
    ISL_CONST_DATA_PTR Value)

DESCRIPTION

This function returns the next attribute name and value for the signature referenced by the iterator object. The state of the iterator is updated such that the next call to this function will return the next attribute. The name and value cannot be modified by the program. If no more attribute values are present, the function returns ISL_FAIL.

PARAMETERS

Iterator (input)

A signature attribute iterator created by EISL_CreateSignatureAttributeEnumerator().

Name (output)

A pointer to a result variable that is updated to refer to the attribute name. The representation of the attribute name must be consistent with the representation of certificates. For example, with X.509V3 certificates, the name is a DER-encoded object identifier for a PKCS#7 authenticated attribute.

Value (output)

A pointer to a result variable that is updated to refer to the attribute value. The representation of the attribute name must be consistent with the representation of certificates. For example, with X.509V3 certificates, it is a DER-encoded value (or values).

RETURN VALUE

The function result is ISL_OK if successful in returning a name and value pair, otherwise ISL_FAIL.

NAME

EISL_RecycleSignatureAttributeEnumerator

SYNOPSIS


ISL_STATUS EISL_RecycleSignatureAttributeEnumerator
    (ISL_ITERATOR_PTR Iterator)

DESCRIPTION

This function destroys and recycles the memory for the signature attribute iterator. It must be the last call referencing the iterator.

PARAMETERS

Iterator (input)

A signature attribute iterator created by EISL_CreateSignatureAttributeEnumerator().

RETURN VALUE

ISL_OK is returned if successful, otherwise ISL_FAIL.

NAME

EISL_RecycleVerifiedSignatureRoot

SYNOPSIS


ISL_STATUS EISL_RecycleVerifiedSignatureRoot
    (ISL_VERIFIED_SIGNATURE_ROOT_PTR Root)

DESCRIPTION

This function destroys and recycles the memory for the verified signature root. It must be the last call referencing the signature root, or any objects derived from or contained in the signature root.

PARAMETERS

Root (input)

A verified signature root explicitly created by EISL_CreateVerifiedSignatureRoot() or EISL_CreateVerifiedSignatureRootWithCertificate().

RETURN VALUE

ISL_OK is returned if successful, otherwise ISL_FAIL.

Certificate Chain Methods

The man-page definitions for functions to manipulate certificate chains in a PKCS#7 signature block are presented in this section. Previous section.

NAME

EISL_CreateCertificateChainWithCredentialData

SYNOPSIS


const ISL_VERIFIED_CERTIFICATE_CHAIN_PTR 
EISL_CreateCertificateChainWithCredentialData
    (const ISL_CONST_DATA RootIssuer,
    const ISL_CONST_DATA PublicKey,
    const ISL_CONST_DATA CredentialsImage,
    const ISL_CONST_DATA ModuleSearchPath)

DESCRIPTION

This function constructs and verifies a certificate chain that begins with the root certificate authority identified by the distinguished name RootIssuer and the PublicKey, and ends with the certificate of a signer of the signed manifest credentials contained in CredentialsImage. The certificates required to construct the chain must be contained in the PKCS#7 signature block of the signed manifest credential.
During the construction process, each certificate is verified, beginning with the certificate of the RootIssuer.
The ModuleSearchPath is a colon-separated list of fully-qualified file system path names for locating the object code modules referenced by the manifest sections of the CredentialsImage. The ModuleSearchPath is stored as state information associated with the verified certificate chain returned by this function. The information is available to subsequent operations on the verified certificate chain.

PARAMETERS

RootIssuer (input)
The distinguished name of the root certificate authority

PublicKey (input)

The public key of the root certificate authority.

CredentialsImage (input)

A pointer to the memory-resident signed manifest credentials containing certificates used to construct the certificate chain.

ModuleSearchPath (input)

A string containing a colon-separated list of fully-qualified file system path names for locating the object code modules referenced by the manifest sections of the CredentialsImage.

RETURN VALUE

A pointer to the verified certificate chain object is returned if successful, otherwise NULL.

NAME

EISL_CreateCertificateChainWithCredentialDataAndCertificate

SYNOPSIS


ISL_VERIFIED_CERTIFICATE_CHAIN_PTR 
EISL_CreateCertificateChainWithCredentialDataAndCertificate
    (const ISL_CONST_DATA Certificate,
    const ISL_CONST_DATA CredentialsImage,
    const ISL_CONST_DATA ModuleSearchPath)

DESCRIPTION

This function constructs and verifies a certificate chain that begins with the root certificate authority Certificate and ends with the certificate of a signer of the signed manifest credentials contained in CredentialsImage. The certificates required to construct the chain must be contained in the PKCS#7 signature block of the signed manifest credential.
During the construction process, each certificate is verified, beginning with the certificate of the root authority.
The ModuleSearchPath is a colon-separated list of fully-qualified file system path names for locating the object code modules referenced by the manifest sections of the CredentialsImage. The ModuleSearchPath is stored as state information associated with the verified certificate chain returned by this function. The information is available to subsequent operations on the verified certificate chain.

PARAMETERS

Certificate (input)

The certificate of the root of the certificate chain.

CredentialsImage (input)

A pointer to the memory-resident signed manifest credentials containing certificates used to construct the certificate chain.

ModuleSearchPath (input)

A string containing a colon-separated list of fully-qualified file system path names for locating the object code modules referenced by the manifest sections of the CredentialsImage.

RETUEN VALUE

A pointer to the verified certificate chain object is returned if successful, otherwise NULL.

NAME

EISL_CreateCertificateChain

SYNOPSIS


ISL_VERIFIED_CERTIFICATE_CHAIN_PTR EISL_CreateCertificateChain
    (ISL_CONST_DATA RootIssuer,
    ISL_CONST_DATA PublicKey,
    ISL_CONST_DATA Credential)

DESCRIPTION

This function constructs and verifies a certificate chain which starts with the root certificate authority (issuer) and ends with the certificate of the signer of the Credential. During the construction process, each certificate is verified, beginning with the root certificate.

PARAMETERS

RootIssuer (input)

The distinguished name of the root certificate authority.

PublicKey (input)

The public key of the root certificate authority.

Credential (input)

The full path filename of a module's signature file.

RETURN VALUE

A pointer to the verified certificate chain object is returned if successful, otherwise NULL.

NAME

EISL_CreateCertificateChainWithCertificate

SYNOPSIS


ISL_VERIFIED_CERTIFICATE_CHAIN_PTR 
EISL_CreateCertificateChainWithCertificate
    (const ISL_CONST_DATA Certificate,
    const ISL_CONST_DATA Credential)

DESCRIPTION

This function constructs and verifies a certificate chain that begins with the root certificate authority Certificate and ends with the certificate of a signer of the Credential. The Credential is a fully-qualified file system path name identifying the location of a signed manifest credential. The certificates required to construct the chain must be contained in the PKCS#7 signature block of the signed manifest credential.
During the construction process, each certificate is verified, beginning with the certificate of the root authority.

PARAMETERS

Certificate (input)

The certificate of the root of the certificate chain.

Credential (input)

A pointer to the memory-resident signed manifest credentials containing certificates used to construct the certificate chain.

RETURN VALUE

A pointer to the verified certificate chain object is returned if successful, otherwise NULL.

NAME

EISL_CopyCertificateChain

SYNOPSIS


uint32 EISL_CopyCertificateChain
    (ISL_VERIFIED_CERTIFICATE_CHAIN_PTR Verification,
    ISL_VERIFIED_CERTIFICATE_PTR Certs[],
    uint32 MaxCertificates)

DESCRIPTION

This function copies pointers to the verified certificates in the certificate chain. The first certificate (subscript zero) is signed by the root certificate authority. The last certificate is the signer's certificate.

PARAMETERS

Verification (input)

A verified certificate chain returned by the EISL_CreateCertificateChain() or EISL_GetCertificateChain() function.

Certs (input/output)

An array of certificate object pointers sufficiently large to contain the expected certificate chain.

MaxCertificates (input)

The dimension of the certificate object pointer array.

RETURN VALUE

The number of certificates returned in the Certs array as a result of the copy process.

NAME

EISL_RecycleVerifiedCertificateChain

SYNOPSIS


ISL_STATUS EISL_RecycleVerifiedCertificateChain
    (ISL_VERIFIED_CERTIFICATE_CHAIN_PTR Chain)

DESCRIPTION

This function destroys and recycles the memory for the verified certificate chain. It must be the last call referencing the certificate chain, or any objects derived from or contained in the certificate chain.

PARAMETERS

Chain (input)

A verified certificate chain explicitly created by EISL_CreateCertificateChain().

RETURN VALUE

ISL_OK is returned if successful, otherwise ISL_FAIL.

Certificate Attribute Methods

The man-page definitions for Certificate Methods are presented in this section. Previous section.

NAME

EISL_FindCertificateAttribute

SYNOPSIS


ISL_STATUS EISL_FindCertificateAttribute
    (ISL_VERIFIED_CERTIFICATE_PTR Cert,
    ISL_CONST_DATA Name,
    ISL_CONST_DATA_PTR Value)

DESCRIPTION

This function returns the value associated with the certificate attribute specified by Name. The value and its length are returned in the Value pointer. The function returns ISL_FAIL if the specified attribute does not exist.

PARAMETERS

Cert (input)

A reference to a certificate returned by the EISL_CopyCertificateChain() function.

Name (input)

The name of the attribute that is requested. The name representation must be consistent with the certificate representation. For example, for X.509V3 certificates, an attribute name is represented as a DER-encoded object identifier.

Value (input/output)

The address and length are updated to refer to the attribute value within the verified certificate.

RETURN VALUE

ISL_OK is returned if the specified certificate attribute is found, or ISL_FAIL if the attribute is not found.

NAME

EISL_CreateCertificateAttributeEnumerator

SYNOPSIS


ISL_ITERATOR_PTR EISL_CreateCertificateAttributeEnumerator
    (ISL_VERIFIED_CERTIFICATE_PTR Cert)

DESCRIPTION

This function creates a dynamic object whose purpose is to list references to the attributes of the certificate. The iterator object is activated using the EISL_GetNextCertificateAttribute() function. The object must be recycled using the EISL_RecycleCertificateAttributeEnumerator() call when it is no longer needed.

PARAMETERS

Cert (input)

A reference to a certificate returned by the ISL_CreateCertificateChain() function.

RETURN VALUE

Pointer to an iterator object if successful, or NULL if unsuccessful.

NAME

EISL_GetNextCertificateAttribute

SYNOPSIS


ISL_STATUS EISL_GetNextCertificateAttribute
    (ISL_ITERATOR_PTR CertIterator,
    ISL_CONST_DATA_PTR Name,
    ISL_CONST_DATA_PTR Value)

DESCRIPTION

This function returns the next attribute name and value. The state of the iterator is updated such that the next call to this function will return the next attribute. The name and value cannot be modified by the program. If no more attribute values are present, the function returns ISL_FAIL.

PARAMETERS

CertIterator (input)

A certificate attribute iterator created by EISL_CreateCertificateAttributeEnumerator().

Name (output)

A pointer to a result variable that is updated to refer to the attribute name. The representation of the attribute name must be consistent with the representation of certificates. For example, with X.509V3 certificates, the name is a DER-encoded object identifier.

Value (output)

A pointer to a result variable that is updated to refer to the attribute value. The representation of the attribute name must be consistent with the representation of certificates. For example, with X.509V3 certificates, it is a DER-encoded value (or values).

RETURN VALUE

The function result is ISL_OK if successful in returning a name and value pair, otherwise ISL_FAIL.

NAME

EISL_RecycleCertificateAttributeEnumerator

SYNOPSIS


ISL_STATUS EISL_RecycleCertificateAttributeEnumerator
    (ISL_ITERATOR_PTR CertIterator)

DESCRIPTION

This function destroys and recycles the memory for the certificate attribute iterator. It must be the last call that references the iterator.

PARAMETERS

CertIterator (input)

A certificate attribute iterator created by EISL_CreateCertificateAttributeEnumerator().

RETURN VALUE

ISL_OK is returned if successful, otherwise ISL_FAIL.

Manifest Section Object Methods

The man-page definitions for Manifest Section Object Methods are presented in this section. Previous section.

NAME

EISL_GetManifestSignatureRoot

SYNOPSIS


ISL_VERIFIED_SIGNATURE_ROOT_PTR EISL_GetManifestSignatureRoot
    (ISL_MANIFEST_SECTION_PTR Section)

DESCRIPTION

This function gets the Verified Signature Root which contains this manifest section.

PARAMETERS

Section (input)

A manifest section pointer returned by EISL_GetNextManifestSection(), EISL_GetModuleManifestSection(), or EISL_FindManifestSection().

RETURN VALUE

Pointer to a signature root object if successful, or NULL if unsuccessful.

NAME

EISL_VerifyAndLoadModule

SYNOPSIS


ISL_VERIFIED_MODULE_PTR EISL_VerifyAndLoadModule
    (ISL_MANIFEST_SECTION_PTR Section)

DESCRIPTION

If the module referenced by the manifest section is already loaded, it is verified in memory. Otherwise, the module is verified on the file system, and, if successful, the module is loaded.

PARAMETERS

Section (input)

A manifest section returned by the EISL_GetNextManifestSection() or EISL_FindManifestSection() functions.

RETURN VALUE

Pointer to a verified module object if successful, or NULL if unsuccessful.

NAME

EISL_VerifyLoadedModule

SYNOPSIS


ISL_VERIFIED_MODULE_PTR EISL_VerifyLoadedModule
    (ISL_MANIFEST_SECTION_PTR Section)

DESCRIPTION

This function verifies a memory-resident object code module referenced in the specified manifest section.

PARAMETERS

Section (input)

A manifest section returned by the EISL_GetNextManifestSection(), EISL_GetModuleManifestSection(), or EISL_FindManifestSection() functions.

RETURN VALUE

Pointer to a verified module object if successful, or NULL if unsuccessful.

NAME

EISL_FindManifestSectionAttribute

SYNOPSIS


ISL_STATUS EISL_FindManifestSectionAttribute
    (ISL_MANIFEST_SECTION_PTR Section,
    ISL_CONST_DATA Name,
    ISL_CONST_DATA_PTR Value)

DESCRIPTION

This function updates the length and pointer to refer to the Manifest Section Attribute (or metadata) Value corresponding to the given name, or returns ISL_FAIL if there is no such attribute.

PARAMETERS

Section (input)

A manifest section object returned by the EISL_FindManifestSection(), EISL_GetModuleManifestSection(), or EISL_GetNextManifestSection() functions.

Name (input)

The name of the attribute that is requested. The name representation must be consistent with the manifest representation. Manifests are human-readable. The attribute name is represented as an alphanumeric (and underscore, minus, and period) ASCII character string.

Value (output)

A pointer to a result variable whose length and pointer are updated to refer to the attribute value.

RETURN VALUE

ISL_OK is returned if the attribute was found, or ISL_FAIL if unsuccessful.

NAME

EISL_CreateManifestSectionAttributeEnumerator

SYNOPSIS


ISL_ITERATOR_PTR EISL_CreateManifestSectionAttributeEnumerator
    (ISL_MANIFEST_SECTION_PTR Section)

DESCRIPTION

This function creates a dynamic object whose purpose is to list references to the attributes of the manifest Section. The iterator object is activated using the EISL_GetNextManifestSectionAttribute() function. The object must be recycled using the EISL_RecycleManifestSectionEnumerator() function when it is no longer needed.

PARAMETERS

Section (input)

A manifest section object returned by the EISL_FindManifestSection(), EISL_GetModuleManifestSection(), or EISL_GetNextManifestSection() functions.

RETURN VALUE

Pointer to a signed object attribute iterator object if successful, or NULL if unsuccessful.

NAME

EISL_GetNextManifestSectionAttribute

SYNOPSIS


ISL_STATUS EISL_GetNextManifestSectionAttribute
    (ISL_ITERATOR_PTR Iterator,
    ISL_CONST_DATA_PTR Name,
    ISL_CONST_DATA_PTR Value)

DESCRIPTION

This function returns the next attribute name and value. The state of the iterator is updated such that the next call to this function will return the next attribute. The name and value cannot be modified by the program. If no more attribute values are present, the function returns ISL_FAIL.

PARAMETERS

Iterator (input)

A signed object attribute iterator created by EISL_CreateManifestSectionAttributeEnumerator().

Name (output)

A pointer to a result variable that is updated to refer to the attribute name. The name representation must be consistent with the manifest representation. Manifests are human-readable. The attribute name is represented as an alphanumeric (and underscore, minus, and period) ASCII character string.

Value (output)

A pointer to a result variable that is updated to refer to the attribute value. The value is an arbitrary binary object.

RETURN VALUE

The function result is ISL_OK if successful in returning a name and value pair, otherwise ISL_FAIL.

NAME

EISL_RecycleManifestSectionAttributeEnumerator

SYNOPSIS


ISL_STATUS EISL_RecycleManifestSectionAttributeEnumerator
    (ISL_ITERATOR_PTR Iterator)

DESCRIPTION

This function destroys and recycles the memory for the Manifest Section Attribute iterator. It must be the last call which references the iterator.

PARAMETERS

Iterator (input)

A signed object attribute iterator created by EISL_CreateManifestSectionAttributeEnumerator.()

RETURN VALUE

ISL_OK is returned if successful, otherwise ISL_FAIL.

NAME

EISL_GetModuleManifestSection

SYNOPSIS


ISL_MANIFEST_SECTION_PTR EISL_GetModuleManifestSection
    (ISL_VERIFIED_MODULE_PTR Module)

DESCRIPTION

This function returns the manifest section that describes the integrity of the specified Module. This is the section that is used to verify module integrity.

PARAMETERS

Module (input)

A verified module object returned 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()

RETURN VALUE

ISL_OK is returned if successful, otherwise ISL_FAIL.

Secure Linkage Services

The man-page definitions for Secure Linkage Services are presented in this section. Previous section.

NAME

EISL_LocateProcedureAddress

SYNOPSIS


ISL_FUNCTION_PTR EISL_LocateProcedureAddress
    (ISL_VERIFIED_MODULE_PTR Module,
    ISL_CONST_DATA Name)

DESCRIPTION

This function returns the address of a function in a verified object code module. The function of interest is specified by Name. The address returned is read from the symbol table associated with the module. This function will return the address of the function specified by Name, only if that function is exported by the module it appears in.
To complete a secure linkage check before invoking the loaded module, the returned address must be checked to determine whether it is actually within the bounds of the verified object code module. If the symbol table associated with the object code module has been modified, the address can reference code outside of the verified module. The function EISL_CheckAddressWithinModule() can to check the address for containment in the verified module.

PARAMETERS

Module (input)

A verified module object returned 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()
EISL_DuplicateVerifiedModulePtr()

Name (input)

An entry point name as required by the platform.

RETURN VALUE

Pointer to the procedure entry point, or NULL if unsuccessful.

NAME

EISL_GetReturnAddress

SYNOPSIS


#define EISL_GetReturnAddress(Address)	\
{                                       \
    /* Platform specific code in here */
}

DESCRIPTION

This macro gets the current return address and facilitates validating that a caller's return address is inside an authorized, verified module.
If function A calls function B at address R and function B calls EISL_GetReturnAddress(), EISL_GetReturnAddress() returns value R. Function B can validate that address R is within a verified module which should contain function A using EISL_CheckAddressWithinModule().
This function macro is platform and compiler dependent.

PARAMETERS

Address (output)

Pointer in which return address value is returned.

RETURN VALUE

Results in copying the return address value in Address pointer.

NAME

EISL_CheckAddressWithinModule

SYNOPSIS


ISL_STATUS EISL_CheckAddressWithinModule
    (ISL_VERIFIED_MODULE_PTR Verification,
    ISL_FUNCTION_PTR Address)

DESCRIPTION

The Address is checked against the list of valid address ranges for executable code within the module identified by the verified module pointer.

PARAMETERS

Verification (input)

A verified module object returned 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()
�Fn EISL_DuplicateVerifiedModulePtr

Address (input)

An address to be checked.

RETURN VALUE

ISL_OK is returned if the address is a valid address within the bounds of the module, otherwise ISL_FAIL is returned.

NAME

EISL_CheckDataAddressWithinModule

SYNOPSIS


ISL_STATUS EISL_CheckDataAddressWithinModule
    (ISL_VERIFIED_MODULE_PTR Verification,
    const void *Address)

DESCRIPTION

The Address is checked against the list of valid address ranges for the data space within the module identified by the verified module pointer.

PARAMETERS

Verification (input)

A verified module object returned 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()
�Fn EISL_DuplicateVerifiedModulePtr

Address (input)

A data address to be checked.

RETURN VALUE

ISL_OK is returned if the data address is a valid address within the bounds of the module, otherwise ISL_FAIL is returned.

NAME

EISL_GetLibHandle

SYNOPSIS


void * EISL_GetLibHandle
    (ISL_VERIFIED_MODULE_PTR Verification)

DESCRIPTION

The system-dependent handle (or address) of the loaded object code module is returned.

PARAMETERS

Verification (input)

A verified module object returned 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()

RETURN VALUE

The handle to the loaded object code is returned, or NULL if failure.

EISL Functions

Credential and Attribute Verification Services

NAME

SYNOPSIS

DESCRIPTION

PARAMETERS

RETURN VALUE

SEE ALSO

NAME

SYNOPSIS

DESCRIPTION

PARAMETERS

RETURN VALUE

SEE ALSO

NAME

SYNOPSIS

DESCRIPTION

PARAMETERS

RETURN VALUE

SEE ALSO

NAME

SYNOPSIS

DESCRIPTION

PARAMETERS

RETURN VALUE

SEE ALSO

NAME

SYNOPSIS

DESCRIPTION

PARAMETERS

RETURN VALUE

SEE ALSO

NAME

SYNOPSIS

DESCRIPTION

PARAMETERS

RETURN VALUE

SEE ALSO

NAME

SYNOPSIS

DESCRIPTION

PARAMETERS

RETURN VALUE

SEE ALSO

NAME

SYNOPSIS

DESCRIPTION

PARAMETERS

RETURN VALUE

SEE ALSO

NAME

SYNOPSIS

DESCRIPTION

PARAMETERS

RETURN VALUE

SEE ALSO

NAME

SYNOPSIS

DESCRIPTION

PARAMETERS

RETURN VALUE

SEE ALSO

NAME

SYNOPSIS

DESCRIPTION

PARAMETERS

RETURN VALUE

SEE ALSO

NAME

SYNOPSIS

DESCRIPTION

PARAMETERS

RETURN VALUE

SEE ALSO

NAME

SYNOPSIS

DESCRIPTION

PARAMETERS

RETURN VALUE

SEE ALSO