InitializeSecurityContext(CredSSP)-Funktion

Artikel
06/01/2023

Die Funktion InitializeSecurityContext (CredSSP) initiiert den clientseitigen ausgehenden Sicherheitskontext über ein Anmeldeinformationshandle. Die Funktion erstellt einen Sicherheitskontext zwischen der Clientanwendung und einem Remotepeer. InitializeSecurityContext (CredSSP) gibt ein Token zurück, das der Client an den Remotepeer übergeben muss. der Peer sendet dieses Token wiederum über den AcceptSecurityContext-Aufruf (CredSSP) an die lokale Sicherheitsimplementierung. Das generierte Token sollte von allen Aufrufenden als undurchsichtig betrachtet werden.

In der Regel wird die Funktion InitializeSecurityContext (CredSSP) in einer Schleife aufgerufen, bis ein ausreichender Sicherheitskontext eingerichtet ist.

Syntax

SECURITY_STATUS SEC_ENTRY InitializeSecurityContext(
  _In_opt_    PCredHandle    phCredential,
  _In_opt_    PCtxtHandle    phContext,
  _In_opt_    SEC_CHAR       *pszTargetName,
  _In_        unsigned long  fContextReq,
  _Reserved_  unsigned long  Reserved1,
  _In_        unsigned long  TargetDataRep,
  _Inout_opt_ PSecBufferDesc pInput,
  _In_        unsigned long  Reserved2,
  _Inout_opt_ PCtxtHandle    phNewContext,
  _Out_opt_   PSecBufferDesc pOutput,
  _Out_       unsigned long  *pfContextAttr,
  _Out_opt_   PTimeStamp     ptsExpiry
);

Parameter

phCredential[in, optional]

Ein Handle für die von AcquireCredentialsHandle (CredSSP) zurückgegebenen Anmeldeinformationen. Dieses Handle wird verwendet, um den Sicherheitskontext zu erstellen. Die Funktion InitializeSecurityContext (CredSSP) erfordert mindestens AUSGEHENDe Anmeldeinformationen.

phContext[in, optional]

Ein Zeiger auf eine CtxtHandle-Struktur . Beim ersten Aufruf von InitializeSecurityContext (CredSSP) lautet NULLdieser Zeiger . Beim zweiten Aufruf ist dieser Parameter ein Zeiger auf das Handle auf den teilweise gebildeten Kontext, der vom ersten Aufruf im parameter phNewContext zurückgegeben wird.

Geben Sie beim ersten Aufruf von InitializeSecurityContext (CredSSP) an NULL. Geben Sie bei zukünftigen Aufrufen das Token an, das im parameter phNewContext nach dem ersten Aufruf dieser Funktion empfangen wurde.

Warnung

Verwenden Sie nicht denselben Kontexthandle bei gleichzeitigen Aufrufen von InitializeSecurityContext (CredSSP). Die API-Implementierung in den Sicherheitsdienstanbietern ist nicht threadsicher.

pTargetName[in, optional]

Ein Zeiger auf eine NULL-Zeichenfolge, die den Zielserver eindeutig identifiziert. Schannel verwendet diesen Wert, um das Serverzertifikat zu überprüfen. Schannel verwendet diesen Wert auch, um die Sitzung im Sitzungscache zu suchen, wenn eine Verbindung wiederhergestellt wird. Die zwischengespeicherte Sitzung wird nur verwendet, wenn alle der folgenden Bedingungen erfüllt sind:

Der Zielname ist identisch.
Der Cacheeintrag ist nicht abgelaufen.
Der Anwendungsprozess, der die Funktion aufruft, ist identisch.
Die Anmeldesitzung ist identisch.
Das Handle für Anmeldeinformationen ist identisch.

fContextReq[in]

Bitflags, die Anforderungen für den Kontext angeben. Nicht alle Pakete können alle Anforderungen unterstützen. Flags, die für diesen Parameter verwendet werden, haben das Präfix ISC_REQ_, z. B. ISC_REQ_DELEGATE.

Dieser Parameter kann mindestens eins der folgenden Attribute-Flags sein.

