會為目前使用者保存生物識別登入憑證。 從 Windows 10 版本 1607 開始，此功能可用於行動映像檔。
語法
HRESULT WinBioSetCredential(
[in] WINBIO_CREDENTIAL_TYPE Type,
[in] PUCHAR Credential,
[in] SIZE_T CredentialSize,
[in] WINBIO_CREDENTIAL_FORMAT Format
);
參數
[in] Type
一個 WINBIO_CREDENTIAL_TYPE 值，用來指定憑證類型。 目前，這可以WINBIO_CREDENTIAL_PASSWORD。
[in] Credential
指向包含憑證的可變長度位元組陣列的指標。 格式依據 類型 與 格式 參數而定。
[in] CredentialSize
以位元組為單位，為 憑證參數所 指定的值。
[in] Format
一個 WINBIO_CREDENTIAL_FORMAT 列舉值，指定憑證格式。 若型 別 參數為 WINBIO_CREDENTIAL_PASSWORD，則可為以下其中之一：
| 價值觀 | Meaning |
|---|---|
|
憑證為明文 NULL 終止的 Unicode 字串。 |
|
憑證是用 CredProtect 函式包裝，再用 CredPackAuthenticationBuffer 函式打包。 這是建議的。 |
|
密碼憑證被 CredProtect 包裝起來。 |
返回值
如果函式成功，則會傳回S_OK。 如果函式失敗，它會傳回指出錯誤的 HRESULT 值。 可能的值包括但不限於下表中的值。 如需常見錯誤碼的清單，請參閱 常見的 HRESULT 值。
| 回傳碼 | Description |
|---|---|
|
來電者無權設定憑證。 |
|
使用者尚未登記生物辨識樣本。 |
|
該憑證對目前使用者來說無效。 |
|
現行行政政策禁止使用憑證提供者。 |
備註
如果目前使用者擁有指定類型的登入憑證， WinBioSetCredential 會覆寫該憑證。 該函式同時驗證使用者憑證與互動式登入權限，若驗證失敗則失效。 與登入嘗試相關的事件會被放入事件日誌中。 網域帳號的憑證只有在群組政策允許的情況下才能儲存。
如果你在 Format 參數中WINBIO_PASSWORD_PACKED，應該呼叫 SecureZeroMemory 來安全地將憑證歸零。
只有中高完整性的流程才能設定憑證。 若較低完整性的程序嘗試設定憑證，函式會回傳E_ACCESSDENIED。
範例
接下來的函式會取得目前使用者的身份與憑證，然後呼叫 WinBioSetCredential 來設定這些憑證。 另外還包含兩個輔助函式，GetCredentials 和 GetCurrentUserIdentity。 連結至 Winbio.lib 靜態程式庫，並包含下列標頭檔：
- Windows.h
- Wincred.h
- 標準.h
- Conio.h
- Winbio.h
HRESULT SetCredential()
{
// Declare variables.
HRESULT hr = S_OK;
PVOID pvAuthBlob = NULL;
ULONG cbAuthBlob = 0;
WINBIO_IDENTITY identity;
PSID pSid = NULL;
// Find the identity of the user.
wprintf_s(L"\n Finding user identity.\n");
hr = GetCurrentUserIdentity( &identity );
if (FAILED(hr))
{
wprintf_s(L"\n User identity not found. hr = 0x%x\n", hr);
return hr;
}
// Set a pointer to the security descriptor for the user.
pSid = identity.Value.AccountSid.Data;
// Retrieve a byte array that contains credential information.
hr = GetCredentials(pSid, &pvAuthBlob, &cbAuthBlob);
if (FAILED(hr))
{
wprintf_s(L"\n GetCredentials failed. hr = 0x%x\n", hr);
goto e_Exit;
}
// Set the credentials.
hr = WinBioSetCredential(
WINBIO_CREDENTIAL_PASSWORD, // Type of credential.
(PUCHAR)pvAuthBlob, // Credentials byte array
cbAuthBlob, // Size of credentials
WINBIO_PASSWORD_PACKED); // Credentials format
if (FAILED(hr))
{
wprintf_s(L"\n WinBioSetCredential failed. hr = 0x%x\n", hr);
goto e_Exit;
}
wprintf_s(L"\n Credentials successfully set.\n");
e_Exit:
// Delete the authentication byte array.
if (NULL != pvAuthBlob)
{
SecureZeroMemory(pvAuthBlob, cbAuthBlob);
CoTaskMemFree(pvAuthBlob);
pvAuthBlob = NULL;
}
wprintf_s(L"\n Press any key to exit...");
_getch();
return hr;
}
//------------------------------------------------------------------------
// The following function displays a dialog box to prompt a user
// for credentials.
//
HRESULT GetCredentials(PSID pSid, PVOID* ppvAuthBlob, ULONG* pcbAuthBlob)
{
HRESULT hr = S_OK;
DWORD dwResult;
WCHAR szUsername[MAX_PATH] = {0};
DWORD cchUsername = ARRAYSIZE(szUsername);
WCHAR szPassword[MAX_PATH] = {0};
WCHAR szDomain[MAX_PATH] = {0};
DWORD cchDomain = ARRAYSIZE(szDomain);
WCHAR szDomainAndUser[MAX_PATH] = {0};
DWORD cchDomainAndUser = ARRAYSIZE(szDomainAndUser);
PVOID pvInAuthBlob = NULL;
ULONG cbInAuthBlob = 0;
PVOID pvAuthBlob = NULL;
ULONG cbAuthBlob = 0;
CREDUI_INFOW ui;
ULONG ulAuthPackage = 0;
BOOL fSave = FALSE;
static const WCHAR WINBIO_CREDPROV_TEST_PASSWORD_PROMPT_MESSAGE[] =
L"Enter your current password to enable biometric logon.";
static const WCHAR WINBIO_CREDPROV_TEST_PASSWORD_PROMPT_CAPTION[] =
L"Biometric Log On Enrollment";
if (NULL == pSid || NULL == ppvAuthBlob || NULL == pcbAuthBlob)
{
return E_INVALIDARG;
}
// Retrieve the user name and domain name.
SID_NAME_USE SidUse;
DWORD cchTmpUsername = cchUsername;
DWORD cchTmpDomain = cchDomain;
if (!LookupAccountSidW(
NULL, // Local computer
pSid, // Security identifier for user
szUsername, // User name
&cchTmpUsername, // Size of user name
szDomain, // Domain name
&cchTmpDomain, // Size of domain name
&SidUse)) // Account type
{
dwResult = GetLastError();
hr = HRESULT_FROM_WIN32(dwResult);
wprintf_s(L"\n LookupAccountSidLocalW failed: hr = 0x%x\n", hr);
return hr;
}
// Combine the domain and user names.
swprintf_s(
szDomainAndUser,
cchDomainAndUser,
L"%s\\%s",
szDomain,
szUsername);
// Call CredPackAuthenticationBufferW once to determine the size,
// in bytes, of the authentication buffer.
if (!CredPackAuthenticationBufferW(
0, // Reserved
szDomainAndUser, // Domain\User name
szPassword, // User Password
NULL, // Packed credentials
&cbInAuthBlob) // Size, in bytes, of credentials
&& GetLastError() != ERROR_INSUFFICIENT_BUFFER)
{
dwResult = GetLastError();
hr = HRESULT_FROM_WIN32(dwResult);
wprintf_s(L"\n CredPackAuthenticationBufferW (1) failed: ");
wprintf_s(L"hr = 0x%x\n", hr);
}
// Allocate memory for the input buffer.
pvInAuthBlob = CoTaskMemAlloc(cbInAuthBlob);
if (!pvInAuthBlob)
{
cbInAuthBlob = 0;
wprintf_s(L"\n CoTaskMemAlloc() Out of memory %d\n");
return HRESULT_FROM_WIN32(ERROR_OUTOFMEMORY);
}
// Call CredPackAuthenticationBufferW again to retrieve the
// authentication buffer.
if (!CredPackAuthenticationBufferW(
0,
szDomainAndUser,
szPassword,
(PBYTE)pvInAuthBlob,
&cbInAuthBlob))
{
dwResult = GetLastError();
hr = HRESULT_FROM_WIN32(dwResult);
wprintf_s(L"\n CredPackAuthenticationBufferW (2) failed: ");
wprintf_s(L"hr = 0x%x\n", hr);
goto e_Exit;
}
// Display a dialog box to request credentials.
ui.cbSize = sizeof(ui);
ui.hwndParent = GetConsoleWindow();
ui.pszMessageText = WINBIO_CREDPROV_TEST_PASSWORD_PROMPT_MESSAGE;
ui.pszCaptionText = WINBIO_CREDPROV_TEST_PASSWORD_PROMPT_CAPTION;
ui.hbmBanner = NULL;
dwResult = CredUIPromptForWindowsCredentialsW(
&ui, // Customizing information
0, // Error code to display
&ulAuthPackage, // Authorization package
pvInAuthBlob, // Credential byte array
cbInAuthBlob, // Size of credential input buffer
&pvAuthBlob, // Output credential byte array
&cbAuthBlob, // Size of credential byte array
&fSave, // Select the save check box.
CREDUIWIN_IN_CRED_ONLY |
CREDUIWIN_ENUMERATE_CURRENT_USER
);
if (dwResult != NO_ERROR)
{
hr = HRESULT_FROM_WIN32(dwResult);
wprintf_s(L"\n CredUIPromptForWindowsCredentials failed: ");
wprintf_s(L"0x%08x\n", dwResult);
goto e_Exit;
}
*ppvAuthBlob = pvAuthBlob;
*pcbAuthBlob = cbAuthBlob;
e_Exit:
// Delete the input authentication byte array.
if (pvInAuthBlob)
{
SecureZeroMemory(pvInAuthBlob, cbInAuthBlob);
CoTaskMemFree(pvInAuthBlob);
pvInAuthBlob = NULL;
};
return hr;
}
//------------------------------------------------------------------------
// The following function retrieves the identity of the current user.
// This is a helper function and is not part of the Windows Biometric
// Framework API.
//
HRESULT GetCurrentUserIdentity(__inout PWINBIO_IDENTITY Identity)
{
// Declare variables.
HRESULT hr = S_OK;
HANDLE tokenHandle = NULL;
DWORD bytesReturned = 0;
struct{
TOKEN_USER tokenUser;
BYTE buffer[SECURITY_MAX_SID_SIZE];
} tokenInfoBuffer;
// Zero the input identity and specify the type.
ZeroMemory( Identity, sizeof(WINBIO_IDENTITY));
Identity->Type = WINBIO_ID_TYPE_NULL;
// Open the access token associated with the
// current process
if (!OpenProcessToken(
GetCurrentProcess(), // Process handle
TOKEN_READ, // Read access only
&tokenHandle)) // Access token handle
{
DWORD win32Status = GetLastError();
wprintf_s(L"Cannot open token handle: %d\n", win32Status);
hr = HRESULT_FROM_WIN32(win32Status);
goto e_Exit;
}
// Zero the tokenInfoBuffer structure.
ZeroMemory(&tokenInfoBuffer, sizeof(tokenInfoBuffer));
// Retrieve information about the access token. In this case,
// retrieve a SID.
if (!GetTokenInformation(
tokenHandle, // Access token handle
TokenUser, // User for the token
&tokenInfoBuffer.tokenUser, // Buffer to fill
sizeof(tokenInfoBuffer), // Size of the buffer
&bytesReturned)) // Size needed
{
DWORD win32Status = GetLastError();
wprintf_s(L"Cannot query token information: %d\n", win32Status);
hr = HRESULT_FROM_WIN32(win32Status);
goto e_Exit;
}
// Copy the SID from the tokenInfoBuffer structure to the
// WINBIO_IDENTITY structure.
CopySid(
SECURITY_MAX_SID_SIZE,
Identity->Value.AccountSid.Data,
tokenInfoBuffer.tokenUser.User.Sid
);
// Specify the size of the SID and assign WINBIO_ID_TYPE_SID
// to the type member of the WINBIO_IDENTITY structure.
Identity->Value.AccountSid.Size = GetLengthSid(tokenInfoBuffer.tokenUser.User.Sid);
Identity->Type = WINBIO_ID_TYPE_SID;
e_Exit:
if (tokenHandle != NULL)
{
CloseHandle(tokenHandle);
}
return hr;
}
需求
| Requirement | 價值觀 |
|---|---|
| 最低支援的用戶端 | Windows 8.1 [僅限傳統型應用程式] |
| 支援的最低伺服器 | Windows Server 2012 R2 [僅限傳統型應用程式] |
| 目標平臺 | 窗戶 |
| Header | winbio.h（包括Winbio.h） |
| Library | Winbio.lib 網站 |
| DLL | Winbio.dll |