InitializeSecurityContext-Funktion (NTLM)

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

In der Regel wird die InitializeSecurityContext-Funktion (NTLM) 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_        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 (NTLM) zurückgegeben werden. Dieses Handle wird verwendet, um den Sicherheitskontext zu erstellen. Die InitializeSecurityContext-Funktion (NTLM) erfordert mindestens OUTBOUND-Anmeldeinformationen.

phContext [ in, optional]

Ein Zeiger auf eine CTXTHandle-Struktur. Beim ersten Aufruf von InitializeSecurityContext (NTLM) 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.

pszTargetName [ In]

Ein Zeiger auf eine auf NULL beendete Zeichenfolge, die den Dienstprinzipalnamen (SERVICE Principal Name, SPN) oder den Sicherheitskontext des Zielservers angibt.

Anwendungen müssen einen gültigen SPN zur Verfügung stellen, um Replay-Angriffe zu minimieren.

Verwenden Sie einen vollqualifizierten Zielnamen, da Kurznamen gesamtstrukturenübergreifend nicht unterstützt werden.

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. Dies ist der Standardwert.
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_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 ausgeführt wird, rufen Sie die NTLM-Funktion (QueryContextAttributes) 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.

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]

Die Datendarstellung, z. B. die Byte reihenfolge, auf dem Ziel. Dieser Parameter kann entweder SECURITY _ NATIVE _ DREP oder SECURITY _ NETWORK _ DREP sein.

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.

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 (NTLM) empfängt dieser Zeiger das neue Kontexthandl. Beim zweiten Aufruf kann phNewContext mit dem im phContext-Parameter angegebenen Handle identisch sein.

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.

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ück gibt. 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 _ E _ OK
Der Sicherheitskontext wurde erfolgreich initialisiert. Es ist kein weiterer InitializeSecurityContext-Aufruf (NTLM) erforderlich. Wenn die Funktion ein Ausgabetoken zurückgibt, das heißt, wenn das SECBUFFER-TOKEN in pOutput eine Länge ungleich _ 0 (null) hat, muss dieses Token an den Server gesendet werden.
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 (NTLM).
SEC _ I _ COMPLETE _ NEEDED
Der Client muss die Meldung fertig stellen 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 (NTLM) übergeben. Das Ausgabetoken kann leer sein.

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

Rückgabecode Beschreibung
_S.E _ NICHT GENÜGEND _ ARBEITSSPEICHER
Es ist nicht genügend Arbeitsspeicher verfügbar, um die angeforderte Aktion abschließen zu können.
INTERNER _ FEHLER IN SEKUNDE E _ _
Es ist ein Fehler aufgetreten, der einem SSPI-Fehlercode nicht zuordnen konnte.
SEC _ E _ UNGÜLTIGES _ HANDLE
Das an die Funktion übergebene Handle ist ungültig.
SEC _ E _ UNGÜLTIGES _ TOKEN
Der Fehler wird durch ein falsch formatiertes Eingabetoken verursacht, z. B. 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 passieren, wenn client und server nicht die richtige eingeschränkte Delegierung aushandelt haben.
SEC _ E _ LOGON _ DENIED
Fehler bei der Anmeldung.
SEC E NO AUTHENTICATING AUTHORITY (KEINE _ _ _ _ AUTHENTIFIZIERUNGSSTELLE)
Es konnte keine Autorität für die Authentifizierung kontaktiert werden. Der Domänenname der authentifizierenden Partei kann falsch sein, die Domäne kann nicht erreichbar sein, oder es ist ein Vertrauensstellungsfehler vor worden.
SEC _ E _ NO _ CREDENTIALS
In der eingeschränkten Delegierung sind keine Anmeldeinformationen verfügbar.
SEC _ E _ TARGET _ UNKNOWN
Das Ziel wurde nicht erkannt.
SEC _ E NICHT UNTERSTÜTZTE _ _ FUNKTION
Ein ungültiges Kontextattributflag (ISC _ REQ _ DELEGATE oder ISC _ REQ PROMPT FOR _ _ CREDS) wurde im _ fContextReq-Parameter angegeben.
SEC _ E _ WRONG _ PRINCIPAL
Der Prinzipal, der die Authentifizierungsanforderung empfangen hat, ist nicht mit dem Prinzipal identisch, der an den pszTargetName-Parameter übergeben wurde. Dies weist auf einen Fehler bei der gegenseitigen Authentifizierung hin.

