Função CoInitializeSecurity (combaseapi.h)
Registra a segurança e define os valores de segurança padrão para o processo.
Sintaxe
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
As permissões de acesso que um servidor usará para receber chamadas. Esse parâmetro é usado pelo COM somente quando um servidor chama CoInitializeSecurity. Seu valor é um ponteiro para um dos três tipos: um AppID, um objeto IAccessControl ou um SECURITY_DESCRIPTOR, em formato absoluto. Consulte a seção Comentários para obter mais informações.
[in] cAuthSvc
A contagem de entradas no parâmetro asAuthSvc . Esse parâmetro é usado pelo COM somente quando um servidor chama CoInitializeSecurity. Se esse parâmetro for 0, nenhum serviço de autenticação será registrado e o servidor não poderá receber chamadas seguras. Um valor de -1 instrui o COM a escolher quais serviços de autenticação registrar e, se esse for o caso, o parâmetro asAuthSvc deverá ser NULL. No entanto, o Schannel nunca será escolhido como um serviço de autenticação pelo servidor se esse parâmetro for -1.
[in, optional] asAuthSvc
Uma matriz de serviços de autenticação que um servidor está disposto a usar para receber uma chamada. Esse parâmetro é usado pelo COM somente quando um servidor chama CoInitializeSecurity. Para obter mais informações, consulte SOLE_AUTHENTICATION_SERVICE.
[in, optional] pReserved1
Esse parâmetro é reservado e deve ser NULL.
[in] dwAuthnLevel
O nível de autenticação padrão para o processo. Servidores e clientes usam esse parâmetro quando chamam CoInitializeSecurity. O COM falhará nas chamadas que chegam com um nível de autenticação mais baixo. Por padrão, todos os proxies usarão pelo menos esse nível de autenticação. Esse valor deve conter uma das constantes de nível de autenticação. Por padrão, todas as chamadas para IUnknown são feitas nesse nível.
[in] dwImpLevel
O nível de representação padrão para proxies. O valor desse parâmetro é usado somente quando o processo é um cliente. Deve ser um valor das constantes de nível de representação, exceto para RPC_C_IMP_LEVEL_DEFAULT, que não é para uso com CoInitializeSecurity.
As chamadas de saída do cliente sempre usam o nível de representação conforme especificado. (Não é negociado.) As chamadas de entrada para o cliente podem estar em qualquer nível de representação. Por padrão, todas as chamadas IUnknown são feitas com esse nível de representação, portanto, até mesmo aplicativos com reconhecimento de segurança devem definir esse nível com cuidado. Para determinar quais níveis de representação cada serviço de autenticação dá suporte, consulte a descrição dos serviços de autenticação em COM e pacotes de segurança. Para obter mais informações sobre níveis de representação, consulte Representação.
[in, optional] pAuthList
Um ponteiro para SOLE_AUTHENTICATION_LIST, que é uma matriz de estruturas SOLE_AUTHENTICATION_INFO . Essa lista indica as informações de cada serviço de autenticação que um cliente pode usar para chamar um servidor. Esse parâmetro é usado pelo COM somente quando um cliente chama CoInitializeSecurity.
[in] dwCapabilities
Recursos adicionais do cliente ou servidor, especificados definindo um ou mais valores de EOLE_AUTHENTICATION_CAPABILITIES . Alguns desses valores não podem ser usados simultaneamente e outros não podem ser definidos quando determinados serviços de autenticação estão sendo usados. Para obter mais informações sobre esses sinalizadores, consulte a seção Comentários.
[in, optional] pReserved3
Esse parâmetro é reservado e deve ser NULL.
Retornar valor
Essa função pode retornar o valor retornado padrão E_INVALIDARG, bem como os valores a seguir.
| Código de retorno | Descrição |
|---|---|
|
Indica êxito. |
|
CoInitializeSecurity já foi chamado. |
|
O parâmetro asAuthSvc não era NULL e nenhum dos serviços de autenticação na lista poderia ser registrado. Verifique os resultados salvos no asAuthSvc para códigos de erro específicos do serviço de autenticação. |
|
Sem memória. |
Comentários
A função CoInitializeSecurity inicializa a camada de segurança e define os valores especificados como o padrão de segurança. Se um processo não chamar CoInitializeSecurity, o COM o chamará automaticamente na primeira vez que uma interface for empacotada ou não registrada, registrando a segurança padrão do sistema. Nenhum pacote de segurança padrão é registrado até lá.
Essa função é chamada exatamente uma vez por processo, seja explicitamente ou implicitamente. Ele pode ser chamado pelo cliente, servidor ou ambos. Para aplicativos herdados e outros aplicativos que não chamam explicitamente CoInitializeSecurity, COM chama essa função implicitamente com valores do Registro. Se você definir a segurança em todo o processo usando o Registro e chamar CoInitializeSecurity, os valores do Registro appID serão ignorados e os valores de CoInitializeSecurity serão usados.
CoInitializeSecurity pode ser usado para substituir permissões de acesso em todo o computador e permissões de acesso específicas do aplicativo, mas não para substituir a política de restrição em todo o computador.
Se pSecDesc apontar para um AppID, o sinalizador EOAC_APPID deverá ser definido em dwCapabilities e, quando o sinalizador EOAC_APPID for definido, todos os outros parâmetros para CoInitializeSecurity serão ignorados. CoInitializeSecurity procura o nível de autenticação sob a chave AppID no registro e a usa para determinar a segurança padrão. Para obter mais informações sobre como a chave AppID é usada para definir a segurança, consulte Configurando Process-Wide segurança por meio do Registro.
Se pSecDesc for um ponteiro para um objeto IAccessControl , o sinalizador EOAC_ACCESS_CONTROL deverá ser definido e dwAuthnLevel não poderá ser nenhum. O objeto IAccessControl é usado para determinar quem pode chamar o processo. O DCOM adicionará o IAccessControl e o lançará quando CoUninitialize for chamado. O estado do objeto IAccessControl não deve ser alterado.
Se pSecDesc for um ponteiro para um SECURITY_DESCRIPTOR, nem o EOAC_APPID nem o sinalizador EOAC_ACCESS_CONTROL poderão ser definidos em dwCapabilities. O proprietário e o grupo do SECURITY_DESCRIPTOR devem ser definidos e, até que o DCOM dê suporte à auditoria, a ACL do sistema deve ser NULL. As ACEs (entradas de controle de acesso) na ACL discricionária (DACL) do SECURITY_DESCRIPTOR são usadas para descobrir quais chamadores têm permissão para se conectar aos objetos do processo. Uma DACL sem ACEs não permite acesso, enquanto uma DACL NULL permitirá chamadas de qualquer pessoa. Para obter mais informações sobre ACLs e ACEs, consulte Controle de Acesso Model. Os aplicativos devem chamar AccessCheck (não IsValidSecurityDescriptor) para garantir que seus SECURITY_DESCRIPTOR sejam formados corretamente antes de chamar CoInitializeSecurity.
Passar pSecDesc como NULL é altamente desencorajado. Uma alternativa apropriada pode ser usar uma SECURITY_DESCRIPTOR que permita a Todos. Se pSecDesc for NULL, os sinalizadores em dwCapabilities determinarão como CoInitializeSecurity define as permissões de acesso que um servidor usará, da seguinte maneira:
- Se o sinalizador EOAC_APPID estiver definido, CoInitializeSecurity procurará o nome .exe do aplicativo no registro e usará o AppID armazenado lá.
- Se o sinalizador EOAC_ACCESS_CONTROL estiver definido, CoInitializeSecurity retornará um erro.
- Se nem o sinalizador EOAC_APPID nem o sinalizador EOAC_ACCESS_CONTROL estiver definido, CoInitializeSecurity permitirá todos os chamadores, incluindo Usuários Anônimos Locais e Remotos.
Requisitos
| Requisito | Valor |
|---|---|
| Cliente mínimo com suporte | Windows 2000 Professional [aplicativos da área de trabalho | Aplicativos UWP] |
| Servidor mínimo com suporte | Windows 2000 Server [aplicativos da área de trabalho | Aplicativos UWP] |
| Plataforma de Destino | Windows |
| Cabeçalho | combaseapi.h (inclua Objbase.h) |
| Biblioteca | Ole32.lib |
| DLL | Ole32.dll |