InitializeSecurityContext (CredSSP)-Funktion

Die InitializeSecurityContext (CredSSP) -Funktion initiiert den clientseitigen, ausgehenden Sicherheitskontext aus einem Anmeldeinformationshandle. Die Funktion erstellt einen Sicherheitskontext zwischen der Clientanwendung und einem Remotepeer. InitializeSecurityContext (CredSSP) gibt ein Token zurück, das der Client an den Remotepeer übergeben muss; der Peer sendet dieses Token wiederum über den AcceptSecurityContext (CredSSP) -Aufruf an die lokale Sicherheitsimplementierung. Das generierte Token sollte von allen Aufrufern als undurchsichtig betrachtet werden.

In der Regel wird die Funktion InitializeSecurityContext (CredSSP) 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_opt_    SEC_CHAR       *pszTargetName,
  _In_        unsigned long  fContextReq,
  _Reserved_  unsigned long  Reserved1,
  _In_        unsigned long  TargetDataRep,
  _Inout_opt_ PSecBufferDesc pInput,
  _In_        unsigned long  Reserved2,
  _Inout_opt_ PCtxtHandle    phNewContext,
  _Out_opt_   PSecBufferDesc pOutput,
  _Out_       unsigned long  *pfContextAttr,
  _Out_opt_   PTimeStamp     ptsExpiry
);

Die Parameter

phCredential (englisch)[in, optional]

Ein Handle für die von AcquireCredentialsHandle (CredSSP) zurückgegebenen Anmeldeinformationen. Dieses Handle wird verwendet, um den Sicherheitskontext zu erstellen. Die Funktion InitializeSecurityContext (CredSSP) erfordert mindestens AUSGEHENDe Anmeldeinformationen.

phContext (englisch)[in, optional]

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

Geben Sie für den ersten Aufruf von InitializeSecurityContext (CredSSP) an NULL. Geben Sie bei zukünftigen Aufrufen das token an, das im parameter phNewContext empfangen wurde, nachdem der erste Aufruf dieser Funktion aufgerufen wurde.

pSoll-Name[in, optional]

Ein Zeiger auf eine mit Null beendete Zeichenfolge, die den Zielserver eindeutig identifiziert. Schannel verwendet diesen Wert, um das Serverzertifikat zu überprüfen. Schannel verwendet diesen Wert auch, um die Sitzung im Sitzungscache zu suchen, wenn eine Verbindung wiederhergestellt wird. Die zwischengespeicherte Sitzung wird nur verwendet, wenn alle folgenden Bedingungen erfüllt sind:

• Der Zielname ist identisch.
• Der Cacheeintrag ist nicht abgelaufen.
• Der Anwendungsprozess, der die Funktion aufruft, ist identisch.
• Die Anmeldesitzung ist identisch.
• Der Anmeldeinformationshandle ist identisch.

fContextReq[in]

Bitkennzeichnungen, die Anforderungen für den Kontext angeben. Nicht alle Pakete können alle Anforderungen unterstützen. Kennzeichen, die für diesen Parameter verwendet werden, werden ISC_REQ_ vorangestellt, z. B. ISC_REQ_DELEGATE.

Dieser Parameter kann mindestens eins der folgenden Attributkennzeichnungen sein.

Die angeforderten Attribute werden möglicherweise vom Client nicht unterstützt. Weitere Informationen finden Sie im Parameter pfContextAttr .

Weitere Beschreibungen der verschiedenen Attribute finden Sie unter Kontextanforderungen.

Reserviert1[in]

Reserviert. Dieser Parameter muss auf Null festgelegt werden.

TargetDataRep[in]

Die Datendarstellung, z. B. Byte-Sortierung, auf dem Ziel. Dieser Parameter kann entweder SECURITY_NATIVE_DREP oder SECURITY_NETWORK_DREP sein.