Wert	Bedeutung
ISC_REQ_ALLOCATE_MEMORY `0x100`	Das Sicherheitspaket weist dem Aufrufer Ausgabepuffer zu. Wenn Sie die Verwendung der Ausgabepuffer abgeschlossen haben, geben Sie sie frei, indem Sie die FreeContextBuffer-Funktion aufrufen.
ISC_REQ_CONNECTION `0x800`	Der Sicherheitskontext verarbeitet keine Formatierungsnachrichten.
ISC_REQ_EXTENDED_ERROR `0x4000`	Wenn Fehler auftreten, wird die Remotepartei benachrichtigt.
ISC_REQ_MANUAL_CRED_VALIDATION `0x80000`	Der Credential Security Support Provider (CredSSP) darf den Server nicht automatisch authentifizieren. Dieses Flag wird immer festgelegt, wenn Sie CredSSP verwenden.
ISC_REQ_SEQUENCE_DETECT `0x8`	Erkennen Sie Nachrichten, die außerhalb der Sequenz empfangen werden.
ISC_REQ_STREAM `0x8000`	Unterstützung einer streamorientierten Verbindung.
ISC_REQ_USE_SUPPLIED_CREDS `0x80`	CredSSP darf nicht versuchen, Anmeldeinformationen für den Client automatisch anzugeben.
ISC_REQ_DELEGATE `0x1`	Gibt an, dass die Anmeldeinformationen des Benutzers an den Server delegiert werden sollen. Wenn dieses Flag nicht angegeben ist, wird ein leerer Satz von Anmeldeinformationen an den Server delegiert. Windows Server 2008 und Windows Vista: Dieses Flag ist erforderlich.
ISC_REQ_MUTUAL_AUTH `0x2`	Gibt an, dass die Serverauthentifizierung nicht erforderlich ist. Delegierungsrichtlinien werden weiterhin erzwungen, wenn dieses Flag nicht angegeben ist. Windows Server 2008 und Windows Vista: Dieses Flag wird ignoriert.

Die angeforderten Attribute werden vom Client möglicherweise nicht unterstützt. Weitere Informationen finden Sie im PfContextAttr-Parameter .

Weitere Beschreibungen der verschiedenen Attribute finden Sie unter Kontextanforderungen.

Reserviert1[in]

Reserviert. Dieser Parameter muss auf 0 festgelegt werden.

TargetDataRep[in]

Die Datendarstellung, z. B. bytereihenfolge, auf dem Ziel. Dieser Parameter kann entweder SECURITY_NATIVE_DREP oder SECURITY_NETWORK_DREP sein.

pInput[in, out, optional]

Ein Zeiger auf eine SecBufferDesc-Struktur , die Zeiger auf die Puffer enthält, die als Eingabe für das Paket bereitgestellt werden. Sofern der Clientkontext nicht vom Server initiiert wurde, muss der Wert dieses Parameters beim ersten Aufruf der Funktion sein NULL . Bei nachfolgenden Aufrufen der Funktion oder wenn der Clientkontext vom Server initiiert wurde, ist der Wert dieses Parameters ein Zeiger auf einen Puffer, der mit genügend Arbeitsspeicher versehen ist, um das vom Remotecomputer zurückgegebene Token aufzunehmen.

Bei Aufrufen dieser Funktion nach dem ersten Aufruf müssen zwei Puffer vorhanden sein. Die erste hat den Typ SECBUFFER_TOKEN und enthält das vom Server empfangene Token. Der zweite Puffer hat den Typ SECBUFFER_EMPTY; Legen Sie sowohl die PvBuffer - als auch die cbBuffer-Member auf 0 fest.

Reserviert2[in]

Reserviert. Dieser Parameter muss auf 0 festgelegt werden.

phNewContext[in, out, optional]

Ein Zeiger auf eine CtxtHandle-Struktur . Beim ersten Aufruf von InitializeSecurityContext (CredSSP) empfängt dieser Zeiger das neue Kontexthandle. Beim zweiten Aufruf kann phNewContext mit dem im phContext-Parameter angegebenen Handle identisch sein. phNewContext sollte niemals sein NULL.

pOutput[out, optional]

Ein Zeiger auf eine SecBufferDesc-Struktur . Diese Struktur enthält wiederum Zeiger auf die SecBuffer-Struktur , die die Ausgabedaten empfängt. Wenn ein Puffer als SEC_READWRITE in der Eingabe eingegeben wurde, ist er bei der Ausgabe vorhanden. Das System weist bei Anforderung (über ISC_REQ_ALLOCATE_MEMORY) einen Puffer für das Sicherheitstoken zu und gibt die Adresse im Pufferdeskriptor für das Sicherheitstoken ein.

Wenn das ISC_REQ_ALLOCATE_MEMORY-Flag angegeben ist, weist CredSSP Arbeitsspeicher für den Puffer zu und legt die entsprechenden Informationen in secBufferDesc.

pfContextAttr[out]

