IOCTL_HAL_GETREGSECUREKEYS (Windows CE 5.0)

Article
09/14/2012

This IOCTL is called by Filesys.exe to enable the OEM to extend the list of registry paths that should be protected from nontrusted applications.

Parameters

dwIoControlCode
[in] Set to IOCTL_HAL_GETREGSECUREKEYS.
lpInBuf
[in]Set to NULL.
nInBufSize
[in] Set to zero.
lpOutBuf
[out] Pointer to a buffer that stores either a RegSecureKeyList structure provided by the OEM or a DWORD.
nOutBufSize
[in] Size of the lpOutBuf.

If the size specified by nOutBufSize is equal to sizeof(DWORD), Filesys.exe is requesting the amount of memory it needs to allocate to store the data to be returned by the OEM. Set the DWORD pointed to by lpOutBuf to the number of bytes that must be allocated by Filesys.exe to retrieve the data.

If the DWORD pointer specified in lpOutBuf is set to zero, no further action is taken by Filesys.exe.
lpBytesReturned
[in] Pointer to DWORD that stores the number of bytes written to the lpBuffer.

Return Values

TRUE indicates success.

FALSE indicates failure.

Remarks

This IOCTL is called twice: The first call queries for the size of the buffer it needs to allocate to store the OAL data; if the OAL specifies a size greater than zero, a second call requests the actual data.

Code Example

case IOCTL_HAL_GETREGSECUREKEYS: {
    RegSecureKey OEMSecNames[] = {
        // Protect HKEY_LOCAL_MACHINE\Name and all of its values/subkeys
        { REGSEC_HKLM, 4, L"Name" },
        
        // Protect HKEY_LOCAL_MACHINE\OtherName and
        // HKEY_CURRENT_USER\OtherName and all of their values/subkeys
        { REGSEC_HKLM | REGSEC_HKCU, 9, L"OtherName" },
    };
    RegSecureKeyList OEMSecList = {
        sizeof(OEMSecNames) / sizeof(RegSecureKey),
        OEMSecNames,
    };
    DWORD dwName;
    
    // First call: return the required buffer size
    //   lpInBuf      unused, should be NULL
    //   nInBufSize   unused, should be 0
    //   lpOutBuf     pointer to a DWORD buffer size
    //   nOutBufSize  sizeof(DWORD)
    if (!lpInBuf && !nInBufSize && lpOutBuf && (nOutBufSize ==     sizeof(DWORD))) {
        DWORD dwBufSize;

        dwBufSize = sizeof(OEMSecList) + sizeof(OEMSecNames);
        // size of structs without names
        for (dwName = 0; dwName < OEMSecList.dwNumKeys; dwName++) {
            dwBufSize += OEMSecNames[dwName].wLen * sizeof(WCHAR); 
            // no nulls
        }
        
        *((DWORD*)lpOutBuf) = dwBufSize;
        retval = TRUE;

    // Second call: fill the provided buffer
    // lpInBuf      unused, should be NULL
    // nInBufSize   unused, should be 0
    // lpOutBuf     pointer to the buffer to be filled
    // nOutBufSize  buffer size, should be the same as returned on first        call
    } else if (!lpInBuf && !nInBufSize && lpOutBuf
            && (nOutBufSize > sizeof(OEMSecList) + sizeof(OEMSecNames))) {
        
        RegSecureKeyList *pKeys = (RegSecureKeyList*)lpOutBuf;
        // pStr moves through the buffer as strings are written
        LPBYTE pStr = (LPBYTE)lpOutBuf + sizeof(OEMSecList) +           sizeof(OEMSecNames);

        pKeys->dwNumKeys = OEMSecList.dwNumKeys;
        pKeys->pList     = (RegSecureKey*) ((LPBYTE)lpOutBuf +           sizeof(OEMSecList));
        for (dwName = 0; dwName < OEMSecList.dwNumKeys; dwName++) {
            pKeys->pList[dwName].wRoots = OEMSecNames[dwName].wRoots;
            pKeys->pList[dwName].wLen   = OEMSecNames[dwName].wLen;
            pKeys->pList[dwName].pName  = (LPWSTR)pStr;
            memcpy(pStr, (LPBYTE)OEMSecNames[dwName].pName,
                OEMSecNames[dwName].wLen * sizeof(WCHAR));

            pStr += OEMSecNames[dwName].wLen * sizeof(WCHAR);
    }

        retval = TRUE;

    } else {
        // Invalid args
        DEBUGCHK(0);
    }

    break;
}

Requirements

OS Versions: Windows CE .NET 4.0 and later.
Header: Pkfuncs.h.