SaslInitializeSecurityContextW, fonction (sspi.h)

Article
11/20/2024

La fonction SaslInitializeSecurityContext encapsule un appel standard à l’interface du fournisseur de support de sécurité Fonction InitializeSecurityContext (Général) et traite les cookies du serveur SASL à partir du serveur.

Syntaxe

SECURITY_STATUS SEC_ENTRY SaslInitializeSecurityContextW(
  [in]            PCredHandle    phCredential,
  [in]            PCtxtHandle    phContext,
  [in]            LPWSTR         pszTargetName,
  [in]            unsigned long  fContextReq,
  [in]            unsigned long  Reserved1,
  [in]            unsigned long  TargetDataRep,
  [in]            PSecBufferDesc pInput,
  [in]            unsigned long  Reserved2,
  [out]           PCtxtHandle    phNewContext,
  [in, out]       PSecBufferDesc pOutput,
  [out]           unsigned long  *pfContextAttr,
  [out, optional] PTimeStamp     ptsExpiry
);

Paramètres

[in] phCredential

Handle pour les informations d’identification retournées par le
fonction AcquireCredentialsHandle utilisée pour générer le contexte de sécurité . L’utilisation de la fonction SaslInitializeSecurityContext nécessite au moins des informations d’identification SORTANTes.

[in] phContext

Pointeur vers une structure CtxtHandle. Lors du premier appel à la fonction SaslInitializeSecurityContext, ce pointeur est NULL. Sur le deuxième appel, ce paramètre est un pointeur vers le handle vers le contexte partiellement formé retourné dans le paramètre phNewContext par le premier appel.

[in] pszTargetName

Pointeur vers une chaîne Unicode ou ANSI qui indique la cible du contexte.

[in] fContextReq

Indicateurs de bits qui indiquent les exigences du contexte. Les indicateurs utilisés pour ce paramètre sont préfixés par ISC_REQ_ ; par exemple : ISC_REQ_DELEGATE. Spécifiez les combinaisons des indicateurs d’attributs suivants.

Valeur	Signification
ISC_REQ_REPLAY_DETECT	Détecter les paquets relectés.
ISC_REQ_SEQUENCE_DETECT	Détecter les messages reçus hors séquence.
ISC_REQ_CONFIDENTIALITY	Chiffrer les messages.
ISC_REQ_STREAM	Prendre en charge une connexion orientée flux.
ISC_REQ_EXTENDED_ERROR	Lorsque des erreurs se produisent, la partie distante est avertie.
ISC_REQ_CONNECTION	Le contexte de sécurité ne gère pas les messages de mise en forme.
ISC_REQ_MUTUAL_AUTH	Le client et le serveur sont authentifiés.
ISC_REQ_INTEGRITY	Signer des messages et vérifier les signatures.

Pour plus d’informations sur les différents attributs, consultez Conditions requises pour le contexte.

[in] Reserved1

Valeur réservée ; doit être égal à zéro.

[in] TargetDataRep

Indique la représentation des données, telle que l’ordre d’octets, sur la cible. Peut être SECURITY_NATIVE_DREP ou SECURITY_NETWORK_DREP.

[in] pInput

Pointeur vers une structure SecBufferDesc qui contient des pointeurs vers les mémoires tampons fournies comme entrée du package. Le pointeur doit être NULL lors du premier appel à la fonction. Lors des appels suivants à la fonction, il s’agit d’un pointeur vers une mémoire tampon allouée avec suffisamment de mémoire pour contenir le jeton retourné par l’homologue distant.

SASL nécessite une mémoire tampon unique de type SECBUFFER_TOKEN qui contient le défi reçu du serveur.

[in] Reserved2

Valeur réservée ; doit être égal à zéro.

[out] phNewContext

Pointeur vers une structure CtxtHandle. Lors du premier appel à la fonction SaslInitializeSecurityContext, ce pointeur reçoit le nouveau handle de contexte. Lors du deuxième appel, phNewContext peut être identique au handle spécifié dans le paramètre phContext.

[in, out] pOutput

Pointeur vers une structure SecBufferDes c qui contient des pointeurs vers la structure SecBuffer qui reçoit les données de sortie. Si une mémoire tampon a été tapée en tant que SEC_READWRITE dans l’entrée, elle y sera en sortie. Le système alloue une mémoire tampon pour le jeton de sécurité si demandé (via ISC_REQ_ALLOCATE_MEMORY) et renseigne l’adresse dans le descripteur de mémoire tampon pour le jeton de sécurité.

[out] pfContextAttr

Pointeur vers une variable pour recevoir un ensemble d’indicateurs de bits qui indiquent les attributs du contexte de établi. Pour obtenir une description des différents attributs, consultez Conditions requises pour le contexte.

Les indicateurs utilisés pour ce paramètre sont préfixés par ISC_RET_, tels que ISC_RET_DELEGATE.

Pour obtenir la liste des valeurs valides, consultez le paramètre fContextReq.

Ne vérifiez pas les attributs liés à la sécurité tant que l’appel de fonction final ne retourne pas correctement. Les indicateurs d’attributs non liés à la sécurité, tels que l’indicateur de ASC_RET_ALLOCATED_MEMORY, peuvent être vérifiés avant le retour final.

Remarque attributs de contexte particuliers peuvent changer lors d’une négociation avec un homologue distant.

[out, optional] ptsExpiry

Pointeur vers une structure TimeStamp qui reçoit l’heure d’expiration du contexte. Il est recommandé que le package de sécurité retourne toujours cette valeur dans l’heure locale. Ce paramètre est facultatif et NULL doit être passé pour les clients de courte durée.

Valeur de retour

Si l’appel est terminé, cette fonction retourne SEC_E_OK. Le tableau suivant présente certaines valeurs de retour d’échec possibles.

Retourner le code	Description
SEC_E_ALGORITHM_MISMATCH	Le traitement de l’authentification n’est pas autorisé.
SEC_E_INSUFFICIENT_MEMORY	La mémoire insuffisante est disponible pour terminer la requête.
SEC_E_INVALID_TOKEN	Aucune mémoire tampon de jeton n’est située dans le paramètre pOutput , ou le message n’a pas pu être déchiffré.

Remarques

Note

L’en-tête sspi.h définit SaslInitializeSecurityContext en tant qu’alias qui sélectionne automatiquement la version ANSI ou Unicode de cette fonction en fonction de la définition de la constante de préprocesseur UNICODE. Le mélange de l’utilisation de l’alias neutre en encodage avec du code qui n’est pas neutre en encodage peut entraîner des incompatibilités qui entraînent des erreurs de compilation ou d’exécution. Pour plus d’informations, consultez Conventions pour les prototypes de fonction.

Exigences

Exigence	Valeur
client minimum pris en charge	Aucun pris en charge
serveur minimum pris en charge	Windows Server 2003 [applications de bureau uniquement]
plateforme cible	Windows
d’en-tête	sspi.h (include Security.h)
bibliothèque	Secur32.lib
DLL	Secur32.dll

Partager via