Ein Zeiger auf eine Reihe von Bitflags, die die Attribute des eingerichteten Kontexts angeben. Eine Beschreibung der verschiedenen Attribute finden Sie unter Kontextanforderungen.

Flags, die für diesen Parameter verwendet werden, haben das Präfix ISC_RET, z. B. ISC_RET_DELEGATE. Eine Liste der gültigen Werte finden Sie im fContextReq-Parameter .

Suchen Sie erst nach sicherheitsbezogenen Attributen, bis der endgültige Funktionsaufruf erfolgreich zurückgegeben wird. Attributflags, die nicht mit der Sicherheit zusammenhängen, z. B . das ASC_RET_ALLOCATED_MEMORY-Flag, können vor der endgültigen Rückgabe überprüft werden.

Hinweis

Bestimmte Kontextattribute können sich während der Aushandlung mit einem Remotepeer ändern.

ptsExpiry[out, optional]

Ein Zeiger auf eine TimeStamp-Struktur , die die Ablaufzeit des Kontexts empfängt. Es wird empfohlen, dass das Sicherheitspaket diesen Wert immer zur Ortszeit zurückgibt. Dieser Parameter ist optional und NULL sollte für kurzlebige Clients übergeben werden.

Rückgabewert

Wenn die Funktion erfolgreich ist, gibt sie einen der folgenden Erfolgscodes zurück.

Rückgabecode	Beschreibung
SEC_E_INCOMPLETE_MESSAGE	Daten für die gesamte Nachricht wurden nicht aus der Leitung gelesen. Wenn dieser Wert zurückgegeben wird, enthält der pInput-Puffer eine SecBuffer-Struktur mit einem BufferType-Membervon SECBUFFER_MISSING. Das cbBuffer-Element von SecBuffer gibt die Anzahl zusätzlicher Bytes an, die die Funktion vom Client lesen muss, bevor diese Funktion erfolgreich ist. Obwohl diese Zahl nicht immer genau ist, kann die Verwendung sie zur Verbesserung der Leistung beitragen, indem mehrere Aufrufe dieser Funktion vermieden werden.
SEC_E_OK	Der Sicherheitskontext wurde erfolgreich initialisiert. Es ist kein weiterer InitializeSecurityContext-Aufruf (CredSSP) erforderlich. Wenn die Funktion ein Ausgabetoken zurückgibt, d. h. wenn das SECBUFFER_TOKEN in pOutput eine nicht zero-Länge aufweist, muss dieses Token an den Server gesendet werden.
SEC_I_COMPLETE_AND_CONTINUE	Der Client muss CompleteAuthToken aufrufen und die Ausgabe dann an den Server übergeben. Der Client wartet dann auf ein zurückgegebenes Token und übergibt es in einem anderen Aufruf an InitializeSecurityContext (CredSSP).
SEC_I_COMPLETE_NEEDED	Der Client muss die Erstellung der Nachricht abschließen und dann die Funktion CompleteAuthToken aufrufen.
SEC_I_CONTINUE_NEEDED	Der Client muss das Ausgabetoken an den Server senden und auf ein Rückgabetoken warten. Der Client übergibt das zurückgegebene Token in einem anderen Aufruf an InitializeSecurityContext (CredSSP). Das Ausgabetoken kann leer sein.
SEC_I_INCOMPLETE_CREDENTIALS	Der Server hat die Clientauthentifizierung angefordert, aber entweder enthalten die angegebenen Anmeldeinformationen kein Zertifikat, oder das Zertifikat wurde nicht von einer Zertifizierungsstelle ausgestellt, der der Server vertraut. Weitere Informationen finden Sie in den Hinweisen.

Wenn die Funktion fehlschlägt, gibt die Funktion einen der folgenden Fehlercodes zurück.

