Méthode IClientSecurity ::SetBlanket (objidl.h)

  • Article

Définit les informations d’authentification (couverture de sécurité) qui seront utilisées pour effectuer des appels sur le proxy spécifié.

Ce paramètre remplace les paramètres par défaut de processus pour le proxy spécifié. L’appel de cette méthode modifie les valeurs de sécurité de tous les autres utilisateurs du proxy spécifié.

Syntaxe

HRESULT SetBlanket(
  [in] IUnknown *pProxy,
  [in] DWORD    dwAuthnSvc,
  [in] DWORD    dwAuthzSvc,
  [in] OLECHAR  *pServerPrincName,
  [in] DWORD    dwAuthnLevel,
  [in] DWORD    dwImpLevel,
  [in] void     *pAuthInfo,
  [in] DWORD    dwCapabilities
);

Paramètres

[in] pProxy

Pointeur vers le proxy.

[in] dwAuthnSvc

Service d’authentification. Il s’agit d’une valeur unique extraite de la liste des constantes de service d’authentification. Si aucune authentification n’est requise, utilisez RPC_C_AUTHN_NONE. Si RPC_C_AUTHN_DEFAULT est spécifié, COM sélectionne un service d’authentification en suivant son algorithme de négociation de couverture de sécurité normal.

[in] dwAuthzSvc

Service d’autorisation. Il s’agit d’une valeur unique extraite de la liste des constantes d’autorisation. Si RPC_C_AUTHZ_DEFAULT est spécifié, COM sélectionne un service d’autorisation en suivant son algorithme de négociation de couverture de sécurité normal. Si NTLMSSP, Kerberos ou Schannel est utilisé comme service d’authentification, RPC_C_AUTHZ_NONE doit être utilisé comme service d’autorisation.

[in] pServerPrincName

Nom du principal du serveur. Si COLE_DEFAULT_PRINCIPAL est spécifié, DCOM choisit un nom principal à l’aide de son algorithme de négociation de couverture de sécurité. Si Kerberos est utilisé comme service d’authentification, ce paramètre doit être le nom de principal correct du serveur, sinon l’appel échoue.

Si Schannel est utilisé comme service d’authentification, cette valeur doit être l’un des formulaires msstd ou fullsic décrits dans Noms de principaux, ou NULL si vous ne souhaitez pas l’authentification mutuelle.

En règle générale, la spécification de NULL ne réinitialise pas le nom du principal du serveur sur le proxy, mais le paramètre précédent est conservé. Vous devez faire preuve de prudence lorsque vous utilisez NULL comme pServerPrincName lors de la sélection d’un autre service d’authentification pour le proxy, car il n’existe aucune garantie que le nom de principal précédemment défini soit valide pour le service d’authentification nouvellement sélectionné.

[in] dwAuthnLevel

Niveau d’authentification. Il s’agit d’une valeur unique extraite de la liste des constantes de niveau d’authentification. Si RPC_C_AUTHN_LEVEL_DEFAULT est spécifié, COM choisit un niveau d’authentification en suivant son algorithme de négociation de couverture de sécurité normal. Si cette valeur est définie sur RPC_C_AUTHN_LEVEL_NONE, le service d’authentification doit être RPC_C_AUTHN_NONE. Chaque service d’authentification peut choisir d’utiliser un niveau d’authentification de sécurité supérieur à celui spécifié.

[in] dwImpLevel

Niveau d’emprunt d’identité. Il s’agit d’une valeur unique extraite de la liste des constantes de niveau d’emprunt d’identité. Si RPC_C_IMP_LEVEL_DEFAULT est spécifié, COM choisit un niveau d’emprunt d’identité en suivant son algorithme de négociation de couverture de sécurité normal. Si vous utilisez NTLMSSP à distance, cette valeur doit être RPC_C_IMP_LEVEL_IMPERSONATE ou RPC_C_IMP_LEVEL_IDENTIFY. Lorsque vous utilisez NTLMSSP sur le même ordinateur, RPC_C_IMP_LEVEL_DELEGATE est également pris en charge. Pour Kerberos, cette valeur peut être RPC_C_IMP_LEVEL_IDENTIFY, RPC_C_IMP_LEVEL_IMPERSONATE ou RPC_C_IMP_LEVEL_DELEGATE. Pour Schannel, cette valeur doit être RPC_C_IMP_LEVEL_IMPERSONATE.

