NAME

ISL_VerifyAndLoadModuleAndCredentials

SYNOPSIS

ISL_VERIFIED_MODULE_PTR ISL_VerifyAndLoadModuleAndCredentials
    (ISL_CONST_DATA Credentials,
    ISL_CONST_DATA SectionName,
    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 SectionName 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 ISL_CreateCertificateChain, ISL_CopyCertificateChain, ISL_CreateVerifiedSignatureRootWithCertificate, ISL_FindManifestSection, and ISL_VerifyAndLoadModule provides the same functionality.

Cleanup is done by ISL_RecycleVerifiedModuleCredentials.

PARAMETERS

Credentials (input)

The full file name to the signature file.

SectionName (input)

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

Signer (input)

The signer information (for directly signed signatures) or issuer name (if signed by certificates). 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)

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

SEE ALSO

ISL_CreateCertificateChain,
ISL_FindManifestSection,
ISL_CopyCertificateChain,
ISL_VerifyAndLoadModule,
ISL_CreateVerifiedSignatureRootWithCertificate,
ISL_RecycleVerifiedModuleCredentials,
ISL_FindRegistryAttribute,