CoInitializeSecurity-Funktion (combaseapi.h)

  • Artikel

Registriert die Sicherheit und legt die Standardsicherheitswerte für den Prozess fest.

Syntax

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

Parameter

[in, optional] pSecDesc

Die Zugriffsberechtigungen, die ein Server zum Empfangen von Anrufen verwendet. Dieser Parameter wird nur von COM verwendet, wenn ein Server CoInitializeSecurity aufruft. Sein Wert ist ein Zeiger auf einen von drei Typen: eine AppID, ein IAccessControl-Objekt oder ein SECURITY_DESCRIPTOR im absoluten Format. Weitere Informationen finden Sie im Abschnitt Hinweise.

[in] cAuthSvc

Die Anzahl der Einträge im asAuthSvc-Parameter . Dieser Parameter wird nur von COM verwendet, wenn ein Server CoInitializeSecurity aufruft. Wenn dieser Parameter 0 ist, werden keine Authentifizierungsdienste registriert, und der Server kann keine sicheren Anrufe empfangen. Der Wert -1 weist COM an, die zu registrierenden Authentifizierungsdienste auszuwählen. Wenn dies der Fall ist, muss der asAuthSvc-ParameterNULL sein. Schannel wird jedoch nie vom Server als Authentifizierungsdienst ausgewählt, wenn dieser Parameter -1 ist.

[in, optional] asAuthSvc

Ein Array von Authentifizierungsdiensten, die ein Server zum Empfangen eines Anrufs verwenden möchte. Dieser Parameter wird nur von COM verwendet, wenn ein Server CoInitializeSecurity aufruft. Weitere Informationen finden Sie unter SOLE_AUTHENTICATION_SERVICE.

[in, optional] pReserved1

Dieser Parameter ist reserviert und muss NULL sein.

[in] dwAuthnLevel

Die Standardauthentifizierungsebene für den Prozess. Sowohl Server als auch Clients verwenden diesen Parameter, wenn sie CoInitializeSecurity aufrufen. COM schlägt Aufrufe fehl, die mit einer niedrigeren Authentifizierungsebene eingehen. Standardmäßig verwenden alle Proxys mindestens diese Authentifizierungsstufe. Dieser Wert sollte eine der Konstanten der Authentifizierungsebene enthalten. Standardmäßig werden alle Aufrufe von IUnknown auf dieser Ebene ausgeführt.

[in] dwImpLevel

Die Standardidentitätswechselebene für Proxys. Der Wert dieses Parameters wird nur verwendet, wenn es sich bei dem Prozess um einen Client handelt. Es sollte sich um einen Wert aus den Konstanten der Identitätswechselebene handeln, mit Ausnahme von RPC_C_IMP_LEVEL_DEFAULT, die nicht für die Verwendung mit CoInitializeSecurity bestimmt ist.

Ausgehende Aufrufe vom Client verwenden immer die Identitätswechselebene, wie angegeben. (Es wird nicht ausgehandelt.) Eingehende Aufrufe des Clients können auf jeder Identitätswechselebene erfolgen. Standardmäßig werden alle IUnknown-Aufrufe mit dieser Identitätswechselebene ausgeführt, sodass selbst sicherheitsrelevante Anwendungen diese Ebene sorgfältig festlegen sollten. Informationen dazu, welche Identitätswechselstufen von jedem Authentifizierungsdienst unterstützt werden, finden Sie in der Beschreibung der Authentifizierungsdienste in COM und Sicherheitspaketen. Weitere Informationen zu Identitätswechselebenen finden Sie unter Identitätswechsel.

[in, optional] pAuthList

Ein Zeiger auf SOLE_AUTHENTICATION_LIST, bei dem es sich um ein Array von SOLE_AUTHENTICATION_INFO Strukturen handelt. Diese Liste gibt die Informationen für jeden Authentifizierungsdienst an, den ein Client zum Aufrufen eines Servers verwenden kann. Dieser Parameter wird nur von COM verwendet, wenn ein Client CoInitializeSecurity aufruft.

[in] dwCapabilities

Zusätzliche Funktionen des Clients oder Servers, die durch Festlegen eines oder mehrerer EOLE_AUTHENTICATION_CAPABILITIES-Werte angegeben werden. Einige dieser Werte können nicht gleichzeitig verwendet werden, und einige können nicht festgelegt werden, wenn bestimmte Authentifizierungsdienste verwendet werden. Weitere Informationen zu diesen Flags finden Sie im Abschnitt Hinweise.

[in, optional] pReserved3

Dieser Parameter ist reserviert und muss NULL sein.

Rückgabewert

Diese Funktion kann den Standardrückgabewert E_INVALIDARG sowie die folgenden Werte zurückgeben.

Rückgabecode BESCHREIBUNG
S_OK
 Gibt die erfolgreiche Ausführung an.
RPC_E_TOO_LATE

CoInitializeSecurity wurde bereits aufgerufen.
RPC_E_NO_GOOD_SECURITY_PACKAGES
 Der asAuthSvc-Parameter war nicht NULL, und keiner der Authentifizierungsdienste in der Liste konnte registriert werden. Überprüfen Sie die in asAuthSvc gespeicherten Ergebnisse auf Authentifizierungsdienstspezifische Fehlercodes.
E_OUT_OF_MEMORY
 Nicht genügend Arbeitsspeicher.

