Функция CoInitializeSecurity (combaseapi.h)
Регистрирует безопасность и задает значения безопасности по умолчанию для процесса.
Синтаксис
HRESULT CoInitializeSecurity(
[in, optional] PSECURITY_DESCRIPTOR pSecDesc,
[in] LONG cAuthSvc,
[in, optional] SOLE_AUTHENTICATION_SERVICE *asAuthSvc,
[in, optional] void *pReserved1,
[in] DWORD dwAuthnLevel,
[in] DWORD dwImpLevel,
[in, optional] void *pAuthList,
[in] DWORD dwCapabilities,
[in, optional] void *pReserved3
);
Параметры
[in, optional] pSecDesc
Разрешения на доступ, которые сервер будет использовать для приема вызовов. Этот параметр используется COM только в том случае, если сервер вызывает CoInitializeSecurity. Его значение представляет собой указатель на один из трех типов: AppID, объект IAccessControl или SECURITY_DESCRIPTOR в абсолютном формате. Дополнительные сведения см. в разделе "Примечания".
[in] cAuthSvc
Количество записей в параметре asAuthSvc . Этот параметр используется COM только в том случае, если сервер вызывает CoInitializeSecurity. Если этот параметр имеет значение 0, службы проверки подлинности не будут зарегистрированы, и сервер не сможет принимать безопасные вызовы. Значение -1 указывает COM выбрать, какие службы проверки подлинности следует зарегистрировать, и в этом случае параметр asAuthSvc должен иметь значение NULL. Однако сервер никогда не будет выбирать Schannel в качестве службы проверки подлинности, если этот параметр имеет значение -1.
[in, optional] asAuthSvc
Массив служб проверки подлинности, которые сервер готов использовать для приема вызова. Этот параметр используется COM только в том случае, если сервер вызывает CoInitializeSecurity. Дополнительные сведения см. в разделе SOLE_AUTHENTICATION_SERVICE.
[in, optional] pReserved1
Этот параметр зарезервирован и должен иметь значение NULL.
[in] dwAuthnLevel
Уровень проверки подлинности по умолчанию для процесса. Серверы и клиенты используют этот параметр при вызове CoInitializeSecurity. COM завершится сбоем вызовов, поступающих с более низким уровнем проверки подлинности. По умолчанию все прокси-серверы будут использовать по крайней мере этот уровень проверки подлинности. Это значение должно содержать одну из констант уровня проверки подлинности. По умолчанию все вызовы iUnknown выполняются на этом уровне.
[in] dwImpLevel
Уровень олицетворения по умолчанию для прокси-серверов. Значение этого параметра используется только в том случае, если процесс является клиентом. Это должно быть значение из констант уровня олицетворения, за исключением RPC_C_IMP_LEVEL_DEFAULT, которое не предназначено для использования с CoInitializeSecurity.
Исходящие вызовы от клиента всегда используют уровень олицетворения, как указано. (Она не согласована.) Входящие вызовы к клиенту могут осуществляться на любом уровне олицетворения. По умолчанию все вызовы IUnknown выполняются с этим уровнем олицетворения, поэтому даже приложения с поддержкой безопасности должны устанавливать этот уровень осторожно. Чтобы определить, какие уровни олицетворения поддерживает каждая служба проверки подлинности, см. описание служб проверки подлинности в com и пакетах безопасности. Дополнительные сведения об уровнях олицетворения см. в разделе Олицетворение.
[in, optional] pAuthList
Указатель на SOLE_AUTHENTICATION_LIST, представляющий собой массив SOLE_AUTHENTICATION_INFO структур. В этом списке указаны сведения для каждой службы проверки подлинности, которую клиент может использовать для вызова сервера. Этот параметр используется COM только в том случае, если клиент вызывает CoInitializeSecurity.
[in] dwCapabilities
Дополнительные возможности клиента или сервера, заданные путем установки одного или нескольких EOLE_AUTHENTICATION_CAPABILITIES значений . Некоторые из этих значений нельзя использовать одновременно, а некоторые — при использовании определенных служб проверки подлинности. Дополнительные сведения об этих флагах см. в разделе Примечания.
[in, optional] pReserved3
Этот параметр зарезервирован и должен иметь значение NULL.
Возвращаемое значение
Эта функция может возвращать стандартное возвращаемое значение E_INVALIDARG, а также следующие значения.
| Код возврата | Описание |
|---|---|
|
Указывает на успешное завершение. |
|
CoInitializeSecurity уже вызван. |
|
Параметр asAuthSvc не имеет значения NULL, и ни одна из служб проверки подлинности в списке не может быть зарегистрирована. Проверьте результаты, сохраненные в asAuthSvc , на наличие кодов ошибок, относящихся к службе проверки подлинности. |
|
Недостаточно памяти. |
Комментарии
Функция CoInitializeSecurity инициализирует уровень безопасности и задает указанные значения в качестве значения безопасности по умолчанию. Если процесс не вызывает CoInitializeSecurity, COM вызывает его автоматически при первом маршале или отмене маршалинга интерфейса, регистрируя системную безопасность по умолчанию. До этого момента пакеты безопасности по умолчанию не регистрируются.
Эта функция вызывается ровно один раз для каждого процесса( явным или неявным образом). Он может вызываться клиентом, сервером или и тем, и другим. Для устаревших приложений и других приложений, которые явно не вызывают CoInitializeSecurity, COM вызывает эту функцию неявно со значениями из реестра. Если вы настроите безопасность на уровне процесса с помощью реестра, а затем вызовите CoInitializeSecurity, значения реестра AppID будут игнорироваться, а значения CoInitializeSecurity будут использоваться.
CoInitializeSecurity можно использовать для переопределения как разрешений доступа на уровне компьютера, так и разрешений доступа для конкретных приложений, но не для переопределения политики ограничений на уровне компьютера.
Если pSecDesc указывает на AppID, флаг EOAC_APPID должен быть установлен в dwCapabilities , а при установке флага EOAC_APPID все остальные параметры CoInitializeSecurity игнорируются. CoInitializeSecurity ищет уровень проверки подлинности в разделе AppID в реестре и использует его для определения безопасности по умолчанию. Дополнительные сведения о том, как ключ AppID используется для настройки безопасности, см. в разделе Настройка Process-Wide безопасности с помощью реестра.
Если pSecDesc является указателем на объект IAccessControl , необходимо задать флаг EOAC_ACCESS_CONTROL, а параметр dwAuthnLevel не может иметь значение none. Объект IAccessControl используется для определения того, кто может вызывать процесс. DCOM добавит значениеIAccessControl и отпустит его при вызове CoUninitialize . Состояние объекта IAccessControl не должно изменяться.
Если pSecDesc является указателем на SECURITY_DESCRIPTOR, в dwCapabilities нельзя задать ни EOAC_APPID, ни флаг EOAC_ACCESS_CONTROL. Необходимо задать владельца и группу SECURITY_DESCRIPTOR , и до тех пор, пока DCOM не будет поддерживать аудит, системный ACL должен иметь значение NULL. Записи управления доступом (ACE) в списке управления доступом (DACL) SECURITY_DESCRIPTOR используются для определения того, каким вызывающим объектам разрешено подключаться к объектам процесса. DACL без ACE не разрешает доступ, а DACL NULL разрешает вызовы от любого пользователя. Дополнительные сведения о списках управления доступом и ACE см. в разделе Модель контроль доступа. Приложения должны вызывать AccessCheck (а не IsValidSecurityDescriptor), чтобы убедиться, что их SECURITY_DESCRIPTOR правильно сформированы перед вызовом CoInitializeSecurity.
Передача pSecDesc в качестве NULL настоятельно не рекомендуется. Подходящим вариантом может быть использование SECURITY_DESCRIPTOR , которая позволяет всем. Если pSecDesc имеет значение NULL, флаги в dwCapabilities определяют, как CoInitializeSecurity определяет разрешения доступа, которые будет использовать сервер, следующим образом:
- Если установлен флаг EOAC_APPID, CoInitializeSecurity будет искать имя .exe приложения в реестре и использовать хранящийся в нем идентификатор AppID.
- Если установлен флаг EOAC_ACCESS_CONTROL, CoInitializeSecurity вернет ошибку.
- Если ни флаг EOAC_APPID, ни флаг EOAC_ACCESS_CONTROL не задан, CoInitializeSecurity разрешает всем вызывающим абонентам, включая локальных и удаленных анонимных пользователей.
Требования
| Требование | Значение |
|---|---|
| Минимальная версия клиента | Windows 2000 Профессиональная [классические приложения | Приложения UWP] |
| Минимальная версия сервера | Windows 2000 Server [классические приложения | Приложения UWP] |
| Целевая платформа | Windows |
| Header | combaseapi.h (включая Objbase.h) |
| Библиотека | Ole32.lib |
| DLL | Ole32.dll |