Функция AcquireCredentialsHandle (Schannel)

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

Синтаксис

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

Параметры

pszPrincipal[in, optional]

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

При использовании Schannel SSP этот параметр не используется и должен иметь значение NULL.

pszPackage[in]

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

При использовании Schannel SSP задайте для этого параметра значение UNISP_NAME.

fCredentialUse[in]

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

pvLogonID[in, optional]

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

При использовании Schannel SSP этот параметр не используется и должен иметь значение NULL.

pAuthData[in, optional]

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

При использовании Schannel SSP укажите SCH_CREDENTIALS структуру, которая указывает протокол для использования и параметры различных настраиваемых функций канала.

pGetKeyFn[in, optional]

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

pvGetKeyArgument[in, optional]

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

phCredential[out]

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

ptsExpiry[out, optional]

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

При использовании Schannel SSP этот параметр является необязательным. Когда учетные данные, используемые для проверки подлинности, являются сертификатом, этот параметр получает время окончания срока действия этого сертификата. Если сертификат не указан, возвращается максимальное значение времени.

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

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

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

Замечания

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

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

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

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

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

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

Требования

См. также

AcceptSecurityContext (Schannel)

FreeCredentialsHandle

InitializeSecurityContext (Schannel)

SCH_CREDENTIALS

Функции SSPI