Función CoInitializeSecurity (combaseapi.h)

Registra la seguridad y establece los valores de seguridad predeterminados para el proceso.

Sintaxis

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
);

Parámetros

[in, optional] pSecDesc

Permisos de acceso que un servidor usará para recibir llamadas. COM usa este parámetro solo cuando un servidor llama a CoInitializeSecurity. Su valor es un puntero a uno de los tres tipos: un AppID, un objeto IAccessControl o un SECURITY_DESCRIPTOR, en formato absoluto. Vea la sección Comentarios para obtener más información.

[in] cAuthSvc

Recuento de entradas en el parámetro asAuthSvc . COM usa este parámetro solo cuando un servidor llama a CoInitializeSecurity. Si este parámetro es 0, no se registrarán servicios de autenticación y el servidor no podrá recibir llamadas seguras. Un valor de -1 indica a COM que elija qué servicios de autenticación se van a registrar y, si es así, el parámetro asAuthSvc debe ser NULL. Sin embargo, el servidor nunca elegirá Schannel como un servicio de autenticación si este parámetro es -1.

[in, optional] asAuthSvc

Matriz de servicios de autenticación que un servidor está dispuesto a usar para recibir una llamada. COM usa este parámetro solo cuando un servidor llama a CoInitializeSecurity. Para obtener más información, consulte SOLE_AUTHENTICATION_SERVICE.

[in, optional] pReserved1

Este parámetro está reservado y debe ser NULL.

[in] dwAuthnLevel

Nivel de autenticación predeterminado para el proceso. Tanto los servidores como los clientes usan este parámetro cuando llaman a CoInitializeSecurity. COM producirá un error en las llamadas que llegan con un nivel de autenticación inferior. De forma predeterminada, todos los servidores proxy usarán al menos este nivel de autenticación. Este valor debe contener una de las constantes de nivel de autenticación. De forma predeterminada, todas las llamadas a IUnknown se realizan en este nivel.

[in] dwImpLevel

Nivel de suplantación predeterminado para servidores proxy. El valor de este parámetro solo se usa cuando el proceso es un cliente. Debe ser un valor de las constantes de nivel de suplantación, excepto por RPC_C_IMP_LEVEL_DEFAULT, que no se usa con CoInitializeSecurity.

Las llamadas salientes del cliente siempre usan el nivel de suplantación como se especifica. (No se negocia). Las llamadas entrantes al cliente pueden estar en cualquier nivel de suplantación. De forma predeterminada, todas las llamadas IUnknown se realizan con este nivel de suplantación, por lo que incluso las aplicaciones compatibles con la seguridad deben establecer este nivel cuidadosamente. Para determinar qué niveles de suplantación admite cada servicio de autenticación, consulte la descripción de los servicios de autenticación en COM y paquetes de seguridad. Para obtener más información sobre los niveles de suplantación, vea Suplantación.

[in, optional] pAuthList

Puntero a SOLE_AUTHENTICATION_LIST, que es una matriz de estructuras de SOLE_AUTHENTICATION_INFO . Esta lista indica la información de cada servicio de autenticación que un cliente puede usar para llamar a un servidor. COM usa este parámetro solo cuando un cliente llama a CoInitializeSecurity.

[in] dwCapabilities

Funcionalidades adicionales del cliente o servidor, especificadas estableciendo uno o varios valores de EOLE_AUTHENTICATION_CAPABILITIES . Algunos de estos valores no se pueden usar simultáneamente y algunos no se pueden establecer cuando se usan servicios de autenticación concretos. Para obtener más información sobre estas marcas, vea la sección Comentarios.

[in, optional] pReserved3

Este parámetro está reservado y debe ser NULL.

Valor devuelto

Esta función puede devolver el valor devuelto estándar E_INVALIDARG, así como los siguientes valores.

Comentarios

La función CoInitializeSecurity inicializa la capa de seguridad y establece los valores especificados como valor predeterminado de seguridad. Si un proceso no llama a CoInitializeSecurity, COM lo llama automáticamente la primera vez que se serializa una interfaz o se anula la selección, registrando la seguridad predeterminada del sistema. No se registran paquetes de seguridad predeterminados hasta entonces.

Esta función se llama exactamente una vez por proceso, ya sea explícita o implícitamente. Puede llamarlo el cliente, el servidor o ambos. Para las aplicaciones heredadas y otras aplicaciones que no llaman explícitamente a CoInitializeSecurity, COM llama a esta función implícitamente con valores del registro. Si establece la seguridad de todo el proceso mediante el Registro y, a continuación, llama a CoInitializeSecurity, se omitirán los valores del Registro appID y se usarán los valores de CoInitializeSecurity .

CoInitializeSecurity se puede usar para invalidar los permisos de acceso en todo el equipo y los permisos de acceso específicos de la aplicación, pero no para invalidar la directiva de restricción en todo el equipo.

Si pSecDesc apunta a un AppID, la marca EOAC_APPID debe establecerse en dwCapabilities y, cuando se establece la marca EOAC_APPID, se omiten todos los demás parámetros en CoInitializeSecurity . CoInitializeSecurity busca el nivel de autenticación en la clave AppID del Registro y lo usa para determinar la seguridad predeterminada. Para obtener más información sobre cómo se usa la clave AppID para establecer la seguridad, vea Establecer Process-Wide seguridad a través del Registro.

Si pSecDesc es un puntero a un objeto IAccessControl , la marca EOAC_ACCESS_CONTROL debe establecerse y dwAuthnLevel no puede ser ninguna. El objeto IAccessControl se usa para determinar quién puede llamar al proceso. DCOM agregaráIAccessControl y lo liberará cuando se llame a CoUninitialize . No se debe cambiar el estado del objeto IAccessControl .

Si pSecDesc es un puntero a un SECURITY_DESCRIPTOR, ni el EOAC_APPID ni la marca EOAC_ACCESS_CONTROL se pueden establecer en dwCapabilities. El propietario y el grupo del SECURITY_DESCRIPTOR deben establecerse y, hasta que DCOM admita la auditoría, la ACL del sistema debe ser NULL. Las entradas de control de acceso (ACE) de la ACL discrecional (DACL) de la SECURITY_DESCRIPTOR se usan para averiguar qué autores de llamada pueden conectarse a los objetos del proceso. Una DACL sin ACL no permite acceso, mientras que una DACL NULL permitirá llamadas de cualquier persona. Para obtener más información sobre las ACL y las ACL, vea modelo de Access Control. Las aplicaciones deben llamar a AccessCheck (no IsValidSecurityDescriptor) para asegurarse de que su SECURITY_DESCRIPTOR se forma correctamente antes de llamar a CoInitializeSecurity.

No se recomienda pasar pSecDesc como NULL . Una alternativa adecuada podría ser usar una SECURITY_DESCRIPTOR que permita a todos. Si pSecDesc es NULL, las marcas de dwCapabilities determinan cómo CoInitializeSecurity define los permisos de acceso que usará un servidor, como se indica a continuación:

• Si se establece la marca EOAC_APPID, CoInitializeSecurity buscará el nombre de .exe de la aplicación en el registro y usará el AppID almacenado allí.
• Si se establece la marca EOAC_ACCESS_CONTROL, CoInitializeSecurity devolverá un error.
• Si no se establece la marca de EOAC_APPID ni la marca EOAC_ACCESS_CONTROL, CoInitializeSecurity permite a todos los autores de llamadas, incluidos los usuarios anónimos locales y remotos.

Requisitos

Consulte también

CoSetProxyBlanket

Seguridad en COM