Hinweise

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

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

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

Für einen Zwei-Bein-Sicherheitskontext lautet die aufrufende Sequenz wie folgt:

  1. Der Client ruft die Funktion auf, bei der phContext auf NULL festgelegt ist, und füllt den Pufferdeskriptor mit der Eingabenachricht auf.
  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, weist 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-Funktion (NTLM).
  4. AcceptSecurityContext (NTLM) gibt möglicherweise ein Token zurück, das der Server für einen zweiten Aufruf von InitializeSecurityContext (NTLM) an den Client sendet, wenn der erste Aufruf SEC I CONTINUE NEEDED zurückgegeben _ _ _ hat.

Für Sicherheitskontexte mit mehrerenBeinen, z. B. gegenseitige Authentifizierung, lautet die aufrufende Sequenz wie folgt:

  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 Erhalt der Antwort des Servers ruft der Client erneut InitializeSecurityContext (NTLM) auf, und phContext wird auf das Handle festgelegt, das vom letzten Aufruf zurückgegeben wurde. Das vom Server empfangene Token wird im pInput-Parameter angegeben.

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 Initialisiereneines Sicherheitskontexts kann je nach zugrunde liegendem Authentifizierungsmechanismus und den im fContextReq-Parameter angegebenen Optionen mehr als ein Aufruf dieser Funktion erforderlich sein.

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

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 keine generische Lösung, ermöglicht aber eine starke Kopplung von Sicherheitspaket und Anwendung, wenn dies angemessen ist.

Wenn ISC REQ ALLOCATE MEMORY angegeben wurde, muss der Aufrufer den Arbeitsspeicher durch Aufrufen der _ _ _ FreeContextBuffer-Funktion frei geben.

Beispielsweise könnte das Eingabetoken die Herausforderung eines LAN-Managers sein. In diesem Fall wäre das Ausgabetoken die NTLM-verschlüsselte Antwort auf die Abfrage.

Die Vom Client ausgeführte Aktion hängt vom Rückgabecode dieser Funktion ab. Wenn der Rückgabecode SEC E OK ist, wird kein zweiter _ _ InitializeSecurityContext-Aufruf (NTLM) 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 an _ _ _ InitializeSecurityContext (NTLM). Der SEC I COMPLETE NEEDED-Rückgabecode gibt an, dass der Client die Meldung fertig stellen und _ _ die _ CompleteAuthToken-Funktion aufrufen muss. Der SEC _ I _ COMPLETE AND _ _ CONTINUE-Code enthält beide Aktionen.

Wenn InitializeSecurityContext (NTLM) einen Erfolg beim ersten (oder nur) Aufruf 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 (NTLM) erneut aufrufen, nachdem er erfolgreich abgeschlossen wurde. Dies weist das Sicherheitspaket darauf hin, dass eine erneute Authentifizierung gewünscht ist.

Aufrufer im Kernelmodus haben die folgenden Unterschiede: Der Zielname ist eine Unicode-Zeichenfolge, die mit VirtualAllocim virtuellen Arbeitsspeicher zugeordnet werden muss. sie 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 befindet.

Anforderungen

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

Weitere Informationen

SSPI-Funktionen

AcceptSecurityContext (NTLM)

AcquireCredentialsHandle (NTLM)

CompleteAuthToken

DeleteSecurityContext

FreeContextBuffer

SecBuffer

SecBufferDesc