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

Функция AcquireCredentialsHandle (CredSSP)

  • Статья

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

Примечание

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

Синтаксис

SECURITY_STATUS SEC_ENTRY AcquireCredentialsHandle(
  _In_opt_   SEC_CHAR       *pszPrincipal,
  _In_       SEC_CHAR       *pszPackage,
  _In_       unsigned long  fCredentialUse,
  _In_opt_   void           *pvLogonID,
  _In_opt_   void           *pAuthData,
  _In_opt_   SEC_GET_KEY_FN pGetKeyFn,
  _Reserved_ void           *pvGetKeyArgument,
  _Out_      PCredHandle    phCredential,
  _Out_opt_  PTimeStamp     ptsExpiry
);

Параметры

pszPrincipal [in, optional]

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

Примечание

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

pszPackage [in]

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

fCredentialUse [in]

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

Значение Значение
SECPKG_CRED_INBOUND
0x1		 Проверка учетных данных входящего сервера. Входящие учетные данные могут проверяться с помощью центра проверки подлинности при вызове Метода InitializeSecurityContext (CredSSP) или AcceptSecurityContext (CredSSP). Если такой центр недоступен, функция завершится ошибкой и возвратит SEC_E_NO_AUTHENTICATING_AUTHORITY. Проверка зависит от пакета
SECPKG_CRED_OUTBOUND
0x0		 Разрешить учетным данным локального клиента подготовить исходящий маркер.

pvLogonId [in, необязательный]

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

pAuthData [in, необязательный]

Указатель на структуру CREDSSP_CRED , указывающую данные проверки подлинности для пакетов Schannel и Negotiate.

pGetKeyFn [в, необязательно]

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

pvGetKeyArgument [в, необязательно]

Зарезервировано. Для этого параметра необходимо задать значение NULL.

phCredential [out]

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

ptsExpiry [out, optional]

Указатель на структуру 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 (CredSSP) возвращает дескриптор учетным данным субъекта, например пользователя или клиента, используемый определенным пакетом безопасности. Функция может возвращать дескриптор либо ранее существовавших учетных данных, либо только что созданным учетным данным и возвращать его. Этот дескриптор можно использовать в последующих вызовах функций AcceptSecurityContext (CredSSP) и InitializeSecurityContext (CredSSP).

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

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

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

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

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

Требования

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

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