Функция AcquireCredentialsHandle (Negotiate)

Статья
06/13/2023

Функция AcquireCredentialsHandle (Negotiate) получает дескриптор для ранее существовающих учетных данных субъекта безопасности. Этот дескриптор требуется для функций InitializeSecurityContext (Negotiate) и AcceptSecurityContext (Negotiate). Это могут быть либо существующие учетные данные, которые устанавливаются с помощью системного входа, который не описан здесь, либо вызывающий объект может предоставить альтернативные учетные данные.

Примечание

Это не "вход в сеть" и не подразумевает сбор учетных данных.

Синтаксис

SECURITY_STATUS SEC_Entry AcquireCredentialsHandle(
  _In_  SEC_CHAR       *pszPrincipal,
  _In_  SEC_CHAR       *pszPackage,
  _In_  ULONG          fCredentialUse,
  _In_  PLUID          pvLogonID,
  _In_  PVOID          pAuthData,
  _In_  SEC_GET_KEY_FN pGetKeyFn,
  _In_  PVOID          pvGetKeyArgument,
  _Out_ PCredHandle    phCredential,
  _Out_ PTimeStamp     ptsExpiry
);

Параметры

pszPrincipal [in]

Указатель на строку, завершающуюся нулевым значением, которая указывает имя участника, учетные данные которого будет ссылаться дескриптор.

Примечание

Если процесс, запрашивающий дескриптор, не имеет доступа к учетным данным, функция возвращает ошибку. Строка NULL указывает, что процессу требуется дескриптор учетных данных пользователя, в контексте безопасности которого он выполняется.

pszPackage [in]

Указатель на строку, завершающуюся нулевым значением, которая указывает имя пакета безопасности , с которым будут использоваться эти учетные данные. Это имя пакета безопасности , возвращаемое в элементе Name структуры SecPkgInfo , возвращаемой функцией EnumerateSecurityPackages . После установки контекста можно вызвать QueryContextAttributes (Negotiate) с параметром ulAttribute , для SECPKG_ATTR_PACKAGE_INFO для возврата сведений об используемом пакете безопасности .

Чтобы успешно вызвать эту функцию с помощью поставщика общих служб Negotiate, задайте для этого параметра значение Negotiate.

fCredentialUse [in]

Флаг, указывающий, как будут использоваться эти учетные данные. Этот параметр может принимать одно из указанных ниже значений.

Значение	Значение
SECPKG_CRED_AUTOLOGON_RESTRICTED 0x00000010	Безопасность не использует учетные данные для входа по умолчанию или учетные данные из диспетчера учетных данных. Windows Server 2008, Windows Vista, Windows Server 2003 и Windows XP: Это значение не поддерживается.
SECPKG_CRED_BOTH	Проверьте входящие учетные данные или используйте локальные учетные данные для подготовки исходящего маркера. Этот флаг включает оба других флага.
SECPKG_CRED_INBOUND	Проверка учетных данных входящего сервера. Входящие учетные данные могут быть проверены с помощью центра проверки подлинности при вызове Метода InitializeSecurityContext (Negotiate) или AcceptSecurityContext (Negotiate). Если такой центр недоступен, функция завершится ошибкой и возвратит SEC_E_NO_AUTHENTICATING_AUTHORITY. Проверка зависит от пакета.
SECPKG_CRED_OUTBOUND	Разрешить учетным данным локального клиента подготовить исходящий маркер.
SECPKG_CRED_PROCESS_POLICY_ONLY 0x00000020	Функция обрабатывает политику сервера и возвращает SEC_E_NO_CREDENTIALS, указывая, что приложение должно запрашивать учетные данные. Windows Server 2008, Windows Vista, Windows Server 2003 и Windows XP: Это значение не поддерживается.

pvLogonID [in]

Указатель на локально уникальный идентификатор (LUID), который идентифицирует пользователя. Этот параметр предоставляется для процессов файловой системы, таких как перенаправление сети. Этот параметр может принимать значение NULL.

pAuthData [in]

Указатель на данные, относящиеся к конкретному пакету. Этот параметр может иметь значение NULL, указывающее, что для этого пакета безопасности должны использоваться учетные данные по умолчанию. Чтобы использовать предоставленные учетные данные, передайте структуру PSEC_WINNT_AUTH_IDENTITY_OPAQUE , возвращенную из предыдущего вызова функции SspiPromptForCredentials .

