Condividi tramite


Funzione CoInitializeSecurity (combaseapi.h)

Registra la sicurezza e imposta i valori di sicurezza predefiniti per il processo.

Sintassi

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

Parametri

[in, optional] pSecDesc

Autorizzazioni di accesso usate da un server per ricevere chiamate. Questo parametro viene usato da COM solo quando un server chiama CoInitializeSecurity. Il valore è un puntatore a uno dei tre tipi: appID, un oggetto IAccessControl o un SECURITY_DESCRIPTOR in formato assoluto. Per altre informazioni, vedere la sezione Osservazioni.

[in] cAuthSvc

Numero di voci nel parametro asAuthSvc . Questo parametro viene usato da COM solo quando un server chiama CoInitializeSecurity. Se questo parametro è 0, non verranno registrati servizi di autenticazione e il server non può ricevere chiamate sicure. Il valore -1 indica a COM di scegliere quali servizi di autenticazione registrare e, se si tratta del caso, il parametro asAuthSvc deve essere NULL. Tuttavia, Schannel non verrà mai scelto come servizio di autenticazione dal server se questo parametro è -1.

[in, optional] asAuthSvc

Matrice di servizi di autenticazione che un server è disposto a usare per ricevere una chiamata. Questo parametro viene usato da COM solo quando un server chiama CoInitializeSecurity. Per altre informazioni, vedere SOLE_AUTHENTICATION_SERVICE.

[in, optional] pReserved1

Questo parametro è riservato e deve essere NULL.

[in] dwAuthnLevel

Livello di autenticazione predefinito per il processo. Entrambi i server e i client usano questo parametro quando chiamano CoInitializeSecurity. Le chiamate COM avranno esito negativo che arrivano con un livello di autenticazione inferiore. Per impostazione predefinita, tutti i proxy useranno almeno questo livello di autenticazione. Questo valore deve contenere una delle costanti del livello di autenticazione. Per impostazione predefinita, tutte le chiamate a IUnknown vengono effettuate a questo livello.

[in] dwImpLevel

Livello di rappresentazione predefinito per i proxy. Il valore di questo parametro viene usato solo quando il processo è un client. Deve essere un valore dalle costanti del livello di rappresentazione, ad eccezione di RPC_C_IMP_LEVEL_DEFAULT, che non è per l'uso con CoInitializeSecurity.

Le chiamate in uscita dal client usano sempre il livello di rappresentazione come specificato. (Non è negoziata). Le chiamate in ingresso al client possono essere a qualsiasi livello di rappresentazione. Per impostazione predefinita, tutte le chiamate IUnknown vengono effettuate con questo livello di rappresentazione, quindi anche le applicazioni con riconoscimento della sicurezza devono impostare attentamente questo livello. Per determinare quali livelli di rappresentazione supporta ogni servizio di autenticazione, vedere la descrizione dei servizi di autenticazione in COM e pacchetti di sicurezza. Per altre informazioni sui livelli di rappresentazione, vedere Rappresentazione.

[in, optional] pAuthList

Puntatore a SOLE_AUTHENTICATION_LIST, ovvero una matrice di strutture SOLE_AUTHENTICATION_INFO . Questo elenco indica le informazioni per ogni servizio di autenticazione che un client può usare per chiamare un server. Questo parametro viene usato da COM solo quando un client chiama CoInitializeSecurity.

[in] dwCapabilities

Funzionalità aggiuntive del client o del server, specificate impostando uno o più valori EOLE_AUTHENTICATION_CAPABILITIES . Alcuni di questi valori non possono essere usati simultaneamente e alcuni non possono essere impostati quando vengono usati servizi di autenticazione specifici. Per altre informazioni su questi flag, vedere la sezione Osservazioni.

[in, optional] pReserved3

Questo parametro è riservato e deve essere NULL.

Valore restituito

Questa funzione può restituire il valore restituito standard E_INVALIDARG, nonché i valori seguenti.

Codice restituito Descrizione
S_OK
Indica l'esito positivo dell'operazione.
RPC_E_TOO_LATE

CoInitializeSecurity è già stato chiamato.

RPC_E_NO_GOOD_SECURITY_PACKAGES
Il parametro asAuthSvc non era NULL e nessuno dei servizi di autenticazione nell'elenco potrebbe essere registrato. Controllare i risultati salvati in asAuthSvc per i codici di errore specifici del servizio di autenticazione.
E_OUT_OF_MEMORY
Memoria insufficiente.

Commenti

