InitializeSecurityContextA-Funktion (sspi.h)
Die Funktion InitializeSecurityContext (Allgemein) initiiert den clientseitigen ausgehenden Sicherheitskontext aus einem Anmeldeinformationshandle. Die Funktion wird verwendet, um einen Sicherheitskontext zwischen der Clientanwendung und einem Remotepeer zu erstellen. InitializeSecurityContext (General) gibt ein Token zurück, das der Client an den Remotepeer übergeben muss, den der Peer wiederum über den AcceptSecurityContext -Aufruf (Allgemein) an die lokale Sicherheitsimplementierung übermittelt. Das generierte Token sollte von allen Aufrufenden als undurchsichtig betrachtet werden.
In der Regel wird die Funktion InitializeSecurityContext (General) in einer Schleife aufgerufen, bis ein ausreichender Sicherheitskontext eingerichtet ist.
Informationen zur Verwendung dieser Funktion mit einem bestimmten Sicherheitsunterstützungsanbieter (Security Support Provider , SSP) finden Sie in den folgenden Themen.
Thema | BESCHREIBUNG |
---|---|
InitializeSecurityContext (CredSSP) | Initiiert den clientseitigen ausgehenden Sicherheitskontext aus einem Anmeldeinformationshandle mithilfe des Credential Security Support Provider (CredSSP). |
InitializeSecurityContext (Digest) | Initiiert den clientseitigen ausgehenden Sicherheitskontext aus einem Anmeldeinformationshandle mithilfe des Digestsicherheitspakets. |
InitializeSecurityContext (Kerberos) | Initiiert den clientseitigen ausgehenden Sicherheitskontext aus einem Anmeldeinformationshandle mithilfe des Kerberos-Sicherheitspakets. |
InitializeSecurityContext (Negotiate) | Initiiert den clientseitigen ausgehenden Sicherheitskontext aus einem Anmeldeinformationshandle mithilfe des Sicherheitspakets Negotiate. |
InitializeSecurityContext (NTLM) | Initiiert den clientseitigen ausgehenden Sicherheitskontext aus einem Anmeldeinformationshandle mithilfe des NTLM-Sicherheitspakets. |
InitializeSecurityContext (Schannel) | Initiiert den clientseitigen ausgehenden Sicherheitskontext aus einem Anmeldeinformationshandle mithilfe des Schannel-Sicherheitspakets. |
Syntax
SECURITY_STATUS SEC_ENTRY InitializeSecurityContextA(
[in, optional] PCredHandle phCredential,
[in, optional] PCtxtHandle phContext,
SEC_CHAR *pszTargetName,
[in] unsigned long fContextReq,
[in] unsigned long Reserved1,
[in] unsigned long TargetDataRep,
[in, optional] PSecBufferDesc pInput,
[in] unsigned long Reserved2,
[in, out, optional] PCtxtHandle phNewContext,
[in, out, optional] PSecBufferDesc pOutput,
[out] unsigned long *pfContextAttr,
[out, optional] PTimeStamp ptsExpiry
);
Parameter
[in, optional] phCredential
Ein Handle für die von AcquireCredentialsHandle (Allgemein) zurückgegebenenAnmeldeinformationen. Dieses Handle wird verwendet, um den Sicherheitskontext zu erstellen. Die Funktion InitializeSecurityContext (Allgemein) erfordert mindestens OUTBOUND-Anmeldeinformationen.
[in, optional] phContext
Ein Zeiger auf eine CtxtHandle-Struktur . Beim ersten Aufruf von InitializeSecurityContext (General) ist dieser Zeiger NULL. Beim zweiten Aufruf ist dieser Parameter ein Zeiger auf das Handle auf den teilgeformten Kontext, der im phNewContext-Parameter vom ersten Aufruf zurückgegeben wird.
Dieser Parameter ist mit dem Microsoft Digest SSP optional und kann auf NULL festgelegt werden.
Wenn Sie den Schannel-SSP verwenden, geben Sie beim ersten Aufruf von InitializeSecurityContext (Allgemein)NULL an. Geben Sie bei zukünftigen Aufrufen das Token an, das nach dem ersten Aufruf dieser Funktion im parameter phNewContext empfangen wurde.
pszTargetName
TBD
[in] fContextReq
Bitflags, die Anforderungen für den Kontext angeben. Nicht alle Pakete können alle Anforderungen unterstützen. Für diesen Parameter verwendete Flags wird ISC_REQ_ vorangestellt, z. B. ISC_REQ_DELEGATE. Bei diesem Parameter kann es sich um ein oder mehrere der folgenden Attribute-Flags handelt.
Wert | Bedeutung |
---|---|
|
Das Sicherheitspaket ordnet Ausgabepuffer für Sie zu. Wenn Sie die Verwendung der Ausgabepuffer abgeschlossen haben, geben Sie sie frei, indem Sie die Funktion FreeContextBuffer aufrufen. |
|
Verschlüsseln sie Nachrichten mithilfe der Funktion EncryptMessage . |
|
Der Sicherheitskontext behandelt keine Formatierungsmeldungen. Dieser Wert ist der Standardwert für die Sicherheitspakete Kerberos, Negotiate und NTLM. |
|
Der Server kann den Kontext verwenden, um sich bei anderen Servern als Client zu authentifizieren. Das flag ISC_REQ_MUTUAL_AUTH muss festgelegt werden, damit dieses Flag funktioniert. Gültig für Kerberos. Ignorieren Sie dieses Flag für die eingeschränkte Delegierung. |
|
Wenn Fehler auftreten, wird die Remotepartei benachrichtigt. |
|
Verwenden Sie Digest für HTTP. Lassen Sie dieses Flag aus, um Digest als SASL-Mechanismus zu verwenden. |
|
Signieren Sie Nachrichten, und überprüfen Sie Signaturen mithilfe der Funktionen EncryptMessage und MakeSignature . |
|
Schannel darf den Server nicht automatisch authentifizieren. |
|
Die Richtlinie für die gegenseitige Authentifizierung des Diensts wird erfüllt.
Vorsicht Dies bedeutet nicht unbedingt, dass die gegenseitige Authentifizierung durchgeführt wird, nur dass die Authentifizierungsrichtlinie des Diensts erfüllt ist. Rufen Sie die Funktion QueryContextAttributes (Allgemein) auf, um sicherzustellen, dass die gegenseitige Authentifizierung durchgeführt wird.
|
|
Wenn dieses Flag festgelegt ist, wird das ISC_REQ_INTEGRITY-Flag ignoriert.
Dieser Wert wird nur von den Sicherheitspaketen Negotiate und Kerberos unterstützt. |
|
Erkennen wiedergegebener Nachrichten, die mithilfe der Funktionen EncryptMessage oder MakeSignature codiert wurden. |
|
Erkennen von Nachrichten, die außerhalb der Reihenfolge empfangen werden. |
|
Unterstützung einer streamorientierten Verbindung. |
|
Ein neuer Sitzungsschlüssel muss ausgehandelt werden.
Dieser Wert wird nur vom Kerberos-Sicherheitspaket unterstützt. |
|
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 im PfContextAttr-Parameter .
Weitere Beschreibungen der verschiedenen Attribute finden Sie unter Kontextanforderungen.
[in] Reserved1
Dieser Parameter ist reserviert und muss auf null festgelegt werden.
[in] TargetDataRep
Die Datendarstellung, z. B. bytereihenfolge, auf dem Ziel. Dieser Parameter kann entweder SECURITY_NATIVE_DREP oder SECURITY_NETWORK_DREP sein.
Dieser Parameter wird nicht mit Digest oder Schannel verwendet. Legen Sie ihn auf 0 (null) fest.
[in, optional] pInput
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 belegt ist, um das vom Remotecomputer zurückgegebene Token zu speichern.
[in] Reserved2
Dieser Parameter ist reserviert und muss auf null festgelegt werden.
[in, out, optional] phNewContext
Ein Zeiger auf eine CtxtHandle-Struktur . Beim ersten Aufruf von InitializeSecurityContext (General) empfängt dieser Zeiger das neue Kontexthandle. Beim zweiten Aufruf kann phNewContext mit dem im parameter phContext angegebenen Handle identisch sein.
Wenn Sie den Schannel-SSP verwenden, übergeben Sie bei Aufrufen nach dem ersten Aufruf das hier zurückgegebene Handle als phContext-Parameter , und geben Sie NULL für phNewContext an.
[in, out, optional] pOutput
Ein Zeiger auf eine SecBufferDesc-Struktur , die Zeiger auf die SecBuffer-Struktur enthält, die die Ausgabedaten empfängt. Wenn ein Puffer als SEC_READWRITE in der Eingabe eingegeben wurde, ist er bei der Ausgabe vorhanden. Das System ordnet einen Puffer für das Sicherheitstoken zu, wenn es angefordert wird (über ISC_REQ_ALLOCATE_MEMORY) und füllt die Adresse im Pufferdeskriptor für das Sicherheitstoken ein.
Bei Verwendung des Microsoft Digest-SSP empfängt dieser Parameter die Anforderungsantwort, die an den Server gesendet werden muss.
Wenn bei Verwendung des Schannel-SSP das ISC_REQ_ALLOCATE_MEMORY-Flag angegeben ist, weist der Schannel-SSP Arbeitsspeicher für den Puffer zu und platziert die entsprechenden Informationen in SecBufferDesc. 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.
[out] pfContextAttr
Ein Zeiger auf eine Variable, um eine Reihe von Bitflags zu empfangen, die die Attribute des eingerichteten Kontexts angeben. Eine Beschreibung der verschiedenen Attribute finden Sie unter Kontextanforderungen.
Für diesen Parameter verwendete Flags wird ISC_RET vorangestellt, z. B. ISC_RET_DELEGATE.
Eine Liste der gültigen Werte finden Sie im fContextReq-Parameter .
Überprüfen Sie erst nach sicherheitsbezogenen Attributen, bis der endgültige Funktionsaufruf erfolgreich zurückgegeben wird. Attributflags, die sich nicht auf die Sicherheit beziehen, z. B. das ASC_RET_ALLOCATED_MEMORY-Flag, können vor der endgültigen Rückgabe überprüft werden.
[out, optional] ptsExpiry
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.
Es gibt keine Ablaufzeit für Microsoft Digest SSP-Sicherheitskontexte oder Anmeldeinformationen.
Rückgabewert
Wenn die Funktion erfolgreich ist, gibt die Funktion einen der folgenden Erfolgscodes zurück.
Rückgabecode | Beschreibung |
---|---|
|
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 (General). |
|
Der Client muss die Erstellung der Nachricht beenden und dann die Funktion CompleteAuthToken aufrufen. |
|
Der Client muss das Ausgabetoken an den Server senden und auf ein Rückgabetoken warten. Das zurückgegebene Token wird dann in einem weiteren Aufruf von InitializeSecurityContext (General) ü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, der der Server vertraut. Weitere Informationen finden Sie in den Hinweisen. |
|
Verwenden Sie mit Schannel. 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. 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 ist. Obwohl diese Zahl nicht immer korrekt ist, kann sie zur Verbesserung der Leistung beitragen, indem mehrere Aufrufe dieser Funktion vermieden werden. |
|
Der Sicherheitskontext wurde erfolgreich initialisiert. Es ist kein weiterer InitializeSecurityContext -Aufruf (Allgemein) erforderlich. Wenn die Funktion ein Ausgabetoken zurückgibt, d. h. wenn das SECBUFFER_TOKEN in pOutput eine Länge ungleich 0 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 |
---|---|
|
Es ist nicht genügend Arbeitsspeicher verfügbar, um die angeforderte Aktion abzuschließen. |
|
Es ist ein Fehler aufgetreten, 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. ein bei der Übertragung beschädigtes Token, ein Token mit falscher Größe oder ein Token, das an das falsche Sicherheitspaket übergeben wurde. Die Übergabe eines Tokens an das falsche Paket kann passieren, wenn client und server nicht das richtige Sicherheitspaket ausgehandelt haben. |
|
Fehler bei der Anmeldung. |
|
Es konnte keine Autorität für die Authentifizierung kontaktiert werden. Der Domänenname der Authentifizierungspartei kann falsch sein, die Domäne kann nicht erreichbar sein, oder es ist möglicherweise ein Vertrauensstellungsfehler aufgetreten. |
|
Im Sicherheitspaket sind keine Anmeldeinformationen verfügbar. |
|
Das Ziel wurde nicht erkannt. |
|
Im fContextReq-Parameter wurde ein ungültiges Kontextattributeflag angegeben (ISC_REQ_DELEGATE oder ISC_REQ_PROMPT_FOR_CREDS). |
|
Der Prinzipal, der die Authentifizierungsanforderung empfangen hat, entspricht nicht dem Prinzipal, der an den parameter pszTargetName übergeben wurde. Dies deutet 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 hergestellt 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.
Die Funktion InitializeSecurityContext (Allgemein) wird von einem Client verwendet, 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, belegt das Sicherheitspaket den Arbeitsspeicher 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 (General) -Funktion.
- AcceptSecurityContext (General) gibt möglicherweise ein Token zurück, das der Server für einen zweiten Aufruf von InitializeSecurityContext (Allgemein) an den Client sendet, wenn der erste Aufruf SEC_I_CONTINUE_NEEDED.
- Der Client ruft die Funktion wie zuvor beschrieben auf, aber das Paket gibt den SEC_I_CONTINUE_NEEDED Erfolgscode 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 InitializeSecurityContext (Allgemein) 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 angegeben.
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.
Um einen Sicherheitskontext zu initialisieren, sind möglicherweise mehrere Aufrufe dieser Funktion erforderlich, abhängig vom zugrunde liegenden Authentifizierungsmechanismus und den im fContextReq-Parameter angegebenen Auswahlmöglichkeiten.
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, wenn Sie die Flags untersuchen, die sich auf Sicherheitsaspekte des Kontexts beziehen. Zwischenzeitliche Rückgaben können z. B. das flag ISC_RET_ALLOCATED_MEMORY festlegen.
Wenn das flag ISC_REQ_USE_SUPPLIED_CREDS festgelegt ist, muss das Sicherheitspaket im pInput-Eingabepuffer nach einem SECBUFFER_PKG_PARAMS Puffertyp suchen. Dies ist 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 wäre das Ausgabetoken die NTLM-verschlüsselte Antwort auf die Anforderung.
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 (Allgemein) 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 (General).. Der SEC_I_COMPLETE_NEEDED Rückgabecode gibt an, dass der Client die Erstellung der Nachricht abschließen und die Funktion CompleteAuthToken aufrufen muss. Der SEC_I_COMPLETE_AND_CONTINUE-Code enthält beide Aktionen.
Wenn InitializeSecurityContext (Allgemein) 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 (General) 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 Sie den Schannel-SSP verwenden, überprüfen Sie, ob Sie in Ihren Anmeldeinformationen ein gültiges und vertrauenswürdiges Zertifikat angegeben haben, wenn die Funktion SEC_I_INCOMPLETE_CREDENTIALS zurückgibt. Das Zertifikat wird beim Aufrufen der Funktion AcquireCredentialsHandle (General) angegeben. Bei dem Zertifikat muss es sich um ein Clientauthentifizierungszertifikat handeln, das von einer Zertifizierungsstelle ausgestellt wurde, der der Server vertraut. Um eine Liste der vom Server vertrauenswürdigen Zertifizierungsstellen abzurufen, rufen Sie die Funktion QueryContextAttributes (General) auf, und geben Sie das attribut SECPKG_ATTR_ISSUER_LIST_EX an.
Wenn Sie den Schannel-SSP verwenden, erstellt die Anwendung, nachdem eine Clientanwendung ein Authentifizierungszertifikat von einer Vom Server vertrauenswürdigen Zertifizierungsstelle empfangen hat, neue Anmeldeinformationen, indem sie die Funktion AcquireCredentialsHandle (General) aufruft und dann InitializeSecurityContext (General) erneut aufruft, wobei die neuen Anmeldeinformationen im parameter phCredential angegeben werden.
Hinweis
Der sspi.h-Header definiert InitializeSecurityContext als Alias, der die ANSI- oder Unicode-Version dieser Funktion basierend auf der Definition der UNICODE-Präprozessorkonstante automatisch auswählt. Das Mischen der Verwendung des codierungsneutralen Alias mit nicht codierungsneutralem Code kann zu Nichtübereinstimmungen führen, die zu Kompilierungs- oder Laufzeitfehlern führen. Weitere Informationen finden Sie unter Konventionen für Funktionsprototypen.
Anforderungen
Anforderung | Wert |
---|---|
Unterstützte Mindestversion (Client) | Windows XP [nur Desktop-Apps] |
Unterstützte Mindestversion (Server) | Windows Server 2003 [nur Desktop-Apps] |
Zielplattform | Windows |
Kopfzeile | sspi.h (einschließlich Security.h) |
Bibliothek | Secur32.lib |
DLL | Secur32.dll |
Weitere Informationen
AcceptSecurityContext (Allgemein)