InitializeSecurityContext-Funktion (Schannel)

Die InitializeSecurityContext-Funktion (Schannel) initiiert den clientseitigen ausgehenden Sicherheitskontext von einem Anmeldeinformationshandle. Die -Funktion wird verwendet, um einen Sicherheitskontext zwischen der Clientanwendung und einem Remote-Peer zu erstellen. InitializeSecurityContext (Schannel) gibt ein Token zurück, das der Client an den Remote-Peer übergeben muss, den der Peer wiederum über den AcceptSecurityContext-Aufruf (Schannel) an die lokale Sicherheitsimplementierung übermittelt. Das generierte Token sollte von allen Aufrufern als nicht transparent betrachtet werden.

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

Syntax

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

Parameter

phCredential [ in, optional]

Ein Handle für die Anmeldeinformationen, die von AcquireCredentialsHandle (Schannel) zurückgegeben werden. Dieses Handle wird verwendet, um den Sicherheitskontext zu erstellen. Die InitializeSecurityContext-Funktion (Schannel) erfordert mindestens OUTBOUND-Anmeldeinformationen.

phContext [ in, optional]

Ein Zeiger auf eine CTXTHandle-Struktur. Beim ersten Aufruf von InitializeSecurityContext (Schannel) ist dieser Zeiger NULL. Beim zweiten Aufruf ist dieser Parameter ein Zeiger auf das Handle auf den teilweise gebildeten Kontext, der durch den ersten Aufruf im phNewContext-Parameter zurückgegeben wird.

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

pszTargetName [ in, optional]

Ein Zeiger auf eine auf NULL beendete Zeichenfolge, die den Zielserver eindeutig identifiziert. Schannel verwendet diesen Wert, um das Serverzertifikat zu überprüfen. Schannel verwendet diesen Wert auch, um die Sitzung beim Wiederherstellen einer Verbindung im Sitzungscache zu suchen. 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 eines der folgenden Attributflags sein.

Wert Bedeutung
ISC_REQ_ALLOCATE_MEMORY
Das Sicherheitspaket ordnet Ausgabepuffer für Sie zu. Wenn Sie die Ausgabepuffer nicht mehr verwenden, geben Sie sie frei, indem Sie die FreeContextBuffer-Funktion aufrufen.
ISC_REQ_CONFIDENTIALITY
Verschlüsseln Sie Nachrichten mithilfe der EncryptMessage-Funktion.
ISC_REQ_CONNECTION
Der Sicherheitskontext verarbeitet keine Formatierungsmeldungen.
ISC_REQ_EXTENDED_ERROR
Wenn Fehler auftreten, wird die Remote-Partei benachrichtigt.
ISC_REQ_INTEGRITY
Signieren Sie Nachrichten, und überprüfen Sie Signaturen mithilfe der Funktionen EncryptMessage und MakeSignature.
ISC_REQ_MANUAL_CRED_VALIDATION
Schannel darf den Server nicht automatisch authentifizieren.
ISC_REQ_MUTUAL_AUTH
Die Richtlinie für gegenseitige Authentifizierung des Diensts wird erfüllt.
[!Caution]
Dies bedeutet nicht notwendigerweise, dass die gegenseitige Authentifizierung erfolgt, sondern nur, dass die Authentifizierungsrichtlinie des Diensts erfüllt ist. Um sicherzustellen, dass gegenseitige Authentifizierung erfolgt, rufen Sie die Funktion QueryContextAttributes (Schannel) auf.

ISC_REQ_REPLAY_DETECT
Erkennen von wiedergegebenen Nachrichten, die mithilfe der Funktionen EncryptMessage oder MakeSignature codiert wurden.
ISC_REQ_SEQUENCE_DETECT
Erkennen von Nachrichten, die nicht sequenziert empfangen werden.
ISC_REQ_STREAM
Unterstützt eine streamorientierte Verbindung.
ISC_REQ_USE_SUPPLIED_CREDS
Schannel darf nicht versuchen, Anmeldeinformationen für den Client automatisch anzugeben.

Die angeforderten Attribute werden vom Client möglicherweise nicht unterstützt. Weitere Informationen finden Sie unter dem parameter pfContextAttr.

Weitere Beschreibungen der verschiedenen Attribute finden Sie unter Kontextanforderungen.

Reserviert1 [ In]

Dieser Parameter ist reserviert und muss auf 0 (null) festgelegt werden.

TargetDataRep [ In]

Dieser Parameter wird nicht mit Schannel verwendet. Legen Sie sie auf 0 (null) fest.