Rückgabecode	Beschreibung
SEC_E_INSUFFICIENT_MEMORY	Es ist nicht genügend Arbeitsspeicher verfügbar, um die angeforderte Aktion abzuschließen.
SEC_E_INTERNAL_ERROR	Es ist ein Fehler aufgetreten, der keinem SSPI-Fehlercode zugeordnet wurde.
SEC_E_INVALID_HANDLE	Das an die Funktion übergebene Handle ist ungültig.
SEC_E_INVALID_TOKEN	Das Eingabetoken ist falsch formatiert. Mögliche Ursachen sind ein bei der Übertragung beschädigtes Token, ein Token mit falscher Größe und ein Token, das an das falsche Sicherheitspaket übergeben wurde. Diese letzte Bedingung kann auftreten, wenn Client und Server das richtige Sicherheitspaket nicht ausgehandelt haben.
SEC_E_LOGON_DENIED	Fehler bei der Anmeldung.
SEC_E_NO_AUTHENTICATING_AUTHORITY	Für die Authentifizierung konnte keine Autorität kontaktiert werden. Der Domänenname der authentifizierenden Partei kann falsch sein, die Domäne kann nicht erreichbar sein, oder es ist möglicherweise ein Vertrauensstellungsfehler aufgetreten.
SEC_E_NO_CREDENTIALS	Im Sicherheitspaket sind keine Anmeldeinformationen verfügbar.
SEC_E_TARGET_UNKNOWN	Das Ziel wurde nicht erkannt.
SEC_E_UNSUPPORTED_FUNCTION	Der Wert des fContextReq-Parameters ist ungültig. Entweder wurde kein erforderliches Flag angegeben oder ein Flag angegeben, das von CredSSP nicht unterstützt wird.
SEC_E_WRONG_PRINCIPAL	Der Prinzipal, der die Authentifizierungsanforderung empfangen hat, ist nicht mit dem Prinzipal identisch, der an den parameter pszTargetName übergeben wurde. Dieser Fehler weist auf einen Fehler bei der gegenseitigen Authentifizierung hin.
SEC_E_DELEGATION_POLICY	Die Richtlinie unterstützt keine Delegierung von Anmeldeinformationen an den Zielserver.
SEC_E_POLICY_NLTM_ONLY	Die Delegierung von Anmeldeinformationen an den Zielserver ist nicht zulässig, wenn die gegenseitige Authentifizierung nicht erreicht wird.
SEC_E_MUTUAL_AUTH_FAILED	Fehler bei der Serverauthentifizierung, wenn das flag ISC_REQ_MUTUAL_AUTH im fContextReq-Parameter angegeben ist.

Bemerkungen

Der Aufrufer ist dafür verantwortlich, zu bestimmen, ob die endgültigen Kontextattribute ausreichend sind. Wenn z. B. Vertraulichkeit angefordert wurde, aber nicht eingerichtet werden konnte, können einige Anwendungen die Verbindung sofort herunterfahren.

Wenn Attribute des Sicherheitskontexts nicht ausreichen, muss der Client den teilweise erstellten Kontext durch Aufrufen der DeleteSecurityContext-Funktion freigeben.

Der Client ruft die Funktion InitializeSecurityContext (CredSSP) auf, um einen ausgehenden Kontext zu initialisieren.

Für einen Sicherheitskontext mit zwei Beinen lautet die Aufrufsequenz wie folgt:

Der Client ruft die Funktion auf, wobei phContext auf NULL festgelegt ist, und füllt den Pufferdeskriptor mit der Eingabenachricht aus.
Das Sicherheitspaket untersucht die Parameter und erstellt ein undurchsichtiges Token und platziert es im TOKEN-Element im Pufferarray. Wenn der fContextReq-Parameter das flag ISC_REQ_ALLOCATE_MEMORY enthält, weist das Sicherheitspaket den Arbeitsspeicher zu und gibt den Zeiger im TOKEN-Element zurück.
Der Client sendet das im pOutput-Puffer zurückgegebene Token an den Zielserver. Der Server übergibt das Token dann als Eingabeargument in einem Aufruf der AcceptSecurityContext-Funktion (CredSSP ).
AcceptSecurityContext (CredSSP) gibt möglicherweise ein Token zurück. Der Server sendet dieses Token an den Client über einen zweiten InitializeSecurityContext -Aufruf (CredSSP), wenn der erste Aufruf SEC_I_CONTINUE_NEEDED zurückgegeben hat.

Wenn der Server erfolgreich reagiert hat, gibt das Sicherheitspaket SEC_E_OK zurück, und es wird eine sichere Sitzung eingerichtet.

Wenn die Funktion eine der Fehlerantworten zurückgibt, wird die Antwort des Servers nicht akzeptiert, und die Sitzung wird nicht eingerichtet.

Wenn die Funktion SEC_I_CONTINUE_NEEDED, SEC_I_COMPLETE_NEEDED oder SEC_I_COMPLETE_AND_CONTINUE zurückgibt, werden die Schritte 2 und 3 wiederholt.

Die Initialisierung des Sicherheitskontexts erfordert möglicherweise mehrere Aufrufe dieser Funktion, abhängig vom zugrunde liegenden Authentifizierungsmechanismus und den im fContextReq-Parameter angegebenen Optionen.