Hinweise

Die CoInitializeSecurity-Funktion initialisiert die Sicherheitsebene und legt die angegebenen Werte als Sicherheitsstandard fest. Wenn ein Prozess CoInitializeSecurity nicht aufruft, ruft COM ihn automatisch auf, wenn eine Schnittstelle zum ersten Mal gemarst oder aufgehoben wird, wobei die Standardsicherheit des Systems registriert wird. Bis dahin werden keine Standardsicherheitspakete registriert.

Diese Funktion wird genau einmal pro Prozess aufgerufen, entweder explizit oder implizit. Sie kann vom Client, Server oder beidem aufgerufen werden. Bei Legacyanwendungen und anderen Anwendungen, die CoInitializeSecurity nicht explizit aufrufen, ruft COM diese Funktion implizit mit Werten aus der Registrierung auf. Wenn Sie die prozessweite Sicherheit mithilfe der Registrierung festlegen und dann CoInitializeSecurity aufrufen, werden die AppID-Registrierungswerte ignoriert und die CoInitializeSecurity-Werte verwendet.

CoInitializeSecurity kann verwendet werden, um sowohl computerweite Zugriffsberechtigungen als auch anwendungsspezifische Zugriffsberechtigungen außer Kraft zu setzen, aber nicht, um die computerweite Einschränkungsrichtlinie außer Kraft zu setzen.

Wenn pSecDesc auf eine AppID verweist, muss das EOAC_APPID-Flag in dwCapabilities festgelegt werden, und wenn das EOAC_APPID-Flag festgelegt ist, werden alle anderen Parameter auf CoInitializeSecurity ignoriert. CoInitializeSecurity sucht nach der Authentifizierungsebene unter dem AppID-Schlüssel in der Registrierung und verwendet sie, um die Standardsicherheit zu bestimmen. Weitere Informationen dazu, wie der AppID-Schlüssel zum Festlegen der Sicherheit verwendet wird, finden Sie unter Festlegen Process-Wide Sicherheit über die Registrierung.

Wenn pSecDesc ein Zeiger auf ein IAccessControl-Objekt ist, muss das EOAC_ACCESS_CONTROL-Flag festgelegt werden, und dwAuthnLevel darf keines sein. Das IAccessControl-Objekt wird verwendet, um zu bestimmen, wer den Prozess aufrufen kann. DCOM addRef the IAccessControl und releaset es, wenn CoUninitialize aufgerufen wird. Der Zustand des IAccessControl-Objekts sollte nicht geändert werden.

Wenn pSecDesc ein Zeiger auf eine SECURITY_DESCRIPTOR ist, können weder das EOAC_APPID noch das EOAC_ACCESS_CONTROL-Flag in dwCapabilities festgelegt werden. Der Besitzer und die Gruppe des SECURITY_DESCRIPTOR müssen festgelegt werden, und bis DCOM die Überwachung unterstützt, muss die System-ACL NULL sein. Die Zugriffssteuerungseinträge (ACEs) in der discretionary ACL (DACL) der SECURITY_DESCRIPTOR werden verwendet, um herauszufinden, welche Aufrufer eine Verbindung mit den Objekten des Prozesses herstellen dürfen. Eine DACL ohne ACEs lässt keinen Zugriff zu, während eine NULL-DACL Anrufe von jeder Person zulässt. Weitere Informationen zu ACLs und ACEs finden Sie unter Access Control Modell. Anwendungen sollten AccessCheck (nicht IsValidSecurityDescriptor) aufrufen, um sicherzustellen, dass ihre SECURITY_DESCRIPTOR vor dem Aufrufen von CoInitializeSecurity ordnungsgemäß gebildet ist.

Es wird dringend davon abgeraten , pSecDesc als NULL zu übergeben. Eine geeignete Alternative könnte die Verwendung eines SECURITY_DESCRIPTOR sein, der "Jeder" zulässt. Wenn pSecDescNULL ist, bestimmen die Flags in dwCapabilities , wie CoInitializeSecurity die Zugriffsberechtigungen definiert, die ein Server verwendet:

  • Wenn das EOAC_APPID-Flag festgelegt ist, sucht CoInitializeSecurity den .exe Namen der Anwendung in der Registrierung und verwendet die dort gespeicherte AppID.
  • Wenn das flag EOAC_ACCESS_CONTROL festgelegt ist, gibt CoInitializeSecurity einen Fehler zurück.
  • Wenn weder das EOAC_APPID-Flag noch das EOAC_ACCESS_CONTROL-Flag festgelegt ist, lässt CoInitializeSecurity alle Aufrufer zu, einschließlich lokaler und anonymer Remotebenutzer.
Die CoInitializeSecurity-Funktion gibt einen Fehler zurück, wenn sowohl die EOAC_APPID- als auch EOAC_ACCESS_CONTROL-Flags in dwCapabilities festgelegt sind.

Anforderungen

Anforderung Wert
Unterstützte Mindestversion (Client) Windows 2000 Professional [Desktop-Apps | UWP-Apps]
Unterstützte Mindestversion (Server) Windows 2000 Server [Desktop-Apps | UWP-Apps]
Zielplattform Windows
Kopfzeile combaseapi.h (include Objbase.h)
Bibliothek Ole32.lib
DLL Ole32.dll

Weitere Informationen

CoSetProxyBlanket

Sicherheit in COM