[in] pAuthInfo

Valeur RPC_AUTH_IDENTITY_HANDLE qui indique l’identité du client. Ce paramètre n’est pas utilisé pour les appels sur le même ordinateur. Si pAuthInfo a la valeur NULL, COM utilise l’identité de proxy actuelle, qui est le jeton de processus, le jeton d’emprunt d’identité ou l’identité d’authentification de la fonction CoInitializeSecurity . Si le handle n’est pas NULL, cette identité est utilisée. Le format de la structure référencée par le handle dépend du fournisseur du service d’authentification.

Pour NTLMSSP ou Kerberos, la structure est une structure SEC_WINNT_AUTH_IDENTITY ou SEC_WINNT_AUTH_IDENTITY_EX . Si le client obtient les informations d’identification définies sur le proxy en appelant CoQueryProxyBlanket, il doit s’assurer que la mémoire reste valide et inchangée jusqu’à ce qu’une identité différente soit définie sur le proxy ou que tous les proxys sur l’objet soient libérés.

Si ce paramètre a la valeur NULL, COM utilise l’identité proxy actuelle (qui est le jeton de processus ou le jeton d’emprunt d’identité). Si le handle fait référence à une structure, cette identité est utilisée.

Pour Schannel, ce paramètre doit être un pointeur vers une structure CERT_CONTEXT qui contient le certificat X.509 du client, ou NULL si le client souhaite établir une connexion anonyme au serveur. Si un certificat est spécifié, l’appelant ne doit pas le libérer tant qu’un proxy vers l’objet existe dans l’appartement actuel.

Pour Snego, ce membre est NULL, pointe vers une structure SEC_WINNT_AUTH_IDENTITY ou pointe vers une structure SEC_WINNT_AUTH_IDENTITY_EX . S’il est NULL, Snego sélectionne une liste de services d’authentification en fonction de ceux disponibles sur l’ordinateur client. S’il pointe vers une structure SEC_WINNT_AUTH_IDENTITY_EX , le membre PackageList de la structure doit pointer vers une chaîne contenant une liste séparée par des virgules de noms de service d’authentification et le membre PackageListLength doit indiquer le nombre d’octets dans la chaîne PackageList . Si PackageList a la valeur NULL, tous les appels utilisant Snego échouent.

Si COLE_DEFAULT_AUTHINFO est spécifié, COM sélectionne les informations d’authentification en suivant son algorithme de négociation de couverture de sécurité normal.

SetBlanket retourne une erreur si pAuthInfo est défini et si l’un des indicateurs de masculation est défini dans dwCapabilities.

[in] dwCapabilities

Fonctionnalités de ce proxy. Les indicateurs de capacité sont définis dans l’énumération EOLE_AUTHENTICATION_CAPABILITIES . Les seuls indicateurs qui peuvent être définis via cette méthode sont EOAC_MUTUAL_AUTH, EOAC_STATIC_CLOAKING, EOAC_DYNAMIC_CLOAKING, EOAC_ANY_AUTHORITY (cet indicateur est déconseillé), EOAC_MAKE_FULLSIC et EOAC_DEFAULT. Vous pouvez définir EOAC_STATIC_CLOAKING ou EOAC_DYNAMIC_CLOAKING si pAuthInfo n’est pas défini et Schannel n’est pas le service d’authentification. (Pour plus d’informations, voir Cloaking .) Si des indicateurs de fonctionnalité autres que ceux mentionnés ici sont indiqués, SetBlanket renvoie une erreur.

Valeur retournée

Cette méthode peut retourner les valeurs suivantes.

Code de retour Description
S_OK
 La commande s'est correctement terminée.
E_INVALIDARG
 Un ou plusieurs arguments ne sont pas valides.

Remarques

SetBlanket définit les informations d’authentification qui seront utilisées pour effectuer des appels sur le proxy d’interface spécifié. Les valeurs spécifiées ici remplacent les valeurs choisies par la sécurité automatique. L’appel de cette méthode modifie les valeurs de sécurité de tous les autres utilisateurs du proxy spécifié. Si vous souhaitez que les modifications s’appliquent uniquement à un instance particulier d’un proxy, appelez IClientSecurity ::CopyProxy pour effectuer une copie privée du proxy, puis appelez SetBlanket sur la copie.