La funzione CoInitializeSecurity inizializza il livello di sicurezza e imposta i valori specificati come impostazione predefinita per la sicurezza. Se un processo non chiama CoInitializeSecurity, COM chiama automaticamente la prima volta che un'interfaccia viene marshallata o non interrotta, registrando la sicurezza predefinita del sistema. Nessun pacchetto di sicurezza predefinito viene registrato fino a allora.

Questa funzione viene chiamata esattamente una volta per processo, in modo esplicito o implicito. Può essere chiamato dal client, dal server o da entrambi. Per le applicazioni legacy e altre applicazioni che non chiamano esplicitamente CoInitializeSecurity, COM chiama questa funzione in modo implicito con i valori del Registro di sistema. Se si imposta la sicurezza a livello di processo usando il Registro di sistema e quindi si chiama CoInitializeSecurity, i valori del Registro di sistema AppID verranno ignorati e verranno usati i valori CoInitializeSecurity .

CoInitializeSecurity può essere usato per eseguire l'override delle autorizzazioni di accesso a livello di computer e delle autorizzazioni di accesso specifiche dell'applicazione, ma non per eseguire l'override dei criteri di restrizione a livello di computer.

Se pSecDesc punta a un AppID, il flag di EOAC_APPID deve essere impostato in dwCapabilities e, quando viene impostato il flag di EOAC_APPID, tutti gli altri parametri su CoInitializeSecurity vengono ignorati. CoInitializeSecurity cerca il livello di autenticazione sotto la chiave AppID nel Registro di sistema e lo usa per determinare la sicurezza predefinita. Per altre informazioni sul modo in cui viene usata la chiave AppID per impostare la sicurezza, vedere Impostazione Process-Wide sicurezza tramite il Registro di sistema.

Se pSecDesc è un puntatore a un oggetto IAccessControl , il flag di EOAC_ACCESS_CONTROL deve essere impostato e dwAuthnLevel non può essere nessuna. L'oggetto IAccessControl viene usato per determinare chi può chiamare il processo. DCOM addRef the IAccessControle lo rilascia quando viene chiamato CoUninitialize . Lo stato dell'oggetto IAccessControl non deve essere modificato.

Se pSecDesc è un puntatore a un SECURITY_DESCRIPTOR, né il EOAC_APPID né il flag di EOAC_ACCESS_CONTROL possono essere impostati in dwCapabilities. Il proprietario e il gruppo del SECURITY_DESCRIPTOR devono essere impostati e finché DCOM supporta il controllo, l'ACL di sistema deve essere NULL. Le voci di controllo di accesso (ACL) nell'ACL discrezionale del SECURITY_DESCRIPTOR vengono usate per scoprire quali chiamanti sono autorizzati a connettersi agli oggetti del processo. Un daCL senza ACL non consente l'accesso, mentre un DACL NULL consentirà chiamate da chiunque. Per altre informazioni sugli ACL e sugli ACL, vedere Controllo di accesso Modello. Le applicazioni devono chiamare AccessCheck (non IsValidSecurityDescriptor) per assicurarsi che il SECURITY_DESCRIPTOR sia formato correttamente prima di chiamare CoInitializeSecurity.

Il passaggio di pSecDesc come NULL è fortemente sconsigliato. Un'alternativa appropriata potrebbe essere quella di usare un SECURITY_DESCRIPTOR che consente a Tutti. Se pSecDesc è NULL, i flag in dwCapabilities determinano il modo in cui CoInitializeSecurity definisce le autorizzazioni di accesso che verrà usato da un server, come indicato di seguito:

  • Se il flag EOAC_APPID è impostato, CoInitializeSecurity cercherà il nome .exe dell'applicazione nel Registro di sistema e userà l'AppID archiviato.
  • Se il flag EOAC_ACCESS_CONTROL è impostato, CoInitializeSecurity restituirà un errore.
  • Se non viene impostato né il flag di EOAC_APPID né il flag di EOAC_ACCESS_CONTROL, CoInitializeSecurity consente a tutti i chiamanti, inclusi utenti anonimi locali e remoti.
La funzione CoInitializeSecurity restituisce un errore se i flag di EOAC_APPID e EOAC_ACCESS_CONTROL vengono impostati in dwCapabilities.

Requisiti

Requisito Valore
Client minimo supportato Windows 2000 Professional [app desktop | App UWP]
Server minimo supportato Windows 2000 Server [app desktop | App UWP]
Piattaforma di destinazione Windows
Intestazione combaseapi.h (include Objbase.h)
Libreria Ole32.lib
DLL Ole32.dll

Vedi anche

CoSetProxyBlanket

Sicurezza in COM