CoInitializeSecurity, fonction (combaseapi.h)
Inscrit la sécurité et définit les valeurs de sécurité par défaut pour le processus.
Syntaxe
HRESULT CoInitializeSecurity(
[in, optional] PSECURITY_DESCRIPTOR pSecDesc,
[in] LONG cAuthSvc,
[in, optional] SOLE_AUTHENTICATION_SERVICE *asAuthSvc,
[in, optional] void *pReserved1,
[in] DWORD dwAuthnLevel,
[in] DWORD dwImpLevel,
[in, optional] void *pAuthList,
[in] DWORD dwCapabilities,
[in, optional] void *pReserved3
);
Paramètres
[in, optional] pSecDesc
Autorisations d’accès qu’un serveur utilisera pour recevoir des appels. Ce paramètre est utilisé par COM uniquement lorsqu’un serveur appelle CoInitializeSecurity. Sa valeur est un pointeur vers l’un des trois types : un AppID, un objet IAccessControl ou un SECURITY_DESCRIPTOR, au format absolu. Pour plus d'informations, consultez la section Notes.
[in] cAuthSvc
Nombre d’entrées dans le paramètre asAuthSvc . Ce paramètre est utilisé par COM uniquement lorsqu’un serveur appelle CoInitializeSecurity. Si ce paramètre est 0, aucun service d’authentification n’est inscrit et le serveur ne peut pas recevoir d’appels sécurisés. La valeur -1 indique à COM de choisir les services d’authentification à inscrire, et si c’est le cas, le paramètre asAuthSvc doit avoir la valeur NULL. Toutefois, Schannel ne sera jamais choisi comme service d’authentification par le serveur si ce paramètre est -1.
[in, optional] asAuthSvc
Tableau de services d’authentification qu’un serveur est prêt à utiliser pour recevoir un appel. Ce paramètre est utilisé par COM uniquement lorsqu’un serveur appelle CoInitializeSecurity. Pour plus d’informations, consultez SOLE_AUTHENTICATION_SERVICE.
[in, optional] pReserved1
Ce paramètre est réservé et doit avoir la valeur NULL.
[in] dwAuthnLevel
Niveau d’authentification par défaut pour le processus. Les serveurs et les clients utilisent ce paramètre lorsqu’ils appellent CoInitializeSecurity. COM échouera les appels qui arrivent avec un niveau d’authentification inférieur. Par défaut, tous les proxys utilisent au moins ce niveau d’authentification. Cette valeur doit contenir l’une des constantes de niveau d’authentification. Par défaut, tous les appels à IUnknown sont effectués à ce niveau.
[in] dwImpLevel
Niveau d’emprunt d’identité par défaut pour les proxys. La valeur de ce paramètre est utilisée uniquement lorsque le processus est un client. Il doit s’agir d’une valeur provenant des constantes de niveau d’emprunt d’identité, à l’exception de RPC_C_IMP_LEVEL_DEFAULT, qui n’est pas à utiliser avec CoInitializeSecurity.
Les appels sortants du client utilisent toujours le niveau d’emprunt d’identité spécifié. (Il n’est pas négocié.) Les appels entrants vers le client peuvent être à n’importe quel niveau d’emprunt d’identité. Par défaut, tous les appels IUnknown sont effectués avec ce niveau d’emprunt d’identité. Par conséquent, même les applications prenant en charge la sécurité doivent définir ce niveau avec soin. Pour déterminer les niveaux d’emprunt d’identité pris en charge par chaque service d’authentification, consultez la description des services d’authentification dans com et packages de sécurité. Pour plus d’informations sur les niveaux d’emprunt d’identité, consultez Emprunt d’identité.
[in, optional] pAuthList
Pointeur vers SOLE_AUTHENTICATION_LIST, qui est un tableau de structures SOLE_AUTHENTICATION_INFO . Cette liste indique les informations pour chaque service d’authentification qu’un client peut utiliser pour appeler un serveur. Ce paramètre est utilisé par COM uniquement lorsqu’un client appelle CoInitializeSecurity.
[in] dwCapabilities
Fonctionnalités supplémentaires du client ou du serveur, spécifiées en définissant une ou plusieurs valeurs EOLE_AUTHENTICATION_CAPABILITIES . Certaines de ces valeurs ne peuvent pas être utilisées simultanément, et d’autres ne peuvent pas être définies lorsque des services d’authentification particuliers sont utilisés. Pour plus d’informations sur ces indicateurs, consultez la section Remarques.
[in, optional] pReserved3
Ce paramètre est réservé et doit avoir la valeur NULL.
Valeur retournée
Cette fonction peut retourner la valeur de retour standard E_INVALIDARG, ainsi que les valeurs suivantes.
| Code de retour | Description |
|---|---|
|
Indique la réussite de l’opération. |
|
CoInitializeSecurity a déjà été appelé. |
|
Le paramètre asAuthSvc n’était pas NULL et aucun des services d’authentification de la liste n’a pu être inscrit. Vérifiez les résultats enregistrés dans asAuthSvc pour les codes d’erreur spécifiques au service d’authentification. |
|
Mémoire insuffisante. |
Remarques
La fonction CoInitializeSecurity initialise la couche de sécurité et définit les valeurs spécifiées comme valeur de sécurité par défaut. Si un processus n’appelle pas CoInitializeSecurity, COM l’appelle automatiquement la première fois qu’une interface est marshalée ou non délimitée, ce qui inscrit la sécurité par défaut du système. Aucun package de sécurité par défaut n’est inscrit jusqu’alors.
Cette fonction est appelée exactement une fois par processus, explicitement ou implicitement. Il peut être appelé par le client, le serveur ou les deux. Pour les applications héritées et d’autres applications qui n’appellent pas explicitement CoInitializeSecurity, COM appelle cette fonction implicitement avec des valeurs du Registre. Si vous définissez la sécurité à l’échelle du processus à l’aide du registre, puis que vous appelez CoInitializeSecurity, les valeurs de Registre AppID sont ignorées et les valeurs CoInitializeSecurity sont utilisées.
CoInitializeSecurity peut être utilisé pour remplacer les autorisations d’accès à l’échelle de l’ordinateur et les autorisations d’accès spécifiques à l’application, mais pas pour remplacer la stratégie de restriction à l’échelle de l’ordinateur.
Si pSecDesc pointe vers un AppID, l’indicateur EOAC_APPID doit être défini dans dwCapabilities et, lorsque l’indicateur EOAC_APPID est défini, tous les autres paramètres sur CoInitializeSecurity sont ignorés. CoInitializeSecurity recherche le niveau d’authentification sous la clé AppID dans le Registre et l’utilise pour déterminer la sécurité par défaut. Pour plus d’informations sur la façon dont la clé AppID est utilisée pour définir la sécurité, consultez Définition Process-Wide sécurité par le biais du Registre.
Si pSecDesc est un pointeur vers un objet IAccessControl , l’indicateur EOAC_ACCESS_CONTROL doit être défini et dwAuthnLevel ne peut pas être aucun. L’objet IAccessControl est utilisé pour déterminer qui peut appeler le processus. DCOM ajoutel’IAccessControl et le libère lorsque CoUninitialize est appelé. L’état de l’objet IAccessControl ne doit pas être modifié.
Si pSecDesc est un pointeur vers un SECURITY_DESCRIPTOR, ni l’indicateur EOAC_APPID ni l’indicateur EOAC_ACCESS_CONTROL ne peuvent être définis dans dwCapabilities. Le propriétaire et le groupe du SECURITY_DESCRIPTOR doivent être définis, et jusqu’à ce que DCOM prenne en charge l’audit, l’ACL système doit être NULL. Les entrées de contrôle d’accès dans l’ACL discrétionnaire (DACL) du SECURITY_DESCRIPTOR sont utilisées pour déterminer quels appelants sont autorisés à se connecter aux objets du processus. Un DACL sans AIC n’autorise aucun accès, tandis qu’un DACL NULL autorise les appels de n’importe qui. Pour plus d’informations sur les listes de contrôle d’accès et les ACL, consultez modèle Access Control. Les applications doivent appeler AccessCheck (et non IsValidSecurityDescriptor) pour s’assurer que leur SECURITY_DESCRIPTOR est correctement formé avant d’appeler CoInitializeSecurity.
Il est fortement déconseillé de passer pSecDesc comme NULL . Une alternative appropriée peut être d’utiliser un SECURITY_DESCRIPTOR qui autorise Tout le monde. Si pSecDesc a la valeur NULL, les indicateurs dans dwCapabilities déterminent comment CoInitializeSecurity définit les autorisations d’accès qu’un serveur utilisera, comme suit :
- Si l’indicateur EOAC_APPID est défini, CoInitializeSecurity recherche le nom .exe de l’application dans le Registre et utilise l’AppID qui y est stocké.
- Si l’indicateur EOAC_ACCESS_CONTROL est défini, CoInitializeSecurity retourne une erreur.
- Si ni l’indicateur EOAC_APPID ni l’indicateur EOAC_ACCESS_CONTROL n’est défini, CoInitializeSecurity autorise tous les appelants, y compris les utilisateurs anonymes locaux et distants.
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 | combaseapi.h (inclure Objbase.h) |
| Bibliothèque | Ole32.lib |
| DLL | Ole32.dll |