Chaque fois que cette méthode est appelée, DCOM définit l’identité sur le proxy, et les appels futurs effectués à l’aide de ce proxy utilisent cette identité. Les appels en cours lorsque SetBlanket est appelé utilisent les informations d’authentification sur le proxy au moment du démarrage de l’appel. Si pAuthInfo a la valeur NULL, l’identité de proxy utilise par défaut le jeton de processus actuel (sauf si une identité d’authentification a été spécifiée lors d’un appel à CoInitializeSecurity). Pour savoir comment les indicateurs de mastruage affectent le proxy lorsque pAuthInfo a la valeur NULL, consultez Masques.

Par défaut, COM choisit le premier service d’authentification et le service d’autorisation disponibles sur les ordinateurs client et serveur, ainsi que le nom principal inscrit par le serveur pour ce service d’authentification. Actuellement, COM n’essaie pas d’autre service d’authentification en cas d’échec du premier.

Lorsque la constante par défaut pour dwImpLevel est spécifiée dans SetBlanket, le paramètre est défini par défaut sur la valeur spécifiée sur CoInitializeSecurity. Si CoInitializeSecurity n’est pas appelé, la valeur par défaut est RPC_C_IMP_LEVEL_IDENTIFY.

La valeur initiale de dwAuthnLevel sur un proxy est la plus élevée de la valeur définie sur l’appel du client à CoInitializeSecurity et l’appel du serveur à CoInitializeSecurity. Pour tout processus qui n’a pas appelé CoInitializeSecurity, le niveau d’authentification par défaut est RPC_C_AUTHN_CONNECT.

Le niveau d’authentification et d’emprunt d’identité par défaut pour les processus qui n’appellent pas CoInitializeSecurity peut être défini avec DCOMCNFG.

Si EOAC_DEFAULT est spécifié pour dwCapabilities, les fonctionnalités valides de CoInitializeSecurity sont utilisées. Si CoInitializeSecurity n’a pas été appelé, EOAC_NONE sera utilisé pour l’indicateur de fonctionnalités.

Si SetBlanket est appelé simultanément sur deux threads sur le même proxy, un seul ensemble de modifications est appliqué. Si SetBlanket et CRpcOptions ::Set sont appelés simultanément sur deux threads sur le même proxy, les deux modifications peuvent être appliquées ou une seule peut être appliquée.

Les informations de sécurité ne peuvent pas être définies sur des interfaces locales telles que l’interface IClientSecurity . Toutefois, étant donné que cette interface est uniquement prise en charge localement, la sécurité n’est pas nécessaire. IUnknown et IMultiQI sont des cas particuliers. L’implémentation de l’emplacement effectue des appels distants pour prendre en charge ces interfaces. SetBlanket peut être utilisé pour IUnknown. IMultiQI utilisera les paramètres de sécurité sur IUnknown.

Pour modifier un paramètre SetBlanket sans avoir à traiter les autres paramètres, vous pouvez spécifier les constantes par défaut pour les autres paramètres. Les applications peuvent modifier un paramètre (tel que le niveau d’authentification) et ignorer les autres paramètres, y compris le service d’authentification, en définissant tous les autres paramètres sur les constantes par défaut.

Notez qu’il est important de définir tous les paramètres inutilisés sur les constantes par défaut, car la valeur par défaut n’est souvent pas évidente. En particulier, si vous définissez le service d’authentification sur la valeur par défaut, vous devez définir les informations d’authentification et le nom du principal sur la valeur par défaut. La raison en est double : tout d’abord, le type des informations d’authentification dépend du service d’authentification choisi par DCOM. Deuxièmement, étant donné que DCOM doit transmettre des informations d’authentification complexes pour certains services d’authentification, si vous définissez le service d’authentification sur par défaut et les informations d’authentification sur NULL, vous pouvez obtenir un paramètre de sécurité qui ne fonctionnera pas.

Configuration requise

Condition requise Valeur
Client minimal pris en charge Windows 2000 Professionnel [applications de bureau | Applications UWP]
Serveur minimal pris en charge Windows 2000 Server [applications de bureau | Applications UWP]
Plateforme cible Windows
En-tête objidl.h (inclure ObjIdl.h)

Voir aussi

CoQueryProxyBlanket

CoSetProxyBlanket

IClientSecurity