pInput [ in, 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 NULL sein. 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 zum Speichern des vom Remotecomputer zurückgegebenen Tokens zugeordnet ist.

Bei Aufrufen dieser Funktion nach dem ersten Aufruf müssen zwei Puffer verwendet werden. 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 den pvBuffer- als auch den cbBuffer-Member auf 0 fest.

Reserved2 [ In]

Dieser Parameter ist reserviert und muss auf 0 (null) festgelegt werden.

phNewContext [ in, out, optional]

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

Übergeben Sie bei Aufrufen nach dem ersten Aufruf das hier zurückgegebene Handle als phContext-Parameter, und geben Sie NULL für phNewContext an.

pOutput [ in, out, optional]

Ein Zeiger auf eine SecBufferDesc-Struktur, die Zeiger auf die SecBuffer-Struktur enthält, die die Ausgabedaten empfängt. Wenn ein Puffer in der Eingabe als SEC _ READWRITE eingegeben wurde, ist er in der Ausgabe vorhanden. Das System ordnet bei Eineranforderung (über ISC REQ ALLOCATE MEMORY) einen Puffer für das Sicherheitstoken zu und füllt die Adresse im Pufferdeskriptor für das _ _ _ Sicherheitstoken aus.

Wenn das ISC REQ ALLOCATE MEMORY-Flag angegeben ist, ordnet der Schannel-SSP Arbeitsspeicher für den Puffer zu und gibt die entsprechenden Informationen _ _ in _ secBufferDesc ab. Darüber hinaus muss der Aufrufer einen Puffer vom Typ SECBUFFER _ ALERT übergeben. Wenn bei der Ausgabe eine Warnung generiert wird, enthält dieser Puffer Informationen zu dieser Warnung, und die Funktion schlägt fehl.

pfContextAttr [ out]

Ein Zeiger auf eine Variable, um einen Satz von Bitflags zu empfangen, die die Attribute des eingerichteten Kontexts angeben. Eine Beschreibung der verschiedenen Attribute finden Sie unter Kontextanforderungen.

Flags, die für diesen Parameter verwendet werden, wird ISC _ RET vorangestellt, z. B. ISC _ RET _ DELEGATE. Eine Liste der gültigen Werte finden Sie unter dem fContextReq-Parameter.

Überprüfen Sie erst nach sicherheitsbezogenen Attributen, wenn der letzte Funktionsaufruf erfolgreich zurückgegeben wird. Attributflags, die sich nicht auf die Sicherheit bezieht, 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 Remote-Peer ä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 in Ortszeit zurückgibt. Dieser Parameter ist optional, und NULL sollte für kurzlebige Clients übergeben werden.

Rückgabewert

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

Rückgabecode Beschreibung
SEC _ I _ COMPLETE _ AND _ CONTINUE
Der Client muss CompleteAuthToken aufrufen und dann die Ausgabe an den Server übergeben. Der Client wartet dann auf ein zurückgegebenes Token und übergibt es in einem anderen Aufruf an InitializeSecurityContext (Schannel).
SEC _ I _ COMPLETE _ NEEDED
Der Client muss die Erstellung der Nachricht abschließen und dann die CompleteAuthToken-Funktion aufrufen.
SEC _ I _ CONTINUE _ NEEDED
Der Client muss das Ausgabetoken an den Server senden und auf ein Rückgabetoken warten. Das zurückgegebene Token wird dann in einem anderen Aufruf von InitializeSecurityContext (Schannel)übergeben. Das Ausgabetoken kann leer sein.
SEC _ I _ INCOMPLETE _ CREDENTIALS
Der Server hat die Clientauthentifizierung angefordert, und die angegebenen Anmeldeinformationen enthalten entweder kein Zertifikat, oder das Zertifikat wurde nicht von einer Zertifizierungsstelle ausgestellt, die vom Server als vertrauenswürdig eingestuft wird. Weitere Informationen finden Sie in den Hinweisen.
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-Member von SECBUFFER _ MISSING. Der cbBuffer-Member von SecBuffer enthält einen Wert, der die Anzahl zusätzlicher Bytes angibt, die die Funktion vom Client lesen muss, bevor diese Funktion erfolgreich ausgeführt wird. Diese Zahl ist zwar nicht immer genau, kann jedoch die Leistung verbessern, indem mehrere Aufrufe dieser Funktion vermieden werden.
SEC _ E _ OK
Der Sicherheitskontext wurde erfolgreich initialisiert. Es ist kein weiterer InitializeSecurityContext-Aufruf (Schannel) erforderlich. Wenn die Funktion ein Ausgabetoken zurückgibt, d. h., wenn das _ SECBUFFER-TOKEN in pOutput eine Länge von ungleich 0 (null) hat, muss dieses Token an den Server gesendet werden.

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.
_INTERNER _ SEC _ E-FEHLER
Fehler, der keinem SSPI-Fehlercode zugeordnet wurde.
SEC _ E _ INVALID _ HANDLE
Das an die Funktion übergebene Handle ist ungültig.
SEC _ E _ INVALID _ TOKEN
Der Fehler ist auf ein falsch formatiertes Eingabetoken zurückzuführen, z. B. auf ein während der Übertragung beschädigtes Token, ein Token mit falscher Größe oder ein Token, das an die falsche eingeschränkte Delegierungübergeben wird. Die Übergabe eines Tokens an das falsche Paket kann auftreten, wenn client und server die ordnungsgemäße eingeschränkte Delegierungnicht 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 Seite kann falsch sein, die Domäne kann nicht erreichbar sein, oder es ist ein Vertrauensstellungsfehler aufgetreten.
SEC _ E _ NO _ CREDENTIALS
In der eingeschränkten Delegierungsind keine Anmeldeinformationen verfügbar.
SEC _ E _ TARGET _ UNKNOWN
Das Ziel wurde nicht erkannt.
_NICHT _ UNTERSTÜTZTE SEC _ E-FUNKTION
Im fContextReq-Parameter wurde ein ungültiges Kontextattributflag _ _ (ISC REQ DELEGATE oder ISC _ REQ _ PROMPT FOR _ _ CREDS) angegeben.
SEC _ E _ WRONG _ PRINCIPAL
Der Prinzipal, der die Authentifizierungsanforderung empfangen hat, ist nicht identisch mit dem Prinzipal, der an den parameter pszTargetName übergeben wird. Dies weist auf einen Fehler bei der gegenseitigen Authentifizierung hin.
SEC _ E _ APPLICATION _ PROTOCOL _ MISMATCH
Zwischen dem Client und dem Server ist kein allgemeines Anwendungsprotokoll vorhanden.

Hinweise

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

Wenn attribute des Sicherheitskontexts nicht ausreichen, muss der Client den teilweise erstellten Kontext freigeben, indem er die DeleteSecurityContext-Funktion aufruft.

Die InitializeSecurityContext (Schannel)-Funktion wird von einem Client verwendet, um einen ausgehenden Kontext zu initialisieren.

Für einen zweistufigen Sicherheitskontextsieht die aufrufende Sequenz wie folgt aus:

  1. Der Client ruft die Funktion auf, wobei phContext auf NULL festgelegt ist, und füllt den Pufferdeskriptor mit der Eingabenachricht aus.
  2. Das Sicherheitspaket untersucht die Parameter und erstellt ein nicht transparentes Token und platziert es im TOKEN-Element im Pufferarray. Wenn der fContextReq-Parameter das ISC _ REQ _ ALLOCATE _ MEMORY-Flag enthält, ordnet das Sicherheitspaket den Arbeitsspeicher zu und gibt den Zeiger im TOKEN-Element zurück.
  3. 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 (Schannel)-Funktion.
  4. AcceptSecurityContext (Schannel) gibt möglicherweise ein Token zurück, das der Server für einen zweiten Aufruf von InitializeSecurityContext (Schannel) an den Client sendet, wenn der erste Aufruf SEC I CONTINUE NEEDED zurückgegeben _ _ _ hat.

Für mehrstufige Sicherheitskontexte,z. B. gegenseitige Authentifizierung, sieht die aufrufende Sequenz wie folgt aus:

  1. Der Client ruft die Funktion wie zuvor beschrieben auf, aber das Paket gibt den Erfolgscode SEC _ I CONTINUE _ NEEDED _ zurück.
  2. Der Client sendet das Ausgabetoken an den Server und wartet auf die Antwort des Servers.
  3. Nach Empfang der Antwort des Servers ruft der Client InitializeSecurityContext (Schannel) erneut auf, wobei phContext auf das Handle festgelegt ist, das vom letzten Aufruf zurückgegeben wurde. Das vom Server empfangene Token wird im pInput-Parameter bereitgestellt.

Wenn der Server erfolgreich geantwortet 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.

Zum Initialisieren eines Sicherheitskontextssind abhängig vom zugrunde liegenden Authentifizierungsmechanismus und den im fContextReq-Parameter angegebenen Optionen möglicherweise mehr als ein Aufruf dieser Funktion erforderlich.

Die Parameter fContextReq und pfContextAttributes sind Bitmasken, die verschiedene Kontextattribute darstellen. Eine Beschreibung der verschiedenen Attribute finden Sie unter Kontextanforderungen. Der pfContextAttributes-Parameter ist bei jeder erfolgreichen Rückgabe gültig, aber nur bei der endgültigen erfolgreichen Rückgabe sollten Sie die Flags untersuchen, die sicherheitsaspekte des Kontexts betreffen. Zwischenrücksetzungen können z. B. das ISC _ RET _ ALLOCATED _ MEMORY-Flag festlegen.

Wenn das ISC _ REQ _ USE _ SUPPLIED _ CREDS-Flag festgelegt ist, muss das Sicherheitspaket nach einem SECBUFFER _ PKG _ PARAMS-Puffertyp im pInput-Eingabepuffer suchen. Dies ist keine generische Lösung, ermöglicht aber ggf. eine starke Kopplung von Sicherheitspaket und Anwendung.

Wenn ISC _ REQ _ ALLOCATE MEMORY angegeben _ wurde, muss der Aufrufer den Arbeitsspeicher freigeben, indem er die FreeContextBuffer-Funktion aufruft.

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

Welche Aktion der Client vornimmt, hängt vom Rückgabecode dieser Funktion ab. Wenn der Rückgabecode SEC _ E _ OK lautet, erfolgt kein zweiter InitializeSecurityContext-Aufruf (Schannel), und es wird keine Antwort vom Server erwartet. Wenn der Rückgabecode SEC _ I _ CONTINUE NEEDED _ lautet, erwartet der Client ein Token als Antwort vom Server und übergibt es in einem zweiten Aufruf an InitializeSecurityContext (Schannel). Der _ SEC I _ COMPLETE _ NEEDED-Rückgabecode gibt an, dass der Client die Erstellung der Nachricht abschließen und die CompleteAuthToken-Funktion aufrufen muss. Der _ SEC I _ COMPLETE AND _ _ CONTINUE-Code umfasst beide Aktionen.

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

Der Client kann InitializeSecurityContext (Schannel) 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 mit VirtualAllocim virtuellen Speicher zugeordnet werden muss. er darf nicht aus dem Pool zugeordnet werden. In pInput und pOutput übergebene und bereitgestellte Puffer müssen sich im virtuellen Speicher und nicht im Pool befinden.

Wenn die Funktion SEC _ I _ INCOMPLETE CREDENTIALS zurückgibt, _ überprüfen Sie, ob Sie in Ihren Anmeldeinformationen ein gültiges und vertrauenswürdiges Zertifikat angegeben haben. Das Zertifikat wird beim Aufrufen der AcquireCredentialsHandle-Funktion (Schannel) angegeben. Das Zertifikat muss ein Clientauthentifizierungszertifikat sein, das von einer Zertifizierungsstelle ausgestellt wurde, die vom Server als vertrauenswürdig eingestuft wird. Um eine Liste der Zertifizierungsstellen abzurufen, denen der Server vertraut, rufen Sie die QueryContextAttributes (Schannel)-Funktion auf, und geben Sie das SECPKG _ ATTR _ ISSUER LIST _ _ EX-Attribut an.

Nachdem eine Clientanwendung ein Authentifizierungszertifikat von einer Zertifizierungsstelle empfangen hat, die vom Server als vertrauenswürdig eingestuft wird, erstellt die Anwendung neue Anmeldeinformationen, indem sie die AcquireCredentialsHandle (Schannel)-Funktion aufruft und dann Erneut InitializeSecurityContext (Schannel) aufruft, wobei die neuen Anmeldeinformationen im phCredential-Parameter angegeben werden.

Anforderungen

Anforderung Wert
Unterstützte Mindestversion (Client)
[Windows 8.1 Nur Desktop-Apps]
Unterstützte Mindestversion (Server)
Windows Server 2012 Nur [ R2-Desktop-Apps]
Header
Sspi.h (include Security.h)
Bibliothek
Secur32.lib
DLL
Secur32.dll

Weitere Informationen

SSPI-Funktionen

AcceptSecurityContext (Schannel)

AcquireCredentialsHandle (Schannel)

CompleteAuthToken

DeleteSecurityContext

FreeContextBuffer

SecBuffer

SecBufferDesc