Функция InitializeSecurityContext (CredSSP)
Функция InitializeSecurityContext (CredSSP) инициирует исходящий контекст безопасности на стороне клиента из дескриптора учетных данных. Функция создает контекст безопасности между клиентским приложением и удаленным одноранговым узлом. InitializeSecurityContext (CredSSP) возвращает маркер, который клиент должен передать удаленному одноранговому элементу; одноранговый узел, в свою очередь, отправляет этот маркер в локальную реализацию безопасности с помощью вызова AcceptSecurityContext (CredSSP). Созданный маркер должен считаться непрозрачным для всех вызывающих.
Обычно функция InitializeSecurityContext (CredSSP) вызывается в цикле, пока не будет установлен достаточный контекст безопасности.
Синтаксис
SECURITY_STATUS SEC_ENTRY InitializeSecurityContext(
_In_opt_ PCredHandle phCredential,
_In_opt_ PCtxtHandle phContext,
_In_opt_ SEC_CHAR *pszTargetName,
_In_ unsigned long fContextReq,
_Reserved_ unsigned long Reserved1,
_In_ unsigned long TargetDataRep,
_Inout_opt_ PSecBufferDesc pInput,
_In_ unsigned long Reserved2,
_Inout_opt_ PCtxtHandle phNewContext,
_Out_opt_ PSecBufferDesc pOutput,
_Out_ unsigned long *pfContextAttr,
_Out_opt_ PTimeStamp ptsExpiry
);
Параметры
phCredential[in, optional]
Дескриптор учетных данных, возвращенных AcquireCredentialsHandle (CredSSP). Этот дескриптор используется для создания контекста безопасности. Для функции InitializeSecurityContext (CredSSP) требуются по крайней мере учетные данные OUTBOUND.
phContext[in, optional]
Указатель на структуру CtxtHandle . При первом вызове Метода InitializeSecurityContext (CredSSP) этот указатель имеет значение NULL
. Во втором вызове этот параметр является указателем на дескриптор частично сформированного контекста, возвращаемого в параметре phNewContext при первом вызове.
При первом вызове Метода InitializeSecurityContext (CredSSP) укажите NULL
. При последующих вызовах укажите токен, полученный в параметре phNewContext после первого вызова этой функции.
Предупреждение
Не используйте один и тот же дескриптор контекста в одновременных вызовах InitializeSecurityContext (CredSSP). Реализация API в поставщиках служб безопасности не является потокобезопасной.
pTargetName[in, optional]
Указатель на строку, завершающуюся значением NULL, которая однозначно идентифицирует целевой сервер. Schannel использует это значение для проверки сертификата сервера. Schannel также использует это значение для поиска сеанса в кэше сеансов при повторном создании подключения. Кэшированный сеанс используется только в том случае, если выполняются все следующие условия:
- Имя целевого объекта совпадает.
- Срок действия записи кэша не истек.
- Процесс приложения, вызывающий функцию, совпадает.
- Сеанс входа в систему совпадает.
- Дескриптор учетных данных совпадает.
fContextReq[in]
Битовые флаги, указывающие запросы для контекста. Не все пакеты могут поддерживать все требования. Флаги, используемые для этого параметра, имеют префикс ISC_REQ_, например ISC_REQ_DELEGATE.
Этот параметр может быть одним или несколькими из следующих флагов атрибутов.
Значение | Значение |
---|---|
ISC_REQ_ALLOCATE_MEMORY0x100 |
Пакет безопасности выделяет выходные буферы для вызывающей стороны. Завершив использование буферов вывода, освободите их, вызвав функцию FreeContextBuffer . |
ISC_REQ_CONNECTION0x800 |
Контекст безопасности не будет обрабатывать сообщения форматирования. |
ISC_REQ_EXTENDED_ERROR0x4000 |
При возникновении ошибок удаленная сторона будет уведомлена. |
ISC_REQ_MANUAL_CRED_VALIDATION0x80000 |
Поставщик поддержки безопасности учетных данных (CredSSP) не должен автоматически проверять подлинность сервера. Этот флаг всегда устанавливается при использовании CredSSP. |
ISC_REQ_SEQUENCE_DETECT0x8 |
Обнаружение сообщений, полученных вне последовательности. |
ISC_REQ_STREAM0x8000 |
Поддержка потокового подключения. |
ISC_REQ_USE_SUPPLIED_CREDS0x80 |
CredSSP не должен пытаться автоматически предоставлять учетные данные для клиента. |
ISC_REQ_DELEGATE0x1 |
Указывает, что учетные данные пользователя должны быть делегированы серверу. Если этот флаг не указан, серверу делегируется пустой набор учетных данных. Windows Server 2008 и Windows Vista: Этот флаг является обязательным. |
ISC_REQ_MUTUAL_AUTH0x2 |
Указывает, что проверка подлинности сервера не требуется. Политики делегирования по-прежнему применяются, если этот флаг не указан. Windows Server 2008 и Windows Vista: Этот флаг игнорируется. |
Запрошенные атрибуты могут не поддерживаться клиентом. Дополнительные сведения см. в параметре pfContextAttr .
Дополнительные описания различных атрибутов см. в разделе Требования к контексту.
Зарезервировано1[in]
Зарезервировано. Для этого параметра необходимо задать нулевое значение.
TargetDataRep[in]
Представление данных, например порядок байтов, в целевом объекте. Этот параметр может быть SECURITY_NATIVE_DREP или SECURITY_NETWORK_DREP.
pInput[in, out, optional]
Указатель на структуру SecBufferDesc , содержащую указатели на буферы, предоставленные в качестве входных данных для пакета. Если контекст клиента не был инициирован сервером, значение этого параметра должно быть NULL
при первом вызове функции. При последующих вызовах функции или при инициировании контекста клиента сервером значение этого параметра является указателем на буфер, выделенный с достаточным объемом памяти для хранения маркера, возвращенного удаленным компьютером.
При вызове этой функции после первоначального вызова должно быть два буфера. Первый имеет тип SECBUFFER_TOKEN и содержит маркер, полученный от сервера. Второй буфер имеет тип SECBUFFER_EMPTY; Установите для обоих элементов pvBuffer и cbBuffer значение 0.
Зарезервировано2[in]
Зарезервировано. Для этого параметра необходимо задать нулевое значение.
phNewContext[in, out, optional]
Указатель на структуру CtxtHandle . При первом вызове Метода InitializeSecurityContext (CredSSP) этот указатель получает новый дескриптор контекста. Во втором вызове phNewContext может совпадать с дескриптором, указанным в параметре phContext .
PhNewContext никогда не должен иметь значение NULL
.
pOutput[out, optional]
Указатель на структуру SecBufferDesc . Эта структура, в свою очередь, содержит указатели на структуру SecBuffer , которая получает выходные данные. Если буфер был введен как SEC_READWRITE во входных данных, он будет там на выходе. Система выделяет буфер для маркера безопасности при запросе (через ISC_REQ_ALLOCATE_MEMORY) и заполняет адрес в дескрипторе буфера для маркера безопасности.
Если указан флаг ISC_REQ_ALLOCATE_MEMORY , CredSSP выделяет память для буфера и помещает соответствующие сведения в SecBufferDesc.
pfContextAttr[out]
Указатель на набор битовых флагов, указывающих атрибуты установленного контекста. Описание различных атрибутов см. в разделе Требования к контексту.
Флаги, используемые для этого параметра, имеют префикс ISC_RET, например ISC_RET_DELEGATE. Список допустимых значений см. в параметре fContextReq .
Не проверка атрибутов, связанных с безопасностью, до тех пор, пока не будет успешно выполнен окончательный вызов функции. Флаги атрибутов, не связанные с безопасностью, такие как флаг ASC_RET_ALLOCATED_MEMORY , можно проверить перед окончательным возвратом.
Примечание
Определенные атрибуты контекста могут изменяться во время согласования с удаленным одноранговым элементом.
ptsExpiry[out, optional]
Указатель на структуру TimeStamp , которая получает время истечения срока действия контекста. Рекомендуется, чтобы пакет безопасности всегда возвращал это значение в местное время. Этот параметр является необязательным и NULL
должен передаваться для кратковременных клиентов.
Возвращаемое значение
Если функция выполняется успешно, она возвращает один из следующих кодов успешного выполнения.
Код возврата | Описание |
---|---|
SEC_E_INCOMPLETE_MESSAGE | Данные для всего сообщения не были считаны из провода. При возвращении этого значения буфер pInput содержит структуру SecBuffer с элементом BufferTypeSECBUFFER_MISSING. Член cbBufferэлемента SecBuffer указывает количество дополнительных байтов, которые функция должна считывать у клиента, прежде чем эта функция будет успешно выполнена. Хотя это число не всегда является точным, его использование может помочь повысить производительность, избегая нескольких вызовов этой функции. |
SEC_E_OK | Контекст безопасности успешно инициализирован. Другой вызов InitializeSecurityContext (CredSSP) не требуется . Если функция возвращает выходной токен, то есть если SECBUFFER_TOKEN в pOutput имеет ненулевое значение, этот маркер должен быть отправлен на сервер. |
SEC_I_COMPLETE_AND_CONTINUE | Клиент должен вызвать CompleteAuthToken , а затем передать выходные данные серверу. Затем клиент ожидает возвращенного маркера и передает его в другом вызове в Приложение InitializeSecurityContext (CredSSP). |
SEC_I_COMPLETE_NEEDED | Клиент должен завершить сборку сообщения, а затем вызвать функцию CompleteAuthToken . |
SEC_I_CONTINUE_NEEDED | Клиент должен отправить выходной маркер на сервер и дождаться возврата маркера. Клиент передает возвращенный маркер в другом вызове Метода InitializeSecurityContext (CredSSP). Выходной маркер может быть пустым. |
SEC_I_INCOMPLETE_CREDENTIALS | Сервер запросил проверку подлинности клиента, но предоставленные учетные данные не включают сертификат, или сертификат не был выдан центром сертификации, которому сервер доверяет. Дополнительные сведения см. в подразделе "Примечания". |
Если функция завершается ошибкой, функция возвращает один из следующих кодов ошибок.
Код возврата | Описание |
---|---|
SEC_E_INSUFFICIENT_MEMORY | Недостаточно памяти для выполнения запрошенного действия. |
SEC_E_INTERNAL_ERROR | Произошла ошибка, не сопоставленная с кодом ошибки SSPI. |
SEC_E_INVALID_HANDLE | Дескриптор, переданный функции, недопустим. |
SEC_E_INVALID_TOKEN | Входной маркер имеет неправильный формат. Возможные причины включают повреждение маркера при передаче, маркер неправильного размера и маркер, переданный в неправильный пакет безопасности. Последнее условие может произойти, если клиент и сервер не согласуют правильный пакет безопасности. |
SEC_E_LOGON_DENIED | Сбой входа. |
SEC_E_NO_AUTHENTICATING_AUTHORITY | Невозможно связаться с центром для проверки подлинности. Доменное имя стороны, проверяющей подлинность, может быть неправильным, домен может быть недостижимым или произошел сбой отношения доверия. |
SEC_E_NO_CREDENTIALS | В пакете безопасности отсутствуют учетные данные. |
SEC_E_TARGET_UNKNOWN | Цель не распознана. |
SEC_E_UNSUPPORTED_FUNCTION | Недопустимое значение параметра fContextReq . Либо не указан обязательный флаг, либо был указан флаг, который не поддерживается CredSSP. |
SEC_E_WRONG_PRINCIPAL | Субъект, получивший запрос проверки подлинности, отличается от субъекта, переданного в параметр pszTargetName . Эта ошибка указывает на сбой во взаимной проверке подлинности. |
SEC_E_DELEGATION_POLICY | Политика не поддерживает делегирование учетных данных на целевой сервер. |
SEC_E_POLICY_NLTM_ONLY | Делегирование учетных данных на целевой сервер не допускается, если не выполняется взаимная проверка подлинности. |
SEC_E_MUTUAL_AUTH_FAILED | Проверка подлинности сервера завершилась сбоем, если флаг ISC_REQ_MUTUAL_AUTH указан в параметре fContextReq . |
Комментарии
Вызывающий объект отвечает за определение достаточности атрибутов конечного контекста. Если, например, была запрошена конфиденциальность, но ее не удалось установить, некоторые приложения могут немедленно завершить подключение.
Если атрибутов контекста безопасности недостаточно, клиент должен освободить частично созданный контекст, вызвав функцию DeleteSecurityContext .
Клиент вызывает функцию InitializeSecurityContext (CredSSP) для инициализации исходящего контекста.
Для двухуровневого контекста безопасности последовательность вызовов выглядит следующим образом:
- Клиент вызывает функцию с параметром phContext и
NULL
заполняет дескриптор буфера входным сообщением. - Пакет безопасности проверяет параметры и создает непрозрачный маркер, помещая его в элемент TOKEN в буферном массиве. Если параметр fContextReq содержит флаг ISC_REQ_ALLOCATE_MEMORY , пакет безопасности выделяет память и возвращает указатель в элементе TOKEN.
- Клиент отправляет маркер, возвращенный в буфере POutput , на целевой сервер. Затем сервер передает маркер в качестве входного аргумента в вызове функции AcceptSecurityContext (CredSSP).
- AcceptSecurityContext (CredSSP) может возвращать маркер. Сервер отправляет этот маркер клиенту через второй вызов InitializeSecurityContext (CredSSP), если первый вызов вернул SEC_I_CONTINUE_NEEDED.
Если сервер успешно ответил, пакет безопасности возвращает SEC_E_OK и устанавливается безопасный сеанс.
Если функция возвращает один из ответов об ошибке, ответ сервера не принимается, и сеанс не устанавливается.
Если функция возвращает SEC_I_CONTINUE_NEEDED, SEC_I_COMPLETE_NEEDED или SEC_I_COMPLETE_AND_CONTINUE, шаги 2 и 3 повторяются.
Для инициализации контекста безопасности может потребоваться несколько вызовов этой функции в зависимости от базового механизма проверки подлинности, а также от вариантов, указанных в параметре fContextReq .
Параметры fContextReq и pfContextAttributes представляют собой битовые маски, представляющие различные атрибуты контекста. Описание различных атрибутов см. в разделе Требования к контексту. Хотя параметр pfContextAttributes действителен при любом успешном возвращении, следует изучить флаги, относящиеся к аспектам безопасности контекста, только при окончательном успешном возвращении. Промежуточные возвраты могут задавать, например, флаг ISC_RET_ALLOCATED_MEMORY .
Если установлен флаг ISC_REQ_USE_SUPPLIED_CREDS , пакет безопасности должен искать тип буфера SECBUFFER_PKG_PARAMS во входном буфере pInput . Хотя это и не является универсальным решением, оно позволяет надежно связать пакет безопасности и приложение, когда это необходимо.
Если указан ISC_REQ_ALLOCATE_MEMORY , вызывающий объект должен освободить память, вызвав функцию FreeContextBuffer .
Например, входной маркер может быть проблемой от диспетчера локальной сети. В этом случае выходной маркер будет ответом на запрос с шифрованием NTLM.
Действия, которые выполняет клиент, зависят от кода, возвращаемого этой функцией. Если код возврата SEC_E_OK, второй вызов InitializeSecurityContext (CredSSP) не будет выполняться, а ответ от сервера не ожидается. Если код возврата SEC_I_CONTINUE_NEEDED, клиент ожидает маркер в ответ от сервера и передает его во втором вызове InitializeSecurityContext (CredSSP). Код возврата SEC_I_COMPLETE_NEEDED указывает, что клиент должен завершить сборку сообщения и вызвать функцию CompleteAuthToken . Код SEC_I_COMPLETE_AND_CONTINUE включает в себя оба этих действия.
Если InitializeSecurityContext (CredSSP) возвращает успешное выполнение при первом (или только) вызове, вызывающий объект должен в конечном итоге вызвать функцию DeleteSecurityContext для возвращенного дескриптора, даже если вызов завершается сбоем на более позднем этапе обмена проверкой подлинности.
Клиент может снова вызвать InitializeSecurityContext (CredSSP) после успешного завершения. Это указывает пакету безопасности на то, что требуется повторная проверку подлинности.
Вызывающие объекты режима ядра имеют следующие отличия: целевое имя — это строка Юникода , которая должна быть выделена в виртуальной памяти с помощью VirtualAlloc; Он не должен быть выделен из пула. Буферы, переданные и предоставленные в pInput и pOutput , должны находиться в виртуальной памяти, а не в пуле.
Если функция возвращает SEC_I_INCOMPLETE_CREDENTIALS, проверка, что в учетных данных r, переданных функции AcquireCredentialsHandle (CredSSP), указан действительный и доверенный сертификат. Сертификат должен быть сертификатом проверки подлинности клиента, выданным центром сертификации, которому доверяет сервер. Чтобы получить список ЦС, доверенных сервером, вызовите функцию QueryContextAttributes (CredSSP) с атрибутом SECPKG_ATTR_ISSUER_LIST_EX .
После получения сертификата проверки подлинности от центра сертификации, которому сервер доверяет, клиентское приложение создает новые учетные данные. Для этого вызовите функцию AcquireCredentialsHandle (CredSSP), а затем снова вызовите InitializeSecurityContext (CredSSP), указав новые учетные данные в параметре phCredential .
Требования
Требование | Значение |
---|---|
Минимальная версия клиента | Windows Vista [только классические приложения] |
Минимальная версия сервера | Windows Server 2008 [только классические приложения] |
Заголовок | Sspi.h (включая Security.h) |
Библиотека | Secur32.lib |
DLL | Secur32.dll |
См. также раздел
AcceptSecurityContext (CredSSP)