CertVerify

11/18/2009

The CertVerify function provides code execution security by validating digital signatures associated with executable files, which includes both In-Process (DLLs) and Out-of-Process (EXE) COM Servers. CertVerify is invoked by the File System Module (filesys) immediately before it loads the file.

For more information on the File System Module, see the filesys Module.

Syntax

DWORD CertVerify (
  HANDLE  hFile,
  LPCWSTR pszFileName,
  LPWSTR  pUserName,
  DWORD   cchUserName,
  LPDWORD pdwCertFlags
);

Parameters

• hFile
  [in] A handle to the file to validate. When the FileSys module identifies that a file is stored in ROM, it automatically sets the value of the hFile parameter to INVALID_HANDLE_VALUE, and then assigns the file the Normal trust level. It is possible to pass the hFile parameter to Evidence Generator's EvgenSetFileInfo function, for access as a memory-mapped file.

• pszFileName
  [in] The name of the file to validate. This can be either the fully-qualified path name, or just the simple file name.

• pUserName
  [out] A string buffer for the Account Name, which is the name of the entity associated with the certificate. This parameter is populated only if a match is found in one of the certificate stores, or if a match is found in the Revoked List.

• cchUserName
  [in] The length, in characters, of pUserName buffer.

• pdwCertFlags
  [out] Flags indicating the result of the validation. The following constants make up the set of valid values:

  Constant	Value	Description
  CERT_UNKNOWN	0x00000000	The file is not digitally signed.
  CERT_REVOKED	0x00000001	The file is digitally signed, but its certificate is registered in the Revoked List.
  CERT_STORE_UNKNOWN	0x00000002	The file is digitally signed, but its certificate is not registered in one of the certificate stores.
  CERT_STORE_VALID	0x00000004	The file is digitally signed, and its certificate is registered in one of the certificate stores.

Return Value

The CertVerify function returns the following results.

• TRUE
  The CertVerify function was able to determine the file's certificate status, and returned a value in the pdwCertFlags parameter.

• FALSE
  The CertVerify function was unable to determine the file's certificate status. This can result from an invalid file name, missing parameters, or when a related process times-out or is denied access to resources.

Remarks

The CertInit function, along with the CertVerify function, belongs to the Certificate Module (certmod), which is part of Windows Embedded CE 6.0's extensible security model. You can include this module in your image by setting SYSGEN_CERTMOD.

CertMod provides an authentication service for the File System Module (filesys) by checking for valid certificate signatures on executable files. It does this by calling into the Evidence Generator (EvGen) module, and Cryptography (Crypto) components to look for and examine certification evidence if it is present in the executable file.

There are no Trust Levels in Windows Embedded CE 6.0, which uses a one tier security model. In this model, the FileSys module only loads an executable file if CertMod can chain it's certificate to a certificate in one of the certificate stores.

On images that do not include the CertMod module, all executable files are loaded—regardless of whether they include a certificate.

Given the handle to an executable file, the CertVerify function calls members of the Evidence Generator (EvGen) library to determine if the file is digitally signed. If the file has a digital signature, CertVerify attempts to Certificate Chains a certificate in one of the certificate stores. If it can do this successfully, then CertVerify returns the certificate Account Name in the pUserName parameter, and the certificate's validation state in the pdwCertFlags parameter.

The CertInit function is only called once, when the FileSys Module loads the Certification Module (Certmod.dll).

CertMod runs in association with the following standard CE 6.0 components:

CertMod runs in association with the following standard CE 6.0 components:

• EvGen
  The Evidence Generator, which opens files to expose their digital certificate for inspection and validation. This is an internal component is used by CertMod.

• filesys Module
  The File System Module, which manages the Windows Embedded CE file system.

• crypt32 Module
  The Cryptographic APIs.

• Registry
  CertVerify checks the following registry key for registered certificate stores:

  [HKLM\Security\CertMod\<Certificate Store Name>]
     "AccountName" = REG_SZ:""
  

  AccountName is the name associated with the certificate. It is returned by CertVerify in the pUserName parameter if the executable file is digitally signed, and if its certificate can be chained to one of the certificates registered in one of the certificate stores, or in the Revoked List.

An image that includes the CertMod component also includes the following registry keys:

[HKEY_LOCAL_MACHINE\Comm\Security\SystemCertificates\CodeSign]
   "InitFile"="\\windows\\codesigncerts.p7b"

[HKEY_LOCAL_MACHINE\Security\CertMod\CodeSign]
   "AccountName"="system"

An image that includes the CertMod component also includes the following certificate store:

\public\common\oak\files\codesigncerts.p7b

Images built with CertMod support contain this default "codesign" certificate store, which is used for archiving digital signatures for validating DLL and executable files. By default, this certificate store is empty. When it contains no Certificates, FileSys loads in-ROM executable files only, and it rejects all other executable files, passing the last error code ERROR_ACCESS_DENIED. Once this certificate store does contain certificates, then in-ROM executable files and executable files signed with a certificate chained to one in this certificate store, are loaded by FileSys.

Requirements

Header	cecertmod.h
Library	Certmod.dll
Windows Embedded CE	Windows Embedded CE 6.0 and later

See Also

Reference

Authentication Services Functions
CertInit

Concepts

System Store Locations

Other Resources

File System Security Best Practices