InitializeSecurityContext-Funktion (Kerberos)
Die InitializeSecurityContext-Funktion (Kerberos) initiiert den clientseitigen ausgehenden Sicherheitskontext von einem Anmeldeinformationshand handle. Die -Funktion wird verwendet, um einen Sicherheitskontext zwischen der Clientanwendung und einem Remote-Peer zu erstellen. InitializeSecurityContext (Kerberos) gibt ein Token zurück, das der Client an den Remote-Peer übergeben muss, den der Peer wiederum über den AcceptSecurityContext-Aufruf (Kerberos) an die lokale Sicherheitsimplementierung übermittelt. Das generierte Token sollte von allen Aufrufern als nicht transparent betrachtet werden.
In der Regel wird die InitializeSecurityContext-Funktion (Kerberos) 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_ 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 (Kerberos) zurückgegeben werden. Dieses Handle wird verwendet, um den Sicherheitskontext zu erstellen. Die InitializeSecurityContext-Funktion (Kerberos) erfordert mindestens OUTBOUND-Anmeldeinformationen.
-
phContext [ in, optional]
-
Ein Zeiger auf eine CTXTHandle-Struktur. Beim ersten Aufruf von InitializeSecurityContext (Kerberos) 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.
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_DELEGATE
Der Server kann den Kontext verwenden, um sich bei anderen Servern als Client zu authentifizieren. Das ISC_REQ_MUTUAL_AUTH-Flag muss festgelegt werden, damit dieses Flag funktioniert. Gültig für Kerberos. Ignorieren Sie dieses Flag für die eingeschränkte Delegierung. - 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 Funktion QueryContextAttributes (Kerberos) auf.- ISC_REQ_NO_INTEGRITY
Wenn dieses Flag festgelegt ist, wird ISC_REQ_INTEGRITY Flag ignoriert. - 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_SESSION_KEY
Ein neuer Sitzungsschlüssel muss ausgehandelt werden. 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 (Kerberos) empfängt dieser Zeiger das neue Kontexthand handle. 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. Da dieser Parameter optional ist, sollte NULL 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 |
|---|---|
|
Der Sicherheitskontext wurde erfolgreich initialisiert. Ein weiterer InitializeSecurityContext-Aufruf (Kerberos) ist nicht 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. |
|
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 (Kerberos). |
|
Der Client muss die Meldung fertig stellen und dann die CompleteAuthToken-Funktion aufrufen. |
|
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 (Kerberos) übergeben. Das Ausgabetoken kann leer sein. |
|
Verwenden Sie mit Schannel. 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. |
Wenn die Funktion fehlschlägt, gibt die Funktion einen der folgenden Fehlercodes zurück.
| Rückgabecode | Beschreibung |
|---|---|
|
Es ist nicht genügend Arbeitsspeicher verfügbar, um die angeforderte Aktion abschließen zu können. |
|
Es ist ein Fehler aufgetreten, der einem SSPI-Fehlercode nicht zuordnen konnte. |
|
Das an die Funktion übergebene Handle ist ungültig. |
|
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. |
|
Fehler bei der Anmeldung. |
|
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. |
|
In der eingeschränkten Delegierung sind keine Anmeldeinformationen verfügbar. |
|
Das Ziel wurde nicht erkannt. |
|
Ein ungültiges Kontextattributflag (ISC _ REQ _ DELEGATE oder ISC _ REQ PROMPT FOR _ _ CREDS) wurde im _ fContextReq-Parameter angegeben. |
|
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 (Kerberos) wird von einem Client verwendet, um einen ausgehenden Kontext zu initialisieren.
Für einen Zwei-Bein-Sicherheitskontext lautet die aufrufende Sequenz wie folgt:
- Der Client ruft die Funktion auf, bei der phContext auf NULL festgelegt ist, und füllt den Pufferdeskriptor mit der Eingabenachricht auf.
- 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.
- 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 (Kerberos).
- AcceptSecurityContext (Kerberos) gibt möglicherweise ein Token zurück, das der Server für einen zweiten Aufruf von InitializeSecurityContext (Kerberos) 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:
- Der Client ruft die Funktion wie zuvor beschrieben auf, aber das Paket gibt den Erfolgscode SEC _ I _ CONTINUE NEEDED _ zurück.
- Der Client sendet das Ausgabetoken an den Server und wartet auf die Antwort des Servers.
- Nach Erhalt der Antwort des Servers ruft der Client erneut InitializeSecurityContext (Kerberos) 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, gibt es keinen zweiten _ _ InitializeSecurityContext (Kerberos)-Aufruf, 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 (Kerberos). 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 (Kerberos) 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 (Kerberos) 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 |
|
| Bibliothek |
|
| DLL |
|