Freigeben über

AcceptSecurityContext (Digest)-Funktion

  • Artikel

Mit der AcceptSecurityContext (Digest)-Funktion kann die Serverkomponente einer Transportanwendung einen Sicherheitskontext zwischen dem Server und einem Remoteclient herstellen. Der Remoteclient verwendet die Funktion InitializeSecurityContext (Digest), um den Prozess der Herstellung eines Sicherheitskontexts zu starten. Der Server kann ein oder mehrere Antworttoken vom Remoteclient benötigen, um den Sicherheitskontext abzuschließen.

Syntax

SECURITY_STATUS SEC_Entry AcceptSecurityContext(
  _In_opt_    PCredHandle    phCredential,
  _Inout_opt_ PCtxtHandle    phContext,
  _In_opt_    PSecBufferDesc pInput,
  _In_        ULONG          fContextReq,
  _In_        ULONG          TargetDataRep,
  _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 des Servers. Der Server ruft die AcquireCredentialsHandle (Digest)-Funktion auf, wobei entweder die SECPKG_CRED_INBOUND- oder SECPKG_CRED_BOTH-Flag zum Abrufen dieses Handles festgelegt ist.

phContext [in, out, optional]

Ein Zeiger auf eine CtxtHandle-Struktur. Beim ersten Aufruf von AcceptSecurityContext (Digest) ist dieser Zeiger NULL. Bei nachfolgenden Aufrufen ist phContext der Handle für den teilweise gebildeten Kontext, der im phNewContext-Parameter vom ersten Aufruf zurückgegeben wurde.

Warnung

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

pInput [in, optional]

Ein Zeiger auf eine SecBufferDesc-Struktur, die von einem Clientaufruf an InitializeSecurityContext (Digest) mit einem Eingabepufferdeskriptor generiert wird.

Die folgende Tabelle zeigt die Pufferkonfiguration für Digest-HTTP. Der erste Puffer muss vom Typ SECBUFFER_TOKEN sein, während der Rest vom Typ SECBUFFER_PKG_PARAMS sein muss. SASL erfordert nur Puffer 0.

Puffer #/Puffertyp Bedeutung
0
SECBUFFER_TOKEN		 Leer für den ersten Aufruf und die vom Client empfangene Antwort auf die Herausforderung für den zweiten Aufruf.
1
SECBUFFER_PKG_PARAMS		 Method. Die Zeichen sind im Textformat der Anfragezeile. US ASCII-Einzelbytezeichen.
2
SECBUFFER_PKG_PARAMS		 Reserviert.
3
SECBUFFER_PKG_PARAMS		 HEntity. Hexadezimale Darstellung von H(entity-body). US ASCII-Einzelbytezeichen.
4
SECBUFFER_PKG_PARAMS		 Realm (Bereich) Bereichszeichenfolge für die Herausforderung. Unicode-Zeichenfolge, die in US ASCII dargestellt werden muss.
5
SECBUFFER_CHANNEL_BINDINGS | SECBUFFER_READONLY		 Enthält den Wert des Kanalbindungstokens.
Windows Server 2008, Windows Vista, Windows Server 2003 und Windows XP: Dieser Wert wird nicht unterstützt.

fContextReq [in]

Bitflags, die die vom Server zum Einrichten des Kontexts erforderlichen Attribute angeben. Bitflags können mithilfe von bitwise-OR-Vorgängen kombiniert werden. Dieser Parameter kann einen der folgenden Werte annehmen.

Wert Bedeutung
ASC_REQ_ALLOCATE_MEMORY Digest weist Ausgabepuffer für Sie zu. Wenn Sie die Verwendung der Ausgabepuffer abgeschlossen haben, geben Sie sie frei, indem Sie die FreeContextBuffer-Funktion aufrufen.
ASC_REQ_ALLOW_MISSING_BINDINGS Gibt an, dass Digest keine Kanalbindungen für interne und externe Kanäle erfordert. Dieser Wert wird für die Abwärtskompatibilität verwendet, wenn die Unterstützung für die Endpunkt-Kanalbindung nicht bekannt ist.
Dieser Wert schließt sich gegenseitig mit ASC_REQ_PROXY_BINDINGS aus.
Windows Server 2008, Windows Vista, Windows Server 2003 und Windows XP: Dieser Wert wird nicht unterstützt.
ASC_REQ_CONFIDENTIALITY Verschlüsseln und Entschlüsseln von Nachrichten.
Der Digest-SSP unterstützt dieses Flag nur für SASL.
ASC_REQ_PROXY_BINDINGS Gibt an, dass Digest eine Kanalbindung erfordert.
Dieser Wert schließt sich gegenseitig mit ASC_REQ_ALLOW_MISSING_BINDINGS aus.
Windows Server 2008, Windows Vista, Windows Server 2003 und Windows XP: Dieser Wert wird nicht unterstützt.
ASC_REQ_CONNECTION Der Sicherheitskontext behandelt keine Formatierungsmeldungen.
ASC_REQ_EXTENDED_ERROR Wenn Fehler auftreten, wird die Remotepartei benachrichtigt.
ASC_REQ_HTTP (0x10000000) Verwenden Sie Digest für HTTP. Lassen Sie dieses Flag weg, um Digest als SASL-Mechanismus zu verwenden.
ASC_REQ_INTEGRITY Signieren der Nachrichten und Überprüfen der Signaturen.
ASC_REQ_REPLAY_DETECT Erkennen wiedergegebener Pakete.
ASC_REQ_SEQUENCE_DETECT Erkennen von Nachrichten, die außerhalb der Sequenz empfangen wurden.

Mögliche Attributflags und deren Bedeutungen finden Sie unter Kontextanforderungen. Kennzeichen, die für diesen Parameter verwendet werden, wird ASC_REQ vorangestellt, z. B. ASC_REQ_DELEGATE.

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

TargetDataRep [in]

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

Dieser Parameter wird mit Digest SSP nicht verwendet. Wenn Sie Digest-SSP verwenden, geben Sie null für diesen Parameter an.

phNewContext [in, out, optional]

Ein Zeiger auf eine CtxtHandle-Struktur. Beim ersten Aufruf von AcceptSecurityContext (Digest) empfängt dieser Zeiger das neue Kontexthandle. Bei nachfolgenden Aufrufen kann phNewContext mit dem im phContext-Parameter angegebenen Handle identisch sein. phNewContext sollte niemals NULL sein.

pOutput [in, out, optional]

Ein Zeiger auf eine SecBufferDesc-Struktur, die den Ausgabepufferdeskriptor enthält. Dieser Puffer wird an den Client gesendet, um zusätzliche Aufrufe an InitializeSecurityContext (Digest) einzugeben. Ein Ausgabepuffer kann auch dann generiert werden, wenn die Funktion SEC_E_OK zurückgibt. Jeder generierte Puffer muss an die Clientanwendung zurückgesendet werden.

pfContextAttr [out]

Ein Zeiger auf eine Variable, die eine Reihe von Bitflags empfängt, die die Attribute des festgelegten Kontexts anzeigen. Eine Beschreibung der verschiedenen Attribute finden Sie unter Kontextanforderungen. Kennzeichen, die für diesen Parameter verwendet werden, wird ASC_RET vorangestellt, z. B. ASC_RET_DELEGATE.

Überprüfen Sie erst auf sicherheitsbezogene Attribute, wenn der endgültige Funktionsaufruf erfolgreich zurückgegeben wurde. Attributflags, die nichts mit der Sicherheit zu tun haben, wie z. B. das ASC_RET_ALLOCATED_MEMORY-Flag, können vor der endgültigen Rückgabe überprüft werden.

ptsTimeStamp [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 Ortszeit zurückgibt.

Dieser Parameter wird auf eine konstante maximale Zeit festgelegt. Es gibt keine Ablaufzeit für den Sicherheitskontext oder Anmeldeinformationen von Digest oder bei Verwendung des Digest-SSP.

Hinweis

Bis zum letzten Aufruf des Authentifizierungsprozesses kann die Ablaufzeit für den Kontext falsch sein, da in späteren Phasen der Verhandlung weitere Informationen bereitgestellt werden. Daher muss ptsTimeStamp bis zum letzten Aufruf der Funktion NULL sein.

Rückgabewert

Diese Funktion gibt einen der folgenden Werte zurück:

Rückgabecode + Wert Beschreibung
SEC_E_INSUFFICIENT_MEMORY
0x80090300L		 Fehler bei der Funktion. Es steht nicht genügend Arbeitsspeicher zur Verfügung, um die angeforderte Aktion abzuschließen.
SEC_E_INTERNAL_ERROR
0x80090304L		 Fehler bei der Funktion. Ein Fehler ist aufgetreten, der keinem SSPI-Fehlercode zugeordnet wurde.
SEC_E_INVALID_HANDLE
0x80100003L		 Fehler bei der Funktion. Die dieser Funktion übergebene URL ist ungültig.
SEC_E_INVALID_TOKEN
0x80090308L		 Fehler bei der Funktion. Das an die Funktion übergebene Token ist ungültig.
SEC_E_LOGON_DENIED
0x8009030CL		 Fehler bei der Anmeldung.
SEC_E_NO_AUTHENTICATING_AUTHORITY
0x80090311L		 Fehler bei der Funktion. Es konnte keine Autorität für die Authentifizierung kontaktiert werden. Dies könnte auf folgende Bedingungen zurückzuführen sein:
- Der Domänenname der Authentifizierungspartei ist falsch.
- Der Domänencontroller ist nicht verfügbar.
- Die Vertrauensstellung ist fehlgeschlagen.
SEC_E_NO_CREDENTIALS
0x8009030EL		 Fehler bei der Funktion. Das im phCredential-Parameter angegebene Anmeldeinformationshandle ist ungültig.
SEC_E_OK
0x00000000L		 Die Funktion wurde erfolgreich ausgeführt. Der vom Client empfangene Sicherheitskontext wurde akzeptiert. Wenn ein Ausgabetoken von der Funktion generiert wurde, muss es an den Clientprozess gesendet werden.
SEC_E_SECURITY_QOS_FAILED
0x80090332L		 Fehler bei der Funktion. Im Parameter fContextReq wurde ein ungültiges Kontextattribut-Flag angegeben.
SEC_I_COMPLETE_AND_CONTINUE
0x00090314L		 Die Funktion wurde erfolgreich ausgeführt. Der Server muss CompleteAuthToken aufrufen und das Ausgabetoken an den Client übergeben. Der Server wartet auf ein Rückgabetoken vom Client und führt dann einen weiteren Aufruf von AcceptSecurityContext (Digest) durch.
SEC_I_COMPLETE_NEEDED
0x00090313L		 Die Funktion wurde erfolgreich ausgeführt. Der Server muss die Erstellung der Nachricht vom Client abschließen und dann die CompleteAuthToken-Funktion aufrufen.
SEC_I_CONTINUE_NEEDED
0x00090312L		 Die Funktion wurde erfolgreich ausgeführt. Der Server muss das Ausgabetoken an den Client senden und auf ein zurückgegebenes Token warten. Das zurückgegebene Token sollte in pInput für einen anderen Aufruf von AcceptSecurityContext (Digest) übergeben werden.
STATUS_LOGON_FAILURE
0xC000006DL		 Fehler bei der Funktion. Die AcceptSecurityContext (Digest)-Funktion wurde aufgerufen, nachdem der angegebene Kontext eingerichtet wurde.
SEC_E_BAD_BINDINGS
0x80090346L		 Fehler bei der Funktion. Die Kanalbindungsrichtlinie wurde nicht erfüllt.

Hinweise

Die AcceptSecurityContext (Digest)-Funktion ist das Server-Gegenstück zur Funktion InitializeSecurityContext (Digest).

Wenn der Server eine Anforderung von einem Client empfängt, verwendet der Server den fContextReq-Parameter, um anzugeben, was er für die Sitzung benötigt. Auf diese Weise kann ein Server angeben, dass Clients in der Lage sein müssen, eine vertrauliche oder integritätsgeprüfte Sitzung zu verwenden, und er kann Clients ablehnen, die diese Anforderung nicht erfüllen können. Alternativ kann ein Server nichts erfordern, und was der Client bereitstellen kann oder erfordert, wird im Parameter pfContextAttr zurückgegeben.

Für ein Paket, das die mehrstufige Authentifizierung unterstützt, z. B. die gegenseitige Authentifizierung, lautet die Aufrufsequenz wie folgt:

  1. Der Client überträgt ein Token an den Server.
  2. Der Server ruft AcceptSecurityContext (Digest) zum ersten Mal auf, wodurch ein Antworttoken generiert wird, das dann an den Client gesendet wird.
  3. Der Client empfängt das Token und übergibt es an InitializeSecurityContext (Digest). Wenn InitializeSecurityContext (Digest) SEC_E_OK zurückgibt, wurde die gegenseitige Authentifizierung abgeschlossen, und eine sichere Sitzung kann beginnen. Wenn InitializeSecurityContext (Digest) einen Fehlercode zurückgibt, endet die gegenseitige Authentifizierungsverhandlung. Andernfalls wird das von InitializeSecurityContext (Digest) zurückgegebene Sicherheitstoken an den Client gesendet, und die Schritte 2 und 3 werden wiederholt.
  4. Verwenden Sie den phContext-Wert nicht in gleichzeitigen Aufrufen von AcceptSecurityContext (Digest). Die Implementierung in den Sicherheitsanbietern ist nicht threadsicher.

Bei den Parametern fContextReq und pfContextAttr handelt es sich um Bitmasken, die verschiedene Kontextattribute darstellen. Eine Beschreibung der verschiedenen Attribute finden Sie unter Kontextanforderungen.

Hinweis

Der pfContextAttr-Parameter ist bei jeder erfolgreichen Rückgabe gültig, aber nur bei der letzten erfolgreichen Rückgabe sollten Sie die Flags in Bezug auf die Sicherheitsaspekte des Kontexts überprüfen. Zwischenrückzeichen können z. B. die ISC_RET_ALLOCATED_MEMORY-Kennzeichnung festlegen.

Der Aufrufer ist dafür verantwortlich, zu bestimmen, ob die endgültigen Kontextattribute ausreichen. Wenn z. B. Vertraulichkeit (Verschlüsselung) angefordert wurde, aber nicht hergestellt werden konnte, können einige Anwendungen die Verbindung sofort beenden. Wenn der Sicherheitskontext nicht eingerichtet werden kann, muss der Server den teilweise erstellten Kontext freigeben, indem er die DeleteSecurityContext-Funktion aufruft. Informationen zum Aufrufen der DeleteSecurityContext-Funktion finden Sie unter DeleteSecurityContext.

Nachdem der Sicherheitskontext eingerichtet wurde, kann die Serveranwendung die QuerySecurityContextToken-Funktion verwenden, um ein Handle für das Benutzerkonto abzurufen, dem das Clientzertifikat zugeordnet wurde. Außerdem kann der Server die ImpersonateSecurityContext-Funktion verwenden, um die Identität des Benutzers zu imitieren.

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

Weitere Informationen

SSPI-Funktionen

DeleteSecurityContext

InitializeSecurityContext (Digest)