InitializeSecurityContext(Digest)-Funktion
Die Funktion InitializeSecurityContext (Digest) initiiert den clientseitigen ausgehenden Sicherheitskontext von einem Anmeldeinformationshandle. Die -Funktion wird verwendet, um einen Sicherheitskontext zwischen der Clientanwendung und einem Remotespeer zu erstellen. InitializeSecurityContext (Digest) gibt ein Token zurück, das der Client an den Remotespeer übergeben muss, den der Peer wiederum über den AcceptSecurityContext-Aufruf (Digest) an die lokale Sicherheitsimplementierungen übermittelt. Das generierte Token sollte von allen Aufrufern als nicht transparent betrachtet werden.
In der Regel wird die Funktion InitializeSecurityContext (Digest) 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_ 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 (Digest)zurückgegeben werden. Dieses Handle wird verwendet, um den Sicherheitskontextzu erstellen. Die Funktion InitializeSecurityContext (Digest) erfordert mindestens OUTBOUND-Anmeldeinformationen.
-
phContext [ in, optional]
-
Ein Zeiger auf eine CTXTHandle-Struktur. Beim ersten Aufruf von InitializeSecurityContext (Digest) 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.
Dieser Parameter ist optional und kann auf NULL festgelegt werden.
-
pszTargetName [ in, optional]
-
Ein Zeiger auf eine auf NULL endende Zeichenfolge, die den URI der angeforderten Ressource eindeutig identifiziert. Die Zeichenfolge muss aus Zeichen bestehen, die in einem URI zulässig sind, und muss durch den US ASCII-Codesatz darstellbar sein. Die Prozentcodierung kann verwendet werden, um Zeichen außerhalb des US ASCII-Codesatzes darzustellen.
-
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 Ihnen Ausgabepuffer zu. Wenn Sie die Verwendung der Ausgabepuffer abgeschlossen haben, können Sie sie freigeben, indem Sie die FreeContextBuffer-Funktion aufrufen. - ISC_REQ_CONFIDENTIALITY
Verschlüsseln Sie Nachrichten mithilfe der EncryptMessage-Funktion. - ISC_REQ_EXTENDED_ERROR
Wenn Fehler auftreten, wird die Remotepartei benachrichtigt. - ISC_REQ_HTTP
Verwenden Sie Digest für HTTP. Lassen Sie dieses Flag aus, um Digest als SASL-Mechanismus zu verwenden. - ISC_REQ_INTEGRITY
Signieren Sie Nachrichten, und überprüfen Sie Signaturen mithilfe der Funktionen EncryptMessage und MakeSignature. - ISC_REQ_MUTUAL_AUTH
Die gegenseitige Authentifizierungsrichtlinie des Diensts wird erfüllt. [!Caution]
Dies bedeutet nicht unbedingt, dass die gegenseitige Authentifizierung ausgeführt wird, sondern nur, dass die Authentifizierungsrichtlinie des Diensts erfüllt ist. Um sicherzustellen, dass die gegenseitige Authentifizierung durchgeführt wird, rufen Sie die Funktion QueryContextAttributes (Digest) auf.- ISC_REQ_REPLAY_DETECT
Erkennen sie wiedergegebene Nachrichten, die mithilfe der Funktionen EncryptMessage oder MakeSignature codiert wurden. - ISC_REQ_SEQUENCE_DETECT
Erkennen von Nachrichten, die außerhalb der Sequenz empfangen wurden. - ISC_REQ_STREAM
Unterstützung einer streamorientierten Verbindung. Die angeforderten Attribute werden vom Client möglicherweise nicht unterstützt. Weitere Informationen finden Sie unter dem pfContextAttr-Parameter.
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 Digest verwendet. Legen Sie ihn 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 für das vom Remotecomputer zurückgegebene Token zugeordnet ist.
Informationen zur Pufferkonfiguration finden Sie unter Eingabepuffer für die Digest-Abfrageantwort.
-
Reserviert2 [ 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 (Digest) empfängt dieser Zeiger das neue Kontexthandle. 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 bei der Ausgabe vorhanden. Das System ordnet auf Anforderung (über ISC REQ ALLOCATE MEMORY) einen Puffer für das Sicherheitstoken zu _ und gibt die Adresse im _ _ Pufferdeskriptor für das Sicherheitstoken ein.
Dieser Parameter empfängt die Abfrageantwort, die an den Server gesendet werden muss.
-
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, haben das Präfix ISC _ RET, z. B. ISC _ RET _ DELEGATE. Eine Liste gültiger Werte finden Sie im fContextReq-Parameter.
Suchen Sie erst nach sicherheitsrelevanten Attributen, wenn der letzte Funktionsaufruf erfolgreich zurückgegeben wurde. Attributflags, die nicht mit der Sicherheit in Zusammenhang stehen, 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 Remotespeer ändern.
-
ptsExpiry [ out, optional]
-
Ein Zeiger auf eine TimeStamp-Struktur, die die Ablaufzeit des Kontexts empfängt.
Es gibt keine Ablaufzeit für Microsoft Digest SSP-Sicherheitskontexteoder Anmeldeinformationen.
Rückgabewert
Wenn die Funktion erfolgreich ist, gibt die Funktion einen der folgenden Erfolgscodes zurück.
| Rückgabecode | Beschreibung |
|---|---|
|
Der Sicherheitskontext wurde erfolgreich initialisiert. Es ist kein weiterer InitializeSecurityContext-Aufruf (Digest) 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. |
|
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 (Digest). |
|
Der Client muss die Erstellung der Nachricht abschließen 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 (Digest)ü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 dem 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 |
|---|---|
|
Es ist nicht genügend Arbeitsspeicher verfügbar, um die angeforderte Aktion abzuschließen. |
|
Fehler, der keinem SSPI-Fehlercode zugeordnet wurde. |
|
Das an die Funktion übergebene Handle ist ungültig. |
|
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. |
|
Fehler bei der Anmeldung. |
|
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. |
|
In der eingeschränkten Delegierungsind keine Anmeldeinformationen verfügbar. |
|
Das Ziel wurde nicht erkannt. |
|
Im fContextReq-Parameter wurde ein ungültiges Kontextattributflag _ _ (ISC REQ DELEGATE oder ISC _ REQ _ PROMPT FOR _ _ CREDS) angegeben. |
|
Der Prinzipal, der die Authentifizierungsanforderung empfangen hat, ist nicht identisch mit dem Prinzipal, der an den Parameter pszTargetName ü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 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 Funktion InitializeSecurityContext (Digest) wird von einem Client verwendet, um einen ausgehenden Kontext zu initialisieren.
Für einen zweistufigen Sicherheitskontextsieht die aufrufende Sequenz wie folgt aus:
- 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 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.
- Der Client sendet das im pOutput-Puffer zurückgegebene Token an den Zielserver. Der Server übergibt dann das Token als Eingabeargument in einem Aufruf der AcceptSecurityContext (Digest)-Funktion.
- AcceptSecurityContext (Digest) gibt möglicherweise ein Token zurück, das der Server für einen zweiten Aufruf von InitializeSecurityContext (Digest) 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:
- 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 (Digest) 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 (Digest), 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 (Digest). 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 (Digest) 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 in einem späteren Abschnitt des Authentifizierungsaustauschs fehlschlägt.
Der Client kann InitializeSecurityContext (Digest) 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.
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 |
|