Die Parameter fContextReq und pfContextAttributes sind Bitmasken , die verschiedene Kontextattribute darstellen. Eine Beschreibung der verschiedenen Attribute finden Sie unter Kontextanforderungen. Während der pfContextAttributes-Parameter bei jeder erfolgreichen Rückgabe gültig ist, sollten Sie die Flags, die sich auf Sicherheitsaspekte des Kontexts beziehen, nur bei der endgültigen erfolgreichen Rückgabe untersuchen. Zwischenrückgibt, z. B. das flag ISC_RET_ALLOCATED_MEMORY .

Wenn das ISC_REQ_USE_SUPPLIED_CREDS-Flag festgelegt ist, muss das Sicherheitspaket im pInput-Eingabepuffer nach einem SECBUFFER_PKG_PARAMS Puffertyp suchen. Dies ist zwar keine generische Lösung, ermöglicht aber bei Bedarf eine starke Kopplung von Sicherheitspaket und Anwendung.

Wenn ISC_REQ_ALLOCATE_MEMORY angegeben wurde, muss der Aufrufer den Arbeitsspeicher durch Aufrufen der FreeContextBuffer-Funktion freigeben.

Das Eingabetoken kann beispielsweise die Herausforderung eines LAN-Managers sein. In diesem Fall ist das Ausgabetoken die NTLM-verschlüsselte Antwort auf die Herausforderung.

Die Aktion, die der Client ausführt, hängt vom Rückgabecode dieser Funktion ab. Wenn der Rückgabecode SEC_E_OK ist, wird kein zweiter InitializeSecurityContext-Aufruf (CredSSP) ausgeführt, und es wird keine Antwort vom Server erwartet. Wenn der Rückgabecode SEC_I_CONTINUE_NEEDED ist, erwartet der Client ein Token als Antwort vom Server und übergibt es in einem zweiten Aufruf von InitializeSecurityContext (CredSSP). Der SEC_I_COMPLETE_NEEDED Rückgabecode gibt an, dass der Client die Erstellung der Nachricht beenden und die Funktion CompleteAuthToken aufrufen muss. Der SEC_I_COMPLETE_AND_CONTINUE Code enthält beide Aktionen.

Wenn InitializeSecurityContext (CredSSP) beim ersten (oder nur) Aufruf erfolgreich ist, muss der Aufrufer schließlich die DeleteSecurityContext-Funktion für das zurückgegebene Handle aufrufen, auch wenn der Aufruf auf einem späteren Abschnitt des Authentifizierungsaustauschs fehlschlägt.

Der Client kann InitializeSecurityContext (CredSSP) erneut aufrufen, nachdem er erfolgreich abgeschlossen wurde. Dies gibt dem Sicherheitspaket an, dass eine erneute Authentifizierung gewünscht ist.

Kernelmodusaufrufer weisen die folgenden Unterschiede auf: Der Zielname ist eine Unicode-Zeichenfolge , die mithilfe von VirtualAlloc im virtuellen Arbeitsspeicher zugeordnet werden muss. sie darf nicht aus dem Pool zugewiesen werden. Puffer, die in pInput und pOutput übergeben und bereitgestellt werden, müssen sich im virtuellen Arbeitsspeicher befinden, nicht im Pool.

Wenn die Funktion SEC_I_INCOMPLETE_CREDENTIALS zurückgibt, überprüfen Sie, ob die r-Anmeldeinformationen, die an die AcquireCredentialsHandle-Funktion (CredSSP) übergeben wurden, ein gültiges und vertrauenswürdiges Zertifikat angegeben haben. Das Zertifikat muss ein Clientauthentifizierungszertifikat sein, das von einer Zertifizierungsstelle ausgestellt wurde, die vom Server vertrauenswürdig ist. Um eine Liste der vom Server vertrauenswürdigen Zertifizierungsstellen abzurufen, rufen Sie die Funktion QueryContextAttributes (CredSSP) mit dem attribut SECPKG_ATTR_ISSUER_LIST_EX auf.

Nach dem Empfang eines Authentifizierungszertifikats von einer Zertifizierungsstelle, der der Server vertraut, erstellt die Clientanwendung neue Anmeldeinformationen. Dazu wird die Funktion AcquireCredentialsHandle (CredSSP) aufgerufen und dann InitializeSecurityContext (CredSSP) erneut aufgerufen, wobei die neuen Anmeldeinformationen im parameter phCredential angegeben werden.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows Vista [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2008 [nur Desktop-Apps]
Header	Sspi.h (einschließlich Security.h)
Bibliothek	Secur32.lib
DLL	Secur32.dll