Windows Server 2008, Windows Vista, Windows Server 2003 и Windows XP: Тип PSEC_WINNT_AUTH_IDENTITY_OPAQUE и функция SspiPromptForCredentials не поддерживаются. Чтобы использовать предоставленные учетные данные, передайте указатель на SEC_WINNT_AUTH_IDENTITY или SEC_WINNT_AUTH_IDENTITY_EX структуру, включающую эти учетные данные.

Время выполнения RPC проходит все, что было предоставлено в RpcBindingSetAuthInfo.

При использовании пакета Negotiate максимальная длина символов для имени пользователя, пароля и домена составляет 256, 256 и 15 соответственно.

pGetKeyFn [in]

Этот параметр не используется и должен иметь значение NULL.

pvGetKeyArgument [in]

Этот параметр не используется и должен иметь значение NULL.

phCredential [out]

Указатель на структуру CredHandle для получения дескриптора учетных данных.

ptsExpiry [out]

Указатель на структуру TimeStamp , которая получает время истечения срока действия возвращенных учетных данных. Значение, возвращаемое в этой структуре TimeStamp, зависит от ограниченного делегирования. Пакет безопасности должен возвращать это значение в местное время.

Возвращаемое значение

Если функция завершается успешно, функция возвращает SEC_E_OK.

Если функция завершается сбоем, она возвращает один из следующих кодов ошибок.

Код возврата	Описание
SEC_E_INSUFFICIENT_MEMORY	Недостаточно памяти для выполнения запрошенного действия.
SEC_E_INTERNAL_ERROR	Произошла ошибка, не сопоставленная с кодом ошибки SSPI.
SEC_E_NO_CREDENTIALS	В ограниченном делегировании учетные данные недоступны.
SEC_E_NOT_OWNER	Вызывающий объект функции не имеет необходимых учетных данных.
SEC_E_SECPKG_NOT_FOUND	Запрошенный пакет безопасности не существует.
SEC_E_UNKNOWN_CREDENTIALS	Учетные данные, предоставленные пакету, не распознаны.

Функция AcquireCredentialsHandle (Negotiate) возвращает дескриптор учетных данных участника, например пользователя или клиента, используемый определенным ограниченным делегированием. Это может быть дескриптор для ранее существовающих учетных данных или функция может создать новый набор учетных данных и вернуть его. Этот дескриптор можно использовать в последующих вызовах функций AcceptSecurityContext (Negotiate) и InitializeSecurityContext (Negotiate).

Как правило, AcquireCredentialsHandle (Negotiate) не позволяет процессу получить дескриптор учетных данных других пользователей, выполнившего вход на тот же компьютер. Однако вызывающий объект с привилегией SE_TCB_NAME может указать идентификатор входа (LUID) любого существующего маркера сеанса входа, чтобы получить дескриптор учетных данных этого сеанса. Как правило, это используется модулями в режиме ядра, которые должны действовать от имени пользователя, выполнившего вход.

Пакет может вызывать функцию в pGetKeyFn , предоставляемую транспортом времени выполнения RPC. Если транспорт не поддерживает понятие обратного вызова для получения учетных данных, этот параметр должен иметь значение NULL.

Для вызывающих объектов режима ядра необходимо отметить следующие различия:

Два строковых параметра должны быть строками Юникода .
Значения буфера должны быть выделены в виртуальной памяти процесса, а не из пула.

Завершив использование возвращенных учетных данных, освободите память, используемую учетными данными, вызвав функцию FreeCredentialsHandle .

Требования

Требование	Значение
Минимальная версия клиента	Windows XP [только классические приложения]
Минимальная версия сервера	Windows Server 2003 [только классические приложения]
Заголовок	Sspi.h (включая Security.h)
Библиотека	Secur32.lib
DLL	Secur32.dll
Имя в кодировке Юникод и ANSI	AcquireCredentialsHandleW (Юникод) и AcquireCredentialsHandleA (ANSI)

См. также раздел

Функции SSPI
AcceptSecurityContext (Negotiate)
InitializeSecurityContext (Negotiate)
FreeCredentialsHandle

Поделиться через

Функция AcquireCredentialsHandle (Negotiate)

Синтаксис

Параметры

Возвращаемое значение

Комментарии

Требования

См. также раздел

Обратная связь

Дополнительные ресурсы