pEingang[in, out, 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 sich der Wert dieses Parameters auf dem ersten Aufruf der Funktion befinden NULL . Bei nachfolgenden Aufrufen der Funktion oder beim Initiieren des Clientkontexts vom Server ist der Wert dieses Parameters ein Zeiger auf einen Puffer, der genügend Arbeitsspeicher zugeordnet ist, um das vom Remotecomputer zurückgegebene Token zu speichern.

Bei Aufrufen dieser Funktion nach dem anfänglichen Aufruf müssen zwei Puffer vorhanden sein. Der erste hat typ SECBUFFER_TOKEN und enthält das vom Server empfangene Token. Der zweite Puffer hat Typ SECBUFFER_EMPTY; legen Sie sowohl die PvBuffer - als auch cbBuffer-Elemente auf Null fest.

Reserviert2[in]

Reserviert. Dieser Parameter muss auf Null festgelegt werden.

phNewContext[in, out, optional]

Ein Zeiger auf eine CtxtHandle-Struktur. Beim ersten Aufruf von InitializeSecurityContext (CredSSP) empfängt dieser Zeiger das neue Kontexthandle. Im zweiten Aufruf kann phNewContext mit dem im phContext-Parameter angegebenen Handle identisch sein. phNewContext sollte niemals NULL sein.

p-Ausgang[out, optional]

Ein Zeiger auf eine SecBufferDesc-Struktur . Diese Struktur enthält wiederum Zeiger auf die SecBuffer-Struktur , die die Ausgabedaten empfängt. Wenn ein Puffer als SEC_READWRITE in die Eingabe eingegeben wurde, wird er in der Ausgabe angezeigt. Das System weist einen Puffer für das Sicherheitstoken zu, falls angefordert (über ISC_REQ_ALLOCATE_MEMORY) und füllt die Adresse im Pufferdeskriptor für das Sicherheitstoken aus.

Wenn das ISC_REQ_ALLOCATE_MEMORY Flag angegeben ist, weist CredSSP Speicher für den Puffer zu und platziert die entsprechenden Informationen in secBufferDesc.

pfContextAttr[out]

Ein Zeiger auf eine Gruppe von Bitkennzeichnungen, die die Attribute des etablierten Kontexts angeben. Eine Beschreibung der verschiedenen Attribute finden Sie unter Kontextanforderungen.

Für diesen Parameter verwendete Flags werden ISC_RET vorangestellt, z. B. ISC_RET_DELEGATE. Eine Liste der gültigen Werte finden Sie im fContextReq-Parameter .

Überprüfen Sie erst auf sicherheitsbezogene Attribute, wenn der endgültige Funktionsaufruf erfolgreich zurückgegeben wurde. Attributkennzeichnungen, 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.

ptsAblaufdatum[out, optional]

Ein Zeiger auf eine TimeStamp-Struktur, welche die Ablaufzeit des Kontexts empfängt. Es wird empfohlen, dass das Sicherheitspaket diesen Wert immer in der lokalen Zeit zurückgibt. Dieser Parameter ist optional und NULL sollte für kurzlebige Clients übergeben werden.

Rückgabewert

Wenn die Funktion erfolgreich ist, wird eine der folgenden Erfolgscodes zurückgegeben.

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

Bemerkungen

Der Aufrufer ist dafür verantwortlich, zu bestimmen, ob die endgültigen Kontextattribute ausreichen. Wenn beispielsweise die Vertraulichkeit angefordert wurde, aber nicht eingerichtet 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.

Der Client ruft die InitializeSecurityContext (CredSSP) -Funktion auf, um einen ausgehenden Kontext zu initialisieren.

Für einen zweistufigen Sicherheitskontext lautet die Aufrufsequenz wie folgt:

1. Der Client ruft die Funktion mit phContext-Satz auf NULL und füllt den Pufferdeskriptor mit der Eingabemeldung aus.
2. Das Sicherheitspaket untersucht die Parameter und erstellt ein undurchsichtiges 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 Speicher 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 (CredSSP) -Funktion.
4. AcceptSecurityContext (CredSSP) kann ein Token zurückgeben. Der Server sendet dieses Token über einen zweiten InitializeSecurityContext (CredSSP) -Aufruf an den Client, wenn der erste Aufruf SEC_I_CONTINUE_NEEDED zurückgegeben wurde.

Wenn der Server erfolgreich reagiert 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.

Für die Initialisierung des Sicherheitskontexts sind je nach zugrunde liegendem Authentifizierungsmechanismus sowie 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. Während der Parameter pfContextAttributes für eine erfolgreiche Rückgabe gültig ist, sollten Sie die Flags untersuchen, die sicherheitsrelevante Aspekte des Kontexts betreffen, nur bei der endgültigen erfolgreichen Rückgabe. Zwischenrückzeichen können z. B. die ISC_RET_ALLOCATED_MEMORY-Kennzeichnung 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 zwar keine generische Lösung, ermöglicht aber bei Bedarf eine starke Kopplung von Sicherheitspaketen und Anwendungen.

Wenn ISC_REQ_ALLOCATE_MEMORY angegeben wurde, muss der Aufrufer den Speicher freigeben, indem die FreeContextBuffer-Funktion aufgerufen wird.

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 Aktion, die der Client ausführt, hängt vom Rückgabecode dieser Funktion ab. Wenn der Rückgabecode SEC_E_OK ist, gibt es keinen zweiten InitializeSecurityContext (CredSSP) -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 (CredSSP). 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 enthält beide Aktionen.

Wenn InitializeSecurityContext (CredSSP) Erfolg für den ersten (oder nur) Aufruf zurückgibt, muss der Aufrufer schließlich die DeleteSecurityContext-Funktion für das zurückgegebene Handle aufrufen, auch wenn der Anruf bei einem späteren Teil des Authentifizierungsaustauschs fehlschlägt.

Der Client kann InitializeSecurityContext (CredSSP) erneut aufrufen, nachdem er erfolgreich abgeschlossen wurde. Dies gibt an, dass für das Sicherheitspaket eine erneute Authentifizierung gewünscht wird.

Kernelmodus-Aufrufer weisen die folgenden Unterschiede auf: Der Zielname ist eine Unicode-Zeichenfolge , die mithilfe von VirtualAlloc im virtuellen Speicher zugewiesen 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 Speicher befinden, nicht im Pool.

Wenn die Funktion SEC_I_INCOMPLETE_CREDENTIALS zurückgibt, überprüfen Sie, ob die r-Anmeldeinformationen, die an die AcquireCredentialsHandle (CredSSP) -Funktion übergeben wurden, ein gültiges und vertrauenswürdiges Zertifikat angegeben. Das Zertifikat muss ein Clientauthentifizierungszertifikat sein, das von einer vom Server vertrauenswürdigen Zertifizierungsstelle ausgestellt wurde. Rufen Sie zum Abrufen einer Liste der vom Server vertrauenswürdigen CAs die QueryContextAttributes (CredSSP) -Funktion mit dem attribut SECPKG_ATTR_ISSUER_LIST_EX auf.

Nachdem sie ein Authentifizierungszertifikat von einer Zertifizierungsstelle erhalten haben, der der Server vertraut, erstellt die Clientanwendung eine neue Anmeldeinformationen. Dazu rufen Sie die Funktion AcquireCredentialsHandle (CredSSP) auf und rufen dann erneut InitializeSecurityContext (CredSSP) auf und geben die neuen Anmeldeinformationen im PhCredential-Parameter an.

Anforderungen

Siehe auch

SSPI-Funktionen

AcceptSecurityContext (CredSSP)

AcquireCredentialsHandle (CredSSP)

CompleteAuthToken

DeleteSecurityContext

FreeContextBuffer

SecBuffer

SecBufferDesc