InitializeSecurityContext(Digest)-Funktion

Artikel
06/01/2023

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

In der Regel wird die InitializeSecurityContext -Funktion (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 von AcquireCredentialsHandle (Digest) zurückgegebenen Anmeldeinformationen. Dieses Handle wird verwendet, um den Sicherheitskontext zu erstellen. Für die Funktion InitializeSecurityContext (Digest) sind mindestens AUSGEHENDe Anmeldeinformationen erforderlich.

phContext[in, optional]

Ein Zeiger auf eine CtxtHandle-Struktur . Beim ersten Aufruf von InitializeSecurityContext (Digest) lautet NULLdieser Zeiger . Beim zweiten Aufruf ist dieser Parameter ein Zeiger auf das Handle auf den teilweise gebildeten Kontext, der vom ersten Aufruf im parameter phNewContext zurückgegeben wird.

Warnung

Verwenden Sie nicht denselben Kontexthandle bei gleichzeitigen Aufrufen von InitializeSecurityContext (Digest). Die API-Implementierung in den Sicherheitsdienstanbietern ist nicht threadsicher.

pszTargetName[in, optional]

Ein Zeiger auf eine NULL-Zeichenfolge, die den URI der angeforderten Ressource eindeutig identifiziert. Die Zeichenfolge muss aus Zeichen bestehen, die in einem URI zulässig sind, und 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 eins der folgenden Attribute-Flags sein.

Wert	Bedeutung
ISC_REQ_ALLOCATE_MEMORY	Das Sicherheitspaket weist Ausgabepuffer für Sie zu. Wenn Sie die Verwendung der Ausgabepuffer abgeschlossen haben, geben Sie sie frei, indem Sie die FreeContextBuffer-Funktion aufrufen.
ISC_REQ_CONFIDENTIALITY	Verschlüsseln Sie Nachrichten mithilfe der Funktion EncryptMessage .
ISC_REQ_EXTENDED_ERROR	Wenn Fehler auftreten, wird die Remotepartei benachrichtigt.
ISC_REQ_HTTP	Verwenden Sie Digest für HTTP. Lassen Sie dieses Flag weg, um Digest als SASL-Mechanismus zu verwenden.
ISC_REQ_INTEGRITY	Signieren Sie Nachrichten und überprüfen Sie Die Signaturen mithilfe der Funktionen EncryptMessage und MakeSignature .
ISC_REQ_MUTUAL_AUTH	Die Gegenseitige Authentifizierungsrichtlinie 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. Um sicherzustellen, dass die gegenseitige Authentifizierung ausgeführt wird, rufen Sie die Funktion QueryContextAttributes (Digest) auf.
ISC_REQ_REPLAY_DETECT	Erkennen Sie wiedergegebene Nachrichten, die mit den Funktionen EncryptMessage oder MakeSignature codiert wurden.
ISC_REQ_SEQUENCE_DETECT	Erkennen Sie Nachrichten, die außerhalb der Sequenz empfangen werden.
ISC_REQ_STREAM	Unterstützung einer streamorientierten Verbindung.

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.

Reserviert1[in]

Dieser Parameter ist reserviert und muss auf null festgelegt werden.

TargetDataRep[in]

Dieser Parameter wird nicht mit Digest verwendet. Legen Sie sie auf 0 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 sein NULL . 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 versehen ist, um das vom Remotecomputer zurückgegebene Token aufzunehmen.

Informationen zur Pufferkonfiguration finden Sie unter Eingabepuffer für die Digest-Challenge-Antwort.

Reserviert2[in]

Dieser Parameter ist reserviert und muss auf 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. phNewContext sollte niemals sein NULL.

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 als SEC_READWRITE in der Eingabe eingegeben wurde, ist er bei der Ausgabe vorhanden. Das System weist bei 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 Anforderungsantwort, die an den Server gesendet werden muss.

pfContextAttr[out]

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 .

Suchen 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.

Hinweis

Bestimmte Kontextattribute können sich während der Aushandlung mit einem Remotepeer ä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
SEC_E_OK	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 nicht zero-Länge aufweist, 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 weiteren Aufruf an InitializeSecurityContext (Digest).
SEC_I_COMPLETE_NEEDED	Der Client muss die Erstellung der Nachricht beenden und dann die Funktion CompleteAuthToken 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 weiteren Aufruf von InitializeSecurityContext (Digest) übergeben. Das Ausgabetoken kann leer sein.
SEC_I_INCOMPLETE_CREDENTIALS	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 wurde. Weitere Informationen finden Sie in den Hinweisen.

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.
SEC_E_INTERNAL_ERROR	Es ist ein Fehler aufgetreten, 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. ein bei der Übertragung beschädigtes Token, ein Token mit falscher Größe oder ein Token, das an die falsche eingeschränkte Delegierung übergeben wurde. Die Übergabe eines Tokens an das falsche Paket kann auftreten, wenn der Client und der Server nicht die richtige eingeschränkte Delegierung ausgehandelt haben.
SEC_E_LOGON_DENIED	Fehler bei der Anmeldung.
SEC_E_NO_AUTHENTICATING_AUTHORITY	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.
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_UNSUPPORTED_FUNCTION	Im fContextReq-Parameter wurde ein ungültiges Kontextattributeflag angegeben (ISC_REQ_DELEGATE oder ISC_REQ_PROMPT_FOR_CREDS).
SEC_E_WRONG_PRINCIPAL	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.

Bemerkungen

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 (Digest) 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 (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.

Für Sicherheitskontextemit mehreren Beinen, z. B. gegenseitige Authentifizierung, lautet die Aufrufsequenz wie folgt:

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 (Digest) 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.
Verwenden Sie den wert phContext nicht in gleichzeitigen Aufrufen von InitializeSecurityContext (Digest). Die Implementierung in den Sicherheitsanbietern ist nicht threadsicher.

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.

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 (Digest) -Aufruf 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 (Digest). Der SEC_I_COMPLETE_NEEDED Rückgabecode gibt an, dass der Client die Erstellung der Nachricht beenden und die Funktion CompleteAuthToken aufrufen muss. Der SEC_I_COMPLETE_AND_CONTINUE Code enthält beide Aktionen.

Wenn InitializeSecurityContext (Digest) beim ersten (oder nur) Aufruf erfolgreich zurückgibt, 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 (Digest) erneut aufrufen, nachdem er erfolgreich abgeschlossen wurde. Dies gibt dem Sicherheitspaket an, dass eine erneute Authentifizierung gewünscht wird.

Aufrufer im Kernelmodus 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 zugeordnet werden. Puffer, die in pInput und pOutput übergeben und bereitgestellt werden, müssen sich im virtuellen Speicher und nicht im Pool befinden.

Anforderungen

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