CertVerify (Windows Embedded CE 6.0)
1/6/2010
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
Certificates Functions
Authentication Services Functions
CertInit