Contents

Security and Identity

Accctrl.h
Overview
ACCESS_MODE enumeration
EXPLICIT_ACCESS_A structure
EXPLICIT_ACCESS_W structure
INHERITED_FROMA structure
INHERITED_FROMW structure
MULTIPLE_TRUSTEE_OPERATION enumeration
OBJECTS_AND_NAME_A structure
OBJECTS_AND_NAME_W structure
OBJECTS_AND_SID structure
PROG_INVOKE_SETTING enumeration
SE_OBJECT_TYPE enumeration
TRUSTEE_A structure
TRUSTEE_FORM enumeration
TRUSTEE_TYPE enumeration
TRUSTEE_W structure
Aclapi.h
Overview
BuildExplicitAccessWithNameA function
BuildExplicitAccessWithNameW function
BuildSecurityDescriptorA function
BuildSecurityDescriptorW function
BuildTrusteeWithNameA function
BuildTrusteeWithNameW function
BuildTrusteeWithObjectsAndNameA function
BuildTrusteeWithObjectsAndNameW function
BuildTrusteeWithObjectsAndSidA function
BuildTrusteeWithObjectsAndSidW function
BuildTrusteeWithSidA function
BuildTrusteeWithSidW function
FreeInheritedFromArray function
GetAuditedPermissionsFromAclA function
GetAuditedPermissionsFromAclW function
GetEffectiveRightsFromAclA function
GetEffectiveRightsFromAclW function
GetExplicitEntriesFromAclA function
GetExplicitEntriesFromAclW function
GetInheritanceSourceA function
GetInheritanceSourceW function
GetNamedSecurityInfoA function
GetNamedSecurityInfoW function
GetSecurityInfo function
GetTrusteeFormA function
GetTrusteeFormW function
GetTrusteeNameA function
GetTrusteeNameW function
GetTrusteeTypeA function
GetTrusteeTypeW function
LookupSecurityDescriptorPartsA function
LookupSecurityDescriptorPartsW function
SetEntriesInAclA function
SetEntriesInAclW function
SetNamedSecurityInfoA function
SetNamedSecurityInfoW function
SetSecurityInfo function
TreeResetNamedSecurityInfoA function
TreeResetNamedSecurityInfoW function
TreeSetNamedSecurityInfoA function
TreeSetNamedSecurityInfoW function
Aclui.h
Overview
CreateSecurityPage function
EditSecurity function
EditSecurityAdvanced function
EFFPERM_RESULT_LIST structure
IEffectivePermission interface
Overview
IEffectivePermission::GetEffectivePermission method
IEffectivePermission2 interface
Overview
IEffectivePermission2::ComputeEffectivePermissionWithSecondarySecurity
method
ISecurityInformation interface
Overview
ISecurityInformation::GetAccessRights method
ISecurityInformation::GetInheritTypes method
ISecurityInformation::GetObjectInformation method
ISecurityInformation::GetSecurity method
ISecurityInformation::MapGeneric method
ISecurityInformation::PropertySheetPageCallback method
ISecurityInformation::SetSecurity method
ISecurityInformation2 interface
Overview
ISecurityInformation2::IsDaclCanonical method
ISecurityInformation2::LookupSids method
ISecurityInformation3 interface
Overview
ISecurityInformation3::GetFullResourceName method
ISecurityInformation3::OpenElevatedEditor method
ISecurityInformation4 interface
Overview
ISecurityInformation4::GetSecondarySecurity method
 ISecurityObjectTypeInfo interface
Overview
ISecurityObjectTypeInfo::GetInheritSource method
SECURITY_OBJECT structure
SI_ACCESS structure
SI_INHERIT_TYPE structure
SI_OBJECT_INFO structure
SI_PAGE_TYPE enumeration
SID_INFO structure
SID_INFO_LIST structure
Adtgen.h
Overview
AUDIT_PARAM_TYPE enumeration
Authz.h
Overview
AUTHZ_ACCESS_REPLY structure
AUTHZ_ACCESS_REQUEST structure
AUTHZ_CONTEXT_INFORMATION_CLASS enumeration
AUTHZ_INIT_INFO structure
AUTHZ_REGISTRATION_OBJECT_TYPE_NAME_OFFSET structure
AUTHZ_RPC_INIT_INFO_CLIENT structure
AUTHZ_SECURITY_ATTRIBUTE_FQBN_VALUE structure
AUTHZ_SECURITY_ATTRIBUTE_OCTET_STRING_VALUE structure
AUTHZ_SECURITY_ATTRIBUTE_OPERATION enumeration
AUTHZ_SECURITY_ATTRIBUTE_V1 structure
AUTHZ_SECURITY_ATTRIBUTES_INFORMATION structure
AUTHZ_SID_OPERATION enumeration
AUTHZ_SOURCE_SCHEMA_REGISTRATION structure
AuthzAccessCheck function
AuthzAddSidsToContext function
AuthzCachedAccessCheck function
AuthzEnumerateSecurityEventSources function
 AuthzFreeAuditEvent function
AuthzFreeCentralAccessPolicyCache function
AuthzFreeContext function
AuthzFreeHandle function
AuthzFreeResourceManager function
AuthzGetInformationFromContext function
AuthzInitializeCompoundContext function
AuthzInitializeContextFromAuthzContext function
AuthzInitializeContextFromSid function
AuthzInitializeContextFromToken function
AuthzInitializeObjectAccessAuditEvent function
AuthzInitializeObjectAccessAuditEvent2 function
AuthzInitializeRemoteResourceManager function
AuthzInitializeResourceManager function
AuthzInitializeResourceManagerEx function
AuthzInstallSecurityEventSource function
AuthzModifyClaims function
AuthzModifySecurityAttributes function
AuthzModifySids function
AuthzOpenObjectAudit function
AuthzRegisterCapChangeNotification function
AuthzRegisterSecurityEventSource function
AuthzReportSecurityEvent function
AuthzReportSecurityEventFromParams function
AuthzSetAppContainerInformation function
AuthzUninstallSecurityEventSource function
AuthzUnregisterCapChangeNotification function
AuthzUnregisterSecurityEventSource function
Azroles.h
Overview
AZ_PROP_CONSTANTS enumeration
IAzApplication interface
Overview
IAzApplication::AddDelegatedPolicyUser method
IAzApplication::AddDelegatedPolicyUserName method
IAzApplication::AddPolicyAdministrator method
IAzApplication::AddPolicyAdministratorName method
IAzApplication::AddPolicyReader method
IAzApplication::AddPolicyReaderName method
IAzApplication::AddPropertyItem method
IAzApplication::CreateApplicationGroup method
IAzApplication::CreateOperation method
IAzApplication::CreateRole method
IAzApplication::CreateScope method
IAzApplication::CreateTask method
IAzApplication::DeleteApplicationGroup method
IAzApplication::DeleteDelegatedPolicyUser method
IAzApplication::DeleteDelegatedPolicyUserName method
IAzApplication::DeleteOperation method
IAzApplication::DeletePolicyAdministrator method
IAzApplication::DeletePolicyAdministratorName method
IAzApplication::DeletePolicyReader method
IAzApplication::DeletePolicyReaderName method
IAzApplication::DeletePropertyItem method
IAzApplication::DeleteRole method
IAzApplication::DeleteScope method
IAzApplication::DeleteTask method
IAzApplication::get_ApplicationData method
IAzApplication::get_ApplicationGroups method
IAzApplication::get_ApplyStoreSacl method
IAzApplication::get_AuthzInterfaceClsid method
IAzApplication::get_DelegatedPolicyUsers method
IAzApplication::get_DelegatedPolicyUsersName method
IAzApplication::get_Description method
 IAzApplication::get_GenerateAudits method
IAzApplication::get_Name method
IAzApplication::get_Operations method
IAzApplication::get_PolicyAdministrators method
IAzApplication::get_PolicyAdministratorsName method
IAzApplication::get_PolicyReaders method
IAzApplication::get_PolicyReadersName method
IAzApplication::get_Roles method
IAzApplication::get_Scopes method
IAzApplication::get_Tasks method
IAzApplication::get_Version method
IAzApplication::get_Writable method
IAzApplication::GetProperty method
IAzApplication::InitializeClientContextFromName method
IAzApplication::InitializeClientContextFromStringSid method
IAzApplication::InitializeClientContextFromToken method
IAzApplication::OpenApplicationGroup method
IAzApplication::OpenOperation method
IAzApplication::OpenRole method
IAzApplication::OpenScope method
IAzApplication::OpenTask method
IAzApplication::put_ApplicationData method
IAzApplication::put_ApplyStoreSacl method
IAzApplication::put_AuthzInterfaceClsid method
IAzApplication::put_Description method
IAzApplication::put_GenerateAudits method
IAzApplication::put_Name method
IAzApplication::put_Version method
IAzApplication::SetProperty method
IAzApplication::Submit method
IAzApplication2 interface
Overview
 IAzApplication2::InitializeClientContext2 method
IAzApplication2::InitializeClientContextFromToken2 method
IAzApplication3 interface
Overview
IAzApplication3::CreateRoleAssignment method
IAzApplication3::CreateRoleDefinition method
IAzApplication3::CreateScope2 method
IAzApplication3::DeleteRoleAssignment method
IAzApplication3::DeleteRoleDefinition method
IAzApplication3::DeleteScope2 method
IAzApplication3::get_BizRulesEnabled method
IAzApplication3::get_RoleAssignments method
IAzApplication3::get_RoleDefinitions method
IAzApplication3::OpenRoleAssignment method
IAzApplication3::OpenRoleDefinition method
IAzApplication3::OpenScope2 method
IAzApplication3::put_BizRulesEnabled method
IAzApplication3::ScopeExists method
IAzApplicationGroup interface
Overview
IAzApplicationGroup::AddAppMember method
IAzApplicationGroup::AddAppNonMember method
IAzApplicationGroup::AddMember method
IAzApplicationGroup::AddMemberName method
IAzApplicationGroup::AddNonMember method
IAzApplicationGroup::AddNonMemberName method
IAzApplicationGroup::AddPropertyItem method
IAzApplicationGroup::DeleteAppMember method
IAzApplicationGroup::DeleteAppNonMember method
IAzApplicationGroup::DeleteMember method
IAzApplicationGroup::DeleteMemberName method
IAzApplicationGroup::DeleteNonMember method
 IAzApplicationGroup::DeleteNonMemberName method
IAzApplicationGroup::DeletePropertyItem method
IAzApplicationGroup::get_AppMembers method
IAzApplicationGroup::get_AppNonMembers method
IAzApplicationGroup::get_Description method
IAzApplicationGroup::get_LdapQuery method
IAzApplicationGroup::get_Members method
IAzApplicationGroup::get_MembersName method
IAzApplicationGroup::get_Name method
IAzApplicationGroup::get_NonMembers method
IAzApplicationGroup::get_NonMembersName method
IAzApplicationGroup::get_Type method
IAzApplicationGroup::get_Writable method
IAzApplicationGroup::GetProperty method
IAzApplicationGroup::put_Description method
IAzApplicationGroup::put_LdapQuery method
IAzApplicationGroup::put_Name method
IAzApplicationGroup::put_Type method
IAzApplicationGroup::SetProperty method
IAzApplicationGroup::Submit method
IAzApplicationGroup2 interface
Overview
IAzApplicationGroup2::get_BizRule method
IAzApplicationGroup2::get_BizRuleImportedPath method
IAzApplicationGroup2::get_BizRuleLanguage method
IAzApplicationGroup2::put_BizRule method
IAzApplicationGroup2::put_BizRuleImportedPath method
IAzApplicationGroup2::put_BizRuleLanguage method
IAzApplicationGroup2::RoleAssignments method
IAzApplicationGroups interface
Overview
IAzApplicationGroups::get__NewEnum method
 IAzApplicationGroups::get_Count method
IAzApplicationGroups::get_Item method
IAzApplications interface
Overview
IAzApplications::get__NewEnum method
IAzApplications::get_Count method
IAzApplications::get_Item method
IAzAuthorizationStore interface
Overview
IAzAuthorizationStore::AddDelegatedPolicyUser method
IAzAuthorizationStore::AddDelegatedPolicyUserName method
IAzAuthorizationStore::AddPolicyAdministrator method
IAzAuthorizationStore::AddPolicyAdministratorName method
IAzAuthorizationStore::AddPolicyReader method
IAzAuthorizationStore::AddPolicyReaderName method
IAzAuthorizationStore::AddPropertyItem method
IAzAuthorizationStore::CloseApplication method
IAzAuthorizationStore::CreateApplication method
IAzAuthorizationStore::CreateApplicationGroup method
IAzAuthorizationStore::Delete method
IAzAuthorizationStore::DeleteApplication method
IAzAuthorizationStore::DeleteApplicationGroup method
IAzAuthorizationStore::DeleteDelegatedPolicyUser method
IAzAuthorizationStore::DeleteDelegatedPolicyUserName method
IAzAuthorizationStore::DeletePolicyAdministrator method
IAzAuthorizationStore::DeletePolicyAdministratorName method
IAzAuthorizationStore::DeletePolicyReader method
IAzAuthorizationStore::DeletePolicyReaderName method
IAzAuthorizationStore::DeletePropertyItem method
IAzAuthorizationStore::get_ApplicationData method
IAzAuthorizationStore::get_ApplicationGroups method
IAzAuthorizationStore::get_Applications method
 IAzAuthorizationStore::get_ApplyStoreSacl method
IAzAuthorizationStore::get_DelegatedPolicyUsers method
IAzAuthorizationStore::get_DelegatedPolicyUsersName method
IAzAuthorizationStore::get_Description method
IAzAuthorizationStore::get_DomainTimeout method
IAzAuthorizationStore::get_GenerateAudits method
IAzAuthorizationStore::get_MaxScriptEngines method
IAzAuthorizationStore::get_PolicyAdministrators method
IAzAuthorizationStore::get_PolicyAdministratorsName method
IAzAuthorizationStore::get_PolicyReaders method
IAzAuthorizationStore::get_PolicyReadersName method
IAzAuthorizationStore::get_ScriptEngineTimeout method
IAzAuthorizationStore::get_TargetMachine method
IAzAuthorizationStore::get_Writable method
IAzAuthorizationStore::GetProperty method
IAzAuthorizationStore::Initialize method
IAzAuthorizationStore::OpenApplication method
IAzAuthorizationStore::OpenApplicationGroup method
IAzAuthorizationStore::put_ApplicationData method
IAzAuthorizationStore::put_ApplyStoreSacl method
IAzAuthorizationStore::put_Description method
IAzAuthorizationStore::put_DomainTimeout method
IAzAuthorizationStore::put_GenerateAudits method
IAzAuthorizationStore::put_MaxScriptEngines method
IAzAuthorizationStore::put_ScriptEngineTimeout method
IAzAuthorizationStore::SetProperty method
IAzAuthorizationStore::Submit method
IAzAuthorizationStore::UpdateCache method
IAzAuthorizationStore2 interface
Overview
IAzAuthorizationStore2::CreateApplication2 method
IAzAuthorizationStore2::OpenApplication2 method
IAzAuthorizationStore3 interface
Overview
IAzAuthorizationStore3::BizruleGroupSupported method
IAzAuthorizationStore3::GetSchemaVersion method
IAzAuthorizationStore3::IsFunctionalLevelUpgradeSupported method
IAzAuthorizationStore3::IsUpdateNeeded method
IAzAuthorizationStore3::UpgradeStoresFunctionalLevel method
IAzBizRuleContext interface
Overview
IAzBizRuleContext::get_BusinessRuleString method
IAzBizRuleContext::GetParameter method
IAzBizRuleContext::put_BusinessRuleResult method
IAzBizRuleContext::put_BusinessRuleString method
IAzBizRuleInterfaces interface
Overview
IAzBizRuleInterfaces::AddInterface method
IAzBizRuleInterfaces::AddInterfaces method
IAzBizRuleInterfaces::get_Count method
IAzBizRuleInterfaces::GetInterfaceValue method
IAzBizRuleInterfaces::Remove method
IAzBizRuleInterfaces::RemoveAll method
IAzBizRuleParameters interface
Overview
IAzBizRuleParameters::AddParameter method
IAzBizRuleParameters::AddParameters method
IAzBizRuleParameters::get_Count method
IAzBizRuleParameters::GetParameterValue method
IAzBizRuleParameters::Remove method
IAzBizRuleParameters::RemoveAll method
IAzClientContext interface
Overview
IAzClientContext::AccessCheck method
 IAzClientContext::get_RoleForAccessCheck method
IAzClientContext::get_UserCanonical method
IAzClientContext::get_UserDisplay method
IAzClientContext::get_UserDn method
IAzClientContext::get_UserDnsSamCompat method
IAzClientContext::get_UserGuid method
IAzClientContext::get_UserSamCompat method
IAzClientContext::get_UserUpn method
IAzClientContext::GetBusinessRuleString method
IAzClientContext::GetProperty method
IAzClientContext::GetRoles method
IAzClientContext::put_RoleForAccessCheck method
IAzClientContext2 interface
Overview
IAzClientContext2::AddApplicationGroups method
IAzClientContext2::AddRoles method
IAzClientContext2::AddStringSids method
IAzClientContext2::get_LDAPQueryDN method
IAzClientContext2::GetAssignedScopesPage method
IAzClientContext2::put_LDAPQueryDN method
IAzClientContext3 interface
Overview
IAzClientContext3::AccessCheck2 method
IAzClientContext3::get_BizRuleInterfaces method
IAzClientContext3::get_BizRuleParameters method
IAzClientContext3::get_Sids method
IAzClientContext3::GetGroups method
IAzClientContext3::GetOperations method
IAzClientContext3::GetTasks method
IAzClientContext3::IsInRoleAssignment method
IAzNameResolver interface
Overview
 IAzNameResolver::NameFromSid method
IAzNameResolver::NamesFromSids method
IAzObjectPicker interface
Overview
IAzObjectPicker::get_Name method
IAzObjectPicker::GetPrincipals method
IAzOperation interface
Overview
IAzOperation::get_ApplicationData method
IAzOperation::get_Description method
IAzOperation::get_Name method
IAzOperation::get_OperationID method
IAzOperation::get_Writable method
IAzOperation::GetProperty method
IAzOperation::put_ApplicationData method
IAzOperation::put_Description method
IAzOperation::put_Name method
IAzOperation::put_OperationID method
IAzOperation::SetProperty method
IAzOperation::Submit method
IAzOperation2 interface
Overview
IAzOperation2::RoleAssignments method
IAzOperations interface
Overview
IAzOperations::get__NewEnum method
IAzOperations::get_Count method
IAzOperations::get_Item method
IAzPrincipalLocator interface
Overview
IAzPrincipalLocator::get_NameResolver method
IAzPrincipalLocator::get_ObjectPicker method
IAzRole interface
Overview
IAzRole::AddAppMember method
IAzRole::AddMember method
IAzRole::AddMemberName method
IAzRole::AddOperation method
IAzRole::AddPropertyItem method
IAzRole::AddTask method
IAzRole::DeleteAppMember method
IAzRole::DeleteMember method
IAzRole::DeleteMemberName method
IAzRole::DeleteOperation method
IAzRole::DeletePropertyItem method
IAzRole::DeleteTask method
IAzRole::get_ApplicationData method
IAzRole::get_AppMembers method
IAzRole::get_Description method
IAzRole::get_Members method
IAzRole::get_MembersName method
IAzRole::get_Name method
IAzRole::get_Operations method
IAzRole::get_Tasks method
IAzRole::get_Writable method
IAzRole::GetProperty method
IAzRole::put_ApplicationData method
IAzRole::put_Description method
IAzRole::put_Name method
IAzRole::SetProperty method
IAzRole::Submit method
IAzRoleAssignment interface
Overview
IAzRoleAssignment::AddRoleDefinition method
 IAzRoleAssignment::DeleteRoleDefinition method
IAzRoleAssignment::get_RoleDefinitions method
IAzRoleAssignment::get_Scope method
IAzRoleAssignments interface
Overview
IAzRoleAssignments::get__NewEnum method
IAzRoleAssignments::get_Count method
IAzRoleAssignments::get_Item method
IAzRoleDefinition interface
Overview
IAzRoleDefinition::AddRoleDefinition method
IAzRoleDefinition::DeleteRoleDefinition method
IAzRoleDefinition::get_RoleDefinitions method
IAzRoleDefinition::RoleAssignments method
IAzRoleDefinitions interface
Overview
IAzRoleDefinitions::get__NewEnum method
IAzRoleDefinitions::get_Count method
IAzRoleDefinitions::get_Item method
IAzRoles interface
Overview
IAzRoles::get__NewEnum method
IAzRoles::get_Count method
IAzRoles::get_Item method
IAzScope interface
Overview
IAzScope::AddPolicyAdministrator method
IAzScope::AddPolicyAdministratorName method
IAzScope::AddPolicyReader method
IAzScope::AddPolicyReaderName method
IAzScope::AddPropertyItem method
IAzScope::CreateApplicationGroup method
IAzScope::CreateRole method
IAzScope::CreateTask method
IAzScope::DeleteApplicationGroup method
IAzScope::DeletePolicyAdministrator method
IAzScope::DeletePolicyAdministratorName method
IAzScope::DeletePolicyReader method
IAzScope::DeletePolicyReaderName method
IAzScope::DeletePropertyItem method
IAzScope::DeleteRole method
IAzScope::DeleteTask method
IAzScope::get_ApplicationData method
IAzScope::get_ApplicationGroups method
IAzScope::get_BizrulesWritable method
IAzScope::get_CanBeDelegated method
IAzScope::get_Description method
IAzScope::get_Name method
IAzScope::get_PolicyAdministrators method
IAzScope::get_PolicyAdministratorsName method
IAzScope::get_PolicyReaders method
IAzScope::get_PolicyReadersName method
IAzScope::get_Roles method
IAzScope::get_Tasks method
IAzScope::get_Writable method
IAzScope::GetProperty method
IAzScope::OpenApplicationGroup method
IAzScope::OpenRole method
IAzScope::OpenTask method
IAzScope::put_ApplicationData method
IAzScope::put_Description method
IAzScope::put_Name method
IAzScope::SetProperty method
IAzScope::Submit method
IAzScope2 interface
Overview
IAzScope2::CreateRoleAssignment method
IAzScope2::CreateRoleDefinition method
IAzScope2::DeleteRoleAssignment method
IAzScope2::DeleteRoleDefinition method
IAzScope2::get_RoleAssignments method
IAzScope2::get_RoleDefinitions method
IAzScope2::OpenRoleAssignment method
IAzScope2::OpenRoleDefinition method
IAzScopes interface
Overview
IAzScopes::get__NewEnum method
IAzScopes::get_Count method
IAzScopes::get_Item method
IAzTask interface
Overview
IAzTask::AddOperation method
IAzTask::AddPropertyItem method
IAzTask::AddTask method
IAzTask::DeleteOperation method
IAzTask::DeletePropertyItem method
IAzTask::DeleteTask method
IAzTask::get_ApplicationData method
IAzTask::get_BizRule method
IAzTask::get_BizRuleImportedPath method
IAzTask::get_BizRuleLanguage method
IAzTask::get_Description method
IAzTask::get_IsRoleDefinition method
IAzTask::get_Name method
IAzTask::get_Operations method
IAzTask::get_Tasks method
 IAzTask::get_Writable method
IAzTask::GetProperty method
IAzTask::put_ApplicationData method
IAzTask::put_BizRule method
IAzTask::put_BizRuleImportedPath method
IAzTask::put_BizRuleLanguage method
IAzTask::put_Description method
IAzTask::put_IsRoleDefinition method
IAzTask::put_Name method
IAzTask::SetProperty method
IAzTask::Submit method
IAzTask2 interface
Overview
IAzTask2::RoleAssignments method
IAzTasks interface
Overview
IAzTasks::get__NewEnum method
IAzTasks::get_Count method
IAzTasks::get_Item method
Bcrypt.h
Overview
BCRYPT_ALGORITHM_IDENTIFIER structure
BCRYPT_AUTHENTICATED_CIPHER_MODE_INFO structure
BCRYPT_DH_KEY_BLOB structure
BCRYPT_DH_PARAMETER_HEADER structure
BCRYPT_DSA_KEY_BLOB structure
BCRYPT_DSA_KEY_BLOB_V2 structure
BCRYPT_DSA_PARAMETER_HEADER structure
BCRYPT_DSA_PARAMETER_HEADER_V2 structure
BCRYPT_ECCKEY_BLOB structure
BCRYPT_HASH_OPERATION_TYPE enumeration
BCRYPT_INIT_AUTH_MODE_INFO macro
BCRYPT_INTERFACE_VERSION structure
BCRYPT_KEY_BLOB structure
BCRYPT_KEY_DATA_BLOB_HEADER structure
BCRYPT_KEY_LENGTHS_STRUCT structure
BCRYPT_MULTI_HASH_OPERATION structure
BCRYPT_MULTI_OBJECT_LENGTH_STRUCT structure
BCRYPT_MULTI_OPERATION_TYPE enumeration
BCRYPT_OAEP_PADDING_INFO structure
BCRYPT_OID structure
BCRYPT_OID_LIST structure
BCRYPT_PKCS1_PADDING_INFO structure
BCRYPT_PROVIDER_NAME structure
BCRYPT_PSS_PADDING_INFO structure
BCRYPT_RSAKEY_BLOB structure
BCryptAddContextFunction function
BCryptBuffer structure
BCryptBufferDesc structure
BCryptCloseAlgorithmProvider function
BCryptConfigureContext function
BCryptConfigureContextFunction function
BCryptCreateContext function
BCryptCreateHash function
BCryptCreateMultiHash function
BCryptDecrypt function
BCryptDeleteContext function
BCryptDeriveKey function
BCryptDeriveKeyCapi function
BCryptDeriveKeyPBKDF2 function
BCryptDestroyHash function
BCryptDestroyKey function
BCryptDestroySecret function
BCryptDuplicateHash function
BCryptDuplicateKey function
BCryptEncrypt function
BCryptEnumAlgorithms function
BCryptEnumContextFunctionProviders function
BCryptEnumContextFunctions function
BCryptEnumContexts function
BCryptEnumProviders function
BCryptEnumRegisteredProviders function
BCryptExportKey function
BCryptFinalizeKeyPair function
BCryptFinishHash function
BCryptFreeBuffer function
BCryptGenerateKeyPair function
BCryptGenerateSymmetricKey function
BCryptGenRandom function
BCryptGetFipsAlgorithmMode function
BCryptGetProperty function
BCryptHash function
BCryptHashData function
BCryptImportKey function
BCryptImportKeyPair function
BCryptKeyDerivation function
BCryptOpenAlgorithmProvider function
BCryptProcessMultiOperations function
BCryptQueryContextConfiguration function
BCryptQueryContextFunctionConfiguration function
BCryptQueryContextFunctionProperty function
BCryptQueryProviderRegistration function
BCryptRegisterConfigChangeNotify function
BCryptRemoveContextFunction function
BCryptResolveProviders function
BCryptSecretAgreement function
 BCryptSetContextFunctionProperty function
BCryptSetProperty function
BCryptSignHash function
BCryptUnregisterConfigChangeNotify function
BCryptVerifySignature function
CRYPT_CONTEXT_CONFIG structure
CRYPT_CONTEXT_FUNCTION_CONFIG structure
CRYPT_CONTEXT_FUNCTION_PROVIDERS structure
CRYPT_CONTEXT_FUNCTIONS structure
CRYPT_CONTEXTS structure
CRYPT_IMAGE_REF structure
CRYPT_IMAGE_REG structure
CRYPT_INTERFACE_REG structure
CRYPT_PROPERTY_REF structure
CRYPT_PROVIDER_REF structure
CRYPT_PROVIDER_REFS structure
CRYPT_PROVIDER_REG structure
CRYPT_PROVIDERS structure
DSAFIPSVERSION_ENUM enumeration
HASHALGORITHM_ENUM enumeration
Casetup.h
Overview
CASetupProperty enumeration
CEPSetupProperty enumeration
CESSetupProperty enumeration
ICertificateEnrollmentPolicyServerSetup interface
Overview
ICertificateEnrollmentPolicyServerSetup::get_ErrorString method
ICertificateEnrollmentPolicyServerSetup::GetProperty method
ICertificateEnrollmentPolicyServerSetup::InitializeInstallDefaults method
ICertificateEnrollmentPolicyServerSetup::Install method
ICertificateEnrollmentPolicyServerSetup::SetProperty method
 ICertificateEnrollmentPolicyServerSetup::UnInstall method
ICertificateEnrollmentServerSetup interface
Overview
ICertificateEnrollmentServerSetup::get_ErrorString method
ICertificateEnrollmentServerSetup::GetProperty method
ICertificateEnrollmentServerSetup::InitializeInstallDefaults method
ICertificateEnrollmentServerSetup::Install method
ICertificateEnrollmentServerSetup::SetApplicationPoolCredentials method
ICertificateEnrollmentServerSetup::SetProperty method
ICertificateEnrollmentServerSetup::UnInstall method
ICertSrvSetup interface
Overview
ICertSrvSetup::CAImportPFX method
ICertSrvSetup::get_CAErrorId method
ICertSrvSetup::get_CAErrorString method
ICertSrvSetup::GetCASetupProperty method
ICertSrvSetup::GetExistingCACertificates method
ICertSrvSetup::GetHashAlgorithmList method
ICertSrvSetup::GetKeyLengthList method
ICertSrvSetup::GetPrivateKeyContainerList method
ICertSrvSetup::GetProviderNameList method
ICertSrvSetup::GetSupportedCATypes method
ICertSrvSetup::InitializeDefaults method
ICertSrvSetup::Install method
ICertSrvSetup::IsPropertyEditable method
ICertSrvSetup::PostUnInstall method
ICertSrvSetup::PreUnInstall method
ICertSrvSetup::SetCADistinguishedName method
ICertSrvSetup::SetCASetupProperty method
ICertSrvSetup::SetDatabaseInformation method
ICertSrvSetup::SetParentCAInformation method
ICertSrvSetup::SetWebCAInformation method
ICertSrvSetupKeyInformation interface
Overview
ICertSrvSetupKeyInformation::get_ContainerName method
ICertSrvSetupKeyInformation::get_Existing method
ICertSrvSetupKeyInformation::get_ExistingCACertificate method
ICertSrvSetupKeyInformation::get_HashAlgorithm method
ICertSrvSetupKeyInformation::get_Length method
ICertSrvSetupKeyInformation::get_ProviderName method
ICertSrvSetupKeyInformation::put_ContainerName method
ICertSrvSetupKeyInformation::put_Existing method
ICertSrvSetupKeyInformation::put_ExistingCACertificate method
ICertSrvSetupKeyInformation::put_HashAlgorithm method
ICertSrvSetupKeyInformation::put_Length method
ICertSrvSetupKeyInformation::put_ProviderName method
ICertSrvSetupKeyInformationCollection interface
Overview
ICertSrvSetupKeyInformationCollection::Add method
ICertSrvSetupKeyInformationCollection::get__NewEnum method
ICertSrvSetupKeyInformationCollection::get_Count method
ICertSrvSetupKeyInformationCollection::get_Item method
IMSCEPSetup interface
Overview
IMSCEPSetup::get_MSCEPErrorId method
IMSCEPSetup::get_MSCEPErrorString method
IMSCEPSetup::GetKeyLengthList method
IMSCEPSetup::GetMSCEPSetupProperty method
IMSCEPSetup::GetProviderNameList method
IMSCEPSetup::InitializeDefaults method
IMSCEPSetup::Install method
IMSCEPSetup::IsMSCEPStoreEmpty method
IMSCEPSetup::PostUnInstall method
IMSCEPSetup::PreUnInstall method
 IMSCEPSetup::SetAccountInformation method
IMSCEPSetup::SetMSCEPSetupProperty method
MSCEPSetupProperty enumeration
Ccgplugins.h
Overview
ICcgDomainAuthCredentials interface
Overview
ICcgDomainAuthCredentials::GetPasswordCredentials method
Celib.h
Overview
ENUM_PERIOD enumeration
Certadm.h
Overview
ICertAdmin interface
Overview
ICertAdmin::DenyRequest method
ICertAdmin::GetCRL method
ICertAdmin::GetRevocationReason method
ICertAdmin::ImportCertificate method
ICertAdmin::IsValidCertificate method
ICertAdmin::PublishCRL method
ICertAdmin::ResubmitRequest method
ICertAdmin::RevokeCertificate method
ICertAdmin::SetCertificateExtension method
ICertAdmin::SetRequestAttributes method
ICertAdmin2 interface
Overview
ICertAdmin2::DeleteRow method
ICertAdmin2::GetArchivedKey method
ICertAdmin2::GetCAProperty method
ICertAdmin2::GetCAPropertyDisplayName method
ICertAdmin2::GetCAPropertyFlags method
 ICertAdmin2::GetConfigEntry method
ICertAdmin2::GetMyRoles method
ICertAdmin2::ImportKey method
ICertAdmin2::PublishCRLs method
ICertAdmin2::SetCAProperty method
ICertAdmin2::SetConfigEntry method
IOCSPAdmin interface
Overview
IOCSPAdmin::get_OCSPCAConfigurationCollection method
IOCSPAdmin::get_OCSPServiceProperties method
IOCSPAdmin::GetConfiguration method
IOCSPAdmin::GetHashAlgorithms method
IOCSPAdmin::GetMyRoles method
IOCSPAdmin::GetSecurity method
IOCSPAdmin::GetSigningCertificates method
IOCSPAdmin::Ping method
IOCSPAdmin::SetConfiguration method
IOCSPAdmin::SetSecurity method
IOCSPCAConfiguration interface
Overview
IOCSPCAConfiguration::get_CACertificate method
IOCSPCAConfiguration::get_CAConfig method
IOCSPCAConfiguration::get_CSPName method
IOCSPCAConfiguration::get_ErrorCode method
IOCSPCAConfiguration::get_HashAlgorithm method
IOCSPCAConfiguration::get_Identifier method
IOCSPCAConfiguration::get_KeySpec method
IOCSPCAConfiguration::get_LocalRevocationInformation method
IOCSPCAConfiguration::get_Modified method
IOCSPCAConfiguration::get_ProviderCLSID method
IOCSPCAConfiguration::get_ProviderProperties method
IOCSPCAConfiguration::get_ReminderDuration method
 IOCSPCAConfiguration::get_SigningCertificate method
IOCSPCAConfiguration::get_SigningCertificateTemplate method
IOCSPCAConfiguration::get_SigningFlags method
IOCSPCAConfiguration::put_CAConfig method
IOCSPCAConfiguration::put_HashAlgorithm method
IOCSPCAConfiguration::put_LocalRevocationInformation method
IOCSPCAConfiguration::put_ProviderCLSID method
IOCSPCAConfiguration::put_ProviderProperties method
IOCSPCAConfiguration::put_ReminderDuration method
IOCSPCAConfiguration::put_SigningCertificate method
IOCSPCAConfiguration::put_SigningCertificateTemplate method
IOCSPCAConfiguration::put_SigningFlags method
IOCSPCAConfigurationCollection interface
Overview
IOCSPCAConfigurationCollection::CreateCAConfiguration method
IOCSPCAConfigurationCollection::DeleteCAConfiguration method
IOCSPCAConfigurationCollection::get__NewEnum method
IOCSPCAConfigurationCollection::get_Count method
IOCSPCAConfigurationCollection::get_Item method
IOCSPCAConfigurationCollection::get_ItemByName method
IOCSPProperty interface
Overview
IOCSPProperty::get_Modified method
IOCSPProperty::get_Name method
IOCSPProperty::get_Value method
IOCSPProperty::put_Value method
IOCSPPropertyCollection interface
Overview
IOCSPPropertyCollection::CreateProperty method
IOCSPPropertyCollection::DeleteProperty method
IOCSPPropertyCollection::get__NewEnum method
IOCSPPropertyCollection::get_Count method
 IOCSPPropertyCollection::get_Item method
IOCSPPropertyCollection::get_ItemByName method
IOCSPPropertyCollection::GetAllProperties method
IOCSPPropertyCollection::InitializeFromProperties method
Certbcli.h
Overview
CertSrvBackupClose function
CertSrvBackupEnd function
CertSrvBackupFree function
CertSrvBackupGetBackupLogsW function
CertSrvBackupGetDatabaseNamesW function
CertSrvBackupGetDynamicFileListW function
CertSrvBackupOpenFileW function
CertSrvBackupPrepareW function
CertSrvBackupRead function
CertSrvBackupTruncateLogs function
CertSrvIsServerOnlineW function
CertSrvRestoreEnd function
CertSrvRestoreGetDatabaseLocationsW function
CertSrvRestorePrepareW function
CertSrvRestoreRegisterComplete function
CertSrvRestoreRegisterThroughFile function
CertSrvRestoreRegisterW function
CertSrvServerControlW function
Certcli.h
Overview
ICertConfig interface
Overview
ICertConfig::GetConfig method
ICertConfig::GetField method
ICertConfig::Next method
ICertConfig::Reset method
 ICertConfig2 interface
Overview
ICertConfig2::SetSharedFolder method
ICertGetConfig interface
ICertRequest interface
Overview
ICertRequest::GetCACertificate method
ICertRequest::GetCertificate method
ICertRequest::GetDispositionMessage method
ICertRequest::GetLastStatus method
ICertRequest::GetRequestId method
ICertRequest::RetrievePending method
ICertRequest::Submit method
ICertRequest2 interface
Overview
ICertRequest2::GetCAProperty method
ICertRequest2::GetCAPropertyDisplayName method
ICertRequest2::GetCAPropertyFlags method
ICertRequest2::GetErrorMessageText method
ICertRequest2::GetFullResponseProperty method
ICertRequest2::GetIssuedCertificate method
ICertRequest3 interface
Overview
ICertRequest3::GetIssuedCertificate2 method
ICertRequest3::GetRefreshPolicy method
ICertRequest3::GetRequestIdString method
ICertRequest3::SetCredential method
X509EnrollmentAuthFlags enumeration
Certenc.h
Overview
ICertEncodeAltName interface
Overview
 ICertEncodeAltName::Decode method
ICertEncodeAltName::Encode method
ICertEncodeAltName::GetName method
ICertEncodeAltName::GetNameChoice method
ICertEncodeAltName::GetNameCount method
ICertEncodeAltName::Reset method
ICertEncodeAltName::SetNameEntry method
ICertEncodeBitString interface
Overview
ICertEncodeBitString::Decode method
ICertEncodeBitString::Encode method
ICertEncodeBitString::GetBitCount method
ICertEncodeBitString::GetBitString method
ICertEncodeCRLDistInfo interface
Overview
ICertEncodeCRLDistInfo::Decode method
ICertEncodeCRLDistInfo::Encode method
ICertEncodeCRLDistInfo::GetDistPointCount method
ICertEncodeCRLDistInfo::GetName method
ICertEncodeCRLDistInfo::GetNameChoice method
ICertEncodeCRLDistInfo::GetNameCount method
ICertEncodeCRLDistInfo::Reset method
ICertEncodeCRLDistInfo::SetNameCount method
ICertEncodeCRLDistInfo::SetNameEntry method
ICertEncodeDateArray interface
Overview
ICertEncodeDateArray::Decode method
ICertEncodeDateArray::Encode method
ICertEncodeDateArray::GetCount method
ICertEncodeDateArray::GetValue method
ICertEncodeDateArray::Reset method
ICertEncodeDateArray::SetValue method
 ICertEncodeLongArray interface
Overview
ICertEncodeLongArray::Decode method
ICertEncodeLongArray::Encode method
ICertEncodeLongArray::GetCount method
ICertEncodeLongArray::GetValue method
ICertEncodeLongArray::Reset method
ICertEncodeLongArray::SetValue method
ICertEncodeStringArray interface
Overview
ICertEncodeStringArray::Decode method
ICertEncodeStringArray::Encode method
ICertEncodeStringArray::GetCount method
ICertEncodeStringArray::GetStringType method
ICertEncodeStringArray::GetValue method
ICertEncodeStringArray::Reset method
ICertEncodeStringArray::SetValue method
Certenroll.h
Overview
AlgorithmFlags enumeration
AlgorithmOperationFlags enumeration
AlgorithmType enumeration
AlternativeNameType enumeration
CERTENROLL_OBJECTID enumeration
CERTENROLL_PROPERTYID enumeration
CommitTemplateFlags enumeration
EncodingType enumeration
EnrollmentCAProperty enumeration
EnrollmentDisplayStatus enumeration
EnrollmentEnrollStatus enumeration
EnrollmentPolicyFlags enumeration
EnrollmentPolicyServerPropertyFlags enumeration
EnrollmentSelectionStatus enumeration
EnrollmentTemplateProperty enumeration
IAlternativeName interface
Overview
IAlternativeName::get_ObjectId method
IAlternativeName::get_RawData method
IAlternativeName::get_StrValue method
IAlternativeName::get_Type method
IAlternativeName::InitializeFromOtherName method
IAlternativeName::InitializeFromRawData method
IAlternativeName::InitializeFromString method
IAlternativeNames interface
Overview
IAlternativeNames::Add method
IAlternativeNames::Clear method
IAlternativeNames::get__NewEnum method
IAlternativeNames::get_Count method
IAlternativeNames::Remove method
IBinaryConverter interface
Overview
IBinaryConverter::StringToString method
IBinaryConverter::StringToVariantByteArray method
IBinaryConverter::VariantByteArrayToString method
ICertificateAttestationChallenge interface
Overview
ICertificateAttestationChallenge::DecryptChallenge method
ICertificateAttestationChallenge::get_RequestID method
ICertificateAttestationChallenge::Initialize method
ICertificatePolicies interface
Overview
ICertificatePolicies::Add method
ICertificatePolicies::Clear method
 ICertificatePolicies::get__NewEnum method
ICertificatePolicies::get_Count method
ICertificatePolicies::Remove method
ICertificatePolicy interface
Overview
ICertificatePolicy::get_ObjectId method
ICertificatePolicy::get_PolicyQualifiers method
ICertificatePolicy::Initialize method
ICertificationAuthorities interface
Overview
ICertificationAuthorities::Add method
ICertificationAuthorities::Clear method
ICertificationAuthorities::ComputeSiteCosts method
ICertificationAuthorities::get__NewEnum method
ICertificationAuthorities::get_Count method
ICertificationAuthorities::get_ItemByName method
ICertificationAuthorities::Remove method
ICertificationAuthority interface
Overview
ICertificationAuthority::get_Property method
ICertProperties interface
Overview
ICertProperties::Add method
ICertProperties::Clear method
ICertProperties::get__NewEnum method
ICertProperties::get_Count method
ICertProperties::InitializeFromCertificate method
ICertProperties::Remove method
ICertProperty interface
Overview
ICertProperty::get_PropertyId method
ICertProperty::get_RawData method
 ICertProperty::InitializeDecode method
ICertProperty::InitializeFromCertificate method
ICertProperty::put_PropertyId method
ICertProperty::RemoveFromCertificate method
ICertProperty::SetValueOnCertificate method
ICertPropertyArchived interface
Overview
ICertPropertyArchived::get_Archived method
ICertPropertyArchived::Initialize method
ICertPropertyArchivedKeyHash interface
Overview
ICertPropertyArchivedKeyHash::get_ArchivedKeyHash method
ICertPropertyArchivedKeyHash::Initialize method
ICertPropertyAutoEnroll interface
Overview
ICertPropertyAutoEnroll::get_TemplateName method
ICertPropertyAutoEnroll::Initialize method
ICertPropertyBackedUp interface
Overview
ICertPropertyBackedUp::get_BackedUpTime method
ICertPropertyBackedUp::get_BackedUpValue method
ICertPropertyBackedUp::Initialize method
ICertPropertyBackedUp::InitializeFromCurrentTime method
ICertPropertyDescription interface
Overview
ICertPropertyDescription::get_Description method
ICertPropertyDescription::Initialize method
ICertPropertyEnrollment interface
Overview
ICertPropertyEnrollment::get_CADnsName method
ICertPropertyEnrollment::get_CAName method
ICertPropertyEnrollment::get_FriendlyName method
 ICertPropertyEnrollment::get_RequestId method
ICertPropertyEnrollment::Initialize method
ICertPropertyEnrollmentPolicyServer interface
Overview
ICertPropertyEnrollmentPolicyServer::GetAuthentication method
ICertPropertyEnrollmentPolicyServer::GetEnrollmentServerAuthentication method
ICertPropertyEnrollmentPolicyServer::GetEnrollmentServerUrl method
ICertPropertyEnrollmentPolicyServer::GetPolicyServerId method
ICertPropertyEnrollmentPolicyServer::GetPolicyServerUrl method
ICertPropertyEnrollmentPolicyServer::GetPropertyFlags method
ICertPropertyEnrollmentPolicyServer::GetRequestIdString method
ICertPropertyEnrollmentPolicyServer::GetUrlFlags method
ICertPropertyEnrollmentPolicyServer::Initialize method
ICertPropertyFriendlyName interface
Overview
ICertPropertyFriendlyName::get_FriendlyName method
ICertPropertyFriendlyName::Initialize method
ICertPropertyKeyProvInfo interface
Overview
ICertPropertyKeyProvInfo::get_PrivateKey method
ICertPropertyKeyProvInfo::Initialize method
ICertPropertyRenewal interface
Overview
ICertPropertyRenewal::get_Renewal method
ICertPropertyRenewal::Initialize method
ICertPropertyRenewal::InitializeFromCertificateHash method
ICertPropertyRequestOriginator interface
Overview
ICertPropertyRequestOriginator::get_RequestOriginator method
ICertPropertyRequestOriginator::Initialize method
ICertPropertyRequestOriginator::InitializeFromLocalRequestOriginator method
ICertPropertySHA1Hash interface
 Overview
ICertPropertySHA1Hash::get_SHA1Hash method
ICertPropertySHA1Hash::Initialize method
ICryptAttribute interface
Overview
ICryptAttribute::get_ObjectId method
ICryptAttribute::get_Values method
ICryptAttribute::InitializeFromObjectId method
ICryptAttribute::InitializeFromValues method
ICryptAttributes interface
Overview
ICryptAttributes::Add method
ICryptAttributes::AddRange method
ICryptAttributes::Clear method
ICryptAttributes::get__NewEnum method
ICryptAttributes::get_Count method
ICryptAttributes::get_IndexByObjectId method
ICryptAttributes::Remove method
ICspAlgorithm interface
Overview
ICspAlgorithm::get_DefaultLength method
ICspAlgorithm::get_IncrementLength method
ICspAlgorithm::get_LongName method
ICspAlgorithm::get_MaxLength method
ICspAlgorithm::get_MinLength method
ICspAlgorithm::get_Name method
ICspAlgorithm::get_Operations method
ICspAlgorithm::get_Type method
ICspAlgorithm::get_Valid method
ICspAlgorithm::GetAlgorithmOid method
ICspAlgorithms interface
Overview
 ICspAlgorithms::Add method
ICspAlgorithms::Clear method
ICspAlgorithms::get__NewEnum method
ICspAlgorithms::get_Count method
ICspAlgorithms::get_IndexByObjectId method
ICspAlgorithms::get_ItemByName method
ICspAlgorithms::Remove method
ICspInformation interface
Overview
ICspInformation::get_CspAlgorithms method
ICspInformation::get_HasHardwareRandomNumberGenerator method
ICspInformation::get_IsHardwareDevice method
ICspInformation::get_IsRemovable method
ICspInformation::get_IsSmartCard method
ICspInformation::get_IsSoftwareDevice method
ICspInformation::get_KeySpec method
ICspInformation::get_LegacyCsp method
ICspInformation::get_MaxKeyContainerNameLength method
ICspInformation::get_Name method
ICspInformation::get_Type method
ICspInformation::get_Valid method
ICspInformation::get_Version method
ICspInformation::GetCspStatusFromOperations method
ICspInformation::GetDefaultSecurityDescriptor method
ICspInformation::InitializeFromName method
ICspInformation::InitializeFromType method
ICspInformations interface
Overview
ICspInformations::Add method
ICspInformations::AddAvailableCsps method
ICspInformations::Clear method
ICspInformations::get__NewEnum method
 ICspInformations::get_Count method
ICspInformations::get_ItemByName method
ICspInformations::GetCspStatusesFromOperations method
ICspInformations::GetCspStatusFromProviderName method
ICspInformations::GetEncryptionCspAlgorithms method
ICspInformations::GetHashAlgorithms method
ICspInformations::Remove method
ICspStatus interface
Overview
ICspStatus::get_CspAlgorithm method
ICspStatus::get_CspInformation method
ICspStatus::get_DisplayName method
ICspStatus::get_EnrollmentStatus method
ICspStatus::get_Ordinal method
ICspStatus::Initialize method
ICspStatus::put_Ordinal method
ICspStatuses interface
Overview
ICspStatuses::Add method
ICspStatuses::Clear method
ICspStatuses::get__NewEnum method
ICspStatuses::get_Count method
ICspStatuses::get_ItemByName method
ICspStatuses::get_ItemByOperations method
ICspStatuses::get_ItemByOrdinal method
ICspStatuses::get_ItemByProvider method
ICspStatuses::Remove method
ImportPFXFlags enumeration
ImportPFXToProvider callback function
ImportPFXToProviderFreeData callback function
InnerRequestLevel enumeration
InstallResponseRestrictionFlags enumeration
IObjectId interface
Overview
IObjectId::get_FriendlyName method
IObjectId::get_Name method
IObjectId::get_Value method
IObjectId::GetAlgorithmName method
IObjectId::InitializeFromAlgorithmName method
IObjectId::InitializeFromName method
IObjectId::InitializeFromValue method
IObjectId::put_FriendlyName method
IObjectIds interface
Overview
IObjectIds::Add method
IObjectIds::AddRange method
IObjectIds::Clear method
IObjectIds::get__NewEnum method
IObjectIds::get_Count method
IObjectIds::Remove method
IPolicyQualifier interface
Overview
IPolicyQualifier::get_ObjectId method
IPolicyQualifier::get_Qualifier method
IPolicyQualifier::get_RawData method
IPolicyQualifier::get_Type method
IPolicyQualifier::InitializeEncode method
IPolicyQualifiers interface
Overview
IPolicyQualifiers::Add method
IPolicyQualifiers::Clear method
IPolicyQualifiers::get__NewEnum method
IPolicyQualifiers::get_Count method
IPolicyQualifiers::Remove method
ISignerCertificate interface
Overview
ISignerCertificate::get_Certificate method
ISignerCertificate::get_ParentWindow method
ISignerCertificate::get_PrivateKey method
ISignerCertificate::get_SignatureInformation method
ISignerCertificate::get_Silent method
ISignerCertificate::get_UIContextMessage method
ISignerCertificate::Initialize method
ISignerCertificate::put_ParentWindow method
ISignerCertificate::put_Pin method
ISignerCertificate::put_Silent method
ISignerCertificate::put_UIContextMessage method
ISignerCertificates interface
Overview
ISignerCertificates::Add method
ISignerCertificates::Clear method
ISignerCertificates::Find method
ISignerCertificates::get__NewEnum method
ISignerCertificates::get_Count method
ISignerCertificates::Remove method
ISmimeCapabilities interface
Overview
ISmimeCapabilities::Add method
ISmimeCapabilities::AddAvailableSmimeCapabilities method
ISmimeCapabilities::AddFromCsp method
ISmimeCapabilities::Clear method
ISmimeCapabilities::get__NewEnum method
ISmimeCapabilities::get_Count method
ISmimeCapabilities::Remove method
ISmimeCapability interface
Overview
 ISmimeCapability::get_BitCount method
ISmimeCapability::get_ObjectId method
ISmimeCapability::Initialize method
IX500DistinguishedName interface
Overview
IX500DistinguishedName::Decode method
IX500DistinguishedName::Encode method
IX500DistinguishedName::get_EncodedName method
IX500DistinguishedName::get_Name method
IX509Attribute interface
Overview
IX509Attribute::get_ObjectId method
IX509Attribute::get_RawData method
IX509Attribute::Initialize method
IX509AttributeArchiveKey interface
Overview
IX509AttributeArchiveKey::get_EncryptedKeyBlob method
IX509AttributeArchiveKey::get_EncryptionAlgorithm method
IX509AttributeArchiveKey::get_EncryptionStrength method
IX509AttributeArchiveKey::InitializeDecode method
IX509AttributeArchiveKey::InitializeEncode method
IX509AttributeArchiveKeyHash interface
Overview
IX509AttributeArchiveKeyHash::get_EncryptedKeyHashBlob method
IX509AttributeArchiveKeyHash::InitializeDecode method
IX509AttributeArchiveKeyHash::InitializeEncodeFromEncryptedKeyBlob method
IX509AttributeClientId interface
Overview
IX509AttributeClientId::get_ClientId method
IX509AttributeClientId::get_MachineDnsName method
IX509AttributeClientId::get_ProcessName method
IX509AttributeClientId::get_UserSamName method
 IX509AttributeClientId::InitializeDecode method
IX509AttributeClientId::InitializeEncode method
IX509AttributeCspProvider interface
Overview
IX509AttributeCspProvider::get_KeySpec method
IX509AttributeCspProvider::get_ProviderName method
IX509AttributeCspProvider::get_Signature method
IX509AttributeCspProvider::InitializeDecode method
IX509AttributeCspProvider::InitializeEncode method
IX509AttributeExtensions interface
Overview
IX509AttributeExtensions::get_X509Extensions method
IX509AttributeExtensions::InitializeDecode method
IX509AttributeExtensions::InitializeEncode method
IX509AttributeOSVersion interface
Overview
IX509AttributeOSVersion::get_OSVersion method
IX509AttributeOSVersion::InitializeDecode method
IX509AttributeOSVersion::InitializeEncode method
IX509AttributeRenewalCertificate interface
Overview
IX509AttributeRenewalCertificate::get_RenewalCertificate method
IX509AttributeRenewalCertificate::InitializeDecode method
IX509AttributeRenewalCertificate::InitializeEncode method
IX509Attributes interface
Overview
IX509Attributes::Add method
IX509Attributes::Clear method
IX509Attributes::get__NewEnum method
IX509Attributes::get_Count method
IX509Attributes::Remove method
IX509CertificateRequest interface
 Overview
IX509CertificateRequest::Encode method
IX509CertificateRequest::get_AlternateSignatureAlgorithm method
IX509CertificateRequest::get_ClientId method
IX509CertificateRequest::get_CspInformations method
IX509CertificateRequest::get_EnrollmentContext method
IX509CertificateRequest::get_HashAlgorithm method
IX509CertificateRequest::get_ParentWindow method
IX509CertificateRequest::get_RawData method
IX509CertificateRequest::get_RenewalCertificate method
IX509CertificateRequest::get_Silent method
IX509CertificateRequest::get_SuppressDefaults method
IX509CertificateRequest::get_Type method
IX509CertificateRequest::get_UIContextMessage method
IX509CertificateRequest::GetInnerRequest method
IX509CertificateRequest::Initialize method
IX509CertificateRequest::put_AlternateSignatureAlgorithm method
IX509CertificateRequest::put_ClientId method
IX509CertificateRequest::put_CspInformations method
IX509CertificateRequest::put_HashAlgorithm method
IX509CertificateRequest::put_ParentWindow method
IX509CertificateRequest::put_RenewalCertificate method
IX509CertificateRequest::put_Silent method
IX509CertificateRequest::put_SuppressDefaults method
IX509CertificateRequest::put_UIContextMessage method
IX509CertificateRequest::ResetForEncode method
IX509CertificateRequestCertificate interface
Overview
IX509CertificateRequestCertificate::CheckPublicKeySignature method
IX509CertificateRequestCertificate::get_Issuer method
IX509CertificateRequestCertificate::get_NotAfter method
IX509CertificateRequestCertificate::get_NotBefore method
 IX509CertificateRequestCertificate::get_SerialNumber method
IX509CertificateRequestCertificate::get_SignerCertificate method
IX509CertificateRequestCertificate::put_Issuer method
IX509CertificateRequestCertificate::put_NotAfter method
IX509CertificateRequestCertificate::put_NotBefore method
IX509CertificateRequestCertificate::put_SerialNumber method
IX509CertificateRequestCertificate::put_SignerCertificate method
IX509CertificateRequestCertificate2 interface
Overview
IX509CertificateRequestCertificate2::get_PolicyServer method
IX509CertificateRequestCertificate2::get_Template method
IX509CertificateRequestCertificate2::InitializeFromPrivateKeyTemplate method
IX509CertificateRequestCertificate2::InitializeFromTemplate method
IX509CertificateRequestCmc interface
Overview
IX509CertificateRequestCmc::get_ArchivePrivateKey method
IX509CertificateRequestCmc::get_CriticalExtensions method
IX509CertificateRequestCmc::get_CryptAttributes method
IX509CertificateRequestCmc::get_EncryptedKeyHash method
IX509CertificateRequestCmc::get_EncryptionAlgorithm method
IX509CertificateRequestCmc::get_EncryptionStrength method
IX509CertificateRequestCmc::get_KeyArchivalCertificate method
IX509CertificateRequestCmc::get_NameValuePairs method
IX509CertificateRequestCmc::get_NullSigned method
IX509CertificateRequestCmc::get_SenderNonce method
IX509CertificateRequestCmc::get_SignatureInformation method
IX509CertificateRequestCmc::get_SignerCertificates method
IX509CertificateRequestCmc::get_SuppressOids method
IX509CertificateRequestCmc::get_TemplateObjectId method
IX509CertificateRequestCmc::get_TransactionId method
IX509CertificateRequestCmc::get_X509Extensions method
IX509CertificateRequestCmc::InitializeFromInnerRequestTemplateName method
 IX509CertificateRequestCmc::put_ArchivePrivateKey method
IX509CertificateRequestCmc::put_EncryptionAlgorithm method
IX509CertificateRequestCmc::put_EncryptionStrength method
IX509CertificateRequestCmc::put_KeyArchivalCertificate method
IX509CertificateRequestCmc::put_SenderNonce method
IX509CertificateRequestCmc::put_TransactionId method
IX509CertificateRequestCmc2 interface
Overview
IX509CertificateRequestCmc2::CheckCertificateSignature method
IX509CertificateRequestCmc2::CheckSignature method
IX509CertificateRequestCmc2::get_PolicyServer method
IX509CertificateRequestCmc2::get_Template method
IX509CertificateRequestCmc2::InitializeFromInnerRequestTemplate method
IX509CertificateRequestCmc2::InitializeFromTemplate method
IX509CertificateRequestPkcs10 interface
Overview
IX509CertificateRequestPkcs10::CheckSignature method
IX509CertificateRequestPkcs10::get_CriticalExtensions method
IX509CertificateRequestPkcs10::get_CryptAttributes method
IX509CertificateRequestPkcs10::get_CspStatuses method
IX509CertificateRequestPkcs10::get_KeyContainerNamePrefix method
IX509CertificateRequestPkcs10::get_NullSigned method
IX509CertificateRequestPkcs10::get_OldCertificate method
IX509CertificateRequestPkcs10::get_PrivateKey method
IX509CertificateRequestPkcs10::get_PublicKey method
IX509CertificateRequestPkcs10::get_RawDataToBeSigned method
IX509CertificateRequestPkcs10::get_ReuseKey method
IX509CertificateRequestPkcs10::get_Signature method
IX509CertificateRequestPkcs10::get_SignatureInformation method
IX509CertificateRequestPkcs10::get_SmimeCapabilities method
IX509CertificateRequestPkcs10::get_Subject method
IX509CertificateRequestPkcs10::get_SuppressOids method
 IX509CertificateRequestPkcs10::get_TemplateObjectId method
IX509CertificateRequestPkcs10::get_X509Extensions method
IX509CertificateRequestPkcs10::GetCspStatuses method
IX509CertificateRequestPkcs10::InitializeDecode method
IX509CertificateRequestPkcs10::InitializeFromCertificate method
IX509CertificateRequestPkcs10::InitializeFromPrivateKey method
IX509CertificateRequestPkcs10::InitializeFromPublicKey method
IX509CertificateRequestPkcs10::InitializeFromTemplateName method
IX509CertificateRequestPkcs10::IsSmartCard method
IX509CertificateRequestPkcs10::put_KeyContainerNamePrefix method
IX509CertificateRequestPkcs10::put_SmimeCapabilities method
IX509CertificateRequestPkcs10::put_Subject method
IX509CertificateRequestPkcs10V2 interface
Overview
IX509CertificateRequestPkcs10V2::get_PolicyServer method
IX509CertificateRequestPkcs10V2::get_Template method
IX509CertificateRequestPkcs10V2::InitializeFromPrivateKeyTemplate method
IX509CertificateRequestPkcs10V2::InitializeFromPublicKeyTemplate method
IX509CertificateRequestPkcs10V2::InitializeFromTemplate method
IX509CertificateRequestPkcs10V3 interface
Overview
IX509CertificateRequestPkcs10V3::get_AttestationEncryptionCertificate method
IX509CertificateRequestPkcs10V3::get_AttestPrivateKey method
IX509CertificateRequestPkcs10V3::get_ChallengePassword method
IX509CertificateRequestPkcs10V3::get_EncryptionAlgorithm method
IX509CertificateRequestPkcs10V3::get_EncryptionStrength method
IX509CertificateRequestPkcs10V3::get_NameValuePairs method
IX509CertificateRequestPkcs10V3::put_AttestationEncryptionCertificate method
IX509CertificateRequestPkcs10V3::put_AttestPrivateKey method
IX509CertificateRequestPkcs10V3::put_ChallengePassword method
IX509CertificateRequestPkcs10V3::put_EncryptionAlgorithm method
IX509CertificateRequestPkcs10V3::put_EncryptionStrength method
IX509CertificateRequestPkcs7 interface
Overview
IX509CertificateRequestPkcs7::get_RequesterName method
IX509CertificateRequestPkcs7::get_SignerCertificate method
IX509CertificateRequestPkcs7::InitializeDecode method
IX509CertificateRequestPkcs7::InitializeFromCertificate method
IX509CertificateRequestPkcs7::InitializeFromInnerRequest method
IX509CertificateRequestPkcs7::InitializeFromTemplateName method
IX509CertificateRequestPkcs7::put_RequesterName method
IX509CertificateRequestPkcs7::put_SignerCertificate method
IX509CertificateRequestPkcs7V2 interface
Overview
IX509CertificateRequestPkcs7V2::CheckCertificateSignature method
IX509CertificateRequestPkcs7V2::get_PolicyServer method
IX509CertificateRequestPkcs7V2::get_Template method
IX509CertificateRequestPkcs7V2::InitializeFromTemplate method
IX509CertificateTemplate interface
Overview
IX509CertificateTemplate::get_Property method
IX509CertificateTemplates interface
Overview
IX509CertificateTemplates::Add method
IX509CertificateTemplates::Clear method
IX509CertificateTemplates::get__NewEnum method
IX509CertificateTemplates::get_Count method
IX509CertificateTemplates::get_ItemByName method
IX509CertificateTemplates::get_ItemByOid method
IX509CertificateTemplates::Remove method
IX509CertificateTemplateWritable interface
Overview
IX509CertificateTemplateWritable::Commit method
IX509CertificateTemplateWritable::get_Property method
 IX509CertificateTemplateWritable::get_Template method
IX509CertificateTemplateWritable::Initialize method
IX509CertificateTemplateWritable::put_Property method
IX509EndorsementKey interface
Overview
IX509EndorsementKey::AddCertificate method
IX509EndorsementKey::Close method
IX509EndorsementKey::ExportPublicKey method
IX509EndorsementKey::get_Length method
IX509EndorsementKey::get_Opened method
IX509EndorsementKey::get_ProviderName method
IX509EndorsementKey::GetCertificateCount method
IX509EndorsementKey::Open method
IX509EndorsementKey::put_ProviderName method
IX509EndorsementKey::RemoveCertificate method
IX509Enrollment interface
Overview
IX509Enrollment::CreatePFX method
IX509Enrollment::CreateRequest method
IX509Enrollment::Enroll method
IX509Enrollment::get_CAConfigString method
IX509Enrollment::get_Certificate method
IX509Enrollment::get_CertificateDescription method
IX509Enrollment::get_CertificateFriendlyName method
IX509Enrollment::get_EnrollmentContext method
IX509Enrollment::get_NameValuePairs method
IX509Enrollment::get_ParentWindow method
IX509Enrollment::get_Request method
IX509Enrollment::get_RequestId method
IX509Enrollment::get_Response method
IX509Enrollment::get_Silent method
IX509Enrollment::get_Status method
 IX509Enrollment::Initialize method
IX509Enrollment::InitializeFromRequest method
IX509Enrollment::InitializeFromTemplateName method
IX509Enrollment::InstallResponse method
IX509Enrollment::put_CertificateDescription method
IX509Enrollment::put_CertificateFriendlyName method
IX509Enrollment::put_ParentWindow method
IX509Enrollment::put_Silent method
IX509Enrollment2 interface
Overview
IX509Enrollment2::get_PolicyServer method
IX509Enrollment2::get_RequestIdString method
IX509Enrollment2::get_Template method
IX509Enrollment2::InitializeFromTemplate method
IX509Enrollment2::InstallResponse2 method
IX509EnrollmentHelper interface
Overview
IX509EnrollmentHelper::AddEnrollmentServer method
IX509EnrollmentHelper::AddPolicyServer method
IX509EnrollmentHelper::Enroll method
IX509EnrollmentHelper::Initialize method
IX509EnrollmentPolicyServer interface
Overview
IX509EnrollmentPolicyServer::Export method
IX509EnrollmentPolicyServer::get_Cost method
IX509EnrollmentPolicyServer::GetAllowUnTrustedCA method
IX509EnrollmentPolicyServer::GetAuthFlags method
IX509EnrollmentPolicyServer::GetCacheDir method
IX509EnrollmentPolicyServer::GetCachePath method
IX509EnrollmentPolicyServer::GetCAs method
IX509EnrollmentPolicyServer::GetCAsForTemplate method
IX509EnrollmentPolicyServer::GetCustomOids method
 IX509EnrollmentPolicyServer::GetFriendlyName method
IX509EnrollmentPolicyServer::GetIsDefaultCEP method
IX509EnrollmentPolicyServer::GetLastUpdateTime method
IX509EnrollmentPolicyServer::GetNextUpdateTime method
IX509EnrollmentPolicyServer::GetPolicyServerId method
IX509EnrollmentPolicyServer::GetPolicyServerUrl method
IX509EnrollmentPolicyServer::GetTemplates method
IX509EnrollmentPolicyServer::GetUseClientId method
IX509EnrollmentPolicyServer::Initialize method
IX509EnrollmentPolicyServer::InitializeImport method
IX509EnrollmentPolicyServer::LoadPolicy method
IX509EnrollmentPolicyServer::put_Cost method
IX509EnrollmentPolicyServer::QueryChanges method
IX509EnrollmentPolicyServer::SetCredential method
IX509EnrollmentPolicyServer::Validate method
IX509EnrollmentStatus interface
Overview
IX509EnrollmentStatus::AppendText method
IX509EnrollmentStatus::get_Display method
IX509EnrollmentStatus::get_Error method
IX509EnrollmentStatus::get_ErrorText method
IX509EnrollmentStatus::get_Selected method
IX509EnrollmentStatus::get_Status method
IX509EnrollmentStatus::get_Text method
IX509EnrollmentStatus::put_Display method
IX509EnrollmentStatus::put_Error method
IX509EnrollmentStatus::put_Selected method
IX509EnrollmentStatus::put_Status method
IX509EnrollmentStatus::put_Text method
IX509EnrollmentWebClassFactory interface
Overview
IX509EnrollmentWebClassFactory::CreateObject method
IX509Extension interface
Overview
IX509Extension::get_Critical method
IX509Extension::get_ObjectId method
IX509Extension::get_RawData method
IX509Extension::Initialize method
IX509Extension::put_Critical method
IX509ExtensionAlternativeNames interface
Overview
IX509ExtensionAlternativeNames::get_AlternativeNames method
IX509ExtensionAlternativeNames::InitializeDecode method
IX509ExtensionAlternativeNames::InitializeEncode method
IX509ExtensionAuthorityKeyIdentifier interface
Overview
IX509ExtensionAuthorityKeyIdentifier::get_AuthorityKeyIdentifier method
IX509ExtensionAuthorityKeyIdentifier::InitializeDecode method
IX509ExtensionAuthorityKeyIdentifier::InitializeEncode method
IX509ExtensionBasicConstraints interface
Overview
IX509ExtensionBasicConstraints::get_IsCA method
IX509ExtensionBasicConstraints::get_PathLenConstraint method
IX509ExtensionBasicConstraints::InitializeDecode method
IX509ExtensionBasicConstraints::InitializeEncode method
IX509ExtensionCertificatePolicies interface
Overview
IX509ExtensionCertificatePolicies::get_Policies method
IX509ExtensionCertificatePolicies::InitializeDecode method
IX509ExtensionCertificatePolicies::InitializeEncode method
IX509ExtensionEnhancedKeyUsage interface
Overview
IX509ExtensionEnhancedKeyUsage::get_EnhancedKeyUsage method
IX509ExtensionEnhancedKeyUsage::InitializeDecode method
 IX509ExtensionEnhancedKeyUsage::InitializeEncode method
IX509ExtensionKeyUsage interface
Overview
IX509ExtensionKeyUsage::get_KeyUsage method
IX509ExtensionKeyUsage::InitializeDecode method
IX509ExtensionKeyUsage::InitializeEncode method
IX509ExtensionMSApplicationPolicies interface
Overview
IX509ExtensionMSApplicationPolicies::get_Policies method
IX509ExtensionMSApplicationPolicies::InitializeDecode method
IX509ExtensionMSApplicationPolicies::InitializeEncode method
IX509Extensions interface
Overview
IX509Extensions::Add method
IX509Extensions::AddRange method
IX509Extensions::Clear method
IX509Extensions::get__NewEnum method
IX509Extensions::get_Count method
IX509Extensions::get_IndexByObjectId method
IX509Extensions::Remove method
IX509ExtensionSmimeCapabilities interface
Overview
IX509ExtensionSmimeCapabilities::get_SmimeCapabilities method
IX509ExtensionSmimeCapabilities::InitializeDecode method
IX509ExtensionSmimeCapabilities::InitializeEncode method
IX509ExtensionSubjectKeyIdentifier interface
Overview
IX509ExtensionSubjectKeyIdentifier::get_SubjectKeyIdentifier method
IX509ExtensionSubjectKeyIdentifier::InitializeDecode method
IX509ExtensionSubjectKeyIdentifier::InitializeEncode method
IX509ExtensionTemplate interface
Overview
 IX509ExtensionTemplate::get_MajorVersion method
IX509ExtensionTemplate::get_MinorVersion method
IX509ExtensionTemplate::get_TemplateOid method
IX509ExtensionTemplate::InitializeDecode method
IX509ExtensionTemplate::InitializeEncode method
IX509ExtensionTemplateName interface
Overview
IX509ExtensionTemplateName::get_TemplateName method
IX509ExtensionTemplateName::InitializeDecode method
IX509ExtensionTemplateName::InitializeEncode method
IX509MachineEnrollmentFactory interface
Overview
IX509MachineEnrollmentFactory::CreateObject method
IX509NameValuePair interface
Overview
IX509NameValuePair::get_Name method
IX509NameValuePair::get_Value method
IX509NameValuePair::Initialize method
IX509NameValuePairs interface
Overview
IX509NameValuePairs::Add method
IX509NameValuePairs::Clear method
IX509NameValuePairs::get__NewEnum method
IX509NameValuePairs::get_Count method
IX509NameValuePairs::Remove method
IX509PolicyServerListManager interface
Overview
IX509PolicyServerListManager::Add method
IX509PolicyServerListManager::Clear method
IX509PolicyServerListManager::get__NewEnum method
IX509PolicyServerListManager::get_Count method
IX509PolicyServerListManager::Initialize method
 IX509PolicyServerListManager::Remove method
IX509PolicyServerUrl interface
Overview
IX509PolicyServerUrl::get_AuthFlags method
IX509PolicyServerUrl::get_Cost method
IX509PolicyServerUrl::get_Default method
IX509PolicyServerUrl::get_Flags method
IX509PolicyServerUrl::get_Url method
IX509PolicyServerUrl::GetStringProperty method
IX509PolicyServerUrl::Initialize method
IX509PolicyServerUrl::put_AuthFlags method
IX509PolicyServerUrl::put_Cost method
IX509PolicyServerUrl::put_Default method
IX509PolicyServerUrl::put_Flags method
IX509PolicyServerUrl::put_Url method
IX509PolicyServerUrl::RemoveFromRegistry method
IX509PolicyServerUrl::SetStringProperty method
IX509PolicyServerUrl::UpdateRegistry method
IX509PrivateKey interface
Overview
IX509PrivateKey::Close method
IX509PrivateKey::Create method
IX509PrivateKey::Delete method
IX509PrivateKey::Export method
IX509PrivateKey::ExportPublicKey method
IX509PrivateKey::get_Algorithm method
IX509PrivateKey::get_Certificate method
IX509PrivateKey::get_ContainerName method
IX509PrivateKey::get_ContainerNamePrefix method
IX509PrivateKey::get_CspInformations method
IX509PrivateKey::get_CspStatus method
IX509PrivateKey::get_DefaultContainer method
IX509PrivateKey::get_Description method
IX509PrivateKey::get_Existing method
IX509PrivateKey::get_ExportPolicy method
IX509PrivateKey::get_FriendlyName method
IX509PrivateKey::get_KeyProtection method
IX509PrivateKey::get_KeySpec method
IX509PrivateKey::get_KeyUsage method
IX509PrivateKey::get_LegacyCsp method
IX509PrivateKey::get_Length method
IX509PrivateKey::get_MachineContext method
IX509PrivateKey::get_Opened method
IX509PrivateKey::get_ParentWindow method
IX509PrivateKey::get_ProviderName method
IX509PrivateKey::get_ProviderType method
IX509PrivateKey::get_ReaderName method
IX509PrivateKey::get_SecurityDescriptor method
IX509PrivateKey::get_Silent method
IX509PrivateKey::get_UIContextMessage method
IX509PrivateKey::get_UniqueContainerName method
IX509PrivateKey::Import method
IX509PrivateKey::Open method
IX509PrivateKey::put_Algorithm method
IX509PrivateKey::put_Certificate method
IX509PrivateKey::put_ContainerName method
IX509PrivateKey::put_ContainerNamePrefix method
IX509PrivateKey::put_CspInformations method
IX509PrivateKey::put_CspStatus method
IX509PrivateKey::put_Description method
IX509PrivateKey::put_Existing method
IX509PrivateKey::put_ExportPolicy method
IX509PrivateKey::put_FriendlyName method
IX509PrivateKey::put_KeyProtection method
 IX509PrivateKey::put_KeySpec method
IX509PrivateKey::put_KeyUsage method
IX509PrivateKey::put_LegacyCsp method
IX509PrivateKey::put_Length method
IX509PrivateKey::put_MachineContext method
IX509PrivateKey::put_ParentWindow method
IX509PrivateKey::put_Pin method
IX509PrivateKey::put_ProviderName method
IX509PrivateKey::put_ProviderType method
IX509PrivateKey::put_ReaderName method
IX509PrivateKey::put_SecurityDescriptor method
IX509PrivateKey::put_Silent method
IX509PrivateKey::put_UIContextMessage method
IX509PrivateKey::Verify method
IX509PublicKey interface
Overview
IX509PublicKey::ComputeKeyIdentifier method
IX509PublicKey::get_Algorithm method
IX509PublicKey::get_EncodedKey method
IX509PublicKey::get_EncodedParameters method
IX509PublicKey::get_Length method
IX509PublicKey::Initialize method
IX509PublicKey::InitializeFromEncodedPublicKeyInfo method
IX509SCEPEnrollment interface
Overview
IX509SCEPEnrollment::CreateRequestMessage method
IX509SCEPEnrollment::CreateRetrieveCertificateMessage method
IX509SCEPEnrollment::CreateRetrievePendingMessage method
IX509SCEPEnrollment::DeleteRequest method
IX509SCEPEnrollment::get_Certificate method
IX509SCEPEnrollment::get_CertificateFriendlyName method
IX509SCEPEnrollment::get_FailInfo method
 IX509SCEPEnrollment::get_OldCertificate method
IX509SCEPEnrollment::get_Request method
IX509SCEPEnrollment::get_SignerCertificate method
IX509SCEPEnrollment::get_Status method
IX509SCEPEnrollment::get_TransactionId method
IX509SCEPEnrollment::Initialize method
IX509SCEPEnrollment::InitializeForPending method
IX509SCEPEnrollment::ProcessResponseMessage method
IX509SCEPEnrollment::put_CertificateFriendlyName method
IX509SCEPEnrollment::put_OldCertificate method
IX509SCEPEnrollment::put_ServerCapabilities method
IX509SCEPEnrollment::put_SignerCertificate method
IX509SCEPEnrollment::put_Silent method
IX509SCEPEnrollment::put_TransactionId method
IX509SignatureInformation interface
Overview
IX509SignatureInformation::get_AlternateSignatureAlgorithm method
IX509SignatureInformation::get_AlternateSignatureAlgorithmSet method
IX509SignatureInformation::get_HashAlgorithm method
IX509SignatureInformation::get_NullSigned method
IX509SignatureInformation::get_Parameters method
IX509SignatureInformation::get_PublicKeyAlgorithm method
IX509SignatureInformation::GetSignatureAlgorithm method
IX509SignatureInformation::put_AlternateSignatureAlgorithm method
IX509SignatureInformation::put_HashAlgorithm method
IX509SignatureInformation::put_NullSigned method
IX509SignatureInformation::put_Parameters method
IX509SignatureInformation::put_PublicKeyAlgorithm method
IX509SignatureInformation::SetDefaultValues method
KeyIdentifierHashAlgorithm enumeration
ObjectIdGroupId enumeration
ObjectIdPublicKeyFlags enumeration
 PFXExportOptions enumeration
Pkcs10AllowedSignatureTypes enumeration
PolicyQualifierType enumeration
PolicyServerUrlFlags enumeration
PolicyServerUrlPropertyID enumeration
RequestClientInfoClientId enumeration
WebEnrollmentFlags enumeration
WebSecurityLevel enumeration
X500NameFlags enumeration
X509CertificateEnrollmentContext enumeration
X509CertificateTemplateEnrollmentFlag enumeration
X509CertificateTemplateGeneralFlag enumeration
X509CertificateTemplatePrivateKeyFlag enumeration
X509CertificateTemplateSubjectNameFlag enumeration
X509EnrollmentPolicyExportFlags enumeration
X509EnrollmentPolicyLoadOption enumeration
X509KeySpec enumeration
X509KeyUsageFlags enumeration
X509PrivateKeyExportFlags enumeration
X509PrivateKeyProtection enumeration
X509PrivateKeyUsageFlags enumeration
X509PrivateKeyVerify enumeration
X509ProviderType enumeration
X509RequestInheritOptions enumeration
X509RequestType enumeration
Certexit.h
Overview
ICertExit interface
Overview
ICertExit::GetDescription method
ICertExit::Initialize method
ICertExit::Notify method
 ICertExit2 interface
Overview
ICertExit2::GetManageModule method
Certif.h
Overview
ICertServerExit interface
Overview
ICertServerExit::EnumerateAttributes method
ICertServerExit::EnumerateAttributesClose method
ICertServerExit::EnumerateAttributesSetup method
ICertServerExit::EnumerateExtensions method
ICertServerExit::EnumerateExtensionsClose method
ICertServerExit::EnumerateExtensionsSetup method
ICertServerExit::GetCertificateExtension method
ICertServerExit::GetCertificateExtensionFlags method
ICertServerExit::GetCertificateProperty method
ICertServerExit::GetRequestAttribute method
ICertServerExit::GetRequestProperty method
ICertServerExit::SetContext method
ICertServerPolicy interface
Overview
ICertServerPolicy::EnumerateAttributes method
ICertServerPolicy::EnumerateAttributesClose method
ICertServerPolicy::EnumerateAttributesSetup method
ICertServerPolicy::EnumerateExtensions method
ICertServerPolicy::EnumerateExtensionsClose method
ICertServerPolicy::EnumerateExtensionsSetup method
ICertServerPolicy::GetCertificateExtension method
ICertServerPolicy::GetCertificateExtensionFlags method
ICertServerPolicy::GetCertificateProperty method
ICertServerPolicy::GetRequestAttribute method
ICertServerPolicy::GetRequestProperty method
 ICertServerPolicy::SetCertificateExtension method
ICertServerPolicy::SetCertificateProperty method
ICertServerPolicy::SetContext method
Certmod.h
Overview
ICertManageModule interface
Overview
ICertManageModule::Configure method
ICertManageModule::GetProperty method
ICertManageModule::SetProperty method
Certpol.h
Overview
ICertPolicy interface
Overview
ICertPolicy::GetDescription method
ICertPolicy::Initialize method
ICertPolicy::ShutDown method
ICertPolicy::VerifyRequest method
ICertPolicy2 interface
Overview
ICertPolicy2::GetManageModule method
INDESPolicy interface
Overview
INDESPolicy::GenerateChallenge method
INDESPolicy::Initialize method
INDESPolicy::Notify method
INDESPolicy::Uninitialize method
INDESPolicy::VerifyRequest method
X509SCEPDisposition enumeration
X509SCEPFailInfo enumeration
Certpoleng.h
Overview
 PstAcquirePrivateKey function
PstGetCertificates function
PstGetTrustAnchors function
PstGetUserNameForCertificate function
PstMapCertificate function
PstValidate function
Certsrv.h
Overview
ENUM_CATYPES enumeration
Certview.h
Overview
ICertView interface
Overview
ICertView::EnumCertViewColumn method
ICertView::GetColumnCount method
ICertView::OpenConnection method
ICertView::OpenView method
ICertView::SetRestriction method
ICertView::SetResultColumn method
ICertView::SetResultColumnCount method
ICertView2 interface
Overview
ICertView2::SetTable method
IEnumCERTVIEWATTRIBUTE interface
Overview
IEnumCERTVIEWATTRIBUTE::Clone method
IEnumCERTVIEWATTRIBUTE::GetName method
IEnumCERTVIEWATTRIBUTE::GetValue method
IEnumCERTVIEWATTRIBUTE::Next method
IEnumCERTVIEWATTRIBUTE::Reset method
IEnumCERTVIEWATTRIBUTE::Skip method
IEnumCERTVIEWCOLUMN interface
 Overview
IEnumCERTVIEWCOLUMN::Clone method
IEnumCERTVIEWCOLUMN::GetDisplayName method
IEnumCERTVIEWCOLUMN::GetMaxLength method
IEnumCERTVIEWCOLUMN::GetName method
IEnumCERTVIEWCOLUMN::GetType method
IEnumCERTVIEWCOLUMN::GetValue method
IEnumCERTVIEWCOLUMN::IsIndexed method
IEnumCERTVIEWCOLUMN::Next method
IEnumCERTVIEWCOLUMN::Reset method
IEnumCERTVIEWCOLUMN::Skip method
IEnumCERTVIEWEXTENSION interface
Overview
IEnumCERTVIEWEXTENSION::Clone method
IEnumCERTVIEWEXTENSION::GetFlags method
IEnumCERTVIEWEXTENSION::GetName method
IEnumCERTVIEWEXTENSION::GetValue method
IEnumCERTVIEWEXTENSION::Next method
IEnumCERTVIEWEXTENSION::Reset method
IEnumCERTVIEWEXTENSION::Skip method
IEnumCERTVIEWROW interface
Overview
IEnumCERTVIEWROW::EnumCertViewAttribute method
IEnumCERTVIEWROW::EnumCertViewColumn method
IEnumCERTVIEWROW::EnumCertViewExtension method
IEnumCERTVIEWROW::Next method
IEnumCERTVIEWROW::Reset method
IEnumCERTVIEWROW::Skip method
Credssp.h
Overview
CREDSPP_SUBMIT_TYPE enumeration
CREDSSP_CRED structure
 SecPkgContext_ClientCreds structure
Cryptdlg.h
Overview
CERT_SELECT_STRUCT_A structure
CERT_SELECT_STRUCT_W structure
CERT_VIEWPROPERTIES_STRUCT_A structure
CERT_VIEWPROPERTIES_STRUCT_W structure
CertModifyCertificatesToTrust function
CertSelectCertificateA function
CertSelectCertificateW function
CertViewPropertiesA function
CertViewPropertiesW function
CTL_MODIFY_REQUEST structure
GetFriendlyNameOfCertA function
GetFriendlyNameOfCertW function
PFNCMFILTERPROC callback function
PFNCMHOOKPROC callback function
Cryptuiapi.h
Overview
CERT_SELECTUI_INPUT structure
CertSelectionGetSerializedBlob function
CRYPTUI_CERT_MGR_STRUCT structure
CRYPTUI_INITDIALOG_STRUCT structure
CRYPTUI_VIEWCERTIFICATE_STRUCTA structure
CRYPTUI_VIEWCERTIFICATE_STRUCTW structure
CRYPTUI_WIZ_DIGITAL_SIGN_BLOB_INFO structure
CRYPTUI_WIZ_DIGITAL_SIGN_CERT_PVK_INFO structure
CRYPTUI_WIZ_DIGITAL_SIGN_CONTEXT structure
CRYPTUI_WIZ_DIGITAL_SIGN_EXTENDED_INFO structure
CRYPTUI_WIZ_DIGITAL_SIGN_INFO structure
CRYPTUI_WIZ_DIGITAL_SIGN_PVK_FILE_INFO structure
CRYPTUI_WIZ_DIGITAL_SIGN_STORE_INFO structure
 CRYPTUI_WIZ_EXPORT_CERTCONTEXT_INFO structure
CRYPTUI_WIZ_EXPORT_INFO structure
CRYPTUI_WIZ_IMPORT_SRC_INFO structure
CryptUIDlgCertMgr function
CryptUIDlgSelectCertificateFromStore function
CryptUIDlgViewCertificateA function
CryptUIDlgViewCertificateW function
CryptUIDlgViewContext function
CryptUIWizDigitalSign function
CryptUIWizExport function
CryptUIWizFreeDigitalSignContext function
CryptUIWizImport function
PFNCFILTERPROC callback function
Cryptxml.h
Overview
CRYPT_XML_ALGORITHM structure
CRYPT_XML_ALGORITHM_INFO structure
CRYPT_XML_BLOB structure
CRYPT_XML_CHARSET enumeration
CRYPT_XML_CRYPTOGRAPHIC_INTERFACE structure
CRYPT_XML_DATA_BLOB structure
CRYPT_XML_DATA_PROVIDER structure
CRYPT_XML_DOC_CTXT structure
CRYPT_XML_ISSUER_SERIAL structure
CRYPT_XML_KEY_DSA_KEY_VALUE structure
CRYPT_XML_KEY_ECDSA_KEY_VALUE structure
CRYPT_XML_KEY_INFO structure
CRYPT_XML_KEY_INFO_ITEM structure
CRYPT_XML_KEY_RSA_KEY_VALUE structure
CRYPT_XML_KEY_VALUE structure
CRYPT_XML_KEYINFO_PARAM structure
CRYPT_XML_KEYINFO_SPEC enumeration
CRYPT_XML_OBJECT structure
CRYPT_XML_PROPERTY structure
CRYPT_XML_PROPERTY_ID enumeration
CRYPT_XML_REFERENCE structure
CRYPT_XML_REFERENCES structure
CRYPT_XML_SIGNATURE structure
CRYPT_XML_SIGNED_INFO structure
CRYPT_XML_STATUS structure
CRYPT_XML_TRANSFORM_CHAIN_CONFIG structure
CRYPT_XML_TRANSFORM_INFO structure
CRYPT_XML_X509DATA structure
CRYPT_XML_X509DATA_ITEM structure
CryptXmlAddObject function
CryptXmlClose function
CryptXmlCreateReference function
CryptXmlDigestReference function
CryptXmlDllCloseDigest callback function
CryptXmlDllCreateDigest callback function
CryptXmlDllCreateKey callback function
CryptXmlDllDigestData callback function
CryptXmlDllEncodeAlgorithm callback function
CryptXmlDllEncodeKeyValue callback function
CryptXmlDllFinalizeDigest callback function
CryptXmlDllGetAlgorithmInfo callback function
CryptXmlDllGetInterface callback function
CryptXmlDllSignData callback function
CryptXmlDllVerifySignature callback function
CryptXmlEncode function
CryptXmlGetAlgorithmInfo function
CryptXmlGetDocContext function
CryptXmlGetReference function
CryptXmlGetSignature function
 CryptXmlGetStatus function
CryptXmlGetTransforms function
CryptXmlImportPublicKey function
CryptXmlOpenToDecode function
CryptXmlOpenToEncode function
CryptXmlSetHMACSecret function
CryptXmlSign function
CryptXmlVerifySignature function
PFN_CRYPT_XML_CREATE_TRANSFORM callback function
PFN_CRYPT_XML_DATA_PROVIDER_CLOSE callback function
PFN_CRYPT_XML_DATA_PROVIDER_READ callback function
PFN_CRYPT_XML_ENUM_ALG_INFO callback function
PFN_CRYPT_XML_WRITE_CALLBACK callback function
Diagnosticdataquery.h
Overview
DdqCancelDiagnosticRecordOperation function
DdqCloseSession function
DdqCreateSession function
DdqExtractDiagnosticReport function
DdqFreeDiagnosticRecordLocaleTags function
DdqFreeDiagnosticRecordPage function
DdqFreeDiagnosticRecordProducerCategories function
DdqFreeDiagnosticRecordProducers function
DdqFreeDiagnosticReport function
DdqGetDiagnosticDataAccessLevelAllowed function
DdqGetDiagnosticRecordAtIndex function
DdqGetDiagnosticRecordBinaryDistribution function
DdqGetDiagnosticRecordCategoryAtIndex function
DdqGetDiagnosticRecordCategoryCount function
DdqGetDiagnosticRecordCount function
DdqGetDiagnosticRecordLocaleTagAtIndex function
DdqGetDiagnosticRecordLocaleTagCount function
 DdqGetDiagnosticRecordLocaleTags function
DdqGetDiagnosticRecordPage function
DdqGetDiagnosticRecordPayload function
DdqGetDiagnosticRecordProducerAtIndex function
DdqGetDiagnosticRecordProducerCategories function
DdqGetDiagnosticRecordProducerCount function
DdqGetDiagnosticRecordProducers function
DdqGetDiagnosticRecordStats function
DdqGetDiagnosticRecordSummary function
DdqGetDiagnosticRecordTagDistribution function
DdqGetDiagnosticReport function
DdqGetDiagnosticReportAtIndex function
DdqGetDiagnosticReportCount function
DdqGetDiagnosticReportStoreReportCount function
DdqGetSessionAccessLevel function
DdqGetTranscriptConfiguration function
DdqIsDiagnosticRecordSampledIn function
DdqSetTranscriptConfiguration function
Diagnosticdataquerytypes.h
Overview
DdqAccessLevel enumeration
DIAGNOSTIC_DATA_EVENT_BINARY_STATS structure
DIAGNOSTIC_DATA_EVENT_CATEGORY_DESCRIPTION structure
DIAGNOSTIC_DATA_EVENT_PRODUCER_DESCRIPTION structure
DIAGNOSTIC_DATA_EVENT_TAG_DESCRIPTION structure
DIAGNOSTIC_DATA_EVENT_TAG_STATS structure
DIAGNOSTIC_DATA_EVENT_TRANSCRIPT_CONFIGURATION structure
DIAGNOSTIC_DATA_GENERAL_STATS structure
DIAGNOSTIC_DATA_RECORD structure
DIAGNOSTIC_DATA_SEARCH_CRITERIA structure
DIAGNOSTIC_REPORT_DATA structure
DIAGNOSTIC_REPORT_PARAMETER structure
 DIAGNOSTIC_REPORT_SIGNATURE structure
Dpapi.h
Overview
CRYPT_INTEGER_BLOB structure
CRYPTPROTECT_PROMPTSTRUCT structure
CryptProtectData function
CryptProtectMemory function
CryptUnprotectData function
CryptUnprotectMemory function
CryptUpdateProtectedState function
Dssec.h
Overview
DSCreateISecurityInfoObject function
DSCreateISecurityInfoObjectEx function
DSCreateSecurityPage function
DSEditSecurity function
Iads.h
Overview
Identitycommon.h
Overview
IDENTITY_TYPE enumeration
Identityprovider.h
Overview
IAssociatedIdentityProvider interface
Overview
IAssociatedIdentityProvider::AssociateIdentity method
IAssociatedIdentityProvider::ChangeCredential method
IAssociatedIdentityProvider::DisassociateIdentity method
IConnectedIdentityProvider interface
Overview
IConnectedIdentityProvider::ConnectIdentity method
IConnectedIdentityProvider::DisconnectIdentity method
 IConnectedIdentityProvider::GetUrl method
IIdentityAdvise interface
Overview
IIdentityAdvise::IdentityUpdated method
IIdentityProvider interface
Overview
IIdentityProvider::Advise method
IIdentityProvider::Create method
IIdentityProvider::Delete method
IIdentityProvider::FindByUniqueID method
IIdentityProvider::GetIdentityEnum method
IIdentityProvider::GetProviderPropertyStore method
IIdentityProvider::Import method
IIdentityProvider::UnAdvise method
Identitystore.h
Overview
IIdentityStore interface
Overview
IIdentityStore::AddToCache method
IIdentityStore::ConvertToSid method
IIdentityStore::EnumerateIdentities method
IIdentityStore::GetAt method
IIdentityStore::GetCount method
IIdentityStore::Reset method
Keycredmgr.h
Overview
KeyCredentialManagerFreeInformation function
KeyCredentialManagerGetInformation function
KeyCredentialManagerGetOperationErrorStates function
KeyCredentialManagerInfo structure
KeyCredentialManagerOperationErrorStates enumeration
KeyCredentialManagerOperationType enumeration
 KeyCredentialManagerShowUIOperation function
Lmaccess.h
Overview
MSA_INFO_0 structure
MSA_INFO_LEVEL enumeration
MSA_INFO_STATE enumeration
NetAddServiceAccount function
NetEnumerateServiceAccounts function
NetIsServiceAccount function
NetQueryServiceAccount function
NetRemoveServiceAccount function
Lsalookup.h
Overview
LSA_OBJECT_ATTRIBUTES structure
LSA_REFERENCED_DOMAIN_LIST structure
LSA_STRING structure
LSA_TRANSLATED_NAME structure
LSA_TRANSLATED_SID2 structure
LSA_TRUST_INFORMATION structure
LSA_UNICODE_STRING structure
POLICY_ACCOUNT_DOMAIN_INFO structure
POLICY_DNS_DOMAIN_INFO structure
Mmcobj.h
Overview
Mscat.h
Overview
CATALOG_INFO structure
CryptCATAdminAcquireContext function
CryptCATAdminAcquireContext2 function
CryptCATAdminAddCatalog function
CryptCATAdminCalcHashFromFileHandle function
CryptCATAdminCalcHashFromFileHandle2 function
 CryptCATAdminEnumCatalogFromHash function
CryptCATAdminReleaseCatalogContext function
CryptCATAdminReleaseContext function
CryptCATAdminRemoveCatalog function
CryptCATAdminResolveCatalogPath function
CRYPTCATATTRIBUTE structure
CryptCATCatalogInfoFromContext function
CRYPTCATCDF structure
CryptCATCDFClose function
CryptCATCDFEnumCatAttributes function
CryptCATCDFOpen function
CryptCATClose function
CryptCATEnumerateAttr function
CryptCATEnumerateCatAttr function
CryptCATEnumerateMember function
CryptCATGetAttrInfo function
CryptCATGetMemberInfo function
CryptCATHandleFromStore function
CRYPTCATMEMBER structure
CryptCATOpen function
CryptCATPersistStore function
CryptCATPutAttrInfo function
CryptCATPutCatAttrInfo function
CryptCATPutMemberInfo function
CRYPTCATSTORE structure
CryptCATStoreFromHandle function
IsCatalogFile function
PFN_CDF_PARSE_ERROR_CALLBACK callback function
Mssip.h
Overview
CryptSIPAddProvider function
CryptSIPCreateIndirectData function
 CryptSIPGetCaps function
CryptSIPGetSignedDataMsg function
CryptSIPLoad function
CryptSIPPutSignedDataMsg function
CryptSIPRemoveProvider function
CryptSIPRemoveSignedDataMsg function
CryptSIPRetrieveSubjectGuid function
CryptSIPRetrieveSubjectGuidForCatalogFile function
CryptSIPVerifyIndirectData function
MS_ADDINFO_BLOB structure
MS_ADDINFO_CATALOGMEMBER structure
MS_ADDINFO_FLAT structure
pCryptSIPGetCaps callback function
pfnIsFileSupported callback function
pfnIsFileSupportedName callback function
SIP_ADD_NEWPROVIDER structure
SIP_CAP_SET_V2 structure
SIP_CAP_SET_V3 structure
SIP_DISPATCH_INFO structure
SIP_INDIRECT_DATA structure
SIP_SUBJECTINFO structure
Namedpipeapi.h
Overview
ImpersonateNamedPipeClient function
Ncrypt.h
Overview
NCRYPT_ALLOC_PARA structure
NCRYPT_KEY_BLOB_HEADER structure
NCRYPT_SUPPORTED_LENGTHS structure
NCRYPT_UI_POLICY structure
NCryptAlgorithmName structure
NCryptCreateClaim function
 NCryptCreatePersistedKey function
NCryptDecrypt function
NCryptDeleteKey function
NCryptDeriveKey function
NCryptEncrypt function
NCryptEnumAlgorithms function
NCryptEnumKeys function
NCryptEnumStorageProviders function
NCryptExportKey function
NCryptFinalizeKey function
NCryptFreeBuffer function
NCryptFreeObject function
NCryptGetProperty function
NCryptImportKey function
NCryptIsAlgSupported function
NCryptIsKeyHandle function
NCryptKeyDerivation function
NCryptKeyName structure
NCryptNotifyChangeKey function
NCryptOpenKey function
NCryptOpenStorageProvider function
NCryptProviderName structure
NCryptSecretAgreement function
NCryptSetProperty function
NCryptSignHash function
NCryptTranslateHandle function
NCryptVerifyClaim function
NCryptVerifySignature function
Ncryptprotect.h
Overview
NCRYPT_PROTECT_STREAM_INFO structure
NCryptCloseProtectionDescriptor function
 NCryptCreateProtectionDescriptor function
NCryptGetProtectionDescriptorInfo function
NCryptProtectSecret function
NCryptQueryProtectionDescriptorName function
NCryptRegisterProtectionDescriptorName function
NCryptStreamClose function
NCryptStreamOpenToProtect function
NCryptStreamOpenToUnprotect function
NCryptStreamOpenToUnprotectEx function
NCryptStreamUpdate function
NCryptUnprotectSecret function
PFNCryptStreamOutputCallback callback function
Npapi.h
Overview
AddConnectNotify function
CancelConnectNotify function
NOTIFYADD structure
NOTIFYCANCEL structure
NOTIFYINFO structure
NPAddConnection function
NPAddConnection3 function
NPCancelConnection function
NPCloseEnum function
NPDeviceMode function
NPDirectoryNotify function
NPEnumResource function
NPFMXEditPerm function
NPFMXGetPermCaps function
NPFMXGetPermHelp function
NPFormatNetworkName function
NPGetCaps function
NPGetConnection function
 NPGetConnection3 function
NPGetConnectionPerformance function
NPGetDirectoryType function
NPGetPropertyText function
NPGetResourceInformation function
NPGetResourceParent function
NPGetUniversalName function
NPGetUser function
NPLogonNotify function
NPOpenEnum function
NPPasswordChangeNotify function
NPPropertyDialog function
NPSearchDialog function
WNetSetLastErrorA function
WNetSetLastErrorW function
Ntlsa.h
Overview
CENTRAL_ACCESS_POLICY structure
CENTRAL_ACCESS_POLICY_ENTRY structure
LSA_FREE_LSA_HEAP callback function
LsaGetAppliedCAPIDs function
LsaLookupPrivilegeValue function
LsaQueryCAPs function
Ntsecapi.h
Overview
AUDIT_POLICY_INFORMATION structure
AuditComputeEffectivePolicyBySid function
AuditComputeEffectivePolicyByToken function
AuditEnumerateCategories function
AuditEnumeratePerUserPolicy function
AuditEnumerateSubCategories function
AuditFree function
AuditLookupCategoryGuidFromCategoryId function
AuditLookupCategoryIdFromCategoryGuid function
AuditLookupCategoryNameA function
AuditLookupCategoryNameW function
AuditLookupSubCategoryNameA function
AuditLookupSubCategoryNameW function
AuditQueryGlobalSaclA function
AuditQueryGlobalSaclW function
AuditQueryPerUserPolicy function
AuditQuerySecurity function
AuditQuerySystemPolicy function
AuditSetGlobalSaclA function
AuditSetGlobalSaclW function
AuditSetPerUserPolicy function
AuditSetSecurity function
AuditSetSystemPolicy function
DOMAIN_PASSWORD_INFORMATION structure
KERB_ADD_BINDING_CACHE_ENTRY_EX_REQUEST structure
KERB_ADD_BINDING_CACHE_ENTRY_REQUEST structure
KERB_ADD_CREDENTIALS_REQUEST structure
KERB_ADD_CREDENTIALS_REQUEST_EX structure
KERB_BINDING_CACHE_ENTRY_DATA structure
KERB_CERTIFICATE_HASHINFO structure
KERB_CERTIFICATE_INFO structure
KERB_CERTIFICATE_INFO_TYPE enumeration
KERB_CERTIFICATE_LOGON structure
KERB_CERTIFICATE_S4U_LOGON structure
KERB_CERTIFICATE_UNLOCK_LOGON structure
KERB_CHANGEPASSWORD_REQUEST structure
KERB_CLEANUP_MACHINE_PKINIT_CREDS_REQUEST structure
KERB_CRYPTO_KEY structure
KERB_EXTERNAL_NAME structure
KERB_EXTERNAL_TICKET structure
KERB_INTERACTIVE_LOGON structure
KERB_INTERACTIVE_PROFILE structure
KERB_INTERACTIVE_UNLOCK_LOGON structure
KERB_LOGON_SUBMIT_TYPE enumeration
KERB_PROFILE_BUFFER_TYPE enumeration
KERB_PROTOCOL_MESSAGE_TYPE enumeration
KERB_PURGE_BINDING_CACHE_REQUEST structure
KERB_PURGE_TKT_CACHE_REQUEST structure
KERB_QUERY_BINDING_CACHE_REQUEST structure
KERB_QUERY_BINDING_CACHE_RESPONSE structure
KERB_QUERY_DOMAIN_EXTENDED_POLICIES_REQUEST structure
KERB_QUERY_DOMAIN_EXTENDED_POLICIES_RESPONSE structure
KERB_QUERY_TKT_CACHE_REQUEST structure
KERB_QUERY_TKT_CACHE_RESPONSE structure
KERB_RETRIEVE_TKT_REQUEST structure
KERB_RETRIEVE_TKT_RESPONSE structure
KERB_S4U_LOGON structure
KERB_SMART_CARD_LOGON structure
KERB_SMART_CARD_UNLOCK_LOGON structure
KERB_TICKET_CACHE_INFO structure
KERB_TICKET_LOGON structure
KERB_TICKET_PROFILE structure
KERB_TICKET_UNLOCK_LOGON structure
LSA_AUTH_INFORMATION structure
LSA_ENUMERATION_INFORMATION structure
LSA_FOREST_TRUST_BINARY_DATA structure
LSA_FOREST_TRUST_COLLISION_INFORMATION structure
LSA_FOREST_TRUST_COLLISION_RECORD structure
LSA_FOREST_TRUST_COLLISION_RECORD_TYPE enumeration
LSA_FOREST_TRUST_DOMAIN_INFO structure
LSA_FOREST_TRUST_INFORMATION structure
LSA_FOREST_TRUST_RECORD structure
LSA_FOREST_TRUST_RECORD_TYPE enumeration
LSA_LAST_INTER_LOGON_INFO structure
LSA_TRANSLATED_SID structure
LsaAddAccountRights function
LsaCallAuthenticationPackage function
LsaClose function
LsaConnectUntrusted function
LsaCreateTrustedDomainEx function
LsaDeleteTrustedDomain function
LsaDeregisterLogonProcess function
LsaEnumerateAccountRights function
LsaEnumerateAccountsWithUserRight function
LsaEnumerateLogonSessions function
LsaEnumerateTrustedDomains function
LsaEnumerateTrustedDomainsEx function
LsaFreeMemory function
LsaFreeReturnBuffer function
LsaGetLogonSessionData function
LsaLogonUser function
LsaLookupAuthenticationPackage function
LsaLookupNames function
LsaLookupSids function
LsaLookupSids2 function
LsaNtStatusToWinError function
LsaOpenPolicy function
LsaOpenTrustedDomainByName function
LsaQueryDomainInformationPolicy function
LsaQueryForestTrustInformation function
LsaQueryInformationPolicy function
LsaQueryTrustedDomainInfo function
LsaQueryTrustedDomainInfoByName function
LsaRegisterLogonProcess function
LsaRegisterPolicyChangeNotification function
LsaRemoveAccountRights function
LsaRetrievePrivateData function
LsaSetDomainInformationPolicy function
LsaSetForestTrustInformation function
LsaSetInformationPolicy function
LsaSetTrustedDomainInfoByName function
LsaSetTrustedDomainInformation function
LsaStorePrivateData function
LsaUnregisterPolicyChangeNotification function
MSV1_0_INTERACTIVE_LOGON structure
MSV1_0_INTERACTIVE_PROFILE structure
MSV1_0_LM20_LOGON structure
MSV1_0_LM20_LOGON_PROFILE structure
MSV1_0_LOGON_SUBMIT_TYPE enumeration
MSV1_0_PROFILE_BUFFER_TYPE enumeration
MSV1_0_PROTOCOL_MESSAGE_TYPE enumeration
MSV1_0_SUBAUTH_LOGON structure
MSV1_0_SUBAUTH_REQUEST structure
MSV1_0_SUBAUTH_RESPONSE structure
MSV1_0_SUPPLEMENTAL_CREDENTIAL structure
PKU2U_CERT_BLOB structure
PKU2U_CERTIFICATE_S4U_LOGON structure
PKU2U_CREDUI_CONTEXT structure
PKU2U_LOGON_SUBMIT_TYPE enumeration
POLICY_AUDIT_EVENT_TYPE enumeration
POLICY_AUDIT_EVENTS_INFO structure
POLICY_AUDIT_SID_ARRAY structure
POLICY_DOMAIN_INFORMATION_CLASS enumeration
POLICY_INFORMATION_CLASS enumeration
POLICY_LSA_SERVER_ROLE enumeration
 POLICY_LSA_SERVER_ROLE_INFO structure
POLICY_MODIFICATION_INFO structure
POLICY_NOTIFICATION_INFORMATION_CLASS enumeration
POLICY_PRIMARY_DOMAIN_INFO structure
POLICY_SERVER_ENABLE_STATE enumeration
PSAM_INIT_NOTIFICATION_ROUTINE callback function
PSAM_PASSWORD_FILTER_ROUTINE callback function
PSAM_PASSWORD_NOTIFICATION_ROUTINE callback function
RtlDecryptMemory function
RtlEncryptMemory function
RtlGenRandom function
SECURITY_LOGON_SESSION_DATA structure
SECURITY_LOGON_TYPE enumeration
TRUSTED_DOMAIN_AUTH_INFORMATION structure
TRUSTED_DOMAIN_FULL_INFORMATION structure
TRUSTED_DOMAIN_INFORMATION_EX structure
TRUSTED_DOMAIN_NAME_INFO structure
TRUSTED_INFORMATION_CLASS enumeration
TRUSTED_PASSWORD_INFO structure
TRUSTED_POSIX_OFFSET_INFO structure
Ntsecpkg.h
Overview
CredFreeCredentialsFn callback function
CrediUnmarshalandDecodeStringFn callback function
CredMarshalTargetInfo function
CredReadDomainCredentialsFn callback function
CredReadFn callback function
CredWriteFn callback function
ENCRYPTED_CREDENTIALW structure
KspDeleteContextFn callback function
KspMakeSignatureFn callback function
KspVerifySignatureFn callback function
LSA_ADD_CREDENTIAL callback function
LSA_ALLOCATE_CLIENT_BUFFER callback function
LSA_ALLOCATE_LSA_HEAP callback function
LSA_ALLOCATE_PRIVATE_HEAP callback function
LSA_ALLOCATE_SHARED_MEMORY callback function
LSA_AP_CALL_PACKAGE callback function
LSA_AP_CALL_PACKAGE_PASSTHROUGH callback function
LSA_AP_INITIALIZE_PACKAGE callback function
LSA_AP_LOGON_TERMINATED callback function
LSA_AP_LOGON_USER callback function
LSA_AP_LOGON_USER_EX callback function
LSA_AP_LOGON_USER_EX2 callback function
LSA_AUDIT_ACCOUNT_LOGON callback function
LSA_AUDIT_LOGON callback function
LSA_CALL_PACKAGE callback function
LSA_CALL_PACKAGE_PASSTHROUGH callback function
LSA_CALL_PACKAGEEX callback function
LSA_CANCEL_NOTIFICATION callback function
LSA_CLIENT_CALLBACK callback function
LSA_CLOSE_SAM_USER callback function
LSA_CONVERT_AUTH_DATA_TO_TOKEN callback function
LSA_COPY_FROM_CLIENT_BUFFER callback function
LSA_COPY_TO_CLIENT_BUFFER callback function
LSA_CRACK_SINGLE_NAME callback function
LSA_CREATE_LOGON_SESSION callback function
LSA_CREATE_SHARED_MEMORY callback function
LSA_CREATE_THREAD callback function
LSA_CREATE_TOKEN callback function
LSA_CREATE_TOKEN_EX callback function
LSA_DELETE_CREDENTIAL callback function
LSA_DELETE_LOGON_SESSION callback function
LSA_DELETE_SHARED_MEMORY callback function
LSA_DISPATCH_TABLE structure
LSA_DUPLICATE_HANDLE callback function
LSA_EXPAND_AUTH_DATA_FOR_DOMAIN callback function
LSA_FREE_CLIENT_BUFFER callback function
LSA_FREE_LSA_HEAP callback function
LSA_FREE_PRIVATE_HEAP callback function
LSA_FREE_SHARED_MEMORY callback function
LSA_GET_AUTH_DATA_FOR_USER callback function
LSA_GET_CALL_INFO callback function
LSA_GET_CLIENT_INFO callback function
LSA_GET_CREDENTIALS callback function
LSA_GET_USER_AUTH_DATA callback function
LSA_MAP_BUFFER callback function
LSA_OPEN_SAM_USER callback function
LSA_OPEN_TOKEN_BY_LOGON_ID callback function
LSA_PROTECT_MEMORY callback function
LSA_REGISTER_NOTIFICATION callback function
LSA_SECPKG_FUNCTION_TABLE structure
LSA_TOKEN_INFORMATION_NULL structure
LSA_TOKEN_INFORMATION_TYPE enumeration
LSA_TOKEN_INFORMATION_V1 structure
LSA_TOKEN_INFORMATION_V3 structure
LSA_UPDATE_PRIMARY_CREDENTIALS callback function
SECPKG_BYTE_VECTOR structure
SECPKG_CALL_INFO structure
SECPKG_CLIENT_INFO structure
SECPKG_CONTEXT_THUNKS structure
SECPKG_CREDENTIAL structure
SECPKG_DLL_FUNCTIONS structure
SECPKG_EVENT_NOTIFY structure
SECPKG_EVENT_PACKAGE_CHANGE structure
SECPKG_EXTENDED_INFORMATION structure
SECPKG_EXTENDED_INFORMATION_CLASS enumeration
SECPKG_EXTRA_OIDS structure
SECPKG_FUNCTION_TABLE structure
SECPKG_GSS_INFO structure
SECPKG_MUTUAL_AUTH_LEVEL structure
SECPKG_NAME_TYPE enumeration
SECPKG_NEGO2_INFO structure
SECPKG_PARAMETERS structure
SECPKG_PRIMARY_CRED structure
SECPKG_SERIALIZED_OID structure
SECPKG_SESSIONINFO_TYPE enumeration
SECPKG_SHORT_VECTOR structure
SECPKG_SUPPLEMENTAL_CRED structure
SECPKG_SUPPLEMENTAL_CRED_ARRAY structure
SECPKG_SUPPLIED_CREDENTIAL structure
SECPKG_TARGETINFO structure
SECPKG_USER_FUNCTION_TABLE structure
SECPKG_WOW_CLIENT_DLL structure
SECURITY_USER_DATA structure
SpAcceptCredentialsFn callback function
SpAcceptLsaModeContextFn callback function
SpAcquireCredentialsHandleFn callback function
SpAddCredentialsFn callback function
SpApplyControlTokenFn callback function
SpCompleteAuthTokenFn callback function
SpDeleteCredentialsFn callback function
SpExchangeMetaDataFn callback function
SpExportSecurityContextFn callback function
SpFormatCredentialsFn callback function
SpFreeCredentialsHandleFn callback function
SpGetContextTokenFn callback function
SpGetCredentialsFn callback function
 SpGetCredUIContextFn callback function
SpGetExtendedInformationFn callback function
SpGetInfoFn callback function
SpGetUserInfoFn callback function
SpImportSecurityContextFn callback function
SpInitializeFn callback function
SpInitLsaModeContextFn callback function
SpInitUserModeContextFn callback function
SpInstanceInitFn callback function
SpLsaModeInitializeFn callback function
SpMarshallSupplementalCredsFn callback function
SpQueryContextAttributesFn callback function
SpQueryCredentialsAttributesFn callback function
SpQueryMetaDataFn callback function
SpSaveCredentialsFn callback function
SpSealMessageFn callback function
SpSetExtendedInformationFn callback function
SpUnsealMessageFn callback function
SpUpdateCredentialsFn callback function
SpUserModeInitializeFn callback function
SpValidateTargetInfoFn callback function
Processthreadsapi.h
Overview
GetCurrentProcessToken function
GetCurrentThreadEffectiveToken function
GetCurrentThreadToken function
GetMachineTypeAttributes function
MACHINE_ATTRIBUTES enumeration
OpenProcessToken function
OpenThreadToken function
PROCESS_INFORMATION_CLASS enumeration
PROCESS_MACHINE_INFORMATION structure
 SetThreadToken function
Sas.h
Overview
SendSAS function
Scesvc.h
Overview
ISceSvcAttachmentData interface
Overview
ISceSvcAttachmentData::CloseHandle method
ISceSvcAttachmentData::FreeBuffer method
ISceSvcAttachmentData::GetData method
ISceSvcAttachmentData::Initialize method
ISceSvcAttachmentPersistInfo interface
Overview
ISceSvcAttachmentPersistInfo::FreeBuffer method
ISceSvcAttachmentPersistInfo::IsDirty method
ISceSvcAttachmentPersistInfo::Save method
PFSCE_FREE_INFO callback function
PFSCE_LOG_INFO callback function
PFSCE_QUERY_INFO callback function
PFSCE_SET_INFO callback function
SCESVC_ANALYSIS_INFO structure
SCESVC_ANALYSIS_LINE structure
SCESVC_CALLBACK_INFO structure
SCESVC_CONFIGURATION_INFO structure
SCESVC_CONFIGURATION_LINE structure
SCESVC_INFO_TYPE enumeration
Schannel.h
Overview
CRYPTO_SETTINGS structure
eTlsAlgorithmUsage enumeration
SCH_CRED_PUBLIC_CERTCHAIN structure
 SCH_CRED_SECRET_PRIVKEY structure
SCH_CREDENTIALS structure
SCHANNEL_ALERT_TOKEN structure
SCHANNEL_CERT_HASH structure
SCHANNEL_CERT_HASH_STORE structure
SCHANNEL_CLIENT_SIGNATURE structure
SCHANNEL_CRED structure
SCHANNEL_SESSION_TOKEN structure
SecPkgContext_CipherInfo structure
SecPkgContext_ConnectionInfo structure
SecPkgContext_EapKeyBlock structure
SecPkgContext_EapPrfInfo structure
SecPkgContext_EarlyStart structure
SecPkgContext_IssuerListInfoEx structure
SecPkgContext_KeyingMaterial structure
SecPkgContext_KeyingMaterialInfo structure
SecPkgContext_SessionAppData structure
SecPkgContext_SessionInfo structure
SecPkgContext_SupportedSignatures structure
SslCrackCertificate function
SslEmptyCacheA function
SslEmptyCacheW function
SslFreeCertificate function
SslGetServerIdentity function
TLS_PARAMETERS structure
X509Certificate structure
Sddl.h
Overview
ConvertSecurityDescriptorToStringSecurityDescriptorA function
ConvertSecurityDescriptorToStringSecurityDescriptorW function
ConvertSidToStringSidA function
ConvertSidToStringSidW function
 ConvertStringSecurityDescriptorToSecurityDescriptorA function
ConvertStringSecurityDescriptorToSecurityDescriptorW function
ConvertStringSidToSidA function
ConvertStringSidToSidW function
Securityappcontainer.h
Overview
GetAppContainerNamedObjectPath function
Securitybaseapi.h
Overview
AccessCheck function
AccessCheckAndAuditAlarmW function
AccessCheckByType function
AccessCheckByTypeAndAuditAlarmW function
AccessCheckByTypeResultList function
AccessCheckByTypeResultListAndAuditAlarmByHandleW function
AccessCheckByTypeResultListAndAuditAlarmW function
AddAccessAllowedAce function
AddAccessAllowedAceEx function
AddAccessAllowedObjectAce function
AddAccessDeniedAce function
AddAccessDeniedAceEx function
AddAccessDeniedObjectAce function
AddAce function
AddAuditAccessAce function
AddAuditAccessAceEx function
AddAuditAccessObjectAce function
AddMandatoryAce function
AddResourceAttributeAce function
AddScopedPolicyIDAce function
AdjustTokenGroups function
AdjustTokenPrivileges function
AllocateAndInitializeSid function
AllocateLocallyUniqueId function
AreAllAccessesGranted function
AreAnyAccessesGranted function
CheckTokenCapability function
CheckTokenMembership function
CheckTokenMembershipEx function
ConvertToAutoInheritPrivateObjectSecurity function
CopySid function
CreatePrivateObjectSecurity function
CreatePrivateObjectSecurityEx function
CreatePrivateObjectSecurityWithMultipleInheritance function
CreateRestrictedToken function
CreateWellKnownSid function
DeleteAce function
DeriveCapabilitySidsFromName function
DestroyPrivateObjectSecurity function
DuplicateToken function
DuplicateTokenEx function
EqualDomainSid function
EqualPrefixSid function
EqualSid function
FindFirstFreeAce function
FreeSid function
GetAce function
GetAclInformation function
GetFileSecurityW function
GetKernelObjectSecurity function
GetLengthSid function
GetPrivateObjectSecurity function
GetSecurityDescriptorControl function
GetSecurityDescriptorDacl function
GetSecurityDescriptorGroup function
GetSecurityDescriptorLength function
GetSecurityDescriptorOwner function
GetSecurityDescriptorRMControl function
GetSecurityDescriptorSacl function
GetSidIdentifierAuthority function
GetSidLengthRequired function
GetSidSubAuthority function
GetSidSubAuthorityCount function
GetTokenInformation function
GetWindowsAccountDomainSid function
ImpersonateAnonymousToken function
ImpersonateLoggedOnUser function
ImpersonateSelf function
InitializeAcl function
InitializeSecurityDescriptor function
InitializeSid function
IsTokenRestricted function
IsValidAcl function
IsValidSecurityDescriptor function
IsValidSid function
IsWellKnownSid function
MakeAbsoluteSD function
MakeSelfRelativeSD function
MapGenericMask function
ObjectCloseAuditAlarmW function
ObjectDeleteAuditAlarmW function
ObjectOpenAuditAlarmW function
ObjectPrivilegeAuditAlarmW function
PrivilegeCheck function
PrivilegedServiceAuditAlarmW function
QuerySecurityAccessMask function
RevertToSelf function
 SetAclInformation function
SetFileSecurityW function
SetKernelObjectSecurity function
SetPrivateObjectSecurity function
SetPrivateObjectSecurityEx function
SetSecurityAccessMask function
SetSecurityDescriptorControl function
SetSecurityDescriptorDacl function
SetSecurityDescriptorGroup function
SetSecurityDescriptorOwner function
SetSecurityDescriptorRMControl function
SetSecurityDescriptorSacl function
SetTokenInformation function
Slpublic.h
Overview
SL_ACTIVATION_INFO_HEADER structure
SL_ACTIVATION_TYPE enumeration
SL_AD_ACTIVATION_INFO structure
SL_GENUINE_STATE enumeration
SL_LICENSING_STATUS structure
SL_NONGENUINE_UI_OPTIONS structure
SLAcquireGenuineTicket function
SLActivateProduct function
SLClose function
SLConsumeRight function
SLDATATYPE enumeration
SLDepositMigrationBlob function
SLDepositOfflineConfirmationId function
SLDepositOfflineConfirmationIdEx function
SLFireEvent function
SLGatherMigrationBlob function
SLGenerateOfflineInstallationId function
SLGenerateOfflineInstallationIdEx function
SLGetApplicationInformation function
SLGetApplicationPolicy function
SLGetAuthenticationResult function
SLGetGenuineInformation function
SLGetGenuineInformationEx function
SLGetInstalledProductKeyIds function
SLGetLicense function
SLGetLicenseFileId function
SLGetLicenseInformation function
SLGetLicensingStatusInformation function
SLGetPKeyId function
SLGetPKeyInformation function
SLGetPolicyInformation function
SLGetPolicyInformationDWORD function
SLGetProductSkuInformation function
SLGetReferralInformation function
SLGetServerStatus function
SLGetServiceInformation function
SLGetSLIDList function
SLGetWindowsInformation function
SLGetWindowsInformationDWORD function
SLIDTYPE enumeration
SLInstallLicense function
SLInstallProofOfPurchase function
SLInstallProofOfPurchaseEx function
SLIsGenuineLocal function
SLIsGenuineLocalEx function
SLLICENSINGSTATUS enumeration
SLLoadApplicationPolicies function
SLOpen function
SLPersistApplicationPolicies function
 SLPersistRTSPayloadOverride function
SLQueryLicenseValueFromApp function
SLReArm function
SLREFERRALTYPE enumeration
SLRegisterEvent function
SLSetAuthenticationData function
SLSetCurrentProductKey function
SLSetGenuineInformation function
SLUninstallLicense function
SLUninstallProofOfPurchase function
SLUnloadApplicationPolicies function
SLUnregisterEvent function
Sspi.h
Overview
AcceptSecurityContext function
AcquireCredentialsHandleA function
AcquireCredentialsHandleW function
AddSecurityPackageA function
AddSecurityPackageW function
ApplyControlToken function
ChangeAccountPasswordA function
ChangeAccountPasswordW function
CompleteAuthToken function
CREDUIWIN_MARSHALED_CONTEXT structure
DecryptMessage function
DeleteSecurityContext function
DeleteSecurityPackageA function
DeleteSecurityPackageW function
EncryptMessage function
EnumerateSecurityPackagesA function
EnumerateSecurityPackagesW function
ExportSecurityContext function
FreeContextBuffer function
FreeCredentialsHandle function
ImpersonateSecurityContext function
ImportSecurityContextA function
ImportSecurityContextW function
InitializeSecurityContextA function
InitializeSecurityContextW function
InitSecurityInterfaceA function
InitSecurityInterfaceW function
MakeSignature function
QueryContextAttributesA function
QueryContextAttributesExA function
QueryContextAttributesExW function
QueryContextAttributesW function
QueryCredentialsAttributesA function
QueryCredentialsAttributesW function
QuerySecurityContextToken function
QuerySecurityPackageInfoA function
QuerySecurityPackageInfoW function
RevertSecurityContext function
SaslAcceptSecurityContext function
SaslEnumerateProfilesA function
SaslEnumerateProfilesW function
SaslGetContextOption function
SaslGetProfilePackageA function
SaslGetProfilePackageW function
SaslIdentifyPackageA function
SaslIdentifyPackageW function
SaslInitializeSecurityContextA function
SaslInitializeSecurityContextW function
SaslSetContextOption function
SEC_APPLICATION_PROTOCOL_NEGOTIATION_STATUS enumeration
SEC_CHANNEL_BINDINGS structure
SEC_WINNT_AUTH_BYTE_VECTOR structure
SEC_WINNT_AUTH_CERTIFICATE_DATA structure
SEC_WINNT_AUTH_DATA structure
SEC_WINNT_AUTH_DATA_PASSWORD structure
SEC_WINNT_AUTH_IDENTITY_A structure
SEC_WINNT_AUTH_IDENTITY_EX2 structure
SEC_WINNT_AUTH_IDENTITY_EXA structure
SEC_WINNT_AUTH_IDENTITY_EXW structure
SEC_WINNT_AUTH_IDENTITY_W structure
SEC_WINNT_AUTH_PACKED_CREDENTIALS structure
SEC_WINNT_AUTH_PACKED_CREDENTIALS_EX structure
SEC_WINNT_AUTH_SHORT_VECTOR structure
SEC_WINNT_CREDUI_CONTEXT structure
SEC_WINNT_CREDUI_CONTEXT_VECTOR structure
SecBuffer structure
SecBufferDesc structure
SECPKG_ATTR_LCT_STATUS enumeration
SECPKG_CRED_CLASS enumeration
SecPkgContext_AccessToken structure
SecPkgContext_AuthorityA structure
SecPkgContext_AuthorityW structure
SecPkgContext_Bindings structure
SecPkgContext_ClientSpecifiedTarget structure
SecPkgContext_CredentialNameA structure
SecPkgContext_CredInfo structure
SecPkgContext_DceInfo structure
SecPkgContext_Flags structure
SecPkgContext_KeyInfoA structure
SecPkgContext_KeyInfoW structure
SecPkgContext_LastClientTokenStatus structure
SecPkgContext_Lifespan structure
SecPkgContext_NamesA structure
SecPkgContext_NamesW structure
SecPkgContext_NativeNamesA structure
SecPkgContext_NegoStatus structure
SecPkgContext_NegotiatedTlsExtensions structure
SecPkgContext_NegotiationInfoA structure
SecPkgContext_NegotiationInfoW structure
SecPkgContext_PasswordExpiry structure
SecPkgContext_ProtoInfoA structure
SecPkgContext_ProtoInfoW structure
SecPkgContext_SessionKey structure
SecPkgContext_Sizes structure
SecPkgContext_StreamSizes structure
SecPkgContext_SubjectAttributes structure
SecPkgContext_TargetInformation structure
SecPkgCredentials_Cert structure
SecPkgCredentials_KdcProxySettingsW structure
SecPkgCredentials_NamesA structure
SecPkgCredentials_NamesW structure
SecPkgCredentials_SSIProviderA structure
SecPkgCredentials_SSIProviderW structure
SecPkgInfoA structure
SecPkgInfoW structure
SECURITY_INTEGER structure
SECURITY_PACKAGE_OPTIONS structure
SECURITY_STRING structure
SecurityFunctionTableA structure
SecurityFunctionTableW structure
SetContextAttributesA function
SetContextAttributesW function
SetCredentialsAttributesA function
SetCredentialsAttributesW function
SspiAcceptSecurityContextAsync function
SspiAcquireCredentialsHandleAsyncA function
SspiAcquireCredentialsHandleAsyncW function
SspiAsyncContextRequiresNotify function
SspiAsyncNotifyCallback callback function
SspiCompareAuthIdentities function
SspiCopyAuthIdentity function
SspiCreateAsyncContext function
SspiDecryptAuthIdentity function
SspiDecryptAuthIdentityEx function
SspiDeleteSecurityContextAsync function
SspiEncodeAuthIdentityAsStrings function
SspiEncodeStringsAsAuthIdentity function
SspiEncryptAuthIdentity function
SspiEncryptAuthIdentityEx function
SspiExcludePackage function
SspiFreeAsyncContext function
SspiFreeAuthIdentity function
SspiFreeCredentialsHandleAsync function
SspiGetAsyncCallStatus function
SspiGetCredUIContext function
SspiGetTargetHostName function
SspiInitializeSecurityContextAsyncA function
SspiInitializeSecurityContextAsyncW function
SspiIsAuthIdentityEncrypted function
SspiIsPromptingNeeded function
SspiLocalFree function
SspiMarshalAuthIdentity function
SspiPrepareForCredRead function
SspiPrepareForCredWrite function
SspiPromptForCredentialsA function
SspiPromptForCredentialsW function
 SspiReinitAsyncContext function
SspiSetAsyncNotifyCallback function
SspiUnmarshalAuthIdentity function
SspiUnmarshalCredUIContext function
SspiUpdateCredentials function
SspiValidateAuthIdentity function
SspiZeroAuthIdentity function
VerifySignature function
Subauth.h
Overview
Msv1_0SubAuthenticationFilter function
Msv1_0SubAuthenticationRoutine function
Msv1_0SubAuthenticationRoutineEx function
Msv1_0SubAuthenticationRoutineGeneric function
NETLOGON_LOGON_IDENTITY_INFO structure
OLD_LARGE_INTEGER structure
SR_SECURITY_DESCRIPTOR structure
UNICODE_STRING structure
USER_ALL_INFORMATION structure
Tokenbinding.h
Overview
TOKENBINDING_EXTENSION_FORMAT enumeration
TOKENBINDING_IDENTIFIER structure
TOKENBINDING_KEY_TYPES structure
TOKENBINDING_RESULT_DATA structure
TOKENBINDING_RESULT_LIST structure
TOKENBINDING_TYPE enumeration
TokenBindingDeleteAllBindings function
TokenBindingDeleteBinding function
TokenBindingGenerateBinding function
TokenBindingGenerateID function
TokenBindingGenerateMessage function
 TokenBindingGetKeyTypesClient function
TokenBindingGetKeyTypesServer function
TokenBindingVerifyMessage function
Tpmvscmgr.h
Overview
ITpmVirtualSmartCardManager interface
Overview
ITpmVirtualSmartCardManager::CreateVirtualSmartCard method
ITpmVirtualSmartCardManager::DestroyVirtualSmartCard method
ITpmVirtualSmartCardManagerStatusCallback interface
Overview
ITpmVirtualSmartCardManagerStatusCallback::ReportError method
ITpmVirtualSmartCardManagerStatusCallback::ReportProgress method
TPMVSCMGR_ERROR enumeration
TPMVSCMGR_STATUS enumeration
Winbase.h
Overview
AccessCheckAndAuditAlarmA function
AccessCheckByTypeAndAuditAlarmA function
AccessCheckByTypeResultListAndAuditAlarmA function
AccessCheckByTypeResultListAndAuditAlarmByHandleA function
AddConditionalAce function
GetFileSecurityA function
LogonUserA function
LogonUserExA function
LogonUserExW function
LogonUserW function
LookupAccountNameA function
LookupAccountNameW function
LookupAccountSidA function
LookupAccountSidLocalA function
LookupAccountSidLocalW function
 LookupAccountSidW function
LookupPrivilegeDisplayNameA function
LookupPrivilegeDisplayNameW function
LookupPrivilegeNameA function
LookupPrivilegeNameW function
LookupPrivilegeValueA function
LookupPrivilegeValueW function
ObjectCloseAuditAlarmA function
ObjectDeleteAuditAlarmA function
ObjectOpenAuditAlarmA function
ObjectPrivilegeAuditAlarmA function
PrivilegedServiceAuditAlarmA function
SetFileSecurityA function
Wincred.h
Overview
CERT_CREDENTIAL_INFO structure
CRED_MARSHAL_TYPE enumeration
CRED_PROTECTION_TYPE enumeration
CredDeleteA function
CredDeleteW function
CREDENTIAL_ATTRIBUTEA structure
CREDENTIAL_ATTRIBUTEW structure
CREDENTIAL_TARGET_INFORMATIONA structure
CREDENTIAL_TARGET_INFORMATIONW structure
CREDENTIALA structure
CREDENTIALW structure
CredEnumerateA function
CredEnumerateW function
CredFindBestCredentialA function
CredFindBestCredentialW function
CredFree function
CredGetSessionTypes function
CredGetTargetInfoA function
CredGetTargetInfoW function
CredIsMarshaledCredentialA function
CredIsMarshaledCredentialW function
CredIsProtectedA function
CredIsProtectedW function
CredMarshalCredentialA function
CredMarshalCredentialW function
CredPackAuthenticationBufferA function
CredPackAuthenticationBufferW function
CredProtectA function
CredProtectW function
CredReadA function
CredReadDomainCredentialsA function
CredReadDomainCredentialsW function
CredReadW function
CredRenameA function
CredRenameW function
CREDUI_INFOA structure
CREDUI_INFOW structure
CredUICmdLinePromptForCredentialsA function
CredUICmdLinePromptForCredentialsW function
CredUIConfirmCredentialsA function
CredUIConfirmCredentialsW function
CredUIParseUserNameA function
CredUIParseUserNameW function
CredUIPromptForCredentialsA function
CredUIPromptForWindowsCredentialsA function
CredUIPromptForWindowsCredentialsW function
CredUIReadSSOCredW function
CredUIStoreSSOCredW function
CredUnmarshalCredentialA function
 CredUnmarshalCredentialW function
CredUnPackAuthenticationBufferA function
CredUnPackAuthenticationBufferW function
CredUnprotectA function
CredUnprotectW function
CredWriteA function
CredWriteDomainCredentialsA function
CredWriteDomainCredentialsW function
CredWriteW function
USERNAME_TARGET_CREDENTIAL_INFO structure
Wincrypt.h
Overview
AUTHENTICODE_EXTRA_CERT_CHAIN_POLICY_PARA structure
AUTHENTICODE_EXTRA_CERT_CHAIN_POLICY_STATUS structure
AUTHENTICODE_TS_EXTRA_CERT_CHAIN_POLICY_PARA structure
BLOBHEADER structure
CERT_ACCESS_DESCRIPTION structure
CERT_ALT_NAME_ENTRY structure
CERT_ALT_NAME_INFO structure
CERT_AUTHORITY_INFO_ACCESS structure
CERT_AUTHORITY_KEY_ID_INFO structure
CERT_AUTHORITY_KEY_ID2_INFO structure
CERT_BASIC_CONSTRAINTS_INFO structure
CERT_BASIC_CONSTRAINTS2_INFO structure
CERT_BIOMETRIC_DATA structure
CERT_BIOMETRIC_EXT_INFO structure
CERT_CHAIN_CONTEXT structure
CERT_CHAIN_ELEMENT structure
CERT_CHAIN_ENGINE_CONFIG structure
CERT_CHAIN_FIND_ISSUER_PARA structure
CERT_CHAIN_PARA structure
CERT_CHAIN_POLICY_PARA structure
CERT_CHAIN_POLICY_STATUS structure
CERT_CONTEXT structure
CERT_CREATE_CONTEXT_PARA structure
CERT_CRL_CONTEXT_PAIR structure
CERT_DH_PARAMETERS structure
CERT_DSS_PARAMETERS structure
CERT_ECC_SIGNATURE structure
CERT_EXTENSION structure
CERT_EXTENSIONS structure
CERT_GENERAL_SUBTREE structure
CERT_HASHED_URL structure
CERT_ID structure
CERT_INFO structure
CERT_ISSUER_SERIAL_NUMBER structure
CERT_KEY_ATTRIBUTES_INFO structure
CERT_KEY_CONTEXT structure
CERT_KEY_USAGE_RESTRICTION_INFO structure
CERT_KEYGEN_REQUEST_INFO structure
CERT_LDAP_STORE_OPENED_PARA structure
CERT_LOGOTYPE_AUDIO structure
CERT_LOGOTYPE_AUDIO_INFO structure
CERT_LOGOTYPE_DATA structure
CERT_LOGOTYPE_DETAILS structure
CERT_LOGOTYPE_EXT_INFO structure
CERT_LOGOTYPE_IMAGE structure
CERT_LOGOTYPE_IMAGE_INFO structure
CERT_LOGOTYPE_INFO structure
CERT_LOGOTYPE_REFERENCE structure
CERT_NAME_CONSTRAINTS_INFO structure
CERT_NAME_INFO structure
CERT_NAME_VALUE structure
CERT_OR_CRL_BLOB structure
CERT_OR_CRL_BUNDLE structure
CERT_OTHER_LOGOTYPE_INFO structure
CERT_PAIR structure
CERT_PHYSICAL_STORE_INFO structure
CERT_POLICIES_INFO structure
CERT_POLICY_CONSTRAINTS_INFO structure
CERT_POLICY_ID structure
CERT_POLICY_INFO structure
CERT_POLICY_MAPPING structure
CERT_POLICY_MAPPINGS_INFO structure
CERT_POLICY_QUALIFIER_INFO structure
CERT_PRIVATE_KEY_VALIDITY structure
CERT_PUBLIC_KEY_INFO structure
CERT_QC_STATEMENT structure
CERT_QC_STATEMENTS_EXT_INFO structure
CERT_RDN structure
CERT_RDN_ATTR structure
CERT_REQUEST_INFO structure
CERT_REVOCATION_CHAIN_PARA structure
CERT_REVOCATION_CRL_INFO structure
CERT_REVOCATION_INFO structure
CERT_REVOCATION_PARA structure
CERT_REVOCATION_STATUS structure
CERT_SELECT_CHAIN_PARA structure
CERT_SELECT_CRITERIA structure
CERT_SERVER_OCSP_RESPONSE_CONTEXT structure
CERT_SIGNED_CONTENT_INFO structure
CERT_SIMPLE_CHAIN structure
CERT_STORE_PROV_FIND_INFO structure
CERT_STORE_PROV_INFO structure
CERT_STRONG_SIGN_PARA structure
CERT_STRONG_SIGN_SERIALIZED_INFO structure
CERT_SYSTEM_STORE_INFO structure
CERT_SYSTEM_STORE_RELOCATE_PARA structure
CERT_TEMPLATE_EXT structure
CERT_TRUST_LIST_INFO structure
CERT_TRUST_STATUS structure
CERT_USAGE_MATCH structure
CERT_X942_DH_PARAMETERS structure
CERT_X942_DH_VALIDATION_PARAMS structure
CertAddCertificateContextToStore function
CertAddCertificateLinkToStore function
CertAddCRLContextToStore function
CertAddCRLLinkToStore function
CertAddCTLContextToStore function
CertAddCTLLinkToStore function
CertAddEncodedCertificateToStore function
CertAddEncodedCertificateToSystemStoreA function
CertAddEncodedCertificateToSystemStoreW function
CertAddEncodedCRLToStore function
CertAddEncodedCTLToStore function
CertAddEnhancedKeyUsageIdentifier function
CertAddRefServerOcspResponse function
CertAddRefServerOcspResponseContext function
CertAddSerializedElementToStore function
CertAddStoreToCollection function
CertAlgIdToOID function
CertCloseServerOcspResponse function
CertCloseStore function
CertCompareCertificate function
CertCompareCertificateName function
CertCompareIntegerBlob function
CertComparePublicKeyInfo function
CertControlStore function
CertCreateCertificateChainEngine function
CertCreateCertificateContext function
CertCreateContext function
CertCreateCRLContext function
CertCreateCTLContext function
CertCreateCTLEntryFromCertificateContextProperties function
CertCreateSelfSignCertificate function
CertDeleteCertificateFromStore function
CertDeleteCRLFromStore function
CertDeleteCTLFromStore function
CertDuplicateCertificateChain function
CertDuplicateCertificateContext function
CertDuplicateCRLContext function
CertDuplicateCTLContext function
CertDuplicateStore function
CertEnumCertificateContextProperties function
CertEnumCertificatesInStore function
CertEnumCRLContextProperties function
CertEnumCRLsInStore function
CertEnumCTLContextProperties function
CertEnumCTLsInStore function
CertEnumPhysicalStore function
CertEnumSubjectInSortedCTL function
CertEnumSystemStore function
CertEnumSystemStoreLocation function
CertFindAttribute function
CertFindCertificateInCRL function
CertFindCertificateInStore function
CertFindChainInStore function
CertFindCRLInStore function
CertFindCTLInStore function
CertFindExtension function
CertFindRDNAttr function
CertFindSubjectInCTL function
CertFindSubjectInSortedCTL function
CertFreeCertificateChain function
CertFreeCertificateChainEngine function
CertFreeCertificateChainList function
CertFreeCertificateContext function
CertFreeCRLContext function
CertFreeCTLContext function
CertFreeServerOcspResponseContext function
CertGetCertificateChain function
CertGetCertificateContextProperty function
CertGetCRLContextProperty function
CertGetCRLFromStore function
CertGetCTLContextProperty function
CertGetEnhancedKeyUsage function
CertGetIntendedKeyUsage function
CertGetIssuerCertificateFromStore function
CertGetNameStringA function
CertGetNameStringW function
CertGetPublicKeyLength function
CertGetServerOcspResponseContext function
CertGetStoreProperty function
CertGetSubjectCertificateFromStore function
CertGetValidUsages function
CertIsRDNAttrsInCertificateName function
CertIsStrongHashToSign function
CertIsValidCRLForCertificate function
CertNameToStrA function
CertNameToStrW function
CertOIDToAlgId function
CertOpenServerOcspResponse function
CertOpenStore function
CertOpenSystemStoreA function
CertOpenSystemStoreW function
CertRDNValueToStrA function
CertRDNValueToStrW function
CertRegisterPhysicalStore function
CertRegisterSystemStore function
CertRemoveEnhancedKeyUsageIdentifier function
CertRemoveStoreFromCollection function
CertResyncCertificateChainEngine function
CertRetrieveLogoOrBiometricInfo function
CertSaveStore function
CertSelectCertificateChains function
CertSerializeCertificateStoreElement function
CertSerializeCRLStoreElement function
CertSerializeCTLStoreElement function
CertSetCertificateContextPropertiesFromCTLEntry function
CertSetCertificateContextProperty function
CertSetCRLContextProperty function
CertSetCTLContextProperty function
CertSetEnhancedKeyUsage function
CertSetStoreProperty function
CertStrToNameA function
CertStrToNameW function
CertUnregisterPhysicalStore function
CertUnregisterSystemStore function
CertVerifyCertificateChainPolicy function
CertVerifyCRLRevocation function
CertVerifyCRLTimeValidity function
CertVerifyCTLUsage function
CertVerifyRevocation function
CertVerifySubjectCertificateContext function
CertVerifyTimeValidity function
CertVerifyValidityNesting function
CMC_ADD_ATTRIBUTES_INFO structure
CMC_ADD_EXTENSIONS_INFO structure
CMC_DATA_INFO structure
CMC_PEND_INFO structure
CMC_RESPONSE_INFO structure
CMC_STATUS_INFO structure
CMC_TAGGED_ATTRIBUTE structure
CMC_TAGGED_CERT_REQUEST structure
CMC_TAGGED_CONTENT_INFO structure
CMC_TAGGED_OTHER_MSG structure
CMC_TAGGED_REQUEST structure
CMS_DH_KEY_INFO structure
CMS_KEY_INFO structure
CMSG_CMS_RECIPIENT_INFO structure
CMSG_CMS_SIGNER_INFO structure
CMSG_CNG_CONTENT_DECRYPT_INFO structure
CMSG_CONTENT_ENCRYPT_INFO structure
CMSG_CTRL_ADD_SIGNER_UNAUTH_ATTR_PARA structure
CMSG_CTRL_DECRYPT_PARA structure
CMSG_CTRL_DEL_SIGNER_UNAUTH_ATTR_PARA structure
CMSG_CTRL_KEY_AGREE_DECRYPT_PARA structure
CMSG_CTRL_KEY_TRANS_DECRYPT_PARA structure
CMSG_CTRL_MAIL_LIST_DECRYPT_PARA structure
CMSG_CTRL_VERIFY_SIGNATURE_EX_PARA structure
CMSG_ENVELOPED_ENCODE_INFO structure
CMSG_HASHED_ENCODE_INFO structure
CMSG_KEY_AGREE_ENCRYPT_INFO structure
CMSG_KEY_AGREE_KEY_ENCRYPT_INFO structure
CMSG_KEY_AGREE_RECIPIENT_ENCODE_INFO structure
CMSG_KEY_AGREE_RECIPIENT_INFO structure
CMSG_KEY_TRANS_ENCRYPT_INFO structure
CMSG_KEY_TRANS_RECIPIENT_ENCODE_INFO structure
CMSG_KEY_TRANS_RECIPIENT_INFO structure
CMSG_MAIL_LIST_ENCRYPT_INFO structure
CMSG_MAIL_LIST_RECIPIENT_ENCODE_INFO structure
CMSG_MAIL_LIST_RECIPIENT_INFO structure
CMSG_RC2_AUX_INFO structure
CMSG_RC4_AUX_INFO structure
CMSG_RECIPIENT_ENCODE_INFO structure
CMSG_RECIPIENT_ENCRYPTED_KEY_ENCODE_INFO structure
CMSG_RECIPIENT_ENCRYPTED_KEY_INFO structure
CMSG_SIGNED_ENCODE_INFO structure
CMSG_SIGNER_ENCODE_INFO structure
CMSG_SIGNER_INFO structure
CMSG_SP3_COMPATIBLE_AUX_INFO structure
CMSG_STREAM_INFO structure
CRL_CONTEXT structure
CRL_DIST_POINT structure
CRL_DIST_POINT_NAME structure
CRL_DIST_POINTS_INFO structure
CRL_ENTRY structure
CRL_FIND_ISSUED_FOR_PARA structure
CRL_INFO structure
CRL_ISSUING_DIST_POINT structure
CROSS_CERT_DIST_POINTS_INFO structure
CRYPT_AES_128_KEY_STATE structure
CRYPT_AES_256_KEY_STATE structure
CRYPT_ALGORITHM_IDENTIFIER structure
CRYPT_ATTRIBUTE structure
CRYPT_ATTRIBUTE_TYPE_VALUE structure
CRYPT_ATTRIBUTES structure
CRYPT_BIT_BLOB structure
CRYPT_BLOB_ARRAY structure
CRYPT_CONTENT_INFO structure
CRYPT_CONTENT_INFO_SEQUENCE_OF_ANY structure
CRYPT_CREDENTIALS structure
CRYPT_DECODE_PARA structure
CRYPT_DECRYPT_MESSAGE_PARA structure
CRYPT_DEFAULT_CONTEXT_MULTI_OID_PARA structure
CRYPT_ECC_CMS_SHARED_INFO structure
CRYPT_ENCODE_PARA structure
CRYPT_ENCRYPT_MESSAGE_PARA structure
CRYPT_ENCRYPTED_PRIVATE_KEY_INFO structure
CRYPT_ENROLLMENT_NAME_VALUE_PAIR structure
CRYPT_GET_TIME_VALID_OBJECT_EXTRA_INFO structure
CRYPT_HASH_MESSAGE_PARA structure
CRYPT_INTEGER_BLOB structure
CRYPT_KEY_PROV_INFO structure
CRYPT_KEY_PROV_PARAM structure
CRYPT_KEY_SIGN_MESSAGE_PARA structure
CRYPT_KEY_VERIFY_MESSAGE_PARA structure
CRYPT_MASK_GEN_ALGORITHM structure
CRYPT_OBJECT_LOCATOR_PROVIDER_TABLE structure
CRYPT_OID_FUNC_ENTRY structure
CRYPT_OID_INFO structure
CRYPT_PASSWORD_CREDENTIALSA structure
CRYPT_PASSWORD_CREDENTIALSW structure
CRYPT_PKCS12_PBE_PARAMS structure
CRYPT_PKCS8_EXPORT_PARAMS structure
CRYPT_PKCS8_IMPORT_PARAMS structure
CRYPT_PRIVATE_KEY_INFO structure
CRYPT_PSOURCE_ALGORITHM structure
CRYPT_RC2_CBC_PARAMETERS structure
CRYPT_RETRIEVE_AUX_INFO structure
CRYPT_RSA_SSA_PSS_PARAMETERS structure
CRYPT_RSAES_OAEP_PARAMETERS structure
CRYPT_SEQUENCE_OF_ANY structure
CRYPT_SIGN_MESSAGE_PARA structure
CRYPT_SMART_CARD_ROOT_INFO structure
CRYPT_SMIME_CAPABILITIES structure
CRYPT_SMIME_CAPABILITY structure
CRYPT_TIME_STAMP_REQUEST_INFO structure
CRYPT_TIMESTAMP_ACCURACY structure
CRYPT_TIMESTAMP_CONTEXT structure
CRYPT_TIMESTAMP_INFO structure
CRYPT_TIMESTAMP_PARA structure
CRYPT_TIMESTAMP_REQUEST structure
CRYPT_TIMESTAMP_RESPONSE structure
CRYPT_URL_INFO structure
CRYPT_VERIFY_CERT_SIGN_STRONG_PROPERTIES_INFO structure
CRYPT_VERIFY_MESSAGE_PARA structure
CRYPT_X942_OTHER_INFO structure
CryptAcquireCertificatePrivateKey function
CryptAcquireContextA function
CryptAcquireContextW function
CryptBinaryToStringA function
CryptBinaryToStringW function
CryptContextAddRef function
CryptCreateHash function
CryptCreateKeyIdentifierFromCSP function
CryptDecodeMessage function
CryptDecodeObject function
CryptDecodeObjectEx function
CryptDecrypt function
CryptDecryptAndVerifyMessageSignature function
CryptDecryptMessage function
CryptDeriveKey function
CryptDestroyHash function
CryptDestroyKey function
CryptDuplicateHash function
CryptDuplicateKey function
CryptEncodeObject function
CryptEncodeObjectEx function
CryptEncrypt function
CryptEncryptMessage function
CryptEnumKeyIdentifierProperties function
CryptEnumOIDFunction function
CryptEnumOIDInfo function
CryptEnumProvidersA function
CryptEnumProvidersW function
CryptEnumProviderTypesA function
CryptEnumProviderTypesW function
CryptExportKey function
CryptExportPKCS8 function
CryptExportPKCS8Ex function
CryptExportPublicKeyInfo function
CryptExportPublicKeyInfoEx function
CryptExportPublicKeyInfoFromBCryptKeyHandle function
CryptFindCertificateKeyProvInfo function
CryptFindLocalizedName function
CryptFindOIDInfo function
CryptFormatObject function
CryptFreeOIDFunctionAddress function
CryptGenKey function
CryptGenRandom function
CryptGetDefaultOIDDllList function
CryptGetDefaultOIDFunctionAddress function
CryptGetDefaultProviderA function
CryptGetDefaultProviderW function
CryptGetHashParam function
CryptGetKeyIdentifierProperty function
CryptGetKeyParam function
CryptGetMessageCertificates function
CryptGetMessageSignerCount function
CryptGetObjectUrl function
CryptGetOIDFunctionAddress function
CryptGetOIDFunctionValue function
CryptGetProvParam function
CryptGetTimeValidObject function
CryptGetUserKey function
CryptHashCertificate function
CryptHashCertificate2 function
CryptHashData function
CryptHashMessage function
CryptHashPublicKeyInfo function
CryptHashSessionKey function
CryptHashToBeSigned function
CryptImportKey function
CryptImportPKCS8 function
CryptImportPublicKeyInfo function
CryptImportPublicKeyInfoEx function
CryptImportPublicKeyInfoEx2 function
CryptInitOIDFunctionSet function
CryptInstallDefaultContext function
CryptInstallOIDFunctionAddress function
CryptMemAlloc function
CryptMemFree function
CryptMemRealloc function
CryptMsgCalculateEncodedLength function
CryptMsgClose function
CryptMsgControl function
CryptMsgCountersign function
CryptMsgCountersignEncoded function
CryptMsgDuplicate function
CryptMsgEncodeAndSignCTL function
CryptMsgGetAndVerifySigner function
CryptMsgGetParam function
CryptMsgOpenToDecode function
CryptMsgOpenToEncode function
CryptMsgSignCTL function
CryptMsgUpdate function
CryptMsgVerifyCountersignatureEncoded function
CryptMsgVerifyCountersignatureEncodedEx function
CRYPTNET_URL_CACHE_FLUSH_INFO structure
CRYPTNET_URL_CACHE_PRE_FETCH_INFO structure
CRYPTNET_URL_CACHE_RESPONSE_INFO structure
CryptQueryObject function
CryptRegisterDefaultOIDFunction function
CryptRegisterOIDFunction function
CryptRegisterOIDInfo function
CryptReleaseContext function
CryptRetrieveObjectByUrlA function
CryptRetrieveObjectByUrlW function
CryptRetrieveTimeStamp function
CryptSetHashParam function
CryptSetKeyIdentifierProperty function
CryptSetKeyParam function
CryptSetOIDFunctionValue function
CryptSetProviderA function
CryptSetProviderExA function
CryptSetProviderExW function
CryptSetProviderW function
CryptSetProvParam function
CryptSignAndEncodeCertificate function
CryptSignAndEncryptMessage function
CryptSignCertificate function
CryptSignHashA function
CryptSignHashW function
CryptSignMessage function
CryptSignMessageWithKey function
CryptStringToBinaryA function
CryptStringToBinaryW function
CryptUninstallDefaultContext function
CryptUnregisterDefaultOIDFunction function
CryptUnregisterOIDFunction function
CryptUnregisterOIDInfo function
CryptVerifyCertificateSignature function
CryptVerifyCertificateSignatureEx function
CryptVerifyDetachedMessageHash function
CryptVerifyDetachedMessageSignature function
CryptVerifyMessageHash function
CryptVerifyMessageSignature function
CryptVerifyMessageSignatureWithKey function
CryptVerifySignatureA function
CryptVerifySignatureW function
CryptVerifyTimeStampSignature function
CTL_ANY_SUBJECT_INFO structure
CTL_CONTEXT structure
CTL_ENTRY structure
CTL_FIND_SUBJECT_PARA structure
CTL_FIND_USAGE_PARA structure
CTL_INFO structure
CTL_USAGE structure
CTL_USAGE_MATCH structure
CTL_VERIFY_USAGE_PARA structure
CTL_VERIFY_USAGE_STATUS structure
DHPRIVKEY_VER3 structure
DHPUBKEY structure
DHPUBKEY_VER3 structure
DSSSEED structure
EV_EXTRA_CERT_CHAIN_POLICY_PARA structure
EV_EXTRA_CERT_CHAIN_POLICY_STATUS structure
GetEncSChannel function
HMAC_INFO structure
HTTPSPolicyCallbackData structure
OCSP_BASIC_RESPONSE_ENTRY structure
OCSP_BASIC_RESPONSE_INFO structure
OCSP_BASIC_REVOKED_INFO structure
OCSP_BASIC_SIGNED_RESPONSE_INFO structure
OCSP_CERT_ID structure
OCSP_REQUEST_ENTRY structure
OCSP_REQUEST_INFO structure
OCSP_RESPONSE_INFO structure
OCSP_SIGNATURE_INFO structure
OCSP_SIGNED_REQUEST_INFO structure
PCRYPT_DECRYPT_PRIVATE_KEY_FUNC callback function
PCRYPT_ENCRYPT_PRIVATE_KEY_FUNC callback function
PCRYPT_RESOLVE_HCRYPTPROV_FUNC callback function
PFN_CERT_CHAIN_FIND_BY_ISSUER_CALLBACK callback function
PFN_CERT_CREATE_CONTEXT_SORT_FUNC callback function
PFN_CERT_DLL_OPEN_STORE_PROV_FUNC callback function
PFN_CERT_ENUM_PHYSICAL_STORE callback function
PFN_CERT_ENUM_SYSTEM_STORE callback function
PFN_CERT_ENUM_SYSTEM_STORE_LOCATION callback function
PFN_CERT_STORE_PROV_CLOSE callback function
PFN_CERT_STORE_PROV_CONTROL callback function
 PFN_CERT_STORE_PROV_DELETE_CERT callback function
PFN_CERT_STORE_PROV_DELETE_CRL callback function
PFN_CERT_STORE_PROV_READ_CERT callback function
PFN_CERT_STORE_PROV_READ_CRL callback function
PFN_CERT_STORE_PROV_READ_CTL callback function
PFN_CERT_STORE_PROV_SET_CERT_PROPERTY callback function
PFN_CERT_STORE_PROV_SET_CRL_PROPERTY callback function
PFN_CERT_STORE_PROV_SET_CTL_PROPERTY callback function
PFN_CERT_STORE_PROV_WRITE_CERT callback function
PFN_CERT_STORE_PROV_WRITE_CRL callback function
PFN_CERT_STORE_PROV_WRITE_CTL callback function
PFN_CMSG_CNG_IMPORT_CONTENT_ENCRYPT_KEY callback function
PFN_CMSG_CNG_IMPORT_KEY_AGREE callback function
PFN_CMSG_CNG_IMPORT_KEY_TRANS callback function
PFN_CMSG_EXPORT_KEY_AGREE callback function
PFN_CMSG_EXPORT_KEY_TRANS callback function
PFN_CMSG_EXPORT_MAIL_LIST callback function
PFN_CMSG_GEN_CONTENT_ENCRYPT_KEY callback function
PFN_CMSG_IMPORT_KEY_AGREE callback function
PFN_CMSG_IMPORT_KEY_TRANS callback function
PFN_CMSG_IMPORT_MAIL_LIST callback function
PFN_CRYPT_ENUM_KEYID_PROP callback function
PFN_CRYPT_ENUM_OID_FUNC callback function
PFN_CRYPT_ENUM_OID_INFO callback function
PFN_CRYPT_EXPORT_PUBLIC_KEY_INFO_EX2_FUNC callback function
PFN_CRYPT_EXTRACT_ENCODED_SIGNATURE_PARAMETERS_FUNC callback
function
PFN_CRYPT_GET_SIGNER_CERTIFICATE callback function
PFN_CRYPT_OBJECT_LOCATOR_PROVIDER_FLUSH callback function
PFN_CRYPT_OBJECT_LOCATOR_PROVIDER_FREE callback function
PFN_CRYPT_OBJECT_LOCATOR_PROVIDER_FREE_IDENTIFIER callback function
PFN_CRYPT_OBJECT_LOCATOR_PROVIDER_FREE_PASSWORD callback function
PFN_CRYPT_OBJECT_LOCATOR_PROVIDER_GET callback function
 PFN_CRYPT_OBJECT_LOCATOR_PROVIDER_INITIALIZE callback function
PFN_CRYPT_OBJECT_LOCATOR_PROVIDER_RELEASE callback function
PFN_CRYPT_SIGN_AND_ENCODE_HASH_FUNC callback function
PFN_CRYPT_VERIFY_ENCODED_SIGNATURE_FUNC callback function
PFN_IMPORT_PUBLIC_KEY_INFO_EX2_FUNC callback function
PFXExportCertStore function
PFXExportCertStoreEx function
PFXImportCertStore function
PFXIsPFXBlob function
PFXVerifyPassword function
PROV_ENUMALGS structure
PROV_ENUMALGS_EX structure
ROOT_INFO_LUID structure
RSAPUBKEY structure
SCHANNEL_ALG structure
SSL_F12_EXTRA_CERT_CHAIN_POLICY_STATUS structure
Winnetwk.h
Overview
NETCONNECTINFOSTRUCT structure
NETRESOURCEA structure
NETRESOURCEW structure
REMOTE_NAME_INFOA structure
REMOTE_NAME_INFOW structure
UNIVERSAL_NAME_INFOA structure
UNIVERSAL_NAME_INFOW structure
Winnt.h
Overview
ACCESS_ALLOWED_ACE structure
ACCESS_ALLOWED_CALLBACK_ACE structure
ACCESS_ALLOWED_CALLBACK_OBJECT_ACE structure
ACCESS_ALLOWED_OBJECT_ACE structure
ACCESS_DENIED_ACE structure
ACCESS_DENIED_CALLBACK_ACE structure
ACCESS_DENIED_CALLBACK_OBJECT_ACE structure
ACCESS_DENIED_OBJECT_ACE structure
ACE_HEADER structure
ACL structure
ACL_INFORMATION_CLASS enumeration
ACL_REVISION_INFORMATION structure
ACL_SIZE_INFORMATION structure
AUDIT_EVENT_TYPE enumeration
CLAIM_SECURITY_ATTRIBUTE_FQBN_VALUE structure
CLAIM_SECURITY_ATTRIBUTE_OCTET_STRING_VALUE structure
CLAIM_SECURITY_ATTRIBUTE_RELATIVE_V1 structure
CLAIM_SECURITY_ATTRIBUTE_V1 structure
CLAIM_SECURITY_ATTRIBUTES_INFORMATION structure
GENERIC_MAPPING structure
LUID_AND_ATTRIBUTES structure
MANDATORY_LEVEL enumeration
OBJECT_TYPE_LIST structure
PRIVILEGE_SET structure
QUOTA_LIMITS structure
SECURITY_CAPABILITIES structure
SECURITY_DESCRIPTOR structure
SECURITY_IMPERSONATION_LEVEL enumeration
SECURITY_QUALITY_OF_SERVICE structure
SID structure
SID_AND_ATTRIBUTES structure
SID_AND_ATTRIBUTES_HASH structure
SID_IDENTIFIER_AUTHORITY structure
SID_NAME_USE enumeration
SYSTEM_ALARM_ACE structure
SYSTEM_ALARM_CALLBACK_ACE structure
SYSTEM_ALARM_CALLBACK_OBJECT_ACE structure
SYSTEM_ALARM_OBJECT_ACE structure
SYSTEM_AUDIT_ACE structure
SYSTEM_AUDIT_CALLBACK_ACE structure
SYSTEM_AUDIT_CALLBACK_OBJECT_ACE structure
SYSTEM_AUDIT_OBJECT_ACE structure
SYSTEM_MANDATORY_LABEL_ACE structure
SYSTEM_RESOURCE_ATTRIBUTE_ACE structure
SYSTEM_SCOPED_POLICY_ID_ACE structure
TOKEN_ACCESS_INFORMATION structure
TOKEN_APPCONTAINER_INFORMATION structure
TOKEN_AUDIT_POLICY structure
TOKEN_CONTROL structure
TOKEN_DEFAULT_DACL structure
TOKEN_DEVICE_CLAIMS structure
TOKEN_ELEVATION structure
TOKEN_ELEVATION_TYPE enumeration
TOKEN_GROUPS structure
TOKEN_GROUPS_AND_PRIVILEGES structure
TOKEN_INFORMATION_CLASS enumeration
TOKEN_LINKED_TOKEN structure
TOKEN_MANDATORY_LABEL structure
TOKEN_MANDATORY_POLICY structure
TOKEN_ORIGIN structure
TOKEN_OWNER structure
TOKEN_PRIMARY_GROUP structure
TOKEN_PRIVILEGES structure
TOKEN_SOURCE structure
TOKEN_STATISTICS structure
TOKEN_TYPE enumeration
TOKEN_USER structure
TOKEN_USER_CLAIMS structure
WELL_KNOWN_SID_TYPE enumeration
Winreg.h
Overview
RegGetKeySecurity function
RegSetKeySecurity function
Winsafer.h
Overview
SAFER_CODE_PROPERTIES_V1 structure
SAFER_CODE_PROPERTIES_V2 structure
SAFER_HASH_IDENTIFICATION structure
SAFER_IDENTIFICATION_HEADER structure
SAFER_IDENTIFICATION_TYPES enumeration
SAFER_OBJECT_INFO_CLASS enumeration
SAFER_PATHNAME_IDENTIFICATION structure
SAFER_POLICY_INFO_CLASS enumeration
SAFER_URLZONE_IDENTIFICATION structure
SaferCloseLevel function
SaferComputeTokenFromLevel function
SaferCreateLevel function
SaferGetLevelInformation function
SaferGetPolicyInformation function
SaferIdentifyLevel function
SaferiIsExecutableFileType function
SaferRecordEventLogEntry function
SaferSetLevelInformation function
SaferSetPolicyInformation function
Winscard.h
Overview
GetOpenCardNameA function
GetOpenCardNameW function
OPENCARD_SEARCH_CRITERIAA structure
OPENCARD_SEARCH_CRITERIAW structure
OPENCARDNAME_EXA structure
OPENCARDNAME_EXW structure
OPENCARDNAMEA structure
OPENCARDNAMEW structure
SCARD_ATRMASK structure
SCARD_READERSTATEA structure
SCARD_READERSTATEW structure
SCardAccessStartedEvent function
SCardAddReaderToGroupA function
SCardAddReaderToGroupW function
SCardAudit function
SCardBeginTransaction function
SCardCancel function
SCardConnectA function
SCardConnectW function
SCardControl function
SCardDisconnect function
SCardEndTransaction function
SCardEstablishContext function
SCardForgetCardTypeA function
SCardForgetCardTypeW function
SCardForgetReaderA function
SCardForgetReaderGroupA function
SCardForgetReaderGroupW function
SCardForgetReaderW function
SCardFreeMemory function
SCardGetAttrib function
SCardGetCardTypeProviderNameA function
SCardGetCardTypeProviderNameW function
SCardGetDeviceTypeIdA function
SCardGetDeviceTypeIdW function
SCardGetProviderIdA function
SCardGetProviderIdW function
SCardGetReaderDeviceInstanceIdA function
SCardGetReaderDeviceInstanceIdW function
SCardGetReaderIconA function
SCardGetReaderIconW function
SCardGetStatusChangeA function
SCardGetStatusChangeW function
SCardGetTransmitCount function
SCardIntroduceCardTypeA function
SCardIntroduceCardTypeW function
SCardIntroduceReaderA function
SCardIntroduceReaderGroupA function
SCardIntroduceReaderGroupW function
SCardIntroduceReaderW function
SCardIsValidContext function
SCardListCardsA function
SCardListCardsW function
SCardListInterfacesA function
SCardListInterfacesW function
SCardListReaderGroupsA function
SCardListReaderGroupsW function
SCardListReadersA function
SCardListReadersW function
SCardListReadersWithDeviceInstanceIdA function
SCardListReadersWithDeviceInstanceIdW function
SCardLocateCardsA function
SCardLocateCardsByATRA function
SCardLocateCardsByATRW function
SCardLocateCardsW function
SCardReadCacheA function
SCardReadCacheW function
SCardReconnect function
SCardReleaseContext function
 SCardReleaseStartedEvent function
SCardRemoveReaderFromGroupA function
SCardRemoveReaderFromGroupW function
SCardSetAttrib function
SCardSetCardTypeProviderNameA function
SCardSetCardTypeProviderNameW function
SCardStatusA function
SCardStatusW function
SCardTransmit function
SCardUIDlgSelectCardA function
SCardUIDlgSelectCardW function
SCardWriteCacheA function
SCardWriteCacheW function
Winsvc.h
Overview
ChangeServiceConfig2A function
ChangeServiceConfig2W function
CloseServiceHandle function
ControlService function
ControlServiceExA function
ControlServiceExW function
DeleteService function
ENUM_SERVICE_STATUS_PROCESSA structure
ENUM_SERVICE_STATUS_PROCESSW structure
ENUM_SERVICE_STATUSA structure
ENUM_SERVICE_STATUSW structure
EnumDependentServicesA function
EnumDependentServicesW function
EnumServicesStatusA function
EnumServicesStatusExA function
EnumServicesStatusExW function
EnumServicesStatusW function
GetServiceDirectory function
GetServiceDisplayNameA function
GetServiceDisplayNameW function
GetServiceKeyNameA function
GetServiceKeyNameW function
GetServiceRegistryStateKey function
GetSharedServiceDirectory function
GetSharedServiceRegistryStateKey function
LockServiceDatabase function
LPHANDLER_FUNCTION callback function
LPHANDLER_FUNCTION_EX callback function
LPSERVICE_MAIN_FUNCTIONA callback function
LPSERVICE_MAIN_FUNCTIONW callback function
NotifyBootConfigStatus function
NotifyServiceStatusChangeA function
NotifyServiceStatusChangeW function
OpenSCManagerA function
OpenSCManagerW function
OpenServiceA function
OpenServiceW function
QUERY_SERVICE_CONFIGA structure
QUERY_SERVICE_CONFIGW structure
QUERY_SERVICE_LOCK_STATUSA structure
QUERY_SERVICE_LOCK_STATUSW structure
QueryServiceConfig2A function
QueryServiceConfig2W function
QueryServiceConfigA function
QueryServiceConfigW function
QueryServiceDynamicInformation function
QueryServiceLockStatusA function
QueryServiceLockStatusW function
QueryServiceObjectSecurity function
QueryServiceStatus function
QueryServiceStatusEx function
RegisterServiceCtrlHandlerA function
RegisterServiceCtrlHandlerExA function
RegisterServiceCtrlHandlerExW function
RegisterServiceCtrlHandlerW function
SC_ACTION structure
SERVICE_CONTROL_STATUS_REASON_PARAMSA structure
SERVICE_CONTROL_STATUS_REASON_PARAMSW structure
SERVICE_DELAYED_AUTO_START_INFO structure
SERVICE_DESCRIPTIONA structure
SERVICE_DESCRIPTIONW structure
SERVICE_DIRECTORY_TYPE enumeration
SERVICE_FAILURE_ACTIONS_FLAG structure
SERVICE_FAILURE_ACTIONSA structure
SERVICE_FAILURE_ACTIONSW structure
SERVICE_LAUNCH_PROTECTED_INFO structure
SERVICE_NOTIFY_2A structure
SERVICE_NOTIFY_2W structure
SERVICE_PREFERRED_NODE_INFO structure
SERVICE_PRESHUTDOWN_INFO structure
SERVICE_REGISTRY_STATE_TYPE enumeration
SERVICE_REQUIRED_PRIVILEGES_INFOA structure
SERVICE_REQUIRED_PRIVILEGES_INFOW structure
SERVICE_SHARED_DIRECTORY_TYPE enumeration
SERVICE_SHARED_REGISTRY_STATE_TYPE enumeration
SERVICE_SID_INFO structure
SERVICE_STATUS structure
SERVICE_STATUS_PROCESS structure
SERVICE_TABLE_ENTRYA structure
SERVICE_TABLE_ENTRYW structure
SERVICE_TIMECHANGE_INFO structure
 SERVICE_TRIGGER structure
SERVICE_TRIGGER_INFO structure
SERVICE_TRIGGER_SPECIFIC_DATA_ITEM structure
SetServiceObjectSecurity function
SetServiceStatus function
StartServiceA function
StartServiceCtrlDispatcherA function
StartServiceCtrlDispatcherW function
StartServiceW function
UnlockServiceDatabase function
Winternl.h
Overview
RtlConvertSidToUnicodeString function
Wintrust.h
Overview
CRYPT_PROVIDER_CERT structure
CRYPT_PROVIDER_DATA structure
CRYPT_PROVIDER_DEFUSAGE structure
CRYPT_PROVIDER_FUNCTIONS structure
CRYPT_PROVIDER_PRIVDATA structure
CRYPT_PROVIDER_REGDEFUSAGE structure
CRYPT_PROVIDER_SGNR structure
CRYPT_PROVIDER_SIGSTATE structure
CRYPT_PROVUI_DATA structure
CRYPT_PROVUI_FUNCS structure
CRYPT_REGISTER_ACTIONID structure
CRYPT_TRUST_REG_ENTRY structure
OpenPersonalTrustDBDialog function
OpenPersonalTrustDBDialogEx function
SPC_INDIRECT_DATA_CONTENT structure
WIN_CERTIFICATE structure
WINTRUST_BLOB_INFO structure
 WINTRUST_CATALOG_INFO structure
WINTRUST_CERT_INFO structure
WINTRUST_DATA structure
WINTRUST_FILE_INFO structure
WINTRUST_SGNR_INFO structure
WINTRUST_SIGNATURE_SETTINGS structure
WintrustAddActionID function
WintrustAddDefaultForUsage function
WintrustGetDefaultForUsage function
WintrustGetRegPolicyFlags function
WintrustLoadFunctionPointers function
WintrustRemoveActionID function
WintrustSetDefaultIncludePEPageHashes function
WintrustSetRegPolicyFlags function
WinVerifyTrust function
WinVerifyTrustEx function
WTHelperCertCheckValidSignature function
WTHelperCertIsSelfSigned function
WTHelperGetProvCertFromChain function
WTHelperGetProvPrivateDataFromChain function
WTHelperGetProvSignerFromChain function
WTHelperProvDataFromStateData function
Winuser.h
Overview
GetUserObjectSecurity function
SetUserObjectSecurity function
Winwlx.h
Overview
PWLX_ASSIGN_SHELL_PROTECTION callback function
PWLX_CHANGE_PASSWORD_NOTIFY callback function
PWLX_CHANGE_PASSWORD_NOTIFY_EX callback function
PWLX_CLOSE_USER_DESKTOP callback function
PWLX_CREATE_USER_DESKTOP callback function
PWLX_DIALOG_BOX callback function
PWLX_DIALOG_BOX_INDIRECT callback function
PWLX_DIALOG_BOX_INDIRECT_PARAM callback function
PWLX_DIALOG_BOX_PARAM callback function
PWLX_DISCONNECT callback function
PWLX_GET_OPTION callback function
PWLX_GET_SOURCE_DESKTOP callback function
PWLX_MESSAGE_BOX callback function
PWLX_QUERY_CLIENT_CREDENTIALS callback function
PWLX_QUERY_CONSOLESWITCH_CREDENTIALS callback function
PWLX_QUERY_IC_CREDENTIALS callback function
PWLX_QUERY_TERMINAL_SERVICES_DATA callback function
PWLX_QUERY_TS_LOGON_CREDENTIALS callback function
PWLX_SAS_NOTIFY callback function
PWLX_SET_CONTEXT_POINTER callback function
PWLX_SET_OPTION callback function
PWLX_SET_RETURN_DESKTOP callback function
PWLX_SET_TIMEOUT callback function
PWLX_SWITCH_DESKTOP_TO_USER callback function
PWLX_SWITCH_DESKTOP_TO_WINLOGON callback function
PWLX_USE_CTRL_ALT_DEL callback function
PWLX_WIN31_MIGRATE callback function
WLX_CLIENT_CREDENTIALS_INFO_V1_0 structure
WLX_CLIENT_CREDENTIALS_INFO_V2_0 structure
WLX_CONSOLESWITCH_CREDENTIALS_INFO_V1_0 structure
WLX_DESKTOP structure
WLX_DISPATCH_VERSION_1_0 structure
WLX_DISPATCH_VERSION_1_1 structure
WLX_DISPATCH_VERSION_1_2 structure
WLX_DISPATCH_VERSION_1_3 structure
WLX_DISPATCH_VERSION_1_4 structure
 WLX_MPR_NOTIFY_INFO structure
WLX_NOTIFICATION_INFO structure
WLX_PROFILE_V1_0 structure
WLX_PROFILE_V2_0 structure
WLX_TERMINAL_SERVICES_DATA structure
WlxActivateUserShell function
WlxDisconnectNotify function
WlxDisplayLockedNotice function
WlxDisplaySASNotice function
WlxDisplayStatusMessage function
WlxGetConsoleSwitchCredentials function
WlxGetStatusMessage function
WlxInitialize function
WlxIsLockOk function
WlxIsLogoffOk function
WlxLoggedOnSAS function
WlxLoggedOutSAS function
WlxLogoff function
WlxNegotiate function
WlxNetworkProviderLoad function
WlxReconnectNotify function
WlxRemoveStatusMessage function
WlxScreenSaverNotify function
WlxShutdown function
WlxStartApplication function
WlxWkstaLockedSAS function
Xenroll.h
Overview
ICEnroll interface
Overview
ICEnroll::acceptFilePKCS7 method
ICEnroll::acceptPKCS7 method
ICEnroll::createFilePKCS10 method
ICEnroll::createPKCS10 method
ICEnroll::enumContainers method
ICEnroll::enumProviders method
ICEnroll::freeRequestInfo method
ICEnroll::get_CAStoreFlags method
ICEnroll::get_CAStoreName method
ICEnroll::get_CAStoreType method
ICEnroll::get_ContainerName method
ICEnroll::get_DeleteRequestCert method
ICEnroll::get_GenKeyFlags method
ICEnroll::get_HashAlgorithm method
ICEnroll::get_KeySpec method
ICEnroll::get_MyStoreFlags method
ICEnroll::get_MyStoreName method
ICEnroll::get_MyStoreType method
ICEnroll::get_ProviderFlags method
ICEnroll::get_ProviderName method
ICEnroll::get_ProviderType method
ICEnroll::get_PVKFileName method
ICEnroll::get_RequestStoreFlags method
ICEnroll::get_RequestStoreName method
ICEnroll::get_RequestStoreType method
ICEnroll::get_RootStoreFlags method
ICEnroll::get_RootStoreName method
ICEnroll::get_RootStoreType method
ICEnroll::get_SPCFileName method
ICEnroll::get_UseExistingKeySet method
ICEnroll::get_WriteCertToCSP method
ICEnroll::getCertFromPKCS7 method
ICEnroll::put_CAStoreFlags method
ICEnroll::put_CAStoreName method
 ICEnroll::put_CAStoreType method
ICEnroll::put_ContainerName method
ICEnroll::put_DeleteRequestCert method
ICEnroll::put_GenKeyFlags method
ICEnroll::put_HashAlgorithm method
ICEnroll::put_KeySpec method
ICEnroll::put_MyStoreFlags method
ICEnroll::put_MyStoreName method
ICEnroll::put_MyStoreType method
ICEnroll::put_ProviderFlags method
ICEnroll::put_ProviderName method
ICEnroll::put_ProviderType method
ICEnroll::put_PVKFileName method
ICEnroll::put_RequestStoreFlags method
ICEnroll::put_RequestStoreName method
ICEnroll::put_RequestStoreType method
ICEnroll::put_RootStoreFlags method
ICEnroll::put_RootStoreName method
ICEnroll::put_RootStoreType method
ICEnroll::put_SPCFileName method
ICEnroll::put_UseExistingKeySet method
ICEnroll::put_WriteCertToCSP method
ICEnroll2 interface
Overview
ICEnroll2::addCertTypeToRequest method
ICEnroll2::addNameValuePairToSignature method
ICEnroll2::get_EnableT61DNEncoding method
ICEnroll2::get_WriteCertToUserDS method
ICEnroll2::put_EnableT61DNEncoding method
ICEnroll2::put_WriteCertToUserDS method
ICEnroll3 interface
Overview
 ICEnroll3::EnumAlgs method
ICEnroll3::get_EnableSMIMECapabilities method
ICEnroll3::get_HashAlgID method
ICEnroll3::get_LimitExchangeKeyToEncipherment method
ICEnroll3::get_ReuseHardwareKeyIfUnableToGenNew method
ICEnroll3::GetAlgName method
ICEnroll3::GetKeyLen method
ICEnroll3::GetSupportedKeySpec method
ICEnroll3::InstallPKCS7 method
ICEnroll3::put_EnableSMIMECapabilities method
ICEnroll3::put_HashAlgID method
ICEnroll3::put_LimitExchangeKeyToEncipherment method
ICEnroll3::put_ReuseHardwareKeyIfUnableToGenNew method
ICEnroll3::Reset method
ICEnroll4 interface
Overview
ICEnroll4::acceptFileResponse method
ICEnroll4::acceptResponse method
ICEnroll4::addAttributeToRequest method
ICEnroll4::addBlobPropertyToCertificate method
ICEnroll4::addCertTypeToRequestEx method
ICEnroll4::addExtensionToRequest method
ICEnroll4::addNameValuePairToRequest method
ICEnroll4::binaryToString method
ICEnroll4::createFilePFX method
ICEnroll4::createFileRequest method
ICEnroll4::createPFX method
ICEnroll4::createRequest method
ICEnroll4::enumPendingRequest method
ICEnroll4::get_ClientId method
ICEnroll4::get_IncludeSubjectKeyID method
ICEnroll4::get_PrivateKeyArchiveCertificate method
 ICEnroll4::get_ThumbPrint method
ICEnroll4::getCertFromFileResponse method
ICEnroll4::getCertFromResponse method
ICEnroll4::GetKeyLenEx method
ICEnroll4::getProviderType method
ICEnroll4::InstallPKCS7Ex method
ICEnroll4::put_ClientId method
ICEnroll4::put_IncludeSubjectKeyID method
ICEnroll4::put_PrivateKeyArchiveCertificate method
ICEnroll4::put_SignerCertificate method
ICEnroll4::put_ThumbPrint method
ICEnroll4::removePendingRequest method
ICEnroll4::resetAttributes method
ICEnroll4::resetBlobProperties method
ICEnroll4::resetExtensions method
ICEnroll4::setPendingRequestInfo method
ICEnroll4::stringToBinary method
IEnroll interface
Overview
IEnroll::acceptFilePKCS7WStr method
IEnroll::acceptPKCS7Blob method
IEnroll::AddAuthenticatedAttributesToPKCS7Request method
IEnroll::AddCertTypeToRequestWStr method
IEnroll::AddExtensionsToRequest method
IEnroll::AddNameValuePairToSignatureWStr method
IEnroll::createFilePKCS10WStr method
IEnroll::createPKCS10WStr method
IEnroll::CreatePKCS7RequestFromRequest method
IEnroll::enumContainersWStr method
IEnroll::enumProvidersWStr method
IEnroll::freeRequestInfoBlob method
IEnroll::get_CAStoreFlags method
IEnroll::get_CAStoreNameWStr method
IEnroll::get_CAStoreTypeWStr method
IEnroll::get_ContainerNameWStr method
IEnroll::get_DeleteRequestCert method
IEnroll::get_EnableT61DNEncoding method
IEnroll::get_GenKeyFlags method
IEnroll::get_HashAlgorithmWStr method
IEnroll::get_KeySpec method
IEnroll::get_MyStoreFlags method
IEnroll::get_MyStoreNameWStr method
IEnroll::get_MyStoreTypeWStr method
IEnroll::get_ProviderFlags method
IEnroll::get_ProviderNameWStr method
IEnroll::get_ProviderType method
IEnroll::get_PVKFileNameWStr method
IEnroll::get_RenewalCertificate method
IEnroll::get_RequestStoreFlags method
IEnroll::get_RequestStoreNameWStr method
IEnroll::get_RequestStoreTypeWStr method
IEnroll::get_RootStoreFlags method
IEnroll::get_RootStoreNameWStr method
IEnroll::get_RootStoreTypeWStr method
IEnroll::get_SPCFileNameWStr method
IEnroll::get_UseExistingKeySet method
IEnroll::get_WriteCertToCSP method
IEnroll::get_WriteCertToUserDS method
IEnroll::getCAStore method
IEnroll::getCertContextFromPKCS7 method
IEnroll::getMyStore method
IEnroll::getROOTHStore method
IEnroll::put_CAStoreFlags method
IEnroll::put_CAStoreNameWStr method
 IEnroll::put_CAStoreTypeWStr method
IEnroll::put_ContainerNameWStr method
IEnroll::put_DeleteRequestCert method
IEnroll::put_EnableT61DNEncoding method
IEnroll::put_GenKeyFlags method
IEnroll::put_HashAlgorithmWStr method
IEnroll::put_KeySpec method
IEnroll::put_MyStoreFlags method
IEnroll::put_MyStoreNameWStr method
IEnroll::put_MyStoreTypeWStr method
IEnroll::put_ProviderFlags method
IEnroll::put_ProviderNameWStr method
IEnroll::put_ProviderType method
IEnroll::put_PVKFileNameWStr method
IEnroll::put_RenewalCertificate method
IEnroll::put_RequestStoreFlags method
IEnroll::put_RequestStoreNameWStr method
IEnroll::put_RequestStoreTypeWStr method
IEnroll::put_RootStoreFlags method
IEnroll::put_RootStoreNameWStr method
IEnroll::put_RootStoreTypeWStr method
IEnroll::put_SPCFileNameWStr method
IEnroll::put_UseExistingKeySet method
IEnroll::put_WriteCertToCSP method
IEnroll::put_WriteCertToUserDS method
IEnroll2 interface
Overview
IEnroll2::EnumAlgs method
IEnroll2::get_EnableSMIMECapabilities method
IEnroll2::get_HashAlgID method
IEnroll2::get_LimitExchangeKeyToEncipherment method
IEnroll2::get_ReuseHardwareKeyIfUnableToGenNew method
 IEnroll2::GetAlgNameWStr method
IEnroll2::GetKeyLen method
IEnroll2::GetSupportedKeySpec method
IEnroll2::InstallPKCS7Blob method
IEnroll2::put_EnableSMIMECapabilities method
IEnroll2::put_HashAlgID method
IEnroll2::put_LimitExchangeKeyToEncipherment method
IEnroll2::put_ReuseHardwareKeyIfUnableToGenNew method
IEnroll2::Reset method
IEnroll2::SetHStoreCA method
IEnroll2::SetHStoreMy method
IEnroll2::SetHStoreRequest method
IEnroll2::SetHStoreROOT method
IEnroll4 interface
Overview
IEnroll4::acceptFileResponseWStr method
IEnroll4::acceptResponseBlob method
IEnroll4::addAttributeToRequestWStr method
IEnroll4::addBlobPropertyToCertificateWStr method
IEnroll4::AddCertTypeToRequestWStrEx method
IEnroll4::addExtensionToRequestWStr method
IEnroll4::addNameValuePairToRequestWStr method
IEnroll4::binaryBlobToString method
IEnroll4::createFilePFXWStr method
IEnroll4::createFileRequestWStr method
IEnroll4::createPFXWStr method
IEnroll4::createRequestWStr method
IEnroll4::enumPendingRequestWStr method
IEnroll4::get_ClientId method
IEnroll4::get_IncludeSubjectKeyID method
IEnroll4::get_ThumbPrintWStr method
IEnroll4::getCertContextFromFileResponseWStr method
IEnroll4::getCertContextFromResponseBlob method
IEnroll4::GetKeyLenEx method
IEnroll4::GetPrivateKeyArchiveCertificate method
IEnroll4::getProviderTypeWStr method
IEnroll4::InstallPKCS7BlobEx method
IEnroll4::put_ClientId method
IEnroll4::put_IncludeSubjectKeyID method
IEnroll4::put_ThumbPrintWStr method
IEnroll4::removePendingRequestWStr method
IEnroll4::resetAttributes method
IEnroll4::resetExtensions method
IEnroll4::setPendingRequestInfoWStr method
IEnroll4::SetPrivateKeyArchiveCertificate method
IEnroll4::SetSignerCertificate method
IEnroll4::stringToBinaryBlob method
 Security and Identity
7/2/2022 • 303 minutes to read • Edit Online

Overview of the Security and Identity technology.

To develop Security and Identity, you need these headers:
aclapi.h
aclui.h
adtgen.h
authz.h
azroles.h
bcrypt.h
casetup.h
ccplugins.h
celib.h
certadm.h
certbcli.h
certcli.h
certenc.h
certenroll.h
certexit.h
certif.h
certmod.h
certpol.h
certpoleng.h
certsrv.h
certview.h
credssp.h
cryptdlg.h
cryptuiapi.h
cryptxml.h
diagnosticdataquery.h
diagnosticdataquerytypes.h
dpapi.h
dssec.h
iads.h
identitycommon.h
identityprovider.h
identitystore.h
keycredmgr.h
lsalookup.h
mscat.h
mssip.h
ncrypt.h
 ncryptprotect.h
npapi.h
ntlsa.h
ntsecapi.h
sas.h
scesvc.h
schannel.h
sddl.h
securityappcontainer.h
slpublic.h
sspi.h
subauth.h
tokenbinding.h
tpmvscmgr.h
wincred.h
wincrypt.h
winnetwk.h
winsafer.h
winscard.h
winsvc.h
wintrust.h
winwlx.h
xenroll.h
For programming guidance for this technology, see:
Authentication
Authorization
Best Practices for the Security APIs
Certificate Enrollment API
Cryptography API: Next Generation
Cryptography
Security Glossary
Security Management
Security WMI Providers
Software Licensing API

Enumerations

ACCESS_MODE

Contains values that indicate how the access rights in an EXPLICIT_ACCESS structure apply to the trustee.

ACL_INFORMATION_CLASS

Contains values that specify the type of information being assigned to or retrieved from an access control list (ACL).
AlgorithmFlags

Contains flags that can be used to refine the search for a cryptographic algorithm.

AlgorithmOperationFlags

Specifies the operations that an algorithm can perform.

AlgorithmType

Specifies the intended purpose of a cryptographic algorithm supported by a cryptographic provider.

AlternativeNameType

Specifies the alternative name types that can be specified when initializing an IAlternativeName object.

AUDIT_EVENT_TYPE

Defines values that indicate the type of object being audited. The AccessCheckByTypeAndAuditAlarm and
AccessCheckByTypeResultListAndAuditAlarm functions use these values.

AUDIT_PARAM_TYPE

Defines the type of audit parameters that are available.

AUTHZ_CONTEXT_INFORMATION_CLASS

Specifies the type of information to be retrieved from an existing AuthzClientContext. This enumeration is used by the
AuthzGetInformationFromContext function.

AUTHZ_SECURITY_ATTRIBUTE_OPERATION

Indicates the type of modification to be made to security attributes by a call to the AuthzModifySecurityAttributes function.

AUTHZ_SID_OPERATION

Indicates the type of SID operations that can be made by a call to the AuthzModifySids function.

AZ_PROP_CONSTANTS

Defines constants used by Authorization Manager.

BCRYPT_HASH_OPERATION_TYPE

The BCRYPT_HASH_OPERATION_TYPE enumeration specifies the hash operation type.

BCRYPT_MULTI_OPERATION_TYPE

The BCRYPT_MULTI_OPERATION_TYPE enumeration specifies type of multi-operation that is passed to the

BCryptProcessMultiOperations function.

CASetupProperty

Specifies a property type for setup and configuration of a certification authority (CA) role when using the ICertSrvSetup
interface.
CEPSetupProperty

Used by the GetProperty and SetProperty methods on the ICertificateEnrollmentPolicyServerSetup interface to specify the
type of property information to retrieve or set.

CERTENROLL_OBJECTID

Contains the predefined object identifiers (OIDs) supported by Certificate Enrollment API.

CERTENROLL_PROPERTYID

Contains predefined object identifiers for external properties that can be associated with a certificate in the certificate store.

CESSetupProperty

Used by the GetProperty and SetProperty methods on the ICertificateEnrollmentServerSetup interface to specify the type of
property information to retrieve or set.

CommitTemplateFlags

Specifies options for saving and deleting templates.

CRED_MARSHAL_TYPE

Specifies the types of credential to be marshaled by CredMarshalCredential or unmarshaled by CredUnmarshalCredential.

CRED_PROTECTION_TYPE

Specifies the security context in which credentials are encrypted when using the CredProtect function.

CREDSPP_SUBMIT_TYPE

Specifies the type of credentials specified by a CREDSSP_CRED structure.

CRYPT_XML_CHARSET

Used to specify the character set used in the XML.

CRYPT_XML_KEYINFO_SPEC

Specifies values for the dwKeyInfoSpec parameter in the CryptXmlSign function.

CRYPT_XML_PROPERTY_ID

Specifies the type and usage of the XML property.

DdqAccessLevel

This resource represents the privilege level for a Diagnostic Data Query session

DSAFIPSVERSION_ENUM

Contains FIPS version information.

EncodingType

Specifies the type of encoding applied to a byte array for display purposes.

EnrollmentCAProperty

Specifies certification authority property values.

EnrollmentDisplayStatus

Specifies whether to display enrollment status information in a user interface.

EnrollmentEnrollStatus

Specifies the enrollment status of a certificate request.

EnrollmentPolicyFlags

Specifies group policy flags.

EnrollmentPolicyServerPropertyFlags

Specifies the default policy server.

EnrollmentSelectionStatus

Specifies whether the enrollment status of an object will be monitored during the enrollment process.

EnrollmentTemplateProperty

Contains property values for a given template.

ENUM_CATYPES

Specifies a certification authority (CA) type.

ENUM_PERIOD

Specifies the units of a time span.

eTlsAlgorithmUsage

Specifies the algorithm being used to disable cryptographic settings.

HASHALGORITHM_ENUM

Specifies signing and hashing algorithms.

IDENTITY_TYPE

Specifies the type of identities to enumerate.

ImportPFXFlags

Flags to use when importing a PFX certificate.

InnerRequestLevel

Specifies the containment level of a certificate request within a PKCS

InstallResponseRestrictionFlags

Contains flags that identify the restrictions placed on the local installation of a certificate chain.

KERB_CERTIFICATE_INFO_TYPE

Specifies the type of certificate information that is provided.

KERB_LOGON_SUBMIT_TYPE

Identifies the type of logon being requested.

KERB_PROFILE_BUFFER_TYPE

Lists the type of logon profile returned.

KERB_PROTOCOL_MESSAGE_TYPE

Lists the types of messages that can be sent to the Kerberos authentication package by calling the
LsaCallAuthenticationPackage function.

KeyCredentialManagerOperationErrorStates

Enumeration of Error states returned by the function KeyCredentialManagerGetOperationErrorStates as flags.

KeyCredentialManagerOperationType

These are the operational enum values that are passed to KeyCredentialManagerShowUIOperation.

KeyIdentifierHashAlgorithm

Specifies the algorithm used to hash the public key in a certificate request.

LSA_FOREST_TRUST_COLLISION_RECORD_TYPE

Defines the types of collision that can occur between Local Security Authority forest trust records.

LSA_FOREST_TRUST_RECORD_TYPE

Defines the type of a Local Security Authority forest trust record.

LSA_TOKEN_INFORMATION_TYPE

Specifies the levels of information that can be included in a logon token.

MACHINE_ATTRIBUTES

Specifies the ways in which an architecture of code can run on a host operating system. More than one bit may be set.
MANDATORY_LEVEL

Lists the possible security levels.

MSA_INFO_LEVEL

Indicates the level of a managed service account.

MSA_INFO_STATE

Indicates the state of a managed service account.

MSCEPSetupProperty

Specifies a property type for setup and configuration of a Microsoft Simple Certificate Enrollment Protocol (SCEP) role using
IMSCEPSetup.

MSV1_0_LOGON_SUBMIT_TYPE

Indicates the kind of logon being requested.

MSV1_0_PROFILE_BUFFER_TYPE

Lists the kind of logon profile returned.

MSV1_0_PROTOCOL_MESSAGE_TYPE

Lists the types of messages that can be sent to the MSV1_0 Authentication Package by calling the
LsaCallAuthenticationPackage function.

MULTIPLE_TRUSTEE_OPERATION

Contains values that indicate whether a TRUSTEE structure is an impersonation trustee.

ObjectIdGroupId

Specifies the category or group to which an object identifier (OID) belongs.

ObjectIdPublicKeyFlags

Specifies whether a public key algorithm is used for signing or for encryption.

PFXExportOptions

Specifies how much of a certificate chain is included when creating a Personal Information Exchange (PFX) message.

Pkcs10AllowedSignatureTypes

Specifies the type of signature permitted when signing a certificate request.

PKU2U_LOGON_SUBMIT_TYPE

Indicates the type of logon message passed in a PKU2U_CERTIFICATE_S4U_LOGON structure.

POLICY_AUDIT_EVENT_TYPE

The POLICY_AUDIT_EVENT_TYPE enumeration defines values that indicate the types of events the system can audit.

POLICY_DOMAIN_INFORMATION_CLASS

Defines the type of policy domain information.

POLICY_INFORMATION_CLASS

Defines values that indicate the type of information to set or query in a Policy object.

POLICY_LSA_SERVER_ROLE

Defines values that indicate the role of an LSA server.

POLICY_NOTIFICATION_INFORMATION_CLASS

The POLICY_NOTIFICATION_INFORMATION_CLASS enumeration defines the types of policy information and policy domain
information for which your application can request notification of changes.

POLICY_SERVER_ENABLE_STATE

The POLICY_SERVER_ENABLE_STATE enumeration represents the state of the LSA server�that is, whether it is enabled or
disabled. Some operations may only be performed on an enabled LSA server.

PolicyQualifierType

Specifies the type of qualifier applied to a certificate policy.

PolicyServerUrlFlags

Contains certificate enrollment policy (CEP) server flags.

PolicyServerUrlPropertyID

Contains values that specify the type of property value to be returned by the GetStringProperty method or set by the
SetStringProperty method on the IX509PolicyServerUrl interface.

PROCESS_INFORMATION_CLASS

Indicates a specific class of process information.

PROG_INVOKE_SETTING

Indicates the initial setting of the function used to track the progress of a call to the TreeSetNamedSecurityInfo or
TreeResetNamedSecurityInfo function.

RequestClientInfoClientId

Specifies the type of application that created a certificate request.

SAFER_IDENTIFICATION_TYPES

Defines the possible types of identification rule structures that can be identified by the SAFER_IDENTIFICATION_HEADER
structure.
SAFER_OBJECT_INFO_CLASS

Defines the type of information requested about a Safer object.

SAFER_POLICY_INFO_CLASS

Defines the ways in which a policy may be queried.

SCESVC_INFO_TYPE

The SCESVC_INFO_TYPE enumeration is used by PFSCE_QUERY_INFO and PFSCE_SET_INFO to indicate the type of
information requested from or passed to the security database. It can be one of the following values.

SE_OBJECT_TYPE

Contains values that correspond to the types of Windows objects that support security.

SEC_APPLICATION_PROTOCOL_NEGOTIATION_STATUS

Describes the status of the SEC application protocol negotiation.

SECPKG_ATTR_LCT_STATUS

Indicates whether the token from the most recent call to the InitializeSecurityContext function is the last token from the client.

SECPKG_CRED_CLASS

Indicates the type of credential used in a client context. The SECPKG_CRED_CLASS enumeration is used in the
SecPkgContext_CredInfo structure.

SECPKG_EXTENDED_INFORMATION_CLASS

The SECPKG_EXTENDED_INFORMATION_CLASS enumeration describes the type of information to set or get for a security
package.This enumeration is used by the SpGetExtendedInformation and SpSetExtendedInformation functions.

SECPKG_NAME_TYPE

The SECPKG_NAME_TYPE enumeration is used to describe the type of name specified for an account.The SECPKG_NAME_TYPE
enumeration is used by the GetAuthDataForUser and OpenSamUser functions.

SECPKG_SESSIONINFO_TYPE

Specifies the format of session information.

SECURITY_IMPERSONATION_LEVEL

Contains values that specify security impersonation levels. Security impersonation levels govern the degree to which a server
process can act on behalf of a client process.

SECURITY_LOGON_TYPE

Indicates the type of logon requested by a logon process.

SERVICE_DIRECTORY_TYPE

Specifies the type of a per-service directory path.

SERVICE_REGISTRY_STATE_TYPE

Specifies a state type for a service registry key.

SERVICE_SHARED_DIRECTORY_TYPE

Specifies the type of a per-service shared directory path.

SERVICE_SHARED_REGISTRY_STATE_TYPE

Specifies a state type for a service registry key.

SI_PAGE_TYPE

Contains values that indicate the types of property pages in an access control editor property sheet.

SID_NAME_USE

Contains values that specify the type of a security identifier (SID).

SL_ACTIVATION_TYPE

Represents the type of offline activation for a license.

SL_GENUINE_STATE

Specifies the state of an application installation.

SLDATATYPE

Specifies the data type of the buffer returned by the SLGetWindowsInformation function.

SLIDTYPE

Represents the type of Software Licensing ID.

SLLICENSINGSTATUS

Represents the licensing status.

SLREFERRALTYPE

Represents the types of information that can be queried with the SLGetReferralInformation function.

TOKEN_ELEVATION_TYPE

Indicates the elevation type of token being queried by the GetTokenInformation function or set by the SetTokenInformation
function.

TOKEN_INFORMATION_CLASS

Contains values that specify the type of information being assigned to or retrieved from an access token.
TOKEN_TYPE

Contains values that differentiate between a primary token and an impersonation token.

TOKENBINDING_EXTENSION_FORMAT

Specifies the formats that are available to interpret extension data.

TOKENBINDING_TYPE

Specifies the possible types for a token binding.

TPMVSCMGR_ERROR

Provides predefined error codes to represent the contexts of errors from the TPM virtual smart card manager.

TPMVSCMGR_STATUS

Provides predefined status codes to represent the progress of the TPM virtual smart card manager.

TRUSTED_INFORMATION_CLASS

The TRUSTED_INFORMATION_CLASS enumeration type defines values that indicate the type of information to set or query for
a trusted domain.

TRUSTEE_FORM

Values that indicate the type of data pointed to by the ptstrName member of the TRUSTEE structure.

TRUSTEE_TYPE

Values that indicate the type of trustee identified by a TRUSTEE structure.

WebEnrollmentFlags

Specifies web enrollment behavior.

WebSecurityLevel

Specifies whether a web-enabled method or property is safe for scripting.

WELL_KNOWN_SID_TYPE

A list of commonly used security identifiers (SIDs). Programs can pass these values to the CreateWellKnownSid function to
create a SID from this list.

X500NameFlags

Specifies the display and encoding characteristics of a distinguished name or relative distinguished name (RDN).

X509CertificateEnrollmentContext

Specifies the nature of the end entity for which the certificate is intended.
X509CertificateTemplateEnrollmentFlag

Contains values that specify server and client actions during enrollment.

X509CertificateTemplateGeneralFlag

Contains use and modification information about templates and associated certificates.

X509CertificateTemplatePrivateKeyFlag

Contains values that specify client actions regarding a private key.

X509CertificateTemplateSubjectNameFlag

Contains values that specify server and client actions concerning subject names.

X509EnrollmentAuthFlags

Specifies the authentication type.

X509EnrollmentPolicyExportFlags

Is used by the Export method on the IX509EnrollmentPolicyServer interface to specify what items to export from the policy
server.

X509EnrollmentPolicyLoadOption

Is used by the LoadPolicy method on the IX509EnrollmentPolicyServer interface to specify how to retrieve policy from the
policy server.

X509KeySpec

Specifies the intended use of a key for a legacy cryptographic service provider (CSP).

X509KeyUsageFlags

Specifies the purpose of a key contained in a certificate.

X509PrivateKeyExportFlags

Specifies the export policy for a private key.

X509PrivateKeyProtection

Specifies the level of private key protection supported by a cryptographic provider.

X509PrivateKeyUsageFlags

Specifies the permitted uses of a private key.

X509PrivateKeyVerify

Specifies whether a user interface is displayed during private key verification and whether verification can proceed if the
cryptographic provider is a smart card provider.
 X509ProviderType

Specifies the type of cryptographic provider.

X509RequestInheritOptions

Specifies how keys, extension values, and external properties are inherited when a new request is created from an existing
certificate.

X509RequestType

Specifies the certificate request type.

X509SCEPDisposition

Describes the resulting disposition of a request to process a response message.

X509SCEPFailInfo

Describes the nature of an SCEP certificate enrollment failure.

Functions

acceptFilePKCS7

Accepts and processes a file that contains a PKCS

acceptFilePKCS7WStr

Accepts and processes a PKCS

acceptFileResponse

Accepts delivery of the credentials issued in response to an earlier call to createFileRequest, and it places the credentials in the
appropriate store.

acceptFileResponseWStr

Accepts delivery of the credentials issued in response to an earlier call to createFileRequestWStr, and it places the credentials in
the appropriate store.

acceptPKCS7

Accepts and processes a PKCS

acceptPKCS7Blob

Accepts and processes a PKCS

acceptResponse

Accepts delivery of the credentials issued in response to an earlier call to createRequest and places the credentials in the
appropriate store.
acceptResponseBlob

Accepts delivery of the credentials issued in response to an earlier call to createRequestWStr and places the credentials in the
appropriate store.

AcceptSecurityContext

Lets the server component of a transport application establish a security context between the server and a remote client.

AccessCheck

Determines whether a security descriptor grants a specified set of access rights to the client identified by an access token.

AccessCheck

Determines whether the current client context is allowed to perform the specified operations.

AccessCheck2

Returns a value that specifies whether the principal represented by the current client context is allowed to perform the
specified operation.

AccessCheckAndAuditAlarmA

Determines whether a security descriptor grants a specified set of access rights to the client being impersonated by the calling
thread.

AccessCheckAndAuditAlarmW

Determines whether a security descriptor grants a specified set of access rights to the client being impersonated by the calling
thread.

AccessCheckByType

Determines whether a security descriptor grants a specified set of access rights to the client identified by an access token.

AccessCheckByTypeAndAuditAlarmA

Determines whether a security descriptor grants a specified set of access rights to the client being impersonated by the calling
thread.

AccessCheckByTypeAndAuditAlarmW

Determines whether a security descriptor grants a specified set of access rights to the client being impersonated by the calling
thread.

AccessCheckByTypeResultList

Determines whether a security descriptor grants a specified set of access rights to the client identified by an access token.

AccessCheckByTypeResultListAndAuditAlarmA

Determines whether a security descriptor grants a specified set of access rights to the client being impersonated by the calling
thread.
AccessCheckByTypeResultListAndAuditAlarmByHandleA

Determines whether a security descriptor grants a specified set of access rights to the client that the calling thread is
impersonating.

AccessCheckByTypeResultListAndAuditAlarmByHandleW

Determines whether a security descriptor grants a specified set of access rights to the client that the calling thread is
impersonating.

AccessCheckByTypeResultListAndAuditAlarmW

Determines whether a security descriptor grants a specified set of access rights to the client being impersonated by the calling
thread.

AcquireCredentialsHandleA

The AcquireCredentialsHandle (CredSSP) function acquires a handle to preexisting credentials of a security principal.

AcquireCredentialsHandleW

The AcquireCredentialsHandle (CredSSP) function acquires a handle to preexisting credentials of a security principal.

Add

Adds an object to the collection.

Add

Adds an object to the collection.

Add

Adds an ICertificationAuthority object to the collection.

Add

Adds a property to the collection.

Add

Adds an ICryptAttribute object to the collection.

Add

Adds an ICspAlgorithm object to the collection.

Add

Adds an ICspInformation object to the collection.

Add

Adds an ICspStatus object to the collection.

Add

Adds an IObjectId object to the collection.

Add

Adds an object to the collection.

Add

Adds an ISignerCertificate object to the collection.

Add

Adds an ISmimeCapability object to the collection.

Add

Adds an IX509Attribute object to the collection.

Add

Adds an IX509CertificateTemplate object to the collection.

Add

Adds an IX509Extension object to the collection.

Add

Adds an IX509NameValuePair object to the collection.

Add

Adds an IX509PolicyServerUrl object to the collection.

Add

Adds an ICertSrvSetupKeyInformation object to the collection.

AddAccessAllowedAce

Adds an access-allowed access control entry (ACE) to an access control list (ACL). The access is granted to a specified security
identifier (SID).

AddAccessAllowedAceEx

Adds an access-allowed access control entry (ACE) to the end of a discretionary access control list (DACL).

AddAccessAllowedObjectAce

Adds an access-allowed access control entry (ACE) to the end of a discretionary access control list (DACL).
AddAccessDeniedAce

Adds an access-denied access control entry (ACE) to an access control list (ACL). The access is denied to a specified security
identifier (SID).

AddAccessDeniedAceEx

Adds an access-denied access control entry (ACE) to the end of a discretionary access control list (DACL).

AddAccessDeniedObjectAce

Adds an access-denied access control entry (ACE) to the end of a discretionary access control list (DACL). The new ACE can
deny access to an object, or to a property set or property on an object.

AddAce

Adds one or more access control entries (ACEs) to a specified access control list (ACL).

AddApplicationGroups

Adds the specified array of existing IAzApplicationGroup objects to the client context object.

AddAppMember

Adds the specified IAzApplicationGroup object to the list of application groups that belong to this application group.

AddAppMember

Adds the specified IAzApplicationGroup object to the list of application groups that belong to this role.

AddAppNonMember

Adds the specified IAzApplicationGroup object to the list of application groups that are refused membership in this application
group.

addAttributeToRequest

Adds an attribute to the certificate request. This method was first defined in the ICEnroll4 interface.

addAttributeToRequestWStr

Adds an attribute to the certificate request.

AddAuditAccessAce

Adds a system-audit access control entry (ACE) to a system access control list (ACL). The access of a specified security
identifier (SID) is audited.

AddAuditAccessAceEx

Adds a system-audit access control entry (ACE) to the end of a system access control list (SACL).

AddAuditAccessObjectAce

Adds a system-audit access control entry (ACE) to the end of a system access control list (SACL).
AddAuthenticatedAttributesToPKCS7Request

The AddAuthenticatedAttributesToPKCS7Request method adds authenticated attributes to a PKCS

AddAvailableCsps

Adds the providers installed on the computer to the collection.

AddAvailableSmimeCapabilities

Adds ISmimeCapability objects to the collection by identifying the encryption algorithms supported by the default RSA
cryptographic provider.

addBlobPropertyToCertificate

Adds a BLOB property to a certificate.

addBlobPropertyToCertificateWStr

The IEnroll4::addBlobPropertyToCertificateWStr method adds a BLOB property to a certificate.

AddCertificate

Add an endorsement key certificate to the key storage provider (KSP) that supports endorsement keys.

addCertTypeToRequest

Adds a certificate template to a request (used to support the enterprise certification authority (CA)). This method was first
defined by the ICEnroll2 interface.

addCertTypeToRequestEx

Adds a certificate template (or "certificate type") to a request.

AddCertTypeToRequestWStr

Adds a certificate template to a request (used to support the enterprise certification authority (CA)).

AddCertTypeToRequestWStrEx

Adds a certificate template (also known as certificate type) to a request.

AddConditionalAce

Adds a conditional access control entry (ACE) to the specified access control list (ACL).

AddConnectNotify

Called before and after each add connection operation (WNetAddConnection, WNetAddConnection2, and
WNetAddConnection3) is attempted by the Multiple Provider Router (MPR).

AddDelegatedPolicyUser

Adds the specified security identifier (SID) in text form to the list of principals that act as delegated policy users.
AddDelegatedPolicyUser

Adds the specified security identifier (SID) in text form to the list of principals that act as delegated policy users.

AddDelegatedPolicyUserName

Adds the specified account name to the list of principals that act as delegated policy users.

AddDelegatedPolicyUserName

Adds the specified account name to the list of principals that act as delegated policy users.

AddEnrollmentServer

Saves certificate enrollment server (CES) access credentials in the credential cache.

AddExtensionsToRequest

The AddExtensionsToRequest method adds extensions to the certificate request. This method was first defined in the IEnroll
interface.

addExtensionToRequest

The ICEnroll4::addExtensionToRequest method adds an extension to the request.

addExtensionToRequestWStr

Adds an extension to the request.

AddFromCsp

Adds objects to the collection by identifying the encryption algorithms supported by a specific cryptographic provider.

AddInterface

Adds the specified interface to the list of IDispatch interfaces that can be called by business rule (BizRule) scripts.

AddInterfaces

Adds the specified interfaces to the list of IDispatch interfaces that can be called by business rule (BizRule) scripts.

AddMandatoryAce

Adds a SYSTEM_MANDATORY_LABEL_ACE access control entry (ACE) to the specified system access control list (SACL).

AddMember

Adds the specified security identifier (SID) in text form to the list of accounts that belong to the application group.

AddMember

Adds the specified security identifier (SID) in text form to the list of Windows accounts that belong to the role.
AddMemberName

Adds the specified account name to the list of accounts that belong to the application group.

AddMemberName

Adds the specified account name to the list of accounts that belong to the role.

addNameValuePairToRequest

Adds an unauthenticated name-value string pair to the request. This method was first defined in the ICEnroll4 interface.

addNameValuePairToRequestWStr

Adds an unauthenticated name-value string pair to the request.

addNameValuePairToSignature

Adds the authenticated name-value pair of an attribute to the request. It is up to the certification authority (CA) to interpret
the meaning of the name-value pair.

AddNameValuePairToSignatureWStr

Adds the authenticated name-value pair of an attribute to the request. The certification authority (CA) interprets the meaning
of the name-value pair.

AddNonMember

Adds the specified security identifier (SID) in text form to the list of accounts that are refused membership in the application
group.

AddNonMemberName

Adds the specified account name to the list of accounts that are refused membership in the application group.

AddOperation

Adds the IAzOperation object with the specified name to the role.

AddOperation

Adds the IAzOperation object with the specified name to the task.

AddParameter

Adds a parameter to the list of parameters available to business rule (BizRule) scripts.

AddParameters

Adds parameters to the list of parameters available to business rule (BizRule) scripts.

AddPolicyAdministrator

Adds the specified security identifier (SID) in text form to the list of principals that act as policy administrators.
AddPolicyAdministrator

Adds the specified security identifier (SID) in text form to the list of principals that act as policy administrators.

AddPolicyAdministrator

The AddPolicyAdministrator method of IAzScope adds the specified security identifier in text form to the list of principals that
act as policy administrators.

AddPolicyAdministratorName

Adds the specified account name to the list of principals that act as policy administrators.

AddPolicyAdministratorName

Adds the specified account name to the list of principals that act as policy administrators.

AddPolicyAdministratorName

The AddPolicyAdministratorName method of IAzScope adds the specified account name to the list of principals that act as
policy administrators.

AddPolicyReader

Adds the specified security identifier (SID) in text form to the list of principals that act as policy readers.

AddPolicyReader

Adds the specified security identifier (SID) in text form to the list of principals that act as policy readers.

AddPolicyReader

The AddPolicyReader method of IAzScope adds the specified security identifier in text form to the list of principals that act as
policy readers.

AddPolicyReaderName

Adds the specified account name to the list of principals that act as policy readers.

AddPolicyReaderName

Adds the specified account name to the list of principals that act as policy readers.

AddPolicyReaderName

The AddPolicyReaderName method of IAzScope adds the specified account name to the list of principals that act as policy
readers.

AddPolicyServer

Registers a certificate enrollment policy (CEP) server and saves CEP access credentials in the credential cache.

AddPropertyItem

Adds the specified principal to the specified list of principals.

AddPropertyItem

Adds the specified entity to the specified list.

AddPropertyItem

Adds the specified principal to the specified list of principals.

AddPropertyItem

Adds the specified entity to the specified list.

AddPropertyItem

Adds the specified principal to the specified list of principals.

AddPropertyItem

Adds the specified entity to the specified list.

AddRange

Adds a range of ICryptAttribute objects to the collection. The attributes are contained in another ICryptAttributes collection.

AddRange

Adds a range of IObjectId objects to the collection.

AddRange

Adds a range of IX509Extension objects to the collection.

AddResourceAttributeAce

Adds a SYSTEM_RESOURCE_ATTRIBUTE_ACEaccess control entry (ACE) to the end of a system access control list (SACL).

AddRoleDefinition

Adds the specified IAzRoleDefinition object to this IAzRoleAssignment object.

AddRoleDefinition

Adds the specified IAzRoleDefinition object to this IAzRoleDefinition object.

AddRoles

Adds the specified array of existing IAzRole objects to the client context.

AddScopedPolicyIDAce

Adds a SYSTEM_SCOPED_POLICY_ID_ACEaccess control entry (ACE) to the end of a system access control list (SACL).

AddSecurityPackageA

Adds a security support provider to the list of providers supported by Microsoft Negotiate.
AddSecurityPackageW

Adds a security support provider to the list of providers supported by Microsoft Negotiate.

AddStringSids

Adds an array of string representations of security identifiers (SIDs) to the client context.

AddTask

Adds the IAzTask object with the specified name to the role.

AddTask

Adds the IAzTask object with the specified name to the task.

AddToCache

Caches the specified identity in the registry.

AdjustTokenGroups

Enables or disables groups already present in the specified access token. Access to TOKEN_ADJUST_GROUPS is required to
enable or disable groups in an access token.

AdjustTokenPrivileges

Enables or disables privileges in the specified access token. Enabling or disabling privileges in an access token requires
TOKEN_ADJUST_PRIVILEGES access.

Advise

Allows a calling application to specify the list of identity events for which the application is to be notified.

AllocateAndInitializeSid

Allocates and initializes a security identifier (SID) with up to eight subauthorities.

AllocateLocallyUniqueId

Allocates a locally unique identifier (LUID).

AppendText

Appends a string to the status information contained in the Text property.

ApplyControlToken

Provides a way to apply a control token to a security context.

AreAllAccessesGranted

Checks whether a set of requested access rights has been granted. The access rights are represented as bit flags in an access
mask.
AreAnyAccessesGranted

Tests whether any of a set of requested access rights has been granted. The access rights are represented as bit flags in an
access mask.

AssociateIdentity

Associates an identity with a local user account.

AuditComputeEffectivePolicyBySid

Computes the effective audit policy for one or more subcategories for the specified security principal. The function computes
effective audit policy by combining system audit policy with per-user policy.

AuditComputeEffectivePolicyByToken

Computes the effective audit policy for one or more subcategories for the security principal associated with the specified
token. The function computes effective audit policy by combining system audit policy with per-user policy.

AuditEnumerateCategories

Enumerates the available audit-policy categories.

AuditEnumeratePerUserPolicy

Enumerates users for whom per-user auditing policy is specified.

AuditEnumerateSubCategories

Enumerates the available audit-policy subcategories.

AuditFree

Frees the memory allocated by audit functions for the specified buffer.

AuditLookupCategoryGuidFromCategoryId

Retrieves a GUID structure that represents the specified audit-policy category.

AuditLookupCategoryIdFromCategoryGuid

Retrieves an element of the POLICY_AUDIT_EVENT_TYPE enumeration that represents the specified audit-policy category.

AuditLookupCategoryNameA

Retrieves the display name of the specified audit-policy category.

AuditLookupCategoryNameW

Retrieves the display name of the specified audit-policy category.

AuditLookupSubCategoryNameA

Retrieves the display name of the specified audit-policy subcategory.

AuditLookupSubCategoryNameW

Retrieves the display name of the specified audit-policy subcategory.

AuditQueryGlobalSaclA

Retrieves a global system access control list (SACL) that delegates access to the audit messages.

AuditQueryGlobalSaclW

Retrieves a global system access control list (SACL) that delegates access to the audit messages.

AuditQueryPerUserPolicy

Retrieves per-user audit policy in one or more audit-policy subcategories for the specified principal.

AuditQuerySecurity

Retrieves security descriptor that delegates access to audit policy.

AuditQuerySystemPolicy

Retrieves system audit policy for one or more audit-policy subcategories.

AuditSetGlobalSaclA

Sets a global system access control list (SACL) that delegates access to the audit messages.

AuditSetGlobalSaclW

Sets a global system access control list (SACL) that delegates access to the audit messages.

AuditSetPerUserPolicy

Sets per-user audit policy in one or more audit subcategories for the specified principal.

AuditSetSecurity

Sets a security descriptor that delegates access to audit policy.

AuditSetSystemPolicy

Sets system audit policy for one or more audit-policy subcategories.

AuthzAccessCheck

Determines which access bits can be granted to a client for a given set of security descriptors.

AuthzAddSidsToContext

Creates a copy of an existing context and appends a given set of security identifiers (SIDs) and restricted SIDs.
AuthzCachedAccessCheck

Performs a fast access check based on a cached handle containing the static granted bits from a previous AuthzAccessCheck
call.

AuthzEnumerateSecurityEventSources

Retrieves the registered security event sources that are not installed by default.

AuthzFreeAuditEvent

Frees the structure allocated by the AuthzInitializeObjectAccessAuditEvent function.

AuthzFreeCentralAccessPolicyCache

Decreases the CAP cache reference count by one so that the CAP cache can be deallocated.

AuthzFreeContext

Frees all structures and memory associated with the client context. The list of handles for a client is freed in this call.

AuthzFreeHandle

Finds and deletes a handle from the handle list.

AuthzFreeResourceManager

Frees a resource manager object.

AuthzGetInformationFromContext

Returns information about an Authz context.

AuthzInitializeCompoundContext

Creates a user-mode context from the given user and device security contexts.

AuthzInitializeContextFromAuthzContext

Creates a new client context based on an existing client context.

AuthzInitializeContextFromSid

Creates a user-mode client context from a user security identifier (SID).

AuthzInitializeContextFromToken

Initializes a client authorization context from a kernel token. The kernel token must have been opened for TOKEN_QUERY.

AuthzInitializeObjectAccessAuditEvent

Initializes auditing for an object.

AuthzInitializeObjectAccessAuditEvent2

Allocates and initializes an AUTHZ_AUDIT_EVENT_HANDLE handle for use with the AuthzAccessCheck function.

AuthzInitializeRemoteResourceManager

Allocates and initializes a remote resource manager. The caller can use the resulting handle to make RPC calls to a remote
instance of the resource manager configured on a server.

AuthzInitializeResourceManager

Uses Authz to verify that clients have access to various resources.

AuthzInitializeResourceManagerEx

Allocates and initializes a resource manager structure.

AuthzInstallSecurityEventSource

Installs the specified source as a security event source.

AuthzModifyClaims

Adds, deletes, or modifies user and device claims in the Authz client context.

AuthzModifySecurityAttributes

Modifies the security attribute information in the specified client context.

AuthzModifySids

Adds, deletes, or modifies user and device groups in the Authz client context.

AuthzOpenObjectAudit

Reads the system access control list (SACL) of the specified security descriptor and generates any appropriate audits specified
by that SACL.

AuthzRegisterCapChangeNotification

Registers a CAP update notification callback.

AuthzRegisterSecurityEventSource

Registers a security event source with the Local Security Authority (LSA).

AuthzReportSecurityEvent

Generates a security audit for a registered security event source.

AuthzReportSecurityEventFromParams

Generates a security audit for a registered security event source by using the specified array of audit parameters.
AuthzSetAppContainerInformation

Sets the app container and capability information in a current Authz context.

AuthzUninstallSecurityEventSource

Removes the specified source from the list of valid security event sources.

AuthzUnregisterCapChangeNotification

Removes a previously registered CAP update notification callback.

AuthzUnregisterSecurityEventSource

Unregisters a security event source with the Local Security Authority (LSA).

BCRYPT_INIT_AUTH_MODE_INFO

Initializes a BCRYPT_AUTHENTICATED_CIPHER_MODE_INFO structure for use in calls to BCryptEncrypt and BCryptDecrypt

functions.

BCryptAddContextFunction

Adds a cryptographic function to the list of functions that are supported by an existing CNG context.

BCryptCloseAlgorithmProvider

Closes an algorithm provider.

BCryptConfigureContext

Sets the configuration information for an existing CNG context.

BCryptConfigureContextFunction

Sets the configuration information for the cryptographic function of an existing CNG context.

BCryptCreateContext

Creates a new CNG configuration context.

BCryptCreateHash

Called to create a hash or Message Authentication Code (MAC) object.

BCryptCreateMultiHash

The BCryptCreateMultiHash function creates a multi-hash state that allows for the parallel computation of multiple hash
operations.

BCryptDecrypt

Decrypts a block of data.

BCryptDeleteContext

Deletes an existing CNG configuration context.

BCryptDeriveKey

Derives a key from a secret agreement value.

BCryptDeriveKeyCapi

Derives a key from a hash value.

BCryptDeriveKeyPBKDF2

Derives a key from a hash value by using the PBKDF2 key derivation algorithm as defined by RFC 2898.

BCryptDestroyHash

Destroys a hash or Message Authentication Code (MAC) object.

BCryptDestroyKey

Destroys a key.

BCryptDestroySecret

Destroys a secret agreement handle that was created by using the BCryptSecretAgreement function.

BCryptDuplicateHash

Duplicates an existing hash or Message Authentication Code (MAC) object.

BCryptDuplicateKey

Creates a duplicate of a symmetric key.

BCryptEncrypt

Encrypts a block of data.

BCryptEnumAlgorithms

Gets a list of the registered algorithm identifiers.

BCryptEnumContextFunctionProviders

Obtains the providers for the cryptographic functions for a context in the specified configuration table.

BCryptEnumContextFunctions

Obtains the cryptographic functions for a context in the specified configuration table.

BCryptEnumContexts

Obtains the identifiers of the contexts in the specified configuration table.

BCryptEnumProviders

Obtains all of the CNG providers that support a specified algorithm.

BCryptEnumRegisteredProviders

Retrieves information about the registered providers.

BCryptExportKey

Exports a key to a memory BLOB that can be persisted for later use.

BCryptFinalizeKeyPair

Completes a public/private key pair.

BCryptFinishHash

Retrieves the hash or Message Authentication Code (MAC) value for the data accumulated from prior calls to
BCryptHashData.

BCryptFreeBuffer

Used to free memory that was allocated by one of the CNG functions.

BCryptGenerateKeyPair

Creates an empty public/private key pair.

BCryptGenerateSymmetricKey

Creates a key object for use with a symmetrical key encryption algorithm from a supplied key.

BCryptGenRandom

Generates a random number.

BCryptGetFipsAlgorithmMode

Determines whether Federal Information Processing Standard (FIPS) compliance is enabled.

BCryptGetProperty

Retrieves the value of a named property for a CNG object.

BCryptHash

Performs a single hash computation. This is a convenience function that wraps calls to BCryptCreateHash, BCryptHashData,
BCryptFinishHash, and BCryptDestroyHash.

BCryptHashData

Performs a one way hash or Message Authentication Code (MAC) on a data buffer.
BCryptImportKey

Imports a symmetric key from a key BLOB.

BCryptImportKeyPair

Imports a public/private key pair from a key BLOB.

BCryptKeyDerivation

Derives a key without requiring a secret agreement.

BCryptOpenAlgorithmProvider

Loads and initializes a CNG provider.

BCryptProcessMultiOperations

The BCryptProcessMultiOperations function processes a sequence of operations on a multi-object state.

BCryptQueryContextConfiguration

Retrieves the current configuration for the specified CNG context.

BCryptQueryContextFunctionConfiguration

Obtains the cryptographic function configuration information for an existing CNG context.

BCryptQueryContextFunctionProperty

Obtains the value of a named property for a cryptographic function in an existing CNG context.

BCryptQueryProviderRegistration

Retrieves information about a CNG provider.

BCryptRegisterConfigChangeNotify

Creates a user mode CNG configuration change event handler.

BCryptRemoveContextFunction

Removes a cryptographic function from the list of functions that are supported by an existing CNG context.

BCryptResolveProviders

Obtains a collection of all of the providers that meet the specified criteria.

BCryptSecretAgreement

Creates a secret agreement value from a private and a public key.

BCryptSetContextFunctionProperty

Sets the value of a named property for a cryptographic function in an existing CNG context.
BCryptSetProperty

Sets the value of a named property for a CNG object.

BCryptSignHash

Creates a signature of a hash value.

BCryptUnregisterConfigChangeNotify

Removes a user mode CNG configuration change event handler that was created by using the
BCryptRegisterConfigChangeNotify(HANDLE*) function.

BCryptVerifySignature

Verifies that the specified signature matches the specified hash.

binaryBlobToString

Converts a binary data BLOB to a string. This method uses the CryptBinaryToString function to perform the conversion. This
method was first defined in the IEnroll4 interface.

binaryToString

Converts a binary data BLOB to a string. This method was first defined in the ICEnroll4 interface.

BizruleGroupSupported

Returns a Boolean value that specifies whether this IAzAuthorizationStore3 object supports application groups that use
business rule (BizRule) scripts.

BuildExplicitAccessWithNameA

Initializes an EXPLICIT_ACCESS structure with data specified by the caller. The trustee is identified by a name string.

BuildExplicitAccessWithNameW

Initializes an EXPLICIT_ACCESS structure with data specified by the caller. The trustee is identified by a name string.

BuildSecurityDescriptorA

Allocates and initializes a new security descriptor.

BuildSecurityDescriptorW

Allocates and initializes a new security descriptor.

BuildTrusteeWithNameA

Initializes a TRUSTEE structure. The caller specifies the trustee name. The function sets other members of the structure to
default values.

BuildTrusteeWithNameW

Initializes a TRUSTEE structure. The caller specifies the trustee name. The function sets other members of the structure to
default values.
BuildTrusteeWithObjectsAndNameA

Initializes a TRUSTEE structure with the object-specific access control entry (ACE) information and initializes the remaining
members of the structure to default values. The caller also specifies the name of the trustee.

BuildTrusteeWithObjectsAndNameW

Initializes a TRUSTEE structure with the object-specific access control entry (ACE) information and initializes the remaining
members of the structure to default values. The caller also specifies the name of the trustee.

BuildTrusteeWithObjectsAndSidA

Initializes a TRUSTEE structure with the object-specific access control entry (ACE) information and initializes the remaining
members of the structure to default values.

BuildTrusteeWithObjectsAndSidW

Initializes a TRUSTEE structure with the object-specific access control entry (ACE) information and initializes the remaining
members of the structure to default values.

BuildTrusteeWithSidA

Initializes a TRUSTEE structure. The caller specifies the security identifier (SID) of the trustee. The function sets other members
of the structure to default values and does not look up the name associated with the SID.

BuildTrusteeWithSidW

Initializes a TRUSTEE structure. The caller specifies the security identifier (SID) of the trustee. The function sets other members
of the structure to default values and does not look up the name associated with the SID.

CAImportPFX

Imports a certification authority (CA) certificate and its associated private key into the local computer store.

CancelConnectNotify

Calls CancelConnectNotify before and after each cancel connection operation (WNetCancelConnection and
WNetCancelConnection2).

CertAddCertificateContextToStore

Adds a certificate context to the certificate store.

CertAddCertificateLinkToStore

Adds a link in a certificate store to a certificate context in a different store.

CertAddCRLContextToStore

Adds a certificate revocation list (CRL) context to the specified certificate store.

CertAddCRLLinkToStore

Adds a link in a store to a certificate revocation list (CRL) context in a different store.
CertAddCTLContextToStore

Adds a certificate trust list (CTL) context to a certificate store.

CertAddCTLLinkToStore

The CertAddCTLLinkToStore function adds a link in a store to a certificate trust list (CTL) context in a different store. Instead of
creating and adding a duplicate of a CTL context, this function adds a link to the original CTL context.

CertAddEncodedCertificateToStore

Creates a certificate context from an encoded certificate and adds it to the certificate store.

CertAddEncodedCertificateToSystemStoreA

Opens the specified system store and adds the encoded certificate to it.

CertAddEncodedCertificateToSystemStoreW

Opens the specified system store and adds the encoded certificate to it.

CertAddEncodedCRLToStore

Creates a certificate revocation list (CRL) context from an encoded CRL and adds it to the certificate store.

CertAddEncodedCTLToStore

Creates a certificate trust list (CTL) context from an encoded CTL and adds it to the certificate store.

CertAddEnhancedKeyUsageIdentifier

The CertAddEnhancedKeyUsageIdentifier function adds a usage identifier object identifier (OID) to the enhanced key usage
(EKU) extended property of the certificate.

CertAddRefServerOcspResponse

Increments the reference count for an HCERT_SERVER_OCSP_RESPONSE handle.

CertAddRefServerOcspResponseContext

Increments the reference count for a CERT_SERVER_OCSP_RESPONSE_CONTEXT structure.

CertAddSerializedElementToStore

Adds a serialized certificate, certificate revocation list (CRL), or certificate trust list (CTL) element to the store.

CertAddStoreToCollection

The CertAddStoreToCollection function adds a sibling certificate store to a collection certificate store.

CertAlgIdToOID

Converts a CryptoAPI algorithm identifier (ALG_ID) to an Abstract Syntax Notation One (ASN.1) object identifier (OID) string.
CertCloseServerOcspResponse

Closes an online certificate status protocol (OCSP) server response handle.

CertCloseStore

Closes a certificate store handle and reduces the reference count on the store.

CertCompareCertificate

Determines whether two certificates are identical by comparing the issuer name and serial number of the certificates.

CertCompareCertificateName

The CertCompareCertificateName function compares two certificate CERT_NAME_BLOB structures to determine whether they
are identical. The CERT_NAME_BLOB structures are used for the subject and the issuer of certificates.

CertCompareIntegerBlob

The CertCompareIntegerBlob function compares two integer BLOBs to determine whether they represent equal numeric
values.

CertComparePublicKeyInfo

The CertComparePublicKeyInfo function compares two encoded public keys to determine whether they are identical.

CertControlStore

Allows an application to be notified when there is a difference between the contents of a cached store in use and the contents
of that store as it is persisted to storage.

CertCreateCertificateChainEngine

The CertCreateCertificateChainEngine function creates a new, nondefault chain engine for an application.

CertCreateCertificateContext

Creates a certificate context from an encoded certificate. The created context is not persisted to a certificate store. The
function makes a copy of the encoded certificate within the created context.

CertCreateContext

Creates the specified context from the encoded bytes. The context created does not include any extended properties.

CertCreateCRLContext

The CertCreateCRLContext function creates a certificate revocation list (CRL) context from an encoded CRL. The created
context is not persisted to a certificate store. It makes a copy of the encoded CRL within the created context.

CertCreateCTLContext

The CertCreateCTLContext function creates a certificate trust list (CTL) context from an encoded CTL. The created context is
not persisted to a certificate store. The function makes a copy of the encoded CTL within the created context.
CertCreateCTLEntryFromCertificateContextProperties

The CertCreateCTLEntryFromCertificateContextProperties function creates a certificate trust list (CTL) entry whose attributes
are the properties of the certificate context. The SubjectIdentifier in the CTL entry is the SHA1 hash of the certificate.

CertCreateSelfSignCertificate

Builds a self-signed certificate and returns a pointer to a CERT_CONTEXT structure that represents the certificate.

CertDeleteCertificateFromStore

The CertDeleteCertificateFromStore function deletes the specified certificate context from the certificate store.

CertDeleteCRLFromStore

The CertDeleteCRLFromStore function deletes the specified certificate revocation list (CRL) context from the certificate store.

CertDeleteCTLFromStore

The CertDeleteCTLFromStore function deletes the specified certificate trust list (CTL) context from a certificate store.

CertDuplicateCertificateChain

The CertDuplicateCertificateChain function duplicates a pointer to a certificate chain by incrementing the chain's reference
count.

CertDuplicateCertificateContext

Duplicates a certificate context by incrementing its reference count.

CertDuplicateCRLContext

The CertDuplicateCRLContext function duplicates a certificate revocation list (CRL) context by incrementing its reference count.

CertDuplicateCTLContext

The CertDuplicateCTLContext function duplicates a certificate trust list (CTL) context by incrementing its reference count.

CertDuplicateStore

Duplicates a store handle by incrementing the store's reference count.

CertEnumCertificateContextProperties

The CertEnumCertificateContextProperties function retrieves the first or next extended property associated with a certificate
context.

CertEnumCertificatesInStore

Retrieves the first or next certificate in a certificate store. Used in a loop, this function can retrieve in sequence all certificates in
a certificate store.

CertEnumCRLContextProperties

The CertEnumCRLContextProperties function retrieves the first or next extended property associated with a certificate
revocation list (CRL) context.
CertEnumCRLsInStore

The CertEnumCRLsInStore function retrieves the first or next certificate revocation list (CRL) context in a certificate store. Used
in a loop, this function can retrieve in sequence all CRL contexts in a certificate store.

CertEnumCTLContextProperties

The CertEnumCTLContextProperties function retrieves the first or next extended property associated with a certificate trust list
(CTL) context. Used in a loop, this function can retrieve in sequence all extended properties associated with a CTL context.

CertEnumCTLsInStore

The CertEnumCTLsInStore function retrieves the first or next certificate trust list (CTL) context in a certificate store. Used in a
loop, this function can retrieve in sequence all CTL contexts in a certificate store.

CertEnumPhysicalStore

The CertEnumPhysicalStore function retrieves the physical stores on a computer. The function calls the provided callback
function for each physical store found.

CertEnumSubjectInSortedCTL

Retrieves the first or next TrustedSubject in a sorted certificate trust list (CTL).

CertEnumSystemStore

The CertEnumSystemStore function retrieves the system stores available. The function calls the provided callback function for
each system store found.

CertEnumSystemStoreLocation

The CertEnumSystemStoreLocation function retrieves all of the system store locations. The function calls the provided callback
function for each system store location found.

CertFindAttribute

The CertFindAttribute function finds the first attribute in the CRYPT_ATTRIBUTE array, as identified by its object identifier
(OID).

CertFindCertificateInCRL

The CertFindCertificateInCRL function searches the certificate revocation list (CRL) for the specified certificate.

CertFindCertificateInStore

Finds the first or next certificate context in a certificate store that matches a search criteria established by the dwFindType and
its associated pvFindPara.

CertFindChainInStore

Finds the first or next certificate in a store that meets the specified criteria.

CertFindCRLInStore

Finds the first or next certificate revocation list (CRL) context in a certificate store that matches a search criterion established
by the dwFindType parameter and the associated pvFindPara parameter.
CertFindCTLInStore

Finds the first or next certificate trust list (CTL) context that matches search criteria established by the dwFindType and its
associated pvFindPara.

CertFindExtension

The CertFindExtension function finds the first extension in the CERT_EXTENSION array, as identified by its object identifier
(OID).

CertFindRDNAttr

The CertFindRDNAttr function finds the first RDN attribute identified by its object identifier (OID) in a list of the Relative
Distinguished Names (RDN).

CertFindSubjectInCTL

The CertFindSubjectInCTL function attempts to find the specified subject in a certificate trust list (CTL).

CertFindSubjectInSortedCTL

The CertFindSubjectInSortedCTL function attempts to find the specified subject in a sorted certificate trust list (CTL).

CertFreeCertificateChain

The CertFreeCertificateChain function frees a certificate chain by reducing its reference count. If the reference count becomes
zero, memory allocated for the chain is released.

CertFreeCertificateChainEngine

The CertFreeCertificateChainEngine function frees a certificate trust engine.

CertFreeCertificateChainList

Frees the array of pointers to chain contexts.

CertFreeCertificateContext

Frees a certificate context by decrementing its reference count. When the reference count goes to zero,
CertFreeCertificateContext frees the memory used by a certificate context.

CertFreeCRLContext

Frees a certificate revocation list (CRL) context by decrementing its reference count.

CertFreeCTLContext

Frees a certificate trust list (CTL) context by decrementing its reference count.

CertFreeServerOcspResponseContext

Decrements the reference count for a CERT_SERVER_OCSP_RESPONSE_CONTEXT structure.

CertGetCertificateChain

Builds a certificate chain context starting from an end certificate and going back, if possible, to a trusted root certificate.
CertGetCertificateContextProperty

Retrieves the information contained in an extended property of a certificate context.

CertGetCRLContextProperty

Gets an extended property for the specified certificate revocation list (CRL) context.

CertGetCRLFromStore

Gets the first or next certificate revocation list (CRL) context from the certificate store for the specified issuer.

CertGetCTLContextProperty

Retrieves an extended property of a certificate trust list (CTL) context.

CertGetEnhancedKeyUsage

Returns information from the enhanced key usage (EKU) extension or the EKU extended property of a certificate.

CertGetIntendedKeyUsage

Acquires the intended key usage bytes from a certificate.

CertGetIssuerCertificateFromStore

Retrieves the certificate context from the certificate store for the first or next issuer of the specified subject certificate. The new
Certificate Chain Verification Functions are recommended instead of the use of this function.

CertGetNameStringA

Obtains the subject or issuer name from a certificate CERT_CONTEXT structure and converts it to a null-terminated character
string.

CertGetNameStringW

Obtains the subject or issuer name from a certificate CERT_CONTEXT structure and converts it to a null-terminated character
string.

CertGetPublicKeyLength

The CertGetPublicKeyLength function acquires the bit length of public/private keys from a public key BLOB.

CertGetServerOcspResponseContext

Retrieves a non-blocking, time valid online certificate status protocol (OCSP) response context for the specified handle.

CertGetStoreProperty

Retrieves a store property.

CertGetSubjectCertificateFromStore

Returns from a certificate store a subject certificate context uniquely identified by its issuer and serial number.
CertGetValidUsages

Returns an array of usages that consist of the intersection of the valid usages for all certificates in an array of certificates.

CertIsRDNAttrsInCertificateName

The CertIsRDNAttrsInCertificateName function compares the attributes in the certificate name with the specified CERT_RDN to
determine whether all attributes are included there.

CertIsStrongHashToSign

Determines whether the specified hash algorithm and the public key in the signing certificate can be used to perform strong
signing.

CertIsValidCRLForCertificate

The CertIsValidCRLForCertificate function checks a CRL to find out if it is a CRL that would include a specific certificate if that
certificate were revoked.

CertModifyCertificatesToTrust

Modifies the set of certificates in a certificate trust list (CTL) for a given purpose.

CertNameToStrA

Converts an encoded name in a CERT_NAME_BLOB structure to a null-terminated character string.

CertNameToStrW

Converts an encoded name in a CERT_NAME_BLOB structure to a null-terminated character string.

CertOIDToAlgId

Use the CryptFindOIDInfo function instead of this function because ALG_ID identifiers are no longer supported in CNG.

CertOpenServerOcspResponse

Opens a handle to an online certificate status protocol (OCSP) response associated with a server certificate chain.

CertOpenStore

Opens a certificate store by using a specified store provider type.

CertOpenSystemStoreA

Opens the most common system certificate store. To open certificate stores with more complex requirements, such as file-
based or memory-based stores, use CertOpenStore.

CertOpenSystemStoreW

Opens the most common system certificate store. To open certificate stores with more complex requirements, such as file-
based or memory-based stores, use CertOpenStore.

CertRDNValueToStrA

The CertRDNValueToStr function converts a name in a CERT_RDN_VALUE_BLOB to a null-terminated character string.

CertRDNValueToStrW

The CertRDNValueToStr function converts a name in a CERT_RDN_VALUE_BLOB to a null-terminated character string.

CertRegisterPhysicalStore

Adds a physical store to a registry system store collection.

CertRegisterSystemStore

Registers a system store.

CertRemoveEnhancedKeyUsageIdentifier

The CertRemoveEnhancedKeyUsageIdentifier function removes a usage identifier object identifier (OID) from the enhanced key
usage (EKU) extended property of the certificate.

CertRemoveStoreFromCollection

Removes a sibling certificate store from a collection store.

CertResyncCertificateChainEngine

Resyncs the certificate chain engine, which resynchronizes the stores the store's engine and updates the engine caches.

CertRetrieveLogoOrBiometricInfo

Performs a URL retrieval of logo or biometric information specified in either the szOID_LOGOTYPE_EXT or
szOID_BIOMETRIC_EXT certificate extension.

CertSaveStore

Saves the certificate store to a file or to a memory BLOB.

CertSelectCertificateA

Presents a dialog box that allows the user to select certificates from a set of certificates that match the given criteria.

CertSelectCertificateChains

Retrieves certificate chains based on specified selection criteria.

CertSelectCertificateW

Presents a dialog box that allows the user to select certificates from a set of certificates that match the given criteria.

CertSelectionGetSerializedBlob

A helper function used to retrieve a serialized certificate BLOB from a CERT_SELECTUI_INPUT structure.

CertSerializeCertificateStoreElement

The CertSerializeCertificateStoreElement function serializes a certificate context's encoded certificate and its encoded
properties. The result can be persisted to storage so that the certificate and properties can be retrieved at a later time.
CertSerializeCRLStoreElement

The CertSerializeCRLStoreElement function serializes an encoded certificate revocation list (CRL) context and the encoded
representation of its properties.

CertSerializeCTLStoreElement

The CertSerializeCTLStoreElement function serializes an encoded certificate trust list (CTL) context and the encoded
representation of its properties. The result can be persisted to storage so that the CTL and properties can be retrieved later.

CertSetCertificateContextPropertiesFromCTLEntry

Sets the properties on the certificate context by using the attributes in the specified certificate trust list (CTL) entry.

CertSetCertificateContextProperty

Sets an extended property for a specified certificate context.

CertSetCRLContextProperty

Sets an extended property for the specified certificate revocation list (CRL) context.

CertSetCTLContextProperty

Sets an extended property for the specified certificate trust list (CTL) context.

CertSetEnhancedKeyUsage

The CertSetEnhancedKeyUsage function sets the enhanced key usage (EKU) property for the certificate.

CertSetStoreProperty

The CertSetStoreProperty function sets a store property.

CertSrvBackupClose

Closes the file opened by the CertSrvBackupOpenFile function.

CertSrvBackupEnd

Ends a Certificate Services backup session.

CertSrvBackupFree

Used to free memory allocated from certain Certificate Services Backup APIs.

CertSrvBackupGetBackupLogsW

Retrieves the list of Certificate Services log file names that need to be backed up for the given backup context.

CertSrvBackupGetDatabaseNamesW

Retrieves the list of Certificate Services database file names that need to be backed up for the given backup context.
CertSrvBackupGetDynamicFileListW

Retrieves the list of Certificate Services dynamic file names that need to be backed up for the given backup context.

CertSrvBackupOpenFileW

Opens a file for backup.

CertSrvBackupPrepareW

Used to prepare a Certificate Services server for backup operations.

CertSrvBackupRead

Reads bytes from a Certificate Services file.

CertSrvBackupTruncateLogs

Eliminates redundant records and reduces the disk storage space used by log files.

CertSrvIsServerOnlineW

Determines if a Certificate Services server is online; if the Certificate Services server is not online, backup operations will not be
successful.

CertSrvRestoreEnd

Ends a Certificate Services restore session.

CertSrvRestoreGetDatabaseLocationsW

Used both in backup and restore scenarios and retrieves the list of Certificate Services database location names for all the files
being backed up or restored.

CertSrvRestorePrepareW

Prepares a Certificate Services instance for restore operations.

CertSrvRestoreRegisterComplete

Completes a registered Certificate Services restore operation.

CertSrvRestoreRegisterThroughFile

Registers a Certificate Services restore.

CertSrvRestoreRegisterW

Registers a Certificate Services restore.

CertSrvServerControlW

Issues a service control command to programmatically stop Certificate Services.

CertStrToNameA

Converts a null-terminated X.500 string to an encoded certificate name.

CertStrToNameW

Converts a null-terminated X.500 string to an encoded certificate name.

CertUnregisterPhysicalStore

The CertUnregisterPhysicalStore function removes a physical store from a specified system store collection.
CertUnregisterPhysicalStore can also be used to delete the physical store.

CertUnregisterSystemStore

The CertUnregisterSystemStore function unregisters a specified system store.

CertVerifyCertificateChainPolicy

Checks a certificate chain to verify its validity, including its compliance with any specified validity policy criteria.

CertVerifyCRLRevocation

Check a certificate revocation list (CRL) to determine whether a subject's certificate has or has not been revoked.

CertVerifyCRLTimeValidity

The CertVerifyCRLTimeValidity function verifies the time validity of a CRL.

CertVerifyCTLUsage

Verifies that a subject is trusted for a specified usage by finding a signed and time-valid certificate trust list (CTL) with the
usage identifiers that contain the subject.

CertVerifyRevocation

Checks the revocation status of the certificates contained in the rgpvContext array. If a certificate in the list is found to be
revoked, no further checking is done.

CertVerifySubjectCertificateContext

The CertVerifySubjectCertificateContext function performs the enabled verification checks on a certificate by checking the
validity of the certificate's issuer. The new Certificate Chain Verification Functions are recommended instead of this function.

CertVerifyTimeValidity

The CertVerifyTimeValidity function verifies the time validity of a certificate.

CertVerifyValidityNesting

The CertVerifyValidityNesting function verifies that a subject certificate's time validity nests correctly within its issuer's time
validity.
CertViewPropertiesA

The CertViewProperties function displays the properties for a certificate in a user interface (UI) dialog box. This function has no
associated import library. You must use the LoadLibrary and GetProcAddress functions to dynamically link to CryptDlg.dll.

CertViewPropertiesW

The CertViewProperties function displays the properties for a certificate in a user interface (UI) dialog box. This function has no
associated import library. You must use the LoadLibrary and GetProcAddress functions to dynamically link to CryptDlg.dll.

ChangeAccountPasswordA

Changes the password for a Windows domain account by using the specified Security Support Provider.

ChangeAccountPasswordW

Changes the password for a Windows domain account by using the specified Security Support Provider.

ChangeCredential

Changes the credentials associated with the specified identity.

ChangeServiceConfig2A

Changes the optional configuration parameters of a service.

ChangeServiceConfig2W

Changes the optional configuration parameters of a service.

CheckCertificateSignature

Verifies the signature for a specified signer.

CheckCertificateSignature

Verifies the certificate signature.

CheckPublicKeySignature

Verifies the certificate signature by using the public key of the signing certificate.

CheckSignature

Verifies that the certificate request has been signed and that the signature is valid.

CheckSignature

Verifies that the certificate request has been signed and that the signature is valid.

CheckTokenCapability

Checks the capabilities of a given token.

CheckTokenMembership

Determines whether a specified security identifier (SID) is enabled in an access token.

CheckTokenMembershipEx

Determines whether the specified SID is enabled in the specified token.

Clear

Removes all objects from the collection.

Clear

Removes all objects from the collection.

Clear

Removes all ICertificationAuthority objects from the collection.

Clear

Removes all properties from the collection.

Clear

Removes all ICryptAttribute objects from the collection.

Clear

Removes all ICspAlgorithm objects from the collection.

Clear

Removes all ICspInformation objects from the collection.

Clear

Removes all ICspStatus objects from the collection.

Clear

Removes all IObjectId objects from the collection.

Clear

Removes all objects from the collection.

Clear

Removes all ISignerCertificate objects from the collection.

Clear

Removes all objects from the collection.

Clear

Removes all IX509Attribute objects from the collection.

Clear

Removes all IX509CertificateTemplate objects from the collection.

Clear

Removes all IX509Extension objects from the collection.

Clear

Removes all IX509NameValuePair objects from the collection.

Clear

Removes all IX509PolicyServerUrl objects from the collection.

Clone

Creates a copy of the attribute-enumeration sequence object in its current state.

Clone

Creates a copy of the column-enumeration sequence.

Clone

Creates a copy of the extension-enumeration sequence.

Close

Closes the endorsement key. You can only call the Close method after the Open method has been successfully called.

Close

Releases the handle of the cryptographic service provider (CSP) or the handle of the Cryptography API:_Next Generation
(CNG) key storage provider (KSP).

CloseApplication

Unloads a specified IAzApplication object from the cache.

CloseHandle

The CloseHandle method closes a handle opened during a previous call to ISceSvcAttachmentData::Initialize.

CloseServiceHandle

Closes a handle to a service control manager or service object.

Commit

Deletes a template from or saves it to Active Directory.

CompleteAuthToken

Completes an authentication token.

ComputeEffectivePermissionWithSecondarySecurity

Computes the effective permissions by using the secondary security for an object.

ComputeKeyIdentifier

Creates an identifier from a 160-bit SHA-1 hash of the public key.

ComputeSiteCosts

Is not currently used.

Configure

Displays the module user interface.

ConnectIdentity

Connects an identity to a domain user.

ControlService

Sends a control code to a service.

ControlServiceExA

Sends a control code to a service.

ControlServiceExW

Sends a control code to a service.

ConvertSecurityDescriptorToStringSecurityDescriptorA

Converts a security descriptor to a string format. You can use the string format to store or transmit the security descriptor.

ConvertSecurityDescriptorToStringSecurityDescriptorW

Converts a security descriptor to a string format. You can use the string format to store or transmit the security descriptor.

ConvertSidToStringSidA

Converts a security identifier (SID) to a string format suitable for display, storage, or transmission.

ConvertSidToStringSidW

Converts a security identifier (SID) to a string format suitable for display, storage, or transmission.
ConvertStringSecurityDescriptorToSecurityDescriptorA

Converts a string-format security descriptor into a valid, functional security descriptor.

ConvertStringSecurityDescriptorToSecurityDescriptorW

Converts a string-format security descriptor into a valid, functional security descriptor.

ConvertStringSidToSidA

Converts a string-format security identifier (SID) into a valid, functional SID. You can use this function to retrieve a SID that the
ConvertSidToStringSid function converted to string format.

ConvertStringSidToSidW

Converts a string-format security identifier (SID) into a valid, functional SID. You can use this function to retrieve a SID that the
ConvertSidToStringSid function converted to string format.

ConvertToAutoInheritPrivateObjectSecurity

Converts a security descriptor and its access control lists (ACLs) to a format that supports automatic propagation of
inheritable access control entries (ACEs).

ConvertToSid

Retrieves the security identifier (SID) associated with the specified identity and identity provider.

CopySid

Copies a security identifier (SID) to a buffer.

Create

Creates a new identity associated with the specified user name.

Create

Creates an asymmetric private key.

CreateApplication

Creates an IAzApplication object with the specified name.

CreateApplication2

Creates an IAzApplication2 object by using the specified name.

CreateApplicationGroup

Creates an IAzApplicationGroup object with the specified name.

CreateApplicationGroup

Creates an IAzApplicationGroup object with the specified name.

CreateApplicationGroup

Creates an IAzApplicationGroup object with the specified name.

CreateCAConfiguration

Creates a new certification authority (CA) configuration and adds it to the configuration set.

createFilePFX

Saves the accepted certificate chain and private key in a file in Personal Information Exchange (PFX) format. This method was
first defined in the ICEnroll4 interface.

createFilePFXWStr

Saves the accepted certificate chain and private key in a file in Personal Information Exchange (PFX) format.

createFilePKCS10

Creates a base64-encoded PKCS

createFilePKCS10WStr

Creates a base64-encoded PKCS

createFileRequest

Creates a PKCS

createFileRequestWStr

Creates a PKCS

CreateObject

Can be used to create an object in the user context on a webpage.

CreateObject

Creates an IX509EnrollmentHelper object on a webpage.

CreateOperation

Creates an IAzOperation object with the specified name.

createPFX

Saves the accepted certificate chain and private key in a Personal Information Exchange (PFX) format string. The PFX format is
also known as PKCS

CreatePFX

Creates a Personal Information Exchange (PFX) message.

createPFXWStr

Saves the accepted certificate chain and private key in a Personal Information Exchange (PFX) format string. The PFX format is
also known as PKCS

createPKCS10

Creates a base64-encoded PKCS

createPKCS10WStr

Creates a base64-encoded PKCS

CreatePKCS7RequestFromRequest

The CreatePKCS7RequestFromRequest method creates a PKCS

CreatePrivateObjectSecurity

Allocates and initializes a self-relative security descriptor for a new private object. A protected server calls this function when it
creates a new private object.

CreatePrivateObjectSecurityEx

Allocates and initializes a self-relative security descriptor for a new private object created by the resource manager calling this
function.

CreatePrivateObjectSecurityWithMultipleInheritance

Allocates and initializes a self-relative security descriptor for a new private object created by the resource manager calling this
function.

CreateProperty

Creates a new property and adds it to a property set.

createRequest

Creates a PKCS

CreateRequest

Retrieves an encoded certificate request.

CreateRequestMessage

Create a PKCS10 request message with a challenge password. The request message is in an enveloped PKCS7 encrypted with
the SCEP server encryption certificate and signed by the server signing certificate.

createRequestWStr

Creates a PKCS
CreateRestrictedToken

Creates a new access token that is a restricted version of an existing access token. The restricted token can have disabled
security identifiers (SIDs), deleted privileges, and a list of restricting SIDs.

CreateRetrieveCertificateMessage

Retrieve a previously issued certificate.

CreateRetrievePendingMessage

Create a message for certificate polling (manual enrollment).

CreateRole

Creates an IAzRole object with the specified name.

CreateRole

Creates an IAzRole object with the specified name.

CreateRoleAssignment

Creates a new IAzRoleAssignment object with the specified name.

CreateRoleAssignment

Creates a new IAzRoleAssignment object with the specified name in this scope.

CreateRoleDefinition

Creates a new IAzRoleDefinition object with the specified name.

CreateRoleDefinition

Creates a new IAzRoleDefinition object with the specified name in this scope.

CreateScope

Creates an IAzScope object with the specified name.

CreateScope2

Creates a new IAzScope2 object with the specified name.

CreateSecurityPage

Creates a basic security property page that enables the user to view and edit the access rights allowed or denied by the access
control entries (ACEs) in an object's discretionary access control list (DACL).

CreateTask

Creates an IAzTask object with the specified name.

CreateTask

Creates an IAzTask object with the specified name.

CreateVirtualSmartCard

Creates a TPM virtual smart card with the given parameters.

CreateWellKnownSid

Creates a SID for predefined aliases.

CredDeleteA

Deletes a credential from the user's credential set.

CredDeleteW

Deletes a credential from the user's credential set.

CredEnumerateA

Enumerates the credentials from the user's credential set.

CredEnumerateW

Enumerates the credentials from the user's credential set.

CredFindBestCredentialA

Searches the Credentials Management (CredMan) database for the set of generic credentials that are associated with the
current logon session and that best match the specified target resource.

CredFindBestCredentialW

Searches the Credentials Management (CredMan) database for the set of generic credentials that are associated with the
current logon session and that best match the specified target resource.

CredFree

The CredFree function frees a buffer returned by any of the credentials management functions.

CredFreeCredentialsFn

Frees memory used to store credentials used by a security package.

CredGetSessionTypes

The CredGetSessionTypes function returns the maximum persistence supported by the current logon session. A separate
maximum persistence is returned for each credential type.

CredGetTargetInfoA

The CredGetTargetInfo function retrieves all known target name information for the named target computer.
CredGetTargetInfoW

The CredGetTargetInfo function retrieves all known target name information for the named target computer.

CredIsMarshaledCredentialA

Determines whether a specified user name string is a marshaled credential previously marshaled by CredMarshalCredential.

CredIsMarshaledCredentialW

Determines whether a specified user name string is a marshaled credential previously marshaled by CredMarshalCredential.

CredIsProtectedA

Specifies whether the specified credentials are encrypted by a previous call to the CredProtect function.

CredIsProtectedW

Specifies whether the specified credentials are encrypted by a previous call to the CredProtect function.

CrediUnmarshalandDecodeStringFn

Transforms a marshaled string back into its original form, and decrypts the unmarshaled string.

CredMarshalCredentialA

The CredMarshalCredential function transforms a credential into a text string.

CredMarshalCredentialW

The CredMarshalCredential function transforms a credential into a text string.

CredMarshalTargetInfo

Serializes the specified target into an array of byte values.

CredPackAuthenticationBufferA

Converts a string user name and password into an authentication buffer.

CredPackAuthenticationBufferW

Converts a string user name and password into an authentication buffer.

CredProtectA

Encrypts the specified credentials so that only the current security context can decrypt them.

CredProtectW

Encrypts the specified credentials so that only the current security context can decrypt them.

CredReadA

Reads a credential from the user's credential set.

CredReadDomainCredentialsA

Reads the domain credentials from the user's credential set.

CredReadDomainCredentialsFn

Reads a domain credential from the Credential Manager.

CredReadDomainCredentialsW

Reads the domain credentials from the user's credential set.

CredReadFn

Reads a credential from the Credential Manager.

CredReadW

Reads a credential from the user's credential set.

CredRenameA

CredRename is no longer supported.

CredRenameW

CredRename is no longer supported.

CredUICmdLinePromptForCredentialsA

Prompts for and accepts credential information from a user working in a command-line (console) application. The name and
password typed by the user are passed back to the calling application for verification.

CredUICmdLinePromptForCredentialsW

Prompts for and accepts credential information from a user working in a command-line (console) application. The name and
password typed by the user are passed back to the calling application for verification.

CredUIConfirmCredentialsA

Is called after CredUIPromptForCredentials or CredUICmdLinePromptForCredentials, to confirm the validity of the credential

harvested.

CredUIConfirmCredentialsW

Is called after CredUIPromptForCredentials or CredUICmdLinePromptForCredentials, to confirm the validity of the credential

harvested.

CredUIParseUserNameA

The CredUIParseUserName function extracts the domain and user account name from a fully qualified user name.

CredUIParseUserNameW

The CredUIParseUserName function extracts the domain and user account name from a fully qualified user name.
CredUIPromptForCredentialsA

Creates and displays a configurable dialog box that accepts credentials information from a user.

CredUIPromptForWindowsCredentialsA

Creates and displays a configurable dialog box that allows users to supply credential information by using any credential
provider installed on the local computer.

CredUIPromptForWindowsCredentialsW

Creates and displays a configurable dialog box that allows users to supply credential information by using any credential
provider installed on the local computer.

CredUIReadSSOCredW

The CredUIReadSSOCredW function retrieves the user name for a single logon credential.

CredUIStoreSSOCredW

The CredUIStoreSSOCredW function stores a single logon credential.

CredUnmarshalCredentialA

The CredUnmarshalCredential function transforms a marshaled credential back into its original form.

CredUnmarshalCredentialW

The CredUnmarshalCredential function transforms a marshaled credential back into its original form.

CredUnPackAuthenticationBufferA

Converts an authentication buffer returned by a call to the CredUIPromptForWindowsCredentials function into a string user
name and password.

CredUnPackAuthenticationBufferW

Converts an authentication buffer returned by a call to the CredUIPromptForWindowsCredentials function into a string user
name and password.

CredUnprotectA

Decrypts credentials that were previously encrypted by using the CredProtect function.

CredUnprotectW

Decrypts credentials that were previously encrypted by using the CredProtect function.

CredWriteA

Creates a new credential or modifies an existing credential in the user's credential set.

CredWriteDomainCredentialsA

Writes domain credentials to the user's credential set.

CredWriteDomainCredentialsW

Writes domain credentials to the user's credential set.

CredWriteFn

Writes the specified credential to the Credential Manager.

CredWriteW

Creates a new credential or modifies an existing credential in the user's credential set.

CryptAcquireCertificatePrivateKey

Obtains the private key for a certificate.

CryptAcquireContextA

Used to acquire a handle to a particular key container within a particular cryptographic service provider (CSP). This returned
handle is used in calls to CryptoAPI functions that use the selected CSP.

CryptAcquireContextW

Used to acquire a handle to a particular key container within a particular cryptographic service provider (CSP). This returned
handle is used in calls to CryptoAPI functions that use the selected CSP.

CryptBinaryToStringA

Converts an array of bytes into a formatted string.

CryptBinaryToStringW

Converts an array of bytes into a formatted string.

CryptCATAdminAcquireContext

Acquires a handle to a catalog administrator context.

CryptCATAdminAcquireContext2

Acquires a handle to a catalog administrator context for a given hash algorithm and hash policy.

CryptCATAdminAddCatalog

Adds a catalog to the catalog database.

CryptCATAdminCalcHashFromFileHandle

Calculates the hash for a file.

CryptCATAdminCalcHashFromFileHandle2

Calculates the hash for a file by using the specified algorithm.

CryptCATAdminEnumCatalogFromHash

Enumerates the catalogs that contain a specified hash.

CryptCATAdminReleaseCatalogContext

Releases a handle to a catalog context previously returned by the CryptCATAdminAddCatalog function.

CryptCATAdminReleaseContext

Releases the handle previously assigned by the CryptCATAdminAcquireContext function.

CryptCATAdminRemoveCatalog

Deletes a catalog file and removes that catalog's entry from the Windows catalog database.

CryptCATAdminResolveCatalogPath

Retrieves the fully qualified path of the specified catalog.

CryptCATCatalogInfoFromContext

Retrieves catalog information from a specified catalog context.

CryptCATCDFClose

Closes a catalog definition file (CDF) and frees the memory for the corresponding CRYPTCATCDF structure.

CryptCATCDFEnumCatAttributes

Enumerates catalog-level attributes within the CatalogHeader section of a catalog definition file (CDF).

CryptCATCDFOpen

Opens an existing catalog definition file (CDF) for reading and initializes a CRYPTCATCDF structure.

CryptCATClose

Closes a catalog handle opened previously by the CryptCATOpen function.

CryptCATEnumerateAttr

Enumerates the attributes associated with a member of a catalog. This function has no associated import library.

CryptCATEnumerateCatAttr

Enumerates the attributes associated with a catalog. This function has no associated import library.

CryptCATEnumerateMember

Enumerates the members of a catalog.

CryptCATGetAttrInfo

Retrieves information about an attribute of a member of a catalog.

CryptCATGetMemberInfo

Retrieves member information from the catalog's PKCS

CryptCATHandleFromStore

Retrieves a catalog handle from memory.

CryptCATOpen

Opens a catalog and returns a context handle to the open catalog.

CryptCATPersistStore

Saves the information in the specified catalog store to an unsigned catalog file.

CryptCATPutAttrInfo

Allocates memory for an attribute and adds it to a catalog member.

CryptCATPutCatAttrInfo

Allocates memory for a catalog file attribute and adds it to the catalog.

CryptCATPutMemberInfo

Allocates memory for a catalog member and adds it to the catalog.

CryptCATStoreFromHandle

Retrieves a CRYPTCATSTORE structure from a catalog handle.

CryptContextAddRef

Adds one to the reference count of an HCRYPTPROV cryptographic service provider (CSP) handle.

CryptCreateHash

Initiates the hashing of a stream of data. It creates and returns to the calling application a handle to a cryptographic service
provider (CSP) hash object.

CryptCreateKeyIdentifierFromCSP

Important This API is deprecated.

CryptDecodeMessage

Decodes, decrypts, and verifies a cryptographic message.

CryptDecodeObject

The CryptDecodeObject function decodes a structure of the type indicated by the lpszStructType parameter. The use of
CryptDecodeObjectEx is recommended as an API that performs the same function with significant performance
improvements.
CryptDecodeObjectEx

Decodes a structure of the type indicated by the lpszStructType parameter.

CryptDecrypt

Decrypts data previously encrypted by using the CryptEncrypt function.

CryptDecryptAndVerifyMessageSignature

The CryptDecryptAndVerifyMessageSignature function decrypts a message and verifies its signature.

CryptDecryptMessage

The CryptDecryptMessage function decodes and decrypts a message.

CryptDeriveKey

Generates cryptographic session keys derived from a base data value.

CryptDestroyHash

Destroys the hash object referenced by the hHash parameter.

CryptDestroyKey

Releases the handle referenced by the hKey parameter.

CryptDuplicateHash

Makes an exact copy of a hash to the point when the duplication is done.

CryptDuplicateKey

Makes an exact copy of a key and the state of the key.

CryptEncodeObject

The CryptEncodeObject function encodes a structure of the type indicated by the value of the lpszStructType parameter. The
use of CryptEncodeObjectEx is recommended as an API that performs the same function with significant performance
improvements.

CryptEncodeObjectEx

Encodes a structure of the type indicated by the value of the lpszStructType parameter.

CryptEncrypt

Encrypts data. The algorithm used to encrypt the data is designated by the key held by the CSP module and is referenced by
the hKey parameter.

CryptEncryptMessage

The CryptEncryptMessage function encrypts and encodes a message.

CryptEnumKeyIdentifierProperties

The CryptEnumKeyIdentifierProperties function enumerates key identifiers and their properties.

CryptEnumOIDFunction

The CryptEnumOIDFunction function enumerates the registered object identifier (OID) functions.

CryptEnumOIDInfo

Enumerates predefined and registered object identifier (OID) CRYPT_OID_INFO structures. This function enumerates either all
of the predefined and registered structures or only structures identified by a selected OID group.

CryptEnumProvidersA

Important This API is deprecated.

CryptEnumProvidersW

Important This API is deprecated.

CryptEnumProviderTypesA

Retrieves the first or next types of cryptographic service provider (CSP) supported on the computer.

CryptEnumProviderTypesW

Retrieves the first or next types of cryptographic service provider (CSP) supported on the computer.

CryptExportKey

Exports a cryptographic key or a key pair from a cryptographic service provider (CSP) in a secure manner.

CryptExportPKCS8

Exports the private key in PKCS

CryptExportPKCS8Ex

Exports the private key in PKCS

CryptExportPublicKeyInfo

The CryptExportPublicKeyInfo function exports the public key information associated with the corresponding private key of
the provider. For an updated version of this function, see CryptExportPublicKeyInfoEx.

CryptExportPublicKeyInfoEx

Exports the public key information associated with the provider's corresponding private key.

CryptExportPublicKeyInfoFromBCryptKeyHandle

Exports the public key information associated with a provider's corresponding private key.
CryptFindCertificateKeyProvInfo

Enumerates the cryptographic providers and their containers to find the private key that corresponds to the certificate's public
key.

CryptFindLocalizedName

Finds the localized name for the specified name, such as the localize name of the "Root" system store.

CryptFindOIDInfo

Retrieves the first predefined or registered CRYPT_OID_INFO structure that matches a specified key type and key. The search
can be limited to object identifiers (OIDs) within a specified OID group.

CryptFormatObject

The CryptFormatObject function formats the encoded data and returns a Unicode string in the allocated buffer according to
the certificate encoding type.

CryptFreeOIDFunctionAddress

The CryptFreeOIDFunctionAddress function releases a handle returned by CryptGetOIDFunctionAddress or

CryptGetDefaultOIDFunctionAddress by decrementing the reference count on the function handle.

CryptGenKey

Generates a random cryptographic session key or a public/private key pair. A handle to the key or key pair is returned in
phKey. This handle can then be used as needed with any CryptoAPI function that requires a key handle.

CryptGenRandom

Fills a buffer with cryptographically random bytes.

CryptGetDefaultOIDDllList

The CryptGetDefaultOIDDllList function acquires the list of the names of DLL files that contain registered default object
identifier (OID) functions for a specified function set and encoding type.

CryptGetDefaultOIDFunctionAddress

The CryptGetDefaultOIDFunctionAddress function loads the DLL that contains a default function address.

CryptGetDefaultProviderA

Finds the default cryptographic service provider (CSP) of a specified provider type for the local computer or current user.

CryptGetDefaultProviderW

Finds the default cryptographic service provider (CSP) of a specified provider type for the local computer or current user.

CryptGetHashParam

Retrieves data that governs the operations of a hash object.

CryptGetKeyIdentifierProperty

The CryptGetKeyIdentifierProperty acquires a specific property from a specified key identifier.

CryptGetKeyParam

Retrieves data that governs the operations of a key.

CryptGetMessageCertificates

The CryptGetMessageCertificates function returns the handle of an open certificate store containing the message's certificates
and CRLs. This function calls CertOpenStore using provider type CERT_STORE_PROV_PKCS7 as its lpszStoreProvider parameter.

CryptGetMessageSignerCount

The CryptGetMessageSignerCount function returns the number of signers of a signed message.

CryptGetObjectUrl

Acquires the URL of the remote object from a certificate, certificate trust list (CTL), or certificate revocation list (CRL).

CryptGetOIDFunctionAddress

Searches the list of registered and installed functions for an encoding type and object identifier (OID) match.

CryptGetOIDFunctionValue

The CryptGetOIDFunctionValue function queries a value associated with an OID.

CryptGetProvParam

Retrieves parameters that govern the operations of a cryptographic service provider (CSP).

CryptGetTimeValidObject

Retrieves a CRL, an OCSP response, or CTL object that is valid within a given context and time.

CryptGetUserKey

Retrieves a handle of one of a user's two public/private key pairs.

CryptHashCertificate

The CryptHashCertificate function hashes the entire encoded content of a certificate including its signature.

CryptHashCertificate2

Hashes a block of data by using a CNG hash provider.

CryptHashData

Adds data to a specified hash object.

CryptHashMessage

Creates a hash of the message.

CryptHashPublicKeyInfo

Encodes the public key information in a CERT_PUBLIC_KEY_INFO structure and computes the hash of the encoded bytes.

CryptHashSessionKey

Computes the cryptographic hash of a session key object.

CryptHashToBeSigned

Important This API is deprecated.

CryptImportKey

Transfers a cryptographic key from a key BLOB into a cryptographic service provider (CSP).

CryptImportPKCS8

Imports the private key in PKCS

CryptImportPublicKeyInfo

Converts and imports the public key information into the provider and returns a handle of the public key.

CryptImportPublicKeyInfoEx

Important This API is deprecated.

CryptImportPublicKeyInfoEx2

Imports a public key into the CNG asymmetric provider that corresponds to the public key object identifier (OID) and returns
a CNG handle to the key.

CryptInitOIDFunctionSet

The CryptInitOIDFunctionSet initializes and returns the handle of the OID function set identified by a supplied function set
name.

CryptInstallDefaultContext

Installs a specific provider to be the default context provider for the specified algorithm.

CryptInstallOIDFunctionAddress

The CryptInstallOIDFunctionAddress function installs a set of callable object identifier (OID) function addresses.

CryptMemAlloc

The CryptMemAlloc function allocates memory for a buffer. It is used by all Crypt32.lib functions that return allocated buffers.
CryptMemFree

The CryptMemFree function frees memory allocated by CryptMemAlloc or CryptMemRealloc.

CryptMemRealloc

The CryptMemRealloc function frees the memory currently allocated for a buffer and allocates memory for a new buffer.

CryptMsgCalculateEncodedLength

Calculates the maximum number of bytes needed for an encoded cryptographic message given the message type, encoding
parameters, and total length of the data to be encoded.

CryptMsgClose

The CryptMsgClose function closes a cryptographic message handle. At each call to this function, the reference count on the
message is reduced by one. When the reference count reaches zero, the message is fully released.

CryptMsgControl

Performs a control operation after a message has been decoded by a final call to the CryptMsgUpdate function.

CryptMsgCountersign

Countersigns an existing signature in a message.

CryptMsgCountersignEncoded

Countersigns an existing PKCS

CryptMsgDuplicate

The CryptMsgDuplicate function duplicates a cryptographic message handle by incrementing its reference count.

CryptMsgEncodeAndSignCTL

The CryptMsgEncodeAndSignCTL function encodes a CTL and creates a signed message containing the encoded CTL.This
function first encodes the CTL pointed to by pCtlInfo and then calls CryptMsgSignCTL to sign the encoded message.

CryptMsgGetAndVerifySigner

The CryptMsgGetAndVerifySigner function verifies a cryptographic message's signature.

CryptMsgGetParam

Acquires a message parameter after a cryptographic message has been encoded or decoded.

CryptMsgOpenToDecode

Opens a cryptographic message for decoding and returns a handle of the opened message.

CryptMsgOpenToEncode

Opens a cryptographic message for encoding and returns a handle of the opened message.
CryptMsgSignCTL

The CryptMsgSignCTL function creates a signed message containing an encoded CTL.

CryptMsgUpdate

Adds contents to a cryptographic message.

CryptMsgVerifyCountersignatureEncoded

Verifies a countersignature in terms of the SignerInfo structure (as defined by PKCS

CryptMsgVerifyCountersignatureEncodedEx

Verifies that the pbSignerInfoCounterSignature parameter contains the encrypted hash of the encryptedDigest field of the
pbSignerInfo parameter structure.

CryptProtectData

Performs encryption on the data in a DATA_BLOB structure.

CryptProtectMemory

encrypts memory to prevent others from viewing sensitive information in your process.

CryptQueryObject

Retrieves information about the contents of a cryptography API object, such as a certificate, a certificate revocation list, or a
certificate trust list.

CryptRegisterDefaultOIDFunction

The CryptRegisterDefaultOIDFunction registers a DLL containing the default function to be called for the specified encoding
type and function name. Unlike CryptRegisterOIDFunction, the function name to be exported by the DLL cannot be
overridden.

CryptRegisterOIDFunction

Registers a DLL that contains the function to be called for the specified encoding type, function name, and object identifier
(OID).

CryptRegisterOIDInfo

The CryptRegisterOIDInfo function registers the OID information specified in the CRYPT_OID_INFO structure, persisting it to
the registry.

CryptReleaseContext

Releases the handle of a cryptographic service provider (CSP) and a key container.

CryptRetrieveObjectByUrlA

Retrieves the public key infrastructure (PKI) object from a location specified by a URL.
CryptRetrieveObjectByUrlW

Retrieves the public key infrastructure (PKI) object from a location specified by a URL.

CryptRetrieveTimeStamp

Encodes a time stamp request and retrieves the time stamp token from a location specified by a URL to a Time Stamping
Authority (TSA).

CryptSetHashParam

Customizes the operations of a hash object, including setting up initial hash contents and selecting a specific hashing
algorithm.

CryptSetKeyIdentifierProperty

The CryptSetKeyIdentifierProperty function sets the property of a specified key identifier. This function can set the property on
the computer identified in pwszComputerName.

CryptSetKeyParam

Customizes various aspects of a session key's operations.

CryptSetOIDFunctionValue

The CryptSetOIDFunctionValue function sets a value for the specified encoding type, function name, OID, and value name.

CryptSetProviderA

Specifies the current user's default cryptographic service provider (CSP).

CryptSetProviderExA

Specifies the default cryptographic service provider (CSP) of a specified provider type for the local computer or current user.

CryptSetProviderExW

Specifies the default cryptographic service provider (CSP) of a specified provider type for the local computer or current user.

CryptSetProviderW

Specifies the current user's default cryptographic service provider (CSP).

CryptSetProvParam

Customizes the operations of a cryptographic service provider (CSP). This function is commonly used to set a security
descriptor on the key container associated with a CSP to control access to the private keys in that key container.

CryptSignAndEncodeCertificate

Encodes and signs a certificate, certificate revocation list (CRL), certificate trust list (CTL), or certificate request.

CryptSignAndEncryptMessage

The CryptSignAndEncryptMessage function creates a hash of the specified content, signs the hash, encrypts the content,
hashes the encrypted contents and the signed hash, and then encodes both the encrypted content and the signed hash.
CryptSignCertificate

The CryptSignCertificate function signs the "to be signed" information in the encoded signed content.

CryptSignHashA

Signs data.

CryptSignHashW

Signs data.

CryptSignMessage

The CryptSignMessage function creates a hash of the specified content, signs the hash, and then encodes both the original
message content and the signed hash.

CryptSignMessageWithKey

Signs a message by using a CSP's private key specified in the parameters.

CryptSIPAddProvider

The CryptSIPAddProvider function registers functions that are exported by a given DLL file that implements a Subject Interface
Package (SIP).

CryptSIPCreateIndirectData

Returns a SIP_INDIRECT_DATA structure that contains a hash of the supplied SIP_SUBJECTINFO structure, the digest
algorithm, and an encoding attribute. The hash can be used as an indirect reference to the data.

CryptSIPGetCaps

Retrieves the capabilities of a subject interface package (SIP).

CryptSIPGetSignedDataMsg

Retrieves an Authenticode signature from the file.

CryptSIPLoad

Loads the dynamic-link library (DLL) that implements a subject interface package (SIP) and assigns appropriate library export
functions to a SIP_DISPATCH_INFO structure.

CryptSIPPutSignedDataMsg

Stores an Authenticode signature in the target file.

CryptSIPRemoveProvider

Removes registry details of a Subject Interface Package (SIP) DLL file added by a previous call to the CryptSIPAddProvider
function.

CryptSIPRemoveSignedDataMsg

Removes a specified Authenticode signature.

CryptSIPRetrieveSubjectGuid

Retrieves a GUID based on the header information in a specified file.

CryptSIPRetrieveSubjectGuidForCatalogFile

Retrieves the subject GUID associated with the specified file.

CryptSIPVerifyIndirectData

Validates the indirect hashed data against the supplied subject.

CryptStringToBinaryA

Converts a formatted string into an array of bytes.

CryptStringToBinaryW

Converts a formatted string into an array of bytes.

CryptUIDlgCertMgr

Displays a dialog box that allows the user to manage certificates.

CryptUIDlgSelectCertificateFromStore

Displays a dialog box that allows the selection of a certificate from a specified store.

CryptUIDlgViewCertificateA

Presents a dialog box that displays a specified certificate.

CryptUIDlgViewCertificateW

Presents a dialog box that displays a specified certificate.

CryptUIDlgViewContext

Displays a certificate, CTL, or CRL context.

CryptUIWizDigitalSign

Digitally signs a document or BLOB.

CryptUIWizExport

Exports a certificate, a certificate trust list (CTL), a certificate revocation list (CRL), or a certificate store to a file.

CryptUIWizFreeDigitalSignContext

Frees the CRYPTUI_WIZ_DIGITAL_SIGN_CONTEXT structure allocated by the CryptUIWizDigitalSign function.

CryptUIWizImport

Imports a certificate, a certificate trust list (CTL), a certificate revocation list (CRL), or a certificate store to a certificate store.
CryptUninstallDefaultContext

Important This API is deprecated.

CryptUnprotectData

Decrypts and does an integrity check of the data in a DATA_BLOB structure.

CryptUnprotectMemory

Decrypts memory that was encrypted using the CryptProtectMemory function.

CryptUnregisterDefaultOIDFunction

The CryptUnregisterDefaultOIDFunction removes the registration of a DLL containing the default function to be called for the
specified encoding type and function name.

CryptUnregisterOIDFunction

Removes the registration of a DLL that contains the function to be called for the specified encoding type, function name, and
OID.

CryptUnregisterOIDInfo

The CryptUnregisterOIDInfo function removes the registration of a specified CRYPT_OID_INFO OID information structure. The
structure to be unregistered is identified by the structure's pszOID and dwGroupId members.

CryptUpdateProtectedState

Migrates the current user's master keys after the user's security identifier (SID) has changed.

CryptVerifyCertificateSignature

Verifies the signature of a certificate, certificate revocation list (CRL), or certificate request by using the public key in a
CERT_PUBLIC_KEY_INFO structure.

CryptVerifyCertificateSignatureEx

Verifies the signature of a subject certificate, certificate revocation list, certificate request, or keygen request by using the
issuer's public key.

CryptVerifyDetachedMessageHash

The CryptVerifyDetachedMessageHash function verifies a detached hash.

CryptVerifyDetachedMessageSignature

The CryptVerifyDetachedMessageSignature function verifies a signed message containing a detached signature or signatures.

CryptVerifyMessageHash

The CryptVerifyMessageHash function verifies the hash of specified content.

CryptVerifyMessageSignature

Verifies a signed message's signature.

CryptVerifyMessageSignatureWithKey

Verifies a signed message's signature by using specified public key information.

CryptVerifySignatureA

Verifies the signature of a hash object.

CryptVerifySignatureW

Verifies the signature of a hash object.

CryptVerifyTimeStampSignature

Validates the time stamp signature on a specified array of bytes.

CryptXmlAddObject

Adds the Object element to the Signature in the Document Context opened for encoding.

CryptXmlClose

Closes a cryptographic XML object handle.

CryptXmlCreateReference

Creates a reference to an XML signature.

CryptXmlDigestReference

Is used by an application to digest the resolved reference. This function applies transforms before updating the digest.

CryptXmlDllCloseDigest

Frees the CRYPT_XML_DIGEST allocated by the CryptXmlDllCreateDigest function.

CryptXmlDllCreateDigest

Creates a digest object for the specified method.

CryptXmlDllCreateKey

Parses the KeyValue element and creates a Cryptography API:_Next Generation (CNG) BCrypt key handle to verify a signature.

CryptXmlDllDigestData

Puts data into the digest.

CryptXmlDllEncodeAlgorithm

Encodes SignatureMethod or DigestMethod elements for agile algorithms with default parameters.

CryptXmlDllEncodeKeyValue

Encodes a KeyValue element.

CryptXmlDllFinalizeDigest

Retrieves the digest value.

CryptXmlDllGetAlgorithmInfo

Decodes the XML algorithm and returns information about the algorithm.

CryptXmlDllGetInterface

Retrieves a pointer to the cryptographic extension functions for the specified algorithm.

CryptXmlDllSignData

Signs data.

CryptXmlDllVerifySignature

Verifies a signature.

CryptXmlEncode

Encodes signature data by using the supplied XML writer callback function.

CryptXmlGetAlgorithmInfo

Decodes the CRYPT_XML_ALGORITHM structure and returns information about the algorithm.

CryptXmlGetDocContext

Returns the document context specified by the supplied handle.

CryptXmlGetReference

Returns the Reference element specified by the supplied handle.

CryptXmlGetSignature

Returns an XML Signature element.

CryptXmlGetStatus

Returns a CRYPT_XML_STATUS structure that contains status information about the object specified by the supplied handle.

CryptXmlGetTransforms

Returns information about the default transform chain engine.

CryptXmlImportPublicKey

Imports the public key specified by the supplied handle.

CryptXmlOpenToDecode

Opens an XML digital signature to decode and returns the handle of the document context that encapsulates a
CRYPT_XML_SIGNATURE structure. The document context can include one or more Signature elements.

CryptXmlOpenToEncode

Opens an XML digital signature to encode and returns a handle of the opened Signature element. The handle encapsulates a
document context with a single CRYPT_XML_SIGNATURE structure and remains open until the CryptXmlClose function is
called.

CryptXmlSetHMACSecret

Sets the HMAC secret on the handle before calling the CryptXmlSign or CryptXmlVerify function.

CryptXmlSign

Creates a cryptographic signature of a SignedInfo element.

CryptXmlVerifySignature

Performs a cryptographic signature validation of a SignedInfo element.

DdqCancelDiagnosticRecordOperation

Cancels all outstanding Diagnostic Data Query API internal query operations for this session. This can be called from another
thread to interrupt long running Query APIs.

DdqCloseSession

Closes a Diagnostic Data Query session handle.

DdqCreateSession

Creates a Diagnostic Data Query API session handle to be used to uniquely identify a Diagnostic Data Query session.

DdqExtractDiagnosticReport

Used for retrieving Windows Error Reporting reports, this API extracts cabs to destination path specified. If the error report
does not contain any cabs, no work is performed.

DdqFreeDiagnosticRecordLocaleTags

Frees memory allocated for tag information referenced by HDIAGNOSTIC_EVENT_TAG_DESCRIPTION handle.

DdqFreeDiagnosticRecordPage

Frees memory allocated for the diagnostic record page referenced by HDIAGNOSTIC_RECORD handle.

DdqFreeDiagnosticRecordProducerCategories

Frees memory allocated for set of categories and the text representation of the categories referenced by
HDIAGNOSTIC_EVENT_CATEGORY_DESCRIPTION handle.
DdqFreeDiagnosticRecordProducers

Frees memory allocated for the set of producers referenced by HDIAGNOSTIC_EVENT_PRODUCER_DESCRIPTION handle.

DdqFreeDiagnosticReport

Frees memory allocated for error reports referenced by HDIAGNOSTIC_REPORT_DATA handle.

DdqGetDiagnosticDataAccessLevelAllowed

Returns the highest available data access level for the API caller. This can be NoData, CurrentUserData or AllUserData.

DdqGetDiagnosticRecordAtIndex

Fetches diagnostic data record information at the specified index in the resource pointed to by the
HDIAGNOSTIC_DATA_RECORD handle.

DdqGetDiagnosticRecordBinaryDistribution

Fetches binary name and associated estimated total upload of Diagnostic Data Events volume in bytes for top N noisiest
binaries based on total estimated upload size, where N is the value passed in for topNBinaries.

DdqGetDiagnosticRecordCategoryAtIndex

Fetches a diagnostic record category at the specified index in the resource pointed to by the
HDIAGNOSTIC_DATA_EVENT_CATEGORY_DESCRIPTION handle.

DdqGetDiagnosticRecordCategoryCount

Fetches the number (size) of diagnostic record categories in the resource pointed by the
HDIAGNOSTIC_EVENT_CATEGORY_DESCRIPTION handle.

DdqGetDiagnosticRecordCount

Fetches number (size) of elements in the resource pointed to by the HDIAGNOSTIC_DATA_RECORD handle.

DdqGetDiagnosticRecordLocaleTagAtIndex

Fetches tag description at the specified index in the resource pointed to by the
HDIAGNOSTIC_DATA_EVENT_TAG_DESCRIPTION handle.

DdqGetDiagnosticRecordLocaleTagCount

Fetches the number (size) of tags in the resource pointed to by the HDIAGNOSTIC_DATA_EVENT_TAG_DESCRIPTION handle.

DdqGetDiagnosticRecordLocaleTags

Fetches information for all known tags under the specified locale and provides a handle,
HDIAGNOSTIC_EVENT_TAG_DESCRIPTION, to the data. An example locale would be “en-US”. An example return value is a
DIAGNOSTIC_EVENT_TAG_DESCRIPTION resource that contains the following data: tag: 11, name: “Device Connectivity and
Configuration” and description: “Data that describes the connections and configuration of the devices connected to the service
and the network, including device identifiers (e.g IP addresses) configuration, setting and performance”.
DdqGetDiagnosticRecordPage

Fetches a page (batch) of filtered records. The filtering on records returned is performed internally using the input parameters
DIAGNOSTIC_DATA_SEARCH_CRITERIA searchCriteria, pageRecordCount, offset and baseRowId.

DdqGetDiagnosticRecordPayload

Fetches the payload text for the event record specified by rowId.

DdqGetDiagnosticRecordProducerAtIndex

Fetches the description of a producer at the specified index in the resource pointed to by the
HDIAGNOSTIC_EVENT_PRODUCER_DESCRIPTION handle.

DdqGetDiagnosticRecordProducerCategories

Producers and categories have a hierarchical relationship--that is, categories belong to producers. This function fetches the
available Category IDs and text representation of categories for a given diagnostic Producer Name.

DdqGetDiagnosticRecordProducerCount

Fetches the number (size) of producers in the resource pointed to by the HDIAGNOSTIC_EVENT_PRODUCER_DESCRIPTION.

DdqGetDiagnosticRecordProducers

Fetches Diagnostic Data Producers available for a Diagnostic Data Query session.

DdqGetDiagnosticRecordStats

Fetches the filtered event transcript Diagnostic Data record stats. The filtering on statistics returned is performed using the
input parameter, DIAGNOSTIC_DATA_SEARCH_CRITERIA filter. The record state describes how many records matching the
search criteria are available, and returns parameters used for further querying of data. One of the uses of this API is to check if
there have been changes since the last time data was queried for. A change in the output parameters indicate a change in
state of the event transcript record state.

DdqGetDiagnosticRecordSummary

Fetches general statistics about the diagnostic data records, filterable by producer.

DdqGetDiagnosticRecordTagDistribution

Fetches Diagnostic Data Events per privacy tag event distribution statistics based on the specified producer names.

DdqGetDiagnosticReport

Fetches error reports uploaded or enqueued for upload from this PC via HDIAGNOSTIC_REPORT_DATA handle.

DdqGetDiagnosticReportAtIndex

Fetches an error report and its information at the specified index in the resource pointed to by the
HDIAGNOSTIC_REPORT_DATA handle.

DdqGetDiagnosticReportCount

Fetches the number (size) of error reports in the resource pointed to by HDIAGNOSTIC_REPORT_DATA handle.
DdqGetDiagnosticReportStoreReportCount

Fetches the number (size) of reports stored in the requested store.

DdqGetSessionAccessLevel

Returns the data access level of the current Diagnostic Data Query session.

DdqGetTranscriptConfiguration

Gets event transcript configuration, such as maximum storage size and hours of data history.

DdqIsDiagnosticRecordSampledIn

Fetches the sampled-in state of the device for an event.

DdqSetTranscriptConfiguration

Sets event transcript configuration, such as maximum storage size and hours of data history. Note that setting the
configuration will fail if the user is not elevated.

Decode

Initializes the object from a Unicode-encoded distinguished name.

Decode

Decodes an Abstract Syntax Notation One (ASN.1)-encoded alternate name extension and stores the resulting array of strings
in the CertEncodeAltName object.

Decode

Decodes an Abstract Syntax Notation One (ASN.1)-encoded bit string and stores the resulting bit string in this object.

Decode

Decodes an Abstract Syntax Notation One (ASN.1)-encoded certificate revocation list (CRL) distribution information extension
and stores the resulting array in the COM object.

Decode

Decodes an Abstract Syntax Notation One (ASN.1)-encoded date array and stores the resulting array of date values in the
CertEncodeDateArray object.

Decode

Decodes an Abstract Syntax Notation One (ASN.1)-encoded Long array and stores the resulting array of Long values in the
CertEncodeLongArray object.

Decode

Decodes an Abstract Syntax Notation One (ASN.1)-encoded string array and stores the resulting array of strings in the
CertEncodeStringArray object.
DecryptChallenge

Decrypts the challenge from the Certificate Management over CMS (CMC) response and creates a re-encrypted response to
send to the CA.

DecryptMessage

Decrypts a message by using Digest.

Delete

Removes the specified identity from the identity store or the specified properties from the identity.

Delete

Deletes the policy store currently in use by the AzAuthorizationStore object.

Delete

Releases the handle of the cryptographic service provider (CSP) or the handle of the Cryptography API:_Next Generation
(CNG) key storage provider (KSP) and deletes the key from disk or smart card.

DeleteAce

Deletes an access control entry (ACE) from an access control list (ACL).

DeleteApplication

Removes the IAzApplication object with the specified name from the AzAuthorizationStore object.

DeleteApplicationGroup

Removes the IAzApplicationGroup object with the specified name from the IAzApplication object.

DeleteApplicationGroup

Removes the IAzApplicationGroup object with the specified name from the AzAuthorizationStore object.

DeleteApplicationGroup

Removes the IAzApplicationGroup object with the specified name from the IAzScope object.

DeleteAppMember

Removes the specified IAzApplicationGroup object from the list of application groups that belong to this application group.

DeleteAppMember

Removes the specified IAzApplicationGroup object from the list of application groups that belong to the role.

DeleteAppNonMember

Removes the specified IAzApplicationGroup object from the list of application groups that are refused membership in this
application group.
DeleteCAConfiguration

Removes a named certification authority (CA) configuration from the configuration set.

DeleteDelegatedPolicyUser

The IAzApplication::DeleteDelegatedPolicyUser method removes the specified security identifier in text form from the list of
principals that act as delegated policy users.

DeleteDelegatedPolicyUser

Removes the specified security identifier (SID) in text form from the list of principals that act as delegated policy users.

DeleteDelegatedPolicyUserName

Removes the specified account name from the list of principals that act as delegated policy users.

DeleteDelegatedPolicyUserName

Removes the specified account name from the list of principals that act as delegated policy users.

DeleteMember

Removes the specified security identifier (SID) in text form from the list of accounts that belong to the application group.

DeleteMember

Removes the specified security identifier (SID) in text form from the list of Windows accounts that belong to the role.

DeleteMemberName

Removes the specified account name from the list of accounts that belong to the application group.

DeleteMemberName

Removes the specified account name from the list of accounts that belong to the role.

DeleteNonMember

Removes the specified security identifier (SID) in text form from the list of accounts that are refused membership in the
application group.

DeleteNonMemberName

Removes the specified account name from the list of accounts that are refused membership in the application group.

DeleteOperation

Removes the IAzOperation object with the specified name from the IAzApplication object.

DeleteOperation

Removes the IAzOperation object with the specified name from the role.
DeleteOperation

Removes the IAzOperation object with the specified name from the task.

DeletePolicyAdministrator

The DeletePolicyAdministrator method of IAzApplication removes the specified security identifier in text form from the list of
principals that act as policy administrators.

DeletePolicyAdministrator

Removes the specified security identifier (SID) in text form from the list of principals that act as policy administrators.

DeletePolicyAdministrator

The DeletePolicyAdministrator method of IAzScope removes the specified security identifier in text form from the list of
principals that act as policy administrators.

DeletePolicyAdministratorName

Removes the specified account name from the list of principals that act as policy administrators.

DeletePolicyAdministratorName

Removes the specified account name from the list of principals that act as policy administrators.

DeletePolicyAdministratorName

The DeletePolicyAdministratorName method of IAzScope removes the specified account name from the list of principals that
act as policy administrators.

DeletePolicyReader

The DeletePolicyReader method of IAzApplication removes the specified security identifier in text form from the list of
principals that act as policy readers.

DeletePolicyReader

Removes the specified security identifier (SID) in text form from the list of principals that act as policy readers.

DeletePolicyReader

The DeletePolicyReader method of IAzScope removes the specified security identifier in text form from the list of principals that
act as policy readers.

DeletePolicyReaderName

Removes the specified account name from the list of principals that act as policy readers.

DeletePolicyReaderName

Removes the specified account name from the list of principals that act as policy readers.
DeletePolicyReaderName

The DeletePolicyReaderName method of IAzScope removes the specified account name from the list of principals that act as
policy readers.

DeleteProperty

Removes a named property from a property set.

DeletePropertyItem

Removes the specified principal from the specified list of principals.

DeletePropertyItem

Removes the specified entity from the specified list.

DeletePropertyItem

Removes the specified principal from the specified list of principals.

DeletePropertyItem

Removes the specified entity from the specified list.

DeletePropertyItem

Removes the specified principal from the specified list of principals.

DeletePropertyItem

Removes the specified entity from the specified list.

DeleteRequest

Delete any certificates or keys created for the request.

DeleteRole

Removes the IAzRole object with the specified name from the IAzApplication object.

DeleteRole

Removes the IAzRole object with the specified name from the IAzScope object.

DeleteRoleAssignment

Removes the specified IAzRoleAssignment object from the IAzApplication3 object.

DeleteRoleAssignment

Removes the specified IAzRoleAssignment object from this scope.

DeleteRoleDefinition

Removes the specified IAzRoleDefinition object from the IAzApplication3 object.

DeleteRoleDefinition

Removes the IAzRoleDefinition object with the specified name from this IAzRoleAssignment object.

DeleteRoleDefinition

Removes the IAzRoleDefinition object with the specified name from this IAzRoleDefinition object.

DeleteRoleDefinition

Removes the specified IAzRoleDefinition object from this scope.

DeleteRow

The DeleteRow method deletes a row or set of rows from a database table. The caller specifies a database table and either a
row ID or an ending date.

DeleteScope

Removes the IAzScope object with the specified name from the IAzApplication object.

DeleteScope2

Removes the specified IAzScope2 object from the IAzApplication3 object.

DeleteSecurityContext

Deletes the local data structures associated with the specified security context initiated by a previous call to the
InitializeSecurityContext (General) function or the AcceptSecurityContext (General) function.

DeleteSecurityPackageA

Deletes a security support provider from the list of providers supported by Microsoft Negotiate.

DeleteSecurityPackageW

Deletes a security support provider from the list of providers supported by Microsoft Negotiate.

DeleteService

Marks the specified service for deletion from the service control manager database.

DeleteTask

Removes the IAzTask object with the specified name from the IAzApplication object.

DeleteTask

Removes the IAzTask object with the specified name from the role.
DeleteTask

Removes the IAzTask object with the specified name from the IAzScope object.

DeleteTask

Removes the IAzTask object with the specified name from the task.

DenyRequest

Denies a specified certificate request that is pending.

DeriveCapabilitySidsFromName

This function constructs two arrays of SIDs out of a capability name. One is an array group SID with NT Authority, and the
other is an array of capability SIDs with AppAuthority.

DestroyPrivateObjectSecurity

Deletes a private object's security descriptor.

DestroyVirtualSmartCard

Destroys the TPM virtual smart card that has the given instance ID.

DisassociateIdentity

Disassociates the specified identity from a local user account.

DisconnectIdentity

Disconnects an online identity from the current domain user.

DSCreateISecurityInfoObject

Creates an instance of the ISecurityInformation interface associated with the specified directory service (DS) object.

DSCreateISecurityInfoObjectEx

Creates an instance of the ISecurityInformation interface associated with the specified directory service (DS) object on the
specified server.

DSCreateSecurityPage

Creates a security property page for an Active Directory object.

DSEditSecurity

Displays a modal dialog box for editing security on a Directory Services (DS) object.

DuplicateToken

Creates a new access token that duplicates one already in existence.

DuplicateTokenEx

Creates a new access token that duplicates an existing token. This function can create either a primary token or an
impersonation token.

EditSecurity

Displays a property sheet that contains a basic security property page. This property page enables the user to view and edit
the access rights allowed or denied by the ACEs in an object's DACL.

EditSecurityAdvanced

Extends the EditSecurity function to include the security page type when displaying the property sheet that contains a basic
security property page.

Encode

Initializes the object from a string that contains a distinguished name.

Encode

Signs and encodes a certificate request and creates a key pair if one does not exist.

Encode

Returns an ASN.1-encoded string of the alternate name array stored in this object. The names in the object are not encoded.

Encode

Performs Abstract Syntax Notation One (ASN.1) encoding on a given bit string.

Encode

Performs Abstract Syntax Notation One (ASN.1) encoding on a certificate revocation list (CRL) distribution information array
stored in the COM object and returns the ASN.1-encoded extension.

Encode

Returns an Abstract Syntax Notation One (ASN.1)-encoded string of the date array stored in this object.

Encode

Returns an ASN.1-encoded string of the LONG array stored in this object.

Encode

Returns an ASN.1-encoded string of the string array stored in this object.

EncryptMessage

Encrypts a message to provide privacy by using Digest.

Enroll

Encodes a request, submits it to an appropriate certification authority (CA), and installs the response.
Enroll

Enrolls a certificate request and retrieves the issued certificate.

EnumAlgs

The ICEnroll4::EnumAlgs method retrieves the IDs of cryptographic algorithms in a given algorithm class that are supported
by the current cryptographic service provider (CSP).

EnumAlgs

Retrieves the IDs of cryptographic algorithms in a given algorithm class that are supported by the current cryptographic
service provider (CSP).

EnumCertViewAttribute

Obtains an instance of an attribute-enumeration sequence for the current row of the row-enumeration sequence.

EnumCertViewColumn

Obtains an instance of a column-enumeration sequence for the database schema.

EnumCertViewColumn

Obtains an instance of a column-enumeration sequence for the current row of the row-enumeration sequence.

EnumCertViewExtension

Obtains an instance of an extension-enumeration sequence for the current row of the row-enumeration sequence.

enumContainers

Retrieves the names of containers for the cryptographic service provider (CSP) specified by the ProviderName property. This
method was first defined in the ICEnroll interface.

enumContainersWStr

Retrieves the names of containers for the cryptographic service provider (CSP) specified by the ProviderNameWStr property.

EnumDependentServicesA

Retrieves the name and status of each service that depends on the specified service.

EnumDependentServicesW

Retrieves the name and status of each service that depends on the specified service.

EnumerateAttributes

Returns the name of the next request attribute within the current context, then increments the internal pointer to the
following attribute.

EnumerateAttributes

Retrieves the name of the current attribute and moves the internal enumeration pointer to the next attribute.
EnumerateAttributesClose

Frees any resources connected with attribute enumeration.

EnumerateAttributesClose

Frees the resources connected with attribute enumeration.

EnumerateAttributesSetup

Initializes the internal enumeration pointer to the first request attribute associated with the current context.

EnumerateAttributesSetup

Initializes the internal enumeration pointer to the first request attribute associated with the current context.

EnumerateExtensions

Returns the object identifier (OID) string (also known as the extension name) of the next certificate extension to be
enumerated, then increments the internal pointer to the following extension.

EnumerateExtensions

Retrieves the object identifier (OID) of the current extension and moves the internal enumeration pointer to the next
extension.

EnumerateExtensionsClose

Frees any resources connected with extension enumeration.

EnumerateExtensionsClose

Frees the resources connected with extension enumeration.

EnumerateExtensionsSetup

Initializes the internal enumeration pointer to the first certificate extension associated with the current context.

EnumerateExtensionsSetup

Initializes the internal enumeration pointer to the first certificate extension associated with the current context.

EnumerateIdentities

Gets a pointer to an IEnumUnknown interface pointer that can be used to enumerate identities across identity providers.

EnumerateSecurityPackagesA

Returns an array of SecPkgInfo structures that provide information about the security packages available to the client.

EnumerateSecurityPackagesW

Returns an array of SecPkgInfo structures that provide information about the security packages available to the client.
enumPendingRequest

Enumerates pending certificate requests and retrieves a specified property from each. This method was first defined in the
ICEnroll4 interface.

enumPendingRequestWStr

Enumerates pending certificate requests and retrieves a specified property from each.

enumProviders

Retrieves the names of the available cryptographic service providers (CSPs) specified by the ProviderType property. This
method was first defined in the ICEnroll interface.

enumProvidersWStr

The IEnroll4::enumProvidersWStr method retrieves the names of the available cryptographic service providers (CSPs) specified
by the ProviderType property.

EnumServicesStatusA

Enumerates services in the specified service control manager database. The name and status of each service are provided.

EnumServicesStatusExA

Enumerates services in the specified service control manager database. The name and status of each service are provided,
along with additional data based on the specified information level.

EnumServicesStatusExW

Enumerates services in the specified service control manager database. The name and status of each service are provided,
along with additional data based on the specified information level.

EnumServicesStatusW

Enumerates services in the specified service control manager database. The name and status of each service are provided.

EqualDomainSid

Determines whether two SIDs are from the same domain.

EqualPrefixSid

Tests two security-identifier (SID) prefix values for equality. A SID prefix is the entire SID except for the last subauthority value.

EqualSid

Tests two security identifier (SID) values for equality. Two SIDs must match exactly to be considered equal.

Export

Exports templates and object identifiers associated with the certificate enrollment policy (CEP) server to a buffer.

Export

Copies the private key to a byte array.

ExportPublicKey

Exports the endorsement public key.

ExportPublicKey

Exports the public key portion of the asymmetric key pair.

ExportSecurityContext

The ExportSecurityContext function creates a serialized representation of a security context that can later be imported into a
different process by calling ImportSecurityContext.

Find

Retrieves the index number of an ISignerCertificate object.

FindByUniqueID

Retrieves a pointer to the IPropertyStore interface instance associated with the specified identity.

FindFirstFreeAce

Retrieves a pointer to the first free byte in an access control list (ACL).

FreeBuffer

The FreeBuffer method frees memory allocated by the Security Configuration snap-in.

FreeBuffer

The FreeBuffer method frees memory allocated by the attachment snap-in extension.

FreeContextBuffer

Enables callers of security package functions to free memory buffers allocated by the security package.

FreeCredentialsHandle

Notifies the security system that the credentials are no longer needed.

FreeInheritedFromArray

Frees memory allocated by the GetInheritanceSource function.

freeRequestInfo

Releases session identifiers when they are no longer needed.

freeRequestInfoBlob

The freeRequestInfoBlob method deletes a certificate context. This method was first defined in the IEnroll interface.
FreeSid

Frees a security identifier (SID) previously allocated by using the AllocateAndInitializeSid function.

GenerateChallenge

Performs the policy decision whether to issue a challenge password to the SCEP client.

get__NewEnum

Retrieves an IEnumVARIANT interface on an object that can be used to enumerate the collection. This property is hidden
within Visual Basic and Visual Basic Scripting Edition (VBScript).

get__NewEnum

Retrieves an IEnumVARIANT interface on an object that can be used to enumerate the collection. This property is hidden
within Visual Basic and Visual Basic Scripting Edition (VBScript).

get__NewEnum

The _NewEnum property of IAzOperations retrieves an IEnumVARIANT interface on an object that can be used to enumerate
the collection. This property is hidden within Visual Basic and Visual Basic Scripting Edition (VBScript).

get__NewEnum

Retrieves an IEnumVARIANT interface on an object that can be used to enumerate the IAzRoleAssignments collection. This
property is hidden within Visual Basic and Visual Basic Scripting Edition (VBScript).

get__NewEnum

Retrieves an IEnumVARIANT interface on an object that can be used to enumerate the IAzRoleDefinitions collection. This
property is hidden within Visual Basic and Visual Basic Scripting Edition (VBScript).

get__NewEnum

The _NewEnum property of IAzRoles retrieves an IEnumVARIANT interface on an object that can be used to enumerate the
collection. This property is hidden within Visual Basic and Visual Basic Scripting Edition (VBScript).

get__NewEnum

The _NewEnum property of IAzScopes retrieves an IEnumVARIANT interface on an object that can be used to enumerate the
collection. This property is hidden within Visual Basic and Visual Basic Scripting Edition (VBScript).

get__NewEnum

The _NewEnum property of IAzTasks retrieves an IEnumVARIANT interface on an object that can be used to enumerate the
collection. This property is hidden within Visual Basic and Visual Basic Scripting Edition (VBScript).

get__NewEnum

Retrieves the enumerator for the collection.

get__NewEnum

Retrieves the enumerator for the collection.

get__NewEnum

Retrieves the enumerator for the collection.

get__NewEnum

Retrieves the enumerator for the collection.

get__NewEnum

Retrieves the enumerator for the collection.

get__NewEnum

Retrieves the enumerator for the collection.

get__NewEnum

Retrieves the enumerator for the collection.

get__NewEnum

Retrieves the enumerator for the collection.

get__NewEnum

Retrieves the enumerator for the collection.

get__NewEnum

Retrieves the enumerator for the collection.

get__NewEnum

Retrieves the enumerator for the collection.

get__NewEnum

Retrieves the enumerator for the collection.

get__NewEnum

Retrieves the enumerator for the collection.

get__NewEnum

Retrieves the enumerator for the collection.

get__NewEnum

Retrieves the enumerator for the collection.

get__NewEnum

Retrieves the enumerator for the collection.

get__NewEnum

Retrieves the enumerator for the collection.

get__NewEnum

Gets an enumerator for the information set.

get__NewEnum

Gets an enumerator for the configuration set.

get__NewEnum

Gets an enumerator for a property set.

get_Algorithm

Specifies or retrieves an object identifier (OID) for the public key algorithm.

get_Algorithm

Retrieves an object identifier (OID) for the public key algorithm.

get_AlternateSignatureAlgorithm

Specifies and retrieves a Boolean value that indicates whether the signature algorithm object identifier (OID) for a PKCS

get_AlternateSignatureAlgorithm

Specifies and retrieves a Boolean value that specifies whether the GetSignatureAlgorithm method should retrieve a discrete or
combined algorithm object identifier (OID) for a PKCS

get_AlternateSignatureAlgorithmSet

Retrieves a Boolean value that specifies whether the AlternateSignatureAlgorithm property has been explicitly set by a caller.

get_AlternativeNames

Retrieves a collection of subject alternative names.

get_ApplicationData

Sets or retrieves an opaque field that can be used by the application to store information.

get_ApplicationData

Sets or retrieves an opaque field that can be used by the application to store information.

get_ApplicationData

The ApplicationData property of IAzOperation sets or retrieves an opaque field that can be used by the application to store
information.
get_ApplicationData

The ApplicationData property of IAzRole sets or retrieves an opaque field that can be used by the application to store
information.

get_ApplicationData

The ApplicationData property of IAzScope sets or retrieves an opaque field that can be used by the application to store
information.

get_ApplicationData

The ApplicationData property of IAzTask sets or retrieves an opaque field that can be used by the application to store
information.

get_ApplicationGroups

Retrieves an IAzApplicationGroups object that is used to enumerate IAzApplicationGroup objects from the policy data.

get_ApplicationGroups

Retrieves an IAzApplicationGroups object that is used to enumerate IAzApplicationGroup objects from the policy data.

get_ApplicationGroups

Retrieves an IAzApplicationGroups object that is used to enumerate IAzApplicationGroup objects from the policy data.

get_Applications

Retrieves an IAzApplications object that is used to enumerate IAzApplication objects from the policy store.

get_ApplyStoreSacl

Sets or retrieves a value that indicates whether policy audits should be generated when the authorization store is modified.

get_ApplyStoreSacl

Sets or retrieves a value that indicates whether policy audits should be generated when the authorization store is modified.

get_AppMembers

Retrieves the application groups that belong to this application group.

get_AppMembers

Retrieves the application groups that belong to the role.

get_AppNonMembers

Retrieves the application groups that are refused membership in this application group.

get_Archived

Retrieves a Boolean value that specifies whether the certificate has been archived.
get_ArchivedKeyHash

Retrieves a SHA-1 hash of the private key.

get_ArchivePrivateKey

Specifies or retrieves a Boolean value that indicates whether to archive a private key on the certification authority (CA).

get_AttestationEncryptionCertificate

The certificate used to encrypt the EKPUB and EKCERT values from the client. This property must be set to a valid certificate
that chains to a trusted machine root.

get_AttestPrivateKey

True if the created private key needs to be attested; otherwise false. If true, it is expected that the
AttestationEncryptionCertificate property has been set.

get_AuthFlags

Specifies and retrieves a value that indicates the authentication type used by the client to authenticate itself to the certificate
enrollment policy (CEP) server.

get_AuthorityKeyIdentifier

Retrieves a byte array that contains the extension value.

get_AuthzInterfaceClsid

Sets or retrieves the class identifier (CLSID) of the interface that the user interface (UI) uses to perform application-specific
operations.

get_BackedUpTime

Retrieves the date and time at which the certificate was backed up.

get_BackedUpValue

Retrieves a Boolean value that identifies whether the certificate was backed up.

get_BitCount

Retrieves the length, in bits, of the encryption key.

get_BizRule

Gets or sets the script that determines membership for this application group.

get_BizRule

Sets or retrieves the text of the script that implements the business rule (BizRule).

get_BizRuleImportedPath

Gets or sets the path of the file that contains the business rule script associated with this application group.
get_BizRuleImportedPath

Sets or retrieves the path to the file from which the business rule (BizRule) is imported.

get_BizRuleInterfaces

Gets the collection of IDispatch interfaces that can be called by the business rule (BizRule) script associated with this client
context.

get_BizRuleLanguage

Gets or sets the programming language of the business rule script associated with this application group.

get_BizRuleLanguage

Sets or retrieves the scripting language in which the business rule (BizRule) is implemented.

get_BizRuleParameters

Gets the collection of parameters that can be passed by the business rule (BizRule) script associated with this client context.

get_BizRulesEnabled

Gets or sets a value that indicates whether business rules are enabled for this application.

get_BizrulesWritable

Retrieves a value that indicates whether a non-delegated scope is writable.

get_BusinessRuleString

Sets or retrieves an application-specific string for the Business Rule (BizRule).

get_CACertificate

Gets an X.509 certificate that has been encoded by using Distinguished Encoding Rules (DER) and that is for a certification
authority (CA).

get_CAConfig

Gets or sets a certification authority (CA) name with which a signing certificate must be signed.

get_CAConfigString

Retrieves the configuration string that identifies the certification authority (CA) to which the certificate request was submitted.

get_CADnsName

Retrieves the Domain Naming System (DNS) name of the certification authority (CA).

get_CAErrorId

Gets the ID for additional error information related to a failed certification authority (CA) specification.
get_CAErrorString

Gets the string data for additional error information related to a failed certification authority (CA) specification.

get_CAName

Retrieves the common name (CN) of the certification authority (CA).

get_CanBeDelegated

Retrieves a value that indicates whether the scope can be delegated.

get_CAStoreFlags

Sets or retrieves a flag that controls the certification authority (CA) store when the store is opened.

get_CAStoreFlags

The CAStoreFlags property of IEnroll4 sets or retrieves a flag that controls the certification authority (CA) store when the store
is opened.

get_CAStoreName

Sets or retrieves the name of the store where all non-"ROOT" and non-"MY" certificates are kept.

get_CAStoreNameWStr

The CAStoreNameWStr property of IEnroll4 sets or retrieves the name of the store where all non-"ROOT" and non-"MY"
certificates are kept.

get_CAStoreType

Sets or retrieves the type of store to use for the store specified by the CAStoreName property.

get_CAStoreTypeWStr

Sets or retrieves the type of store to use for the store specified by the CAStoreNameWStr property.

get_Certificate

Retrieves a Distinguished Encoding Rules (DER) encoded byte array that contains the certificate.

get_Certificate

Retrieves the installed certificate.

get_Certificate

Specifies or retrieves a byte array that contains the certificate associated with the private key.

get_Certificate

Gets the certificate for the request.

get_CertificateDescription

Specifies or retrieves a string that contains a description of the certificate.

get_CertificateFriendlyName

Specifies or retrieves the display name of a certificate.

get_CertificateFriendlyName

Gets or sets the friendly name for the certificate.

get_ChallengePassword

The password to use when creating a request with a challenge. To create a request without a challenge, do not set the
ChallengePassword property.

get_ClientId

Retrieves the type of client application that generated the request.

get_ClientId

Specifies and retrieves a value that identifies the executable that created the request.

get_ClientId

Sets or retrieves a client ID request attribute. The client ID request attribute indicates the source of the certificate request. This
property was first defined in the ICEnroll4 interface.

get_ClientId

The ClientId property sets or retrieves a client ID request attribute. The client ID request attribute indicates the source of the
certificate request. This property was first defined in the IEnroll4 interface.

get_ContainerName

Specifies or retrieves the name of the key container.

get_ContainerName

Gets or sets the name used by the cryptographic service provider (CSP) to generate, store, or access the key.

get_ContainerName

The ContainerName property of ICEnroll4 sets or retrieves the name of the key container to use.

get_ContainerNamePrefix

Specifies or retrieves a prefix added to the name of the key container.

get_ContainerNameWStr

Sets or retrieves the name of the key container to use.

get_Cost

Specifies and retrieves an arbitrary cost for contacting the certificate enrollment policy server.

get_Cost

Specifies and retrieves an arbitrary cost for contacting the certificate enrollment policy server.

get_Count

Retrieves the number of IAzApplicationGroup objects in the collection.

get_Count

Retrieves the number of IAzApplication objects in the collection.

get_Count

Specifies the number of interfaces that can be called by business rule (BizRule) scripts.

get_Count

Gets the number of parameters available to business rule (BizRule) scripts.

get_Count

Retrieves the number of IAzOperation objects in the collection.

get_Count

Retrieves the number of IAzRoleAssignments objects in the collection.

get_Count

Retrieves the number of IAzRoleDefinitions objects in the collection.

get_Count

Retrieves the number of IAzRole objects in the collection.

get_Count

Retrieves the number of IAzScope objects in the collection.

get_Count

Retrieves the number of IAzTask objects in the collection.

get_Count

Retrieves the number of objects in the collection.

get_Count

Retrieves the number of objects in the collection.

get_Count

Retrieves the number of ICertificationAuthority objects in the collection.

get_Count

Retrieves the number of properties in the collection.

get_Count

Retrieves the number of ICryptAttribute objects in the collection.

get_Count

Retrieves the number of ICspAlgorithm objects in the collection.

get_Count

Retrieves the number of ICspInformation objects in the collection.

get_Count

Retrieves the number of ICspStatus objects in the collection.

get_Count

Retrieves the number of objects in the collection.

get_Count

Retrieves the number of objects in the collection.

get_Count

Retrieves the number of ISignerCertificate objects in the collection.

get_Count

Retrieves the number of objects in the collection.

get_Count

Retrieves the number of IX509Attribute objects in the collection.

get_Count

Retrieves the number of IX509CertificateTemplate objects in the collection.

get_Count

Retrieves the number of IX509Extension objects in the collection.

get_Count

Retrieves the number of IX509NameValuePair objects in the collection.

get_Count

Retrieves the number of IX509PolicyServerUrl objects in the collection.

get_Count

Gets the number of ICertSrvSetupKeyInformation objects in the collection.

get_Count

Gets the number of certification authority (CA) configurations in the configuration set.

get_Count

Gets the number of properties in a property set.

get_Critical

Specifies and retrieves a Boolean value that identifies whether the certificate extension is critical.

get_CriticalExtensions

Retrieves an IObjectIds collection that identifies the version 3 certificate extensions marked as critical.

get_CriticalExtensions

Retrieves an IObjectIds collection that identifies the version 3 certificate extensions marked as critical.

get_CryptAttributes

Retrieves an ICryptAttributes collection of optional certificate attributes.

get_CryptAttributes

Retrieves an ICryptAttributes collection of optional certificate attributes.

get_CspAlgorithm

Retrieves an ICspAlgorithm object that contains information about an algorithm supported by the provider.

get_CspAlgorithms

Retrieves a collection of ICspAlgorithm interfaces that contain information about the algorithms supported by the provider.

get_CspInformation

Retrieves an ICspInformation object that contains general information about the provider.

get_CspInformations

Specifies and retrieves a collection of cryptographic providers available for use by the request object.
get_CspInformations

Specifies or retrieves a collection of ICspInformation objects that contain information about the available cryptographic
providers that support the public key algorithm associated with the private key.

get_CSPName

Gets a cryptographic service provider (CSP) or key storage provider (KSP) name.

get_CspStatus

Specifies or retrieves an ICspStatus object that contains information about the cryptographic provider and algorithm pair
associated with the private key.

get_CspStatuses

Retrieves a collection of ICspStatus objects that matches the intended use of the private key associated with the certificate
request.

get_Default

Specifies and retrieves a Boolean value that indicates whether this is the default certificate enrollment policy (CEP) server.

get_DefaultContainer

Retrieves a Boolean value that specifies whether the private key represents the default key container.

get_DefaultLength

Retrieves the default length of a key.

get_DelegatedPolicyUsers

Retrieves the security identifiers (SIDs), in text form, of principals that act as delegated policy users.

get_DelegatedPolicyUsers

Retrieves the security identifiers (SIDs) of principals that act as delegated policy users in text form.

get_DelegatedPolicyUsersName

The DelegatedPolicyUsersName property of IAzApplication retrieves the account names of principals that act as delegated
policy users.

get_DelegatedPolicyUsersName

Retrieves the account names of principals that act as delegated policy users.

get_DeleteRequestCert

Sets or retrieves a Boolean value that determines whether dummy certificates in the request store are deleted.

get_DeleteRequestCert

The DeleteRequestCert property of IEnroll4 sets or retrieves a Boolean value that determines whether dummy certificates in
the request store are deleted.
get_Description

Sets or retrieves a comment that describes the application.

get_Description

Sets or retrieves a comment that describes the application group.

get_Description

Sets or retrieves a comment that describes the operation.

get_Description

The Description property of IAzOperation sets or retrieves a comment that describes the operation.

get_Description

Sets or retrieves a comment that describes the role.

get_Description

Sets or retrieves a comment that describes the scope.

get_Description

Sets or retrieves a comment that describes the task.

get_Description

Retrieves a description of the certificate.

get_Description

Specifies or retrieves a string that contains a description of the private key.

get_Display

Specifies or retrieves a value that indicates whether to display the status information in a user interface.

get_DisplayName

Retrieves a string that contains the name of the provider, the algorithm name, and the operations that can be performed by
the algorithm.

get_DomainTimeout

Sets or retrieves the time in milliseconds after which a domain is determined to be unreachable.

get_EnableSMIMECapabilities

The ICEnroll4::EnableSMIMECapabilities property controls whether the PKCS

get_EnableSMIMECapabilities

Controls whether the PKCS

get_EnableT61DNEncoding

The EnableT61DNEncoding property of ICEnroll4 sets or retrieves a Boolean value that determines whether the distinguished
name in the request is encoded as a T61 string instead of as a Unicode string.

get_EnableT61DNEncoding

Sets or retrieves a Boolean value that determines whether the distinguished name in the request is encoded as a T61 string
instead of as a Unicode string.

get_EncodedKey

Retrieves a byte array that contains the public key.

get_EncodedName

Retrieves a Unicode-encoded distinguished name.

get_EncodedParameters

Retrieves a byte array that contains the parameters associated with the public key algorithm.

get_EncryptedKeyBlob

Retrieves a byte array that contains the encrypted key.

get_EncryptedKeyHash

Retrieves a hash of the private key to be archived.

get_EncryptedKeyHashBlob

Retrieves a string that contains a hash of the encrypted private key.

get_EncryptionAlgorithm

Retrieves the object identifier (OID) of the symmetric encryption algorithm used to encrypt the private key.

get_EncryptionAlgorithm

Specifies or retrieves an object identifier (OID) of the algorithm used to encrypt the private key to be archived.

get_EncryptionAlgorithm

The encryption algorithm used to encrypt the EKPUB and EKCERT values from the client.

get_EncryptionStrength

Retrieves an integer that contains the encryption strength of the symmetric algorithm used to encrypt the key.
get_EncryptionStrength

Specifies or retrieves the relative encryption level applied to the private key to be archived.

get_EncryptionStrength

Identifies the bit length for the EncryptionAlgorithm to use for encryption. If the EncryptionAlgorithm only supports one bit
length, then you do not need to specify a value for the EncryptionStrength property.

get_EnhancedKeyUsage

Retrieves a collection of key usage object identifiers (OIDs).

get_EnrollmentContext

Retrieves a value that specifies whether the certificate is intended for a computer or a user.

get_EnrollmentContext

Retrieves an enrollment context that identifies whether the certificate is intended for a computer or an end-user.

get_EnrollmentStatus

Retrieves an IX509EnrollmentStatus object that contains information about the certificate enrollment.

get_Error

Specifies and retrieves a value that identifies the error status of the certificate enrollment process.

get_ErrorCode

Gets a code that identifies an error condition in a CA configuration.

get_ErrorString

Retrieves a string that contains additional information about Certificate Enrollment Policy (CEP) Web Service setup failure.

get_ErrorString

Retrieves a string that contains additional information about Certificate Enrollment Web Service (CES) setup failure.

get_ErrorText

Retrieves a string that contains the message associated with the error result code returned by the Error property.

get_Existing

Specifies or retrieves a Boolean value that indicates whether the private key has been created or imported.

get_Existing

Gets or sets a value that indicates whether the private key already exists.
get_ExistingCACertificate

Gets or sets the binary value that has been encoded by using Distinguished Encoding Rules (DER) and that is the binary value
of the certification authority (CA) certificate that corresponds to an existing key.

get_ExportPolicy

Specifies or retrieves export constraints for a private key.

get_FailInfo

Gets information when the ProcessResponseMessage method detects a failed environment.

get_Flags

Specifies or retrieves a value that indicates whether the certificate enrollment policy (CEP) server policy information can be
loaded from group policy, from the registry, or both.

get_FriendlyName

Retrieves the display name of the certificate.

get_FriendlyName

Retrieves the display name of the certificate.

get_FriendlyName

Specifies and retrieves a display name for the object identifier.

get_FriendlyName

Specifies or retrieves a display name for the private key.

get_GenerateAudits

The GenerateAudits property of IAzApplication sets or retrieves a value that indicates whether run-time audits should be
generated.

get_GenerateAudits

Sets or retrieves a value that indicates whether run-time audits should be generated.

get_GenKeyFlags

Sets or retrieves the values passed to the CryptGenKey function when the certificate request is generated.

get_GenKeyFlags

Sets or retrieves the values passed to CryptGenKey when the certificate request is generated.

get_HashAlgID

Sets or retrieves the hash algorithm used when signing a PKCS

get_HashAlgID

The HashAlgID property of IEnroll4 sets or retrieves the hash algorithm used when signing a PKCS

get_HashAlgorithm

Specifies and retrieves the object identifier (OID) of the hash algorithm used to sign the certificate request.

get_HashAlgorithm

Specifies and retrieves an object identifier (OID) for the hashing algorithm used in the GetSignatureAlgorithm method.

get_HashAlgorithm

Gets or sets the name of the hashing algorithm used to sign or verify the certification authority (CA) certificate for the key.

get_HashAlgorithm

Sets or retrieves only the signature hashing algorithm used to sign the PKCS

get_HashAlgorithm

Gets or sets an identifier for the hash algorithm used to sign a certificate.

get_HashAlgorithmWStr

Sets or retrieves only the signature hashing algorithm used to sign the PKCS

get_HasHardwareRandomNumberGenerator

Retrieves a Boolean value that specifies whether the provider supports a hardware random number generator that can be
used to create random bytes for cryptographic operations.

get_Identifier

Gets a name for the certification authority (CA) configuration.

get_IncludeSubjectKeyID

Determines whether the subject key ID extension is added to the certificate request that is generated.

get_IncludeSubjectKeyID

The IncludeSubjectKeyID property of IEnroll4 determines whether the subject key ID extension is added to the certificate
request that is generated.

get_IncrementLength

Retrieves a value, in bits, that can be used to determine valid incremental key lengths for algorithms that support multiple key
sizes.

get_IndexByObjectId

Retrieves the index of an attribute by object identifier (OID).

get_IndexByObjectId

Retrieves the index of an ICspAlgorithm object by object identifier (OID).

get_IndexByObjectId

Retrieves the index of an extension in the collection by object identifier (OID).

get_IsCA

Retrieves a Boolean value that identifies whether the subject of the certificate is a certification authority (CA).

get_IsHardwareDevice

Retrieves a Boolean value that determines whether the provider is implemented in a hardware device.

get_IsRemovable

Retrieves a Boolean value that specifies whether the token that contains the key can be removed.

get_IsRoleDefinition

Sets or retrieves a value that indicates whether the task is a role definition.

get_IsSmartCard

Retrieves a Boolean value that specifies whether the provider is a smart card provider.

get_IsSoftwareDevice

Retrieves a Boolean value that specifies whether the provider is implemented in software.

get_Issuer

Specifies or retrieves the name of the certificate issuer.

get_Item

Retrieves the IAzApplicationGroup object at the specified index into the IAzApplicationGroups collection.

get_Item

Retrieves the IAzApplication object at the specified index into the IAzApplications collection.

get_Item

Retrieves the IAzOperation object at the specified index into the IAzOperations collection.

get_Item

Retrieves the IAzRoleAssignment object at the specified index in the IAzRoleAssignments collection.

get_Item

Retrieves the IAzRoleDefinition object at the specified index in the IAzRoleDefinitions collection.
get_Item

Retrieves the IAzRole object at the specified index into the IAzRoles collection.

get_Item

Retrieves the IAzScope object at the specified index into the IAzScopes collection.

get_Item

Retrieves the IAzTask object at the specified index into the IAzTasks collection.

get_Item

Gets an ICertSrvSetupKeyInformation object that is identified by index in the collection.

get_Item

Gets a certification authority (CA) configuration identified by index in the configuration set.

get_Item

Gets the property identified by index in a property set.

get_ItemByName

Retrieves an ICertificationAuthority object from the collection by certification authority name.

get_ItemByName

Retrieves an ICspAlgorithm object from the collection by name.

get_ItemByName

Retrieves an ICspInformation object from the collection by name.

get_ItemByName

Retrieves an ICspStatus object from the collection by provider and algorithm name.

get_ItemByName

Retrieves an IX509CertificateTemplate object from the collection by name.

get_ItemByName

Gets a certification authority (CA) configuration identified by name in the configuration set.

get_ItemByName

Gets the property identified by name in a property set.

get_ItemByOid

Retrieves an IX509CertificateTemplate object from the collection by object identifier.

get_ItemByOperations

Retrieves an ICspStatus object that has the same name as the provider specified on input and the same algorithm but
identifies a different cryptographic operation.

get_ItemByOrdinal

Retrieves an ICspStatus object from the collection by ordinal number.

get_ItemByProvider

Retrieves an ICspStatus object that has the same name as the provider specified on input but identifies an algorithm that
supports a different intended key use.

get_KeyArchivalCertificate

Specifies or retrieves a certification authority (CA) encryption certificate.

get_KeyContainerNamePrefix

Specifies or retrieves a prefix used to create the container name for a new private key.

get_KeyProtection

Specifies or retrieves a value that indicates how a private key is protected before use.

get_KeySpec

Retrieves a value that specifies the intended use of the algorithms supported by the provider.

get_KeySpec

Retrieves a value that identifies whether the key pair stored by the provider or key container is used for encryption or for
signing content.

get_KeySpec

Specifies or retrieves a value that identifies whether a private key can be used for signing, or encryption, or both.

get_KeySpec

The KeySpec property of ICEnroll4 sets or retrieves the type of key generated.

get_KeySpec

Sets or retrieves the type of key generated.

get_KeySpec

Gets a value that indicates whether the key bound to the configuration is used for encryption or for signing content.

get_KeyUsage

Retrieves the restrictions placed on the public key.

get_KeyUsage

Specifies or retrieves a value that identifies the specific purpose for which a private key can be used.

get_LdapQuery

Sets or retrieves the Lightweight Directory Access Protocol (LDAP) query used to define membership for an LDAP query
application group.

get_LDAPQueryDN

Retrieves or sets the domain name of the directory object to be used during evaluation of LDAP query groups.

get_LegacyCsp

Retrieves a Boolean value that specifies whether the provider is a Cryptography API:_Next Generation (CNG) provider or a
CryptoAPI (legacy) CSP.

get_LegacyCsp

Specifies or retrieves a Boolean value that indicates whether the provider is a CryptoAPI (legacy) cryptographic service
provider (CSP).

get_Length

The bit length of the endorsement key. You can only access this property after the Open method has been called.

get_Length

Specifies or retrieves the length, in bits, of the private key.

get_Length

Retrieves the length of the public key.

get_Length

Gets or sets the strength of the key to one of the values supported by the cryptographic service provider (CSP).

get_LimitExchangeKeyToEncipherment

Sets or retrieves a Boolean value that determines whether an AT_KEYEXCHANGE request contains digital signature and
nonrepudiation key usages.

get_LimitExchangeKeyToEncipherment

The LimitExchangeKeyToEncipherment property of IEnroll4 sets or retrieves a Boolean value that determines whether an
AT_KEYEXCHANGE request contains digital signature and nonrepudiation key usages.

get_LocalRevocationInformation

Gets or sets the certificate revocation list (CRL) of the local machine.

get_LongName

Retrieves the full name of the algorithm.

get_MachineContext

Specifies or retrieves a Boolean value that identifies the local certificate store context.

get_MachineDnsName

Retrieves the Domain Name System (DNS) name of the computer that generated the request.

get_MajorVersion

Retrieves the minimum major version number of the certificate template.

get_MaxKeyContainerNameLength

Retrieves the maximum supported length for the name of the private key container associated with the provider.

get_MaxLength

Retrieves the maximum permitted length for a key.

get_MaxScriptEngines

Sets or retrieves the maximum number of Business Rule (BizRule) script engines that will be cached.

get_Members

Retrieves the security identifiers (SIDs), in text form, of accounts that belong to the application group.

get_Members

Retrieves the security identifiers (SIDs), in text form, of Windows accounts that belong to the role.

get_MembersName

Retrieves the account names of accounts that belong to the application group.

get_MembersName

Retrieves the account names of accounts that belong to the role.

get_MinLength

Retrieves the minimum permitted length for a key.

get_MinorVersion

Retrieves the minimum minor version number of the certificate template.

get_Modified

Gets a value that indicates whether an OCSPCAConfiguration object has been modified since it was created.

get_Modified

Gets a value that indicates whether an OCSPProperty object has been modified since it was instantiated.
get_MSCEPErrorId

Gets the ID for additional error information related to a failed Network Device Enrollment Service (NDES) specification. Any
method call on the parent object resets this property.

get_MSCEPErrorString

Contains the string data for additional error information related to a failed Network Device Enrollment Service (NDES)
specification. Any method call on the parent object resets this property.

get_MyStoreFlags

Sets or retrieves the registry location used for MY store.

get_MyStoreFlags

Sets or retrieves the registry location used for the MY store.

get_MyStoreName

Sets or retrieves the name of the store where certificates with linked private keys are kept.

get_MyStoreNameWStr

The MyStoreNameWStr property of IEnroll4 sets or retrieves the name of the store where certificates with linked private keys
are kept.

get_MyStoreType

Sets or retrieves the type of store specified by the MyStoreName property.

get_MyStoreTypeWStr

Sets or retrieves the type of store specified by the MyStoreTypeWStr property.

get_Name

Sets or retrieves the name of the application.

get_Name

Sets or retrieves the name of the application group.

get_Name

Gets the name of the IAzObjectPicker object.

get_Name

Sets or retrieves the name of the operation.

get_Name

Sets or retrieves the name of the role.

get_Name

Sets or retrieves the name of the scope.

get_Name

Sets or retrieves the name of the task.

get_Name

Retrieves the abbreviated algorithm name.

get_Name

Retrieves the name.

get_Name

Retrieves a CERTENROLL_OBJECTID value that contains an object identifier.

get_Name

Retrieves a distinguished name.

get_Name

Retrieves the name portion of the name-value pair.

get_Name

Gets the identifier part of the name-value pair represented by an OCSPProperty object.

get_NameResolver

Gets a pointer to the IAzNameResolver interface associated with this IAzPrincipalLocator object.

get_NameValuePairs

Retrieves an IX509NameValuePairs collection associated with a certificate request.

get_NameValuePairs

A collection of name/value pairs of additional certificate property values.

get_NameValuePairs

Retrieves a collection of name-value pairs associated with the enrollment object.

get_NonMembers

Retrieves the security identifiers (SIDs), in text form, of accounts that are refused membership in the application group.

get_NonMembersName

Retrieves the account names of accounts that are refused membership in the application group.
get_NotAfter

Specifies or retrieves the date and time after which the certificate is no longer valid.

get_NotBefore

Specifies or retrieves the date and time before which the certificate is not valid.

get_NullSigned

Retrieves a Boolean value that specifies whether the primary signature on the certificate request is null-signed.

get_NullSigned

Retrieves a Boolean value that indicates whether the certificate request is null-signed.

get_NullSigned

Specifies and retrieves a Boolean value that indicates whether the certificate request is null-signed.

get_ObjectId

Retrieves the object identifier (OID), if any, associated with the name.

get_ObjectId

Retrieves an object identifier (OID) for the policy object.

get_ObjectId

Retrieves the object identifier (OID) for the attribute.

get_ObjectId

Retrieves the object identifier (OID) for the qualifier.

get_ObjectId

Retrieves the object identifier (OID) of the symmetric encryption algorithm.

get_ObjectId

Retrieves the object identifier (OID) for the attribute.

get_ObjectId

Retrieves the object identifier (OID) for the extension.

get_ObjectPicker

Gets a pointer to the IAzObjectPicker interface associated with this IAzPrincipalLocator object.
get_OCSPCAConfigurationCollection

Gets an instance of an OCSPCAConfigurationCollection object. This object represents the set of certification authority (CA)
certificates for which an Online Certificate Status Protocol (OCSP) responder service can handle status requests.

get_OCSPServiceProperties

Gets an instance of an OCSPPropertyCollection object. This object represents the attributes of an Online Certificate Status
Protocol (OCSP) responder service.

get_OldCertificate

Retrieves the certificate passed to the InitializeFromCertificate method.

get_OldCertificate

Gets or sets an old certificate that a request is intended to replace.

get_Opened

Indicates whether the Open method has been successfully called.

get_Opened

Retrieves a Boolean value that specifies whether the private key is open.

get_OperationID

Sets or retrieves an application-specific value that uniquely identifies the operation within the application.

get_Operations

Retrieves an IAzOperations object that is used to enumerate IAzOperation objects from the policy data.

get_Operations

Retrieves the operations associated with the role.

get_Operations

Retrieves the operations associated with the task.

get_Operations

Retrieves the operations that can be performed by the algorithm.

get_Ordinal

Specifies or retrieves the position of the ICspStatus object in the ICspStatuses collection.

get_OSVersion

Retrieves the client operating system version information.

get_Parameters

Retrieves a byte array that contains the parameters associated with the signature algorithm.

get_ParentWindow

Specifies or retrieves the ID of the window used to display signing certificate information.

get_ParentWindow

Specifies and retrieves the ID of the window used by key-related user interface dialogs.

get_ParentWindow

Specifies or retrieves the ID of the window used to display the enrollment information.

get_ParentWindow

Specifies or retrieves the ID of the window used to display key information.

get_PathLenConstraint

Retrieves the depth of the subordinate certification authority chain.

get_Policies

Retrieves a collection of certificate policies.

get_Policies

Retrieves a collection of application policies.

get_PolicyAdministrators

Retrieves the security identifiers (SIDs), in text form, of principals that act as policy administrators.

get_PolicyAdministrators

Retrieves the security identifiers (SIDs) of principals that act as policy administrators in text form.

get_PolicyAdministrators

The PolicyAdministrators property of IAzScope retrieves the security identifiers (SIDs), in text form, of principals that act as
policy administrators.

get_PolicyAdministratorsName

The IAzApplication::PolicyAdministratorsName property retrieves the account names of principals that act as policy
administrators.

get_PolicyAdministratorsName

Retrieves the account names of principals that act as policy administrators.

get_PolicyAdministratorsName

Retrieves the account names of principals that act as policy administrators.

get_PolicyQualifiers

Retrieves a collection of optional policy qualifiers that can be applied to a certificate policy.

get_PolicyReaders

Retrieves the security identifiers (SIDs), in text form, of principals that act as policy readers.

get_PolicyReaders

Retrieves the security identifiers (SIDs) of principals that act as policy readers in text form.

get_PolicyReaders

The PolicyReaders property of IAzScope retrieves the security identifiers (SIDs), in text form, of principals that act as policy
readers.

get_PolicyReadersName

The IAzApplication::PolicyReadersName property retrieves the account names of principals that act as policy readers.

get_PolicyReadersName

Retrieves the account names of principals that act as policy readers.

get_PolicyReadersName

Retrieves the account names of principals that act as policy readers.

get_PolicyServer

Retrieves the certificate enrollment policy (CEP) server that contains the template used during initialization.

get_PolicyServer

Retrieves the certificate enrollment policy (CEP) server that contains the template used during initialization.

get_PolicyServer

Retrieves the certificate enrollment policy (CEP) server that contains the template used during initialization.

get_PolicyServer

Retrieves the certificate enrollment policy (CEP) server that contains the template used during initialization.

get_PolicyServer

Retrieves the certificate enrollment policy (CEP) server that contains the template used during initialization.
get_PrivateKey

Retrieves the private key associated with the certificate.

get_PrivateKey

Retrieves the private key associated with the ISignerCertificate object.

get_PrivateKey

Retrieves an IX509PrivateKey object that contains the private key used to sign the certificate request.

get_PrivateKeyArchiveCertificate

Sets or retrieves the certificate that is used to archive a private key with a PKCS

get_ProcessName

Retrieves the name of the application that generated the request.

get_Property

Retrieves a certification authority property value.

get_Property

Retrieves a template property value.

get_Property

Specifies or retrieves a property value for the IX509CertificateTemplateWritable object.

get_PropertyId

Specifies or retrieves a value of the CERTENROLL_PROPERTYID enumeration that identifies an external certificate property.

get_ProviderCLSID

Gets or sets the CLSID of the revocation information provider used by the CA configuration.

get_ProviderFlags

Sets or retrieves the provider type.

get_ProviderFlags

The ProviderFlags property of IEnroll4 sets or retrieves the provider type.

get_ProviderName

Retrieves the provider name.

get_ProviderName

The name of the encryption provider. The default is the Microsoft Platform Crypto Provider. You must set the ProviderName
property before you call the Open method. You cannot change the ProviderName property after you have called the Open
method.

get_ProviderName

Specifies or retrieves the name of the cryptographic provider.

get_ProviderName

Gets or sets the name of the cryptographic service provider (CSP) or key storage provider (KSP) that is used to generate or
store the private key.

get_ProviderName

The ProviderName property of ICEnroll4 sets or retrieves the name of the cryptographic service provider (CSP) to use.

get_ProviderNameWStr

Sets or retrieves the name of the cryptographic service provider (CSP) to use.

get_ProviderProperties

Gets or sets information that provides certificate status responses.

get_ProviderType

Specifies or retrieves the type of cryptographic provider associated with the private key.

get_ProviderType

The ProviderType property of ICEnroll4 sets or retrieves the type of provider.

get_ProviderType

Sets or retrieves the type of provider.

get_PublicKey

Retrieves the IX509PublicKey object that contains the public key included in the certificate request.

get_PublicKeyAlgorithm

Specifies and retrieves an object identifier (OID) for the public key algorithm used in the GetSignatureAlgorithm method.

get_PVKFileName

The PVKFileName property of ICEnroll4 sets or retrieves the name of the file that will contain exported keys.

get_PVKFileNameWStr

Sets or retrieves the name of the file that will contain exported keys.
get_Qualifier

Retrieves a string that contains the qualifier used to initialize the object.

get_RawData

Retrieves the Distinguished Encoding Rules (DER) encoded byte array that contains the name.

get_RawData

Retrieves the value of the certificate property.

get_RawData

Retrieves the Distinguished Encoding Rules (DER) encoded qualifier object.

get_RawData

Retrieves the attribute value.

get_RawData

Retrieves a byte array that contains the signed, Distinguished Encoding Rules (DER) encoded certificate request.

get_RawData

Retrieves a byte array that contains the extension value.

get_RawDataToBeSigned

Retrieves the unsigned certificate request created by the Encode method.

get_ReaderName

Specifies or retrieves the name of a smart card reader.

get_ReminderDuration

Gets or sets the percentage of a signing certificate lifetime after which a warning event is logged.

get_Renewal

Retrieves the SHA-1 hash of the new certificate.

get_RenewalCertificate

Retrieves the certificate to be renewed.

get_RenewalCertificate

Specifies or retrieves a byte array that contains the Distinguished Encoding Rules (DER) encoded certificate that is being
renewed.
get_RenewalCertificate

Specifies the certificate context for the renewal certificate.

get_Request

Retrieves the certificate request associated with the enrollment object.

get_Request

Gets the inner PKCS10 request.

get_RequesterName

Specifies or retrieves a string that contains the Security Account Manager (SAM) name of the end-entity requesting the
certificate.

get_RequestId

Retrieves a unique certificate request identifier.

get_RequestId

Retrieves a unique identifier for the certificate request sent to the certification authority by the Enroll method.

get_RequestID

Gets the request ID from the Certificate Management over CMS (CMC) response.

get_RequestIdString

Retrieves a string that contains a unique identifier for the certificate request sent to the certification enrollment server (CES).

get_RequestOriginator

Retrieves a string that contains the DNS name of the originating computer.

get_RequestStoreFlags

Sets or retrieves the registry location used for the request store.

get_RequestStoreFlags

The RequestStoreFlags property of IEnroll4 sets or retrieves the registry location used for the request store.

get_RequestStoreName

Sets or retrievesICEnroll the name of the store that contains the dummy certificate.

get_RequestStoreNameWStr

The RequestStoreNameWStr property of IEnroll4 sets or retrieves the name of the store that contains the dummy certificate.
get_RequestStoreType

Sets or retrieves the type of store to use for the store specified by the RequestStoreName property. This store type is passed
directly to the CertOpenStore function.

get_RequestStoreTypeWStr

Sets or retrieves the type of store to use for the store specified by the RequestStoreNameWStr property. This store type is
passed directly to the CertOpenStore function.

get_Response

Retrieves the certificate response returned from a certification authority.

get_ReuseHardwareKeyIfUnableToGenNew

Sets or retrieves a Boolean value that determines the action taken by the certificate enrollment control object if an error is
encountered when generating a new key.

get_ReuseHardwareKeyIfUnableToGenNew

The ReuseHardwareKeyIfUnableToGenNew property of IEnroll4 sets or retrieves a Boolean value that determines the action
taken by the certificate enrollment control object if an error is encountered when generating a new key.

get_ReuseKey

Retrieves a Boolean value that indicates whether an existing private key was used to sign the request.

get_RoleAssignments

Gets an IAzRoleAssignments object that represents the collection of IAzRoleAssignment objects associated with the current
IAzApplication3 object.

get_RoleAssignments

Retrieves an IAzRoleAssignments object that represents the collection of IAzRoleAssignment objects associated with this scope.

get_RoleDefinitions

Gets an IAzRoleDefinitions object that represents the collection of IAzRoleDefinition objects associated with the current
IAzApplication3 object.

get_RoleDefinitions

Retrieves a collection of the IAzRoleDefinition objects associated with this IAzRoleAssignment object.

get_RoleDefinitions

Retrieves a collection of the IAzRoleDefinition objects associated with this IAzRoleDefinition object.

get_RoleDefinitions

Retrieves an IAzRoleDefinitions object that represents the collection of IAzRoleDefinition objects associated with this scope.
get_RoleForAccessCheck

Sets or retrieves the role that is used to perform the access check.

get_Roles

The Roles property of IAzApplication retrieves an IAzRoles object that is used to enumerate IAzRole objects from the policy
data.

get_Roles

Retrieves an IAzRoles object that is used to enumerate IAzRole objects from the policy data.

get_RootStoreFlags

The RootStoreFlags property of ICEnroll4 sets or retrieves the registry location used for the root store.

get_RootStoreFlags

Sets or retrieves the registry location used for the root store.

get_RootStoreName

Sets or retrieves the name of the root store where all intrinsically trusted, self-signed root certificates are kept.

get_RootStoreNameWStr

The RootStoreNameWStr property of IEnroll4 sets or retrieves the name of the root store where all intrinsically trusted, self-
signed root certificates are kept.

get_RootStoreType

Sets or retrieves the type of store to use for the store specified by the RootStoreName property.

get_RootStoreTypeWStr

Sets or retrieves the type of store to use for the store specified by the RootStoreNameWStr property.

get_Scope

Retrieves the IAzScope object that represents the scope in which this IAzRoleAssignment object is defined.

get_Scopes

Retrieves an IAzScopes object that is used to enumerate IAzScope objects from the policy data.

get_ScriptEngineTimeout

Sets or retrieves the time in milliseconds that the IAzClientContext::AccessCheck method will wait for a Business Rule (BizRule)
to complete execution before canceling it.

get_SecurityDescriptor

Specifies or retrieves the security descriptor for the private key.

get_Selected

Specifies or retrieves a value that indicates whether an item can be used during the enrollment process.

get_SenderNonce

Specifies or retrieves a byte array that contains a nonce.

get_SerialNumber

Specifies and retrieves the certificate serial number.

get_SHA1Hash

Retrieves the SHA-1 hash of a certificate.

get_Sids

Gets an array of the security identifiers (SIDs) associated with this client context.

get_Signature

Retrieves the digital signature on the provider.

get_Signature

Retrieves the request signature created by the Encode method.

get_SignatureInformation

Retrieves an IX509SignatureInformation object that contains information about the certificate signature.

get_SignatureInformation

Retrieves the IX509SignatureInformation object that contains information about the primary signature used to sign the
certificate request.

get_SignatureInformation

Retrieves the IX509SignatureInformation object that contains information about the certificate request signature.

get_SignerCertificate

Specifies or retrieves the ISignerCertificate object used to sign the certificate.

get_SignerCertificate

Specifies or retrieves a certificate used to sign the certificate request.

get_SignerCertificate

Gets or sets the signer certificate for the request.

get_SignerCertificates

Retrieves a collection of certificates used to sign the request.

get_SigningCertificate

Gets or sets a signing certificate that has been encoded by using Distinguished Encoding Rules (DER). An Online Certificate
Status Protocol (OCSP) responder service uses this certificate to sign its responses to certificate status requests.

get_SigningCertificateTemplate

Gets or sets the template name for a signing certificate.

get_SigningFlags

Gets or sets a combination of flag values. These values specify the management of signing certificates that belong to a
certification authority (CA) configuration.

get_Silent

Specifies or retrieves a Boolean value that indicates whether the user is notified when the private key is used to sign a
certificate request.

get_Silent

Specifies or retrieves a Boolean value that indicates whether any of the key-related modal dialogs are displayed during the
certificate enrollment process.

get_Silent

Specifies or retrieves a Boolean value that indicates whether a user interface is displayed during the certificate enrollment
process.

get_Silent

Specifies or retrieves a Boolean value that indicates whether the Certificate Enrollment Control is allowed to display a dialog
box when the private key is accessed.

get_SmimeCapabilities

Specifies or retrieves a Boolean value that tells the Encode method whether to create an IX509ExtensionSmimeCapabilities
collection that identifies the encryption capabilities supported by the computer.

get_SmimeCapabilities

Retrieves a collection of ISmimeCapability objects.

get_SPCFileName

Sets or retrieves the name of the file to which to write the base64-encoded PKCS

get_SPCFileNameWStr

The SPCFileNameWStr property of IEnroll4 sets or retrieves the name of the file to which to write the base64-encoded PKCS
get_Status

Retrieves an IX509EnrollmentStatus object that can be used to monitor the status of the enrollment process and retrieve error
information.

get_Status

Specifies or retrieves a value that indicates the status of the enrollment process.

get_Status

Gets the status of the request.

get_StrValue

Retrieves a string that contains an email address, a Domain Name System (DNS) name, a URL, a registered object identifier
(OID), or a user principal name (UPN).

get_Subject

Specifies or retrieves the X.500 distinguished name of the entity requesting the certificate.

get_SubjectKeyIdentifier

Retrieves a byte array that contains the key identifier.

get_SuppressDefaults

Specifies or retrieves a Boolean value that indicates whether the default extensions and attributes are included in the request.

get_SuppressOids

Retrieves a collection of extension or attribute object identifiers (OIDs) to be suppressed from the certificate during the
encoding process.

get_SuppressOids

Retrieves a collection of the default extension and attribute object identifiers (OIDs) that were not added to the request when
the request was encoded.

get_TargetMachine

Retrieves the name of the computer on which account resolution should occur.

get_Tasks

The Tasks property of IAzApplication retrieves an IAzTasks object that is used to enumerate IAzTask objects from the policy
data.

get_Tasks

Retrieves the tasks associated with the role.

get_Tasks

Retrieves an IAzTasks object that is used to enumerate IAzTask objects from the policy data.
get_Tasks

Retrieves the tasks associated with the task.

get_Template

Retrieves the certificate request template used during initialization.

get_Template

Retrieves the certificate request template used during initialization.

get_Template

Retrieves the certificate request template used during initialization.

get_Template

Retrieves the certificate request template used during initialization.

get_Template

Retrieves a copy of the IX509CertificateTemplate object that was used to initialize this IX509CertificateTemplateWritable
instance.

get_Template

Retrieves the certificate request template used during initialization.

get_TemplateName

Retrieves a string that contains the name of the template that the certificate can use for autoenrollment.

get_TemplateName

Retrieves the name of the template.

get_TemplateObjectId

Retrieves the object identifier (OID) of the template used to create the certificate request.

get_TemplateObjectId

Retrieves the object identifier (OID) of the template used to create the certificate request.

get_TemplateOid

Retrieves the template object identifier (OID).

get_Text

Specifies or retrieves a string that contains a message associated with the status of the enrollment process.
get_ThumbPrint

Sets or retrieves a hash of the certificate data.

get_ThumbPrintWStr

Sets or retrieves a hash of the certificate data. The thumbprint is used to point to the pending certificate.

get_TransactionId

Specifies or retrieves a transaction identifier that can be used to track a certificate request or response.

get_TransactionId

Gets or sets the transaction id for the request.

get_Type

Sets or retrieves the group type of the application group.

get_Type

Retrieves the alternative name type.

get_Type

Retrieves the algorithm type.

get_Type

Retrieves the type of the provider.

get_Type

Retrieves the qualifier type.

get_Type

Retrieves a value that specifies the type of the request object.

get_UIContextMessage

Specifies or retrieves a string that contains user interface text associated with the signing certificate.

get_UIContextMessage

Specifies or retrieves a context string to display in the user interface.

get_UIContextMessage

Specifies or retrieves a string that contains user interface text associated with the private key.

get_UniqueContainerName

Retrieves a unique name for the key container.

get_Url

Specifies or retrieves the URL for the certificate enrollment policy (CEP) server.

get_UseExistingKeySet

Sets or retrieves a Boolean value that determines whether the existing keys should be used.

get_UseExistingKeySet

The UseExistingKeySet property of IEnroll4 sets or retrieves a Boolean value that determines whether the existing keys should
be used.

get_UserCanonical

Retrieves the name of the current client in canonical format.

get_UserDisplay

Retrieves the name of the current client in user display name format.

get_UserDn

Retrieves the name of the current client in distinguished name (DN) format.

get_UserDnsSamCompat

Retrieves the name of the current client in a DNS format compatible with Windows�Security�Account�Manager (SAM).

get_UserGuid

Retrieves the name of the current client in GUID format.

get_UserSamCompat

Retrieves the name of the current client in a format compatible with Windows�Security�Account�Manager (SAM).

get_UserSamName

Retrieves the Security Accounts Manager (SAM) name of the user.

get_UserUpn

Retrieves the name of the current client in user principal name (UPN) format.

get_Valid

Retrieves a Boolean value that specifies whether the algorithm object is valid.

get_Valid

Retrieves a Boolean value that specifies whether the provider is installed on the client computer.
get_Value

Retrieves a string that contains the dotted decimal object identifier (OID).

get_Value

Retrieves the value portion of the name-value pair.

get_Value

Gets or sets the data part of the name-value pair represented by an OCSPProperty object.

get_Values

Retrieves an IX509Attributes object that contains a collection of attributes.

get_Version

Sets or retrieves the version of the application.

get_Version

Retrieves the version number of the provider.

get_Writable

Retrieves a value that indicates whether the object can be modified by the user context that initialized it.

get_Writable

Retrieves a value that indicates whether the application group can be modified by the user context that initialized it.

get_Writable

Retrieves a value that indicates whether the object can be modified by the user context that called the Initialize method.

get_Writable

Retrieves a value that indicates whether the operation can be modified by the user context that initialized it.

get_Writable

Retrieves a value that indicates whether the role can be modified by the user context that initialized it.

get_Writable

Retrieves a value that indicates whether the scope can be modified by the user context that initialized it.

get_Writable

Retrieves a value that indicates whether the task can be modified by the user context that initialized it.
get_WriteCertToCSP

The WriteCertToCSP property of ICEnroll4 sets or retrieves a Boolean value that determines whether a certificate should be
written to the cryptographic service provider (CSP).

get_WriteCertToCSP

Sets or retrieves a Boolean value that determines whether a certificate should be written to the cryptographic service provider
(CSP).

get_WriteCertToUserDS

Sets or retrieves a Boolean value that determines whether the certificate is written to the user's Active Directory store.

get_WriteCertToUserDS

The WriteCertToUserDS property of IEnroll4 sets or retrieves a Boolean value that determines whether the certificate is written
to the user's Active Directory store.

get_X509Extensions

Retrieves the certificate extensions.

get_X509Extensions

Retrieves a collection of the extensions included in the certificate request.

get_X509Extensions

Retrieves a collection of the extensions included in the certificate request.

GetAccessRights

The GetAccessRights method requests information about the access rights that can be controlled for a securable object.

GetAce

Obtains a pointer to an access control entry (ACE) in an access control list (ACL).

GetAclInformation

Retrieves information about an access control list (ACL).

GetAlgName

Retrieves the name of a cryptographic algorithm given its ID. The values retrieved by this method depend on the current
cryptographic service provider (CSP). This method was first defined in the ICEnroll3 interface.

GetAlgNameWStr

Retrieves the name of a cryptographic algorithm given its ID. The values retrieved by this method depend on the current
cryptographic service provider (CSP).

GetAlgorithmName

Retrieves the display name associated with an algorithm object identifier (OID).
GetAlgorithmOid

Retrieves the algorithm object identifier (OID). This method is web enabled.

GetAllowUnTrustedCA

Retrieves a value that specifies whether to allow an untrusted certification authority certificate.

GetAllProperties

Gets all properties in a property set.

GetAppContainerNamedObjectPath

Retrieves the named object path for the app container.

GetArchivedKey

Retrieves an archived key recovery BLOB.

GetAssignedScopesPage

Retrieves a list of the scopes in which the client represented by the current IAzClientContext2 object is assigned to at least one
role.

GetAt

Retrieves an IIdentityProvider interface pointer for the specified identity provider.

GetAuditedPermissionsFromAclA

Retrieves the audited access rights for a specified trustee.

GetAuditedPermissionsFromAclW

Retrieves the audited access rights for a specified trustee.

GetAuthentication

The GetAuthentication method retrieves a value that specifies the type of authentication used by the certificate enrollment
policy (CEP) server to authenticate a client. This value is set by the Initialize method.

GetAuthFlags

Retrieves a value that specifies the authentication type used by the client to authenticate itself to the certificate enrollment
policy (CEP) server.

GetBitCount

Returns the number of bits in a bit string that belongs to the CertEncodeBitString object and has been initialized by an earlier
call to ICertEncodeBitString::Decode.

GetBitString

Returns the string of bits in the object's bit string.

GetBusinessRuleString

Returns the application-specific string for the business rule (BizRule).

GetCACertificate

Returns the certification authority (CA) certificate for the Certificate Services server.

GetCacheDir

Retrieves the name of the directory on the certificate enrollment policy (CEP) server that contains the policy cache file.

GetCachePath

Retrieves the path of the policy cache file on the certificate enrollment policy (CEP) server.

GetCAProperty

Retrieves a property value for the certification authority (CA).

GetCAProperty

Retrieves a property value for the certification authority (CA).

GetCAPropertyDisplayName

Retrieves the property display name for a certification authority (CA) property.

GetCAPropertyDisplayName

The ICertAdmin2::GetCAPropertyDisplayName method retrieves the property display name for a certification authority (CA)
property.

GetCAPropertyFlags

Retrieves the property flags for a certification authority (CA) property.

GetCAPropertyFlags

The ICertAdmin2::GetCAPropertyFlags method retrieves the property flags for a certification authority (CA) property.

GetCAs

Retrieves a collection of certification enrollment servers included in the policy.

GetCASetupProperty

Gets a property value for a certification authority (CA) configuration.

GetCAsForTemplate

Retrieves a collection of certificate enrollment servers that support a specified template.

getCAStore

The getCAStore method is not implemented.

getCertContextFromFileResponseWStr

Retrieves the certificate from a file containing a response from a certification authority.

getCertContextFromPKCS7

Retrieves a certificate context based on a PKCS

getCertContextFromResponseBlob

Retrieves the certificate from a certification authority's response.

getCertFromFileResponse

Retrieves the certificate from a file containing a response from a certification authority. This method was first defined in the
ICEnroll4 interface.

getCertFromPKCS7

Retrieves the certificate, contained in a PKCS

getCertFromResponse

Retrieves the certificate from a certification authority's response. This method was first defined by the ICEnroll4 interface.

GetCertificate

Returns the certificate issued for the request as an X.509 certificate, or optionally packaged in a Public Key Cryptography
Standards (PKCS)

GetCertificateCount

Gets the count of the endorsement certificates in the key storage provider.

GetCertificateExtension

Gets a specified certificate extension.

GetCertificateExtension

Retrieves a specific certificate extension.

GetCertificateExtensionFlags

Gets the flags from the extension acquired by the most recent call to ICertServerExit::GetCertificateExtension.

GetCertificateExtensionFlags

Retrieves the flags associated with the extension acquired by the most recent call to GetCertificateExtension.
GetCertificateProperty

Returns a named property from a certificate.

GetCertificateProperty

Returns a named property from a certificate.

GetColumnCount

Retrieves the number of columns in the view of the Certificate Services database.

GetConfig

Retrieves the configuration string for a Certificate Services server. This method was first defined in the ICertConfig interface.

GetConfigEntry

Retrieves configuration information for a certification authority (CA).

GetConfiguration

Connects to an Online Certificate Status Protocol (OCSP) responder server and initializes an OCSPAdmin object with the
configuration information from the server.

GetCount

Gets the number of identity providers registered on the system.

GetCount

Returns the number of DATE values in the object's DATE array.

GetCount

Returns the number of Long values in the object's Long array.

GetCount

Returns the number of string values in the string array.

GetCRL

Retrieves the current certificate revocation list (CRL) for the Certificate Services certification authority (CA).

GetCspStatuses

Retrieves an ICspStatuses collection that contains all provider/algorithm pairs consistent with the intended use of the private
key as specified by the caller.

GetCspStatusesFromOperations

Retrieves an ICspStatuses collection by supported key operations and optional provider information.
GetCspStatusFromOperations

Creates an ICspStatus object for the first supported algorithm that is consistent with the specified signature, encryption,
hashing, or cipher operation.

GetCspStatusFromProviderName

Retrieves an ICspStatus object for a legacy provider by provider name and supported key operations.

GetCurrentProcessToken

Retrieves a pseudo-handle that you can use as a shorthand way to refer to the access token associated with a process.

GetCurrentThreadEffectiveToken

Retrieves a pseudo-handle that you can use as a shorthand way to refer to the token that is currently in effect for the thread,
which is the thread token if one exists and the process token otherwise.

GetCurrentThreadToken

Retrieves a pseudo-handle that you can use as a shorthand way to refer to the impersonation token that was assigned to the
current thread.

GetCustomOids

Is not implemented.

GetData

The GetData method retrieves configuration information from the Security Configuration snap-in.

GetDefaultSecurityDescriptor

Retrieves the default private key security descriptor.

GetDescription

Returns a human-readable description of the policy module and its function.

GetDescription

Returns a human-readable description of the exit module and its function.

GetDisplayName

Retrieves the localized name of the current column in the column-enumeration sequence.

GetDispositionMessage

Gets a human-readable message that gives the current disposition of the certificate request.

GetDistPointCount

Returns the number of certificate revocation list (CRL) distribution points in a CRL distribution information array.
GetEffectivePermission

Returns the effective permission for an object type.

GetEffectiveRightsFromAclA

Retrieves the effective access rights that an ACL structure grants to a specified trustee. The trustee's effective access rights are
the access rights that the ACL grants to the trustee or to any groups of which the trustee is a member.

GetEffectiveRightsFromAclW

Retrieves the effective access rights that an ACL structure grants to a specified trustee. The trustee's effective access rights are
the access rights that the ACL grants to the trustee or to any groups of which the trustee is a member.

GetEncryptionCspAlgorithms

Retrieves the collection of encryption algorithms supported by a provider.

GetEncSChannel

This function is unavailable.

GetEnrollmentServerAuthentication

The GetEnrollmentServerAuthentication method retrieves a value that specifies the type of authentication used by the
certificate enrollment server (CES) to authenticate a client. This value is set by the Initialize method.

GetEnrollmentServerUrl

Retrieves a string that contains the URL for the certificate enrollment server.

GetErrorMessageText

Retrieves the error message text for an HRESULT error code.

GetExistingCACertificates

Gets the collection of CertSrvSetupKeyInformation objects that represent valid certification authority (CA) certificates currently
installed on the computer.

GetExplicitEntriesFromAclA

Retrieves an array of structures that describe the access control entries (ACEs) in an access control list (ACL).

GetExplicitEntriesFromAclW

Retrieves an array of structures that describe the access control entries (ACEs) in an access control list (ACL).

GetField

Gets a specific field from the current record of the configuration database. This method was first defined in the ICertConfig
interface.
GetFileSecurityA

Obtains specified information about the security of a file or directory. The information obtained is constrained by the caller's
access rights and privileges.

GetFileSecurityW

Obtains specified information about the security of a file or directory. The information obtained is constrained by the caller's
access rights and privileges.

GetFlags

Retrieves the policy and origin flags of the current extension in the extension-enumeration sequence.

GetFriendlyName

Retrieves a display name for the certificate enrollment policy (CEP) server.

GetFriendlyNameOfCertA

Retrieves the display name for a certificate.

GetFriendlyNameOfCertW

Retrieves the display name for a certificate.

GetFullResourceName

Retrieves the full path and file name of the object associated with the access control editor that is displayed by calling the
OpenElevatedEditor method.

GetFullResponseProperty

Retrieves the cached response data returned by the server.

GetGroups

Returns an array of the application groups associated with this client context.

GetHashAlgorithmList

Gets the list of hash algorithms supported by the specified cryptographic service provider (CSP) for an asymmetric signature
key algorithm.

GetHashAlgorithms

Retrieves the collection of hash algorithms supported by a provider.

GetHashAlgorithms

Gets a list of hash-algorithm names. The Online Certificate Status Protocol (OCSP) responder server uses these names to sign
OCSP responses for a given certification authority (CA) configuration.

GetIdentityEnum

Retrieves an IEnumUnknown interface pointer that can be used to enumerate identities.

GetInheritanceSourceA

Returns information about the source of inherited access control entries (ACEs) in an access control list (ACL).

GetInheritanceSourceW

Returns information about the source of inherited access control entries (ACEs) in an access control list (ACL).

GetInheritSource

The ISecurityObjectTypeInfo::GetInheritSource method provides a means of determining the source of inherited access control
entries in discretionary access control lists and system access control lists.

GetInheritTypes

The GetInheritTypes method requests information about how ACEs can be inherited by child objects. For more information,
see ACE Inheritance.

GetInnerRequest

Retrieves a nested request object.

GetInterfaceValue

Gets the ID and flags of the interface that corresponds to the specified interface name.

GetIsDefaultCEP

Retrieves a Boolean value that specifies whether this is the default certificate enrollment policy (CEP) server.

GetIssuedCertificate

Retrieves a certificate's disposition by specifying either the request ID or the certificate serial number.

GetIssuedCertificate2

Retrieves a certificate's disposition by specifying either the request ID string or the certificate serial number.

GetKernelObjectSecurity

Retrieves a copy of the security descriptor that protects a kernel object.

GetKeyLen

Retrieves the minimum and maximum key lengths for the signature and exchange keys.

GetKeyLen

The IEnroll4::GetKeyLen method retrieves the minimum and maximum key lengths for the signature and exchange keys.

GetKeyLenEx

Retrieves size information for the signature and exchange keys. This method was first defined in the ICEnroll4 interface.
GetKeyLenEx

Retrieves size information for the signature and exchange keys.

GetKeyLengthList

Gets the list of key lengths supported by the specified cryptographic service provider (CSP).

GetKeyLengthList

Gets the list of key lengths supported by the specified cryptographic service provider (CSP).

GetLastStatus

Gets the last return code for this request. This returns the error code information, rather than the disposition of the request.

GetLastUpdateTime

Retrieves the date and time at which the policy was last downloaded.

GetLengthSid

Returns the length, in bytes, of a valid security identifier (SID).

GetMachineTypeAttributes

Queries if the specified architecture is supported on the current system, either natively or by any form of compatibility or
emulation layer.

GetManageModule

Retrieves the ICertManageModule interface associated with the ICertPolicy2 interface by calling GetManageModule and
passing in the address of a pointer to an ICertManageModule.

GetManageModule

Retrieves the ICertManageModule interface associated with the ICertExit2 interface by calling GetManageModule and passing
in the address of a pointer to an ICertManageModule.

GetMaxLength

Retrieves the maximum allowable length, in bytes, for the column data.

GetMSCEPSetupProperty

Gets a property value for a Network Device Enrollment Service (NDES) configuration.

GetMyRoles

Retrieves the certification authority (CA) roles of the caller.

GetMyRoles

Gets the access mask of privilege roles for a user on a given Online Certificate Status Protocol (OCSP) responder server.
getMyStore

The getMyStore method is not implemented.

GetName

Returns the specified name from the alternate name array.

GetName

Returns the name at a specified index of a certificate revocation list (CRL) distribution information point.

GetName

Retrieves the name of the current attribute in the attribute-enumeration sequence.

GetName

Retrieves the nonlocalized name of the current column in the column-enumeration sequence.

GetName

Retrieves the name of the current extension in the extension-enumeration sequence.

GetNameChoice

Returns the name choice at a specified index of an alternate name array.

GetNameChoice

Returns the name choice at a specified index of a certificate revocation list (CRL) distribution information point.

GetNameCount

Returns the number of names in the alternate name array.

GetNameCount

Returns the number of names in a certificate revocation list (CRL) distribution point.

GetNamedSecurityInfoA

Retrieves a copy of the security descriptor for an object specified by name.

GetNamedSecurityInfoW

Retrieves a copy of the security descriptor for an object specified by name.

GetNextUpdateTime

Retrieves the date and time at which the policy expires and should be refreshed.
GetObjectInformation

The GetObjectInformation method requests information that the access control editor uses to initialize its pages and to
determine the editing options available to the user.

GetOpenCardNameA

The GetOpenCardName function displays the smart card "select card" dialog box.

GetOpenCardNameW

The GetOpenCardName function displays the smart card "select card" dialog box.

GetOperations

Returns a collection of the operations, within the specified scope, that the principal represented by the current client context
has permission to perform.

GetParameter

Gets the specified value from the varParameterValues parameter of the IAzClientContext::AccessCheck method.

GetParameterValue

Gets the value type of the business rule (BizRule) parameter with the specified name.

GetPasswordCredentials

Returns credentials to authenticate a non-domain joined container with Active Directory.

GetPolicyServerId

Retrieves a string that uniquely identifies the certificate enrollment policy (CEP) server.

GetPolicyServerId

Retrieves a string value that uniquely identifies the certificate enrollment policy (CEP) server.

GetPolicyServerUrl

Retrieves a string that contains the URL for the certificate enrollment policy (CEP) server.

GetPolicyServerUrl

Retrieves a string value that contains the URL for the certificate enrollment policy (CEP) server.

GetPrincipals

Displays a dialog box from which users can choose one or more principals, and then returns the chosen list of principals and
their corresponding security identifiers (SIDs).

GetPrivateKeyArchiveCertificate

The GetPrivateKeyArchiveCertificate method retrieves the certificate used to archive the private key. This method was first
defined in the IEnroll4 interface.
GetPrivateKeyContainerList

Gets the list of key container names stored by the specified cryptographic service provider (CSP) for asymmetric signature key
algorithms.

GetPrivateObjectSecurity

Retrieves information from a private object's security descriptor.

GetProperty

Returns the IAzApplication object property with the specified property ID.

GetProperty

Returns the IAzApplicationGroup object property with the specified property ID.

GetProperty

Returns the AzAuthorizationStore object property with the specified property ID.

GetProperty

Returns the IAzClientContext object property with the specified property ID.

GetProperty

Returns the IAzOperation object property with the specified property ID.

GetProperty

Returns the IAzRole object property with the specified property ID.

GetProperty

Returns the IAzScope object property with the specified property ID.

GetProperty

Returns the IAzTask object property with the specified property ID.

GetProperty

Retrieves a CEPSetupProperty enumeration value for the Certificate Enrollment Policy (CEP) Web Service configuration.

GetProperty

Retrieves a CESSetupProperty enumeration value for the Certificate Enrollment Web Service (CES) configuration.

GetProperty

Retrieves a module's property value.

GetPropertyFlags

Retrieves a value that specifies the default policy server URL.

GetProviderNameList

Gets the list of cryptographic service providers (CSPs) that provide asymmetric key signature algorithms on the computer.

GetProviderNameList

Gets the list of cryptographic service providers (CSPs) that provide asymmetric key signature and exchange algorithms on the
computer.

GetProviderPropertyStore

Retrieves a pointer to the IPropertyStore interface associated with the identity provider.

getProviderType

Retrieves the type of the specified cryptographic service provider (CSP). This method was first defined in the ICEnroll4
interface.

getProviderTypeWStr

Retrieves the type of the specified cryptographic service provider (CSP).

GetRefreshPolicy

Returns a value that indicates whether a client's cached certificate enrollment policy is out of date and needs to be refreshed.

GetRequestAttribute

Returns a named attribute value from a request.

GetRequestAttribute

Returns a named attribute from a request.

GetRequestId

Gets the current internal request number for the request and subsequent certificate.

GetRequestIdString

Retrieves a unique string identifier for the certificate request sent to the certification authority during enrollment.

GetRequestIdString

Gets the current internal request number, formatted as a string, for the request and subsequent certificate.

GetRequestProperty

Returns a named property from a request.

GetRequestProperty

Retrieves a specific property from a request.

GetRevocationReason

Returns the reason a certificate was revoked. This method was first defined in the ICertAdmin interface.

GetRoles

Returns the roles for the client context.

getROOTHStore

The getROOTHStore method is not implemented.

GetSchemaVersion

Gets the version number of this authorization store.

GetSecondarySecurity

Returns additional security contexts that may impact access to the resource.

GetSecurity

The GetSecurity method requests a security descriptor for the securable object whose security descriptor is being edited. The
access control editor calls this method to retrieve the object's current or default security descriptor.

GetSecurity

Gets security descriptor information for an Online Certificate Status Protocol (OCSP) responder server.

GetSecurityDescriptorControl

Retrieves a security descriptor control and revision information.

GetSecurityDescriptorDacl

Retrieves a pointer to the discretionary access control list (DACL) in a specified security descriptor.

GetSecurityDescriptorGroup

Retrieves the primary group information from a security descriptor.

GetSecurityDescriptorLength

Returns the length, in bytes, of a structurally valid security descriptor. The length includes the length of all associated
structures.

GetSecurityDescriptorOwner

Retrieves the owner information from a security descriptor.

GetSecurityDescriptorRMControl

Retrieves the resource manager control bits.

GetSecurityDescriptorSacl

Retrieves a pointer to the system access control list (SACL) in a specified security descriptor.

GetSecurityInfo

Retrieves a copy of the security descriptor for an object specified by a handle.

GetServiceDirectory

Returns a path for a per-service filesystem location for a service to read and/or write state to.

GetServiceDisplayNameA

Retrieves the display name of the specified service.

GetServiceDisplayNameW

Retrieves the display name of the specified service.

GetServiceKeyNameA

Retrieves the service name of the specified service.

GetServiceKeyNameW

Retrieves the service name of the specified service.

GetServiceRegistryStateKey

Returns a handle for a registry key for a service to read and/or write state to.

GetSharedServiceDirectory

Returns a path for a per-service filesystem location for a service and associated programs to read and/or write state to.

GetSharedServiceRegistryStateKey

Returns a handle for a registry key for a service and associated programs to read and/or write state to.

GetSidIdentifierAuthority

Returns a pointer to the SID_IDENTIFIER_AUTHORITY structure in a specified security identifier (SID).

GetSidLengthRequired

Returns the length, in bytes, of the buffer required to store a SID with a specified number of subauthorities.

GetSidSubAuthority

Returns a pointer to a specified subauthority in a security identifier (SID). The subauthority value is a relative identifier (RID).
GetSidSubAuthorityCount

Returns a pointer to the member in a security identifier (SID) structure that contains the subauthority count.

GetSignatureAlgorithm

Retrieves the signing algorithm object identifier (OID).

GetSigningCertificates

Gets the signing certificates that are available on a responder server for a given certification authority (CA) certificate.

GetStringProperty

Retrieves the certificate enrollment policy (CEP) server ID or the display name of the CEP server.

GetStringType

Returns the type of string values that the string array contains.

GetSupportedCATypes

Gets the types of certification authorities (CAs) that can be installed on a computer under the caller context.

GetSupportedKeySpec

Retrieves information regarding the current cryptographic service provider (CSP) support for signature and/or exchange
operations. This method was first defined in the ICEnroll3 interface.

GetSupportedKeySpec

Retrieves information regarding the current cryptographic service provider (CSP) support for signature and/or exchange
operations.

GetTasks

Returns a collection of the tasks, within the specified scope, that the principal represented by the current client context has
permission to perform.

GetTemplates

Retrieves a collection of the templates supported by the certificate enrollment policy (CEP) server.

GetTokenInformation

Retrieves a specified type of information about an access token. The calling process must have appropriate access rights to
obtain the information.

GetTrusteeFormA

Retrieves the trustee name from the specified TRUSTEE structure. This value indicates whether the structure uses a name string
or a security identifier (SID) to identify the trustee.
GetTrusteeFormW

Retrieves the trustee name from the specified TRUSTEE structure. This value indicates whether the structure uses a name string
or a security identifier (SID) to identify the trustee.

GetTrusteeNameA

Retrieves the trustee name from the specified TRUSTEE structure.

GetTrusteeNameW

Retrieves the trustee name from the specified TRUSTEE structure.

GetTrusteeTypeA

Retrieves the trustee type from the specified TRUSTEE structure. This value indicates whether the trustee is a user, a group, or
the trustee type is unknown.

GetTrusteeTypeW

Retrieves the trustee type from the specified TRUSTEE structure. This value indicates whether the trustee is a user, a group, or
the trustee type is unknown.

GetType

Retrieves the data type of the current column in the column-enumeration sequence.

GetUrl

Returns the URL string for the specified wizard or webpage.

GetUrlFlags

Retrieves a set of flags that contain miscellaneous policy information about the certificate enrollment policy (CEP) server.

GetUseClientId

Retrieves a value that specifies whether the ClientId attribute is set in the policy server flags of the certificate enrollment policy
(CEP) server.

GetUserObjectSecurity

Retrieves security information for the specified user object.

GetValue

Returns the specified date from the DATE array.

GetValue

Returns the specified Long value from the Long array.

GetValue

Returns the specified string from the string array.

GetValue

Retrieves the value of the current attribute in the attribute-enumeration sequence.

GetValue

Retrieves the data value contained in the current column in the column-enumeration sequence.

GetValue

Retrieves the value of the current extension in the extension-enumeration sequence.

GetWindowsAccountDomainSid

Receives a security identifier (SID) and returns a SID representing the domain of that SID.

IdentityUpdated

Is called by an identity provider to notify a calling application that an identity event occurred.

ImpersonateAnonymousToken

Enables the specified thread to impersonate the system's anonymous logon token.

ImpersonateLoggedOnUser

Lets the calling thread impersonate the security context of a logged-on user. The user is represented by a token handle.

ImpersonateNamedPipeClient

Impersonates a named-pipe client application.

ImpersonateSecurityContext

Allows a server to impersonate a client by using a token previously obtained by a call to AcceptSecurityContext (General) or
QuerySecurityContextToken.

ImpersonateSelf

Obtains an access token that impersonates the security context of the calling process. The token is assigned to the calling
thread.

Import

Imports an identity to the system.

Import

Imports an existing private key into a key container within a cryptographic provider.

ImportCertificate

Takes a previously issued certificate and imports it to the certification authority's (CA) database. This method was first defined
in the ICertAdmin interface.
ImportKey

Adds an encrypted key set to an item in the Certificate Services database. The key set is encrypted to one or several key
recovery agent (KRA) certificates.

ImportPFXToProvider

Imports a PFX certificate.

ImportPFXToProviderFreeData

Frees PFX certificate context(s).

ImportSecurityContextA

Imports a security context. The security context must have been exported to the process calling ImportSecurityContext by a
previous call to ExportSecurityContext.

ImportSecurityContextW

Imports a security context. The security context must have been exported to the process calling ImportSecurityContext by a
previous call to ExportSecurityContext.

Initialize

Initializes the authorization manager.

Initialize

Initialize using the full Certificate Management over CMS (CMC) response returned from the CA.

Initialize

Initializes the object from an object identifier (OID).

Initialize

Initializes the object from a Boolean value that specifies whether the certificate has been archived.

Initialize

Initializes the object from a byte array that contains the hash.

Initialize

Initializes the object by specifying the name of the template to be used for autoenrollment.

Initialize

Initializes the object from a Boolean value and a date.

Initialize

Initializes the object from a string that contains descriptive information about the certificate.
Initialize

Initializes the property from the certificate request ID, the certification authority (CA) configuration string, and an optional
certificate display name.

Initialize

Initializes an ICertPropertyEnrollmentPolicyServer object.

Initialize

Initializes the object from the certificate display name.

Initialize

Initializes the object from a private key.

Initialize

Initializes the object from a SHA-1 hash of the new certificate.

Initialize

Initializes the object from a string that contains the DNS name of the originating computer.

Initialize

Initializes the object from the SHA-1 hash of a certificate.

Initialize

Initializes the object from a cryptographic provider and an associated algorithm.

Initialize

Initializes the object from a signing certificate.

Initialize

Initializes the object from a symmetric encryption algorithm object identifier (OID) and an optional key length.

Initialize

Initializes the object from an object identifier (OID) and a value.

Initialize

Initializes the request object for a user or a computer.

Initialize

Initializes an IX509CertificateTemplateWritable object from a template.

Initialize

Initializes the enrollment object and creates a default PKCS

Initialize

Initializes an IX509EnrollmentHelper object.

Initialize

Initializes an IX509EnrollmentPolicyServer object.

Initialize

Initializes an IX509Extension object by using an object identifier (OID) and a byte array that contains the Distinguished
Encoding Rules (DER) encoded extension.

Initialize

Initializes the object from strings that contain the name and associated value.

Initialize

Initializes an IX509PolicyServerListManager object.

Initialize

Initializes an IX509PolicyServerUrl object for a computer or user context.

Initialize

Initializes the object from a public key algorithm object identifier (OID) and from byte arrays that contain a public key and the
associated parameters, if any.

Initialize

Initialize the instance in preparation for a new request.

Initialize

Called by the server engine to allow the policy module to perform initialization tasks.

Initialize

Initializes the NDES policy module.

Initialize

Called by the server engine when it initializes itself.

Initialize

The Initialize method informs the Security Configuration snap-in that the snap-in extension is loaded, and it establishes a
context for communications.
InitializeAcl

Initializes a new ACL structure.

InitializeClientContext2

Retrieves an IAzClientContext2 object pointer.

InitializeClientContextFromName

Gets an IAzClientContext object pointer from the client identity as a (domain name, client name) pair.

InitializeClientContextFromStringSid

Gets an IAzClientContext object pointer from the specified security identifier (SID) in text form.

InitializeClientContextFromToken

Gets an IAzClientContext object pointer from the specified client token.

InitializeClientContextFromToken2

Retrieves an IAzClientContext2 object pointer from the specified client token.

InitializeDecode

Initializes the object from a byte array that contains the property value.

InitializeDecode

Initializes the object from a Distinguished Encoding Rules (DER) encoded byte array that contains the encrypted private key.

InitializeDecode

Initializes the object from a Distinguished Encoding Rules (DER) encoded byte array that contains a SHA-1 hash of the
encrypted private key.

InitializeDecode

Initializes the object from a Distinguished Encoding Rules (DER) encoded byte array that contains the attribute value.

InitializeDecode

Initializes the object from a Distinguished Encoding Rules (DER) encoded byte array that contains information about the
provider.

InitializeDecode

Initializes the object from a Distinguished Encoding Rules (DER) encoded byte array that contains the attribute value.

InitializeDecode

Initializes the object from a Distinguished Encoding Rules (DER) encoded byte array that contains the operating system version
information.
InitializeDecode

Initializes the object from a Distinguished Encoding Rules (DER) encoded byte array that contains the certificate to be renewed.

InitializeDecode

Decodes an existing signed or unsigned PKCS

InitializeDecode

Decodes an existing signed or unsigned PKCS

InitializeDecode

Initializes the extension from a Distinguished Encoding Rules (DER) encoded byte array that contains the extension value.

InitializeDecode

Initializes the extension from a Distinguished Encoding Rules (DER) encoded byte array that contains the extension value.

InitializeDecode

Initializes the extension from a Distinguished Encoding Rules (DER) encoded byte array that contains the extension value.

InitializeDecode

Initializes the object from a Distinguished Encoding Rules (DER) encoded byte array that contains the extension value.

InitializeDecode

Initializes the extension from a Distinguished Encoding Rules (DER) encoded byte array that contains the extension value.

InitializeDecode

Initializes the extension from a Distinguished Encoding Rules (DER) encoded byte array that contains the extension value.

InitializeDecode

Initializes the extension from a Distinguished Encoding Rules (DER) encoded byte array that contains the extension value.

InitializeDecode

Initializes the extension from a Distinguished Encoding Rules (DER) encoded byte array that contains the extension value.

InitializeDecode

Initializes the extension from a Distinguished Encoding Rules (DER) encoded byte array that contains the extension value.

InitializeDecode

Initializes the extension from a DER-encoded byte array that contains the extension value.

InitializeDecode

Initializes the extension from a Distinguished Encoding Rules (DER) encoded byte array that contains the extension value.
InitializeDefaults

Initializes a CCertSrvSetup object with default values to enable installation of the Certification Authority role.

InitializeDefaults

Initializes a CMSCEPSetup object with default values to enable installation of a Network Device Enrollment Service (NDES) role.

InitializeEncode

Initializes the object from a string and a value that identifies the qualifier type.

InitializeEncode

Initializes the attribute from an IX509PrivateKey object, the certification authority encryption certificate, and the symmetric
encryption algorithm object identifier (OID).

InitializeEncode

Initializes the attribute from information about the user, client computer, and application that submitted the certificate
request.

InitializeEncode

Initializes the attribute from information about the provider.

InitializeEncode

Initializes the object from an IX509Extensions collection.

InitializeEncode

Initializes the attribute from operating system version information.

InitializeEncode

Initializes the attribute by using the certificate to be renewed.

InitializeEncode

Initializes the extension from an IAlternativeNames collection.

InitializeEncode

Initializes the extension from a byte array.

InitializeEncode

Initializes the extension from a Boolean value that indicates whether the certificate subject is a certification authority (CA) and
an integer that contains the depth of the subordinate CA chain.

InitializeEncode

Initializes the object from an ICertificatePolicies collection.

InitializeEncode

Initializes the extension from a collection of IObjectId object identifiers (OIDs) that specify the intended uses of the public key.

InitializeEncode

Initializes the extension by using the X509KeyUsageFlags enumeration.

InitializeEncode

Initializes the extension from an ICertificatePolicies collection.

InitializeEncode

Initializes the extension from an ISmimeCapabilities collection.

InitializeEncode

Initializes the extension from a byte array that contains the key identifier.

InitializeEncode

Initializes the extension from a template object identifier (OID) and from major and minor version numbers.

InitializeEncode

Initializes the extension from a string that contains the template name.

InitializeEncodeFromEncryptedKeyBlob

Initializes the attribute from an encrypted private key.

InitializeForPending

Initialize the instance to prepare to generate a message to either retrieve an issued certificate, or install a response for a
previous request by the issuer.

InitializeFromAlgorithmName

Initializes the object from an algorithm name or an object identifier.

InitializeFromCertificate

Initializes the collection from the properties contained in a certificate.

InitializeFromCertificate

Initializes the object by using a property value associated with an existing certificate.

InitializeFromCertificate

Initializes the certificate request by using an existing certificate.

InitializeFromCertificate

Initializes the certificate request by using an existing certificate.

InitializeFromCertificateHash

Initializes the object from the new certificate.

InitializeFromCurrentTime

Initializes the property from a Boolean value and the current system date and time.

InitializeFromEncodedPublicKeyInfo

Initializes the object from a byte array that contains a public key.

InitializeFromInnerRequest

Initializes the certificate request from the inner PKCS

InitializeFromInnerRequestTemplate

Initializes the certificate request from an inner request object and a template.

InitializeFromInnerRequestTemplateName

The InitializeFromInnerRequestTemplateName method initializes the certificate request from an inner request object and a
template.

InitializeFromLocalRequestOriginator

Initializes the object from the DNS name of the local computer.

InitializeFromName

Initializes the object from a string that contains a provider name.

InitializeFromName

Initializes the object from a CERTENROLL_OBJECTID enumeration value.

InitializeFromObjectId

Initializes a cryptographic attribute by using an object identifier.

InitializeFromOtherName

Initializes the object from an object identifier (OID) and the associated raw data (byte array).

InitializeFromPrivateKey

Initializes the certificate request by using an IX509PrivateKey object and, optionally, a template.
InitializeFromPrivateKeyTemplate

Initializes the certificate request by using an IX509PrivateKey object and a certificate template.

InitializeFromPrivateKeyTemplate

Initializes the certificate request by using an IX509PrivateKey object and a certificate template.

InitializeFromProperties

Creates a property set from the properties contained in an existing server configuration.

InitializeFromPublicKey

Initializes a null-signed certificate request by using an IX509PublicKey object and, optionally, a template.

InitializeFromPublicKeyTemplate

Initializes a null-signed certificate request by using an IX509PublicKey object and a template.

InitializeFromRawData

Initializes the object from a Digital Signature Algorithm (DSA) GUID, an X.500 directory name, or an Internet Protocol (IP)
address contained in a Distinguished Encoding Rules (DER) encoded byte array.

InitializeFromRequest

Initializes the enrollment object from an existing IX509CertificateRequest object.

InitializeFromString

Initializes the object from a string that contains an email address, a Domain Name System (DNS) name, a URL, a registered
object identifier (OID), or a user principal name (UPN).

InitializeFromTemplate

Initializes the certificate request by using a template.

InitializeFromTemplate

Initializes the certificate request by using a template.

InitializeFromTemplate

Initializes the certificate request by using a template.

InitializeFromTemplate

Initializes the certificate request by using a template.

InitializeFromTemplate

Initializes the enrollment object by using a template.

InitializeFromTemplateName

InitializeFromTemplateName

Initializes the certificate request by using a template.

InitializeFromTemplateName

Initializes the enrollment object from a template common name (CN).

InitializeFromType

Initializes the object from the default cryptographic provider.

InitializeFromValue

Initializes the object from a string that contains a dotted decimal object identifier (OID).

InitializeFromValues

Initializes a cryptographic attribute by using an IX509Attributes object.

InitializeImport

Initializes the certificate enrollment policy (CEP) server from a collection of templates and object identifiers.

InitializeInstallDefaults

Initializes the ICertificateEnrollmentPolicyServerSetup object with a default configuration.

InitializeInstallDefaults

Initializes the ICertificateEnrollmentServerSetup object with a default configuration.

InitializeSecurityContextA

Initiates the client side, outbound security context from a credential handle.

InitializeSecurityContextW

Initiates the client side, outbound security context from a credential handle.

InitializeSecurityDescriptor

Initializes a new security descriptor.

InitializeSid

Initializes a security identifier (SID).

InitSecurityInterfaceA

The InitSecurityInterface function returns a pointer to an SSPI dispatch table. This function enables clients to use SSPI without
binding directly to an implementation of the interface.

InitSecurityInterfaceW

The InitSecurityInterface function returns a pointer to an SSPI dispatch table. This function enables clients to use SSPI without
binding directly to an implementation of the interface.

Install

Installs the Certificate Enrollment Policy (CEP) Web Service configured by the ICertificateEnrollmentPolicyServerSetup object.

Install

Installs the Certificate Enrollment Web Service (CES) configured by the ICertificateEnrollmentServerSetup object.

Install

Installs a role as configured in the CCertSrvSetup object.

Install

Installs a Network Device Enrollment Service (NDES) role as configured in a CMSCEPSetup object.

InstallPKCS7

Processes a certificate or chain of certificates, placing them into the appropriate certificate stores. This method differs from the
acceptPKCS7 method in that InstallPKCS7 does not receive a request certificate.

InstallPKCS7Blob

Processes a certificate or chain of certificates, placing them into the appropriate certificate stores. This method differs from the
acceptPKCS7Blob method in that InstallPKCS7Blob does not receive a request certificate.

InstallPKCS7BlobEx

The same as InstallPKCS7Blob except that it returns the number of certificates actually installed in local stores.

InstallPKCS7Ex

Processes a certificate or chain of certificates, placing them into the appropriate certificate stores.InstallPKCS7 except that it
returns the number of certificates actually installed in local stores.

InstallResponse

Installs a certificate chain on the end-entity computer.

InstallResponse2

Installs a certificate chain on the end-entity computer.

IsCatalogFile

Retrieves a Boolean value that indicates whether the specified file is a catalog file.
IsDaclCanonical

The IsDaclCanonical method determines whether the ACEs contained in the specified DACL structure are ordered according to
the definition of DACL ordering implemented by the client.

IsDirty

The IsDirty method returns a value indicating whether data in the attachment snap-in has been modified since it was last
saved.

IsFunctionalLevelUpgradeSupported

Gets a Boolean value that indicates whether the version of this authorization store can be upgraded.

IsIndexed

Reports whether the data in the column is indexed.

IsInRoleAssignment

Checks whether the principal represented by the current client context is a member of the specified role in the specified scope.

IsMSCEPStoreEmpty

Always returns VARIANT_TRUE. It should not be used.

IsPropertyEditable

Indicates to the caller whether a specified property can be edited.

IsSmartCard

Retrieves a Boolean value that indicates whether any of the cryptographic providers associated with the request object is a
smart card provider.

IsTokenRestricted

Indicates whether a token contains a list of restricted security identifiers (SIDs).

IsUpdateNeeded

Checks whether the persisted version of this authorization store is newer than the cached version.

IsValidAcl

Validates an access control list (ACL).

IsValidCertificate

Verifies the certificate against the certification authority (CA) key and checks that the certificate has not been revoked. This
method was first defined in the ICertAdmin interface.

IsValidSecurityDescriptor

Determines whether the components of a security descriptor are valid.

IsValidSid

Validates a security identifier (SID) by verifying that the revision number is within a known range, and that the number of
subauthorities is less than the maximum.

IsWellKnownSid

Compares a SID to a well-known SID and returns TRUE if they match.

KeyCredentialManagerFreeInformation

API to free the KeyCredentialManagerInfo pointer variable from the KeyCredentialManagerGetInformation call.

KeyCredentialManagerGetInformation

API to get a unique identifier of the users enrollment.

KeyCredentialManagerGetOperationErrorStates

Prerequisite API to call to determine if the operation will be successful prior.

KeyCredentialManagerShowUIOperation

API to perform the requested WHFB operation.

KspDeleteContextFn

Deletes a security context.

KspMakeSignatureFn

Generates a signature based on the specified message and security context.

KspVerifySignatureFn

Verifies that the message received is correct according to the signature.

LoadPolicy

Retrieves policy information from the certificate enrollment policy (CEP) server.

LockServiceDatabase

Requests ownership of the service control manager (SCM) database lock. Only one process can own the lock at any specified
time.

LogonUserA

The Win32 LogonUser function attempts to log a user on to the local computer. LogonUser returns a handle to a user token
that you can use to impersonate user.

LogonUserExA

The LogonUserEx function attempts to log a user on to the local computer.

LogonUserExW

The LogonUserEx function attempts to log a user on to the local computer.

LogonUserW

The Win32 LogonUser function attempts to log a user on to the local computer. LogonUser returns a handle to a user token
that you can use to impersonate user.

LookupAccountNameA

Accepts the name of a system and an account as input. It retrieves a security identifier (SID) for the account and the name of
the domain on which the account was found.

LookupAccountNameW

Accepts the name of a system and an account as input. It retrieves a security identifier (SID) for the account and the name of
the domain on which the account was found.

LookupAccountSidA

Accepts a security identifier (SID) as input. It retrieves the name of the account for this SID and the name of the first domain
on which this SID is found.

LookupAccountSidLocalA

Retrieves the name of the account for the specified SID on the local machine.

LookupAccountSidLocalW

Retrieves the name of the account for the specified SID on the local machine.

LookupAccountSidW

Accepts a security identifier (SID) as input. It retrieves the name of the account for this SID and the name of the first domain
on which this SID is found.

LookupPrivilegeDisplayNameA

Retrieves the display name that represents a specified privilege.

LookupPrivilegeDisplayNameW

Retrieves the display name that represents a specified privilege.

LookupPrivilegeNameA

Retrieves the name that corresponds to the privilege represented on a specific system by a specified locally unique identifier
(LUID).

LookupPrivilegeNameW

Retrieves the name that corresponds to the privilege represented on a specific system by a specified locally unique identifier
(LUID).
LookupPrivilegeValueA

Retrieves the locally unique identifier (LUID) used on a specified system to locally represent the specified privilege name.

LookupPrivilegeValueW

Retrieves the locally unique identifier (LUID) used on a specified system to locally represent the specified privilege name.

LookupSecurityDescriptorPartsA

Retrieves security information from a self-relative security descriptor.

LookupSecurityDescriptorPartsW

Retrieves security information from a self-relative security descriptor.

LookupSids

The LookupSids method returns the common names corresponding to each of the elements in the specified list of SIDs.

LPHANDLER_FUNCTION

An application-defined callback function used with the RegisterServiceCtrlHandler function. A service program can use it as the
control handler function of a particular service.

LPHANDLER_FUNCTION_EX

An application-defined callback function used with the RegisterServiceCtrlHandlerEx function. A service program can use it as
the control handler function of a particular service.

LPSERVICE_MAIN_FUNCTIONA

The entry point for a service.

LPSERVICE_MAIN_FUNCTIONW

The entry point for a service.

LSA_ADD_CREDENTIAL

Adds credentials to a logon session.

LSA_ALLOCATE_CLIENT_BUFFER

Allocates a buffer in the client's address space.

LSA_ALLOCATE_LSA_HEAP

Allocates memory on the heap. Some information passed back to the LSA is expected to be allocated using this function.

LSA_ALLOCATE_PRIVATE_HEAP

Allocates memory on the private heap.

LSA_ALLOCATE_SHARED_MEMORY

The AllocateSharedMemory function allocates a block of shared memory from a section of memory previously reserved by a
call to the CreateSharedMemory function.

LSA_AP_CALL_PACKAGE

Called by the Local Security Authority (LSA) when a logon application with a trusted connection to the LSA calls the
LsaCallAuthenticationPackage function and specifies the authentication package's identifier.

LSA_AP_CALL_PACKAGE_PASSTHROUGH

The dispatch function for pass-through logon requests sent to the LsaCallAuthenticationPackage function.

LSA_AP_INITIALIZE_PACKAGE

Called once by the Local Security Authority (LSA) during system initialization to provide the authentication package a chance
to initialize itself.

LSA_AP_LOGON_TERMINATED

Used to notify an authentication package when a logon session terminates. A logon session terminates when the last token
referencing the logon session is deleted.

LSA_AP_LOGON_USER

Authenticates a user's logon credentials.

LSA_AP_LOGON_USER_EX

Authenticates a user's logon credentials.

LSA_AP_LOGON_USER_EX2

Used to authenticate a user logon attempt on the user's initial logon. A new logon session is established for the user, and
validation information for the user is returned.

LSA_AUDIT_ACCOUNT_LOGON

The AuditAccountLogon function produces an audit record that represents the mapping of a foreign principal name onto a
Windows account.

LSA_AUDIT_LOGON

The AuditLogon function is used to audit a logon attempt.

LSA_CALL_PACKAGE

The CallPackage function is used to call another security package to access its services.

LSA_CALL_PACKAGE_PASSTHROUGH

The CallPackagePassthrough function is used to call another security package to access its services.
LSA_CALL_PACKAGEEX

The CallPackageEx function is used to call another security package to access its services.

LSA_CANCEL_NOTIFICATION

The CancelNotification function cancels a previously registered notification.

LSA_CLIENT_CALLBACK

Allows a Local Security Authority (LSA)-mode security package to call back to its user-mode package and invoke a function in
its DLL there.

LSA_CLOSE_SAM_USER

Closes a handle to a Security Accounts Manager (SAM) user account.

LSA_CONVERT_AUTH_DATA_TO_TOKEN

The ConvertAuthDataToToken function creates an access token from the authorization data returned from the
GetAuthDataForUser or GetUserAuthData functions.

LSA_COPY_FROM_CLIENT_BUFFER

Copies information from the address space of a client process into a buffer in the current process.

LSA_COPY_TO_CLIENT_BUFFER

Copies information from a buffer in the current process into a client process's address space.

LSA_CRACK_SINGLE_NAME

The CrackSingleName function converts a name from one format to another.

LSA_CREATE_LOGON_SESSION

Creates logon sessions.

LSA_CREATE_SHARED_MEMORY

The CreateSharedMemory function creates a section of memory that is shared by client processes and the security package.

LSA_CREATE_THREAD

A wrapper for the Windows CreateThread function that should be used by the Local Security Authority (LSA).

LSA_CREATE_TOKEN

The CreateToken function is used by SSP/APs to create tokens while processing calls to SpAcceptLsaModeContext.

LSA_CREATE_TOKEN_EX

Creates tokens while processing calls to SpAcceptLsaModeContext.

LSA_DELETE_CREDENTIAL

Deletes an existing credential.

LSA_DELETE_LOGON_SESSION

Cleans up any logon sessions created while determining whether a user's authentication information is legitimate.

LSA_DELETE_SHARED_MEMORY

The DeleteSharedMemory function releases a section of memory that is shared by clients and a security package.

LSA_DUPLICATE_HANDLE

The DuplicateHandle function creates a duplicate handle. The returned duplicate is in the caller's process space.

LSA_EXPAND_AUTH_DATA_FOR_DOMAIN

Expands the domain groups in the specified user authentication data.

LSA_FREE_CLIENT_BUFFER

Frees a client buffer previously allocated with the AllocateClientBuffer function.

LSA_FREE_LSA_HEAP

The FreeReturnBuffer function is used to free buffers allocated by the Local Security Authority (LSA) and returned to the
security package. The package calls this function when the information in the returned buffer is no longer needed.

LSA_FREE_LSA_HEAP

Deallocates heap memory previously allocated by AllocateLsaHeap.

LSA_FREE_PRIVATE_HEAP

Frees memory that was allocated by using the AllocatePrivateHeap function.

LSA_FREE_SHARED_MEMORY

The FreeSharedMemory function frees a block of shared memory previously allocated by the AllocateSharedMemory function.

LSA_GET_AUTH_DATA_FOR_USER

The GetAuthDataForUser function retrieves authentication information for a user from the Security Accounts Manager (SAM)
database and puts it into a format suitable for the ConvertAuthDataToToken function.

LSA_GET_CALL_INFO

The GetCallInfo function retrieves information about the most recent function call.

LSA_GET_CLIENT_INFO

The GetClientInfo function gets information about the client process, such as thread and process ID, and flags indicating the
client's state and privileges.
LSA_GET_CREDENTIALS

Retrieves credentials associated with a logon session.

LSA_GET_USER_AUTH_DATA

The GetUserAuthData function returns the authorization data for the user in a single buffer.

LSA_MAP_BUFFER

Maps a SecBuffer structure into the address space of the security support provider/authentication package (SSP/AP).

LSA_OPEN_SAM_USER

Retrieves a handle to a user account in the Security Accounts Manager (SAM) database.

LSA_OPEN_TOKEN_BY_LOGON_ID

Opens the user access token associated with the specified user logon.

LSA_PROTECT_MEMORY

Encrypts the specified memory buffer.

LSA_REGISTER_NOTIFICATION

Provides a mechanism whereby the security package is notified. Notification can occur at fixed intervals, when an event object
is signaled, or during certain system events.

LSA_UPDATE_PRIMARY_CREDENTIALS

Provides a mechanism for one security package to notify other packages that the credentials for a logon session have
changed.

LsaAddAccountRights

Assigns one or more privileges to an account.

LsaCallAuthenticationPackage

Used by a logon application to communicate with an authentication package.

LsaClose

The LsaClose function closes a handle to a Policy or TrustedDomain object.

LsaConnectUntrusted

Establishes an untrusted connection to the LSA server.

LsaCreateTrustedDomainEx

The LsaCreateTrustedDomainEx function establishes a new trusted domain by creating a new TrustedDomain object.
LsaDeleteTrustedDomain

The LsaDeleteTrustedDomain function removes a trusted domain from the list of trusted domains for a system and deletes the
associated TrustedDomain object.

LsaDeregisterLogonProcess

Deletes the caller's logon application context and closes the connection to the LSA server.

LsaEnumerateAccountRights

The LsaEnumerateAccountRights function enumerates the privileges assigned to an account.

LsaEnumerateAccountsWithUserRight

Returns the accounts in the database of a Local Security Authority (LSA) Policy object that hold a specified privilege.

LsaEnumerateLogonSessions

Retrieves the set of existing logon session identifiers (LUIDs) and the number of sessions.

LsaEnumerateTrustedDomains

The LsaEnumerateTrustedDomains function retrieves the names and SIDs of domains trusted to authenticate logon
credentials.

LsaEnumerateTrustedDomainsEx

Returns information about the domains trusted by the local system.

LsaFreeMemory

The LsaFreeMemory function frees memory allocated for an output buffer by an LSA function call.

LsaFreeReturnBuffer

Frees the memory used by a buffer previously allocated by the LSA.

LsaGetAppliedCAPIDs

Returns an array of central access policies (CAPs) identifiers (CAPIDs) of all the CAPs applied on a specific computer.

LsaGetLogonSessionData

Retrieves information about a specified logon session.

LsaLogonUser

Authenticates a security principal's logon data by using stored credentials information.

LsaLookupAuthenticationPackage

Obtains the unique identifier of an authentication package.

LsaLookupNames

Retrieves the security identifiers (SIDs) that correspond to an array of user, group, or local group names.

LsaLookupPrivilegeValue

Retrieves the locally unique identifier (LUID) used by the Local Security Authority (LSA) to represent the specified privilege
name.

LsaLookupSids

Looks up the names that correspond to an array of security identifiers (SIDs). If LsaLookupSids cannot find a name that
corresponds to a SID, the function returns the SID in character form.

LsaLookupSids2

Looks up the names that correspond to an array of security identifiers (SIDs) and supports Internet provider identities. If
LsaLookupSids2 cannot find a name that corresponds to a SID, the function returns the SID in character form.

LsaNtStatusToWinError

The LsaNtStatusToWinError function converts an NTSTATUS code returned by an LSA function to a Windows error code.

LsaOpenPolicy

Opens a handle to the Policy object on a local or remote system.

LsaOpenTrustedDomainByName

The LsaOpenTrustedDomainByName function opens the LSA policy handle of a remote trusted domain. You can pass this
handle into LSA function calls in order to set or query the LSA policy of the remote machine.

LsaQueryCAPs

Returns the Central Access Policies (CAPs) for the specified IDs.

LsaQueryDomainInformationPolicy

Retrieves domain information from the Policyobject.

LsaQueryForestTrustInformation

Retrieves forest trust information for the specified Local Security Authority�TrustedDomain object.

LsaQueryInformationPolicy

Retrieves information about a Policy object.

LsaQueryTrustedDomainInfo

The LsaQueryTrustedDomainInfo function retrieves information about a trusted domain.

LsaQueryTrustedDomainInfoByName

The LsaQueryTrustedDomainInfoByName function returns information about a trusted domain.

LsaRegisterLogonProcess

Establishes a connection to the LSA server and verifies that the caller is a logon application.

LsaRegisterPolicyChangeNotification

The LsaRegisterPolicyChangeNotification function registers an event handle with the local security authority (LSA). This event
handle is signaled whenever the indicated LSA policy is modified.

LsaRemoveAccountRights

Removes one or more privileges from an account.

LsaRetrievePrivateData

Do not use the LSA private data functions. Instead, use the CryptProtectData and CryptUnprotectData functions.

LsaSetDomainInformationPolicy

Sets domain information to the Policyobject.

LsaSetForestTrustInformation

Sets the forest trust information for a specified Local Security Authority�TrustedDomain object.

LsaSetInformationPolicy

Modifies information in a Policy object.

LsaSetTrustedDomainInfoByName

The LsaSetTrustedDomainInfoByName function sets values for a TrustedDomain object.

LsaSetTrustedDomainInformation

The LsaSetTrustedDomainInformation function modifies a Policy object's information about a trusted domain.

LsaStorePrivateData

Do not use the LSA private data functions. Instead, use the CryptProtectData and CryptUnprotectData functions.

LsaUnregisterPolicyChangeNotification

The LsaUnregisterPolicyChangeNotification function disables a previously registered notification event.

MakeAbsoluteSD

Creates a security descriptor in absolute format by using a security descriptor in self-relative format as a template.

MakeSelfRelativeSD

Creates a security descriptor in self-relative format by using a security descriptor in absolute format as a template.
MakeSignature

Generates a cryptographic checksum of the message, and also includes sequencing information to prevent message loss or
insertion.

MapGeneric

The MapGeneric method requests that the generic access rights in an access mask be mapped to their corresponding
standard and specific access rights.

MapGenericMask

Maps the generic access rights in an access mask to specific and standard access rights. The function applies a mapping
supplied in a GENERIC_MAPPING structure.

Msv1_0SubAuthenticationFilter

Performs user logon authentication that is specific to domain controllers.

Msv1_0SubAuthenticationRoutine

Performs client/server-specific authentication.

Msv1_0SubAuthenticationRoutineEx

Performs Remote Access Service authentication when subauthentication is requested by calling the LogonUser function.

Msv1_0SubAuthenticationRoutineGeneric

Performs Remote Access Service authentication when subauthentication is requested by calling the
LsaCallAuthenticationPackage function.

NameFromSid

Gets the display name that corresponds to the specified security identifier (SID).

NamesFromSids

Gets the display names that correspond to the specified security identifiers (SIDs).

NCryptCloseProtectionDescriptor

Zeros and frees a protection descriptor object and releases its handle.

NCryptCreateClaim

Creates a key attestation claim.

NCryptCreatePersistedKey

Creates a new key and stores it in the specified key storage provider.

NCryptCreateProtectionDescriptor

Retrieves a handle to a protection descriptor object.

NCryptDecrypt

Decrypts a block of encrypted data.

NCryptDeleteKey

Deletes a CNG key.

NCryptDeriveKey

Derives a key from a secret agreement value.

NCryptEncrypt

Encrypts a block of data.

NCryptEnumAlgorithms

Obtains the names of the algorithms that are supported by the specified key storage provider.

NCryptEnumKeys

Obtains the names of the keys that are stored by the provider.

NCryptEnumStorageProviders

Obtains the names of the registered key storage providers.

NCryptExportKey

Exports a CNG key to a memory BLOB.

NCryptFinalizeKey

Completes a CNG key storage key.

NCryptFreeBuffer

Releases a block of memory allocated by a CNG key storage provider.

NCryptFreeObject

Frees a CNG key storage object.

NCryptGetProperty

Retrieves the value of a named property for a key storage object.

NCryptGetProtectionDescriptorInfo

Retrieves a protection descriptor rule string.

NCryptImportKey

Imports a Cryptography API:_Next Generation (CNG) key from a memory BLOB.

NCryptIsAlgSupported

Determines if a CNG key storage provider supports a specific cryptographic algorithm.

NCryptIsKeyHandle

Determines if the specified handle is a CNG key handle.

NCryptKeyDerivation

Creates a key from another key by using the specified key derivation function.

NCryptNotifyChangeKey

Creates or removes a key change notification.

NCryptOpenKey

Opens a key that exists in the specified CNG key storage provider.

NCryptOpenStorageProvider

Loads and initializes a CNG key storage provider.

NCryptProtectSecret

Encrypts data to a specified protection descriptor.

NCryptQueryProtectionDescriptorName

Retrieves the protection descriptor rule string associated with a registered descriptor display name.

NCryptRegisterProtectionDescriptorName

Registers the display name and the associated rule string for a protection descriptor.

NCryptSecretAgreement

Creates a secret agreement value from a private and a public key.

NCryptSetProperty

Sets the value for a named property for a CNG key storage object.

NCryptSignHash

Creates a signature of a hash value.

NCryptStreamClose

Closes a data protection stream object opened by using the NCryptStreamOpenToProtect or NCryptStreamOpenToUnprotect
functions.
NCryptStreamOpenToProtect

Opens a stream object that can be used to encrypt large amounts of data to a given protection descriptor.

NCryptStreamOpenToUnprotect

Opens a stream object that can be used to decrypt large amounts of data to the same protection descriptor used for
encryption.

NCryptStreamOpenToUnprotectEx

Opens a stream object that can be used to decrypt large amounts of data to the same protection descriptor used for
encryption.

NCryptStreamUpdate

Encrypts and decrypts blocks of data.

NCryptTranslateHandle

Translates a CryptoAPI handle into a CNG key handle.

NCryptUnprotectSecret

Decrypts data to a specified protection descriptor.

NCryptVerifyClaim

Verifies a key attestation claim.

NCryptVerifySignature

Verifies that the specified signature matches the specified hash.

NetAddServiceAccount

Creates a standalone managed service account (sMSA) or retrieves the credentials for a group managed service account
(gMSA) and stores the account information on the local computer.

NetEnumerateServiceAccounts

Enumerates the standalone managed service accounts (sMSA) on the specified server.

NetIsServiceAccount

Tests whether the specified standalone managed service account (sMSA) or group managed service account (gMSA) exists in
the Netlogon store on the specified server.

NetQueryServiceAccount

Gets information about the specified managed service account.

NetRemoveServiceAccount

Deletes the specified service account from the Active Directory database if the account is a standalone managed service
account (sMSA).
Next

Retrieves the index of the next available Certificate Services server configuration in the configuration point. This method was
first defined in the ICertConfig interface.

Next

Moves to the next attribute in the attribute-enumeration sequence.

Next

Moves to the next column in the column-enumeration sequence.

Next

Moves to the next extension in the extension-enumeration sequence.

Next

Moves to the next row in the row-enumeration sequence.

Notify

Notifies the plug-in of the transaction status of the SCEP certificate request.

Notify

Called by the server engine to notify an exit module that an event has occurred.

NotifyBootConfigStatus

Reports the boot status to the service control manager. It is used by boot verification programs.

NotifyServiceStatusChangeA

Enables an application to receive notification when the specified service is created or deleted or when its status changes.

NotifyServiceStatusChangeW

Enables an application to receive notification when the specified service is created or deleted or when its status changes.

NPAddConnection

Connects a local device to a network resource.

NPAddConnection3

Connects a local device to a network resource.

NPCancelConnection

Disconnects a network connection.

NPCloseEnum

Closes an enumeration.

NPDeviceMode

Specifies the parent window of a device. This window owns any dialog boxes that originate from the device.

NPDirectoryNotify

Notifies the network provider of certain directory operations.

NPEnumResource

Performs an enumeration based on a handle returned by NPOpenEnum.

NPFMXEditPerm

Enables network vendors to supply their own permission editor dialog boxes.

NPFMXGetPermCaps

Retrieves the capabilities of the permission editor. The return value is a bitmask that indicates which of the Security menu items
in File Manager are to be enabled.

NPFMXGetPermHelp

Retrieves the help file and help context of the permission editor dialog boxes when a menu item in the Security menu of File
Manager is selected and F1 is pressed.

NPFormatNetworkName

Formats a network name in a provider-specific format for display in a control.

NPGetCaps

Returns information about which services are supported on the network.

NPGetConnection

Retrieves information about a connection.

NPGetConnection3

Retrieves information about a network connection, even if it is currently disconnected.

NPGetConnectionPerformance

Returns information about the expected performance of a connection used to access a network resource. The request can only
be for a network resource that is currently connected.

NPGetDirectoryType

Determines the type of a network directory.

NPGetPropertyText

Retrieves the names of buttons to add to a property dialog box for a network resource.

NPGetResourceInformation

Separates the part of a network resource accessed through the WNet API from the part accessed through APIs specific to the
resource type.

NPGetResourceParent

Retrieves the parent of a specified network resource in the browse hierarchy.

NPGetUniversalName

Retrieves the universal name of a network resource. The NPGetUniversalName function can retrieve this universal name in
UNC format or in the older, remote-name format.

NPGetUser

Retrieves the value of the current default user name or the user name used to establish a network connection.

NPLogonNotify

MPR calls this function to notify the credential manager that a logon event has occurred, allowing the credential manager to
return a logon script.

NPOpenEnum

Opens an enumeration of network resources or existing connections. The NPOpenEnum function must be called to obtain a
valid handle for an enumeration.

NPPasswordChangeNotify

MPR calls this function to notify the credential manager of a password change event.

NPPropertyDialog

Called when the user clicks a button added by using the NPPropertyDialog function. The NPPropertyDialog function is called
only for file and directory network properties.

NPSearchDialog

Enables network vendors to supply their own form of browsing and search, beyond the hierarchical view presented in the
Connection dialog box.

ObjectCloseAuditAlarmA

Generates an audit message in the security event log when a handle to a private object is deleted.

ObjectCloseAuditAlarmW

Generates an audit message in the security event log when a handle to a private object is deleted.
ObjectDeleteAuditAlarmA

Generates audit messages when an object is deleted.

ObjectDeleteAuditAlarmW

Generates audit messages when an object is deleted.

ObjectOpenAuditAlarmA

Generates audit messages when a client application attempts to gain access to an object or to create a new one.

ObjectOpenAuditAlarmW

Generates audit messages when a client application attempts to gain access to an object or to create a new one.

ObjectPrivilegeAuditAlarmA

Generates an audit message in the security event log.

ObjectPrivilegeAuditAlarmW

Generates an audit message in the security event log.

Open

Opens the endorsement key. The endorsement key must be open before you can retrieve an information from the
endorsement key, add or remove certificates, or export the endorsement key.

Open

Opens an existing private key.

OpenApplication

Opens the IAzApplication object with the specified name.

OpenApplication2

Opens the IAzApplication2 object with the specified name.

OpenApplicationGroup

Opens an IAzApplicationGroup object by specifying its name.

OpenApplicationGroup

Opens an IAzApplicationGroup object by specifying its name.

OpenApplicationGroup

Opens an IAzApplicationGroup object by specifying its name.

OpenConnection

Establishes a connection with a Certificate Services server.

OpenElevatedEditor

Opens an access control editor when a user clicks the Edit button on an access control editor page that displays an image of a
shield on that Edit button.

OpenOperation

Opens an IAzOperation object with the specified name.

OpenPersonalTrustDBDialog

Displays the Certificates dialog box.

OpenPersonalTrustDBDialogEx

Displays the Certificates dialog box.

OpenProcessToken

Opens the access token associated with a process.

OpenRole

Opens an IAzRole object with the specified name.

OpenRole

Opens an IAzRole object with the specified name.

OpenRoleAssignment

Opens an IAzRoleAssignment object with the specified name.

OpenRoleAssignment

Opens an IAzRoleAssignment object with the specified name in this scope.

OpenRoleDefinition

Opens an IAzRoleDefinition object with the specified name.

OpenRoleDefinition

Opens an IAzRoleDefinition object with the specified name in this scope.

OpenSCManagerA

Establishes a connection to the service control manager on the specified computer and opens the specified service control
manager database.
OpenSCManagerW

Establishes a connection to the service control manager on the specified computer and opens the specified service control
manager database.

OpenScope

Opens an IAzScope object with the specified name.

OpenScope2

Opens an IAzScope2 object with the specified name.

OpenServiceA

Opens an existing service.

OpenServiceW

Opens an existing service.

OpenTask

Opens an IAzTask object with the specified name.

OpenTask

Opens an IAzTask object with the specified name.

OpenThreadToken

Opens the access token associated with a thread.

OpenView

Opens a view to a Certificate Services database and instantiates an instance of an IEnumCERTVIEWROW object.

PCRYPT_DECRYPT_PRIVATE_KEY_FUNC

Decrypts the private key and returns the decrypted key in the pbClearTextKey parameter.

PCRYPT_ENCRYPT_PRIVATE_KEY_FUNC

Encrypts the private key and returns the encrypted contents in the pbEncryptedKey parameter.

PCRYPT_RESOLVE_HCRYPTPROV_FUNC

Returns a handle to a cryptographic service provider (CSP) by using the phCryptProv parameter to receive the key being
imported.

pCryptSIPGetCaps

Is implemented by a subject interface package (SIP) to report capabilities.

PFN_CDF_PARSE_ERROR_CALLBACK

Called for Catalog Definition Function errors while parsing a catalog definition file (CDF).

PFN_CERT_CHAIN_FIND_BY_ISSUER_CALLBACK

An application-defined callback function that allows the application to filter certificates that might be added to the certificate
chain.

PFN_CERT_CREATE_CONTEXT_SORT_FUNC

Called for each sorted context entry when a context is created.

PFN_CERT_DLL_OPEN_STORE_PROV_FUNC

Implemented by a store-provider and is used to open a store.

PFN_CERT_ENUM_PHYSICAL_STORE

The CertEnumPhysicalStoreCallback callback function formats and presents information on each physical store found by a call
to CertEnumPhysicalStore.

PFN_CERT_ENUM_SYSTEM_STORE

The CertEnumSystemStoreCallback callback function formats and presents information on each system store found by a call to
CertEnumSystemStore.

PFN_CERT_ENUM_SYSTEM_STORE_LOCATION

The CertEnumSystemStoreLocationCallback callback function formats and presents information on each system store location
found by a call to CertEnumSystemStoreLocation.

PFN_CERT_STORE_PROV_CLOSE

An application-defined callback function that is called by CertCloseStore when the store's reference count is decremented to
zero.

PFN_CERT_STORE_PROV_CONTROL

The CertStoreProvControl callback function supports the CertControlStore API. All of the API's parameters are passed straight
through to the callback. For details, see CertControlStore.

PFN_CERT_STORE_PROV_DELETE_CERT

An application-defined callback function that is called by CertDeleteCertificateFromStore before deleting a certificate from the
store.

PFN_CERT_STORE_PROV_DELETE_CRL

An application-defined callback function that is called by CertDeleteCRLFromStore before deleting the CRL from the store.

PFN_CERT_STORE_PROV_READ_CERT

An application-defined callback function that reads the provider's copy of the certificate context.
PFN_CERT_STORE_PROV_READ_CRL

An application-defined callback function that reads the provider's copy of the CRL context.

PFN_CERT_STORE_PROV_READ_CTL

The CertStoreProvReadCTL callback function is called to read the provider's copy of the CTL context and, if it exists, to create a
new CTL context.

PFN_CERT_STORE_PROV_SET_CERT_PROPERTY

An application-defined callback function that is called by CertSetCertificateContextProperty before setting the certificate's
property.

PFN_CERT_STORE_PROV_SET_CRL_PROPERTY

An application-defined callback function that is called by CertSetCRLContextProperty before setting the CRL's property.

PFN_CERT_STORE_PROV_SET_CTL_PROPERTY

The CertStoreProvSetCTLProperty callback function determines whether a property can be set on a CTL.

PFN_CERT_STORE_PROV_WRITE_CERT

An application-defined callback function that is called by CertAddEncodedCertificateToStore, CertAddCertificateContextToStore

and CertAddSerializedElementToStore before adding to the store.

PFN_CERT_STORE_PROV_WRITE_CRL

An application-defined callback function that is called by CertAddEncodedCRLToStore, CertAddCRLContextToStore and

CertAddSerializedElementToStore before adding to the store.

PFN_CERT_STORE_PROV_WRITE_CTL

The CertStoreProvWriteCTL callback function can be called by CertAddEncodedCTLToStore, CertAddCTLContextToStore or

CertAddSerializedElementToStore before a CTL is added to the store.

PFN_CMSG_CNG_IMPORT_CONTENT_ENCRYPT_KEY

Imports an already decrypted content encryption key (CEK).

PFN_CMSG_CNG_IMPORT_KEY_AGREE

Decrypts a content encryption key (CEK) that is intended for a key agreement recipient.

PFN_CMSG_CNG_IMPORT_KEY_TRANS

Imports and decrypts a content encryption key (CEK) that is intended for a key transport recipient.

PFN_CMSG_EXPORT_KEY_AGREE

Encrypts and exports the content encryption key for a key agreement recipient of an enveloped message.

PFN_CMSG_EXPORT_KEY_TRANS

Encrypts and exports the content encryption key for a key transport recipient of an enveloped message.
PFN_CMSG_EXPORT_MAIL_LIST

Encrypts and exports the content encryption key for a mailing list recipient of an enveloped message.

PFN_CMSG_GEN_CONTENT_ENCRYPT_KEY

Generates the symmetric key used to encrypt content for an enveloped message.

PFN_CMSG_IMPORT_KEY_AGREE

Imports a content encryption key for a key transport recipient of an enveloped message.

PFN_CMSG_IMPORT_KEY_TRANS

Imports a content encryption key for a key transport recipient of an enveloped message.

PFN_CMSG_IMPORT_MAIL_LIST

Imports a content encryption key for a key transport recipient of an enveloped message.

PFN_CRYPT_ENUM_KEYID_PROP

The CRYPT_ENUM_KEYID_PROP callback function is used with the CryptEnumKeyIdentifierProperties function.

PFN_CRYPT_ENUM_OID_FUNC

The CRYPT_ENUM_OID_FUNCTION callback function is used with the CryptEnumOIDFunction function.

PFN_CRYPT_ENUM_OID_INFO

The CRYPT_ENUM_OID_INFO callback function is used with the CryptEnumOIDInfo function.

PFN_CRYPT_EXPORT_PUBLIC_KEY_INFO_EX2_FUNC

Called by CryptExportPublicKeyInfoEx to export a public key BLOB and encode it.

PFN_CRYPT_EXTRACT_ENCODED_SIGNATURE_PARAMETERS_FUNC

Called to decode and return the hash algorithm identifier and optionally the signature parameters.

PFN_CRYPT_GET_SIGNER_CERTIFICATE

The CryptGetSignerCertificateCallback user supplied callback function is used with the CRYPT_VERIFY_MESSAGE_PARA
structure to get and verify a message signer's certificate.

PFN_CRYPT_OBJECT_LOCATOR_PROVIDER_FLUSH

Specifies that an object has changed.

PFN_CRYPT_OBJECT_LOCATOR_PROVIDER_FREE

Releases the object returned by the provider.

PFN_CRYPT_OBJECT_LOCATOR_PROVIDER_FREE_IDENTIFIER

Releases memory for an object identifier.

PFN_CRYPT_OBJECT_LOCATOR_PROVIDER_FREE_PASSWORD

Releases the password used to encrypt a personal information exchange (PFX) byte array.

PFN_CRYPT_OBJECT_LOCATOR_PROVIDER_GET

Retrieves an object.

PFN_CRYPT_OBJECT_LOCATOR_PROVIDER_INITIALIZE

Initializes the provider.

PFN_CRYPT_OBJECT_LOCATOR_PROVIDER_RELEASE

Releases the provider.

PFN_CRYPT_SIGN_AND_ENCODE_HASH_FUNC

Called to sign and encode a computed hash.

PFN_CRYPT_VERIFY_ENCODED_SIGNATURE_FUNC

Called to decrypt an encoded signature and compare it to a computed hash.

PFN_CRYPT_XML_CREATE_TRANSFORM

Creates a transform for a specified data provider.

PFN_CRYPT_XML_DATA_PROVIDER_CLOSE

Releases the data provider.

PFN_CRYPT_XML_DATA_PROVIDER_READ

Reads XML data.

PFN_CRYPT_XML_ENUM_ALG_INFO

Enumerates predefined and registered CRYPT_XML_ALGORITHM_INFO entries.

PFN_CRYPT_XML_WRITE_CALLBACK

Writes XML data.

PFN_IMPORT_PUBLIC_KEY_INFO_EX2_FUNC

Called by CryptImportPublicKeyInfoEx2 to decode the public key algorithm identifier, load the algorithm provider, and import
the key pair.
PFNCFILTERPROC

An application-defined callback function that filters the certificates that appear in the digital signature wizard that are
displayed by the CryptUIWizDigitalSign function.

PFNCMFILTERPROC

Filters each certificate to determine whether it will appear in the certificate selection dialog box that is displayed by the
CertSelectCertificate function.

PFNCMHOOKPROC

Called before messages are processed by the certificate selection dialog box produced by the CertSelectCertificate function.

PFNCryptStreamOutputCallback

Receives encrypted or decrypted data from tasks started by using the NCryptStreamOpenToProtect or
NCryptStreamOpenToUnprotect functions.

pfnIsFileSupported

Queries the subject interface packages (SIPs) listed in the registry to determine which SIP handles the file type.

pfnIsFileSupportedName

Queries the subject interface packages (SIPs) listed in the registry to determine which SIP handles the file type.

PFSCE_FREE_INFO

Frees the memory for buffers allocated by the Security Configuration tool set when it calls PFSCE_QUERY_INFO.

PFSCE_LOG_INFO

Logs messages to the configuration log file or analysis log file.

PFSCE_QUERY_INFO

Queries service-specific information from the Security Configuration file or analysis database.

PFSCE_SET_INFO

Sets or overwrites service-specific configuration and analysis information.

PFXExportCertStore

Exports the certificates and, if available, the associated private keys from the referenced certificate store.

PFXExportCertStoreEx

Exports the certificates and, if available, their associated private keys from the referenced certificate store.

PFXImportCertStore

Imports a PFX BLOB and returns the handle of a store that contains certificates and any associated private keys.
PFXIsPFXBlob

The PFXIsPFXBlob function attempts to decode the outer layer of a BLOB as a PFX packet.

PFXVerifyPassword

The PFXVerifyPassword function attempts to decode the outer layer of a BLOB as a Personal Information Exchange (PFX)
packet and to decrypt it with the given password. No data from the BLOB is imported.

Ping

Tests a DCOM connection with an Online Certificate Status Protocol (OCSP) responder service.

PostUnInstall

Is not implemented and is reserved for future use.

PostUnInstall

Is not implemented. It is reserved for future use.

PreUnInstall

Temporarily saves role-specific state information and then it uninstalls the role.

PreUnInstall

Removes registry and IIS settings for the Network Device Enrollment Service (NDES) role.

PrivilegeCheck

Determines whether a specified set of privileges are enabled in an access token.

PrivilegedServiceAuditAlarmA

Generates an audit message in the security event log.

PrivilegedServiceAuditAlarmW

Generates an audit message in the security event log.

ProcessResponseMessage

Process a response message and return the disposition of the message.

PropertySheetPageCallback

The PropertySheetPageCallback method notifies an EditSecurity or CreateSecurityPage caller that an access control editor
property page is being created or destroyed.

PSAM_INIT_NOTIFICATION_ROUTINE

The InitializeChangeNotify function is implemented by a password filter DLL. This function initializes the DLL.
PSAM_PASSWORD_FILTER_ROUTINE

Implemented by a password filter DLL. The value returned by this function determines whether the new password is accepted
by the system.

PSAM_PASSWORD_NOTIFICATION_ROUTINE

Is implemented by a password filter DLL. It notifies the DLL that a password was changed.

PstAcquirePrivateKey

Associates the caller's private key with the specified certificate.

PstGetCertificates

Retrieves certificate chains that specify certificates that can be used to authenticate a user on the specified server.

PstGetTrustAnchors

Retrieves a list of certification authorities (CAs) trusted by the specified server.

PstGetUserNameForCertificate

Retrieves the user name associated with the specified certificate.

PstMapCertificate

Retrieves a structure that specifies information that can be used to create a user token associated with the specified certificate.

PstValidate

Validates the specified certificate.

PublishCRL

Sends a request to the Certificate Services certification authority (CA) to publish a new certificate revocation list (CRL). This
method was first introduced in the ICertAdmin interface.

PublishCRLs

Publishes certificate revocation lists (CRLs) for a certification authority (CA).

put_Algorithm

Specifies or retrieves an object identifier (OID) for the public key algorithm.

put_AlternateSignatureAlgorithm

Specifies and retrieves a Boolean value that indicates whether the signature algorithm object identifier (OID) for a PKCS

put_AlternateSignatureAlgorithm

Specifies and retrieves a Boolean value that specifies whether the GetSignatureAlgorithm method should retrieve a discrete or
combined algorithm object identifier (OID) for a PKCS
put_ApplicationData

Sets or retrieves an opaque field that can be used by the application to store information.

put_ApplicationData

Sets or retrieves an opaque field that can be used by the application to store information.

put_ApplicationData

The ApplicationData property of IAzOperation sets or retrieves an opaque field that can be used by the application to store
information.

put_ApplicationData

The ApplicationData property of IAzRole sets or retrieves an opaque field that can be used by the application to store
information.

put_ApplicationData

The ApplicationData property of IAzScope sets or retrieves an opaque field that can be used by the application to store
information.

put_ApplicationData

The ApplicationData property of IAzTask sets or retrieves an opaque field that can be used by the application to store
information.

put_ApplyStoreSacl

Sets or retrieves a value that indicates whether policy audits should be generated when the authorization store is modified.

put_ApplyStoreSacl

Sets or retrieves a value that indicates whether policy audits should be generated when the authorization store is modified.

put_ArchivePrivateKey

Specifies or retrieves a Boolean value that indicates whether to archive a private key on the certification authority (CA).

put_AttestationEncryptionCertificate

The certificate used to encrypt the EKPUB and EKCERT values from the client. This property must be set to a valid certificate
that chains to a trusted machine root.

put_AttestPrivateKey

True if the created private key needs to be attested; otherwise false. If true, it is expected that the
AttestationEncryptionCertificate property has been set.

put_AuthFlags

Specifies and retrieves a value that indicates the authentication type used by the client to authenticate itself to the certificate
enrollment policy (CEP) server.
put_AuthzInterfaceClsid

Sets or retrieves the class identifier (CLSID) of the interface that the user interface (UI) uses to perform application-specific
operations.

put_BizRule

Gets or sets the script that determines membership for this application group.

put_BizRule

Sets or retrieves the text of the script that implements the business rule (BizRule).

put_BizRuleImportedPath

Gets or sets the path of the file that contains the business rule script associated with this application group.

put_BizRuleImportedPath

Sets or retrieves the path to the file from which the business rule (BizRule) is imported.

put_BizRuleLanguage

Gets or sets the programming language of the business rule script associated with this application group.

put_BizRuleLanguage

Sets or retrieves the scripting language in which the business rule (BizRule) is implemented.

put_BizRulesEnabled

Gets or sets a value that indicates whether business rules are enabled for this application.

put_BusinessRuleResult

Sets a value that indicates whether the Business Rule (BizRule) allows the user to perform the requested task.

put_BusinessRuleString

Sets or retrieves an application-specific string for the Business Rule (BizRule).

put_CAConfig

Gets or sets a certification authority (CA) name with which a signing certificate must be signed.

put_CAStoreFlags

Sets or retrieves a flag that controls the certification authority (CA) store when the store is opened.

put_CAStoreFlags

The CAStoreFlags property of IEnroll4 sets or retrieves a flag that controls the certification authority (CA) store when the store
is opened.
put_CAStoreName

Sets or retrieves the name of the store where all non-"ROOT" and non-"MY" certificates are kept.

put_CAStoreNameWStr

The CAStoreNameWStr property of IEnroll4 sets or retrieves the name of the store where all non-"ROOT" and non-"MY"
certificates are kept.

put_CAStoreType

Sets or retrieves the type of store to use for the store specified by the CAStoreName property.

put_CAStoreTypeWStr

Sets or retrieves the type of store to use for the store specified by the CAStoreNameWStr property.

put_Certificate

Specifies or retrieves a byte array that contains the certificate associated with the private key.

put_CertificateDescription

Specifies or retrieves a string that contains a description of the certificate.

put_CertificateFriendlyName

Specifies or retrieves the display name of a certificate.

put_CertificateFriendlyName

Gets or sets the friendly name for the certificate.

put_ChallengePassword

The password to use when creating a request with a challenge. To create a request without a challenge, do not set the
ChallengePassword property.

put_ClientId

Specifies and retrieves a value that identifies the executable that created the request.

put_ClientId

Sets or retrieves a client ID request attribute. The client ID request attribute indicates the source of the certificate request. This
property was first defined in the ICEnroll4 interface.

put_ClientId

The ClientId property sets or retrieves a client ID request attribute. The client ID request attribute indicates the source of the
certificate request. This property was first defined in the IEnroll4 interface.

put_ContainerName

Specifies or retrieves the name of the key container.

put_ContainerName

Gets or sets the name used by the cryptographic service provider (CSP) to generate, store, or access the key.

put_ContainerName

The ContainerName property of ICEnroll4 sets or retrieves the name of the key container to use.

put_ContainerNamePrefix

Specifies or retrieves a prefix added to the name of the key container.

put_ContainerNameWStr

Sets or retrieves the name of the key container to use.

put_Cost

Specifies and retrieves an arbitrary cost for contacting the certificate enrollment policy server.

put_Cost

Specifies and retrieves an arbitrary cost for contacting the certificate enrollment policy server.

put_Critical

Specifies and retrieves a Boolean value that identifies whether the certificate extension is critical.

put_CspInformations

Specifies and retrieves a collection of cryptographic providers available for use by the request object.

put_CspInformations

Specifies or retrieves a collection of ICspInformation objects that contain information about the available cryptographic
providers that support the public key algorithm associated with the private key.

put_CspStatus

Specifies or retrieves an ICspStatus object that contains information about the cryptographic provider and algorithm pair
associated with the private key.

put_Default

Specifies and retrieves a Boolean value that indicates whether this is the default certificate enrollment policy (CEP) server.

put_DeleteRequestCert

Sets or retrieves a Boolean value that determines whether dummy certificates in the request store are deleted.

put_DeleteRequestCert

The DeleteRequestCert property of IEnroll4 sets or retrieves a Boolean value that determines whether dummy certificates in
the request store are deleted.
put_Description

Sets or retrieves a comment that describes the application.

put_Description

Sets or retrieves a comment that describes the application group.

put_Description

Sets or retrieves a comment that describes the operation.

put_Description

The Description property of IAzOperation sets or retrieves a comment that describes the operation.

put_Description

Sets or retrieves a comment that describes the role.

put_Description

Sets or retrieves a comment that describes the scope.

put_Description

Sets or retrieves a comment that describes the task.

put_Description

Specifies or retrieves a string that contains a description of the private key.

put_Display

Specifies or retrieves a value that indicates whether to display the status information in a user interface.

put_DomainTimeout

Sets or retrieves the time in milliseconds after which a domain is determined to be unreachable.

put_EnableSMIMECapabilities

The ICEnroll4::EnableSMIMECapabilities property controls whether the PKCS

put_EnableSMIMECapabilities

Controls whether the PKCS

put_EnableT61DNEncoding

The EnableT61DNEncoding property of ICEnroll4 sets or retrieves a Boolean value that determines whether the distinguished
name in the request is encoded as a T61 string instead of as a Unicode string.
put_EnableT61DNEncoding

Sets or retrieves a Boolean value that determines whether the distinguished name in the request is encoded as a T61 string
instead of as a Unicode string.

put_EncryptionAlgorithm

Specifies or retrieves an object identifier (OID) of the algorithm used to encrypt the private key to be archived.

put_EncryptionAlgorithm

The encryption algorithm used to encrypt the EKPUB and EKCERT values from the client.

put_EncryptionStrength

Specifies or retrieves the relative encryption level applied to the private key to be archived.

put_EncryptionStrength

Identifies the bit length for the EncryptionAlgorithm to use for encryption. If the EncryptionAlgorithm only supports one bit
length, then you do not need to specify a value for the EncryptionStrength property.

put_Error

Specifies and retrieves a value that identifies the error status of the certificate enrollment process.

put_Existing

Specifies or retrieves a Boolean value that indicates whether the private key has been created or imported.

put_Existing

Gets or sets a value that indicates whether the private key already exists.

put_ExistingCACertificate

Gets or sets the binary value that has been encoded by using Distinguished Encoding Rules (DER) and that is the binary value
of the certification authority (CA) certificate that corresponds to an existing key.

put_ExportPolicy

Specifies or retrieves export constraints for a private key.

put_Flags

Specifies or retrieves a value that indicates whether the certificate enrollment policy (CEP) server policy information can be
loaded from group policy, from the registry, or both.

put_FriendlyName

Specifies and retrieves a display name for the object identifier.

put_FriendlyName

Specifies or retrieves a display name for the private key.

put_GenerateAudits

The GenerateAudits property of IAzApplication sets or retrieves a value that indicates whether run-time audits should be
generated.

put_GenerateAudits

Sets or retrieves a value that indicates whether run-time audits should be generated.

put_GenKeyFlags

Sets or retrieves the values passed to the CryptGenKey function when the certificate request is generated.

put_GenKeyFlags

Sets or retrieves the values passed to CryptGenKey when the certificate request is generated.

put_HashAlgID

Sets or retrieves the hash algorithm used when signing a PKCS

put_HashAlgID

The HashAlgID property of IEnroll4 sets or retrieves the hash algorithm used when signing a PKCS

put_HashAlgorithm

Specifies and retrieves the object identifier (OID) of the hash algorithm used to sign the certificate request.

put_HashAlgorithm

Specifies and retrieves an object identifier (OID) for the hashing algorithm used in the GetSignatureAlgorithm method.

put_HashAlgorithm

Gets or sets the name of the hashing algorithm used to sign or verify the certification authority (CA) certificate for the key.

put_HashAlgorithm

Sets or retrieves only the signature hashing algorithm used to sign the PKCS

put_HashAlgorithm

Gets or sets an identifier for the hash algorithm used to sign a certificate.

put_HashAlgorithmWStr

Sets or retrieves only the signature hashing algorithm used to sign the PKCS

put_IncludeSubjectKeyID

Determines whether the subject key ID extension is added to the certificate request that is generated.
put_IncludeSubjectKeyID

The IncludeSubjectKeyID property of IEnroll4 determines whether the subject key ID extension is added to the certificate
request that is generated.

put_IsRoleDefinition

Sets or retrieves a value that indicates whether the task is a role definition.

put_Issuer

Specifies or retrieves the name of the certificate issuer.

put_KeyArchivalCertificate

Specifies or retrieves a certification authority (CA) encryption certificate.

put_KeyContainerNamePrefix

Specifies or retrieves a prefix used to create the container name for a new private key.

put_KeyProtection

Specifies or retrieves a value that indicates how a private key is protected before use.

put_KeySpec

Specifies or retrieves a value that identifies whether a private key can be used for signing, or encryption, or both.

put_KeySpec

The KeySpec property of ICEnroll4 sets or retrieves the type of key generated.

put_KeySpec

Sets or retrieves the type of key generated.

put_KeyUsage

Specifies or retrieves a value that identifies the specific purpose for which a private key can be used.

put_LdapQuery

Sets or retrieves the Lightweight Directory Access Protocol (LDAP) query used to define membership for an LDAP query
application group.

put_LDAPQueryDN

Retrieves or sets the domain name of the directory object to be used during evaluation of LDAP query groups.

put_LegacyCsp

Specifies or retrieves a Boolean value that indicates whether the provider is a CryptoAPI (legacy) cryptographic service
provider (CSP).
put_Length

Specifies or retrieves the length, in bits, of the private key.

put_Length

Gets or sets the strength of the key to one of the values supported by the cryptographic service provider (CSP).

put_LimitExchangeKeyToEncipherment

Sets or retrieves a Boolean value that determines whether an AT_KEYEXCHANGE request contains digital signature and
nonrepudiation key usages.

put_LimitExchangeKeyToEncipherment

The LimitExchangeKeyToEncipherment property of IEnroll4 sets or retrieves a Boolean value that determines whether an
AT_KEYEXCHANGE request contains digital signature and nonrepudiation key usages.

put_LocalRevocationInformation

Gets or sets the certificate revocation list (CRL) of the local machine.

put_MachineContext

Specifies or retrieves a Boolean value that identifies the local certificate store context.

put_MaxScriptEngines

Sets or retrieves the maximum number of Business Rule (BizRule) script engines that will be cached.

put_MyStoreFlags

Sets or retrieves the registry location used for MY store.

put_MyStoreFlags

Sets or retrieves the registry location used for the MY store.

put_MyStoreName

Sets or retrieves the name of the store where certificates with linked private keys are kept.

put_MyStoreNameWStr

The MyStoreNameWStr property of IEnroll4 sets or retrieves the name of the store where certificates with linked private keys
are kept.

put_MyStoreType

Sets or retrieves the type of store specified by the MyStoreName property.

put_MyStoreTypeWStr

Sets or retrieves the type of store specified by the MyStoreTypeWStr property.

put_Name

Sets or retrieves the name of the application.

put_Name

Sets or retrieves the name of the application group.

put_Name

Sets or retrieves the name of the operation.

put_Name

Sets or retrieves the name of the role.

put_Name

Sets or retrieves the name of the scope.

put_Name

Sets or retrieves the name of the task.

put_NotAfter

Specifies or retrieves the date and time after which the certificate is no longer valid.

put_NotBefore

Specifies or retrieves the date and time before which the certificate is not valid.

put_NullSigned

Specifies and retrieves a Boolean value that indicates whether the certificate request is null-signed.

put_OldCertificate

Gets or sets an old certificate that a request is intended to replace.

put_OperationID

Sets or retrieves an application-specific value that uniquely identifies the operation within the application.

put_Ordinal

Specifies or retrieves the position of the ICspStatus object in the ICspStatuses collection.

put_Parameters

Retrieves a byte array that contains the parameters associated with the signature algorithm.

put_ParentWindow

Specifies or retrieves the ID of the window used to display signing certificate information.
put_ParentWindow

Specifies and retrieves the ID of the window used by key-related user interface dialogs.

put_ParentWindow

Specifies or retrieves the ID of the window used to display the enrollment information.

put_ParentWindow

Specifies or retrieves the ID of the window used to display key information.

put_Pin

Specifies a personal identification number (PIN) used to authenticate a smart card user.

put_Pin

Specifies a personal identification number (PIN) that is used to authenticate users prior to accessing a private key container on
a smart card.

put_PrivateKeyArchiveCertificate

Sets or retrieves the certificate that is used to archive a private key with a PKCS

put_Property

Specifies or retrieves a property value for the IX509CertificateTemplateWritable object.

put_PropertyId

Specifies or retrieves a value of the CERTENROLL_PROPERTYID enumeration that identifies an external certificate property.

put_ProviderCLSID

Gets or sets the CLSID of the revocation information provider used by the CA configuration.

put_ProviderFlags

Sets or retrieves the provider type.

put_ProviderFlags

The ProviderFlags property of IEnroll4 sets or retrieves the provider type.

put_ProviderName

The name of the encryption provider. The default is the Microsoft Platform Crypto Provider. You must set the ProviderName
property before you call the Open method. You cannot change the ProviderName property after you have called the Open
method.

put_ProviderName

Specifies or retrieves the name of the cryptographic provider.

put_ProviderName

Gets or sets the name of the cryptographic service provider (CSP) or key storage provider (KSP) that is used to generate or
store the private key.

put_ProviderName

The ProviderName property of ICEnroll4 sets or retrieves the name of the cryptographic service provider (CSP) to use.

put_ProviderNameWStr

Sets or retrieves the name of the cryptographic service provider (CSP) to use.

put_ProviderProperties

Gets or sets information that provides certificate status responses.

put_ProviderType

Specifies or retrieves the type of cryptographic provider associated with the private key.

put_ProviderType

The ProviderType property of ICEnroll4 sets or retrieves the type of provider.

put_ProviderType

Sets or retrieves the type of provider.

put_PublicKeyAlgorithm

Specifies and retrieves an object identifier (OID) for the public key algorithm used in the GetSignatureAlgorithm method.

put_PVKFileName

The PVKFileName property of ICEnroll4 sets or retrieves the name of the file that will contain exported keys.

put_PVKFileNameWStr

Sets or retrieves the name of the file that will contain exported keys.

put_ReaderName

Specifies or retrieves the name of a smart card reader.

put_ReminderDuration

Gets or sets the percentage of a signing certificate lifetime after which a warning event is logged.

put_RenewalCertificate

Specifies or retrieves a byte array that contains the Distinguished Encoding Rules (DER) encoded certificate that is being
renewed.
put_RenewalCertificate

Specifies the certificate context for the renewal certificate.

put_RequesterName

Specifies or retrieves a string that contains the Security Account Manager (SAM) name of the end-entity requesting the
certificate.

put_RequestStoreFlags

Sets or retrieves the registry location used for the request store.

put_RequestStoreFlags

The RequestStoreFlags property of IEnroll4 sets or retrieves the registry location used for the request store.

put_RequestStoreName

Sets or retrievesICEnroll the name of the store that contains the dummy certificate.

put_RequestStoreNameWStr

The RequestStoreNameWStr property of IEnroll4 sets or retrieves the name of the store that contains the dummy certificate.

put_RequestStoreType

Sets or retrieves the type of store to use for the store specified by the RequestStoreName property. This store type is passed
directly to the CertOpenStore function.

put_RequestStoreTypeWStr

Sets or retrieves the type of store to use for the store specified by the RequestStoreNameWStr property. This store type is
passed directly to the CertOpenStore function.

put_ReuseHardwareKeyIfUnableToGenNew

Sets or retrieves a Boolean value that determines the action taken by the certificate enrollment control object if an error is
encountered when generating a new key.

put_ReuseHardwareKeyIfUnableToGenNew

The ReuseHardwareKeyIfUnableToGenNew property of IEnroll4 sets or retrieves a Boolean value that determines the action
taken by the certificate enrollment control object if an error is encountered when generating a new key.

put_RoleForAccessCheck

Sets or retrieves the role that is used to perform the access check.

put_RootStoreFlags

The RootStoreFlags property of ICEnroll4 sets or retrieves the registry location used for the root store.

put_RootStoreFlags

Sets or retrieves the registry location used for the root store.
put_RootStoreName

Sets or retrieves the name of the root store where all intrinsically trusted, self-signed root certificates are kept.

put_RootStoreNameWStr

The RootStoreNameWStr property of IEnroll4 sets or retrieves the name of the root store where all intrinsically trusted, self-
signed root certificates are kept.

put_RootStoreType

Sets or retrieves the type of store to use for the store specified by the RootStoreName property.

put_RootStoreTypeWStr

Sets or retrieves the type of store to use for the store specified by the RootStoreNameWStr property.

put_ScriptEngineTimeout

Sets or retrieves the time in milliseconds that the IAzClientContext::AccessCheck method will wait for a Business Rule (BizRule)
to complete execution before canceling it.

put_SecurityDescriptor

Specifies or retrieves the security descriptor for the private key.

put_Selected

Specifies or retrieves a value that indicates whether an item can be used during the enrollment process.

put_SenderNonce

Specifies or retrieves a byte array that contains a nonce.

put_SerialNumber

Specifies and retrieves the certificate serial number.

put_ServerCapabilities

Sets the preferred hash and encryption algorithms for the request.

put_SignerCertificate

Specifies or retrieves the ISignerCertificate object used to sign the certificate.

put_SignerCertificate

Specifies or retrieves a certificate used to sign the certificate request.

put_SignerCertificate

Gets or sets the signer certificate for the request.

put_SignerCertificate

Sets the signer's certificate.

put_SigningCertificate

Gets or sets a signing certificate that has been encoded by using Distinguished Encoding Rules (DER). An Online Certificate
Status Protocol (OCSP) responder service uses this certificate to sign its responses to certificate status requests.

put_SigningCertificateTemplate

Gets or sets the template name for a signing certificate.

put_SigningFlags

Gets or sets a combination of flag values. These values specify the management of signing certificates that belong to a
certification authority (CA) configuration.

put_Silent

Specifies or retrieves a Boolean value that indicates whether the user is notified when the private key is used to sign a
certificate request.

put_Silent

Specifies or retrieves a Boolean value that indicates whether any of the key-related modal dialogs are displayed during the
certificate enrollment process.

put_Silent

Specifies or retrieves a Boolean value that indicates whether a user interface is displayed during the certificate enrollment
process.

put_Silent

Specifies or retrieves a Boolean value that indicates whether the Certificate Enrollment Control is allowed to display a dialog
box when the private key is accessed.

put_Silent

Gets or sets whether to allow UI during the request.

put_SmimeCapabilities

Specifies or retrieves a Boolean value that tells the Encode method whether to create an IX509ExtensionSmimeCapabilities
collection that identifies the encryption capabilities supported by the computer.

put_SPCFileName

Sets or retrieves the name of the file to which to write the base64-encoded PKCS

put_SPCFileNameWStr

The SPCFileNameWStr property of IEnroll4 sets or retrieves the name of the file to which to write the base64-encoded PKCS
put_Status

Specifies or retrieves a value that indicates the status of the enrollment process.

put_Subject

Specifies or retrieves the X.500 distinguished name of the entity requesting the certificate.

put_SuppressDefaults

Specifies or retrieves a Boolean value that indicates whether the default extensions and attributes are included in the request.

put_Text

Specifies or retrieves a string that contains a message associated with the status of the enrollment process.

put_ThumbPrint

Sets or retrieves a hash of the certificate data.

put_ThumbPrintWStr

Sets or retrieves a hash of the certificate data. The thumbprint is used to point to the pending certificate.

put_TransactionId

Specifies or retrieves a transaction identifier that can be used to track a certificate request or response.

put_TransactionId

Gets or sets the transaction id for the request.

put_Type

Sets or retrieves the group type of the application group.

put_UIContextMessage

Specifies or retrieves a string that contains user interface text associated with the signing certificate.

put_UIContextMessage

Specifies or retrieves a context string to display in the user interface.

put_UIContextMessage

Specifies or retrieves a string that contains user interface text associated with the private key.

put_Url

Specifies or retrieves the URL for the certificate enrollment policy (CEP) server.

put_UseExistingKeySet

Sets or retrieves a Boolean value that determines whether the existing keys should be used.
put_UseExistingKeySet

The UseExistingKeySet property of IEnroll4 sets or retrieves a Boolean value that determines whether the existing keys should
be used.

put_Value

Gets or sets the data part of the name-value pair represented by an OCSPProperty object.

put_Version

Sets or retrieves the version of the application.

put_WriteCertToCSP

The WriteCertToCSP property of ICEnroll4 sets or retrieves a Boolean value that determines whether a certificate should be
written to the cryptographic service provider (CSP).

put_WriteCertToCSP

Sets or retrieves a Boolean value that determines whether a certificate should be written to the cryptographic service provider
(CSP).

put_WriteCertToUserDS

Sets or retrieves a Boolean value that determines whether the certificate is written to the user's Active Directory store.

put_WriteCertToUserDS

The WriteCertToUserDS property of IEnroll4 sets or retrieves a Boolean value that determines whether the certificate is written
to the user's Active Directory store.

PWLX_ASSIGN_SHELL_PROTECTION

Called by GINA to assign protection to the shell program of a newly logged-on user.

PWLX_CHANGE_PASSWORD_NOTIFY

Called by GINA to indicate it has changed a password.

PWLX_CHANGE_PASSWORD_NOTIFY_EX

Called by GINA to tell a specific network provider (or all network providers) that a password has changed.

PWLX_CLOSE_USER_DESKTOP

Called by GINA to close an alternate user desktop and clean up after the desktop is closed.

PWLX_CREATE_USER_DESKTOP

Called by GINA to create alternate application desktops for the user.

PWLX_DIALOG_BOX

Called by the GINA to create a modal dialog box from a dialog box template.
PWLX_DIALOG_BOX_INDIRECT

Called by GINA to create a modal dialog box from a dialog box template in memory.

PWLX_DIALOG_BOX_INDIRECT_PARAM

Called by GINA to initialize dialog box controls and then create a modal dialog box from a dialog box template in memory.

PWLX_DIALOG_BOX_PARAM

Called by GINA to initialize dialog box controls and then create a modal dialog box from a dialog box template resource.

PWLX_DISCONNECT

Called by a replacement GINA DLL if Terminal Services is enabled. GINA calls this function to disconnect from a Terminal
Services network session.

PWLX_GET_OPTION

Called by GINA to retrieve the current value of an option.

PWLX_GET_SOURCE_DESKTOP

Called by GINA to determine the name and handle of the desktop that was current before Winlogon switched to the
Winlogon desktop.

PWLX_MESSAGE_BOX

Called by GINA to create, display, and operate a message box.

PWLX_QUERY_CLIENT_CREDENTIALS

Called by a replacement GINA DLL if Terminal Services is enabled. GINA calls this function to retrieve the credentials of remote
Terminal Services clients that are not using an Internet connector license.

PWLX_QUERY_CONSOLESWITCH_CREDENTIALS

Called by GINA to read the credentials transferred from the Winlogon of the temporary session to the Winlogon of the
destination session.

PWLX_QUERY_IC_CREDENTIALS

Called by a replacement GINA DLL if Terminal Services is enabled. GINA calls this function to determine whether the terminal
server is using Internet connector licensing and to retrieve credentials information.

PWLX_QUERY_TERMINAL_SERVICES_DATA

Called by GINA to retrieve Terminal Services user configuration information after a user has logged on.

PWLX_QUERY_TS_LOGON_CREDENTIALS

Called by a replacement GINA DLL to retrieve credentials information if Terminal Services is enabled. The GINA DLL can then
use this information to fill in a logon box automatically and attempt to log the user in.
PWLX_SAS_NOTIFY

Called by GINA to notify Winlogon of a secure attention sequence (SAS) event.

PWLX_SET_CONTEXT_POINTER

Called by GINA to specify the context pointer passed by Winlogon as the first parameter to all future calls to GINA functions.

PWLX_SET_OPTION

Called by GINA to set the value of an option.

PWLX_SET_RETURN_DESKTOP

Called by GINA to specify the alternate application desktop that Winlogon will switch to when the current secure attention
sequence (SAS) event processing function is complete.

PWLX_SET_TIMEOUT

Called by GINA to change the time-out associated with a dialog box. The default time-out is two minutes.

PWLX_SWITCH_DESKTOP_TO_USER

Called by GINA to switch to the application desktop.

PWLX_SWITCH_DESKTOP_TO_WINLOGON

Allows the GINA DLL switch to the Winlogon desktop.

PWLX_USE_CTRL_ALT_DEL

Called by GINA to tell Winlogon to use the standard CTRL+ALT+DEL key combination as a secure attention sequence (SAS).

PWLX_WIN31_MIGRATE

Called by a replacement GINA DLL if Terminal Services is enabled. GINA calls this function to complete the setup of the
Terminal Services client.

QueryChanges

Retrieves a value that specifies whether the template or certification authority collections have changed in Active Directory.

QueryContextAttributesA

Lets a transport application query the Credential Security Support Provider (CredSSP) security package for certain attributes
of a security context.

QueryContextAttributesExA

Enables a transport application to query a security package for certain attributes of a security context.

QueryContextAttributesExW

Enables a transport application to query a security package for certain attributes of a security context.
QueryContextAttributesW

Lets a transport application query the Credential Security Support Provider (CredSSP) security package for certain attributes
of a security context.

QueryCredentialsAttributesA

Retrieves the attributes of a credential, such as the name associated with the credential.

QueryCredentialsAttributesW

Retrieves the attributes of a credential, such as the name associated with the credential.

QuerySecurityAccessMask

Creates an access mask that represents the access permissions necessary to query the specified object security information.

QuerySecurityContextToken

Obtains the access token for a client security context and uses it directly.

QuerySecurityPackageInfoA

Retrieves information about a specified security package. This information includes the bounds on sizes of authentication
information, credentials, and contexts.

QuerySecurityPackageInfoW

Retrieves information about a specified security package. This information includes the bounds on sizes of authentication
information, credentials, and contexts.

QueryServiceConfig2A

Retrieves the optional configuration parameters of the specified service.

QueryServiceConfig2W

Retrieves the optional configuration parameters of the specified service.

QueryServiceConfigA

Retrieves the configuration parameters of the specified service.

QueryServiceConfigW

Retrieves the configuration parameters of the specified service.

QueryServiceDynamicInformation

Retrieves dynamic information related to the current service start.

QueryServiceLockStatusA

Retrieves the lock status of the specified service control manager database.
QueryServiceLockStatusW

Retrieves the lock status of the specified service control manager database.

QueryServiceObjectSecurity

Retrieves a copy of the security descriptor associated with a service object.

QueryServiceStatus

Retrieves the current status of the specified service.

QueryServiceStatusEx

Retrieves the current status of the specified service based on the specified information level.

RegGetKeySecurity

Retrieves a copy of the security descriptor protecting the specified open registry key.

RegisterServiceCtrlHandlerA

Registers a function to handle service control requests.

RegisterServiceCtrlHandlerExA

Registers a function to handle extended service control requests.

RegisterServiceCtrlHandlerExW

Registers a function to handle extended service control requests.

RegisterServiceCtrlHandlerW

Registers a function to handle service control requests.

RegSetKeySecurity

Sets the security of an open registry key.

Remove

Removes the specified interface from the list of interfaces The number of interfaces in the list of interfaces that can be called by
BizRule scripts.

Remove

Removes the specified parameter from the list of parameters available to business rule (BizRule) scripts.

Remove

Removes an object from the collection by index number.

Remove

Removes an object from the collection by index number.

Remove

Removes an ICertificationAuthority object from the collection by index number.

Remove

Removes a property from the collection by index value.

Remove

Removes an ICryptAttribute object from the collection by index number.

Remove

Removes an ICspAlgorithm object from the collection by index number.

Remove

Removes an ICspInformation object from the collection by index number.

Remove

Removes an ICspStatus object from the collection by index number.

Remove

Removes an IObjectId object from the collection by index value.

Remove

Removes an object from the collection by index value.

Remove

Removes an ISignerCertificate object from the collection by index number.

Remove

Removes an object from the collection by index value.

Remove

Removes an IX509Attribute object from the collection by index number.

Remove

Removes an IX509CertificateTemplate object from the collection by index number.

Remove

Removes an IX509Extension object from the collection by index number.

Remove

Removes an IX509NameValuePair object from the collection by index number.

Remove

Removes an IX509PolicyServerUrl object from the collection by index number.

RemoveAll

Removes all interfaces from the list of interfaces that can be called by business rule (BizRule) scripts.

RemoveAll

Removes all parameters from the list of parameters available to business rule (BizRule) scripts.

RemoveCertificate

Removes an endorsement certificate related to the endorsement key from the key storage provider. You can only call the
RemoveCertificate method after the Open method has been successfully called.

RemoveFromCertificate

Disassociates a property from a certificate.

RemoveFromRegistry

Unregisters a certificate enrollment policy (CEP) server.

removePendingRequest

Removes a pending request from the client's request store. This method was first defined in the ICEnroll4 interface.

removePendingRequestWStr

Removes a pending request from the client's request store.

ReportError

Reports any errors from the requested operation.

ReportProgress

Reports the progress of the current operation.

Reset

Sets the current index of the identity enumeration to zero.

Reset

Resets the configuration query state to point at the Certificate Services server configuration indexed on the specified
configuration point. This method was first defined in the ICertConfig interface.
Reset

Returns the certificate enrollment control object to its initial state and thereby allow reuse of the control. This method was first
defined in the ICEnroll3 interface.

Reset

Returns the certificate enrollment control object to its initial state and thereby allows reuse of the control.

Reset

Specifies the size of the alternate name array in this object. The value of all elements in the array are set to zero.

Reset

Resets a certificate revocation list (CRL) distribution information array to a specified number of distribution point structures.

Reset

Specifies the size of DATE array in this object.

Reset

Specifies the size of the array in this object.

Reset

Specifies the size of the string array and the type of strings the array will contain.

Reset

Moves to the beginning of the attribute-enumeration sequence.

Reset

Moves to the beginning of the column-enumeration sequence.

Reset

Moves to the beginning of the extension-enumeration sequence.

Reset

Moves to the beginning of the row-enumeration sequence.

resetAttributes

Removes all attributes from the request. This method was first defined in the ICEnroll4 interface.

resetAttributes

Removes all attributes from the request.

resetBlobProperties

Resets the properties of a BLOB.

resetExtensions

Removes all extensions from the request. This method was first defined in the ICEnroll4 interface.

resetExtensions

Removes all extensions from the request.

ResetForEncode

Restores the state of the request object to that which existed before the Encode method was called.

ResubmitRequest

Submits the specified certificate request to the policy module for the specified certification authority. This method was first
introduced in the ICertAdmin interface.

RetrievePending

Retrieves a certificate's disposition status from an earlier request that may have previously returned CR_DISP_INCOMPLETE or
CR_DISP_UNDER_SUBMISSION.

RevertSecurityContext

Allows a security package to discontinue the impersonation of the caller and restore its own security context.

RevertToSelf

Terminates the impersonation of a client application.

RevokeCertificate

Revokes a certificate either on a specified date or immediately. This method was first defined in the ICertAdmin interface.

RoleAssignments

Gets a collection of IAzRoleAssignment objects associated with this application group.

RoleAssignments

Returns a collection of the role assignments associated with this operation.

RoleAssignments

Retrieves a collection of IAzRoleAssignment objects that represent the role assignments associated with this IAzRoleDefinition
object.

RoleAssignments

Returns a collection of the role assignments associated with this task.

RtlConvertSidToUnicodeString

Converts a security identifier (SID) to its Unicode character representation.

RtlDecryptMemory

Decrypts memory contents previously encrypted by the RtlEncryptMemory function.

RtlEncryptMemory

Encrypts memory contents.

RtlGenRandom

Generates a pseudo-random number.

SaferCloseLevel

Closes a SAFER_LEVEL_HANDLE that was opened by using the SaferIdentifyLevel function or the SaferCreateLevel function.

SaferComputeTokenFromLevel

Restricts a token using restrictions specified by a SAFER_LEVEL_HANDLE.

SaferCreateLevel

Opens a SAFER_LEVEL_HANDLE.

SaferGetLevelInformation

Retrieves information about a policy level.

SaferGetPolicyInformation

Gets information about a policy.

SaferIdentifyLevel

Retrieves information about a level.

SaferiIsExecutableFileType

Determines whether a specified file is an executable file.

SaferRecordEventLogEntry

Saves messages to an event log.

SaferSetLevelInformation

Sets the information about a policy level.

SaferSetPolicyInformation

Sets the global policy controls.

SaslAcceptSecurityContext

Wraps a standard call to the Security Support Provider Interface AcceptSecurityContext (General) function and includes
creation of SASL server cookies.

SaslEnumerateProfilesA

Lists the packages that provide a SASL interface.

SaslEnumerateProfilesW

Lists the packages that provide a SASL interface.

SaslGetContextOption

Retrieves the specified property of the specified SASL context.

SaslGetProfilePackageA

Returns the package information for the specified package.

SaslGetProfilePackageW

Returns the package information for the specified package.

SaslIdentifyPackageA

Returns the negotiate prefix that matches the specified SASL negotiation buffer.

SaslIdentifyPackageW

Returns the negotiate prefix that matches the specified SASL negotiation buffer.

SaslInitializeSecurityContextA

Wraps a standard call to the Security Support Provider Interface InitializeSecurityContext (General) function and processes
SASL server cookies from the server.

SaslInitializeSecurityContextW

Wraps a standard call to the Security Support Provider Interface InitializeSecurityContext (General) function and processes
SASL server cookies from the server.

SaslSetContextOption

Sets the value of the specified property for the specified SASL context.

Save

The Save method causes the snap-in extension to return information about the data that needs to be saved. The caller is
responsible for saving the data.

SCardAccessStartedEvent

Returns an event handle when an event signals that the smart card resource manager is started.
SCardAddReaderToGroupA

Adds a reader to a reader group.

SCardAddReaderToGroupW

Adds a reader to a reader group.

SCardAudit

Writes event messages to the Windows application log Microsoft-Windows-SmartCard-Audit/Authentication.

SCardBeginTransaction

Starts a transaction.

SCardCancel

Terminates all outstanding actions within a specific resource manager context.

SCardConnectA

Establishes a connection (using a specific resource manager context) between the calling application and a smart card
contained by a specific reader. If no card exists in the specified reader, an error is returned.

SCardConnectW

Establishes a connection (using a specific resource manager context) between the calling application and a smart card
contained by a specific reader. If no card exists in the specified reader, an error is returned.

SCardControl

Gives you direct control of the reader. You can call it any time after a successful call to SCardConnect and before a successful
call to SCardDisconnect.

SCardDisconnect

Terminates a connection previously opened between the calling application and a smart card in the target reader.

SCardEndTransaction

Completes a previously declared transaction, allowing other applications to resume interactions with the card.

SCardEstablishContext

Establishes the resource manager context (the scope) within which database operations are performed.

SCardForgetCardTypeA

Removes an introduced smart card from the smart card subsystem.

SCardForgetCardTypeW

Removes an introduced smart card from the smart card subsystem.

SCardForgetReaderA

Removes a previously introduced reader from control by the smart card subsystem. It is removed from the smart card
database, including from any reader group that it may have been added to.

SCardForgetReaderGroupA

Removes a previously introduced smart card reader group from the smart card subsystem. Although this function
automatically clears all readers from the group, it does not affect the existence of the individual readers in the database.

SCardForgetReaderGroupW

Removes a previously introduced smart card reader group from the smart card subsystem. Although this function
automatically clears all readers from the group, it does not affect the existence of the individual readers in the database.

SCardForgetReaderW

Removes a previously introduced reader from control by the smart card subsystem. It is removed from the smart card
database, including from any reader group that it may have been added to.

SCardFreeMemory

Releases memory that has been returned from the resource manager using the SCARD_AUTOALLOCATE length designator.

SCardGetAttrib

Retrieves the current reader attributes for the given handle. It does not affect the state of the reader, driver, or card.

SCardGetCardTypeProviderNameA

Returns the name of the module (dynamic link library) that contains the provider for a given card name and provider type.

SCardGetCardTypeProviderNameW

Returns the name of the module (dynamic link library) that contains the provider for a given card name and provider type.

SCardGetDeviceTypeIdA

Gets the device type identifier of the card reader for the given reader name. This function does not affect the state of the
reader.

SCardGetDeviceTypeIdW

Gets the device type identifier of the card reader for the given reader name. This function does not affect the state of the
reader.

SCardGetProviderIdA

Returns the identifier (GUID) of the primary service provider for a given card.

SCardGetProviderIdW

Returns the identifier (GUID) of the primary service provider for a given card.
SCardGetReaderDeviceInstanceIdA

Gets the device instance identifier of the card reader for the given reader name. This function does not affect the state of the
reader.

SCardGetReaderDeviceInstanceIdW

Gets the device instance identifier of the card reader for the given reader name. This function does not affect the state of the
reader.

SCardGetReaderIconA

Gets an icon of the smart card reader for a given reader's name.

SCardGetReaderIconW

Gets an icon of the smart card reader for a given reader's name.

SCardGetStatusChangeA

Blocks execution until the current availability of the cards in a specific set of readers changes.

SCardGetStatusChangeW

Blocks execution until the current availability of the cards in a specific set of readers changes.

SCardGetTransmitCount

Retrieves the number of transmit operations that have completed since the specified card reader was inserted.

SCardIntroduceCardTypeA

Introduces a smart card to the smart card subsystem (for the active user) by adding it to the smart card database.

SCardIntroduceCardTypeW

Introduces a smart card to the smart card subsystem (for the active user) by adding it to the smart card database.

SCardIntroduceReaderA

Introduces a new name for an existing smart card reader.

SCardIntroduceReaderGroupA

Introduces a reader group to the smart card subsystem. However, the reader group is not created until the group is specified
when adding a reader to the smart card database.

SCardIntroduceReaderGroupW

Introduces a reader group to the smart card subsystem. However, the reader group is not created until the group is specified
when adding a reader to the smart card database.

SCardIntroduceReaderW

Introduces a new name for an existing smart card reader.

SCardIsValidContext

Determines whether a smart card context handle is valid.

SCardListCardsA

Searches the smart card database and provides a list of named cards previously introduced to the system by the user.

SCardListCardsW

Searches the smart card database and provides a list of named cards previously introduced to the system by the user.

SCardListInterfacesA

Provides a list of interfaces supplied by a given card.

SCardListInterfacesW

Provides a list of interfaces supplied by a given card.

SCardListReaderGroupsA

Provides the list of reader groups that have previously been introduced to the system.

SCardListReaderGroupsW

Provides the list of reader groups that have previously been introduced to the system.

SCardListReadersA

Provides the list of readers within a set of named reader groups, eliminating duplicates.

SCardListReadersW

Provides the list of readers within a set of named reader groups, eliminating duplicates.

SCardListReadersWithDeviceInstanceIdA

Gets the list of readers that have provided a device instance identifier. This function does not affect the state of the reader.

SCardListReadersWithDeviceInstanceIdW

Gets the list of readers that have provided a device instance identifier. This function does not affect the state of the reader.

SCardLocateCardsA

Searches the readers listed in the rgReaderStates parameter for a card with an ATR string that matches one of the card names
specified in mszCards, returning immediately with the result.

SCardLocateCardsByATRA

Searches the readers listed in the rgReaderStates parameter for a card with a name that matches one of the card names
contained in one of the SCARD_ATRMASK structures specified by the rgAtrMasks parameter.
SCardLocateCardsByATRW

Searches the readers listed in the rgReaderStates parameter for a card with a name that matches one of the card names
contained in one of the SCARD_ATRMASK structures specified by the rgAtrMasks parameter.

SCardLocateCardsW

Searches the readers listed in the rgReaderStates parameter for a card with an ATR string that matches one of the card names
specified in mszCards, returning immediately with the result.

SCardReadCacheA

Retrieves the value portion of a name-value pair from the global cache maintained by the Smart Card Resource Manager.

SCardReadCacheW

Retrieves the value portion of a name-value pair from the global cache maintained by the Smart Card Resource Manager.

SCardReconnect

Reestablishes an existing connection between the calling application and a smart card.

SCardReleaseContext

Closes an established resource manager context, freeing any resources allocated under that context, including SCARDHANDLE
objects and memory allocated using the SCARD_AUTOALLOCATE length designator.

SCardReleaseStartedEvent

Decrements the reference count for a handle acquired by a previous call to the SCardAccessStartedEvent function.

SCardRemoveReaderFromGroupA

Removes a reader from an existing reader group. This function has no effect on the reader.

SCardRemoveReaderFromGroupW

Removes a reader from an existing reader group. This function has no effect on the reader.

SCardSetAttrib

Sets the given reader attribute for the given handle.

SCardSetCardTypeProviderNameA

Specifies the name of the module (dynamic link library) containing the provider for a given card name and provider type.

SCardSetCardTypeProviderNameW

Specifies the name of the module (dynamic link library) containing the provider for a given card name and provider type.

SCardStatusA

Provides the current status of a smart card in a reader.

SCardStatusW

Provides the current status of a smart card in a reader.

SCardTransmit

Sends a service request to the smart card and expects to receive data back from the card.

SCardUIDlgSelectCardA

Displays the smart card Select Card dialog box.

SCardUIDlgSelectCardW

Displays the smart card Select Card dialog box.

SCardWriteCacheA

Writes a name-value pair from a smart card to the global cache maintained by the Smart Card Resource Manager.

SCardWriteCacheW

Writes a name-value pair from a smart card to the global cache maintained by the Smart Card Resource Manager.

ScopeExists

Indicates whether the specified scope exists in this IAzApplication3 object.

SendSAS

Simulates a secure attention sequence (SAS).

SetAccountInformation

Sets the user account information used by the IIS Network Device Enrollment Service (NDES) extension to perform enrollment
on behalf of network devices.

SetAclInformation

Sets information about an access control list (ACL).

SetApplicationPoolCredentials

Specifies user account information for the application pool in which the Certificate Enrollment Web Service (CES) runs.

SetCADistinguishedName

Sets a certification authority (CA) common name and an optional distinguished name suffix.

SetCAProperty

Sets a property value for the certification authority (CA).

SetCASetupProperty

Sets a property value for a certification authority (CA) configuration.

SetCertificateExtension

Adds a new extension to the certificate issued in response to a certificate request. This method was first defined by the
ICertAdmin interface.

SetCertificateExtension

Adds a new extension to the certificate.

SetCertificateProperty

To set a property associated with a certificate.

SetConfigEntry

Sets configuration information for a certification authority (CA).

SetConfiguration

Updates a responder service with configuration changes.

SetContext

Causes the current instantiation of the interface to operate on the request referenced by Context.

SetContext

Specifies the request to be used as the context for subsequent calls to Certificate Services.

SetContextAttributesA

Enables a transport application to set attributes of a security context for a security package. This function is supported only by
the Schannel security package.

SetContextAttributesW

Enables a transport application to set attributes of a security context for a security package. This function is supported only by
the Schannel security package.

SetCredential

Sets the credential used to contact the certificate enrollment policy (CEP) server.

SetCredential

Sets the credential used to contact the Certificate Enrollment Web Service.

SetCredentialsAttributesA

Sets the attributes of a credential, such as the name associated with the credential.
SetCredentialsAttributesW

Sets the attributes of a credential, such as the name associated with the credential.

SetDatabaseInformation

Sets the database related information for the certification authority (CA) role.

SetDefaultValues

Specifies a default hashing algorithm used to create a digest of the certificate request prior to signing.

SetEntriesInAclA

Creates a new access control list (ACL) by merging new access control or audit control information into an existing ACL
structure.

SetEntriesInAclW

Creates a new access control list (ACL) by merging new access control or audit control information into an existing ACL
structure.

SetFileSecurityA

Sets the security of a file or directory object.

SetFileSecurityW

Sets the security of a file or directory object.

SetHStoreCA

The SetHStoreCA method specifies the handle to use for the CA store. This method was first defined in the IEnroll2 interface.

SetHStoreMy

The SetHStoreMy method specifies the handle to use for the MY store. This method was first defined in the IEnroll2 interface.

SetHStoreRequest

The SetHStoreRequest method specifies the handle to use for the request store. This method was first defined in the IEnroll2
interface.

SetHStoreROOT

The SetHStoreROOT method specifies the handle to use for the Root store. This method was first defined in the IEnroll2
interface.

SetKernelObjectSecurity

Sets the security of a kernel object.

SetMSCEPSetupProperty

Sets a property value for a Network Device Enrollment Service (NDES) configuration.
SetNameCount

Sets a name count for the specified distribution point in a certificate revocation list (CRL) distribution information array.

SetNamedSecurityInfoA

Sets specified security information in the security descriptor of a specified object.

SetNamedSecurityInfoW

Sets specified security information in the security descriptor of a specified object.

SetNameEntry

Sets a name at a specified index of the alternate name array.

SetNameEntry

Sets a name at a specified index of a distribution point in a certificate revocation list (CRL) distribution information array.

SetParentCAInformation

Sets the parent certification authority (CA) information for a subordinate CA configuration.

setPendingRequestInfo

Sets properties for a pending request. This method was first defined in the ICEnroll4 interface.

setPendingRequestInfoWStr

Sets properties for a pending request.

SetPrivateKeyArchiveCertificate

The SetPrivateKeyArchiveCertificate method specifies the certificate used to archive the private key. This method was first
defined in the IEnroll4 interface.

SetPrivateObjectSecurity

Modifies a private object's security descriptor.

SetPrivateObjectSecurityEx

Modifies the security descriptor of a private object maintained by the resource manager calling this function.

SetProperty

Sets the specified value to the IAzApplication object property with the specified property ID.

SetProperty

Sets the specified value to the IAzApplicationGroup object property with the specified property ID.
SetProperty

Sets the specified value to the AzAuthorizationStore object property with the specified property ID.

SetProperty

Sets the specified value to the IAzOperation object property with the specified property ID.

SetProperty

Sets the specified value to the IAzRole object property with the specified property ID.

SetProperty

Sets the specified value to the IAzScope object property with the specified property ID.

SetProperty

Sets the specified value to the IAzTask object property with the specified property ID.

SetProperty

Specifies a CEPSetupProperty enumeration value for the Certificate Enrollment Policy (CEP) Web Service configuration.

SetProperty

Specifies a CESSetupProperty enumeration value for the Certificate Enrollment Web Service (CES) configuration.

SetProperty

Allows a module to set a property value.

SetRequestAttributes

Sets attributes in the specified pending certificate request. This method was first defined in the ICertAdmin interface.

SetRestriction

Sets the sorting and qualifying restrictions on a column.

SetResultColumn

Specifies a column for the result set of a customized view of the Certificate Services database.

SetResultColumnCount

Specifies the maximum number of columns for the result set of a customized view of the Certificate Services database.

SetSecurity

The SetSecurity method provides a security descriptor containing the security information the user wants to apply to the
securable object. The access control editor calls this method when the user clicks Okay or Apply.
SetSecurity

Updates security descriptor information for an Online Certificate Status Protocol (OCSP) responder server.

SetSecurityAccessMask

Creates an access mask that represents the access permissions necessary to set the specified object security information.

SetSecurityDescriptorControl

Sets the control bits of a security descriptor. The function can set only the control bits that relate to automatic inheritance of
ACEs.

SetSecurityDescriptorDacl

Sets information in a discretionary access control list (DACL). If a DACL is already present in the security descriptor, the DACL
is replaced.

SetSecurityDescriptorGroup

Sets the primary group information of an absolute-format security descriptor, replacing any primary group information
already present in the security descriptor.

SetSecurityDescriptorOwner

Sets the owner information of an absolute-format security descriptor. It replaces any owner information already present in the
security descriptor.

SetSecurityDescriptorRMControl

Sets the resource manager control bits in the SECURITY_DESCRIPTOR structure.

SetSecurityDescriptorSacl

Sets information in a system access control list (SACL). If there is already a SACL present in the security descriptor, it is
replaced.

SetSecurityInfo

Sets specified security information in the security descriptor of a specified object. The caller identifies the object by a handle.

SetServiceObjectSecurity

Sets the security descriptor of a service object.

SetServiceStatus

Updates the service control manager's status information for the calling service.

SetSharedFolder

Specifies the path to be used as the certification authority's (CA) shared folder.

SetSignerCertificate

The SetSignerCertificate method specifies the signer's certificate. This method was first defined in the IEnroll4 interface.
SetStringProperty

Specifies the certificate enrollment policy (CEP) server ID or the display name of the CEP server.

SetTable

Specifies which Certificate Services database table is used for subsequent calls to the methods of the ICertView2 interface.

SetThreadToken

Assigns an impersonation token to a thread. The function can also cause a thread to stop using an impersonation token.

SetTokenInformation

Sets various types of information for a specified access token.

SetUserObjectSecurity

Sets the security of a user object. This can be, for example, a window or a DDE conversation.

SetValue

Sets a DATE value at the specified index of the DATE array.

SetValue

Sets a Long value at the specified index of the Long array.

SetValue

Sets a string value at the specified index of the string array.

SetValueOnCertificate

Associates a property value with an existing certificate.

SetWebCAInformation

Sets the certification authority (CA) information for the Certification Authority Web Enrollment role.

ShutDown

Called by the server engine before the server is terminated.

Skip

Skips a specified number of attributes in the attribute-enumeration sequence.

Skip

Skips a specified number of columns in the column-enumeration sequence.

Skip

Skips a specified number of extensions in the extension-enumeration sequence.

Skip

Skips a specified number of rows in the row enumeration sequence.

SLAcquireGenuineTicket

Gets a XrML genuine ticket acquired from the Software Licensing Server (SLS).

SLActivateProduct

Acquires a use license from the Software License Server (SLS).

SLClose

Closes the Software Licensing Client (SLC) context handle.

SLConsumeRight

Let an application to exercise rights on a locally-stored licenses.

SLDepositMigrationBlob

Deposits licensing information previously collected and gathered using the SLGatherMigrationBlob function.

SLDepositOfflineConfirmationId

Deposits Installation ID (IID) and Confirmation ID (CID) for offline activation.

SLDepositOfflineConfirmationIdEx

Deposits Installation ID (IID) and Confirmation ID (CID) for offline activation.

SLFireEvent

Sends a specified event to a registered listener.

SLGatherMigrationBlob

Gathers licensing information for the provided file handle. This licensing information can later be applied or deposited using
the SLDepositMigrationBlob function.

SLGenerateOfflineInstallationId

Generates the Installation ID (IID).

SLGenerateOfflineInstallationIdEx

Generates Installation ID (IID).

SLGetApplicationInformation

Gets information about the specified application.

SLGetApplicationPolicy

Queries a policy from the set stored with the SLPersistApplicationPolicies function and loaded using the
SLLoadApplicationPolicies function.

SLGetAuthenticationResult

Gets the authentication results.

SLGetGenuineInformation

Gets information about the genuine state of a Windows computer.

SLGetGenuineInformationEx

Specifies information about the genuine status of a Windows computer.

SLGetInstalledProductKeyIds

This function returns a list of product key IDs associated with the specified Product SKU ID.

SLGetLicense

Returns the license file BLOB.

SLGetLicenseFileId

Checks if the license BLOB has been installed already.

SLGetLicenseInformation

Gets the specified license information.

SLGetLicensingStatusInformation

Gets the licensing status of the specified application or SKU.

SLGetPKeyId

Gets the registered product key ID associated with the product.

SLGetPKeyInformation

Gets the information of the specified product key.

SLGetPolicyInformation

Gets the policy information after right has been consumed successfully.

SLGetPolicyInformationDWORD

Gets the policy information after right has been consumed successfully.
SLGetProductSkuInformation

Gets information about the specified product SKU.

SLGetReferralInformation

Gets referral information for the specified product.

SLGetServerStatus

Checks the server status according to the specified URL and RequestType.

SLGetServiceInformation

Gets global data information.

SLGetSLIDList

Gets a list of SLIDs according to the input query ID type and the ID value.

SLGetWindowsInformation

Retrieves the value portion of a name-value pair from the licensing policy of a software component.

SLGetWindowsInformationDWORD

Retrieves the DWORD value portion of a name-value pair from the licensing policy of a software component.

SLInstallLicense

Stores the specified license and returns a license file ID.

SLInstallProofOfPurchase

Registers the product key with SL.

SLInstallProofOfPurchaseEx

Register the product key with SL.

SLIsGenuineLocal

Checks whether the specified application is a genuine Windows installation.

SLIsGenuineLocalEx

Checks whether the specified application installation is genuine.

SLLoadApplicationPolicies

Loads the application policies set with the SLPersistApplicationPolicies function for use by the SLGetApplicationPolicy function.

SLOpen

Initializes the Software Licensing Client (SLC) and connects SLC to the Software Licensing Service (SLS).
SLPersistApplicationPolicies

Stores the current consumed policies to disk for fast policy access.

SLPersistRTSPayloadOverride

Associates information with the specified product for both online and phone activation.

SLQueryLicenseValueFromApp

Gets the value for the specified component policy.

SLReArm

This function is rearm application activation.

SLRegisterEvent

Registers an event in the SL service.

SLSetAuthenticationData

Sets authentication data.

SLSetCurrentProductKey

Sets the current product key to the previously installed product key.

SLSetGenuineInformation

Specifies information about the genuine status of a Windows computer.

SLUninstallLicense

Uninstalls the license specified by the license file ID and target user option.

SLUninstallProofOfPurchase

Unregisters the product key information.

SLUnloadApplicationPolicies

Releases the policy context handle returned by the SLLoadApplicationPolicies function.

SLUnregisterEvent

Unregisters a registered event in the SL service.

SpAcceptCredentialsFn

Called by the Local Security Authority (LSA) to pass the security package any credentials stored for the authenticated security
principal.
SpAcceptLsaModeContextFn

Server dispatch function used to create a security context shared by a server and client.

SpAcquireCredentialsHandleFn

Called to obtain a handle to a principal's credentials.

SpAddCredentialsFn

Used to add credentials for a security principal.

SpApplyControlTokenFn

Applies a control token to a security context. This function is not currently called by the Local Security Authority (LSA).

SpCompleteAuthTokenFn

Completes an authentication token.

SpDeleteCredentialsFn

Deletes credentials from a security package's list of primary or supplemental credentials.

SpExchangeMetaDataFn

Sends metadata to a security support provider.

SpExportSecurityContextFn

Exports a security context to another process.

SpFormatCredentialsFn

Formats credentials to be stored in a user object.

SpFreeCredentialsHandleFn

Frees credentials acquired by calling the SpAcquireCredentialsHandle function.

SpGetContextTokenFn

Obtains the token to impersonate.

SpGetCredentialsFn

Retrieves the primary and supplemental credentials from the user object.

SpGetCredUIContextFn

Retrieves context information from a credential provider.

SpGetExtendedInformationFn

Provides extended information about a security package.

SpGetInfoFn

Provides general information about the security package, such as its name and capabilities.

SpGetUserInfoFn

Retrieves information about a logon session.

SpImportSecurityContextFn

Imports a security context from another process.

SpInitializeFn

Is called once by the Local Security Authority (LSA) to provide a security package with general security information and a
dispatch table of support functions.

SpInitLsaModeContextFn

The client dispatch function used to establish a security context between a server and client.

SpInitUserModeContextFn

Creates a user-mode security context from a packed Local Security Authority (LSA)-mode context.

SpInstanceInitFn

Initializes user-mode security packages in an SSP/AP.

SpLsaModeInitializeFn

Provides the LSA with pointers to the functions implemented by each security package in the SSP/AP DLL.

SpMarshallSupplementalCredsFn

Converts supplemental credentials from a public format into a format suitable for local procedure calls.

SpQueryContextAttributesFn

Retrieves the attributes of a security context.

SpQueryCredentialsAttributesFn

Retrieves the attributes for a credential.

SpQueryMetaDataFn

Gets metadata from a security support provider (SSP) when it is initiating a security context.

SpSaveCredentialsFn

Saves a supplemental credential to the user object.

SpSealMessageFn

Encrypts a message exchanged between a client and server.

SpSetExtendedInformationFn

Sets extended information about the security package.

SpUnsealMessageFn

Decrypts a message that was previously encrypted with the SpSealMessage function.

SpUpdateCredentialsFn

Updates the credentials associated with the specified context.

SpUserModeInitializeFn

Called when a security support provider/authentication package (SSP/AP) DLL is loaded into the process space of a
client/server application. This function provides the SECPKG_USER_FUNCTION_TABLE tables for each security package in the
SSP/AP DLL.

SpValidateTargetInfoFn

Validates that the specified SECPKG_TARGETINFO structure represents a valid target.

SslCrackCertificate

Returns an X509Certificate structure with the information contained in the specified certificate BLOB.

SslEmptyCacheA

Removes the specified string from the Schannel cache.

SslEmptyCacheW

Removes the specified string from the Schannel cache.

SslFreeCertificate

Frees a certificate that was allocated by a previous call to the SslCrackCertificate function.

SslGetServerIdentity

Gets the identity of the server.

SspiAcceptSecurityContextAsync

Lets the server component of a transport application asynchronously establish a security context between the server and a
remote client.

SspiAcquireCredentialsHandleAsyncA

Asynchronously acquires a handle to preexisting credentials of a security principal.

SspiAcquireCredentialsHandleAsyncW

Asynchronously acquires a handle to preexisting credentials of a security principal.

SspiAsyncContextRequiresNotify

Determines whether a given async context requires notification on completion of the call.

SspiAsyncNotifyCallback

Callback used for notifying completion of an async SSPI call.

SspiCompareAuthIdentities

Compares the two specified credentials.

SspiCopyAuthIdentity

Creates a copy of the specified opaque credential structure.

SspiCreateAsyncContext

Creates an instance of SspiAsyncContext which is used to track the async call.

SspiDecryptAuthIdentity

Decrypts the specified encrypted credential.

SspiDecryptAuthIdentityEx

Decrypts a SEC_WINNT_AUTH_IDENTITY_OPAQUE structure.

SspiDeleteSecurityContextAsync

Deletes the local data structures associated with the specified security context initiated by a previous call to the
SspiInitializeSecurityContextAsync function or the SspiAcceptSecurityContextAsync function.

SspiEncodeAuthIdentityAsStrings

Encodes the specified authentication identity as three strings.

SspiEncodeStringsAsAuthIdentity

Encodes a set of three credential strings as an authentication identity structure.

SspiEncryptAuthIdentity

Encrypts the specified identity structure.

SspiEncryptAuthIdentityEx

Encrypts a SEC_WINNT_AUTH_IDENTITY_OPAQUE structure.

SspiExcludePackage

Creates a new identity structure that is a copy of the specified identity structure modified to exclude the specified security
support provider (SSP).

SspiFreeAsyncContext

Frees up a context created in the call to the SspiCreateAsyncContext function.

SspiFreeAuthIdentity

Frees the memory allocated for the specified identity structure.

SspiFreeCredentialsHandleAsync

Frees up a credential handle.

SspiGetAsyncCallStatus

Gets the current status of an async call associated with the provided context.

SspiGetCredUIContext

Retrieves context information from a credential provider.

SspiGetTargetHostName

Gets the host name associated with the specified target.

SspiInitializeSecurityContextAsyncA

Initializes an async security context.

SspiInitializeSecurityContextAsyncW

Initializes an async security context.

SspiIsAuthIdentityEncrypted

Indicates whether the specified identity structure is encrypted.

SspiIsPromptingNeeded

Indicates whether an error returned after a call to either the InitializeSecurityContext or the AcceptSecurityContext function
requires an additional call to the SspiPromptForCredentials function.

SspiLocalFree

Frees the memory associated with the specified buffer.

SspiMarshalAuthIdentity

Serializes the specified identity structure into a byte array.

SspiPrepareForCredRead

Generates a target name and credential type from the specified identity structure.

SspiPrepareForCredWrite

Generates values from an identity structure that can be passed as the values of parameters in a call to the CredWrite function.

SspiPromptForCredentialsA

Allows a Security Support Provider Interface (SSPI) application to prompt a user to enter credentials.

SspiPromptForCredentialsW

Allows a Security Support Provider Interface (SSPI) application to prompt a user to enter credentials.

SspiReinitAsyncContext

Marks an async context for reuse.

SspiSetAsyncNotifyCallback

Registers a callback that is notified on async call completion.

SspiUnmarshalAuthIdentity

Deserializes the specified array of byte values into an identity structure.

SspiUnmarshalCredUIContext

Deserializes credential information obtained by a credential provider during a previous call to the
ICredentialProvider::SetSerialization method.

SspiUpdateCredentials

Updates the credentials associated with the specified context.

SspiValidateAuthIdentity

Indicates whether the specified identity structure is valid.

SspiZeroAuthIdentity

Fills the block of memory associated with the specified identity structure with zeros.

StartServiceA

Starts a service.

StartServiceCtrlDispatcherA

Connects the main thread of a service process to the service control manager, which causes the thread to be the service
control dispatcher thread for the calling process.
StartServiceCtrlDispatcherW

Connects the main thread of a service process to the service control manager, which causes the thread to be the service
control dispatcher thread for the calling process.

StartServiceW

Starts a service.

stringToBinary

Converts an encoded string to a binary data BLOB. This method was first defined in the ICEnroll4 interface.

stringToBinaryBlob

Converts an encoded string to a binary data BLOB.

StringToString

Modifies the type of Unicode encoding applied to a string.

StringToVariantByteArray

Creates a byte array from a Unicode encoded string.

Submit

Persists changes made to the IAzApplication object.

Submit

Persists changes made to the IAzApplicationGroup object.

Submit

Persists changes made to the AzAuthorizationStore object.

Submit

Persists changes made to the IAzOperation object.

Submit

Persists changes made to the IAzRole object.

Submit

Persists changes made to the IAzScope object.

Submit

Persists changes made to the IAzTask object.

Submit

Submits a request to the Certificate Services server.

TokenBindingDeleteAllBindings

Deletes all token binding keys that are associated with the calling user or app container.

TokenBindingDeleteBinding

Deletes the token binding key that is associated with the specified target string.

TokenBindingGenerateBinding

Constructs one token binding that contains the exported public key and signature by using the specified key type for the
token binding, a target identifier string for creating and retrieving the token binding key, and the unique data.

TokenBindingGenerateID

Constructs the token binding identifier by extracting the signature algorithm from the key type and copying the exported
public key.

TokenBindingGenerateMessage

Assembles the list of token bindings and generates the final message for the client device to the server.

TokenBindingGetKeyTypesClient

Retrieves a list of the key types that the client device supports.

TokenBindingGetKeyTypesServer

Retrieves a list of the key types that the server supports.

TokenBindingVerifyMessage

Validates the token binding message and verifies the token bindings that the message contains.

TreeResetNamedSecurityInfoA

Resets specified security information in the security descriptor of a specified tree of objects.

TreeResetNamedSecurityInfoW

Resets specified security information in the security descriptor of a specified tree of objects.

TreeSetNamedSecurityInfoA

Sets specified security information in the security descriptor of a specified tree of objects.

TreeSetNamedSecurityInfoW

Sets specified security information in the security descriptor of a specified tree of objects.
UnAdvise

Deletes a connection created by calling the Advise method.

Uninitialize

Uninitializes the NDES policy module.

UnInstall

Removes the Certificate Enrollment Policy (CEP) Web Service.

UnInstall

Removes the Certificate Enrollment Web Service (CES).

UnlockServiceDatabase

Unlocks a service control manager database by releasing the specified lock.

UpdateCache

Updates the cache of objects and object attributes to match the underlying policy store.

UpdateRegistry

Registers a certificate enrollment policy (CEP) server.

UpgradeStoresFunctionalLevel

Upgrades this authorization store from version 1 to version 2.

Validate

Validates the current policy information.

VariantByteArrayToString

Creates a Unicode encoded string from a byte array.

Verify

Verifies that a private key exists and can be used by the client but does not open the key.

VerifyRequest

Notifies the policy module that a new request has entered the system.

VerifyRequest

Verifies the NDES certificate request for submission to the CA.

VerifySignature

Verifies that a message signed by using the MakeSignature function was received in the correct sequence and has not been
modified.

WintrustAddActionID

Adds a trust provider action to the user's system.

WintrustAddDefaultForUsage

Specifies the default usage identifier and callback information for a provider.

WintrustGetDefaultForUsage

Retrieves the default usage identifier and callback information.

WintrustGetRegPolicyFlags

Retrieves policy flags for a policy provider.

WintrustLoadFunctionPointers

Loads function entry points for a specified action GUID. This function has no associated import library.

WintrustRemoveActionID

Removes an action added by the WintrustAddActionID function. This function has no associated import library.

WintrustSetDefaultIncludePEPageHashes

Sets the default setting that determines whether page hashes are included when creating subject interface package (SIP)
indirect data for PE files.

WintrustSetRegPolicyFlags

Sets policy flags for a policy provider.

WinVerifyTrust

Performs a trust verification action on a specified object.

WinVerifyTrustEx

Performs a trust verification action on a specified object and takes a pointer to a WINTRUST_DATA structure.

WlxActivateUserShell

Activates the user shell program.

WlxDisconnectNotify

Winlogon calls this function when a Terminal Services network session is disconnected.
WlxDisplayLockedNotice

Allows the GINA to display information about the lock, such as who locked the workstation and when it was locked.

WlxDisplaySASNotice

Winlogon calls this function when no user is logged on.

WlxDisplayStatusMessage

Winlogon calls this function when the GINA DLL should display a message.

WlxGetConsoleSwitchCredentials

Winlogon calls this function to read the currently logged on user's credentials to transparently transfer them to a target
session.

WlxGetStatusMessage

Winlogon calls this function to get the status message being displayed by the GINA DLL.

WlxInitialize

Winlogon calls this function once for each window station present on the computer. Currently, the operating system supports
one window station per workstation.

WlxIsLockOk

Winlogon calls this function before attempting to lock the workstation.

WlxIsLogoffOk

Winlogon calls this function when the user initiates a logoff operation.

WlxLoggedOnSAS

Winlogon calls this function when it receives a secure attention sequence (SAS) event while the user is logged on and the
workstation is not locked.

WlxLoggedOutSAS

Winlogon calls this function when it receives a secure attention sequence (SAS) event while no user is logged on.

WlxLogoff

Winlogon calls this function to notify the GINA of a logoff operation on this workstation, allowing the GINA to perform any
logoff operations that may be required.

WlxNegotiate

The WlxNegotiate function must be implemented by a replacement GINA DLL. This is the first call made by Winlogon to the
GINA DLL. WlxNegotiate allows the GINA to verify that it supports the installed version of Winlogon.

WlxNetworkProviderLoad

Winlogon calls this function to collect valid authentication and identification information.
WlxReconnectNotify

Winlogon calls this function when a Terminal Services network session is reconnected.

WlxRemoveStatusMessage

Winlogon calls this function to tell the GINA DLL to stop displaying the status message.

WlxScreenSaverNotify

Winlogon calls this function immediately before a screen saver is activated, allowing the GINA to interact with the screen saver
program.

WlxShutdown

Winlogon calls this function just before shutting down, allowing the GINA to perform any shutdown tasks, such as ejecting a
smart card from a reader.

WlxStartApplication

Winlogon calls this function when the system needs an application to be started in the context of the user.

WlxWkstaLockedSAS

Winlogon calls this function when it receives a secure attention sequence (SAS) and the workstation is locked.

WNetSetLastErrorA

Sets extended error information. Network providers should call this function instead of SetLastError.

WNetSetLastErrorW

Sets extended error information. Network providers should call this function instead of SetLastError.

WTHelperCertCheckValidSignature

Checks whether a signature is valid.

WTHelperCertIsSelfSigned

Checks whether a certificate is self-signed.

WTHelperGetProvCertFromChain

Retrieves a trust provider certificate from the certificate chain.

WTHelperGetProvPrivateDataFromChain

Receives a CRYPT_PROVIDER_PRIVDATA structure from the chain by using the provider ID.

WTHelperGetProvSignerFromChain

Retrieves a signer or countersigner by index from the chain.

 WTHelperProvDataFromStateData

Retrieves trust provider information from a specified handle.

Interfaces

IAlternativeName

Is used by an IX509ExtensionAlternativeNames object to represent an instance of an AlternativeNames extension.

IAlternativeNames

Contains methods and properties that enable you to manage a collection of IAlternativeName objects.

IAssociatedIdentityProvider

Allows an identity provider to associate identities with local user accounts.

IAzApplication

Defines an installed instance of an application. An IAzApplication object is created when an application is installed.

IAzApplication2

Inherits from the IAzApplication interface and implements additional methods to initialize IAzClientContext2 objects.

IAzApplication3

Provides methods to manage IAzRoleAssignment, IAzRoleDefinition, and IAzScope2 objects.

IAzApplicationGroup

Defines a collection of principals.

IAzApplicationGroup2

Extends the IAzApplicationGroup interface by adding support for the BizRule group type.

IAzApplicationGroups

Represents a collection of IAzApplicationGroup objects.

IAzApplications

Represents a collection of IAzApplication objects.

IAzAuthorizationStore

Defines the container that is the root of the authorization policy store.
IAzAuthorizationStore2

Inherits from the AzAuthorizationStore object and implements methods to create and open IAzApplication2 objects.

IAzAuthorizationStore3

Extends the IAzAuthorizationStore2 interface with methods that manage business rule (BizRule) support and caching.

IAzBizRuleContext

Contains information about a Business Rule (BizRule) operation.

IAzBizRuleInterfaces

Provides methods and properties used to manage a list of IDispatch interfaces that can be called by business rule (BizRule)
scripts.

IAzBizRuleParameters

Provides methods and properties used to manage a list of parameters that can be passed to business rule (BizRule) scripts.

IAzClientContext

Maintains the state that describes a particular client.

IAzClientContext2

Inherits from the IAzClientContext interface and implements new methods that manipulate the client context.

IAzClientContext3

Extends the IAzClientContext2 interface.

IAzNameResolver

Translates security identifiers (SIDs) into principal display names.

IAzObjectPicker

Displays a dialog box that allows users to select one or more principals from a list.

IAzOperation

Defines a low-level operation supported by an application.

IAzOperation2

Extends the IAzOperation with a method that returns the role assignments associated with the operation.

IAzOperations

Represents a collection of IAzOperation objects.

IAzPrincipalLocator

Locates and chooses ADAM principals in Authorization Manager.

IAzRole

Defines the set of operations that can be performed by a set of users within a scope.

IAzRoleAssignment

Represents a role to which users and groups can be assigned.

IAzRoleAssignments

Represents a collection of IAzRoleAssignment objects.

IAzRoleDefinition

Represents one or more IAzRoleDefinition, IAzTask, and IAzOperation objects that specify a set of operations.

IAzRoleDefinitions

Represents a collection of IAzRoleDefinition objects.

IAzRoles

Represents a collection of IAzRole objects.

IAzScope

Defines a logical container of resources to which the application manages access.

IAzScope2

Extends the IAzScope interface to manage IAzRoleAssignment and IAzRoleDefinition objects.

IAzScopes

Represents a collection of IAzScope objects.

IAzTask

Describes a set of operations.

IAzTask2

Extends the IAzTask interface with a method that returns the role assignments associated with the task.

IAzTasks

Represents a collection of IAzTask objects.

IBinaryConverter

Contains general methods that enable you to create a Unicode-encoded string from a byte array, create a byte array from a
Unicode-encoded string, and modify the type of Unicode encoding applied to a string.

ICcgDomainAuthCredentials

A client-implemented interface that allows developers to supply their own credentials dynamically at run time to authenticate
non-domain joined containers with Active Directory.

ICEnroll

The ICEnroll interface is one of several interfaces that represent the Certificate Enrollment Control.

ICEnroll2

The ICEnroll2 interface is one of several interfaces that represent the Certificate Enrollment Control.

ICEnroll3

One of several interfaces that represent the Certificate Enrollment Control.

ICEnroll4

The ICEnroll4 interface is one of several interfaces that represent the Certificate Enrollment Control.

ICertAdmin

Provides administration functionality for properly authorized clients.

ICertAdmin2

Provide administration functionality for properly authorized clients.

ICertConfig

The ICertConfig interface provides functionality for retrieving the public configuration data (specified during client setup) for a
Certificate Services server.

ICertConfig2

Provide functionality for retrieving the public configuration data (specified during client setup) for a Certificate Services server.

ICertEncodeAltName

Provides methods for handling alternate names used in certificate extensions.

ICertEncodeBitString

Provides methods for handling bit strings used in certificate extensions.

ICertEncodeCRLDistInfo

Provides methods for handling certificate revocation list (CRL) distribution information arrays used in certificate extensions.
ICertEncodeDateArray

Provides methods for handling Date arrays used in certificate extensions.

ICertEncodeLongArray

Provides methods for handling Long arrays used in certificate extensions.

ICertEncodeStringArray

Provides methods for handling string arrays used in certificate extensions.

ICertExit

Provides communications between the Certificate Services server and an exit module.

ICertExit2

Provide communications between the Certificate Services server and an exit module.

ICertGetConfig

Provides functionality for retrieving the public configuration data (specified during client setup) for a Certificate Services server.

ICertificateAttestationChallenge

Allows applications to decrypt a key attestation challenge received from a server.

ICertificateEnrollmentPolicyServerSetup

The ICertificateEnrollmentPolicyServerSetup interface represents the Certificate Enrollment Policy (CEP) Web Service within
Active Directory Certificate Services (ADCS).

ICertificateEnrollmentServerSetup

The ICertificateEnrollmentServerSetup interface represents the Certificate Enrollment Web Service (CES) within Active
Directory Certificate Services (ADCS).

ICertificatePolicies

Contains methods and properties that enable you to manage a collection of ICertificatePolicy objects.

ICertificatePolicy

Can be used to specify a certificate policy that identifies a purpose for which the certificate can be used.

ICertificationAuthorities

The ICertificationAuthorities interface defines the following methods and properties that manage a collection of
ICertificationAuthority objects.

ICertificationAuthority

The ICertificationAuthority interface represents a single certification authority. A collection of certification authorities is
represented by the ICertificationAuthorities interface.
ICertManageModule

Provided to retrieve information about a Certificate Services Policy or Exit module.

ICertPolicy

Provides communications between the Certificate Services server engine and the policy module.

ICertPolicy2

Provide communications between the Certificate Services server engine and the policy module.

ICertProperties

Contains methods and properties that enable you to manage a collection of certificate properties.

ICertProperty

Can be used to associate an external property with a certificate.

ICertPropertyArchived

Represents a certificate property that identifies whether a certificate has been archived.

ICertPropertyArchivedKeyHash

Represents a SHA-1 hash of an encrypted private key submitted to a certification authority for archival.

ICertPropertyAutoEnroll

Represents a certificate property that identifies a template that has been configured to enable autoenrollment of the
certificate.

ICertPropertyBackedUp

Represents an external certificate property that identifies whether a certificate has been backed up and, if so, the date and
time that it was saved.

ICertPropertyDescription

Enables you to specify and retrieve a string that contains descriptive information for a certificate.

ICertPropertyEnrollment

Represents a certificate property that contains certificate and certification authority (CA) information created when the client
calls the Enroll method on the IX509Enrollment interface.

ICertPropertyEnrollmentPolicyServer

Represents an external certificate property that contains information about a certificate enrollment policy (CEP) server and a
certificate enrollment server (CES).

ICertPropertyFriendlyName

Enables you to specify and retrieve a string that contains the display name of a certificate.
ICertPropertyKeyProvInfo

Represents a certificate property that contains information about a private key.

ICertPropertyRenewal

Represents a certificate property that contains a SHA-1 hash of the new certificate created when an existing certificate is
renewed.

ICertPropertyRequestOriginator

Represents a certificate property that contains the Domain Naming System (DNS) name of the computer on which the request
was created.

ICertPropertySHA1Hash

Represents a certificate property that contains a SHA-1 hash of the certificate.

ICertRequest

Provides communications between a client or intermediary application and Certificate services.

ICertRequest2

Provide communications between a client or intermediary application and Certificate Services.

ICertRequest3

Provide communications between a client or intermediary application and Certificate Services.

ICertServerExit

Exported by the server engine and is called by exit modules.

ICertServerPolicy

Allows the policy module to communicate with Certificate Services.

ICertSrvSetup

Defines functionality to install and uninstall Certification Authority (CA) and Certification Authority Web Enrollment roles on a
Certificate Services computer.

ICertSrvSetupKeyInformation

Defines a set of private key properties that are used for setup of certification authority (CA) or Microsoft Simple Certificate
Enrollment Protocol (SCEP) roles.

ICertSrvSetupKeyInformationCollection

Defines functionality to populate and enumerate a collection of ICertSrvSetupKeyInformation objects.

ICertView

Allows properly authorized clients to create a customized or complete view of the Certificate Services database.
ICertView2

Allow properly authorized clients to create a customized or complete view of the Certificate Services database.

IConnectedIdentityProvider

Provides methods of interaction with a connected identity provider.

ICryptAttribute

The ICryptAttribute interface represents a cryptographic attribute in a certificate request. A collection of these attributes is
contained in the CertificateRequestInfo structure of a PKCS

ICryptAttributes

The ICryptAttributes interface contains methods and properties that enable you to manage a collection of ICryptAttribute
objects.

ICspAlgorithm

Represents an algorithm implemented by a cryptographic provider.

ICspAlgorithms

The ICspAlgorithms interface defines the following methods and properties that manage a collection of ICspAlgorithm objects.

ICspInformation

Provides access to general information about a cryptographic provider.

ICspInformations

The ICspInformations interface defines the following methods and properties to manage a collection of ICspInformation
objects.

ICspStatus

Contains information about a cryptographic provider/algorithm pair.

ICspStatuses

Contains information about a cryptographic provider/algorithm pair.

IEffectivePermission

Provides a means to determine effective permission for a security principal on an object.

IEffectivePermission2

Provides a way to determine effective permission for a security principal on an object.

IEnroll

Represents the Certificate Enrollment Control and is used primarily to generate certificate requests.
IEnroll2

Represents the Certificate Enrollment Control and is used primarily to generate certificate requests.

IEnroll4

The IEnroll4 interface represents the Certificate Enrollment Control and is used primarily to generate certificate requests.

IEnumCERTVIEWATTRIBUTE

Represents an attribute-enumeration sequence that contains the certificate attributes for the current row of the row-
enumeration sequence.

IEnumCERTVIEWCOLUMN

Represents a column-enumeration sequence that contains the column data for the current row of the enumeration sequence.

IEnumCERTVIEWEXTENSION

Represents an extension-enumeration sequence that contains the certificate extension data for the current row of the row-
enumeration sequence.

IEnumCERTVIEWROW

Represents a row-enumeration sequence that contains the data in the rows of the Certificate Services view, allowing further
access to the columns, attributes, and extensions associated with each row.

IIdentityAdvise

Allows an identity provider to notify a calling application when an identity is updated.

IIdentityProvider

Represents an identity provider.

IIdentityStore

Provides methods to enumerate and manage identities and identity providers.

IMSCEPSetup

Defines functionality to install and uninstall a Network Device Enrollment Service (NDES) role on a Certificate Services
computer.

INDESPolicy

The NDES Policy Module Interface. When installed against an enterprise CA, NDES generates a password after checking that
the user has enrollment permission on the configured NDES templates, both user and machine templates.

IObjectId

Represents an object identifier (OID).

IObjectIds

The IObjectIds interface defines methods and properties that enable you to manage a collection of IObjectId objects.
IOCSPAdmin

Provides functionality to manage an Online Certificate Status Protocol (OCSP) responder server.

IOCSPCAConfiguration

Represents a set of definitions that enable an Online Certificate Status Protocol (OCSP) service to respond to a certificate
status request for a specific certification authority (CA).

IOCSPCAConfigurationCollection

Represents a set of certificates for which an Online Certificate Status Protocol (OCSP) service has been configured to provide
certificate status responses.

IOCSPProperty

Represents a name-value pair for OCSPServiceProperties or ProviderProperties.

IOCSPPropertyCollection

Represents a set of configurable attribute properties (name-value pairs) for an Online Certificate Status Protocol (OCSP)
service.

IPolicyQualifier

Represents a qualifier that can be associated with a certificate policy.

IPolicyQualifiers

Defines methods and properties that enable you to manage a collection of IPolicyQualifier objects.

ISceSvcAttachmentData

The ISceSvcAttachmentData interface retrieves configuration and analysis data about a specified security service from the
Security Configuration snap-ins.

ISceSvcAttachmentPersistInfo

The ISceSvcAttachmentPersistInfo interface retrieves any modified configuration or analysis information from an attachment
snap-in.

ISecurityInformation

Enables the access control editor to communicate with the caller of the CreateSecurityPage and EditSecurity functions.

ISecurityInformation2

Enables the access control editor to obtain information from the client that is not provided by the ISecurityInformation
interface.

ISecurityInformation3

Provides methods necessary for displaying an elevated access control editor when a user clicks the Edit button on an access
control editor page that displays an image of a shield on that Edit button.
ISecurityInformation4

Enables the access control editor (ACE) to obtain the share's security descriptor to initialize the share page.

ISecurityObjectTypeInfo

Provides a means of determining the source of inherited access control entries (ACEs) in discretionary access control lists
(DACLs) and system access control lists (SACLs).

ISignerCertificate

Represents a signing certificate that enables you to sign a certificate request.

ISignerCertificates

The ISignerCertificates interface defines the following methods and properties to manage a collection of ISignerCertificate
objects.

ISmimeCapabilities

Defines the following methods and properties to manage a collection of ISmimeCapability objects.

ISmimeCapability

Represents an SMIMECapabilities extension that identifies the decryption capabilities of an email recipient.

ITpmVirtualSmartCardManager

Manages the TPM virtual smart cards.

ITpmVirtualSmartCardManagerStatusCallback

Notifies the caller of the progress of the requested operation or any resulting errors.

IX500DistinguishedName

Represents an X.500 distinguished name (DN).

IX509Attribute

Can be used to represent an attribute in a PKCS

IX509AttributeArchiveKey

Represents an attribute that contains an encrypted private key to be archived by a certification authority.

IX509AttributeArchiveKeyHash

Represents an attribute that contains a SHA-1 hash of the encrypted private key to be archived by a certification authority.

IX509AttributeClientId

Represents an attribute that can be used to identify the client that generated a certificate request.
IX509AttributeCspProvider

Represents an attribute that identifies the cryptographic provider used by the entity requesting the certificate.

IX509AttributeExtensions

Defines methods and properties that initialize and retrieve certificate extensions in a certificate request.

IX509AttributeOSVersion

Represents an attribute that contains version information about the client operating system on which the certificate request
was generated.

IX509AttributeRenewalCertificate

Represents an attribute that contains the certificate being renewed. This attribute is automatically placed in the PKCS

IX509Attributes

The IX509Attributes interface defines the following methods and properties that enable you to manage a collection of
IX509Attribute objects.

IX509CertificateRequest

The IX509CertificateRequest interface represents an abstract base certificate request that identifies methods and properties
common to and inherited by each of the request objects implemented by the Certificate Enrollment API.

IX509CertificateRequestCertificate

The IX509CertificateRequestCertificate interface represents a request object for a self-generated certificate, enabling you to
create a certificate directly without going through a registration or certification authority.

IX509CertificateRequestCertificate2

The IX509CertificateRequestCertificate2 interface represents a request object for a self-generated certificate, enabling you to
create a certificate directly without going through a registration or certification authority.

IX509CertificateRequestCmc

Represents a CMC (Certificate Management Message over CMS) certificate request.

IX509CertificateRequestCmc2

The IX509CertificateRequestCmc2 interface represents a CMC (Certificate Management Message over CMS) certificate
request.

IX509CertificateRequestPkcs10

The IX509CertificateRequestPkcs10 interface represents a PKCS

IX509CertificateRequestPkcs10V2

The IX509CertificateRequestPkcs10V2 interface represents a PKCS

IX509CertificateRequestPkcs10V3

The IX509CertificateRequestPkcs10V3 interface represents a PKCS

IX509CertificateRequestPkcs7

The IX509CertificateRequestPkcs7 interface represents a PKCS

IX509CertificateRequestPkcs7V2

The IX509CertificateRequestPkcs7V2 interface represents a PKCS

IX509CertificateTemplate

The IX509CertificateTemplate interface represents a certificate request template. It can be used to initialize an
IX509CertificateTemplateWritable interface.

IX509CertificateTemplates

The IX509CertificateTemplates interface defines the following methods and properties that manage a collection of
IX509CertificateTemplate objects.

IX509CertificateTemplateWritable

The IX509CertificateTemplateWritable interface enables you to add a template to or delete it from a template store. Currently,
Active Directory is the only available store.

IX509EndorsementKey

X.509 Endorsement Key Interface

IX509Enrollment

Represents the top level object and enables you to enroll in a certificate hierarchy and install a certificate response.

IX509Enrollment2

The IX509Enrollment2 interface enables you to enroll in a certificate hierarchy and install a certificate response.

IX509EnrollmentHelper

The IX509EnrollmentHelper interface defines methods that enable a web application to enroll a certificate, store policy server
credentials in the credential cache, and register policy servers and enrollment servers.

IX509EnrollmentPolicyServer

The IX509EnrollmentPolicyServer interface represents a certificate enrollment policy (CEP) server.

IX509EnrollmentStatus

The IX509EnrollmentStatus interface can be used to specify or retrieve detailed error information about a certificate enrollment
transaction.

IX509EnrollmentWebClassFactory

Can be used to create any of the following objects on a webpage.

IX509Extension

Can be used to define an extension for a certificate request.

IX509ExtensionAlternativeNames

Enables you to specify one or more alternative name forms for the subject of a certificate. A certification authority processes
the extension by binding the names to the certified public key.

IX509ExtensionAuthorityKeyIdentifier

Enables you to specify an AuthorityKeyIdentifier extension.

IX509ExtensionBasicConstraints

Enables you to specify whether the certificate subject is a certification authority and, if so, the depth of the subordinate
certification authority chain that can exist beneath the certification authority for which this extension ID is defined.

IX509ExtensionCertificatePolicies

Enables you to specify a collection of policy information terms, each of which consists of an object identifier (OID) and optional
policy qualifiers. A single policy term is defined by an ICertificatePolicy object.

IX509ExtensionEnhancedKeyUsage

Can be used to define a collection of object identifiers (OIDs) that identify the intended uses of the public key contained in the
certificate.

IX509ExtensionKeyUsage

Can be used to define restrictions on the operations that can be performed by the public key contained in the certificate.

IX509ExtensionMSApplicationPolicies

Enables you to specify a collection of object identifiers (OIDs) that indicate how a certificate can be used by an application.

IX509Extensions

The IX509Extensions interface defines the following methods and properties to manage a collection of IX509Extension objects.

IX509ExtensionSmimeCapabilities

Can be used to report the decryption capabilities of an email recipient to an email sender so that the sender can choose the
most secure algorithm supported by both parties.

IX509ExtensionSubjectKeyIdentifier

Enables you to specify a SubjectKeyIdentifier extension.

IX509ExtensionTemplate

Defines methods and properties that can be used to initialize or retrieve a CertificateTemplate extension.

IX509ExtensionTemplateName

Defines methods and properties that can be used to initialize or retrieve a template name extension.
 IX509MachineEnrollmentFactory

Can be used to create an IX509EnrollmentHelper object on a webpage.

IX509NameValuePair

Represents a generic name-value pair.

IX509NameValuePairs

The IX509NameValuePairs interface defines the following methods and properties to manage a collection of
IX509NameValuePair objects.

IX509PolicyServerListManager

The IX509PolicyServerListManager interface defines the following methods and properties that enable you to manage a
collection of IX509PolicyServerUrl objects.

IX509PolicyServerUrl

The IX509PolicyServerUrl interface can be used to set or retrieve property values associated with the certificate enrollment
policy (CEP) server and to update associated registry values.

IX509PrivateKey

Represents an asymmetric private key that can be used for encryption, signing, and key agreement.

IX509PublicKey

Represents a public key in a public/private key pair.

IX509SCEPEnrollment

X.509 Simple Computer Enrollment Protocol Interface

IX509SignatureInformation

Represents information used to sign a certificate request.

Structures

ACCESS_ALLOWED_ACE

Defines an access control entry (ACE) for the discretionary access control list (DACL) that controls access to an object. An
access-allowed ACE allows access to an object for a specific trustee identified by a security identifier (SID).

ACCESS_ALLOWED_CALLBACK_ACE

The ACCESS_ALLOWED_CALLBACK_ACE structure defines an access control entry for the discretionary access control list that
controls access to an object.
ACCESS_ALLOWED_CALLBACK_OBJECT_ACE

Defines an access control entry (ACE) that controls allowed access to an object, property set, or property.

ACCESS_ALLOWED_OBJECT_ACE

Defines an access control entry (ACE) that controls allowed access to an object, a property set, or property.

ACCESS_DENIED_ACE

Defines an access control entry (ACE) for the discretionary access control list (DACL) that controls access to an object. An
access-denied ACE denies access to an object for a specific trustee identified by a security identifier (SID).

ACCESS_DENIED_CALLBACK_ACE

The ACCESS_DENIED_CALLBACK_ACE structure defines an access control entry for the discretionary access control list that
controls access to an object.

ACCESS_DENIED_CALLBACK_OBJECT_ACE

The ACCESS_DENIED_CALLBACK_OBJECT_ACE structure defines an access control entry that controls denied access to an
object, a property set, or property.

ACCESS_DENIED_OBJECT_ACE

Defines an access control entry (ACE) that controls denied access to an object, a property set, or property.

ACE_HEADER

Defines the type and size of an access control entry (ACE).

ACL

Header of an access control list (ACL).

ACL_REVISION_INFORMATION

Contains revision information about an ACL structure.

ACL_SIZE_INFORMATION

Contains information about the size of an ACL structure.

AUDIT_POLICY_INFORMATION

Specifies a security event type and when to audit that type.

AUTHENTICODE_EXTRA_CERT_CHAIN_POLICY_PARA

Holds policy information used in the verification of certificate chains for files.

AUTHENTICODE_EXTRA_CERT_CHAIN_POLICY_STATUS

The AUTHENTICODE_EXTRA_CERT_CHAIN_POLICY_STATUS structure holds additional Authenticode policy information for

chain verification of files.
AUTHENTICODE_TS_EXTRA_CERT_CHAIN_POLICY_PARA

The AUTHENTICODE_TS_EXTRA_CERT_CHAIN_POLICY_PARA structure contains time stamp policy information that can be
used in certificate chain verification of files.

AUTHZ_ACCESS_REPLY

Defines an access check reply.

AUTHZ_ACCESS_REQUEST

Defines an access check request.

AUTHZ_INIT_INFO

Defines the initialization information for the resource manager.

AUTHZ_REGISTRATION_OBJECT_TYPE_NAME_OFFSET

Specifies the offset of a registration object type name.

AUTHZ_RPC_INIT_INFO_CLIENT

Initializes a remote resource manager for a client.

AUTHZ_SECURITY_ATTRIBUTE_FQBN_VALUE

Specifies a fully qualified binary name value associated with a security attribute.

AUTHZ_SECURITY_ATTRIBUTE_OCTET_STRING_VALUE

Specifies an octet string value for a security attribute.

AUTHZ_SECURITY_ATTRIBUTE_V1

Defines a security attribute that can be associated with an authorization context.

AUTHZ_SECURITY_ATTRIBUTES_INFORMATION

Specifies one or more security attributes and values.

AUTHZ_SOURCE_SCHEMA_REGISTRATION

Specifies information about source schema registration.

BCRYPT_ALGORITHM_IDENTIFIER

Is used with the BCryptEnumAlgorithms function to contain a cryptographic algorithm identifier.

BCRYPT_AUTHENTICATED_CIPHER_MODE_INFO

Used with the BCryptEncrypt and BCryptDecrypt functions to contain additional information related to authenticated cipher
modes.
BCRYPT_DH_KEY_BLOB

Used as a header for a Diffie-Hellman public key or private key BLOB in memory.

BCRYPT_DH_PARAMETER_HEADER

Used to contain parameter header information for a Diffie-Hellman key.

BCRYPT_DSA_KEY_BLOB

Used as a header for a Digital Signature Algorithm (DSA) public key or private key BLOB in memory.

BCRYPT_DSA_KEY_BLOB_V2

Used as a header for a Digital Signature Algorithm (DSA) public key or private key BLOB in memory.

BCRYPT_DSA_PARAMETER_HEADER

Used to contain parameter header information for a Digital Signature Algorithm (DSA) key.

BCRYPT_DSA_PARAMETER_HEADER_V2

Contains parameter header information for a Digital Signature Algorithm (DSA) key.

BCRYPT_ECCKEY_BLOB

Used as a header for an elliptic curve public key or private key BLOB in memory.

BCRYPT_INTERFACE_VERSION

Contains version information for a programmatic interface for a CNG provider.

BCRYPT_KEY_BLOB

Is the base structure for all CNG key BLOBs.

BCRYPT_KEY_DATA_BLOB_HEADER

Used to contain information about a key data BLOB.

BCRYPT_KEY_LENGTHS_STRUCT

Defines the range of key sizes that are supported by the provider.

BCRYPT_MULTI_HASH_OPERATION

A BCRYPT_MULTI_HASH_OPERATION structure defines a single operation in a multi-hash operation.

BCRYPT_MULTI_OBJECT_LENGTH_STRUCT

The BCRYPT_MULTI_OBJECT_LENGTH_STRUCT structure contains information to determine the size of the pbHashObject
buffer for the BCryptCreateMultiHash function.
BCRYPT_OAEP_PADDING_INFO

Used to provide options for the Optimal Asymmetric Encryption Padding (OAEP) scheme.

BCRYPT_OID

Contains information about a DER-encoded object identifier (OID).

BCRYPT_OID_LIST

Used to contain a collection of BCRYPT_OID structures. Use this structure with the BCRYPT_HASH_OID_LIST property to
retrieve the list of hashing object identifiers (OIDs) that have been encoded by using Distinguished Encoding Rules (DER)
encoding.

BCRYPT_PKCS1_PADDING_INFO

Used to provide options for the PKCS

BCRYPT_PROVIDER_NAME

Contains the name of a CNG provider.

BCRYPT_PSS_PADDING_INFO

Used to provide options for the Probabilistic Signature Scheme (PSS) padding scheme.

BCRYPT_RSAKEY_BLOB

Used as a header for an RSA public key or private key BLOB in memory.

BCryptBuffer

BCryptBufferDesc

BLOBHEADER

Indicates a key's BLOB type and the algorithm that the key uses.

CATALOG_INFO

The CATALOG_INFO structure contains the name of a catalog file. This structure is used by the
CryptCATCatalogInfoFromContext function.

CENTRAL_ACCESS_POLICY

Represents a central access policy that contains a set of central access policy entries.

CENTRAL_ACCESS_POLICY_ENTRY

Represents a central access policy entry containing a list of security descriptors and staged security descriptors.
CERT_ACCESS_DESCRIPTION

The CERT_ACCESS_DESCRIPTION structure is a member of a CERT_AUTHORITY_INFO_ACCESS structure.

CERT_ALT_NAME_ENTRY

Contains an alternative name in one of a variety of name forms.

CERT_ALT_NAME_INFO

The CERT_ALT_NAME_INFO structure is used in encoding and decoding extensions for subject or issuer certificates, Certificate
Revocation Lists (CRLs), and Certificate Trust Lists (CTLs).

CERT_AUTHORITY_INFO_ACCESS

Represents authority information access and subject information access certificate extensions and specifies how to access
additional information and services for the subject or the issuer of a certificate.

CERT_AUTHORITY_KEY_ID_INFO

Identifies the key used to sign a certificate or certificate revocation list (CRL).

CERT_AUTHORITY_KEY_ID2_INFO

The CERT_AUTHORITY_KEY_ID2_INFO structure identifies the key used to sign a certificate or CRL.

CERT_BASIC_CONSTRAINTS_INFO

The CERT_BASIC_CONSTRAINTS_INFO structure contains information that indicates whether the certified subject can act as a
certification authority (CA), an end entity, or both.

CERT_BASIC_CONSTRAINTS2_INFO

The CERT_BASIC_CONSTRAINTS2_INFO structure contains information indicating whether the certified subject can act as a CA
or an end entity. If the subject can act as a CA, a certification path length constraint can also be specified.

CERT_BIOMETRIC_DATA

Contains information about biometric data.

CERT_BIOMETRIC_EXT_INFO

Contains a set of biometric information.

CERT_CHAIN_CONTEXT

Contains an array of simple certificate chains and a trust status structure that indicates summary validity data on all of the
connected simple chains.

CERT_CHAIN_ELEMENT

The CERT_CHAIN_ELEMENT structure is a single element in a simple certificate chain.

CERT_CHAIN_ENGINE_CONFIG

Sets parameters for building a non-default certificate chain engine. The engine used determines the ways that certificate
chains are built.

CERT_CHAIN_FIND_ISSUER_PARA

Contains information used in the CertFindChainInStore function to build certificate chains.

CERT_CHAIN_PARA

The CERT_CHAIN_PARA structure establishes the searching and matching criteria to be used in building a certificate chain.

CERT_CHAIN_POLICY_PARA

Contains information used in CertVerifyCertificateChainPolicy to establish policy criteria for the verification of certificate chains.

CERT_CHAIN_POLICY_STATUS

Holds certificate chain status information returned by the CertVerifyCertificateChainPolicy function when the certificate chains
are validated.

CERT_CONTEXT

Contains both the encoded and decoded representations of a certificate.

CERT_CREATE_CONTEXT_PARA

Defines additional values that can be used when calling the CertCreateContext function.

CERT_CREDENTIAL_INFO

The CERT_CREDENTIAL_INFO structure contains a reference to a certificate.

CERT_CRL_CONTEXT_PAIR

The CERT_CRL_CONTEXT_PAIR structure contains a certificate context and an associated CRL context.

CERT_DH_PARAMETERS

Contains parameters associated with a Diffie/Hellman public key algorithm.

CERT_DSS_PARAMETERS

Contains parameters associated with a Digital Signature Standard (DSS) public key algorithm.

CERT_ECC_SIGNATURE

Contains the r and s values for an Elliptic Curve Digital Signature Algorithm (ECDSA) signature.

CERT_EXTENSION

The CERT_EXTENSION structure contains the extension information for a certificate, Certificate Revocation List (CRL) or
Certificate Trust List (CTL).
CERT_EXTENSIONS

The CERT_EXTENSIONS structure contains an array of extensions.

CERT_GENERAL_SUBTREE

The CERT_GENERAL_SUBTREE structure is used in CERT_NAME_CONSTRAINTS_INFO structure. This structure provides the
identity of a certificate that can be included or excluded.

CERT_HASHED_URL

Contains a hashed URL.

CERT_ID

Is used as a flexible means of uniquely identifying a certificate.

CERT_INFO

Contains the information of a certificate.

CERT_ISSUER_SERIAL_NUMBER

Acts as a unique identifier of a certificate containing the issuer and issuer's serial number for a certificate.

CERT_KEY_ATTRIBUTES_INFO

The CERT_KEY_ATTRIBUTES_INFO structure contains optional additional information about the public key being certified.

CERT_KEY_CONTEXT

Contains data associated with a CERT_KEY_CONTEXT_PROP_ID property.

CERT_KEY_USAGE_RESTRICTION_INFO

The CERT_KEY_USAGE_RESTRICTION_INFO structure contains restrictions imposed on the usage of a certificate's public key.
This includes purposes for use of the key and policies under which the key can be used.

CERT_KEYGEN_REQUEST_INFO

Contains information stored in the Netscape key generation request. The subject and subject public key BLOBs are encoded.

CERT_LDAP_STORE_OPENED_PARA

Used with the CertOpenStore function when the CERT_STORE_PROV_LDAP provider is specified by using the
CERT_LDAP_STORE_OPENED_FLAG flag to specify both the existing LDAP session to use to perform the query as well as the
LDAP query string.

CERT_LOGOTYPE_AUDIO

Contains information about an audio logotype.

CERT_LOGOTYPE_AUDIO_INFO

Contains more detailed information about an audio logotype.

CERT_LOGOTYPE_DATA

Contains logotype data.

CERT_LOGOTYPE_DETAILS

Contains additional information about a logotype.

CERT_LOGOTYPE_EXT_INFO

Contains a set of logotype information.

CERT_LOGOTYPE_IMAGE

Contains information about an image logotype.

CERT_LOGOTYPE_IMAGE_INFO

Contains more detailed information about an image logotype.

CERT_LOGOTYPE_INFO

Contains information about logotype data.

CERT_LOGOTYPE_REFERENCE

Contains logotype reference information.

CERT_NAME_CONSTRAINTS_INFO

The CERT_NAME_CONSTRAINTS_INFO structure contains information about certificates that are specifically permitted or
excluded from trust.

CERT_NAME_INFO

Contains subject or issuer names.

CERT_NAME_VALUE

Contains a relative distinguished name (RDN) attribute value.

CERT_OR_CRL_BLOB

Encapsulates certificates for use with Internet Key Exchange messages.

CERT_OR_CRL_BUNDLE

Encapsulates an array of certificates for use with Internet Key Exchange messages.

CERT_OTHER_LOGOTYPE_INFO

Contains information about logo types that are not predefined.

CERT_PAIR

The CERT_PAIR structure contains a certificate and its pair cross certificate.

CERT_PHYSICAL_STORE_INFO

Contains information on physical certificate stores.

CERT_POLICIES_INFO

The CERT_POLICIES_INFO structure contains an array of CERT_POLICY_INFO.

CERT_POLICY_CONSTRAINTS_INFO

The CERT_POLICY_CONSTRAINTS_INFO structure contains established policies for accepting certificates as trusted.

CERT_POLICY_ID

The CERT_POLICY_ID structure contains a list of certificate policies that the certificate expressly supports, together with
optional qualifier information pertaining to these policies.

CERT_POLICY_INFO

The CERT_POLICY_INFO structure contains an object identifier (OID) specifying a policy and an optional array of policy
qualifiers.

CERT_POLICY_MAPPING

Contains a mapping between issuer domain and subject domain policy OIDs.

CERT_POLICY_MAPPINGS_INFO

The CERT_POLICY_MAPPINGS_INFO structure provides mapping between the policy OIDs of two domains.

CERT_POLICY_QUALIFIER_INFO

The CERT_POLICY_QUALIFIER_INFO structure contains an object identifier (OID) specifying the qualifier and qualifier-specific
supplemental information.

CERT_PRIVATE_KEY_VALIDITY

The CERT_PRIVATE_KEY_VALIDITY structure indicates a valid time span for the private key corresponding to a certificate's
public key.

CERT_PUBLIC_KEY_INFO

Contains a public key and its algorithm.

CERT_QC_STATEMENT

Represents a single statement in a sequence of one or more statements for inclusion in a Qualified Certificate (QC) statements
extension.

CERT_QC_STATEMENTS_EXT_INFO

Contains a sequence of one or more statements that make up the Qualified Certificate (QC) statements extension for a QC.
CERT_RDN

The CERT_RDN structure contains a relative distinguished name (RDN) consisting of an array of CERT_RDN_ATTR structures.

CERT_RDN_ATTR

Contains a single attribute of a relative distinguished name (RDN). A whole RDN is expressed in a CERT_RDN structure that
contains an array of CERT_RDN_ATTR structures.

CERT_REQUEST_INFO

The CERT_REQUEST_INFO structure contains information for a certificate request. The subject, subject public key, and attribute
BLOBs are encoded.

CERT_REVOCATION_CHAIN_PARA

Contains parameters used for building a chain for an independent online certificate status protocol (OCSP) response signer
certificate.

CERT_REVOCATION_CRL_INFO

Contains information updated by a certificate revocation list (CRL) revocation type handler.

CERT_REVOCATION_INFO

Indicates the revocation status of a certificate in a CERT_CHAIN_ELEMENT.

CERT_REVOCATION_PARA

Is passed in calls to the CertVerifyRevocation function to assist in finding the issuer of the context to be verified.

CERT_REVOCATION_STATUS

Contains information on the revocation status of the certificate.

CERT_SELECT_CHAIN_PARA

Contains the parameters used for building and selecting chains.

CERT_SELECT_CRITERIA

Specifies selection criteria that is passed to the CertSelectCertificateChains function.

CERT_SELECT_STRUCT_A

Contains criteria upon which to select certificates that are presented in a certificate selection dialog box. This structure is used
in the CertSelectCertificate function.

CERT_SELECT_STRUCT_W

Contains criteria upon which to select certificates that are presented in a certificate selection dialog box. This structure is used
in the CertSelectCertificate function.
CERT_SELECTUI_INPUT

Used by the CertSelectionGetSerializedBlob function to serialize the certificates contained in a store or an array of certificate
chains. The returned serialized BLOB can be passed to the CredUIPromptForWindowsCredentials function.

CERT_SERVER_OCSP_RESPONSE_CONTEXT

Contains an encoded OCSP response.

CERT_SIGNED_CONTENT_INFO

The CERT_SIGNED_CONTENT_INFO structure contains encoded content to be signed and a BLOB to hold the signature. The
ToBeSigned member is an encoded CERT_INFO, CRL_INFO, CTL_INFO or CERT_REQUEST_INFO.

CERT_SIMPLE_CHAIN

The CERT_SIMPLE_CHAIN structure contains an array of chain elements and a summary trust status for the chain that the
array represents.

CERT_STORE_PROV_FIND_INFO

Used by many of the store provider callback functions.

CERT_STORE_PROV_INFO

Contains information returned by the installed CertDllOpenStoreProv function when a store is opened by using the
CertOpenStore function.

CERT_STRONG_SIGN_PARA

Contains parameters used to check for strong signatures on certificates, certificate revocation lists (CRLs), online certificate
status protocol (OCSP) responses, and PKCS

CERT_STRONG_SIGN_SERIALIZED_INFO

Contains the signature algorithm/hash algorithm and public key algorithm/bit length pairs that can be used for strong
signing.

CERT_SYSTEM_STORE_INFO

The CERT_SYSTEM_STORE_INFO structure contains information used by functions that work with system stores. Currently, no
essential information is contained in this structure.

CERT_SYSTEM_STORE_RELOCATE_PARA

The CERT_SYSTEM_STORE_RELOCATE_PARA structure contains data to be passed to CertOpenStore when that function's
dwFlags parameter is set to CERT_SYSTEM_STORE_RELOCATE_FLAG.

CERT_TEMPLATE_EXT

A certificate template.

CERT_TRUST_LIST_INFO

The CERT_TRUST_LIST_INFO structure that indicates valid usage of a CTL.

CERT_TRUST_STATUS

Contains trust information about a certificate in a certificate chain, summary trust information about a simple chain of
certificates, or summary information about an array of simple chains.

CERT_USAGE_MATCH

Provides criteria for identifying issuer certificates to be used to build a certificate chain.

CERT_VIEWPROPERTIES_STRUCT_A

The CERT_VIEWPROPERTIES_STRUCT structure defines information used when the CertViewProperties function is called to
display a certificate's properties.

CERT_VIEWPROPERTIES_STRUCT_W

The CERT_VIEWPROPERTIES_STRUCT structure defines information used when the CertViewProperties function is called to
display a certificate's properties.

CERT_X942_DH_PARAMETERS

Contains parameters associated with a Diffie-Hellman public key algorithm.

CERT_X942_DH_VALIDATION_PARAMS

Optionally pointed to by a member of the CERT_X942_DH_PARAMETERS structure and contains additional seed information.

CLAIM_SECURITY_ATTRIBUTE_FQBN_VALUE

Specifies the fully qualified binary name.

CLAIM_SECURITY_ATTRIBUTE_OCTET_STRING_VALUE

Specifies the OCTET_STRING value type of the claim security attribute.

CLAIM_SECURITY_ATTRIBUTE_RELATIVE_V1

Defines a resource attribute that is defined in continuous memory for persistence within a serialized security descriptor.

CLAIM_SECURITY_ATTRIBUTE_V1

Defines a security attribute that can be associated with a token or authorization context.

CLAIM_SECURITY_ATTRIBUTES_INFORMATION

Defines the security attributes for the claim.

CMC_ADD_ATTRIBUTES_INFO

Contains certificate attributes to be added to a certificate.

CMC_ADD_EXTENSIONS_INFO

Contains certificate extension control attributes to be added to a certificate.

CMC_DATA_INFO

Provides a means of communicating different pieces of tagged information.

CMC_PEND_INFO

A possible member of a CMC_STATUS_INFO structure.

CMC_RESPONSE_INFO

Provides a means of communicating different pieces of tagged information.

CMC_STATUS_INFO

Contains status information about Certificate Management Messages over CMS.

CMC_TAGGED_ATTRIBUTE

Used in the CMC_DATA_INFO and CMC_RESPONSE_INFO structures.

CMC_TAGGED_CERT_REQUEST

Used in the CMC_TAGGED_REQUEST structure.

CMC_TAGGED_CONTENT_INFO

Used in the CMC_DATA_INFO and CMC_RESPONSE_INFO structures.

CMC_TAGGED_OTHER_MSG

Used in the CMC_DATA_INFO and CMC_RESPONSE_INFO structures.

CMC_TAGGED_REQUEST

Used in the CMC_DATA_INFO structures to request a certificate.

CMS_DH_KEY_INFO

Used with the KP_CMS_DH_KEY_INFO parameter in the CryptSetKeyParam function to contain Diffie-Hellman key information.

CMS_KEY_INFO

Not used.

CMSG_CMS_RECIPIENT_INFO

Used with the CryptMsgGetParam function to get information on a key transport, key agreement, or mail list envelope
message recipient.

CMSG_CMS_SIGNER_INFO

Contains the content of the defined SignerInfo in signed or signed and enveloped messages.
CMSG_CNG_CONTENT_DECRYPT_INFO

Contains all the relevant information passed between CryptMsgControl and object identifier (OID) installable functions for the
import and decryption of a Cryptography API:_Next Generation (CNG) content encryption key (CEK).

CMSG_CONTENT_ENCRYPT_INFO

Contains information shared between the PFN_CMSG_GEN_CONTENT_ENCRYPT_KEY, PFN_CMSG_EXPORT_KEY_TRANS,

PFN_CMSG_EXPORT_KEY_AGREE, and PFN_CMSG_EXPORT_MAIL_LIST functions.

CMSG_CTRL_ADD_SIGNER_UNAUTH_ATTR_PARA

Used to add an unauthenticated attribute to a signer of a signed message.

CMSG_CTRL_DECRYPT_PARA

Contains information used to decrypt an enveloped message for a key transport recipient. This structure is passed to
CryptMsgControl if the dwCtrlType parameter is CMSG_CTRL_DECRYPT.

CMSG_CTRL_DEL_SIGNER_UNAUTH_ATTR_PARA

Used to delete an unauthenticated attribute of a signer of a signed message.

CMSG_CTRL_KEY_AGREE_DECRYPT_PARA

Contains information about a key agreement recipient.

CMSG_CTRL_KEY_TRANS_DECRYPT_PARA

Contains information about a key transport message recipient.

CMSG_CTRL_MAIL_LIST_DECRYPT_PARA

Contains information on a mail list message recipient.

CMSG_CTRL_VERIFY_SIGNATURE_EX_PARA

Contains information used to verify a message signature. It contains the signer index and signer public key.

CMSG_ENVELOPED_ENCODE_INFO

Contains information needed to encode an enveloped message. It is passed to CryptMsgOpenToEncode if the dwMsgType
parameter is CMSG_ENVELOPED.

CMSG_HASHED_ENCODE_INFO

Used with hashed messages. It is passed to the CryptMsgOpenToEncode function if the CryptMsgOpenToEncode function's
dwMsgType parameter is CMSG_ENVELOPED.

CMSG_KEY_AGREE_ENCRYPT_INFO

Contains encryption information applicable to all key agreement recipients of an enveloped message.

CMSG_KEY_AGREE_KEY_ENCRYPT_INFO

Contains the encrypted key for a key agreement recipient of an enveloped message.
CMSG_KEY_AGREE_RECIPIENT_ENCODE_INFO

Contains information about a message recipient that is using key agreement key management.

CMSG_KEY_AGREE_RECIPIENT_INFO

Contains information used for key agreement algorithms.

CMSG_KEY_TRANS_ENCRYPT_INFO

Contains encryption information for a key transport recipient of enveloped data.

CMSG_KEY_TRANS_RECIPIENT_ENCODE_INFO

Contains encoded key transport information for a message recipient.

CMSG_KEY_TRANS_RECIPIENT_INFO

The CMSG_KEY_TRANS_RECIPIENT_INFO structure contains information used in key transport algorithms.

CMSG_MAIL_LIST_ENCRYPT_INFO

Contains encryption information for a mailing list recipient of enveloped data.

CMSG_MAIL_LIST_RECIPIENT_ENCODE_INFO

The CMSG_MAIL_LIST_RECIPIENT_ENCODE_INFO structure is used with previously distributed symmetric keys for decrypting
the content key encryption key (KEK).

CMSG_MAIL_LIST_RECIPIENT_INFO

Contains information used for previously distributed symmetric key-encryption keys (KEK).

CMSG_RC2_AUX_INFO

Contains the bit length of the key for RC2 encryption algorithms.

CMSG_RC4_AUX_INFO

The CMSG_RC4_AUX_INFO structure contains the bit length of the key for RC4 encryption algorithms. The
pvEncryptionAuxInfo member in CMSG_ENVELOPED_ENCODE_INFO can be set to point to an instance of this structure.

CMSG_RECIPIENT_ENCODE_INFO

Contains information a message recipient's content encryption key management type.

CMSG_RECIPIENT_ENCRYPTED_KEY_ENCODE_INFO

Contains information on a message receiver used to decrypt the session key needed to decrypt the message contents.

CMSG_RECIPIENT_ENCRYPTED_KEY_INFO

The CMSG_RECIPIENT_ENCRYPTED_KEY_INFO structure contains information used for an individual key agreement recipient.
CMSG_SIGNED_ENCODE_INFO

Contains information to be passed to CryptMsgOpenToEncode if dwMsgType is CMSG_SIGNED.

CMSG_SIGNER_ENCODE_INFO

Contains signer information. It is passed to CryptMsgCountersign, CryptMsgCountersignEncoded, and optionally to

CryptMsgOpenToEncode as a member of the CMSG_SIGNED_ENCODE_INFO structure, if the dwMsgType parameter is
CMSG_SIGNED.

CMSG_SIGNER_INFO

The CMSG_SIGNER_INFO structure contains the content of the PKCS

CMSG_SP3_COMPATIBLE_AUX_INFO

Contains information needed for SP3 compatible encryption.

CMSG_STREAM_INFO

Used to enable stream processing of data rather than single block processing.

CREDENTIAL_ATTRIBUTEA

The CREDENTIAL_ATTRIBUTE structure contains an application-defined attribute of the credential. An attribute is a keyword-
value pair. It is up to the application to define the meaning of the attribute.

CREDENTIAL_ATTRIBUTEW

The CREDENTIAL_ATTRIBUTE structure contains an application-defined attribute of the credential. An attribute is a keyword-
value pair. It is up to the application to define the meaning of the attribute.

CREDENTIAL_TARGET_INFORMATIONA

The CREDENTIAL_TARGET_INFORMATION structure contains the target computer's name, domain, and tree.

CREDENTIAL_TARGET_INFORMATIONW

The CREDENTIAL_TARGET_INFORMATION structure contains the target computer's name, domain, and tree.

CREDENTIALA

The CREDENTIAL structure contains an individual credential.

CREDENTIALW

The CREDENTIAL structure contains an individual credential.

CREDSSP_CRED

Specifies authentication data for both Schannel and Negotiate security packages.

CREDUI_INFOA

The CREDUI_INFO structure is used to pass information to the CredUIPromptForCredentials function that creates a dialog box
used to obtain credentials information.
CREDUI_INFOW

The CREDUI_INFO structure is used to pass information to the CredUIPromptForCredentials function that creates a dialog box
used to obtain credentials information.

CREDUIWIN_MARSHALED_CONTEXT

Specifies credential information that has been serialized by using the ICredentialProvider::SetSerialization method.

CRL_CONTEXT

The CRL_CONTEXT structure contains both the encoded and decoded representations of a certificate revocation list (CRL). CRL
contexts returned by any CryptoAPI function must be freed by calling the CertFreeCRLContext function.

CRL_DIST_POINT

Identifies a single certificate revocation list (CRL) distribution point that a certificate user can reference to determine whether
certificates have been revoked.

CRL_DIST_POINT_NAME

Identifies a location from which the CRL can be obtained.

CRL_DIST_POINTS_INFO

Contains a list of certificate revocation list (CRL) distribution points a certificate user can reference to determine whether the
certificate has been revoked.

CRL_ENTRY

Contains information about a single revoked certificate. It is a member of a CRL_INFO structure.

CRL_FIND_ISSUED_FOR_PARA

Contains the certificate contexts of both a subject and a certificate issuer.

CRL_INFO

Contains the information of a certificate revocation list (CRL).

CRL_ISSUING_DIST_POINT

Contains information about the kinds of certificates listed in a certificate revocation list (CRL).

CROSS_CERT_DIST_POINTS_INFO

Provides information used to update dynamic cross certificates.

CRYPT_AES_128_KEY_STATE

Specifies the 128-bit symmetric key information for an Advanced Encryption Standard (AES) cipher.

CRYPT_AES_256_KEY_STATE

Specifies the 256-bit symmetric key information for an Advanced Encryption Standard (AES) cipher.
CRYPT_ALGORITHM_IDENTIFIER

Specifies an algorithm used to encrypt a private key.

CRYPT_ATTRIBUTE

The CRYPT_ATTRIBUTE structure specifies an attribute that has one or more values.

CRYPT_ATTRIBUTE_TYPE_VALUE

Contains a single attribute value. The Value member's CRYPT_OBJID_BLOB is encoded.

CRYPT_ATTRIBUTES

Contains an array of attributes.

CRYPT_BIT_BLOB

Contains a set of bits represented by an array of bytes.

CRYPT_BLOB_ARRAY

Contains an array of CRYPT_DATA_BLOB structures.

CRYPT_CONTENT_INFO

Contains data encoded in the PKCS

CRYPT_CONTENT_INFO_SEQUENCE_OF_ANY

Contains information representing the Netscape certificate sequence of certificates.

CRYPT_CONTEXT_CONFIG

Contains configuration information for a CNG context.

CRYPT_CONTEXT_FUNCTION_CONFIG

Contains configuration information for a cryptographic function of a CNG context.

CRYPT_CONTEXT_FUNCTION_PROVIDERS

Contains a set of cryptographic function providers for a CNG configuration context.

CRYPT_CONTEXT_FUNCTIONS

Contains a set of cryptographic functions for a CNG configuration context.

CRYPT_CONTEXTS

Contains a set of CNG configuration context identifiers.

CRYPT_CREDENTIALS

Contains information about credentials that can be passed as optional input to a remote object retrieval function such as
CryptRetrieveObjectByUrl or CryptGetTimeValidObject.

CRYPT_DECODE_PARA

Used by the CryptDecodeObjectEx function to provide access to memory allocation and memory freeing callback functions.

CRYPT_DECRYPT_MESSAGE_PARA

The CRYPT_DECRYPT_MESSAGE_PARA structure contains information for decrypting messages.

CRYPT_DEFAULT_CONTEXT_MULTI_OID_PARA

Used with the CryptInstallDefaultContext function to contain an array of object identifier strings.

CRYPT_ECC_CMS_SHARED_INFO

Represents key-encryption key information when using Elliptic Curve Cryptography (ECC) in the Cryptographic Message
Syntax (CMS) EnvelopedData content type.

CRYPT_ENCODE_PARA

Used by the CryptEncodeObjectEx function to provide access to memory allocation and memory freeing callback functions.

CRYPT_ENCRYPT_MESSAGE_PARA

Contains information used to encrypt messages.

CRYPT_ENCRYPTED_PRIVATE_KEY_INFO

Contains the information in a PKCS

CRYPT_ENROLLMENT_NAME_VALUE_PAIR

Used to create certificate requests on behalf of a user.

CRYPT_GET_TIME_VALID_OBJECT_EXTRA_INFO

Contains optional extra information that can be passed to the CryptGetTimeValidObject function in the pExtraInfo parameter.

CRYPT_HASH_MESSAGE_PARA

Contains data for hashing messages.

CRYPT_IMAGE_REF

Contains information about a CNG provider module.

CRYPT_IMAGE_REG

Contains image registration information about a CNG provider.

CRYPT_INTEGER_BLOB

The CryptoAPI CRYPT_INTEGER_BLOB structure is used for an arbitrary array of bytes. It is declared in Wincrypt.h and
provides flexibility for objects that can contain various data types.

CRYPT_INTEGER_BLOB

The CryptoAPI CRYPT_INTEGER_BLOB structure is used for an arbitrary array of bytes. It is declared in Wincrypt.h and
provides flexibility for objects that can contain various data types.

CRYPT_INTERFACE_REG

Used to contain information about the type of interface supported by a CNG provider.

CRYPT_KEY_PROV_INFO

The CRYPT_KEY_PROV_INFO structure contains information about a key container within a cryptographic service provider
(CSP).

CRYPT_KEY_PROV_PARAM

Contains information about a key container parameter.

CRYPT_KEY_SIGN_MESSAGE_PARA

Contains information about the cryptographic service provider (CSP) and algorithms used to sign a message.

CRYPT_KEY_VERIFY_MESSAGE_PARA

Contains information needed to verify signed messages without a certificate for the signer.

CRYPT_MASK_GEN_ALGORITHM

Identifies the algorithm used to generate an RSA PKCS

CRYPT_OBJECT_LOCATOR_PROVIDER_TABLE

Contains pointers to functions implemented by an object location provider.

CRYPT_OID_FUNC_ENTRY

Contains an object identifier (OID) and a pointer to its related function.

CRYPT_OID_INFO

Contains information about an object identifier (OID).

CRYPT_PASSWORD_CREDENTIALSA

Contains the user name and password credentials to be used in the CRYPT_CREDENTIALS structure as optional input to a
remote object retrieval function such as CryptRetrieveObjectByUrl or CryptGetTimeValidObject.

CRYPT_PASSWORD_CREDENTIALSW

Contains the user name and password credentials to be used in the CRYPT_CREDENTIALS structure as optional input to a
remote object retrieval function such as CryptRetrieveObjectByUrl or CryptGetTimeValidObject.
CRYPT_PKCS12_PBE_PARAMS

Contains parameters used to create an encryption key, initialization vector (IV), or Message Authentication Code (MAC) key
for a PKCS

CRYPT_PKCS8_EXPORT_PARAMS

Identifies the private key and a callback function to encrypt the private key. CRYPT_PKCS8_EXPORT_PARAMS is used as a
parameter to the CryptExportPKCS8Ex function, which exports a private key in PKCS

CRYPT_PKCS8_IMPORT_PARAMS

Contains a PKCS

CRYPT_PRIVATE_KEY_INFO

Contains a clear-text private key in the PrivateKey field (DER encoded). CRYPT_PRIVATE_KEY_INFO contains the information in
a PKCS

CRYPT_PROPERTY_REF

Contains information about a CNG context property.

CRYPT_PROVIDER_CERT

Provides information about a provider certificate.

CRYPT_PROVIDER_DATA

Used to pass data between WinVerifyTrust and trust providers.

CRYPT_PROVIDER_DEFUSAGE

Used by the WintrustGetDefaultForUsage function to retrieve callback information for a provider's default usage.

CRYPT_PROVIDER_FUNCTIONS

Defines the functions used by a cryptographic service provider (CSP) for WinTrust operations.

CRYPT_PROVIDER_PRIVDATA

Contains private data to be used by a provider.

CRYPT_PROVIDER_REF

Contains information about a cryptographic interface that a provider supports.

CRYPT_PROVIDER_REFS

Contains a collection of provider references.

CRYPT_PROVIDER_REG

Used to contain registration information for a CNG provider.

CRYPT_PROVIDER_REGDEFUSAGE

Used by the WintrustAddDefaultForUsage function to register callback information about a provider's default usage.

CRYPT_PROVIDER_SGNR

Provides information about a signer or countersigner.

CRYPT_PROVIDER_SIGSTATE

Is used to communicate between policy providers and Wintrust.

CRYPT_PROVIDERS

Contains information about the registered CNG providers.

CRYPT_PROVUI_DATA

Provides user interface (UI) data for a provider. This structure is used by the CRYPT_PROVUI_FUNCS structure.

CRYPT_PROVUI_FUNCS

Provides information about the user interface (UI) functions of a provider. This structure is used by the
CRYPT_PROVIDER_FUNCTIONS structure.

CRYPT_PSOURCE_ALGORITHM

Identifies the algorithm and (optionally) the value of the label for an RSAES-OAEP key encryption.

CRYPT_RC2_CBC_PARAMETERS

Contains information used with szOID_RSA_RC2CBC encryption.

CRYPT_REGISTER_ACTIONID

Provides information about the functions of a provider.

CRYPT_RETRIEVE_AUX_INFO

Contains optional information to pass to the CryptRetrieveObjectByUrl function.

CRYPT_RSA_SSA_PSS_PARAMETERS

Contains the parameters for an RSA PKCS

CRYPT_RSAES_OAEP_PARAMETERS

Contains the parameters for an RSAES-OAEP key encryption.

CRYPT_SEQUENCE_OF_ANY

Contains an arbitrary list of encoded BLOBs.

CRYPT_SIGN_MESSAGE_PARA

The CRYPT_SIGN_MESSAGE_PARA structure contains information for signing messages using a specified signing certificate
context.

CRYPT_SMART_CARD_ROOT_INFO

Contains the smart card and session IDs associated with a certificate context.

CRYPT_SMIME_CAPABILITIES

Contains a prioritized array of supported capabilities.

CRYPT_SMIME_CAPABILITY

The CRYPT_SMIME_CAPABILITY structure specifies a single capability and its associated parameters. Single capabilities are
grouped together into a list of CRYPT_SMIME_CAPABILITIES which can specify a prioritized list of capability preferences.

CRYPT_TIME_STAMP_REQUEST_INFO

Used for time stamping.

CRYPT_TIMESTAMP_ACCURACY

Is used by the CRYPT_TIMESTAMP_INFO structure to represent the accuracy of the time deviation around the UTC time at
which the time stamp token was created by the Time Stamp Authority (TSA).

CRYPT_TIMESTAMP_CONTEXT

Contains both the encoded and decoded representations of a time stamp token.

CRYPT_TIMESTAMP_INFO

Contains a signed data content type in Cryptographic Message Syntax (CMS) format.

CRYPT_TIMESTAMP_PARA

Defines additional parameters for the time stamp request.

CRYPT_TIMESTAMP_REQUEST

Defines a time stamp request structure that corresponds to the Abstract Syntax Notation One (ASN.1) definition of a
TimeStampReq type.

CRYPT_TIMESTAMP_RESPONSE

Is used internally to encapsulate an Abstract Syntax Notation One (ASN.1) Distinguished Encoding Rules (DER) encoded
response.

CRYPT_TRUST_REG_ENTRY

Identifies a provider function by DLL name and function name.

CRYPT_URL_INFO

Contains information about groupings of URLs.

CRYPT_VERIFY_CERT_SIGN_STRONG_PROPERTIES_INFO

Contains the length, in bits, of the public key and the names of the signing and hashing algorithms used for strong signing.

CRYPT_VERIFY_MESSAGE_PARA

The CRYPT_VERIFY_MESSAGE_PARA structure contains information needed to verify signed messages.

CRYPT_X942_OTHER_INFO

The CRYPT_X942_OTHER_INFO structure contains additional key generation information.

CRYPT_XML_ALGORITHM

Specifies the algorithm used to sign or transform the message.

CRYPT_XML_ALGORITHM_INFO

Contains algorithm information.

CRYPT_XML_BLOB

Contains an arbitrary array of bytes.

CRYPT_XML_CRYPTOGRAPHIC_INTERFACE

Exposes the implemented CryptXML functions.

CRYPT_XML_DATA_BLOB

Contains XML encoded data.

CRYPT_XML_DATA_PROVIDER

Specifies the interface to the XML data provider.

CRYPT_XML_DOC_CTXT

Defines document context information.

CRYPT_XML_ISSUER_SERIAL

Contains an X.509 issued distinguished name�serial number pair.

CRYPT_XML_KEY_DSA_KEY_VALUE

Defines a Digital Signature Algorithm (DSA) key value. The CRYPT_XML_KEY_DSA_KEY_VALUE structure is used as an element
of the key value union in the CRYPT_XML_KEY_VALUE structure.

CRYPT_XML_KEY_ECDSA_KEY_VALUE

Defines an Elliptic Curve Digital Signature Algorithm (ECDSA) key value. The CRYPT_XML_KEY_ECDSA_KEY_VALUE structure is
used as an element of the key value union in the CRYPT_XML_KEY_VALUE structure.
CRYPT_XML_KEY_INFO

Encapsulates key information data.

CRYPT_XML_KEY_INFO_ITEM

Encapsulates key information data that corresponds to a KeyInfo element. The KeyInfo element enables the recipient to obtain
the key needed to validate the signature.

CRYPT_XML_KEY_RSA_KEY_VALUE

Defines an RSA key value. The CRYPT_XML_KEY_RSA_KEY_VALUE structure is used as element of the key value union in the
CRYPT_XML_KEY_VALUE structure.

CRYPT_XML_KEY_VALUE

Contains a single public key that may be useful in validating the signature.

CRYPT_XML_KEYINFO_PARAM

Is used by the CryptXmlSign function to specify the members of the KeyInfo element to be encoded.

CRYPT_XML_OBJECT

Describes an Object element in the signature.

CRYPT_XML_PROPERTY

Contains information about a CryptXML property.

CRYPT_XML_REFERENCE

Contains information used to populate the Reference element.

CRYPT_XML_REFERENCES

Defines an array of CRYPT_XML_REFERENCE structures.

CRYPT_XML_SIGNATURE

Contains information used to populate the Signature element.

CRYPT_XML_SIGNED_INFO

Describes an XML encoded SignedInfo element.

CRYPT_XML_STATUS

Returns information about the signature validation status, summary status information about a SignedInfo element, or
summary status information about an array of Reference elements.

CRYPT_XML_TRANSFORM_CHAIN_CONFIG

Contains application defined transforms that are allowed for use in the XML digital signature.
CRYPT_XML_TRANSFORM_INFO

Contains information that is used when applying the data transform.

CRYPT_XML_X509DATA

Represents the sequence of choices in the X509Data element.

CRYPT_XML_X509DATA_ITEM

Represents X.509 data that is to be encoded in an X509Data named element.

CRYPTCATATTRIBUTE

The CRYPTCATATTRIBUTE structure defines a catalog attribute. This structure is used by the CryptCATEnumerateAttr and
CryptCATEnumerateCatAttr functions.

CRYPTCATCDF

Contains information used to create a signed catalog file (.cat) from a catalog definition file (CDF).

CRYPTCATMEMBER

The CRYPTCATMEMBER structure provides information about a catalog member. This structure is used by the
CryptCATGetMemberInfo and CryptCATEnumerateAttr functions.

CRYPTCATSTORE

Represents a catalog file.

CRYPTNET_URL_CACHE_FLUSH_INFO

Contains expiry information used by the Cryptnet URL Cache (CUC) service to maintain a URL cache entry.

CRYPTNET_URL_CACHE_PRE_FETCH_INFO

Contains update information used by the Cryptnet URL Cache (CUC) service to maintain a URL cache entry.

CRYPTNET_URL_CACHE_RESPONSE_INFO

Contains response information used by the Cryptnet URL Cache (CUC) service to maintain a URL cache entry.

CRYPTO_SETTINGS

Indicates disabled cryptographic settings.

CRYPTPROTECT_PROMPTSTRUCT

Provides the text of a prompt and information about when and where that prompt is to be displayed when using the
CryptProtectData and CryptUnprotectData functions.

CRYPTUI_CERT_MGR_STRUCT

Contains information about a certificate manager dialog box.

CRYPTUI_INITDIALOG_STRUCT

Supports the CRYPTUI_VIEWCERTIFICATE_STRUCT structure.

CRYPTUI_VIEWCERTIFICATE_STRUCTA

Contains information about a certificate to view. This structure is used in the CryptUIDlgViewCertificate function.

CRYPTUI_VIEWCERTIFICATE_STRUCTW

Contains information about a certificate to view. This structure is used in the CryptUIDlgViewCertificate function.

CRYPTUI_WIZ_DIGITAL_SIGN_BLOB_INFO

Contains information about the public key BLOB used by the CryptUIWizDigitalSign function.

CRYPTUI_WIZ_DIGITAL_SIGN_CERT_PVK_INFO

Contains information about the PVK file that contains the certificates used by the CryptUIWizDigitalSign function.

CRYPTUI_WIZ_DIGITAL_SIGN_CONTEXT

Used with the CryptUIWizDigitalSign function to contain information about a BLOB.

CRYPTUI_WIZ_DIGITAL_SIGN_EXTENDED_INFO

Used with the CRYPTUI_WIZ_DIGITAL_SIGN_INFO structure to contain extended information about a signature.

CRYPTUI_WIZ_DIGITAL_SIGN_INFO

Contains information about digital signing.

CRYPTUI_WIZ_DIGITAL_SIGN_PVK_FILE_INFO

Used with the CRYPTUI_WIZ_DIGITAL_SIGN_INFO structure to contain information about the PVK file used by the digital
signature wizard.

CRYPTUI_WIZ_DIGITAL_SIGN_STORE_INFO

Contains information about the certificate store used by the digital signature wizard.

CRYPTUI_WIZ_EXPORT_CERTCONTEXT_INFO

Contains information that controls the operation of the CryptUIWizExport function when a certificate is the object being
exported.

CRYPTUI_WIZ_EXPORT_INFO

Contains information that controls the operation of the CryptUIWizExport function.

CRYPTUI_WIZ_IMPORT_SRC_INFO

Contains the subject to import into the CryptUIWizImport function.

CTL_ANY_SUBJECT_INFO

Contains a SubjectAlgorithm to be matched in the certificate trust list (CTL) and the SubjectIdentifier to be matched in one of
the CTL entries in calls to CertFindSubjectInCTL.

CTL_CONTEXT

The CTL_CONTEXT structure contains both the encoded and decoded representations of a CTL.

CTL_ENTRY

An element of a certificate trust list (CTL).

CTL_FIND_SUBJECT_PARA

Contains data used by CertFindCTLInStore with a dwFindType parameter of CTL_FIND_SUBJECT to find a Certificate Trust List
(CTL).

CTL_FIND_USAGE_PARA

A member of the CTL_FIND_SUBJECT_PARA structure and it is used by CertFindCTLInStore.

CTL_INFO

Contains the information stored in a Certificate Trust List (CTL).

CTL_MODIFY_REQUEST

Contains a request to modify a certificate trust list (CTL). This structure is used in the CertModifyCertificatesToTrust function.

CTL_USAGE

Contains an array of object identifiers (OIDs) for Certificate Trust List (CTL) extensions.

CTL_USAGE_MATCH

Provides parameters for finding certificate trust lists (CTL) used to build a certificate chain.

CTL_VERIFY_USAGE_PARA

The CTL_VERIFY_USAGE_PARA structure contains parameters used by CertVerifyCTLUsage to establish the validity of a CTL's
usage.

CTL_VERIFY_USAGE_STATUS

Contains information about a Certificate Trust List (CTL) returned by CertVerifyCTLUsage.

DHPRIVKEY_VER3

Contains information specific to the particular private key contained in the key BLOB.

DHPUBKEY

Contains information specific to the particular Diffie-Hellman public key contained in the key BLOB.
DHPUBKEY_VER3

Contains information specific to the particular public key contained in the key BLOB.

DIAGNOSTIC_DATA_EVENT_BINARY_STATS

A resource that describes this binary and the amount of diagnostic data it has sent.

DIAGNOSTIC_DATA_EVENT_CATEGORY_DESCRIPTION

A resource that represents a category, defined by an identifier and a name. A category is an organizational construct to
categorize records for a given producer. For example, "Browsing Data" could be a category for the producer "Microsoft Edge".

DIAGNOSTIC_DATA_EVENT_PRODUCER_DESCRIPTION

A resource that represents a producer. A Producer is an OS component, application or service that emits events. For example,
“Microsoft Edge” is the Producer ID for the Microsoft Edge browser.

DIAGNOSTIC_DATA_EVENT_TAG_DESCRIPTION

A resource that describes a tag, defined by the tag's name and its description.

DIAGNOSTIC_DATA_EVENT_TAG_STATS

A resource that includes a privacy tag and how many events have this privacy tag.

DIAGNOSTIC_DATA_EVENT_TRANSCRIPT_CONFIGURATION

Event transcript configuration details such as maximum storage size and hours of data history.

DIAGNOSTIC_DATA_GENERAL_STATS

This resource contains general statistics about a set of diagnostic data records.

DIAGNOSTIC_DATA_RECORD

This resource describes an individual diagnostic data record (event).

DIAGNOSTIC_DATA_SEARCH_CRITERIA

This resource contains details of the search criteria when fetching a diagnostic data record.

DIAGNOSTIC_REPORT_DATA

This resource contains information about a diagnostic report.

DIAGNOSTIC_REPORT_PARAMETER

Resource that describes the parameters for an error report.

DIAGNOSTIC_REPORT_SIGNATURE

This resource describes the signature for a diagnostic report.

DOMAIN_PASSWORD_INFORMATION

Contains information about a domain's password policy, such as the minimum length for passwords and how unique
passwords must be.

DSSSEED

Holds the seed and counter values that can be used to verify the primes of the DSS public key.

EFFPERM_RESULT_LIST

Lists the effective permissions.

ENCRYPTED_CREDENTIALW

Represents an encrypted credential.

ENUM_SERVICE_STATUS_PROCESSA

Contains the name of a service in a service control manager database and information about the service. It is used by the
EnumServicesStatusEx function.

ENUM_SERVICE_STATUS_PROCESSW

Contains the name of a service in a service control manager database and information about the service. It is used by the
EnumServicesStatusEx function.

ENUM_SERVICE_STATUSA

Contains the name of a service in a service control manager database and information about that service. It is used by the
EnumDependentServices and EnumServicesStatus functions.

ENUM_SERVICE_STATUSW

Contains the name of a service in a service control manager database and information about that service. It is used by the
EnumDependentServices and EnumServicesStatus functions.

EV_EXTRA_CERT_CHAIN_POLICY_PARA

Specifies the parameters that are passed in for EV policy validation. Applications use this structure to pass hints to the API that
indicate which of the policy qualifier flags of the extended validation certificates are important to the application.

EV_EXTRA_CERT_CHAIN_POLICY_STATUS

Contains policy flags returned from a call to the CertVerifyCertificateChainPolicy function.

EXPLICIT_ACCESS_A

Defines access control information for a specified trustee.

EXPLICIT_ACCESS_W

Defines access control information for a specified trustee.

GENERIC_MAPPING

Defines the mapping of generic access rights to specific and standard access rights for an object.

HMAC_INFO

The HMAC_INFO structure specifies the hash algorithm and the inner and outer strings that are to be used to calculate the
HMAC hash.

HTTPSPolicyCallbackData

Holds policy information used in the verification of Secure Sockets Layer (SSL) client/server certificate chains.

INHERITED_FROMA

Provides information about an object's inherited access control entry (ACE).

INHERITED_FROMW

Provides information about an object's inherited access control entry (ACE).

KERB_ADD_BINDING_CACHE_ENTRY_EX_REQUEST

Allows the user to bind to a specific domain controller (DC), overriding the Kerberos domain binding cache.

KERB_ADD_BINDING_CACHE_ENTRY_REQUEST

Specifies a message to add a binding cache entry.

KERB_ADD_CREDENTIALS_REQUEST

Specifies a message to add, remove, or replace an extra server credential for a logon session.

KERB_ADD_CREDENTIALS_REQUEST_EX

Specifies a message to add, remove, or replace an extra server credential for a logon session, and the service principal names
(SPNs) to be associated with that credential.

KERB_BINDING_CACHE_ENTRY_DATA

Specifies the data for the binding cache entry.

KERB_CERTIFICATE_HASHINFO

Provides the payload information of the certificate hash.

KERB_CERTIFICATE_INFO

Contains the certificate information.

KERB_CERTIFICATE_LOGON

Contains information about a smart card logon session.

KERB_CERTIFICATE_S4U_LOGON

Contains information about the certificate for a service for user (S4U) logon.

KERB_CERTIFICATE_UNLOCK_LOGON

Contains information used to unlock a workstation that has been locked during an interactive smart card logon session.

KERB_CHANGEPASSWORD_REQUEST

Contains information used to change a password.

KERB_CLEANUP_MACHINE_PKINIT_CREDS_REQUEST

Cleans up the PKINIT device credentials from the computer.

KERB_CRYPTO_KEY

Contains information about a Kerberos cryptographic session key.

KERB_EXTERNAL_NAME

Contains information about an external name.

KERB_EXTERNAL_TICKET

Contains information about an external ticket.

KERB_INTERACTIVE_LOGON

Contains information about an interactive logon session.

KERB_INTERACTIVE_PROFILE

The KERB_INTERACTIVE_PROFILE structure contains information about an interactive logon profile. This structure is used by
the LsaLogonUser function.

KERB_INTERACTIVE_UNLOCK_LOGON

Contains information used to unlock a workstation that has been locked during an interactive logon session.

KERB_PURGE_BINDING_CACHE_REQUEST

Deletes the request for the binding cache.

KERB_PURGE_TKT_CACHE_REQUEST

Contains information used to delete entries from the ticket cache.

KERB_QUERY_BINDING_CACHE_REQUEST

Contains information used to query the binding cache.

KERB_QUERY_BINDING_CACHE_RESPONSE

Contains the results of querying the binding cache.

KERB_QUERY_DOMAIN_EXTENDED_POLICIES_REQUEST

Contains information used to query the domain for the extended policies.

KERB_QUERY_DOMAIN_EXTENDED_POLICIES_RESPONSE

Contains the results of querying for the extended policies of the specified domain.

KERB_QUERY_TKT_CACHE_REQUEST

Contains information used to query the ticket cache.

KERB_QUERY_TKT_CACHE_RESPONSE

Contains the results of querying the ticket cache.

KERB_RETRIEVE_TKT_REQUEST

Contains information used to retrieve a ticket.

KERB_RETRIEVE_TKT_RESPONSE

Contains the response from retrieving a ticket.

KERB_S4U_LOGON

Contains information about a service for user (S4U) logon.

KERB_SMART_CARD_LOGON

Contains information about a smart card logon session.

KERB_SMART_CARD_UNLOCK_LOGON

Contains information used to unlock a workstation that has been locked during a smart card logon session.

KERB_TICKET_CACHE_INFO

Contains information about a cached Kerberos ticket. The Kerberos ticket is defined in Internet RFC 4120. For more
information, see http://www.ietf.org.

KERB_TICKET_LOGON

Contains profile information for a network logon.

KERB_TICKET_PROFILE

The KERB_TICKET_PROFILE structure contains information about an interactive logon profile. This structure is returned by
LsaLogonUser.
KERB_TICKET_UNLOCK_LOGON

Contains information to unlock a workstation.

KeyCredentialManagerInfo

Data structure returned from KeyCredentialManagerGetInformation.

LSA_AUTH_INFORMATION

The LSA_AUTH_INFORMATION structure contains authentication information for a trusted domain.

LSA_DISPATCH_TABLE

Contains pointers to the Local Security Authority (LSA) functions that Windows authentication packages can call.

LSA_ENUMERATION_INFORMATION

The LSA_ENUMERATION_INFORMATION structure is used with the LsaEnumerateAccountsWithUserRight function to return a

pointer to a SID.

LSA_FOREST_TRUST_BINARY_DATA

Contains binary data used in Local Security Authority forest trust operations.

LSA_FOREST_TRUST_COLLISION_INFORMATION

Contains information about Local Security Authority forest trust collisions.

LSA_FOREST_TRUST_COLLISION_RECORD

Contains information about a Local Security Authority forest trust collision.

LSA_FOREST_TRUST_DOMAIN_INFO

Contains identifying information for a domain.

LSA_FOREST_TRUST_INFORMATION

Contains Local Security Authority forest trust information.

LSA_FOREST_TRUST_RECORD

Represents a Local Security Authority forest trust record.

LSA_LAST_INTER_LOGON_INFO

Contains information about a logon session.

LSA_OBJECT_ATTRIBUTES

The LSA_OBJECT_ATTRIBUTES structure is used with the LsaOpenPolicy function to specify the attributes of the connection to
the Policy object.
LSA_REFERENCED_DOMAIN_LIST

The LSA_REFERENCED_DOMAIN_LIST structure contains information about the domains referenced in a lookup operation.

LSA_SECPKG_FUNCTION_TABLE

Contains pointers to the LSA functions that a security package can call. The Local Security Authority (LSA) passes this structure
to a security package when it calls the package's SpInitialize function.

LSA_STRING

Used by Local Security Authority (LSA) functions to specify an ANSI string.

LSA_TOKEN_INFORMATION_NULL

Used in cases where a non-authenticated system access is needed.

LSA_TOKEN_INFORMATION_V1

Contains information an authentication package can place in a Version 2 Windows token object and has superceded
LSA_TOKEN_INFORMATION_V1.

LSA_TOKEN_INFORMATION_V3

Adds claim support to the LSA token and contains information an authentication package can place in a Version 3 Windows
token object and has superceded LSA_TOKEN_INFORMATION_V1.

LSA_TRANSLATED_NAME

Used with the LsaLookupSids function to return information about the account identified by a SID.

LSA_TRANSLATED_SID

Used with the LsaLookupNames function to return information about the SID that identifies an account.

LSA_TRANSLATED_SID2

Contains SIDs that are retrieved based on account names.

LSA_TRUST_INFORMATION

Identifies a domain.

LSA_UNICODE_STRING

The LSA_UNICODE_STRING structure is used by various Local Security Authority (LSA) functions to specify a Unicode string.

LUID_AND_ATTRIBUTES

Represents a locally unique identifier (LUID) and its attributes.

MS_ADDINFO_BLOB

Provides additional information for in-memory BLOB subject types.

MS_ADDINFO_CATALOGMEMBER

Provides additional information for catalog member subject types.

MS_ADDINFO_FLAT

Provides additional information about flat or end-to-end subject types.

MSA_INFO_0

Specifies information about a managed service account.

MSV1_0_INTERACTIVE_LOGON

Contains information about an interactive logon.

MSV1_0_INTERACTIVE_PROFILE

The MSV1_0_INTERACTIVE_PROFILE structure contains information about an interactive logon profile. This structure is used
by the LsaLogonUser function.

MSV1_0_LM20_LOGON

Contains logon information used in network logons.

MSV1_0_LM20_LOGON_PROFILE

Contains information about a network logon session.

MSV1_0_SUBAUTH_LOGON

Used by subauthentication DLLs.

MSV1_0_SUBAUTH_REQUEST

Contains information to pass to a subauthentication package.

MSV1_0_SUBAUTH_RESPONSE

Contains the response from a subauthentication package.

MSV1_0_SUPPLEMENTAL_CREDENTIAL

The MSV1_0_SUPPLEMENTAL_CREDENTIAL structure is used to pass credentials into MSV1_0 from Kerberos or custom
authentication package.

NCRYPT_ALLOC_PARA

Enables you to specify custom functions that can be used to allocate and free data.

NCRYPT_KEY_BLOB_HEADER

Contains a key BLOB.

NCRYPT_PROTECT_STREAM_INFO

Is used by the NCryptStreamOpenToProtect and NCryptStreamOpenToUnprotect functions to pass blocks of processed data
to your application.

NCRYPT_SUPPORTED_LENGTHS

Used with the NCRYPT_LENGTHS_PROPERTY property to contain length information for a key.

NCRYPT_UI_POLICY

Used with the NCRYPT_UI_POLICY_PROPERTY property to contain strong key user interface information for a key.

NCryptAlgorithmName

Used to contain information about a CNG algorithm.

NCryptKeyName

Used to contain information about a CNG key.

NCryptProviderName

Used to contain the name of a CNG key storage provider.

NETCONNECTINFOSTRUCT

The NETCONNECTINFOSTRUCT structure contains information about the performance of a network. It is used by the
NPGetConnectionPerformance function.

NETLOGON_LOGON_IDENTITY_INFO

Used to pass information about a user for logon subauthentication.

NETRESOURCEA

The following structure contains information about a network resource. It is used by several of the network provider functions,
including NPOpenEnum and NPAddConnection.

NETRESOURCEW

The following structure contains information about a network resource. It is used by several of the network provider functions,
including NPOpenEnum and NPAddConnection.

NOTIFYADD

The NOTIFYADD structure contains the details of a network connect operation. It is used by the AddConnectNotify function.

NOTIFYCANCEL

The NOTIFYCANCEL structure contains the details of a network disconnect operation. It is used by the CancelConnectNotify
function.
NOTIFYINFO

The NOTIFYINFO structure contains status information about a network connect or disconnect operation. It is used by the
AddConnectNotify and CancelConnectNotify functions.

OBJECT_TYPE_LIST

Identifies an object type element in a hierarchy of object types.

OBJECTS_AND_NAME_A

Contains a string that identifies a trustee by name and additional strings that identify the object types of an object-specific
access control entry (ACE).

OBJECTS_AND_NAME_W

Contains a string that identifies a trustee by name and additional strings that identify the object types of an object-specific
access control entry (ACE).

OBJECTS_AND_SID

Contains a security identifier (SID) that identifies a trustee and GUIDs that identify the object types of an object-specific access
control entry (ACE).

OCSP_BASIC_RESPONSE_ENTRY

Contains the current certificate status for a single certificate.

OCSP_BASIC_RESPONSE_INFO

Contains a basic online certificate status protocol (OCSP) response as specified by RFC 2560.

OCSP_BASIC_REVOKED_INFO

Contains the reason a certificate was revoked.

OCSP_BASIC_SIGNED_RESPONSE_INFO

Contains a basic online certificate status protocol (OCSP) response with a signature.

OCSP_CERT_ID

Contains information to identify a certificate in an online certificate status protocol (OCSP) request or response.

OCSP_REQUEST_ENTRY

Contains information about a single certificate in an online certificate status protocol (OCSP) request.

OCSP_REQUEST_INFO

Contains information for an online certificate status protocol (OCSP) request as specified by RFC 2560.

OCSP_RESPONSE_INFO

Indicates the success or failure of the corresponding online certificate status protocol (OCSP) request. For successful requests,
it contains the type and value of response information.
OCSP_SIGNATURE_INFO

Contains a signature for an online certificate status protocol (OCSP) request or response.

OCSP_SIGNED_REQUEST_INFO

Contains information for an online certificate status protocol (OCSP) request with optional signature information.

OLD_LARGE_INTEGER

Is used to represent a 64-bit signed integer value as two 32-bit integers.

OPENCARD_SEARCH_CRITERIAA

The OPENCARD_SEARCH_CRITERIA structure is used by the SCardUIDlgSelectCard function in order to recognize cards that
meet the requirements set forth by the caller. You can, however, call SCardUIDlgSelectCard without using this structure.

OPENCARD_SEARCH_CRITERIAW

The OPENCARD_SEARCH_CRITERIA structure is used by the SCardUIDlgSelectCard function in order to recognize cards that
meet the requirements set forth by the caller. You can, however, call SCardUIDlgSelectCard without using this structure.

OPENCARDNAME_EXA

The OPENCARDNAME_EX structure contains the information that the SCardUIDlgSelectCard function uses to initialize a smart
card Select Card dialog box.

OPENCARDNAME_EXW

The OPENCARDNAME_EX structure contains the information that the SCardUIDlgSelectCard function uses to initialize a smart
card Select Card dialog box.

OPENCARDNAMEA

Contains the information that the GetOpenCardName function uses to initialize a smart card Select Card dialog box.

OPENCARDNAMEW

Contains the information that the GetOpenCardName function uses to initialize a smart card Select Card dialog box.

PKU2U_CERT_BLOB

Specifies PKU2U certificate data.

PKU2U_CERTIFICATE_S4U_LOGON

Specifies a certificate used for S4U logon.

PKU2U_CREDUI_CONTEXT

Specifies a PKU2U client context.

POLICY_ACCOUNT_DOMAIN_INFO

Used to set and query the name and SID of the system's account domain.
POLICY_AUDIT_EVENTS_INFO

The POLICY_AUDIT_EVENTS_INFO structure is used to set and query the system's auditing rules.

POLICY_AUDIT_SID_ARRAY

Specifies an array of SID structures that represent Windows users or groups.

POLICY_DNS_DOMAIN_INFO

The POLICY_DNS_DOMAIN_INFO structure is used to set and query Domain Name System (DNS) information about the
primary domain associated with a Policy object.

POLICY_LSA_SERVER_ROLE_INFO

Used to set and query the role of an LSA server.

POLICY_MODIFICATION_INFO

The POLICY_MODIFICATION_INFO structure is used to query information about the creation time and last modification of the
LSA database.

POLICY_PRIMARY_DOMAIN_INFO

The PolicyPrimaryDomainInformation value and POLICY_PRIMARY_DOMAIN_INFO structure are obsolete. Use the
PolicyDnsDomainInformation and POLICY_DNS_DOMAIN_INFO structure instead.

PRIVILEGE_SET

Specifies a set of privileges.

PROCESS_MACHINE_INFORMATION

Specifies the architecture of a process and if that architecture of code can run in user mode, kernel mode, and/or under
WoW64 on the host operating system.

PROV_ENUMALGS

Used with the CryptGetProvParam function when the PP_ENUMALGS parameter is retrieved to contain information about an
algorithm supported by a cryptographic service provider (CSP).

PROV_ENUMALGS_EX

Used with the CryptGetProvParam function when the PP_ENUMALGS_EX parameter is retrieved to contain information about
an algorithm supported by a cryptographic service provider (CSP).

QUERY_SERVICE_CONFIGA

Contains configuration information for an installed service. It is used by the QueryServiceConfig function.

QUERY_SERVICE_CONFIGW

Contains configuration information for an installed service. It is used by the QueryServiceConfig function.
QUERY_SERVICE_LOCK_STATUSA

Contains information about the lock status of a service control manager database. It is used by the QueryServiceLockStatus
function.

QUERY_SERVICE_LOCK_STATUSW

Contains information about the lock status of a service control manager database. It is used by the QueryServiceLockStatus
function.

QUOTA_LIMITS

Describes the amount of system resources available to a user.

REMOTE_NAME_INFOA

The REMOTE_NAME_INFO structure contains information about the remote form of a universal name. It is used by the
NPGetUniversalName function.

REMOTE_NAME_INFOW

The REMOTE_NAME_INFO structure contains information about the remote form of a universal name. It is used by the
NPGetUniversalName function.

ROOT_INFO_LUID

Contains a locally unique identifier (LUID) for Cryptographic Smart Card Root Information.

RSAPUBKEY

The RSAPUBKEY structure contains information specific to the particular public key contained in the key BLOB.

SAFER_CODE_PROPERTIES_V1

Contains code image information and criteria to be checked on the code image.

SAFER_CODE_PROPERTIES_V2

Contains code image information and criteria to be checked on the code image.

SAFER_HASH_IDENTIFICATION

Represents a hash identification rule.

SAFER_IDENTIFICATION_HEADER

SAFER_IDENTIFICATION_HEADER structure is used as the header for the SAFER_PATHNAME_IDENTIFICATION,

SAFER_HASH_IDENTIFICATION, and SAFER_URLZONE_IDENTIFICATION structures.

SAFER_PATHNAME_IDENTIFICATION

Represents a path identification rule.

SAFER_URLZONE_IDENTIFICATION

Represents a URL zone identification rule.

SC_ACTION

Represents an action that the service control manager can perform.

SCARD_ATRMASK

Used by the SCardLocateCardsByATR function to locate cards.

SCARD_READERSTATEA

Used by functions for tracking smart cards within readers.

SCARD_READERSTATEW

Used by functions for tracking smart cards within readers.

SCESVC_ANALYSIS_INFO

Contains the analysis information.

SCESVC_ANALYSIS_LINE

The SCESVC_ANALYSIS_LINE structure contains the key, value, and value length for a specific line specified by an
SCESVC_ANALYSIS_INFO structure.

SCESVC_CALLBACK_INFO

The SCESVC_CALLBACK_INFO structure contains an opaque database handle and callback function pointers to query, set, and
free information.

SCESVC_CONFIGURATION_INFO

The SCESVC_CONFIGURATION_INFO structure provides configuration information for a service. This structure is used by the
PFSCE_QUERY_INFO and PFSCE_SET_INFO functions when the configuration information is specified.

SCESVC_CONFIGURATION_LINE

The SCESVC_CONFIGURATION_LINE structure contains information about a line of configuration data. It is used by the
SCESVC_CONFIGURATION_INFO structure.

SCH_CRED_PUBLIC_CERTCHAIN

The SCH_CRED_PUBLIC_CERTCHAIN structure contains a single certificate. A certification chain can be built from this
certificate.

SCH_CRED_SECRET_PRIVKEY

Contains private key information needed to authenticate a client or server.

SCH_CREDENTIALS

Contains the data for an Schannel credential.

SCHANNEL_ALERT_TOKEN

Generates a Secure Sockets Layer Protocol (SSL) or Transport Layer Security Protocol (TLS) alert to be sent to the target of a
call to either the InitializeSecurityContext (Schannel) function or the AcceptSecurityContext (Schannel) function.

SCHANNEL_ALG

The SCHANNEL_ALG structure contains algorithm and key size information. It is used as the structure passed as pbData in
CryptSetKeyParam when dwParam is set to KP_SCHANNEL_ALG.

SCHANNEL_CERT_HASH

Contains the hash store data for the certificate that Schannel uses.

SCHANNEL_CERT_HASH_STORE

Contains the hash store data for the certificate that Schannel uses in kernel-mode.

SCHANNEL_CLIENT_SIGNATURE

Specifies a client signature when a call to the InitializeSecurityContext (Schannel) function cannot access the private key for a
client certificate (in this case, the function returns SEC_I_SIGNATURE_NEEDED).

SCHANNEL_CRED

Contains the data for an Schannel credential.

SCHANNEL_SESSION_TOKEN

Specifies whether reconnections are enabled for an authentication session created by calling either the InitializeSecurityContext
(Schannel) function or the AcceptSecurityContext (Schannel) function.

SEC_CHANNEL_BINDINGS

Specifies channel binding information for a security context.

SEC_WINNT_AUTH_BYTE_VECTOR

Specifies the byte offset and array length of the data in an authentication structure.

SEC_WINNT_AUTH_CERTIFICATE_DATA

Specifies serialized certificate information.

SEC_WINNT_AUTH_DATA

Specifies authentication data.

SEC_WINNT_AUTH_DATA_PASSWORD

Specifies a serialized password.

SEC_WINNT_AUTH_IDENTITY_A

Allows you to pass a particular user name and password to the run-time library for the purpose of authentication.
SEC_WINNT_AUTH_IDENTITY_EX2

Contains information about an authentication identity.

SEC_WINNT_AUTH_IDENTITY_EXA

SEC_WINNT_AUTH_IDENTITY_EXW

SEC_WINNT_AUTH_IDENTITY_W

Allows you to pass a particular user name and password to the run-time library for the purpose of authentication.

SEC_WINNT_AUTH_PACKED_CREDENTIALS

Specifies serialized credentials.

SEC_WINNT_AUTH_PACKED_CREDENTIALS_EX

Specifies serialized credentials and a list of security packages that support the credentials.

SEC_WINNT_AUTH_SHORT_VECTOR

Specifies the offset and number of characters in an array of USHORT values.

SEC_WINNT_CREDUI_CONTEXT

Specifies unserialized credential information.

SEC_WINNT_CREDUI_CONTEXT_VECTOR

Specifies the offset and size of the credential context data in a SEC_WINNT_CREDUI_CONTEXT structure.

SecBuffer

Describes a buffer allocated by a transport application to pass to a security package.

SecBufferDesc

The SecBufferDesc structure describes an array of SecBuffer structures to pass from a transport application to a security
package.

SECPKG_BYTE_VECTOR

Specifies the byte vector information.

SECPKG_CALL_INFO

Contains information about a currently executing call.

SECPKG_CLIENT_INFO

The SECPKG_CLIENT_INFO structure holds information about a security package's client. This structure is used by the
GetClientInfo function.
SECPKG_CONTEXT_THUNKS

The SECPKG_CONTEXT_THUNKS structure contains information about QueryContextAttributes (General) calls to be executed
in LSA mode.This structure is used by the SpGetExtendedInformation and SpSetExtendedInformation functions.

SECPKG_CREDENTIAL

Specifies the credentials.

SECPKG_DLL_FUNCTIONS

The SECPKG_DLL_FUNCTIONS structure contains pointers to the LSA functions that a security package can call while executing
in-process with a client/server application.

SECPKG_EVENT_NOTIFY

The SECPKG_EVENT_NOTIFY structure contains information about security events. This structure is passed to a function
registered to receive event notifications. Event notification functions are registered by calling the RegisterNotification function.

SECPKG_EVENT_PACKAGE_CHANGE

The SECPKG_EVENT_PACKAGE_CHANGE structure contains information about changes in security package availability.

SECPKG_EXTENDED_INFORMATION

The SECPKG_EXTENDED_INFORMATION structure is used to hold information about optional package capabilities.This
structure is used by the SpGetExtendedInformation and SpSetExtendedInformation functions.

SECPKG_EXTRA_OIDS

Contains the object identifiers (OIDs) for the extended security package.

SECPKG_FUNCTION_TABLE

The SECPKG_FUNCTION_TABLE structure contains pointers to the LSA functions that a security package must implement. The
Local Security Authority (LSA) obtains this structure from an SSP/AP DLL when it calls the SpLsaModeInitialize function.

SECPKG_GSS_INFO

A SECPKG_GSS_INFO structure contains information used for GSS-compatible negotiations.

SECPKG_MUTUAL_AUTH_LEVEL

The SECPKG_MUTUAL_AUTH_LEVEL structure contains the authentication level used by a security package.

SECPKG_NEGO2_INFO

Contains extended package information used for NEGO2 negotiations.

SECPKG_PARAMETERS

The SECPKG_PARAMETERS structure contains information about the computer system. This structure is used by the SpInitialize
function.
SECPKG_PRIMARY_CRED

The SECPKG_PRIMARY_CRED structure contains the primary credentials. This structure is used by the LsaApLogonUserEx2 and
SpAcceptCredentials functions.

SECPKG_SERIALIZED_OID

Contains the security package's object identifier (OID).

SECPKG_SHORT_VECTOR

Specifies the short vector information.

SECPKG_SUPPLEMENTAL_CRED

The SECPKG_SUPPLEMENTAL_CRED structure contains supplemental credentials recognized by the security package.

SECPKG_SUPPLEMENTAL_CRED_ARRAY

The SECPKG_SUPPLEMENTAL_CRED_ARRAY structure contains supplemental credentials information. This structure is used by
the LsaApLogonUserEx2 and UpdateCredentials functions.

SECPKG_SUPPLIED_CREDENTIAL

Specifies the supplied credentials.

SECPKG_TARGETINFO

Specifies the target of an authentication request.

SECPKG_USER_FUNCTION_TABLE

The SECPKG_USER_FUNCTION_TABLE structure contains pointers to the functions that a security package implements to
support executing in process with client/server applications. This structure is provided by the SpUserModeInitialize function.

SECPKG_WOW_CLIENT_DLL

Contains the path to the WOW-aware 32-bit DLL.

SecPkgContext_AccessToken

Returns a handle to the access token for the current security context.

SecPkgContext_AuthorityA

The SecPkgContext_Authority structure contains the name of the authenticating authority if one is available.

SecPkgContext_AuthorityW

The SecPkgContext_Authority structure contains the name of the authenticating authority if one is available.

SecPkgContext_Bindings

Specifies a structure that contains channel binding information for a security context.
SecPkgContext_CipherInfo

Cipher info structure. This is returned by SECPKG_ATTR_CIPHER_INFO ulAttribute from the QueryContextAttributes (Schannel)
function.

SecPkgContext_ClientCreds

Specifies client credentials when calling the QueryContextAttributes (CredSSP) function.

SecPkgContext_ClientSpecifiedTarget

Specifies the service principal name (SPN) of the initial target when calling the QueryContextAttributes (Digest) function.

SecPkgContext_ConnectionInfo

The SecPkgContext_ConnectionInfo structure contains protocol and cipher information. This structure is used by the
InitializeSecurityContext (Schannel) function.This attribute is supported only by the Schannel security support provider (SSP).

SecPkgContext_CredentialNameA

Contains the credential name and type.

SecPkgContext_CredInfo

Specifies the type of credentials used to create a client context.

SecPkgContext_DceInfo

The SecPkgContext_DceInfo structure contains authorization data used by DCE services. The QueryContextAttributes
(General) function uses this structure.

SecPkgContext_EapKeyBlock

Contains key data used by the EAP TLS Authentication Protocol.

SecPkgContext_EapPrfInfo

Specifies the pseudorandom function (PRF) and extracts key data used by the Extensible Authentication Protocol (EAP)
Transport Layer Security protocol (TLS) Authentication Protocol.

SecPkgContext_EarlyStart

The SecPkgContext_EarlyStart structure contains information about whether to attempt to use the False Start feature in a
security context.

SecPkgContext_Flags

The SecPkgContext_Flags structure contains information about the flags in the current security context. This structure is
returned by QueryContextAttributes (General).

SecPkgContext_IssuerListInfoEx

The SecPkgContext_IssuerListInfoEx structure holds a list of trusted certification authorities (CAs).

SecPkgContext_KeyInfoA

The SecPkgContext_KeyInfo structure contains information about the session keys used in a security context.

SecPkgContext_KeyInfoW

The SecPkgContext_KeyInfo structure contains information about the session keys used in a security context.

SecPkgContext_KeyingMaterial

The SecPkgContext_KeyingMaterial structure.

SecPkgContext_KeyingMaterialInfo

The SecPkgContext_KeyingMaterialInfo structure contains information about the exportable keying material in a security
context.

SecPkgContext_LastClientTokenStatus

Specifies whether the token from the most recent call to the InitializeSecurityContext function is the last token from the client.

SecPkgContext_Lifespan

The SecPkgContext_Lifespan structure indicates the life span of a security context. The QueryContextAttributes (General)
function uses this structure.

SecPkgContext_NamesA

The SecPkgContext_Names structure indicates the name of the user associated with a security context. The
QueryContextAttributes (General) function uses this structure.

SecPkgContext_NamesW

The SecPkgContext_Names structure indicates the name of the user associated with a security context. The
QueryContextAttributes (General) function uses this structure.

SecPkgContext_NativeNamesA

Contains the client and server principal names.

SecPkgContext_NegoStatus

Specifies the error status of the last attempt to create a client context.

SecPkgContext_NegotiatedTlsExtensions

The SecPkgContext_NegotiatedTlsExtensions structure contains information about the (D)TLS extensions negotiated for the
current (D)TLS connection.

SecPkgContext_NegotiationInfoA

The SecPkgContext_NegotiationInfo structure contains information on the security package that is being set up or has been
set up, and also gives the status on the negotiation to set up the security package.
SecPkgContext_NegotiationInfoW

The SecPkgContext_NegotiationInfo structure contains information on the security package that is being set up or has been
set up, and also gives the status on the negotiation to set up the security package.

SecPkgContext_PasswordExpiry

The SecPkgContext_PasswordExpiry structure contains information about the expiration of a password or other credential
used for the security context. This structure is returned by QueryContextAttributes (General).

SecPkgContext_ProtoInfoA

The SecPkgContext_ProtoInfo structure holds information about the protocol in use.

SecPkgContext_ProtoInfoW

The SecPkgContext_ProtoInfo structure holds information about the protocol in use.

SecPkgContext_SessionAppData

Stores application data for a session context.

SecPkgContext_SessionInfo

Specifies whether the session is a reconnection and retrieves a value that identifies the session.

SecPkgContext_SessionKey

The SecPkgContext_SessionKey structure contains information about the session key used for the security context. This
structure is returned by the QueryContextAttributes (General) function.

SecPkgContext_Sizes

The SecPkgContext_Sizes structure indicates the sizes of important structures used in the message support functions. The
QueryContextAttributes (General) function uses this structure.

SecPkgContext_StreamSizes

Indicates the sizes of the various parts of a stream for use with the message support functions. The QueryContextAttributes
(General) function uses this structure.

SecPkgContext_SubjectAttributes

Returns the security attribute information.

SecPkgContext_SupportedSignatures

Specifies the signature algorithms supported by an Schannel connection.

SecPkgContext_TargetInformation

Returns information about the credential used for the security context.

SecPkgCredentials_Cert

Specifies the certificate credentials. The QueryCredentialsAttributes function uses this structure.
SecPkgCredentials_KdcProxySettingsW

Specifies the Kerberos proxy settings for the credentials.

SecPkgCredentials_NamesA

The SecPkgCredentials_Names structure holds the name of the user associated with a context. The QueryCredentialsAttributes
function uses this structure.

SecPkgCredentials_NamesW

The SecPkgCredentials_Names structure holds the name of the user associated with a context. The QueryCredentialsAttributes
function uses this structure.

SecPkgCredentials_SSIProviderA

The SecPkgCredentials_SSIProvider structure holds the SSI provider information associated with a context. The
QueryCredentialsAttributes function uses this structure.

SecPkgCredentials_SSIProviderW

The SecPkgCredentials_SSIProvider structure holds the SSI provider information associated with a context. The
QueryCredentialsAttributes function uses this structure.

SecPkgInfoA

The SecPkgInfo structure provides general information about a security package, such as its name and capabilities.

SecPkgInfoW

The SecPkgInfo structure provides general information about a security package, such as its name and capabilities.

SECURITY_CAPABILITIES

Defines the security capabilities of the app container.

SECURITY_DESCRIPTOR

Contains the security information associated with an object.

SECURITY_INTEGER

SECURITY_INTEGER is a structure that holds a numeric value. It is used in defining other types.

SECURITY_LOGON_SESSION_DATA

Contains information about a logon session.

SECURITY_OBJECT

Contains the security object information.

SECURITY_PACKAGE_OPTIONS

Specifies information about a security package.

SECURITY_QUALITY_OF_SERVICE

Contains information used to support client impersonation.

SECURITY_STRING

Used as the string interface for kernel operations and is a clone of the UNICODE_STRING structure.

SECURITY_USER_DATA

The SecurityUserData structure contains information about the user of a security support provider/authentication package.
This structure is used by the SpGetUserInfo function.

SecurityFunctionTableA

The SecurityFunctionTable structure is a dispatch table that contains pointers to the functions defined in SSPI.

SecurityFunctionTableW

The SecurityFunctionTable structure is a dispatch table that contains pointers to the functions defined in SSPI.

SERVICE_CONTROL_STATUS_REASON_PARAMSA

Contains service control parameters.

SERVICE_CONTROL_STATUS_REASON_PARAMSW

Contains service control parameters.

SERVICE_DELAYED_AUTO_START_INFO

Contains the delayed auto-start setting of an auto-start service.

SERVICE_DESCRIPTIONA

Contains a service description.

SERVICE_DESCRIPTIONW

Contains a service description.

SERVICE_FAILURE_ACTIONS_FLAG

Contains the failure actions flag setting of a service. This setting determines when failure actions are to be executed.

SERVICE_FAILURE_ACTIONSA

Represents the action the service controller should take on each failure of a service. A service is considered failed when it
terminates without reporting a status of SERVICE_STOPPED to the service controller.

SERVICE_FAILURE_ACTIONSW

Represents the action the service controller should take on each failure of a service. A service is considered failed when it
terminates without reporting a status of SERVICE_STOPPED to the service controller.
SERVICE_LAUNCH_PROTECTED_INFO

Indicates a service protection type.

SERVICE_NOTIFY_2A

Represents service status notification information.

SERVICE_NOTIFY_2W

Represents service status notification information.

SERVICE_PREFERRED_NODE_INFO

Represents the preferred node on which to run a service.

SERVICE_PRESHUTDOWN_INFO

Contains preshutdown settings.

SERVICE_REQUIRED_PRIVILEGES_INFOA

Represents the required privileges for a service.

SERVICE_REQUIRED_PRIVILEGES_INFOW

Represents the required privileges for a service.

SERVICE_SID_INFO

Represents a service security identifier (SID).

SERVICE_STATUS

Contains status information for a service.

SERVICE_STATUS_PROCESS

Contains process status information for a service. The ControlServiceEx, EnumServicesStatusEx, NotifyServiceStatusChange,
and QueryServiceStatusEx functions use this structure.

SERVICE_TABLE_ENTRYA

Specifies the ServiceMain function for a service that can run in the calling process. It is used by the StartServiceCtrlDispatcher
function.

SERVICE_TABLE_ENTRYW

Specifies the ServiceMain function for a service that can run in the calling process. It is used by the StartServiceCtrlDispatcher
function.

SERVICE_TIMECHANGE_INFO

Contains system time change settings.

SERVICE_TRIGGER

Represents a service trigger event. This structure is used by the SERVICE_TRIGGER_INFO structure.

SERVICE_TRIGGER_INFO

Contains trigger event information for a service. This structure is used by the ChangeServiceConfig2 and QueryServiceConfig2
functions.

SERVICE_TRIGGER_SPECIFIC_DATA_ITEM

Contains trigger-specific data for a service trigger event.

SI_ACCESS

Contains information about an access right or default access mask for a securable object.

SI_INHERIT_TYPE

Contains information about how access control entries (ACEs) can be inherited by child objects.

SI_OBJECT_INFO

Used to initialize the access control editor.

SID

Used to uniquely identify users or groups.

SID_AND_ATTRIBUTES

Represents a security identifier (SID) and its attributes.

SID_AND_ATTRIBUTES_HASH

Specifies a hash values for the specified array of security identifiers (SIDs).

SID_IDENTIFIER_AUTHORITY

Represents the top-level authority of a security identifier (SID).

SID_INFO

Contains the list of common names corresponding to the SID structures returned by ISecurityInformation2::LookupSids.

SID_INFO_LIST

Contains a list of SID_INFO structures.

SIP_ADD_NEWPROVIDER

Defines a subject interface package (SIP). This structure is used by the CryptSIPAddProvider function.
SIP_CAP_SET_V2

Defines the capabilities of a subject interface package (SIP).

SIP_CAP_SET_V3

Defines the capabilities of a subject interface package (SIP).

SIP_DISPATCH_INFO

Contains a set of function pointers assigned by the CryptSIPLoad function that your application uses to perform subject
interface package (SIP) operations.

SIP_INDIRECT_DATA

Contains the digest of the hashed subject information.

SIP_SUBJECTINFO

Specifies subject information data to the subject interface package (SIP) APIs.

SL_ACTIVATION_INFO_HEADER

Specifies the product activation information.

SL_AD_ACTIVATION_INFO

Specifies information used for the retail or Active Directory phone activation of a license.

SL_LICENSING_STATUS

Represents the licensing status.

SL_NONGENUINE_UI_OPTIONS

Specifies an application that displays a dialog box when the SLIsGenuineLocal function indicates that an installation is not
genuine.

SPC_INDIRECT_DATA_CONTENT

Is used in Authenticode signatures to store the digest and other attributes of the signed file.

SR_SECURITY_DESCRIPTOR

The SR_SECURITY_DESCRIPTOR structure contains information about the security privileges of the user.

SSL_F12_EXTRA_CERT_CHAIN_POLICY_STATUS

The SSL_F12_EXTRA_CERT_CHAIN_POLICY_STATUS structure checks if any certificates in the chain have weak cryptography
and checks if a third party root certificate is compliant with the Microsoft Root Program requirements.

SYSTEM_ALARM_ACE

The SYSTEM_ALARM_ACE structure is reserved for future use.

SYSTEM_ALARM_CALLBACK_ACE

The SYSTEM_ALARM_CALLBACK_ACE structure is reserved for future use.

SYSTEM_ALARM_CALLBACK_OBJECT_ACE

The SYSTEM_ALARM_CALLBACK_OBJECT_ACE structure is reserved for future use.

SYSTEM_ALARM_OBJECT_ACE

The SYSTEM_ALARM_OBJECT_ACE structure is reserved for future use.

SYSTEM_AUDIT_ACE

Defines an access control entry (ACE) for the system access control list (SACL) that specifies what types of access cause
system-level notifications.

SYSTEM_AUDIT_CALLBACK_ACE

The SYSTEM_AUDIT_CALLBACK_ACE structure defines an access control entry for the system access control list that specifies
what types of access cause system-level notifications.

SYSTEM_AUDIT_CALLBACK_OBJECT_ACE

The SYSTEM_AUDIT_CALLBACK_OBJECT_ACE structure defines an access control entry for a system access control list.

SYSTEM_AUDIT_OBJECT_ACE

Defines an access control entry (ACE) for a system access control list (SACL).

SYSTEM_MANDATORY_LABEL_ACE

Defines an access control entry (ACE) for the system access control list (SACL) that specifies the mandatory access level and
policy for a securable object.

SYSTEM_RESOURCE_ATTRIBUTE_ACE

Defines an access control entry (ACE) for the system access control list (SACL) that specifies the system resource attributes for
a securable object.

SYSTEM_SCOPED_POLICY_ID_ACE

Defines an access control entry (ACE) for the system access control list (SACL) that specifies the scoped policy identifier for a
securable object.

TLS_PARAMETERS

Indicates TLS parameter restrictions.

TOKEN_ACCESS_INFORMATION

Specifies all the information in a token that is necessary to perform an access check.

TOKEN_APPCONTAINER_INFORMATION

Specifies all the information in a token that is necessary for an app container.
TOKEN_AUDIT_POLICY

Specifies the per user audit policy for a token.

TOKEN_CONTROL

Contains information that identifies an access token.

TOKEN_DEFAULT_DACL

Specifies a discretionary access control list (DACL).

TOKEN_DEVICE_CLAIMS

Defines the device claims for the token.

TOKEN_ELEVATION

Indicates whether a token has elevated privileges.

TOKEN_GROUPS

Contains information about the group security identifiers (SIDs) in an access token.

TOKEN_GROUPS_AND_PRIVILEGES

Contains information about the group security identifiers (SIDs) and privileges in an access token.

TOKEN_LINKED_TOKEN

Contains a handle to a token. This token is linked to the token being queried by the GetTokenInformation function or set by
the SetTokenInformation function.

TOKEN_MANDATORY_LABEL

Specifies the mandatory integrity level for a token.

TOKEN_MANDATORY_POLICY

Specifies the mandatory integrity policy for a token.

TOKEN_ORIGIN

Contains information about the origin of the logon session.

TOKEN_OWNER

Contains the default owner security identifier (SID) that will be applied to newly created objects.

TOKEN_PRIMARY_GROUP

Specifies a group security identifier (SID) for an access token.

TOKEN_PRIVILEGES

Contains information about a set of privileges for an access token.

TOKEN_SOURCE

Identifies the source of an access token.

TOKEN_STATISTICS

Contains information about an access token.

TOKEN_USER

Identifies the user associated with an access token.

TOKEN_USER_CLAIMS

Defines the user claims for the token.

TOKENBINDING_IDENTIFIER

Contains the information for representing a token binding identifier that results from a token binding message exchange.

TOKENBINDING_KEY_TYPES

Contains all of the combinations of types of token binding keys that a client device or server supports.

TOKENBINDING_RESULT_DATA

Contains data about the result of generating a token binding or verifying one of the token bindings in a token binding
message.

TOKENBINDING_RESULT_LIST

Contains the results for each of the token bindings that TokenBindingVerifyMessage verified.

TRUSTED_DOMAIN_AUTH_INFORMATION

The TRUSTED_DOMAIN_AUTH_INFORMATION structure is used to retrieve authentication information for a trusted domain.
The LsaQueryTrustedDomainInfo function uses this structure when its InformationClass parameter is set to
TrustedDomainAuthInformation.

TRUSTED_DOMAIN_FULL_INFORMATION

Used to retrieve complete information about a trusted domain.

TRUSTED_DOMAIN_INFORMATION_EX

Used to retrieve extended information about a trusted domain.

TRUSTED_DOMAIN_NAME_INFO

Used to query or set the name of a trusted domain.

TRUSTED_PASSWORD_INFO

The TRUSTED_PASSWORD_INFO structure is used to query or set the password for a trusted domain.

TRUSTED_POSIX_OFFSET_INFO

Used to query or set the value used to generate Posix user and group identifiers.

TRUSTEE_A

Identifies the user account, group account, or logon session to which an access control entry (ACE) applies.

TRUSTEE_W

Identifies the user account, group account, or logon session to which an access control entry (ACE) applies.

UNICODE_STRING

Used by various Local Security Authority (LSA) functions to specify a Unicode string.

UNIVERSAL_NAME_INFOA

The UNIVERSAL_NAME_INFO structure contains information about the UNC form of a universal name. It is used by the
NPGetUniversalName function.

UNIVERSAL_NAME_INFOW

The UNIVERSAL_NAME_INFO structure contains information about the UNC form of a universal name. It is used by the
NPGetUniversalName function.

USER_ALL_INFORMATION

Contains information on the session user.

USERNAME_TARGET_CREDENTIAL_INFO

The USERNAME_TARGET_CREDENTIAL_INFO structure contains a reference to a credential.

WIN_CERTIFICATE

This structure encapsulates a signature used in verifying executable files.

WINTRUST_BLOB_INFO

Used when calling WinVerifyTrust to verify a memory BLOB.

WINTRUST_CATALOG_INFO

The WINTRUST_CATALOG_INFO structure is used when calling WinVerifyTrust to verify a member of a Microsoft catalog.

WINTRUST_CERT_INFO

Used when calling WinVerifyTrust to verify a CERT_CONTEXT.

WINTRUST_DATA

Used when calling WinVerifyTrust to pass necessary information into the trust providers.

WINTRUST_FILE_INFO

The WINTRUST_FILE_INFO structure is used when calling WinVerifyTrust to verify an individual file.

WINTRUST_SGNR_INFO

Used when calling WinVerifyTrust to verify a CMSG_SIGNER_INFO structure.

WINTRUST_SIGNATURE_SETTINGS

Can be used to specify the signatures on a file.

WLX_CLIENT_CREDENTIALS_INFO_V1_0

Contains the client credentials returned by a call to WlxQueryClientCredentials or WlxQueryInetConnectorCredentials.

WLX_CLIENT_CREDENTIALS_INFO_V2_0

Contains the client credentials returned by a call to WlxQueryTsLogonCredentials.

WLX_CONSOLESWITCH_CREDENTIALS_INFO_V1_0

Contains the client credentials returned by a call to WlxGetConsoleSwitchCredentials.

WLX_DESKTOP

Used to pass desktop information between your GINA DLL and Winlogon.

WLX_DISPATCH_VERSION_1_0

Defines the format of the Winlogon version 1.0 function dispatch table passed to your GINA DLL in the WlxInitialize call.

WLX_DISPATCH_VERSION_1_1

Defines the format of the Winlogon version 1.1 function dispatch passed to your GINA DLL in the WlxInitialize call.

WLX_DISPATCH_VERSION_1_2

Defines the format of the Winlogon version 1.2 function dispatch table passed to your GINA DLL in the WlxInitialize call.

WLX_DISPATCH_VERSION_1_3

Defines the format of the Winlogon version 1.3 function dispatch table passed to your GINA DLL in the WlxInitialize call.

WLX_DISPATCH_VERSION_1_4

Defines the format of the Winlogon version 1.4 function dispatch table passed to the GINA DLL in the WlxInitialize call.

WLX_MPR_NOTIFY_INFO

Provides identification and authentication information to network providers.

WLX_NOTIFICATION_INFO

This structure stores information about a Winlogon event.

WLX_PROFILE_V1_0

Contains information used for setting up the initial environment.

WLX_PROFILE_V2_0

Contains profile information in addition to the information provided by WLX_PROFILE_V1_0.

WLX_TERMINAL_SERVICES_DATA

Used to provide GINA with Terminal Services user configuration information.

X509Certificate

Represents an X.509 certificate.

 accctrl.h header
7/2/2022 • 2 minutes to read • Edit Online

This header is used by multiple technologies. For more information, see:

Component Object Model (COM)
Security and Identity
accctrl.h contains the following programming interfaces:

Structures

ACTRL_ACCESS_ENTRY_LISTA

Contains a list of access entries.

ACTRL_ACCESS_ENTRY_LISTW

Contains a list of access entries.

ACTRL_ACCESS_ENTRYA

Contains access-control information for a specified trustee. This structure stores information equivalent to the access-control
information stored in an ACE.

ACTRL_ACCESS_ENTRYW

Contains access-control information for a specified trustee. This structure stores information equivalent to the access-control
information stored in an ACE.

ACTRL_ACCESSA

Contains an array of access-control lists for an object and its properties.

ACTRL_ACCESSW

Contains an array of access-control lists for an object and its properties.

ACTRL_PROPERTY_ENTRYA

Contains a list of access-control entries for an object or a specified property on an object.

ACTRL_PROPERTY_ENTRYW

Contains a list of access-control entries for an object or a specified property on an object.

EXPLICIT_ACCESS_A

Defines access control information for a specified trustee.

 EXPLICIT_ACCESS_W

Defines access control information for a specified trustee.

INHERITED_FROMA

Provides information about an object's inherited access control entry (ACE).

INHERITED_FROMW

Provides information about an object's inherited access control entry (ACE).

OBJECTS_AND_NAME_A

Contains a string that identifies a trustee by name and additional strings that identify the object types of an object-specific
access control entry (ACE).

OBJECTS_AND_NAME_W

Contains a string that identifies a trustee by name and additional strings that identify the object types of an object-specific
access control entry (ACE).

OBJECTS_AND_SID

Contains a security identifier (SID) that identifies a trustee and GUIDs that identify the object types of an object-specific access
control entry (ACE).

TRUSTEE_A

Identifies the user account, group account, or logon session to which an access control entry (ACE) applies.

TRUSTEE_W

Identifies the user account, group account, or logon session to which an access control entry (ACE) applies.

Enumerations

ACCESS_MODE

Contains values that indicate how the access rights in an EXPLICIT_ACCESS structure apply to the trustee.

MULTIPLE_TRUSTEE_OPERATION

Contains values that indicate whether a TRUSTEE structure is an impersonation trustee.

PROG_INVOKE_SETTING

Indicates the initial setting of the function used to track the progress of a call to the TreeSetNamedSecurityInfo or
TreeResetNamedSecurityInfo function.

SE_OBJECT_TYPE

Contains values that correspond to the types of Windows objects that support security.
TRUSTEE_FORM

Values that indicate the type of data pointed to by the ptstrName member of the TRUSTEE structure.

TRUSTEE_TYPE

Values that indicate the type of trustee identified by a TRUSTEE structure.

 ACCESS_MODE enumeration (accctrl.h)
7/2/2022 • 2 minutes to read • Edit Online

The ACCESS_MODE enumeration contains values that indicate how the access rights in an EXPLICIT_ACCESS
structure apply to the trustee. Functions such as SetEntriesInAcl and GetExplicitEntriesFromAcl use these values
to set or retrieve information in an access control entry (ACE).

Syntax
typedef enum _ACCESS_MODE {
NOT_USED_ACCESS,
GRANT_ACCESS,
SET_ACCESS,
DENY_ACCESS,
REVOKE_ACCESS,
SET_AUDIT_SUCCESS,
SET_AUDIT_FAILURE
} ACCESS_MODE;

Constants

NOT_USED_ACCESS
Value not used.

GRANT_ACCESS
Indicates an
ACCESS_ALLOWED_ACE structure. The new ACE combines the specified rights with any existing allowed or denied rights of the
trustee.

SET_ACCESS
Indicates an ACCESS_ALLOWED_ACE structure that allows the specified rights.

On input, this value discards any existing access control information for the trustee.

DENY_ACCESS
Indicates an
ACCESS_DENIED_ACE structure that denies the specified rights.

On input, this value denies the specified rights in addition to any currently denied rights of the trustee.

REVOKE_ACCESS
Indicates that all existing ACCESS_ALLOWED_ACE or
SYSTEM_AUDIT_ACE structures for the specified trustee are removed.
 SET_AUDIT_SUCCESS
Indicates a SYSTEM_AUDIT_ACE structure that generates audit messages for successful attempts to use the specified access
rights.

On input, this value combines the specified rights with any existing audited access rights for the trustee.

SET_AUDIT_FAILURE
Indicates a
SYSTEM_AUDIT_ACE structure that generates audit messages for failed attempts to use the specified access rights.

On input, this value combines the specified rights with any existing audited access rights for the trustee.

Requirements

Minimum suppor ted client Windows XP [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Header accctrl.h

See also
ACCESS_ALLOWED_ACE
ACCESS_DENIED_ACE
ACE
Access Control
Authorization Enumerations
EXPLICIT_ACCESS
GetExplicitEntriesFromAcl
SYSTEM_AUDIT_ACE
SetEntriesInAcl
 EXPLICIT_ACCESS_A structure (accctrl.h)
7/2/2022 • 2 minutes to read • Edit Online

The EXPLICIT_ACCESS structure defines access control information for a specified trustee. Access control
functions, such as SetEntriesInAcl and GetExplicitEntriesFromAcl, use this structure to describe the information in
an access control entry(ACE) of an access control list (ACL).

Syntax
typedef struct _EXPLICIT_ACCESS_A {
DWORD grfAccessPermissions;
ACCESS_MODE grfAccessMode;
DWORD grfInheritance;
TRUSTEE_A Trustee;
} EXPLICIT_ACCESS_A, *PEXPLICIT_ACCESS_A, EXPLICIT_ACCESSA, *PEXPLICIT_ACCESSA;

Members
grfAccessPermissions

A set of bit flags that use the ACCESS_MASK format to specify the access rights that an ACE allows, denies, or
audits for the trustee. The functions that use the EXPLICIT_ACCESS structure do not convert, interpret, or
validate the bits in this mask.
grfAccessMode

A value from the ACCESS_MODE enumeration. For a discretionary access control list (DACL), this flag indicates
whether the ACL allows or denies the specified access rights. For a system access control list (SACL), this flag
indicates whether the ACL generates audit messages for successful attempts to use the specified access rights,
or failed attempts, or both. When modifying an existing ACL, you can specify the REVOKE_ACCESS flag to
remove any existing ACEs for the specified trustee.
grfInheritance

A set of bit flags that determines whether other containers or objects can inherit the ACE from the primary
object to which the ACL is attached. The value of this member corresponds to the inheritance portion (low-order
byte) of the AceFlags member of the ACE_HEADER structure. This parameter can be NO_INHERITANCE to
indicate that the ACE is not inheritable; or it can be a combination of the following values.

VA L UE M EA N IN G

Other containers that are contained by the primary object

CONTAINER_INHERIT_ACE inherit the ACE.

Inherit but do not propagate.

INHERIT_NO_PROPAGATE

Inherit only.
INHERIT_ONLY
 The ACE does not apply to the primary object to which the
INHERIT_ONLY_ACE ACL is attached, but objects contained by the primary object
inherit the ACE.

Do not inherit.
NO_INHERITANCE

The OBJECT_INHERIT_ACE and CONTAINER_INHERIT_ACE

NO_PROPAGATE_INHERIT_ACE flags are not propagated to an inherited ACE.

Noncontainer objects contained by the primary object

OBJECT_INHERIT_ACE inherit the ACE.

Both containers and noncontainer objects that are contained

SUB_CONTAINERS_AND_OBJECTS_INHERIT by the primary object inherit the ACE. This flag corresponds
to the combination of the CONTAINER_INHERIT_ACE and
OBJECT_INHERIT_ACE flags.

Other containers that are contained by the primary object

SUB_CONTAINERS_ONLY_INHERIT inherit the ACE. This flag corresponds to the
CONTAINER_INHERIT_ACE flag.

Noncontainer objects contained by the primary object

SUB_OBJECTS_ONLY_INHERIT inherit the ACE. This flag corresponds to the
OBJECT_INHERIT_ACE flag.

Trustee

A TRUSTEE structure that identifies the user, group, or program (such as a Windows service) to which the ACE
applies.

Remarks
NOTE
The accctrl.h header defines EXPLICIT_ACCESS_ as an alias which automatically selects the ANSI or Unicode version of this
function based on the definition of the UNICODE preprocessor constant. Mixing usage of the encoding-neutral alias with
code that not encoding-neutral can lead to mismatches that result in compilation or runtime errors. For more
information, see Conventions for Function Prototypes.

Requirements

Minimum suppor ted client Windows XP [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Header accctrl.h

See also
ACCESS_MASK
ACCESS_MODE
ACE
ACE_HEADER
ACL
BuildExplicitAccessWithName
BuildSecurityDescriptor
GetExplicitEntriesFromAcl
LookupSecurityDescriptorParts
SetEntriesInAcl
TRUSTEE
 EXPLICIT_ACCESS_W structure (accctrl.h)
7/2/2022 • 2 minutes to read • Edit Online

The EXPLICIT_ACCESS structure defines access control information for a specified trustee. Access control
functions, such as SetEntriesInAcl and GetExplicitEntriesFromAcl, use this structure to describe the information in
an access control entry(ACE) of an access control list (ACL).

Syntax
typedef struct _EXPLICIT_ACCESS_W {
DWORD grfAccessPermissions;
ACCESS_MODE grfAccessMode;
DWORD grfInheritance;
TRUSTEE_W Trustee;
} EXPLICIT_ACCESS_W, *PEXPLICIT_ACCESS_W, EXPLICIT_ACCESSW, *PEXPLICIT_ACCESSW;

Members
grfAccessPermissions

A set of bit flags that use the ACCESS_MASK format to specify the access rights that an ACE allows, denies, or
audits for the trustee. The functions that use the EXPLICIT_ACCESS structure do not convert, interpret, or
validate the bits in this mask.
grfAccessMode

A value from the ACCESS_MODE enumeration. For a discretionary access control list (DACL), this flag indicates
whether the ACL allows or denies the specified access rights. For a system access control list (SACL), this flag
indicates whether the ACL generates audit messages for successful attempts to use the specified access rights,
or failed attempts, or both. When modifying an existing ACL, you can specify the REVOKE_ACCESS flag to
remove any existing ACEs for the specified trustee.
grfInheritance

A set of bit flags that determines whether other containers or objects can inherit the ACE from the primary
object to which the ACL is attached. The value of this member corresponds to the inheritance portion (low-order
byte) of the AceFlags member of the ACE_HEADER structure. This parameter can be NO_INHERITANCE to
indicate that the ACE is not inheritable; or it can be a combination of the following values.

VA L UE M EA N IN G

Other containers that are contained by the primary object

CONTAINER_INHERIT_ACE inherit the ACE.

Inherit but do not propagate.

INHERIT_NO_PROPAGATE

Inherit only.
INHERIT_ONLY
 The ACE does not apply to the primary object to which the
INHERIT_ONLY_ACE ACL is attached, but objects contained by the primary object
inherit the ACE.

Do not inherit.
NO_INHERITANCE

The OBJECT_INHERIT_ACE and CONTAINER_INHERIT_ACE

NO_PROPAGATE_INHERIT_ACE flags are not propagated to an inherited ACE.

Noncontainer objects contained by the primary object

OBJECT_INHERIT_ACE inherit the ACE.

Both containers and noncontainer objects that are contained

SUB_CONTAINERS_AND_OBJECTS_INHERIT by the primary object inherit the ACE. This flag corresponds
to the combination of the CONTAINER_INHERIT_ACE and
OBJECT_INHERIT_ACE flags.

Other containers that are contained by the primary object

SUB_CONTAINERS_ONLY_INHERIT inherit the ACE. This flag corresponds to the
CONTAINER_INHERIT_ACE flag.

Noncontainer objects contained by the primary object

SUB_OBJECTS_ONLY_INHERIT inherit the ACE. This flag corresponds to the
OBJECT_INHERIT_ACE flag.

Trustee

A TRUSTEE structure that identifies the user, group, or program (such as a Windows service) to which the ACE
applies.

Remarks
NOTE
The accctrl.h header defines EXPLICIT_ACCESS_ as an alias which automatically selects the ANSI or Unicode version of this
function based on the definition of the UNICODE preprocessor constant. Mixing usage of the encoding-neutral alias with
code that not encoding-neutral can lead to mismatches that result in compilation or runtime errors. For more
information, see Conventions for Function Prototypes.

Requirements

Minimum suppor ted client Windows XP [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Header accctrl.h

See also
ACCESS_MASK
ACCESS_MODE
ACE
ACE_HEADER
ACL
BuildExplicitAccessWithName
BuildSecurityDescriptor
GetExplicitEntriesFromAcl
LookupSecurityDescriptorParts
SetEntriesInAcl
TRUSTEE
 INHERITED_FROMA structure (accctrl.h)
7/2/2022 • 2 minutes to read • Edit Online

The INHERITED_FROM structure provides information about an object's inherited access control entry (ACE).

Syntax
typedef struct _INHERITED_FROMA {
LONG GenerationGap;
LPSTR AncestorName;
} INHERITED_FROMA, *PINHERITED_FROMA;

Members
GenerationGap

Number of levels, or generations, between the object and the ancestor. Set this to zero for an explicit ACE. If the
ancestor cannot be determined for the inherited ACE, set this member to –1.
AncestorName

Name of the ancestor from which the ACE was inherited. For an explicit ACE, set this to NULL .

Remarks
NOTE
The accctrl.h header defines INHERITED_FROM as an alias which automatically selects the ANSI or Unicode version of this
function based on the definition of the UNICODE preprocessor constant. Mixing usage of the encoding-neutral alias with
code that not encoding-neutral can lead to mismatches that result in compilation or runtime errors. For more
information, see Conventions for Function Prototypes.

Requirements

Minimum suppor ted client Windows XP [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Header accctrl.h

See also
FreeInheritedFromArray
GetInheritanceSource
 INHERITED_FROMW structure (accctrl.h)
7/2/2022 • 2 minutes to read • Edit Online

The INHERITED_FROM structure provides information about an object's inherited access control entry (ACE).

Syntax
typedef struct _INHERITED_FROMW {
LONG GenerationGap;
LPWSTR AncestorName;
} INHERITED_FROMW, *PINHERITED_FROMW;

Members
GenerationGap

Number of levels, or generations, between the object and the ancestor. Set this to zero for an explicit ACE. If the
ancestor cannot be determined for the inherited ACE, set this member to –1.
AncestorName

Name of the ancestor from which the ACE was inherited. For an explicit ACE, set this to NULL .

Remarks
NOTE
The accctrl.h header defines INHERITED_FROM as an alias which automatically selects the ANSI or Unicode version of this
function based on the definition of the UNICODE preprocessor constant. Mixing usage of the encoding-neutral alias with
code that not encoding-neutral can lead to mismatches that result in compilation or runtime errors. For more
information, see Conventions for Function Prototypes.

Requirements

Minimum suppor ted client Windows XP [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Header accctrl.h

See also
FreeInheritedFromArray
GetInheritanceSource
 MULTIPLE_TRUSTEE_OPERATION enumeration
(accctrl.h)
7/2/2022 • 2 minutes to read • Edit Online

The MULTIPLE_TRUSTEE_OPERATION enumeration contains values that indicate whether a TRUSTEE

structure is an impersonation trustee.

Syntax
typedef enum _MULTIPLE_TRUSTEE_OPERATION {
NO_MULTIPLE_TRUSTEE,
TRUSTEE_IS_IMPERSONATE
} MULTIPLE_TRUSTEE_OPERATION;

Constants

NO_MULTIPLE_TRUSTEE
The trustee is not an impersonation trustee.

TRUSTEE_IS_IMPERSONATE
The trustee is an impersonation trustee. The pMultipleTrustee member of the TRUSTEE structure points to a trustee for a
server that can impersonate the client trustee.

Requirements

Minimum suppor ted client Windows XP [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Header accctrl.h

See also
Access Control Overview
Authorization Enumerations
TRUSTEE
 OBJECTS_AND_NAME_A structure (accctrl.h)
7/2/2022 • 2 minutes to read • Edit Online

The OBJECTS_AND_NAME structure contains a string that identifies a trustee by name and additional strings
that identify the object types of an object-specific access control entry (ACE).

Syntax
typedef struct _OBJECTS_AND_NAME_A {
DWORD ObjectsPresent;
SE_OBJECT_TYPE ObjectType;
LPSTR ObjectTypeName;
LPSTR InheritedObjectTypeName;
LPSTR ptstrName;
} OBJECTS_AND_NAME_A, *POBJECTS_AND_NAME_A;

Members
ObjectsPresent

Indicates whether the ObjectTypeName and InheritedObjectTypeName members contain strings. This
parameter can be a combination of the following values.

VA L UE M EA N IN G

The ObjectTypeName member contains a string.

ACE_OBJECT_TYPE_PRESENT
0x1

The InheritedObjectTypeName member contains a string.

ACE_INHERITED_OBJECT_TYPE_PRESENT
0x2

ObjectType

Specifies a value from the SE_OBJECT_TYPE enumeration that indicates the type of object.
ObjectTypeName

A pointer to a null-terminated string that identifies the type of object to which the ACE applies.
This string must be a valid LDAP display name in the Active Directory schema.
InheritedObjectTypeName

A pointer to a null-terminated string that identifies the type of object that can inherit the ACE.
This string must be a valid LDAP display name in the Active Directory schema.
If the ACE_INHERITED_OBJECT_TYPE_PRESENT bit is not set in the ObjectsPresent member, the
InheritedObjectTypeName member is ignored, and all types of child objects can inherit the ACE. Otherwise,
only the specified object type can inherit the ACE. In either case, inheritance is also controlled by the inheritance
flags in the ACE_HEADER structure as well as by any protection against inheritance placed on the child objects.
ptstrName

A pointer to a null-terminated string that contains the name of the trustee.

Remarks
The ptstrName member of a TRUSTEE structure can be a pointer to an OBJECTS_AND_NAME structure. This
enables functions such as SetEntriesInAcl and GetExplicitEntriesFromAcl to store object-specific ACE information
in the Trustee member of an EXPLICIT_ACCESS structure.

NOTE
The accctrl.h header defines OBJECTS_AND_NAME_ as an alias which automatically selects the ANSI or Unicode version of
this function based on the definition of the UNICODE preprocessor constant. Mixing usage of the encoding-neutral alias
with code that not encoding-neutral can lead to mismatches that result in compilation or runtime errors. For more
information, see Conventions for Function Prototypes.

Requirements

Minimum suppor ted client Windows XP [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Header accctrl.h

See also
ACE_HEADER
EXPLICIT_ACCESS
GetExplicitEntriesFromAcl
OBJECTS_AND_SID
SE_OBJECT_TYPE
SetEntriesInAcl
TRUSTEE
 OBJECTS_AND_NAME_W structure (accctrl.h)
7/2/2022 • 2 minutes to read • Edit Online

The OBJECTS_AND_NAME structure contains a string that identifies a trustee by name and additional strings
that identify the object types of an object-specific access control entry (ACE).

Syntax
typedef struct _OBJECTS_AND_NAME_W {
DWORD ObjectsPresent;
SE_OBJECT_TYPE ObjectType;
LPWSTR ObjectTypeName;
LPWSTR InheritedObjectTypeName;
LPWSTR ptstrName;
} OBJECTS_AND_NAME_W, *POBJECTS_AND_NAME_W;

Members
ObjectsPresent

Indicates whether the ObjectTypeName and InheritedObjectTypeName members contain strings. This
parameter can be a combination of the following values.

VA L UE M EA N IN G

The ObjectTypeName member contains a string.

ACE_OBJECT_TYPE_PRESENT
0x1

The InheritedObjectTypeName member contains a string.

ACE_INHERITED_OBJECT_TYPE_PRESENT
0x2

ObjectType

Specifies a value from the SE_OBJECT_TYPE enumeration that indicates the type of object.
ObjectTypeName

A pointer to a null-terminated string that identifies the type of object to which the ACE applies.
This string must be a valid LDAP display name in the Active Directory schema.
InheritedObjectTypeName

A pointer to a null-terminated string that identifies the type of object that can inherit the ACE.
This string must be a valid LDAP display name in the Active Directory schema.
If the ACE_INHERITED_OBJECT_TYPE_PRESENT bit is not set in the ObjectsPresent member, the
InheritedObjectTypeName member is ignored, and all types of child objects can inherit the ACE. Otherwise,
only the specified object type can inherit the ACE. In either case, inheritance is also controlled by the inheritance
flags in the ACE_HEADER structure as well as by any protection against inheritance placed on the child objects.
ptstrName

A pointer to a null-terminated string that contains the name of the trustee.

Remarks
The ptstrName member of a TRUSTEE structure can be a pointer to an OBJECTS_AND_NAME structure. This
enables functions such as SetEntriesInAcl and GetExplicitEntriesFromAcl to store object-specific ACE information
in the Trustee member of an EXPLICIT_ACCESS structure.

NOTE
The accctrl.h header defines OBJECTS_AND_NAME_ as an alias which automatically selects the ANSI or Unicode version of
this function based on the definition of the UNICODE preprocessor constant. Mixing usage of the encoding-neutral alias
with code that not encoding-neutral can lead to mismatches that result in compilation or runtime errors. For more
information, see Conventions for Function Prototypes.

Requirements

Minimum suppor ted client Windows XP [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Header accctrl.h

See also
ACE_HEADER
EXPLICIT_ACCESS
GetExplicitEntriesFromAcl
OBJECTS_AND_SID
SE_OBJECT_TYPE
SetEntriesInAcl
TRUSTEE
 OBJECTS_AND_SID structure (accctrl.h)
7/2/2022 • 2 minutes to read • Edit Online

The OBJECTS_AND_SID structure contains a security identifier (SID) that identifies a trustee and GUIDs that
identify the object types of an object-specific access control entry (ACE).

Syntax
typedef struct _OBJECTS_AND_SID {
DWORD ObjectsPresent;
GUID ObjectTypeGuid;
GUID InheritedObjectTypeGuid;
SID *pSid;
} OBJECTS_AND_SID, *POBJECTS_AND_SID;

Members
ObjectsPresent

Indicates whether the ObjectTypeGuid and InheritedObjectTypeGuid members contain GUIDs. This
parameter can be a combination of the following values.

VA L UE M EA N IN G

The ObjectTypeGuid member contains a GUID.

ACE_OBJECT_TYPE_PRESENT
0x1

The InheritedObjectTypeGuid member contains a GUID.

ACE_INHERITED_OBJECT_TYPE_PRESENT
0x2

ObjectTypeGuid

A GUID structure that identifies the type of object, property set, or property protected by the ACE. If this ACE is
inherited, the GUID identifies the type of object, property set, or property protected by the inherited ACE. This
GUID must be a valid schema identifier in the Active Directory schema.
If the ACE_OBJECT_TYPE_PRESENT bit is not set in the ObjectsPresent member, the ObjectTypeGuid member
is ignored, and the ACE protects the object to which the ACL is assigned.
InheritedObjectTypeGuid

A GUID structure that identifies the type of object that can inherit the ACE. This GUID must be a valid schema
identifier in the Active Directory schema.
If the ACE_INHERITED_OBJECT_TYPE_PRESENT bit is not set in the ObjectsPresent member, the
InheritedObjectTypeGuid member is ignored, and all types of child objects can inherit the ACE. Otherwise,
only the specified object type can inherit the ACE. In either case, inheritance is also controlled by the inheritance
flags in the ACE_HEADER structure as well as by any protection against inheritance placed on the child objects.
pSid
A pointer to the SID of the trustee to whom the ACE applies.

Remarks
The ptstrName member of a TRUSTEE structure can be a pointer to an OBJECTS_AND_SID structure. This
enables functions such as SetEntriesInAcl and GetExplicitEntriesFromAcl to store object-specific ACE information
in the Trustee member of an EXPLICIT_ACCESS structure.
When you use this structure in a call to SetEntriesInAcl, ObjectTypeGuid and InheritedObjectTypeGuid must
be valid schema identifiers in the Active Directory schema. The system does not verify the GUIDs; they are used
as is.

Requirements

Minimum suppor ted client Windows XP [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Header accctrl.h

See also
ACE_HEADER
EXPLICIT_ACCESS
GUID
GetExplicitEntriesFromAcl
OBJECTS_AND_NAME
SetEntriesInAcl
TRUSTEE
 PROG_INVOKE_SETTING enumeration (accctrl.h)
7/2/2022 • 2 minutes to read • Edit Online

The PROG_INVOKE_SETTING enumeration indicates the initial setting of the function used to track the
progress of a call to the TreeSetNamedSecurityInfo or TreeResetNamedSecurityInfo function.

Syntax
typedef enum _PROGRESS_INVOKE_SETTING {
ProgressInvokeNever,
ProgressInvokeEveryObject,
ProgressInvokeOnError,
ProgressCancelOperation,
ProgressRetryOperation,
ProgressInvokePrePostError
} PROG_INVOKE_SETTING, *PPROG_INVOKE_SETTING;

Constants

ProgressInvokeNever
Never invoke the progress function.

ProgressInvokeEveryObject
Invoke the progress function for every object.

ProgressInvokeOnError
Invoke the progress function only when an error is encountered.

ProgressCancelOperation
Discontinue the tree operation.

Note The original state of the tree will not be reset, and the results are unpredictable.

ProgressRetryOperation
Retry the tree operation.

ProgressInvokePrePostError
Invoke the progress function before and after applying security on the object and on the error.

Requirements

Minimum suppor ted client Windows XP [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Header accctrl.h
 SE_OBJECT_TYPE enumeration (accctrl.h)
7/2/2022 • 2 minutes to read • Edit Online

The SE_OBJECT_TYPE enumeration contains values that correspond to the types of Windows objects that
support security. The functions, such as GetSecurityInfo and SetSecurityInfo, that set and retrieve the security
information of an object, use these values to indicate the type of object.

Syntax
typedef enum _SE_OBJECT_TYPE {
SE_UNKNOWN_OBJECT_TYPE,
SE_FILE_OBJECT,
SE_SERVICE,
SE_PRINTER,
SE_REGISTRY_KEY,
SE_LMSHARE,
SE_KERNEL_OBJECT,
SE_WINDOW_OBJECT,
SE_DS_OBJECT,
SE_DS_OBJECT_ALL,
SE_PROVIDER_DEFINED_OBJECT,
SE_WMIGUID_OBJECT,
SE_REGISTRY_WOW64_32KEY,
SE_REGISTRY_WOW64_64KEY
} SE_OBJECT_TYPE;

Constants

SE_UNKNOWN_OBJECT_TYPE
Unknown object type.

SE_FILE_OBJECT
Indicates a file or directory. The name string that identifies a file or directory object can be in one of the following formats:

A relative path, such as FileName.dat or ..\FileName

An absolute path, such as FileName.dat, C:\DirectoryName\FileName.dat, or G:\RemoteDirectoryName\FileName.dat.

A UNC name, such as \\ComputerName\ShareName\FileName.dat.

SE_SERVICE
Indicates a Windows service. A service object can be a local service, such as ServiceName, or a remote service, such as \\
ComputerName\ServiceName.

SE_PRINTER
Indicates a printer. A printer object can be a local printer, such as PrinterName, or a remote printer, such as \\ComputerName\
PrinterName.
 SE_REGISTRY_KEY
Indicates a registry key. A registry key object can be in the local registry, such as CL ASSES_ROOT \SomePath or in a remote
registry, such as \\ComputerName\CL ASSES_ROOT \SomePath.

The names of registry keys must use the following literal strings to identify the predefined registry keys: "CLASSES_ROOT",
"CURRENT_USER", "MACHINE", and "USERS".

SE_LMSHARE
Indicates a network share. A share object can be local, such as ShareName, or remote, such as \\ComputerName\ShareName.

SE_KERNEL_OBJECT
Indicates a local
kernel object.

The
GetSecurityInfo and
SetSecurityInfo functions support all types of kernel objects. The
GetNamedSecurityInfo and
SetNamedSecurityInfo functions work only with the following kernel objects: semaphore, event, mutex, waitable timer, and file
mapping.

SE_WINDOW_OBJECT
Indicates a window station or desktop object on the local computer. You cannot use
GetNamedSecurityInfo and
SetNamedSecurityInfo with these objects because the names of window stations or desktops are not unique.

SE_DS_OBJECT
Indicates a directory service object or a property set or property of a directory service object.

The name string for a directory service object must be in X.500 form, for example:

CN=SomeObject,OU=ou2,OU=ou1,DC=DomainName,DC=CompanyName,DC=com,O=internet

SE_DS_OBJECT_ALL
Indicates a directory service object and all of its property sets and properties.

SE_PROVIDER_DEFINED_OBJECT
Indicates a provider-defined object.

SE_WMIGUID_OBJECT
Indicates a WMI object.

SE_REGISTRY_WOW64_32KEY
Indicates an object for a registry entry under WOW64.

SE_REGISTRY_WOW64_64KEY

Requirements
 Minimum suppor ted client Windows XP [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Header accctrl.h

See also
Access Control Overview
Authorization Enumerations
GetNamedSecurityInfo
GetSecurityInfo
SetNamedSecurityInfo
SetSecurityInfo
 TRUSTEE_A structure (accctrl.h)
7/2/2022 • 2 minutes to read • Edit Online

The TRUSTEE structure identifies the user account, group account, or logon session to which an access control
entry (ACE) applies. The structure can use a name or a security identifier (SID) to identify the trustee.
Access control functions, such as SetEntriesInAcl and GetExplicitEntriesFromAcl, use this structure to identify the
logon account associated with the access control or audit control information in an EXPLICIT_ACCESS structure.

Syntax
typedef struct _TRUSTEE_A {
struct _TRUSTEE_A *pMultipleTrustee;
MULTIPLE_TRUSTEE_OPERATION MultipleTrusteeOperation;
TRUSTEE_FORM TrusteeForm;
TRUSTEE_TYPE TrusteeType;
union {
LPSTR ptstrName;
SID *pSid;
OBJECTS_AND_SID *pObjectsAndSid;
OBJECTS_AND_NAME_A *pObjectsAndName;
};
LPCH ptstrName;
} TRUSTEE_A, *PTRUSTEE_A, TRUSTEEA, *PTRUSTEEA;

Members
pMultipleTrustee

A pointer to a TRUSTEE structure that identifies a server account that can impersonate the user identified by the
ptstrName member. This member is not currently supported and must be NULL .
MultipleTrusteeOperation

A value of the MULTIPLE_TRUSTEE_OPERATION enumeration type. Currently, this member must be

NO_MULTIPLE_TRUSTEE.
TrusteeForm

A value from the TRUSTEE_FORM enumeration type that indicates the type of data pointed to by the
ptstrName member.
TrusteeType

A value from the TRUSTEE_TYPE enumeration type that indicates whether the trustee is a user account, a group
account, or an unknown account type.
ptstrName

A pointer to a buffer that identifies the trustee and, optionally, contains information about object-specific ACEs.
The type of data depends on the value of the TrusteeForm member.
This member can be one of the following values.

VA L UE M EA N IN G
 A pointer to a null-terminated string that contains the
TRUSTEE_IS_NAME name of the trustee.

A pointer to an OBJECTS_AND_NAME structure that

TRUSTEE_IS_OBJECTS_AND_NAME contains the name of the trustee and the names of the
object types in an object-specific ACE.

A pointer to an OBJECTS_AND_SID structure that contains

TRUSTEE_IS_OBJECTS_AND_SID the SID of the trustee and the GUIDs of the object types in
an object-specific ACE.

Pointer to the SID of the trustee.

TRUSTEE_IS_SID

pSid

pObjectsAndSid

pObjectsAndName

Remarks
A trustee name can have any of the following formats:
A fully qualified name, such as "g:\remotedir\abc".
A domain account, such as "domain1\xyz".
One of the predefined group names, such as "EVERYONE" or "GUEST".
One of the following special names.
NAME M EA N IN G

CREATOR GROUP The CREATOR_GROUP SID is a SID used in inheritable

ACEs. When a new object is created, the system replaces
this SID with the primary group SID of the user who
created the object.

CREATOR OWNER The CREATOR_OWNER SID is a SID used in inheritable

ACEs. When a new object is created, the system replaces
this SID with the SID of the user who created the object.

CURRENT_USER The owner of the calling thread or process.

A trustee SID can be any user or group SID. It can also be any of the universal, well-known SIDs. For more
information, see Security Identifiers.

NOTE
The accctrl.h header defines TRUSTEE_ as an alias which automatically selects the ANSI or Unicode version of this function
based on the definition of the UNICODE preprocessor constant. Mixing usage of the encoding-neutral alias with code that
not encoding-neutral can lead to mismatches that result in compilation or runtime errors. For more information, see
Conventions for Function Prototypes.

Requirements
 Minimum suppor ted client Windows XP [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Header accctrl.h

See also
ACL
EXPLICIT_ACCESS
GetExplicitEntriesFromAcl
MULTIPLE_TRUSTEE_OPERATION
OBJECTS_AND_NAME
OBJECTS_AND_SID
SID
SetEntriesInAcl
TRUSTEE_FORM
TRUSTEE_TYPE
 TRUSTEE_FORM enumeration (accctrl.h)
7/2/2022 • 2 minutes to read • Edit Online

The TRUSTEE_FORM enumeration contains values that indicate the type of data pointed to by the ptstrName
member of the TRUSTEE structure.

Syntax
typedef enum _TRUSTEE_FORM {
TRUSTEE_IS_SID,
TRUSTEE_IS_NAME,
TRUSTEE_BAD_FORM,
TRUSTEE_IS_OBJECTS_AND_SID,
TRUSTEE_IS_OBJECTS_AND_NAME
} TRUSTEE_FORM;

Constants

TRUSTEE_IS_SID
The ptstrName member is a pointer to a security identifier (SID) that identifies the trustee.

TRUSTEE_IS_NAME
The ptstrName member is a pointer to a null-terminated string that identifies the trustee.

TRUSTEE_BAD_FORM
Indicates a trustee form that is not valid.

TRUSTEE_IS_OBJECTS_AND_SID
The ptstrName member is a pointer to an
OBJECTS_AND_SID structure that contains the SID of the trustee and the GUIDs of the object types in an object-specific
access control entry (ACE).

TRUSTEE_IS_OBJECTS_AND_NAME
The ptstrName member is a pointer to an
OBJECTS_AND_NAME structure that contains the name of the trustee and the names of the object types in an object-specific
ACE.

Requirements

Minimum suppor ted client Windows XP [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Header accctrl.h
See also
Access Control
Authorization Enumerations
OBJECTS_AND_NAME
OBJECTS_AND_SID
TRUSTEE
 TRUSTEE_TYPE enumeration (accctrl.h)
7/2/2022 • 2 minutes to read • Edit Online

The TRUSTEE_TYPE enumeration contains values that indicate the type of trustee identified by a TRUSTEE
structure.

Syntax
typedef enum _TRUSTEE_TYPE {
TRUSTEE_IS_UNKNOWN,
TRUSTEE_IS_USER,
TRUSTEE_IS_GROUP,
TRUSTEE_IS_DOMAIN,
TRUSTEE_IS_ALIAS,
TRUSTEE_IS_WELL_KNOWN_GROUP,
TRUSTEE_IS_DELETED,
TRUSTEE_IS_INVALID,
TRUSTEE_IS_COMPUTER
} TRUSTEE_TYPE;

Constants

TRUSTEE_IS_UNKNOWN
The trustee type is unknown, but it may be valid.

TRUSTEE_IS_USER
Indicates a user.

TRUSTEE_IS_GROUP
Indicates a group.

TRUSTEE_IS_DOMAIN
Indicates a domain.

TRUSTEE_IS_ALIAS
Indicates an alias.

TRUSTEE_IS_WELL_KNOWN_GROUP
Indicates a
well-known group.

TRUSTEE_IS_DELETED
Indicates a deleted account.

TRUSTEE_IS_INVALID
Indicates a trustee type that is not valid.

TRUSTEE_IS_COMPUTER
Indicates a computer.
Requirements

Minimum suppor ted client Windows XP [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Header accctrl.h

See also
Access Control Overview
Authorization Enumerations
TRUSTEE
 TRUSTEE_W structure (accctrl.h)
7/2/2022 • 2 minutes to read • Edit Online

The TRUSTEE structure identifies the user account, group account, or logon session to which an access control
entry (ACE) applies. The structure can use a name or a security identifier (SID) to identify the trustee.
Access control functions, such as SetEntriesInAcl and GetExplicitEntriesFromAcl, use this structure to identify the
logon account associated with the access control or audit control information in an EXPLICIT_ACCESS structure.

Syntax
typedef struct _TRUSTEE_W {
struct _TRUSTEE_W *pMultipleTrustee;
MULTIPLE_TRUSTEE_OPERATION MultipleTrusteeOperation;
TRUSTEE_FORM TrusteeForm;
TRUSTEE_TYPE TrusteeType;
union {
LPWSTR ptstrName;
SID *pSid;
OBJECTS_AND_SID *pObjectsAndSid;
OBJECTS_AND_NAME_W *pObjectsAndName;
};
LPWCH ptstrName;
} TRUSTEE_W, *PTRUSTEE_W, TRUSTEEW, *PTRUSTEEW;

Members
pMultipleTrustee

A pointer to a TRUSTEE structure that identifies a server account that can impersonate the user identified by the
ptstrName member. This member is not currently supported and must be NULL .
MultipleTrusteeOperation

A value of the MULTIPLE_TRUSTEE_OPERATION enumeration type. Currently, this member must be

NO_MULTIPLE_TRUSTEE.
TrusteeForm

A value from the TRUSTEE_FORM enumeration type that indicates the type of data pointed to by the
ptstrName member.
TrusteeType

A value from the TRUSTEE_TYPE enumeration type that indicates whether the trustee is a user account, a group
account, or an unknown account type.
ptstrName

A pointer to a buffer that identifies the trustee and, optionally, contains information about object-specific ACEs.
The type of data depends on the value of the TrusteeForm member.
This member can be one of the following values.

VA L UE M EA N IN G
 A pointer to a null-terminated string that contains the
TRUSTEE_IS_NAME name of the trustee.

A pointer to an OBJECTS_AND_NAME structure that

TRUSTEE_IS_OBJECTS_AND_NAME contains the name of the trustee and the names of the
object types in an object-specific ACE.

A pointer to an OBJECTS_AND_SID structure that contains

TRUSTEE_IS_OBJECTS_AND_SID the SID of the trustee and the GUIDs of the object types in
an object-specific ACE.

Pointer to the SID of the trustee.

TRUSTEE_IS_SID

pSid

pObjectsAndSid

pObjectsAndName

Remarks
A trustee name can have any of the following formats:
A fully qualified name, such as "g:\remotedir\abc".
A domain account, such as "domain1\xyz".
One of the predefined group names, such as "EVERYONE" or "GUEST".
One of the following special names.

NAME M EA N IN G

CREATOR GROUP The CREATOR_GROUP SID is a SID used in inheritable

ACEs. When a new object is created, the system replaces
this SID with the primary group SID of the user who
created the object.

CREATOR OWNER The CREATOR_OWNER SID is a SID used in inheritable

ACEs. When a new object is created, the system replaces
this SID with the SID of the user who created the object.

CURRENT_USER The owner of the calling thread or process.

A trustee SID can be any user or group SID. It can also be any of the universal, well-known SIDs. For more
information, see Security Identifiers.

NOTE
The accctrl.h header defines TRUSTEE_ as an alias which automatically selects the ANSI or Unicode version of this function
based on the definition of the UNICODE preprocessor constant. Mixing usage of the encoding-neutral alias with code that
not encoding-neutral can lead to mismatches that result in compilation or runtime errors. For more information, see
Conventions for Function Prototypes.
Requirements

Minimum suppor ted client Windows XP [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Header accctrl.h

See also
ACL
EXPLICIT_ACCESS
GetExplicitEntriesFromAcl
MULTIPLE_TRUSTEE_OPERATION
OBJECTS_AND_NAME
OBJECTS_AND_SID
SID
SetEntriesInAcl
TRUSTEE_FORM
TRUSTEE_TYPE
 aclapi.h header
7/2/2022 • 4 minutes to read • Edit Online

This header is used by Security and Identity. For more information, see:
Security and Identity
aclapi.h contains the following programming interfaces:

Functions

BuildExplicitAccessWithNameA

Initializes an EXPLICIT_ACCESS structure with data specified by the caller. The trustee is identified by a name string.

BuildExplicitAccessWithNameW

Initializes an EXPLICIT_ACCESS structure with data specified by the caller. The trustee is identified by a name string.

BuildSecurityDescriptorA

Allocates and initializes a new security descriptor.

BuildSecurityDescriptorW

Allocates and initializes a new security descriptor.

BuildTrusteeWithNameA

Initializes a TRUSTEE structure. The caller specifies the trustee name. The function sets other members of the structure to
default values.

BuildTrusteeWithNameW

Initializes a TRUSTEE structure. The caller specifies the trustee name. The function sets other members of the structure to
default values.

BuildTrusteeWithObjectsAndNameA

Initializes a TRUSTEE structure with the object-specific access control entry (ACE) information and initializes the remaining
members of the structure to default values. The caller also specifies the name of the trustee.

BuildTrusteeWithObjectsAndNameW

Initializes a TRUSTEE structure with the object-specific access control entry (ACE) information and initializes the remaining
members of the structure to default values. The caller also specifies the name of the trustee.

BuildTrusteeWithObjectsAndSidA

Initializes a TRUSTEE structure with the object-specific access control entry (ACE) information and initializes the remaining
members of the structure to default values.
BuildTrusteeWithObjectsAndSidW

Initializes a TRUSTEE structure with the object-specific access control entry (ACE) information and initializes the remaining
members of the structure to default values.

BuildTrusteeWithSidA

Initializes a TRUSTEE structure. The caller specifies the security identifier (SID) of the trustee. The function sets other members
of the structure to default values and does not look up the name associated with the SID.

BuildTrusteeWithSidW

Initializes a TRUSTEE structure. The caller specifies the security identifier (SID) of the trustee. The function sets other members
of the structure to default values and does not look up the name associated with the SID.

FreeInheritedFromArray

Frees memory allocated by the GetInheritanceSource function.

GetAuditedPermissionsFromAclA

Retrieves the audited access rights for a specified trustee.

GetAuditedPermissionsFromAclW

Retrieves the audited access rights for a specified trustee.

GetEffectiveRightsFromAclA

Retrieves the effective access rights that an ACL structure grants to a specified trustee. The trustee's effective access rights are
the access rights that the ACL grants to the trustee or to any groups of which the trustee is a member.

GetEffectiveRightsFromAclW

Retrieves the effective access rights that an ACL structure grants to a specified trustee. The trustee's effective access rights are
the access rights that the ACL grants to the trustee or to any groups of which the trustee is a member.

GetExplicitEntriesFromAclA

Retrieves an array of structures that describe the access control entries (ACEs) in an access control list (ACL).

GetExplicitEntriesFromAclW

Retrieves an array of structures that describe the access control entries (ACEs) in an access control list (ACL).

GetInheritanceSourceA

Returns information about the source of inherited access control entries (ACEs) in an access control list (ACL).

GetInheritanceSourceW

Returns information about the source of inherited access control entries (ACEs) in an access control list (ACL).

GetNamedSecurityInfoA

Retrieves a copy of the security descriptor for an object specified by name.

GetNamedSecurityInfoW

Retrieves a copy of the security descriptor for an object specified by name.

GetSecurityInfo

Retrieves a copy of the security descriptor for an object specified by a handle.

GetTrusteeFormA

Retrieves the trustee name from the specified TRUSTEE structure. This value indicates whether the structure uses a name string
or a security identifier (SID) to identify the trustee.

GetTrusteeFormW

Retrieves the trustee name from the specified TRUSTEE structure. This value indicates whether the structure uses a name string
or a security identifier (SID) to identify the trustee.

GetTrusteeNameA

Retrieves the trustee name from the specified TRUSTEE structure.

GetTrusteeNameW

Retrieves the trustee name from the specified TRUSTEE structure.

GetTrusteeTypeA

Retrieves the trustee type from the specified TRUSTEE structure. This value indicates whether the trustee is a user, a group, or
the trustee type is unknown.

GetTrusteeTypeW

Retrieves the trustee type from the specified TRUSTEE structure. This value indicates whether the trustee is a user, a group, or
the trustee type is unknown.

LookupSecurityDescriptorPartsA

Retrieves security information from a self-relative security descriptor.

LookupSecurityDescriptorPartsW

Retrieves security information from a self-relative security descriptor.

SetEntriesInAclA

Creates a new access control list (ACL) by merging new access control or audit control information into an existing ACL
structure.

SetEntriesInAclW

Creates a new access control list (ACL) by merging new access control or audit control information into an existing ACL
structure.
SetNamedSecurityInfoA

Sets specified security information in the security descriptor of a specified object.

SetNamedSecurityInfoW

Sets specified security information in the security descriptor of a specified object.

SetSecurityInfo

Sets specified security information in the security descriptor of a specified object. The caller identifies the object by a handle.

TreeResetNamedSecurityInfoA

Resets specified security information in the security descriptor of a specified tree of objects.

TreeResetNamedSecurityInfoW

Resets specified security information in the security descriptor of a specified tree of objects.

TreeSetNamedSecurityInfoA

Sets specified security information in the security descriptor of a specified tree of objects.

TreeSetNamedSecurityInfoW

Sets specified security information in the security descriptor of a specified tree of objects.
 BuildExplicitAccessWithNameA function (aclapi.h)
7/2/2022 • 2 minutes to read • Edit Online

The BuildExplicitAccessWithName function initializes an EXPLICIT_ACCESS structure with data specified by

the caller. The trustee is identified by a name string.

Syntax
void BuildExplicitAccessWithNameA(
[in, out] PEXPLICIT_ACCESS_A pExplicitAccess,
[in, optional] LPSTR pTrusteeName,
[in] DWORD AccessPermissions,
[in] ACCESS_MODE AccessMode,
[in] DWORD Inheritance
);

Parameters
[in, out] pExplicitAccess

A pointer to an EXPLICIT_ACCESS structure to initialize. The BuildExplicitAccessWithName function does not

allocate any memory. This parameter cannot be NULL .
[in, optional] pTrusteeName

A pointer to a null -terminated string that contains the name of the trustee for the ptstrName member of the
TRUSTEE structure. The BuildExplicitAccessWithName function sets the other members of the TRUSTEE
structure as follows.

VA L UE M EA N IN G

NULL
pMultipleTrustee

NO_MULTIPLE_TRUSTEE
MultipleTrusteeOperation

TRUSTEE_IS_NAME
TrusteeForm

TRUSTEE_IS_UNKNOWN
TrusteeType

[in] AccessPermissions

Specifies an access mask for the grfAccessPermissions member of the EXPLICIT_ACCESS structure. The mask
is a set of bit flags that use the ACCESS_MASK format to specify the access rights that an ACE allows, denies, or
audits for the trustee. The functions that use the EXPLICIT_ACCESS structure do not convert, interpret, or
validate the bits in this mask.
[in] AccessMode
Specifies an access mode for the grfAccessMode member of the EXPLICIT_ACCESS structure. The access mode
indicates whether the access control entry (ACE) allows, denies, or audits the specified rights. For a discretionary
access control list (DACL), this parameter can be one of the values from the ACCESS_MODE enumeration. For a
system access control list (SACL), this parameter can be a combination of ACCESS_MODE values.
[in] Inheritance

Specifies an inheritance type for the grfInheritance member of the EXPLICIT_ACCESS structure. This value is a
set of bit flags that determine whether other containers or objects can inherit the ACE from the primary object
to which the ACL is attached. The value of this member corresponds to the inheritance portion (low-order byte)
of the AceFlags member of the ACE_HEADER structure. This parameter can be NO_INHERITANCE to indicate
that the ACE is not inheritable, or it can be a combination of the following values.

VA L UE M EA N IN G

Other containers that are contained by the primary object

CONTAINER_INHERIT_ACE inherit the ACE.

The ACE does not apply to the primary object to which the
INHERIT_ONLY_ACE ACL is attached, but objects contained by the primary object
inherit the ACE.

The OBJECT_INHERIT_ACE and CONTAINER_INHERIT_ACE

NO_PROPAGATE_INHERIT_ACE flags are not propagated to an inherited ACE.

Noncontainer objects contained by the primary object

OBJECT_INHERIT_ACE inherit the ACE.

Both containers and noncontainer objects that are contained

SUB_CONTAINERS_AND_OBJECTS_INHERIT by the primary object inherit the ACE. This flag corresponds
to the combination of the CONTAINER_INHERIT_ACE and
OBJECT_INHERIT_ACE flags.

Other containers that are contained by the primary object

SUB_CONTAINERS_ONLY_INHERIT inherit the ACE. This flag corresponds to the combination of
the CONTAINER_INHERIT_ACE and
INHERIT_ONLY_ACE flags.

Noncontainer objects contained by the primary object

SUB_OBJECTS_ONLY_INHERIT inherit the ACE. This flag corresponds to the combination of
the OBJECT_INHERIT_ACE and INHERIT_ONLY_ACE
flags.

Return value
None

Remarks
 NOTE
The aclapi.h header defines BuildExplicitAccessWithName as an alias which automatically selects the ANSI or Unicode
version of this function based on the definition of the UNICODE preprocessor constant. Mixing usage of the encoding-
neutral alias with code that not encoding-neutral can lead to mismatches that result in compilation or runtime errors. For
more information, see Conventions for Function Prototypes.

Requirements

Minimum suppor ted client Windows XP [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header aclapi.h

Librar y Advapi32.lib

DLL Advapi32.dll

See also
ACE
ACL
Access Control Overview
Basic Access Control Functions
EXPLICIT_ACCESS
GetExplicitEntriesFromAcl
SetEntriesInAcl
TRUSTEE
 BuildExplicitAccessWithNameW function (aclapi.h)
7/2/2022 • 2 minutes to read • Edit Online

The BuildExplicitAccessWithName function initializes an EXPLICIT_ACCESS structure with data specified by

the caller. The trustee is identified by a name string.

Syntax
void BuildExplicitAccessWithNameW(
[in, out] PEXPLICIT_ACCESS_W pExplicitAccess,
[in, optional] LPWSTR pTrusteeName,
[in] DWORD AccessPermissions,
[in] ACCESS_MODE AccessMode,
[in] DWORD Inheritance
);

Parameters
[in, out] pExplicitAccess

A pointer to an EXPLICIT_ACCESS structure to initialize. The BuildExplicitAccessWithName function does not

allocate any memory. This parameter cannot be NULL .
[in, optional] pTrusteeName

A pointer to a null -terminated string that contains the name of the trustee for the ptstrName member of the
TRUSTEE structure. The BuildExplicitAccessWithName function sets the other members of the TRUSTEE
structure as follows.

VA L UE M EA N IN G

NULL
pMultipleTrustee

NO_MULTIPLE_TRUSTEE
MultipleTrusteeOperation

TRUSTEE_IS_NAME
TrusteeForm

TRUSTEE_IS_UNKNOWN
TrusteeType

[in] AccessPermissions

Specifies an access mask for the grfAccessPermissions member of the EXPLICIT_ACCESS structure. The mask
is a set of bit flags that use the ACCESS_MASK format to specify the access rights that an ACE allows, denies, or
audits for the trustee. The functions that use the EXPLICIT_ACCESS structure do not convert, interpret, or
validate the bits in this mask.
[in] AccessMode
Specifies an access mode for the grfAccessMode member of the EXPLICIT_ACCESS structure. The access mode
indicates whether the access control entry (ACE) allows, denies, or audits the specified rights. For a discretionary
access control list (DACL), this parameter can be one of the values from the ACCESS_MODE enumeration. For a
system access control list (SACL), this parameter can be a combination of ACCESS_MODE values.
[in] Inheritance

Specifies an inheritance type for the grfInheritance member of the EXPLICIT_ACCESS structure. This value is a
set of bit flags that determine whether other containers or objects can inherit the ACE from the primary object
to which the ACL is attached. The value of this member corresponds to the inheritance portion (low-order byte)
of the AceFlags member of the ACE_HEADER structure. This parameter can be NO_INHERITANCE to indicate
that the ACE is not inheritable, or it can be a combination of the following values.

VA L UE M EA N IN G

Other containers that are contained by the primary object

CONTAINER_INHERIT_ACE inherit the ACE.

The ACE does not apply to the primary object to which the
INHERIT_ONLY_ACE ACL is attached, but objects contained by the primary object
inherit the ACE.

The OBJECT_INHERIT_ACE and CONTAINER_INHERIT_ACE

NO_PROPAGATE_INHERIT_ACE flags are not propagated to an inherited ACE.

Noncontainer objects contained by the primary object

OBJECT_INHERIT_ACE inherit the ACE.

Both containers and noncontainer objects that are contained

SUB_CONTAINERS_AND_OBJECTS_INHERIT by the primary object inherit the ACE. This flag corresponds
to the combination of the CONTAINER_INHERIT_ACE and
OBJECT_INHERIT_ACE flags.

Other containers that are contained by the primary object

SUB_CONTAINERS_ONLY_INHERIT inherit the ACE. This flag corresponds to the combination of
the CONTAINER_INHERIT_ACE and
INHERIT_ONLY_ACE flags.

Noncontainer objects contained by the primary object

SUB_OBJECTS_ONLY_INHERIT inherit the ACE. This flag corresponds to the combination of
the OBJECT_INHERIT_ACE and INHERIT_ONLY_ACE
flags.

Return value
None

Remarks
 NOTE
The aclapi.h header defines BuildExplicitAccessWithName as an alias which automatically selects the ANSI or Unicode
version of this function based on the definition of the UNICODE preprocessor constant. Mixing usage of the encoding-
neutral alias with code that not encoding-neutral can lead to mismatches that result in compilation or runtime errors. For
more information, see Conventions for Function Prototypes.

Requirements

Minimum suppor ted client Windows XP [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header aclapi.h

Librar y Advapi32.lib

DLL Advapi32.dll

See also
ACE
ACL
Access Control Overview
Basic Access Control Functions
EXPLICIT_ACCESS
GetExplicitEntriesFromAcl
SetEntriesInAcl
TRUSTEE
 BuildSecurityDescriptorA function (aclapi.h)
7/2/2022 • 3 minutes to read • Edit Online

The BuildSecurityDescriptor function allocates and initializes a new security descriptor. This function can
initialize the new security descriptor by merging specified security information with the information in an
existing security descriptor. If you do not specify an existing security descriptor, the function initializes a new
security descriptor based on the specified security information.
The BuildSecurityDescriptor function creates a self-relative security descriptor. The self-relative format makes
the security descriptor suitable for storing in a stream.

Syntax
DWORD BuildSecurityDescriptorA(
[in, optional] PTRUSTEE_A pOwner,
[in, optional] PTRUSTEE_A pGroup,
[in] ULONG cCountOfAccessEntries,
[in, optional] PEXPLICIT_ACCESS_A pListOfAccessEntries,
[in] ULONG cCountOfAuditEntries,
[in, optional] PEXPLICIT_ACCESS_A pListOfAuditEntries,
[in, optional] PSECURITY_DESCRIPTOR pOldSD,
[out] PULONG pSizeNewSD,
[out] PSECURITY_DESCRIPTOR *pNewSD
);

Parameters
[in, optional] pOwner

A pointer to a TRUSTEE structure that identifies the owner for the new security descriptor. If the structure uses
the TRUSTEE_IS_NAME form, BuildSecurityDescriptor looks up the security identifier (SID) associated with
the specified trustee name.
If this parameter is NULL , the function uses the owner SID from the original security descriptor pointed to by
pOldSD. If pOldSD is NULL , or if the owner SID in pOldSD is NULL , the owner SID is NULL in the new security
descriptor.
[in, optional] pGroup

A pointer to a TRUSTEE structure that identifies the primary group SID for the new security descriptor. If the
structure uses the TRUSTEE_IS_NAME form, BuildSecurityDescriptor looks up the SID associated with the
specified trustee name.
If this parameter is NULL , the function uses the group SID from the original security descriptor pointed to by
pOldSD. If pOldSD is NULL , or if the group SID in pOldSD is NULL , the group SID is NULL in the new security
descriptor.
[in] cCountOfAccessEntries

The number of EXPLICIT_ACCESS structures in the pListOfAccessEntries array.

[in, optional] pListOfAccessEntries

A pointer to an array of EXPLICIT_ACCESS structures that describe access control information for the
discretionary access control list (DACL) of the new security descriptor. The function creates the new DACL by
merging the information in the array with the DACL in pOldSD, if any. If pOldSD is NULL , or if the DACL in
pOldSD is NULL , the function creates a new DACL based solely on the information in the array. For a description
of the rules for creating an ACL from an array of EXPLICIT_ACCESS structures, see the SetEntriesInAcl function.
If pListOfAccessEntries is NULL , the new security descriptor gets the DACL from pOldSD. In this case, if pOldSD
is NULL , or if the DACL in pOldSD is NULL , the new DACL is NULL .
[in] cCountOfAuditEntries

The number of EXPLICIT_ACCESS structures in the pListOfAuditEntries array.

[in, optional] pListOfAuditEntries

A pointer to an array of EXPLICIT_ACCESS structures that describe audit control information for the SACL of the
new security descriptor. The function creates the new SACL by merging the information in the array with the
SACL in pOldSD, if any. If pOldSD is NULL , or the SACL in pOldSD is NULL , the function creates a new SACL
based solely on the information in the array.
If pListOfAuditEntries is NULL , the new security descriptor gets the SACL from pOldSD. In this case, if pOldSD is
NULL , or the SACL in pOldSD is NULL , the new SACL is NULL .
[in, optional] pOldSD

A pointer to an existing self-relative SECURITY_DESCRIPTOR structure and its associated security information.
The function builds the new security descriptor by merging the specified owner, group, access control, and audit-
control information with the information in this security descriptor. This parameter can be NULL .
[out] pSizeNewSD

A pointer to a variable that receives the size, in bytes, of the security descriptor.
[out] pNewSD

A pointer to a variable that receives a pointer to the new security descriptor. The function allocates memory for
the new security descriptor. You must call the LocalFree function to free the returned buffer.

Return value
If the function succeeds, the function returns ERROR_SUCCESS.
If the function fails, it returns a nonzero error code defined in WinError.h.

Remarks
The BuildSecurityDescriptor function is intended for trusted servers that implement or expose security on
their own objects. The function uses self-relative security descriptors suitable for serializing into a stream and
storing to disk, as a trusted server might require.

NOTE
The aclapi.h header defines BuildSecurityDescriptor as an alias which automatically selects the ANSI or Unicode version of
this function based on the definition of the UNICODE preprocessor constant. Mixing usage of the encoding-neutral alias
with code that not encoding-neutral can lead to mismatches that result in compilation or runtime errors. For more
information, see Conventions for Function Prototypes.

Requirements
 Minimum suppor ted client Windows XP [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header aclapi.h

Librar y Advapi32.lib

DLL Advapi32.dll

See also
ACL
Client/Server Access Control Functions
Client/Server Access Control Overview
EXPLICIT_ACCESS
LocalFree
SECURITY_DESCRIPTOR
SID
SetEntriesInAcl
TRUSTEE
 BuildSecurityDescriptorW function (aclapi.h)
7/2/2022 • 3 minutes to read • Edit Online

The BuildSecurityDescriptor function allocates and initializes a new security descriptor. This function can
initialize the new security descriptor by merging specified security information with the information in an
existing security descriptor. If you do not specify an existing security descriptor, the function initializes a new
security descriptor based on the specified security information.
The BuildSecurityDescriptor function creates a self-relative security descriptor. The self-relative format makes
the security descriptor suitable for storing in a stream.

Syntax
DWORD BuildSecurityDescriptorW(
[in, optional] PTRUSTEE_W pOwner,
[in, optional] PTRUSTEE_W pGroup,
[in] ULONG cCountOfAccessEntries,
[in, optional] PEXPLICIT_ACCESS_W pListOfAccessEntries,
[in] ULONG cCountOfAuditEntries,
[in, optional] PEXPLICIT_ACCESS_W pListOfAuditEntries,
[in, optional] PSECURITY_DESCRIPTOR pOldSD,
[out] PULONG pSizeNewSD,
[out] PSECURITY_DESCRIPTOR *pNewSD
);

Parameters
[in, optional] pOwner

A pointer to a TRUSTEE structure that identifies the owner for the new security descriptor. If the structure uses
the TRUSTEE_IS_NAME form, BuildSecurityDescriptor looks up the security identifier (SID) associated with
the specified trustee name.
If this parameter is NULL , the function uses the owner SID from the original security descriptor pointed to by
pOldSD. If pOldSD is NULL , or if the owner SID in pOldSD is NULL , the owner SID is NULL in the new security
descriptor.
[in, optional] pGroup

A pointer to a TRUSTEE structure that identifies the primary group SID for the new security descriptor. If the
structure uses the TRUSTEE_IS_NAME form, BuildSecurityDescriptor looks up the SID associated with the
specified trustee name.
If this parameter is NULL , the function uses the group SID from the original security descriptor pointed to by
pOldSD. If pOldSD is NULL , or if the group SID in pOldSD is NULL , the group SID is NULL in the new security
descriptor.
[in] cCountOfAccessEntries

The number of EXPLICIT_ACCESS structures in the pListOfAccessEntries array.

[in, optional] pListOfAccessEntries

A pointer to an array of EXPLICIT_ACCESS structures that describe access control information for the
discretionary access control list (DACL) of the new security descriptor. The function creates the new DACL by
merging the information in the array with the DACL in pOldSD, if any. If pOldSD is NULL , or if the DACL in
pOldSD is NULL , the function creates a new DACL based solely on the information in the array. For a description
of the rules for creating an ACL from an array of EXPLICIT_ACCESS structures, see the SetEntriesInAcl function.
If pListOfAccessEntries is NULL , the new security descriptor gets the DACL from pOldSD. In this case, if pOldSD
is NULL , or if the DACL in pOldSD is NULL , the new DACL is NULL .
[in] cCountOfAuditEntries

The number of EXPLICIT_ACCESS structures in the pListOfAuditEntries array.

[in, optional] pListOfAuditEntries

A pointer to an array of EXPLICIT_ACCESS structures that describe audit control information for the SACL of the
new security descriptor. The function creates the new SACL by merging the information in the array with the
SACL in pOldSD, if any. If pOldSD is NULL , or the SACL in pOldSD is NULL , the function creates a new SACL
based solely on the information in the array.
If pListOfAuditEntries is NULL , the new security descriptor gets the SACL from pOldSD. In this case, if pOldSD is
NULL , or the SACL in pOldSD is NULL , the new SACL is NULL .
[in, optional] pOldSD

A pointer to an existing self-relative SECURITY_DESCRIPTOR structure and its associated security information.
The function builds the new security descriptor by merging the specified owner, group, access control, and audit-
control information with the information in this security descriptor. This parameter can be NULL .
[out] pSizeNewSD

A pointer to a variable that receives the size, in bytes, of the security descriptor.
[out] pNewSD

A pointer to a variable that receives a pointer to the new security descriptor. The function allocates memory for
the new security descriptor. You must call the LocalFree function to free the returned buffer.

Return value
If the function succeeds, the function returns ERROR_SUCCESS.
If the function fails, it returns a nonzero error code defined in WinError.h.

Remarks
The BuildSecurityDescriptor function is intended for trusted servers that implement or expose security on
their own objects. The function uses self-relative security descriptors suitable for serializing into a stream and
storing to disk, as a trusted server might require.

NOTE
The aclapi.h header defines BuildSecurityDescriptor as an alias which automatically selects the ANSI or Unicode version of
this function based on the definition of the UNICODE preprocessor constant. Mixing usage of the encoding-neutral alias
with code that not encoding-neutral can lead to mismatches that result in compilation or runtime errors. For more
information, see Conventions for Function Prototypes.

Requirements
 Minimum suppor ted client Windows XP [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header aclapi.h

Librar y Advapi32.lib

DLL Advapi32.dll

See also
ACL
Client/Server Access Control Functions
Client/Server Access Control Overview
EXPLICIT_ACCESS
LocalFree
SECURITY_DESCRIPTOR
SID
SetEntriesInAcl
TRUSTEE
 BuildTrusteeWithNameA function (aclapi.h)
7/2/2022 • 2 minutes to read • Edit Online

The BuildTrusteeWithName function initializes a TRUSTEE structure. The caller specifies the trustee name. The
function sets other members of the structure to default values.

Syntax
void BuildTrusteeWithNameA(
[in, out] PTRUSTEE_A pTrustee,
[in, optional] LPSTR pName
);

Parameters
[in, out] pTrustee

A pointer to a TRUSTEE structure to initialize. The BuildTrusteeWithName function does not allocate any
memory. If this parameter is NULL or a pointer that is not valid, the results are undefined.
[in, optional] pName

A pointer to a null-terminated string that contains the name of the trustee for the ptstrName member of the
TRUSTEE structure. The BuildTrusteeWithName function sets the other members of the TRUSTEE structure as
follows.

VA L UE M EA N IN G

NULL
pMultipleTrustee

NO_MULTIPLE_TRUSTEE
MultipleTrusteeOperation

TRUSTEE_IS_NAME
TrusteeForm

TRUSTEE_IS_UNKNOWN
TrusteeType

Return value
None

Remarks
 NOTE
The aclapi.h header defines BuildTrusteeWithName as an alias which automatically selects the ANSI or Unicode version of
this function based on the definition of the UNICODE preprocessor constant. Mixing usage of the encoding-neutral alias
with code that not encoding-neutral can lead to mismatches that result in compilation or runtime errors. For more
information, see Conventions for Function Prototypes.

Requirements

Minimum suppor ted client Windows XP [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header aclapi.h

Librar y Advapi32.lib

DLL Advapi32.dll

See also
Access Control Overview
Basic Access Control Functions
BuildTrusteeWithObjectsAndName
BuildTrusteeWithObjectsAndSid
BuildTrusteeWithSid
TRUSTEE
 BuildTrusteeWithNameW function (aclapi.h)
7/2/2022 • 2 minutes to read • Edit Online

The BuildTrusteeWithName function initializes a TRUSTEE structure. The caller specifies the trustee name. The
function sets other members of the structure to default values.

Syntax
void BuildTrusteeWithNameW(
[in, out] PTRUSTEE_W pTrustee,
[in, optional] LPWSTR pName
);

Parameters
[in, out] pTrustee

A pointer to a TRUSTEE structure to initialize. The BuildTrusteeWithName function does not allocate any
memory. If this parameter is NULL or a pointer that is not valid, the results are undefined.
[in, optional] pName

A pointer to a null-terminated string that contains the name of the trustee for the ptstrName member of the
TRUSTEE structure. The BuildTrusteeWithName function sets the other members of the TRUSTEE structure as
follows.

VA L UE M EA N IN G

NULL
pMultipleTrustee

NO_MULTIPLE_TRUSTEE
MultipleTrusteeOperation

TRUSTEE_IS_NAME
TrusteeForm

TRUSTEE_IS_UNKNOWN
TrusteeType

Return value
None

Remarks
 NOTE
The aclapi.h header defines BuildTrusteeWithName as an alias which automatically selects the ANSI or Unicode version of
this function based on the definition of the UNICODE preprocessor constant. Mixing usage of the encoding-neutral alias
with code that not encoding-neutral can lead to mismatches that result in compilation or runtime errors. For more
information, see Conventions for Function Prototypes.

Requirements

Minimum suppor ted client Windows XP [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header aclapi.h

Librar y Advapi32.lib

DLL Advapi32.dll

See also
Access Control Overview
Basic Access Control Functions
BuildTrusteeWithObjectsAndName
BuildTrusteeWithObjectsAndSid
BuildTrusteeWithSid
TRUSTEE
 BuildTrusteeWithObjectsAndNameA function
(aclapi.h)
7/2/2022 • 2 minutes to read • Edit Online

The BuildTrusteeWithObjectsAndName function initializes a TRUSTEE structure with the object-specific

access control entry (ACE) information and initializes the remaining members of the structure to default values.
The caller also specifies the name of the trustee.

Syntax
void BuildTrusteeWithObjectsAndNameA(
[in, out] PTRUSTEE_A pTrustee,
[in, optional] POBJECTS_AND_NAME_A pObjName,
[in, optional] SE_OBJECT_TYPE ObjectType,
[in, optional] LPSTR ObjectTypeName,
[in, optional] LPSTR InheritedObjectTypeName,
[in, optional] LPSTR Name
);

Parameters
[in, out] pTrustee

A pointer to a TRUSTEE structure that will be initialized by this function. If the value of this parameter is NULL or
a pointer that is not valid, the results are undefined.
[in, optional] pObjName

A pointer to an OBJECTS_AND_NAME structure that contains information about the trustee and the securable
object.
[in, optional] ObjectType

A pointer to an SE_OBJECT_TYPE enumeration that contains information about the type of securable object.
[in, optional] ObjectTypeName

A pointer to a string that specifies the name that corresponds to the ObjectType GUID to be added to the
TRUSTEE structure returned in the pTrustee parameter. This function determines the ObjectType GUID that
corresponds to this name.
[in, optional] InheritedObjectTypeName

A pointer to a string that specifies the name that corresponds to the InheritedObjectType GUID to be added to
the TRUSTEE structure returned in the pTrustee parameter. This function determines the InheritedObjectType
GUID that corresponds to this name.
[in, optional] Name

A pointer to a string that specifies the name used to identify the trustee.

Return value
None

Remarks
This function does not allocate memory for the TRUSTEE and OBJECTS_AND_NAME structures.
For more information about object-specific ACEs, see Object-specific ACEs.

NOTE
The aclapi.h header defines BuildTrusteeWithObjectsAndName as an alias which automatically selects the ANSI or Unicode
version of this function based on the definition of the UNICODE preprocessor constant. Mixing usage of the encoding-
neutral alias with code that not encoding-neutral can lead to mismatches that result in compilation or runtime errors. For
more information, see Conventions for Function Prototypes.

Requirements

Minimum suppor ted client Windows XP [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header aclapi.h

Librar y Advapi32.lib

DLL Advapi32.dll

See also
Access Control
Basic Access Control Functions
BuildTrusteeWithName
BuildTrusteeWithObjectsAndSid
BuildTrusteeWithSid
OBJECTS_AND_NAME
Object-specific ACEs
SE_OBJECT_TYPE
TRUSTEE
 BuildTrusteeWithObjectsAndNameW function
(aclapi.h)
7/2/2022 • 2 minutes to read • Edit Online

The BuildTrusteeWithObjectsAndName function initializes a TRUSTEE structure with the object-specific

access control entry (ACE) information and initializes the remaining members of the structure to default values.
The caller also specifies the name of the trustee.

Syntax
void BuildTrusteeWithObjectsAndNameW(
[in, out] PTRUSTEE_W pTrustee,
[in, optional] POBJECTS_AND_NAME_W pObjName,
[in, optional] SE_OBJECT_TYPE ObjectType,
[in, optional] LPWSTR ObjectTypeName,
[in, optional] LPWSTR InheritedObjectTypeName,
[in, optional] LPWSTR Name
);

Parameters
[in, out] pTrustee

A pointer to a TRUSTEE structure that will be initialized by this function. If the value of this parameter is NULL or
a pointer that is not valid, the results are undefined.
[in, optional] pObjName

A pointer to an OBJECTS_AND_NAME structure that contains information about the trustee and the securable
object.
[in, optional] ObjectType

A pointer to an SE_OBJECT_TYPE enumeration that contains information about the type of securable object.
[in, optional] ObjectTypeName

A pointer to a string that specifies the name that corresponds to the ObjectType GUID to be added to the
TRUSTEE structure returned in the pTrustee parameter. This function determines the ObjectType GUID that
corresponds to this name.
[in, optional] InheritedObjectTypeName

A pointer to a string that specifies the name that corresponds to the InheritedObjectType GUID to be added to
the TRUSTEE structure returned in the pTrustee parameter. This function determines the InheritedObjectType
GUID that corresponds to this name.
[in, optional] Name

A pointer to a string that specifies the name used to identify the trustee.

Return value
None

Remarks
This function does not allocate memory for the TRUSTEE and OBJECTS_AND_NAME structures.
For more information about object-specific ACEs, see Object-specific ACEs.

NOTE
The aclapi.h header defines BuildTrusteeWithObjectsAndName as an alias which automatically selects the ANSI or Unicode
version of this function based on the definition of the UNICODE preprocessor constant. Mixing usage of the encoding-
neutral alias with code that not encoding-neutral can lead to mismatches that result in compilation or runtime errors. For
more information, see Conventions for Function Prototypes.

Requirements

Minimum suppor ted client Windows XP [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header aclapi.h

Librar y Advapi32.lib

DLL Advapi32.dll

See also
Access Control
Basic Access Control Functions
BuildTrusteeWithName
BuildTrusteeWithObjectsAndSid
BuildTrusteeWithSid
OBJECTS_AND_NAME
Object-specific ACEs
SE_OBJECT_TYPE
TRUSTEE
 BuildTrusteeWithObjectsAndSidA function (aclapi.h)
7/2/2022 • 2 minutes to read • Edit Online

The BuildTrusteeWithObjectsAndSid function initializes a TRUSTEE structure with the object-specific access
control entry (ACE) information and initializes the remaining members of the structure to default values. The
caller also specifies the SID structure that represents the security identifier of the trustee.

Syntax
void BuildTrusteeWithObjectsAndSidA(
[in, out] PTRUSTEE_A pTrustee,
[in, optional] POBJECTS_AND_SID pObjSid,
[in, optional] GUID *pObjectGuid,
[in, optional] GUID *pInheritedObjectGuid,
[in, optional] PSID pSid
);

Parameters
[in, out] pTrustee

A pointer to a TRUSTEE structure to initialize. The BuildTrusteeWithObjectsAndSid function does not allocate
any memory. If this parameter is NULL or a pointer that is not valid, the results are undefined.
[in, optional] pObjSid

A pointer to an OBJECTS_AND_SID structure that contains information about the trustee and the securable
object.
[in, optional] pObjectGuid

A pointer to a GUID structure that describes the ObjectType GUID to be added to the TRUSTEE structure.
[in, optional] pInheritedObjectGuid

A pointer to a GUID structure that describes the InheritedObjectType GUID to be added to the TRUSTEE
structure.
[in, optional] pSid

A pointer to a SID structure that identifies the trustee.

Return value
None

Remarks
This function does not allocate memory for the TRUSTEE and OBJECTS_AND_SID structures.
For more information about object-specific ACEs, see Object-specific ACEs.
 NOTE
The aclapi.h header defines BuildTrusteeWithObjectsAndSid as an alias which automatically selects the ANSI or Unicode
version of this function based on the definition of the UNICODE preprocessor constant. Mixing usage of the encoding-
neutral alias with code that not encoding-neutral can lead to mismatches that result in compilation or runtime errors. For
more information, see Conventions for Function Prototypes.

Requirements

Minimum suppor ted client Windows XP [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header aclapi.h

Librar y Advapi32.lib

DLL Advapi32.dll

See also
Access Control
Basic Access Control Functions
BuildTrusteeWithName
BuildTrusteeWithObjectsAndName
BuildTrusteeWithSid
OBJECTS_AND_NAME
Object-specific ACEs
SE_OBJECT_TYPE
SID
TRUSTEE
 BuildTrusteeWithObjectsAndSidW function (aclapi.h)
7/2/2022 • 2 minutes to read • Edit Online

The BuildTrusteeWithObjectsAndSid function initializes a TRUSTEE structure with the object-specific access
control entry (ACE) information and initializes the remaining members of the structure to default values. The
caller also specifies the SID structure that represents the security identifier of the trustee.

Syntax
void BuildTrusteeWithObjectsAndSidW(
[in, out] PTRUSTEE_W pTrustee,
[in, optional] POBJECTS_AND_SID pObjSid,
[in, optional] GUID *pObjectGuid,
[in, optional] GUID *pInheritedObjectGuid,
[in, optional] PSID pSid
);

Parameters
[in, out] pTrustee

A pointer to a TRUSTEE structure to initialize. The BuildTrusteeWithObjectsAndSid function does not allocate
any memory. If this parameter is NULL or a pointer that is not valid, the results are undefined.
[in, optional] pObjSid

A pointer to an OBJECTS_AND_SID structure that contains information about the trustee and the securable
object.
[in, optional] pObjectGuid

A pointer to a GUID structure that describes the ObjectType GUID to be added to the TRUSTEE structure.
[in, optional] pInheritedObjectGuid

A pointer to a GUID structure that describes the InheritedObjectType GUID to be added to the TRUSTEE
structure.
[in, optional] pSid

A pointer to a SID structure that identifies the trustee.

Return value
None

Remarks
This function does not allocate memory for the TRUSTEE and OBJECTS_AND_SID structures.
For more information about object-specific ACEs, see Object-specific ACEs.
 NOTE
The aclapi.h header defines BuildTrusteeWithObjectsAndSid as an alias which automatically selects the ANSI or Unicode
version of this function based on the definition of the UNICODE preprocessor constant. Mixing usage of the encoding-
neutral alias with code that not encoding-neutral can lead to mismatches that result in compilation or runtime errors. For
more information, see Conventions for Function Prototypes.

Requirements

Minimum suppor ted client Windows XP [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header aclapi.h

Librar y Advapi32.lib

DLL Advapi32.dll

See also
Access Control
Basic Access Control Functions
BuildTrusteeWithName
BuildTrusteeWithObjectsAndName
BuildTrusteeWithSid
OBJECTS_AND_NAME
Object-specific ACEs
SE_OBJECT_TYPE
SID
TRUSTEE
 BuildTrusteeWithSidA function (aclapi.h)
7/2/2022 • 2 minutes to read • Edit Online

The BuildTrusteeWithSid function initializes a TRUSTEE structure. The caller specifies the security identifier
(SID) of the trustee. The function sets other members of the structure to default values and does not look up the
name associated with the SID.

Syntax
void BuildTrusteeWithSidA(
[in, out] PTRUSTEE_A pTrustee,
[in, optional] PSID pSid
);

Parameters
[in, out] pTrustee

A pointer to a TRUSTEE structure to initialize. The BuildTrusteeWithSid function does not allocate any
memory. If this parameter is NULL or a pointer that is not valid, the results are undefined.
[in, optional] pSid

A pointer to a SID structure that identifies the trustee. The BuildTrusteeWithSid function assigns this pointer to
the ptstrName member of the TRUSTEE structure. The function sets the other members of the TRUSTEE
structure as follows.

VA L UE M EA N IN G

NULL
pMultipleTrustee

NO_MULTIPLE_TRUSTEE
MultipleTrusteeOperation

TRUSTEE_IS_SID
TrusteeForm

TRUSTEE_IS_UNKNOWN
TrusteeType

Return value
None

Remarks
 NOTE
The aclapi.h header defines BuildTrusteeWithSid as an alias which automatically selects the ANSI or Unicode version of this
function based on the definition of the UNICODE preprocessor constant. Mixing usage of the encoding-neutral alias with
code that not encoding-neutral can lead to mismatches that result in compilation or runtime errors. For more
information, see Conventions for Function Prototypes.

Requirements

Minimum suppor ted client Windows XP [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header aclapi.h

Librar y Advapi32.lib

DLL Advapi32.dll

See also
Access Control Overview
Basic Access Control Functions
BuildTrusteeWithName
BuildTrusteeWithObjectsAndName
BuildTrusteeWithObjectsAndSid
TRUSTEE
 BuildTrusteeWithSidW function (aclapi.h)
7/2/2022 • 2 minutes to read • Edit Online

The BuildTrusteeWithSid function initializes a TRUSTEE structure. The caller specifies the security identifier
(SID) of the trustee. The function sets other members of the structure to default values and does not look up the
name associated with the SID.

Syntax
void BuildTrusteeWithSidW(
[in, out] PTRUSTEE_W pTrustee,
[in, optional] PSID pSid
);

Parameters
[in, out] pTrustee

A pointer to a TRUSTEE structure to initialize. The BuildTrusteeWithSid function does not allocate any
memory. If this parameter is NULL or a pointer that is not valid, the results are undefined.
[in, optional] pSid

A pointer to a SID structure that identifies the trustee. The BuildTrusteeWithSid function assigns this pointer to
the ptstrName member of the TRUSTEE structure. The function sets the other members of the TRUSTEE
structure as follows.

VA L UE M EA N IN G

NULL
pMultipleTrustee

NO_MULTIPLE_TRUSTEE
MultipleTrusteeOperation

TRUSTEE_IS_SID
TrusteeForm

TRUSTEE_IS_UNKNOWN
TrusteeType

Return value
None

Remarks
 NOTE
The aclapi.h header defines BuildTrusteeWithSid as an alias which automatically selects the ANSI or Unicode version of this
function based on the definition of the UNICODE preprocessor constant. Mixing usage of the encoding-neutral alias with
code that not encoding-neutral can lead to mismatches that result in compilation or runtime errors. For more
information, see Conventions for Function Prototypes.

Requirements

Minimum suppor ted client Windows XP [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header aclapi.h

Librar y Advapi32.lib

DLL Advapi32.dll

See also
Access Control Overview
Basic Access Control Functions
BuildTrusteeWithName
BuildTrusteeWithObjectsAndName
BuildTrusteeWithObjectsAndSid
TRUSTEE
 FreeInheritedFromArray function (aclapi.h)
7/2/2022 • 2 minutes to read • Edit Online

The FreeInheritedFromArray function frees memory allocated by the GetInheritanceSource function.

Syntax
DWORD FreeInheritedFromArray(
[in] PINHERITED_FROMW pInheritArray,
[in] USHORT AceCnt,
[in, optional] PFN_OBJECT_MGR_FUNCTS pfnArray
);

Parameters
[in] pInheritArray

A pointer to the array of INHERITED_FROM structures returned by GetInheritanceSource.

[in] AceCnt

Number of entries in pInheritArray.

[in, optional] pfnArray

Unused. Set to NULL .

Return value
If the function succeeds, the function returns ERROR_SUCCESS.
If the function fails, it returns a nonzero error code defined in WinError.h.

Requirements

Minimum suppor ted client Windows XP [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header aclapi.h

Librar y Advapi32.lib

DLL Advapi32.dll

See also
GetInheritanceSource
 GetAuditedPermissionsFromAclA function (aclapi.h)
7/2/2022 • 2 minutes to read • Edit Online

The GetAuditedPermissionsFromAcl function retrieves the audited access rights for a specified trustee. The
audited rights are based on the access control entries (ACEs) of a specified access control list (ACL). The audited
access rights indicate the types of access attempts that cause the system to generate an audit record in the
system event log. The audited rights include those that the ACL specifies for the trustee or for any groups of
which the trustee is a member. In determining the audited rights, the function does not consider the security
privileges held by the trustee.

Syntax
DWORD GetAuditedPermissionsFromAclA(
[in] PACL pacl,
[in] PTRUSTEE_A pTrustee,
[out] PACCESS_MASK pSuccessfulAuditedRights,
[out] PACCESS_MASK pFailedAuditRights
);

Parameters
[in] pacl

A pointer to an ACL structure from which to get the trustee's audited access rights.
[in] pTrustee

A pointer to a TRUSTEE structure that identifies the trustee. A trustee can be a user, group, or program (such as a
Windows service). You can use a name or a security identifier (SID) to identify a trustee. For information about
SID structures, see SID.
[out] pSuccessfulAuditedRights

A pointer to an ACCESS_MASK structure that receives the successful audit mask for rights audited for the trustee
specified by the pTrustee parameter. The system generates an audit record when the trustee successfully uses
any of these access rights.
[out] pFailedAuditRights

A pointer to an ACCESS_MASK structure that receives the failed audit mask for rights audited for the trustee
specified by the pTrustee parameter. The system generates an audit record when the trustee fails in an attempt
to use any of these rights.

Return value
If the function succeeds, the function returns ERROR_SUCCESS.
If the function fails, it returns a nonzero error code defined in WinError.h.

Remarks
The GetAuditedPermissionsFromAcl function checks all system-audit ACEs in the ACL to determine the
audited rights for the trustee. For all ACEs that specify audited rights for a group,
GetAuditedPermissionsFromAcl enumerates the members of the group to determine whether the trustee is
a member. The function returns an error if it cannot enumerate the members of a group.

NOTE
The aclapi.h header defines GetAuditedPermissionsFromAcl as an alias which automatically selects the ANSI or Unicode
version of this function based on the definition of the UNICODE preprocessor constant. Mixing usage of the encoding-
neutral alias with code that not encoding-neutral can lead to mismatches that result in compilation or runtime errors. For
more information, see Conventions for Function Prototypes.

Requirements

Minimum suppor ted client Windows XP [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header aclapi.h

Librar y Advapi32.lib

DLL Advapi32.dll

See also
ACCESS_MASK
ACE
ACL
Access Control Overview
Basic Access Control Functions
GetEffectiveRightsFromAcl
SID
SYSTEM_AUDIT_ACE
TRUSTEE
 GetAuditedPermissionsFromAclW function (aclapi.h)
7/2/2022 • 2 minutes to read • Edit Online

The GetAuditedPermissionsFromAcl function retrieves the audited access rights for a specified trustee. The
audited rights are based on the access control entries (ACEs) of a specified access control list (ACL). The audited
access rights indicate the types of access attempts that cause the system to generate an audit record in the
system event log. The audited rights include those that the ACL specifies for the trustee or for any groups of
which the trustee is a member. In determining the audited rights, the function does not consider the security
privileges held by the trustee.

Syntax
DWORD GetAuditedPermissionsFromAclW(
[in] PACL pacl,
[in] PTRUSTEE_W pTrustee,
[out] PACCESS_MASK pSuccessfulAuditedRights,
[out] PACCESS_MASK pFailedAuditRights
);

Parameters
[in] pacl

A pointer to an ACL structure from which to get the trustee's audited access rights.
[in] pTrustee

A pointer to a TRUSTEE structure that identifies the trustee. A trustee can be a user, group, or program (such as a
Windows service). You can use a name or a security identifier (SID) to identify a trustee. For information about
SID structures, see SID.
[out] pSuccessfulAuditedRights

A pointer to an ACCESS_MASK structure that receives the successful audit mask for rights audited for the trustee
specified by the pTrustee parameter. The system generates an audit record when the trustee successfully uses
any of these access rights.
[out] pFailedAuditRights

A pointer to an ACCESS_MASK structure that receives the failed audit mask for rights audited for the trustee
specified by the pTrustee parameter. The system generates an audit record when the trustee fails in an attempt
to use any of these rights.

Return value
If the function succeeds, the function returns ERROR_SUCCESS.
If the function fails, it returns a nonzero error code defined in WinError.h.

Remarks
The GetAuditedPermissionsFromAcl function checks all system-audit ACEs in the ACL to determine the
audited rights for the trustee. For all ACEs that specify audited rights for a group,
GetAuditedPermissionsFromAcl enumerates the members of the group to determine whether the trustee is
a member. The function returns an error if it cannot enumerate the members of a group.

NOTE
The aclapi.h header defines GetAuditedPermissionsFromAcl as an alias which automatically selects the ANSI or Unicode
version of this function based on the definition of the UNICODE preprocessor constant. Mixing usage of the encoding-
neutral alias with code that not encoding-neutral can lead to mismatches that result in compilation or runtime errors. For
more information, see Conventions for Function Prototypes.

Requirements

Minimum suppor ted client Windows XP [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header aclapi.h

Librar y Advapi32.lib

DLL Advapi32.dll

See also
ACCESS_MASK
ACE
ACL
Access Control Overview
Basic Access Control Functions
GetEffectiveRightsFromAcl
SID
SYSTEM_AUDIT_ACE
TRUSTEE
 GetEffectiveRightsFromAclA function (aclapi.h)
7/2/2022 • 5 minutes to read • Edit Online

[GetEffectiveRightsFromAcl is available for use in the operating systems specified in the Requirements
section. It may be altered or unavailable in subsequent versions. Instead, use the method demonstrated in the
example below.]
The GetEffectiveRightsFromAcl function retrieves the effective access rights that an ACL structure grants to a
specified trustee. The trustee's effective access rights are the access rights that the ACL grants to the trustee or
to any groups of which the trustee is a member.

Syntax
DWORD GetEffectiveRightsFromAclA(
[in] PACL pacl,
[in] PTRUSTEE_A pTrustee,
[out] PACCESS_MASK pAccessRights
);

Parameters
[in] pacl

A pointer to an ACL structure from which to get the trustee's effective access rights.
[in] pTrustee

A pointer to a TRUSTEE structure that identifies the trustee. A trustee can be a user, group, or program (such as a
Windows service). You can use a name or a security identifier (SID) to identify a trustee.
[out] pAccessRights

A pointer to an ACCESS_MASK variable that receives the effective access rights of the trustee.

Return value
If the function succeeds, the function returns ERROR_SUCCESS.
If the function fails, it returns a nonzero error code defined in WinError.h.

Remarks
The GetEffectiveRightsFromAcl function checks all access-allowed and access-denied access control entries
(ACEs) in the access control list (ACL) to determine the effective rights for the trustee. For all ACEs that allow or
deny rights to a group, GetEffectiveRightsFromAcl enumerates the members of the group to determine
whether the trustee is a member. The function returns an error if it cannot enumerate the members of a group.
A trustee's group rights are enumerated by GetEffectiveRightsFromAcl on the local computer, even if the
trustee is accessing objects on a remote computer. This function does not evaluate group rights on remote
computers.
The GetEffectiveRightsFromAcl function does not consider the following:
 Implicitly granted access rights, such as READ_CONTROL and WRITE_DAC, for the owner of an object when
determining effective rights.
Privileges held by the trustee when determining effective access rights.
Group rights associated with the logon session, such as interactive, network, authenticated users, and so
forth, in determining effective access rights.
Resource manager policy. For example, for file objects, Delete and Read attributes can be provided by the
parent even if they have been denied on the object.
The GetEffectiveRightsFromAcl function fails and returns ERROR_INVALID_ACL if the specified ACL contains
an inherited access-denied ACE.
Examples
The following example shows using Authz API to get effective access rights from an ACL.

// Copyright (C) Microsoft. All rights reserved.

#include <windows.h>
#include <stdio.h>
#include <aclapi.h>
#include <tchar.h>
#include <strsafe.h> // for proper buffer handling
#include <authz.h>

#pragma comment(lib, "advapi32.lib")

#pragma comment(lib, "authz.lib")

LPTSTR lpServerName = NULL;

PSID ConvertNameToBinarySid(LPTSTR pAccountName)

{
LPTSTR pDomainName = NULL;
DWORD dwDomainNameSize = 0;
PSID pSid = NULL;
DWORD dwSidSize = 0;
SID_NAME_USE sidType;
BOOL fSuccess = FALSE;
HRESULT hr = S_OK;

__try
{
LookupAccountName(
lpServerName, // look up on local system
pAccountName,
pSid, // buffer to receive name
&dwSidSize,
pDomainName,
&dwDomainNameSize,
&sidType);

// If the Name cannot be resolved, LookupAccountName will fail with

// ERROR_NONE_MAPPED.
if (GetLastError() == ERROR_NONE_MAPPED)
{
wprintf_s(_T("LookupAccountName failed with %d\n"), GetLastError());
__leave;
}
else if (GetLastError() == ERROR_INSUFFICIENT_BUFFER)
{
pSid = (LPTSTR)LocalAlloc(LPTR, dwSidSize * sizeof(TCHAR));
if (pSid == NULL)
{
wprintf_s(_T("LocalAlloc failed with %d\n"), GetLastError());
__leave;
 }

pDomainName = (LPTSTR)LocalAlloc(LPTR, dwDomainNameSize * sizeof(TCHAR));

if (pDomainName == NULL)
{
wprintf_s(_T("LocalAlloc failed with %d\n"), GetLastError());
__leave;
}

if (!LookupAccountName(
lpServerName, // look up on local system
pAccountName,
pSid, // buffer to receive name
&dwSidSize,
pDomainName,
&dwDomainNameSize,
&sidType))
{
wprintf_s(_T("LookupAccountName failed with %d\n"), GetLastError());
__leave;
}
}

// Any other error code

else
{
wprintf_s(_T("LookupAccountName failed with %d\n"), GetLastError());
__leave;
}

fSuccess = TRUE;
}
__finally
{
if(pDomainName != NULL)
{
LocalFree(pDomainName);
pDomainName = NULL;
}

// Free pSid only if failed;

// otherwise, the caller has to free it after use.
if (fSuccess == FALSE)
{
if(pSid != NULL)
{
LocalFree(pSid);
pSid = NULL;
}
}
}

return pSid;
}

void DisplayError(char* pszAPI, DWORD dwError)

{
LPVOID lpvMessageBuffer;

if (!FormatMessage(FORMAT_MESSAGE_ALLOCATE_BUFFER | FORMAT_MESSAGE_FROM_HMODULE |
FORMAT_MESSAGE_FROM_SYSTEM,
GetModuleHandle(L"Kernel32.dll"), dwError,
MAKELANGID(LANG_NEUTRAL, SUBLANG_DEFAULT), // the user default language
(LPTSTR)&lpvMessageBuffer, 0, NULL))
{
wprintf_s(L"FormatMessage failed with %d\n", GetLastError());
ExitProcess(GetLastError());
}
 // ...now display this string.
wprintf_s(L"ERROR: API = %s.\n", (char *)pszAPI);
wprintf_s(L" error code = %08X.\n", dwError);
wprintf_s(L" message = %s.\n", (char *)lpvMessageBuffer);

// Free the buffer allocated by the system.

LocalFree(lpvMessageBuffer);

ExitProcess(GetLastError());
}

void DisplayAccessMask(ACCESS_MASK Mask)

{
// This evaluation of the ACCESS_MASK is an example.
// Applications should evaluate the ACCESS_MASK as necessary.

wprintf_s(L"Effective Allowed Access Mask : %8X\n", Mask);

if (((Mask & GENERIC_ALL) == GENERIC_ALL)
|| ((Mask & FILE_ALL_ACCESS) == FILE_ALL_ACCESS))
{
wprintf_s(L"Full Control\n");
return;
}
if (((Mask & GENERIC_READ) == GENERIC_READ)
|| ((Mask & FILE_GENERIC_READ) == FILE_GENERIC_READ))
wprintf_s(L"Read\n");
if (((Mask & GENERIC_WRITE) == GENERIC_WRITE)
|| ((Mask & FILE_GENERIC_WRITE) == FILE_GENERIC_WRITE))
wprintf_s(L"Write\n");
if (((Mask & GENERIC_EXECUTE) == GENERIC_EXECUTE)
|| ((Mask & FILE_GENERIC_EXECUTE) == FILE_GENERIC_EXECUTE))
wprintf_s(L"Execute\n");

void GetAccess(AUTHZ_CLIENT_CONTEXT_HANDLE hAuthzClient, PSECURITY_DESCRIPTOR psd)

{
AUTHZ_ACCESS_REQUEST AccessRequest = {0};
AUTHZ_ACCESS_REPLY AccessReply = {0};
BYTE Buffer[1024];
BOOL bRes = FALSE; // assume error

// Do AccessCheck.
AccessRequest.DesiredAccess = MAXIMUM_ALLOWED;
AccessRequest.PrincipalSelfSid = NULL;
AccessRequest.ObjectTypeList = NULL;
AccessRequest.ObjectTypeListLength = 0;
AccessRequest.OptionalArguments = NULL;

RtlZeroMemory(Buffer, sizeof(Buffer));
AccessReply.ResultListLength = 1;
AccessReply.GrantedAccessMask = (PACCESS_MASK) (Buffer);
AccessReply.Error = (PDWORD) (Buffer + sizeof(ACCESS_MASK));

if (!AuthzAccessCheck( 0,
hAuthzClient,
&AccessRequest,
NULL,
psd,
NULL,
0,
&AccessReply,
NULL) ) {
wprintf_s(_T("AuthzAccessCheck failed with %d\n"), GetLastError());
}
else
DisplayAccessMask(*(PACCESS_MASK)(AccessReply.GrantedAccessMask));
 DisplayAccessMask(*(PACCESS_MASK)(AccessReply.GrantedAccessMask));

return;
}

BOOL GetEffectiveRightsForUser(AUTHZ_RESOURCE_MANAGER_HANDLE hManager,

PSECURITY_DESCRIPTOR psd,
LPTSTR lpszUserName)
{
PSID pSid = NULL;
BOOL bResult = FALSE;
LUID unusedId = { 0 };
AUTHZ_CLIENT_CONTEXT_HANDLE hAuthzClientContext = NULL;

pSid = ConvertNameToBinarySid(lpszUserName);
if (pSid != NULL)
{
bResult = AuthzInitializeContextFromSid(0,
pSid,
hManager,
NULL,
unusedId,
NULL,
&hAuthzClientContext);
if (bResult)
{
GetAccess(hAuthzClientContext, psd);
AuthzFreeContext(hAuthzClientContext);
}
else
wprintf_s(_T("AuthzInitializeContextFromSid failed with %d\n"), GetLastError());
}
if(pSid != NULL)
{
LocalFree(pSid);
pSid = NULL;
}

return bResult;
}

void UseAuthzSolution(PSECURITY_DESCRIPTOR psd, LPTSTR lpszUserName)

{
AUTHZ_RESOURCE_MANAGER_HANDLE hManager;
BOOL bResult = FALSE;

bResult = AuthzInitializeResourceManager(AUTHZ_RM_FLAG_NO_AUDIT,
NULL, NULL, NULL, NULL, &hManager);
if (bResult)
{
bResult = GetEffectiveRightsForUser(hManager, psd, lpszUserName);
AuthzFreeResourceManager(hManager);
}
else
wprintf_s(_T("AuthzInitializeResourceManager failed with %d\n"), GetLastError());
}

void wmain(int argc, wchar_t *argv[])

{
DWORD dw;
PACL pacl;
PSECURITY_DESCRIPTOR psd;
PSID psid = NULL;

if (argc != 3)
{
wprintf_s(L"Usage: FileOrFolderName UserOrGroupName\n");
wprintf_s(L"Usage: FileOrFolderName UserOrGroupName\n");
return;
 return;
}

dw = GetNamedSecurityInfo(argv[1], SE_FILE_OBJECT, DACL_SECURITY_INFORMATION |

OWNER_SECURITY_INFORMATION |
GROUP_SECURITY_INFORMATION, NULL, NULL, &pacl, NULL, &psd);
if (dw != ERROR_SUCCESS)
{ printf("couldn't do getnamedsecinfo \n");
DisplayError("GetNamedSecurityInfo", dw);
}

UseAuthzSolution(psd, argv[2]);

if(psid != NULL)
{
LocalFree(psid);
psid = NULL;
};

LocalFree(psd);
}

NOTE
The aclapi.h header defines GetEffectiveRightsFromAcl as an alias which automatically selects the ANSI or Unicode version
of this function based on the definition of the UNICODE preprocessor constant. Mixing usage of the encoding-neutral
alias with code that not encoding-neutral can lead to mismatches that result in compilation or runtime errors. For more
information, see Conventions for Function Prototypes.

Requirements

Minimum suppor ted client Windows XP [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header aclapi.h

Librar y Advapi32.lib

DLL Advapi32.dll

See also
ACCESS_ALLOWED_ACE
ACCESS_DENIED_ACE
ACCESS_MASK
ACE
ACL
Access Control Overview
Basic Access Control Functions
GetAuditedPermissionsFromAcl
SID
TRUSTEE
 GetEffectiveRightsFromAclW function (aclapi.h)
7/2/2022 • 5 minutes to read • Edit Online

[GetEffectiveRightsFromAcl is available for use in the operating systems specified in the Requirements
section. It may be altered or unavailable in subsequent versions. Instead, use the method demonstrated in the
example below.]
The GetEffectiveRightsFromAcl function retrieves the effective access rights that an ACL structure grants to a
specified trustee. The trustee's effective access rights are the access rights that the ACL grants to the trustee or
to any groups of which the trustee is a member.

Syntax
DWORD GetEffectiveRightsFromAclW(
[in] PACL pacl,
[in] PTRUSTEE_W pTrustee,
[out] PACCESS_MASK pAccessRights
);

Parameters
[in] pacl

A pointer to an ACL structure from which to get the trustee's effective access rights.
[in] pTrustee

A pointer to a TRUSTEE structure that identifies the trustee. A trustee can be a user, group, or program (such as a
Windows service). You can use a name or a security identifier (SID) to identify a trustee.
[out] pAccessRights

A pointer to an ACCESS_MASK variable that receives the effective access rights of the trustee.

Return value
If the function succeeds, the function returns ERROR_SUCCESS.
If the function fails, it returns a nonzero error code defined in WinError.h.

Remarks
The GetEffectiveRightsFromAcl function checks all access-allowed and access-denied access control entries
(ACEs) in the access control list (ACL) to determine the effective rights for the trustee. For all ACEs that allow or
deny rights to a group, GetEffectiveRightsFromAcl enumerates the members of the group to determine
whether the trustee is a member. The function returns an error if it cannot enumerate the members of a group.
A trustee's group rights are enumerated by GetEffectiveRightsFromAcl on the local computer, even if the
trustee is accessing objects on a remote computer. This function does not evaluate group rights on remote
computers.
The GetEffectiveRightsFromAcl function does not consider the following:
 Implicitly granted access rights, such as READ_CONTROL and WRITE_DAC, for the owner of an object when
determining effective rights.
Privileges held by the trustee when determining effective access rights.
Group rights associated with the logon session, such as interactive, network, authenticated users, and so
forth, in determining effective access rights.
Resource manager policy. For example, for file objects, Delete and Read attributes can be provided by the
parent even if they have been denied on the object.
The GetEffectiveRightsFromAcl function fails and returns ERROR_INVALID_ACL if the specified ACL contains
an inherited access-denied ACE.
Examples
The following example shows using Authz API to get effective access rights from an ACL.

// Copyright (C) Microsoft. All rights reserved.

#include <windows.h>
#include <stdio.h>
#include <aclapi.h>
#include <tchar.h>
#include <strsafe.h> // for proper buffer handling
#include <authz.h>

#pragma comment(lib, "advapi32.lib")

#pragma comment(lib, "authz.lib")

LPTSTR lpServerName = NULL;

PSID ConvertNameToBinarySid(LPTSTR pAccountName)

{
LPTSTR pDomainName = NULL;
DWORD dwDomainNameSize = 0;
PSID pSid = NULL;
DWORD dwSidSize = 0;
SID_NAME_USE sidType;
BOOL fSuccess = FALSE;
HRESULT hr = S_OK;

__try
{
LookupAccountName(
lpServerName, // look up on local system
pAccountName,
pSid, // buffer to receive name
&dwSidSize,
pDomainName,
&dwDomainNameSize,
&sidType);

// If the Name cannot be resolved, LookupAccountName will fail with

// ERROR_NONE_MAPPED.
if (GetLastError() == ERROR_NONE_MAPPED)
{
wprintf_s(_T("LookupAccountName failed with %d\n"), GetLastError());
__leave;
}
else if (GetLastError() == ERROR_INSUFFICIENT_BUFFER)
{
pSid = (LPTSTR)LocalAlloc(LPTR, dwSidSize * sizeof(TCHAR));
if (pSid == NULL)
{
wprintf_s(_T("LocalAlloc failed with %d\n"), GetLastError());
__leave;
 }

pDomainName = (LPTSTR)LocalAlloc(LPTR, dwDomainNameSize * sizeof(TCHAR));

if (pDomainName == NULL)
{
wprintf_s(_T("LocalAlloc failed with %d\n"), GetLastError());
__leave;
}

if (!LookupAccountName(
lpServerName, // look up on local system
pAccountName,
pSid, // buffer to receive name
&dwSidSize,
pDomainName,
&dwDomainNameSize,
&sidType))
{
wprintf_s(_T("LookupAccountName failed with %d\n"), GetLastError());
__leave;
}
}

// Any other error code

else
{
wprintf_s(_T("LookupAccountName failed with %d\n"), GetLastError());
__leave;
}

fSuccess = TRUE;
}
__finally
{
if(pDomainName != NULL)
{
LocalFree(pDomainName);
pDomainName = NULL;
}

// Free pSid only if failed;

// otherwise, the caller has to free it after use.
if (fSuccess == FALSE)
{
if(pSid != NULL)
{
LocalFree(pSid);
pSid = NULL;
}
}
}

return pSid;
}

void DisplayError(char* pszAPI, DWORD dwError)

{
LPVOID lpvMessageBuffer;

if (!FormatMessage(FORMAT_MESSAGE_ALLOCATE_BUFFER | FORMAT_MESSAGE_FROM_HMODULE |
FORMAT_MESSAGE_FROM_SYSTEM,
GetModuleHandle(L"Kernel32.dll"), dwError,
MAKELANGID(LANG_NEUTRAL, SUBLANG_DEFAULT), // the user default language
(LPTSTR)&lpvMessageBuffer, 0, NULL))
{
wprintf_s(L"FormatMessage failed with %d\n", GetLastError());
ExitProcess(GetLastError());
}
 // ...now display this string.
wprintf_s(L"ERROR: API = %s.\n", (char *)pszAPI);
wprintf_s(L" error code = %08X.\n", dwError);
wprintf_s(L" message = %s.\n", (char *)lpvMessageBuffer);

// Free the buffer allocated by the system.

LocalFree(lpvMessageBuffer);

ExitProcess(GetLastError());
}

void DisplayAccessMask(ACCESS_MASK Mask)

{
// This evaluation of the ACCESS_MASK is an example.
// Applications should evaluate the ACCESS_MASK as necessary.

wprintf_s(L"Effective Allowed Access Mask : %8X\n", Mask);

if (((Mask & GENERIC_ALL) == GENERIC_ALL)
|| ((Mask & FILE_ALL_ACCESS) == FILE_ALL_ACCESS))
{
wprintf_s(L"Full Control\n");
return;
}
if (((Mask & GENERIC_READ) == GENERIC_READ)
|| ((Mask & FILE_GENERIC_READ) == FILE_GENERIC_READ))
wprintf_s(L"Read\n");
if (((Mask & GENERIC_WRITE) == GENERIC_WRITE)
|| ((Mask & FILE_GENERIC_WRITE) == FILE_GENERIC_WRITE))
wprintf_s(L"Write\n");
if (((Mask & GENERIC_EXECUTE) == GENERIC_EXECUTE)
|| ((Mask & FILE_GENERIC_EXECUTE) == FILE_GENERIC_EXECUTE))
wprintf_s(L"Execute\n");

void GetAccess(AUTHZ_CLIENT_CONTEXT_HANDLE hAuthzClient, PSECURITY_DESCRIPTOR psd)

{
AUTHZ_ACCESS_REQUEST AccessRequest = {0};
AUTHZ_ACCESS_REPLY AccessReply = {0};
BYTE Buffer[1024];
BOOL bRes = FALSE; // assume error

// Do AccessCheck.
AccessRequest.DesiredAccess = MAXIMUM_ALLOWED;
AccessRequest.PrincipalSelfSid = NULL;
AccessRequest.ObjectTypeList = NULL;
AccessRequest.ObjectTypeListLength = 0;
AccessRequest.OptionalArguments = NULL;

RtlZeroMemory(Buffer, sizeof(Buffer));
AccessReply.ResultListLength = 1;
AccessReply.GrantedAccessMask = (PACCESS_MASK) (Buffer);
AccessReply.Error = (PDWORD) (Buffer + sizeof(ACCESS_MASK));

if (!AuthzAccessCheck( 0,
hAuthzClient,
&AccessRequest,
NULL,
psd,
NULL,
0,
&AccessReply,
NULL) ) {
wprintf_s(_T("AuthzAccessCheck failed with %d\n"), GetLastError());
}
else
DisplayAccessMask(*(PACCESS_MASK)(AccessReply.GrantedAccessMask));
 DisplayAccessMask(*(PACCESS_MASK)(AccessReply.GrantedAccessMask));

return;
}

BOOL GetEffectiveRightsForUser(AUTHZ_RESOURCE_MANAGER_HANDLE hManager,

PSECURITY_DESCRIPTOR psd,
LPTSTR lpszUserName)
{
PSID pSid = NULL;
BOOL bResult = FALSE;
LUID unusedId = { 0 };
AUTHZ_CLIENT_CONTEXT_HANDLE hAuthzClientContext = NULL;

pSid = ConvertNameToBinarySid(lpszUserName);
if (pSid != NULL)
{
bResult = AuthzInitializeContextFromSid(0,
pSid,
hManager,
NULL,
unusedId,
NULL,
&hAuthzClientContext);
if (bResult)
{
GetAccess(hAuthzClientContext, psd);
AuthzFreeContext(hAuthzClientContext);
}
else
wprintf_s(_T("AuthzInitializeContextFromSid failed with %d\n"), GetLastError());
}
if(pSid != NULL)
{
LocalFree(pSid);
pSid = NULL;
}

return bResult;
}

void UseAuthzSolution(PSECURITY_DESCRIPTOR psd, LPTSTR lpszUserName)

{
AUTHZ_RESOURCE_MANAGER_HANDLE hManager;
BOOL bResult = FALSE;

bResult = AuthzInitializeResourceManager(AUTHZ_RM_FLAG_NO_AUDIT,
NULL, NULL, NULL, NULL, &hManager);
if (bResult)
{
bResult = GetEffectiveRightsForUser(hManager, psd, lpszUserName);
AuthzFreeResourceManager(hManager);
}
else
wprintf_s(_T("AuthzInitializeResourceManager failed with %d\n"), GetLastError());
}

void wmain(int argc, wchar_t *argv[])

{
DWORD dw;
PACL pacl;
PSECURITY_DESCRIPTOR psd;
PSID psid = NULL;

if (argc != 3)
{
wprintf_s(L"Usage: FileOrFolderName UserOrGroupName\n");
wprintf_s(L"Usage: FileOrFolderName UserOrGroupName\n");
return;
 return;
}

dw = GetNamedSecurityInfo(argv[1], SE_FILE_OBJECT, DACL_SECURITY_INFORMATION |

OWNER_SECURITY_INFORMATION |
GROUP_SECURITY_INFORMATION, NULL, NULL, &pacl, NULL, &psd);
if (dw != ERROR_SUCCESS)
{ printf("couldn't do getnamedsecinfo \n");
DisplayError("GetNamedSecurityInfo", dw);
}

UseAuthzSolution(psd, argv[2]);

if(psid != NULL)
{
LocalFree(psid);
psid = NULL;
};

LocalFree(psd);
}

NOTE
The aclapi.h header defines GetEffectiveRightsFromAcl as an alias which automatically selects the ANSI or Unicode version
of this function based on the definition of the UNICODE preprocessor constant. Mixing usage of the encoding-neutral
alias with code that not encoding-neutral can lead to mismatches that result in compilation or runtime errors. For more
information, see Conventions for Function Prototypes.

Requirements

Minimum suppor ted client Windows XP [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header aclapi.h

Librar y Advapi32.lib

DLL Advapi32.dll

See also
ACCESS_ALLOWED_ACE
ACCESS_DENIED_ACE
ACCESS_MASK
ACE
ACL
Access Control Overview
Basic Access Control Functions
GetAuditedPermissionsFromAcl
SID
TRUSTEE
 GetExplicitEntriesFromAclA function (aclapi.h)
7/2/2022 • 2 minutes to read • Edit Online

The GetExplicitEntriesFromAcl function retrieves an array of structures that describe the access control
entries (ACEs) in an access control list (ACL).

Syntax
DWORD GetExplicitEntriesFromAclA(
[in] PACL pacl,
[out] PULONG pcCountOfExplicitEntries,
[out] PEXPLICIT_ACCESS_A *pListOfExplicitEntries
);

Parameters
[in] pacl

A pointer to an ACL structure from which to get ACE information.

[out] pcCountOfExplicitEntries

A pointer to a variable that receives the number of EXPLICIT_ACCESS structures returned in the
pListOfExplicitEntries array.
[out] pListOfExplicitEntries

A pointer to a variable that receives a pointer to an array of EXPLICIT_ACCESS structures that describe the ACEs
in the ACL. If the function succeeds, you must call the LocalFree function to free the returned buffer.

Return value
If the function succeeds, the function returns ERROR_SUCCESS.
If the function fails, it returns a nonzero error code defined in WinError.h.

Remarks
Each entry in the array of EXPLICIT_ACCESS structures describes access control information from an ACE for a
trustee. A trustee can be a user, group, or program (such as a Windows service).
Each EXPLICIT_ACCESS structure specifies a set of access rights and an access mode flag that indicates whether
the ACE allows, denies, or audits the specified rights.
For a discretionary access control list (DACL), the access mode flag can be either GRANT_ACCESS or
DENY_ACCESS. For information about these values, see ACCESS_MODE.
For a system access control list (SACL), the access mode flag can be SET_AUDIT_ACCESS, SET_AUDIT_FAILURE,
or both. For information about these values, see ACCESS_MODE.
 NOTE
The aclapi.h header defines GetExplicitEntriesFromAcl as an alias which automatically selects the ANSI or Unicode version
of this function based on the definition of the UNICODE preprocessor constant. Mixing usage of the encoding-neutral
alias with code that not encoding-neutral can lead to mismatches that result in compilation or runtime errors. For more
information, see Conventions for Function Prototypes.

Requirements

Minimum suppor ted client Windows XP [desktop apps | UWP apps]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps | UWP apps]

Target Platform Windows

Header aclapi.h

Librar y Advapi32.lib

DLL Advapi32.dll

See also
ACCESS_ALLOWED_ACE
ACCESS_DENIED_ACE
ACCESS_MODE
ACE
ACL
Access Control
Basic Access Control Functions
EXPLICIT_ACCESS
LocalFree
SYSTEM_AUDIT_ACE
 GetExplicitEntriesFromAclW function (aclapi.h)
7/2/2022 • 2 minutes to read • Edit Online

The GetExplicitEntriesFromAcl function retrieves an array of structures that describe the access control
entries (ACEs) in an access control list (ACL).

Syntax
DWORD GetExplicitEntriesFromAclW(
[in] PACL pacl,
[out] PULONG pcCountOfExplicitEntries,
[out] PEXPLICIT_ACCESS_W *pListOfExplicitEntries
);

Parameters
[in] pacl

A pointer to an ACL structure from which to get ACE information.

[out] pcCountOfExplicitEntries

A pointer to a variable that receives the number of EXPLICIT_ACCESS structures returned in the
pListOfExplicitEntries array.
[out] pListOfExplicitEntries

A pointer to a variable that receives a pointer to an array of EXPLICIT_ACCESS structures that describe the ACEs
in the ACL. If the function succeeds, you must call the LocalFree function to free the returned buffer.

Return value
If the function succeeds, the function returns ERROR_SUCCESS.
If the function fails, it returns a nonzero error code defined in WinError.h.

Remarks
Each entry in the array of EXPLICIT_ACCESS structures describes access control information from an ACE for a
trustee. A trustee can be a user, group, or program (such as a Windows service).
Each EXPLICIT_ACCESS structure specifies a set of access rights and an access mode flag that indicates whether
the ACE allows, denies, or audits the specified rights.
For a discretionary access control list (DACL), the access mode flag can be either GRANT_ACCESS or
DENY_ACCESS. For information about these values, see ACCESS_MODE.
For a system access control list (SACL), the access mode flag can be SET_AUDIT_ACCESS, SET_AUDIT_FAILURE,
or both. For information about these values, see ACCESS_MODE.
 NOTE
The aclapi.h header defines GetExplicitEntriesFromAcl as an alias which automatically selects the ANSI or Unicode version
of this function based on the definition of the UNICODE preprocessor constant. Mixing usage of the encoding-neutral
alias with code that not encoding-neutral can lead to mismatches that result in compilation or runtime errors. For more
information, see Conventions for Function Prototypes.

Requirements

Minimum suppor ted client Windows XP [desktop apps | UWP apps]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps | UWP apps]

Target Platform Windows

Header aclapi.h

Librar y Advapi32.lib

DLL Advapi32.dll

See also
ACCESS_ALLOWED_ACE
ACCESS_DENIED_ACE
ACCESS_MODE
ACE
ACL
Access Control
Basic Access Control Functions
EXPLICIT_ACCESS
LocalFree
SYSTEM_AUDIT_ACE
 GetInheritanceSourceA function (aclapi.h)
7/2/2022 • 2 minutes to read • Edit Online

This version of this function is not supported. The wide character version of this function,
GetInheritanceSourceW, is supported.

Syntax
DWORD GetInheritanceSourceA(
[in] LPSTR pObjectName,
[in] SE_OBJECT_TYPE ObjectType,
[in] SECURITY_INFORMATION SecurityInfo,
[in] BOOL Container,
[in, optional] GUID **pObjectClassGuids,
[in] DWORD GuidCount,
[in] PACL pAcl,
[in, optional] PFN_OBJECT_MGR_FUNCTS pfnArray,
[in] PGENERIC_MAPPING pGenericMapping,
[out] PINHERITED_FROMA pInheritArray
);

Parameters
[in] pObjectName

A pointer to the name of the object that uses the ACL to be checked.
[in] ObjectType

The type of object indicated by pObjectName. The possible values are SE_FILE_OBJECT, SE_REGISTRY_KEY,
SE_DS_OBJECT, and SE_DS_OBJECT_ALL.
[in] SecurityInfo

The type of ACL used with the object. The possible values are DACL_SECURITY_INFORMATION or
SACL_SECURITY_INFORMATION.
[in] Container

TRUE if the object is a container object or FALSE if the object is a leaf object. Note that the only leaf object is
SE_FILE_OBJECT.
[in, optional] pObjectClassGuids

Optional list of GUIDs that identify the object types or names associated with pObjectName. This may be NULL
if the object manager only supports one object class or has no GUID associated with the object class.
[in] GuidCount

Number of GUIDs pointed to by pObjectClassGuids.

[in] pAcl

The ACL for the object.

[in, optional] pfnArray
Reserved. Set this parameter to NULL .
[in] pGenericMapping

The mapping of generic rights to specific rights for the object.

[out] pInheritArray

A pointer to an array of INHERITED_FROM structures that the GetInheritanceSource function fills with the
inheritance information. The caller must allocate enough memory for an entry for each ACE in the ACL.

Return value
If the function succeeds, the function returns ERROR_SUCCESS.
If the function fails, it returns a nonzero error code defined in WinError.h.

Remarks
The GetInheritanceSource function allocates memory for the names returned in the INHERITED_FROM
structure. When the function has finished using this memory, the calling program must free it by calling
FreeInheritedFromArray. Note that the caller must provide memory for the array itself. If the caller allocated the
memory, the caller must free that memory after calling FreeInheritedFromArray .
This function does not handle race conditions. If your thread calls this function at the approximate time that
another thread changes the object's security descriptor, then this function could fail.

NOTE
The aclapi.h header defines GetInheritanceSource as an alias which automatically selects the ANSI or Unicode version of
this function based on the definition of the UNICODE preprocessor constant. Mixing usage of the encoding-neutral alias
with code that not encoding-neutral can lead to mismatches that result in compilation or runtime errors. For more
information, see Conventions for Function Prototypes.

Requirements

Minimum suppor ted client Windows XP [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header aclapi.h

Librar y Advapi32.lib

DLL Advapi32.dll

See also
FreeInheritedFromArray
 GetInheritanceSourceW function (aclapi.h)
7/2/2022 • 2 minutes to read • Edit Online

The GetInheritanceSource function returns information about the source of inherited access control entries
(ACEs) in an access control list (ACL).

Syntax
DWORD GetInheritanceSourceW(
[in] LPWSTR pObjectName,
[in] SE_OBJECT_TYPE ObjectType,
[in] SECURITY_INFORMATION SecurityInfo,
[in] BOOL Container,
[in, optional] GUID **pObjectClassGuids,
[in] DWORD GuidCount,
[in] PACL pAcl,
[in, optional] PFN_OBJECT_MGR_FUNCTS pfnArray,
[in] PGENERIC_MAPPING pGenericMapping,
[out] PINHERITED_FROMW pInheritArray
);

Parameters
[in] pObjectName

A pointer to the name of the object that uses the ACL to be checked.
[in] ObjectType

The type of object indicated by pObjectName. The possible values are SE_FILE_OBJECT, SE_REGISTRY_KEY,
SE_DS_OBJECT, and SE_DS_OBJECT_ALL.
[in] SecurityInfo

The type of ACL used with the object. The possible values are DACL_SECURITY_INFORMATION or
SACL_SECURITY_INFORMATION.
[in] Container

TRUE if the object is a container object or FALSE if the object is a leaf object. Note that the only leaf object is
SE_FILE_OBJECT.
[in, optional] pObjectClassGuids

Optional list of GUIDs that identify the object types or names associated with pObjectName. This may be NULL
if the object manager only supports one object class or has no GUID associated with the object class.
[in] GuidCount

Number of GUIDs pointed to by pObjectClassGuids.

[in] pAcl

The ACL for the object.

[in, optional] pfnArray
Reserved. Set this parameter to NULL .
[in] pGenericMapping

The mapping of generic rights to specific rights for the object.

[out] pInheritArray

A pointer to an array of INHERITED_FROM structures that the GetInheritanceSource function fills with the
inheritance information. The caller must allocate enough memory for an entry for each ACE in the ACL.

Return value
If the function succeeds, the function returns ERROR_SUCCESS.
If the function fails, it returns a nonzero error code defined in WinError.h.

Remarks
The GetInheritanceSource function allocates memory for the names returned in the INHERITED_FROM
structure. When the function has finished using this memory, the calling program must free it by calling
FreeInheritedFromArray. Note that the caller must provide memory for the array itself. If the caller allocated the
memory, the caller must free that memory after calling FreeInheritedFromArray .
This function does not handle race conditions. If your thread calls this function at the approximate time that
another thread changes the object's security descriptor, then this function could fail.

NOTE
The aclapi.h header defines GetInheritanceSource as an alias which automatically selects the ANSI or Unicode version of
this function based on the definition of the UNICODE preprocessor constant. Mixing usage of the encoding-neutral alias
with code that not encoding-neutral can lead to mismatches that result in compilation or runtime errors. For more
information, see Conventions for Function Prototypes.

Requirements

Minimum suppor ted client Windows XP [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header aclapi.h

Librar y Advapi32.lib

DLL Advapi32.dll

See also
FreeInheritedFromArray
 GetNamedSecurityInfoA function (aclapi.h)
7/2/2022 • 4 minutes to read • Edit Online

The GetNamedSecurityInfo function retrieves a copy of the security descriptor for an object specified by
name.

Syntax
DWORD GetNamedSecurityInfoA(
[in] LPCSTR pObjectName,
[in] SE_OBJECT_TYPE ObjectType,
[in] SECURITY_INFORMATION SecurityInfo,
[out, optional] PSID *ppsidOwner,
[out, optional] PSID *ppsidGroup,
[out, optional] PACL *ppDacl,
[out, optional] PACL *ppSacl,
[out, optional] PSECURITY_DESCRIPTOR *ppSecurityDescriptor
);

Parameters
[in] pObjectName

A pointer to a null-terminated string that specifies the name of the object from which to retrieve security
information. For descriptions of the string formats for the different object types, see SE_OBJECT_TYPE.
[in] ObjectType

Specifies a value from the SE_OBJECT_TYPE enumeration that indicates the type of object named by the
pObjectName parameter.
[in] SecurityInfo

A set of bit flags that indicate the type of security information to retrieve. This parameter can be a combination
of the SECURITY_INFORMATION bit flags.
[out, optional] ppsidOwner

A pointer to a variable that receives a pointer to the owner SID in the security descriptor returned in
ppSecurityDescriptor or NULL if the security descriptor has no owner SID. The returned pointer is valid only if
you set the OWNER_SECURITY_INFORMATION flag. Also, this parameter can be NULL if you do not need the
owner SID.
[out, optional] ppsidGroup

A pointer to a variable that receives a pointer to the primary group SID in the returned security descriptor or
NULL if the security descriptor has no group SID. The returned pointer is valid only if you set the
GROUP_SECURITY_INFORMATION flag. Also, this parameter can be NULL if you do not need the group SID.
[out, optional] ppDacl

A pointer to a variable that receives a pointer to the DACL in the returned security descriptor or NULL if the
security descriptor has no DACL. The returned pointer is valid only if you set the
DACL_SECURITY_INFORMATION flag. Also, this parameter can be NULL if you do not need the DACL.
[out, optional] ppSacl

A pointer to a variable that receives a pointer to the SACL in the returned security descriptor or NULL if the
security descriptor has no SACL. The returned pointer is valid only if you set the
SACL_SECURITY_INFORMATION flag. Also, this parameter can be NULL if you do not need the SACL.
[out, optional] ppSecurityDescriptor

A pointer to a variable that receives a pointer to the security descriptor of the object. When you have finished
using the pointer, free the returned buffer by calling the LocalFree function.
This parameter is required if any one of the ppsidOwner, ppsidGroup, ppDacl, or ppSacl parameters is not
NULL .

Return value
If the function succeeds, the return value is ERROR_SUCCESS.
If the function fails, the return value is a nonzero error code defined in WinError.h.

Remarks
If any of the ppsidOwner, ppsidGroup, ppDacl, or ppSacl parameters are non-NULL , and the SecurityInfo
parameter specifies that they be retrieved from the object, those parameters will point to the corresponding
parameters in the security descriptor returned in ppSecurityDescriptor. If the security descriptor does not
contain the requested information, the corresponding parameter will be set to NULL .
To read the owner, group, or DACL from the object's security descriptor, the object's DACL must grant
READ_CONTROL access to the caller, or the caller must be the owner of the object.
To read the system access control list of the object, the SE_SECURITY_NAME privilege must be enabled for the
calling process. For information about the security implications of enabling privileges, see Running with Special
Privileges.
You can use the GetNamedSecurityInfo function with the following types of objects:
Local or remote files or directories on an NTFS file system
Local or remote printers
Local or remote Windows services
Network shares
Registry keys
Semaphores, events, mutexes, and waitable timers
File-mapping objects
Directory service objects
This function does not handle race conditions. If your thread calls this function at the approximate time that another
thread changes the object's security descriptor, then this function could fail.
This function transfers information in plaintext. The information transferred by this function is signed unless
signing has been turned off for the system, but no encryption is performed.
For more information about controlling access to objects through user accounts, group accounts, or logon
sessions, see How DACLs Control Access to an Object.
Examples
For an example that uses GetNamedSecurityInfo , see Modifying the ACLs of an Object.
 NOTE
The aclapi.h header defines GetNamedSecurityInfo as an alias which automatically selects the ANSI or Unicode version of
this function based on the definition of the UNICODE preprocessor constant. Mixing usage of the encoding-neutral alias
with code that not encoding-neutral can lead to mismatches that result in compilation or runtime errors. For more
information, see Conventions for Function Prototypes.

Requirements

Minimum suppor ted client Windows XP [desktop apps | UWP apps]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps | UWP apps]

Target Platform Windows

Header aclapi.h

Librar y Advapi32.lib

DLL Advapi32.dll

See also
ACL
Access Control
Basic Access Control Functions
GetSecurityInfo
LocalFree
Privilege Constants
SECURITY_DESCRIPTOR
SECURITY_INFORMATION
SE_OBJECT_TYPE
SID
SetNamedSecurityInfo
SetSecurityInfo
 GetNamedSecurityInfoW function (aclapi.h)
7/2/2022 • 4 minutes to read • Edit Online

The GetNamedSecurityInfo function retrieves a copy of the security descriptor for an object specified by
name.

Syntax
DWORD GetNamedSecurityInfoW(
[in] LPCWSTR pObjectName,
[in] SE_OBJECT_TYPE ObjectType,
[in] SECURITY_INFORMATION SecurityInfo,
[out, optional] PSID *ppsidOwner,
[out, optional] PSID *ppsidGroup,
[out, optional] PACL *ppDacl,
[out, optional] PACL *ppSacl,
[out, optional] PSECURITY_DESCRIPTOR *ppSecurityDescriptor
);

Parameters
[in] pObjectName

A pointer to a null-terminated string that specifies the name of the object from which to retrieve security
information. For descriptions of the string formats for the different object types, see SE_OBJECT_TYPE.
[in] ObjectType

Specifies a value from the SE_OBJECT_TYPE enumeration that indicates the type of object named by the
pObjectName parameter.
[in] SecurityInfo

A set of bit flags that indicate the type of security information to retrieve. This parameter can be a combination
of the SECURITY_INFORMATION bit flags.
[out, optional] ppsidOwner

A pointer to a variable that receives a pointer to the owner SID in the security descriptor returned in
ppSecurityDescriptor or NULL if the security descriptor has no owner SID. The returned pointer is valid only if
you set the OWNER_SECURITY_INFORMATION flag. Also, this parameter can be NULL if you do not need the
owner SID.
[out, optional] ppsidGroup

A pointer to a variable that receives a pointer to the primary group SID in the returned security descriptor or
NULL if the security descriptor has no group SID. The returned pointer is valid only if you set the
GROUP_SECURITY_INFORMATION flag. Also, this parameter can be NULL if you do not need the group SID.
[out, optional] ppDacl

A pointer to a variable that receives a pointer to the DACL in the returned security descriptor or NULL if the
security descriptor has no DACL. The returned pointer is valid only if you set the
DACL_SECURITY_INFORMATION flag. Also, this parameter can be NULL if you do not need the DACL.
[out, optional] ppSacl

A pointer to a variable that receives a pointer to the SACL in the returned security descriptor or NULL if the
security descriptor has no SACL. The returned pointer is valid only if you set the
SACL_SECURITY_INFORMATION flag. Also, this parameter can be NULL if you do not need the SACL.
[out, optional] ppSecurityDescriptor

A pointer to a variable that receives a pointer to the security descriptor of the object. When you have finished
using the pointer, free the returned buffer by calling the LocalFree function.
This parameter is required if any one of the ppsidOwner, ppsidGroup, ppDacl, or ppSacl parameters is not
NULL .

Return value
If the function succeeds, the return value is ERROR_SUCCESS.
If the function fails, the return value is a nonzero error code defined in WinError.h.

Remarks
If any of the ppsidOwner, ppsidGroup, ppDacl, or ppSacl parameters are non-NULL , and the SecurityInfo
parameter specifies that they be retrieved from the object, those parameters will point to the corresponding
parameters in the security descriptor returned in ppSecurityDescriptor. If the security descriptor does not
contain the requested information, the corresponding parameter will be set to NULL .
To read the owner, group, or DACL from the object's security descriptor, the object's DACL must grant
READ_CONTROL access to the caller, or the caller must be the owner of the object.
To read the system access control list of the object, the SE_SECURITY_NAME privilege must be enabled for the
calling process. For information about the security implications of enabling privileges, see Running with Special
Privileges.
You can use the GetNamedSecurityInfo function with the following types of objects:
Local or remote files or directories on an NTFS file system
Local or remote printers
Local or remote Windows services
Network shares
Registry keys
Semaphores, events, mutexes, and waitable timers
File-mapping objects
Directory service objects
This function does not handle race conditions. If your thread calls this function at the approximate time that another
thread changes the object's security descriptor, then this function could fail.
This function transfers information in plaintext. The information transferred by this function is signed unless
signing has been turned off for the system, but no encryption is performed.
For more information about controlling access to objects through user accounts, group accounts, or logon
sessions, see How DACLs Control Access to an Object.
Examples
For an example that uses GetNamedSecurityInfo , see Modifying the ACLs of an Object.
 NOTE
The aclapi.h header defines GetNamedSecurityInfo as an alias which automatically selects the ANSI or Unicode version of
this function based on the definition of the UNICODE preprocessor constant. Mixing usage of the encoding-neutral alias
with code that not encoding-neutral can lead to mismatches that result in compilation or runtime errors. For more
information, see Conventions for Function Prototypes.

Requirements

Minimum suppor ted client Windows XP [desktop apps | UWP apps]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps | UWP apps]

Target Platform Windows

Header aclapi.h

Librar y Advapi32.lib

DLL Advapi32.dll

See also
ACL
Access Control
Basic Access Control Functions
GetSecurityInfo
LocalFree
Privilege Constants
SECURITY_DESCRIPTOR
SECURITY_INFORMATION
SE_OBJECT_TYPE
SID
SetNamedSecurityInfo
SetSecurityInfo
 GetSecurityInfo function (aclapi.h)
7/2/2022 • 3 minutes to read • Edit Online

The GetSecurityInfo function retrieves a copy of the security descriptor for an object specified by a handle.

Syntax
DWORD GetSecurityInfo(
[in] HANDLE handle,
[in] SE_OBJECT_TYPE ObjectType,
[in] SECURITY_INFORMATION SecurityInfo,
[out, optional] PSID *ppsidOwner,
[out, optional] PSID *ppsidGroup,
[out, optional] PACL *ppDacl,
[out, optional] PACL *ppSacl,
[out, optional] PSECURITY_DESCRIPTOR *ppSecurityDescriptor
);

Parameters
[in] handle

A handle to the object from which to retrieve security information.

[in] ObjectType

SE_OBJECT_TYPE enumeration value that indicates the type of object.

[in] SecurityInfo

A set of bit flags that indicate the type of security information to retrieve. This parameter can be a combination
of the SECURITY_INFORMATION bit flags.
[out, optional] ppsidOwner

A pointer to a variable that receives a pointer to the owner SID in the security descriptor returned in
ppSecurityDescriptor. The returned pointer is valid only if you set the OWNER_SECURITY_INFORMATION flag.
This parameter can be NULL if you do not need the owner SID.
[out, optional] ppsidGroup

A pointer to a variable that receives a pointer to the primary group SID in the returned security descriptor. The
returned pointer is valid only if you set the GROUP_SECURITY_INFORMATION flag. This parameter can be NULL
if you do not need the group SID.
[out, optional] ppDacl

A pointer to a variable that receives a pointer to the DACL in the returned security descriptor. The returned
pointer is valid only if you set the DACL_SECURITY_INFORMATION flag. This parameter can be NULL if you do
not need the DACL.
[out, optional] ppSacl

A pointer to a variable that receives a pointer to the SACL in the returned security descriptor. The returned
pointer is valid only if you set the SACL_SECURITY_INFORMATION flag. This parameter can be NULL if you do
not need the SACL.
[out, optional] ppSecurityDescriptor

A pointer to a variable that receives a pointer to the security descriptor of the object. When you have finished
using the pointer, free the returned buffer by calling the LocalFree function.
This parameter is required if any one of the ppsidOwner, ppsidGroup, ppDacl, or ppSacl parameters is not
NULL .

Return value
If the function succeeds, the return value is ERROR_SUCCESS.
If the function fails, the return value is a nonzero error code defined in WinError.h.

Remarks
If the ppsidOwner, ppsidGroup, ppDacl, and ppSacl parameters are non-NULL , and the SecurityInfo parameter
specifies that they be retrieved from the object, those parameters will point to the corresponding parameters in
the security descriptor returned in ppSecurityDescriptor.
To read the owner, group, or DACL from the object's security descriptor, the calling process must have been
granted READ_CONTROL access when the handle was opened. To get READ_CONTROL access, the caller must
be the owner of the object or the object's DACL must grant the access.
To read the SACL from the security descriptor, the calling process must have been granted
ACCESS_SYSTEM_SECURITY access when the handle was opened. The proper way to get this access is to enable
the SE_SECURITY_NAME privilege in the caller's current token, open the handle for ACCESS_SYSTEM_SECURITY
access, and then disable the privilege. For information about the security implications of enabling privileges, see
Running with Special Privileges.
You can use the GetSecurityInfo function with the following types of objects:
Local or remote files or directories on an NTFS file system
Named pipes
Local or remote printers
Local or remote Windows services
Network shares
Registry keys
Semaphores, events, mutexes, and waitable timers
Processes, threads, jobs, and file-mapping objects
Interactive service window stations and desktops
Directory service objects
This function does not handle race conditions. If your thread calls this function at the approximate time that another
thread changes the object's security descriptor, then this function could fail.
Examples
For an example that uses this function, see Finding the Owner of a File Object.

Requirements
 Minimum suppor ted client Windows XP [desktop apps | UWP apps]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps | UWP apps]

Target Platform Windows

Header aclapi.h

Librar y Advapi32.lib

DLL Advapi32.dll

See also
ACL
Access Control Overview
Basic Access Control Functions
GetNamedSecurityInfo
LocalFree
Privilege Constants
SECURITY_DESCRIPTOR
SECURITY_INFORMATION
SE_OBJECT_TYPE
SID
SetNamedSecurityInfo
SetSecurityInfo
 GetTrusteeFormA function (aclapi.h)
7/2/2022 • 2 minutes to read • Edit Online

The GetTrusteeForm function retrieves the trustee name from the specified TRUSTEE structure. This value
indicates whether the structure uses a name string or a security identifier (SID) to identify the trustee.

Syntax
TRUSTEE_FORM GetTrusteeFormA(
[in] PTRUSTEE_A pTrustee
);

Parameters
[in] pTrustee

A pointer to a TRUSTEE structure.

Return value
The return value is one of the constants from the TRUSTEE_FORM enumeration.

Remarks
NOTE
The aclapi.h header defines GetTrusteeForm as an alias which automatically selects the ANSI or Unicode version of this
function based on the definition of the UNICODE preprocessor constant. Mixing usage of the encoding-neutral alias with
code that not encoding-neutral can lead to mismatches that result in compilation or runtime errors. For more
information, see Conventions for Function Prototypes.

Requirements

Minimum suppor ted client Windows XP [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header aclapi.h

Librar y Advapi32.lib

DLL Advapi32.dll
See also
Access Control Overview
Basic Access Control Functions
GetTrusteeName
GetTrusteeType
TRUSTEE
TRUSTEE_FORM
 GetTrusteeFormW function (aclapi.h)
7/2/2022 • 2 minutes to read • Edit Online

The GetTrusteeForm function retrieves the trustee name from the specified TRUSTEE structure. This value
indicates whether the structure uses a name string or a security identifier (SID) to identify the trustee.

Syntax
TRUSTEE_FORM GetTrusteeFormW(
[in] PTRUSTEE_W pTrustee
);

Parameters
[in] pTrustee

A pointer to a TRUSTEE structure.

Return value
The return value is one of the constants from the TRUSTEE_FORM enumeration.

Remarks
NOTE
The aclapi.h header defines GetTrusteeForm as an alias which automatically selects the ANSI or Unicode version of this
function based on the definition of the UNICODE preprocessor constant. Mixing usage of the encoding-neutral alias with
code that not encoding-neutral can lead to mismatches that result in compilation or runtime errors. For more
information, see Conventions for Function Prototypes.

Requirements

Minimum suppor ted client Windows XP [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header aclapi.h

Librar y Advapi32.lib

DLL Advapi32.dll
See also
Access Control Overview
Basic Access Control Functions
GetTrusteeName
GetTrusteeType
TRUSTEE
TRUSTEE_FORM
 GetTrusteeNameA function (aclapi.h)
7/2/2022 • 2 minutes to read • Edit Online

The GetTrusteeName function retrieves the trustee name from the specified TRUSTEE structure.

Syntax
LPSTR GetTrusteeNameA(
[in] PTRUSTEE_A pTrustee
);

Parameters
[in] pTrustee

A pointer to a TRUSTEE structure.

Return value
If the TrusteeForm member of the TRUSTEE structure is TRUSTEE_IS_NAME, the return value is the pointer
assigned to the ptstrName member of the structure.
If the TrusteeForm member is TRUSTEE_IS_SID, the return value is NULL . The function does not look up the
name associated with a security identifier (SID).

Remarks
The GetTrusteeName function does not allocate any memory.

NOTE
The aclapi.h header defines GetTrusteeName as an alias which automatically selects the ANSI or Unicode version of this
function based on the definition of the UNICODE preprocessor constant. Mixing usage of the encoding-neutral alias with
code that not encoding-neutral can lead to mismatches that result in compilation or runtime errors. For more
information, see Conventions for Function Prototypes.

Requirements

Minimum suppor ted client Windows XP [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header aclapi.h
 Librar y Advapi32.lib

DLL Advapi32.dll

See also
Access Control Overview
Basic Access Control Functions
SID
TRUSTEE
 GetTrusteeNameW function (aclapi.h)
7/2/2022 • 2 minutes to read • Edit Online

The GetTrusteeName function retrieves the trustee name from the specified TRUSTEE structure.

Syntax
LPWSTR GetTrusteeNameW(
[in] PTRUSTEE_W pTrustee
);

Parameters
[in] pTrustee

A pointer to a TRUSTEE structure.

Return value
If the TrusteeForm member of the TRUSTEE structure is TRUSTEE_IS_NAME, the return value is the pointer
assigned to the ptstrName member of the structure.
If the TrusteeForm member is TRUSTEE_IS_SID, the return value is NULL . The function does not look up the
name associated with a security identifier (SID).

Remarks
The GetTrusteeName function does not allocate any memory.

NOTE
The aclapi.h header defines GetTrusteeName as an alias which automatically selects the ANSI or Unicode version of this
function based on the definition of the UNICODE preprocessor constant. Mixing usage of the encoding-neutral alias with
code that not encoding-neutral can lead to mismatches that result in compilation or runtime errors. For more
information, see Conventions for Function Prototypes.

Requirements

Minimum suppor ted client Windows XP [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header aclapi.h
 Librar y Advapi32.lib

DLL Advapi32.dll

See also
Access Control Overview
Basic Access Control Functions
SID
TRUSTEE
 GetTrusteeTypeA function (aclapi.h)
7/2/2022 • 2 minutes to read • Edit Online

The GetTrusteeType function retrieves the trustee type from the specified TRUSTEE structure. This value
indicates whether the trustee is a user, a group, or the trustee type is unknown.

Syntax
TRUSTEE_TYPE GetTrusteeTypeA(
[in, optional] PTRUSTEE_A pTrustee
);

Parameters
[in, optional] pTrustee

A pointer to a TRUSTEE structure.

Return value
The return value is one of the constants from the TRUSTEE_TYPE enumeration.

Remarks
NOTE
The aclapi.h header defines GetTrusteeType as an alias which automatically selects the ANSI or Unicode version of this
function based on the definition of the UNICODE preprocessor constant. Mixing usage of the encoding-neutral alias with
code that not encoding-neutral can lead to mismatches that result in compilation or runtime errors. For more
information, see Conventions for Function Prototypes.

Requirements

Minimum suppor ted client Windows XP [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header aclapi.h

Librar y Advapi32.lib

DLL Advapi32.dll
See also
Access Control Overview
Basic Access Control Functions
TRUSTEE
TRUSTEE_TYPE
 GetTrusteeTypeW function (aclapi.h)
7/2/2022 • 2 minutes to read • Edit Online

The GetTrusteeType function retrieves the trustee type from the specified TRUSTEE structure. This value
indicates whether the trustee is a user, a group, or the trustee type is unknown.

Syntax
TRUSTEE_TYPE GetTrusteeTypeW(
[in, optional] PTRUSTEE_W pTrustee
);

Parameters
[in, optional] pTrustee

A pointer to a TRUSTEE structure.

Return value
The return value is one of the constants from the TRUSTEE_TYPE enumeration.

Remarks
NOTE
The aclapi.h header defines GetTrusteeType as an alias which automatically selects the ANSI or Unicode version of this
function based on the definition of the UNICODE preprocessor constant. Mixing usage of the encoding-neutral alias with
code that not encoding-neutral can lead to mismatches that result in compilation or runtime errors. For more
information, see Conventions for Function Prototypes.

Requirements

Minimum suppor ted client Windows XP [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header aclapi.h

Librar y Advapi32.lib

DLL Advapi32.dll
See also
Access Control Overview
Basic Access Control Functions
TRUSTEE
TRUSTEE_TYPE
 LookupSecurityDescriptorPartsA function (aclapi.h)
7/2/2022 • 3 minutes to read • Edit Online

The LookupSecurityDescriptorPar ts function retrieves security information from a self-relative security

descriptor.

Syntax
DWORD LookupSecurityDescriptorPartsA(
[out, optional] PTRUSTEE_A
[out, optional] PTRUSTEE_A
[out, optional] PULONG
[out, optional] PEXPLICIT_ACCESS_A
[out, optional] PULONG
[out, optional] PEXPLICIT_ACCESS_A
[in] PSECURITY_DESCRIPTOR
);
*ppOwner,
*ppGroup,
pcCountOfAccessEntries,
*ppListOfAccessEntries,
pcCountOfAuditEntries,
*ppListOfAuditEntries,
pSD

Parameters
[out, optional] ppOwner

A pointer to a variable that receives a pointer to a TRUSTEE structure. The function looks up the name associated
with the owner security identifier (SID) in the pSD security descriptor, and returns a pointer to the name in the
ptstrName member of the TRUSTEE structure. The function sets the TrusteeForm member to
TRUSTEE_IS_NAME.
This parameter can be NULL if you are not interested in the name of the owner.
[out, optional] ppGroup

A pointer to a variable that receives a pointer to a TRUSTEE structure. The function looks up the name associated
with the primary group SID of the security descriptor, and returns a pointer to the name in the ptstrName
member of the TRUSTEE structure. The function sets the TrusteeForm member to TRUSTEE_IS_NAME.
This parameter can be NULL if you are not interested in the name of the group.
[out, optional] pcCountOfAccessEntries

A pointer to a ULONG that receives the number of EXPLICIT_ACCESS structures returned in the
pListOfAccessEntries array. This parameter can be NULL only if the pListOfAccessEntries parameter is also
NULL .
[out, optional] ppListOfAccessEntries

A pointer to a variable that receives a pointer to an array of EXPLICIT_ACCESS structures that describe the access
control entries (ACEs) in the discretionary access control list (DACL) of the security descriptor. The TRUSTEE
structure in these EXPLICIT_ACCESS structures use the TRUSTEE_IS_NAME form. For a description of how an
array of EXPLICIT_ACCESS structures describes the ACEs in an access control list (ACL), see the
GetExplicitEntriesFromAcl function. If this parameter is NULL , the cCountOfAccessEntries parameter must also
be NULL .
[out, optional] pcCountOfAuditEntries
A pointer to a ULONG that receives the number of EXPLICIT_ACCESS structures returned in the
pListOfAuditEntries array. This parameter can be NULL only if the pListOfAuditEntries parameter is also NULL .
[out, optional] ppListOfAuditEntries

A pointer to a variable that receives a pointer to an array of EXPLICIT_ACCESS structures that describe the ACEs
in the system access control list (SACL) of the security descriptor. The TRUSTEE structure in these
EXPLICIT_ACCESS structures uses the TRUSTEE_IS_NAME form. If this parameter is NULL , the
cCountOfAuditEntries parameter must also be NULL .
[in] pSD

A pointer to an existing self-relative security descriptor from which the function retrieves security information.

Return value
If the function succeeds, the function returns ERROR_SUCCESS.
If the function fails, it returns a nonzero error code defined in WinError.h.

Remarks
The LookupSecurityDescriptorPar ts function retrieves the names of the owner and primary group of the
security descriptor. This function also returns descriptions of the ACEs in the DACL and audit-control entries in
the SACL of the security descriptor.
The parameters other than pSD can be NULL if you are not interested in the information. If you do not want
information about the DACL, both pListOfAccessEntries and cCountOfAuditEntries must be NULL . If you do not
want information about the SACL, both pListOfAuditEntries and cCountOfAuditEntries must be NULL . Similarly,
if you do want DACL or SACL information, both of the corresponding parameters must not be NULL .
When you have finished using any of the buffers returned by the pOwner, pGroup, pListOfAccessEntries, or
pListOfAuditEntries parameters, free them by calling the LocalFree function.
The LookupSecurityDescriptorPar ts function is intended for trusted servers that implement or expose
security on their own objects. The function works with a self-relative security descriptor suitable for serializing
into a stream and storing to disk, as a trusted server might require.

NOTE
The aclapi.h header defines LookupSecurityDescriptorParts as an alias which automatically selects the ANSI or Unicode
version of this function based on the definition of the UNICODE preprocessor constant. Mixing usage of the encoding-
neutral alias with code that not encoding-neutral can lead to mismatches that result in compilation or runtime errors. For
more information, see Conventions for Function Prototypes.

Requirements

Minimum suppor ted client Windows XP [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

 Header aclapi.h

Librar y Advapi32.lib

DLL Advapi32.dll

See also
ACE
ACL
Client/Server Access Control Functions
Client/Server Access Control Overview
EXPLICIT_ACCESS
GetExplicitEntriesFromAcl
LocalFree
SECURITY_DESCRIPTOR
SID
TRUSTEE
 LookupSecurityDescriptorPartsW function (aclapi.h)
7/2/2022 • 3 minutes to read • Edit Online

The LookupSecurityDescriptorPar ts function retrieves security information from a self-relative security

descriptor.

Syntax
DWORD LookupSecurityDescriptorPartsW(
[out, optional] PTRUSTEE_W
[out, optional] PTRUSTEE_W
[out, optional] PULONG
[out, optional] PEXPLICIT_ACCESS_W
[out, optional] PULONG
[out, optional] PEXPLICIT_ACCESS_W
[in] PSECURITY_DESCRIPTOR
);
*ppOwner,
*ppGroup,
pcCountOfAccessEntries,
*ppListOfAccessEntries,
pcCountOfAuditEntries,
*ppListOfAuditEntries,
pSD

Parameters
[out, optional] ppOwner

A pointer to a variable that receives a pointer to a TRUSTEE structure. The function looks up the name associated
with the owner security identifier (SID) in the pSD security descriptor, and returns a pointer to the name in the
ptstrName member of the TRUSTEE structure. The function sets the TrusteeForm member to
TRUSTEE_IS_NAME.
This parameter can be NULL if you are not interested in the name of the owner.
[out, optional] ppGroup

A pointer to a variable that receives a pointer to a TRUSTEE structure. The function looks up the name associated
with the primary group SID of the security descriptor, and returns a pointer to the name in the ptstrName
member of the TRUSTEE structure. The function sets the TrusteeForm member to TRUSTEE_IS_NAME.
This parameter can be NULL if you are not interested in the name of the group.
[out, optional] pcCountOfAccessEntries

A pointer to a ULONG that receives the number of EXPLICIT_ACCESS structures returned in the
pListOfAccessEntries array. This parameter can be NULL only if the pListOfAccessEntries parameter is also
NULL .
[out, optional] ppListOfAccessEntries

A pointer to a variable that receives a pointer to an array of EXPLICIT_ACCESS structures that describe the access
control entries (ACEs) in the discretionary access control list (DACL) of the security descriptor. The TRUSTEE
structure in these EXPLICIT_ACCESS structures use the TRUSTEE_IS_NAME form. For a description of how an
array of EXPLICIT_ACCESS structures describes the ACEs in an access control list (ACL), see the
GetExplicitEntriesFromAcl function. If this parameter is NULL , the cCountOfAccessEntries parameter must also
be NULL .
[out, optional] pcCountOfAuditEntries
A pointer to a ULONG that receives the number of EXPLICIT_ACCESS structures returned in the
pListOfAuditEntries array. This parameter can be NULL only if the pListOfAuditEntries parameter is also NULL .
[out, optional] ppListOfAuditEntries

A pointer to a variable that receives a pointer to an array of EXPLICIT_ACCESS structures that describe the ACEs
in the system access control list (SACL) of the security descriptor. The TRUSTEE structure in these
EXPLICIT_ACCESS structures uses the TRUSTEE_IS_NAME form. If this parameter is NULL , the
cCountOfAuditEntries parameter must also be NULL .
[in] pSD

A pointer to an existing self-relative security descriptor from which the function retrieves security information.

Return value
If the function succeeds, the function returns ERROR_SUCCESS.
If the function fails, it returns a nonzero error code defined in WinError.h.

Remarks
The LookupSecurityDescriptorPar ts function retrieves the names of the owner and primary group of the
security descriptor. This function also returns descriptions of the ACEs in the DACL and audit-control entries in
the SACL of the security descriptor.
The parameters other than pSD can be NULL if you are not interested in the information. If you do not want
information about the DACL, both pListOfAccessEntries and cCountOfAuditEntries must be NULL . If you do not
want information about the SACL, both pListOfAuditEntries and cCountOfAuditEntries must be NULL . Similarly,
if you do want DACL or SACL information, both of the corresponding parameters must not be NULL .
When you have finished using any of the buffers returned by the pOwner, pGroup, pListOfAccessEntries, or
pListOfAuditEntries parameters, free them by calling the LocalFree function.
The LookupSecurityDescriptorPar ts function is intended for trusted servers that implement or expose
security on their own objects. The function works with a self-relative security descriptor suitable for serializing
into a stream and storing to disk, as a trusted server might require.

NOTE
The aclapi.h header defines LookupSecurityDescriptorParts as an alias which automatically selects the ANSI or Unicode
version of this function based on the definition of the UNICODE preprocessor constant. Mixing usage of the encoding-
neutral alias with code that not encoding-neutral can lead to mismatches that result in compilation or runtime errors. For
more information, see Conventions for Function Prototypes.

Requirements

Minimum suppor ted client Windows XP [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

 Header aclapi.h

Librar y Advapi32.lib

DLL Advapi32.dll

See also
ACE
ACL
Client/Server Access Control Functions
Client/Server Access Control Overview
EXPLICIT_ACCESS
GetExplicitEntriesFromAcl
LocalFree
SECURITY_DESCRIPTOR
SID
TRUSTEE
 SetEntriesInAclA function (aclapi.h)
7/2/2022 • 2 minutes to read • Edit Online

The SetEntriesInAcl function creates a new access control list (ACL) by merging new access control or audit
control information into an existing ACL structure.

Syntax
DWORD SetEntriesInAclA(
[in] ULONG cCountOfExplicitEntries,
[in, optional] PEXPLICIT_ACCESS_A pListOfExplicitEntries,
[in, optional] PACL OldAcl,
[out] PACL *NewAcl
);

Parameters
[in] cCountOfExplicitEntries

The number of EXPLICIT_ACCESS structures in the pListOfExplicitEntries array.

[in, optional] pListOfExplicitEntries

A pointer to an array of EXPLICIT_ACCESS structures that describe the access control information to merge into
the existing ACL.
[in, optional] OldAcl

A pointer to the existing ACL. This parameter can be NULL , in which case, the function creates a new ACL based
on the EXPLICIT_ACCESS entries.
[out] NewAcl

A pointer to a variable that receives a pointer to the new ACL. If the function succeeds, you must call the
LocalFree function to free the returned buffer.

Return value
If the function succeeds, the function returns ERROR_SUCCESS.
If the function fails, it returns a nonzero error code defined in WinError.h.

Remarks
Each entry in the array of EXPLICIT_ACCESS structures specifies access control or audit control information for a
specified trustee. A trustee can be a user, group, or other security identifier (SID) value, such as a logon identifier
or logon type (for instance, a Windows service or batch job). You can use a name or a SID to identify a trustee.
You can use the SetEntriesInAcl function to modify the list of access control entries (ACEs) in a discretionary
access control list (DACL) or a system access control list (SACL). Note that SetEntriesInAcl does not prevent
you from mixing access control and audit control information in the same ACL; however, the resulting ACL will
contain meaningless entries.
For a DACL, the grfAccessMode member of the EXPLICIT_ACCESS structure specifies whether to allow, deny, or
revoke access rights for the trustee. This member can specify one of the following values:
GRANT_ACCESS
SET_ACCESS
DENY_ACCESS
REVOKE_ACCESS
For information about these values, see ACCESS_MODE.
The SetEntriesInAcl function places any new access-denied ACEs at the beginning of the list of ACEs for the
new ACL. This function places any new access-allowed ACEs just before any existing access-allowed ACEs.
For a SACL, the grfAccessMode member of the EXPLICIT_ACCESS structure can specify the following values:
REVOKE_ACCESS
SET_AUDIT_FAILURE
SET_AUDIT_SUCCESS
SET_AUDIT_FAILURE and SET_AUDIT_SUCCESS can be combined. For information about these values, see
ACCESS_MODE.
The SetEntriesInAcl function places any new system-audit ACEs at the beginning of the list of ACEs for the new
ACL.
Examples
For an example that uses this function, see Modifying the ACLs of an Object or Creating a Security Descriptor for
a New Object or Taking Object Ownership.

NOTE
The aclapi.h header defines SetEntriesInAcl as an alias which automatically selects the ANSI or Unicode version of this
function based on the definition of the UNICODE preprocessor constant. Mixing usage of the encoding-neutral alias with
code that not encoding-neutral can lead to mismatches that result in compilation or runtime errors. For more
information, see Conventions for Function Prototypes.

Requirements

Minimum suppor ted client Windows XP [desktop apps | UWP apps]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps | UWP apps]

Target Platform Windows

Header aclapi.h

Librar y Advapi32.lib

DLL Advapi32.dll

See also
ACCESS_ALLOWED_ACE
ACCESS_DENIED_ACE
ACL
Access Control
Basic Access Control Functions
EXPLICIT_ACCESS
LocalFree
SYSTEM_AUDIT_ACE
 SetEntriesInAclW function (aclapi.h)
7/2/2022 • 2 minutes to read • Edit Online

The SetEntriesInAcl function creates a new access control list (ACL) by merging new access control or audit
control information into an existing ACL structure.

Syntax
DWORD SetEntriesInAclW(
[in] ULONG cCountOfExplicitEntries,
[in, optional] PEXPLICIT_ACCESS_W pListOfExplicitEntries,
[in, optional] PACL OldAcl,
[out] PACL *NewAcl
);

Parameters
[in] cCountOfExplicitEntries

The number of EXPLICIT_ACCESS structures in the pListOfExplicitEntries array.

[in, optional] pListOfExplicitEntries

A pointer to an array of EXPLICIT_ACCESS structures that describe the access control information to merge into
the existing ACL.
[in, optional] OldAcl

A pointer to the existing ACL. This parameter can be NULL , in which case, the function creates a new ACL based
on the EXPLICIT_ACCESS entries.
[out] NewAcl

A pointer to a variable that receives a pointer to the new ACL. If the function succeeds, you must call the
LocalFree function to free the returned buffer.

Return value
If the function succeeds, the function returns ERROR_SUCCESS.
If the function fails, it returns a nonzero error code defined in WinError.h.

Remarks
Each entry in the array of EXPLICIT_ACCESS structures specifies access control or audit control information for a
specified trustee. A trustee can be a user, group, or other security identifier (SID) value, such as a logon identifier
or logon type (for instance, a Windows service or batch job). You can use a name or a SID to identify a trustee.
You can use the SetEntriesInAcl function to modify the list of access control entries (ACEs) in a discretionary
access control list (DACL) or a system access control list (SACL). Note that SetEntriesInAcl does not prevent
you from mixing access control and audit control information in the same ACL; however, the resulting ACL will
contain meaningless entries.
For a DACL, the grfAccessMode member of the EXPLICIT_ACCESS structure specifies whether to allow, deny, or
revoke access rights for the trustee. This member can specify one of the following values:
GRANT_ACCESS
SET_ACCESS
DENY_ACCESS
REVOKE_ACCESS
For information about these values, see ACCESS_MODE.
The SetEntriesInAcl function places any new access-denied ACEs at the beginning of the list of ACEs for the
new ACL. This function places any new access-allowed ACEs just before any existing access-allowed ACEs.
For a SACL, the grfAccessMode member of the EXPLICIT_ACCESS structure can specify the following values:
REVOKE_ACCESS
SET_AUDIT_FAILURE
SET_AUDIT_SUCCESS
SET_AUDIT_FAILURE and SET_AUDIT_SUCCESS can be combined. For information about these values, see
ACCESS_MODE.
The SetEntriesInAcl function places any new system-audit ACEs at the beginning of the list of ACEs for the new
ACL.
Examples
For an example that uses this function, see Modifying the ACLs of an Object or Creating a Security Descriptor for
a New Object or Taking Object Ownership.

NOTE
The aclapi.h header defines SetEntriesInAcl as an alias which automatically selects the ANSI or Unicode version of this
function based on the definition of the UNICODE preprocessor constant. Mixing usage of the encoding-neutral alias with
code that not encoding-neutral can lead to mismatches that result in compilation or runtime errors. For more
information, see Conventions for Function Prototypes.

Requirements

Minimum suppor ted client Windows XP [desktop apps | UWP apps]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps | UWP apps]

Target Platform Windows

Header aclapi.h

Librar y Advapi32.lib

DLL Advapi32.dll

See also
ACCESS_ALLOWED_ACE
ACCESS_DENIED_ACE
ACL
Access Control
Basic Access Control Functions
EXPLICIT_ACCESS
LocalFree
SYSTEM_AUDIT_ACE
 SetNamedSecurityInfoA function (aclapi.h)
7/2/2022 • 3 minutes to read • Edit Online

The SetNamedSecurityInfo function sets specified security information in the security descriptor of a
specified object. The caller identifies the object by name.

Syntax
DWORD SetNamedSecurityInfoA(
[in] LPSTR pObjectName,
[in] SE_OBJECT_TYPE ObjectType,
[in] SECURITY_INFORMATION SecurityInfo,
[in, optional] PSID psidOwner,
[in, optional] PSID psidGroup,
[in, optional] PACL pDacl,
[in, optional] PACL pSacl
);

Parameters
[in] pObjectName

A pointer to a null -terminated string that specifies the name of the object for which to set security information.
This can be the name of a local or remote file or directory on an NTFS file system, network share, registry key,
semaphore, event, mutex, file mapping, or waitable timer.
For descriptions of the string formats for the different object types, see SE_OBJECT_TYPE.
[in] ObjectType

A value of the SE_OBJECT_TYPE enumeration that indicates the type of object named by the pObjectName
parameter.
[in] SecurityInfo

A set of bit flags that indicate the type of security information to set. This parameter can be a combination of the
SECURITY_INFORMATION bit flags.
[in, optional] psidOwner

A pointer to a SID structure that identifies the owner of the object. If the caller does not have the
SeRestorePrivilege constant (see Privilege Constants), this SID must be contained in the caller's token, and
must have the SE_GROUP_OWNER permission enabled. The SecurityInfo parameter must include the
OWNER_SECURITY_INFORMATION flag. To set the owner, the caller must have WRITE_OWNER access to the
object or have the SE_TAKE_OWNERSHIP_NAME privilege enabled. If you are not setting the owner SID , this
parameter can be NULL .
[in, optional] psidGroup

A pointer to a SID that identifies the primary group of the object. The SecurityInfo parameter must include the
GROUP_SECURITY_INFORMATION flag. If you are not setting the primary group SID, this parameter can be
NULL .
[in, optional] pDacl
A pointer to the new DACL for the object. The SecurityInfo parameter must include the
DACL_SECURITY_INFORMATION flag. The caller must have WRITE_DAC access to the object or be the owner of
the object. If you are not setting the DACL, this parameter can be NULL .
[in, optional] pSacl

A pointer to the new SACL for the object. The SecurityInfo parameter must include any of the following flags:
SACL_SECURITY_INFORMATION, LABEL_SECURITY_INFORMATION, ATTRIBUTE_SECURITY_INFORMATION,
SCOPE_SECURITY_INFORMATION, or BACKUP_SECURITY_INFORMATION.
If setting SACL_SECURITY_INFORMATION or SCOPE_SECURITY_INFORMATION, the caller must have the
SE_SECURITY_NAME privilege enabled. If you are not setting the SACL, this parameter can be NULL .

Return value
If the function succeeds, the function returns ERROR_SUCCESS.
If the function fails, it returns a nonzero error code defined in WinError.h.

Remarks
If you are setting the discretionary access control list (DACL) or any elements in the system access control list
(SACL) of an object, the system automatically propagates any inheritable access control entries (ACEs) to
existing child objects, according to the rules of inheritance.
You can use the SetNamedSecurityInfo function with the following types of objects:
Local or remote files or directories on an NTFS
Local or remote printers
Local or remote Windows services
Network shares
Registry keys
Semaphores, events, mutexes, and waitable timers
File-mapping objects
Directory service objects
The SetNamedSecurityInfo function does not reorder access-allowed or access-denied ACEs based on the
preferred order. When propagating inheritable ACEs to existing child objects, SetNamedSecurityInfo puts
inherited ACEs in order after all of the noninherited ACEs in the DACLs of the child objects.
This function transfers information in plaintext. The information transferred by this function is signed unless
signing has been turned off for the system, but no encryption is performed.
When you update access rights of a folder indicated by an UNC path, for example \Test\TestFolder, the original
inherited ACE is removed and the full volume path is not included.
Examples
For an example that uses this function, see Modifying the ACLs of an Object or Taking Object Ownership.

NOTE
The aclapi.h header defines SetNamedSecurityInfo as an alias which automatically selects the ANSI or Unicode version of
this function based on the definition of the UNICODE preprocessor constant. Mixing usage of the encoding-neutral alias
with code that not encoding-neutral can lead to mismatches that result in compilation or runtime errors. For more
information, see Conventions for Function Prototypes.
Requirements

Minimum suppor ted client Windows XP [desktop apps | UWP apps]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps | UWP apps]

Target Platform Windows

Header aclapi.h

Librar y Advapi32.lib

DLL Advapi32.dll

See also
ACL
Access Control
Basic Access Control Functions
GetNamedSecurityInfo
GetSecurityInfo
SECURITY_DESCRIPTOR
SECURITY_INFORMATION
SE_OBJECT_TYPE
SID
SetSecurityInfo
 SetNamedSecurityInfoW function (aclapi.h)
7/2/2022 • 3 minutes to read • Edit Online

The SetNamedSecurityInfo function sets specified security information in the security descriptor of a
specified object. The caller identifies the object by name.

Syntax
DWORD SetNamedSecurityInfoW(
[in] LPWSTR pObjectName,
[in] SE_OBJECT_TYPE ObjectType,
[in] SECURITY_INFORMATION SecurityInfo,
[in, optional] PSID psidOwner,
[in, optional] PSID psidGroup,
[in, optional] PACL pDacl,
[in, optional] PACL pSacl
);

Parameters
[in] pObjectName

A pointer to a null -terminated string that specifies the name of the object for which to set security information.
This can be the name of a local or remote file or directory on an NTFS file system, network share, registry key,
semaphore, event, mutex, file mapping, or waitable timer.
For descriptions of the string formats for the different object types, see SE_OBJECT_TYPE.
[in] ObjectType

A value of the SE_OBJECT_TYPE enumeration that indicates the type of object named by the pObjectName
parameter.
[in] SecurityInfo

A set of bit flags that indicate the type of security information to set. This parameter can be a combination of the
SECURITY_INFORMATION bit flags.
[in, optional] psidOwner

A pointer to a SID structure that identifies the owner of the object. If the caller does not have the
SeRestorePrivilege constant (see Privilege Constants), this SID must be contained in the caller's token, and
must have the SE_GROUP_OWNER permission enabled. The SecurityInfo parameter must include the
OWNER_SECURITY_INFORMATION flag. To set the owner, the caller must have WRITE_OWNER access to the
object or have the SE_TAKE_OWNERSHIP_NAME privilege enabled. If you are not setting the owner SID , this
parameter can be NULL .
[in, optional] psidGroup

A pointer to a SID that identifies the primary group of the object. The SecurityInfo parameter must include the
GROUP_SECURITY_INFORMATION flag. If you are not setting the primary group SID, this parameter can be
NULL .
[in, optional] pDacl
A pointer to the new DACL for the object. The SecurityInfo parameter must include the
DACL_SECURITY_INFORMATION flag. The caller must have WRITE_DAC access to the object or be the owner of
the object. If you are not setting the DACL, this parameter can be NULL .
[in, optional] pSacl

A pointer to the new SACL for the object. The SecurityInfo parameter must include any of the following flags:
SACL_SECURITY_INFORMATION, LABEL_SECURITY_INFORMATION, ATTRIBUTE_SECURITY_INFORMATION,
SCOPE_SECURITY_INFORMATION, or BACKUP_SECURITY_INFORMATION.
If setting SACL_SECURITY_INFORMATION or SCOPE_SECURITY_INFORMATION, the caller must have the
SE_SECURITY_NAME privilege enabled. If you are not setting the SACL, this parameter can be NULL .

Return value
If the function succeeds, the function returns ERROR_SUCCESS.
If the function fails, it returns a nonzero error code defined in WinError.h.

Remarks
If you are setting the discretionary access control list (DACL) or any elements in the system access control list
(SACL) of an object, the system automatically propagates any inheritable access control entries (ACEs) to
existing child objects, according to the rules of inheritance.
You can use the SetNamedSecurityInfo function with the following types of objects:
Local or remote files or directories on an NTFS
Local or remote printers
Local or remote Windows services
Network shares
Registry keys
Semaphores, events, mutexes, and waitable timers
File-mapping objects
Directory service objects
The SetNamedSecurityInfo function does not reorder access-allowed or access-denied ACEs based on the
preferred order. When propagating inheritable ACEs to existing child objects, SetNamedSecurityInfo puts
inherited ACEs in order after all of the noninherited ACEs in the DACLs of the child objects.
This function transfers information in plaintext. The information transferred by this function is signed unless
signing has been turned off for the system, but no encryption is performed.
When you update access rights of a folder indicated by an UNC path, for example \Test\TestFolder, the original
inherited ACE is removed and the full volume path is not included.
Examples
For an example that uses this function, see Modifying the ACLs of an Object or Taking Object Ownership.

NOTE
The aclapi.h header defines SetNamedSecurityInfo as an alias which automatically selects the ANSI or Unicode version of
this function based on the definition of the UNICODE preprocessor constant. Mixing usage of the encoding-neutral alias
with code that not encoding-neutral can lead to mismatches that result in compilation or runtime errors. For more
information, see Conventions for Function Prototypes.
Requirements

Minimum suppor ted client Windows XP [desktop apps | UWP apps]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps | UWP apps]

Target Platform Windows

Header aclapi.h

Librar y Advapi32.lib

DLL Advapi32.dll

See also
ACL
Access Control
Basic Access Control Functions
GetNamedSecurityInfo
GetSecurityInfo
SECURITY_DESCRIPTOR
SECURITY_INFORMATION
SE_OBJECT_TYPE
SID
SetSecurityInfo
 SetSecurityInfo function (aclapi.h)
7/2/2022 • 3 minutes to read • Edit Online

The SetSecurityInfo function sets specified security information in the security descriptor of a specified object.
The caller identifies the object by a handle.
To set the SACL of an object, the caller must have the SE_SECURITY_NAME privilege enabled.

Syntax
DWORD SetSecurityInfo(
[in] HANDLE handle,
[in] SE_OBJECT_TYPE ObjectType,
[in] SECURITY_INFORMATION SecurityInfo,
[in, optional] PSID psidOwner,
[in, optional] PSID psidGroup,
[in, optional] PACL pDacl,
[in, optional] PACL pSacl
);

Parameters
[in] handle

A handle to the object for which to set security information.

[in] ObjectType

A member of the SE_OBJECT_TYPE enumeration that indicates the type of object identified by the handle
parameter.
[in] SecurityInfo

A set of bit flags that indicate the type of security information to set. This parameter can be a combination of the
SECURITY_INFORMATION bit flags.
[in, optional] psidOwner

A pointer to a SID that identifies the owner of the object. The SID must be one that can be assigned as the owner
SID of a security descriptor. The SecurityInfo parameter must include the OWNER_SECURITY_INFORMATION
flag. This parameter can be NULL if you are not setting the owner SID.
[in, optional] psidGroup

A pointer to a SID that identifies the primary group of the object. The SecurityInfo parameter must include the
GROUP_SECURITY_INFORMATION flag. This parameter can be NULL if you are not setting the primary group
SID.
[in, optional] pDacl

A pointer to the new DACL for the object. This parameter is ignored unless the value of the SecurityInfo
parameter includes the DACL_SECURITY_INFORMATION flag. If the value of the SecurityInfo parameter
includes the DACL_SECURITY_INFORMATION flag and the value of this parameter is set to NULL , full access
to the object is granted to everyone. For information about null DACLs, see Creating a DACL.
[in, optional] pSacl

A pointer to the new SACL for the object. The SecurityInfo parameter must include any of the following flags:
SACL_SECURITY_INFORMATION, LABEL_SECURITY_INFORMATION, ATTRIBUTE_SECURITY_INFORMATION,
SCOPE_SECURITY_INFORMATION, or BACKUP_SECURITY_INFORMATION. If setting
SACL_SECURITY_INFORMATION or SCOPE_SECURITY_INFORMATION, the caller must have the
SE_SECURITY_NAME privilege enabled. This parameter can be NULL if you are not setting the SACL.

Return value
If the function succeeds, the function returns ERROR_SUCCESS.
If the function fails, it returns a nonzero error code defined in WinError.h.

Remarks
If you are setting the discretionary access control list (DACL) or any elements in the system access control list
(SACL) of an object, the system automatically propagates any inheritable access control entries (ACEs) to
existing child objects, according to the ACE inheritance rules.
You can use the SetSecurityInfo function with the following types of objects:
Local or remote files or directories on an NTFS
Named pipes
Local or remote printers
Local or remote Windows services
Network shares
Registry keys
Semaphores, events, mutexes, and waitable timers
Processes, threads, jobs, and file-mapping objects
Window stations and desktops
Directory service objects
The SetSecurityInfo function does not reorder access-allowed or access-denied ACEs based on the preferred
order. When propagating inheritable ACEs to existing child objects, SetSecurityInfo puts inherited ACEs in
order after all of the noninherited ACEs in the DACLs of the child objects.

Note If share access to the children of the object is not available, this function will not propagate unprotected ACEs to the
children. For example, if a directory is opened with exclusive access, the operating system will not propagate unprotected
ACEs to the subdirectories or files of that directory when the security on the directory is changed.

Warning If the supplied handle was opened with an ACCESS_MASK value of MAXIMUM_ALLOWED , then the
SetSecurityInfo function will not propagate ACEs to children.

Requirements
 Minimum suppor ted client Windows XP [desktop apps | UWP apps]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps | UWP apps]

Target Platform Windows

Header aclapi.h

Librar y Advapi32.lib

DLL Advapi32.dll

See also
ACL
Access Control
Basic Access Control Functions
GetNamedSecurityInfo
GetSecurityInfo
SECURITY_DESCRIPTOR
SECURITY_INFORMATION
SE_OBJECT_TYPE
SID
SetNamedSecurityInfo
 TreeResetNamedSecurityInfoA function (aclapi.h)
7/2/2022 • 4 minutes to read • Edit Online

This version of this function is not supported. The wide character version of this function,
TreeResetNamedSecurityInfoW, is supported.

Syntax
DWORD TreeResetNamedSecurityInfoA(
[in] LPSTR pObjectName,
[in] SE_OBJECT_TYPE ObjectType,
[in] SECURITY_INFORMATION SecurityInfo,
[in, optional] PSID pOwner,
[in, optional] PSID pGroup,
[in, optional] PACL pDacl,
[in, optional] PACL pSacl,
[in] BOOL KeepExplicit,
[in, optional] FN_PROGRESS fnProgress,
[in] PROG_INVOKE_SETTING ProgressInvokeSetting,
[in, optional] PVOID Args
);

Parameters
[in] pObjectName

Pointer to a null -terminated string that specifies the name of the root node object for the objects that are to
receive updated security information. Supported objects are registry keys and file objects. For descriptions of
the string formats for the different object types, see SE_OBJECT_TYPE.
[in] ObjectType

A value of the SE_OBJECT_TYPE enumeration that indicates the type of object named by the pObjectName
parameter. The supported values are SE_REGISTRY_KEY and SE_FILE_OBJECT, for registry keys and file objects,
respectively.
[in] SecurityInfo

A set of bit flags that indicate the type of security information to reset. This parameter can be a combination of
the SECURITY_INFORMATION bit flags.
[in, optional] pOwner

A pointer to a SID structure that identifies the owner of the object. The SID must be one that can be assigned as
the owner SID of a security descriptor. The SecurityInfo parameter must include the
OWNER_SECURITY_INFORMATION flag. To set the owner, the caller must have WRITE_OWNER access to each
object, including the root object. If you are not setting the owner SID, this parameter can be NULL .
[in, optional] pGroup

A pointer to a SID structure that identifies the primary group of the object. The SecurityInfo parameter must
include the GROUP_SECURITY_INFORMATION flag. To set the group, the caller must have WRITE_OWNER
access to each object, including the root object. If you are not setting the primary group SID, this parameter can
be NULL .
[in, optional] pDacl

A pointer to an access control list (ACL) structure that represents the new DACL for the objects being reset. The
SecurityInfo parameter must include the DACL_SECURITY_INFORMATION flag. The caller must have
READ_CONTROL and WRITE_DAC access to each object, including the root object. If you are not setting the
DACL, this parameter can be NULL .
[in, optional] pSacl

A pointer to an ACL structure that represents the new SACL for the objects being reset. The SecurityInfo
parameter must include any of the following flags: SACL_SECURITY_INFORMATION,
LABEL_SECURITY_INFORMATION, ATTRIBUTE_SECURITY_INFORMATION, SCOPE_SECURITY_INFORMATION, or
BACKUP_SECURITY_INFORMATION. If setting SACL_SECURITY_INFORMATION or
SCOPE_SECURITY_INFORMATION, the caller must have the SE_SECURITY_NAME privilege enabled. If you are
not setting the SACL, this parameter can be NULL .
[in] KeepExplicit

Boolean value that defines whether explicitly defined ACEs are kept or deleted for the sub-tree. If KeepExplicit is
TRUE , then explicitly defined ACEs are kept for each subtree DACL and SACL, and inherited ACEs are replaced
by the inherited ACEs from pDacl and pSacl. If KeepExplicit is FALSE , then explicitly defined ACEs for each
subtree DACL and SACL are deleted before the inherited ACEs are replaced by the inherited ACEs from pDacl
and pSacl.
[in, optional] fnProgress

A pointer to the function used to track the progress of the TreeResetNamedSecurityInfo function. The
prototype of the progress function is:

#include <windows.h>
#include <Aclapi.h>

typedef VOID (*FN_PROGRESS) (

IN LPWSTR pObjectName, // Name of object just processed
IN DWORD Status, // Status of operation on object
IN OUT PPROG_INVOKE_SETTING pInvokeSetting, // When to set
IN PVOID Args, // Caller specific data
IN BOOL SecuritySet // Whether security was set
);

The progress function provides the caller with progress and error information when nodes are processed. The
caller specifies the progress function in fnProgress, and during the tree operation,
TreeResetNamedSecurityInfo passes the name of the last object processed, the error status of that operation,
and the current PROG_INVOKE_SETTING value. The caller can change the PROG_INVOKE_SETTING value by
using pInvokeSetting.
If no progress function is to be used, set this parameter to NULL .
[in] ProgressInvokeSetting

A value of the PROG_INVOKE_SETTING enumeration that specifies the initial setting for the progress function.
[in, optional] Args

A pointer to a VOID for progress function arguments specified by the caller.

Return value
If the function succeeds, the function returns ERROR_SUCCESS.
If the function fails, it returns an error code defined in WinError.h.

Remarks
Setting a NULL owner, group, DACL, or SACL is not supported by this function.
If the caller does not contain the proper privileges and permissions to support the requested owner, group,
DACL, and SACL updates, then none of the updates are performed.
This function is similar to the TreeSetNamedSecurityInfo function:
If the KeepExplicit parameter of TreeResetNamedSecurityInfo is set to TRUE , then the function is
equivalent to TreeSetNamedSecurityInfo with the dwAction parameter set to
TREE_SEC_INFO_RESET_KEEP_EXPLICIT.
If the KeepExplicit parameter of TreeResetNamedSecurityInfo is set to FALSE , then the function is
equivalent to TreeSetNamedSecurityInfo with the dwAction parameter set to TREE_SEC_INFO_RESET.

NOTE
The aclapi.h header defines TreeResetNamedSecurityInfo as an alias which automatically selects the ANSI or Unicode
version of this function based on the definition of the UNICODE preprocessor constant. Mixing usage of the encoding-
neutral alias with code that not encoding-neutral can lead to mismatches that result in compilation or runtime errors. For
more information, see Conventions for Function Prototypes.

Requirements

Minimum suppor ted client Windows XP [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header aclapi.h

Librar y Advapi32.lib

DLL Advapi32.dll
 TreeResetNamedSecurityInfoW function (aclapi.h)
7/2/2022 • 4 minutes to read • Edit Online

The TreeResetNamedSecurityInfo function resets specified security information in the security descriptor of a
specified tree of objects. This function allows a specified discretionary access control list (DACL) or any elements
in the system access control list (SACL) to be propagated throughout an entire tree. This function supports a
callback function to track the progress of the tree operation.

Syntax
DWORD TreeResetNamedSecurityInfoW(
[in] LPWSTR pObjectName,
[in] SE_OBJECT_TYPE ObjectType,
[in] SECURITY_INFORMATION SecurityInfo,
[in, optional] PSID pOwner,
[in, optional] PSID pGroup,
[in, optional] PACL pDacl,
[in, optional] PACL pSacl,
[in] BOOL KeepExplicit,
[in, optional] FN_PROGRESS fnProgress,
[in] PROG_INVOKE_SETTING ProgressInvokeSetting,
[in, optional] PVOID Args
);

Parameters
[in] pObjectName

Pointer to a null -terminated string that specifies the name of the root node object for the objects that are to
receive updated security information. Supported objects are registry keys and file objects. For descriptions of
the string formats for the different object types, see SE_OBJECT_TYPE.
[in] ObjectType

A value of the SE_OBJECT_TYPE enumeration that indicates the type of object named by the pObjectName
parameter. The supported values are SE_REGISTRY_KEY and SE_FILE_OBJECT, for registry keys and file objects,
respectively.
[in] SecurityInfo

A set of bit flags that indicate the type of security information to reset. This parameter can be a combination of
the SECURITY_INFORMATION bit flags.
[in, optional] pOwner

A pointer to a SID structure that identifies the owner of the object. The SID must be one that can be assigned as
the owner SID of a security descriptor. The SecurityInfo parameter must include the
OWNER_SECURITY_INFORMATION flag. To set the owner, the caller must have WRITE_OWNER access to each
object, including the root object. If you are not setting the owner SID, this parameter can be NULL .
[in, optional] pGroup

A pointer to a SID structure that identifies the primary group of the object. The SecurityInfo parameter must
include the GROUP_SECURITY_INFORMATION flag. To set the group, the caller must have WRITE_OWNER
access to each object, including the root object. If you are not setting the primary group SID, this parameter can
be NULL .
[in, optional] pDacl

A pointer to an access control list (ACL) structure that represents the new DACL for the objects being reset. The
SecurityInfo parameter must include the DACL_SECURITY_INFORMATION flag. The caller must have
READ_CONTROL and WRITE_DAC access to each object, including the root object. If you are not setting the
DACL, this parameter can be NULL .
[in, optional] pSacl

A pointer to an ACL structure that represents the new SACL for the objects being reset. The SecurityInfo
parameter must include any of the following flags: SACL_SECURITY_INFORMATION,
LABEL_SECURITY_INFORMATION, ATTRIBUTE_SECURITY_INFORMATION, SCOPE_SECURITY_INFORMATION, or
BACKUP_SECURITY_INFORMATION. If setting SACL_SECURITY_INFORMATION or
SCOPE_SECURITY_INFORMATION, the caller must have the SE_SECURITY_NAME privilege enabled. If you are
not setting the SACL, this parameter can be NULL .
[in] KeepExplicit

Boolean value that defines whether explicitly defined ACEs are kept or deleted for the sub-tree. If KeepExplicit is
TRUE , then explicitly defined ACEs are kept for each subtree DACL and SACL, and inherited ACEs are replaced
by the inherited ACEs from pDacl and pSacl. If KeepExplicit is FALSE , then explicitly defined ACEs for each
subtree DACL and SACL are deleted before the inherited ACEs are replaced by the inherited ACEs from pDacl
and pSacl.
[in, optional] fnProgress

A pointer to the function used to track the progress of the TreeResetNamedSecurityInfo function. The
prototype of the progress function is:

#include <windows.h>
#include <Aclapi.h>

typedef VOID (*FN_PROGRESS) (

IN LPWSTR pObjectName, // Name of object just processed
IN DWORD Status, // Status of operation on object
IN OUT PPROG_INVOKE_SETTING pInvokeSetting, // When to set
IN PVOID Args, // Caller specific data
IN BOOL SecuritySet // Whether security was set
);

The progress function provides the caller with progress and error information when nodes are processed. The
caller specifies the progress function in fnProgress, and during the tree operation,
TreeResetNamedSecurityInfo passes the name of the last object processed, the error status of that operation,
and the current PROG_INVOKE_SETTING value. The caller can change the PROG_INVOKE_SETTING value by
using pInvokeSetting.
If no progress function is to be used, set this parameter to NULL .
[in] ProgressInvokeSetting

A value of the PROG_INVOKE_SETTING enumeration that specifies the initial setting for the progress function.
[in, optional] Args

A pointer to a VOID for progress function arguments specified by the caller.

Return value
If the function succeeds, the function returns ERROR_SUCCESS.
If the function fails, it returns an error code defined in WinError.h.

Remarks
Setting a NULL owner, group, DACL, or SACL is not supported by this function.
If the caller does not contain the proper privileges and permissions to support the requested owner, group,
DACL, and SACL updates, then none of the updates are performed.
This function is similar to the TreeSetNamedSecurityInfo function:
If the KeepExplicit parameter of TreeResetNamedSecurityInfo is set to TRUE , then the function is
equivalent to TreeSetNamedSecurityInfo with the dwAction parameter set to
TREE_SEC_INFO_RESET_KEEP_EXPLICIT.
If the KeepExplicit parameter of TreeResetNamedSecurityInfo is set to FALSE , then the function is
equivalent to TreeSetNamedSecurityInfo with the dwAction parameter set to TREE_SEC_INFO_RESET.

NOTE
The aclapi.h header defines TreeResetNamedSecurityInfo as an alias which automatically selects the ANSI or Unicode
version of this function based on the definition of the UNICODE preprocessor constant. Mixing usage of the encoding-
neutral alias with code that not encoding-neutral can lead to mismatches that result in compilation or runtime errors. For
more information, see Conventions for Function Prototypes.

Requirements

Minimum suppor ted client Windows XP [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header aclapi.h

Librar y Advapi32.lib

DLL Advapi32.dll
 TreeSetNamedSecurityInfoA function (aclapi.h)
7/2/2022 • 5 minutes to read • Edit Online

This version of this function is not supported. The wide character version of this function,
TreeSetNamedSecurityInfoW, is supported.

Syntax
DWORD TreeSetNamedSecurityInfoA(
[in] LPSTR pObjectName,
[in] SE_OBJECT_TYPE ObjectType,
[in] SECURITY_INFORMATION SecurityInfo,
[in, optional] PSID pOwner,
[in, optional] PSID pGroup,
[in, optional] PACL pDacl,
[in, optional] PACL pSacl,
[in] DWORD dwAction,
[in] FN_PROGRESS fnProgress,
[in] PROG_INVOKE_SETTING ProgressInvokeSetting,
[in, optional] PVOID Args
);

Parameters
[in] pObjectName

Pointer to a null -terminated string that specifies the name of the root node object for the objects that are to
receive updated security information. Supported objects are registry keys and file objects. For descriptions of
the string formats for the different object types, see SE_OBJECT_TYPE.
[in] ObjectType

A value of the SE_OBJECT_TYPE enumeration that indicates the type of object named by the pObjectName
parameter. The supported values are SE_REGISTRY_KEY and SE_FILE_OBJECT, for registry keys and file objects,
respectively.
[in] SecurityInfo

A set of bit flags that indicate the type of security information to set. This parameter can be a combination of the
SECURITY_INFORMATION bit flags.
[in, optional] pOwner

A pointer to a SID structure that identifies the owner of the object. The SID must be one that can be assigned as
the owner SID of a security descriptor. The SecurityInfo parameter must include the
OWNER_SECURITY_INFORMATION flag. To set the owner, the caller must have WRITE_OWNER access to each
object, including the root object. If you are not setting the owner SID, this parameter can be NULL .
[in, optional] pGroup

A pointer to a SID structure that identifies the primary group of the object. The SecurityInfo parameter must
include the GROUP_SECURITY_INFORMATION flag. To set the group, the caller must have WRITE_OWNER
access to each object, including the root object. If you are not setting the primary group SID, this parameter can
be NULL .
[in, optional] pDacl

A pointer to an access control list (ACL) structure that represents the new DACL for the objects being reset. The
SecurityInfo parameter must include the DACL_SECURITY_INFORMATION flag. The caller must have
READ_CONTROL and WRITE_DAC access to each object, including the root object. If you are not setting the
DACL, this parameter can be NULL .
[in, optional] pSacl

A pointer to an ACL structure that represents the new SACL for the objects being reset. The SecurityInfo
parameter must include any of the following flags: SACL_SECURITY_INFORMATION,
LABEL_SECURITY_INFORMATION, ATTRIBUTE_SECURITY_INFORMATION, SCOPE_SECURITY_INFORMATION, or
BACKUP_SECURITY_INFORMATION. If setting SACL_SECURITY_INFORMATION or
SCOPE_SECURITY_INFORMATION, the caller must have the SE_SECURITY_NAME privilege enabled. If you are
not setting the SACL, this parameter can be NULL .
[in] dwAction

Specifies the behavior of this function. This must be set to one of the following values, defined in AccCtrl.h.

VA L UE M EA N IN G

The security information is set on the object specified by the

TREE_SEC_INFO_SET pObjectName parameter and the tree of child objects of that
0x00000001 object. If ACLs are specified in either the pDacl or pSacl
parameters, the security descriptors are associated with the
object. The security descriptors are propagated to the tree of
child objects based on their inheritance properties.

The security information is reset on the object specified by

TREE_SEC_INFO_RESET the pObjectName parameter and the tree of child objects of
0x00000002 that object. Any existing security information is removed
from all objects on the tree.
If any object in the tree does not grant appropriate
permissions to the caller to modify the security
descriptor on the object, then the propagation of
security information on that particular node of the tree
and its objects is skipped. The operation continues on
the rest of the tree under the object specified by the
pObjectName parameter.

The security information is reset on the object specified by

TREE_SEC_INFO_RESET_KEEP_EXPLICIT the pObjectName parameter and the tree of child objects of
0x00000003 that object. Any existing inherited security information is
removed from all objects on the tree. Security information
that was explicitly set on objects in the tree is unchanged.
If any object in the tree does not grant appropriate
permissions to the caller to modify the security
descriptor on the object, then the propagation of
security information on that particular node of the tree
and its objects is skipped. The operation continues on
the rest of the tree under the object specified by the
pObjectName parameter.

[in] fnProgress

A pointer to the function used to track the progress of the TreeSetNamedSecurityInfo function. The prototype
of the progress function is:
 #include <windows.h>
#include <Aclapi.h>
#pragma comment(lib, "Advapi32.lib")

typedef VOID (*FN_PROGRESS) (

IN LPWSTR pObjectName, // Name of object just processed
IN DWORD Status, // Status of operation on object
IN OUT PPROG_INVOKE_SETTING
pInvokeSetting, // When to set
IN PVOID Args, // Caller specific data
IN BOOL SecuritySet // Whether security was set
);

The progress function provides the caller with progress and error information when nodes are processed. The
caller specifies the progress function in fnProgress, and during the tree operation, TreeSetNamedSecurityInfo
passes the name of the last object processed, the error status of that operation, and the current
PROG_INVOKE_SETTING value. The caller can change the PROG_INVOKE_SETTING value by using
pInvokeSetting.
If no progress function is to be used, set this parameter to NULL .
[in] ProgressInvokeSetting

A value of the PROG_INVOKE_SETTING enumeration that specifies the initial setting for the progress function.
[in, optional] Args

A pointer to a VOID for progress function arguments specified by the caller.

Return value
If the function succeeds, the function returns ERROR_SUCCESS .
If the function fails, it returns an error code defined in WinError.h.

Remarks
Setting a NULL owner, group, DACL, or SACL is not supported by this function.
If the caller does not contain the proper privileges and permissions to support the requested owner, group,
DACL, and SACL updates, then none of the updates is performed.
This function provides the same functionality as the SetNamedSecurityInfo function when the value of the
dwAction parameter is set to TREE_SEC_INFO_SET , the value of the ProgressInvokeSetting parameter is set to
ProgressInvokePrePostError , and the function pointed to by the fnProgress parameter sets the value of its
pInvokeSetting parameter to ProgressInvokePrePostError .
This function is similar to the TreeResetNamedSecurityInfo function:
If the dwAction parameter of TreeSetNamedSecurityInfo is set to TREE_SEC_INFO_RESET_KEEP_EXPLICIT,
then the function is equivalent to TreeResetNamedSecurityInfo with the KeepExplicit parameter set to TRUE .
If the dwAction parameter of TreeSetNamedSecurityInfo is set to TREE_SEC_INFO_RESET, then the
function is equivalent to TreeResetNamedSecurityInfo with the KeepExplicit parameter set to FALSE .
 NOTE
The aclapi.h header defines TreeSetNamedSecurityInfo as an alias which automatically selects the ANSI or Unicode version
of this function based on the definition of the UNICODE preprocessor constant. Mixing usage of the encoding-neutral
alias with code that not encoding-neutral can lead to mismatches that result in compilation or runtime errors. For more
information, see Conventions for Function Prototypes.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header aclapi.h

Librar y Advapi32.lib

DLL Advapi32.dll
 TreeSetNamedSecurityInfoW function (aclapi.h)
7/2/2022 • 5 minutes to read • Edit Online

The TreeSetNamedSecurityInfo function sets specified security information in the security descriptor of a
specified tree of objects. This function allows a specified discretionary access control list (DACL) or any elements
in the system access control list (SACL) to be propagated throughout an entire tree. This function supports a
callback function to track the progress of the tree operation.

Syntax
DWORD TreeSetNamedSecurityInfoW(
[in] LPWSTR pObjectName,
[in] SE_OBJECT_TYPE ObjectType,
[in] SECURITY_INFORMATION SecurityInfo,
[in, optional] PSID pOwner,
[in, optional] PSID pGroup,
[in, optional] PACL pDacl,
[in, optional] PACL pSacl,
[in] DWORD dwAction,
[in] FN_PROGRESS fnProgress,
[in] PROG_INVOKE_SETTING ProgressInvokeSetting,
[in, optional] PVOID Args
);

Parameters
[in] pObjectName

Pointer to a null -terminated string that specifies the name of the root node object for the objects that are to
receive updated security information. Supported objects are registry keys and file objects. For descriptions of
the string formats for the different object types, see SE_OBJECT_TYPE.
[in] ObjectType

A value of the SE_OBJECT_TYPE enumeration that indicates the type of object named by the pObjectName
parameter. The supported values are SE_REGISTRY_KEY and SE_FILE_OBJECT, for registry keys and file objects,
respectively.
[in] SecurityInfo

A set of bit flags that indicate the type of security information to set. This parameter can be a combination of the
SECURITY_INFORMATION bit flags.
[in, optional] pOwner

A pointer to a SID structure that identifies the owner of the object. The SID must be one that can be assigned as
the owner SID of a security descriptor. The SecurityInfo parameter must include the
OWNER_SECURITY_INFORMATION flag. To set the owner, the caller must have WRITE_OWNER access to each
object, including the root object. If you are not setting the owner SID, this parameter can be NULL .
[in, optional] pGroup

A pointer to a SID structure that identifies the primary group of the object. The SecurityInfo parameter must
include the GROUP_SECURITY_INFORMATION flag. To set the group, the caller must have WRITE_OWNER
access to each object, including the root object. If you are not setting the primary group SID, this parameter can
be NULL .
[in, optional] pDacl

A pointer to an access control list (ACL) structure that represents the new DACL for the objects being reset. The
SecurityInfo parameter must include the DACL_SECURITY_INFORMATION flag. The caller must have
READ_CONTROL and WRITE_DAC access to each object, including the root object. If you are not setting the
DACL, this parameter can be NULL .
[in, optional] pSacl

A pointer to an ACL structure that represents the new SACL for the objects being reset. The SecurityInfo
parameter must include any of the following flags: SACL_SECURITY_INFORMATION,
LABEL_SECURITY_INFORMATION, ATTRIBUTE_SECURITY_INFORMATION, SCOPE_SECURITY_INFORMATION, or
BACKUP_SECURITY_INFORMATION. If setting SACL_SECURITY_INFORMATION or
SCOPE_SECURITY_INFORMATION, the caller must have the SE_SECURITY_NAME privilege enabled. If you are
not setting the SACL, this parameter can be NULL .
[in] dwAction

Specifies the behavior of this function. This must be set to one of the following values, defined in AccCtrl.h.

VA L UE M EA N IN G

The security information is set on the object specified by the

TREE_SEC_INFO_SET pObjectName parameter and the tree of child objects of that
0x00000001 object. If ACLs are specified in either the pDacl or pSacl
parameters, the security descriptors are associated with the
object. The security descriptors are propagated to the tree of
child objects based on their inheritance properties.

The security information is reset on the object specified by

TREE_SEC_INFO_RESET the pObjectName parameter and the tree of child objects of
0x00000002 that object. Any existing security information is removed
from all objects on the tree.
If any object in the tree does not grant appropriate
permissions to the caller to modify the security
descriptor on the object, then the propagation of
security information on that particular node of the tree
and its objects is skipped. The operation continues on
the rest of the tree under the object specified by the
pObjectName parameter.

The security information is reset on the object specified by

TREE_SEC_INFO_RESET_KEEP_EXPLICIT the pObjectName parameter and the tree of child objects of
0x00000003 that object. Any existing inherited security information is
removed from all objects on the tree. Security information
that was explicitly set on objects in the tree is unchanged.
If any object in the tree does not grant appropriate
permissions to the caller to modify the security
descriptor on the object, then the propagation of
security information on that particular node of the tree
and its objects is skipped. The operation continues on
the rest of the tree under the object specified by the
pObjectName parameter.

[in] fnProgress
A pointer to the function used to track the progress of the TreeSetNamedSecurityInfo function. The prototype
of the progress function is:

#include <windows.h>
#include <Aclapi.h>
#pragma comment(lib, "Advapi32.lib")

typedef VOID (*FN_PROGRESS) (

IN LPWSTR pObjectName, // Name of object just processed
IN DWORD Status, // Status of operation on object
IN OUT PPROG_INVOKE_SETTING
pInvokeSetting, // When to set
IN PVOID Args, // Caller specific data
IN BOOL SecuritySet // Whether security was set
);

The progress function provides the caller with progress and error information when nodes are processed. The
caller specifies the progress function in fnProgress, and during the tree operation, TreeSetNamedSecurityInfo
passes the name of the last object processed, the error status of that operation, and the current
PROG_INVOKE_SETTING value. The caller can change the PROG_INVOKE_SETTING value by using
pInvokeSetting.
If no progress function is to be used, set this parameter to NULL .
[in] ProgressInvokeSetting

A value of the PROG_INVOKE_SETTING enumeration that specifies the initial setting for the progress function.
[in, optional] Args

A pointer to a VOID for progress function arguments specified by the caller.

Return value
If the function succeeds, the function returns ERROR_SUCCESS .
If the function fails, it returns an error code defined in WinError.h.

Remarks
Setting a NULL owner, group, DACL, or SACL is not supported by this function.
If the caller does not contain the proper privileges and permissions to support the requested owner, group,
DACL, and SACL updates, then none of the updates is performed.
This function provides the same functionality as the SetNamedSecurityInfo function when the value of the
dwAction parameter is set to TREE_SEC_INFO_SET , the value of the ProgressInvokeSetting parameter is set to
ProgressInvokePrePostError , and the function pointed to by the fnProgress parameter sets the value of its
pInvokeSetting parameter to ProgressInvokePrePostError .
This function is similar to the TreeResetNamedSecurityInfo function:
If the dwAction parameter of TreeSetNamedSecurityInfo is set to TREE_SEC_INFO_RESET_KEEP_EXPLICIT,
then the function is equivalent to TreeResetNamedSecurityInfo with the KeepExplicit parameter set to TRUE .
If the dwAction parameter of TreeSetNamedSecurityInfo is set to TREE_SEC_INFO_RESET, then the
function is equivalent to TreeResetNamedSecurityInfo with the KeepExplicit parameter set to FALSE .
 NOTE
The aclapi.h header defines TreeSetNamedSecurityInfo as an alias which automatically selects the ANSI or Unicode version
of this function based on the definition of the UNICODE preprocessor constant. Mixing usage of the encoding-neutral
alias with code that not encoding-neutral can lead to mismatches that result in compilation or runtime errors. For more
information, see Conventions for Function Prototypes.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header aclapi.h

Librar y Advapi32.lib

DLL Advapi32.dll
 aclui.h header
7/2/2022 • 2 minutes to read • Edit Online

This header is used by multiple technologies. For more information, see:

CIMWin32 WMI Providers
Security and Identity
aclui.h contains the following programming interfaces:

Interfaces

IEffectivePermission

Provides a means to determine effective permission for a security principal on an object.

IEffectivePermission2

Provides a way to determine effective permission for a security principal on an object.

ISecurityInformation

Enables the access control editor to communicate with the caller of the CreateSecurityPage and EditSecurity functions.

ISecurityInformation2

Enables the access control editor to obtain information from the client that is not provided by the ISecurityInformation
interface.

ISecurityInformation3

Provides methods necessary for displaying an elevated access control editor when a user clicks the Edit button on an access
control editor page that displays an image of a shield on that Edit button.

ISecurityInformation4

Enables the access control editor (ACE) to obtain the share's security descriptor to initialize the share page.

ISecurityObjectTypeInfo

Provides a means of determining the source of inherited access control entries (ACEs) in discretionary access control lists
(DACLs) and system access control lists (SACLs).

Functions
 CreateSecurityPage

Creates a basic security property page that enables the user to view and edit the access rights allowed or denied by the access
control entries (ACEs) in an object's discretionary access control list (DACL).

EditSecurity

Displays a property sheet that contains a basic security property page. This property page enables the user to view and edit
the access rights allowed or denied by the ACEs in an object's DACL.

EditSecurityAdvanced

Extends the EditSecurity function to include the security page type when displaying the property sheet that contains a basic
security property page.

Structures

EFFPERM_RESULT_LIST

Lists the effective permissions.

SECURITY_OBJECT

Contains the security object information.

SI_ACCESS

Contains information about an access right or default access mask for a securable object.

SI_INHERIT_TYPE

Contains information about how access control entries (ACEs) can be inherited by child objects.

SI_OBJECT_INFO

Used to initialize the access control editor.

SID_INFO

Contains the list of common names corresponding to the SID structures returned by ISecurityInformation2::LookupSids.

SID_INFO_LIST

Contains a list of SID_INFO structures.

Enumerations
SI_PAGE_TYPE

Contains values that indicate the types of property pages in an access control editor property sheet.
 CreateSecurityPage function (aclui.h)
7/2/2022 • 2 minutes to read • Edit Online

The CreateSecurityPage function creates a basic security property page that enables the user to view and edit
the access rights allowed or denied by the access control entries (ACEs) in an object's discretionary access
control list (DACL). Use the PropertySheet function or the PSM_ADDPAGE message to add this page to a
property sheet.

Syntax
HPROPSHEETPAGE ACLUIAPI CreateSecurityPage(
[in] LPSECURITYINFO psi
);

Parameters
[in] psi

A pointer to your implementation of the ISecurityInformation interface. The system calls the interface methods
to retrieve information about the object being edited and to return the user's input.

Return value
If the function succeeds, the function returns a handle to a basic security property page.
If the function fails, it returns NULL . To get extended error information, call GetLastError.

Remarks
During the property page initialization, the system calls the ISecurityInformation::GetSecurity and
ISecurityInformation::SetSecurity methods to determine whether the user has permission to edit the object's
security descriptor. The system displays an error message if the user does not have permission.
The basic security property page can include an Advanced button for displaying the advanced security
property sheet. This advanced security property sheet can contain three additional property pages that enable
the user to view and edit the object's DACL, system access control list (SACL), and owner.

Requirements

Minimum suppor ted client Windows XP [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header aclui.h
 Librar y Aclui.lib

DLL Aclui.dll

See also
Access Control Editor
Access Control Editor Functions
EditSecurity
GetSecurity
ISecurityInformation
PSM_ADDPAGE
PropertySheet
SetSecurity
 EditSecurity function (aclui.h)
7/2/2022 • 2 minutes to read • Edit Online

The EditSecurity function displays a property sheet that contains a basic security property page. This property
page enables the user to view and edit the access rights allowed or denied by the ACEs in an object's DACL.

Syntax
BOOL ACLUIAPI EditSecurity(
[in] HWND hwndOwner,
[in] LPSECURITYINFO psi
);

Parameters
[in] hwndOwner

A handle to the window that owns the property sheet. This parameter can be NULL .
[in] psi

A pointer to your implementation of the ISecurityInformation interface. The system calls the interface methods
to retrieve information about the object being edited and to return the user's input.

Return value
If the function succeeds, the return value is a nonzero value.
If the function fails, the return value is zero. To get extended error information, call GetLastError.

Remarks
The EditSecurity function calls the CreateSecurityPage function to create a basic security property page.
During the property page initialization, the system calls the ISecurityInformation::GetSecurity and
ISecurityInformation::SetSecurity methods to determine whether the user has permission to edit the object's
security descriptor. The system displays an error message if the user does not have permission.
The basic security property page can include an Advanced button for displaying the advanced security
property sheet. This advanced security property sheet can contain three additional property pages that enable
the user to view and edit the object's DACL, SACL, and owner.

Requirements

Minimum suppor ted client Windows XP [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

 Header aclui.h

Librar y Aclui.lib

DLL Aclui.dll

See also
Access Control Editor
Access Control Editor Functions
CreateSecurityPage
GetSecurity
ISecurityInformation
SetSecurity
 EditSecurityAdvanced function (aclui.h)
7/2/2022 • 2 minutes to read • Edit Online

The EditSecurityAdvanced function extends the EditSecurity function to include the security page type when
displaying the property sheet that contains a basic security property page. This property page enables the user
to view and edit the access rights allowed or denied by the access control entries (ACEs) in an object's
discretionary access control list (DACL).

Syntax
HRESULT ACLUIAPI EditSecurityAdvanced(
[in] HWND hwndOwner,
[in] LPSECURITYINFO psi,
[in] SI_PAGE_TYPE uSIPage
);

Parameters
[in] hwndOwner

A handle to the window that owns the property sheet. This parameter can be NULL .
[in] psi

A pointer to your implementation of the ISecurityInformation interface. The system calls the interface methods
to retrieve information about the object being edited and to return the user's input.
[in] uSIPage

A value of the SI_PAGE_TYPE enumeration that indicates the page type on which to display the elevated access
control editor.

Return value
If the function succeeds, the return value is S_OK.
If the function fails, any other HRESULT value indicates an error. For a list of common error codes, see Common
HRESULT Values.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header aclui.h
 Librar y Aclui.lib

DLL Aclui.dll

See also
Access Control Editor
Access Control Editor Functions
CreateSecurityPage
EditSecurity
GetSecurity
ISecurityInformation
SetSecurity
 EFFPERM_RESULT_LIST structure (aclui.h)
7/2/2022 • 2 minutes to read • Edit Online

The EFFPERM_RESULT_LIST structure lists the effective permissions.

Syntax
typedef struct _EFFPERM_RESULT_LIST {
BOOLEAN fEvaluated;
ULONG cObjectTypeListLength;
OBJECT_TYPE_LIST *pObjectTypeList;
ACCESS_MASK *pGrantedAccessList;
} EFFPERM_RESULT_LIST, *PEFFPERM_RESULT_LIST;

Members
fEvaluated

Indicates if the effective permissions results have been evaluated.

cObjectTypeListLength

The number of elements in both the pObjectTypeList and pGrantedAccessList members.

pObjectTypeList

A pointer to an array of OBJECT_TYPE_LIST structures that specifies the properties and property sets for which
access was evaluated.
pGrantedAccessList

A pointer to an array of ACCESS_MASK values that specifies the access rights granted for each corresponding
object type.

Requirements

Minimum suppor ted client Windows 8 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2012 [desktop apps only]

Header aclui.h
 IEffectivePermission interface (aclui.h)
7/2/2022 • 2 minutes to read • Edit Online

The IEffectivePermission interface provides a means to determine effective permission for a security principal
on an object. The access control editor uses this information to communicate the effective permission to the
client.

Inheritance
The IEffectivePermission interface inherits from the IUnknown interface. IEffectivePermission also has
these types of members:

Methods
The IEffectivePermission interface has these methods.

IEffectivePermission::GetEffectivePermission

Returns the effective permission for an object type.

Requirements

Minimum suppor ted client Windows XP [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header aclui.h

See also
ISecurityInformation2
ISecurityObjectTypeInfo
 IEffectivePermission::GetEffectivePermission method
(aclui.h)
7/2/2022 • 2 minutes to read • Edit Online

The GetEffectivePermission method returns the effective permission for an object type.

Syntax
HRESULT GetEffectivePermission(
[in] const GUID *pguidObjectType,
[in] PSID pUserSid,
[in] LPCWSTR pszServerName,
[in] PSECURITY_DESCRIPTOR pSD,
[out] POBJECT_TYPE_LIST *ppObjectTypeList,
[out] ULONG *pcObjectTypeListLength,
[out] PACCESS_MASK *ppGrantedAccessList,
[out] ULONG *pcGrantedAccessListLength
);

Parameters
[in] pguidObjectType

A GUID for the object type whose permission is being queried.

[in] pUserSid

A pointer to a SID structure that represents the security principal whose effective permission is being
determined.
[in] pszServerName

A pointer to null-terminated wide character string that represents the server name.
[in] pSD

A pointer to a SECURITY_DESCRIPTOR structure that represents the object's security descriptor. The security
descriptor is used to perform the access check.
[out] ppObjectTypeList

A pointer to a pointer to an OBJECT_TYPE_LIST structure that represents the array of object types in the object
tree for the object. If an object does not support property access, use the following technique to specify the
value for the OBJECT_TYPE_LIST .

#include <windows.h>

OBJECT_TYPE_LIST g_DefaultOTL[] = {
{0, 0, (LPGUID)&GUID_NULL},
};
[out] pcObjectTypeListLength

A pointer to a ULONG that receives the count of object types pointed to by ppObjectTypeList.
[out] ppGrantedAccessList

A pointer to a pointer to an ACCESS_MASK that receives the array of granted access masks. The operating
system will use LocalFree to free the memory allocated for this parameter.
[out] pcGrantedAccessListLength

A pointer to a ULONG variable that receives the count of granted access masks pointed to by the
ppGrantedAccessList parameter.

Return value
If the function is successful, the return value is S_OK.
If the function fails, the return value is an HRESULT that indicates the error. For a list of common error codes,
see Common HRESULT Values.

Requirements

Minimum suppor ted client Windows XP [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header aclui.h
 IEffectivePermission2 interface (aclui.h)
7/2/2022 • 2 minutes to read • Edit Online

The IEffectivePermission2 interface provides a way to determine effective permissions for a security principal
on an object in a way where the principal's security context may be compounded with a device context or
adjusted in other ways. Additionally, it determines the effective permissions even when multiple security checks
apply. The access control editor uses this information to communicate the effective permissions to the client.

Inheritance
The IEffectivePermission2 interface inherits from the IUnknown interface. IEffectivePermission2 also has
these types of members:

Methods
The IEffectivePermission2 interface has these methods.

IEffectivePermission2::ComputeEffectivePermissionWithSecondarySecurity

Computes the effective permissions by using the secondary security for an object.

Remarks
The IEffectivePermission2 interface should be implemented by resource managers that support dynamic
access control or by resource managers where the effective access to an object is determined by more than one
security check, for example, a security descriptor and a firewall.
The resource manager typically implements ISecurityInformation4 before implementing
IEffectivePermission2 because IEffectivePermission2 interprets the SECURITY_OBJECT returned by the
GetSecondarySecurity method.
If the IEffectivePermission2 interface is implemented, then the IEffectivePermission interface is not used.

Requirements

Minimum suppor ted client Windows 8 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2012 [desktop apps only]

Target Platform Windows

Header aclui.h

See also
IEffectivePermission
 IEffectivePermission2::ComputeEffectivePermissionWithSecondarySecurity
method (aclui.h)
7/2/2022 • 5 minutes to read • Edit Online

The ComputeEffectivePermissionWithSecondar ySecurity method computes the effective permissions for

an object. It supports integrating secondary or custom security policies. You may choose to provide this
additional security information by implementing the ISecurityInformation4 interface. This method supports
compound identity, which is when a principal's access token contains user and device authorization information.

Syntax
HRESULT ComputeEffectivePermissionWithSecondarySecurity(
[in] PSID pSid,
[in, optional] PSID pDeviceSid,
[in, optional] PCWSTR pszServerName,
[in] PSECURITY_OBJECT pSecurityObjects,
[in] DWORD dwSecurityObjectCount,
[in, optional] PTOKEN_GROUPS pUserGroups,
[in, optional] PAUTHZ_SID_OPERATION pAuthzUserGroupsOperations,
[in, optional] PTOKEN_GROUPS pDeviceGroups,
[in, optional] PAUTHZ_SID_OPERATION pAuthzDeviceGroupsOperations,
[in, optional] PAUTHZ_SECURITY_ATTRIBUTES_INFORMATION pAuthzUserClaims,
[in, optional] PAUTHZ_SECURITY_ATTRIBUTE_OPERATION pAuthzUserClaimsOperations,
[in, optional] PAUTHZ_SECURITY_ATTRIBUTES_INFORMATION pAuthzDeviceClaims,
[in, optional] PAUTHZ_SECURITY_ATTRIBUTE_OPERATION pAuthzDeviceClaimsOperations,
[in, out] PEFFPERM_RESULT_LIST pEffpermResultLists
);

Parameters
[in] pSid

A pointer to a SID structure that represents the security principal whose effective permission is being
determined.
[in, optional] pDeviceSid

A pointer to a SID structure that represents the device from which the principal is accessing the object. If this is
not NULL and you are using the AuthzAccessCheck function to compute the effective permissions, then the
device SID may be compounded with the pSid parameter by using the AuthzInitializeCompoundContext
function.
[in, optional] pszServerName

The name of the server on which the object resides. This is the same name that was returned from the
ISecurityInformation::GetObjectInformation method.
[in] pSecurityObjects

An array of security objects. This array is composed of objects that were deduced by the access control editor in
addition to the ones returned from the ISecurityInformation4::GetSecondarySecurity method.
[in] dwSecurityObjectCount

The number of security objects in the pSecurityObjects parameter, and the number of results lists in the
pEffpermResultLists parameter.
[in, optional] pUserGroups

A pointer to additional user groups that should be used to modify the security context which was initialized from
the pSid parameter. If you are using the AuthzAccessCheck function to compute the effective permissions, then
the modification may be done by calling the AuthzModifySids function using AuthzContextInfoGroupsSids as
the SidClass parameter.
[in, optional] pAuthzUserGroupsOperations

Pointer to an array of AUTHZ_SID_OPERATION structures that specify how the user groups in the authz context
must be modified for each user group in the pUserGroups argument. This array contains as many elements as
the number of groups in the pUserGroups parameter.
[in, optional] pDeviceGroups

A pointer to additional device groups that should be used to modify the security context which was initialized
from the pSid parameter or one that was created by compounding the contexts that were initialized from the
pSid and pDeviceSid parameters. If you are using the AuthzAccessCheck function to compute the effective
permissions, then the modification may be done by calling the AuthzModifySids function using
AuthzContextInfoDeviceSids as the SidClass parameter.
[in, optional] pAuthzDeviceGroupsOperations

Pointer to an array of AUTHZ_SID_OPERATION enumeration types that specify how the device groups in the
authz context must be modified for each device group in the pDeviceGroups argument. This array contains as
many elements as the number of groups in the pDeviceGroups parameter.
[in, optional] pAuthzUserClaims

Pointer to an AUTHZ_SECURITY_ATTRIBUTES_INFORMATION structure that contains the user claims context that
should be used to modify the security context that was initialized from the pSid parameter. If you are using the
AuthzAccessCheck function to compute the effective permissions, then the modification may be done by calling
the AuthzModifyClaims function using AuthzContextInfoUserClaims as the ClaimClass parameter.
[in, optional] pAuthzUserClaimsOperations

Pointer to an AUTHZ_SECURITY_ATTRIBUTE_OPERATION enumeration type that specifies the operations

associated with the user claims context.
[in, optional] pAuthzDeviceClaims

A pointer to the device claims context that should be used to modify the security context that was initialized
from the pSid parameter or one that was created by compounding the contexts that were initialized from the
pSid and pDeviceSid parameters. This may be supplied by the caller, even if the pDeviceSid parameter is not. If
you are using the AuthzAccessCheck function to compute the effective permissions, then the modification may
be done by calling the AuthzModifyClaims function using AuthzContextInfoDeviceClaims as the ClaimClass
parameter.
[in, optional] pAuthzDeviceClaimsOperations

Pointer to an AUTHZ_SECURITY_ATTRIBUTE_OPERATION enumeration type that specifies the operations

associated with the device claims context.
[in, out] pEffpermResultLists

A pointer to an array of the effective permissions results of type EFFPERM_RESULT_LIST. This array is
dwSecurityObjectCount elements long. The array is initialized by the caller and the implementation is expected
to set all fields of each member in the array, indicating what access was granted by the corresponding security
object.
If a security object was considered, the fEvaluated member should be set to TRUE . In this case, the
pObjectTypeList and pGrantedAccessList members should both be cObjectTypeListLength elements
long. The pObjectTypeList member must point to memory that is owned by the resource manager and must
remain valid until the EditSecurity function exits. The pGrantedAccessList member is freed by the caller by
using the LocalFree function. If the resource manager does not support object ACEs, then the pObjectTypeList
member should point to the NULL GUID, the cObjectTypeListLength member should be 1, and the
pGrantedAccessList member should be a single DWORD.

Return value
If the function is successful, the return value is S_OK.
If the function is successful but returned an approximate result, the return value is S_FALSE.
If the function fails, the return value is an HRESULT that indicates the error. For a list of common error codes,
see Common HRESULT Values.

Remarks
When the Id member the SECURITY_OBJECT structure is set to SECURITY_OBJECT_ID_CENTRAL_ACCESS_RULE,
the ComputeEffectivePermissionWithSecondar ySecurity method should use the pData2 member first
and only then evaluate access by using the pData member.
It is expected that the caller will use AuthzAccessCheck to determine the effective permissions. When possible,
the implementation should initialize a remote resource manager on the supplied pszSer verName member,
using the AuthzInitializeRemoteResourceManager function to ensure that the groups and claims are initialized in
the same manner as when the principal really accesses the object. If
AuthzInitializeRemoteResourceManager fails, the implementation may fall back to using the
AuthzInitializeResourceManager function and return S_FALSE to indicate that approximate results are returned.
For each of the secondary security objects whose fEvaluated member is set to TRUE , the access control editor
will display which permissions and properties were limited by that object using the pwszName member.

Requirements

Minimum suppor ted client Windows 8 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2012 [desktop apps only]

Target Platform Windows

Header aclui.h

See also
AUTHZ_SECURITY_ATTRIBUTE_OPERATION
AuthzInitializeRemoteResourceManager
IEffectivePermission2
ISecurityInformation4::GetSecondarySecurity
SECURITY_OBJECT
 ISecurityInformation interface (aclui.h)
7/2/2022 • 2 minutes to read • Edit Online

The ISecurityInformation interface enables the access control editor to communicate with the caller of the
CreateSecurityPage and EditSecurity functions. The editor calls the interface methods to retrieve information
that is used to initialize its pages and to determine the editing options available to the user. The editor also calls
the interface methods to pass the user's input back to the application.
The LPSECURITYINFO type is a pointer to an ISecurityInformation object.

Inheritance
The ISecurityInformation interface inherits from the IUnknown interface. ISecurityInformation also has
these types of members:

Methods
The ISecurityInformation interface has these methods.

ISecurityInformation::GetAccessRights

The GetAccessRights method requests information about the access rights that can be controlled for a securable object.

ISecurityInformation::GetInheritTypes

The GetInheritTypes method requests information about how ACEs can be inherited by child objects. For more information,
see ACE Inheritance.

ISecurityInformation::GetObjectInformation

The GetObjectInformation method requests information that the access control editor uses to initialize its pages and to
determine the editing options available to the user.

ISecurityInformation::GetSecurity

The GetSecurity method requests a security descriptor for the securable object whose security descriptor is being edited. The
access control editor calls this method to retrieve the object's current or default security descriptor.

ISecurityInformation::MapGeneric

The MapGeneric method requests that the generic access rights in an access mask be mapped to their corresponding
standard and specific access rights.

ISecurityInformation::PropertySheetPageCallback

The PropertySheetPageCallback method notifies an EditSecurity or CreateSecurityPage caller that an access control editor
property page is being created or destroyed.
 ISecurityInformation::SetSecurity

The SetSecurity method provides a security descriptor containing the security information the user wants to apply to the
securable object. The access control editor calls this method when the user clicks Okay or Apply.

Requirements

Minimum suppor ted client Windows XP [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header aclui.h

See also
Access Control Editor
Access Control Editor Functions
CreateSecurityPage
EditSecurity
ISecurityInformation2
 ISecurityInformation::GetAccessRights method
(aclui.h)
7/2/2022 • 2 minutes to read • Edit Online

The GetAccessRights method requests information about the access rights that can be controlled for a
securable object. The access control editor calls this method to retrieve display strings and other information
used to initialize the property pages. For more information, see Access Rights and Access Masks.

Syntax
HRESULT GetAccessRights(
[in] const GUID *pguidObjectType,
[in] DWORD dwFlags,
[out] PSI_ACCESS *ppAccess,
[out] ULONG *pcAccesses,
[out] ULONG *piDefaultAccess
);

Parameters
[in] pguidObjectType

A pointer to a GUID structure that identifies the type of object for which access rights are being requested. If this
parameter is NULL or a pointer to GUID_NULL, return the access rights for the object being edited. Otherwise,
the GUID identifies a child object type returned by the ISecurityInformation::GetInheritTypes method. The GUID
corresponds to the InheritedObjectType member of an object-specific ACE.
[in] dwFlags

A set of bit flags that indicate the property page being initialized. This value is zero if the basic security page is
being initialized. Otherwise, it is a combination of the following values.

VA L UE M EA N IN G

The Advanced Security property sheet is being initialized.

SI_ADVANCED

The Advanced Security property sheet includes the Audit

SI_EDIT_AUDITS property page.

The Advanced Security property sheet enables editing of

SI_EDIT_PROPERTIES ACEs that apply to the properties and property sets of the
object.

[out] ppAccess

A pointer to an array of SI_ACCESS structures. The array must include one entry for each access right. You can
specify access rights that apply to the object itself, as well as object-specific access rights that apply only to a
property set or property on the object.
[out] pcAccesses
A pointer to ULONG that indicates the number of entries in the ppAccess array.
[out] piDefaultAccess

A pointer to ULONG that indicates the zero-based index of the array entry that contains the default access
rights. The access control editor uses this entry as the initial access rights in a new ACE.

Return value
If the function succeeds, the function returns S_OK.
If the function fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.

Remarks
The GetAccessRights method is called each time a property page is initialized.
The access control editor does not free the pointer returned in ppAccess.

Requirements

Minimum suppor ted client Windows XP [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header aclui.h

See also
Access Control Editor
Access Control Editor Functions
CreateSecurityPage
EditSecurity
GUID
ISecurityInformation
ISecurityInformation::GetInheritTypes
SI_ACCESS
 ISecurityInformation::GetInheritTypes method
(aclui.h)
7/2/2022 • 2 minutes to read • Edit Online

The GetInheritTypes method requests information about how ACEs can be inherited by child objects. For more
information, see ACE Inheritance.

Syntax
HRESULT GetInheritTypes(
[out] PSI_INHERIT_TYPE *ppInheritTypes,
[out] ULONG *pcInheritTypes
);

Parameters
[out] ppInheritTypes

A pointer to a variable you should set to a pointer to an array of SI_INHERIT_TYPE structures. The array should
include one entry for each combination of inheritance flags and child object type that you support.
[out] pcInheritTypes

A pointer to a variable that you should set to indicate the number of entries in the ppInheritTypes array.

Return value
Returns S_OK if successful.
Returns a nonzero error code if an error occurs.

Remarks
The access control editor does not free the pointer returned in ppInheritTypes.

Requirements

Minimum suppor ted client Windows XP [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header aclui.h

See also
Access Control Editor
Access Control Editor Functions
CreateSecurityPage
EditSecurity
ISecurityInformation
SI_INHERIT_TYPE
 ISecurityInformation::GetObjectInformation method
(aclui.h)
7/2/2022 • 2 minutes to read • Edit Online

The GetObjectInformation method requests information that the access control editor uses to initialize its
pages and to determine the editing options available to the user.

Syntax
HRESULT GetObjectInformation(
[out] PSI_OBJECT_INFO pObjectInfo
);

Parameters
[out] pObjectInfo

A pointer to an SI_OBJECT_INFO structure. Your implementation must fill this structure to pass information back
to the access control editor.

Return value
Returns S_OK if successful.
Returns a nonzero error code if an error occurs.

Remarks
The system does not free the string pointers that you return in the SI_OBJECT_INFO structure.

Requirements

Minimum suppor ted client Windows XP [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header aclui.h

See also
Access Control Editor
Access Control Editor Functions
ISecurityInformation
SI_OBJECT_INFO
 ISecurityInformation::GetSecurity method (aclui.h)
7/2/2022 • 2 minutes to read • Edit Online

The GetSecurity method requests a security descriptor for the securable object whose security descriptor is
being edited. The access control editor calls this method to retrieve the object's current or default security
descriptor.

Syntax
HRESULT GetSecurity(
[in] SECURITY_INFORMATION RequestedInformation,
[out] PSECURITY_DESCRIPTOR *ppSecurityDescriptor,
[in] BOOL fDefault
);

Parameters
[in] RequestedInformation

A set of SECURITY_INFORMATION bit flags that indicate the parts of the security descriptor being requested.
This parameter can be a combination of the following values.

VA L UE M EA N IN G

The security descriptor must include the SID of the object's

OWNER_SECURITY_INFORMATION owner.

The security descriptor must include the SID of the object's

GROUP_SECURITY_INFORMATION primary group.

The security descriptor must include the object's DACL.

DACL_SECURITY_INFORMATION

The security descriptor must include the object's SACL.

SACL_SECURITY_INFORMATION

[out] ppSecurityDescriptor

A pointer to a variable that your implementation must set to a pointer to the object's security descriptor. The
security descriptor must include the components requested by the RequestedInformation parameter.
The system calls the LocalFree function to free the returned pointer.
[in] fDefault

If this parameter is TRUE , ppSecurityDescriptor should return an application-defined default security descriptor
for the object. The access control editor uses this default security descriptor to reinitialize the property page.
The access control editor sets this parameter to TRUE only if the user clicks the Default button. The Default
button is displayed only if you set the SI_RESET flag in the ISecurityInformation::GetObjectInformation method. If
no default security descriptor is available, do not set the SI_RESET flag.
If this flag is FALSE , ppSecurityDescriptor should return the object's current security descriptor.

Return value
Returns S_OK if successful.
Returns a nonzero error code if an error occurs. Returns E_ACCESSDENIED if the user does not have permission
to read the requested security information.

Requirements

Minimum suppor ted client Windows XP [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header aclui.h

See also
Access Control Editor
Access Control Editor Functions
ISecurityInformation
ISecurityInformation::GetObjectInformation
LocalFree
SECURITY_INFORMATION
 ISecurityInformation::MapGeneric method (aclui.h)
7/2/2022 • 2 minutes to read • Edit Online

The MapGeneric method requests that the generic access rights in an access mask be mapped to their
corresponding standard and specific access rights. For more information about generic, standard, and specific
access rights, see Access Rights and Access Masks.

Syntax
HRESULT MapGeneric(
[in] const GUID *pguidObjectType,
[in] UCHAR *pAceFlags,
[in] ACCESS_MASK *pMask
);

Parameters
[in] pguidObjectType

A pointer to a GUID structure that identifies the type of object to which the access mask applies. If this member
is NULL or a pointer to GUID_NULL, the access mask applies to the object itself.
[in] pAceFlags

A pointer to the AceFlags member of the ACE_HEADER structure from the ACE whose access mask is being
mapped.
[in] pMask

A pointer to an access mask that contains the generic access rights to map. Your implementation must map the
generic access rights to the corresponding standard and specific access rights for the specified object type.

Return value
If the function succeeds, the function returns S_OK.
If the function fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.

Remarks
Your MapGeneric implementation can call the MapGenericMask function to map the generic access rights in
the access mask.

Requirements

Minimum suppor ted client Windows XP [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]
 Target Platform Windows

Header aclui.h

See also
ACE_HEADER
Access Control Editor
Access Control Editor Functions
CreateSecurityPage
EditSecurity
GUID
ISecurityInformation
MapGenericMask
 ISecurityInformation::PropertySheetPageCallback
method (aclui.h)
7/2/2022 • 2 minutes to read • Edit Online

The Proper tySheetPageCallback method notifies an EditSecurity or CreateSecurityPage caller that an access
control editor property page is being created or destroyed.

Syntax
HRESULT PropertySheetPageCallback(
[in] HWND hwnd,
[in] UINT uMsg,
[in] SI_PAGE_TYPE uPage
);

Parameters
[in] hwnd

If uMsg is PSPCB_SI_INITDIALOG, hwnd is a handle to the property page dialog box. Otherwise, hwnd is NULL .
[in] uMsg

Identifies the message being received. This parameter is one of the following values.

VA L UE M EA N IN G

Indicates that a property page is being created.

PSPCB_CREATE

Indicates that a property page is being destroyed.

PSPCB_RELEASE

Indicates that a property page is being initialized.

PSPCB_SI_INITDIALOG

[in] uPage

A value from the SI_PAGE_TYPE enumeration type that indicates the type of access control editor property page
being created or destroyed.

Return value
Returns S_OK if successful.
Returns a nonzero error code if an error occurs.

Requirements
 Minimum suppor ted client Windows XP [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header aclui.h

See also
Access Control Editor
Access Control Editor Functions
CreateSecurityPage
EditSecurity
ISecurityInformation
SI_PAGE_TYPE
 ISecurityInformation::SetSecurity method (aclui.h)
7/2/2022 • 2 minutes to read • Edit Online

The SetSecurity method provides a security descriptor containing the security information the user wants to
apply to the securable object. The access control editor calls this method when the user clicks Okay or Apply .

Syntax
HRESULT SetSecurity(
[in] SECURITY_INFORMATION SecurityInformation,
[in] PSECURITY_DESCRIPTOR pSecurityDescriptor
);

Parameters
[in] SecurityInformation

A set of SECURITY_INFORMATION bit flags that indicate the parts of the security descriptor to set. This
parameter can be a combination of the following values.

VA L UE M EA N IN G

The security descriptor contains the SID of the object's

OWNER_SECURITY_INFORMATION owner.

The security descriptor contains the SID of the object's

GROUP_SECURITY_INFORMATION primary group.

The security descriptor contains the object's DACL.

DACL_SECURITY_INFORMATION

The security descriptor contains the object's SACL.

SACL_SECURITY_INFORMATION

[in] pSecurityDescriptor

A pointer to a security descriptor containing the new security information. Do not assume the security descriptor
is in self-relative form; it can be either absolute or self-relative.

Return value
Returns S_OK if successful.
Returns a nonzero error code if an error occurs.

Remarks
To build a complete security descriptor for the object, the application must merge the new security descriptor
parts, as defined by the SecurityInformation parameter, into the object's existing security descriptor.
Requirements

Minimum suppor ted client Windows XP [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header aclui.h

See also
Access Control Editor
Access Control Editor Functions
ISecurityInformation
SECURITY_INFORMATION
 ISecurityInformation2 interface (aclui.h)
7/2/2022 • 2 minutes to read • Edit Online

The ISecurityInformation2 interface enables the access control editor to obtain information from the client
that is not provided by the ISecurityInformation interface. The client does not need to implement
ISecurityInformation2 unless the default behavior of the access control editor is unsuitable for the client.

Inheritance
The ISecurityInformation2 interface inherits from the IUnknown interface. ISecurityInformation2 also has
these types of members:

Methods
The ISecurityInformation2 interface has these methods.

ISecurityInformation2::IsDaclCanonical

The IsDaclCanonical method determines whether the ACEs contained in the specified DACL structure are ordered according to
the definition of DACL ordering implemented by the client.

ISecurityInformation2::LookupSids

The LookupSids method returns the common names corresponding to each of the elements in the specified list of SIDs.

Requirements

Minimum suppor ted client Windows XP [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header aclui.h

See also
Access Control Editor
Access Control Editor Functions
 ISecurityInformation2::IsDaclCanonical method
(aclui.h)
7/2/2022 • 2 minutes to read • Edit Online

The IsDaclCanonical method determines whether the ACEs contained in the specified DACL structure are
ordered according to the definition of DACL ordering implemented by the client.

Syntax
BOOL IsDaclCanonical(
[in] PACL pDacl
);

Parameters
[in] pDacl

A pointer to a discretionary ACL structure initialized by InitializeAcl.

Return value
Returns TRUE if the ACEs contained in the specified DACL structure are ordered according to the definition of
DACL ordering implemented by the client.
Returns FALSE if the ACEs are not ordered correctly.

Remarks
If the return value of this method is FALSE , the access control editor displays a message box stating that the
DACL is incorrectly ordered. If this method is not provided and the editor requires this information, the editor
will check the canonical ordering defined in Order of ACEs in a DACL.

Requirements

Minimum suppor ted client Windows XP [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header aclui.h

See also
ACL
Access Control Editor
Access Control Editor Functions
ISecurityInformation2
InitializeAcl
 ISecurityInformation2::LookupSids method (aclui.h)
7/2/2022 • 2 minutes to read • Edit Online

The LookupSids method returns the common names corresponding to each of the elements in the specified
list of SIDs.

Syntax
HRESULT LookupSids(
[in] ULONG cSids,
[in] PSID *rgpSids,
[out] LPDATAOBJECT *ppdo
);

Parameters
[in] cSids

The number of pointers to SID structures pointed to by rgpSids.

[in] rgpSids

A pointer to an array of pointers to SID structures.

[out] ppdo

A pointer to a pointer to a returned data transfer object that contains the common names of the SIDs. Optionally,
this parameter also returns the user principal name (UPN) of the SIDs in the rgpSids parameter. The data
transfer object is a SID_INFO structure.

Return value
Returns S_OK if successful.
Returns a nonzero error code if an error occurs.

Remarks
Your implementation of LookupSids can return E_NOTIMPL if the access control editor is to determine the
common names corresponding to the specified SIDs. However, if the access control editor receives any return
code other than S_OK, the editor determines this information.
The client must return the common names through the data object using the following format.
 #include <windows.h>

// HGLOBAL containing SID_INFO_LIST returned by

// ISecurityInformation2::LookupSids
#define CFSTR_ACLUI_SID_INFO_LIST TEXT("CFSTR_ACLUI_SID_INFO_LIST")

// Data structures corresponding to CFSTR_ACLUI_SID_INFO_LIST

typedef struct _SID_INFO
{
PSID pSid;
PWSTR pwzCommonName;
PWSTR pwzClass; // Used for selecting icon, for example,
// "User" or "Group"
PWSTR pwzUPN; // Optional pointer to a user principal
// name
} SID_INFO, *PSID_INFO;

typedef struct _SID_INFO_LIST

{
ULONG cItems;
SID_INFO aSidInfo[ANYSIZE_ARRAY];
} SID_INFO_LIST, *PSID_INFO_LIST;

Requirements

Minimum suppor ted client Windows XP [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header aclui.h

See also
Access Control Editor
Access Control Editor Functions
ISecurityInformation2
SID
SID_INFO
SID_INFO_LIST
 ISecurityInformation3 interface (aclui.h)
7/2/2022 • 2 minutes to read • Edit Online

The ISecurityInformation3 interface provides methods necessary for displaying an elevated access control
editor when a user clicks the Edit button on an access control editor page that displays an image of a shield on
that Edit button. The image of a shield is displayed on the Edit button when the access control editor is
launched by a process with a token that lacks permission to save changes to the object being edited.

Inheritance
The ISecurityInformation3 interface inherits from the IUnknown interface. ISecurityInformation3 also has
these types of members:

Methods
The ISecurityInformation3 interface has these methods.

ISecurityInformation3::GetFullResourceName

Retrieves the full path and file name of the object associated with the access control editor that is displayed by calling the
OpenElevatedEditor method.

ISecurityInformation3::OpenElevatedEditor

Opens an access control editor when a user clicks the Edit button on an access control editor page that displays an image of a
shield on that Edit button.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header aclui.h

See also
Access Control Editor
ISecurityInformation
ISecurityInformation2
 ISecurityInformation3::GetFullResourceName
method (aclui.h)
7/2/2022 • 2 minutes to read • Edit Online

The GetFullResourceName method retrieves the full path and file name of the object associated with the
access control editor that is displayed by calling the OpenElevatedEditor method.

Syntax
HRESULT GetFullResourceName(
[out] LPWSTR *ppszResourceName
);

Parameters
[out] ppszResourceName

The full path and file name of the object for which permissions are to be edited.

Return value
If the method succeeds, it returns S_OK .
If the method fails, it returns an error code. For a list of common error codes, see Common HRESULT Values.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header aclui.h

See also
ISecurityInformation3
OpenElevatedEditor
 ISecurityInformation3::OpenElevatedEditor method
(aclui.h)
7/2/2022 • 2 minutes to read • Edit Online

The OpenElevatedEditor method opens an access control editor when a user clicks the Edit button on an
access control editor page that displays an image of a shield on that Edit button. The image of a shield is
displayed when the access control editor is launched by a process with a token that lacks permission to save
changes to the object being edited.

Syntax
HRESULT OpenElevatedEditor(
[in] HWND hWnd,
[in] SI_PAGE_TYPE uPage
);

Parameters
[in] hWnd

The parent window of the access control editor.

[in] uPage

A value of the SI_PAGE_TYPE enumeration that indicates the page type on which to display the elevated access
control editor.

Return value
If the method succeeds, it returns S_OK .
If the method fails, it returns an error code. For a list of common error codes, see Common HRESULT Values.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header aclui.h

See also
GetFullResourceName
ISecurityInformation3
 ISecurityInformation4 interface (aclui.h)
7/2/2022 • 2 minutes to read • Edit Online

The ISecurityInformation4 interface enables the resource manager to provide additional information when
computing effective permissions using the IEffectivePermission2 interface.

Inheritance
The ISecurityInformation4 interface inherits from the IUnknown interface. ISecurityInformation4 also has
these types of members:

Methods
The ISecurityInformation4 interface has these methods.

ISecurityInformation4::GetSecondarySecurity

Returns additional security contexts that may impact access to the resource.

Requirements

Minimum suppor ted client Windows 8 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2012 [desktop apps only]

Target Platform Windows

Header aclui.h
 ISecurityInformation4::GetSecondarySecurity
method (aclui.h)
7/2/2022 • 2 minutes to read • Edit Online

The GetSecondar ySecurity method returns additional security contexts that may impact access to the
resource.

Syntax
HRESULT GetSecondarySecurity(
[out] PSECURITY_OBJECT *pSecurityObjects,
[out] PULONG pSecurityObjectCount
);

Parameters
[out] pSecurityObjects

An array of SECURITY_OBJECT structures that contain the secondary security objects associated with the
resources that are set on success. The array is owned by the caller and is freed by using the LocalFree function.
The pwszName member is also freed by using LocalFree . If the cbData or cbData2 members of the
SECURITY_OBJECT structure are not zero, then the caller must free the corresponding pData or pData2 by
using LocalFree . If either of those members are zero, then the corresponding pData and pData2 members are
owned by the resource manager and must remain valid until the EditSecurity function returns
[out] pSecurityObjectCount

The number of security objects in the pSecurityObjects parameter that are set on success.

Return value
If the method succeeds, it returns S_OK .
If the method fails, it returns an error code. For a list of common error codes, see Common HRESULT Values.

Remarks
A resource manager does not need to return secondary objects with the fWellKnown member set to TRUE and
the Id member set to SECURITY_OBJECT_ID_OBJECT_SD, SECURITY_OBJECT_ID_CENTRAL_POLICY, or
SECURITY_OBJECT_ID_CENTRAL_ACCESS_RULE. Security objects with these IDs will be provided by the access
control editor when calling ComputeEffectivePermissionWithSecondarySecurity.
Interpretation of the returned security objects is tied to the implementation of
ComputeEffectivePermissionWithSecondarySecurity.

Requirements
 Minimum suppor ted client Windows 8 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2012 [desktop apps only]

Target Platform Windows

Header aclui.h

See also
ISecurityInformation4
 ISecurityObjectTypeInfo interface (aclui.h)
7/2/2022 • 2 minutes to read • Edit Online

The ISecurityObjectTypeInfo interface provides a means of determining the source of inherited access control
entries (ACEs) in discretionary access control lists (DACLs) and system access control lists (SACLs). The access
control editor uses this information to communicate the inheritance source to the client.

Inheritance
The ISecurityObjectTypeInfo interface inherits from the IUnknown interface. ISecurityObjectTypeInfo also
has these types of members:

Methods
The ISecurityObjectTypeInfo interface has these methods.

ISecurityObjectTypeInfo::GetInheritSource

The ISecurityObjectTypeInfo::GetInheritSource method provides a means of determining the source of inherited access control
entries in discretionary access control lists and system access control lists.

Requirements

Minimum suppor ted client Windows XP [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header aclui.h

See also
IEffectivePermission
ISecurityInformation2
 ISecurityObjectTypeInfo::GetInheritSource method
(aclui.h)
7/2/2022 • 2 minutes to read • Edit Online

The GetInheritSource method provides a means of determining the source of inherited access control entries
(ACEs) in discretionary access control lists (DACLs) and system access control lists (SACLs).

Syntax
HRESULT GetInheritSource(
[in] SECURITY_INFORMATION si,
[in] PACL pACL,
[out] PINHERITED_FROM *ppInheritArray
);

Parameters
[in] si

A SECURITY_INFORMATION structure that represents the security information of the object.

[in] pACL

A pointer to an ACL structure that represents the access control list (ACL) of the object.
[out] ppInheritArray

A pointer to a pointer to an INHERITED_FROM structure that receives an array of INHERITED_FROM structures.

The length of this array is the same as the number of ACEs in the ACL referenced by pACL. Each
INHERITED_FROM entry in ppInheritArray provides inheritance information for the corresponding ACE entry
in pACL.

Return value
If the function is successful, the return value is S_OK.
If the function fails, the return value is an HRESULT that indicates the error. For a list of common error codes,
see Common HRESULT Values.

Requirements

Minimum suppor ted client Windows XP [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header aclui.h
 SECURITY_OBJECT structure (aclui.h)
7/2/2022 • 3 minutes to read • Edit Online

The SECURITY_OBJECT structure contains the security object information.

Syntax
typedef struct _SECURITY_OBJECT {
PWSTR pwszName;
PVOID pData;
DWORD cbData;
PVOID pData2;
DWORD cbData2;
DWORD Id;
BOOLEAN fWellKnown;
} SECURITY_OBJECT, *PSECURITY_OBJECT;

Members
pwszName

A pointer to the name.

pData

A pointer to the security data.

cbData

The size, in bytes, of the data pointed to by the pData member. This may be zero if pData contains the data,
such as when the data is an IUnknown interface pointer, a handle, or data specific to the resource manager that
can be stored in pData directly without a memory allocation.
pData2

A pointer to the additional security data.

cbData2

The size, in bytes, of the data pointed to by the pData2 member. This may be zero if pData2 contains the data,
such as when the data is an IUnknown interface pointer, a handle, or data specific to the resource manager that
can be stored in pData2 directly without a memory allocation.
Id

The identifier for the security object's type. If the fWellKnown member is FALSE , then the Id member has no
special significance other than to help resource managers distinguish it from other classes of security objects. If
the fWellKnown member is TRUE , then the Id member is one of the following and the entire structure follows
the corresponding representation.

VA L UE M EA N IN G
 The security descriptor of the resource.
SECURITY_OBJECT_ID_OBJECT_SD (1)
If Id is set to this value, then pData points to a security
descriptor and cbData is the number of bytes in pData .
pData2 is NULL and cbData2 is 0.

The security descriptor of a network share.

SECURITY_OBJECT_ID_SHARE (2)
If Id is set to this value, then pData points to the
ISecurityInformation interface of an object that
represents the security context of the share.
If the security descriptor is not yet available, then
pData2 must be a handle to a waitable object that is
signaled when the security descriptor is ready when the
GetSecondarySecurity method returns S_FALSE. The
waitable object should be created by the CreateEvent
function. In this case, cbData2 is 0.
This identifier is only applicable to file system objects.

The security descriptor of a central access policy.

SECURITY_OBJECT_ID_CENTRAL_POLICY (3)
If Id is set to this value, then pData points to the
security descriptor with an empty DACL, an owner,
group, and attribute access control entries (ACEs) that
match the resource's owner, group, and attributes as well
as a SCOPE_SECURITY_INFORMATION_ACE that
contains the central policy's ID. cbData is set to the
number of bytes in pData .
pData2 is NULL and cbData2 is 0.
The security descriptor is constructed to allow
computing effective permissions to correctly determine
when access is limited by the central policy and higher
detail of the central access rule cannot be determined.
This is used when a central access policy that applies to a
resource cannot be resolved into its elemental central
access rules.

The security descriptor of a central access rule.

SECURITY_OBJECT_ID_CENTRAL_ACCESS_RULE (4)
If Id is set to this value, then pData points to the
security descriptor with an owner, group, and attribute
ACEs that match the resource's owner, group, and
attributes, and a discretionary access control list (DACL)
that matches the central access rule's DACL. cbData is
set to the number of bytes in pData .
In addition, pData2 points to a security descriptor with
a DACL that contains a conditional ACE that grants 0x1
to Everyone if the resource condition from the central
access rule evaluates to TRUE . cbData2 is set to the
number of bytes in pData2 .
The security descriptor is constructed to allow
computing effective permissions to determine when
access is limited by the central access policy at the
highest detail. That is, access is limited by pointing to a
central policy rule.

fWellKnown
TRUE if the security object represents one of the well-know security objects listed in the Id member.

Remarks
When the Id member the SECURITY_OBJECT structure is set to
SECURITY_OBJECT_ID_CENTRAL_ACCESS_RULE, the ComputeEffectivePermissionWithSecondarySecurity
method must use the pData2 member of first and only then evaluate the access using the pData member.

Requirements

Minimum suppor ted client Windows 8 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2012 [desktop apps only]

Header aclui.h

See also
IEffectivePermission2::ComputeEffectivePermissionWithSecondarySecurity
ISecurityInformation4::GetSecondarySecurity
 SI_ACCESS structure (aclui.h)
7/2/2022 • 2 minutes to read • Edit Online

The SI_ACCESS structure contains information about an access right or default access mask for a securable
object. The ISecurityInformation::GetAccessRights method uses this structure to specify information that the
access control editor uses to initialize its property pages.

Syntax
typedef struct _SI_ACCESS {
const GUID *pguid;
ACCESS_MASK mask;
LPCWSTR pszName;
DWORD dwFlags;
} SI_ACCESS, *PSI_ACCESS;

Members
pguid

A pointer to a GUID structure that identifies the type of object to which the access right or default access mask
applies. The GUID can identify a property set or property on the object, or a type of child object that can be
contained by the object.
If this member points to GUID_NULL, the access right applies to the object itself.
mask

A bitmask that specifies the access right described by this structure. The mask can contain any combination of
standard and specific rights, but should not contain generic rights such as GENERIC_ALL.
pszName

A pointer to a null-terminated Unicode string containing a display string that describes the access right.
Alternatively, pszName can be a string resource identifier returned by the MAKEINTRESOURCE macro. Use the
ISecurityInformation::GetObjectInformation method to identify the module that contains the string resource.
dwFlags

A set of bit flags that indicate where the access right is displayed. This member can be a combination of the
following.

VA L UE M EA N IN G

The access right is displayed on the advanced security pages.

SI_ACCESS_SPECIFIC

The access right is displayed on the basic security page.

SI_ACCESS_GENERAL
 Indicates an access right that applies only to containers. If
SI_ACCESS_CONTAINER this flag is set, the access right is displayed on the basic
security page only if the
ISecurityInformation::GetObjectInformation method specifies
the SI_CONTAINER flag.

Indicates a property-specific access right. Used with

SI_ACCESS_PROPERTY SI_EDIT_PROPERTIES.

This member can also specify a combination of the following flags to indicate whether other containers or
objects can inherit the access right.

VA L UE M EA N IN G

Other containers that are contained by the primary object

CONTAINER_INHERIT_ACE inherit the entry.

The ACE does not apply to the primary object to which the
INHERIT_ONLY_ACE ACL is attached, but objects contained by the primary object
inherit the entry.

Noncontainer objects contained by the primary object

OBJECT_INHERIT_ACE inherit the entry.

Requirements

Minimum suppor ted client Windows XP [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Header aclui.h

See also
GUID
ISecurityInformation::GetAccessRights
ISecurityInformation::GetObjectInformation
 SI_INHERIT_TYPE structure (aclui.h)
7/2/2022 • 2 minutes to read • Edit Online

The SI_INHERIT_TYPE structure contains information about how access control entries (ACEs) can be inherited
by child objects. The ISecurityInformation::GetInheritTypes method uses this structure to specify display strings
that the access control editor uses to initialize its property pages.

Syntax
typedef struct _SI_INHERIT_TYPE {
const GUID *pguid;
ULONG dwFlags;
LPCWSTR pszName;
} SI_INHERIT_TYPE, *PSI_INHERIT_TYPE;

Members
pguid

A pointer to a GUID structure that identifies the type of child object. This member can be a pointer to
GUID_NULL. The GUID corresponds to the InheritedObjectType member of an object-specific ACE.
dwFlags

A set of inheritance flags that indicate the types of ACEs that can be inherited by the pguid object type. These
flags correspond to the AceFlags member of an ACE_HEADER structure. This member can be a combination of
the following values.

VA L UE M EA N IN G

The specified object type can inherit ACEs that have the
CONTAINER_INHERIT_ACE CONTAINER_INHERIT_ACE flag set.

The specified object type can inherit ACEs that have the
INHERIT_ONLY_ACE INHERIT_ONLY_ACE flag set.

The specified object type can inherit ACEs that have the
OBJECT_INHERIT_ACE OBJECT_INHERIT_ACE flag set.

pszName

A pointer to a null-terminated Unicode string containing a display string that describes the child object.
Alternatively, pszName can be a string resource identifier returned by the MAKEINTRESOURCE macro. Use the
ISecurityInformation::GetObjectInformation method to identify the module that contains the string resource.

Requirements
 Minimum suppor ted client Windows XP [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Header aclui.h

See also
ACE_HEADER
GUID
ISecurityInformation::GetInheritTypes
ISecurityInformation::GetObjectInformation
 SI_OBJECT_INFO structure (aclui.h)
7/2/2022 • 8 minutes to read • Edit Online

The SI_OBJECT_INFO structure is used by the ISecurityInformation::GetObjectInformation method to specify

information used to initialize the access control editor.

Syntax
typedef struct _SI_OBJECT_INFO {
DWORD dwFlags;
HINSTANCE hInstance;
LPWSTR pszServerName;
LPWSTR pszObjectName;
LPWSTR pszPageTitle;
GUID guidObjectType;
} SI_OBJECT_INFO, *PSI_OBJECT_INFO;

Members
dwFlags

A set of bit flags that determine the editing options available to the user. This member can be a combination of
the following values.

VA L UE M EA N IN G

If this flag is set, the Advanced button is displayed on the

SI_ADVANCED basic security property page. If the user clicks this button,
0x00000010L the system displays an advanced security property sheet
that enables advanced editing of the discretionary access
control list (DACL) of the object.
Combine this flag with the SI_EDIT_AUDITS,
SI_EDIT_OWNER, and SI_EDIT_PROPERTIES flags to
enable editing of the object's SACL, owner, and object-
specific access control entries (ACEs).

If this flag is set, a shield is displayed on the Edit button of

SI_AUDITS_ELEVATION_REQUIRED the advanced Auditing pages. For NTFS objects, this flag is
0x02000000L requested when the user does not have READ_CONTROL
or ACCESS_SYSTEM_SECURITY access.
Windows Ser ver 2003 and Windows XP: This flag
is not supported.

Indicates that the object is a container. If this flag is set, the

SI_CONTAINER access control editor enables the controls relevant to the
0x00000004L inheritance of permissions onto child objects.
 If this flag is set, the system disables denying an ACE. Clients
SI_DISABLE_DENY_ACE of the access control editor must implement the
0x80000000L ISecurityInformation4 interface to set this flag.
Windows Ser ver 2008 R2, Windows 7, Windows
Ser ver 2008, Windows Vista, Windows
Ser ver 2003 and Windows XP: This flag is not
supported.

Combines the SI_EDIT_PERMS, SI_EDIT_OWNER, and

SI_EDIT_ALL SI_EDIT_AUDITS flags.

If this flag is set and the user clicks the Advanced button,
SI_EDIT_AUDITS the system displays an advanced security property sheet
0x00000002L that includes an Auditing property page for editing the
object's SACL. To display the Advanced button, set the
SI_ADVANCED flag.

If this flag is set, the Effective Permissions page is

SI_EDIT_EFFECTIVE displayed. This flag is ignored if the ISecurityInformation
0x00020000L object that initialized the access control editor does not
implement the IEffectivePermission interface.

If this flag is set and the user clicks the Advanced button,
SI_EDIT_OWNER the system displays an advanced security property sheet
0x00000001L that includes an Owner property page for changing the
object's owner. To display the Advanced button, set the
SI_ADVANCED flag.

This is the default value. The basic security property page

SI_EDIT_PERMS always displays the controls for basic editing of the object's
0x00000000L DACL. To disable these controls, set the SI_READONLY flag.

If this flag is set, the system enables controls for editing

SI_EDIT_PROPERTIES ACEs that apply to the object's property sets and properties.
0x00000080L These controls are available only on the property sheet
displayed when the user clicks the Advanced button.

If this flag is set, the system enables editing attributes.

SI_ENABLE_CENTRAL_POLICY Clients of the access control editor must implement the
0x40000000L ISecurityInformation4 interface to set this flag.
Windows Ser ver 2008 R2, Windows 7, Windows
Ser ver 2008, Windows Vista, Windows
Ser ver 2003 and Windows XP: This flag is not
supported.

If this flag is set, the system enables editing attributes.

SI_ENABLE_EDIT_ATTRIBUTE_CONDITION
0x20000000L
Clients of the access control editor must implement the
ISecurityInformation4 interface to set this flag.
Windows Ser ver 2008 R2, Windows 7, Windows
Ser ver 2008, Windows Vista, Windows
Ser ver 2003 and Windows XP: This flag is not
supported.
 Indicates that the access control editor cannot read the
SI_MAY_WRITE DACL but might be able to write to the DACL. If a call to the
0x10000000L ISecurityInformation::GetSecurity method returns
AccessDenied , the user can try to add a new ACE, and a
more appropriate warning is displayed.

If this flag is set, the access control editor hides the check
SI_NO_ACL_PROTECT box that allows inheritable ACEs to propagate from the
0x00000200L parent object to this object. If this flag is not set, the check
box is visible.
The check box is clear if the SE_DACL_PROTECTED flag is
set in the object's security descriptor. In this case, the
object's DACL is protected from being modified by
inheritable ACEs.
If the user clears the check box, any inherited ACEs in
the security descriptor are deleted or converted to
noninherited ACEs. Before proceeding with this
conversion, the system displays a warning message box
to confirm the change.

If this flag is set, the access control editor hides the Special
SI_NO_ADDITIONAL_PERMISSION Permissions tab on the Advanced Security Settings
0x00200000L page.

If this flag is set, the access control editor hides the check
SI_NO_TREE_APPLY box that controls the NO_PROPAGATE_INHERIT_ACE flag.
0x00000400L This flag is relevant only when the SI_ADVANCED flag is also
set.

When set, indicates that the guidObjectType member of

SI_OBJECT_GUID the SI_OBJECT_INFO structure is valid. This is set in
0x00010000L comparisons with object-specific ACEs in determining
whether the ACE applies to the current object.

If this flag is set, a shield is displayed on the Edit button of

SI_OWNER_ELEVATION_REQUIRED
0x04000000L
the advanced Owner page. For NTFS objects, this flag is
requested when the user does not have WRITE_OWNER
access. This flag is valid only if the owner page is requested.
Windows Ser ver 2003 and Windows XP: This flag
is not supported.

If this flag is set, the user cannot change the owner of the
SI_OWNER_READONLY object. Set this flag if SI_EDIT_OWNER is set but the user
0x00000040L does not have permission to change the owner.

Combine this flag with SI_CONTAINER to display a check box

SI_OWNER_RECURSE on the owner page that indicates whether the user intends
0x00000100L the new owner to be applied to all child objects as well as
the current object. The access control editor does not
perform the recursion; the recursion should be performed by
the application in ISecurityInformation::SetSecurity.

If this flag is set, the pszPageTitle member is used as the

SI_PAGE_TITLE title of the basic security property page. Otherwise, a default
0x00000800L title is used.

SI_PERMS_ELEVATION_REQUIRED
0x01000000L
If this flag is set, an image of a shield is displayed on the
Edit button of the simple and advanced Permissions
pages. For NTFS objects, this flag is requested when the user
does not have READ_CONTROL or WRITE_DAC access.
Windows Ser ver 2003 and Windows XP: This flag
is not supported.

If this flag is set, the editor displays the object's security

SI_READONLY information, but the controls for editing the information are
0x00000008L disabled.
This flag cannot be combined with the SI_VIEW_ONLY
flag.

If this flag is set, the Default button is displayed. If the user

SI_RESET clicks this button, the access control editor calls the
0x00000020L ISecurityInformation::GetSecurity method to retrieve an
application-defined default security descriptor. The access
control editor uses this security descriptor to reinitialize the
property sheet, and the user is allowed to apply the change
or cancel.

When set, this flag displays the Reset Defaults button on

SI_RESET_DACL the Permissions page.
0x00040000L

When set, this flag displays the Reset permissions on all child
SI_RESET_DACL_TREE objects and enable propagation of inheritable permissions
0x00004000L check box in the Permissions page of the Access Control
Settings window. If this check box is selected when the user
clicks the Apply button, a bitwise-OR operation is
performed on the SecurityInformation parameter of
ISecurityInformation::SetSecurity with SI_RESET_DACL_TREE.
This function does not reset the permissions and enable
propagation of inheritable permissions; the implementation
of ISecurityInformation must do this.

When set, this flag displays the Reset Defaults button on

SI_RESET_OWNER the Owner page.
0x00100000L

When set, this flag displays the Reset Defaults button on

SI_RESET_SACL the Auditing page.
0x00080000L

When set, this flag displays the Reset auditing entries on all
SI_RESET_SACL_TREE child objects and enables propagation of the inheritable
0x00008000L auditing entries check box in the Auditing page of the Access
Control Settings window. If this check box is selected when
the user clicks the Apply button, a bitwise-OR operation is
performed on the SecurityInformation parameter of
ISecurityInformation::SetSecurity with SI_RESET_SACL_TREE.
This function does not reset the permissions and enable
propagation of inheritable permissions; the implementation
of ISecurityInformation must do this.
 If this flag is set, an image of a shield is displayed on the
SI_SCOPE_ELEVATION_REQUIRED Change button of the Scope attribute. For NTFS objects,
0x08000000L this flag is requested when the user does not have
READ_CONTROL or WRITE_DAC access. Clients of the access
control editor must implement the ISecurityInformation4
interface to set this flag.
Windows Ser ver 2008 R2, Windows 7, Windows
Ser ver 2008, Windows Vista, Windows
Ser ver 2003 and Windows XP: This flag is not
supported.

Set this flag if the pszSer verName computer is known to

SI_SERVER_IS_DC be a domain controller. If this flag is set, the domain name is
0x00001000L included in the scope list of the Add Users and Groups
dialog box. Otherwise, the pszSer verName computer is
used to determine the scope list of the dialog box.

This flag is set by the access control editor client to display

SI_VIEW_ONLY read-only versions of the access control editor dialog boxes.
0x00400000L These versions of the dialog boxes do not allow editing of
the associated object's permissions. Clients of the access
control editor must implement the ISecurityInformation3
interface to set this flag.
This flag cannot be combined with the SI_READONLY
flag.
Windows Ser ver 2003 and Windows XP: This flag
is not supported.

hInstance

Identifies a module that contains string resources to be used in the property sheet. The
ISecurityInformation::GetAccessRights and ISecurityInformation::GetInheritTypes methods can specify string
resource identifiers for display names.
pszServerName

A pointer to a null -terminated, Unicode string that names the computer on which to look up account names and
SIDs. This value can be NULL to specify the local computer. The access control editor does not free this pointer.
pszObjectName

A pointer to a null -terminated, Unicode string that names the object being edited. This name appears in the title
of the advanced security property sheet and any error message boxes displayed by the access control editor. The
access control editor does not free this pointer.
pszPageTitle

A pointer to a null -terminated, Unicode string used as the title of the basic security property page. This member
is ignored unless the SI_PAGE_TITLE flag is set in dwFlags . If the page title is not provided, a default title is used.
The access control editor does not free this pointer.
guidObjectType

A GUID for the object. This member is ignored unless the SI_OBJECT_GUID flag is set in dwFlags .

Requirements
 Minimum suppor ted client Windows XP [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Header aclui.h

See also
ISecurityInformation
ISecurityInformation::GetAccessRights
ISecurityInformation::GetInheritTypes
ISecurityInformation::GetObjectInformation
ISecurityInformation::GetSecurity
ISecurityInformation::SetSecurity
 SI_PAGE_TYPE enumeration (aclui.h)
7/2/2022 • 2 minutes to read • Edit Online

The SI_PAGE_TYPE enumeration contains values that indicate the types of property pages in an access control
editor property sheet.

Syntax
typedef enum _SI_PAGE_TYPE {
SI_PAGE_PERM,
SI_PAGE_ADVPERM,
SI_PAGE_AUDIT,
SI_PAGE_OWNER,
SI_PAGE_EFFECTIVE,
SI_PAGE_TAKEOWNERSHIP,
SI_PAGE_SHARE
} SI_PAGE_TYPE;

Constants

SI_PAGE_PERM
The
basic security property page for editing the object's DACL.

SI_PAGE_ADVPERM
The
Permissions tab for advanced editing of the object's DACL, such as editing object-specific ACEs.

SI_PAGE_AUDIT
The
Auditing tab for editing the object's SACL.

SI_PAGE_OWNER
The
Owner tab for editing the object's owner.

SI_PAGE_EFFECTIVE
The Effective Permission tab that displays the effective permissions granted to a specified user or group for access to the
object.

SI_PAGE_TAKEOWNERSHIP
A dialog box for changing the owner of the object.

SI_PAGE_SHARE

Requirements
 Minimum suppor ted client Windows XP [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Header aclui.h

See also
Access Control Editor
Authorization Enumerations
ISecurityInformation::PropertySheetPageCallback
 SID_INFO structure (aclui.h)
7/2/2022 • 2 minutes to read • Edit Online

The SID_INFO structure contains the list of common names corresponding to the SID structures returned by
ISecurityInformation2::LookupSids. It is a member of the SID_INFO_LIST structure.

Syntax
typedef struct _SID_INFO {
PSID pSid;
PWSTR pwzCommonName;
PWSTR pwzClass;
PWSTR pwzUPN;
} SID_INFO, *PSID_INFO;

Members
pSid

A pointer to a SID structure that identifies one of the SIDs passed into ISecurityInformation2::LookupSids.
pwzCommonName

A pointer to a string containing the common name corresponding to the SID structure specified in pSid .
pwzClass

A pointer to a string describing the SID structure as either a user or a group. The possible values of this string
are as follows:
"Computer"
"Group"
"User"
pwzUPN

A pointer to the user principal name (UPN) corresponding to the SID structure specified in pSid . If a UPN has
not been designated for the SID structure, the value of this parameter is NULL .

Requirements

Minimum suppor ted client Windows XP [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Header aclui.h

See also
ISecurityInformation2::LookupSids
SID
 SID_INFO_LIST structure (aclui.h)
7/2/2022 • 2 minutes to read • Edit Online

The SID_INFO_LIST structure contains a list of SID_INFO structures.

Syntax
typedef struct _SID_INFO_LIST {
ULONG cItems;
SID_INFO aSidInfo[ANYSIZE_ARRAY];
} SID_INFO_LIST, *PSID_INFO_LIST;

Members
cItems

The number of SID_INFO structures contained in the aSidInfo member.

aSidInfo

A pointer to a list of SID_INFO structures that is returned by the ISecurityInformation2::LookupSids method.

Requirements

Minimum suppor ted client Windows XP [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Header aclui.h

See also
ISecurityInformation2::LookupSids
SID_INFO
 adtgen.h header
7/2/2022 • 2 minutes to read • Edit Online

This header is used by Security and Identity. For more information, see:
Security and Identity
adtgen.h contains the following programming interfaces:

Enumerations

AUDIT_PARAM_TYPE

Defines the type of audit parameters that are available.

 AUDIT_PARAM_TYPE enumeration (adtgen.h)
7/2/2022 • 2 minutes to read • Edit Online

The AUDIT_PARAM_TYPE enumeration defines the type of audit parameters that are available.

Syntax
typedef enum _AUDIT_PARAM_TYPE {
APT_None,
APT_String,
APT_Ulong,
APT_Pointer,
APT_Sid,
APT_LogonId,
APT_ObjectTypeList,
APT_Luid,
APT_Guid,
APT_Time,
APT_Int64,
APT_IpAddress,
APT_LogonIdWithSid
} AUDIT_PARAM_TYPE;

Constants

APT_None
No audit options.

APT_String
A string that terminates with NULL .

APT_Ulong
An unsigned long.

APT_Pointer
A pointer that is used to specify handles and pointers. These are 32-bit on 32-bit systems and 64-bit on 64-bit systems. Use
this option when you are interested in the absolute value of the pointer. The memory to which the pointer points is not
marshaled when using this type.

APT_Sid
The security identifier (SID).
 APT_LogonId
The logon identifier (LUID) that results in three output parameters:

Account name

Authority name

LogonID""

APT_ObjectTypeList
Object type list.

APT_Luid
LUID that is not translated to LogonId.

APT_Guid
GUID.

APT_Time
Time as FILETIME.

APT_Int64
ULONGLONG.

APT_IpAddress
IP Address (IPv4 and IPv6). This logs the address as the first parameter and the port as the second parameter. You must
ensure that two entries are added in the event message file. You should ensure that the buffer size is 128 bytes.

APT_LogonIdWithSid
Logon ID with SID that results in four output parameters:

SID

Account name

Authority name

LogonID

Requirements

Minimum suppor ted client Windows XP [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Header adtgen.h
 authz.h header
7/2/2022 • 3 minutes to read • Edit Online

This header is used by Security and Identity. For more information, see:
Security and Identity
authz.h contains the following programming interfaces:

Functions

AuthzAccessCheck

Determines which access bits can be granted to a client for a given set of security descriptors.

AuthzAddSidsToContext

Creates a copy of an existing context and appends a given set of security identifiers (SIDs) and restricted SIDs.

AuthzCachedAccessCheck

Performs a fast access check based on a cached handle containing the static granted bits from a previous AuthzAccessCheck
call.

AuthzEnumerateSecurityEventSources

Retrieves the registered security event sources that are not installed by default.

AuthzFreeAuditEvent

Frees the structure allocated by the AuthzInitializeObjectAccessAuditEvent function.

AuthzFreeCentralAccessPolicyCache

Decreases the CAP cache reference count by one so that the CAP cache can be deallocated.

AuthzFreeContext

Frees all structures and memory associated with the client context. The list of handles for a client is freed in this call.

AuthzFreeHandle

Finds and deletes a handle from the handle list.

AuthzFreeResourceManager

Frees a resource manager object.

AuthzGetInformationFromContext

Returns information about an Authz context.

AuthzInitializeCompoundContext

Creates a user-mode context from the given user and device security contexts.

AuthzInitializeContextFromAuthzContext

Creates a new client context based on an existing client context.

AuthzInitializeContextFromSid

Creates a user-mode client context from a user security identifier (SID).

AuthzInitializeContextFromToken

Initializes a client authorization context from a kernel token. The kernel token must have been opened for TOKEN_QUERY.

AuthzInitializeObjectAccessAuditEvent

Initializes auditing for an object.

AuthzInitializeObjectAccessAuditEvent2

Allocates and initializes an AUTHZ_AUDIT_EVENT_HANDLE handle for use with the AuthzAccessCheck function.

AuthzInitializeRemoteResourceManager

Allocates and initializes a remote resource manager. The caller can use the resulting handle to make RPC calls to a remote
instance of the resource manager configured on a server.

AuthzInitializeResourceManager

Uses Authz to verify that clients have access to various resources.

AuthzInitializeResourceManagerEx

Allocates and initializes a resource manager structure.

AuthzInstallSecurityEventSource

Installs the specified source as a security event source.

AuthzModifyClaims

Adds, deletes, or modifies user and device claims in the Authz client context.

AuthzModifySecurityAttributes

Modifies the security attribute information in the specified client context.

AuthzModifySids

Adds, deletes, or modifies user and device groups in the Authz client context.
 AuthzOpenObjectAudit

Reads the system access control list (SACL) of the specified security descriptor and generates any appropriate audits specified
by that SACL.

AuthzRegisterCapChangeNotification

Registers a CAP update notification callback.

AuthzRegisterSecurityEventSource

Registers a security event source with the Local Security Authority (LSA).

AuthzReportSecurityEvent

Generates a security audit for a registered security event source.

AuthzReportSecurityEventFromParams

Generates a security audit for a registered security event source by using the specified array of audit parameters.

AuthzSetAppContainerInformation

Sets the app container and capability information in a current Authz context.

AuthzUninstallSecurityEventSource

Removes the specified source from the list of valid security event sources.

AuthzUnregisterCapChangeNotification

Removes a previously registered CAP update notification callback.

AuthzUnregisterSecurityEventSource

Unregisters a security event source with the Local Security Authority (LSA).

Structures

AUTHZ_ACCESS_REPLY

Defines an access check reply.

AUTHZ_ACCESS_REQUEST

Defines an access check request.

AUTHZ_INIT_INFO

Defines the initialization information for the resource manager.

 AUTHZ_REGISTRATION_OBJECT_TYPE_NAME_OFFSET

Specifies the offset of a registration object type name.

AUTHZ_RPC_INIT_INFO_CLIENT

Initializes a remote resource manager for a client.

AUTHZ_SECURITY_ATTRIBUTE_FQBN_VALUE

Specifies a fully qualified binary name value associated with a security attribute.

AUTHZ_SECURITY_ATTRIBUTE_OCTET_STRING_VALUE

Specifies an octet string value for a security attribute.

AUTHZ_SECURITY_ATTRIBUTE_V1

Defines a security attribute that can be associated with an authorization context.

AUTHZ_SECURITY_ATTRIBUTES_INFORMATION

Specifies one or more security attributes and values.

AUTHZ_SOURCE_SCHEMA_REGISTRATION

Specifies information about source schema registration.

Enumerations

AUTHZ_CONTEXT_INFORMATION_CLASS

Specifies the type of information to be retrieved from an existing AuthzClientContext. This enumeration is used by the
AuthzGetInformationFromContext function.

AUTHZ_SECURITY_ATTRIBUTE_OPERATION

Indicates the type of modification to be made to security attributes by a call to the AuthzModifySecurityAttributes function.

AUTHZ_SID_OPERATION

Indicates the type of SID operations that can be made by a call to the AuthzModifySids function.
 AUTHZ_ACCESS_REPLY structure (authz.h)
7/2/2022 • 2 minutes to read • Edit Online

The AUTHZ_ACCESS_REPLY structure defines an access check reply.

Syntax
typedef struct _AUTHZ_ACCESS_REPLY {
DWORD ResultListLength;
PACCESS_MASK GrantedAccessMask;
PDWORD SaclEvaluationResults;
PDWORD Error;
} AUTHZ_ACCESS_REPLY, *PAUTHZ_ACCESS_REPLY;

Members
ResultListLength

The number of elements in the GrantedAccessMask , SaclEvaluationResults , and Error arrays. This number
matches the number of entries in the object type list structure used in the access check. If no object type is used
to represent the object, then set ResultListLength to one.
GrantedAccessMask

An array of granted access masks. Memory for this array is allocated by the application before calling
AccessCheck.
SaclEvaluationResults

An array of system access control list (SACL) evaluation results. Memory for this array is allocated by the
application before calling AccessCheck. SACL evaluation will only be performed if auditing is requested. Each
element of this member can be one of the following values.

VA L UE M EA N IN G

An audit message that indicates success was generated.

AUTHZ_GENERATE_SUCCESS_AUDIT
0x1

An audit message that indicates failure was generated.

AUTHZ_GENERATE_FAILURE_AUDIT
0x2

Error

An array of results for each element of the array. Memory for this array is allocated by the application before
calling AccessCheck.
The following table lists the possible error values.

VA L UE M EA N IN G
 All the access bits, not including MAXIMUM_ALLOWED, are
ERROR_SUCCESS granted and the GrantedAccessMask member is not zero.

DesiredAccess includes ACCESS_SYSTEM_SECURITY and the

ERROR_PRIVILEGE_NOT_HELD client does not have SeSecurityPrivilege.

Includes each of the following:

ERROR_ACCESS_DENIED The requested bits are not granted.
MaximumAllowed bit is on and granted access is
zero.
DesiredAccess is zero.

Requirements

Minimum suppor ted client Windows XP [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Header authz.h

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP

See also
AccessCheck
 AUTHZ_ACCESS_REQUEST structure (authz.h)
7/2/2022 • 2 minutes to read • Edit Online

The AUTHZ_ACCESS_REQUEST structure defines an access check request.

Syntax
typedef struct _AUTHZ_ACCESS_REQUEST {
ACCESS_MASK DesiredAccess;
PSID PrincipalSelfSid;
POBJECT_TYPE_LIST ObjectTypeList;
DWORD ObjectTypeListLength;
PVOID OptionalArguments;
} AUTHZ_ACCESS_REQUEST, *PAUTHZ_ACCESS_REQUEST;

Members
DesiredAccess

The type of access to test for.

PrincipalSelfSid

The security identifier (SID) to use for the principal self SID in the access control list (ACL).
ObjectTypeList

An array of OBJECT_TYPE_LIST structures in the object tree for the object. Set to NULL unless the application
checks access at the property level.
ObjectTypeListLength

The number of elements in the ObjectTypeList array. This member is necessary only if the application checks
access at the property level.
OptionalArguments

A pointer to memory to pass to AuthzAccessCheckCallback when checking callback access control entries
(ACEs).

Requirements

Minimum suppor ted client Windows XP [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Header authz.h

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
See also
AuthzAccessCheckCallback
 AUTHZ_CONTEXT_INFORMATION_CLASS
enumeration (authz.h)
7/2/2022 • 2 minutes to read • Edit Online

The AUTHZ_CONTEXT_INFORMATION_CL ASS enumeration specifies the type of information to be retrieved

from an existing AuthzClientContext. This enumeration is used by the AuthzGetInformationFromContext
function.

Syntax
typedef enum _AUTHZ_CONTEXT_INFORMATION_CLASS {
AuthzContextInfoUserSid = 1,
AuthzContextInfoGroupsSids,
AuthzContextInfoRestrictedSids,
AuthzContextInfoPrivileges,
AuthzContextInfoExpirationTime,
AuthzContextInfoServerContext,
AuthzContextInfoIdentifier,
AuthzContextInfoSource,
AuthzContextInfoAll,
AuthzContextInfoAuthenticationId,
AuthzContextInfoSecurityAttributes,
AuthzContextInfoDeviceSids,
AuthzContextInfoUserClaims,
AuthzContextInfoDeviceClaims,
AuthzContextInfoAppContainerSid,
AuthzContextInfoCapabilitySids
} AUTHZ_CONTEXT_INFORMATION_CLASS;

Constants

AuthzContextInfoUserSid
Value: 1
Retrieves a TOKEN_USER structure that contains a user security identifier (SID) and its attribute.

AuthzContextInfoGroupsSids
Retrieves a TOKEN_GROUPS structure that contains the group SIDs to which the user belongs and their attributes.

AuthzContextInfoRestrictedSids
Retrieves a TOKEN_GROUPS structure that contains the restricted group SIDs in the context and their attributes.

AuthzContextInfoPrivileges
Retrieves a TOKEN_PRIVILEGES structure that contains the privileges held by the user.

AuthzContextInfoExpirationTime
Retrieves the expiration time set on the context.

AuthzContextInfoServerContext
This constant is reserved. Do not use it.
 AuthzContextInfoIdentifier
Retrieves an LUID structures used by the resource manager to identify the context.

AuthzContextInfoSource
This constant is reserved. Do not use it.

AuthzContextInfoAll
This constant is reserved. Do not use it.

AuthzContextInfoAuthenticationId
This constant is reserved. Do not use it.

AuthzContextInfoSecurityAttributes
Retrieves an AUTHZ_SECURITY_ATTRIBUTES_INFORMATION structure that contains security attributes.

Windows Ser ver 2008, Windows Vista, Windows Ser ver 2003 and Windows XP: This value is not supported.

AuthzContextInfoDeviceSids
Retrieves a TOKEN_GROUPS structure that contains device SIDs and their attributes.

Windows Ser ver 2008 R2, Windows 7, Windows Ser ver 2008, Windows Vista, Windows Ser ver 2003 and
Windows XP: This value is not supported.

AuthzContextInfoUserClaims
Retrieves a AUTHZ_SECURITY_ATTRIBUTES_INFORMATION structure that contains user claims.

Windows Ser ver 2008 R2, Windows 7, Windows Ser ver 2008, Windows Vista, Windows Ser ver 2003 and
Windows XP: This value is not supported.

AuthzContextInfoDeviceClaims
Retrieves a AUTHZ_SECURITY_ATTRIBUTES_INFORMATION structure that contains device claims.

Windows Ser ver 2008 R2, Windows 7, Windows Ser ver 2008, Windows Vista, Windows Ser ver 2003 and
Windows XP: This value is not supported.

AuthzContextInfoAppContainerSid
Retrieves a TOKEN_APPCONTAINER_INFORMATION structure that contains the app container SID.

Windows Ser ver 2008 R2, Windows 7, Windows Ser ver 2008, Windows Vista, Windows Ser ver 2003 and
Windows XP: This value is not supported.

AuthzContextInfoCapabilitySids
Retrieves a TOKEN_GROUPS structure that contains capability SIDs.

Windows Ser ver 2008 R2, Windows 7, Windows Ser ver 2008, Windows Vista, Windows Ser ver 2003 and
Windows XP: This value is not supported.

Requirements

Minimum suppor ted client Windows XP [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]
 Header authz.h

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP

See also
Authorization Enumerations
AuthzGetInformationFromContext
SECURITY_CAPABILITIES
TOKEN_APPCONTAINER_INFORMATION
TOKEN_DEVICE_CLAIMS
TOKEN_GROUPS
TOKEN_PRIVILEGES
TOKEN_USER
TOKEN_USER_CLAIMS
 AUTHZ_INIT_INFO structure (authz.h)
7/2/2022 • 2 minutes to read • Edit Online

The AUTHZ_INIT_INFO structure defines the initialization information for the resource manager.

Syntax
typedef struct _AUTHZ_INIT_INFO {
USHORT
PCWSTR
PFN_AUTHZ_DYNAMIC_ACCESS_CHECK
PFN_AUTHZ_COMPUTE_DYNAMIC_GROUPS
PFN_AUTHZ_FREE_DYNAMIC_GROUPS
PFN_AUTHZ_GET_CENTRAL_ACCESS_POLICY
PFN_AUTHZ_FREE_CENTRAL_ACCESS_POLICY
} AUTHZ_INIT_INFO, *PAUTHZ_INIT_INFO;
version;
szResourceManagerName;
pfnDynamicAccessCheck;
pfnComputeDynamicGroups;
pfnFreeDynamicGroups;
pfnGetCentralAccessPolicy;
pfnFreeCentralAccessPolicy;

Members
version

The version of the authorization resource manager initialization information structure. This must be set to
AUTHZ_INIT_INFO_VERSION_V1 (1).
szResourceManagerName

Pointer to a Unicode string that identifies the resource manager. This parameter can be NULL if the resource
manager does not need a name.
pfnDynamicAccessCheck

Pointer to an AuthzAccessCheckCallback callback function that the resource manager calls each time it
encounters a callback access control entry (ACE) during access control list (ACL) evaluation in AuthzAccessCheck
or AuthzCachedAccessCheck. This parameter can be NULL if no access check callback function is used.
pfnComputeDynamicGroups

Pointer to the AuthzComputeGroupsCallback callback function called by the resource manager during
initialization of an AuthzClientContext handle. This parameter can be NULL if no callback function is used to
compute dynamic groups.
pfnFreeDynamicGroups

Pointer to the AuthzFreeGroupsCallback callback function called by the resource manager to free security
identifier (SID) attribute arrays allocated by the compute dynamic groups callback. This parameter can be NULL
if no callback function is used to compute dynamic groups.
pfnGetCentralAccessPolicy

Pointer to the AuthzGetCentralAccessPolicyCallback callback function to be called by the resource manager to

resolve any Central Access Policy ID ACE (SYSTEM_SCOPED_POLICY_ID_ACE) encountered by AuthzAccessCheck
or AuthzCachedAccessCheck. If this parameter is NULL , the AuthzAccessCheck function will fall back to LSA to
resolve the Central Access Policy ID ACE.
pfnFreeCentralAccessPolicy

Pointer to the AuthzFreeCentralAccessPolicyCallback callback function called by the resource manager to free
the Central Access Policy allocated by the callback to get a central access policy. This parameter can be NULL if
no callback function is specified for pfnGetCentralAccessPolicy

Requirements

Minimum suppor ted client Windows 8 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2012 [desktop apps only]

Header authz.h
 AUTHZ_REGISTRATION_OBJECT_TYPE_NAME_OFFSET
structure (authz.h)
7/2/2022 • 2 minutes to read • Edit Online

The AUTHZ_REGISTRATION_OBJECT_TYPE_NAME_OFFSET structure specifies the offset of a registration

object type name.

Syntax
typedef struct _AUTHZ_REGISTRATION_OBJECT_TYPE_NAME_OFFSET {
PWSTR szObjectTypeName;
DWORD dwOffset;
} AUTHZ_REGISTRATION_OBJECT_TYPE_NAME_OFFSET, *PAUTHZ_REGISTRATION_OBJECT_TYPE_NAME_OFFSET;

Members
szObjectTypeName

A pointer to a wide character string that represents the name of the object type.
dwOffset

Offset of the object type name in an object types message DLL.

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Header authz.h

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP

See also
AUTHZ_SOURCE_SCHEMA_REGISTRATION
 AUTHZ_RPC_INIT_INFO_CLIENT structure (authz.h)
7/2/2022 • 2 minutes to read • Edit Online

The AUTHZ_RPC_INIT_INFO_CLIENT structure initializes a remote resource manager for a client.

Syntax
typedef struct _AUTHZ_RPC_INIT_INFO_CLIENT {
USHORT version;
PWSTR ObjectUuid;
PWSTR ProtSeq;
PWSTR NetworkAddr;
PWSTR Endpoint;
PWSTR Options;
PWSTR ServerSpn;
} AUTHZ_RPC_INIT_INFO_CLIENT, *PAUTHZ_RPC_INIT_INFO_CLIENT;

Members
version

Version of the structure. The highest currently supported version is

AUTHZ_RPC_INIT_INFO_CLIENT_VERSION_V1.
ObjectUuid

Null-terminated string representation of the resource manager UUID. Only the following values are valid.
Use “5fc860e0-6f6e-4fc2-83cd-46324f25e90b” for remote effective access evaluation that ignores central
policy.
Use “9a81c2bd-a525-471d-a4ed-49907c0b23da” for remote effective access evaluation that takes central
policy into account.
ProtSeq

Null-terminated string representation of a protocol sequence. This can be the following value.
“ncacn_ip_tcp”.
NetworkAddr

Null-terminated string representation of a network address. The network-address format is associated with the
protocol sequence.
Endpoint

Null-terminated string representation of an endpoint. The endpoint format and content are associated with the
protocol sequence. For example, the endpoint associated with the protocol sequence ncacn_np is a pipe name in
the format \ Pipe\ PipeName.
Options

Null-terminated string representation of network options. The option string is associated with the protocol
sequence.
ServerSpn

Server Principal Name (SPN) of the server. If this member is missing, it is constructed from NetworkAddr
assuming "host" service class.

Remarks
For a sample that uses this structure, see the Effective access rights for files sample.

Requirements

Minimum suppor ted client Windows 8 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2012 [desktop apps only]

Header authz.h
 AUTHZ_SECURITY_ATTRIBUTE_FQBN_VALUE
structure (authz.h)
7/2/2022 • 2 minutes to read • Edit Online

The AUTHZ_SECURITY_ATTRIBUTE_FQBN_VALUE structure specifies a fully qualified binary name value

associated with a security attribute.

Syntax
typedef struct _AUTHZ_SECURITY_ATTRIBUTE_FQBN_VALUE {
ULONG64 Version;
PWSTR pName;
} AUTHZ_SECURITY_ATTRIBUTE_FQBN_VALUE, *PAUTHZ_SECURITY_ATTRIBUTE_FQBN_VALUE;

Members
Version

The version number of the structure.

pName

A pointer to strings that specify the names of the publisher, the product, and the original binary file of the value.

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Header authz.h

See also
AUTHZ_SECURITY_ATTRIBUTE_V1
AUTHZ_SECURITY_ATTRUBUTES_INFORMATION
AuthzModifySecurityAttributes
 AUTHZ_SECURITY_ATTRIBUTE_OCTET_STRING_VALUE
structure (authz.h)
7/2/2022 • 2 minutes to read • Edit Online

The AUTHZ_SECURITY_ATTRIBUTE_OCTET_STRING_VALUE structure specifies an octet string value for a

security attribute.

Syntax
typedef struct _AUTHZ_SECURITY_ATTRIBUTE_OCTET_STRING_VALUE {
PVOID pValue;
ULONG ValueLength;
} AUTHZ_SECURITY_ATTRIBUTE_OCTET_STRING_VALUE, *PAUTHZ_SECURITY_ATTRIBUTE_OCTET_STRING_VALUE;

Members
pValue

A pointer to the value.

ValueLength

The length, in bytes, of the pValue member.

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Header authz.h

See also
AUTHZ_SECURITY_ATTRIBUTE_V1
AUTHZ_SECURITY_ATTRUBUTES_INFORMATION
AuthzModifySecurityAttributes
 AUTHZ_SECURITY_ATTRIBUTE_OPERATION
enumeration (authz.h)
7/2/2022 • 2 minutes to read • Edit Online

The AUTHZ_SECURITY_ATTRIBUTE_OPERATION enumeration indicates the type of modification to be made

to security attributes by a call to the AuthzModifySecurityAttributes function.

Syntax
typedef enum {
AUTHZ_SECURITY_ATTRIBUTE_OPERATION_NONE = 0,
AUTHZ_SECURITY_ATTRIBUTE_OPERATION_REPLACE_ALL,
AUTHZ_SECURITY_ATTRIBUTE_OPERATION_ADD,
AUTHZ_SECURITY_ATTRIBUTE_OPERATION_DELETE,
AUTHZ_SECURITY_ATTRIBUTE_OPERATION_REPLACE
} AUTHZ_SECURITY_ATTRIBUTE_OPERATION, *PAUTHZ_SECURITY_ATTRIBUTE_OPERATION;

Constants

AUTHZ_SECURITY_ATTRIBUTE_OPERATION_NONE
Value: 0
Do not perform any modification.

AUTHZ_SECURITY_ATTRIBUTE_OPERATION_REPLACE_ALL
Delete all existing security attributes and their values in the token and replace them with the specified attributes and values.

If no new attributes are specified, all existing attributes and values are deleted.

This operation must be the only operation specified and can be specified only once in a single call to
AuthzModifySecurityAttributes. If the operation is not specified as the first in the list of operations, the call to
AuthzModifySecurityAttributes fails. If the operation is specified as the first in the array of operations performed, the rest
of the operations are ignored.

AUTHZ_SECURITY_ATTRIBUTE_OPERATION_ADD
Add a new attribute or a new value to an existing attribute.

If the value specified for any attribute already exists for that attribute, the call to AuthzModifySecurityAttributes fails.

AUTHZ_SECURITY_ATTRIBUTE_OPERATION_DELETE
Delete the specified values of the specified attributes. If an attribute is specified without a value, that attribute is deleted.

If this operation results in an attribute that does not contain any values, that attribute is deleted.

If a value is specified that does not match an existing attribute, no modifications are performed and the call to
AuthzModifySecurityAttributes fails.
 AUTHZ_SECURITY_ATTRIBUTE_OPERATION_REPLACE
The existing values of the specified security attributes are replaced by the specified new values.

If any of the specified attributes does not already exist, they are added.

When no value is specified for an attribute, that attribute is deleted. Otherwise, the operation is simply ignored and no failure
is reported.

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Header authz.h

See also
AuthzModifySecurityAttributes
 AUTHZ_SECURITY_ATTRIBUTE_V1 structure
(authz.h)
7/2/2022 • 2 minutes to read • Edit Online

The AUTHZ_SECURITY_ATTRIBUTE_V1 structure defines a security attribute that can be associated with an
authorization context.

Syntax
typedef struct _AUTHZ_SECURITY_ATTRIBUTE_V1 {
PWSTR pName;
USHORT ValueType;
USHORT Reserved;
ULONG Flags;
ULONG ValueCount;
union {
PLONG64 pInt64;
PULONG64 pUint64;
PWSTR *ppString;
PAUTHZ_SECURITY_ATTRIBUTE_FQBN_VALUE pFqbn;
PAUTHZ_SECURITY_ATTRIBUTE_OCTET_STRING_VALUE pOctetString;
} Values;
} AUTHZ_SECURITY_ATTRIBUTE_V1, *PAUTHZ_SECURITY_ATTRIBUTE_V1;

Members
pName

A pointer to a name of a security attribute.

ValueType

The data type of the values pointed to by the Values member.

VA L UE M EA N IN G

The Values member refers to a security attribute that is of

AUTHZ_SECURITY_ATTRIBUTE_TYPE_INT64 INT64 type.
0x0001

The Values member refers to a security attribute that is of

AUTHZ_SECURITY_ATTRIBUTE_TYPE_UINT64 UINT64 type.
0x0002

The Values member refers to a security attribute that is of

AUTHZ_SECURITY_ATTRIBUTE_TYPE_STRING STRING type.
0x0003

The Values member refers to a security attribute that is of

AUTHZ_SECURITY_ATTRIBUTE_TYPE_FQBN AUTHZ_SECURITY_ATTRIBUTE_TYPE_FQBN type.
0x0004
 The Values member refers to a security attribute that is of
AUTHZ_SECURITY_ATTRIBUTE_TYPE_SID AUTHZ_SECURITY_ATTRIBUTE_TYPE_SID type.
0x0005
Windows Ser ver 2008 R2 and Windows 7: This
value type is not available.

The Values member refers to a security attribute that is of

AUTHZ_SECURITY_ATTRIBUTE_TYPE_BOOLEAN AUTHZ_SECURITY_ATTRIBUTE_TYPE_BOOLEAN type.
0x0006
Windows Ser ver 2008 R2 and Windows 7: This
value type is not available.

The Values member refers to a security attribute that is of

AUTHZ_SECURITY_ATTRIBUTE_TYPE_OCTET_STRING AUTHZ_SECURITY_ATTRIBUTE_TYPE_OCTET_STRING
0x0010 type.

The Values member refers to a security attribute that is of

AUTHZ_SECURITY_ATTRIBUTE_TYPE_OCTET_STRING AUTHZ_SECURITY_ATTRIBUTE_TYPE_OCTET_STRING
0x0010 type.

Reserved

Reserved for future use.

Flags

A combination of one or more of the following values.

VA L UE M EA N IN G

This security attribute is not inherited across processes.

AUTHZ_SECURITY_ATTRIBUTE_NON_INHERITABLE
0x0001

The value of the attribute is case sensitive. This flag is valid

AUTHZ_SECURITY_ATTRIBUTE_VALUE_CASE_SENSITIV for values that contain string types.
E
0x0002

ValueCount

The number of values specified in the Values member.

Values

Values.pInt64

A pointer to one or more numeric attribute values.

Values.pUint64

A pointer to one or more numeric attribute values.

Values.ppString

A pointer to one or more string attribute values.

Values.pFqbn

A pointer to one or more AUTHZ_SECURITY_ATTRIBUTE_FQBN_VALUE structures.

Values.pOctetString

A pointer to one or more AUTHZ_SECURITY_ATTRIBUTE_OCTET_STRING_VALUE structures.

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Header authz.h

See also
AUTHZ_SECURITY_ATTRIBUTES_INFORMATION
AuthzModifySecurityAttributes
 AUTHZ_SECURITY_ATTRIBUTES_INFORMATION
structure (authz.h)
7/2/2022 • 2 minutes to read • Edit Online

The AUTHZ_SECURITY_ATTRIBUTES_INFORMATION structure specifies one or more security attributes.

Syntax
typedef struct _AUTHZ_SECURITY_ATTRIBUTES_INFORMATION {
USHORT Version;
USHORT Reserved;
ULONG AttributeCount;
union {
PAUTHZ_SECURITY_ATTRIBUTE_V1 pAttributeV1;
} Attribute;
} AUTHZ_SECURITY_ATTRIBUTES_INFORMATION, *PAUTHZ_SECURITY_ATTRIBUTES_INFORMATION;

Members
Version

The version of this structure. Currently the only value supported is 1.

Reserved

Reserved. Do not use.

AttributeCount

The number of attributes specified by the Attribute member.

Attribute

Attribute.pAttributeV1

An array of AUTHZ_SECURITY_ATTRIBUTE_V1 structures of the length of the AttributeCount member.

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Header authz.h

See also
AuthzModifySecurityAttributes
 AUTHZ_SID_OPERATION enumeration (authz.h)
7/2/2022 • 2 minutes to read • Edit Online

The AUTHZ_SID_OPERATION enumeration indicates the type of SID operations that can be made by a call to
the AuthzModifySids function.

Syntax
typedef enum {
AUTHZ_SID_OPERATION_NONE = 0,
AUTHZ_SID_OPERATION_REPLACE_ALL,
AUTHZ_SID_OPERATION_ADD,
AUTHZ_SID_OPERATION_DELETE,
AUTHZ_SID_OPERATION_REPLACE
} AUTHZ_SID_OPERATION, *PAUTHZ_SID_OPERATION;

Constants

AUTHZ_SID_OPERATION_NONE
Value: 0
Do not modify anything.

AUTHZ_SID_OPERATION_REPLACE_ALL
Deletes all existing SIDs and replaces them with the specified SIDs. If the replacement SIDs are not specified, all existing SIDs
are deleted. This operation can be specified only once and must be the only operation specified.

AUTHZ_SID_OPERATION_ADD
Adds a new SID. If the SID already exists, the call fails.

AUTHZ_SID_OPERATION_DELETE
Deletes the specified SID. If no matching SID is found, no modifications are done and the call fails.

AUTHZ_SID_OPERATION_REPLACE
Replaces the existing SID with the specified SID. If the SID does not already exist, then adds the SID.

Requirements

Minimum suppor ted client Windows 8 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2012 [desktop apps only]

Header authz.h
 AUTHZ_SOURCE_SCHEMA_REGISTRATION
structure (authz.h)
7/2/2022 • 2 minutes to read • Edit Online

The AUTHZ_SOURCE_SCHEMA_REGISTRATION structure specifies information about source schema

registration.

Syntax
typedef struct _AUTHZ_SOURCE_SCHEMA_REGISTRATION {
DWORD dwFlags;
PWSTR szEventSourceName;
PWSTR szEventMessageFile;
PWSTR szEventSourceXmlSchemaFile;
PWSTR szEventAccessStringsFile;
PWSTR szExecutableImagePath;
union {
PVOID pReserved;
GUID *pProviderGuid;
} DUMMYUNIONNAME;
DWORD dwObjectTypeNameCount;
AUTHZ_REGISTRATION_OBJECT_TYPE_NAME_OFFSET ObjectTypeNames[ANYSIZE_ARRAY];
} AUTHZ_SOURCE_SCHEMA_REGISTRATION, *PAUTHZ_SOURCE_SCHEMA_REGISTRATION;

Members
dwFlags

Flags that control the behavior of the operation. The following table shows a possible value.

VA L UE M EA N IN G

Allows registration of multiple sources with the same name.

AUTHZ_ALLOW_MULTIPLE_SOURCE_INSTANCES Use of this flag means that more than one source can call
0x1 the AuthzRegisterSecurityEventSource function with the
same szEventSourceName at runtime.

The caller is a migrated publisher that has registered a

AUTHZ_MIGRATED_LEGACY_PUBLISHER manifest with WEvtUtil.exe. The GUID of the provider
0x2 specified by the pProviderGuid member is stored in the
registry.

szEventSourceName

A pointer to a wide character string that represents the name of the event source.
szEventMessageFile

A pointer to a wide character string that represents the name of the resource that contains the event messages.
szEventSourceXmlSchemaFile

A pointer to a wide character string that represents the name of the XML schema file for the event source.
szEventAccessStringsFile

A pointer to a wide character string that represents the name of the resource that contains the event parameter
strings.
szExecutableImagePath

This member is reserved and must be set to NULL .

DUMMYUNIONNAME

DUMMYUNIONNAME.pReserved

This member is reserved and must be set to NULL .

DUMMYUNIONNAME.pProviderGuid

The GUID of a migrated publisher. The value of this member is converted to a string and stored in the registry if
the caller is a migrated publisher.
dwObjectTypeNameCount

The number of objects in the ObjectTypeNames array.

ObjectTypeNames

An array of AUTHZ_REGISTRATION_OBJECT_TYPE_NAME_OFFSET structures that represents the object types for

the events.

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Header authz.h

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP

See also
AuthzEnumerateSecurityEventSources
AuthzInstallSecurityEventSource
 AuthzAccessCheck function (authz.h)
7/2/2022 • 3 minutes to read • Edit Online

The AuthzAccessCheck function determines which access bits can be granted to a client for a given set of
security descriptors. The AUTHZ_ACCESS_REPLY structure returns an array of granted access masks and error
status. Optionally, access masks that will always be granted can be cached, and a handle to cached values is
returned.

Syntax
AUTHZAPI BOOL AuthzAccessCheck(
[in] DWORD Flags,
[in] AUTHZ_CLIENT_CONTEXT_HANDLE hAuthzClientContext,
[in] PAUTHZ_ACCESS_REQUEST pRequest,
[in, optional] AUTHZ_AUDIT_EVENT_HANDLE hAuditEvent,
[in] PSECURITY_DESCRIPTOR pSecurityDescriptor,
[in, optional] PSECURITY_DESCRIPTOR *OptionalSecurityDescriptorArray,
[in, optional] DWORD OptionalSecurityDescriptorCount,
[in, out] PAUTHZ_ACCESS_REPLY pReply,
[out, optional] PAUTHZ_ACCESS_CHECK_RESULTS_HANDLE phAccessCheckResults
);

Parameters
[in] Flags

A DWORD value that specifies how the security descriptor is copied. This parameter can be one of the following
values.
Starting with Windows 8 and Windows Server 2012, when you call this function on a remote context handle, the
upper 16 bits must be zero.

VA L UE M EA N IN G

If phAccessCheckResults is not NULL , a deep copy of the

0 security descriptor is copied to the handle referenced by
phAccessCheckResults.

A deep copy of the security descriptor is not performed. The

AUTHZ_ACCESS_CHECK_NO_DEEP_COPY_SD calling application must pass the address of an
1 AUTHZ_ACCESS_CHECK_RESULTS_HANDLE handle in
phAccessCheckResults. The AuthzAccessCheck function
sets this handle to a security descriptor that must remain
valid during subsequent calls to AuthzCachedAccessCheck.

[in] hAuthzClientContext

A handle to a structure that represents the client.

Starting with Windows 8 and Windows Server 2012, the client context can be local or remote.
[in] pRequest

A pointer to an AUTHZ_ACCESS_REQUEST structure that specifies the desired access mask, principal self security
identifier (SID), and the object type list structure, if it exists.
[in, optional] hAuditEvent

A structure that contains object-specific audit information. When the value of this parameter is not null , an audit
is automatically requested. Static audit information is read from the resource manager structure.
Starting with Windows 8 and Windows Server 2012, when you use this function with a remote context handle,
the value of the parameter must be NULL .
[in] pSecurityDescriptor

A pointer to a SECURITY_DESCRIPTOR structure to be used for access checks. The owner SID for the object is
picked from this security descriptor. A NULL discretionary access control list (DACL) in this security descriptor
represents a NULL DACL for the entire object. Make sure the security descriptor contains OWNER and DACL
information, or an error code 87 or "invalid parameter" message will be generated.

Impor tant NULL DACLs permit all types of access to all users; therefore, do not use NULL DACLs. For information about
creating a DACL, see Creating a DACL.

A NULL system access control list (SACL) in this security descriptor is treated the same way as an empty SACL.
[in, optional] OptionalSecurityDescriptorArray

An array of SECURITY_DESCRIPTOR structures. NULL access control lists (ACLs) in these security descriptors are
treated as empty ACLs. The ACL for the entire object is the logical concatenation of all of the ACLs.
[in, optional] OptionalSecurityDescriptorCount

The number of security descriptors not including the primary security descriptor.
[in, out] pReply

A pointer to an AUTHZ_ACCESS_REPLY structure that contains the results of the access check. Before calling the
AuthzAccessCheck function, an application must allocate memory for the GrantedAccessMask and
SaclEvaluationResults members of the AUTHZ_ACCESS_REPLY structure referenced by pReply.
[out, optional] phAccessCheckResults

A pointer to return a handle to the cached results of the access check. When this parameter value is not null , the
results of this access check call will be cached. This results in a MAXIMUM_ALLOWED check.
Starting with Windows 8 and Windows Server 2012, when you use this function with a remote context handle,
the value of the parameter must be NULL .

Return value
If the function succeeds, the function returns TRUE .
If the function fails, it returns FALSE . To get extended error information, call GetLastError.

Remarks
The AuthzAccessCheckCallback callback function will be called if the DACL of the SECURITY_DESCRIPTOR
structure pointed to by the pSecurityDescriptor parameter contains a callback access control entry (ACE).
Security attribute variables must be present in the client context if referred to in a conditional expression,
otherwise the conditional expression term referencing them will evaluate to unknown. For more information,
see the Security Descriptor Definition Language for Conditional ACEs topic.
For more information, see the How AccessCheck Works and Centralized Authorization Policy overviews.

Requirements

Minimum suppor ted client Windows XP [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header authz.h

Librar y Authz.lib

DLL Authz.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP

See also
AUTHZ_ACCESS_REPLY
AUTHZ_ACCESS_REQUEST
AuthzCachedAccessCheck
Basic Access Control Functions
Centralized Authorization Policy
How AccessCheck Works
SECURITY_DESCRIPTOR
Security Descriptor Definition Language for Conditional ACEs
 AuthzAddSidsToContext function (authz.h)
7/2/2022 • 2 minutes to read • Edit Online

The AuthzAddSidsToContext function creates a copy of an existing context and appends a given set of security
identifiers (SIDs) and restricted SIDs.

Syntax
AUTHZAPI BOOL AuthzAddSidsToContext(
[in] AUTHZ_CLIENT_CONTEXT_HANDLE hAuthzClientContext,
[in] PSID_AND_ATTRIBUTES Sids,
[in] DWORD SidCount,
[in] PSID_AND_ATTRIBUTES RestrictedSids,
[in] DWORD RestrictedSidCount,
[out] PAUTHZ_CLIENT_CONTEXT_HANDLE phNewAuthzClientContext
);

Parameters
[in] hAuthzClientContext

An AUTHZ_CLIENT_CONTEXT_HANDLE structure to be copied as the basis for NewClientContext.

[in] Sids

A pointer to a SID_AND_ATTRIBUTES structure containing the SIDs and attributes to be added to the unrestricted
part of the client context.
[in] SidCount

The number of SIDs to be added.

[in] RestrictedSids

A pointer to a SID_AND_ATTRIBUTES structure containing the SIDs and attributes to be added to the restricted
part of the client context.
[in] RestrictedSidCount

Number of restricted SIDs to be added.

[out] phNewAuthzClientContext

A pointer to the created AUTHZ_CLIENT_CONTEXT_HANDLE structure containing input values for expiration
time, identifier, flags, additional SIDs and restricted SIDs.

Return value
If the function succeeds, it returns TRUE .
If the function fails, it returns FALSE . To get extended error information, call GetLastError.

Requirements
 Minimum suppor ted client Windows XP [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header authz.h

Librar y Authz.lib

DLL Authz.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP

See also
Basic Access Control Functions
SID_AND_ATTRIBUTES
 AuthzCachedAccessCheck function (authz.h)
7/2/2022 • 2 minutes to read • Edit Online

The AuthzCachedAccessCheck function performs a fast access check based on a cached handle containing
the static granted bits from a previous AuthzAccessCheck call.

Syntax
AUTHZAPI BOOL AuthzCachedAccessCheck(
[in] DWORD Flags,
[in] AUTHZ_ACCESS_CHECK_RESULTS_HANDLE hAccessCheckResults,
[in] PAUTHZ_ACCESS_REQUEST pRequest,
[in] AUTHZ_AUDIT_EVENT_HANDLE hAuditEvent,
[out] PAUTHZ_ACCESS_REPLY pReply
);

Parameters
[in] Flags

Reserved for future use.

[in] hAccessCheckResults

A handle to the cached access check results.

[in] pRequest

Access request handle specifying the desired access mask, principal self SID, and the object type list structure (if
any).
[in] hAuditEvent

A structure that contains object-specific audit information. When the value of this parameter is not null, an audit
is automatically requested. Static audit information is read from the resource manager structure.
[out] pReply

A pointer to an AUTHZ_ACCESS_REPLY handle that returns the results of access check as an array of
GrantedAccessMask/ErrorValue pairs. The number of pairs returned is supplied by the caller in the
ResultListLength member of the AUTHZ_ACCESS_REPLY structure.

Return value
If the function succeeds, it returns TRUE .
If the function fails, it returns FALSE . To get extended error information, call GetLastError.
Expected values of the Error members of array elements returned are shown in the following table.

RET URN C O DE DESC RIP T IO N

 All the access bits, not including MAXIMUM_ALLOWED, are
ERROR_SUCCESS granted and the GrantedAccessMask member of the
pReply parameter is not zero.

The DesiredAccess member of the pRequest parameter

ERROR_PRIVILEGE_NOT_HELD includes ACCESS_SYSTEM_SECURITY, and the client does not
have the SeSecurityPrivilege privilege.

One or more of the following is true:

ERROR_ACCESS_DENIED The requested bits are not granted.
The MaximumAllowed bit is on, and the granted
access is zero.
The DesiredAccess member of the pRequest
parameter is zero.

Remarks
The client context pointer is stored in the AuthzHandle parameter. The structure of the client context must be
exactly the same as it was at the time AuthzHandle was created. This restriction is for the following fields:
SIDs
RestrictedSids
Privileges
Pointers to the primary security descriptor and the optional security descriptor array are stored in AuthzHandle at
the time of handle creation. These pointers must still be valid.
The AuthzCachedAccessCheck function maintains a cache as a result of evaluating Central Access Policies
(CAP) on objects unless CAPs are ignored, for example when the
AUTHZ_RM_FLAG_NO_CENTRAL_ACCESS_POLICIES flag is used. The client may call the
AuthzFreeCentralAccessPolicyCache function to free up this cache. Note that this requires a subsequent call to
AuthzCachedAccessCheck to rebuild the cache if necessary.
For more information, see the How AccessCheck Works and Centralized Authorization Policy overviews.

Requirements

Minimum suppor ted client Windows XP [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header authz.h

Librar y Authz.lib

DLL Authz.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
See also
AUTHZ_ACCESS_REPLY
AuthzAccessCheck
AuthzFreeCentralAccessPolicyCache
AuthzInitializeResourceManager
Basic Access Control Functions
Centralized Authorization Policy
How AccessCheck Works
 AuthzEnumerateSecurityEventSources function
(authz.h)
7/2/2022 • 2 minutes to read • Edit Online

The AuthzEnumerateSecurityEventSources function retrieves the registered security event sources that are
not installed by default.

Syntax
AUTHZAPI BOOL AuthzEnumerateSecurityEventSources(
[in] DWORD dwFlags,
[out] PAUTHZ_SOURCE_SCHEMA_REGISTRATION Buffer,
[out] PDWORD pdwCount,
[in, out] PDWORD pdwLength
);

Parameters
[in] dwFlags

Reserved for future use; set this parameter to zero.

[out] Buffer

A pointer to an array of AUTHZ_SOURCE_SCHEMA_REGISTRATION structures that returns the registered

security event sources.
[out] pdwCount

A pointer to a variable that receives the number of event sources found.

[in, out] pdwLength

A pointer to a variable that specifies the length of the Buffer parameter in bytes. On output, this parameter
receives the number of bytes used or required.

Return value
If the function succeeds, it returns TRUE .
If the function fails, it returns FALSE . For extended error information, call GetLastError.

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

 Header authz.h

Librar y Authz.lib

DLL Authz.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP

See also
AUTHZ_SOURCE_SCHEMA_REGISTRATION
 AuthzFreeAuditEvent function (authz.h)
7/2/2022 • 2 minutes to read • Edit Online

The AuthzFreeAuditEvent function frees the structure allocated by the AuthzInitializeObjectAccessAuditEvent

function.

Syntax
AUTHZAPI BOOL AuthzFreeAuditEvent(
[in] AUTHZ_AUDIT_EVENT_HANDLE hAuditEvent
);

Parameters
[in] hAuditEvent

A pointer to the AUTHZ_AUDIT_EVENT_HANDLE structure to be freed.

Return value
If the function succeeds, the function returns TRUE .
If the function fails, it returns FALSE . To get extended error information, call GetLastError.

Requirements

Minimum suppor ted client Windows XP [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header authz.h

Librar y Authz.lib

DLL Authz.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP

See also
AuthzInitializeObjectAccessAuditEvent
Basic Access Control Functions
 AuthzFreeCentralAccessPolicyCache function
(authz.h)
7/2/2022 • 2 minutes to read • Edit Online

The AuthzFreeCentralAccessPolicyCache function frees the cache maintained as a result of

AuthzCachedAccessCheck evaluating the Central Access Policies (CAP) that applies for the resource.

Syntax
AUTHZAPI BOOL AuthzFreeCentralAccessPolicyCache();

Return value
If the function succeeds, it returns TRUE .
If the function fails, it returns FALSE . To get extended error information, call GetLastError.

Remarks
For more information, see the How AccessCheck Works and Centralized Authorization Policy overviews.

Requirements

Minimum suppor ted client Windows 8 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2012 [desktop apps only]

Target Platform Windows

Header authz.h

Librar y Authz.lib

DLL Authz.dll

See also
Centralized Authorization Policy
How AccessCheck Works
 AuthzFreeContext function (authz.h)
7/2/2022 • 2 minutes to read • Edit Online

The AuthzFreeContext function frees all structures and memory associated with the client context. The list of
handles for a client is freed in this call.
Starting with Windows Server 2012 and Windows 8, this function also frees the memory associated with device
groups, user claims, and device claims.

Syntax
AUTHZAPI BOOL AuthzFreeContext(
[in] AUTHZ_CLIENT_CONTEXT_HANDLE hAuthzClientContext
);

Parameters
[in] hAuthzClientContext

The AUTHZ_CLIENT_CONTEXT_HANDLE structure to be freed.

Return value
If the function succeeds, it returns TRUE .
If the function fails, it returns FALSE . To get extended error information, call GetLastError.

Requirements

Minimum suppor ted client Windows XP [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header authz.h

Librar y Authz.lib

DLL Authz.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP

See also
Basic Access Control Functions
 AuthzFreeHandle function (authz.h)
7/2/2022 • 2 minutes to read • Edit Online

The AuthzFreeHandle function finds and deletes a handle from the handle list.

Syntax
AUTHZAPI BOOL AuthzFreeHandle(
[in] AUTHZ_ACCESS_CHECK_RESULTS_HANDLE hAccessCheckResults
);

Parameters
[in] hAccessCheckResults

A handle to be freed.

Return value
If the function succeeds, it returns TRUE .
If the function fails, it returns FALSE . To get extended error information, call GetLastError.

Requirements

Minimum suppor ted client Windows XP [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header authz.h

Librar y Authz.lib

DLL Authz.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP

See also
Basic Access Control Functions
 AuthzFreeResourceManager function (authz.h)
7/2/2022 • 2 minutes to read • Edit Online

The AuthzFreeResourceManager function frees a resource manager object.

Syntax
AUTHZAPI BOOL AuthzFreeResourceManager(
[in] AUTHZ_RESOURCE_MANAGER_HANDLE hAuthzResourceManager
);

Parameters
[in] hAuthzResourceManager

The AUTHZ_RESOURCE_MANAGER_HANDLE to be freed.

Return value
If the function succeeds, it returns TRUE .
If the function fails, it returns FALSE . To get extended error information, call GetLastError.

Requirements

Minimum suppor ted client Windows XP [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header authz.h

Librar y Authz.lib

DLL Authz.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP

See also
Basic Access Control Functions
 AuthzGetInformationFromContext function (authz.h)
7/2/2022 • 2 minutes to read • Edit Online

The AuthzGetInformationFromContext function returns information about an Authz context.

Starting with Windows Server 2012 and Windows 8, device groups are returned as a TOKEN_GROUPS structure.
User and device claims are returned as an AUTHZ_SECURITY_ATTRIBUTES_INFORMATION structure.

Syntax
AUTHZAPI BOOL AuthzGetInformationFromContext(
[in] AUTHZ_CLIENT_CONTEXT_HANDLE hAuthzClientContext,
[in] AUTHZ_CONTEXT_INFORMATION_CLASS InfoClass,
[in] DWORD BufferSize,
[out] PDWORD pSizeRequired,
[out] PVOID Buffer
);

Parameters
[in] hAuthzClientContext

A handle to the context.

[in] InfoClass

A value of the AUTHZ_CONTEXT_INFORMATION_CLASS enumeration that indicates the type of information to

be returned.
[in] BufferSize

Size of the buffer passed.

[out] pSizeRequired

A pointer to a DWORD of the buffer size required for returning the structure.
[out] Buffer

A pointer to memory that can receive the information. The structure returned depends on the information
requested in the InfoClass parameter.

Return value
If the function succeeds, it returns TRUE .
If the function fails, it returns FALSE . To get extended error information, call GetLastError.

Requirements

Minimum suppor ted client Windows XP [desktop apps only]

 Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header authz.h

Librar y Authz.lib

DLL Authz.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP

See also
AUTHZ_CONTEXT_INFORMATION_CLASS
AUTHZ_SECURITY_ATTRIBUTES_INFORMATION
Basic Access Control Functions
TOKEN_GROUPS
 AuthzInitializeCompoundContext function (authz.h)
7/2/2022 • 2 minutes to read • Edit Online

The AuthzInitializeCompoundContext function creates a user-mode context from the given user and device
security contexts.

Syntax
AUTHZAPI BOOL AuthzInitializeCompoundContext(
[in] AUTHZ_CLIENT_CONTEXT_HANDLE UserContext,
[in] AUTHZ_CLIENT_CONTEXT_HANDLE DeviceContext,
[out] PAUTHZ_CLIENT_CONTEXT_HANDLE phCompoundContext
);

Parameters
[in] UserContext

User context to create the compound context from.

[in] DeviceContext

Device context to create the compound context from. This must not be the same as the user context.
[out] phCompoundContext

Used to return the resultant compound context.

Return value
If the function succeeds, it returns TRUE .
If the function fails, it returns FALSE . To get extended error information, call GetLastError.

Requirements

Minimum suppor ted client Windows 8 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2012 [desktop apps only]

Target Platform Windows

Header authz.h

Librar y Authz.lib

DLL Authz.dll
 AuthzInitializeContextFromAuthzContext function
(authz.h)
7/2/2022 • 2 minutes to read • Edit Online

The AuthzInitializeContextFromAuthzContext function creates a new client context based on an existing

client context.
Starting with Windows Server 2012 and Windows 8, this function also duplicates device groups, user claims,
and device claims.

Syntax
AUTHZAPI BOOL AuthzInitializeContextFromAuthzContext(
[in] DWORD Flags,
[in] AUTHZ_CLIENT_CONTEXT_HANDLE hAuthzClientContext,
[in, optional] PLARGE_INTEGER pExpirationTime,
[in] LUID Identifier,
[in] PVOID DynamicGroupArgs,
[out] PAUTHZ_CLIENT_CONTEXT_HANDLE phNewAuthzClientContext
);

Parameters
[in] Flags

Reserved for future use.

[in] hAuthzClientContext

The handle to an existing client context.

[in, optional] pExpirationTime

Sets the time limit for how long the returned context structure is valid. If no value is passed, then the token
never expires. Expiration time is not currently enforced.
[in] Identifier

The specific identifier for the resource manager.

[in] DynamicGroupArgs

A pointer to parameters to be passed to the callback function that computes dynamic groups. If the value is
NULL , then the callback function is not called.
[out] phNewAuthzClientContext

A pointer to the duplicated AUTHZ_CLIENT_CONTEXT_HANDLE handle. When you have finished using the
handle, release it by calling the AuthzFreeContext function.

Return value
If the function succeeds, it returns TRUE .
If the function fails, it returns FALSE . To get extended error information, call GetLastError.

Remarks
This function calls the AuthzComputeGroupsCallback callback function to add security identifiers to the newly
created context.

Requirements

Minimum suppor ted client Windows XP [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header authz.h

Librar y Authz.lib

DLL Authz.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP

See also
AUTHZ_ACCESS_REPLY
Basic Access Control Functions
 AuthzInitializeContextFromSid function (authz.h)
7/2/2022 • 4 minutes to read • Edit Online

The AuthzInitializeContextFromSid function creates a user-mode client context from a user security identifier
(SID). Domain SIDs retrieve token group attributes from the Active Directory.

Note If possible, call the AuthzInitializeContextFromToken function instead of AuthzInitializeContextFromSid . For more
information, see Remarks.

Syntax
AUTHZAPI BOOL AuthzInitializeContextFromSid(
[in] DWORD Flags,
[in] PSID UserSid,
[in, optional] AUTHZ_RESOURCE_MANAGER_HANDLE hAuthzResourceManager,
[in] PLARGE_INTEGER pExpirationTime,
[in] LUID Identifier,
[in, optional] PVOID DynamicGroupArgs,
[out] PAUTHZ_CLIENT_CONTEXT_HANDLE phAuthzClientContext
);

Parameters
[in] Flags

The following flags are defined.

Starting with Windows 8 and Windows Server 2012, when you call this function on a remote context handle, the
upper 16 bits must be zero.

VA L UE M EA N IN G

Default value.
0 (0x0)
AuthzInitializeContextFromSid attempts to retrieve
the user's token group information by performing an
S4U logon.
If S4U logon is not supported by the user's domain or
the calling computer, AuthzInitializeContextFromSid
queries the user's account object for group information.
When an account is queried directly, some groups that
represent logon characteristics, such as Network,
Interactive, Anonymous, Network Service, or Local
Service, are omitted. Applications can explicitly add such
group SIDs by implementing the
AuthzComputeGroupsCallback function or calling the
AuthzAddSidsToContext function.
 Causes AuthzInitializeContextFromSid to skip all group
AUTHZ_SKIP_TOKEN_GROUPS evaluations. When this flag is used, the context returned
2 (0x2) contains only the SID specified by the UserSid parameter.
The specified SID can be an arbitrary or application-specific
SID. Other SIDs can be added to this context by
implementing the AuthzComputeGroupsCallback function or
by calling the AuthzAddSidsToContext function.

Causes AuthzInitializeContextFromSid to fail if Windows

AUTHZ_REQUIRE_S4U_LOGON Services For User is not available to retrieve token group
4 (0x4) information.
Windows XP: This flag is not supported.

Causes AuthzInitializeContextFromSid to retrieve

AUTHZ_COMPUTE_PRIVILEGES privileges for the new context. If this function performs an
8 (0x8) S4U logon, it retrieves privileges from the token. Otherwise,
the function retrieves privileges from all SIDs in the context.

[in] UserSid

The SID of the user for whom a client context will be created. This must be a valid user or computer account
unless the AUTHZ_SKIP_TOKEN_GROUPS flag is used.
[in, optional] hAuthzResourceManager

A handle to the resource manager creating this client context. This handle is stored in the client context structure.
Starting with Windows 8 and Windows Server 2012, the resource manager can be local or remote and is
obtained by calling the AuthzInitializeRemoteResourceManager function.
[in] pExpirationTime

Expiration date and time of the token. If no value is passed, the token never expires. Expiration time is not
currently enforced.
[in] Identifier

Specific identifier of the resource manager. This parameter is not currently used.
[in, optional] DynamicGroupArgs

A pointer to parameters to be passed to the callback function that computes dynamic groups. This parameter
can be NULL if no dynamic parameters are passed to the callback function.
Starting with Windows 8 and Windows Server 2012, this parameter must be NULL if the resource manager is
remote. Otherwise, ERROR_NOT_SUPPORTED will be set.
[out] phAuthzClientContext

A pointer to the handle to the client context that the AuthzInitializeContextFromSid function creates. When
you have finished using the handle, free it by calling the AuthzFreeContext function.

Return value
If the function succeeds, the function returns nonzero.
If the function fails, it returns zero. To get extended error information, call GetLastError.

Remarks
If possible, call the AuthzInitializeContextFromToken function instead of AuthzInitializeContextFromSid .
AuthzInitializeContextFromSid attempts to retrieve the information available in a logon token had the client
actually logged on. An actual logon token provides more information, such as logon type and logon properties,
and reflects the behavior of the authentication package used for the logon. The client context created by
AuthzInitializeContextFromToken uses a logon token, and the resulting client context is more complete and
accurate than a client context created by AuthzInitializeContextFromSid .
This function resolves valid user SIDs only.
Windows XP: This function resolves group memberships for valid user and group SIDs (unless the
AUTHZ_SKIP_TOKEN_GROUPS flag is used). Support for resolving memberships of group SIDs may be altered
or unavailable in subsequent versions.
This function calls the AuthzComputeGroupsCallback callback function to add SIDs to the newly created context.

Impor tant Applications should not assume that the calling context has permission to use this function. The
AuthzInitializeContextFromSid function reads the tokenGroupsGlobalAndUniversal attribute of the SID specified in the
call to determine the current user's group memberships. If the user's object is in Active Directory, the calling context must
have read access to the tokenGroupsGlobalAndUniversal attribute on the user object. When a new domain is created, the
default access compatibility selection is Permissions compatible with Windows 2000 and Windows Ser ver 2003
operating systems . When this option is set, the Pre-Windows 2000 Compatible Access group includes only the
Authenticated Users built-in security identifiers. Therefore, applications may not have access to the
tokenGroupsGlobalAndUniversal attribute; in this case, the AuthzInitializeContextFromSid function fails with
ACCESS_DENIED. Applications that use this function should correctly handle this error and provide supporting documentation.
To simplify granting accounts permission to query a user's group information, add accounts that need the ability to look up
group information to the Windows Authorization Access Group.

Requirements

Minimum suppor ted client Windows XP [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header authz.h

Librar y Authz.lib

DLL Authz.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP

See also
Allowing Anonymous Access
AuthzFreeContext
Basic Access Control Functions
 AuthzInitializeContextFromToken function (authz.h)
7/2/2022 • 2 minutes to read • Edit Online

The AuthzInitializeContextFromToken function initializes a client authorization context from a kernel token.
The kernel token must have been opened for TOKEN_QUERY.
Starting with Windows Server 2012 and Windows 8, this function can also copy device groups, user claims, and
device claims.

Syntax
AUTHZAPI BOOL AuthzInitializeContextFromToken(
[in] DWORD Flags,
[in] HANDLE TokenHandle,
[in] AUTHZ_RESOURCE_MANAGER_HANDLE hAuthzResourceManager,
[in, optional] PLARGE_INTEGER pExpirationTime,
[in] LUID Identifier,
[in, optional] PVOID DynamicGroupArgs,
[out] PAUTHZ_CLIENT_CONTEXT_HANDLE phAuthzClientContext
);

Parameters
[in] Flags

Reserved for future use.

[in] TokenHandle

A handle to the client token used to initialize the pAuthzClientContext parameter. The token must have been
opened with TOKEN_QUERY access.
[in] hAuthzResourceManager

A handle to the resource manager that created this client context. This handle is stored in the client context
structure.
[in, optional] pExpirationTime

Expiration date and time of the token. If no value is passed, the token never expires. Expiration time is not
currently enforced.
[in] Identifier

Identifier that is specific to the resource manager. This parameter is not currently used.
[in, optional] DynamicGroupArgs

A pointer to parameters to be passed to the callback function that computes dynamic groups.
[out] phAuthzClientContext

A pointer to the AuthzClientContext handle returned. Call AuthzFreeContext when done with the client context.

Return value
If the function succeeds, it returns TRUE .
If the function fails, it returns FALSE . To get extended error information, call GetLastError.

Remarks
This function calls the AuthzComputeGroupsCallback callback function to add security identifiers to the newly
created context.

Requirements

Minimum suppor ted client Windows XP [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header authz.h

Librar y Authz.lib

DLL Authz.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP

See also
AuthzFreeContext
Basic Access Control Functions
 AuthzInitializeObjectAccessAuditEvent function
(authz.h)
7/2/2022 • 2 minutes to read • Edit Online

The AuthzInitializeObjectAccessAuditEvent function initializes auditing for an object.

Syntax
AUTHZAPI BOOL AuthzInitializeObjectAccessAuditEvent(
[in] DWORD Flags,
[in] AUTHZ_AUDIT_EVENT_TYPE_HANDLE hAuditEventType,
[in] PWSTR szOperationType,
[in] PWSTR szObjectType,
[in] PWSTR szObjectName,
[in] PWSTR szAdditionalInfo,
[out] PAUTHZ_AUDIT_EVENT_HANDLE phAuditEvent,
[in] DWORD dwAdditionalParameterCount,
...
);

Parameters
[in] Flags

Modifies the audit. This parameter can be one of the following values.

VA L UE M EA N IN G

Disable generation of success audits.

AUTHZ_NO_SUCCESS_AUDIT

Disable generation of failure audits.

AUTHZ_NO_FAILURE_AUDIT

Use pointers to the passed strings instead of allocating

AUTHZ_NO_ALLOC_STRINGS memory and copying the strings. The calling application
must ensure that the passed memory stays valid during
access checks.

[in] hAuditEventType

Reserved. This parameter should be set to NULL .

[in] szOperationType

String that indicates the operation that is to be audited.

[in] szObjectType

String that indicates the type of object being accessed.

[in] szObjectName
String the indicates the name of the object being accessed.
[in] szAdditionalInfo

String, defined by the Resource Manager, for additional audit information.

[out] phAuditEvent

Pointer that receives an AUTHZ_AUDIT_EVENT_HANDLE structure.

[in] dwAdditionalParameterCount

Must be set to zero.

...

Additional parameters.

Return value
If the function succeeds, it returns TRUE .
If the function fails, it returns FALSE . For extended error information, call GetLastError.

Requirements

Minimum suppor ted client Windows XP [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header authz.h

Librar y Authz.lib

DLL Authz.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP

See also
AuthzAccessCheck
Basic Access Control Functions
 AuthzInitializeObjectAccessAuditEvent2 function
(authz.h)
7/2/2022 • 2 minutes to read • Edit Online

The AuthzInitializeObjectAccessAuditEvent2 function allocates and initializes an

AUTHZ_AUDIT_EVENT_HANDLE handle for use with the AuthzAccessCheck function.

Syntax
AUTHZAPI BOOL AuthzInitializeObjectAccessAuditEvent2(
[in] DWORD Flags,
[in] AUTHZ_AUDIT_EVENT_TYPE_HANDLE hAuditEventType,
[in] PWSTR szOperationType,
[in] PWSTR szObjectType,
[in] PWSTR szObjectName,
[in] PWSTR szAdditionalInfo,
[in] PWSTR szAdditionalInfo2,
[out] PAUTHZ_AUDIT_EVENT_HANDLE phAuditEvent,
[in] DWORD dwAdditionalParameterCount,
...
);

Parameters
[in] Flags

Flags that modify the behavior of the audit. The following table shows the possible values.

VA L UE M EA N IN G

Uses pointers to the passed strings instead of allocating

AUTHZ_NO_ALLOC_STRINGS memory and copying the strings. The calling application
must ensure that the passed memory remains valid during
access checks.

Disables generation of failure audits.

AUTHZ_NO_FAILURE_AUDIT

Disables generation of success audits.

AUTHZ_NO_SUCCESS_AUDIT

[in] hAuditEventType

Reserved. This parameter should be set to NULL .

[in] szOperationType

A pointer to a string that indicates the operation that is to be audited.

[in] szObjectType

A pointer to a string that indicates the type of object accessed.

[in] szObjectName

A pointer to a string that indicates the name of the object accessed.

[in] szAdditionalInfo

Pointer to a string defined by the Resource Manager that contains additional audit information.
[in] szAdditionalInfo2

Pointer to a string defined by the Resource Manager that contains additional audit information.
[out] phAuditEvent

A pointer to the returned AUTHZ_AUDIT_EVENT_HANDLE handle.

[in] dwAdditionalParameterCount

Must be set to zero.

...

Additional parameters.

Return value
If the function succeeds, it returns TRUE .
If the function fails, it returns FALSE . For extended error information, call GetLastError.

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header authz.h

Librar y Authz.lib

DLL Authz.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP

See also
AuthzAccessCheck
Basic Access Control Functions
 AuthzInitializeRemoteResourceManager function
(authz.h)
7/2/2022 • 2 minutes to read • Edit Online

The AuthzInitializeRemoteResourceManager function allocates and initializes a remote resource manager.

The caller can use the resulting handle to make AuthZ calls over RPC to a remote instance of the resource
manager configured on a server.

Syntax
AUTHZAPI BOOL AuthzInitializeRemoteResourceManager(
[in] PAUTHZ_RPC_INIT_INFO_CLIENT pRpcInitInfo,
[out] PAUTHZ_RESOURCE_MANAGER_HANDLE phAuthzResourceManager
);

Parameters
[in] pRpcInitInfo

Pointer to an AUTHZ_RPC_INIT_INFO_CLIENT structure containing the initial information needed to configure

the connection.
[out] phAuthzResourceManager

A handle to the resource manager. When you have finished using the handle, free it by calling the
AuthzFreeResourceManager function.

Return value
If the function succeeds, the function returns TRUE .
If the function fails, it returns FALSE . To get extended error information, call GetLastError.

Requirements

Minimum suppor ted client Windows 8 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2012 [desktop apps only]

Target Platform Windows

Header authz.h

Librar y Authz.lib

DLL Authz.dll
 AuthzInitializeResourceManager function (authz.h)
7/2/2022 • 2 minutes to read • Edit Online

The AuthzInitializeResourceManager function uses Authz to verify that clients have access to various
resources.

Syntax
AUTHZAPI BOOL AuthzInitializeResourceManager(
[in] DWORD Flags,
[in, optional] PFN_AUTHZ_DYNAMIC_ACCESS_CHECK pfnDynamicAccessCheck,
[in, optional] PFN_AUTHZ_COMPUTE_DYNAMIC_GROUPS pfnComputeDynamicGroups,
[in, optional] PFN_AUTHZ_FREE_DYNAMIC_GROUPS pfnFreeDynamicGroups,
[in] PCWSTR szResourceManagerName,
[out] PAUTHZ_RESOURCE_MANAGER_HANDLE phAuthzResourceManager
);

Parameters
[in] Flags

A DWORD value that defines how the resource manager is initialized. This parameter can contain the following
values.

VA L UE M EA N IN G

Default call to the function. The resource manager is

0 initialized as the principal identified in the process token, and
auditing is in effect. Note that unless the
AUTHZ_RM_FL AG_NO_AUDIT flag is set,
SeAuditPrivilege must be enabled for the function to
succeed.

Auditing is not in effect. If this flag is set, the caller does not
AUTHZ_RM_FL AG_NO_AUDIT need to have SeAuditPrivilege enabled to call this
function.

The resource manager is initialized as the identity of the

AUTHZ_RM_FL AG_INITIALIZE_UNDER_IMPERSONATI thread token.
ON

The resource manager ignores CAP IDs and does not

AUTHZ_RM_FL AG_NO_CENTRAL_ACCESS_POLICIES evaluate centralized access policies.

AUTHZ_RM_FLAG_NO_AUDIT and AUTHZ_RM_FLAG_INITIALIZE_UNDER_IMPERSONATION can be bitwise-

combined.
[in, optional] pfnDynamicAccessCheck

A pointer to the AuthzAccessCheckCallback callback function that the resource manager calls each time it
encounters a callback access control entry (ACE) during access control list (ACL) evaluation in AuthzAccessCheck
or AuthzCachedAccessCheck. This parameter can be NULL if no access check callback function is used.
[in, optional] pfnComputeDynamicGroups

A pointer to the AuthzComputeGroupsCallback callback function called by the resource manager during
initialization of an AuthzClientContext handle. This parameter can be NULL if no callback function is used to
compute dynamic groups.
[in, optional] pfnFreeDynamicGroups

A pointer to the AuthzFreeGroupsCallback callback function called by the resource manager to free security
identifier (SID) attribute arrays allocated by the compute dynamic groups callback. This parameter can be NULL
if no callback function is used to compute dynamic groups.
[in] szResourceManagerName

A string that identifies the resource manager. This parameter can be NULL if the resource manager does not
need a name.
[out] phAuthzResourceManager

A pointer to the returned resource manager handle. When you have finished using the handle, free it by calling
the AuthzFreeResourceManager function.

Return value
If the function succeeds, the function returns a nonzero value.
If the function fails, it returns a zero value. To get extended error information, call GetLastError.

Requirements

Minimum suppor ted client Windows XP [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header authz.h

Librar y Authz.lib

DLL Authz.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP

See also
AuthzAccessCheck
AuthzCachedAccessCheck
AuthzFreeResourceManager
Basic Access Control Functions
 AuthzInitializeResourceManagerEx function
(authz.h)
7/2/2022 • 2 minutes to read • Edit Online

The AuthzInitializeResourceManagerEx function initializes an Authz resource manager and returns a handle
to it. Use this function rather than AuthzInitializeResourceManager when you want the resource manager to
manage Central Access Policies (CAPs).

Syntax
AUTHZAPI BOOL AuthzInitializeResourceManagerEx(
[in, optional] DWORD Flags,
[in, optional] PAUTHZ_INIT_INFO pAuthzInitInfo,
[out] PAUTHZ_RESOURCE_MANAGER_HANDLE phAuthzResourceManager
);

Parameters
[in, optional] Flags

A DWORD value that defines how the resource manager is initialized. This parameter can be one or more of the
following values.

VA L UE M EA N IN G

Default call to the function. The resource manager is

0 initialized as the principal identified in the process token, and
auditing is in effect. Unless the
AUTHZ_RM_FL AG_NO_AUDIT flag is set,
SeAuditPrivilege must be enabled for the function to
succeed.

Auditing is not in effect. If this flag is set, the caller does not
AUTHZ_RM_FL AG_NO_AUDIT need to have SeAuditPrivilege enabled to call this
1 function. Use this flag if the resource manager will never
generate an audit for best performance.

The resource manager is initialized as the identity of the

AUTHZ_RM_FL AG_INITIALIZE_UNDER_IMPERSONATI thread token. If the current thread is impersonating, then
ON use the impersonation token as the identity of the resource
2 manager.

The central access policy IDs are ignored. Do not evaluate

AUTHZ_RM_FL AG_NO_CENTRAL_ACCESS_POLICIES central access policies.
4

[in, optional] pAuthzInitInfo

A pointer to a AUTHZ_INIT_INFO structure that contains the authorization resource manager initialization
information.
[out] phAuthzResourceManager

A pointer to the returned resource manager handle. When you have finished using the handle, free it by using
the AuthzFreeResourceManager function.

Return value
If the function succeeds, the function returns a value of TRUE .
If the function fails, it returns a value of FALSE . To get extended error information, call GetLastError.

Remarks
If the AUTHZ_RM_FLAG_NO_CENTRAL_ACCESS_POLICIES flag is specified, then AuthzAccessCheck and
AuthzCachedAccessCheck ignore CAPID (Central Access Policie ID) access control
entriesSYSTEM_SCOPED_POLICY_ID_ACE and will not evaluate CAPs.
If the AUTHZ_RM_FLAG_NO_CENTRAL_ACCESS_POLICIES flag is not specified and pfnGetCentralAccessPolicy is
NULL , then AuthzAccessCheck and AuthzCachedAccessCheck will get CAPs from LSA. For more information,
see LsaGetAppliedCAPIDs.
If the AUTHZ_RM_FLAG_NO_CENTRAL_ACCESS_POLICIES flag is not specified and a central access policy
callback is provided by the resource manager, then AuthzAccessCheck and AuthzCachedAccessCheck will get
CAPs from the resource manager by invoking the callback.
The LSA and the central access policy callback can indicate that CAPs are not supported, in which case
AuthzAccessCheck and AuthzCachedAccessCheck ignore CAPID ACEs and will not evaluate CAPs.
The LSA and the central access policy callback may fail to return a CAP that corresponds to a particular CAPID, in
which case AuthzAccessCheck and AuthzCachedAccessCheck use the same default CAP as the kernel
AccessCheck.

Requirements

Minimum suppor ted client Windows 8 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2012 [desktop apps only]

Target Platform Windows

Header authz.h

Librar y Authz.lib

DLL Authz.dll

See also
LsaGetAppliedCAPIDs
 AuthzInstallSecurityEventSource function (authz.h)
7/2/2022 • 2 minutes to read • Edit Online

The AuthzInstallSecurityEventSource function installs the specified source as a security event source.

Syntax
AUTHZAPI BOOL AuthzInstallSecurityEventSource(
[in] DWORD dwFlags,
[in] PAUTHZ_SOURCE_SCHEMA_REGISTRATION pRegistration
);

Parameters
[in] dwFlags

This parameter is reserved for future use and must be set to zero.
[in] pRegistration

A pointer to an AUTHZ_SOURCE_SCHEMA_REGISTRATION structure that contains information about the

security event source to be added.
The members of the AUTHZ_SOURCE_SCHEMA_REGISTRATION structure are used as follows to install the
security event source in the security log key:
The szEventSourceName member is added as a registry key under

HKEY_LOCAL_MACHINE
SYSTEM
CurrentControlSet
Services
EventLog
Security

The szEventMessageFile member is added as the data in a REG_SZ value named EventMessageFile
under the event source key.
The szEventAccessStringsFile member is added as the data in a REG_SZ value named
ParameterMessageFile under the event source key.
If the registry path does not exist, it is created.
If the szEventSourceXmlSchemaFile member is not NULL , it is added as the data in a REG_SZ value
named XmlSchemaFile under the event source key. This value is not used.
The szExecutableImagePath member may be set to NULL .

Return value
If the function succeeds, the function returns TRUE .
If the function fails, it returns FALSE . For extended error information, call GetLastError.
Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header authz.h

Librar y Authz.lib

DLL Authz.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP

See also
AUTHZ_SOURCE_SCHEMA_REGISTRATION
AuthzUninstallSecurityEventSource
 AuthzModifyClaims function (authz.h)
7/2/2022 • 2 minutes to read • Edit Online

The AuthzModifyClaims function adds, deletes, or modifies user and device claims in the Authz client context.

Syntax
AUTHZAPI BOOL AuthzModifyClaims(
[in] AUTHZ_CLIENT_CONTEXT_HANDLE hAuthzClientContext,
[in] AUTHZ_CONTEXT_INFORMATION_CLASS ClaimClass,
[in] PAUTHZ_SECURITY_ATTRIBUTE_OPERATION pClaimOperations,
[in, optional] PAUTHZ_SECURITY_ATTRIBUTES_INFORMATION pClaims
);

Parameters
[in] hAuthzClientContext

A handle to the client context to be modified.

[in] ClaimClass

Type of information to be modified. The caller can specify AuthzContextInfoUserClaims or

AuthzContextInfoDeviceClaims.
[in] pClaimOperations

A pointer to an array of AUTHZ_SECURITY_ATTRIBUTE_OPERATION enumeration values that specify the type of

claim modification to make.
[in, optional] pClaims

A pointer to an AUTHZ_SECURITY_ATTRIBUTES_INFORMATION structure that specifies the claims to modify.

Return value
If the function succeeds, it returns TRUE .
If the function fails, it returns FALSE . To get extended error information, call GetLastError.

Remarks
The AUTHZ_SECURITY_ATTRIBUTE_OPERATION enumeration must have only one element if the value of that
element is AUTHZ_SECURITY_ATTRIBUTE_OPERATION_REPLACE_ALL. Otherwise, the array has the same
number of elements as the corresponding PAUTHZ_SECURITY_ATTRIBUTES_INFORMATION.
If the AUTHZ_SECURITY_ATTRIBUTE_OPERATION enumeration is
AUTHZ_SECURITY_ATTRIBUTE_OPERATION_REPLACE and the function fails, call GetLastError. If the error code is
ERROR_ALREADY_EXISTS, the claim's values have duplicate entries.

Requirements
Minimum suppor ted client Windows 8 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2012 [desktop apps only]

Target Platform Windows

Header authz.h

Librar y Authz.lib

DLL Authz.dll
 AuthzModifySecurityAttributes function (authz.h)
7/2/2022 • 2 minutes to read • Edit Online

The AuthzModifySecurityAttributes function modifies the security attribute information in the specified
client context.

Syntax
AUTHZAPI BOOL AuthzModifySecurityAttributes(
[in] AUTHZ_CLIENT_CONTEXT_HANDLE hAuthzClientContext,
[in] PAUTHZ_SECURITY_ATTRIBUTE_OPERATION pOperations,
[in] PAUTHZ_SECURITY_ATTRIBUTES_INFORMATION pAttributes
);

Parameters
[in] hAuthzClientContext

A handle to the client context to be modified.

[in] pOperations

A pointer to an array of AUTHZ_SECURITY_ATTRIBUTE_OPERATION enumeration values that specify the types of

modifications to make.
This array must have only one element if the value of that element is
AUTHZ_SECURITY_ATTRIBUTE_OPERATION_REPL ACE_ALL . Otherwise, the array has the same number of
elements as the pAttributes array.
[in] pAttributes

A pointer to an AUTHZ_SECURITY_ATTRIBUTES_INFORMATION structure that specifies the attributes to modify.

Return value
If the function succeeds, it returns TRUE .
If the function fails, it returns FALSE . To get extended error information, call GetLastError.

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Target Platform Windows

Header authz.h
Librar y Authz.lib

DLL Authz.dll
 AuthzModifySids function (authz.h)
7/2/2022 • 2 minutes to read • Edit Online

The AuthzModifySids function adds, deletes, or modifies user and device groups in the Authz client context.

Syntax
AUTHZAPI BOOL AuthzModifySids(
[in] AUTHZ_CLIENT_CONTEXT_HANDLE hAuthzClientContext,
[in] AUTHZ_CONTEXT_INFORMATION_CLASS SidClass,
[in] PAUTHZ_SID_OPERATION pSidOperations,
[in, optional] PTOKEN_GROUPS pSids
);

Parameters
[in] hAuthzClientContext

A handle to the client context to be modified.

[in] SidClass

Type of information to be modified. The caller can specify AuthzContextInfoGroupsSids,

AuthzContextInfoRestrictedSids, or AuthzContextInfoDeviceSids.
[in] pSidOperations

A pointer to an array of AUTHZ_SID_OPERATION enumeration values that specify the group modifications to
make.
[in, optional] pSids

A pointer to a TOKEN_GROUPS structure that specifies the groups to modify.

Return value
If the function succeeds, it returns TRUE .
If the function fails, it returns FALSE . To get extended error information, call GetLastError.

Remarks
The AUTHZ_SID_OPERATION enumeration must have only one element if the value of that element is
AUTHZ_SID_OPERATION_REPLACE_ALL. Otherwise, the array has the same number of elements as the
corresponding PTOKEN_GROUPS.
When you want to use AuthzModifySids to delete, the SIDs are matched but not the SID flags. If no matching
SID is found, no modifications are done and the call fails.

Requirements
Minimum suppor ted client Windows 8 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2012 [desktop apps only]

Target Platform Windows

Header authz.h

Librar y Authz.lib

DLL Authz.dll
 AuthzOpenObjectAudit function (authz.h)
7/2/2022 • 2 minutes to read • Edit Online

The AuthzOpenObjectAudit function reads the system access control list (SACL) of the specified security
descriptor and generates any appropriate audits specified by that SACL.

Syntax
AUTHZAPI BOOL AuthzOpenObjectAudit(
[in] DWORD Flags,
[in] AUTHZ_CLIENT_CONTEXT_HANDLE hAuthzClientContext,
[in] PAUTHZ_ACCESS_REQUEST pRequest,
[in] AUTHZ_AUDIT_EVENT_HANDLE hAuditEvent,
[in] PSECURITY_DESCRIPTOR pSecurityDescriptor,
[in] PSECURITY_DESCRIPTOR *OptionalSecurityDescriptorArray,
[in] DWORD OptionalSecurityDescriptorCount,
[in] PAUTHZ_ACCESS_REPLY pReply
);

Parameters
[in] Flags

Reserved for future use.

[in] hAuthzClientContext

A handle to the client context of the object to open.

[in] pRequest

A pointer to an AUTHZ_ACCESS_REQUEST structure.

[in] hAuditEvent

A handle to the audit event to use.

[in] pSecurityDescriptor

A pointer to the SECURITY_DESCRIPTOR structure for the object.

[in] OptionalSecurityDescriptorArray

A pointer to an array of SECURITY_DESCRIPTOR structures.

[in] OptionalSecurityDescriptorCount

The number of elements in SecurityDescriptorArray.

[in] pReply

A pointer to an AUTHZ_ACCESS_REPLY structure.

Return value
If the function succeeds, it returns a nonzero value.
If the function fails, it returns a zero value. To get extended error information, call GetLastError.

Requirements

Minimum suppor ted client Windows XP [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header authz.h

Librar y Authz.lib

DLL Authz.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP

See also
Basic Access Control Functions
 AuthzRegisterCapChangeNotification function
(authz.h)
7/2/2022 • 2 minutes to read • Edit Online

The AuthzRegisterCapChangeNotification function registers a CAP update notification callback.

Syntax
AUTHZAPI BOOL AuthzRegisterCapChangeNotification(
[out] PAUTHZ_CAP_CHANGE_SUBSCRIPTION_HANDLE phCapChangeSubscription,
[in] LPTHREAD_START_ROUTINE pfnCapChangeCallback,
[in, optional] PVOID pCallbackContext
);

Parameters
[out] phCapChangeSubscription

Pointer to the CAP change notification subscription handle. When you have finished using the handle,
unsubscribe by passing this parameter to the AuthzUnregisterCapChangeNotification function.
[in] pfnCapChangeCallback

The CAP change notification callback function.

[in, optional] pCallbackContext

The context of the user to be passed to the callback function.

Return value
If the function succeeds, it returns TRUE .
If the function fails, it returns FALSE . To get extended error information, call GetLastError.

Remarks
This function is intended for applications that manually manage CAP usage to get notified of CAP changes in the
system.

Requirements

Minimum suppor ted client Windows 8 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2012 [desktop apps only]

Target Platform Windows

 Header authz.h

Librar y Authz.lib

DLL Authz.dll

See also
AuthzUnregisterCapChangeNotification
Central Access Policies
How AccessCheck Works
 AuthzRegisterSecurityEventSource function
(authz.h)
7/2/2022 • 2 minutes to read • Edit Online

The AuthzRegisterSecurityEventSource function registers a security event source with the Local Security
Authority (LSA).

Syntax
AUTHZAPI BOOL AuthzRegisterSecurityEventSource(
[in] DWORD dwFlags,
[in] PCWSTR szEventSourceName,
[out] PAUTHZ_SECURITY_EVENT_PROVIDER_HANDLE phEventProvider
);

Parameters
[in] dwFlags

This parameter is reserved for future use. Set this parameter to zero.
[in] szEventSourceName

A pointer to the name of the security event source to register.

[out] phEventProvider

A pointer to a handle to the registered security event source.

Return value
If the function succeeds, the function returns TRUE .
If the function fails, it returns FALSE . For extended error information, call GetLastError.

Remarks
This function validates the szEventSourceName parameter and sets up the appropriate structures and RPC
connections to log events with that source name. The validation is handled by an underlying call to an LSA API.
The LSA API verifies the following:
The caller has the SeAuditPrivilege access right.
The event source is not already in use.
The event source is registered.
The calling application matches the executable image path in the event source registration, if one exists.

Requirements
 Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header authz.h

Librar y Authz.lib

DLL Authz.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP

See also
AuthzUnregisterSecurityEventSource
 AuthzReportSecurityEvent function (authz.h)
7/2/2022 • 2 minutes to read • Edit Online

The AuthzRepor tSecurityEvent function generates a security audit for a registered security event source.
Auditing for the object access event category must be enabled for the AuthzRepor tSecurityEvent function to
generate a security audit. The available audit types are defined in the AUDIT_PARAM_TYPE enumeration.

Syntax
AUTHZAPI BOOL AuthzReportSecurityEvent(
[in] DWORD dwFlags,
[in, out] AUTHZ_SECURITY_EVENT_PROVIDER_HANDLE hEventProvider,
[in] DWORD dwAuditId,
[in, optional] PSID pUserSid,
[in] DWORD dwCount,
...
);

Parameters
[in] dwFlags

Flags that specify the type of audit generated. The following table shows the possible values.

VA L UE M EA N IN G

Failure audits are generated.

APF_AuditFailure
0x00000000

Success audits are generated.

APF_AuditSuccess
0x00000001

[in, out] hEventProvider

A handle to the registered security event source to use for the audit.
[in] dwAuditId

The identifier of the audit.

[in, optional] pUserSid

A pointer to the security identifier (SID) that will be listed as the source of the audit in the event log.
[in] dwCount

The number of AuditParamFlag type/value pairs that appear in the variable arguments section that follows this
parameter.
...
A list of AuditParamFlag type/value pairs that provide additional information about the event.

Return value
If the function succeeds, the function returns TRUE .
If the function fails, it returns FALSE . For extended error information, call GetLastError.

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header authz.h

Librar y Authz.lib

DLL Authz.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP

See also
AuthzRegisterSecurityEventSource
AuthzReportSecurityEventFromParams
 AuthzReportSecurityEventFromParams function
(authz.h)
7/2/2022 • 2 minutes to read • Edit Online

The AuthzRepor tSecurityEventFromParams function generates a security audit for a registered security
event source by using the specified array of audit parameters.

Syntax
AUTHZAPI BOOL AuthzReportSecurityEventFromParams(
[in] DWORD dwFlags,
[in] AUTHZ_SECURITY_EVENT_PROVIDER_HANDLE hEventProvider,
[in] DWORD dwAuditId,
[in, optional] PSID pUserSid,
[in] PAUDIT_PARAMS pParams
);

Parameters
[in] dwFlags

Reserved for future use.

[in] hEventProvider

A handle to the registered security event source to use for the audit.
[in] dwAuditId

The identifier of the audit.

[in, optional] pUserSid

A pointer to the security identifier (SID) that will be listed as the source of the audit in the event log.
[in] pParams

An array of audit parameters.

Return value
If the function succeeds, the function returns TRUE .
If the function fails, it returns FALSE . For extended error information, call GetLastError.

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]
 Target Platform Windows

Header authz.h

Librar y Authz.lib

DLL Authz.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP

See also
AuthzRegisterSecurityEventSource
AuthzReportSecurityEvent
 AuthzSetAppContainerInformation function
(authz.h)
7/2/2022 • 2 minutes to read • Edit Online

The AuthzSetAppContainerInformation function sets the app container and capability information in a
current Authz context. If the passed in context already has an app container security identifier (SID) set or if the
passed in context is not a valid app container SID, this function fails.

Syntax
AUTHZAPI BOOL AuthzSetAppContainerInformation(
[in] AUTHZ_CLIENT_CONTEXT_HANDLE hAuthzClientContext,
[in] PSID pAppContainerSid,
[in] DWORD CapabilityCount,
[in, optional] PSID_AND_ATTRIBUTES pCapabilitySids
);

Parameters
[in] hAuthzClientContext

The handle to the client context to which the given app container SID and capability SIDs will be added.
[in] pAppContainerSid

The app container SID.

[in] CapabilityCount

The number of capability SIDs to be added. This value can be zero if no capability is to be added.
[in, optional] pCapabilitySids

The capability SIDs to be added to the context. This value must be NULL when the CapabilityCount parameter is
zero.

Return value
If the function succeeds, it returns TRUE .
If the function fails, it returns FALSE . To get extended error information, call GetLastError.

Requirements

Minimum suppor ted client Windows 8 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2012 [desktop apps only]

Target Platform Windows

Header authz.h

Librar y Authz.lib

DLL Authz.dll
 AuthzUninstallSecurityEventSource function
(authz.h)
7/2/2022 • 2 minutes to read • Edit Online

The AuthzUninstallSecurityEventSource function removes the specified source from the list of valid security
event sources.

Syntax
AUTHZAPI BOOL AuthzUninstallSecurityEventSource(
[in] DWORD dwFlags,
[in] PCWSTR szEventSourceName
);

Parameters
[in] dwFlags

Reserved for future use; set this parameter to zero.

[in] szEventSourceName

Name of the source to remove from the list of valid security event sources. This corresponds to the
szEventSourceName member of the AUTHZ_SOURCE_SCHEMA_REGISTRATION structure that defines the
source.
This function removes the source information from the registry. For more information about the registry keys
and values affected, see the AuthzInstallSecurityEventSource function.

Return value
If the function succeeds, it returns TRUE .
If the function fails, it returns FALSE . For extended error information, call GetLastError.

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header authz.h

Librar y Authz.lib
 DLL Authz.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP

See also
AUTHZ_SOURCE_SCHEMA_REGISTRATION
AuthzInstallSecurityEventSource
 AuthzUnregisterCapChangeNotification function
(authz.h)
7/2/2022 • 2 minutes to read • Edit Online

The AuthzUnregisterCapChangeNotification function removes a previously registered CAP update

notification callback.

Syntax
AUTHZAPI BOOL AuthzUnregisterCapChangeNotification(
[in] AUTHZ_CAP_CHANGE_SUBSCRIPTION_HANDLE hCapChangeSubscription
);

Parameters
[in] hCapChangeSubscription

Handle of the CAP change notification subscription to unregister.

Return value
If the function succeeds, it returns TRUE .
If the function fails, it returns FALSE . To get extended error information, call GetLastError.

Remarks
This function blocks operations until all callbacks are complete. Do not call this function from inside a callback
function because it will cause a deadlock.

Requirements

Minimum suppor ted client Windows 8 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2012 [desktop apps only]

Target Platform Windows

Header authz.h

Librar y Authz.lib

DLL Authz.dll

See also
AuthzRegisterCapChangeNotification
Central Access Policies
How AccessCheck Works
 AuthzUnregisterSecurityEventSource function
(authz.h)
7/2/2022 • 2 minutes to read • Edit Online

The AuthzUnregisterSecurityEventSource function unregisters a security event source with the Local
Security Authority (LSA).

Syntax
AUTHZAPI BOOL AuthzUnregisterSecurityEventSource(
[in] DWORD dwFlags,
[in, out] PAUTHZ_SECURITY_EVENT_PROVIDER_HANDLE phEventProvider
);

Parameters
[in] dwFlags

This parameter is reserved for future use. Set this parameter to zero.
[in, out] phEventProvider

A pointer to a handle to the security event source to unregister.

Return value
If the function succeeds, the function returns TRUE .
If the function fails, it returns FALSE . For extended error information, call GetLastError.

Remarks
This function deallocates any resources and closes any RPC connections associated with a previous call to the
AuthzRegisterSecurityEventSource function.

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header authz.h

Librar y Authz.lib
 DLL Authz.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP

See also
AuthzRegisterSecurityEventSource
 azroles.h header
7/2/2022 • 2 minutes to read • Edit Online

This header is used by Security and Identity. For more information, see:
Security and Identity
azroles.h contains the following programming interfaces:

Interfaces

IAzApplication

Defines an installed instance of an application. An IAzApplication object is created when an application is installed.

IAzApplication2

Inherits from the IAzApplication interface and implements additional methods to initialize IAzClientContext2 objects.

IAzApplication3

Provides methods to manage IAzRoleAssignment, IAzRoleDefinition, and IAzScope2 objects.

IAzApplicationGroup

Defines a collection of principals.

IAzApplicationGroup2

Extends the IAzApplicationGroup interface by adding support for the BizRule group type.

IAzApplicationGroups

Represents a collection of IAzApplicationGroup objects.

IAzApplications

Represents a collection of IAzApplication objects.

IAzAuthorizationStore

Defines the container that is the root of the authorization policy store.

IAzAuthorizationStore2

Inherits from the AzAuthorizationStore object and implements methods to create and open IAzApplication2 objects.

IAzAuthorizationStore3

Extends the IAzAuthorizationStore2 interface with methods that manage business rule (BizRule) support and caching.
IAzBizRuleContext

Contains information about a Business Rule (BizRule) operation.

IAzBizRuleInterfaces

Provides methods and properties used to manage a list of IDispatch interfaces that can be called by business rule (BizRule)
scripts.

IAzBizRuleParameters

Provides methods and properties used to manage a list of parameters that can be passed to business rule (BizRule) scripts.

IAzClientContext

Maintains the state that describes a particular client.

IAzClientContext2

Inherits from the IAzClientContext interface and implements new methods that manipulate the client context.

IAzClientContext3

Extends the IAzClientContext2 interface.

IAzNameResolver

Translates security identifiers (SIDs) into principal display names.

IAzObjectPicker

Displays a dialog box that allows users to select one or more principals from a list.

IAzOperation

Defines a low-level operation supported by an application.

IAzOperation2

Extends the IAzOperation with a method that returns the role assignments associated with the operation.

IAzOperations

Represents a collection of IAzOperation objects.

IAzPrincipalLocator

Locates and chooses ADAM principals in Authorization Manager.

IAzRole

Defines the set of operations that can be performed by a set of users within a scope.
 IAzRoleAssignment

Represents a role to which users and groups can be assigned.

IAzRoleAssignments

Represents a collection of IAzRoleAssignment objects.

IAzRoleDefinition

Represents one or more IAzRoleDefinition, IAzTask, and IAzOperation objects that specify a set of operations.

IAzRoleDefinitions

Represents a collection of IAzRoleDefinition objects.

IAzRoles

Represents a collection of IAzRole objects.

IAzScope

Defines a logical container of resources to which the application manages access.

IAzScope2

Extends the IAzScope interface to manage IAzRoleAssignment and IAzRoleDefinition objects.

IAzScopes

Represents a collection of IAzScope objects.

IAzTask

Describes a set of operations.

IAzTask2

Extends the IAzTask interface with a method that returns the role assignments associated with the task.

IAzTasks

Represents a collection of IAzTask objects.

Enumerations

AZ_PROP_CONSTANTS

Defines constants used by Authorization Manager.

 AZ_PROP_CONSTANTS enumeration (azroles.h)
7/2/2022 • 3 minutes to read • Edit Online

The AZ_PROP_CONSTANTS enumeration defines constants used by Authorization Manager. For information
about Authorization Manager, see Role-based Access Control.

Syntax
typedef enum tagAZ_PROP_CONSTANTS {
AZ_PROP_NAME = 1,
AZ_PROP_DESCRIPTION = 2,
AZ_PROP_WRITABLE = 3,
AZ_PROP_APPLICATION_DATA = 4,
AZ_PROP_CHILD_CREATE = 5,
AZ_MAX_APPLICATION_NAME_LENGTH = 512,
AZ_MAX_OPERATION_NAME_LENGTH = 64,
AZ_MAX_TASK_NAME_LENGTH = 64,
AZ_MAX_SCOPE_NAME_LENGTH = 65536,
AZ_MAX_GROUP_NAME_LENGTH = 64,
AZ_MAX_ROLE_NAME_LENGTH = 64,
AZ_MAX_NAME_LENGTH = 65536,
AZ_MAX_DESCRIPTION_LENGTH = 1024,
AZ_MAX_APPLICATION_DATA_LENGTH = 4096,
AZ_SUBMIT_FLAG_ABORT = 0x1,
AZ_SUBMIT_FLAG_FLUSH = 0x2,
AZ_MAX_POLICY_URL_LENGTH = 65536,
AZ_AZSTORE_FLAG_CREATE = 0x1,
AZ_AZSTORE_FLAG_MANAGE_STORE_ONLY = 0x2,
AZ_AZSTORE_FLAG_BATCH_UPDATE = 0x4,
AZ_AZSTORE_FLAG_AUDIT_IS_CRITICAL = 0x8,
AZ_AZSTORE_FORCE_APPLICATION_CLOSE = 0x10,
AZ_AZSTORE_NT6_FUNCTION_LEVEL = 0x20,
AZ_AZSTORE_FLAG_MANAGE_ONLY_PASSIVE_SUBMIT = 0x8000,
AZ_PROP_AZSTORE_DOMAIN_TIMEOUT = 100,
AZ_AZSTORE_DEFAULT_DOMAIN_TIMEOUT,
AZ_PROP_AZSTORE_SCRIPT_ENGINE_TIMEOUT = 101,
AZ_AZSTORE_MIN_DOMAIN_TIMEOUT = 500,
AZ_AZSTORE_MIN_SCRIPT_ENGINE_TIMEOUT,
AZ_AZSTORE_DEFAULT_SCRIPT_ENGINE_TIMEOUT,
AZ_PROP_AZSTORE_MAX_SCRIPT_ENGINES = 102,
AZ_AZSTORE_DEFAULT_MAX_SCRIPT_ENGINES = 120,
AZ_PROP_AZSTORE_MAJOR_VERSION = 103,
AZ_PROP_AZSTORE_MINOR_VERSION = 104,
AZ_PROP_AZSTORE_TARGET_MACHINE = 105,
AZ_PROP_AZTORE_IS_ADAM_INSTANCE = 106,
AZ_PROP_OPERATION_ID = 200,
AZ_PROP_TASK_OPERATIONS = 300,
AZ_PROP_TASK_BIZRULE = 301,
AZ_PROP_TASK_BIZRULE_LANGUAGE = 302,
AZ_PROP_TASK_TASKS = 303,
AZ_PROP_TASK_BIZRULE_IMPORTED_PATH = 304,
AZ_PROP_TASK_IS_ROLE_DEFINITION = 305,
AZ_MAX_TASK_BIZRULE_LENGTH = 65536,
AZ_MAX_TASK_BIZRULE_LANGUAGE_LENGTH = 64,
AZ_MAX_TASK_BIZRULE_IMPORTED_PATH_LENGTH = 512,
AZ_MAX_BIZRULE_STRING = 65536,
AZ_PROP_GROUP_TYPE = 400,
AZ_GROUPTYPE_LDAP_QUERY = 1,
AZ_GROUPTYPE_BASIC = 2,
AZ_GROUPTYPE_BIZRULE = 3,
AZ_PROP_GROUP_APP_MEMBERS = 401,
 AZ_PROP_GROUP_APP_NON_MEMBERS = 402,
AZ_PROP_GROUP_LDAP_QUERY = 403,
AZ_MAX_GROUP_LDAP_QUERY_LENGTH = 4096,
AZ_PROP_GROUP_MEMBERS = 404,
AZ_PROP_GROUP_NON_MEMBERS = 405,
AZ_PROP_GROUP_MEMBERS_NAME = 406,
AZ_PROP_GROUP_NON_MEMBERS_NAME = 407,
AZ_PROP_GROUP_BIZRULE = 408,
AZ_PROP_GROUP_BIZRULE_LANGUAGE = 409,
AZ_PROP_GROUP_BIZRULE_IMPORTED_PATH = 410,
AZ_MAX_GROUP_BIZRULE_LENGTH = 65536,
AZ_MAX_GROUP_BIZRULE_LANGUAGE_LENGTH = 64,
AZ_MAX_GROUP_BIZRULE_IMPORTED_PATH_LENGTH = 512,
AZ_PROP_ROLE_APP_MEMBERS = 500,
AZ_PROP_ROLE_MEMBERS = 501,
AZ_PROP_ROLE_OPERATIONS = 502,
AZ_PROP_ROLE_TASKS = 504,
AZ_PROP_ROLE_MEMBERS_NAME = 505,
AZ_PROP_SCOPE_BIZRULES_WRITABLE = 600,
AZ_PROP_SCOPE_CAN_BE_DELEGATED = 601,
AZ_PROP_CLIENT_CONTEXT_USER_DN = 700,
AZ_PROP_CLIENT_CONTEXT_USER_SAM_COMPAT = 701,
AZ_PROP_CLIENT_CONTEXT_USER_DISPLAY = 702,
AZ_PROP_CLIENT_CONTEXT_USER_GUID = 703,
AZ_PROP_CLIENT_CONTEXT_USER_CANONICAL = 704,
AZ_PROP_CLIENT_CONTEXT_USER_UPN = 705,
AZ_PROP_CLIENT_CONTEXT_USER_DNS_SAM_COMPAT = 707,
AZ_PROP_CLIENT_CONTEXT_ROLE_FOR_ACCESS_CHECK = 708,
AZ_PROP_CLIENT_CONTEXT_LDAP_QUERY_DN = 709,
AZ_PROP_APPLICATION_AUTHZ_INTERFACE_CLSID = 800,
AZ_PROP_APPLICATION_VERSION = 801,
AZ_MAX_APPLICATION_VERSION_LENGTH = 512,
AZ_PROP_APPLICATION_NAME = 802,
AZ_PROP_APPLICATION_BIZRULE_ENABLED = 803,
AZ_PROP_APPLY_STORE_SACL = 900,
AZ_PROP_GENERATE_AUDITS = 901,
AZ_PROP_POLICY_ADMINS = 902,
AZ_PROP_POLICY_READERS = 903,
AZ_PROP_DELEGATED_POLICY_USERS = 904,
AZ_PROP_POLICY_ADMINS_NAME = 905,
AZ_PROP_POLICY_READERS_NAME = 906,
AZ_PROP_DELEGATED_POLICY_USERS_NAME = 907,
AZ_CLIENT_CONTEXT_SKIP_GROUP = 1,
AZ_CLIENT_CONTEXT_SKIP_LDAP_QUERY = 1,
AZ_CLIENT_CONTEXT_GET_GROUP_RECURSIVE = 2,
AZ_CLIENT_CONTEXT_GET_GROUPS_STORE_LEVEL_ONLY = 2
} AZ_PROP_CONSTANTS;

Constants

AZ_PROP_NAME
Value: 1

AZ_PROP_DESCRIPTION
Value: 2

AZ_PROP_WRITABLE
Value: 3
 AZ_PROP_APPLICATION_DATA
Value: 4

AZ_PROP_CHILD_CREATE
Value: 5

AZ_MAX_APPLICATION_NAME_LENGTH
Value: 512

AZ_MAX_OPERATION_NAME_LENGTH
Value: 64

AZ_MAX_TASK_NAME_LENGTH
Value: 64

AZ_MAX_SCOPE_NAME_LENGTH
Value: 65536

AZ_MAX_GROUP_NAME_LENGTH
Value: 64

AZ_MAX_ROLE_NAME_LENGTH
Value: 64

AZ_MAX_NAME_LENGTH
Value: 65536

AZ_MAX_DESCRIPTION_LENGTH
Value: 1024

AZ_MAX_APPLICATION_DATA_LENGTH
Value: 4096

AZ_SUBMIT_FLAG_ABORT
Value: 0x1

AZ_SUBMIT_FLAG_FLUSH
Value: 0x2

AZ_MAX_POLICY_URL_LENGTH
Value: 65536

AZ_AZSTORE_FLAG_CREATE
Value: 0x1

AZ_AZSTORE_FLAG_MANAGE_STORE_ONLY
Value: 0x2

AZ_AZSTORE_FLAG_BATCH_UPDATE
Value: 0x4
AZ_AZSTORE_FLAG_AUDIT_IS_CRITICAL
Value: 0x8

AZ_AZSTORE_FORCE_APPLICATION_CLOSE
Value: 0x10

AZ_AZSTORE_NT6_FUNCTION_LEVEL
Value: 0x20

AZ_AZSTORE_FLAG_MANAGE_ONLY_PASSIVE_SUBMIT
Value: 0x8000

AZ_PROP_AZSTORE_DOMAIN_TIMEOUT
Value: 100

AZ_AZSTORE_DEFAULT_DOMAIN_TIMEOUT

AZ_PROP_AZSTORE_SCRIPT_ENGINE_TIMEOUT
Value: 101

AZ_AZSTORE_MIN_DOMAIN_TIMEOUT
Value: 500

AZ_AZSTORE_MIN_SCRIPT_ENGINE_TIMEOUT

AZ_AZSTORE_DEFAULT_SCRIPT_ENGINE_TIMEOUT

AZ_PROP_AZSTORE_MAX_SCRIPT_ENGINES
Value: 102

AZ_AZSTORE_DEFAULT_MAX_SCRIPT_ENGINES
Value: 120

AZ_PROP_AZSTORE_MAJOR_VERSION
Value: 103

AZ_PROP_AZSTORE_MINOR_VERSION
Value: 104

AZ_PROP_AZSTORE_TARGET_MACHINE
Value: 105

AZ_PROP_AZTORE_IS_ADAM_INSTANCE
Value: 106

AZ_PROP_OPERATION_ID
Value: 200

AZ_PROP_TASK_OPERATIONS
Value: 300
 AZ_PROP_TASK_BIZRULE
Value: 301

AZ_PROP_TASK_BIZRULE_LANGUAGE
Value: 302

AZ_PROP_TASK_TASKS
Value: 303

AZ_PROP_TASK_BIZRULE_IMPORTED_PATH
Value: 304

AZ_PROP_TASK_IS_ROLE_DEFINITION
Value: 305

AZ_MAX_TASK_BIZRULE_LENGTH
Value: 65536

AZ_MAX_TASK_BIZRULE_LANGUAGE_LENGTH
Value: 64

AZ_MAX_TASK_BIZRULE_IMPORTED_PATH_LENGTH
Value: 512

AZ_MAX_BIZRULE_STRING
Value: 65536

AZ_PROP_GROUP_TYPE
Value: 400

AZ_GROUPTYPE_LDAP_QUERY
Value: 1

AZ_GROUPTYPE_BASIC
Value: 2

AZ_GROUPTYPE_BIZRULE
Value: 3

AZ_PROP_GROUP_APP_MEMBERS
Value: 401

AZ_PROP_GROUP_APP_NON_MEMBERS
Value: 402

AZ_PROP_GROUP_LDAP_QUERY
Value: 403

AZ_MAX_GROUP_LDAP_QUERY_LENGTH
Value: 4096
AZ_PROP_GROUP_MEMBERS
Value: 404

AZ_PROP_GROUP_NON_MEMBERS
Value: 405

AZ_PROP_GROUP_MEMBERS_NAME
Value: 406

AZ_PROP_GROUP_NON_MEMBERS_NAME
Value: 407

AZ_PROP_GROUP_BIZRULE
Value: 408

AZ_PROP_GROUP_BIZRULE_LANGUAGE
Value: 409

AZ_PROP_GROUP_BIZRULE_IMPORTED_PATH
Value: 410

AZ_MAX_GROUP_BIZRULE_LENGTH
Value: 65536

AZ_MAX_GROUP_BIZRULE_LANGUAGE_LENGTH
Value: 64

AZ_MAX_GROUP_BIZRULE_IMPORTED_PATH_LENGTH
Value: 512

AZ_PROP_ROLE_APP_MEMBERS
Value: 500

AZ_PROP_ROLE_MEMBERS
Value: 501

AZ_PROP_ROLE_OPERATIONS
Value: 502

AZ_PROP_ROLE_TASKS
Value: 504

AZ_PROP_ROLE_MEMBERS_NAME
Value: 505

AZ_PROP_SCOPE_BIZRULES_WRITABLE
Value: 600

AZ_PROP_SCOPE_CAN_BE_DELEGATED
Value: 601
AZ_PROP_CLIENT_CONTEXT_USER_DN
Value: 700

AZ_PROP_CLIENT_CONTEXT_USER_SAM_COMPAT
Value: 701

AZ_PROP_CLIENT_CONTEXT_USER_DISPLAY
Value: 702

AZ_PROP_CLIENT_CONTEXT_USER_GUID
Value: 703

AZ_PROP_CLIENT_CONTEXT_USER_CANONICAL
Value: 704

AZ_PROP_CLIENT_CONTEXT_USER_UPN
Value: 705

AZ_PROP_CLIENT_CONTEXT_USER_DNS_SAM_COMPAT
Value: 707

AZ_PROP_CLIENT_CONTEXT_ROLE_FOR_ACCESS_CHECK
Value: 708

AZ_PROP_CLIENT_CONTEXT_LDAP_QUERY_DN
Value: 709

AZ_PROP_APPLICATION_AUTHZ_INTERFACE_CLSID
Value: 800

AZ_PROP_APPLICATION_VERSION
Value: 801

AZ_MAX_APPLICATION_VERSION_LENGTH
Value: 512

AZ_PROP_APPLICATION_NAME
Value: 802

AZ_PROP_APPLICATION_BIZRULE_ENABLED
Value: 803

AZ_PROP_APPLY_STORE_SACL
Value: 900

AZ_PROP_GENERATE_AUDITS
Value: 901

AZ_PROP_POLICY_ADMINS
Value: 902
 AZ_PROP_POLICY_READERS
Value: 903

AZ_PROP_DELEGATED_POLICY_USERS
Value: 904

AZ_PROP_POLICY_ADMINS_NAME
Value: 905

AZ_PROP_POLICY_READERS_NAME
Value: 906

AZ_PROP_DELEGATED_POLICY_USERS_NAME
Value: 907

AZ_CLIENT_CONTEXT_SKIP_GROUP
Value: 1

AZ_CLIENT_CONTEXT_SKIP_LDAP_QUERY
Value: 1

AZ_CLIENT_CONTEXT_GET_GROUP_RECURSIVE
Value: 2

AZ_CLIENT_CONTEXT_GET_GROUPS_STORE_LEVEL_ONLY
Value: 2

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Header azroles.h

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzApplication interface (azroles.h)
7/2/2022 • 5 minutes to read • Edit Online

The IAzApplication interface defines an installed instance of an application. An IAzApplication object is

created when an application is installed.

Inheritance
The IAzApplication interface inherits from the IDispatch interface. IAzApplication also has these types of
members:

Methods
The IAzApplication interface has these methods.

IAzApplication::AddDelegatedPolicyUser

Adds the specified security identifier (SID) in text form to the list of principals that act as delegated policy users.

IAzApplication::AddDelegatedPolicyUserName

Adds the specified account name to the list of principals that act as delegated policy users.

IAzApplication::AddPolicyAdministrator

Adds the specified security identifier (SID) in text form to the list of principals that act as policy administrators.

IAzApplication::AddPolicyAdministratorName

Adds the specified account name to the list of principals that act as policy administrators.

IAzApplication::AddPolicyReader

Adds the specified security identifier (SID) in text form to the list of principals that act as policy readers.

IAzApplication::AddPolicyReaderName

Adds the specified account name to the list of principals that act as policy readers.

IAzApplication::AddPropertyItem

Adds the specified principal to the specified list of principals.

IAzApplication::CreateApplicationGroup

Creates an IAzApplicationGroup object with the specified name.

IAzApplication::CreateOperation

Creates an IAzOperation object with the specified name.

IAzApplication::CreateRole

Creates an IAzRole object with the specified name.

IAzApplication::CreateScope

Creates an IAzScope object with the specified name.

IAzApplication::CreateTask

Creates an IAzTask object with the specified name.

IAzApplication::DeleteApplicationGroup

Removes the IAzApplicationGroup object with the specified name from the IAzApplication object.

IAzApplication::DeleteDelegatedPolicyUser

The IAzApplication::DeleteDelegatedPolicyUser method removes the specified security identifier in text form from the list of
principals that act as delegated policy users.

IAzApplication::DeleteDelegatedPolicyUserName

Removes the specified account name from the list of principals that act as delegated policy users.

IAzApplication::DeleteOperation

Removes the IAzOperation object with the specified name from the IAzApplication object.

IAzApplication::DeletePolicyAdministrator

The DeletePolicyAdministrator method of IAzApplication removes the specified security identifier in text form from the list of
principals that act as policy administrators.

IAzApplication::DeletePolicyAdministratorName

Removes the specified account name from the list of principals that act as policy administrators.

IAzApplication::DeletePolicyReader

The DeletePolicyReader method of IAzApplication removes the specified security identifier in text form from the list of
principals that act as policy readers.

IAzApplication::DeletePolicyReaderName

Removes the specified account name from the list of principals that act as policy readers.

IAzApplication::DeletePropertyItem

Removes the specified principal from the specified list of principals.

IAzApplication::DeleteRole

Removes the IAzRole object with the specified name from the IAzApplication object.
IAzApplication::DeleteScope

Removes the IAzScope object with the specified name from the IAzApplication object.

IAzApplication::DeleteTask

Removes the IAzTask object with the specified name from the IAzApplication object.

IAzApplication::get_ApplicationData

Sets or retrieves an opaque field that can be used by the application to store information.

IAzApplication::get_ApplicationGroups

Retrieves an IAzApplicationGroups object that is used to enumerate IAzApplicationGroup objects from the policy data.

IAzApplication::get_ApplyStoreSacl

Sets or retrieves a value that indicates whether policy audits should be generated when the authorization store is modified.

IAzApplication::get_AuthzInterfaceClsid

Sets or retrieves the class identifier (CLSID) of the interface that the user interface (UI) uses to perform application-specific
operations.

IAzApplication::get_DelegatedPolicyUsers

Retrieves the security identifiers (SIDs), in text form, of principals that act as delegated policy users.

IAzApplication::get_DelegatedPolicyUsersName

The DelegatedPolicyUsersName property of IAzApplication retrieves the account names of principals that act as delegated
policy users.

IAzApplication::get_Description

Sets or retrieves a comment that describes the application.

IAzApplication::get_GenerateAudits

The GenerateAudits property of IAzApplication sets or retrieves a value that indicates whether run-time audits should be
generated.

IAzApplication::get_Name

Sets or retrieves the name of the application.

IAzApplication::get_Operations

Retrieves an IAzOperations object that is used to enumerate IAzOperation objects from the policy data.

IAzApplication::get_PolicyAdministrators

Retrieves the security identifiers (SIDs), in text form, of principals that act as policy administrators.
IAzApplication::get_PolicyAdministratorsName

The IAzApplication::PolicyAdministratorsName property retrieves the account names of principals that act as policy
administrators.

IAzApplication::get_PolicyReaders

Retrieves the security identifiers (SIDs), in text form, of principals that act as policy readers.

IAzApplication::get_PolicyReadersName

The IAzApplication::PolicyReadersName property retrieves the account names of principals that act as policy readers.

IAzApplication::get_Roles

The Roles property of IAzApplication retrieves an IAzRoles object that is used to enumerate IAzRole objects from the policy
data.

IAzApplication::get_Scopes

Retrieves an IAzScopes object that is used to enumerate IAzScope objects from the policy data.

IAzApplication::get_Tasks

The Tasks property of IAzApplication retrieves an IAzTasks object that is used to enumerate IAzTask objects from the policy
data.

IAzApplication::get_Version

Sets or retrieves the version of the application.

IAzApplication::get_Writable

Retrieves a value that indicates whether the object can be modified by the user context that initialized it.

IAzApplication::GetProperty

Returns the IAzApplication object property with the specified property ID.

IAzApplication::InitializeClientContextFromName

Gets an IAzClientContext object pointer from the client identity as a (domain name, client name) pair.

IAzApplication::InitializeClientContextFromStringSid

Gets an IAzClientContext object pointer from the specified security identifier (SID) in text form.

IAzApplication::InitializeClientContextFromToken

Gets an IAzClientContext object pointer from the specified client token.

IAzApplication::OpenApplicationGroup

Opens an IAzApplicationGroup object by specifying its name.

 IAzApplication::OpenOperation

Opens an IAzOperation object with the specified name.

IAzApplication::OpenRole

Opens an IAzRole object with the specified name.

IAzApplication::OpenScope

Opens an IAzScope object with the specified name.

IAzApplication::OpenTask

Opens an IAzTask object with the specified name.

IAzApplication::put_ApplicationData

Sets or retrieves an opaque field that can be used by the application to store information.

IAzApplication::put_ApplyStoreSacl

Sets or retrieves a value that indicates whether policy audits should be generated when the authorization store is modified.

IAzApplication::put_AuthzInterfaceClsid

Sets or retrieves the class identifier (CLSID) of the interface that the user interface (UI) uses to perform application-specific
operations.

IAzApplication::put_Description

Sets or retrieves a comment that describes the application.

IAzApplication::put_GenerateAudits

The GenerateAudits property of IAzApplication sets or retrieves a value that indicates whether run-time audits should be
generated.

IAzApplication::put_Name

Sets or retrieves the name of the application.

IAzApplication::put_Version

Sets or retrieves the version of the application.

IAzApplication::SetProperty

Sets the specified value to the IAzApplication object property with the specified property ID.

IAzApplication::Submit

Persists changes made to the IAzApplication object.

Remarks
The IAzApplication object is a container in which all authorization policies that apply to an instance of an
application reside.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP

See also
Allowing Anonymous Access
IDispatch
 IAzApplication::AddDelegatedPolicyUser method
(azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The AddDelegatedPolicyUser method adds the specified security identifier (SID) in text form to the list of
principals that act as delegated policy users.

Syntax
HRESULT AddDelegatedPolicyUser(
[in] BSTR bstrDelegatedPolicyUser,
[in, optional] VARIANT varReserved
);

Parameters
[in] bstrDelegatedPolicyUser

Text form of the SID to add to the list of delegated policy users.
[in, optional] varReserved

Reserved for future use. This parameter can be any of the following values:
varReserved.vt == VT_ERROR and varReserved.scode == DISP_E_PARAMNOTFOUND
varReserved.vt == VT_EMPTY
varReserved.vt == VT_NULL
varReserved.vt == VT_I4 and varReserved.lVal == 0
varReserved.vt == VT_I2 and varReserved.iVal == 0

Return value
C++
If the method succeeds, the method returns S_OK.
An attempt to call this method on an XML store will return E_INVALIDARG.
Any other HRESULT value indicates that the operation failed.
VB
If the method succeeds, the method returns S_OK.
An attempt to call this method on an XML store will return E_INVALIDARG.
Any other HRESULT value indicates that the operation failed.

Remarks
Delegated policy users are principals that are allowed to read the subset of the policy data that the policy
administrator of an IAzApplication object uses to administer the delegated object.
 Note Delegated policy users are not supported for XML stores.

To view the list of delegated policy users, use the DelegatedPolicyUsers property.
You must call the Submit method to persist any changes made by this method.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzApplication::AddDelegatedPolicyUserName
method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The AddDelegatedPolicyUserName method adds the specified account name to the list of principals that act
as delegated policy users.

Syntax
HRESULT AddDelegatedPolicyUserName(
[in] BSTR bstrDelegatedPolicyUser,
[in, optional] VARIANT varReserved
);

Parameters
[in] bstrDelegatedPolicyUser

Account name to add to the list of delegated policy users. The account name must be in user principal name
(UPN) format (for example, "someone@example.com"). The LookupAccountName function is called to retrieve
the domain.
[in, optional] varReserved

Reserved for future use.

Return value
If the method succeeds, the method returns S_OK.
An attempt to call this method on an XML store will return E_INVALIDARG.
Any other HRESULT value indicates that the operation failed.

Remarks
Delegated policy users are principals that are allowed to read the subset of the policy data that the policy
administrator of an IAzApplication object uses to administer the delegated object.

Note Delegated policy users are not supported for XML stores.

To view the list of delegated policy users in account name format, use the DelegatedPolicyUsersName property.
You must call the Submit method to persist any changes made by this method.

Requirements
Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzApplication::AddPolicyAdministrator method
(azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The AddPolicyAdministrator method adds the specified security identifier (SID) in text form to the list of
principals that act as policy administrators.

Syntax
HRESULT AddPolicyAdministrator(
[in] BSTR bstrAdmin,
[in, optional] VARIANT varReserved
);

Parameters
[in] bstrAdmin

Text form of the SID to add to the list of policy administrators.

[in, optional] varReserved

Reserved for future use.

Return value
None

Remarks
Policy administrators for an object can perform the following tasks:
Read the object
Write attributes to the object
Read attributes of child objects of the object
Write attributes to child objects of the object
Delete the object
Delete child objects of the object
Create child objects of the object
To view the list of policy administrators, use the PolicyAdministrators property.
You must call the Submit method to persist any changes made by this method.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzApplication::AddPolicyAdministratorName
method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The AddPolicyAdministratorName method adds the specified account name to the list of principals that act
as policy administrators.

Syntax
HRESULT AddPolicyAdministratorName(
[in] BSTR bstrAdmin,
[in, optional] VARIANT varReserved
);

Parameters
[in] bstrAdmin

Account name to add to the list of policy administrators. The account name must be in user principal name
(UPN) format (for example, "someone@example.com"). The LookupAccountName function is called to retrieve
the domain.
[in, optional] varReserved

Reserved for future use.

Return value
If the method succeeds, the method returns S_OK.
Any other HRESULT value indicates that the operation failed.

Remarks
Policy administrators for an object can perform the following tasks:
Read the object
Write attributes to the object
Read attributes of child objects of the object
Write attributes to child objects of the object
Delete the object
Delete child objects of the object
Create child objects of the object
To view the list of policy administrators in account name format, use the PolicyAdministratorsName property.
You must call the Submit method to persist any changes made by this method.

Requirements
Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzApplication::AddPolicyReader method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The AddPolicyReader method adds the specified security identifier (SID) in text form to the list of principals
that act as policy readers.

Syntax
HRESULT AddPolicyReader(
[in] BSTR bstrReader,
[in, optional] VARIANT varReserved
);

Parameters
[in] bstrReader

Text form of the SID to add to the list of policy readers.

[in, optional] varReserved

Reserved for future use.

Return value
None

Remarks
Policy readers for an object can read attributes for the object and for child objects of the object. Readers can also
use the policy; for example, readers can call the AccessCheck method. Readers cannot modify the object or its
child objects.
To view the list of policy readers, use the PolicyReaders property.
You must call the Submit method to persist any changes made by this method.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib
DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzApplication::AddPolicyReaderName method
(azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The AddPolicyReaderName method adds the specified account name to the list of principals that act as policy
readers.

Syntax
HRESULT AddPolicyReaderName(
[in] BSTR bstrReader,
[in, optional] VARIANT varReserved
);

Parameters
[in] bstrReader

Account name to add to the list of policy readers. The account name must be in user principal name (UPN)
format (for example, "someone@example.com"). The LookupAccountName function is called to retrieve the
domain.
[in, optional] varReserved

Reserved for future use.

Return value
If the method succeeds, the method returns S_OK.
Any other HRESULT value indicates that the operation failed.

Remarks
Policy readers for an object can read attributes for the object and for child objects of the object. Readers can also
use the policy; for example, readers can call the AccessCheck method. Readers cannot modify the object or its
child objects.
To view the list of policy readers in account name format, use the PolicyReadersName property.
You must call the Submit method to persist any changes made by this method.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]
Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzApplication::AddPropertyItem method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The AddProper tyItem method adds the specified principal to the specified list of principals.

Syntax
HRESULT AddPropertyItem(
[in] LONG lPropId,
[in] VARIANT varProp,
[in, optional] VARIANT varReserved
);

Parameters
[in] lPropId

Property ID of the list of principals to which to add the principal specified by the varProp parameter. The
following table shows the possible values.

VA L UE M EA N IN G

Can also be added using the AddPolicyAdministrator

AZ_PROP_POLICY_ADMINS method

Can also be added using the AddPolicyAdministratorName

AZ_PROP_POLICY_ADMINS_NAME method

Can also be added using the AddPolicyReader method

AZ_PROP_POLICY_READERS

Can also be added using the AddPolicyReaderName method

AZ_PROP_POLICY_READERS_NAME

Can also be added using the AddDelegatedPolicyUser

AZ_PROP_DELEGATED_POLICY_USERS method

Can also be added using the AddDelegatedPolicyUserName

AZ_PROP_DELEGATED_POLICY_USERS_NAME method

[in] varProp

Principal to add to the list of principals specified by the lPropId parameter.

The variant must be a BSTR variant.
If AZ_PROP_POLICY_ADMINS_NAME, AZ_PROP_POLICY_READERS_NAME, or
AZ_PROP_DELEGATED_POLICY_USERS_NAME is specified for the lPropId parameter, the string is the account
name of the account to add to the list. The account name must be in user principal name (UPN) format (for
example, "someone@example.com").
[in, optional] varReserved

Reserved for future use.

Return value
If the method succeeds, the method returns S_OK.
Any other HRESULT value indicates that the operation failed.

Remarks
You must call the Submit method to persist any changes made by this method.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzApplication::CreateApplicationGroup method
(azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The CreateApplicationGroup method creates an IAzApplicationGroup object with the specified name.

Syntax
HRESULT CreateApplicationGroup(
[in] BSTR bstrGroupName,
[in, optional] VARIANT varReserved,
[out] IAzApplicationGroup **ppGroup
);

Parameters
[in] bstrGroupName

Name for the new IAzApplicationGroup object.

[in, optional] varReserved

Reserved for future use.

[out] ppGroup

A pointer to a pointer to the created IAzApplicationGroup object.

Return value
If the method succeeds, the method returns S_OK.
Any other HRESULT value indicates that the operation failed.

Remarks
You must call the IAzApplicationGroup::Submit method to persist any changes made to the returned object.
The returned IAzApplicationGroup object is an immediate child object of the IAzApplication object.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzApplication::CreateOperation method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The CreateOperation method creates an IAzOperation object with the specified name.

Syntax
HRESULT CreateOperation(
[in] BSTR bstrOperationName,
[in, optional] VARIANT varReserved,
[out] IAzOperation **ppOperation
);

Parameters
[in] bstrOperationName

Name for the new IAzOperation object.

[in, optional] varReserved

Reserved for future use.

[out] ppOperation

A pointer to a pointer to the created IAzOperation object.

Return value
If the method succeeds, the method returns S_OK.
Any other HRESULT value indicates that the operation failed.

Remarks
You must call the IAzOperation::Submit method to persist any changes made to the returned object.
The returned IAzOperation object is an immediate child object of the IAzApplication object.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h
Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzApplication::CreateRole method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The CreateRole method creates an IAzRole object with the specified name.

Syntax
HRESULT CreateRole(
[in] BSTR bstrRoleName,
[in, optional] VARIANT varReserved,
[out] IAzRole **ppRole
);

Parameters
[in] bstrRoleName

Name for the new IAzRole object.

[in, optional] varReserved

Reserved for future use.

[out] ppRole

A pointer to a pointer to the created IAzRole object.

Return value
If the method succeeds, the method returns S_OK.
Any other HRESULT value indicates that the operation failed.

Remarks
You must call the IAzRole::Submit method to persist any changes made to the returned object.
The returned IAzRole object is an immediate child object of the IAzApplication object.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h
Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzApplication::CreateScope method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The CreateScope method creates an IAzScope object with the specified name.

Syntax
HRESULT CreateScope(
[in] BSTR bstrScopeName,
[in, optional] VARIANT varReserved,
[out] IAzScope **ppScope
);

Parameters
[in] bstrScopeName

Name for the new IAzScope object.

[in, optional] varReserved

Reserved for future use.

[out] ppScope

A pointer to a pointer to the created IAzScope object.

Return value
If the method succeeds, the method returns S_OK.
Any other HRESULT value indicates that the operation failed.

Remarks
You must call the IAzScope::Submit method to persist any changes made to the returned object.
The returned IAzScope object is an immediate child object of the IAzApplication object.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h
Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzApplication::CreateTask method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The CreateTask method creates an IAzTask object with the specified name.

Syntax
HRESULT CreateTask(
[in] BSTR bstrTaskName,
[in, optional] VARIANT varReserved,
[out] IAzTask **ppTask
);

Parameters
[in] bstrTaskName

Name for the new IAzTask object.

[in, optional] varReserved

Reserved for future use.

[out] ppTask

A pointer to a pointer to the created IAzTask object.

Return value
If the method succeeds, the method returns S_OK.
Any other HRESULT value indicates that the operation failed.

Remarks
You must call the IAzTask::Submit method to persist any changes made to the returned object.
The returned IAzTask object is an immediate child object of the IAzApplication object.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h
Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzApplication::DeleteApplicationGroup method
(azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The DeleteApplicationGroup method removes the IAzApplicationGroup object with the specified name from
the IAzApplication object.

Syntax
HRESULT DeleteApplicationGroup(
[in] BSTR bstrGroupName,
[in, optional] VARIANT varReserved
);

Parameters
[in] bstrGroupName

Name of the IAzApplicationGroup object to delete.

[in, optional] varReserved

Reserved for future use.

Return value
None

Remarks
If there are any IAzApplicationGroup references to an IAzApplicationGroup object that has been deleted from
the cache, the IAzApplicationGroup object can no longer be used. In C++, you must release references to
deleted IAzApplicationGroup objects by calling the IUnknown::Release method. In Visual Basic, references to
deleted objects are automatically released.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib
DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzApplication::DeleteDelegatedPolicyUser method
(azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The DeleteDelegatedPolicyUser method removes the specified security identifier (SID) in text form from the
list of principals that act as delegated policy users.

Syntax
HRESULT DeleteDelegatedPolicyUser(
[in] BSTR bstrDelegatedPolicyUser,
[in, optional] VARIANT varReserved
);

Parameters
[in] bstrDelegatedPolicyUser

Text form of the SID to remove from the list of delegated policy users.
[in, optional] varReserved

Reserved for future use.

Return value
None

Remarks
Delegated policy users are principals that are allowed to read the subset of the policy data that the policy
administrator of an IAzApplication object uses to administer the delegated object.

Note Delegated policy users are not supported for XML stores.

To view the list of delegated policy users, use the DelegatedPolicyUsers property.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzApplication::DeleteDelegatedPolicyUserName
method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The DeleteDelegatedPolicyUserName method removes the specified account name from the list of
principals that act as delegated policy users.

Syntax
HRESULT DeleteDelegatedPolicyUserName(
[in] BSTR bstrDelegatedPolicyUser,
[in, optional] VARIANT varReserved
);

Parameters
[in] bstrDelegatedPolicyUser

The account name to remove from the list of delegated policy users. The account name must be in user principal
name (UPN) format (for example, "someone@example.com"). The LookupAccountName function is called to
retrieve the domain.
[in, optional] varReserved

Reserved for future use.

Return value
If the method succeeds, the method returns S_OK.
Any other HRESULT value indicates that the operation failed. An attempt to call this method on an XML store
will return E_INVALIDARG.

Remarks
Delegated policy users are principals that are allowed to read the subset of the policy data that the policy
administrator of an IAzApplication object uses to administer the delegated object.

Note Delegated policy users are not supported for XML stores.

To view the list of delegated policy users in account name format, use the DelegatedPolicyUsersName property.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzApplication::DeleteOperation method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The DeleteOperation method removes the IAzOperation object with the specified name from the
IAzApplication object.

Syntax
HRESULT DeleteOperation(
[in] BSTR bstrOperationName,
[in, optional] VARIANT varReserved
);

Parameters
[in] bstrOperationName

Name of the IAzOperation object to delete.

[in, optional] varReserved

Reserved for future use.

Return value
None

Remarks
If there are any IAzOperation references to an IAzOperation object that has been deleted from the cache, the
IAzOperation object can no longer be used. In C++, you must release references to deleted IAzOperation
objects by calling the IUnknown::Release method. In Visual Basic, references to deleted objects are automatically
released.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll
Redistributable Windows Server 2003 Administration Tools Pack on
Windows XP
 IAzApplication::DeletePolicyAdministrator method
(azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The DeletePolicyAdministrator method removes the specified security identifier (SID) in text form from the
list of principals that act as policy administrators.

Syntax
HRESULT DeletePolicyAdministrator(
[in] BSTR bstrAdmin,
[in, optional] VARIANT varReserved
);

Parameters
[in] bstrAdmin

Text form of the SID to remove from the list of policy administrators.
[in, optional] varReserved

Reserved for future use.

Return value
None

Remarks
Policy administrators for an object can perform the following tasks:
Read the object
Write attributes to the object
Read attributes of child objects of the object
Write attributes to child objects of the object
Delete the object
Delete child objects of the object
Create child objects of the object
To view the list of policy administrators, use the PolicyAdministrators property.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]
Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzApplication::DeletePolicyAdministratorName
method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The DeletePolicyAdministratorName method removes the specified account name from the list of principals
that act as policy administrators.

Syntax
HRESULT DeletePolicyAdministratorName(
[in] BSTR bstrAdmin,
[in, optional] VARIANT varReserved
);

Parameters
[in] bstrAdmin

Account name to remove from the list of policy administrators. The account name can be in either user principal
name (UPN) format (for example, "someone@example.com") or in the format of "ExampleDomain\UserName". If
the domain is not in the "ExampleDomain\UserName" format, the LookupAccountName function is called to
retrieve the domain.
[in, optional] varReserved

Reserved for future use.

Return value
If the method succeeds, the method returns S_OK.
Any other HRESULT value indicates that the operation failed.

Remarks
Policy administrators for an object can perform the following tasks:
Read the object
Write attributes to the object
Read attributes of child objects of the object
Write attributes to child objects of the object
Delete the object
Delete child objects of the object
Create child objects of the object
To view the list of policy administrators in account name format, use the PolicyAdministratorsName property.

Requirements
Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzApplication::DeletePolicyReader method
(azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The DeletePolicyReader method removes the specified security identifier (SID) in text form from the list of
principals that act as policy readers.

Syntax
HRESULT DeletePolicyReader(
[in] BSTR bstrReader,
[in, optional] VARIANT varReserved
);

Parameters
[in] bstrReader

Text form of the SID to remove from the list of policy readers.
[in, optional] varReserved

Reserved for future use.

Return value
None

Remarks
Policy readers for an object can read attributes for the object and for child objects of the object. Readers can also
use the policy; for example, readers can call the AccessCheck method. Readers cannot modify the object or its
child objects.
To view the list of policy readers, use the PolicyReaders property.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib
DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzApplication::DeletePolicyReaderName method
(azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The DeletePolicyReaderName method removes the specified account name from the list of principals that act
as policy readers.

Syntax
HRESULT DeletePolicyReaderName(
[in] BSTR bstrReader,
[in, optional] VARIANT varReserved
);

Parameters
[in] bstrReader

The account name to remove from the list of policy readers. The account name can be in either user principal
name (UPN) format (for example, "someone@example.com") or in the format of "ExampleDomain\UserName". If
the domain is not in the "ExampleDomain\UserName" format, the LookupAccountName function is called to
retrieve the domain.
[in, optional] varReserved

Reserved for future use.

Return value
If the method succeeds, the method returns S_OK.
Any other HRESULT value indicates that the operation failed.

Remarks
Policy readers for an object can read attributes for the object and for child objects of the object. Readers can also
use the policy; for example, readers can call the AccessCheck method. Readers cannot modify the object or its
child objects.
To view the list of policy readers in account name format, use the PolicyReadersName property.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]
Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzApplication::DeletePropertyItem method
(azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The DeleteProper tyItem method removes the specified principal from the specified list of principals.

Syntax
HRESULT DeletePropertyItem(
[in] LONG lPropId,
[in] VARIANT varProp,
[in, optional] VARIANT varReserved
);

Parameters
[in] lPropId

Property ID of the list of principals from which to remove the principal specified by the varProp parameter. The
following table shows the possible values.

VA L UE M EA N IN G

Can also be removed using the DeletePolicyAdministrator

AZ_PROP_POLICY_ADMINS method

Can also be removed using the

AZ_PROP_POLICY_ADMINS_NAME DeletePolicyAdministratorName method

Can also be removed using the DeletePolicyReader method

AZ_PROP_POLICY_READERS

Can also be removed using the DeletePolicyReaderName

AZ_PROP_POLICY_READERS_NAME method

Can also be removed using the DeleteDelegatedPolicyUser

AZ_PROP_DELEGATED_POLICY_USERS method

Can also be removed using the

AZ_PROP_DELEGATED_POLICY_USERS_NAME DeleteDelegatedPolicyUserName method

[in] varProp

Principal to remove from the list of principals specified by the lPropId parameter.
The variant must be a BSTR variant.
If AZ_PROP_POLICY_ADMINS, AZ_PROP_POLICY_READERS, or AZ_PROP_DELEGATED_POLICY_USERS is
specified for the lPropId parameter, the string is the text form of the security identifier (SID) of the Windows
account to remove from the list. If AZ_PROP_POLICY_ADMINS_NAME, AZ_PROP_POLICY_READERS_NAME, or
AZ_PROP_DELEGATED_POLICY_USERS_NAME is specified for the lPropId parameter, the string is the account
name of the account to remove from the list. The account name can be in either user principal name (UPN)
format (for example, "someone@example.com") or in the format of "ExampleDomain\UserName".
[in, optional] varReserved

Reserved for future use.

Return value
If the method succeeds, the method returns S_OK.
Any other HRESULT value indicates that the operation failed.

Remarks
You must call the Submit method to persist any changes made by this method.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzApplication::DeleteRole method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The DeleteRole method removes the IAzRole object with the specified name from the IAzApplication object.

Syntax
HRESULT DeleteRole(
[in] BSTR bstrRoleName,
[in, optional] VARIANT varReserved
);

Parameters
[in] bstrRoleName

Name of the IAzRole object to delete.

[in, optional] varReserved

Reserved for future use.

Return value
None

Remarks
If there are any IAzRole references to an IAzRole object that has been deleted from the cache, the IAzRole
object can no longer be used. In C++, you must release references to deleted IAzRole objects by calling the
IUnknown::Release method. In Visual Basic, references to deleted objects are automatically released.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzApplication::DeleteScope method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The DeleteScope method removes the IAzScope object with the specified name from the IAzApplication object.

Syntax
HRESULT DeleteScope(
[in] BSTR bstrScopeName,
[in, optional] VARIANT varReserved
);

Parameters
[in] bstrScopeName

Name of the IAzScope object to delete.

[in, optional] varReserved

Reserved for future use.

Return value
None

Remarks
If there are any IAzScope references to an IAzScope object that has been deleted from the cache, the IAzScope
object can no longer be used. In C++, you must release references to deleted IAzScope objects by calling the
IUnknown::Release method. In Visual Basic, references to deleted objects are automatically released.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzApplication::DeleteTask method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The DeleteTask method removes the IAzTask object with the specified name from the IAzApplication object.

Syntax
HRESULT DeleteTask(
[in] BSTR bstrTaskName,
[in, optional] VARIANT varReserved
);

Parameters
[in] bstrTaskName

Name of the IAzTask object to delete.

[in, optional] varReserved

Reserved for future use.

Return value
None

Remarks
If there are any IAzTask references to an IAzTask object that has been deleted from the cache, the IAzTask object
can no longer be used. In C++, you must release references to deleted IAzTask objects by calling the
IUnknown::Release method. In Visual Basic, references to deleted objects are automatically released.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzApplication::get_ApplicationData method
(azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The ApplicationData property sets or retrieves an opaque field that can be used by the application to store
information.
This property is read/write.

Syntax
HRESULT get_ApplicationData(
BSTR *pbstrApplicationData
);

Parameters
pbstrApplicationData

Return value
None

Remarks
Impor tant Policy administrators can read from and write to this property. Applications should not store data in the
ApplicationData property that should not be available to the policy administrator.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll
Redistributable Windows Server 2003 Administration Tools Pack on
Windows XP
 IAzApplication::get_ApplicationGroups method
(azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The ApplicationGroups property retrieves an IAzApplicationGroups object that is used to enumerate

IAzApplicationGroup objects from the policy data.
This property is read-only.

Syntax
HRESULT get_ApplicationGroups(
IAzApplicationGroups **ppGroupCollection
);

Parameters
ppGroupCollection

Return value
None

Remarks
This property can be used only to enumerate IAzApplicationGroup objects that are direct child objects of the
IAzApplication object.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzApplication::get_ApplyStoreSacl method
(azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The ApplyStoreSacl property sets or retrieves a value that indicates whether policy audits should be generated
when the authorization store is modified.
This property is read/write.

Syntax
HRESULT get_ApplyStoreSacl(
BOOL *pbProp
);

Parameters
pbProp

Return value
None

Remarks
Policy audits are generated when the underlying policy store is modified. Both success and failure audits are
requested.
This property controls policy auditing only for the IAzApplication object and its child objects.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzApplication::get_AuthzInterfaceClsid method
(azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The AuthzInterfaceClsid property sets or retrieves the class identifier (CLSID) of the interface that the user
interface (UI) uses to perform application-specific operations.
This property is read/write.

Syntax
HRESULT get_AuthzInterfaceClsid(
BSTR *pbstrProp
);

Parameters
pbstrProp

Return value
None

Remarks
A CLSID is a GUID associated with a COM class.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzApplication::get_DelegatedPolicyUsers method
(azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The DelegatedPolicyUsers property retrieves the security identifiers (SIDs), in text form, of principals that act
as delegated policy users.
This property is read-only.

Syntax
HRESULT get_DelegatedPolicyUsers(
VARIANT *pvarDelegatedPolicyUsers
);

Parameters
pvarDelegatedPolicyUsers

Return value
None

Remarks
Delegated policy users are principals that are allowed to read the subset of the policy data that the policy
administrator of an IAzApplication object uses to administer the delegated object.

Note Delegated policy users are not supported for XML stores.

In JScript, the returned SAFEARRAY must be converted to the JScript Array object.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib
DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzApplication::get_DelegatedPolicyUsersName
method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The DelegatedPolicyUsersName property retrieves the account names of principals that act as delegated
policy users.
This property is read-only.

Syntax
HRESULT get_DelegatedPolicyUsersName(
VARIANT *pvarDelegatedPolicyUsers
);

Parameters
pvarDelegatedPolicyUsers

Return value
None

Remarks
Delegated policy users are principals that are allowed to read the subset of the policy data that the policy
administrator of an IAzApplication object uses to administer the delegated object.

Note Delegated policy users are not supported for XML stores.

In JScript, the returned SAFEARRAY must be converted to the JScript Array object.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib
DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzApplication::get_Description method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The Description property sets or retrieves a comment that describes the application.
This property is read/write.

Syntax
HRESULT get_Description(
BSTR *pbstrDescription
);

Parameters
pbstrDescription

Return value
None

Remarks
The maximum length of the Description property is 1,024 characters.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzApplication::get_GenerateAudits method
(azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The GenerateAudits property sets or retrieves a value that indicates whether run-time audits should be
generated.
This property is read/write.

Syntax
HRESULT get_GenerateAudits(
BOOL *pbProp
);

Parameters
pbProp

Return value
None

Remarks
The GenerateAudits property controls client context creation, client context deletion, and access check run-
time auditing. The client context can be created by a security identifier (SID), name, or token.
The AzAuthorizationStore.GenerateAudits property controls application initialization auditing.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzApplication::get_Name method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The Name property sets or retrieves the name of the application.

This property is read/write.

Syntax
HRESULT get_Name(
BSTR *pbstrName
);

Parameters
pbstrName

Return value
None

Remarks
The maximum length of the Name property is 512 characters.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzApplication::get_Operations method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The Operations property retrieves an IAzOperations object that is used to enumerate IAzOperation objects
from the policy data.
This property is read-only.

Syntax
HRESULT get_Operations(
IAzOperations **ppOperationCollection
);

Parameters
ppOperationCollection

Return value
None

Remarks
This property can be used only to enumerate IAzOperation objects that are direct child objects of the
IAzApplication object.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzApplication::get_PolicyAdministrators method
(azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The PolicyAdministrators property retrieves the security identifiers (SIDs), in text form, of principals that act
as policy administrators.
This property is read-only.

Syntax
HRESULT get_PolicyAdministrators(
VARIANT *pvarAdmins
);

Parameters
pvarAdmins

Return value
None

Remarks
Policy administrators for an object can perform the following tasks:
Read the object
Write attributes to the object
Read attributes of child objects of the object
Write attributes to child objects of the object
Delete the object
Delete child objects of the object
Create child objects of the object
In JScript, the returned SAFEARRAY must be converted to the JScript Array object.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h
Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzApplication::get_PolicyAdministratorsName
method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The PolicyAdministratorsName property retrieves the account names of principals that act as policy
administrators.
This property is read-only.

Syntax
HRESULT get_PolicyAdministratorsName(
VARIANT *pvarAdmins
);

Parameters
pvarAdmins

Return value
None

Remarks
Policy administrators for an object can perform the following tasks:
Read the object
Write attributes to the object
Read attributes of child objects of the object
Write attributes to child objects of the object
Delete the object
Delete child objects of the object
Create child objects of the object
In JScript, the returned SAFEARRAY must be converted to the JScript Array object.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h
Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzApplication::get_PolicyReaders method
(azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The PolicyReaders property retrieves the security identifiers (SIDs), in text form, of principals that act as policy
readers.
This property is read-only.

Syntax
HRESULT get_PolicyReaders(
VARIANT *pvarReaders
);

Parameters
pvarReaders

Return value
None

Remarks
Policy readers for an object can read attributes for the object and for child objects of the object. Readers can also
use the policy; for example, readers can call the AccessCheck method. Readers cannot modify the object or its
child objects.
In JScript, the returned SAFEARRAY must be converted to the JScript Array object.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll
Redistributable Windows Server 2003 Administration Tools Pack on
Windows XP
 IAzApplication::get_PolicyReadersName method
(azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The PolicyReadersName property retrieves the account names of principals that act as policy readers.
This property is read-only.

Syntax
HRESULT get_PolicyReadersName(
VARIANT *pvarReaders
);

Parameters
pvarReaders

Return value
None

Remarks
Policy readers for an object can read attributes for the object and for child objects of the object. Readers can also
use the policy; for example, readers can call the AccessCheck method. Readers cannot modify the object or its
child objects.
In JScript, the returned SAFEARRAY must be converted to the JScript Array object.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzApplication::get_Roles method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The Roles property retrieves an IAzRoles object that is used to enumerate IAzRole objects from the policy data.
This property is read-only.

Syntax
HRESULT get_Roles(
IAzRoles **ppRoleCollection
);

Parameters
ppRoleCollection

Return value
None

Remarks
This property can be used only to enumerate IAzRole objects that are direct child objects of the IAzApplication
object.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzApplication::get_Scopes method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The Scopes property retrieves an IAzScopes object that is used to enumerate IAzScope objects from the policy
data.
This property is read-only.

Syntax
HRESULT get_Scopes(
IAzScopes **ppScopeCollection
);

Parameters
ppScopeCollection

Return value
None

Remarks
This property can be used only to enumerate IAzScope objects that are direct child objects of the IAzApplication
object.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzApplication::get_Tasks method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The Tasks property retrieves an IAzTasks object that is used to enumerate IAzTask objects from the policy data.
This property is read-only.

Syntax
HRESULT get_Tasks(
IAzTasks **ppTaskCollection
);

Parameters
ppTaskCollection

Return value
None

Remarks
This property can be used only to enumerate IAzTask objects that are direct child objects of the IAzApplication
object.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzApplication::get_Version method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The Version property sets or retrieves the version of the application.

This property is read/write.

Syntax
HRESULT get_Version(
BSTR *pbstrProp
);

Parameters
pbstrProp

Return value
None

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzApplication::get_Writable method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The Writable property retrieves a value that indicates whether the object can be modified by the user context
that initialized it.
This property is read-only.

Syntax
HRESULT get_Writable(
BOOL *pfProp
);

Parameters
pfProp

Return value
None

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzApplication::GetProperty method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The GetProper ty method returns the IAzApplication object property with the specified property ID.

Syntax
HRESULT GetProperty(
[in] LONG lPropId,
[in, optional] VARIANT varReserved,
[out] VARIANT *pvarProp
);

Parameters
[in] lPropId

Property ID of the IAzApplication object property to return. The following table shows the possible values.

VA L UE M EA N IN G

Also accessed through the AuthzInterfaceClsid property

AZ_PROP_APPLICATION_AUTHZ_INTERFACE_CLSID

Also accessed through the ApplicationData property

AZ_PROP_APPLICATION_DATA

Also accessed through the Version property

AZ_PROP_APPLICATION_VERSION

Also accessed through the ApplyStoreSacl property

AZ_PROP_APPLY_STORE_SACL

Determines whether the current user has permission to

AZ_PROP_CHILD_CREATE create child objects. This value is TRUE if the current user
has permission; otherwise, FALSE .

Also accessed through the DelegatedPolicyUsers property

AZ_PROP_DELEGATED_POLICY_USERS

Also accessed through the DelegatedPolicyUsersName

AZ_PROP_DELEGATED_POLICY_USERS_NAME property

Also accessed through the Description property

AZ_PROP_DESCRIPTION

Also accessed through the GenerateAudits property

AZ_PROP_GENERATE_AUDITS
 Also accessed through the Name property
AZ_PROP_NAME

Also accessed through the PolicyAdministrators property

AZ_PROP_POLICY_ADMINS

Also accessed through the PolicyAdministratorsName

AZ_PROP_POLICY_ADMINS_NAME property

Also accessed through the PolicyReaders property

AZ_PROP_POLICY_READERS

Also accessed through the PolicyReadersName property

AZ_PROP_POLICY_READERS_NAME

Also accessed through the Writable property

AZ_PROP_WRITABLE

[in, optional] varReserved

Reserved for future use.

[out] pvarProp

A pointer to the returned IAzApplication object property.

Return value
If the method succeeds, the method returns S_OK.
Any other HRESULT value indicates that the operation failed.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzApplication::InitializeClientContextFromName
method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The InitializeClientContextFromName method gets an IAzClientContext object pointer from the client
identity as a (domain name, client name) pair.

Note If possible, call the InitializeClientContextFromToken function instead of InitializeClientContextFromName . For

more information, see Remarks.

Syntax
HRESULT InitializeClientContextFromName(
[in] BSTR ClientName,
[in, optional] BSTR DomainName,
[in, optional] VARIANT varReserved,
[out] IAzClientContext **ppClientContext
);

Parameters
[in] ClientName

Name of the security principal.

[in, optional] DomainName

Domain name in which the user account resides. The default value is NULL .
[in, optional] varReserved

Reserved for future use. This parameter can be one of the following values:
varReserved.vt == VT_ERROR and varReserved.scode == DISP_E_PARAMNOTFOUND
varReserved.vt == VT_EMPTY
varReserved.vt == VT_NULL
varReserved.vt == VT_I4 and varReserved.lVal == 0
varReserved.vt == VT_I2 and varReserved.iVal == 0
[out] ppClientContext

A pointer to a pointer to the returned IAzClientContext object.

Return value
If the function succeeds, the function returns S_OK.
If the function fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.
Remarks
If possible, call the InitializeClientContextFromToken function instead of InitializeClientContextFromName .
InitializeClientContextFromName attempts to retrieve the information available in a logon token had the
client actually logged on. An actual logon token provides more information, such as logon type and logon
properties, and reflects the behavior of the authentication package used for the logon. The client context created
by InitializeClientContextFromToken uses a logon token, and the resulting client context is more complete
and accurate than a client context created by InitializeClientContextFromName .
The DomainName and ClientName parameters must combine to represent a SidTypeUser.
The supported name formats are the same as those supported by the LookupAccountName function.

Impor tant Applications should not assume that the calling context has permission to use this function. The
AuthzInitializeContextFromSid function reads the tokenGroupsGlobalAndUniversal attribute of the SID specified in the call to
determine the current user's group memberships. If the user's object is in Active Directory, the calling context must have read
access to the tokenGroupsGlobalAndUniversal attribute on the user object. Read access to the
tokenGroupsGlobalAndUniversal attribute is granted to the Pre-Windows 2000 Compatible Access group, but new
domains contain an empty Pre-Windows 2000 Compatible Access group by default because the default setup selection
is Permissions compatible with Windows 2000 and Windows Ser ver 2003 . Therefore, applications may not have
access to the tokenGroupsGlobalAndUniversal attribute; in this case, the AuthzInitializeContextFromSid function fails with
ACCESS_DENIED. Applications that use this function should correctly handle this error and provide supporting documentation.
To simplify granting accounts permission to query a user's group information, add accounts that need the ability to look up
group information to the Windows Authorization Access Group.

Applications calling this function should use the fully qualified domain name or user principal name (UPN).
Otherwise, this method might fail across forests if the NetBIOS domain name is used and the two domains do not
have a direct trust relationship.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP

See also
Allowing Anonymous Access
IAzApplication
 IAzApplication::InitializeClientContextFromStringSid
method (azroles.h)
7/2/2022 • 3 minutes to read • Edit Online

The InitializeClientContextFromStringSid method gets an IAzClientContext object pointer from the specified
security identifier (SID) in text form.

Note If possible, call the InitializeClientContextFromToken function instead of InitializeClientContextFromStringSid . For

more information, see Remarks.

Syntax
HRESULT InitializeClientContextFromStringSid(
[in] BSTR SidString,
[in] LONG lOptions,
[in, optional] VARIANT varReserved,
[out] IAzClientContext **ppClientContext
);

Parameters
[in] SidString

A string that contains the text form of the SID of the security principal. This must be a valid string SID that can be
converted by the ConvertStringSidToSid function.
[in] lOptions

Options for the context creation.

If AZ_CLIENT_CONTEXT_SKIP_GROUP is specified, the SID specified in the SidString parameter is not necessarily
a valid user account. The SID will be used to create the context without validation. The created context will be
flagged as having been created from a SID, the SID string will be stored in the client name field, and the domain
name field will be empty. Token groups will not be used in the client context creation. Lightweight Directory
Access Protocol (LDAP) query groups are not supported when AZ_CLIENT_CONTEXT_SKIP_GROUP is specified.
Because the account is not validated in Active Directory, the client context's user information properties, such as
UserSamCompat, will not be valid, and when accessed, they will return ERROR_INVALID_HANDLE. The
RoleForAccessCheck property and the AccessCheck method of IAzClientContext can still be used to specify a role
for access checking. The GetRoles method of IAzClientContext can still be used to enumerate roles assigned to
the context within a specific scope.
If AZ_CLIENT_CONTEXT_SKIP_GROUP is not specified, the SID must represent a valid user account.
[in, optional] varReserved

Reserved for future use. This parameter can be one of the following values:
varReserved.vt == VT_ERROR and varReserved.scode == DISP_E_PARAMNOTFOUND
varReserved.vt == VT_EMPTY
 varReserved.vt == VT_NULL
varReserved.vt == VT_I4 and varReserved.lVal == 0
varReserved.vt == VT_I2 and varReserved.iVal == 0
[out] ppClientContext

A pointer to a pointer to the returned IAzClientContext object.

Return value
If the function succeeds, the function returns S_OK.
If the function fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.

Remarks
If possible, call the InitializeClientContextFromToken function instead of
InitializeClientContextFromStringSid . InitializeClientContextFromStringSid attempts to retrieve the
information available in a logon token had the client actually logged on. An actual logon token provides more
information, such as logon type and logon properties, and reflects the behavior of the authentication package
used for the logon. The client context created by InitializeClientContextFromToken uses a logon token, and
the resulting client context is more complete and accurate than a client context created by
InitializeClientContextFromStringSid .

Impor tant Applications should not assume that the calling context has permission to use this function. The
AuthzInitializeContextFromSid function reads the tokenGroupsGlobalAndUniversal attribute of the SID specified in the call to
determine the current user's group memberships. If the user's object is in Active Directory, the calling context must have read
access to the tokenGroupsGlobalAndUniversal attribute on the user object. Read access to the
tokenGroupsGlobalAndUniversal attribute is granted to the Pre-Windows 2000 Compatible Access group, but new
domains contain an empty Pre-Windows 2000 Compatible Access group by default because the default setup selection
is Permissions compatible with Windows 2000 and Windows Ser ver 2003 . Therefore, applications may not have
access to the tokenGroupsGlobalAndUniversal attribute; in this case, the AuthzInitializeContextFromSid function fails with
ACCESS_DENIED. Applications that use this function should correctly handle this error and provide supporting documentation.
To simplify granting accounts permission to query a user's group information, add accounts that need the ability to look up
group information to the Windows Authorization Access Group.

Applications calling this function should use the fully qualified domain name or user principal name (UPN).
Otherwise, this method might fail across forests if the NetBIOS domain name is used and the two domains do not
have a direct trust relationship.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h
 Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP

See also
Allowing Anonymous Access
IAzApplication
 IAzApplication::InitializeClientContextFromToken
method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The InitializeClientContextFromToken method gets an IAzClientContext object pointer from the specified
client token.

Syntax
HRESULT InitializeClientContextFromToken(
[in] ULONGLONG ullTokenHandle,
[in, optional] VARIANT varReserved,
[out] IAzClientContext **ppClientContext
);

Parameters
[in] ullTokenHandle

A handle to a Windows token that specifies the client. If this parameter is NULL , the impersonation token of the
caller's thread is used. If the thread does not have an impersonation token, the process token is used. The token
must have been opened for TOKEN_QUERY, TOKEN_IMPERSONATE, and TOKEN_DUPLICATE access.
[in, optional] varReserved

Reserved for future use.

[out] ppClientContext

A pointer to a pointer to the returned IAzClientContext object.

Return value
If the method succeeds, the method returns S_OK.
Any other HRESULT value indicates that the operation failed.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib
DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzApplication::OpenApplicationGroup method
(azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The OpenApplicationGroup method opens an IAzApplicationGroup object with the specified name.

Syntax
HRESULT OpenApplicationGroup(
[in] BSTR bstrGroupName,
[in, optional] VARIANT varReserved,
[out] IAzApplicationGroup **ppGroup
);

Parameters
[in] bstrGroupName

Name of the IAzApplicationGroup object to open.

[in, optional] varReserved

Reserved for future use.

[out] ppGroup

A pointer to a pointer to the opened IAzApplicationGroup object.

Return value
If the method succeeds, the method returns S_OK.
Any other HRESULT value indicates that the operation failed.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll
Redistributable Windows Server 2003 Administration Tools Pack on
Windows XP
 IAzApplication::OpenOperation method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The OpenOperation method opens an IAzOperation object with the specified name.

Syntax
HRESULT OpenOperation(
[in] BSTR bstrOperationName,
[in, optional] VARIANT varReserved,
[out] IAzOperation **ppOperation
);

Parameters
[in] bstrOperationName

Name of the IAzOperation object to open.

[in, optional] varReserved

Reserved for future use.

[out] ppOperation

A pointer to a pointer to the opened IAzOperation object.

Return value
If the method succeeds, the method returns S_OK.
Any other HRESULT value indicates that the operation failed.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzApplication::OpenRole method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The OpenRole method opens an IAzRole object with the specified name.

Syntax
HRESULT OpenRole(
[in] BSTR bstrRoleName,
[in, optional] VARIANT varReserved,
[out] IAzRole **ppRole
);

Parameters
[in] bstrRoleName

Name of the IAzRole object to open.

[in, optional] varReserved

Reserved for future use.

[out] ppRole

A pointer to a pointer to the opened IAzRole object.

Return value
If the method succeeds, the method returns S_OK.
Any other HRESULT value indicates that the operation failed.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzApplication::OpenScope method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The OpenScope method opens an IAzScope object with the specified name.

Syntax
HRESULT OpenScope(
[in] BSTR bstrScopeName,
[in, optional] VARIANT varReserved,
[out] IAzScope **ppScope
);

Parameters
[in] bstrScopeName

Name of the IAzScope object to open.

[in, optional] varReserved

Reserved for future use.

[out] ppScope

A pointer to a pointer to the opened IAzScope object.

Return value
If the method succeeds, the method returns S_OK.
Any other HRESULT value indicates that the operation failed.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzApplication::OpenTask method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The OpenTask method opens an IAzTask object with the specified name.

Syntax
HRESULT OpenTask(
[in] BSTR bstrTaskName,
[in, optional] VARIANT varReserved,
[out] IAzTask **ppTask
);

Parameters
[in] bstrTaskName

Name of the IAzTask object to open.

[in, optional] varReserved

Reserved for future use.

[out] ppTask

A pointer to a pointer to the opened IAzTask object.

Return value
If the method succeeds, the method returns S_OK.
Any other HRESULT value indicates that the operation failed.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzApplication::put_ApplicationData method
(azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The ApplicationData property sets or retrieves an opaque field that can be used by the application to store
information.
This property is read/write.

Syntax
HRESULT put_ApplicationData(
BSTR bstrApplicationData
);

Parameters
bstrApplicationData

Return value
None

Remarks
Impor tant Policy administrators can read from and write to this property. Applications should not store data in the
ApplicationData property that should not be available to the policy administrator.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll
Redistributable Windows Server 2003 Administration Tools Pack on
Windows XP
 IAzApplication::put_ApplyStoreSacl method
(azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The ApplyStoreSacl property sets or retrieves a value that indicates whether policy audits should be generated
when the authorization store is modified.
This property is read/write.

Syntax
HRESULT put_ApplyStoreSacl(
BOOL bProp
);

Parameters
bProp

Return value
None

Remarks
Policy audits are generated when the underlying policy store is modified. Both success and failure audits are
requested.
This property controls policy auditing only for the IAzApplication object and its child objects.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzApplication::put_AuthzInterfaceClsid method
(azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The AuthzInterfaceClsid property sets or retrieves the class identifier (CLSID) of the interface that the user
interface (UI) uses to perform application-specific operations.
This property is read/write.

Syntax
HRESULT put_AuthzInterfaceClsid(
BSTR bstrProp
);

Parameters
bstrProp

Return value
None

Remarks
A CLSID is a GUID associated with a COM class.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzApplication::put_Description method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The Description property sets or retrieves a comment that describes the application.
This property is read/write.

Syntax
HRESULT put_Description(
BSTR bstrDescription
);

Parameters
bstrDescription

Return value
None

Remarks
The maximum length of the Description property is 1,024 characters.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzApplication::put_GenerateAudits method
(azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The GenerateAudits property sets or retrieves a value that indicates whether run-time audits should be
generated.
This property is read/write.

Syntax
HRESULT put_GenerateAudits(
BOOL bProp
);

Parameters
bProp

Return value
None

Remarks
The GenerateAudits property controls client context creation, client context deletion, and access check run-
time auditing. The client context can be created by a security identifier (SID), name, or token.
The AzAuthorizationStore.GenerateAudits property controls application initialization auditing.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzApplication::put_Name method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The Name property sets or retrieves the name of the application.

This property is read/write.

Syntax
HRESULT put_Name(
BSTR bstrName
);

Parameters
bstrName

Return value
None

Remarks
The maximum length of the Name property is 512 characters.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzApplication::put_Version method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The Version property sets or retrieves the version of the application.

This property is read/write.

Syntax
HRESULT put_Version(
BSTR bstrProp
);

Parameters
bstrProp

Return value
None

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzApplication::SetProperty method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The SetProper ty method sets the specified value to the IAzApplication object property with the specified
property ID.

Syntax
HRESULT SetProperty(
[in] LONG lPropId,
[in] VARIANT varProp,
[in, optional] VARIANT varReserved
);

Parameters
[in] lPropId

Property ID of the IAzApplication object property to set. The following table shows the possible values.

VA L UE M EA N IN G

Also accessed through the ApplicationData property

AZ_PROP_APPLICATION_DATA

Also accessed through the AuthzInterfaceClsid property

AZ_PROP_APPLICATION_AUTHZ_INTERFACE_CLSID

Also accessed through the Version property

AZ_PROP_APPLICATION_VERSION

Also accessed through the ApplyStoreSacl property

AZ_PROP_APPLY_STORE_SACL

Also accessed through the Description property

AZ_PROP_DESCRIPTION

Also accessed through the GenerateAudits property

AZ_PROP_GENERATE_AUDITS

Also accessed through the Name property

AZ_PROP_NAME

[in] varProp

Value to set to the IAzApplication object property specified by the lPropId parameter. The type of data that must
be used depends on the value of the lPropId parameter.

L P RO P ID VA L UE DATA T Y P E ( C ++/ VISUA L B A SIC )

 BSTR/String
AZ_PROP_APPLICATION_DATA

BSTR/String
AZ_PROP_APPLICATION_INTERFACE_CLSID

BSTR/String
AZ_PROP_APPLICATION_VERSION

BSTR/String
AZ_PROP_APPLY_STORE_SACL

BSTR/String
AZ_PROP_DESCRIPTION

BSTR/String
AZ_PROP_GENERATE_AUDITS

BSTR/String
AZ_PROP_NAME

[in, optional] varReserved

Reserved for future use.

Return value
If the method succeeds, the method returns S_OK.
Any other HRESULT value indicates that the operation failed.

Remarks
You must call the Submit method to persist any changes made by this method.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h
Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzApplication::Submit method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The Submit method persists changes made to the IAzApplication object.

Syntax
HRESULT Submit(
[in] LONG lFlags,
[in, optional] VARIANT varReserved
);

Parameters
[in] lFlags

Flags that modify the behavior of the Submit method. The default value is zero. If the AZ_SUBMIT_FLAG_ABORT
flag is specified, the changes to the object are discarded and the object is updated to match the underlying
policy store.
[in, optional] varReserved

Reserved for future use.

Return value
None

Remarks
Any additions or modifications to an IAzApplication object are not persisted until the Submit method is called.
The Submit method does not extend to child objects; child objects must be individually persisted to the policy
store. A created IAzApplication object must be submitted before it can be referenced or become a parent object.
The destructor for an object silently discards unsubmitted changes.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib
DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzApplication2 interface (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The IAzApplication2 interface inherits from the IAzApplication interface and implements additional methods to
initialize IAzClientContext2 objects.

Inheritance
The IAzApplication2 interface inherits from IDispatch and IAzApplication. IAzApplication2 also has these
types of members:

Methods
The IAzApplication2 interface has these methods.

IAzApplication2::InitializeClientContext2

Retrieves an IAzClientContext2 object pointer.

IAzApplication2::InitializeClientContextFromToken2

Retrieves an IAzClientContext2 object pointer from the specified client token.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008, Windows Server 2003 with SP1
[desktop apps only]

Target Platform Windows

Header azroles.h

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzApplication2::InitializeClientContext2 method
(azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The InitializeClientContext2 method retrieves an IAzClientContext2 object pointer.

Syntax
HRESULT InitializeClientContext2(
[in] BSTR IdentifyingString,
[in, optional] VARIANT varReserved,
[out] IAzClientContext2 **ppClientContext
);

Parameters
[in] IdentifyingString

A string that identifies the client context in the audit trail for client connection and object access audit entries.
[in, optional] varReserved

Reserved for future use.

[out] ppClientContext

A pointer to a pointer to the returned IAzClientContext2 object.

Return value
If the method succeeds, the method returns S_OK.
If the method fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008, Windows Server 2003 with SP1
[desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib
DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzApplication2::InitializeClientContextFromToken2
method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The InitializeClientContextFromToken2 method retrieves an IAzClientContext2 object pointer from the

specified client token.

Syntax
HRESULT InitializeClientContextFromToken2(
[in] ULONG ulTokenHandleLowPart,
[in] ULONG ulTokenHandleHighPart,
[in, optional] VARIANT varReserved,
[out] IAzClientContext2 **ppClientContext
);

Parameters
[in] ulTokenHandleLowPart

Low byte of a handle to a token that specifies the client. If the values of both this parameter and the
ulTokenHandleHighPart parameter are zero, the impersonation token of the caller's thread is used. If the thread
does not have an impersonation token, the process token is used. The token must have been opened for
TOKEN_QUERY, TOKEN_IMPERSONATE, or TOKEN_DUPLICATE access.
[in] ulTokenHandleHighPart

High byte of a handle to a token that specifies the client. If the values of both this parameter and the
ulTokenHandleHighPart parameter are zero, the impersonation token of the caller's thread is used. If the thread
does not have an impersonation token, the process token is used. The token must have been opened for
TOKEN_QUERY, TOKEN_IMPERSONATE, or TOKEN_DUPLICATE access.
[in, optional] varReserved

Reserved for future use.

[out] ppClientContext

A pointer to a pointer to the returned IAzClientContext2 object.

Return value
If the method succeeds, the method returns S_OK.
If the method fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.

Requirements
Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008, Windows Server 2003 with SP1
[desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzApplication3 interface (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The IAzApplication3 interface provides methods to manage IAzRoleAssignment, IAzRoleDefinition, and

IAzScope2 objects.

Inheritance
The IAzApplication3 interface inherits from IAzApplication2. IAzApplication3 also has these types of
members:

Methods
The IAzApplication3 interface has these methods.

IAzApplication3::CreateRoleAssignment

Creates a new IAzRoleAssignment object with the specified name.

IAzApplication3::CreateRoleDefinition

Creates a new IAzRoleDefinition object with the specified name.

IAzApplication3::CreateScope2

Creates a new IAzScope2 object with the specified name.

IAzApplication3::DeleteRoleAssignment

Removes the specified IAzRoleAssignment object from the IAzApplication3 object.

IAzApplication3::DeleteRoleDefinition

Removes the specified IAzRoleDefinition object from the IAzApplication3 object.

IAzApplication3::DeleteScope2

Removes the specified IAzScope2 object from the IAzApplication3 object.

IAzApplication3::get_BizRulesEnabled

Gets or sets a value that indicates whether business rules are enabled for this application.

IAzApplication3::get_RoleAssignments

Gets an IAzRoleAssignments object that represents the collection of IAzRoleAssignment objects associated with the current
IAzApplication3 object.
 IAzApplication3::get_RoleDefinitions

Gets an IAzRoleDefinitions object that represents the collection of IAzRoleDefinition objects associated with the current
IAzApplication3 object.

IAzApplication3::OpenRoleAssignment

Opens an IAzRoleAssignment object with the specified name.

IAzApplication3::OpenRoleDefinition

Opens an IAzRoleDefinition object with the specified name.

IAzApplication3::OpenScope2

Opens an IAzScope2 object with the specified name.

IAzApplication3::put_BizRulesEnabled

Gets or sets a value that indicates whether business rules are enabled for this application.

IAzApplication3::ScopeExists

Indicates whether the specified scope exists in this IAzApplication3 object.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header azroles.h
 IAzApplication3::CreateRoleAssignment method
(azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The CreateRoleAssignment method creates a new IAzRoleAssignment object with the specified name.

Syntax
HRESULT CreateRoleAssignment(
[in] BSTR bstrRoleAssignmentName,
[out] IAzRoleAssignment **ppRoleAssignment
);

Parameters
[in] bstrRoleAssignmentName

A string that contains the name of the new IAzRoleAssignment object.

[out] ppRoleAssignment

The address of a pointer to the IAzRoleAssignment object that this method creates.
When you have finished using this IAzRoleAssignment object, release it by calling the IUnknown::Release
method.

Return value
If the method succeeds, it returns S_OK .
If the method fails, it returns an error code. For a list of common error codes, see Common HRESULT Values.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header azroles.h

DLL Azroles.dll
 IAzApplication3::CreateRoleDefinition method
(azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The CreateRoleDefinition method creates a new IAzRoleDefinition object with the specified name.

Syntax
HRESULT CreateRoleDefinition(
[in] BSTR bstrRoleDefinitionName,
[out] IAzRoleDefinition **ppRoleDefinitions
);

Parameters
[in] bstrRoleDefinitionName

A string that contains the name of the new IAzRoleDefinition object.

[out] ppRoleDefinitions

The address of a pointer to the IAzRoleDefinition object that this method creates.
When you have finished using this IAzRoleDefinition object, release it by calling the IUnknown::Release method.

Return value
If the method succeeds, it returns S_OK .
If the method fails, it returns an error code. For a list of common error codes, see Common HRESULT Values.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header azroles.h

DLL Azroles.dll
 IAzApplication3::CreateScope2 method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The CreateScope2 method creates a new IAzScope2 object with the specified name.

Syntax
HRESULT CreateScope2(
[in] BSTR bstrScopeName,
[out] IAzScope2 **ppScope2
);

Parameters
[in] bstrScopeName

A string that contains the name of the new IAzScope2 object.

[out] ppScope2

The address of a pointer to the IAzScope2 object that this method creates.
When you have finished using this IAzScope2 object, release it by calling the IUnknown::Release method.

Return value
If the method succeeds, it returns S_OK .
If the method fails, it returns an error code. For a list of common error codes, see Common HRESULT Values.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header azroles.h

DLL Azroles.dll
 IAzApplication3::DeleteRoleAssignment method
(azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The DeleteRoleAssignment method removes the specified IAzRoleAssignment object from the
IAzApplication3 object.

Syntax
HRESULT DeleteRoleAssignment(
[in] BSTR bstrRoleAssignmentName
);

Parameters
[in] bstrRoleAssignmentName

A string that contains the name of the IAzRoleAssignment object to remove.

Return value
If the method succeeds, it returns S_OK .
If the method fails, it returns an error code. For a list of common error codes, see Common HRESULT Values.

Remarks
If any references to an IAzRoleAssignment object have been deleted from the cache, you can no longer use that
object. In C++, you must release references to deleted IAzRoleAssignment objects by calling the
IUnknown::Release method. In Visual Basic, references to deleted objects are automatically released.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header azroles.h

DLL Azroles.dll
 IAzApplication3::DeleteRoleDefinition method
(azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The DeleteRoleDefinition method removes the specified IAzRoleDefinition object from the IAzApplication3
object.

Syntax
HRESULT DeleteRoleDefinition(
[in] BSTR bstrRoleDefinitionName
);

Parameters
[in] bstrRoleDefinitionName

A string that contains the name of the IAzRoleDefinition object to remove.

Return value
If the method succeeds, it returns S_OK .
If the method fails, it returns an error code. For a list of common error codes, see Common HRESULT Values.

Remarks
If any references to an IAzRoleDefinition object have been deleted from the cache, you can no longer use that
object. In C++, you must release references to deleted IAzRoleDefinition objects by calling the
IUnknown::Release method. In Visual Basic, references to deleted objects are automatically released.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header azroles.h

DLL Azroles.dll
 IAzApplication3::DeleteScope2 method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The DeleteScope2 method removes the specified IAzScope2 object from the IAzApplication3 object.

Syntax
HRESULT DeleteScope2(
[in] BSTR bstrScopeName
);

Parameters
[in] bstrScopeName

A string that contains the name of the IAzScope2 object to remove.

Return value
If the method succeeds, it returns S_OK .
If the method fails, it returns an error code. For a list of common error codes, see Common HRESULT Values.

Remarks
If any references to an IAzScope2 object have been deleted from the cache, you can no longer use that object. In
C++, you must release references to deleted IAzScope2 objects by calling the IUnknown::Release method. In
Visual Basic, references to deleted objects are automatically released.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header azroles.h

DLL Azroles.dll
 IAzApplication3::get_BizRulesEnabled method
(azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

Gets or sets a value that indicates whether business rules are enabled for this application.
This property is read/write.

Syntax
HRESULT get_BizRulesEnabled(
VARIANT_BOOL *pbEnabled
);

Parameters
pbEnabled

Return value
None

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header azroles.h

DLL Azroles.dll
 IAzApplication3::get_RoleAssignments method
(azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The RoleAssignments property gets an IAzRoleAssignments object that represents the collection of
IAzRoleAssignment objects associated with the current IAzApplication3 object.
This property is read-only.

Syntax
HRESULT get_RoleAssignments(
IAzRoleAssignments **ppRoleAssignments
);

Parameters
ppRoleAssignments

Return value
None

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header azroles.h

DLL Azroles.dll
 IAzApplication3::get_RoleDefinitions method
(azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The RoleDefinitions property gets an IAzRoleDefinitions object that represents the collection of
IAzRoleDefinition objects associated with the current IAzApplication3 object.
This property is read-only.

Syntax
HRESULT get_RoleDefinitions(
IAzRoleDefinitions **ppRoleDefinitions
);

Parameters
ppRoleDefinitions

Return value
None

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header azroles.h

DLL Azroles.dll
 IAzApplication3::OpenRoleAssignment method
(azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The OpenRoleAssignment method opens an IAzRoleAssignment object with the specified name.

Syntax
HRESULT OpenRoleAssignment(
[in] BSTR bstrRoleAssignmentName,
[out] IAzRoleAssignment **ppRoleAssignment
);

Parameters
[in] bstrRoleAssignmentName

A string that contains the name of the IAzRoleAssignment object to open.

[out] ppRoleAssignment

The address of a pointer to the IAzRoleAssignment object that this method opens.
When you have finished using this IAzRoleAssignment object, release it by calling the IUnknown::Release
method.

Return value
If the method succeeds, it returns S_OK .
If the method fails, it returns an error code. For a list of common error codes, see Common HRESULT Values.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header azroles.h

DLL Azroles.dll
 IAzApplication3::OpenRoleDefinition method
(azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The OpenRoleDefinition method opens an IAzRoleDefinition object with the specified name.

Syntax
HRESULT OpenRoleDefinition(
[in] BSTR bstrRoleDefinitionName,
[out] IAzRoleDefinition **ppRoleDefinitions
);

Parameters
[in] bstrRoleDefinitionName

A string that contains the name of the IAzRoleDefinition object to open.

[out] ppRoleDefinitions

The address of a pointer to the IAzRoleDefinition object that this method opens.
When you have finished using this IAzRoleDefinition object, release it by calling the IUnknown::Release method.

Return value
If the method succeeds, the method returns S_OK .
If the method fails, it returns an error code. For a list of common error codes, see Common HRESULT Values.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header azroles.h

DLL Azroles.dll
 IAzApplication3::OpenScope2 method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The OpenScope2 method opens an IAzScope2 object with the specified name.

Syntax
HRESULT OpenScope2(
[in] BSTR bstrScopeName,
[out] IAzScope2 **ppScope2
);

Parameters
[in] bstrScopeName

A string that contains the name of the IAzScope2 object to open.

[out] ppScope2

The address of a pointer to the IAzScope2 object that this method opens.
When you have finished using the IAzScope2 object, release it by calling the IUnknown::Release method.

Return value
If the method succeeds, it returns S_OK .
If the method fails, it returns an error code. For a list of common error codes, see Common HRESULT Values.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header azroles.h

DLL Azroles.dll
 IAzApplication3::put_BizRulesEnabled method
(azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

Gets or sets a value that indicates whether business rules are enabled for this application.
This property is read/write.

Syntax
HRESULT put_BizRulesEnabled(
VARIANT_BOOL bEnabled
);

Parameters
bEnabled

Return value
None

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header azroles.h

DLL Azroles.dll
 IAzApplication3::ScopeExists method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The ScopeExists method indicates whether the specified scope exists in this IAzApplication3 object.

Syntax
HRESULT ScopeExists(
[in] BSTR bstrScopeName,
[out] VARIANT_BOOL *pbExist
);

Parameters
[in] bstrScopeName

A string that contains the name of the scope to be checked.

[out] pbExist

VARIANT_TRUE if the specified scope exists in this IAzApplication3 object; otherwise, VARIANT_FALSE .

Return value
If the method succeeds, it returns S_OK .
If the method fails, it returns an error code. For a list of common error codes, see Common HRESULT Values.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header azroles.h

DLL Azroles.dll
 IAzApplicationGroup interface (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The IAzApplicationGroup interface defines a collection of principals.

Inheritance
The IAzApplicationGroup interface inherits from the IDispatch interface. IAzApplicationGroup also has
these types of members:

Methods
The IAzApplicationGroup interface has these methods.

IAzApplicationGroup::AddAppMember

Adds the specified IAzApplicationGroup object to the list of application groups that belong to this application group.

IAzApplicationGroup::AddAppNonMember

Adds the specified IAzApplicationGroup object to the list of application groups that are refused membership in this application
group.

IAzApplicationGroup::AddMember

Adds the specified security identifier (SID) in text form to the list of accounts that belong to the application group.

IAzApplicationGroup::AddMemberName

Adds the specified account name to the list of accounts that belong to the application group.

IAzApplicationGroup::AddNonMember

Adds the specified security identifier (SID) in text form to the list of accounts that are refused membership in the application
group.

IAzApplicationGroup::AddNonMemberName

Adds the specified account name to the list of accounts that are refused membership in the application group.

IAzApplicationGroup::AddPropertyItem

Adds the specified entity to the specified list.

IAzApplicationGroup::DeleteAppMember

Removes the specified IAzApplicationGroup object from the list of application groups that belong to this application group.
IAzApplicationGroup::DeleteAppNonMember

Removes the specified IAzApplicationGroup object from the list of application groups that are refused membership in this
application group.

IAzApplicationGroup::DeleteMember

Removes the specified security identifier (SID) in text form from the list of accounts that belong to the application group.

IAzApplicationGroup::DeleteMemberName

Removes the specified account name from the list of accounts that belong to the application group.

IAzApplicationGroup::DeleteNonMember

Removes the specified security identifier (SID) in text form from the list of accounts that are refused membership in the
application group.

IAzApplicationGroup::DeleteNonMemberName

Removes the specified account name from the list of accounts that are refused membership in the application group.

IAzApplicationGroup::DeletePropertyItem

Removes the specified entity from the specified list.

IAzApplicationGroup::get_AppMembers

Retrieves the application groups that belong to this application group.

IAzApplicationGroup::get_AppNonMembers

Retrieves the application groups that are refused membership in this application group.

IAzApplicationGroup::get_Description

Sets or retrieves a comment that describes the application group.

IAzApplicationGroup::get_LdapQuery

Sets or retrieves the Lightweight Directory Access Protocol (LDAP) query used to define membership for an LDAP query
application group.

IAzApplicationGroup::get_Members

Retrieves the security identifiers (SIDs), in text form, of accounts that belong to the application group.

IAzApplicationGroup::get_MembersName

Retrieves the account names of accounts that belong to the application group.

IAzApplicationGroup::get_Name

Sets or retrieves the name of the application group.

 IAzApplicationGroup::get_NonMembers

Retrieves the security identifiers (SIDs), in text form, of accounts that are refused membership in the application group.

IAzApplicationGroup::get_NonMembersName

Retrieves the account names of accounts that are refused membership in the application group.

IAzApplicationGroup::get_Type

Sets or retrieves the group type of the application group.

IAzApplicationGroup::get_Writable

Retrieves a value that indicates whether the application group can be modified by the user context that initialized it.

IAzApplicationGroup::GetProperty

Returns the IAzApplicationGroup object property with the specified property ID.

IAzApplicationGroup::put_Description

Sets or retrieves a comment that describes the application group.

IAzApplicationGroup::put_LdapQuery

Sets or retrieves the Lightweight Directory Access Protocol (LDAP) query used to define membership for an LDAP query
application group.

IAzApplicationGroup::put_Name

Sets or retrieves the name of the application group.

IAzApplicationGroup::put_Type

Sets or retrieves the group type of the application group.

IAzApplicationGroup::SetProperty

Sets the specified value to the IAzApplicationGroup object property with the specified property ID.

IAzApplicationGroup::Submit

Persists changes made to the IAzApplicationGroup object.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzApplicationGroup::AddAppMember method
(azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The AddAppMember method adds the specified IAzApplicationGroup object to the list of application groups
that belong to this application group.

Syntax
HRESULT AddAppMember(
[in] BSTR bstrProp,
[in, optional] VARIANT varReserved
);

Parameters
[in] bstrProp

String that contains the Name property of the IAzApplicationGroup object to add to the list of the application
groups that belong to this application group.
[in, optional] varReserved

Reserved for future use.

Return value
None

Remarks
To view the list of application groups that belong to this application group, use the AppMembers property.
You must call the Submit method to persist any changes made by this method.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib
DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzApplicationGroup::AddAppNonMember method
(azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The AddAppNonMember method adds the specified IAzApplicationGroup object to the list of application
groups that are refused membership in this application group.

Syntax
HRESULT AddAppNonMember(
[in] BSTR bstrProp,
[in, optional] VARIANT varReserved
);

Parameters
[in] bstrProp

String that contains the Name property of the IAzApplicationGroup object to add to the list of the application
groups that are refused membership in this application group.
[in, optional] varReserved

Reserved for future use.

Return value
None

Remarks
To view the list of application groups that are refused membership in this application group, use the
AppNonMembers property.
Denying membership to an account in an application group does not prevent that account from being assigned
to a role through a different application group, nor from being granted permission to a resource through
assignment to any other role.
You must call the Submit method to persist any changes made by this method.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzApplicationGroup::AddMember method
(azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The AddMember method adds the specified security identifier (SID) in text form to the list of accounts that
belong to the application group.

Syntax
HRESULT AddMember(
[in] BSTR bstrProp,
[in, optional] VARIANT varReserved
);

Parameters
[in] bstrProp

String that contains the text form of the SID to add to the list of accounts that belong to the application group.
[in, optional] varReserved

Reserved for future use.

Return value
None

Remarks
To view the list of SIDs of accounts that belong to this application group in text form, use the Members property.
You must call the Submit method to persist any changes made by this method.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll
Redistributable Windows Server 2003 Administration Tools Pack on
Windows XP
 IAzApplicationGroup::AddMemberName method
(azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The AddMemberName method adds the specified account name to the list of accounts that belong to the
application group.

Syntax
HRESULT AddMemberName(
[in] BSTR bstrProp,
[in, optional] VARIANT varReserved
);

Parameters
[in] bstrProp

String that contains the account name to add to the list of accounts that belong to the application group. The
account name must be in user principal name (UPN) format. The LookupAccountName function is called to
retrieve the domain.
[in, optional] varReserved

Reserved for future use.

Return value
None

Remarks
To view the list of account names of accounts that belong to this application group, use the MembersName
property.
You must call the Submit method to persist any changes made by this method.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h
Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzApplicationGroup::AddNonMember method
(azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The AddNonMember method adds the specified security identifier (SID) in text form to the list of accounts that
are refused membership in the application group.

Syntax
HRESULT AddNonMember(
[in] BSTR bstrProp,
[in, optional] VARIANT varReserved
);

Parameters
[in] bstrProp

String that contains the text form of the SID to add to the list of accounts that are refused membership in the
application group.
[in, optional] varReserved

Reserved for future use.

Return value
None

Remarks
The application group will never have an account added using this method as a member, even if that account is
specified directly or indirectly by the Members property.
Denying membership to an account in an application group does not prevent that account from being assigned
to a role through a different application group, nor from being granted permission to a resource through
assignment to any other role.
To view the list of SIDs of accounts that are refused membership in this application group in text form, use the
NonMembers property.
You must call the Submit method to persist any changes made by this method.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]
Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzApplicationGroup::AddNonMemberName
method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The AddNonMemberName method adds the specified account name to the list of accounts that are refused
membership in the application group.

Syntax
HRESULT AddNonMemberName(
[in] BSTR bstrProp,
[in, optional] VARIANT varReserved
);

Parameters
[in] bstrProp

String that contains the SID to add to the list of accounts that are refused membership in the application group.
The account name must be in user principal name (UPN) format (for example, "someone@example.com"). The
LookupAccountName function is called to retrieve the domain.
[in, optional] varReserved

Reserved for future use.

Return value
None

Remarks
The application group will never have an account added using this method as a member, even if that account is
specified directly or indirectly by the Members property.
Denying membership to an account in an application group does not prevent that account from being assigned
to a role through a different application group, nor from being granted permission to a resource through
assignment to any other role.
To view the list of account names of accounts that are refused membership in this application group, use the
NonMembersName property.
You must call the Submit method to persist any changes made by this method.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzApplicationGroup::AddPropertyItem method
(azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The AddProper tyItem method adds the specified entity to the specified list.

Syntax
HRESULT AddPropertyItem(
[in] LONG lPropId,
VARIANT varProp,
[in, optional] VARIANT varReserved
);

Parameters
[in] lPropId

Property ID of the list to which to add the entity specified by the varProp parameter. The following table shows
the possible values.

VA L UE M EA N IN G

Can also be added using the AddAppMember method

AZ_PROP_GROUP_APP_MEMBERS

Can also be added using the AddAppNonMember method

AZ_PROP_GROUP_APP_NON_MEMBERS

Can also be added using the AddMember method

AZ_PROP_GROUP_MEMBERS

Can also be added using the AddMemberName method

AZ_PROP_GROUP_MEMBERS_NAME

Can also be added using the AddNonMember method

AZ_PROP_GROUP_NON_MEMBERS

Can also be added using the AddNonMemberName method

AZ_PROP_GROUP_NON_MEMBERS_NAME

varProp

TBD
[in, optional] varReserved

Reserved for future use.

Return value
None

Remarks
You must call the Submit method to persist any changes made by this method.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzApplicationGroup::DeleteAppMember method
(azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The DeleteAppMember method removes the specified IAzApplicationGroup object from the list of application
groups that belong to this application group.

Syntax
HRESULT DeleteAppMember(
[in] BSTR bstrProp,
[in, optional] VARIANT varReserved
);

Parameters
[in] bstrProp

String that contains the Name property of the IAzApplicationGroup object to remove from the list of application
groups that belong to this application group.
[in, optional] varReserved

Reserved for future use.

Return value
None

Remarks
To view the list of application groups that belong to this application group, use the AppMembers property.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll
Redistributable Windows Server 2003 Administration Tools Pack on
Windows XP
 IAzApplicationGroup::DeleteAppNonMember
method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The DeleteAppNonMember method removes the specified IAzApplicationGroup object from the list of
application groups that are refused membership in this application group.

Syntax
HRESULT DeleteAppNonMember(
[in] BSTR bstrProp,
[in, optional] VARIANT varReserved
);

Parameters
[in] bstrProp

String that contains the Name property of the IAzApplicationGroup object to remove from the list of the
application groups that are refused membership in this application group.
[in, optional] varReserved

Reserved for future use.

Return value
None

Remarks
To view the list of application groups that are refused membership in this application group, use the
AppNonMembers property.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll
Redistributable Windows Server 2003 Administration Tools Pack on
Windows XP
 IAzApplicationGroup::DeleteMember method
(azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The DeleteMember method removes the specified security identifier (SID) in text form from the list of accounts
that belong to the application group.

Syntax
HRESULT DeleteMember(
[in] BSTR bstrProp,
[in, optional] VARIANT varReserved
);

Parameters
[in] bstrProp

String that contains the text form of the SID to remove from the list of accounts that belong to the application
group.
[in, optional] varReserved

Reserved for future use.

Return value
None

Remarks
To view the list of SIDs of accounts that belong to this application group in text form, use the Members property.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll
Redistributable Windows Server 2003 Administration Tools Pack on
Windows XP
 IAzApplicationGroup::DeleteMemberName method
(azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The DeleteMemberName method removes the specified account name from the list of accounts that belong
to the application group.

Syntax
HRESULT DeleteMemberName(
[in] BSTR bstrProp,
[in, optional] VARIANT varReserved
);

Parameters
[in] bstrProp

String that contains the account name to remove from the list of accounts that belong to the application group.
The account name must be in user principal name (UPN) format (for example, "someone@example.com"). The
LookupAccountName function is called to retrieve the domain.
[in, optional] varReserved

Reserved for future use.

Return value
None

Remarks
To view the list of account names of accounts that belong to this application group, use the MembersName
property.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib
DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzApplicationGroup::DeleteNonMember method
(azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The DeleteNonMember method removes the specified security identifier (SID) in text form from the list of
accounts that are refused membership in the application group.

Syntax
HRESULT DeleteNonMember(
[in] BSTR bstrProp,
[in, optional] VARIANT varReserved
);

Parameters
[in] bstrProp

String that contains the text form of the SID to remove from the list of accounts that are refused membership in
the application group.
[in, optional] varReserved

Reserved for future use.

Return value
None

Remarks
To view the list of SIDs of accounts that are refused membership in this application group in text form, use the
NonMembers property.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll
Redistributable Windows Server 2003 Administration Tools Pack on
Windows XP
 IAzApplicationGroup::DeleteNonMemberName
method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The DeleteNonMemberName method removes the specified account name from the list of accounts that are
refused membership in the application group.

Syntax
HRESULT DeleteNonMemberName(
[in] BSTR bstrProp,
[in, optional] VARIANT varReserved
);

Parameters
[in] bstrProp

String that contains the account name to remove from the list of accounts that are refused membership in the
application group. The account name must be in user principal name (UPN) format (for example,
"someone@example.com"). The LookupAccountName function is called to retrieve the domain.
[in, optional] varReserved

Reserved for future use.

Return value
None

Remarks
To view the list of account names of accounts that are refused membership in this application group, use the
NonMembersName property.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib
DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzApplicationGroup::DeletePropertyItem method
(azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The DeleteProper tyItem method removes the specified entity from the specified list.

Syntax
HRESULT DeletePropertyItem(
[in] LONG lPropId,
[in] VARIANT varProp,
[in, optional] VARIANT varReserved
);

Parameters
[in] lPropId

Property ID of the list from which to remove the entity specified by the varProp parameter. The following table
shows the possible values.

VA L UE M EA N IN G

Can also be removed using the DeleteAppMember method

AZ_PROP_GROUP_APP_MEMBERS

Can also be removed using the DeleteAppNonMember

AZ_PROP_GROUP_APP_NON_MEMBERS method

Can also be removed using the DeleteMember method

AZ_PROP_GROUP_MEMBERS

Can also be removed using the DeleteMemberName

AZ_PROP_GROUP_MEMBERS_NAME method

Can also be removed using the DeleteNonMember method

AZ_PROP_GROUP_NON_MEMBERS

Can also be removed using the DeleteNonMemberName

AZ_PROP_GROUP_NON_MEMBERS_NAME method

[in] varProp

The entity to remove from the list specified by the lPropId parameter.
The variant must be a BSTR variant.
If AZ_PROP_GROUP_MEMBERS_NAME or AZ_PROP_GROUP_NON_MEMBERS_NAME is specified for the
lPropId parameter, the string is the account name of the account to remove from the list. The account name
must be in user principal name (UPN) format (for example, "someone@example.com"). If
AZ_PROP_GROUP_APP_MEMBERS or AZ_PROP_GROUP_APP_NON_MEMBERS is specified for the lPropId
parameter, the string is the Name property of the IAzApplicationGroup object to remove from the list.
[in, optional] varReserved

Reserved for future use.

Return value
If the method succeeds, the method returns S_OK.
Any other HRESULT value indicates that the operation failed.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzApplicationGroup::get_AppMembers method
(azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The AppMembers property retrieves the application groups that belong to this application group.
This property is read-only.

Syntax
HRESULT get_AppMembers(
VARIANT *pvarProp
);

Parameters
pvarProp

Return value
None

Remarks
This property allows the nesting of IAzApplicationGroup objects within another IAzApplicationGroup object.
In JScript, the returned SAFEARRAY must be converted to the JScript Array object.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzApplicationGroup::get_AppNonMembers
method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The AppNonMembers property retrieves the application groups that are refused membership in this
application group.
This property is read-only.

Syntax
HRESULT get_AppNonMembers(
VARIANT *pvarProp
);

Parameters
pvarProp

Return value
None

Remarks
Denying membership to an account in an application group does not prevent that account from being assigned
to a role through a different application group, nor from being granted permission to a resource through
assignment to any other role.
In JScript, the returned SAFEARRAY must be converted to the JScript Array object.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll
Redistributable Windows Server 2003 Administration Tools Pack on
Windows XP
 IAzApplicationGroup::get_Description method
(azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The Description property sets or retrieves a comment that describes the application group.
This property is read/write.

Syntax
HRESULT get_Description(
BSTR *pbstrDescription
);

Parameters
pbstrDescription

Return value
None

Remarks
The maximum length of the Description property is 1,024 characters.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzApplicationGroup::get_LdapQuery method
(azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The LdapQuer y property sets or retrieves the Lightweight Directory Access Protocol (LDAP) query used to
define membership for an LDAP query application group.
This property is read/write.

Syntax
HRESULT get_LdapQuery(
BSTR *pbstrProp
);

Parameters
pbstrProp

Return value
None

Remarks
This property is ignored unless the Type property is AZ_GROUPTYPE_LDAP_QUERY.
The maximum length of this property is 4,096 characters.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzApplicationGroup::get_Members method
(azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The Members property retrieves the security identifiers (SIDs), in text form, of accounts that belong to the
application group.
This property is read-only.

Syntax
HRESULT get_Members(
VARIANT *pvarProp
);

Parameters
pvarProp

Return value
None

Remarks
This property is ignored unless the Type property is AZ_GROUPTYPE_BASIC.
In JScript, the returned SAFEARRAY must be converted to the JScript Array object.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzApplicationGroup::get_MembersName method
(azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The MembersName property retrieves the account names of accounts that belong to the application group.
This property is read-only.

Syntax
HRESULT get_MembersName(
VARIANT *pvarProp
);

Parameters
pvarProp

Return value
None

Remarks
This property is ignored unless the Type property is AZ_GROUPTYPE_BASIC.
In JScript, the returned SAFEARRAY must be converted to the JScript Array object.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzApplicationGroup::get_Name method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The Name property sets or retrieves the name of the application group.
This property is read/write.

Syntax
HRESULT get_Name(
BSTR *pbstrName
);

Parameters
pbstrName

Return value
None

Remarks
The maximum length of the Name property is 64 characters.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzApplicationGroup::get_NonMembers method
(azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The NonMembers property retrieves the security identifiers (SIDs), in text form, of accounts that are refused
membership in the application group.
This property is read-only.

Syntax
HRESULT get_NonMembers(
VARIANT *pvarProp
);

Parameters
pvarProp

Return value
None

Remarks
The application group will never have an account specified by this property as a member, even if that account is
specified directly or indirectly by the Members property.
This property is ignored unless the Type property is AZ_GROUPTYPE_BASIC.
In JScript, the returned SAFEARRAY must be converted to the JScript Array object.
Denying membership to an account in an application group does not prevent that account from being assigned
to a role through a different application group, nor from being granted permission to a resource through
assignment to any other role.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib
DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzApplicationGroup::get_NonMembersName
method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The NonMembersName property retrieves the account names of accounts that are refused membership in the
application group.
This property is read-only.

Syntax
HRESULT get_NonMembersName(
VARIANT *pvarProp
);

Parameters
pvarProp

Return value
None

Remarks
The application group will never have an account specified by this property as a member, even if that account is
specified directly or indirectly by the Members property.
Denying membership to an account in an application group does not prevent that account from being assigned
to a role through a different application group, nor from being granted permission to a resource through
assignment to any other role.
This property is ignored unless the Type property is AZ_GROUPTYPE_BASIC.
In JScript, the returned SAFEARRAY must be converted to the JScript Array object.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib
DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzApplicationGroup::get_Type method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The Type property sets or retrieves the group type of the application group.
This property is read/write.

Syntax
HRESULT get_Type(
LONG *plProp
);

Parameters
plProp

Return value
None

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzApplicationGroup::get_Writable method
(azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The Writable property retrieves a value that indicates whether the application group can be modified by the
user context that initialized it.
This property is read-only.

Syntax
HRESULT get_Writable(
BOOL *pfProp
);

Parameters
pfProp

Return value
None

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzApplicationGroup::GetProperty method
(azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The GetProper ty method returns the IAzApplicationGroup object property with the specified property ID.

Syntax
HRESULT GetProperty(
[in] LONG lPropId,
[in, optional] VARIANT varReserved,
[out] VARIANT *pvarProp
);

Parameters
[in] lPropId

Property ID of the IAzApplicationGroup object property to return. The following table shows the possible values.

VA L UE M EA N IN G

Determines whether the current user has permission to

AZ_PROP_CHILD_CREATE create child objects. This value will always be FALSE because
this object cannot have child objects.

Also accessed through the Description property

AZ_PROP_DESCRIPTION

Also accessed through the AppMembers property

AZ_PROP_GROUP_APP_MEMBERS

Also accessed through the AppNonMembers property

AZ_PROP_GROUP_APP_NON_MEMBERS

Also accessed through the Members property

AZ_PROP_GROUP_MEMBERS

Also accessed through the MembersName property

AZ_PROP_GROUP_MEMBERS_NAME

Also accessed through the NonMembers property

AZ_PROP_GROUP_NON_MEMBERS

Also accessed through the NonMembersName property

AZ_PROP_GROUP_NON_MEMBERS_NAME
 Also accessed through the Type property
AZ_PROP_GROUP_TYPE

Also accessed through the LdapQuery property

AZ_PROP_GROUP_LDAP_QUERY

Also accessed through the Name property

AZ_PROP_NAME

Also accessed through the Writable property

AZ_PROP_WRITABLE

[in, optional] varReserved

Reserved for future use.

[out] pvarProp

A pointer to the returned IAzApplicationGroup object property.

Return value
If the method succeeds, the method returns S_OK.
Any other HRESULT value indicates that the operation failed.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzApplicationGroup::put_Description method
(azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The Description property sets or retrieves a comment that describes the application group.
This property is read/write.

Syntax
HRESULT put_Description(
BSTR bstrDescription
);

Parameters
bstrDescription

Return value
None

Remarks
The maximum length of the Description property is 1,024 characters.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzApplicationGroup::put_LdapQuery method
(azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The LdapQuer y property sets or retrieves the Lightweight Directory Access Protocol (LDAP) query used to
define membership for an LDAP query application group.
This property is read/write.

Syntax
HRESULT put_LdapQuery(
BSTR bstrProp
);

Parameters
bstrProp

Return value
None

Remarks
This property is ignored unless the Type property is AZ_GROUPTYPE_LDAP_QUERY.
The maximum length of this property is 4,096 characters.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzApplicationGroup::put_Name method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The Name property sets or retrieves the name of the application group.
This property is read/write.

Syntax
HRESULT put_Name(
BSTR bstrName
);

Parameters
bstrName

Return value
None

Remarks
The maximum length of the Name property is 64 characters.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzApplicationGroup::put_Type method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The Type property sets or retrieves the group type of the application group.
This property is read/write.

Syntax
HRESULT put_Type(
LONG lProp
);

Parameters
lProp

Return value
None

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzApplicationGroup::SetProperty method
(azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The SetProper ty method sets the specified value to the IAzApplicationGroup object property with the specified
property ID.

Syntax
HRESULT SetProperty(
[in] LONG lPropId,
[in] VARIANT varProp,
[in, optional] VARIANT varReserved
);

Parameters
[in] lPropId

Property ID of the IAzApplicationGroup object property to set. The following table shows the possible values.

VA L UE M EA N IN G

Also accessed through the Description property

AZ_PROP_DESCRIPTION

Also accessed through the Type property

AZ_PROP_GROUP_TYPE

Also accessed through the LdapQuery property

AZ_PROP_GROUP_LDAP_QUERY

Also accessed through the Name property

AZ_PROP_NAME

[in] varProp

Value to set to the IAzApplicationGroup object property specified by the lPropId parameter. The following table
shows the type of data that must be used depending on the value of the lPropId parameter.

L P RO P ID VA L UE DATA T Y P E ( C ++/ VISUA L B A SIC )

BSTR/String
AZ_PROP_DESCRIPTION

BSTR/String
AZ_PROP_GROUP_LDAP_QUERY
 LONG /Long
AZ_PROP_GROUP_TYPE

BSTR/String
AZ_PROP_NAME

[in, optional] varReserved

Reserved for future use.

Return value
If the method succeeds, the method returns S_OK.
Any other HRESULT value indicates that the operation failed.

Remarks
You must call the Submit method to persist any changes made by this method.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzApplicationGroup::Submit method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The Submit method persists changes made to the IAzApplicationGroup object.

Syntax
HRESULT Submit(
[in, optional] LONG lFlags,
[in, optional] VARIANT varReserved
);

Parameters
[in, optional] lFlags

Flags that modify the behavior of the Submit method. The default value is zero. If the AZ_SUBMIT_FLAG_ABORT
flag is specified, the changes to the object are discarded and the object is updated to match the underlying
policy store.
[in, optional] varReserved

Reserved for future use.

Return value
None

Remarks
Any additions or modifications to an IAzApplicationGroup object are not persisted until the Submit method is
called.
A created IAzApplicationGroup object must be submitted before it can be referenced. The destructor for an
object silently discards unsubmitted changes.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib
DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzApplicationGroup2 interface (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The IAzApplicationGroup2 interface extends the IAzApplicationGroup interface by adding support for the
BizRule group type. This interface also adds a method that gets the role assignments associated with the
application group.

Inheritance
The IAzApplicationGroup2 interface inherits from the IAzApplicationGroup interface.

Methods
The IAzApplicationGroup2 interface has these methods.

IAzApplicationGroup2::get_BizRule

Gets or sets the script that determines membership for this application group.

IAzApplicationGroup2::get_BizRuleImportedPath

Gets or sets the path of the file that contains the business rule script associated with this application group.

IAzApplicationGroup2::get_BizRuleLanguage

Gets or sets the programming language of the business rule script associated with this application group.

IAzApplicationGroup2::put_BizRule

Gets or sets the script that determines membership for this application group.

IAzApplicationGroup2::put_BizRuleImportedPath

Gets or sets the path of the file that contains the business rule script associated with this application group.

IAzApplicationGroup2::put_BizRuleLanguage

Gets or sets the programming language of the business rule script associated with this application group.

IAzApplicationGroup2::RoleAssignments

Gets a collection of IAzRoleAssignment objects associated with this application group.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header azroles.h
 IAzApplicationGroup2::get_BizRule method
(azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The BizRule property gets or sets the script that determines membership for this application group.
This property is read/write.

Syntax
HRESULT get_BizRule(
BSTR *pbstrProp
);

Parameters
pbstrProp

Return value
None

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header azroles.h
 IAzApplicationGroup2::get_BizRuleImportedPath
method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The BizRuleImpor tedPath method gets or sets the path of the file that contains the business rule script
associated with this application group.
This property is read/write.

Syntax
HRESULT get_BizRuleImportedPath(
BSTR *pbstrProp
);

Parameters
pbstrProp

Return value
None

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header azroles.h
 IAzApplicationGroup2::get_BizRuleLanguage
method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The BizRuleLanguage method gets or sets the programming language of the business rule script associated
with this application group. The value of this property can be either "VBScript" or "JScript".
This property is read/write.

Syntax
HRESULT get_BizRuleLanguage(
BSTR *pbstrProp
);

Parameters
pbstrProp

Return value
None

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header azroles.h
 IAzApplicationGroup2::put_BizRule method
(azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The BizRule property gets or sets the script that determines membership for this application group.
This property is read/write.

Syntax
HRESULT put_BizRule(
BSTR bstrProp
);

Parameters
bstrProp

Return value
None

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header azroles.h
 IAzApplicationGroup2::put_BizRuleImportedPath
method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The BizRuleImpor tedPath method gets or sets the path of the file that contains the business rule script
associated with this application group.
This property is read/write.

Syntax
HRESULT put_BizRuleImportedPath(
BSTR bstrProp
);

Parameters
bstrProp

Return value
None

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header azroles.h
 IAzApplicationGroup2::put_BizRuleLanguage
method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The BizRuleLanguage method gets or sets the programming language of the business rule script associated
with this application group. The value of this property can be either "VBScript" or "JScript".
This property is read/write.

Syntax
HRESULT put_BizRuleLanguage(
BSTR bstrProp
);

Parameters
bstrProp

Return value
None

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header azroles.h
 IAzApplicationGroup2::RoleAssignments method
(azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The RoleAssignments method gets a collection of IAzRoleAssignment objects associated with this application
group.
This property is read-only.

Syntax
HRESULT RoleAssignments(
BSTR bstrScopeName,
VARIANT_BOOL bRecursive,
IAzRoleAssignments **ppRoleAssignments
);

Parameters
bstrScopeName

bRecursive

ppRoleAssignments

Return value
None

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header azroles.h
 IAzApplicationGroups interface (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The IAzApplicationGroups interface represents a collection of

IAzApplicationGroup objects.

Inheritance
The IAzApplicationGroups interface inherits from the IDispatch interface. IAzApplicationGroups also has
these types of members:

Methods
The IAzApplicationGroups interface has these methods.

IAzApplicationGroups::get__NewEnum

Retrieves an IEnumVARIANT interface on an object that can be used to enumerate the collection. This property is hidden
within Visual Basic and Visual Basic Scripting Edition (VBScript).

IAzApplicationGroups::get_Count

Retrieves the number of IAzApplicationGroup objects in the collection.

IAzApplicationGroups::get_Item

Retrieves the IAzApplicationGroup object at the specified index into the IAzApplicationGroups collection.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzApplicationGroups::get__NewEnum method
(azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The _NewEnum property retrieves an IEnumVARIANT interface on an object that can be used to enumerate the
collection. This property is hidden within Visual Basic and Visual Basic Scripting Edition (VBScript).
This property is read-only.

Syntax
HRESULT get__NewEnum(
LPUNKNOWN *ppEnumPtr
);

Parameters
ppEnumPtr

Return value
None

Remarks
This property is provided for use by the For Each keyword in Visual Basic and the foreach keyword in Visual
C#.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzApplicationGroups::get_Count method
(azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The Count property retrieves the number of IAzApplicationGroup objects in the collection.
This property is read-only.

Syntax
HRESULT get_Count(
LONG *plCount
);

Parameters
plCount

Return value
None

Remarks
The Count property can be used to specify the last IAzApplicationGroup object in a collection when retrieving a
specific IAzApplicationGroup object using the IAzApplicationGroups.Item property.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzApplicationGroups::get_Item method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The Item property retrieves the IAzApplicationGroup object at the specified index into the IAzApplicationGroups
collection.
This property is read-only.

Syntax
HRESULT get_Item(
LONG Index,
VARIANT *pvarObtPtr
);

Parameters
Index

pvarObtPtr

Return value
None

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzApplications interface (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The IAzApplications interface represents a collection of

IAzApplication objects.

Inheritance
The IAzApplications interface inherits from the IDispatch interface. IAzApplications also has these types of
members:

Methods
The IAzApplications interface has these methods.

IAzApplications::get__NewEnum

Retrieves an IEnumVARIANT interface on an object that can be used to enumerate the collection. This property is hidden
within Visual Basic and Visual Basic Scripting Edition (VBScript).

IAzApplications::get_Count

Retrieves the number of IAzApplication objects in the collection.

IAzApplications::get_Item

Retrieves the IAzApplication object at the specified index into the IAzApplications collection.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzApplications::get__NewEnum method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The _NewEnum property retrieves an IEnumVARIANT interface on an object that can be used to enumerate the
collection. This property is hidden within Visual Basic and Visual Basic Scripting Edition (VBScript).
This property is read-only.

Syntax
HRESULT get__NewEnum(
LPUNKNOWN *ppEnumPtr
);

Parameters
ppEnumPtr

Return value
None

Remarks
This property is provided for use by the For Each keyword in Visual Basic and the foreach keyword in Visual
C#.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzApplications::get_Count method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The Count property retrieves the number of IAzApplication objects in the collection.
This property is read-only.

Syntax
HRESULT get_Count(
long *plCount
);

Parameters
plCount

Return value
None

Remarks
The Count property can be used to specify the last IAzApplication object in a collection when retrieving a
specific IAzApplication object using the IAzApplications.Item property.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzApplications::get_Item method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The Item property retrieves the IAzApplication object at the specified index into the IAzApplications collection.
This property is read-only.

Syntax
HRESULT get_Item(
long Index,
VARIANT *pvarObtPtr
);

Parameters
Index

pvarObtPtr

Return value
None

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzAuthorizationStore interface (azroles.h)
7/2/2022 • 4 minutes to read • Edit Online

The AzAuthorizationStore object defines the container that is the root of the authorization policy store.

Inheritance
The IAzAuthorizationStore interface inherits from the IUnknown interface. IAzAuthorizationStore also has
these types of members:

Methods
The IAzAuthorizationStore interface has these methods.

IAzAuthorizationStore::AddDelegatedPolicyUser

Adds the specified security identifier (SID) in text form to the list of principals that act as delegated policy users.

IAzAuthorizationStore::AddDelegatedPolicyUserName

Adds the specified account name to the list of principals that act as delegated policy users.

IAzAuthorizationStore::AddPolicyAdministrator

Adds the specified security identifier (SID) in text form to the list of principals that act as policy administrators.

IAzAuthorizationStore::AddPolicyAdministratorName

Adds the specified account name to the list of principals that act as policy administrators.

IAzAuthorizationStore::AddPolicyReader

Adds the specified security identifier (SID) in text form to the list of principals that act as policy readers.

IAzAuthorizationStore::AddPolicyReaderName

Adds the specified account name to the list of principals that act as policy readers.

IAzAuthorizationStore::AddPropertyItem

Adds the specified principal to the specified list of principals.

IAzAuthorizationStore::CloseApplication

Unloads a specified IAzApplication object from the cache.

IAzAuthorizationStore::CreateApplication

Creates an IAzApplication object with the specified name.

IAzAuthorizationStore::CreateApplicationGroup

Creates an IAzApplicationGroup object with the specified name.

IAzAuthorizationStore::Delete

Deletes the policy store currently in use by the AzAuthorizationStore object.

IAzAuthorizationStore::DeleteApplication

Removes the IAzApplication object with the specified name from the AzAuthorizationStore object.

IAzAuthorizationStore::DeleteApplicationGroup

Removes the IAzApplicationGroup object with the specified name from the AzAuthorizationStore object.

IAzAuthorizationStore::DeleteDelegatedPolicyUser

Removes the specified security identifier (SID) in text form from the list of principals that act as delegated policy users.

IAzAuthorizationStore::DeleteDelegatedPolicyUserName

Removes the specified account name from the list of principals that act as delegated policy users.

IAzAuthorizationStore::DeletePolicyAdministrator

Removes the specified security identifier (SID) in text form from the list of principals that act as policy administrators.

IAzAuthorizationStore::DeletePolicyAdministratorName

Removes the specified account name from the list of principals that act as policy administrators.

IAzAuthorizationStore::DeletePolicyReader

Removes the specified security identifier (SID) in text form from the list of principals that act as policy readers.

IAzAuthorizationStore::DeletePolicyReaderName

Removes the specified account name from the list of principals that act as policy readers.

IAzAuthorizationStore::DeletePropertyItem

Removes the specified principal from the specified list of principals.

IAzAuthorizationStore::get_ApplicationData

Sets or retrieves an opaque field that can be used by the application to store information.

IAzAuthorizationStore::get_ApplicationGroups

Retrieves an IAzApplicationGroups object that is used to enumerate IAzApplicationGroup objects from the policy data.

IAzAuthorizationStore::get_Applications

Retrieves an IAzApplications object that is used to enumerate IAzApplication objects from the policy store.
IAzAuthorizationStore::get_ApplyStoreSacl

Sets or retrieves a value that indicates whether policy audits should be generated when the authorization store is modified.

IAzAuthorizationStore::get_DelegatedPolicyUsers

Retrieves the security identifiers (SIDs) of principals that act as delegated policy users in text form.

IAzAuthorizationStore::get_DelegatedPolicyUsersName

Retrieves the account names of principals that act as delegated policy users.

IAzAuthorizationStore::get_Description

Sets or retrieves a comment that describes the operation.

IAzAuthorizationStore::get_DomainTimeout

Sets or retrieves the time in milliseconds after which a domain is determined to be unreachable.

IAzAuthorizationStore::get_GenerateAudits

Sets or retrieves a value that indicates whether run-time audits should be generated.

IAzAuthorizationStore::get_MaxScriptEngines

Sets or retrieves the maximum number of Business Rule (BizRule) script engines that will be cached.

IAzAuthorizationStore::get_PolicyAdministrators

Retrieves the security identifiers (SIDs) of principals that act as policy administrators in text form.

IAzAuthorizationStore::get_PolicyAdministratorsName

Retrieves the account names of principals that act as policy administrators.

IAzAuthorizationStore::get_PolicyReaders

Retrieves the security identifiers (SIDs) of principals that act as policy readers in text form.

IAzAuthorizationStore::get_PolicyReadersName

Retrieves the account names of principals that act as policy readers.

IAzAuthorizationStore::get_ScriptEngineTimeout

Sets or retrieves the time in milliseconds that the IAzClientContext::AccessCheck method will wait for a Business Rule (BizRule)
to complete execution before canceling it.

IAzAuthorizationStore::get_TargetMachine

Retrieves the name of the computer on which account resolution should occur.
IAzAuthorizationStore::get_Writable

Retrieves a value that indicates whether the object can be modified by the user context that called the Initialize method.

IAzAuthorizationStore::GetProperty

Returns the AzAuthorizationStore object property with the specified property ID.

IAzAuthorizationStore::Initialize

Initializes the authorization manager.

IAzAuthorizationStore::OpenApplication

Opens the IAzApplication object with the specified name.

IAzAuthorizationStore::OpenApplicationGroup

Opens an IAzApplicationGroup object by specifying its name.

IAzAuthorizationStore::put_ApplicationData

Sets or retrieves an opaque field that can be used by the application to store information.

IAzAuthorizationStore::put_ApplyStoreSacl

Sets or retrieves a value that indicates whether policy audits should be generated when the authorization store is modified.

IAzAuthorizationStore::put_Description

Sets or retrieves a comment that describes the operation.

IAzAuthorizationStore::put_DomainTimeout

Sets or retrieves the time in milliseconds after which a domain is determined to be unreachable.

IAzAuthorizationStore::put_GenerateAudits

Sets or retrieves a value that indicates whether run-time audits should be generated.

IAzAuthorizationStore::put_MaxScriptEngines

Sets or retrieves the maximum number of Business Rule (BizRule) script engines that will be cached.

IAzAuthorizationStore::put_ScriptEngineTimeout

Sets or retrieves the time in milliseconds that the IAzClientContext::AccessCheck method will wait for a Business Rule (BizRule)
to complete execution before canceling it.

IAzAuthorizationStore::SetProperty

Sets the specified value to the AzAuthorizationStore object property with the specified property ID.
 IAzAuthorizationStore::Submit

Persists changes made to the AzAuthorizationStore object.

IAzAuthorizationStore::UpdateCache

Updates the cache of objects and object attributes to match the underlying policy store.

Remarks
The AzAuthorizationStore object is named according to the URL passed to the Initialize method. The object
has no name within the policy store.
The application must ensure that the user context from which the Initialize method is called is used for all future
access to the AzAuthorizationStore object, except for the IAzApplication::InitializeClientContextFromToken
method.

Note If an XML store is used over a network, the traffic is not automatically encrypted. IPsec can be used to encrypt the
authorization information in transit.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzAuthorizationStore::AddDelegatedPolicyUser
method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The AddDelegatedPolicyUser method adds the specified security identifier (SID) in text form to the list of
principals that act as delegated policy users.

Syntax
HRESULT AddDelegatedPolicyUser(
[in] BSTR bstrDelegatedPolicyUser,
[in, optional] VARIANT varReserved
);

Parameters
[in] bstrDelegatedPolicyUser

Text form of the SID to add to the list of delegated policy users.
[in, optional] varReserved

Reserved for future use.

Return value
None

Remarks
Delegated policy users are principals that are allowed to read the subset of the policy data that the policy
administrator of an IAzApplication or IAzScope object uses to administer the delegated object.

Note Delegated policy users are not supported for XML stores.

To view the list of delegated policy users, use the DelegatedPolicyUsers property.
You must call the Submit method to persist any changes made by this method.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzAuthorizationStore::AddDelegatedPolicyUserName
method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The AddDelegatedPolicyUserName method adds the specified account name to the list of principals that act
as delegated policy users.
This method is an alternate version of the AddDelegatedPolicyUser method.

Syntax
HRESULT AddDelegatedPolicyUserName(
[in] BSTR bstrDelegatedPolicyUser,
[in, optional] VARIANT varReserved
);

Parameters
[in] bstrDelegatedPolicyUser

Account name to add to the list of delegated policy users. The account name must be in user principal name
(UPN) format (for example, "someone@example.com"). The LookupAccountName function is called to retrieve
the domain.
[in, optional] varReserved

Reserved for future use.

Return value
If the method succeeds, the method returns S_OK.
An attempt to call this method on an XML store will return E_INVALIDARG.
If the method fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.

Remarks
Delegated policy users are principals that are allowed to read the subset of the policy data that the policy
administrator of an IAzApplication or IAzScope object uses to administer the delegated object.

Note Delegated policy users are not supported for XML stores.

To view the list of delegated policy users in account name format, use the DelegatedPolicyUsersName property.
You must call the Submit method to persist any changes made by this method.

Requirements
Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzAuthorizationStore::AddPolicyAdministrator
method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The AddPolicyAdministrator method adds the specified security identifier (SID) in text form to the list of
principals that act as policy administrators.

Syntax
HRESULT AddPolicyAdministrator(
[in] BSTR bstrAdmin,
[in, optional] VARIANT varReserved
);

Parameters
[in] bstrAdmin

Text form of the SID to add to the list of policy administrators.

[in, optional] varReserved

Reserved for future use.

Return value
None

Remarks
Policy administrators for an object can perform the following tasks:
Read the object
Write attributes to the object
Read attributes of child objects of the object
Write attributes to child objects of the object
Delete the object
Delete child objects of the object
Create child objects of the object
To view the list of policy administrators, use the PolicyAdministrators property.
You must call the Submit method to persist any changes made by this method.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzAuthorizationStore::AddPolicyAdministratorName
method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The AddPolicyAdministratorName method adds the specified account name to the list of principals that act
as policy administrators.
This method is an alternate version of the AddPolicyAdministrator method.

Syntax
HRESULT AddPolicyAdministratorName(
[in] BSTR bstrAdmin,
[in, optional] VARIANT varReserved
);

Parameters
[in] bstrAdmin

Account name to add to the list of policy administrators. The account name must be in user principal name
(UPN) format (for example, "someone@example.com"). The LookupAccountName function is called to retrieve
the domain.
[in, optional] varReserved

Reserved for future use.

Return value
If the method succeeds, the method returns S_OK.
Any other HRESULT value indicates that the operation failed.

Remarks
Policy administrators for an object can perform the following tasks:
Read the object
Write attributes to the object
Read attributes of child objects of the object
Write attributes to child objects of the object
Delete the object
Delete child objects of the object
Create child objects of the object
To view the list of policy administrators in account name format, use the PolicyAdministratorsName property.
You must call the Submit method to persist any changes made by this method.
Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzAuthorizationStore::AddPolicyReader method
(azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The AddPolicyReader method adds the specified security identifier (SID) in text form to the list of principals
that act as policy readers.

Syntax
HRESULT AddPolicyReader(
[in] BSTR bstrReader,
[in, optional] VARIANT varReserved
);

Parameters
[in] bstrReader

Text form of the SID to add to the list of policy readers.

[in, optional] varReserved

Reserved for future use.

Return value
None

Remarks
Policy readers for an object can read attributes for the object and for child objects of the object. Readers can also
use the policy; for example, readers can call the AccessCheck method. Readers cannot modify the object or its
child objects.
To view the list of policy readers, use the PolicyReaders property.
You must call the Submit method to persist any changes made by this method.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h
Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzAuthorizationStore::AddPolicyReaderName
method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The AddPolicyReaderName method adds the specified account name to the list of principals that act as policy
readers.

Syntax
HRESULT AddPolicyReaderName(
[in] BSTR bstrReader,
[in, optional] VARIANT varReserved
);

Parameters
[in] bstrReader

Account name to add to the list of policy readers. The account name must be in user principal name (UPN)
format (for example, "someone@example.com"). The LookupAccountName function is called to retrieve the
domain.
[in, optional] varReserved

Reserved for future use.

Return value
If the method succeeds, the method returns S_OK.
If the method fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.

Remarks
Policy readers for an object can read attributes for the object and for child objects of the object. Readers can also
use the policy; for example, readers can call the AccessCheck method. Readers cannot modify the object or its
child objects.
To view the list of policy readers in account name format, use the PolicyReadersName property.
You must call the Submit method to persist any changes made by this method.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]
Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzAuthorizationStore::AddPropertyItem method
(azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The AddProper tyItem method adds the specified principal to the specified list of principals.

Syntax
HRESULT AddPropertyItem(
[in] LONG lPropId,
[in] VARIANT varProp,
[in, optional] VARIANT varReserved
);

Parameters
[in] lPropId

Property ID of the list of principals to which to add the principal specified by the varProp parameter. This
parameter can be one of the following values.

VA L UE M EA N IN G

Can also be added by using the AddPolicyAdministrator

AZ_PROP_POLICY_ADMINS method.

Can also be added by using the

AZ_PROP_POLICY_ADMINS_NAME AddPolicyAdministratorName method.

Can also be added by using the AddPolicyReader method.

AZ_PROP_POLICY_READERS

Can also be added by using the AddPolicyReaderName

AZ_PROP_POLICY_READERS_NAME method.

Can also be added by using the AddDelegatedPolicyUser

AZ_PROP_DELEGATED_POLICY_USERS method.

Can also be added by using the

AZ_PROP_DELEGATED_POLICY_USERS_NAME AddDelegatedPolicyUserName method.

[in] varProp

Principal to add to the list of principals specified by the lPropId parameter.

The variant must be a BSTR variant.
If AZ_PROP_POLICY_ADMINS_NAME, AZ_PROP_POLICY_READERS_NAME, or
AZ_PROP_DELEGATED_POLICY_USERS_NAME is specified for the lPropId parameter, the string is the account
name of the account to add to the list. The account name must be in user principal name (UPN) format (for
example, "someone@example.com").
[in, optional] varReserved

Reserved for future use.

Return value
If the method succeeds, the method returns S_OK.
If the method fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.

Remarks
You must call the Submit method to persist any changes made by this method.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzAuthorizationStore::CloseApplication method
(azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The CloseApplication method unloads a specified IAzApplication object from the cache.
This method is not supported for XML authorization policy stores.

Syntax
HRESULT CloseApplication(
[in] BSTR bstrApplicationName,
[in] LONG lFlag
);

Parameters
[in] bstrApplicationName

The name of the IAzApplication object to close.

[in] lFlag

Flags that control the behavior of the operation. The following table shows the possible values.

VA L UE M EA N IN G

Child objects of the specified IAzApplication object will be

0 unloaded from the cache only when the user closes the last
handle to the IAzApplication object.

All child objects of the specified IAzApplication object will be

AZ_AZSTORE_FORCE_APPLICATION_CLOSE
forcefully closed. Attempts to reference an open handle to a
child object of the specified IAzApplication object will result
in an HRESULT_FROM_WIN32(ERROR_INVALID_HANDLE)
error. This flag should be used only if the user has
implemented code to gracefully handle the error.

Return value
None

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]
Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzAuthorizationStore::CreateApplication method
(azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The CreateApplication method creates an IAzApplication object with the specified name.

Syntax
HRESULT CreateApplication(
[in] BSTR bstrApplicationName,
[in, optional] VARIANT varReserved,
[out] IAzApplication **ppApplication
);

Parameters
[in] bstrApplicationName

Name for the new IAzApplication object.

[in, optional] varReserved

Reserved for future use.

[out] ppApplication

A pointer to a pointer to the created IAzApplication object.

Return value
If the method succeeds, the method returns S_OK.
Any other HRESULT value indicates that the operation failed.

Remarks
You must call the IAzApplication::Submit method to persist any changes made by the returned object.
The returned IAzApplication object is an immediate child object of the AzAuthorizationStore object.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzAuthorizationStore::CreateApplicationGroup
method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The CreateApplicationGroup method creates an IAzApplicationGroup object with the specified name.

Syntax
HRESULT CreateApplicationGroup(
[in] BSTR bstrGroupName,
[in, optional] VARIANT varReserved,
[out] IAzApplicationGroup **ppGroup
);

Parameters
[in] bstrGroupName

Name for the new IAzApplicationGroup object.

[in, optional] varReserved

Reserved for future use.

[out] ppGroup

A pointer to a pointer to the created IAzApplicationGroup object.

Return value
If the method succeeds, the method returns S_OK.
Any other HRESULT value indicates that the operation failed.

Remarks
You must call the IAzApplicationGroup::Submit method to persist any changes made to the returned object.
The returned IAzApplicationGroup object is an immediate child object of the AzAuthorizationStore object.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzAuthorizationStore::Delete method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The Delete method deletes the policy store currently in use by the AzAuthorizationStore object.

Syntax
HRESULT Delete(
[in, optional] VARIANT varReserved
);

Parameters
[in, optional] varReserved

Reserved for future use.

Return value
None

Remarks
When the Delete method is called, the AzAuthorizationStore object returns to an uninitialized state. The Initialize
method can then be called to reinitialize the object.

Impor tant All objects opened by clients on the policy store (for example, IAzApplication objects created using
CreateApplication) must be released before you call the Delete method. If the Delete method is called on an
AzAuthorizationStore object whose current policy store contains child objects,
HRESULT_FROM_WIN32(ERROR_SERVER_HAS_OPEN_HANDLES) is returned.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll
Redistributable Windows Server 2003 Administration Tools Pack on
Windows XP
 IAzAuthorizationStore::DeleteApplication method
(azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The DeleteApplication method removes the IAzApplication object with the specified name from the
AzAuthorizationStore object.

Syntax
HRESULT DeleteApplication(
[in] BSTR bstrApplicationName,
[in, optional] VARIANT varReserved
);

Parameters
[in] bstrApplicationName

Name of the IAzApplication object to delete.

[in, optional] varReserved

Reserved for future use.

Return value
None

Remarks
If the deleted IAzApplication object has child objects, those objects are deleted, as well. If there are any
IAzApplication references to an IAzApplication object that has been deleted from the cache, the
IAzApplication object can no longer be used. In C++, you must release references to deleted IAzApplication
objects by calling the IUnknown::Release method. In Visual Basic, references to deleted objects are automatically
released.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib
DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzAuthorizationStore::DeleteApplicationGroup
method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The DeleteApplicationGroup method removes the IAzApplicationGroup object with the specified name from
the AzAuthorizationStore object.

Syntax
HRESULT DeleteApplicationGroup(
[in] BSTR bstrGroupName,
[in, optional] VARIANT varReserved
);

Parameters
[in] bstrGroupName

Name of the IAzApplicationGroup object to delete.

[in, optional] varReserved

Reserved for future use.

Return value
None

Remarks
If there are any IAzApplicationGroup references to an IAzApplicationGroup object that has been deleted from
the cache, the IAzApplicationGroup object can no longer be used. In C++, you must release references to
deleted IAzApplicationGroup objects by calling the IUnknown::Release method. In Visual Basic, references to
deleted objects are automatically released.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib
DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzAuthorizationStore::DeleteDelegatedPolicyUser
method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The DeleteDelegatedPolicyUser method removes the specified security identifier (SID) in text form from the
list of principals that act as delegated policy users.

Syntax
HRESULT DeleteDelegatedPolicyUser(
[in] BSTR bstrDelegatedPolicyUser,
[in, optional] VARIANT varReserved
);

Parameters
[in] bstrDelegatedPolicyUser

Text form of the SID to remove from the list of delegated policy users.
[in, optional] varReserved

Reserved for future use.

Return value
None

Remarks
Delegated policy users are principals that are allowed to read the subset of the policy data that the policy
administrator of an IAzApplication or IAzScope object uses to administer the delegated object.

Note Delegated policy users are not supported for XML stores.

To view the list of delegated policy users, use the DelegatedPolicyUsers property.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzAuthorizationStore::DeleteDelegatedPolicyUserName
method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The DeleteDelegatedPolicyUserName method removes the specified account name from the list of
principals that act as delegated policy users.

Syntax
HRESULT DeleteDelegatedPolicyUserName(
[in] BSTR bstrDelegatedPolicyUser,
[in, optional] VARIANT varReserved
);

Parameters
[in] bstrDelegatedPolicyUser

Account name to remove from the list of delegated policy users. The account name must be in user principal
name (UPN) format (for example, "someone@example.com"). The LookupAccountName function is called to
retrieve the domain.
[in, optional] varReserved

Reserved for future use.

Return value
If the method succeeds, the method returns S_OK.
An attempt to call this method on an XML store will return E_INVALIDARG.
If the method fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.

Remarks
Delegated policy users are principals that are allowed to read the subset of the policy data that the policy
administrator of an IAzApplication or IAzScope object uses to administer the delegated object.

Note Delegated policy users are not supported for XML stores.

To view the list of delegated policy users in account name format, use the DelegatedPolicyUsersName property.

Requirements
Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzAuthorizationStore::DeletePolicyAdministrator
method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The DeletePolicyAdministrator method removes the specified security identifier (SID) in text form from the
list of principals that act as policy administrators.

Syntax
HRESULT DeletePolicyAdministrator(
[in] BSTR bstrAdmin,
[in, optional] VARIANT varReserved
);

Parameters
[in] bstrAdmin

Text form of the SID to remove from the list of policy administrators.
[in, optional] varReserved

Reserved for future use.

Return value
None

Remarks
Policy administrators for an object can perform the following tasks:
Read the object
Write attributes to the object
Read attributes of child objects of the object
Write attributes to child objects of the object
Delete the object
Delete child objects of the object
Create child objects of the object
To view the list of policy administrators, use the PolicyAdministrators property.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]
Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzAuthorizationStore::DeletePolicyAdministratorName
method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The DeletePolicyAdministratorName method removes the specified account name from the list of principals
that act as policy administrators.

Syntax
HRESULT DeletePolicyAdministratorName(
[in] BSTR bstrAdmin,
[in, optional] VARIANT varReserved
);

Parameters
[in] bstrAdmin

The account name to remove from the list of policy administrators. The account name must be in user principal
name (UPN) format (for example, "someone@example.com"). The LookupAccountName function is called to
retrieve the domain.
[in, optional] varReserved

Reserved for future use.

Return value
If the method succeeds, the method returns S_OK.
Any other HRESULT value indicates that the operation failed.

Remarks
Policy administrators for an object can perform the following tasks:
Read the object
Write attributes to the object
Read attributes of child objects of the object
Write attributes to child objects of the object
Delete the object
Delete child objects of the object
Create child objects of the object
To view the list of policy administrators in account name format, use the PolicyAdministratorsName property.

Requirements
Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzAuthorizationStore::DeletePolicyReader method
(azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The DeletePolicyReader method removes the specified security identifier (SID) in text form from the list of
principals that act as policy readers.

Syntax
HRESULT DeletePolicyReader(
[in] BSTR bstrReader,
[in, optional] VARIANT varReserved
);

Parameters
[in] bstrReader

Text form of the SID to remove from the list of policy readers.
[in, optional] varReserved

Reserved for future use.

Return value
None

Remarks
Policy readers for an object can read attributes for the object and for child objects of the object. Readers can also
use the policy; for example, readers can call the AccessCheck method. Readers cannot modify the object or its
child objects.
To view the list of policy readers, use the PolicyReaders property.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib
DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzAuthorizationStore::DeletePolicyReaderName
method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The DeletePolicyReaderName method removes the specified account name from the list of principals that act
as policy readers.

Syntax
HRESULT DeletePolicyReaderName(
[in] BSTR bstrReader,
[in, optional] VARIANT varReserved
);

Parameters
[in] bstrReader

The account name to remove from the list of policy readers. The account name must be in user principal name
(UPN) format (for example, "someone@example.com"). The LookupAccountName function is called to retrieve
the domain.
[in, optional] varReserved

Reserved for future use.

Return value
If the method succeeds, the method returns S_OK.
Any other HRESULT value indicates that the operation failed.

Remarks
Policy readers for an object can read attributes for the object and for child objects of the object. Readers can also
use the policy; for example, readers can call the AccessCheck method. Readers cannot modify the object or its
child objects.
To view the list of policy readers in account name format, use the PolicyReadersName property.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzAuthorizationStore::DeletePropertyItem method
(azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The DeleteProper tyItem method removes the specified principal from the specified list of principals.

Syntax
HRESULT DeletePropertyItem(
[in] LONG lPropId,
[in] VARIANT varProp,
[in, optional] VARIANT varReserved
);

Parameters
[in] lPropId

Property ID of the list of principals from which to remove the principal specified by the varProp parameter. The
following table shows the possible values.

VA L UE M EA N IN G

Can also be removed using the DeletePolicyAdministrator

AZ_PROP_POLICY_ADMINS method

Can also be removed using the

AZ_PROP_POLICY_ADMINS_NAME DeletePolicyAdministratorName method

Can also be removed using the DeletePolicyReader method

AZ_PROP_POLICY_READERS

Can also be removed using the DeletePolicyReaderName

AZ_PROP_POLICY_READERS_NAME method

Can also be removed using the DeleteDelegatedPolicyUser

AZ_PROP_DELEGATED_POLICY_USERS method

Can also be removed using the

AZ_PROP_DELEGATED_POLICY_USERS_NAME DeleteDelegatedPolicyUserName method

[in] varProp

The principal to remove from the list of principals specified by the lPropId parameter.
The variant must be a BSTR variant.
If AZ_PROP_POLICY_ADMINS_NAME, AZ_PROP_POLICY_READERS_NAME, or
AZ_PROP_DELEGATED_POLICY_USERS_NAME is specified for the lPropId parameter, the string is the account
name of the account to remove from the list. The account name must be in user principal name (UPN) format
(for example, "someone@example.com").
[in, optional] varReserved

Reserved for future use.

Return value
If the method succeeds, the method returns S_OK.
Any other HRESULT value indicates that the operation failed.

Remarks
You must call the Submit method to persist any changes made by this method.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzAuthorizationStore::get_ApplicationData method
(azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The ApplicationData property sets or retrieves an opaque field that can be used by the application to store
information.
This property is read/write.

Syntax
HRESULT get_ApplicationData(
BSTR *pbstrApplicationData
);

Parameters
pbstrApplicationData

Return value
None

Remarks
Impor tant Policy administrators can read from and write to this property. Applications should not store data in the
ApplicationData property that should not be available to the policy administrator.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll
Redistributable Windows Server 2003 Administration Tools Pack on
Windows XP
 IAzAuthorizationStore::get_ApplicationGroups
method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The ApplicationGroups property retrieves an IAzApplicationGroups object that is used to enumerate

IAzApplicationGroup objects from the policy data.
This property is read-only.

Syntax
HRESULT get_ApplicationGroups(
IAzApplicationGroups **ppGroupCollection
);

Parameters
ppGroupCollection

Return value
None

Remarks
This property can be used only to enumerate IAzApplicationGroup objects that are direct child objects of the
AzAuthorizationStore object.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzAuthorizationStore::get_Applications method
(azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The Applications property retrieves an IAzApplications object that is used to enumerate IAzApplication objects
from the policy store.
This property is read-only.

Syntax
HRESULT get_Applications(
IAzApplications **ppAppCollection
);

Parameters
ppAppCollection

Return value
None

Remarks
This property can be used only to enumerate IAzApplication objects that are direct child objects of the
AzAuthorizationStore object.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzAuthorizationStore::get_ApplyStoreSacl method
(azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The ApplyStoreSacl property sets or retrieves a value that indicates whether policy audits should be generated
when the authorization store is modified.
This property is read/write.

Syntax
HRESULT get_ApplyStoreSacl(
BOOL *pbApplyStoreSacl
);

Parameters
pbApplyStoreSacl

Return value
None

Remarks
Policy audits are generated when the underlying policy store is modified. Both success and failure audits are
requested.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzAuthorizationStore::get_DelegatedPolicyUsers
method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The DelegatedPolicyUsers property retrieves the security identifiers (SIDs) of principals that act as delegated
policy users in text form.
This property is read-only.

Syntax
HRESULT get_DelegatedPolicyUsers(
VARIANT *pvarDelegatedPolicyUsers
);

Parameters
pvarDelegatedPolicyUsers

Return value
None

Remarks
Delegated policy users are principals that are allowed to read the subset of the policy data that the policy
administrator of an IAzApplication or IAzScope object uses to administer the delegated object.

Note Delegated policy users are not supported for XML stores.

In JScript, the returned SAFEARRAY must be converted to the JScript Array object.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib
DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzAuthorizationStore::get_DelegatedPolicyUsersName
method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The DelegatedPolicyUsersName property retrieves the account names of principals that act as delegated
policy users.
This property is read-only.

Syntax
HRESULT get_DelegatedPolicyUsersName(
VARIANT *pvarDelegatedPolicyUsers
);

Parameters
pvarDelegatedPolicyUsers

Return value
None

Remarks
Delegated policy users are principals that are allowed to read the subset of the policy data that the policy
administrator of an IAzApplication or IAzScope object uses to administer the delegated object.

Note Delegated policy users are not supported for XML stores.

In JScript, the returned SAFEARRAY must be converted to the JScript Array object.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib
DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzAuthorizationStore::get_Description method
(azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The Description property sets or retrieves a comment that describes the operation.
This property is read/write.

Syntax
HRESULT get_Description(
BSTR *pbstrDescription
);

Parameters
pbstrDescription

Return value
None

Remarks
The maximum length of the Description property is 1,024 characters.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzAuthorizationStore::get_DomainTimeout method
(azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The DomainTimeout property sets or retrieves the time in milliseconds after which a domain is determined to
be unreachable.
This property is read/write.

Syntax
HRESULT get_DomainTimeout(
LONG *plProp
);

Parameters
plProp

Return value
None

Remarks
After the specified time-out interval, LDAP query group membership will attempt to contact a domain controller
again.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzAuthorizationStore::get_GenerateAudits method
(azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The GenerateAudits property sets or retrieves a value that indicates whether run-time audits should be
generated.
This property is read/write.

Syntax
HRESULT get_GenerateAudits(
BOOL *pbProp
);

Parameters
pbProp

Return value
None

Remarks
The GenerateAudits property controls application initialization, client context creation, client context deletion,
and access check run-time auditing. The client context can be created by security identifier (SID), name, or token.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzAuthorizationStore::get_MaxScriptEngines
method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The MaxScriptEngines property sets or retrieves the maximum number of Business Rule (BizRule) script
engines that will be cached.
This property is read/write.

Syntax
HRESULT get_MaxScriptEngines(
LONG *plProp
);

Parameters
plProp

Return value
None

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzAuthorizationStore::get_PolicyAdministrators
method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The PolicyAdministrators property retrieves the security identifiers (SIDs) of principals that act as policy
administrators in text form.
This property is read-only.

Syntax
HRESULT get_PolicyAdministrators(
VARIANT *pvarAdmins
);

Parameters
pvarAdmins

Return value
None

Remarks
Policy administrators for an object can perform the following tasks:
Read the object
Write attributes to the object
Read attributes of child objects of the object
Write attributes to child objects of the object
Delete the object
Delete child objects of the object
Create child objects of the object
In JScript, the returned SAFEARRAY must be converted to the JScript Array object.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h
Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzAuthorizationStore::get_PolicyAdministratorsName
method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The PolicyAdministratorsName property retrieves the account names of principals that act as policy
administrators.
This property is read-only.

Syntax
HRESULT get_PolicyAdministratorsName(
VARIANT *pvarAdmins
);

Parameters
pvarAdmins

Return value
None

Remarks
Policy administrators for an object can perform the following tasks:
Read the object
Write attributes to the object
Read attributes of child objects of the object
Write attributes to child objects of the object
Delete the object
Delete child objects of the object
Create child objects of the object
In JScript, the returned SAFEARRAY must be converted to the JScript Array object.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h
Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzAuthorizationStore::get_PolicyReaders method
(azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The PolicyReaders property retrieves the security identifiers (SIDs) of principals that act as policy readers in
text form.
This property is read-only.

Syntax
HRESULT get_PolicyReaders(
VARIANT *pvarReaders
);

Parameters
pvarReaders

Return value
None

Remarks
Policy readers for an object can read attributes for the object and for child objects of the object. Readers can also
use the policy; for example, readers can call the AccessCheck method. Readers cannot modify the object or its
child objects.
In JScript, the returned SAFEARRAY must be converted to the JScript Array object.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll
Redistributable Windows Server 2003 Administration Tools Pack on
Windows XP
 IAzAuthorizationStore::get_PolicyReadersName
method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The PolicyReadersName property retrieves the account names of principals that act as policy readers.
This property is read-only.

Syntax
HRESULT get_PolicyReadersName(
VARIANT *pvarReaders
);

Parameters
pvarReaders

Return value
None

Remarks
Policy readers for an object can read attributes for the object and for child objects of the object. Readers can also
use the policy; for example, readers can call the AccessCheck method. Readers cannot modify the object or its
child objects.
In JScript, the returned SAFEARRAY must be converted to the JScript Array object.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzAuthorizationStore::get_ScriptEngineTimeout
method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The ScriptEngineTimeout property sets or retrieves the time in milliseconds that the
IAzClientContext::AccessCheck method will wait for a Business Rule (BizRule) to complete execution before
canceling it.
This property is read/write.

Syntax
HRESULT get_ScriptEngineTimeout(
LONG *plProp
);

Parameters
plProp

Return value
None

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzAuthorizationStore::get_TargetMachine method
(azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The TargetMachine property retrieves the name of the computer on which account resolution should occur.
This property is read-only.

Syntax
HRESULT get_TargetMachine(
BSTR *pbstrTargetMachine
);

Parameters
pbstrTargetMachine

Return value
None

Remarks
Determination of the target computer takes into consideration active directories in local and remote domains,
Distributed File System (DFS) shares, mount point, local drive, remote mapped shares, and so on.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzAuthorizationStore::get_Writable method
(azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The Writable property retrieves a value that indicates whether the object can be modified by the user context
that called the Initialize method.
This property is read-only.

Syntax
HRESULT get_Writable(
BOOL *pfProp
);

Parameters
pfProp

Return value
None

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzAuthorizationStore::GetProperty method
(azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The GetProper ty method returns the AzAuthorizationStore object property with the specified property ID.

Syntax
HRESULT GetProperty(
[in] LONG lPropId,
[in, optional] VARIANT varReserved,
[out] VARIANT *pvarProp
);

Parameters
[in] lPropId

Property ID of the AzAuthorizationStore object property to return. The following table shows the possible
values.

VA L UE M EA N IN G

Also accessed through the Description property

AZ_PROP_DESCRIPTION

Also accessed through the ApplicationData property

AZ_PROP_APPLICATION_DATA

Also accessed through the DomainTimeout property

AZ_PROP_AZSTORE_DOMAIN_TIMEOUT

Also accessed through the ScriptEngineTimeout property

AZ_PROP_AZSTORE_SCRIPT_ENGINE_TIMEOUT

Also accessed through the MaxScriptEngines property

AZ_PROP_AZSTORE_MAX_SCRIPT_ENGINES

Also accessed through the TargetMachine property

AZ_PROP_AZSTORE_TARGET_MACHINE

Determines whether the current user has permission to

AZ_PROP_CHILD_CREATE create child objects. This value is TRUE if the current user
has permission; otherwise, FALSE .

Also accessed through the GenerateAudits property

AZ_PROP_GENERATE_AUDITS
 Also accessed through the ApplyStoreSacl property
AZ_PROP_APPLY_STORE_SACL

Also accessed through the Writable property

AZ_PROP_WRITABLE

[in, optional] varReserved

Reserved for future use.

[out] pvarProp

A pointer to the returned AzAuthorizationStore object property.

Return value
If the method succeeds, the method returns S_OK.
Any other HRESULT value indicates that the operation failed.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzAuthorizationStore::Initialize method (azroles.h)
7/2/2022 • 3 minutes to read • Edit Online

The Initialize method initializes the authorization manager.

Syntax
HRESULT Initialize(
[in] LONG lFlags,
[in] BSTR bstrPolicyURL,
[in, optional] VARIANT varReserved
);

Parameters
[in] lFlags

Flags that control the behavior of the initialization. This parameter can be one of the following values.

VA L UE M EA N IN G

The authorization store is opened for use by the Update

0 (0x0) method and the AccessCheck method.

The calling application is required to have

AZ_AZSTORE_FL AG_AUDIT_IS_CRITICAL SE_AUDIT_PRIVILEGE; if the application does not have the
8 (0x8) audit privilege, the Initialize method fails.

The provider is notified that many objects will be modified or

AZ_AZSTORE_FL AG_BATCH_UPDATE created. The provider then optimizes submission of the
4 (0x4) changes for better performance. Use this flag only when
multiple child objects of an AzAuthorizationStore object are
updated simultaneously, such as during an install or a
controlled batch update.

The system attempts to create the policy store specified by

AZ_AZSTORE_FL AG_CREATE the bstrPolicyURL parameter.
1 (0x1)

An existing store is opened for management purposes. Run-

AZ_AZSTORE_FL AG_MANAGE_STORE_ONLY time routines cannot be performed.
2 (0x2)

If the AZ_AZSTORE_FLAG_CREATE flag is specified:

The system will attempt to create the underlying policy store specified by the bstrPolicyURL parameter.
If the specified policy store exists, the Initialize method will fail with ERROR_ALREADY_EXISTS.
You must call the Submit method to persist any changes made by this method.
The UpdateCache method will fail until the Submit method is called. The underlying policy store is actually
 created when Submit is called.
If the AZ_AZSTORE_FLAG_CREATE flag is not specified, the system expects the underlying policy store to exist. If the
store does not exist, the Initialize method will fail with ERROR_FILE_NOT_FOUND.
[in] bstrPolicyURL

Location of the persistent copy of the authorization policy database.

This string must contain both the policy URL prefix and the provider-specific policy location. Authorization
Manager uses the provider prefix to load the appropriate provider. The store is loaded from the provider-specific
policy location. No spaces are allowed in the policy URL prefix.
The policy URL prefix for an Active Directory store is msldap:. The general format for the URL is as follows:
msldap:// ServerName:Port// DistinguishedNameForTheStore
The server name and the port are optional. If a server name is not provided, the default domain controller is
used. If a port is not specified, the default LDAP port (LDAP_PORT, 389) is used. The distinguished name (DN) for
the store begins with the relative distinguished name (RDN) of the AzAuthorizationStore object. For example, if
the RDN of the AzAuthorizationStore object is MyStore and MyStore is in an organizational unit (OU) named
AzMan, a possible URL for the Active Directory store is as follows:
msldap://MyServer/CN=MyStore,OU=AzMan,DC=MyDomain,DC=Fabrikam,DC=Com
The policy URL prefix for an XML store is msxml:. The general format for an XML store URL is the same as for a
file URL, as shown in the following examples:
msxml://c:/abc/test.xml
msxml://\\server\share\abc.xml
msxml://d|/dir1/dir2/abc.xml
msxml://c:/Documents%20and%20Settings/test%2exml
Note that in the fourth example, the URL uses encoding for the space (%20) and the period (%2e) characters. Also,
the traditional relative path notation is not supported in URLs. If you specify msxml://abc.xml, the URL points to the
file at the root of your drive.

Note If an XML or SQL store is used over a network, the traffic is not automatically encrypted. IPsec can be used to encrypt
the authorization information in transit. For an SQL store, it is also possible to set up the open database connectivity (ODBC)
connection to use encryption. For information about how to set up the ODBC connection, see How to enable encryption after
SQL Server has been installed (Network Utility).

[in, optional] varReserved

Reserved for future use. This parameter can be one of the following values:
varReserved.vt == VT_ERROR and varReserved.scode == DISP_E_PARAMNOTFOUND
varReserved.vt == VT_EMPTY
varReserved.vt == VT_NULL
varReserved.vt == VT_I4 and varReserved.lVal == 0
varReserved.vt == VT_I2 and varReserved.iVal == 0

Return value
If the method succeeds, the method returns S_OK.
If the bstrPolicyURL parameter is not valid, the method returns
HRESULT_FROM_WIN32(ERROR_INVALID_NAME).
If the method fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.

Remarks
Active Directory supports Application Partitions, which are also known as Non-Domain Naming Contexts. These
partitions are used as a location for programs to store application data. An Authorization Manager policy store
cannot be created or kept in the Application Partition; instead, use the Program Data container as the container
for Active Directory Authorization Manager policy stores.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzAuthorizationStore::OpenApplication method
(azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The OpenApplication method opens the IAzApplication object with the specified name.

Syntax
HRESULT OpenApplication(
[in] BSTR bstrApplicationName,
[in, optional] VARIANT varReserved,
[out] IAzApplication **ppApplication
);

Parameters
[in] bstrApplicationName

Name of the IAzApplication object to open.

[in, optional] varReserved

Reserved for future use.

[out] ppApplication

A pointer to a pointer to the opened IAzApplication object.

Return value
If the method succeeds, the method returns S_OK.
Any other HRESULT value indicates that the operation failed.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll
Redistributable Windows Server 2003 Administration Tools Pack on
Windows XP
 IAzAuthorizationStore::OpenApplicationGroup
method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The OpenApplicationGroup method opens an IAzApplicationGroup object with the specified name.

Syntax
HRESULT OpenApplicationGroup(
[in] BSTR bstrGroupName,
[in, optional] VARIANT varReserved,
[out] IAzApplicationGroup **ppGroup
);

Parameters
[in] bstrGroupName

Name of the IAzApplicationGroup object to open.

[in, optional] varReserved

Reserved for future use.

[out] ppGroup

A pointer to a pointer to the opened IAzApplicationGroup object.

Return value
If the method succeeds, the method returns S_OK.
Any other HRESULT value indicates that the operation failed.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll
Redistributable Windows Server 2003 Administration Tools Pack on
Windows XP
 IAzAuthorizationStore::put_ApplicationData method
(azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The ApplicationData property sets or retrieves an opaque field that can be used by the application to store
information.
This property is read/write.

Syntax
HRESULT put_ApplicationData(
BSTR bstrApplicationData
);

Parameters
bstrApplicationData

Return value
None

Remarks
Impor tant Policy administrators can read from and write to this property. Applications should not store data in the
ApplicationData property that should not be available to the policy administrator.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll
Redistributable Windows Server 2003 Administration Tools Pack on
Windows XP
 IAzAuthorizationStore::put_ApplyStoreSacl method
(azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The ApplyStoreSacl property sets or retrieves a value that indicates whether policy audits should be generated
when the authorization store is modified.
This property is read/write.

Syntax
HRESULT put_ApplyStoreSacl(
BOOL bApplyStoreSacl
);

Parameters
bApplyStoreSacl

Return value
None

Remarks
Policy audits are generated when the underlying policy store is modified. Both success and failure audits are
requested.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzAuthorizationStore::put_Description method
(azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The Description property sets or retrieves a comment that describes the operation.
This property is read/write.

Syntax
HRESULT put_Description(
BSTR bstrDescription
);

Parameters
bstrDescription

Return value
None

Remarks
The maximum length of the Description property is 1,024 characters.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzAuthorizationStore::put_DomainTimeout method
(azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The DomainTimeout property sets or retrieves the time in milliseconds after which a domain is determined to
be unreachable.
This property is read/write.

Syntax
HRESULT put_DomainTimeout(
LONG lProp
);

Parameters
lProp

Return value
None

Remarks
After the specified time-out interval, LDAP query group membership will attempt to contact a domain controller
again.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzAuthorizationStore::put_GenerateAudits method
(azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The GenerateAudits property sets or retrieves a value that indicates whether run-time audits should be
generated.
This property is read/write.

Syntax
HRESULT put_GenerateAudits(
BOOL bProp
);

Parameters
bProp

Return value
None

Remarks
The GenerateAudits property controls application initialization, client context creation, client context deletion,
and access check run-time auditing. The client context can be created by security identifier (SID), name, or token.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzAuthorizationStore::put_MaxScriptEngines
method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The MaxScriptEngines property sets or retrieves the maximum number of Business Rule (BizRule) script
engines that will be cached.
This property is read/write.

Syntax
HRESULT put_MaxScriptEngines(
LONG lProp
);

Parameters
lProp

Return value
None

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzAuthorizationStore::put_ScriptEngineTimeout
method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The ScriptEngineTimeout property sets or retrieves the time in milliseconds that the
IAzClientContext::AccessCheck method will wait for a Business Rule (BizRule) to complete execution before
canceling it.
This property is read/write.

Syntax
HRESULT put_ScriptEngineTimeout(
LONG lProp
);

Parameters
lProp

Return value
None

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzAuthorizationStore::SetProperty method
(azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The SetProper ty method sets the specified value to the AzAuthorizationStore object property with the specified
property ID.

Syntax
HRESULT SetProperty(
[in] LONG lPropId,
[in] VARIANT varProp,
[in, optional] VARIANT varReserved
);

Parameters
[in] lPropId

Property ID of the AzAuthorizationStore object property to set. The following table shows the possible values.

VA L UE M EA N IN G

Also accessed through the DomainTimeout property

AZ_PROP_AZSTORE_DOMAIN_TIMEOUT

Also accessed through the MaxScriptEngines property

AZ_PROP_AZSTORE_MAX_SCRIPT_ENGINES

Also accessed through the ScriptEngineTimeout property

AZ_PROP_AZSTORE_SCRIPT_ENGINE_TIMEOUT

Also accessed through the ApplicationData property

AZ_PROP_APPLICATION_DATA

Also accessed through the ApplyStoreSacl property

AZ_PROP_APPLY_STORE_SACL

Also accessed through the Description property

AZ_PROP_DESCRIPTION

Also accessed through the GenerateAudits property

AZ_PROP_GENERATE_AUDITS

[in] varProp

Value to set to the AzAuthorizationStore object property specified by the lPropId parameter. The following table
shows the type of data that must be used depending on the value of the lPropId parameter.
 L P RO P ID VA L UE DATA T Y P E

LONG
AZ_PROP_AZSTORE_DOMAIN_TIMEOUT

LONG
AZ_PROP_AZSTORE_MAX_SCRIPT_ENGINES

LONG
AZ_PROP_AZSTORE_SCRIPT_ENGINE_TIMEOUT

BSTR
AZ_PROP_APPLICATION_DATA

BOOL
AZ_PROP_APPLY_STORE_SACL

BSTR
AZ_PROP_DESCRIPTION

BOOL
AZ_PROP_GENERATE_AUDITS

[in, optional] varReserved

Reserved for future use.

Return value
If the method succeeds, the method returns S_OK .
Any other HRESULT value indicates that the operation failed.

Remarks
You must call the Submit method to persist any changes made by this method.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll
Redistributable Windows Server 2003 Administration Tools Pack on
Windows XP
 IAzAuthorizationStore::Submit method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The Submit method persists changes made to the AzAuthorizationStore object.

Syntax
HRESULT Submit(
[in] LONG lFlags,
[in, optional] VARIANT varReserved
);

Parameters
[in] lFlags

Flags that modify the behavior of the Submit method. The default value is zero. If the AZ_SUBMIT_FLAG_ABORT
flag is specified, the changes to the object are discarded and the object is updated to match the underlying
policy store.
[in, optional] varReserved

Reserved for future use.

Return value
None

Remarks
Any additions or modifications to an AzAuthorizationStore object are not persisted until the Submit method is
called. The Delete method automatically submits changes.
The Submit method does not extend to child objects; child objects must be individually persisted to the policy
store. A created AzAuthorizationStore object must be submitted before it can be referenced or become a parent
object. The destructor for an object silently discards unsubmitted changes.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib
DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzAuthorizationStore::UpdateCache method
(azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The UpdateCache method updates the cache of objects and object attributes to match the underlying policy
store.

Syntax
HRESULT UpdateCache(
[in, optional] VARIANT varReserved
);

Parameters
[in, optional] varReserved

Reserved for future use.

Return value
None

Remarks
When the UpdateCache method is called, all changes to the persistent store after the last call to the Initialize
method or to the UpdateCache method are incorporated into the cache. Any changes to the cache that have
not been submitted using the Submit method override the changes to the store.
Most stores should be stable and have few changes. Providers are expected to implement this method to
efficiently determine whether changes have been written to the physical store since the last update.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll
Redistributable Windows Server 2003 Administration Tools Pack on
Windows XP
 IAzAuthorizationStore2 interface (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The IAzAuthorizationStore2 interface inherits from the AzAuthorizationStore object and implements methods
to create and open IAzApplication2 objects.

Inheritance
The IAzAuthorizationStore2 interface inherits from AzAuthorizationStore and IDispatch.
IAzAuthorizationStore2 also has these types of members:

Methods
The IAzAuthorizationStore2 interface has these methods.

IAzAuthorizationStore2::CreateApplication2

Creates an IAzApplication2 object by using the specified name.

IAzAuthorizationStore2::OpenApplication2

Opens the IAzApplication2 object with the specified name.

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2008, Windows Server 2003 with SP1
[desktop apps only]

Target Platform Windows

Header azroles.h
 IAzAuthorizationStore2::CreateApplication2 method
(azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The CreateApplication2 method creates an IAzApplication2 object by using the specified name.

Syntax
HRESULT CreateApplication2(
[in] BSTR bstrApplicationName,
[in, optional] VARIANT varReserved,
[out] IAzApplication2 **ppApplication
);

Parameters
[in] bstrApplicationName

The name for the new IAzApplication2 object.

[in, optional] varReserved

Reserved for future use.

[out] ppApplication

A pointer to a pointer to the created IAzApplication2 object.

Return value
If the method succeeds, the method returns S_OK.
If the method fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.

Remarks
You must call the IAzApplication::Submit method to persist any changes made by the returned object.
The returned IAzApplication2 object is an immediate child object of the IAzAuthorizationStore2 object.

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2008, Windows Server 2003 with SP1
[desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll
 IAzAuthorizationStore2::OpenApplication2 method
(azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The OpenApplication2 method opens the IAzApplication2 object with the specified name.

Syntax
HRESULT OpenApplication2(
[in] BSTR bstrApplicationName,
[in, optional] VARIANT varReserved,
[out] IAzApplication2 **ppApplication
);

Parameters
[in] bstrApplicationName

The name of the IAzApplication2 object to open.

[in, optional] varReserved

Reserved for future use.

[out] ppApplication

A pointer to a pointer to the opened IAzApplication2 object.

Return value
If the method succeeds, the method returns S_OK.
If the method fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2008, Windows Server 2003 with SP1
[desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib
DLL Azroles.dll
 IAzAuthorizationStore3 interface (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The IAzAuthorizationStore3 interface extends the IAzAuthorizationStore2 interface with methods that
manage business rule (BizRule) support and caching.

Inheritance
The IAzAuthorizationStore3 interface inherits from IAzAuthorizationStore2. IAzAuthorizationStore3 also
has these types of members:

Methods
The IAzAuthorizationStore3 interface has these methods.

IAzAuthorizationStore3::BizruleGroupSupported

Returns a Boolean value that specifies whether this IAzAuthorizationStore3 object supports application groups that use
business rule (BizRule) scripts.

IAzAuthorizationStore3::GetSchemaVersion

Gets the version number of this authorization store.

IAzAuthorizationStore3::IsFunctionalLevelUpgradeSupported

Gets a Boolean value that indicates whether the version of this authorization store can be upgraded.

IAzAuthorizationStore3::IsUpdateNeeded

Checks whether the persisted version of this authorization store is newer than the cached version.

IAzAuthorizationStore3::UpgradeStoresFunctionalLevel

Upgrades this authorization store from version 1 to version 2.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header azroles.h
 IAzAuthorizationStore3::BizruleGroupSupported
method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The BizruleGroupSuppor ted method returns a Boolean value that specifies whether this
IAzAuthorizationStore3 object supports application groups that use business rule (BizRule) scripts.

Syntax
HRESULT BizruleGroupSupported(
[out] VARIANT_BOOL *pbSupported
);

Parameters
[out] pbSupported

VARIANT_TRUE if the current IAzAuthorizationStore3 object supports scripts that use business logic to
determine group membership; otherwise, VARIANT_FALSE .

Return value
If the method succeeds, it returns S_OK .
If the method fails, it returns an error code. For a list of common error codes, see Common HRESULT Values.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header azroles.h
 IAzAuthorizationStore3::GetSchemaVersion method
(azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The GetSchemaVersion method gets the version number of this authorization store.

Syntax
HRESULT GetSchemaVersion(
[out] LONG *plMajorVersion,
[out] LONG *plMinorVersion
);

Parameters
[out] plMajorVersion

The major version of the authorization store. Valid values are 1 and 2. A version 1 Authorization Manager
(AzMan) runtime cannot read from or write to an authorization store with a major version of 2.
[out] plMinorVersion

The minor version of the authorization store. Valid values are 1 and 2. A version 1 AzMan runtime can read from
but not write to an authorization store with a minor version of 2.

Return value
If the method succeeds, it returns S_OK .
If the method fails, it returns an error code. For a list of common error codes, see Common HRESULT Values.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header azroles.h
 IAzAuthorizationStore3::IsFunctionalLevelUpgradeSupported
method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The IsFunctionalLevelUpgradeSuppor ted method gets a Boolean value that indicates whether the version of
this authorization store can be upgraded.

Syntax
HRESULT IsFunctionalLevelUpgradeSupported(
[in] LONG lFunctionalLevel,
[out] VARIANT_BOOL *pbSupported
);

Parameters
[in] lFunctionalLevel

The version to check. Set this parameter to AZ_AZSTORE_NT6_FUNCTION_LEVEL .

[out] pbSupported

VARIANT_TRUE if the underlying authorization store supports version 2 functionality; otherwise,

VARIANT_FALSE .

Return value
If the method succeeds, it returns S_OK .
If the method fails, it returns an error code. For a list of common error codes, see Common HRESULT Values.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header azroles.h

See also
IAzAuthorizationStore3
UpgradeStoresFunctionalLevel
 IAzAuthorizationStore3::IsUpdateNeeded method
(azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The IsUpdateNeeded method checks whether the persisted version of this authorization store is newer than
the cached version. If the cached version of the store is newer, the calling application can update the cached
version by calling the UpdateCache method of the AzAuthorizationStore object.

Syntax
HRESULT IsUpdateNeeded(
[out] VARIANT_BOOL *pbIsUpdateNeeded
);

Parameters
[out] pbIsUpdateNeeded

VARIANT_TRUE if the persisted version of this authorization store is newer than the cached version; otherwise,
VARIANT_FALSE .

Return value
If the method succeeds, it returns S_OK .
If the method fails, it returns an error code. For a list of common error codes, see Common HRESULT Values.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header azroles.h
 IAzAuthorizationStore3::UpgradeStoresFunctionalLevel
method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The UpgradeStoresFunctionalLevel method upgrades this authorization store from version 1 to version 2.

Syntax
HRESULT UpgradeStoresFunctionalLevel(
[in] LONG lFunctionalLevel
);

Parameters
[in] lFunctionalLevel

Specifies the version to which to upgrade the authorization store. Set the value of this parameter to
AZ_AZSTORE_NT6_FUNCTION_LEVEL

Return value
If the method succeeds, it returns S_OK .
If the method fails, it returns an error code. For a list of common error codes, see Common HRESULT Values.

Remarks
If the authorization store being updated is an Active Directory store, this method checks whether the LDAP
schema of the Active Directory store is updated. If the LDAP schema of the Active Directory store is not updated,
the authorization store is not updated.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header azroles.h
 IAzBizRuleContext interface (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The AzBizRuleContext object contains information about a Business Rule (BizRule) operation.

Inheritance
The IAzBizRuleContext interface inherits from the IUnknown interface. IAzBizRuleContext also has these
types of members:

Methods
The IAzBizRuleContext interface has these methods.

IAzBizRuleContext::get_BusinessRuleString

Sets or retrieves an application-specific string for the Business Rule (BizRule).

IAzBizRuleContext::GetParameter

Gets the specified value from the varParameterValues parameter of the IAzClientContext::AccessCheck method.

IAzBizRuleContext::put_BusinessRuleResult

Sets a value that indicates whether the Business Rule (BizRule) allows the user to perform the requested task.

IAzBizRuleContext::put_BusinessRuleString

Sets or retrieves an application-specific string for the Business Rule (BizRule).

Remarks
The IAzClientContext::AccessCheck method creates an AzBizRuleContext object before it calls a BizRule script.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzBizRuleContext::get_BusinessRuleString method
(azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The BusinessRuleString property sets or retrieves an application-specific string for the Business Rule
(BizRule).
This property is read/write.

Syntax
HRESULT get_BusinessRuleString(
BSTR *pbstrBusinessRuleString
);

Parameters
pbstrBusinessRuleString

Return value
None

Remarks
This property is returned to the application that called the IAzClientContext::AccessCheck method. One possible
use of this property is to explain the reason that the BizRule denied access to the user.
The maximum length of this property is 65,536 characters.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzBizRuleContext::GetParameter method
(azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The GetParameter method gets the specified value from the varParameterValues parameter of the
IAzClientContext::AccessCheck method.

Syntax
HRESULT GetParameter(
[in] BSTR bstrParameterName,
[out] VARIANT *pvarParameterValue
);

Parameters
[in] bstrParameterName

Name of the value to return. The name must match the name in one of the elements in the array passed into the
varParameterNames parameter of the AccessCheck method.

Impor tant Users of VBScript must be aware that the comparison between this parameter and the names in the
varParameterNames parameter is case sensitive.

[out] pvarParameterValue

Parameter value from the varParameterValues parameter of the AccessCheck method that corresponds to the
name specified by the bstrParameterName parameter, if found; otherwise, NULL .

Return value
If the method succeeds, the method returns S_OK.
Any other HRESULT value indicates that the operation failed.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h
Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzBizRuleContext::put_BusinessRuleResult method
(azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The BusinessRuleResult property sets a value that indicates whether the Business Rule (BizRule) allows the
user to perform the requested task.
This property is write-only.

Syntax
HRESULT put_BusinessRuleResult(
BOOL bResult
);

Parameters
bResult

Return value
None

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzBizRuleContext::put_BusinessRuleString method
(azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The BusinessRuleString property sets or retrieves an application-specific string for the Business Rule
(BizRule).
This property is read/write.

Syntax
HRESULT put_BusinessRuleString(
BSTR bstrBusinessRuleString
);

Parameters
bstrBusinessRuleString

Return value
None

Remarks
This property is returned to the application that called the IAzClientContext::AccessCheck method. One possible
use of this property is to explain the reason that the BizRule denied access to the user.
The maximum length of this property is 65,536 characters.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzBizRuleInterfaces interface (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The IAzBizRuleInterfaces interface provides methods and properties used to manage a list of IDispatch
interfaces that can be called by business rule (BizRule) scripts.

Inheritance
The IAzBizRuleInterfaces interface inherits from the IDispatch interface. IAzBizRuleInterfaces also has these
types of members:

Methods
The IAzBizRuleInterfaces interface has these methods.

IAzBizRuleInterfaces::AddInterface

Adds the specified interface to the list of IDispatch interfaces that can be called by business rule (BizRule) scripts.

IAzBizRuleInterfaces::AddInterfaces

Adds the specified interfaces to the list of IDispatch interfaces that can be called by business rule (BizRule) scripts.

IAzBizRuleInterfaces::get_Count

Specifies the number of interfaces that can be called by business rule (BizRule) scripts.

IAzBizRuleInterfaces::GetInterfaceValue

Gets the ID and flags of the interface that corresponds to the specified interface name.

IAzBizRuleInterfaces::Remove

Removes the specified interface from the list of interfaces The number of interfaces in the list of interfaces that can be called by
BizRule scripts.

IAzBizRuleInterfaces::RemoveAll

Removes all interfaces from the list of interfaces that can be called by business rule (BizRule) scripts.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header azroles.h
 IAzBizRuleInterfaces::AddInterface method
(azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The AddInterface method adds the specified interface to the list of IDispatch interfaces that can be called by
business rule (BizRule) scripts. To add the specified interface, AzMan calls the AddNamedItem method of the
IActiveScript interface.

Syntax
HRESULT AddInterface(
[in] BSTR bstrInterfaceName,
[in] LONG lInterfaceFlag,
[in] VARIANT varInterface
);

Parameters
[in] bstrInterfaceName

A string that contains the name used by scripts to call the interface specified by the varInterface parameter.
[in] lInterfaceFlag

Flags sent to the AddNamedItem method of the IActiveScript interface. The AddNamedItem always behaves as
if the SCRIPTITEM_ISVISIBLE flag is set, and the SCRIPTITEM_ISPERSISTENT flag is not set.
[in] varInterface

The ID of the interface to be added.

Return value
If the method succeeds, it returns S_OK .
If the method fails, it returns an error code. For a list of common error codes, see Common HRESULT Values.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header azroles.h
See also
IAzBizRuleInterfaces
 IAzBizRuleInterfaces::AddInterfaces method
(azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The AddInterfaces method adds the specified interfaces to the list of IDispatch interfaces that can be called by
business rule (BizRule) scripts. To add the specified interfaces, AzMan calls the AddNamedItem method of the
IActiveScript interface once for each specified interface.

Syntax
HRESULT AddInterfaces(
[in] VARIANT varInterfaceNames,
[in] VARIANT varInterfaceFlags,
[in] VARIANT varInterfaces
);

Parameters
[in] varInterfaceNames

A SAFEARRAY that specifies the names that scripts use to call the interfaces specified by the varInterfaces array.
[in] varInterfaceFlags

A SAFEARRAY that specifies flags sent to the AddNamedItem method of the IActiveScript interface. The
AddNamedItem always behaves as if the SCRIPTITEM_ISVISIBLE flag is set, and the
SCRIPTITEM_ISPERSISTENT flag is not set.
[in] varInterfaces

A SAFEARRAY that specifies the IDs of the interfaces to be added.

Return value
If the method succeeds, it returns S_OK .
If the method fails, it returns an error code. For a list of common error codes, see Common HRESULT Values.

Remarks
The names of the interfaces specified by the varInterfaceNames array are in the same order as the
corresponding interface IDs specified by the varInterfaces array.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]
Target Platform Windows

Header azroles.h
 IAzBizRuleInterfaces::get_Count method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The Count property specifies the number of interfaces that can be called by business rule (BizRule) scripts.
This property is read-only.

Syntax
HRESULT get_Count(
unsigned long *plCount
);

Parameters
plCount

Return value
None

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header azroles.h

See also
AddInterface
IAzBizRuleInterfaces
 IAzBizRuleInterfaces::GetInterfaceValue method
(azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The GetInterfaceValue method gets the ID and flags of the interface that corresponds to the specified interface
name.

Syntax
HRESULT GetInterfaceValue(
[in] BSTR bstrInterfaceName,
[out] LONG *lInterfaceFlag,
[out] VARIANT *varInterface
);

Parameters
[in] bstrInterfaceName

A string that contains the interface name.

[out] lInterfaceFlag

A pointer to the flags associated with the interface name.

[out] varInterface

A pointer to the ID associated with the interface name.

Return value
If the method succeeds, it returns S_OK .
If the method fails, it returns an error code. For a list of common error codes, see Common HRESULT Values.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header azroles.h

See also
AddInterface
IAzBizRuleInterfaces
 IAzBizRuleInterfaces::Remove method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The Remove method removes the specified interface from the list of interfaces The number of interfaces in the
list of interfaces that can be called by BizRule scripts.

Syntax
HRESULT Remove(
[in] BSTR bstrInterfaceName
);

Parameters
[in] bstrInterfaceName

The name of the interface to remove.

Return value
If the method succeeds, it returns S_OK .
If the method fails, it returns an error code. For a list of common error codes, see Common HRESULT Values.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header azroles.h

See also
AddInterface
IAzBizRuleInterfaces
 IAzBizRuleInterfaces::RemoveAll method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The RemoveAll method removes all interfaces from the list of interfaces that can be called by business rule
(BizRule) scripts.

Syntax
HRESULT RemoveAll();

Return value
None

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header azroles.h

See also
AddInterface
IAzBizRuleInterfaces
 IAzBizRuleParameters interface (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The IAzBizRuleParameters interface provides methods and properties used to manage a list of parameters
that can be passed to business rule (BizRule) scripts.

Inheritance
The IAzBizRuleParameters interface inherits from the IDispatch interface. IAzBizRuleParameters also has
these types of members:

Methods
The IAzBizRuleParameters interface has these methods.

IAzBizRuleParameters::AddParameter

Adds a parameter to the list of parameters available to business rule (BizRule) scripts.

IAzBizRuleParameters::AddParameters

Adds parameters to the list of parameters available to business rule (BizRule) scripts.

IAzBizRuleParameters::get_Count

Gets the number of parameters available to business rule (BizRule) scripts.

IAzBizRuleParameters::GetParameterValue

Gets the value type of the business rule (BizRule) parameter with the specified name.

IAzBizRuleParameters::Remove

Removes the specified parameter from the list of parameters available to business rule (BizRule) scripts.

IAzBizRuleParameters::RemoveAll

Removes all parameters from the list of parameters available to business rule (BizRule) scripts.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

 Header azroles.h

See also
IAzClientContext3::BizRuleParameters
IDispatch
 IAzBizRuleParameters::AddParameter method
(azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The AddParameter method adds a parameter to the list of parameters available to business rule (BizRule)
scripts.

Syntax
HRESULT AddParameter(
[in] BSTR bstrParameterName,
[in] VARIANT varParameterValue
);

Parameters
[in] bstrParameterName

A string that contains the parameter name.

[in] varParameterValue

The data type of the parameter value.

Return value
If the method succeeds, it returns S_OK .
If the method fails, it returns an error code. For a list of common error codes, see Common HRESULT Values.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header azroles.h

See also
IAzBizRuleParameters
IAzClientContext3::BizRuleParameters
 IAzBizRuleParameters::AddParameters method
(azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The AddParameters method adds parameters to the list of parameters available to business rule (BizRule)
scripts.

Syntax
HRESULT AddParameters(
[in] VARIANT varParameterNames,
[in] VARIANT varParameterValues
);

Parameters
[in] varParameterNames

The parameter names. This is a variant that contains either a SAFEARRAY or the JScript Array object. Each
element of the array holds a VT_BSTR that contains a parameter name. This array must be sorted
alphabetically; the sort order is as defined by a case-sensitive VarCmp. The order of the varParameterValues
array must match the order of this array.
[in] varParameterValues

The values of the parameters that are available to BizRule scripts. This is a variant that contains either a
SAFEARRAY or the JScript Array object. Each element of the array holds a value that corresponds to an element
in the varParameterNames array. The default value is VT_NULL . The entries in the array can hold any type
except VT_UNKNOWN and VT_DISPATCH .

Return value
If the method succeeds, it returns S_OK .
If the method fails, it returns an error code. For a list of common error codes, see Common HRESULT Values.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header azroles.h
See also
IAzBizRuleParameters
IAzClientContext3::BizRuleParameters
 IAzBizRuleParameters::get_Count method
(azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The Count property gets the number of parameters available to business rule (BizRule) scripts.
This property is read-only.

Syntax
HRESULT get_Count(
unsigned long *plCount
);

Parameters
plCount

Return value
None

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header azroles.h

See also
IAzBizRuleParameters
IAzClientContext3::BizRuleParameters
 IAzBizRuleParameters::GetParameterValue method
(azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The GetParameterValue method gets the value type of the business rule (BizRule) parameter with the
specified name.

Syntax
HRESULT GetParameterValue(
[in] BSTR bstrParameterName,
[out] VARIANT *pvarParameterValue
);

Parameters
[in] bstrParameterName

A string that contains the parameter name.

[out] pvarParameterValue

A pointer to the data type of the parameter value.

Return value
If the method succeeds, it returns S_OK .
If the method fails, it returns an error code. For a list of common error codes, see Common HRESULT Values.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header azroles.h

See also
IAzBizRuleParameters
IAzClientContext3::BizRuleParameters
 IAzBizRuleParameters::Remove method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The Remove method removes the specified parameter from the list of parameters available to business rule
(BizRule) scripts.

Syntax
HRESULT Remove(
[in] BSTR varParameterName
);

Parameters
[in] varParameterName

The name of the parameter to remove.

Return value
If the method succeeds, it returns S_OK .
If the method fails, it returns an error code. For a list of common error codes, see Common HRESULT Values.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header azroles.h

See also
IAzBizRuleParameters
IAzClientContext3::BizRuleParameters
 IAzBizRuleParameters::RemoveAll method
(azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The IAzBizRuleParameters::RemoveAll method removes all parameters from the list of parameters available
to business rule (BizRule) scripts.

Syntax
HRESULT RemoveAll();

Return value
None

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header azroles.h

See also
IAzBizRuleParameters
IAzClientContext3::BizRuleParameters
 IAzClientContext interface (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The IAzClientContext interface maintains the state that describes a particular client.

Inheritance
The IAzClientContext interface inherits from the IDispatch interface. IAzClientContext also has these types of
members:

Methods
The IAzClientContext interface has these methods.

IAzClientContext::AccessCheck

Determines whether the current client context is allowed to perform the specified operations.

IAzClientContext::get_RoleForAccessCheck

Sets or retrieves the role that is used to perform the access check.

IAzClientContext::get_UserCanonical

Retrieves the name of the current client in canonical format.

IAzClientContext::get_UserDisplay

Retrieves the name of the current client in user display name format.

IAzClientContext::get_UserDn

Retrieves the name of the current client in distinguished name (DN) format.

IAzClientContext::get_UserDnsSamCompat

Retrieves the name of the current client in a DNS format compatible with Windows�Security�Account�Manager (SAM).

IAzClientContext::get_UserGuid

Retrieves the name of the current client in GUID format.

IAzClientContext::get_UserSamCompat

Retrieves the name of the current client in a format compatible with Windows�Security�Account�Manager (SAM).

IAzClientContext::get_UserUpn

Retrieves the name of the current client in user principal name (UPN) format.
 IAzClientContext::GetBusinessRuleString

Returns the application-specific string for the business rule (BizRule).

IAzClientContext::GetProperty

Returns the IAzClientContext object property with the specified property ID.

IAzClientContext::GetRoles

Returns the roles for the client context.

IAzClientContext::put_RoleForAccessCheck

Sets or retrieves the role that is used to perform the access check.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzClientContext::AccessCheck method (azroles.h)
7/2/2022 • 4 minutes to read • Edit Online

The AccessCheck method determines whether the current client context is allowed to perform the specified
operations.

Syntax
HRESULT AccessCheck(
[in] BSTR bstrObjectName,
[in] VARIANT varScopeNames,
[in] VARIANT varOperations,
[in, optional] VARIANT varParameterNames,
[in, optional] VARIANT varParameterValues,
[in, optional] VARIANT varInterfaceNames,
[in, optional] VARIANT varInterfaceFlags,
[in, optional] VARIANT varInterfaces,
[out] VARIANT *pvarResults
);

Parameters
[in] bstrObjectName

The name of the accessed object. This string is used in audits.

[in] varScopeNames

A variant that contains either a SAFEARRAY or the JScript Array object. Each element of the array holds a
VT_BSTR that contains the name of a scope that the object specified by the bstrObjectName parameter
matches. The array can contain only one element. To use the default application level scope, set the first entry in
the array to an empty string ("") or VT_EMPTY , or pass VT_EMPTY in to this parameter.
[in] varOperations

The operations for which access by the client context is checked. This is a variant that contains either a
SAFEARRAY or the JScript Array object. Each element of the array holds a VT_I2 or VT_I4 that represents the
OperationID property of an IAzOperation object in the IAzApplication policy.
[in, optional] varParameterNames

The names of the parameters available to business rules (BizRules) through the AzBizRuleContext::GetParameter
method. This is a variant that contains either a SAFEARRAY or the JScript Array object. Each element of the array
holds a VT_BSTR that contains a parameter name. This array must be sorted alphabetically by the caller; the
sort order is as defined by a case-sensitive VarCmp. The order of the varParameterValues array must match the
order of this array. The default value is VT_NULL .
[in, optional] varParameterValues

The values of the parameters that are available to business rules (BizRules) through the
AzBizRuleContext::GetParameter method. This is a variant that contains either a SAFEARRAY or the JScript Array
object. Each element of the array holds a value that corresponds to an element in the varParameterNames array.
The default value is VT_NULL . The entries in the array can hold any type except VT_UNKNOWN and
VT_DISPATCH .
[in, optional] varInterfaceNames

The names by which the interfaces in the varInterfaces array will be known in a BizRule script. This is a variant
that contains either a SAFEARRAY or the JScript Array object. Each element of the array holds a string variant
that contains an interface name. This method calls the IActiveScript::AddNamedItem method for each entry in
the array. The default value is VT_NULL .
[in, optional] varInterfaceFlags

Flags that will be passed in the call to IActiveScript::AddNamedItem. This is a variant that contains either a
SAFEARRAY or the JScript Array object. Each element of the array holds a VT_I4 . The SCRIPTITEM_ISVISIBLE flag
is implied; the SCRIPTITEM_ISPERSISTENT flag is ignored. Each entry in the array must match the corresponding
element in the varInterfaceNames array. The default value is VT_NULL .
[in, optional] varInterfaces

The IDispatch interfaces that will be made available to the BizRule script. This is a variant that contains either a
SAFEARRAY or the JScript Array object. Each element of the array holds an IDispatch interface. Each entry in the
array must match the corresponding element in the varInterfaceNames array. The default value is VT_NULL .
[out] pvarResults

A pointer to a VARIANT used to return a SAFEARRAY that contains the results of the access check. Each element
of the SAFEARRAY is a VARIANT of type VT_I4 . Each entry in the array matches the corresponding element in
the varOperations array. If access to an operation is granted to the client context, a value of NO_ERROR is
returned in the corresponding element in the pvarResults array. Any other value indicates that access to that
operation is not granted. A typical value that indicates failure is ERROR_ACCESS_DENIED.
In JScript, the returned SAFEARRAY must be converted to the JScript Array object.

Return value
If the method succeeds, the method returns NO_ERROR.
If the method fails, it returns an HRESULT value that indicates the status of the method, not the result of the
access check. Possible values include, but are not limited to, those in the following table. For a list of common
error codes, see Common HRESULT Values.

RET URN C O DE/ VA L UE DESC RIP T IO N

This error code can be returned if an Active Directory

ERROR_FILE_CORRUPT authorization store is used and the administration of the
scope has been delegated. The task and role definitions
within a delegated scope cannot have BizRules. If a task or
role definition within a delegated scope contains a BizRule
(this is possible if the store is corrupted), the AccessCheck
method will fail.

The BizRule used to evaluate access contains a syntax error.

OLESCRIPT_E_SYNTAX

Remarks
If the RoleForAccessCheck property is defined in the client context, the AccessCheck method will be performed
only on that role.
When this method is called, the application group membership is added to the client context so that it does not
need to be recomputed for subsequent access checks on the same client context.
This method cannot be called by a BizRule.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzClientContext::get_RoleForAccessCheck method
(azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The RoleForAccessCheck property sets or retrieves the role that is used to perform the access check.
This property is read/write.

Syntax
HRESULT get_RoleForAccessCheck(
BSTR *pbstrProp
);

Parameters
pbstrProp

Return value
None

Remarks
If this property is set, the role specified by this property will be the only role used in the access check; otherwise,
all roles contained in the context will be used.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzClientContext::get_UserCanonical method
(azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The UserCanonical property retrieves the name of the current client in canonical format.
This property is read-only.

Syntax
HRESULT get_UserCanonical(
BSTR *pbstrProp
);

Parameters
pbstrProp

Return value
None

Remarks
The canonical client name is retrieved by impersonating the client token and calling the GetUserNameEx
function with NameCanonical specified for the NameFormat parameter.
An example of a client name in canonical format is "example.fourthcoffee.com/software/Ben Smith".

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzClientContext::get_UserDisplay method
(azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The UserDisplay property retrieves the name of the current client in user display name format.
This property is read-only.

Syntax
HRESULT get_UserDisplay(
BSTR *pbstrProp
);

Parameters
pbstrProp

Return value
None

Remarks
The user display client name is retrieved by impersonating the client token and calling the GetUserNameEx
function with NameCanonical specified for the NameDisplay parameter.
An example of a client name in user display name format is "Ben Smith".

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzClientContext::get_UserDn method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The UserDn property retrieves the name of the current client in distinguished name (DN) format.
This property is read-only.

Syntax
HRESULT get_UserDn(
BSTR *pbstrProp
);

Parameters
pbstrProp

Return value
None

Remarks
The DN client name is retrieved by impersonating the client token and calling the GetUserNameEx function with
NameFullyQualifiedDN specified for the NameFormat parameter.
An example of a client name in DN format is "CN=Ben Smith, OU=Software, OU=Example, O=FourthCoffee,
C=US".

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzClientContext::get_UserDnsSamCompat method
(azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The UserDnsSamCompat property retrieves the name of the current client in a DNS format compatible with
Windows Security Account Manager (SAM).
This property is read-only.

Syntax
HRESULT get_UserDnsSamCompat(
BSTR *pbstrProp
);

Parameters
pbstrProp

Return value
None

Remarks
The SAM-compatible DNS client name is retrieved by impersonating the client token and calling the
GetUserNameEx function with NameDnsDomain specified for the NameFormat parameter.
An example of a client name in SAM-compatible DNS format is "example.fourthcoffee.com\Username".

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzClientContext::get_UserGuid method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The UserGuid property retrieves the name of the current client in GUID format.
This property is read-only.

Syntax
HRESULT get_UserGuid(
BSTR *pbstrProp
);

Parameters
pbstrProp

Return value
None

Remarks
The GUID client name is retrieved by impersonating the client token and calling the GetUserNameEx function
with NameUniqueId specified for the NameFormat parameter.
An example of a client name in GUID format is "{4fa050f0-f561-11cf-bdd9-00aa003a77b6}Ben Smith".

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzClientContext::get_UserSamCompat method
(azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The UserSamCompat property retrieves the name of the current client in a format compatible with
Windows Security Account Manager (SAM).
This property is read-only.

Syntax
HRESULT get_UserSamCompat(
BSTR *pbstrProp
);

Parameters
pbstrProp

Return value
None

Remarks
The SAM-compatible client name is retrieved by impersonating the client token and calling the GetUserNameEx
function with NameSamCompatible specified for the NameFormat parameter.
An example of a client name in SAM-compatible format is "ExampleDomain\UserName".

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzClientContext::get_UserUpn method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The UserUpn property retrieves the name of the current client in user principal name (UPN) format.
This property is read-only.

Syntax
HRESULT get_UserUpn(
BSTR *pbstrProp
);

Parameters
pbstrProp

Return value
None

Remarks
The UPN client name is retrieved by impersonating the client token and calling the GetUserNameEx function
with NameUserPrincipal specified for the NameFormat parameter.
An example of a client name in UPN format is "someone@example.com".

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzClientContext::GetBusinessRuleString method
(azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The GetBusinessRuleString method returns the application-specific string for the business rule (BizRule).

Syntax
HRESULT GetBusinessRuleString(
[out] BSTR *pbstrBusinessRuleString
);

Parameters
[out] pbstrBusinessRuleString

String that contains information about the BizRule. The format and contents of the string are defined by the
application.

Return value
The return value is an HRESULT . A value of S_OK indicates success. Any other value indicates that the operation
failed.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP

See also
BusinessRuleString
IAzClientContext
 IAzClientContext::GetProperty method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The GetProper ty method returns the IAzClientContext object property with the specified property ID.

Syntax
HRESULT GetProperty(
[in] LONG lPropId,
[in, optional] VARIANT varReserved,
[out] VARIANT *pvarProp
);

Parameters
[in] lPropId

Property ID of the IAzClientContext object property to return. The following table shows the possible values.

VA L UE M EA N IN G

Determines whether the current user has permission to

AZ_PROP_CHILD_CREATE create child objects. This value will always be FALSE because
this object cannot have child objects.

Also accessed through the RoleForAccessCheck property

AZ_PROP_CLIENT_CONTEXT_ROLE_FOR_ACCESS_CHE
CK

Also accessed through the UserCanonical property

AZ_PROP_CLIENT_CONTEXT_USER_CANONICAL

Also accessed through the UserDisplay property

AZ_PROP_CLIENT_CONTEXT_USER_DISPL AY

Also accessed through the UserDn property

AZ_PROP_CLIENT_CONTEXT_USER_DN

Also accessed through the UserDnsSamCompat property

AZ_PROP_CLIENT_CONTEXT_USER_DNS_SAM_COMP
AT

Also accessed through the UserGuid property

AZ_PROP_CLIENT_CONTEXT_USER_GUID

Also accessed through the UserSamCompat property

AZ_PROP_CLIENT_CONTEXT_USER_SAM_COMPAT
 Also accessed through the UserUpn property
AZ_PROP_CLIENT_CONTEXT_USER_UPN

[in, optional] varReserved

Reserved for future use.

[out] pvarProp

A pointer to the returned IAzClientContext object property.

Return value
The return value is an HRESULT . A value of S_OK indicates success. Any other value indicates that the operation
failed.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzClientContext::GetRoles method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The GetRoles method returns the roles for the client context.

Syntax
HRESULT GetRoles(
[in, optional] BSTR bstrScopeName,
[out] VARIANT *pvarRoleNames
);

Parameters
[in, optional] bstrScopeName

Name of the IAzScope object from which the roles returned in the pvarRoleNames parameter are applicable. If
this property is NULL , the roles from the application scope are returned; otherwise, the roles from the specified
scope are returned instead of the roles from the application scope.
[out] pvarRoleNames

A pointer to a VARIANT used to return a SAFEARRAY. Each element of the SAFEARRAY is a VARIANT of type
BSTR that contains the name of a role to which the client belongs at the scope specified by the bstrScopeName
parameter.

Return value
The return value is an HRESULT . A value of S_OK indicates success. Any other value indicates that the operation
failed.

Remarks
In JScript, the returned SAFEARRAY must be converted to the JScript Array object.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib
DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzClientContext::put_RoleForAccessCheck method
(azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The RoleForAccessCheck property sets or retrieves the role that is used to perform the access check.
This property is read/write.

Syntax
HRESULT put_RoleForAccessCheck(
BSTR bstrProp
);

Parameters
bstrProp

Return value
None

Remarks
If this property is set, the role specified by this property will be the only role used in the access check; otherwise,
all roles contained in the context will be used.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzClientContext2 interface (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The IAzClientContext2 interface inherits from the IAzClientContext interface and implements new methods
that manipulate the client context.

Inheritance
The IAzClientContext2 interface inherits from IDispatch and IAzClientContext. IAzClientContext2 also has
these types of members:

Methods
The IAzClientContext2 interface has these methods.

IAzClientContext2::AddApplicationGroups

Adds the specified array of existing IAzApplicationGroup objects to the client context object.

IAzClientContext2::AddRoles

Adds the specified array of existing IAzRole objects to the client context.

IAzClientContext2::AddStringSids

Adds an array of string representations of security identifiers (SIDs) to the client context.

IAzClientContext2::get_LDAPQueryDN

Retrieves or sets the domain name of the directory object to be used during evaluation of LDAP query groups.

IAzClientContext2::GetAssignedScopesPage

Retrieves a list of the scopes in which the client represented by the current IAzClientContext2 object is assigned to at least one
role.

IAzClientContext2::put_LDAPQueryDN

Retrieves or sets the domain name of the directory object to be used during evaluation of LDAP query groups.

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2008, Windows Server 2003 with SP1
[desktop apps only]
Target Platform Windows

Header azroles.h
 IAzClientContext2::AddApplicationGroups method
(azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The AddApplicationGroups method adds the specified array of existing IAzApplicationGroup objects to the
client context object.

Syntax
HRESULT AddApplicationGroups(
[in] VARIANT varApplicationGroups
);

Parameters
[in] varApplicationGroups

The array of IAzApplicationGroup objects to add.

Return value
If the method succeeds, the method returns S_OK.
If the method fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.

Remarks
The IAzApplicationGroup objects in the varApplicationGroups array must already exist in the authorization store.
The added roles are used in subsequent calls to the AccessCheck and GetRoles methods.

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2008, Windows Server 2003 with SP1
[desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll
See also
AccessCheck
GetRoles
IAzClientContext2
 IAzClientContext2::AddRoles method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The AddRoles method adds the specified array of existing IAzRole objects to the client context.

Syntax
HRESULT AddRoles(
[in] VARIANT varRoles,
[in] BSTR bstrScopeName
);

Parameters
[in] varRoles

The array of role names that specify the IAzRole objects to add to the client context.
[in] bstrScopeName

The scope to which the array of roles applies.

Return value
If the method succeeds, the method returns S_OK.
If the method fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.

Remarks
The IAzRole objects associated with the names in the varRoles array must already exist in the specified scope.
The added roles are used in subsequent calls to the AccessCheck and GetRoles methods.

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2008, Windows Server 2003 with SP1
[desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib
 DLL Azroles.dll

See also
AccessCheck
GetRoles
IAzClientContext2
 IAzClientContext2::AddStringSids method
(azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The AddStringSids method adds an array of string representations of security identifiers (SIDs) to the client
context.

Syntax
HRESULT AddStringSids(
[in] VARIANT varStringSids
);

Parameters
[in] varStringSids

The array of string representations of SIDs to add to the client context.

Return value
If the method succeeds, the method returns S_OK.
If the method fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2008, Windows Server 2003 with SP1
[desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll
 IAzClientContext2::get_LDAPQueryDN method
(azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The LDAPQuer yDN property retrieves or sets the domain name of the directory object to be used during
evaluation of LDAP query groups.
This property is read/write.

Syntax
HRESULT get_LDAPQueryDN(
BSTR *pbstrLDAPQueryDN
);

Parameters
pbstrLDAPQueryDN

Return value
None

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2008, Windows Server 2003 with SP1
[desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll
 IAzClientContext2::GetAssignedScopesPage method
(azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The GetAssignedScopesPage method retrieves a list of the scopes in which the client represented by the
current IAzClientContext2 object is assigned to at least one role.

Syntax
HRESULT GetAssignedScopesPage(
[in] LONG lOptions,
[in] LONG PageSize,
[in, out] VARIANT *pvarCursor,
VARIANT *pvarScopeNames
);

Parameters
[in] lOptions

A flag that specifies whether this method checks LDAP query groups for scope assignment. Previously cached
LDAP query groups are checked regardless of the value of this flag.

VA L UE M EA N IN G

LDAP query groups that were not previously cached are not
AZ_CLIENT_CONTEXT_SKIP_LDAP_QUERY checked.
1

[in] PageSize

The number of elements in each page result.

[in, out] pvarCursor

A pointer to a VARIANT that represents the current page of results. For the first call to the
GetAssignedScopesPage method, pass VT_EMPTY as the value for this parameter to retrieve the first page of
results. The number of elements on a page is determined by the value of the PageSize parameter. On output, this
parameter contains the value to be passed in the next call to GetAssignedScopesPage to retrieve the next
page of results. If the value of this parameter on output is EMPTY , there are no more result pages.
pvarScopeNames

On return, contains an array of variables of type VARIANT . Each element of the array is of type VT_BSTR and
contains the name of a scope to which the current client is assigned. The number of elements in the array is
specified by the PageSize parameter.

Return value
If the method succeeds, the method returns S_OK.
If the method fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.

Remarks
If multiple threads access the same authorization store, a call to the GetAssignedScopesPage method on one
of the threads might not return accurate results if the other thread modifies the store.
In JScript, the returned SAFEARRAY values must be converted to the JScript Array object.

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2008, Windows Server 2003 with SP1
[desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzClientContext2::put_LDAPQueryDN method
(azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The LDAPQuer yDN property retrieves or sets the domain name of the directory object to be used during
evaluation of LDAP query groups.
This property is read/write.

Syntax
HRESULT put_LDAPQueryDN(
BSTR bstrLDAPQueryDN
);

Parameters
bstrLDAPQueryDN

Return value
None

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2008, Windows Server 2003 with SP1
[desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll
 IAzClientContext3 interface (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The IAzClientContext3 interface extends the IAzClientContext2 interface.

Inheritance
The IAzClientContext3 interface inherits from IAzClientContext2. IAzClientContext3 also has these types of
members:

Methods
The IAzClientContext3 interface has these methods.

IAzClientContext3::AccessCheck2

Returns a value that specifies whether the principal represented by the current client context is allowed to perform the
specified operation.

IAzClientContext3::get_BizRuleInterfaces

Gets the collection of IDispatch interfaces that can be called by the business rule (BizRule) script associated with this client
context.

IAzClientContext3::get_BizRuleParameters

Gets the collection of parameters that can be passed by the business rule (BizRule) script associated with this client context.

IAzClientContext3::get_Sids

Gets an array of the security identifiers (SIDs) associated with this client context.

IAzClientContext3::GetGroups

Returns an array of the application groups associated with this client context.

IAzClientContext3::GetOperations

Returns a collection of the operations, within the specified scope, that the principal represented by the current client context
has permission to perform.

IAzClientContext3::GetTasks

Returns a collection of the tasks, within the specified scope, that the principal represented by the current client context has
permission to perform.

IAzClientContext3::IsInRoleAssignment

Checks whether the principal represented by the current client context is a member of the specified role in the specified scope.
Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header azroles.h
 IAzClientContext3::AccessCheck2 method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The AccessCheck2 method returns a value that specifies whether the principal represented by the current
client context is allowed to perform the specified operation.

Syntax
HRESULT AccessCheck2(
[in] BSTR bstrObjectName,
[in] BSTR bstrScopeName,
[in] long lOperation,
[out] unsigned long *plResult
);

Parameters
[in] bstrObjectName

The name of the accessed object. This string is used in audits.

[in] bstrScopeName

The name of the scope that contains the operation specified by the lOperation parameter.
[in] lOperation

The OperationID property of the IAzOperation object for which to check access.
[out] plResult

A pointer to a value that indicates whether the principal represented by the current client context is allowed to
perform the operation specified by the lOperation parameter.
A value of NO_ERROR indicates that the principal does have permission. Any other value indicates that the
principal does not have permission.

Return value
If the method succeeds, it returns S_OK .
If the method fails, it returns an error code. For a list of common error codes, see Common HRESULT Values.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header azroles.h
 IAzClientContext3::get_BizRuleInterfaces method
(azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The IAzClientContext3::BizRuleInterfaces method gets the collection of IDispatch interfaces that can be
called by the business rule (BizRule) script associated with this client context.
This property is read-only.

Syntax
HRESULT get_BizRuleInterfaces(
IAzBizRuleInterfaces **ppBizRuleInterfaces
);

Parameters
ppBizRuleInterfaces

Return value
None

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header azroles.h
 IAzClientContext3::get_BizRuleParameters method
(azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The IAzClientContext3::BizRuleParameters method gets the collection of parameters that can be passed by
the business rule (BizRule) script associated with this client context.
This property is read-only.

Syntax
HRESULT get_BizRuleParameters(
IAzBizRuleParameters **ppBizRuleParam
);

Parameters
ppBizRuleParam

Return value
None

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header azroles.h
 IAzClientContext3::get_Sids method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The Sids property gets an array of the security identifiers (SIDs) associated with this client context.
This property is read-only.

Syntax
HRESULT get_Sids(
VARIANT *pStringSidArray
);

Parameters
pStringSidArray

Return value
None

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header azroles.h

See also
IAzClientContext3
 IAzClientContext3::GetGroups method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The GetGroups method returns an array of the application groups associated with this client context.

Syntax
HRESULT GetGroups(
[in] BSTR bstrScopeName,
[in] ULONG ulOptions,
[out] VARIANT *pGroupArray
);

Parameters
[in] bstrScopeName

The name of the scope in which to check for application groups. This parameter is ignored if the value of the
ulOptions parameter is set to AZ_CLIENT_CONTEXT_GET_GROUPS_STORE_LEVEL_ONLY .
[in] ulOptions

A set of flags that modify the behavior of this method. This can be zero or a combination of one or more of the
following values.

VA L UE M EA N IN G

This method checks only for application groups at the store

AZ_CLIENT_CONTEXT_GET_GROUPS_STORE_LEVEL_O level.
NLY
0x2

[out] pGroupArray

A pointer to an array of the names of application groups associated with this client context.
This is a variant that contains either a SAFEARRAY or the JScript Array object. Each element of the array holds a
VT_BSTR that contains the name of an application group.

Return value
If the method succeeds, it returns S_OK .
If the method fails, it returns an error code. For a list of common error codes, see Common HRESULT Values.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

 Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header azroles.h

See also
IAzClientContext3
 IAzClientContext3::GetOperations method
(azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The GetOperations method returns a collection of the operations, within the specified scope, that the principal
represented by the current client context has permission to perform.

Syntax
HRESULT GetOperations(
[in] BSTR bstrScopeName,
[out] IAzOperations **ppOperationCollection
);

Parameters
[in] bstrScopeName

The name of the scope to check.

[out] ppOperationCollection

The address of a pointer to the collection of operations that the principal represented by the current client
context has permission to perform.

Return value
If the method succeeds, it returns S_OK .
If the method fails, it returns an error code. For a list of common error codes, see Common HRESULT Values.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header azroles.h
 IAzClientContext3::GetTasks method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The GetTasks method returns a collection of the tasks, within the specified scope, that the principal represented
by the current client context has permission to perform.

Syntax
HRESULT GetTasks(
[in] BSTR bstrScopeName,
[out] IAzTasks **ppTaskCollection
);

Parameters
[in] bstrScopeName

The name of the scope to check.

[out] ppTaskCollection

The address of a pointer to the collection of tasks that the principal represented by the current client context has
permission to perform.

Return value
If the method succeeds, it returns S_OK .
If the method fails, it returns an error code. For a list of common error codes, see Common HRESULT Values.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header azroles.h
 IAzClientContext3::IsInRoleAssignment method
(azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The IsInRoleAssignment method checks whether the principal represented by the current client context is a
member of the specified role in the specified scope.

Syntax
HRESULT IsInRoleAssignment(
[in] BSTR bstrScopeName,
[in] BSTR bstrRoleName,
[out] VARIANT_BOOL *pbIsInRole
);

Parameters
[in] bstrScopeName

The name of the scope to check.

[in] bstrRoleName

The name of the role to check.

[out] pbIsInRole

VARIANT_TRUE if the principal represented by the current client context is a member of the role specified by
the bstrRoleName parameter in the scope specified by the bstrScopeName parameter; otherwise,
VARIANT_FALSE .

Return value
If the method succeeds, it returns S_OK .
If the method fails, it returns an error code. For a list of common error codes, see Common HRESULT Values.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header azroles.h
 IAzNameResolver interface (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The IAzNameResolver interface translates security identifiers (SIDs) into principal display names.

Inheritance
The IAzNameResolver interface inherits from the IDispatch interface. IAzNameResolver also has these types
of members:

Methods
The IAzNameResolver interface has these methods.

IAzNameResolver::NameFromSid

Gets the display name that corresponds to the specified security identifier (SID).

IAzNameResolver::NamesFromSids

Gets the display names that correspond to the specified security identifiers (SIDs).

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header azroles.h
 IAzNameResolver::NameFromSid method
(azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The NameFromSid method gets the display name that corresponds to the specified security identifier (SID).

Syntax
HRESULT NameFromSid(
[in] BSTR bstrSid,
[out] long *pSidType,
[out] BSTR *pbstrName
);

Parameters
[in] bstrSid

The string representation of the SID to translate.

[out] pSidType

An element of the SID_NAME_USE enumeration that specifies the type of SID being translated.
[out] pbstrName

A pointer to the display name of the principal that corresponds to the SID specified by the bstrSid parameter.

Return value
If the method succeeds, it returns S_OK .
If the method fails, it returns an error code. In particular, if the method cannot find the display name of the
principal, it returns CO_E_NOMATCHINGNAMEFOUND . For a list of other common error codes, see Common
HRESULT Values.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header azroles.h
 IAzNameResolver::NamesFromSids method
(azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The NamesFromSids method gets the display names that correspond to the specified security identifiers
(SIDs).

Syntax
HRESULT NamesFromSids(
[in] VARIANT vSids,
[out] VARIANT *pvSidTypes,
[out] VARIANT *pvNames
);

Parameters
[in] vSids

An array of string representations of the SIDs to translate.

This is a variant that contains either a SAFEARRAY or the JScript Array object. Each element of the array holds a
VT_BSTR that contains a string representation of a SID.
[out] pvSidTypes

A pointer to an array of elements of the SID_NAME_USE enumeration that specify the types of SIDs being
translated.
This is a variant that contains either a SAFEARRAY or the JScript Array object. Each element of the array holds a
VT_I4 value that specifies an element of the SID_NAME_USE enumeration.
[out] pvNames

A pointer to an array of strings that contain the display names of the principals that correspond to the SIDs
specified by the vSids parameter.
This is a variant that contains either a SAFEARRAY or the JScript Array object. Each element of the array holds a
VT_BSTR that contains a display name. If a name could not be found for one or more of the SIDs, the
corresponding array element contains an empty string.

Return value
If the method succeeds, it returns S_OK .
If the method fails, it returns an error code. If the method cannot find the display names of any of the principals,
it returns CO_E_NOMATCHINGNAMEFOUND . For a list of other common error codes, see Common
HRESULT Values.

Requirements
Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header azroles.h
 IAzObjectPicker interface (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The IAzObjectPicker interface displays a dialog box that allows users to select one or more principals from a
list.

Inheritance
The IAzObjectPicker interface inherits from the IDispatch interface. IAzObjectPicker also has these types of
members:

Methods
The IAzObjectPicker interface has these methods.

IAzObjectPicker::get_Name

Gets the name of the IAzObjectPicker object.

IAzObjectPicker::GetPrincipals

Displays a dialog box from which users can choose one or more principals, and then returns the chosen list of principals and
their corresponding security identifiers (SIDs).

Remarks
Implement this interface when you need a custom dialog box that allows users to choose principals.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header azroles.h
 IAzObjectPicker::get_Name method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The Name property gets the name of the IAzObjectPicker object.

This property is read-only.

Syntax
HRESULT get_Name(
BSTR *pbstrName
);

Parameters
pbstrName

Return value
None

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header azroles.h
 IAzObjectPicker::GetPrincipals method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The GetPrincipals method displays a dialog box from which users can choose one or more principals, and then
returns the chosen list of principals and their corresponding security identifiers (SIDs).

Syntax
HRESULT GetPrincipals(
[in] HWND hParentWnd,
[in] BSTR bstrTitle,
[out] VARIANT *pvSidTypes,
[out] VARIANT *pvNames,
[out] VARIANT *pvSids
);

Parameters
[in] hParentWnd

A handle to the parent window of the dialog box.

[in] bstrTitle

The display title of the dialog box.

[out] pvSidTypes

A pointer to an array of elements of the SID_NAME_USE enumeration that specify the types of the SIDs that
correspond to the principals chosen by the user.
This is a variant that contains either a SAFEARRAY or the JScript Array object. Each element of the array holds a
VT_I4 value that specifies an element of the SID_NAME_USE enumeration.
[out] pvNames

A pointer to an array of display names of the principals chosen by the user.

This is a variant that contains either a SAFEARRAY or the JScript Array object. Each element of the array holds a
VT_BSTR that contains a display name.
[out] pvSids

A pointer to an array of string representations of the SIDs that correspond to the principals chosen by the user.
This is a variant that contains either a SAFEARRAY or the JScript Array object. Each element of the array holds a
VT_BSTR that contains a string representation of a SID.

Return value
If the method succeeds, it returns S_OK .
If the method fails, it returns an error code. For a list of common error codes, see Common HRESULT Values.
Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header azroles.h
 IAzOperation interface (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The IAzOperation interface defines a low-level operation supported by an application.

Inheritance
The IAzOperation interface inherits from the IDispatch interface. IAzOperation also has these types of
members:

Methods
The IAzOperation interface has these methods.

IAzOperation::get_ApplicationData

The ApplicationData property of IAzOperation sets or retrieves an opaque field that can be used by the application to store
information.

IAzOperation::get_Description

The Description property of IAzOperation sets or retrieves a comment that describes the operation.

IAzOperation::get_Name

Sets or retrieves the name of the operation.

IAzOperation::get_OperationID

Sets or retrieves an application-specific value that uniquely identifies the operation within the application.

IAzOperation::get_Writable

Retrieves a value that indicates whether the operation can be modified by the user context that initialized it.

IAzOperation::GetProperty

Returns the IAzOperation object property with the specified property ID.

IAzOperation::put_ApplicationData

The ApplicationData property of IAzOperation sets or retrieves an opaque field that can be used by the application to store
information.

IAzOperation::put_Description

The Description property of IAzOperation sets or retrieves a comment that describes the operation.

IAzOperation::put_Name

Sets or retrieves the name of the operation.

 IAzOperation::put_OperationID

Sets or retrieves an application-specific value that uniquely identifies the operation within the application.

IAzOperation::SetProperty

Sets the specified value to the IAzOperation object property with the specified property ID.

IAzOperation::Submit

Persists changes made to the IAzOperation object.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzOperation::get_ApplicationData method
(azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The ApplicationData property sets or retrieves an opaque field that can be used by the application to store
information.
This property is read/write.

Syntax
HRESULT get_ApplicationData(
BSTR *pbstrApplicationData
);

Parameters
pbstrApplicationData

Return value
None

Remarks
Impor tant Policy administrators can read from and write to this property. Applications should not store data in the
ApplicationData property that should not be available to the policy administrator.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll
Redistributable Windows Server 2003 Administration Tools Pack on
Windows XP
 IAzOperation::get_Description method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The Description property sets or retrieves a comment that describes the operation.
This property is read/write.

Syntax
HRESULT get_Description(
BSTR *pbstrDescription
);

Parameters
pbstrDescription

Return value
None

Remarks
The maximum length of the Description property is 1,024 characters.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzOperation::get_Name method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The Name property sets or retrieves the name of the operation.

This property is read/write.

Syntax
HRESULT get_Name(
BSTR *pbstrName
);

Parameters
pbstrName

Return value
None

Remarks
The maximum length of the Name property is 64 characters.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzOperation::get_OperationID method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The OperationID property sets or retrieves an application-specific value that uniquely identifies the operation
within the application.
This property is read/write.

Syntax
HRESULT get_OperationID(
LONG *plProp
);

Parameters
plProp

Return value
None

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzOperation::get_Writable method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The Writable property retrieves a value that indicates whether the operation can be modified by the user
context that initialized it.
This property is read-only.

Syntax
HRESULT get_Writable(
BOOL *pfProp
);

Parameters
pfProp

Return value
None

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzOperation::GetProperty method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The GetProper ty method returns the IAzOperation object property with the specified property ID.

Syntax
HRESULT GetProperty(
[in] LONG lPropId,
[in, optional] VARIANT varReserved,
[out] VARIANT *pvarProp
);

Parameters
[in] lPropId

Property ID of the IAzOperation object property to return. The following table shows the possible values.

VA L UE M EA N IN G

Also accessed through the ApplicationData property

AZ_PROP_APPLICATION_DATA

Determines whether the current user has permission to

AZ_PROP_CHILD_CREATE create child objects. This value will always be FALSE because
this object cannot have child objects.

Also accessed through the Description property

AZ_PROP_DESCRIPTION

Also accessed through the Name property

AZ_PROP_NAME

Also accessed through the OperationID property

AZ_PROP_OPERATION_ID

Also accessed through the Writable property

AZ_PROP_WRITABLE

[in, optional] varReserved

Reserved for future use.

[out] pvarProp

A pointer to the returned IAzOperation object property.

Return value
The return value is an HRESULT . A value of S_OK indicates success. Any other value indicates that the operation
failed.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzOperation::put_ApplicationData method
(azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The ApplicationData property sets or retrieves an opaque field that can be used by the application to store
information.
This property is read/write.

Syntax
HRESULT put_ApplicationData(
BSTR bstrApplicationData
);

Parameters
bstrApplicationData

Return value
None

Remarks
Impor tant Policy administrators can read from and write to this property. Applications should not store data in the
ApplicationData property that should not be available to the policy administrator.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll
Redistributable Windows Server 2003 Administration Tools Pack on
Windows XP
 IAzOperation::put_Description method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The Description property sets or retrieves a comment that describes the operation.
This property is read/write.

Syntax
HRESULT put_Description(
BSTR bstrDescription
);

Parameters
bstrDescription

Return value
None

Remarks
The maximum length of the Description property is 1,024 characters.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzOperation::put_Name method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The Name property sets or retrieves the name of the operation.

This property is read/write.

Syntax
HRESULT put_Name(
BSTR bstrName
);

Parameters
bstrName

Return value
None

Remarks
The maximum length of the Name property is 64 characters.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzOperation::put_OperationID method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The OperationID property sets or retrieves an application-specific value that uniquely identifies the operation
within the application.
This property is read/write.

Syntax
HRESULT put_OperationID(
LONG lProp
);

Parameters
lProp

Return value
None

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzOperation::SetProperty method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The SetProper ty method sets the specified value to the IAzOperation object property with the specified
property ID.

Syntax
HRESULT SetProperty(
[in] LONG lPropId,
[in] VARIANT varProp,
[in, optional] VARIANT varReserved
);

Parameters
[in] lPropId

Property ID of the IAzOperation object property to set. The following table shows the possible values.

VA L UE M EA N IN G

Also accessed through the ApplicationData property

AZ_PROP_APPLICATION_DATA

Also accessed through the Description property

AZ_PROP_DESCRIPTION

Also accessed through the Name property

AZ_PROP_NAME

Also accessed through the OperationID property

AZ_PROP_OPERATION_ID

[in] varProp

The value to set to the IAzOperation object property specified by the lPropId parameter. The following table
shows the type of data that must be used depending on the value of the lPropId parameter.

L P RO P ID VA L UE DATA T Y P E ( C ++/ VISUA L B A SIC )

BSTR/String
AZ_PROP_APPLICATION_DATA

BSTR/String
AZ_PROP_DESCRIPTION

LONG /Long
AZ_PROP_OPERATION_ID
 BSTR/String
AZ_PROP_NAME

[in, optional] varReserved

Reserved for future use.

Return value
The return value is an HRESULT . A value of S_OK indicates success. Any other value indicates that the operation
failed.

Remarks
You must call the Submit method to persist any changes made by this method.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzOperation::Submit method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The Submit method persists changes made to the IAzOperation object.

Syntax
HRESULT Submit(
[in, optional] LONG lFlags,
[in, optional] VARIANT varReserved
);

Parameters
[in, optional] lFlags

Flags that modify the behavior of the Submit method. The default value is zero. If the AZ_SUBMIT_FLAG_ABORT
flag is specified, the changes to the object are discarded and the object is updated to match the underlying
policy store.
[in, optional] varReserved

Reserved for future use.

Return value
None

Remarks
Any additions or modifications to an IAzOperation object are not persisted until the Submit method is called.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzOperation2 interface (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The IAzOperation2 interface extends the IAzOperation with a method that returns the role assignments
associated with the operation.

Inheritance
The IAzOperation2 interface inherits from the IAzOperation interface.

Methods
The IAzOperation2 interface has these methods.

IAzOperation2::RoleAssignments

Returns a collection of the role assignments associated with this operation.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header azroles.h
 IAzOperation2::RoleAssignments method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The RoleAssignments method returns a collection of the role assignments associated with this operation.

Syntax
HRESULT RoleAssignments(
[in] BSTR bstrScopeName,
[in] VARIANT_BOOL bRecursive,
[out] IAzRoleAssignments **ppRoleAssignments
);

Parameters
[in] bstrScopeName

The name of the scope in which to check for role assignments. If the value of this parameter is an empty string,
the method checks for role assignments at the application level.
[in] bRecursive

TRUE if the method checks all scopes within the application; otherwise, FALSE . This parameter is ignored if the
value of the bstrScopeName parameter is not NULL .
[out] ppRoleAssignments

The address of a pointer to an IAzRoleAssignments interface that represents the collection of IAzRoleAssignment
objects associated with this operation.

Return value
If the method succeeds, it returns S_OK .
If the method fails, it returns an error code. For a list of common error codes, see Common HRESULT Values.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header azroles.h
 IAzOperations interface (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The IAzOperations interface represents a collection of

IAzOperation objects.

Inheritance
The IAzOperations interface inherits from the IDispatch interface. IAzOperations also has these types of
members:

Methods
The IAzOperations interface has these methods.

IAzOperations::get__NewEnum

The _NewEnum property of IAzOperations retrieves an IEnumVARIANT interface on an object that can be used to enumerate
the collection. This property is hidden within Visual Basic and Visual Basic Scripting Edition (VBScript).

IAzOperations::get_Count

Retrieves the number of IAzOperation objects in the collection.

IAzOperations::get_Item

Retrieves the IAzOperation object at the specified index into the IAzOperations collection.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzOperations::get__NewEnum method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The _NewEnum property retrieves an IEnumVARIANT interface on an object that can be used to enumerate the
collection. This property is hidden within Visual Basic and Visual Basic Scripting Edition (VBScript).
This property is read-only.

Syntax
HRESULT get__NewEnum(
LPUNKNOWN *ppEnumPtr
);

Parameters
ppEnumPtr

Return value
None

Remarks
This property is provided for use by the For Each keyword in Visual Basic and the foreach keyword in Visual
C#.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzOperations::get_Count method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The Count property retrieves the number of IAzOperation objects in the collection.
This property is read-only.

Syntax
HRESULT get_Count(
LONG *plCount
);

Parameters
plCount

Return value
None

Remarks
The Count property can be used to specify the last IAzOperation object in a collection when retrieving a specific
IAzOperation object using the IAzOperations.Item property.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzOperations::get_Item method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The Item property retrieves the IAzOperation object at the specified index into the IAzOperations collection.
This property is read-only.

Syntax
HRESULT get_Item(
LONG Index,
VARIANT *pvarObtPtr
);

Parameters
Index

pvarObtPtr

Return value
None

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzPrincipalLocator interface (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The IAzPrincipalLocator interface locates and chooses Active Directory Application Mode (ADAM) principals in
Authorization Manager.

Inheritance
The IAzPrincipalLocator interface inherits from the IDispatch interface.

Methods
The IAzPrincipalLocator interface has these methods.

IAzPrincipalLocator::get_NameResolver

Gets a pointer to the IAzNameResolver interface associated with this IAzPrincipalLocator object.

IAzPrincipalLocator::get_ObjectPicker

Gets a pointer to the IAzObjectPicker interface associated with this IAzPrincipalLocator object.

Remarks
An IAzPrincipalLocator object can contain a name resolver and an object picker. A name resolver translates
security identifiers (SIDs) into display names. An object picker displays a dialog box that enables a user to select
from a list of ADAM principals. The dialog box can appear when a user modifies application groups or roles
through the Authorization Manager user interface.
The IAzPrincipalLocator interface must be registered under the following key.
HKEY_LOCAL_MACHINE \Software \Microsoft \AzMan \ObjectPicker
Under this registry key, create a subkey with a value of the COM class ID of the IAzPrincipalLocator interface.
Authorization Manager supports only one registered principal locator.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header azroles.h
 IAzPrincipalLocator::get_NameResolver method
(azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The NameResolver method gets a pointer to the IAzNameResolver interface associated with this
IAzPrincipalLocator object.
This property is read-only.

Syntax
HRESULT get_NameResolver(
IAzNameResolver **ppNameResolver
);

Parameters
ppNameResolver

Return value
None

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header azroles.h
 IAzPrincipalLocator::get_ObjectPicker method
(azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The ObjectPicker method gets a pointer to the IAzObjectPicker interface associated with this
IAzPrincipalLocator object.
This property is read-only.

Syntax
HRESULT get_ObjectPicker(
IAzObjectPicker **ppObjectPicker
);

Parameters
ppObjectPicker

Return value
None

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header azroles.h
 IAzRole interface (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The IAzRole interface defines the set of operations that can be performed by a set of users within a scope.

Inheritance
The IAzRole interface inherits from the IDispatch interface. IAzRole also has these types of members:

Methods
The IAzRole interface has these methods.

IAzRole::AddAppMember

Adds the specified IAzApplicationGroup object to the list of application groups that belong to this role.

IAzRole::AddMember

Adds the specified security identifier (SID) in text form to the list of Windows accounts that belong to the role.

IAzRole::AddMemberName

Adds the specified account name to the list of accounts that belong to the role.

IAzRole::AddOperation

Adds the IAzOperation object with the specified name to the role.

IAzRole::AddPropertyItem

Adds the specified entity to the specified list.

IAzRole::AddTask

Adds the IAzTask object with the specified name to the role.

IAzRole::DeleteAppMember

Removes the specified IAzApplicationGroup object from the list of application groups that belong to the role.

IAzRole::DeleteMember

Removes the specified security identifier (SID) in text form from the list of Windows accounts that belong to the role.

IAzRole::DeleteMemberName

Removes the specified account name from the list of accounts that belong to the role.
IAzRole::DeleteOperation

Removes the IAzOperation object with the specified name from the role.

IAzRole::DeletePropertyItem

Removes the specified entity from the specified list.

IAzRole::DeleteTask

Removes the IAzTask object with the specified name from the role.

IAzRole::get_ApplicationData

The ApplicationData property of IAzRole sets or retrieves an opaque field that can be used by the application to store
information.

IAzRole::get_AppMembers

Retrieves the application groups that belong to the role.

IAzRole::get_Description

Sets or retrieves a comment that describes the role.

IAzRole::get_Members

Retrieves the security identifiers (SIDs), in text form, of Windows accounts that belong to the role.

IAzRole::get_MembersName

Retrieves the account names of accounts that belong to the role.

IAzRole::get_Name

Sets or retrieves the name of the role.

IAzRole::get_Operations

Retrieves the operations associated with the role.

IAzRole::get_Tasks

Retrieves the tasks associated with the role.

IAzRole::get_Writable

Retrieves a value that indicates whether the role can be modified by the user context that initialized it.

IAzRole::GetProperty

Returns the IAzRole object property with the specified property ID.
 IAzRole::put_ApplicationData

The ApplicationData property of IAzRole sets or retrieves an opaque field that can be used by the application to store
information.

IAzRole::put_Description

Sets or retrieves a comment that describes the role.

IAzRole::put_Name

Sets or retrieves the name of the role.

IAzRole::SetProperty

Sets the specified value to the IAzRole object property with the specified property ID.

IAzRole::Submit

Persists changes made to the IAzRole object.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzRole::AddAppMember method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The AddAppMember method adds the specified IAzApplicationGroup object to the list of application groups
that belong to this role.

Syntax
HRESULT AddAppMember(
[in] BSTR bstrProp,
[in, optional] VARIANT varReserved
);

Parameters
[in] bstrProp

String that contains the Name property of the IAzApplicationGroup object to add to the list of the application
groups that belong to this role.
[in, optional] varReserved

Reserved for future use.

Return value
None

Remarks
To view the list of application groups that belong to this role, use the AppMembers property.
You must call the Submit method to persist any changes made by this method.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll
Redistributable Windows Server 2003 Administration Tools Pack on
Windows XP
 IAzRole::AddMember method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The AddMember method adds the specified security identifier (SID) in text form to the list of Windows
accounts that belong to the role.

Syntax
HRESULT AddMember(
[in] BSTR bstrProp,
[in, optional] VARIANT varReserved
);

Parameters
[in] bstrProp

String that contains the text form of the SID to add to the list of Windows accounts that belong to the role.
[in, optional] varReserved

Reserved for future use.

Return value
None

Remarks
To view the list of SIDs of Windows accounts that belong to this role in text form, use the Members property.
You must call the Submit method to persist any changes made by this method.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll
Redistributable Windows Server 2003 Administration Tools Pack on
Windows XP
 IAzRole::AddMemberName method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The AddMemberName method adds the specified account name to the list of accounts that belong to the role.

Syntax
HRESULT AddMemberName(
[in] BSTR bstrProp,
[in, optional] VARIANT varReserved
);

Parameters
[in] bstrProp

String that contains the account name to add to the list of accounts that belong to the role. The account name
can be in either user principal name (UPN) format (for example, "someone@example.com") or in the
"ExampleDomain\UserName" format. If the domain is not in the "ExampleDomain\UserName" format, the
LookupAccountName function is called to retrieve the domain.
[in, optional] varReserved

Reserved for future use.

Return value
None

Remarks
To view the list of account names of accounts that belong to this role, use the MembersName property.
You must call the Submit method to persist any changes made by this method.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll
Redistributable Windows Server 2003 Administration Tools Pack on
Windows XP
 IAzRole::AddOperation method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The AddOperation method adds the IAzOperation object with the specified name to the role.

Syntax
HRESULT AddOperation(
[in] BSTR bstrProp,
[in, optional] VARIANT varReserved
);

Parameters
[in] bstrProp

Name of the IAzOperation object to add to the role.

[in, optional] varReserved

Reserved for future use.

Return value
None

Remarks
You must call the Submit method to persist any changes made by this method.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzRole::AddPropertyItem method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The AddProper tyItem method adds the specified entity to the specified list.

Syntax
HRESULT AddPropertyItem(
[in] LONG lPropId,
[in] VARIANT varProp,
[in, optional] VARIANT varReserved
);

Parameters
[in] lPropId

Property ID of the list to which to add the entity specified by the varProp parameter. The following table shows
the possible values.

VA L UE M EA N IN G

Can also be added using the AddAppMember method

AZ_PROP_ROLE_APP_MEMBERS

Can also be added using the AddMember method

AZ_PROP_ROLE_MEMBERS

Can also be added using the AddMemberName method

AZ_PROP_ROLE_MEMBERS_NAME

Can also be added using the AddOperation method

AZ_PROP_ROLE_OPERATIONS

Can also be added using the AddTask method

AZ_PROP_ROLE_TASKS

[in] varProp

Entity to add to the list specified by the lPropId parameter.

The variant must be a BSTR variant.
If AZ_PROP_ROLE_MEMBERS is specified for the lPropId parameter, the string is the text form of the security
identifier (SID) of the Windows account to add to the list. If AZ_PROP_ROLE_MEMBERS_NAME is specified for
the lPropId parameter, the string is the account name of the account to add to the list. The account name can be
in either user principal name (UPN) format (for example, "someone@example.com") or in the
"ExampleDomain\UserName" format. If AZ_PROP_ROLE_APP_MEMBERS is specified for the lPropId parameter,
the string is the Name property of the IAzApplicationGroup object to add to the list.
[in, optional] varReserved

Reserved for future use.

Return value
The return value is an HRESULT . A value of S_OK indicates success. Any other value indicates that the operation
failed.

Remarks
You must call the Submit method to persist any changes made by this method.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzRole::AddTask method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The AddTask method adds the IAzTask object with the specified name to the role.

Syntax
HRESULT AddTask(
[in] BSTR bstrProp,
[in, optional] VARIANT varReserved
);

Parameters
[in] bstrProp

Name of the IAzTask object to add to the role.

[in, optional] varReserved

Reserved for future use.

Return value
None

Remarks
You must call the Submit method to persist any changes made by this method.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzRole::DeleteAppMember method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The DeleteAppMember method removes the specified IAzApplicationGroup object from the list of application
groups that belong to the role.

Syntax
HRESULT DeleteAppMember(
[in] BSTR bstrProp,
[in, optional] VARIANT varReserved
);

Parameters
[in] bstrProp

String that contains the Name property of the IAzApplicationGroup object to remove from the list of application
groups that belong to the role.
[in, optional] varReserved

Reserved for future use.

Return value
None

Remarks
To view the list of application groups that belong to the role, use the AppMembers property.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzRole::DeleteMember method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The DeleteMember method removes the specified security identifier (SID) in text form from the list of
Windows accounts that belong to the role.

Syntax
HRESULT DeleteMember(
[in] BSTR bstrProp,
[in, optional] VARIANT varReserved
);

Parameters
[in] bstrProp

String that contains the text form of the SID to remove from the list of Windows accounts that belong to the role.
[in, optional] varReserved

Reserved for future use.

Return value
None

Remarks
To view the list of SIDs of Windows accounts that belong to the role in text form, use the Members property.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzRole::DeleteMemberName method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The DeleteMemberName method removes the specified account name from the list of accounts that belong
to the role.

Syntax
HRESULT DeleteMemberName(
[in] BSTR bstrProp,
[in, optional] VARIANT varReserved
);

Parameters
[in] bstrProp

String that contains the account name to remove from the list of accounts that belong to the role. The account
name can be in either user principal name (UPN) format (for example, "someone@example.com") or in the
"ExampleDomain\UserName" format. If the domain is not in the "ExampleDomain\UserName" format, the
LookupAccountName function is called to retrieve the domain.
[in, optional] varReserved

Reserved for future use.

Return value
None

Remarks
To view the list of account names of accounts that belong to the role, use the MembersName property.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll
Redistributable Windows Server 2003 Administration Tools Pack on
Windows XP
 IAzRole::DeleteOperation method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The DeleteOperation method removes the IAzOperation object with the specified name from the role.

Syntax
HRESULT DeleteOperation(
[in] BSTR bstrProp,
[in, optional] VARIANT varReserved
);

Parameters
[in] bstrProp

Name of the IAzOperation object to remove from the role.

[in, optional] varReserved

Reserved for future use.

Return value
None

Remarks
If there are any IAzOperation references to an IAzOperation object that has been deleted from the cache, the
IAzOperation object can no longer be used. In C++, you must release references to deleted IAzOperation
objects by calling the IUnknown::Release method. In Visual Basic, references to deleted objects are automatically
released.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll
Redistributable Windows Server 2003 Administration Tools Pack on
Windows XP
 IAzRole::DeletePropertyItem method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The DeleteProper tyItem method removes the specified entity from the specified list.

Syntax
HRESULT DeletePropertyItem(
[in] LONG lPropId,
[in] VARIANT varProp,
[in, optional] VARIANT varReserved
);

Parameters
[in] lPropId

Property ID of the list from which to remove the entity specified by the varProp parameter. The following table
shows the possible values.

VA L UE M EA N IN G

Can also be removed using the DeleteAppMember method

AZ_PROP_ROLE_APP_MEMBERS

Can also be removed using the DeleteMember method

AZ_PROP_ROLE_MEMBERS

Can also be removed using the DeleteMemberName

AZ_PROP_ROLE_MEMBERS_NAME method

Can also be removed using the DeleteOperation method

AZ_PROP_ROLE_OPERATIONS

Can also be removed using the DeleteTask method

AZ_PROP_ROLE_TASKS

[in] varProp

Entity to remove from the list specified by the lPropId parameter.

The variant must be a BSTR variant.
If AZ_PROP_ROLE_MEMBERS is specified for the lPropId parameter, the string is the security identifier (SID) of
the Windows account to remove from the list. If AZ_PROP_ROLE_MEMBERS_NAME is specified for the lPropId
parameter, the string is the account name of the account to remove from the list. The account name can be in
either user principal name (UPN) format (for example, "someone@example.com") or in the
"ExampleDomain\UserName" format. If AZ_PROP_ROLE_APP_MEMBERS is specified for the lPropId parameter,
the string is the Name property of the IAzApplicationGroup object to remove from the list.
[in, optional] varReserved

Reserved for future use.

Return value
The return value is an HRESULT . A value of S_OK indicates success. Any other value indicates that the operation
failed.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzRole::DeleteTask method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The DeleteTask method removes the IAzTask object with the specified name from the role.

Syntax
HRESULT DeleteTask(
[in] BSTR bstrProp,
[in, optional] VARIANT varReserved
);

Parameters
[in] bstrProp

Name of the IAzTask object to remove from the role.

[in, optional] varReserved

Reserved for future use.

Return value
None

Remarks
If there are any IAzTask references to an IAzTask object that has been deleted from the cache, the IAzTask object
can no longer be used. In C++, you must release references to deleted IAzTask objects by calling the
IUnknown::Release method. In Visual Basic, references to deleted objects are automatically released.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzRole::get_ApplicationData method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The ApplicationData property sets or retrieves an opaque field that can be used by the application to store
information.
This property is read/write.

Syntax
HRESULT get_ApplicationData(
BSTR *pbstrApplicationData
);

Parameters
pbstrApplicationData

Return value
None

Remarks
Impor tant Policy administrators can read from and write to this property. Applications should not store data in the
ApplicationData property that should not be available to the policy administrator.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzRole::get_AppMembers method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The AppMembers property retrieves the application groups that belong to the role.
This property is read-only.

Syntax
HRESULT get_AppMembers(
VARIANT *pvarProp
);

Parameters
pvarProp

Return value
None

Remarks
In JScript, the returned SAFEARRAY must be converted to the JScript Array object.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzRole::get_Description method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The Description property sets or retrieves a comment that describes the role.
This property is read/write.

Syntax
HRESULT get_Description(
BSTR *pbstrDescription
);

Parameters
pbstrDescription

Return value
None

Remarks
The maximum length of the Description property is 1,024 characters.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzRole::get_Members method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The Members property retrieves the security identifiers (SIDs), in text form, of Windows accounts that belong
to the role.
This property is read-only.

Syntax
HRESULT get_Members(
VARIANT *pvarProp
);

Parameters
pvarProp

Return value
None

Remarks
In JScript, the returned SAFEARRAY must be converted to the JScript Array object.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzRole::get_MembersName method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The MembersName property retrieves the account names of accounts that belong to the role.
This property is read-only.

Syntax
HRESULT get_MembersName(
VARIANT *pvarProp
);

Parameters
pvarProp

Return value
None

Remarks
In JScript, the returned SAFEARRAY must be converted to the JScript Array object.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzRole::get_Name method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The Name property sets or retrieves the name of the role.

This property is read/write.

Syntax
HRESULT get_Name(
BSTR *pbstrName
);

Parameters
pbstrName

Return value
None

Remarks
The maximum length of the Name property is 64 characters.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzRole::get_Operations method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The Operations property retrieves the operations associated with the role.
This property is read-only.

Syntax
HRESULT get_Operations(
VARIANT *pvarProp
);

Parameters
pvarProp

Return value
None

Remarks
In JScript, the returned SAFEARRAY must be converted to the JScript Array object.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzRole::get_Tasks method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The Tasks property retrieves the tasks associated with the role.
This property is read-only.

Syntax
HRESULT get_Tasks(
VARIANT *pvarProp
);

Parameters
pvarProp

Return value
None

Remarks
In JScript, the returned SAFEARRAY must be converted to the JScript Array object.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzRole::get_Writable method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The Writable property retrieves a value that indicates whether the role can be modified by the user context that
initialized it.
This property is read-only.

Syntax
HRESULT get_Writable(
BOOL *pfProp
);

Parameters
pfProp

Return value
None

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzRole::GetProperty method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The GetProper ty method returns the IAzRole object property with the specified property ID.

Syntax
HRESULT GetProperty(
[in] LONG lPropId,
[in, optional] VARIANT varReserved,
[out] VARIANT *pvarProp
);

Parameters
[in] lPropId

Property ID of the IAzRole object property to return. The following table shows the possible values.

VA L UE M EA N IN G

Also accessed through the ApplicationData property

AZ_PROP_APPLICATION_DATA

Determines whether the current user has permission to

AZ_PROP_CHILD_CREATE create child objects. This value will always be FALSE because
this object cannot have child objects.

Also accessed through the Description property

AZ_PROP_DESCRIPTION

Also accessed through the Name property

AZ_PROP_NAME

Also accessed through the AppMembers property

AZ_PROP_ROLE_APP_MEMBERS

Also accessed through the Members property

AZ_PROP_ROLE_MEMBERS

Also accessed through the MembersName property

AZ_PROP_ROLE_MEMBERS_NAME

Also accessed through the Operations property

AZ_PROP_ROLE_OPERATIONS

Also accessed through the Tasks property

AZ_PROP_ROLE_TASKS
 Also accessed through the Writable property
AZ_PROP_WRITABLE

[in, optional] varReserved

Reserved for future use.

[out] pvarProp

A pointer to the returned IAzRole object property.

Return value
The return value is an HRESULT . A value of S_OK indicates success. Any other value indicates that the operation
failed.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzRole::put_ApplicationData method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The ApplicationData property sets or retrieves an opaque field that can be used by the application to store
information.
This property is read/write.

Syntax
HRESULT put_ApplicationData(
BSTR bstrApplicationData
);

Parameters
bstrApplicationData

Return value
None

Remarks
Impor tant Policy administrators can read from and write to this property. Applications should not store data in the
ApplicationData property that should not be available to the policy administrator.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzRole::put_Description method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The Description property sets or retrieves a comment that describes the role.
This property is read/write.

Syntax
HRESULT put_Description(
BSTR bstrDescription
);

Parameters
bstrDescription

Return value
None

Remarks
The maximum length of the Description property is 1,024 characters.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzRole::put_Name method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The Name property sets or retrieves the name of the role.

This property is read/write.

Syntax
HRESULT put_Name(
BSTR bstrName
);

Parameters
bstrName

Return value
None

Remarks
The maximum length of the Name property is 64 characters.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzRole::SetProperty method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The SetProper ty method sets the specified value to the IAzRole object property with the specified property ID.

Syntax
HRESULT SetProperty(
[in] LONG lPropId,
[in] VARIANT varProp,
[in, optional] VARIANT varReserved
);

Parameters
[in] lPropId

Property ID of the IAzRole object property to set. The following table shows the possible values.

VA L UE M EA N IN G

Also accessed through the ApplicationData property

AZ_PROP_APPLICATION_DATA

Also accessed through the Description property

AZ_PROP_DESCRIPTION

Also accessed through the Name property

AZ_PROP_NAME

[in] varProp

The value to set to the IAzRole object property specified by the lPropId parameter. The following table shows the
type of data that must be used depending on the value of the lPropId parameter.

L P RO P ID VA L UE DATA T Y P E ( C ++/ VISUA L B A SIC )

BSTR/String
AZ_PROP_APPLICATION_DATA

BSTR/String
AZ_PROP_DESCRIPTION

BSTR/String
AZ_PROP_NAME

[in, optional] varReserved

Reserved for future use.

Return value
The return value is an HRESULT . A value of S_OK indicates success. Any other value indicates that the operation
failed.

Remarks
You must call the Submit method to persist any changes made by this method.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzRole::Submit method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The Submit method persists changes made to the IAzRole object.

Syntax
HRESULT Submit(
[in, optional] LONG lFlags,
[in, optional] VARIANT varReserved
);

Parameters
[in, optional] lFlags

Flags that modify the behavior of the Submit method. The default value is zero. If the AZ_SUBMIT_FLAG_ABORT
flag is specified, the changes to the object are discarded and the object is updated to match the underlying
policy store.
[in, optional] varReserved

Reserved for future use.

Return value
None

Remarks
Any additions or modifications to an IAzRole object are not persisted until the Submit method is called.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzRoleAssignment interface (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The IAzRoleAssignment interface represents a role to which users and groups can be assigned. A
IAzRoleAssignment object can be associated with one or more IAzRoleDefinition, IAzTask, and IAzOperation
objects that specify the operations to which users and groups assigned to the role can access.

Inheritance
The IAzRoleAssignment interface inherits from IAzRole. IAzRoleAssignment also has these types of
members:

Methods
The IAzRoleAssignment interface has these methods.

IAzRoleAssignment::AddRoleDefinition

Adds the specified IAzRoleDefinition object to this IAzRoleAssignment object.

IAzRoleAssignment::DeleteRoleDefinition

Removes the IAzRoleDefinition object with the specified name from this IAzRoleAssignment object.

IAzRoleAssignment::get_RoleDefinitions

Retrieves a collection of the IAzRoleDefinition objects associated with this IAzRoleAssignment object.

IAzRoleAssignment::get_Scope

Retrieves the IAzScope object that represents the scope in which this IAzRoleAssignment object is defined.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header azroles.h
 IAzRoleAssignment::AddRoleDefinition method
(azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The AddRoleDefinition method adds the specified IAzRoleDefinition object to this IAzRoleAssignment object.

Syntax
HRESULT AddRoleDefinition(
[in] BSTR bstrRoleDefinition
);

Parameters
[in] bstrRoleDefinition

The name of the IAzRoleDefinition to add.

Return value
If the method succeeds, the method returns S_OK.
If the method fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.

Remarks
You must call the Submit method to persist any changes made by this method.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header azroles.h

DLL Azroles.dll
 IAzRoleAssignment::DeleteRoleDefinition method
(azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The DeleteRoleDefinition method removes the IAzRoleDefinition object with the specified name from this
IAzRoleAssignment object.

Syntax
HRESULT DeleteRoleDefinition(
[in] BSTR bstrRoleDefinition
);

Parameters
[in] bstrRoleDefinition

The name of the IAzRoleDefinition object to delete.

Return value
If the method succeeds, the method returns S_OK.
If the method fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.

Remarks
If there are any references to an IAzRoleDefinition object that has been deleted from the cache, the
IAzRoleDefinition object can no longer be used. In C++, you must release references to deleted
IAzRoleDefinition objects by calling the IUnknown::Release method. In Visual Basic, references to deleted
objects are automatically released.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header azroles.h

DLL Azroles.dll
 IAzRoleAssignment::get_RoleDefinitions method
(azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The RoleDefinitions property retrieves a collection of the IAzRoleDefinition objects associated with this
IAzRoleAssignment object.
This property is read-only.

Syntax
HRESULT get_RoleDefinitions(
IAzRoleDefinitions **ppRoleDefinitions
);

Parameters
ppRoleDefinitions

Return value
None

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header azroles.h

DLL Azroles.dll
 IAzRoleAssignment::get_Scope method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The Scope property retrieves the IAzScope object that represents the scope in which this IAzRoleAssignment
object is defined.
This property is read-only.

Syntax
HRESULT get_Scope(
IAzScope **ppScope
);

Parameters
ppScope

Return value
None

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header azroles.h

DLL Azroles.dll
 IAzRoleAssignments interface (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The IAzRoleAssignments interface represents a collection of IAzRoleAssignment objects.

Inheritance
The IAzRoleAssignments interface inherits from the IDispatch interface.

Methods
The IAzRoleAssignments interface has these methods.

IAzRoleAssignments::get__NewEnum

Retrieves an IEnumVARIANT interface on an object that can be used to enumerate the IAzRoleAssignments collection. This
property is hidden within Visual Basic and Visual Basic Scripting Edition (VBScript).

IAzRoleAssignments::get_Count

Retrieves the number of IAzRoleAssignments objects in the collection.

IAzRoleAssignments::get_Item

Retrieves the IAzRoleAssignment object at the specified index in the IAzRoleAssignments collection.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header azroles.h
 IAzRoleAssignments::get__NewEnum method
(azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The _NewEnum property retrieves an IEnumVARIANT interface on an object that can be used to enumerate the
IAzRoleAssignments collection. This property is hidden within Visual Basic and Visual Basic Scripting Edition
(VBScript).
This property is read-only.

Syntax
HRESULT get__NewEnum(
LPUNKNOWN *ppEnumPtr
);

Parameters
ppEnumPtr

Return value
None

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header azroles.h

DLL Azroles.dll
 IAzRoleAssignments::get_Count method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The Count property retrieves the number of IAzRoleAssignments objects in the collection.
This property is read-only.

Syntax
HRESULT get_Count(
LONG *plCount
);

Parameters
plCount

Return value
None

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header azroles.h

DLL Azroles.dll
 IAzRoleAssignments::get_Item method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The Item property retrieves the IAzRoleAssignment object at the specified index in the IAzRoleAssignments
collection.
This property is read-only.

Syntax
HRESULT get_Item(
LONG Index,
VARIANT *pvarObtPtr
);

Parameters
Index

pvarObtPtr

Return value
None

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header azroles.h

DLL Azroles.dll
 IAzRoleDefinition interface (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The IAzRoleDefinition interface represents one or more IAzRoleDefinition , IAzTask, and IAzOperation objects
that specify a set of operations. If an IAzRoleAssignment object is associated with an IAzRoleDefinition object,
users and groups assigned to that IAzRoleAssignment object are allowed to access the operations specified by
that IAzRoleDefinition object.

Inheritance
The IAzRoleDefinition interface inherits from IAzTask. IAzRoleDefinition also has these types of members:

Methods
The IAzRoleDefinition interface has these methods.

IAzRoleDefinition::AddRoleDefinition

Adds the specified IAzRoleDefinition object to this IAzRoleDefinition object.

IAzRoleDefinition::DeleteRoleDefinition

Removes the IAzRoleDefinition object with the specified name from this IAzRoleDefinition object.

IAzRoleDefinition::get_RoleDefinitions

Retrieves a collection of the IAzRoleDefinition objects associated with this IAzRoleDefinition object.

IAzRoleDefinition::RoleAssignments

Retrieves a collection of IAzRoleAssignment objects that represent the role assignments associated with this IAzRoleDefinition
object.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header azroles.h
 IAzRoleDefinition::AddRoleDefinition method
(azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The AddRoleDefinition method adds the specified IAzRoleDefinition object to this IAzRoleDefinition object.

Syntax
HRESULT AddRoleDefinition(
[in] BSTR bstrRoleDefinition
);

Parameters
[in] bstrRoleDefinition

The name of the IAzRoleDefinition to add.

Return value
If the method succeeds, the method returns S_OK.
If the method fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.

Remarks
You must call the Submit method to persist any changes made by this method.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header azroles.h

DLL Azroles.dll
 IAzRoleDefinition::DeleteRoleDefinition method
(azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The DeleteRoleDefinition method removes the IAzRoleDefinition object with the specified name from this
IAzRoleDefinition object.

Syntax
HRESULT DeleteRoleDefinition(
[in] BSTR bstrRoleDefinition
);

Parameters
[in] bstrRoleDefinition

The name of the IAzRoleDefinition object to delete.

Return value
If the method succeeds, the method returns S_OK.
If the method fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.

Remarks
If there are any references to an IAzRoleDefinition object that has been deleted from the cache, the
IAzRoleDefinition object can no longer be used. In C++, you must release references to deleted
IAzRoleDefinition objects by calling the IUnknown::Release method. In Visual Basic, references to deleted
objects are automatically released.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header azroles.h

DLL Azroles.dll
 IAzRoleDefinition::get_RoleDefinitions method
(azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The RoleDefinitions property retrieves a collection of the IAzRoleDefinition objects associated with this
IAzRoleDefinition object.
This property is read-only.

Syntax
HRESULT get_RoleDefinitions(
IAzRoleDefinitions **ppRoleDefinitions
);

Parameters
ppRoleDefinitions

Return value
None

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header azroles.h

DLL Azroles.dll
 IAzRoleDefinition::RoleAssignments method
(azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The RoleAssignments property retrieves a collection of IAzRoleAssignment objects that represent the role
assignments associated with this IAzRoleDefinition object.
This property is read-only.

Syntax
HRESULT RoleAssignments(
BSTR bstrScopeName,
VARIANT_BOOL bRecursive,
IAzRoleAssignments **ppRoleAssignments
);

Parameters
bstrScopeName

bRecursive

ppRoleAssignments

Return value
None

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header azroles.h

DLL Azroles.dll
 IAzRoleDefinitions interface (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The IAzRoleDefinitions interface represents a collection of IAzRoleDefinition objects.

Inheritance
The IAzRoleDefinitions interface inherits from the IDispatch interface.

Methods
The IAzRoleDefinitions interface has these methods.

IAzRoleDefinitions::get__NewEnum

Retrieves an IEnumVARIANT interface on an object that can be used to enumerate the IAzRoleDefinitions collection. This
property is hidden within Visual Basic and Visual Basic Scripting Edition (VBScript).

IAzRoleDefinitions::get_Count

Retrieves the number of IAzRoleDefinitions objects in the collection.

IAzRoleDefinitions::get_Item

Retrieves the IAzRoleDefinition object at the specified index in the IAzRoleDefinitions collection.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header azroles.h
 IAzRoleDefinitions::get__NewEnum method
(azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The _NewEnum property retrieves an IEnumVARIANT interface on an object that can be used to enumerate the
IAzRoleDefinitions collection. This property is hidden within Visual Basic and Visual Basic Scripting Edition
(VBScript).
This property is read-only.

Syntax
HRESULT get__NewEnum(
LPUNKNOWN *ppEnumPtr
);

Parameters
ppEnumPtr

Return value
None

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header azroles.h

DLL Azroles.dll
 IAzRoleDefinitions::get_Count method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The Count property retrieves the number of IAzRoleDefinitions objects in the collection.
This property is read-only.

Syntax
HRESULT get_Count(
LONG *plCount
);

Parameters
plCount

Return value
None

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header azroles.h

DLL Azroles.dll
 IAzRoleDefinitions::get_Item method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The Item property retrieves the IAzRoleDefinition object at the specified index in the IAzRoleDefinitions
collection.
This property is read-only.

Syntax
HRESULT get_Item(
LONG Index,
VARIANT *pvarObtPtr
);

Parameters
Index

pvarObtPtr

Return value
None

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header azroles.h

DLL Azroles.dll
 IAzRoles interface (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The IAzRoles interface represents a collection of

IAzRole objects.

Inheritance
The IAzRoles interface inherits from the IDispatch interface. IAzRoles also has these types of members:

Methods
The IAzRoles interface has these methods.

IAzRoles::get__NewEnum

The _NewEnum property of IAzRoles retrieves an IEnumVARIANT interface on an object that can be used to enumerate the
collection. This property is hidden within Visual Basic and Visual Basic Scripting Edition (VBScript).

IAzRoles::get_Count

Retrieves the number of IAzRole objects in the collection.

IAzRoles::get_Item

Retrieves the IAzRole object at the specified index into the IAzRoles collection.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzRoles::get__NewEnum method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The _NewEnum property retrieves an IEnumVARIANT interface on an object that can be used to enumerate the
collection. This property is hidden within Visual Basic and Visual Basic Scripting Edition (VBScript).
This property is read-only.

Syntax
HRESULT get__NewEnum(
LPUNKNOWN *ppEnumPtr
);

Parameters
ppEnumPtr

Return value
None

Remarks
This property is provided for use by the For Each keyword in Visual Basic and the foreach keyword in Visual
C#.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzRoles::get_Count method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The Count property retrieves the number of IAzRole objects in the collection.
This property is read-only.

Syntax
HRESULT get_Count(
LONG *plCount
);

Parameters
plCount

Return value
None

Remarks
The Count property can be used to specify the last IAzRole object in a collection when retrieving a specific
IAzRole object using the IAzRoles.Item property.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzRoles::get_Item method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The Item property retrieves the IAzRole object at the specified index into the IAzRoles collection.
This property is read-only.

Syntax
HRESULT get_Item(
LONG Index,
VARIANT *pvarObtPtr
);

Parameters
Index

pvarObtPtr

Return value
None

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzScope interface (azroles.h)
7/2/2022 • 3 minutes to read • Edit Online

The IAzScope interface defines a logical container of resources to which the application manages access. The
scope name will be used in calls to the AccessCheck method to determine whether a user has the requested
access to resources logically contained within the scope.

Inheritance
The IAzScope interface inherits from the IDispatch interface. IAzScope also has these types of members:

Methods
The IAzScope interface has these methods.

IAzScope::AddPolicyAdministrator

The AddPolicyAdministrator method of IAzScope adds the specified security identifier in text form to the list of principals that
act as policy administrators.

IAzScope::AddPolicyAdministratorName

The AddPolicyAdministratorName method of IAzScope adds the specified account name to the list of principals that act as
policy administrators.

IAzScope::AddPolicyReader

The AddPolicyReader method of IAzScope adds the specified security identifier in text form to the list of principals that act as
policy readers.

IAzScope::AddPolicyReaderName

The AddPolicyReaderName method of IAzScope adds the specified account name to the list of principals that act as policy
readers.

IAzScope::AddPropertyItem

Adds the specified principal to the specified list of principals.

IAzScope::CreateApplicationGroup

Creates an IAzApplicationGroup object with the specified name.

IAzScope::CreateRole

Creates an IAzRole object with the specified name.

IAzScope::CreateTask

Creates an IAzTask object with the specified name.

IAzScope::DeleteApplicationGroup

Removes the IAzApplicationGroup object with the specified name from the IAzScope object.

IAzScope::DeletePolicyAdministrator

The DeletePolicyAdministrator method of IAzScope removes the specified security identifier in text form from the list of
principals that act as policy administrators.

IAzScope::DeletePolicyAdministratorName

The DeletePolicyAdministratorName method of IAzScope removes the specified account name from the list of principals that
act as policy administrators.

IAzScope::DeletePolicyReader

The DeletePolicyReader method of IAzScope removes the specified security identifier in text form from the list of principals that
act as policy readers.

IAzScope::DeletePolicyReaderName

The DeletePolicyReaderName method of IAzScope removes the specified account name from the list of principals that act as
policy readers.

IAzScope::DeletePropertyItem

Removes the specified principal from the specified list of principals.

IAzScope::DeleteRole

Removes the IAzRole object with the specified name from the IAzScope object.

IAzScope::DeleteTask

Removes the IAzTask object with the specified name from the IAzScope object.

IAzScope::get_ApplicationData

The ApplicationData property of IAzScope sets or retrieves an opaque field that can be used by the application to store
information.

IAzScope::get_ApplicationGroups

Retrieves an IAzApplicationGroups object that is used to enumerate IAzApplicationGroup objects from the policy data.

IAzScope::get_BizrulesWritable

Retrieves a value that indicates whether a non-delegated scope is writable.

IAzScope::get_CanBeDelegated

Retrieves a value that indicates whether the scope can be delegated.

IAzScope::get_Description

Sets or retrieves a comment that describes the scope.

IAzScope::get_Name

Sets or retrieves the name of the scope.

IAzScope::get_PolicyAdministrators

The PolicyAdministrators property of IAzScope retrieves the security identifiers (SIDs), in text form, of principals that act as
policy administrators.

IAzScope::get_PolicyAdministratorsName

Retrieves the account names of principals that act as policy administrators.

IAzScope::get_PolicyReaders

The PolicyReaders property of IAzScope retrieves the security identifiers (SIDs), in text form, of principals that act as policy
readers.

IAzScope::get_PolicyReadersName

Retrieves the account names of principals that act as policy readers.

IAzScope::get_Roles

Retrieves an IAzRoles object that is used to enumerate IAzRole objects from the policy data.

IAzScope::get_Tasks

Retrieves an IAzTasks object that is used to enumerate IAzTask objects from the policy data.

IAzScope::get_Writable

Retrieves a value that indicates whether the scope can be modified by the user context that initialized it.

IAzScope::GetProperty

Returns the IAzScope object property with the specified property ID.

IAzScope::OpenApplicationGroup

Opens an IAzApplicationGroup object by specifying its name.

IAzScope::OpenRole

Opens an IAzRole object with the specified name.

IAzScope::OpenTask

Opens an IAzTask object with the specified name.

IAzScope::put_ApplicationData

The ApplicationData property of IAzScope sets or retrieves an opaque field that can be used by the application to store
information.
 IAzScope::put_Description

Sets or retrieves a comment that describes the scope.

IAzScope::put_Name

Sets or retrieves the name of the scope.

IAzScope::SetProperty

Sets the specified value to the IAzScope object property with the specified property ID.

IAzScope::Submit

Persists changes made to the IAzScope object.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzScope::AddPolicyAdministrator method
(azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The AddPolicyAdministrator method adds the specified security identifier (SID) in text form to the list of
principals that act as policy administrators.

Syntax
HRESULT AddPolicyAdministrator(
[in] BSTR bstrAdmin,
[in, optional] VARIANT varReserved
);

Parameters
[in] bstrAdmin

Text form of the SID to add to the list of policy administrators.

[in, optional] varReserved

Reserved for future use.

Return value
None

Remarks
Policy administrators for an object can perform the following tasks:
Read the object
Write attributes to the object
Read attributes of child objects of the object
Write attributes to child objects of the object
Delete the object
Delete child objects of the object
Create child objects of the object
To view the list of policy administrators, use the PolicyAdministrators property.
You must call the Submit method to persist any changes made by this method.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzScope::AddPolicyAdministratorName method
(azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The AddPolicyAdministratorName method adds the specified account name to the list of principals that act
as policy administrators.

Syntax
HRESULT AddPolicyAdministratorName(
[in] BSTR bstrAdmin,
[in, optional] VARIANT varReserved
);

Parameters
[in] bstrAdmin

The account name to add to the list of policy administrators. The account name can be in either user principal
name (UPN) format (for example, "someone@example.com") or in the "ExampleDomain\UserName" format. If
the domain is not in the "ExampleDomain\UserName" format, the LookupAccountName function is called to
retrieve the domain.
[in, optional] varReserved

Reserved for future use.

Return value
None

Remarks
Policy administrators for an object can perform the following tasks:
Read the object
Write attributes to the object
Read attributes of child objects of the object
Write attributes to child objects of the object
Delete the object
Delete child objects of the object
Create child objects of the object
To view the list of policy administrators in account name format, use the PolicyAdministratorsName property.
You must call the Submit method to persist any changes made by this method.

Requirements
Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzScope::AddPolicyReader method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The AddPolicyReader method adds the specified security identifier (SID) in text form to the list of principals
that act as policy readers.

Syntax
HRESULT AddPolicyReader(
[in] BSTR bstrReader,
[in, optional] VARIANT varReserved
);

Parameters
[in] bstrReader

Text form of the SID to add to the list of policy readers.

[in, optional] varReserved

Reserved for future use.

Return value
None

Remarks
Policy readers for an object can read attributes for the object and for child objects of the object. Readers can also
use the policy; for example, readers can call the AccessCheck method. Readers cannot modify the object or its
child objects.
To view the list of policy readers, use the PolicyReaders property.
You must call the Submit method to persist any changes made by this method.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib
DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzScope::AddPolicyReaderName method
(azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The AddPolicyReaderName method adds the specified account name to the list of principals that act as policy
readers.

Syntax
HRESULT AddPolicyReaderName(
[in] BSTR bstrReader,
[in, optional] VARIANT varReserved
);

Parameters
[in] bstrReader

Account name to add to the list of policy readers. The account name can be in either user principal name (UPN)
format (for example, "someone@example.com") or in the "ExampleDomain\UserName" format. If the domain is
not in the "ExampleDomain\UserName" format, the LookupAccountName function is called to retrieve the
domain.
[in, optional] varReserved

Reserved for future use.

Return value
None

Remarks
Policy readers for an object can read attributes for the object and for child objects of the object. Readers can also
use the policy; for example, readers can call the AccessCheck method. Readers cannot modify the object or its
child objects.
To view the list of policy readers in account name format, use the PolicyReadersName property.
You must call the Submit method to persist any changes made by this method.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]
Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzScope::AddPropertyItem method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The AddProper tyItem method adds the specified principal to the specified list of principals.

Syntax
HRESULT AddPropertyItem(
[in] LONG lPropId,
[in] VARIANT varProp,
[in, optional] VARIANT varReserved
);

Parameters
[in] lPropId

Property ID of the list of principals to which to add the principal specified by the varProp parameter. The
following table shows the possible values.

VA L UE M EA N IN G

Can also be added using the AddPolicyAdministrator

AZ_PROP_POLICY_ADMINS method

Can also be added using the AddPolicyAdministratorName

AZ_PROP_POLICY_ADMINS_NAME method

Can also be added using the AddPolicyReader method

AZ_PROP_POLICY_READERS

Can also be added using the AddPolicyReaderName method

AZ_PROP_POLICY_READERS_NAME

[in] varProp

Principal to add to the list of principals specified by the lPropId parameter.

The variant must be a BSTR variant.
If AZ_PROP_POLICY_ADMINS or AZ_PROP_POLICY_READERS is specified for the lPropId parameter, the string is
the text form of the security identifier (SID) of the Windows account to add to the list. If
AZ_PROP_POLICY_ADMINS_NAME or AZ_PROP_POLICY_READERS_NAME is specified for the lPropId
parameter, the string is the account name of the account to add to the list. The account name can be in either
user principal name (UPN) format (for example, "someone@example.com") or in the
"ExampleDomain\UserName" format.
[in, optional] varReserved

Reserved for future use.

Return value
The return value is an HRESULT . A value of S_OK indicates success. Any other value indicates that the operation
failed.

Remarks
You must call the Submit method to persist any changes made by this method.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzScope::CreateApplicationGroup method
(azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The CreateApplicationGroup method creates an IAzApplicationGroup object with the specified name.

Syntax
HRESULT CreateApplicationGroup(
[in] BSTR bstrGroupName,
[in, optional] VARIANT varReserved,
[out] IAzApplicationGroup **ppGroup
);

Parameters
[in] bstrGroupName

Name for the new IAzApplicationGroup object.

[in, optional] varReserved

Reserved for future use.

[out] ppGroup

A pointer to a pointer to the created IAzApplicationGroup object.

Return value
The return value is an HRESULT . A value of S_OK indicates success. Any other value indicates that the operation
failed.

Remarks
You must call the IAzApplicationGroup::Submit method to persist any changes made to the returned object.
The returned IAzApplicationGroup object is an immediate child object of the IAzScope object.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h
Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzScope::CreateRole method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The CreateRole method creates an IAzRole object with the specified name.

Syntax
HRESULT CreateRole(
[in] BSTR bstrRoleName,
[in, optional] VARIANT varReserved,
[out] IAzRole **ppRole
);

Parameters
[in] bstrRoleName

Name for the new IAzRole object.

[in, optional] varReserved

Reserved for future use.

[out] ppRole

A pointer to a pointer to the created IAzRole object.

Return value
The return value is an HRESULT . A value of S_OK indicates success. Any other value indicates that the operation
failed.

Remarks
You must call the IAzRole::Submit method to persist any changes made to the returned object.
The returned IAzRole object is an immediate child object of the IAzScope object.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib
DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzScope::CreateTask method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The CreateTask method creates an IAzTask object with the specified name.

Syntax
HRESULT CreateTask(
[in] BSTR bstrTaskName,
[in, optional] VARIANT varReserved,
[out] IAzTask **ppTask
);

Parameters
[in] bstrTaskName

Name for the new IAzTask object.

[in, optional] varReserved

Reserved for future use.

[out] ppTask

A pointer to a pointer to the created IAzTask object.

Return value
The return value is an HRESULT . A value of S_OK indicates success. Any other value indicates that the operation
failed.

Remarks
You must call the IAzTask::Submit method to persist any changes made to the returned object.
The returned IAzTask object is an immediate child object of the IAzScope object.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib
DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzScope::DeleteApplicationGroup method
(azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The DeleteApplicationGroup method removes the IAzApplicationGroup object with the specified name from
the IAzScope object.

Syntax
HRESULT DeleteApplicationGroup(
[in] BSTR bstrGroupName,
[in, optional] VARIANT varReserved
);

Parameters
[in] bstrGroupName

Name of the IAzApplicationGroup object to delete.

[in, optional] varReserved

Reserved for future use.

Return value
None

Remarks
If there are any IAzApplicationGroup references to an IAzApplicationGroup object that has been deleted from
the cache, the IAzApplicationGroup object can no longer be used. In C++, you must release references to
deleted IAzApplicationGroup objects by calling the IUnknown::Release method. In Visual Basic, references to
deleted objects are automatically released.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib
DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzScope::DeletePolicyAdministrator method
(azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The DeletePolicyAdministrator method removes the specified security identifier (SID) in text form from the
list of principals that act as policy administrators.

Syntax
HRESULT DeletePolicyAdministrator(
[in] BSTR bstrAdmin,
[in, optional] VARIANT varReserved
);

Parameters
[in] bstrAdmin

Text form of the SID to remove from the list of policy administrators.
[in, optional] varReserved

Reserved for future use.

Return value
None

Remarks
Policy administrators for an object can perform the following tasks:
Read the object
Write attributes to the object
Read attributes of child objects of the object
Write attributes to child objects of the object
Delete the object
Delete child objects of the object
Create child objects of the object
To view the list of policy administrators, use the PolicyAdministrators property.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]
Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzScope::DeletePolicyAdministratorName method
(azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The DeletePolicyAdministratorName method removes the specified account name from the list of principals
that act as policy administrators.

Syntax
HRESULT DeletePolicyAdministratorName(
[in] BSTR bstrAdmin,
[in, optional] VARIANT varReserved
);

Parameters
[in] bstrAdmin

Account name to remove from the list of policy administrators. The account name can be in either user principal
name (UPN) format (for example, "someone@example.com") or in the "ExampleDomain\UserName" format. If
the domain is not in the "ExampleDomain\UserName" format, the LookupAccountName function is called to
retrieve the domain.
[in, optional] varReserved

Reserved for future use.

Return value
None

Remarks
Policy administrators for an object can perform the following tasks:
Read the object
Write attributes to the object
Read attributes of child objects of the object
Write attributes to child objects of the object
Delete the object
Delete child objects of the object
Create child objects of the object
To view the list of policy administrators in account name format, use the PolicyAdministratorsName property.

Requirements
Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzScope::DeletePolicyReader method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The DeletePolicyReader method removes the specified security identifier (SID) in text form from the list of
principals that act as policy readers.

Syntax
HRESULT DeletePolicyReader(
[in] BSTR bstrReader,
[in, optional] VARIANT varReserved
);

Parameters
[in] bstrReader

Text form of the SID to remove from the list of policy readers.
[in, optional] varReserved

Reserved for future use.

Return value
None

Remarks
Policy readers for an object can read attributes for the object and for child objects of the object. Readers can also
use the policy; for example, readers can call the AccessCheck method. Readers cannot modify the object or its
child objects.
To view the list of policy readers, use the PolicyReaders property.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll
Redistributable Windows Server 2003 Administration Tools Pack on
Windows XP
 IAzScope::DeletePolicyReaderName method
(azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The DeletePolicyReaderName method removes the specified account name from the list of principals that act
as policy readers.

Syntax
HRESULT DeletePolicyReaderName(
[in] BSTR bstrReader,
[in, optional] VARIANT varReserved
);

Parameters
[in] bstrReader

Account name to remove from the list of policy readers. The account name can be in either user principal name
(UPN) format (for example, "someone@example.com") or in the "ExampleDomain\UserName" format. If the
domain is not in the "ExampleDomain\UserName" format, the LookupAccountName function is called to retrieve
the domain.
[in, optional] varReserved

Reserved for future use.

Return value
None

Remarks
Policy readers for an object can read attributes for the object and for child objects of the object. Readers can also
use the policy; for example, readers can call the AccessCheck method. Readers cannot modify the object or its
child objects.
To view the list of policy readers in account name format, use the PolicyReadersName property.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzScope::DeletePropertyItem method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The DeleteProper tyItem method removes the specified principal from the specified list of principals.

Syntax
HRESULT DeletePropertyItem(
[in] LONG lPropId,
[in] VARIANT varProp,
[in, optional] VARIANT varReserved
);

Parameters
[in] lPropId

Property ID of the list of principals from which to remove the principal specified by the varProp parameter. The
following table shows the possible values.

VA L UE M EA N IN G

Can also be removed using the DeletePolicyAdministrator

AZ_PROP_POLICY_ADMINS method

Can also be removed using the

AZ_PROP_POLICY_ADMINS_NAME DeletePolicyAdministratorName method

Can also be removed using the DeletePolicyReader method

AZ_PROP_POLICY_READERS

Can also be removed using the DeletePolicyReaderName

AZ_PROP_POLICY_READERS_NAME method

[in] varProp

Principal to remove from the list of principals specified by the lPropId parameter.
The variant must be a BSTR variant.
If AZ_PROP_POLICY_ADMINS or AZ_PROP_POLICY_READERS is specified for the lPropId parameter, the string is
the text form of the security identifier (SID) of the Windows account to remove from the list. If
AZ_PROP_POLICY_ADMINS_NAME or AZ_PROP_POLICY_READERS_NAME is specified for the lPropId
parameter, the string is the account name of the account to remove from the list. The account name can be in
either user principal name (UPN) format (for example, "someone@example.com") or in the
"ExampleDomain\UserName" format.
[in, optional] varReserved

Reserved for future use.

Return value
The return value is an HRESULT . A value of S_OK indicates success. Any other value indicates that the operation
failed.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzScope::DeleteRole method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The DeleteRole method removes the IAzRole object with the specified name from the IAzScope object.

Syntax
HRESULT DeleteRole(
[in] BSTR bstrRoleName,
[in, optional] VARIANT varReserved
);

Parameters
[in] bstrRoleName

Name of the IAzRole object to delete.

[in, optional] varReserved

Reserved for future use.

Return value
None

Remarks
If there are any IAzRole references to an IAzRole object that has been deleted from the cache, the IAzRole
object can no longer be used. In C++, you must release references to deleted IAzRole objects by calling the
IUnknown::Release method. In Visual Basic, references to deleted objects are automatically released.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzScope::DeleteTask method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The DeleteTask method removes the IAzTask object with the specified name from the IAzScope object.

Syntax
HRESULT DeleteTask(
[in] BSTR bstrTaskName,
[in, optional] VARIANT varReserved
);

Parameters
[in] bstrTaskName

Name of the IAzTask object to delete.

[in, optional] varReserved

Reserved for future use.

Return value
None

Remarks
If there are any IAzTask references to an IAzTask object that has been deleted from the cache, the IAzTask object
can no longer be used. In C++, you must release references to deleted IAzTask objects by calling the
IUnknown::Release method. In Visual Basic, references to deleted objects are automatically released.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzScope::get_ApplicationData method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The ApplicationData property sets or retrieves an opaque field that can be used by the application to store
information.
This property is read/write.

Syntax
HRESULT get_ApplicationData(
BSTR *pbstrApplicationData
);

Parameters
pbstrApplicationData

Return value
None

Remarks
Impor tant Policy administrators can read from and write to this property. Applications should not store data in the
ApplicationData property that should not be available to the policy administrator.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzScope::get_ApplicationGroups method
(azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The ApplicationGroups property retrieves an IAzApplicationGroups object that is used to enumerate

IAzApplicationGroup objects from the policy data.
This property is read-only.

Syntax
HRESULT get_ApplicationGroups(
IAzApplicationGroups **ppGroupCollection
);

Parameters
ppGroupCollection

Return value
None

Remarks
This property can be used only to enumerate IAzApplicationGroup objects that are direct child objects of the
IAzScope object.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzScope::get_BizrulesWritable method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The BizrulesWritable property retrieves a value that indicates whether a non-delegated scope is writable.
This property is read-only.

Syntax
HRESULT get_BizrulesWritable(
BOOL *pfProp
);

Parameters
pfProp

Return value
None

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzScope::get_CanBeDelegated method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The CanBeDelegated property retrieves a value that indicates whether the scope can be delegated.
This property is read-only.

Syntax
HRESULT get_CanBeDelegated(
BOOL *pfProp
);

Parameters
pfProp

Return value
None

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzScope::get_Description method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The Description property sets or retrieves a comment that describes the scope.
This property is read/write.

Syntax
HRESULT get_Description(
BSTR *pbstrDescription
);

Parameters
pbstrDescription

Return value
None

Remarks
The maximum length of the Description property is 1,024 characters.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzScope::get_Name method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The Name property sets or retrieves the name of the scope.

This property is read/write.

Syntax
HRESULT get_Name(
BSTR *pbstrName
);

Parameters
pbstrName

Return value
None

Remarks
The maximum length of the Name property is 512 characters.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzScope::get_PolicyAdministrators method
(azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The PolicyAdministrators property retrieves the security identifiers (SIDs), in text form, of principals that act
as policy administrators.
This property is read-only.

Syntax
HRESULT get_PolicyAdministrators(
VARIANT *pvarAdmins
);

Parameters
pvarAdmins

Return value
None

Remarks
Policy administrators for an object can perform the following tasks:
Read the object
Write attributes to the object
Read attributes of child objects of the object
Write attributes to child objects of the object
Delete the object
Delete child objects of the object
Create child objects of the object
In JScript, the returned SAFEARRAY must be converted to the JScript Array object.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h
Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzScope::get_PolicyAdministratorsName method
(azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The PolicyAdministratorsName property retrieves the account names of principals that act as policy
administrators.
This property is read-only.

Syntax
HRESULT get_PolicyAdministratorsName(
VARIANT *pvarAdmins
);

Parameters
pvarAdmins

Return value
None

Remarks
Policy administrators for an object can perform the following tasks:
Read the object
Write attributes to the object
Read attributes of child objects of the object
Write attributes to child objects of the object
Delete the object
Delete child objects of the object
Create child objects of the object
In JScript, the returned SAFEARRAY must be converted to the JScript Array object.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h
Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzScope::get_PolicyReaders method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The PolicyReaders property retrieves the security identifiers (SIDs), in text form, of principals that act as policy
readers.
This property is read-only.

Syntax
HRESULT get_PolicyReaders(
VARIANT *pvarReaders
);

Parameters
pvarReaders

Return value
None

Remarks
Policy readers for an object can read attributes for the object and for child objects of the object. Readers can also
use the policy; for example, readers can call the AccessCheck method. Readers cannot modify the object or its
child objects.
In JScript, the returned SAFEARRAY must be converted to the JScript Array object.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzScope::get_PolicyReadersName method
(azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The PolicyReadersName property retrieves the account names of principals that act as policy readers.
This property is read-only.

Syntax
HRESULT get_PolicyReadersName(
VARIANT *pvarReaders
);

Parameters
pvarReaders

Return value
None

Remarks
Policy readers for an object can read attributes for the object and for child objects of the object. Readers can also
use the policy; for example, readers can call the AccessCheck method. Readers cannot modify the object or its
child objects.
In JScript, the returned SAFEARRAY must be converted to the JScript Array object.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzScope::get_Roles method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The Roles property retrieves an IAzRoles object that is used to enumerate IAzRole objects from the policy data.
This property is read-only.

Syntax
HRESULT get_Roles(
IAzRoles **ppRoleCollection
);

Parameters
ppRoleCollection

Return value
None

Remarks
This property can be used only to enumerate IAzRole objects that are direct child objects of the IAzScope object.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzScope::get_Tasks method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The Tasks property retrieves an IAzTasks object that is used to enumerate IAzTask objects from the policy data.
This property is read-only.

Syntax
HRESULT get_Tasks(
IAzTasks **ppTaskCollection
);

Parameters
ppTaskCollection

Return value
None

Remarks
This property can be used only to enumerate IAzTask objects that are direct child objects of the IAzScope object.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzScope::get_Writable method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The Writable property retrieves a value that indicates whether the scope can be modified by the user context
that initialized it.
This property is read-only.

Syntax
HRESULT get_Writable(
BOOL *pfProp
);

Parameters
pfProp

Return value
None

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzScope::GetProperty method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The GetProper ty method returns the IAzScope object property with the specified property ID.

Syntax
HRESULT GetProperty(
[in] LONG lPropId,
[in, optional] VARIANT varReserved,
[out] VARIANT *pvarProp
);

Parameters
[in] lPropId

Property ID of the IAzScope object property to return. The following table shows the possible values.

VA L UE M EA N IN G

Also accessed through the ApplicationData property

AZ_PROP_APPLICATION_DATA

Determines whether the current user has permission to

AZ_PROP_CHILD_CREATE create child objects. This value is TRUE if the current user
has permission; otherwise, FALSE .

Also accessed through the Description property

AZ_PROP_DESCRIPTION

Also accessed through the Name property

AZ_PROP_NAME

Also accessed through the PolicyAdministrators property

AZ_PROP_POLICY_ADMINS

Also accessed through the PolicyAdministratorsName

AZ_PROP_POLICY_ADMINS_NAME property

Also accessed through the PolicyReaders property

AZ_PROP_POLICY_READERS

Also accessed through the PolicyReadersName property

AZ_PROP_POLICY_READERS_NAME

Also accessed through the BizrulesWritable property

AZ_PROP_SCOPE_BIZRULES_WRITABLE
 Also accessed through the CanBeDelegated property
AZ_PROP_SCOPE_CAN_BE_DELEGATED

Also accessed through the Writable property

AZ_PROP_WRITABLE

[in, optional] varReserved

Reserved for future use.

[out] pvarProp

A pointer to the returned IAzScope object property.

Return value
The return value is an HRESULT . A value of S_OK indicates success. Any other value indicates that the operation
failed.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzScope::OpenApplicationGroup method
(azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The OpenApplicationGroup method opens an IAzApplicationGroup object with the specified name.

Syntax
HRESULT OpenApplicationGroup(
[in] BSTR bstrGroupName,
[in, optional] VARIANT varReserved,
[out] IAzApplicationGroup **ppGroup
);

Parameters
[in] bstrGroupName

Name of the IAzApplicationGroup object to open.

[in, optional] varReserved

Reserved for future use.

[out] ppGroup

A pointer to a pointer to the opened IAzApplicationGroup object.

Return value
The return value is an HRESULT . A value of S_OK indicates success. Any other value indicates that the operation
failed.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll
Redistributable Windows Server 2003 Administration Tools Pack on
Windows XP
 IAzScope::OpenRole method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The OpenRole method opens an IAzRole object with the specified name.

Syntax
HRESULT OpenRole(
[in] BSTR bstrRoleName,
[in, optional] VARIANT varReserved,
[out] IAzRole **ppRole
);

Parameters
[in] bstrRoleName

Name of the IAzRole object to open.

[in, optional] varReserved

Reserved for future use.

[out] ppRole

A pointer to a pointer to the opened IAzRole object.

Return value
The return value is an HRESULT . A value of S_OK indicates success. Any other value indicates that the operation
failed.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzScope::OpenTask method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The OpenTask method opens an IAzTask object with the specified name.

Syntax
HRESULT OpenTask(
[in] BSTR bstrTaskName,
[in, optional] VARIANT varReserved,
[out] IAzTask **ppTask
);

Parameters
[in] bstrTaskName

Name of the IAzTask object to open.

[in, optional] varReserved

Reserved for future use.

[out] ppTask

A pointer to a pointer to the opened IAzTask object.

Return value
The return value is an HRESULT . A value of S_OK indicates success. Any other value indicates that the operation
failed.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzScope::put_ApplicationData method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The ApplicationData property sets or retrieves an opaque field that can be used by the application to store
information.
This property is read/write.

Syntax
HRESULT put_ApplicationData(
BSTR bstrApplicationData
);

Parameters
bstrApplicationData

Return value
None

Remarks
Impor tant Policy administrators can read from and write to this property. Applications should not store data in the
ApplicationData property that should not be available to the policy administrator.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzScope::put_Description method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The Description property sets or retrieves a comment that describes the scope.
This property is read/write.

Syntax
HRESULT put_Description(
BSTR bstrDescription
);

Parameters
bstrDescription

Return value
None

Remarks
The maximum length of the Description property is 1,024 characters.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzScope::put_Name method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The Name property sets or retrieves the name of the scope.

This property is read/write.

Syntax
HRESULT put_Name(
BSTR bstrName
);

Parameters
bstrName

Return value
None

Remarks
The maximum length of the Name property is 512 characters.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzScope::SetProperty method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The SetProper ty method sets the specified value to the IAzScope object property with the specified property
ID.

Syntax
HRESULT SetProperty(
[in] LONG lPropId,
[in] VARIANT varProp,
[in, optional] VARIANT varReserved
);

Parameters
[in] lPropId

Property ID of the IAzScope object property to set. The following table shows the possible values.

VA L UE M EA N IN G

Also accessed through the ApplicationData property

AZ_PROP_APPLICATION_DATA

Also accessed through the Description property

AZ_PROP_DESCRIPTION

Also accessed through the Name property

AZ_PROP_NAME

[in] varProp

Value to set to the IAzScope object property specified by the lPropId parameter. The following table shows the
type of data that must be used depending on the value of the lPropId parameter.

L P RO P ID VA L UE DATA T Y P E ( C ++/ VISUA L B A SIC )

BSTR/String
AZ_PROP_APPLICATION_DATA

BSTR/String
AZ_PROP_DESCRIPTION

BSTR/String
AZ_PROP_NAME

[in, optional] varReserved

Reserved for future use.

Return value
The return value is an HRESULT . A value of S_OK indicates success. Any other value indicates that the operation
failed.

Remarks
You must call the Submit method to persist any changes made by this method.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzScope::Submit method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The Submit method persists changes made to the IAzScope object.

Syntax
HRESULT Submit(
[in] LONG lFlags,
[in, optional] VARIANT varReserved
);

Parameters
[in] lFlags

Flags that modify the behavior of the Submit method. The default value is zero. If the AZ_SUBMIT_FLAG_ABORT
flag is specified, the changes to the object are discarded and the object is updated to match the underlying
policy store.
[in, optional] varReserved

Reserved for future use.

Return value
None

Remarks
Any additions or modifications to an IAzScope object are not persisted until the Submit method is called.
The Submit method does not extend to child objects; child objects must be individually persisted to the policy
store. A created IAzScope object must be submitted before it can be referenced or become a parent object. The
destructor for an object silently discards unsubmitted changes.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib
DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzScope2 interface (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The IAzScope2 interface extends the IAzScope interface to manage IAzRoleAssignment and IAzRoleDefinition
objects.

Inheritance
The IAzScope2 interface inherits from IAzScope. IAzScope2 also has these types of members:

Methods
The IAzScope2 interface has these methods.

IAzScope2::CreateRoleAssignment

Creates a new IAzRoleAssignment object with the specified name in this scope.

IAzScope2::CreateRoleDefinition

Creates a new IAzRoleDefinition object with the specified name in this scope.

IAzScope2::DeleteRoleAssignment

Removes the specified IAzRoleAssignment object from this scope.

IAzScope2::DeleteRoleDefinition

Removes the specified IAzRoleDefinition object from this scope.

IAzScope2::get_RoleAssignments

Retrieves an IAzRoleAssignments object that represents the collection of IAzRoleAssignment objects associated with this scope.

IAzScope2::get_RoleDefinitions

Retrieves an IAzRoleDefinitions object that represents the collection of IAzRoleDefinition objects associated with this scope.

IAzScope2::OpenRoleAssignment

Opens an IAzRoleAssignment object with the specified name in this scope.

IAzScope2::OpenRoleDefinition

Opens an IAzRoleDefinition object with the specified name in this scope.

Requirements
Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header azroles.h
 IAzScope2::CreateRoleAssignment method
(azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The CreateRoleAssignment method creates a new IAzRoleAssignment object with the specified name in this
scope.

Syntax
HRESULT CreateRoleAssignment(
[in] BSTR bstrRoleAssignmentName,
[out] IAzRoleAssignment **ppRoleAssignment
);

Parameters
[in] bstrRoleAssignmentName

A string that contains the name of the new IAzRoleAssignment object.

[out] ppRoleAssignment

The address of a pointer to the IAzRoleAssignment object that this method creates.
When you have finished using the IAzRoleAssignment object, release it by calling the IUnknown::Release
method.

Return value
If the method succeeds, it returns S_OK .
If the method fails, it returns an error code. For a list of common error codes, see Common HRESULT Values.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header azroles.h

DLL Azroles.dll
 IAzScope2::CreateRoleDefinition method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The CreateRoleDefinition method creates a new IAzRoleDefinition object with the specified name in this
scope.

Syntax
HRESULT CreateRoleDefinition(
[in] BSTR bstrRoleDefinitionName,
[out] IAzRoleDefinition **ppRoleDefinitions
);

Parameters
[in] bstrRoleDefinitionName

A string that contains the name of the new IAzRoleDefinition object.

[out] ppRoleDefinitions

The address of a pointer to the IAzRoleDefinition object that this method creates.
When you have finished using the IAzRoleDefinition object, release it by calling the IUnknown::Release method.

Return value
If the method succeeds, it returns S_OK .
If the method fails, it returns an error code. For a list of common error codes, see Common HRESULT Values.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header azroles.h

DLL Azroles.dll
 IAzScope2::DeleteRoleAssignment method
(azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The DeleteRoleAssignment method removes the specified IAzRoleAssignment object from this scope.

Syntax
HRESULT DeleteRoleAssignment(
[in] BSTR bstrRoleAssignmentName
);

Parameters
[in] bstrRoleAssignmentName

A string that contains the name of the IAzRoleAssignment object to remove.

Return value
If the method succeeds, it returns S_OK .
If the method fails, it returns an error code. For a list of common error codes, see Common HRESULT Values.

Remarks
If any references to an IAzRoleAssignment object have been deleted from the cache, the IAzRoleAssignment
object can no longer be used. In C++, you must release references to deleted IAzRoleAssignment objects by
calling the IUnknown::Release method. In Visual Basic, references to deleted objects are automatically released.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header azroles.h

DLL Azroles.dll
 IAzScope2::DeleteRoleDefinition method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The DeleteRoleDefinition method removes the specified IAzRoleDefinition object from this scope.

Syntax
HRESULT DeleteRoleDefinition(
[in] BSTR bstrRoleDefinitionName
);

Parameters
[in] bstrRoleDefinitionName

A string that contains the name of the IAzRoleDefinition object to remove.

Return value
If the method succeeds, it returns S_OK .
If the method fails, it returns an error code. For a list of common error codes, see Common HRESULT Values.

Remarks
If any references to an IAzRoleDefinition object have been deleted from the cache, that object can no longer be
used. In C++, you must release references to deleted IAzRoleDefinition objects by calling the
IUnknown::Release method. In Visual Basic, references to deleted objects are automatically released.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header azroles.h

DLL Azroles.dll
 IAzScope2::get_RoleAssignments method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The RoleAssignments property retrieves an IAzRoleAssignments object that represents the collection of
IAzRoleAssignment objects associated with this scope.
This property is read-only.

Syntax
HRESULT get_RoleAssignments(
IAzRoleAssignments **ppRoleAssignments
);

Parameters
ppRoleAssignments

Return value
None

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header azroles.h

DLL Azroles.dll
 IAzScope2::get_RoleDefinitions method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The RoleDefinitions property retrieves an IAzRoleDefinitions object that represents the collection of
IAzRoleDefinition objects associated with this scope.
This property is read-only.

Syntax
HRESULT get_RoleDefinitions(
IAzRoleDefinitions **ppRoleDefinitions
);

Parameters
ppRoleDefinitions

Return value
None

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header azroles.h

DLL Azroles.dll
 IAzScope2::OpenRoleAssignment method
(azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The OpenRoleAssignment method opens an IAzRoleAssignment object with the specified name in this scope.

Syntax
HRESULT OpenRoleAssignment(
[in] BSTR bstrRoleAssignmentName,
[out] IAzRoleAssignment **ppRoleAssignment
);

Parameters
[in] bstrRoleAssignmentName

A string that contains the name of the IAzRoleAssignment object to open.

[out] ppRoleAssignment

The address of a pointer to the IAzRoleAssignment object that this method opens.
When you have finished using the IAzRoleAssignment object, release it by calling the IUnknown::Release
method.

Return value
If the method succeeds, it returns S_OK .
If the method fails, it returns an error code. For a list of common error codes, see Common HRESULT Values.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header azroles.h

DLL Azroles.dll
 IAzScope2::OpenRoleDefinition method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The OpenRoleDefinition method opens an IAzRoleDefinition object with the specified name in this scope.

Syntax
HRESULT OpenRoleDefinition(
[in] BSTR bstrRoleDefinitionName,
[out] IAzRoleDefinition **ppRoleDefinitions
);

Parameters
[in] bstrRoleDefinitionName

A string that contains the name of the IAzRoleDefinition object to open.

[out] ppRoleDefinitions

The address of a pointer to the IAzRoleDefinition object that this method opens.
When you have finished using the IAzRoleDefinition object, release it by calling the IUnknown::Release method.

Return value
If the method succeeds, it returns S_OK .
If the method fails, it returns an error code. For a list of common error codes, see Common HRESULT Values.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header azroles.h

DLL Azroles.dll
 IAzScopes interface (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The IAzScopes interface represents a collection of

IAzScope objects.

Inheritance
The IAzScopes interface inherits from the IDispatch interface.

Methods
The IAzScopes interface has these methods.

IAzScopes::get__NewEnum

The _NewEnum property of IAzScopes retrieves an IEnumVARIANT interface on an object that can be used to enumerate the
collection. This property is hidden within Visual Basic and Visual Basic Scripting Edition (VBScript).

IAzScopes::get_Count

Retrieves the number of IAzScope objects in the collection.

IAzScopes::get_Item

Retrieves the IAzScope object at the specified index into the IAzScopes collection.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzScopes::get__NewEnum method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The NewEnum property retrieves an IEnumVARIANT interface on an object that can be used to enumerate the
collection. This property is hidden within Visual Basic and Visual Basic Scripting Edition (VBScript).
This property is read-only.

Syntax
HRESULT get__NewEnum(
LPUNKNOWN *ppEnumPtr
);

Parameters
ppEnumPtr

Return value
None

Remarks
This property is provided for use by the For Each keyword in Visual Basic and the foreach keyword in Visual
C#.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzScopes::get_Count method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The Count property retrieves the number of IAzScope objects in the collection.
This property is read-only.

Syntax
HRESULT get_Count(
LONG *plCount
);

Parameters
plCount

Return value
None

Remarks
The Count property can be used to specify the last IAzScope object in a collection when retrieving a specific
IAzScope object using the IAzScopes.Item property.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzScopes::get_Item method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The Item property retrieves the IAzScope object at the specified index into the IAzScopes collection.
This property is read-only.

Syntax
HRESULT get_Item(
LONG Index,
VARIANT *pvarObtPtr
);

Parameters
Index

pvarObtPtr

Return value
None

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzTask interface (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The IAzTask interface describes a set of operations.

Inheritance
The IAzTask interface inherits from the IDispatch interface. IAzTask also has these types of members:

Methods
The IAzTask interface has these methods.

IAzTask::AddOperation

Adds the IAzOperation object with the specified name to the task.

IAzTask::AddPropertyItem

Adds the specified entity to the specified list.

IAzTask::AddTask

Adds the IAzTask object with the specified name to the task.

IAzTask::DeleteOperation

Removes the IAzOperation object with the specified name from the task.

IAzTask::DeletePropertyItem

Removes the specified entity from the specified list.

IAzTask::DeleteTask

Removes the IAzTask object with the specified name from the task.

IAzTask::get_ApplicationData

The ApplicationData property of IAzTask sets or retrieves an opaque field that can be used by the application to store
information.

IAzTask::get_BizRule

Sets or retrieves the text of the script that implements the business rule (BizRule).

IAzTask::get_BizRuleImportedPath

Sets or retrieves the path to the file from which the business rule (BizRule) is imported.
IAzTask::get_BizRuleLanguage

Sets or retrieves the scripting language in which the business rule (BizRule) is implemented.

IAzTask::get_Description

Sets or retrieves a comment that describes the task.

IAzTask::get_IsRoleDefinition

Sets or retrieves a value that indicates whether the task is a role definition.

IAzTask::get_Name

Sets or retrieves the name of the task.

IAzTask::get_Operations

Retrieves the operations associated with the task.

IAzTask::get_Tasks

Retrieves the tasks associated with the task.

IAzTask::get_Writable

Retrieves a value that indicates whether the task can be modified by the user context that initialized it.

IAzTask::GetProperty

Returns the IAzTask object property with the specified property ID.

IAzTask::put_ApplicationData

The ApplicationData property of IAzTask sets or retrieves an opaque field that can be used by the application to store
information.

IAzTask::put_BizRule

Sets or retrieves the text of the script that implements the business rule (BizRule).

IAzTask::put_BizRuleImportedPath

Sets or retrieves the path to the file from which the business rule (BizRule) is imported.

IAzTask::put_BizRuleLanguage

Sets or retrieves the scripting language in which the business rule (BizRule) is implemented.

IAzTask::put_Description

Sets or retrieves a comment that describes the task.

 IAzTask::put_IsRoleDefinition

Sets or retrieves a value that indicates whether the task is a role definition.

IAzTask::put_Name

Sets or retrieves the name of the task.

IAzTask::SetProperty

Sets the specified value to the IAzTask object property with the specified property ID.

IAzTask::Submit

Persists changes made to the IAzTask object.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzTask::AddOperation method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The AddOperation method adds the IAzOperation object with the specified name to the task.

Syntax
HRESULT AddOperation(
[in] BSTR bstrOp,
[in, optional] VARIANT varReserved
);

Parameters
[in] bstrOp

Name of the IAzOperation object to add to the task.

[in, optional] varReserved

Reserved for future use.

Return value
None

Remarks
You must call the Submit method to persist any changes made by this method.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzTask::AddPropertyItem method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The AddProper tyItem method adds the specified entity to the specified list.

Syntax
HRESULT AddPropertyItem(
[in] LONG lPropId,
[in] VARIANT varProp,
[in, optional] VARIANT varReserved
);

Parameters
[in] lPropId

Property ID of the list to which to add the entity specified by the varProp parameter. The following table shows
the possible values.

VA L UE M EA N IN G

Can also be added using the AddOperation method

AZ_PROP_TASK_OPERATIONS

Can also be added using the AddTask method

AZ_PROP_TASK_TASKS

[in] varProp

Name of the entity to add to the list specified by the lPropId parameter.
The variant must be a BSTR variant.
[in, optional] varReserved

Reserved for future use.

Return value
The return value is an HRESULT . A value of S_OK indicates success. Any other value indicates that the operation
failed.

Remarks
You must call the Submit method to persist any changes made by this method.

Requirements
Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzTask::AddTask method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The AddTask method adds the IAzTask object with the specified name to the task.

Syntax
HRESULT AddTask(
[in] BSTR bstrTask,
[in, optional] VARIANT varReserved
);

Parameters
[in] bstrTask

Name of the IAzTask object to add to the task.

[in, optional] varReserved

Reserved for future use.

Return value
None

Remarks
This method allows the nesting of IAzTask objects within another IAzTask object.
You must call the Submit method to persist any changes made by this method.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzTask::DeleteOperation method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The DeleteOperation method removes the IAzOperation object with the specified name from the task.

Syntax
HRESULT DeleteOperation(
[in] BSTR bstrOp,
[in, optional] VARIANT varReserved
);

Parameters
[in] bstrOp

Name of the IAzOperation object to remove from the task.

[in, optional] varReserved

Reserved for future use.

Return value
None

Remarks
If there are any IAzOperation references to an IAzOperation object that has been deleted from the cache, the
IAzOperation object can no longer be used. In C++, you must release references to deleted IAzOperation
objects by calling the IUnknown::Release method. In Visual Basic, references to deleted objects are automatically
released.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll
Redistributable Windows Server 2003 Administration Tools Pack on
Windows XP
 IAzTask::DeletePropertyItem method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The DeleteProper tyItem method removes the specified entity from the specified list.

Syntax
HRESULT DeletePropertyItem(
[in] LONG lPropId,
[in] VARIANT varProp,
[in, optional] VARIANT varReserved
);

Parameters
[in] lPropId

Property ID of the list from which to remove the entity specified by the varProp parameter. The following table
shows the possible values.

VA L UE M EA N IN G

Can also be removed using the DeleteOperation method

AZ_PROP_TASK_OPERATIONS

Can also be removed using the DeleteTask method

AZ_PROP_TASK_TASKS

[in] varProp

Name of the entity to remove from the list specified by the lPropId parameter.
The variant must be a BSTR variant.
[in, optional] varReserved

Reserved for future use.

Return value
The return value is an HRESULT . A value of S_OK indicates success. Any other value indicates that the operation
failed.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]
Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzTask::DeleteTask method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The DeleteTask method removes the IAzTask object with the specified name from the task.

Syntax
HRESULT DeleteTask(
[in] BSTR bstrTask,
[in, optional] VARIANT varReserved
);

Parameters
[in] bstrTask

Name of the IAzTask object to remove from the task.

[in, optional] varReserved

Reserved for future use.

Return value
None

Remarks
If there are any IAzTask references to an IAzTask object that has been deleted from the cache, the IAzTask object
can no longer be used. In C++, you must release references to deleted IAzTask objects by calling the
IUnknown::Release method. In Visual Basic, references to deleted objects are automatically released.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzTask::get_ApplicationData method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The ApplicationData property sets or retrieves an opaque field that can be used by the application to store
information.
This property is read/write.

Syntax
HRESULT get_ApplicationData(
BSTR *pbstrApplicationData
);

Parameters
pbstrApplicationData

Return value
None

Remarks
Impor tant Policy administrators can read from and write to this property. Applications should not store data in the
ApplicationData property that should not be available to the policy administrator.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzTask::get_BizRule method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The BizRule property sets or retrieves the text of the script that implements the business rule (BizRule).
This property is read/write.

Syntax
HRESULT get_BizRule(
BSTR *pbstrProp
);

Parameters
pbstrProp

Return value
None

Remarks
The maximum length of this property is 65,536 characters.

Impor tant The BizRuleLanguage property must be set before this property is set.

An IAzTask object that is a child object of a delegated IAzScope object cannot have an associated BizRule.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
See also
BizRuleImportedPath
BizRuleLanguage
IAzTask
 IAzTask::get_BizRuleImportedPath method
(azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The BizRuleImpor tedPath property sets or retrieves the path to the file from which the business rule (BizRule)
is imported.
This property is read/write.

Syntax
HRESULT get_BizRuleImportedPath(
BSTR *pbstrProp
);

Parameters
pbstrProp

Return value
None

Remarks
The path information is stored for use by the UI. The UI should supply a mechanism to synchronize the contents
of the file and this property.
The maximum length of this property is 512 characters.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
See also
BizRule
BizRuleLanguage
IAzTask
 IAzTask::get_BizRuleLanguage method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The BizRuleLanguage property sets or retrieves the scripting language in which the business rule (BizRule) is
implemented.
This property is read/write.

Syntax
HRESULT get_BizRuleLanguage(
BSTR *pbstrProp
);

Parameters
pbstrProp

Return value
None

Remarks
This property must be set before the BizRule property is set.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP

See also
BizRule
BizRuleImportedPath
IAzTask
 IAzTask::get_Description method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The Description property sets or retrieves a comment that describes the task.
This property is read/write.

Syntax
HRESULT get_Description(
BSTR *pbstrDescription
);

Parameters
pbstrDescription

Return value
None

Remarks
The maximum length of the Description property is 1,024 characters.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzTask::get_IsRoleDefinition method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The IsRoleDefinition property sets or retrieves a value that indicates whether the task is a role definition.
This property is read/write.

Syntax
HRESULT get_IsRoleDefinition(
BOOL *pfProp
);

Parameters
pfProp

Return value
None

Remarks
This property represents a user interface abstraction and does not affect the functionality of the task.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzTask::get_Name method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The Name property sets or retrieves the name of the task.

This property is read/write.

Syntax
HRESULT get_Name(
BSTR *pbstrName
);

Parameters
pbstrName

Return value
None

Remarks
The maximum length of the Name property is 64 characters.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzTask::get_Operations method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The Operations property retrieves the operations associated with the task.
This property is read-only.

Syntax
HRESULT get_Operations(
VARIANT *pvarProp
);

Parameters
pvarProp

Return value
None

Remarks
In JScript, the returned SAFEARRAY must be converted to the JScript Array object.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzTask::get_Tasks method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The Tasks property retrieves the tasks associated with the task.
This property is read-only.

Syntax
HRESULT get_Tasks(
VARIANT *pvarProp
);

Parameters
pvarProp

Return value
None

Remarks
This property shows the nesting of IAzTask objects within another IAzTask object.
In JScript, the returned SAFEARRAY must be converted to the JScript Array object.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzTask::get_Writable method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The Writable property retrieves a value that indicates whether the task can be modified by the user context that
initialized it.
This property is read-only.

Syntax
HRESULT get_Writable(
BOOL *pfProp
);

Parameters
pfProp

Return value
None

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzTask::GetProperty method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The GetProper ty method returns the IAzTask object property with the specified property ID.

Syntax
HRESULT GetProperty(
[in] LONG lPropId,
[in, optional] VARIANT varReserved,
[out] VARIANT *pvarProp
);

Parameters
[in] lPropId

Property ID of the IAzTask object property to return. The following table shows the possible values.

VA L UE M EA N IN G

Also accessed through the ApplicationData property

AZ_PROP_APPLICATION_DATA

Determines whether the current user has permission to

AZ_PROP_CHILD_CREATE create child objects. This value is TRUE if the current user
has permission; otherwise, FALSE .

Also accessed through the Description property

AZ_PROP_DESCRIPTION

Also accessed through the Name property

AZ_PROP_NAME

Also accessed through the BizRule property

AZ_PROP_TASK_BIZRULE

Also accessed through the BizRuleLanguage property

AZ_PROP_TASK_BIZRULE_L ANGUAGE

Also accessed through the IsRoleDefinition property

AZ_PROP_TASK_IS_ROLE_DEFINITION

Also accessed through the Operations property

AZ_PROP_TASK_OPERATIONS

Also accessed through the Tasks property

AZ_PROP_TASK_TASKS
 Also accessed through the Writable property
AZ_PROP_WRITABLE

[in, optional] varReserved

Reserved for future use.

[out] pvarProp

A pointer to the returned IAzTask object property.

Return value
The return value is an HRESULT . A value of S_OK indicates success. Any other value indicates that the operation
failed.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzTask::put_ApplicationData method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The ApplicationData property sets or retrieves an opaque field that can be used by the application to store
information.
This property is read/write.

Syntax
HRESULT put_ApplicationData(
BSTR bstrApplicationData
);

Parameters
bstrApplicationData

Return value
None

Remarks
Impor tant Policy administrators can read from and write to this property. Applications should not store data in the
ApplicationData property that should not be available to the policy administrator.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzTask::put_BizRule method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The BizRule property sets or retrieves the text of the script that implements the business rule (BizRule).
This property is read/write.

Syntax
HRESULT put_BizRule(
BSTR bstrProp
);

Parameters
bstrProp

Return value
None

Remarks
The maximum length of this property is 65,536 characters.

Impor tant The BizRuleLanguage property must be set before this property is set.

An IAzTask object that is a child object of a delegated IAzScope object cannot have an associated BizRule.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
See also
BizRuleImportedPath
BizRuleLanguage
IAzTask
 IAzTask::put_BizRuleImportedPath method
(azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The BizRuleImpor tedPath property sets or retrieves the path to the file from which the business rule (BizRule)
is imported.
This property is read/write.

Syntax
HRESULT put_BizRuleImportedPath(
BSTR bstrProp
);

Parameters
bstrProp

Return value
None

Remarks
The path information is stored for use by the UI. The UI should supply a mechanism to synchronize the contents
of the file and this property.
The maximum length of this property is 512 characters.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
See also
BizRule
BizRuleLanguage
IAzTask
 IAzTask::put_BizRuleLanguage method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The BizRuleLanguage property sets or retrieves the scripting language in which the business rule (BizRule) is
implemented.
This property is read/write.

Syntax
HRESULT put_BizRuleLanguage(
BSTR bstrProp
);

Parameters
bstrProp

Return value
None

Remarks
This property must be set before the BizRule property is set.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP

See also
BizRule
BizRuleImportedPath
IAzTask
 IAzTask::put_Description method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The Description property sets or retrieves a comment that describes the task.
This property is read/write.

Syntax
HRESULT put_Description(
BSTR bstrDescription
);

Parameters
bstrDescription

Return value
None

Remarks
The maximum length of the Description property is 1,024 characters.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzTask::put_IsRoleDefinition method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The IsRoleDefinition property sets or retrieves a value that indicates whether the task is a role definition.
This property is read/write.

Syntax
HRESULT put_IsRoleDefinition(
BOOL fProp
);

Parameters
fProp

Return value
None

Remarks
This property represents a user interface abstraction and does not affect the functionality of the task.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzTask::put_Name method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The Name property sets or retrieves the name of the task.

This property is read/write.

Syntax
HRESULT put_Name(
BSTR bstrName
);

Parameters
bstrName

Return value
None

Remarks
The maximum length of the Name property is 64 characters.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzTask::SetProperty method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The SetProper ty method sets the specified value to the IAzTask object property with the specified property ID.

Syntax
HRESULT SetProperty(
[in] LONG lPropId,
[in] VARIANT varProp,
[in, optional] VARIANT varReserved
);

Parameters
[in] lPropId

Property ID of the IAzTask object property to set. The following table shows the possible values.

VA L UE M EA N IN G

Also accessed through the ApplicationData property

AZ_PROP_APPLICATION_DATA

Also accessed through the Description property

AZ_PROP_DESCRIPTION

Also accessed through the Name property

AZ_PROP_NAME

Also accessed through the BizRule property

AZ_PROP_TASK_BIZRULE

Also accessed through the BizRuleLanguage property

AZ_PROP_TASK_BIZRULE_L ANGUAGE

Also accessed through the IsRoleDefinition property

AZ_PROP_TASK_IS_ROLE_DEFINITION

[in] varProp

Value to set to the IAzTask object property specified by the lPropId parameter. The following table shows the
type of data that must be used depending on the value of the lPropId parameter.

L P RO P ID VA L UE DATA T Y P E

BSTR
AZ_PROP_APPLICATION_DATA
 BSTR
AZ_PROP_DESCRIPTION

BSTR
AZ_PROP_NAME

BSTR
AZ_PROP_TASK_BIZRULE

BSTR
AZ_PROP_TASK_BIZRULE_L ANGUAGE

BOOL
AZ_PROP_IS_ROLE_DEFINITION

[in, optional] varReserved

Reserved for future use.

Return value
The return value is an HRESULT . A value of S_OK indicates success. Any other value indicates that the operation
failed.

Remarks
You must call the Submit method to persist any changes made by this method.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzTask::Submit method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The Submit method persists changes made to the IAzTask object.

Syntax
HRESULT Submit(
[in, optional] LONG lFlags,
[in, optional] VARIANT varReserved
);

Parameters
[in, optional] lFlags

Flags that modify the behavior of the Submit method. The default value is zero. If the AZ_SUBMIT_FLAG_ABORT
flag is specified, the changes to the object are discarded and the object is updated to match the underlying
policy store.
[in, optional] varReserved

Reserved for future use.

Return value
None

Remarks
Any additions or modifications to an IAzTask object are not persisted until the Submit method is called.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzTask2 interface (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The IAzTask2 interface extends the IAzTask interface with a method that returns the role assignments associated
with the task.

Inheritance
The IAzTask2 interface inherits from the IAzTask interface.

Methods
The IAzTask2 interface has these methods.

IAzTask2::RoleAssignments

Returns a collection of the role assignments associated with this task.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header azroles.h
 IAzTask2::RoleAssignments method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The RoleAssignments method returns a collection of the role assignments associated with this task.

Syntax
HRESULT RoleAssignments(
[in] BSTR bstrScopeName,
[in] VARIANT_BOOL bRecursive,
[out] IAzRoleAssignments **ppRoleAssignments
);

Parameters
[in] bstrScopeName

The name of the scope in which to check for role assignments. If the value of this parameter is an empty string,
the method checks for role assignments at the application level.
[in] bRecursive

TRUE if the method checks all scopes within the application; otherwise, FALSE . This parameter is ignored if the
value of the bstrScopeName parameter is not NULL .
[out] ppRoleAssignments

The address of a pointer to an IAzRoleAssignments interface that represents the collection of IAzRoleAssignment
objects associated with this task.

Return value
If the method succeeds, it returns S_OK .
If the method fails, it returns an error code. For a list of common error codes, see Common HRESULT Values.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header azroles.h
 IAzTasks interface (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The IAzTasks interface represents a collection of

IAzTask objects.

Inheritance
The IAzTasks interface inherits from the IDispatch interface. IAzTasks also has these types of members:

Methods
The IAzTasks interface has these methods.

IAzTasks::get__NewEnum

The _NewEnum property of IAzTasks retrieves an IEnumVARIANT interface on an object that can be used to enumerate the
collection. This property is hidden within Visual Basic and Visual Basic Scripting Edition (VBScript).

IAzTasks::get_Count

Retrieves the number of IAzTask objects in the collection.

IAzTasks::get_Item

Retrieves the IAzTask object at the specified index into the IAzTasks collection.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzTasks::get__NewEnum method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The _NewEnum property retrieves an IEnumVARIANT interface on an object that can be used to enumerate the
collection. This property is hidden within Visual Basic and Visual Basic Scripting Edition (VBScript).
This property is read-only.

Syntax
HRESULT get__NewEnum(
LPUNKNOWN *ppEnumPtr
);

Parameters
ppEnumPtr

Return value
None

Remarks
This property is provided for use by the For Each keyword in Visual Basic and the foreach keyword in Visual
C#.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzTasks::get_Count method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The Count property retrieves the number of IAzTask objects in the collection.
This property is read-only.

Syntax
HRESULT get_Count(
LONG *plCount
);

Parameters
plCount

Return value
None

Remarks
The Count property can be used to specify the last IAzTask object in a collection when retrieving a specific
IAzTask object using the IAzTasks.Item property.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 IAzTasks::get_Item method (azroles.h)
7/2/2022 • 2 minutes to read • Edit Online

The Item property retrieves the IAzTask object at the specified index into the IAzTasks collection.
This property is read-only.

Syntax
HRESULT get_Item(
LONG Index,
VARIANT *pvarObtPtr
);

Parameters
Index

pvarObtPtr

Return value
None

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header azroles.h

Librar y Azroles.lib

DLL Azroles.dll

Redistributable Windows Server 2003 Administration Tools Pack on

Windows XP
 bcrypt.h header
7/2/2022 • 5 minutes to read • Edit Online

This header is used by Security and Identity. For more information, see:
Security and Identity
bcrypt.h contains the following programming interfaces:

Functions

BCRYPT_INIT_AUTH_MODE_INFO

Initializes a BCRYPT_AUTHENTICATED_CIPHER_MODE_INFO structure for use in calls to BCryptEncrypt and BCryptDecrypt

functions.

BCryptAddContextFunction

Adds a cryptographic function to the list of functions that are supported by an existing CNG context.

BCryptCloseAlgorithmProvider

Closes an algorithm provider.

BCryptConfigureContext

Sets the configuration information for an existing CNG context.

BCryptConfigureContextFunction

Sets the configuration information for the cryptographic function of an existing CNG context.

BCryptCreateContext

Creates a new CNG configuration context.

BCryptCreateHash

Called to create a hash or Message Authentication Code (MAC) object.

BCryptCreateMultiHash

The BCryptCreateMultiHash function creates a multi-hash state that allows for the parallel computation of multiple hash
operations.

BCryptDecrypt

Decrypts a block of data.

BCryptDeleteContext

Deletes an existing CNG configuration context.

BCryptDeriveKey

Derives a key from a secret agreement value.

BCryptDeriveKeyCapi

Derives a key from a hash value.

BCryptDeriveKeyPBKDF2

Derives a key from a hash value by using the PBKDF2 key derivation algorithm as defined by RFC 2898.

BCryptDestroyHash

Destroys a hash or Message Authentication Code (MAC) object.

BCryptDestroyKey

Destroys a key.

BCryptDestroySecret

Destroys a secret agreement handle that was created by using the BCryptSecretAgreement function.

BCryptDuplicateHash

Duplicates an existing hash or Message Authentication Code (MAC) object.

BCryptDuplicateKey

Creates a duplicate of a symmetric key.

BCryptEncrypt

Encrypts a block of data.

BCryptEnumAlgorithms

Gets a list of the registered algorithm identifiers.

BCryptEnumContextFunctionProviders

Obtains the providers for the cryptographic functions for a context in the specified configuration table.

BCryptEnumContextFunctions

Obtains the cryptographic functions for a context in the specified configuration table.

BCryptEnumContexts

Obtains the identifiers of the contexts in the specified configuration table.

BCryptEnumProviders

Obtains all of the CNG providers that support a specified algorithm.

BCryptEnumRegisteredProviders

Retrieves information about the registered providers.

BCryptExportKey

Exports a key to a memory BLOB that can be persisted for later use.

BCryptFinalizeKeyPair

Completes a public/private key pair.

BCryptFinishHash

Retrieves the hash or Message Authentication Code (MAC) value for the data accumulated from prior calls to
BCryptHashData.

BCryptFreeBuffer

Used to free memory that was allocated by one of the CNG functions.

BCryptGenerateKeyPair

Creates an empty public/private key pair.

BCryptGenerateSymmetricKey

Creates a key object for use with a symmetrical key encryption algorithm from a supplied key.

BCryptGenRandom

Generates a random number.

BCryptGetFipsAlgorithmMode

Determines whether Federal Information Processing Standard (FIPS) compliance is enabled.

BCryptGetProperty

Retrieves the value of a named property for a CNG object.

BCryptHash

Performs a single hash computation. This is a convenience function that wraps calls to BCryptCreateHash, BCryptHashData,
BCryptFinishHash, and BCryptDestroyHash.

BCryptHashData

Performs a one way hash or Message Authentication Code (MAC) on a data buffer.
BCryptImportKey

Imports a symmetric key from a key BLOB.

BCryptImportKeyPair

Imports a public/private key pair from a key BLOB.

BCryptKeyDerivation

Derives a key without requiring a secret agreement.

BCryptOpenAlgorithmProvider

Loads and initializes a CNG provider.

BCryptProcessMultiOperations

The BCryptProcessMultiOperations function processes a sequence of operations on a multi-object state.

BCryptQueryContextConfiguration

Retrieves the current configuration for the specified CNG context.

BCryptQueryContextFunctionConfiguration

Obtains the cryptographic function configuration information for an existing CNG context.

BCryptQueryContextFunctionProperty

Obtains the value of a named property for a cryptographic function in an existing CNG context.

BCryptQueryProviderRegistration

Retrieves information about a CNG provider.

BCryptRegisterConfigChangeNotify

Creates a user mode CNG configuration change event handler.

BCryptRegisterConfigChangeNotify

BCryptRemoveContextFunction

Removes a cryptographic function from the list of functions that are supported by an existing CNG context.

BCryptResolveProviders

Obtains a collection of all of the providers that meet the specified criteria.

BCryptSecretAgreement

Creates a secret agreement value from a private and a public key.

 BCryptSetContextFunctionProperty

Sets the value of a named property for a cryptographic function in an existing CNG context.

BCryptSetProperty

Sets the value of a named property for a CNG object.

BCryptSignHash

Creates a signature of a hash value.

BCryptUnregisterConfigChangeNotify

Removes a user mode CNG configuration change event handler that was created by using the
BCryptRegisterConfigChangeNotify(HANDLE*) function.

BCryptVerifySignature

Verifies that the specified signature matches the specified hash.

Structures

BCRYPT_ALGORITHM_IDENTIFIER

Is used with the BCryptEnumAlgorithms function to contain a cryptographic algorithm identifier.

BCRYPT_AUTHENTICATED_CIPHER_MODE_INFO

Used with the BCryptEncrypt and BCryptDecrypt functions to contain additional information related to authenticated cipher
modes.

BCRYPT_DH_KEY_BLOB

Used as a header for a Diffie-Hellman public key or private key BLOB in memory.

BCRYPT_DH_PARAMETER_HEADER

Used to contain parameter header information for a Diffie-Hellman key.

BCRYPT_DSA_KEY_BLOB

Used as a header for a Digital Signature Algorithm (DSA) public key or private key BLOB in memory.

BCRYPT_DSA_KEY_BLOB_V2

Used as a header for a Digital Signature Algorithm (DSA) public key or private key BLOB in memory.

BCRYPT_DSA_PARAMETER_HEADER

Used to contain parameter header information for a Digital Signature Algorithm (DSA) key.
BCRYPT_DSA_PARAMETER_HEADER_V2

Contains parameter header information for a Digital Signature Algorithm (DSA) key.

BCRYPT_ECCKEY_BLOB

Used as a header for an elliptic curve public key or private key BLOB in memory.

BCRYPT_INTERFACE_VERSION

Contains version information for a programmatic interface for a CNG provider.

BCRYPT_KEY_BLOB

Is the base structure for all CNG key BLOBs.

BCRYPT_KEY_DATA_BLOB_HEADER

Used to contain information about a key data BLOB.

BCRYPT_KEY_LENGTHS_STRUCT

Defines the range of key sizes that are supported by the provider.

BCRYPT_MULTI_HASH_OPERATION

A BCRYPT_MULTI_HASH_OPERATION structure defines a single operation in a multi-hash operation.

BCRYPT_MULTI_OBJECT_LENGTH_STRUCT

The BCRYPT_MULTI_OBJECT_LENGTH_STRUCT structure contains information to determine the size of the pbHashObject
buffer for the BCryptCreateMultiHash function.

BCRYPT_OAEP_PADDING_INFO

Used to provide options for the Optimal Asymmetric Encryption Padding (OAEP) scheme.

BCRYPT_OID

Contains information about a DER-encoded object identifier (OID).

BCRYPT_OID_LIST

Used to contain a collection of BCRYPT_OID structures. Use this structure with the BCRYPT_HASH_OID_LIST property to
retrieve the list of hashing object identifiers (OIDs) that have been encoded by using Distinguished Encoding Rules (DER)
encoding.

BCRYPT_PKCS1_PADDING_INFO

Used to provide options for the PKCS

BCRYPT_PROVIDER_NAME

Contains the name of a CNG provider.

BCRYPT_PSS_PADDING_INFO

Used to provide options for the Probabilistic Signature Scheme (PSS) padding scheme.

BCRYPT_RSAKEY_BLOB

Used as a header for an RSA public key or private key BLOB in memory.

BCryptBuffer

BCryptBufferDesc

CRYPT_CONTEXT_CONFIG

Contains configuration information for a CNG context.

CRYPT_CONTEXT_FUNCTION_CONFIG

Contains configuration information for a cryptographic function of a CNG context.

CRYPT_CONTEXT_FUNCTION_PROVIDERS

Contains a set of cryptographic function providers for a CNG configuration context.

CRYPT_CONTEXT_FUNCTIONS

Contains a set of cryptographic functions for a CNG configuration context.

CRYPT_CONTEXTS

Contains a set of CNG configuration context identifiers.

CRYPT_IMAGE_REF

Contains information about a CNG provider module.

CRYPT_IMAGE_REG

Contains image registration information about a CNG provider.

CRYPT_INTERFACE_REG

Used to contain information about the type of interface supported by a CNG provider.

CRYPT_PROPERTY_REF

Contains information about a CNG context property.

CRYPT_PROVIDER_REF

Contains information about a cryptographic interface that a provider supports.

 CRYPT_PROVIDER_REFS

Contains a collection of provider references.

CRYPT_PROVIDER_REG

Used to contain registration information for a CNG provider.

CRYPT_PROVIDERS

Contains information about the registered CNG providers.

Enumerations

BCRYPT_HASH_OPERATION_TYPE

The BCRYPT_HASH_OPERATION_TYPE enumeration specifies the hash operation type.

BCRYPT_MULTI_OPERATION_TYPE

The BCRYPT_MULTI_OPERATION_TYPE enumeration specifies type of multi-operation that is passed to the

BCryptProcessMultiOperations function.

DSAFIPSVERSION_ENUM

Contains FIPS version information.

HASHALGORITHM_ENUM

Specifies signing and hashing algorithms.

 BCRYPT_ALGORITHM_IDENTIFIER structure
(bcrypt.h)
7/2/2022 • 2 minutes to read • Edit Online

The BCRYPT_ALGORITHM_IDENTIFIER structure is used with the BCryptEnumAlgorithms function to contain

a cryptographic algorithm identifier.

Syntax
typedef struct _BCRYPT_ALGORITHM_IDENTIFIER {
LPWSTR pszName;
ULONG dwClass;
ULONG dwFlags;
} BCRYPT_ALGORITHM_IDENTIFIER;

Members
pszName

A pointer to a null-terminated Unicode string that contains the string identifier of the algorithm. The CNG
Algorithm Identifiers topic contains the predefined algorithm identifiers.
dwClass

Specifies the class of the algorithm. This can be one of the CNG Interface Identifiers.
dwFlags

A set of flags that specify other information about the algorithm. There are currently no flags defined for this
member.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Header bcrypt.h

See also
BCryptEnumAlgorithms
 BCRYPT_AUTHENTICATED_CIPHER_MODE_INFO
structure (bcrypt.h)
7/2/2022 • 4 minutes to read • Edit Online

The BCRYPT_AUTHENTICATED_CIPHER_MODE_INFO structure is used with the BCryptEncrypt and

BCryptDecrypt functions to contain additional information related to authenticated cipher modes.

Syntax
typedef struct _BCRYPT_AUTHENTICATED_CIPHER_MODE_INFO {
ULONG cbSize;
ULONG dwInfoVersion;
PUCHAR pbNonce;
ULONG cbNonce;
PUCHAR pbAuthData;
ULONG cbAuthData;
PUCHAR pbTag;
ULONG cbTag;
PUCHAR pbMacContext;
ULONG cbMacContext;
ULONG cbAAD;
ULONGLONG cbData;
ULONG dwFlags;
} BCRYPT_AUTHENTICATED_CIPHER_MODE_INFO, *PBCRYPT_AUTHENTICATED_CIPHER_MODE_INFO;

Members
cbSize

The size, in bytes, of this structure. Do not set this field directly. Use the BCRYPT_INIT_AUTH_MODE_INFO macro
instead.
dwInfoVersion

The version number of the structure. The only supported value is

BCRYPT_AUTHENTICATED_CIPHER_MODE_INFO_VERSION . Do not set this field directly. Use the
BCRYPT_INIT_AUTH_MODE_INFO macro instead.
pbNonce

A pointer to a buffer that contains a nonce. The Microsoft algorithm providers for Advanced Encryption
Standard (AES) require a nonce for the Counter with CBC-MAC (CCM) and Galois/Counter Mode (GCM) chaining
modes, and will return an error if none is present. If a nonce is not used, this member must be set to NULL .
cbNonce

The size, in bytes, of the buffer pointed to by the pbNonce member. If a nonce is not used, this member must be
set to zero.
pbAuthData

A pointer to a buffer that contains the authenticated data. This is data that will be included in the Message
Authentication Code (MAC) but not encrypted. If there is no authenticated data, this member must be set to
NULL .
cbAuthData

The size, in bytes, of the buffer pointed to by the pbAuthData member. If there is no authenticated data, this
member must be set to zero.
pbTag

A pointer to a buffer.
The use of this member depends on the function to which the structure is passed.

F UN C T IO N DESC RIP T IO N

The buffer will receive the authentication tag.

BCr yptEncr ypt

The buffer contains the authentication tag to be checked

BCr yptDecr ypt against.

If there is no tag, this member must be set to NULL .

cbTag

The size, in bytes, of the pbTag buffer. The buffer must be long enough to include the whole authentication tag.
Some authentication modes, such as CCM and GCM, support checking against a tag with multiple lengths. To
obtain the valid authentication tag lengths use BCryptGetProperty to query the BCRYPT_AUTH_TAG_LENGTH
property. If there is no tag, this member must be set to zero.
pbMacContext

A pointer to a buffer that stores the partially computed MAC between calls to BCryptEncrypt and BCryptDecrypt
when chaining encryption or decryption.
If the input to encryption or decryption is scattered across multiple buffers, then you must chain calls to the
BCryptEncrypt and BCryptDecrypt functions. Chaining is indicated by setting the
BCRYPT_AUTH_MODE_IN_PROGRESS_FL AG flag in the dwFlags member.
This buffer must be supplied by the caller and must be at least as large as the maximum length of an
authentication tag for the cipher you are using. To get the valid authentication tag lengths, use
BCryptGetProperty to query the BCRYPT_AUTH_TAG_LENGTH property.
If BCryptEncrypt and BCryptDecrypt calls are not being chained, this member must be set to NULL .
cbMacContext

The size, in bytes, of the buffer pointed to by the pbMacContext member. If BCryptEncrypt and BCryptDecrypt
calls are not being chained, this member must be set to zero.
cbAAD

The length, in bytes, of additional authenticated data (AAD) to be used by the BCryptEncrypt and BCryptDecrypt
functions. This member is used only when chaining calls.
This member is used only when the BCRYPT_AUTH_MODE_IN_PROGRESS_FL AG flag in the dwFlags
member is set.
On the first call to BCryptEncrypt or BCryptDecrypt you must set this field to zero.
 Note During the chaining sequence, this member is maintained internally and must not be changed or the value of the
computed MAC will be corrupted.

cbData

The length, in bytes, of the payload data that was encrypted or decrypted. This member is used only when
chaining calls.
This member is used only when the BCRYPT_AUTH_MODE_IN_PROGRESS_FL AG flag in the dwFlags
member is set.
On the first call to BCryptEncrypt or BCryptDecrypt you must set this field to zero, , either directly or by calling
the BCRYPT_INIT_AUTH_INFO macro

Note During the chaining sequence, this member is maintained internally and must not be changed or the value of the
computed MAC will be corrupted.

dwFlags

This flag is used when chaining BCryptEncrypt or BCryptDecrypt function calls. If calls are not being chained,
this member must be set to zero.

VA L UE M EA N IN G

For BCryptEncrypt, calculate the authentication tag and

0x00000000 place it in the buffer pointed to by the pbTag member.
For BCryptDecrypt, calculate the authentication tag and
compare it against the tag passed in to the buffer
pointed to by the pbTag member. When chaining
multiple calls to BCryptEncrypt or BCr yptDecr ypt , this
value signals the end of the chain.

Indicates that BCryptEncrypt and BCryptDecrypt function

BCRYPT_AUTH_MODE_CHAIN_CALLS_FL AG calls are being chained and that the MAC value will not be
0x00000001 computed. On the last call in the chain, clear this value to
compute the MAC value for the entire chain.

Indicates that this

BCRYPT_AUTH_MODE_IN_PROGRESS_FL AG BCRYPT_AUTHENTICATED_CIPHER_MODE_INFO
0x00000002 structure is being used in a sequence of chained
BCryptEncrypt or BCryptDecrypt function calls. This flag is
set and maintained internally.

Note During the chaining sequence, this flag value is

maintained internally and must not be changed or the
value of the computed MAC will be corrupted.

Remarks
The size of this structure is different between 64-bit and 32-bit operating systems. On 64-bit operating systems,
the size is different between 64-bit and 32-bit processes. Instances of this structure must not be shared across
threads or passed between processes.

Requirements

Minimum suppor ted client Windows Vista with SP1 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Header bcrypt.h
 BCRYPT_DH_KEY_BLOB structure (bcrypt.h)
7/2/2022 • 2 minutes to read • Edit Online

The BCRYPT_DH_KEY_BLOB structure is used as a header for a Diffie-Hellman public key or private key BLOB
in memory.

Syntax
typedef struct _BCRYPT_DH_KEY_BLOB {
ULONG dwMagic;
ULONG cbKey;
} BCRYPT_DH_KEY_BLOB, *PBCRYPT_DH_KEY_BLOB;

Members
dwMagic

Determines the type of key this structure represents. This can be one of the following values.

VA L UE M EA N IN G

The structure represents a Diffie-Hellman public key.

BCRYPT_DH_PUBLIC_MAGIC
0x42504844

The structure represents a Diffie-Hellman private key.

BCRYPT_DH_PRIVATE_MAGIC
0x56504844

cbKey

The length, in bytes, of the key.

Remarks
This structure is used as a header for a larger buffer. A Diffie-Hellman public key BLOB
(BCRYPT_DH_PUBLIC_BLOB) has the following format in contiguous memory. The Modulus, Generator, and
Public numbers are in big-endian format.

BCRYPT_DH_KEY_BLOB
Modulus[cbKey] // Big-endian.
Generator[cbKey] // Big-endian.
Public[cbKey] // Big-endian.

A Diffie-Hellman private key BLOB (BCRYPT_DH_PRIVATE_BLOB) has the following format in contiguous
memory. The Modulus, Generator, Public, and PrivateExponent numbers are in big-endian format.
 BCRYPT_DH_KEY_BLOB
Modulus[cbKey] // Big-endian.
Generator[cbKey] // Big-endian.
Public[cbKey] // Big-endian.
PrivateExponent[cbKey] // Big-endian.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Header bcrypt.h

See also
BCryptExportKey
BCryptImportKey
 BCRYPT_DH_PARAMETER_HEADER structure
(bcrypt.h)
7/2/2022 • 2 minutes to read • Edit Online

The BCRYPT_DH_PARAMETER_HEADER structure is used to contain parameter header information for a

Diffie-Hellman key. This structure is used with the BCRYPT_DH_PARAMETERS property in the BCryptSetProperty
function.

Syntax
typedef struct _BCRYPT_DH_PARAMETER_HEADER {
ULONG cbLength;
ULONG dwMagic;
ULONG cbKeyLength;
} BCRYPT_DH_PARAMETER_HEADER;

Members
cbLength

The total size, in bytes, of this structure and the buffer that immediately follows this structure in memory.
dwMagic

The magic value for the key.

This member must be the following value.
BCRYPT_DH_PARAMETERS_MAGIC (0x4d504844)
cbKeyLength

The size, in bytes, of the key that this structure applies to.

Remarks
This structure is used as a header for a larger buffer. The single memory block consists of this structure followed
by a buffer of cbKeyLength size that contains the Diffie-Hellman prime number, and another buffer of
cbKeyLength size that contains the Diffie-Hellman generator number. Both of these numbers are in big-endian
format.
The following example shows how to calculate the sizes needed for this buffer and how to fill in the members of
this structure.
 // In this example, the rgbModulus variable is a byte array that contains the modulus in big-endian byte
order.
// The rgbGenerator variable is a byte array that contains the generator in big-endian byte order.

ULONG cbDHParams = sizeof(BCRYPT_DH_PARAMETER_HEADER) + (cbKeySize * 2);

PBYTE pbDHParams = (PBYTE)malloc(cbDHParams);
if(!pbDHParams)
{
status = STATUS_NO_MEMORY;
goto Cleanup;
}

BCRYPT_DH_PARAMETER_HEADER *pDHParamHeader;
pDHParamHeader = (BCRYPT_DH_PARAMETER_HEADER*)pbDHParams;
pDHParamHeader->cbLength = cbDHParams;
pDHParamHeader->cbKeyLength = cbKeySize;
pDHParamHeader->dwMagic = BCRYPT_DH_PARAMETERS_MAGIC;

// Add the modulus to the parameters.

// The rgbModulus argument is a byte array that contains the modulus.
PBYTE pbTemp = (PBYTE)pbDHParams + sizeof(BCRYPT_DH_PARAMETER_HEADER);
CopyMemory(pbTemp, rgbModulus, pDHParamHeader->cbKeyLength);

// Add the generator to the parameters.

// The rgbGenerator argument is a byte array that contains the generator.
pbTemp += pDHParamHeader->cbKeyLength;
CopyMemory(pbTemp, rgbGenerator, pDHParamHeader->cbKeyLength);

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Header bcrypt.h

See also
BCryptSetProperty
Cryptography Primitive Property Identifiers
 BCRYPT_DSA_KEY_BLOB structure (bcrypt.h)
7/2/2022 • 2 minutes to read • Edit Online

The BCRYPT_DSA_KEY_BLOB structure is used as a header for a Digital Signature Algorithm (DSA) public key
or private key BLOB in memory.

Syntax
typedef struct _BCRYPT_DSA_KEY_BLOB {
ULONG dwMagic;
ULONG cbKey;
UCHAR Count[4];
UCHAR Seed[20];
UCHAR q[20];
} BCRYPT_DSA_KEY_BLOB, *PBCRYPT_DSA_KEY_BLOB;

Members
dwMagic

Determines the type of key this structure represents. This can be one of the following values.

VA L UE M EA N IN G

The structure represents a DSA public key.

BCRYPT_DSA_PUBLIC_MAGIC
0x42505344

The structure represents a DSA private key.

BCRYPT_DSA_PRIVATE_MAGIC
0x56505344

cbKey

The length, in bytes, of the key.

Count

The number of iterations, in big-endian format, used to generate q.

Seed

The seed value, in big-endian format, used to generate q.

q

The 160-bit prime factor, in big-endian format.

Remarks
The structure applies to DSA keys that equal or exceed 512 bits in length but are less than or equal to 1024 bits.
This structure is used as a header for a larger buffer. A DSA public key BLOB (BCRYPT_DSA_PUBLIC_BLOB) has
the following format in contiguous memory. The Modulus, Generator, and Public numbers are in big-endian
format.

BCRYPT_DSA_KEY_BLOB
Modulus[cbKey] // Big-endian.
Generator[cbKey] // Big-endian.
Public[cbKey] // Big-endian.

A DSA private key BLOB (BCRYPT_DSA_PRIVATE_BLOB) has the following format in contiguous memory. The
Modulus, Generator, Public, and PrivateExponent numbers are in big-endian format.

BCRYPT_DSA_KEY_BLOB
Modulus[cbKey] // Big-endian.
Generator[cbKey] // Big-endian.
Public[cbKey] // Big-endian.
PrivateExponent[20] // Big-endian.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Header bcrypt.h

See also
BCryptExportKey
BCryptImportKeyPair
 BCRYPT_DSA_KEY_BLOB_V2 structure (bcrypt.h)
7/2/2022 • 2 minutes to read • Edit Online

The BCRYPT_DSA_KEY_BLOB_V2 structure is used as a header for a Digital Signature Algorithm (DSA) public
key or private key BLOB in memory.

Syntax
typedef struct _BCRYPT_DSA_KEY_BLOB_V2 {
ULONG dwMagic;
ULONG cbKey;
HASHALGORITHM_ENUM hashAlgorithm;
DSAFIPSVERSION_ENUM standardVersion;
ULONG cbSeedLength;
ULONG cbGroupSize;
UCHAR Count[4];
} BCRYPT_DSA_KEY_BLOB_V2, *PBCRYPT_DSA_KEY_BLOB_V2;

Members
dwMagic

Determines the type of key this structure represents. This can be one of the following values.

VA L UE M EA N IN G

The structure represents a DSA public key.

BCRYPT_DSA_PUBLIC_MAGIC_V2
0x32425044

The structure represents a DSA private key.

BCRYPT_DSA_PRIVATE_MAGIC_V2
0x32565044

cbKey

The length, in bytes, of the key.

hashAlgorithm

A HASHALGORITHM_ENUM enumeration value that specifies the hashing algorithm to use.

standardVersion

A DSAFIPSVERSION_ENUM enumeration value that specifies the Federal Information Processing Standard (FIPS)
to apply.
cbSeedLength

Length of the seed used to generate the prime number q in bytes.

cbGroupSize

Size of the prime number q in bytes. Currently, when the key exceeds 1024 bits in length, q is 32 bytes long.
Count

The number of iterations performed to generate the prime number q from the seed. For more information, see
NIST standard FIPS186-3.

Remarks
The structure applies to DSA keys that exceed 1024 bits in length but are less than or equal to 3072 bits.
This structure is used as a header for a larger buffer. A DSA public key BLOB (BCRYPT_DSA_PUBLIC_BLOB) has
the following format in contiguous memory. The Seed, q, Modulus, Generator, and Public numbers are in big-
endian format.

BCRYPT_DSA_KEY_BLOB_V2
Seed[cbSeedLength] // Big-endian.
q[cbGroupSize] // Big-endian.
Modulus[cbKey] // Big-endian.
Generator[cbKey] // Big-endian.
Public[cbKey] // Big-endian.

A DSA private key BLOB (BCRYPT_DSA_PRIVATE_BLOB) has the following format in contiguous memory. The
Seed, q, Modulus, Generator, Public, and PrivateExponent numbers are in big-endian format.

BCRYPT_DSA_KEY_BLOB_V2
Seed[cbSeedLength] // Big-endian.
q[cbGroupSize] // Big-endian.
Modulus[cbKey] // Big-endian.
Generator[cbKey] // Big-endian.
Public[cbKey] // Big-endian.
PrivateExponent[cbGroupSize] // Big-endian.

Requirements

Minimum suppor ted client Windows 8 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2012 [desktop apps only]

Header bcrypt.h

See also
BCryptExportKey
BCryptImportKeyPair
 BCRYPT_DSA_PARAMETER_HEADER structure
(bcrypt.h)
7/2/2022 • 2 minutes to read • Edit Online

The BCRYPT_DSA_PARAMETER_HEADER structure is used as a header for a Digital Signature Algorithm

(DSA) parameters BLOB containing information for generating a DSA key. This structure is used with the
BCRYPT_DSA_PARAMETERS property in the BCryptSetProperty function.

Syntax
typedef struct _BCRYPT_DSA_PARAMETER_HEADER {
ULONG cbLength;
ULONG dwMagic;
ULONG cbKeyLength;
UCHAR Count[4];
UCHAR Seed[20];
UCHAR q[20];
} BCRYPT_DSA_PARAMETER_HEADER;

Members
cbLength

The total size, in bytes, of this structure and the buffer that immediately follows this structure in memory.
dwMagic

The magic value for the key.

This member must be the following value.
BCRYPT_DSA_PARAMETERS_MAGIC (0x4d505344)
cbKeyLength

The size, in bytes, of the key that this structure applies to.
Count

The number of iterations performed to generate the prime number q from the seed.
Seed

The seed value, in big-endian format, used to generate q.

q

The 160-bit prime factor, in big-endian format.

Remarks
When using this structure in a BCryptSetProperty call, to set the parameters for a DSA key created in a
BCryptGenerateKeyPair call, (cbKeyLength*8) must equal the previously set dwLength.
The structure applies to DSA keys that equal or exceed 512 bits in length but are less than or equal to 1024 bits.
This structure is used as a header for a larger buffer. The DSA parameters blob has the following format in
contiguous memory. The Modulus and Generator are in big-endian format.

BCRYPT_DSA_PARAMETER_HEADER
Modulus[cbKeyLength] // Big-endian.
Generator[cbKeyLength] // Big-endian.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Header bcrypt.h

See also
BCryptGenerateKeyPair
BCryptSetProperty
Cryptography Primitive Property Identifiers
 BCRYPT_DSA_PARAMETER_HEADER_V2 structure
(bcrypt.h)
7/2/2022 • 2 minutes to read • Edit Online

The BCRYPT_DSA_PARAMETER_HEADER_V2 structure is used as a header for a Digital Signature Algorithm

(DSA) parameters BLOB containing information for generating a DSA key. This structure is used with the
BCRYPT_DSA_PARAMETERS property in the BCryptSetProperty function.

Syntax
typedef struct _BCRYPT_DSA_PARAMETER_HEADER_V2 {
ULONG cbLength;
ULONG dwMagic;
ULONG cbKeyLength;
HASHALGORITHM_ENUM hashAlgorithm;
DSAFIPSVERSION_ENUM standardVersion;
ULONG cbSeedLength;
ULONG cbGroupSize;
UCHAR Count[4];
} BCRYPT_DSA_PARAMETER_HEADER_V2;

Members
cbLength

The total size, in bytes, of this structure and the buffer that immediately follows this structure in memory.
dwMagic

The magic value for the key.

This member must be the following value.
BCRYPT_DSA_PARAMETERS_MAGIC_V2 (0x324d5044)
cbKeyLength

The size, in bytes, of the key that this structure applies to.
hashAlgorithm

A HASHALGORITHM_ENUM enumeration value that specifies the hashing algorithm to use.

standardVersion

A DSAFIPSVERSION_ENUM enumeration value that specifies the Federal Information Processing Standard (FIPS)
to apply.
cbSeedLength

Length of the seed used to generate the prime number q in bytes.

cbGroupSize

Size of the prime number q. Currently, when the key exceeds 1024 bits in length, q is 32 bytes long.
Count

The number of iterations performed to generate the prime number q from the seed. For more information, see
NIST standard FIPS186-3.

Remarks
When using this structure in a BCryptSetProperty call, to set the parameters for a DSA key created in a
BCryptGenerateKeyPair call, (cbKeyLength*8) must equal the previously set dwLength.
The structure applies to DSA keys that exceed 1024 bits in length but are less than or equal to 3072 bits.
This structure is used as a header for a larger buffer. The DSA parameters blob has the following format in
contiguous memory. The Seed, q, Modulus, and Generator are in big-endian format.

BCRYPT_DSA_PARAMETER_HEADER_V2
Seed[cbSeedLength] // Big-endian.
q[cbGroupSize] // Big-endian.
Modulus[cbKeyLength] // Big-endian.
Generator[cbKeyLength] // Big-endian.

Requirements

Minimum suppor ted client Windows 8 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2012 [desktop apps only]

Header bcrypt.h

See also
BCryptGenerateKeyPair
BCryptSetProperty
Cryptography Primitive Property Identifiers
 BCRYPT_ECCKEY_BLOB structure (bcrypt.h)
7/2/2022 • 2 minutes to read • Edit Online

The BCRYPT_ECCKEY_BLOB structure is used as a header for an elliptic curve public key or private key BLOB in
memory.

Syntax
typedef struct _BCRYPT_ECCKEY_BLOB {
ULONG dwMagic;
ULONG cbKey;
} BCRYPT_ECCKEY_BLOB, *PBCRYPT_ECCKEY_BLOB;

Members
dwMagic

Specifies the type of key this BLOB represents. The possible values for this member depend on the type of BLOB
this structure represents. The following keys use the NIST 256-bit prime curve defined in FIPS 186-2.

VA L UE M EA N IN G

The key is a 256 bit elliptic curve Diffie-Hellman public key.

BCRYPT_ECDH_PUBLIC_P256_MAGIC

The key is a 256 bit elliptic curve Diffie-Hellman private key.

BCRYPT_ECDH_PRIVATE_P256_MAGIC

The key is a 384 bit elliptic curve Diffie-Hellman public key.

BCRYPT_ECDH_PUBLIC_P384_MAGIC

The key is a 384 bit elliptic curve Diffie-Hellman private key.

BCRYPT_ECDH_PRIVATE_P384_MAGIC

The key is a 521 bit elliptic curve Diffie-Hellman public key.

BCRYPT_ECDH_PUBLIC_P521_MAGIC

The key is a 521 bit elliptic curve Diffie-Hellman private key.

BCRYPT_ECDH_PRIVATE_P521_MAGIC

The key is a 256 bit elliptic curve DSA public key.

BCRYPT_ECDSA_PUBLIC_P256_MAGIC

The key is a 256 bit elliptic curve DSA private key.

BCRYPT_ECDSA_PRIVATE_P256_MAGIC

The key is a 384 bit elliptic curve DSA public key.

BCRYPT_ECDSA_PUBLIC_P384_MAGIC
 The key is a 384 bit elliptic curve DSA private key.
BCRYPT_ECDSA_PRIVATE_P384_MAGIC

The key is a 521 bit elliptic curve DSA public key.

BCRYPT_ECDSA_PUBLIC_P521_MAGIC

The key is a 521 bit elliptic curve DSA private key.

BCRYPT_ECDSA_PRIVATE_P521_MAGIC

cbKey

The length, in bytes, of the key.

Remarks
This structure is used as a header for a larger buffer. An elliptic curve public key BLOB
(BCRYPT_ECCPUBLIC_BLOB) has the following format in contiguous memory. The X and Y coordinates are
unsigned integers encoded in big-endian format.

BCRYPT_ECCKEY_BLOB
BYTE X[cbKey] // Big-endian.
BYTE Y[cbKey] // Big-endian.

An elliptic curve private key BLOB (BCRYPT_ECCPRIVATE_BLOB) has the following format in contiguous memory.
The X and Y coordinates and d value are unsigned integers encoded in big-endian format.

BCRYPT_ECCKEY_BLOB
BYTE X[cbKey] // Big-endian.
BYTE Y[cbKey] // Big-endian.
BYTE d[cbKey] // Big-endian.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Header bcrypt.h

See also
BCRYPT_KEY_BLOB
BCryptExportKey
BCryptImportKey
 BCRYPT_HASH_OPERATION_TYPE enumeration
(bcrypt.h)
7/2/2022 • 2 minutes to read • Edit Online

The BCRYPT_HASH_OPERATION_TYPE enumeration specifies the hash operation type.

Syntax
typedef enum {
BCRYPT_HASH_OPERATION_HASH_DATA = 1,
BCRYPT_HASH_OPERATION_FINISH_HASH = 2
} BCRYPT_HASH_OPERATION_TYPE;

Constants

BCRYPT_HASH_OPERATION_HASH_DATA
Value: 1
Equivalent to calling the BCryptHashData function.

BCRYPT_HASH_OPERATION_FINISH_HASH
Value: 2
Equivalent to calling the BCryptFinishHash function.

Requirements

Header bcrypt.h

See also
BCryptFinishHash
BCryptHashData
 BCRYPT_INIT_AUTH_MODE_INFO macro (bcrypt.h)
7/2/2022 • 2 minutes to read • Edit Online

The BCRYPT_INIT_AUTH_MODE_INFO macro initializes a BCRYPT_AUTHENTICATED_CIPHER_MODE_INFO

structure for use in calls to BCryptEncrypt and BCryptDecrypt functions.

Syntax
void BCRYPT_INIT_AUTH_MODE_INFO(
_AUTH_INFO_STRUCT_
);

Parameters
_AUTH_INFO_STRUCT_

The BCRYPT_AUTHENTICATED_CIPHER_MODE_INFO structure to initialize.

Return value
None

Requirements

Minimum suppor ted client Windows Vista with SP1 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header bcrypt.h
 BCRYPT_INTERFACE_VERSION structure (bcrypt.h)
7/2/2022 • 2 minutes to read • Edit Online

The BCRYPT_INTERFACE_VERSION structure contains version information for a programmatic interface for a
CNG provider.

Syntax
typedef struct _BCRYPT_INTERFACE_VERSION {
USHORT MajorVersion;
USHORT MinorVersion;
} BCRYPT_INTERFACE_VERSION, *PBCRYPT_INTERFACE_VERSION;

Members
MajorVersion

The major version of the programmatic interface.

MinorVersion

The minor version of the programmatic interface.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Header bcrypt.h
 BCRYPT_KEY_BLOB structure (bcrypt.h)
7/2/2022 • 2 minutes to read • Edit Online

The BCRYPT_KEY_BLOB structure is the base structure for all CNG key BLOBs. All CNG key BLOBs are based on
this structure. For example, the BCRYPT_RSAKEY_BLOB structure is based on this structure.

Syntax
typedef struct _BCRYPT_KEY_BLOB {
ULONG Magic;
} BCRYPT_KEY_BLOB;

Members
Magic

Specifies the type of key this BLOB represents. The possible values for this member depend on the type of BLOB
this structure represents.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Header bcrypt.h

See also
BCRYPT_ECCKEY_BLOB
BCRYPT_RSAKEY_BLOB
 BCRYPT_KEY_DATA_BLOB_HEADER structure
(bcrypt.h)
7/2/2022 • 2 minutes to read • Edit Online

The BCRYPT_KEY_DATA_BLOB_HEADER structure is used to contain information about a key data BLOB. The
key data BLOB must immediately follow this structure in memory.

Syntax
typedef struct _BCRYPT_KEY_DATA_BLOB_HEADER {
ULONG dwMagic;
ULONG dwVersion;
ULONG cbKeyData;
} BCRYPT_KEY_DATA_BLOB_HEADER, *PBCRYPT_KEY_DATA_BLOB_HEADER;

Members
dwMagic

The magic value for the key.

This member must be the following value.
BCRYPT_KEY_DATA_BLOB_MAGIC (0x4d42444b)
dwVersion

Contains the numeric version of the key.

VA L UE M EA N IN G

Version 1.
BCRYPT_KEY_DATA_BLOB_VERSION1
1

cbKeyData

The size, in bytes, of the key data.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Header bcrypt.h

See also
BCryptExportKey
BCryptImportKey
 BCRYPT_KEY_LENGTHS_STRUCT structure
(bcrypt.h)
7/2/2022 • 2 minutes to read • Edit Online

The BCRYPT_KEY_LENGTHS_STRUCT structure defines the range of key sizes that are supported by the
provider. This structure is used with the BCRYPT_KEY_LENGTHS property.
This structure is also used with the BCRYPT_AUTH_TAG_LENGTH property to contain the minimum,
maximum, and increment size of an authentication tag.

Syntax
typedef struct __BCRYPT_KEY_LENGTHS_STRUCT {
ULONG dwMinLength;
ULONG dwMaxLength;
ULONG dwIncrement;
} BCRYPT_KEY_LENGTHS_STRUCT;

Members
dwMinLength

The minimum length, in bits, of a key.

dwMaxLength

The maximum length, in bits, of a key.

dwIncrement

The number of bits that the key size can be incremented between dwMinLength and dwMaxLength .

Remarks
The key sizes are given in a range that is inclusive of the minimum and maximum values and are separated by
the increment. For example, if the minimum key size is 8 bits, the maximum key size is 16 bits, and the
increment is 2 bits, the provider would support key sizes of 8, 10, 12, 14, and 16 bits.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Header bcrypt.h
 BCRYPT_MULTI_HASH_OPERATION structure
(bcrypt.h)
7/2/2022 • 2 minutes to read • Edit Online

A BCRYPT_MULTI_HASH_OPERATION structure defines a single operation in a multi-hash operation.

Syntax
typedef struct _BCRYPT_MULTI_HASH_OPERATION {
ULONG iHash;
BCRYPT_HASH_OPERATION_TYPE hashOperation;
PUCHAR pbBuffer;
ULONG cbBuffer;
} BCRYPT_MULTI_HASH_OPERATION;

Members
iHash

An index into the multi-object state array of the hash state on which this computation operates. The first element
of the array corresponds to an iHash value of zero (0). Valid values are less than the value of the nHashes
parameter of the BCryptCreateMultiHash function.
hashOperation

A hash operation type, either BCRYPT_HASH_OPERATION_HASH_DATA or

BCRYPT_HASH_OPERATION_FINISH_HASH .
If the value is BCRYPT_HASH_OPERATION_HASH_DATA , the operation performed is equivalent to calling the
BCryptHashData function on the hash object array element with pbBuffer/cbBuffer pointing to the buffer to be
hashed.
If the value is BCRYPT_HASH_OPERATION_FINISH_HASH , the operation performed is equivalent to calling
the BCryptFinishHash function on the hash object array element with pbBuffer/cbBuffer pointing to the output
buffer that receives the result.
pbBuffer

The buffer on which the operation works.

cbBuffer

The buffer on which the operation works.

Requirements

Minimum suppor ted client Windows 8.1 Update [desktop apps | UWP apps]

Minimum suppor ted ser ver Windows Server 2008 Update [desktop apps | UWP apps]
 Header bcrypt.h

See also
BCryptCreateMultiHash
BCryptFinishHash
BCryptHashData
 BCRYPT_MULTI_OBJECT_LENGTH_STRUCT
structure (bcrypt.h)
7/2/2022 • 2 minutes to read • Edit Online

The BCRYPT_MULTI_OBJECT_LENGTH_STRUCT structure contains information to determine the size of the

pbHashObject buffer for the BCryptCreateMultiHash function.

Syntax
typedef struct _BCRYPT_MULTI_OBJECT_LENGTH_STRUCT {
ULONG cbPerObject;
ULONG cbPerElement;
} BCRYPT_MULTI_OBJECT_LENGTH_STRUCT;

Members
cbPerObject

The number of bytes needed for the object overhead.

cbPerElement

The number of bytes needed for each element of the object.

Remarks
The size of the pbHashObject buffer for the BCryptCreateMultiHash function is the following:
cbPerObject + (number of hash states) * cbPerElement .

Requirements

Minimum suppor ted client Windows 8.1 Update [desktop apps | UWP apps]

Minimum suppor ted ser ver Windows Server 2008 Update [desktop apps | UWP apps]

Header bcrypt.h

See also
BCryptCreateMultiHash
 BCRYPT_MULTI_OPERATION_TYPE enumeration
(bcrypt.h)
7/2/2022 • 2 minutes to read • Edit Online

The BCRYPT_MULTI_OPERATION_TYPE enumeration specifies type of multi-operation that is passed to the

BCryptProcessMultiOperations function.

Syntax
typedef enum {
BCRYPT_OPERATION_TYPE_HASH = 1
} BCRYPT_MULTI_OPERATION_TYPE;

Constants

BCRYPT_OPERATION_TYPE_HASH
Value: 1
A hash operation.

Requirements

Header bcrypt.h

See also
BCryptProcessMultiOperations
 BCRYPT_OAEP_PADDING_INFO structure (bcrypt.h)
7/2/2022 • 2 minutes to read • Edit Online

The BCRYPT_OAEP_PADDING_INFO structure is used to provide options for the Optimal Asymmetric
Encryption Padding (OAEP) scheme.

Syntax
typedef struct _BCRYPT_OAEP_PADDING_INFO {
LPCWSTR pszAlgId;
PUCHAR pbLabel;
ULONG cbLabel;
} BCRYPT_OAEP_PADDING_INFO;

Members
pszAlgId

A pointer to a null-terminated Unicode string that identifies the cryptographic algorithm to use to create the
padding. This algorithm must be a hashing algorithm.
pbLabel

The address of a buffer that contains the data to use to create the padding. The cbLabel member contains the
size of this buffer.
cbLabel

Contains the number of bytes in the pbLabel buffer to use to create the padding.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Header bcrypt.h

See also
BCryptDecrypt
BCryptEncrypt
 BCRYPT_OID structure (bcrypt.h)
7/2/2022 • 2 minutes to read • Edit Online

The BCRYPT_OID structure contains information about a DER-encoded object identifier (OID). CNG uses hash
OIDs in functions that sign or verify data in PKCS #1 format.

Syntax
typedef struct _BCRYPT_OID {
ULONG cbOID;
PUCHAR pbOID;
} BCRYPT_OID;

Members
cbOID

The size, in bytes, of the pbOID buffer.

pbOID

The address of a buffer that contains the OID.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Header bcrypt.h

See also
BCRYPT_HASH_OID_LIST
BCRYPT_OID_LIST
 BCRYPT_OID_LIST structure (bcrypt.h)
7/2/2022 • 2 minutes to read • Edit Online

The BCRYPT_OID_LIST structure is used to contain a collection of BCRYPT_OID structures. Use this structure
with the BCRYPT_HASH_OID_LIST property to retrieve the list of hashing object identifiers (OIDs) that have been
encoded by using Distinguished Encoding Rules (DER) encoding.

Syntax
typedef struct _BCRYPT_OID_LIST {
ULONG dwOIDCount;
BCRYPT_OID *pOIDs;
} BCRYPT_OID_LIST;

Members
dwOIDCount

The number of elements in the pOIDs array.

pOIDs

The address of an array of BCRYPT_OID structures that contains OIDs.

Remarks
The first OID in the pOIDs array is used to identify any hashes or signatures created by this algorithm provider.
When verifying a hash or signature, all the OIDs in the array are treated as valid.
In the Microsoft Primitive Provider implementation, dwOIDCount is 2, so that the pOIDs array contains two
members:
pOIDs[0] contains a DER-encoded AlgorithmIdentifier with a NULL parameter.
pOIDs[1] contains the DER-encoded AlgorithmIdentifier without a NULL parameter.
For example, the SHA-1 encoding would be:
pOIDs[0] --> 06 05 2b 0e 03 02 1a 05 00
pOIDs[1] --> 06 05 2b 0e 03 02 1a
The following snippet describes an AlgorithmIdentifier in Abstract Syntax Notation One (ASN.1) notation.
SEQUENCE , OBJECT IDENTIFIER , and ANY are DER encoded. The ANY BLOB is NULL .

AlgorithmIdentifier ::= SEQUENCE {

algorithm OBJECT IDENTIFIER,
algorithmParams ANY
}

Requirements
 Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Header bcrypt.h

See also
BCRYPT_OID
BCryptGetProperty
Cryptography Primitive Property Identifiers
 BCRYPT_PKCS1_PADDING_INFO structure
(bcrypt.h)
7/2/2022 • 2 minutes to read • Edit Online

The BCRYPT_PKCS1_PADDING_INFO structure is used to provide options for the PKCS #1 padding scheme.

Syntax
typedef struct _BCRYPT_PKCS1_PADDING_INFO {
LPCWSTR pszAlgId;
} BCRYPT_PKCS1_PADDING_INFO;

Members
pszAlgId

A pointer to a null-terminated Unicode string that identifies the cryptographic algorithm to use to create the
padding. This algorithm must be a hashing algorithm. When creating a signature, the object identifier (OID) that
corresponds to this algorithm is added to the DigestInfo element in the signature, and if this member is NULL ,
then the OID is not added. When verifying a signature, the verification fails if the OID that corresponds to this
member is not the same as the OID in the signature. If there is no OID in the signature, then verification fails
unless this member is NULL .

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Header bcrypt.h

See also
BCryptDecrypt
BCryptEncrypt
BCryptSignHash
BCryptVerifySignature
 BCRYPT_PROVIDER_NAME structure (bcrypt.h)
7/2/2022 • 2 minutes to read • Edit Online

The BCRYPT_PROVIDER_NAME structure contains the name of a CNG provider.

Syntax
typedef struct _BCRYPT_PROVIDER_NAME {
LPWSTR pszProviderName;
} BCRYPT_PROVIDER_NAME;

Members
pszProviderName

A pointer to a null-terminated Unicode string that contains the name of the provider.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Header bcrypt.h

See also
BCryptEnumProviders
 BCRYPT_PSS_PADDING_INFO structure (bcrypt.h)
7/2/2022 • 2 minutes to read • Edit Online

The BCRYPT_PSS_PADDING_INFO structure is used to provide options for the Probabilistic Signature Scheme
(PSS) padding scheme.

Syntax
typedef struct _BCRYPT_PSS_PADDING_INFO {
LPCWSTR pszAlgId;
ULONG cbSalt;
} BCRYPT_PSS_PADDING_INFO;

Members
pszAlgId

A pointer to a null-terminated Unicode string that identifies the cryptographic algorithm to use to create the
padding. This algorithm must be a hashing algorithm.
cbSalt

The size, in bytes, of the random salt to use for the padding.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Header bcrypt.h

See also
BCryptSignHash
BCryptVerifySignature
 BCRYPT_RSAKEY_BLOB structure (bcrypt.h)
7/2/2022 • 2 minutes to read • Edit Online

The BCRYPT_RSAKEY_BLOB structure is used as a header for an RSA public key or private key BLOB in
memory.

Syntax
typedef struct _BCRYPT_RSAKEY_BLOB {
ULONG Magic;
ULONG BitLength;
ULONG cbPublicExp;
ULONG cbModulus;
ULONG cbPrime1;
ULONG cbPrime2;
} BCRYPT_RSAKEY_BLOB;

Members
Magic

Specifies the type of RSA key this BLOB represents. This can be one of the following values.

VA L UE M EA N IN G

The key is an RSA public key.

BCRYPT_RSAPUBLIC_MAGIC

The key is an RSA private key.

BCRYPT_RSAPRIVATE_MAGIC

The key is a full RSA private key.

BCRYPT_RSAFULLPRIVATE_MAGIC

BitLength

The size, in bits, of the key.

cbPublicExp

The size, in bytes, of the exponent of the key. As of Windows 10 version 1903, public exponents larger than
(2^64 - 1) are no longer supported.
cbModulus

The size, in bytes, of the modulus of the key.

cbPrime1

The size, in bytes, of the first prime number of the key. This is only used for private key BLOBs.
cbPrime2
The size, in bytes, of the second prime number of the key. This is only used for private key BLOBs.

Remarks
This structure is used as a header for a larger buffer. An RSA public key BLOB (BCRYPT_RSAPUBLIC_BLOB) has
the following format in contiguous memory. All of the numbers following the structure are in big-endian format.

BCRYPT_RSAKEY_BLOB
PublicExponent[cbPublicExp] // Big-endian.
Modulus[cbModulus] // Big-endian.

An RSA private key BLOB (BCRYPT_RSAPRIVATE_BLOB) has the following format in contiguous memory. All of
the numbers following the structure are in big-endian format.

BCRYPT_RSAKEY_BLOB
PublicExponent[cbPublicExp] // Big-endian.
Modulus[cbModulus] // Big-endian.
Prime1[cbPrime1] // Big-endian.
Prime2[cbPrime2] // Big-endian.

A full RSA private key BLOB (BCRYPT_RSAFULLPRIVATE_BLOB) has the following format in contiguous memory.
All of the numbers following the structure are in big-endian format.
Note that in different versions of Windows, the value that PrivateExponent takes from a call of BCryptExportKey
may be different as there are several mathematically equivalent representations of the PrivateExponent in
cbModulus bytes. Notably, in some versions the PrivateExponent will be exported modulo (Prime1 - 1) * (Prime2
- 1), and in others it will be exported modulo LeastCommonMultiple(Prime1 - 1, Prime2 - 1).

BCRYPT_RSAKEY_BLOB
PublicExponent[cbPublicExp] // Big-endian.
Modulus[cbModulus] // Big-endian.
Prime1[cbPrime1] // Big-endian.
Prime2[cbPrime2] // Big-endian.
Exponent1[cbPrime1] // Big-endian.
Exponent2[cbPrime2] // Big-endian.
Coefficient[cbPrime1] // Big-endian.
PrivateExponent[cbModulus] // Big-endian.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Header bcrypt.h

See also
BCRYPT_KEY_BLOB
BCryptExportKey
BCryptImportKey
 BCryptAddContextFunction function (bcrypt.h)
7/2/2022 • 2 minutes to read • Edit Online

[BCr yptAddContextFunction is available for use in the operating systems specified in the Requirements
section. It may be altered or unavailable in subsequent versions.]
The BCr yptAddContextFunction function adds a cryptographic function to the list of functions that are
supported by an existing CNG context.

Syntax
NTSTATUS BCryptAddContextFunction(
[in] ULONG dwTable,
[in] LPCWSTR pszContext,
[in] ULONG dwInterface,
[in] LPCWSTR pszFunction,
[in] ULONG dwPosition
);

Parameters
[in] dwTable

Identifies the configuration table that the context exists in. This can be one of the following values.

VA L UE M EA N IN G

The context exists in the local-machine configuration table.

CRYPT_LOCAL

This value is not available for use.

CRYPT_DOMAIN

[in] pszContext

A pointer to a null-terminated Unicode string that contains the identifier of the context to add the function to.
[in] dwInterface

Identifies the cryptographic interface to add the function to. This can be one of the following values.

VA L UE M EA N IN G

Add the function to the list of asymmetric encryption

BCRYPT_ASYMMETRIC_ENCRYPTION_INTERFACE functions.

Add the function to the list of cipher functions.

BCRYPT_CIPHER_INTERFACE

Add the function to the list of hash functions.

BCRYPT_HASH_INTERFACE
 Add the function to the list of random number generator
BCRYPT_RNG_INTERFACE functions.

Add the function to the list of secret agreement functions.

BCRYPT_SECRET_AGREEMENT_INTERFACE

Add the function to the list of signature functions.

BCRYPT_SIGNATURE_INTERFACE

Add the function to the list of key storage functions.

NCRYPT_KEY_STORAGE_INTERFACE

Add the function to the list of Schannel functions.

NCRYPT_SCHANNEL_INTERFACE

Add the function to the list of signature suites that Schannel

NCRYPT_SCHANNEL_SIGNATURE_INTERFACE will accept for TLS 1.2.
Windows Vista and Windows Ser ver 2008: This
value is not supported.

[in] pszFunction

A pointer to a null-terminated Unicode string that contains the identifier of the cryptographic function to add.
[in] dwPosition

Specifies the position in the list at which to insert this function. The function is inserted at this position ahead of
any existing functions. The CRYPT_PRIORITY_TOP value is used to insert the function at the top of the list. The
CRYPT_PRIORITY_BOTTOM value is used to insert the function at the end of the list.

Return value
Returns a status code that indicates the success or failure of the function.
Possible return codes include, but are not limited to, the following.

RET URN C O DE DESC RIP T IO N

The function was successful.

STATUS_SUCCESS

One or more parameters are not valid.

STATUS_INVALID_PARAMETER

A memory allocation failure occurred.

STATUS_NO_MEMORY

The context could not be found.

STATUS_NOT_FOUND

Remarks
If the function added is already in the list, it will be removed and inserted at the new position.
BCr yptAddContextFunction can be called only in user mode.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header bcrypt.h

Librar y Bcrypt.lib

DLL Bcrypt.dll

See also
BCryptRemoveContextFunction
 BCryptBuffer structure (bcrypt.h)
7/2/2022 • 2 minutes to read • Edit Online

Represents a generic Cryptography API: Next Generation (CNG) buffer.

NOTE
This struct is also aliased as NCryptBuffer.

Syntax
typedef struct _BCryptBuffer {
ULONG cbBuffer;
ULONG BufferType;
PVOID pvBuffer;
} BCryptBuffer, *PBCryptBuffer;

Members
cbBuffer

The size, in bytes, of the buffer.

BufferType

The type of buffer represented by this structure. This can be one of the following values.

VA L UE M EA N IN G

KDF_HASH_ALGORITHM 0 The buffer is a key derivation function (KDF) parameter that

contains a null-terminated Unicode string that identifies the
hash algorithm. This can be one of the standard hash
algorithm identifiers from CNG Algorithm Identifiers or the
identifier for another registered hash algorithm.

The size specified by the cbBuffer member of this structure

must include the terminating NULL character.

KDF_SECRET_PREPEND 1 The buffer is a KDF parameter that contains the value to add
to the beginning of the message that is input to the hash
function.

KDF_SECRET_APPEND 2 The buffer is a KDF parameter that contains the value to add
to the end of the message that is input to the hash function.

KDF_HMAC_KEY 3 The buffer is a KDF parameter that contains the plain text
value of the HMAC key.

KDF_TLS_PRF_L ABEL 4 The buffer is a KDF parameter that contains an ANSI string
that contains the transport layer security (TLS) pseudo-
random function (PRF) label.
 VA L UE M EA N IN G

KDF_TLS_PRF_SEED 5 The buffer is a KDF parameter that contains the PRF seed
value. The seed must be 64 bytes long.

KDF_SECRET_HANDLE 6 The buffer is a KDF parameter that contains the secret

agreement handle. The pvBuffer member contains a
BCRYPT_SECRET_HANDLE value and is not a pointer.

KDF_TLS_PRF_PROTOCOL 7 The buffer is a KDF parameter that contains a DWORD value

identifying the SSL/TLS protocol version whose PRF
algorithm is to be used.

KDF_ALGORITHMID 8 The buffer is a KDF parameter that contains the byte array
to use as the AlgorithmID subfield of the OtherInfo
parameter to the SP 800-56A KDF.

KDF_PARTYUINFO 9 The buffer is a KDF parameter that contains the byte array
to use as the Par tyUInfo subfield of the OtherInfo
parameter to the SP 800-56A KDF.

KDF_PARTYVINFO 10 The buffer is a KDF parameter that contains the byte array
to use as the Par tyVInfo subfield of the OtherInfo
parameter to the SP 800-56A KDF.

KDF_SUPPPUBINFO 11 The buffer is a KDF parameter that contains the byte array
to use as the SuppPubInfo subfield of the OtherInfo
parameter to the SP 800-56A KDF.

KDF_SUPPPRIVINFO 12 The buffer is a KDF parameter that contains the byte array
to use as the SuppPrivInfo subfield of the OtherInfo
parameter to the SP 800-56A KDF.

KDF_L ABEL 13 See BCryptKeyDerivation function for more info.

KDF_CONTEXT 14 See BCryptKeyDerivation function for more info.

KDF_SALT 15 See BCryptKeyDerivation function for more info.

KDF_ITERATION_COUNT 16 See BCryptKeyDerivation function for more info.

pvBuffer

A 32-bit value defined by the BufferType member.

Requirements

Header bcrypt.h
 BCryptBufferDesc structure (bcrypt.h)
7/2/2022 • 2 minutes to read • Edit Online

Contains a set of generic Cryptography API: Next Generation (CNG) buffers.

NOTE
This struct is also aliased as NCryptBufferDesc.

Syntax
typedef struct _BCryptBufferDesc {
ULONG ulVersion;
ULONG cBuffers;
PBCryptBuffer pBuffers;
} BCryptBufferDesc, *PBCryptBufferDesc;

Members
ulVersion

The version of the structure. This must be the following value.

VA L UE M EA N IN G

BCRYPTBUFFER_VERSION The default version number.

cBuffers

The number of elements in the pBuffers array.

pBuffers

The address of an array of BCr yptBuffer structures that contain the buffers. cBuffers contains the number of
elements in this array.

Requirements

Header bcrypt.h

See also
BCryptDeriveKey function
 BCryptCloseAlgorithmProvider function (bcrypt.h)
7/2/2022 • 2 minutes to read • Edit Online

The BCr yptCloseAlgorithmProvider function closes an algorithm provider.

Syntax
NTSTATUS BCryptCloseAlgorithmProvider(
[in, out] BCRYPT_ALG_HANDLE hAlgorithm,
[in] ULONG dwFlags
);

Parameters
[in, out] hAlgorithm

A handle that represents the algorithm provider to close. This handle is obtained by calling the
BCryptOpenAlgorithmProvider function.
[in] dwFlags

A set of flags that modify the behavior of this function. No flags are defined for this function.

Return value
Returns a status code that indicates the success or failure of the function.
Possible return codes include, but are not limited to, the following.

RET URN C O DE DESC RIP T IO N

The function was successful.

STATUS_SUCCESS

The algorithm handle in the hAlgorithm parameter is not

STATUS_INVALID_HANDLE valid.

Remarks
BCr yptCloseAlgorithmProvider can be called either from user mode or kernel mode. Kernel mode callers
must be executing at PASSIVE_LEVEL IRQL.
To call this function in kernel mode, use Cng.lib, which is part of the Driver Development Kit (DDK). For more
information, see WDK and Developer Tools.Windows Ser ver 2008 and Windows Vista: To call this function
in kernel mode, use Ksecdd.lib.

Requirements
 Minimum suppor ted client Windows Vista [desktop apps | UWP apps]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps | UWP apps]

Target Platform Windows

Header bcrypt.h

Librar y Bcrypt.lib

DLL Bcrypt.dll

See also
BCryptOpenAlgorithmProvider
 BCryptConfigureContext function (bcrypt.h)
7/2/2022 • 2 minutes to read • Edit Online

[BCr yptConfigureContext is available for use in the operating systems specified in the Requirements section.
It may be altered or unavailable in subsequent versions.]
The BCr yptConfigureContext function sets the configuration information for an existing CNG context.

Syntax
NTSTATUS BCryptConfigureContext(
[in] ULONG dwTable,
[in] LPCWSTR pszContext,
[in] PCRYPT_CONTEXT_CONFIG pConfig
);

Parameters
[in] dwTable

Identifies the configuration table that the context exists in. This can be one of the following values.

VA L UE M EA N IN G

The context exists in the local-machine configuration table.

CRYPT_LOCAL

This value is not available for use.

CRYPT_DOMAIN

[in] pszContext

A pointer to a null-terminated Unicode string that contains the identifier of the context to set the configuration
information for.
[in] pConfig

The address of a CRYPT_CONTEXT_CONFIG structure that contains the new context configuration information.

Return value
Returns a status code that indicates the success or failure of the function.
Possible return codes include, but are not limited to, the following.

RET URN C O DE DESC RIP T IO N

The function was successful.

STATUS_SUCCESS
 One or more parameters are not valid.
STATUS_INVALID_PARAMETER

A memory allocation failure occurred.

STATUS_NO_MEMORY

Remarks
BCr yptConfigureContext can be called only in user mode.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header bcrypt.h

Librar y Bcrypt.lib

DLL Bcrypt.dll

See also
CRYPT_CONTEXT_CONFIG
 BCryptConfigureContextFunction function
(bcrypt.h)
7/2/2022 • 2 minutes to read • Edit Online

[BCr yptConfigureContextFunction is available for use in the operating systems specified in the
Requirements section. It may be altered or unavailable in subsequent versions.]
The BCr yptConfigureContextFunction function sets the configuration information for the cryptographic
function of an existing CNG context.

Syntax
NTSTATUS BCryptConfigureContextFunction(
[in] ULONG dwTable,
[in] LPCWSTR pszContext,
[in] ULONG dwInterface,
[in] LPCWSTR pszFunction,
[in] PCRYPT_CONTEXT_FUNCTION_CONFIG pConfig
);

Parameters
[in] dwTable

Identifies the configuration table that the context exists in. This can be one of the following values.

VA L UE M EA N IN G

The context exists in the local-machine configuration table.

CRYPT_LOCAL

This value is not available for use.

CRYPT_DOMAIN

[in] pszContext

A pointer to a null-terminated Unicode string that contains the identifier of the context to set the cryptographic
function configuration information for.
[in] dwInterface

Identifies the cryptographic interface to set the function configuration information for. This can be one of the
following values.

VA L UE M EA N IN G

Set the function configuration information in the list of

BCRYPT_ASYMMETRIC_ENCRYPTION_INTERFACE asymmetric encryption functions.
 Set the function configuration information in the list of
BCRYPT_CIPHER_INTERFACE cipher functions.

Set the function configuration information in the list of hash

BCRYPT_HASH_INTERFACE functions.

Set the function configuration information in the list of

BCRYPT_RNG_INTERFACE random number generator functions.

Set the function configuration information in the list of

BCRYPT_SECRET_AGREEMENT_INTERFACE secret agreement functions.

Set the function configuration information in the list of

BCRYPT_SIGNATURE_INTERFACE signature functions.

Set the function configuration information in the list of key

NCRYPT_KEY_STORAGE_INTERFACE storage functions.

Set the function configuration information in the list of

NCRYPT_SCHANNEL_INTERFACE Schannel functions.

Set the function configuration information in the list of

NCRYPT_SCHANNEL_SIGNATURE_INTERFACE signature suites that Schannel accepts for TLS 1.2.
Windows Vista and Windows Ser ver 2008: This
value is not supported.

[in] pszFunction

A pointer to a null-terminated Unicode string that contains the identifier of the cryptographic function to set the
configuration information for.
[in] pConfig

The address of a CRYPT_CONTEXT_FUNCTION_CONFIG structure that contains the new function configuration
information.

Return value
Returns a status code that indicates the success or failure of the function.
Possible return codes include, but are not limited to, the following.

RET URN C O DE DESC RIP T IO N

The function was successful.

STATUS_SUCCESS

One or more parameters are not valid.

STATUS_INVALID_PARAMETER

A memory allocation failure occurred.

STATUS_NO_MEMORY
Remarks
BCr yptConfigureContextFunction can be called only in user mode.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header bcrypt.h

Librar y Bcrypt.lib

DLL Bcrypt.dll

See also
CRYPT_CONTEXT_FUNCTION_CONFIG
 BCryptCreateContext function (bcrypt.h)
7/2/2022 • 2 minutes to read • Edit Online

[BCr yptCreateContext is available for use in the operating systems specified in the Requirements section. It
may be altered or unavailable in subsequent versions.]
The BCr yptCreateContext function creates a new CNG configuration context.

Syntax
NTSTATUS BCryptCreateContext(
[in] ULONG dwTable,
[in] LPCWSTR pszContext,
[in, optional] PCRYPT_CONTEXT_CONFIG pConfig
);

Parameters
[in] dwTable

Identifies the configuration table to create the context in. This can be one of the following values.

VA L UE M EA N IN G

Create the context in the local-machine configuration table.

CRYPT_LOCAL

This value is not available for use.

CRYPT_DOMAIN

[in] pszContext

A pointer to a null-terminated Unicode string that contains the identifier of the context to create.
[in, optional] pConfig

A pointer to a CRYPT_CONTEXT_CONFIG structure that contains additional configuration data for the new
context. This parameter can be NULL if it is not needed.

Return value
Returns a status code that indicates the success or failure of the function.
Possible return codes include, but are not limited to, the following.

RET URN C O DE DESC RIP T IO N

The function was successful.

STATUS_SUCCESS
 One or more parameters are not valid.
STATUS_INVALID_PARAMETER

A memory allocation failure occurred.

STATUS_NO_MEMORY

Remarks
BCr yptCreateContext can be called only in user mode.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header bcrypt.h

Librar y Bcrypt.lib

DLL Bcrypt.dll
 BCryptCreateHash function (bcrypt.h)
7/2/2022 • 3 minutes to read • Edit Online

The BCr yptCreateHash function is called to create a hash or Message Authentication Code (MAC) object.

Syntax
NTSTATUS BCryptCreateHash(
[in, out] BCRYPT_ALG_HANDLE hAlgorithm,
[out] BCRYPT_HASH_HANDLE *phHash,
[out] PUCHAR pbHashObject,
[in, optional] ULONG cbHashObject,
[in, optional] PUCHAR pbSecret,
[in] ULONG cbSecret,
[in] ULONG dwFlags
);

Parameters
[in, out] hAlgorithm

The handle of an algorithm provider created by using the BCryptOpenAlgorithmProvider function. The
algorithm that was specified when the provider was created must support the hash interface.
[out] phHash

A pointer to a BCRYPT_HASH_HANDLE value that receives a handle that represents the hash or MAC object.
This handle is used in subsequent hashing or MAC functions, such as the BCryptHashData function. When you
have finished using this handle, release it by passing it to the BCryptDestroyHash function.
[out] pbHashObject

A pointer to a buffer that receives the hash or MAC object. The cbHashObject parameter contains the size of this
buffer. The required size of this buffer can be obtained by calling the BCryptGetProperty function to get the
BCRYPT_OBJECT_LENGTH property. This will provide the size of the hash or MAC object for the specified
algorithm.
This memory can only be freed after the handle pointed to by the phHash parameter is destroyed.
If the value of this parameter is NULL and the value of the cbHashObject parameter is zero, the memory for the
hash object is allocated and freed by this function. Windows 7: This memory management functionality is
available beginning with Windows 7.
[in, optional] cbHashObject

The size, in bytes, of the pbHashObject buffer.

If the value of this parameter is zero and the value of the pbHashObject parameter is NULL , the memory for the
key object is allocated and freed by this function. Windows 7: This memory management functionality is
available beginning with Windows 7.
[in, optional] pbSecret

A pointer to a buffer that contains the key to use for the hash or MAC. The cbSecret parameter contains the size
of this buffer. This key only applies to hash algorithms opened by the BCryptOpenAlgorithmProvider function by
using the BCRYPT_ALG_HANDLE_HMAC flag. Otherwise, set this parameter to NULL .
[in] cbSecret

The size, in bytes, of the pbSecret buffer. If no key is used, set this parameter to zero.
[in] dwFlags

Flags that modify the behavior of the function. This can be zero or the following value.

VA L UE M EA N IN G

Creates a reusable hashing object. The object can be used

BCRYPT_HASH_REUSABLE_FL AG for a new hashing operation immediately after calling
BCryptFinishHash. For more information, see Creating a
Hash with CNG.
Windows Ser ver 2008 R2, Windows 7, Windows
Ser ver 2008 and Windows Vista: This flag is not
supported.

Return value
Returns a status code that indicates the success or failure of the function.
Possible return codes include, but are not limited to, the following.

RET URN C O DE DESC RIP T IO N

The function was successful.

STATUS_SUCCESS

The size of the hash object specified by the cbHashObject

STATUS_BUFFER_TOO_SMALL parameter is not large enough to hold the hash object.

The algorithm handle in the hAlgorithm parameter is not

STATUS_INVALID_HANDLE valid.

One or more parameters are not valid.

STATUS_INVALID_PARAMETER

The algorithm provider specified by the hAlgorithm

STATUS_NOT_SUPPORTED parameter does not support the hash interface.

Remarks
Depending on what processor modes a provider supports, BCr yptCreateHash can be called either from user
mode or kernel mode. Kernel mode callers can execute either at PASSIVE_LEVEL IRQL or DISPATCH_LEVEL
IRQL. If the current IRQL level is DISPATCH_LEVEL , the handle provided in the hAlgorithm parameter must
have been opened by using the BCRYPT_PROV_DISPATCH flag, and any pointers passed to the
BCr yptCreateHash function must refer to nonpaged (or locked) memory.
To call this function in kernel mode, use Cng.lib, which is part of the Driver Development Kit (DDK). For more
information, see WDK and Developer Tools.Windows Ser ver 2008 and Windows Vista: To call this function
in kernel mode, use Ksecdd.lib.
Requirements

Minimum suppor ted client Windows Vista [desktop apps | UWP apps]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps | UWP apps]

Target Platform Windows

Header bcrypt.h

Librar y Bcrypt.lib

DLL Bcrypt.dll

See also
BCryptDestroyHash
 BCryptCreateMultiHash function (bcrypt.h)
7/2/2022 • 3 minutes to read • Edit Online

The BCr yptCreateMultiHash function creates a multi-hash state that allows for the parallel computation of
multiple hash operations. This multi-hash state is used by the BCryptProcessMultiOperations function. The
multi-hash state can be thought of as an array of hash objects, each of which is equivalent to one created by
BCryptCreateHash.
Parallel computations can greatly increase overall throughput, at the expense of increased latency for individual
computations.
Parallel hash computations are currently only implemented for SHA-256, SHA-384, and SHA-512. Other hash
algorithms can be used with the parallel computation API but they run at the throughput of the sequential hash
operations. The set of hash algorithms that can benefit from parallel computations might change in future
updates.

Syntax
NTSTATUS BCryptCreateMultiHash(
[in, out] BCRYPT_ALG_HANDLE hAlgorithm,
[out] BCRYPT_HASH_HANDLE *phHash,
[in] ULONG nHashes,
[out] PUCHAR pbHashObject,
[in] ULONG cbHashObject,
[in] PUCHAR pbSecret,
[in] ULONG cbSecret,
[in] ULONG dwFlags
);

Parameters
[in, out] hAlgorithm

The algorithm handle used for all of the hash states in the multi-hash array. The algorithm handle must have
been opened with the BCYRPT_MULTI_FL AG passed to the BCryptOpenAlgorithmProvider function.
Alternatively, the caller can use the pseudo-handles.
[out] phHash

A pointer to a BCRYPT_HASH_HANDLE value that receives a handle that represents the multi-hash state. This
handle is used in subsequent operations such as BCryptProcessMultiOperations. When you have finished using
this handle, release it by passing it to the BCryptDestroyHash function.
[in] nHashes

The number of elements in the array. The multi-hash state that this function creates is able to perform parallel
computations on nHashes different hash states.
[out] pbHashObject

A pointer to a buffer that receives the multi-hash state.

The size can be calculated from the cbPerObject and cbPerElement members of the
BCRYPT_MULTI_OBJECT_LENGTH_STRUCT structure. The value is the following:
cbPerObject + (number of hash states) * cbPerElement .
If pbHashObject is NULL and cbHashObject has a value of zero (0), the object buffer is automatically allocated.
[in] cbHashObject

The size of the pbHashObject buffer, or zero if pbHashObject is NULL .

[in] pbSecret

A pointer to a buffer that contains the key to use for the hash or MAC. The cbSecret parameter contains the size
of this buffer. This key only applies to hash algorithms opened by the BCryptOpenAlgorithmProvider function by
using the BCRYPT_ALG_HANDLE_HMAC flag. Otherwise, set this parameter to NULL .
The same key is used for all elements of the array.
[in] cbSecret

The size, in bytes, of the pbSecret buffer. If no key is used, set this parameter to zero.
[in] dwFlags

Flags that modify the behavior of the function. This can be zero or the values below. Multi-hash objects are
always reusable and always behave as if the BCRYPT_HASH_REUSABLE_FL AG was passed. This flag is
supported here for consistency.

VA L UE M EA N IN G

Creates a reusable hashing object. The object can be used

BCRYPT_HASH_REUSABLE_FL AG for a new hashing operation immediately after calling
BCryptFinishHash. For more information, see Creating a
Hash with CNG.

Return value
None

Remarks
Internally, parallel hash computations are done using single-instruction multiple-data (SIMD) instructions with
up to 8 parallel computations at a time, depending on the hash algorithm and the CPU features available. To
maximize performance, we recommend that the caller provide at least eight computations that can be processed
in parallel.
For computations of unequal length, providing more computations in parallel allows the implementation to
schedule the computations better across the CPU registers. This can provide a throughput benefit. For optimal
throughput, we recommend that the caller provide between eight and 100 computations. Select a lower value in
that range only if all the hash computations are the same length.
Multi-hashing is not supported for HMAC-MD2, HMAC-MD4, and GMAC.

Requirements

Minimum suppor ted client Windows 8.1 Update [desktop apps | UWP apps]
 Minimum suppor ted ser ver Windows Server 2008 Update [desktop apps | UWP apps]

Target Platform Windows

Header bcrypt.h

Librar y Bcrypt.lib

DLL Bcrypt.dll

See also
BCRYPT_MULTI_OBJECT_LENGTH
BCryptCreateHash
BCryptDestroyHash
BCryptFinishHash
BCryptHashData
BCryptOpenAlgorithmProvider
BCryptProcessMultiOperations
Creating a Hash with CNG
 BCryptDecrypt function (bcrypt.h)
7/2/2022 • 4 minutes to read • Edit Online

The BCr yptDecr ypt function decrypts a block of data.

Syntax
NTSTATUS BCryptDecrypt(
[in, out] BCRYPT_KEY_HANDLE hKey,
[in] PUCHAR pbInput,
[in] ULONG cbInput,
[in, optional] VOID *pPaddingInfo,
[in, out, optional] PUCHAR pbIV,
[in] ULONG cbIV,
[out, optional] PUCHAR pbOutput,
[in] ULONG cbOutput,
[out] ULONG *pcbResult,
[in] ULONG dwFlags
);

Parameters
[in, out] hKey

The handle of the key to use to decrypt the data. This handle is obtained from one of the key creation functions,
such as BCryptGenerateSymmetricKey, BCryptGenerateKeyPair, or BCryptImportKey.
[in] pbInput

The address of a buffer that contains the ciphertext to be decrypted. The cbInput parameter contains the size of
the ciphertext to decrypt. For more information, see Remarks.
[in] cbInput

The number of bytes in the pbInput buffer to decrypt.

[in, optional] pPaddingInfo

A pointer to a structure that contains padding information. This parameter is only used with asymmetric keys
and authenticated encryption modes. If an authenticated encryption mode is used, this parameter must point to
a BCRYPT_AUTHENTICATED_CIPHER_MODE_INFO structure. If asymmetric keys are used, the type of structure
this parameter points to is determined by the value of the dwFlags parameter. Otherwise, the parameter must
be set to NULL .
[in, out, optional] pbIV

The address of a buffer that contains the initialization vector (IV) to use during decryption. The cbIV parameter
contains the size of this buffer. This function will modify the contents of this buffer. If you need to reuse the IV
later, make sure you make a copy of this buffer before calling this function.
This parameter is optional and can be NULL if no IV is used.
The required size of the IV can be obtained by calling the BCryptGetProperty function to get the
BCRYPT_BLOCK_LENGTH property. This will provide the size of a block for the algorithm, which is also the
size of the IV.
[in] cbIV

The size, in bytes, of the pbIV buffer.

[out, optional] pbOutput

The address of a buffer to receive the plaintext produced by this function. The cbOutput parameter contains the
size of this buffer. For more information, see Remarks.
If this parameter is NULL , the BCr yptDecr ypt function calculates the size required for the plaintext of the
encrypted data passed in the pbInput parameter. In this case, the location pointed to by the pcbResult parameter
contains this size, and the function returns STATUS_SUCCESS .
If the values of both the pbOutput and pbInput parameters are NULL , an error is returned unless an
authenticated encryption algorithm is in use. In the latter case, the call is treated as an authenticated encryption
call with zero length data, and the authentication tag, passed in the pPaddingInfo parameter, is verified.
[in] cbOutput

The size, in bytes, of the pbOutput buffer. This parameter is ignored if the pbOutput parameter is NULL .
[out] pcbResult

A pointer to a ULONG variable to receive the number of bytes copied to the pbOutput buffer. If pbOutput is
NULL , this receives the size, in bytes, required for the plaintext.
[in] dwFlags

A set of flags that modify the behavior of this function. The allowed set of flags depends on the type of key
specified by the hKey parameter.
If the key is a symmetric key, this can be zero or the following value.

VA L UE M EA N IN G

The data was padded to the next block size when it was
BCRYPT_BLOCK_PADDING encrypted. If this flag was used with the BCryptEncrypt
function, it must also be specified in this function. This flag
must not be used with the authenticated encryption modes
(AES-CCM and AES-GCM).

If the key is an asymmetric key, this can be one of the following values.

VA L UE M EA N IN G

Do not use any padding. The pPaddingInfo parameter is not

BCRYPT_PAD_NONE used. The cbInput parameter must be a multiple of the
algorithm's block size.
The block size can be obtained by calling the
BCryptGetProperty function to get the
BCRYPT_BLOCK_LENGTH property for the key. This
will provide the size of a block for the algorithm.

The Optimal Asymmetric Encryption Padding (OAEP) scheme

BCRYPT_PAD_OAEP was used when the data was encrypted. The pPaddingInfo
parameter is a pointer to a BCRYPT_OAEP_PADDING_INFO
structure.
 The data was padded with a random number when the data
BCRYPT_PAD_PKCS1 was encrypted. The pPaddingInfo parameter is not used.

Return value
Returns a status code that indicates the success or failure of the function.
Possible return codes include, but are not limited to, the following.

RET URN C O DE DESC RIP T IO N

The function was successful.

STATUS_SUCCESS

The computed authentication tag did not match the value

STATUS_AUTH_TAG_MISMATCH supplied in the pPaddingInfo parameter.

The size specified by the cbOutput parameter is not large

STATUS_BUFFER_TOO_SMALL enough to hold the ciphertext.

The cbInput parameter is not a multiple of the algorithm's

STATUS_INVALID_BUFFER_SIZE block size, and the BCRYPT_BLOCK_PADDING flag was
not specified in the dwFlags parameter.

The key handle in the hKey parameter is not valid.

STATUS_INVALID_HANDLE

One or more parameters are not valid.

STATUS_INVALID_PARAMETER

The algorithm does not support decryption.

STATUS_NOT_SUPPORTED

Remarks
The pbInput and pbOutput parameters can be equal. In this case, this function will perform the decryption in
place. If pbInput and pbOutput are not equal, the two buffers may not overlap.
Depending on what processor modes a provider supports, BCr yptDecr ypt can be called either from user
mode or kernel mode. Kernel mode callers can execute either at PASSIVE_LEVEL IRQL or DISPATCH_LEVEL
IRQL. If the current IRQL level is DISPATCH_LEVEL , the handle provided in the hKey parameter must be derived
from an algorithm handle returned by a provider that was opened with the BCRYPT_PROV_DISPATCH flag,
and any pointers passed to the BCr yptDecr ypt function must refer to nonpaged (or locked) memory.
To call this function in kernel mode, use Cng.lib, which is part of the Driver Development Kit (DDK). Windows
Ser ver 2008 and Windows Vista: To call this function in kernel mode, use Ksecdd.lib.

Requirements

Minimum suppor ted client Windows Vista [desktop apps | UWP apps]
 Minimum suppor ted ser ver Windows Server 2008 [desktop apps | UWP apps]

Target Platform Windows

Header bcrypt.h

Librar y Bcrypt.lib

DLL Bcrypt.dll

See also
BCryptEncrypt
 BCryptDeleteContext function (bcrypt.h)
7/2/2022 • 2 minutes to read • Edit Online

[BCr yptDeleteContext is available for use in the operating systems specified in the Requirements section. It
may be altered or unavailable in subsequent versions.]
The BCr yptDeleteContext function deletes an existing CNG configuration context.

Syntax
NTSTATUS BCryptDeleteContext(
[in] ULONG dwTable,
[in] LPCWSTR pszContext
);

Parameters
[in] dwTable

Identifies the configuration table to delete the context from. This can be one of the following values.

VA L UE M EA N IN G

Delete the context from the local-machine configuration

CRYPT_LOCAL table.

This value is not available for use.

CRYPT_DOMAIN

[in] pszContext

A pointer to a null-terminated Unicode string that contains the identifier of the context to delete.

Return value
Returns a status code that indicates the success or failure of the function.
Possible return codes include, but are not limited to, the following.

RET URN C O DE DESC RIP T IO N

The function was successful.

STATUS_SUCCESS

One or more parameters are not valid.

STATUS_INVALID_PARAMETER

A memory allocation failure occurred.

STATUS_NO_MEMORY
Remarks
BCr yptDeleteContext can be called only in user mode.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header bcrypt.h

Librar y Bcrypt.lib

DLL Bcrypt.dll
 BCryptDeriveKey function (bcrypt.h)
7/2/2022 • 8 minutes to read • Edit Online

The BCr yptDeriveKey function derives a key from a secret agreement value.
For key derivation from a given secret, see BCryptKeyDerivation.

Syntax
NTSTATUS BCryptDeriveKey(
[in] BCRYPT_SECRET_HANDLE hSharedSecret,
[in] LPCWSTR pwszKDF,
[in, optional] BCryptBufferDesc *pParameterList,
[out, optional] PUCHAR pbDerivedKey,
[in] ULONG cbDerivedKey,
[out] ULONG *pcbResult,
[in] ULONG dwFlags
);

Parameters
[in] hSharedSecret

The secret agreement handle to create the key from. This handle is obtained from the BCryptSecretAgreement
function.
[in] pwszKDF

A pointer to a null-terminated Unicode string that identifies the key derivation function (KDF) to use to derive
the key. This can be one of the following strings.
BCRYPT_KDF_HASH (L"HASH")
Use the hash key derivation function.
If the cbDerivedKey parameter is less than the size of the derived key, this function will only copy the specified
number of bytes to the pbDerivedKey buffer. If the cbDerivedKey parameter is greater than the size of the
derived key, this function will copy the key to the pbDerivedKey buffer and set the variable pointed to by the
pcbResult to the actual number of bytes copied.
The parameters identified by the pParameterList parameter either can or must contain the following parameters,
as indicated by the Required or optional column.

PA RA M ET ER DESC RIP T IO N REQ UIRED O R O P T IO N A L

KDF_HASH_ALGORITHM A null-terminated Unicode string that Optional

identifies the hash algorithm to use.
This can be one of the standard hash
algorithm identifiers from CNG
Algorithm Identifiers or the identifier
for another registered hash algorithm.
If this parameter is not specified,
the SHA1 hash algorithm is used.
 KDF_SECRET_PREPEND A value to add to the beginning of the Optional
message input to the hash function.
For more information, see Remarks.

KDF_SECRET_APPEND A value to add to the end of the Optional

message input to the hash function.
For more information, see Remarks.

The call to the KDF is made as shown in the following pseudocode.

KDF-Prepend = KDF_SECRET_PREPEND[0] +
KDF_SECRET_PREPEND[1] +
... +
KDF_SECRET_PREPEND[n]

KDF-Append = KDF_SECRET_APPEND[0] +
KDF_SECRET_APPEND[1] +
... +
KDF_SECRET_APPEND[n]

KDF-Output = Hash(
KDF-Prepend +
hSharedSecret +
KDF-Append)

BCRYPT_KDF_HMAC (L"HMAC")
Use the Hash-Based Message Authentication Code (HMAC) key derivation function.
If the cbDerivedKey parameter is less than the size of the derived key, this function will only copy the specified
number of bytes to the pbDerivedKey buffer. If the cbDerivedKey parameter is greater than the size of the
derived key, this function will copy the key to the pbDerivedKey buffer and set the variable pointed to by the
pcbResult to the actual number of bytes copied.
The parameters identified by the pParameterList parameter either can or must contain the following parameters,
as indicated by the Required or optional column.

PA RA M ET ER DESC RIP T IO N REQ UIRED O R O P T IO N A L

KDF_HASH_ALGORITHM A null-terminated Unicode string that Optional

identifies the hash algorithm to use.
This can be one of the standard hash
algorithm identifiers from CNG
Algorithm Identifiers or the identifier
for another registered hash algorithm.
If this parameter is not specified,
the SHA1 hash algorithm is used.

KDF_HMAC_KEY The key to use for the pseudo-random Optional

function (PRF).

KDF_SECRET_PREPEND A value to add to the beginning of the Optional

message input to the hash function.
For more information, see Remarks.

KDF_SECRET_APPEND A value to add to the end of the Optional

message input to the hash function.
For more information, see Remarks.
The call to the KDF is made as shown in the following pseudocode.

KDF-Prepend = KDF_SECRET_PREPEND[0] +
KDF_SECRET_PREPEND[1] +
... +
KDF_SECRET_PREPEND[n]

KDF-Append = KDF_SECRET_APPEND[0] +
KDF_SECRET_APPEND[1] +
... +
KDF_SECRET_APPEND[n]

KDF-Output = HMAC-Hash(
KDF_HMAC_KEY,
KDF-Prepend +
hSharedSecret +
KDF-Append)

BCRYPT_KDF_TLS_PRF (L"TLS_PRF")
Use the transport layer security (TLS) pseudo-random function (PRF) key derivation function. The size of the
derived key is always 48 bytes, so the cbDerivedKey parameter must be 48.
The parameters identified by the pParameterList parameter either can or must contain the following parameters,
as indicated by the Required or optional column.

PA RA M ET ER DESC RIP T IO N REQ UIRED O R O P T IO N A L

KDF_TLS_PRF_L ABEL An ANSI string that contains the PRF Required

label.

KDF_TLS_PRF_SEED The PRF seed. The seed must be 64 Required

bytes long.

KDF_TLS_PRF_PROTOCOL A DWORD value that specifies the TLS Optional

protocol version whose PRF algorithm
is to be used.
Valid values are:
SSL2_PROTOCOL_VERSION (0x0002)
SSL3_PROTOCOL_VERSION (0x0300)
TLS1_PROTOCOL_VERSION (0x0301)
TLS1_0_PROTOCOL_VERSION (0x0301)
TLS1_1_PROTOCOL_VERSION (0x0302)
TLS1_2_PROTOCOL_VERSION (0x0303)
DTLS1_0_PROTOCOL_VERSION (0xfeff)
Windows Ser ver 2008 and
Windows Vista: TLS1_1_PROTO
COL_VERSION,
TLS1_2_PROTOCOL_VERSION and
DTLS1_0_PROTOCOL_VERSION are
not supported.
Windows Ser ver 2008 R2,
Windows 7, Windows
Ser ver 2008 and
Windows Vista: DTLS1_0_PROT
OCOL_VERSION is not supported.
 KDF_HASH_ALGORITHM The CNG algorithm ID of the hash to Optional
be used with the HMAC in the PRF, for
the TLS 1.2 protocol version. Valid
choices are SHA-256 and SHA-384. If
not specified, SHA-256 is used.

The call to the KDF is made as shown in the following pseudocode.

KDF-Output = PRF(
hSharedSecret,
KDF_TLS_PRF_LABEL,
KDF_TLS_PRF_SEED)

BCRYPT_KDF_SP80056A_CONCAT (L"SP800_56A_CONCAT")
Use the SP800-56A key derivation function.
The parameters identified by the pParameterList parameter either can or must contain the following parameters,
as indicated by the Required or optional column. All parameter values are treated as opaque byte arrays.

PA RA M ET ER DESC RIP T IO N REQ UIRED O R O P T IO N A L

KDF_ALGORITHMID Specifies the AlgorithmID subfield of Required

the OtherInfo field in the SP800-56A
key derivation function. Indicates the
intended purpose of the derived key.

KDF_PARTYUINFO Specifies the Par tyUInfo subfield of Required

the OtherInfo field in the SP800-56A
key derivation function. The field
contains public information
contributed by the initiator.

KDF_PARTYVINFO Specifies the Par tyVInfo subfield of Required

the OtherInfo field in the SP800-56A
key derivation function. The field
contains public information
contributed by the responder.

KDF_SUPPPUBINFO Specifies the SuppPubInfo subfield of Optional

the OtherInfo field in the SP800-56A
key derivation function. The field
contains public information known to
both initiator and responder.

KDF_SUPPPRIVINFO Specifies the SuppPrivInfo subfield of Optional

the OtherInfo field in the SP800-56A
key derivation function. It contains
private information known to both
initiator and responder, such as a
shared secret.

The call to the KDF is made as shown in the following pseudocode.

 KDF-Output = SP_800-56A_KDF(
hSharedSecret,
KDF_ALGORITHMID,
KDF_PARTYUINFO,
KDF_PARTYVINFO,
KDF_SUPPPUBINFO,
KDF_SUPPPRIVINFO)

Windows Ser ver 2008, Windows Vista, Windows Ser ver 2003 and Windows XP: This value is not
supported.
BCRYPT_KDF_RAW_SECRET (L"TRUNCATE")
Returns the little-endian representation of the raw secret without any modification.
If the cbDerivedKey parameter is less than the size of the derived key, this function will only copy the specified
number of bytes to the pbDerivedKey buffer. If the cbDerivedKey parameter is greater than the size of the
derived key, this function will copy the key to the pbDerivedKey buffer and set the variable pointed to by the
pcbResult to the actual number of bytes copied.
Windows 8, Windows Ser ver 2008, Windows Vista, Windows Ser ver 2003 and Windows XP: This
value is not supported.
[in, optional] pParameterList

The address of a BCryptBufferDesc structure that contains the KDF parameters. This parameter is optional and
can be NULL if it is not needed.
[out, optional] pbDerivedKey

The address of a buffer that receives the key. The cbDerivedKey parameter contains the size of this buffer. If this
parameter is NULL , this function will place the required size, in bytes, in the ULONG pointed to by the
pcbResult parameter.
[in] cbDerivedKey

The size, in bytes, of the pbDerivedKey buffer.

[out] pcbResult

A pointer to a ULONG that receives the number of bytes that were copied to the pbDerivedKey buffer. If the
pbDerivedKey parameter is NULL , this function will place the required size, in bytes, in the ULONG pointed to
by this parameter.
[in] dwFlags

A set of flags that modify the behavior of this function. This can be zero or the following value.

VA L UE M EA N IN G

KDF_USE_SECRET_AS_HMAC_KEY_FL AG
The secret agreement value will also serve as the HMAC key.
If this flag is specified, the KDF_HMAC_KEY parameter
should not be included in the set of parameters in the
pParameterList parameter. This flag is only used by the
BCRYPT_KDF_HMAC key derivation function.

Return value
Returns a status code that indicates the success or failure of the function.
Possible return codes include, but are not limited to, the following.
 RET URN C O DE DESC RIP T IO N

The function was successful.

STATUS_SUCCESS

An internal error occurred.

STATUS_INTERNAL_ERROR

The handle in the hSharedSecret parameter is not valid.

STATUS_INVALID_HANDLE

One or more parameters are not valid.

STATUS_INVALID_PARAMETER

Remarks
The BCryptBufferDesc structure in the pParameterList parameter can contain more than one of the
KDF_SECRET_PREPEND and KDF_SECRET_APPEND parameters. If more than one of these parameters is
specified, the parameter values are concatenated in the order in which they are contained in the array before the
KDF is called. For example, assume the following parameter values are specified.

BYTE pbValue0[1] = {0x01};

BYTE pbValue1[2] = {0x04, 0x05};
BYTE pbValue2[3] = {0x10, 0x11, 0x12};
BYTE pbValue3[4] = {0x20, 0x21, 0x22, 0x23};

Parameter[0].type = KDF_SECRET_APPEND
Parameter[0].value = pbValue0;
Parameter[0].length = sizeof (pbValue0);
Parameter[1].type = KDF_SECRET_PREPEND
Parameter[1].value = pbValue1;
Parameter[1].length = sizeof (pbValue1);
Parameter[2].type = KDF_SECRET_APPEND
Parameter[2].value = pbValue2;
Parameter[2].length = sizeof (pbValue2);
Parameter[3].type = KDF_SECRET_PREPEND
Parameter[3].value = pbValue3;
Parameter[3].length = sizeof (pbValue3);

If the above parameter values are specified, the concatenated values to the actual KDF are as follows.

Type: KDF_SECRET_PREPEND
Value: {0x04, 0x05, 0x20, 0x21, 0x22, 0x23}, length 6

Type: KDF_SECRET_APPEND
Value: {0x01, 0x10, 0x11, 0x12}, length 4

If the pwszKDF parameter is set to BCRYPT_KDF_RAW_SECRET , The returned secret (unlike the other
pwszKDF values) will be encoded in little-endian format. It is important to take note of this when using the raw
secret in any other CNG functions, as most of them take in big-endian encoded inputs.
Depending on what processor modes a provider supports, BCr yptDeriveKey can be called either from user
mode or kernel mode. Kernel mode callers can execute either at PASSIVE_LEVEL IRQL or DISPATCH_LEVEL
IRQL. If the current IRQL level is DISPATCH_LEVEL , the handle provided in the hSharedSecret parameter must
be located in nonpaged (or locked) memory and must be derived from an algorithm handle returned by a
provider that was opened by using the BCRYPT_PROV_DISPATCH flag.
To call this function in kernel mode, use Cng.lib, which is part of the Driver Development Kit (DDK). Windows
Ser ver 2008 and Windows Vista: To call this function in kernel mode, use Ksecdd.lib.

Requirements

Minimum suppor ted client Windows Vista [desktop apps | UWP apps]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps | UWP apps]

Target Platform Windows

Header bcrypt.h

Librar y Bcrypt.lib

DLL Bcrypt.dll

See also
BCryptSecretAgreement
 BCryptDeriveKeyCapi function (bcrypt.h)
7/2/2022 • 2 minutes to read • Edit Online

The BCr yptDeriveKeyCapi function derives a key from a hash value.

This function is provided as a helper function to assist in migrating legacy Cryptography API (CAPI)–based
applications to use Cryptography API: Next Generation (CNG). The BCr yptDeriveKeyCapi function performs
the key derivation in a manner that is compatible with the CAPI CryptDeriveKey function.

Syntax
NTSTATUS BCryptDeriveKeyCapi(
[in] BCRYPT_HASH_HANDLE hHash,
[in, optional] BCRYPT_ALG_HANDLE hTargetAlg,
[out] PUCHAR pbDerivedKey,
[in] ULONG cbDerivedKey,
[in] ULONG dwFlags
);

Parameters
[in] hHash

The handle of the hash object. The handle is obtained by calling the BCryptCreateHash function. When you have
finished using the handle, you must free it by calling the BCryptDestroyHash function.
[in, optional] hTargetAlg

The handle of the algorithm object. This can be an ALG_ID value that is compatible with the CryptDeriveKey
function.

Note Limitations in CAPI and key expansion prevent the use of any hash algorithm that generates an output that is larger
than 512 bits.

[out] pbDerivedKey

A pointer to the buffer that receives the derived key.

[in] cbDerivedKey

The size, in characters, of the derived key pointed to by the pbDerivedKey parameter.
[in] dwFlags

This parameter is reserved and must be set to zero.

Return value
Returns a status code that indicates the success or failure of the function.
Possible return codes include, but are not limited to, the following.
 RET URN C O DE DESC RIP T IO N

The function was successful.

STATUS_SUCCESS

The handle in the hHash or hTargetAlg parameter is not

STATUS_INVALID_HANDLE valid.

The value in the cbDerivedKey parameter is larger than twice

STATUS_INVALID_PARAMETER the output size of the hash function.

A memory allocation failure occurred.

STATUS_NO_MEMORY

Remarks
This function does not support the PK salt functionality of the CAPI CryptDeriveKey function.

Requirements

Minimum suppor ted client Windows 7 [desktop apps | UWP apps]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps | UWP apps]

Target Platform Windows

Header bcrypt.h

Librar y Bcrypt.lib

DLL Bcrypt.dll
 BCryptDeriveKeyPBKDF2 function (bcrypt.h)
7/2/2022 • 2 minutes to read • Edit Online

The BCr yptDeriveKeyPBKDF2 function derives a key from a hash value by using the PBKDF2 key derivation
algorithm as defined by RFC 2898.

Syntax
NTSTATUS BCryptDeriveKeyPBKDF2(
[in] BCRYPT_ALG_HANDLE hPrf,
[in, optional] PUCHAR pbPassword,
[in] ULONG cbPassword,
[in, optional] PUCHAR pbSalt,
[in] ULONG cbSalt,
[in] ULONGLONG cIterations,
[out] PUCHAR pbDerivedKey,
[in] ULONG cbDerivedKey,
[in] ULONG dwFlags
);

Parameters
[in] hPrf

The handle of an algorithm provider that provides the pseudo-random function. This should be an algorithm
provider that performs a Message Authentication Code computation. When you use the default Microsoft
algorithm provider, any hashing algorithm opened by using the BCRYPT_ALG_HANDLE_HMAC_FL AG flag
can be used.

Note Only algorithms that implement the BCRYPT_IS_KEYED_HASH property can be used to populate this parameter.

[in, optional] pbPassword

A pointer to a buffer that contains the password parameter for the PBKDF2 key derivation algorithm.

Note Any secret information used in the key derivation should be passed in this buffer.

[in] cbPassword

The length, in bytes, of the data in the buffer pointed to by the pbPassword parameter.
[in, optional] pbSalt

A pointer to a buffer that contains the salt argument for the PBKDF2 key derivation algorithm.

Note Any information that is not secret and that is used in the key derivation should be passed in this buffer.
[in] cbSalt

The length, in bytes, of the salt argument pointed to by the pbSalt parameter.
[in] cIterations

The iteration count for the PBKDF2 key derivation algorithm.

[out] pbDerivedKey

A pointer to a buffer that receives the derived key.

[in] cbDerivedKey

The length, in bytes, of the derived key returned in the buffer pointed to by the pbDerivedKey parameter.
[in] dwFlags

This parameter is reserved and must be set to zero.

Return value
Returns a status code that indicates the success or failure of the function.
Possible return codes include, but are not limited to, the following.

RET URN C O DE DESC RIP T IO N

The function was successful.

STATUS_SUCCESS

The handle in the hPrf parameter is not valid.

STATUS_INVALID_HANDLE

One or more parameters are not valid.

STATUS_INVALID_PARAMETER

A memory allocation failure occurred.

STATUS_NO_MEMORY

Requirements

Minimum suppor ted client Windows 7 [desktop apps | UWP apps]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps | UWP apps]

Target Platform Windows

Header bcrypt.h

Librar y Bcrypt.lib

DLL Bcrypt.dll
 BCryptDestroyHash function (bcrypt.h)
7/2/2022 • 2 minutes to read • Edit Online

The BCr yptDestroyHash function destroys a hash or Message Authentication Code (MAC) object.

Syntax
NTSTATUS BCryptDestroyHash(
[in, out] BCRYPT_HASH_HANDLE hHash
);

Parameters
[in, out] hHash

The handle of the hash or MAC object to destroy. This handle is obtained by using the BCryptCreateHash
function.

Return value
Returns a status code that indicates the success or failure of the function.
Possible return codes include, but are not limited to, the following.

RET URN C O DE DESC RIP T IO N

The function was successful.

STATUS_SUCCESS

The algorithm handle in the hHash parameter is not valid.

STATUS_INVALID_HANDLE

Remarks
Depending on what processor modes a provider supports, BCr yptDestroyHash can be called either from user
mode or kernel mode. Kernel mode callers can execute either at PASSIVE_LEVEL IRQL or DISPATCH_LEVEL
IRQL. If the current IRQL level is DISPATCH_LEVEL , the handle provided in the hHash parameter must be
derived from an algorithm handle returned by a provider that was opened by using the
BCRYPT_PROV_DISPATCH flag.
To call this function in kernel mode, use Cng.lib, which is part of the Driver Development Kit (DDK). Windows
Ser ver 2008 and Windows Vista: To call this function in kernel mode, use Ksecdd.lib.

Requirements

Minimum suppor ted client Windows Vista [desktop apps | UWP apps]
 Minimum suppor ted ser ver Windows Server 2008 [desktop apps | UWP apps]

Target Platform Windows

Header bcrypt.h

Librar y Bcrypt.lib

DLL Bcrypt.dll

See also
BCryptCreateHash
 BCryptDestroyKey function (bcrypt.h)
7/2/2022 • 2 minutes to read • Edit Online

The BCr yptDestroyKey function destroys a key.

Syntax
NTSTATUS BCryptDestroyKey(
[in, out] BCRYPT_KEY_HANDLE hKey
);

Parameters
[in, out] hKey

The handle of the key to destroy.

Return value
Returns a status code that indicates the success or failure of the function.
Possible return codes include, but are not limited to, the following.

RET URN C O DE DESC RIP T IO N

The function was successful.

STATUS_SUCCESS

The key handle in the hKey parameter is not valid.

STATUS_INVALID_HANDLE

Remarks
Depending on what processor modes a provider supports, BCr yptDestroyKey can be called either from user
mode or kernel mode. Kernel mode callers can execute either at PASSIVE_LEVEL IRQL or DISPATCH_LEVEL
IRQL. If the current IRQL level is DISPATCH_LEVEL , the handle provided in the hKey parameter must be derived
from an algorithm handle returned by a provider that was opened with the BCRYPT_PROV_DISPATCH flag.
To call this function in kernel mode, use Cng.lib, which is part of the Driver Development Kit (DDK). Windows
Ser ver 2008 and Windows Vista: To call this function in kernel mode, use Ksecdd.lib.

Requirements

Minimum suppor ted client Windows Vista [desktop apps | UWP apps]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps | UWP apps]
 Target Platform Windows

Header bcrypt.h

Librar y Bcrypt.lib

DLL Bcrypt.dll

See also
BCryptGenerateKeyPair
BCryptGenerateSymmetricKey
BCryptImportKey
BCryptImportKeyPair
 BCryptDestroySecret function (bcrypt.h)
7/2/2022 • 2 minutes to read • Edit Online

The BCr yptDestroySecret function destroys a secret agreement handle that was created by using the
BCryptSecretAgreement function.

Syntax
NTSTATUS BCryptDestroySecret(
[in] BCRYPT_SECRET_HANDLE hSecret
);

Parameters
[in] hSecret

The BCRYPT_SECRET_HANDLE to be destroyed.

Return value
Returns a status code that indicates the success or failure of the function.
Possible return codes include, but are not limited to, the following.

RET URN C O DE DESC RIP T IO N

The function was successful.

STATUS_SUCCESS

The handle in the hSecret parameter is not valid.

STATUS_INVALID_HANDLE

Remarks
Depending on what processor modes a provider supports, BCr yptDestroySecret can be called either from
user mode or kernel mode. Kernel mode callers can execute either at PASSIVE_LEVEL IRQL or
DISPATCH_LEVEL IRQL. If the current IRQL level is DISPATCH_LEVEL , the handle provided in the hSecret
parameter must be derived from an algorithm handle returned by a provider that was opened by using the
BCRYPT_PROV_DISPATCH flag.
To call this function in kernel mode, use Cng.lib, which is part of the Driver Development Kit (DDK). Windows
Ser ver 2008 and Windows Vista: To call this function in kernel mode, use Ksecdd.lib.

Requirements

Minimum suppor ted client Windows Vista [desktop apps | UWP apps]
 Minimum suppor ted ser ver Windows Server 2008 [desktop apps | UWP apps]

Target Platform Windows

Header bcrypt.h

Librar y Bcrypt.lib

DLL Bcrypt.dll

See also
BCryptSecretAgreement
 BCryptDuplicateHash function (bcrypt.h)
7/2/2022 • 2 minutes to read • Edit Online

The BCr yptDuplicateHash function duplicates an existing hash or Message Authentication Code (MAC) object.
The duplicate object contains all state and data contained in the original object at the point of duplication.

Syntax
NTSTATUS BCryptDuplicateHash(
[in] BCRYPT_HASH_HANDLE hHash,
[out] BCRYPT_HASH_HANDLE *phNewHash,
[out] PUCHAR pbHashObject,
[in] ULONG cbHashObject,
[in] ULONG dwFlags
);

Parameters
[in] hHash

The handle of the hash or MAC object to duplicate.

[out] phNewHash

A pointer to a BCRYPT_HASH_HANDLE value that receives the handle that represents the duplicate hash or
MAC object.
[out] pbHashObject

A pointer to a buffer that receives the duplicate hash or MAC object. The cbHashObject parameter contains the
size of this buffer. The required size of this buffer can be obtained by calling the BCryptGetProperty function to
get the BCRYPT_OBJECT_LENGTH property. This will provide the size of the hash object for the specified
algorithm.
When the duplicate hash handle is released, free this memory.
[in] cbHashObject

The size, in bytes, of the pbHashObject buffer.

[in] dwFlags

A set of flags that modify the behavior of this function. No flags are currently defined, so this parameter should
be zero.

Return value
Returns a status code that indicates the success or failure of the function.
Possible return codes include, but are not limited to, the following.

RET URN C O DE DESC RIP T IO N

 The function was successful.
STATUS_SUCCESS

The size of the hash object specified by the cbHashObject

STATUS_BUFFER_TOO_SMALL parameter is not large enough to hold the hash object.

The hash handle in the hHash parameter is not valid.

STATUS_INVALID_HANDLE

One or more parameters are not valid.

STATUS_INVALID_PARAMETER

Remarks
This function is useful when computing a hash or MAC over a block of common data. After the common data
has been processed, the hash or MAC object can be duplicated, and then the unique data can be added to the
individual objects.
Depending on what processor modes a provider supports, BCr yptDuplicateHash can be called either from
user mode or kernel mode. Kernel mode callers can execute either at PASSIVE_LEVEL IRQL or
DISPATCH_LEVEL IRQL. If the current IRQL level is DISPATCH_LEVEL , the handle provided in the hHash
parameter must be derived from an algorithm handle returned by a provider that was opened by using the
BCRYPT_PROV_DISPATCH flag, and any pointers passed to the BCryptDestroyKey function must refer to
nonpaged (or locked) memory.
To call this function in kernel mode, use Cng.lib, which is part of the Driver Development Kit (DDK). Windows
Ser ver 2008 and Windows Vista: To call this function in kernel mode, use Ksecdd.lib.

Requirements

Minimum suppor ted client Windows Vista [desktop apps | UWP apps]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps | UWP apps]

Target Platform Windows

Header bcrypt.h

Librar y Bcrypt.lib

DLL Bcrypt.dll
 BCryptDuplicateKey function (bcrypt.h)
7/2/2022 • 2 minutes to read • Edit Online

The BCr yptDuplicateKey function creates a duplicate of a symmetric key.

Syntax
NTSTATUS BCryptDuplicateKey(
[in] BCRYPT_KEY_HANDLE hKey,
[out] BCRYPT_KEY_HANDLE *phNewKey,
[out] PUCHAR pbKeyObject,
[in] ULONG cbKeyObject,
[in] ULONG dwFlags
);

Parameters
[in] hKey

The handle of the key to duplicate. This must be a handle to a symmetric key.
[out] phNewKey

A pointer to a BCRYPT_KEY_HANDLE variable that receives the handle of the duplicate key. This handle is used
in subsequent functions that require a key, such as BCryptEncrypt. This handle must be released when it is no
longer needed by passing it to the BCryptDestroyKey function.
[out] pbKeyObject

A pointer to a buffer that receives the duplicate key object. The cbKeyObject parameter contains the size of this
buffer. The required size of this buffer can be obtained by calling the BCryptGetProperty function to get the
BCRYPT_OBJECT_LENGTH property. This will provide the size of the key object for the specified algorithm.
This memory can only be freed after the phNewKey key handle is destroyed.
[in] cbKeyObject

The size, in bytes, of the pbKeyObject buffer.

[in] dwFlags

A set of flags that modify the behavior of this function. No flags are currently defined, so this parameter should
be zero.

Return value
Returns a status code that indicates the success or failure of the function.
Possible return codes include, but are not limited to, the following.

RET URN C O DE DESC RIP T IO N

 The function was successful.
STATUS_SUCCESS

The size of the key object specified by the cbKeyObject

STATUS_BUFFER_TOO_SMALL parameter is not large enough to hold the key object.

The key handle in the hKey parameter is not valid. This value
STATUS_INVALID_HANDLE is also returned if the key to duplicate is not a symmetric
key.

One or more parameters are not valid.

STATUS_INVALID_PARAMETER

Remarks
Depending on what processor modes a provider supports, BCr yptDuplicateKey can be called either from user
mode or kernel mode. Kernel mode callers can execute either at PASSIVE_LEVEL IRQL or DISPATCH_LEVEL
IRQL. If the current IRQL level is DISPATCH_LEVEL , the handle provided in the hKey parameter must be derived
from an algorithm handle returned by a provider that was opened with the BCRYPT_PROV_DISPATCH flag,
and any pointers passed to the BCr yptDuplicateKey function must refer to nonpaged (or locked) memory.
To call this function in kernel mode, use Cng.lib, which is part of the Driver Development Kit (DDK). Windows
Ser ver 2008 and Windows Vista: To call this function in kernel mode, use Ksecdd.lib.

Requirements

Minimum suppor ted client Windows Vista [desktop apps | UWP apps]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps | UWP apps]

Target Platform Windows

Header bcrypt.h

Librar y Bcrypt.lib

DLL Bcrypt.dll
 BCryptEncrypt function (bcrypt.h)
7/2/2022 • 5 minutes to read • Edit Online

The BCr yptEncr ypt function encrypts a block of data.

Syntax
NTSTATUS BCryptEncrypt(
[in, out] BCRYPT_KEY_HANDLE hKey,
[in] PUCHAR pbInput,
[in] ULONG cbInput,
[in, optional] VOID *pPaddingInfo,
[in, out, optional] PUCHAR pbIV,
[in] ULONG cbIV,
[out, optional] PUCHAR pbOutput,
[in] ULONG cbOutput,
[out] ULONG *pcbResult,
[in] ULONG dwFlags
);

Parameters
[in, out] hKey

The handle of the key to use to encrypt the data. This handle is obtained from one of the key creation functions,
such as BCryptGenerateSymmetricKey, BCryptGenerateKeyPair, or BCryptImportKey.
[in] pbInput

The address of a buffer that contains the plaintext to be encrypted. The cbInput parameter contains the size of
the plaintext to encrypt. For more information, see Remarks.
[in] cbInput

The number of bytes in the pbInput buffer to encrypt.

[in, optional] pPaddingInfo

A pointer to a structure that contains padding information. This parameter is only used with asymmetric keys
and authenticated encryption modes. If an authenticated encryption mode is used, this parameter must point to
a BCRYPT_AUTHENTICATED_CIPHER_MODE_INFO structure. If asymmetric keys are used, the type of structure
this parameter points to is determined by the value of the dwFlags parameter. Otherwise, the parameter must
be set to NULL .
[in, out, optional] pbIV

The address of a buffer that contains the initialization vector (IV) to use during encryption. The cbIV parameter
contains the size of this buffer. This function will modify the contents of this buffer. If you need to reuse the IV
later, make sure you make a copy of this buffer before calling this function.
This parameter is optional and can be NULL if no IV is used.
The required size of the IV can be obtained by calling the BCryptGetProperty function to get the
BCRYPT_BLOCK_LENGTH property. This will provide the size of a block for the algorithm, which is also the
size of the IV.
[in] cbIV

The size, in bytes, of the pbIV buffer.

[out, optional] pbOutput

The address of the buffer that receives the ciphertext produced by this function. The cbOutput parameter
contains the size of this buffer. For more information, see Remarks.
If this parameter is NULL , the BCr yptEncr ypt function calculates the size needed for the ciphertext of the data
passed in the pbInput parameter. In this case, the location pointed to by the pcbResult parameter contains this
size, and the function returns STATUS_SUCCESS . The pPaddingInfo parameter is not modified.
If the values of both the pbOutput and pbInput parameters are NULL , an error is returned unless an
authenticated encryption algorithm is in use. In the latter case, the call is treated as an authenticated encryption
call with zero length data, and the authentication tag is returned in the pPaddingInfo parameter.
[in] cbOutput

The size, in bytes, of the pbOutput buffer. This parameter is ignored if the pbOutput parameter is NULL .
[out] pcbResult

A pointer to a ULONG variable that receives the number of bytes copied to the pbOutput buffer. If pbOutput is
NULL , this receives the size, in bytes, required for the ciphertext.
[in] dwFlags

A set of flags that modify the behavior of this function. The allowed set of flags depends on the type of key
specified by the hKey parameter.
If the key is a symmetric key, this can be zero or the following value.

VA L UE M EA N IN G

Allows the encryption algorithm to pad the data to the next

BCRYPT_BLOCK_PADDING block size. If this flag is not specified, the size of the plaintext
specified in the cbInput parameter must be a multiple of the
algorithm's block size.
The block size can be obtained by calling the
BCryptGetProperty function to get the
BCRYPT_BLOCK_LENGTH property for the key. This
will provide the size of a block for the algorithm.
This flag must not be used with the authenticated
encryption modes (AES-CCM and AES-GCM).

If the key is an asymmetric key, this can be one of the following values.

VA L UE M EA N IN G

Do not use any padding. The pPaddingInfo parameter is not

BCRYPT_PAD_NONE used. The size of the plaintext specified in the cbInput
parameter must be a multiple of the algorithm's block size.

Use the Optimal Asymmetric Encryption Padding (OAEP)

BCRYPT_PAD_OAEP scheme. The pPaddingInfo parameter is a pointer to a
BCRYPT_OAEP_PADDING_INFO structure.
 The data will be padded with a random number to round
BCRYPT_PAD_PKCS1 out the block size. The pPaddingInfo parameter is not used.

Return value
Returns a status code that indicates the success or failure of the function.
Possible return codes include, but are not limited to, the following.

RET URN C O DE DESC RIP T IO N

The function was successful.

STATUS_SUCCESS

The size specified by the cbOutput parameter is not large

STATUS_BUFFER_TOO_SMALL enough to hold the ciphertext.

The cbInput parameter is not a multiple of the algorithm's

STATUS_INVALID_BUFFER_SIZE block size and the BCRYPT_BLOCK_PADDING or the
BCRYPT_PAD_NONE flag was not specified in the dwFlags
parameter.

The key handle in the hKey parameter is not valid.

STATUS_INVALID_HANDLE

One or more parameters are not valid.

STATUS_INVALID_PARAMETER

The algorithm does not support encryption.

STATUS_NOT_SUPPORTED

Remarks
The pbInput and pbOutput parameters can be equal. In this case, this function will perform the encryption in
place. It is possible that the encrypted data size will be larger than the unencrypted data size, so the buffer must
be large enough to hold the encrypted data. If pbInput and pbOutput are not equal then the two buffers may not
overlap.
Depending on what processor modes a provider supports, BCr yptEncr ypt can be called either from user mode
or kernel mode. Kernel mode callers can execute either at PASSIVE_LEVEL IRQL or DISPATCH_LEVEL IRQL. If
the current IRQL level is DISPATCH_LEVEL , the handle provided in the hKey parameter must be derived from
an algorithm handle returned by a provider that was opened with the BCRYPT_PROV_DISPATCH flag, and any
pointers passed to the BCr yptEncr ypt function must refer to nonpaged (or locked) memory.
To call this function in kernel mode, use Cng.lib, which is part of the Driver Development Kit (DDK). Windows
Ser ver 2008 and Windows Vista: To call this function in kernel mode, use Ksecdd.lib.

Requirements

Minimum suppor ted client Windows Vista [desktop apps | UWP apps]
 Minimum suppor ted ser ver Windows Server 2008 [desktop apps | UWP apps]

Target Platform Windows

Header bcrypt.h

Librar y Bcrypt.lib

DLL Bcrypt.dll

See also
BCryptDecrypt
 BCryptEnumAlgorithms function (bcrypt.h)
7/2/2022 • 2 minutes to read • Edit Online

The BCr yptEnumAlgorithms function gets a list of the registered algorithm identifiers.

Syntax
NTSTATUS BCryptEnumAlgorithms(
[in] ULONG dwAlgOperations,
[out] ULONG *pAlgCount,
[out] BCRYPT_ALGORITHM_IDENTIFIER **ppAlgList,
[in] ULONG dwFlags
);

Parameters
[in] dwAlgOperations

A value that specifies the algorithm operation types to include in the enumeration. This can be a combination of
one or more of the following values.

VA L UE M EA N IN G

Include the cipher algorithms in the enumeration.

BCRYPT_CIPHER_OPERATION
0x00000001

Include the hash algorithms in the enumeration.

BCRYPT_HASH_OPERATION
0x00000002

Include the asymmetric encryption algorithms in the

BCRYPT_ASYMMETRIC_ENCRYPTION_OPERATION enumeration.
0x00000004

Include the secret agreement algorithms in the enumeration.

BCRYPT_SECRET_AGREEMENT_OPERATION
0x00000008

Include the signature algorithms in the enumeration.

BCRYPT_SIGNATURE_OPERATION
0x00000010

Include the random number generator (RNG) algorithms in

BCRYPT_RNG_OPERATION the enumeration.
0x00000020

[out] pAlgCount

A pointer to a ULONG variable to receive the number of elements in the ppAlgList array.
[out] ppAlgList

The address of a BCRYPT_ALGORITHM_IDENTIFIER structure pointer to receive the array of registered algorithm
identifiers. This pointer must be passed to the BCryptFreeBuffer function when it is no longer needed.
[in] dwFlags

A set of flags that modify the behavior of this function. No flags are defined for this function.

Return value
Returns a status code that indicates the success or failure of the function.
Possible return codes include, but are not limited to, the following.

RET URN C O DE DESC RIP T IO N

The function was successful.

STATUS_SUCCESS

One or more parameters are not valid.

STATUS_INVALID_PARAMETER

A memory allocation failure occurred.

STATUS_NO_MEMORY

Remarks
BCr yptEnumAlgorithms can be called either from user mode or kernel mode. Kernel mode callers must be
executing at PASSIVE_LEVEL IRQL.

Requirements

Minimum suppor ted client Windows Vista [desktop apps | UWP apps]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps | UWP apps]

Target Platform Windows

Header bcrypt.h

Librar y Bcrypt.lib

DLL Bcrypt.dll
 BCryptEnumContextFunctionProviders function
(bcrypt.h)
7/2/2022 • 3 minutes to read • Edit Online

The BCr yptEnumContextFunctionProviders function obtains the providers for the cryptographic functions
for a context in the specified configuration table.

Syntax
NTSTATUS BCryptEnumContextFunctionProviders(
[in] ULONG dwTable,
[in] LPCWSTR pszContext,
[in] ULONG dwInterface,
[in] LPCWSTR pszFunction,
[in, out] ULONG *pcbBuffer,
[in, out] PCRYPT_CONTEXT_FUNCTION_PROVIDERS *ppBuffer
);

Parameters
[in] dwTable

Identifies the configuration table from which to retrieve the context function providers. This can be one of the
following values.

VA L UE M EA N IN G

Retrieve the context functions from the local-machine

CRYPT_LOCAL configuration table.

This value is not available for use.

CRYPT_DOMAIN

[in] pszContext

A pointer to a null-terminated Unicode string that contains the identifier of the context to enumerate the
function providers for.
[in] dwInterface

Identifies the cryptographic interface to retrieve the function providers for. This can be one of the following
values.

VA L UE M EA N IN G

Retrieve the asymmetric encryption function providers.

BCRYPT_ASYMMETRIC_ENCRYPTION_INTERFACE

Retrieve the cipher function providers.

BCRYPT_CIPHER_INTERFACE
 Retrieve the hash function providers.
BCRYPT_HASH_INTERFACE

Retrieve the random number generator function providers.

BCRYPT_RNG_INTERFACE

Retrieve the secret agreement function providers.

BCRYPT_SECRET_AGREEMENT_INTERFACE

Retrieve the signature function providers.

BCRYPT_SIGNATURE_INTERFACE

Retrieve the key storage function providers.

NCRYPT_KEY_STORAGE_INTERFACE

Retrieve the Schannel function providers.

NCRYPT_SCHANNEL_INTERFACE

[in] pszFunction

A pointer to a null-terminated Unicode string that contains the identifier of the function to enumerate the
providers for.
[in, out] pcbBuffer

The address of a ULONG variable that, on entry, contains the size, in bytes, of the buffer pointed to by ppBuffer.
If this size is not large enough to hold the set of context identifiers, this function will fail with
STATUS_BUFFER_TOO_SMALL .
After this function returns, this value contains the number of bytes that were copied to the ppBuffer buffer.
[in, out] ppBuffer

The address of a pointer to a CRYPT_CONTEXT_FUNCTION_PROVIDERS structure that receives the set of context
function providers retrieved by this function. The value pointed to by the pcbBuffer parameter contains the size
of this buffer.
If the value pointed to by this parameter is NULL , this function will allocate the required memory. This memory
must be freed when it is no longer needed by passing this pointer to the BCryptFreeBuffer function.
If this parameter is NULL , this function will place the required size, in bytes, in the variable pointed to by the
pcbBuffer parameter and return STATUS_BUFFER_TOO_SMALL .

Return value
Returns a status code that indicates the success or failure of the function.
Possible return codes include, but are not limited to, the following.

RET URN C O DE DESC RIP T IO N

The function was successful.

STATUS_SUCCESS
 The ppBuffer parameter is not NULL , and the value pointed
STATUS_BUFFER_TOO_SMALL to by the pcbBuffer parameter is not large enough to hold
the set of contexts.

One or more parameters are not valid.

STATUS_INVALID_PARAMETER

A memory allocation failure occurred.

STATUS_NO_MEMORY

No context function providers that match the specified

STATUS_NOT_FOUND criteria were found.

Remarks
BCr yptEnumContextFunctionProviders can be called only in user mode.
Examples
The following example shows how to use the BCr yptEnumContextFunctionProviders function to enumerate
the providers for all key storage functions for all contexts in the local-machine configuration table.

#include <windows.h>
#include <stdio.h>
#include <ntstatus.h>
#include <Bcrypt.h>
#pragma comment(lib, "Bcrypt.lib")

#ifndef NT_SUCCESS
#define NT_SUCCESS(Status) ((NTSTATUS)(Status) >= 0)
#endif

NTSTATUS EnumContextFunctionProviders()
{
NTSTATUS status;
ULONG uSize = 0;
ULONG uTable = CRYPT_LOCAL;
PCRYPT_CONTEXTS pContexts = NULL;

// Get the contexts for the local machine.

// CNG will allocate the memory for us.
status = BCryptEnumContexts(uTable, &uSize, &pContexts);
if(NT_SUCCESS(status))
{
// Enumerate the context identifiers.
for(ULONG a = 0;
a < pContexts->cContexts;
a++)
{
ULONG uInterface = NCRYPT_SCHANNEL_INTERFACE;

wprintf(L"Context functions for %s:\n",

pContexts->rgpszContexts[a]);

// Get the functions for this context.

// CNG will allocate the memory for us.
PCRYPT_CONTEXT_FUNCTIONS pContextFunctions = NULL;
status = BCryptEnumContextFunctions(
uTable,
pContexts->rgpszContexts[a],
uInterface,
&uSize,
&pContextFunctions);
 &pContextFunctions);
if(NT_SUCCESS(status))
{
// Enumerate the functions.
for(ULONG b = 0;
b < pContextFunctions->cFunctions;
b++)
{
wprintf(L"\tFunction providers for %s:\n",
pContextFunctions->rgpszFunctions[b]);

// Get the providers for this function.

PCRYPT_CONTEXT_FUNCTION_PROVIDERS pProviders;
pProviders = NULL;
status = BCryptEnumContextFunctionProviders(
uTable,
pContexts->rgpszContexts[a],
uInterface,
pContextFunctions->rgpszFunctions[b],
&uSize,
&pProviders);
if(NT_SUCCESS(status))
{
for(ULONG c = 0;
c < pProviders->cProviders;
c++)
{
wprintf(L"\t\t%s\n",
pProviders->rgpszProviders[c]);
}
}
else if(STATUS_NOT_FOUND == status)
{
wprintf(L"\t\tNone found.\n");
}
}

// Free the context functions buffer.

BCryptFreeBuffer(pContextFunctions);
}
}

// Free the contexts buffer.

BCryptFreeBuffer(pContexts);
}

return status;
}

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header bcrypt.h

Librar y Bcrypt.lib
 DLL Bcrypt.dll

See also
BCryptFreeBuffer
CRYPT_CONTEXT_FUNCTION_PROVIDERS
 BCryptEnumContextFunctions function (bcrypt.h)
7/2/2022 • 3 minutes to read • Edit Online

The BCr yptEnumContextFunctions function obtains the cryptographic functions for a context in the specified
configuration table.

Syntax
NTSTATUS BCryptEnumContextFunctions(
[in] ULONG dwTable,
[in] LPCWSTR pszContext,
[in] ULONG dwInterface,
[in, out] ULONG *pcbBuffer,
[in, out] PCRYPT_CONTEXT_FUNCTIONS *ppBuffer
);

Parameters
[in] dwTable

Identifies the configuration table from which to retrieve the context functions. This can be one of the following
values.

VA L UE M EA N IN G

Retrieve the context functions from the local-machine

CRYPT_LOCAL configuration table.

This value is not available for use.

CRYPT_DOMAIN

[in] pszContext

A pointer to a null-terminated Unicode string that contains the identifier of the context to enumerate the
functions for.
[in] dwInterface

Identifies the cryptographic interface to retrieve the functions for. This can be one of the following values.

VA L UE M EA N IN G

Retrieve the asymmetric encryption functions.

BCRYPT_ASYMMETRIC_ENCRYPTION_INTERFACE

Retrieve the cipher functions.

BCRYPT_CIPHER_INTERFACE

Retrieve the hash functions.

BCRYPT_HASH_INTERFACE
 Retrieve the random number generator functions.
BCRYPT_RNG_INTERFACE

Retrieve the secret agreement functions.

BCRYPT_SECRET_AGREEMENT_INTERFACE

Retrieve the signature functions.

BCRYPT_SIGNATURE_INTERFACE

Retrieve the key storage functions.

NCRYPT_KEY_STORAGE_INTERFACE

Retrieve the Schannel functions.

NCRYPT_SCHANNEL_INTERFACE

[in, out] pcbBuffer

The address of a ULONG variable that, on entry, contains the size, in bytes, of the buffer pointed to by ppBuffer.
If this size is not large enough to hold the set of context identifiers, this function will fail with
STATUS_BUFFER_TOO_SMALL .
After this function returns, this value contains the number of bytes that were copied to the ppBuffer buffer.
[in, out] ppBuffer

The address of a pointer to a CRYPT_CONTEXT_FUNCTIONS structure that receives the set of context functions
retrieved by this function. The value pointed to by the pcbBuffer parameter contains the size of this buffer.
If the value pointed to by this parameter is NULL , this function will allocate the required memory. This memory
must be freed when it is no longer needed by passing this pointer to the BCryptFreeBuffer function.
If this parameter is NULL , this function will place the required size, in bytes, in the variable pointed to by the
pcbBuffer parameter and return STATUS_BUFFER_TOO_SMALL .

Return value
Returns a status code that indicates the success or failure of the function.
Possible return codes include, but are not limited to, the following.

RET URN C O DE DESC RIP T IO N

The function was successful.

STATUS_SUCCESS

The ppBuffer parameter is not NULL , and the value pointed

STATUS_BUFFER_TOO_SMALL to by the pcbBuffer parameter is not large enough to hold
the set of contexts.

One or more parameters are not valid.

STATUS_INVALID_PARAMETER

A memory allocation failure occurred.

STATUS_NO_MEMORY
 No context functions that match the specified criteria were
STATUS_NOT_FOUND found.

Remarks
BCr yptEnumContextFunctions can be called only in user mode.
Examples
The following example shows how to use the BCr yptEnumContextFunctions function to enumerate the key
storage functions for all contexts in the local-machine configuration table.
 #include <windows.h>
#include <stdio.h>
#include <Bcrypt.h>
#pragma comment(lib, "Bcrypt.lib")

#ifndef NT_SUCCESS
#define NT_SUCCESS(Status) ((NTSTATUS)(Status) >= 0)
#endif

NTSTATUS EnumContextFunctions()
{
NTSTATUS status;
ULONG uSize = 0;
PCRYPT_CONTEXTS pContexts = NULL;

// Get the contexts for the local machine.

// CNG will allocate the memory for us.
status = BCryptEnumContexts(CRYPT_LOCAL, &uSize, &pContexts);
if(NT_SUCCESS(status))
{
// Enumerate the context identifiers.
for(ULONG uContextIndex = 0;
uContextIndex < pContexts->cContexts;
uContextIndex++)
{
wprintf(L"Context functions for %s:\n",
pContexts->rgpszContexts[uContextIndex]);

// Get the functions for this context.

// CNG will allocate the memory for us.
PCRYPT_CONTEXT_FUNCTIONS pContextFunctions = NULL;
status = BCryptEnumContextFunctions(
CRYPT_LOCAL,
pContexts->rgpszContexts[uContextIndex],
NCRYPT_SCHANNEL_INTERFACE,
&uSize,
&pContextFunctions);
if(NT_SUCCESS(status))
{
// Enumerate the functions.
for(ULONG i = 0;
i < pContextFunctions->cFunctions;
i++)
{
wprintf(L"\t%s\n",
pContextFunctions->rgpszFunctions[i]);
}

// Free the context functions buffer.

BCryptFreeBuffer(pContextFunctions);
}
}

// Free the contexts buffer.

BCryptFreeBuffer(pContexts);
}

return status;
}

Requirements
 Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header bcrypt.h

Librar y Bcrypt.lib

DLL Bcrypt.dll

See also
CRYPT_CONTEXT_FUNCTIONS
 BCryptEnumContexts function (bcrypt.h)
7/2/2022 • 2 minutes to read • Edit Online

[BCr yptEnumContexts is available for use in the operating systems specified in the Requirements section. It
may be altered or unavailable in subsequent versions.]
The BCr yptEnumContexts function obtains the identifiers of the contexts in the specified configuration table.

Syntax
NTSTATUS BCryptEnumContexts(
[in] ULONG dwTable,
[in, out] ULONG *pcbBuffer,
[in, out] PCRYPT_CONTEXTS *ppBuffer
);

Parameters
[in] dwTable

Identifies the configuration table from which to retrieve the contexts. This can be one of the following values.

VA L UE M EA N IN G

Retrieve the contexts from the local-machine configuration

CRYPT_LOCAL table.

This value is not available for use.

CRYPT_DOMAIN

[in, out] pcbBuffer

The address of a ULONG variable that, on entry, contains the size, in bytes, of the buffer pointed to by ppBuffer.
If this size is not large enough to hold the set of context identifiers, this function will fail with
STATUS_BUFFER_TOO_SMALL .
After this function returns, this value contains the number of bytes that were copied to the ppBuffer buffer.
[in, out] ppBuffer

The address of a pointer to a CRYPT_CONTEXTS structure that receives the set of contexts retrieved by this
function. The value pointed to by the pcbBuffer parameter contains the size of this buffer.
If the value pointed to by this parameter is NULL , this function will allocate the required memory. This memory
must be freed when it is no longer needed by passing this pointer to the BCryptFreeBuffer function.
If this parameter is NULL , this function will place the required size, in bytes, in the variable pointed to by the
pcbBuffer parameter and return STATUS_BUFFER_TOO_SMALL .

Return value
Returns a status code that indicates the success or failure of the function.
Possible return codes include, but are not limited to, the following.

RET URN C O DE DESC RIP T IO N

The function was successful.

STATUS_SUCCESS

One or more parameters are not valid.

STATUS_INVALID_PARAMETER

A memory allocation failure occurred.

STATUS_NO_MEMORY

The ppBuffer parameter is not NULL , and the value pointed

STATUS_BUFFER_TOO_SMALL to by the pcbBuffer parameter is not large enough to hold
the set of contexts.

Remarks
BCr yptEnumContexts can be called only in user mode.
Examples
The following example shows how to use the BCr yptEnumContexts function to allocate the memory for the
ppBuffer buffer.

#ifndef NT_SUCCESS
#define NT_SUCCESS(Status) ((NTSTATUS)(Status) >= 0)
#endif

NTSTATUS EnumContexts_SystemAlloc()
{
NTSTATUS status;
ULONG uSize = 0;
PCRYPT_CONTEXTS pContexts = NULL;

// Get the contexts for the local computer.

// CNG allocates the memory.
status = BCryptEnumContexts(CRYPT_LOCAL, &uSize, &pContexts);
if(NT_SUCCESS(status))
{
// Enumerate the context identifiers.
for(ULONG i = 0; i < pContexts->cContexts; i++)
{
wprintf(pContexts->rgpszContexts[i]);
wprintf(L"\n");
}

// Free the buffer.

BCryptFreeBuffer(pContexts);
}

return status;
}

The following example shows how to use the BCr yptEnumContexts function to allocate your own memory for
the ppBuffer buffer.
 #ifndef NT_SUCCESS
#define NT_SUCCESS(Status) ((NTSTATUS)(Status) >= 0)
#endif

NTSTATUS EnumContexts_SelfAlloc()
{
NTSTATUS status;
ULONG uSize = 0;

// Get the required size of the buffer.

status = BCryptEnumContexts(CRYPT_LOCAL, &uSize, NULL);
if(STATUS_BUFFER_TOO_SMALL == status)
{
// Allocate the buffer.
PCRYPT_CONTEXTS pContexts = (PCRYPT_CONTEXTS)HeapAlloc(
GetProcessHeap(),
HEAP_ZERO_MEMORY,
uSize);
if(pContexts)
{
// Get the contexts for the local machine.
status = BCryptEnumContexts(
CRYPT_LOCAL,
&uSize,
&pContexts);
if(NT_SUCCESS((status))
{
// Enumerate the context identifiers.
for(ULONG i = 0; i < pContexts->cContexts; i++)
{
wprintf(pContexts->rgpszContexts[i]);
wprintf(L"\n");
}
}

// Free the buffer.

HeapFree(GetProcessHeap(), 0, pContexts);
pContexts = NULL;
}
else
{
status = STATUS_NO_MEMORY;
}
}

return status;
}

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header bcrypt.h
 Librar y Bcrypt.lib

DLL Bcrypt.dll

See also
BCryptFreeBuffer
CRYPT_CONTEXTS
 BCryptEnumProviders function (bcrypt.h)
7/2/2022 • 2 minutes to read • Edit Online

The BCr yptEnumProviders function obtains all of the CNG providers that support a specified algorithm.

Syntax
NTSTATUS BCryptEnumProviders(
[in] LPCWSTR pszAlgId,
[out] ULONG *pImplCount,
[out] BCRYPT_PROVIDER_NAME **ppImplList,
[in] ULONG dwFlags
);

Parameters
[in] pszAlgId

A pointer to a null-terminated Unicode string that identifies the algorithm to obtain the providers for. This can be
one of the predefined CNG Algorithm Identifiers or another algorithm identifier.
[out] pImplCount

A pointer to a ULONG variable to receive the number of elements in the ppImplList array.
[out] ppImplList

The address of an array of BCRYPT_PROVIDER_NAME structures to receive the collection of providers that
support the specified algorithm. The pImplCount parameter receives the number of elements in this array. This
memory must be freed when it is no longer needed by passing this pointer to the BCryptFreeBuffer function.
[in] dwFlags

A set of flags that modifies the behavior of this function. There are currently no flags defined, so this parameter
must be zero.

Return value
Returns a status code that indicates the success or failure of the function.
Possible return codes include, but are not limited to, the following.

RET URN C O DE DESC RIP T IO N

The function was successful.

STATUS_SUCCESS

One or more parameters are not valid.

STATUS_INVALID_PARAMETER

A memory allocation failure occurred.

STATUS_NO_MEMORY
Remarks
BCr yptEnumProviders can be called either from user mode or kernel mode. Kernel mode callers must be
executing at PASSIVE_LEVEL IRQL.

Requirements

Minimum suppor ted client Windows Vista [desktop apps | UWP apps]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps | UWP apps]

Target Platform Windows

Header bcrypt.h

Librar y Bcrypt.lib

DLL Bcrypt.dll

See also
BCRYPT_PROVIDER_NAME
BCryptFreeBuffer
 BCryptEnumRegisteredProviders function (bcrypt.h)
7/2/2022 • 2 minutes to read • Edit Online

The BCr yptEnumRegisteredProviders function retrieves information about the registered providers.

Syntax
NTSTATUS BCryptEnumRegisteredProviders(
[in, out] ULONG *pcbBuffer,
[in, out] PCRYPT_PROVIDERS *ppBuffer
);

Parameters
[in, out] pcbBuffer

A pointer to a ULONG value that, on entry, contains the size, in bytes, of the buffer pointed to by the ppBuffer
parameter. On exit, this value receives either the number of bytes copied to the buffer or the required size, in
bytes, of the buffer.

Note This is the total size, in bytes, of the entire buffer, not just the size of the CRYPT_PROVIDERS structure. The buffer must
be able to hold other data for the providers in addition to the CRYPT_PROVIDERS structure.

[in, out] ppBuffer

A pointer to a buffer pointer that receives a CRYPT_PROVIDERS structure and other data that describes the
collection of registered providers.
If this parameter is NULL , this function will return STATUS_BUFFER_TOO_SMALL and place in the value
pointed to by the pcbBuffer parameter, the required size, in bytes, of all the data.
If this parameter is the address of a NULL pointer, this function will allocate the required memory, fill the
memory with the information about the providers, and place the pointer to this memory in this parameter.
When you have finished using this memory, free it by passing this pointer to the BCryptFreeBuffer function.
If this parameter is the address of a non-NULL pointer, this function will copy the provider information into this
buffer. The pcbBuffer parameter must contain the size, in bytes, of the entire buffer. If the buffer is not large
enough to hold all of the provider information, this function will return STATUS_BUFFER_TOO_SMALL .

Return value
Returns a status code that indicates the success or failure of the function.
Possible return codes include, but are not limited to, the following.

RET URN C O DE DESC RIP T IO N

The function was successful.

STATUS_SUCCESS
 The size specified by the pcbBuffer parameter is not large
STATUS_BUFFER_TOO_SMALL enough to hold all of the data.

One or more parameters are not valid.

STATUS_INVALID_PARAMETER

Remarks
The BCr yptEnumRegisteredProviders function can be called in one of two ways:
The first is to have the BCr yptEnumRegisteredProviders function allocate the memory. This is
accomplished by passing the address of a NULL pointer for the ppBuffer parameter.
The following example shows how to use the BCr yptEnumRegisteredProviders function to allocate
memory by passing the address of a NULL pointer for the ppBuffer parameter.

PCRYPT_PROVIDERS pBuffer = NULL;

BCryptEnumRegisteredProviders(/*...*/, &pBuffer);

This code will allocate the memory required for the CRYPT_PROVIDERS structure and the associated
strings. When the BCr yptEnumRegisteredProviders function is used in this manner, you must free the
memory when it is no longer needed by passing ppBuffer to the BCryptFreeBuffer function.
The second method is to allocate the required memory yourself. This is accomplished by calling the
BCr yptEnumRegisteredProviders function with NULL for the ppBuffer parameter. The
BCr yptEnumRegisteredProviders function will place in the value pointed to by the pcbBuffer parameter,
the required size, in bytes, of the CRYPT_PROVIDERS structure and all strings. You then allocate the required
memory and pass the address of this buffer pointer for the ppBuffer parameter in a second call to the
BCr yptEnumRegisteredProviders function.
BCr yptEnumRegisteredProviders can be called only in user mode.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header bcrypt.h

Librar y Bcrypt.lib

DLL Bcrypt.dll

See also
BCryptFreeBuffer
CRYPT_PROVIDERS
 BCryptExportKey function (bcrypt.h)
7/2/2022 • 5 minutes to read • Edit Online

The BCr yptExpor tKey function exports a key to a memory BLOB that can be persisted for later use.

Syntax
NTSTATUS BCryptExportKey(
[in] BCRYPT_KEY_HANDLE hKey,
[in] BCRYPT_KEY_HANDLE hExportKey,
[in] LPCWSTR pszBlobType,
[out] PUCHAR pbOutput,
[in] ULONG cbOutput,
[out] ULONG *pcbResult,
[in] ULONG dwFlags
);

Parameters
[in] hKey

The handle of the key to export.

[in] hExportKey

The handle of the key with which to wrap the exported key. Use this parameter when exporting BLOBs of type
BCRYPT_AES_WRAP_KEY_BLOB ; otherwise, set it to NULL .

Note The hExportKey handle must be supplied by the same provider that supplied the hKey handle, and hExportKey must be
a handle to a symmetric key that can be used in the Advanced Encryption Standard (AES) key wrap algorithm. When the hKey
handle is from the Microsoft provider, hExportKey must be an AES key handle.

Windows Ser ver 2008 and Windows Vista: This parameter is not used and should be set to NULL .
[in] pszBlobType

A null-terminated Unicode string that contains an identifier that specifies the type of BLOB to export. This can be
one of the following values.

VA L UE M EA N IN G

Export an AES key wrapped key. The hExportKey parameter

BCRYPT_AES_WRAP_KEY_BLOB must reference a valid BCRYPT_KEY_HANDLE pointer to
the key encryption key, and the key represented by the hKey
parameter must be a multiple of 8 bytes long.
Windows Ser ver 2008 and Windows Vista: This
BLOB type is not supported.

Export a Diffie-Hellman public/private key pair. The

BCRYPT_DH_PRIVATE_BLOB pbOutput buffer receives a BCRYPT_DH_KEY_BLOB structure
immediately followed by the key data.
 Export a Diffie-Hellman public key. The pbOutput buffer
BCRYPT_DH_PUBLIC_BLOB receives a BCRYPT_DH_KEY_BLOB structure immediately
followed by the key data.

Export a DSA public/private key pair. The pbOutput buffer

BCRYPT_DSA_PRIVATE_BLOB receives a BCRYPT_DSA_KEY_BLOB or
BCRYPT_DSA_KEY_BLOB_V2 structure immediately followed
by the key data. BCRYPT_DSA_KEY_BLOB is used for key
lengths from 512 to 1024 bits.
BCRYPT_DSA_KEY_BLOB_V2 is used for key lengths that
exceed 1024 bits but are less than or equal to 3072 bits.
Windows 8: Support for BCRYPT_DSA_KEY_BLOB_V2
begins.

Export a DSA public key. The pbOutput buffer receives a

BCRYPT_DSA_PUBLIC_BLOB BCRYPT_DSA_KEY_BLOB or BCRYPT_DSA_KEY_BLOB_V2
structure immediately followed by the key data.
BCRYPT_DSA_KEY_BLOB is used for key lengths from 512
to 1024 bits. BCRYPT_DSA_KEY_BLOB_V2 is used for key
lengths that exceed 1024 bits but are less than or equal to
3072 bits.
Windows 8: Support for BCRYPT_DSA_KEY_BLOB_V2
begins.

Export an elliptic curve cryptography (ECC) private key. The

BCRYPT_ECCPRIVATE_BLOB pbOutput buffer receives a BCRYPT_ECCKEY_BLOB structure
immediately followed by the key data.

Export an ECC public key. The pbOutput buffer receives a

BCRYPT_ECCPUBLIC_BLOB BCRYPT_ECCKEY_BLOB structure immediately followed by
the key data.

Export a symmetric key to a data BLOB. The pbOutput

BCRYPT_KEY_DATA_BLOB buffer receives a BCRYPT_KEY_DATA_BLOB_HEADER
structure immediately followed by the key BLOB.

Export a symmetric key in a format that is specific to a single

BCRYPT_OPAQUE_KEY_BLOB cryptographic service provider (CSP). Opaque BLOBs are not
transferable and must be imported by using the same CSP
that generated the BLOB. Opaque BLOBs are only intended
to be used for interprocess transfer of keys and are not
suitable to be persisted and read across versions of a
provider.

Export a generic public key of any type. The type of key in

BCRYPT_PUBLIC_KEY_BLOB this BLOB is determined by the Magic member of the
BCRYPT_KEY_BLOB structure.

Export a generic private key of any type. The private key

BCRYPT_PRIVATE_KEY_BLOB does not necessarily contain the public key. The type of key
in this BLOB is determined by the Magic member of the
BCRYPT_KEY_BLOB structure.

Export a full RSA public/private key pair. The pbOutput buffer

BCRYPT_RSAFULLPRIVATE_BLOB receives a BCRYPT_RSAKEY_BLOB structure immediately
followed by the key data. This BLOB will include additional
key material compared to the
BCRYPT_RSAPRIVATE_BLOB type.
 Export an RSA public/private key pair. The pbOutput buffer
BCRYPT_RSAPRIVATE_BLOB receives a BCRYPT_RSAKEY_BLOB structure immediately
followed by the key data.

Export an RSA public key. The pbOutput buffer receives a

BCRYPT_RSAPUBLIC_BLOB BCRYPT_RSAKEY_BLOB structure immediately followed by
the key data.

Export a legacy Diffie-Hellman Version 3 Private Key BLOB

LEGACY_DH_PRIVATE_BLOB that contains a Diffie-Hellman public/private key pair that
can be imported by using CryptoAPI.

Export a legacy Diffie-Hellman Version 3 Public Key BLOB

LEGACY_DH_PUBLIC_BLOB that contains a Diffie-Hellman public key that can be
imported by using CryptoAPI.

Export a DSA public/private key pair in a form that can be

LEGACY_DSA_PRIVATE_BLOB imported by using CryptoAPI.

Export a DSA public key in a form that can be imported by

LEGACY_DSA_PUBLIC_BLOB using CryptoAPI.

Export a DSA version 2 private key in a form that can be

LEGACY_DSA_V2_PRIVATE_BLOB imported by using CryptoAPI.

Export an RSA public/private key pair in a form that can be

LEGACY_RSAPRIVATE_BLOB imported by using CryptoAPI.

Export an RSA public key in a form that can be imported by

LEGACY_RSAPUBLIC_BLOB using CryptoAPI.

[out] pbOutput

The address of a buffer that receives the key BLOB. The cbOutput parameter contains the size of this buffer. If
this parameter is NULL , this function will place the required size, in bytes, in the ULONG pointed to by the
pcbResult parameter.
[in] cbOutput

Contains the size, in bytes, of the pbOutput buffer.

[out] pcbResult

A pointer to a ULONG that receives the number of bytes that were copied to the pbOutput buffer. If the
pbOutput parameter is NULL , this function will place the required size, in bytes, in the ULONG pointed to by
this parameter.
[in] dwFlags

A set of flags that modify the behavior of this function. No flags are defined for this function.

Return value
Returns a status code that indicates the success or failure of the function.
Possible return codes include, but are not limited to, the following.
 RET URN C O DE DESC RIP T IO N

The function was successful.

STATUS_SUCCESS

The size specified by the cbOutput parameter is not large

STATUS_BUFFER_TOO_SMALL enough to hold the ciphertext.

The key handle in the hKey parameter is not valid.

STATUS_INVALID_HANDLE

One or more parameters are not valid.

STATUS_INVALID_PARAMETER

The specified BLOB type is not supported by the provider.

STATUS_NOT_SUPPORTED

Remarks
Depending on what processor modes a provider supports, BCr yptExpor tKey can be called either from user
mode or kernel mode. Kernel mode callers can execute either at PASSIVE_LEVEL IRQL or DISPATCH_LEVEL
IRQL. If the current IRQL level is DISPATCH_LEVEL , the handle provided in the hKey parameter must be derived
from an algorithm handle returned by a provider that was opened with the BCRYPT_PROV_DISPATCH flag,
and any pointers passed to the BCr yptExpor tKey function must refer to nonpaged (or locked) memory.
To call this function in kernel mode, use Cng.lib, which is part of the Driver Development Kit (DDK). Windows
Ser ver 2008 and Windows Vista: To call this function in kernel mode, use Ksecdd.lib.

Requirements

Minimum suppor ted client Windows Vista [desktop apps | UWP apps]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps | UWP apps]

Target Platform Windows

Header bcrypt.h

Librar y Bcrypt.lib

DLL Bcrypt.dll

See also
BCryptImportKey
BCryptImportKeyPair
 BCryptFinalizeKeyPair function (bcrypt.h)
7/2/2022 • 2 minutes to read • Edit Online

The BCr yptFinalizeKeyPair function completes a public/private key pair. The key cannot be used until this
function has been called. After this function has been called, the BCryptSetProperty function can no longer be
used for this key.

Syntax
NTSTATUS BCryptFinalizeKeyPair(
[in, out] BCRYPT_KEY_HANDLE hKey,
[in] ULONG dwFlags
);

Parameters
[in, out] hKey

The handle of the key to complete. This handle is obtained by calling the BCryptGenerateKeyPair function.
[in] dwFlags

A set of flags that modify the behavior of this function. No flags are currently defined, so this parameter should
be zero.

Return value
Returns a status code that indicates the success or failure of the function.
Possible return codes include, but are not limited to, the following.

RET URN C O DE DESC RIP T IO N

The function was successful.

STATUS_SUCCESS

The key handle in the hKey parameter is not valid.

STATUS_INVALID_HANDLE

One or more parameters are not valid.

STATUS_INVALID_PARAMETER

The specified provider does not support asymmetric key

STATUS_NOT_SUPPORTED encryption.

Remarks
Depending on what processor modes a provider supports, BCr yptFinalizeKeyPair can be called either from
user mode or kernel mode. Kernel mode callers can execute either at PASSIVE_LEVEL IRQL or
DISPATCH_LEVEL IRQL. If the current IRQL level is DISPATCH_LEVEL , the handle provided in the hKey
parameter must be derived from an algorithm handle returned by a provider that was opened with the
BCRYPT_PROV_DISPATCH flag.
To call this function in kernel mode, use Cng.lib, which is part of the Driver Development Kit (DDK). Windows
Ser ver 2008 and Windows Vista: To call this function in kernel mode, use Ksecdd.lib.

Requirements

Minimum suppor ted client Windows Vista [desktop apps | UWP apps]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps | UWP apps]

Target Platform Windows

Header bcrypt.h

Librar y Bcrypt.lib

DLL Bcrypt.dll

See also
BCryptGenerateKeyPair
 BCryptFinishHash function (bcrypt.h)
7/2/2022 • 2 minutes to read • Edit Online

The BCr yptFinishHash function retrieves the hash or Message Authentication Code (MAC) value for the data
accumulated from prior calls to BCryptHashData.

Syntax
NTSTATUS BCryptFinishHash(
[in, out] BCRYPT_HASH_HANDLE hHash,
[out] PUCHAR pbOutput,
[in] ULONG cbOutput,
[in] ULONG dwFlags
);

Parameters
[in, out] hHash

The handle of the hash or MAC object to use to compute the hash or MAC. This handle is obtained by calling the
BCryptCreateHash function. After this function has been called, the hash handle passed to this function cannot
be used again except in a call to BCryptDestroyHash.
[out] pbOutput

A pointer to a buffer that receives the hash or MAC value. The cbOutput parameter contains the size of this
buffer.
[in] cbOutput

The size, in bytes, of the pbOutput buffer. This size must exactly match the size of the hash or MAC value.
The size can be obtained by calling the BCryptGetProperty function to get the BCRYPT_HASH_LENGTH
property. This will provide the size of the hash or MAC value for the specified algorithm.
[in] dwFlags

A set of flags that modify the behavior of this function. No flags are currently defined, so this parameter should
be zero.

Return value
Returns a status code that indicates the success or failure of the function.
Possible return codes include, but are not limited to, the following.

RET URN C O DE DESC RIP T IO N

The function was successful.

STATUS_SUCCESS
 The hash handle in the hHash parameter is not valid. After
STATUS_INVALID_HANDLE the BCryptFinishHash function has been called for a hash
handle, that handle cannot be reused.

One or more parameters are not valid. This includes the case
STATUS_INVALID_PARAMETER where cbOutput is not the same size as the hash.

Remarks
Depending on what processor modes a provider supports, BCr yptFinishHash can be called either from user
mode or kernel mode. Kernel mode callers can execute either at PASSIVE_LEVEL IRQL or DISPATCH_LEVEL
IRQL. If the current IRQL level is DISPATCH_LEVEL , the handle provided in the hHash parameter must be
derived from an algorithm handle returned by a provider that was opened by using the
BCRYPT_PROV_DISPATCH flag, and any pointers passed to the BCr yptFinishHash function must refer to
nonpaged (or locked) memory.
To call this function in kernel mode, use Cng.lib, which is part of the Driver Development Kit (DDK). Windows
Ser ver 2008 and Windows Vista: To call this function in kernel mode, use Ksecdd.lib.

Requirements

Minimum suppor ted client Windows Vista [desktop apps | UWP apps]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps | UWP apps]

Target Platform Windows

Header bcrypt.h

Librar y Bcrypt.lib

DLL Bcrypt.dll

See also
BCryptHashData
 BCryptFreeBuffer function (bcrypt.h)
7/2/2022 • 2 minutes to read • Edit Online

The BCr yptFreeBuffer function is used to free memory that was allocated by one of the CNG functions.

Syntax
void BCryptFreeBuffer(
[in] PVOID pvBuffer
);

Parameters
[in] pvBuffer

A pointer to the memory buffer to be freed.

Return value
None

Remarks
BCr yptFreeBuffer must be called in the same processor mode as the BCrypt API function that allocated the
buffer. In addition, if the buffer was allocated at PASSIVE_LEVEL IRQL, it must be freed at that IRQL. If the buffer
was allocated at DISPATCH_LEVEL IRQL, it can be freed at either DISPATCH_LEVEL IRQL or PASSIVE_LEVEL
IRQL.
To call this function in kernel mode, use Cng.lib, which is part of the Driver Development Kit (DDK). Windows
Ser ver 2008 and Windows Vista: To call this function in kernel mode, use Ksecdd.lib.

Requirements

Minimum suppor ted client Windows Vista [desktop apps | UWP apps]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps | UWP apps]

Target Platform Windows

Header bcrypt.h

Librar y Bcrypt.lib

DLL Bcrypt.dll

See also
BCryptEnumContexts
BCryptEnumRegisteredProviders
BCryptQueryProviderRegistration
 BCryptGenerateKeyPair function (bcrypt.h)
7/2/2022 • 2 minutes to read • Edit Online

The BCr yptGenerateKeyPair function creates an empty public/private key pair. After you create a key by using
this function, you can use the BCryptSetProperty function to set its properties; however, the key cannot be used
until the BCryptFinalizeKeyPair function is called.

Syntax
NTSTATUS BCryptGenerateKeyPair(
[in, out] BCRYPT_ALG_HANDLE hAlgorithm,
[out] BCRYPT_KEY_HANDLE *phKey,
[in] ULONG dwLength,
[in] ULONG dwFlags
);

Parameters
[in, out] hAlgorithm

Handle of an algorithm provider that supports signing, asymmetric encryption, or key agreement. This handle
must have been created by using the BCryptOpenAlgorithmProvider function.
[out] phKey

A pointer to a BCRYPT_KEY_HANDLE that receives the handle of the key. This handle is used in subsequent
functions that require a key, such as BCryptEncrypt. This handle must be released when it is no longer needed
by passing it to the BCryptDestroyKey function.
[in] dwLength

The length, in bits, of the key. Algorithm providers have different key size restrictions for each standard
asymmetric algorithm.

A L GO RIT H M IDEN T IF IER M EA N IN G

The key size must be greater than or equal to 512 bits, less
BCRYPT_DH_ALGORITHM than or equal to 4096 bits, and must be a multiple of 64.

Prior to Windows 8, the key size must be greater than or

BCRYPT_DSA_ALGORITHM equal to 512 bits, less than or equal to 1024 bits, and must
be a multiple of 64.
Beginning with Windows 8, the key size must be greater
than or equal to 512 bits, less than or equal to 3072
bits, and must be a multiple of 64. Processing for key
sizes less than or equal to 1024 bits adheres to FIPS
186-2. Processing for key sizes greater than 1024 and
less than or equal to 3072 adheres to FIPS 186-3.

The key size must be 256 bits.

BCRYPT_ECDH_P256_ALGORITHM
 The key size must be 384 bits.
BCRYPT_ECDH_P384_ALGORITHM

The key size must be 521 bits.

BCRYPT_ECDH_P521_ALGORITHM

The key size must be 256 bits.

BCRYPT_ECDSA_P256_ALGORITHM

The key size must be 384 bits.

BCRYPT_ECDSA_P384_ALGORITHM

The key size must be 521 bits.

BCRYPT_ECDSA_P521_ALGORITHM

The key size must be greater than or equal to 512 bits, less
BCRYPT_RSA_ALGORITHM than or equal to 16384 bits, and must be a multiple of 64.

[in] dwFlags

A set of flags that modify the behavior of this function. No flags are currently defined, so this parameter should
be zero.

Return value
Returns a status code that indicates the success or failure of the function.
Possible return codes include, but are not limited to, the following.

RET URN C O DE DESC RIP T IO N

The function was successful.

STATUS_SUCCESS

The algorithm handle in the hAlgorithm parameter is not

STATUS_INVALID_HANDLE valid.

One or more parameters are not valid.

STATUS_INVALID_PARAMETER

The specified provider does not support asymmetric key

STATUS_NOT_SUPPORTED encryption.

Remarks
Depending on what processor modes a provider supports, BCr yptGenerateKeyPair can be called either from
user mode or kernel mode. Kernel mode callers can execute either at PASSIVE_LEVEL IRQL or
DISPATCH_LEVEL IRQL. If the current IRQL level is DISPATCH_LEVEL , the handle provided in the hAlgorithm
parameter must have been opened by using the BCRYPT_PROV_DISPATCH flag, and any pointers passed to
the BCr yptGenerateKeyPair function must refer to nonpaged (or locked) memory.
To call this function in kernel mode, use Cng.lib, which is part of the Driver Development Kit (DDK). Windows
Ser ver 2008 and Windows Vista: To call this function in kernel mode, use Ksecdd.lib.

Requirements

Minimum suppor ted client Windows Vista [desktop apps | UWP apps]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps | UWP apps]

Target Platform Windows

Header bcrypt.h

Librar y Bcrypt.lib

DLL Bcrypt.dll

See also
BCryptDestroyKey
 BCryptGenerateSymmetricKey function (bcrypt.h)
7/2/2022 • 2 minutes to read • Edit Online

The BCr yptGenerateSymmetricKey function creates a key object for use with a symmetrical key encryption
algorithm from a supplied key.

Syntax
NTSTATUS BCryptGenerateSymmetricKey(
[in, out] BCRYPT_ALG_HANDLE hAlgorithm,
[out] BCRYPT_KEY_HANDLE *phKey,
[out, optional] PUCHAR pbKeyObject,
[in] ULONG cbKeyObject,
[in] PUCHAR pbSecret,
[in] ULONG cbSecret,
[in] ULONG dwFlags
);

Parameters
[in, out] hAlgorithm

The handle of an algorithm provider created with the BCryptOpenAlgorithmProvider function. The algorithm
specified when the provider was created must support symmetric key encryption.
[out] phKey

A pointer to a BCRYPT_KEY_HANDLE that receives the handle of the key. This handle is used in subsequent
functions that require a key, such as BCryptEncrypt. This handle must be released when it is no longer needed
by passing it to the BCryptDestroyKey function.
[out, optional] pbKeyObject

A pointer to a buffer that receives the key object. The cbKeyObject parameter contains the size of this buffer. The
required size of this buffer can be obtained by calling the BCryptGetProperty function to get the
BCRYPT_OBJECT_LENGTH property. This will provide the size of the key object for the specified algorithm.
This memory can only be freed after the phKey key handle is destroyed.
If the value of this parameter is NULL and the value of the cbKeyObject parameter is zero, the memory for the
key object is allocated and freed by this function.Windows 7: This memory management functionality is
available beginning with Windows 7.
[in] cbKeyObject

The size, in bytes, of the pbKeyObject buffer.

If the value of this parameter is zero and the value of the pbKeyObject parameter is NULL , the memory for the
key object is allocated and freed by this function.Windows 7: This memory management functionality is
available beginning with Windows 7.
[in] pbSecret

Pointer to a buffer that contains the key from which to create the key object. The cbSecret parameter contains
the size of this buffer. This is normally a hash of a password or some other reproducible data. If the data passed
in exceeds the target key size, the data will be truncated and the excess will be ignored.

Note We strongly recommended that applications pass in the exact number of bytes required by the target key.

[in] cbSecret

The size, in bytes, of the pbSecret buffer.

[in] dwFlags

A set of flags that modify the behavior of this function. No flags are currently defined, so this parameter should
be zero.

Return value
Returns a status code that indicates the success or failure of the function.
Possible return codes include, but are not limited to, the following.

RET URN C O DE DESC RIP T IO N

The function was successful.

STATUS_SUCCESS

The size of the key object specified by the cbKeyObject

STATUS_BUFFER_TOO_SMALL parameter is not large enough to hold the key object.

The algorithm handle in the hAlgorithm parameter is not

STATUS_INVALID_HANDLE valid.

One or more parameters are not valid.

STATUS_INVALID_PARAMETER

Remarks
Depending on what processor modes a provider supports, BCr yptGenerateSymmetricKey can be called
either from user mode or kernel mode. Kernel mode callers can execute either at PASSIVE_LEVEL IRQL or
DISPATCH_LEVEL IRQL. If the current IRQL level is DISPATCH_LEVEL , the handle provided in the hAlgorithm
parameter must have been opened by using the BCRYPT_PROV_DISPATCH flag, and any pointers passed to
the BCr yptGenerateSymmetricKey function must refer to nonpaged (or locked) memory.
To call this function in kernel mode, use Cng.lib, which is part of the Driver Development Kit (DDK). Windows
Ser ver 2008 and Windows Vista: To call this function in kernel mode, use Ksecdd.lib.

Requirements

Minimum suppor ted client Windows Vista [desktop apps | UWP apps]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps | UWP apps]
 Target Platform Windows

Header bcrypt.h

Librar y Bcrypt.lib

DLL Bcrypt.dll

See also
BCryptDestroyKey
 BCryptGenRandom function (bcrypt.h)
7/2/2022 • 2 minutes to read • Edit Online

The BCr yptGenRandom function generates a random number.

Syntax
NTSTATUS BCryptGenRandom(
[in, out] BCRYPT_ALG_HANDLE hAlgorithm,
[in, out] PUCHAR pbBuffer,
[in] ULONG cbBuffer,
[in] ULONG dwFlags
);

Parameters
[in, out] hAlgorithm

The handle of an algorithm provider created by using the BCryptOpenAlgorithmProvider function. The
algorithm that was specified when the provider was created must support the random number generator
interface.
[in, out] pbBuffer

The address of a buffer that receives the random number. The size of this buffer is specified by the cbBuffer
parameter.
[in] cbBuffer

The size, in bytes, of the pbBuffer buffer.

[in] dwFlags

A set of flags that modify the behavior of this function. This parameter can be zero or the following value.

VA L UE M EA N IN G

This function will use the number in the pbBuffer buffer as

BCRYPT_RNG_USE_ENTROPY_IN_BUFFER additional entropy for the random number. If this flag is not
0x00000001 specified, this function will use a random number for the
entropy.
Windows 8 and later : This flag is ignored in
Windows 8 and later.

Use the system-preferred random number generator

BCRYPT_USE_SYSTEM_PREFERRED_RNG algorithm. The hAlgorithm parameter must be NULL .
0x00000002
BCRYPT_USE_SYSTEM_PREFERRED_RNG is only
supported at PASSIVE_LEVEL IRQL. For more
information, see Remarks.
Windows Vista: This flag is not supported without
SP2.
Return value
Returns a status code that indicates the success or failure of the function.
Possible return codes include, but are not limited to, the following.

RET URN C O DE DESC RIP T IO N

The function was successful.

STATUS_SUCCESS

The handle in the hAlgorithm parameter is not valid.

STATUS_INVALID_HANDLE

One or more parameters are not valid.

STATUS_INVALID_PARAMETER

Remarks
The default random number provider implements an algorithm for generating random numbers that complies
with the NIST SP800-90 standard, specifically the CTR_DRBG portion of that standard.
Windows Vista: Prior to Windows Vista with Service Pack 1 (SP1) the default random number provider
implements an algorithm for generating random numbers that complies with the FIPS 186-2 standard.
Depending on what processor modes a provider supports, BCr yptGenRandom can be called either from user
mode or kernel mode. Kernel mode callers can execute either at PASSIVE_LEVEL IRQL or DISPATCH_LEVEL
IRQL. If the current IRQL level is DISPATCH_LEVEL , the handle provided in the hAlgorithm parameter must
have been opened by using the BCRYPT_PROV_DISPATCH flag, and any pointers passed to the
BCr yptGenRandom function must refer to nonpaged (or locked) memory.Windows Vista: The Microsoft
provider does not support calling at DISPATCH_LEVEL .
To call this function in kernel mode, use Cng.lib, which is part of the Driver Development Kit (DDK). Windows
Ser ver 2008 and Windows Vista: To call this function in kernel mode, use Ksecdd.lib.

Requirements

Minimum suppor ted client Windows Vista [desktop apps | UWP apps]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps | UWP apps]

Target Platform Windows

Header bcrypt.h

Librar y Bcrypt.lib

DLL Bcrypt.dll
 BCryptGetFipsAlgorithmMode function (bcrypt.h)
7/2/2022 • 2 minutes to read • Edit Online

The BCr yptGetFipsAlgorithmMode function determines whether Federal Information Processing Standard
(FIPS) compliance is enabled.

Syntax
NTSTATUS BCryptGetFipsAlgorithmMode(
[out] BOOLEAN *pfEnabled
);

Parameters
[out] pfEnabled

The address of a BOOLEAN variable that receives zero if FIPS compliance is not enabled, or a nonzero value if
FIPS compliance is enabled.

Return value
Returns a status code that indicates the success or failure of the function.
Possible return codes include, but are not limited to, the following.

RET URN C O DE DESC RIP T IO N

The function was successful.

STATUS_SUCCESS

The pfEnabled parameter is not valid.

STATUS_INVALID_PARAMETER

Remarks
BCr yptGetFipsAlgorithmMode can be called either from user mode or kernel mode. Kernel mode callers
must be executing at PASSIVE_LEVEL IRQL.

Requirements

Minimum suppor ted client Windows Vista [desktop apps | UWP apps]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps | UWP apps]

Target Platform Windows

Header bcrypt.h

Librar y Bcrypt.lib

DLL Bcrypt.dll
 BCryptGetProperty function (bcrypt.h)
7/2/2022 • 2 minutes to read • Edit Online

The BCr yptGetProper ty function retrieves the value of a named property for a CNG object.

Syntax
NTSTATUS BCryptGetProperty(
[in] BCRYPT_HANDLE hObject,
[in] LPCWSTR pszProperty,
[out] PUCHAR pbOutput,
[in] ULONG cbOutput,
[out] ULONG *pcbResult,
[in] ULONG dwFlags
);

Parameters
[in] hObject

A handle that represents the CNG object to obtain the property value for.
[in] pszProperty

A pointer to a null-terminated Unicode string that contains the name of the property to retrieve. This can be one
of the predefined Cryptography Primitive Property Identifiers or a custom property identifier.
[out] pbOutput

The address of a buffer that receives the property value. The cbOutput parameter contains the size of this buffer.
[in] cbOutput

The size, in bytes, of the pbOutput buffer.

[out] pcbResult

A pointer to a ULONG variable that receives the number of bytes that were copied to the pbOutput buffer. If the
pbOutput parameter is NULL , this function will place the required size, in bytes, in the location pointed to by
this parameter.
[in] dwFlags

A set of flags that modify the behavior of this function. No flags are defined for this function.

Return value
Returns a status code that indicates the success or failure of the function.
Possible return codes include, but are not limited to, the following.

RET URN C O DE DESC RIP T IO N

 The function was successful.
STATUS_SUCCESS

The buffer size specified by the cbOutput parameter is not

STATUS_BUFFER_TOO_SMALL large enough to hold the property value.

The handle in the hObject parameter is not valid.

STATUS_INVALID_HANDLE

One or more parameters are not valid.

STATUS_INVALID_PARAMETER

The named property specified by the pszProperty parameter

STATUS_NOT_SUPPORTED is not supported.

Remarks
To obtain the required size for a property, pass NULL for the pbOutput parameter. This function will place the
required size, in bytes, in the value pointed to by the pcbResult parameter.
Depending on what processor modes a provider supports, BCr yptGetProper ty can be called either from user
mode or kernel mode. Kernel mode callers can execute either at PASSIVE_LEVEL IRQL or DISPATCH_LEVEL
IRQL. If the current IRQL level is DISPATCH_LEVEL , any pointers passed to the BCr yptGetProper ty function
must refer to nonpaged (or locked) memory. If the object specified in the hObject parameter is a handle, it must
have been opened by using the BCRYPT_PROV_DISPATCH flag.
To call this function in kernel mode, use Cng.lib, which is part of the Driver Development Kit (DDK). Windows
Ser ver 2008 and Windows Vista: To call this function in kernel mode, use Ksecdd.lib.

Requirements

Minimum suppor ted client Windows Vista [desktop apps | UWP apps]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps | UWP apps]

Target Platform Windows

Header bcrypt.h

Librar y Bcrypt.lib

DLL Bcrypt.dll
 BCryptHash function (bcrypt.h)
7/2/2022 • 2 minutes to read • Edit Online

Performs a single hash computation. This is a convenience function that wraps calls to BCryptCreateHash,
BCryptHashData, BCryptFinishHash, and BCryptDestroyHash.

Syntax
NTSTATUS BCryptHash(
BCRYPT_ALG_HANDLE hAlgorithm,
PUCHAR pbSecret,
ULONG cbSecret,
PUCHAR pbInput,
ULONG cbInput,
PUCHAR pbOutput,
ULONG cbOutput
);

Parameters
hAlgorithm

The handle of an algorithm provider created by using the BCryptOpenAlgorithmProvider function. The
algorithm that was specified when the provider was created must support the hash interface.
pbSecret

A pointer to a buffer that contains the key to use for the hash or MAC. The cbSecret parameter contains the size
of this buffer. This key only applies to hash algorithms opened by the BCryptOpenAlgorithmProvider function by
using the BCRYPT_ALG_HANDLE_HMAC flag. Otherwise, set this parameter to NULL
cbSecret

The size, in bytes, of the pbSecret buffer. If no key is used, set this parameter to zero.
pbInput

A pointer to a buffer that contains the data to process. The cbInput parameter contains the number of bytes in
this buffer. This function does not modify the contents of this buffer.
cbInput

The number of bytes in the pbInput buffer.

pbOutput

A pointer to a buffer that receives the hash or MAC value. The cbOutput parameter contains the size of this
buffer.
cbOutput

The size, in bytes, of the pbOutput buffer. This size must exactly match the size of the hash or MAC value.
The size can be obtained by calling the BCryptGetProperty function to get the BCRYPT_HASH_LENGTH
property. This will provide the size of the hash or MAC value for the specified algorithm.
Return value
A status code indicating success or failure.

Requirements

Minimum suppor ted client Windows 10 [desktop apps | UWP apps]

Minimum suppor ted ser ver Windows Server 2016 [desktop apps | UWP apps]

Target Platform Windows

Header bcrypt.h

Librar y Bcrypt.lib

DLL Bcrypt.dll
 BCryptHashData function (bcrypt.h)
7/2/2022 • 2 minutes to read • Edit Online

The BCr yptHashData function performs a one way hash or Message Authentication Code (MAC) on a data
buffer.

Syntax
NTSTATUS BCryptHashData(
[in, out] BCRYPT_HASH_HANDLE hHash,
[in] PUCHAR pbInput,
[in] ULONG cbInput,
[in] ULONG dwFlags
);

Parameters
[in, out] hHash

The handle of the hash or MAC object to use to perform the operation. This handle is obtained by calling the
BCryptCreateHash function.
[in] pbInput

A pointer to a buffer that contains the data to process. The cbInput parameter contains the number of bytes in
this buffer. This function does not modify the contents of this buffer.
[in] cbInput

The number of bytes in the pbInput buffer.

[in] dwFlags

A set of flags that modify the behavior of this function. No flags are currently defined, so this parameter should
be zero.

Return value
Returns a status code that indicates the success or failure of the function.
Possible return codes include, but are not limited to, the following.

RET URN C O DE DESC RIP T IO N

The function was successful.

STATUS_SUCCESS

One or more parameters are not valid.

STATUS_INVALID_PARAMETER
 The hash handle in the hHash parameter is not valid. After
STATUS_INVALID_HANDLE the BCryptFinishHash function has been called for a hash
handle, that handle cannot be reused.

Remarks
To combine more than one buffer into the hash or MAC, you can call this function multiple times, passing a
different buffer each time. To obtain the hash or MAC value, call the BCryptFinishHash function. After the
BCr yptFinishHash function has been called for a specified handle, that handle cannot be reused.
Depending on what processor modes a provider supports, BCr yptHashData can be called either from user
mode or kernel mode. Kernel mode callers can execute either at PASSIVE_LEVEL IRQL or DISPATCH_LEVEL
IRQL. If the current IRQL level is DISPATCH_LEVEL , the handle provided in the hHash parameter must be
derived from an algorithm handle returned by a provider that was opened by using the
BCRYPT_PROV_DISPATCH flag, and any pointers passed to the BCr yptHashData function must refer to
nonpaged (or locked) memory.
To call this function in kernel mode, use Cng.lib, which is part of the Driver Development Kit (DDK). Windows
Ser ver 2008 and Windows Vista: To call this function in kernel mode, use Ksecdd.lib.

Requirements

Minimum suppor ted client Windows Vista [desktop apps | UWP apps]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps | UWP apps]

Target Platform Windows

Header bcrypt.h

Librar y Bcrypt.lib

DLL Bcrypt.dll

See also
BCryptCreateHash
BCryptFinishHash
 BCryptImportKey function (bcrypt.h)
7/2/2022 • 3 minutes to read • Edit Online

The BCr yptImpor tKey function imports a symmetric key from a key BLOB. The BCryptImportKeyPair function
is used to import a public/private key pair.

Syntax
NTSTATUS BCryptImportKey(
[in] BCRYPT_ALG_HANDLE hAlgorithm,
[in, optional] BCRYPT_KEY_HANDLE hImportKey,
[in] LPCWSTR pszBlobType,
[out] BCRYPT_KEY_HANDLE *phKey,
[out, optional] PUCHAR pbKeyObject,
[in] ULONG cbKeyObject,
[in] PUCHAR pbInput,
[in] ULONG cbInput,
[in] ULONG dwFlags
);

Parameters
[in] hAlgorithm

The handle of the algorithm provider to import the key. This handle is obtained by calling the
BCryptOpenAlgorithmProvider function.
[in, optional] hImportKey

The handle of the key encryption key needed to unwrap the key BLOB in the pbInput parameter.

Note The handle must be supplied by the same provider that supplied the key that is being imported.

Windows Ser ver 2008 and Windows Vista: This parameter is not used and should be set to NULL .
[in] pszBlobType

A null-terminated Unicode string that contains an identifier that specifies the type of BLOB that is contained in
the pbInput buffer. This can be one of the following values.

VA L UE M EA N IN G

Import a symmetric key from an AES key–wrapped key

BCRYPT_AES_WRAP_KEY_BLOB BLOB. The hImportKey parameter must reference a valid
BCRYPT_KEY_HANDLE pointer to the key encryption key.
Windows Ser ver 2008 and Windows Vista: This
BLOB type is not supported.
 Import a symmetric key from a data BLOB. The pbInput
BCRYPT_KEY_DATA_BLOB parameter is a pointer to a
BCRYPT_KEY_DATA_BLOB_HEADER structure immediately
followed by the key BLOB.

Import a symmetric key BLOB in a format that is specific to a

BCRYPT_OPAQUE_KEY_BLOB single CSP. Opaque BLOBs are not transferable and must be
imported by using the same CSP that generated the BLOB.
Opaque BLOBs are only intended to be used for interprocess
transfer of keys and are not suitable to be persisted and
read in across versions of a provider.

[out] phKey

A pointer to a BCRYPT_KEY_HANDLE that receives the handle of the imported key. This handle is used in
subsequent functions that require a key, such as BCryptEncrypt. This handle must be released when it is no
longer needed by passing it to the BCryptDestroyKey function.
[out, optional] pbKeyObject

A pointer to a buffer that receives the imported key object. The cbKeyObject parameter contains the size of this
buffer. The required size of this buffer can be obtained by calling the BCryptGetProperty function to get the
BCRYPT_OBJECT_LENGTH property. This will provide the size of the key object for the specified algorithm.
This memory can only be freed after the phKey key handle is destroyed.
[in] cbKeyObject

The size, in bytes, of the pbKeyObject buffer.

[in] pbInput

The address of a buffer that contains the key BLOB to import. The cbInput parameter contains the size of this
buffer. The pszBlobType parameter specifies the type of key BLOB this buffer contains.
[in] cbInput

The size, in bytes, of the pbInput buffer.

[in] dwFlags

A set of flags that modify the behavior of this function. No flags are currently defined, so this parameter should
be zero.

Return value
Returns a status code that indicates the success or failure of the function.
Possible return codes include, but are not limited to, the following.

RET URN C O DE DESC RIP T IO N

The function was successful.

STATUS_SUCCESS

The size of the key object specified by the cbKeyObject

STATUS_BUFFER_TOO_SMALL parameter is not large enough to hold the key object.
 The algorithm handle in the hAlgorithm parameter is not
STATUS_INVALID_HANDLE valid.

One or more parameters are not valid.

STATUS_INVALID_PARAMETER

The algorithm provider specified by the hAlgorithm

STATUS_NOT_SUPPORTED parameter does not support the BLOB type specified by the
pszBlobType parameter.

Remarks
Depending on what processor modes a provider supports, BCr yptImpor tKey can be called either from user
mode or kernel mode. Kernel mode callers can execute either at PASSIVE_LEVEL IRQL or DISPATCH_LEVEL
IRQL. If the current IRQL level is DISPATCH_LEVEL , the handle provided in the hAlgorithm parameter must
have been opened by using the BCRYPT_PROV_DISPATCH flag, and any pointers passed to the
BCr yptImpor tKey function must refer to nonpaged (or locked) memory.
To call this function in kernel mode, use Cng.lib, which is part of the Driver Development Kit (DDK). Windows
Ser ver 2008 and Windows Vista: To call this function in kernel mode, use Ksecdd.lib.

Requirements

Minimum suppor ted client Windows Vista [desktop apps | UWP apps]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps | UWP apps]

Target Platform Windows

Header bcrypt.h

Librar y Bcrypt.lib

DLL Bcrypt.dll

See also
BCryptDestroyKey
BCryptExportKey
BCryptImportKeyPair
 BCryptImportKeyPair function (bcrypt.h)
7/2/2022 • 4 minutes to read • Edit Online

The BCr yptImpor tKeyPair function imports a public/private key pair from a key BLOB. The BCryptImportKey
function is used to import a symmetric key pair.

Syntax
NTSTATUS BCryptImportKeyPair(
[in] BCRYPT_ALG_HANDLE hAlgorithm,
[in, out] BCRYPT_KEY_HANDLE hImportKey,
[in] LPCWSTR pszBlobType,
[out] BCRYPT_KEY_HANDLE *phKey,
[in] PUCHAR pbInput,
[in] ULONG cbInput,
[in] ULONG dwFlags
);

Parameters
[in] hAlgorithm

The handle of the algorithm provider to import the key. This handle is obtained by calling the
BCryptOpenAlgorithmProvider function.
[in, out] hImportKey

This parameter is not currently used and should be NULL .

[in] pszBlobType

A null-terminated Unicode string that contains an identifier that specifies the type of BLOB that is contained in
the pbInput buffer. This can be one of the following values.

VA L UE M EA N IN G

The BLOB is a Diffie-Hellman public/private key pair BLOB.

BCRYPT_DH_PRIVATE_BLOB The pbInput buffer must contain a BCRYPT_DH_KEY_BLOB
structure immediately followed by the key data.

The BLOB is a Diffie-Hellman public key BLOB. The pbInput

BCRYPT_DH_PUBLIC_BLOB buffer must contain a BCRYPT_DH_KEY_BLOB structure
immediately followed by the key data.

The BLOB is a DSA public/private key pair BLOB. The pbInput

BCRYPT_DSA_PRIVATE_BLOB buffer must contain a BCRYPT_DSA_KEY_BLOB or
BCRYPT_DSA_KEY_BLOB_V2 structure immediately followed
by the key data. BCRYPT_DSA_KEY_BLOB is used for key
lengths from 512 to 1024 bits.
BCRYPT_DSA_KEY_BLOB_V2 is used for key lengths that
exceed 1024 bits but are less than or equal to 3072 bits.
Windows 8: Support for BCRYPT_DSA_KEY_BLOB_V2
begins.
 The BLOB is a DSA public key BLOB. The pbInput buffer must
BCRYPT_DSA_PUBLIC_BLOB contain a BCRYPT_DSA_KEY_BLOB or
BCRYPT_DSA_KEY_BLOB_V2 structure immediately followed
by the key data. BCRYPT_DSA_KEY_BLOB is used for key
lengths from 512 to 1024 bits.
BCRYPT_DSA_KEY_BLOB_V2 is used for key lengths that
exceed 1024 bits but are less than or equal to 3072 bits.
Windows 8: Support for BCRYPT_DSA_KEY_BLOB_V2
begins.

The BLOB is an elliptic curve cryptography (ECC) private key.

BCRYPT_ECCPRIVATE_BLOB The pbInput buffer must contain a BCRYPT_ECCKEY_BLOB
structure immediately followed by the key data.

The BLOB is an ECC public key. The pbInput buffer must

BCRYPT_ECCPUBLIC_BLOB contain a BCRYPT_ECCKEY_BLOB structure immediately
followed by the key data.

The BLOB is a generic public key of any type. The type of key
BCRYPT_PUBLIC_KEY_BLOB in this BLOB is determined by the Magic member of the
BCRYPT_KEY_BLOB structure.

The BLOB is a generic private key of any type. The private

BCRYPT_PRIVATE_KEY_BLOB key does not necessarily contain the public key. The type of
key in this BLOB is determined by the Magic member of the
BCRYPT_KEY_BLOB structure.

The BLOB is an RSA public/private key pair BLOB. The

BCRYPT_RSAPRIVATE_BLOB pbInput buffer must contain a BCRYPT_RSAKEY_BLOB
structure immediately followed by the key data.

The BLOB is an RSA public key BLOB. The pbInput buffer

BCRYPT_RSAPUBLIC_BLOB must contain a BCRYPT_RSAKEY_BLOB structure immediately
followed by the key data.

The BLOB is a Diffie-Hellman public key BLOB that was

LEGACY_DH_PUBLIC_BLOB exported by using CryptoAPI. The Microsoft primitive
provider does not support importing this BLOB type.

The BLOB is a legacy Diffie-Hellman Version 3 Private Key

LEGACY_DH_PRIVATE_BLOB BLOB that contains a Diffie-Hellman public/private key pair
that was exported by using CryptoAPI.

The BLOB is a DSA public/private key pair BLOB that was

LEGACY_DSA_PRIVATE_BLOB exported by using CryptoAPI.

The BLOB is a DSA public key BLOB that was exported by

LEGACY_DSA_PUBLIC_BLOB using CryptoAPI. The Microsoft primitive provider does not
support importing this BLOB type.

The BLOB is a DSA version 2 private key in a form that can

LEGACY_DSA_V2_PRIVATE_BLOB be imported by using CryptoAPI.

The BLOB is an RSA public/private key pair BLOB that was

LEGACY_RSAPRIVATE_BLOB exported by using CryptoAPI.
 The BLOB is an RSA public key BLOB that was exported by
LEGACY_RSAPUBLIC_BLOB using CryptoAPI. The Microsoft primitive provider does not
support importing this BLOB type.

[out] phKey

A pointer to a BCRYPT_KEY_HANDLE that receives the handle of the imported key. This handle is used in
subsequent functions that require a key, such as BCryptSignHash. This handle must be released when it is no
longer needed by passing it to the BCryptDestroyKey function.
[in] pbInput

The address of a buffer that contains the key BLOB to import. The cbInput parameter contains the size of this
buffer. The pszBlobType parameter specifies the type of key BLOB this buffer contains.
[in] cbInput

The size, in bytes, of the pbInput buffer.

[in] dwFlags

A set of flags that modify the behavior of this function. This can be zero or the following value.

VA L UE M EA N IN G

Do not validate the public portion of the key pair.

BCRYPT_NO_KEY_VALIDATION

Return value
Returns a status code that indicates the success or failure of the function.
Possible return codes include, but are not limited to, the following.

RET URN C O DE DESC RIP T IO N

The function was successful.

STATUS_SUCCESS

The algorithm handle in the hAlgorithm parameter is not

STATUS_INVALID_HANDLE valid.

One or more parameters are not valid.

STATUS_INVALID_PARAMETER

The algorithm provider specified by the hAlgorithm

STATUS_NOT_SUPPORTED parameter does not support the BLOB type specified by the
pszBlobType parameter.

Remarks
Depending on what processor modes a provider supports, BCr yptImpor tKeyPair can be called either from
user mode or kernel mode. Kernel mode callers can execute either at PASSIVE_LEVEL IRQL or
DISPATCH_LEVEL IRQL. If the current IRQL level is DISPATCH_LEVEL , the handle provided in the hAlgorithm
parameter must have been opened by using the BCRYPT_PROV_DISPATCH flag, and any pointers passed to
the BCr yptImpor tKeyPair function must refer to nonpaged (or locked) memory.
To call this function in kernel mode, use Cng.lib, which is part of the Driver Development Kit (DDK). Windows
Ser ver 2008 and Windows Vista: To call this function in kernel mode, use Ksecdd.lib.

Requirements

Minimum suppor ted client Windows Vista [desktop apps | UWP apps]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps | UWP apps]

Target Platform Windows

Header bcrypt.h

Librar y Bcrypt.lib

DLL Bcrypt.dll

See also
BCryptDestroyKey
BCryptExportKey
BCryptImportKey
 BCryptKeyDerivation function (bcrypt.h)
7/2/2022 • 2 minutes to read • Edit Online

The BCr yptKeyDerivation function derives a key without requiring a secret agreement. It is similar in
functionality to BCryptDeriveKey but does not require a BCRYPT_SECRET_HANDLE value as input.

Syntax
NTSTATUS BCryptKeyDerivation(
[in] BCRYPT_KEY_HANDLE hKey,
[in, optional] BCryptBufferDesc *pParameterList,
[out] PUCHAR pbDerivedKey,
[in] ULONG cbDerivedKey,
[out] ULONG *pcbResult,
[in] ULONG dwFlags
);

Parameters
[in] hKey

Handle of the input key.

[in, optional] pParameterList

Pointer to a BCr yptBufferDesc structure that contains the KDF parameters. This parameter is optional and can
be NULL if it is not needed. The parameters can be specific to a key derivation function (KDF) or generic. The
following table shows the required and optional parameters for specific KDFs implemented by the Microsoft
Primitive provider.

K DF PA RA M ET ER REQ UIRED

SP800-108 HMAC in counter mode KDF_LABEL yes

KDF_CONTEXT yes

KDF_HASH_ALGORITHM yes

SP800-56A KDF_ALGORITHMID yes

KDF_PARTYUINFO yes

KDF_PARTYVINFO yes

KDF_HASH_ALGORITHM yes

KDF_SUPPPUBINFO no

KDF_SUPPPRIVINFO no

PBKDF2 KDF_HASH_ALGORITHM yes

 KDF_SALT yes

KDF_ITERATION_COUNT no

CAPI_KDF KDF_HASH_ALGORITHM yes

The following generic parameter can be used:

KDF_GENERIC_PARAMETER
Generic parameters map to KDF specific parameters in the following manner:
SP800-108 HMAC in counter mode:
KDF_GENERIC_PARAMETER = KDF_LABEL||0x00||KDF_CONTEXT
SP800-56A
KDF_GENERIC_PARAMETER = KDF_ALGORITHMID || KDF_PARTYUINFO || KDF_PARTYVINFO {||
KDF_SUPPPUBINFO } {|| KDF_SUPPPRIVINFO }
PBKDF2
KDF_GENERIC_PARAMETER = KDF_SALT
KDF_ITERATION_COUNT – defaults to 10000
CAPI_KDF
KDF_GENERIC_PARAMETER = Not Used
[out] pbDerivedKey

Address of a buffer that receives the key. The cbDerivedKey parameter contains the size of this buffer.
[in] cbDerivedKey

Size, in bytes, of the buffer pointed to by the pbDerivedKey parameter.

[out] pcbResult

Pointer to a variable that receives the number of bytes that were copied to the buffer pointed to by the
pbDerivedKey parameter.
[in] dwFlags

Flags that modify the behavior of this function. The following value can be used with the Microsoft Primitive
provider.

VA L UE M EA N IN G

Specifies that the target algorithm is AES and that the key
BCRYPT_CAPI_AES_FLAG therefore must be double expanded. This flag is only valid
with the CAPI_KDF algorithm.

Return value
Returns a status code that indicates the success or failure of the function.
Remarks
You can use the following algorithm identifiers in the BCryptOpenAlgorithmProvider function before calling
BCr yptKeyDerivation :
BCRYPT_CAPI_KDF_ALGORITHM
BCRYPT_SP800108_CTR_HMAC_ALGORITHM
BCRYPT_SP80056A_CONCAT_ALGORITHM
BCRYPT_PBKDF2_ALGORITHM
To call this function in kernel mode, use Cng.lib, which is part of the Driver Development Kit (DDK). Windows
Ser ver 2008 and Windows Vista: To call this function in kernel mode, use Ksecdd.lib.

Requirements

Minimum suppor ted client Windows 8 [desktop apps | UWP apps]

Minimum suppor ted ser ver Windows Server 2012 [desktop apps | UWP apps]

Target Platform Windows

Header bcrypt.h

Librar y Bcrypt.lib

DLL Bcrypt.dll

See also
BCryptDeriveKey
NCryptKeyDerivation
 BCryptOpenAlgorithmProvider function (bcrypt.h)
7/2/2022 • 3 minutes to read • Edit Online

The BCr yptOpenAlgorithmProvider function loads and initializes a CNG provider.

Syntax
NTSTATUS BCryptOpenAlgorithmProvider(
[out] BCRYPT_ALG_HANDLE *phAlgorithm,
[in] LPCWSTR pszAlgId,
[in] LPCWSTR pszImplementation,
[in] ULONG dwFlags
);

Parameters
[out] phAlgorithm

A pointer to a BCRYPT_ALG_HANDLE variable that receives the CNG provider handle. When you have finished
using this handle, release it by passing it to the BCryptCloseAlgorithmProvider function.
[in] pszAlgId

A pointer to a null-terminated Unicode string that identifies the requested cryptographic algorithm. This can be
one of the standard CNG Algorithm Identifiers or the identifier for another registered algorithm.
[in] pszImplementation

A pointer to a null-terminated Unicode string that identifies the specific provider to load. This is the registered
alias of the cryptographic primitive provider. This parameter is optional and can be NULL if it is not needed. If
this parameter is NULL , the default provider for the specified algorithm will be loaded.

Note If the pszImplementation parameter value is NULL , CNG attempts to open each registered provider, in order of
priority, for the algorithm specified by the pszAlgId parameter and returns the handle of the first provider that is successfully
opened. For the lifetime of the handle, any BCrypt*** cryptographic APIs will use the provider that was successfully opened.

Windows Ser ver 2008 and Windows Vista: CNG attempts to fall back to the Microsoft CNG provider.
The following are the predefined provider names.

VA L UE M EA N IN G

Identifies the basic Microsoft CNG provider.

MS_PRIMITIVE_PROVIDER
"Microsoft Primitive Provider"

Identifies the TPM key storage provider that is provided by

MS_PL ATFORM_CRYPTO_PROVIDER Microsoft.
L"Microsoft Platform Crypto Provider"

[in] dwFlags
Flags that modify the behavior of the function. This can be zero or a combination of one or more of the
following values.

VA L UE M EA N IN G

The provider will perform the Hash-Based Message

BCRYPT_ALG_HANDLE_HMAC_FL AG Authentication Code (HMAC) algorithm with the specified
hash algorithm. This flag is only used by hash algorithm
providers.

Loads the provider into the nonpaged memory pool. If this

BCRYPT_PROV_DISPATCH flag is not present, the provider is loaded into the paged
memory pool. When this flag is specified, the handle
returned must not be closed before all dependent objects
have been freed.

Note This flag is only supported in kernel mode and

allows subsequent operations on the provider to be
processed at the Dispatch level. If the provider does not
support being called at dispatch level, then it will return an
error when opened using this flag.

Windows Ser ver 2008 and Windows Vista: This flag is

only supported by the Microsoft algorithm providers and
only for hashing algorithms and symmetric key
cryptographic algorithms.

Creates a reusable hashing object. The object can be used

BCRYPT_HASH_REUSABLE_FL AG for a new hashing operation immediately after calling
BCryptFinishHash. For more information, see Creating a
Hash with CNG.
Windows Ser ver 2008 R2, Windows 7, Windows
Ser ver 2008 and Windows Vista: This flag is not
supported.

Return value
Returns a status code that indicates the success or failure of the function.
Possible return codes include, but are not limited to, the following.

RET URN C O DE DESC RIP T IO N

The function was successful.

STATUS_SUCCESS

No provider was found for the specified algorithm ID.

STATUS_NOT_FOUND

One or more parameters are not valid.

STATUS_INVALID_PARAMETER

A memory allocation failure occurred.

STATUS_NO_MEMORY
Remarks
Because of the number and type of operations that are required to find, load, and initialize an algorithm
provider, the BCr yptOpenAlgorithmProvider function is a relatively time intensive function. Because of this,
we recommend that you cache any algorithm provider handles that you will use more than once, rather than
opening and closing the algorithm providers over and over.
BCr yptOpenAlgorithmProvider can be called either from user mode or kernel mode. Kernel mode callers
must be executing at PASSIVE_LEVEL IRQL.
To call this function in kernel mode, use Cng.lib, which is part of the Driver Development Kit (DDK). Windows
Ser ver 2008 and Windows Vista: To call this function in kernel mode, use Ksecdd.lib.
Starting in Windows 10, CNG no longer follows every update to the cryptography configuration. Certain
changes, like adding a new default provider or changing the preference order of algorithm providers, may
require a reboot. Because of this, you should reboot before calling BCr yptOpenAlgorithmProvider with any
newly configured provider.

Requirements

Minimum suppor ted client Windows Vista [desktop apps | UWP apps]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps | UWP apps]

Target Platform Windows

Header bcrypt.h

Librar y Bcrypt.lib

DLL Bcrypt.dll

See also
BCryptCloseAlgorithmProvider
 BCryptProcessMultiOperations function (bcrypt.h)
7/2/2022 • 2 minutes to read • Edit Online

The BCr yptProcessMultiOperations function processes a sequence of operations on a multi-object state.

Syntax
NTSTATUS BCryptProcessMultiOperations(
[in, out] BCRYPT_HANDLE hObject,
[in] BCRYPT_MULTI_OPERATION_TYPE operationType,
[in] PVOID pOperations,
[in] ULONG cbOperations,
[in] ULONG dwFlags
);

Parameters
[in, out] hObject

A handle to a multi-object state, such as one created by the BCryptCreateMultiHash function.

[in] operationType

A BCRYPT_OPERATION_TYPE_* value. Currently the only defined value is

BCRYPT_OPERATION_TYPE_HASH . This value identifies the hObject parameter as a multi-hash object and
the pOperations pointer as pointing to an array of BCRYPT_MULTI_HASH_OPERATION elements.
[in] pOperations

A pointer to an array of operation command structures. For hashing, it is a pointer to an array of

BCRYPT_MULTI_HASH_OPERATION structures.
[in] cbOperations

The size, in bytes, of the pOperations array.

[in] dwFlags

Specify a value of zero (0).

Return value
None

Remarks
Each element of the pOperations array contains instructions for a particular computation to be performed on a
single element of the multi-object state. The functional behavior of BCr yptProcessMultiOperations is
equivalent to performing, for each element in the multi-object state, the computations specified in the
operations array for that element, one at a time, in order.
The relative order of two operations that operate on different elements of the array is not guaranteed. If an
output buffer overlaps an input or output buffer the result is not deterministic.
Requirements

Minimum suppor ted client Windows 8.1 Update [desktop apps | UWP apps]

Minimum suppor ted ser ver Windows Server 2008 Update [desktop apps | UWP apps]

Target Platform Windows

Header bcrypt.h

Librar y Bcrypt.lib

DLL Bcrypt.dll

See also
BCRYPT_MULTI_HASH_OPERATION
BCryptCreateMultiHash
 BCryptQueryContextConfiguration function
(bcrypt.h)
7/2/2022 • 2 minutes to read • Edit Online

[BCr yptQuer yContextConfiguration is available for use in the operating systems specified in the
Requirements section. It may be altered or unavailable in subsequent versions.]
The BCr yptQuer yContextConfiguration function retrieves the current configuration for the specified CNG
context.

Syntax
NTSTATUS BCryptQueryContextConfiguration(
[in] ULONG dwTable,
[in] LPCWSTR pszContext,
[in, out] ULONG *pcbBuffer,
[in, out] PCRYPT_CONTEXT_CONFIG *ppBuffer
);

Parameters
[in] dwTable

Identifies the configuration table that the context exists in. This can be one of the following values.

VA L UE M EA N IN G

The context exists in the local-machine configuration table.

CRYPT_LOCAL

This value is not available for use.

CRYPT_DOMAIN

[in] pszContext

A pointer to a null-terminated Unicode string that contains the identifier of the context to obtain the
configuration information for.
[in, out] pcbBuffer

The address of a ULONG variable that, on entry, contains the size, in bytes, of the buffer pointed to by ppBuffer.
If this size is not large enough to hold the context information, this function will fail with
STATUS_BUFFER_TOO_SMALL .
After this function returns, this variable contains the number of bytes that were copied to the ppBuffer buffer.
[in, out] ppBuffer

The address of a pointer to a CRYPT_CONTEXT_CONFIG structure that receives the context configuration
information retrieved by this function. The value pointed to by the pcbBuffer parameter contains the size of this
buffer.
If the value pointed to by this parameter is NULL , this function will allocate the required memory. This memory
must be freed when it is no longer needed by passing this pointer to the BCryptFreeBuffer function.
If this parameter is NULL , this function will place the required size, in bytes, in the variable pointed to by the
pcbBuffer parameter and return STATUS_BUFFER_TOO_SMALL .
For more information on the usage of this parameter, see Remarks.

Return value
Returns a status code that indicates the success or failure of the function.
Possible return codes include, but are not limited to, the following.

RET URN C O DE DESC RIP T IO N

The function was successful.

STATUS_SUCCESS

The ppBuffer parameter is not NULL , and the value pointed

STATUS_BUFFER_TOO_SMALL to by the pcbBuffer parameter is not large enough to hold
the set of contexts.

One or more parameters are not valid.

STATUS_INVALID_PARAMETER

A memory allocation failure occurred.

STATUS_NO_MEMORY

The specified context could not be found.

STATUS_NOT_FOUND

Remarks
Each context has only one set of configuration information, so although the ppBuffer parameter appears to be a
used as an array, this function treats this as an array with only one element. The following example helps clarify
how this parameter is used.

// Get the configuration information for the context.

CRYPT_CONTEXT_CONFIG config;
ULONG uSize = sizeof(config);
PCRYPT_CONTEXT_CONFIG pConfig = &config;
status = BCryptQueryContextConfiguration(
CRYPT_LOCAL,
pszContextID,
&uSize,
&pConfig);

BCr yptQuer yContextConfiguration can be called only in user mode.

Requirements
Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header bcrypt.h

Librar y Bcrypt.lib

DLL Bcrypt.dll
 BCryptQueryContextFunctionConfiguration
function (bcrypt.h)
7/2/2022 • 3 minutes to read • Edit Online

[BCr yptQuer yContextFunctionConfiguration is available for use in the operating systems specified in the
Requirements section. It may be altered or unavailable in subsequent versions.]
The BCr yptQuer yContextFunctionConfiguration function obtains the cryptographic function configuration
information for an existing CNG context.

Syntax
NTSTATUS BCryptQueryContextFunctionConfiguration(
[in] ULONG dwTable,
[in] LPCWSTR pszContext,
[in] ULONG dwInterface,
[in] LPCWSTR pszFunction,
[in, out] ULONG *pcbBuffer,
[in, out] PCRYPT_CONTEXT_FUNCTION_CONFIG *ppBuffer
);

Parameters
[in] dwTable

Identifies the configuration table that the context exists in. This can be one of the following values.

VA L UE M EA N IN G

The context exists in the local-machine configuration table.

CRYPT_LOCAL

This value is not available for use.

CRYPT_DOMAIN

[in] pszContext

A pointer to a null-terminated Unicode string that contains the identifier of the context to obtain the function
configuration information for.
[in] dwInterface

Identifies the cryptographic interface to obtain the function configuration information for. This can be one of the
following values.

VA L UE M EA N IN G

Obtain the function configuration information from the list

BCRYPT_ASYMMETRIC_ENCRYPTION_INTERFACE of asymmetric encryption functions.
 Obtain the function configuration information from the list
BCRYPT_CIPHER_INTERFACE of cipher functions.

Obtain the function configuration information from the list

BCRYPT_HASH_INTERFACE of hash functions.

Obtain the function configuration information from the list

BCRYPT_RNG_INTERFACE of random number generator functions.

Obtain the function configuration information from the list

BCRYPT_SECRET_AGREEMENT_INTERFACE of secret agreement functions.

Obtain the function configuration information from the list

BCRYPT_SIGNATURE_INTERFACE of signature functions.

Obtain the function configuration information from the list

NCRYPT_KEY_STORAGE_INTERFACE of key storage functions.

Obtain the function configuration information from the list

NCRYPT_SCHANNEL_INTERFACE of Schannel functions.

[in] pszFunction

A pointer to a null-terminated Unicode string that contains the identifier of the cryptographic function to obtain
the configuration information for.
[in, out] pcbBuffer

The address of a ULONG variable that, on entry, contains the size, in bytes, of the buffer pointed to by ppBuffer.
If this size is not large enough to hold the context information, this function will fail with
STATUS_BUFFER_TOO_SMALL .
After this function returns, this variable contains the number of bytes that were copied to the ppBuffer buffer.
[in, out] ppBuffer

The address of a pointer to a CRYPT_CONTEXT_FUNCTION_CONFIG structure that receives the function

configuration information retrieved by this function. The value pointed to by the pcbBuffer parameter contains
the size of this buffer.
If the value pointed to by this parameter is NULL , this function will allocate the required memory. This memory
must be freed when it is no longer needed by passing this pointer to the BCryptFreeBuffer function.
If this parameter is NULL , this function will place the required size, in bytes, in the variable pointed to by the
pcbBuffer parameter and return STATUS_BUFFER_TOO_SMALL .
For more information about the usage of this parameter, see Remarks.

Return value
Returns a status code that indicates the success or failure of the function.
Possible return codes include, but are not limited to, the following.

RET URN C O DE DESC RIP T IO N

 The function was successful.
STATUS_SUCCESS

The ppBuffer parameter is not NULL , and the value pointed

STATUS_BUFFER_TOO_SMALL to by the pcbBuffer parameter is not large enough to hold
the set of contexts.

One or more parameters are not valid.

STATUS_INVALID_PARAMETER

A memory allocation failure occurred.

STATUS_NO_MEMORY

The specified context or function could not be found.

STATUS_NOT_FOUND

Remarks
Each cryptographic function has only one set of configuration information, so although the ppBuffer parameter
appears to be a used as an array, this function treats this as an array with only one element. The following
example helps clarify how this parameter is used.

// Get the function configuration information.

CRYPT_CONTEXT_FUNCTION_CONFIG FuncConfig;
ULONG uSize = sizeof(FuncConfig);
PCRYPT_CONTEXT_FUNCTION_CONFIG pFuncConfig = &FuncConfig;
status = BCryptQueryContextFunctionConfiguration(
CRYPT_LOCAL,
pszContext,
NCRYPT_SCHANNEL_INTERFACE,
pszFunction,
&uSize,
&pFuncConfig);

BCr yptQuer yContextFunctionConfiguration can be called only in user mode.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header bcrypt.h

Librar y Bcrypt.lib

DLL Bcrypt.dll
See also
CRYPT_CONTEXT_FUNCTION_CONFIG
 BCryptQueryContextFunctionProperty function
(bcrypt.h)
7/2/2022 • 2 minutes to read • Edit Online

The BCr yptQuer yContextFunctionProper ty function obtains the value of a named property for a
cryptographic function in an existing CNG context.

Syntax
NTSTATUS BCryptQueryContextFunctionProperty(
[in] ULONG dwTable,
[in] LPCWSTR pszContext,
[in] ULONG dwInterface,
[in] LPCWSTR pszFunction,
[in] LPCWSTR pszProperty,
[in, out] ULONG *pcbValue,
[in, out] PUCHAR *ppbValue
);

Parameters
[in] dwTable

Identifies the configuration table that the context exists in. This can be one of the following values.

VA L UE M EA N IN G

The context exists in the local-machine configuration table.

CRYPT_LOCAL

This value is not available for use.

CRYPT_DOMAIN

[in] pszContext

A pointer to a null-terminated Unicode string that contains the identifier of the context to obtain the function
property from.
[in] dwInterface

Identifies the cryptographic interface that the function exists in. This can be one of the following values.

VA L UE M EA N IN G

The function exists in the list of asymmetric encryption

BCRYPT_ASYMMETRIC_ENCRYPTION_INTERFACE functions.

The function exists in the list of cipher functions.

BCRYPT_CIPHER_INTERFACE
 The function exists in the list of hash functions.
BCRYPT_HASH_INTERFACE

The function exists in the list of random number generator

BCRYPT_RNG_INTERFACE functions.

The function exists in the list of secret agreement functions.

BCRYPT_SECRET_AGREEMENT_INTERFACE

The function exists in the list of signature functions.

BCRYPT_SIGNATURE_INTERFACE

The function exists in the list of key storage functions.

NCRYPT_KEY_STORAGE_INTERFACE

The function exists in the list of Schannel functions.

NCRYPT_SCHANNEL_INTERFACE

[in] pszFunction

A pointer to a null-terminated Unicode string that contains the identifier of the cryptographic function to obtain
the property for.
[in] pszProperty

A pointer to a null-terminated Unicode string that contains the identifier of the property to obtain.
[in, out] pcbValue

The address of a ULONG variable that, on entry, contains the size, in bytes, of the buffer pointed to by ppbValue.
If this size is not large enough to hold the property value, this function will fail with
STATUS_BUFFER_TOO_SMALL .
After this function returns, this variable contains the number of bytes that were copied to the ppbValue buffer.
[in, out] ppbValue

The address of a pointer to a buffer that receives the property data. The size and format of this buffer depends
on the format of the property being retrieved. The value pointed to by the pcbValue parameter contains the size
of this buffer.
If the value pointed to by this parameter is NULL , this function will allocate the required memory. This memory
must be freed when it is no longer needed by passing this pointer to the BCryptFreeBuffer function.
If this parameter is NULL , this function will place the required size, in bytes, in the variable pointed to by the
pcbValue parameter and return STATUS_BUFFER_TOO_SMALL .

Return value
Returns a status code that indicates the success or failure of the function.
Possible return codes include, but are not limited to, the following.

RET URN C O DE DESC RIP T IO N

 The function was successful.
STATUS_SUCCESS

The ppbValue parameter is not NULL , and the value pointed

STATUS_BUFFER_TOO_SMALL to by the pcbValue parameter is not large enough to hold
the set of contexts.

One or more parameters are not valid.

STATUS_INVALID_PARAMETER

A memory allocation failure occurred.

STATUS_NO_MEMORY

The specified context, function, or property could not be

STATUS_NOT_FOUND found.

Remarks
BCr yptQuer yContextFunctionProper ty can be called only in user mode.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header bcrypt.h

Librar y Bcrypt.lib

DLL Bcrypt.dll
 BCryptQueryProviderRegistration function
(bcrypt.h)
7/2/2022 • 2 minutes to read • Edit Online

The BCr yptQuer yProviderRegistration function retrieves information about a CNG provider.

Syntax
NTSTATUS BCryptQueryProviderRegistration(
[in] LPCWSTR pszProvider,
[in] ULONG dwMode,
[in] ULONG dwInterface,
[in, out] ULONG *pcbBuffer,
[in, out] PCRYPT_PROVIDER_REG *ppBuffer
);

Parameters
[in] pszProvider

A pointer to a null-terminated Unicode string that contains the name of the provider to obtain information
about.
[in] dwMode

Specifies the type of information to retrieve. This can be one of the following values.

VA L UE M EA N IN G

Retrieve any information for the provider.

CRYPT_ANY

Retrieve the user mode information for the provider.

CRYPT_UM

Retrieve the kernel mode information for the provider.

CRYPT_KM

Retrieve both the user mode and kernel mode information

CRYPT_MM for the provider.

[in] dwInterface

Specifies the interface to retrieve information for. This can be one of the following values.

VA L UE M EA N IN G

Retrieve the asymmetric encryption interface.

BCRYPT_ASYMMETRIC_ENCRYPTION_INTERFACE
 Retrieve the cipher interface.
BCRYPT_CIPHER_INTERFACE

Retrieve the hash interface.

BCRYPT_HASH_INTERFACE

Retrieve the key storage interface.

NCRYPT_KEY_STORAGE_INTERFACE

Retrieve the random number generator interface.

BCRYPT_RNG_INTERFACE

Retrieve the Schannel interface.

NCRYPT_SCHANNEL_INTERFACE

Retrieve the secret agreement interface.

BCRYPT_SECRET_AGREEMENT_INTERFACE

Retrieve the signature interface.

BCRYPT_SIGNATURE_INTERFACE

[in, out] pcbBuffer

A pointer to a ULONG value that, on entry, contains the size, in bytes, of the buffer pointed to by the ppBuffer
parameter. On exit, this value receives either the number of bytes copied to the buffer or the required size, in
bytes, of the buffer.

Note This is the total size, in bytes, of the entire buffer, not just the size of the CRYPT_PROVIDER_REG structure. The buffer
must be able to hold other data for the providers in addition to the CRYPT_PROVIDER_REG structure.

[in, out] ppBuffer

A pointer to a buffer pointer that receives a CRYPT_PROVIDER_REG structure and other data that describes the
provider.
If this parameter is NULL , this function will return STATUS_BUFFER_TOO_SMALL and place in the value
pointed to by the pcbBuffer parameter, the required size, in bytes, of all data.
If this parameter is the address of a NULL pointer, this function will allocate the required memory, fill it in with
the provider information, and place a pointer to this memory in this parameter. When you have finished using
this memory, free it by passing this pointer to the BCryptFreeBuffer function.
If this parameter is the address of a non-NULL pointer, this function will copy the provider information into this
buffer. The pcbBuffer parameter must contain the size, in bytes, of the entire buffer. If the buffer is not large
enough to hold all of the provider information, this function will return STATUS_BUFFER_TOO_SMALL .

Return value
Returns a status code that indicates the success or failure of the function.
Possible return codes include, but are not limited to, the following.
 RET URN C O DE DESC RIP T IO N

The function was successful.

STATUS_SUCCESS

One or more parameters are not valid.

STATUS_INVALID_PARAMETER

The size specified by the pcbBuffer parameter is not large

STATUS_BUFFER_TOO_SMALL enough to hold all of the data.

No provider could be found that matches the specified

STATUS_NOT_FOUND criteria.

Remarks
BCr yptQuer yProviderRegistration can be called only in user mode.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header bcrypt.h

Librar y Bcrypt.lib

DLL Bcrypt.dll

See also
BCryptFreeBuffer
CRYPT_PROVIDER_REG
 BCryptRegisterConfigChangeNotify function
(bcrypt.h)
7/2/2022 • 2 minutes to read • Edit Online

[BCr yptRegisterConfigChangeNotify is deprecated beginning with Windows 10.]

The BCr yptRegisterConfigChangeNotify(HANDLE*) function creates a user mode CNG configuration
change event handler.

Syntax
NTSTATUS BCryptRegisterConfigChangeNotify(
[out] PRKEVENT pEvent
);

Parameters
[out] pEvent

The address of a HANDLE variable that receives the event handle. Use one of the Wait Functions, such as
WaitForSingleObject, to determine when the event has been signaled. The event is unnamed and must be a
manual-reset event. The event is signaled when any CNG configuration data has changed.
This handle must be passed to the BCryptUnregisterConfigChangeNotify(HANDLE) function to remove the
event notification.

Return value
Returns a status code that indicates the success or failure of the function.
Possible return codes include, but are not limited to, the following.

RET URN C O DE DESC RIP T IO N

The function was successful.

STATUS_SUCCESS

The phEvent parameter is not valid.

STATUS_INVALID_PARAMETER

A memory allocation failure occurred.

STATUS_NO_MEMORY

Remarks
The handle returned in the variable pointed to by the phEvent parameter will be signaled when a change to the
CNG configuration occurs.
BCr yptRegisterConfigChangeNotify(HANDLE*) can be called only in user mode. Code executing in kernel
mode must call BCryptRegisterConfigChangeNotify(PRKEVENT).

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header bcrypt.h

Librar y Bcrypt.lib

DLL Bcrypt.dll

See also
BCryptUnregisterConfigChangeNotify(HANDLE)
 BCryptRemoveContextFunction function (bcrypt.h)
7/2/2022 • 2 minutes to read • Edit Online

[BCr yptRemoveContextFunction is available for use in the operating systems specified in the Requirements
section. It may be altered or unavailable in subsequent versions.]
The BCr yptRemoveContextFunction function removes a cryptographic function from the list of functions
that are supported by an existing CNG context.

Syntax
NTSTATUS BCryptRemoveContextFunction(
[in] ULONG dwTable,
[in] LPCWSTR pszContext,
[in] ULONG dwInterface,
[in] LPCWSTR pszFunction
);

Parameters
[in] dwTable

Identifies the configuration table that the context exists in. This can be one of the following values.

VA L UE M EA N IN G

The context exists in the local-machine configuration table.

CRYPT_LOCAL

This value is not available for use.

CRYPT_DOMAIN

[in] pszContext

A pointer to a null-terminated Unicode string that contains the identifier of the context to remove the function
from.
[in] dwInterface

Identifies the cryptographic interface to remove the function from. This can be one of the following values.

VA L UE M EA N IN G

Remove the function from the list of asymmetric encryption

BCRYPT_ASYMMETRIC_ENCRYPTION_INTERFACE functions.

Remove the function from the list of cipher functions.

BCRYPT_CIPHER_INTERFACE

Remove the function from the list of hash functions.

BCRYPT_HASH_INTERFACE
 Remove the function from the list of random number
BCRYPT_RNG_INTERFACE generator functions.

Remove the function from the list of secret agreement

BCRYPT_SECRET_AGREEMENT_INTERFACE functions.

Remove the function from the list of signature functions.

BCRYPT_SIGNATURE_INTERFACE

Remove the function from the list of key storage functions.

NCRYPT_KEY_STORAGE_INTERFACE

Remove the function from the list of Schannel functions.

NCRYPT_SCHANNEL_INTERFACE

Remove the function from the list of signature suites that

NCRYPT_SCHANNEL_SIGNATURE_INTERFACE Schannel accepts for TLS 1.2.
Windows Vista and Windows Ser ver 2008: This
value is not supported.

[in] pszFunction

A pointer to a null-terminated Unicode string that contains the identifier of the cryptographic function to
remove.

Return value
Returns a status code that indicates the success or failure of the function.
Possible return codes include, but are not limited to, the following.

RET URN C O DE DESC RIP T IO N

The function was successful.

STATUS_SUCCESS

One or more parameters are not valid.

STATUS_INVALID_PARAMETER

The specified context or function could not be found.

STATUS_NOT_FOUND

Remarks
BCr yptRemoveContextFunction can be called only in user mode.

Requirements
 Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header bcrypt.h

Librar y Bcrypt.lib

DLL Bcrypt.dll

See also
BCryptAddContextFunction
 BCryptResolveProviders function (bcrypt.h)
7/2/2022 • 3 minutes to read • Edit Online

The BCr yptResolveProviders function obtains a collection of all of the providers that meet the specified
criteria.

Syntax
NTSTATUS BCryptResolveProviders(
[in, optional] LPCWSTR pszContext,
[in, optional] ULONG dwInterface,
[in, optional] LPCWSTR pszFunction,
[in, optional] LPCWSTR pszProvider,
[in] ULONG dwMode,
[in] ULONG dwFlags,
[in, out] ULONG *pcbBuffer,
[in, out] PCRYPT_PROVIDER_REFS *ppBuffer
);

Parameters
[in, optional] pszContext

A pointer to a null-terminated Unicode string that contains the identifier of the context for which to obtain the
providers. If this is set to NULL or to an empty string, the default context is assumed.
[in, optional] dwInterface

The identifier of an interface that the provider must support. This must be one of the CNG Interface Identifiers. If
the pszFunction parameter is not NULL or an empty string, you can set dwInterface to zero to force the function
to infer the interface.
[in, optional] pszFunction

A pointer to a null-terminated Unicode string that contains the algorithm or function identifier that the provider
must support. This can be one of the standard CNG Algorithm Identifiers or the identifier for another registered
algorithm. If dwInterface is set to a nonzero value, then pszFunction can be NULL to include all algorithms and
functions.
[in, optional] pszProvider

A pointer to a null-terminated Unicode string that contains the name of the provider to retrieve. If this
parameter is NULL , then all providers will be included.
This parameter allows you to specify a specific provider to retrieve in the event that more than one provider
meets the other criteria.
[in] dwMode

Specifies the type of provider to retrieve. This can be one of the following values.

VA L UE M EA N IN G
 Retrieve user mode providers.
CRYPT_UM

Retrieve kernel mode providers.

CRYPT_KM

Retrieve both user mode and kernel mode providers.

CRYPT_MM

[in] dwFlags

A set of flags that modify the behavior of this function.

This can be a zero or a combination of one or more of the following values.

VA L UE M EA N IN G

This function will retrieve all of the functions supported by

CRYPT_ALL_FUNCTIONS each provider that meets the specified criteria. If this flag is
1 not specified, this function will only retrieve the first function
of the provider or providers that meet the specified criteria.

This function will retrieve all of the providers that meet the
CRYPT_ALL_PROVIDERS specified criteria. If this flag is not specified, this function will
2 only retrieve the first provider that is found that meets the
specified criteria.

[in, out] pcbBuffer

A pointer to a DWORD value that, on entry, contains the size, in bytes, of the buffer pointed to by the ppBuffer
parameter. On exit, this value receives either the number of bytes copied to the buffer or the required size, in
bytes, of the buffer.
[in, out] ppBuffer

The address of a CRYPT_PROVIDER_REFS pointer that receives the collection of providers that meet the
specified criteria.
If this parameter is NULL , this function will return STATUS_SUCCESS and place in the value pointed to by the
pcbBuffer parameter, the required size, in bytes, of all the data.
If this parameter is the address of a NULL pointer, this function will allocate the required memory, fill the
memory with the information about the providers, and place the pointer to this memory in this parameter.
When you have finished using this memory, free it by passing this pointer to the BCryptFreeBuffer function.
If this parameter is the address of a non-NULL pointer, this function will copy the provider information into this
buffer. The pcbBuffer parameter must contain the size, in bytes, of the entire buffer. If the buffer is not large
enough to hold all of the provider information, this function will return STATUS_BUFFER_TOO_SMALL .

Return value
Returns a status code that indicates the success or failure of the function.
Possible return codes include, but are not limited to, the following.

RET URN C O DE DESC RIP T IO N

 The function was successful.
STATUS_SUCCESS

The size specified by the pcbBuffer parameter is not large

STATUS_BUFFER_TOO_SMALL enough to hold all of the data.

One or more parameters are not valid.

STATUS_INVALID_PARAMETER

No provider could be found that meets all of the specified

STATUS_NOT_FOUND criteria.

Remarks
BCr yptResolveProviders can be called either from user mode or kernel mode. Kernel mode callers must be
executing at PASSIVE_LEVEL IRQL.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header bcrypt.h

Librar y Bcrypt.lib

DLL Bcrypt.dll
 BCryptSecretAgreement function (bcrypt.h)
7/2/2022 • 2 minutes to read • Edit Online

The BCr yptSecretAgreement function creates a secret agreement value from a private and a public key.

Syntax
NTSTATUS BCryptSecretAgreement(
[in] BCRYPT_KEY_HANDLE hPrivKey,
[in] BCRYPT_KEY_HANDLE hPubKey,
[out] BCRYPT_SECRET_HANDLE *phAgreedSecret,
[in] ULONG dwFlags
);

Parameters
[in] hPrivKey

The handle of the private key to use to create the secret agreement value. This key and the hPubKey key must
come from the same CNG cryptographic algorithm provider.
[in] hPubKey

The handle of the public key to use to create the secret agreement value. This key and the hPrivKey key must
come from the same CNG cryptographic algorithm provider.
[out] phAgreedSecret

A pointer to a BCRYPT_SECRET_HANDLE that receives a handle that represents the secret agreement value.
This handle must be released by passing it to the BCryptDestroySecret function when it is no longer needed.
[in] dwFlags

A set of flags that modify the behavior of this function. No flags are defined for this function.

Return value
Returns a status code that indicates the success or failure of the function.
Possible return codes include, but are not limited to, the following.

RET URN C O DE DESC RIP T IO N

The function was successful.

STATUS_SUCCESS

The key handle in the hPrivKey or hPubKey parameter is not

STATUS_INVALID_HANDLE valid.

One or more parameters are not valid.

STATUS_INVALID_PARAMETER
 The key handle in the hPrivKey parameter is not a Diffie-
STATUS_NOT_SUPPORTED Hellman key.

Remarks
Depending on what processor modes a provider supports, BCr yptSecretAgreement can be called either from
user mode or kernel mode. Kernel mode callers can execute either at PASSIVE_LEVEL IRQL or
DISPATCH_LEVEL IRQL. If the current IRQL level is DISPATCH_LEVEL , the handles provided in the hPrivKey
and hPubKey parameters must be derived from an algorithm handle returned by a provider that was opened by
using the BCRYPT_PROV_DISPATCH flag, and any pointers passed to the BCr yptSecretAgreement function
must refer to nonpaged (or locked) memory.
To call this function in kernel mode, use Cng.lib, which is part of the Driver Development Kit (DDK). Windows
Ser ver 2008 and Windows Vista: To call this function in kernel mode, use Ksecdd.lib.

Requirements

Minimum suppor ted client Windows Vista [desktop apps | UWP apps]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps | UWP apps]

Target Platform Windows

Header bcrypt.h

Librar y Bcrypt.lib

DLL Bcrypt.dll

See also
BCryptDestroySecret
 BCryptSetContextFunctionProperty function
(bcrypt.h)
7/2/2022 • 2 minutes to read • Edit Online

The BCr yptSetContextFunctionProper ty function sets the value of a named property for a cryptographic
function in an existing CNG context.

Syntax
NTSTATUS BCryptSetContextFunctionProperty(
[in] ULONG dwTable,
[in] LPCWSTR pszContext,
[in] ULONG dwInterface,
[in] LPCWSTR pszFunction,
[in] LPCWSTR pszProperty,
[in] ULONG cbValue,
[in] PUCHAR pbValue
);

Parameters
[in] dwTable

Identifies the configuration table that the context exists in. This can be one of the following values.

VA L UE M EA N IN G

The context exists in the local-machine configuration table.

CRYPT_LOCAL

This value is not available for use.

CRYPT_DOMAIN

[in] pszContext

A pointer to a null-terminated Unicode string that contains the identifier of the context to set the function
property in.
[in] dwInterface

Identifies the cryptographic interface that the function exists in. This can be one of the following values.

VA L UE M EA N IN G

The function exists in the list of asymmetric encryption

BCRYPT_ASYMMETRIC_ENCRYPTION_INTERFACE functions.

The function exists in the list of cipher functions.

BCRYPT_CIPHER_INTERFACE
 The function exists in the list of hash functions.
BCRYPT_HASH_INTERFACE

The function exists in the list of random number generator

BCRYPT_RNG_INTERFACE functions.

The function exists in the list of secret agreement functions.

BCRYPT_SECRET_AGREEMENT_INTERFACE

The function exists in the list of signature functions.

BCRYPT_SIGNATURE_INTERFACE

The function exists in the list of key storage functions.

NCRYPT_KEY_STORAGE_INTERFACE

The function exists in the list of Schannel functions.

NCRYPT_SCHANNEL_INTERFACE

[in] pszFunction

A pointer to a null-terminated Unicode string that contains the identifier of the cryptographic function to set the
property for.
[in] pszProperty

A pointer to a null-terminated Unicode string that contains the identifier of the property to set.
[in] cbValue

Contains the size, in bytes, of the pbValue buffer. This is the exact number of bytes that will be stored. If the
property value is a string, you should add the size of one character to also store the terminating null character, if
needed.
[in] pbValue

The address of a buffer that contains the new property value.

Return value
Returns a status code that indicates the success or failure of the function.
Possible return codes include, but are not limited to, the following.

RET URN C O DE DESC RIP T IO N

The function was successful.

STATUS_SUCCESS

The caller does not have write access to the properties for
STATUS_ACCESS_DENIED the function.

One or more parameters are not valid.

STATUS_INVALID_PARAMETER
 A memory allocation failure occurred.
STATUS_NO_MEMORY

The specified context or function could not be found.

STATUS_NOT_FOUND

Remarks
BCr yptSetContextFunctionProper ty can be called only in user mode.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header bcrypt.h

Librar y Bcrypt.lib

DLL Bcrypt.dll
 BCryptSetProperty function (bcrypt.h)
7/2/2022 • 2 minutes to read • Edit Online

The BCr yptSetProper ty function sets the value of a named property for a CNG object.

Syntax
NTSTATUS BCryptSetProperty(
[in, out] BCRYPT_HANDLE hObject,
[in] LPCWSTR pszProperty,
[in] PUCHAR pbInput,
[in] ULONG cbInput,
[in] ULONG dwFlags
);

Parameters
[in, out] hObject

A handle that represents the CNG object to set the property value for.
[in] pszProperty

A pointer to a null-terminated Unicode string that contains the name of the property to set. This can be one of
the predefined Cryptography Primitive Property Identifiers or a custom property identifier.
[in] pbInput

The address of a buffer that contains the new property value. The cbInput parameter contains the size of this
buffer.
[in] cbInput

The size, in bytes, of the pbInput buffer.

[in] dwFlags

A set of flags that modify the behavior of this function. No flags are defined for this function.

Return value
Returns a status code that indicates the success or failure of the function.
Possible return codes include, but are not limited to, the following.

RET URN C O DE DESC RIP T IO N

The function was successful.

STATUS_SUCCESS

The handle in the hObject parameter is not valid.

STATUS_INVALID_HANDLE
 One or more parameters are not valid.
STATUS_INVALID_PARAMETER

The named property specified by the pszProperty parameter

STATUS_NOT_SUPPORTED is not supported or is read-only.

Remarks
Depending on what processor modes a provider supports, BCr yptSetProper ty can be called either from user
mode or kernel mode. Kernel mode callers can execute either at PASSIVE_LEVEL IRQL or DISPATCH_LEVEL
IRQL. If the current IRQL level is DISPATCH_LEVEL , any pointers passed to BCr yptSetProper ty must refer to
nonpaged (or locked) memory. If the object specified in the hObject parameter is a handle, it must have been
opened by using the BCRYPT_PROV_DISPATCH flag.
To call this function in kernel mode, use Cng.lib, which is part of the Driver Development Kit (DDK). Windows
Ser ver 2008 and Windows Vista: To call this function in kernel mode, use Ksecdd.lib.

Requirements

Minimum suppor ted client Windows Vista [desktop apps | UWP apps]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps | UWP apps]

Target Platform Windows

Header bcrypt.h

Librar y Bcrypt.lib

DLL Bcrypt.dll
 BCryptSignHash function (bcrypt.h)
7/2/2022 • 2 minutes to read • Edit Online

The BCr yptSignHash function creates a signature of a hash value.

Syntax
NTSTATUS BCryptSignHash(
[in] BCRYPT_KEY_HANDLE hKey,
[in, optional] VOID *pPaddingInfo,
[in] PUCHAR pbInput,
[in] ULONG cbInput,
[out] PUCHAR pbOutput,
[in] ULONG cbOutput,
[out] ULONG *pcbResult,
[in] ULONG dwFlags
);

Parameters
[in] hKey

The handle of the key to use to sign the hash.

[in, optional] pPaddingInfo

A pointer to a structure that contains padding information. The actual type of structure this parameter points to
depends on the value of the dwFlags parameter. This parameter is only used with asymmetric keys and must be
NULL otherwise.
[in] pbInput

A pointer to a buffer that contains the hash value to sign. The cbInput parameter contains the size of this buffer.
[in] cbInput

The number of bytes in the pbInput buffer to sign.

[out] pbOutput

The address of a buffer to receive the signature produced by this function. The cbOutput parameter contains the
size of this buffer.
If this parameter is NULL , this function will calculate the size required for the signature and return the size in the
location pointed to by the pcbResult parameter.
[in] cbOutput

The size, in bytes, of the pbOutput buffer. This parameter is ignored if the pbOutput parameter is NULL .
[out] pcbResult

A pointer to a ULONG variable that receives the number of bytes copied to the pbOutput buffer.
If pbOutput is NULL , this receives the size, in bytes, required for the signature.
[in] dwFlags

A set of flags that modify the behavior of this function. The allowed set of flags depends on the type of key
specified by the hKey parameter.
This can be one of the following values.

VA L UE M EA N IN G

Use the PKCS1 padding scheme. The pPaddingInfo

BCRYPT_PAD_PKCS1 parameter is a pointer to a BCRYPT_PKCS1_PADDING_INFO
structure.

Use the Probabilistic Signature Scheme (PSS) padding

BCRYPT_PAD_PSS scheme. The pPaddingInfo parameter is a pointer to a
BCRYPT_PSS_PADDING_INFO structure.

Return value
Returns a status code that indicates the success or failure of the function.
Possible return codes include, but are not limited to, the following.

RET URN C O DE DESC RIP T IO N

The function was successful.

STATUS_SUCCESS

The key handle specified by the hKey parameter is not valid.

STATUS_INVALID_HANDLE

The algorithm provider used to create the key handle

STATUS_NOT_SUPPORTED specified by the hKey parameter is not a signing algorithm.

A memory allocation failure occurred.

STATUS_NO_MEMORY

The memory size specified by the cbOutput parameter is not

STATUS_BUFFER_TOO_SMALL large enough to hold the signature.

Remarks
This function will encrypt the hash value with the specified key to create the signature.
To later verify that the signature is valid, call the BCryptVerifySignature function with an identical key and an
identical hash of the original data.
Depending on what processor modes a provider supports, BCr yptSignHash can be called either from user
mode or kernel mode. Kernel mode callers can execute either at PASSIVE_LEVEL IRQL or DISPATCH_LEVEL
IRQL. If the current IRQL level is DISPATCH_LEVEL , the handle provided in the hKey parameter must be derived
from an algorithm handle returned by a provider that was opened with the BCRYPT_PROV_DISPATCH flag,
and any pointers passed to the BCr yptSignHash function must refer to nonpaged (or locked) memory.
To call this function in kernel mode, use Cng.lib, which is part of the Driver Development Kit (DDK). Windows
Ser ver 2008 and Windows Vista: To call this function in kernel mode, use Ksecdd.lib.
Requirements

Minimum suppor ted client Windows Vista [desktop apps | UWP apps]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps | UWP apps]

Target Platform Windows

Header bcrypt.h

Librar y Bcrypt.lib

DLL Bcrypt.dll

See also
BCryptVerifySignature
 BCryptUnregisterConfigChangeNotify function
(bcrypt.h)
7/2/2022 • 2 minutes to read • Edit Online

The BCr yptUnregisterConfigChangeNotify(HANDLE) function removes a user mode CNG configuration

change event handler that was created by using the BCryptRegisterConfigChangeNotify(HANDLE*) function.

Syntax
NTSTATUS BCryptUnregisterConfigChangeNotify(
[in] PRKEVENT pEvent
);

Parameters
[in] pEvent

The handle of the event to remove. This is the handle that was obtained by using the
BCryptRegisterConfigChangeNotify(HANDLE*) function.

Return value
Returns a status code that indicates the success or failure of the function.
Possible return codes include, but are not limited to, the following.

RET URN C O DE DESC RIP T IO N

The function was successful.

STATUS_SUCCESS

The hEvent parameter is not valid.

STATUS_INVALID_PARAMETER

A memory allocation failure occurred.

STATUS_NO_MEMORY

Remarks
BCr yptUnregisterConfigChangeNotify(HANDLE) can be called only in user mode. Code executing in kernel
mode must call BCryptUnregisterConfigChangeNotify(PRKEVENT).

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

 Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header bcrypt.h

Librar y Bcrypt.lib

DLL Bcrypt.dll

See also
BCryptRegisterConfigChangeNotify(HANDLE*)
 BCryptVerifySignature function (bcrypt.h)
7/2/2022 • 3 minutes to read • Edit Online

The BCr yptVerifySignature function verifies that the specified signature matches the specified hash.

Syntax
NTSTATUS BCryptVerifySignature(
[in] BCRYPT_KEY_HANDLE hKey,
[in, optional] VOID *pPaddingInfo,
[in] PUCHAR pbHash,
[in] ULONG cbHash,
[in] PUCHAR pbSignature,
[in] ULONG cbSignature,
[in] ULONG dwFlags
);

Parameters
[in] hKey

The handle of the key to use to decrypt the signature. This must be an identical key or the public key portion of
the key pair used to sign the data with the BCryptSignHash function.
[in, optional] pPaddingInfo

A pointer to a structure that contains padding information. The actual type of structure this parameter points to
depends on the value of the dwFlags parameter. This parameter is only used with asymmetric keys and must be
NULL otherwise.
[in] pbHash

The address of a buffer that contains the hash of the data. The cbHash parameter contains the size of this buffer.
[in] cbHash

The size, in bytes, of the pbHash buffer.

[in] pbSignature

The address of a buffer that contains the signed hash of the data. The BCryptSignHash function is used to create
the signature. The cbSignature parameter contains the size of this buffer.
[in] cbSignature

The size, in bytes, of the pbSignature buffer. The BCryptSignHash function is used to create the signature.
[in] dwFlags

A set of flags that modify the behavior of this function. The allowed set of flags depends on the type of key
specified by the hKey parameter.
If the key is a symmetric key, this parameter is not used and should be zero.
If the key is an asymmetric key, this can be one of the following values.
 VA L UE M EA N IN G

The PKCS1 padding scheme was used when the signature

BCRYPT_PAD_PKCS1 was created. The pPaddingInfo parameter is a pointer to a
BCRYPT_PKCS1_PADDING_INFO structure.

The Probabilistic Signature Scheme (PSS) padding scheme

BCRYPT_PAD_PSS was used when the signature was created. The pPaddingInfo
parameter is a pointer to a BCRYPT_PSS_PADDING_INFO
structure.

Return value
Returns a status code that indicates the success or failure of the function.
Possible return codes include, but are not limited to, the following.

RET URN C O DE DESC RIP T IO N

The function was successful.

STATUS_SUCCESS

The signature was not verified.

STATUS_INVALID_SIGNATURE

A memory allocation failure occurred.

NTE_NO_MEMORY

One of supplied parameters is invalid.

STATUS_INVALID_PARAMETER

The key handle specified by the hKey parameter is not valid.

STATUS_INVALID_HANDLE

The algorithm provider used to create the key handle

STATUS_NOT_SUPPORTED specified by the hKey parameter is not a signing algorithm.

Remarks
This function calculates the signature with provided key and then compares calculated signature value to the
specified signature value.
To use this function, you must hash the data by using the same hashing algorithm that was used to create the
hash value that was signed. If applicable, you must also specify the same padding scheme that was specified
when the signature was created.
Depending on what processor modes a provider supports, BCr yptVerifySignature can be called either from
user mode or kernel mode. Kernel mode callers can execute either at PASSIVE_LEVEL IRQL or
DISPATCH_LEVEL IRQL. If the current IRQL level is DISPATCH_LEVEL , the handle provided in the hKey
parameter must be derived from an algorithm handle returned by a provider that was opened by using the
BCRYPT_PROV_DISPATCH flag, and any pointers passed to the BCr yptVerifySignature function must refer
to nonpaged (or locked) memory.
To call this function in kernel mode, use Cng.lib, which is part of the Driver Development Kit (DDK). Windows
Ser ver 2008 and Windows Vista: To call this function in kernel mode, use Ksecdd.lib.

Requirements

Minimum suppor ted client Windows Vista [desktop apps | UWP apps]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps | UWP apps]

Target Platform Windows

Header bcrypt.h

Librar y Bcrypt.lib

DLL Bcrypt.dll

See also
BCryptSignHash
 CRYPT_CONTEXT_CONFIG structure (bcrypt.h)
7/2/2022 • 2 minutes to read • Edit Online

The CRYPT_CONTEXT_CONFIG structure contains configuration information for a CNG context.

Syntax
typedef struct _CRYPT_CONTEXT_CONFIG {
ULONG dwFlags;
ULONG dwReserved;
} CRYPT_CONTEXT_CONFIG, *PCRYPT_CONTEXT_CONFIG;

Members
dwFlags

A set of flags that determine the options for the configuration context. This can be zero or a combination of one
or more of the following values.

VA L UE M EA N IN G

Restricts the set of cryptographic functions in an interface to

CRYPT_EXCLUSIVE those that the current CNG context is specifically registered
to support.
If this flag is set, then any attempts to resolve a given
function will succeed only if one of the following is true:
The function exists within the current CNG context.
The function exists in some interface in the default
context, and an instance of that same interface also
exists within the current CNG context.

Indicates that this entry in the enterprise-wide configuration

CRYPT_OVERRIDE table should take precedence over any and all corresponding
entries in the local-machine configuration table for this
context. This flag only applies to entries in the enterprise-
wide configuration table. Without this flag, local machine
configuration entries take precedence.

dwReserved

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Header bcrypt.h
See also
BCryptConfigureContext
BCryptCreateContext
BCryptQueryContextConfiguration
 CRYPT_CONTEXT_FUNCTION_CONFIG structure
(bcrypt.h)
7/2/2022 • 2 minutes to read • Edit Online

The CRYPT_CONTEXT_FUNCTION_CONFIG structure contains configuration information for a cryptographic

function of a CNG context.

Syntax
typedef struct _CRYPT_CONTEXT_FUNCTION_CONFIG {
ULONG dwFlags;
ULONG dwReserved;
} CRYPT_CONTEXT_FUNCTION_CONFIG, *PCRYPT_CONTEXT_FUNCTION_CONFIG;

Members
dwFlags

A set of flags that determine the options for the context function configuration. This can be zero or the following
value.

VA L UE M EA N IN G

Restricts the set of usable providers for this function to only

CRYPT_EXCLUSIVE those that this function is specifically registered to support.

dwReserved

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Header bcrypt.h

See also
BCryptConfigureContextFunction
 CRYPT_CONTEXT_FUNCTION_PROVIDERS
structure (bcrypt.h)
7/2/2022 • 2 minutes to read • Edit Online

The CRYPT_CONTEXT_FUNCTION_PROVIDERS structure contains a set of cryptographic function providers

for a CNG configuration context.

Syntax
typedef struct _CRYPT_CONTEXT_FUNCTION_PROVIDERS {
ULONG cProviders;
PWSTR *rgpszProviders;
} CRYPT_CONTEXT_FUNCTION_PROVIDERS, *PCRYPT_CONTEXT_FUNCTION_PROVIDERS;

Members
cProviders

The number of elements in the rgpszProviders array.

rgpszProviders

An array of pointers to null-terminated Unicode strings that contain the identifiers of the function providers
contained in this set. The cProviders member contains the number of elements in this array.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Header bcrypt.h

See also
BCryptEnumContextFunctionProviders
 CRYPT_CONTEXT_FUNCTIONS structure (bcrypt.h)
7/2/2022 • 2 minutes to read • Edit Online

The CRYPT_CONTEXT_FUNCTIONS structure contains a set of cryptographic functions for a CNG

configuration context.

Syntax
typedef struct _CRYPT_CONTEXT_FUNCTIONS {
ULONG cFunctions;
PWSTR *rgpszFunctions;
} CRYPT_CONTEXT_FUNCTIONS, *PCRYPT_CONTEXT_FUNCTIONS;

Members
cFunctions

The number of elements in the rgpszFunctions array.

rgpszFunctions

An array of pointers to null-terminated Unicode strings that contain the identifiers of the cryptographic
functions contained in this set. The cFunctions member contains the number of elements in this array.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Header bcrypt.h

See also
BCryptEnumContextFunctions
 CRYPT_CONTEXTS structure (bcrypt.h)
7/2/2022 • 2 minutes to read • Edit Online

The CRYPT_CONTEXTS structure contains a set of CNG configuration context identifiers.

Syntax
typedef struct _CRYPT_CONTEXTS {
ULONG cContexts;
PWSTR *rgpszContexts;
} CRYPT_CONTEXTS, *PCRYPT_CONTEXTS;

Members
cContexts

Contains the number of elements in the rgpszContexts array.

rgpszContexts

An array of pointers to null-terminated Unicode strings that contain the identifiers of the contexts contained in
this set. The cContext member contains the number of elements in this array.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Header bcrypt.h

See also
BCryptEnumContexts
 CRYPT_IMAGE_REF structure (bcrypt.h)
7/2/2022 • 2 minutes to read • Edit Online

The CRYPT_IMAGE_REF structure contains information about a CNG provider module.

Syntax
typedef struct _CRYPT_IMAGE_REF {
PWSTR pszImage;
ULONG dwFlags;
} CRYPT_IMAGE_REF, *PCRYPT_IMAGE_REF;

Members
pszImage

A pointer to a null-terminated Unicode string that contains the name of the provider module.
dwFlags

A set of flags that indicate how CNG will manage the binary image with respect to this interface. This can be
zero or a combination of one or more of the following values.

VA L UE M EA N IN G

The provider for this interface is only dependent on a

CRYPT_MIN_DEPENDENCIES minimum set of system components. This flag applies to a
specific interface only and does not mean that all interfaces
supported by the binary image conform to this standard.

This flag is not used.

CRYPT_PROCESS_ISOL ATE

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Header bcrypt.h

See also
BCryptResolveProviders
CRYPT_PROVIDER_REF
 CRYPT_IMAGE_REG structure (bcrypt.h)
7/2/2022 • 2 minutes to read • Edit Online

The CRYPT_IMAGE_REG structure contains image registration information about a CNG provider.

Syntax
typedef struct _CRYPT_IMAGE_REG {
PWSTR pszImage;
ULONG cInterfaces;
PCRYPT_INTERFACE_REG *rgpInterfaces;
} CRYPT_IMAGE_REG, *PCRYPT_IMAGE_REG;

Members
pszImage

A pointer to a null-terminated Unicode string that contains only the file name of the provider module.
cInterfaces

Contains the number of elements in the rgpInterfaces array.

rgpInterfaces

A pointer to an array of CRYPT_INTERFACE_REG structure pointers that specify the types of cryptographic
interfaces that are supported by the provider. For example, if the provider supports both a cipher interface
(BCRYPT_CIPHER_INTERFACE ) and a hash interface (BCRYPT_HASH_INTERFACE ), this array would contain
two CRYPT_INTERFACE_REG structure pointers, one for the cipher interface and one for the hash interface.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Header bcrypt.h

See also
CRYPT_PROVIDER_REG
 CRYPT_INTERFACE_REG structure (bcrypt.h)
7/2/2022 • 2 minutes to read • Edit Online

The CRYPT_INTERFACE_REG structure is used to contain information about the type of interface supported by
a CNG provider.

Syntax
typedef struct _CRYPT_INTERFACE_REG {
ULONG dwInterface;
ULONG dwFlags;
ULONG cFunctions;
PWSTR *rgpszFunctions;
} CRYPT_INTERFACE_REG, *PCRYPT_INTERFACE_REG;

Members
dwInterface

Contains the identifier of the interface type. This can be one of the following values.

VA L UE M EA N IN G

The provider supports the asymmetric encryption interface.

BCRYPT_ASYMMETRIC_ENCRYPTION_INTERFACE

The provider supports the cipher interface.

BCRYPT_CIPHER_INTERFACE

The provider supports the hash interface.

BCRYPT_HASH_INTERFACE

The provider supports the key storage interface.

NCRYPT_KEY_STORAGE_INTERFACE

The provider supports the random number generator

BCRYPT_RNG_INTERFACE interface.

The provider supports the Schannel interface.

NCRYPT_SCHANNEL_INTERFACE

The provider supports the secret agreement interface.

BCRYPT_SECRET_AGREEMENT_INTERFACE

The provider supports the signature interface.

BCRYPT_SIGNATURE_INTERFACE

dwFlags
Contains flags that modify the behavior of the interface. This can be one of the following values.

VA L UE M EA N IN G

This value is not available for use.

CRYPT_DOMAIN

The interface is registered in the local configuration table.

CRYPT_LOCAL

cFunctions

Contains the number of elements in the rgpszFunctions array.

rgpszFunctions

An array of null-terminated Unicode strings that contains the identifiers of the algorithms that are supported by
this interface. These identifiers can be the standard CNG Algorithm Identifiers or the identifiers for other
registered algorithms.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Header bcrypt.h

See also
CRYPT_IMAGE_REG
 CRYPT_PROPERTY_REF structure (bcrypt.h)
7/2/2022 • 2 minutes to read • Edit Online

The CRYPT_PROPERTY_REF structure contains information about a CNG context property.

Syntax
typedef struct _CRYPT_PROPERTY_REF {
PWSTR pszProperty;
ULONG cbValue;
PUCHAR pbValue;
} CRYPT_PROPERTY_REF, *PCRYPT_PROPERTY_REF;

Members
pszProperty

A pointer to a null-terminated Unicode string that contains the name of the property.
cbValue

The size, in bytes, of the pbValue buffer.

pbValue

A pointer to a memory buffer that contains the value of the property. The format and type of this data depend
on the property.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Header bcrypt.h

See also
BCryptResolveProviders
CRYPT_PROVIDER_REF
 CRYPT_PROVIDER_REF structure (bcrypt.h)
7/2/2022 • 2 minutes to read • Edit Online

The CRYPT_PROVIDER_REF structure contains information about a cryptographic interface that a provider
supports.

Syntax
typedef struct _CRYPT_PROVIDER_REF {
ULONG dwInterface;
PWSTR pszFunction;
PWSTR pszProvider;
ULONG cProperties;
PCRYPT_PROPERTY_REF *rgpProperties;
PCRYPT_IMAGE_REF pUM;
PCRYPT_IMAGE_REF pKM;
} CRYPT_PROVIDER_REF, *PCRYPT_PROVIDER_REF;

Members
dwInterface

The identifier of the interface that this reference applies to. This will be one of the CNG Interface Identifiers.
pszFunction

A pointer to a null-terminated Unicode string that identifies the algorithm or function that the reference applies
to. This can be one of the standard CNG Algorithm Identifiers or the identifier for another registered algorithm.
pszProvider

A pointer to a null-terminated Unicode string that contains the name of the provider.
cProperties

The number of elements in the rgpProper ties array. If the algorithm or function has no properties, then this
member will be zero.
rgpProperties

An array of CRYPT_PROPERTY_REF structure pointers that contain the properties for this algorithm or function.
The cProper ties member contains the number of elements in this array.
pUM

A pointer to a CRYPT_IMAGE_REF structure that contains information about the user mode provider module. If
this information was not requested or the provider is not registered as a user mode provider, this member will
be NULL .
pKM

A pointer to a CRYPT_IMAGE_REF structure that contains information about the kernel mode provider module. If
this information was not requested or the provider is not registered as a kernel mode provider, this member will
be NULL .
Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Header bcrypt.h

See also
BCryptResolveProviders
CRYPT_PROVIDER_REFS
 CRYPT_PROVIDER_REFS structure (bcrypt.h)
7/2/2022 • 2 minutes to read • Edit Online

The CRYPT_PROVIDER_REFS structure contains a collection of provider references.

Syntax
typedef struct _CRYPT_PROVIDER_REFS {
ULONG cProviders;
PCRYPT_PROVIDER_REF *rgpProviders;
} CRYPT_PROVIDER_REFS, *PCRYPT_PROVIDER_REFS;

Members
cProviders

The number of elements in the rgpProviders array.

rgpProviders

An array of CRYPT_PROVIDER_REF structure pointers that contain the provider references. The cProviders
member contains the number of elements in this array.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Header bcrypt.h

See also
BCryptResolveProviders
 CRYPT_PROVIDER_REG structure (bcrypt.h)
7/2/2022 • 2 minutes to read • Edit Online

The CRYPT_PROVIDER_REG structure is used to contain registration information for a CNG provider.

Syntax
typedef struct _CRYPT_PROVIDER_REG {
ULONG cAliases;
PWSTR *rgpszAliases;
PCRYPT_IMAGE_REG pUM;
PCRYPT_IMAGE_REG pKM;
} CRYPT_PROVIDER_REG, *PCRYPT_PROVIDER_REG;

Members
cAliases

Contains the number of elements in the rgpszAliases array. If the provider has no aliases, this member will be
zero and the rgpszAliases member will be NULL .
rgpszAliases

An array of null-terminated Unicode strings that contains the aliases of the provider. If the provider has no
aliases, this member will contain NULL and the cAliases member will contain zero.
pUM

A pointer to a CRYPT_IMAGE_REG structure that contains the registration information for the user mode
provider. If this member is NULL , the provider is not registered for user mode.
pKM

A pointer to a CRYPT_IMAGE_REG structure that contains the registration information for the kernel mode
provider. If this member is NULL , the provider is not registered for kernel mode.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Header bcrypt.h
 CRYPT_PROVIDERS structure (bcrypt.h)
7/2/2022 • 2 minutes to read • Edit Online

The CRYPT_PROVIDERS structure contains information about the registered CNG providers.

Syntax
typedef struct _CRYPT_PROVIDERS {
ULONG cProviders;
PWSTR *rgpszProviders;
} CRYPT_PROVIDERS, *PCRYPT_PROVIDERS;

Members
cProviders

Contains the number of elements in the rgpszProviders array.

rgpszProviders

An array of null-terminated Unicode strings that contains the names of the registered providers.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Header bcrypt.h

See also
BCryptEnumRegisteredProviders
 DSAFIPSVERSION_ENUM enumeration (bcrypt.h)
7/2/2022 • 2 minutes to read • Edit Online

The DSAFIPSVERSION_ENUM enumeration type contains FIPS version information. It is used by the
BCRYPT_DSA_KEY_BLOB_V2 and BCRYPT_DSA_PARAMETER_HEADER_V2 structures.

Syntax
typedef enum {
DSA_FIPS186_2,
DSA_FIPS186_3
} DSAFIPSVERSION_ENUM;

Constants

DSA_FIPS186_2
Federal Information Processing Standard (FIPS) 2.

DSA_FIPS186_3
Federal Information Processing Standard (FIPS) 3.

Requirements

Header bcrypt.h

See also
BCRYPT_DSA_KEY_BLOB_V2
BCRYPT_DSA_PARAMETER_HEADER_V2
 HASHALGORITHM_ENUM enumeration (bcrypt.h)
7/2/2022 • 2 minutes to read • Edit Online

The HASHALGORITHM_ENUM enumeration type specifies signing and hashing algorithms. It is used by the
BCRYPT_DSA_KEY_BLOB_V2 and BCRYPT_DSA_PARAMETER_HEADER_V2 structures.

Syntax
typedef enum {
DSA_HASH_ALGORITHM_SHA1,
DSA_HASH_ALGORITHM_SHA256,
DSA_HASH_ALGORITHM_SHA512
} HASHALGORITHM_ENUM;

Constants

DSA_HASH_ALGORITHM_SHA1
Represents a Digital Signature Algorithm (DSA) that uses the Secure Hashing Algorithm 1 (SHA1) to hash the message
contents before signing.

DSA_HASH_ALGORITHM_SHA256
Represents a Digital Signature Algorithm (DSA) that uses the Secure Hashing Algorithm 256 (SHA256) to hash the message
contents before signing.

DSA_HASH_ALGORITHM_SHA512
Represents a Digital Signature Algorithm (DSA) that uses the Secure Hashing Algorithm 512 (SHA512) to hash the message
contents before signing.

Requirements

Header bcrypt.h

See also
BCRYPT_DSA_KEY_BLOB_V2
BCRYPT_DSA_PARAMETER_HEADER_V2
 casetup.h header
7/2/2022 • 2 minutes to read • Edit Online

This header is used by Security and Identity. For more information, see:
Security and Identity
casetup.h contains the following programming interfaces:

Interfaces

ICertificateEnrollmentPolicyServerSetup

The ICertificateEnrollmentPolicyServerSetup interface represents the Certificate Enrollment Policy (CEP) Web Service within
Active Directory Certificate Services (ADCS).

ICertificateEnrollmentServerSetup

The ICertificateEnrollmentServerSetup interface represents the Certificate Enrollment Web Service (CES) within Active
Directory Certificate Services (ADCS).

ICertSrvSetup

Defines functionality to install and uninstall Certification Authority (CA) and Certification Authority Web Enrollment roles on a
Certificate Services computer.

ICertSrvSetupKeyInformation

Defines a set of private key properties that are used for setup of certification authority (CA) or Microsoft Simple Certificate
Enrollment Protocol (SCEP) roles.

ICertSrvSetupKeyInformationCollection

Defines functionality to populate and enumerate a collection of ICertSrvSetupKeyInformation objects.

IMSCEPSetup

Defines functionality to install and uninstall a Network Device Enrollment Service (NDES) role on a Certificate Services
computer.

Enumerations

CASetupProperty

Specifies a property type for setup and configuration of a certification authority (CA) role when using the ICertSrvSetup
interface.
CEPSetupProperty

Used by the GetProperty and SetProperty methods on the ICertificateEnrollmentPolicyServerSetup interface to specify the
type of property information to retrieve or set.

CESSetupProperty

Used by the GetProperty and SetProperty methods on the ICertificateEnrollmentServerSetup interface to specify the type of
property information to retrieve or set.

MSCEPSetupProperty

Specifies a property type for setup and configuration of a Microsoft Simple Certificate Enrollment Protocol (SCEP) role using
IMSCEPSetup.
 CASetupProperty enumeration (casetup.h)
7/2/2022 • 3 minutes to read • Edit Online

The CASetupProper ty enumeration specifies a property type for setup and configuration of a certification
authority (CA) role when using the ICertSrvSetup interface.

Syntax
typedef enum __MIDL___MIDL_itf_casetup_0000_0002_0001 {
ENUM_SETUPPROP_INVALID = -1,
ENUM_SETUPPROP_CATYPE = 0,
ENUM_SETUPPROP_CAKEYINFORMATION = 1,
ENUM_SETUPPROP_INTERACTIVE = 2,
ENUM_SETUPPROP_CANAME = 3,
ENUM_SETUPPROP_CADSSUFFIX = 4,
ENUM_SETUPPROP_VALIDITYPERIOD = 5,
ENUM_SETUPPROP_VALIDITYPERIODUNIT = 6,
ENUM_SETUPPROP_EXPIRATIONDATE = 7,
ENUM_SETUPPROP_PRESERVEDATABASE = 8,
ENUM_SETUPPROP_DATABASEDIRECTORY = 9,
ENUM_SETUPPROP_LOGDIRECTORY = 10,
ENUM_SETUPPROP_SHAREDFOLDER = 11,
ENUM_SETUPPROP_PARENTCAMACHINE = 12,
ENUM_SETUPPROP_PARENTCANAME = 13,
ENUM_SETUPPROP_REQUESTFILE = 14,
ENUM_SETUPPROP_WEBCAMACHINE = 15,
ENUM_SETUPPROP_WEBCANAME = 16
} CASetupProperty;

Constants

ENUM_SETUPPROP_INVALID
Value: -1
A value that specifies a property type that is not valid.

ENUM_SETUPPROP_CATYPE
Value: 0
A VT_I4 value that specifies a value of the ENUM_CATYPES enumeration.

If the computer is not joined to a domain, or the caller

is not an Enterprise or Domain administrator but is a local administrator, the default value is
ENUM_STANDALONE_ROOTCA . If the computer is joined to a domain, the caller is an Enterprise or Domain administrator,
and an enterprise root CA already exists, the default is ENUM_ENTERPRISE_SUBCA , or if no enterprise root CA exists, the
default value is ENUM_ENTERPRISE_ROOTCA .
ENUM_SETUPPROP_CAKEYINFORMATION
Value: 1
A VT_DISPATCH value, in the form of a CCer tSr vSetupKeyInformation object, that specifies the private key information
used for a CA certificate. By default, setup generates a new key

with a 2048-bit key length for root and subordinate CAs using "Microsoft

Strong Cryptographic Provider."

ENUM_SETUPPROP_INTERACTIVE
Value: 2
A VT_BOOL value that indicates whether the cryptographic service provider (CSP) is allowed to interact with the desktop. The
default is false.

ENUM_SETUPPROP_CANAME
Value: 3
A VT_BSTR value that contains the common name for the CA. By default, the common

name is DomainName-LocalComputerName-CAName.

ENUM_SETUPPROP_CADSSUFFIX
Value: 4
A VT_BSTR value that contains the distinguished name suffix for a CA name.

ENUM_SETUPPROP_VALIDITYPERIOD
Value: 5
A VT_I4 value that specifies the number of units in the validity period as specified by the
ENUM_SETUPPROP_VALIDITYPERIODUNIT property type. For a subordinate CA, the validity period is determined by the
parent CA.

ENUM_SETUPPROP_VALIDITYPERIODUNIT
Value: 6
A VT_I4 value that specifies a value of the ENUM_PERIOD enumeration that indicates the time units of the validity period. For
a subordinate CA, the validity period time unit is determined by the parent CA.

ENUM_SETUPPROP_EXPIRATIONDATE
Value: 7
A VT_BSTR value that specifies the expected expiration date of the root CA certificate based on the current time, validity
period, and validity period unit. For a subordinate CA, the expiration date is

determined by its parent CA.

ENUM_SETUPPROP_PRESERVEDATABASE
Value: 8
A VT_BOOL value that specifies whether to preserve an existing database. This is relevant under the following conditions:

A CA

was previously installed (and later uninstalled) on this computer.

An existing key (and its associated certificate) is being used for installation.

A database exists in the given database directory.

 ENUM_SETUPPROP_DATABASEDIRECTORY
Value: 9
A VT_BSTR value that specifies the path of the directory where CA database files are stored after installation. The default path
is %SystemRoot%\System32\Certlog.

ENUM_SETUPPROP_LOGDIRECTORY
Value: 10
A VT_BSTR value that specifies the path of the directory where CA database log files are stored after installation. The default
path is %SystemRoot%\System32\Certlog.

ENUM_SETUPPROP_SHAREDFOLDER
Value: 11
This value is not used and is reserved for future use.

ENUM_SETUPPROP_PARENTCAMACHINE
Value: 12
A VT_BSTR value that specifies the name of the computer that is hosting the parent CA. This value is only applicable if a
subordinate CA is being installed. There is no default value.

ENUM_SETUPPROP_PARENTCANAME
Value: 13
A VT_BSTR value that specifies the name of the parent CA. This value is only applicable if a subordinate CA is being installed.
There is no default value.

ENUM_SETUPPROP_REQUESTFILE
Value: 14
A VT_BSTR value that specifies the file path to use to save a subordinate CA request, so that it can be submitted later to the
parent CA. The default value is %SystemDrive%\\DNSMachineName_CAName.req.

ENUM_SETUPPROP_WEBCAMACHINE
Value: 15
A VT_BSTR value that specifies the name of the computer that is hosting the CA. This value is only applicable if support for
the Certification Authority Web Enrollment role is being installed. There is no default value.

ENUM_SETUPPROP_WEBCANAME
Value: 16
A VT_BSTR value that specifies the name of the CA. This value is only applicable if support for the Certification Authority Web
Enrollment role is being installed. There is no default value.

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Header casetup.h
 CEPSetupProperty enumeration (casetup.h)
7/2/2022 • 2 minutes to read • Edit Online

The CEPSetupProper ty enumeration type is used by the GetProperty and SetProperty methods on the
ICertificateEnrollmentPolicyServerSetup interface to specify the type of property information to retrieve or set.

Syntax
typedef enum __MIDL___MIDL_itf_casetup_0000_0005_0001 {
ENUM_CEPSETUPPROP_AUTHENTICATION = 0,
ENUM_CEPSETUPPROP_SSLCERTHASH = 1,
ENUM_CEPSETUPPROP_URL = 2,
ENUM_CEPSETUPPROP_KEYBASED_RENEWAL = 3
} CEPSetupProperty;

Constants

ENUM_CEPSETUPPROP_AUTHENTICATION
Value: 0
The property value contains the type of authentication procedure used.

ENUM_CEPSETUPPROP_SSLCERTHASH
Value: 1
The property value contains the hash of the certificate, if any, used for authentication.

ENUM_CEPSETUPPROP_URL
Value: 2
The property value contains the Certificate Enrollment Policy (CEP) Web Service URL.

ENUM_CEPSETUPPROP_KEYBASED_RENEWAL
Value: 3
The property value indicates whether to set up the Enrollment Policy Server in a mode that returns policies for
KeyBasedRenewal templates only.

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Header casetup.h

See also
GetProperty
ICertificateEnrollmentPolicyServerSetup
SetProperty
 CESSetupProperty enumeration (casetup.h)
7/2/2022 • 2 minutes to read • Edit Online

The CESSetupProper ty enumeration type is used by the GetProperty and SetProperty methods on the
ICertificateEnrollmentServerSetup interface to specify the type of property information to retrieve or set.

Syntax
typedef enum __MIDL___MIDL_itf_casetup_0000_0004_0001 {
ENUM_CESSETUPPROP_USE_IISAPPPOOLIDENTITY = 0,
ENUM_CESSETUPPROP_CACONFIG = 1,
ENUM_CESSETUPPROP_AUTHENTICATION = 2,
ENUM_CESSETUPPROP_SSLCERTHASH = 3,
ENUM_CESSETUPPROP_URL = 4,
ENUM_CESSETUPPROP_RENEWALONLY = 5,
ENUM_CESSETUPPROP_ALLOW_KEYBASED_RENEWAL = 6
} CESSetupProperty;

Constants

ENUM_CESSETUPPROP_USE_IISAPPPOOLIDENTITY
Value: 0
The property value specifies whether the server context is ApplicationPoolIdentity .

ENUM_CESSETUPPROP_CACONFIG
Value: 1
The property value contains a certification authority (CA) configuration string.

ENUM_CESSETUPPROP_AUTHENTICATION
Value: 2
The property value specifies the type of authentication procedure used.

ENUM_CESSETUPPROP_SSLCERTHASH
Value: 3
The property value contains a hash of the certificate used for authentication.

ENUM_CESSETUPPROP_URL
Value: 4
The property value contains the Certificate Enrollment Web Service (CES) URL.

ENUM_CESSETUPPROP_RENEWALONLY
Value: 5
The property value specifies whether CES can process only certificate renewals.

ENUM_CESSETUPPROP_ALLOW_KEYBASED_RENEWAL
Value: 6

Requirements
 Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Header casetup.h

See also
GetProperty
ICertificateEnrollmentServerSetup
SetProperty
 ICertificateEnrollmentPolicyServerSetup interface
(casetup.h)
7/2/2022 • 2 minutes to read • Edit Online

The ICer tificateEnrollmentPolicySer verSetup interface represents the Certificate Enrollment Policy (CEP)
Web Service within Active Directory Certificate Services (ADCS). The service enables users and computers to
obtain certificate enrollment policy information even when a computer is not a member of the domain or if a
domain-joined computer is temporarily outside the security boundary of the corporate network.
A related interface, ICertificateEnrollmentServerSetup, represents the Certificate Enrollment Web Service (CES)
and enables users and computers to enroll for and renew certificates. CEP and CES work together to provide
policy-based certificate enrollment.

Inheritance
The ICer tificateEnrollmentPolicySer verSetup interface inherits from the IDispatch interface.
ICer tificateEnrollmentPolicySer verSetup also has these types of members:

Methods
The ICer tificateEnrollmentPolicySer verSetup interface has these methods.

ICertificateEnrollmentPolicyServerSetup::get_ErrorString

Retrieves a string that contains additional information about Certificate Enrollment Policy (CEP) Web Service setup failure.

ICertificateEnrollmentPolicyServerSetup::GetProperty

Retrieves a CEPSetupProperty enumeration value for the Certificate Enrollment Policy (CEP) Web Service configuration.

ICertificateEnrollmentPolicyServerSetup::InitializeInstallDefaults

Initializes the ICertificateEnrollmentPolicyServerSetup object with a default configuration.

ICertificateEnrollmentPolicyServerSetup::Install

Installs the Certificate Enrollment Policy (CEP) Web Service configured by the ICertificateEnrollmentPolicyServerSetup object.

ICertificateEnrollmentPolicyServerSetup::SetProperty

Specifies a CEPSetupProperty enumeration value for the Certificate Enrollment Policy (CEP) Web Service configuration.

ICertificateEnrollmentPolicyServerSetup::UnInstall

Removes the Certificate Enrollment Policy (CEP) Web Service.

Requirements
 Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Target Platform Windows

Header casetup.h

See also
ICertificateEnrollmentServerSetup
IDispatch
 ICertificateEnrollmentPolicyServerSetup::get_ErrorString
method (casetup.h)
7/2/2022 • 2 minutes to read • Edit Online

The ErrorString property retrieves a string that contains additional information about Certificate Enrollment
Policy (CEP) Web Service setup failure.
This property is read-only.

Syntax
HRESULT get_ErrorString(
BSTR *pVal
);

Parameters
pVal

Return value
None

Remarks
Calling any method on the ICertificateEnrollmentPolicyServerSetup interface resets this property value to an
empty error string.

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Target Platform Windows

Header casetup.h

DLL Certocm.dll

See also
ICertificateEnrollmentPolicyServerSetup
 ICertificateEnrollmentPolicyServerSetup::GetProperty
method (casetup.h)
7/2/2022 • 2 minutes to read • Edit Online

The GetProper ty method retrieves a CEPSetupProperty enumeration value for the Certificate Enrollment Policy
(CEP) Web Service configuration.

Syntax
HRESULT GetProperty(
[in] CEPSetupProperty propertyId,
[out] VARIANT *pPropertyValue
);

Parameters
[in] propertyId

A value of the CEPSetupProperty enumeration that specifies the property value to set. The following values are
valid.

VA L UE DESC RIP T IO N

ENUM_CEPSETUPPROP_AUTHENTICATION The pPropertyValue parameter contains a value that

identifies the type of authentication to be used.

ENUM_CEPSETUPPROP_SSLCERTHASH The pPropertyValue parameter contains a hash of the

certificate, if any, used during authentication.

ENUM_CEPSETUPPROP_KEYBASED_RENEWAL The pPropertyValue parameter specifies whether to set up

the Enrollment Policy Server in a mode that returns policies
for KeyBasedRenewal templates only.

ENUM_CEPSETUPPROP_URL Contains the CEP service URL. If the GetProper ty method

returns successfully, the pPropertyValue argument will
contain a VT_BSTR subtype that contains a URL of the form
"https://computerDNSname/ADPolicyProvider_cep_
AuthenticationType/service.svc/cep" where the
authentication type can be one of the following:
kerberos
usernamepassword
certificate

[out] pPropertyValue

A pointer to a VARIANT variable that contains the property value.

If you specify ENUM_CEPSETUPPROP_AUTHENTICATION in the propertyId parameter, the pPropertyValue
parameter will contain one of the following constants if the GetProper ty method returns successfully:
X509AuthKerberos
 X509AuthUsername
X509AuthCer tificate
If you specify ENUM_CEPSETUPPROP_SSLCERTHASH in the propertyId parameter, the pPropertyValue
parameter will contain a VT_BSTR subtype that contains the hash if the GetProper ty method returns
successfully.
If you specify ENUM_CEPSETUPPROP_AUTHENTICATION in the propertyId parameter, the pPropertyValue
parameter contains the authentication procedure.
If you specify ENUM_CEPSETUPPROP_URL in the propertyId parameter, the pPropertyValue parameter
contains the Certificate Enrollment Policy (CEP) Web Service URL.
If you specify ENUM_CEPSETUPPROP_KEYBASED_RENEWAL in the propertyId parameter, you must set the
pPropertyValue parameter to the VT_BOOL subtype that indicates whether to set up the Enrollment Policy
Server in a mode that returns policies for KeyBasedRenewal templates only.

Return value
RET URN C O DE DESC RIP T IO N

The propertyId argument is not a member of the

E_INVALIDARG CEPSetupProperty enumeration type.

The pPropertyValue parameter cannot be NULL .

E_POINTER

The ICertificateEnrollmentPolicyServerSetup object has not

HRESULT_FROM_WIN32(ERROR_INVALID_STATE) been initialized.
The ErrorString property value is set to "The setup object
has not been initialized. Please initialize the setup object
with the InitializeInstallDefaults method."

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Target Platform Windows

Header casetup.h

DLL Certocm.dll

See also
ICertificateEnrollmentPolicyServerSetup
InitializeInstallDefaults
SetProperty
 ICertificateEnrollmentPolicyServerSetup::InitializeInstallDefaults
method (casetup.h)
7/2/2022 • 2 minutes to read • Edit Online

The InitializeInstallDefaults method initializes the ICertificateEnrollmentPolicyServerSetup object with a

default configuration.

Syntax
HRESULT InitializeInstallDefaults();

Return value
RET URN C O DE DESC RIP T IO N

A user must be an administrator of the domain root or the

E_ACCESSDENIED enterprise. A computer must be joined to the domain.
If the user is not a domain root or enterprise
administrator, the ErrorString property is set to:
"You must be a member of the Enterprise Admins group
to run Setup."
If the computer is not joined to the domain, the
ErrorString property is set to:
"The Certificate Enrollment Web Service or Certificate
Enrollment Policy Web Service cannot be installed on a
computer that is not a member of a domain."

The ICertificateEnrollmentPolicyServerSetup object has

HRESULT_FROM_WIN32(ERROR_INVALID_STATE) already been initialized. The ErrorString property is set to:
"The setup object has already been initialized. This object
cannot be initialized more than once."

Remarks
This method performs the following actions:
Sets the default authentication procedure to Kerberos. You can call SetProperty to change the authentication
method.
Sets the default URL to https://computerDNSname/ADPolicyProvider_CEP_Kerberos/service.svc/CEP.
Checks to determine whether the CEP service is installed on a computer running Windows Server 2008 R2.

Note If this check fails, the method sets the ErrorString property to "The Certificate Enrollment Web Service or
Certificate Enrollment Policy Web Service must be installed on a member server in an Active Directory forest in which
the Windows Server 2008 R2 version of ADPrep /forestprep has been successfully run."

You must call the InitializeInstallDefaults method before calling any method other than UnInstall. Call the Install
method to install the configured CEP service. Call the UnInstall method on a new
ICertificateEnrollmentPolicyServerSetup object to remove the service.

Requirements
 Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Target Platform Windows

Header casetup.h

DLL Certocm.dll

See also
CEPSetupProperty
ICertificateEnrollmentPolicyServerSetup
SetProperty
 ICertificateEnrollmentPolicyServerSetup::Install
method (casetup.h)
7/2/2022 • 3 minutes to read • Edit Online

The Install method installs the Certificate Enrollment Policy (CEP) Web Service configured by the
ICertificateEnrollmentPolicyServerSetup object.

Syntax
HRESULT Install();

Return value
RET URN C O DE DESC RIP T IO N

The name specified for the event tracing directory or the

E_UNEXPECTED application directory already existed but represented a file
rather than a directory.

The CEP application already exists. For more information, see

HRESULT_FROM_WIN32(ERROR_ALREADY_EXISTS) Remarks.

The ICertificateEnrollmentPolicyServerSetup object has not

HRESULT_FROM_WIN32(ERROR_INVALID_STATE) been initialized.
The ErrorString property value is set to "The setup object
has not been initialized. Please initialize the setup object
with the InitializeInstallDefaults method."

Remarks
This function performs the following actions:
Initializes Windows Management Instrumentation (WMI).
Validates the CEP configuration by verifying that an application with the same name does not already exist.
The application name is part of the CEP URL where the URL is of the form "https://computerDNSname
/ADPolicyProvider_cep_AuthenticationType/service.svc/cep". The application name consists of
"ADPolicyProvider_cep_AuthenticationType" where AuthenticationType can be one of the following:
kerberos
usernamepassword
certificate

Note If an application with the same name exists, the ErrorString property is set to "Setup could not add this role
service because it already exists in the default website. Please remove the existing role service or select a different
certification authority (CA) or authentication type."

Creates the %windir%\systemdata\cep\ADPolicyProvider_cep_AuthenticationType application directory.

 Note This method does not return an error if the name specified already exists as a directory, but if the specified
name exists as a file or if some other error occurred, the method returns a failure HRESULT and sets the ErrorString
property to "Failed to create the directory %1."

Creates the %windir%\systemdata\cep\ADPolicyProvider_cep_AuthenticationType\Traces event tracing

directory.
Creates the Web.config and Service.svc files and writes them to the application directory. If the files already
exist, they are overwritten.
Creates an IIS application pool. By default, the pool runs under the ApplicationPoolIdentity account.
Creates the application in the default website.
Creates a secure (https) binding to port 443 and sets the certificate hash if one has been specified during
configuration by calling the SetProperty method.
Sets IIS authentication to anonymous if you called SetProperty and specified X509AuthCertificate or
X509AuthUsername in the pPropertyValue argument. Sets authentication to Windows if you called
SetProper ty and specified X509AuthKerberos.
Sets SSL flags depending on the type of authentication chosen during configuration. The default flags for all
authentication types are SSL (require secure channel) and SSL_128 (128-bit encryption). Additionally, if you
specify X509AuthCertificate, the SSL_REQUIRE_CERT and SSL_NEGOTIATE_CERT flags are set.
Adds read and write access to the event tracing directory.
Updates the security descriptor of the Deleted Objects container in Active Directory to permit access by the
computer and/or the application pool. This enables the CEP service to notify the certification authority when
a relevant Active Directory object is deleted. If Active Directory is installed on a domain controller, both the
computer and application pool are allowed to access the Deleted Objects container. If Active Directory is not
installed on a domain controller, only the computer is allowed access.

Note If access to the Deleted Objects container fails, the method returns a failure HRESULT and sets the ErrorString
property to "Setup cannot give the Certificate Enrollment Policy Web Service account List permission on the ""Deleted
Objects"" container. The web service will not be able to detect deletion of Active Directory objects such as certificate
templates. To complete Setup, a member of the Domain Admins group must manually give the Certificate Enrollment
Policy Web Service account List permission on the ""Deleted Objects"" container in Active Directory Domain Services
(AD DS)."

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Target Platform Windows

Header casetup.h

DLL Certocm.dll

See also
ICertificateEnrollmentPolicyServerSetup
SetProperty
 ICertificateEnrollmentPolicyServerSetup::SetProperty
method (casetup.h)
7/2/2022 • 2 minutes to read • Edit Online

The SetProper ty method specifies a CEPSetupProperty enumeration value for the Certificate Enrollment Policy
(CEP) Web Service configuration.

Syntax
HRESULT SetProperty(
[in] CEPSetupProperty propertyId,
[in] VARIANT *pPropertyValue
);

Parameters
[in] propertyId

A value of the CEPSetupProperty enumeration that specifies the property value to set. The following values are
valid.

VA L UE DESC RIP T IO N

ENUM_CEPSETUPPROP_AUTHENTICATION The pPropertyValue parameter contains a value that

identifies the type of authentication to be used.

ENUM_CEPSETUPPROP_SSLCERTHASH The pPropertyValue parameter contains a hash of the

certificate, if any, used during authentication.
ENUM_CEPSETUPPROP_AUTHENTICATION must be set
to X509AuthCertificate.

ENUM_CEPSETUPPROP_KEYBASED_RENEWAL The pPropertyValue parameter specifies whether to set up

the Enrollment Policy Server in a mode that returns policies
for KeyBasedRenewal templates only.

ENUM_CEPSETUPPROP_URL You cannot specify this value.

[in] pPropertyValue

A pointer to a VARIANT variable that contains the property value.

If you specify ENUM_CEPSETUPPROP_AUTHENTICATION in the propertyId parameter, the VARIANT
subtype must be VT_I2 , VT_I4 or VT_UII4 , and the pPropertyValue argument must be one of the following
constants:
X509AuthKerberos
X509AuthUsername
X509AuthCer tificate
If you specify ENUM_CEPSETUPPROP_SSLCERTHASH in the propertyId parameter, you must set the
pPropertyValue parameter to a VT_BSTR subtype that contains a hash of the certificate used for authentication.
If you specify ENUM_CEPSETUPPROP_AUTHENTICATION in the propertyId parameter, the pPropertyValue
parameter contains the authentication procedure.
If you specify ENUM_CEPSETUPPROP_URL in the propertyId parameter, the pPropertyValue parameter
contains the Certificate Enrollment Policy (CEP) Web Service URL.
If you specify ENUM_CEPSETUPPROP_KEYBASED_RENEWAL in the propertyId parameter, you must set the
pPropertyValue parameter to the VT_BOOL subtype that indicates whether to set up the Enrollment Policy
Server in a mode that returns policies for KeyBasedRenewal templates only.

Return value
RET URN C O DE DESC RIP T IO N

The propertyId argument is not a member of the

E_INVALIDARG CEPSetupProperty enumeration type or you have tried to
set the ENUM_CEPSETUPPROP_URL value.

The pPropertyValue parameter cannot be NULL .

E_POINTER

The ICertificateEnrollmentPolicyServerSetup object has not

HRESULT_FROM_WIN32(ERROR_INVALID_STATE) been initialized.
The ErrorString property value is set to "The setup object
has not been initialized. Please initialize the setup object
with the InitializeInstallDefaults method."

If you are setting the

HRESULT_FROM_WIN32(ERROR_CLUSTER_PROPERTY ENUM_CEPSETUPPROP_AUTHENTICATION property,
_DATA_TYPE_MISMATCH) the VARIANT subtype must be VT_I2 , VT_I4 , or VT_UI4 .

Remarks
You must call InitializeInstallDefaults before calling the SetProper ty method.

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Target Platform Windows

Header casetup.h

DLL Certocm.dll

See also
GetProperty
ICertificateEnrollmentPolicyServerSetup
InitializeInstallDefaults
 ICertificateEnrollmentPolicyServerSetup::UnInstall
method (casetup.h)
7/2/2022 • 2 minutes to read • Edit Online

The UnInstall method removes the Certificate Enrollment Policy (CEP) Web Service.

Syntax
HRESULT UnInstall(
[in, optional] VARIANT *pAuthKeyBasedRenewal
);

Parameters
[in, optional] pAuthKeyBasedRenewal

A pointer to a VARIANT array that contains the authentication type and the optional KeyBasedRenewal values.
You can set the following values for authentication type in the first element of the array.
X509AuthKerberos
X509AuthUserName
X509AuthCertificate
The second (optional) element in the array value is VARIANT_TRUE for a KeyBasedRenewal CEP.

Return value
RET URN C O DE DESC RIP T IO N

The user must be a local administrator.

E_ACCESSDENIED
The ErrorString property value is set to "You have to be
the local machine administrator in order to run this
setup."

The ICertificateEnrollmentPolicyServerSetup object has been

HRESULT_FROM_WIN32(ERROR_INVALID_STATE)
initialized. An object is initialized when you successfully call
InitializeInstallDefaults.
The ErrorString property value is set to "The object has
been initialized. You cannot call UnInstall on an initialized
object."

Remarks
You can call this method to remove the CEP service. However, because you cannot call the UnInstall method on
an ICertificateEnrollmentPolicyServerSetup object that has already been initialized, you must create a new
ICer tificateEnrollmentPolicySer verSetup before calling UnInstall .
When the pAuthKeyBasedRenewal parameter is NULL, this function performs the following actions:
 Initializes Windows Management Instrumentation (WMI).
Attempts to delete the %Windir%\Systemdata\Cep directory and all application subdirectories that may exist.
For more information, see the Install Remarks section.
Attempts to delete the application pool and all applications in the pool.
Attempts to update the security descriptor of the Deleted Objects container in Active Directory to deny access
by the computer. For more information, see the Install Remarks section.
When the pAuthKeyBasedRenewal parameter contains values for the authentication type and KeyBasedRenewal,
this function performs the actions in the previous list but it only deletes the application that corresponds to the
values set in pAuthKeyBasedRenewal and leaves other applications in place.

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Target Platform Windows

Header casetup.h

DLL Certocm.dll

See also
ICertificateEnrollmentPolicyServerSetup
InitializeInstallDefaults
Install
 ICertificateEnrollmentServerSetup interface
(casetup.h)
7/2/2022 • 2 minutes to read • Edit Online

The ICer tificateEnrollmentSer verSetup interface represents the Certificate Enrollment Web Service (CES)
within Active Directory Certificate Services (ADCS). The service enables users and computers to enroll for and
renew certificates under the following conditions:
Computers and users can enroll, manually renew, and automatically renew certificates when joined to a
domain.
Users can automatically renew, enroll, and manually renew when not a member of the domain or when they
are temporarily outside the security boundary of the organization.
Computers can enroll and manually renew but cannot automatically renew when they are not a member of
the domain or when they are temporarily outside the security boundary of the organization.
A related interface, ICertificateEnrollmentPolicyServerSetup, represents the Certificate Enrollment Policy (CEP)
Web Service and enables users and computers to obtain certificate enrollment policy information. CEP and CES
work together to provide policy-based certificate enrollment.

Inheritance
The ICer tificateEnrollmentSer verSetup interface inherits from the IDispatch interface.
ICer tificateEnrollmentSer verSetup also has these types of members:

Methods
The ICer tificateEnrollmentSer verSetup interface has these methods.

ICertificateEnrollmentServerSetup::get_ErrorString

Retrieves a string that contains additional information about Certificate Enrollment Web Service (CES) setup failure.

ICertificateEnrollmentServerSetup::GetProperty

Retrieves a CESSetupProperty enumeration value for the Certificate Enrollment Web Service (CES) configuration.

ICertificateEnrollmentServerSetup::InitializeInstallDefaults

Initializes the ICertificateEnrollmentServerSetup object with a default configuration.

ICertificateEnrollmentServerSetup::Install

Installs the Certificate Enrollment Web Service (CES) configured by the ICertificateEnrollmentServerSetup object.

ICertificateEnrollmentServerSetup::SetApplicationPoolCredentials

Specifies user account information for the application pool in which the Certificate Enrollment Web Service (CES) runs.
 ICertificateEnrollmentServerSetup::SetProperty

Specifies a CESSetupProperty enumeration value for the Certificate Enrollment Web Service (CES) configuration.

ICertificateEnrollmentServerSetup::UnInstall

Removes the Certificate Enrollment Web Service (CES).

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Target Platform Windows

Header casetup.h

See also
ICertificateEnrollmentPolicyServerSetup
IDispatch
 ICertificateEnrollmentServerSetup::get_ErrorString
method (casetup.h)
7/2/2022 • 2 minutes to read • Edit Online

The ErrorString property retrieves a string that contains additional information about Certificate Enrollment
Web Service (CES) setup failure.
This property is read-only.

Syntax
HRESULT get_ErrorString(
BSTR *pVal
);

Parameters
pVal

Return value
None

Remarks
Calling any method on the ICertificateEnrollmentServerSetup interface resets this property value to an empty
error string.

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Target Platform Windows

Header casetup.h

DLL Certocm.dll

See also
ICertificateEnrollmentServerSetup
 ICertificateEnrollmentServerSetup::GetProperty
method (casetup.h)
7/2/2022 • 2 minutes to read • Edit Online

The GetProper ty method retrieves a CESSetupProperty enumeration value for the Certificate Enrollment Web
Service (CES) configuration.

Syntax
HRESULT GetProperty(
[in] CESSetupProperty propertyId,
[out] VARIANT *pPropertyValue
);

Parameters
[in] propertyId

A CESSetupProperty enumeration value that specifies the property value to retrieve. For more information, see
Remarks.
[out] pPropertyValue

A pointer to a VARIANT variable that contains the property value.

Return value
RET URN C O DE DESC RIP T IO N

The propertyId argument is not a member of the

E_INVALIDARG CESSetupProperty enumeration type.

The pPropertyValue parameter cannot be NULL .

E_POINTER

The ICertificateEnrollmentServerSetup object has not been

HRESULT_FROM_WIN32(ERROR_INVALID_STATE) initialized.
The ErrorString property value is set to "The setup object
has not been initialized. Please initialize the setup object
with the InitializeInstallDefaults method."

Remarks
The CESSetupProperty enumeration type contains the following values:
ENUM_CESSETUPPROP_USE_IISAPPPOOLIDENTITY
ENUM_CESSETUPPROP_CACONFIG
ENUM_CESSETUPPROP_AUTHENTICATION
ENUM_CESSETUPPROP_SSLCERTHASH
 ENUM_CESSETUPPROP_URL
ENUM_CESSETUPPROP_RENEWALONLY
These values have the following meanings:
The ENUM_CESSETUPPROP_USE_IISAPPPOOLIDENTITY property is a VT_BOOL value that specifies
whether the server context is ApplicationPoolIdentity .
The ENUM_CESSETUPPROP_CACONFIG property contains a certification authority (CA) configuration
string (VT_BSTR ) of the form computerDNSname/CAName where computerDNSname is the fully qualified
DNS name of the server and CAName is the common name of the CA.
The ENUM_CESSETUPPROP_AUTHENTICATION property specifies the type of authentication procedure
used. If the GetProper ty method returns successfully, the pPropertyValue argument will contain one of the
following constants:
X509AuthKerberos
X509AuthUsername
X509AuthCertificate
The ENUM_CESSETUPPROP_SSLCERTHASH property contains the hash (VT_BSTR ) of the certificate
used during authentication. The ENUM_CESSETUPPROP_AUTHENTICATION property must be set to
X509AuthCertificate.
The ENUM_CESSETUPPROP_URL property contains the CES service URL. If the GetProper ty method
returns successfully, the pPropertyValue argument will contain a VT_BSTR subtype that contains a URL of
the form "https://computerDNSname/ADPolicyProvider_ces_AuthenticationType/service.svc/ces" where the
authentication type can be one of the following:
kerberos
usernamepassword
certificate
The ENUM_CESSETUPPROP_RENEWALONLY property is a VT_BOOL value that specifies whether CES
can process only certificate renewals.

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Target Platform Windows

Header casetup.h

DLL Certocm.dll

See also
ICertificateEnrollmentServerSetup
 ICertificateEnrollmentServerSetup::InitializeInstallDefaults
method (casetup.h)
7/2/2022 • 2 minutes to read • Edit Online

The InitializeInstallDefaults method initializes the ICertificateEnrollmentServerSetup object with a default

configuration.

Syntax
HRESULT InitializeInstallDefaults();

Return value
RET URN C O DE DESC RIP T IO N

A user must be an administrator of the domain root or the

E_ACCESSDENIED enterprise. A computer must be joined to the domain.
If the user is not a domain root or enterprise
administrator, the ErrorString property is set to:
"You must be a member of the Enterprise Admins group
to run Setup."
If the computer is not joined to the domain, the
ErrorString property is set to:
"The Certificate Enrollment Web Service or Certificate
Enrollment Policy Web Service cannot be installed on a
computer that is not a member of a domain."

The ICertificateEnrollmentServerSetup object has already

HRESULT_FROM_WIN32(ERROR_INVALID_STATE) been initialized. The ErrorString property is set to:
"The setup object has already been initialized. This object
cannot be initialized more than once."

Remarks
This method performs the following actions:
Determines whether the ICertificateEnrollmentServerSetup object has already been initialized.

Note If this check fails, the method sets the ErrorString property to "The setup object has already been initialized.
This object cannot be initialized more than once."

Determines whether the user is an administrator of the domain root or the enterprise.

Note If this check fails, the method sets the ErrorString property to "You must be a member of the Enterprise Admins
group to run Setup."
 Determines whether the computer is joined to the domain.

Note If this check fails, the method sets the ErrorString property to "The Certificate Enrollment Web Service or
Certificate Enrollment Policy Web Service cannot be installed on a computer that is not a member of a domain."

Sets the default authentication procedure to Kerberos. You can call SetProperty to change the authentication
method.
Determines whether CES is installed on a computer running Windows Server 2008 R2.

Note If this check fails, the method sets the ErrorString property to "The Certificate Enrollment Web Service or
Certificate Enrollment Policy Web Service must be installed on a member server in an Active Directory forest in which
the Windows Server 2008 R2 version of ADPrep /forestprep has been successfully run."

Sets the default server context to the ApplicationPoolIdentity built-in account.

Sets the ENUM_CESSETUPPROP_RENEWALONLY property to FALSE .
Sets the ENUM_CESSETUPPROP_URL property is to "https://computerDNSname/SanitizedCAShortName
_CES_Kerberos/service.svc/ces" if a valid certification authority (CA) configuration exists. If a valid
configuration does not exist, the ENUM_CESSETUPPROP_URL property is not set. The
SanitizedCAShortName is the sanitized short name of the CA. For more information about sanitized names,
see GetConfig.

Note If the certification authority is a standalone CA, the ErrorString property is set to "The Certificate Enrollment
Web Service cannot be used with a standalone certification authority (CA). It can only be used with an enterprise CA."

You must call the InitializeInstallDefaults method before calling any method other than UnInstall. Call the Install
method to install the configured service. Call UnInstall on a new ICertificateEnrollmentServerSetup object to
remove the service.

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Target Platform Windows

Header casetup.h

DLL Certocm.dll

See also
CESSetupProperty
ICertificateEnrollmentServerSetup
 ICertificateEnrollmentServerSetup::Install method
(casetup.h)
7/2/2022 • 3 minutes to read • Edit Online

The Install method installs the Certificate Enrollment Web Service (CES) configured by the
ICertificateEnrollmentServerSetup object.

Syntax
HRESULT Install();

Return value
RET URN C O DE DESC RIP T IO N

The name specified for the event tracing directory or the

E_UNEXPECTED application directory already existed but represented a file
rather than a directory.

The CES application already exists. For more information, see

HRESULT_FROM_WIN32(ERROR_ALREADY_EXISTS) Remarks

The ICertificateEnrollmentServerSetup object has not been

HRESULT_FROM_WIN32(ERROR_INVALID_STATE) initialized.
The ErrorString property value is set to "The setup object
has not been initialized. Please initialize the setup object
with the InitializeInstallDefaults method."

Remarks
This function performs the following actions:
Initializes Windows Management Instrumentation (WMI).
Validates the CES configuration by verifying that an application with the same name does not already exist.
The application name is part of the CES URL where the URL is of the form "https://computerDNSname/
SanitizedCAShortName_ces_AuthenticationType/service.svc/ces". The application name consists of "
SanitizedCAShortName_ces_AuthenticationType" where AuthenticationType can be one of the following:
kerberos
usernamepassword
certificate

Note If an application with the same name exists, the ErrorString property is set to "Setup could not add this role
service because it already exists in the default website. Please remove the existing role service or select a different
certification authority (CA) or authentication type."

Creates the %windir%\systemdata\ces\SanitizedCAShortName_ces_AuthenticationType application directory.

 Note This method does not return an error if the name specified already exists as a directory, but if the specified
name exists as a file or if some other error occurred, the method returns a failure HRESULT and sets the ErrorString
property to "Failed to create the directory %1."

Creates the %windir%\systemdata\ces\SanitizedCAShortName_ces_AuthenticationType\Traces event tracing

directory.
Creates the Web.config and Service.svc files and writes them to the application directory. If the files already
exist, they are overwritten.
Creates an IIS application pool. By default, the pool runs under the ApplicationPoolIdentity account. To use
a different identity, you must manually change it after the CES role has been installed.
Creates the application in the default website.
Creates a secure (https) binding to port 443 and sets the certificate hash if one was specified during
configuration.
Sets IIS authentication to anonymous if you called SetProperty and specified X509AuthCertificate or
X509AuthUsername in the pPropertyValue argument. Sets authentication to Windows if you called
SetProper ty and specified X509AuthKerberos.
Sets SSL flags depending on the type of authentication chosen during configuration. The default flags for all
authentication types are SSL (require secure channel) and SSL_128 (128-bit encryption). Additionally, if you
specify X509AuthCertificate, the SSL_REQUIRE_CERT and SSL_NEGOTIATE_CERT flags are set.
Adds read and write access to the event tracing directory.
Updates the security descriptor of the Deleted Objects container in Active Directory to permit access by the
computer and/or the application pool. This enables CES to notify the certification authority when a relevant
Active Directory object is deleted. If Active Directory resides on a domain controller, both the computer and
application pool are allowed to access the Deleted Objects container. If Active Directory does not reside on a
domain controller, only the computer is allowed access.

Note If access to the Deleted Objects container fails, the method returns a failure HRESULT and sets the ErrorString
property to "Setup cannot give the Certificate Enrollment Policy Web Service account List permission on the ""Deleted
Objects"" container. The web service will not be able to detect deletion of Active Directory objects such as certificate
templates. To complete Setup, a member of the Domain Admins group must manually give the Certificate Enrollment
Policy Web Service account List permission on the ""Deleted Objects"" container in Active Directory Domain Services
(AD DS)."

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Target Platform Windows

Header casetup.h

DLL Certocm.dll
See also
ICertificateEnrollmentServerSetup
 ICertificateEnrollmentServerSetup::SetApplicationPoolCredentials
method (casetup.h)
7/2/2022 • 2 minutes to read • Edit Online

The SetApplicationPoolCredentials method specifies user account information for the application pool in
which the Certificate Enrollment Web Service (CES) runs.

Syntax
HRESULT SetApplicationPoolCredentials(
[in] const BSTR bstrUsername,
[in] const BSTR bstrPassword
);

Parameters
[in] bstrUsername

A BSTR that contains the username for the account.

[in] bstrPassword

A BSTR that contains the account password.

Return value
RET URN C O DE DESC RIP T IO N

The bstrUsername and bstrPassword arguments cannot be

E_INVALIDARG NULL or empty.

The ICertificateEnrollmentServerSetup object has not been

HRESULT_FROM_WIN32(ERROR_INVALID_STATE) initialized.
The ErrorString property value is set to "The setup object
has not been initialized. Please initialize the setup object
with the InitializeInstallDefaults method."

Remarks
The SetApplicationPoolCredentials method determines whether the user credentials are valid and whether
the account is a member of the IIS_IUSRS group. If an error is encountered, the ErrorString property can be set
to any of the following:
"Setup is unable to obtain security information for the account."
"Setup is unable to check the membership of the account."
"The account is not a member of the local machine's IIS_IUSRS group."
"Fail to retrieve the DNS name of the computer."
"The account should be a domain account. Local account is not allowed."

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

 Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Target Platform Windows

Header casetup.h

DLL Certocm.dll

See also
ICertificateEnrollmentServerSetup
 ICertificateEnrollmentServerSetup::SetProperty
method (casetup.h)
7/2/2022 • 2 minutes to read • Edit Online

The SetProper ty method specifies a CESSetupProperty enumeration value for the Certificate Enrollment Web
Service (CES) configuration.

Syntax
HRESULT SetProperty(
[in] CESSetupProperty propertyId,
[in] VARIANT *pPropertyValue
);

Parameters
[in] propertyId

A CESSetupProperty enumeration value that specifies the property value to retrieve.

[in] pPropertyValue

A pointer to a VARIANT variable that contains the property value.

Return value
RET URN C O DE DESC RIP T IO N

The propertyId argument is not a member of the

E_INVALIDARG CESSetupProperty enumeration type.
Also, if you are setting the
ENUM_CESSETUPPROP_AUTHENTICATION
property, you must specify one of the following values in
the pPropertyValue argument:
X509AuthKerberos
X509AuthUsername
X509AuthCer tificate

The pPropertyValue parameter cannot be NULL .

E_POINTER

The ICertificateEnrollmentServerSetup object has not been

HRESULT_FROM_WIN32(ERROR_INVALID_STATE) initialized.
The ErrorString property value is set to "The setup object
has not been initialized. Please initialize the setup object
with the InitializeInstallDefaults method."
 If you are setting the
HRESULT_FROM_WIN32(ERROR_CLUSTER_PROPERTY ENUM_CESSETUPPROP_AUTHENTICATION property,
_DATA_TYPE_MISMATCH) the VARIANT subtype must be VT_I2 , VT_I4 , or VT_UI4 .

Remarks
You must call InitializeInstallDefaults before calling SetProper ty .
You cannot set the ENUM_CESSETUPPROP_URL property.
You cannot set the ENUM_CESSETUPPROP_USE_IISAPPPOOLIDENTITY if the WSEnrollmentServer
application pool already exists and WMI has been initialized.
If you are setting the ENUM_CESSETUPPROP_AUTHENTICATION property, the VARIANT subtype must be
VT_I2 , VT_I4 or VT_UII4 , and the pPropertyValue argument must be one of the following constants:
X509AuthKerberos
X509AuthUsername
X509AuthCer tificate
You cannot set the ENUM_CESSETUPPROP_CACONFIG property if the target server is a standalone certification
authority. The ErrorString property will be set to "The Certificate Enrollment Web Service cannot be used with a
standalone certification authority (CA). It can only be used with an enterprise CA."
.

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Target Platform Windows

Header casetup.h

DLL Certocm.dll

See also
ICertificateEnrollmentServerSetup
 ICertificateEnrollmentServerSetup::UnInstall method
(casetup.h)
7/2/2022 • 2 minutes to read • Edit Online

The UnInstall method removes the Certificate Enrollment Web Service (CES).

Syntax
HRESULT UnInstall(
VARIANT *pCAConfig,
VARIANT *pAuthentication
);

Parameters
pCAConfig

This parameter is reserved for future use.

pAuthentication

This parameter is reserved for future use.

Return value
RET URN C O DE DESC RIP T IO N

The user must be a local administrator.

E_ACCESSDENIED
The ErrorString property value is set to "You have to be
the local machine administrator in order to run this
setup."

The ICertificateEnrollmentServerSetup object has been

HRESULT_FROM_WIN32(ERROR_INVALID_STATE)
initialized. An object is initialized when you successfully call
InitializeInstallDefaults.
The ErrorString property value is set to "The object has
been initialized. You cannot call UnInstall on an initialized
object."

Remarks
You can call this method to remove CES. However, because you cannot call the UnInstall method on an
ICertificateEnrollmentServerSetup object that has already been initialized, you must create a new
ICer tificateEnrollmentSer verSetup before calling UnInstall .
This method attempts to delete all CES-related directories and the application pool. If it is unable to do so, it still
returns S_OK, but you can check the ErrorString property to determine what problems the method encountered.
This function performs the following actions:
 Initializes Windows Management Instrumentation (WMI).
Attempts to delete the %windir%\systemdata\ces directory and all application subdirectories that may exist.
For more information, see the Install Remarks section.
Attempts to delete the application pool and all applications in the pool.
Attempts to update the security descriptor of the Deleted Objects container in Active Directory to deny access
by the computer. For more information, see the Install Remarks section.

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Target Platform Windows

Header casetup.h

DLL Certocm.dll

See also
ICertificateEnrollmentServerSetup
 ICertSrvSetup interface (casetup.h)
7/2/2022 • 2 minutes to read • Edit Online

The ICer tSr vSetup interface defines functionality to install and uninstall Certification Authority (CA) and
Certification Authority Web Enrollment roles on a Certificate Services computer.
Microsoft provides an implementation of this interface in the CCer tSr vSetup class. For installation, you must
call the InitializeDefaults method before accessing any properties or calling any other methods on the
CCer tSr vSetup object.
In C++, you create an instance of this interface by calling the CoCreateInstance function with the
CLSID_CCer tSr vSetup class identifier.
Windows Ser ver 2008 Standard: The following services are not available:
Online Responder Service
Network Device Enrollment Service
In addition, the certification authority (CA) service has limited functionality:
V2 templates are not supported; therefore, autoenrollment is not supported.
Delegated enrollment agents are not supported.
Role separation is not supported.

Inheritance
The ICer tSr vSetup interface inherits from the IDispatch interface. ICer tSr vSetup also has these types of
members:

Methods
The ICer tSr vSetup interface has these methods.

ICertSrvSetup::CAImportPFX

Imports a certification authority (CA) certificate and its associated private key into the local computer store.

ICertSrvSetup::get_CAErrorId

Gets the ID for additional error information related to a failed certification authority (CA) specification.

ICertSrvSetup::get_CAErrorString

Gets the string data for additional error information related to a failed certification authority (CA) specification.

ICertSrvSetup::GetCASetupProperty

Gets a property value for a certification authority (CA) configuration.

ICertSrvSetup::GetExistingCACertificates

Gets the collection of CertSrvSetupKeyInformation objects that represent valid certification authority (CA) certificates currently
installed on the computer.

ICertSrvSetup::GetHashAlgorithmList

Gets the list of hash algorithms supported by the specified cryptographic service provider (CSP) for an asymmetric signature
key algorithm.

ICertSrvSetup::GetKeyLengthList

Gets the list of key lengths supported by the specified cryptographic service provider (CSP).

ICertSrvSetup::GetPrivateKeyContainerList

Gets the list of key container names stored by the specified cryptographic service provider (CSP) for asymmetric signature key
algorithms.

ICertSrvSetup::GetProviderNameList

Gets the list of cryptographic service providers (CSPs) that provide asymmetric key signature algorithms on the computer.

ICertSrvSetup::GetSupportedCATypes

Gets the types of certification authorities (CAs) that can be installed on a computer under the caller context.

ICertSrvSetup::InitializeDefaults

Initializes a CCertSrvSetup object with default values to enable installation of the Certification Authority role.

ICertSrvSetup::Install

Installs a role as configured in the CCertSrvSetup object.

ICertSrvSetup::IsPropertyEditable

Indicates to the caller whether a specified property can be edited.

ICertSrvSetup::PostUnInstall

Is not implemented and is reserved for future use.

ICertSrvSetup::PreUnInstall

Temporarily saves role-specific state information and then it uninstalls the role.

ICertSrvSetup::SetCADistinguishedName

Sets a certification authority (CA) common name and an optional distinguished name suffix.

ICertSrvSetup::SetCASetupProperty

Sets a property value for a certification authority (CA) configuration.

 ICertSrvSetup::SetDatabaseInformation

Sets the database related information for the certification authority (CA) role.

ICertSrvSetup::SetParentCAInformation

Sets the parent certification authority (CA) information for a subordinate CA configuration.

ICertSrvSetup::SetWebCAInformation

Sets the certification authority (CA) information for the Certification Authority Web Enrollment role.

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header casetup.h

See also
IDispatch
 ICertSrvSetup::CAImportPFX method (casetup.h)
7/2/2022 • 2 minutes to read • Edit Online

The CAImpor tPFX method imports a certification authority (CA) certificate and its associated private key into
the local computer store. This method does not change the state of the CCer tSr vSetup object.

Syntax
HRESULT CAImportPFX(
[in] const BSTR bstrFileName,
[in] const BSTR bstrPasswd,
[in] VARIANT_BOOL bOverwriteExistingKey,
[out] ICertSrvSetupKeyInformation **ppVal
);

Parameters
[in] bstrFileName

A string that contains the name of a PFX file used to import a private key.
[in] bstrPasswd

A string that contains a password for the PFX file.

[in] bOverwriteExistingKey

A value that indicates whether to overwrite an existing key of the same name.
[out] ppVal

The address of a pointer to an ICertSrvSetupKeyInformation interface that can be used to set properties of the
imported private key.

Return value
None

Remarks
The CAImpor tPFX method uses the input parameters to decrypt and decode a PFX file and then installs the key
and certificate in the local computer store. If the certificate satisfies the following criteria and after installation of
the key, the method returns an ICertSrvSetupKeyInformation object to the caller.
Contains an AT_SIGNATURE key that matches the key in the private key container.
Is self-signed or has basic constraints for a CA.
Passes chain validation but might have an offline revocation error.
If the PFX file contains multiple certificates and keys, CAImpor tPFX installs all of the certificates and keys; however,
the returned ICertSrvSetupKeyInformation object only contains properties of the last CA certificate in the file. When
the caller finishes using the ICer tSr vSetupKeyInformation object, the caller must release it by using the Release
method.
Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header casetup.h

DLL Certocm.dll

See also
ICertSrvSetup
 ICertSrvSetup::get_CAErrorId method (casetup.h)
7/2/2022 • 2 minutes to read • Edit Online

The CAErrorId property gets the ID for additional error information related to a failed certification authority
(CA) specification. Any method call on the parent object resets this property.
This property is read-only.

Syntax
HRESULT get_CAErrorId(
LONG *pVal
);

Parameters
pVal

Return value
None

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header casetup.h

DLL Certocm.dll

See also
ICertSrvSetup
 ICertSrvSetup::get_CAErrorString method
(casetup.h)
7/2/2022 • 2 minutes to read • Edit Online

The CAErrorString property gets the string data for additional error information related to a failed certification
authority (CA) specification. Any method call on the parent object resets this property.
This property is read-only.

Syntax
HRESULT get_CAErrorString(
BSTR *pVal
);

Parameters
pVal

Return value
None

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header casetup.h

DLL Certocm.dll

See also
ICertSrvSetup
 ICertSrvSetup::GetCASetupProperty method
(casetup.h)
7/2/2022 • 2 minutes to read • Edit Online

The GetCASetupProper ty method gets a property value for a certification authority (CA) configuration.

Syntax
HRESULT GetCASetupProperty(
[in] CASetupProperty propertyId,
[out] VARIANT *pPropertyValue
);

Parameters
[in] propertyId

A value of the CASetupProperty enumeration that specifies the type of property to get.
[out] pPropertyValue

A VARIANT value that specifies the property value. The VARIANT type depends on the property type. For more
information about the VARIANT type, see CASetupProperty.

Return value
None

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header casetup.h

DLL Certocm.dll

See also
ICertSrvSetup
 ICertSrvSetup::GetExistingCACertificates method
(casetup.h)
7/2/2022 • 2 minutes to read • Edit Online

The GetExistingCACer tificates method gets the collection of Cer tSr vSetupKeyInformation objects that
represent valid certification authority (CA) certificates currently installed on the computer. This method does not
change the state of the CCer tSr vSetup object.

Syntax
HRESULT GetExistingCACertificates(
[out] ICertSrvSetupKeyInformationCollection **ppVal
);

Parameters
[out] ppVal

The address of a pointer to an ICertSrvSetupKeyInformationCollection interface that can be used to access

information for the set of valid CA certificates installed in the "LocalMachine" store.

Return value
None

Remarks
The Cer tSr vSetupKeyInformationCollection object contains valid certificates. A certificate is considered
valid if it satisfies the following criteria:
Contains an AT_SIGNATURE key that matches the key in the private key container.
Is self-signed or has basic constraints for a CA.
Passes chain validation but might have an offline revocation error.

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header casetup.h

DLL Certocm.dll
See also
ICertSrvSetup
 ICertSrvSetup::GetHashAlgorithmList method
(casetup.h)
7/2/2022 • 2 minutes to read • Edit Online

The GetHashAlgorithmList method gets the list of hash algorithms supported by the specified cryptographic
service provider (CSP) for an asymmetric signature key algorithm. This method does not change the state of the
CCer tSr vSetup object.

Syntax
HRESULT GetHashAlgorithmList(
[in] const BSTR bstrProviderName,
[out] VARIANT *pVal
);

Parameters
[in] bstrProviderName

A string that contains the provider name. For key storage providers, this must be in the form
PublicKeyAlgorithmName#KeyStorageProviderName for example "RSA#Microsoft Software Key Storage
provider".
[out] pVal

A pointer to a VARIANT array of VT_BSTR types, where each string represents the name of a hash algorithm
supported by the CSP.

Return value
None

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header casetup.h

DLL Certocm.dll

See also
ICertSrvSetup
 ICertSrvSetup::GetKeyLengthList method
(casetup.h)
7/2/2022 • 2 minutes to read • Edit Online

The GetKeyLengthList method gets the list of key lengths supported by the specified cryptographic service
provider (CSP). This method does not change the state of the CCer tSr vSetup object.

Syntax
HRESULT GetKeyLengthList(
[in] const BSTR bstrProviderName,
[out] VARIANT *pVal
);

Parameters
[in] bstrProviderName

A string that contains the name of the provider. For key storage providers, this must be in the form
PublicKeyAlgorithmName#KeyStorageProviderName for example "RSA#Microsoft Software Key Storage
provider".
[out] pVal

A pointer to a VARIANT array of VT_UI4 types that correspond to the key lengths supported by the CSP.

Return value
None

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header casetup.h

DLL Certocm.dll

See also
ICertSrvSetup
 ICertSrvSetup::GetPrivateKeyContainerList method
(casetup.h)
7/2/2022 • 2 minutes to read • Edit Online

The GetPrivateKeyContainerList method gets the list of key container names stored by the specified
cryptographic service provider (CSP) for asymmetric signature key algorithms. This method does not change
the state of the CCer tSr vSetup object.

Syntax
HRESULT GetPrivateKeyContainerList(
[in] const BSTR bstrProviderName,
[out] VARIANT *pVal
);

Parameters
[in] bstrProviderName

A string that contains the name of the provider. For key storage providers, this must be in the form
PublicKeyAlgorithmName#KeyStorageProviderName for example "RSA#Microsoft Software Key Storage
provider".
[out] pVal

A pointer to a VARIANT array of VT_BSTR types, where each string represents the name of a key container
used by the specified CSP.

Return value
None

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header casetup.h

DLL Certocm.dll

See also
ICertSrvSetup
 ICertSrvSetup::GetProviderNameList method
(casetup.h)
7/2/2022 • 2 minutes to read • Edit Online

The GetProviderNameList method gets the list of cryptographic service providers (CSPs) that provide
asymmetric key signature algorithms on the computer. This method does not change the state of the
CCer tSr vSetup object.

Syntax
HRESULT GetProviderNameList(
[out] VARIANT *pVal
);

Parameters
[out] pVal

A pointer to a VARIANT array of VT_BSTR types, where each string represents the name of a CSP.

Return value
None

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header casetup.h

DLL Certocm.dll

See also
ICertSrvSetup
 ICertSrvSetup::GetSupportedCATypes method
(casetup.h)
7/2/2022 • 2 minutes to read • Edit Online

The GetSuppor tedCATypes method gets the types of certification authorities (CAs) that can be installed on a
computer under the caller context. This method does not change the state of the CCer tSr vSetup object.

Syntax
HRESULT GetSupportedCATypes(
[out] VARIANT *pCATypes
);

Parameters
[out] pCATypes

A pointer to a VARIANT array of VT_UI4 types that specify the supported CAs. The ENUM_CATYPES
enumeration specifies the possible values for the array.

Return value
None

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header casetup.h

DLL Certocm.dll

See also
ICertSrvSetup
 ICertSrvSetup::InitializeDefaults method (casetup.h)
7/2/2022 • 2 minutes to read • Edit Online

The InitializeDefaults method initializes a CCer tSr vSetup object with default values to enable installation of
the Certification Authority role. To install a CA role, this method must be called before using the
CCer tSr vSetup object. For information about default values, see CASetupProperty.

Syntax
HRESULT InitializeDefaults(
[in] VARIANT_BOOL bServer,
[in] VARIANT_BOOL bClient
);

Parameters
[in] bServer

A value that indicates whether a CA will be installed on the computer. A VARIANT_TRUE value indicates that the
role will be installed. Neither the Certification Authority nor Certification Authority Web Enrollment roles can be
previously installed on the computer.
[in] bClient

A value that indicates whether a Certification Authority Web Enrollment role will be installed on the computer. A
VARIANT_TRUE value indicates that the role will be installed. This role cannot be previously installed on the
computer.

Return value
None

Remarks
If the policy statement file "CAPolicy.inf" is installed, InitializeDefaults processes it.

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header casetup.h

DLL Certocm.dll
See also
ICertSrvSetup
 ICertSrvSetup::Install method (casetup.h)
7/2/2022 • 2 minutes to read • Edit Online

The Install method installs a role as configured in the CCer tSr vSetup object.

Syntax
HRESULT Install();

Return value
None

Remarks
The InitializeDefaults method must be called before calling this or any other method on a CCer tSr vSetup
object.
Unless the key already exists, the Install method creates a key for the certification authority (CA) certificate. If
the cryptographic service provider (CSP) requires interaction, it prompts the user.

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header casetup.h

DLL Certocm.dll

See also
ICertSrvSetup
 ICertSrvSetup::IsPropertyEditable method
(casetup.h)
7/2/2022 • 2 minutes to read • Edit Online

The IsProper tyEditable method indicates to the caller whether a specified property can be edited.

Syntax
HRESULT IsPropertyEditable(
[in] CASetupProperty propertyId,
[out] VARIANT_BOOL *pbEditable
);

Parameters
[in] propertyId

A CASetupProperty constant that specifies the type of property to query.

[out] pbEditable

A value that indicates whether the property can be edited.

Return value
None

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header casetup.h

DLL Certocm.dll

See also
ICertSrvSetup
 ICertSrvSetup::PostUnInstall method (casetup.h)
7/2/2022 • 2 minutes to read • Edit Online

The PostUnInstall method is not implemented and is reserved for future use.

Syntax
HRESULT PostUnInstall();

Return value
This method does not return a value.

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header casetup.h

DLL Certocm.dll

See also
ICertSrvSetup
 ICertSrvSetup::PreUnInstall method (casetup.h)
7/2/2022 • 2 minutes to read • Edit Online

The PreUnInstall method temporarily saves role-specific state information and then it uninstalls the role.

Syntax
HRESULT PreUnInstall(
[in] VARIANT_BOOL bClientOnly
);

Parameters
[in] bClientOnly

A value that indicates whether the caller wants to only uninstall the Certification Authority Web Enrollment role.
A value of VARIANT_TRUE specifies to only uninstall the Certification Authority Web Enrollment role. This only
applies if both the Certification Authority and Certification Authority Web Enrollment roles are installed on the
computer.

Return value
None

Remarks
The PreUnInstall method should be called before performing a role-specific uninstall.

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header casetup.h

DLL Certocm.dll

See also
ICertSrvSetup
 ICertSrvSetup::SetCADistinguishedName method
(casetup.h)
7/2/2022 • 2 minutes to read • Edit Online

The SetCADistinguishedName method sets a certification authority (CA) common name and an optional
distinguished name suffix.

Syntax
HRESULT SetCADistinguishedName(
[in] const BSTR bstrCADN,
[in] VARIANT_BOOL bIgnoreUnicode,
[in] VARIANT_BOOL bOverwriteExistingKey,
[in] VARIANT_BOOL bOverwriteExistingCAInDS
);

Parameters
[in] bstrCADN

A string that contains the name for a CA in the form CommonName,DistinguishedNameSuffix, where the
comma (,) and DistinguishedNameSuffix are optional.
The following table describes an example of a distinguished name, including the optional distinguished name
suffix, for the computer MyServer.

VA L UE M EA N IN G

Common name for the MyServer computer that belongs to

CN=mydomain-MyServer-CA the MyDomain domain.

Distinguished name suffix (optional)

DC=MyDomain,DC=MyCompany,DC=com

Distinguished name including the optional suffix

CN=MyDomain-MyServer-CA,DC=MyDomain,DC=
MyCompany,DC=com

[in] bIgnoreUnicode

A value that indicates whether to allow Unicode encoding of the name information. A value of VARIANT_TRUE
enables Unicode encoding.
[in] bOverwriteExistingKey

A value that indicates whether to allow the name in bstrCADN, even though a private key with the same name
exists on the computer. A value of VARIANT_TRUE enables the method to overwrite the existing key.
[in] bOverwriteExistingCAInDS

A value that indicates whether to allow the name in bstrCADN, even though a CA with the same distinguished
name exists in the directory service. A value of VARIANT_TRUE enables the method to overwrite the existing
directory service entry.

Return value
None

Remarks
Upon success, the SetCADistinguishedName method changes the ENUM_SETUPPROP_CANAME and
ENUM_SETUPPROP_CADSSUFFIX property values to reflect the bstrCADN name. For more information
about setup properties, see CASetupProperty.
Upon failure, the SetCADistinguishedName method might set additional error information in the CAErrorId
and CAErrorString properties.
If an existing key and its associated certificate are being used to configure the CA, this method must not be
called. If an existing key is being used to configure the CA, without using the associated certificate, the common
name in bstrCADN must match the sanitized ContainerName of the key.
If bstrCADN includes UTF8 encoding, set the appropriate flag in CAPolicy.inf and place it in the %windir%.

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header casetup.h

DLL Certocm.dll

See also
ICertSrvSetup
 ICertSrvSetup::SetCASetupProperty method
(casetup.h)
7/2/2022 • 2 minutes to read • Edit Online

The SetCASetupProper ty method sets a property value for a certification authority (CA) configuration.

Syntax
HRESULT SetCASetupProperty(
[in] CASetupProperty propertyId,
[in] VARIANT *pPropertyValue
);

Parameters
[in] propertyId

A CASetupProperty constant that specifies the type of property to configure.

The following properties are set as a side effect of other methods and cannot be set directly with this method.
ENUM_SETUPPROP_CANAME ENUM_SETUPPROP_CADSSUFFIX
ENUM_SETUPPROP_EXPIRATIONDATE ENUM_SETUPPROP_PARENTCANAME
ENUM_SETUPPROP_PARENTCAMACHINE ENUM_SETUPPROP_DATABASEDIRECTORY
ENUM_SETUPPROP_LOGDIRECTORY ENUM_SETUPPROP_SHAREDFOLDER
ENUM_SETUPPROP_WEBCAMACHINE ENUM_SETUPPROP_WEBCANAME
[in] pPropertyValue

A pointer to a VARIANT that specifies the property value. The VARIANT type depends on the property type. For
more information about the VARIANT type, see CASetupProperty.

Return value
None

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header casetup.h

DLL Certocm.dll
See also
ICertSrvSetup
 ICertSrvSetup::SetDatabaseInformation method
(casetup.h)
7/2/2022 • 2 minutes to read • Edit Online

The SetDatabaseInformation method sets the database related information for the certification authority (CA)
role.

Syntax
HRESULT SetDatabaseInformation(
[in] const BSTR bstrDBDirectory,
[in] const BSTR bstrLogDirectory,
[in] const BSTR bstrSharedFolder,
[in] VARIANT_BOOL bForceOverwrite
);

Parameters
[in] bstrDBDirectory

A string that contains the name of the directory where the CA database files will be stored. This parameter must
not be NULL or an empty string.
[in] bstrLogDirectory

A string that contains the name of the directory where the CA database log files will be stored. This parameter
must not be NULL or an empty string.
[in] bstrSharedFolder

This parameter is reserved for future use and must be NULL or an empty string.
[in] bForceOverwrite

A value that indicates whether to overwrite any existing database files in the specified directory. A value of
VARIANT_TRUE specifies to overwrite existing files.

Return value
None

Remarks
The SetDatabaseInformation method creates the specified directories if they do not exist.
Upon failure, the SetDatabaseInformation method might set additional error information in the CAErrorId
and CAErrorString properties.

Requirements
 Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header casetup.h

DLL Certocm.dll

See also
ICertSrvSetup
 ICertSrvSetup::SetParentCAInformation method
(casetup.h)
7/2/2022 • 2 minutes to read • Edit Online

The SetParentCAInformation method sets the parent certification authority (CA) information for a
subordinate CA configuration. This facilitates retrieval and installation of the subordinate certificate directly from
the parent CA. The parent CA must be a Microsoft CA.

Syntax
HRESULT SetParentCAInformation(
[in] const BSTR bstrCAConfiguration
);

Parameters
[in] bstrCAConfiguration

A string that contains a valid configuration for the parent CA. The string must be in the form ComputerName or
ComputerName\CAName, where ComputerName is the network name of the parent CA host computer, and
CAName is the common name of the parent CA.

Return value
None

Remarks
The SetParentCAInformation method pings the parent CA computer to verify that it is available on the
network.
Upon success, SetParentCAInformation sets the ENUM_SETUPPROP_PARENTCAMACHINE and
ENUM_SETUPPROP_PARENTCANAME properties for the subordinate CA configuration. For more information
about setup properties, see CASetupProperty.

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header casetup.h

DLL Certocm.dll
See also
ICertSrvSetup
 ICertSrvSetup::SetWebCAInformation method
(casetup.h)
7/2/2022 • 2 minutes to read • Edit Online

The SetWebCAInformation method sets the certification authority (CA) information for the Certification
Authority Web Enrollment role. You can use this method to enable certificate-related requests to a remote CA
through a web interface.

Syntax
HRESULT SetWebCAInformation(
[in] const BSTR bstrCAConfiguration
);

Parameters
[in] bstrCAConfiguration

A string that contains a valid configuration for the CA. The string must be in the form ComputerName or
ComputerName\CAName, where ComputerName is the network name of the CA host computer, and CAName
is the common name of the CA.

Return value
None

Remarks
The SetWebCAInformation method pings the CA computer to verify that it is available on the network.
Upon success, SetWebCAInformation sets the ENUM_SETUPPROP_WEBCAMACHINE and
ENUM_SETUPPROP_WEBCANAME properties for the Certification Authority Web Enrollment role configuration.
For more information about setup properties, see CASetupProperty.

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header casetup.h

DLL Certocm.dll
See also
ICertSrvSetup
 ICertSrvSetupKeyInformation interface (casetup.h)
7/2/2022 • 2 minutes to read • Edit Online

The ICer tSr vSetupKeyInformation interface defines a set of private key properties that are used for setup of
certification authority (CA) or Microsoft Simple Certificate Enrollment Protocol (SCEP) roles. The information
describes either an existing private key or one that setup generates.
Microsoft provides an implementation of this interface in the CCer tSr vSetupKeyInformation class.
In C++, you create an instance of this interface by calling the CoCreateInstance function with the
CLSID_CCer tSr vSetupKeyInformation class identifier.

Inheritance
The ICertSrvSetupKeyInformation interface inherits from the IDispatch interface.

Methods
The ICer tSr vSetupKeyInformation interface has these methods.

ICertSrvSetupKeyInformation::get_ContainerName

Gets or sets the name used by the cryptographic service provider (CSP) to generate, store, or access the key.

ICertSrvSetupKeyInformation::get_Existing

Gets or sets a value that indicates whether the private key already exists.

ICertSrvSetupKeyInformation::get_ExistingCACertificate

Gets or sets the binary value that has been encoded by using Distinguished Encoding Rules (DER) and that is the binary value
of the certification authority (CA) certificate that corresponds to an existing key.

ICertSrvSetupKeyInformation::get_HashAlgorithm

Gets or sets the name of the hashing algorithm used to sign or verify the certification authority (CA) certificate for the key.

ICertSrvSetupKeyInformation::get_Length

Gets or sets the strength of the key to one of the values supported by the cryptographic service provider (CSP).

ICertSrvSetupKeyInformation::get_ProviderName

Gets or sets the name of the cryptographic service provider (CSP) or key storage provider (KSP) that is used to generate or
store the private key.

ICertSrvSetupKeyInformation::put_ContainerName

Gets or sets the name used by the cryptographic service provider (CSP) to generate, store, or access the key.
 ICertSrvSetupKeyInformation::put_Existing

Gets or sets a value that indicates whether the private key already exists.

ICertSrvSetupKeyInformation::put_ExistingCACertificate

Gets or sets the binary value that has been encoded by using Distinguished Encoding Rules (DER) and that is the binary value
of the certification authority (CA) certificate that corresponds to an existing key.

ICertSrvSetupKeyInformation::put_HashAlgorithm

Gets or sets the name of the hashing algorithm used to sign or verify the certification authority (CA) certificate for the key.

ICertSrvSetupKeyInformation::put_Length

Gets or sets the strength of the key to one of the values supported by the cryptographic service provider (CSP).

ICertSrvSetupKeyInformation::put_ProviderName

Gets or sets the name of the cryptographic service provider (CSP) or key storage provider (KSP) that is used to generate or
store the private key.

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2008 Datacenter, Windows Server 2008
Enterprise [desktop apps only]

Target Platform Windows

Header casetup.h
 ICertSrvSetupKeyInformation::get_ContainerName
method (casetup.h)
7/2/2022 • 2 minutes to read • Edit Online

The ContainerName property gets or sets the name used by the cryptographic service provider (CSP) to
generate, store, or access the key.
This property is read/write.

Syntax
HRESULT get_ContainerName(
BSTR *pVal
);

Parameters
pVal

Return value
None

Remarks
If the private key already exists, this name must match the name used by the CSP to access the key.

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2008 Datacenter, Windows Server 2008
Enterprise [desktop apps only]

Target Platform Windows

Header casetup.h

DLL Certocm.dll

See also
ICertSrvSetupKeyInformation
 ICertSrvSetupKeyInformation::get_Existing method
(casetup.h)
7/2/2022 • 2 minutes to read • Edit Online

The Existing property gets or sets a value that indicates whether the private key already exists.
This property is read/write.

Syntax
HRESULT get_Existing(
VARIANT_BOOL *pVal
);

Parameters
pVal

Return value
None

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2008 Datacenter, Windows Server 2008
Enterprise [desktop apps only]

Target Platform Windows

Header casetup.h

DLL Certocm.dll

See also
ICertSrvSetupKeyInformation
 ICertSrvSetupKeyInformation::get_ExistingCACertificate
method (casetup.h)
7/2/2022 • 2 minutes to read • Edit Online

The ExistingCACer tificate property gets or sets the binary value that has been encoded by using
Distinguished Encoding Rules (DER) and that is the binary value of the certification authority (CA) certificate that
corresponds to an existing key.
This property is read/write.

Syntax
HRESULT get_ExistingCACertificate(
VARIANT *pVal
);

Parameters
pVal

Return value
None

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2008 Datacenter, Windows Server 2008
Enterprise [desktop apps only]

Target Platform Windows

Header casetup.h

DLL Certocm.dll

See also
ICertSrvSetupKeyInformation
 ICertSrvSetupKeyInformation::get_HashAlgorithm
method (casetup.h)
7/2/2022 • 2 minutes to read • Edit Online

The HashAlgorithm property gets or sets the name of the hashing algorithm used to sign or verify the
certification authority (CA) certificate for the key.
This property is read/write.

Syntax
HRESULT get_HashAlgorithm(
BSTR *pVal
);

Parameters
pVal

Return value
None

Remarks
The hashing algorithm must be supported by the ProviderName provider. For cryptographic service providers
(CSPs), get supported algorithms by calling the CryptGetProvParam function for the given provider. For key
storage providers (KSPs), get supported algorithms by calling the BCryptEnumAlgorithms function with the
dwAlgOperations parameter set to BCRYPT_HASH_OPERATION . For information about algorithm identifiers,
see CNG Algorithm Identifiers.
Examples
For an example of enumerating supported algorithms by using CryptGetProvParam, see Example C Program:
Enumerating CSP Providers and Provider Types.

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2008 Datacenter, Windows Server 2008
Enterprise [desktop apps only]

Target Platform Windows

Header casetup.h
 DLL Certocm.dll

See also
ICertSrvSetupKeyInformation
 ICertSrvSetupKeyInformation::get_Length method
(casetup.h)
7/2/2022 • 2 minutes to read • Edit Online

The Length property gets or sets the strength of the key to one of the values supported by the cryptographic
service provider (CSP).
This property is read/write.

Syntax
HRESULT get_Length(
LONG *pVal
);

Parameters
pVal

Return value
None

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2008 Datacenter, Windows Server 2008
Enterprise [desktop apps only]

Target Platform Windows

Header casetup.h

DLL Certocm.dll

See also
ICertSrvSetupKeyInformation
 ICertSrvSetupKeyInformation::get_ProviderName
method (casetup.h)
7/2/2022 • 2 minutes to read • Edit Online

The ProviderName property gets or sets the name of the cryptographic service provider (CSP) or key storage
provider (KSP) that is used to generate or store the private key.
This property is read/write.

Syntax
HRESULT get_ProviderName(
BSTR *pVal
);

Parameters
pVal

Return value
None

Remarks
For a KSP, the ProviderName property value must be formatted as PublicKeyAlgorithmName, number sign (#),
and KeyStorageProviderName, for example "RSA#Microsoft Software Key Storage Provider" or
"ECDSA_P256#Microsoft Software Key Storage Provider". The public key algorithm must be supported by the
provider. To get supported algorithms, call the NCryptEnumAlgorithms function with the dwAlgOperations
parameter set to NCRYPT_SIGNATURE_OPERATION . For information about algorithm identifiers, see CNG
Algorithm Identifiers.

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2008 Datacenter, Windows Server 2008
Enterprise [desktop apps only]

Target Platform Windows

Header casetup.h

DLL Certocm.dll
See also
ICertSrvSetupKeyInformation
 ICertSrvSetupKeyInformation::put_ContainerName
method (casetup.h)
7/2/2022 • 2 minutes to read • Edit Online

The ContainerName property gets or sets the name used by the cryptographic service provider (CSP) to
generate, store, or access the key.
This property is read/write.

Syntax
HRESULT put_ContainerName(
const BSTR bstrVal
);

Parameters
bstrVal

Return value
None

Remarks
If the private key already exists, this name must match the name used by the CSP to access the key.

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2008 Datacenter, Windows Server 2008
Enterprise [desktop apps only]

Target Platform Windows

Header casetup.h

DLL Certocm.dll

See also
ICertSrvSetupKeyInformation
 ICertSrvSetupKeyInformation::put_Existing method
(casetup.h)
7/2/2022 • 2 minutes to read • Edit Online

The Existing property gets or sets a value that indicates whether the private key already exists.
This property is read/write.

Syntax
HRESULT put_Existing(
VARIANT_BOOL bVal
);

Parameters
bVal

Return value
None

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2008 Datacenter, Windows Server 2008
Enterprise [desktop apps only]

Target Platform Windows

Header casetup.h

DLL Certocm.dll

See also
ICertSrvSetupKeyInformation
 ICertSrvSetupKeyInformation::put_ExistingCACertificate
method (casetup.h)
7/2/2022 • 2 minutes to read • Edit Online

The ExistingCACer tificate property gets or sets the binary value that has been encoded by using
Distinguished Encoding Rules (DER) and that is the binary value of the certification authority (CA) certificate that
corresponds to an existing key.
This property is read/write.

Syntax
HRESULT put_ExistingCACertificate(
VARIANT varVal
);

Parameters
varVal

Return value
None

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2008 Datacenter, Windows Server 2008
Enterprise [desktop apps only]

Target Platform Windows

Header casetup.h

DLL Certocm.dll

See also
ICertSrvSetupKeyInformation
 ICertSrvSetupKeyInformation::put_HashAlgorithm
method (casetup.h)
7/2/2022 • 2 minutes to read • Edit Online

The HashAlgorithm property gets or sets the name of the hashing algorithm used to sign or verify the
certification authority (CA) certificate for the key.
This property is read/write.

Syntax
HRESULT put_HashAlgorithm(
const BSTR bstrVal
);

Parameters
bstrVal

Return value
None

Remarks
The hashing algorithm must be supported by the ProviderName provider. For cryptographic service providers
(CSPs), get supported algorithms by calling the CryptGetProvParam function for the given provider. For key
storage providers (KSPs), get supported algorithms by calling the BCryptEnumAlgorithms function with the
dwAlgOperations parameter set to BCRYPT_HASH_OPERATION . For information about algorithm identifiers,
see CNG Algorithm Identifiers.
Examples
For an example of enumerating supported algorithms by using CryptGetProvParam, see Example C Program:
Enumerating CSP Providers and Provider Types.

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2008 Datacenter, Windows Server 2008
Enterprise [desktop apps only]

Target Platform Windows

Header casetup.h
 DLL Certocm.dll

See also
ICertSrvSetupKeyInformation
 ICertSrvSetupKeyInformation::put_Length method
(casetup.h)
7/2/2022 • 2 minutes to read • Edit Online

The Length property gets or sets the strength of the key to one of the values supported by the cryptographic
service provider (CSP).
This property is read/write.

Syntax
HRESULT put_Length(
LONG lVal
);

Parameters
lVal

Return value
None

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2008 Datacenter, Windows Server 2008
Enterprise [desktop apps only]

Target Platform Windows

Header casetup.h

DLL Certocm.dll

See also
ICertSrvSetupKeyInformation
 ICertSrvSetupKeyInformation::put_ProviderName
method (casetup.h)
7/2/2022 • 2 minutes to read • Edit Online

The ProviderName property gets or sets the name of the cryptographic service provider (CSP) or key storage
provider (KSP) that is used to generate or store the private key.
This property is read/write.

Syntax
HRESULT put_ProviderName(
const BSTR bstrVal
);

Parameters
bstrVal

Return value
None

Remarks
For a KSP, the ProviderName property value must be formatted as PublicKeyAlgorithmName, number sign (#),
and KeyStorageProviderName, for example "RSA#Microsoft Software Key Storage Provider" or
"ECDSA_P256#Microsoft Software Key Storage Provider". The public key algorithm must be supported by the
provider. To get supported algorithms, call the NCryptEnumAlgorithms function with the dwAlgOperations
parameter set to NCRYPT_SIGNATURE_OPERATION . For information about algorithm identifiers, see CNG
Algorithm Identifiers.

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2008 Datacenter, Windows Server 2008
Enterprise [desktop apps only]

Target Platform Windows

Header casetup.h

DLL Certocm.dll
See also
ICertSrvSetupKeyInformation
 ICertSrvSetupKeyInformationCollection interface
(casetup.h)
7/2/2022 • 2 minutes to read • Edit Online

The ICer tSr vSetupKeyInformationCollection interface defines functionality to populate and enumerate a
collection of ICertSrvSetupKeyInformation objects. Microsoft provides an implementation of this interface in the
CCer tSr vSetupKeyInformationCollection class. You cannot create an external instance of this interface. You
obtain this interface by calling the GetExistingCACertificates method.

Inheritance
The ICer tSr vSetupKeyInformationCollection interface inherits from the IUnknown interface.
ICer tSr vSetupKeyInformationCollection also has these types of members:

Methods
The ICer tSr vSetupKeyInformationCollection interface has these methods.

ICertSrvSetupKeyInformationCollection::Add

Adds an ICertSrvSetupKeyInformation object to the collection.

ICertSrvSetupKeyInformationCollection::get__NewEnum

Gets an enumerator for the information set.

ICertSrvSetupKeyInformationCollection::get_Count

Gets the number of ICertSrvSetupKeyInformation objects in the collection.

ICertSrvSetupKeyInformationCollection::get_Item

Gets an ICertSrvSetupKeyInformation object that is identified by index in the collection.

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2008 Datacenter, Windows Server 2008
Enterprise [desktop apps only]

Target Platform Windows

Header casetup.h
 ICertSrvSetupKeyInformationCollection::Add
method (casetup.h)
7/2/2022 • 2 minutes to read • Edit Online

The Add method adds an ICertSrvSetupKeyInformation object to the collection.

Syntax
HRESULT Add(
[in] ICertSrvSetupKeyInformation *pIKeyInformation
);

Parameters
[in] pIKeyInformation

A pointer to an ICertSrvSetupKeyInformation object.

Return value
None

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2008 Datacenter, Windows Server 2008
Enterprise [desktop apps only]

Target Platform Windows

Header casetup.h

DLL Certocm.dll

See also
ICertSrvSetupKeyInformationCollection
 ICertSrvSetupKeyInformationCollection::get__NewEnum
method (casetup.h)
7/2/2022 • 2 minutes to read • Edit Online

The _NewEnum property gets an enumerator for the information set.

This property is read-only.

Syntax
HRESULT get__NewEnum(
IUnknown **ppVal
);

Parameters
ppVal

Return value
None

Remarks
This property is provided for internal use by the For Each statement in Visual Basic Scripting Edition (VBScript)
and C#. To enumerate the collection of properties with C++, use the Count and Item properties defined by the
ICertSrvSetupKeyInformationCollection interface.

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2008 Datacenter, Windows Server 2008
Enterprise [desktop apps only]

Target Platform Windows

Header casetup.h

DLL Certocm.dll

See also
ICertSrvSetupKeyInformationCollection
 ICertSrvSetupKeyInformationCollection::get_Count
method (casetup.h)
7/2/2022 • 2 minutes to read • Edit Online

The Count property gets the number of ICertSrvSetupKeyInformation objects in the collection.
This property is read-only.

Syntax
HRESULT get_Count(
LONG *pVal
);

Parameters
pVal

Return value
None

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2008 Datacenter, Windows Server 2008
Enterprise [desktop apps only]

Target Platform Windows

Header casetup.h

DLL Certocm.dll

See also
ICertSrvSetupKeyInformationCollection
 ICertSrvSetupKeyInformationCollection::get_Item
method (casetup.h)
7/2/2022 • 2 minutes to read • Edit Online

The Item property gets an ICertSrvSetupKeyInformation object that is identified by index in the collection.
This property is read-only.

Syntax
HRESULT get_Item(
LONG Index,
VARIANT *pVal
);

Parameters
Index

pVal

Return value
None

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2008 Datacenter, Windows Server 2008
Enterprise [desktop apps only]

Target Platform Windows

Header casetup.h

DLL Certocm.dll

See also
ICertSrvSetupKeyInformationCollection
 IMSCEPSetup interface (casetup.h)
7/2/2022 • 2 minutes to read • Edit Online

The IMSCEPSetup interface defines functionality to install and uninstall a Network Device Enrollment Service
(NDES) role on a Certificate Services computer. Implement this interface to provide a custom setup program for
installing and uninstalling this role.
Microsoft provides an implementation of this interface in the CMSCEPSetup class. For installation, you must
call InitializeDefaults before accessing any properties or calling any other methods on the CMSCEPSetup
object.
In C++, you create an instance of this interface by calling the CoCreateInstance function with the
CLSID_CMSCEPSetup class identifier.

Inheritance
The IMSCEPSetup interface inherits from the IUnknown interface. IMSCEPSetup also has these types of
members:

Methods
The IMSCEPSetup interface has these methods.

IMSCEPSetup::get_MSCEPErrorId

Gets the ID for additional error information related to a failed Network Device Enrollment Service (NDES) specification. Any
method call on the parent object resets this property.

IMSCEPSetup::get_MSCEPErrorString

Contains the string data for additional error information related to a failed Network Device Enrollment Service (NDES)
specification. Any method call on the parent object resets this property.

IMSCEPSetup::GetKeyLengthList

Gets the list of key lengths supported by the specified cryptographic service provider (CSP).

IMSCEPSetup::GetMSCEPSetupProperty

Gets a property value for a Network Device Enrollment Service (NDES) configuration.

IMSCEPSetup::GetProviderNameList

Gets the list of cryptographic service providers (CSPs) that provide asymmetric key signature and exchange algorithms on the
computer.

IMSCEPSetup::InitializeDefaults

Initializes a CMSCEPSetup object with default values to enable installation of a Network Device Enrollment Service (NDES) role.
 IMSCEPSetup::Install

Installs a Network Device Enrollment Service (NDES) role as configured in a CMSCEPSetup object.

IMSCEPSetup::IsMSCEPStoreEmpty

Always returns VARIANT_TRUE. It should not be used.

IMSCEPSetup::PostUnInstall

Is not implemented. It is reserved for future use.

IMSCEPSetup::PreUnInstall

Removes registry and IIS settings for the Network Device Enrollment Service (NDES) role.

IMSCEPSetup::SetAccountInformation

Sets the user account information used by the IIS Network Device Enrollment Service (NDES) extension to perform enrollment
on behalf of network devices.

IMSCEPSetup::SetMSCEPSetupProperty

Sets a property value for a Network Device Enrollment Service (NDES) configuration.

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2008 Datacenter, Windows Server 2008
Enterprise [desktop apps only]

Target Platform Windows

Header casetup.h
 IMSCEPSetup::get_MSCEPErrorId method
(casetup.h)
7/2/2022 • 2 minutes to read • Edit Online

The MSCEPErrorId property gets the ID for additional error information related to a failed Network Device
Enrollment Service (NDES) specification. Any method call on the parent object resets this property.
This property is read-only.

Syntax
HRESULT get_MSCEPErrorId(
LONG *pVal
);

Parameters
pVal

Return value
None

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2008 Datacenter, Windows Server 2008
Enterprise [desktop apps only]

Target Platform Windows

Header casetup.h

DLL Certocm.dll

See also
IMSCEPSetup
 IMSCEPSetup::get_MSCEPErrorString method
(casetup.h)
7/2/2022 • 2 minutes to read • Edit Online

The MSCEPErrorString property contains the string data for additional error information related to a failed
Network Device Enrollment Service (NDES) specification. Any method call on the parent object resets this
property.
This property is read-only.

Syntax
HRESULT get_MSCEPErrorString(
BSTR *pVal
);

Parameters
pVal

Return value
None

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2008 Datacenter, Windows Server 2008
Enterprise [desktop apps only]

Target Platform Windows

Header casetup.h

DLL Certocm.dll

See also
IMSCEPSetup
 IMSCEPSetup::GetKeyLengthList method (casetup.h)
7/2/2022 • 2 minutes to read • Edit Online

The GetKeyLengthList method gets the list of key lengths supported by the specified cryptographic service
provider (CSP).

Syntax
HRESULT GetKeyLengthList(
[in] VARIANT_BOOL bExchange,
[in] const BSTR bstrProviderName,
[out] VARIANT *pVal
);

Parameters
[in] bExchange

A value that indicates whether the listed lengths are for an exchange key algorithm. A VARIANT_TRUE value
indicates exchange key lengths; otherwise, the lengths are for signing keys.
[in] bstrProviderName

A string that contains the name of the CSP.

[out] pVal

A pointer to a VARIANT array of VT_UI4 types that correspond to the key lengths supported by the CSP.

Return value
None

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2008 Datacenter, Windows Server 2008
Enterprise [desktop apps only]

Target Platform Windows

Header casetup.h

DLL Certocm.dll

See also
IMSCEPSetup
 IMSCEPSetup::GetMSCEPSetupProperty method
(casetup.h)
7/2/2022 • 2 minutes to read • Edit Online

The GetMSCEPSetupProper ty method gets a property value for a Network Device Enrollment Service (NDES)
configuration.

Syntax
HRESULT GetMSCEPSetupProperty(
[in] MSCEPSetupProperty propertyId,
[out] VARIANT *pVal
);

Parameters
[in] propertyId

A value of the MSCEPSetupProperty enumeration that specifies the type of property to get.
[out] pVal

A VARIANT that specifies the property value. The VARIANT type depends on the property type. For more
information about the VARIANT type, see MSCEPSetupProperty.

Return value
None

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2008 Datacenter, Windows Server 2008
Enterprise [desktop apps only]

Target Platform Windows

Header casetup.h

DLL Certocm.dll

See also
IMSCEPSetup
 IMSCEPSetup::GetProviderNameList method
(casetup.h)
7/2/2022 • 2 minutes to read • Edit Online

The GetProviderNameList method gets the list of cryptographic service providers (CSPs) that provide
asymmetric key signature and exchange algorithms on the computer.

Syntax
HRESULT GetProviderNameList(
[in] VARIANT_BOOL bExchange,
[out] VARIANT *pVal
);

Parameters
[in] bExchange

A value that indicates whether the provider names are for exchange key algorithms. A VARIANT_TRUE value
indicates exchange key providers; otherwise, the providers are for signing keys.
[out] pVal

A pointer to a VARIANT array of VT_BSTR types, where each string represents the name of a CSP.

Return value
None

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2008 Datacenter, Windows Server 2008
Enterprise [desktop apps only]

Target Platform Windows

Header casetup.h

DLL Certocm.dll

See also
IMSCEPSetup
 IMSCEPSetup::InitializeDefaults method (casetup.h)
7/2/2022 • 2 minutes to read • Edit Online

The InitializeDefaults method initializes a CMSCEPSetup object with default values to enable installation of a
Network Device Enrollment Service (NDES) role. To install an NDES role, this method must be called before
using the CMSCEPSetup object. For information about default values, see MSCEPSetupProperty.

Syntax
HRESULT InitializeDefaults();

Return value
None

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2008 Datacenter, Windows Server 2008
Enterprise [desktop apps only]

Target Platform Windows

Header casetup.h

DLL Certocm.dll

See also
IMSCEPSetup
 IMSCEPSetup::Install method (casetup.h)
7/2/2022 • 2 minutes to read • Edit Online

The Install method installs a Network Device Enrollment Service (NDES) role as configured in a CMSCEPSetup
object.

Syntax
HRESULT Install();

Return value
None

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2008 Datacenter, Windows Server 2008
Enterprise [desktop apps only]

Target Platform Windows

Header casetup.h

DLL Certocm.dll

See also
IMSCEPSetup
 IMSCEPSetup::IsMSCEPStoreEmpty method
(casetup.h)
7/2/2022 • 2 minutes to read • Edit Online

The IsMSCEPStoreEmpty method always returns VARIANT_TRUE . It should not be used.

Syntax
HRESULT IsMSCEPStoreEmpty(
[out] VARIANT_BOOL *pbEmpty
);

Parameters
[out] pbEmpty

This parameter always contains VARIANT_TRUE .

Return value
None

Remarks
For the Network Device Enrollment Service (NDES) role, the My personal store is used. The default
implementation does not use a separate store for signing and exchange certificates.

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2008 Datacenter, Windows Server 2008
Enterprise [desktop apps only]

Target Platform Windows

Header casetup.h

DLL Certocm.dll

See also
IMSCEPSetup
 IMSCEPSetup::PostUnInstall method (casetup.h)
7/2/2022 • 2 minutes to read • Edit Online

The PostUnInstall method is not implemented. It is reserved for future use.

Syntax
HRESULT PostUnInstall();

Return value
This method does not return a value.

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2008 Datacenter, Windows Server 2008
Enterprise [desktop apps only]

Target Platform Windows

Header casetup.h

DLL Certocm.dll

See also
IMSCEPSetup
 IMSCEPSetup::PreUnInstall method (casetup.h)
7/2/2022 • 2 minutes to read • Edit Online

The PreUnInstall method removes registry and IIS settings for the Network Device Enrollment Service (NDES)
role.

Syntax
HRESULT PreUnInstall();

Return value
None

Remarks
You can use this method to support an uninstall of an NDES role. The role must be already installed on the
computer. This method should be called before calling the role-specific component-based servicing (CBS)
uninstall process.

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2008 Datacenter, Windows Server 2008
Enterprise [desktop apps only]

Target Platform Windows

Header casetup.h

DLL Certocm.dll

See also
IMSCEPSetup
 IMSCEPSetup::SetAccountInformation method
(casetup.h)
7/2/2022 • 2 minutes to read • Edit Online

The SetAccountInformation method sets the user account information used by the IIS Network Device
Enrollment Service (NDES) extension to perform enrollment on behalf of network devices.

Syntax
HRESULT SetAccountInformation(
[in] const BSTR bstrUserName,
[in] const BSTR bstrPassword
);

Parameters
[in] bstrUserName

A string that contains the name of the user account to use with the IIS extension in the form [DomainName]
UserName.
[in] bstrPassword

A string that contains the password for the user account.

Return value
None

Remarks
The account must be a member of the IIS_USRS group on the computer.
If NDES is configured for an enterprise certification authority (CA), the account must have read permission on
the IPSecIntermediateOffline template.

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2008 Datacenter, Windows Server 2008
Enterprise [desktop apps only]

Target Platform Windows

Header casetup.h
 DLL Certocm.dll

See also
IMSCEPSetup
 IMSCEPSetup::SetMSCEPSetupProperty method
(casetup.h)
7/2/2022 • 2 minutes to read • Edit Online

The SetMSCEPSetupProper ty method sets a property value for a Network Device Enrollment Service (NDES)
configuration.

Syntax
HRESULT SetMSCEPSetupProperty(
[in] MSCEPSetupProperty propertyId,
[in] VARIANT *pPropertyValue
);

Parameters
[in] propertyId

A value of the MSCEPSetupProperty enumeration that specifies the type of property to configure.
[in] pPropertyValue

A pointer to a VARIANT that specifies the property value. The VARIANT type depends on the property type. For
more information about the VARIANT type, see MSCEPSetupProperty.

Return value
None

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2008 Datacenter, Windows Server 2008
Enterprise [desktop apps only]

Target Platform Windows

Header casetup.h

DLL Certocm.dll

See also
IMSCEPSetup
 MSCEPSetupProperty enumeration (casetup.h)
7/2/2022 • 2 minutes to read • Edit Online

The MSCEPSetupProper ty enumeration specifies a property type for setup and configuration of a Microsoft
Simple Certificate Enrollment Protocol (SCEP) role using IMSCEPSetup.

Syntax
typedef enum __MIDL___MIDL_itf_casetup_0000_0003_0001 {
ENUM_CEPSETUPPROP_USELOCALSYSTEM = 0,
ENUM_CEPSETUPPROP_USECHALLENGE = 1,
ENUM_CEPSETUPPROP_RANAME_CN = 2,
ENUM_CEPSETUPPROP_RANAME_EMAIL = 3,
ENUM_CEPSETUPPROP_RANAME_COMPANY = 4,
ENUM_CEPSETUPPROP_RANAME_DEPT = 5,
ENUM_CEPSETUPPROP_RANAME_CITY = 6,
ENUM_CEPSETUPPROP_RANAME_STATE = 7,
ENUM_CEPSETUPPROP_RANAME_COUNTRY = 8,
ENUM_CEPSETUPPROP_SIGNINGKEYINFORMATION = 9,
ENUM_CEPSETUPPROP_EXCHANGEKEYINFORMATION = 10,
ENUM_CEPSETUPPROP_CAINFORMATION = 11,
ENUM_CEPSETUPPROP_MSCEPURL = 12,
ENUM_CEPSETUPPROP_CHALLENGEURL = 13
} MSCEPSetupProperty;

Constants

ENUM_CEPSETUPPROP_USELOCALSYSTEM
Value: 0
A VT_BOOL value that specifies whether the Microsoft SCEP ISAPI Extension runs as the local system user or under a
separate user account. For remote CA or standalone CA configurations, by default this is set to VARIANT_FALSE . For a local
enterprise CA configuration, by default this is set to VARIANT_TRUE .

ENUM_CEPSETUPPROP_USECHALLENGE
Value: 1
A VT_BOOL value that specifies whether to require an SCEP challenge phrase to enroll. By default, setup sets this to TRUE .

ENUM_CEPSETUPPROP_RANAME_CN
Value: 2
A VT_BSTR value that specifies the common name for Microsoft SCEP registration authority (RA) certificate name information.
By default, the common name format is MachineName"-RA", where MachineName is the local machine name.

ENUM_CEPSETUPPROP_RANAME_EMAIL
Value: 3
A VT_BSTR value that specifies an optional email address to be added in Microsoft SCEP RA certificate name information.

ENUM_CEPSETUPPROP_RANAME_COMPANY
Value: 4
A VT_BSTR value that specifies an optional company name to be added in Microsoft SCEP RA certificate name information.
 ENUM_CEPSETUPPROP_RANAME_DEPT
Value: 5
A VT_BSTR value that specifies an optional department name to be added in Microsoft SCEP RA certificate name information.

ENUM_CEPSETUPPROP_RANAME_CITY
Value: 6
A VT_BSTR value that specifies an optional city name to be added in Microsoft SCEP RA certificate name information.

ENUM_CEPSETUPPROP_RANAME_STATE
Value: 7
A VT_BSTR value that specifies an optional state name to be added in Microsoft SCEP RA certificate name information.

ENUM_CEPSETUPPROP_RANAME_COUNTRY
Value: 8
A VT_BSTR value that specifies the country or region name to be added in Microsoft SCEP RA certificate name information.
By default, setup uses the country or region setting for the local computer.

ENUM_CEPSETUPPROP_SIGNINGKEYINFORMATION
Value: 9
A VT_IDISPATCH value that is made up of an ICertSrvSetupKeyInformation object used to create a Microsoft SCEP signing
certificate. Setup creates a signing certificate based on an "EnrollmentAgentOffline" template.

ENUM_CEPSETUPPROP_EXCHANGEKEYINFORMATION
Value: 10
A VT_IDISPATCH value that is made up of an ICertSrvSetupKeyInformation object used to create a Microsoft SCEP key
exchange certificate. Setup creates a key exchange certificate based on a "CEPEncryption" template.

ENUM_CEPSETUPPROP_CAINFORMATION
Value: 11
A VT_BSTR value that specifies the Certification Authority (CA) information. By default, setup uses the local CA. If a local CA is
present, you should not set this property.

ENUM_CEPSETUPPROP_MSCEPURL
Value: 12
A VT_BSTR value that specifies the URL for use by routers to connect and send certificate requests using SCEP. By default,
setup uses http://MachineName/certsrv/mscep/mscep.dll, where MachineName is the local machine name. This is a read-only
property.

ENUM_CEPSETUPPROP_CHALLENGEURL
Value: 13
A VT_BSTR value that specifies the URL for use by router administrators to connect and obtain a challenge phrase. By default,
setup uses http://MachineName/certsrv/mscep/, where MachineName is the local machine name. This is a read-only property.

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2008 Datacenter, Windows Server 2008
Enterprise [desktop apps only]

Header casetup.h
 ccgplugins.h header
7/2/2022 • 2 minutes to read • Edit Online

This header is used by Security and Identity. For more information, see:
Security and Identity
ccgplugins.h contains the following programming interfaces:

Interfaces

ICcgDomainAuthCredentials

A client-implemented interface that allows developers to supply their own credentials dynamically at run time to authenticate
non-domain joined containers with Active Directory.
 ICcgDomainAuthCredentials interface (ccgplugins.h)
7/2/2022 • 2 minutes to read • Edit Online

A client-implemented interface that allows developers to supply their own credentials dynamically at run time to
authenticate non-domain joined containers with Active Directory.

Inheritance
The ICcgDomainAuthCredentials interface inherits from the IUnknown interface.

Methods
The ICcgDomainAuthCredentials interface has these methods.

ICcgDomainAuthCredentials::GetPasswordCredentials

Returns credentials to authenticate a non-domain joined container with Active Directory.

Requirements

Minimum suppor ted client Windows 10, version 1809 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2019 [desktop apps only]

Header ccgplugins.h
 ICcgDomainAuthCredentials::GetPasswordCredentials
method (ccgplugins.h)
7/2/2022 • 2 minutes to read • Edit Online

Returns credentials to authenticate a non-domain joined container with Active Directory.

Syntax
HRESULT GetPasswordCredentials(
LPCWSTR pluginInput,
LPWSTR *domainName,
LPWSTR *username,
LPWSTR *password
);

Parameters
pluginInput

An input string passed in by the container runtime. The client implementation uses the provided input string to
retrieve authentication credentials, typically from a secure storage provider, that are returned in the output
parameters. The input string is provided to the Host Compute Services (HCS) in a credential specification file.
For more information, see the Remarks section.
domainName

The domain name for the credentials

username

The user name for the credentials.

password

The password for the credentials.

Return value
The return value is an HRESULT. A value of S_OK indicates the call was successful.

Remarks
The API may be called concurrently. Therefore, the developer needs to ensure that their implementation is
thread safe. Additionally, the COM object will be activated out-of-proc and it must be registered appropriately.
The implementer must add a key under
“HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\CCG\COMClasses” for their COM CLSID. Write access to
“CCG\COMClasses” is restricted to SYSTEM and Administrator accounts.
The following is an example credential specification file. For information on supplying this file to Docker, see Run
a container with a gMSA.
 {
"CmsPlugins": [
"ActiveDirectory"
],
"DomainJoinConfig": {
"Sid": "S-1-5-21-3700119848-2853083131-2094573802",
"MachineAccountName": "gmsa1",
"Guid": "630a7dd3-2d3e-4471-ae91-1d9ea2556cd5",
"DnsTreeName": "contoso.com",
"DnsName": "contoso.com",
"NetBiosName": "CONTOSO"
},
"ActiveDirectoryConfig": {
"GroupManagedServiceAccounts": [
{
"Name": "gmsa1",
"Scope": "contoso.com"
},
{
"Name": "gmsa1",
"Scope": "CONTOSO"
}
],
"HostAccountConfig": {
"PortableCcgVersion": "1",
"PluginGUID": "{CFCA0441-511D-4B2A-862E-20348A78760B}",
"PluginInput": "contoso.com:gmsaccg:<password>"
}
}
}

Examples
The following example shows a simple implementation of ICcgDomainAuthCredentials . Note that, for
illustrative purposes, this sample obtains the credentials by simply parsing the input string. A real-world
implementation would store the credentials in a secure data store and use the input string to locate the
credential information. Also, the standard COM method implementations have been omitted from this sample
for brevity.
 // UUID generated by the developer
[uuid("cfca0441-511d-4b2a-862e-20348a78760b")]
class CCGStubPlugin : public RuntimeClass<RuntimeClassFlags<RuntimeClassType::ClassicCom>,
ICcgDomainAuthCredentials >
{
public:
CCGStubPlugin() {}

~CCGStubPlugin() {}

IFACEMETHODIMP GetPasswordCredentials(
_In_ LPCWSTR pluginInput,
_Outptr_ LPWSTR *domainName,
_Outptr_ LPWSTR *username,
_Outptr_ LPWSTR *password)
{
std::wstring domainParsed, userParsed, passwordParsed;
try
{
if(domainName == NULL || username == NULL || password == NULL)
{
return STG_E_INVALIDPARAMETER;
}
*domainName = NULL;
*username = NULL;
*password = NULL;
wstring pluginInputString(pluginInput);
if (count(pluginInputString.begin(), pluginInputString.end(), ':') < 2)
{
return CO_E_NOT_SUPPORTED;
}
// Extract creds of this format Domain:Username:Password
size_t sep1 = pluginInputString.find(L":");
size_t sep2 = pluginInputString.find(L":", sep1 + 1);
domainParsed = pluginInputString.substr(0, sep1);
userParsed = pluginInputString.substr(sep1 + 1, sep2 - sep1 - 1);
passwordParsed = pluginInputString.substr(sep2 + 1);
}
catch (...)
{
return EVENT_E_INTERNALERROR;
}

auto userCo = wil::make_cotaskmem_string_nothrow(userParsed.c_str());

auto passwordCo = wil::make_cotaskmem_string_nothrow(passwordParsed.c_str());
auto domainCo = wil::make_cotaskmem_string_nothrow(domainParsed.c_str());
if (userCo == nullptr || passwordCo == nullptr || domainCo == nullptr)
{
return STG_E_INSUFFICIENTMEMORY;
}

*domainName = domainCo.release();
*username = userCo.release();
*password = passwordCo.release();
return S_OK;
}
};
CoCreatableClass(CCGStubPlugin);

Requirements

Minimum suppor ted client Windows 10 Build 20348

 Minimum suppor ted ser ver Windows 10 Build 20348

Header ccgplugins.h

See also
ICcgDomainAuthCredentials
 celib.h header
7/2/2022 • 2 minutes to read • Edit Online

This header is used by Security and Identity. For more information, see:
Security and Identity
celib.h contains the following programming interfaces:

Enumerations

ENUM_PERIOD

Specifies the units of a time span.

 ENUM_PERIOD enumeration (celib.h)
7/2/2022 • 2 minutes to read • Edit Online

The ENUM_PERIOD enumeration specifies the units of a time span.

Syntax
typedef enum ENUM_PERIOD {
ENUM_PERIOD_INVALID = -1,
ENUM_PERIOD_SECONDS = 0,
ENUM_PERIOD_MINUTES,
ENUM_PERIOD_HOURS,
ENUM_PERIOD_DAYS,
ENUM_PERIOD_WEEKS,
ENUM_PERIOD_MONTHS,
ENUM_PERIOD_YEARS
} ;

Constants

ENUM_PERIOD_INVALID
Value: -1

ENUM_PERIOD_SECONDS
Value: 0

ENUM_PERIOD_MINUTES

ENUM_PERIOD_HOURS

ENUM_PERIOD_DAYS

ENUM_PERIOD_WEEKS

ENUM_PERIOD_MONTHS

ENUM_PERIOD_YEARS

Requirements

Header celib.h (include Certca.h)

 certadm.h header
7/2/2022 • 2 minutes to read • Edit Online

This header is used by Security and Identity. For more information, see:
Security and Identity
certadm.h contains the following programming interfaces:

Interfaces

ICertAdmin

Provides administration functionality for properly authorized clients.

ICertAdmin2

Provide administration functionality for properly authorized clients.

IOCSPAdmin

Provides functionality to manage an Online Certificate Status Protocol (OCSP) responder server.

IOCSPCAConfiguration

Represents a set of definitions that enable an Online Certificate Status Protocol (OCSP) service to respond to a certificate
status request for a specific certification authority (CA).

IOCSPCAConfigurationCollection

Represents a set of certificates for which an Online Certificate Status Protocol (OCSP) service has been configured to provide
certificate status responses.

IOCSPProperty

Represents a name-value pair for OCSPServiceProperties or ProviderProperties.

IOCSPPropertyCollection

Represents a set of configurable attribute properties (name-value pairs) for an Online Certificate Status Protocol (OCSP)
service.
 ICertAdmin interface (certadm.h)
7/2/2022 • 2 minutes to read • Edit Online

The ICer tAdmin interface provides administration functionality for properly authorized clients.
The ICer tAdmin interface is used to perform the following tasks:
Authorize or deny a certificate request.
Revoke an issued certificate.
Trigger the generation of a certificate revocation list (CRL).
Get the current CRL for the server.
Determine whether a certificate is valid.
When you use the ICer tAdmin interface, you have write-only access to request attributes and certificate
extensions, but no direct access to other request and certificate properties.
ICer tAdmin is defined in Certadm.h. When you create a program, however, use Certsrv.h as the include file.
Certadm.dll, on the other hand, provides the implementation of the ICer tAdmin interface. The type information
for this interface is also in Certadml.dll, which is shipped with the Platform Software Development Kit (SDK).
Administration tasks use DCOM. Code that calls this interface method as defined in an earlier version of
Certadm.h will run on Windows-based servers as long as the client and the server are both running the same
Windows operating system.
Certificate Services interfaces support both apartment-threading and free-threading models. For better
throughput, free threading is recommended.

Inheritance
The ICer tAdmin interface inherits from the IDispatch interface. ICer tAdmin also has these types of members:

Methods
The ICer tAdmin interface has these methods.

ICertAdmin::DenyRequest

Denies a specified certificate request that is pending.

ICertAdmin::GetCRL

Retrieves the current certificate revocation list (CRL) for the Certificate Services certification authority (CA).

ICertAdmin::GetRevocationReason

Returns the reason a certificate was revoked. This method was first defined in the ICertAdmin interface.

ICertAdmin::ImportCertificate

Takes a previously issued certificate and imports it to the certification authority's (CA) database. This method was first defined
in the ICertAdmin interface.
 ICertAdmin::IsValidCertificate

Verifies the certificate against the certification authority (CA) key and checks that the certificate has not been revoked. This
method was first defined in the ICertAdmin interface.

ICertAdmin::PublishCRL

Sends a request to the Certificate Services certification authority (CA) to publish a new certificate revocation list (CRL). This
method was first introduced in the ICertAdmin interface.

ICertAdmin::ResubmitRequest

Submits the specified certificate request to the policy module for the specified certification authority. This method was first
introduced in the ICertAdmin interface.

ICertAdmin::RevokeCertificate

Revokes a certificate either on a specified date or immediately. This method was first defined in the ICertAdmin interface.

ICertAdmin::SetCertificateExtension

Adds a new extension to the certificate issued in response to a certificate request. This method was first defined by the
ICertAdmin interface.

ICertAdmin::SetRequestAttributes

Sets attributes in the specified pending certificate request. This method was first defined in the ICertAdmin interface.

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header certadm.h (include Certsrv.h)

 ICertAdmin::DenyRequest method (certadm.h)
7/2/2022 • 2 minutes to read • Edit Online

The DenyRequest method denies a specified certificate request that is pending. This method was first defined
in the ICertAdmin interface.
For this method to succeed, the certificate request must be pending.

Syntax
HRESULT DenyRequest(
[in] const BSTR strConfig,
[in] LONG RequestId
);

Parameters
[in] strConfig

Represents a valid configuration string for the certification authority (CA) in the form
COMPUTERNAME\CANAME where COMPUTERNAME is the network name of the Certificate Services server
and CANAME is the common name of the certification authority as entered during Certificate Services setup.
For information about the configuration string, see ICertConfig.

Impor tant DenyRequest does not clear the internal cache when the configuration string is changed. When you change the
configuration string for the CA, you must instantiate a new ICertAdmin object and call this method again with the new
configuration string.

[in] RequestId

Specifies the ID of the pending request to be denied.

Return value
None

Remarks
Administration tasks use DCOM. Code that calls this interface method as defined in an earlier version of
Certadm.h will run on Windows-based servers as long as the client and the server are both running the same
Windows operating system.
Examples
The following example declares the necessary variables, initializes COM, and creates an instance of the
CertAdmin class. It then calls DenyRequest and prints success or failure to the screen. Finally, it frees resources.
// Pointer to an interface object.
ICertAdmin * pCertAdmin = NULL;

BSTR bstrCA = NULL; // variable for machine\CAName

long nReqID; // variable for Request ID
HRESULT hr;

// Initialize COM.
hr = CoInitializeEx(NULL, COINIT_APARTMENTTHREADED);
if (FAILED(hr))
{
printf("Failed CoInitializeEx [%x]\n", hr);
goto error;
}

// Create the CertAdmin object

// and get a pointer to its ICertAdmin interface.
hr = CoCreateInstance( CLSID_CCertAdmin,
NULL,
CLSCTX_INPROC_SERVER,
IID_ICertAdmin,
(void **)&pCertAdmin);
if (FAILED(hr))
{
printf("Failed CoCreateInstance pCertAdmin [%x]\n", hr);
goto error;
}

// Note the use of two '\' in C++ to produce one '\'.

bstrCA = SysAllocString(L"<COMPUTERNAMEHERE>\\<CANAMEHERE>");
if (NULL == bstrCA)
{
printf("Failed to allocate memory for bstrCA\n");
goto error;
}

// nReqID is RequestID to be denied.

nReqID = <REQUESTIDHERE>;

// Deny the request.

hr = pCertAdmin->DenyRequest( bstrCA, nReqID );
if (FAILED(hr))
{
printf("Failed DenyRequest %ws %d [%x]\n",
bstrCA, nReqID, hr);
goto error;
}
else
printf("Denied request %ws %d\n",
bstrCA, nReqID );

// Done processing.

error:

// Free BSTR values.

if (NULL != bstrCA)
SysFreeString(bstrCA);

// Clean up object resources.

if (NULL != pCertAdmin)
pCertAdmin->Release();

// Free COM resources.

CoUninitialize();
Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header certadm.h (include Certsrv.h)

Librar y Certidl.lib

DLL Certadm.dll

See also
CCertAdmin
ICertAdmin
ICer tAdmin2
ICertConfig
 ICertAdmin::GetCRL method (certadm.h)
7/2/2022 • 2 minutes to read • Edit Online

The GetCRL method retrieves the current certificate revocation list (CRL) for the Certificate Services
certification authority (CA). This method was first defined in the ICertAdmin interface.

Syntax
HRESULT GetCRL(
[in] const BSTR strConfig,
[in] LONG Flags,
[out] BSTR *pstrCRL
);

Parameters
[in] strConfig

Represents a valid configuration string for the CA whose CRL you want to retrieve. This string is in the form
COMPUTERNAME\CANAME, where COMPUTERNAME is the network name of the Certificate Services server
and CANAME is the common name of the CA, as entered during Certificate Services setup. For information
about the configuration string name, see ICertConfig.

Impor tant GetCRL does not clear the internal cache when the configuration string is changed. When you change the
configuration string for the CA, you must instantiate a new ICertAdmin object and call this method again with the new
configuration string.

[in] Flags

Specifies the format of the returned CRL. This parameter can be one of the following flags.

VA L UE M EA N IN G

BASE64 format with begin/end.

CR_OUT_BASE64HEADER

BASE64 format without begin/end.

CR_OUT_BASE64

Binary format.
CR_OUT_BINARY

[out] pstrCRL

A pointer to a BSTR that receives the CRL.

When using this method, create a variable of BSTR type, set the variable to NULL , and pass the address of this
variable in the pbstrCRL parameter. When you have finished using the BSTR variable, free it by calling the
SysFreeString function.
Return value
If the function succeeds, the function returns S_OK.
If the function fails, it returns an HRESULT value that indicates the error. Possible values include, but are not
limited to, those in the following table. For a list of common error codes, see Common HRESULT Values.

RET URN C O DE DESC RIP T IO N

The strConfig parameter cannot be NULL or no CRL has

E_POINTER been found.

Remarks
Administration tasks use DCOM. Code that calls this interface method as defined in an earlier version of
Certadm.h will run on Windows-based servers as long as the client and the server are both running the same
Windows operating system.
Examples
The following example declares the necessary variables, initializes COM, and creates an instance of the
Cer tAdmin class. It then calls GetCRL and prints success or failure to the screen. Finally, it frees resources.
 ICertAdmin * pCertAdmin = NULL; // pointer to interface object
BSTR bstrCA = NULL; // variable for machine\CAName
BSTR bstrCRL = NULL; // variable to contain
// the retrieved CRL

HRESULT hr;

// Initialize COM.
hr = CoInitializeEx(NULL, COINIT_APARTMENTTHREADED);
if (FAILED(hr))
{
printf("Failed CoInitializeEx [%x]\n", hr);
goto error;
}

// Create the CertAdmin object

// and get a pointer to its ICertAdmin interface.
hr = CoCreateInstance( CLSID_CCertAdmin,
NULL,
CLSCTX_INPROC_SERVER,
IID_ICertAdmin,
(void **)&pCertAdmin);
if (FAILED(hr))
{
printf("Failed CoCreateInstance pCertAdmin [%x]\n", hr);
goto error;
}

// Note the use of two backslashes (\\)

// in C++ to produce one backslash (\).
bstrCA = SysAllocString(L"<COMPUTERNAMEHERE>\\<CANAMEHERE>");
if (FAILED(hr))
{
printf("Failed to allocate memory for bstrCA\n");
goto error;
}

// Retrieve the CRL.

hr = pCertAdmin->GetCRL( bstrCA, CR_OUT_BINARY, &bstrCRL );
if (FAILED(hr))
{
printf("Failed GetCRL [%x]\n", hr);
goto error;
}
else
printf("CRL retrieved successfully\n");
// Use the CRL as needed.

// Done processing.

error:

// Free BSTR values.

if (NULL != bstrCA)
SysFreeString(bstrCA);

if (NULL != bstrCRL)
SysFreeString(bstrCRL);

// Clean up object resources.

if (NULL != pCertAdmin)
pCertAdmin->Release();

// Free COM resources.

CoUninitialize();
Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header certadm.h (include Certsrv.h)

Librar y Certidl.lib

DLL Certadm.dll

See also
CCertAdmin
ICertAdmin
ICer tAdmin2
ICertConfig
 ICertAdmin::GetRevocationReason method
(certadm.h)
7/2/2022 • 2 minutes to read • Edit Online

The GetRevocationReason method returns the reason a certificate was revoked. This method was first defined
in the ICertAdmin interface.
Before you call this method, you must call the IsValidCertificate method. For more information, see Remarks.

Syntax
HRESULT GetRevocationReason(
[out] LONG *pReason
);

Parameters
[out] pReason

A pointer to a variable that will receive the revocation reason.

Return value
C++
If the method succeeds, the method returns S_OK, and the pReason parameter is set to one of the values listed in
the following table.
If the method fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.
VB
Returns a value that specifies the reason the certificate was revoked. The value can be one of the following
revocation reason codes (defined in Wincrypt.h).

RET URN C O DE DESC RIP T IO N

No reason was specified for revocation.

CRL_REASON_UNSPECIFIED

It is known or suspected that the subject's private key or

CRL_REASON_KEY_COMPROMISE other aspects of the subject validated in the certificate are
compromised.

It is known or suspected that the CA's private key or other

CRL_REASON_CA_COMPROMISE aspects of the CA validated in the certificate are
compromised.

The subject's name or other information in the certificate has

CRL_REASON_AFFILIATION_CHANGED been modified but there is no cause to suspect that the
private key has been compromised.
 The certificate has been superseded, but there is no cause to
CRL_REASON_SUPERSEDED suspect that the private key has been compromised.

The certificate is no longer needed for the purpose for which

CRL_REASON_CESSATION_OF_OPERATION it was issued, but there is no cause to suspect that the
private key has been compromised.

The certificate has been placed on hold.

CRL_REASON_CERTIFICATE_HOLD

Remarks
Before you call GetRevocationReason , call the IsValidCertificate method to retrieve the disposition of the
certificate. To call GetRevocationReason , you must receive a certificate disposition CA_DISP_REVOKED from
this earlier call, indicating that the certificate has been revoked. The call to IsValidCer tificate establishes the
identity of the certificate whose revocation reason you want to retrieve.
Administration tasks use DCOM. Code that calls this interface method as defined in an earlier version of
Certadm.h will run on Windows-based servers as long as the client and the server are both running the same
Windows operating system.
Examples

// The value for nDisp was set by

// a call to ICertAdmin2::IsValidCertificate.
if (CA_DISP_REVOKED == nDisp)
{
// Variable to contain revocation reason.
long nReason;

// Retrieve the revocation reason.

hr = pCertAdmin->GetRevocationReason(&nReason);
if (FAILED(hr))
{
printf("Failed GetRevocationReason [%x]\n", hr);
goto error;
}
else
printf("Revocation reason = %d\n", nReason );
}

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header certadm.h (include Certsrv.h)

Librar y Certidl.lib
 DLL Certadm.dll

See also
CCertAdmin
ICertAdmin
ICertAdmin2
IsValidCertificate
 ICertAdmin::ImportCertificate method (certadm.h)
7/2/2022 • 3 minutes to read • Edit Online

The Impor tCer tificate method takes a previously issued certificate and imports it to the certification
authority's (CA) database. This method was first defined in the ICertAdmin interface.
For the requirements that the certificate must meet to be successfully imported, see Remarks.

Syntax
HRESULT ImportCertificate(
[in] const BSTR strConfig,
[in] const BSTR strCertificate,
[in] LONG Flags,
[out] LONG *pRequestId
);

Parameters
[in] strConfig

Represents a valid configuration string for the certification authority in the form COMPUTERNAME\CANAME,
where COMPUTERNAME is the Certificate Services server's network name, and CANAME is the common name
of the certification authority, as entered during Certificate Services setup. For information about the
configuration string name, see ICertConfig.

Impor tant Impor tCer tificate does not clear the internal cache when the configuration string is changed. When you
change the configuration string for the CA, you must instantiate a new ICertAdmin object and call this method again with the
new configuration string.

[in] strCertificate

The binary representation of the certificate being imported.

[in] Flags

Specifies the format of the certificate. This parameter can be one of the following values.

VA L UE M EA N IN G

BASE64 format with begin/end.

CR_IN_BASE64HEADER

BASE64 format without begin/end.

CR_IN_BASE64

Binary format.
CR_IN_BINARY
[out] pRequestId

A pointer to a LONG value that receives the database-assigned request ID for the imported certificate.

Return value
C++
If the method succeeds, and the pRequestID parameter is set to the value of the database-assigned request ID for
the imported certificate, the method returns S_OK.
If the method fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.
VB
The return value is the database-assigned request ID for the imported certificate.

Remarks
The Impor tCer tificate method is useful in the case of a certification authority that has been partially restored
from backup: If a certificate is not on the backup tapes used to restore the certification authority but exists in a
file, the certificate can be imported by means of this method.
For this method to succeed, the certificate being imported must have been previously issued by the certification
authority specified in strConfig. The restored certification authority will validate the certificate's signature, and if
the signature is not valid, the method call will fail.
Furthermore, you cannot import a certificate if it already exists in the database. Each certificate in the database
must be unique. The database ensures uniqueness by checking the certificate's serial number.
Examples

// This code imports a binary certificate file.

BSTR bstrCert = NULL; // Variable for certificate.
HANDLE hFile;
DWORD cchFile, cbRead;
LONG nID; // Variable for request ID.

// Open the file that contains the certificate.

hFile = CreateFile((LPCSTR) "d:\\cert1.cer",
GENERIC_READ,
FILE_SHARE_READ,
NULL,
OPEN_EXISTING,
0,
NULL);
if (INVALID_HANDLE_VALUE == hFile)
{
printf("Unable to open file\n");
// Take error action as needed.
}
// Determine the file size.
cchFile = GetFileSize(hFile, NULL);
if ( (DWORD)-1 == cchFile )
{
printf("Failed GetFileSize\n");
CloseHandle(hFile);
// Take error action as needed.
}
// Allocate the memory for the certificate.
bstrCert = SysAllocStringByteLen(NULL, cchFile);
if (NULL == bstrCert)
{
printf("Failed SysAllocStringByteLen\n");
 CloseHandle(hFile);
// Take error action as needed.
}
// Read in the certificate.
if (!ReadFile(hFile,
(char *)bstrCert,
cchFile,
&cbRead,
NULL) || (cbRead != cchFile))
{
printf("Failed to successfully read file\n");
CloseHandle(hFile);
SysFreeString(bstrCert);
// Take error action as needed.
}
// Close the file.
CloseHandle(hFile);

// Import the certificate.

bstrCA = SysAllocString(L"<COMPUTERNAMEHERE>\\<CANAMEHERE>");
if (FAILED(hr))
{
printf("Failed to allocate memory for bstrCA\n");
SysFreeString(bstrCert);
// Take error action as needed.
}

hr = pCertAdmin->ImportCertificate(bstrCA,
bstrCert,
CR_IN_BINARY,
&nID);
if (FAILED(hr))
printf("Failed ImportCertificate [%x]\n", hr);
else
printf("Imported certificated has Request ID: %d\n", nID);

SysFreeString(bstrCert);
SysFreeString(bstrCA);

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header certadm.h (include Certsrv.h)

Librar y Certidl.lib

DLL Certadm.dll

See also
CCertAdmin
ICertAdmin
ICertAdmin2
ICertConfig
 ICertAdmin::IsValidCertificate method (certadm.h)
7/2/2022 • 2 minutes to read • Edit Online

The IsValidCer tificate method verifies the certificate against the certification authority (CA) key and checks
that the certificate has not been revoked. This method was first defined in the ICertAdmin interface.

Syntax
HRESULT IsValidCertificate(
[in] const BSTR strConfig,
[in] const BSTR strSerialNumber,
[out, retval] LONG *pDisposition
);

Parameters
[in] strConfig

Represents a valid configuration string for the CA in the form COMPUTERNAME\CANAME, where
COMPUTERNAME is the network name of the Certificate Services server and CANAME is the common name of
the certification authority, as entered during Certificate Services setup. For information about the configuration
string name, see ICertConfig.

Impor tant IsValidCer tificate does not clear the internal cache when the configuration string is changed. When you
change the configuration string for the CA, you must instantiate a new ICertAdmin object and call this method again with the
new configuration string.

[in] strSerialNumber

Specifies a serial number that identifies the certificate to be reviewed. The string must specify the serial number
as an even number of hexadecimal digits. If necessary, a zero can be prefixed to the number to produce an even
number of digits. No more than one leading zero may be used.
[out, retval] pDisposition

A pointer to a LONG that receives the disposition value.

Return value
C++
If the method succeeds and the pDisposition parameter is set to one of the following values, the method returns
S_OK.
If the method fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.
VB
The return value specifies the disposition of the certificate. This value is one of the following values. (These values
are defined in Certadm.h.)
 RET URN C O DE DESC RIP T IO N

The call was not completed.

CA_DISP_INCOMPLETE

The call failed.

CA_DISP_ERROR

The certificate has been revoked.

CA_DISP_REVOKED

The certificate is still valid.

CA_DISP_VALID

The certificate was never issued.

CA_DISP_INVALID

The certificate is pending.

CA_DISP_UNDER_SUBMISSION

Remarks
This method determines only whether a certificate has been issued and is not currently revoked; it does not
check that the current time and date are within the period for which the certificate is valid (the NotBefore and
NotAfter certificate properties). An application that uses this method is also responsible for checking the
certificate expiration.
Administration tasks use DCOM. Code that calls this interface method as defined in an earlier version of
Certadm.h will run on Windows-based servers as long as the client and the server are both running the same
Windows operating system.
Examples
 BSTR bstrCA = NULL; // Machine\CAName
BSTR bstrSerial = NULL; // Contains the certificate
// serial number
long nDisp; // Contains the certificate
// disposition
HRESULT hr;

bstrCA = SysAllocString(L"<COMPUTERNAMEHERE>\\<CANAMEHERE>");
bstrSerial = SysAllocString(L"<SERIALNUMBERHERE>");

if (NULL == bstrCA || NULL == bstrSerial)

{
printf("Memory allocation failed\n");
goto error;
}

// Determine whether the certificate is valid.

// pCertAdmin is a previously instantiated ICertAdmin
// object pointer.
hr = pCertAdmin->IsValidCertificate(bstrCA, bstrSerial, &nDisp);
if (FAILED(hr))
{
printf("Failed IsValidCertificate [%x]\n", hr);
goto error;
}
// Use nDisp as needed.

// Done processing.

error:

// Free BSTR values.

if (NULL != bstrCA)
SysFreeString(bstrCA);

if (NULL != bstrSerial)
SysFreeString(bstrSerial);

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header certadm.h (include Certsrv.h)

Librar y Certidl.lib

DLL Certadm.dll

See also
CCertAdmin
ICertAdmin
ICertAdmin2
ICertConfig
 ICertAdmin::PublishCRL method (certadm.h)
7/2/2022 • 2 minutes to read • Edit Online

The PublishCRL method sends a request to the Certificate Services certification authority (CA) to publish a new
certificate revocation list (CRL). This method was first introduced in the ICertAdmin interface.

Syntax
HRESULT PublishCRL(
[in] const BSTR strConfig,
[in] DATE Date
);

Parameters
[in] strConfig

Represents a valid configuration string for the CA in the form COMPUTERNAME\CANAME, where
COMPUTERNAME is the Certificate Services server's network name, and CANAME is the common name of the
certification authority, as entered during Certificate Services setup. For information about the configuration
string name, see ICertConfig.

Impor tant PublishCRL does not clear the internal cache when the configuration string is changed. When you change the
configuration string for the CA, you must instantiate a new ICertAdmin object and call this method again with the new
configuration string.

[in] Date

Specifies the next update value of the CRL in Coordinated Universal Time (Greenwich Mean Time). If Date is
nonzero, the next update value for the CRL is Date, subject to rounding or ceiling limits enforced by Certificate
Services. If Date is zero, the next update value of the CRL is calculated from the default CRL publication period.

Return value
VB
If the method succeeds, the method returns S_OK.
If the method fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.

Remarks
Administration tasks use DCOM. Code that calls this interface method as defined in an earlier version of
Certadm.h will run on Windows-based servers as long as the client and the server are both running the same
Windows operating system.
Examples
The following example shows publishing a CRL.
 DATE ExpDate; // CRL expiration date
SYSTEMTIME st;
BSTR bstrCA = NULL;

// Set the CRL Expiration Date to Noon on Jan. 1, 2005 GMT.

// Zero out values first
// (avoids setting minutes, seconds, and so on).
memset(&st, 0, sizeof(SYSTEMTIME));
st.wYear = 2005;
st.wMonth = 1; // Jan
st.wDay = 1; // 1st day of month
st.wHour = 12; // Noon

// Place the date in required format.

if (!SystemTimeToVariantTime(&st, &ExpDate))
{
printf("Unable to convert time\n");
goto error;
}

bstrCA = SysAllocString(L"<COMPUTERNAMEHERE>\\<CANAMEHERE>");
if (NULL == bstrCA)
{
printf("Memory allocation failed\n");
goto error;
}

// Publish the CRL.

// pCertAdmin is a previously instantiated ICertAdmin object.
hr = pCertAdmin->PublishCRL(bstrCA, ExpDate);
if (FAILED(hr))
{
printf("Failed PublishCRL [%x]\n", hr);
goto error;
}
else
printf("PublishCRL succeeded\n");

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header certadm.h (include Certsrv.h)

Librar y Certidl.lib

DLL Certadm.dll

See also
CCertAdmin
ICertAdmin
ICertAdmin2
ICertConfig
 ICertAdmin::ResubmitRequest method (certadm.h)
7/2/2022 • 2 minutes to read • Edit Online

The ResubmitRequest method submits the specified certificate request to the policy module for the specified
certification authority. This method was first introduced in the ICertAdmin interface.
For this method to succeed, the certificate request must be pending.

Syntax
HRESULT ResubmitRequest(
[in] const BSTR strConfig,
[in] LONG RequestId,
[out, retval] LONG *pDisposition
);

Parameters
[in] strConfig

Represents a valid configuration string for the certification authority (CA) in the form
COMPUTERNAME\CANAME, where COMPUTERNAME is the network name of the Certificate Services server
and CANAME is the common name of the certification authority, as entered during Certificate Services setup.
For information about the configuration string name, see ICertConfig.

Impor tant ResubmitRequest does not clear the internal cache when the configuration string is changed. When you
change the configuration string for the CA, you must instantiate a new ICertAdmin object and call this method again with the
new configuration string.

[in] RequestId

Specifies the ID of the request to resubmit.

[out, retval] pDisposition

A pointer to the disposition of the request.

Return value
C++
If the method succeeds and the pDisposition parameter is set to one of the following values that specify the
disposition of the request, the method returns S_OK.
If the method fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.
VB
The return value specifies the disposition of the request. This value is one of the following values.
RET URN C O DE DESC RIP T IO N
 The request was not completed.
CR_DISP_INCOMPLETE

The request failed.

CR_DISP_ERROR

The request was denied.

CR_DISP_DENIED

The certificate was issued.

CR_DISP_ISSUED

The certificate was issued separately.

CR_DISP_ISSUED_OUT_OF_BAND

The request was taken under submission.

CR_DISP_UNDER_SUBMISSION

Remarks
Administration tasks use DCOM. Code that calls this interface method as defined in an earlier version of
Certadm.h will run on Windows-based servers as long as the client and the server are both running the same
Windows operating system.
Examples

#include <windows.h>
#include <stdio.h>
#include <Certadm.h>

long nDisp; // disposition value

long nReqID = <REQUESTIDHERE>;
BSTR bstrCA = NULL;

bstrCA = SysAllocString(L"<COMPUTERNAMEHERE>\\<CANAMEHERE>");
if (NULL == bstrCA)
{
printf("Memory allocation failed\n");
goto error;
}

// pCertAdmin is a previously instantiated ICertAdmin object.

hr = pCertAdmin->ResubmitRequest(bstrCA, nReqID, &nDisp);
if (FAILED(hr))
{
printf("Failed ResubmitRequest [%x]\n", hr);
goto error;
}
else
printf("ResubmitRequest disposition is %d\n", nDisp);

error:
// Free resources.
if (bstrCA)
SysFreeString(bstrCA);
Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header certadm.h (include Certsrv.h)

Librar y Certidl.lib

DLL Certadm.dll

See also
CCertAdmin
ICertAdmin
ICertAdmin2
ICertConfig
ICertRequest::Submit
 ICertAdmin::RevokeCertificate method (certadm.h)
7/2/2022 • 3 minutes to read • Edit Online

The RevokeCer tificate method revokes a certificate either on a specified date or immediately. This method
was first defined in the ICertAdmin interface.
A revoked certificate will appear in a subsequent certificate revocation lists (CRLs), provided the revocation date
is effective at the time the CRL was published.

Syntax
HRESULT RevokeCertificate(
[in] const BSTR strConfig,
[in] const BSTR strSerialNumber,
[in] LONG Reason,
[in] DATE Date
);

Parameters
[in] strConfig

Represents a valid configuration string for the certification authority (CA) server in the form
COMPUTERNAME\CANAME, where COMPUTERNAME is the network name of the Certificate Services server
and CANAME is the common name of the certification authority, as entered during Certificate Services setup.
For information about the configuration string name, see ICertConfig.

Impor tant RevokeCer tificate does not clear the internal cache when the configuration string is changed. When you
change the configuration string for the CA, you must instantiate a new ICertAdmin object and call this method again with the
new configuration string.

[in] strSerialNumber

Specifies a serial number that identifies the certificate to be revoked. The string must specify the serial number
as an even number of hexadecimal digits. If necessary, a zero can be prefixed to the number to produce an even
number of digits. However, no more than one leading zero may be used.
[in] Reason

Specifies the reason for the revocation. The following values (defined in Wincrypt.h) are supported reason
codes.
CRL_REASON_UNSPECIFIED (0)
CRL_REASON_KEY_COMPROMISE (1)
CRL_REASON_CA_COMPROMISE (2)
CRL_REASON_AFFILIATION_CHANGED (3)
CRL_REASON_SUPERSEDED (4)
CRL_REASON_CESSATION_OF_OPERATION (5)
CRL_REASON_CERTIFICATE_HOLD (6)
You can reinstate a certificate revoked with the CRL_REASON_CERTIFICATE_HOLD revocation reason code by
calling RevokeCer tificate with MAXDWORD as the Reason value. Note that if a certificate has been revoked
with any reason code other than CRL_REASON_CERTIFICATE_HOLD, it cannot be reinstated.
[in] Date

Specifies the date, in Coordinated Universal Time (Greenwich Mean Time), on which the revocation will become
effective. The value zero indicates the current Coordinated Universal Time, causing a certificate to be revoked
immediately. The value of Date appears in the Effective Revocation Date column of the revoked certificate (in
the Certification Authority MMC snap-in).

Return value
VB
If the method succeeds, the method returns S_OK.
If the method fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.

Remarks
This method can be called more than once on the same certificate, which allows you to change the effective
revocation date and revocation reason.
If a currently revoked certificate has CRL_REASON_CERTIFICATE_HOLD as its reason code, you can reinstate the
certificate by calling RevokeCer tificate with MAXDWORD (defined in Winnt.h) as the value for its reason code
(the Reason parameter). After it is reinstated, the certificate will not appear in future CRLs.
Administration tasks use DCOM. Code that calls this interface method as defined in an earlier version of
Certadm.h will run on Windows-based servers as long as the client and the server are both running the same
Windows operating system.
Examples
 BSTR bstrCA = NULL;
BSTR bstrSerial = NULL; // certificate serial number
long nReason;
DATE RevokeDate; // revocation date
SYSTEMTIME st;

bstrSerial = SysAllocString(L"<SERIALNUMBERHERE>");
bstrCA = SysAllocString(L"<COMPUTERNAMEHERE>\\<CANAMEHERE>");
if (NULL == bstrCA || NULL == bstrSerial)
{
printf("Memory allocation failed\n");
goto error;
}

nReason = CRL_REASON_AFFILIATION_CHANGED; // Defined

// in Wincrypt.h

// Specify when the cert should be revoked.

// Note: To revoke immediately, set RevokeDate to zero.
// This example sets the revoke date to noon on 1/1/2001.
// Zero out values first (avoids setting minutes, seconds,
// and so on).
memset(&st, 0, sizeof(SYSTEMTIME));
st.wYear = 2001;
st.wMonth = 1; // Jan
st.wDay = 1; // 1st day of month
st.wHour = 12; // Noon

// Place the date in the required format.

if (!SystemTimeToVariantTime(&st, &RevokeDate))
{
printf("Unable to convert time.\n");
goto error;
}

// Revoke the certificate.

// pCertAdmin is a previously instantiated ICertAdmin object.
hr = pCertAdmin->RevokeCertificate( bstrCA,
bstrSerial,
nReason,
RevokeDate );
if (FAILED(hr))
{
printf("Failed RevokeCertificate. [%x]\n", hr);
goto error;
}
else
printf("Certificate %ws revoked.\n", bstrSerial );

// Done processing.

error:

// Free resources.
if (bstrSerial)
SysFreeString( bstrSerial );
if (bstrCA)
SysFreeString( bstrCA );

Requirements

Minimum suppor ted client None supported

 Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header certadm.h (include Certsrv.h)

Librar y Certidl.lib

DLL Certadm.dll

See also
CCertAdmin
ICertAdmin
ICertAdmin2
ICertConfig
 ICertAdmin::SetCertificateExtension method
(certadm.h)
7/2/2022 • 2 minutes to read • Edit Online

The SetCer tificateExtension method adds a new extension to the certificate issued in response to a certificate
request. This method was first defined by the ICertAdmin interface.
For this method to succeed, the certificate request must be pending.

Syntax
HRESULT SetCertificateExtension(
[in] const BSTR strConfig,
[in] LONG RequestId,
[in] const BSTR strExtensionName,
[in] LONG Type,
[in] LONG Flags,
[in] const VARIANT *pvarValue
);

Parameters
[in] strConfig

Represents a valid configuration string for the certification authority (CA) server in the form
COMPUTERNAME\CANAME, where COMPUTERNAME is the network name of the Certificate Services server
and CANAME is the common name of the certification authority, as entered during Certificate Services setup.
For information about the configuration string name, see ICertConfig.

Impor tant SetCer tificateExtension does not clear the internal cache when the configuration string is changed. When you
change the configuration string for the CA, you must instantiate a new ICertAdmin object and call this method again with the
new configuration string.

[in] RequestId

Specifies the ID of the certificate request.

[in] strExtensionName

Specifies the object identifier (OID) for the extension to set. The string must be 31 or fewer non-NULL characters
in length.
[in] Type

Specifies the type of extension being set. The Type parameter must agree with the data type of the pvarValue
parameter. This data type is set in the vt field of the VARIANT structure.
This parameter can be one of the following values.

VA L UE M EA N IN G
 Signed long data
PROPTYPE_LONG

Date/time
PROPTYPE_DATE

The extension value is set as is and is assumed to be ASN.1

PROPTYPE_BINARY encoded if necessary.

The extension value will be ASN.1 encoded as an IA5 string

PROPTYPE_STRING before it is placed in the new certificate.

Note You should use PROPTYPE_STRING for an

extension value that consists of a single URL only if you
want the URL to be automatically encoded as an IA5 string.
Otherwise, encode the URL as an IA5 string yourself and
pass the encoded value as PROPTYPE_BINARY .

[in] Flags

Specifies the flags for the extension being set. If no flag is to be set, use a value of zero. You can combine these
flags with a bitwise-OR operation and also with policy private extension flags (the high 8 bits of the
EXTENSION_POLICY_MASK field).

Note When the Flags parameter is set to EXTENSION_DISABLE_FLAG, the extension will be disabled in the server log and will
not be added to the certificate.

VA L UE M EA N IN G

This is a critical extension.

EXTENSION_CRITICAL_FL AG

The extension will not be used.

EXTENSION_DISABLE_FL AG

[in] pvarValue

Specifies the value associated with the extension.

Return value
VB
If the method succeeds, the method returns S_OK.
If the method fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.

Remarks
Administration tasks use DCOM. Code that calls this interface method as defined in an earlier version of
Certadm.h will run on Windows-based servers as long as the client and the server are both running the same
Windows operating system.

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header certadm.h (include Certsrv.h)

Librar y Certidl.lib

DLL Certadm.dll

See also
CCertAdmin
ICertAdmin
ICertAdmin2
ICertConfig
 ICertAdmin::SetRequestAttributes method
(certadm.h)
7/2/2022 • 3 minutes to read • Edit Online

The SetRequestAttributes method sets attributes in the specified pending certificate request. This method was
first defined in the ICertAdmin interface.
For this method to succeed, the certificate request must be pending.

Syntax
HRESULT SetRequestAttributes(
[in] const BSTR strConfig,
[in] LONG RequestId,
[in] const BSTR strAttributes
);

Parameters
[in] strConfig

Represents a valid configuration string for the certification authority (CA) server in the form
COMPUTERNAME\CANAME, where COMPUTERNAME is the network name of the Certificate Services server
and CANAME is the common name of the certification authority, as entered during Certificate Services setup.
For information about the configuration string name, see ICertConfig.

Impor tant SetRequestAttributes does not clear the internal cache when the configuration string is changed. When you
change the configuration string for the CA, you must instantiate a new ICertAdmin object and call this method again with the
new configuration string.

[in] RequestId

Specifies the ID of the request receiving the attributes.

[in] strAttributes

Specifies the attribute data. Each attribute is a name-value string pair. The colon character separates the name
and value, and a newline character separates multiple name-value pairs, for example:

C++ AttributeName1: AttributeValue1\ nAttributeName2:

AttributeValue2

VB AttributeName1: AttributeValue1 & vbNewLine &

AttributeName2: AttributeValue2

There is no set limit to the number of request attributes that may be added to a request.
When Certificate Services parses attribute names, it ignores spaces, hyphens (minus signs), and case. For
example, AttributeName1, Attribute Name1, and Attribute-name1 are all equivalent. For attribute values,
Certificate Services ignores leading and trailing white space.
 Note The maximum length for an attribute name is 127 non-NULL characters. The maximum length for an attribute value is
4,096 non-NULL characters.

Return value
VB
If the method succeeds, the method returns S_OK.
If the method fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.

Remarks
Attributes added or updated by calling SetRequestAttributes do not alter the initial, unparsed attribute string
associated with the certificate request. The certificate request's unparsed attribute string is unalterable after the
certificate is requested (the ICertRequest::Submit method allows attributes to be specified at the time the
certificate is requested).
You can use the Certification Authority MMC snap-in to display the initial unparsed request attribute string.
When you view the parsed attributes, you will also see any changes due to calls to SetRequestAttributes .
To view the parsed attributes
1. Open the Certification Authority MMC snap-in.
2. Open the Pending Requests folder.
3. Right-click a request, point to All Tasks , and then click View Attributes/Extensions .
To enumerate or view all of the parsed attributes, including those added by means of SetRequestAttributes , you
may also use the IEnumCERTVIEWATTRIBUTE interface.
Administration tasks use DCOM. Code that calls this interface method as defined in an earlier version of
Certadm.h will run on Windows-based servers as long as the client and the server are both running the same
Windows operating system.
Examples
 BSTR bstrAttribs = NULL;
BSTR bstrCA = NULL;
long nReqID; // request ID

// Specify the attributes.

// For example, "AttName1:AttValue1\nAttName2:AttValue2".
bstrAttribs = SysAllocString(L"<ATTRIBUTESHERE>");
if (NULL == bstrAttribs)
{
printf("Memory allocation failed for bstrAttribs.\n");
goto error;
}

bstrCA = SysAllocString(L"<COMPUTERNAMEHERE>\\<CANAMEHERE>");
if (NULL == bstrCA)
{
printf("Memory allocation failed for bstrCA.\n");
goto error;
}

// Request ID to receive the attributes.

nReqID = <REQUESTIDHERE>;

// Add these attributes to the certificate.

// pCertAdmin is a previously instantiated
// ICertAdmin object pointer.
hr = pCertAdmin->SetRequestAttributes( bstrCA,
nReqID,
bstrAttribs );
if (FAILED(hr))
printf("Failed SetRequestAttributes [%x]\n", hr);
else
printf("SetRequestAttributes succeeded\n");

// Done processing.

error:

if (bstrAttribs)
SysFreeString(bstrAttribs);
if (bstrCA)
SysFreeString(bstrCA);
// Free other resources.

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header certadm.h (include Certsrv.h)

Librar y Certidl.lib

DLL Certadm.dll
See also
CCertAdmin
ICertAdmin
ICertAdmin2
ICertConfig
IEnumCERTVIEWATTRIBUTE
 ICertAdmin2 interface (certadm.h)
7/2/2022 • 2 minutes to read • Edit Online

The ICer tAdmin2 interface is one of two interfaces that provide administration functionality for properly
authorized clients.
The ICer tAdmin2 interface is used to perform the following tasks:
Authorize or deny a certificate request.
Revoke an issued certificate.
Trigger the generation of a certificate revocation list (CRL).
Get the current CRL for the server.
Determine whether a certificate is valid.
Get an archived key.
Get a certification authority (CA) display name, property, or property flag.
Publish one or several CRLs.
Get or set configuration information.
Determine which roles are set.
Import a certificate or key.
Certificate Services interfaces support both apartment-threading and free-threading models. For better throughput,
free threading is recommended.

Inheritance
The ICer tAdmin2 interface inherits from ICertAdmin and IDispatch. ICer tAdmin2 also has these types of
members:

Methods
The ICer tAdmin2 interface has these methods.

ICertAdmin2::DeleteRow

The DeleteRow method deletes a row or set of rows from a database table. The caller specifies a database table and either a
row ID or an ending date.

ICertAdmin2::GetArchivedKey

Retrieves an archived key recovery BLOB.

ICertAdmin2::GetCAProperty

Retrieves a property value for the certification authority (CA).

ICertAdmin2::GetCAPropertyDisplayName

The ICertAdmin2::GetCAPropertyDisplayName method retrieves the property display name for a certification authority (CA)
property.
 ICertAdmin2::GetCAPropertyFlags

The ICertAdmin2::GetCAPropertyFlags method retrieves the property flags for a certification authority (CA) property.

ICertAdmin2::GetConfigEntry

Retrieves configuration information for a certification authority (CA).

ICertAdmin2::GetMyRoles

Retrieves the certification authority (CA) roles of the caller.

ICertAdmin2::ImportKey

Adds an encrypted key set to an item in the Certificate Services database. The key set is encrypted to one or several key
recovery agent (KRA) certificates.

ICertAdmin2::PublishCRLs

Publishes certificate revocation lists (CRLs) for a certification authority (CA).

ICertAdmin2::SetCAProperty

Sets a property value for the certification authority (CA).

ICertAdmin2::SetConfigEntry

Sets configuration information for a certification authority (CA).

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header certadm.h (include Certsrv.h)

 ICertAdmin2::DeleteRow method (certadm.h)
7/2/2022 • 2 minutes to read • Edit Online

The DeleteRow method deletes a row or set of rows from a database table. The caller specifies a database table
and either a row ID or an ending date.

Syntax
HRESULT DeleteRow(
[in] const BSTR strConfig,
[in] LONG Flags,
[in] DATE Date,
[in] LONG Table,
[in] LONG RowId,
[out] LONG *pcDeleted
);

Parameters
[in] strConfig

Represents a valid configuration string for the certification authority (CA) in the form
COMPUTERNAME\CANAME, where COMPUTERNAME is the Certificate Services server's network name, and
CANAME is the common name of the certification authority, as entered during Certificate Services setup. For
information about the configuration string name, see ICertConfig.

Impor tant DeleteRow does not clear the internal cache when the configuration string is changed. When you change the
configuration string for the CA, you must instantiate a new ICertAdmin object and call this method again with the new
configuration string.

[in] Flags

If not zero, specifies whether Date applies to an expiration date or a last modified date.
This can be one of the following values.

VA L UE M EA N IN G

The rows being deleted have an expiration date less than

CDR_EXPIRED Date. This flag can be used when Table is
CVRC_TABLE_REQCERT or CVRC_TABLE_CRL.

The rows being deleted are for pending or denied requests,

CDR_REQUEST_L AST_CHANGED and their last modified date is less than Date. This flag can
be used when Table is CVRC_TABLE_REQCERT.

[in] Date

Specifies an expiration date when deleting certificates or CRLs, and a last modified date when deleting certificate
requests.
If this value is not zero, then RowID must be zero.
[in] Table

A LONG value that specifies the Certificate Services database table from which the rows are to be deleted.
This can be one of the following values.

VA L UE M EA N IN G

The attributes table is used.

CVRC_TABLE_ATTRIBUTES

The certificate revocation list (CRL) table is used.

CVRC_TABLE_CRL

The extensions table is used.

CVRC_TABLE_EXTENSIONS

The table of pending requests, denied requests, issued

CVRC_TABLE_REQCERT certificates, and revoked certificates is used.

[in] RowId

Specifies the ID of the row to delete.

If this value is not zero, then Date must be zero.
[out] pcDeleted

The number of rows successfully deleted.

Return value
C++
The return value is an HRESULT . A value of S_OK indicates the method was successful, and *pcDeleted is set to the
number of rows deleted.
VB
The number of rows deleted.

Remarks
RowID and Date are mutually exclusive; one and only one of them can be nonzero.

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

 Header certadm.h (include Certsrv.h)

Librar y Certidl.lib

DLL Certadm.dll

See also
CCer tAdmin
ICertAdmin
ICertAdmin2
 ICertAdmin2::GetArchivedKey method (certadm.h)
7/2/2022 • 2 minutes to read • Edit Online

The GetArchivedKey method retrieves an archived key recovery BLOB. This method was first defined in the
ICertAdmin interface.

Syntax
HRESULT GetArchivedKey(
[in] const BSTR strConfig,
[in] LONG RequestId,
[in] LONG Flags,
[out] BSTR *pstrArchivedKey
);

Parameters
[in] strConfig

Represents a valid configuration string for the certification authority (CA) in the form ComputerName\CAName,
where ComputerName is the Certificate Services server's network name, and CAName is the common name of
the CA, as entered during Certificate Services setup. For information about the configuration string name, see
ICertConfig.

Impor tant GetArchivedKey does not clear the internal cache when the configuration string is changed. When you change
the configuration string for the CA, you must instantiate a new ICertAdmin object and call this method again with the new
configuration string.

[in] RequestId

Represents the certificate request ID in the Certificates Services database.

[in] Flags

The following flags can be used to specify the format of the returned BLOB.

VA L UE M EA N IN G

BASE64 without BEGIN/END

CR_OUT_BASE64

BASE64 with BEGIN CERTIFICATE and END CERTIFICATE

CR_OUT_BASE64HEADER

Binary
CV_OUT_BINARY

[out] pstrArchivedKey
A pointer to the string that represents the retrieved archived key BLOB. When you have finished using this
string, it is the responsibility of the caller to free it by calling the SysFreeString function.

Return value
C++
The return value is an HRESULT . A value of S_OK indicates the method was successful.
VB
A string that contains the retrieved archived key BLOB.

Remarks
An archived key is encrypted in a PKCS #7 to the key recovery agent certificate or certificates, and is stored in
the Certificate Services database in that form. This method retrieves the encrypted PKCS #7 from the Certificate
Services database, wraps it in a signed PKCS #7 which contains the user certificate and chain, the key recovery
agent certificate or certificates, and the certification authority's signing certificate and chain. An authenticated
attribute contains a certificate used to uniquely identify the user certificate.

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header certadm.h (include Certsrv.h)

Librar y Certidl.lib

DLL Certadm.dll
 ICertAdmin2::GetCAProperty method (certadm.h)
7/2/2022 • 6 minutes to read • Edit Online

The GetCAProper ty method retrieves a property value for the certification authority (CA). This method was
first defined in the ICertAdmin interface.

Syntax
HRESULT GetCAProperty(
[in] const BSTR strConfig,
[in] LONG PropId,
[in] LONG PropIndex,
[in] LONG PropType,
[in] LONG Flags,
[out] VARIANT *pvarPropertyValue
);

Parameters
[in] strConfig

Represents a valid configuration string for the CA in the form COMPUTERNAME\CANAME, where
COMPUTERNAME is the Certificate Services server's network name, and CANAME is the common name of the
CA, as entered during Certificate Services setup. For information about the configuration string name, see
ICertConfig.

Impor tant GetCAProper ty does not clear the internal cache when the configuration string is changed. When you change
the configuration string for the CA, you must instantiate a new ICertAdmin object and call this method again with the new
configuration string.

[in] PropId

Specifies one of the following property identifiers.

VA L UE M EA N IN G

Data type of the property: Long

CR_PROP_ADVANCEDSERVER
Specifies whether the CA is running Advanced Server.

Data type of the property: Binary, indexed

CR_PROP_BASECRL
The CA's full, or base, certificate revocation list (CRL).

Data type of the property: Long, indexed

CR_PROP_BASECRLPUBLISHSTATUS
The base CRL publish status. For more details, see
Remarks.
 Data type of the property: Binary, indexed
CR_PROP_CABACKWARDCROSSCERT
The backward cross certificate. A backward cross
certificate is the certificate issued upon renewal from the
CA to itself signed with CA's new key. The backward
cross certificate has the authority key identifier of the
new CA certificate and the subject key identifier of the
old CA certificate.
Applies to root CAs only.

Data type of the property: Long, indexed

CR_PROP_CABACKWARDCROSSCERTSTATE
Whether the backward cross certificate is valid. Valid for
root CAs only.

Data type of the property: Long

CR_PROP_CACERTSTATE
State of the CA certificate. The values can be:
CA_DISP_REVOKED
CA_DISP_VALID
CA_DISP_INVALID

Data type of the property: Long, indexed

CR_PROP_CACERTSTATUSCODE
Status of the CA certificate, as an HRESULT .

Data type of the property: Long, indexed

CR_PROP_CACERTVERSION
Version of the CA certificate, as a DWORD. The high-
order word is the key index, and the low-order word is
the CA certificate index.

Data type of the property: Binary, indexed

CR_PROP_CAFORWARDCROSSCERT
The forward cross certificate. A forward cross certificate
is a certificate issued upon renewal from the CA to itself
signed with CA's previous key. The forward cross
certificate has the authority key identifier of the previous
CA certificate and the subject key identifier of the new
CA certificate.
Applies to root CAs only.

Data type of the property: Long, indexed

CR_PROP_CAFORWARDCROSSCERTSTATE
Whether the forward cross certificate is valid. Valid for
root CAs only.

Data type of the property: String

CR_PROP_CANAME
Name of the CA.

Data type of the property: Binary, indexed

CR_PROP_CASIGCERT
CA signing certificate.

Data type of the property: Binary, indexed

CR_PROP_CASIGCERTCHAIN
CA signing certificate chain.
 Data type of the property: Long
CR_PROP_CASIGCERTCOUNT
Number of signing certificates for the CA.

Data type of the property: Binary, indexed

CR_PROP_CASIGCERTCRLCHAIN
The CA's signing certificate CRL chain.

Data type of the property: Long

CR_PROP_CATYPE
Type of CA. This can be one of the following values
(defined in Certsrv.h):
ENUM_ENTERPRISE_ROOTCA
ENUM_ENTERPRISE_SUBCA
ENUM_STANDALONE_ROOTCA
ENUM_STANDALONE_SUBCA

Data type of the property: Binary, indexed

CR_PROP_CAXCHGCERT
CA exchange certificate.

Data type of the property: Binary, indexed

CR_PROP_CAXCHGCERTCHAIN
CA exchange certificate chain.

Data type of the property: Long

CR_PROP_CAXCHGCERTCOUNT
Number of exchange certificates for the CA.

Data type of the property: Binary, indexed

CR_PROP_CAXCHGCERTCRLCHAIN
The CA's exchange certificate CRL chain.

Data type of the property: String, indexed

CR_PROP_CERTAIAURLS
Specifies Authority Information Access URLs as the type
of URL requested by a client.
Windows Ser ver 2003: This flag is not supported.

Data type of the property: String, indexed

CR_PROP_CERTCDPURLS
Specifies CRL Distribution Point URLs as the type of URL
requested by a client.
Windows Ser ver 2003: This flag is not supported.

Data type of the property: Long

CR_PROP_CRLSTATE
State of the CA's CRL. The values can be:
CA_DISP_REVOKED
CA_DISP_VALID
CA_DISP_INVALID
CA_DISP_ERROR

Data type of the property: Binary, indexed

CR_PROP_DELTACRL
The CA's delta CRL.
 Data type of the property: Long, indexed
CR_PROP_DELTACRLPUBLISHSTATUS
The delta CRL publish status. For more details, see
Remarks.

Data type of the property: String

CR_PROP_DNSNAME
The CA's DNS Name.

Data type of the property: Long

CR_PROP_EXITCOUNT
Number of exit modules in use by the CA.

Data type of the property: String

CR_PROP_EXITDESCRIPTION
Description for the exit module.

Data type of the property: String

CR_PROP_FILEVERSION
The Certificate Services file version.

Data type of the property: Binary, indexed

CR_PROP_KRACERT
The CA's key recovery agent (KRA) certificate.

Data type of the property: Long

CR_PROP_KRACERTCOUNT
Number of KRA certificates for the CA.

Data type of the property: Long, indexed

CR_PROP_KRACERTSTATE
The KRA's certificate state. The return value is one of the
following:
KRA_DISP_EXPIRED
KRA_DISP_NOTFOUND
KRA_DISP_REVOKED
KRA_DISP_VALID
KRA_DISP_UNTRUSTED
KRA_DISP_NOTLOADED
KRA_DISP_INVALID

Data type of the property: Long

CR_PROP_KRACERTUSEDCOUNT
Number of KRA certificates used by the CA.

Data type of the property: String

CR_PROP_PARENTCA
The name of the CA's parent CA.

Data type of the property: String

CR_PROP_POLICYDESCRIPTION
The description for the policy module.

Data type of the property: String

CR_PROP_PRODUCTVERSION
The product version in which the file shipped.
 Data type of the property: Long
CR_PROP_ROLESEPARATIONENABLED
Value specifying whether role separation is enabled.

Data type of the property: String

CR_PROP_SANITIZEDCANAME
The sanitized name of the CA. For a definition of a
sanitized CA name, see ICertConfig2::GetConfig.

Data type of the property: String

CR_PROP_SANITIZEDCASHORTNAME
The sanitized short name of the CA. For a definition of a
sanitized CA short name, see ICertConfig2::GetConfig.

Data type of the property: String

CR_PROP_SHAREDFOLDER
The name of the shared folder directory.

Data type of the property: String

CR_PROP_TEMPL ATES
List of templates supported by the CA.

[in] PropIndex

If the PropId parameter is indexed, the zero-based index to use when retrieving the property value. If PropId is
not indexed, this value is ignored.
[in] PropType

Specifies the type of the property, indicated in the Meaning column of the PropId table. The type can be one of
the following types.

VA L UE M EA N IN G

Signed long data

PROPTYPE_LONG

Date/time (reserved for future use)

PROPTYPE_DATE

Binary data
PROPTYPE_BINARY

Unicode string data

PROPTYPE_STRING

[in] Flags

The following flags can be used to specify the format of the returned property value; these flags have meaning
only for binary data (such as certificates, certificate chains or certificate revocation lists) and is ignored
otherwise.

VA L UE M EA N IN G

BASE64 without BEGIN/END

CV_OUT_BASE64
 BASE64 with BEGIN CERTIFICATE and END CERTIFICATE
CV_OUT_BASE64HEADER

BASE64 with BEGIN NEW CERTIFICATE REQUEST and END

CV_OUT_BASE64REQUESTHEADER NEW CERTIFICATE REQUEST

BASE64 with BEGIN X509 CRL and END X509 CRL

CV_OUT_BASE64X509CRLHEADER

Binary
CV_OUT_BINARY

Hexadecimal string
CV_OUT_HEX

Hexadecimal string with address/offset

CV_OUT_HEXADDR

Hexadecimal string with ASCII

CV_OUT_HEXASCII

Hexadecimal string with ASCII and address/offset

CV_OUT_HEXASCIIADDR

[out] pvarPropertyValue

A pointer to a buffer that receives the requested property value. It is a caller's responsibility to free this resource
when done by calling VariantClear.

Return value
C++
The return value is an HRESULT . A value of S_OK indicates the method was successful.
VB
The requested property value.

Remarks
The following values are returned when the property identifier is CR_PROP_BASECRLPUBLISHSTATUS or
CR_PROP_DELTACRLPUBLISHSTATUS. These values can be combined.

VA L UE DESC RIP T IO N

CPF_BADURL_ERROR A URL is not valid.

CPF_BASE A base CRL was published.

CPF_CASTORE_ERROR A CA store error prevented publication.

CPF_COMPLETE A complete CRL was published.

 CPF_DELTA A delta CRL was published.

CPF_FILE_ERROR A file error prevented publication.

CPF_FTP_ERROR An FTP error prevented publication.

CPF_HTTP_ERROR An HTTP error prevented publication.

CPF_LDAP_ERROR An LDAP error prevented publication.

CPF_MANUAL A CRL was published manually.

CPF_SHADOW An empty delta CRL was published, along with a new BASE
CRL.

CPF_SIGNATURE_ERROR A signature error prevented publication.

For an example of retrieving a CRL, see Retrieving a Certificate Revocation List.

Examples
The following example shows retrieving the signature certificate of the CA. The example assumes the
ICertAdmin2 interface pointer is valid.

BSTR bstrCA = NULL;

VARIANT var1;
HRESULT hr;

bstrCA = SysAllocString(L"<COMPUTERNAMEHERE>\\<CANAMEHERE>");
if (NULL == bstrCA)
{
printf("Failed to allocate memory for bstrCA\n");
exit(1);
}

VariantInit(&var1);
// Retrieve the CA signature certificate at index 0.
hr = pAdmin2->GetCAProperty(bstrCA,
CR_PROP_CASIGCERT,
0,
PROPTYPE_BINARY,
CV_OUT_BASE64HEADER,
&var1);
if (FAILED(hr))
{
printf("Failed GetCAProperty\n");
SysFreeString(bstrCA);
exit(1); // Or other error action.
}

// Use the property as needed.

// ...

// Clear the variant when finished.

VariantClear(&var1);
SysFreeString(bstrCA);

Requirements
Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header certadm.h (include Certsrv.h)

Librar y Certidl.lib

DLL Certadm.dll
 ICertAdmin2::GetCAPropertyDisplayName method
(certadm.h)
7/2/2022 • 2 minutes to read • Edit Online

The GetCAProper tyDisplayName method retrieves the property display name for a certification authority
(CA) property. This method was first defined in the ICertAdmin interface.

Syntax
HRESULT GetCAPropertyDisplayName(
[in] const BSTR strConfig,
[in] LONG PropId,
[out] BSTR *pstrDisplayName
);

Parameters
[in] strConfig

Represents a valid configuration string for the CA in the form COMPUTERNAME\CANAME, where
COMPUTERNAME is the Certificate Services server's network name, and CANAME is the common name of the
CA, as entered during Certificate Services setup. For information about the configuration string name, see
ICertConfig.

Impor tant GetCAProper tyDisplayName does not clear the internal cache when the configuration string is changed.
When you change the configuration string for the CA, you must instantiate a new ICertAdmin object and call this method
again with the new configuration string.

[in] PropId

Specifies the property identifier. For information about this parameter, see the table in
ICertAdmin2::GetCAProperty.
[out] pstrDisplayName

A pointer to the string representing the property's display name.

It is the responsibility of the caller to free the BSTR when done by calling SysFreeString.

Return value
C++
The return value is an HRESULT . A value of S_OK indicates the method was successful.
VB
A string that represents the property's display name.

Requirements
Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header certadm.h (include Certsrv.h)

Librar y Certidl.lib

DLL Certadm.dll
 ICertAdmin2::GetCAPropertyFlags method
(certadm.h)
7/2/2022 • 2 minutes to read • Edit Online

The GetCAProper tyFlags method retrieves the property flags for a certification authority (CA) property. This
method was first defined in the ICertAdmin interface.
The property flags can be examined to determine the data type and to determine whether the property is
indexed.

Syntax
HRESULT GetCAPropertyFlags(
[in] const BSTR strConfig,
[in] LONG PropId,
[out] LONG *pPropFlags
);

Parameters
[in] strConfig

Represents a valid configuration string for the CA in the form COMPUTERNAME\CANAME, where
COMPUTERNAME is the Certificate Services server's network name, and CANAME is the common name of the
CA, as entered during Certificate Services setup. For information about the configuration string name, see
ICer tConfig .

Impor tant GetCAProper tyFlags does not clear the internal cache when the configuration string is changed. When you
change the configuration string for the CA, you must instantiate a new ICertAdmin object and call this method again with the
new configuration string.

[in] PropId

Specifies the property identifier. For information about this parameter, see the table in
ICertAdmin2::GetCAProperty.
[out] pPropFlags

A pointer to a value that represents the property flags.

Return value
C++
The return value is an HRESULT . A value of S_OK indicates the method was successful.
VB
A Long representing the property flags.
Remarks
The LONG value retrieved by calling this method can be examined to determine the data type and the indexed
status. To determine the data type and indexed status, use the PROPTYPE_MASK and PROPFLAGS_INDEXED
values, respectively.
Examples
The following example assumes the ICertAdmin2 interface pointer is valid.

BSTR bstrCA = NULL;

LONG nFlags; // Variable to contain the property flags.

bstrCA = SysAllocString(L"<COMPUTERNAMEHERE>\\<CANAMEHERE>");
if (NULL == bstrCA)
{
printf("Failed to allocate memory for bstrCA\n");
exit(1);
}

// Retrieve a property's flags.

hr = pCertAdmin2->GetCAPropertyFlags(bstrCA,
CR_PROP_EXITCOUNT,
&nFlags);
if (FAILED(hr))
{
printf("Failed GetCAPropertyFlags\n");
SysFreeString(bstrCA);
exit(1); // Or other error action.
}
// Display the property data type.
switch (nFlags & PROPTYPE_MASK)
{
case PROPTYPE_BINARY:
printf("Type is BINARY\n");
break;
case PROPTYPE_DATE:
printf("Type is DATE\n");
break;
case PROPTYPE_LONG:
printf("Type is LONG\n");
break;
case PROPTYPE_STRING:
printf("Type is STRING\n");
break;
default:
printf("Unexpected data type.\n");
break;
}
// Display the property's indexed status.
printf("Property %s indexed\n",
nFlags & PROPFLAGS_INDEXED ? "is" : "is not");

SysFreeString(bstrCA);

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]
Target Platform Windows

Header certadm.h (include Certsrv.h)

Librar y Certidl.lib

DLL Certadm.dll
 ICertAdmin2::GetConfigEntry method (certadm.h)
7/2/2022 • 2 minutes to read • Edit Online

The GetConfigEntr y method retrieves configuration information for a certification authority (CA).

Syntax
HRESULT GetConfigEntry(
[in] const BSTR strConfig,
[in] const BSTR strNodePath,
[in] const BSTR strEntryName,
[out] VARIANT *pvarEntry
);

Parameters
[in] strConfig

String value that represents a valid configuration string for the CA in the form COMPUTERNAME\CANAME,
where COMPUTERNAME is the Certificate Services server's network name, and CANAME is the common name
of the CA, as entered during Certificate Services setup. For information about the configuration string name, see
ICertConfig. This parameter can be an empty string, in which case the function retrieves configuration
information that is not specific to a CA. This parameter cannot be NULL .

Impor tant GetConfigEntr y does not clear the internal cache when the configuration string is changed. When you change
the configuration string for the CA, you must instantiate a new ICertAdmin object and call this method again with the new
configuration string.

[in] strNodePath

String value that represents the node path for the configuration information. This parameter can be an empty
string, in which case the function retrieves configuration information from the path identified by strConfig. This
parameter cannot be NULL .
[in] strEntryName

String value that represents the name of the entry whose information is being retrieved. This value can be an
empty string, in which case all of the entry names are retrieved. This parameter cannot be NULL .
[out] pvarEntry

A pointer to a VARIANT that receives the requested information.

Return value
C++
If the function is successful, the return value is S_OK.
If the function fails, the return value is an HRESULT that indicates the error. For a list of common error codes,
see Common HRESULT Values.
VB
The return value is a Variant that represents the retrieved configuration information.

Remarks
The configuration information is stored in the registry under the following path.
HKEY_LOCAL_MACHINE \SYSTEM \CurrentControlSet \Ser vices \Cer tSvc \Configuration \
[CASANITIZEDNAME]\[strNodePath]\[strEntryName]
Where CASANITIZEDNAME is the sanitized name for the CA. For more information about sanitized names, see
ICertConfig2::GetConfig.

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header certadm.h (include Certsrv.h)

Librar y Certidl.lib

DLL Certadm.dll

See also
ICertAdmin2
 ICertAdmin2::GetMyRoles method (certadm.h)
7/2/2022 • 2 minutes to read • Edit Online

The GetMyRoles method retrieves the certification authority (CA) roles of the caller.

Syntax
HRESULT GetMyRoles(
[in] const BSTR strConfig,
[out] LONG *pRoles
);

Parameters
[in] strConfig

String value that represents a valid configuration string for the CA in the form COMPUTERNAME\CANAME,
where COMPUTERNAME is the Certificate Services server's network name, and CANAME is the common name
of the CA, as entered during Certificate Services setup. For information about the configuration string name, see
ICertConfig.

Impor tant GetMyRoles does not clear the internal cache when the configuration string is changed. When you change the
configuration string for the CA, you must instantiate a new ICertAdmin object and call this method again with the new
configuration string.

[out] pRoles

A pointer to a LONG value that represents the retrieved CA roles for the caller. This can be a bitwise
combination of zero or more of the following values.

VA L UE M EA N IN G

Caller has CA administrator capability.

CA_ACCESS_ADMIN
0x1

Caller has CA auditor capability.

CA_ACCESS_AUDITOR
0x4

Caller has enrollment access.

CA_ACCESS_ENROLL
0x200

Caller has CA officer capability.

CA_ACCESS_OFFICER
0x2
 Caller has CA backup capability.
CA_ACCESS_OPERATOR
0x8

Caller has CA read access.

CA_ACCESS_READ
0x100

Return value
C++
If the function is successful, the return value is S_OK.
If the function fails, the return value is an HRESULT that indicates the error. For a list of common error codes,
see Common HRESULT Values.
VB
The return value is a Long value that represents the retrieved CA roles for the caller. This can be a bitwise
combination of zero or more of the following values.

RET URN C O DE/ VA L UE DESC RIP T IO N

Caller has CA administrator capability.

CA_ACCESS_ADMIN
0x1

Caller has CA auditor capability.

CA_ACCESS_AUDITOR
0x4

Caller has enrollment access.

CA_ACCESS_ENROLL
0x200

Caller has CA officer capability.

CA_ACCESS_OFFICER
0x2

Caller has CA backup capability.

CA_ACCESS_OPERATOR
0x8

Caller has read access.

CA_ACCESS_READ
0x100

Requirements

Minimum suppor ted client None supported

 Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header certadm.h (include Certsrv.h)

Librar y Certidl.lib

DLL Certadm.dll

See also
ICertAdmin2
 ICertAdmin2::ImportKey method (certadm.h)
7/2/2022 • 2 minutes to read • Edit Online

The Impor tKey method adds an encrypted key set to an item in the Certificate Services database. The key set is
encrypted to one or several key recovery agent (KRA) certificates.

Syntax
HRESULT ImportKey(
[in] const BSTR strConfig,
[in] LONG RequestId,
[in] const BSTR strCertHash,
[in] LONG Flags,
[in] const BSTR strKey
);

Parameters
[in] strConfig

String value that represents a valid configuration string for the certification authority (CA) in the form
COMPUTERNAME\CANAME, where COMPUTERNAME is the Certificate Services server's network name, and
CANAME is the common name of the CA, as entered during Certificate Services setup. For information about
the configuration string name, see ICertConfig.

Impor tant Impor tKey does not clear the internal cache when the configuration string is changed. When you change the
configuration string for the CA, you must instantiate a new ICertAdmin object and call this method again with the new
configuration string.

[in] RequestId

LONG value that represents the certificate request ID in the Certificates Services database. If the serial number
(passed in as strCertHash) is to be used instead of the request ID, use zero for this value.
[in] strCertHash

String value that represents the certificate hash. For strCertHash to be used, you must specify a value of zero for
RequestId.
[in] Flags

Specifies the format of the key. This parameter can be one of the following values.

VA L UE M EA N IN G

BASE64 format with begin or end.

CR_IN_BASE64HEADER

BASE64 format without begin or end.

CR_IN_BASE64
 Binary format.
CR_IN_BINARY

Additionally, the following value can be combined with the format value by using a bitwise-OR operation.

VA L UE M EA N IN G

Any existing KRA encoded information is overwritten.

IKF_OVERWRITE

[in] strKey

String value that represents the KRA key information.

Return value
None

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header certadm.h (include Certsrv.h)

Librar y Certidl.lib

DLL Certadm.dll

See also
ICertAdmin2
 ICertAdmin2::PublishCRLs method (certadm.h)
7/2/2022 • 2 minutes to read • Edit Online

The PublishCRLs method publishes certificate revocation lists (CRLs) for a certification authority (CA). This
method was first defined in the ICertAdmin interface.
The PublishCRLs method publishes a CRL based on the CA's current certificate, as well as CRLs based on any
CA certificates that have been renewed and are not yet expired.

Syntax
HRESULT PublishCRLs(
[in] const BSTR strConfig,
[in] DATE Date,
[in] LONG CRLFlags
);

Parameters
[in] strConfig

Represents a valid configuration string for the CA in the form COMPUTERNAME\CANAME, where
COMPUTERNAME is the Certificate Services server's network name, and CANAME is the common name of the
certification authority, as entered during Certificate Services setup. For information about the configuration
string name, see ICertConfig.

Impor tant PublishCRLs does not clear the internal cache when the configuration string is changed. When you change the
configuration string for the CA, you must instantiate a new ICertAdmin object and call this method again with the new
configuration string.

[in] Date

Specifies the next update value of the CRL in GMT time. If Date is nonzero, the next update value for the CRL is
Date, subject to rounding or ceiling limits enforced by Certificate Services. If Date is zero, the next update value
of the CRL is calculated from the default CRL publication period.
[in] CRLFlags

Value that specifies the CRL publishing options. This value can be a bitwise combination of the following flags.

VA L UE M EA N IN G

A base CRL is published, or the most recent base CRL is

CA_CRL_BASE republished if CA_CRL_REPUBLISH is set.

A delta CRL is published, or the most recent delta CRL is

CA_CRL_DELTA republished if CA_CRL_REPUBLISH is set. Note that if the CA
has not enabled delta CRL publishing, use of this flag will
result in an error.
 The most recent base or delta CRL, as specified by
CA_CRL_REPUBLISH CA_CRL_BASE or CA_CRL_DELTA, is republished. The CA will
not republish a CRL to a CRL distribution point if the CRL at
the distribution point is already the most recent CRL.

Return value
None

Remarks
To determine whether a CA has successfully published base and delta CRLs, call ICertAdmin2::GetCAProperty
with the CR_PROP_BASECRLPUBLISHSTATUS and CR_PROP_DELTACRLPUBLISHSTATUS property identifiers,
respectively.
Examples
The following example shows publishing CRLs.
 DATE ExpDate; // CRL expiration date.
SYSTEMTIME st;
BSTR bstrCA = NULL;

// Set the CRL expiration date to noon, July 1, 2001.

// Zero out values first (avoids setting minutes,
// seconds, and so on).
memset(&st, 0, sizeof(SYSTEMTIME));
st.wYear = 2001;
st.wMonth = 7; // July
st.wDay = 1; // first day of month
st.wHour = 12; // noon

// Place the date in required format.

if (!SystemTimeToVariantTime(&st, &ExpDate))
{
printf("Unable to convert time\n");
goto error;
}

bstrCA = SysAllocString(L"<COMPUTERNAMEHERE>\\<CANAMEHERE>");
if (NULL == bstrCA)
{
printf("Memory allocation failed\n");
goto error;
}

// Publish the CRL.

// pCertAdmin is a previously instantiated ICertAdmin object.
hr = pCertAdmin2->PublishCRLs(bstrCA,
ExpDate,
CA_CRL_BASE);
if (FAILED(hr))
{
printf("Failed PublishCRLs [%x]\n", hr);
goto error;
}
else
printf("PublishCRLs succeeded\n");
// Done.

error:

// Free resources.
if (bstrCA)
SysFreeString(bstrCA);

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header certadm.h (include Certsrv.h)

Librar y Certidl.lib
DLL Certadm.dll
 ICertAdmin2::SetCAProperty method (certadm.h)
7/2/2022 • 2 minutes to read • Edit Online

The SetCAProper ty method sets a property value for the certification authority (CA).

Syntax
HRESULT SetCAProperty(
[in] const BSTR strConfig,
[in] LONG PropId,
[in] LONG PropIndex,
[in] LONG PropType,
[in] VARIANT *pvarPropertyValue
);

Parameters
[in] strConfig

String value that represents a valid configuration string for the CA in the form COMPUTERNAME\CANAME,
where COMPUTERNAME is the Certificate Services server's network name, and CANAME is the common name
of the CA, as entered during Certificate Services setup. For information about the configuration string name, see
ICertConfig.

Impor tant SetCAProper ty does not clear the internal cache when the configuration string is changed. When you change
the configuration string for the CA, you must instantiate a new ICertAdmin object and call this method again with the new
configuration string.

[in] PropId

Specifies one of the following property identifiers.

For information about all CA properties, including those that are read-only, see ICertAdmin2::GetCAProperty.

VA L UE M EA N IN G

The CA's key recovery agent (KRA) certificate.

CR_PROP_KRACERT
Data format: binary, indexed.

Number of KRA certificates for the CA.

CR_PROP_KRACERTCOUNT
Data format: Long .

Number of KRA certificates used by the CA.

CR_PROP_KRACERTUSEDCOUNT
Data format: Long .

Value that specifies whether role separation is enabled.

CR_PROP_ROLESEPARATIONENABLED
Data format: Long .
 List of templates supported by the CA.
CR_PROP_TEMPL ATES
Data format: String .

[in] PropIndex

If the PropId parameter is indexed, the zero-based index to use when retrieving the property value. If PropId is
not indexed, this value is ignored.
[in] PropType

Specifies the type of the property. This parameter can be one of the following values.

VA L UE M EA N IN G

Signed Long data.

PROPTYPE_LONG

Date/Time (reserved for future use).

PROPTYPE_DATE

Binary data.
PROPTYPE_BINARY

Unicode String data.

PROPTYPE_STRING

[in] pvarPropertyValue

C++ A pointer to a VARIANT that specifies the property value.

VB A Variant that specifies the property value.

Return value
VB
If the function is successful, the return value is S_OK.
If the function fails, the return value is an HRESULT that indicates the error. For a list of common error codes,
see Common HRESULT Values.

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header certadm.h (include Certsrv.h)

 Librar y Certidl.lib

DLL Certadm.dll

See also
ICertAdmin2
ICertAdmin2::GetCAProperty
 ICertAdmin2::SetConfigEntry method (certadm.h)
7/2/2022 • 2 minutes to read • Edit Online

The SetConfigEntr y method sets configuration information for a certification authority (CA).

Syntax
HRESULT SetConfigEntry(
[in] const BSTR strConfig,
[in] const BSTR strNodePath,
[in] const BSTR strEntryName,
[in] VARIANT *pvarEntry
);

Parameters
[in] strConfig

String value that represents a valid configuration string for the CA in the form COMPUTERNAME\CANAME,
where COMPUTERNAME is the Certificate Services server's network name, and CANAME is the common name
of the CA, as entered during Certificate Services setup. For information about the configuration string name, see
ICertConfig. This parameter can be an empty string, in which case the function sets configuration information
that is not specific to a CA. This parameter cannot be NULL .

Impor tant SetConfigEntr y does not clear the internal cache when the configuration string is changed. When you change
the configuration string for the CA, you must instantiate a new ICertAdmin object and call this method again with the new
configuration string.

[in] strNodePath

String value that represents the node path for the configuration information. This parameter can be an empty
string, in which case the function retrieves configuration information from the path identified by strConfig. This
parameter cannot be NULL .
[in] strEntryName

String value that represents the name of the entry whose information is being set. This value can be an empty
string, in which case the default entry is the entry being set. This parameter cannot be NULL .
[in] pvarEntry

C++ Pointer to VARIANT that specifies the information to set. If

this value is empty, then the indicated key will be deleted.

VB Variant that specifies the information to set. If this value is

empty, then the indicated key will be deleted.

Return value
VB
If the function is successful, the return value is S_OK.
If the function fails, the return value is an HRESULT that indicates the error. For a list of common error codes,
see Common HRESULT Values.

Remarks
The configuration information is stored in the registry under the following path.
HKEY_LOCAL_MACHINE \SYSTEM \CurrentControlSet \Ser vices \Cer tSvc \Configuration \
[CASANITIZEDNAME]\[strNodePath]\[strEntryName]
Where CASANITIZEDNAME is the sanitized name for the CA. For more information about sanitized names, see
ICertConfig2::GetConfig.

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header certadm.h (include Certsrv.h)

Librar y Certidl.lib

DLL Certadm.dll

See also
ICertAdmin2
 IOCSPAdmin interface (certadm.h)
7/2/2022 • 2 minutes to read • Edit Online

The IOCSPAdmin interface provides functionality to manage an Online Certificate Status Protocol (OCSP)
responder server. Implement this interface to manage individual responder server properties and certification
authority (CA) definitions. After creating an instance of this interface, you call GetConfiguration to connect to a
responder service and initialize an OCSPAdmin object. Each OCSPAdmin object corresponds to one physical
responder server.

Note This interface does not include functionality to create or parse certificate status requests.

In C++, you create an instance of this interface by calling the CoCreateInstance function with the
CLSID_OCSPAdmin class identifier.
In Visual Basic Scripting Edition, you create an instance of the OCSPAdmin object.

Inheritance
The IOCSPAdmin interface inherits from the IDispatch interface. IOCSPAdmin also has these types of
members:

Methods
The IOCSPAdmin interface has these methods.

IOCSPAdmin::get_OCSPCAConfigurationCollection

Gets an instance of an OCSPCAConfigurationCollection object. This object represents the set of certification authority (CA)
certificates for which an Online Certificate Status Protocol (OCSP) responder service can handle status requests.

IOCSPAdmin::get_OCSPServiceProperties

Gets an instance of an OCSPPropertyCollection object. This object represents the attributes of an Online Certificate Status
Protocol (OCSP) responder service.

IOCSPAdmin::GetConfiguration

Connects to an Online Certificate Status Protocol (OCSP) responder server and initializes an OCSPAdmin object with the
configuration information from the server.

IOCSPAdmin::GetHashAlgorithms

Gets a list of hash-algorithm names. The Online Certificate Status Protocol (OCSP) responder server uses these names to sign
OCSP responses for a given certification authority (CA) configuration.

IOCSPAdmin::GetMyRoles

Gets the access mask of privilege roles for a user on a given Online Certificate Status Protocol (OCSP) responder server.
 IOCSPAdmin::GetSecurity

Gets security descriptor information for an Online Certificate Status Protocol (OCSP) responder server.

IOCSPAdmin::GetSigningCertificates

Gets the signing certificates that are available on a responder server for a given certification authority (CA) certificate.

IOCSPAdmin::Ping

Tests a DCOM connection with an Online Certificate Status Protocol (OCSP) responder service.

IOCSPAdmin::SetConfiguration

Updates a responder service with configuration changes.

IOCSPAdmin::SetSecurity

Updates security descriptor information for an Online Certificate Status Protocol (OCSP) responder server.

Remarks
The following table disambiguates the various properties used in the Microsoft OCSP architecture.

A RC H IT EC T URE SC O P E IN F O RM AT IO N T Y P ES

OCSPServiceProperties Governs general responder-service Proxy

behavior for every CA. Audit
Security configurations

OCSPCAConfigurationCollection Governs response behavior for a CA

specific CA. Hash algorithm
Certificate signing
Revocation provider
configurations

ProviderProperties Governs behavior of a revocation Certificate revocation lists

information provider that is specific to (CRLs)
a particular OCSPCAConfiguration. Refresh interval

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2008 Datacenter, Windows Server 2008
Enterprise [desktop apps only]

Target Platform Windows

 Header certadm.h

See also
IDispatch
 IOCSPAdmin::get_OCSPCAConfigurationCollection
method (certadm.h)
7/2/2022 • 2 minutes to read • Edit Online

The OCSPCAConfigurationCollection property gets an instance of an OCSPCAConfigurationCollection

object. This object represents the set of certification authority (CA) certificates for which an Online Certificate
Status Protocol (OCSP) responder service can handle status requests.
This property is read-only.

Syntax
HRESULT get_OCSPCAConfigurationCollection(
IOCSPCAConfigurationCollection **pVal
);

Parameters
pVal

Return value
None

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2008 Datacenter, Windows Server 2008
Enterprise [desktop apps only]

Target Platform Windows

Header certadm.h (include Certsrv.h)

Librar y Certadm.lib

DLL Certadm.dll

See also
IOCSPAdmin
 IOCSPAdmin::get_OCSPServiceProperties method
(certadm.h)
7/2/2022 • 2 minutes to read • Edit Online

The OCSPSer viceProper ties property gets an instance of an OCSPPropertyCollection object. This object
represents the attributes of an Online Certificate Status Protocol (OCSP) responder service. After instantiating an
OCSPAdmin object, a script or administration tool can use the retrieved IOCSPPropertyCollection interface to
expose responder-service attributes.
This property is read-only.

Syntax
HRESULT get_OCSPServiceProperties(
IOCSPPropertyCollection **ppVal
);

Parameters
ppVal

Return value
None

Remarks
The following table lists the possible Name-Value pairs for OCSP service properties.

NAME VA L UE

LogLevel The Value of LogLevel must be one of the following

constants.
Constant: CERTLOG_MINIMAL
DWORD : 0
Constant: CERTLOG_TERSE
DWORD : 1
Constant: CERTLOG_ERROR
DWORD : 2
Constant: CERTLOG_WARNING
DWORD : 3 (default)
Constant: CERTLOG_VERBOSE
DWORD : 4
Constant: CERTLOG_EXHAUSTIVE
DWORD : 5
 AuditFilter The Value of AuditFilter can be any bitwise combination of
the following DWORD values.
Description: Audit OCSP service start/stop
DWORD : 0x1
Description: Changes to the OCSP configuration
DWORD : 0x2
Description: Requests submitted to the OCSP
DWORD : 0x4
Description: Changes to the OCSP security settings
DWORD : 0x8

ArrayController The Value of ArrayController must be a string that

represents the computer name of the OCSP server that acts
as the array controller for an OCSP array configuration.

ArrayMembers The Value of ArrayMembers can be a multiple-line string

that represents the computer names of the OCSP servers
that are part of an OCSP array configuration.

EnrollPollInter val The Value of EnrollPollInter val must be a DWORD value

from 0 to 24 that represents the number of hours between
OCSP service certificate enrollment attempts. This interval
determines how often the service checks the status of target
certificates for a template change or pending validity change.
When the service finds a change, it attempts to enroll for a
new certificate.

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2008 Datacenter, Windows Server 2008
Enterprise [desktop apps only]

Target Platform Windows

Header certadm.h (include Certsrv.h)

Librar y Certadm.lib

DLL Certadm.dll

See also
IOCSPAdmin
 IOCSPAdmin::GetConfiguration method (certadm.h)
7/2/2022 • 2 minutes to read • Edit Online

The GetConfiguration method connects to an Online Certificate Status Protocol (OCSP) responder server and
initializes an OCSPAdmin object with the configuration information from the server.

Syntax
HRESULT GetConfiguration(
[in] const BSTR bstrServerName,
[in] VARIANT_BOOL bForce
);

Parameters
[in] bstrServerName

A string that contains the responder-server name.

[in] bForce

C++ VARIANT_TRUE if the caller wants to read the responder

configuration from the server's registry when a running
instance of the OCSP responder service cannot be found;
otherwise, VARIANT_FALSE .

VB True if the caller wants to read the responder configuration

from the server's registry when a running instance of the
OCSP responder service cannot be found; otherwise, False .

Return value
VB
If the method succeeds, it returns S_OK .
If the method fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.
If the method returns HRESULT_FROM_WIN32(ERROR_INVALID_STATE) , the configuration is already
initialized.
If the method returns E_INVALIDARG , the pVal parameter was set to NULL .

Remarks
The following table lists the effects of the bForce parameter value on the method call.

O C SP RESP O N DER SERVIC E O N T H E B FO RC E IS VA RIA N T _T RUE B FO RC E IS VA RIA N T _FA L SE

TA RGET SERVER

Running Retrieve configuration from the service. Retrieve configuration from the service.
 Stopped Attempt to retrieve configuration from Return an error.
the server registry. If this attempt fails,
return an error.

The following table lists the effects of the bForce parameter value on the method call.

O C SP RESP O N DER SERVIC E O N T H E B FO RC E IS T RUE B FO RC E IS FA L SE

TA RGET SERVER

Running Retrieve configuration from the service. Retrieve configuration from the service.

Stopped Attempt to retrieve configuration from Return an error.

the server registry. If this attempt fails,
return an error.

This method attempts to read the configuration from a running instance of an OCSP responder service, but that
might not be possible if the service is not running or is in an inaccessible state. The caller can instruct the
method to read the configuration from the server's registry if a running instance cannot be found.
The method fails if you try to call it more than once for a given OCSPAdmin object. Each instance of
OCSPAdmin corresponds to one responder server. To connect to another server in an array of OCSP responder
servers, create a new instance of an OCSPAdmin object.

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2008 Datacenter, Windows Server 2008
Enterprise [desktop apps only]

Target Platform Windows

Header certadm.h (include Certsrv.h)

Librar y Certadm.lib

DLL Certadm.dll

See also
IOCSPAdmin
 IOCSPAdmin::GetHashAlgorithms method
(certadm.h)
7/2/2022 • 2 minutes to read • Edit Online

The GetHashAlgorithms method gets a list of hash-algorithm names. The Online Certificate Status Protocol
(OCSP) responder server uses these names to sign OCSP responses for a given certification authority (CA)
configuration.

Syntax
HRESULT GetHashAlgorithms(
[in] const BSTR bstrServerName,
[in] const BSTR bstrCAId,
[out] VARIANT *pVal
);

Parameters
[in] bstrServerName

A string that contains the responder-server name.

[in] bstrCAId

A string that contains an OCSPCAConfiguration Identifier.

[out] pVal

The list of hash algorithms with which a responder server can sign responses.

Return value
C++
If the method succeeds, it returns S_OK .
If the method fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.
VB
A list of hash algorithms with which a responder server can sign responses.

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2008 Datacenter, Windows Server 2008
Enterprise [desktop apps only]
 Target Platform Windows

Header certadm.h (include Certsrv.h)

Librar y Certadm.lib

DLL Certadm.dll

See also
IOCSPAdmin
 IOCSPAdmin::GetMyRoles method (certadm.h)
7/2/2022 • 2 minutes to read • Edit Online

The GetMyRoles method gets the access mask of privilege roles for a user on a given Online Certificate Status
Protocol (OCSP) responder server.

Syntax
HRESULT GetMyRoles(
[in] const BSTR bstrServerName,
[out] LONG *pRoles
);

Parameters
[in] bstrServerName

A string that contains the responder-server name.

[out] pRoles

A pointer to the 32-bit access mask.

Return value
C++
If the method succeeds, it returns S_OK .
If the method fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.
VB
The 32-bit access mask.

Remarks
The OCSP responder server defines the following masks for access privilege roles.

C O N STA N T C ++ VA L UE VB SC RIP T VA L UE DESC RIP T IO N

CA_ACCESS_ADMIN 0x001 &H1 CA administrator

CA_ACCESS_READ 0x100 &H100 Read-only access to a CA

CA_ACCESS_ENROLL 0x200 &H200 Enroll access to a CA

Examples of privileges a user might have, depending on the mask:

Configure and upgrade an OCSP server.
Assign existing signing certificate and key.
 Install and update Certificate Revocation Lists (CRLs).
Configure a response format.

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2008 Datacenter, Windows Server 2008
Enterprise [desktop apps only]

Target Platform Windows

Header certadm.h (include Certsrv.h)

Librar y Certadm.lib

DLL Certadm.dll

See also
IOCSPAdmin
 IOCSPAdmin::GetSecurity method (certadm.h)
7/2/2022 • 2 minutes to read • Edit Online

The GetSecurity method gets security descriptor information for an Online Certificate Status Protocol (OCSP)
responder server.

Syntax
HRESULT GetSecurity(
[in] const BSTR bstrServerName,
[out] BSTR *pVal
);

Parameters
[in] bstrServerName

A string that contains the responder-server name.

[out] pVal

Return value
C++
If the method succeeds, it returns S_OK .
If the method fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.
VB
The security descriptor information.

Remarks
This method calls the ConvertSecurityDescriptorToStringSecurityDescriptor function to create a string value in
Security Descriptor String Format.

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2008 Datacenter, Windows Server 2008
Enterprise [desktop apps only]

Target Platform Windows

Header certadm.h (include Certsrv.h)

 Librar y Certadm.lib

DLL Certadm.dll

See also
IOCSPAdmin
 IOCSPAdmin::GetSigningCertificates method
(certadm.h)
7/2/2022 • 2 minutes to read • Edit Online

The GetSigningCer tificates method gets the signing certificates that are available on a responder server for a
given certification authority (CA) certificate. This method only returns signing certificates from the
CERT_SYSTEM_STORE_LOCAL_MACHINE system store for the specified server.

Syntax
HRESULT GetSigningCertificates(
[in] const BSTR bstrServerName,
[in] const VARIANT *pCACertVar,
[out] VARIANT *pVal
);

Parameters
[in] bstrServerName

A string that contains the responder-server name.

[in] pCACertVar

The CA certificate for which to retrieve signing certificates.

[out] pVal

Return value
C++
If the method succeeds, it returns S_OK .
If the method fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.
VB
The available signing certificates.

Remarks
Each signing certificate has the following properties:
Signed by the CA specified by the pCACertVar parameter
Includes the Online Certificate Status Protocol (OCSP) signing (XCN_OID_PKIX_KP_OCSP_SIGNING )
extension
Has not expired
Responder server can access the certificate private key

Requirements
 Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2008 Datacenter, Windows Server 2008
Enterprise [desktop apps only]

Target Platform Windows

Header certadm.h (include Certsrv.h)

Librar y Certadm.lib

DLL Certadm.dll

See also
IOCSPAdmin
 IOCSPAdmin::Ping method (certadm.h)
7/2/2022 • 2 minutes to read • Edit Online

The Ping method tests a DCOM connection with an Online Certificate Status Protocol (OCSP) responder service.

Syntax
HRESULT Ping(
[in] const BSTR bstrServerName
);

Parameters
[in] bstrServerName

A string that contains the OCSP responder server name.

Return value
None

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2008 Datacenter, Windows Server 2008
Enterprise [desktop apps only]

Target Platform Windows

Header certadm.h (include Certsrv.h)

Librar y Certadm.lib

DLL Certadm.dll

See also
IOCSPAdmin
 IOCSPAdmin::SetConfiguration method (certadm.h)
7/2/2022 • 2 minutes to read • Edit Online

The SetConfiguration method updates a responder service with configuration changes.

Syntax
HRESULT SetConfiguration(
[in] const BSTR bstrServerName,
[in] VARIANT_BOOL bForce
);

Parameters
[in] bstrServerName

A string that contains the responder-service name.

[in] bForce

C++ VARIANT_TRUE if the method should update the

responder service registry when the service is offline or
unavailable; otherwise, VARIANT_FALSE . If the service is
offline or unavailable and the bForce parameter is
VARIANT_TRUE , SetConfiguration updates the
responder service registry directly.

VB True if the method should update the responder service

registry when the service is offline or unavailable; otherwise,
False . If the service is offline or unavailable and the bForce
parameter is True , SetConfiguration updates the
responder service registry directly.

Return value
VB
If the method succeeds, it returns S_OK .
If the method fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.

Remarks
The following table lists the effects of the bForce parameter value on the method call.

O C SP RESP O N DER SERVIC E O N T H E B FO RC E IS VA RIA N T _T RUE B FO RC E IS VA RIA N T _FA L SE

TA RGET SERVER

Running Retrieve configuration from the service. Retrieve configuration from the service.
 Stopped Attempt to retrieve configuration from Return an error.
the server registry. If this attempt fails,
return an error.

The following table lists the effects of the bForce parameter value on the method call.

O C SP RESP O N DER SERVIC E O N T H E B FO RC E IS T RUE B FO RC E IS FA L SE

TA RGET SERVER

Running Retrieve configuration from the service. Retrieve configuration from the service.

Stopped Attempt to retrieve configuration from Return an error.

the server registry. If this attempt fails,
return an error.

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2008 Datacenter, Windows Server 2008
Enterprise [desktop apps only]

Target Platform Windows

Header certadm.h (include Certsrv.h)

Librar y Certadm.lib

DLL Certadm.dll

See also
IOCSPAdmin
 IOCSPAdmin::SetSecurity method (certadm.h)
7/2/2022 • 2 minutes to read • Edit Online

The SetSecurity method updates security descriptor information for an Online Certificate Status Protocol
(OCSP) responder server.

Syntax
HRESULT SetSecurity(
[in] const BSTR bstrServerName,
[in] const BSTR bstrVal
);

Parameters
[in] bstrServerName

A string that contains the responder-server name.

[in] bstrVal

A string that contains the security descriptor information to assign to the responder server.

Return value
None

Remarks
This method calls the ConvertStringSecurityDescriptorToSecurityDescriptor function to create a security
descriptor from a string in Security Descriptor String Format.

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2008 Datacenter, Windows Server 2008
Enterprise [desktop apps only]

Target Platform Windows

Header certadm.h (include Certsrv.h)

Librar y Certadm.lib

DLL Certadm.dll
See also
IOCSPAdmin
 IOCSPCAConfiguration interface (certadm.h)
7/2/2022 • 2 minutes to read • Edit Online

The IOCSPCAConfiguration interface represents a set of definitions that enable an Online Certificate Status
Protocol (OCSP) service to respond to a certificate status request for a specific certification authority (CA).
Microsoft provides a default implementation of this interface in the OCSPCAConfiguration class. An
OCSPCAConfiguration object cannot be created externally. An OCSPCAConfiguration object can only be
created by using the CreateCAConfiguration method.
The default implementations of IOCSPAdmin and IOCSPCAConfigurationCollection methods create a
OCSPCAConfiguration object and use its properties.

Inheritance
The IOCSPCAConfiguration interface inherits from the IDispatch interface.

Methods
The IOCSPCAConfiguration interface has these methods.

IOCSPCAConfiguration::get_CACertificate

Gets an X.509 certificate that has been encoded by using Distinguished Encoding Rules (DER) and that is for a certification
authority (CA).

IOCSPCAConfiguration::get_CAConfig

Gets or sets a certification authority (CA) name with which a signing certificate must be signed.

IOCSPCAConfiguration::get_CSPName

Gets a cryptographic service provider (CSP) or key storage provider (KSP) name.

IOCSPCAConfiguration::get_ErrorCode

Gets a code that identifies an error condition in a CA configuration.

IOCSPCAConfiguration::get_HashAlgorithm

Gets or sets an identifier for the hash algorithm used to sign a certificate.

IOCSPCAConfiguration::get_Identifier

Gets a name for the certification authority (CA) configuration.

IOCSPCAConfiguration::get_KeySpec

Gets a value that indicates whether the key bound to the configuration is used for encryption or for signing content.
IOCSPCAConfiguration::get_LocalRevocationInformation

Gets or sets the certificate revocation list (CRL) of the local machine.

IOCSPCAConfiguration::get_Modified

Gets a value that indicates whether an OCSPCAConfiguration object has been modified since it was created.

IOCSPCAConfiguration::get_ProviderCLSID

Gets or sets the CLSID of the revocation information provider used by the CA configuration.

IOCSPCAConfiguration::get_ProviderProperties

Gets or sets information that provides certificate status responses.

IOCSPCAConfiguration::get_ReminderDuration

Gets or sets the percentage of a signing certificate lifetime after which a warning event is logged.

IOCSPCAConfiguration::get_SigningCertificate

Gets or sets a signing certificate that has been encoded by using Distinguished Encoding Rules (DER). An Online Certificate
Status Protocol (OCSP) responder service uses this certificate to sign its responses to certificate status requests.

IOCSPCAConfiguration::get_SigningCertificateTemplate

Gets or sets the template name for a signing certificate.

IOCSPCAConfiguration::get_SigningFlags

Gets or sets a combination of flag values. These values specify the management of signing certificates that belong to a
certification authority (CA) configuration.

IOCSPCAConfiguration::put_CAConfig

Gets or sets a certification authority (CA) name with which a signing certificate must be signed.

IOCSPCAConfiguration::put_HashAlgorithm

Gets or sets an identifier for the hash algorithm used to sign a certificate.

IOCSPCAConfiguration::put_LocalRevocationInformation

Gets or sets the certificate revocation list (CRL) of the local machine.

IOCSPCAConfiguration::put_ProviderCLSID

Gets or sets the CLSID of the revocation information provider used by the CA configuration.

IOCSPCAConfiguration::put_ProviderProperties

Gets or sets information that provides certificate status responses.

 IOCSPCAConfiguration::put_ReminderDuration

Gets or sets the percentage of a signing certificate lifetime after which a warning event is logged.

IOCSPCAConfiguration::put_SigningCertificate

Gets or sets a signing certificate that has been encoded by using Distinguished Encoding Rules (DER). An Online Certificate
Status Protocol (OCSP) responder service uses this certificate to sign its responses to certificate status requests.

IOCSPCAConfiguration::put_SigningCertificateTemplate

Gets or sets the template name for a signing certificate.

IOCSPCAConfiguration::put_SigningFlags

Gets or sets a combination of flag values. These values specify the management of signing certificates that belong to a
certification authority (CA) configuration.

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2008 Datacenter, Windows Server 2008
Enterprise [desktop apps only]

Target Platform Windows

Header certadm.h (include Certserv.h)

See also
IDispatch
 IOCSPCAConfiguration::get_CACertificate method
(certadm.h)
7/2/2022 • 2 minutes to read • Edit Online

The CACer tificate property gets an X.509 certificate that has been encoded by using Distinguished Encoding
Rules (DER) and that is for a certification authority (CA). The default implementations of IOCSPAdmin and
IOCSPCAConfigurationCollection methods set this value.
This property is read-only.

Syntax
HRESULT get_CACertificate(
VARIANT *pVal
);

Parameters
pVal

Return value
None

Remarks
The pVal certificate corresponds to the certificate used in the varCACert parameter of the
CreateCAConfiguration method to create the configuration.

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2008 Datacenter, Windows Server 2008
Enterprise [desktop apps only]

Target Platform Windows

Header certadm.h (include Certserv.h)

Librar y Certadm.lib

DLL Certadm.dll

See also
IOCSPCAConfiguration
 IOCSPCAConfiguration::get_CAConfig method
(certadm.h)
7/2/2022 • 2 minutes to read • Edit Online

The CAConfig property gets or sets a certification authority (CA) name with which a signing certificate must be
signed.
The CAConfig property contains a CA name. This name lets an Online Certificate Status Protocol (OCSP)
signing-certificate renewal request specify the issuing CA. The new signing certificate must be signed with this
CA.
This property supports responses to status requests for a certificate that has been replaced but is still valid.
This property is read/write.

Syntax
HRESULT get_CAConfig(
BSTR *pVal
);

Parameters
pVal

Return value
None

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2008 Datacenter, Windows Server 2008
Enterprise [desktop apps only]

Target Platform Windows

Header certadm.h (include Certserv.h)

Librar y Certadm.lib

DLL Certadm.dll

See also
IOCSPCAConfiguration
 IOCSPCAConfiguration::get_CSPName method
(certadm.h)
7/2/2022 • 2 minutes to read • Edit Online

The CSPName property gets a cryptographic service provider (CSP) or key storage provider (KSP) name. The
default implementations of IOCSPAdmin and IOCSPCAConfigurationCollection set this value.
This property is read-only.

Syntax
HRESULT get_CSPName(
BSTR *pVal
);

Parameters
pVal

Return value
None

Remarks
The name returned in pVal corresponds to the CSP or KSP used for the SigningCertificate property.

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2008 Datacenter, Windows Server 2008
Enterprise [desktop apps only]

Target Platform Windows

Header certadm.h (include Certserv.h)

Librar y Certadm.lib

DLL Certadm.dll

See also
IOCSPCAConfiguration
 IOCSPCAConfiguration::get_ErrorCode method
(certadm.h)
7/2/2022 • 2 minutes to read • Edit Online

The ErrorCode property gets a code that identifies an error condition in a CA configuration. The default
implementations of IOCSPAdmin and IOCSPCAConfigurationCollection set the initial error-condition value.
This property is read-only.

Syntax
HRESULT get_ErrorCode(
ULONG *pVal
);

Parameters
pVal

Return value
None

Remarks
The OCSP responder service returns an error code when it encounters a problem with a configuration. For the
definition of a returned code, see Winerror.h in the Microsoft Windows Software Development Kit (SDK).
An OCSPCAConfiguration object internally stores the error code as an HRESULT with an initial value of
E_PENDING . When IOCSPAdmin::SetConfiguration is called, the error code is reset to E_PENDING .

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2008 Datacenter, Windows Server 2008
Enterprise [desktop apps only]

Target Platform Windows

Header certadm.h (include Certserv.h)

Librar y Certadm.lib

DLL Certadm.dll
See also
IOCSPCAConfiguration
 IOCSPCAConfiguration::get_HashAlgorithm method
(certadm.h)
7/2/2022 • 2 minutes to read • Edit Online

The HashAlgorithm property gets or sets an identifier for the hash algorithm used to sign a certificate. The
default value is SHA1 .
This property is read/write.

Syntax
HRESULT get_HashAlgorithm(
BSTR *pVal
);

Parameters
pVal

Return value
None

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2008 Datacenter, Windows Server 2008
Enterprise [desktop apps only]

Target Platform Windows

Header certadm.h (include Certserv.h)

Librar y Certadm.lib

DLL Certadm.dll

See also
IOCSPCAConfiguration
 IOCSPCAConfiguration::get_Identifier method
(certadm.h)
7/2/2022 • 2 minutes to read • Edit Online

The Identifier property gets a name for the certification authority (CA) configuration. The default
implementations of IOCSPAdmin and IOCSPCAConfigurationCollection set this value.
This property is read-only.

Syntax
HRESULT get_Identifier(
BSTR *pVal
);

Parameters
pVal

Return value
None

Remarks
The name returned in pVal corresponds to the name used in the bstrIdentifier parameter of the
CreateCAConfiguration method.

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2008 Datacenter, Windows Server 2008
Enterprise [desktop apps only]

Target Platform Windows

Header certadm.h (include Certserv.h)

Librar y Certadm.lib

DLL Certadm.dll

See also
IOCSPCAConfiguration
 IOCSPCAConfiguration::get_KeySpec method
(certadm.h)
7/2/2022 • 2 minutes to read • Edit Online

The KeySpec property gets a value that indicates whether the key bound to the configuration is used for
encryption or for signing content. The default implementations of IOCSPAdmin and
IOCSPCAConfigurationCollection methods set this value.
Possible values are determined by the cryptographic service provider (CSP) in use.
This property is read-only.

Syntax
HRESULT get_KeySpec(
ULONG *pVal
);

Parameters
pVal

Return value
None

Remarks
For the Microsoft Base Cryptographic Provider, the KeySpec property has the value AT_KEYEXCHANGE for
exchange keys and the value AT_SIGNATURE for signature keys. The default value is AT_SIGNATURE .
For information about the other Microsoft CSPs, see Cryptographic Service Providers in the CryptoAPI 2.0
documentation.
For information about a non-Microsoft CSP, see the documentation provided with that CSP.

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2008 Datacenter, Windows Server 2008
Enterprise [desktop apps only]

Target Platform Windows

Header certadm.h (include Certserv.h)

 Librar y Certadm.lib

DLL Certadm.dll

See also
IOCSPCAConfiguration
 IOCSPCAConfiguration::get_LocalRevocationInformation
method (certadm.h)
7/2/2022 • 2 minutes to read • Edit Online

The LocalRevocationInformation property gets or sets the certificate revocation list (CRL) of the local
machine. This list provides additional revocation information, or supersedes information from the revocation
provider configured by ProviderCLSID.
This property is read/write.

Syntax
HRESULT get_LocalRevocationInformation(
VARIANT *pVal
);

Parameters
pVal

Return value
None

Remarks
The CRL used for the LocalRevocationInformation property can be signed or not signed. There is no
signature verification for the CRL.

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2008 Datacenter, Windows Server 2008
Enterprise [desktop apps only]

Target Platform Windows

Header certadm.h (include Certserv.h)

Librar y Certadm.lib

DLL Certadm.dll

See also
IOCSPCAConfiguration
 IOCSPCAConfiguration::get_Modified method
(certadm.h)
7/2/2022 • 2 minutes to read • Edit Online

The Modified property gets a value that indicates whether an OCSPCAConfiguration object has been
modified since it was created.
This property is read-only.

Syntax
HRESULT get_Modified(
VARIANT_BOOL *pVal
);

Parameters
pVal

Return value
None

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2008 Datacenter, Windows Server 2008
Enterprise [desktop apps only]

Target Platform Windows

Header certadm.h (include Certserv.h)

Librar y Certadm.lib

DLL Certadm.dll

See also
IOCSPCAConfiguration
 IOCSPCAConfiguration::get_ProviderCLSID method
(certadm.h)
7/2/2022 • 2 minutes to read • Edit Online

The ProviderCLSID property gets or sets the CLSID of the revocation information provider used by the CA
configuration. A provider implements IOCSPRevInfoProvider interface and processes certificate status
requests for a responder service.
This property is read/write.

Syntax
HRESULT get_ProviderCLSID(
BSTR *pVal
);

Parameters
pVal

Return value
None

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2008 Datacenter, Windows Server 2008
Enterprise [desktop apps only]

Target Platform Windows

Header certadm.h (include Certserv.h)

Librar y Certadm.lib

DLL Certadm.dll

See also
IOCSPCAConfiguration
 IOCSPCAConfiguration::get_ProviderProperties
method (certadm.h)
7/2/2022 • 2 minutes to read • Edit Online

The ProviderProper ties property gets or sets information that provides certificate status responses. The
revocation information provider configured in the ProviderCLSID property uses certificate revocation lists
(CRLs) specified in this property to provide responses.
This property is read/write.

Syntax
HRESULT get_ProviderProperties(
VARIANT *pVal
);

Parameters
pVal

Return value
None

Remarks
The VARIANT returned in pVal is a pointer to a safe array that contains the properties as name-value pairs.
This array is a two-dimensional array of elements, each of type VARIANT. The array contains one row for each
named property in the collection. Each row contains two columns: the property name and the property value.
The following table lists the possible named property values and their data types for the default revocation
provider:

NAME DATA T Y P E

BaseCrl REG_BINARY

BaseCrlUrls REG_MULTI_SZ

CrlUrlTimeout DWORD

DeltaCrl REG_BINARY

DeltaCrlUrls REG_MULTI_SZ

RefreshTimeOut DWORD

RevocationErrorCode DWORD
 IssuedSerialNumbersDirectories REG_MULTI_SZ

Note: IssuedSerialNumberDirectories is not supported on Windows Server 2008.

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2008 Datacenter, Windows Server 2008
Enterprise [desktop apps only]

Target Platform Windows

Header certadm.h (include Certserv.h)

Librar y Certadm.lib

DLL Certadm.dll

See also
IOCSPCAConfiguration
 IOCSPCAConfiguration::get_ReminderDuration
method (certadm.h)
7/2/2022 • 2 minutes to read • Edit Online

The ReminderDuration property gets or sets the percentage of a signing certificate lifetime after which a
warning event is logged.
This property is read/write.

Syntax
HRESULT get_ReminderDuration(
ULONG *pVal
);

Parameters
pVal

Return value
None

Remarks
Percentage values must be in the range 0 through 100; the default value is 90. An Online Certificate Status
Protocol (OCSP) responder service includes a service-wide value having this default.

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2008 Datacenter, Windows Server 2008
Enterprise [desktop apps only]

Target Platform Windows

Header certadm.h (include Certserv.h)

Librar y Certadm.lib

DLL Certadm.dll

See also
IOCSPCAConfiguration
 IOCSPCAConfiguration::get_SigningCertificate
method (certadm.h)
7/2/2022 • 2 minutes to read • Edit Online

The SigningCer tificate property gets or sets a signing certificate that has been encoded by using
Distinguished Encoding Rules (DER). An Online Certificate Status Protocol (OCSP) responder service uses this
certificate to sign its responses to certificate status requests.
This property is read/write.

Syntax
HRESULT get_SigningCertificate(
VARIANT *pVal
);

Parameters
pVal

Return value
None

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2008 Datacenter, Windows Server 2008
Enterprise [desktop apps only]

Target Platform Windows

Header certadm.h (include Certserv.h)

Librar y Certadm.lib

DLL Certadm.dll

See also
IOCSPCAConfiguration
 IOCSPCAConfiguration::get_SigningCertificateTemplate
method (certadm.h)
7/2/2022 • 2 minutes to read • Edit Online

The SigningCer tificateTemplate property gets or sets the template name for a signing certificate.
The SigningCer tificateTemplate property contains a template name. This name is used in an Online
Certificate Status Protocol (OCSP) signing-certificate renewal to specify the certificate version being requested.
This property supports enrollment or renewal of signing certificates that were signed by a replaced certificate
key.
This property is read/write.

Syntax
HRESULT get_SigningCertificateTemplate(
BSTR *pVal
);

Parameters
pVal

Return value
None

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2008 Datacenter, Windows Server 2008
Enterprise [desktop apps only]

Target Platform Windows

Header certadm.h (include Certserv.h)

Librar y Certadm.lib

DLL Certadm.dll

See also
IOCSPCAConfiguration
 IOCSPCAConfiguration::get_SigningFlags method
(certadm.h)
7/2/2022 • 2 minutes to read • Edit Online

The SigningFlags property gets or sets a combination of flag values. These values specify the management of
signing certificates that belong to a certification authority (CA) configuration.
This property is read/write.

Syntax
HRESULT get_SigningFlags(
ULONG *pVal
);

Parameters
pVal

Return value
None

Remarks
The following table lists bit flag values for SigningFlags .

F L A G C O N STA N T F L A G VA L UE DESC RIP T IO N

OCSP_SF_SILENT 0x001 Acquire a private key silently.

OCSP_SF_USE_CACERT 0x002 Use a CA certificate in this

configuration for signing an OCSP
response. This option is available only
if the responder service is installed on
the CA computer.

OCSP_SF_ALLOW_SIGNINGCERT_ 0x004 Enable a responder service to

AUTORENEWAL automatically transition to a renewed
signing certificate.

OCSP_SF_FORCE_SIGNINGCERT_I 0x008 Force a delegated signing certificate to

SSUER_ISCA be signed by the CA.

OCSP_SF_AUTODISCOVER_SIGNI 0x010 Automatically discover a delegated

NGCERT signing certificate.

OCSP_SF_MANUAL_ASSIGN_SIGN 0x020 Manually assign a signing certificate.

INGCERT
 OCSP_SF_RESPONDER_ID_KEYHA 0x040 A responder ID includes a hash of the
SH public key of the signing certificate
(default).

OCSP_SF_RESPONDER_ID_NAME 0x080 A responder ID includes the name of

the subject in a signing certificate.

OCSP_SF_ALLOW_NONCE_EXTENS 0x100 Enable NONCE extension to be

ION processed by a responder service.

OCSP_SF_ALLOW_SIGNINGCERT_ 0x200 A responder service can enroll for a

AUTOENROLLMENT signing certificate.

When setting SigningFlags , you must specify one of the values OCSP_SF_USE_CACERT ,
OCSP_SF_AUTODISCOVER_SIGNINGCERT , or OCSP_SF_MANUAL_ASSIGN_SIGNINGCERT .
If you specify OCSP_SF_ALLOW_SIGNINGCERT_AUTOENROLLMENT , you must also specify
OCSP_SF_AUTODISCOVER_SIGNINGCERT .

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2008 Datacenter, Windows Server 2008
Enterprise [desktop apps only]

Target Platform Windows

Header certadm.h (include Certserv.h)

Librar y Certadm.lib

DLL Certadm.dll

See also
IOCSPCAConfiguration
 IOCSPCAConfiguration::put_CAConfig method
(certadm.h)
7/2/2022 • 2 minutes to read • Edit Online

The CAConfig property gets or sets a certification authority (CA) name with which a signing certificate must be
signed.
The CAConfig property contains a CA name. This name lets an Online Certificate Status Protocol (OCSP)
signing-certificate renewal request specify the issuing CA. The new signing certificate must be signed with this
CA.
This property supports responses to status requests for a certificate that has been replaced but is still valid.
This property is read/write.

Syntax
HRESULT put_CAConfig(
const BSTR newVal
);

Parameters
newVal

Return value
None

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2008 Datacenter, Windows Server 2008
Enterprise [desktop apps only]

Target Platform Windows

Header certadm.h (include Certserv.h)

Librar y Certadm.lib

DLL Certadm.dll

See also
IOCSPCAConfiguration
 IOCSPCAConfiguration::put_HashAlgorithm
method (certadm.h)
7/2/2022 • 2 minutes to read • Edit Online

The HashAlgorithm property gets or sets an identifier for the hash algorithm used to sign a certificate. The
default value is SHA1 .
This property is read/write.

Syntax
HRESULT put_HashAlgorithm(
const BSTR newVal
);

Parameters
newVal

Return value
None

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2008 Datacenter, Windows Server 2008
Enterprise [desktop apps only]

Target Platform Windows

Header certadm.h (include Certserv.h)

Librar y Certadm.lib

DLL Certadm.dll

See also
IOCSPCAConfiguration
 IOCSPCAConfiguration::put_LocalRevocationInformation
method (certadm.h)
7/2/2022 • 2 minutes to read • Edit Online

The LocalRevocationInformation property gets or sets the certificate revocation list (CRL) of the local
machine. This list provides additional revocation information, or supersedes information from the revocation
provider configured by ProviderCLSID.
This property is read/write.

Syntax
HRESULT put_LocalRevocationInformation(
VARIANT newVal
);

Parameters
newVal

Return value
None

Remarks
The CRL used for the LocalRevocationInformation property can be signed or not signed. There is no
signature verification for the CRL.

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2008 Datacenter, Windows Server 2008
Enterprise [desktop apps only]

Target Platform Windows

Header certadm.h (include Certserv.h)

Librar y Certadm.lib

DLL Certadm.dll

See also
IOCSPCAConfiguration
 IOCSPCAConfiguration::put_ProviderCLSID method
(certadm.h)
7/2/2022 • 2 minutes to read • Edit Online

The ProviderCLSID property gets or sets the CLSID of the revocation information provider used by the CA
configuration. A provider implements IOCSPRevInfoProvider interface and processes certificate status
requests for a responder service.
This property is read/write.

Syntax
HRESULT put_ProviderCLSID(
const BSTR newVal
);

Parameters
newVal

Return value
None

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2008 Datacenter, Windows Server 2008
Enterprise [desktop apps only]

Target Platform Windows

Header certadm.h (include Certserv.h)

Librar y Certadm.lib

DLL Certadm.dll

See also
IOCSPCAConfiguration
 IOCSPCAConfiguration::put_ProviderProperties
method (certadm.h)
7/2/2022 • 2 minutes to read • Edit Online

The ProviderProper ties property gets or sets information that provides certificate status responses. The
revocation information provider configured in the ProviderCLSID property uses certificate revocation lists
(CRLs) specified in this property to provide responses.
This property is read/write.

Syntax
HRESULT put_ProviderProperties(
VARIANT newVal
);

Parameters
newVal

Return value
None

Remarks
The VARIANT returned in pVal is an IOCSPPropertyCollection interface.
To work with revocation-information provider properties:
1. Create an IOCSPPropertyCollection object.
2. Call InitializeFromProperties and pass in the VARIANT , pVal, returned by the ProviderProper ties property.
3. Use the Methods and Properties of the IOCSPPropertyCollection interface.
The following table lists the possible IOCSPProperty Name values and their data types for the default revocation-
information provider.

NAME DATA T Y P E

BaseCrl Depends on BaseCrlUrl

BaseCrlUrl REG_MULTI_SZ

CrlUrlTimeout DWORD

DeltaCrl Depends on BaseCrlUrl or DeltaCrlUrl

DeltaCrlUrl REG_MULTI_SZ
 RefreshTimeOut DWORD

RevocationErrorCode DWORD

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2008 Datacenter, Windows Server 2008
Enterprise [desktop apps only]

Target Platform Windows

Header certadm.h (include Certserv.h)

Librar y Certadm.lib

DLL Certadm.dll

See also
IOCSPCAConfiguration
 IOCSPCAConfiguration::put_ReminderDuration
method (certadm.h)
7/2/2022 • 2 minutes to read • Edit Online

The ReminderDuration property gets or sets the percentage of a signing certificate lifetime after which a
warning event is logged.
This property is read/write.

Syntax
HRESULT put_ReminderDuration(
ULONG newVal
);

Parameters
newVal

Return value
None

Remarks
Percentage values must be in the range 0 through 100; the default value is 90. An Online Certificate Status
Protocol (OCSP) responder service includes a service-wide value having this default.

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2008 Datacenter, Windows Server 2008
Enterprise [desktop apps only]

Target Platform Windows

Header certadm.h (include Certserv.h)

Librar y Certadm.lib

DLL Certadm.dll

See also
IOCSPCAConfiguration
 IOCSPCAConfiguration::put_SigningCertificate
method (certadm.h)
7/2/2022 • 2 minutes to read • Edit Online

The SigningCer tificate property gets or sets a signing certificate that has been encoded by using
Distinguished Encoding Rules (DER). An Online Certificate Status Protocol (OCSP) responder service uses this
certificate to sign its responses to certificate status requests.
This property is read/write.

Syntax
HRESULT put_SigningCertificate(
VARIANT newVal
);

Parameters
newVal

Return value
None

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2008 Datacenter, Windows Server 2008
Enterprise [desktop apps only]

Target Platform Windows

Header certadm.h (include Certserv.h)

Librar y Certadm.lib

DLL Certadm.dll

See also
IOCSPCAConfiguration
 IOCSPCAConfiguration::put_SigningCertificateTemplate
method (certadm.h)
7/2/2022 • 2 minutes to read • Edit Online

The SigningCer tificateTemplate property gets or sets the template name for a signing certificate.
The SigningCer tificateTemplate property contains a template name. This name is used in an Online
Certificate Status Protocol (OCSP) signing-certificate renewal to specify the certificate version being requested.
This property supports enrollment or renewal of signing certificates that were signed by a replaced certificate
key.
This property is read/write.

Syntax
HRESULT put_SigningCertificateTemplate(
const BSTR newVal
);

Parameters
newVal

Return value
None

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2008 Datacenter, Windows Server 2008
Enterprise [desktop apps only]

Target Platform Windows

Header certadm.h (include Certserv.h)

Librar y Certadm.lib

DLL Certadm.dll

See also
IOCSPCAConfiguration
 IOCSPCAConfiguration::put_SigningFlags method
(certadm.h)
7/2/2022 • 2 minutes to read • Edit Online

The SigningFlags property gets or sets a combination of flag values. These values specify the management of
signing certificates that belong to a certification authority (CA) configuration.
This property is read/write.

Syntax
HRESULT put_SigningFlags(
ULONG newVal
);

Parameters
newVal

Return value
None

Remarks
The following table lists bit flag values for SigningFlags .

F L A G C O N STA N T F L A G VA L UE DESC RIP T IO N

OCSP_SF_SILENT 0x001 Acquire a private key silently.

OCSP_SF_USE_CACERT 0x002 Use a CA certificate in this

configuration for signing an OCSP
response. This option is available only
if the responder service is installed on
the CA computer.

OCSP_SF_ALLOW_SIGNINGCERT_ 0x004 Enable a responder service to

AUTORENEWAL automatically transition to a renewed
signing certificate.

OCSP_SF_FORCE_SIGNINGCERT_I 0x008 Force a delegated signing certificate to

SSUER_ISCA be signed by the CA.

OCSP_SF_AUTODISCOVER_SIGNI 0x010 Automatically discover a delegated

NGCERT signing certificate.

OCSP_SF_MANUAL_ASSIGN_SIGN 0x020 Manually assign a signing certificate.

INGCERT
 OCSP_SF_RESPONDER_ID_KEYHA 0x040 A responder ID includes a hash of the
SH public key of the signing certificate
(default).

OCSP_SF_RESPONDER_ID_NAME 0x080 A responder ID includes the name of

the subject in a signing certificate.

OCSP_SF_ALLOW_NONCE_EXTENS 0x100 Enable NONCE extension to be

ION processed by a responder service.

OCSP_SF_ALLOW_SIGNINGCERT_ 0x200 A responder service can enroll for a

AUTOENROLLMENT signing certificate.

When setting SigningFlags , you must specify one of the values OCSP_SF_USE_CACERT ,
OCSP_SF_AUTODISCOVER_SIGNINGCERT , or OCSP_SF_MANUAL_ASSIGN_SIGNINGCERT .
If you specify OCSP_SF_ALLOW_SIGNINGCERT_AUTOENROLLMENT , you must also specify
OCSP_SF_AUTODISCOVER_SIGNINGCERT .

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2008 Datacenter, Windows Server 2008
Enterprise [desktop apps only]

Target Platform Windows

Header certadm.h (include Certserv.h)

Librar y Certadm.lib

DLL Certadm.dll

See also
IOCSPCAConfiguration
 IOCSPCAConfigurationCollection interface
(certadm.h)
7/2/2022 • 2 minutes to read • Edit Online

The IOCSPCAConfigurationCollection interface represents a set of certificates for which an Online

Certificate Status Protocol (OCSP) service has been configured to provide certificate status responses.
Microsoft provides a default implementation of this interface in the OCSPCAConfigurationCollection class. A
OCSPCAConfigurationCollection object cannot be created externally.
The default implementation of IOCSPAdmin creates a OCSPCAConfiguration object and uses its properties.

Inheritance
The IOCSPCAConfigurationCollection interface inherits from the IDispatch interface.
IOCSPCAConfigurationCollection also has these types of members:

Methods
The IOCSPCAConfigurationCollection interface has these methods.

IOCSPCAConfigurationCollection::CreateCAConfiguration

Creates a new certification authority (CA) configuration and adds it to the configuration set.

IOCSPCAConfigurationCollection::DeleteCAConfiguration

Removes a named certification authority (CA) configuration from the configuration set.

IOCSPCAConfigurationCollection::get__NewEnum

Gets an enumerator for the configuration set.

IOCSPCAConfigurationCollection::get_Count

Gets the number of certification authority (CA) configurations in the configuration set.

IOCSPCAConfigurationCollection::get_Item

Gets a certification authority (CA) configuration identified by index in the configuration set.

IOCSPCAConfigurationCollection::get_ItemByName

Gets a certification authority (CA) configuration identified by name in the configuration set.

Requirements
 Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2008 Datacenter, Windows Server 2008
Enterprise [desktop apps only]

Target Platform Windows

Header certadm.h (include Certsrv.h)

See also
IDispatch
 IOCSPCAConfigurationCollection::CreateCAConfiguration
method (certadm.h)
7/2/2022 • 2 minutes to read • Edit Online

The CreateCAConfiguration method creates a new certification authority (CA) configuration and adds it to the
configuration set.

Syntax
HRESULT CreateCAConfiguration(
[in] const BSTR bstrIdentifier,
[in] VARIANT varCACert,
[out] IOCSPCAConfiguration **ppVal
);

Parameters
[in] bstrIdentifier

A string that contains a name for the new IOCSPCAConfiguration object.

[in] varCACert

An X.509 CA certificate.
[out] ppVal

The address of a pointer to an IOCSPCAConfiguration interface for the newly created object.

Return value
C++
If the method succeeds, it returns S_OK .
If the method fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.
VB
An IOCSPCAConfiguration interface for the newly created object.

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2008 Datacenter, Windows Server 2008
Enterprise [desktop apps only]

Target Platform Windows

Header certadm.h (include Certsrv.h)

 Librar y Certadm.lib

DLL Certadm.dll

See also
IOCSPCAConfigurationCollection
 IOCSPCAConfigurationCollection::DeleteCAConfiguration
method (certadm.h)
7/2/2022 • 2 minutes to read • Edit Online

The DeleteCAConfiguration method removes a named certification authority (CA) configuration from the
configuration set.

Syntax
HRESULT DeleteCAConfiguration(
[in] const BSTR bstrIdentifier
);

Parameters
[in] bstrIdentifier

A string that contains the name for the IOCSPCAConfiguration object.

Return value
None

Remarks
The bstrIdentifier value must be one previously set by the CreateCAConfiguration method.

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2008 Datacenter, Windows Server 2008
Enterprise [desktop apps only]

Target Platform Windows

Header certadm.h (include Certsrv.h)

Librar y Certadm.lib

DLL Certadm.dll

See also
IOCSPCAConfigurationCollection
 IOCSPCAConfigurationCollection::get__NewEnum
method (certadm.h)
7/2/2022 • 2 minutes to read • Edit Online

The _NewEnum property gets an enumerator for the configuration set.

To enumerate the collection of properties in C++, use the Count and Item properties defined by the
IOCSPCAConfigurationCollection interface.
This property is read-only.

Syntax
HRESULT get__NewEnum(
IUnknown **pVal
);

Parameters
pVal

Return value
None

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2008 Datacenter, Windows Server 2008
Enterprise [desktop apps only]

Target Platform Windows

Header certadm.h (include Certsrv.h)

Librar y Certadm.lib

DLL Certadm.dll

See also
IOCSPCAConfigurationCollection
 IOCSPCAConfigurationCollection::get_Count
method (certadm.h)
7/2/2022 • 2 minutes to read • Edit Online

The Count property gets the number of certification authority (CA) configurations in the configuration set.
This property is read-only.

Syntax
HRESULT get_Count(
LONG *pVal
);

Parameters
pVal

Return value
None

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2008 Datacenter, Windows Server 2008
Enterprise [desktop apps only]

Target Platform Windows

Header certadm.h (include Certsrv.h)

Librar y Certadm.lib

DLL Certadm.dll

See also
IOCSPCAConfigurationCollection
 IOCSPCAConfigurationCollection::get_Item method
(certadm.h)
7/2/2022 • 2 minutes to read • Edit Online

The Item property gets a certification authority (CA) configuration identified by index in the configuration set.
This property is read-only.

Syntax
HRESULT get_Item(
LONG Index,
VARIANT *pVal
);

Parameters
Index

pVal

Return value
None

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2008 Datacenter, Windows Server 2008
Enterprise [desktop apps only]

Target Platform Windows

Header certadm.h (include Certsrv.h)

Librar y Certadm.lib

DLL Certadm.dll

See also
IOCSPCAConfigurationCollection
 IOCSPCAConfigurationCollection::get_ItemByName
method (certadm.h)
7/2/2022 • 2 minutes to read • Edit Online

The ItemByName property gets a certification authority (CA) configuration identified by name in the
configuration set.
This property is read-only.

Syntax
HRESULT get_ItemByName(
const BSTR bstrIdentifier,
VARIANT *pVal
);

Parameters
bstrIdentifier

pVal

Return value
None

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2008 Datacenter, Windows Server 2008
Enterprise [desktop apps only]

Target Platform Windows

Header certadm.h (include Certsrv.h)

Librar y Certadm.lib

DLL Certadm.dll

See also
IOCSPCAConfigurationCollection
 IOCSPProperty interface (certadm.h)
7/2/2022 • 2 minutes to read • Edit Online

The IOCSPProper ty interface represents a name-value pair for OCSPServiceProperties or ProviderProperties.

Microsoft provides a default implementation of this interface in the OCSPProper ty class. An OCSPProper ty
object cannot be created externally.
The default implementation of IOCSPPropertyCollection methods creates an OCSPProper ty object and uses its
properties.

Inheritance
The IOCSPProperty interface inherits from the IDispatch interface.

Methods
The IOCSPProper ty interface has these methods.

IOCSPProperty::get_Modified

Gets a value that indicates whether an OCSPProperty object has been modified since it was instantiated.

IOCSPProperty::get_Name

Gets the identifier part of the name-value pair represented by an OCSPProperty object.

IOCSPProperty::get_Value

Gets or sets the data part of the name-value pair represented by an OCSPProperty object.

IOCSPProperty::put_Value

Gets or sets the data part of the name-value pair represented by an OCSPProperty object.

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2008 Datacenter, Windows Server 2008
Enterprise [desktop apps only]

Target Platform Windows

Header certadm.h (include Certserv.h)

See also
IDispatch
 IOCSPProperty::get_Modified method (certadm.h)
7/2/2022 • 2 minutes to read • Edit Online

The Modified property gets a value that indicates whether an OCSPProper ty object has been modified since it
was instantiated.
This property is read-only.

Syntax
HRESULT get_Modified(
VARIANT_BOOL *pVal
);

Parameters
pVal

Return value
None

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2008 Datacenter, Windows Server 2008
Enterprise [desktop apps only]

Target Platform Windows

Header certadm.h (include Certserv.h)

Librar y Certadm.lib

DLL Certadm.dll

See also
IOCSPProperty
 IOCSPProperty::get_Name method (certadm.h)
7/2/2022 • 2 minutes to read • Edit Online

The Name property gets the identifier part of the name-value pair represented by an OCSPProper ty object.
This property is read-only.

Syntax
HRESULT get_Name(
BSTR *pVal
);

Parameters
pVal

Return value
None

Remarks
For possible values of pVal, see OCSPServiceProperties or ProviderProperties.

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2008 Datacenter, Windows Server 2008
Enterprise [desktop apps only]

Target Platform Windows

Header certadm.h (include Certserv.h)

Librar y Certadm.lib

DLL Certadm.dll

See also
IOCSPProperty
 IOCSPProperty::get_Value method (certadm.h)
7/2/2022 • 2 minutes to read • Edit Online

The Value property gets or sets the data part of the name-value pair represented by an OCSPProper ty object.
This property is read/write.

Syntax
HRESULT get_Value(
VARIANT *pVal
);

Parameters
pVal

Return value
None

Remarks
For possible values of newVal and pVal, see OCSPServiceProperties or ProviderProperties.

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2008 Datacenter, Windows Server 2008
Enterprise [desktop apps only]

Target Platform Windows

Header certadm.h (include Certserv.h)

Librar y Certadm.lib

DLL Certadm.dll

See also
IOCSPProperty
 IOCSPProperty::put_Value method (certadm.h)
7/2/2022 • 2 minutes to read • Edit Online

The Value property gets or sets the data part of the name-value pair represented by an OCSPProper ty object.
This property is read/write.

Syntax
HRESULT put_Value(
VARIANT newVal
);

Parameters
newVal

Return value
None

Remarks
For possible values of newVal and pVal, see OCSPServiceProperties or ProviderProperties.

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2008 Datacenter, Windows Server 2008
Enterprise [desktop apps only]

Target Platform Windows

Header certadm.h (include Certserv.h)

Librar y Certadm.lib

DLL Certadm.dll

See also
IOCSPProperty
 IOCSPPropertyCollection interface (certadm.h)
7/2/2022 • 2 minutes to read • Edit Online

The IOCSPProper tyCollection interface represents a set of configurable attribute properties (name-value
pairs) for an Online Certificate Status Protocol (OCSP) service. Microsoft provides a default implementation of
this interface in the OCSPProper tyCollection class.
In C++, you create an instance of this interface by calling the CoCreateInstance function with the
CLSID_OCSPProper tyCollection class identifier.
In Visual Basic Scripting Edition, you create an instance of the OCSPProper tyCollection object.

Inheritance
The IOCSPProper tyCollection interface inherits from the IDispatch interface. IOCSPProper tyCollection
also has these types of members:

Methods
The IOCSPProper tyCollection interface has these methods.

IOCSPPropertyCollection::CreateProperty

Creates a new property and adds it to a property set.

IOCSPPropertyCollection::DeleteProperty

Removes a named property from a property set.

IOCSPPropertyCollection::get__NewEnum

Gets an enumerator for a property set.

IOCSPPropertyCollection::get_Count

Gets the number of properties in a property set.

IOCSPPropertyCollection::get_Item

Gets the property identified by index in a property set.

IOCSPPropertyCollection::get_ItemByName

Gets the property identified by name in a property set.

IOCSPPropertyCollection::GetAllProperties

Gets all properties in a property set.

 IOCSPPropertyCollection::InitializeFromProperties

Creates a property set from the properties contained in an existing server configuration.

Remarks
The IOCSPProper tyCollection contains attributes for the following:
Web proxy settings that include the number of threads and number of cache entries
Audit settings that include start/stop, configuration change, security change, and request events
Security settings that include ACEs for IOCSPAdmin interfaces
All OCSP attribute information is stored in the following registry key:
HKEY_LOCAL_MACHINE \SYSTEM \CurrentControlSet \Ser vices \OCSPSvc \Responder
OCSP attributes govern OCSP responder service behavior for all CA configurations. For more information on CA
configurations, see the IOCSPCAConfiguration interface topic.

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2008 Datacenter, Windows Server 2008
Enterprise [desktop apps only]

Target Platform Windows

Header certadm.h (include Certserv.h)

See also
IDispatch
 IOCSPPropertyCollection::CreateProperty method
(certadm.h)
7/2/2022 • 2 minutes to read • Edit Online

The CreateProper ty method creates a new property and adds it to a property set.

Syntax
HRESULT CreateProperty(
[in] const BSTR bstrPropName,
[in] const VARIANT *pVarPropValue,
[out] IOCSPProperty **ppVal
);

Parameters
[in] bstrPropName

A string that contains the name of the new property object.

[in] pVarPropValue

C++ A pointer to the new property object.

VB The new property object.

[out] ppVal

A pointer to an IOCSPProperty interface for the newly created object.

Return value
C++
If the method succeeds, it returns S_OK .
If the method fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.
VB
An IOCSPProperty interface for the newly created object.

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2008 Datacenter, Windows Server 2008
Enterprise [desktop apps only]
 Target Platform Windows

Header certadm.h (include Certserv.h)

Librar y Certadm.lib

DLL Certadm.dll

See also
IOCSPPropertyCollection
 IOCSPPropertyCollection::DeleteProperty method
(certadm.h)
7/2/2022 • 2 minutes to read • Edit Online

The DeleteProper ty method removes a named property from a property set.

Syntax
HRESULT DeleteProperty(
[in] const BSTR bstrPropName
);

Parameters
[in] bstrPropName

A string that contains the name of the property to remove.

Return value
None

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2008 Datacenter, Windows Server 2008
Enterprise [desktop apps only]

Target Platform Windows

Header certadm.h (include Certserv.h)

Librar y Certadm.lib

DLL Certadm.dll

See also
IOCSPPropertyCollection
 IOCSPPropertyCollection::get__NewEnum method
(certadm.h)
7/2/2022 • 2 minutes to read • Edit Online

The _NewEnum property gets an enumerator for a property set.

To enumerate the collection of properties with C++, use the Count and Item properties defined by the
IOCSPPropertyCollection interface.
This property is read-only.

Syntax
HRESULT get__NewEnum(
IUnknown **ppVal
);

Parameters
ppVal

Return value
None

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2008 Datacenter, Windows Server 2008
Enterprise [desktop apps only]

Target Platform Windows

Header certadm.h (include Certserv.h)

Librar y Certadm.lib

DLL Certadm.dll

See also
IOCSPPropertyCollection
 IOCSPPropertyCollection::get_Count method
(certadm.h)
7/2/2022 • 2 minutes to read • Edit Online

The Count property gets the number of properties in a property set.

This property is read-only.

Syntax
HRESULT get_Count(
LONG *pVal
);

Parameters
pVal

Return value
None

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2008 Datacenter, Windows Server 2008
Enterprise [desktop apps only]

Target Platform Windows

Header certadm.h (include Certserv.h)

Librar y Certadm.lib

DLL Certadm.dll

See also
IOCSPPropertyCollection
 IOCSPPropertyCollection::get_Item method
(certadm.h)
7/2/2022 • 2 minutes to read • Edit Online

The Item property gets the property identified by index in a property set.
This property is read-only.

Syntax
HRESULT get_Item(
LONG Index,
VARIANT *pVal
);

Parameters
Index

pVal

Return value
None

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2008 Datacenter, Windows Server 2008
Enterprise [desktop apps only]

Target Platform Windows

Header certadm.h (include Certserv.h)

Librar y Certadm.lib

DLL Certadm.dll

See also
IOCSPPropertyCollection
 IOCSPPropertyCollection::get_ItemByName method
(certadm.h)
7/2/2022 • 2 minutes to read • Edit Online

The ItemByName property gets the property identified by name in a property set.
This property is read-only.

Syntax
HRESULT get_ItemByName(
const BSTR bstrPropName,
VARIANT *pVal
);

Parameters
bstrPropName

pVal

Return value
None

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2008 Datacenter, Windows Server 2008
Enterprise [desktop apps only]

Target Platform Windows

Header certadm.h (include Certserv.h)

Librar y Certadm.lib

DLL Certadm.dll

See also
IOCSPPropertyCollection
 IOCSPPropertyCollection::GetAllProperties method
(certadm.h)
7/2/2022 • 2 minutes to read • Edit Online

The GetAllProper ties method gets all properties in a property set.

Syntax
HRESULT GetAllProperties(
[out] VARIANT *pVarProperties
);

Parameters
[out] pVarProperties

A pointer to a safe array that contains the properties as name-value pairs.

This array is a two-dimensional array of elements, each of type VARIANT . The array contains one row for each
named property in the collection. Each row contains two columns: the property name and the property value.

Return value
C++
If the method succeeds, it returns S_OK .
If the method fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.
VB
A safe array that contains the properties as name-value pairs.
This array is a two-dimensional array of elements, each of type Variant . The array contains one row for each
named property in the collection. Each row contains two columns: the property name and the property value.

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2008 Datacenter, Windows Server 2008
Enterprise [desktop apps only]

Target Platform Windows

Header certadm.h (include Certserv.h)

Librar y Certadm.lib
 DLL Certadm.dll

See also
IOCSPPropertyCollection
 IOCSPPropertyCollection::InitializeFromProperties
method (certadm.h)
7/2/2022 • 2 minutes to read • Edit Online

The InitializeFromProper ties method creates a property set from the properties contained in an existing
server configuration.

Syntax
HRESULT InitializeFromProperties(
[in] const VARIANT *pVarProperties
);

Parameters
[in] pVarProperties

C++ A pointer to an array that contains the property values. Each

array element is a VARIANT array that contains the
property name BSTR and a value VARIANT .

VB An array that contains the property values. Each array

element is a Variant array that contains the property name
String and a value Variant .

Return value
VB
If the method succeeds, it returns S_OK .
If the method fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.
If the method returns E_UNEXPECTED , the array pointed to by the pVarProperties parameter contained
duplicate properties.
If the method returns DISP_E_ARRAYISLOCKED , the array pointed to by the pVarProperties parameter is
locked.

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2008 Datacenter, Windows Server 2008
Enterprise [desktop apps only]

Target Platform Windows

 Header certadm.h (include Certserv.h)

Librar y Certadm.lib

DLL Certadm.dll

See also
IOCSPPropertyCollection
 certbcli.h header
7/2/2022 • 2 minutes to read • Edit Online

This header is used by Security and Identity. For more information, see:
Security and Identity
certbcli.h contains the following programming interfaces:

Functions

CertSrvBackupClose

Closes the file opened by the CertSrvBackupOpenFile function.

CertSrvBackupEnd

Ends a Certificate Services backup session.

CertSrvBackupFree

Used to free memory allocated from certain Certificate Services Backup APIs.

CertSrvBackupGetBackupLogsW

Retrieves the list of Certificate Services log file names that need to be backed up for the given backup context.

CertSrvBackupGetDatabaseNamesW

Retrieves the list of Certificate Services database file names that need to be backed up for the given backup context.

CertSrvBackupGetDynamicFileListW

Retrieves the list of Certificate Services dynamic file names that need to be backed up for the given backup context.

CertSrvBackupOpenFileW

Opens a file for backup.

CertSrvBackupPrepareW

Used to prepare a Certificate Services server for backup operations.

CertSrvBackupRead

Reads bytes from a Certificate Services file.

CertSrvBackupTruncateLogs

Eliminates redundant records and reduces the disk storage space used by log files.
CertSrvIsServerOnlineW

Determines if a Certificate Services server is online; if the Certificate Services server is not online, backup operations will not be
successful.

CertSrvRestoreEnd

Ends a Certificate Services restore session.

CertSrvRestoreGetDatabaseLocationsW

Used both in backup and restore scenarios and retrieves the list of Certificate Services database location names for all the files
being backed up or restored.

CertSrvRestorePrepareW

Prepares a Certificate Services instance for restore operations.

CertSrvRestoreRegisterComplete

Completes a registered Certificate Services restore operation.

CertSrvRestoreRegisterThroughFile

Registers a Certificate Services restore.

CertSrvRestoreRegisterW

Registers a Certificate Services restore.

CertSrvServerControlW

Issues a service control command to programmatically stop Certificate Services.

 CertSrvBackupClose function (certbcli.h)
7/2/2022 • 2 minutes to read • Edit Online

The Cer tSr vBackupClose function closes the file opened by the CertSrvBackupOpenFile function.

Syntax
HRESULT CERTBCLI_API CertSrvBackupClose(
[in] HCSBC hbc
);

Parameters
[in] hbc

A handle to a Certificate Services backup context.

Return value
The return value is an HRESULT . A value of S_OK indicates success.

Remarks
For every successful call to CertSrvBackupOpenFile, there should be a subsequent call to
Cer tSr vBackupClose . Upon completion of backing up a file, the file needs to be closed.
Examples

FNCERTSRVBACKUPCLOSE* pfnClose;
char * szBackupCloseFunc = "CertSrvBackupClose";
HRESULT hr=0;

// Get the address for the desired function.

// hInst was set by calling LoadLibrary for Certadm.dll.
pfnClose = (FNCERTSRVBACKUPCLOSE*)GetProcAddress(hInst,
szBackupCloseFunc);
if ( NULL == pfnClose )
{
printf("Failed GetProcAddress - %s, error=%d\n",
szBackupCloseFunc,
GetLastError() );
exit(1); // Or other appropriate error action.
}
// Close the file.
// hCSBC represents an HCSBC used in
// an earlier call to CertSrvBackupOpenFile.
hr = pfnClose(hCSBC);
if (FAILED(hr))
{
printf("Failed pfnClose call [%x]\n", hr);
exit(1); // Or other appropriate error action.
}

Requirements
 Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header certbcli.h (include Certsrv.h)

Librar y Certadm.lib

DLL Certadm.dll

See also
CertSrvBackupOpenFile
CertSrvBackupRead
Using the Certificate Services Backup and Restore Functions
 CertSrvBackupEnd function (certbcli.h)
7/2/2022 • 2 minutes to read • Edit Online

The Cer tSr vBackupEnd function ends a Certificate Services backup session.

Syntax
HRESULT CERTBCLI_API CertSrvBackupEnd(
[in] HCSBC hbc
);

Parameters
[in] hbc

A handle to a Certificate Services backup context.

Return value
The return value is an HRESULT . A value of S_OK indicates success.

Remarks
Upon completion of a backup session, the session needs to be terminated by means of Cer tSr vBackupEnd .
For every successful call to CertSrvBackupPrepare, there should be a call to Cer tSr vBackupEnd .
Examples

FNCERTSRVBACKUPEND* pfnBackupEnd;
char * szBackEndFunc = "CertSrvBackupEnd";
HRESULT hr=0;

// Get the address for the desired function.

// hInst was set by calling LoadLibrary for Certadm.dll.
pfnBackupEnd = (FNCERTSRVBACKUPEND*)GetProcAddress(hInst,
szBackEndFunc);
if (NULL == pfnBackupEnd)
{
printf("Failed GetProcAddress - %s, error=%d\n",
szBackEndFunc,
GetLastError() );
exit(1); // Or other appropriate error action.
}

// When done, release the HCSBC.

// hCSBC would have been created by an earlier call
// to CertSrvBackupPrepare.
hr = pfnBackupEnd(hCSBC);
if (FAILED(hr))
{
printf("Failed pfnBackupEnd call [%x]\n", hr);
exit(1); // Or other appropriate error action.
}
Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header certbcli.h (include Certsrv.h)

Librar y Certadm.lib

DLL Certadm.dll

See also
CertSrvBackupPrepare
Using the Certificate Services Backup and Restore Functions
 CertSrvBackupFree function (certbcli.h)
7/2/2022 • 2 minutes to read • Edit Online

The Cer tSr vBackupFree function is used to free memory allocated from certain Certificate Services Backup
APIs.

Syntax
VOID CERTBCLI_API CertSrvBackupFree(
[in] VOID *pv
);

Parameters
[in] pv

A pointer to the memory to be freed.

Return value
This function does not return a value.

Remarks
Call this function when finished with memory allocated by using the following functions:
CertSrvBackupGetBackupLogs
CertSrvBackupGetDatabaseNames
CertSrvBackupGetDynamicFileList
CertSrvServerControl
CertSrvRestoreGetDatabaseLocations
Examples
 FNCERTSRVBACKUPFREE* pfnBackupFree;

char * szBackupFreeFunc = "CertSrvBackupFree";

// Get the address for the desired function.

// hInst was set by calling LoadLibrary for Certadm.dll.
pfnBackupFree = (FNCERTSRVBACKUPFREE*)GetProcAddress(hInst,
szBackupFreeFunc);
if ( NULL == pfnBackupFree )
{
printf("Failed GetProcAddress - %s, error=%d\n",
szBackupFreeFunc,
GetLastError() );
exit(1);
}

// Use the backup APIs.

// ...

// Free allocated memory.

// pBuff was allocated by another certsrv backup function.
pfnBackupFree(pBuff);

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header certbcli.h (include Certsrv.h)

Librar y Certadm.lib

DLL Certadm.dll

See also
CertSrvBackupGetBackupLogs
CertSrvBackupGetDatabaseNames
CertSrvBackupGetDynamicFileList
CertSrvRestoreGetDatabaseLocations
CertSrvServerControl
Using the Certificate Services Backup and Restore Functions
 CertSrvBackupGetBackupLogsW function
(certbcli.h)
7/2/2022 • 2 minutes to read • Edit Online

The Cer tSr vBackupGetBackupLogs function retrieves the list of Certificate Services log file names that need
to be backed up for the given backup context.

Syntax
HRESULT CERTBCLI_API CertSrvBackupGetBackupLogsW(
[in] HCSBC hbc,
[out] PWSTR *ppwszzBackupLogFiles,
[out] DWORD *pcbSize
);

Parameters
[in] hbc

A handle to a Certificate Services backup context.

[out] ppwszzBackupLogFiles

A pointer to WCHAR pointer that will receive the list of null-terminated log file names. There is a null character
after every file name and an extra null character at the end of the list. The file name will be in the UNC form "##
\\Server\SharePoint\…Path…\FileName.ext". The directory names will have the same form but without the
trailing "\FileName.ext". The text "##" denotes a Certificate Services Backup file type (CSBFT_*) and is stored as a
single non-null Unicode character prefixed onto each UNC path. This type tag is defined in Certbcli.h and can be
one of the following values for this function.

VA L UE M EA N IN G

Certificate Services database log file name including path.

CSBFT_LOG

The name, including path, of the update file for the

CSBFT_PATCH_FILE Certificate Services database.
Windows Ser ver 2003: Database update files are not
used.

When you have finished using this allocated memory, free it by calling the CertSrvBackupFree function.
Setting ppwszzBackupLogFiles to NULL before calling this function is optional.
[out] pcbSize

A pointer to the DWORD value that specifies the number of bytes in ppwszzBackupLogFiles.

Return value
The return value is an HRESULT . A value of S_OK indicates success.

Remarks
The log files represent database activity (request submissions, certificate revocation, and so on) that has
occurred since the last log file truncation. Log file volume increases as database activity occurs. The log files can
be decreased in size by performing a backup and then calling CertSrvBackupTruncateLogs.
This function's name in the Certadm.dll is Cer tSr vBackupGetBackupLogsW . You must use this form of the
name when calling GetProcAddress. Also, this function is defined as type
FNCERTSRVBACKUPGETBACKUPLOGSW in the Certbcli.h header file.
Examples

FNCERTSRVBACKUPGETBACKUPLOGSW* pfnGetBackupLogs;
char * szGetBackupLogsFunc = "CertSrvBackupGetBackupLogsW";

WCHAR * pwszzLogFiles;

DWORD nListBytes=0;

HRESULT hr=0;

// Get the address for the desired function.

// hInst was set by calling LoadLibrary for Certadm.dll.
pfnGetBackupLogs = (FNCERTSRVBACKUPGETBACKUPLOGSW*)GetProcAddress
(hInst, szGetBackupLogsFunc);
if ( NULL == pfnGetBackupLogs )
{
printf("Failed GetProcAddress - %s, error=%d\n",
szGetBackupLogsFunc,
GetLastError() );
exit(1); // Or other appropriate error action.
}

// Determine the names of the log files.

// hCSBC was set by an earlier call to CertSrvbackupPrepare.
hr = pfnGetBackupLogs(hCSBC, &pwszzLogFiles, &nListBytes);
if (FAILED(hr))
{
printf("Failed pfnGetBackupLogs call [%x]\n", hr);
exit(1); // Or other appropriate error action.
}
else
{
printf("%d bytes for log file names\n", nListBytes);
WCHAR * pwszLog = pwszzLogFiles;
// Process the list.
while ( L'\0' != *pwszLog )
{
// Use the file name referenced by pwszLog.
// Here it is merely displayed.
printf("%02x: %ws\n", *pwszLog, &pwszLog[1]);
// Move to the next logfile name.
// + 1 moves past the null terminator.
pwszLog+=(wcslen(pwszLog)) + 1;
}

// Free the allocated memory.

// pfnBackupFree is the address of the CertSrvBackupFree
// function.
pfnBackupFree(pwszzLogFiles);
}
Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header certbcli.h (include Certsrv.h)

Librar y Certadm.lib

DLL Certadm.dll

See also
CertSrvBackupFree
CertSrvBackupOpenFile
CertSrvBackupTruncateLogs
Using the Certificate Services Backup and Restore Functions
 CertSrvBackupGetDatabaseNamesW function
(certbcli.h)
7/2/2022 • 2 minutes to read • Edit Online

The Cer tSr vBackupGetDatabaseNames function retrieves the list of Certificate Services database file names
that need to be backed up for the given backup context.

Syntax
HRESULT CERTBCLI_API CertSrvBackupGetDatabaseNamesW(
[in] HCSBC hbc,
[out] PWSTR *ppwszzAttachmentInformation,
[out] DWORD *pcbSize
);

Parameters
[in] hbc

A handle to a Certificate Services backup context.

[out] ppwszzAttachmentInformation

A pointer to a WCHAR pointer that will receive the list of null-terminated database file names. There is a null
character after every file name and an extra null character at the end of the list. The file name will be in the UNC
form "## \\Server\SharePoint\…Path…\FileName.ext". The directory names will have the same form but without
the trailing "\FileName.ext". The text "##" denotes a Certificate Services Backup file type (CSBFT_*) and is stored
as a single non-null Unicode character prefixed onto each UNC path. The type tag is defined in Certbcli.h and
can be the following value for this function.

VA L UE M EA N IN G

Certificate Services database file name including path.

CSBFT_CERTSERVER_DATABASE

You must free this allocated memory when done by calling CertSrvBackupFree. Before calling this function,
setting *ppwszzAttachmentInformation to NULL is optional.
[out] pcbSize

A pointer to the DWORD value that specifies the number of bytes in ppwszzAttachmentInformation.

Return value
The return value is an HRESULT . A value of S_OK indicates success.

Remarks
This function's name in the Certadm.dll is Cer tSr vBackupGetDatabaseNamesW . You must use this form of
the name when calling GetProcAddress. Also, this function is defined as type
FNCERTSRVBACKUPGETDATABASENAMESW in the Certbcli.h header file.
Examples

FNCERTSRVBACKUPGETDATABASENAMESW* pfnGetDBNames;
char * szGetDBNamesFunc = "CertSrvBackupGetDatabaseNamesW";
WCHAR * pwszzDBFiles;
DWORD nListBytes=0;
HRESULT hr=0;

// Get the address for the desired function.

// hInst was set by calling LoadLibrary for Certadm.dll.
pfnGetDBNames = (FNCERTSRVBACKUPGETDATABASENAMESW*)
GetProcAddress(hInst, szGetDBNamesFunc);

if ( NULL == pfnGetDBNames )
{
printf("Failed GetProcAddress - %s, error=%d\n",
szGetDBNamesFunc,
GetLastError() );
exit(1); // Or other appropriate error action.
}

// Determine the names of the database files.

// hCSBC was set by an earlier call to CertSrvBackupPrepare
hr = pfnGetDBNames(hCSBC, &pwszzDBFiles, &nListBytes);
if (FAILED(hr))
{
printf("Failed pfnGetDBNames call [%x]\n", hr);
exit(1); // Or other appropriate error action.
}
else
{
printf("%d bytes for DB file names\n", nListBytes);
WCHAR * pwszFile = pwszzDBFiles;
// Process the list.
while ( L'\0' != *pwszFile )
{
// Use the file name referenced by pwszFile.
// Here it is merely displayed.
printf("%02x: %ws\n", *pwszFile, &pwszFile[1]);
// Move to the next database file name.
// + 1 moves past the null terminator.
pwszFile+=(wcslen(pwszFile)) + 1;
}
// Free the allocated memory.
// pfnBackupFree is the address of the
// CertSrvBackupFree function.
pfnBackupFree(pwszzDBFiles);
}

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

 Header certbcli.h (include Certsrv.h)

Librar y Certadm.lib

DLL Certadm.dll

See also
CertSrvBackupFree
CertSrvBackupOpenFile
Using the Certificate Services Backup and Restore Functions
 CertSrvBackupGetDynamicFileListW function
(certbcli.h)
7/2/2022 • 2 minutes to read • Edit Online

The Cer tSr vBackupGetDynamicFileList function retrieves the list of Certificate Services dynamic file names
that need to be backed up for the given backup context. The dynamic files are those that are not included in the
Certificate Services database backup.

Syntax
HRESULT CERTBCLI_API CertSrvBackupGetDynamicFileListW(
[in] HCSBC hbc,
[out] PWSTR *ppwszzFileList,
[out] DWORD *pcbSize
);

Parameters
[in] hbc

A handle to a Certificate Services backup context.

[out] ppwszzFileList

A pointer to a WCHAR pointer that will receive the list of null-terminated dynamic file names used by
Certificate Services. There is a null character after every file name and an extra null character at the end of the
list. The file name will be in the UNC form "\\Server\SharePoint\…Path…\FileName.ext". When you have finished
using this allocated memory, free it by calling the CertSrvBackupFree function.
Before calling this function, setting *ppwszzFileList to NULL is optional.
[out] pcbSize

A pointer to the DWORD value that specifies the number of bytes in ppwszzFileList.

Return value
The return value is an HRESULT . A value of S_OK indicates success.

Remarks
Use this function to retrieve a list of the Certificate Services dynamic file names. These files are separate from
the Certificate Services database and log files, and they are not backed up by the Certificate Services backup
APIs. As a result, some other means must be used to back up the dynamic files. An example of a Certificate
Services dynamic file is the certificate revocation list (CRL).
This function's name in the Certadm.dll is Cer tSr vBackupGetDynamicFileListW . You must use this form of
the name when calling GetProcAddress. Also, this function is defined as type
FNCERTSRVBACKUPGETDYNAMICFILELISTW in the Certbcli.h header file.
Examples
 FNCERTSRVBACKUPGETDYNAMICFILELISTW* pfnGetDynFiles;
char * szGetDynFilesFunc = "CertSrvBackupGetDynamicFileListW";
WCHAR * pwszzDynFiles;
DWORD nListBytes=0;
HRESULT hr=0;

// Get the address for the desired function.

// hInst was set by calling LoadLibrary for Certadm.dll.
pfnGetDynFiles = (FNCERTSRVBACKUPGETDYNAMICFILELISTW*)
GetProcAddress(hInst, szGetDynFilesFunc);
if ( NULL == pfnGetDynFiles )
{
printf("Failed GetProcAddress - %s, error=%d\n",
szGetDynFilesFunc,
GetLastError() );
exit(1); // Or other appropriate error action.
}

// Determine the names of the dynamic files.

// hCSBC was set by an earlier call to CertSrvBackupPrepare.
hr = pfnGetDynFiles(hCSBC, &pwszzDynFiles, &nListBytes);
if (FAILED(hr))
{
printf("Failed pfnGetDynFiles call [%x]\n", hr);
exit(1); // Or other appropriate error action.
}
else
{
printf("%d bytes for dynamic file names\n", nListBytes);
WCHAR * pwszFile = pwszzDynFiles;
// Process the list.
while ( L'\0' != *pwszFile )
{
// Use the file name referenced by pwszFile.
// Here it is merely displayed.
printf("%ws\n", pwszFile);
// Move to the next dynamic file name.
// + 1 moves past the null terminator.
pwszFile+=(wcslen(pwszFile)) + 1;
}
// Free the allocated memory.
// pfnBackupFree is the address of the
// CertSrvBackupFree function.
pfnBackupFree(pwszzDynFiles);
}

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header certbcli.h (include Certsrv.h)

Librar y Certadm.lib

DLL Certadm.dll
See also
CertSrvBackupFree
Using the Certificate Services Backup and Restore Functions
 CertSrvBackupOpenFileW function (certbcli.h)
7/2/2022 • 2 minutes to read • Edit Online

The Cer tSr vBackupOpenFile function opens a file for backup.

Syntax
HRESULT CERTBCLI_API CertSrvBackupOpenFileW(
[in] HCSBC hbc,
[in] WCHAR const *pwszAttachmentName,
[in] DWORD cbReadHintSize,
[out] LARGE_INTEGER *pliFileSize
);

Parameters
[in] hbc

A handle to a Certificate Services backup context.

[in] pwszAttachmentName

File name to open for backup purposes. This file name would be parsed from a list produced by means of
CertSrvBackupGetBackupLogs or CertSrvBackupGetDatabaseNames. Note that the names returned by
Cer tSr vBackupGetBackupLogs and Cer tSr vBackupGetDatabaseNames must have the single-WCHAR
CSBFT_* prefix stripped before Cer tSr vBackupOpenFile is called.
[in] cbReadHintSize

Number of bytes used as a hint when the file is read by CertSrvBackupRead. The cbReadHintSize parameter
passed to the first Cer tSr vBackupOpenFile call for the backup context is used to size the read buffer. Pass zero
for this parameter, and the buffer will be sized at a reasonably efficient size chosen by
Cer tSr vBackupOpenFile . If insufficient memory is available, the buffer size will be reduced until memory
allocation succeeds or until the buffer size reaches its minimum possible value. Pass a nonzero size to cause
Cer tSr vBackupOpenFile to size the buffer to a power of two near the value of cbReadHintSize. The
implementation will choose only powers of two between 64 KB and 4 MB.
[out] pliFileSize

A pointer to a L ARGE_INTEGER value that represents the number of bytes in the file.

Return value
If the function succeeds, the function returns S_OK.
If the function fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.

Remarks
Use this function to open a file for backup purposes. When you have finished using the file, close the file by
calling the CertSrvBackupClose function.
The name of this function in Certadm.dll is Cer tSr vBackupOpenFileW . You must use this form of the name
when calling GetProcAddress. Also, this function is defined as type FNCERTSRVBACKUPOPENFILEW in
Certbcli.h.
Examples

FNCERTSRVBACKUPOPENFILEW* pfnOpenFile;
char * szBackupOpenFunc = "CertSrvBackupOpenFileW";
LARGE_INTEGER liFileSize;
HRESULT hr=0;

// Get the address for the desired function.

// hInst was set by calling LoadLibrary for Certadm.dll.
pfnOpenFile = (FNCERTSRVBACKUPOPENFILEW*)GetProcAddress(hInst,
szBackupOpenFunc);
if ( NULL == pfnOpenFile )
{
printf("Failed GetProcAddress - %s, error=%d\n",
szBackupOpenFunc,
GetLastError() );
exit(1); // or other appropriate error action
}

// Open the file.

// hCSBC was set by an earlier call to CertSrvBackupPrepare.
// pwszFile specifies the name of a file.
// This name could have resulted from parsing the
// output from CertSrvBackupGetDatabaseNames, and so on.
hr = pfnOpenFile(hCSBC,
pwszFile,
0,
&liFileSize);
if (FAILED(hr))
{
printf("Failed pfnOpenFile call [%x] %ws\n",
hr,
pwszFile);
exit(1); // Or other appropriate error action.
}

// Use the opened file as needed.

// When you have finished using the file, call CertSrvBackupClose.
// ...

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header certbcli.h (include Certsrv.h)

Librar y Certadm.lib

DLL Certadm.dll
See also
CertSrvBackupClose
CertSrvBackupRead
Using the Certificate Services Backup and Restore Functions
 CertSrvBackupPrepareW function (certbcli.h)
7/2/2022 • 2 minutes to read • Edit Online

The Cer tSr vBackupPrepare function is used to prepare a Certificate Services server for backup operations.

Syntax
HRESULT CERTBCLI_API CertSrvBackupPrepareW(
[in] WCHAR const *pwszServerName,
[in] ULONG grbitJet,
[in] ULONG dwBackupFlags,
[out] HCSBC *phbc
);

Parameters
[in] pwszServerName

A pointer to the machine name of the server to prepare for online backup. This name can be the NetBIOS name
or the DNS name.
[in] grbitJet

Value used by the database engine; this value should be set to zero.
[in] dwBackupFlags

Specifies the backup type. This can be either of the following values.

VA L UE M EA N IN G

Backup the Certificate Services database, logs and related

CSBACKUP_TYPE_FULL files.

Backup the log files only.

CSBACKUP_TYPE_LOGS_ONLY

[out] phbc

A pointer to a Certificate Services backup context handle (HCSBC ).

Return value
The return value is an HRESULT . A value of S_OK indicates success, and *phbc will be set to an HCSBC which
can be used by other Certificate Services backup APIs.

Remarks
Before a Certificate Services backup can occur, it is necessary to create an HCSBC by means of
Cer tSr vBackupPrepare . The resulting HCSBC is a necessary parameter of Certificate Services backup
functions which can be used to list, open, read, and close files, as well as truncate the log files.
 Note When the backup session is completed, it is necessary to call CertSrvBackupEnd to release the HCSBC which resulted
from the call to Cer tSr vBackupPrepare .

This function's name in Certadm.dll is Cer tSr vBackupPrepareW . You must use this form of the name when calling
GetProcAddress. Also, this function is defined as type FNCERTSRVBACKUPPREPAREW in the Certbcli.h header
file.
To execute this call, you must have the backup privilege. For details, see Setting the Backup and Restore
Privileges.
Examples

WCHAR * wszServer = L"MyCertServerMachine";

FNCERTSRVBACKUPPREPAREW* pfnBackupPrepare;
char * szBackPrepFunc = "CertSrvBackupPrepareW";
HINSTANCE hInst=0;
HCSBC hCSBC=NULL;
HRESULT hr=0;

// Load the DLL.

hInst = LoadLibrary(L"Certadm.dll");
if ( NULL == hInst )
{
printf("Failed LoadLibrary, error=%d\n",
GetLastError() );
exit(1); // Or other appropriate error action.
}
// Get the address for the desired function.
pfnBackupPrepare = (FNCERTSRVBACKUPPREPAREW*)GetProcAddress( hInst,
szBackPrepFunc );
if ( NULL == pfnBackupPrepare )
{
printf("Failed GetProcAddress - %s, error=%d\n",
szBackPrepFunc,
GetLastError() );
exit(1); // Or other appropriate error action.
}

// Prepare CertServ for backup.

hr = pfnBackupPrepare(wszServer,
0,
CSBACKUP_TYPE_FULL,
&hCSBC);
if (FAILED(hr))
{
printf("Failed pfnBackupPrepare call [%x]\n", hr);
exit(1); // Or other appropriate error action.
}

// Use the HCSBC for backup operations.

// ...

// When done processing, release the HCSBC context

// by calling CertSrvBackupEnd (not shown here).
// ...

// Done processing, free the DLL.

if (hInst)
FreeLibrary(hInst);
Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header certbcli.h (include Certsrv.h)

Librar y Certadm.lib

DLL Certadm.dll

See also
CertSrvBackupEnd
Using the Certificate Services Backup and Restore Functions
 CertSrvBackupRead function (certbcli.h)
7/2/2022 • 2 minutes to read • Edit Online

The Cer tSr vBackupRead function reads bytes from a Certificate Services file.

Syntax
HRESULT CERTBCLI_API CertSrvBackupRead(
[in] HCSBC hbc,
[out] VOID *pvBuffer,
[in] DWORD cbBuffer,
[out] DWORD *pcbRead
);

Parameters
[in] hbc

A handle to a Certificate Services backup context.

[out] pvBuffer

Void pointer to storage which will contain bytes read from the file being backed up.
[in] cbBuffer

Size of the storage area referenced by pvBuffer.

[out] pcbRead

A pointer to a DWORD value which represents the actual number of bytes read by Cer tSr vBackupRead . The
number of bytes read can be less than the size of the storage area allocated to pvBuffer if the end of the file has
been reached.

Return value
The return value is an HRESULT . A value of S_OK indicates success.

Remarks
After opening the file for backup purposes (using CertSrvBackupOpenFile), call Cer tSr vBackupRead to
retrieve the contents of the file, and call an application-specific routine to write the contents to a backup
medium. Cer tSr vBackupRead and the application-specific routine can be placed in a loop until all the bytes of
the file are read and backed up. When done reading the file, close it by calling CertSrvBackupClose.
Examples
 #include <windows.h>
#include <stdio.h>
#include <Certbcli.h>

#define BUFFSIZE 524288

FNCERTSRVBACKUPREAD* pfnRead;
char * szBackupReadFunc = "CertSrvBackupRead";
BYTE ReadBuff[BUFFSIZE];
DWORD cbRead=0;
HRESULT hr=0;

// Get the address for the desired function.

// hInst was set by calling LoadLibrary for Certadm.dll.
pfnRead = (FNCERTSRVBACKUPREAD*)GetProcAddress(hInst,
szBackupReadFunc);
if ( NULL == pfnRead )
{
printf("Failed GetProcAddress - %s, error=%d\n",
szBackupReadFunc,
GetLastError() );
exit(1); // Or other appropriate error action.
}

// Read the file.

// hCSBC represents an HCSBC used in
// an earlier call to CertSrvBackupOpenFile.
// To read the entire file, this code
// would be placed in a loop.
hr = pfnRead( hCSBC,
&ReadBuff,
BUFFSIZE,
&cbRead );
if (FAILED(hr))
{
printf("Failed pfnRead call [%x]\n", hr);
exit(1); // Or other appropriate error action.
}

// Use the bytes read as needed. For example,

// in an application-specific routine to back
// up the file contents.
// ...

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header certbcli.h (include Certsrv.h)

Librar y Certadm.lib

DLL Certadm.dll
See also
CertSrvBackupClose
CertSrvBackupOpenFile
Using the Certificate Services Backup and Restore Functions
 CertSrvBackupTruncateLogs function (certbcli.h)
7/2/2022 • 2 minutes to read • Edit Online

The Cer tSr vBackupTruncateLogs function eliminates redundant records and reduces the disk storage space
used by log files. Before truncating the log files, ensure that a backup of all files returned by
CertSrvBackupGetDatabaseNames and CertSrvBackupGetBackupLogs have been secured.

Syntax
HRESULT CERTBCLI_API CertSrvBackupTruncateLogs(
[in] HCSBC hbc
);

Parameters
[in] hbc

A handle to a Certificate Services backup context.

Return value
The return value is an HRESULT . A value of S_OK indicates success.

Remarks
After securing a backup of the database and log files, the log files can optionally be truncated. Log file volume
increases with database activity, and truncating the log files will reduce the redundant records in the log files
(thereby decreasing the disk space used to store the log files).
The log files are provided for database integrity and efficiency. If a less-than-graceful exit occurs with the
Certificate Services application, the next time Certificate Services is started, the database replays the log files to
prevent data corruption from being introduced into the database.
Depending on the volume of the log files, the log file replay can be a time-consuming process. During this
replay, the certification authority will be unavailable for other activity. Note that if the Certificate Services
application is properly halted (such as by stopping the service or by shutting down the operating system
properly), the log files are not replayed the next time it is started.

Note If you call Cer tSr vBackupTruncateLogs without backing up all files returned from
CertSrvBackupGetDatabaseNames and CertSrvBackupGetBackupLogs, you will not be able to restore the backup set
successfully, resulting in an unusable Certificate Services machine. Therefore, call Cer tSr vBackupTruncateLogs only when
the backup set contains all files returned from Cer tSr vBackupGetDatabaseNames and Cer tSr vBackupGetBackupLogs .

Examples
 FNCERTSRVBACKUPTRUNCATELOGS* pfnTruncateLogs;
char * szTruncateLogsFunc = "CertSrvBackupTruncateLogs";

HRESULT hr=0;

// Get the address for the desired function.

// hInst was set by calling LoadLibrary for Certadm.dll.
pfnTruncateLogs = (FNCERTSRVBACKUPTRUNCATELOGS*)GetProcAddress( hInst,
szTruncateLogsFunc );
if ( NULL == pfnTruncateLogs )
{
printf("Failed GetProcAddress - %s, error=%d\n",
szTruncateLogsFunc,
GetLastError() );
exit(1); // Or other appropriate error action.
}

// After they have been backed up, truncate the logs.

// hCSBC is a previously set HCSBC variable.
hr = pfnTruncateLogs(hCSBC);
if (FAILED(hr))
{
printf("Failed pfnTruncateLogs call [%x]\n", hr);
exit(1); // Or other appropriate error action.
}
else
printf("Logs truncated\n");

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header certbcli.h (include Certsrv.h)

Librar y Certadm.lib

DLL Certadm.dll

See also
CertSrvBackupGetBackupLogs
Using the Certificate Services Backup and Restore Functions
 CertSrvIsServerOnlineW function (certbcli.h)
7/2/2022 • 2 minutes to read • Edit Online

The Cer tSr vIsSer verOnline function determines if a Certificate Services server is online; if the Certificate
Services server is not online, backup operations will not be successful.

Syntax
HRESULT CERTBCLI_API CertSrvIsServerOnlineW(
[in] WCHAR const *pwszServerName,
[out] BOOL *pfServerOnline
);

Parameters
[in] pwszServerName

A pointer to the NetBIOS or DNS machine name of the server to check for online status.
[out] pfServerOnline

A pointer to Boolean value which will be TRUE if the Certificate Services server is online and FALSE if it is not
online.

Return value
The return value is an HRESULT . This function will fail if Certificate Services is not running. If Certificate
Services is running and ready to accept requests, this function will return S_OK, and *pfServerOnline will point
to a value of TRUE . If Certificate Services is running in suspended (or paused) mode, this function will return
S_OK, and *pfServerOnline will point to a value of FALSE .

Remarks
Call this function to determine whether a Certificate Services server is online and available for backup
operations.
This function's name in Certadm.dll is Cer tSr vIsSer verOnlineW . You must use this form of the name when
calling GetProcAddress. Also, this function is defined as type FNCERTSRVISSERVERONLINEW in the
Certbcli.h header file.
Examples
 FNCERTSRVISSERVERONLINEW* pfnOnline = NULL;
char * szOnlineFunc = "CertSrvIsServerOnlineW";
BOOL bOnline = 0;
HRESULT hr = 0;

// Get the address of the function.

// hInst was set by calling LoadLibrary for Certadm.dll.
pfnOnline = (FNCERTSRVISSERVERONLINEW*) GetProcAddress(hInst,
szOnlineFunc );
if ( NULL == pfnOnline )
{
printf("Failed GetProcAddress - %s, error=%d\n",
szOnlineFunc,
GetLastError() );
exit(1); // Or other appropriate error action.
}

// Call the function; wszServer was set earlier to the server name.
hr = pfnOnline(wszServer, &bOnline);
if (FAILED(hr))
{
printf("Failed pfnOnline, hr=%x, err=%d\n",
hr,
GetLastError());
exit(1); // Or other appropriate error action.
}

// Display the online status.

printf("Server is %s\n",
(bOnline ? "Online" : "Suspended" ));

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header certbcli.h (include Certsrv.h)

Librar y Certadm.lib

DLL Certadm.dll

See also
CertSrvBackupPrepare
Using the Certificate Services Backup and Restore Functions
 CertSrvRestoreEnd function (certbcli.h)
7/2/2022 • 2 minutes to read • Edit Online

The Cer tSr vRestoreEnd function ends a Certificate Services restore session.

Syntax
HRESULT CERTBCLI_API CertSrvRestoreEnd(
[in] HCSBC hbc
);

Parameters
[in] hbc

A handle to a Certificate Services backup context.

Return value
The return value is an HRESULT . A value of S_OK indicates success.

Remarks
When a restore session is complete, terminate the session by calling Cer tSr vRestoreEnd . For every successful
call to CertSrvRestorePrepare, there should be a call to Cer tSr vRestoreEnd .
When a restore is complete, it is important that you make a new full backup of the Certificate Services database.
This is necessary to truncate the restored log files and to establish a base backup set for future restores. Backups
performed after a restore cannot be mixed with backups (full or incremental) taken before the restore; that is,
after a certificate services database is restored and has progressed to a subsequent state, you cannot use the
pre-restoration backups to restore the database to that subsequent state.
Examples
 FNCERTSRVRESTOREEND* pfnRestoreEnd;
char * szRestoreEndFunc = "CertSrvRestoreEnd";
HRESULT hr=0;

// Get the address for the desired function.

// hInst was set by calling LoadLibrary for Certadm.dll.
pfnRestoreEnd = (FNCERTSRVRESTOREEND*)GetProcAddress(hInst,
szRestoreEndFunc);
if ( NULL == pfnRestoreEnd )
{
printf("Failed GetProcAddress - %s, error=%d\n",
szRestoreEndFunc,
GetLastError() );
exit(1); // Or other appropriate error action.
}

// When done, release the HCSBC.

// hCSBC would have been set by an earlier call
// to CertSrvRestorePrepare.
hr = pfnRestoreEnd(hCSBC);
if (FAILED(hr))
{
printf("Failed pfnRestoreEnd call [%x]\n", hr);
exit(1); // Or other appropriate error action.
}

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header certbcli.h (include Certsrv.h)

Librar y Certadm.lib

DLL Certadm.dll

See also
CertSrvRestorePrepare
Using the Certificate Services Backup and Restore Functions
 CertSrvRestoreGetDatabaseLocationsW function
(certbcli.h)
7/2/2022 • 2 minutes to read • Edit Online

The Cer tSr vRestoreGetDatabaseLocations function is used both in backup and restore scenarios and
retrieves the list of Certificate Services database location names for all the files being backed up or restored.

Syntax
HRESULT CERTBCLI_API CertSrvRestoreGetDatabaseLocationsW(
[in] HCSBC hbc,
[out] PWSTR *ppwszzDatabaseLocationList,
[out] DWORD *pcbSize
);

Parameters
[in] hbc

A handle to a Certificate Services backup or restore context.

[out] ppwszzDatabaseLocationList

A pointer to a WCHAR pointer to receive the list of null-terminated database location names, log directory
name, and system (or checkpoint) directory name. There is a null character after every name and an extra null
character at the end of the list. The location name will be in the UNC form "## \\Server\SharePoint\…Path…\
FileName.ext". The directory names will have the same form but without the trailing "\FileName.ext". The text
"##" denotes a Certificate Services Backup file type (CSBFT_*) and is stored as a single non-null Unicode
character prefixed onto each UNC path. The type tag is defined in Certbcli.h and can be one of the following
values for this function.

VA L UE M EA N IN G

Certificate Services database file name including path.

CSBFT_CERTSERVER_DATABASE

Certificate Services database system (or checkpoint)

CSBFT_CHECKPOINT_DIR directory.

Certificate Services database log directory.

CSBFT_LOG_DIR

You must free this allocated memory when done by calling CertSrvBackupFree.
Setting *ppwszzDatabaseLocationList to NULL before calling this function is optional.
[out] pcbSize

A pointer to the DWORD value that specifies the number of bytes in ppwszzDatabaseLocationList.
Return value
The return value is an HRESULT . A value of S_OK indicates success.

Remarks
Certificate Services must be running for this method to succeed.
This function's name in Certadm.dll is Cer tSr vRestoreGetDatabaseLocationsW . You must use this form of
the name when calling GetProcAddress. Also, this function is defined as type
FNCERTSRVRESTOREGETDATABASELOCATIONSW in the Certbcli.h header file.
Examples

FNCERTSRVRESTOREGETDATABASELOCATIONSW* pfnGetDBLocs;
char * szGetDBLocsFunc = "CertSrvRestoreGetDatabaseLocationsW";
WCHAR * pwszzDBLocs;
DWORD nListBytes=0;
HRESULT hr=0;

// Get the address for the desired function.

// hInst was set by calling LoadLibrary for Certadm.dll.
pfnGetDBLocs = (FNCERTSRVRESTOREGETDATABASELOCATIONSW*)
GetProcAddress(hInst, szGetDBLocsFunc);
if ( NULL == pfnGetDBLocs )
{
printf("Failed GetProcAddress - %s, error=%d\n",
szGetDBLocsFunc,
GetLastError() );
exit(1); // Or other appropriate error action.
}

// Determine the names of the database locations.

// hCSBC was set by an earlier call to CertSrvRestorePrepare.
hr = pfnGetDBLocs(hCSBC, &pwszzDBLocs, &nListBytes);
if (FAILED(hr))
{
printf("Failed pfnGetDBLocs call [%x]\n", hr);
exit(1); // Or other appropriate error action.
}
else
{
printf("%d bytes for DB locations\n", nListBytes);
WCHAR * pwszFile = pwszzDBLocs;
// Process the list.
while ( L'\0' != *pwszFile )
{
// Use the file name referenced by pwszFile.
// Here it is merely displayed.
printf("%02x: %ws\n", *pwszFile, &pwszFile[1]);
// Move to the next database file name.
// + 1 moves past the null terminator.
pwszFile+=(wcslen(pwszFile)) + 1;
}
// Free the allocated memory.
// pfnBackupFree is the address of the
// CertSrvBackupFree function.
pfnBackupFree(pwszzDBLocs);
}

Requirements
 Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header certbcli.h (include Certsrv.h)

Librar y Certadm.lib

DLL Certadm.dll

See also
CertSrvBackupFree
Using the Certificate Services Backup and Restore Functions
 CertSrvRestorePrepareW function (certbcli.h)
7/2/2022 • 2 minutes to read • Edit Online

The Cer tSr vRestorePrepare function prepares a Certificate Services instance for restore operations.

Syntax
HRESULT CERTBCLI_API CertSrvRestorePrepareW(
[in] WCHAR const *pwszServerName,
[in] ULONG dwRestoreFlags,
[out] HCSBC *phbc
);

Parameters
[in] pwszServerName

A pointer to the computer name of the server to prepare for restore operations. This name can be the NetBIOS
name or the DNS name.
[in] dwRestoreFlags

A bitfield that represents the combination of values in the following table.

VA L UE M EA N IN G

Restore Certificate Services database, logs, and related files.

CSRESTORE_TYPE_FULL

[out] phbc

A pointer to a Certificate Services backup context handle (HCSBC ).

Return value
The return value is an HRESULT . A value of S_OK indicates success, and *phbc is set to an HCSBC , which can be
used by other Certificate Services restore APIs.

Remarks
Before a Certificate Services restore operation can occur, it is necessary to create an HCSBC by means of
Cer tSr vRestorePrepare . This HCSBC can be used by various Certificate Services restore functions.

Note When the restore session is completed, it is necessary to call CertSrvRestoreEnd to release the HCSBC which resulted
from the call to Cer tSr vRestorePrepare .

This function's name in Certadm.dll is Cer tSr vRestorePrepareW . You must use this form of the name when
calling GetProcAddress. Also, this function is defined as type FNCERTSRVRESTOREPREPAREW in the Certbcli.h
header file.
To execute this call, you must have the restore privilege. For more information, see Setting the Backup and
Restore Privileges.
Examples

FNCERTSRVRESTOREPREPAREW* pfnRestorePrepare;
char * szRestorePrepFunc = "CertSrvRestorePrepareW";
HCSBC hCSBC=NULL;
HINSTANCE hInst=0;
HRESULT hr=0;

// Load the DLL.

hInst = LoadLibrary(L"Certadm.dll");
if ( NULL == hInst )
{
printf("Failed LoadLibrary,error=%d\n",
GetLastError() );
exit(1); // Or other appropriate error action.
}

// Get the address for the desired function.

pfnRestorePrepare = (FNCERTSRVRESTOREPREPAREW*)GetProcAddress( hInst,
szRestorePrepFunc );
if ( NULL == pfnRestorePrepare )
{
printf("Failed GetProcAddress - %s, error=%d\n",
szRestorePrepFunc,
GetLastError() );
exit(1); // Or other appropriate error action.
}

// Prepare CertServ for restoration.

hr = pfnRestorePrepare(wszServer,
CSRESTORE_TYPE_FULL,
&hCSBC);

if (FAILED(hr))
{
printf("Failed pfnRestorePrepare call [%x]\n", hr);
exit(1); // Or other appropriate error action.
}

// Use the HCSBC for restore operations.

// ...

// When done processing, release the HCSBC context

// by calling CertSrvRestoreEnd (not shown here).
// ...

// Free the DLL.

if (hInst)
FreeLibrary(hInst);

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

 Header certbcli.h (include Certsrv.h)

Librar y Certadm.lib

DLL Certadm.dll

See also
CertSrvRestoreEnd
GetProcAddress
Setting the Backup and Restore Privileges
Using the Certificate Services Backup and Restore Functions
 CertSrvRestoreRegisterComplete function
(certbcli.h)
7/2/2022 • 2 minutes to read • Edit Online

The Cer tSr vRestoreRegisterComplete function completes a registered Certificate Services restore operation.

Syntax
HRESULT CERTBCLI_API CertSrvRestoreRegisterComplete(
[in] HCSBC hbc,
[in] HRESULT hrRestoreState
);

Parameters
[in] hbc

A handle to a Certificate Services restore context. You must set this handle by calling CertSrvRestoreRegister
before using it in Cer tSr vRestoreRegisterComplete .
[in] hrRestoreState

HRESULT value indicating the success code for the restore operation. Set this value to S_OK if the restore
operation was successful.

Return value
The return value is an HRESULT . A value of S_OK indicates success.

Remarks
If a registered restore operation is not completed, Certificate Services will not start.
Examples
 FNCERTSRVRESTOREREGISTERCOMPLETE* pfnRestRegComplete;
char * szResRegCompleteFunc = "CertSrvRestoreRegisterComplete";
HRESULT hr=0;

// Get the address for the desired function.

// hInst was set by calling LoadLibrary for Certadm.dll.
pfnRestRegComplete = (FNCERTSRVRESTOREREGISTERCOMPLETE*)
GetProcAddress( hInst, szResRegCompleteFunc );
if ( NULL == pfnRestRegComplete )
{
printf("Failed GetProcAddress - %s, error=%d\n",
szResRegCompleteFunc,
GetLastError() );
exit(1); // Or other appropriate error action.
}

// Complete a registered restoration operation.

// hCSBC is an HCSBC variable used in a previous
// call to CertSrvRestoreRegister.
hr = pfnRestRegComplete(hCSBC, S_OK);
if (FAILED(hr))
{
printf("Failed pfnRestRegComplete call [%x]\n", hr);
exit(1); // Or other appropriate error action.
}

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header certbcli.h (include Certsrv.h)

Librar y Certadm.lib

DLL Certadm.dll

See also
CertSrvRestoreRegister
Using the Certificate Services Backup and Restore Functions
 CertSrvRestoreRegisterThroughFile function
(certbcli.h)
7/2/2022 • 2 minutes to read • Edit Online

The Cer tSr vRestoreRegisterThroughFile function registers a Certificate Services restore.

Syntax
HRESULT CERTBCLI_API CertSrvRestoreRegisterThroughFile(
[in] HCSBC hbc,
[in, optional] WCHAR const *pwszCheckPointFilePath,
[in, optional] WCHAR const *pwszLogPath,
[in, optional] CSEDB_RSTMAPW [] rgrstmap,
[in] LONG crstmap,
[in, optional] WCHAR const *pwszBackupLogPath,
[in] ULONG genLow,
[in] ULONG genHigh
);

Parameters
[in] hbc

A handle to the Certificate Services restore context. This handle is obtained by calling the CertSrvRestorePrepare
function.
[in, optional] pwszCheckPointFilePath

A pointer to a null-terminated Unicode string that contains the restore path for the check point file. Pass NULL
for this parameter if it is not needed.
[in, optional] pwszLogPath

A pointer to a null-terminated Unicode string that contains the current log file directory. Pass NULL for this
parameter if it is not needed.
[in, optional] rgrstmap

An array of CSEDB_RSTMAP structures that contains the restore map. If you are performing a full database
restoration, this parameter specifies the name of the backup database, as well as a new name for the database
after it is restored. The backup database name is referenced by the pwszDatabaseName member, and the new
database name is referenced by the pwszNewDatabaseName member. If the intent is to maintain the same
name for both the backup database and the restored database, set both the pwszNewDatabaseName and the
pwszDatabaseName members to the same name. The backup database name is constructed from the path
returned by the backup client's call to the CertSrvRestoreGetDatabaseLocations function.
Cer tSr vRestoreGetDatabaseLocations would have been called during a full backup, and the backup client
would have saved the returned path.
If you are performing an incremental restoration, set this parameter to NULL .
[in] crstmap

The number of elements in the rgrstmap array. Set this value to one if a you are performing a full restoration, or
zero if you are performing an incremental restoration.
[in, optional] pwszBackupLogPath

A pointer to a null-terminated Unicode string that contains the path for the backup log directory. Pass NULL for
this parameter if it is not needed.
[in] genLow

The lowest log number that was restored in this restore session. Log files are in the form of edbXXXXX.log,
where XXXXX is a five hexadecimal digit value. For example, edb00001.log is the first log file created by the
internal database. For purposes of this function, a value of one in genLow corresponds to the log file
edb00001.log.
[in] genHigh

The highest log number that was restored in this restore session.

Return value
The return value is an HRESULT . A value of S_OK indicates success.

Remarks
This function is identical to the CertSrvRestoreRegister function except that Cer tSr vRestoreRegister requires
the calling account to be a local administrator. The Cer tSr vRestoreRegisterThroughFile function only
requires that the calling account have the restore privilege.

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header certbcli.h (include Certsrv.h)

Librar y Certadm.lib

DLL Certadm.dll

See also
CertSrvRestoreRegister
CertSrvRestoreRegisterComplete
Using the Certificate Services Backup and Restore Functions
 CertSrvRestoreRegisterW function (certbcli.h)
7/2/2022 • 3 minutes to read • Edit Online

The Cer tSr vRestoreRegister function registers a Certificate Services restore.

Syntax
HRESULT CERTBCLI_API CertSrvRestoreRegisterW(
[in] HCSBC hbc,
[in] WCHAR const *pwszCheckPointFilePath,
[in] WCHAR const *pwszLogPath,
[in] CSEDB_RSTMAPW [] rgrstmap,
[in] LONG crstmap,
[in] WCHAR const *pwszBackupLogPath,
[in] ULONG genLow,
[in] ULONG genHigh
);

Parameters
[in] hbc

A handle to the Certificate Services restore context. This handle is obtained by calling the CertSrvRestorePrepare
function.
[in] pwszCheckPointFilePath

A pointer to a null-terminated Unicode string that contains the restore path for the check point file. Pass NULL
for this parameter if it is not needed.
[in] pwszLogPath

A pointer to a null-terminated Unicode string that contains the current log file directory. Pass NULL for this
parameter if it is not needed.
[in] rgrstmap

An array of CSEDB_RSTMAP structures that contains the restore map. If you are performing a full database
restoration, this parameter specifies the name of the backup database, as well as a new name for the database
after it is restored. The backup database name is referenced by the pwszDatabaseName member, and the new
database name is referenced by the pwszNewDatabaseName member. If the intent is to maintain the same
name for both the backup database and the restored database, set both the pwszNewDatabaseName and the
pwszDatabaseName members to the same name. The backup database name is constructed from the path
returned by the backup client's call to the CertSrvRestoreGetDatabaseLocations function.
Cer tSr vRestoreGetDatabaseLocations would have been called during a full backup, and the backup client
would have saved the returned path.
If you are performing an incremental restoration, pass NULL for this parameter.
[in] crstmap

The number of elements in the rgrstmap array. Pass zero for this parameter if you are performing an
incremental restoration.
[in] pwszBackupLogPath

A pointer to a null-terminated Unicode string that contains the path for the backup log directory. Pass NULL for
this parameter if it is not needed.
[in] genLow

The lowest log number that was restored in this restore session. Log files are in the form of edbXXXXX.log,
where XXXXX is a five hexadecimal digit value. For example, edb00001.log is the first log file created by the
internal database. For purposes of this function, a value of one in genLow corresponds to the log file
edb00001.log.
[in] genHigh

The highest log number that was restored in this restore session.

Return value
The return value is an HRESULT . A value of S_OK indicates success.

Remarks
Use this function to register a restore operation. All subsequent restore operations will be interlocked. The
restore target will be prevented from starting (or successfully executing another call to
Cer tSr vRestoreRegister ) until CertSrvRestoreRegisterComplete is called.
When restoring more than one incremental backup, the order in which the incremental backups are registered
does not matter. However, the full database backup must be registered before registering the incremental
backups.
This function requires that the calling account be a local administrator. If this is not practical, use the
CertSrvRestoreRegisterThroughFile function instead. The Cer tSr vRestoreRegisterThroughFile function only
requires that the calling account have the restore privilege.
Examples
 // szMyDBName is the returned path from the backup client's
// call to CertSrvRestoreGetDatabaseLocations. This value would
// have been saved during a full backup operation.
CSEDB_RSTMAP rgrstmap[1] =
{
szMyDBName, // database name
szMyDBName // new name same as old
};

HRESULT hr = 0;

// Register a restore operation.

// hsb is an HCSBC created previously by CertSrvRestorePrepare.
hr = CertSrvRestoreRegister(
hsb,
NULL,
szMyRestoreLogPath, // defined elsewhere
rgrstmap,
1,
szMyBackupLogPath, // defined elsewhere
1, // edb00001.log
0x1a // edb0001a.log
);

if (S_OK != hr)
{
printf("Failed CertSrvRestoreRegister - %x\n", hr);
exit(1); // Or other appropriate error action.
}

// Continue processing.
// When done, call CertSrvRestoreRegisterComplete (not shown).
// ...

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header certbcli.h (include Certsrv.h)

Librar y Certadm.lib

DLL Certadm.dll

See also
CertSrvRestoreRegisterComplete
CertSrvRestoreRegisterThroughFile
Using the Certificate Services Backup and Restore Functions
 CertSrvServerControlW function (certbcli.h)
7/2/2022 • 2 minutes to read • Edit Online

The Cer tSr vSer verControl function issues a service control command to programmatically stop Certificate
Services.

Syntax
HRESULT CERTBCLI_API CertSrvServerControlW(
[in] WCHAR const *pwszServerName,
[in] DWORD dwControlFlags,
[out] DWORD *pcbOut,
[out] BYTE **ppbOut
);

Parameters
[in] pwszServerName

A pointer to a name or a configuration string of the server to be issued the control command.
[in] dwControlFlags

Value representing the control command being issued to the Certificate Services server specified by
pwszServerName. The following value is supported for dwControlFlags.

VA L UE M EA N IN G

Stop Certificate Services.

CSCONTROL_SHUTDOWN

[out] pcbOut

For future use, this parameter will be the number of bytes allocated to ppbOut. The current implementation
does not allocate memory to ppbOut. You can set this value to NULL .
[out] ppbOut

For future use, this parameter will be the pointer to pointer to bytes representing the output from the issued
command. The current implementation does not allocate memory to ppbOut. You can set this value to NULL .

Return value
The return value is an HRESULT . A value of S_OK indicates success.

Remarks
The purpose of this function is to allow a backup or restore application to programmatically stop the Certificate
Services application (thereby not requiring the use of the service controller APIs). Stopping Certificate Services
in this manner will also work when Certificate Services is running in console mode; the service controller APIs
cannot control applications running in console mode.
This function's name in Certadm.dll is Cer tSr vSer verControlW . You must use this form of the name when
calling GetProcAddress. Also, this function is defined as type FNCERTSRVSERVERCONTROLW in the
Certbcli.h header file.
Examples

FNCERTSRVSERVERCONTROLW* pfnControl;
char * szControlFunc = "CertSrvServerControlW";
HRESULT hr=0;

// Get the address for the desired function.

// hInst was set by calling LoadLibrary for Certadm.dll.
pfnControl = (FNCERTSRVSERVERCONTROLW*)GetProcAddress(hInst,
szControlFunc);
if ( NULL == pfnControl )
{
printf("Failed GetProcAddress - %s, error=%d\n",
szControlFunc,
GetLastError() );
exit(1); // Or other appropriate error action.
}

// Issue a command to stop the service.

hr = pfnControl( L"MyCertServMachine",
CSCONTROL_SHUTDOWN,
NULL,
NULL);

if ( FAILED( hr ) )
{
printf("Failed pfnControl call [%x]\n", hr);
exit(1); // Or other appropriate error action.
}

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header certbcli.h (include Certsrv.h)

Librar y Certadm.lib

DLL Certadm.dll

See also
Using the Certificate Services Backup and Restore Functions
 certcli.h header
7/2/2022 • 2 minutes to read • Edit Online

This header is used by Security and Identity. For more information, see:
Security and Identity
certcli.h contains the following programming interfaces:

Interfaces

ICertConfig

The ICertConfig interface provides functionality for retrieving the public configuration data (specified during client setup) for a
Certificate Services server.

ICertConfig2

Provide functionality for retrieving the public configuration data (specified during client setup) for a Certificate Services server.

ICertGetConfig

Provides functionality for retrieving the public configuration data (specified during client setup) for a Certificate Services server.

ICertRequest

Provides communications between a client or intermediary application and Certificate services.

ICertRequest2

Provide communications between a client or intermediary application and Certificate Services.

ICertRequest3

Provide communications between a client or intermediary application and Certificate Services.

Enumerations

X509EnrollmentAuthFlags

Specifies the authentication type.

 ICertConfig interface (certcli.h)
7/2/2022 • 2 minutes to read • Edit Online

The ICer tConfig interface provides functionality for retrieving the public configuration data (specified during
client setup) for a Certificate Services server.
The ICer tConfig interface is used to perform the following tasks:
Enumerate through the configuration strings for a Certificate Services server in the configuration point.
Retrieve the default configuration for a Certificate Services server.
Retrieve the details of a specific Certificate Services server configuration.
Reset the configuration of a Certificate Services server.
For each installation of Certificate Services, this public configuration data resides in the Certsrv.txt file, which
exists in the shared folder, the Active Directory, or both. Any server set up to post its configuration information
in Certsrv.txt is visible to ICer tConfig .
ICer tConfig is defined in Certcli.h. When you create your program, however, use Certsrv.h as the include file.
Certcli.dll provides the ICer tConfig interface. The type information for this interface is also in Certclil.dll, which
is shipped with the Platform Software Development Kit (SDK).
Certificate Services interfaces support both apartment-threading and free-threading models. For better
throughput, free threading is recommended.

Inheritance
The ICer tConfig interface inherits from the IDispatch interface. ICer tConfig also has these types of members:

Methods
The ICer tConfig interface has these methods.

ICertConfig::GetConfig

Retrieves the configuration string for a Certificate Services server. This method was first defined in the ICertConfig interface.

ICertConfig::GetField

Gets a specific field from the current record of the configuration database. This method was first defined in the ICertConfig
interface.

ICertConfig::Next

Retrieves the index of the next available Certificate Services server configuration in the configuration point. This method was
first defined in the ICertConfig interface.

ICertConfig::Reset

Resets the configuration query state to point at the Certificate Services server configuration indexed on the specified
configuration point. This method was first defined in the ICertConfig interface.
Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header certcli.h (include Certsrv.h)

 ICertConfig::GetConfig method (certcli.h)
7/2/2022 • 4 minutes to read • Edit Online

The GetConfig method retrieves the configuration string for a Certificate Services server. This method was first
defined in the ICertConfig interface.
The configuration string is the server name and certification authority name separated by a backslash (); for
example: ServerName\ CAName. This configuration string can be used to refer unambiguously to a specific
Certificate Services server. For more information, see Remarks.

Syntax
HRESULT GetConfig(
[in] LONG Flags,
[out] BSTR *pstrOut
);

Parameters
[in] Flags

Value that specifies the certification authority to use. This parameter can be one of the following values.

VA L UE M EA N IN G

Retrieves the default certification authority.

CC_DEFAULTCONFIG
0x00000000

Returns the first certification authority.

CC_FIRSTCONFIG
0x00000002

Retrieves the local certification authority if it is running.

CC_LOCAL ACTIVECONFIG
0x00000004

Retrieves the local certification authority.

CC_LOCALCONFIG
0x00000003

Displays a user interface that allows the user to select a

CC_UIPICKCONFIG certification authority.
0x00000001
 Displays a user interface that allows the user to select a
CC_UIPICKCONFIGSKIPLOCALCA certification authority. The UI excludes any local certification
0x00000005 authority. This exclusion is useful during subordinate
certification authority certificate renewal when the
subordinate certification authority certificate request is
submitted to a certification authority other than the current
certification authority.

[out] pstrOut

A pointer to a BSTR that contains the configuration. When you have finished using the configuration, call the
SysFreeString function to free pbstrOut.

Return value
C++
If the method succeeds, the method returns S_OK.
If the method fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.
VB
The return value is a string that contains the configuration.

Remarks
The certification authority (CA) name portion of the configuration string that this function returns is the exact
text entered during the Certificate Services setup process. Note that this text may be different from the form of
the CA name found in file names (such as for the certificate revocation list) or in registry keys. This is because
file names and registry keys use a sanitized version of the CA name.
The process of sanitizing the CA name is necessary to remove characters that are illegal for file names, registry
key names, or distinguished name values, or illegal for reasons specific to Certificate Services. In the sanitizing
process, any illegal character in the common name is converted to a five-character representation in the format
! xxxx, where ! is used as an escape character and xxxx represents four hexadecimal digits that uniquely identify
the character to be converted.
For example, the number sign (#) is not allowed in distinguished names in Active Directory. If the CA name
entered during setup is # YourName, the sanitized CA name will be !0023 YourName.
The following characters, if entered for the common name of the CA during setup, are converted to the ! xxxx
format during the sanitizing process. This list is subject to change.

NAME C H A RA C T ER VA L UE IN !XXXX F O RM AT

Ampersand & !0026

Apostrophe ' !0027

Asterisk * !002a

Backslash \ !005c

Left brace { !007b

Right brace } !007d

 Left bracket [ !005b

Right bracket ] !005d

Caret ^ !005e

Colon : !003a

Comma , !002c

Equal sign = !003d

Exclamation point ! !0021

Grave accent ` !0060

Greater than sign > !003e

Less than sign < !003c

Number sign # !0023

Opening parenthesis ( !0028

Closing parenthesis ) !0029

Percent % !0025

Pipe | !007c

Plus sign + !002b

Question mark ? !003f

Quotation mark " !0022

Semicolon ; !003b

Slash mark / !002f

Any nonprinting character and all Unicode characters that are not seven bits are also converted to the ! xxxx
format.
A sanitized short name is generated when the sanitized name is too long for a 64-character directory services
relative distinguished name (RDN). The sanitized short name consists of the sanitized name truncated and
appended with a hash of the full sanitized name. The sanitized short name reserves some of the 64 characters to
contain certificate revocation list (CRL) suffixes, such as (123).
The certification authority name portion of the configuration string returned by this method is the original text
entered during setup. Note that Certificate Services methods that require a certification authority name as a
parameter accept the originally entered certification authority name. For example, for the certification authority
name # YourName, the
ICertView2::OpenConnection method accepts # YourName as the parameter's certification authority portion.
Examples
The following example shows how to use this method to retrieve the default certification authority configuration
string.

ICertConfig2 * pConfig = NULL;

BSTR bstrConfig = NULL; //Contains CA configuration name
HRESULT hr;

hr = CoInitializeEx(NULL, COINIT_APARTMENTTHREADED);
if (FAILED(hr))
{
printf("Failed CoInitializeEx - [%x]\n", hr);
goto error;
}

// Create an instance of the CertConfig object.

hr = CoCreateInstance( CLSID_CCertConfig,
NULL,
CLSCTX_INPROC_SERVER,
IID_ICertConfig2,
(void **)&pConfig);
if (FAILED(hr))
{
printf("Failed CoCreateInstance - pConfig [%x]\n", hr);
goto error;
}

// Retrieve the default CA configuration string.

hr = pConfig->GetConfig(CC_DEFAULTCONFIG, &bstrConfig);
if (FAILED(hr))
{
printf("Failed GetConfig - [%x]\n", hr);
goto error;
}
else
printf("GetConfig returned: %ws\n", bstrConfig );

error:

// Done processing.
if (pConfig)
pConfig->Release();

if (bstrConfig)
SysFreeString(bstrConfig);

CoUninitialize();

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

 Header certcli.h (include Certsrv.h)

Librar y Certidl.lib

DLL Certcli.dll

See also
CCertConfig
ICertConfig
ICertView2::OpenConnection
 ICertConfig::GetField method (certcli.h)
7/2/2022 • 2 minutes to read • Edit Online

The GetField method gets a specific field from the current record of the configuration database. This method
was first defined in the ICertConfig interface.

Syntax
HRESULT GetField(
[in] const BSTR strFieldName,
[out, retval] BSTR *pstrOut
);

Parameters
[in] strFieldName

Specifies the name of the field to return. This parameter can be one of the following valid strings for field names
(note that some certification authorities may not provide data for each field).

VA L UE M EA N IN G

Reference certification authority (CA) name.

Authority

Common name of the server.

CommonName

Reference computer\CA name.

Config

Country/region.
Countr y

Descriptive comment about the server (replaces obsolete

Description "Comment").

Name of the file that contains the exchange certificate

ExchangeCer tificate (applies to Certificate Services 1.0 only).

String that represents the location where the CA information

Flags was found. For more information, see Remarks.

City or town.
Locality

Organization.
Organization
 Organizational unit.
OrgUnit

CA name that is sanitized according to the rules described in

SanitizedName GetConfig.

CA name that is sanitized and shortened according to the

SanitizedShor tName rules described in GetConfig.

Reference computer name.

Ser ver

SanitizedShortName, but with the '!xxx' sequences, as

Shor tName described in GetConfig, translated back into the original text.

Name of the file that contains the CA certificate (also known

SignatureCer tificate as the CA signature certificate); this may or may not be a
root certificate.

State or province.
State

An array of certificate enrollment Web service URLs for a

WebEnrollmentSer vers specific CA configuration in the Active Directory.
Windows Vista and Windows Storage
Ser ver 2003: This field is not supported.

[out, retval] pstrOut

A pointer to a BSTR that receives the data from the field. When you have finished using the BSTR , free pbstrOut
by calling the SysFreeString function.

Return value
C++
If the method succeeds, the method returns S_OK.
If the method fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.
VB
The return value is a string that represents the data for the field.

Remarks
This method returns the field data for the specified field.
When you specify "Flags" in the strFieldName parameter, the retrieved data for the flags field is a string that can
be converted to an integer by means of the C-library function _wtoi . The resulting integer represents a bitfield
that can be examined to determine whether the flags CAIF_DSENTRY and CAIF_SHAREDFOLDERENTRY are set.
If CAIF_DSENTRY (0x00000001) is set, the information for the CA was contained in Directory Services. If
CAIF_SHAREDFOLDERENTRY (0x00000002) is set, the information for the CA was contained in the shared folder.
Note that one or both of these flags may be set.
Examples

BSTR bstrFieldName = NULL;

BSTR bstrFieldValue = NULL;
HRESULT hr;

// Specify the field to retrieve, for example, "CommonName".

bstrFieldName = SysAllocString(L"<FIELDNAMEHERE>");
if (NULL == bstrFieldName)
{
printf("Memory allocation failed for bstrFieldName.\n");
goto error;
}

// pConfig is a previously instantiated ICertConfig object.

hr = pConfig->GetField(bstrFieldName, &bstrFieldValue);
if (FAILED(hr))
{
printf("Failed GetField - [%x]\n", hr);
goto error;
}
else
printf("GetField value for %ws is: %ws\n",
bstrFieldName, bstrFieldValue );

error:

if (bstrFieldName)
SysFreeString(bstrFieldName);

if (bstrFieldValue)
SysFreeString(bstrFieldValue);

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header certcli.h (include Certsrv.h)

Librar y Certidl.lib

DLL Certcli.dll

See also
CCertConfig
ICertConfig
 ICertConfig::Next method (certcli.h)
7/2/2022 • 2 minutes to read • Edit Online

The Next method retrieves the index of the next available Certificate Services server configuration in the
configuration point. This method was first defined in the ICertConfig interface.

Syntax
HRESULT Next(
[out] LONG *pIndex
);

Parameters
[out] pIndex

A pointer to a Long variable that will contain the index of the enumerated configuration, or –1 if there are no
more configurations to enumerate.

Return value
C++
If the method succeeds, the method returns S_OK, and the pIndex parameter contains the index of the enumerated
configuration. If there are no more configurations to enumerate, the return value is S_FALSE, and the pIndex
parameter points to a value of –1.
If the method fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.
VB
Returns a value that specifies the index of the next available Certificate Services server configuration in the
configuration point. If no more configurations are available, the method returns a value of –1.

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header certcli.h (include Certsrv.h)

Librar y Certidl.lib

DLL Certcli.dll
See also
ICertConfig
ICertConfig2
Reset
 ICertConfig::Reset method (certcli.h)
7/2/2022 • 2 minutes to read • Edit Online

The Reset method resets the configuration query state to point at the Certificate Services server configuration
indexed on the specified configuration point. This method was first defined in the ICertConfig interface.
Each individual configuration indicates a specific Certificate Services server. Some Certificate Services servers
may have multiple valid configurations in the configuration database.

Syntax
HRESULT Reset(
[in] LONG Index,
[out] LONG *pCount
);

Parameters
[in] Index

Specifies the configuration point used by the configuration query to index a Certificate Services server
configuration. The first configuration is index zero.
[out] pCount

A pointer to the number of configurations in the enterprise.

Return value
C++
If the method succeeds, the method returns S_OK, and the pCount parameter points to a Long that contains the
number of configurations in the enterprise.
If the method fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.
VB
The return value is the number of configurations in the enterprise.

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header certcli.h (include Certsrv.h)

 Librar y Certidl.lib

DLL Certcli.dll

See also
ICertConfig
ICertConfig2
Next
 ICertConfig2 interface (certcli.h)
7/2/2022 • 2 minutes to read • Edit Online

The ICer tConfig2 interface is one of two interfaces that provide functionality for retrieving the public
configuration data (specified during client setup) for a Certificate Services server.
The ICer tConfig2 interface is used to perform the following tasks:
Enumerate through the configuration strings for a Certificate Services server.
Retrieve the default configuration for a Certificate Services server.
Retrieve the details of a specific Certificate Services server configuration.
Reset the configuration of a Certificate Services server.
Specify a new path for the shared folder.
For each installation of Certificate Services, this public configuration data resides in the Certsrv.txt file, which
exists in the shared folder, the Active Directory, or both. Any server set up to post its configuration information
in Certsrv.txt is visible to ICer tConfig2 .
ICer tConfig2 is defined in Certcli.h. When you create your program, however, use Certsrv.h as the include file.
Certcli.dll provides the ICer tConfig2 interface. In Windows Server 2003 and later operating systems, the type
information for this interface is also in Certclil.dll, which is shipped with the Platform Software Development Kit
(SDK).
Certificate Services interfaces support both apartment-threading and free-threading models. For better
throughput, free threading is recommended.

Inheritance
The ICer tConfig2 interface inherits from ICertConfig and IDispatch. ICer tConfig2 also has these types of
members:

Methods
The ICer tConfig2 interface has these methods.

ICertConfig2::SetSharedFolder

Specifies the path to be used as the certification authority's (CA) shared folder.

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header certcli.h (include Certsrv.h)
 ICertConfig2::SetSharedFolder method (certcli.h)
7/2/2022 • 2 minutes to read • Edit Online

The SetSharedFolder method specifies the path to be used as the certification authority's (CA) shared folder.
This method was first defined in the ICertConfig interface.

Syntax
HRESULT SetSharedFolder(
[in] const BSTR strSharedFolder
);

Parameters
[in] strSharedFolder

String value that specifies the path of the new shared folder directory.

Return value
VB
If the method succeeds, the method returns S_OK.
If the method fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header certcli.h (include Certsrv.h)

Librar y Certidl.lib

DLL Certcli.dll
 ICertGetConfig interface (certcli.h)
7/2/2022 • 2 minutes to read • Edit Online

The ICer tGetConfig interface provides functionality for retrieving the public configuration data (specified
during client setup) for a Certificate Services server.

Inheritance
The ICer tGetConfig interface inherits from the IDispatch interface. ICer tGetConfig also has these types of
members:

Methods
The ICer tGetConfig interface has these methods.

ICertGetConfig::GetConfig

The ICertGetConfig::GetConfig method retrieves the configuration string for a Certificate Services server.

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header certcli.h (include Certsrv.h)

See also
ICertConfig2
IDispatch
 ICertRequest interface (certcli.h)
7/2/2022 • 2 minutes to read • Edit Online

The ICer tRequest interface provides communications between a client or intermediary application and
Certificate services.
Client and intermediary applications can call the ICer tRequest methods to perform the following tasks:
Submit certificate request.
Retrieve the disposition, last status, and identifier of a request.
Retrieve the certificate issued for the request.
Retrieve pending certificates for previous requests.
Retrieve the certification authority (CA) certificate for the Certificate Services server.
ICer tRequest is defined in Certcli.h. When you create your program, however, use Certsrv.h as the include file.
Certcli.dll provides the ICer tRequest interface. The type information for this interface is also in Certclil.dll,
which is shipped with the Platform Software Development Kit (SDK).
Certificate Services interfaces support both apartment-threading and free-threading models. For better
throughput, free threading is recommended.

Inheritance
The ICer tRequest interface inherits from the IDispatch interface. ICer tRequest also has these types of
members:

Methods
The ICer tRequest interface has these methods.

ICertRequest::GetCACertificate

Returns the certification authority (CA) certificate for the Certificate Services server.

ICertRequest::GetCertificate

Returns the certificate issued for the request as an X.509 certificate, or optionally packaged in a Public Key Cryptography
Standards (PKCS)

ICertRequest::GetDispositionMessage

Gets a human-readable message that gives the current disposition of the certificate request.

ICertRequest::GetLastStatus

Gets the last return code for this request. This returns the error code information, rather than the disposition of the request.

ICertRequest::GetRequestId

Gets the current internal request number for the request and subsequent certificate.
 ICertRequest::RetrievePending

Retrieves a certificate's disposition status from an earlier request that may have previously returned CR_DISP_INCOMPLETE or
CR_DISP_UNDER_SUBMISSION.

ICertRequest::Submit

Submits a request to the Certificate Services server.

Requirements

Minimum suppor ted client Windows XP [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header certcli.h (include Certsrv.h)

 ICertRequest::GetCACertificate method (certcli.h)
7/2/2022 • 2 minutes to read • Edit Online

The GetCACer tificate method returns the certification authority (CA) certificate for the Certificate Services
server.

Syntax
HRESULT GetCACertificate(
[in] LONG fExchangeCertificate,
[in] const BSTR strConfig,
[in] LONG Flags,
[out, retval] BSTR *pstrCertificate
);

Parameters
[in] fExchangeCertificate

A Boolean value that specifies which CA certificate to return. If fExchangeCertificate is set to false , the signature
certificate of the CA will be returned. The Signature certificate of the CA can be used to verify signatures on
certificates issued by the CA.
Windows Ser ver 2003: If fExchangeCertificate is set to true , the Exchange certificate of the CA will be
returned. The Exchange certificate of the CA can be used to encrypt requests sent to the CA.
Beginning with Windows 7 and Windows Server 2008 R2, this parameter is ignored during https:// enrollment
and the function, if successful, always returns the CA exchange certificate. To retrieve the CA signing certificate
for an enrollment web service, use the Property method on the ICertificationAuthority interface with the
CAPropCertificate EnrollmentCAProperty enumeration value.
Note that TRUE is defined (in a Microsoft header file) for C/C++ programmers as one, while Visual Basic defines
the True keyword as negative one. As a result, Visual Basic developers must use one (instead of True ) to set this
parameter to TRUE . However, to set this parameter to FALSE , Visual Basic developers can use zero or False .
[in] strConfig

Represents a valid configuration string for the Certificate Services server. The string can be either an HTTPS URL
for an enrollment server or in the form ComputerName\ CAName, where ComputerName is the network name
of the server, and CAName is the common name of the certification authority, as entered during Certificate
Services setup. For information about the configuration string name, see ICertConfig.
Windows Ser ver 2008, Windows Vista, Windows Ser ver 2003 and Windows XP: An HTTPS URL is not
supported as an input.
[in] Flags

The following flags can be used to specify the format of the returned certificate.

VA L UE M EA N IN G
 BASE64 format with begin/end.
CR_OUT_BASE64HEADER

BASE64 format without begin/end.

CR_OUT_BASE64

Binary format.
CR_OUT_BINARY

The following flag can be combined with the format flag to specify that the complete certificate chain should be
included with the requested CA certificate. Otherwise, just the requested CA certificate (in X.509 format) is
returned.

VA L UE M EA N IN G

Include complete certificate chain in a PKCS #7.

CR_OUT_CHAIN

[out, retval] pstrCertificate

A pointer to the BSTR that contains the CA certificate for the Certificate Services server, in the specified format.

Return value
C++
If the method succeeds, the method returns S_OK.
Upon successful completion of this method, *pstrCertificate is set to the BSTR that contains the CA certificate. To
use this method, create a variable of BSTR type, set the variable equal to NULL , and pass the address of this
variable as pstrCertificate.
When you have finished using *pstrCertificate, free it by calling the SysFreeString function.
If the method fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.
VB
The CA certificate for the Certificate Services server, in the specified format.

Remarks
Administration tasks use DCOM. Code that calls this interface method as defined in an earlier version of
Certadm.h will run on Windows-based servers as long as the client and the server are both running the same
Windows operating system.

Requirements

Minimum suppor ted client Windows XP [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]
 Target Platform Windows

Header certcli.h (include Certsrv.h)

Librar y Certidl.lib

DLL Certcli.dll

See also
CCertRequest
ICertRequest
ICertRequest2
ICertRequest3
 ICertRequest::GetCertificate method (certcli.h)
7/2/2022 • 2 minutes to read • Edit Online

The GetCer tificate method returns the certificate issued for the request as an X.509 certificate, or optionally
packaged in a Public Key Cryptography Standards (PKCS) #7 message that contains the complete certificate
chain for the Certificate Services server.

Syntax
HRESULT GetCertificate(
[in] LONG Flags,
[out] BSTR *pstrCertificate
);

Parameters
[in] Flags

A flag for the format and whether the complete certificate chain is included.
The format of the returned certificate can be one of the following flags.

VA L UE M EA N IN G

BASE64 format with begin/end

CR_OUT_BASE64HEADER

BASE64 format without begin/end

CR_OUT_BASE64

Binary format
CR_OUT_BINARY

The following flags can be combined with the format flag.

VA L UE M EA N IN G

Include complete certificate chain in the PKCS #7.

CR_OUT_CHAIN
If this flag is not specified, only the requested certificate,
in X.509 format, is returned.

Include certificate revocation lists (CRLs) in the PKCS #7.

CR_OUT_CRLS

For example, to retrieve a binary certificate with complete certificate chain in C++ you would write the
following.
 hResult = pCertReq-&gt;GetCACertificate(FALSE, bstrConfig,
CR_OUT_BINARY | CR_OUT_CHAIN, &amp;bstrCert);

[out] pstrCertificate

A pointer to the BSTR that contains the certificate, in the specified format.
When using this method, create a variable of BSTR type, set the variable equal to NULL , and then pass the
address of this variable as pstrCertificate. When you have finished using the certificate pointed to by
pstrCertificate, free it by calling the SysFreeString function.

Return value
If the method sets *pstrCertificate to the BSTR that contains the certificate for the request, the method returns
S_OK.
If the method fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.

Remarks
An application would call this method to retrieve the certificate issued by means of an earlier call to
ICertRequest3::Submit or ICertRequest3::RetrievePending.
Examples
The following example shows retrieving a certificate.

#include <windows.h>
#include <stdio.h>
#include <Certcli.h>

HRESULT main()
{
// Pointer to interface object.
ICertRequest * pCertRequest = NULL;

// Variable for COMPUTER\CANAME.

BSTR bstrCA = NULL;

// Variable for CA Certificate.

BSTR bstrCACert = NULL;

HRESULT hr;

// Initialize COM.
hr = CoInitializeEx(NULL, COINIT_APARTMENTTHREADED);

// Check status.
if (FAILED(hr))
{
printf("Failed CoInitializeEx [%x]\n", hr);
goto error;
}

// Instantiate the CertConfig object.

hr = CoCreateInstance(CLSID_CCertRequest,
NULL,
CLSCTX_INPROC_SERVER,
IID_ICertRequest,
(void **)&pCertRequest);
if (FAILED(hr))
{
 printf("Failed CoCreateInstance pCertRequest [%x]\n", hr);
goto error;
}

// Note use of two backslashes (\\) in C++

// to produce one backslash (\).
bstrCA = SysAllocString(L"server01\\myCAName");

// Retrieve the CA certificate.

hr = pCertRequest->GetCACertificate(FALSE,
bstrCA,
CR_OUT_BASE64,
&bstrCACert);
if (FAILED(hr))
{
printf("Failed GetCACertificate [%x]\n", hr);
goto error;
}
else
{
// Use CA Certificate as needed.
}

// Done processing.

error:

// Free BSTR values.

if (NULL != bstrCA)
SysFreeString(bstrCA);

if (NULL != bstrCACert)
SysFreeString(bstrCACert);

// Clean up object resources.

if (NULL != pCertRequest)
pCertRequest->Release();

// Free COM resources.

CoUninitialize();

return hr;

Requirements

Minimum suppor ted client Windows XP [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header certcli.h (include Certsrv.h)

Librar y Certidl.lib

DLL Certcli.dll
See also
CCertRequest
ICertRequest
ICertRequest2
ICertRequest3
 ICertRequest::GetDispositionMessage method
(certcli.h)
7/2/2022 • 2 minutes to read • Edit Online

The GetDispositionMessage method gets a human-readable message that gives the current disposition of the
certificate request.
Note that the message returned here may have more detail than the returned error code. For example,
ICertRequest3::GetLastStatus may return an HRESULT , while GetDispositionMessage will return a detailed
reason that specifies why the request was denied.

Syntax
HRESULT GetDispositionMessage(
[out] BSTR *pstrDispositionMessage
);

Parameters
[out] pstrDispositionMessage

A pointer to the BSTR that contains the disposition message.

Return value
C++
If the method succeeds, the method returns S_OK.
Upon successful completion of this function, *pstrDispositionMessage is set to the BSTR that contains a human-
readable message that gives the current disposition of the certificate request. To use this method, create a
variable of BSTR type, set the variable equal to NULL , and pass the address of this variable as
pstrDispositionMessage. When you have finished using the BSTR , free it by calling the SysFreeString function.
If the method fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.
VB
The return value is a string that contains a human-readable message that gives the current disposition of the
certificate request.

Remarks
An application would call this method to obtain the message retrieved from the server by means of an earlier
call to ICertRequest3::Submit or ICertRequest3::RetrievePending. Additionally, the message is stored in the
Certificate Services database and may be viewed by the Certification Authority MMC snap-in (choose the
Request Disposition Message column). If the message contains localized text, it was localized on the server
(based on the server's locale).
Examples
 #include <windows.h>
#include <stdio.h>
#include <Certcli.h>

BSTR bstrDispMsg = NULL;

// pCertRequest is previously instantiated ICertRequest object
// pointer. Retrieve the disposition message for the
// previous request.
hr = pCertRequest->GetDispositionMessage(&bstrDispMsg);
if (FAILED(hr))
{
printf("Failed GetDispositionMessage [%x]\n", hr);
goto error;
}
else
{
// Use the disposition message as needed...
}

// Done processing.

error:

// Free BSTR values.

if (NULL != bstrCA)
SysFreeString(bstrCA);

if (NULL != bstrDispMsg)
SysFreeString(bstrDispMsg);

Requirements

Minimum suppor ted client Windows XP [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header certcli.h (include Certsrv.h)

Librar y Certidl.lib

DLL Certcli.dll

See also
CCertRequest
ICertRequest
ICertRequest2
ICertRequest3
 ICertRequest::GetLastStatus method (certcli.h)
7/2/2022 • 2 minutes to read • Edit Online

The GetLastStatus method gets the last return code for this request. This returns the error code information,
rather than the disposition of the request.

Syntax
HRESULT GetLastStatus(
[out] LONG *pStatus
);

Parameters
[out] pStatus

A pointer to the request's status code.

Return value
C++
If the method succeeds, the method returns S_OK.
Upon successful completion of this function, *pStatus is set to the result code of the latest call to
ICertRequest3::Submit, ICertRequest3::RetrievePending, or ICertRequest3::GetCACertificate.
If the method fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.
VB
The return value is the result code of the latest call to CCertRequest3.Submit, CCertRequest3.RetrievePending or
CCertRequest3.GetCACertificate.

Remarks
The value retrieved by GetLastStatus depends on the most recent call to ICertRequest3::Submit,
ICertRequest3::RetrievePending, or ICertRequest3::GetCACertificate. If a call to one of these methods fails on the
server, call GetLastStatus to retrieve the error number. Some server failures (such as denied requests) return
S_OK and a disposition other than CR_DISP_ISSUED from the method call, and you can use GetLastStatus to
retrieve the specific cause of failure. If a call to one of these methods succeeds, then a subsequent call to
GetLastStatus returns S_OK (which is zero).
Additionally, the request disposition is stored in the Certificate Services database, and can be viewed by means
of the Certification Authority MMC snap-in (choose the Request Disposition column).
Examples
 HRESULT hrServer, hr;
// pCertRequest is previously instantiated
// ICertRequest object pointer.
hr = pCertRequest->GetLastStatus((LONG *) &hrServer);
if (FAILED(hr))
{
printf("Failed GetLastStatus [%x]\n", hr);
goto error;
}
else
{
// Use the HRESULT value as needed...
}

Requirements

Minimum suppor ted client Windows XP [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header certcli.h (include Certsrv.h)

Librar y Certidl.lib

DLL Certcli.dll

See also
CCertRequest
ICertRequest
ICertRequest2
ICertRequest3
 ICertRequest::GetRequestId method (certcli.h)
7/2/2022 • 2 minutes to read • Edit Online

The GetRequestId method gets the current internal request number for the request and subsequent certificate.
This can be used to reference a request unambiguously to a server administrator or other interface.

Syntax
HRESULT GetRequestId(
[out] LONG *pRequestId
);

Parameters
[out] pRequestId

A pointer to the request ID value.

Return value
C++
If the method succeeds, the method returns S_OK.
Upon successful completion of this function, *pRequestId is set to the value of the request ID.
If the method fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.
VB
The return value specifies the current internal request number for the request and subsequent certificate.

Requirements

Minimum suppor ted client Windows XP [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header certcli.h (include Certsrv.h)

Librar y Certidl.lib

DLL Certcli.dll

See also
CCertRequest
ICertRequest
ICertRequest2
ICertRequest3
 ICertRequest::RetrievePending method (certcli.h)
7/2/2022 • 2 minutes to read • Edit Online

The RetrievePending method retrieves a certificate's disposition status from an earlier request that may have
previously returned CR_DISP_INCOMPLETE or CR_DISP_UNDER_SUBMISSION.
If the resulting disposition status is CR_DISP_ISSUED, you can retrieve the issued certificate by calling
ICertRequest3::GetCertificate. If a disposition other than CR_DISP_ISSUED is returned, call
ICertRequest3::GetLastStatus, ICertRequest3::GetDispositionMessage, or both methods for more information.

Syntax
HRESULT RetrievePending(
[in] LONG RequestId,
[in] const BSTR strConfig,
[out, retval] LONG *pDisposition
);

Parameters
[in] RequestId

The ID of the request that had previously returned CR_DISP_INCOMPLETE or CR_DISP_UNDER_SUBMISSION.

[in] strConfig

Represents a valid configuration string for the Certificate Services server. The string can be either an HTTPS URL
for an enrollment server or in the form ComputerName\ CAName, where ComputerName is the network name
of the server, and CAName is the common name of the certification authority, as entered during Certificate
Services setup. For information about the configuration string name, see ICertConfig.
Windows Ser ver 2008, Windows Vista, Windows Ser ver 2003 and Windows XP: An HTTPS URL is not
supported as an input.
[out, retval] pDisposition

A pointer to the request's disposition value.

Return value
C++
If the method succeeds, the method returns S_OK.
Upon successful completion of this function, *pDisposition is set to one of the values in the following table.
If the method fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.
VB
The return value specifies the disposition of the request. The disposition is one of the following values.
RET URN C O DE DESC RIP T IO N
 Request did not complete
CR_DISP_INCOMPLETE

Request failed
CR_DISP_ERROR

Request denied
CR_DISP_DENIED

Certificate issued
CR_DISP_ISSUED

Certificate issued separately

CR_DISP_ISSUED_OUT_OF_BAND

Request taken under submission

CR_DISP_UNDER_SUBMISSION

Remarks
A successful call to this method generates an EXITEVENT_CERTRETRIEVEPENDING event. An active exit module
will receive notification of this event (by means of a call to ICertExit3::Notify) if the exit module specified this
event when calling ICertExit3::Initialize.
Examples

BSTR bstrCA = NULL;

long nReqID, nDisp;

// In this example, the request ID is hard-coded.

nReqID = 1234;

// Note use of two '\' in C++ to produce one '\'.

bstrCA = SysAllocString(L"server01\\myCAName");

// pCertRequest is previously instantiated ICertRequest

// object pointer. Retrieve the status for the specified request.
hr = pCertRequest->RetrievePending( nReqID, bstrCA, &nDisp );
if (FAILED(hr))
{
printf("Failed RetrievePending [%x]\n", hr);
goto error;
}
else
{
// Use the disposition value as needed...
}
// Free BSTR resource.
if ( NULL != bstrCA )
SysFreeString( bstrCA );

Requirements

Minimum suppor ted client Windows XP [desktop apps only]

 Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header certcli.h (include Certsrv.h)

Librar y Certidl.lib

DLL Certcli.dll

See also
CCertRequest
ICertConfig
ICertRequest
ICertRequest2
ICertRequest3
 ICertRequest::Submit method (certcli.h)
7/2/2022 • 5 minutes to read • Edit Online

The Submit method submits a request to the Certificate Services server.

If the resulting disposition status is CR_DISP_ISSUED, you can retrieve the issued certificate by calling the
ICertRequest3::GetCertificate method.

Syntax
HRESULT Submit(
[in] LONG Flags,
[in] const BSTR strRequest,
[in] const BSTR strAttributes,
[in] const BSTR strConfig,
[out, retval] LONG *pDisposition
);

Parameters
[in] Flags

Specifies the request format, type of request, and whether the request is encrypted. One of the following format
attribute flags can be used to specify how the request is encoded.

VA L UE M EA N IN G

Unicode BASE64 format without begin/end.

CR_IN_BASE64

Unicode BASE64 format with begin/end.

CR_IN_BASE64HEADER

Binary format.
CR_IN_BINARY

Try all of the CR_IN_BASE64HEADER, CR_IN_BASE64, or

CR_IN_ENCODEANY CR_IN_BINARY formats.

One of the following format value flags can be used to specify the type of the request.

VA L UE M EA N IN G

Return a challenge that can be submitted to a CA. The

CR_IN_RETURNCHALLENGE challenge is a Certificate Management over CMS (CMC) full
request. When this flag is turned on, calling the
GetFullResponseProperty method with the
FR_PROP_FULLRESPONSE flag returns a CMC response that
contains key attestation challenge.
 The call is a response to a challenge. The RequestId must be
CR_IN_CHALLENGERESPONSE passed in the strAttributes parameter and the response to
the challenge must be passed in the strRequest parameter.
This flag should be turned on when an application needs to
send back the decrypted challenge to the CA. You can then
call the GetFullResponseProperty method to get the issued
end entity certificate.

A Certificate Management over CMS (CMC) request.

CR_IN_CMC

Try all of the CR_IN_CMC, CR_IN_KEYGEN, CR_IN_PKCS7, or

CR_IN_FORMATANY CR_IN_PKCS10 formats.

Keygen request (Netscape format).

CR_IN_KEYGEN

PKCS #7 request (renewal or registration agent).

CR_IN_PKCS7

PKCS #10 request.

CR_IN_PKCS10

Transmit the messages using RPC instead of DCOM.

CR_IN_RPC

Return a full CMC response.

CR_IN_FULLRESPONSE

Include the current certificate revocation lists.

CR_IN_CRLS

Use the context of the key service computer.

CR_IN_MACHINE
 Indicates that the message is being requested on behalf of
CR_IN_ROBO another sender.
If the certification authority (CA) is not configured for
"renew on behalf of", then the CA rejects the request.
For more information about enabling "renew on behalf
of" on the CA, see Configuring the Certificate Enrollment
Web Service for Renewal Only Mode.
The request must be a renewal request and the signing
certificate must be using the same template as the
request.
In addition, the request will succeed only when one of
the following conditions is true:
The signing certificate must have been issued by the
same CA
The signing certificate's SAN2 extension has the UPN
of the subject
The signing certificate's Subject Name has the
FQDN_1779 of the subject
Windows Ser ver 2008 and Windows
Ser ver 2003: This flag is not supported.

Do not include in the request data that identifies the client.

CR_IN_CLIENTIDNONE
Windows Ser ver 2008 and Windows
Ser ver 2003: This flag is not supported.

Specifies that the DCOM connection with the server is

CR_IN_CONNECTONLY established, but the request is not submitted.

[in] strRequest

A pointer to the string that contains the certificate request. If CR_IN_BASE64 or CR_IN_BASE64HEADER was
specified in Flags, strRequest must be a Unicode string.
[in] strAttributes

A pointer to the string that contains optional extra attributes for the request. Each attribute is a name-value
string pair. The colon character separates the name and value, and a newline character separates multiple name-
value pairs, for example:

C++ "AttributeName1:AttributeValue1\nAttributeName2:Attribut
eValue2"

VB "AttributeName1:AttributeValue1" & vbNewLine &

"AttributeName2:AttributeValue2"

When Certificate Services server parses attribute names, it ignores spaces, hyphens (minus signs), and case. For
example, "AttributeName1", "Attribute Name1", and "Attribute-name1" are all equivalent. For attribute values,
Certificate Services server ignores leading and trailing white space.
[in] strConfig

Represents a valid configuration string for the Certificate Services server. The string can be either an HTTPS URL
for an enrollment server or in the form ComputerName\ CAName, where ComputerName is the network name
of the server, and CAName is the common name of the certification authority, as entered during Certificate
Services setup. For information about the configuration string name, see ICertConfig.
Windows Ser ver 2008, Windows Vista, Windows Ser ver 2003 and Windows XP: An HTTPS URL is not
supported as an input.
[out, retval] pDisposition

A pointer to the request's disposition value.

Return value
C++
If the method succeeds, the method returns S_OK.
Upon successful completion of this function, *pDisposition is set to one of the values in the following table.
If the method fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.
VB
The return value specifies the disposition of the request. The disposition is one of the following values.

RET URN C O DE DESC RIP T IO N

Request denied
CR_DISP_DENIED

Request failed
CR_DISP_ERROR

Request did not complete

CR_DISP_INCOMPLETE

Certificate issued
CR_DISP_ISSUED

Certificate issued separately

CR_DISP_ISSUED_OUT_OF_BAND

Request taken under submission

CR_DISP_UNDER_SUBMISSION

Remarks
If you read a BASE64 format request from a file, ensure that the file is in Unicode, or convert it from ASCII to
Unicode before submitting the request with this method.
Examples

// The pointer to the interface object.

ICertRequest * pCertRequest = NULL;

// The variable for the computer\CAName.

BSTR bstrCA = NULL;

// The variable for the request.

BSTR bstrRequest = NULL;

// The variable for the attributes.

BSTR bstrAttribs = NULL;
 BSTR bstrAttribs = NULL;

// The variable for the disposition code.

long nDisp;

HRESULT hr;

// Initialize COM.
hr = CoInitializeEx(NULL, COINIT_APARTMENTTHREADED);

// Check status.
if (FAILED(hr))
{
printf("Failed CoInitializeEx [%x]\n", hr);
goto error;
}

// Instantiate the CertConfig object.

hr = CoCreateInstance(CLSID_CCertRequest,
NULL,
CLSCTX_INPROC_SERVER,
IID_ICertRequest,
(void **)&pCertRequest);
if (FAILED(hr))
{
printf("Failed CoCreateInstance pCertRequest [%x]\n", hr);
goto error;
}

// Specify the certification authority.

// Note: In C++, produce one backslash (\) by using two.
bstrCA = SysAllocString(L"server01\\myCAName");

// Create the request (not shown), and assign it to bstrRequest,

// for example, use ICEnroll::createPKCS10.

// Generate the attributes. In this case, no attributes

// are specified.
bstrAttribs = SysAllocString(L"");

// Submit the request.

hr = pCertRequest->Submit(CR_IN_BASE64 | CR_IN_PKCS10,
bstrRequest,
bstrAttribs,
bstrCA,
&nDisp );
if (FAILED(hr))
{
printf("Failed Submit [%x]\n", hr);
goto error;
}
else
{
// Use the disposition value as needed.
}

// Done processing.

error:

// Free BSTR values.

if (NULL != bstrCA)
SysFreeString(bstrCA);

if (NULL != bstrRequest)
SysFreeString(bstrRequest);

if (NULL != bstrAttribs)
SysFreeString(bstrAttribs);
 // Clean up object resources.
if (NULL != pCertRequest)
pCertRequest->Release();

// Free COM resources.

CoUninitialize();

Requirements

Minimum suppor ted client Windows XP [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header certcli.h (include Certsrv.h)

Librar y Certidl.lib

DLL Certcli.dll

See also
CCertRequest
ICEnroll::createPKCS10
ICertConfig
ICertRequest
ICertRequest2
ICertRequest3
 ICertRequest2 interface (certcli.h)
7/2/2022 • 2 minutes to read • Edit Online

The ICer tRequest2 interface is one of two interfaces that provide communications between a client or
intermediary application and Certificate Services.
Client and intermediary applications can call the ICertRequest2 methods to perform the following tasks:
Submit certificate request.
Retrieve the disposition, last status, and identifier of a request.
Retrieve the certificate issued for the request.
Retrieve pending certificates for previous requests.
Retrieve the certification authority (CA) certificate for the Certificate Services server.
Retrieve the CA property value, display name, and any flags associated with the property.
Retrieve the cached response data returned by the server.
Retrieve error message text for an HRESULT error code.
ICer tRequest2 is defined in Certcli.h. When you create your program, however, use Certsrv.h as the include file.
Certcli.dll provides the ICer tRequest2 interface. The type information for this interface is also in Certclil.dll,
which is shipped with the Platform Software Development Kit (SDK).
Certificate Services interfaces support both apartment-threading and free-threading models. For better
throughput, free threading is recommended.

Inheritance
The ICer tRequest2 interface inherits from ICertRequest and IDispatch. ICer tRequest2 also has these types of
members:

Methods
The ICer tRequest2 interface has these methods.

ICertRequest2::GetCAProperty

Retrieves a property value for the certification authority (CA).

ICertRequest2::GetCAPropertyDisplayName

Retrieves the property display name for a certification authority (CA) property.

ICertRequest2::GetCAPropertyFlags

Retrieves the property flags for a certification authority (CA) property.

ICertRequest2::GetErrorMessageText

Retrieves the error message text for an HRESULT error code.

 ICertRequest2::GetFullResponseProperty

Retrieves the cached response data returned by the server.

ICertRequest2::GetIssuedCertificate

Retrieves a certificate's disposition by specifying either the request ID or the certificate serial number.

Requirements

Minimum suppor ted client Windows XP [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header certcli.h (include Certsrv.h)

 ICertRequest2::GetCAProperty method (certcli.h)
7/2/2022 • 2 minutes to read • Edit Online

The GetCAProper ty method retrieves a property value for the certification authority (CA). This method's
functionality is identical to ICertAdmin2::GetCAProperty. For information about this method, see
ICer tAdmin2::GetCAProper ty .

Syntax
HRESULT GetCAProperty(
[in] const BSTR strConfig,
[in] LONG PropId,
[in] LONG PropIndex,
[in] LONG PropType,
[in] LONG Flags,
[out, retval] VARIANT *pvarPropertyValue
);

Parameters
[in] strConfig

Represents a valid configuration string for the CA in the form COMPUTERNAME\CANAME, where
COMPUTERNAME is the Certificate Services server's network name, and CANAME is the common name of the
CA, as entered during Certificate Services setup. For information about the configuration string name, see
ICertConfig.
[in] PropId

Specifies the property identifier. For information about this parameter, see the table in
ICertAdmin2::GetCAProperty.
[in] PropIndex

If PropId is indexed, the zero-based index to use when retrieving the property value. If PropId is not indexed, this
value is ignored.
[in] PropType

Specifies the type of the property, which corresponds to the Type column in the PropId table. The type can be
one of the following types.

VA L UE M EA N IN G

Signed long data

PROPTYPE_LONG

Date/time (reserved for future use)

PROPTYPE_DATE

Binary data
PROPTYPE_BINARY
 Unicode string data
PROPTYPE_STRING

[in] Flags

The following flags can be used to specify the format of the returned property value; these flags have meaning
only for binary data (such as certificates, certificate chains, or certificate revocation lists) and is ignored
otherwise.

VA L UE M EA N IN G

BASE64 without BEGIN/END

CV_OUT_BASE64

BASE64 with BEGIN CERTIFICATE and END CERTIFICATE

CV_OUT_BASE64HEADER

BASE64 with BEGIN NEW CERTIFICATE REQUEST and END

CV_OUT_BASE64REQUESTHEADER NEW CERTIFICATE REQUEST

BASE64 with BEGIN X509 CRL and END X509 CRL

CV_OUT_BASE64X509CRLHEADER

Binary
CV_OUT_BINARY

Hexadecimal string
CV_OUT_HEX

Hexadecimal string with address/offset

CV_OUT_HEXADDR

Hexadecimal string with ASCII

CV_OUT_HEXASCII

Hexadecimal string with ASCII and address/offset

CV_OUT_HEXASCIIADDR

[out, retval] pvarPropertyValue

A pointer to a VARIANT that receives the requested property value.

When you have finished using the VARIANT , free it by calling the VariantClear function.

Return value
C++
If the method succeeds, the method returns S_OK.
If the method fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.
VB
The return value is a Variant that receives the requested property value.

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header certcli.h (include Certsrv.h)

Librar y Certidl.lib

DLL Certcli.dll

See also
CCer tRequest
ICertRequest
ICertRequest2
 ICertRequest2::GetCAPropertyDisplayName
method (certcli.h)
7/2/2022 • 2 minutes to read • Edit Online

The GetCAProper tyDisplayName method retrieves the property display name for a certification authority
(CA) property.

Syntax
HRESULT GetCAPropertyDisplayName(
[in] const BSTR strConfig,
[in] LONG PropId,
[out, retval] BSTR *pstrDisplayName
);

Parameters
[in] strConfig

Represents a valid configuration string for the CA in the form ComputerName\ CAName, where ComputerName
is the network name of the Certificate Services server, and CAName is the common name of the CA, as entered
during Certificate Services setup. For information about the configuration string name, see ICertConfig.
[in] PropId

Specifies the property identifier. For information about this parameter, see the table in
ICertAdmin2::GetCAProperty.
[out, retval] pstrDisplayName

A pointer to the BSTR that represents the property's display name. When you have finished using the BSTR ,
free it by calling the SysFreeString function.

Return value
C++
If the method succeeds, the method returns S_OK.
If the method fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.
VB
The return value is a String that contains the property's display name.

Remarks
The GetCAProper tyDisplayName method's functionality is similar to that of the
ICertAdmin2::GetCAPropertyDisplayName method.
In the ICertAdmin2 method, the CA enforces that the caller has CA read access, which is usually only granted to
CA officers and CA administrators.
By contrast, in the ICertRequest2 and ICertRequest3 implementations of the method, the CA does not require
any access rights by default. Only Distributed Component Object Model (DCOM) access control lists (ACLs) are
enforced; for a domain-joined CA, the DCOM ACLs allow Everyone access to the CAs. Everyone does not include
Anonymous. The CA's request interface can be locked down by using the registry configuration to enforce that
the caller has enroll access.

Requirements

Minimum suppor ted client Windows XP [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header certcli.h (include Certsrv.h)

Librar y Certidl.lib

DLL Certcli.dll

See also
CCertRequest
ICertRequest
ICertRequest2
ICertRequest3
 ICertRequest2::GetCAPropertyFlags method
(certcli.h)
7/2/2022 • 2 minutes to read • Edit Online

The GetCAProper tyFlags method retrieves the property flags for a certification authority (CA) property.

Syntax
HRESULT GetCAPropertyFlags(
[in] const BSTR strConfig,
[in] LONG PropId,
[out, retval] LONG *pPropFlags
);

Parameters
[in] strConfig

Represents a valid configuration string for the CA in the form ComputerName\ CAName, where ComputerName
is the network name of the Certificate Services server, and CAName is the common name of the CA, as entered
during Certificate Services setup. For information about the configuration string name, see ICertConfig.
[in] PropId

Specifies the property identifier. For information about this parameter, see the table in
ICertAdmin2::GetCAProperty.
[out, retval] pPropFlags

A pointer to a LONG value that represents the property flags.

Return value
C++
If the method succeeds, the method returns S_OK.
If the method fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.
VB
The return value is a Long that represents the property flags.

Remarks
The GetCAProper tyFlags method's functionality is similar to that of the ICertAdmin2::GetCAPropertyFlags
method.
In the ICertAdmin2 method, the CA enforces that the caller has CA read access, which is usually only granted to
CA officers and CA administrators.
By contrast, in the ICertRequest2 and ICertRequest3 implementations of the method, the CA does not require
any access rights by default. Only Distributed Component Object Model (DCOM) access control lists (ACLs) are
enforced; for a domain-joined CA, the DCOM ACLs allow Everyone access to the CAs. Everyone does not include
Anonymous. The CA's request interface can be locked down by using the registry configuration to enforce that
the caller has enroll access.

Requirements

Minimum suppor ted client Windows XP [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header certcli.h (include Certsrv.h)

Librar y Certidl.lib

DLL Certcli.dll

See also
CCertRequest
ICertRequest
ICertRequest2
ICertRequest3
 ICertRequest2::GetErrorMessageText method
(certcli.h)
7/2/2022 • 2 minutes to read • Edit Online

The GetErrorMessageText method retrieves the error message text for an HRESULT error code.
If the error message text is localized, it has been localized on the client.

Syntax
HRESULT GetErrorMessageText(
[in] LONG hrMessage,
[in] LONG Flags,
[out] BSTR *pstrErrorMessageText
);

Parameters
[in] hrMessage

A value that represents an HRESULT error.

[in] Flags

A LONG value that corresponds to one of the values in the following table.

VA L UE M EA N IN G

The error message text will not have the HRESULT

Zero (0) hexadecimal and decimal values appended.

The error message text will have the HRESULT hexadecimal

CR_GEMT_HRESULT_STRING and decimal values appended.

[out] pstrErrorMessageText

A pointer to the BSTR that represents the error message text for hrMessage. When you have finished using the
BSTR , free it by calling the SysFreeString function.

Return value
C++
If the method succeeds, the method returns S_OK.
If the method fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.
VB
The return value is a String that contains the error message text for hrMessage.
Requirements

Minimum suppor ted client Windows XP [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header certcli.h (include Certsrv.h)

Librar y Certidl.lib

DLL Certcli.dll
 ICertRequest2::GetFullResponseProperty method
(certcli.h)
7/2/2022 • 2 minutes to read • Edit Online

The GetFullResponseProper ty method retrieves the cached response data returned by the server.

Syntax
HRESULT GetFullResponseProperty(
[in] LONG PropId,
[in] LONG PropIndex,
[in] LONG PropType,
[in] LONG Flags,
[out] VARIANT *pvarPropertyValue
);

Parameters
[in] PropId

The data to be retrieved. If the property is indexed, use PropIndex to specify the index. This parameter can be
one of the following values.

VA L UE M EA N IN G

No data.
FR_PROP_NONE
0

All the cached data is retrieved (binary data).

FR_PROP_FULLRESPONSE
1

The number of responses in cache data (long, indexed

FR_PROP_STATUSINFOCOUNT property).
2

Hierarchy data (string, indexed property).

FR_PROP_BODYPARTSTRING
3

The request status value (long, indexed property).

FR_PROP_STATUS
4

The request status string (string, indexed property).

FR_PROP_STATUSSTRING
5
 Choice for other information (long, indexed property). This
FR_PROP_OTHERINFOCHOICE can be one of the following values.
6 CMC_OTHER_INFO_NO_CHOICE
CMC_OTHER_INFO_FAIL_CHOICE
CMC_OTHER_INFO_PEND_CHOICE

The request failure information (long, indexed property).

FR_PROP_FAILINFO
7

The request pending token (binary, indexed property).

FR_PROP_PENDINFOTOKEN
8

The request pending date (DATE , indexed property).

FR_PROP_PENDINFOTIME
9

The hash of the issued certificate is retrieved (binary, indexed

FR_PROP_ISSUEDCERTIFICATEHASH property).
10

The issued certificate is retrieved (binary, indexed property).

FR_PROP_ISSUEDCERTIFICATE
11

The issued certificate (binary, indexed property).

FR_PROP_ISSUEDCERTIFICATECHAIN
12

The issued certificate chain (binary, indexed property).

FR_PROP_ISSUEDCERTIFICATECRLCHAIN
13

The encrypted key hash (binary, indexed property).

FR_PROP_ENCRYPTEDKEYHASH
14

All the cached data is retrieved except for the PKCS #7

FR_PROP_FULLRESPONSENOPKCS7 (binary).
15

The CA exchange certificate hash.

FR_PROP_CAEXCHANGECERTIFICATEHASH
16

The CA exchange certificate.

FR_PROP_CAEXCHANGECERTIFICATE
17
 The CA exchange certificate chain.
FR_PROP_CAEXCHANGECERTIFICATECHAIN
18

The CA exchange certificate CLR chain.

FR_PROP_CAEXCHANGECERTIFICATECRLCHAIN
19

The key attestation challenge response

FR_PROP_ATTESTATIONCHALLENGE
20

The name of the key storage provider for key attestation.

FR_PROP_ATTESTATIONPROVIDERNAME
21

[in] PropIndex

The zero-based index when PropId is an indexed property. If PropId is not an indexed property, then PropIndex
must be zero.
[in] PropType

The type of data returned in pvarPropertyValue. The property type here must match the type of data specified
by the PropId parameter.
This parameter can be one of the following values.

VA L UE M EA N IN G

Signed long data.

PROPTYPE_LONG
1

Date data (includes date and time).

PROPTYPE_DATE
2

Binary data.
PROPTYPE_BINARY
3

String data.
PROPTYPE_STRING
4

[in] Flags

The format of the data returned in pvarPropertyValue. The flag set here must match the type of data specified by
the PropId parameter.
For more information, see Remarks. This parameter can be one of the following values.

VA L UE M EA N IN G
 BASE64 format with begin/end header.
CR_OUT_BASE64HEADER
0

BASE64 format without begin/end header.

CR_OUT_BASE64
1

Binary format.
CR_OUT_BINARY
2

[out] pvarPropertyValue

The data returned.

Return value
C++
If the method succeeds, the method returns S_OK and pvarPropertyValue contains the returned data.
If the method fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.
VB
The return value is a Variant that contains the returned data.

Remarks
The following PropId values return binary data, which means that the Flags parameter must set to
CR_OUT_BINARY:
FR_PROP_FULLRESPONSE
FR_PROP_ISSUEDCERTIFICATEHASH
FR_PROP_ISSUEDCERTIFICATE
FR_PROP_ISSUEDCERTIFICATECHAIN
FR_PROP_ISSUEDCERTIFICATECRLCHAIN
FR_PROP_ENCRYPTEDKYEHASH
FR_PROP_FULLRESPONSENOPKCS7
This method is called after the ICertRequest3::Submit or ICertRequest3::RetrievePending methods have been called.
These methods populate the cached data that is returned by GetFullResponseProper ty .
After the ICer tRequest3::GetFullResponseProper ty method returns its data, the following methods can be
called:
ICEnroll4::AcceptResponse can be called to install the returned certificate.
ICEnroll4::GetCertFromResponse can be called to parse the certificate from the response.

Requirements

Minimum suppor ted client Windows XP [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header certcli.h (include Certsrv.h)

Librar y Certidl.lib

DLL Certcli.dll
 ICertRequest2::GetIssuedCertificate method
(certcli.h)
7/2/2022 • 2 minutes to read • Edit Online

The GetIssuedCer tificate method retrieves a certificate's disposition by specifying either the request ID or the
certificate serial number.
This method is effectively the same as calling ICertRequest3::RetrievePending, with the additional capability of
specifying a serial number for the certificate in question.

Syntax
HRESULT GetIssuedCertificate(
[in] const BSTR strConfig,
[in] LONG RequestId,
[in] const BSTR strSerialNumber,
[out, retval] LONG *pDisposition
);

Parameters
[in] strConfig

Represents a valid configuration string for the Certificate Services server. The string can be either an HTTPS URL
for an enrollment server or in the form ComputerName\ CAName, where ComputerName is the network name
of the server, and CAName is the common name of the certification authority, as entered during Certificate
Services setup. For information about the configuration string name, see ICertConfig.
Windows Ser ver 2008, Windows Vista, Windows Ser ver 2003 and Windows XP: An HTTPS URL is not
supported as an input.
[in] RequestId

A LONG value that represents the certificate request ID in the Certificates Services database. Use –1 for this
value if the serial number (passed in as strSerialNumber) is to be used instead of the request ID.
[in] strSerialNumber

A BSTR value that represents the certificate serial number, as issued by the CA. For strSerialNumber to be used,
you must specify a value of –1 for RequestId.
[out, retval] pDisposition

A pointer to a LONG value that represents the certificate's disposition. The disposition is one of the following
values.

VA L UE M EA N IN G

Request denied.
CR_DISP_DENIED
 Request failed.
CR_DISP_ERROR

Request did not complete.

CR_DISP_INCOMPLETE

Certificate issued.
CR_DISP_ISSUED

Certificate issued separately.

CR_DISP_ISSUED_OUT_OF_BAND

Request taken under submission.

CR_DISP_UNDER_SUBMISSION

Return value
C++
If the method succeeds, the method returns S_OK.
If the method fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.
VB
The return value is a Long that represents the certificate's disposition.

Requirements

Minimum suppor ted client Windows XP [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header certcli.h (include Certsrv.h)

Librar y Certidl.lib

DLL Certcli.dll
 ICertRequest3 interface (certcli.h)
7/2/2022 • 2 minutes to read • Edit Online

The ICer tRequest3 interface is one of three interfaces that provide communications between a client or
intermediary application and Certificate Services.
Client and intermediary applications can call the ICer tRequest3 methods to perform the following tasks:
Submit a certificate request.
Retrieve the disposition, last status, and identifier of a request.
Retrieve the certificate issued for the request.
Retrieve pending certificates for previous requests.
Retrieve the certification authority (CA) certificate for the Certificate Services server.
Retrieve the CA property value, display name, and any flags associated with the property.
Retrieve the cached response data returned by the server.
Retrieve error message text for an HRESULT error code.
ICer tRequest3 is defined in Certcli.h. When you create your program, however, use Certsrv.h as the include file.
Certcli.dll provides the ICer tRequest3 interface. The type information for this interface is also in Certcli.dll,
which is shipped with the Platform Software Development Kit (SDK).
Certificate Services interfaces support both apartment-threading and free-threading models. For better
throughput, free threading is recommended.

Inheritance
The ICer tRequest3 interface inherits from ICertRequest2, ICertRequest, and IDispatch. ICer tRequest3 also has
these types of members:

Methods
The ICer tRequest3 interface has these methods.

ICertRequest3::GetIssuedCertificate2

Retrieves a certificate's disposition by specifying either the request ID string or the certificate serial number.

ICertRequest3::GetRefreshPolicy

Returns a value that indicates whether a client's cached certificate enrollment policy is out of date and needs to be refreshed.

ICertRequest3::GetRequestIdString

Gets the current internal request number, formatted as a string, for the request and subsequent certificate.

ICertRequest3::SetCredential

Sets the credential used to contact the Certificate Enrollment Web Service.
Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Target Platform Windows

Header certcli.h (include Certsrv.h)

See also
ICertRequest
ICertRequest2
IDispatch
 ICertRequest3::GetIssuedCertificate2 method
(certcli.h)
7/2/2022 • 2 minutes to read • Edit Online

The GetIssuedCer tificate2 method retrieves a certificate's disposition by specifying either the request ID
string or the certificate serial number.

Syntax
HRESULT GetIssuedCertificate2(
[in] BSTR strConfig,
[in] BSTR strRequestId,
[in] BSTR strSerialNumber,
[out, retval] LONG *pDisposition
);

Parameters
[in] strConfig

Represents a valid configuration string for the Certificate Services server. The string can be either an HTTPS URL
for an enrollment server or in the form ComputerName\ CAName, where ComputerName is the network name
of the server, and CAName is the common name of the certification authority, as entered during Certificate
Services setup. For information about the configuration string name, see ICertConfig.
Windows Ser ver 2008, Windows Vista, Windows Ser ver 2003 and Windows XP: An HTTPS URL is not
supported as an input.
[in] strRequestId

A BSTR value that represents the certificate request ID in the Certificates Services database. Set this parameter
to NULL if the serial number (passed in as strSerialNumber) is to be used instead of the request ID.
Use the ICertRequest3::GetRequestIdString method to obtain the request ID string.
[in] strSerialNumber

A BSTR value that represents the certificate serial number, as issued by the CA. The string must specify the serial
number as an even number of hexadecimal digits. If necessary, a zero can be prefixed to the number to produce
an even number of digits. However, no more than one leading zero may be used.
The strSerialNumber value is only used when the strRequestId is set to NULL .
[out, retval] pDisposition

A pointer to a LONG value that represents the certificate's disposition. The disposition is one of the following
values.

VA L UE M EA N IN G

Request denied.
CR_DISP_DENIED
 Request failed.
CR_DISP_ERROR

Request did not complete.

CR_DISP_INCOMPLETE

Certificate issued.
CR_DISP_ISSUED

Certificate issued separately.

CR_DISP_ISSUED_OUT_OF_BAND

Request taken under submission.

CR_DISP_UNDER_SUBMISSION

Return value
C++
If the method succeeds, the method returns S_OK .
If the method fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.
VB
The return value is a Long that represents the certificate's disposition.

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Target Platform Windows

Header certcli.h (include Certsrv.h)

Librar y Certidl.lib

DLL Certcli.dll

See also
CCertRequest
ICertRequest3
 ICertRequest3::GetRefreshPolicy method (certcli.h)
7/2/2022 • 2 minutes to read • Edit Online

The GetRefreshPolicy method returns a value that indicates whether a client's cached certificate enrollment
policy is out of date and needs to be refreshed.

Syntax
HRESULT GetRefreshPolicy(
[out, retval] VARIANT_BOOL *pValue
);

Parameters
[out, retval] pValue

A pointer to a VARIANT_BOOL variable to receive the refresh indicator.

Return value
C++
If the method succeeds, the method returns S_OK .
If the method fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.
VB
The return value is a BOOL that indicates whether the client's policy service is out of date.

Remarks
The GetRefreshPolicy method returns TRUE only when the enrollment server returns a fault. Before calling
the GetRefreshPolicy method you must contact the enrollment server. If a fault is returned, then call the
GetRefreshPolicy method from same instance of ICertRequest3 to determine whether the cached policy is out
of date and needs to be refreshed.

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Target Platform Windows

Header certcli.h (include Certsrv.h)

Librar y Certidl.lib
DLL Certcli.dll
 ICertRequest3::GetRequestIdString method
(certcli.h)
7/2/2022 • 2 minutes to read • Edit Online

The GetRequestIdString method gets the current internal request number, formatted as a string, for the
request and subsequent certificate.
This can be used to reference a request unambiguously to a server administrator or other interface.

Syntax
HRESULT GetRequestIdString(
[out, retval] BSTR *pstrRequestId
);

Parameters
[out, retval] pstrRequestId

A pointer to BSTR variable to receive the request ID string.

Return value
C++
If the method succeeds, the method returns S_OK .
Upon successful completion of this function, the string pointed to by the pstrRequestId parameter is set to the
request ID string.
If the method fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.
VB
The return value specifies the current internal request number, as a string, for the request and subsequent
certificate.

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Target Platform Windows

Header certcli.h (include Certsrv.h)

Librar y Certidl.lib
 DLL Certcli.dll

See also
CCertRequest
ICertRequest3
 ICertRequest3::SetCredential method (certcli.h)
7/2/2022 • 2 minutes to read • Edit Online

The SetCredential method sets the credential used to contact the Certificate Enrollment Web Service.

Syntax
HRESULT SetCredential(
[in] LONG hWnd,
[in] X509EnrollmentAuthFlags AuthType,
[in] BSTR strCredential,
[in] BSTR strPassword
);

Parameters
[in] hWnd

A handle to the parent window.

You must set the hWnd parameter there is a UI presented to obtain the credential.
For certificate based authorization, the handle is used if a UI prompt is needed to obtain the credential, for
example, if the credential is on a smart card and a pin prompt is needed.
When using Kerberos, anonymous, or user name and password authentication, this parameter is ignored.
[in] AuthType

A value of the X509EnrollmentAuthFlags enumeration that specifies the authentication type.

VA L UE M EA N IN G

Anonymous authentication.
X509AuthAnonymous
Set the strCredential and strPassword parameters to
NULL or to empty strings.

Client authentication certificate installed on the local

X509AuthCer tificate computer. The certificate contains a public key that is
associated with a private key (not contained in the
certificate). The certificate is used by the server to verify the
identity of the client.
The strCredential parameter contains a binary 20-byte
SHA-1 hash of the certificate to be passed to the
Certificate Enrollment Web Service to authenticate the
caller. Set the strPassword parameter to NULL or an
empty string. The strCredential parameter must refer to
a certificate installed in the relevant personal certificate
store, and it must have an associated private key that is
accessible to the caller.
 Kerberos authentication.
X509AuthKerberos
Set the strCredential and strPassword parameters to
NULL or to empty strings.

Plaintext user name and password authentication. The user

X509AuthUsername name and password are encrypted when they are stored in
the credential vault on the client.
The strCredential and strPassword parameters contain a
user name string and a plaintext password that are
supported by the Certificate Enrollment Web Service to
authenticate the caller. Because an enrollment service
connection always uses Secure Sockets Layer protocol
(SSL), the password is encrypted when sent over the
wire.

[in] strCredential

A string that contains the credential.

[in] strPassword

A string that contains the password.

Return value
RET URN C O DE DESC RIP T IO N

The AuthType parameter must be X509AuthKerberos .

E_INVALIDARG

Remarks
The SetCredential method must be called prior to calling the ICertRequest2::Submit method.
The strCredential and strPassword arguments change depending on the value specified in the AuthType
parameter as shown in the following table.

A UT H T Y P E PA RA M ET ER ST RC REDEN T IA L PA RA M ET ER ST RP A SSWO RD PA RA M ET ER

X509AuthAnonymous NULL NULL

X509AuthCertificate A 20 byte SHA-1 hash (thumbprint) of NULL

the certificate

X509AuthKerberos NULL NULL

X509AuthUsername A plaintext user name that is A plaintext password that is associated

recognized by the Certificate with the user name
Enrollment Web Service

Requirements
 Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Target Platform Windows

Header certcli.h (include Certsrv.h)

Librar y Certidl.lib

DLL Certcli.dll

See also
CCertRequest
ICertRequest3
 X509EnrollmentAuthFlags enumeration (certcli.h)
7/2/2022 • 2 minutes to read • Edit Online

The X509EnrollmentAuthFlags enumeration specifies the authentication type.

Syntax
typedef enum X509EnrollmentAuthFlags {
X509AuthNone = 0,
X509AuthAnonymous = 1,
X509AuthKerberos = 2,
X509AuthUsername = 4,
X509AuthCertificate = 8
} ;

Constants

X509AuthNone
Value: 0
Reserved.

X509AuthAnonymous
Value: 1
Anonymous authentication.

X509AuthKerberos
Value: 2
Kerberos authentication.

X509AuthUsername
Value: 4
Plaintext user name and password authentication.

X509AuthCertificate
Value: 8
A client authentication certificate (suitable for Secure Sockets Layer protocol (SSL) client authentication) that is installed locally
and that has an associated private key. This certificate is used by the server to verify the client's identity.

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Header certcli.h
 certenc.h header
7/2/2022 • 2 minutes to read • Edit Online

This header is used by Security and Identity. For more information, see:
Security and Identity
certenc.h contains the following programming interfaces:

Interfaces

ICertEncodeAltName

Provides methods for handling alternate names used in certificate extensions.

ICertEncodeBitString

Provides methods for handling bit strings used in certificate extensions.

ICertEncodeCRLDistInfo

Provides methods for handling certificate revocation list (CRL) distribution information arrays used in certificate extensions.

ICertEncodeDateArray

Provides methods for handling Date arrays used in certificate extensions.

ICertEncodeLongArray

Provides methods for handling Long arrays used in certificate extensions.

ICertEncodeStringArray

Provides methods for handling string arrays used in certificate extensions.

 ICertEncodeAltName interface (certenc.h)
7/2/2022 • 2 minutes to read • Edit Online

The ICer tEncodeAltName interface provides methods for handling alternate names used in certificate
extensions.
A certificate extension can be created using an alternate name array stored in an extension handler COM object.
Each element in the array is a structure that contains a name string and a name choice.
This interface is useful for encoding and decoding szOID_SUBJECT_ALT_NAME2 "2.5.29.17" extensions; the SDK
sample policy module uses this interface.
ICer tEncodeAltName is defined in Certenc.h. When you create your program, however, use Certsrv.h as the
include file. Certenc.dll provides the ICer tEncodeAltName interface. The type information for this interface is
also in Certencl.dll, which is shipped with the Platform Software Development Kit (SDK).
Certificate Services interfaces support both apartment-threading and free-threading models. For better
throughput, free threading is recommended.

Inheritance
The ICer tEncodeAltName interface inherits from the IDispatch interface. ICer tEncodeAltName also has
these types of members:

Methods
The ICer tEncodeAltName interface has these methods.

ICertEncodeAltName::Decode

Decodes an Abstract Syntax Notation One (ASN.1)-encoded alternate name extension and stores the resulting array of strings
in the CertEncodeAltName object.

ICertEncodeAltName::Encode

Returns an ASN.1-encoded string of the alternate name array stored in this object. The names in the object are not encoded.

ICertEncodeAltName::GetName

Returns the specified name from the alternate name array.

ICertEncodeAltName::GetNameChoice

Returns the name choice at a specified index of an alternate name array.

ICertEncodeAltName::GetNameCount

Returns the number of names in the alternate name array.

 ICertEncodeAltName::Reset

Specifies the size of the alternate name array in this object. The value of all elements in the array are set to zero.

ICertEncodeAltName::SetNameEntry

Sets a name at a specified index of the alternate name array.

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header certenc.h (include Certsrv.h)

 ICertEncodeAltName::Decode method (certenc.h)
7/2/2022 • 2 minutes to read • Edit Online

The Decode method decodes an Abstract Syntax Notation One (ASN.1)-encoded alternate name extension and
stores the resulting array of strings in the Cer tEncodeAltName object.

Syntax
HRESULT Decode(
[in] const BSTR strBinary
);

Parameters
[in] strBinary

Represents an ASN.1-encoded alternate name extension.

Return value
VB
If the method succeeds, the method returns S_OK.
If the method fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header certenc.h (include Certsrv.h)

Librar y Certidl.lib

DLL Certenc.dll

See also
ICertEncodeAltName
ICertEncodeAltName::Encode
 ICertEncodeAltName::Encode method (certenc.h)
7/2/2022 • 2 minutes to read • Edit Online

The Encode method returns an ASN.1-encoded string of the alternate name array stored in this object. The
names in the object are not encoded.
Use the Decode method to decode the encoded string into an Cer tEncodeAltName object.
Before using this method, you must call both the Reset method to size the array and the SetNameEntry method
to set each array element.

Syntax
HRESULT Encode(
[out] BSTR *pstrBinary
);

Parameters
[out] pstrBinary

A pointer to a BSTR that receives the ASN.1-encoded alternate name extension. When done, call SysFreeString
to free pbstrBinary.

Return value
C++
If the method succeeds, the method returns S_OK.
If the method fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.
VB
The return value is the ASN.1-encoded alternate name array.

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header certenc.h (include Certsrv.h)

Librar y Certidl.lib

DLL Certenc.dll
See also
ICertEncodeAltName
ICertEncodeAltName::Decode
ICertEncodeAltName::Reset
ICertEncodeAltName::SetNameEntry
 ICertEncodeAltName::GetName method (certenc.h)
7/2/2022 • 2 minutes to read • Edit Online

The GetName method returns the specified name from the alternate name array.

Syntax
HRESULT GetName(
[in] LONG NameIndex,
[out] BSTR *pstrName
);

Parameters
[in] NameIndex

A zero-based index that specifies the index of the alternate name entry to retrieve.
To retrieve the object identifier (OID) of a CERT_ALT_NAME_OTHER_NAME name, combine the index value with
EAN_NAMEOBJECTID (defined as 0x80000000) with a bitwise-OR operation. Otherwise, the binary value is
retrieved. To determine the type of name, call the ICertEncodeAltName::GetNameChoice method.
[out] pstrName

A pointer to a BSTR that receives the alternate name. When you have finished using the BSTR , free it by calling
the SysFreeString function.

Return value
C++
If the method succeeds, the method returns S_OK.
If the method fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.
VB
The return value is the alternate name at the specified index. The return value is a Unicode string.

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header certenc.h (include Certsrv.h)

 Librar y Certidl.lib

DLL Certenc.dll

See also
ICertEncodeAltName
ICertEncodeAltName::GetNameChoice
ICertEncodeAltName::SetNameEntry
 ICertEncodeAltName::GetNameChoice method
(certenc.h)
7/2/2022 • 2 minutes to read • Edit Online

The GetNameChoice method returns the name choice at a specified index of an alternate name array.

Syntax
HRESULT GetNameChoice(
[in] LONG NameIndex,
[out] LONG *pNameChoice
);

Parameters
[in] NameIndex

Specifies the index of the alternate name entry. The first entry is at index zero.
[out] pNameChoice

A pointer to a LONG that receives the name choice specifier.

Return value
C++
If the method succeeds, the method returns S_OK, and the pNameChoice parameter points to a value that indicates
the type of the alternate name. This is one of the following values.
If the method fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.
VB
The return value is the name choice at the specified index. The name choice indicates the type of the alternate name
so that it can be used correctly. It must be one of the following values.
RET URN C O DE DESC RIP T IO N

The name is a directory name.

CERT_ALT_NAME_DIRECTORY_NAME

The name is an IA5 string that contains a DNS (Domain

CERT_ALT_NAME_DNS_NAME Name System) name in the format Host. Entity. Domain.

The name is an octet string that represents an Internet

CERT_ALT_NAME_IP_ADDRESS protocol address.

The name is a registered object identifier (OID).

CERT_ALT_NAME_REGISTERED_ID
 The name is an email address.
CERT_ALT_NAME_RFC822_NAME

The name is an IA5 string that contains a URL in the format

CERT_ALT_NAME_URL Service://HostName/Path.

The name consists of an OID and a binary BLOB.

CERT_ALT_NAME_OTHER_NAME

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header certenc.h (include Certsrv.h)

Librar y Certidl.lib

DLL Certenc.dll

See also
ICertEncodeAltName
ICertEncodeAltName::GetName
ICertEncodeAltName::SetNameEntry
 ICertEncodeAltName::GetNameCount method
(certenc.h)
7/2/2022 • 2 minutes to read • Edit Online

The GetNameCount method returns the number of names in the alternate name array.

Syntax
HRESULT GetNameCount(
[out] LONG *pNameCount
);

Parameters
[out] pNameCount

The number of alternate names in the array.

Return value
C++
If the method succeeds, the method returns S_OK.
If the method fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.
VB
The return value is the number of alternate names in the array.

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header certenc.h (include Certsrv.h)

Librar y Certidl.lib

DLL Certenc.dll

See also
ICertEncodeAltName
 ICertEncodeAltName::Reset method (certenc.h)
7/2/2022 • 2 minutes to read • Edit Online

The Reset method specifies the size of the alternate name array in this object. The value of all elements in the
array are set to zero.

Syntax
HRESULT Reset(
[in] LONG NameCount
);

Parameters
[in] NameCount

Specifies the number of elements in the array.

Return value
VB
If the method succeeds, the method returns S_OK.
If the method fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header certenc.h (include Certsrv.h)

Librar y Certidl.lib

DLL Certenc.dll

See also
ICertEncodeAltName
 ICertEncodeAltName::SetNameEntry method
(certenc.h)
7/2/2022 • 2 minutes to read • Edit Online

The SetNameEntr y method sets a name at a specified index of the alternate name array.
Before using this method, you must call ICertEncodeAltName::Reset so that the object knows how many
elements are in the array.

Syntax
HRESULT SetNameEntry(
[in] LONG NameIndex,
[in] LONG NameChoice,
[in] const BSTR strName
);

Parameters
[in] NameIndex

Zero-based index that specifies the index of the alternate name entry to set.
If the NameChoice parameter is CERT_ALT_NAME_OTHER_NAME, OR (|) the index value with
EAN_NAMEOBJECTID (defined as 0x80000000) to set the OID. Otherwise, the binary value is set.
[in] NameChoice

Specifies the name choice. The name choice indicates the type of the alternate name so that it can be used
correctly. It must be one of the following values.

VA L UE M EA N IN G

The name is a directory name.

CERT_ALT_NAME_DIRECTORY_NAME

The name is an IA5 string specifying a DNS (Domain Name

CERT_ALT_NAME_DNS_NAME System) name in the format host.entity.domain.

The name is an octet string that represents an Internet

CERT_ALT_NAME_IP_ADDRESS Protocol address.

The name is a registered object identifier (OID).

CERT_ALT_NAME_REGISTERED_ID

The name is an email address.

CERT_ALT_NAME_RFC822_NAME
 The name is an IA5 string that contains a URL in the format
CERT_ALT_NAME_URL Service://HostName/Path.

The name consists of an object identifier (OID) and a binary

CERT_ALT_NAME_OTHER_NAME BLOB.

[in] strName

Specifies the alternate name.

Return value
VB
If the method succeeds, the method returns S_OK.
If the method fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header certenc.h (include Certsrv.h)

Librar y Certidl.lib

DLL Certenc.dll

See also
ICertEncodeAltName
 ICertEncodeBitString interface (certenc.h)
7/2/2022 • 2 minutes to read • Edit Online

The ICer tEncodeBitString interface provides methods for handling bit strings used in certificate extensions. A
certificate extension can be created by using a bit string stored in an extension handler COM object instantiated
by the policy module. The bit string can contain an arbitrary string of binary values. This interface is useful for
encoding and decoding szOID_KEY_USAGE "2.5.29.15" extensions; the SDK sample policy module uses this
interface.
ICer tEncodeBitString is defined in Certenc.h. When you create your program, however, use Certsrv.h as the
include file. Certenc.dll provides the ICer tEncodeBitString interface. The type information for this interface is
also in Certencl.dll, which is shipped with the Platform Software Development Kit (SDK).
Certificate Services interfaces support both apartment-threading and free-threading models. For better
throughput, free threading is recommended.

Inheritance
The ICer tEncodeBitString interface inherits from the IDispatch interface. ICer tEncodeBitString also has
these types of members:

Methods
The ICer tEncodeBitString interface has these methods.

ICertEncodeBitString::Decode

Decodes an Abstract Syntax Notation One (ASN.1)-encoded bit string and stores the resulting bit string in this object.

ICertEncodeBitString::Encode

Performs Abstract Syntax Notation One (ASN.1) encoding on a given bit string.

ICertEncodeBitString::GetBitCount

Returns the number of bits in a bit string that belongs to the CertEncodeBitString object and has been initialized by an earlier
call to ICertEncodeBitString::Decode.

ICertEncodeBitString::GetBitString

Returns the string of bits in the object's bit string.

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]
Target Platform Windows

Header certenc.h (include Certsrv.h)

 ICertEncodeBitString::Decode method (certenc.h)
7/2/2022 • 2 minutes to read • Edit Online

The Decode method decodes an Abstract Syntax Notation One (ASN.1)-encoded bit string and stores the
resulting bit string in this object. You can then call the ICertEncodeBitString::GetBitCount and
ICertEncodeBitString::GetBitString methods to retrieve the bit string and its size.

Syntax
HRESULT Decode(
[in] const BSTR strBinary
);

Parameters
[in] strBinary

An ASN.1-encoded bit string.

Return value
VB
If the method succeeds, the method returns S_OK.
If the method fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.

Remarks
Use this method to decode an encoded bit string.
Examples
For an example that calls the Decode method, see the ICertEncodeBitString::Encode method.

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header certenc.h (include Certsrv.h)

Librar y Certidl.lib

DLL Certenc.dll
See also
ICertEncodeBitString
ICertEncodeBitString::Encode
 ICertEncodeBitString::Encode method (certenc.h)
7/2/2022 • 2 minutes to read • Edit Online

The Encode method performs Abstract Syntax Notation One (ASN.1) encoding on a given bit string.

Syntax
HRESULT Encode(
[in] LONG BitCount,
[in] BSTR strBitString,
[out] BSTR *pstrBinary
);

Parameters
[in] BitCount

The number of bits in strBitString.

[in] strBitString

The bit string to encode.

[out] pstrBinary

A pointer to a BSTR that will contain the encoded bit string. When you have finished using this BSTR , call the
SysFreeString function to free pbstrBinary.

Return value
C++
If the method succeeds, the method returns S_OK.
If the method fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.
VB
The return value is the ASN.1-encoded bit string.

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header certenc.h (include Certsrv.h)

 Librar y Certidl.lib

DLL Certenc.dll

See also
ICertEncodeBitString
ICertEncodeBitString::Decode
 ICertEncodeBitString::GetBitCount method
(certenc.h)
7/2/2022 • 2 minutes to read • Edit Online

The GetBitCount method returns the number of bits in a bit string that belongs to the CertEncodeBitString
object and has been initialized by an earlier call to ICertEncodeBitString::Decode.

Syntax
HRESULT GetBitCount(
[out] LONG *pBitCount
);

Parameters
[out] pBitCount

A pointer to a Long that will receive the number of bits in the bit string.

Return value
C++
If the method succeeds, the method returns S_OK.
If the method fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.
VB
The return value is the number of bits in the bit string.

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header certenc.h (include Certsrv.h)

Librar y Certidl.lib

DLL Certenc.dll

See also
ICertEncodeBitString
 ICertEncodeBitString::GetBitString method
(certenc.h)
7/2/2022 • 2 minutes to read • Edit Online

The GetBitString method returns the string of bits in the object's bit string.

Syntax
HRESULT GetBitString(
[out] BSTR *pstrBitString
);

Parameters
[out] pstrBitString

A pointer to a BSTR that will contain the bit string. When you have finished using the BSTR , free it by calling the
SysFreeString function.

Return value
C++
If the method succeeds, the method returns S_OK.
If the method fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.
VB
The return value is the bit string.

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header certenc.h (include Certsrv.h)

Librar y Certidl.lib

DLL Certenc.dll

See also
ICertEncodeBitString
 ICertEncodeCRLDistInfo interface (certenc.h)
7/2/2022 • 2 minutes to read • Edit Online

The ICer tEncodeCRLDistInfo interface provides methods for handling certificate revocation list (CRL)
distribution information arrays used in certificate extensions.
A certificate extension can be created by using a CRL distribution information array stored in an extension
handler COM object instantiated by the policy module. Each element in the array is a CRL distribution point
structure that contains an array of names and name choices. This interface is useful for encoding and decoding
szOID_CRL_DIST_POINTS "2.5.29.31" extensions; the SDK sample policy module uses this interface.
ICer tEncodeCRLDistInfo is defined in Certenc.h. When you create your program, however, use Certsrv.h as
the include file. Certenc.dll provides the ICer tEncodeCRLDistInfo interface. The type information for this
interface is also in Certencl.dll, which is shipped with the Platform Software Development Kit (SDK).
Certificate Services interfaces support both apartment-threading and free-threading models. For better
throughput, free threading is recommended.

Inheritance
The ICer tEncodeCRLDistInfo interface inherits from the IDispatch interface. ICer tEncodeCRLDistInfo also
has these types of members:

Methods
The ICer tEncodeCRLDistInfo interface has these methods.

ICertEncodeCRLDistInfo::Decode

Decodes an Abstract Syntax Notation One (ASN.1)-encoded certificate revocation list (CRL) distribution information extension
and stores the resulting array in the COM object.

ICertEncodeCRLDistInfo::Encode

Performs Abstract Syntax Notation One (ASN.1) encoding on a certificate revocation list (CRL) distribution information array
stored in the COM object and returns the ASN.1-encoded extension.

ICertEncodeCRLDistInfo::GetDistPointCount

Returns the number of certificate revocation list (CRL) distribution points in a CRL distribution information array.

ICertEncodeCRLDistInfo::GetName

Returns the name at a specified index of a certificate revocation list (CRL) distribution information point.

ICertEncodeCRLDistInfo::GetNameChoice

Returns the name choice at a specified index of a certificate revocation list (CRL) distribution information point.
 ICertEncodeCRLDistInfo::GetNameCount

Returns the number of names in a certificate revocation list (CRL) distribution point.

ICertEncodeCRLDistInfo::Reset

Resets a certificate revocation list (CRL) distribution information array to a specified number of distribution point structures.

ICertEncodeCRLDistInfo::SetNameCount

Sets a name count for the specified distribution point in a certificate revocation list (CRL) distribution information array.

ICertEncodeCRLDistInfo::SetNameEntry

Sets a name at a specified index of a distribution point in a certificate revocation list (CRL) distribution information array.

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header certenc.h (include Certsrv.h)

 ICertEncodeCRLDistInfo::Decode method
(certenc.h)
7/2/2022 • 2 minutes to read • Edit Online

The Decode method decodes an Abstract Syntax Notation One (ASN.1)-encoded certificate revocation list (CRL)
distribution information extension and stores the resulting array in the COM object.

Syntax
HRESULT Decode(
[in] const BSTR strBinary
);

Parameters
[in] strBinary

An ASN.1-encoded CRL distribution information extension.

Return value
VB
If the method succeeds, the method returns S_OK.
If the method fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.

Remarks
This method places the decoded contents of strBinary into the object's array of CRL distribution information
points. If the object's array already contains data, this existing content will be freed, and the array will be loaded
with the decoded values.
Examples
For an example that uses the Decode method, see the ICertEncodeCRLDistInfo::Encode method.

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header certenc.h (include Certsrv.h)

Librar y Certidl.lib
 DLL Certenc.dll

See also
ICertEncodeCRLDistInfo
ICertEncodeCRLDistInfo::Encode
 ICertEncodeCRLDistInfo::Encode method
(certenc.h)
7/2/2022 • 2 minutes to read • Edit Online

The Encode method performs Abstract Syntax Notation One (ASN.1) encoding on a certificate revocation list
(CRL) distribution information array stored in the COM object and returns the ASN.1-encoded extension.
Before using this method, you must call the Reset method to size the array and the SetNameCount and
SetNameEntry methods to set each element in each distribution point structure.

Syntax
HRESULT Encode(
[out] BSTR *pstrBinary
);

Parameters
[out] pstrBinary

A pointer to a BSTR that will contain the encoded CRL distribution information extension. When you have
finished using the BSTR , free it by calling the SysFreeString function.

Return value
C++
If the method succeeds, the method returns S_OK.
If the method fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.
VB
The return value is the ASN.1-encoded string that represents the CRL distribution information array.

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header certenc.h (include Certsrv.h)

Librar y Certidl.lib

DLL Certenc.dll
See also
ICertEncodeCRLDistInfo
ICertEncodeCRLDistInfo::Reset
ICertEncodeCRLDistInfo::SetNameCount
ICertEncodeCRLDistInfo::SetNameEntry
 ICertEncodeCRLDistInfo::GetDistPointCount
method (certenc.h)
7/2/2022 • 2 minutes to read • Edit Online

The GetDistPointCount method returns the number of certificate revocation list (CRL) distribution points in a
CRL distribution information array.

Syntax
HRESULT GetDistPointCount(
[out] LONG *pDistPointCount
);

Parameters
[out] pDistPointCount

A pointer to a LONG that will represent the number of CRL distribution points in the array.

Return value
C++
If the method succeeds, the method returns S_OK.
If the method fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.
VB
The return value is the number of CRL distribution points in the array.

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header certenc.h (include Certsrv.h)

Librar y Certidl.lib

DLL Certenc.dll

See also
ICertEncodeCRLDistInfo
ICertEncodeCRLDistInfo::GetNameCount
ICertEncodeCRLDistInfo::Reset
 ICertEncodeCRLDistInfo::GetName method
(certenc.h)
7/2/2022 • 2 minutes to read • Edit Online

The GetName method returns the name at a specified index of a certificate revocation list (CRL) distribution
information point.

Syntax
HRESULT GetName(
[in] LONG DistPointIndex,
[in] LONG NameIndex,
[out] BSTR *pstrName
);

Parameters
[in] DistPointIndex

Specifies the index of the distribution point for which to get a name. The first value is at index zero.
[in] NameIndex

Specifies the index of the name entry to get. The first value is at index zero.
[out] pstrName

A pointer to a BSTR that represents the name value. When you have finished using the BSTR , free it by calling
the SysFreeString function.

Return value
C++
If the method succeeds, the method returns S_OK.
If the method fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.
VB
The return value is the name at the specified index of the specified distribution point. The return value is a Unicode
string.

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]
 Target Platform Windows

Header certenc.h (include Certsrv.h)

Librar y Certidl.lib

DLL Certenc.dll

See also
ICertEncodeCRLDistInfo
ICertEncodeCRLDistInfo::GetNameCount
ICertEncodeCRLDistInfo::SetNameEntry
 ICertEncodeCRLDistInfo::GetNameChoice method
(certenc.h)
7/2/2022 • 2 minutes to read • Edit Online

The GetNameChoice method returns the name choice at a specified index of a certificate revocation list (CRL)
distribution information point.

Syntax
HRESULT GetNameChoice(
[in] LONG DistPointIndex,
[in] LONG NameIndex,
[out] LONG *pNameChoice
);

Parameters
[in] DistPointIndex

Specifies the index of the distribution point for which to get a name choice. The first value is at index zero.
[in] NameIndex

Specifies the index of the name choice entry to get. The first value is at index zero.
[out] pNameChoice

A pointer to a Long that represents the name choice.

Return value
C++
If the method succeeds, the method returns S_OK.
If the method fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.
VB
The return value is the name choice at the specified index. The name choice indicates the type of the name so that it
can be used correctly. The name choice must be one of the following values.
RET URN C O DE DESC RIP T IO N

The name is an email address.

CERT_ALT_NAME_RFC822_NAME

The name is an IA5 string that contains a DNS (Domain

CERT_ALT_NAME_DNS_NAME Name System) name in the format Host. Entity. Domain.
 The name is an IA5 string that contains a URL in the format
CERT_ALT_NAME_URL Service://HostName/Path.

The name is a registered object identifier (OID).

CERT_ALT_NAME_REGISTERED_ID

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header certenc.h (include Certsrv.h)

Librar y Certidl.lib

DLL Certenc.dll

See also
ICertEncodeCRLDistInfo
ICertEncodeCRLDistInfo::SetNameEntry
 ICertEncodeCRLDistInfo::GetNameCount method
(certenc.h)
7/2/2022 • 2 minutes to read • Edit Online

The GetNameCount method returns the number of names in a certificate revocation list (CRL) distribution
point.

Syntax
HRESULT GetNameCount(
[in] LONG DistPointIndex,
[out] LONG *pNameCount
);

Parameters
[in] DistPointIndex

Specifies the index of the distribution point for which to get the name count.
[out] pNameCount

A pointer to a Long that will represent the number of name values contained in the CRL distribution point.

Return value
C++
If the method succeeds, the method returns S_OK.
If the method fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.
VB
The return value is the number of names in the CRL distribution point.

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header certenc.h (include Certsrv.h)

Librar y Certidl.lib
 DLL Certenc.dll

See also
ICertEncodeCRLDistInfo
ICertEncodeCRLDistInfo::GetDistPointCount
ICertEncodeCRLDistInfo::GetName
ICertEncodeCRLDistInfo::SetNameCount
 ICertEncodeCRLDistInfo::Reset method (certenc.h)
7/2/2022 • 2 minutes to read • Edit Online

The Reset method resets a certificate revocation list (CRL) distribution information array to a specified number
of distribution point structures.
The values of all the elements in the array of structures are set to zero.

Syntax
HRESULT Reset(
[in] LONG DistPointCount
);

Parameters
[in] DistPointCount

Specifies the number of CRL distribution points in the CRL distribution information array.

Return value
VB
If the method succeeds, the method returns S_OK.
If the method fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header certenc.h (include Certsrv.h)

Librar y Certidl.lib

DLL Certenc.dll

See also
ICertEncodeCRLDistInfo
ICertEncodeCRLDistInfo::GetDistPointCount
 ICertEncodeCRLDistInfo::SetNameCount method
(certenc.h)
7/2/2022 • 2 minutes to read • Edit Online

The SetNameCount method sets a name count for the specified distribution point in a certificate revocation list
(CRL) distribution information array.

Syntax
HRESULT SetNameCount(
[in] LONG DistPointIndex,
[in] LONG NameCount
);

Parameters
[in] DistPointIndex

Specifies the index of the distribution point for which to set the name count.
[in] NameCount

Specifies the name count.

Return value
VB
If the method succeeds, the method returns S_OK.
If the method fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header certenc.h (include Certsrv.h)

Librar y Certidl.lib

DLL Certenc.dll

See also
ICertEncodeCRLDistInfo
ICertEncodeCRLDistInfo::GetNameCount
ICertEncodeCRLDistInfo::SetNameEntry
 ICertEncodeCRLDistInfo::SetNameEntry method
(certenc.h)
7/2/2022 • 2 minutes to read • Edit Online

The SetNameEntr y method sets a name at a specified index of a distribution point in a certificate revocation
list (CRL) distribution information array.

Syntax
HRESULT SetNameEntry(
[in] LONG DistPointIndex,
[in] LONG NameIndex,
[in] LONG NameChoice,
[in] const BSTR strName
);

Parameters
[in] DistPointIndex

Specifies the index of the CRL distribution point for which to set the name. The first value is at index zero.
[in] NameIndex

Specifies the index of the name entry to set. The first value is at index zero.
[in] NameChoice

Specifies the name choice of the name being set. The name choice indicates the type of the name so that it can
be used correctly. The name choice must be one of the following values.

VA L UE M EA N IN G

The name is an email address.

CERT_ALT_NAME_RFC822_NAME

The name is an IA5 string specifying a DNS (Domain Name

CERT_ALT_NAME_DNS_NAME System) name in the format host.entity.domain.

The name is an IA5 string specifying a URL in the format

CERT_ALT_NAME_URL Service://HostName/Path.

The name is a registered object identifier (OID).

CERT_ALT_NAME_REGISTERED_ID

[in] strName

Specifies the name.

Return value
VB
If the method succeeds, the method returns S_OK.
If the method fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header certenc.h (include Certsrv.h)

Librar y Certidl.lib

DLL Certenc.dll

See also
ICertEncodeCRLDistInfo
ICertEncodeCRLDistInfo::GetName
ICertEncodeCRLDistInfo::GetNameChoice
ICertEncodeCRLDistInfo::SetNameCount
 ICertEncodeDateArray interface (certenc.h)
7/2/2022 • 2 minutes to read • Edit Online

The ICer tEncodeDateArray interface provides methods for handling Date arrays used in certificate
extensions.
A certificate extension can be created by using a Date array stored in an extension handler COM object
instantiated by the policy module. Each element in the array is a Date value.
This interface is provided mainly as a demonstration for encoding custom extensions. The Certificate Services
sample programs in the Platform Software Development Kit (SDK) contain source code for this interface.
ICer tEncodeDateArray is defined in Certenc.h. When you create your program, however, use Certsrv.h as the
include file. Certenc.dll provides the ICer tEncodeDateArray interface. The type information for this interface is
also in Certencl.dll, which is shipped with the Platform SDK.
Certificate Services interfaces support both apartment-threading and free-threading models. For better
throughput, free threading is recommended.

Inheritance
The ICer tEncodeDateArray interface inherits from the IDispatch interface. ICer tEncodeDateArray also has
these types of members:

Methods
The ICer tEncodeDateArray interface has these methods.

ICertEncodeDateArray::Decode

Decodes an Abstract Syntax Notation One (ASN.1)-encoded date array and stores the resulting array of date values in the
CertEncodeDateArray object.

ICertEncodeDateArray::Encode

Returns an Abstract Syntax Notation One (ASN.1)-encoded string of the date array stored in this object.

ICertEncodeDateArray::GetCount

Returns the number of DATE values in the object's DATE array.

ICertEncodeDateArray::GetValue

Returns the specified date from the DATE array.

ICertEncodeDateArray::Reset

Specifies the size of DATE array in this object.

 ICertEncodeDateArray::SetValue

Sets a DATE value at the specified index of the DATE array.

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header certenc.h (include Certsrv.h)

 ICertEncodeDateArray::Decode method (certenc.h)
7/2/2022 • 2 minutes to read • Edit Online

The Decode method decodes an Abstract Syntax Notation One (ASN.1)-encoded date array and stores the
resulting array of date values in the Cer tEncodeDateArray object.

Syntax
HRESULT Decode(
[in] const BSTR strBinary
);

Parameters
[in] strBinary

An ASN.1-encoded DATE array.

Return value
VB
If the method succeeds, the method returns S_OK.
If the method fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.

Remarks
This method places the decoded contents of strBinary into the object's array of date values. If the object's array
already contains date values, this existing content will be freed, and the array will be loaded with the decoded
values.
Examples
For an example that uses the Decode method, see the ICertEncodeDateArray::Encode method.

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header certenc.h (include Certsrv.h)

Librar y Certidl.lib
 DLL Certenc.dll

See also
ICertEncodeDateArray
ICertEncodeDateArray::Encode
 ICertEncodeDateArray::Encode method (certenc.h)
7/2/2022 • 2 minutes to read • Edit Online

The Encode method returns an Abstract Syntax Notation One (ASN.1)-encoded string of the date array stored
in this object.
Use the Decode method to decode the encoded string into an Cer tEncodeDateArray object.
Before using this method, you must call both the Reset method to size the array and the SetValue method to set
each array element.

Syntax
HRESULT Encode(
[out] BSTR *pstrBinary
);

Parameters
[out] pstrBinary

A pointer to a BSTR that will contain the encoded Date array. When you have finished using the BSTR , free it by
calling the SysFreeString function.

Return value
C++
If the method succeeds, the method returns S_OK.
If the method fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.
VB
The return value is the ASN.1-encoded string that represents the DATE array.

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header certenc.h (include Certsrv.h)

Librar y Certidl.lib

DLL Certenc.dll
See also
ICertEncodeDateArray
ICertEncodeDateArray::Decode
ICertEncodeDateArray::Reset
ICertEncodeDateArray::SetValue
 ICertEncodeDateArray::GetCount method
(certenc.h)
7/2/2022 • 2 minutes to read • Edit Online

The GetCount method returns the number of DATE values in the object's DATE array.

Syntax
HRESULT GetCount(
[out] LONG *pCount
);

Parameters
[out] pCount

A pointer to a LONG that receives the number of DATE values contained in the DATE array.

Return value
C++
If the method succeeds, the method returns S_OK.
If the method fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.
VB
The return value is the number of DATE values contained in the DATE array.

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header certenc.h (include Certsrv.h)

Librar y Certidl.lib

DLL Certenc.dll

See also
ICertEncodeDateArray
ICertEncodeDateArray::GetValue
ICertEncodeDateArray::Reset
 ICertEncodeDateArray::GetValue method
(certenc.h)
7/2/2022 • 2 minutes to read • Edit Online

The GetValue method returns the specified date from the DATE array.

Syntax
HRESULT GetValue(
[in] LONG Index,
[out] DATE *pValue
);

Parameters
[in] Index

The zero-based index that specifies the date to retrieve.

[out] pValue

A pointer to a DATE variable that receives the date.

Return value
C++
If the method succeeds, the method returns S_OK.
If the method fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.
VB
The return value is the DATE value at the specified index.

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header certenc.h (include Certsrv.h)

Librar y Certidl.lib

DLL Certenc.dll
See also
ICertEncodeDateArray
ICertEncodeDateArray::GetCount
ICertEncodeDateArray::SetValue
 ICertEncodeDateArray::Reset method (certenc.h)
7/2/2022 • 2 minutes to read • Edit Online

The Reset method specifies the size of DATE array in this object. The values of all the elements in the array are
set to zero. You must call this method before calling the ICertEncodeDateArray::SetValue method for the first
time.

Syntax
HRESULT Reset(
[in] LONG Count
);

Parameters
[in] Count

Specifies the number of elements in the DATE array.

Return value
VB
If the method succeeds, the method returns S_OK.
If the method fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header certenc.h (include Certsrv.h)

Librar y Certidl.lib

DLL Certenc.dll

See also
ICertEncodeDateArray
ICertEncodeDateArray::SetValue
 ICertEncodeDateArray::SetValue method (certenc.h)
7/2/2022 • 2 minutes to read • Edit Online

The SetValue method sets a DATE value at the specified index of the DATE array.
You must call the ICertEncodeDateArray::Reset method before calling SetValue for the first time.

Syntax
HRESULT SetValue(
[in] LONG Index,
[in] DATE Value
);

Parameters
[in] Index

The zero-based index that specifies the index of the date element to set.
[in] Value

Specifies the DATE value to set.

Return value
VB
If the method succeeds, the method returns S_OK.
If the method fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header certenc.h (include Certsrv.h)

Librar y Certidl.lib

DLL Certenc.dll

See also
ICertEncodeDateArray
ICertEncodeDateArray::GetValue
ICertEncodeDateArray::Reset
 ICertEncodeLongArray interface (certenc.h)
7/2/2022 • 2 minutes to read • Edit Online

The ICer tEncodeLongArray interface provides methods for handling Long arrays used in certificate
extensions.
A certificate extension can be created by using a Long array stored in an extension handler COM object
instantiated by the policy module. Each element in the array is a Long value.
This interface is provided mainly as a demonstration for encoding custom extensions. The Certificate Services
sample programs in the Platform Software Development Kit (SDK) contain source code for this interface.
ICer tEncodeLongArray is defined in Certenc.h. When you create your program, however, use Certsrv.h as the
include file. Certenc.dll provides the ICer tEncodeLongArray interface. The type information for this interface is
also in Certencl.dll, which is shipped with the Platform SDK.
Certificate Services interfaces support both apartment-threading and free-threading models. For better
throughput, free threading is recommended.

Inheritance
The ICer tEncodeLongArray interface inherits from the IDispatch interface. ICer tEncodeLongArray also has
these types of members:

Methods
The ICer tEncodeLongArray interface has these methods.

ICertEncodeLongArray::Decode

Decodes an Abstract Syntax Notation One (ASN.1)-encoded Long array and stores the resulting array of Long values in the
CertEncodeLongArray object.

ICertEncodeLongArray::Encode

Returns an ASN.1-encoded string of the LONG array stored in this object.

ICertEncodeLongArray::GetCount

Returns the number of Long values in the object's Long array.

ICertEncodeLongArray::GetValue

Returns the specified Long value from the Long array.

ICertEncodeLongArray::Reset

Specifies the size of the array in this object.

 ICertEncodeLongArray::SetValue

Sets a Long value at the specified index of the Long array.

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header certenc.h (include Certsrv.h)

 ICertEncodeLongArray::Decode method (certenc.h)
7/2/2022 • 2 minutes to read • Edit Online

The Decode method decodes an Abstract Syntax Notation One (ASN.1)-encoded Long array and stores the
resulting array of Long values in the Cer tEncodeLongArray object.

Syntax
HRESULT Decode(
[in] const BSTR strBinary
);

Parameters
[in] strBinary

An ASN.1-encoded Long array.

Return value
VB
If the method succeeds, the method returns S_OK.
If the method fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.

Remarks
This method places the decoded contents of strBinary into the object's array of Long values. If the object's array
already contains Long values, the existing content will be freed, and the array will be loaded with the decoded
values.
Examples
For an example that uses the Decode method, see the ICertEncodeLongArray::Encode method.

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header certenc.h (include Certsrv.h)

Librar y Certidl.lib
 DLL Certenc.dll

See also
ICertEncodeLongArray
ICertEncodeLongArray::Encode
 ICertEncodeLongArray::Encode method (certenc.h)
7/2/2022 • 2 minutes to read • Edit Online

The Encode method returns an ASN.1-encoded string of the LONG array stored in this object.
Use the Decode method to decode the encoded string into an Cer tEncodeLongArray object.
Before calling the Encode method, you must call the Reset method to size the array and the SetValue method to
set each LONG value in the array.

Syntax
HRESULT Encode(
[out] BSTR *pstrBinary
);

Parameters
[out] pstrBinary

A pointer to a BSTR that will contain the encoded LONG array. When you have finished using the BSTR , free it
by calling the SysFreeString function.

Return value
C++
If the method succeeds, the method returns S_OK.
If the method fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.
VB
The return value is the ASN.1-encoded LONG array.

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header certenc.h (include Certsrv.h)

Librar y Certidl.lib

DLL Certenc.dll
See also
ICertEncodeLongArray
ICertEncodeLongArray::Decode
ICertEncodeLongArray::Reset
ICertEncodeLongArray::SetValue
 ICertEncodeLongArray::GetCount method
(certenc.h)
7/2/2022 • 2 minutes to read • Edit Online

The GetCount method returns the number of Long values in the object's Long array.

Syntax
HRESULT GetCount(
[out] LONG *pCount
);

Parameters
[out] pCount

A pointer to a Long that receives the number of Long values contained in the Long array.

Return value
C++
If the method succeeds, the method returns S_OK.
If the method fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.
VB
The return value is the number of Long values contained in the Long array.

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header certenc.h (include Certsrv.h)

Librar y Certidl.lib

DLL Certenc.dll

See also
ICertEncodeLongArray
ICertEncodeLongArray::Reset
 ICertEncodeLongArray::GetValue method
(certenc.h)
7/2/2022 • 2 minutes to read • Edit Online

The GetValue method returns the specified Long value from the Long array.

Syntax
HRESULT GetValue(
[in] LONG Index,
[out] LONG *pValue
);

Parameters
[in] Index

The zero-based index that specifies the Long value to retrieve.

[out] pValue

A pointer to a Long variable that receives the value.

Return value
C++
If the method succeeds, the method returns S_OK.
If the method fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.
VB
The return value is the Long value at the specified index.

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header certenc.h (include Certsrv.h)

Librar y Certidl.lib

DLL Certenc.dll
See also
ICertEncodeLongArray
ICertEncodeLongArray::SetValue
 ICertEncodeLongArray::Reset method (certenc.h)
7/2/2022 • 2 minutes to read • Edit Online

The Reset method specifies the size of the array in this object. The values of all the elements in the array are set
to zero. You must call this method before calling the ICertEncodeLongArray::SetValue method for the first time.

Syntax
HRESULT Reset(
[in] LONG Count
);

Parameters
[in] Count

Specifies the number of elements in the Long array.

Return value
VB
If the method succeeds, the method returns S_OK.
If the method fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header certenc.h (include Certsrv.h)

Librar y Certidl.lib

DLL Certenc.dll

See also
ICertEncodeLongArray
 ICertEncodeLongArray::SetValue method (certenc.h)
7/2/2022 • 2 minutes to read • Edit Online

The SetValue method sets a Long value at the specified index of the Long array.
You must call ICertEncodeLongArray::Reset before calling SetValue for the first time.

Syntax
HRESULT SetValue(
[in] LONG Index,
[in] LONG Value
);

Parameters
[in] Index

The zero-based index that specifies the index of the array element to set.
[in] Value

Specifies the Long value to set.

Return value
VB
If the method succeeds, the method returns S_OK.
If the method fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header certenc.h (include Certsrv.h)

Librar y Certidl.lib

DLL Certenc.dll

See also
ICertEncodeLongArray
ICertEncodeLongArray::GetValue
ICertEncodeLongArray::Reset
 ICertEncodeStringArray interface (certenc.h)
7/2/2022 • 2 minutes to read • Edit Online

The ICer tEncodeStringArray interface provides methods for handling string arrays used in certificate
extensions.
A certificate extension can be created by using a string array stored in an extension handler COM object
instantiated by the policy module. Each element in the array is a string value.
This interface is provided mainly as a demonstration for encoding custom extensions. The Certificate Services
sample programs in the Platform Software Development Kit (SDK) contain source code for this interface.
ICer tEncodeStringArray is defined in Certenc.h. When you create your program, however, use Certsrv.h as
the include file. Certenc.dll provides the ICer tEncodeStringArray interface. The type information for this
interface is also in Certencl.dll, which is shipped with the Platform SDK.
Certificate Services interfaces support both apartment-threading and free-threading models. For better
throughput, free threading is recommended.

Inheritance
The ICer tEncodeStringArray interface inherits from the IDispatch interface. ICer tEncodeStringArray also
has these types of members:

Methods
The ICer tEncodeStringArray interface has these methods.

ICertEncodeStringArray::Decode

Decodes an Abstract Syntax Notation One (ASN.1)-encoded string array and stores the resulting array of strings in the
CertEncodeStringArray object.

ICertEncodeStringArray::Encode

Returns an ASN.1-encoded string of the string array stored in this object.

ICertEncodeStringArray::GetCount

Returns the number of string values in the string array.

ICertEncodeStringArray::GetStringType

Returns the type of string values that the string array contains.

ICertEncodeStringArray::GetValue

Returns the specified string from the string array.

 ICertEncodeStringArray::Reset

Specifies the size of the string array and the type of strings the array will contain.

ICertEncodeStringArray::SetValue

Sets a string value at the specified index of the string array.

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header certenc.h (include Certsrv.h)

 ICertEncodeStringArray::Decode method (certenc.h)
7/2/2022 • 2 minutes to read • Edit Online

The Decode method decodes an Abstract Syntax Notation One (ASN.1)-encoded string array and stores the
resulting array of strings in the Cer tEncodeStringArray object.

Syntax
HRESULT Decode(
[in] const BSTR strBinary
);

Parameters
[in] strBinary

An ASN.1-encoded string array.

Return value
VB
If the method succeeds, the method returns S_OK.
If the method fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.

Remarks
This method will place the decoded contents of strBinary into the object's array of strings. If the object's array
already contains strings, this existing content will be freed, and the array will be loaded with the decoded values.
Examples
For an example that uses the Decode method, see the ICertEncodeStringArray::Encode method.

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header certenc.h (include Certsrv.h)

Librar y Certidl.lib

DLL Certenc.dll
See also
ICertEncodeStringArray
ICertEncodeStringArray::Encode
 ICertEncodeStringArray::Encode method (certenc.h)
7/2/2022 • 2 minutes to read • Edit Online

The Encode method returns an ASN.1-encoded string of the string array stored in this object.
Use the Decode method to decode the encoded string into an Cer tEncodeStringArray object.
Before using this method, you must call the Reset to size the array and the SetValue method to set each string in
the array.

Syntax
HRESULT Encode(
[out] BSTR *pstrBinary
);

Parameters
[out] pstrBinary

A pointer to a BSTR that will contain the encoded string array. When you have finished using the BSTR , free it
by calling the SysFreeString function.

Return value
C++
If the method succeeds, the method returns S_OK.
If the method fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.
VB
The return value is the ASN.1-encoded string array.

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header certenc.h (include Certsrv.h)

Librar y Certidl.lib

DLL Certenc.dll
See also
ICertEncodeStringArray
ICertEncodeStringArray::Decode
ICertEncodeStringArray::Reset
ICertEncodeStringArray::SetValue
 ICertEncodeStringArray::GetCount method
(certenc.h)
7/2/2022 • 2 minutes to read • Edit Online

The GetCount method returns the number of string values in the string array.

Syntax
HRESULT GetCount(
[out] LONG *pCount
);

Parameters
[out] pCount

A pointer to a LONG that receives the number of string values contained in the string array.

Return value
C++
If the method succeeds, the method returns S_OK.
If the method fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.
VB
The return value is the number of string values contained in the string array.

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header certenc.h (include Certsrv.h)

Librar y Certidl.lib

DLL Certenc.dll

See also
ICertEncodeStringArray
ICertEncodeStringArray::Reset
 ICertEncodeStringArray::GetStringType method
(certenc.h)
7/2/2022 • 2 minutes to read • Edit Online

The GetStringType method returns the type of string values that the string array contains.

Syntax
HRESULT GetStringType(
[out] LONG *pStringType
);

Parameters
[out] pStringType

A pointer to a Long that represents the string type. For a list of string types, see Remarks.

Return value
C++
If the method succeeds, the method returns S_OK.
If the method fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.
VB
The return value indicates the type of strings in the string array. For a list of string types, see Remarks.

Remarks
The following table lists the types of strings that the string array can contain. For more information about RDN
types, see the CryptoAPI 2.0 documents.

ST RIN G T Y P E M EA N IN G

CERT_RDN_ANY_TYPE For encoding an X509_UNICODE_NAME name.

CERT_RDN_NUMERIC_STRING The numerals 0 through 9 and the space character (8 bit).

CERT_RDN_PRINTABLE_STRING Printable characters (8 bit).

CERT_RDN_T61_STRING T.61 encoded characters (8 bit).

CERT_RDN_VIDEOTEX_STRING VIDEOTEX characters.

CERT_RDN_IA5_STRING IA5 (ASCII) characters.

CERT_RDN_GRAPHIC_STRING A string of ISO-defined GRAPHIC characters.

 CERT_RDN_ISO646_STRING 128 character set (8 bit).

CERT_RDN_GENERAL_STRING A string of ISO-defined GENERAL characters.

CERT_RDN_INT4_STRING An array of INT4 values (32 bit).

CERT_RDN_UNICODE_STRING Unicode characters (16 bit).

Examples
For an example that uses the GetStringType method, see the ICertEncodeStringArray::Encode method.

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header certenc.h (include Certsrv.h)

Librar y Certidl.lib

DLL Certenc.dll

See also
ICertEncodeStringArray
ICertEncodeStringArray::Reset
 ICertEncodeStringArray::GetValue method
(certenc.h)
7/2/2022 • 2 minutes to read • Edit Online

The GetValue method returns the specified string from the string array.

Syntax
HRESULT GetValue(
[in] LONG Index,
[out] BSTR *pstr
);

Parameters
[in] Index

The zero-based index that specifies the string to retrieve.

[out] pstr

A pointer to a BSTR that represents the string value. When you have finished using the BSTR , free it by calling
the SysFreeString function.

Return value
C++
If the method succeeds, the method returns S_OK.
If the method fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.
VB
The return value is the string value at the specified index.

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header certenc.h (include Certsrv.h)

Librar y Certidl.lib
 DLL Certenc.dll

See also
ICertEncodeStringArray
ICertEncodeStringArray::GetStringType
ICertEncodeStringArray::SetValue
 ICertEncodeStringArray::Reset method (certenc.h)
7/2/2022 • 2 minutes to read • Edit Online

The Reset method specifies the size of the string array and the type of strings the array will contain.The values
of all the elements in the string array are set to zero.
You must call this method before calling the ICertEncodeStringArray::SetValue method for the first time.

Syntax
HRESULT Reset(
[in] LONG Count,
[in] LONG StringType
);

Parameters
[in] Count

Specifies the number of elements in the string array.

[in] StringType

Specifies the type of stings that the string array contains. The type must be one of the following values. For more
information about RDN types, see the CryptoAPI 2.0 documents.

VA L UE M EA N IN G

For encoding an X509_UNICODE_NAME name.

CERT_RDN_ANY_TYPE

The characters 0 through 9 and the space character (8 bit).

CERT_RDN_NUMERIC_STRING

Printable characters (8 bit).

CERT_RDN_PRINTABLE_STRING

T.61 encoded characters (8 bit).

CERT_RDN_T61_STRING

VIDEOTEX characters.
CERT_RDN_VIDEOTEX_STRING

IA5 (ASCII) characters.

CERT_RDN_IA5_STRING

A string of ISO-defined GRAPHIC characters.

CERT_RDN_GRAPHIC_STRING
 128 character set (8 bit).
CERT_RDN_ISO646_STRING

A string of ISO-defined GENERAL characters.

CERT_RDN_GENERAL_STRING

An array of INT4 values (32 bit).

CERT_RDN_INT4_STRING

Unicode characters (16 bit).

CERT_RDN_UNICODE_STRING

Return value
VB
If the method succeeds, the method returns S_OK.
If the method fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header certenc.h (include Certsrv.h)

Librar y Certidl.lib

DLL Certenc.dll

See also
ICertEncodeStringArray
 ICertEncodeStringArray::SetValue method
(certenc.h)
7/2/2022 • 2 minutes to read • Edit Online

The SetValue method sets a string value at the specified index of the string array.
You must call the ICertEncodeStringArray::Reset method before calling SetValue for the first time.

Syntax
HRESULT SetValue(
[in] LONG Index,
[in] const BSTR str
);

Parameters
[in] Index

The zero-based index that specifies the element of the string array to set.
[in] str

Specifies the string value to set.

Return value
VB
If the method succeeds, the method returns S_OK.
If the method fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header certenc.h (include Certsrv.h)

Librar y Certidl.lib

DLL Certenc.dll
See also
ICertEncodeStringArray
ICertEncodeStringArray::Reset
 certenroll.h header
7/2/2022 • 10 minutes to read • Edit Online

This header is used by multiple technologies. For more information, see:

Mobile Device Management Settings Provider
Security and Identity
certenroll.h contains the following programming interfaces:

Interfaces

IAlternativeName

Is used by an IX509ExtensionAlternativeNames object to represent an instance of an AlternativeNames extension.

IAlternativeNames

Contains methods and properties that enable you to manage a collection of IAlternativeName objects.

IBinaryConverter

Contains general methods that enable you to create a Unicode-encoded string from a byte array, create a byte array from a
Unicode-encoded string, and modify the type of Unicode encoding applied to a string.

ICertificateAttestationChallenge

Allows applications to decrypt a key attestation challenge received from a server.

ICertificatePolicies

Contains methods and properties that enable you to manage a collection of ICertificatePolicy objects.

ICertificatePolicy

Can be used to specify a certificate policy that identifies a purpose for which the certificate can be used.

ICertificationAuthorities

The ICertificationAuthorities interface defines the following methods and properties that manage a collection of
ICertificationAuthority objects.

ICertificationAuthority

The ICertificationAuthority interface represents a single certification authority. A collection of certification authorities is
represented by the ICertificationAuthorities interface.

ICertProperties

Contains methods and properties that enable you to manage a collection of certificate properties.
ICertProperty

Can be used to associate an external property with a certificate.

ICertPropertyArchived

Represents a certificate property that identifies whether a certificate has been archived.

ICertPropertyArchivedKeyHash

Represents a SHA-1 hash of an encrypted private key submitted to a certification authority for archival.

ICertPropertyAutoEnroll

Represents a certificate property that identifies a template that has been configured to enable autoenrollment of the
certificate.

ICertPropertyBackedUp

Represents an external certificate property that identifies whether a certificate has been backed up and, if so, the date and
time that it was saved.

ICertPropertyDescription

Enables you to specify and retrieve a string that contains descriptive information for a certificate.

ICertPropertyEnrollment

Represents a certificate property that contains certificate and certification authority (CA) information created when the client
calls the Enroll method on the IX509Enrollment interface.

ICertPropertyEnrollmentPolicyServer

Represents an external certificate property that contains information about a certificate enrollment policy (CEP) server and a
certificate enrollment server (CES).

ICertPropertyFriendlyName

Enables you to specify and retrieve a string that contains the display name of a certificate.

ICertPropertyKeyProvInfo

Represents a certificate property that contains information about a private key.

ICertPropertyRenewal

Represents a certificate property that contains a SHA-1 hash of the new certificate created when an existing certificate is
renewed.

ICertPropertyRequestOriginator

Represents a certificate property that contains the Domain Naming System (DNS) name of the computer on which the request
was created.
ICertPropertySHA1Hash

Represents a certificate property that contains a SHA-1 hash of the certificate.

ICryptAttribute

The ICryptAttribute interface represents a cryptographic attribute in a certificate request. A collection of these attributes is
contained in the CertificateRequestInfo structure of a PKCS

ICryptAttributes

The ICryptAttributes interface contains methods and properties that enable you to manage a collection of ICryptAttribute
objects.

ICspAlgorithm

Represents an algorithm implemented by a cryptographic provider.

ICspAlgorithms

The ICspAlgorithms interface defines the following methods and properties that manage a collection of ICspAlgorithm objects.

ICspInformation

Provides access to general information about a cryptographic provider.

ICspInformations

The ICspInformations interface defines the following methods and properties to manage a collection of ICspInformation
objects.

ICspStatus

Contains information about a cryptographic provider/algorithm pair.

ICspStatuses

Contains information about a cryptographic provider/algorithm pair.

IObjectId

Represents an object identifier (OID).

IObjectIds

The IObjectIds interface defines methods and properties that enable you to manage a collection of IObjectId objects.

IPolicyQualifier

Represents a qualifier that can be associated with a certificate policy.

IPolicyQualifiers

Defines methods and properties that enable you to manage a collection of IPolicyQualifier objects.
ISignerCertificate

Represents a signing certificate that enables you to sign a certificate request.

ISignerCertificates

The ISignerCertificates interface defines the following methods and properties to manage a collection of ISignerCertificate
objects.

ISmimeCapabilities

Defines the following methods and properties to manage a collection of ISmimeCapability objects.

ISmimeCapability

Represents an SMIMECapabilities extension that identifies the decryption capabilities of an email recipient.

IX500DistinguishedName

Represents an X.500 distinguished name (DN).

IX509Attribute

Can be used to represent an attribute in a PKCS

IX509AttributeArchiveKey

Represents an attribute that contains an encrypted private key to be archived by a certification authority.

IX509AttributeArchiveKeyHash

Represents an attribute that contains a SHA-1 hash of the encrypted private key to be archived by a certification authority.

IX509AttributeClientId

Represents an attribute that can be used to identify the client that generated a certificate request.

IX509AttributeCspProvider

Represents an attribute that identifies the cryptographic provider used by the entity requesting the certificate.

IX509AttributeExtensions

Defines methods and properties that initialize and retrieve certificate extensions in a certificate request.

IX509AttributeOSVersion

Represents an attribute that contains version information about the client operating system on which the certificate request
was generated.

IX509AttributeRenewalCertificate

Represents an attribute that contains the certificate being renewed. This attribute is automatically placed in the PKCS
IX509Attributes

The IX509Attributes interface defines the following methods and properties that enable you to manage a collection of
IX509Attribute objects.

IX509CertificateRequest

The IX509CertificateRequest interface represents an abstract base certificate request that identifies methods and properties
common to and inherited by each of the request objects implemented by the Certificate Enrollment API.

IX509CertificateRequestCertificate

The IX509CertificateRequestCertificate interface represents a request object for a self-generated certificate, enabling you to
create a certificate directly without going through a registration or certification authority.

IX509CertificateRequestCertificate2

The IX509CertificateRequestCertificate2 interface represents a request object for a self-generated certificate, enabling you to
create a certificate directly without going through a registration or certification authority.

IX509CertificateRequestCmc

Represents a CMC (Certificate Management Message over CMS) certificate request.

IX509CertificateRequestCmc2

The IX509CertificateRequestCmc2 interface represents a CMC (Certificate Management Message over CMS) certificate
request.

IX509CertificateRequestPkcs10

The IX509CertificateRequestPkcs10 interface represents a PKCS

IX509CertificateRequestPkcs10V2

The IX509CertificateRequestPkcs10V2 interface represents a PKCS

IX509CertificateRequestPkcs10V3

The IX509CertificateRequestPkcs10V3 interface represents a PKCS

IX509CertificateRequestPkcs7

The IX509CertificateRequestPkcs7 interface represents a PKCS

IX509CertificateRequestPkcs7V2

The IX509CertificateRequestPkcs7V2 interface represents a PKCS

IX509CertificateTemplate

The IX509CertificateTemplate interface represents a certificate request template. It can be used to initialize an
IX509CertificateTemplateWritable interface.
IX509CertificateTemplates

The IX509CertificateTemplates interface defines the following methods and properties that manage a collection of
IX509CertificateTemplate objects.

IX509CertificateTemplateWritable

The IX509CertificateTemplateWritable interface enables you to add a template to or delete it from a template store. Currently,
Active Directory is the only available store.

IX509EndorsementKey

X.509 Endorsement Key Interface

IX509Enrollment

Represents the top level object and enables you to enroll in a certificate hierarchy and install a certificate response.

IX509Enrollment2

The IX509Enrollment2 interface enables you to enroll in a certificate hierarchy and install a certificate response.

IX509EnrollmentHelper

The IX509EnrollmentHelper interface defines methods that enable a web application to enroll a certificate, store policy server
credentials in the credential cache, and register policy servers and enrollment servers.

IX509EnrollmentPolicyServer

The IX509EnrollmentPolicyServer interface represents a certificate enrollment policy (CEP) server.

IX509EnrollmentStatus

The IX509EnrollmentStatus interface can be used to specify or retrieve detailed error information about a certificate enrollment
transaction.

IX509EnrollmentWebClassFactory

Can be used to create any of the following objects on a webpage.

IX509Extension

Can be used to define an extension for a certificate request.

IX509ExtensionAlternativeNames

Enables you to specify one or more alternative name forms for the subject of a certificate. A certification authority processes
the extension by binding the names to the certified public key.

IX509ExtensionAuthorityKeyIdentifier

Enables you to specify an AuthorityKeyIdentifier extension.

IX509ExtensionBasicConstraints

Enables you to specify whether the certificate subject is a certification authority and, if so, the depth of the subordinate
certification authority chain that can exist beneath the certification authority for which this extension ID is defined.

IX509ExtensionCertificatePolicies

Enables you to specify a collection of policy information terms, each of which consists of an object identifier (OID) and optional
policy qualifiers. A single policy term is defined by an ICertificatePolicy object.

IX509ExtensionEnhancedKeyUsage

Can be used to define a collection of object identifiers (OIDs) that identify the intended uses of the public key contained in the
certificate.

IX509ExtensionKeyUsage

Can be used to define restrictions on the operations that can be performed by the public key contained in the certificate.

IX509ExtensionMSApplicationPolicies

Enables you to specify a collection of object identifiers (OIDs) that indicate how a certificate can be used by an application.

IX509Extensions

The IX509Extensions interface defines the following methods and properties to manage a collection of IX509Extension objects.

IX509ExtensionSmimeCapabilities

Can be used to report the decryption capabilities of an email recipient to an email sender so that the sender can choose the
most secure algorithm supported by both parties.

IX509ExtensionSubjectKeyIdentifier

Enables you to specify a SubjectKeyIdentifier extension.

IX509ExtensionTemplate

Defines methods and properties that can be used to initialize or retrieve a CertificateTemplate extension.

IX509ExtensionTemplateName

Defines methods and properties that can be used to initialize or retrieve a template name extension.

IX509MachineEnrollmentFactory

Can be used to create an IX509EnrollmentHelper object on a webpage.

IX509NameValuePair

Represents a generic name-value pair.

IX509NameValuePairs

The IX509NameValuePairs interface defines the following methods and properties to manage a collection of
IX509NameValuePair objects.
 IX509PolicyServerListManager

The IX509PolicyServerListManager interface defines the following methods and properties that enable you to manage a
collection of IX509PolicyServerUrl objects.

IX509PolicyServerUrl

The IX509PolicyServerUrl interface can be used to set or retrieve property values associated with the certificate enrollment
policy (CEP) server and to update associated registry values.

IX509PrivateKey

Represents an asymmetric private key that can be used for encryption, signing, and key agreement.

IX509PublicKey

Represents a public key in a public/private key pair.

IX509SCEPEnrollment

X.509 Simple Computer Enrollment Protocol Interface

IX509SignatureInformation

Represents information used to sign a certificate request.

Callback functions

ImportPFXToProvider

Imports a PFX certificate.

ImportPFXToProviderFreeData

Frees PFX certificate context(s).

Enumerations

AlgorithmFlags

Contains flags that can be used to refine the search for a cryptographic algorithm.

AlgorithmOperationFlags

Specifies the operations that an algorithm can perform.

AlgorithmType

Specifies the intended purpose of a cryptographic algorithm supported by a cryptographic provider.

AlternativeNameType

Specifies the alternative name types that can be specified when initializing an IAlternativeName object.

CERTENROLL_OBJECTID

Contains the predefined object identifiers (OIDs) supported by Certificate Enrollment API.

CERTENROLL_PROPERTYID

Contains predefined object identifiers for external properties that can be associated with a certificate in the certificate store.

CommitTemplateFlags

Specifies options for saving and deleting templates.

EncodingType

Specifies the type of encoding applied to a byte array for display purposes.

EnrollmentCAProperty

Specifies certification authority property values.

EnrollmentDisplayStatus

Specifies whether to display enrollment status information in a user interface.

EnrollmentEnrollStatus

Specifies the enrollment status of a certificate request.

EnrollmentPolicyFlags

Specifies group policy flags.

EnrollmentPolicyServerPropertyFlags

Specifies the default policy server.

EnrollmentSelectionStatus

Specifies whether the enrollment status of an object will be monitored during the enrollment process.

EnrollmentTemplateProperty

Contains property values for a given template.

ImportPFXFlags

Flags to use when importing a PFX certificate.

InnerRequestLevel

Specifies the containment level of a certificate request within a PKCS

InstallResponseRestrictionFlags

Contains flags that identify the restrictions placed on the local installation of a certificate chain.

KeyIdentifierHashAlgorithm

Specifies the algorithm used to hash the public key in a certificate request.

ObjectIdGroupId

Specifies the category or group to which an object identifier (OID) belongs.

ObjectIdPublicKeyFlags

Specifies whether a public key algorithm is used for signing or for encryption.

PFXExportOptions

Specifies how much of a certificate chain is included when creating a Personal Information Exchange (PFX) message.

Pkcs10AllowedSignatureTypes

Specifies the type of signature permitted when signing a certificate request.

PolicyQualifierType

Specifies the type of qualifier applied to a certificate policy.

PolicyServerUrlFlags

Contains certificate enrollment policy (CEP) server flags.

PolicyServerUrlPropertyID

Contains values that specify the type of property value to be returned by the GetStringProperty method or set by the
SetStringProperty method on the IX509PolicyServerUrl interface.

RequestClientInfoClientId

Specifies the type of application that created a certificate request.

WebEnrollmentFlags

Specifies web enrollment behavior.

WebSecurityLevel

Specifies whether a web-enabled method or property is safe for scripting.

X500NameFlags

Specifies the display and encoding characteristics of a distinguished name or relative distinguished name (RDN).
X509CertificateEnrollmentContext

Specifies the nature of the end entity for which the certificate is intended.

X509CertificateTemplateEnrollmentFlag

Contains values that specify server and client actions during enrollment.

X509CertificateTemplateGeneralFlag

Contains use and modification information about templates and associated certificates.

X509CertificateTemplatePrivateKeyFlag

Contains values that specify client actions regarding a private key.

X509CertificateTemplateSubjectNameFlag

Contains values that specify server and client actions concerning subject names.

X509EnrollmentPolicyExportFlags

Is used by the Export method on the IX509EnrollmentPolicyServer interface to specify what items to export from the policy
server.

X509EnrollmentPolicyLoadOption

Is used by the LoadPolicy method on the IX509EnrollmentPolicyServer interface to specify how to retrieve policy from the
policy server.

X509KeySpec

Specifies the intended use of a key for a legacy cryptographic service provider (CSP).

X509KeyUsageFlags

Specifies the purpose of a key contained in a certificate.

X509PrivateKeyExportFlags

Specifies the export policy for a private key.

X509PrivateKeyProtection

Specifies the level of private key protection supported by a cryptographic provider.

X509PrivateKeyUsageFlags

Specifies the permitted uses of a private key.

X509PrivateKeyVerify

Specifies whether a user interface is displayed during private key verification and whether verification can proceed if the
cryptographic provider is a smart card provider.
X509ProviderType

Specifies the type of cryptographic provider.

X509RequestInheritOptions

Specifies how keys, extension values, and external properties are inherited when a new request is created from an existing
certificate.

X509RequestType

Specifies the certificate request type.

 AlgorithmFlags enumeration (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The AlgorithmFlags enumeration type contains flags that can be used to refine the search for a cryptographic
algorithm. The only flag currently defined enables retrieval of key wrapping algorithms. This enumeration is
used by the InitializeFromAlgorithmName method on the IObjectId interface.

Syntax
typedef enum AlgorithmFlags {
AlgorithmFlagsNone = 0,
AlgorithmFlagsWrap = 0x1
} ;

Constants

AlgorithmFlagsNone
Value: 0
No flags are specified.

AlgorithmFlagsWrap
Value: 0x1
The algorithm is used for key wrapping. For more information, see InitializeFromAlgorithmName.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Header certenroll.h

See also
CertEnroll Enumerations
CertEnroll Interfaces
ICspAlgorithm
IObjectId
 AlgorithmOperationFlags enumeration (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The AlgorithmOperationFlags enumeration type specifies the operations that an algorithm can perform. This
enumeration is used in the following interfaces to retrieve the operational capabilities of a cryptographic
provider or status information based on those capabilities.
ICspAlgorithm
ICspInformation
ICspInformations
ICspStatuses
The binary format of the flags are as follows.

XCN_NCRYPT_NO_OPERATION = 00000000 00000000 00000000

XCN_NCRYPT_CIPHER_OPERATION = 00000000 00000000 00000001
XCN_NCRYPT_HASH_OPERATION = 00000000 00000000 00000010

XCN_NCRYPT_ASYMMETRIC_ENCRYPTION_OPERATION = 00000000 00000000 00000100

XCN_NCRYPT_SECRET_AGREEMENT_OPERATION = 00000000 00000000 00001000
XCN_NCRYPT_SIGNATURE_OPERATION = 00000000 00000000 00010000
XCN_NCRYPT_ANY_ASYMMETRIC_OPERATION = 00000000 00000000 00011100

XCN_NCRYPT_RNG_OPERATION = 00000000 00000000 00100000

XCN_NCRYPT_PREFER_SIGNATURE_ONLY_OPERATION = 00100000 00000000 00000000

XCN_NCRYPT_PREFER_NON_SIGNATURE_OPERATION = 01000000 00000000 00000000
XCN_NCRYPT_EXACT_MATCH_OPERATION = 10000000 00000000 00000000
XCN_NCRYPT_PREFERENCE_MASK_OPERATION = 11100000 00000000 00000000

Syntax
typedef enum AlgorithmOperationFlags {
XCN_NCRYPT_NO_OPERATION = 0,
XCN_NCRYPT_CIPHER_OPERATION = 0x1,
XCN_NCRYPT_HASH_OPERATION = 0x2,
XCN_NCRYPT_ASYMMETRIC_ENCRYPTION_OPERATION = 0x4,
XCN_NCRYPT_SECRET_AGREEMENT_OPERATION = 0x8,
XCN_NCRYPT_SIGNATURE_OPERATION = 0x10,
XCN_NCRYPT_RNG_OPERATION = 0x20,
XCN_NCRYPT_KEY_DERIVATION_OPERATION = 0x40,
XCN_NCRYPT_ANY_ASYMMETRIC_OPERATION,
XCN_NCRYPT_PREFER_SIGNATURE_ONLY_OPERATION = 0x200000,
XCN_NCRYPT_PREFER_NON_SIGNATURE_OPERATION = 0x400000,
XCN_NCRYPT_EXACT_MATCH_OPERATION = 0x800000,
XCN_NCRYPT_PREFERENCE_MASK_OPERATION = 0xe00000
} ;

Constants
 XCN_NCRYPT_NO_OPERATION
Value: 0
No operation is specified.

XCN_NCRYPT_CIPHER_OPERATION
Value: 0x1
The algorithm can be used for symmetric encryption. This includes the RC2, RC4, Data Encryption Standard (DES), 3DED, and
AES algorithms.

XCN_NCRYPT_HASH_OPERATION
Value: 0x2
The algorithm can be used for hashing. This includes the MD2, MD4, SHA1, SHA256, SHA384, SHA512 MAC, and Hash-Based
Message Authentication Code (HMAC) hashing algorithms.

XCN_NCRYPT_ASYMMETRIC_ENCRYPTION_OPERATION
Value: 0x4
The algorithm can be used for public key encryption. This includes RSA.

XCN_NCRYPT_SECRET_AGREEMENT_OPERATION
Value: 0x8
The algorithm can used for key exchange. This includes the Diffie-Hellman algorithm and ECDH algorithm.

XCN_NCRYPT_SIGNATURE_OPERATION
Value: 0x10
The algorithm can be used for signing. This includes the RSA algorithm, Digital Signature Algorithm (DSA), and ECDSA
algorithm.

XCN_NCRYPT_RNG_OPERATION
Value: 0x20
The algorithm can be used to generate a random number.

XCN_NCRYPT_KEY_DERIVATION_OPERATION
Value: 0x40

XCN_NCRYPT_ANY_ASYMMETRIC_OPERATION
The algorithm can be used for public key encryption, key exchange, and signing. This is a bitwise-OR combination of the
following constants:

XCN_NCRYPT_ASYMMETRIC_ENCRYPTION_OPERATION

XCN_NCRYPT_SECRET_AGREEMENT_OPERATION

XCN_NCRYPT_SIGNATURE_OPERATION

XCN_NCRYPT_PREFER_SIGNATURE_ONLY_OPERATION
Value: 0x200000
Signature algorithms are preferred but not required. An encryption algorithm may be chosen instead. This is used when
searching for cryptographic service provider (CSP) status information based on supported operational capability.
 XCN_NCRYPT_PREFER_NON_SIGNATURE_OPERATION
Value: 0x400000
An encryption algorithm (such as that identified by the XCN_NCRYPT_ANY_ASYMMETRIC_OPERATION or
XCN_NCRYPT_SECRET_AGREEMENT_OPERATION flags) is preferred but not required. A signature algorithm may be
chosen instead. This is used when searching for CSP status information based on supported operational capability.

XCN_NCRYPT_EXACT_MATCH_OPERATION
Value: 0x800000
Only an algorithm that exactly matches the specified operations is selected.

XCN_NCRYPT_PREFERENCE_MASK_OPERATION
Value: 0xe00000
Use to mask the algorithm operation preference.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Header certenroll.h

See also
AlgorithmType
CertEnroll Enumerations
CertEnroll Interfaces
 AlgorithmType enumeration (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The AlgorithmType enumeration type specifies the intended purpose of a cryptographic algorithm supported
by a cryptographic provider. Algorithms are typically classified by use into the following general categories:
Signing
Hashing
Asymmetric encryption
Symmetric encryption
Key exchange
This enumeration is used in the ICspAlgorithm interface.

Syntax
typedef enum AlgorithmType {
XCN_BCRYPT_UNKNOWN_INTERFACE = 0,
XCN_BCRYPT_CIPHER_INTERFACE = 0x1,
XCN_BCRYPT_HASH_INTERFACE = 0x2,
XCN_BCRYPT_ASYMMETRIC_ENCRYPTION_INTERFACE = 0x3,
XCN_BCRYPT_SIGNATURE_INTERFACE = 0x5,
XCN_BCRYPT_SECRET_AGREEMENT_INTERFACE = 0x4,
XCN_BCRYPT_RNG_INTERFACE = 0x6,
XCN_BCRYPT_KEY_DERIVATION_INTERFACE = 0x7
} ;

Constants

XCN_BCRYPT_UNKNOWN_INTERFACE
Value: 0
The algorithm type is not defined.

XCN_BCRYPT_CIPHER_INTERFACE
Value: 0x1
The algorithm is used for symmetric encryption. This includes the RC2, RC4, Data Encryption Standard (DES), 3DED, and AES
algorithms.

XCN_BCRYPT_HASH_INTERFACE
Value: 0x2
The algorithm is used for hashing. This includes the MD2, MD4, SHA1, SHA256, SHA384, SHA512 MAC, and Hash-Based
Message Authentication Code (HMAC) hash algorithms.

XCN_BCRYPT_ASYMMETRIC_ENCRYPTION_INTERFACE
Value: 0x3
The algorithm is used for public key encryption. This includes RSA.
 XCN_BCRYPT_SIGNATURE_INTERFACE
Value: 0x5
The algorithm is used for signing. This includes the RSA algorithm, Digital Signature Algorithm (DSA), and ECDSA algorithm.

XCN_BCRYPT_SECRET_AGREEMENT_INTERFACE
Value: 0x4
The algorithm is used for key exchange. This includes the Diffie-Hellman algorithm and ECDH algorithm.

XCN_BCRYPT_RNG_INTERFACE
Value: 0x6
The algorithm is used to generate a random number.

XCN_BCRYPT_KEY_DERIVATION_INTERFACE
Value: 0x7

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Header certenroll.h

See also
AlgorithmOperationFlags
CertEnroll Enumerations
CertEnroll Interfaces
 AlternativeNameType enumeration (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The AlternativeNameType enumeration specifies the alternative name types that can be specified when
initializing an IAlternativeName object. Alternative names are used to create a version 3 X.509
AlternativeNames extension. You can create this extension by using the IX509ExtensionAlternativeNames
interface.

Syntax
typedef enum AlternativeNameType {
XCN_CERT_ALT_NAME_UNKNOWN = 0,
XCN_CERT_ALT_NAME_OTHER_NAME = 1,
XCN_CERT_ALT_NAME_RFC822_NAME = 2,
XCN_CERT_ALT_NAME_DNS_NAME = 3,
XCN_CERT_ALT_NAME_X400_ADDRESS = 4,
XCN_CERT_ALT_NAME_DIRECTORY_NAME = 5,
XCN_CERT_ALT_NAME_EDI_PARTY_NAME = 6,
XCN_CERT_ALT_NAME_URL = 7,
XCN_CERT_ALT_NAME_IP_ADDRESS = 8,
XCN_CERT_ALT_NAME_REGISTERED_ID = 9,
XCN_CERT_ALT_NAME_GUID = 10,
XCN_CERT_ALT_NAME_USER_PRINCIPLE_NAME = 11
} ;

Constants

XCN_CERT_ALT_NAME_UNKNOWN
Value: 0
The name type is not identified.

XCN_CERT_ALT_NAME_OTHER_NAME
Value: 1
The name consists of an object identifier (OID) and a byte array that contains the name value.

XCN_CERT_ALT_NAME_RFC822_NAME
Value: 2
The name is an email address such as someone@example.com.

XCN_CERT_ALT_NAME_DNS_NAME
Value: 3
The name is a Domain Name System (DNS) name such as MyDomain.Microsoft.com. The format of a DNS name is
Host.Entity.Domain. For more information about DNS, see RFC 1034 (Domain Names—Concepts and Facilities), and RFC 1035
(Domain Names—Implementation and Specification).

XCN_CERT_ALT_NAME_X400_ADDRESS
Value: 4
 XCN_CERT_ALT_NAME_DIRECTORY_NAME
Value: 5
The name is an X.500 directory name such as CN=administrators,CN=users,DC=nttest,DC=microsoft,DC=com.

XCN_CERT_ALT_NAME_EDI_PARTY_NAME
Value: 6

XCN_CERT_ALT_NAME_URL
Value: 7
The name is a URL such as http://www.adatum.com/.

XCN_CERT_ALT_NAME_IP_ADDRESS
Value: 8
The name is an Internet Protocol (IP) address in dotted decimal format 123.456.789.123.

XCN_CERT_ALT_NAME_REGISTERED_ID
Value: 9
The name is an object identifier (OID) registered with the International Standards Organization (ISO).

XCN_CERT_ALT_NAME_GUID
Value: 10
The name is a Directory Service Agent GUID. The GUID identifies a server to the Active Directory replication system as a
domain controller.

XCN_CERT_ALT_NAME_USER_PRINCIPLE_NAME
Value: 11
The name is a user principal name (UPN). A UPN is a user logon name in email address format. That is, a UPN consists of a
shorthand name for a user account followed by the DNS name of the Active Directory tree in which the user object resides. It
has the form UserName@DNS_suffix. An example is UserName@Microsoft.com where Microsoft.com is the DNS suffix and
UserName is a placeholder for a shorthand name assigned by Microsoft to a user account.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Header certenroll.h

See also
CertEnroll Enumerations
CertEnroll Interfaces
IAlternativeName
IX509ExtensionAlternativeNames
 CERTENROLL_OBJECTID enumeration (certenroll.h)
7/2/2022 • 18 minutes to read • Edit Online

The CERTENROLL_OBJECTID enumeration type contains the predefined object identifiers (OIDs) supported by
Certificate Enrollment API.

Syntax
typedef enum CERTENROLL_OBJECTID {
XCN_OID_NONE = 0,
XCN_OID_RSA = 1,
XCN_OID_PKCS = 2,
XCN_OID_RSA_HASH = 3,
XCN_OID_RSA_ENCRYPT = 4,
XCN_OID_PKCS_1 = 5,
XCN_OID_PKCS_2 = 6,
XCN_OID_PKCS_3 = 7,
XCN_OID_PKCS_4 = 8,
XCN_OID_PKCS_5 = 9,
XCN_OID_PKCS_6 = 10,
XCN_OID_PKCS_7 = 11,
XCN_OID_PKCS_8 = 12,
XCN_OID_PKCS_9 = 13,
XCN_OID_PKCS_10 = 14,
XCN_OID_PKCS_12 = 15,
XCN_OID_RSA_RSA = 16,
XCN_OID_RSA_MD2RSA = 17,
XCN_OID_RSA_MD4RSA = 18,
XCN_OID_RSA_MD5RSA = 19,
XCN_OID_RSA_SHA1RSA = 20,
XCN_OID_RSA_SETOAEP_RSA = 21,
XCN_OID_RSA_DH = 22,
XCN_OID_RSA_data = 23,
XCN_OID_RSA_signedData = 24,
XCN_OID_RSA_envelopedData = 25,
XCN_OID_RSA_signEnvData = 26,
XCN_OID_RSA_digestedData = 27,
XCN_OID_RSA_hashedData = 28,
XCN_OID_RSA_encryptedData = 29,
XCN_OID_RSA_emailAddr = 30,
XCN_OID_RSA_unstructName = 31,
XCN_OID_RSA_contentType = 32,
XCN_OID_RSA_messageDigest = 33,
XCN_OID_RSA_signingTime = 34,
XCN_OID_RSA_counterSign = 35,
XCN_OID_RSA_challengePwd = 36,
XCN_OID_RSA_unstructAddr = 37,
XCN_OID_RSA_extCertAttrs = 38,
XCN_OID_RSA_certExtensions = 39,
XCN_OID_RSA_SMIMECapabilities = 40,
XCN_OID_RSA_preferSignedData = 41,
XCN_OID_RSA_SMIMEalg = 42,
XCN_OID_RSA_SMIMEalgESDH = 43,
XCN_OID_RSA_SMIMEalgCMS3DESwrap = 44,
XCN_OID_RSA_SMIMEalgCMSRC2wrap = 45,
XCN_OID_RSA_MD2 = 46,
XCN_OID_RSA_MD4 = 47,
XCN_OID_RSA_MD5 = 48,
XCN_OID_RSA_RC2CBC = 49,
XCN_OID_RSA_RC4 = 50,
XCN_OID_RSA_DES_EDE3_CBC = 51,
XCN_OID_RSA_RC5_CBCPad = 52,
XCN_OID_ANSI_X942 = 53,
XCN_OID_ANSI_X942_DH = 54,
XCN_OID_X957 = 55,
XCN_OID_X957_DSA = 56,
XCN_OID_X957_SHA1DSA = 57,
XCN_OID_DS = 58,
XCN_OID_DSALG = 59,
XCN_OID_DSALG_CRPT = 60,
XCN_OID_DSALG_HASH = 61,
XCN_OID_DSALG_SIGN = 62,
XCN_OID_DSALG_RSA = 63,
XCN_OID_OIW = 64,
XCN_OID_OIWSEC = 65,
XCN_OID_OIWSEC_md4RSA = 66,
XCN_OID_OIWSEC_md5RSA = 67,
XCN_OID_OIWSEC_md4RSA2 = 68,
XCN_OID_OIWSEC_desECB = 69,
XCN_OID_OIWSEC_desCBC = 70,
XCN_OID_OIWSEC_desOFB = 71,
XCN_OID_OIWSEC_desCFB = 72,
XCN_OID_OIWSEC_desMAC = 73,
XCN_OID_OIWSEC_rsaSign = 74,
XCN_OID_OIWSEC_dsa = 75,
XCN_OID_OIWSEC_shaDSA = 76,
XCN_OID_OIWSEC_mdc2RSA = 77,
XCN_OID_OIWSEC_shaRSA = 78,
XCN_OID_OIWSEC_dhCommMod = 79,
XCN_OID_OIWSEC_desEDE = 80,
XCN_OID_OIWSEC_sha = 81,
XCN_OID_OIWSEC_mdc2 = 82,
XCN_OID_OIWSEC_dsaComm = 83,
XCN_OID_OIWSEC_dsaCommSHA = 84,
XCN_OID_OIWSEC_rsaXchg = 85,
XCN_OID_OIWSEC_keyHashSeal = 86,
XCN_OID_OIWSEC_md2RSASign = 87,
XCN_OID_OIWSEC_md5RSASign = 88,
XCN_OID_OIWSEC_sha1 = 89,
XCN_OID_OIWSEC_dsaSHA1 = 90,
XCN_OID_OIWSEC_dsaCommSHA1 = 91,
XCN_OID_OIWSEC_sha1RSASign = 92,
XCN_OID_OIWDIR = 93,
XCN_OID_OIWDIR_CRPT = 94,
XCN_OID_OIWDIR_HASH = 95,
XCN_OID_OIWDIR_SIGN = 96,
XCN_OID_OIWDIR_md2 = 97,
XCN_OID_OIWDIR_md2RSA = 98,
XCN_OID_INFOSEC = 99,
XCN_OID_INFOSEC_sdnsSignature = 100,
XCN_OID_INFOSEC_mosaicSignature = 101,
XCN_OID_INFOSEC_sdnsConfidentiality = 102,
XCN_OID_INFOSEC_mosaicConfidentiality = 103,
XCN_OID_INFOSEC_sdnsIntegrity = 104,
XCN_OID_INFOSEC_mosaicIntegrity = 105,
XCN_OID_INFOSEC_sdnsTokenProtection = 106,
XCN_OID_INFOSEC_mosaicTokenProtection = 107,
XCN_OID_INFOSEC_sdnsKeyManagement = 108,
XCN_OID_INFOSEC_mosaicKeyManagement = 109,
XCN_OID_INFOSEC_sdnsKMandSig = 110,
XCN_OID_INFOSEC_mosaicKMandSig = 111,
XCN_OID_INFOSEC_SuiteASignature = 112,
XCN_OID_INFOSEC_SuiteAConfidentiality = 113,
XCN_OID_INFOSEC_SuiteAIntegrity = 114,
XCN_OID_INFOSEC_SuiteATokenProtection = 115,
XCN_OID_INFOSEC_SuiteAKeyManagement = 116,
XCN_OID_INFOSEC_SuiteAKMandSig = 117,
XCN_OID_INFOSEC_mosaicUpdatedSig = 118,
XCN_OID_INFOSEC_mosaicKMandUpdSig = 119,
XCN_OID_INFOSEC_mosaicUpdatedInteg = 120,
XCN_OID_INFOSEC_mosaicUpdatedInteg = 120,
XCN_OID_COMMON_NAME = 121,
XCN_OID_SUR_NAME = 122,
XCN_OID_DEVICE_SERIAL_NUMBER = 123,
XCN_OID_COUNTRY_NAME = 124,
XCN_OID_LOCALITY_NAME = 125,
XCN_OID_STATE_OR_PROVINCE_NAME = 126,
XCN_OID_STREET_ADDRESS = 127,
XCN_OID_ORGANIZATION_NAME = 128,
XCN_OID_ORGANIZATIONAL_UNIT_NAME = 129,
XCN_OID_TITLE = 130,
XCN_OID_DESCRIPTION = 131,
XCN_OID_SEARCH_GUIDE = 132,
XCN_OID_BUSINESS_CATEGORY = 133,
XCN_OID_POSTAL_ADDRESS = 134,
XCN_OID_POSTAL_CODE = 135,
XCN_OID_POST_OFFICE_BOX = 136,
XCN_OID_PHYSICAL_DELIVERY_OFFICE_NAME = 137,
XCN_OID_TELEPHONE_NUMBER = 138,
XCN_OID_TELEX_NUMBER = 139,
XCN_OID_TELETEXT_TERMINAL_IDENTIFIER = 140,
XCN_OID_FACSIMILE_TELEPHONE_NUMBER = 141,
XCN_OID_X21_ADDRESS = 142,
XCN_OID_INTERNATIONAL_ISDN_NUMBER = 143,
XCN_OID_REGISTERED_ADDRESS = 144,
XCN_OID_DESTINATION_INDICATOR = 145,
XCN_OID_PREFERRED_DELIVERY_METHOD = 146,
XCN_OID_PRESENTATION_ADDRESS = 147,
XCN_OID_SUPPORTED_APPLICATION_CONTEXT = 148,
XCN_OID_MEMBER = 149,
XCN_OID_OWNER = 150,
XCN_OID_ROLE_OCCUPANT = 151,
XCN_OID_SEE_ALSO = 152,
XCN_OID_USER_PASSWORD = 153,
XCN_OID_USER_CERTIFICATE = 154,
XCN_OID_CA_CERTIFICATE = 155,
XCN_OID_AUTHORITY_REVOCATION_LIST = 156,
XCN_OID_CERTIFICATE_REVOCATION_LIST = 157,
XCN_OID_CROSS_CERTIFICATE_PAIR = 158,
XCN_OID_GIVEN_NAME = 159,
XCN_OID_INITIALS = 160,
XCN_OID_DN_QUALIFIER = 161,
XCN_OID_DOMAIN_COMPONENT = 162,
XCN_OID_PKCS_12_FRIENDLY_NAME_ATTR = 163,
XCN_OID_PKCS_12_LOCAL_KEY_ID = 164,
XCN_OID_PKCS_12_KEY_PROVIDER_NAME_ATTR = 165,
XCN_OID_LOCAL_MACHINE_KEYSET = 166,
XCN_OID_PKCS_12_EXTENDED_ATTRIBUTES = 167,
XCN_OID_KEYID_RDN = 168,
XCN_OID_AUTHORITY_KEY_IDENTIFIER = 169,
XCN_OID_KEY_ATTRIBUTES = 170,
XCN_OID_CERT_POLICIES_95 = 171,
XCN_OID_KEY_USAGE_RESTRICTION = 172,
XCN_OID_SUBJECT_ALT_NAME = 173,
XCN_OID_ISSUER_ALT_NAME = 174,
XCN_OID_BASIC_CONSTRAINTS = 175,
XCN_OID_KEY_USAGE = 176,
XCN_OID_PRIVATEKEY_USAGE_PERIOD = 177,
XCN_OID_BASIC_CONSTRAINTS2 = 178,
XCN_OID_CERT_POLICIES = 179,
XCN_OID_ANY_CERT_POLICY = 180,
XCN_OID_AUTHORITY_KEY_IDENTIFIER2 = 181,
XCN_OID_SUBJECT_KEY_IDENTIFIER = 182,
XCN_OID_SUBJECT_ALT_NAME2 = 183,
XCN_OID_ISSUER_ALT_NAME2 = 184,
XCN_OID_CRL_REASON_CODE = 185,
XCN_OID_REASON_CODE_HOLD = 186,
XCN_OID_CRL_DIST_POINTS = 187,
XCN_OID_ENHANCED_KEY_USAGE = 188,
XCN_OID_CRL_NUMBER = 189,
XCN_OID_CRL_NUMBER = 189,
XCN_OID_DELTA_CRL_INDICATOR = 190,
XCN_OID_ISSUING_DIST_POINT = 191,
XCN_OID_FRESHEST_CRL = 192,
XCN_OID_NAME_CONSTRAINTS = 193,
XCN_OID_POLICY_MAPPINGS = 194,
XCN_OID_LEGACY_POLICY_MAPPINGS = 195,
XCN_OID_POLICY_CONSTRAINTS = 196,
XCN_OID_RENEWAL_CERTIFICATE = 197,
XCN_OID_ENROLLMENT_NAME_VALUE_PAIR = 198,
XCN_OID_ENROLLMENT_CSP_PROVIDER = 199,
XCN_OID_OS_VERSION = 200,
XCN_OID_ENROLLMENT_AGENT = 201,
XCN_OID_PKIX = 202,
XCN_OID_PKIX_PE = 203,
XCN_OID_AUTHORITY_INFO_ACCESS = 204,
XCN_OID_BIOMETRIC_EXT = 205,
XCN_OID_LOGOTYPE_EXT = 206,
XCN_OID_CERT_EXTENSIONS = 207,
XCN_OID_NEXT_UPDATE_LOCATION = 208,
XCN_OID_REMOVE_CERTIFICATE = 209,
XCN_OID_CROSS_CERT_DIST_POINTS = 210,
XCN_OID_CTL = 211,
XCN_OID_SORTED_CTL = 212,
XCN_OID_SERIALIZED = 213,
XCN_OID_NT_PRINCIPAL_NAME = 214,
XCN_OID_PRODUCT_UPDATE = 215,
XCN_OID_ANY_APPLICATION_POLICY = 216,
XCN_OID_AUTO_ENROLL_CTL_USAGE = 217,
XCN_OID_ENROLL_CERTTYPE_EXTENSION = 218,
XCN_OID_CERT_MANIFOLD = 219,
XCN_OID_CERTSRV_CA_VERSION = 220,
XCN_OID_CERTSRV_PREVIOUS_CERT_HASH = 221,
XCN_OID_CRL_VIRTUAL_BASE = 222,
XCN_OID_CRL_NEXT_PUBLISH = 223,
XCN_OID_KP_CA_EXCHANGE = 224,
XCN_OID_KP_KEY_RECOVERY_AGENT = 225,
XCN_OID_CERTIFICATE_TEMPLATE = 226,
XCN_OID_ENTERPRISE_OID_ROOT = 227,
XCN_OID_RDN_DUMMY_SIGNER = 228,
XCN_OID_APPLICATION_CERT_POLICIES = 229,
XCN_OID_APPLICATION_POLICY_MAPPINGS = 230,
XCN_OID_APPLICATION_POLICY_CONSTRAINTS = 231,
XCN_OID_ARCHIVED_KEY_ATTR = 232,
XCN_OID_CRL_SELF_CDP = 233,
XCN_OID_REQUIRE_CERT_CHAIN_POLICY = 234,
XCN_OID_ARCHIVED_KEY_CERT_HASH = 235,
XCN_OID_ISSUED_CERT_HASH = 236,
XCN_OID_DS_EMAIL_REPLICATION = 237,
XCN_OID_REQUEST_CLIENT_INFO = 238,
XCN_OID_ENCRYPTED_KEY_HASH = 239,
XCN_OID_CERTSRV_CROSSCA_VERSION = 240,
XCN_OID_NTDS_REPLICATION = 241,
XCN_OID_SUBJECT_DIR_ATTRS = 242,
XCN_OID_PKIX_KP = 243,
XCN_OID_PKIX_KP_SERVER_AUTH = 244,
XCN_OID_PKIX_KP_CLIENT_AUTH = 245,
XCN_OID_PKIX_KP_CODE_SIGNING = 246,
XCN_OID_PKIX_KP_EMAIL_PROTECTION = 247,
XCN_OID_PKIX_KP_IPSEC_END_SYSTEM = 248,
XCN_OID_PKIX_KP_IPSEC_TUNNEL = 249,
XCN_OID_PKIX_KP_IPSEC_USER = 250,
XCN_OID_PKIX_KP_TIMESTAMP_SIGNING = 251,
XCN_OID_PKIX_KP_OCSP_SIGNING = 252,
XCN_OID_PKIX_OCSP_NOCHECK = 253,
XCN_OID_IPSEC_KP_IKE_INTERMEDIATE = 254,
XCN_OID_KP_CTL_USAGE_SIGNING = 255,
XCN_OID_KP_TIME_STAMP_SIGNING = 256,
XCN_OID_SERVER_GATED_CRYPTO = 257,
XCN_OID_SGC_NETSCAPE = 258,
XCN_OID_SGC_NETSCAPE = 258,
XCN_OID_KP_EFS = 259,
XCN_OID_EFS_RECOVERY = 260,
XCN_OID_WHQL_CRYPTO = 261,
XCN_OID_NT5_CRYPTO = 262,
XCN_OID_OEM_WHQL_CRYPTO = 263,
XCN_OID_EMBEDDED_NT_CRYPTO = 264,
XCN_OID_ROOT_LIST_SIGNER = 265,
XCN_OID_KP_QUALIFIED_SUBORDINATION = 266,
XCN_OID_KP_KEY_RECOVERY = 267,
XCN_OID_KP_DOCUMENT_SIGNING = 268,
XCN_OID_KP_LIFETIME_SIGNING = 269,
XCN_OID_KP_MOBILE_DEVICE_SOFTWARE = 270,
XCN_OID_KP_SMART_DISPLAY = 271,
XCN_OID_KP_CSP_SIGNATURE = 272,
XCN_OID_DRM = 273,
XCN_OID_DRM_INDIVIDUALIZATION = 274,
XCN_OID_LICENSES = 275,
XCN_OID_LICENSE_SERVER = 276,
XCN_OID_KP_SMARTCARD_LOGON = 277,
XCN_OID_YESNO_TRUST_ATTR = 278,
XCN_OID_PKIX_POLICY_QUALIFIER_CPS = 279,
XCN_OID_PKIX_POLICY_QUALIFIER_USERNOTICE = 280,
XCN_OID_CERT_POLICIES_95_QUALIFIER1 = 281,
XCN_OID_PKIX_ACC_DESCR = 282,
XCN_OID_PKIX_OCSP = 283,
XCN_OID_PKIX_CA_ISSUERS = 284,
XCN_OID_VERISIGN_PRIVATE_6_9 = 285,
XCN_OID_VERISIGN_ONSITE_JURISDICTION_HASH = 286,
XCN_OID_VERISIGN_BITSTRING_6_13 = 287,
XCN_OID_VERISIGN_ISS_STRONG_CRYPTO = 288,
XCN_OID_NETSCAPE = 289,
XCN_OID_NETSCAPE_CERT_EXTENSION = 290,
XCN_OID_NETSCAPE_CERT_TYPE = 291,
XCN_OID_NETSCAPE_BASE_URL = 292,
XCN_OID_NETSCAPE_REVOCATION_URL = 293,
XCN_OID_NETSCAPE_CA_REVOCATION_URL = 294,
XCN_OID_NETSCAPE_CERT_RENEWAL_URL = 295,
XCN_OID_NETSCAPE_CA_POLICY_URL = 296,
XCN_OID_NETSCAPE_SSL_SERVER_NAME = 297,
XCN_OID_NETSCAPE_COMMENT = 298,
XCN_OID_NETSCAPE_DATA_TYPE = 299,
XCN_OID_NETSCAPE_CERT_SEQUENCE = 300,
XCN_OID_CT_PKI_DATA = 301,
XCN_OID_CT_PKI_RESPONSE = 302,
XCN_OID_PKIX_NO_SIGNATURE = 303,
XCN_OID_CMC = 304,
XCN_OID_CMC_STATUS_INFO = 305,
XCN_OID_CMC_IDENTIFICATION = 306,
XCN_OID_CMC_IDENTITY_PROOF = 307,
XCN_OID_CMC_DATA_RETURN = 308,
XCN_OID_CMC_TRANSACTION_ID = 309,
XCN_OID_CMC_SENDER_NONCE = 310,
XCN_OID_CMC_RECIPIENT_NONCE = 311,
XCN_OID_CMC_ADD_EXTENSIONS = 312,
XCN_OID_CMC_ENCRYPTED_POP = 313,
XCN_OID_CMC_DECRYPTED_POP = 314,
XCN_OID_CMC_LRA_POP_WITNESS = 315,
XCN_OID_CMC_GET_CERT = 316,
XCN_OID_CMC_GET_CRL = 317,
XCN_OID_CMC_REVOKE_REQUEST = 318,
XCN_OID_CMC_REG_INFO = 319,
XCN_OID_CMC_RESPONSE_INFO = 320,
XCN_OID_CMC_QUERY_PENDING = 321,
XCN_OID_CMC_ID_POP_LINK_RANDOM = 322,
XCN_OID_CMC_ID_POP_LINK_WITNESS = 323,
XCN_OID_CMC_ID_CONFIRM_CERT_ACCEPTANCE = 324,
XCN_OID_CMC_ADD_ATTRIBUTES = 325,
XCN_OID_LOYALTY_OTHER_LOGOTYPE = 326,
XCN_OID_BACKGROUND_OTHER_LOGOTYPE = 327,
XCN_OID_BACKGROUND_OTHER_LOGOTYPE = 327,
XCN_OID_PKIX_OCSP_BASIC_SIGNED_RESPONSE = 328,
XCN_OID_PKCS_7_DATA = 329,
XCN_OID_PKCS_7_SIGNED = 330,
XCN_OID_PKCS_7_ENVELOPED = 331,
XCN_OID_PKCS_7_SIGNEDANDENVELOPED = 332,
XCN_OID_PKCS_7_DIGESTED = 333,
XCN_OID_PKCS_7_ENCRYPTED = 334,
XCN_OID_PKCS_9_CONTENT_TYPE = 335,
XCN_OID_PKCS_9_MESSAGE_DIGEST = 336,
XCN_OID_CERT_PROP_ID_PREFIX = 337,
XCN_OID_CERT_KEY_IDENTIFIER_PROP_ID = 338,
XCN_OID_CERT_ISSUER_SERIAL_NUMBER_MD5_HASH_PROP_ID = 339,
XCN_OID_CERT_SUBJECT_NAME_MD5_HASH_PROP_ID = 340,
XCN_OID_CERT_MD5_HASH_PROP_ID = 341,
XCN_OID_RSA_SHA256RSA = 342,
XCN_OID_RSA_SHA384RSA = 343,
XCN_OID_RSA_SHA512RSA = 344,
XCN_OID_NIST_sha256 = 345,
XCN_OID_NIST_sha384 = 346,
XCN_OID_NIST_sha512 = 347,
XCN_OID_RSA_MGF1 = 348,
XCN_OID_ECC_PUBLIC_KEY = 349,
XCN_OID_ECDSA_SHA1 = 350,
XCN_OID_ECDSA_SPECIFIED = 351,
XCN_OID_ANY_ENHANCED_KEY_USAGE = 352,
XCN_OID_RSA_SSA_PSS = 353,
XCN_OID_ATTR_SUPPORTED_ALGORITHMS = 355,
XCN_OID_ATTR_TPM_SECURITY_ASSERTIONS = 356,
XCN_OID_ATTR_TPM_SPECIFICATION = 357,
XCN_OID_CERT_DISALLOWED_FILETIME_PROP_ID = 358,
XCN_OID_CERT_SIGNATURE_HASH_PROP_ID = 359,
XCN_OID_CERT_STRONG_KEY_OS_1 = 360,
XCN_OID_CERT_STRONG_KEY_OS_CURRENT = 361,
XCN_OID_CERT_STRONG_KEY_OS_PREFIX = 362,
XCN_OID_CERT_STRONG_SIGN_OS_1 = 363,
XCN_OID_CERT_STRONG_SIGN_OS_CURRENT = 364,
XCN_OID_CERT_STRONG_SIGN_OS_PREFIX = 365,
XCN_OID_DH_SINGLE_PASS_STDDH_SHA1_KDF = 366,
XCN_OID_DH_SINGLE_PASS_STDDH_SHA256_KDF = 367,
XCN_OID_DH_SINGLE_PASS_STDDH_SHA384_KDF = 368,
XCN_OID_DISALLOWED_HASH = 369,
XCN_OID_DISALLOWED_LIST = 370,
XCN_OID_ECC_CURVE_P256 = 371,
XCN_OID_ECC_CURVE_P384 = 372,
XCN_OID_ECC_CURVE_P521 = 373,
XCN_OID_ECDSA_SHA256 = 374,
XCN_OID_ECDSA_SHA384 = 375,
XCN_OID_ECDSA_SHA512 = 376,
XCN_OID_ENROLL_CAXCHGCERT_HASH = 377,
XCN_OID_ENROLL_EK_INFO = 378,
XCN_OID_ENROLL_EKPUB_CHALLENGE = 379,
XCN_OID_ENROLL_EKVERIFYCERT = 380,
XCN_OID_ENROLL_EKVERIFYCREDS = 381,
XCN_OID_ENROLL_EKVERIFYKEY = 382,
XCN_OID_EV_RDN_COUNTRY = 383,
XCN_OID_EV_RDN_LOCALE = 384,
XCN_OID_EV_RDN_STATE_OR_PROVINCE = 385,
XCN_OID_INHIBIT_ANY_POLICY = 386,
XCN_OID_INTERNATIONALIZED_EMAIL_ADDRESS = 387,
XCN_OID_KP_KERNEL_MODE_CODE_SIGNING = 388,
XCN_OID_KP_KERNEL_MODE_HAL_EXTENSION_SIGNING = 389,
XCN_OID_KP_KERNEL_MODE_TRUSTED_BOOT_SIGNING = 390,
XCN_OID_KP_TPM_AIK_CERTIFICATE = 391,
XCN_OID_KP_TPM_EK_CERTIFICATE = 392,
XCN_OID_KP_TPM_PLATFORM_CERTIFICATE = 393,
XCN_OID_NIST_AES128_CBC = 394,
XCN_OID_NIST_AES128_WRAP = 395,
XCN_OID_NIST_AES192_CBC = 396,
 XCN_OID_NIST_AES192_WRAP = 397,
XCN_OID_NIST_AES256_CBC = 398,
XCN_OID_NIST_AES256_WRAP = 399,
XCN_OID_PKCS_12_PbeIds = 400,
XCN_OID_PKCS_12_pbeWithSHA1And128BitRC2 = 401,
XCN_OID_PKCS_12_pbeWithSHA1And128BitRC4 = 402,
XCN_OID_PKCS_12_pbeWithSHA1And2KeyTripleDES = 403,
XCN_OID_PKCS_12_pbeWithSHA1And3KeyTripleDES = 404,
XCN_OID_PKCS_12_pbeWithSHA1And40BitRC2 = 405,
XCN_OID_PKCS_12_pbeWithSHA1And40BitRC4 = 406,
XCN_OID_PKCS_12_PROTECTED_PASSWORD_SECRET_BAG_TYPE_ID = 407,
XCN_OID_PKINIT_KP_KDC = 408,
XCN_OID_PKIX_CA_REPOSITORY = 409,
XCN_OID_PKIX_OCSP_NONCE = 410,
XCN_OID_PKIX_TIME_STAMPING = 411,
XCN_OID_QC_EU_COMPLIANCE = 412,
XCN_OID_QC_SSCD = 413,
XCN_OID_QC_STATEMENTS_EXT = 414,
XCN_OID_RDN_TPM_MANUFACTURER = 415,
XCN_OID_RDN_TPM_MODEL = 416,
XCN_OID_RDN_TPM_VERSION = 417,
XCN_OID_REVOKED_LIST_SIGNER = 418,
XCN_OID_RFC3161_counterSign = 419,
XCN_OID_ROOT_PROGRAM_AUTO_UPDATE_CA_REVOCATION = 420,
XCN_OID_ROOT_PROGRAM_AUTO_UPDATE_END_REVOCATION = 421,
XCN_OID_ROOT_PROGRAM_FLAGS = 422,
XCN_OID_ROOT_PROGRAM_NO_OCSP_FAILOVER_TO_CRL = 423,
XCN_OID_RSA_PSPECIFIED = 424,
XCN_OID_RSAES_OAEP = 425,
XCN_OID_SUBJECT_INFO_ACCESS = 426,
XCN_OID_TIMESTAMP_TOKEN = 427,
XCN_OID_ENROLL_SCEP_ERROR = 428,
XCN_OIDVerisign_MessageType = 429,
XCN_OIDVerisign_PkiStatus = 430,
XCN_OIDVerisign_FailInfo = 431,
XCN_OIDVerisign_SenderNonce = 432,
XCN_OIDVerisign_RecipientNonce = 433,
XCN_OIDVerisign_TransactionID = 434,
XCN_OID_ENROLL_ATTESTATION_CHALLENGE = 435,
XCN_OID_ENROLL_ATTESTATION_STATEMENT = 436,
XCN_OID_ENROLL_ENCRYPTION_ALGORITHM = 437,
XCN_OID_ENROLL_KSP_NAME = 438
} ;

Constants

XCN_OID_NONE
Value: 0
No OID is defined.

XCN_OID_RSA
Value: 1
(1.2.840.113549)

Identifies the top level OID for RSA laboratories.

XCN_OID_PKCS
Value: 2
(1.2.840.113549.1)

Identifies the top level public key cryptography standard (PKCS) OID.
XCN_OID_RSA_HASH
Value: 3
(1.2.840.113549.2)

Identifies an RSA hashing algorithm.

XCN_OID_RSA_ENCRYPT
Value: 4
(1.2.840.113549.3)

Identifies an RSA encryption algorithm.

XCN_OID_PKCS_1
Value: 5
(1.2.840.113549.1.1)

Identifies the PKCS #1 standard.

XCN_OID_PKCS_2
Value: 6
(1.2.840.113549.1.2)

Identifies the PKCS #2 standard.

XCN_OID_PKCS_3
Value: 7
(1.2.840.113549.1.3)

Identifies the PKCS #3 standard.

XCN_OID_PKCS_4
Value: 8
(1.2.840.113549.1.4)

Identifies the PKCS #4 standard.

XCN_OID_PKCS_5
Value: 9
(1.2.840.113549.1.5)

Identifies the PKCS #5 standard.

XCN_OID_PKCS_6
Value: 10
(1.2.840.113549.1.6)

Identifies the PKCS #6 standard.

XCN_OID_PKCS_7
Value: 11
(1.2.840.113549.1.7)

Identifies the PKCS #7 standard.

XCN_OID_PKCS_8
Value: 12
(1.2.840.113549.1.8)

Identifies the PKCS #8 standard.

XCN_OID_PKCS_9
Value: 13
(1.2.840.113549.1.9)

Identifies the PKCS #9 standard.

XCN_OID_PKCS_10
Value: 14
(1.2.840.113549.1.10)

Identifies the PKCS #10 standard.

XCN_OID_PKCS_12
Value: 15
(1.2.840.113549.1.12)

Identifies the PKCS #12 standard.

XCN_OID_RSA_RSA
Value: 16
(1.2.840.113549.1.1.1)

Identifies an RSA encryption or signing algorithm.

XCN_OID_RSA_MD2RSA
Value: 17
(1.2.840.113549.1.1.2)

Identifies an RSA asymmetric algorithm combined with an MD2 hashing algorithm.

XCN_OID_RSA_MD4RSA
Value: 18
(1.2.840.113549.1.1.3)

Identifies an RSA asymmetric algorithm combined with an MD4 hashing algorithm.

XCN_OID_RSA_MD5RSA
Value: 19
(1.2.840.113549.1.1.4)

Identifies an RSA asymmetric algorithm combined with an MD5 hashing algorithm.

XCN_OID_RSA_SHA1RSA
Value: 20
(1.2.840.113549.1.1.5)

Identifies an RSA asymmetric algorithm combined with an MD5 hashing algorithm.

XCN_OID_RSA_SETOAEP_RSA
Value: 21
(1.2.840.113549.1.1.6)

XCN_OID_RSA_DH
Value: 22
(1.2.840.113549.1.3.1)

Identifies a Diffie-Hellman key exchange algorithm.

XCN_OID_RSA_data
Value: 23

XCN_OID_RSA_signedData
Value: 24

XCN_OID_RSA_envelopedData
Value: 25

XCN_OID_RSA_signEnvData
Value: 26

XCN_OID_RSA_digestedData
Value: 27

XCN_OID_RSA_hashedData
Value: 28

XCN_OID_RSA_encryptedData
Value: 29

XCN_OID_RSA_emailAddr
Value: 30
Contains the subject email address or addresses as an unstructured ASCII string. The interpretation of the string is determined
by the certificate issuer.

XCN_OID_RSA_unstructName
Value: 31
Contains the subject name or names in an unstructured ASCII string. The interpretation of the string is determined by the
certificate issuer.

XCN_OID_RSA_contentType
Value: 32
Contains an OID that specifies the type of the data being signed in a PKCS #7 message. Possible examples include
XCN_OID_RSA_signedData or XCN_OID_RSA_envelopedData .

XCN_OID_RSA_messageDigest
Value: 33
Contains the message digest of the content being signed in a PKCS #7 message.

XCN_OID_RSA_signingTime
Value: 34
Contains the date and time at which the PKCS #7 data was signed.
 XCN_OID_RSA_counterSign
Value: 35
Contains one or more signatures on the encryptedDigest field of the SignerInfo structure in a PKCS #7 message.

XCN_OID_RSA_challengePwd
Value: 36
Contains a password that can be used to request that a certificate be revoked. The interpretation of the password string is
determined by the certificate issuer.

XCN_OID_RSA_unstructAddr
Value: 37
Contains the subject address or addresses in an unstructured ASCII string. The interpretation of the string is determined by
the certificate issuer.

XCN_OID_RSA_extCertAttrs
Value: 38
Contains a set of attributes for a PKCS #6 extended certificate in a PKCS #10 certification request. This attribute became
deprecated with the introduction of X.509 version 3 certificates that include extensions.

XCN_OID_RSA_certExtensions
Value: 39

XCN_OID_RSA_SMIMECapabilities
Value: 40

XCN_OID_RSA_preferSignedData
Value: 41

XCN_OID_RSA_SMIMEalg
Value: 42

XCN_OID_RSA_SMIMEalgESDH
Value: 43

XCN_OID_RSA_SMIMEalgCMS3DESwrap
Value: 44

XCN_OID_RSA_SMIMEalgCMSRC2wrap
Value: 45

XCN_OID_RSA_MD2
Value: 46

XCN_OID_RSA_MD4
Value: 47

XCN_OID_RSA_MD5
Value: 48

XCN_OID_RSA_RC2CBC
Value: 49
XCN_OID_RSA_RC4
Value: 50

XCN_OID_RSA_DES_EDE3_CBC
Value: 51

XCN_OID_RSA_RC5_CBCPad
Value: 52

XCN_OID_ANSI_X942
Value: 53

XCN_OID_ANSI_X942_DH
Value: 54

XCN_OID_X957
Value: 55

XCN_OID_X957_DSA
Value: 56

XCN_OID_X957_SHA1DSA
Value: 57

XCN_OID_DS
Value: 58

XCN_OID_DSALG
Value: 59

XCN_OID_DSALG_CRPT
Value: 60

XCN_OID_DSALG_HASH
Value: 61

XCN_OID_DSALG_SIGN
Value: 62

XCN_OID_DSALG_RSA
Value: 63

XCN_OID_OIW
Value: 64

XCN_OID_OIWSEC
Value: 65

XCN_OID_OIWSEC_md4RSA
Value: 66
XCN_OID_OIWSEC_md5RSA
Value: 67

XCN_OID_OIWSEC_md4RSA2
Value: 68

XCN_OID_OIWSEC_desECB
Value: 69

XCN_OID_OIWSEC_desCBC
Value: 70

XCN_OID_OIWSEC_desOFB
Value: 71

XCN_OID_OIWSEC_desCFB
Value: 72

XCN_OID_OIWSEC_desMAC
Value: 73

XCN_OID_OIWSEC_rsaSign
Value: 74

XCN_OID_OIWSEC_dsa
Value: 75

XCN_OID_OIWSEC_shaDSA
Value: 76

XCN_OID_OIWSEC_mdc2RSA
Value: 77

XCN_OID_OIWSEC_shaRSA
Value: 78

XCN_OID_OIWSEC_dhCommMod
Value: 79

XCN_OID_OIWSEC_desEDE
Value: 80

XCN_OID_OIWSEC_sha
Value: 81

XCN_OID_OIWSEC_mdc2
Value: 82

XCN_OID_OIWSEC_dsaComm
Value: 83
XCN_OID_OIWSEC_dsaCommSHA
Value: 84

XCN_OID_OIWSEC_rsaXchg
Value: 85

XCN_OID_OIWSEC_keyHashSeal
Value: 86

XCN_OID_OIWSEC_md2RSASign
Value: 87

XCN_OID_OIWSEC_md5RSASign
Value: 88

XCN_OID_OIWSEC_sha1
Value: 89

XCN_OID_OIWSEC_dsaSHA1
Value: 90

XCN_OID_OIWSEC_dsaCommSHA1
Value: 91

XCN_OID_OIWSEC_sha1RSASign
Value: 92

XCN_OID_OIWDIR
Value: 93

XCN_OID_OIWDIR_CRPT
Value: 94

XCN_OID_OIWDIR_HASH
Value: 95

XCN_OID_OIWDIR_SIGN
Value: 96

XCN_OID_OIWDIR_md2
Value: 97

XCN_OID_OIWDIR_md2RSA
Value: 98

XCN_OID_INFOSEC
Value: 99

XCN_OID_INFOSEC_sdnsSignature
Value: 100
XCN_OID_INFOSEC_mosaicSignature
Value: 101

XCN_OID_INFOSEC_sdnsConfidentiality
Value: 102

XCN_OID_INFOSEC_mosaicConfidentiality
Value: 103

XCN_OID_INFOSEC_sdnsIntegrity
Value: 104

XCN_OID_INFOSEC_mosaicIntegrity
Value: 105

XCN_OID_INFOSEC_sdnsTokenProtection
Value: 106

XCN_OID_INFOSEC_mosaicTokenProtection
Value: 107

XCN_OID_INFOSEC_sdnsKeyManagement
Value: 108

XCN_OID_INFOSEC_mosaicKeyManagement
Value: 109

XCN_OID_INFOSEC_sdnsKMandSig
Value: 110

XCN_OID_INFOSEC_mosaicKMandSig
Value: 111

XCN_OID_INFOSEC_SuiteASignature
Value: 112

XCN_OID_INFOSEC_SuiteAConfidentiality
Value: 113

XCN_OID_INFOSEC_SuiteAIntegrity
Value: 114

XCN_OID_INFOSEC_SuiteATokenProtection
Value: 115

XCN_OID_INFOSEC_SuiteAKeyManagement
Value: 116

XCN_OID_INFOSEC_SuiteAKMandSig
Value: 117
 XCN_OID_INFOSEC_mosaicUpdatedSig
Value: 118

XCN_OID_INFOSEC_mosaicKMandUpdSig
Value: 119

XCN_OID_INFOSEC_mosaicUpdatedInteg
Value: 120

XCN_OID_COMMON_NAME
Value: 121
Contains one or more common names for the entity requesting the certificate.

XCN_OID_SUR_NAME
Value: 122
Contains one or more strings for the family name of a person.

XCN_OID_DEVICE_SERIAL_NUMBER
Value: 123
Contains one or more device serial numbers.

XCN_OID_COUNTRY_NAME
Value: 124
Contains a two-letter ISO 3166 country or region code for the entity requesting the certificate.

XCN_OID_LOCALITY_NAME
Value: 125
Contains place names that identify a city, country, or other geographic region. The attribute can contain multiple values.

XCN_OID_STATE_OR_PROVINCE_NAME
Value: 126
Contains one or more names of states or provinces associated with the entity requesting the certificate.

XCN_OID_STREET_ADDRESS
Value: 127
Contains one or more street addresses for the entity requesting the certificate.

XCN_OID_ORGANIZATION_NAME
Value: 128
Contains one or more names that identify the organization with which the entity requesting the certificate is associated.

XCN_OID_ORGANIZATIONAL_UNIT_NAME
Value: 129
Contains one or more names for the organizational unit with which the entity requesting the certificate is associated.

XCN_OID_TITLE
Value: 130
Contains the title, if any, of the entity requesting the certificate.

XCN_OID_DESCRIPTION
Value: 131
Contains one or more strings that describe the entity requesting the certificate.
 XCN_OID_SEARCH_GUIDE
Value: 132
Contains information used by directory clients to construct search filters. The attribute can contain multiple values.

XCN_OID_BUSINESS_CATEGORY
Value: 133
Contains one or more strings that describe the type of business performed by the entity requesting the certificate.

XCN_OID_POSTAL_ADDRESS
Value: 134
Contains one or more addresses that a postal service uses for the object to which this attribute applies.

XCN_OID_POSTAL_CODE
Value: 135
Contains one or more codes that a postal service uses to identify postal zones.

XCN_OID_POST_OFFICE_BOX
Value: 136
Contains one or more numbers that a postal services uses to identify a delivery location that is not a street address.

XCN_OID_PHYSICAL_DELIVERY_OFFICE_NAME
Value: 137
Contains the name that a postal service uses to identify a post office.

XCN_OID_TELEPHONE_NUMBER
Value: 138
Contains one or more telephone numbers for the entity requesting the certificate.

XCN_OID_TELEX_NUMBER
Value: 139
Contains one or more strings that identify the number, country or region code, and return answer code of a telex terminal.

XCN_OID_TELETEXT_TERMINAL_IDENTIFIER
Value: 140
Contains one or more numbers that identify a teletext terminal.

XCN_OID_FACSIMILE_TELEPHONE_NUMBER
Value: 141
Contains facsimile machine telephone numbers and optional parameters for the entity requesting the certificate.

XCN_OID_X21_ADDRESS
Value: 142
Contains one or more data network addresses, as defined by ITU recommendation X.121, of the entity requesting the
certificate.

XCN_OID_INTERNATIONAL_ISDN_NUMBER
Value: 143
Contains one or more ISDN addresses,
as defined in ITU Recommendation E.164, for the entity requesting the certificate.

XCN_OID_REGISTERED_ADDRESS
Value: 144
Contains one or more addresses that can be used for delivering telegrams or expedited documents.
 XCN_OID_DESTINATION_INDICATOR
Value: 145
Contains one or more strings that identify the city and country or region of the entity requesting the certificate.

XCN_OID_PREFERRED_DELIVERY_METHOD
Value: 146
Contains a string that indicates the preferred method of receiving a message for the object to which this attribute applies.

XCN_OID_PRESENTATION_ADDRESS
Value: 147
Contains an OSI presentation address.

XCN_OID_SUPPORTED_APPLICATION_CONTEXT
Value: 148

XCN_OID_MEMBER
Value: 149
Contains the distinguished names of objects that are included in a list or group. The attribute can contain multiple values.

XCN_OID_OWNER
Value: 150
Contains one or more distinguished names for the owner of the certificate request.

XCN_OID_ROLE_OCCUPANT
Value: 151
Contains the distinguished names of people that fulfill the responsibilities defined by a role object.

XCN_OID_SEE_ALSO
Value: 152
Contains one or more distinguished names of objects that are related to the subject of the certificate request.

XCN_OID_USER_PASSWORD
Value: 153
Contains one or more passwords for the entity requesting the certificate.

XCN_OID_USER_CERTIFICATE
Value: 154

XCN_OID_CA_CERTIFICATE
Value: 155

XCN_OID_AUTHORITY_REVOCATION_LIST
Value: 156

XCN_OID_CERTIFICATE_REVOCATION_LIST
Value: 157

XCN_OID_CROSS_CERTIFICATE_PAIR
Value: 158

XCN_OID_GIVEN_NAME
Value: 159
Contains strings that identify the parts of a person's name other than the surname. The attribute can contain multiple values.
 XCN_OID_INITIALS
Value: 160
Contains the initials of all or part of a person's name other than the surname. The attribute can contain multiple values.

XCN_OID_DN_QUALIFIER
Value: 161
Contains disambiguating information for a relative distinguished name. The attribute prevents conflicts between objects that
would otherwise have the same name. The attribute can contain multiple values.

XCN_OID_DOMAIN_COMPONENT
Value: 162
Contains a component of a DNS domain name. For example, if the DNS name is contoso.com, contoso and com represent
separate domain components.

XCN_OID_PKCS_12_FRIENDLY_NAME_ATTR
Value: 163
Contains the PKCS #12 display name attribute transmitted in the SafeBag data of a PKCS #12 PFX message. The attribute
specifies the display name of the object with which it is associated.

XCN_OID_PKCS_12_LOCAL_KEY_ID
Value: 164
Contains a PKCS #12 key identifier attribute transmitted in the SafeBag data of a PKCS #12 PFX message. The identifier is
only used in local applications.

XCN_OID_PKCS_12_KEY_PROVIDER_NAME_ATTR
Value: 165

XCN_OID_LOCAL_MACHINE_KEYSET
Value: 166

XCN_OID_PKCS_12_EXTENDED_ATTRIBUTES
Value: 167

XCN_OID_KEYID_RDN
Value: 168

XCN_OID_AUTHORITY_KEY_IDENTIFIER
Value: 169

XCN_OID_KEY_ATTRIBUTES
Value: 170

XCN_OID_CERT_POLICIES_95
Value: 171

XCN_OID_KEY_USAGE_RESTRICTION
Value: 172

XCN_OID_SUBJECT_ALT_NAME
Value: 173

XCN_OID_ISSUER_ALT_NAME
Value: 174
XCN_OID_BASIC_CONSTRAINTS
Value: 175

XCN_OID_KEY_USAGE
Value: 176

XCN_OID_PRIVATEKEY_USAGE_PERIOD
Value: 177

XCN_OID_BASIC_CONSTRAINTS2
Value: 178

XCN_OID_CERT_POLICIES
Value: 179

XCN_OID_ANY_CERT_POLICY
Value: 180

XCN_OID_AUTHORITY_KEY_IDENTIFIER2
Value: 181

XCN_OID_SUBJECT_KEY_IDENTIFIER
Value: 182

XCN_OID_SUBJECT_ALT_NAME2
Value: 183

XCN_OID_ISSUER_ALT_NAME2
Value: 184

XCN_OID_CRL_REASON_CODE
Value: 185

XCN_OID_REASON_CODE_HOLD
Value: 186

XCN_OID_CRL_DIST_POINTS
Value: 187

XCN_OID_ENHANCED_KEY_USAGE
Value: 188

XCN_OID_CRL_NUMBER
Value: 189

XCN_OID_DELTA_CRL_INDICATOR
Value: 190

XCN_OID_ISSUING_DIST_POINT
Value: 191
XCN_OID_FRESHEST_CRL
Value: 192

XCN_OID_NAME_CONSTRAINTS
Value: 193

XCN_OID_POLICY_MAPPINGS
Value: 194

XCN_OID_LEGACY_POLICY_MAPPINGS
Value: 195

XCN_OID_POLICY_CONSTRAINTS
Value: 196

XCN_OID_RENEWAL_CERTIFICATE
Value: 197

XCN_OID_ENROLLMENT_NAME_VALUE_PAIR
Value: 198

XCN_OID_ENROLLMENT_CSP_PROVIDER
Value: 199

XCN_OID_OS_VERSION
Value: 200

XCN_OID_ENROLLMENT_AGENT
Value: 201

XCN_OID_PKIX
Value: 202

XCN_OID_PKIX_PE
Value: 203

XCN_OID_AUTHORITY_INFO_ACCESS
Value: 204

XCN_OID_BIOMETRIC_EXT
Value: 205

XCN_OID_LOGOTYPE_EXT
Value: 206

XCN_OID_CERT_EXTENSIONS
Value: 207

XCN_OID_NEXT_UPDATE_LOCATION
Value: 208
 XCN_OID_REMOVE_CERTIFICATE
Value: 209

XCN_OID_CROSS_CERT_DIST_POINTS
Value: 210

XCN_OID_CTL
Value: 211

XCN_OID_SORTED_CTL
Value: 212

XCN_OID_SERIALIZED
Value: 213

XCN_OID_NT_PRINCIPAL_NAME
Value: 214

XCN_OID_PRODUCT_UPDATE
Value: 215

XCN_OID_ANY_APPLICATION_POLICY
Value: 216
(1.3.6.1.4.1.311.10.12.1)

Identifies an EKU OID which indicates that there are no restrictions on the applications that can use the certificate.

XCN_OID_AUTO_ENROLL_CTL_USAGE
Value: 217

XCN_OID_ENROLL_CERTTYPE_EXTENSION
Value: 218

XCN_OID_CERT_MANIFOLD
Value: 219

XCN_OID_CERTSRV_CA_VERSION
Value: 220

XCN_OID_CERTSRV_PREVIOUS_CERT_HASH
Value: 221

XCN_OID_CRL_VIRTUAL_BASE
Value: 222

XCN_OID_CRL_NEXT_PUBLISH
Value: 223

XCN_OID_KP_CA_EXCHANGE
Value: 224
XCN_OID_KP_KEY_RECOVERY_AGENT
Value: 225

XCN_OID_CERTIFICATE_TEMPLATE
Value: 226

XCN_OID_ENTERPRISE_OID_ROOT
Value: 227

XCN_OID_RDN_DUMMY_SIGNER
Value: 228

XCN_OID_APPLICATION_CERT_POLICIES
Value: 229

XCN_OID_APPLICATION_POLICY_MAPPINGS
Value: 230

XCN_OID_APPLICATION_POLICY_CONSTRAINTS
Value: 231

XCN_OID_ARCHIVED_KEY_ATTR
Value: 232

XCN_OID_CRL_SELF_CDP
Value: 233

XCN_OID_REQUIRE_CERT_CHAIN_POLICY
Value: 234

XCN_OID_ARCHIVED_KEY_CERT_HASH
Value: 235

XCN_OID_ISSUED_CERT_HASH
Value: 236

XCN_OID_DS_EMAIL_REPLICATION
Value: 237

XCN_OID_REQUEST_CLIENT_INFO
Value: 238

XCN_OID_ENCRYPTED_KEY_HASH
Value: 239

XCN_OID_CERTSRV_CROSSCA_VERSION
Value: 240

XCN_OID_NTDS_REPLICATION
Value: 241
XCN_OID_SUBJECT_DIR_ATTRS
Value: 242

XCN_OID_PKIX_KP
Value: 243

XCN_OID_PKIX_KP_SERVER_AUTH
Value: 244

XCN_OID_PKIX_KP_CLIENT_AUTH
Value: 245

XCN_OID_PKIX_KP_CODE_SIGNING
Value: 246

XCN_OID_PKIX_KP_EMAIL_PROTECTION
Value: 247

XCN_OID_PKIX_KP_IPSEC_END_SYSTEM
Value: 248

XCN_OID_PKIX_KP_IPSEC_TUNNEL
Value: 249

XCN_OID_PKIX_KP_IPSEC_USER
Value: 250

XCN_OID_PKIX_KP_TIMESTAMP_SIGNING
Value: 251

XCN_OID_PKIX_KP_OCSP_SIGNING
Value: 252

XCN_OID_PKIX_OCSP_NOCHECK
Value: 253

XCN_OID_IPSEC_KP_IKE_INTERMEDIATE
Value: 254

XCN_OID_KP_CTL_USAGE_SIGNING
Value: 255

XCN_OID_KP_TIME_STAMP_SIGNING
Value: 256

XCN_OID_SERVER_GATED_CRYPTO
Value: 257

XCN_OID_SGC_NETSCAPE
Value: 258
XCN_OID_KP_EFS
Value: 259

XCN_OID_EFS_RECOVERY
Value: 260

XCN_OID_WHQL_CRYPTO
Value: 261

XCN_OID_NT5_CRYPTO
Value: 262

XCN_OID_OEM_WHQL_CRYPTO
Value: 263

XCN_OID_EMBEDDED_NT_CRYPTO
Value: 264

XCN_OID_ROOT_LIST_SIGNER
Value: 265

XCN_OID_KP_QUALIFIED_SUBORDINATION
Value: 266

XCN_OID_KP_KEY_RECOVERY
Value: 267

XCN_OID_KP_DOCUMENT_SIGNING
Value: 268

XCN_OID_KP_LIFETIME_SIGNING
Value: 269

XCN_OID_KP_MOBILE_DEVICE_SOFTWARE
Value: 270

XCN_OID_KP_SMART_DISPLAY
Value: 271

XCN_OID_KP_CSP_SIGNATURE
Value: 272

XCN_OID_DRM
Value: 273

XCN_OID_DRM_INDIVIDUALIZATION
Value: 274

XCN_OID_LICENSES
Value: 275
XCN_OID_LICENSE_SERVER
Value: 276

XCN_OID_KP_SMARTCARD_LOGON
Value: 277

XCN_OID_YESNO_TRUST_ATTR
Value: 278

XCN_OID_PKIX_POLICY_QUALIFIER_CPS
Value: 279

XCN_OID_PKIX_POLICY_QUALIFIER_USERNOTICE
Value: 280

XCN_OID_CERT_POLICIES_95_QUALIFIER1
Value: 281

XCN_OID_PKIX_ACC_DESCR
Value: 282

XCN_OID_PKIX_OCSP
Value: 283

XCN_OID_PKIX_CA_ISSUERS
Value: 284

XCN_OID_VERISIGN_PRIVATE_6_9
Value: 285

XCN_OID_VERISIGN_ONSITE_JURISDICTION_HASH
Value: 286

XCN_OID_VERISIGN_BITSTRING_6_13
Value: 287

XCN_OID_VERISIGN_ISS_STRONG_CRYPTO
Value: 288

XCN_OID_NETSCAPE
Value: 289

XCN_OID_NETSCAPE_CERT_EXTENSION
Value: 290

XCN_OID_NETSCAPE_CERT_TYPE
Value: 291

XCN_OID_NETSCAPE_BASE_URL
Value: 292
XCN_OID_NETSCAPE_REVOCATION_URL
Value: 293

XCN_OID_NETSCAPE_CA_REVOCATION_URL
Value: 294

XCN_OID_NETSCAPE_CERT_RENEWAL_URL
Value: 295

XCN_OID_NETSCAPE_CA_POLICY_URL
Value: 296

XCN_OID_NETSCAPE_SSL_SERVER_NAME
Value: 297

XCN_OID_NETSCAPE_COMMENT
Value: 298

XCN_OID_NETSCAPE_DATA_TYPE
Value: 299

XCN_OID_NETSCAPE_CERT_SEQUENCE
Value: 300

XCN_OID_CT_PKI_DATA
Value: 301

XCN_OID_CT_PKI_RESPONSE
Value: 302

XCN_OID_PKIX_NO_SIGNATURE
Value: 303

XCN_OID_CMC
Value: 304

XCN_OID_CMC_STATUS_INFO
Value: 305

XCN_OID_CMC_IDENTIFICATION
Value: 306

XCN_OID_CMC_IDENTITY_PROOF
Value: 307

XCN_OID_CMC_DATA_RETURN
Value: 308

XCN_OID_CMC_TRANSACTION_ID
Value: 309
XCN_OID_CMC_SENDER_NONCE
Value: 310

XCN_OID_CMC_RECIPIENT_NONCE
Value: 311

XCN_OID_CMC_ADD_EXTENSIONS
Value: 312

XCN_OID_CMC_ENCRYPTED_POP
Value: 313

XCN_OID_CMC_DECRYPTED_POP
Value: 314

XCN_OID_CMC_LRA_POP_WITNESS
Value: 315

XCN_OID_CMC_GET_CERT
Value: 316

XCN_OID_CMC_GET_CRL
Value: 317

XCN_OID_CMC_REVOKE_REQUEST
Value: 318

XCN_OID_CMC_REG_INFO
Value: 319

XCN_OID_CMC_RESPONSE_INFO
Value: 320

XCN_OID_CMC_QUERY_PENDING
Value: 321

XCN_OID_CMC_ID_POP_LINK_RANDOM
Value: 322

XCN_OID_CMC_ID_POP_LINK_WITNESS
Value: 323

XCN_OID_CMC_ID_CONFIRM_CERT_ACCEPTANCE
Value: 324

XCN_OID_CMC_ADD_ATTRIBUTES
Value: 325

XCN_OID_LOYALTY_OTHER_LOGOTYPE
Value: 326
XCN_OID_BACKGROUND_OTHER_LOGOTYPE
Value: 327

XCN_OID_PKIX_OCSP_BASIC_SIGNED_RESPONSE
Value: 328

XCN_OID_PKCS_7_DATA
Value: 329

XCN_OID_PKCS_7_SIGNED
Value: 330

XCN_OID_PKCS_7_ENVELOPED
Value: 331

XCN_OID_PKCS_7_SIGNEDANDENVELOPED
Value: 332

XCN_OID_PKCS_7_DIGESTED
Value: 333

XCN_OID_PKCS_7_ENCRYPTED
Value: 334

XCN_OID_PKCS_9_CONTENT_TYPE
Value: 335

XCN_OID_PKCS_9_MESSAGE_DIGEST
Value: 336

XCN_OID_CERT_PROP_ID_PREFIX
Value: 337

XCN_OID_CERT_KEY_IDENTIFIER_PROP_ID
Value: 338

XCN_OID_CERT_ISSUER_SERIAL_NUMBER_MD5_HASH_PROP_ID
Value: 339

XCN_OID_CERT_SUBJECT_NAME_MD5_HASH_PROP_ID
Value: 340

XCN_OID_CERT_MD5_HASH_PROP_ID
Value: 341

XCN_OID_RSA_SHA256RSA
Value: 342

XCN_OID_RSA_SHA384RSA
Value: 343
XCN_OID_RSA_SHA512RSA
Value: 344

XCN_OID_NIST_sha256
Value: 345

XCN_OID_NIST_sha384
Value: 346

XCN_OID_NIST_sha512
Value: 347

XCN_OID_RSA_MGF1
Value: 348

XCN_OID_ECC_PUBLIC_KEY
Value: 349

XCN_OID_ECDSA_SHA1
Value: 350

XCN_OID_ECDSA_SPECIFIED
Value: 351

XCN_OID_ANY_ENHANCED_KEY_USAGE
Value: 352

XCN_OID_RSA_SSA_PSS
Value: 353

XCN_OID_ATTR_SUPPORTED_ALGORITHMS
Value: 355

XCN_OID_ATTR_TPM_SECURITY_ASSERTIONS
Value: 356

XCN_OID_ATTR_TPM_SPECIFICATION
Value: 357

XCN_OID_CERT_DISALLOWED_FILETIME_PROP_ID
Value: 358

XCN_OID_CERT_SIGNATURE_HASH_PROP_ID
Value: 359

XCN_OID_CERT_STRONG_KEY_OS_1
Value: 360

XCN_OID_CERT_STRONG_KEY_OS_CURRENT
Value: 361
XCN_OID_CERT_STRONG_KEY_OS_PREFIX
Value: 362

XCN_OID_CERT_STRONG_SIGN_OS_1
Value: 363

XCN_OID_CERT_STRONG_SIGN_OS_CURRENT
Value: 364

XCN_OID_CERT_STRONG_SIGN_OS_PREFIX
Value: 365

XCN_OID_DH_SINGLE_PASS_STDDH_SHA1_KDF
Value: 366

XCN_OID_DH_SINGLE_PASS_STDDH_SHA256_KDF
Value: 367

XCN_OID_DH_SINGLE_PASS_STDDH_SHA384_KDF
Value: 368

XCN_OID_DISALLOWED_HASH
Value: 369

XCN_OID_DISALLOWED_LIST
Value: 370

XCN_OID_ECC_CURVE_P256
Value: 371

XCN_OID_ECC_CURVE_P384
Value: 372

XCN_OID_ECC_CURVE_P521
Value: 373

XCN_OID_ECDSA_SHA256
Value: 374

XCN_OID_ECDSA_SHA384
Value: 375

XCN_OID_ECDSA_SHA512
Value: 376

XCN_OID_ENROLL_CAXCHGCERT_HASH
Value: 377

XCN_OID_ENROLL_EK_INFO
Value: 378
XCN_OID_ENROLL_EKPUB_CHALLENGE
Value: 379

XCN_OID_ENROLL_EKVERIFYCERT
Value: 380

XCN_OID_ENROLL_EKVERIFYCREDS
Value: 381

XCN_OID_ENROLL_EKVERIFYKEY
Value: 382

XCN_OID_EV_RDN_COUNTRY
Value: 383

XCN_OID_EV_RDN_LOCALE
Value: 384

XCN_OID_EV_RDN_STATE_OR_PROVINCE
Value: 385

XCN_OID_INHIBIT_ANY_POLICY
Value: 386

XCN_OID_INTERNATIONALIZED_EMAIL_ADDRESS
Value: 387

XCN_OID_KP_KERNEL_MODE_CODE_SIGNING
Value: 388

XCN_OID_KP_KERNEL_MODE_HAL_EXTENSION_SIGNING
Value: 389

XCN_OID_KP_KERNEL_MODE_TRUSTED_BOOT_SIGNING
Value: 390

XCN_OID_KP_TPM_AIK_CERTIFICATE
Value: 391

XCN_OID_KP_TPM_EK_CERTIFICATE
Value: 392

XCN_OID_KP_TPM_PLATFORM_CERTIFICATE
Value: 393

XCN_OID_NIST_AES128_CBC
Value: 394

XCN_OID_NIST_AES128_WRAP
Value: 395
XCN_OID_NIST_AES192_CBC
Value: 396

XCN_OID_NIST_AES192_WRAP
Value: 397

XCN_OID_NIST_AES256_CBC
Value: 398

XCN_OID_NIST_AES256_WRAP
Value: 399

XCN_OID_PKCS_12_PbeIds
Value: 400

XCN_OID_PKCS_12_pbeWithSHA1And128BitRC2
Value: 401

XCN_OID_PKCS_12_pbeWithSHA1And128BitRC4
Value: 402

XCN_OID_PKCS_12_pbeWithSHA1And2KeyTripleDES
Value: 403

XCN_OID_PKCS_12_pbeWithSHA1And3KeyTripleDES
Value: 404

XCN_OID_PKCS_12_pbeWithSHA1And40BitRC2
Value: 405

XCN_OID_PKCS_12_pbeWithSHA1And40BitRC4
Value: 406

XCN_OID_PKCS_12_PROTECTED_PASSWORD_SECRET_BAG_TYPE_ID
Value: 407

XCN_OID_PKINIT_KP_KDC
Value: 408

XCN_OID_PKIX_CA_REPOSITORY
Value: 409

XCN_OID_PKIX_OCSP_NONCE
Value: 410

XCN_OID_PKIX_TIME_STAMPING
Value: 411

XCN_OID_QC_EU_COMPLIANCE
Value: 412
XCN_OID_QC_SSCD
Value: 413

XCN_OID_QC_STATEMENTS_EXT
Value: 414

XCN_OID_RDN_TPM_MANUFACTURER
Value: 415

XCN_OID_RDN_TPM_MODEL
Value: 416

XCN_OID_RDN_TPM_VERSION
Value: 417

XCN_OID_REVOKED_LIST_SIGNER
Value: 418

XCN_OID_RFC3161_counterSign
Value: 419

XCN_OID_ROOT_PROGRAM_AUTO_UPDATE_CA_REVOCATION
Value: 420

XCN_OID_ROOT_PROGRAM_AUTO_UPDATE_END_REVOCATION
Value: 421

XCN_OID_ROOT_PROGRAM_FLAGS
Value: 422

XCN_OID_ROOT_PROGRAM_NO_OCSP_FAILOVER_TO_CRL
Value: 423

XCN_OID_RSA_PSPECIFIED
Value: 424

XCN_OID_RSAES_OAEP
Value: 425

XCN_OID_SUBJECT_INFO_ACCESS
Value: 426

XCN_OID_TIMESTAMP_TOKEN
Value: 427

XCN_OID_ENROLL_SCEP_ERROR
Value: 428

XCN_OIDVerisign_MessageType
Value: 429
 XCN_OIDVerisign_PkiStatus
Value: 430

XCN_OIDVerisign_FailInfo
Value: 431

XCN_OIDVerisign_SenderNonce
Value: 432

XCN_OIDVerisign_RecipientNonce
Value: 433

XCN_OIDVerisign_TransactionID
Value: 434

XCN_OID_ENROLL_ATTESTATION_CHALLENGE
Value: 435

XCN_OID_ENROLL_ATTESTATION_STATEMENT
Value: 436

XCN_OID_ENROLL_ENCRYPTION_ALGORITHM
Value: 437

XCN_OID_ENROLL_KSP_NAME
Value: 438

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Header certenroll.h

See also
CertEnroll Enumerations
CertEnroll Interfaces
 CERTENROLL_PROPERTYID enumeration
(certenroll.h)
7/2/2022 • 10 minutes to read • Edit Online

The CERTENROLL_PROPERTYID enumeration type contains predefined object identifiers for external
properties that can be associated with a certificate in the certificate store. This enumeration is used by the
ICertProperty interface.
The descriptions for each of the supported values identify the property data type so that you know how to
create the value before calling the InitializeDecode method. The following interfaces, derived from ICertProperty,
have been defined to simplify initialization and retrieval of the most common properties:
ICertPropertyArchived
ICertPropertyArchivedKeyHash
ICertPropertyAutoEnroll
ICertPropertyBackedUp
ICertPropertyDescription
ICertPropertyEnrollment
ICertPropertyEnrollmentPolicyServer
ICertPropertyFriendlyName
ICertPropertyKeyProvInfo
ICertPropertyRenewal
ICertPropertyRequestOriginator
ICertPropertySHA1Hash

Syntax
typedef enum CERTENROLL_PROPERTYID {
XCN_PROPERTYID_NONE = 0,
XCN_CERT_KEY_PROV_HANDLE_PROP_ID = 1,
XCN_CERT_KEY_PROV_INFO_PROP_ID = 2,
XCN_CERT_SHA1_HASH_PROP_ID = 3,
XCN_CERT_MD5_HASH_PROP_ID = 4,
XCN_CERT_HASH_PROP_ID = 3,
XCN_CERT_KEY_CONTEXT_PROP_ID = 5,
XCN_CERT_KEY_SPEC_PROP_ID = 6,
XCN_CERT_IE30_RESERVED_PROP_ID = 7,
XCN_CERT_PUBKEY_HASH_RESERVED_PROP_ID = 8,
XCN_CERT_ENHKEY_USAGE_PROP_ID = 9,
XCN_CERT_CTL_USAGE_PROP_ID = 9,
XCN_CERT_NEXT_UPDATE_LOCATION_PROP_ID = 10,
XCN_CERT_FRIENDLY_NAME_PROP_ID = 11,
XCN_CERT_PVK_FILE_PROP_ID = 12,
XCN_CERT_DESCRIPTION_PROP_ID = 13,
XCN_CERT_ACCESS_STATE_PROP_ID = 14,
XCN_CERT_SIGNATURE_HASH_PROP_ID = 15,
XCN_CERT_SMART_CARD_DATA_PROP_ID = 16,
XCN_CERT_EFS_PROP_ID = 17,
XCN_CERT_FORTEZZA_DATA_PROP_ID = 18,
XCN_CERT_ARCHIVED_PROP_ID = 19,
XCN_CERT_KEY_IDENTIFIER_PROP_ID = 20,
XCN_CERT_AUTO_ENROLL_PROP_ID = 21,
XCN_CERT_PUBKEY_ALG_PARA_PROP_ID = 22,
XCN_CERT_CROSS_CERT_DIST_POINTS_PROP_ID = 23,
XCN_CERT_CROSS_CERT_DIST_POINTS_PROP_ID = 23,
XCN_CERT_ISSUER_PUBLIC_KEY_MD5_HASH_PROP_ID = 24,
XCN_CERT_SUBJECT_PUBLIC_KEY_MD5_HASH_PROP_ID = 25,
XCN_CERT_ENROLLMENT_PROP_ID = 26,
XCN_CERT_DATE_STAMP_PROP_ID = 27,
XCN_CERT_ISSUER_SERIAL_NUMBER_MD5_HASH_PROP_ID = 28,
XCN_CERT_SUBJECT_NAME_MD5_HASH_PROP_ID = 29,
XCN_CERT_EXTENDED_ERROR_INFO_PROP_ID = 30,
XCN_CERT_RENEWAL_PROP_ID = 64,
XCN_CERT_ARCHIVED_KEY_HASH_PROP_ID = 65,
XCN_CERT_AUTO_ENROLL_RETRY_PROP_ID = 66,
XCN_CERT_AIA_URL_RETRIEVED_PROP_ID = 67,
XCN_CERT_AUTHORITY_INFO_ACCESS_PROP_ID = 68,
XCN_CERT_BACKED_UP_PROP_ID = 69,
XCN_CERT_OCSP_RESPONSE_PROP_ID = 70,
XCN_CERT_REQUEST_ORIGINATOR_PROP_ID = 71,
XCN_CERT_SOURCE_LOCATION_PROP_ID = 72,
XCN_CERT_SOURCE_URL_PROP_ID = 73,
XCN_CERT_NEW_KEY_PROP_ID = 74,
XCN_CERT_OCSP_CACHE_PREFIX_PROP_ID = 75,
XCN_CERT_SMART_CARD_ROOT_INFO_PROP_ID = 76,
XCN_CERT_NO_AUTO_EXPIRE_CHECK_PROP_ID = 77,
XCN_CERT_NCRYPT_KEY_HANDLE_PROP_ID = 78,
XCN_CERT_HCRYPTPROV_OR_NCRYPT_KEY_HANDLE_PROP_ID = 79,
XCN_CERT_SUBJECT_INFO_ACCESS_PROP_ID = 80,
XCN_CERT_CA_OCSP_AUTHORITY_INFO_ACCESS_PROP_ID = 81,
XCN_CERT_CA_DISABLE_CRL_PROP_ID = 82,
XCN_CERT_ROOT_PROGRAM_CERT_POLICIES_PROP_ID = 83,
XCN_CERT_ROOT_PROGRAM_NAME_CONSTRAINTS_PROP_ID = 84,
XCN_CERT_SUBJECT_OCSP_AUTHORITY_INFO_ACCESS_PROP_ID = 85,
XCN_CERT_SUBJECT_DISABLE_CRL_PROP_ID = 86,
XCN_CERT_CEP_PROP_ID = 87,
XCN_CERT_SIGN_HASH_CNG_ALG_PROP_ID = 89,
XCN_CERT_SCARD_PIN_ID_PROP_ID = 90,
XCN_CERT_SCARD_PIN_INFO_PROP_ID = 91,
XCN_CERT_SUBJECT_PUB_KEY_BIT_LENGTH_PROP_ID = 92,
XCN_CERT_PUB_KEY_CNG_ALG_BIT_LENGTH_PROP_ID = 93,
XCN_CERT_ISSUER_PUB_KEY_BIT_LENGTH_PROP_ID = 94,
XCN_CERT_ISSUER_CHAIN_SIGN_HASH_CNG_ALG_PROP_ID = 95,
XCN_CERT_ISSUER_CHAIN_PUB_KEY_CNG_ALG_BIT_LENGTH_PROP_ID = 96,
XCN_CERT_NO_EXPIRE_NOTIFICATION_PROP_ID = 97,
XCN_CERT_AUTH_ROOT_SHA256_HASH_PROP_ID = 98,
XCN_CERT_NCRYPT_KEY_HANDLE_TRANSFER_PROP_ID = 99,
XCN_CERT_HCRYPTPROV_TRANSFER_PROP_ID = 100,
XCN_CERT_SMART_CARD_READER_PROP_ID = 101,
XCN_CERT_SEND_AS_TRUSTED_ISSUER_PROP_ID = 102,
XCN_CERT_KEY_REPAIR_ATTEMPTED_PROP_ID = 103,
XCN_CERT_DISALLOWED_FILETIME_PROP_ID = 104,
XCN_CERT_ROOT_PROGRAM_CHAIN_POLICIES_PROP_ID = 105,
XCN_CERT_SMART_CARD_READER_NON_REMOVABLE_PROP_ID = 106,
XCN_CERT_SHA256_HASH_PROP_ID = 107,
XCN_CERT_SCEP_SERVER_CERTS_PROP_ID = 108,
XCN_CERT_SCEP_RA_SIGNATURE_CERT_PROP_ID = 109,
XCN_CERT_SCEP_RA_ENCRYPTION_CERT_PROP_ID = 110,
XCN_CERT_SCEP_CA_CERT_PROP_ID = 111,
XCN_CERT_SCEP_SIGNER_CERT_PROP_ID = 112,
XCN_CERT_SCEP_NONCE_PROP_ID = 113,
XCN_CERT_SCEP_ENCRYPT_HASH_CNG_ALG_PROP_ID = 114,
XCN_CERT_SCEP_FLAGS_PROP_ID = 115,
XCN_CERT_SCEP_GUID_PROP_ID = 116,
XCN_CERT_SERIALIZABLE_KEY_CONTEXT_PROP_ID = 117,
XCN_CERT_ISOLATED_KEY_PROP_ID = 118,
XCN_CERT_SERIAL_CHAIN_PROP_ID = 119,
XCN_CERT_KEY_CLASSIFICATION_PROP_ID = 120,
XCN_CERT_DISALLOWED_ENHKEY_USAGE_PROP_ID = 122,
XCN_CERT_NONCOMPLIANT_ROOT_URL_PROP_ID = 123,
XCN_CERT_PIN_SHA256_HASH_PROP_ID = 124,
XCN_CERT_CLR_DELETE_KEY_PROP_ID = 125,
XCN_CERT_NOT_BEFORE_FILETIME_PROP_ID = 126,
 XCN_CERT_CERT_NOT_BEFORE_ENHKEY_USAGE_PROP_ID = 127,
XCN_CERT_FIRST_RESERVED_PROP_ID = 128,
XCN_CERT_LAST_RESERVED_PROP_ID = 0x7fff,
XCN_CERT_FIRST_USER_PROP_ID = 0x8000,
XCN_CERT_LAST_USER_PROP_ID = 0xffff,
XCN_CERT_STORE_LOCALIZED_NAME_PROP_ID = 0x1000
} ;

Constants

XCN_PROPERTYID_NONE
Value: 0
No property is identified.

XCN_CERT_KEY_PROV_HANDLE_PROP_ID
Value: 1
Data type: HCRYPTPROV

The handle of the private key associated with the certificate.

XCN_CERT_KEY_PROV_INFO_PROP_ID
Value: 2
Data type: pointer to a CRYPT_KEY_PROV_INFO structure.

The structure contains information about a CSP key container or a Cryptography API: Next Generation (CNG) key. This is used
to acquire a handle to the private key. We recommend that you use the ICertPropertyKeyProvInfo interface to initialize and
retrieve this property.

XCN_CERT_SHA1_HASH_PROP_ID
Value: 3
Data type: pointer to a CRYPT_INTEGER_BLOB structure.

The pbData structure member points to a byte array that contains a SHA-1 hash value of the certificate. We recommend that
you use the ICertPropertySHA1Hash interface to initialize and retrieve this property.

XCN_CERT_MD5_HASH_PROP_ID
Value: 4
Data type: pointer to a CRYPT_INTEGER_BLOB structure.

The pbData structure member points to a byte array that contains an MD5 hash value of the certificate.

XCN_CERT_HASH_PROP_ID
Value: 3
Data type: pointer to a CRYPT_INTEGER_BLOB structure.

The pbData structure member points to a byte array that contains a hash of the certificate created by using the default
hashing algorithm. The default algorithm is currently SHA-1.

XCN_CERT_KEY_CONTEXT_PROP_ID
Value: 5
Data type: pointer to a CERT_KEY_CONTEXT structure.

The structure contains the information necessary to retrieve a key, including the CSP or key service provider (KSP) handle and
a value that indicates whether the key is used for signing or encryption.
XCN_CERT_KEY_SPEC_PROP_ID
Value: 6
Data type: pointer to a DWORD .

The DWORD contains a value that identifies whether the key is used for signing or for encryption and whether the key is
associated with a CNG KSP. This is the same as the value specified in the dwKeySpec parameter of the CERT_KEY_CONTEXT
structure. This value can be a bitwise-OR combination of the following values:

AT_KEYEXCHANGE

AT_SIGNATURE

CERT_NCRYPT_KEY_SPEC

XCN_CERT_IE30_RESERVED_PROP_ID
Value: 7
Not supported.

XCN_CERT_PUBKEY_HASH_RESERVED_PROP_ID
Value: 8
Not supported.

XCN_CERT_ENHKEY_USAGE_PROP_ID
Value: 9
Data type: pointer to a CRYPT_INTEGER_BLOB structure.

The pbData structure member points to a byte array that contains a DER-encoded EnhancedKeyUsage extension in a
CERT_ENHKEY_USAGE structure. You can encode the structure by using the CryptoAPI CryptEncodeObject function and
setting the lpszStructType parameter to X509_ENHANCED_KEY_USAGE .

syntax<br>typedef struct _CTL_USAGE <br>{<br> DWORD cUsageIdentifier;<br> LPSTR *rgpszUsageIdentifier; <br>}

<br>CTL_USAGE, *PCTL_USAGE, CERT_ENHKEY_USAGE, *PCERT_ENHKEY_USAGE;<br>

XCN_CERT_CTL_USAGE_PROP_ID
Value: 9
Data type: pointer to a CRYPT_INTEGER_BLOB structure.

The pbData structure member points to a byte array that contains a DER-encoded certificate trust list (CTL) usage identifier in
a CTL_USAGE structure. You can encode the structure by using the CryptoAPI CryptEncodeObject function and setting the
lpszStructType parameter to X509_ENHANCED_KEY_USAGE .

syntax<br>typedef struct _CTL_USAGE <br>{<br> DWORD cUsageIdentifier;<br> LPSTR *rgpszUsageIdentifier; <br>}

<br>CTL_USAGE;<br>

XCN_CERT_NEXT_UPDATE_LOCATION_PROP_ID
Value: 10
Data type: pointer to a CRYPT_INTEGER_BLOB structure.

The pbData structure member points to a byte array that contains a DER-encoded AlternativeNames extension in a
CERT_ALT_NAME_INFO structure. You can encode the structure by using the CryptoAPI CryptEncodeObject function and
setting the lpszStructType parameter to X509_ALTERNATE_NAME .
 XCN_CERT_FRIENDLY_NAME_PROP_ID
Value: 11
Data type: pointer to a CRYPT_INTEGER_BLOB structure.

The pbData structure member contains a pointer to a null-terminated Unicode string that contains the display name for the
certificate. We recommend that you use the ICertPropertyFriendlyName interface to initialize and retrieve this property.

XCN_CERT_PVK_FILE_PROP_ID
Value: 12
Data type: pointer to a CRYPT_INTEGER_BLOB structure.

The pbData structure member contains a pointer to a null-terminated Unicode string that contains the name of the private
key file.

XCN_CERT_DESCRIPTION_PROP_ID
Value: 13
Data type: pointer to a CRYPT_INTEGER_BLOB structure.

The pbData structure member contains a pointer to a null-terminated Unicode string that contains a description of the
certificate. We recommend that you use the ICertPropertyDescription interface to initialize and retrieve this property.

XCN_CERT_ACCESS_STATE_PROP_ID
Value: 14
Data type: pointer to a DWORD .

The DWORD can contain a value that is a bitwise-OR combination of the following flags:

CERT_ACCESS_STATE_WRITE_PERSIST_FLAG (0x1)

CERT_ACCESS_STATE_SYSTEM_STORE_FLAG (0x2)

CERT_ACCESS_STATE_LM_SYSTEM_STORE_FLAG (0x4)

CERT_ACCESS_STATE_GP_SYSTEM_STORE_FLAG (0x8)

This is a read-only property and cannot be associated with an existing certificate by calling the SetValueOnCertificate method.
You can retrieve it by calling the RawData property after initializing the property value by using the InitializeFromCertificate
method.

XCN_CERT_SIGNATURE_HASH_PROP_ID
Value: 15
Data type: pointer to a CRYPT_INTEGER_BLOB structure.

The pbData structure member points to a byte array that contains a hash of the certificate signature.

XCN_CERT_SMART_CARD_DATA_PROP_ID
Value: 16
Not supported.

XCN_CERT_EFS_PROP_ID
Value: 17
Not supported.

XCN_CERT_FORTEZZA_DATA_PROP_ID
Value: 18
Not supported.
 XCN_CERT_ARCHIVED_PROP_ID
Value: 19
Data type: pointer to a CRYPT_INTEGER_BLOB structure.

The pbData structure member points to a byte array that identifies whether a certificate is archived. A certificate is typically
archived when it has been replaced by a newer certificate. Subsequent enumeration of the certificate store usually skips the
archived certificates. To indicate that the certificate is not archived, you can set pbData to NULL and cbData to zero (0). To
indicate that the certificate is archived, you can set pbData to something other than NULL such as the address of the
CRYPT_INTEGER_BLOB structure. We recommend, however, that you use the ICertPropertyArchived interface to set this
property.

XCN_CERT_KEY_IDENTIFIER_PROP_ID
Value: 20
Data type: pointer to a CRYPT_INTEGER_BLOB structure.

The pbData structure member points to a byte array that contains the hash of the certificate subject public key. Typically, this
is a 20-byte SHA-1 hash. For more information, see the IX509ExtensionSubjectKeyIdentifier interface.

XCN_CERT_AUTO_ENROLL_PROP_ID
Value: 21
Data type: pointer to a CRYPT_INTEGER_BLOB structure.

The pbData structure member contains a pointer to a null-terminated Unicode string that contains the name or object
identifier used for auto-enrollment. We recommend that you use the ICertPropertyAutoEnroll interface to initialize and
retrieve this property.

XCN_CERT_PUBKEY_ALG_PARA_PROP_ID
Value: 22
Data type: pointer to a CRYPT_INTEGER_BLOB structure.

The pbData structure member points to the DER-encoded public key algorithm parameters. For more information, see the
EncodedParameters property on the IX509PublicKey interface.

XCN_CERT_CROSS_CERT_DIST_POINTS_PROP_ID
Value: 23
Data type: pointer to a CRYPT_INTEGER_BLOB structure.

The pbData structure member points to a byte array that contains a DER-encoded CROSS_CERT_DIST_POINTS_INFO
structure. You can encode the structure by using the CryptoAPI CryptEncodeObject function and setting the lpszStructType
parameter to X509_CROSS_CERT_DIST_POINTS.

XCN_CERT_ISSUER_PUBLIC_KEY_MD5_HASH_PROP_ID
Value: 24
Data type: pointer to a CRYPT_INTEGER_BLOB structure.

The pbData structure member points to a byte array that contains an MD5 hash of the public key associated with the private
key used to sign the certificate.

XCN_CERT_SUBJECT_PUBLIC_KEY_MD5_HASH_PROP_ID
Value: 25
Data type: pointer to a CRYPT_INTEGER_BLOB structure.

The pbData structure member points to a byte array that contains an MD5 hash of the public key contained in the certificate.
 XCN_CERT_ENROLLMENT_PROP_ID
Value: 26
Data type: pointer to a CRYPT_INTEGER_BLOB structure.

The pbData structure member points to a byte array that contains the following information (in the order listed) about a
pending request. Each Unicode string is null-terminated, and the length includes the terminating null character.

Request ID length (4 bytes)

Request ID string

CA DNS name string length (4 bytes)

CA DNS name string

CA name string length (4 bytes)

CA name string

Display name length (4 bytes)

Display name string

We recommend that you use the ICertPropertyEnrollment interface to initialize and retrieve this property.

XCN_CERT_DATE_STAMP_PROP_ID
Value: 27
Data type: pointer to a FILETIME structure.

The structure contains the time that the certificate was added to the certificate store.

XCN_CERT_ISSUER_SERIAL_NUMBER_MD5_HASH_PROP_ID
Value: 28
Data type: pointer to a CRYPT_INTEGER_BLOB structure.

The pbData structure member points to a byte array that contains an MD5 hash of the CA signing certificate serial number.

XCN_CERT_SUBJECT_NAME_MD5_HASH_PROP_ID
Value: 29
Data type: pointer to a CRYPT_INTEGER_BLOB structure.

The pbData structure member points to a byte array that contains an MD5 hash of the subject name.

XCN_CERT_EXTENDED_ERROR_INFO_PROP_ID
Value: 30
Data type: pointer to a CRYPT_INTEGER_BLOB structure.

The pbData structure member points to a null-terminated Unicode string that contains information about an error.

XCN_CERT_RENEWAL_PROP_ID
Value: 64
Data type: pointer to a CRYPT_INTEGER_BLOB structure.

The pbData structure member points to a byte array that contains a SHA-1 hash of the certificate that is being renewed. We
recommend that you use the ICertPropertyRenewal interface to initialize and retrieve this property.
XCN_CERT_ARCHIVED_KEY_HASH_PROP_ID
Value: 65
Data type: pointer to a CRYPT_INTEGER_BLOB structure.

The pbData structure member points to a byte array that contains a hash of the archived private key. We recommend that
you use the ICertPropertyArchivedKeyHash interface to initialize and retrieve this property value.

XCN_CERT_AUTO_ENROLL_RETRY_PROP_ID
Value: 66
Not supported.

XCN_CERT_AIA_URL_RETRIEVED_PROP_ID
Value: 67
Not supported.

XCN_CERT_AUTHORITY_INFO_ACCESS_PROP_ID
Value: 68
Not supported.

XCN_CERT_BACKED_UP_PROP_ID
Value: 69
Data type: pointer to a CRYPT_INTEGER_BLOB structure.

The pbData structure member points to a byte array that contains a VARIANT_BOOL followed by a FILETIME structure. To
specify that the certificate is not backed up, set the first sizeof(VARIANT_BOOL) bytes in the array to zero (0). Otherwise,
specify a value that is not zero. To specify the time at which the certificate was backed up, set the next sizeof(FILETIME)
bytes to the date and time. We recommend that you use the ICertPropertyBackedUp interface to set this property value. This
property is not currently used.

XCN_CERT_OCSP_RESPONSE_PROP_ID
Value: 70
Not supported.

XCN_CERT_REQUEST_ORIGINATOR_PROP_ID
Value: 71
Data type: pointer to a CRYPT_INTEGER_BLOB structure.

The pbData structure member points to a null-terminated Unicode string that contains the name of the computer that
originated an auto-enrollment certificate request. We recommend that you use the ICertPropertyRequestOriginator interface
to initialize and retrieve this property.

XCN_CERT_SOURCE_LOCATION_PROP_ID
Value: 72
Not supported.

XCN_CERT_SOURCE_URL_PROP_ID
Value: 73
Not supported.

XCN_CERT_NEW_KEY_PROP_ID
Value: 74
Not supported.

XCN_CERT_OCSP_CACHE_PREFIX_PROP_ID
Value: 75
 XCN_CERT_SMART_CARD_ROOT_INFO_PROP_ID
Value: 76

XCN_CERT_NO_AUTO_EXPIRE_CHECK_PROP_ID
Value: 77

XCN_CERT_NCRYPT_KEY_HANDLE_PROP_ID
Value: 78

XCN_CERT_HCRYPTPROV_OR_NCRYPT_KEY_HANDLE_PROP_ID
Value: 79

XCN_CERT_SUBJECT_INFO_ACCESS_PROP_ID
Value: 80

XCN_CERT_CA_OCSP_AUTHORITY_INFO_ACCESS_PROP_ID
Value: 81

XCN_CERT_CA_DISABLE_CRL_PROP_ID
Value: 82

XCN_CERT_ROOT_PROGRAM_CERT_POLICIES_PROP_ID
Value: 83

XCN_CERT_ROOT_PROGRAM_NAME_CONSTRAINTS_PROP_ID
Value: 84

XCN_CERT_SUBJECT_OCSP_AUTHORITY_INFO_ACCESS_PROP_ID
Value: 85

XCN_CERT_SUBJECT_DISABLE_CRL_PROP_ID
Value: 86

XCN_CERT_CEP_PROP_ID
Value: 87
Contains information about a certificate enrollment policy (CEP) server and a certificate enrollment server (CES). This includes:

The CEP authentication method.

The CES authentication method.

The CEP URL.

The CES URL

The CEP ID.

The request ID string.

For more information, see ICertPropertyEnrollmentPolicyServer.

XCN_CERT_SIGN_HASH_CNG_ALG_PROP_ID
Value: 89

XCN_CERT_SCARD_PIN_ID_PROP_ID
Value: 90

XCN_CERT_SCARD_PIN_INFO_PROP_ID
Value: 91

XCN_CERT_SUBJECT_PUB_KEY_BIT_LENGTH_PROP_ID
Value: 92

XCN_CERT_PUB_KEY_CNG_ALG_BIT_LENGTH_PROP_ID
Value: 93

XCN_CERT_ISSUER_PUB_KEY_BIT_LENGTH_PROP_ID
Value: 94

XCN_CERT_ISSUER_CHAIN_SIGN_HASH_CNG_ALG_PROP_ID
Value: 95

XCN_CERT_ISSUER_CHAIN_PUB_KEY_CNG_ALG_BIT_LENGTH_PROP_ID
Value: 96

XCN_CERT_NO_EXPIRE_NOTIFICATION_PROP_ID
Value: 97

XCN_CERT_AUTH_ROOT_SHA256_HASH_PROP_ID
Value: 98

XCN_CERT_NCRYPT_KEY_HANDLE_TRANSFER_PROP_ID
Value: 99

XCN_CERT_HCRYPTPROV_TRANSFER_PROP_ID
Value: 100

XCN_CERT_SMART_CARD_READER_PROP_ID
Value: 101

XCN_CERT_SEND_AS_TRUSTED_ISSUER_PROP_ID
Value: 102

XCN_CERT_KEY_REPAIR_ATTEMPTED_PROP_ID
Value: 103

XCN_CERT_DISALLOWED_FILETIME_PROP_ID
Value: 104

XCN_CERT_ROOT_PROGRAM_CHAIN_POLICIES_PROP_ID
Value: 105
XCN_CERT_SMART_CARD_READER_NON_REMOVABLE_PROP_ID
Value: 106

XCN_CERT_SHA256_HASH_PROP_ID
Value: 107

XCN_CERT_SCEP_SERVER_CERTS_PROP_ID
Value: 108

XCN_CERT_SCEP_RA_SIGNATURE_CERT_PROP_ID
Value: 109

XCN_CERT_SCEP_RA_ENCRYPTION_CERT_PROP_ID
Value: 110

XCN_CERT_SCEP_CA_CERT_PROP_ID
Value: 111

XCN_CERT_SCEP_SIGNER_CERT_PROP_ID
Value: 112

XCN_CERT_SCEP_NONCE_PROP_ID
Value: 113

XCN_CERT_SCEP_ENCRYPT_HASH_CNG_ALG_PROP_ID
Value: 114

XCN_CERT_SCEP_FLAGS_PROP_ID
Value: 115

XCN_CERT_SCEP_GUID_PROP_ID
Value: 116

XCN_CERT_SERIALIZABLE_KEY_CONTEXT_PROP_ID
Value: 117

XCN_CERT_ISOLATED_KEY_PROP_ID
Value: 118

XCN_CERT_SERIAL_CHAIN_PROP_ID
Value: 119

XCN_CERT_KEY_CLASSIFICATION_PROP_ID
Value: 120

XCN_CERT_DISALLOWED_ENHKEY_USAGE_PROP_ID
Value: 122

XCN_CERT_NONCOMPLIANT_ROOT_URL_PROP_ID
Value: 123
 XCN_CERT_PIN_SHA256_HASH_PROP_ID
Value: 124

XCN_CERT_CLR_DELETE_KEY_PROP_ID
Value: 125

XCN_CERT_NOT_BEFORE_FILETIME_PROP_ID
Value: 126

XCN_CERT_CERT_NOT_BEFORE_ENHKEY_USAGE_PROP_ID
Value: 127

XCN_CERT_FIRST_RESERVED_PROP_ID
Value: 128
Not supported.

XCN_CERT_LAST_RESERVED_PROP_ID
Value: 0x7fff
Not supported.

XCN_CERT_FIRST_USER_PROP_ID
Value: 0x8000
The minimum number for a user-defined property ID.

XCN_CERT_LAST_USER_PROP_ID
Value: 0xffff
The maximum number for a user-defined property ID.

XCN_CERT_STORE_LOCALIZED_NAME_PROP_ID
Value: 0x1000
Data type: pointer to a CRYPT_INTEGER_BLOB structure.

The pbData structure member points to a null-terminated Unicode string that contains the localized name of the certificate
store.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Header certenroll.h

See also
CertEnroll Enumerations
CertEnroll Interfaces
 CommitTemplateFlags enumeration (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The CommitTemplateFlags enumeration type specifies options for saving and deleting templates. It is used by
the Commit method on the IX509CertificateTemplateWritable interface.

Syntax
typedef enum CommitTemplateFlags {
CommitFlagSaveTemplateGenerateOID = 1,
CommitFlagSaveTemplateUseCurrentOID = 2,
CommitFlagSaveTemplateOverwrite = 3,
CommitFlagDeleteTemplate = 4
} ;

Constants

CommitFlagSaveTemplateGenerateOID
Value: 1
Save the template and create an object identifier for it.

CommitFlagSaveTemplateUseCurrentOID
Value: 2
Not used.

CommitFlagSaveTemplateOverwrite
Value: 3
Not used.

CommitFlagDeleteTemplate
Value: 4
Delete the template.

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Header certenroll.h

See also
Commit
IX509CertificateTemplateWritable
 EncodingType enumeration (certenroll.h)
7/2/2022 • 3 minutes to read • Edit Online

The EncodingType enumeration specifies the type of encoding applied to a byte array for display purposes.

Syntax
typedef enum EncodingType {
XCN_CRYPT_STRING_BASE64HEADER = 0,
XCN_CRYPT_STRING_BASE64 = 0x1,
XCN_CRYPT_STRING_BINARY = 0x2,
XCN_CRYPT_STRING_BASE64REQUESTHEADER = 0x3,
XCN_CRYPT_STRING_HEX = 0x4,
XCN_CRYPT_STRING_HEXASCII = 0x5,
XCN_CRYPT_STRING_BASE64_ANY = 0x6,
XCN_CRYPT_STRING_ANY = 0x7,
XCN_CRYPT_STRING_HEX_ANY = 0x8,
XCN_CRYPT_STRING_BASE64X509CRLHEADER = 0x9,
XCN_CRYPT_STRING_HEXADDR = 0xa,
XCN_CRYPT_STRING_HEXASCIIADDR = 0xb,
XCN_CRYPT_STRING_HEXRAW = 0xc,
XCN_CRYPT_STRING_BASE64URI = 0xd,
XCN_CRYPT_STRING_ENCODEMASK = 0xff,
XCN_CRYPT_STRING_CHAIN = 0x100,
XCN_CRYPT_STRING_TEXT = 0x200,
XCN_CRYPT_STRING_PERCENTESCAPE = 0x8000000,
XCN_CRYPT_STRING_HASHDATA = 0x10000000,
XCN_CRYPT_STRING_STRICT = 0x20000000,
XCN_CRYPT_STRING_NOCRLF = 0x40000000,
XCN_CRYPT_STRING_NOCR = 0x80000000
} ;

Constants

XCN_CRYPT_STRING_BASE64HEADER
Value: 0
The string is base64 encoded with beginning and ending certificate headers. Base64 is an encoding scheme used to transmit
binary data. The data to be encoded is examined three bytes at a time. Every six bits in the 24-bit buffer is used as an index
into a text string. The strings used vary depending on the type of data being encoded. The following string is commonly used
for Multipurpose Internet Mail Extensions (MIME) email base64 encoding.

syntax<br>ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/<br>

The following example shows a certificate that is base64 encoded and includes the beginning and ending headers.

syntax<br>-----BEGIN CERTIFICATE-----
<br>MIIBqDCCARECAQAwaTELMAkGA1UEBhMCVVMxDjAMBgNVBAgTBVRleGFzMRMwEQYD<br>VQQHEwpMYXNDb2xpbmFzMRIwEAYDVQQKEwlNaWNyb3NvZnQxDjAMBgNVBAsTBUl0<br>ZWFtMREwDwYDVQQDFAhOVFZPT0RP
<br>WD30lAfGBr8SZixLep4pMIN/wO0eu6f30cBuoPtDnDulNT8AuQHjkJIc8Qc=<br>-----END CERTIFICATE----- <br>

XCN_CRYPT_STRING_BASE64
Value: 0x1
The string is base64 encoded without beginning and ending certificate headers.

XCN_CRYPT_STRING_BINARY
Value: 0x2
The string is a pure binary sequence. It is not encoded.

XCN_CRYPT_STRING_BASE64REQUESTHEADER
Value: 0x3
The string is base64 encoded with beginning and ending certificate request headers. This is shown in the following example.

syntax<br>-----BEGIN NEW CERTIFICATE REQUEST-----

<br>MIIDBjCCAm8CAQAwcTERMA8GA1UEAxMIcXV1eC5jb20xDzANBgNVBAsTBkJyYWlu<br>czEWMBQGA1UEChMNRGV2ZWxvcE1lbnRvcjERMA8GA1UEBxMIVG9ycmFuY2UxEzAR<br>BgNVBAgTCkNhbGlmb3JuaWExCzAJ
<br>-----END NEW CERTIFICATE REQUEST-----<br>

XCN_CRYPT_STRING_HEX
Value: 0x4
The string is hexadecimal encoded. Each 4-bit nibble of the string is represented as a number between zero and nine or a
letter between A and F (or a and f). This is shown in the following example.

syntax<br>3a 20 63 65 72 74 6c 69 62 5c 6c 64 61 70 2e 63<br>70 70 28 32 31 33 31 29 3a 20 6c 64 61 70 65
72<br>...<br>

XCN_CRYPT_STRING_HEXASCII
Value: 0x5
The string is hexadecimal encoded, and the corresponding ASCII characters are displayed. This is shown in the following
example.

syntax<br>3a 20 63 65 72 74 6c 69 62 5c 6c 64 61 70 2e 63 : certlib\ldap.c<br>70 70 28 32 31 33 31 29 3a 20
6c 64 61 70 65 72 pp(2131): ldaper<br>...<br>
 XCN_CRYPT_STRING_BASE64_ANY
Value: 0x6
The string is base64 encoded. Enumeration values are tried in the following order:

1. XCN_CRYPT_STRING_BASE64HEADER

2. XCN_CRYPT_STRING_BASE64

XCN_CRYPT_STRING_ANY
Value: 0x7
Enumeration values are tried in the following order:

1. XCN_CRYPT_STRING_BASE64_ANY

2. XCN_CRYPT_STRING_BINARY

The XCN_CRYPT_STRING_BINARY value always succeeds.

XCN_CRYPT_STRING_HEX_ANY
Value: 0x8
Enumeration values are tried in the following order:

1. XCN_CRYPT_STRING_HEXADDR

2. XCN_CRYPT_STRING_HEXASCIIADDR

3. XCN_CRYPT_STRING_HEXASCII

4. XCN_CRYPT_STRING_HEX

XCN_CRYPT_STRING_BASE64X509CRLHEADER
Value: 0x9
The string is base64 encoded with beginning and ending X.509 certificate revocation list (CRL) headers. This is shown in the
following example.

syntax<br>-----BEGIN X509 CRL-----

<br>MIIDBjCCAm8CAQAwcTERMA8GA1UEAxMIcXV1eC5jb20xDzANBgNVBAsTBkJyYWlu<br>czEWMBQGA1UEChMNRGV2ZWxvcE1lbnRvcjERMA8GA1UEBxMIVG9ycmFuY2UxEzAR<br>BgNVBAgTCkNhbGlmb3JuaWExCzAJ
<br>-----END X509 CRL-----<br>

XCN_CRYPT_STRING_HEXADDR
Value: 0xa
The string is hexadecimal encoded and displayed as a hexadecimal address. This is shown in the following example.

syntax<br>0000 3a 20 63 65 72 74 6c 69 62 5c 6c 64 61 70 2e 63<br>0010 70 70 28 32 31 33 31 29 3a 20 6c 64
61 70 65 72<br>...<br>

XCN_CRYPT_STRING_HEXASCIIADDR
Value: 0xb
The string is hexadecimal encoded and displayed as a hexadecimal address along with the corresponding ASCII characters. This
is shown in the following example.

syntax<br>0000 3a 20 63 65 72 74 6c 69 62 5c 6c 64 61 70 2e 63 : certlib\ldap.c<br>0010 70 70 28 32 31 33 31
29 3a 20 6c 64 61 70 65 72 pp(2131): ldaper<br>...<br>

XCN_CRYPT_STRING_HEXRAW
Value: 0xc
The string is hexadecimal encoded and displayed without punctuation. XCN_CRYPT_STRING_HEXRAW is available only with
Windows Vista.

syntax<br>3a20636572746c69625c6c6461702e6370702832313331293a206c6461706572...<br>

XCN_CRYPT_STRING_BASE64URI
Value: 0xd

XCN_CRYPT_STRING_ENCODEMASK
Value: 0xff

XCN_CRYPT_STRING_CHAIN
Value: 0x100

XCN_CRYPT_STRING_TEXT
Value: 0x200

XCN_CRYPT_STRING_PERCENTESCAPE
Value: 0x8000000

XCN_CRYPT_STRING_HASHDATA
Value: 0x10000000

XCN_CRYPT_STRING_STRICT
Value: 0x20000000
 XCN_CRYPT_STRING_NOCRLF
Value: 0x40000000
Removes carriage return and line feed control characters from the encoded string.

XCN_CRYPT_STRING_NOCR
Value: 0x80000000
Removes the carriage return control character from the encoded string.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Header certenroll.h

See also
CertEnroll Enumerations
CertEnroll Interfaces
 EnrollmentCAProperty enumeration (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The EnrollmentCAProper ty enumeration specifies certification authority property values. It is used by the
Property method on the ICertificationAuthority interface.

Syntax
typedef enum EnrollmentCAProperty {
CAPropCommonName = 1,
CAPropDistinguishedName = 2,
CAPropSanitizedName = 3,
CAPropSanitizedShortName = 4,
CAPropDNSName = 5,
CAPropCertificateTypes = 6,
CAPropCertificate = 7,
CAPropDescription = 8,
CAPropWebServers = 9,
CAPropSiteName = 10,
CAPropSecurity = 11,
CAPropRenewalOnly = 12
} ;

Constants

CAPropCommonName
Value: 1
A VT_BSTR value that contains the common name of the
certification authority (CA) in Active Directory.

CAPropDistinguishedName
Value: 2
A VT_DISPATCH value that contains a pointer to an
IX500DistinguishedName object.

CAPropSanitizedName
Value: 3
A VT_BSTR value that contains the sanitized common name
of the CA in Active Directory. A name is sanitized by
replacing disallowed characters with an exclamation point (!)
followed by four hexadecimal values that represent the
character.
 CAPropSanitizedShortName
Value: 4
A VT_BSTR value that contains the sanitized and shortened
common name of the CA in Active Directory. A name is
sanitized by replacing disallowed characters with an
exclamation point (!) followed by four hexadecimal values
that represent the character. The name is then shortened so
that it does not exceed 51 characters. The characters that
are removed from the sanitized string must be hashed and
the hash converted to a 5-character string.

CAPropDNSName
Value: 5
A VT_BSTR value that contains the DNS name of the CA in
Active Directory.

CAPropCertificateTypes VT_BSTR collection of templates supported by the CA.

Value: 6
A VT_ARRAY

CAPropCertificate VT_UI1 value that contains the signing certificate used by

Value: 7 the CA.
A VT_ARRAY

CAPropDescription
Value: 8
A VT_BSTR value that contains a description comment for
the CA.

CAPropWebServers VT_BSTR collection of certificate enrollment servers

Value: 9 configured for the CA. Each string in the collection contains a
A VT_ARRAY server URL, the authentication method used, an integer that
specifies the priority level, and an integer that specifies
whether the server can perform only certificate renewals.
Each value is delimited by a newline character.

CAPropSiteName
Value: 10
A VT_BSTR value that contains the name of the AD site to
which the CA belongs. This can be used by the enrolling
clients to determine the relative cost of communicating with
the CA versus CAs that belong to other sites. This value is
relevant only for CA objects retrieved by using the GetCAs
method on the IX509EnrollmentPolicyServer interface.

CAPropSecurity
Value: 11
A VT_BSTR value that contains the security descriptor
definition language (SDDL) string representation of the
security descriptor for the CA. This value is relevant only for
CA objects retrieved by using the GetCAs method.

CAPropRenewalOnly
Value: 12
A VT_BOOL value that specifies whether a CA is configured
to perform only certificate renewals. This value is relevant
only for CA objects retrieved by using the GetCAs method.
Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Header certenroll.h

See also
ICertificationAuthority
Property
 EnrollmentDisplayStatus enumeration (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The EnrollmentDisplayStatus enumeration type specifies whether to display enrollment status information in
a user interface. This enumeration is used by the Display property in the IX509EnrollmentStatus interface.

Syntax
typedef enum EnrollmentDisplayStatus {
DisplayNo = 0,
DisplayYes = 1
} ;

Constants

DisplayNo
Value: 0
Status is not displayed.

DisplayYes
Value: 1
Status is displayed.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Header certenroll.h

See also
CertEnroll Enumerations
CertEnroll Interfaces
IX509EnrollmentStatus
 EnrollmentEnrollStatus enumeration (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The EnrollmentEnrollStatus enumeration type specifies the enrollment status of a certificate request. This
enumeration is used by the Status property on the IX509EnrollmentStatus interface.

Syntax
typedef enum EnrollmentEnrollStatus {
Enrolled = 0x1,
EnrollPended = 0x2,
EnrollUIDeferredEnrollmentRequired = 0x4,
EnrollError = 0x10,
EnrollUnknown = 0x20,
EnrollSkipped = 0x40,
EnrollDenied = 0x100
} ;

Constants

Enrolled
Value: 0x1
The enrollment succeeded, and the certificate has been issued.

EnrollPended
Value: 0x2
The request has been submitted and the enrollment is pending, or the request has been issued out of band.

EnrollUIDeferredEnrollmentRequired
Value: 0x4
Enrollment must be deferred.

EnrollError
Value: 0x10
An error occurred.

EnrollUnknown
Value: 0x20
The enrollment status is unknown.

EnrollSkipped
Value: 0x40
The status information has been skipped. This can occur if a certification authority is not valid or has not been selected for
monitoring.

EnrollDenied
Value: 0x100
Enrollment has been denied.
Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Header certenroll.h

See also
CertEnroll Enumerations
CertEnroll Interfaces
EnrollmentSelectionStatus
IX509EnrollmentStatus
 EnrollmentPolicyFlags enumeration (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The EnrollmentPolicyFlags enumeration specifies group policy flags. This enumeration type is not currently
used.

Syntax
typedef enum EnrollmentPolicyFlags {
DisableGroupPolicyList = 0x2,
DisableUserServerList = 0x4
} ;

Constants

DisableGroupPolicyList
Value: 0x2
Ignore policy servers configured in group policy.

DisableUserServerList
Value: 0x4
Ignore user configured policy servers.

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Header certenroll.h
 EnrollmentPolicyServerPropertyFlags enumeration
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The EnrollmentPolicySer verProper tyFlags enumeration specifies the default policy server. It is used by the
Initialize method on the ICertPropertyEnrollmentPolicyServer interface.

Syntax
typedef enum EnrollmentPolicyServerPropertyFlags {
DefaultNone = 0,
DefaultPolicyServer = 0x1
} ;

Constants

DefaultNone
Value: 0
No default policy server URL has been specified.

DefaultPolicyServer
Value: 0x1
The policy server URL returned by GetPolicyServerUrl is the default value when an URL has not been specified.

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Header certenroll.h

See also
ICertPropertyEnrollmentPolicyServer
Initialize
 EnrollmentSelectionStatus enumeration
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The EnrollmentSelectionStatus enumeration type specifies whether the enrollment status of an object will be
monitored during the enrollment process. Cryptographic providers, individual enrollment objects in a collection,
and certification authorities are often monitored and their status displayed in a user interface. A value of this
enumeration can be specified or retrieved by using the Selected property on the IX509EnrollmentStatus
interface. An IX509EnrollmentStatus object can be retrieved from the IX509Enrollment and ICspStatus
objects.

Syntax
typedef enum EnrollmentSelectionStatus {
SelectedNo = 0,
SelectedYes = 1
} ;

Constants

SelectedNo
Value: 0
The enrollment status is not monitored.

SelectedYes
Value: 1
The enrollment status is monitored.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Header certenroll.h

See also
CertEnroll Enumerations
CertEnroll Interfaces
IX509EnrollmentStatus
 EnrollmentTemplateProperty enumeration
(certenroll.h)
7/2/2022 • 4 minutes to read • Edit Online

The EnrollmentTemplateProper ty enumeration contains property values for a given template.

Syntax
typedef enum EnrollmentTemplateProperty {
TemplatePropCommonName = 1,
TemplatePropFriendlyName = 2,
TemplatePropEKUs = 3,
TemplatePropCryptoProviders = 4,
TemplatePropMajorRevision = 5,
TemplatePropDescription = 6,
TemplatePropKeySpec = 7,
TemplatePropSchemaVersion = 8,
TemplatePropMinorRevision = 9,
TemplatePropRASignatureCount = 10,
TemplatePropMinimumKeySize = 11,
TemplatePropOID = 12,
TemplatePropSupersede = 13,
TemplatePropRACertificatePolicies = 14,
TemplatePropRAEKUs = 15,
TemplatePropCertificatePolicies = 16,
TemplatePropV1ApplicationPolicy = 17,
TemplatePropAsymmetricAlgorithm = 18,
TemplatePropKeySecurityDescriptor = 19,
TemplatePropSymmetricAlgorithm = 20,
TemplatePropSymmetricKeyLength = 21,
TemplatePropHashAlgorithm = 22,
TemplatePropKeyUsage = 23,
TemplatePropEnrollmentFlags = 24,
TemplatePropSubjectNameFlags = 25,
TemplatePropPrivateKeyFlags = 26,
TemplatePropGeneralFlags = 27,
TemplatePropSecurityDescriptor = 28,
TemplatePropExtensions = 29,
TemplatePropValidityPeriod = 30,
TemplatePropRenewalPeriod = 31
} ;

Constants

TemplatePropCommonName
Value: 1
A VT_BSTR value that contains the common name of the
template in Active Directory.

TemplatePropFriendlyName
Value: 2
A VT_BSTR value that contains the template display name.
 TemplatePropEKUs
Value: 3
A VT_DISPATCH pointer to an IObjectIds interface that
contains a collection of extended key usage object identifiers.
This value applies to version 2 and later templates.

TemplatePropCryptoProviders VT_BSTR collection of cryptographic service providers

Value: 4 (version 2) and key storage providers (version 3) that the
A VT_ARRAY client can use when generating requests based on this
template.

TemplatePropMajorRevision
Value: 5
A VT_UI4 (VT_I4 beginning with Windows 8.1) value that
specifies the major version number for the template.

TemplatePropDescription
Value: 6
Not used.

TemplatePropKeySpec
Value: 7
A VT_UI4 (VT_I4 beginning with Windows 8.1) value that
contains AT_SIGNATURE or AT_KEYEXCHANGE to specify
the Key_Spec value for legacy cryptographic service
providers.

TemplatePropSchemaVersion
Value: 8
A VT_UI4 (VT_I4 beginning with Windows 8.1) value that
specifies the template version. Currently, this can be 1, 2, or
3.

TemplatePropMinorRevision
Value: 9
A VT_UI4 (VT_I4 beginning with Windows 8.1) value that
specifies the minor version number of a version 2 and later
template.

TemplatePropRASignatureCount
Value: 10
A VT_UI4 (VT_I4 beginning with Windows 8.1) value that
specifies the number of recovery agent signatures that are
required when generating a certificate request base on this
template.

TemplatePropMinimumKeySize
Value: 11
A VT_UI4 (VT_I4 beginning with Windows 8.1) value that
specifies the minimum size of the public key used by the
enrolling client.
 TemplatePropOID
Value: 12
A VT_DISPATCH pointer to an IObjectId interface that
contains an object identifier for this template. This value
applies to version 2 and later templates.

TemplatePropSupersede VT_BSTR collection that contains the common names of all

Value: 13 version 2 and later templates that have been superseded.
A VT_ARRAY

TemplatePropRACertificatePolicies
Value: 14
A VT_DISPATCH pointer to an IObjectIds interface that
contains a collection of certificate policy object identifiers for
the registration authority certificates. This value applies to
version 2 and later templates.

TemplatePropRAEKUs
Value: 15
A VT_DISPATCH pointer to an IObjectIds interface that
contains a collection of application policy object identifiers
for the registration authority certificates. This value applies
to version 2 and later templates.

TemplatePropCertificatePolicies
Value: 16
A VT_DISPATCH pointer to an IObjectIds interface that
contains a collection of policy object identifiers to be added
to the certificate policy extension.

TemplatePropV1ApplicationPolicy
Value: 17
A VT_DISPATCH pointer to an IObjectIds interface that
contains a collection of policy object identifiers to be added
to the certificate application policy extension.

TemplatePropAsymmetricAlgorithm
Value: 18
A VT_BSTR value that specifies the name of a public key
algorithm the enrolling client must use when generating a
certificate request based on this template. This value applies
to version 3 and later templates.

TemplatePropKeySecurityDescriptor
Value: 19
A VT_BSTR value that specifies the asymmetric key security
descriptor for version 3 and later templates.

TemplatePropSymmetricAlgorithm
Value: 20
A VT_BSTR value that specifies the name of the symmetric
algorithm that a client must use for key exchange when
using this template. This value applies to version 3 and later
templates.
 TemplatePropSymmetricKeyLength
Value: 21
A VT_UI4 (VT_I4 beginning with Windows 8.1) value that
specifies the length, in bits, of the symmetric key. This value
applies to version 3 and later templates.

TemplatePropHashAlgorithm
Value: 22
A VT_BSTR value that specifies the name of the hashing
algorithm that an enrolling client must use. This value
applies to version 3 and later templates.

TemplatePropKeyUsage
Value: 23

TemplatePropEnrollmentFlags
Value: 24
A VT_I4 value that contains a bitwise OR of
X509CertificateTemplateEnrollmentFlag values.

TemplatePropSubjectNameFlags
Value: 25
A VT_UI4 (VT_I4 beginning with Windows 8.1) value that
contains a bitwise OR of
X509CertificateTemplateSubjectNameFlag values.

TemplatePropPrivateKeyFlags
Value: 26
A VT_UI4 (VT_I4 beginning with Windows 8.1) value that
contains a bitwise OR of
X509CertificateTemplatePrivateKeyFlag values.

TemplatePropGeneralFlags
Value: 27
A VT_UI4 (VT_I4 beginning with Windows 8.1) value that
contains a bitwise OR of
X509CertificateTemplateGeneralFlag values.

TemplatePropSecurityDescriptor
Value: 28
A VT_BSTR value that specifies the security descriptor.

TemplatePropExtensions
Value: 29
A VT_DISPATCH pointer to an IX509Extensions interface
that contains the certificate extensions to be added to the
certificate request when generating requests based on this
template.

TemplatePropValidityPeriod
Value: 30
A VT_UI8 FILETIME value that contains the maximum
validity period, in seconds, of the certificate.
 TemplatePropRenewalPeriod
Value: 31
A VT_UI8 FILETIME value that specifies the amount of
time before expiration that automatic enrollment has to
attempt certificate renewal.

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Header certenroll.h
 IAlternativeName interface (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

A collection of IAlternativeName interfaces is used by an IX509ExtensionAlternativeNames object to represent

an instance of an AlternativeNames extension. The collection is represented by the IAlternativeNames
interface. The following syntax shows the Abstract Syntax Notation One (ASN.1) structure of the extension.

----------------------------------------------------------------------
-- AlternativeNames
-- XCN_OID_SUBJECT_ALT_NAME2 (2.5.29.17)
----------------------------------------------------------------------

AltNames ::= SEQUENCE --#public-- OF GeneralName

GeneralNames ::= AltNames

GeneralName ::= CHOICE

{
otherName [0] IMPLICIT OtherName,
rfc822Name [1] IMPLICIT IA5STRING,
dNSName [2] IMPLICIT IA5STRING,
x400Address [3] IMPLICIT SeqOfAny, --Not supported
directoryName [4] EXPLICIT ANY,
ediPartyName [5] IMPLICIT SeqOfAny,
uniformResourceLocator [6] IMPLICIT IA5STRING,
iPAddress [7] IMPLICIT OCTETSTRING,
registeredID [8] IMPLICIT EncodedObjectID --Not supported
}

OtherName ::= SEQUENCE

{
type EncodedObjectID,
value [0] EXPLICIT NOCOPYANY
}

You can initialize an IAlternativeName object from an AlternativeNameType enumeration. The following types
are available, but they are supported by different initialization methods as indicated.

VA L UE DESC RIP T IO N IN IT IA L IZ AT IO N M ET H O D

XCN_CERT_ALT_NAME_OTHER_NAME The name consists of an object InitializeFromOtherName

identifier (OID) and a byte array.

XCN_CERT_ALT_NAME_RFC822_NAME The name is an email address. InitializeFromString

XCN_CERT_ALT_NAME_DNS_NAME The name is a Domain Name System InitializeFromString

(DNS) name.

XCN_CERT_ALT_NAME_DIRECTORY_N The name is an X.500 directory name. InitializeFromRawData

AME

XCN_CERT_ALT_NAME_URL The name is a URL. InitializeFromString

 XCN_CERT_ALT_NAME_IP_ADDRESS The name is an Internet Protocol (IP) InitializeFromRawData
address.

XCN_CERT_ALT_NAME_REGISTERED_ID The name is a registered OID. InitializeFromString

XCN_CERT_ALT_NAME_GUID The name is a GUID. InitializeFromRawData

XCN_CERT_ALT_NAME_USER_PRINCIP The name is a user principal name InitializeFromString

LE_NAME (UPN).

Inheritance
The IAlternativeName interface inherits from the IDispatch interface. IAlternativeName also has these types
of members:

Methods
The IAlternativeName interface has these methods.

IAlternativeName::get_ObjectId

Retrieves the object identifier (OID), if any, associated with the name.

IAlternativeName::get_RawData

Retrieves the Distinguished Encoding Rules (DER) encoded byte array that contains the name.

IAlternativeName::get_StrValue

Retrieves a string that contains an email address, a Domain Name System (DNS) name, a URL, a registered object identifier
(OID), or a user principal name (UPN).

IAlternativeName::get_Type

Retrieves the alternative name type.

IAlternativeName::InitializeFromOtherName

Initializes the object from an object identifier (OID) and the associated raw data (byte array).

IAlternativeName::InitializeFromRawData

Initializes the object from a Digital Signature Algorithm (DSA) GUID, an X.500 directory name, or an Internet Protocol (IP)
address contained in a Distinguished Encoding Rules (DER) encoded byte array.

IAlternativeName::InitializeFromString

Initializes the object from a string that contains an email address, a Domain Name System (DNS) name, a URL, a registered
object identifier (OID), or a user principal name (UPN).

Requirements
 Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

See also
CertEnroll Interfaces
IAlternativeNames
IDispatch
IX509ExtensionAlternativeNames
 IAlternativeName::get_ObjectId method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The ObjectId property retrieves the object identifier (OID), if any, associated with the name.
This property is read-only.

Syntax
HRESULT get_ObjectId(
IObjectId **ppValue
);

Parameters
ppValue

Return value
None

Remarks
You can retrieve a value for this property if you initialized the IAlternativeName object in any of the following
ways:
Call InitializeFromOtherName and supply an OID.
Call InitializeFromRawData and specify the XCN_CERT_ALT_NAME_GUID type.
Call InitializeFromString and specify the XCN_CERT_ALT_NAME_USER_PRINCIPLE_NAME type.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IAlternativeName
 IAlternativeName::get_RawData method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The RawData property retrieves the Distinguished Encoding Rules (DER) encoded byte array that contains the
name. The byte array is contained in a Unicode encoded string.
This property is read-only.

Syntax
HRESULT get_RawData(
EncodingType Encoding,
BSTR *pValue
);

Parameters
Encoding

pValue

Return value
None

Remarks
You can retrieve a value for this property if you initialized the IAlternativeName object in any of the following
ways:
Call InitializeFromOtherName and supply an object identifier (OID).
Call InitializeFromRawData and specify the XCN_CERT_ALT_NAME_GUID,
XCN_CERT_ALT_NAME_DIRECTORY_NAME, or XCN_CERT_ALT_NAME_IP_ADDRESS types.
Call InitializeFromString and specify the XCN_CERT_ALT_NAME_USER_PRINCIPLE_NAME type.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h
 DLL CertEnroll.dll

See also
IAlternativeName
 IAlternativeName::get_StrValue method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The StrValue property retrieves a string that contains an email address, a Domain Name System (DNS) name, a
URL, a registered object identifier (OID), or a user principal name (UPN).
This property is read-only.

Syntax
HRESULT get_StrValue(
BSTR *pValue
);

Parameters
pValue

Return value
None

Remarks
You can call this property to retrieve a string if you initialized the IAlternativeName object by calling the
InitializeFromString method and specifying one of the following AlternativeNameType values.

VA L UE DESC RIP T IO N

XCN_CERT_ALT_NAME_RFC822_NAME The name is an email address.

XCN_CERT_ALT_NAME_DNS_NAME The name is a DNS name.

XCN_CERT_ALT_NAME_URL The name is a URL.

XCN_CERT_ALT_NAME_REGISTERED_ID The name is a registered OID.

XCN_CERT_ALT_NAME_USER_PRINCIPLE_NAME The name is a UPN.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]
 Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IAlternativeName
 IAlternativeName::get_Type method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Type property retrieves the alternative name type.

This property is read-only.

Syntax
HRESULT get_Type(
AlternativeNameType *pValue
);

Parameters
pValue

Return value
None

Remarks
The following values from the AlternativeNameType enumeration can be returned. The
XCN_CERT_ALT_NAME_UNKNOWN value is never returned.

VA L UE DESC RIP T IO N

XCN_CERT_ALT_NAME_OTHER_NAME The name consists of an object identifier (OID) and a byte

array.

XCN_CERT_ALT_NAME_RFC822_NAME The name is an email address.

XCN_CERT_ALT_NAME_DNS_NAME The name is a DNS name.

XCN_CERT_ALT_NAME_DIRECTORY_NAME The name is an X.500 directory name.

XCN_CERT_ALT_NAME_URL The name is a URL.

XCN_CERT_ALT_NAME_IP_ADDRESS The name is an IP address.

XCN_CERT_ALT_NAME_REGISTERED_ID The name is a registered OID.

XCN_CERT_ALT_NAME_GUID The name is a GUID.

XCN_CERT_ALT_NAME_USER_PRINCIPLE_NAME The name is a user principal name (UPN).

Requirements
 Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IAlternativeName
 IAlternativeName::InitializeFromOtherName
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The InitializeFromOtherName method initializes the object from an object identifier (OID) and the associated
raw data (byte array). This method is provided to support the otherName field in the Abstract Syntax Notation
One (ASN.1) AlternativeNames extension declaration.

----------------------------------------------------------------------
-- AlternativeNames
-- XCN_OID_SUBJECT_ALT_NAME2 (2.5.29.17)
----------------------------------------------------------------------

AltNames ::= SEQUENCE --#public-- OF GeneralName

GeneralNames ::= AltNames

GeneralName ::= CHOICE

{
otherName [0] IMPLICIT OtherName,
rfc822Name [1] IMPLICIT IA5STRING,
dNSName [2] IMPLICIT IA5STRING,
x400Address [3] IMPLICIT SeqOfAny, -- Not supported
directoryName [4] EXPLICIT ANY,
ediPartyName [5] IMPLICIT SeqOfAny,
uniformResourceLocator [6] IMPLICIT IA5STRING,
iPAddress [7] IMPLICIT OCTETSTRING,
registeredID [8] IMPLICIT EncodedObjectID -- Not supported
}

OtherName ::= SEQUENCE

{
type EncodedObjectID,
value [0] EXPLICIT NOCOPYANY
}

Syntax
HRESULT InitializeFromOtherName(
[in] IObjectId *pObjectId,
[in] EncodingType Encoding,
[in] BSTR strRawData,
[in] VARIANT_BOOL ToBeWrapped
);

Parameters
[in] pObjectId

Pointer to an IObjectId interface that represents an OID.

[in] Encoding

An EncodingType enumeration value that identifies the type of Unicode encoding applied to the strRawData
parameter.
[in] strRawData

A BSTR variable that contains the name associated with the OID.
[in] ToBeWrapped

A VARIANT_BOOL variable that identifies whether the input string contained in the strRawData parameter is
encoded and saved as an octet string (byte array).

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. Possible values include, but are not
limited to, those in the following table. For a list of common error codes, see Common HRESULT Values.

RET URN C O DE/ VA L UE DESC RIP T IO N

The object is already initialized.

HRESULT_FROM_WIN32(ERROR_ALREADY_INITIALIZE
D)

Remarks
You can use this function to initialize an IAlternativeName object from an OID and an associated string value.
The string is Unicode encoded. If you specify true for the ToBeWrapped parameter, the string is encoded by
using Distinguished Encoding Rules (DER). You can retrieve the OID by calling the ObjectId property. You can
retrieve the encoded string or, if ToBeWrapped is true, the DER-encoded byte array by calling the RawData
property to retrieve the encoded byte array.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IAlternativeName
 IAlternativeName::InitializeFromRawData method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The InitializeFromRawData method initializes the object from a Digital Signature Algorithm (DSA) GUID, an
X.500 directory name, or an Internet Protocol (IP) address contained in a Distinguished Encoding Rules (DER)
encoded byte array.

Syntax
HRESULT InitializeFromRawData(
[in] AlternativeNameType Type,
[in] EncodingType Encoding,
[in] BSTR strRawData
);

Parameters
[in] Type

An AlternativeNameType enumeration value that identifies the type of name represented by the input string.
This must be one of the following values.

VA L UE M EA N IN G

The name is an X.500 directory name.

XCN_CERT_ALT_NAME_DIRECTORY_NAME

The name is an IP address.

XCN_CERT_ALT_NAME_IP_ADDRESS

The name is a GUID.

XCN_CERT_ALT_NAME_GUID

[in] Encoding

An EncodingType enumeration value that identifies the type of Unicode encoding applied to the strRawData
parameter.
[in] strRawData

A BSTR variable that contains the DER-encoded data.

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. Possible values include, but are not
limited to, those in the following table. For a list of common error codes, see Common HRESULT Values.
 RET URN C O DE DESC RIP T IO N

The object is already initialized.

HRESULT_FROM_WIN32(ERROR_ALREADY_INITIALIZE
D)

Remarks
The raw data is a byte array that has been encoded by using Distinguished Encoding Rules (DER). You must
specify the byte array as a Unicode encoded string.
If you use this method to specify a DSA GUID (XCN_CERT_ALT_NAME_GUID), the GUID is associated with the
XCN_OID_NTDS_REPLICATION (1.3.6.1.4.1.311.25.1) object identifier (OID) and encoded as an octet string (byte
array). You can retrieve the OID by calling the ObjectId property. You can call the RawData property to retrieve
the encoded byte array.
If you use this method to specify any of the following name types, the method returns E_INVALIDARG .

VA L UE DESC RIP T IO N

XCN_CERT_ALT_NAME_UNKNOWN The name type is not identified.

XCN_CERT_ALT_NAME_RFC822_NAME The name is an email address.

XCN_CERT_ALT_NAME_DNS_NAME The name is a DNS name.

XCN_CERT_ALT_NAME_URL The name is a URL.

XCN_CERT_ALT_NAME_REGISTERED_ID The name is a registered OID.

XCN_CERT_ALT_NAME_USER_PRINCIPLE_NAME The name is a user principal name (UPN).

XCN_CERT_ALT_NAME_OTHER_NAME The name consists of an OID and a byte array.

You can use the InitializeFromOtherName method to specify an OID and a corresponding name string, and you
can use the InitializeFromString method to specify an email address, a DNS name, a URL, a registered OID, or a
user principal name (UPN).

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll
See also
IAlternativeName
 IAlternativeName::InitializeFromString method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The InitializeFromString method initializes the object from a string that contains an email address, a Domain
Name System (DNS) name, a URL, a registered object identifier (OID), or a user principal name (UPN).

Syntax
HRESULT InitializeFromString(
[in] AlternativeNameType Type,
[in] BSTR strValue
);

Parameters
[in] Type

An AlternativeNameType enumeration value that identifies the type of name represented by the input string
contained in the strValue parameter. This must be one of the following values.

VA L UE M EA N IN G

The name is an email address.

XCN_CERT_ALT_NAME_RFC822_NAME

The name is a DNS name.

XCN_CERT_ALT_NAME_DNS_NAME

The name is a URL.

XCN_CERT_ALT_NAME_URL

The name is a registered OID.

XCN_CERT_ALT_NAME_REGISTERED_ID

The name is a UPN.

XCN_CERT_ALT_NAME_USER_PRINCIPLE_NAME

[in] strValue

A BSTR variable that contains the name.

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.
Remarks
If you use this method to specify a UPN, the UPN is associated with the XCN_OID_NT_PRINCIPAL_NAME
(1.3.6.1.4.1.311.20.2.3) OID and is Distinguished Encoding Rules (DER) encoded. You can call the RawData
property to retrieve the encoded byte array. You can retrieve the OID by calling the ObjectId property.
If you use this method to specify any of the following name types, the method returns E_INVALIDARG .

VA L UE DESC RIP T IO N

XCN_CERT_ALT_NAME_UNKNOWN The name type is not identified.

XCN_CERT_ALT_NAME_OTHER_NAME The name consists of an OID and a byte array.

XCN_CERT_ALT_NAME_DIRECTORY_NAME The name is an X.500 directory name.

XCN_CERT_ALT_NAME_IP_ADDRESS The name is an IP address.

XCN_CERT_ALT_NAME_GUID The name is a GUID.

You can use the InitializeFromOtherName method to specify an OID and a corresponding name string, and you
can use the InitializeFromRawData method to specify a GUID, IP address, or X.500 directory name.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IAlternativeName
IAlternativeNames
IX509ExtensionAlternativeNames
 IAlternativeNames interface (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The IAlternativeNames interface contains methods and properties that enable you to manage a collection of
IAlternativeName objects.

Inheritance
The IAlternativeNames interface inherits from the IDispatch interface. IAlternativeNames also has these
types of members:

Methods
The IAlternativeNames interface has these methods.

IAlternativeNames::Add

Adds an object to the collection.

IAlternativeNames::Clear

Removes all objects from the collection.

IAlternativeNames::get__NewEnum

Retrieves the enumerator for the collection.

IAlternativeNames::get_Count

Retrieves the number of objects in the collection.

IAlternativeNames::get_ItemByIndex

Retrieves an object from the collection by index number.

IAlternativeNames::Remove

Removes an object from the collection by index number.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

 Header certenroll.h

See also
CertEnroll Interfaces
IAlternativeName
IDispatch
 IAlternativeNames::Add method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Add method adds an object to the collection.

Syntax
HRESULT Add(
[in] IAlternativeName *pVal
);

Parameters
[in] pVal

Pointer to an IAlternativeName interface to add.

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IAlternativeName
IAlternativeNames
 IAlternativeNames::Clear method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Clear method removes all objects from the collection.

Syntax
HRESULT Clear();

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IAlternativeName
IAlternativeNames
 IAlternativeNames::get__NewEnum method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The _NewEnum property retrieves the enumerator for the collection.

This property is read-only.

Syntax
HRESULT get__NewEnum(
LPUNKNOWN *pVal
);

Parameters
pVal

Return value
None

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IAlternativeName
IAlternativeNames
 IAlternativeNames::get_Count method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Count property retrieves the number of objects in the collection.

This property is read-only.

Syntax
HRESULT get_Count(
long *pVal
);

Parameters
pVal

Return value
None

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IAlternativeName
IAlternativeNames
 IAlternativeNames::Remove method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Remove method removes an object from the collection by index number.

Syntax
HRESULT Remove(
[in] LONG Index
);

Parameters
[in] Index

A LONG variable that contains the index of the object to remove.

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IAlternativeName
IAlternativeNames
 IBinaryConverter interface (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The IBinar yConver ter interface contains general methods that enable you to create a Unicode-encoded string
from a byte array, create a byte array from a Unicode-encoded string, and modify the type of Unicode encoding
applied to a string. You can use this interface to represent a certificate BLOB as a printable string or to decode
the string back into a certificate BLOB.

Inheritance
The IBinar yConver ter interface inherits from the IDispatch interface. IBinar yConver ter also has these types
of members:

Methods
The IBinar yConver ter interface has these methods.

IBinaryConverter::StringToString

Modifies the type of Unicode encoding applied to a string.

IBinaryConverter::StringToVariantByteArray

Creates a byte array from a Unicode encoded string.

IBinaryConverter::VariantByteArrayToString

Creates a Unicode encoded string from a byte array.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

See also
CertEnroll Interfaces
IDispatch
 IBinaryConverter::StringToString method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The StringToString method modifies the type of Unicode encoding applied to a string.

Syntax
HRESULT StringToString(
[in] BSTR strEncodedIn,
[in] EncodingType EncodingIn,
[in] EncodingType Encoding,
[out] BSTR *pstrEncoded
);

Parameters
[in] strEncodedIn

A BSTR variable that contains the string to modify.

[in] EncodingIn

An EncodingType enumeration value that specifies the Unicode encoding applied to the input string.
[in] Encoding

An EncodingType enumeration value that specifies the type of Unicode encoding to apply to the output string.
The default value is XCN_CRYPT_STRING_BASE64 .
[out] pstrEncoded

Pointer to a BSTR variable that contains the encoded output string.

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

 Header certenroll.h

DLL CertEnroll.dll

See also
IBinaryConverter
 IBinaryConverter::StringToVariantByteArray method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The StringToVariantByteArray method creates a byte array from a Unicode encoded string. Use this method
to create a certificate BLOB from an encoded string that contains a certificate.

Syntax
HRESULT StringToVariantByteArray(
[in] BSTR strEncoded,
[in] EncodingType Encoding,
[out] VARIANT *pvarByteArray
);

Parameters
[in] strEncoded

A BSTR variable that contains the Unicode encoded string.

[in] Encoding

An EncodingType enumeration value that specifies the Unicode encoding applied to the input string. The default
value is XCN_CRYPT_STRING_BASE64 .
[out] pvarByteArray

Pointer to a VARIANT array of bytes. The VARTYPE enumeration value equals VT_ARRAY | VT_UI1 .

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll
See also
IBinaryConverter
 IBinaryConverter::VariantByteArrayToString method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The VariantByteArrayToString method creates a Unicode encoded string from a byte array. You can use this
method to create a printable string from a certificate BLOB.

Syntax
HRESULT VariantByteArrayToString(
[in] VARIANT *pvarByteArray,
[in] EncodingType Encoding,
[out] BSTR *pstrEncoded
);

Parameters
[in] pvarByteArray

Pointer to a VARIANT array of bytes to be encoded. Each byte in the array must be an unsigned integer. That is,
the VARTYPE enumeration value must equal VT_ARRAY | VT_UI1 .
[in] Encoding

An EncodingType enumeration value that specifies the Unicode encoding applied to the input string. The default
value is XCN_CRYPT_STRING_BASE64 .
[out] pstrEncoded

Pointer to a BSTR variable that contains the Unicode-encoded certificate.

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h
 DLL CertEnroll.dll

See also
IBinaryConverter
 ICertificateAttestationChallenge interface
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

Allows applications to decrypt a key attestation challenge received from a server.

Inheritance
The ICer tificateAttestationChallenge interface inherits from the IDispatch interface.
ICer tificateAttestationChallenge also has these types of members:

Methods
The ICer tificateAttestationChallenge interface has these methods.

ICertificateAttestationChallenge::DecryptChallenge

Decrypts the challenge from the Certificate Management over CMS (CMC) response and creates a re-encrypted response to
send to the CA.

ICertificateAttestationChallenge::get_RequestID

Gets the request ID from the Certificate Management over CMS (CMC) response.

ICertificateAttestationChallenge::Initialize

Initialize using the full Certificate Management over CMS (CMC) response returned from the CA.

Remarks
If the challenge is successfully decrypted, the decrypted secret needs to be sent back to the server so that an
attested end entity certificate can be issued.

Requirements

Target Platform Windows

Header certenroll.h
 ICertificateAttestationChallenge::DecryptChallenge
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

Decrypts the challenge from the Certificate Management over CMS (CMC) response and creates a re-encrypted
response to send to the CA.

Syntax
HRESULT DecryptChallenge(
[in] EncodingType Encoding,
[out, retval] BSTR *pstrEnvelopedPkcs7ReencryptedToCA
);

Parameters
[in] Encoding

An EncodingType enumeration value that specifies the type of Unicode-encoding applied to the attestation
challenge. The default value is XCN_CRYPT_STRING_BASE64.
[out, retval] pstrEnvelopedPkcs7ReencryptedToCA

The decrypted challenge from the CMC response re-encrypted for the CA.

Return value
If this method succeeds, it returns S_OK . Otherwise, it returns an HRESULT error code.

Requirements

Target Platform Windows

Header certenroll.h

DLL Certenroll.dll

See also
ICertificateAttestationChallenge
 ICertificateAttestationChallenge::get_RequestID
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

Gets the request ID from the Certificate Management over CMS (CMC) response.
This property is read-only.

Syntax
HRESULT get_RequestID(
BSTR *pstrRequestID
);

Parameters
pstrRequestID

Return value
None

Requirements

Target Platform Windows

Header certenroll.h

DLL Certenroll.dll

See also
ICertificateAttestationChallenge
 ICertificateAttestationChallenge::Initialize method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

Initialize using the full Certificate Management over CMS (CMC) response returned from the CA.

Syntax
HRESULT Initialize(
[in] EncodingType Encoding,
[in] BSTR strPendingFullCmcResponseWithChallenge
);

Parameters
[in] Encoding

An EncodingType enumeration value that specifies the type of Unicode-encoding applied to the response. The
default value is XCN_CRYPT_STRING_BASE64.
[in] strPendingFullCmcResponseWithChallenge

The pending CMC response from the CA.

Return value
If this method succeeds, it returns S_OK . Otherwise, it returns an HRESULT error code.

Remarks
The CA should have returned a pending CMC response. The content of the CMC response should contain a
challenge. There must be only one CMC response and it must contain pending information.

Requirements

Target Platform Windows

Header certenroll.h

DLL Certenroll.dll

See also
ICertificateAttestationChallenge
 ICertificatePolicies interface (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The ICer tificatePolicies interface contains methods and properties that enable you to manage a collection of
ICertificatePolicy objects.

Inheritance
The ICer tificatePolicies interface inherits from the IDispatch interface. ICer tificatePolicies also has these
types of members:

Methods
The ICer tificatePolicies interface has these methods.

ICertificatePolicies::Add

Adds an object to the collection.

ICertificatePolicies::Clear

Removes all objects from the collection.

ICertificatePolicies::get__NewEnum

Retrieves the enumerator for the collection.

ICertificatePolicies::get_Count

Retrieves the number of objects in the collection.

ICertificatePolicies::get_ItemByIndex

Retrieves an object from the collection by index number.

ICertificatePolicies::Remove

Removes an object from the collection by index number.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

 Header certenroll.h

See also
CertEnroll Interfaces
ICertificatePolicy
IDispatch
 ICertificatePolicies::Add method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Add method adds an object to the collection.

Syntax
HRESULT Add(
[in] ICertificatePolicy *pVal
);

Parameters
[in] pVal

Pointer to the ICertificatePolicy interface to add.

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
ICertificatePolicies
ICertificatePolicy
 ICertificatePolicies::Clear method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Clear method removes all objects from the collection.

Syntax
HRESULT Clear();

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
ICertificatePolicies
ICertificatePolicy
 ICertificatePolicies::get__NewEnum method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The _NewEnum property retrieves the enumerator for the collection.

This property is read-only.

Syntax
HRESULT get__NewEnum(
LPUNKNOWN *pVal
);

Parameters
pVal

Return value
None

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
ICertificatePolicies
ICertificatePolicy
 ICertificatePolicies::get_Count method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Count property retrieves the number of objects in the collection.

This property is read-only.

Syntax
HRESULT get_Count(
long *pVal
);

Parameters
pVal

Return value
None

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
ICertificatePolicies
ICertificatePolicy
 ICertificatePolicies::Remove method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Remove method removes an object from the collection by index number.

Syntax
HRESULT Remove(
[in] LONG Index
);

Parameters
[in] Index

A LONG variable that contains the index of the object to remove.

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
ICertificatePolicies
ICertificatePolicy
 ICertificatePolicy interface (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The ICer tificatePolicy interface can be used to specify a certificate policy that identifies a purpose for which
the certificate can be used. The policies are collected into an ICertificatePolicies object that you can use to
initialize an IX509ExtensionCertificatePolicies or IX509ExtensionMSApplicationPolicies object.
The following syntax shows the Abstract Syntax Notation One (ASN.1) structure used by both extension objects.
The extension values are encoded by using Distinguished Encoding Rules (DER) and included in the certificate
request. A certificate policies collection consists of a sequence of object identifiers (OIDs) and optional sequence
of policy qualifiers for each policy OID.

Note Policy qualifiers, defined by the IPolicyQualifier interface, are used by a Cer tificatePolicies extension but not by an
MSApplicationPolicies extension.

----------------------------------------------------------------------
-- CertificatePolicies
-- XCN_OID_CERT_POLICIES (2.5.29.32)
----------------------------------------------------------------------

CertificatePolicies ::= SEQUENCE OF PolicyInformation

PolicyInformation ::= SEQUENCE

{
policyIdentifier EncodedObjectID,
policyQualifiers PolicyQualifiers OPTIONAL
}

PolicyQualifiers ::= SEQUENCE OF PolicyQualifierInfo

PolicyQualifierInfo ::= SEQUENCE

{
policyQualifierId EncodedObjectID,
qualifier NOCOPYANY OPTIONAL
}

Issuance policies, defined by an IX509ExtensionCertificatePolicies object, identify the extent to which the identity
presented in the certificate is trusted. The following policies are predefined. The x.y.z portion of each OID
represents a randomly generated numeric sequence that is unique for each forest. You can also create custom
OIDs to represent custom issuance policies.

P O L IC Y DESC RIP T IO N

All Issuance(2.5.29.32.0) Contains all other policies. This is typically assigned only to
certification authority certificates. The OID is
XCN_OID_ANY_CERT_POLICY.

Low Assurance(1.3.6.1.4.1.311.21.8.x.y.z.1.400) Indicates that a certificate is issued with no additional

security requirements.
 Medium Assurance (1.3.6.1.4.1.311.21.8.x.y.z.1.401) Indicates that a certificate issuance has additional security
requirements. For example, the policy might require that the
certificate subject physically appear before the certification
authority.

High Assurance (1.3.6.1.4.1.311.21.8.x.y.z.1.402)
Indicates that the certificate is issued with the highest
security. For example, the issuance of a key recovery agent
certificate can require additional background checks and a
digital signature from a designated approver because a
person holding this certificate can recover private key
material from the CA.

Application policies, defined by an IX509ExtensionMSApplicationPolicies object, enable an application to filter

certificates by comparing the policy OIDs it will accept to the policy OIDs contained in the certificate. The
MSApplicationPolicies extension is very similar to the EnhancedKeyUsage extension but is often used for
policy mapping.

Inheritance
The ICer tificatePolicy interface inherits from the IDispatch interface. ICer tificatePolicy also has these types
of members:

Methods
The ICer tificatePolicy interface has these methods.

ICertificatePolicy::get_ObjectId

Retrieves an object identifier (OID) for the policy object.

ICertificatePolicy::get_PolicyQualifiers

Retrieves a collection of optional policy qualifiers that can be applied to a certificate policy.

ICertificatePolicy::Initialize

Initializes the object from an object identifier (OID).

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h
See also
CertEnroll Interfaces
ICertificatePolicies
IDispatch
IX509ExtensionCertificatePolicies
 ICertificatePolicy::get_ObjectId method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The ObjectId property retrieves an object identifier (OID) for the policy object.
This property is read-only.

Syntax
HRESULT get_ObjectId(
IObjectId **ppValue
);

Parameters
ppValue

Return value
None

Remarks
The IObjectId object stores information about the OID internally in a CryptoAPI CRYPT_OID_INFO structure. You
cannot use this structure directly from the Certificate Enrollment API, but you can use the IObjectId interface to
retrieve the display name or dotted decimal name of the OID, or the CERTENROLL_OBJECTID value.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
ICertificatePolicies
ICertificatePolicy
 ICertificatePolicy::get_PolicyQualifiers method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The PolicyQualifiers property retrieves a collection of optional policy qualifiers that can be applied to a
certificate policy.
This property is read-only.

Syntax
HRESULT get_PolicyQualifiers(
IPolicyQualifiers **ppValue
);

Parameters
ppValue

Return value
None

Remarks
An empty IPolicyQualifiers object is created when you call the Initialize method. You can call the
PolicyQualifiers property to retrieve this object and specify qualifying information for the policy. Policy
qualifiers only apply if you are creating a Cer tificatePolicies extension. For more information, see the
IX509ExtensionCertificatePolicies.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
ICertificatePolicies
ICertificatePolicy
 ICertificatePolicy::Initialize method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Initialize method initializes the object from an object identifier (OID).

Syntax
HRESULT Initialize(
[in] IObjectId *pValue
);

Parameters
[in] pValue

Pointer to an IObjectId interface that represents the OID.

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. Possible values include, but are not
limited to, those in the following table. For a list of common error codes, see Common HRESULT Values.

RET URN C O DE/ VA L UE DESC RIP T IO N

The pointer to the IObjectId interface is NULL .

CERTSRV_E_PROPERTY_EMPTY

The object is already initialized.

HRESULT_FROM_WIN32(ERROR_ALREADY_INITIALIZE
D)

Remarks
You must use an initialized IObjectId object when calling this method. All of the IObjectId initialization methods
search the registry and static memory on the local computer and Active Directory on the domain server for the
first OID that matches the specified initialization parameters. You can retrieve the OID by calling the ObjectId
property.
When you call the Initialize method, an empty IPolicyQualifiers object is created. You can retrieve the object by
calling the PolicyQualifiers property. You can use the object to define policy qualifiers if you are creating a
Cer tificatePolicies extension.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

 Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
ICertificatePolicies
ICertificatePolicy
 ICertificationAuthorities interface (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The ICer tificationAuthorities interface defines the following methods and properties that manage a
collection of ICertificationAuthority objects.

Inheritance
The ICer tificationAuthorities interface inherits from the IDispatch interface. ICer tificationAuthorities also
has these types of members:

Methods
The ICer tificationAuthorities interface has these methods.

ICertificationAuthorities::Add

Adds an ICertificationAuthority object to the collection.

ICertificationAuthorities::Clear

Removes all ICertificationAuthority objects from the collection.

ICertificationAuthorities::ComputeSiteCosts

Is not currently used.

ICertificationAuthorities::get__NewEnum

Retrieves the enumerator for the collection.

ICertificationAuthorities::get_Count

Retrieves the number of ICertificationAuthority objects in the collection.

ICertificationAuthorities::get_ItemByIndex

Retrieves an ICertificationAuthority object from the collection by index number.

ICertificationAuthorities::get_ItemByName

Retrieves an ICertificationAuthority object from the collection by certification authority name.

ICertificationAuthorities::Remove

Removes an ICertificationAuthority object from the collection by index number.

Requirements
 Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Target Platform Windows

Header certenroll.h

See also
ICertificationAuthority
IDispatch
 ICertificationAuthorities::Add method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Add method adds an ICertificationAuthority object to the collection. This method is web enabled.

Syntax
HRESULT Add(
[in] ICertificationAuthority *pVal
);

Parameters
[in] pVal

Pointer to an ICertificationAuthority object to add to the collection.

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Target Platform Windows

Header certenroll.h

See also
ICertificationAuthorities
ICertificationAuthority
 ICertificationAuthorities::Clear method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Clear method removes all ICertificationAuthority objects from the collection.

Syntax
HRESULT Clear();

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Target Platform Windows

Header certenroll.h

See also
ICertificationAuthorities
ICertificationAuthority
 ICertificationAuthorities::ComputeSiteCosts method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The ComputeSiteCosts method is not currently used.

Syntax
HRESULT ComputeSiteCosts();

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. Possible values include, but are not
limited to, those in the following table. For a list of common error codes, see Common HRESULT Values.

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Target Platform Windows

Header certenroll.h

See also
ICertificationAuthorities
 ICertificationAuthorities::get__NewEnum method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The _NewEnum property retrieves the enumerator for the collection.

This property is read-only.

Syntax
HRESULT get__NewEnum(
LPUNKNOWN *pVal
);

Parameters
pVal

Return value
None

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Target Platform Windows

Header certenroll.h

See also
ICertificationAuthorities
ICertificationAuthority
 ICertificationAuthorities::get_Count method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Count property retrieves the number of ICertificationAuthority objects in the collection. This property is
web enabled.
This property is read-only.

Syntax
HRESULT get_Count(
long *pVal
);

Parameters
pVal

Return value
None

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Target Platform Windows

Header certenroll.h

See also
ICertificationAuthorities
ICertificationAuthority
 ICertificationAuthorities::get_ItemByName method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The ItemByName property retrieves an ICertificationAuthority object from the collection by certification
authority name. This property is web enabled.
This property is read-only.

Syntax
HRESULT get_ItemByName(
BSTR strName,
ICertificationAuthority **ppValue
);

Parameters
strName

ppValue

Return value
None

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Target Platform Windows

Header certenroll.h

See also
ICertificationAuthorities
ICertificationAuthority
 ICertificationAuthorities::Remove method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Remove method removes an ICertificationAuthority object from the collection by index number.

Syntax
HRESULT Remove(
[in] LONG Index
);

Parameters
[in] Index

A LONG variable that contains the index of the object to remove.

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Target Platform Windows

Header certenroll.h

See also
ICertificationAuthorities
ICertificationAuthority
 ICertificationAuthority interface (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The ICer tificationAuthority interface represents a single certification authority. A collection of certification
authorities is represented by the ICertificationAuthorities interface.

Inheritance
The ICertificationAuthority interface inherits from the IDispatch interface.

Methods
The ICer tificationAuthority interface has these methods.

ICertificationAuthority::get_Property

Retrieves a certification authority property value.

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Target Platform Windows

Header certenroll.h

See also
ICertificationAuthorities
IDispatch
 ICertificationAuthority::get_Property method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Property method retrieves a certification authority property value.

This property is read-only.

Syntax
HRESULT get_Property(
EnrollmentCAProperty property,
VARIANT *pValue
);

Parameters
property

pValue

Return value
None

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Target Platform Windows

Header certenroll.h

See also
ICertificationAuthority
 ICertProperties interface (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The ICer tProper ties interface contains methods and properties that enable you to manage a collection of
certificate properties.

Inheritance
The ICer tProper ties interface inherits from the IDispatch interface. ICer tProper ties also has these types of
members:

Methods
The ICer tProper ties interface has these methods.

ICertProperties::Add

Adds a property to the collection.

ICertProperties::Clear

Removes all properties from the collection.

ICertProperties::get__NewEnum

Retrieves the enumerator for the collection.

ICertProperties::get_Count

Retrieves the number of properties in the collection.

ICertProperties::get_ItemByIndex

Retrieves a property from the collection by index number.

ICertProperties::InitializeFromCertificate

Initializes the collection from the properties contained in a certificate.

ICertProperties::Remove

Removes a property from the collection by index value.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

 Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

See also
CertEnroll Interfaces
IDispatch
 ICertProperties::Add method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Add method adds a property to the collection. This method is web enabled.

Syntax
HRESULT Add(
[in] ICertProperty *pVal
);

Parameters
[in] pVal

Pointer to an ICertProperty interface that represents the property to add to the collection.

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. Possible values include, but are not
limited to, those in the following table. For a list of common error codes, see Common HRESULT Values.

RET URN C O DE/ VA L UE DESC RIP T IO N

An item in the collection has the same ID as the property

HRESULT_FROM_WIN32(ERROR_FILE_EXISTS) you specified.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
ICertProperties
ICertProperty
 ICertProperties::Clear method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Clear method removes all properties from the collection.

Syntax
HRESULT Clear();

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
ICertProperties
ICertProperty
 ICertProperties::get__NewEnum method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The _NewEnum property retrieves the enumerator for the collection.

This property is read-only.

Syntax
HRESULT get__NewEnum(
LPUNKNOWN *pVal
);

Parameters
pVal

Return value
None

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
ICertProperties
ICertProperty
 ICertProperties::get_Count method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Count property retrieves the number of properties in the collection. This property is web enabled.
This property is read-only.

Syntax
HRESULT get_Count(
long *pVal
);

Parameters
pVal

Return value
None

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
ICertProperties
ICertProperty
 ICertProperties::InitializeFromCertificate method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The InitializeFromCer tificate method initializes the collection from the properties contained in a certificate.

Syntax
HRESULT InitializeFromCertificate(
[in] VARIANT_BOOL MachineContext,
[in] EncodingType Encoding,
[in] BSTR strCertificate
);

Parameters
[in] MachineContext

A VARIANT_BOOL variable that identifies the certificate store context. Specify VARIANT_TRUE for the
computer and VARIANT_FALSE for the user.
[in] Encoding

An EncodingType enumeration value that specifies the type of Unicode encoding applied to the certificate
contained in the strCertificate parameter.
[in] strCertificate

A BSTR variable that contains the DER-encoded certificate.

Beginning with Windows 7 and Windows Server 2008 R2, you can specify a certificate thumb print or serial
number rather than an encoded certificate. Doing so causes the function to search the appropriate local stores
for the matching certificate. Keep in mind the following points:
The BSTR must be an even number of hexadecimal digits.
Whitespace between hexadecimal pairs is ignored.
The Encoding parameter must be set to XCN_CRYPT_STRING_HEXRAW .
The MachineContext parameter determines whether the user or computer stores or both are searched.
If a private key is needed, only the personal and request stores are searched.
If a private key is not needed, the root and intermediate CA stores are also searched.

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. Possible values include, but are not
limited to, those in the following table. For a list of common error codes, see Common HRESULT Values.

RET URN C O DE/ VA L UE DESC RIP T IO N

 The certificate could not be found.
CRYPT_E_NOT_FOUND

The certificate was found but the private key could not be
CRYPT_E_UNEXPECTED_MSG_TYPE loaded.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
ICertProperties
ICertProperty
 ICertProperties::Remove method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Remove method removes a property from the collection by index value.

Syntax
HRESULT Remove(
[in] LONG Index
);

Parameters
[in] Index

A LONG variable that contains the index of the property to remove.

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
ICertProperties
ICertProperty
 ICertProperty interface (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The ICer tProper ty interface can be used to associate an external property with a certificate. Properties are
never sent to or processed by a certification authority, and they are not stored inside a certificate. Typically, they
are associated with a certificate after the certificate is received from the certification authority and before it is
saved in a store. The properties are saved in the store along with the certificate. A collection of properties is
contained in an ICertProperties object. You can initialize the collection by using an existing certificate.
The CERTENROLL_PROPERTYID enumeration identifies the properties that you can specify or retrieve. Also, the
following interfaces, which inherit from ICer tProper ty , can be used to specify the most commonly used
properties:
ICertPropertyArchived
ICertPropertyArchivedKeyHash
ICertPropertyAutoEnroll
ICertPropertyBackedUp
ICertPropertyDescription
ICertPropertyEnrollment
ICertPropertyFriendlyName
ICertPropertyKeyProvInfo
ICertPropertyRenewal
ICertPropertyRequestOriginator
ICertPropertySHA1Hash

Note We recommend that you use the interfaces in the preceding list when appropriate. Enrollment behavior is not defined
when you use an ICer tProper ty base interface to represent any of these common properties.

Inheritance
The ICer tProper ty interface inherits from the IDispatch interface. ICer tProper ty also has these types of
members:

Methods
The ICer tProper ty interface has these methods.

ICertProperty::get_PropertyId

Specifies or retrieves a value of the CERTENROLL_PROPERTYID enumeration that identifies an external certificate property.

ICertProperty::get_RawData

Retrieves the value of the certificate property.

 ICertProperty::InitializeDecode

Initializes the object from a byte array that contains the property value.

ICertProperty::InitializeFromCertificate

Initializes the object by using a property value associated with an existing certificate.

ICertProperty::put_PropertyId

Specifies or retrieves a value of the CERTENROLL_PROPERTYID enumeration that identifies an external certificate property.

ICertProperty::RemoveFromCertificate

Disassociates a property from a certificate.

ICertProperty::SetValueOnCertificate

Associates a property value with an existing certificate.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

See also
CertEnroll Interfaces
ICertProperties
IDispatch
 ICertProperty::get_PropertyId method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Proper tyId property specifies or retrieves a value of the CERTENROLL_PROPERTYID enumeration that
identifies an external certificate property.
This property is read/write.

Syntax
HRESULT get_PropertyId(
CERTENROLL_PROPERTYID *pValue
);

Parameters
pValue

Return value
None

Remarks
Call the Proper tyId property before trying to initialize the ICertProperty object. Call the InitializeDecode
method or the InitializeFromCertificate method to create a value for the certificate property. Call the RawData
property to retrieve the property value.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
ICertProperties
ICertProperty
 ICertProperty::get_RawData method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The RawData property retrieves the value of the certificate property.

This property is read-only.

Syntax
HRESULT get_RawData(
EncodingType Encoding,
BSTR *pValue
);

Parameters
Encoding

pValue

Return value
None

Remarks
Call PropertyId to identify the property to retrieve before calling the RawData property.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
ICertProperty
 ICertProperty::InitializeDecode method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The InitializeDecode method initializes the object from a byte array that contains the property value. The byte
array is represented by a Unicode-encoded string.

Syntax
HRESULT InitializeDecode(
[in] EncodingType Encoding,
[in] BSTR strEncodedData
);

Parameters
[in] Encoding

An EncodingType enumeration value that specifies the type of Unicode encoding applied to the input string.
[in] strEncodedData

A BSTR variable that contains the Distinguished Encoding Rules (DER) encoded property value.

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. Possible values include, but are not
limited to, those in the following table. For a list of common error codes, see Common HRESULT Values.

RET URN C O DE/ VA L UE DESC RIP T IO N

The object is already initialized.

HRESULT_FROM_WIN32(ERROR_ALREADY_INITIALIZE
D)

Remarks
Specify the property to initialize by calling the PropertyId property. You can call the RawData property to
retrieve the encoded property value. Call the SetValueOnCertificate method to associate the property value with
a certificate.
If the InitializeDecode method fails, the ICertProperty object is not initialized and the input property value is
not saved. However, the PropertyId property retains the specified identifier.
The InitializeDecode method is provided to enable you to initialize custom properties and properties
identified in the CERTENROLL_PROPERTYID enumeration for which there exist no specific interface. Each of the
supported values in that enumeration contains information about the type of data, usually a
CRYPT_INTEGER_BLOB, that you must supply to the InitializeDecode method. You can use the
IBinaryConverter interface to convert a byte array to a string.
The following interfaces simplify creation of the most common properties:
ICertPropertyArchived
ICertPropertyArchivedKeyHash
ICertPropertyAutoEnroll
ICertPropertyBackedUp
ICertPropertyDescription
ICertPropertyEnrollment
ICertPropertyFriendlyName
ICertPropertyKeyProvInfo
ICertPropertyRenewal
ICertPropertyRequestOriginator
ICertPropertySHA1Hash

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
ICertProperties
ICertProperty
 ICertProperty::InitializeFromCertificate method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The InitializeFromCer tificate method initializes the object by using a property value associated with an
existing certificate.

Syntax
HRESULT InitializeFromCertificate(
[in] VARIANT_BOOL MachineContext,
[in] EncodingType Encoding,
[in] BSTR strCertificate
);

Parameters
[in] MachineContext

A VARIANT_BOOL value that indicates whether the certificate store is for the local computer or the current
user. Specify VARIANT_TRUE for the computer and VARIANT_FALSE for the user.
[in] Encoding

An EncodingType enumeration value that specifies the type of Unicode encoding applied to the certificate
contained in the strCertificate parameter.
[in] strCertificate

A BSTR variable that contains the DER-encoded certificate.

Beginning with Windows 7 and Windows Server 2008 R2, you can specify a certificate thumb print or serial
number rather than an encoded certificate. Doing so causes the function to search the appropriate local stores
for the matching certificate. Keep in mind the following points:
The BSTR must be an even number of hexadecimal digits.
Whitespace between hexadecimal pairs is ignored.
The Encoding parameter must be set to XCN_CRYPT_STRING_HEXRAW .
The MachineContext parameter determines whether the user or computer stores or both are searched.
If a private key is needed, only the personal and request stores are searched.
If a private key is not needed, the root and intermediate CA stores are also searched.

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. Possible values include, but are not
limited to, those in the following table. For a list of common error codes, see Common HRESULT Values.

RET URN C O DE/ VA L UE DESC RIP T IO N

 The certificate could not be found.
CRYPT_E_NOT_FOUND

The certificate was found but the private key could not be
CRYPT_E_UNEXPECTED_MSG_TYPE loaded.

Remarks
Specify the property to initialize by calling the PropertyId property. You can call the RawData property to
retrieve an encoded string that contains the property.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
ICertProperties
ICertProperty
 ICertProperty::put_PropertyId method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Proper tyId property specifies or retrieves a value of the CERTENROLL_PROPERTYID enumeration that
identifies an external certificate property.
This property is read/write.

Syntax
HRESULT put_PropertyId(
CERTENROLL_PROPERTYID Value
);

Parameters
Value

Return value
None

Remarks
Call the Proper tyId property before trying to initialize the ICertProperty object. Call the InitializeDecode
method or the InitializeFromCertificate method to create a value for the certificate property. Call the RawData
property to retrieve the property value.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
ICertProperties
ICertProperty
 ICertProperty::RemoveFromCertificate method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The RemoveFromCer tificate method disassociates a property from a certificate. Specify the property to
remove by calling the PropertyId property.

Syntax
HRESULT RemoveFromCertificate(
[in] VARIANT_BOOL MachineContext,
[in] EncodingType Encoding,
[in] BSTR strCertificate
);

Parameters
[in] MachineContext

A VARIANT_BOOL value that indicates whether the certificate store is located on the local computer. Specify
VARIANT_TRUE if the store is local.
[in] Encoding

An EncodingType enumeration value that specifies the type of encoding applied to the certificate string
identified by the strCertificate parameter.
[in] strCertificate

A BSTR variable that contains the DER-encoded certificate.

Beginning with Windows 7 and Windows Server 2008 R2, you can specify a certificate thumb print or serial
number rather than an encoded certificate. Doing so causes the function to search the appropriate local stores
for the matching certificate. Keep in mind the following points:
The BSTR must be an even number of hexadecimal digits.
Whitespace between hexadecimal pairs is ignored.
The Encoding parameter must be set to XCN_CRYPT_STRING_HEXRAW .
The MachineContext parameter determines whether the user or computer stores or both are searched.
If a private key is needed, only the personal and request stores are searched.
If a private key is not needed, the root and intermediate CA stores are also searched.

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. Possible values include, but are not
limited to, those in the following table. For a list of common error codes, see Common HRESULT Values.

RET URN C O DE/ VA L UE DESC RIP T IO N

 The certificate could not be found.
CRYPT_E_NOT_FOUND

The certificate was found but the private key could not be
CRYPT_E_UNEXPECTED_MSG_TYPE loaded.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
ICertProperties
ICertProperty
 ICertProperty::SetValueOnCertificate method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The SetValueOnCer tificate method associates a property value with an existing certificate.

Syntax
HRESULT SetValueOnCertificate(
[in] VARIANT_BOOL MachineContext,
[in] EncodingType Encoding,
[in] BSTR strCertificate
);

Parameters
[in] MachineContext

A VARIANT_BOOL value that indicates whether the certificate store is for the local computer or the current
user. Specify VARIANT_TRUE for the computer and VARIANT_FALSE for the user.
[in] Encoding

An EncodingType enumeration value that specifies the type of Unicode encoding applied to the certificate string
identified by the strCertificate parameter.
[in] strCertificate

A BSTR variable that contains the DER-encoded certificate.

Beginning with Windows 7 and Windows Server 2008 R2, you can specify a certificate thumb print or serial
number rather than an encoded certificate. Doing so causes the function to search the appropriate local stores
for the matching certificate. Keep in mind the following points:
The BSTR must be an even number of hexadecimal digits.
Whitespace between hexadecimal pairs is ignored.
The Encoding parameter must be set to XCN_CRYPT_STRING_HEXRAW .
The MachineContext parameter determines whether the user or computer stores or both are searched.
If a private key is needed, only the personal and request stores are searched.
If a private key is not needed, the root and intermediate CA stores are also searched.

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. Possible values include, but are not
limited to, those in the following table. For a list of common error codes, see Common HRESULT Values.

RET URN C O DE/ VA L UE DESC RIP T IO N

 The certificate could not be found.
CRYPT_E_NOT_FOUND

The certificate was found but the private key could not be
CRYPT_E_UNEXPECTED_MSG_TYPE loaded.

Remarks
Call the InitializeDecode method or the InitializeFromCertificate method to create a property value. Before
calling either method, you must first set the PropertyId property to specify which property value to initialize.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
ICertProperties
ICertProperty
 ICertPropertyArchived interface (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The ICer tProper tyArchived interface represents a certificate property that identifies whether a certificate has
been archived. Typically, a certificate is archived after being renewed, and this property is set so that archived
certificates can be identified and skipped during enumeration.
This property is initialized by the enrollment process after the client requests that a certificate be renewed. If a
new certificate is issued, the property is associated with the old certificate in the personal store.

Note The CERTENROLL_PROPERTYID value is XCN_CERT_ARCHIVED_PROP_ID.

Inheritance
The ICer tProper tyArchived interface inherits from ICertProperty. ICer tProper tyArchived also has these
types of members:

Methods
The ICer tProper tyArchived interface has these methods.

ICertPropertyArchived::get_Archived

Retrieves a Boolean value that specifies whether the certificate has been archived.

ICertPropertyArchived::Initialize

Initializes the object from a Boolean value that specifies whether the certificate has been archived.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

See also
CertEnroll Interfaces
ICertProperty
 ICertPropertyArchived::get_Archived method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Archived property retrieves a Boolean value that specifies whether the certificate has been archived.
This property is read-only.

Syntax
HRESULT get_Archived(
VARIANT_BOOL *pValue
);

Parameters
pValue

Return value
None

Remarks
Call the Initialize method to specify the Boolean value.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
ICertProperty
ICertPropertyArchived
 ICertPropertyArchived::Initialize method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Initialize method initializes the object from a Boolean value that specifies whether the certificate has been
archived.

Syntax
HRESULT Initialize(
[in] VARIANT_BOOL ArchivedValue
);

Parameters
[in] ArchivedValue

A VARIANT_BOOL variable that identifies whether the certificate has been archived.

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. Possible values include, but are not
limited to, those in the following table. For a list of common error codes, see Common HRESULT Values.

RET URN C O DE/ VA L UE DESC RIP T IO N

The object is already initialized.

HRESULT_FROM_WIN32(ERROR_ALREADY_INITIALIZE
D)

Remarks
Call the SetValueOnCertificate method to associate the property with a certificate. Call the Archived property to
retrieve the Boolean value.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h
 DLL CertEnroll.dll

See also
ICertProperty
ICertPropertyArchived
 ICertPropertyArchivedKeyHash interface
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The ICer tProper tyArchivedKeyHash interface represents a SHA-1 hash of an encrypted private key
submitted to a certification authority for archival.
To archive a private key, a client first encrypts the key by using the public key from a CA exchange certificate. The
client then places the encrypted private key into a PKCS #7 EnvelopedData structure and hashes the structure by
using a SHA-1 hash algorithm. The resulting hash is used to initialize an ICer tProper tyArchivedKeyHash
object and is included in a CMC certificate request. The property value is typically associated with the certificate
after the certificate response is received from the CA and before the response is placed in a store.
This property is initialized by the enrollment process and associated with the dummy certificate that is
temporarily copied to the request store. If the CA denies the certificate request, the dummy certificate in the
request store and all properties associated with it are deleted. If the CA issues the certificate and it is installed in
the certificate store, this property is associated with the new certificate in the personal store and the dummy
certificate is deleted.

Note The CERTENROLL_PROPERTYID value is XCN_CERT_ARCHIVED_KEY_HASH_PROP_IDD.

Inheritance
The ICer tProper tyArchivedKeyHash interface inherits from ICertProperty.
ICer tProper tyArchivedKeyHash also has these types of members:

Methods
The ICer tProper tyArchivedKeyHash interface has these methods.

ICertPropertyArchivedKeyHash::get_ArchivedKeyHash

Retrieves a SHA-1 hash of the private key.

ICertPropertyArchivedKeyHash::Initialize

Initializes the object from a byte array that contains the hash.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]
 Target Platform Windows

Header certenroll.h

See also
CertEnroll Interfaces
ICertProperty
 ICertPropertyArchivedKeyHash::get_ArchivedKeyHash
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The ArchivedKeyHash property retrieves a SHA-1 hash of the private key.

This property is read-only.

Syntax
HRESULT get_ArchivedKeyHash(
EncodingType Encoding,
BSTR *pValue
);

Parameters
Encoding

pValue

Return value
None

Remarks
Call the Initialize method to specify the hash.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
ArchivePrivateKey
ICertPropertyArchivedKeyHash
KeyArchivalCertificate
 ICertPropertyArchivedKeyHash::Initialize method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Initialize method initializes the object from a byte array that contains the hash. The byte array is
represented as a Unicode-encoded string.

Syntax
HRESULT Initialize(
[in] EncodingType Encoding,
[in] BSTR strArchivedKeyHashValue
);

Parameters
[in] Encoding

An EncodingType enumeration value that specifies the type of Unicode encoding applied to the input string.
[in] strArchivedKeyHashValue

A BSTR variable that contains a SHA-1 hash of the encrypted private key.

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. Possible values include, but are not
limited to, those in the following table. For a list of common error codes, see Common HRESULT Values.

RET URN C O DE/ VA L UE DESC RIP T IO N

The object is already initialized.

HRESULT_FROM_WIN32(ERROR_ALREADY_INITIALIZE
D)

Remarks
Call the SetValueOnCertificate method to associate the property with a certificate. Call the ArchivedKeyHash
property to retrieve the hash.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]
 Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
ArchivePrivateKey
ICertPropertyArchivedKeyHash
KeyArchivalCertificate
 ICertPropertyAutoEnroll interface (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The ICer tProper tyAutoEnroll interface represents a certificate property that identifies a template that has
been configured to enable autoenrollment of the certificate.
Computers and users that are joined to a domain can be automatically enrolled for certificates to enable better
management of the certificate life cycle. By default, computers are enrolled when they are restarted, and users
are enrolled during logon.
The autoenrollment process copies appropriate certificate stores from Active Directory on the server to the
client and enumerates the templates that have been configured for autoenrollment. A certificate request is
automatically created and submitted to a certification authority for each enumerated template that requires no
user interaction.

Note The CERTENROLL_PROPERTYID value is XCN_CERT_AUTO_ENROLL_PROP_ID.

Inheritance
The ICer tProper tyAutoEnroll interface inherits from ICertProperty. ICer tProper tyAutoEnroll also has
these types of members:

Methods
The ICer tProper tyAutoEnroll interface has these methods.

ICertPropertyAutoEnroll::get_TemplateName

Retrieves a string that contains the name of the template that the certificate can use for autoenrollment.

ICertPropertyAutoEnroll::Initialize

Initializes the object by specifying the name of the template to be used for autoenrollment.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h
See also
CertEnroll Interfaces
ICertProperty
 ICertPropertyAutoEnroll::get_TemplateName
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The TemplateName property retrieves a string that contains the name of the template that the certificate can
use for autoenrollment.
This property is read-only.

Syntax
HRESULT get_TemplateName(
BSTR *pValue
);

Parameters
pValue

Return value
None

Remarks
Call the Initialize method to specify the property value.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
ICertProperty
ICertPropertyAutoEnroll
 ICertPropertyAutoEnroll::Initialize method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Initialize method initializes the object by specifying the name of the template to be used for
autoenrollment.

Syntax
HRESULT Initialize(
[in] BSTR strTemplateName
);

Parameters
[in] strTemplateName

A BSTR variable that contains the template name or object identifier.

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. Possible values include, but are not
limited to, those in the following table. For a list of common error codes, see Common HRESULT Values.

RET URN C O DE/ VA L UE DESC RIP T IO N

The object is already initialized.

HRESULT_FROM_WIN32(ERROR_ALREADY_INITIALIZE
D)

Remarks
Call the SetValueOnCertificate method to associate the property with a certificate. Call the TemplateName
property to retrieve the template name.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h
 DLL CertEnroll.dll

See also
ICertProperty
ICertPropertyAutoEnroll
 ICertPropertyBackedUp interface (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The ICer tProper tyBackedUp interface represents an external certificate property that identifies whether a
certificate has been backed up and, if so, the date and time that it was saved. This property is not currently used.

Note The CERTENROLL_PROPERTYID value is XCN_CERT_BACKED_UP_PROP_ID.

Inheritance
The ICer tProper tyBackedUp interface inherits from ICertProperty. ICer tProper tyBackedUp also has these
types of members:

Methods
The ICer tProper tyBackedUp interface has these methods.

ICertPropertyBackedUp::get_BackedUpTime

Retrieves the date and time at which the certificate was backed up.

ICertPropertyBackedUp::get_BackedUpValue

Retrieves a Boolean value that identifies whether the certificate was backed up.

ICertPropertyBackedUp::Initialize

Initializes the object from a Boolean value and a date.

ICertPropertyBackedUp::InitializeFromCurrentTime

Initializes the property from a Boolean value and the current system date and time.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h
See also
CertEnroll Interfaces
ICertProperty
 ICertPropertyBackedUp::get_BackedUpTime
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The BackedUpTime property retrieves the date and time at which the certificate was backed up.
This property is read-only.

Syntax
HRESULT get_BackedUpTime(
DATE *pDate
);

Parameters
pDate

Return value
None

Remarks
Call the Initialize method or the InitializeFromCurrentTime method to set the BackedUpTime value.
The date is stored as an 8-byte real value, representing a date between January 1, 1900 and December 31, 9999,
inclusive. The value 2.0 represents January 1, 1900; 3.0 represents January 2, 1900. Adding 1 to the value
increments the date by a day. The fractional part of the value represents the time of day. Therefore, 2.5
represents 12:00 on January 1, 1900; 3.25 represents 06:00 on January 2, 1900.
For dates between 1950 and 2049 inclusive, the date and time is encoded UTC-time in the form
YYMMDDHHMMSS. For dates before 1950 or after 2049, encoded generalized time is used. Encoded
generalized time is in the form YYYYMMDDHHMMSSMMM, using a four digit year, and is precise to
milliseconds.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h
 DLL CertEnroll.dll

See also
ICertProperty
ICertPropertyBackedUp
 ICertPropertyBackedUp::get_BackedUpValue
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The BackedUpValue property retrieves a Boolean value that identifies whether the certificate was backed up.
This property is read-only.

Syntax
HRESULT get_BackedUpValue(
VARIANT_BOOL *pValue
);

Parameters
pValue

Return value
None

Remarks
Call the Initialize method or the InitializeFromCurrentTime method to set the BackedUpValue property value.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
ICertProperty
ICertPropertyBackedUp
 ICertPropertyBackedUp::Initialize method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Initialize method initializes the object from a Boolean value and a date.

Syntax
HRESULT Initialize(
[in] VARIANT_BOOL BackedUpValue,
[in] DATE Date
);

Parameters
[in] BackedUpValue

A VARIANT_BOOL variable that identifies whether the certificate has been backed up.
[in] Date

A DATE variable that identifies when a certificate was last backed up.

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. Possible values include, but are not
limited to, those in the following table. For a list of common error codes, see Common HRESULT Values.

RET URN C O DE/ VA L UE DESC RIP T IO N

The object is already initialized.

HRESULT_FROM_WIN32(ERROR_ALREADY_INITIALIZE
D)

The specified time is not valid.

HRESULT_FROM_WIN32(ERROR_INVALID_DATA)

Remarks
The date is stored as an 8-byte real value, representing a date between January 1, 1900 and December 31, 9999,
inclusive. The value 2.0 represents January 1, 1900; 3.0 represents January 2, 1900. Adding 1 to the value
increments the date by a day. The fractional part of the value represents the time of day. Therefore, 2.5
represents 12:00 on January 1, 1900; 3.25 represents 06:00 on January 2, 1900.
For dates between 1950 and 2049 inclusive, the date and time is encoded UTC-time in the form
YYMMDDHHMMSS. For dates before 1950 or after 2049, encoded generalized time is used. Encoded
generalized time is in the form YYYYMMDDHHMMSSMMM, using a four digit year, and is precise to
milliseconds.
Call the SetValueOnCertificate method to associate the property with a certificate. To retrieve the date, call the
BackedUpTime property. To retrieve the Boolean value that identifies whether a certificate was backed up, call
the BackedUpValue property.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
ICertProperty
ICertPropertyBackedUp
 ICertPropertyBackedUp::InitializeFromCurrentTime
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The InitializeFromCurrentTime method initializes the property from a Boolean value and the current system
date and time.

Syntax
HRESULT InitializeFromCurrentTime(
[in] VARIANT_BOOL BackedUpValue
);

Parameters
[in] BackedUpValue

A VARIANT_BOOL variable that identifies whether the certificate has been backed up.

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. Possible values include, but are not
limited to, those in the following table. For a list of common error codes, see Common HRESULT Values.

RET URN C O DE/ VA L UE DESC RIP T IO N

The object is already initialized.

HRESULT_FROM_WIN32(ERROR_ALREADY_INITIALIZE
D)

The specified time is not valid.

HRESULT_FROM_WIN32(ERROR_INVALID_DATA)

Remarks
Internally, the InitializeFromCurrentTime calls the GetSystemTimeAsFileTime function in the Windows
SDK. The date is stored as an 8-byte real value, representing a date between January 1, 1900 and December 31,
9999, inclusive. The value 2.0 represents January 1, 1900; 3.0 represents January 2, 1900. Adding 1 to the value
increments the date by a day. The fractional part of the value represents the time of day. Therefore, 2.5
represents 12:00 on January 1, 1900; 3.25 represents 06:00 on January 2, 1900.
For dates between 1950 and 2049 inclusive, the date and time is encoded UTC-time in the form
YYMMDDHHMMSS. For dates before 1950 or after 2049, encoded generalized time is used. Encoded
generalized time is in the form YYYYMMDDHHMMSSMMM, using a four digit year, and is precise to
milliseconds.
Call the SetValueOnCertificate method to associate the property with a certificate. To retrieve the date, call the
BackedUpTime property. To retrieve the Boolean value that identifies whether a certificate was backed up, call
the BackedUpValue property.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
ICertProperty
ICertPropertyBackedUp
 ICertPropertyDescription interface (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The ICer tProper tyDescription interface enables you to specify and retrieve a string that contains descriptive
information for a certificate. You can use this interface to identify the intended purpose of a certificate for
display in a user interface.

Note The CERTENROLL_PROPERTYID value is XCN_CERT_DESCRIPTION_PROP_ID.

Inheritance
The ICer tProper tyDescription interface inherits from ICertProperty. ICer tProper tyDescription also has
these types of members:

Methods
The ICer tProper tyDescription interface has these methods.

ICertPropertyDescription::get_Description

Retrieves a description of the certificate.

ICertPropertyDescription::Initialize

Initializes the object from a string that contains descriptive information about the certificate.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

See also
ICertProperties
ICertProperty
ICertPropertyFriendlyName
 ICertPropertyDescription::get_Description method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Description property retrieves a description of the certificate. The description identifies the intended use of
the certificate.
This property is read-only.

Syntax
HRESULT get_Description(
BSTR *pValue
);

Parameters
pValue

Return value
None

Remarks
Call the Initialize method to create a description.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
ICertProperties
ICertProperty
ICertPropertyDescription
ICertPropertyFriendlyName
 ICertPropertyDescription::Initialize method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Initialize method initializes the object from a string that contains descriptive information about the
certificate. Use this property to create a string that can be displayed in user interfaces that enumerate certificate
properties. This method is web enabled.

Syntax
HRESULT Initialize(
[in] BSTR strDescription
);

Parameters
[in] strDescription

A BSTR variable that contains a description. The string length cannot exceed 260 characters.

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. Possible values include, but are not
limited to, those in the following table. For a list of common error codes, see Common HRESULT Values.

RET URN C O DE/ VA L UE DESC RIP T IO N

The object is already initialized.

HRESULT_FROM_WIN32(ERROR_ALREADY_INITIALIZE
D)

The string length exceeds 260 characters.

HRESULT_FROM_WIN32(ERROR_FILENAME_EXCED_R
ANGE)

Remarks
Call the SetValueOnCertificate method to associate the property with a certificate. Call the Description property
to retrieve the description string.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

 Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
ICertProperties
ICertProperty
ICertPropertyDescription
ICertPropertyFriendlyName
 ICertPropertyEnrollment interface (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The ICer tProper tyEnrollment interface represents a certificate property that contains certificate and
certification authority (CA) information created when the client calls the Enroll method on the IX509Enrollment
interface. The property value consists of the following information:
A certificate request ID
The common name (CN) of the certificate subject
The certification authority (CA) Domain Name System (DNS) name
The optional display name of the certificate being requested
This property is initialized by the enrollment process and associated with the dummy certificate that is
temporarily copied to the request store. If the CA marks the request pending after it is submitted, auto-
enrollment can later use the request ID to retrieve the certificate response. If the CA denies the certificate
request, the dummy certificate in the request store and all properties associated with it are deleted. If the CA
issues the certificate and it is installed in the personal store, this property is associated with the new certificate
and the dummy certificate is deleted.

Note The CERTENROLL_PROPERTYID value is XCN_CERT_ENROLLMENT_PROP_ID.

Inheritance
The ICer tProper tyEnrollment interface inherits from ICertProperty. ICer tProper tyEnrollment also has
these types of members:

Methods
The ICer tProper tyEnrollment interface has these methods.

ICertPropertyEnrollment::get_CADnsName

Retrieves the Domain Naming System (DNS) name of the certification authority (CA).

ICertPropertyEnrollment::get_CAName

Retrieves the common name (CN) of the certification authority (CA).

ICertPropertyEnrollment::get_FriendlyName

Retrieves the display name of the certificate.

ICertPropertyEnrollment::get_RequestId

Retrieves a unique certificate request identifier.

 ICertPropertyEnrollment::Initialize

Initializes the property from the certificate request ID, the certification authority (CA) configuration string, and an optional
certificate display name.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

See also
CertEnroll Interfaces
ICertProperty
 ICertPropertyEnrollment::get_CADnsName method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The CADnsName property retrieves the Domain Naming System (DNS) name of the certification authority
(CA).
This property is read-only.

Syntax
HRESULT get_CADnsName(
BSTR *pValue
);

Parameters
pValue

Return value
None

Remarks
Set the CADnsName property by calling the Initialize method. The DNS name is returned to the client during
the enrollment process and is part of the CA configuration string. For more information, see the CAConfigString
property on the IX509Enrollment interface.
You can also call the following properties to retrieve the other values specified during initialization:
CAName
FriendlyName
RequestId

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll
See also
ICertProperty
ICertPropertyEnrollment
 ICertPropertyEnrollment::get_CAName method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The CAName property retrieves the common name (CN) of the certification authority (CA).
This property is read-only.

Syntax
HRESULT get_CAName(
BSTR *pValue
);

Parameters
pValue

Return value
None

Remarks
Set the CAName property by calling the Initialize method. The common name is returned to the client during
the enrollment process and is part of the certification authority configuration string. For more information, see
the CAConfigString property on the IX509Enrollment interface.
You can also call the following properties to retrieve the other values specified during initialization:
CADnsName
FriendlyName
RequestId

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll
See also
ICertProperty
ICertPropertyEnrollment
 ICertPropertyEnrollment::get_FriendlyName method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The FriendlyName property retrieves the display name of the certificate.

This property is read-only.

Syntax
HRESULT get_FriendlyName(
BSTR *pValue
);

Parameters
pValue

Return value
None

Remarks
Set the FriendlyName property by calling the Initialize method. The display name is specified during the
enrollment process. For more information, see the CertificateFriendlyName property on the IX509Enrollment
interface.
You can also call the following properties to retrieve the other values specified during initialization:
CADnsName
CAName
RequestId

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll
See also
ICertProperty
ICertPropertyEnrollment
 ICertPropertyEnrollment::get_RequestId method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The RequestId property retrieves a unique certificate request identifier.

This property is read-only.

Syntax
HRESULT get_RequestId(
LONG *pValue
);

Parameters
pValue

Return value
None

Remarks
Set the RequestId property by calling the Initialize method. The request ID is created during the enrollment
process. For more information, see the RequestId property on the IX509Enrollment interface.
The ID can be used during subsequent communication between the client and the CA. For example, if a CA
marks a request as pending when initially submitted, the client can use the request ID and the configuration
string when it again contacts the CA and attempts to retrieve the certificate response.
You can also call the following properties to retrieve the other values specified during initialization:
CADnsName
CAName
FriendlyName

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h
 DLL CertEnroll.dll

See also
ICertProperty
ICertPropertyEnrollment
 ICertPropertyEnrollment::Initialize method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Initialize method initializes the property from the certificate request ID, the certification authority (CA)
configuration string, and an optional certificate display name.

Syntax
HRESULT Initialize(
[in] LONG RequestId,
[in] BSTR strCADnsName,
[in] BSTR strCAName,
[in, optional] BSTR strFriendlyName
);

Parameters
[in] RequestId

A LONG variable that contains the certificate request ID. A request ID is created by the enrollment process. You
can retrieve this value by calling the RequestId property on the IX509Enrollment interface.
[in] strCADnsName

A BSTR variable that contains the Domain Name System (DNS) name of the CA. This is the first name in the
CADnsName\CAName CA configuration string. The configuration string is typically set during the enrollment
process. The DNS name can be retrieved by calling the CAConfigString property and separating the string into
its constituent parts.
[in] strCAName

A BSTR variable that contains the subject common name (CN) of the CA. This is the second name in the
CADnsName\CAName CA configuration string. The configuration string is typically set during the enrollment
process. The CN name can be retrieved by calling the CAConfigString property and separating the string into its
constituent parts.
[in, optional] strFriendlyName

A BSTR variable that contains an optional display name for the certificate. The default value is NULL . This value
is typically set during the enrollment process. You can retrieve it by calling the CertificateFriendlyName property.

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. Possible values include, but are not
limited to, those in the following table. For a list of common error codes, see Common HRESULT Values.

RET URN C O DE/ VA L UE DESC RIP T IO N

 The object is already initialized.
HRESULT_FROM_WIN32(ERROR_ALREADY_INITIALIZE
D)

Remarks
The values that you can use to initialize the ICertPropertyEnrollment object are set during the certificate
enrollment process when the client calls the Enroll method on the IX509Enrollment object. That is, to retrieve a
request ID, call the RequestId property on the IX509Enrollment object. To retrieve a certificate display name,
call the CertificateFriendlyName property. To retrieve a distinguished name and common name, call the
CAConfigString property and separate the configuration string into its constituent parts.
Call the SetValueOnCertificate method to associate the property with a certificate. You can also call the following
properties to retrieve the values specified during initialization:
CADnsName
CAName
FriendlyName
RequestId

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
ICertProperty
ICertPropertyEnrollment
 ICertPropertyEnrollmentPolicyServer interface
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The ICer tProper tyEnrollmentPolicySer ver interface represents an external certificate property that contains
information about a certificate enrollment policy (CEP) server and a certificate enrollment server (CES). A CEP
server is a web service that retrieves policy information. A CES is a web service that targets a specific
certification authority to support certificate enrollment.
The following list identifies the policy data managed by this interface and which can be added as a property
value to an issued certificate.
The CEP client authentication method.
The CES client authentication method.
The CEP URL.
The CES URL.
The CEP ID.
The request ID string.
In addition to the preceding policy information, a CEP web service also queries Active Directory for collections of
available certification authorities, certificate templates, and custom object identifiers. These collections can be
retrieved by using the IX509EnrollmentPolicyServer interface.

Note The CERTENROLL_PROPERTYID value is XCN_CERT_CEP_PROP_ID.

Inheritance
The ICer tProper tyEnrollmentPolicySer ver interface inherits from ICertProperty.
ICer tProper tyEnrollmentPolicySer ver also has these types of members:

Methods
The ICer tProper tyEnrollmentPolicySer ver interface has these methods.

ICertPropertyEnrollmentPolicyServer::GetAuthentication

The GetAuthentication method retrieves a value that specifies the type of authentication used by the certificate enrollment
policy (CEP) server to authenticate a client. This value is set by the Initialize method.

ICertPropertyEnrollmentPolicyServer::GetEnrollmentServerAuthentication

The GetEnrollmentServerAuthentication method retrieves a value that specifies the type of authentication used by the
certificate enrollment server (CES) to authenticate a client. This value is set by the Initialize method.
 ICertPropertyEnrollmentPolicyServer::GetEnrollmentServerUrl

Retrieves a string that contains the URL for the certificate enrollment server.

ICertPropertyEnrollmentPolicyServer::GetPolicyServerId

Retrieves a string that uniquely identifies the certificate enrollment policy (CEP) server.

ICertPropertyEnrollmentPolicyServer::GetPolicyServerUrl

Retrieves a string that contains the URL for the certificate enrollment policy (CEP) server.

ICertPropertyEnrollmentPolicyServer::GetPropertyFlags

Retrieves a value that specifies the default policy server URL.

ICertPropertyEnrollmentPolicyServer::GetRequestIdString

Retrieves a unique string identifier for the certificate request sent to the certification authority during enrollment.

ICertPropertyEnrollmentPolicyServer::GetUrlFlags

Retrieves a set of flags that contain miscellaneous policy information about the certificate enrollment policy (CEP) server.

ICertPropertyEnrollmentPolicyServer::Initialize

Initializes an ICertPropertyEnrollmentPolicyServer object.

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Target Platform Windows

Header certenroll.h

See also
ICertProperty
IX509EnrollmentPolicyServer
 ICertPropertyEnrollmentPolicyServer::GetAuthentication
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The GetAuthentication method retrieves a value that specifies the type of authentication used by the
certificate enrollment policy (CEP) server to authenticate a client. This value is set by the Initialize method.

Syntax
HRESULT GetAuthentication(
[out, retval] X509EnrollmentAuthFlags *pValue
);

Parameters
[out, retval] pValue

An X509EnrollmentAuthFlags enumeration value that specifies the client authentication type. This can be one of
the following values.

VA L UE M EA N IN G

Anonymous authentication.
X509AuthAnonymous

Kerberos authentication.
X509AuthKerberos

Clear text user name and password authentication.

X509AuthUsername
Note The user name and password are encrypted before
transmission and are stored securely in the credential vault
on the CEP server.

Client authentication certificate installed on the local

X509AuthCer tificate computer and used by the server to verify the identity of the
client.

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. Possible values include, but are not
limited to, those in the following table. For a list of common error codes, see Common HRESULT Values.

RET URN C O DE/ VA L UE DESC RIP T IO N

 The pValue parameter cannot be NULL .
E_POINTER

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Target Platform Windows

Header certenroll.h

See also
ICertPropertyEnrollmentPolicyServer
 ICertPropertyEnrollmentPolicyServer::GetEnrollmentServerAuthentication
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The GetEnrollmentSer verAuthentication method retrieves a value that specifies the type of authentication
used by the certificate enrollment server (CES) to authenticate a client. This value is set by the Initialize method.

Syntax
HRESULT GetEnrollmentServerAuthentication(
[out, retval] X509EnrollmentAuthFlags *pValue
);

Parameters
[out, retval] pValue

An X509EnrollmentAuthFlags enumeration value that specifies the client authentication type. This can be one of
the following values.

VA L UE M EA N IN G

Anonymous authentication.
X509AuthAnonymous

Kerberos authentication.
X509AuthKerberos

Clear text user name and password authentication.

X509AuthUsername
Note The user name and password are encrypted before
transmission and are stored securely in the credential vault
on the certificate enrollment server.

Client authentication certificate installed on the local

X509AuthCer tificate computer and used by the server to verify the identity of the
client.

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. Possible values include, but are not
limited to, those in the following table. For a list of common error codes, see Common HRESULT Values.

RET URN C O DE/ VA L UE DESC RIP T IO N

The pValue parameter cannot be NULL .

E_POINTER

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Target Platform Windows

 Header certenroll.h

See also
ICertPropertyEnrollmentPolicyServer
 ICertPropertyEnrollmentPolicyServer::GetEnrollmentServerUrl
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The GetEnrollmentSer verUrl method retrieves a string that contains the URL for the certificate enrollment
server. This value is set by the Initialize method.

Syntax
HRESULT GetEnrollmentServerUrl(
[out, retval] BSTR *pValue
);

Parameters
[out, retval] pValue

Pointer to a BSTR that receives the URL.

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. Possible values include, but are not
limited to, those in the following table. For a list of common error codes, see Common HRESULT Values.

RET URN C O DE/ VA L UE DESC RIP T IO N

The property value is empty.

CERTSRV_E_PROPERTY_EMPTY

There was insufficient memory available to create the URL

E_OUTOFMEMORY string.

The property value has not been initialized.

HRESULT_FROM_WIN32(OLE_E_BL ANK)

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Target Platform Windows

Header certenroll.h

See also
ICertPropertyEnrollmentPolicyServer
 ICertPropertyEnrollmentPolicyServer::GetPolicyServerId
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The GetPolicySer verId method retrieves a string that uniquely identifies the certificate enrollment policy (CEP)
server. This value is set by the Initialize method.

Syntax
HRESULT GetPolicyServerId(
[out, retval] BSTR *pValue
);

Parameters
[out, retval] pValue

Pointer to a BSTR that receives the ID string.

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. Possible values include, but are not
limited to, those in the following table. For a list of common error codes, see Common HRESULT Values.

RET URN C O DE/ VA L UE DESC RIP T IO N

The property value is empty.

CERTSRV_E_PROPERTY_EMPTY

There was insufficient memory available to create the URL

E_OUTOFMEMORY string.

The property value has not been initialized.

HRESULT_FROM_WIN32(OLE_E_BL ANK)

Remarks
The ID can be any string. It is set by the administrator who installs the CEP server.

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

 Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Target Platform Windows

Header certenroll.h

See also
ICertPropertyEnrollmentPolicyServer
 ICertPropertyEnrollmentPolicyServer::GetPolicyServerUrl
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The GetPolicySer verUrl method retrieves a string that contains the URL for the certificate enrollment policy
(CEP) server. This value is set by the Initialize method.

Syntax
HRESULT GetPolicyServerUrl(
[out, retval] BSTR *pValue
);

Parameters
[out, retval] pValue

Pointer to a BSTR that receives the URL.

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. Possible values include, but are not
limited to, those in the following table. For a list of common error codes, see Common HRESULT Values.

RET URN C O DE/ VA L UE DESC RIP T IO N

The property value is empty.

CERTSRV_E_PROPERTY_EMPTY

There was insufficient memory available to create the URL

E_OUTOFMEMORY string.

The property value has not been initialized.

HRESULT_FROM_WIN32(OLE_E_BL ANK)

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Target Platform Windows

Header certenroll.h
See also
ICertPropertyEnrollmentPolicyServer
 ICertPropertyEnrollmentPolicyServer::GetPropertyFlags
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The GetProper tyFlags method retrieves a value that specifies the default policy server URL. This value is set by
the Initialize method.

Syntax
HRESULT GetPropertyFlags(
[out, retval] EnrollmentPolicyServerPropertyFlags *pValue
);

Parameters
[out, retval] pValue

Pointer to an EnrollmentPolicyServerPropertyFlags enumeration value that contains the flag. This can be one of
the following values.

VA L UE M EA N IN G

No default policy server URL has been specified.

DefaultNone

The policy server URL returned by GetPolicyServerUrl is the

DefaultPolicySer ver default value when an URL has not been specified.

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. Possible values include, but are not
limited to, those in the following table. For a list of common error codes, see Common HRESULT Values.

RET URN C O DE/ VA L UE DESC RIP T IO N

The pValue parameter cannot be NULL .

E_POINTER

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]
 Target Platform Windows

Header certenroll.h

See also
ICertPropertyEnrollmentPolicyServer
 ICertPropertyEnrollmentPolicyServer::GetRequestIdString
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The GetRequestIdString method retrieves a unique string identifier for the certificate request sent to the
certification authority during enrollment.

Syntax
HRESULT GetRequestIdString(
[out, retval] BSTR *pValue
);

Parameters
[out, retval] pValue

Pointer to a BSTR that receives the ID string.

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. Possible values include, but are not
limited to, those in the following table. For a list of common error codes, see Common HRESULT Values.

RET URN C O DE/ VA L UE DESC RIP T IO N

The property value is empty.

CERTSRV_E_PROPERTY_EMPTY

There was insufficient memory available to create the URL

E_OUTOFMEMORY string.

The property value has not been initialized.

HRESULT_FROM_WIN32(OLE_E_BL ANK)

Remarks
The string can contain any information that uniquely identifies the certificate request. This value is set when you
call the Initialize method.

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]
 Target Platform Windows

Header certenroll.h

See also
ICertPropertyEnrollmentPolicyServer
 ICertPropertyEnrollmentPolicyServer::GetUrlFlags
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The GetUrlFlags method retrieves a set of flags that contain miscellaneous policy information about the
certificate enrollment policy (CEP) server. These flags are set by the Initialize method.

Syntax
HRESULT GetUrlFlags(
[out, retval] PolicyServerUrlFlags *pValue
);

Parameters
[out, retval] pValue

Pointer to a PolicyServerUrlFlags enumeration value that specifies the policy server flags. This can be a bitwise
OR of the following values.

VA L UE M EA N IN G

No flags are specified.

PsfNone

The policy server URL is specified in group policy by an

PsfLocationGroupPolicy administrator.

The policy server URL is specified in the registry.

PsfLocationRegistr y

Specifies that certificate enrollments and renewals include

PsfUseClientId client specific data. Examples include the name of the
cryptographic service provider, the Windows version
number, the user name, the computer DNS name, and the
domain controller DNS name. This flag is set when it is
defined in group policy and is the default policy ID.

Automatic certificate enrollment is enabled.

PsfAutoEnrollmentEnabled

Specifies that the certificate of the issuing CA need not be

PsfAllowUnTrustedCA trusted by the client to install a certificate signed by the CA.

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. Possible values include, but are not
limited to, those in the following table. For a list of common error codes, see Common HRESULT Values.

RET URN C O DE/ VA L UE DESC RIP T IO N

The pValue parameter cannot be NULL .

E_POINTER

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Target Platform Windows

Header certenroll.h

See also
ICertPropertyEnrollmentPolicyServer
 ICertPropertyEnrollmentPolicyServer::Initialize
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Initialize method initializes an ICertPropertyEnrollmentPolicyServer object.

Syntax
HRESULT Initialize(
[in] EnrollmentPolicyServerPropertyFlags PropertyFlags,
[in] X509EnrollmentAuthFlags AuthFlags,
[in] X509EnrollmentAuthFlags EnrollmentServerAuthFlags,
[in] PolicyServerUrlFlags UrlFlags,
[in] BSTR strRequestId,
[in] BSTR strUrl,
[in] BSTR strId,
[in] BSTR strEnrollmentServerUrl
);

Parameters
[in] PropertyFlags

An EnrollmentPolicyServerPropertyFlags enumeration value that specifies the default certificate enrollment

policy (CEP) server. This can be one of the following values.

VA L UE M EA N IN G

No default policy server URL has been specified.

DefaultNone

The policy server URL returned by GetPolicyServerUrl is the

DefaultPolicySer ver default value when an URL has not been specified.

[in] AuthFlags

An X509EnrollmentAuthFlags enumeration value that specifies the authentication type used by the client to
authenticate itself to the CEP server. This can be one of the following values.

VA L UE M EA N IN G

Anonymous authentication.
X509AuthAnonymous

Kerberos authentication.
X509AuthKerberos
 Clear text user name and password authentication.
X509AuthUsername
Note The user name and password are encrypted before
transmission and are stored securely in the credential vault
on the server.

Client authentication certificate installed on the local

X509AuthCer tificate computer and used by the server to verify the identity of the
client.

[in] EnrollmentServerAuthFlags

An X509EnrollmentAuthFlags enumeration value that specifies the authentication type used by the client to
authenticate itself to the CES. See the AuthFlags parameter for the possible values of the enumeration type. For
Windows 7, only X509AuthCer tificate can be specified.
[in] UrlFlags

A PolicyServerUrlFlags enumeration value that specifies policy server flags. This can be a bitwise OR of the
following values.

VA L UE M EA N IN G

No flags are specified.

PsfNone

The policy server URL is specified in group policy by an

PsfLocationGroupPolicy administrator.

The policy server URL is specified in the registry.

PsfLocationRegistr y

Specifies that certificate enrollments and renewals include

PsfUseClientId client specific data in a ClientId attribute. Examples include
the name of the cryptographic service provider, the
Windows version number, the user name, the computer DNS
name, and the domain controller DNS name.
This flag has been included to address privacy concerns
that can arise during enrollment to servers that are
managed by administrators other than those who
manage the forest in which the user resides. By not
setting this flag, you can prevent sending personal
information to non-local administrators.

Automatic certificate enrollment is enabled.

PsfAutoEnrollmentEnabled

Specifies that the certificate of the issuing CA need not be

PsfAllowUnTrustedCA trusted by the client to install a certificate signed by the CA.

[in] strRequestId

A BSTR variable that contains a unique string identifier for the certificate request to be sent to the certification
authority during enrollment. The string can contain any information that uniquely identifies the request.
[in] strUrl

A BSTR variable that contains the URL for the certificate enrollment policy (CEP) server.
[in] strId

A BSTR variable that contains the ID of the CEP server.

[in] strEnrollmentServerUrl

A BSTR variable that contains the URL for the certificate enrollment server.

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. Possible values include, but are not
limited to, those in the following table. For a list of common error codes, see Common HRESULT Values.

RET URN C O DE DESC RIP T IO N

There was insufficient memory available to a string value.

E_OUTOFMEMORY

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Target Platform Windows

Header certenroll.h

See also
ICertPropertyEnrollmentPolicyServer
 ICertPropertyFriendlyName interface (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The ICer tProper tyFriendlyName interface enables you to specify and retrieve a string that contains the
display name of a certificate.
This property is initialized during the enrollment process and associated with the dummy certificate that is
temporarily copied to the request store. If the CA denies the certificate request, the dummy certificate in the
request store and all properties associated with it are deleted. If the CA issues the certificate and it is installed in
the certificate store, this property is associated with the new certificate in the personal store and the dummy
certificate is deleted.

Note The CERTENROLL_PROPERTYID value is XCN_CERT_FRIENDLY_NAME_PROP_ID.

Inheritance
The ICer tProper tyFriendlyName interface inherits from ICertProperty. ICer tProper tyFriendlyName also
has these types of members:

Methods
The ICer tProper tyFriendlyName interface has these methods.

ICertPropertyFriendlyName::get_FriendlyName

Retrieves the display name of the certificate.

ICertPropertyFriendlyName::Initialize

Initializes the object from the certificate display name.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

See also
ICertProperties
ICertProperty
ICertPropertyDescription
 ICertPropertyFriendlyName::get_FriendlyName
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The FriendlyName property retrieves the display name of the certificate.

This property is read-only.

Syntax
HRESULT get_FriendlyName(
BSTR *pValue
);

Parameters
pValue

Return value
None

Remarks
Call the Initialize method to create a description.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
ICertProperties
ICertProperty
ICertPropertyDescription
ICertPropertyFriendlyName
 ICertPropertyFriendlyName::Initialize method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Initialize method initializes the object from the certificate display name. This method is web enabled.

Syntax
HRESULT Initialize(
[in] BSTR strFriendlyName
);

Parameters
[in] strFriendlyName

A BSTR variable that contains the name. The string length cannot exceed 260 characters.

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. Possible values include, but are not
limited to, those in the following table. For a list of common error codes, see Common HRESULT Values.

RET URN C O DE/ VA L UE DESC RIP T IO N

The object is already initialized.

HRESULT_FROM_WIN32(ERROR_ALREADY_INITIALIZE
D)

The string length exceeds 260 characters.

HRESULT_FROM_WIN32(ERROR_FILENAME_EXCED_R
ANGE)

Remarks
Typically, you specify the display name in a user interface or from the command line before beginning the
enrollment process so that the name can be associated with the dummy certificate in the request store. To
retrieve that value and use it here, call the CertificateFriendlyName on the IX509Enrollment interface.
Call the SetValueOnCertificate method to associate the property with a certificate. Call the FriendlyName
property to retrieve the display name.

Requirements
 Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
ICertProperties
ICertProperty
ICertPropertyDescription
ICertPropertyFriendlyName
 ICertPropertyKeyProvInfo interface (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The ICer tProper tyKeyProvInfo interface represents a certificate property that contains information about a
private key. The key information is contained in an IX509PrivateKey object.
This property is typically initialized by the enrollment process and associated with the dummy certificate that is
temporarily copied to the request store. If the certification authority marks the request pending after it is
submitted, autoenrollment can later use the request ID to retrieve the certificate response. If the certification
authority denies the certificate request, the dummy certificate in the request store and all properties associated
with it are deleted. If the certification authority issues the certificate and it is installed in the personal store, this
property is associated with the new certificate and the dummy certificate is deleted.
When a smart card is inserted, the smart card certificate is automatically installed in the personal store and this
property is associated with it.
Use this property whenever you need to retrieve the private key to perform a cryptographic operation.

Note The CERTENROLL_PROPERTYID value is XCN_CERT_KEY_PROV_INFO_PROP_ID.

Inheritance
The ICer tProper tyKeyProvInfo interface inherits from ICertProperty. ICer tProper tyKeyProvInfo also has
these types of members:

Methods
The ICer tProper tyKeyProvInfo interface has these methods.

ICertPropertyKeyProvInfo::get_PrivateKey

Retrieves the private key associated with the certificate.

ICertPropertyKeyProvInfo::Initialize

Initializes the object from a private key.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

 Header certenroll.h

See also
CertEnroll Interfaces
ICertProperty
 ICertPropertyKeyProvInfo::get_PrivateKey method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The PrivateKey property retrieves the private key associated with the certificate.
This property is read-only.

Syntax
HRESULT get_PrivateKey(
IX509PrivateKey **ppValue
);

Parameters
ppValue

Return value
None

Remarks
Call the Initialize method to create a description.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
ICertProperty
ICertPropertyKeyProvInfo
 ICertPropertyKeyProvInfo::Initialize method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Initialize method initializes the object from a private key.

Syntax
HRESULT Initialize(
[in] IX509PrivateKey *pValue
);

Parameters
[in] pValue

Pointer to an IX509PrivateKey interface that represents the private key.

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. Possible values include, but are not
limited to, those in the following table. For a list of common error codes, see Common HRESULT Values.

RET URN C O DE/ VA L UE DESC RIP T IO N

The IX509PrivateKey pointer is NULL .

CERTSRV_E_PROPERTY_EMPTY

The unique container name and the provider name are too
ERROR_ARITHMETIC_OVERFLOW long.

Remarks
Call the SetValueOnCertificate method to associate the property with a certificate. Call the PrivateKey property
to retrieve the key.
The Initialize method opens the private key and verifies that the following IX509PrivateKey properties are set:
CspInformations
ContainerName
UniqueContainerName
ProviderType
KeySpec
MachineContext

Requirements
 Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
ICertProperty
ICertPropertyKeyProvInfo
 ICertPropertyRenewal interface (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The ICer tProper tyRenewal interface represents a certificate property that contains a SHA-1 hash of the new
certificate created when an existing certificate is renewed. This property is associated with the old certificate to
identify the new certificate that replaces it. Typically, the SHA-1 hash is referred to as the thumb print of a
certificate.
This property is initialized by the enrollment process after the client requests that a certificate be renewed. If a
new certificate is issued, the property is associated with the old certificate in the personal store.

Note The CERTENROLL_PROPERTYID value is XCN_CERT_RENEWAL_PROP_ID.

Inheritance
The ICer tProper tyRenewal interface inherits from ICertProperty. ICer tProper tyRenewal also has these
types of members:

Methods
The ICer tProper tyRenewal interface has these methods.

ICertPropertyRenewal::get_Renewal

Retrieves the SHA-1 hash of the new certificate.

ICertPropertyRenewal::Initialize

Initializes the object from a SHA-1 hash of the new certificate.

ICertPropertyRenewal::InitializeFromCertificateHash

Initializes the object from the new certificate.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h
See also
CertEnroll Interfaces
ICertProperty
 ICertPropertyRenewal::get_Renewal method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Renewal property retrieves the SHA-1 hash of the new certificate. The hash is returned in a byte array , and
the byte array is represented by a Unicode encoded string.
This property is read-only.

Syntax
HRESULT get_Renewal(
EncodingType Encoding,
BSTR *pValue
);

Parameters
Encoding

pValue

Return value
None

Remarks
Call the Initialize method or the InitializeFromCertificateHash method to specify a value for the Renewal
property.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
ICertPropertyRenewal
 ICertPropertyRenewal::Initialize method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Initialize method initializes the object from a SHA-1 hash of the new certificate.

Syntax
HRESULT Initialize(
[in] EncodingType Encoding,
[in] BSTR strRenewalValue
);

Parameters
[in] Encoding

An EncodingType enumeration value that specifies the type of Unicode encoding applied to the input string that
contains the hash.
[in] strRenewalValue

A BSTR variable that contains the hash.

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. Possible values include, but are not
limited to, those in the following table. For a list of common error codes, see Common HRESULT Values.

RET URN C O DE/ VA L UE DESC RIP T IO N

The object is already initialized.

HRESULT_FROM_WIN32(ERROR_ALREADY_INITIALIZE
D)

Remarks
Typically this property is initialized during the enrollment process. You can retrieve the certificate used during
enrollment by calling the Certificate property on the IX509Enrollment interface.
Call the SetValueOnCertificate method to associate the property with a certificate. Call the Renewal property to
retrieve the hash.

Requirements
 Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
ICertPropertyRenewal
 ICertPropertyRenewal::InitializeFromCertificateHash
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The InitializeFromCer tificateHash method initializes the object from the new certificate.

Syntax
HRESULT InitializeFromCertificateHash(
[in] VARIANT_BOOL MachineContext,
[in] EncodingType Encoding,
[in] BSTR strCertificate
);

Parameters
[in] MachineContext

A VARIANT_BOOL value that indicates whether the certificate store is for the local computer or the current
user. Specify VARIANT_TRUE for the computer and VARIANT_FALSE for the user.
[in] Encoding

An EncodingType enumeration value that specifies the type of Unicode encoding applied to the input string that
contains the DER-encoded certificate.
[in] strCertificate

A BSTR variable that contains the DER-encoded certificate.

Beginning with Windows 7 and Windows Server 2008 R2, you can specify a certificate thumb print or serial
number rather than an encoded certificate. Doing so causes the function to search the appropriate local stores
for the matching certificate. Keep in mind the following points:
The BSTR must be an even number of hexadecimal digits.
Whitespace between hexadecimal pairs is ignored.
The Encoding parameter must be set to XCN_CRYPT_STRING_HEXRAW .
The MachineContext parameter determines whether the user or computer stores or both are searched.
If a private key is needed, only the personal and request stores are searched.
If a private key is not needed, the root and intermediate CA stores are also searched.

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. Possible values include, but are not
limited to, those in the following table. For a list of common error codes, see Common HRESULT Values.

RET URN C O DE/ VA L UE DESC RIP T IO N

 The object is already initialized.
HRESULT_FROM_WIN32(ERROR_ALREADY_INITIALIZE
D)

Remarks
This method creates a SHA-1 hash by using the specified certificate. The certificate must be encoded by using
Distinguished Encoding Rules (DER) as defined by the Abstract Syntax Notation One (ASN.1) standard. You must
also specify the type of Unicode encoding applied to the string that contains the DER-encoded certificate.
Typically the ICertPropertyRenewal object is initialized during the enrollment process. You can retrieve the
certificate used during enrollment by calling the Certificate property on the IX509Enrollment interface.
Call the SetValueOnCertificate method to associate the property with a certificate. Call the Renewal property to
retrieve the hash.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
ICertPropertyRenewal
 ICertPropertyRequestOriginator interface
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The ICer tProper tyRequestOriginator interface represents a certificate property that contains the Domain
Naming System (DNS) name of the computer on which the request was created. This property exists to reduce
the potential for race conditions when using auto-enrollment to renew a certificate. Auto-enrollment attempts to
renew a certificate that exists on the originating computer when the potential renewal period begins. Other
computers on which that certificate is also installed and for which this property is set wait to determine whether
that renewal attempt is successful. If the originating computer successfully enrolls and the new certificate is
roamed to the other computers in a timely manner, the other computers will not attempt to enroll.

Note The CERTENROLL_PROPERTYID value is XCN_CERT_REQUEST_ORIGINATOR_PROP_ID.

Inheritance
The ICer tProper tyRequestOriginator interface inherits from ICertProperty.
ICer tProper tyRequestOriginator also has these types of members:

Methods
The ICer tProper tyRequestOriginator interface has these methods.

ICertPropertyRequestOriginator::get_RequestOriginator

Retrieves a string that contains the DNS name of the originating computer.

ICertPropertyRequestOriginator::Initialize

Initializes the object from a string that contains the DNS name of the originating computer.

ICertPropertyRequestOriginator::InitializeFromLocalRequestOriginator

Initializes the object from the DNS name of the local computer.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

 Header certenroll.h

See also
CertEnroll Interfaces
ICertProperty
 ICertPropertyRequestOriginator::get_RequestOriginator
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The RequestOriginator property retrieves a string that contains the DNS name of the originating computer.
This property is read-only.

Syntax
HRESULT get_RequestOriginator(
BSTR *pValue
);

Parameters
pValue

Return value
None

Remarks
Call the Initialize method or the InitializeFromLocalRequestOriginator method to specify a value for the
RequestOriginator property.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
ICertPropertyRequestOriginator
 ICertPropertyRequestOriginator::Initialize method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Initialize method initializes the object from a string that contains the DNS name of the originating
computer.

Syntax
HRESULT Initialize(
[in] BSTR strRequestOriginator
);

Parameters
[in] strRequestOriginator

A BSTR variable that contains the name.

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. Possible values include, but are not
limited to, those in the following table. For a list of common error codes, see Common HRESULT Values.

RET URN C O DE/ VA L UE DESC RIP T IO N

The object is already initialized.

HRESULT_FROM_WIN32(ERROR_ALREADY_INITIALIZE
D)

Remarks
Call the SetValueOnCertificate method to associate the property with a certificate. Call the RequestOriginator
property to retrieve the DNS name of the originating computer.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h
 DLL CertEnroll.dll

See also
ICertPropertyRequestOriginator
 ICertPropertyRequestOriginator::InitializeFromLocalRequestOriginator
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The InitializeFromLocalRequestOriginator method initializes the object from the DNS name of the local
computer.

Syntax
HRESULT InitializeFromLocalRequestOriginator();

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.

Remarks
Call the SetValueOnCertificate method to associate the property with a certificate. Call the RequestOriginator
property to retrieve the DNS name of the originating computer.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
ICertPropertyRequestOriginator
 ICertPropertySHA1Hash interface (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The ICer tProper tySHA1Hash interface represents a certificate property that contains a SHA-1 hash of the
certificate. The hash functions as a unique identifier. Typically, it is called a thumb print.

Note The CERTENROLL_PROPERTYID value is XCN_CERT_SHA1_HASH_PROP_ID.

Inheritance
The ICer tProper tySHA1Hash interface inherits from ICertProperty. ICer tProper tySHA1Hash also has these
types of members:

Methods
The ICer tProper tySHA1Hash interface has these methods.

ICertPropertySHA1Hash::get_SHA1Hash

Retrieves the SHA-1 hash of a certificate.

ICertPropertySHA1Hash::Initialize

Initializes the object from the SHA-1 hash of a certificate.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

See also
CertEnroll Interfaces
ICertProperty
 ICertPropertySHA1Hash::get_SHA1Hash method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The SHA1Hash property retrieves the SHA-1 hash of a certificate.

This property is read-only.

Syntax
HRESULT get_SHA1Hash(
EncodingType Encoding,
BSTR *pValue
);

Parameters
Encoding

pValue

Return value
None

Remarks
Call the Initialize method to specify a value for the SHA1Hash property.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
ICertPropertySHA1Hash
 ICertPropertySHA1Hash::Initialize method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Initialize method initializes the object from the SHA-1 hash of a certificate.

Syntax
HRESULT Initialize(
[in] EncodingType Encoding,
[in] BSTR strRenewalValue
);

Parameters
[in] Encoding

An EncodingType enumeration value that specifies the type of Unicode encoding applied to the input string that
contains the certificate hash.
[in] strRenewalValue

A BSTR variable that contains the hash.

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. Possible values include, but are not
limited to, those in the following table. For a list of common error codes, see Common HRESULT Values.

RET URN C O DE/ VA L UE DESC RIP T IO N

The object is already initialized.

HRESULT_FROM_WIN32(ERROR_ALREADY_INITIALIZE
D)

Remarks
Call the SetValueOnCertificate method to associate the property with a certificate. Call the SHA1Hash property
to retrieve the hash value.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]
 Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
ICertPropertySHA1Hash
 ICryptAttribute interface (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The ICr yptAttribute interface represents a cryptographic attribute in a certificate request. A collection of these
attributes is contained in the Cer tificateRequestInfo structure of a PKCS #10 request as shown by the
following example syntax.

CertificationRequestInfo ::= SEQUENCE

{
version CertificationRequestInfoVersion,
subject ANY,
subjectPublicKeyInfo SubjectPublicKeyInfo,
attributes [0] IMPLICIT Attributes
}

Attributes ::= SET OF Attribute

Attribute ::= SEQUENCE

{
type EncodedObjectID,
values AttributeSetValue
}

AttributeSetValue ::= SET OF ANY

A single ICr yptAttribute object corresponds to the attributes collection in the request. The ICr yptAttribute
object in turn contains a collection of IX509Attribute objects. Each attribute in this collection contains an object
identifier and one or more values. Each value is an encoded Abstract Syntax Notation One (ASN.1) structure.
Zero or more of the following objects can be included in the collection:
IX509AttributeClientId
IX509AttributeExtensions
IX509AttributeArchiveKey
IX509AttributeArchiveKeyHash
IX509AttributeCspProvider
IX509AttributeOSVersion
IX509AttributeRenewalCertificate

Inheritance
The ICr yptAttribute interface inherits from the IDispatch interface. ICr yptAttribute also has these types of
members:

Methods
The ICr yptAttribute interface has these methods.
 ICryptAttribute::get_ObjectId

Retrieves the object identifier (OID) for the attribute.

ICryptAttribute::get_Values

Retrieves an IX509Attributes object that contains a collection of attributes.

ICryptAttribute::InitializeFromObjectId

Initializes a cryptographic attribute by using an object identifier.

ICryptAttribute::InitializeFromValues

Initializes a cryptographic attribute by using an IX509Attributes object.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

See also
ICryptAttribute
ICryptAttributes
IDispatch
IX509Attribute
IX509Attributes
 ICryptAttribute::get_ObjectId method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The ObjectId property retrieves the object identifier (OID) for the attribute.
This property is read-only.

Syntax
HRESULT get_ObjectId(
IObjectId **ppValue
);

Parameters
ppValue

Return value
None

Remarks
You can initialize an IObjectId object by calling InitializeFromName. This method initializes the object by using a
value from the CERTENROLL_OBJECTID enumeration. The enumeration value is associated with an ASN.1 object
identifier. For example, the value XCN_OID_COUNTRY_NAME is associated with a string containing 2.5.4.6.
This is the dotted decimal representation of the joint-iso-itu-t(2)ds(5)attributeType(4)countryName(6) object
identifier.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
ICryptAttribute
ICryptAttributes
IX509Attribute
IX509Attributes
 ICryptAttribute::get_Values method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Values property retrieves an IX509Attributes object that contains a collection of attributes.
This property is read-only.

Syntax
HRESULT get_Values(
IX509Attributes **ppValue
);

Parameters
ppValue

Return value
None

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
ICryptAttribute
ICryptAttributes
IX509Attribute
IX509Attributes
 ICryptAttribute::InitializeFromObjectId method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The InitializeFromObjectId method initializes a cryptographic attribute by using an object identifier.

Syntax
HRESULT InitializeFromObjectId(
[in] IObjectId *pObjectId
);

Parameters
[in] pObjectId

Pointer to an IObjectId interface that contains the object identifier of the attribute.

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. Possible values include, but are not
limited to, those in the following table. For a list of common error codes, see Common HRESULT Values.

RET URN C O DE/ VA L UE DESC RIP T IO N

The pointer to the IObjectId interface is NULL .

CERTSRV_E_PROPERTY_EMPTY

Remarks
You must initialize the IObjectId object by calling the InitializeFromName or InitializeFromValue methods before
using it in this method.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll
See also
ICryptAttribute
ICryptAttributes
IX509Attribute
IX509Attributes
 ICryptAttribute::InitializeFromValues method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The InitializeFromValues method initializes a cryptographic attribute by using an IX509Attributes object.

Syntax
HRESULT InitializeFromValues(
[in] IX509Attributes *pAttributes
);

Parameters
[in] pAttributes

Pointer to an IX509Attributes interface that contains the attribute collection.

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.

Remarks
The InitializeFromValues method uses the first IX509Attribute object in the collection.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
ICryptAttribute
ICryptAttributes
IX509Attribute
IX509Attributes
 ICryptAttributes interface (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The ICr yptAttributes interface contains methods and properties that enable you to manage a collection of
ICryptAttribute objects.

Inheritance
The ICr yptAttributes interface inherits from the IDispatch interface. ICr yptAttributes also has these types of
members:

Methods
The ICr yptAttributes interface has these methods.

ICryptAttributes::Add

Adds an ICryptAttribute object to the collection.

ICryptAttributes::AddRange

Adds a range of ICryptAttribute objects to the collection. The attributes are contained in another ICryptAttributes collection.

ICryptAttributes::Clear

Removes all ICryptAttribute objects from the collection.

ICryptAttributes::get__NewEnum

Retrieves the enumerator for the collection.

ICryptAttributes::get_Count

Retrieves the number of ICryptAttribute objects in the collection.

ICryptAttributes::get_IndexByObjectId

Retrieves the index of an attribute by object identifier (OID).

ICryptAttributes::get_ItemByIndex

Retrieves an ICryptAttribute object from the collection by index number.

ICryptAttributes::Remove

Removes an ICryptAttribute object from the collection by index number.

Requirements
 Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

See also
CertEnroll Interfaces
IDispatch
 ICryptAttributes::Add method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Add method adds an ICryptAttribute object to the collection.

Syntax
HRESULT Add(
[in] ICryptAttribute *pVal
);

Parameters
[in] pVal

Pointer to an ICryptAttribute interface that represents the attribute to add.

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
ICryptAttribute
ICryptAttributes
IX509Attribute
IX509AttributeExtensions
IX509Attributes
 ICryptAttributes::AddRange method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The AddRange method adds a range of ICryptAttribute objects to the collection. The attributes are contained in
another ICryptAttributes collection.

Syntax
HRESULT AddRange(
[in] ICryptAttributes *pValue
);

Parameters
[in] pValue

Pointer to an ICryptAttributes interface that contains the attribute collection to add.

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
ICryptAttribute
ICryptAttributes
IX509Attribute
IX509AttributeExtensions
IX509Attributes
 ICryptAttributes::Clear method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Clear method removes all ICryptAttribute objects from the collection.

Syntax
HRESULT Clear();

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
ICryptAttribute
ICryptAttributes
IX509Attribute
IX509AttributeExtensions
IX509Attributes
 ICryptAttributes::get__NewEnum method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The _NewEnum property retrieves the enumerator for the collection.

This property is read-only.

Syntax
HRESULT get__NewEnum(
LPUNKNOWN *pVal
);

Parameters
pVal

Return value
None

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
ICryptAttribute
ICryptAttributes
IX509Attribute
IX509AttributeExtensions
IX509Attributes
 ICryptAttributes::get_Count method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Count property retrieves the number of ICryptAttribute objects in the collection.
This property is read-only.

Syntax
HRESULT get_Count(
long *pVal
);

Parameters
pVal

Return value
None

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
ICryptAttribute
ICryptAttributes
IX509Attribute
IX509AttributeExtensions
IX509Attributes
 ICryptAttributes::get_IndexByObjectId method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The IndexByObjectId property retrieves the index of an attribute by object identifier (OID).
This property is read-only.

Syntax
HRESULT get_IndexByObjectId(
IObjectId *pObjectId,
LONG *pIndex
);

Parameters
pObjectId

pIndex

Return value
None

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
ICryptAttribute
ICryptAttributes
IX509Attribute
IX509AttributeExtensions
IX509Attributes
 ICryptAttributes::Remove method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Remove method removes an ICryptAttribute object from the collection by index number.

Syntax
HRESULT Remove(
[in] LONG Index
);

Parameters
[in] Index

A LONG variable that contains the index of the object to remove.

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
ICryptAttribute
ICryptAttributes
IX509Attribute
IX509AttributeExtensions
IX509Attributes
 ICspAlgorithm interface (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The ICspAlgorithm interface represents an algorithm implemented by a cryptographic provider. Providers are
separate modules that implement encryption, hashing, signing, and key exchange (archival) algorithms. Similar
providers are grouped together in a type. For example, the PROV_RSA_FULL type identifies providers that
typically support the following algorithms. An individual provider can, however, choose to support fewer or
more algorithms than those listed.
Encryption: RC2, RC4
Hashing: MD5, SHA
Key Exchange: RSA
Signature: RSA
For more information, see Microsoft Cryptographic Service Providers.
A collection of ICspAlgorithm objects can be retrieved from an ICspInformation object. The ICspInformation
object can be initialized from a provider name or type.

Inheritance
The ICspAlgorithm interface inherits from the IDispatch interface. ICspAlgorithm also has these types of
members:

Methods
The ICspAlgorithm interface has these methods.

ICspAlgorithm::get_DefaultLength

Retrieves the default length of a key.

ICspAlgorithm::get_IncrementLength

Retrieves a value, in bits, that can be used to determine valid incremental key lengths for algorithms that support multiple key
sizes.

ICspAlgorithm::get_LongName

Retrieves the full name of the algorithm.

ICspAlgorithm::get_MaxLength

Retrieves the maximum permitted length for a key.

ICspAlgorithm::get_MinLength

Retrieves the minimum permitted length for a key.

 ICspAlgorithm::get_Name

Retrieves the abbreviated algorithm name.

ICspAlgorithm::get_Operations

Retrieves the operations that can be performed by the algorithm.

ICspAlgorithm::get_Type

Retrieves the algorithm type.

ICspAlgorithm::get_Valid

Retrieves a Boolean value that specifies whether the algorithm object is valid.

ICspAlgorithm::GetAlgorithmOid

Retrieves the algorithm object identifier (OID). This method is web enabled.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

See also
CertEnroll Interfaces
Cryptographic Service Providers
IDispatch
 ICspAlgorithm::get_DefaultLength method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The DefaultLength property retrieves the default length of a key. This property is web enabled.
This property is read-only.

Syntax
HRESULT get_DefaultLength(
LONG *pValue
);

Parameters
pValue

Return value
None

Remarks
You can use this property to retrieve the default size, in bits, of a key. The DefaultLength , IncrementLength,
MaxLength, and MinLength properties can vary by algorithm and provider. The following table lists a few
algorithms for which multiple key sizes can be set. The list is not inclusive.

A L GO RIT H M O ID C RY P TO GRA P H IC P RO VIDER K EY L EN GT H ( B IT S)

XCN_OID_RSA_RSA(1.2.840.113549.1. Microsoft Smart Card Key Storage Minimum: 1,024

1.1) Provider Maximum: 4,096
Microsoft Base Smart Card Crypto
Provider Default: 1,024
Increment: 512
XCN_OID_RSA_RSA(1.2.840.113549.1. Microsoft Software Key Storage Minimum: 384
1.1) Provider Maximum: 16,384
Microsoft Base Cryptographic
Provider v1.0 Default: 1,024

Microsoft Enhanced Cryptographic Increment: 8

Provider v1.0
Microsoft Enhanced RSA and AES
Cryptographic Provider
Microsoft RSA Schannel
Cryptographic Provider
Microsoft Strong Cryptographic
Provider

XCN_OID_X957_DSA(1.2.840.10040.4. Microsoft Software Key Storage Minimum: 512

1) Provider Maximum: 1,024
Microsoft Base DSS and Diffie-
Hellman Cryptographic Provider Default: 1,024

Microsoft Base DSS Cryptographic Increment: 64

Provider
Microsoft DH Schannel
Cryptographic Provider
Microsoft Enhanced DSS and
Diffie-Hellman Cryptographic
Provider

XCN_OID_ANSI_X942_DH(1.2.840.100 Diffie-Hellman key exchange algorithm. Minimum: 512

46.2.1) Maximum: 1,024
Default: 1,024
Increment: 64

XCN_OID_ANSI_X942_DH(1.2.840.100 Microsoft DH Schannel Cryptographic Minimum: 512

46.2.1) Provider Maximum: 4,096
Microsoft Enhanced DSS and
Diffie-Hellman Cryptographic Default: 1,024
Provider Increment: 64
 XCN_OID_RSA_RC2CBC(1.2.840.11354 Microsoft Software Key Storage Minimum: 40
9.3.2) Provider Maximum: 128
Microsoft Smart Card Key Storage
Provider Default: 128

Microsoft Base Smart Card Crypto Increment: 8

Provider
Microsoft DH Schannel
Cryptographic Provider
Microsoft Enhanced Cryptographic
Provider v1.0
Microsoft Enhanced DSS and
Diffie-Hellman Cryptographic
Provider
Microsoft Enhanced RSA and AES
Cryptographic Provider
Microsoft RSA Schannel
Cryptographic Provider
Microsoft Strong Cryptographic
Provider

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
ICspAlgorithm
IncrementLength
 ICspAlgorithm::get_IncrementLength method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The IncrementLength property retrieves a value, in bits, that can be used to determine valid incremental key
lengths for algorithms that support multiple key sizes. This property is web enabled.
This property is read-only.

Syntax
HRESULT get_IncrementLength(
LONG *pValue
);

Parameters
pValue

Return value
None

Remarks
You can use the value of this property to determine valid key sizes for generated keys. For example, if the
minimum key length of a DSA signing key is 512 bits, the maximum length is 1,024 bits, and the increment is 64
bits, valid key sizes include 512, 576, 640 and so in 64 bit increments up to 1,024.
The DefaultLength, IncrementLength , MaxLength, and MinLength properties can vary by algorithm and
provider. The following table lists a few algorithms for which multiple key sizes can be set. The list is not
inclusive.

A L GO RIT H M O ID C RY P TO GRA P H IC P RO VIDER K EY L EN GT H ( B IT S)

XCN_OID_RSA_RSA(1.2.840.113549.1. Microsoft Smart Card Key Storage Minimum: 1,024

1.1) Provider Maximum: 4,096
Microsoft Base Smart Card Crypto
Provider Default: 1,024
Increment: 512
XCN_OID_RSA_RSA(1.2.840.113549.1. Microsoft Software Key Storage Minimum: 384
1.1) Provider Maximum: 16,384
Microsoft Base Cryptographic
Provider v1.0 Default: 1,024

Microsoft Enhanced Cryptographic Increment: 8

Provider v1.0
Microsoft Enhanced RSA and AES
Cryptographic Provider
Microsoft RSA Schannel
Cryptographic Provider
Microsoft Strong Cryptographic
Provider

XCN_OID_X957_DSA(1.2.840.10040.4. Microsoft Software Key Storage Minimum: 512

1) Provider Maximum: 1,024
Microsoft Base DSS and Diffie-
Hellman Cryptographic Provider Default: 1,024

Microsoft Base DSS Cryptographic Increment: 64

Provider
Microsoft DH Schannel
Cryptographic Provider
Microsoft Enhanced DSS and
Diffie-Hellman Cryptographic
Provider

XCN_OID_ANSI_X942_DH(1.2.840.100 Diffie-Hellman key exchange algorithm. Minimum: 512

46.2.1) Maximum: 1,024
Default: 1,024
Increment: 64

XCN_OID_ANSI_X942_DH(1.2.840.100 Microsoft DH Schannel Cryptographic Minimum: 512

46.2.1) Provider Maximum: 4,096
Microsoft Enhanced DSS and
Diffie-Hellman Cryptographic Default: 1,024
Provider Increment: 64
 XCN_OID_RSA_RC2CBC(1.2.840.11354 Microsoft Software Key Storage Minimum: 40
9.3.2) Provider Maximum: 128
Microsoft Smart Card Key Storage
Provider Default: 128

Microsoft Base Smart Card Crypto Increment: 8

Provider
Microsoft DH Schannel
Cryptographic Provider
Microsoft Enhanced Cryptographic
Provider v1.0
Microsoft Enhanced DSS and
Diffie-Hellman Cryptographic
Provider
Microsoft Enhanced RSA and AES
Cryptographic Provider
Microsoft RSA Schannel
Cryptographic Provider
Microsoft Strong Cryptographic
Provider

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
DefaultLength
ICspAlgorithm
 ICspAlgorithm::get_LongName method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The LongName property retrieves the full name of the algorithm.

This property is read-only.

Syntax
HRESULT get_LongName(
BSTR *pValue
);

Parameters
pValue

Return value
None

Remarks
The Name property retrieves a short algorithm name. Call the LongName property to retrieve a more
descriptive name. The names are not localized. Examples are shown in the following table.

Note Cryptography API: Next Generation (CNG) key storage providers (KSPs) do not support the long name concept. The
LongName property and Name property return an abbreviated name.

A L GO RIT H M O ID N A M E ( K SP A N D C SP ) LO N GN A M E ( K SP ) LO N GN A M E ( C SP )

XCN_OID_OIWSEC_desCBC( DES DES Data Encryption Standard

1.3.14.3.2.7) (DES)

XCN_OID_OIWSEC_sha1(1. SHA-1 SHA-1 Secure Hash Algorithm

3.14.3.2.26) (SHA-1)

XCN_OID_RSA_MD2(1.2.84 MD2 MD2 Message Digest 2 (MD2)

0.113549.2.2)

XCN_OID_RSA_RC2CBC(1.2. RC2 RC2 RSA Data Security's RC2

840.113549.3.2)

XCN_OID_ANSI_X942_DH(1 DH_KEYX DH_KEYX Diffie-Hellman Key

.2.840.10046.2.1) Exchange Algorithm
Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
ICspAlgorithm
 ICspAlgorithm::get_MaxLength method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The MaxLength property retrieves the maximum permitted length for a key. This property is web enabled.
This property is read-only.

Syntax
HRESULT get_MaxLength(
LONG *pValue
);

Parameters
pValue

Return value
None

Remarks
The DefaultLength, IncrementLength, MaxLength , and MinLength properties can vary by algorithm and
provider. The following table lists a few example maximum, minimum and default key sizes.

A L GO RIT H M O ID C RY P TO GRA P H IC P RO VIDER K EY L EN GT H ( B IT S)

XCN_OID_OIWSEC_desCBC Microsoft Base DSS and Diffie-Hellman Minimum: 56

(1.3.14.3.2.7) Cryptographic Provider Maximum: 56
Microsoft Enhanced Cryptographic
Provider v1.0 Default: 56

Microsoft DH Schannel
Cryptographic Provider
Microsoft Enhanced RSA and AES
Cryptographic Provider
 XCN_OID_RSA_DES_EDE3_CBC Microsoft Base DSS and Diffie-Hellman Minimum: 168
(1.2.840.113549.3.7) Cryptographic Provider Maximum: 168
Microsoft Enhanced Cryptographic
Provider v1.0 Default: 168

Microsoft DH Schannel
Cryptographic Provider
Microsoft Enhanced RSA and AES
Cryptographic Provider
Microsoft Exchange Cryptographic
Provider v1.0

XCN_OID_RSA_RSA Microsoft Enhanced Cryptographic Minimum: 384

(1.2.840.113549.1.1.1) Provider v1.0 Maximum: 16,384
Microsoft Enhanced RSA and AES
Cryptographic Provider Default: 1,024

Microsoft RSA Schannel Increment: 8

Cryptographic Provider
Microsoft Strong Cryptographic
Provider

XCN_OID_X957_DSA Microsoft Base DSS and Diffie-Hellman Minimum: 512

(1.2.840.10040.4.1) Cryptographic Provider Maximum: 1,024
Microsoft Base DSS Cryptographic
Provider Default: 1,024

Microsoft DH Schannel Increment: 64

Cryptographic Provider
Microsoft Enhanced DSS and
Diffie-Hellman Cryptographic
Provider

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
ICspAlgorithm
MinLength
 ICspAlgorithm::get_MinLength method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The MinLength property retrieves the minimum permitted length for a key. This property is web enabled.
This property is read-only.

Syntax
HRESULT get_MinLength(
LONG *pValue
);

Parameters
pValue

Return value
None

Remarks
The DefaultLength, IncrementLength, MaxLength, and MinLength properties can vary by algorithm and
provider. The following table lists a few example maximum, minimum and default key sizes.

A L GO RIT H M O ID C RY P TO GRA P H IC P RO VIDER K EY L EN GT H ( B IT S)

XCN_OID_OIWSEC_desCBC(1.3.14.3.2. Microsoft Base DSS and Diffie-Hellman Minimum: 56

7) Cryptographic Provider Maximum: 56
Microsoft Enhanced Cryptographic
Provider v1.0 Default: 56

Microsoft DH Schannel
Cryptographic Provider
Microsoft Enhanced RSA and AES
Cryptographic Provider

XCN_OID_RSA_DES_EDE3_CBC(1.2.840 Microsoft Base DSS and Diffie-Hellman Minimum: 168

.113549.3.7) Cryptographic Provider Maximum: 168
Microsoft Enhanced Cryptographic
Provider v1.0 Default: 168

Microsoft DH Schannel
Cryptographic Provider
Microsoft Enhanced RSA and AES
Cryptographic Provider
Microsoft Exchange Cryptographic
Provider v1.0
 XCN_OID_RSA_RSA(1.2.840.113549.1. Microsoft Enhanced Cryptographic Minimum: 384
1.1) Provider v1.0 Maximum: 16,384
Microsoft Enhanced RSA and AES
Cryptographic Provider Default: 1,024

Microsoft RSA Schannel Increment: 8

Cryptographic Provider
Microsoft Strong Cryptographic
Provider

XCN_OID_X957_DSA(1.2.840.10040.4. Microsoft Base DSS and Diffie-Hellman Minimum: 512

1) Cryptographic Provider Maximum: 1,024
Microsoft Base DSS Cryptographic
Provider Default: 1,024

Microsoft DH Schannel Increment: 64

Cryptographic Provider
Microsoft Enhanced DSS and
Diffie-Hellman Cryptographic
Provider

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
ICspAlgorithm
 ICspAlgorithm::get_Name method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Name property retrieves the abbreviated algorithm name. This property is web enabled.
This property is read-only.

Syntax
HRESULT get_Name(
BSTR *pValue
);

Parameters
pValue

Return value
None

Remarks
The Name property retrieves a shortened algorithm name. Call the LongName property to retrieve a more
descriptive name. The names are not localized. Examples are shown in the following table.

Note Cryptography API: Next Generation (CNG) key storage providers (KSPs) do not support the long name concept. The
LongName property and Name property return an abbreviated name.

A L GO RIT H M O ID N A M E ( K SP A N D C SP ) LO N GN A M E ( K SP ) LO N GN A M E ( C SP )

XCN_OID_OIWSEC_desCBC( DES DES Data Encryption Standard

1.3.14.3.2.7) (DES)

XCN_OID_OIWSEC_sha1(1. SHA-1 SHA-1 Secure Hash Algorithm

3.14.3.2.26) (SHA-1)

XCN_OID_RSA_MD2(1.2.84 MD2 MD2 Message Digest 2 (MD2)

0.113549.2.2)

XCN_OID_RSA_RC2CBC(1.2. RC2 RC2 RSA Data Security's RC2

840.113549.3.2)

XCN_OID_ANSI_X942_DH(1 DH_KEYX DH_KEYX Diffie-Hellman Key

.2.840.10046.2.1) Exchange Algorithm

Requirements
 Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
ICspAlgorithm
 ICspAlgorithm::get_Operations method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Operations property retrieves the operations that can be performed by the algorithm. This property is web
enabled.
This property is read-only.

Syntax
HRESULT get_Operations(
AlgorithmOperationFlags *pValue
);

Parameters
pValue

Return value
None

Remarks
The main difference between the Type property and the Operations property is that the latter contains a
bitfield in which multiple bits can be set. Because many algorithms can be used for multiple purposes, the
Operations property is often more useful. The Type value can correspond to only one of the Operations
value bits. For example, if the Operations property returns XCN_NCRYPT_SIGNATURE_OPERATION |
XCN_NCRYPT_ASYMMETRIC_ENCRYPTION_OPERATION, the Type property may return
XCN_BCRYPT_ASYMMETRIC_ENCRYPTION_INTERFACE.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
ICspAlgorithm
Type
 ICspAlgorithm::get_Type method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Type property retrieves the algorithm type. This property is web enabled.
This property is read-only.

Syntax
HRESULT get_Type(
AlgorithmType *pValue
);

Parameters
pValue

Return value
None

Remarks
The main difference between the Type property and the Operations property is that the latter contains a bitfield
in which multiple bits can be set. Because many algorithms can be used for multiple purposes, the Operations
property is often more useful. The Type value can correspond to only one of the Operations value bits. For
example, if the Operations property returns XCN_NCRYPT_SIGNATURE_OPERATION |
XCN_NCRYPT_ASYMMETRIC_ENCRYPTION_OPERATION, the Type property may return
XCN_BCRYPT_ASYMMETRIC_ENCRYPTION_INTERFACE.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
ICspAlgorithm
Operations
 ICspAlgorithm::get_Valid method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Valid property retrieves a Boolean value that specifies whether the algorithm object is valid.
This property is read-only.

Syntax
HRESULT get_Valid(
VARIANT_BOOL *pValue
);

Parameters
pValue

Return value
None

Remarks
If a template refers to an algorithm that is not supported by the specified cryptographic provider, the enrollment
process creates a placeholder ICspAlgorithm object, sets the Valid property to false, and sets the Name
property. No other property values are defined.
You must call the InitializeFromName method or the InitializeFromType method on the ICspInformation
interface before calling this property.
Abstract Syntax Notation One (ASN.1) is defined by the X.680 through X.683 standards. The Certificate
Enrollment API verifies an object identifier (OID) by Distinguished Encoding Rules (DER) encoding it and then
decoding the result to make certain that the OID remains unchanged and by checking that the following are
true:
The first number in the OID is either 0, 1, or 2.
All other characters are either digits (0 to 9) or periods (.).
No periods start or end the OID.
No consecutive characters are both periods.
The OID must contain at least one period.
If the first number is 0 or 1, the second number must be between 0 and 39 inclusive.
If the first number is 2, the second number can be any value.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

 Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
ICspAlgorithm
 ICspAlgorithm::GetAlgorithmOid method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The GetAlgorithmOid method retrieves the algorithm object identifier (OID). This method is web enabled.

Syntax
HRESULT GetAlgorithmOid(
[in] LONG Length,
[in] AlgorithmFlags AlgFlags,
[out] IObjectId **ppValue
);

Parameters
[in] Length

A LONG variable that identifies the required key size of the symmetric encryption algorithm. Use this parameter
to retrieve a specific AES algorithm from a Cryptography API: Next Generation (CNG) key storage provider
(KSP). A KSP may list only one algorithm named AES but support all of the AES variants in the following list:
szOID_NIST_AES128_CBC (2.16.840.1.101.3.4.1.2)
szOID_NIST_AES192_CBC (2.16.840.1.101.3.4.1.22)
szOID_NIST_AES256_CBC (2.16.840.1.101.3.4.1.42)
szOID_NIST_AES128_WRAP (2.16.840.1.101.3.4.1.5)
szOID_NIST_AES192_WRAP (2.16.840.1.101.3.4.1.25)
szOID_NIST_AES256_WRAP (2.16.840.1.101.3.4.1.45)
If you specify zero for the Length parameter and AlgorithmFlagsNone (0x00000000) for the AlgFlags
parameter, the OID associated with the default algorithm is retrieved. For the Microsoft Software KSP and the
Microsoft Smart Card KSP, the default AES algorithm is szOID_NIST_AES128_CBC (2.16.840.1.101.3.4.1.2).

Note This parameter must be zero for any algorithm other than a symmetric encryption algorithm.

[in] AlgFlags

An AlgorithmFlags enumeration value that specifies whether to search for a key wrapping algorithm. This can be
one of the following values:
AlgorithmFlagsNone
AlgorithmFlagsWrap
Specifying AlgorithmFlagsWrap causes this method to search for algorithms for which the display name ends
with "wrap". This includes the following OIDs:
szOID_NIST_AES128_WRAP (2.16.840.1.101.3.4.1.5)
szOID_NIST_AES192_WRAP (2.16.840.1.101.3.4.1.25)
 szOID_NIST_AES256_WRAP (2.16.840.1.101.3.4.1.45)
XCN_OID_RSA_SMIMEalgCMS3DESwrap (1.2.840.113549.1.9.16.3.6)
XCN_OID_RSA_SMIMEalgCMSRC2wrap (1.2.840.113549.1.9.16.3.7)
If you specify zero for the Length parameter and AlgorithmFlagsNone (0x00000000) for the AlgFlags
parameter, the OID associated with the default algorithm is retrieved. For the Microsoft Software KSP and the
Microsoft Smart Card KSP, the default AES algorithm is szOID_NIST_AES128_CBC (2.16.840.1.101.3.4.1.2).

Note This parameter must be zero for any algorithm other than a symmetric encryption algorithm.

[out] ppValue

Address of a variable that receives a pointer to an IObjectId interface that represents the algorithm OID.

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. Possible values include, but are not
limited to, those in the following table. For a list of common error codes, see Common HRESULT Values.

RET URN C O DE/ VA L UE DESC RIP T IO N

The algorithm OID could not be found.

CERTSRV_E_PROPERTY_EMPTY

The CSP information has not been initialized. For more

OLE_E_BL ANK information, see the ICspInformation interface.

Remarks
You must call the InitializeFromName method or the InitializeFromType method on the ICspInformation
interface before calling GetAlgorithmOid .

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
ICspAlgorithm
 ICspAlgorithms interface (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The ICspAlgorithms interface defines the following methods and properties that manage a collection of
ICspAlgorithm objects.

Inheritance
The ICspAlgorithms interface inherits from the IDispatch interface. ICspAlgorithms also has these types of
members:

Methods
The ICspAlgorithms interface has these methods.

ICspAlgorithms::Add

Adds an ICspAlgorithm object to the collection.

ICspAlgorithms::Clear

Removes all ICspAlgorithm objects from the collection.

ICspAlgorithms::get__NewEnum

Retrieves the enumerator for the collection.

ICspAlgorithms::get_Count

Retrieves the number of ICspAlgorithm objects in the collection.

ICspAlgorithms::get_IndexByObjectId

Retrieves the index of an ICspAlgorithm object by object identifier (OID).

ICspAlgorithms::get_ItemByIndex

Retrieves an ICspAlgorithm object from the collection by index number.

ICspAlgorithms::get_ItemByName

Retrieves an ICspAlgorithm object from the collection by name.

ICspAlgorithms::Remove

Removes an ICspAlgorithm object from the collection by index number.

Requirements
 Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

See also
CertEnroll Interfaces
IDispatch
 ICspAlgorithms::Add method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Add method adds an ICspAlgorithm object to the collection. This method is web enabled.

Syntax
HRESULT Add(
[in] ICspAlgorithm *pVal
);

Parameters
[in] pVal

Pointer to an ICspAlgorithm interface to add.

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
ICspAlgorithm
ICspAlgorithms
 ICspAlgorithms::Clear method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Clear method removes all ICspAlgorithm objects from the collection.

Syntax
HRESULT Clear();

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
ICspAlgorithm
ICspAlgorithms
 ICspAlgorithms::get__NewEnum method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The _NewEnum property retrieves the enumerator for the collection.

This property is read-only.

Syntax
HRESULT get__NewEnum(
LPUNKNOWN *pVal
);

Parameters
pVal

Return value
None

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
ICspAlgorithm
ICspAlgorithms
 ICspAlgorithms::get_Count method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Count property retrieves the number of ICspAlgorithm objects in the collection. This property is web
enabled.
This property is read-only.

Syntax
HRESULT get_Count(
long *pVal
);

Parameters
pVal

Return value
None

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
ICspAlgorithm
ICspAlgorithms
 ICspAlgorithms::get_IndexByObjectId method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The IndexByObjectId property retrieves the index of an ICspAlgorithm object by object identifier (OID).
This property is read-only.

Syntax
HRESULT get_IndexByObjectId(
IObjectId *pObjectId,
LONG *pIndex
);

Parameters
pObjectId

pIndex

Return value
None

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
ICspAlgorithm
ICspAlgorithms
 ICspAlgorithms::get_ItemByName method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The ItemByName property retrieves an ICspAlgorithm object from the collection by name. This property is web
enabled.
This property is read-only.

Syntax
HRESULT get_ItemByName(
BSTR strName,
ICspAlgorithm **ppValue
);

Parameters
strName

ppValue

Return value
None

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
ICspAlgorithm
ICspAlgorithms
 ICspAlgorithms::Remove method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Remove method removes an ICspAlgorithm object from the collection by index number.

Syntax
HRESULT Remove(
[in] LONG Index
);

Parameters
[in] Index

A LONG variable that contains the index of the object to remove.

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
ICspAlgorithm
ICspAlgorithms
 ICspInformation interface (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The ICspInformation interface provides access to general information about a cryptographic provider. The
information is initialized by calling the InitializeFromName or InitializeFromType method. The information is
retrieved by using the following methods and properties. For information about CSPs, see CSPs and the
Cryptography Process.

Inheritance
The ICspInformation interface inherits from the IDispatch interface. ICspInformation also has these types of
members:

Methods
The ICspInformation interface has these methods.

ICspInformation::get_CspAlgorithms

Retrieves a collection of ICspAlgorithm interfaces that contain information about the algorithms supported by the provider.

ICspInformation::get_HasHardwareRandomNumberGenerator

Retrieves a Boolean value that specifies whether the provider supports a hardware random number generator that can be
used to create random bytes for cryptographic operations.

ICspInformation::get_IsHardwareDevice

Retrieves a Boolean value that determines whether the provider is implemented in a hardware device.

ICspInformation::get_IsRemovable

Retrieves a Boolean value that specifies whether the token that contains the key can be removed.

ICspInformation::get_IsSmartCard

Retrieves a Boolean value that specifies whether the provider is a smart card provider.

ICspInformation::get_IsSoftwareDevice

Retrieves a Boolean value that specifies whether the provider is implemented in software.

ICspInformation::get_KeySpec

Retrieves a value that specifies the intended use of the algorithms supported by the provider.

ICspInformation::get_LegacyCsp

Retrieves a Boolean value that specifies whether the provider is a Cryptography API:_Next Generation (CNG) provider or a
CryptoAPI (legacy) CSP.
 ICspInformation::get_MaxKeyContainerNameLength

Retrieves the maximum supported length for the name of the private key container associated with the provider.

ICspInformation::get_Name

Retrieves the name.

ICspInformation::get_Type

Retrieves the type of the provider.

ICspInformation::get_Valid

Retrieves a Boolean value that specifies whether the provider is installed on the client computer.

ICspInformation::get_Version

Retrieves the version number of the provider.

ICspInformation::GetCspStatusFromOperations

Creates an ICspStatus object for the first supported algorithm that is consistent with the specified signature, encryption,
hashing, or cipher operation.

ICspInformation::GetDefaultSecurityDescriptor

Retrieves the default private key security descriptor.

ICspInformation::InitializeFromName

Initializes the object from a string that contains a provider name.

ICspInformation::InitializeFromType

Initializes the object from the default cryptographic provider.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

See also
CertEnroll Interfaces
ICspInformations
IDispatch
 ICspInformation::get_CspAlgorithms method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The CspAlgorithms property retrieves a collection of ICspAlgorithm interfaces that contain information about
the algorithms supported by the provider. This property is web enabled.
This property is read-only.

Syntax
HRESULT get_CspAlgorithms(
ICspAlgorithms **ppValue
);

Parameters
ppValue

Return value
None

Remarks
An ICspAlgorithm object contains information about the cryptographic algorithms supported by the provider.
This includes the algorithm object identifier (OID), the permitted key lengths and incremental lengths, the
algorithm name and abbreviated name, and a Boolean value that specifies whether the algorithm OID object is
valid.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
ICspInformation
 ICspInformation::get_HasHardwareRandomNumberGenerator
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The HasHardwareRandomNumberGenerator property retrieves a Boolean value that specifies whether the
provider supports a hardware random number generator that can be used to create random bytes for
cryptographic operations.
This property is read-only.

Syntax
HRESULT get_HasHardwareRandomNumberGenerator(
VARIANT_BOOL *pValue
);

Parameters
pValue

Return value
None

Remarks
There are currently no Microsoft cryptographic providers that support this feature.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
ICspInformation
 ICspInformation::get_IsHardwareDevice method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The IsHardwareDevice property retrieves a Boolean value that determines whether the provider is
implemented in a hardware device.
This property is read-only.

Syntax
HRESULT get_IsHardwareDevice(
VARIANT_BOOL *pValue
);

Parameters
pValue

Return value
None

Remarks
This property only specifies whether a provider is implemented in hardware. Because a provider can be
implemented in both hardware and software, you cannot assume that a value of true for this property indicates
that there is no software component. You must also examine the IsSoftwareDevice property. The following
providers return true for the IsHardwareDevice property:
Microsoft Smart Card Key Storage Provider
Microsoft Base Smart Card Crypto Provider
Both of these providers also return true for the IsSoftwareDevice property. The Certificate Enrollment service
assumes that a provider is a smart card provider if both the IsHardwareDevice and IsSoftwareDevice
properties are set, or if the IsRemovable property is set.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h
 DLL CertEnroll.dll

See also
ICspInformation
 ICspInformation::get_IsRemovable method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The IsRemovable property retrieves a Boolean value that specifies whether the token that contains the key can
be removed.
This property is read-only.

Syntax
HRESULT get_IsRemovable(
VARIANT_BOOL *pValue
);

Parameters
pValue

Return value
None

Remarks
Operator cards and smart cards are examples of removable tokens that can contain keys. For example, the
following providers return true for this property value:
Microsoft Smart Card Key Storage Provider
Microsoft Base Smart Card Crypto Provider
The Certificate Enrollment service assumes that a provider is a smart card provider if both the
IsHardwareDevice and IsSoftwareDevice properties are set, or if the IsRemovable property is set.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll
See also
ICspInformation
 ICspInformation::get_IsSmartCard method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The IsSmar tCard property retrieves a Boolean value that specifies whether the provider is a smart card
provider.
This property is read-only.

Syntax
HRESULT get_IsSmartCard(
VARIANT_BOOL *pValue
);

Parameters
pValue

Return value
None

Remarks
A smart card provider is typically identified by the IsHardwareDevice property and the IsSoftwareDevice
property being set or the IsRemovable property being set.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
ICspInformation
 ICspInformation::get_IsSoftwareDevice method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The IsSoftwareDevice property retrieves a Boolean value that specifies whether the provider is implemented
in software.
This property is read-only.

Syntax
HRESULT get_IsSoftwareDevice(
VARIANT_BOOL *pValue
);

Parameters
pValue

Return value
None

Remarks
This property only specifies whether a provider is implemented in software. Because a provider can be
implemented in both hardware and software, you cannot assume that a value of true for the IsSoftwareDevice
property indicates that there is no hardware component. You must also examine the IsHardwareDevice property.
The following Microsoft providers return true for the IsSoftwareDevice property:
Microsoft Software Key Storage Provider
Microsoft Smart Card Key Storage Provider
Microsoft Base Cryptographic Provider v1.0
Microsoft Base DSS and Diffie-Hellman Cryptographic Provider
Microsoft Base DSS Cryptographic Provider
Microsoft Base Smart Card Crypto Provider
Microsoft DH Schannel Cryptographic Provider
Microsoft Enhanced Cryptographic Provider v1.0
Microsoft Enhanced DSS and Diffie-Hellman Cryptographic Provider
Microsoft Enhanced RSA and AES Cryptographic Provider
Microsoft RSA Schannel Cryptographic Provider
Microsoft Strong Cryptographic Provider
The Microsoft Smart Card Key Storage Provider and the Microsoft Base Smart Card Crypto Provider also return
true for the IsHardwareDevice property. The Certificate Enrollment service assumes a smart card provider if
both the IsHardwareDevice and IsSoftwareDevice properties are set, or if the IsRemovable property is set.
Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
ICspInformation
 ICspInformation::get_KeySpec method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The KeySpec property retrieves a value that specifies the intended use of the algorithms supported by the
provider. This property is web enabled.
This property is read-only.

Syntax
HRESULT get_KeySpec(
X509KeySpec *pValue
);

Parameters
pValue

Return value
None

Remarks
The value retrieved can be 0, 1, 2, or 3. If the value is 0 (XCN_AT_NONE), the provider is a Cryptography API:
Next Generation (CNG) provider. The values associated with the providers distributed by Microsoft are listed in
the following table. Some of these providers may not be included on all operating systems and others may be
included instead.

P RO VIDER K EY SP EC VA L UE

Microsoft Software Key Storage Provider 0

Microsoft Smart Card Key Storage Provider 0

Microsoft Base Cryptographic Provider v1.0 3

Microsoft Base DSS and Diffie-Hellman Cryptographic 3

Provider

Microsoft Base DSS Cryptographic Provider 2

Microsoft Base Smart Card Crypto Provider 3

Microsoft DH Schannel Cryptographic Provider 3

Microsoft Enhanced Cryptographic Provider v1.0 3

 Microsoft Enhanced DSS and Diffie-Hellman Cryptographic 3
Provider

Microsoft Enhanced RSA and AES Cryptographic Provider 3

Microsoft RSA Schannel Cryptographic Provider 1

Microsoft Strong Cryptographic Provider 3

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
ICspInformation
 ICspInformation::get_LegacyCsp method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The LegacyCsp property retrieves a Boolean value that specifies whether the provider is a Cryptography API:
Next Generation (CNG) provider or a CryptoAPI (legacy) CSP. This property is web enabled.
This property is read-only.

Syntax
HRESULT get_LegacyCsp(
VARIANT_BOOL *pValue
);

Parameters
pValue

Return value
None

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
ICspInformation
 ICspInformation::get_MaxKeyContainerNameLength
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The MaxKeyContainerNameLength property retrieves the maximum supported length for the name of the
private key container associated with the provider.
This property is read-only.

Syntax
HRESULT get_MaxKeyContainerNameLength(
LONG *pValue
);

Parameters
pValue

Return value
None

Remarks
The key container name can be specified and retrieved by calling the ContainerName property on the
IX509PrivateKey interface. The values associated with the providers distributed by Microsoft are listed in the
following table. Some of these providers may not be included on all operating systems and others may be
included instead.

P RO VIDER M A XK EY C O N TA IN ERN A M EL EN GT H VA L UE

Microsoft Software Key Storage Provider 261

Microsoft Smart Card Key Storage Provider 40

Microsoft Base Cryptographic Provider v1.0 261

Microsoft Base DSS and Diffie-Hellman Cryptographic 261

Provider

Microsoft Base DSS Cryptographic Provider 261

Microsoft Base Smart Card Crypto Provider 40

Microsoft DH Schannel Cryptographic Provider 261

Microsoft Enhanced Cryptographic Provider v1.0 261

 Microsoft Enhanced DSS and Diffie-Hellman Cryptographic 261
Provider

Microsoft Enhanced RSA and AES Cryptographic Provider 261

Microsoft RSA Schannel Cryptographic Provider 261

Microsoft Strong Cryptographic Provider 261

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
ICspInformation
 ICspInformation::get_Name method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Name property retrieves the name. This property is web enabled.
This property is read-only.

Syntax
HRESULT get_Name(
BSTR *pValue
);

Parameters
pValue

Return value
None

Remarks
The following list shows the names of some of the Microsoft providers installed on Windows Vista and later. This
list is not inclusive:
Microsoft Software Key Storage Provider
Microsoft Smart Card Key Storage Provider
Microsoft Base Cryptographic Provider v1.0
Microsoft Base DSS and Diffie-Hellman Cryptographic Provider
Microsoft Base DSS Cryptographic Provider
Microsoft Base Smart Card Crypto Provider
Microsoft DH Schannel Cryptographic Provider
Microsoft Enhanced Cryptographic Provider v1.0
Microsoft Enhanced DSS and Diffie-Hellman Cryptographic Provider
Microsoft Enhanced RSA and AES Cryptographic Provider
Microsoft RSA Schannel Cryptographic Provider
Microsoft Strong Cryptographic Provider

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]
 Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
ICspInformation
 ICspInformation::get_Type method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Type property retrieves the type of the provider. This property is web enabled.
This property is read-only.

Syntax
HRESULT get_Type(
X509ProviderType *pValue
);

Parameters
pValue

Return value
None

Remarks
The values associated with the providers distributed by Microsoft are listed in the following table. Some of these
providers may not be included on all operating systems and others may be included instead.

P RO VIDER T Y P E VA L UE

Microsoft Software Key Storage Provider XCN_PROV_NONE (0)

Microsoft Smart Card Key Storage Provider XCN_PROV_NONE (0)

Microsoft Base Cryptographic Provider v1.0 XCN_PROV_RSA_FULL (1)

Microsoft Base DSS and Diffie-Hellman Cryptographic XCN_PROV_DSS_DH (13)

Provider

Microsoft Base DSS Cryptographic Provider XCN_PROV_DSS (3)

Microsoft Base Smart Card Crypto Provider XCN_PROV_RSA_FULL (1)

Microsoft DH Schannel Cryptographic Provider XCN_PROV_DH_SCHANNEL (18)

Microsoft Enhanced Cryptographic Provider v1.0 XCN_PROV_RSA_FULL (1)

Microsoft Enhanced DSS and Diffie-Hellman Cryptographic XCN_PROV_DSS_DH (13)

Provider

Microsoft Enhanced RSA and AES Cryptographic Provider XCN_PROV_RSA_AES (24)

 Microsoft RSA Schannel Cryptographic Provider XCN_PROV_RSA_SCHANNEL (12)

Microsoft Strong Cryptographic Provider CN_PROV_RSA_FULL (1)

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
ICspInformation
 ICspInformation::get_Valid method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Valid property retrieves a Boolean value that specifies whether the provider is installed on the client
computer.
This property is read-only.

Syntax
HRESULT get_Valid(
VARIANT_BOOL *pValue
);

Parameters
pValue

Return value
None

Remarks
The Valid property is typically set by the Certificate Enrollment Control when it processes the list of providers
identified in a template-based certificate request. If a provider listed in the template is not installed on the client,
the control creates an ICspInformation object and sets the value of this property to false. You can use this
property value in a user interface to indicate whether a provider is available. If a provider is not installed, only
the Valid property and the Name property provide meaningful information.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
ICspInformation
 ICspInformation::get_Version method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Version property retrieves the version number of the provider.

This property is read-only.

Syntax
HRESULT get_Version(
LONG *pValue
);

Parameters
pValue

Return value
None

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
ICspInformation
 ICspInformation::GetCspStatusFromOperations
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The GetCspStatusFromOperations method creates an ICspStatus object for the first supported algorithm that
is consistent with the specified signature, encryption, hashing, or cipher operation.

Syntax
HRESULT GetCspStatusFromOperations(
[in, optional] IObjectId *pAlgorithm,
[in] AlgorithmOperationFlags Operations,
[out] ICspStatus **ppValue
);

Parameters
[in, optional] pAlgorithm

Pointer to an IObjectId interface that represents an algorithm OID. This parameter is optional and can be NULL .
If you specify an OID and set the Operations parameter to XCN_NCRYPT_SIGNATURE_OPERATION and
combine this flag with either XCN_NCRYPT_EXACT_MATCH_OPERATION or
XCN_NCRYPT_PREFER_SIGNATURE_ONLY_OPERATION, the first signature algorithm, if any, that matches the
OID is used.
If you specify an OID but do not set the Operations parameter to
XCN_NCRYPT_SIGNATURE_OPERATION , or you set XCN_NCRYPT_SIGNATURE_OPERATION but do
not combine it with either XCN_NCRYPT_EXACT_MATCH_OPERATION or
XCN_NCRYPT_PREFER_SIGNATURE_ONLY_OPERATION, the first algorithm that can be used for signing or
encryption is used.
If you do not specify an OID, the first supported algorithm consistent with the flags specified in the
Operations parameter is used.
[in] Operations

An AlgorithmOperationFlags enumeration value that identifies the type of algorithm to retrieve. One of the
following values must be specified:
XCN_NCRYPT_CIPHER_OPERATION
XCN_NCRYPT_HASH_OPERATION
XCN_NCRYPT_SIGNATURE_OPERATION
XCN_NCRYPT_SECRET_AGREEMENT_OPERATION
XCN_NCRYPT_ASYMMETRIC_ENCRYPTION_OPERATION
You can refine the search characteristics by combining one of the preceding flags with one of the following:
XCN_NCRYPT_PREFER_SIGNATURE_ONLY_OPERATION
XCN_NCRYPT_PREFER_NON_SIGNATURE_OPERATION
XCN_NCRYPT_EXACT_MATCH_OPERATION
If you set the XCN_NCRYPT_PREFER_SIGNATURE_ONLY_OPERATION or
XCN_NCRYPT_PREFER_NON_SIGNATURE_OPERATION preference flags, you cannot also specify either of the
following:
XCN_NCRYPT_CIPHER_OPERATION
XCN_NCRYPT_HASH_OPERATION
[out] ppValue

Address of a variable that receives a pointer to an ICspStatus interface.

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. Possible values include, but are not
limited to, those in the following table. For a list of common error codes, see Common HRESULT Values.

RET URN C O DE/ VA L UE DESC RIP T IO N

The ICspStatus object could not be found.

CERTSRV_E_PROPERTY_EMPTY

The ICspInformation object has not been initialized.

OLE_E_BL ANK

Remarks
An ICspStatus object contains status information about a cryptographic provider. Each object is initialized for a
specific algorithm supported by the provider. If you do not specify an algorithm in the pAlgorithm parameter,
the first supported algorithm that is consistent with the permitted operations is chosen to create the ICspStatus
object.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
ICspInformation
 ICspInformation::GetDefaultSecurityDescriptor
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The GetDefaultSecurityDescriptor method retrieves the default private key security descriptor.

Syntax
HRESULT GetDefaultSecurityDescriptor(
[in] VARIANT_BOOL MachineContext,
[out] BSTR *pValue
);

Parameters
[in] MachineContext

A VARIANT_BOOL variable that indicates whether to retrieve the security descriptor for the computer or the
user. Specify VARIANT_TRUE for the computer and VARIANT_FALSE for the user.
[out] pValue

Pointer to a BSTR variable that contains the security descriptor.

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. Possible values include, but are not
limited to, those in the following table. For a list of common error codes, see Common HRESULT Values.

RET URN C O DE/ VA L UE DESC RIP T IO N

The property value could not be found.

CERTSRV_E_PROPERTY_EMPTY

The cryptographic provider does not support security

NTE_BAD_TYPE descriptors.

The cryptographic provider does not support security

NTE_NOT_FOUND descriptors.

The cryptographic provider does not support security

NTE_BAD_KEY_STATE descriptors.

Remarks
To use the security descriptor, you must call the ConvertStringSecurityDescriptorToSecurityDescriptor function
included with the Microsoft Authorization API and specify the string returned by the
GetDefaultSecurityDescriptor method. The function returns a pointer to a SECURITY_DESCRIPTOR structure.
The default security descriptor is used to define access to private keys for the computer and user in the
following manner:
By default, only local administrators and services running under the LocalSystem account can access private
keys associated with the computer account.
When a provider stores the private key of a user in an encrypted file in the user profile, it uses a security
descriptor to set access permissions to the file.
This method retrieves the default security descriptor that will be associated with the specified MachineContext
parameter and the current provider if a new private key is created. You can use the default descriptor to create a
custom descriptor. Custom descriptors are typically created when a private key associated with a computer
context certificate must be used by a service running under an account other than the LocalSystem account.
Some cryptographic providers do not support security descriptors. Examples include smart card and hardware
security module (HSM) providers.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
ICspInformation
 ICspInformation::InitializeFromName method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The InitializeFromName method initializes the object from a string that contains a provider name. This
method is web enabled.

Syntax
HRESULT InitializeFromName(
[in] BSTR strName
);

Parameters
[in] strName

A BSTR variable that contains the name.

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. Possible values include, but are not
limited to, those in the following table. For a list of common error codes, see Common HRESULT Values.

RET URN C O DE/ VA L UE DESC RIP T IO N

The object is already initialized.

HRESULT_FROM_WIN32(ERROR_ALREADY_INITIALIZE
D)

Remarks
The InitializeFromName method opens the named provider and queries it to set the following property
values on the ICspInformation object:
CspAlgorithms
HasHardwareRandomNumberGenerator
IsHardwareDevice
IsRemovable
IsSmartCard
IsSoftwareDevice
KeySpec
LegacyCsp
MaxKeyContainerNameLength
Name
Type
 Valid
Version
The method adds the available algorithms to the ICspAlgorithms collection returned by the CspAlgorithms
property. Call the InitializeFromType method to initialize the object from a provider type.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
ICspInformation
 ICspInformation::InitializeFromType method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The InitializeFromType method initializes the object from the default cryptographic provider.

Syntax
HRESULT InitializeFromType(
[in] X509ProviderType Type,
[in, optional] IObjectId *pAlgorithm,
[in] VARIANT_BOOL MachineContext
);

Parameters
[in] Type

An X509ProviderType enumeration value that defines the provider type.

If you specify XCN_PROV_NONE and set the pAlgorithm parameter to a value other than NULL , the default
Cryptography API: Next Generation (CNG) provider is used.
If you specify a value other than XCN_PROV_NONE and set the pAlgorithm parameter to NULL , the default
legacy cryptographic service provider (CSP) is used.
[in, optional] pAlgorithm

Pointer to an IObjectId interface that represents an algorithm OID. This parameter is optional and can be NULL .
For more information, see the Type parameter.
[in] MachineContext

A VARIANT_BOOL variable that indicates whether to use the computer or user context to determine the default
provider for the specified provider type. Specify VARIANT_TRUE for the computer and VARIANT_FALSE for
the user.

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. Possible values include, but are not
limited to, those in the following table. For a list of common error codes, see Common HRESULT Values.

RET URN C O DE/ VA L UE DESC RIP T IO N

The object is already initialized.

HRESULT_FROM_WIN32(ERROR_ALREADY_INITIALIZE
D)

Remarks
The InitializeFromType method validates the specified type and saves it in the Type property, retrieves the
default provider, and sets the following property values on the ICspInformation object:
CspAlgorithms
HasHardwareRandomNumberGenerator
IsHardwareDevice
IsRemovable
IsSmartCard
IsSoftwareDevice
KeySpec
LegacyCsp
MaxKeyContainerNameLength
Name
Valid
Version
The method adds the available algorithms to the ICspAlgorithms collection returned by the CspAlgorithms
property. Call the InitializeFromName method to initialize the object from a CSP name.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
ICspInformation
 ICspInformations interface (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The ICspInformations interface defines the following methods and properties to manage a collection of
ICspInformation objects.

Inheritance
The ICspInformations interface inherits from the IDispatch interface. ICspInformations also has these types
of members:

Methods
The ICspInformations interface has these methods.

ICspInformations::Add

Adds an ICspInformation object to the collection.

ICspInformations::AddAvailableCsps

Adds the providers installed on the computer to the collection.

ICspInformations::Clear

Removes all ICspInformation objects from the collection.

ICspInformations::get__NewEnum

Retrieves the enumerator for the collection.

ICspInformations::get_Count

Retrieves the number of ICspInformation objects in the collection.

ICspInformations::get_ItemByIndex

Retrieves an ICspInformation object from the collection by index number.

ICspInformations::get_ItemByName

Retrieves an ICspInformation object from the collection by name.

ICspInformations::GetCspStatusesFromOperations

Retrieves an ICspStatuses collection by supported key operations and optional provider information.

ICspInformations::GetCspStatusFromProviderName

Retrieves an ICspStatus object for a legacy provider by provider name and supported key operations.
 ICspInformations::GetEncryptionCspAlgorithms

Retrieves the collection of encryption algorithms supported by a provider.

ICspInformations::GetHashAlgorithms

Retrieves the collection of hash algorithms supported by a provider.

ICspInformations::Remove

Removes an ICspInformation object from the collection by index number.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

See also
CertEnroll Interfaces
ICspInformation
IDispatch
 ICspInformations::Add method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Add method adds an ICspInformation object to the collection. This method is web enabled.

Syntax
HRESULT Add(
[in] ICspInformation *pVal
);

Parameters
[in] pVal

Pointer to an ICspInformation object to add to the collection.

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
ICspInformation
ICspInformations
 ICspInformations::AddAvailableCsps method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The AddAvailableCsps method adds the providers installed on the computer to the collection. This method is
web enabled.

Syntax
HRESULT AddAvailableCsps();

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. Possible values include, but are not
limited to, those in the following table. For a list of common error codes, see Common HRESULT Values.

RET URN C O DE/ VA L UE DESC RIP T IO N

The collection is not empty.

HRESULT_FROM_WIN32(ERROR_INVALID_OPERATIO
N)

Remarks
The ICspInformations collection must be empty before you call this method.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
ICspInformation
ICspInformations
 ICspInformations::Clear method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Clear method removes all ICspInformation objects from the collection.

Syntax
HRESULT Clear();

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
ICspInformation
ICspInformations
 ICspInformations::get__NewEnum method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The _NewEnum property retrieves the enumerator for the collection.

This property is read-only.

Syntax
HRESULT get__NewEnum(
LPUNKNOWN *pVal
);

Parameters
pVal

Return value
None

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
ICspInformation
ICspInformations
 ICspInformations::get_Count method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Count property retrieves the number of ICspInformation objects in the collection. This property is web
enabled.
This property is read-only.

Syntax
HRESULT get_Count(
long *pVal
);

Parameters
pVal

Return value
None

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
ICspInformation
ICspInformations
 ICspInformations::get_ItemByName method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The ItemByName property retrieves an ICspInformation object from the collection by name. This property is
web enabled.
This property is read-only.

Syntax
HRESULT get_ItemByName(
BSTR strName,
ICspInformation **ppCspInformation
);

Parameters
strName

ppCspInformation

Return value
None

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
ICspInformation
ICspInformations
 ICspInformations::GetCspStatusesFromOperations
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The GetCspStatusesFromOperations method retrieves an ICspStatuses collection by supported key

operations and optional provider information. This method is web enabled.

Syntax
HRESULT GetCspStatusesFromOperations(
[in] AlgorithmOperationFlags Operations,
[in, optional] ICspInformation *pCspInformation,
[out] ICspStatuses **ppValue
);

Parameters
[in] Operations

An AlgorithmOperationFlags enumeration value that specifies the supported operations. This can be a bitwise
combination of the following flags:
XCN_NCRYPT_NO_OPERATION
XCN_NCRYPT_CIPHER_OPERATION
XCN_NCRYPT_HASH_OPERATION
XCN_NCRYPT_ASYMMETRIC_ENCRYPTION_OPERATION
XCN_NCRYPT_SECRET_AGREEMENT_OPERATION
XCN_NCRYPT_SIGNATURE_OPERATION
XCN_NCRYPT_RNG_OPERATION
XCN_NCRYPT_ANY_ASYMMETRIC_OPERATION
XCN_NCRYPT_PREFER_SIGNATURE_ONLY_OPERATION
XCN_NCRYPT_PREFER_NON_SIGNATURE_OPERATION
XCN_NCRYPT_EXACT_MATCH_OPERATION
XCN_NCRYPT_PREFERENCE_MASK_OPERATION
[in, optional] pCspInformation

Pointer to an ICspInformation interface that represents information for a specific provider.

[out] ppValue

Address of a variable that receives a pointer to an ICspStatuses interface that contains the collection.

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.
Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
ICspInformation
ICspInformations
 ICspInformations::GetCspStatusFromProviderName
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The GetCspStatusFromProviderName method retrieves an ICspStatus object for a legacy provider by

provider name and supported key operations. This method is web enabled.

Syntax
HRESULT GetCspStatusFromProviderName(
[in] BSTR strProviderName,
[in] X509KeySpec LegacyKeySpec,
[out] ICspStatus **ppValue
);

Parameters
[in] strProviderName

A BSTR that contains the cryptographic provider name or the provider and algorithm names separated by a
comma in the format algorithm_name, provider_name.
[in] LegacyKeySpec

An X509KeySpec enumeration value that specifies whether a key can be used for encryption, signing, or both.
This can be one of the following values:
XCN_AT_KEYEXCHANGE
XCN_AT_SIGNATURE
[out] ppValue

Address of a variable that receives a pointer to an ICspStatus interface that contains information about a
cryptographic provider and algorithm pair that satisfies the strProviderName and LegacyKeySpec parameter
values.

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]
 Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
ICspInformation
ICspInformations
 ICspInformations::GetEncryptionCspAlgorithms
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The GetEncr yptionCspAlgorithms method retrieves the collection of encryption algorithms supported by a
provider.

Syntax
HRESULT GetEncryptionCspAlgorithms(
[in, optional] ICspInformation *pCspInformation,
[out] ICspAlgorithms **ppValue
);

Parameters
[in, optional] pCspInformation

Pointer to an ICspInformation interface that represents the provider. This can be a legacy cryptographic service
provider (CSP), a Cryptography API: Next Generation (CNG) provider, or NULL . If you specify NULL , this
method returns the collection of all encryption algorithms supported by all CSPs and CNG providers.
[out] ppValue

Address of a variable that receives a pointer to an ICspAlgorithms interface that represents the collection.

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
ICspInformation
ICspInformations
 ICspInformations::GetHashAlgorithms method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The GetHashAlgorithms method retrieves the collection of hash algorithms supported by a provider.

Syntax
HRESULT GetHashAlgorithms(
[in, optional] ICspInformation *pCspInformation,
[out] IObjectIds **ppValue
);

Parameters
[in, optional] pCspInformation

Pointer to an ICspInformation interface that represents the provider. This can be a legacy cryptographic service
provider (CSP), a Cryptography API: Next Generation (CNG) provider, or NULL . If you specify NULL , this
method returns the collection of all hash algorithms supported by all CSPs and CNG providers.
[out] ppValue

Address of a pointer to an IObjectIds interface that represents the collection.

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
ICspInformation
ICspInformations
 ICspInformations::Remove method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Remove method removes an ICspInformation object from the collection by index number.

Syntax
HRESULT Remove(
[in] LONG Index
);

Parameters
[in] Index

A LONG variable that contains the index of the object to remove.

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
ICspInformation
ICspInformations
 ICspStatus interface (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

An ICspStatus object contains information about a cryptographic provider/algorithm pair. The object is
primarily used by the Certificate Enrollment Control to enable a user to select which cryptographic providers
and algorithms to use when creating a certificate request. It can be retrieved, either alone or in an ICspStatuses
collection, by calling the following properties or methods:

P RO P ERT Y / M ET H O D IN T ERFA C E DESC RIP T IO N

GetCspStatusFromOperations ICspInformation Creates an ICspStatus object for the

first supported algorithm that is
consistent with a specified algorithm
object identifier (OID) and algorithm
type.

GetCspStatusesFromOperations ICspInformations Creates an ICspStatuses collection for a

specified algorithm type and optional
provider information.

Note The Certificate Enrollment

Control uses an ICspStatuses
collection only for private key
asymmetric (encryption, signing,
and key exchange) algorithm
selection.

GetCspStatusFromProviderName ICspInformations Creates an ICspStatus object for a

legacy provider by provider name and
supported key operations.

CspStatus IX509PrivateKey Specifies or retrieves an ICspStatus

object. The object is typically created
during the enrollment process.

GetCspStatuses IX509CertificateRequestPkcs10 Creates an ICspStatuses collection that

contains all provider/algorithm pairs
consistent with the intended use of the
private key as specified by the caller.

CspStatuses IX509CertificateRequestPkcs10 Creates an ICspStatuses collection that

contains all provider/algorithm pairs
consistent with the intended use of the
private key as identified by the
IX509PrivateKey object associated with
the certificate request.

Because cryptographic providers typically support more than one algorithm, multiple ICspStatus objects may
be created and returned when you call any of the preceding properties or methods that return a collection. This
is shown by the following illustration:
You can use the EnrollmentStatus property on an ICspStatus object to retrieve an IX509EnrollmentStatus object
that defines the following properties:
The Display property specifies whether the provider/algorithm pair can be displayed in a user interface.
The Selected property specifies or retrieves a value that indicates whether the status of a specific item is
monitored during the enrollment process.
The Status property identifies the status of the enrollment process.

Inheritance
The ICspStatus interface inherits from the IDispatch interface. ICspStatus also has these types of members:

Methods
The ICspStatus interface has these methods.

ICspStatus::get_CspAlgorithm

Retrieves an ICspAlgorithm object that contains information about an algorithm supported by the provider.
 ICspStatus::get_CspInformation

Retrieves an ICspInformation object that contains general information about the provider.

ICspStatus::get_DisplayName

Retrieves a string that contains the name of the provider, the algorithm name, and the operations that can be performed by
the algorithm.

ICspStatus::get_EnrollmentStatus

Retrieves an IX509EnrollmentStatus object that contains information about the certificate enrollment.

ICspStatus::get_Ordinal

Specifies or retrieves the position of the ICspStatus object in the ICspStatuses collection.

ICspStatus::Initialize

Initializes the object from a cryptographic provider and an associated algorithm.

ICspStatus::put_Ordinal

Specifies or retrieves the position of the ICspStatus object in the ICspStatuses collection.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

See also
CertEnroll Interfaces
ICspStatuses
IDispatch
 ICspStatus::get_CspAlgorithm method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The CspAlgorithm property retrieves an ICspAlgorithm object that contains information about an algorithm
supported by the provider. This property is web enabled.
This property is read-only.

Syntax
HRESULT get_CspAlgorithm(
ICspAlgorithm **ppValue
);

Parameters
ppValue

Return value
None

Remarks
The ICspAlgorithm object includes the following information about an algorithm:
The default, minimum, maximum, and incremental lengths of the key.
The abbreviated and long name of the algorithm.
The cryptographic operations that can be performed by the algorithm.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
ICspStatus
ICspStatuses
 ICspStatus::get_CspInformation method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The CspInformation property retrieves an ICspInformation object that contains general information about the
provider. This property is web enabled.
This property is read-only.

Syntax
HRESULT get_CspInformation(
ICspInformation **ppValue
);

Parameters
ppValue

Return value
None

Remarks
The ICspInformation object includes the following information about a CSP:
A collection of supported algorithms and their intended uses.
Whether the CSP is implemented in hardware or software.
Whether the CSP is a smart card provider or a legacy provider.
The version number and name.
Whether the CSP is installed on the client computer.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll
See also
ICspStatus
ICspStatuses
 ICspStatus::get_DisplayName method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The DisplayName property retrieves a string that contains the name of the provider, the algorithm name, and
the operations that can be performed by the algorithm.
This property is read-only.

Syntax
HRESULT get_DisplayName(
BSTR *pValue
);

Parameters
pValue

Return value
None

Remarks
The format of the string returned by this property depends on whether the provider is a CryptoAPI
cryptographic service provider (CSP) or a Cryptography API: Next Generation (CNG) provider.
The format of the string for a CSP is ProviderName(KeyType) where KeyType is either "Signature" or
"Encryption".
The format of the string for a CNG provider is AlgorithmName,ProviderName where AlgorithmName can be
"Unknown Algorithm".

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
ICspStatus
ICspStatuses
 ICspStatus::get_EnrollmentStatus method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The EnrollmentStatus property retrieves an IX509EnrollmentStatus object that contains information about the
certificate enrollment.
This property is read-only.

Syntax
HRESULT get_EnrollmentStatus(
IX509EnrollmentStatus **ppValue
);

Parameters
ppValue

Return value
None

Remarks
This property returns an IX509EnrollmentStatus object. This object is typically populated when you create a
PKCS #10 certificate request. The following three properties returned by this object provide information about
the provider/algorithm pair represented by an ICspStatus object:
The Display property specifies whether the provider and algorithm should be displayed in a user interface.
The Selected property specifies whether the provider and algorithm can be used to create a key pair for a
certificate request.
The Status property specifies whether the provider and algorithm were skipped or resulted in an error during
request initialization.
To understand how these properties are important, assume that a certificate request is based on a template that
specifies a particular provider and algorithm. The Display and Status properties for this provider/algorithm pair
are enabled. For other ICspStatus objects, one or both of these properties may not be enabled. For more
complete examples, see the Ordinal property.
The Status property is set to EnrollUnknown when the IX509EnrollmentStatus object is first created. If a
provider/algorithm pair is not selected, the status may be set to EnrollSkipped . The status will be set to
EnrollError if key creation fails for the selected provider and algorithm during certificate initialization.

Requirements
 Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
ICspStatus
ICspStatuses
 ICspStatus::get_Ordinal method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Ordinal property specifies or retrieves the position of the ICspStatus object in the ICspStatuses collection.
This property is read/write.

Syntax
HRESULT get_Ordinal(
LONG *pValue
);

Parameters
pValue

Return value
None

Remarks
To iterate through the ICspStatuses collection by ordinal, call the ItemByOrdinal property. The ordinal order of
the ICspStatus objects in the collection can vary each time the collection is enumerated for a variety of reasons
including, but not limited to, the following:
Certificate request template settings
Property values for the cryptographic provider
Private key property values
For example, assume that the version 2 template chosen to create a certificate request specifies that the
certificate can only be used for signing (the pKIDefaultKeySpec template attribute is XCN_AT_SIGNATURE) and
that the default provider is the Microsoft Enhanced RSA and AES Cryptographic Provider. Notice that the
template restricts the certificate to signing even though the provider supports both encryption and signing
algorithms. That is, the KeySpec property on the provider is a bitwise combination of the
XCN_AT_KEYEXCHANGE and XCN_AT_SIGNATURE constants, but the pKIDefaultKeySpec template attribute
supports only XCN_AT_SIGNATURE.
The ICspStatus objects in the collection will be ordered in the following manner:
Of the ICspStatus objects enumerated for this provider, those associated with signature algorithms
(XCN_AT_SIGNATURE) are ordered first (lower ordinal value) and their Display and Selected properties are
enabled.

Note If the pKIDefaultKeySpec template attribute had been XCN_AT_KEYEXCHANGE, the encryption algorithms
would be ordered first.

Of the ICspStatus objects enumerated for this provider, those associated with encryption algorithms
 (XCN_AT_KEYEXCHANGE) are ordered later (higher ordinal values) and their Display and Selected properties
are not enabled.
For all other installed CryptoAPI providers that support asymmetric signing algorithms
(XCN_AT_SIGNATURE) but which are not associated with the specified provider, the Display property is
enabled and the Selected property is not enabled.
For all other installed CryptoAPI providers that support asymmetric encryption algorithms
(XCN_AT_KEYEXCHANGE), the Display and Selected properties are not enabled.
For all installed Cryptography API: Next Generation (CNG) providers, the Display and Selected properties are
not enabled.
For another example, assume that a version 3 template specifies one specific CNG provider and algorithm. That
provider/algorithm pair (ICspStatus object) is ordered first, enabled for display and selected. All other algorithms
supported by that provider are ordered later, not enabled for display, and not selected. All other providers that
support the specified algorithm will be ordered later still, enabled for display, but not selected. All remaining
provider/algorithm pairs will not be enabled for display and not selected.

Note CNG providers do not support the KeySpec intended use concept. They return XCN_AT_NONE for this property value.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
ICspStatus
ICspStatuses
 ICspStatus::Initialize method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Initialize method initializes the object from a cryptographic provider and an associated algorithm. This
method is web enabled.

Syntax
HRESULT Initialize(
[in] ICspInformation *pCsp,
[in, optional] ICspAlgorithm *pAlgorithm
);

Parameters
[in] pCsp

Pointer to an ICspInformation interface that represents information about the provider.

[in, optional] pAlgorithm

Pointer to an ICspAlgorithm interface that represents an algorithm supported by the provider identified in the
pCsp parameter. This parameter is optional and can be NULL .

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. Possible values include, but are not
limited to, those in the following table. For a list of common error codes, see Common HRESULT Values.

RET URN C O DE/ VA L UE DESC RIP T IO N

The object is already initialized.

HRESULT_FROM_WIN32(ERROR_ALREADY_INITIALIZE
D)

Remarks
The Initialize method saves the ICspInformation and ICspAlgorithm objects you specify in the CspInformation
and CspAlgorithm properties. The method also creates an empty IX509EnrollmentStatus object and saves it in
the EnrollmentStatus property.
An ICspStatuses collection is typically initialized by an IX509CertificateRequestPkcs10 object. The Initialize
method has been provided so that you can create ICspStatus objects to add to a custom collection.

Requirements
 Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
ICspStatus
ICspStatuses
 ICspStatus::put_Ordinal method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Ordinal property specifies or retrieves the position of the ICspStatus object in the ICspStatuses collection.
This property is read/write.

Syntax
HRESULT put_Ordinal(
LONG Value
);

Parameters
Value

Return value
None

Remarks
To iterate through the ICspStatuses collection by ordinal, call the ItemByOrdinal property. The ordinal order of
the ICspStatus objects in the collection can vary each time the collection is enumerated for a variety of reasons
including, but not limited to, the following:
Certificate request template settings
Property values for the cryptographic provider
Private key property values
For example, assume that the version 2 template chosen to create a certificate request specifies that the
certificate can only be used for signing (the pKIDefaultKeySpec template attribute is XCN_AT_SIGNATURE) and
that the default provider is the Microsoft Enhanced RSA and AES Cryptographic Provider. Notice that the
template restricts the certificate to signing even though the provider supports both encryption and signing
algorithms. That is, the KeySpec property on the provider is a bitwise combination of the
XCN_AT_KEYEXCHANGE and XCN_AT_SIGNATURE constants, but the pKIDefaultKeySpec template attribute
supports only XCN_AT_SIGNATURE.
The ICspStatus objects in the collection will be ordered in the following manner:
Of the ICspStatus objects enumerated for this provider, those associated with signature algorithms
(XCN_AT_SIGNATURE) are ordered first (lower ordinal value) and their Display and Selected properties are
enabled.

Note If the pKIDefaultKeySpec template attribute had been XCN_AT_KEYEXCHANGE, the encryption algorithms
would be ordered first.

Of the ICspStatus objects enumerated for this provider, those associated with encryption algorithms
 (XCN_AT_KEYEXCHANGE) are ordered later (higher ordinal values) and their Display and Selected properties
are not enabled.
For all other installed CryptoAPI providers that support asymmetric signing algorithms
(XCN_AT_SIGNATURE) but which are not associated with the specified provider, the Display property is
enabled and the Selected property is not enabled.
For all other installed CryptoAPI providers that support asymmetric encryption algorithms
(XCN_AT_KEYEXCHANGE), the Display and Selected properties are not enabled.
For all installed Cryptography API: Next Generation (CNG) providers, the Display and Selected properties are
not enabled.
For another example, assume that a version 3 template specifies one specific CNG provider and algorithm. That
provider/algorithm pair (ICspStatus object) is ordered first, enabled for display and selected. All other algorithms
supported by that provider are ordered later, not enabled for display, and not selected. All other providers that
support the specified algorithm will be ordered later still, enabled for display, but not selected. All remaining
provider/algorithm pairs will not be enabled for display and not selected.

Note CNG providers do not support the KeySpec intended use concept. They return XCN_AT_NONE for this property value.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
ICspStatus
ICspStatuses
 ICspStatuses interface (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The ICspStatuses interface defines methods and properties that can be used to manage a collection of
ICspStatus objects. The ICspStatus interface contains information about a cryptographic provider/algorithm
pair. The collection object is created when you call the following properties and methods.

P RO P ERT Y / M ET H O D IN T ERFA C E DESC RIP T IO N

GetCspStatusesFromOperations ICspInformations Creates an ICspStatuses collection

for a specified algorithm type and
optional provider information.

Note The Certificate Enrollment

Control uses an ICspStatuses
collection only for private key
asymmetric (encryption, signing,
and key exchange) algorithm
selection.

GetCspStatuses IX509CertificateRequestPkcs10 Creates an ICspStatuses collection

that contains all provider/algorithm
pairs consistent with the intended use
of the private key as specified by the
caller.

CspStatuses IX509CertificateRequestPkcs10 Creates an ICspStatuses collection

that contains all provider/algorithm
pairs consistent with the intended use
of the private key as identified by the
IX509PrivateKey object associated with
the certificate request.

Inheritance
The ICspStatuses interface inherits from the IDispatch interface. ICspStatuses also has these types of
members:

Methods
The ICspStatuses interface has these methods.

ICspStatuses::Add

Adds an ICspStatus object to the collection.

ICspStatuses::Clear

Removes all ICspStatus objects from the collection.

 ICspStatuses::get__NewEnum

Retrieves the enumerator for the collection.

ICspStatuses::get_Count

Retrieves the number of ICspStatus objects in the collection.

ICspStatuses::get_ItemByIndex

Retrieves an ICspStatus object from the collection by index number.

ICspStatuses::get_ItemByName

Retrieves an ICspStatus object from the collection by provider and algorithm name.

ICspStatuses::get_ItemByOperations

Retrieves an ICspStatus object that has the same name as the provider specified on input and the same algorithm but
identifies a different cryptographic operation.

ICspStatuses::get_ItemByOrdinal

Retrieves an ICspStatus object from the collection by ordinal number.

ICspStatuses::get_ItemByProvider

Retrieves an ICspStatus object that has the same name as the provider specified on input but identifies an algorithm that
supports a different intended key use.

ICspStatuses::Remove

Removes an ICspStatus object from the collection by index number.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

See also
CertEnroll Interfaces
ICspStatus
IDispatch
 ICspStatuses::Add method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Add method adds an ICspStatus object to the collection. This method is web enabled.

Syntax
HRESULT Add(
[in] ICspStatus *pVal
);

Parameters
[in] pVal

Pointer to an ICspStatus object to add to the collection.

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
ICspStatus
ICspStatuses
 ICspStatuses::Clear method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Clear method removes all ICspStatus objects from the collection.

Syntax
HRESULT Clear();

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
ICspStatus
ICspStatuses
 ICspStatuses::get__NewEnum method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The _NewEnum property retrieves the enumerator for the collection.

This property is read-only.

Syntax
HRESULT get__NewEnum(
LPUNKNOWN *pVal
);

Parameters
pVal

Return value
None

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
ICspStatus
ICspStatuses
 ICspStatuses::get_Count method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Count property retrieves the number of ICspStatus objects in the collection. This property is web enabled.
This property is read-only.

Syntax
HRESULT get_Count(
long *pVal
);

Parameters
pVal

Return value
None

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
ICspStatus
ICspStatuses
 ICspStatuses::get_ItemByName method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The ItemByName property retrieves an ICspStatus object from the collection by provider and algorithm name.
This property is web enabled.
This property is read-only.

Syntax
HRESULT get_ItemByName(
BSTR strCspName,
BSTR strAlgorithmName,
ICspStatus **ppValue
);

Parameters
strCspName

strAlgorithmName

ppValue

Return value
None

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
ICspStatus
ICspStatuses
 ICspStatuses::get_ItemByOperations method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The ItemByOperations property retrieves an ICspStatus object that has the same name as the provider
specified on input and the same algorithm but identifies a different cryptographic operation.
This property is read-only.

Syntax
HRESULT get_ItemByOperations(
BSTR strCspName,
BSTR strAlgorithmName,
AlgorithmOperationFlags Operations,
ICspStatus **ppValue
);

Parameters
strCspName

strAlgorithmName

Operations

ppValue

Return value
None

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
ICspStatus
ICspStatuses
 ICspStatuses::get_ItemByOrdinal method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The ItemByOrdinal property retrieves an ICspStatus object from the collection by ordinal number.
This property is read-only.

Syntax
HRESULT get_ItemByOrdinal(
LONG Ordinal,
ICspStatus **ppValue
);

Parameters
Ordinal

ppValue

Return value
None

Remarks
The ordinal order of the ICspStatus objects in the collection can vary each time the collection is enumerated for a
variety of reasons including, but not limited to, the following:
Certificate request template settings
Property values for the cryptographic provider
Private key property values
For example, assume that the version 2 template chosen to create a certificate request specifies that the
certificate can only be used for signing (the pKIDefaultKeySpec template attribute is XCN_AT_SIGNATURE) and
that the default provider is the Microsoft Enhanced RSA and AES Cryptographic Provider. Notice that the
template restricts the certificate to signing even though the provider supports both encryption and signing
algorithms. That is, the KeySpec property on the provider is a bitwise combination of the
XCN_AT_KEYEXCHANGE and XCN_AT_SIGNATURE constants, but the pKIDefaultKeySpec template attribute
supports only XCN_AT_SIGNATURE.
The ICspStatus objects in the collection will be ordered in the following manner:
Of the ICspStatus objects enumerated for this provider, those associated with signature algorithms
(XCN_AT_SIGNATURE) are ordered first (lower ordinal value) and their Display and Selected properties are
enabled.

Note If the pKIDefaultKeySpec template attribute had been XCN_AT_KEYEXCHANGE, the encryption algorithms
would be ordered first.
 Of the ICspStatus objects enumerated for this provider, those associated with encryption algorithms
(XCN_AT_KEYEXCHANGE) are ordered later (higher ordinal values) and their Display and Selected properties
are not enabled.
For all other installed CryptoAPI providers that support asymmetric signing algorithms
(XCN_AT_SIGNATURE) but which are not associated with the specified provider, the Display property is
enabled and the Selected property is not enabled.
For all other installed CryptoAPI providers that support asymmetric encryption algorithms
(XCN_AT_KEYEXCHANGE), the Display and Selected properties are not enabled.
For all installed Cryptography API: Next Generation (CNG) providers, the Display and Selected properties are
not enabled.
For another example, assume that a version 3 template specifies one specific CNG provider and algorithm. That
provider/algorithm pair (ICspStatus object) is ordered first, enabled for display and selected. All other algorithms
supported by that provider are ordered later, not enabled for display, and not selected. All other providers that
support the specified algorithm will be ordered later still, enabled for display, but not selected. All remaining
provider/algorithm pairs will not be enabled for display and not selected.

Note CNG providers do not support the KeySpec intended use concept. They return XCN_AT_NONE for this property value.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
ICspStatus
ICspStatuses
 ICspStatuses::get_ItemByProvider method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The ItemByProvider property retrieves an ICspStatus object that has the same name as the provider specified
on input but identifies an algorithm that supports a different intended key use.
This property is read-only.

Syntax
HRESULT get_ItemByProvider(
ICspStatus *pCspStatus,
ICspStatus **ppValue
);

Parameters
pCspStatus

ppValue

Return value
None

Remarks
The ItemByProvider property retrieves the ICspStatus object that matches the name of the input provider but
is associated with a different X509KeySpec enumeration value. For example, if the input provider has a KeySpec
value of XCN_AT_KEYEXCHANGE, the ItemByProvider property attempts to find an ICspStatus object for the
same provider but with a KeySpec value of XCN_AT_SIGNATURE.
Because the KeySpec property is only associated with legacy providers, if you specify a Cryptography API: Next
Generation (CNG) providers, the ItemByProvider property returns the same ICspStatus object as that entered.
To use this property to iterate through the collection, perform the following steps:
Retrieve an ICspStatuses collection by calling the GetCspStatuses method or the CspStatuses property on the
IX509CertificateRequestPkcs10 interface.
Call the ItemByIndex property to iterate through the collection.
For each ICspStatus element retrieved that contains the provider you are interested in, call ItemByProvider .

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

 Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
ICspStatuses
 ICspStatuses::Remove method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Remove method removes an ICspStatus object from the collection by index number.

Syntax
HRESULT Remove(
[in] LONG Index
);

Parameters
[in] Index

A LONG variable that contains the index of the object to remove.

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
ICspStatus
ICspStatuses
 ImportPFXFlags enumeration (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

[Some information relates to pre-released product which may be substantially modified before it's commercially
released. Microsoft makes no warranties, express or implied, with respect to the information provided here.]
Flags to use when importing a PFX certificate.

Syntax
typedef enum ImportPFXFlags {
ImportNone = 0,
ImportMachineContext = 0x1,
ImportForceOverwrite = 0x2,
ImportSilent = 0x4,
ImportSaveProperties = 0x8,
ImportExportable = 0x10,
ImportExportableEncrypted = 0x20,
ImportNoUserProtected = 0x40,
ImportUserProtected = 0x80,
ImportUserProtectedHigh = 0x100,
ImportInstallCertificate = 0x200,
ImportInstallChain = 0x400,
ImportInstallChainAndRoot = 0x800
} ;

Constants

ImportNone
Value: 0
None

ImportMachineContext
Value: 0x1
Import the PFX certificate into the machine certificate store; otherwise install to the user certificate store.

ImportForceOverwrite
Value: 0x2
Overwrite existing certificate, if exists.

ImportSilent
Value: 0x4
Silently perform the operation (do not show a user interface).

ImportSaveProperties
Value: 0x8
Save Properties on the imported PFX file.

ImportExportable
Value: 0x10
Import the PFX certificate’s private key as exportable
 ImportExportableEncrypted
Value: 0x20
Import the PFX certificate’s private key as exportable and encrypted.

ImportNoUserProtected
Value: 0x40
Import the PFX certificate’s private key to not require consent.

ImportUserProtected
Value: 0x80
Import the PFX certificate’s private key to require consent without a password.

ImportUserProtectedHigh
Value: 0x100
Import the PFX certificate’s private key to require consent with a password.

ImportInstallCertificate
Value: 0x200
Install the PFX certificate to the certificate store.

ImportInstallChain
Value: 0x400
Install the PFX certificate’s chain to the certificate store.

ImportInstallChainAndRoot
Value: 0x800
Install the PFX certificate’s chain and root to the certificate store.

Requirements

Header certenroll.h
 ImportPFXToProvider callback function (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

Imports a PFX certificate.

Syntax
ImportPFXToProvider Importpfxtoprovider;

HRESULT Importpfxtoprovider(
[in] HWND hWndParent,
[in] BYTE const *pbPFX,
[in] DWORD cbPFX,
[in] ImportPFXFlags ImportFlags,
[in, optional] PCWSTR pwszPassword,
[in, optional] PCWSTR pwszProviderName,
[in, optional] PCWSTR pwszReaderName,
[in, optional] PCWSTR pwszContainerNamePrefix,
[in, optional] PCWSTR pwszPin,
[in, optional] PCWSTR pwszFriendlyName,
[out, optional] DWORD *pcCertOut,
[out, optional] PCCERT_CONTEXT **prgpCertOut
)
{...}

Parameters
[in] hWndParent

Handle to a Parent Window.

[in] pbPFX

Pointer to a buffer that contains the PFX file.

[in] cbPFX

Size of pbPFX in bytes.

[in] ImportFlags

One or more ImportPFXFlag values.

[in, optional] pwszPassword

Pointer to a constant null-terminated string of 16-bit Unicode characters that is the Password for the PFX file.
[in, optional] pwszProviderName

Pointer to a constant null-terminated string of 16-bit Unicode characters that is the name of the crypto provider.
[in, optional] pwszReaderName

Pointer to a constant null-terminated string of 16-bit Unicode characters that is the name of the smart card
reader (can be nullptr).
[in, optional] pwszContainerNamePrefix
Pointer to a constant null-terminated string of 16-bit Unicode characters that is the name of the container (can
be nullptr).
[in, optional] pwszPin

Pointer to a constant null-terminated string of 16-bit Unicode characters that is the PIN of the smart card (can
be nullptr).
[in, optional] pwszFriendlyName

Pointer to a constant null-terminated string of 16-bit Unicode characters that is the friendly name of the
certificate (can be nullptr).
[out, optional] pcCertOut

Pointer to DWORD that receives the number of certificates successfully imported (can be nullptr).
[out, optional] prgpCertOut

Pointer to a pointer that receives a CERT_CONTEXT structure (can be nullptr).

Return value
None

Requirements

Target Platform Windows

Header certenroll.h
 ImportPFXToProviderFreeData callback function
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

Frees PFX certificate context(s).

Syntax
ImportPFXToProviderFreeData Importpfxtoproviderfreedata;

void Importpfxtoproviderfreedata(
[in] DWORD cCert,
[in, optional] PCCERT_CONTEXT *rgpCert
)
{...}

Parameters
[in] cCert

DWORD of the number of certificate contexts to free.

[in, optional] rgpCert

Pointer to a certificate Context containing to free.

Return value
None

Requirements

Target Platform Windows

Header certenroll.h
 InnerRequestLevel enumeration (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The InnerRequestLevel enumeration type specifies the containment level of a certificate request within a PKCS
#7 or Certificate Management over CMS (CMC) request. This enumeration is used by the GetInnerRequest
method on the IX509CertificateRequest interface and inherited by the IX509CertificateRequestPkcs7 and
IX509CertificateRequestCmc interfaces. You can use the enumeration values to retrieve the innermost nested
certificate or to iterate through all of the nesting levels.

Syntax
typedef enum InnerRequestLevel {
LevelInnermost = 0,
LevelNext = 1
} ;

Constants

LevelInnermost
Value: 0
Use to retrieve the most deeply nested request.

LevelNext
Value: 1
Use to retrieve the request at the next nesting level.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Header certenroll.h

See also
CertEnroll Enumerations
CertEnroll Interfaces
GetInnerRequest
 InstallResponseRestrictionFlags enumeration
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The InstallResponseRestrictionFlags enumeration contains flags that identify the restrictions placed on the
local installation of a certificate chain. This enumeration is used by the InstallResponse method on the
IX509Enrollment interface.

Syntax
typedef enum InstallResponseRestrictionFlags {
AllowNone = 0,
AllowNoOutstandingRequest = 0x1,
AllowUntrustedCertificate = 0x2,
AllowUntrustedRoot = 0x4
} ;

Constants

AllowNone
Value: 0
Does not allow the installation of untrusted certificates or certificates for which there is no corresponding request.

AllowNoOutstandingRequest
Value: 0x1
Creates the private key from the certificate response rather than from the dummy certificate. This makes the dummy
certificate optional. If this value is not set, the dummy certificate must exist, and the private key is extracted from it.

AllowUntrustedCertificate
Value: 0x2
Installs untrusted end entity and certification authority certificates. Certification authority certificates include root and
subordinate certification authority certificates. End entity certificates are installed to the personal store, and certification
authority certificates are installed to the certification authority store.

AllowUntrustedRoot
Value: 0x4
Performs the same action as the AllowUntrustedCer tificate flag but also installs the certificate even if the certificate chain
cannot be built because the root is not trusted.

Note On Windows Vista, the behavior of this flag is the same as that defined for the AllowUntrustedCertificate flag. You
can install an untrusted root beginning with Windows Vista with SP1.

Requirements
 Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Header certenroll.h

See also
CertEnroll Enumerations
CertEnroll Interfaces
InstallResponse
 IObjectId interface (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The IObjectId interface represents an object identifier (OID). OIDs are returned from numerous Certificate
Enrollment API properties, and they can be used to initialize the following objects:
IAlternativeName
ICertificatePolicy
ICryptAttribute
ISmimeCapability
IX509Attribute
IX509AttributeArchiveKey
IX509Extension
IX509ExtensionEnhancedKeyUsage
IX509ExtensionTemplate
All of the methods used to initialize an IObjectId object call the CryptoAPI CryptFindOIDInfo function which
retrieves the first registered CRYPT_OID_INFO structure that matches the specified parameters. The function
searches the registry and static memory on the local computer and Active Directory on the domain server. The
CRYPT_OID_INFO structure is declared in Wincrypt.h and has the following signature.

Note You cannot use the CRYPT_OID_INFO structure directly in the Certificate Enrollment API.

Inheritance
The IObjectId interface inherits from the IDispatch interface. IObjectId also has these types of members:

Methods
The IObjectId interface has these methods.

IObjectId::get_FriendlyName

Specifies and retrieves a display name for the object identifier.

IObjectId::get_Name

Retrieves a CERTENROLL_OBJECTID value that contains an object identifier.

IObjectId::get_Value

Retrieves a string that contains the dotted decimal object identifier (OID).

IObjectId::GetAlgorithmName

Retrieves the display name associated with an algorithm object identifier (OID).
 IObjectId::InitializeFromAlgorithmName

Initializes the object from an algorithm name or an object identifier.

IObjectId::InitializeFromName

Initializes the object from a CERTENROLL_OBJECTID enumeration value.

IObjectId::InitializeFromValue

Initializes the object from a string that contains a dotted decimal object identifier (OID).

IObjectId::put_FriendlyName

Specifies and retrieves a display name for the object identifier.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

See also
CertEnroll Interfaces
IDispatch
IObjectIds
 IObjectId::get_FriendlyName method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The FriendlyName property specifies and retrieves a display name for the object identifier. The display name
exists until another name is specified or the object lifetime has ended. This property is web enabled for output.
This property is read/write.

Syntax
HRESULT get_FriendlyName(
BSTR *pValue
);

Parameters
pValue

Return value
None

Remarks
You must call any of the following methods before you can retrieve this property value:
InitializeFromAlgorithmName
InitializeFromName
InitializeFromValue
You can also retrieve the following property values:
Name
Value

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll
See also
IObjectId
 IObjectId::get_Name method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Name property retrieves a CERTENROLL_OBJECTID value that contains an object identifier.
This property is read-only.

Syntax
HRESULT get_Name(
CERTENROLL_OBJECTID *pValue
);

Parameters
pValue

Return value
None

Remarks
You must call any of the following methods before you can retrieve this property value:
InitializeFromAlgorithmName
InitializeFromName
InitializeFromValue
You can also retrieve the following property values:
FriendlyName
Value

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IObjectID
 IObjectId::get_Value method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Value property retrieves a string that contains the dotted decimal object identifier (OID). This property is
web enabled.
This property is read-only.

Syntax
HRESULT get_Value(
BSTR *pValue
);

Parameters
pValue

Return value
None

Remarks
The dotted decimal format is discussed in the ASN.1 X.208 specification. For example, the string
1.2.840.10045.4.1. represents the iso(1)member-body(2)us(840)10045 signatures(4)sha1(1) object identifier.
You must call any of the following methods before you can retrieve this property value:
InitializeFromAlgorithmName
InitializeFromName
InitializeFromValue
You can also retrieve the following property values:
FriendlyName
Name

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h
 DLL CertEnroll.dll

See also
IObjectID
 IObjectId::GetAlgorithmName method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The GetAlgorithmName method retrieves the display name associated with an algorithm object identifier
(OID).

Syntax
HRESULT GetAlgorithmName(
[in] ObjectIdGroupId GroupId,
[in] ObjectIdPublicKeyFlags KeyFlags,
[out] BSTR *pstrAlgorithmName
);

Parameters
[in] GroupId

An ObjectIdGroupId enumeration value that specifies the OID group to search. This can be any of the following
algorithm groups:
XCN_CRYPT_HASH_ALG_OID_GROUP_ID
XCN_CRYPT_ENCRYPT_ALG_OID_GROUP_ID
XCN_CRYPT_PUBKEY_ALG_OID_GROUP_ID
XCN_CRYPT_SIGN_ALG_OID_GROUP_ID
In addition, you can also specify groups that do not contain cryptographic algorithms:
XCN_CRYPT_RDN_ATTR_OID_GROUP_ID
XCN_CRYPT_EXT_OR_ATTR_OID_GROUP_ID
XCN_CRYPT_ENHKEY_USAGE_OID_GROUP_ID
XCN_CRYPT_POLICY_OID_GROUP_ID
XCN_CRYPT_TEMPL ATE_OID_GROUP_ID
[in] KeyFlags

An ObjectIdPublicKeyFlags enumeration value that specifies whether to search for a signing or an encryption
algorithm. This can be one of the following values:
XCN_CRYPT_OID_INFO_PUBKEY_ANY
XCN_CRYPT_OID_INFO_PUBKEY_SIGN_KEY_FL AG
XCN_CRYPT_OID_INFO_PUBKEY_ENCRYPT_KEY_FL AG
You can use either of the last two values to disambiguate among algorithms such as RSA that can be used to both
encrypt and sign messages. You must also specify XCN_CRYPT_PUBKEY_ALG_OID_GROUP_ID in the GroupId
parameter. Specify XCN_CRYPT_OID_INFO_PUBKEY_ANY if you set the GroupId parameter to anything other
than XCN_CRYPT_PUBKEY_ALG_OID_GROUP_ID .
[out] pstrAlgorithmName

Pointer to a BSTR variable that contains the name.

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. Possible values include, but are not
limited to, those in the following table. For a list of common error codes, see Common HRESULT Values.

RET URN C O DE/ VA L UE DESC RIP T IO N

The string that contains the algorithm name is empty.

CERTSRV_E_PROPERTY_EMPTY

The algorithm name could not be found. You must call

OLE_E_BL ANK InitializeFromAlgorithmName before calling
GetAlgorithmName.

Remarks
You can use the XCN_CRYPT_ENCRYPT_ALG_OID_GROUP_ID constant to create a GroupId parameter value
that takes account of the key size for algorithms that can be identified by a variable bit length. For example, to
initialize an IObjectId object from a 192-bit AES algorithm, specify "AES" for the strAlgorithmName parameter,
shift the length left by 16, and perform a bitwise-OR combination on the shifted bit length and
XCN_CRYPT_ENCRYPT_ALG_OID_GROUP_ID .
If you set the GroupId parameter to anything other than XCN_CRYPT_PUBKEY_ALG_OID_GROUP_ID , specify
XCN_CRYPT_OID_INFO_PUBKEY_ANY for the KeyFlags parameter.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IObjectId
 IObjectId::InitializeFromAlgorithmName method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The InitializeFromAlgorithmName method initializes the object from an algorithm name or an object
identifier. This method has been provided primarily to enable you to initialize the object from a Cryptography
API: Next Generation (CNG) algorithm name. You can, however, specify any OID name. This method is web
enabled.

Syntax
HRESULT InitializeFromAlgorithmName(
[in] ObjectIdGroupId GroupId,
[in] ObjectIdPublicKeyFlags KeyFlags,
[in] AlgorithmFlags AlgFlags,
[in] BSTR strAlgorithmName
);

Parameters
[in] GroupId

An ObjectIdGroupId enumeration value that specifies the OID group to search. This can be any of the following
algorithm groups:
XCN_CRYPT_HASH_ALG_OID_GROUP_ID
XCN_CRYPT_ENCRYPT_ALG_OID_GROUP_ID
XCN_CRYPT_PUBKEY_ALG_OID_GROUP_ID
XCN_CRYPT_SIGN_ALG_OID_GROUP_ID
In addition, you can also specify groups that do not contain cryptographic algorithms:
XCN_CRYPT_RDN_ATTR_OID_GROUP_ID
XCN_CRYPT_EXT_OR_ATTR_OID_GROUP_ID
XCN_CRYPT_ENHKEY_USAGE_OID_GROUP_ID
XCN_CRYPT_POLICY_OID_GROUP_ID
XCN_CRYPT_TEMPL ATE_OID_GROUP_ID
[in] KeyFlags

An ObjectIdPublicKeyFlags enumeration value that specifies whether to search for a signing or an encryption
algorithm. This can be one of the following values:
XCN_CRYPT_OID_INFO_PUBKEY_SIGN_KEY_FL AG
XCN_CRYPT_OID_INFO_PUBKEY_ENCRYPT_KEY_FL AG
You can use either value to disambiguate among algorithms such as RSA that can be used to both encrypt and sign
messages. You must also specify XCN_CRYPT_PUBKEY_ALG_OID_GROUP_ID in the GroupId parameter.
[in] AlgFlags

An AlgorithmFlags enumeration value. This can be one of the following values:

 AlgorithmFlagsNone
AlgorithmFlagsWrap
If you specify XCN_CRYPT_ENCRYPT_ALG_OID_GROUP_ID for the GroupId parameter, you can use the
AlgorithmFlags enumeration to search for an OID that can be used to wrap a key. For example, you can retrieve
information about the AES128wrap algorithm if you specify a bit length of 128 (see the Remarks section), set the
strAlgorithmName parameter to AES, and specify AlgorithmFlagsWrap .
[in] strAlgorithmName

A BSTR variable that contains the name. You can specify a name, or an OID in dotted decimal format. The
method verifies that the format is consistent with the ASN.1 X.208 standard. For more information about CNG
algorithm names, see CNG Algorithm Identifiers.

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. Possible values include, but are not
limited to, those in the following table. For a list of common error codes, see Common HRESULT Values.

RET URN C O DE/ VA L UE DESC RIP T IO N

The OID information could not be found.

CERTSRV_E_PROPERTY_EMPTY

The algorithm name is not recognized.

CRYPT_E_UNKNOWN_ALGO

The object is already initialized.

HRESULT_FROM_WIN32(ERROR_ALREADY_INITIALIZE
D)

Remarks
You can use the upper 16 bits of the GroupId parameter to specify the key size for algorithms that accept a
variable bit length. For example, to initialize an IObjectId object from a 192-bit AES algorithm, specify "AES" for
the strAlgorithmName parameter, shift the length left by 16, and perform a bitwise-OR combination on the
shifted bit length and the GroupId value.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll
See also
IObjectId
 IObjectId::InitializeFromName method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The InitializeFromName method initializes the object from a CERTENROLL_OBJECTID enumeration value. This
method is web enabled.

Syntax
HRESULT InitializeFromName(
[in] CERTENROLL_OBJECTID Name
);

Parameters
[in] Name

A CERTENROLL_OBJECTID enumeration value.

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. Possible values include, but are not
limited to, those in the following table. For a list of common error codes, see Common HRESULT Values.

RET URN C O DE/ VA L UE DESC RIP T IO N

The OID information could not be found.

CERTSRV_E_PROPERTY_EMPTY

The algorithm name is not recognized.

CRYPT_E_UNKNOWN_ALGO

The object is already initialized.

HRESULT_FROM_WIN32(ERROR_ALREADY_INITIALIZE
D)

Remarks
Every CERTENROLL_OBJECTID value is associated with an ASN.1 object identifier. For example, the value
XCN_OID_ECDSA_SHA1 is associated with a string that contains 1.2.840.10045.4.1. This is the dotted decimal
representation of the iso(1)member-body(2)us(840)10045 signatures(4)sha1(1) object identifier.
The InitializeFromName method searches the registry for information associated with the ASN.1 object
identifier. If information is found, the method internally populates a CRYPT_OID_INFO structure and associates it
with the object. The method also uses the local information to initialize, if possible, the display name of the
object.
You can call the following properties to retrieve information about an initialized IObjectId object:
 FriendlyName
Name
Value

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
FriendlyName
IObjectID
 IObjectId::InitializeFromValue method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The InitializeFromValue method initializes the object from a string that contains a dotted decimal object
identifier (OID). This method is web enabled.

Syntax
HRESULT InitializeFromValue(
[in] BSTR strValue
);

Parameters
[in] strValue

A BSTR variable that contains the dotted decimal representation of the ASN.1 object identifier. For example, the
value 1.2.840.10045.4.1. represents the iso(1)member-body(2)us(840)10045 signatures(4)sha1(1) object
identifier.

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. Possible values include, but are not
limited to, those in the following table. For a list of common error codes, see Common HRESULT Values.

RET URN C O DE/ VA L UE DESC RIP T IO N

The OID information could not be found.

CERTSRV_E_PROPERTY_EMPTY

The algorithm name is not recognized.

CRYPT_E_UNKNOWN_ALGO

The object is already initialized.

HRESULT_FROM_WIN32(ERROR_ALREADY_INITIALIZE
D)

Remarks
You can call the following properties to retrieve information about an initialized IObjectId object:
FriendlyName
Name
Value

Requirements
 Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IObjectID
 IObjectId::put_FriendlyName method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The FriendlyName property specifies and retrieves a display name for the object identifier. The display name
exists until another name is specified or the object lifetime has ended. This property is web enabled for output.
This property is read/write.

Syntax
HRESULT put_FriendlyName(
BSTR Value
);

Parameters
Value

Return value
None

Remarks
You must call any of the following methods before you can retrieve this property value:
InitializeFromAlgorithmName
InitializeFromName
InitializeFromValue
You can also retrieve the following property values:
Name
Value

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll
See also
IObjectId
 IObjectIds interface (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The IObjectIds interface defines methods and properties that enable you to manage a collection of IObjectId
objects.

Inheritance
The IObjectIds interface inherits from the IDispatch interface. IObjectIds also has these types of members:

Methods
The IObjectIds interface has these methods.

IObjectIds::Add

Adds an IObjectId object to the collection.

IObjectIds::AddRange

Adds a range of IObjectId objects to the collection.

IObjectIds::Clear

Removes all IObjectId objects from the collection.

IObjectIds::get__NewEnum

Retrieves the enumerator for the collection.

IObjectIds::get_Count

Retrieves the number of objects in the collection.

IObjectIds::get_ItemByIndex

Retrieves an IObjectId object from the collection by index number.

IObjectIds::Remove

Removes an IObjectId object from the collection by index value.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]
 Target Platform Windows

Header certenroll.h

See also
CertEnroll Interfaces
IDispatch
IObjectId
 IObjectIds::Add method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Add method adds an IObjectId object to the collection. This method is web enabled.

Syntax
HRESULT Add(
[in] IObjectId *pVal
);

Parameters
[in] pVal

Pointer to an IObjectId interface that represents the object identifier to add.

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IObjectId
IObjectIds
 IObjectIds::AddRange method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The AddRange method adds a range of IObjectId objects to the collection.

Syntax
HRESULT AddRange(
[in] IObjectIds *pValue
);

Parameters
[in] pValue

Pointer to an IObjectIds interface that represents the collection to add.

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IObjectId
IObjectIds
 IObjectIds::Clear method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Clear method removes all IObjectId objects from the collection.

Syntax
HRESULT Clear();

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IObjectId
IObjectIds
 IObjectIds::get__NewEnum method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The NewEnum property retrieves the enumerator for the collection.

This property is read-only.

Syntax
HRESULT get__NewEnum(
LPUNKNOWN *pVal
);

Parameters
pVal

Return value
None

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IObjectId
IObjectIds
 IObjectIds::get_Count method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Count property retrieves the number of objects in the collection. This property is web enabled.
This property is read-only.

Syntax
HRESULT get_Count(
long *pVal
);

Parameters
pVal

Return value
None

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IObjectId
IObjectIds
 IObjectIds::Remove method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Remove method removes an IObjectId object from the collection by index value.

Syntax
HRESULT Remove(
[in] LONG Index
);

Parameters
[in] Index

A LONG variable that contains the index of the object to remove.

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IObjectId
IObjectIds
 IPolicyQualifier interface (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The IPolicyQualifier interface represents a qualifier that can be associated with a certificate policy. The
following syntax shows the Abstract Syntax Notation One (ASN.1) structures that define certificate policies and
their associated qualifiers. The value is encoded by using Distinguished Encoding Rules (DER) and included in
the certificate request with the policy object it qualifies.

----------------------------------------------------------------------
-- CertificatePolicies
-- XCN_OID_CERT_POLICIES (2.5.29.32)
----------------------------------------------------------------------

CertificatePolicies ::= SEQUENCE OF PolicyInformation

PolicyInformation ::= SEQUENCE

{
policyIdentifier EncodedObjectID,
policyQualifiers PolicyQualifiers OPTIONAL
}

PolicyQualifiers ::= SEQUENCE OF PolicyQualifierInfo

PolicyQualifierInfo ::= SEQUENCE

{
policyQualifierId EncodedObjectID,
qualifier NOCOPYANY OPTIONAL
}

----------------------------------------------------------------------
-- UserNotice
-- XCN_OID_PKIX_POLICY_QUALIFIER_USERNOTICE (1.3.6.1.5.5.7.2.2)
----------------------------------------------------------------------

UserNotice ::= SEQUENCE

{
noticeRef, -- Not supported
explicitText -- Not supported
}

----------------------------------------------------------------------
-- Certification Practice Statement (CPS) qualifier
-- XCN_OID_PKIX_POLICY_QUALIFIER_CPS (1.3.6.1.5.5.7.2.1)
----------------------------------------------------------------------

CpsURLs ::= SEQUENCE OF SEQUENCE

{
url IA5String,
digestAlgorithmId, -- Not supported
digest -- Not supported
}

Policy qualifiers can be used when an object identifier (OID) is considered insufficient to fully identify a policy.
Qualifiers are defined by using the IPolicyQualifier interface and can be associated with a policy by adding
qualifiers to the IPolicyQualifiers collection retrieved from an ICertificatePolicy object. A Windows certification
authority supports the following qualifiers.
 VA L UE DESC RIP T IO N

XCN_OID_PKIX_POLICY_QUALIFIER_USERNOTICE(1.3.6.1.5.5 Contains a notice to be displayed to any user who relies on

.7.2.2) the certificate.

XCN_OID_PKIX_POLICY_QUALIFIER_CPS(1.3.6.1.5.5.7.2.1) Identifies a pointer to a URI that contains the Certification

Practice Statement (CPS) defined by the certification
authority.

Unless one user notice in the chain duplicates another, all notices in the certificate path should be displayed to
the relying party. To minimize duplication, this qualifier should be present only in the end entity certificate and
certification authority certificates issued to other organizations. The user notice has two optional fields,
noticeRef and explicitText , that are not supported. Policies and policy qualifiers are used in
IX509ExtensionCertificatePolicies objects.

Inheritance
The IPolicyQualifier interface inherits from the IDispatch interface. IPolicyQualifier also has these types of
members:

Methods
The IPolicyQualifier interface has these methods.

IPolicyQualifier::get_ObjectId

Retrieves the object identifier (OID) for the qualifier.

IPolicyQualifier::get_Qualifier

Retrieves a string that contains the qualifier used to initialize the object.

IPolicyQualifier::get_RawData

Retrieves the Distinguished Encoding Rules (DER) encoded qualifier object.

IPolicyQualifier::get_Type

Retrieves the qualifier type.

IPolicyQualifier::InitializeEncode

Initializes the object from a string and a value that identifies the qualifier type.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]
 Target Platform Windows

Header certenroll.h

See also
CertEnroll Interfaces
IDispatch
IPolicyQualifier
IX509ExtensionCertificatePolicies
 IPolicyQualifier::get_ObjectId method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The ObjectId property retrieves the object identifier (OID) for the qualifier.
This property is read-only.

Syntax
HRESULT get_ObjectId(
IObjectId **ppValue
);

Parameters
ppValue

Return value
None

Remarks
If you specified PolicyQualifierTypeUrl in the Type parameter of the InitializeEncode method,
XCN_OID_PKIX_POLICY_QUALIFIER_CPS (1.3.6.1.5.5.7.2.1) is returned. If you specified
PolicyQualifierTypeUserNotice , XCN_OID_PKIX_POLICY_QUALIFIER_USERNOTICE (1.3.6.1.5.5.7.2.2) is
returned.
You must call InitializeEncode to initialize the qualifier object before you can retrieve this property. You can also
retrieve the following properties for this object:
The Qualifier property retrieves the string specified for the strQualifier parameter of the InitializeEncode
method.
The RawData property retrieves the Distinguished Encoding Rules (DER) encoded qualifier.
The Type property retrieves a value of the PolicyQualifierType enumeration that specifies the qualifier type.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll
See also
IPolicyQualifier
 IPolicyQualifier::get_Qualifier method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Qualifier property retrieves a string that contains the qualifier used to initialize the object.
This property is read-only.

Syntax
HRESULT get_Qualifier(
BSTR *pValue
);

Parameters
pValue

Return value
None

Remarks
You must call InitializeEncode to initialize the qualifier object before you can retrieve this property. The value
retrieved is the string entered in the strQualifier parameter of that method. You can also retrieve the following
properties for this object:
The ObjectId property retrieves an object identifier (OID) that identifies whether the qualifier is a CPS or a
user notice.
The RawData property retrieves the Distinguished Encoding Rules (DER) encoded qualifier.
The Type property retrieves a value of the PolicyQualifierType enumeration that specifies the qualifier type.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IPolicyQualifier
 IPolicyQualifier::get_RawData method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The RawData property retrieves the Distinguished Encoding Rules (DER) encoded qualifier object.
This property is read-only.

Syntax
HRESULT get_RawData(
EncodingType Encoding,
BSTR *pValue
);

Parameters
Encoding

pValue

Return value
None

Remarks
You must call InitializeEncode to initialize the qualifier object before you can retrieve this property. The value
retrieved is the DER-encoded byte array that contains the qualifier. The byte array is represented as a string. You
can use the EncodingType enumeration to apply Unicode encoding to the string.
You can also retrieve the following properties for this object:
The ObjectId property retrieves an object identifier (OID) that identifies whether the qualifier is a CPS or a
user notice.
The Qualifier property retrieves the string specified for the strQualifier parameter of the InitializeEncode
method.
The Type property retrieves a value of the PolicyQualifierType enumeration that specifies the qualifier type.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h
 DLL CertEnroll.dll

See also
IPolicyQualifier
 IPolicyQualifier::get_Type method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Type property retrieves the qualifier type.

This property is read-only.

Syntax
HRESULT get_Type(
PolicyQualifierType *pValue
);

Parameters
pValue

Return value
None

Remarks
You must call InitializeEncode to initialize the qualifier object before you can retrieve this property. The value
retrieved is one of the following values of the PolicyQualifierType enumeration.

VA L UE DESC RIP T IO N

PolicyQualifierTypeUrl The qualifier is a URL that points to a Certification Practice

Statement (CPS).

PolicyQualifierTypeUserNotice The qualifier is a string to be displayed to users who rely on

the certificate.

You can also retrieve the following properties for this object:
The ObjectId property retrieves an object identifier (OID) that identifies whether the qualifier is a CPS or a
user notice.
The Qualifier property retrieves the string specified for the strQualifier parameter of the InitializeEncode
method.
The RawData property retrieves the Distinguished Encoding Rules (DER) encoded qualifier.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

 Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IPolicyQualifier
 IPolicyQualifier::InitializeEncode method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The InitializeEncode method initializes the object from a string and a value that identifies the qualifier type.

Syntax
HRESULT InitializeEncode(
[in] BSTR strQualifier,
[in] PolicyQualifierType Type
);

Parameters
[in] strQualifier

A BSTR variable that contains the qualifier.

[in] Type

A PolicyQualifierType enumeration value that specifies the type of qualifier applied to a certificate policy. This
can be one of the following values.

VA L UE M EA N IN G

The qualifier type is not specified.

PolicyQualifierTypeUnknown

The qualifier is a URL that points to a Certification Practice

PolicyQualifierTypeUrl Statement (CPS) that has been defined by the certification
authority to outline the policies under which the certificate
was issued and the purposes for which the certificate can be
used.

The qualifier is a text statement to be displayed by the

PolicyQualifierTypeUserNotice application to any user who relies on the certificate. The user
notice identifies the permitted uses of the certificate.

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. Possible values include, but are not
limited to, those in the following table. For a list of common error codes, see Common HRESULT Values.

RET URN C O DE DESC RIP T IO N

 The object is already initialized.
HRESULT_FROM_WIN32(ERROR_ALREADY_INITIALIZE
D)

Remarks
If you specify PolicyQualifierTypeUrl in the Type parameter, this method associates the string entered in the
strQualifier parameter with the XCN_OID_PKIX_POLICY_QUALIFIER_CPS (1.3.6.1.5.5.7.2.1) object identifier
(OID) and encodes it by using Distinguished Encoding Rules (DER). The URL is encoded as an Abstract Syntax
Notation One (ASN.1) IA5 string.
If you specify PolicyQualifierTypeUserNotice in the Type parameter, this method associates the string
entered in the strQualifier parameter with the XCN_OID_PKIX_POLICY_QUALIFIER_USERNOTICE
(1.3.6.1.5.5.7.2.2) OID and encodes it by using DER.
You can retrieve the following properties for this object:
The ObjectId property retrieves an OID that identifies whether the qualifier is a CPS or a user notice.
The Qualifier property retrieves the string specified for the strQualifier parameter of the InitializeEncode
method.
The RawData property retrieves the DER-encoded qualifier.
The Type property retrieves a value of the PolicyQualifierType enumeration that specifies the qualifier type.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IPolicyQualifier
 IPolicyQualifiers interface (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The IPolicyQualifiers interface defines methods and properties that enable you to manage a collection of
IPolicyQualifier objects.

Inheritance
The IPolicyQualifiers interface inherits from the IDispatch interface. IPolicyQualifiers also has these types of
members:

Methods
The IPolicyQualifiers interface has these methods.

IPolicyQualifiers::Add

Adds an object to the collection.

IPolicyQualifiers::Clear

Removes all objects from the collection.

IPolicyQualifiers::get__NewEnum

Retrieves the enumerator for the collection.

IPolicyQualifiers::get_Count

Retrieves the number of objects in the collection.

IPolicyQualifiers::get_ItemByIndex

Retrieves an object from the collection by index number.

IPolicyQualifiers::Remove

Removes an object from the collection by index value.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

 Header certenroll.h

See also
CertEnroll Interfaces
IDispatch
IPolicyQualifier
 IPolicyQualifiers::Add method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Add method adds an object to the collection.

Syntax
HRESULT Add(
[in] IPolicyQualifier *pVal
);

Parameters
[in] pVal

Pointer to the IPolicyQualifier interface to add.

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IPolicyQualifier
IPolicyQualifiers
 IPolicyQualifiers::Clear method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Clear method removes all objects from the collection.

Syntax
HRESULT Clear();

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IPolicyQualifier
IPolicyQualifiers
 IPolicyQualifiers::get__NewEnum method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The _NewEnum property retrieves the enumerator for the collection.

This property is read-only.

Syntax
HRESULT get__NewEnum(
LPUNKNOWN *pVal
);

Parameters
pVal

Return value
None

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IPolicyQualifier
IPolicyQualifiers
 IPolicyQualifiers::get_Count method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Count property retrieves the number of objects in the collection.

This property is read-only.

Syntax
HRESULT get_Count(
long *pVal
);

Parameters
pVal

Return value
None

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IPolicyQualifier
IPolicyQualifiers
 IPolicyQualifiers::Remove method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Remove method removes an object from the collection by index value.

Syntax
HRESULT Remove(
[in] LONG Index
);

Parameters
[in] Index

A LONG variable that contains the index of the object to remove.

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IPolicyQualifier
IPolicyQualifiers
 ISignerCertificate interface (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The ISignerCer tificate interface represents a signing certificate that enables you to sign a certificate request.
When you initialize the interface, the Certificate Enrollment Control retrieves the signing certificate from the
personal store and uses it to find an associated private key. You can use the private key to sign a PKCS #7 or a
CMC request but not a PKCS #10 request. PKCS #10 requests must be signed by using the private key associated
with the public key included in the request. Self-signed certificates can be signed by using the private key
associated with the request or the private key associated with the signing certificate. This is summarized in the
following table.

REQ UEST T Y P E ( IN T ERFA C E) SIGN IN G C ERT IF IC AT ES

PKCS #7(IX509CertificateRequestPkcs7) 1

PKCS #10(IX509CertificateRequestPkcs10) 0

CMC(IX509CertificateRequestCmc) 0 or more

Self-signed(IX509CertificateRequestCertificate) 0 or 1

When signing a CMC request, the data to be signed consists of a Distinguished Encoding Rules (DER) encoded
CmcData object wrapped in a CMS SignedData object. The encr yptedDigest field of the SignerInfo object
contains a signature, and multiple SignerInfo objects can be associated with the request.
 ---------------------------------------------------------------------
-- CMC request data
---------------------------------------------------------------------

CmcData ::= SEQUENCE

{
controlSequence SEQUENCE OF TaggedAttribute,
reqSequence SEQUENCE OF TaggedRequest,
cmsSequence SEQUENCE OF TaggedContentInfo,
otherMsgSequence SEQUENCE OF TaggedOtherMs
}

---------------------------------------------------------------------
-- SignedData object that wraps the CMC request
---------------------------------------------------------------------

SignedData ::= SEQUENCE

{
version INTEGER,
digestAlgorithms DigestAlgorithmIdentifiers,
contentInfo ContentInfo,
certificates [0] IMPLICIT Certificates OPTIONAL,
crls [1] IMPLICIT CertificateRevocationLists OPTIONAL,
signerInfos SignerInfos
}

DigestAlgorithmIdentifiers ::= SET OF DigestAlgorithmIdentifier

DigestAlgorithmIdentifiersNC ::= SET OF DigestAlgorithmIdentifierNC

SignerInfos ::= SET OF SignerInfo

SignerInfo ::= SEQUENCE

{
version INTEGER,
sid CertIdentifier,
digestAlgorithm DigestAlgorithmIdentifier,
authenticatedAttributes [0] IMPLICIT Attributes OPTIONAL,
digestEncryptionAlgorithm DigestEncryptionAlgId,
encryptedDigest EncryptedDigest,
unauthenticatedAttributes [1] IMPLICIT Attributes OPTIONAL
}

Each ISignerCer tificate object is associated with one IX509SignatureInformation object that identifies the
hashing and public key algorithms used. This object is created and initialized when the ISignerCer tificate
object is initialized.

Inheritance
The ISignerCer tificate interface inherits from the IDispatch interface. ISignerCer tificate also has these types
of members:

Methods
The ISignerCer tificate interface has these methods.

ISignerCertificate::get_Certificate

Retrieves a Distinguished Encoding Rules (DER) encoded byte array that contains the certificate.
 ISignerCertificate::get_ParentWindow

Specifies or retrieves the ID of the window used to display signing certificate information.

ISignerCertificate::get_PrivateKey

Retrieves the private key associated with the ISignerCertificate object.

ISignerCertificate::get_SignatureInformation

Retrieves an IX509SignatureInformation object that contains information about the certificate signature.

ISignerCertificate::get_Silent

Specifies or retrieves a Boolean value that indicates whether the user is notified when the private key is used to sign a
certificate request.

ISignerCertificate::get_UIContextMessage

Specifies or retrieves a string that contains user interface text associated with the signing certificate.

ISignerCertificate::Initialize

Initializes the object from a signing certificate.

ISignerCertificate::put_ParentWindow

Specifies or retrieves the ID of the window used to display signing certificate information.

ISignerCertificate::put_Pin

Specifies a personal identification number (PIN) used to authenticate a smart card user.

ISignerCertificate::put_Silent

Specifies or retrieves a Boolean value that indicates whether the user is notified when the private key is used to sign a
certificate request.

ISignerCertificate::put_UIContextMessage

Specifies or retrieves a string that contains user interface text associated with the signing certificate.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h
See also
CertEnroll Interfaces
IDispatch
ISignerCertificates
 ISignerCertificate::get_Certificate method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Cer tificate property retrieves a Distinguished Encoding Rules (DER) encoded byte array that contains the
certificate. The DER-encoded byte array is represented by a Unicode-encoded string.
This property is read-only.

Syntax
HRESULT get_Certificate(
EncodingType Encoding,
BSTR *pValue
);

Parameters
Encoding

pValue

Return value
None

Remarks
Call the Initialize method to specify the certificate. You can also call the following properties to retrieve
information about the signing certificate object:
Pin
PrivateKey
SignatureInformation
Silent
UIContextMessage

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h
 DLL CertEnroll.dll

See also
ISignerCertificate
 ISignerCertificate::get_ParentWindow method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The ParentWindow property specifies or retrieves the ID of the window used to display signing certificate
information.
This property is read/write.

Syntax
HRESULT get_ParentWindow(
LONG *pValue
);

Parameters
pValue

Return value
None

Remarks
Call this property to specify a window ID before calling the Initialize method. The ParentWindow property
internally sets the window ID on the IX509PrivateKey object. You can retrieve the private key object by calling
the PrivateKey property. You can call the following properties to retrieve additional information about the
signing certificate object:
Certificate
Pin
SignatureInformation
Silent
UIContextMessage

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h
 DLL CertEnroll.dll

See also
ISignerCertificate
 ISignerCertificate::get_PrivateKey method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The PrivateKey property retrieves the private key associated with the ISignerCertificate object.
This property is read-only.

Syntax
HRESULT get_PrivateKey(
IX509PrivateKey **ppValue
);

Parameters
ppValue

Return value
None

Remarks
When you call the Initialize method the Certificate Enrollment Control retrieves the signing certificate from the
personal store and uses it to find an associated private key. You can also call the following properties to retrieve
information about the signing certificate object:
Certificate
ParentWindow
Pin
SignatureInformation
Silent
UIContextMessage

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h
 DLL CertEnroll.dll

See also
ISignerCertificate
 ISignerCertificate::get_SignatureInformation method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The SignatureInformation property retrieves an IX509SignatureInformation object that contains information

about the certificate signature.
This property is read-only.

Syntax
HRESULT get_SignatureInformation(
IX509SignatureInformation **ppValue
);

Parameters
ppValue

Return value
None

Remarks
When you call the Initialize method the Certificate Enrollment Control creates an IX509SignatureInformation
object. You can also call the following properties to retrieve information about the signing certificate object:
Certificate
ParentWindow
Pin
PrivateKey
Silent
UIContextMessage

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h
 DLL CertEnroll.dll

See also
ISignerCertificate
 ISignerCertificate::get_Silent method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Silent property specifies or retrieves a Boolean value that indicates whether the user is notified when the
private key is used to sign a certificate request.
This property is read/write.

Syntax
HRESULT get_Silent(
VARIANT_BOOL *pValue
);

Parameters
pValue

Return value
None

Remarks
Call this property to specify a value before calling the Initialize method. Setting this property also sets the Silent
property on the IX509PrivateKey object. You can retrieve the private key object by calling PrivateKey. You can call
the following properties to retrieve additional information about the signing certificate object:
Certificate
ParentWindow
Pin
SignatureInformation
UIContextMessage

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll
See also
ISignerCertificate
 ISignerCertificate::get_UIContextMessage method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The UIContextMessage property specifies or retrieves a string that contains user interface text associated with
the signing certificate.
This property is read/write.

Syntax
HRESULT get_UIContextMessage(
BSTR *pValue
);

Parameters
pValue

Return value
None

Remarks
Call this property to specify a value before calling the Initialize method. You can also call the following
properties to retrieve additional information about the signing certificate object:
Certificate
ParentWindow
Pin
PrivateKey
SignatureInformation
Silent

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h
 DLL CertEnroll.dll

See also
ISignerCertificate
 ISignerCertificate::Initialize method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Initialize method initializes the object from a signing certificate.

Syntax
HRESULT Initialize(
[in] VARIANT_BOOL MachineContext,
[in] X509PrivateKeyVerify VerifyType,
[in] EncodingType Encoding,
[in] BSTR strCertificate
);

Parameters
[in] MachineContext

A VARIANT_BOOL variable that indicates whether to search the local computer certificate store context or the
user context to find the certificate identified by the strCertificate parameter. Specify VARIANT_TRUE for the
computer and VARIANT_FALSE for the user.
[in] VerifyType

An X509PrivateKeyVerify enumeration value that specifies whether the private key used to sign the certificate
must be verified and, if so, whether the verification must be silent or allows user input.
[in] Encoding

An EncodingType enumeration value that specifies the type of Unicode encoding applied to the Distinguished
Encoding Rules (DER) encoded certificate string.
[in] strCertificate

A BSTR variable that contains the DER-encoded certificate.

Beginning with Windows 7 and Windows Server 2008 R2, you can specify a certificate thumb print or serial
number rather than an encoded certificate. Doing so causes the function to search the appropriate local stores
for the matching certificate. Keep in mind the following points:
The BSTR must be an even number of hexadecimal digits.
Whitespace between hexadecimal pairs is ignored.
The Encoding parameter must be set to XCN_CRYPT_STRING_HEXRAW .
The MachineContext parameter determines whether the user or computer stores or both are searched.
If a private key is needed, only the personal and request stores are searched.
If a private key is not needed, the root and intermediate CA stores are also searched.

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. Possible values include, but are not
limited to, those in the following table. For a list of common error codes, see Common HRESULT Values.

RET URN C O DE/ VA L UE DESC RIP T IO N

The ISignerCertificate object has already been initialized.

HRESULT_FROM_WIN32(ERROR_ALREADY_INITIALIZE
D)

Remarks
The Initialize method:
Verifies whether the private key associated with the certificate exists.
Creates an IX509SignatureInformation object and assigns it to the ISignerCertificate object.
Retrieves the public key algorithm from the private key.
Assigns the public key algorithm to the IX509SignatureInformation object.
Set the following properties before calling Initialize :
ParentWindow
Pin
Silent
UIContextMessage

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
ISignerCertificate
 ISignerCertificate::put_ParentWindow method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The ParentWindow property specifies or retrieves the ID of the window used to display signing certificate
information.
This property is read/write.

Syntax
HRESULT put_ParentWindow(
LONG Value
);

Parameters
Value

Return value
None

Remarks
Call this property to specify a window ID before calling the Initialize method. The ParentWindow property
internally sets the window ID on the IX509PrivateKey object. You can retrieve the private key object by calling
the PrivateKey property. You can call the following properties to retrieve additional information about the
signing certificate object:
Certificate
Pin
SignatureInformation
Silent
UIContextMessage

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h
 DLL CertEnroll.dll

See also
ISignerCertificate
 ISignerCertificate::put_Pin method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Pin property specifies a personal identification number (PIN) used to authenticate a smart card user. A user
must be authenticated before accessing the private key container on the smart card.
This property is write-only.

Syntax
HRESULT put_Pin(
BSTR Value
);

Parameters
Value

Return value
None

Remarks
Call this property to specify a value before calling the Initialize method. The Pin property internally sets the pin
number on the IX509PrivateKey object. You can retrieve the private key object by calling PrivateKey. You can call
the following properties to retrieve additional information about the signing certificate object:
Certificate
ParentWindow
SignatureInformation
Silent
UIContextMessage

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll
See also
ISignerCertificate
 ISignerCertificate::put_Silent method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Silent property specifies or retrieves a Boolean value that indicates whether the user is notified when the
private key is used to sign a certificate request.
This property is read/write.

Syntax
HRESULT put_Silent(
VARIANT_BOOL Value
);

Parameters
Value

Return value
None

Remarks
Call this property to specify a value before calling the Initialize method. Setting this property also sets the Silent
property on the IX509PrivateKey object. You can retrieve the private key object by calling PrivateKey. You can call
the following properties to retrieve additional information about the signing certificate object:
Certificate
ParentWindow
Pin
SignatureInformation
UIContextMessage

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll
See also
ISignerCertificate
 ISignerCertificate::put_UIContextMessage method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The UIContextMessage property specifies or retrieves a string that contains user interface text associated with
the signing certificate.
This property is read/write.

Syntax
HRESULT put_UIContextMessage(
BSTR Value
);

Parameters
Value

Return value
None

Remarks
Call this property to specify a value before calling the Initialize method. You can also call the following
properties to retrieve additional information about the signing certificate object:
Certificate
ParentWindow
Pin
PrivateKey
SignatureInformation
Silent

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h
 DLL CertEnroll.dll

See also
ISignerCertificate
 ISignerCertificates interface (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The ISignerCer tificates interface defines the following methods and properties to manage a collection of
ISignerCertificate objects.

Inheritance
The ISignerCer tificates interface inherits from the IDispatch interface. ISignerCer tificates also has these
types of members:

Methods
The ISignerCer tificates interface has these methods.

ISignerCertificates::Add

Adds an ISignerCertificate object to the collection.

ISignerCertificates::Clear

Removes all ISignerCertificate objects from the collection.

ISignerCertificates::Find

Retrieves the index number of an ISignerCertificate object.

ISignerCertificates::get__NewEnum

Retrieves the enumerator for the collection.

ISignerCertificates::get_Count

Retrieves the number of ISignerCertificate objects in the collection.

ISignerCertificates::get_ItemByIndex

Retrieves an ISignerCertificate object from the collection by index number.

ISignerCertificates::Remove

Removes an ISignerCertificate object from the collection by index number.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

 Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

See also
Certificate Enrollment API
IDispatch
ISignerCertificate
 ISignerCertificates::Add method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Add method adds an ISignerCertificate object to the collection.

Syntax
HRESULT Add(
[in] ISignerCertificate *pVal
);

Parameters
[in] pVal

Pointer to an ISignerCertificate object to add to the collection.

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
ISignerCertificate
ISignerCertificates
 ISignerCertificates::Clear method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Clear method removes all ISignerCertificate objects from the collection.

Syntax
HRESULT Clear();

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
ISignerCertificate
ISignerCertificates
 ISignerCertificates::Find method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Find method retrieves the index number of an ISignerCertificate object.

Syntax
HRESULT Find(
[in] ISignerCertificate *pSignerCert,
[out] LONG *piSignerCert
);

Parameters
[in] pSignerCert

Pointer to the ISignerCertificate interface.

[out] piSignerCert

Pointer to a LONG variable that receives the index number.

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
ISignerCertificate
ISignerCertificates
 ISignerCertificates::get__NewEnum method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The _NewEnum property retrieves the enumerator for the collection.

This property is read-only.

Syntax
HRESULT get__NewEnum(
LPUNKNOWN *pVal
);

Parameters
pVal

Return value
None

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
ISignerCertificate
ISignerCertificates
 ISignerCertificates::get_Count method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Count property retrieves the number of ISignerCertificate objects in the collection.
This property is read-only.

Syntax
HRESULT get_Count(
long *pVal
);

Parameters
pVal

Return value
None

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
ISignerCertificate
ISignerCertificates
 ISignerCertificates::Remove method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Remove method removes an ISignerCertificate object from the collection by index number.

Syntax
HRESULT Remove(
[in] LONG Index
);

Parameters
[in] Index

A LONG variable that contains the index of the object to remove.

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
ISignerCertificate
ISignerCertificates
 ISmimeCapabilities interface (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The ISmimeCapabilities interface defines the following methods and properties to manage a collection of
ISmimeCapability objects.

Inheritance
The ISmimeCapabilities interface inherits from the IDispatch interface. ISmimeCapabilities also has these
types of members:

Methods
The ISmimeCapabilities interface has these methods.

ISmimeCapabilities::Add

Adds an ISmimeCapability object to the collection.

ISmimeCapabilities::AddAvailableSmimeCapabilities

Adds ISmimeCapability objects to the collection by identifying the encryption algorithms supported by the default RSA
cryptographic provider.

ISmimeCapabilities::AddFromCsp

Adds objects to the collection by identifying the encryption algorithms supported by a specific cryptographic provider.

ISmimeCapabilities::Clear

Removes all objects from the collection.

ISmimeCapabilities::get__NewEnum

Retrieves the enumerator for the collection.

ISmimeCapabilities::get_Count

Retrieves the number of objects in the collection.

ISmimeCapabilities::get_ItemByIndex

Retrieves an object from the collection by index number.

ISmimeCapabilities::Remove

Removes an object from the collection by index value.

Requirements
 Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

See also
IDispatch
 ISmimeCapabilities::Add method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Add method adds an ISmimeCapability object to the collection.

Syntax
HRESULT Add(
[in] ISmimeCapability *pVal
);

Parameters
[in] pVal

Pointer to the ISmimeCapability interface to add.

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
ISmimeCapabilities
ISmimeCapability
 ISmimeCapabilities::AddAvailableSmimeCapabilities
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The AddAvailableSmimeCapabilities method adds ISmimeCapability objects to the collection by identifying

the encryption algorithms supported by the default RSA cryptographic provider.

Syntax
HRESULT AddAvailableSmimeCapabilities(
[in] VARIANT_BOOL MachineContext
);

Parameters
[in] MachineContext

A VARIANT_BOOL variable that identifies the certificate store context. Specify VARIANT_TRUE for the
computer and VARIANT_FALSE for the user.

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
ISmimeCapabilities
ISmimeCapability
 ISmimeCapabilities::AddFromCsp method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The AddFromCsp method adds objects to the collection by identifying the encryption algorithms supported by
a specific cryptographic provider.

Syntax
HRESULT AddFromCsp(
[in] ICspInformation *pValue
);

Parameters
[in] pValue

Pointer to an ICspInformation interface that represents the provider.

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
ISmimeCapabilities
ISmimeCapability
 ISmimeCapabilities::Clear method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Clear method removes all objects from the collection.

Syntax
HRESULT Clear();

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
ISmimeCapabilities
ISmimeCapability
 ISmimeCapabilities::get__NewEnum method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The _NewEnum property retrieves the enumerator for the collection.

This property is read-only.

Syntax
HRESULT get__NewEnum(
LPUNKNOWN *pVal
);

Parameters
pVal

Return value
None

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
ISmimeCapabilities
ISmimeCapability
 ISmimeCapabilities::get_Count method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Count property retrieves the number of objects in the collection.

This property is read-only.

Syntax
HRESULT get_Count(
long *pVal
);

Parameters
pVal

Return value
None

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
ISmimeCapabilities
ISmimeCapability
 ISmimeCapabilities::Remove method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Remove method removes an object from the collection by index value.

Syntax
HRESULT Remove(
[in] LONG Index
);

Parameters
[in] Index

A LONG variable that contains the index of the object to remove.

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
ISmimeCapabilities
ISmimeCapability
 ISmimeCapability interface (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

A collection of ISmimeCapability objects represents an SMIMECapabilities extension that identifies the

decryption capabilities of an email recipient. The extension includes a collection of ISmimeCapability objects,
each of which identifies a symmetric encryption algorithm supported by the client, and an optional bit length
that indicates the relative strength of the algorithm. The following syntax shows the Abstract Syntax Notation
One (ASN.1) structure of the extension. The extension is represented by an IX509ExtensionSmimeCapabilities
interface.

----------------------------------------------------------------------
-- SMIMECapabilities
-- XCN_OID_RSA_SMIMECapabilities (1.2.840.113549.1.9.15)
----------------------------------------------------------------------

SMIMECapabilities ::= SEQUENCE OF SMIMECapability

SMIMECapability ::= SEQUENCE

{
capabilityID EncodedObjectID,
smimeParameters ANY OPTIONAL
}

The extension is used to report the decryption capabilities of an email recipient to an email sender. This enables
the sender to choose the most secure algorithm supported by both parties.
The optional bit length is used to identify the length of the encryption key used by algorithm. The key length is
implicitly defined by the object identifier for the AES, DES, and 3DES algorithms, but it is variable for the RC2
and RC4 algorithms. If you specify a key length, it must be consistent with that supported by the cryptographic
providers used by the client. For more information, see ICspInformation.

Inheritance
The ISmimeCapability interface inherits from the IUnknown interface. ISmimeCapability also has these
types of members:

Methods
The ISmimeCapability interface has these methods.

ISmimeCapability::get_BitCount

Retrieves the length, in bits, of the encryption key.

ISmimeCapability::get_ObjectId

Retrieves the object identifier (OID) of the symmetric encryption algorithm.

 ISmimeCapability::Initialize

Initializes the object from a symmetric encryption algorithm object identifier (OID) and an optional key length.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

See also
Certificate Enrollment API
ICspAlgorithm
ICspInformation
ISmimeCapabilities
IX509ExtensionSmimeCapabilities
IX509Extensions
 ISmimeCapability::get_BitCount method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The BitCount property retrieves the length, in bits, of the encryption key.
This property is read-only.

Syntax
HRESULT get_BitCount(
LONG *pValue
);

Parameters
pValue

Return value
None

Remarks
Call the Initialize method to specify the BitCount property. The following symmetric encryption algorithms and
key lengths are supported by the Certificate Enrollment API.

O ID K EY L EN GT H

XCN_OID_OIWSEC_desCBC1.3.14.3.2.7 56

XCN_OID_RSA_DES_EDE3_CBC1.2.840.113549.3.7 168

XCN_OID_RSA_RC2CBC1.2.840.113549.3.2 40 to 128

XCN_OID_RSA_RC41.2.840.113549.3.4 40 to 128

XCN_OID_RSA_SMIMEalgCMS3DESwrap1.2.840.113549.1.9. 168
16.3.6

XCN_OID_RSA_SMIMEalgCMSRC2wrap1.2.840.113549.1.9.1 128
6.3.7

XCN_OID_NIST_AES128_CBC2.16.840.1.101.3.4.1.2 128

XCN_OID_NIST_AES192_CBC2.16.840.1.101.3.4.1.22 192

XCN_OID_NIST_AES256_CBC2.16.840.1.101.3.4.1.42 256
 XCN_OID_NIST_AES128_WRAP2.16.840.1.101.3.4.1.5 128

XCN_OID_NIST_AES192_WRAP2.16.840.1.101.3.4.1.25 192

XCN_OID_NIST_AES256_WRAP2.16.840.1.101.3.4.1.45 256

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
ISmimeCapabilities
ISmimeCapability
IX509ExtensionSmimeCapabilities
 ISmimeCapability::get_ObjectId method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The ObjectId property retrieves the object identifier (OID) of the symmetric encryption algorithm.
This property is read-only.

Syntax
HRESULT get_ObjectId(
IObjectId **ppValue
);

Parameters
ppValue

Return value
None

Remarks
Call the Initialize method to specify the ObjectId property. The following encryption OIDs are currently
supported:
XCN_OID_NIST_AES128_CBC (2.16.840.1.101.3.4.1.2)
XCN_OID_NIST_AES192_CBC (2.16.840.1.101.3.4.1.22)
XCN_OID_NIST_AES256_CBC (2.16.840.1.101.3.4.1.42)
XCN_OID_NIST_AES128_WRAP (2.16.840.1.101.3.4.1.5)
XCN_OID_NIST_AES192_WRAP (2.16.840.1.101.3.4.1.25)
XCN_OID_NIST_AES256_WRAP (2.16.840.1.101.3.4.1.45)
XCN_OID_OIWSEC_desCBC (1.3.14.3.2.7)
XCN_OID_RSA_DES_EDE3_CBC (1.2.840.113549.3.7)
XCN_OID_RSA_RC2CBC (1.2.840.113549.3.2)
XCN_OID_RSA_RC4 (1.2.840.113549.3.4)
XCN_OID_RSA_SMIMEalgCMS3DESwrap (1.2.840.113549.1.9.16.3.6)
XCN_OID_RSA_SMIMEalgCMSRC2wrap (1.2.840.113549.1.9.16.3.7)

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

 Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
ISmimeCapabilities
ISmimeCapability
IX509ExtensionSmimeCapabilities
 ISmimeCapability::Initialize method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Initialize method initializes the object from a symmetric encryption algorithm object identifier (OID) and
an optional key length.

Syntax
HRESULT Initialize(
[in] IObjectId *pObjectId,
[in] LONG BitCount
);

Parameters
[in] pObjectId

Pointer to an IObjectId interface that represents the OID.

[in] BitCount

A LONG variable that contains the bit length of the symmetric key.

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. Possible values include, but are not
limited to, those in the following table. For a list of common error codes, see Common HRESULT Values.

RET URN C O DE/ VA L UE DESC RIP T IO N

The IObjectId pointer is NULL .

CERTSRV_E_PROPERTY_EMPTY

Remarks
The following symmetric encryption algorithms are supported by the Certificate Enrollment API. Only the RC2
and RC4 algorithms have variable key lengths that can be specified.

O ID K EY L EN GT H DESC RIP T IO N

XCN_OID_OIWSEC_desCBC1.3.14.3.2. 56 The key size is of the DES CBC

7 algorithm is 56 bits. You do not need
to specify this value.

XCN_OID_RSA_DES_EDE3_CBC1.2.840. 168 The key size is of the 3DES CBC

113549.3.7 algorithm is 168 bits. You do not need
to specify this value.
 XCN_OID_RSA_RC2CBC1.2.840.11354 40 to 128 RC4 is a variable key algorithm.
9.3.2 common values are 40, 64, and 128
bits.

XCN_OID_RSA_RC41.2.840.113549.3.4 40 to 128 RC4 is a variable key algorithm.

common values are 40, 64, and 128
bits.

XCN_OID_RSA_SMIMEalgCMS3DESwr 168 The key size of the MMS Data

ap1.2.840.113549.1.9.16.3.6 Encryption Standard (DES) key wrap
algorithm is 168 bits. You do not need
to specify this value.

XCN_OID_RSA_SMIMEalgCMSRC2wra 128 The key size of the MMS RC2 key wrap
p1.2.840.113549.1.9.16.3.7 algorithm is 128 bits. You do not need
to specify this value.

XCN_OID_NIST_AES128_CBC2.16.840. 128 The key size is implied by the OID. You

1.101.3.4.1.2 do not need to specify this value.

XCN_OID_NIST_AES192_CBC2.16.840. 192 The key size is implied by the OID. You

1.101.3.4.1.22 do not need to specify this value.

XCN_OID_NIST_AES256_CBC2.16.840. 256 The key size is implied by the OID. You

1.101.3.4.1.42 do not need to specify this value.

XCN_OID_NIST_AES128_WRAP2.16.84 128 The key size is implied by the OID. You

0.1.101.3.4.1.5 do not need to specify this value.

XCN_OID_NIST_AES192_WRAP2.16.84 192 The key size is implied by the OID. You

0.1.101.3.4.1.25 do not need to specify this value.

XCN_OID_NIST_AES256_WRAP2.16.84 256 The key size is implied by the OID. You

0.1.101.3.4.1.45 do not need to specify this value.

The key length that you specify for RC2 and RC4 algorithms must be consistent with that supported by the
cryptographic provider or providers used by the client. For more information, see ICspInformation. You can
retrieve the bit length by calling the BitCount property, and you can retrieve the algorithm OID by calling the
ObjectId property.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll
See also
ISmimeCapabilities
ISmimeCapability
IX509ExtensionSmimeCapabilities
 IX500DistinguishedName interface (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The IX500DistinguishedName interface represents an X.500 distinguished name (DN). The X.500 series of
networking standards covers electronic directory services. A distinguished name uniquely identifies
(distinguishes) each entry in the directory from all other entries. Each DN consists of one or more relative
distinguished names (RDNs).
The subject field of a PKCS #10 certificate request contains the DN of the entity requesting the certificate

CertificationRequestInfo ::= SEQUENCE

{
version CertificationRequestInfoVersion,
subject Name,
subjectPublicKeyInfo SubjectPublicKeyInfo,
attributes [0] IMPLICIT Attributes
}

The DN consists of a sequence of RDNs. Each RDN consists of a set of attributes, and each attribute consists of
an object identifier (OID) and a value. The data type of the value is identified by the Director yString structure.

Name ::= SEQUENCE OF RelativeDistinguishedName

RelativeDistinguishedName ::= SET OF AttributeTypeValue

AttributeTypeValue ::= SEQUENCE

{
type EncodedObjectID,
value ANY
}

DirectoryString ::= CHOICE

{
teletexString TeletexString (SIZE (1..MAX)),
printableString PrintableString (SIZE (1..MAX)),
universalString UniversalString (SIZE (1..MAX)),
utf8String UTF8String (SIZE (1..MAX)),
bmpString BMPString (SIZE (1..MAX))
}

The following RDN keys and associated OIDs are currently supported.

K EY O ID DESC RIP T IO N RDN T Y P E

C XCN_OID_COUNTRY_NAME Contains a two-letter ISO PrintableString

3166 country or region
code.

CN XCN_OID_COMMON_NAM Contains a common name. PrintableString

E
 EEMAIL XCN_OID_RSA_emailAddr Contains an email address. IA5String

DC XCN_OID_DOMAIN_COMP Contains one component of IA5String

ONENT a Domain Name System
(DNS) name.

GGivenName XCN_OID_GIVEN_NAME Contains the part of a PrintableString

person's name that is not a
surname.

I XCN_OID_INITIALS Contains a person's initials. PrintableString

L XCN_OID_LOCALITY_NAME Contains the locality name PrintableString

that identifies a city,
country, or other
geographic region.

O XCN_OID_ORGANIZATION_ Contains the name of an PrintableString

NAME organization.

OU XCN_OID_ORGANIZATION Contains the name of a unit PrintableString

AL_UNIT_NAME subdivision within an
organization.

SST XCN_OID_STATE_OR_PROVI Contains the full name of a PrintableString

NCE_NAME state or province.

STREET XCN_OID_STREET_ADDRESS Contains the physical PrintableString

address.

SN XCN_OID_SUR_NAME Contains the family name of PrintableString

a person.

TTITLE XCN_OID_TITLE Contains the title of a PrintableString

person in the organization.

Each service that is based on X.500 defines its own distinguished name string representation. For example,
LDAP uses a comma-delimited list arranged from right to left. Active Directory uses a forward slash (/) and
arranges the list from left to right. Other services use semicolons as separators. The following example shows an
Active Directory entry for an employee named John Peoples who works in the pharmaceutical division of a
company named Contoso, Ltd.

/c=gb/o=Contoso Ltd./ou=Contoso Pharmaceuticals/cn=John Peoples

Inheritance
The IX500DistinguishedName interface inherits from the IDispatch interface. IX500DistinguishedName
also has these types of members:

Methods
The IX500DistinguishedName interface has these methods.

IX500DistinguishedName::Decode

Initializes the object from a Unicode-encoded distinguished name.

IX500DistinguishedName::Encode

Initializes the object from a string that contains a distinguished name.

IX500DistinguishedName::get_EncodedName

Retrieves a Unicode-encoded distinguished name.

IX500DistinguishedName::get_Name

Retrieves a distinguished name.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

See also
CertEnroll Interfaces
IDispatch
Subject Names
 IX500DistinguishedName::Decode method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Decode method initializes the object from a Unicode-encoded distinguished name.

Syntax
HRESULT Decode(
[in] BSTR strEncodedName,
[in] EncodingType Encoding,
[in] X500NameFlags NameFlags
);

Parameters
[in] strEncodedName

A BSTR variable that contains the encoded name.

[in] Encoding

An EncodingType enumeration value that specifies the type of Unicode encoding applied to the input string. The
default value is XCN_CRYPT_STRING_BASE64 .
[in] NameFlags

An X500NameFlags enumeration value that specifies the format of the decoded string.

Note The following flags are set automatically:

The default value specified in Certenroll.h is XCN_CERT_NAME_STR_NONE .
If you do not specify XCN_CERT_NAME_STR_FORWARD_FLAG, then XCN_CERT_NAME_STR_REVERSE_FLAG is
automatically applied.
If you do not specify XCN_CERT_NAME_STR_DISABLE_UTF8_DIR_STR_FLAG, then
XCN_CERT_NAME_STR_FORCE_UTF8_DIR_STR_FLAG is automatically applied.
XCN_CERT_NAME_STR_ENABLE_PUNYCODE_FLAG is automatically set regardless of any other flag you specify.

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. Possible values include, but are not
limited to, those in the following table. For a list of common error codes, see Common HRESULT Values.

RET URN C O DE/ VA L UE DESC RIP T IO N

 Memory could not be allocated for the decoded value.
E_OUTOFMEMORY

The strEncodedName parameter cannot be NULL .

E_POINTER

The name could not be decoded.

HRESULT_FROM_WIN32(ERROR_FILE_NOT_FOUND)

Remarks
This method internally calls the CryptoAPI CertNameToStr function. Call the Name property to retrieve the name
as a null-terminated character string. Call the EncodedName property to retrieve a string containing an encoded
name.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX500DistinguishedName
 IX500DistinguishedName::Encode method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Encode method initializes the object from a string that contains a distinguished name. This method is web
enabled.

Syntax
HRESULT Encode(
[in] BSTR strName,
[in] X500NameFlags NameFlags
);

Parameters
[in] strName

A BSTR variable that contains the string to encode.

[in] NameFlags

An X500NameFlags enumeration value that specifies the format of the encoded value.

Note The following flags are set automatically:

The default value specified in Certenroll.h is XCN_CERT_NAME_STR_NONE .
If you do not specify XCN_CERT_NAME_STR_FORWARD_FLAG, then XCN_CERT_NAME_STR_REVERSE_FLAG is
automatically applied.
If you do not specify XCN_CERT_NAME_STR_DISABLE_UTF8_DIR_STR_FLAG, then
XCN_CERT_NAME_STR_FORCE_UTF8_DIR_STR_FLAG is automatically applied.
XCN_CERT_NAME_STR_ENABLE_PUNYCODE_FLAG is automatically set regardless of any other flag you specify.

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. Possible values include, but are not
limited to, those in the following table. For a list of common error codes, see Common HRESULT Values.

RET URN C O DE/ VA L UE DESC RIP T IO N

Memory could not be allocated for the encoded value.

E_OUTOFMEMORY

The strName parameter cannot be NULL .

E_POINTER
 The length, in characters of the strName parameter cannot
HRESULT_FROM_WIN32(ERROR_FILENAME_EXCED_R exceed 64 * 1024.
ANGE)

Remarks
This method internally calls the CryptoAPI CertStrToName function. Call the Name property to retrieve the name
as a null-terminated character string. Call the EncodedName property to retrieve a string containing an encoded
name.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX500DistinguishedName
 IX500DistinguishedName::get_EncodedName
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The EncodedName property retrieves a Unicode-encoded distinguished name.

This property is read-only.

Syntax
HRESULT get_EncodedName(
EncodingType Encoding,
BSTR *pValue
);

Parameters
Encoding

pValue

Return value
None

Remarks
Call the Encode method to encode a distinguished name. Call the Decode method to decode a distinguished
name.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX500DistinguishedName
 IX500DistinguishedName::get_Name method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Name property retrieves a distinguished name.

This property is read-only.

Syntax
HRESULT get_Name(
BSTR *pValue
);

Parameters
pValue

Return value
None

Remarks
Call the Encode method to encode a distinguished name. Call the Decode method to decode a distinguished
name. Call the EncodedName property to retrieve the name as an encoded string.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX500DistinguishedName
 IX509Attribute interface (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The IX509Attribute interface can be used to represent an attribute in a PKCS #7, PKCS #10, or CMC certificate
request. For more information, see the following topics:
Attributes
PKCS #7 Attributes
PKCS #10 Attributes
CMC Attributes
Attributes are added to a certificate request to provide a certification authority with additional information that
it can use when creating and issuing a certificate. Each attribute is a Distinguished Encoding Rules (DER)
encoded Abstract Syntax Notation One (ASN.1) structure that contains an object identifier (OID) and zero or
more values as shown by the following syntax.

Attributes ::= SET OF Attribute

Attribute ::= SEQUENCE

{
type EncodedObjectID,
values AttributeSetValue
}

The IX509Attribute interface can be used to initialize and retrieve an attribute value. It also serves as the base
for the following common attribute interfaces.

IN T ERFA C E/ O ID DESC RIP T IO N

IX509AttributeClientId (XCN_OID_REQUEST_CLIENT_INFO) Represents an attribute that can be used to identify the

client that generated a certificate request.

IX509AttributeExtensions (XCN_OID_RSA_certExtensions) Represents an attribute that contains certificate extensions in

a certificate request.

IX509AttributeArchiveKey (XCN_OID_ARCHIVED_KEY_ATTR) Represents an attribute that contains an encrypted private

key to be archived by a certification authority.

IX509AttributeArchiveKeyHash Represents an attribute that contains a SHA-1 hash of the

(XCN_OID_ENCRYPTED_KEY_HASH) encrypted private key to be archived by a certification
authority.

IX509AttributeCspProvider Represents an attribute that identifies the cryptographic

(XCN_OID_ENROLLMENT_CSP_PROVIDER) service provider (CSP) used by the entity requesting the
certificate.

IX509AttributeOSVersion (XCN_OID_OS_VERSION) Represents an attribute that contains version information

about the client operating system on which the certificate
request was generated.
 IX509AttributeRenewalCertificate Represents an attribute that contains the certificate being
(XCN_OID_RENEWAL_CERTIFICATE) renewed.

Inheritance
The IX509Attribute interface inherits from the IDispatch interface. IX509Attribute also has these types of
members:

Methods
The IX509Attribute interface has these methods.

IX509Attribute::get_ObjectId

Retrieves the object identifier (OID) for the attribute.

IX509Attribute::get_RawData

Retrieves the attribute value.

IX509Attribute::Initialize

Initializes the object from an object identifier (OID) and a value.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

See also
CertEnroll Interfaces
ICryptAttribute
IDispatch
IX509Attribute
IX509Attributes
 IX509Attribute::get_ObjectId method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The ObjectId property retrieves the object identifier (OID) for the attribute.
This property is read-only.

Syntax
HRESULT get_ObjectId(
IObjectId **ppValue
);

Parameters
ppValue

Return value
None

Remarks
Call the Initialize method to specify the property value.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
ICryptAttribute
IX509Attribute
IX509Attributes
 IX509Attribute::get_RawData method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The RawData property retrieves the attribute value.

This property is read-only.

Syntax
HRESULT get_RawData(
EncodingType Encoding,
BSTR *pValue
);

Parameters
Encoding

pValue

Return value
None

Remarks
Call the Initialize method to specify the property value.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
ICryptAttribute
IX509Attribute
IX509Attributes
 IX509Attribute::Initialize method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Initialize method initializes the object from an object identifier (OID) and a value.

Syntax
HRESULT Initialize(
[in] IObjectId *pObjectId,
[in] EncodingType Encoding,
[in] BSTR strEncodedData
);

Parameters
[in] pObjectId

Pointer to an IObjectId interface that contains the attribute OID.

[in] Encoding

An EncodingType enumeration value that specifies the type of Unicode encoding applied to the attribute value
contained in the strEncodedData parameter.
[in] strEncodedData

A BSTR variable that contains the attribute value.

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. Possible values include, but are not
limited to, those in the following table. For a list of common error codes, see Common HRESULT Values.

RET URN C O DE/ VA L UE DESC RIP T IO N

The pointer to the IObjectId interface is NULL .

CERTSRV_E_PROPERTY_EMPTY

Remarks
You must initialize the IObjectId object by calling the InitializeFromName or InitializeFromValue methods before
using it in this method.
Call the ObjectId property to retrieve the OID. Call the RawData property to retrieve the attribute value.

Requirements
 Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
ICryptAttribute
IX509Attribute
IX509Attributes
 IX509AttributeArchiveKey interface (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The IX509AttributeArchiveKey interface represents an attribute that contains an encrypted private key to be
archived by a certification authority. The key is attached as an unauthenticated attribute to the primary signature
of a CMC request. The hash of the encrypted key is encoded as an authenticated attribute in the CMC request.
For more information, see the IX509AttributeArchiveKeyHash interface.

Inheritance
The IX509AttributeArchiveKey interface inherits from IX509Attribute. IX509AttributeArchiveKey also has
these types of members:

Methods
The IX509AttributeArchiveKey interface has these methods.

IX509AttributeArchiveKey::get_EncryptedKeyBlob

Retrieves a byte array that contains the encrypted key.

IX509AttributeArchiveKey::get_EncryptionAlgorithm

Retrieves the object identifier (OID) of the symmetric encryption algorithm used to encrypt the private key.

IX509AttributeArchiveKey::get_EncryptionStrength

Retrieves an integer that contains the encryption strength of the symmetric algorithm used to encrypt the key.

IX509AttributeArchiveKey::InitializeDecode

Initializes the object from a Distinguished Encoding Rules (DER) encoded byte array that contains the encrypted private key.

IX509AttributeArchiveKey::InitializeEncode

Initializes the attribute from an IX509PrivateKey object, the certification authority encryption certificate, and the symmetric
encryption algorithm object identifier (OID).

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

 Header certenroll.h

See also
CertEnroll Interfaces
IX509Attribute
IX509Attributes
 IX509AttributeArchiveKey::get_EncryptedKeyBlob
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Encr yptedKeyBlob property retrieves a byte array that contains the encrypted key. The byte array is
represented by a Unicode-encoded string.
This property is read-only.

Syntax
HRESULT get_EncryptedKeyBlob(
EncodingType Encoding,
BSTR *pValue
);

Parameters
Encoding

pValue

Return value
None

Remarks
Call the InitializeEncode method or the InitializeDecode method to initialize the Encr yptedKeyBlob property.
You can call the following properties to retrieve the raw data:
EncryptionAlgorithm
EncryptionStrength

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll
See also
IX509AttributeArchiveKey
 IX509AttributeArchiveKey::get_EncryptionAlgorithm
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Encr yptionAlgorithm property retrieves the object identifier (OID) of the symmetric encryption algorithm
used to encrypt the private key.
This property is read-only.

Syntax
HRESULT get_EncryptionAlgorithm(
IObjectId **ppValue
);

Parameters
ppValue

Return value
None

Remarks
Call the InitializeEncode method or the InitializeDecode method to initialize the Encr yptionAlgorithm
property. You can call the following properties to retrieve the raw data:
EncryptedKeyBlob
EncryptionStrength

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509AttributeArchiveKey
 IX509AttributeArchiveKey::get_EncryptionStrength
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Encr yptionStrength property retrieves an integer that contains the encryption strength of the symmetric
algorithm used to encrypt the key.
This property is read-only.

Syntax
HRESULT get_EncryptionStrength(
LONG *pValue
);

Parameters
pValue

Return value
None

Remarks
You can specify this property by calling the InitializeEncode method or the InitializeDecode method. However,
the property is currently ignored and zero is returned because the Certificate Enrollment SDK does not support
any algorithms for which the object identifier (OID) does not already imply the encryption strength (key length).
For example, AES has multiple strengths, but each strength is already indicated by the OID.
You can call the following properties to retrieve the raw data:
EncryptionAlgorithm
EncryptedKeyBlob

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll
See also
IX509AttributeArchiveKey
 IX509AttributeArchiveKey::InitializeDecode method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The InitializeDecode method initializes the object from a Distinguished Encoding Rules (DER) encoded byte
array that contains the encrypted private key. The byte array is represented by a Unicode-encoded string.

Syntax
HRESULT InitializeDecode(
[in] EncodingType Encoding,
[in] BSTR strEncodedData
);

Parameters
[in] Encoding

An EncodingType enumeration value that specifies the type of Unicode encoding applied to the input string.
[in] strEncodedData

A BSTR variable that contains the DER-encoded attribute.

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.

Remarks
The object identifier (OID) for this attribute is XCN_OID_ARCHIVED_KEY_ATTR (1.3.6.1.4.1.311.21.13). For
more information, see CERTENROLL_OBJECTID.
You can use this method if you have a DER-encoded Abstract Syntax Notation One (ASN.1) object that contains
the attribute value. You must supply the DER-encoded object in a Unicode encoded string. For more information,
see the IBinaryConverter interface.
You must call either InitializeEncode or InitializeDecode before you can use an IX509AttributeArchiveKey
object. The two methods complement each other. The InitializeEncode method enables you to construct an
encoded ASN.1 structure from raw data, and the InitializeDecode method enables you to initialize raw data
from an encoded ASN.1 structure. You can call the following properties to retrieve the raw data:
EncryptionAlgorithm
EncryptedKeyBlob
EncryptionStrength

Requirements
 Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509AttributeArchiveKey
 IX509AttributeArchiveKey::InitializeEncode method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The InitializeEncode method initializes the attribute from an IX509PrivateKey object, the certification authority
encryption certificate, and the symmetric encryption algorithm object identifier (OID).

Syntax
HRESULT InitializeEncode(
[in] IX509PrivateKey *pKey,
[in] EncodingType Encoding,
[in] BSTR strCAXCert,
[in, optional] IObjectId *pAlgorithm,
[in] LONG EncryptionStrength
);

Parameters
[in] pKey

Pointer to an IX509PrivateKey interface that represents the key.

[in] Encoding

An EncodingType enumeration value that specifies the type of Unicode encoding applied to the input string that
contains the encrypted key.
[in] strCAXCert

A BSTR variable that contains the certification authority encryption certificate that contains the public key used
to encrypt the private key.
Beginning with Windows 7 and Windows Server 2008 R2, you can specify a certificate thumb print or serial
number rather than an encoded certificate. Doing so causes the function to search the appropriate local stores
for the matching certificate. Keep in mind the following points:
The BSTR must be an even number of hexadecimal digits.
Whitespace between hexadecimal pairs is ignored.
The Encoding parameter must be set to XCN_CRYPT_STRING_HEXRAW .
Only the personal and request stores are searched for the private key.
[in, optional] pAlgorithm

Pointer to an IObjectId interface that represents the OID of the symmetric encryption algorithm used to encrypt
the private key. This parameter is optional. If you do not supply an OID, XCN_OID_RSA_DES_EDE3_CBC (Triple
DES) is used.
[in] EncryptionStrength

A LONG variable that contains the encryption strength of the algorithm identified by the pAlgorithm parameter.
This parameter is not currently used because the Certificate Enrollment SDK does not support any algorithms
for which the OID does not already imply the strength (key length). For example, AES has multiple strengths but
strength each is already indicated by the OID.

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.

Remarks
The object identifier for this attribute is XCN_OID_ARCHIVED_KEY_ATTR (1.3.6.1.4.1.311.21.13). For more
information, see CERTENROLL_OBJECTID.
You must call either InitializeEncode or InitializeDecode before you can use an IX509AttributeArchiveKey
object. The two methods complement each other. The InitializeEncode method enables you to construct an
encoded Abstract Syntax Notation One (ASN.1) structure from raw data, and the InitializeDecode method
enables you to initialize raw data from an encoded ASN.1 structure. You can call the following properties to
retrieve the raw data:
EncryptionAlgorithm
EncryptedKeyBlob
EncryptionStrength

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509AttributeArchiveKey
 IX509AttributeArchiveKeyHash interface
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The IX509AttributeArchiveKeyHash interface represents an attribute that contains a SHA-1 hash of the
encrypted private key to be archived by a certification authority. The encrypted key is attached as an
unauthenticated attribute to the primary signature of a CMC request. The hash of the encrypted key is encoded
as an authenticated attribute in a CMC request.
When a certification authority receives the request, it hashes the unsigned encrypted key and compares it to the
signed hash sent by the requester. If the hashes match, the key was not tampered with.

Inheritance
The IX509AttributeArchiveKeyHash interface inherits from IX509Attribute.
IX509AttributeArchiveKeyHash also has these types of members:

Methods
The IX509AttributeArchiveKeyHash interface has these methods.

IX509AttributeArchiveKeyHash::get_EncryptedKeyHashBlob

Retrieves a string that contains a hash of the encrypted private key.

IX509AttributeArchiveKeyHash::InitializeDecode

Initializes the object from a Distinguished Encoding Rules (DER) encoded byte array that contains a SHA-1 hash of the
encrypted private key.

IX509AttributeArchiveKeyHash::InitializeEncodeFromEncryptedKeyBlob

Initializes the attribute from an encrypted private key.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

See also
CertEnroll Interfaces
IX509Attribute
IX509Attributes
 IX509AttributeArchiveKeyHash::get_EncryptedKeyHashBlob
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Encr yptedKeyHashBlob property retrieves a string that contains a hash of the encrypted private key.
This property is read-only.

Syntax
HRESULT get_EncryptedKeyHashBlob(
EncodingType Encoding,
BSTR *pValue
);

Parameters
Encoding

pValue

Return value
None

Remarks
Call the InitializeEncodeFromEncryptedKeyBlob method or the InitializeDecode method to initialize the
Encr yptedKeyHashBlob property.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509AttributeArchiveKeyHash
 IX509AttributeArchiveKeyHash::InitializeDecode
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The InitializeDecode method initializes the object from a Distinguished Encoding Rules (DER) encoded byte
array that contains a SHA-1 hash of the encrypted private key. The byte array is represented by a Unicode-
encoded string.

Syntax
HRESULT InitializeDecode(
[in] EncodingType Encoding,
[in] BSTR strEncodedData
);

Parameters
[in] Encoding

An EncodingType enumeration value that specifies the type of Unicode encoding applied to the input string that
contains hash value.
[in] strEncodedData

A BSTR variable that contains the DER-encoded attribute.

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.

Remarks
The object identifier (OID) for this attribute is XCN_OID_ENCRYPTED_KEY_HASH (1.3.6.1.4.1.311.21.21). For
more information, see CERTENROLL_OBJECTID.
You can use this method if you have a DER-encoded Abstract Syntax Notation One (ASN.1) object that contains
the attribute value. You must supply the DER-encoded object in a Unicode encoded string. For more information,
see the IBinaryConverter interface.
You must call either InitializeEncodeFromEncryptedKeyBlob or InitializeDecode before you can use an
IX509AttributeArchiveKeyHash object. The two methods complement each other. The
InitializeEncodeFromEncr yptedKeyBlob method enables you to construct an encoded ASN.1 structure from
raw data, and the InitializeDecode method enables you to initialize raw data from an encoded ASN.1 structure.
You can call the EncryptedKeyHashBlob property to retrieve the raw data.

Requirements
 Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509AttributeArchiveKeyHash
 IX509AttributeArchiveKeyHash::InitializeEncodeFromEncryptedKeyBlob
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The InitializeEncodeFromEncr yptedKeyBlob method initializes the attribute from an encrypted private key.
The method computes a SHA-1 hash of the private key.

Syntax
HRESULT InitializeEncodeFromEncryptedKeyBlob(
[in] EncodingType Encoding,
[in] BSTR strEncryptedKeyBlob
);

Parameters
[in] Encoding

An EncodingType enumeration value that specifies the type of Unicode encoding applied to the input string that
contains the key.
[in] strEncryptedKeyBlob

A BSTR variable that contains the encrypted key.

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.

Remarks
The object identifier (OID) for this attribute is XCN_OID_ENCRYPTED_KEY_HASH (1.3.6.1.4.1.311.21.21). For
more information, see CERTENROLL_OBJECTID.
You must call either InitializeEncodeFromEncr yptedKeyBlob or InitializeDecode before you can use an
IX509AttributeArchiveKeyHash object. The two methods complement each other. The
InitializeEncodeFromEncr yptedKeyBlob method enables you to construct an encoded Abstract Syntax
Notation One (ASN.1) structure from raw data, and the InitializeDecode method enables you to initialize raw
data from an encoded ASN.1 structure. You can call the EncryptedKeyHashBlob property to retrieve the raw
data.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509AttributeArchiveKeyHash
 IX509AttributeClientId interface (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The IX509AttributeClientId interface represents an attribute that can be used to identify the client that
generated a certificate request. This can be used for post-mortem request analysis.

Inheritance
The IX509AttributeClientId interface inherits from IX509Attribute. IX509AttributeClientId also has these
types of members:

Methods
The IX509AttributeClientId interface has these methods.

IX509AttributeClientId::get_ClientId

Retrieves the type of client application that generated the request.

IX509AttributeClientId::get_MachineDnsName

Retrieves the Domain Name System (DNS) name of the computer that generated the request.

IX509AttributeClientId::get_ProcessName

Retrieves the name of the application that generated the request.

IX509AttributeClientId::get_UserSamName

Retrieves the Security Accounts Manager (SAM) name of the user.

IX509AttributeClientId::InitializeDecode

Initializes the object from a Distinguished Encoding Rules (DER) encoded byte array that contains the attribute value.

IX509AttributeClientId::InitializeEncode

Initializes the attribute from information about the user, client computer, and application that submitted the certificate
request.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

 Header certenroll.h

See also
CertEnroll Interfaces
IX509Attribute
 IX509AttributeClientId::get_ClientId method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The ClientId property retrieves the type of client application that generated the request.
This property is read-only.

Syntax
HRESULT get_ClientId(
RequestClientInfoClientId *pValue
);

Parameters
pValue

Return value
None

Remarks
Call the InitializeEncode method or the InitializeDecode method to initialize the ClientId value. You can call the
following properties to retrieve the raw data:
MachineDnsName
ProcessName
UserSamName

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509AttributeClientId
 IX509AttributeClientId::get_MachineDnsName
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The MachineDnsName property retrieves the Domain Name System (DNS) name of the computer that
generated the request.
This property is read-only.

Syntax
HRESULT get_MachineDnsName(
BSTR *pValue
);

Parameters
pValue

Return value
None

Remarks
Call the InitializeEncode method or the InitializeDecode method to initialize the MachineDnsName value. You
can call the following properties to retrieve the raw data:
ClientId
ProcessName
UserSamName

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509AttributeClientId
 IX509AttributeClientId::get_ProcessName method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The ProcessName property retrieves the name of the application that generated the request.
This property is read-only.

Syntax
HRESULT get_ProcessName(
BSTR *pValue
);

Parameters
pValue

Return value
None

Remarks
Call the InitializeEncode method or the InitializeDecode method to initialize the ProcessName value. You can
call the following properties to retrieve the raw data:
ClientId
MachineDnsName
UserSamName

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509AttributeClientId
IX509Enrollment
 IX509AttributeClientId::get_UserSamName method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The UserSamName property retrieves the Security Accounts Manager (SAM) name of the user.
This property is read-only.

Syntax
HRESULT get_UserSamName(
BSTR *pValue
);

Parameters
pValue

Return value
None

Remarks
Call the InitializeEncode method or the InitializeDecode method to initialize the UserSamName value. You can
call the following properties to retrieve the raw data:
ClientId
MachineDnsName
ProcessName

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509AttributeClientId
 IX509AttributeClientId::InitializeDecode method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The InitializeDecode method initializes the object from a Distinguished Encoding Rules (DER) encoded byte
array that contains the attribute value. The byte array is represented by a Unicode-encoded string.

Syntax
HRESULT InitializeDecode(
[in] EncodingType Encoding,
[in] BSTR strEncodedData
);

Parameters
[in] Encoding

An EncodingType enumeration value that specifies the type of Unicode encoding applied to the input string.
[in] strEncodedData

A BSTR variable that contains the DER-encoded attribute.

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.

Remarks
The object identifier (OID) for this attribute is XCN_OID_REQUEST_CLIENT_INFO (1.3.6.1.4.1.311.21.20). For
more information, see CERTENROLL_OBJECTID.
You can use this method if you have a DER-encoded Abstract Syntax Notation One (ASN.1) object that contains
the attribute value. You must supply the DER-encoded object in a Unicode encoded string. For more information,
see the IBinaryConverter interface.
You must call either InitializeEncode or InitializeDecode before you can use an IX509AttributeClientId object.
The two methods complement each other. The InitializeEncode method enables you to construct an encoded
ASN.1 structure from raw data, and the InitializeDecode method enables you to initialize raw data from an
encoded ASN.1 structure. You can call the following properties to retrieve the raw data:
ClientId
MachineDnsName
ProcessName
UserSamName
Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509AttributeClientId
 IX509AttributeClientId::InitializeEncode method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The InitializeEncode method initializes the attribute from information about the user, client computer, and
application that submitted the certificate request.

Syntax
HRESULT InitializeEncode(
[in] RequestClientInfoClientId ClientId,
[in, optional] BSTR strMachineDnsName,
[in, optional] BSTR strUserSamName,
[in, optional] BSTR strProcessName
);

Parameters
[in] ClientId

A RequestClientInfoClientId enumeration value that identifies the type of application that created the request.
Examples include autoenrollment services, command-line request tools, and custom request applications.
[in, optional] strMachineDnsName

A BSTR variable that contains the Domain Name System (DNS) name of the computer on which the request
was created, for example ComputerName.contoso.com. If you do not supply a name, the method calls the
GetComputerNameEx function. If a name cannot be found, the method fails.
[in, optional] strUserSamName

A BSTR variable that contains the Security Accounts Manager (SAM) name for the user in the form
DomainName\UserName. If you do not supply a name, the method calls the GetUserNameEx function. If a name
cannot be found, the method fails.
[in, optional] strProcessName

A BSTR variable that contains the name of the application that created the certificate request. If you do not
supply a name, the method calls the GetCommandLine() function and parses the command line. If a name
cannot be found, the method fails.

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.

Remarks
The object identifier (OID) for this attribute is XCN_OID_REQUEST_CLIENT_INFO (1.3.6.1.4.1.311.21.20). For
more information, see CERTENROLL_OBJECTID. The attribute is created as an Abstract Syntax Notation One
(ASN.1) structure that is encoded by using Distinguished Encoding Rules (DER).
You must call either InitializeEncode or InitializeDecode before you can use an IX509AttributeClientId object.
The two methods complement each other. The InitializeEncode method enables you to construct an encoded
ASN.1 structure from raw data, and the InitializeDecode method enables you to initialize raw data from an
encoded ASN.1 structure. You can call the following properties to retrieve the raw data:
ClientId
MachineDnsName
ProcessName
UserSamName

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509AttributeClientId
 IX509AttributeCspProvider interface (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The IX509AttributeCspProvider interface represents an attribute that identifies the cryptographic provider
used by the entity requesting the certificate. Cryptographic providers and key containers are used to generate
and store keys and perform encryption, signing, and hashing.
This attribute is automatically placed in the PKCS #10 attribute collection when you call the Encode method.

Inheritance
The IX509AttributeCspProvider interface inherits from IX509Attribute. IX509AttributeCspProvider also
has these types of members:

Methods
The IX509AttributeCspProvider interface has these methods.

IX509AttributeCspProvider::get_KeySpec

Retrieves a value that identifies whether the key pair stored by the provider or key container is used for encryption or for
signing content.

IX509AttributeCspProvider::get_ProviderName

Retrieves the provider name.

IX509AttributeCspProvider::get_Signature

Retrieves the digital signature on the provider.

IX509AttributeCspProvider::InitializeDecode

Initializes the object from a Distinguished Encoding Rules (DER) encoded byte array that contains information about the
provider.

IX509AttributeCspProvider::InitializeEncode

Initializes the attribute from information about the provider.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

 Header certenroll.h

See also
CertEnroll Interfaces
IX509Attribute
IX509Attributes
 IX509AttributeCspProvider::get_KeySpec method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The KeySpec property retrieves a value that identifies whether the key pair stored by the provider or key
container is used for encryption or for signing content.
This property is read-only.

Syntax
HRESULT get_KeySpec(
X509KeySpec *pValue
);

Parameters
pValue

Return value
None

Remarks
Call the InitializeEncode method or the InitializeDecode method to initialize the KeySpec property. You can also
call the following properties to retrieve raw data:
ProviderName
Signature

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509AttributeCspProvider
 IX509AttributeCspProvider::get_ProviderName
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The ProviderName property retrieves the provider name.

This property is read-only.

Syntax
HRESULT get_ProviderName(
BSTR *pValue
);

Parameters
pValue

Return value
None

Remarks
Call the InitializeEncode method or the InitializeDecode method to initialize the ProviderName property. You
can also call the following properties to retrieve raw data:
KeySpec
Signature

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509AttributeCspProvider
 IX509AttributeCspProvider::get_Signature method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Signature property retrieves the digital signature on the provider. The signature is contained in a byte
array represented by a Unicode-encoded string.
This property is read-only.

Syntax
HRESULT get_Signature(
EncodingType Encoding,
BSTR *pValue
);

Parameters
Encoding

pValue

Return value
None

Remarks
Call the InitializeEncode method or the InitializeDecode method to initialize the Signature property. You can call
the following properties to retrieve the raw data:
KeySpec
ProviderName

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll
See also
IX509AttributeCspProvider
 IX509AttributeCspProvider::InitializeDecode method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The InitializeDecode method initializes the object from a Distinguished Encoding Rules (DER) encoded byte
array that contains information about the provider. The byte array is represented by a Unicode-encoded string.

Syntax
HRESULT InitializeDecode(
[in] EncodingType Encoding,
[in] BSTR strEncodedData
);

Parameters
[in] Encoding

An EncodingType enumeration value that specifies the type of Unicode encoding applied to the input string.
[in] strEncodedData

A BSTR variable that contains the DER-encoded attribute.

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.

Remarks
The object identifier (OID) for this attribute is XCN_OID_ENROLLMENT_CSP_PROVIDER
(1.3.6.1.4.1.311.13.2.2). For more information, see CERTENROLL_OBJECTID.
You can use this method if you have a DER-encoded Abstract Syntax Notation One (ASN.1) object that contains
the attribute value. You must supply the DER-encoded object in a Unicode encoded string. For more information,
see the IBinaryConverter interface.
You must call either InitializeEncode or InitializeDecode before you can use an IX509AttributeCspProvider
object. The two methods complement each other. The InitializeEncode method enables you to construct an
encoded ASN.1 structure from raw data, and the InitializeDecode method enables you to initialize raw data
from an encoded ASN.1 structure. You can call the following properties to retrieve the raw data:
KeySpec
ProviderName
Signature

Requirements
 Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509AttributeCspProvider
 IX509AttributeCspProvider::InitializeEncode method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The InitializeEncode method initializes the attribute from information about the provider.

Syntax
HRESULT InitializeEncode(
[in] X509KeySpec KeySpec,
[in] BSTR strProviderName,
[in] EncodingType Encoding,
[in] BSTR strSignature
);

Parameters
[in] KeySpec

An X509KeySpec enumeration value that identifies whether the key pair is used for encryption or for signing.
[in] strProviderName

A BSTR variable that contains the provider name.

[in] Encoding

An EncodingType enumeration value that specifies the type of Unicode encoding applied to the signature
contained in the strSignature parameter.
[in] strSignature

A BSTR variable that contains the provider signature.

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.

Remarks
The object identifier (OID) for this attribute is XCN_OID_ENROLLMENT_CSP_PROVIDER
(1.3.6.1.4.1.311.13.2.2). For more information, see CERTENROLL_OBJECTID.
You must call either InitializeEncode or InitializeDecode before you can use an IX509AttributeCspProvider
object. The two methods complement each other. The InitializeEncode method enables you to construct an
encoded Abstract Syntax Notation One (ASN.1) structure from raw data, and the InitializeDecode method
enables you to initialize raw data from an encoded ASN.1 structure. You can call the following properties to
retrieve the raw data:
 KeySpec
ProviderName
Signature

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509AttributeCspProvider
 IX509AttributeExtensions interface (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The IX509AttributeExtensions interface defines methods and properties that initialize and retrieve certificate
extensions in a certificate request. For example, the Cer tificateRequestInfo structure of a PKCS #10 request
does not contain a field for version 3 extensions. Instead, the extensions must be added to the attributes
collection in the request.

CertificationRequestInfo ::= SEQUENCE

{
version INTEGER { v1(0) } (v1,...),
subject Name,
subjectPKInfo SubjectPublicKeyInfo{{ PKInfoAlgorithms }},
attributes [0] Attributes{{ CRIAttributes }}
}

Also, extensions are included in a CMC request by adding them to the TaggedAttributes structure shown in the
following Abstract Syntax Notation One (ASN.1) syntax example. For more information, see Attributes and
Extensions.

CmcData ::= SEQUENCE

{
controlSequence ControlSequence,
reqSequence ReqSequence,
cmsSequence CmsSequence,
otherMsgSequence OtherMsgSequence
}

ControlSequence ::= SEQUENCE OF TaggedAttribute

TaggedAttribute ::= SEQUENCE

{
bodyPartID BodyPartID,
type EncodedObjectID,
values AttributeSetValue
}

BodyPartID ::= INTEGER (0..4294967295)

EncodedObjectID ::= OBJECT IDENTIFIER
AttributeSetValue ::= SET OF ANY

You can create one or more version 3 extensions and include them in a certificate request in the following
manner:
Initialize any of the following IX509Extension objects:
IX509ExtensionAlternativeNames
IX509ExtensionAuthorityKeyIdentifier
IX509ExtensionBasicConstraints
IX509ExtensionCertificatePolicies
IX509ExtensionMSApplicationPolicies
 IX509ExtensionEnhancedKeyUsage
IX509ExtensionKeyUsage
IX509ExtensionSmimeCapabilities
IX509ExtensionSubjectKeyIdentifier
IX509ExtensionTemplate
IX509ExtensionTemplateName
Add the extension objects into an IX509Extensions collection.
Use the IX509Extensions collection to initialize an IX509AttributeExtensions object.
Add the IX509AttributeExtensions object to an IX509Attributes collection.
Use the IX509Attributes collection to initialize an ICryptAttribute object.
Initialize a CMC or PKCS #10 request object and retrieve the ICryptAttributes collection.
Add the ICryptAttribute object to the ICryptAttributes collection for the request.

Inheritance
The IX509AttributeExtensions interface inherits from IX509Attribute. IX509AttributeExtensions also has
these types of members:

Methods
The IX509AttributeExtensions interface has these methods.

IX509AttributeExtensions::get_X509Extensions

Retrieves the certificate extensions.

IX509AttributeExtensions::InitializeDecode

Initializes the object from a Distinguished Encoding Rules (DER) encoded byte array that contains the attribute value.

IX509AttributeExtensions::InitializeEncode

Initializes the object from an IX509Extensions collection.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

See also
CertEnroll Interfaces
IX509Attribute
IX509Attributes
 IX509AttributeExtensions::get_X509Extensions
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The X509Extensions property retrieves the certificate extensions.

This property is read-only.

Syntax
HRESULT get_X509Extensions(
IX509Extensions **ppValue
);

Parameters
ppValue

Return value
None

Remarks
Call the InitializeEncode method or the InitializeDecode method to initialize the X509Extensions property.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509Attribute
IX509AttributeExtensions
IX509Attributes
 IX509AttributeExtensions::InitializeDecode method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The InitializeDecode method initializes the object from a Distinguished Encoding Rules (DER) encoded byte
array that contains the attribute value. The byte array is represented by a Unicode-encoded string.

Syntax
HRESULT InitializeDecode(
[in] EncodingType Encoding,
[in] BSTR strEncodedData
);

Parameters
[in] Encoding

An EncodingType enumeration value that specifies the type of Unicode encoding applied to the input string.
[in] strEncodedData

A BSTR variable that contains the encoded extensions.

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.

Remarks
The object identifier (OID) for this attribute is XCN_OID_RSA_cer tExtensions (1.2.840.113549.1.9.14). For
more information, see CERTENROLL_OBJECTID.
You can use this method if you have a DER-encoded ASN.1 object that contains an attribute value. You must
supply the DER-encoded object in a Unicode encoded string. For more information, see the IBinaryConverter
interface.
You must call either InitializeEncode or InitializeDecode before you can use an IX509AttributeExtensions
object. The two methods complement each other. The InitializeEncode method enables you to construct an
encoded Abstract Syntax Notation One (ASN.1) structure from raw data, and the InitializeDecode method
enables you to initialize raw data from an encoded ASN.1 structure that contains the certificate extensions. You
can call the X509Extensions property to retrieve the extensions.

Requirements
 Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IBinaryConverter
IX509Attribute
IX509AttributeExtensions
IX509Attributes
 IX509AttributeExtensions::InitializeEncode method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The InitializeEncode method initializes the object from an IX509Extensions collection.

Syntax
HRESULT InitializeEncode(
[in] IX509Extensions *pExtensions
);

Parameters
[in] pExtensions

Pointer to an IX509Extensions interface that contains the collection.

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.

Remarks
The object identifier for this attribute is XCN_OID_RSA_cer tExtensions (1.2.840.113549.1.9.14). For more
information, see CERTENROLL_OBJECTID.
You must call either InitializeEncode or InitializeDecode before you can use an IX509AttributeExtensions
object. The two methods complement each other. The InitializeEncode method enables you to construct an
encoded Abstract Syntax Notation One (ASN.1) structure from raw data, and the InitializeDecode method
enables you to initialize raw data from an encoded ASN.1 structure that contains the certificate extensions. You
can call the X509Extensions property to retrieve the extensions.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h
 DLL CertEnroll.dll

See also
IX509Attribute
IX509AttributeExtensions
IX509Attributes
 IX509AttributeOSVersion interface (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The IX509AttributeOSVersion interface represents an attribute that contains version information about the
client operating system on which the certificate request was generated. The information includes the major and
minor versions, the build number, and the platform identifier.

Inheritance
The IX509AttributeOSVersion interface inherits from IX509Attribute. IX509AttributeOSVersion also has
these types of members:

Methods
The IX509AttributeOSVersion interface has these methods.

IX509AttributeOSVersion::get_OSVersion

Retrieves the client operating system version information.

IX509AttributeOSVersion::InitializeDecode

Initializes the object from a Distinguished Encoding Rules (DER) encoded byte array that contains the operating system version
information.

IX509AttributeOSVersion::InitializeEncode

Initializes the attribute from operating system version information.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

See also
CertEnroll Interfaces
IX509Attribute
IX509Attributes
 IX509AttributeOSVersion::get_OSVersion method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The OSVersion property retrieves the client operating system version information.
This property is read-only.

Syntax
HRESULT get_OSVersion(
BSTR *pValue
);

Parameters
pValue

Return value
None

Remarks
Call the InitializeEncode method or the InitializeDecode method to initialize the OSVersion property.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509AttributeOSVersion
 IX509AttributeOSVersion::InitializeDecode method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The InitializeDecode method initializes the object from a Distinguished Encoding Rules (DER) encoded byte
array that contains the operating system version information. The byte array is represented by a Unicode-
encoded string.

Syntax
HRESULT InitializeDecode(
[in] EncodingType Encoding,
[in] BSTR strEncodedData
);

Parameters
[in] Encoding

An EncodingType enumeration value that specifies the type of Unicode encoding applied to the input string.
[in] strEncodedData

A BSTR variable that contains the DER-encoded attribute.

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.

Remarks
The object identifier (OID) for this attribute is XCN_OID_OS_VERSION (1.3.6.1.4.1.311.13.2.3). For more
information, see CERTENROLL_OBJECTID.
You can use this method if you have a DER-encoded Abstract Syntax Notation One (ASN.1) object that contains
the attribute value. You must supply the DER-encoded object in a Unicode encoded string. For more information,
see the IBinaryConverter interface.
You must call either InitializeEncode or InitializeDecode before you can use an IX509AttributeOSVersion
object. The two methods complement each other. The InitializeEncode method enables you to construct an
encoded ASN.1 structure from raw data, and the InitializeDecode method enables you to initialize raw data
from an encoded ASN.1 structure. You can call the OSVersion property to retrieve the raw data.

Requirements
 Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509AttributeOSVersion
 IX509AttributeOSVersion::InitializeEncode method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The InitializeEncode method initializes the attribute from operating system version information.

Syntax
HRESULT InitializeEncode(
[in, optional] BSTR strOSVersion
);

Parameters
[in, optional] strOSVersion

A BSTR variable that contains the version information. The format of the string is major.minor.build.platform.
This parameter is optional. If you do not specify a string, this method calls the GetVersionEx function.

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.

Remarks
The object identifier (OID) for this attribute is XCN_OID_OS_VERSION (1.3.6.1.4.1.311.13.2.3). For more
information, see CERTENROLL_OBJECTID.
You must call either InitializeEncode or InitializeDecode before you can use an IX509AttributeOSVersion
object. The two methods complement each other. The InitializeEncode method enables you to construct an
encoded Abstract Syntax Notation One (ASN.1) structure from raw data, and the InitializeDecode method
enables you to initialize raw data from an encoded ASN.1 structure. You can call the OSVersion property to
retrieve the raw data.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h
 DLL CertEnroll.dll

See also
IX509AttributeOSVersion
 IX509AttributeRenewalCertificate interface
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The IX509AttributeRenewalCer tificate interface represents an attribute that contains the certificate being
renewed. This attribute is automatically placed in the PKCS #10 attribute collection when you call the Encode
method.

Inheritance
The IX509AttributeRenewalCer tificate interface inherits from IX509Attribute.
IX509AttributeRenewalCer tificate also has these types of members:

Methods
The IX509AttributeRenewalCer tificate interface has these methods.

IX509AttributeRenewalCertificate::get_RenewalCertificate

Retrieves the certificate to be renewed.

IX509AttributeRenewalCertificate::InitializeDecode

Initializes the object from a Distinguished Encoding Rules (DER) encoded byte array that contains the certificate to be renewed.

IX509AttributeRenewalCertificate::InitializeEncode

Initializes the attribute by using the certificate to be renewed.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

See also
CertEnroll Interfaces
IX509Attribute
IX509Attributes
 IX509AttributeRenewalCertificate::get_RenewalCertificate
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The RenewalCer tificate property retrieves the certificate to be renewed. The Distinguished Encoding Rules
(DER) encoded certificate is contained in a byte array that is represented by a Unicode-encoded string.
This property is read-only.

Syntax
HRESULT get_RenewalCertificate(
EncodingType Encoding,
BSTR *pValue
);

Parameters
Encoding

pValue

Return value
None

Remarks
Call the InitializeEncode method or the InitializeDecode method to initialize the RenewalCer tificate property.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509AttributeRenewalCertificate
 IX509AttributeRenewalCertificate::InitializeDecode
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The InitializeDecode method initializes the object from a Distinguished Encoding Rules (DER) encoded byte
array that contains the certificate to be renewed. The byte array is represented by a Unicode-encoded string.

Syntax
HRESULT InitializeDecode(
[in] EncodingType Encoding,
[in] BSTR strEncodedData
);

Parameters
[in] Encoding

An EncodingType enumeration value that specifies the type of Unicode encoding applied to the input string.
[in] strEncodedData

A BSTR variable that contains the DER-encoded certificate.

Beginning with Windows 7 and Windows Server 2008 R2, you can specify a certificate thumb print or serial
number rather than an encoded certificate. Doing so causes the function to search the appropriate local stores
for the matching certificate. Keep in mind the following points:
The BSTR must be an even number of hexadecimal digits.
Whitespace between hexadecimal pairs is ignored.
The Encoding parameter must be set to XCN_CRYPT_STRING_HEXRAW .
If a private key is needed, only the personal and request stores are searched.
If a private key is not needed, the root and intermediate CA stores are also searched.

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.

Remarks
The object identifier (OID) for this attribute is XCN_OID_RENEWAL_CERTIFICATE (1.3.6.1.4.1.311.13.1). For
more information, see CERTENROLL_OBJECTID.
You can use this method if you have a DER-encoded Abstract Syntax Notation One (ASN.1) object that contains
the attribute value. You must supply the DER-encoded object in a Unicode encoded string. For more information,
see the IBinaryConverter interface.
You must call either InitializeEncode or InitializeDecode before you can use an
IX509AttributeRenewalCertificate object. The two methods complement each other. The InitializeEncode
method enables you to construct an encoded ASN.1 structure from raw data, and the InitializeDecode method
enables you to initialize raw data from an encoded ASN.1 structure. You can call the RenewalCertificate property
to retrieve the raw data.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509AttributeRenewalCertificate
 IX509AttributeRenewalCertificate::InitializeEncode
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The InitializeEncode method initializes the attribute by using the certificate to be renewed. The certificate must
be encoded by using Distinguished Encoding Rules (DER).

Syntax
HRESULT InitializeEncode(
[in] EncodingType Encoding,
[in] BSTR strCert
);

Parameters
[in] Encoding

An EncodingType enumeration value that specifies the type of Unicode encoding applied to the certificate
contained in the strCert parameter.
[in] strCert

A BSTR variable that contains the DER-encoded certificate.

Beginning with Windows 7 and Windows Server 2008 R2, you can specify a certificate thumb print or serial
number rather than an encoded certificate. Doing so causes the function to search the appropriate local stores
for the matching certificate. Keep in mind the following points:
The BSTR must be an even number of hexadecimal digits.
Whitespace between hexadecimal pairs is ignored.
The Encoding parameter must be set to XCN_CRYPT_STRING_HEXRAW .
If a private key is needed, only the personal and request stores are searched.
If a private key is not needed, the root and intermediate CA stores are also searched.

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.

Remarks
The object identifier (OID) for this attribute is XCN_OID_RENEWAL_CERTIFICATE (1.3.6.1.4.1.311.13.1). For
more information, see CERTENROLL_OBJECTID.
You must call either InitializeEncode or InitializeDecode before you can use an
IX509AttributeRenewalCertificate object. The two methods complement each other. The InitializeEncode
method enables you to construct an encoded Abstract Syntax Notation One (ASN.1) structure from raw data,
and the InitializeDecode method enables you to initialize raw data from an encoded ASN.1 structure. You can
call the RenewalCertificate property to retrieve the raw data.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509AttributeRenewalCertificate
 IX509Attributes interface (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The IX509Attributes interface defines the following methods and properties that enable you to manage a
collection of IX509Attribute objects.

Inheritance
The IX509Attributes interface inherits from the IDispatch interface. IX509Attributes also has these types of
members:

Methods
The IX509Attributes interface has these methods.

IX509Attributes::Add

Adds an IX509Attribute object to the collection.

IX509Attributes::Clear

Removes all IX509Attribute objects from the collection.

IX509Attributes::get__NewEnum

Retrieves the enumerator for the collection.

IX509Attributes::get_Count

Retrieves the number of IX509Attribute objects in the collection.

IX509Attributes::get_ItemByIndex

Retrieves an IX509Attribute object from the collection by index number.

IX509Attributes::Remove

Removes an IX509Attribute object from the collection by index number.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

 Header certenroll.h

See also
CertEnroll Interfaces
IDispatch
IX509Attribute
IX509AttributeExtensions
IX509Attributes
 IX509Attributes::Add method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Add method adds an IX509Attribute object to the collection.

Syntax
HRESULT Add(
[in] IX509Attribute *pVal
);

Parameters
[in] pVal

Pointer to an IX509Attribute interface that represents the attribute to add to the collection.

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509Attribute
IX509AttributeExtensions
IX509Attributes
 IX509Attributes::Clear method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Clear method removes all IX509Attribute objects from the collection.

Syntax
HRESULT Clear();

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509Attribute
IX509AttributeExtensions
IX509Attributes
 IX509Attributes::get__NewEnum method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The _NewEnum property retrieves the enumerator for the collection.

This property is read-only.

Syntax
HRESULT get__NewEnum(
LPUNKNOWN *pVal
);

Parameters
pVal

Return value
None

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509Attribute
IX509AttributeExtensions
IX509Attributes
 IX509Attributes::get_Count method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Count property retrieves the number of IX509Attribute objects in the collection.
This property is read-only.

Syntax
HRESULT get_Count(
long *pVal
);

Parameters
pVal

Return value
None

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509Attribute
IX509AttributeExtensions
IX509Attributes
 IX509Attributes::Remove method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Remove method removes an IX509Attribute object from the collection by index number.

Syntax
HRESULT Remove(
[in] LONG Index
);

Parameters
[in] Index

A LONG variable that contains the index of the object to remove.

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509Attribute
IX509AttributeExtensions
IX509Attributes
 IX509CertificateRequest interface (certenroll.h)
7/2/2022 • 3 minutes to read • Edit Online

The IX509Cer tificateRequest interface represents an abstract base certificate request that identifies methods
and properties common to and inherited by each of the request objects implemented by the Certificate
Enrollment API. The following list discusses the inheritance structure of these objects:
A PKCS #10 certificate request implements the IX509Cer tificateRequest and

IX509CertificateRequestPkcs10 interfaces.
PKCS #7 certificate request implements the IX509Cer tificateRequest and IX509CertificateRequestPkcs7

interfaces.
Although the PKCS #7 specification defines a secure message syntax rather than a type of certificate
request, the implementation of the IX509CertificateRequestPkcs7 interface in this SDK requires that it
contain a PKCS #10 request. Therefore, this documentation refers to a PKCS #7 object as a certificate
request.
A CMC (Certificate Management Message over CMS) certificate request implements the
IX509Cer tificateRequest , IX509CertificateRequestPkcs7, and IX509CertificateRequestCmc interfaces.

An object that can be used to represent a self-generated certificate (a certificate not issued by a certification
authority) implements the IX509Cer tificateRequest , IX509CertificateRequestPkcs10, and

IX509CertificateRequestCertificate interfaces.

Inheritance
The IX509Cer tificateRequest interface inherits from the IDispatch interface. IX509Cer tificateRequest also
has these types of members:

Methods
The IX509Cer tificateRequest interface has these methods.
IX509CertificateRequest::Encode

Signs and encodes a certificate request and creates a key pair if one does not exist.

IX509CertificateRequest::get_AlternateSignatureAlgorithm

Specifies and retrieves a Boolean value that indicates whether the signature algorithm object identifier (OID) for a PKCS

IX509CertificateRequest::get_ClientId

Specifies and retrieves a value that identifies the executable that created the request.

IX509CertificateRequest::get_CspInformations

Specifies and retrieves a collection of cryptographic providers available for use by the request object.

IX509CertificateRequest::get_EnrollmentContext

Retrieves a value that specifies whether the certificate is intended for a computer or a user.

IX509CertificateRequest::get_HashAlgorithm

Specifies and retrieves the object identifier (OID) of the hash algorithm used to sign the certificate request.

IX509CertificateRequest::get_ParentWindow

Specifies and retrieves the ID of the window used by key-related user interface dialogs.

IX509CertificateRequest::get_RawData

Retrieves a byte array that contains the signed, Distinguished Encoding Rules (DER) encoded certificate request.

IX509CertificateRequest::get_RenewalCertificate

Specifies or retrieves a byte array that contains the Distinguished Encoding Rules (DER) encoded certificate that is being
renewed.

IX509CertificateRequest::get_Silent

Specifies or retrieves a Boolean value that indicates whether any of the key-related modal dialogs are displayed during the
certificate enrollment process.

IX509CertificateRequest::get_SuppressDefaults

Specifies or retrieves a Boolean value that indicates whether the default extensions and attributes are included in the request.

IX509CertificateRequest::get_Type

Retrieves a value that specifies the type of the request object.

IX509CertificateRequest::get_UIContextMessage

Specifies or retrieves a context string to display in the user interface.

 IX509CertificateRequest::GetInnerRequest

Retrieves a nested request object.

IX509CertificateRequest::Initialize

Initializes the request object for a user or a computer.

IX509CertificateRequest::put_AlternateSignatureAlgorithm

Specifies and retrieves a Boolean value that indicates whether the signature algorithm object identifier (OID) for a PKCS

IX509CertificateRequest::put_ClientId

Specifies and retrieves a value that identifies the executable that created the request.

IX509CertificateRequest::put_CspInformations

Specifies and retrieves a collection of cryptographic providers available for use by the request object.

IX509CertificateRequest::put_HashAlgorithm

Specifies and retrieves the object identifier (OID) of the hash algorithm used to sign the certificate request.

IX509CertificateRequest::put_ParentWindow

Specifies and retrieves the ID of the window used by key-related user interface dialogs.

IX509CertificateRequest::put_RenewalCertificate

Specifies or retrieves a byte array that contains the Distinguished Encoding Rules (DER) encoded certificate that is being
renewed.

IX509CertificateRequest::put_Silent

Specifies or retrieves a Boolean value that indicates whether any of the key-related modal dialogs are displayed during the
certificate enrollment process.

IX509CertificateRequest::put_SuppressDefaults

Specifies or retrieves a Boolean value that indicates whether the default extensions and attributes are included in the request.

IX509CertificateRequest::put_UIContextMessage

Specifies or retrieves a context string to display in the user interface.

IX509CertificateRequest::ResetForEncode

Restores the state of the request object to that which existed before the Encode method was called.

Requirements
 Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

See also
CertEnroll Interfaces
IDispatch
IX509CertificateRequestCertificate
IX509CertificateRequestCmc
IX509CertificateRequestPkcs10
IX509CertificateRequestPkcs7
 IX509CertificateRequest::Encode method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Encode method signs and encodes a certificate request and creates a key pair if one does not exist. The
request is encoded by using Distinguished Encoding Rules (DER) as defined by the Abstract Syntax Notation
One (ASN.1) standard. The encoding process creates a byte array. You can retrieve the byte array by calling the
RawData property.

Syntax
HRESULT Encode();

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. Possible values include, but are not
limited to, those in the following table. For a list of common error codes, see Common HRESULT Values.

RET URN C O DE/ VA L UE DESC RIP T IO N

The ArchivePrivateKey property has been set for a CMC

CERTSRV_E_ARCHIVED_KEY_REQUIRED request but a key exchange certificate could not be found.

The object is not initialized.

OLE_E_BL ANK

Remarks
For a PKCS #10 request, this method:
Updates the private key or creates the key if necessary.
Populates the public key from the private key.
Updates the extensions, adding any default extensions and taking account of the suppressed OID collection
and critical extension OID collection.
Updates the attributes, adding default attributes and taking account of the suppressed OID collection.
Assembles and encodes the unsigned updated request.
Creates and encodes a signature.
Encodes the signature and the unsigned request.
For a CMC request, this method:
Encodes all inner request objects.
Updates the extensions for the outer request object, adding any default extensions and taking account of the
suppressed OID collection and critical extension OID collection.
Updates the attributes for the outer request object, adding default attributes and taking account of the
 suppressed OID collection.
Updates the name-value pair collection.
Encodes the CMC content that consists of the encoded inner request and the updated outer request.
Creates and encodes a signature for each signing certificate.
Creates and encodes a primary signature.
Assembles the encoded CMC content (including the inner request and the updated outer request) and the
encoded signatures.
Encodes the assembled content into a PKCS #7 message.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509CertificateRequest
IX509CertificateRequestCertificate
IX509CertificateRequestCmc
IX509CertificateRequestPkcs10
IX509CertificateRequestPkcs7
IX509SignatureInformation
 IX509CertificateRequest::get_AlternateSignatureAlgorithm
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The AlternateSignatureAlgorithm property specifies and retrieves a Boolean value that indicates whether the
signature algorithm object identifier (OID) for a PKCS #10 request or certificate signature is discrete or
combined. A PKCS #10 object can be a stand-alone request or it can be contained in a CMC or PKCS #7 request
object.
This property is read/write.

Syntax
HRESULT get_AlternateSignatureAlgorithm(
VARIANT_BOOL *pValue
);

Parameters
pValue

Return value
None

Remarks
Discrete algorithms are represented by separate object identifiers (OIDs) for the hashing algorithm and the
signing algorithm. Examples include the following values.

DISC RET E A L GO RIT H M O ID DESC RIP T IO N

XCN_OID_NIST_sha256 National Institute of Standards and Technologies (NIST) 256-

(2.16.840.1.101.3.4.2.1) bit SHA hashing algorithm.

XCN_OID_OIWSEC_rsaSign NIST OSE Implementer Workshop Security (OIWSEC) RSA

(1.3.14.3.2.11) signing algorithm.

Combined algorithms are represented by a single OID that identifies both the hashing and the signing
algorithm. Examples include the following values.

C O M B IN ED A L GO RIT H M O ID DESC RIP T IO N

XCN_OID_RSA_MD2RSA MD2 hashing algorithm combined with the RSA encryption

(1.2.840.113549.1.1.2) algorithm from RSA Laboratories.
 XCN_OID_OIWSEC_md5RSA OIWSEC MD5 hashing algorithm combined with the RSA
(1.3.14.3.2.3) encryption algorithm.

If the certificate request contains nested requests and you set the AlternateSignatureAlgorithm property on
the top level request, it is automatically propagated to all of the inner requests. You can, however, set the
property manually on each of the inner objects.
For a PKCS #7 or a CMC request, this property retrieves a Boolean value for the primary signature on the inner
PKCS #10 request. On input, all signer certificates are updated with the specified property value.
For a PKCS #10 request or certificate signature using the RSA public key algorithm, a property value of False
(which indicates a combined OID) implies a version 1.5 signature and True (discrete OID) implies a version 2.1
signature.
You must initialize the request object before calling this property. You can call this property before calling the
Encode method.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509CertificateRequest
IX509CertificateRequestCertificate
IX509CertificateRequestCmc
IX509CertificateRequestPkcs10
IX509CertificateRequestPkcs7
IX509SignatureInformation
 IX509CertificateRequest::get_ClientId method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The ClientId property specifies and retrieves a value that identifies the executable that created the request. For
example, a request can be generated by using a request wizard, by an auto-enrollment process, or by other
means. This property is web enabled for both input and output.
This property is read/write.

Syntax
HRESULT get_ClientId(
RequestClientInfoClientId *pValue
);

Parameters
pValue

Return value
None

Remarks
You must initialize the request object before calling this property. You can call this property before calling the
Encode method.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509CertificateRequest
IX509CertificateRequestCertificate
IX509CertificateRequestCmc
IX509CertificateRequestPkcs10
IX509CertificateRequestPkcs7
IX509SignatureInformation
 IX509CertificateRequest::get_CspInformations
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The CspInformations property specifies and retrieves a collection of cryptographic providers available for use
by the request object.
This property is read/write.

Syntax
HRESULT get_CspInformations(
ICspInformations **ppValue
);

Parameters
ppValue

Return value
None

Remarks
If you want to specify a collection of providers, you must set this property before calling the Initialize method.
The collection that you specify must contain all providers currently installed on the computer. If you specify a
subset or a superset, the behavior of this property is undefined.
If you do not specify a collection, the Initialize method sets the property value to a collection of all providers
installed on the computer.
The CspInformations property exists so that the caller can avoid forcing the request object to fill the collection.
This is useful when the caller is creating multiple requests in one session.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll
See also
IX509CertificateRequest
IX509CertificateRequestCertificate
IX509CertificateRequestCmc
IX509CertificateRequestPkcs10
IX509CertificateRequestPkcs7
IX509SignatureInformation
 IX509CertificateRequest::get_EnrollmentContext
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The EnrollmentContext property retrieves a value that specifies whether the certificate is intended for a
computer or a user.
This property is read-only.

Syntax
HRESULT get_EnrollmentContext(
X509CertificateEnrollmentContext *pValue
);

Parameters
pValue

Return value
None

Remarks
For a PKCS #7 or CMC request, the property value is retrieved from the inner request object.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509CertificateRequest
IX509CertificateRequestCertificate
IX509CertificateRequestCmc
IX509CertificateRequestPkcs10
IX509CertificateRequestPkcs7
IX509SignatureInformation
 IX509CertificateRequest::get_HashAlgorithm
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The HashAlgorithm property specifies and retrieves the object identifier (OID) of the hash algorithm used to
sign the certificate request. This property is web enabled for both input and output.
This property is read/write.

Syntax
HRESULT get_HashAlgorithm(
IObjectId **ppValue
);

Parameters
ppValue

Return value
None

Remarks
If the certificate request contains nested requests and you set the HashAlgorithm property on the top level
request, it is automatically propagated to all of the inner requests, overwriting values that may have been
previously set. You can, however, set the property manually on each of the inner objects.
You must initialize the request object before calling this property. You can call this property before calling the
Encode method.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509CertificateRequest
IX509CertificateRequestCertificate
IX509CertificateRequestCmc
IX509CertificateRequestPkcs10
IX509CertificateRequestPkcs7
IX509SignatureInformation
 IX509CertificateRequest::get_ParentWindow method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The ParentWindow property specifies and retrieves the ID of the window used by key-related user interface
dialogs.
This property is read/write.

Syntax
HRESULT get_ParentWindow(
LONG *pValue
);

Parameters
pValue

Return value
None

Remarks
This property value is used by key-related Certificate Enrollment Control modal dialogs that:
Direct a user to insert a smart card
Request a smart card pin number
Request the protection level for a new key
Request a user password before accessing a key
If your application uses key-related modal dialogs, we recommend that you use this property to ensure that
your window displays in front of other windows and that the requested action is performed before the thread
can be unblocked.
You can set this property before calling any initialization method or the Encode method. If the certificate request
contains nested requests and you set the ParentWindow property on the top level request, it is automatically
propagated to all of the inner requests. You can, however, set the property manually on each of the inner objects.
For a PKCS #10 request, the property value is retrieved from and specified on the associated IX509PrivateKey
object if the key exists. For a PKCS #7 or CMC request the window ID is updated on the inner request and all
signing certificates.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

 Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509CertificateRequest
IX509CertificateRequestCertificate
IX509CertificateRequestCmc
IX509CertificateRequestPkcs10
IX509CertificateRequestPkcs7
IX509SignatureInformation
 IX509CertificateRequest::get_RawData method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The RawData property retrieves a byte array that contains the signed, Distinguished Encoding Rules (DER)
encoded certificate request. The byte array is represented by a Unicode-encoded string.
This property is read-only.

Syntax
HRESULT get_RawData(
EncodingType Encoding,
BSTR *pValue
);

Parameters
Encoding

pValue

Return value
None

Remarks
Call the Encode method to encode a certificate request using DER as defined by the Abstract Syntax Notation
One (ASN.1) standard. The encoding process creates a byte array that the RawData property returns as a string.
The string is either a pure binary sequence, or it is Unicode encoded so that it can be displayed as text.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509CertificateRequest
IX509CertificateRequestCertificate
IX509CertificateRequestCmc
IX509CertificateRequestPkcs10
IX509CertificateRequestPkcs7
IX509SignatureInformation
 IX509CertificateRequest::get_RenewalCertificate
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The RenewalCer tificate property specifies or retrieves a byte array that contains the Distinguished Encoding
Rules (DER) encoded certificate that is being renewed. The DER-encoded byte array is represented by a Unicode-
encoded string.
This property is read/write.

Syntax
HRESULT get_RenewalCertificate(
EncodingType Encoding,
BSTR *pValue
);

Parameters
Encoding

pValue

Return value
None

Remarks
The certificate is encoded by using DER as defined by the Abstract Syntax Notation One (ASN.1) standard. The
encoding process creates a byte array. The byte array is returned in a string that is either a pure binary sequence
or is Unicode encoded so that it can be displayed as text.
You must initialize the request object before calling this property. You can call this property before calling the
Encode method.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll
See also
IX509CertificateRequest
IX509CertificateRequestCertificate
IX509CertificateRequestCmc
IX509CertificateRequestPkcs10
IX509CertificateRequestPkcs7
IX509SignatureInformation
 IX509CertificateRequest::get_Silent method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Silent property specifies or retrieves a Boolean value that indicates whether any of the key-related modal
dialogs are displayed during the certificate enrollment process.
This property is read/write.

Syntax
HRESULT get_Silent(
VARIANT_BOOL *pValue
);

Parameters
pValue

Return value
None

Remarks
This property value is used by key-related Certificate Enrollment Control modal dialogs that:
Direct a user to insert a smart card
Request a smart card pin number
Request the protection level for a new key
Request a user password before accessing a key
You can set this property before calling any initialization method or the Encode method. For a PKCS #10 request,
the property value is retrieved from and specified on the associated IX509PrivateKey object if the key exists. For
a PKCS #7 or CMC request the property value is updated on the inner request and all signing certificates.
If the certificate request contains nested requests and you set the Silent property on the top level request, it is
automatically propagated to all of the inner requests. You can, however, set the property manually on each of the
inner objects.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]
 Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509CertificateRequest
IX509CertificateRequestCertificate
IX509CertificateRequestCmc
IX509CertificateRequestPkcs10
IX509CertificateRequestPkcs7
IX509SignatureInformation
 IX509CertificateRequest::get_SuppressDefaults
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The SuppressDefaults property specifies or retrieves a Boolean value that indicates whether the default
extensions and attributes are included in the request. The defaults are represented by their object identifiers
(OIDs).
This property is read/write.

Syntax
HRESULT get_SuppressDefaults(
VARIANT_BOOL *pValue
);

Parameters
pValue

Return value
None

Remarks
You must initialize the request object before calling this property. Set this property before calling the Encode
method to suppress inclusion and encoding of default extensions and attributes in the certificate request.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509CertificateRequest
IX509CertificateRequestCertificate
IX509CertificateRequestCmc
IX509CertificateRequestPkcs10
IX509CertificateRequestPkcs7
IX509SignatureInformation
 IX509CertificateRequest::get_Type method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Type property retrieves a value that specifies the type of the request object.
This property is read-only.

Syntax
HRESULT get_Type(
X509RequestType *pValue
);

Parameters
pValue

Return value
None

Remarks
You can use this property with the GetInnerRequest method to determine the type of the inner request object.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509CertificateRequest
IX509CertificateRequestCertificate
IX509CertificateRequestCmc
IX509CertificateRequestPkcs10
IX509CertificateRequestPkcs7
IX509SignatureInformation
 IX509CertificateRequest::get_UIContextMessage
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The UIContextMessage property specifies or retrieves a context string to display in the user interface.
This property is read/write.

Syntax
HRESULT get_UIContextMessage(
BSTR *pValue
);

Parameters
pValue

Return value
None

Remarks
You can set this property before calling any initialization method or the Encode method. For a PKCS #10 request,
the property value is retrieved from and specified on the associated IX509PrivateKey object if the key exists. For
a PKCS #7 or CMC request the property value is updated on the inner request and all signing certificates.
The context string should include additional information about an action. For example, if the user interface
instructs the user to enter a smartcard PIN, the context string can indicate that a PIN is used to verify the identity
of the user so that the request can be signed.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509CertificateRequest
IX509CertificateRequestCertificate
IX509CertificateRequestCmc
IX509CertificateRequestPkcs10
IX509CertificateRequestPkcs7
IX509SignatureInformation
 IX509CertificateRequest::GetInnerRequest method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The GetInnerRequest method retrieves a nested request object.

Syntax
HRESULT GetInnerRequest(
[in] InnerRequestLevel Level,
[out] IX509CertificateRequest **ppValue
);

Parameters
[in] Level

A value of an InnerRequestLevel enumeration that specifies the envelopment level of the data to retrieve. You
can use the LevelNext value to iterate through the nested levels or the LevelInnermost value to retrieve the most
deeply nested request object. You cannot specify LevelNext for a PKCS #10 request.
[out] ppValue

Address of a variable that receives a pointer to an IX509CertificateRequest interface that contains the nested
request. Call the Type property to determine whether the inner request object is a PKCS #10 or a CMC request.
Then call Quer yInterface to retrieve the appropriate pointer.

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. Possible values include, but are not
limited to, those in the following table. For a list of common error codes, see Common HRESULT Values.

RET URN C O DE/ VA L UE DESC RIP T IO N

You specified a value of LevelNext PKCS #10 request.

CERTSRV_E_PROPERTY_EMPTY

Remarks
A top-level request object can be a PKCS #10, PKCS #7, or CMC request. The following rules apply to inner
request objects:
A PKCS #10 request cannot contain an inner request object.
A PKCS #7 request can contain only a PKCS #10 inner request object.
A CMC request can contain a CMC or a PKCS #10 inner request object. For a CMC request that contains an
inner CMC request, there is no theoretical limit to the number of nested levels that can exist before the final
inner PKCS #10 request is reached. That is, a top-level CMC request can contain an inner CMC request that
 also contains an inner CMC request and so on.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509CertificateRequest
IX509CertificateRequestCertificate
IX509CertificateRequestCmc
IX509CertificateRequestPkcs10
IX509CertificateRequestPkcs7
IX509SignatureInformation
 IX509CertificateRequest::Initialize method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Initialize method initializes the request object for a user or a computer.

Syntax
HRESULT Initialize(
[in] X509CertificateEnrollmentContext Context
);

Parameters
[in] Context

An X509CertificateEnrollmentContext enumeration value that specifies whether the certificate is intended for an
end user, a computer, or an administrator acting on behalf of a computer. This can be one of the following values.

VA L UE M EA N IN G

The certificate is being requested for an end user.

ContextUser

The certificate is being requested for a computer.

ContextMachine

The certificate is being requested by an administrator acting

ContextAdministratorForceMachine on the behalf of a computer.

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. Possible values include, but are not
limited to, those in the following table. For a list of common error codes, see Common HRESULT Values.

RET URN C O DE DESC RIP T IO N

The object is already initialized.

HRESULT_FROM_WIN32(ERROR_ALREADY_INITIALIZE
D)

Remarks
The Initialize method initializes various objects depending on the type of certificate request being created. If
you call this method from an IX509CertificateRequestPkcs10 object, a private key object is created and the
following objects are initialized:
 An empty ICryptAttributes collection.
An empty IX509Extensions collection.
An IObjectIds collection that contains the default critical extension object identifiers, XCN_OID_KEY_USAGE
and XCN_OID_BASIC_CONSTRAINTS2. This collection can be retrieved by calling the CriticalExtensions
property.
An empty IObjectIds collection for the SuppressOids property.
An ICspInformations object that contains the values you specified in the CSPInformations property or a
collection of all providers installed on the computer. This collection is used to create a private key.
If you call this method from an IX509CertificateRequestCmc object, an inner PKCS #10 request is created as
above and the following objects are initialized:
An empty ICryptAttributes collection.
An empty IX509NameValuePairs collection.
An empty IX509Extensions collection.
An IObjectIds collection that contains the default critical extension object identifiers, XCN_OID_KEY_USAGE
and XCN_OID_BASIC_CONSTRAINTS2. This collection can be retrieved by calling the CriticalExtensions
property.
An empty IObjectIds collection for the SuppressOids property.
An empty ISignerCertificates collection.
If you call this method from an IX509CertificateRequestPkcs7 object, an inner PKCS #10 request is created as
above.
The following properties can be called before you call this method.
ParentWindow
Silent
UIContextMessage
You must call the CSPInformations property before calling this method if you want to specify an
ICspInformations collection.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509CertificateRequest
IX509CertificateRequestCertificate
IX509CertificateRequestCmc
IX509CertificateRequestPkcs10
IX509CertificateRequestPkcs7
IX509SignatureInformation
 IX509CertificateRequest::put_AlternateSignatureAlgorithm
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The AlternateSignatureAlgorithm property specifies and retrieves a Boolean value that indicates whether the
signature algorithm object identifier (OID) for a PKCS #10 request or certificate signature is discrete or
combined. A PKCS #10 object can be a stand-alone request or it can be contained in a CMC or PKCS #7 request
object.
This property is read/write.

Syntax
HRESULT put_AlternateSignatureAlgorithm(
VARIANT_BOOL Value
);

Parameters
Value

Return value
None

Remarks
Discrete algorithms are represented by separate object identifiers (OIDs) for the hashing algorithm and the
signing algorithm. Examples include the following values.

DISC RET E A L GO RIT H M O ID DESC RIP T IO N

XCN_OID_NIST_sha256 National Institute of Standards and Technologies (NIST) 256-

(2.16.840.1.101.3.4.2.1) bit SHA hashing algorithm.

XCN_OID_OIWSEC_rsaSign NIST OSE Implementer Workshop Security (OIWSEC) RSA

(1.3.14.3.2.11) signing algorithm.

Combined algorithms are represented by a single OID that identifies both the hashing and the signing
algorithm. Examples include the following values.

C O M B IN ED A L GO RIT H M O ID DESC RIP T IO N

XCN_OID_RSA_MD2RSA MD2 hashing algorithm combined with the RSA encryption

(1.2.840.113549.1.1.2) algorithm from RSA Laboratories.
 XCN_OID_OIWSEC_md5RSA OIWSEC MD5 hashing algorithm combined with the RSA
(1.3.14.3.2.3) encryption algorithm.

If the certificate request contains nested requests and you set the AlternateSignatureAlgorithm property on
the top level request, it is automatically propagated to all of the inner requests. You can, however, set the
property manually on each of the inner objects.
For a PKCS #7 or a CMC request, this property retrieves a Boolean value for the primary signature on the inner
PKCS #10 request. On input, all signer certificates are updated with the specified property value.
For a PKCS #10 request or certificate signature using the RSA public key algorithm, a property value of False
(which indicates a combined OID) implies a version 1.5 signature and True (discrete OID) implies a version 2.1
signature.
You must initialize the request object before calling this property. You can call this property before calling the
Encode method.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509CertificateRequest
IX509CertificateRequestCertificate
IX509CertificateRequestCmc
IX509CertificateRequestPkcs10
IX509CertificateRequestPkcs7
IX509SignatureInformation
 IX509CertificateRequest::put_ClientId method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The ClientId property specifies and retrieves a value that identifies the executable that created the request. For
example, a request can be generated by using a request wizard, by an auto-enrollment process, or by other
means. This property is web enabled for both input and output.
This property is read/write.

Syntax
HRESULT put_ClientId(
RequestClientInfoClientId Value
);

Parameters
Value

Return value
None

Remarks
You must initialize the request object before calling this property. You can call this property before calling the
Encode method.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509CertificateRequest
IX509CertificateRequestCertificate
IX509CertificateRequestCmc
IX509CertificateRequestPkcs10
IX509CertificateRequestPkcs7
IX509SignatureInformation
 IX509CertificateRequest::put_CspInformations
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The CspInformations property specifies and retrieves a collection of cryptographic providers available for use
by the request object.
This property is read/write.

Syntax
HRESULT put_CspInformations(
ICspInformations *pValue
);

Parameters
pValue

Return value
None

Remarks
If you want to specify a collection of providers, you must set this property before calling the Initialize method.
The collection that you specify must contain all providers currently installed on the computer. If you specify a
subset or a superset, the behavior of this property is undefined.
If you do not specify a collection, the Initialize method sets the property value to a collection of all providers
installed on the computer.
The CspInformations property exists so that the caller can avoid forcing the request object to fill the collection.
This is useful when the caller is creating multiple requests in one session.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll
See also
IX509CertificateRequest
IX509CertificateRequestCertificate
IX509CertificateRequestCmc
IX509CertificateRequestPkcs10
IX509CertificateRequestPkcs7
IX509SignatureInformation
 IX509CertificateRequest::put_HashAlgorithm
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The HashAlgorithm property specifies and retrieves the object identifier (OID) of the hash algorithm used to
sign the certificate request. This property is web enabled for both input and output.
This property is read/write.

Syntax
HRESULT put_HashAlgorithm(
IObjectId *pValue
);

Parameters
pValue

Return value
None

Remarks
If the certificate request contains nested requests and you set the HashAlgorithm property on the top level
request, it is automatically propagated to all of the inner requests, overwriting values that may have been
previously set. You can, however, set the property manually on each of the inner objects.
You must initialize the request object before calling this property. You can call this property before calling the
Encode method.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509CertificateRequest
IX509CertificateRequestCertificate
IX509CertificateRequestCmc
IX509CertificateRequestPkcs10
IX509CertificateRequestPkcs7
IX509SignatureInformation
 IX509CertificateRequest::put_ParentWindow
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The ParentWindow property specifies and retrieves the ID of the window used by key-related user interface
dialogs.
This property is read/write.

Syntax
HRESULT put_ParentWindow(
LONG Value
);

Parameters
Value

Return value
None

Remarks
This property value is used by key-related Certificate Enrollment Control modal dialogs that:
Direct a user to insert a smart card
Request a smart card pin number
Request the protection level for a new key
Request a user password before accessing a key
If your application uses key-related modal dialogs, we recommend that you use this property to ensure that
your window displays in front of other windows and that the requested action is performed before the thread
can be unblocked.
You can set this property before calling any initialization method or the Encode method. If the certificate request
contains nested requests and you set the ParentWindow property on the top level request, it is automatically
propagated to all of the inner requests. You can, however, set the property manually on each of the inner objects.
For a PKCS #10 request, the property value is retrieved from and specified on the associated IX509PrivateKey
object if the key exists. For a PKCS #7 or CMC request the window ID is updated on the inner request and all
signing certificates.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

 Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509CertificateRequest
IX509CertificateRequestCertificate
IX509CertificateRequestCmc
IX509CertificateRequestPkcs10
IX509CertificateRequestPkcs7
IX509SignatureInformation
 IX509CertificateRequest::put_RenewalCertificate
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The RenewalCer tificate property specifies or retrieves a byte array that contains the Distinguished Encoding
Rules (DER) encoded certificate that is being renewed. The DER-encoded byte array is represented by a Unicode-
encoded string.
This property is read/write.

Syntax
HRESULT put_RenewalCertificate(
EncodingType Encoding,
BSTR Value
);

Parameters
Encoding

Value

Return value
None

Remarks
The certificate is encoded by using DER as defined by the Abstract Syntax Notation One (ASN.1) standard. The
encoding process creates a byte array. The byte array is returned in a string that is either a pure binary sequence
or is Unicode encoded so that it can be displayed as text.
You must initialize the request object before calling this property. You can call this property before calling the
Encode method.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll
See also
IX509CertificateRequest
IX509CertificateRequestCertificate
IX509CertificateRequestCmc
IX509CertificateRequestPkcs10
IX509CertificateRequestPkcs7
IX509SignatureInformation
 IX509CertificateRequest::put_Silent method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Silent property specifies or retrieves a Boolean value that indicates whether any of the key-related modal
dialogs are displayed during the certificate enrollment process.
This property is read/write.

Syntax
HRESULT put_Silent(
VARIANT_BOOL Value
);

Parameters
Value

Return value
None

Remarks
This property value is used by key-related Certificate Enrollment Control modal dialogs that:
Direct a user to insert a smart card
Request a smart card pin number
Request the protection level for a new key
Request a user password before accessing a key
You can set this property before calling any initialization method or the Encode method. For a PKCS #10 request,
the property value is retrieved from and specified on the associated IX509PrivateKey object if the key exists. For
a PKCS #7 or CMC request the property value is updated on the inner request and all signing certificates.
If the certificate request contains nested requests and you set the Silent property on the top level request, it is
automatically propagated to all of the inner requests. You can, however, set the property manually on each of the
inner objects.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]
 Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509CertificateRequest
IX509CertificateRequestCertificate
IX509CertificateRequestCmc
IX509CertificateRequestPkcs10
IX509CertificateRequestPkcs7
IX509SignatureInformation
 IX509CertificateRequest::put_SuppressDefaults
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The SuppressDefaults property specifies or retrieves a Boolean value that indicates whether the default
extensions and attributes are included in the request. The defaults are represented by their object identifiers
(OIDs).
This property is read/write.

Syntax
HRESULT put_SuppressDefaults(
VARIANT_BOOL Value
);

Parameters
Value

Return value
None

Remarks
You must initialize the request object before calling this property. Set this property before calling the Encode
method to suppress inclusion and encoding of default extensions and attributes in the certificate request.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509CertificateRequest
IX509CertificateRequestCertificate
IX509CertificateRequestCmc
IX509CertificateRequestPkcs10
IX509CertificateRequestPkcs7
IX509SignatureInformation
 IX509CertificateRequest::put_UIContextMessage
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The UIContextMessage property specifies or retrieves a context string to display in the user interface.
This property is read/write.

Syntax
HRESULT put_UIContextMessage(
BSTR Value
);

Parameters
Value

Return value
None

Remarks
You can set this property before calling any initialization method or the Encode method. For a PKCS #10 request,
the property value is retrieved from and specified on the associated IX509PrivateKey object if the key exists. For
a PKCS #7 or CMC request the property value is updated on the inner request and all signing certificates.
The context string should include additional information about an action. For example, if the user interface
instructs the user to enter a smartcard PIN, the context string can indicate that a PIN is used to verify the identity
of the user so that the request can be signed.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509CertificateRequest
IX509CertificateRequestCertificate
IX509CertificateRequestCmc
IX509CertificateRequestPkcs10
IX509CertificateRequestPkcs7
IX509SignatureInformation
 IX509CertificateRequest::ResetForEncode method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The ResetForEncode method restores the state of the request object to that which existed before the Encode
method was called.

Syntax
HRESULT ResetForEncode();

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. Possible values include, but are not
limited to, those in the following table. For a list of common error codes, see Common HRESULT Values.

RET URN C O DE/ VA L UE DESC RIP T IO N

Certificate extensions and attributes have not been defined.

CERTSRV_E_PROPERTY_EMPTY

The request object is not encoded.

HRESULT_FROM_WIN32(ERROR_INVALID_STATE)

The object is not initialized.

OLE_E_BL ANK

Remarks
You can use this method to reconfigure (re-encode and re-sign) a certificate request in response to rejection of
the request by a certification authority. The signature and the raw data are cleared. The extensions and attributes
are reset to the values they had before the Encode method was called, but critical extension flags are not. For a
CMC request object, each nested request is also reset.
This method is typically used for a CMC key archival request when the private key is encrypted and included in
the request.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]
 Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509CertificateRequest
IX509CertificateRequestCertificate
IX509CertificateRequestCmc
IX509CertificateRequestPkcs10
IX509CertificateRequestPkcs7
IX509SignatureInformation
 IX509CertificateRequestCertificate interface
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The IX509Cer tificateRequestCer tificate interface represents a request object for a self-generated certificate,
enabling you to create a certificate directly without going through a registration or certification authority. The
following illustration shows the inheritance structure for this object.

Inheritance
The IX509Cer tificateRequestCer tificate interface inherits from IX509CertificateRequestPkcs10.
IX509Cer tificateRequestCer tificate also has these types of members:

Methods
The IX509Cer tificateRequestCer tificate interface has these methods.

IX509CertificateRequestCertificate::CheckPublicKeySignature

Verifies the certificate signature by using the public key of the signing certificate.

IX509CertificateRequestCertificate::get_Issuer

Specifies or retrieves the name of the certificate issuer.

IX509CertificateRequestCertificate::get_NotAfter

Specifies or retrieves the date and time after which the certificate is no longer valid.

IX509CertificateRequestCertificate::get_NotBefore

Specifies or retrieves the date and time before which the certificate is not valid.

IX509CertificateRequestCertificate::get_SerialNumber

Specifies and retrieves the certificate serial number.

IX509CertificateRequestCertificate::get_SignerCertificate

Specifies or retrieves the ISignerCertificate object used to sign the certificate.

 IX509CertificateRequestCertificate::put_Issuer

Specifies or retrieves the name of the certificate issuer.

IX509CertificateRequestCertificate::put_NotAfter

Specifies or retrieves the date and time after which the certificate is no longer valid.

IX509CertificateRequestCertificate::put_NotBefore

Specifies or retrieves the date and time before which the certificate is not valid.

IX509CertificateRequestCertificate::put_SerialNumber

Specifies and retrieves the certificate serial number.

IX509CertificateRequestCertificate::put_SignerCertificate

Specifies or retrieves the ISignerCertificate object used to sign the certificate.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

See also
CertEnroll Interfaces
IX509CertificateRequest
IX509CertificateRequestPkcs10
 IX509CertificateRequestCertificate::CheckPublicKeySignature
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The CheckPublicKeySignature method verifies the certificate signature by using the public key of the signing
certificate.

Syntax
HRESULT CheckPublicKeySignature(
[in] IX509PublicKey *pPublicKey
);

Parameters
[in] pPublicKey

Pointer to an IX509PublicKey interface that represents the public key.

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. Possible values include, but are not
limited to, those in the following table. For a list of common error codes, see Common HRESULT Values.

RET URN C O DE/ VA L UE DESC RIP T IO N

The signature cannot be found.

CRYPT_E_NO_SIGNER

The IX509PublicKey object has not been initialized.

HRESULT_FROM_WIN32(ERROR_INVALID_STATE)

The request object has not been initialized.

OLE_E_BL ANK

Remarks
This method decrypts the signature and compares it to a hash of the certificate, using the hash algorithm
specified by the signature. You must initialize the request object before calling this property. For more
information, see any of the following methods:
Initialize
InitializeDecode
InitializeFromCertificate
InitializeFromPrivateKey
InitializeFromPublicKey
InitializeFromTemplateName

Requirements
 Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509CertificateRequestCertificate
 IX509CertificateRequestCertificate::get_Issuer
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Issuer property specifies or retrieves the name of the certificate issuer.
This property is read/write.

Syntax
HRESULT get_Issuer(
IX500DistinguishedName **ppValue
);

Parameters
ppValue

Return value
None

Remarks
If you do not specify this property before calling Encode, the property value is set by using the subject of the
signing certificate. If no signing certificate was supplied, the property value is set by using the subject of the
request object.
You must initialize the request object before calling this property. For more information, see any of the following
methods:
Initialize
InitializeDecode
InitializeFromCertificate
InitializeFromPrivateKey
InitializeFromPublicKey
InitializeFromTemplateName

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

 Header certenroll.h

DLL CertEnroll.dll

See also
IX500DistinguishedName
IX509CertificateRequestCertificate
 IX509CertificateRequestCertificate::get_NotAfter
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The NotAfter property specifies or retrieves the date and time after which the certificate is no longer valid.
This property is read/write.

Syntax
HRESULT get_NotAfter(
DATE *pValue
);

Parameters
pValue

Return value
None

Remarks
The expiration date is stored as an 8-byte real value that represents a Coordinated Universal Time (Greenwich
Mean Time) value between January 1, 1900 and December 31, 9999, inclusive. The value 2.0 represents January
1, 1900; 3.0 represents January 2, 1900. Adding 1 to the value increments the date by a day. The fractional part
of the value represents the time of day. Therefore, 2.5 represents 12:00 on January 1, 1900; 3.25 represents
06:00 on January 2, 1900.
For dates between 1950 and 2049 inclusive, the date and time is encoded Coordinated Universal Time in the
form YYMMDDHHMMSS. For dates before 1950 or after 2049, encoded generalized time is used. Encoded
generalized time is in the form YYYYMMDDHHMMSSMMM, using a four digit year, and is precise to
milliseconds. The NotAfter time is, however, only precise to seconds.
After calling Encode, the default value equals the NotBefore property value plus one year plus ten minutes to
compensate for clock skew. Typically, this value is adjusted by time zone and daylight saving time, if applicable,
before it is displayed.
You must initialize the request object before calling this property. For more information, see any of the following
methods:
Initialize
InitializeDecode
InitializeFromCertificate
InitializeFromPrivateKey
InitializeFromPublicKey
InitializeFromTemplateName
Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509CertificateRequestCertificate
 IX509CertificateRequestCertificate::get_NotBefore
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The NotBefore property specifies or retrieves the date and time before which the certificate is not valid.
This property is read/write.

Syntax
HRESULT get_NotBefore(
DATE *pValue
);

Parameters
pValue

Return value
None

Remarks
The expiration date is stored as an 8-byte real value that represents a Coordinated Universal Time (Greenwich
Mean Time) value between January 1, 1900 and December 31, 9999, inclusive. The value 2.0 represents January
1, 1900; 3.0 represents January 2, 1900. Adding 1 to the value increments the date by a day. The fractional part
of the value represents the time of day. Therefore, 2.5 represents 12:00 on January 1, 1900; 3.25 represents
06:00 on January 2, 1900.
For dates between 1950 and 2049 inclusive, the date and time is encoded Coordinated Universal Time in the
form YYMMDDHHMMSS. For dates before 1950 or after 2049, encoded generalized time is used. Encoded
generalized time is in the form YYYYMMDDHHMMSSMMM, using a four digit year, and is precise to
milliseconds. The NotBefore time is, however, only precise to seconds.
After calling Encode, the default value equals the current time plus one year minus ten minutes to compensate
for clock skew. Typically, this value is adjusted by time zone and daylight saving time, if applicable, before it is
displayed.
You must initialize the request object before calling this property. For more information, see any of the following
methods:
Initialize
InitializeDecode
InitializeFromCertificate
InitializeFromPrivateKey
InitializeFromPublicKey
InitializeFromTemplateName
Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509CertificateRequestCertificate
 IX509CertificateRequestCertificate::get_SerialNumber
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The SerialNumber property specifies and retrieves the certificate serial number. The serial number is contained
in a byte array encoded by using Distinguished Encoding Rules (DER) as defined by the Abstract Syntax Notation
One (ASN.1) standard. The DER-encoded byte array is represented by a string that is either a pure binary
sequence or is Unicode encoded.
This property is read/write.

Syntax
HRESULT get_SerialNumber(
EncodingType Encoding,
BSTR *pValue
);

Parameters
Encoding

pValue

Return value
None

Remarks
After calling Encode, the default value is a GUID with a high-order nibble that is not zero (to ensure that the
hexadecimal representation of the serial number has an even number of digits). The high-order nibble is in the
range 1 to 7. You must initialize the request object before calling this property. For more information, see any of
the following methods:
Initialize
InitializeDecode
InitializeFromCertificate
InitializeFromPrivateKey
InitializeFromPublicKey
InitializeFromTemplateName

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

 Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509CertificateRequestCertificate
 IX509CertificateRequestCertificate::get_SignerCertificate
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The SignerCer tificate property specifies or retrieves the ISignerCertificate object used to sign the certificate.
This property is read/write.

Syntax
HRESULT get_SignerCertificate(
ISignerCertificate **ppValue
);

Parameters
ppValue

Return value
None

Remarks
You can set this property if you are not creating a self-signed certificate. If you do not specify the property value
before calling Encode, the private key associated with the IX509CertificateRequestCertificate object is used to
sign the certificate, and the name of the issuer is set, by default, to the subject name.
You must initialize the request object before calling this property. For more information, see any of the following
methods:
Initialize
InitializeDecode
InitializeFromCertificate
InitializeFromPrivateKey
InitializeFromPublicKey
InitializeFromTemplateName

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

 Header certenroll.h

DLL CertEnroll.dll

See also
ISignerCertificate
IX509CertificateRequestCertificate
 IX509CertificateRequestCertificate::put_Issuer
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Issuer property specifies or retrieves the name of the certificate issuer.
This property is read/write.

Syntax
HRESULT put_Issuer(
IX500DistinguishedName *pValue
);

Parameters
pValue

Return value
None

Remarks
If you do not specify this property before calling Encode, the property value is set by using the subject of the
signing certificate. If no signing certificate was supplied, the property value is set by using the subject of the
request object.
You must initialize the request object before calling this property. For more information, see any of the following
methods:
Initialize
InitializeDecode
InitializeFromCertificate
InitializeFromPrivateKey
InitializeFromPublicKey
InitializeFromTemplateName

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

 Header certenroll.h

DLL CertEnroll.dll

See also
IX500DistinguishedName
IX509CertificateRequestCertificate
 IX509CertificateRequestCertificate::put_NotAfter
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The NotAfter property specifies or retrieves the date and time after which the certificate is no longer valid.
This property is read/write.

Syntax
HRESULT put_NotAfter(
DATE Value
);

Parameters
Value

Return value
None

Remarks
The expiration date is stored as an 8-byte real value that represents a Coordinated Universal Time (Greenwich
Mean Time) value between January 1, 1900 and December 31, 9999, inclusive. The value 2.0 represents January
1, 1900; 3.0 represents January 2, 1900. Adding 1 to the value increments the date by a day. The fractional part
of the value represents the time of day. Therefore, 2.5 represents 12:00 on January 1, 1900; 3.25 represents
06:00 on January 2, 1900.
For dates between 1950 and 2049 inclusive, the date and time is encoded Coordinated Universal Time in the
form YYMMDDHHMMSS. For dates before 1950 or after 2049, encoded generalized time is used. Encoded
generalized time is in the form YYYYMMDDHHMMSSMMM, using a four digit year, and is precise to
milliseconds. The NotAfter time is, however, only precise to seconds.
After calling Encode, the default value equals the NotBefore property value plus one year plus ten minutes to
compensate for clock skew. Typically, this value is adjusted by time zone and daylight saving time, if applicable,
before it is displayed.
You must initialize the request object before calling this property. For more information, see any of the following
methods:
Initialize
InitializeDecode
InitializeFromCertificate
InitializeFromPrivateKey
InitializeFromPublicKey
InitializeFromTemplateName
Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509CertificateRequestCertificate
 IX509CertificateRequestCertificate::put_NotBefore
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The NotBefore property specifies or retrieves the date and time before which the certificate is not valid.
This property is read/write.

Syntax
HRESULT put_NotBefore(
DATE Value
);

Parameters
Value

Return value
None

Remarks
The expiration date is stored as an 8-byte real value that represents a Coordinated Universal Time (Greenwich
Mean Time) value between January 1, 1900 and December 31, 9999, inclusive. The value 2.0 represents January
1, 1900; 3.0 represents January 2, 1900. Adding 1 to the value increments the date by a day. The fractional part
of the value represents the time of day. Therefore, 2.5 represents 12:00 on January 1, 1900; 3.25 represents
06:00 on January 2, 1900.
For dates between 1950 and 2049 inclusive, the date and time is encoded Coordinated Universal Time in the
form YYMMDDHHMMSS. For dates before 1950 or after 2049, encoded generalized time is used. Encoded
generalized time is in the form YYYYMMDDHHMMSSMMM, using a four digit year, and is precise to
milliseconds. The NotBefore time is, however, only precise to seconds.
After calling Encode, the default value equals the current time plus one year minus ten minutes to compensate
for clock skew. Typically, this value is adjusted by time zone and daylight saving time, if applicable, before it is
displayed.
You must initialize the request object before calling this property. For more information, see any of the following
methods:
Initialize
InitializeDecode
InitializeFromCertificate
InitializeFromPrivateKey
InitializeFromPublicKey
InitializeFromTemplateName
Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509CertificateRequestCertificate
 IX509CertificateRequestCertificate::put_SerialNumber
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The SerialNumber property specifies and retrieves the certificate serial number. The serial number is contained
in a byte array encoded by using Distinguished Encoding Rules (DER) as defined by the Abstract Syntax Notation
One (ASN.1) standard. The DER-encoded byte array is represented by a string that is either a pure binary
sequence or is Unicode encoded.
This property is read/write.

Syntax
HRESULT put_SerialNumber(
EncodingType Encoding,
BSTR Value
);

Parameters
Encoding

Value

Return value
None

Remarks
After calling Encode, the default value is a GUID with a high-order nibble that is not zero (to ensure that the
hexadecimal representation of the serial number has an even number of digits). The high-order nibble is in the
range 1 to 7. You must initialize the request object before calling this property. For more information, see any of
the following methods:
Initialize
InitializeDecode
InitializeFromCertificate
InitializeFromPrivateKey
InitializeFromPublicKey
InitializeFromTemplateName

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

 Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509CertificateRequestCertificate
 IX509CertificateRequestCertificate::put_SignerCertificate
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The SignerCer tificate property specifies or retrieves the ISignerCertificate object used to sign the certificate.
This property is read/write.

Syntax
HRESULT put_SignerCertificate(
ISignerCertificate *pValue
);

Parameters
pValue

Return value
None

Remarks
You can set this property if you are not creating a self-signed certificate. If you do not specify the property value
before calling Encode, the private key associated with the IX509CertificateRequestCertificate object is used to
sign the certificate, and the name of the issuer is set, by default, to the subject name.
You must initialize the request object before calling this property. For more information, see any of the following
methods:
Initialize
InitializeDecode
InitializeFromCertificate
InitializeFromPrivateKey
InitializeFromPublicKey
InitializeFromTemplateName

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

 Header certenroll.h

DLL CertEnroll.dll

See also
ISignerCertificate
IX509CertificateRequestCertificate
 IX509CertificateRequestCertificate2 interface
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The IX509Cer tificateRequestCer tificate2 interface represents a request object for a self-generated
certificate, enabling you to create a certificate directly without going through a registration or certification
authority. It includes all of the methods defined by the IX509CertificateRequestCertificate interface and adds
methods that enable initialization from certificate request templates.

Inheritance
The IX509Cer tificateRequestCer tificate2 interface inherits from IX509CertificateRequestCertificate.
IX509Cer tificateRequestCer tificate2 also has these types of members:

Methods
The IX509Cer tificateRequestCer tificate2 interface has these methods.

IX509CertificateRequestCertificate2::get_PolicyServer

Retrieves the certificate enrollment policy (CEP) server that contains the template used during initialization.

IX509CertificateRequestCertificate2::get_Template

Retrieves the certificate request template used during initialization.

IX509CertificateRequestCertificate2::InitializeFromPrivateKeyTemplate

Initializes the certificate request by using an IX509PrivateKey object and a certificate template.

IX509CertificateRequestCertificate2::InitializeFromTemplate

Initializes the certificate request by using a template.

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Target Platform Windows

Header certenroll.h

See also
IX509CertificateRequestCertificate
IX509CertificateRequestPkcs10
 IX509CertificateRequestCertificate2::get_PolicyServer
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The PolicySer ver property retrieves the certificate enrollment policy (CEP) server that contains the template
used during initialization.
This property is read-only.

Syntax
HRESULT get_PolicyServer(
IX509EnrollmentPolicyServer **ppPolicyServer
);

Parameters
ppPolicyServer

Return value
None

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Target Platform Windows

Header certenroll.h

See also
IX509CertificateRequestCertificate2
 IX509CertificateRequestCertificate2::get_Template
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Template property retrieves the certificate request template used during initialization.
This property is read-only.

Syntax
HRESULT get_Template(
IX509CertificateTemplate **ppTemplate
);

Parameters
ppTemplate

Return value
None

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Target Platform Windows

Header certenroll.h

See also
IX509CertificateRequestCertificate2
 IX509CertificateRequestCertificate2::InitializeFromPrivateKeyTemplate
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The InitializeFromPrivateKeyTemplate method initializes the certificate request by using an IX509PrivateKey

object and a certificate template.

Syntax
HRESULT InitializeFromPrivateKeyTemplate(
[in] X509CertificateEnrollmentContext Context,
[in] IX509PrivateKey *pPrivateKey,
[in] IX509EnrollmentPolicyServer *pPolicyServer,
[in] IX509CertificateTemplate *pTemplate
);

Parameters
[in] Context

An X509CertificateEnrollmentContext enumeration value that specifies whether the requested certificate is

intended for an end user, a computer, or an administrator acting on behalf of the computer. This can be one of
the following values. However, if the MachineContext property of the private key is set, you must specify the
ContextMachine enumeration value.

VA L UE M EA N IN G

The certificate is being requested for an end user.

ContextUser

The certificate is being requested for a computer.

ContextMachine

The certificate is being requested by an administrator acting

ContextAdministratorForceMachine on the behalf of a computer.

[in] pPrivateKey

Pointer to an IX509PrivateKey interface that represents the private key.

[in] pPolicyServer

Pointer to an IX509EnrollmentPolicyServer object that represents the certificate enrollment policy (CEP) server
that contains the template specified by the pTemplate parameter.
[in] pTemplate

Pointer to an IX509CertificateTemplate object that represents the template to use during initialization.

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. Possible values include, but are not
limited to, those in the following table. For a list of common error codes, see Common HRESULT Values.

RET URN C O DE DESC RIP T IO N

The pPrivateKey, pPolicyServer, or pTemplate parameters are

E_POINTER NULL .
 The certificate request object has already been initialized.
HRESULT_FROM_WIN32(ERROR_ALREADY_INITIALIZE
D)

Remarks
The InitializeFromPrivateKeyTemplate method performs the following actions:
Adds the extensions specified by the template to an IX509Extensions collection.
Creates an IObjectIds collection and populates it with the default XCN_OID_KEY_USAGE and
XCN_OID_BASIC_CONSTRAINTS2 object identifiers. If the template indicates that these OIDs are not critical,
they are removed from the collection. The OIDs marked critical by the template are added.
Sets the SmimeCapabilities property if the template supports symmetric algorithms.
Sets the AlternateSignatureAlgorithm property if the template requires a discrete signature algorithm OID.
Creates an IX509SignatureInformation object.
Creates a hash algorithm OID if the algorithm is specified in the template and sets it on the
IX509SignatureInformation object.
Retrieves an asymmetric encryption algorithm OID, if it exists, from the template and sets it on the
IX509SignatureInformation object.
Populates many of the IX509PrivateKey properties from the template settings.
If the CSPInformations property is not specified, the method creates an ICspInformations collection from the
providers installed on the computer.
No private key is created at this point. If the IX509PrivateKey object passed to the method does not represent an
existing key, a key is created when the Encode method is called. The key will be created by using the default
provider if no template was specified and the ProviderName property on the IX509PrivateKey is not set. When
a private key exists, it is set on the PrivateKey property.

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Target Platform Windows

Header certenroll.h

See also
IX509CertificateRequestCertificate2
 IX509CertificateRequestCertificate2::InitializeFromTemplate
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The InitializeFromTemplate method initializes the certificate request by using a template.

Syntax
HRESULT InitializeFromTemplate(
[in] X509CertificateEnrollmentContext context,
[in] IX509EnrollmentPolicyServer *pPolicyServer,
[in] IX509CertificateTemplate *pTemplate
);

Parameters
[in] context

An X509CertificateEnrollmentContext enumeration value that specifies whether the requested certificate is

intended for an end user, a computer, or administrator acting on behalf of the computer. This can be one of the
following values.

VA L UE M EA N IN G

The certificate is being requested for an end user.

ContextUser

The certificate is being requested for a computer.

ContextMachine

The certificate is being requested by an administrator acting

ContextAdministratorForceMachine on the behalf of a computer.

[in] pPolicyServer

Pointer to an IX509EnrollmentPolicyServer object that represents the certificate enrollment policy (CEP) server
that contains the template specified by the pTemplate parameter.
[in] pTemplate

Pointer to an IX509CertificateTemplate object that represents the template to use during initialization.

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. Possible values include, but are not
limited to, those in the following table. For a list of common error codes, see Common HRESULT Values.

RET URN C O DE DESC RIP T IO N

 The pTemplate parameters cannot be NULL .
E_POINTER

The certificate request object has already been initialized.

HRESULT_FROM_WIN32(ERROR_ALREADY_INITIALIZE
D)

Remarks
The InitializeFromTemplate method creates the following collections:
An ICryptAttributes collection.
An IX509Extensions collection.
An IObjectIds collection populated with the default XCN_OID_KEY_USAGE and
XCN_OID_BASIC_CONSTRAINTS2 object identifiers.
An empty IObjectIds collection for attribute and extension OIDs to be suppressed from the new request.
The method then examines the template and performs the following actions:
Adds the extensions specified by the template to the IX509Extensions collection.
Removes the default critical extensions (XCN_OID_KEY_USAGE and XCN_OID_BASIC_CONSTRAINTS2) from
the collection if the template indicates that they are not critical. The OIDs marked critical by the template are
added.
Sets the SmimeCapabilities property if the template supports symmetric algorithms.
Sets the AlternateSignatureAlgorithm property if the template requires a discrete signature algorithm OID.
Creates an IX509SignatureInformation object.
Creates a hash algorithm OID if the algorithm is specified in the template and sets it on the
IX509SignatureInformation object.
Creates an asymmetric encryption algorithm OID if the algorithm is specified in the template and sets it on
the IX509SignatureInformation object.
Populates many of the IX509PrivateKey properties from the template settings.
If the CSPInformations property is NULL , the method creates an ICspInformations collection from the providers
installed on the computer.

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Target Platform Windows

Header certenroll.h

See also
IX509CertificateRequestCertificate2
 IX509CertificateRequestCmc interface (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The IX509Cer tificateRequestCmc interface represents a CMC (Certificate Management Message over CMS)
certificate request. A CMC request is always wrapped by a PKCS #7 certificate message syntax (CMS) object.
Therefore, the IX509Cer tificateRequestCmc interface inherits from the IX509CertificateRequestPkcs7
interface.
A CMC request contains sequences of TaggedAttribute , TaggedRequest , and TaggedContentInfo ASN.1
structures. The TaggedOtherMsg structure identified in the RFC is not supported.

CmcData ::= SEQUENCE

{
controlSequence ControlSequence,
reqSequence ReqSequence,
cmsSequence CmsSequence,
otherMsgSequence OtherMsgSequence
}

ControlSequence ::= SEQUENCE OF TaggedAttribute

ReqSequence ::= SEQUENCE OF TaggedRequest
CmsSequence ::= SEQUENCE OF TaggedContentInfo
OtherMsgSequence ::= SEQUENCE OF TaggedOtherMsg

TaggedAttribute ::= SEQUENCE

{
bodyPartID BodyPartID,
type EncodedObjectID,
values AttributeSetValue
}

TaggedRequest ::= CHOICE

{
tcr [0] IMPLICIT TaggedCertificationRequest
}

TaggedContentInfo ::= SEQUENCE

{
bodyPartID BodyPartID,
contentInfo ANY
}

BodyPartID ::= INTEGER (0..4294967295)

EncodedObjectID ::= OBJECT IDENTIFIER
AttributeSetValue ::= SET OF ANY

A CMC request can contain a PKCS #10 request in the TaggedRequest sequence or another CMC request
object in the TaggedContentInfo sequence. There is no theoretical limit to the possible number of nesting
levels, but certification authorities typically place a physical limit on the request size.
The TaggedAttribute sequence contains extensions and optional attributes. For more information, see CMC
Extensions and CMC Attributes.

Inheritance
The IX509Cer tificateRequestCmc interface inherits from IX509CertificateRequestPkcs7.
IX509Cer tificateRequestCmc also has these types of members:

Methods
The IX509Cer tificateRequestCmc interface has these methods.

IX509CertificateRequestCmc::get_ArchivePrivateKey

Specifies or retrieves a Boolean value that indicates whether to archive a private key on the certification authority (CA).

IX509CertificateRequestCmc::get_CriticalExtensions

Retrieves an IObjectIds collection that identifies the version 3 certificate extensions marked as critical.

IX509CertificateRequestCmc::get_CryptAttributes

Retrieves an ICryptAttributes collection of optional certificate attributes.

IX509CertificateRequestCmc::get_EncryptedKeyHash

Retrieves a hash of the private key to be archived.

IX509CertificateRequestCmc::get_EncryptionAlgorithm

Specifies or retrieves an object identifier (OID) of the algorithm used to encrypt the private key to be archived.

IX509CertificateRequestCmc::get_EncryptionStrength

Specifies or retrieves the relative encryption level applied to the private key to be archived.

IX509CertificateRequestCmc::get_KeyArchivalCertificate

Specifies or retrieves a certification authority (CA) encryption certificate.

IX509CertificateRequestCmc::get_NameValuePairs

Retrieves an IX509NameValuePairs collection associated with a certificate request.

IX509CertificateRequestCmc::get_NullSigned

Retrieves a Boolean value that specifies whether the primary signature on the certificate request is null-signed.

IX509CertificateRequestCmc::get_SenderNonce

Specifies or retrieves a byte array that contains a nonce.

IX509CertificateRequestCmc::get_SignatureInformation

Retrieves the IX509SignatureInformation object that contains information about the primary signature used to sign the
certificate request.

IX509CertificateRequestCmc::get_SignerCertificates

Retrieves a collection of certificates used to sign the request.

 IX509CertificateRequestCmc::get_SuppressOids

Retrieves a collection of extension or attribute object identifiers (OIDs) to be suppressed from the certificate during the
encoding process.

IX509CertificateRequestCmc::get_TemplateObjectId

Retrieves the object identifier (OID) of the template used to create the certificate request.

IX509CertificateRequestCmc::get_TransactionId

Specifies or retrieves a transaction identifier that can be used to track a certificate request or response.

IX509CertificateRequestCmc::get_X509Extensions

Retrieves a collection of the extensions included in the certificate request.

IX509CertificateRequestCmc::InitializeFromInnerRequestTemplateName

The InitializeFromInnerRequestTemplateName method initializes the certificate request from an inner request object and a
template.

IX509CertificateRequestCmc::put_ArchivePrivateKey

Specifies or retrieves a Boolean value that indicates whether to archive a private key on the certification authority (CA).

IX509CertificateRequestCmc::put_EncryptionAlgorithm

Specifies or retrieves an object identifier (OID) of the algorithm used to encrypt the private key to be archived.

IX509CertificateRequestCmc::put_EncryptionStrength

Specifies or retrieves the relative encryption level applied to the private key to be archived.

IX509CertificateRequestCmc::put_KeyArchivalCertificate

Specifies or retrieves a certification authority (CA) encryption certificate.

IX509CertificateRequestCmc::put_SenderNonce

Specifies or retrieves a byte array that contains a nonce.

IX509CertificateRequestCmc::put_TransactionId

Specifies or retrieves a transaction identifier that can be used to track a certificate request or response.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]
 Target Platform Windows

Header certenroll.h

See also
CertEnroll Interfaces
IX509CertificateRequest
IX509CertificateRequestPkcs7
 IX509CertificateRequestCmc::get_ArchivePrivateKey
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The ArchivePrivateKey property specifies or retrieves a Boolean value that indicates whether to archive a
private key on the certification authority (CA).
This property is read/write.

Syntax
HRESULT get_ArchivePrivateKey(
VARIANT_BOOL *pValue
);

Parameters
pValue

Return value
None

Remarks
To request that a CA archive your private key, you must also set the KeyArchivalCertificate property with the CA
encryption (key exchange) certificate.
You can set this property before calling the Encode method, but you must initialize the CMC request object
before setting the property value. For more information, see the following topics:
Initialize
InitializeDecode
InitializeFromCertificate
InitializeFromInnerRequest
InitializeFromInnerRequestTemplateName
InitializeFromTemplateName

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

 Header certenroll.h

DLL CertEnroll.dll

See also
IX509CertificateRequestCmc
 IX509CertificateRequestCmc::get_CriticalExtensions
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The CriticalExtensions property retrieves an IObjectIds collection that identifies the version 3 certificate
extensions marked as critical.
This property is read-only.

Syntax
HRESULT get_CriticalExtensions(
IObjectIds **ppValue
);

Parameters
ppValue

Return value
None

Remarks
The extension criticality indicates to an application that uses certificates whether it can ignore the extension. You
must initialize the CMC request object before calling this property. For more information, see the following
topics:
Initialize
InitializeDecode
InitializeFromCertificate
InitializeFromInnerRequest
InitializeFromInnerRequestTemplateName
InitializeFromTemplateName

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h
 DLL CertEnroll.dll

See also
IX509CertificateRequestCmc
 IX509CertificateRequestCmc::get_CryptAttributes
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Cr yptAttributes property retrieves an ICryptAttributes collection of optional certificate attributes.

This property is read-only.

Syntax
HRESULT get_CryptAttributes(
ICryptAttributes **ppValue
);

Parameters
ppValue

Return value
None

Remarks
You must initialize the CMC request object before calling this property. For more information, see the following
topics:
Initialize
InitializeDecode
InitializeFromCertificate
InitializeFromInnerRequest
InitializeFromInnerRequestTemplateName
InitializeFromTemplateName

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll
See also
IX509CertificateRequestCmc
 IX509CertificateRequestCmc::get_EncryptedKeyHash
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Encr yptedKeyHash property retrieves a hash of the private key to be archived. The hash is contained in an
encoded byte array.
This property is read-only.

Syntax
HRESULT get_EncryptedKeyHash(
EncodingType Encoding,
BSTR *pValue
);

Parameters
Encoding

pValue

Return value
None

Remarks
For more information about archiving private keys, see the ArchivePrivateKey and KeyArchivalCertificate
properties.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509CertificateRequestCmc
 IX509CertificateRequestCmc::get_EncryptionAlgorithm
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Encr yptionAlgorithm property specifies or retrieves an object identifier (OID) of the algorithm used to
encrypt the private key to be archived. This property is web enabled for both input and output.
This property is read/write.

Syntax
HRESULT get_EncryptionAlgorithm(
IObjectId **ppValue
);

Parameters
ppValue

Return value
None

Remarks
When you request that a certification authority (CA) archive your private key, you must retrieve an exchange
certificate from the CA and use the public key contained in that certificate to encrypt the private key that you are
submitting for archival. The Encr yptionAlgorithm property identifies the algorithm used to encrypt your key.
This property is related to the following properties:
ArchivePrivateKey
EncryptedKeyHash
EncryptionStrength
KeyArchivalCertificate
You must set this property, if at all, before calling the Encode method, but you must initialize the CMC request
object before calling the property. For more information, see the following topics:
Initialize
InitializeDecode
InitializeFromCertificate
InitializeFromInnerRequest
InitializeFromInnerRequestTemplateName
InitializeFromTemplateName

Requirements
 Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509CertificateRequestCmc
 IX509CertificateRequestCmc::get_EncryptionStrength
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Encr yptionStrength property specifies or retrieves the relative encryption level applied to the private key
to be archived.
This property is read/write.

Syntax
HRESULT get_EncryptionStrength(
LONG *pValue
);

Parameters
pValue

Return value
None

Remarks
This property is related to the following properties:
ArchivePrivateKey
EncryptedKeyHash
EncryptionAlgorithm
KeyArchivalCertificate
The encryption strength is often implied by the encryption algorithm. If the algorithm does not support multiple
strengths, you should not set the Encr yptionStrength property.
You must set this property, if at all, before calling the Encode method, but you must initialize the CMC request
object before calling the property. For more information, see the following topics:
Initialize
InitializeDecode
InitializeFromCertificate
InitializeFromInnerRequest
InitializeFromInnerRequestTemplateName
InitializeFromTemplateName

Requirements
 Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509CertificateRequestCmc
 IX509CertificateRequestCmc::get_KeyArchivalCertificate
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The KeyArchivalCer tificate property specifies or retrieves a certification authority (CA) encryption certificate.
The certificate is contained in a byte array that is encoded by using Distinguished Encoding Rules (DER) as
defined by the Abstract Syntax Notation One (ASN.1) standard. The DER-encoded byte array is represented by a
string that is either a pure binary sequence or is Unicode encoded. This property is web enabled for both input
and output.
This property is read/write.

Syntax
HRESULT get_KeyArchivalCertificate(
EncodingType Encoding,
BSTR *pValue
);

Parameters
Encoding

pValue

Return value
None

Remarks
If correctly configured, a certification authority (CA) can archive a client's private key. Typically, the client
requests an exchange certificate from the CA, validates it, and uses it as input to the KeyArchivalCer tificate
property. The CA's public key is used to encrypt the private key that is being submitted for archiving. You can
use the ArchivePrivateKey property to request key archival.
You must set this property, if at all, before calling the Encode method, but you must initialize the CMC request
object before calling the property. For more information, see the following topics:
Initialize
InitializeDecode
InitializeFromCertificate
InitializeFromInnerRequest
InitializeFromInnerRequestTemplateName
InitializeFromTemplateName

Requirements
 Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509CertificateRequestCmc
 IX509CertificateRequestCmc::get_NameValuePairs
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The NameValuePairs property retrieves an IX509NameValuePairs collection associated with a certificate

request.
This property is read-only.

Syntax
HRESULT get_NameValuePairs(
IX509NameValuePairs **ppValue
);

Parameters
ppValue

Return value
None

Remarks
For an example of a name-value pair in a CMC request object, see IX509NameValuePair. You must initialize the
CMC request object before calling this property. For more information, see the following topics:
Initialize
InitializeDecode
InitializeFromCertificate
InitializeFromInnerRequest
InitializeFromInnerRequestTemplateName
InitializeFromTemplateName

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h
 DLL CertEnroll.dll

See also
IX509CertificateRequestCmc
 IX509CertificateRequestCmc::get_NullSigned
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The NullSigned property retrieves a Boolean value that specifies whether the primary signature on the
certificate request is null-signed.
This property is read-only.

Syntax
HRESULT get_NullSigned(
VARIANT_BOOL *pValue
);

Parameters
pValue

Return value
None

Remarks
A null-signed certificate request is not really signed. That is, the request can be digested by using a digest
algorithm such as SHA-1, but it is not encrypted with a public key algorithm such as RSA. This can be used when
a private key is not available as is often the case when certification authorities are being cross-certified.
You must initialize the CMC request object before calling this property. For more information, see the following
topics:
Initialize
InitializeDecode
InitializeFromCertificate
InitializeFromInnerRequest
InitializeFromInnerRequestTemplateName
InitializeFromTemplateName

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

 Header certenroll.h

DLL CertEnroll.dll

See also
IX509CertificateRequestCmc
 IX509CertificateRequestCmc::get_SenderNonce
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The SenderNonce property specifies or retrieves a byte array that contains a nonce. The byte array is
represented by a string that is either a pure binary sequence or is Unicode encoded.
This property is read/write.

Syntax
HRESULT get_SenderNonce(
EncodingType Encoding,
BSTR *pValue
);

Parameters
Encoding

pValue

Return value
None

Remarks
A nonce is single use, random or pseudo-random byte array that can be included in a certificate request to help
ensure that the request is not a repeat of a previous message.
You can set this property before calling the Encode method, but you must initialize the CMC request object
before calling the property. For more information, see the following topics:
Initialize
InitializeDecode
InitializeFromCertificate
InitializeFromInnerRequest
InitializeFromInnerRequestTemplateName
InitializeFromTemplateName

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]
 Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509CertificateRequestCmc
 IX509CertificateRequestCmc::get_SignatureInformation
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The SignatureInformation property retrieves the IX509SignatureInformation object that contains information
about the primary signature used to sign the certificate request. This property is web enabled.
This property is read-only.

Syntax
HRESULT get_SignatureInformation(
IX509SignatureInformation **ppValue
);

Parameters
ppValue

Return value
None

Remarks
The IX509SignatureInformation object contains information about the hash, public key and signature algorithms
used for the primary signature that signs the certificate request. A CMC request can have a primary signature
plus zero or more certificate-based signatures. Certificate-based signatures can be included in a request if, for
example, one or more additional parties must vouch for the identity of the entity requesting the new certificate.
You can call the SignerCertificates property to retrieve a collection of these additional certificate-based
signatures.
The primary signature is typically created by using the private key that matches the public key in the inner PKCS
#10 request object. Because the private key is usually created to enroll a new request in a certificate hierarchy,
the primary signature is not certificate-based, and you must call the SignatureInformation property to
retrieve it.
If the IX509SignatureInformation object does not exist when the SignatureInformation property is called or
creation of the signature was deferred during initialization, this property:
Retrieves the innermost PKCS #10 request object.
Retrieves and duplicates the signature information from the inner request.
Attempts to retrieve the private key associated with the inner PKCS #10 and sets the NullSigned property if
no private key can be found.
Retrieves the hash algorithm, if one is specified, from the template associated with the inner request and sets
the HashAlgorithm property.
Retrieves the asymmetric algorithm, if one is specified, from the private key associated with the inner request
and sets the PublicKeyAlgorithm property.
Retrieves the private key flags from the template and sets the AlternateSignatureAlgorithm if appropriate
You must initialize the CMC request object before calling this property. For more information, see the following
topics:
Initialize
InitializeDecode
InitializeFromCertificate
InitializeFromInnerRequest
InitializeFromInnerRequestTemplateName
InitializeFromTemplateName

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509CertificateRequestCmc
IX509CertificateRequestPkcs10
 IX509CertificateRequestCmc::get_SignerCertificates
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The SignerCer tificates property retrieves a collection of certificates used to sign the request.
This property is read-only.

Syntax
HRESULT get_SignerCertificates(
ISignerCertificates **ppValue
);

Parameters
ppValue

Return value
None

Remarks
A CMC request can have a primary signature plus zero or more certificate-based signatures. Certificate-based
signatures can be included in a request if, for example, one or more additional parties must vouch for the
identity of the entity requesting the new certificate. Call the SignerCer tificates property to retrieve a collection
of these additional certificate-based signatures.
The primary signature is typically created by using the private key that matches the public key in the inner PKCS
#10 request object. Because the private key is usually created to enroll a new request in a certificate hierarchy,
the primary signature is not certificate-based, and you must call the SignatureInformation property to retrieve
it.
You must initialize the CMC request object before calling this property. For more information, see the following
topics:
Initialize
InitializeDecode
InitializeFromCertificate
InitializeFromInnerRequest
InitializeFromInnerRequestTemplateName
InitializeFromTemplateName

Requirements
 Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509CertificateRequestCmc
 IX509CertificateRequestCmc::get_SuppressOids
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The SuppressOids property retrieves a collection of extension or attribute object identifiers (OIDs) to be
suppressed from the certificate during the encoding process.
This property is read-only.

Syntax
HRESULT get_SuppressOids(
IObjectIds **ppValue
);

Parameters
ppValue

Return value
None

Remarks
Attributes and extensions are added to a certificate request when it is encoded or initialized. You can suppress
the addition of default extensions and attributes by calling the SuppressDefaults property. For a CMC request,
only the XCN_OID_REQUEST_CLIENT_INFO (IX509AttributeClientId) attribute is created by default. No
extensions are added by default.
You must initialize the IX509CertificateRequestCmc object before calling this property. For more information,
see any of the following methods:
Initialize
InitializeDecode
InitializeFromCertificate
InitializeFromInnerRequest
InitializeFromInnerRequestTemplateName
InitializeFromTemplateName

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]
 Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509CertificateRequestCmc
 IX509CertificateRequestCmc::get_TemplateObjectId
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The TemplateObjectId property retrieves the object identifier (OID) of the template used to create the
certificate request.
This property is read-only.

Syntax
HRESULT get_TemplateObjectId(
IObjectId **ppValue
);

Parameters
ppValue

Return value
None

Remarks
The object identifier can be an OID for the Active Directory Common Name (CN) of the template. You must
initialize the IX509CertificateRequestCmc object before calling this property. For more information, see any of
the following methods:
Initialize
InitializeDecode
InitializeFromCertificate
InitializeFromInnerRequest
InitializeFromInnerRequestTemplateName
InitializeFromTemplateName

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h
 DLL CertEnroll.dll

See also
IX509CertificateRequestCmc
 IX509CertificateRequestCmc::get_TransactionId
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The TransactionId property specifies or retrieves a transaction identifier that can be used to track a certificate
request or response.
This property is read/write.

Syntax
HRESULT get_TransactionId(
LONG *pValue
);

Parameters
pValue

Return value
None

Remarks
A round trip certificate request and response transaction can be tracked using an identifier. The client generates
a transaction ID and retains it until the certificate or registration authority responds with a message that
completes the transaction. The response includes the identifier.
You must set this property, if at all, before calling the Encode method, but you must initialize the CMC request
object before calling the property. For more information, see the following topics:
Initialize
InitializeDecode
InitializeFromCertificate
InitializeFromInnerRequest
InitializeFromInnerRequestTemplateName
InitializeFromTemplateName

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

 Header certenroll.h

DLL CertEnroll.dll

See also
IX509CertificateRequestCmc
 IX509CertificateRequestCmc::get_X509Extensions
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The X509Extensions property retrieves a collection of the extensions included in the certificate request.
This property is read-only.

Syntax
HRESULT get_X509Extensions(
IX509Extensions **ppValue
);

Parameters
ppValue

Return value
None

Remarks
You must initialize the CMC request object before calling this property. For more information, see the following
topics:
Initialize
InitializeDecode
InitializeFromCertificate
InitializeFromInnerRequest
InitializeFromInnerRequestTemplateName
InitializeFromTemplateName

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll
See also
IX509CertificateRequestCmc
 IX509CertificateRequestCmc::InitializeFromInnerRequestTemplateName
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The InitializeFromInnerRequestTemplateName method initializes the certificate request from an inner

request object and a template.

Syntax
HRESULT InitializeFromInnerRequestTemplateName(
[in] IX509CertificateRequest *pInnerRequest,
[in] BSTR strTemplateName
);

Parameters
[in] pInnerRequest

Pointer to an IX509CertificateRequest interface that represents the inner request object. This can be a PKCS #10
or a CMC request.
[in] strTemplateName

A BSTR variable that contains the Common Name (CN) of the template as it appears in Active Directory or the
dotted decimal object identifier.

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. Possible values include, but are not
limited to, those in the following table. For a list of common error codes, see Common HRESULT Values.

RET URN C O DE/ VA L UE DESC RIP T IO N

The request object passed to the pInnerRequest parameter

CRYPT_E_INVALID_MSG_TYPE must be a PKCS #10 or a CMC request.

The request object has already been initialized.

HRESULT_FROM_WIN32(ERROR_ALREADY_INITIALIZE
D)

Remarks
By specifying a template, you can add information to the outer request object that may not be contained in the
inner request. For example, if the inner request does not contain the necessary extensions, you can supply a
template that does.
The InitializeFromInnerRequestTemplateName method:
Creates an empty ICryptAttributes collection.
Creates an empty IX509NameValuePairs collection.
Creates an empty IX509Extensions collection.
Creates an IObjectIds collection for critical extensions and adds the XCN_OID_KEY_USAGE and
XCN_OID_BASIC_CONSTRAINTS2 object identifiers (OIDs).
Creates an empty IObjectIds collection of OIDs to be suppressed from the request object.
Creates an empty ISignerCertificates collection.
Retrieves private key flags from the template.
Sets the ArchivePrivateKey property if required by the template flags or settings.
Retrieves the encryption algorithm from the template if one is specified and sets the EncryptionAlgorithm
property.
 Sets the EncryptionStrength property if possible.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509CertificateRequestCmc
 IX509CertificateRequestCmc::put_ArchivePrivateKey
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The ArchivePrivateKey property specifies or retrieves a Boolean value that indicates whether to archive a
private key on the certification authority (CA).
This property is read/write.

Syntax
HRESULT put_ArchivePrivateKey(
VARIANT_BOOL Value
);

Parameters
Value

Return value
None

Remarks
To request that a CA archive your private key, you must also set the KeyArchivalCertificate property with the CA
encryption (key exchange) certificate.
You can set this property before calling the Encode method, but you must initialize the CMC request object
before setting the property value. For more information, see the following topics:
Initialize
InitializeDecode
InitializeFromCertificate
InitializeFromInnerRequest
InitializeFromInnerRequestTemplateName
InitializeFromTemplateName

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

 Header certenroll.h

DLL CertEnroll.dll

See also
IX509CertificateRequestCmc
 IX509CertificateRequestCmc::put_EncryptionAlgorithm
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Encr yptionAlgorithm property specifies or retrieves an object identifier (OID) of the algorithm used to
encrypt the private key to be archived. This property is web enabled for both input and output.
This property is read/write.

Syntax
HRESULT put_EncryptionAlgorithm(
IObjectId *pValue
);

Parameters
pValue

Return value
None

Remarks
When you request that a certification authority (CA) archive your private key, you must retrieve an exchange
certificate from the CA and use the public key contained in that certificate to encrypt the private key that you are
submitting for archival. The Encr yptionAlgorithm property identifies the algorithm used to encrypt your key.
This property is related to the following properties:
ArchivePrivateKey
EncryptedKeyHash
EncryptionStrength
KeyArchivalCertificate
You must set this property, if at all, before calling the Encode method, but you must initialize the CMC request
object before calling the property. For more information, see the following topics:
Initialize
InitializeDecode
InitializeFromCertificate
InitializeFromInnerRequest
InitializeFromInnerRequestTemplateName
InitializeFromTemplateName

Requirements
 Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509CertificateRequestCmc
 IX509CertificateRequestCmc::put_EncryptionStrength
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Encr yptionStrength property specifies or retrieves the relative encryption level applied to the private key
to be archived.
This property is read/write.

Syntax
HRESULT put_EncryptionStrength(
LONG Value
);

Parameters
Value

Return value
None

Remarks
This property is related to the following properties:
ArchivePrivateKey
EncryptedKeyHash
EncryptionAlgorithm
KeyArchivalCertificate
The encryption strength is often implied by the encryption algorithm. If the algorithm does not support multiple
strengths, you should not set the Encr yptionStrength property.
You must set this property, if at all, before calling the Encode method, but you must initialize the CMC request
object before calling the property. For more information, see the following topics:
Initialize
InitializeDecode
InitializeFromCertificate
InitializeFromInnerRequest
InitializeFromInnerRequestTemplateName
InitializeFromTemplateName

Requirements
 Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509CertificateRequestCmc
 IX509CertificateRequestCmc::put_KeyArchivalCertificate
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The KeyArchivalCer tificate property specifies or retrieves a certification authority (CA) encryption certificate.
The certificate is contained in a byte array that is encoded by using Distinguished Encoding Rules (DER) as
defined by the Abstract Syntax Notation One (ASN.1) standard. The DER-encoded byte array is represented by a
string that is either a pure binary sequence or is Unicode encoded. This property is web enabled for both input
and output.
This property is read/write.

Syntax
HRESULT put_KeyArchivalCertificate(
EncodingType Encoding,
BSTR Value
);

Parameters
Encoding

Value

Return value
None

Remarks
If correctly configured, a certification authority (CA) can archive a client's private key. Typically, the client
requests an exchange certificate from the CA, validates it, and uses it as input to the KeyArchivalCer tificate
property. The CA's public key is used to encrypt the private key that is being submitted for archiving. You can
use the ArchivePrivateKey property to request key archival.
You must set this property, if at all, before calling the Encode method, but you must initialize the CMC request
object before calling the property. For more information, see the following topics:
Initialize
InitializeDecode
InitializeFromCertificate
InitializeFromInnerRequest
InitializeFromInnerRequestTemplateName
InitializeFromTemplateName

Requirements
 Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509CertificateRequestCmc
 IX509CertificateRequestCmc::put_SenderNonce
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The SenderNonce property specifies or retrieves a byte array that contains a nonce. The byte array is
represented by a string that is either a pure binary sequence or is Unicode encoded.
This property is read/write.

Syntax
HRESULT put_SenderNonce(
EncodingType Encoding,
BSTR Value
);

Parameters
Encoding

Value

Return value
None

Remarks
A nonce is single use, random or pseudo-random byte array that can be included in a certificate request to help
ensure that the request is not a repeat of a previous message.
You can set this property before calling the Encode method, but you must initialize the CMC request object
before calling the property. For more information, see the following topics:
Initialize
InitializeDecode
InitializeFromCertificate
InitializeFromInnerRequest
InitializeFromInnerRequestTemplateName
InitializeFromTemplateName

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]
 Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509CertificateRequestCmc
 IX509CertificateRequestCmc::put_TransactionId
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The TransactionId property specifies or retrieves a transaction identifier that can be used to track a certificate
request or response.
This property is read/write.

Syntax
HRESULT put_TransactionId(
LONG Value
);

Parameters
Value

Return value
None

Remarks
A round trip certificate request and response transaction can be tracked using an identifier. The client generates
a transaction ID and retains it until the certificate or registration authority responds with a message that
completes the transaction. The response includes the identifier.
You must set this property, if at all, before calling the Encode method, but you must initialize the CMC request
object before calling the property. For more information, see the following topics:
Initialize
InitializeDecode
InitializeFromCertificate
InitializeFromInnerRequest
InitializeFromInnerRequestTemplateName
InitializeFromTemplateName

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

 Header certenroll.h

DLL CertEnroll.dll

See also
IX509CertificateRequestCmc
 IX509CertificateRequestCmc2 interface (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The IX509Cer tificateRequestCmc2 interface represents a CMC (Certificate Management Message over CMS)
certificate request. It includes all of the methods defined by the IX509CertificateRequestCmc interface and adds
methods that enable initialization from certificate request templates.

Inheritance
The IX509Cer tificateRequestCmc2 interface inherits from IX509CertificateRequestCmc.
IX509Cer tificateRequestCmc2 also has these types of members:

Methods
The IX509Cer tificateRequestCmc2 interface has these methods.

IX509CertificateRequestCmc2::CheckCertificateSignature

Verifies the signature for a specified signer.

IX509CertificateRequestCmc2::CheckSignature

Verifies that the certificate request has been signed and that the signature is valid.

IX509CertificateRequestCmc2::get_PolicyServer

Retrieves the certificate enrollment policy (CEP) server that contains the template used during initialization.

IX509CertificateRequestCmc2::get_Template

Retrieves the certificate request template used during initialization.

IX509CertificateRequestCmc2::InitializeFromInnerRequestTemplate

Initializes the certificate request from an inner request object and a template.

IX509CertificateRequestCmc2::InitializeFromTemplate

Initializes the certificate request by using a template.

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Target Platform Windows

 Header certenroll.h

See also
IX509CertificateRequestCmc
IX509CertificateRequestPkcs7
 IX509CertificateRequestCmc2::CheckCertificateSignature
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The CheckCer tificateSignature method verifies the signature for a specified signer.

Syntax
HRESULT CheckCertificateSignature(
[in] ISignerCertificate *pSignerCertificate,
[in] VARIANT_BOOL ValidateCertificateChain
);

Parameters
[in] pSignerCertificate

Pointer to an ISignerCertificate interface that represents a signing certificate.

[in] ValidateCertificateChain

A Boolean value that specifies whether to also verify the certificate chain. This parameter can be NULL .

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. Possible values include, but are not
limited to, those in the following table. For a list of common error codes, see Common HRESULT Values.

RET URN C O DE/ VA L UE DESC RIP T IO N

The pSignerCertificate parameter cannot be NULL .

E_POINTER

A signer certificate cannot be found.

CERTSRV_E_PROPERTY_EMPTY

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Target Platform Windows

Header certenroll.h
See also
IX509CertificateRequestCmc2
 IX509CertificateRequestCmc2::CheckSignature
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The CheckSignature method verifies that the certificate request has been signed and that the signature is
valid.

Syntax
HRESULT CheckSignature(
[in] Pkcs10AllowedSignatureTypes AllowedSignatureTypes
);

Parameters
[in] AllowedSignatureTypes

A value from the Pkcs10AllowedSignatureTypes enumeration. This can be a bitwise combination of the
following values.

VA L UE M EA N IN G

Signatures generated by using asymmetric keys are

AllowedKeySignature permitted. If this flag is set, the signature is verified against
the public key in the inner PKCS #10 request. This is the
default flag.

Null-signed signatures are permitted.

AllowedNullSignature

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. Possible values include, but are not
limited to, those in the following table. For a list of common error codes, see Common HRESULT Values.

RET URN C O DE DESC RIP T IO N

The certificate request has not been signed.

CRYPT_E_NO_SIGNER

The signature type is not specified by the

ERROR_INVALID_STATE AllowedSignatureTypes parameter.

The value specified by the AllowedSignatureTypes parameter

NTE_BAD_SIGNATURE is not a member of the Pkcs10AllowedSignatureTypes
enumeration type.
Remarks
This method uses the public key to decrypt the signature and compares the signature to a hash of the certificate
request.

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Target Platform Windows

Header certenroll.h

See also
IX509CertificateRequestCmc2
 IX509CertificateRequestCmc2::get_PolicyServer
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The PolicySer ver property retrieves the certificate enrollment policy (CEP) server that contains the template
used during initialization.
This property is read-only.

Syntax
HRESULT get_PolicyServer(
IX509EnrollmentPolicyServer **ppPolicyServer
);

Parameters
ppPolicyServer

Return value
None

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Target Platform Windows

Header certenroll.h

See also
IX509CertificateRequestCmc2
 IX509CertificateRequestCmc2::get_Template method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Template property retrieves the certificate request template used during initialization.
This property is read-only.

Syntax
HRESULT get_Template(
IX509CertificateTemplate **ppTemplate
);

Parameters
ppTemplate

Return value
None

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Target Platform Windows

Header certenroll.h

See also
IX509CertificateRequestCmc2
 IX509CertificateRequestCmc2::InitializeFromInnerRequestTemplate
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The InitializeFromInnerRequestTemplate method initializes the certificate request from an inner request
object and a template.

Syntax
HRESULT InitializeFromInnerRequestTemplate(
[in] IX509CertificateRequest *pInnerRequest,
[in] IX509EnrollmentPolicyServer *pPolicyServer,
[in] IX509CertificateTemplate *pTemplate
);

Parameters
[in] pInnerRequest

Pointer to an IX509CertificateRequest interface that represents the inner request object. This can be a PKCS #10
or a CMC request.
[in] pPolicyServer

Pointer to an IX509EnrollmentPolicyServer object that represents the certificate enrollment policy (CEP) server
that contains the template specified by the pTemplate parameter.
[in] pTemplate

Pointer to an IX509CertificateTemplate object that represents the template to use during initialization.

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. Possible values include, but are not
limited to, those in the following table. For a list of common error codes, see Common HRESULT Values.

RET URN C O DE/ VA L UE DESC RIP T IO N

The request object passed to the pInnerRequest parameter

CRYPT_E_INVALID_MSG_TYPE must be a PKCS #10 or a CMC request.

The pInnerRequest, pPolicyServer, and pTemplate

E_POINTER parameters cannot be NULL .

The request object has already been initialized.

HRESULT_FROM_WIN32(ERROR_ALREADY_INITIALIZE
D)

Remarks
By specifying a template, you can add information to the outer request object that may not be contained in the
inner request. For example, if the inner request does not contain the necessary extensions, you can supply a
template that does.
The InitializeFromInnerRequestTemplate method:
Creates an empty ICryptAttributes collection.
 Creates an empty IX509NameValuePairs collection.
Creates an empty IX509Extensions collection.
Creates an IObjectIds collection for critical extensions and adds the XCN_OID_KEY_USAGE and
XCN_OID_BASIC_CONSTRAINTS2 object identifiers (OIDs).
Creates an empty IObjectIds collection of OIDs to be suppressed from the request object.
Creates an empty ISignerCertificates collection.
Retrieves private key flags from the template.
Sets the ArchivePrivateKey property if required by the template flags or settings.
Retrieves the encryption algorithm from the template if one is specified and sets the EncryptionAlgorithm
property.
Sets the EncryptionStrength property if possible.

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Target Platform Windows

Header certenroll.h

See also
IX509CertificateRequestCmc2
 IX509CertificateRequestCmc2::InitializeFromTemplate
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The InitializeFromTemplate method initializes the certificate request by using a template.

Syntax
HRESULT InitializeFromTemplate(
[in] X509CertificateEnrollmentContext context,
[in] IX509EnrollmentPolicyServer *pPolicyServer,
[in] IX509CertificateTemplate *pTemplate
);

Parameters
[in] context

A value of the X509CertificateEnrollmentContext enumeration type that specifies whether the requested
certificate is intended for an end user, a computer, or administrator acting on behalf of the computer. This can be
one of the following values.

VA L UE M EA N IN G

The certificate is being requested for an end user.

ContextUser

The certificate is being requested for a computer.

ContextMachine

The certificate is being requested by an administrator acting

ContextAdministratorForceMachine on the behalf of a computer.

[in] pPolicyServer

Pointer to an IX509EnrollmentPolicyServer object that represents the certificate enrollment policy (CEP) server
that contains the template specified by the pTemplate parameter.
[in] pTemplate

Pointer to an IX509CertificateTemplate object that represents the template to use during initialization.

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. Possible values include, but are not
limited to, those in the following table. For a list of common error codes, see Common HRESULT Values.

RET URN C O DE DESC RIP T IO N

 The pPolicyServer and pTemplate parameters cannot be
E_POINTER NULL .

The certificate request object has already been initialized.

HRESULT_FROM_WIN32(ERROR_ALREADY_INITIALIZE
D)

Remarks
The InitializeFromTemplate method creates the following collections:
An ICryptAttributes collection.
An IX509Extensions collection.
An IObjectIds collection populated with the default XCN_OID_KEY_USAGE and
XCN_OID_BASIC_CONSTRAINTS2 object identifiers.
An empty IObjectIds collection for attribute and extension OIDs to be suppressed from the new request.
The method then examines the template and performs the following actions:
Adds the extensions specified by the template to the IX509Extensions collection.
Removes the default critical extensions (XCN_OID_KEY_USAGE and XCN_OID_BASIC_CONSTRAINTS2) from
the collection if the template indicates that they are not critical. The OIDs marked critical by the template are
added.
Sets the SmimeCapabilities property if the template supports symmetric algorithms.
Sets the AlternateSignatureAlgorithm property if the template requires a discrete signature algorithm OID.
Creates an IX509SignatureInformation object.
Creates a hash algorithm OID if the algorithm is specified in the template and sets it on the
IX509SignatureInformation object.
Creates an asymmetric encryption algorithm OID if the algorithm is specified in the template and sets it on
the IX509SignatureInformation object.
Populates many of the IX509PrivateKey properties from the template settings.
If the CSPInformations property is NULL , the method creates an ICspInformations collection from the providers
installed on the computer.

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Target Platform Windows

Header certenroll.h

See also
IX509CertificateRequestCmc2
 IX509CertificateRequestPkcs10 interface
(certenroll.h)
7/2/2022 • 3 minutes to read • Edit Online

The IX509Cer tificateRequestPkcs10 interface represents a PKCS #10 certificate request. The public key
cryptography standard (PKCS) #10 defines the format of messages sent to a certification or registration
authority to request a public-key certificate.
A PKCS #10 ASN.1 request object contains a version identifier, the subject name, a public key and a set of
attributes as shown by the following syntax example.
 --------------------------------------------------------------------
-- Certificate request.
--------------------------------------------------------------------
CertificationRequestInfo ::= SEQUENCE
{
version CertificationRequestInfoVersion,
subject Name,
subjectPublicKeyInfo SubjectPublicKeyInfo,
attributes [0] IMPLICIT Attributes
}

-------------------------------------------------------
-- Version number.
-------------------------------------------------------
CertificationRequestInfoVersion ::= INTEGER

-------------------------------------------------------
-- Subject distinguished name (DN).
-------------------------------------------------------
Name ::= SEQUENCE OF RelativeDistinguishedName

RelativeDistinguishedName ::= SET OF AttributeTypeValue

AttributeTypeValue ::= SEQUENCE

{
type EncodedObjectID,
value ANY
}

-------------------------------------------------------
-- Public key information.
-------------------------------------------------------
SubjectPublicKeyInfo ::= SEQUENCE
{
algorithm AlgorithmIdentifier,
subjectPublicKey BITSTRING
}

-------------------------------------------------------
-- Attributes.
-------------------------------------------------------
Attributes ::= SET OF Attribute

Attribute ::= SEQUENCE

{
type EncodedObjectID,
values AttributeSetValue
}

The Cer tificationRequestInfo ASN.1 object is wrapped in a Cer tificationRequest object as shown by the
following syntax. The Cer tificationRequest object also includes the signature and the signature algorithm. A
PKCS #10 request must be signed by the associated private key or null-signed if it is a cross-certification
request. You can call the RawData property to retrieve the signed Cer tificationRequest object, and you can call
the RawDataToBeSigned property to retrieve the unsigned Cer tificationRequestInfo object.
 --------------------------------------------------------------------
-- Certificate request.
--------------------------------------------------------------------
CertificationRequest ::= SEQUENCE
{
certificationRequestInfo CertificationRequestInfo,
signatureAlgorithm AlgorithmIdentifier,
signature BIT STRING
}

--------------------------------------------
-- Algorithm Identifier
--------------------------------------------
AlgorithmIdentifier ::= SEQUENCE
{
algorithm EncodedObjectID,
parameters ANY OPTIONAL
}

The following properties can be set before calling the Encode method:
AlternateSignatureAlgorithm
ClientId
HashAlgorithm
ParentWindow
RenewalCertificate
Silent
SuppressDefaults
UIContextMessage
Also, the Silent, ParentWindow, and UIContextMessage properties are typically called before calling an initialization
method.
The following properties must be set, if at all, before calling the Encode method:
CspInformations
KeyContainerNamePrefix
SmimeCapabilities
Subject

Inheritance
The IX509Cer tificateRequestPkcs10 interface inherits from IX509CertificateRequest.
IX509Cer tificateRequestPkcs10 also has these types of members:

Methods
The IX509Cer tificateRequestPkcs10 interface has these methods.

IX509CertificateRequestPkcs10::CheckSignature

Verifies that the certificate request has been signed and that the signature is valid.
IX509CertificateRequestPkcs10::get_CriticalExtensions

Retrieves an IObjectIds collection that identifies the version 3 certificate extensions marked as critical.

IX509CertificateRequestPkcs10::get_CryptAttributes

Retrieves an ICryptAttributes collection of optional certificate attributes.

IX509CertificateRequestPkcs10::get_CspStatuses

Retrieves a collection of ICspStatus objects that matches the intended use of the private key associated with the certificate
request.

IX509CertificateRequestPkcs10::get_KeyContainerNamePrefix

Specifies or retrieves a prefix used to create the container name for a new private key.

IX509CertificateRequestPkcs10::get_NullSigned

Retrieves a Boolean value that indicates whether the certificate request is null-signed.

IX509CertificateRequestPkcs10::get_OldCertificate

Retrieves the certificate passed to the InitializeFromCertificate method.

IX509CertificateRequestPkcs10::get_PrivateKey

Retrieves an IX509PrivateKey object that contains the private key used to sign the certificate request.

IX509CertificateRequestPkcs10::get_PublicKey

Retrieves the IX509PublicKey object that contains the public key included in the certificate request.

IX509CertificateRequestPkcs10::get_RawDataToBeSigned

Retrieves the unsigned certificate request created by the Encode method.

IX509CertificateRequestPkcs10::get_ReuseKey

Retrieves a Boolean value that indicates whether an existing private key was used to sign the request.

IX509CertificateRequestPkcs10::get_Signature

Retrieves the request signature created by the Encode method.

IX509CertificateRequestPkcs10::get_SignatureInformation

Retrieves the IX509SignatureInformation object that contains information about the certificate request signature.

IX509CertificateRequestPkcs10::get_SmimeCapabilities

Specifies or retrieves a Boolean value that tells the Encode method whether to create an IX509ExtensionSmimeCapabilities
collection that identifies the encryption capabilities supported by the computer.
IX509CertificateRequestPkcs10::get_Subject

Specifies or retrieves the X.500 distinguished name of the entity requesting the certificate.

IX509CertificateRequestPkcs10::get_SuppressOids

Retrieves a collection of the default extension and attribute object identifiers (OIDs) that were not added to the request when
the request was encoded.

IX509CertificateRequestPkcs10::get_TemplateObjectId

Retrieves the object identifier (OID) of the template used to create the certificate request.

IX509CertificateRequestPkcs10::get_X509Extensions

Retrieves a collection of the extensions included in the certificate request.

IX509CertificateRequestPkcs10::GetCspStatuses

Retrieves an ICspStatuses collection that contains all provider/algorithm pairs consistent with the intended use of the private
key as specified by the caller.

IX509CertificateRequestPkcs10::InitializeDecode

Decodes an existing signed or unsigned PKCS

IX509CertificateRequestPkcs10::InitializeFromCertificate

Initializes the certificate request by using an existing certificate.

IX509CertificateRequestPkcs10::InitializeFromPrivateKey

Initializes the certificate request by using an IX509PrivateKey object and, optionally, a template.

IX509CertificateRequestPkcs10::InitializeFromPublicKey

Initializes a null-signed certificate request by using an IX509PublicKey object and, optionally, a template.

IX509CertificateRequestPkcs10::InitializeFromTemplateName

IX509CertificateRequestPkcs10::IsSmartCard

Retrieves a Boolean value that indicates whether any of the cryptographic providers associated with the request object is a
smart card provider.

IX509CertificateRequestPkcs10::put_KeyContainerNamePrefix

Specifies or retrieves a prefix used to create the container name for a new private key.

IX509CertificateRequestPkcs10::put_SmimeCapabilities

Specifies or retrieves a Boolean value that tells the Encode method whether to create an IX509ExtensionSmimeCapabilities
collection that identifies the encryption capabilities supported by the computer.
 IX509CertificateRequestPkcs10::put_Subject

Specifies or retrieves the X.500 distinguished name of the entity requesting the certificate.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

See also
CertEnroll Interfaces
IX509CertificateRequest
 IX509CertificateRequestPkcs10::CheckSignature
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The CheckSignature method verifies that the certificate request has been signed and that the signature is
valid.

Syntax
HRESULT CheckSignature(
[in] Pkcs10AllowedSignatureTypes AllowedSignatureTypes
);

Parameters
[in] AllowedSignatureTypes

An Pkcs10AllowedSignatureTypes enumeration value. This can be a bitwise combination of the following values.

VA L UE M EA N IN G

Signatures generated by using asymmetric keys are

AllowedKeySignature permitted. If this flag is set, the signature is verified against
the public key in the PKCS #10 request.

Null-signed signatures are permitted.

AllowedNullSignature

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. Possible values include, but are not
limited to, those in the following table. For a list of common error codes, see Common HRESULT Values.

RET URN C O DE DESC RIP T IO N

The certificate request has not been signed.

CRYPT_E_NO_SIGNER

The signature type is not specified by the

ERROR_INVALID_STATE AllowedSignatureTypes parameter.

The value specified by the AllowedSignatureTypes parameter

NTE_BAD_SIGNATURE is not a member of the Pkcs10AllowedSignatureTypes
enumeration type.

Remarks
This method uses the public key to decrypt the signature and compares the signature to a hash of the certificate
request.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509CertificateRequestPkcs10
 IX509CertificateRequestPkcs10::get_CriticalExtensions
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The CriticalExtensions property retrieves an IObjectIds collection that identifies the version 3 certificate
extensions marked as critical.
This property is read-only.

Syntax
HRESULT get_CriticalExtensions(
IObjectIds **ppValue
);

Parameters
ppValue

Return value
None

Remarks
The extension criticality indicates to an application that uses certificates whether it can ignore the extension. You
must initialize the IX509CertificateRequestPkcs10 object before calling this property. For more information, see
any of the following methods:
InitializeDecode
InitializeFromCertificate
InitializeFromPrivateKey
InitializeFromPublicKey
InitializeFromTemplateName

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h
 DLL CertEnroll.dll

See also
IX509CertificateRequestPkcs10
 IX509CertificateRequestPkcs10::get_CryptAttributes
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Cr yptAttributes property retrieves an ICryptAttributes collection of optional certificate attributes.

This property is read-only.

Syntax
HRESULT get_CryptAttributes(
ICryptAttributes **ppValue
);

Parameters
ppValue

Return value
None

Remarks
You must initialize the IX509CertificateRequestPkcs10 object before calling this property. For more information,
see any of the following methods:
InitializeDecode
InitializeFromCertificate
InitializeFromPrivateKey
InitializeFromPublicKey
InitializeFromTemplateName

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll
See also
IX509CertificateRequestPkcs10
 IX509CertificateRequestPkcs10::get_CspStatuses
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The CspStatuses property retrieves a collection of ICspStatus objects that matches the intended use of the
private key associated with the certificate request.
This property is read-only.

Syntax
HRESULT get_CspStatuses(
ICspStatuses **ppValue
);

Parameters
ppValue

Return value
None

Remarks
This property retrieves a collection of ICspStatus objects. Each object represents a single provider/algorithm pair.
The CspStatuses property differs from the GetCspStatuses method. The method enables you to set a KeySpec
parameter, but CspStatuses uses the KeySpec property set on the private key associated with the
IX509CertificateRequestPkcs10 object. This can be one of the following values.

VA L UE DESC RIP T IO N

XCN_AT_NONE Only Cryptography API: Next Generation (CNG) providers

are selected.

XCN_AT_KEYEXCHANGE Only CryptoAPI cryptographic service providers (CSPs) with

encryption algorithms (including key exchange) are selected.

XCN_AT_SIGNATURE Only CryptoAPI cryptographic service providers (CSPs) with

signature algorithms are selected.

If you specify a template when initializing the request object, template attributes such as the pKIDefaultCSPs
and pKIDefaultKeySpec affect which provider/algorithm pairs are initially enabled in the collection. You can
call the following properties on each ICspStatus object to retrieve information about a pair:
The CspInformation property retrieves provider information.
The CspAlgorithm property retrieves algorithm information.
The EnrollmentStatus property retrieves an IX509EnrollmentStatus object. Call the Selected property on the
 status object to determine whether the provider/algorithm pair is enabled for this request.
The Ordinal property retrieves the position in the collection of the provider/algorithm pair.
The collection retrieved by this method is saved internally on the request object. The collection exists as long as
the PKCS #10 object continues to exist.
Assume, for example, that the KeySpec property on the private key associated with the request object is set to
XCN_AT_SIGNATURE and that a template is used to initialize the request. The following statements will be true:
A collection of ICspStatus objects is created and saved on the IX509CertificateRequestPkcs10 object. The
collection contains all valid provider/algorithm pairs installed on the computer.
Because the KeySpec property is not set to XCN_AT_NONE, the Selected property is set to SelectedNo for
each Cryptography API: Next Generation (CNG) provider/algorithm pair in the collection.
Because the KeySpec property is not set to XCN_AT_KEYEXCHANGE, the Selected property is set to
SelectedNo for each CryptoAPI CSP/algorithm pair in the collection where the algorithm can be used only to
encrypt data or archive a key.
For each provider referenced by the template or private key but not supported on the computer, a
placeholder ICspStatus object is created and added to the collection and the Selected property is set to
SelectedNo.
The Selected property is set to SelectedYes for each CryptoAPI CSP/algorithm pair where the algorithm can
be used only to sign data.
The Ordinal property is set to reflect the CSP order, if any, identified by the pKIDefaultCSPs template
attribute. The CSPs listed first by the attribute are ordered first in the collection. This property is used during
enrollment if a private key must be created. The first selected CSP/algorithm pair is used to create the key,
but if the operation fails, the next selected pair is tried.
You must initialize the IX509CertificateRequestPkcs10 object before calling this method. For more information,
see any of the following methods:
InitializeDecode
InitializeFromCertificate
InitializeFromPrivateKey
InitializeFromPublicKey
InitializeFromTemplateName

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
ICspAlgorithm
ICspAlgorithms
ICspInformation
ICspInformations
ICspStatus
IX509CertificateRequestPkcs10
 IX509CertificateRequestPkcs10::get_KeyContainerNamePrefix
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The KeyContainerNamePrefix property specifies or retrieves a prefix used to create the container name for a
new private key.
This property is read/write.

Syntax
HRESULT get_KeyContainerNamePrefix(
BSTR *pValue
);

Parameters
pValue

Return value
None

Remarks
Each CryptoAPI cryptographic service provider or Cryptography API: Next Generation (CNG) key provider
maintains a key container for the private key. To retrieve the name of a key container for an existing key, use the
ContainerName property of the IX509PrivateKey object.
A prefix can contain any string limited to the maximum length of the key container name and to legal container
name characters. For example, if you do not call the ContainerName property to specify a key container name,
one is automatically created when the private key is created, and the prefix to the container name will be the
string "lp". For another example, if you are creating a test harness and want to differentiate key containers by the
programs that generated them, you can use the name of the executable as the prefix.
You must set this property before calling the Encode method, and you must initialize the
IX509CertificateRequestPkcs10 object before calling this property. For more information, see any of the
following methods:
InitializeDecode
InitializeFromCertificate
InitializeFromPrivateKey
InitializeFromPublicKey
InitializeFromTemplateName

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]
 Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509CertificateRequestPkcs10
 IX509CertificateRequestPkcs10::get_NullSigned
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The NullSigned property retrieves a Boolean value that indicates whether the certificate request is null-signed.
This property is read-only.

Syntax
HRESULT get_NullSigned(
VARIANT_BOOL *pValue
);

Parameters
pValue

Return value
None

Remarks
A null-signed PKCS #10 certificate request is not really signed. That is, the signature is a hash created by using a
digest algorithm such as SHA-1, but the request is not encrypted with a public key algorithm such as RSA. This
can be used when a private key is not available as is often the case when certification authorities are being
cross-certified. For more information, see the InitializeFromPublicKey method.
You must initialize the IX509CertificateRequestPkcs10 object before calling this property. For more information,
see any of the following methods:
InitializeDecode
InitializeFromCertificate
InitializeFromPrivateKey
InitializeFromPublicKey
InitializeFromTemplateName

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

 Header certenroll.h

DLL CertEnroll.dll

See also
IX509CertificateRequestPkcs10
 IX509CertificateRequestPkcs10::get_OldCertificate
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The OldCer tificate property retrieves the certificate passed to the InitializeFromCertificate method. The
certificate is contained in a byte array encoded by using Distinguished Encoding Rules (DER) as defined by the
Abstract Syntax Notation One (ASN.1) standard. The DER-encoded byte array is represented by a string that is
either a pure binary sequence or is Unicode encoded.
This property is read-only.

Syntax
HRESULT get_OldCertificate(
EncodingType Encoding,
BSTR *pValue
);

Parameters
Encoding

pValue

Return value
None

Remarks
You must initialize the IX509CertificateRequestPkcs10 object before calling this property. For more information,
see any of the following methods:
InitializeDecode
InitializeFromCertificate
InitializeFromPrivateKey
InitializeFromPublicKey
InitializeFromTemplateName

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

 Header certenroll.h

DLL CertEnroll.dll

See also
IX509CertificateRequestPkcs10
 IX509CertificateRequestPkcs10::get_PrivateKey
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The PrivateKey property retrieves an IX509PrivateKey object that contains the private key used to sign the
certificate request. This property is web enabled.
This property is read-only.

Syntax
HRESULT get_PrivateKey(
IX509PrivateKey **ppValue
);

Parameters
ppValue

Return value
None

Remarks
You must initialize the IX509CertificateRequestPkcs10 object before calling this property. For more information,
see any of the following methods:
InitializeDecode
InitializeFromCertificate
InitializeFromPrivateKey
InitializeFromPublicKey
InitializeFromTemplateName

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll
See also
IX509CertificateRequestPkcs10
 IX509CertificateRequestPkcs10::get_PublicKey
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The PublicKey property retrieves the IX509PublicKey object that contains the public key included in the
certificate request.
This property is read-only.

Syntax
HRESULT get_PublicKey(
IX509PublicKey **ppValue
);

Parameters
ppValue

Return value
None

Remarks
You must initialize the IX509CertificateRequestPkcs10 object before calling this property. For more information,
see any of the following methods:
InitializeDecode
InitializeFromCertificate
InitializeFromPrivateKey
InitializeFromPublicKey
InitializeFromTemplateName

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll
See also
IX509CertificateRequestPkcs10
 IX509CertificateRequestPkcs10::get_RawDataToBeSigned
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The RawDataToBeSigned property retrieves the unsigned certificate request created by the Encode method.
The request is contained in a byte array encoded by using Distinguished Encoding Rules (DER) as defined by the
Abstract Syntax Notation One (ASN.1) standard. The DER-encoded byte array is represented by a string that is
either a pure binary sequence or is Unicode encoded.
This property is read-only.

Syntax
HRESULT get_RawDataToBeSigned(
EncodingType Encoding,
BSTR *pValue
);

Parameters
Encoding

pValue

Return value
None

Remarks
The Encode method creates a DER-encoded and signed certificate request, but it also internally saves the
unsigned request as a byte array. You can use the RawDataToBeSigned property to retrieve that binary data as
an Unicode-encoded string.
You must initialize the IX509CertificateRequestPkcs10 object and call Encode before calling this property. For
more information, see any of the following methods:
InitializeDecode
InitializeFromCertificate
InitializeFromPrivateKey
InitializeFromPublicKey
InitializeFromTemplateName

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

 Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509CertificateRequestPkcs10
 IX509CertificateRequestPkcs10::get_ReuseKey
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The ReuseKey property retrieves a Boolean value that indicates whether an existing private key was used to
sign the request.
This property is read-only.

Syntax
HRESULT get_ReuseKey(
VARIANT_BOOL *pValue
);

Parameters
pValue

Return value
None

Remarks
If you initialized the request object by calling the InitializeFromCertificate method, you specified a value for the
InheritOptions parameter that indicated whether the private key used to sign the request was inherited from the
certificate. If you specified InheritPrivateKey for this parameter, the ReuseKey property returns a value of
Boolean true.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509CertificateRequestPkcs10
 IX509CertificateRequestPkcs10::get_Signature
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Signature property retrieves the request signature created by the Encode method. The signature is
contained in a byte array encoded by using Distinguished Encoding Rules (DER) as defined by the Abstract
Syntax Notation One (ASN.1) standard. The DER-encoded byte array is represented by a string that is either a
pure binary sequence or is Unicode encoded.
This property is read-only.

Syntax
HRESULT get_Signature(
EncodingType Encoding,
BSTR *pValue
);

Parameters
Encoding

pValue

Return value
None

Remarks
The Encode method creates a DER-encoded and signed certificate request which it saves internally as a byte
array. You can use the Signature property to retrieve a byte array that contains the signature.
You must initialize the IX509CertificateRequestPkcs10 object and call Encode before calling this property. For
more information, see any of the following methods:
InitializeDecode
InitializeFromCertificate
InitializeFromPrivateKey
InitializeFromPublicKey
InitializeFromTemplateName

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

 Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509CertificateRequestPkcs10
 IX509CertificateRequestPkcs10::get_SignatureInformation
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The SignatureInformation property retrieves the IX509SignatureInformation object that contains information
about the certificate request signature. This property is web enabled.
This property is read-only.

Syntax
HRESULT get_SignatureInformation(
IX509SignatureInformation **ppValue
);

Parameters
ppValue

Return value
None

Remarks
The IX509SignatureInformation object contains information about the hash, public key and signature algorithms
used to sign the certificate request. If no IX509SignatureInformation object has been associated with the
request, this property attempts to create one and use the private key to set the PublicKeyAlgorithm property.
You must initialize the IX509CertificateRequestPkcs10 object and call Encode before calling this property. For
more information, see any of the following methods:
InitializeDecode
InitializeFromCertificate
InitializeFromPrivateKey
InitializeFromPublicKey
InitializeFromTemplateName

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

 Header certenroll.h

DLL CertEnroll.dll

See also
IX509CertificateRequestPkcs10
 IX509CertificateRequestPkcs10::get_SmimeCapabilities
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The SmimeCapabilities property specifies or retrieves a Boolean value that tells the Encode method whether
to create an IX509ExtensionSmimeCapabilities collection that identifies the encryption capabilities supported by
the computer. This property is web enabled for both input and output.
This property is read/write.

Syntax
HRESULT get_SmimeCapabilities(
VARIANT_BOOL *pValue
);

Parameters
pValue

Return value
None

Remarks
Multipurpose Internet Mail Extensions (MIME) is a specification for formatting binary data into text so that it can
be sent in email. Secure/Multipurpose Internet Mail Extensions (S/MIME) is a standard for encrypting and
signing a MIME message.
The SmimeCapabilities extension, represented by an IX509ExtensionSmimeCapabilities object, is used when
sending and receiving encrypted email messages to report the recipient's decryption capabilities to the sender.
This enables the sender to choose the most secure algorithm supported by both the sender and recipient.
If you did not set the SuppressDefaults property before calling the Encode method, the SmimeCapabilities
extension is added by default and the available symmetric algorithm OIDs are enumerated and added to the
extension value. Set the SmimeCapabilities property before calling Encode .

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

 Header certenroll.h

DLL CertEnroll.dll

See also
IX509CertificateRequestPkcs10
 IX509CertificateRequestPkcs10::get_Subject method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Subject property specifies or retrieves the X.500 distinguished name of the entity requesting the certificate.
This property is web enabled for both input and output.
This property is read/write.

Syntax
HRESULT get_Subject(
IX500DistinguishedName **ppValue
);

Parameters
ppValue

Return value
None

Remarks
You must set this property before calling the Encode method, and you must initialize the
IX509CertificateRequestPkcs10 object before calling this property. For more information, see any of the
following methods:
InitializeDecode
InitializeFromCertificate
InitializeFromPrivateKey
InitializeFromPublicKey
InitializeFromTemplateName

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h
 DLL CertEnroll.dll

See also
IX509CertificateRequestPkcs10
 IX509CertificateRequestPkcs10::get_SuppressOids
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The SuppressOids property retrieves a collection of the default extension and attribute object identifiers (OIDs)
that were not added to the request when the request was encoded.
This property is read-only.

Syntax
HRESULT get_SuppressOids(
IObjectIds **ppValue
);

Parameters
ppValue

Return value
None

Remarks
Attributes and extensions are added to a certificate request when it is encoded or initialized. You can suppress
the addition of default extensions and attributes by calling the SuppressDefaults property. For a PKCS #10
request, the following attributes are added by default:
XCN_OID_REQUEST_CLIENT_INFO (IX509AttributeClientId)
XCN_OID_ENROLLMENT_CSP_PROVIDER (IX509AttributeCspProvider)
XCN_OID_OS_VERSION (IX509AttributeOSVersion)
XCN_OID_RENEWAL_CERTIFICATE (IX509AttributeRenewalCertificate)
The following extensions are added by default:
XCN_OID_RSA_SMIMECapabilities (IX509ExtensionSmimeCapabilities)
XCN_OID_SUBJECT_KEY_IDENTIFIER (IX509ExtensionSubjectKeyIdentifier)
XCN_OID_KEY_USAGE (IX509ExtensionKeyUsage)
You must initialize the IX509CertificateRequestPkcs10 object before calling this property. For more information,
see any of the following methods:
InitializeDecode
InitializeFromCertificate
InitializeFromPrivateKey
InitializeFromPublicKey
InitializeFromTemplateName
Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
ICryptAttribute
IX509CertificateRequestPkcs10
IX509Extension
 IX509CertificateRequestPkcs10::get_TemplateObjectId
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The TemplateObjectId property retrieves the object identifier (OID) of the template used to create the
certificate request.
This property is read-only.

Syntax
HRESULT get_TemplateObjectId(
IObjectId **ppValue
);

Parameters
ppValue

Return value
None

Remarks
The object identifier can be an OID for the Active Directory Common Name (CN) of the template. You must
initialize the IX509CertificateRequestPkcs10 object before calling this property. For more information, see any of
the following methods:
InitializeDecode
InitializeFromCertificate
InitializeFromPrivateKey
InitializeFromPublicKey
InitializeFromTemplateName

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h
 DLL CertEnroll.dll

See also
IX509CertificateRequestPkcs10
 IX509CertificateRequestPkcs10::get_X509Extensions
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The X509Extensions property retrieves a collection of the extensions included in the certificate request. This
property is web enabled.
This property is read-only.

Syntax
HRESULT get_X509Extensions(
IX509Extensions **ppValue
);

Parameters
ppValue

Return value
None

Remarks
You must initialize the IX509CertificateRequestPkcs10 object before calling this property. For more information,
see any of the following methods:
InitializeDecode
InitializeFromCertificate
InitializeFromPrivateKey
InitializeFromPublicKey
InitializeFromTemplateName

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll
See also
IX509CertificateRequestPkcs10
 IX509CertificateRequestPkcs10::GetCspStatuses
method (certenroll.h)
7/2/2022 • 3 minutes to read • Edit Online

The GetCspStatuses method retrieves an ICspStatuses collection that contains all provider/algorithm pairs
consistent with the intended use of the private key as specified by the caller.

Syntax
HRESULT GetCspStatuses(
[in] X509KeySpec KeySpec,
[out] ICspStatuses **ppCspStatuses
);

Parameters
[in] KeySpec

An X509KeySpec enumeration value that specifies the intended use of the key. This can be one of the following
values.

VA L UE M EA N IN G

Only Cryptography API: Next Generation (CNG) providers

XCN_AT_NONE are selected.

Only CryptoAPI cryptographic service providers (CSPs) with

XCN_AT_KEYEXCHANGE encryption algorithms (including key exchange) are selected.

Only CryptoAPI CSPs with signature algorithms are selected.

XCN_AT_SIGNATURE

[out] ppCspStatuses

Address of a variable that receives a pointer to an ICspStatuses interface that represents the collection.

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. Possible values include, but are not
limited to, those in the following table. For a list of common error codes, see Common HRESULT Values.

RET URN C O DE DESC RIP T IO N

The private key cannot be found.

CERTSRV_E_PROPERTY_EMPTY
 The object is not initialized.
OLE_E_BL ANK

Remarks
This method retrieves a collection of ICspStatus objects. Each object represents a single provider/algorithm pair.
If you specify a template when initializing the IX509CertificateRequestPkcs10 request object, template attributes
such as the pKIDefaultCSPs and pKIDefaultKeySpec affect which pairs are initially enabled. You can call the
following properties on each ICspStatus object to retrieve information about a pair:
The CspInformation property retrieves provider information.
The CspAlgorithm property retrieves algorithm information.
The EnrollmentStatus property retrieves an IX509EnrollmentStatus object. Call the Selected property on the
status object to determine whether the provider/algorithm pair is enabled for this request.
The Ordinal property retrieves the position in the provider/algorithm pair collection.
The collection retrieved by this method is saved internally on the request object. Up to three collections, one for
each KeySpec value, can be created and saved. This is done to preserve the selection state of the
provider/algorithm pairs so that relevant property pages can be displayed accurately and quickly multiple times
and so that the Encode method can identify which providers and algorithms are selected if a private key must be
created. If the selection state of a provider/algorithm pair is modified, the changes are saved to the appropriate
collection. Changes made to the members of one collection do not affect the members of any other collection.
The collections exist as long as the PKCS #10 object continues to exist.
Assume, for example, that this method is called with the KeySpec parameter set to XCN_AT_SIGNATURE and that
a template is used to initialize the request. The following statements will be true:
A collection of ICspStatus objects is created and saved on the IX509CertificateRequestPkcs10 object. The
collection contains all valid provider/algorithm pairs installed on the computer.
Because the KeySpec parameter is not set to XCN_AT_NONE, the Selected property is set to SelectedNo for
each Cryptography API: Next Generation (CNG) provider/algorithm pair in the collection.
Because the KeySpec parameter is not set to XCN_AT_KEYEXCHANGE, the Selected property is set to
SelectedNo for each CryptoAPI CSP/algorithm pair in the collection where the algorithm can be used to
encrypt data or archive a key.
For each provider referenced by the template or private key but not supported on the computer, a
placeholder ICspStatus object is created and added to the collection and the Selected property is set to
SelectedNo.
The Selected property is set to SelectedYes for each CryptoAPI CSP/algorithm pair where the algorithm can
be used only to sign data.
The Ordinal property is set to reflect the CSP order, if any, identified by the pKIDefaultCSPs template
attribute. The CSPs listed first by the attribute are ordered first in the collection. This property is used during
enrollment if a private key must be created. The first selected CSP/algorithm pair is used to create the key,
but if the operation fails, the next selected pair is tried.
Calling this method again with the same KeySpec parameter retrieves a pointer to the existing collection
created previously for that parameter value.
Calling this method again with a different KeySpec parameter will not affect the collection created for the
XCN_AT_SIGNATURE KeySpec value. Further, changing the Selected property on any member of the new
collection does not affect any member of the previous collection.
The GetCspStatuses method differs from the CspStatuses property by use of the KeySpec parameter. The
method allows users to specify this value, but the property uses the value set on the private key associated with
the request object.
You must initialize the IX509CertificateRequestPkcs10 object before calling this method. For more information,
see any of the following methods:
InitializeDecode
InitializeFromCertificate
InitializeFromPrivateKey
InitializeFromPublicKey
InitializeFromTemplateName

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509CertificateRequestPkcs10
 IX509CertificateRequestPkcs10::InitializeDecode
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The InitializeDecode method decodes an existing signed or unsigned PKCS #10 certificate request and uses it
to initialize the new PKCS #10 request object. The existing request is contained in a byte array that has been
encoded by using Distinguished Encoding Rules (DER) as defined by the Abstract Syntax Notation One (ASN.1)
standard. The byte array is represented by a string that is either a pure binary sequence or is Unicode encoded.

Syntax
HRESULT InitializeDecode(
[in] BSTR strEncodedData,
[in] EncodingType Encoding
);

Parameters
[in] strEncodedData

A BSTR variable that contains the DER-encoded request. For more information, see Remarks.
[in] Encoding

An EncodingType enumeration value that specifies the type of Unicode encoding applied to the input string that
contains the DER-encoded request. The default value is XCN_CRYPT_STRING_BASE64 .

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. Possible values include, but are not
limited to, those in the following table. For a list of common error codes, see Common HRESULT Values.

RET URN C O DE/ VA L UE DESC RIP T IO N

The certificate request object has already been initialized.

HRESULT_FROM_WIN32(ERROR_ALREADY_INITIALIZE
D)

Remarks
The InitializeDecode method decodes the existing PKCS #10 request and uses the information retrieved to
initialize the following collections for the new request object:
An empty ICryptAttributes collection.
An empty IX509Extensions collection.
An empty IObjectIds collection for attribute and extension OIDs to be suppressed from the new request.
The method also:
 Adds the decoded extensions to the IX509Extensions collection.
Adds the decoded attributes to the ICryptAttributes collection.
Sets the CriticalExtensions property with the decoded critical extensions.
Sets the ClientId property.
Sets the TemplateObjectId property.
By default, the InitializeDecode method assumes that the certificate request to be decoded is for an end user.
Beginning with Windows 8 and Windows Server 2012, you can change this default behavior. After creating an
instance of the IX509CertificateRequestPkcs10 interface, call InitializeDecode by setting the Encoding
parameter to XCN_CRYPT_STRING_BINARY and the strEncodedData parameter to one of the following
values:

VA L UE DESC RIP T IO N

L"ContextMachine" The encoded certificate request is for a computer.

L"ContextUser" The encoded certificate request is for an end user.

L"ContextAdministratorForceMachine" The encoded certificate is being requested by an

administrator acting on the behalf of a computer.

Then, call the InitializeDecode method again with the encoded certificate set in the strEncodedData argument.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509CertificateRequestPkcs10
 IX509CertificateRequestPkcs10::InitializeFromCertificate
method (certenroll.h)
7/2/2022 • 3 minutes to read • Edit Online

The InitializeFromCer tificate method initializes the certificate request by using an existing certificate. The
certificate is contained in a byte array encoded by using Distinguished Encoding Rules (DER) as defined by the
Abstract Syntax Notation One (ASN.1) standard. The DER-encoded byte array is represented by a string that is
either a pure binary sequence or is Unicode encoded.

Syntax
HRESULT InitializeFromCertificate(
[in] X509CertificateEnrollmentContext Context,
[in] BSTR strCertificate,
[in] EncodingType Encoding,
[in] X509RequestInheritOptions InheritOptions
);

Parameters
[in] Context

An X509CertificateEnrollmentContext enumeration value that specifies whether the requested certificate is

intended for an end user, a computer, or an administrator acting on behalf of the computer.
[in] strCertificate

A BSTR variable that contains the DER-encoded certificate.

Beginning with Windows 7 and Windows Server 2008 R2, you can specify a certificate thumb print or serial
number rather than an encoded certificate. Doing so causes the function to search the appropriate local stores
for the matching certificate. Keep in mind the following points:
The BSTR must be an even number of hexadecimal digits.
Whitespace between hexadecimal pairs is ignored.
The Encoding parameter must be set to XCN_CRYPT_STRING_HEXRAW .
The Context parameter determines whether the user or computer stores or both are searched.
If a private key is needed, only the personal and request stores are searched.
If a private key is not needed, the root and intermediate CA stores are also searched.
[in] Encoding

An EncodingType enumeration value that specifies the type of Unicode encoding applied to the DER-encoded
certificate. The default value is XCN_CRYPT_STRING_BASE64 .
[in] InheritOptions

An X509RequestInheritOptions enumeration value that specifies how to create the certificate request object
from the existing certificate. You can specify how to inherit a key by choosing one of the following values. The
default value is InheritDefault .
 VA L UE M EA N IN G

Provider and key inheritance is not specified.

InheritDefault

Creates a new key but inherits the default cryptographic

InheritNewDefaultKey provider.

Creates a new key but inherits the cryptographic provider

InheritNewSimilarKey used to create the existing certificate.

Inherits the private and public keys.

InheritPrivateKey

Inherits only the public key.

InheritPublicKey

You can also use a bitwise-OR operation to combine the key inheritance value with any combination of the
following values.

VA L UE M EA N IN G

Inherits the renewal certificate. Specifying this flag sets the

InheritRenewalCer tificateFlag RenewalCertificate property.

Inherits the certificate template.

InheritTemplateFlag

Inherits the subject distinguished name.

InheritSubjectFlag

Inherits the relevant extensions from the certificate.

InheritExtensionsFlag

Inherits the SubjectAlternativeName extension.

InheritSubjectAltNameFlag

Inherits the validity period.

InheritValidityPeriodFlag

You can also specify InheritNone to prevent any of the flags in the preceding table (flags not related to key
inheritance) from being implemented by default. If you specify InheritNone but also specify a flag not related
to key inheritance, the method returns E_INVALIDARG .
If you set the InheritOptions parameter to zero (0) or specify InheritDefault and do not specify a key
inheritance value, InheritNewSimilarKey is used by default.
If you set the InheritOptions parameter to zero (0) or specify InheritDefault and do not specify any of the
values not related to key inheritance, the following flags are set by default:
InheritSubjectFlag
InheritExtensionsFlag
 InheritValidityPeriodFlag
InheritTemplateFlag (if the certificate contains a template extension)

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. Possible values include, but are not
limited to, those in the following table. For a list of common error codes, see Common HRESULT Values.

RET URN C O DE DESC RIP T IO N

The certificate request object has already been initialized.

HRESULT_FROM_WIN32(ERROR_ALREADY_INITIALIZE
D)

Remarks
The InitializeFromCer tificate method validates the options specified in the InheritOptions parameter and
initializes a new PKCS #10 request object by performing the following actions:
Copies the renewal certificate, if there is one and you have specified InheritRenewalCer tificateFlag , from
the input certificate to the new request.
Copies the template if one is specified in the existing certificate and you set the InheritTemplateFlag value.
Copies the subject distinguished name to the new request if you specify InheritSubjectFlag .
Copies the subject alternative name to the new request if you specify InheritSubjectAltNameFlag .
Copies the extensions to the new request if you specify InheritExtensionsFlag .

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509CertificateRequestPkcs10
 IX509CertificateRequestPkcs10::InitializeFromPrivateKey
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The InitializeFromPrivateKey method initializes the certificate request by using an IX509PrivateKey object
and, optionally, a template. This method is web enabled.

Syntax
HRESULT InitializeFromPrivateKey(
[in] X509CertificateEnrollmentContext Context,
[in] IX509PrivateKey *pPrivateKey,
[in, optional] BSTR strTemplateName
);

Parameters
[in] Context

An X509CertificateEnrollmentContext enumeration value that specifies whether the requested certificate is

intended for an end user, a computer, or an administrator acting on behalf of the computer. This can be one of
the following values. However, if the MachineContext property of the private key is set, you must specify the
ContextMachine enumeration value.

VA L UE M EA N IN G

The certificate is being requested for an end user.

ContextUser

The certificate is being requested for a computer.

ContextMachine

The certificate is being requested by an administrator acting

ContextAdministratorForceMachine on the behalf of a computer.

[in] pPrivateKey

Pointer to an IX509PrivateKey interface that represents the private key.

[in, optional] strTemplateName

A BSTR variable that contains the Common Name (CN) of the template as it appears in Active Directory or the
dotted decimal object identifier. This is an optional parameter.

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. Possible values include, but are not
limited to, those in the following table. For a list of common error codes, see Common HRESULT Values.
 RET URN C O DE DESC RIP T IO N

The certificate request object has already been initialized.

HRESULT_FROM_WIN32(ERROR_ALREADY_INITIALIZE
D)

Remarks
If you specify a template, the InitializeFromPrivateKey method performs the following actions:
Adds the extensions specified by the template to an IX509Extensions collection.
Creates an IObjectIds collection and populates it with the default XCN_OID_KEY_USAGE and
XCN_OID_BASIC_CONSTRAINTS2 object identifiers. If the template indicates that these OIDs are not critical,
they are removed from the collection. The OIDs marked critical by the template are added.
Sets the SmimeCapabilities property if the template supports symmetric algorithms.
Sets the AlternateSignatureAlgorithm property if the template requires a discrete signature algorithm OID.
Creates an IX509SignatureInformation object.
Creates a hash algorithm OID if the algorithm is specified in the template and sets it on the
IX509SignatureInformation object.
Retrieves an asymmetric encryption algorithm OID, if it exists, from the template and sets it on the
IX509SignatureInformation object.
Populates many of the IX509PrivateKey properties from the template settings.
Whether you specify a template or not, if the CSPInformations property is not specified, the method creates an
ICspInformations collection from the providers installed on the computer.
No private key is created at this point. If the IX509PrivateKey object passed to the method does not represent an
existing key, a key is created when the Encode method is called. The key will be created by using the default
provider if no template was specified and the ProviderName property on the IX509PrivateKey is not set. When
a private key exists, it is set on the PrivateKey property.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509CertificateRequestPkcs10
 IX509CertificateRequestPkcs10::InitializeFromPublicKey
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The InitializeFromPublicKey method initializes a null-signed certificate request by using an IX509PublicKey

object and, optionally, a template.

Syntax
HRESULT InitializeFromPublicKey(
[in] X509CertificateEnrollmentContext Context,
[in] IX509PublicKey *pPublicKey,
[in, optional] BSTR strTemplateName
);

Parameters
[in] Context

An X509CertificateEnrollmentContext enumeration value that specifies whether the requested certificate is

intended for an end user, a computer, or an administrator acting on behalf of the computer.
[in] pPublicKey

Pointer to an IX509PublicKey interface that represents the public key.

[in, optional] strTemplateName

A BSTR variable that contains the Common Name (CN) of the template as it appears in Active Directory or the
dotted decimal object identifier. This is an optional parameter.

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. Possible values include, but are not
limited to, those in the following table. For a list of common error codes, see Common HRESULT Values.

RET URN C O DE/ VA L UE DESC RIP T IO N

The certificate request object has already been initialized.

HRESULT_FROM_WIN32(ERROR_ALREADY_INITIALIZE
D)

Remarks
If you specify a template, the InitializeFromPublicKey method performs the following actions:
Adds the extensions specified in the optional template, if any, to the IX509Extensions collection.
Creates a CriticalExtensions collection and populates it with the default XCN_OID_KEY_USAGE and
XCN_OID_BASIC_CONSTRAINTS2 object identifiers. If a template is specified and indicates that these OIDs
 are not critical, they are removed from the collection. The OIDs marked critical by the template, if any, are
added.
Sets the SmimeCapabilities property if the template supports symmetric algorithms.
Sets the AlternateSignatureAlgorithm property if the template requires a discrete signature algorithm OID.
Creates an IX509SignatureInformation object.
Creates a hash algorithm OID if the algorithm is specified in the template and sets it on the
IX509SignatureInformation object.
Creates an asymmetric encryption algorithm OID if the algorithm is specified in the template and sets it on
the IX509SignatureInformation object.
Whether you specify a template or not, if the CSPInformations property is not specified, the method creates an
ICspInformations collection from the providers installed on the computer.
The method does not create a private key. The use of this method implies that the request is null-signed.
Therefore, the method sets the NullSigned property on the IX509SignatureInformation object.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509CertificateRequestPkcs10
 IX509CertificateRequestPkcs10::InitializeFromTemplateName
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The InitializeFromTemplateName method initializes the certificate request by using a template.

Syntax
HRESULT InitializeFromTemplateName(
[in] X509CertificateEnrollmentContext Context,
[in] BSTR strTemplateName
);

Parameters
[in] Context

An X509CertificateEnrollmentContext enumeration value that specifies whether the requested certificate is

intended for an end user, a computer, or administrator acting on behalf of the computer.
[in] strTemplateName

A BSTR variable that contains the Common Name (CN) of the template as it appears in Active Directory or the
dotted decimal object identifier.

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. Possible values include, but are not
limited to, those in the following table. For a list of common error codes, see Common HRESULT Values.

RET URN C O DE/ VA L UE DESC RIP T IO N

The certificate request object has already been initialized.

HRESULT_FROM_WIN32(ERROR_ALREADY_INITIALIZE
D)

Remarks
The InitializeFromTemplateName method creates the following collections:
An ICryptAttributes collection.
An IX509Extensions collection.
An IObjectIds collection populated with the default XCN_OID_KEY_USAGE and
XCN_OID_BASIC_CONSTRAINTS2 object identifiers.
An empty IObjectIds collection for attribute and extension OIDs to be suppressed from the new request.
The method then examines the template and performs the following actions:
Adds the extensions specified by the template to the IX509Extensions collection.
Removes the default critical extensions (XCN_OID_KEY_USAGE and XCN_OID_BASIC_CONSTRAINTS2) from
the collection if the template indicates that they are not critical. The OIDs marked critical by the template are
 added.
Sets the SmimeCapabilities property if the template supports symmetric algorithms.
Sets the AlternateSignatureAlgorithm property if the template requires a discrete signature algorithm OID.
Creates an IX509SignatureInformation object.
Creates a hash algorithm OID if the algorithm is specified in the template and sets it on the
IX509SignatureInformation object.
Creates an asymmetric encryption algorithm OID if the algorithm is specified in the template and sets it on
the IX509SignatureInformation object.
Sets the following IX509PrivateKey properties from the template settings:
KeySpec
KeyUsage
Length
ExportPolicy
KeyProtection
SecurityDescriptor
Silent
MachineContext
Algorithm
If the CSPInformations property is NULL , the method creates an ICspInformations collection from the providers
installed on the computer.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509CertificateRequestPkcs10
 IX509CertificateRequestPkcs10::IsSmartCard method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The IsSmar tCard method retrieves a Boolean value that indicates whether any of the cryptographic providers
associated with the request object is a smart card provider.

Syntax
HRESULT IsSmartCard(
[out] VARIANT_BOOL *pValue
);

Parameters
[out] pValue

Pointer to a VARIANT_BOOL variable that indicates whether any of the enumerated and selected providers is a
smart card provider.

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. Possible values include, but are not
limited to, those in the following table. For a list of common error codes, see Common HRESULT Values.

RET URN C O DE/ VA L UE DESC RIP T IO N

The private key cannot be found, or the ICspInformation

CERTSRV_E_PROPERTY_EMPTY object associated with the private key cannot be found.

The object is not initialized.

OLE_E_BL ANK

Remarks
The IsSmar tCard method first checks the provider associated with the private key. If that provider is not for a
smart card, the method iterates through the CspStatuses collection until it finds a selected provider that is. If no
selected smart card providers are found, the method returns False . You must initialize the
IX509CertificateRequestPkcs10 object before calling this method. For more information, see any of the following
methods:
InitializeDecode
InitializeFromCertificate
InitializeFromPrivateKey
InitializeFromPublicKey
InitializeFromTemplateName
Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509CertificateRequestPkcs10
 IX509CertificateRequestPkcs10::put_KeyContainerNamePrefix
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The KeyContainerNamePrefix property specifies or retrieves a prefix used to create the container name for a
new private key.
This property is read/write.

Syntax
HRESULT put_KeyContainerNamePrefix(
BSTR Value
);

Parameters
Value

Return value
None

Remarks
Each CryptoAPI cryptographic service provider or Cryptography API: Next Generation (CNG) key provider
maintains a key container for the private key. To retrieve the name of a key container for an existing key, use the
ContainerName property of the IX509PrivateKey object.
A prefix can contain any string limited to the maximum length of the key container name and to legal container
name characters. For example, if you do not call the ContainerName property to specify a key container name,
one is automatically created when the private key is created, and the prefix to the container name will be the
string "lp". For another example, if you are creating a test harness and want to differentiate key containers by the
programs that generated them, you can use the name of the executable as the prefix.
You must set this property before calling the Encode method, and you must initialize the
IX509CertificateRequestPkcs10 object before calling this property. For more information, see any of the
following methods:
InitializeDecode
InitializeFromCertificate
InitializeFromPrivateKey
InitializeFromPublicKey
InitializeFromTemplateName

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]
 Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509CertificateRequestPkcs10
 IX509CertificateRequestPkcs10::put_SmimeCapabilities
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The SmimeCapabilities property specifies or retrieves a Boolean value that tells the Encode method whether
to create an IX509ExtensionSmimeCapabilities collection that identifies the encryption capabilities supported by
the computer. This property is web enabled for both input and output.
This property is read/write.

Syntax
HRESULT put_SmimeCapabilities(
VARIANT_BOOL Value
);

Parameters
Value

Return value
None

Remarks
Multipurpose Internet Mail Extensions (MIME) is a specification for formatting binary data into text so that it can
be sent in email. Secure/Multipurpose Internet Mail Extensions (S/MIME) is a standard for encrypting and
signing a MIME message.
The SmimeCapabilities extension, represented by an IX509ExtensionSmimeCapabilities object, is used when
sending and receiving encrypted email messages to report the recipient's decryption capabilities to the sender.
This enables the sender to choose the most secure algorithm supported by both the sender and recipient.
If you did not set the SuppressDefaults property before calling the Encode method, the SmimeCapabilities
extension is added by default and the available symmetric algorithm OIDs are enumerated and added to the
extension value. Set the SmimeCapabilities property before calling Encode .

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

 Header certenroll.h

DLL CertEnroll.dll

See also
IX509CertificateRequestPkcs10
 IX509CertificateRequestPkcs10::put_Subject method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Subject property specifies or retrieves the X.500 distinguished name of the entity requesting the certificate.
This property is web enabled for both input and output.
This property is read/write.

Syntax
HRESULT put_Subject(
IX500DistinguishedName *pValue
);

Parameters
pValue

Return value
None

Remarks
You must set this property before calling the Encode method, and you must initialize the
IX509CertificateRequestPkcs10 object before calling this property. For more information, see any of the
following methods:
InitializeDecode
InitializeFromCertificate
InitializeFromPrivateKey
InitializeFromPublicKey
InitializeFromTemplateName

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h
 DLL CertEnroll.dll

See also
IX509CertificateRequestPkcs10
 IX509CertificateRequestPkcs10V2 interface
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The IX509Cer tificateRequestPkcs10V2 interface represents a PKCS #10 certificate request. It includes all of
the methods defined by the IX509CertificateRequestPkcs10 interface and adds methods that enable initialization
from certificate request templates.

Inheritance
The IX509Cer tificateRequestPkcs10V2 interface inherits from IX509CertificateRequestPkcs10.
IX509Cer tificateRequestPkcs10V2 also has these types of members:

Methods
The IX509Cer tificateRequestPkcs10V2 interface has these methods.

IX509CertificateRequestPkcs10V2::get_PolicyServer

Retrieves the certificate enrollment policy (CEP) server that contains the template used during initialization.

IX509CertificateRequestPkcs10V2::get_Template

Retrieves the certificate request template used during initialization.

IX509CertificateRequestPkcs10V2::InitializeFromPrivateKeyTemplate

Initializes the certificate request by using an IX509PrivateKey object and a certificate template.

IX509CertificateRequestPkcs10V2::InitializeFromPublicKeyTemplate

Initializes a null-signed certificate request by using an IX509PublicKey object and a template.

IX509CertificateRequestPkcs10V2::InitializeFromTemplate

Initializes the certificate request by using a template.

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Target Platform Windows

Header certenroll.h
 IX509CertificateRequestPkcs10V2::get_PolicyServer
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The PolicySer ver property retrieves the certificate enrollment policy (CEP) server that contains the template
used during initialization.
This property is read-only.

Syntax
HRESULT get_PolicyServer(
IX509EnrollmentPolicyServer **ppPolicyServer
);

Parameters
ppPolicyServer

Return value
None

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Target Platform Windows

Header certenroll.h

See also
IX509CertificateRequestPkcs10V2
 IX509CertificateRequestPkcs10V2::get_Template
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Template property retrieves the certificate request template used during initialization.
This property is read-only.

Syntax
HRESULT get_Template(
IX509CertificateTemplate **ppTemplate
);

Parameters
ppTemplate

Return value
None

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Target Platform Windows

Header certenroll.h

See also
IX509CertificateRequestPkcs10V2
 IX509CertificateRequestPkcs10V2::InitializeFromPrivateKeyTemplate
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The InitializeFromPrivateKeyTemplate method initializes the certificate request by using an IX509PrivateKey

object and a certificate template.

Syntax
HRESULT InitializeFromPrivateKeyTemplate(
[in] X509CertificateEnrollmentContext Context,
[in] IX509PrivateKey *pPrivateKey,
[in] IX509EnrollmentPolicyServer *pPolicyServer,
[in] IX509CertificateTemplate *pTemplate
);

Parameters
[in] Context

An X509CertificateEnrollmentContext enumeration value that specifies whether the requested certificate is

intended for an end user, a computer, or an administrator acting on behalf of the computer. This can be one of
the following values. However, if the MachineContext property of the private key is set, you must specify the
ContextMachine enumeration value.

VA L UE M EA N IN G

The certificate is being requested for an end user.

ContextUser

The certificate is being requested for a computer.

ContextMachine

The certificate is being requested by an administrator acting

ContextAdministratorForceMachine on the behalf of a computer.

[in] pPrivateKey

Pointer to an IX509PrivateKey interface that represents the private key.

[in] pPolicyServer

Pointer to an IX509EnrollmentPolicyServer object that represents the certificate enrollment policy (CEP) server
that contains the template specified by the pTemplate parameter.
[in] pTemplate

Pointer to an IX509CertificateTemplate object that represents the template to use during initialization.

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. Possible values include, but are not
limited to, those in the following table. For a list of common error codes, see Common HRESULT Values.

RET URN C O DE DESC RIP T IO N

 The pPrivateKey, pPolicyServer, or pTemplate parameters are
E_POINTER NULL .

The certificate request object has already been initialized.

HRESULT_FROM_WIN32(ERROR_ALREADY_INITIALIZE
D)

Remarks
The InitializeFromPrivateKeyTemplate method performs the following actions:
Adds the extensions specified by the template to an IX509Extensions collection.
Creates an IObjectIds collection and populates it with the default XCN_OID_KEY_USAGE and
XCN_OID_BASIC_CONSTRAINTS2 object identifiers. If the template indicates that these OIDs are not critical,
they are removed from the collection. The OIDs marked critical by the template are added.
Sets the SmimeCapabilities property if the template supports symmetric algorithms.
Sets the AlternateSignatureAlgorithm property if the template requires a discrete signature algorithm OID.
Creates an IX509SignatureInformation object.
Creates a hash algorithm OID if the algorithm is specified in the template and sets it on the
IX509SignatureInformation object.
Retrieves an asymmetric encryption algorithm OID, if it exists, from the template and sets it on the
IX509SignatureInformation object.
Populates many of the IX509PrivateKey properties from the template settings.
If the CSPInformations property is not specified, the method creates an ICspInformations collection from the
providers installed on the computer.
No private key is created at this point. If the IX509PrivateKey object passed to the method does not represent an
existing key, a key is created when the Encode method is called. The key will be created by using the default
provider if no template was specified and the ProviderName property on the IX509PrivateKey is not set. When
a private key exists, it is set on the PrivateKey property.

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Target Platform Windows

Header certenroll.h

See also
IX509CertificateRequestPkcs10V2
 IX509CertificateRequestPkcs10V2::InitializeFromPublicKeyTemplate
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The InitializeFromPublicKeyTemplate method initializes a null-signed certificate request by using an

IX509PublicKey object and a template.

Syntax
HRESULT InitializeFromPublicKeyTemplate(
[in] X509CertificateEnrollmentContext Context,
[in] IX509PublicKey *pPublicKey,
[in] IX509EnrollmentPolicyServer *pPolicyServer,
[in] IX509CertificateTemplate *pTemplate
);

Parameters
[in] Context

An X509CertificateEnrollmentContext enumeration value that specifies whether the requested certificate is

intended for an end user, a computer, or an administrator acting on behalf of the computer. This can be one of
the following values.

VA L UE M EA N IN G

The certificate is being requested for an end user.

ContextUser

The certificate is being requested for a computer.

ContextMachine

The certificate is being requested by an administrator acting

ContextAdministratorForceMachine on the behalf of a computer.

[in] pPublicKey

Pointer to an IX509PublicKey interface that represents the public key.

[in] pPolicyServer

Pointer to an IX509EnrollmentPolicyServer object that represents the certificate enrollment policy (CEP) server
that contains the template specified by the pTemplate parameter.
[in] pTemplate

Pointer to an IX509CertificateTemplate object that represents the template to use during initialization.

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. Possible values include, but are not
limited to, those in the following table. For a list of common error codes, see Common HRESULT Values.

RET URN C O DE/ VA L UE DESC RIP T IO N

The pPublicKey, pPolicyServer, or pTemplate parameters are

E_POINTER NULL .
 The certificate request object has already been initialized.
HRESULT_FROM_WIN32(ERROR_ALREADY_INITIALIZE
D)

Remarks
The InitializeFromPublicKeyTemplate method performs the following actions:
Adds the extensions specified in the template, if any, to the IX509Extensions collection.
Creates a CriticalExtensions collection and populates it with the default XCN_OID_KEY_USAGE and
XCN_OID_BASIC_CONSTRAINTS2 object identifiers. If the template indicates that these OIDs are not critical,
they are removed from the collection. The OIDs marked critical by the template, if any, are added.
Sets the SmimeCapabilities property if the template supports symmetric algorithms.
Sets the AlternateSignatureAlgorithm property if the template requires a discrete signature algorithm OID.
Creates an IX509SignatureInformation object.
Creates a hash algorithm OID if the algorithm is specified in the template and sets it on the
IX509SignatureInformation object.
Creates an asymmetric encryption algorithm OID if the algorithm is specified in the template and sets it on
the IX509SignatureInformation object.
If the CSPInformations property is not specified, the method creates an ICspInformations collection from the
providers installed on the computer.
The method does not create a private key. The use of this method implies that the request is null-signed.
Therefore, the method sets the NullSigned property on the IX509SignatureInformation object.

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Target Platform Windows

Header certenroll.h

See also
IX509CertificateRequestPkcs10V2
 IX509CertificateRequestPkcs10V2::InitializeFromTemplate
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The InitializeFromTemplate method initializes the certificate request by using a template.

Syntax
HRESULT InitializeFromTemplate(
[in] X509CertificateEnrollmentContext context,
[in] IX509EnrollmentPolicyServer *pPolicyServer,
[in] IX509CertificateTemplate *pTemplate
);

Parameters
[in] context

An X509CertificateEnrollmentContext enumeration value that specifies whether the requested certificate is

intended for an end user, a computer, or administrator acting on behalf of the computer. This can be one of the
following values.

VA L UE M EA N IN G

The certificate is being requested for an end user.

ContextUser

The certificate is being requested for a computer.

ContextMachine

The certificate is being requested by an administrator acting

ContextAdministratorForceMachine on the behalf of a computer.

[in] pPolicyServer

Pointer to an IX509EnrollmentPolicyServer object that represents the certificate enrollment policy (CEP) server
that contains the template specified by the pTemplate parameter.
[in] pTemplate

Pointer to an IX509CertificateTemplate object that represents the template to use during initialization.

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. Possible values include, but are not
limited to, those in the following table. For a list of common error codes, see Common HRESULT Values.

RET URN C O DE DESC RIP T IO N

 The pPolicyServer or pTemplate parameters are NULL .
E_POINTER

The certificate request object has already been initialized.

HRESULT_FROM_WIN32(ERROR_ALREADY_INITIALIZE
D)

Remarks
The InitializeFromTemplate method creates the following collections:
An ICryptAttributes collection.
An IX509Extensions collection.
An IObjectIds collection populated with the default XCN_OID_KEY_USAGE and
XCN_OID_BASIC_CONSTRAINTS2 object identifiers.
An empty IObjectIds collection for attribute and extension OIDs to be suppressed from the new request.
The method then examines the template and performs the following actions:
Adds the extensions specified by the template to the IX509Extensions collection.
Removes the default critical extensions (XCN_OID_KEY_USAGE and XCN_OID_BASIC_CONSTRAINTS2) from
the collection if the template indicates that they are not critical. The OIDs marked critical by the template are
added.
Sets the SmimeCapabilities property if the template supports symmetric algorithms.
Sets the AlternateSignatureAlgorithm property if the template requires a discrete signature algorithm OID.
Creates an IX509SignatureInformation object.
Creates a hash algorithm OID if the algorithm is specified in the template and sets it on the
IX509SignatureInformation object.
Creates an asymmetric encryption algorithm OID if the algorithm is specified in the template and sets it on
the IX509SignatureInformation object.
Populates many of the IX509PrivateKey properties from the template settings.
If the CSPInformations property is NULL , the method creates an ICspInformations collection from the providers
installed on the computer.

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Target Platform Windows

Header certenroll.h

See also
IX509CertificateRequestPkcs10V2
 IX509CertificateRequestPkcs10V3 interface
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The IX509Cer tificateRequestPkcs10V3 interface represents a PKCS #10 certificate request. It includes all of
the methods defined by the IX509CertificateRequestPkcs10 and IX509CertificateRequestPkcs10V2 interfaces
and adds properties that enable TPM certificate attestation.

Inheritance
The IX509CertificateRequestPkcs10V3 interface inherits from the IX509CertificateRequestPkcs10V2 interface.

Methods
The IX509Cer tificateRequestPkcs10V3 interface has these methods.

IX509CertificateRequestPkcs10V3::get_AttestationEncryptionCertificate

The certificate used to encrypt the EKPUB and EKCERT values from the client. This property must be set to a valid certificate
that chains to a trusted machine root.

IX509CertificateRequestPkcs10V3::get_AttestPrivateKey

True if the created private key needs to be attested; otherwise false. If true, it is expected that the
AttestationEncryptionCertificate property has been set.

IX509CertificateRequestPkcs10V3::get_ChallengePassword

The password to use when creating a request with a challenge. To create a request without a challenge, do not set the
ChallengePassword property.

IX509CertificateRequestPkcs10V3::get_EncryptionAlgorithm

The encryption algorithm used to encrypt the EKPUB and EKCERT values from the client.

IX509CertificateRequestPkcs10V3::get_EncryptionStrength

Identifies the bit length for the EncryptionAlgorithm to use for encryption. If the EncryptionAlgorithm only supports one bit
length, then you do not need to specify a value for the EncryptionStrength property.

IX509CertificateRequestPkcs10V3::get_NameValuePairs

A collection of name/value pairs of additional certificate property values.

IX509CertificateRequestPkcs10V3::put_AttestationEncryptionCertificate

The certificate used to encrypt the EKPUB and EKCERT values from the client. This property must be set to a valid certificate
that chains to a trusted machine root.
 IX509CertificateRequestPkcs10V3::put_AttestPrivateKey

True if the created private key needs to be attested; otherwise false. If true, it is expected that the
AttestationEncryptionCertificate property has been set.

IX509CertificateRequestPkcs10V3::put_ChallengePassword

The password to use when creating a request with a challenge. To create a request without a challenge, do not set the
ChallengePassword property.

IX509CertificateRequestPkcs10V3::put_EncryptionAlgorithm

The encryption algorithm used to encrypt the EKPUB and EKCERT values from the client.

IX509CertificateRequestPkcs10V3::put_EncryptionStrength

Identifies the bit length for the EncryptionAlgorithm to use for encryption. If the EncryptionAlgorithm only supports one bit
length, then you do not need to specify a value for the EncryptionStrength property.

Requirements

Target Platform Windows

Header certenroll.h
 IX509CertificateRequestPkcs10V3::get_AttestationEncryptionCertificate
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The certificate used to encrypt the EKPUB and EKCERT values from the client. This property must be set to a valid
certificate that chains to a trusted machine root.
This property is read/write.

Syntax
HRESULT get_AttestationEncryptionCertificate(
EncodingType Encoding,
BSTR *pValue
);

Parameters
Encoding

pValue

Return value
None

Requirements

Target Platform Windows

Header certenroll.h

DLL Certenroll.dll

See also
IX509CertificateRequestPkcs10V3
 IX509CertificateRequestPkcs10V3::get_AttestPrivateKey
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

True if the created private key needs to be attested; otherwise false. If true, it is expected that the
AttestationEncryptionCertificate property has been set.
This property is read/write.

Syntax
HRESULT get_AttestPrivateKey(
VARIANT_BOOL *pValue
);

Parameters
pValue

Return value
None

Requirements

Target Platform Windows

Header certenroll.h

DLL Certenroll.dll

See also
IX509CertificateRequestPkcs10V3
 IX509CertificateRequestPkcs10V3::get_ChallengePassword
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The password to use when creating a request with a challenge. To create a request without a challenge, do not
set the ChallengePassword property.
This property is read/write.

Syntax
HRESULT get_ChallengePassword(
BSTR *pValue
);

Parameters
pValue

Return value
None

Requirements

Target Platform Windows

Header certenroll.h

DLL Certenroll.dll

See also
IX509CertificateRequestPkcs10V3
 IX509CertificateRequestPkcs10V3::get_EncryptionAlgorithm
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The encryption algorithm used to encrypt the EKPUB and EKCERT values from the client.
This property is read/write.

Syntax
HRESULT get_EncryptionAlgorithm(
IObjectId **ppValue
);

Parameters
ppValue

Return value
None

Requirements

Target Platform Windows

Header certenroll.h

DLL Certenroll.dll

See also
IX509CertificateRequestPkcs10V3
 IX509CertificateRequestPkcs10V3::get_EncryptionStrength
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

Identifies the bit length for the EncryptionAlgorithm to use for encryption. If the Encr yptionAlgorithm only
supports one bit length, then you do not need to specify a value for the Encr yptionStrength property.
This property is read/write.

Syntax
HRESULT get_EncryptionStrength(
LONG *pValue
);

Parameters
pValue

Return value
None

Requirements

Target Platform Windows

Header certenroll.h

DLL Certenroll.dll

See also
IX509CertificateRequestPkcs10V3
 IX509CertificateRequestPkcs10V3::get_NameValuePairs
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

A collection of name/value pairs of additional certificate property values.

This property is read-only.

Syntax
HRESULT get_NameValuePairs(
IX509NameValuePairs **ppValue
);

Parameters
ppValue

Return value
None

Requirements

Target Platform Windows

Header certenroll.h

DLL Certenroll.dll

See also
IX509CertificateRequestPkcs10V3
 IX509CertificateRequestPkcs10V3::put_AttestationEncryptionCertificate
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The certificate used to encrypt the EKPUB and EKCERT values from the client. This property must be set to a valid
certificate that chains to a trusted machine root.
This property is read/write.

Syntax
HRESULT put_AttestationEncryptionCertificate(
EncodingType Encoding,
BSTR Value
);

Parameters
Encoding

Value

Return value
None

Requirements

Target Platform Windows

Header certenroll.h

DLL Certenroll.dll

See also
IX509CertificateRequestPkcs10V3
 IX509CertificateRequestPkcs10V3::put_AttestPrivateKey
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

True if the created private key needs to be attested; otherwise false. If true, it is expected that the
AttestationEncryptionCertificate property has been set.
This property is read/write.

Syntax
HRESULT put_AttestPrivateKey(
VARIANT_BOOL Value
);

Parameters
Value

Return value
None

Requirements

Target Platform Windows

Header certenroll.h

DLL Certenroll.dll

See also
IX509CertificateRequestPkcs10V3
 IX509CertificateRequestPkcs10V3::put_ChallengePassword
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The password to use when creating a request with a challenge. To create a request without a challenge, do not
set the ChallengePassword property.
This property is read/write.

Syntax
HRESULT put_ChallengePassword(
BSTR Value
);

Parameters
Value

Return value
None

Requirements

Target Platform Windows

Header certenroll.h

DLL Certenroll.dll

See also
IX509CertificateRequestPkcs10V3
 IX509CertificateRequestPkcs10V3::put_EncryptionAlgorithm
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The encryption algorithm used to encrypt the EKPUB and EKCERT values from the client.
This property is read/write.

Syntax
HRESULT put_EncryptionAlgorithm(
IObjectId *pValue
);

Parameters
pValue

Return value
None

Requirements

Target Platform Windows

Header certenroll.h

DLL Certenroll.dll

See also
IX509CertificateRequestPkcs10V3
 IX509CertificateRequestPkcs10V3::put_EncryptionStrength
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

Identifies the bit length for the EncryptionAlgorithm to use for encryption. If the Encr yptionAlgorithm only
supports one bit length, then you do not need to specify a value for the Encr yptionStrength property.
This property is read/write.

Syntax
HRESULT put_EncryptionStrength(
LONG Value
);

Parameters
Value

Return value
None

Requirements

Target Platform Windows

Header certenroll.h

DLL Certenroll.dll

See also
IX509CertificateRequestPkcs10V3
 IX509CertificateRequestPkcs7 interface (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The IX509Cer tificateRequestPkcs7 interface represents a PKCS #7 certificate message syntax (CMS) object.
PKCS #7 defines the format of messages sent to a certification or registration authority to request a public-key
certificate. The IX509Cer tificateRequestPkcs7 interface can be confusing because its implementation does
not perfectly mirror the way most security professionals think about the PKCS #7 standard. To avoid this
confusion, keep the following points in mind:
Although a PKCS #7 message is used to wrap a CMC request, an IX509Cer tificateRequestPkcs7 object
cannot contain a IX509CertificateRequestCmc object. Instead, the IX509Cer tificateRequestCmc interface
inherits and implements the IX509Cer tificateRequestPkcs7 interface. As implemented, a CMC request is
therefore a PKCS #7 SignedData object that contains CMC content, a primary signature that is either null-
signed or key-based, and zero or more certificate-based signatures. By contrast, a PKCS #7 request is a
SignedData object that contains PKCS #10 content (see the next item in this list) and has exactly one
certificate-based signature.
An IX509Cer tificateRequestPkcs7 must contain an IX509CertificateRequestPkcs10 object. The main
advantage of wrapping a PKCS #10 request in a PKCS #7 message is the ability to add multiple signers. The
PKCS #10 request is signed by the associated private key, and the PKCS #7 message that wraps the PKCS #10
request is also signed. This second signer uses the certificate being renewed (for a renewal request) or the
enrollment agent certificate (for an enroll-on-behalf-of request).
You can create and enroll a stand-alone IX509CertificateRequestPkcs10 certificate request without wrapping
it in an IX509Cer tificateRequestPkcs7 object.
The ASN.1 representation of a PKCS #7 object in the following syntax example shows that it can be composed of
a variety of data types.

PKCS7ContentTable PKCS7-CONTENT-TYPE ::=

{
data | signed-data | enveloped-data | signed-and-enveloped-data |
digested-data | encrypted-data | authenticated-data, ...
}

Of these, the SignedData object shown below is most relevant. The SignerInfo object referenced in the
SignedData object contains the signature information. For a more complete discussion, see PKCS #7 Attributes.
 -------------------------------------------------------------------
-- signed-data
-------------------------------------------------------------------

SignedData ::= SEQUENCE

{
version INTEGER,
digestAlgorithms DigestAlgorithmIdentifiers,
contentInfo ContentInfo,
certificates [0] IMPLICIT Certificates OPTIONAL,
crls [1] IMPLICIT CertificateRevocationLists OPTIONAL,
signerInfos SignerInfos
}

SignerInfo ::= SEQUENCE

{
version INTEGER,
sid CertIdentifier,
digestAlgorithm DigestAlgorithmIdentifier,
authenticatedAttributes [0] IMPLICIT Attributes OPTIONAL,
signatureAlgorithm SignatureAlgorithmIdentifier,
signature SignatureValue,
unauthenticatedAttributes [1] IMPLICIT Attributes
}

Inheritance
The IX509Cer tificateRequestPkcs7 interface inherits from IX509CertificateRequest.
IX509Cer tificateRequestPkcs7 also has these types of members:

Methods
The IX509Cer tificateRequestPkcs7 interface has these methods.

IX509CertificateRequestPkcs7::get_RequesterName

Specifies or retrieves a string that contains the Security Account Manager (SAM) name of the end-entity requesting the
certificate.

IX509CertificateRequestPkcs7::get_SignerCertificate

Specifies or retrieves a certificate used to sign the certificate request.

IX509CertificateRequestPkcs7::InitializeDecode

Decodes an existing signed or unsigned PKCS

IX509CertificateRequestPkcs7::InitializeFromCertificate

Initializes the certificate request by using an existing certificate.

IX509CertificateRequestPkcs7::InitializeFromInnerRequest

Initializes the certificate request from the inner PKCS

 IX509CertificateRequestPkcs7::InitializeFromTemplateName

Initializes the certificate request by using a template.

IX509CertificateRequestPkcs7::put_RequesterName

Specifies or retrieves a string that contains the Security Account Manager (SAM) name of the end-entity requesting the
certificate.

IX509CertificateRequestPkcs7::put_SignerCertificate

Specifies or retrieves a certificate used to sign the certificate request.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

See also
CertEnroll Interfaces
IX509CertificateRequest
 IX509CertificateRequestPkcs7::get_RequesterName
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The RequesterName property specifies or retrieves a string that contains the Security Account Manager (SAM)
name of the end-entity requesting the certificate. This property is web enabled for both input and output.
This property is read/write.

Syntax
HRESULT get_RequesterName(
BSTR *pValue
);

Parameters
pValue

Return value
None

Remarks
This property is only used when the enrollment agent is enrolling on behalf of another user. You must initialize
the PKCS #7 request object before calling this property. For more information, see the following topics:
Initialize
InitializeDecode
InitializeFromCertificate
InitializeFromInnerRequest
InitializeFromTemplateName

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll
See also
IX509CertificateRequestPkcs7
 IX509CertificateRequestPkcs7::get_SignerCertificate
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The SignerCer tificate property specifies or retrieves a certificate used to sign the certificate request.
This property is read/write.

Syntax
HRESULT get_SignerCertificate(
ISignerCertificate **ppValue
);

Parameters
ppValue

Return value
None

Remarks
You must initialize the PKCS #7 request object before calling this property. For more information, see the
following topics:
Initialize
InitializeDecode
InitializeFromCertificate
InitializeFromInnerRequest
InitializeFromTemplateName

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll
See also
IX509CertificateRequestPkcs7
 IX509CertificateRequestPkcs7::InitializeDecode
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The InitializeDecode method decodes an existing signed or unsigned PKCS #7 request object and uses it to
initialize the new PKCS #7 object. The existing request is contained in a byte array that has been encoded by
using Distinguished Encoding Rules (DER) as defined by the Abstract Syntax Notation One (ASN.1) standard. The
byte array is represented by a string that is either a pure binary sequence or is Unicode encoded.

Syntax
HRESULT InitializeDecode(
[in] BSTR strEncodedData,
[in] EncodingType Encoding
);

Parameters
[in] strEncodedData

A BSTR variable that contains the DER-encoded request.

[in] Encoding

An EncodingType enumeration value that specifies the type of Unicode encoding applied to the input string that
contains the DER-encoded request. The default value is XCN_CRYPT_STRING_BASE64 .

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. Possible values include, but are not
limited to, those in the following table. For a list of common error codes, see Common HRESULT Values.

RET URN C O DE/ VA L UE DESC RIP T IO N

The request object has already been initialized.

HRESULT_FROM_WIN32(ERROR_ALREADY_INITIALIZE
D)

Remarks
The InitializeDecode method:
Decodes the PKCS #7 request specified on input.
Uses the decoded object to create an inner PKCS #10 request with the following collections:
An empty ICryptAttributes collection.
An empty IX509Extensions collection.
An empty IObjectIds collection for critical extensions.
 An empty IObjectIds collection for attribute and extension OIDs to be suppressed from the new
request.
Adds the decoded extensions to the IX509Extensions collection.
Adds the decoded attributes to the ICryptAttributes collection
Sets the ClientId property.
Sets the TemplateObjectId property.
Uses the signature on the original PKCS #7 request to create a new ISignerCertificate object.
Retrieves an IX509SignatureInformation object from the ISignerCertificate object.
Initializes the new IX509SignatureInformation object by using the original signature and hash algorithms.
Sets the PKCS #10 request as the inner request object.
By default, the InitializeDecode method assumes that the certificate request to be decoded is for an end user.
Beginning with Windows 8 and Windows Server 2012, you can change this default behavior. After creating an
instance of the IX509CertificateRequestPkcs7 interface, call InitializeDecode by setting the Encoding
parameter to XCN_CRYPT_STRING_BINARY and the strEncodedData parameter to one of the following
values:

VA L UE DESC RIP T IO N

L"ContextMachine" The encoded certificate request is for a computer.

L"ContextUser" The encoded certificate request is for an end user.

L"ContextAdministratorForceMachine" The encoded certificate is being requested by an

administrator acting on the behalf of a computer.

Then, call the InitializeDecode method again with the encoded certificate set in the strEncodedData argument.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509CertificateRequestPkcs7
 IX509CertificateRequestPkcs7::InitializeFromCertificate
method (certenroll.h)
7/2/2022 • 3 minutes to read • Edit Online

The InitializeFromCer tificate method initializes the certificate request by using an existing certificate. The
certificate is contained in a byte array encoded by using Distinguished Encoding Rules (DER) as defined by the
Abstract Syntax Notation One (ASN.1) standard. The DER-encoded byte array is represented by a string that is
either a pure binary sequence or is Unicode encoded.

Syntax
HRESULT InitializeFromCertificate(
[in] X509CertificateEnrollmentContext Context,
[in] VARIANT_BOOL RenewalRequest,
[in] BSTR strCertificate,
[in] EncodingType Encoding,
[in] X509RequestInheritOptions InheritOptions
);

Parameters
[in] Context

An X509CertificateEnrollmentContext enumeration value that specifies whether the requested certificate is

intended for an end user, a computer, or an administrator acting on behalf of the computer.
[in] RenewalRequest

A VARIANT_BOOL that indicates whether the end entity is requesting that the certificate identified by the
strCertificate parameter be renewed.
[in] strCertificate

A BSTR variable that contains the DER-encoded certificate.

Beginning with Windows 7 and Windows Server 2008 R2, you can specify a certificate thumb print or serial
number rather than an encoded certificate. Doing so causes the function to search the appropriate local stores
for the matching certificate. Keep in mind the following points:
The BSTR must be an even number of hexadecimal digits.
Whitespace between hexadecimal pairs is ignored.
The Encoding parameter must be set to XCN_CRYPT_STRING_HEXRAW .
The Context parameter determines whether the local or computer stores or both are searched.
If a private key is needed, only the personal and request stores are searched.
If a private key is not needed, the root and intermediate CA stores are also searched.
[in] Encoding

An EncodingType enumeration value that specifies the type of encoding applied to the DER-encoded certificate.
The default value is XCN_CRYPT_STRING_BASE64 .
[in] InheritOptions
An X509RequestInheritOptions enumeration value that specifies how to create the certificate request object
from the existing certificate. You can specify how to inherit a key by choosing one of the following values. The
default value is InheritDefault .

VA L UE M EA N IN G

Provider and key inheritance is not specified.

InheritDefault

Creates a new key but inherits the default cryptographic

InheritNewDefaultKey provider.

Creates a new key but inherits the cryptographic provider

InheritNewSimilarKey used to create the existing certificate.

Inherits the private and public keys.

InheritPrivateKey

Inherits only the public key.

InheritPublicKey

You can also use a bitwise-AND operation to combine the key inheritance value with any combination of the
following values.

VA L UE M EA N IN G

Inherits the renewal certificate. Specifying this flag sets an

InheritRenewalCer tificateFlag ICertPropertyRenewal value.

Inherits the certificate template.

InheritTemplateFlag

Inherits the subject distinguished name.

InheritSubjectFlag

Inherits the relevant extensions from the certificate.

InheritExtensionsFlag

Inherits the SubjectAlternativeName extension.

InheritSubjectAltNameFlag

Inherits the validity period.

InheritValidityPeriodFlag

You can also specify InheritNone to prevent any of the flags in the preceding table (flags not related to key
inheritance) from being implemented by default. If you specify InheritNone but also specify a flag not related
to key inheritance, the method returns E_INVALIDARG .
If you set the InheritOptions parameter to zero (0) or specify InheritDefault and do not specify a key
inheritance value, InheritNewSimilarKey is used by default.
If you set the InheritOptions parameter to zero (0) or specify InheritDefault and do not specify any of the
values not related to key inheritance, the following flags are set by default:
InheritSubjectFlag
InheritExtensionsFlag
InheritValidityPeriodFlag
InheritTemplateFlag (if the certificate contains a template extension)
InheritRenewalCer tificateFlag (if the client is renewing a certificate)

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. Possible values include, but are not
limited to, those in the following table. For a list of common error codes, see Common HRESULT Values.

RET URN C O DE DESC RIP T IO N

The certificate request object has already been initialized.

ERROR_ALREADY_INITIALIZED

Remarks
The InitializeFromCer tificate method validates the options specified in the InheritOptions parameter and
initializes a new PKCS #7 request object by performing the following actions:
Creates a PKCS #10 request object from the certificate, enrollment context, and inherit options specified on
input. The PKCS #10 object inherits:
The template if one exists in the original certificate and you set the InheritTemplateFlag value.
The subject distinguished name if you specify InheritSubjectFlag .
The subject alternative name if you specify InheritSubjectAltNameFlag .
The extensions if you specify InheritExtensionsFlag .
Copies the original certificate, if it is to be renewed, to the RenewalCertificate property on the new PKCS #10
request.
Creates an ISignerCertificate from the original certificate, if it is to be renewed, and sets it on the
SignerCertificate property.
Sets the PKCS #10 request as the inner request object.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll
See also
IX509CertificateRequestPkcs7
 IX509CertificateRequestPkcs7::InitializeFromInnerRequest
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The InitializeFromInnerRequest method initializes the certificate request from the inner PKCS #10 object.
This method is web enabled.

Syntax
HRESULT InitializeFromInnerRequest(
[in] IX509CertificateRequest *pInnerRequest
);

Parameters
[in] pInnerRequest

Pointer to an IX509CertificateRequest interface that represents the request.

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. Possible values include, but are not
limited to, those in the following table. For a list of common error codes, see Common HRESULT Values.

RET URN C O DE/ VA L UE DESC RIP T IO N

The request object specified on input is not a PKCS #10

CRYPT_E_INVALID_MSG_TYPE request.

The request object has already been initialized.

HRESULT_FROM_WIN32(ERROR_ALREADY_INITIALIZE
D)

Remarks
This method sets the inner request object to the PKCS #10 request specified on input.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

 Header certenroll.h

DLL CertEnroll.dll

See also
IX509CertificateRequestPkcs7
 IX509CertificateRequestPkcs7::InitializeFromTemplateName
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The InitializeFromTemplateName method initializes the certificate request by using a template.

Syntax
HRESULT InitializeFromTemplateName(
[in] X509CertificateEnrollmentContext Context,
[in] BSTR strTemplateName
);

Parameters
[in] Context

An X509CertificateEnrollmentContext enumeration value that specifies whether the requested certificate is

intended for an end user, a computer, or an administrator acting on behalf of the computer.
[in] strTemplateName

A BSTR variable that contains the Common Name (CN) of the template as it appears in Active Directory or the
dotted decimal object identifier.

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. Possible values include, but are not
limited to, those in the following table. For a list of common error codes, see Common HRESULT Values.

RET URN C O DE/ VA L UE DESC RIP T IO N

The certificate request object has already been initialized.

ERROR_ALREADY_INITIALIZED

Remarks
The InitializeFromTemplateName method creates a PKCS #7 request object and sets the following properties
to the values that existed before this method was called:
CspInformations
ParentWindow
Silent
UIContextMessage
The method creates the following collections:
An ICryptAttributes collection.
An IX509Extensions collection.
An IObjectIds collection populated with the default XCN_OID_KEY_USAGE and
XCN_OID_BASIC_CONSTRAINTS2 object identifiers.
 An empty IObjectIds collection for attribute and extension OIDs to be suppressed from the new request.
The method then examines the template and performs the following actions:
Adds the extensions specified by the template to the IX509Extensions collection.
Removes the default critical extensions (XCN_OID_KEY_USAGE and XCN_OID_BASIC_CONSTRAINTS2) from
the collection if the template indicates that they are not critical. The OIDs marked critical by the template are
added.
Sets the SmimeCapabilities property if the template supports symmetric algorithms.
Sets the AlternateSignatureAlgorithm property if the template requires a discrete signature algorithm OID.
Creates an IX509SignatureInformation object.
Creates a hash algorithm OID if the algorithm is specified in the template and sets it on the
IX509SignatureInformation object.
Creates an asymmetric encryption algorithm OID if the algorithm is specified in the template and sets it on
the IX509SignatureInformation object.
Sets the following IX509PrivateKey properties from the template settings:
KeySpec
KeyUsage
Length
ExportPolicy
KeyProtection
SecurityDescriptor
Silent
MachineContext
Algorithm
If the CSPInformations property is NULL , the method creates an ICspInformations collection from the providers
installed on the computer.
Finally, the method sets the initialized PKCS #10 request as the inner request object.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509CertificateRequestPkcs7
 IX509CertificateRequestPkcs7::put_RequesterName
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The RequesterName property specifies or retrieves a string that contains the Security Account Manager (SAM)
name of the end-entity requesting the certificate. This property is web enabled for both input and output.
This property is read/write.

Syntax
HRESULT put_RequesterName(
BSTR Value
);

Parameters
Value

Return value
None

Remarks
This property is only used when the enrollment agent is enrolling on behalf of another user. You must initialize
the PKCS #7 request object before calling this property. For more information, see the following topics:
Initialize
InitializeDecode
InitializeFromCertificate
InitializeFromInnerRequest
InitializeFromTemplateName

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll
See also
IX509CertificateRequestPkcs7
 IX509CertificateRequestPkcs7::put_SignerCertificate
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The SignerCer tificate property specifies or retrieves a certificate used to sign the certificate request.
This property is read/write.

Syntax
HRESULT put_SignerCertificate(
ISignerCertificate *pValue
);

Parameters
pValue

Return value
None

Remarks
You must initialize the PKCS #7 request object before calling this property. For more information, see the
following topics:
Initialize
InitializeDecode
InitializeFromCertificate
InitializeFromInnerRequest
InitializeFromTemplateName

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll
See also
IX509CertificateRequestPkcs7
 IX509CertificateRequestPkcs7V2 interface
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The IX509Cer tificateRequestPkcs7V2 interface represents a PKCS #10 certificate request. It includes all of
the methods defined by the IX509CertificateRequestPkcs7 interface and adds a method that enables
initialization from a certificate request template, methods to retrieve the template and certificate enrollment
policy server used during initialization, and a method to verify the certificate signature.

Inheritance
The IX509Cer tificateRequestPkcs7V2 interface inherits from IX509CertificateRequestPkcs7.
IX509Cer tificateRequestPkcs7V2 also has these types of members:

Methods
The IX509Cer tificateRequestPkcs7V2 interface has these methods.

IX509CertificateRequestPkcs7V2::CheckCertificateSignature

Verifies the certificate signature.

IX509CertificateRequestPkcs7V2::get_PolicyServer

Retrieves the certificate enrollment policy (CEP) server that contains the template used during initialization.

IX509CertificateRequestPkcs7V2::get_Template

Retrieves the certificate request template used during initialization.

IX509CertificateRequestPkcs7V2::InitializeFromTemplate

Initializes the certificate request by using a template.

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Target Platform Windows

Header certenroll.h

See also
IX509CertificateRequest
IX509CertificateRequestPkcs7
 IX509CertificateRequestPkcs7V2::CheckCertificateSignature
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The CheckCer tificateSignature method verifies the certificate signature.

Syntax
HRESULT CheckCertificateSignature(
[in] VARIANT_BOOL ValidateCertificateChain
);

Parameters
[in] ValidateCertificateChain

A Boolean value that specifies whether to also verify the certificate chain. This parameter can be NULL .

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. Possible values include, but are not
limited to, those in the following table. For a list of common error codes, see Common HRESULT Values.

RET URN C O DE/ VA L UE DESC RIP T IO N

A signer certificate cannot be found.

CERTSRV_E_PROPERTY_EMPTY

Remarks
A PKCS #7 request has exactly one certificate-based signature.

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Target Platform Windows

Header certenroll.h

See also
IX509CertificateRequestPkcs7V2
 IX509CertificateRequestPkcs7V2::get_PolicyServer
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The PolicySer ver property retrieves the certificate enrollment policy (CEP) server that contains the template
used during initialization.
This property is read-only.

Syntax
HRESULT get_PolicyServer(
IX509EnrollmentPolicyServer **ppPolicyServer
);

Parameters
ppPolicyServer

Return value
None

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Target Platform Windows

Header certenroll.h

See also
IX509CertificateRequestPkcs7V2
 IX509CertificateRequestPkcs7V2::get_Template
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Template property retrieves the certificate request template used during initialization.
This property is read-only.

Syntax
HRESULT get_Template(
IX509CertificateTemplate **ppTemplate
);

Parameters
ppTemplate

Return value
None

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Target Platform Windows

Header certenroll.h

See also
IX509CertificateRequestPkcs7V2
 IX509CertificateRequestPkcs7V2::InitializeFromTemplate
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The InitializeFromTemplate method initializes the certificate request by using a template.

Syntax
HRESULT InitializeFromTemplate(
[in] X509CertificateEnrollmentContext context,
[in] IX509EnrollmentPolicyServer *pPolicyServer,
[in] IX509CertificateTemplate *pTemplate
);

Parameters
[in] context

An X509CertificateEnrollmentContext enumeration value that specifies whether the requested certificate is

intended for an end user, a computer, or an administrator acting on behalf of the computer. This can be one of
the following values.

VA L UE M EA N IN G

The certificate is being requested for an end user.

ContextUser

The certificate is being requested for a computer.

ContextMachine

The certificate is being requested by an administrator acting

ContextAdministratorForceMachine on the behalf of a computer.

[in] pPolicyServer

Pointer to an IX509EnrollmentPolicyServer object that represents the certificate enrollment policy (CEP) server
that contains the template specified by the pTemplate parameter.
[in] pTemplate

Pointer to an IX509CertificateTemplate object that represents the template to use during initialization.

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. Possible values include, but are not
limited to, those in the following table. For a list of common error codes, see Common HRESULT Values.

RET URN C O DE/ VA L UE DESC RIP T IO N

 The pTemplate parameter cannot be NULL .
E_POINTER

The certificate request object has already been initialized.

ERROR_ALREADY_INITIALIZED

Remarks
The InitializeFromTemplate method creates a PKCS #7 request object and sets the following properties to the
values that existed before this method was called:
CspInformations
ParentWindow
Silent
UIContextMessage
The method creates the following collections:
An ICryptAttributes collection.
An IX509Extensions collection.
An IObjectIds collection populated with the default XCN_OID_KEY_USAGE and
XCN_OID_BASIC_CONSTRAINTS2 object identifiers.
An empty IObjectIds collection for attribute and extension OIDs to be suppressed from the new request.
The method then examines the template and performs the following actions:
Adds the extensions specified by the template to the IX509Extensions collection.
Removes the default critical extensions (XCN_OID_KEY_USAGE and XCN_OID_BASIC_CONSTRAINTS2) from
the collection if the template indicates that they are not critical. The OIDs marked critical by the template are
added.
Sets the SmimeCapabilities property if the template supports symmetric algorithms.
Sets the AlternateSignatureAlgorithm property if the template requires a discrete signature algorithm OID.
Creates an IX509SignatureInformation object.
Creates a hash algorithm OID if the algorithm is specified in the template and sets it on the
IX509SignatureInformation object.
Creates an asymmetric encryption algorithm OID if the algorithm is specified in the template and sets it on
the IX509SignatureInformation object.
Populates many of the IX509PrivateKey properties from the template settings.
If the CSPInformations property is NULL , the method creates an ICspInformations collection from the providers
installed on the computer.
Finally, the method sets the initialized PKCS #10 request as the inner request object.

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]
 Target Platform Windows

Header certenroll.h

See also
IX509CertificateRequestPkcs7V2
 IX509CertificateTemplate interface (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The IX509Cer tificateTemplate interface represents a certificate request template. It can be used to initialize an
IX509CertificateTemplateWritable interface.

Inheritance
The IX509CertificateTemplate interface inherits from the IDispatch interface.

Methods
The IX509Cer tificateTemplate interface has these methods.

IX509CertificateTemplate::get_Property

Retrieves a template property value.

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Target Platform Windows

Header certenroll.h
 IX509CertificateTemplate::get_Property method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Proper ty property retrieves a template property value.

This property is read-only.

Syntax
HRESULT get_Property(
EnrollmentTemplateProperty property,
VARIANT *pValue
);

Parameters
property

pValue

Return value
None

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Target Platform Windows

Header certenroll.h

See also
IX509CertificateTemplate
 IX509CertificateTemplates interface (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The IX509Cer tificateTemplates interface defines the following methods and properties that manage a
collection of IX509CertificateTemplate objects.

Inheritance
The IX509Cer tificateTemplates interface inherits from the IDispatch interface. IX509Cer tificateTemplates
also has these types of members:

Methods
The IX509Cer tificateTemplates interface has these methods.

IX509CertificateTemplates::Add

Adds an IX509CertificateTemplate object to the collection.

IX509CertificateTemplates::Clear

Removes all IX509CertificateTemplate objects from the collection.

IX509CertificateTemplates::get__NewEnum

Retrieves the enumerator for the collection.

IX509CertificateTemplates::get_Count

Retrieves the number of IX509CertificateTemplate objects in the collection.

IX509CertificateTemplates::get_ItemByIndex

Retrieves an IX509CertificateTemplate object from the collection by index number.

IX509CertificateTemplates::get_ItemByName

Retrieves an IX509CertificateTemplate object from the collection by name.

IX509CertificateTemplates::get_ItemByOid

Retrieves an IX509CertificateTemplate object from the collection by object identifier.

IX509CertificateTemplates::Remove

Removes an IX509CertificateTemplate object from the collection by index number.

Requirements
Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Target Platform Windows

Header certenroll.h
 IX509CertificateTemplates::Add method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Add method adds an IX509CertificateTemplate object to the collection. This method is web enabled.

Syntax
HRESULT Add(
[in] IX509CertificateTemplate *pVal
);

Parameters
[in] pVal

Pointer to an IX509CertificateTemplate object to add to the collection.

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Target Platform Windows

Header certenroll.h

See also
IX509CertificateTemplate
IX509CertificateTemplates
 IX509CertificateTemplates::Clear method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Clear method removes all IX509CertificateTemplate objects from the collection.

Syntax
HRESULT Clear();

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Target Platform Windows

Header certenroll.h

See also
IX509CertificateTemplate
IX509CertificateTemplates
 IX509CertificateTemplates::get__NewEnum method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The _NewEnum property retrieves the enumerator for the collection.

This property is read-only.

Syntax
HRESULT get__NewEnum(
LPUNKNOWN *pVal
);

Parameters
pVal

Return value
None

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Target Platform Windows

Header certenroll.h

See also
IX509CertificateTemplate
IX509CertificateTemplates
 IX509CertificateTemplates::get_Count method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Count property retrieves the number of IX509CertificateTemplate objects in the collection. This property is
web enabled.
This property is read-only.

Syntax
HRESULT get_Count(
long *pVal
);

Parameters
pVal

Return value
None

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Target Platform Windows

Header certenroll.h

See also
IX509CertificateTemplate
IX509CertificateTemplates
 IX509CertificateTemplates::get_ItemByName
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The ItemByName property retrieves an IX509CertificateTemplate object from the collection by name. This
property is web enabled.
This property is read-only.

Syntax
HRESULT get_ItemByName(
BSTR bstrName,
IX509CertificateTemplate **ppValue
);

Parameters
bstrName

ppValue

Return value
None

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Target Platform Windows

Header certenroll.h

See also
IX509CertificateTemplate
IX509CertificateTemplates
 IX509CertificateTemplates::get_ItemByOid method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The ItemByOid property retrieves an IX509CertificateTemplate object from the collection by object identifier.
This property is read-only.

Syntax
HRESULT get_ItemByOid(
IObjectId *pOid,
IX509CertificateTemplate **ppValue
);

Parameters
pOid

ppValue

Return value
None

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Target Platform Windows

Header certenroll.h

See also
IX509CertificateTemplate
IX509CertificateTemplates
 IX509CertificateTemplates::Remove method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Remove method removes an IX509CertificateTemplate object from the collection by index number.

Syntax
HRESULT Remove(
[in] LONG Index
);

Parameters
[in] Index

A LONG variable that contains the index of the object to remove.

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Target Platform Windows

Header certenroll.h

See also
IX509CertificateTemplates
 IX509CertificateTemplateWritable interface
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The IX509Cer tificateTemplateWritable interface enables you to add a template to or delete it from a
template store. Currently, Active Directory is the only available store.

Inheritance
The IX509Cer tificateTemplateWritable interface inherits from the IDispatch interface.
IX509Cer tificateTemplateWritable also has these types of members:

Methods
The IX509Cer tificateTemplateWritable interface has these methods.

IX509CertificateTemplateWritable::Commit

Deletes a template from or saves it to Active Directory.

IX509CertificateTemplateWritable::get_Property

Specifies or retrieves a property value for the IX509CertificateTemplateWritable object.

IX509CertificateTemplateWritable::get_Template

Retrieves a copy of the IX509CertificateTemplate object that was used to initialize this IX509CertificateTemplateWritable
instance.

IX509CertificateTemplateWritable::Initialize

Initializes an IX509CertificateTemplateWritable object from a template.

IX509CertificateTemplateWritable::put_Property

Specifies or retrieves a property value for the IX509CertificateTemplateWritable object.

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Target Platform Windows

Header certenroll.h
 IX509CertificateTemplateWritable::Commit method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Commit method deletes a template from or saves it to Active Directory.

Syntax
HRESULT Commit(
[in] CommitTemplateFlags commitFlags,
[in] BSTR strServerContext
);

Parameters
[in] commitFlags

A CommitTemplateFlags enumeration value that specifies how to save or delete the template. This must be one
of the following values.

VA L UE M EA N IN G

Save the template and create an object identifier for it.

CommitFlagSaveTemplateGenerateOID

Not used.
CommitFlagSaveTemplateUseCurrentOID

Not used.
CommitFlagSaveTemplateOver write

Delete the template.

CommitFlagDeleteTemplate

[in] strServerContext

A BSTR variable that contains the DNS name of the Active Directory server to which the changes will be applied.
If this value is NULL , the changes will be applied to the default domain controller.

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. Possible values include, but are not
limited to, those in the following table. For a list of common error codes, see Common HRESULT Values.

RET URN C O DE DESC RIP T IO N

 CommitFlagSaveTemplateGenerateOID was specified in
CRYPT_E_EXISTS the commitFlags argument but a template with a matching
common name or a matching object identifier (OID) already
exists.

CommitFlagDelete was specified in the commitFlags

CRYPT_E_NOT_FOUND argument and a template with the same Common Name
was found but the OID did not match.

The caller does not have the appropriate permission to save

E_ACCESSDEINED or delete a template. The caller must have write and delete
permission on the template container and template objects
in Active Directory. If the caller has delete permission on the
template container and objects but does not have delete
permission on the OID container and objects, the template
will be deleted but the OID will not be.

Either CommitFlagSaveTemplateUseCurrentOID or
E_NOTIMPL CommitFlagSaveTemplateOver write was specified in the
commitFlags argument. These values are not currently used.

CommitFlagDelete was specified in the commitFlags

HRESULT_FROM_WIN32(ERROR_NOT_FOUND) argument but a template having a matching Common Name
(CN) could not be found.

The Commit method is not supported for default templates.

HRESULT_FROM_WIN32(ERROR_NOT_SUPPORTED)

The IX509CertificateTemplateWritable object has not been

OLE_E_BL ANK initialized.

Remarks
When CommitFlagSaveTemplateGenerateOID is specified in the commitFlags argument, this method will
not succeed unless the template and OID containers have already been created. These containers can be created
in any of the following ways:
Installing an enterprise certification authority on the server.
Launching the Certtmpl.msc snap-in.
Using the Cer tutil.exe -installDefaultTemplates command to install the default templates.

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Target Platform Windows

Header certenroll.h
See also
IX509CertificateTemplateWritable
 IX509CertificateTemplateWritable::get_Property
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Proper ty property specifies or retrieves a property value for the IX509CertificateTemplateWritable object.
This property is read/write.

Syntax
HRESULT get_Property(
EnrollmentTemplateProperty property,
VARIANT *pValue
);

Parameters
property

pValue

Return value
None

Remarks
Currently, TemplatePropSecurityDescriptor is the only property that you can set. The property value must be a
VARIANT of type VT_BSTR or VT_BYREF|VT_BSTR and must be a valid SDDL string.

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Target Platform Windows

Header certenroll.h

See also
IX509CertificateTemplateWritable
 IX509CertificateTemplateWritable::get_Template
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Template property retrieves a copy of the IX509CertificateTemplate object that was used to initialize this
IX509CertificateTemplateWritable instance.
This property is read-only.

Syntax
HRESULT get_Template(
IX509CertificateTemplate **ppValue
);

Parameters
ppValue

Return value
None

Remarks
You must call the COM Release method to free the interface pointer when you are finished using it.

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Target Platform Windows

Header certenroll.h

See also
IX509CertificateTemplateWritable
 IX509CertificateTemplateWritable::Initialize method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Initialize method initializes an IX509CertificateTemplateWritable object from a template.

Syntax
HRESULT Initialize(
[in] IX509CertificateTemplate *pValue
);

Parameters
[in] pValue

Pointer to an IX509CertificateTemplate interface that represents a certificate request template.

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. Possible values include, but are not
limited to, those in the following table. For a list of common error codes, see Common HRESULT Values.

RET URN C O DE/ VA L UE DESC RIP T IO N

The pValue parameter cannot be NULL .

E_POINTER

The pValue parameter does not point to an

E_NOINTERFACE IX509CertificateTemplate interface.

The IX509CertificateTemplateWritable has already been

HRESULT_FROM_WIN32(ERROR_ALREADY_INITIALIZE initialized.
D)

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Target Platform Windows

Header certenroll.h
See also
IX509CertificateTemplateWritable
 IX509CertificateTemplateWritable::put_Property
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Proper ty property specifies or retrieves a property value for the IX509CertificateTemplateWritable object.
This property is read/write.

Syntax
HRESULT put_Property(
EnrollmentTemplateProperty property,
VARIANT value
);

Parameters
property

value

Return value
None

Remarks
Currently, TemplatePropSecurityDescriptor is the only property that you can set. The property value must be a
VARIANT of type VT_BSTR or VT_BYREF|VT_BSTR and must be a valid SDDL string.

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Target Platform Windows

Header certenroll.h

See also
IX509CertificateTemplateWritable
 IX509EndorsementKey interface (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

X.509 Endorsement Key Interface

Inheritance
The IX509EndorsementKey interface inherits from the IDispatch interface. IX509EndorsementKey also has
these types of members:

Methods
The IX509EndorsementKey interface has these methods.

IX509EndorsementKey::AddCertificate

Add an endorsement key certificate to the key storage provider (KSP) that supports endorsement keys.

IX509EndorsementKey::Close

Closes the endorsement key. You can only call the Close method after the Open method has been successfully called.

IX509EndorsementKey::ExportPublicKey

Exports the endorsement public key.

IX509EndorsementKey::get_Length

The bit length of the endorsement key. You can only access this property after the Open method has been called.

IX509EndorsementKey::get_Opened

Indicates whether the Open method has been successfully called.

IX509EndorsementKey::get_ProviderName

The name of the encryption provider. The default is the Microsoft Platform Crypto Provider. You must set the ProviderName
property before you call the Open method. You cannot change the ProviderName property after you have called the Open
method.

IX509EndorsementKey::GetCertificateByIndex

Gets the endorsement certificate associated with the endorsement key from the key storage provider for the specified index.

IX509EndorsementKey::GetCertificateCount

Gets the count of the endorsement certificates in the key storage provider.
 IX509EndorsementKey::Open

Opens the endorsement key. The endorsement key must be open before you can retrieve an information from the
endorsement key, add or remove certificates, or export the endorsement key.

IX509EndorsementKey::put_ProviderName

The name of the encryption provider. The default is the Microsoft Platform Crypto Provider. You must set the ProviderName
property before you call the Open method. You cannot change the ProviderName property after you have called the Open
method.

IX509EndorsementKey::RemoveCertificate

Removes an endorsement certificate related to the endorsement key from the key storage provider. You can only call the
RemoveCertificate method after the Open method has been successfully called.

Requirements

Target Platform Windows

Header certenroll.h
 IX509EndorsementKey::AddCertificate method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

Add an endorsement key certificate to the key storage provider (KSP) that supports endorsement keys. You can
only call the AddCer tificate method after the Open method has been successfully called.

Syntax
HRESULT AddCertificate(
[in] EncodingType Encoding,
[in] BSTR strCertificate
);

Parameters
[in] Encoding

An EncodingType enumeration value that specifies the type of Unicode-encoding applied to the certificate. The
default value is XCN_CRYPT_STRING_BASE64.
[in] strCertificate

The certificate to add to the store. The public key from this certificate must match the public key of the
endorsement key.

Return value
If this method succeeds, it returns S_OK . Otherwise, it returns an HRESULT error code.

Remarks
Only non-manufacturer certificates can be added to the key storage provider.

Requirements

Target Platform Windows

Header certenroll.h

DLL Certenroll.dll

See also
IX509EndorsementKey
 IX509EndorsementKey::Close method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

Closes the endorsement key. You can only call the Close method after the Open method has been successfully
called.

Syntax
HRESULT Close();

Return value
If this method succeeds, it returns S_OK . Otherwise, it returns an HRESULT error code.

Remarks
The Close method releases any resources held by the object except for the ProviderName. The ProviderName
is released when it is re-assigned or when this object is destroyed.

Requirements

Target Platform Windows

Header certenroll.h

DLL Certenroll.dll

See also
IX509EndorsementKey
 IX509EndorsementKey::ExportPublicKey method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

Exports the endorsement public key. You can only call the Expor tPublicKey method after the Open method has
been successfully called.

Syntax
HRESULT ExportPublicKey(
[out, retval] IX509PublicKey **ppPublicKey
);

Parameters
[out, retval] ppPublicKey

The exported endorsement public key.

Return value
If this method succeeds, it returns S_OK . Otherwise, it returns an HRESULT error code.

Requirements

Target Platform Windows

Header certenroll.h

DLL Certenroll.dll

See also
IX509EndorsementKey
 IX509EndorsementKey::get_Length method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The bit length of the endorsement key. You can only access this property after the Open method has been called.
This property is read-only.

Syntax
HRESULT get_Length(
LONG *pValue
);

Parameters
pValue

Return value
None

Requirements

Target Platform Windows

Header certenroll.h

DLL Certenroll.dll

See also
IX509EndorsementKey
 IX509EndorsementKey::get_Opened method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

Indicates whether the Open method has been successfully called.

This property is read-only.

Syntax
HRESULT get_Opened(
VARIANT_BOOL *pValue
);

Parameters
pValue

Return value
None

Requirements

Target Platform Windows

Header certenroll.h

DLL Certenroll.dll

See also
IX509EndorsementKey
 IX509EndorsementKey::get_ProviderName method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The name of the encryption provider. The default is the Microsoft Platform Crypto Provider. You must set the
ProviderName property before you call the Open method. You cannot change the ProviderName property
after you have called the Open method.
This property is read/write.

Syntax
HRESULT get_ProviderName(
BSTR *pValue
);

Parameters
pValue

Return value
None

Requirements

Target Platform Windows

Header certenroll.h

DLL Certenroll.dll

See also
IX509EndorsementKey
 IX509EndorsementKey::GetCertificateCount method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

Gets the count of the endorsement certificates in the key storage provider. You can only call the
GetCer tificateCount method after the Open method has been successfully called.

Syntax
HRESULT GetCertificateCount(
[in] VARIANT_BOOL ManufacturerOnly,
[out, retval] LONG *pCount
);

Parameters
[in] ManufacturerOnly

True to return the count for only manufacturer certificates. False to return the count for only non-manufacturer
certificates.
[out, retval] pCount

The count of endorsement certificates from the key storage provider.

Return value
If this method succeeds, it returns S_OK . Otherwise, it returns an HRESULT error code.

Requirements

Target Platform Windows

Header certenroll.h

DLL Certenroll.dll

See also
IX509EndorsementKey
 IX509EndorsementKey::Open method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

Opens the endorsement key. The endorsement key must be open before you can retrieve an information from
the endorsement key, add or remove certificates, or export the endorsement key.

Syntax
HRESULT Open();

Return value
If this method succeeds, it returns S_OK . Otherwise, it returns an HRESULT error code.

Requirements

Target Platform Windows

Header certenroll.h

DLL Certenroll.dll

See also
IX509EndorsementKey
 IX509EndorsementKey::put_ProviderName method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The name of the encryption provider. The default is the Microsoft Platform Crypto Provider. You must set the
ProviderName property before you call the Open method. You cannot change the ProviderName property
after you have called the Open method.
This property is read/write.

Syntax
HRESULT put_ProviderName(
BSTR Value
);

Parameters
Value

Return value
None

Requirements

Target Platform Windows

Header certenroll.h

DLL Certenroll.dll

See also
IX509EndorsementKey
 IX509EndorsementKey::RemoveCertificate method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

Removes an endorsement certificate related to the endorsement key from the key storage provider. You can only
call the RemoveCer tificate method after the Open method has been successfully called.

Syntax
HRESULT RemoveCertificate(
[in] EncodingType Encoding,
[in] BSTR strCertificate
);

Parameters
[in] Encoding

An EncodingType enumeration value that specifies the type of Unicode-encoding applied to the endorsement
certificate. The default value is XCN_CRYPT_STRING_BASE64.
[in] strCertificate

The certificate to remove from the store.

Return value
If this method succeeds, it returns S_OK . Otherwise, it returns an HRESULT error code.

Remarks
Only non-manufacturer certificates can be removed from the key storage provider.

Requirements

Target Platform Windows

Header certenroll.h

DLL Certenroll.dll

See also
IX509EndorsementKey
 IX509Enrollment interface (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The IX509Enrollment interface represents the top level object and enables you to enroll in a certificate
hierarchy and install a certificate response. The enrollment process supports the following three scenarios:
Out-of-band enrollment
1. Call any initialization method implemented by the IX509Enrollment object.
2. Call the CreateRequest method.
3. Submit the request out of band (manually or through some other process).
4. Receive the response from a certification or registration authority.
5. Call the InstallResponse method.
Automatic enrollment
1. Call any initialization method implemented by the IX509Enrollment object.
2. Call the Enroll method.
Delayed enrollment
1. Call any initialization method implemented by the IX509Enrollment object.
2. Call the CreateRequest method.
3. Store the request for a period of time such as days or weeks.
4. Call the Initialize method to create a request object when you are ready to enroll.
5. Populate the request object from your stored request.
6. Call the InstallResponse method.

Inheritance
The IX509Enrollment interface inherits from the IDispatch interface. IX509Enrollment also has these types of
members:

Methods
The IX509Enrollment interface has these methods.

IX509Enrollment::CreatePFX

Creates a Personal Information Exchange (PFX) message.

IX509Enrollment::CreateRequest

Retrieves an encoded certificate request.

IX509Enrollment::Enroll

Encodes a request, submits it to an appropriate certification authority (CA), and installs the response.
IX509Enrollment::get_CAConfigString

Retrieves the configuration string that identifies the certification authority (CA) to which the certificate request was submitted.

IX509Enrollment::get_Certificate

Retrieves the installed certificate.

IX509Enrollment::get_CertificateDescription

Specifies or retrieves a string that contains a description of the certificate.

IX509Enrollment::get_CertificateFriendlyName

Specifies or retrieves the display name of a certificate.

IX509Enrollment::get_EnrollmentContext

Retrieves an enrollment context that identifies whether the certificate is intended for a computer or an end-user.

IX509Enrollment::get_NameValuePairs

Retrieves a collection of name-value pairs associated with the enrollment object.

IX509Enrollment::get_ParentWindow

Specifies or retrieves the ID of the window used to display the enrollment information.

IX509Enrollment::get_Request

Retrieves the certificate request associated with the enrollment object.

IX509Enrollment::get_RequestId

Retrieves a unique identifier for the certificate request sent to the certification authority by the Enroll method.

IX509Enrollment::get_Response

Retrieves the certificate response returned from a certification authority.

IX509Enrollment::get_Silent

Specifies or retrieves a Boolean value that indicates whether a user interface is displayed during the certificate enrollment
process.

IX509Enrollment::get_Status

Retrieves an IX509EnrollmentStatus object that can be used to monitor the status of the enrollment process and retrieve error
information.

IX509Enrollment::Initialize

Initializes the enrollment object and creates a default PKCS

 IX509Enrollment::InitializeFromRequest

Initializes the enrollment object from an existing IX509CertificateRequest object.

IX509Enrollment::InitializeFromTemplateName

Initializes the enrollment object from a template common name (CN).

IX509Enrollment::InstallResponse

Installs a certificate chain on the end-entity computer.

IX509Enrollment::put_CertificateDescription

Specifies or retrieves a string that contains a description of the certificate.

IX509Enrollment::put_CertificateFriendlyName

Specifies or retrieves the display name of a certificate.

IX509Enrollment::put_ParentWindow

Specifies or retrieves the ID of the window used to display the enrollment information.

IX509Enrollment::put_Silent

Specifies or retrieves a Boolean value that indicates whether a user interface is displayed during the certificate enrollment
process.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

See also
Certificate Enrollment API
IDispatch
IX509EnrollmentStatus
 IX509Enrollment::CreatePFX method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The CreatePFX method creates a Personal Information Exchange (PFX) message. The message is contained in a
byte array that is encoded by using Distinguished Encoding Rules (DER) as defined by the Abstract Syntax
Notation One (ASN.1) standard. The DER-encoded byte array is represented by a string that is either a pure
binary sequence or is Unicode encoded.

Syntax
HRESULT CreatePFX(
[in] BSTR strPassword,
[in] PFXExportOptions ExportOptions,
[in] EncodingType Encoding,
[out] BSTR *pValue
);

Parameters
[in] strPassword

A BSTR variable that contains a password for the PFX message. This can be NULL to indicate that no password
is used. When you have finished using the password, clear it from memory by calling the SecureZeroMemory
function. For more information about protecting the password, see Handling Passwords.
[in] ExportOptions

A PFXExportOptions enumeration value that specifies how much of the certificate chain is exported. You can
export the certificate only, the certificate chain without the root, or the entire chain.
[in] Encoding

An EncodingType enumeration value that specifies the type of Unicode encoding applied to the DER-encoded
message. The default value is XCN_CRYPT_STRING_BASE64 .
[out] pValue

Pointer to a BSTR variable that contains the DER-encoded PFX message.

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. Possible values include, but are not
limited to, those in the following table. For a list of common error codes, see Common HRESULT Values.

RET URN C O DE/ VA L UE DESC RIP T IO N

The certificate cannot be found.

CERTSRV_E_PROPERTY_EMPTY
 No certificate chain can be found.
HRESULT_FROM_WIN32(ERROR_FILE_NOT_FOUND)

The enrollment object has not been initialized.

OLE_E_BL ANK

Remarks
The PFX format is also known as PKCS #12. The CreatePFX method:
Opens the certificate store in memory for the default provider.
Adds the installed certificate to the store or builds the certificate chain adds a link to it.
Exports the certificate and the private key to a PFX message depending on the export options specified.
Encodes the exported message by using DER.
Before calling this method, you must initialize the IX509Enrollment object by calling one of the following
methods.
Initialize
InitializeFromRequest
InitializeFromTemplateName
Further, you must return successfully from the Enroll method.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509Enrollment
 IX509Enrollment::CreateRequest method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The CreateRequest method retrieves an encoded certificate request. The certificate request is contained in a
byte array that is encoded by using Distinguished Encoding Rules (DER) as defined by the Abstract Syntax
Notation One (ASN.1) standard. The DER-encoded byte array is represented by a string that is either a pure
binary sequence or Unicode encoded. This method is web enabled.

Syntax
HRESULT CreateRequest(
[in] EncodingType Encoding,
[out] BSTR *pValue
);

Parameters
[in] Encoding

An EncodingType enumeration value that specifies the type of Unicode encoding applied to the DER-encoded
request. The default value is XCN_CRYPT_STRING_BASE64 .
[out] pValue

Pointer to a BSTR variable that contains the DER-encoded request.

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. Possible values include, but are not
limited to, those in the following table. For a list of common error codes, see Common HRESULT Values.

RET URN C O DE/ VA L UE DESC RIP T IO N

The certificate request cannot be found.

CERTSRV_E_PROPERTY_EMPTY

The enrollment object has not been initialized.

OLE_E_BL ANK

Remarks
The CreateRequest method calls the Encode method, if necessary, to encode the raw data from the associated
request object.
This method uses the information provided during initialization and other properties that have been specified,
creates a dummy certificate and places it in the request store. The method also creates a key pair if necessary.
Depending on how you initialize the enrollment object and on what properties you set, there may be no need to
create a key pair. For example, if you are renewing a certificate by using an existing key, or if the IX509PrivateKey
object associated with the certificate request represents an existing key, this method does not create a new key
pair.
If a smartcard is involved, this method encodes external properties as extensions, includes them in the dummy
certificate, and writes the dummy certificate to the smartcard key container. Smartcard logon certificates are
encoded to the request store, not the personal store.
Before calling the CreateRequest method, you must initialize the IX509Enrollment object by calling one of the
following methods.
Initialize
InitializeFromRequest
InitializeFromTemplateName

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509CertificateRequest
IX509Enrollment
 IX509Enrollment::Enroll method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Enroll method encodes a request, submits it to an appropriate certification authority (CA), and installs the
response.

Syntax
HRESULT Enroll();

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. Possible values include, but are not
limited to, those in the following table. For a list of common error codes, see Common HRESULT Values.

RET URN C O DE/ VA L UE DESC RIP T IO N

The enrollment object has not been initialized.

OLE_E_BL ANK

Remarks
The method may create a key pair if necessary. Depending on how you initialize the enrollment object and on
what properties you set, there may be no need to create a key pair. For example, if you are renewing a certificate
by using an existing key, or if the IX509PrivateKey object associated with the certificate request represents an
existing key, this method does not create a new key pair.
Before enrolling, you must initialize the IX509Enrollment object by calling one of the following methods.
Initialize
InitializeFromRequest
InitializeFromTemplateName
If the enrollment operation succeeds, the function returns S_OK . However, this does not necessarily mean that
the response from the CA was installed. Call the Status property to determine the enrollment status.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

 Header certenroll.h

DLL CertEnroll.dll

See also
IX509Enrollment
 IX509Enrollment::get_CAConfigString method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The CAConfigString property retrieves the configuration string that identifies the certification authority (CA) to
which the certificate request was submitted.
This property is read-only.

Syntax
HRESULT get_CAConfigString(
BSTR *pValue
);

Parameters
pValue

Return value
None

Remarks
The configuration string contains the Domain Name System (DNS) name and the common name (CN) of the
certification authority. The format of the string is "CAComputerDNSName\CACommonName".

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509Enrollment
 IX509Enrollment::get_Certificate method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Cer tificate property retrieves the installed certificate. The certificate is contained in a byte array that is
encoded by using Distinguished Encoding Rules (DER) as defined by the Abstract Syntax Notation One (ASN.1)
standard. The DER-encoded byte array is represented by a string that is either a pure binary sequence or
Unicode encoded.
This property is read-only.

Syntax
HRESULT get_Certificate(
EncodingType Encoding,
BSTR *pValue
);

Parameters
Encoding

pValue

Return value
None

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509Enrollment
 IX509Enrollment::get_CertificateDescription method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Cer tificateDescription property specifies or retrieves a string that contains a description of the certificate.
This property is web enabled for both input and output.
This property is read/write.

Syntax
HRESULT get_CertificateDescription(
BSTR *pValue
);

Parameters
pValue

Return value
None

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509Enrollment
 IX509Enrollment::get_CertificateFriendlyName
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Cer tificateFriendlyName property specifies or retrieves the display name of a certificate. This property is
web enabled for both input and output.
This property is read/write.

Syntax
HRESULT get_CertificateFriendlyName(
BSTR *pValue
);

Parameters
pValue

Return value
None

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509Enrollment
 IX509Enrollment::get_EnrollmentContext method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The EnrollmentContext property retrieves an enrollment context that identifies whether the certificate is
intended for a computer or an end-user.
This property is read-only.

Syntax
HRESULT get_EnrollmentContext(
X509CertificateEnrollmentContext *pValue
);

Parameters
pValue

Return value
None

Remarks
Before calling this property, you must initialize the IX509Enrollment object by calling one of the following
methods.
Initialize
InitializeFromRequest
InitializeFromTemplateName

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509Enrollment
 IX509Enrollment::get_NameValuePairs method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The NameValuePairs property retrieves a collection of name-value pairs associated with the enrollment object.
This property is read-only.

Syntax
HRESULT get_NameValuePairs(
IX509NameValuePairs **ppValue
);

Parameters
ppValue

Return value
None

Remarks
name-value pairs are passed to the certification authority (CA) with the request for the CA to act upon. The
IX509NameValuePairs object is associated with the IX509Enrollment object when the object is initialized.
Therefore, before calling this property, you must initialize the IX509Enrollment object by calling one of the
following methods.
Initialize
InitializeFromRequest
InitializeFromTemplateName

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll
See also
IX509Enrollment
 IX509Enrollment::get_ParentWindow method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The ParentWindow property specifies or retrieves the ID of the window used to display the enrollment
information.
This property is read/write.

Syntax
HRESULT get_ParentWindow(
LONG *pValue
);

Parameters
pValue

Return value
None

Remarks
You can call this property before initializing the enrollment object. If you do not, it may be specified when the
object is initialized.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509Enrollment
 IX509Enrollment::get_Request method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Request property retrieves the certificate request associated with the enrollment object.
This property is read-only.

Syntax
HRESULT get_Request(
IX509CertificateRequest **pValue
);

Parameters
pValue

Return value
None

Remarks
This property can be set when the InitializeFromRequest method is called.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509Enrollment
 IX509Enrollment::get_RequestId method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The RequestId property retrieves a unique identifier for the certificate request sent to the certification authority
by the Enroll method.
This property is read-only.

Syntax
HRESULT get_RequestId(
LONG *pValue
);

Parameters
pValue

Return value
None

Remarks
The value of the RequestId property is set during the enrollment process. It can be used during subsequent
communication between the client and the CA. For example, if a CA marks a request as pending when initially
submitted, the client can use the request ID and the configuration string when it again contacts the CA and
attempts to retrieve the certificate response. To retrieve the configuration string, call the CAConfigString
property.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509Enrollment
 IX509Enrollment::get_Response method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Response property retrieves the certificate response returned from a certification authority. The response
is contained in a byte array that is encoded by using Distinguished Encoding Rules (DER) as defined by the
Abstract Syntax Notation One (ASN.1) standard. The DER-encoded byte array is represented by a string that is
either a pure binary sequence or Unicode encoded.
This property is read-only.

Syntax
HRESULT get_Response(
EncodingType Encoding,
BSTR *pValue
);

Parameters
Encoding

pValue

Return value
None

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509Enrollment
 IX509Enrollment::get_Silent method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Silent property specifies or retrieves a Boolean value that indicates whether a user interface is displayed
during the certificate enrollment process.
This property is read/write.

Syntax
HRESULT get_Silent(
VARIANT_BOOL *pValue
);

Parameters
pValue

Return value
None

Remarks
You can set this property before initializing the enrollment object.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509Enrollment
 IX509Enrollment::get_Status method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Status property retrieves an IX509EnrollmentStatus object that can be used to monitor the status of the
enrollment process and retrieve error information.
This property is read-only.

Syntax
HRESULT get_Status(
IX509EnrollmentStatus **ppValue
);

Parameters
ppValue

Return value
None

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509Enrollment
 IX509Enrollment::Initialize method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Initialize method initializes the enrollment object and creates a default PKCS #10 request. This method is
web enabled.

Syntax
HRESULT Initialize(
[in] X509CertificateEnrollmentContext Context
);

Parameters
[in] Context

An X509CertificateEnrollmentContext enumeration value that specifies whether the requested enrollment is for
a user, a computer, or an administrator acting on behalf of a computer.

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. Possible values include, but are not
limited to, those in the following table. For a list of common error codes, see Common HRESULT Values.

RET URN C O DE/ VA L UE DESC RIP T IO N

The enrollment object has already been initialized.

HRESULT_FROM_WIN32(ERROR_ALREADY_INITIALIZE
D)

Remarks
The Initialize method creates a new key pair and initializes empty collections for the attributes, extensions and
critical extensions associated with the request.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h
 DLL CertEnroll.dll

See also
IX509Enrollment
 IX509Enrollment::InitializeFromRequest method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The InitializeFromRequest method initializes the enrollment object from an existing IX509CertificateRequest
object. This method is web enabled.

Syntax
HRESULT InitializeFromRequest(
[in] IX509CertificateRequest *pRequest
);

Parameters
[in] pRequest

Pointer to the IX509CertificateRequest interface.

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. Possible values include, but are not
limited to, those in the following table. For a list of common error codes, see Common HRESULT Values.

RET URN C O DE/ VA L UE DESC RIP T IO N

The enrollment object has already been initialized.

HRESULT_FROM_WIN32(ERROR_ALREADY_INITIALIZE
D)

Remarks
The InitializeFromRequest method:
Verifies that the request is a PKCS #10, PKCS #7, or CMC request object.
Retrieves the template, if any, associated with the request.
Validates the template.
Sets the request object on the Request property.
Retrieves the signature count, issuance policies, and application policies from the template.
Retrieves the renewal certificate if one exists.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

 Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509CertificateRequest
IX509CertificateRequestCmc
IX509CertificateRequestPkcs10
IX509CertificateRequestPkcs7
IX509Enrollment
 IX509Enrollment::InitializeFromTemplateName
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The InitializeFromTemplateName method initializes the enrollment object from a template common name
(CN).

Syntax
HRESULT InitializeFromTemplateName(
[in] X509CertificateEnrollmentContext Context,
[in] BSTR strTemplateName
);

Parameters
[in] Context

An X509CertificateEnrollmentContext enumeration value that indicates whether the requested enrollment is for
a user, a computer, or an administrator acting on behalf of a computer.
[in] strTemplateName

A BSTR variable that contains the Common Name (CN) of the template as it appears in Active Directory or the
dotted decimal object identifier.

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. Possible values include, but are not
limited to, those in the following table. For a list of common error codes, see Common HRESULT Values.

RET URN C O DE/ VA L UE DESC RIP T IO N

The enrollment object has already been initialized.

HRESULT_FROM_WIN32(ERROR_ALREADY_INITIALIZE
D)

Remarks
The InitializeFromTemplateName method:
Examines the template to determine the type of request needed.
Creates the appropriate type of request object (PKCS #10, PKCS #7, or CMC).
Sets the following properties on the request if values currently exist:
CspInformations
ParentWindow
Silent
 Initializes the request object by using the template.
Retrieves the signature count, issuance policies, and application policies from the template.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509Enrollment
 IX509Enrollment::InstallResponse method
(certenroll.h)
7/2/2022 • 3 minutes to read • Edit Online

The InstallResponse method installs a certificate chain on the end-entity computer. The byte array that
contains the response is encoded by using Distinguished Encoding Rules (DER) as defined by the Abstract
Syntax Notation One (ASN.1) standard. You must specify the DER-encoded byte array in a string that is either a
pure binary sequence or is Unicode encoded. This method is web enabled.

Syntax
HRESULT InstallResponse(
[in] InstallResponseRestrictionFlags Restrictions,
[in] BSTR strResponse,
[in] EncodingType Encoding,
[in, optional] BSTR strPassword
);

Parameters
[in] Restrictions

An InstallResponseRestrictionFlags enumeration value that specifies the type of certificates that can be installed.
This can be one or more of the following values.

VA L UE M EA N IN G

Do not install untrusted certificates or certificates for which

AllowNone there is no corresponding request.

Create the private key from the certificate response rather

AllowNoOutstandingRequest than from the dummy certificate. This makes the dummy
certificate optional. If this value is not set, the dummy
certificate must exist, and the private key is extracted from it.

Install untrusted end entity and certification authority

AllowUntrustedCer tificate certificates. Certification authority certificates include root
and subordinate CA certificates. End entity certificates are
installed to the personal store, and CA certificates are
installed to the certification authority store.
 Perform the same action as the
AllowUntrustedRoot AllowUntrustedCer tificate flag but also installs the
certificate even if the certificate chain cannot be built
because the root is not trusted.

Note On Windows Vista, the behavior of this flag is the

same as that defined for the AllowUntrustedCertificate
flag. Beginning with Windows Vista with SP1, you can install
a certificate that chains up to an untrusted root.

[in] strResponse

A BSTR variable that contains the DER-encoded response.

[in] Encoding

An EncodingType enumeration value that specifies the type of encoding applied to the string that contains the
DER-encoded response.
[in, optional] strPassword

An optional password for the certificate installation. This can be NULL or an empty string to indicate that no
password is used. If there is a password, clear it from memory when you have finished using it by calling the
SecureZeroMemory function. For more information about protecting the password, see Handling Passwords.
Beginning with Windows 8 and Windows Server 2012, a NULL or empty password may mean that the PFX
packet was created in the PFXExportCertStoreEx function by using the PKCS12_PROTECT_TO_DOMAIN_SIDS
flag. If so, the PFX was encrypted to an Active Directory group. For more information, see
PFXExpor tCer tStoreEx and PFXImportCertStore.

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. Possible values include, but are not
limited to, those in the following table. For a list of common error codes, see Common HRESULT Values.

RET URN C O DE DESC RIP T IO N

This method was called from the web and either

E_ACCESSDENIED AllowNoOutstandingRequest or
AllowUntrustedCer tificate was specified in the
Restrictions parameter.

The length of the string that contains the password exceeds

HRESULT_FROM_WIN32(ERROR_ARITHMETIC_OVERF 64 kilobytes.
LOW

The enrollment object has not been initialized.

OLE_E_BL ANK

Remarks
The InstallResponse method:
1. Retrieves the dummy certificate from the external store.
2. Retrieves the certificate contained in the response and installs it on the computer.
3. Copies properties from the dummy certificate in the external store onto the newly installed certificate in the
personal store.
Before calling the InstallResponse method, you must initialize the IX509Enrollment object by calling one of the
following methods.
Initialize
InitializeFromRequest
InitializeFromTemplateName
If you call this method from the web, you can specify only AllowNone or AllowUntrustedRoot in the
Restrictions parameter. If you specify AllowNoOutstandingRequest or AllowUntrustedCer tificate , the
method returns an E_ACCESSDENIED error.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509Enrollment
 IX509Enrollment::put_CertificateDescription method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Cer tificateDescription property specifies or retrieves a string that contains a description of the certificate.
This property is web enabled for both input and output.
This property is read/write.

Syntax
HRESULT put_CertificateDescription(
BSTR strValue
);

Parameters
strValue

Return value
None

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509Enrollment
 IX509Enrollment::put_CertificateFriendlyName
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Cer tificateFriendlyName property specifies or retrieves the display name of a certificate. This property is
web enabled for both input and output.
This property is read/write.

Syntax
HRESULT put_CertificateFriendlyName(
BSTR strValue
);

Parameters
strValue

Return value
None

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509Enrollment
 IX509Enrollment::put_ParentWindow method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The ParentWindow property specifies or retrieves the ID of the window used to display the enrollment
information.
This property is read/write.

Syntax
HRESULT put_ParentWindow(
LONG Value
);

Parameters
Value

Return value
None

Remarks
You can call this property before initializing the enrollment object. If you do not, it may be specified when the
object is initialized.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509Enrollment
 IX509Enrollment::put_Silent method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Silent property specifies or retrieves a Boolean value that indicates whether a user interface is displayed
during the certificate enrollment process.
This property is read/write.

Syntax
HRESULT put_Silent(
VARIANT_BOOL Value
);

Parameters
Value

Return value
None

Remarks
You can set this property before initializing the enrollment object.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509Enrollment
 IX509Enrollment2 interface (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The IX509Enrollment2 interface enables you to enroll in a certificate hierarchy and install a certificate
response. It includes all of the methods defined by the IX509Enrollment interface and adds methods that enable
initialization from certificate request templates.

Inheritance
The IX509Enrollment2 interface inherits from IX509Enrollment. IX509Enrollment2 also has these types of
members:

Methods
The IX509Enrollment2 interface has these methods.

IX509Enrollment2::get_PolicyServer

Retrieves the certificate enrollment policy (CEP) server that contains the template used during initialization.

IX509Enrollment2::get_RequestIdString

Retrieves a string that contains a unique identifier for the certificate request sent to the certification enrollment server (CES).

IX509Enrollment2::get_Template

Retrieves the certificate request template used during initialization.

IX509Enrollment2::InitializeFromTemplate

Initializes the enrollment object by using a template.

IX509Enrollment2::InstallResponse2

Installs a certificate chain on the end-entity computer.

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Target Platform Windows

Header certenroll.h
See also
IX509Enrollment
 IX509Enrollment2::get_PolicyServer method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The PolicySer ver property retrieves the certificate enrollment policy (CEP) server that contains the template
used during initialization.
This property is read-only.

Syntax
HRESULT get_PolicyServer(
IX509EnrollmentPolicyServer **ppPolicyServer
);

Parameters
ppPolicyServer

Return value
None

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Target Platform Windows

Header certenroll.h

See also
IX509Enrollment2
 IX509Enrollment2::get_RequestIdString method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The RequestIdString property retrieves a string that contains a unique identifier for the certificate request sent
to the certification enrollment server (CES).
This property is read-only.

Syntax
HRESULT get_RequestIdString(
BSTR *pValue
);

Parameters
pValue

Return value
None

Remarks
The value of the RequestIdString property is set during the enrollment process. It can be used during
subsequent communication between the client and the CES. For example, if a CES marks a request as pending
when initially submitted, the client can use the request ID string when it again contacts the CES and attempts to
retrieve the certificate response.

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Target Platform Windows

Header certenroll.h

See also
IX509Enrollment2
 IX509Enrollment2::get_Template method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Template property retrieves the certificate request template used during initialization.
This property is read-only.

Syntax
HRESULT get_Template(
IX509CertificateTemplate **ppTemplate
);

Parameters
ppTemplate

Return value
None

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Target Platform Windows

Header certenroll.h

See also
IX509Enrollment2
 IX509Enrollment2::InitializeFromTemplate method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The InitializeFromTemplate method initializes the enrollment object by using a template.

Syntax
HRESULT InitializeFromTemplate(
[in] X509CertificateEnrollmentContext context,
[in] IX509EnrollmentPolicyServer *pPolicyServer,
[in] IX509CertificateTemplate *pTemplate
);

Parameters
[in] context

An X509CertificateEnrollmentContext enumeration value that indicates whether the requested enrollment is for
a user, a computer, or an administrator acting on behalf of a computer. This can be one of the following values.

VA L UE M EA N IN G

The certificate is being requested for an end user.

ContextUser

The certificate is being requested for a computer.

ContextMachine

The certificate is being requested by an administrator acting

ContextAdministratorForceMachine on the behalf of a computer.

[in] pPolicyServer

Pointer to an IX509EnrollmentPolicyServer object that represents the certificate enrollment policy (CEP) server
that contains the template specified by the pTemplate parameter.
[in] pTemplate

Pointer to an IX509CertificateTemplate object that represents the template to use during initialization.

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. Possible values include, but are not
limited to, those in the following table. For a list of common error codes, see Common HRESULT Values.

RET URN C O DE/ VA L UE DESC RIP T IO N

 The pPolicyServer and pTemplate parameters cannot be
E_POINTER NULL .

The enrollment object has already been initialized.

HRESULT_FROM_WIN32(ERROR_ALREADY_INITIALIZE
D)

Remarks
The InitializeFromTemplate method:
Examines the template to determine the type of request needed.
Creates the appropriate type of request object (PKCS #10, PKCS #7, or CMC).
Sets the following properties on the request if values currently exist:
CspInformations
ParentWindow
Silent
Initializes the request object by using the template.
Retrieves the signature count, issuance policies, and application policies from the template.

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Target Platform Windows

Header certenroll.h

See also
IX509Enrollment2
 IX509Enrollment2::InstallResponse2 method
(certenroll.h)
7/2/2022 • 4 minutes to read • Edit Online

The InstallResponse2 method installs a certificate chain on the end-entity computer. The byte array that
contains the response is encoded by using Distinguished Encoding Rules (DER) as defined by the Abstract
Syntax Notation One (ASN.1) standard. You must specify the DER-encoded byte array in a string that is either a
pure binary sequence or is Unicode encoded. This method is web enabled.

Syntax
HRESULT InstallResponse2(
[in] InstallResponseRestrictionFlags Restrictions,
[in] BSTR strResponse,
[in] EncodingType Encoding,
[in, optional] BSTR strPassword,
[in] BSTR strEnrollmentPolicyServerUrl,
[in] BSTR strEnrollmentPolicyServerID,
[in] PolicyServerUrlFlags EnrollmentPolicyServerFlags,
[in] X509EnrollmentAuthFlags authFlags
);

Parameters
[in] Restrictions

An InstallResponseRestrictionFlags enumeration value that specifies the type of certificates that can be installed.
This can be one or more of the following values.

VA L UE M EA N IN G

Do not install untrusted certificates or certificates for which

AllowNone there is no corresponding request.

Create the private key from the certificate response rather

AllowNoOutstandingRequest than from the dummy certificate. This makes the dummy
certificate optional. If this value is not set, the dummy
certificate must exist, and the private key is extracted from it.

Install untrusted end entity and certification authority

AllowUntrustedCer tificate certificates. Certification authority certificates include root
and subordinate CA certificates. End entity certificates are
installed to the personal store, and CA certificates are
installed to the certification authority store.
 Perform the same action as the
AllowUntrustedRoot AllowUntrustedCer tificate flag but also installs the
certificate even if the certificate chain cannot be built
because the root is not trusted.

Note On Windows Vista, the behavior of this flag is the

same as that defined for the AllowUntrustedCertificate
flag. You can install an untrusted root beginning with
Windows Vista with SP1.

[in] strResponse

A BSTR variable that contains the DER-encoded response.

[in] Encoding

An EncodingType enumeration value that specifies the type of encoding applied to the string that contains the
DER-encoded response.
[in, optional] strPassword

An optional password for the certificate installation. This can be NULL to indicate that no password is used.
When you have finished using the password, clear it from memory by calling the SecureZeroMemory function.
For more information about protecting the password, see Handling Passwords.
[in] strEnrollmentPolicyServerUrl

A BSTR that contains the URL of the certificate enrollment policy (CEP) server.
[in] strEnrollmentPolicyServerID

A BSTR that contains an identifier for the CEP server.

[in] EnrollmentPolicyServerFlags

A PolicyServerUrlFlags enumeration value. This can be one of the following values.

VA L UE M EA N IN G

The CEP server URL is specified in group policy by an

PsfLocationGroupPolicy administrator.

The CEP server URL is specified in the registry.

PsfLocationRegistr y
 Specifies that certificate enrollments and renewals include
PsfUseClientId client specific data in a ClientId attribute. Examples include
the name of the cryptographic service provider, the
Windows version number, the user name, the computer DNS
name, and the domain controller DNS name. This flag can be
set by group policy.
This flag has been included to address privacy concerns
that can arise during enrollment to servers that are
managed by administrators other than those who
manage the forest in which the user resides. By not
setting this flag, you can prevent sending personal
information to non-local administrators.

Automatic certificate enrollment is enabled.

PsfAutoEnrollmentEnabled

Specifies that the certificate of the issuing CA need not be

PsfAllowUnTrustedCA trusted by the client to install a certificate signed by the CA.

[in] authFlags

An X509EnrollmentAuthFlags enumeration value that specifies the client authentication type. For Windows 7,
only X509AuthCer tificate can be chosen from the following values.

VA L UE M EA N IN G

Anonymous authentication.
X509AuthAnonymous

Kerberos authentication.
X509AuthKerberos

Clear text user name and password authentication.

X509AuthUsername
Note The user name and password are encrypted before
transmission and are stored securely in the credential vault
on the CEP server.

Client authentication certificate installed on the local

X509AuthCer tificate computer and used by the server to verify the identity of the
client.

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. Possible values include, but are not
limited to, those in the following table. For a list of common error codes, see Common HRESULT Values.

RET URN C O DE DESC RIP T IO N

 This method was called from the web and either
E_ACCESSDENIED AllowNoOutstandingRequest or
AllowUntrustedCer tificate was specified in the
Restrictions parameter.

The length of the string that contains the password exceeds

HRESULT_FROM_WIN32(ERROR_ARITHMETIC_OVERF 64 kilobytes.
LOW

The enrollment object has not been initialized.

OLE_E_BL ANK

Remarks
The InstallResponse2 method:
1. Retrieves the dummy certificate from the external store.
2. Retrieves the certificate contained in the response and installs it on the computer.
3. Copies properties from the dummy certificate in the external store onto the newly installed certificate in the
personal store.
Before calling the InstallResponse2 method, you must initialize the IX509Enrollment object by calling one of
the following methods.
Initialize
InitializeFromRequest
InitializeFromTemplate
InitializeFromTemplateName
If you call this method from the web, you can specify only AllowNone or AllowUntrustedRoot in the
Restrictions parameter. If you specify AllowNoOutstandingRequest or AllowUntrustedCer tificate , the
method returns an E_ACCESSDENIED error.
The last four parameters (strEnrollmentPolicyServerUrl, strEnrollmentPolicyServerID,
EnrollmentPolicyServerFlags, and authFlags) are not included in the InstallResponse method. They enable you to
add a property value to the installed certificate in much the same way as the
ICertPropertyEnrollmentPolicyServer interface does.

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Target Platform Windows

Header certenroll.h

See also
IX509Enrollment2
 IX509EnrollmentHelper interface (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The IX509EnrollmentHelper interface defines methods that enable a web application to enroll a certificate,
store policy server credentials in the credential cache, and register policy servers and enrollment servers.

Inheritance
The IX509EnrollmentHelper interface inherits from the IDispatch interface. IX509EnrollmentHelper also
has these types of members:

Methods
The IX509EnrollmentHelper interface has these methods.

IX509EnrollmentHelper::AddEnrollmentServer

Saves certificate enrollment server (CES) access credentials in the credential cache.

IX509EnrollmentHelper::AddPolicyServer

Registers a certificate enrollment policy (CEP) server and saves CEP access credentials in the credential cache.

IX509EnrollmentHelper::Enroll

Enrolls a certificate request and retrieves the issued certificate.

IX509EnrollmentHelper::Initialize

Initializes an IX509EnrollmentHelper object.

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Target Platform Windows

Header certenroll.h
 IX509EnrollmentHelper::AddEnrollmentServer
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The AddEnrollmentSer ver method saves certificate enrollment server (CES) access credentials in the
credential cache. This method is web enabled.

Syntax
HRESULT AddEnrollmentServer(
[in] BSTR strEnrollmentServerURI,
[in] X509EnrollmentAuthFlags authFlags,
[in] BSTR strCredential,
[in] BSTR strPassword
);

Parameters
[in] strEnrollmentServerURI

A BSTR that contains the certificate enrollment server URL.

[in] authFlags

An X509EnrollmentAuthFlags enumeration value that specifies the client authentication type. This can be one of
the following values.

VA L UE M EA N IN G

Anonymous authentication. Set the strCredential and

X509AuthAnonymous strPassword parameters to NULL .

Kerberos authentication. Set the strCredential and

X509AuthKerberos strPassword parameters to NULL .

Clear text user name and password authentication. Set the

X509AuthUsername strCredential and strPassword parameters to the user name
and associated password. These strings are encrypted before
transmission and are stored securely in the credential vault
on the certificate enrollment server.

Client authentication certificate installed on the local

X509AuthCer tificate computer and used by the server to verify the identity of the
client. Set the strPassword parameter to NULL and set the
certificate thumbprint, a 20-byte SHA1 hash of the
certificate, in the strCredential parameter.

[in] strCredential

A BSTR that contains the credential.

[in] strPassword
A BSTR that contains a clear text password.

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. Possible values include, but are not
limited to, those in the following table. For a list of common error codes, see Common HRESULT Values.

RET URN C O DE DESC RIP T IO N

The strEnrollmentServerURI parameter cannot be NULL or

E_INVALIDARG empty.
If X509AuthAnonymous or X509AuthKerberos is
specified in the authFlags parameter, the strCredential
parameter must not be NULL .
If X509AuthCertificate is specified in the authFlags
parameter, the strCredential parameter must be NULL .
If X509AuthCertificateis specified in the authFlags
parameter, the strPassword parameter must be NULL ,
but strCredential parameter must not be.

The strPassword, strCredential, or strEnrollmentServerURI

HRESULT_FROM_WIN32(ERROR_ARITHMETIC_OVERF parameters exceed 64,000 characters or contain embedded
LOW) null characters.

Remarks
The strCredential and strPassword arguments change depending on the value specified in the authFlags
argument as shown in the following table.

FL A G PA RA M ET ER ST RC REDEN T IA L PA RA M ET ER ST RP A SSWO RD PA RA M ET ER

X509AuthAnonymous NULL NULL

X509AuthKerberos NULL NULL

X509AuthUsername Clear text user name recognized by the Clear text password associated with
CEP server. the user name.

X509AuthCertificate Contains a 20 byte SHA-1 hash NULL

(thumbprint) of the certificate.

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Target Platform Windows

 Header certenroll.h

See also
IX509EnrollmentHelper
 IX509EnrollmentHelper::AddPolicyServer method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The AddPolicySer ver method registers a certificate enrollment policy (CEP) server and saves CEP access
credentials in the credential cache. This method is web enabled.

Syntax
HRESULT AddPolicyServer(
[in] BSTR strEnrollmentPolicyServerURI,
[in] BSTR strEnrollmentPolicyID,
[in] PolicyServerUrlFlags EnrollmentPolicyServerFlags,
[in] X509EnrollmentAuthFlags authFlags,
[in] BSTR strCredential,
[in] BSTR strPassword
);

Parameters
[in] strEnrollmentPolicyServerURI

A BSTR that contains the certificate enrollment policy server URL.

[in] strEnrollmentPolicyID

A BSTR that contains the certificate enrollment policy server ID. The ID can be any string. It is set by the
administrator who installs the CEP server.
[in] EnrollmentPolicyServerFlags

A PolicyServerUrlFlags enumeration value. For the AddPolicySer ver function, you can specify a bitwise OR of
the following values.

VA L UE M EA N IN G

Automatic certificate enrollment is enabled.

PsfAutoEnrollmentEnabled

Specifies that the certificate of the issuing CA need not be

PsfAllowUnTrustedCA trusted by the client to install a certificate signed by the CA.

[in] authFlags

An X509EnrollmentAuthFlags enumeration value that specifies the client authentication type. This can be one of
the following values.

VA L UE M EA N IN G

Anonymous authentication. Set the strCredential and

X509AuthAnonymous strPassword parameters to NULL .
 Kerberos authentication. Set the strCredential and
X509AuthKerberos strPassword parameters to NULL .

Clear text user name and password authentication. Set the

X509AuthUsername strCredential and strPassword parameters to the user name
and associated password. These strings are encrypted before
transmission and are stored securely in the credential vault
on the CEP server.

Client authentication certificate installed on the local

X509AuthCer tificate computer and used by the server to verify the identity of the
client. Set the strPassword parameter to NULL and set the
certificate thumbprint, a 20-byte SHA1 hash of the
certificate, in the strCredential parameter.

[in] strCredential

A BSTR that contains the credential.

[in] strPassword

A BSTR that contains a clear text password.

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. Possible values include, but are not
limited to, those in the following table. For a list of common error codes, see Common HRESULT Values.

RET URN C O DE DESC RIP T IO N

The strEnrollmentPolicyServerURI, strCredential, or

E_INVALIDARG strPassword parameters cannot be NULL or empty.

The strPassword, strCredential, or strEnrollmentServerURI

HRESULT_FROM_WIN32(ERROR_ARITHMETIC_OVERF parameters exceed 64,000 characters or contain embedded
LOW) null characters.

Remarks
The strCredential and strPassword arguments change depending on the value specified in the authFlags
argument as shown in the following table.

FL A G PA RA M ET ER ST RC REDEN T IA L PA RA M ET ER ST RP A SSWO RD PA RA M ET ER

X509AuthAnonymous NULL NULL

X509AuthKerberos NULL NULL

X509AuthUsername Clear text user name recognized by the Clear text password associated with
CEP server. the user name.

X509AuthCertificate Contains a 20 byte SHA-1 hash NULL

(thumbprint) of the certificate.
Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Target Platform Windows

Header certenroll.h

See also
IX509EnrollmentHelper
 IX509EnrollmentHelper::Enroll method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Enroll method enrolls a certificate request and retrieves the issued certificate. This method is web enabled.

Syntax
HRESULT Enroll(
[in] BSTR strEnrollmentPolicyServerURI,
[in] BSTR strTemplateName,
[in] EncodingType Encoding,
[in] WebEnrollmentFlags enrollFlags,
[out, retval] BSTR *pstrCertificate
);

Parameters
[in] strEnrollmentPolicyServerURI

A BSTR that contains the certificate enrollment policy server URL.

[in] strTemplateName

A BSTR variable that contains the Common Name (CN) of the template as it appears in Active Directory or the
dotted decimal object identifier.
[in] Encoding

An EncodingType enumeration value that specifies the type of encoding applied to a byte array for display
purposes.
[in] enrollFlags

A WebEnrollmentFlags enumeration value that specifies web enrollment behavior. This can be the following
value.

VA L UE M EA N IN G

If this flag is set and no authentication credential is available

EnrollPrompt for the certificate enrollment server, the certificate service
prompts for a credential. If there is no authentication
credential and this flag is not set, the Enroll method fails.

[out, retval] pstrCertificate

A BSTR that contains the issued certificate.

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. Possible values include, but are not
limited to, those in the following table. For a list of common error codes, see Common HRESULT Values.
 RET URN C O DE DESC RIP T IO N

The strEnrollmentPolicyServerURI and strTemplateName

E_INVALIDARG parameters cannot be NULL .

The strEnrollmentPolicyServerURI and strTemplateName

HRESULT_FROM_WIN32(ERROR_ARITHMETIC_OVERF parameters exceed 64,000 characters or contain embedded
LOW) null characters.

Remarks
The Enroll method retrieves the appropriate template, calls InitializeFromTemplate, and then calls Enroll on the
IX509Enrollment object.
This method does not installed the issued certificate.

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Target Platform Windows

Header certenroll.h

See also
IX509EnrollmentHelper
 IX509EnrollmentHelper::Initialize method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Initialize method initializes an IX509EnrollmentHelper object.

Syntax
HRESULT Initialize(
[in] X509CertificateEnrollmentContext Context
);

Parameters
[in] Context

An X509CertificateEnrollmentContext enumeration value that specifies the nature of the end entity for which the
issued certificate is intended. This can be one of the following values.

VA L UE M EA N IN G

The certificate is intended for an end user.

ContextUser

The certificate is intended for a computer.

ContextMachine

The certificate is being requested by an administrator acting

ContextAdministratorForceMachine on the behalf of a computer.

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. Possible values include, but are not
limited to, those in the following table. For a list of common error codes, see Common HRESULT Values.

RET URN C O DE DESC RIP T IO N

The object has already been initialized.

HRESULT_FROM_WIN32(ERROR_ALREADY_INITIALIZE
D

Requirements
 Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Target Platform Windows

Header certenroll.h

See also
IX509EnrollmentHelper
 IX509EnrollmentPolicyServer interface (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The IX509EnrollmentPolicySer ver interface represents a certificate enrollment policy (CEP) server.

Inheritance
The IX509EnrollmentPolicySer ver interface inherits from the IDispatch interface.
IX509EnrollmentPolicySer ver also has these types of members:

Methods
The IX509EnrollmentPolicySer ver interface has these methods.

IX509EnrollmentPolicyServer::Export

Exports templates and object identifiers associated with the certificate enrollment policy (CEP) server to a buffer.

IX509EnrollmentPolicyServer::get_Cost

Specifies and retrieves an arbitrary cost for contacting the certificate enrollment policy server.

IX509EnrollmentPolicyServer::GetAllowUnTrustedCA

Retrieves a value that specifies whether to allow an untrusted certification authority certificate.

IX509EnrollmentPolicyServer::GetAuthFlags

Retrieves a value that specifies the authentication type used by the client to authenticate itself to the certificate enrollment
policy (CEP) server.

IX509EnrollmentPolicyServer::GetCacheDir

Retrieves the name of the directory on the certificate enrollment policy (CEP) server that contains the policy cache file.

IX509EnrollmentPolicyServer::GetCachePath

Retrieves the path of the policy cache file on the certificate enrollment policy (CEP) server.

IX509EnrollmentPolicyServer::GetCAs

Retrieves a collection of certification enrollment servers included in the policy.

IX509EnrollmentPolicyServer::GetCAsForTemplate

Retrieves a collection of certificate enrollment servers that support a specified template.

IX509EnrollmentPolicyServer::GetCustomOids

Is not implemented.
IX509EnrollmentPolicyServer::GetFriendlyName

Retrieves a display name for the certificate enrollment policy (CEP) server.

IX509EnrollmentPolicyServer::GetIsDefaultCEP

Retrieves a Boolean value that specifies whether this is the default certificate enrollment policy (CEP) server.

IX509EnrollmentPolicyServer::GetLastUpdateTime

Retrieves the date and time at which the policy was last downloaded.

IX509EnrollmentPolicyServer::GetNextUpdateTime

Retrieves the date and time at which the policy expires and should be refreshed.

IX509EnrollmentPolicyServer::GetPolicyServerId

Retrieves a string value that uniquely identifies the certificate enrollment policy (CEP) server.

IX509EnrollmentPolicyServer::GetPolicyServerUrl

Retrieves a string value that contains the URL for the certificate enrollment policy (CEP) server.

IX509EnrollmentPolicyServer::GetTemplates

Retrieves a collection of the templates supported by the certificate enrollment policy (CEP) server.

IX509EnrollmentPolicyServer::GetUseClientId

Retrieves a value that specifies whether the ClientId attribute is set in the policy server flags of the certificate enrollment policy
(CEP) server.

IX509EnrollmentPolicyServer::Initialize

Initializes an IX509EnrollmentPolicyServer object.

IX509EnrollmentPolicyServer::InitializeImport

Initializes the certificate enrollment policy (CEP) server from a collection of templates and object identifiers.

IX509EnrollmentPolicyServer::LoadPolicy

Retrieves policy information from the certificate enrollment policy (CEP) server.

IX509EnrollmentPolicyServer::put_Cost

Specifies and retrieves an arbitrary cost for contacting the certificate enrollment policy server.

IX509EnrollmentPolicyServer::QueryChanges

Retrieves a value that specifies whether the template or certification authority collections have changed in Active Directory.
 IX509EnrollmentPolicyServer::SetCredential

Sets the credential used to contact the certificate enrollment policy (CEP) server.

IX509EnrollmentPolicyServer::Validate

Validates the current policy information.

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Target Platform Windows

Header certenroll.h
 IX509EnrollmentPolicyServer::Export method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Expor t method exports templates and object identifiers associated with the certificate enrollment policy
(CEP) server to a buffer.

Syntax
HRESULT Export(
[in] X509EnrollmentPolicyExportFlags exportFlags,
[out, retval] VARIANT *pVal
);

Parameters
[in] exportFlags

An X509EnrollmentPolicyExportFlags enumeration value that specifies what to export. This can be a bitwise OR
of the following values.

VA L UE M EA N IN G

Export templates.
Expor tTemplates

Export custom object identifiers.

Expor tOIDs

[out, retval] pVal

Pointer to a VARIANT of type VT_ARRAY|VT_UI1 that receives the templates and object identifiers.

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. Possible values include, but are not
limited to, those in the following table. For a list of common error codes, see Common HRESULT Values.

RET URN C O DE DESC RIP T IO N

The pVal parameter must not be NULL .

E_POINTER

The exportFlags parameter must contain Expor tTemplates

HRESULT_FROM_WIN32(ERROR_NOT_SUPPORTED) or Expor tOIDs .
 The IX509EnrollmentPolicyServer has not been initialized.
OLE_E_BL ANK

Remarks
To prevent memory leaks, you must free the VARIANT returned by this function.
You must call LoadPolicy before calling this function and after calling Initialize for the exported data to be
meaningful.

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Target Platform Windows

Header certenroll.h

See also
IX509EnrollmentPolicyServer
 IX509EnrollmentPolicyServer::get_Cost method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Cost property specifies and retrieves an arbitrary cost for contacting the certificate enrollment policy
server.
This property is read/write.

Syntax
HRESULT get_Cost(
DWORD *pValue
);

Parameters
pValue

Return value
None

Remarks
If multiple CEP servers have the same ID value (specified when the Initialize method is called), the server with
the lowest cost is contacted first.

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Target Platform Windows

Header certenroll.h

See also
IX509EnrollmentPolicyServer
 IX509EnrollmentPolicyServer::GetAllowUnTrustedCA
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The GetAllowUnTrustedCA method retrieves a value that specifies whether to allow an untrusted certification
authority certificate. This value is set by the Initialize method.

Syntax
HRESULT GetAllowUnTrustedCA(
[out, retval] VARIANT_BOOL *pValue
);

Parameters
[out, retval] pValue

Pointer to a Boolean value that specifies whether to allow the certificate.

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. Possible values include, but are not
limited to, those in the following table. For a list of common error codes, see Common HRESULT Values.

RET URN C O DE DESC RIP T IO N

The pValue parameter cannot be NULL .

E_POINTER

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Target Platform Windows

Header certenroll.h

See also
IX509EnrollmentPolicyServer
 IX509EnrollmentPolicyServer::GetAuthFlags method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The GetAuthFlags method retrieves a value that specifies the authentication type used by the client to
authenticate itself to the certificate enrollment policy (CEP) server. This value is set by the Initialize method on
the ICertPropertyEnrollmentPolicyServer interface.

Syntax
HRESULT GetAuthFlags(
[out, retval] X509EnrollmentAuthFlags *pValue
);

Parameters
[out, retval] pValue

Pointer to an X509EnrollmentAuthFlags enumeration value that specifies the authentication type. This can be
one of the following values.

VA L UE M EA N IN G

Anonymous authentication.
X509AuthAnonymous

Kerberos authentication.
X509AuthKerberos

Clear text user name and password authentication.

X509AuthUsername

Client authentication certificate installed on the local

X509AuthCer tificate computer and used by the server to verify the identity of the
client.

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. Possible values include, but are not
limited to, those in the following table. For a list of common error codes, see Common HRESULT Values.

RET URN C O DE DESC RIP T IO N

The pValue parameter cannot be NULL .

E_POINTER
Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Target Platform Windows

Header certenroll.h

See also
IX509EnrollmentPolicyServer
 IX509EnrollmentPolicyServer::GetCacheDir method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The GetCacheDir method retrieves the name of the directory on the certificate enrollment policy (CEP) server
that contains the policy cache file.

Syntax
HRESULT GetCacheDir(
[out, retval] BSTR *pValue
);

Parameters
[out, retval] pValue

Pointer to a BSTR that receives the directory name.

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. Possible values include, but are not
limited to, those in the following table. For a list of common error codes, see Common HRESULT Values.

RET URN C O DE DESC RIP T IO N

The cache directory could not be found.

CERTSRV_E_PROPERTY_EMPTY

The pValue parameter must not be NULL .

E_POINTER

The IX509EnrollmentPolicyServer has not been initialized.

OLE_E_BL ANK

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Target Platform Windows

 Header certenroll.h

See also
IX509EnrollmentPolicyServer
 IX509EnrollmentPolicyServer::GetCachePath
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The GetCachePath method retrieves the path of the policy cache file on the certificate enrollment policy (CEP)
server.

Syntax
HRESULT GetCachePath(
[out, retval] BSTR *pValue
);

Parameters
[out, retval] pValue

Pointer to a BSTR that receives the path.

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. Possible values include, but are not
limited to, those in the following table. For a list of common error codes, see Common HRESULT Values.

RET URN C O DE DESC RIP T IO N

The cache path could not be found.

CERTSRV_E_PROPERTY_EMPTY

The pValue parameter must not be NULL .

E_POINTER

The IX509EnrollmentPolicyServer has not been initialized.

OLE_E_BL ANK

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Target Platform Windows

 Header certenroll.h

See also
IX509EnrollmentPolicyServer
 IX509EnrollmentPolicyServer::GetCAs method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The GetCAs method retrieves a collection of certification enrollment servers included in the policy.

Syntax
HRESULT GetCAs(
[out, retval] ICertificationAuthorities **ppCAs
);

Parameters
[out, retval] ppCAs

Address of a variable that receives a pointer to an ICertificationAuthorities interface that represents the
collection.

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. Possible values include, but are not
limited to, those in the following table. For a list of common error codes, see Common HRESULT Values.

RET URN C O DE DESC RIP T IO N

The IX509EnrollmentPolicyServer object has not been

OLE_E_BL ANK initialized.

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Target Platform Windows

Header certenroll.h

See also
IX509EnrollmentPolicyServer
 IX509EnrollmentPolicyServer::GetCAsForTemplate
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The GetCAsForTemplate method retrieves a collection of certificate enrollment servers that support a
specified template.

Syntax
HRESULT GetCAsForTemplate(
[in] IX509CertificateTemplate *pTemplate,
[out, retval] ICertificationAuthorities **ppCAs
);

Parameters
[in] pTemplate

Pointer to an IX509CertificateTemplate interface that represents the template.

[out, retval] ppCAs

Address of a variable that receives a pointer to an ICertificationAuthorities interface that represents the server
collection.

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. Possible values include, but are not
limited to, those in the following table. For a list of common error codes, see Common HRESULT Values.

RET URN C O DE DESC RIP T IO N

The IX509EnrollmentPolicyServer object has not been

OLE_E_BL ANK initialized.

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Target Platform Windows

Header certenroll.h
See also
IX509EnrollmentPolicyServer
 IX509EnrollmentPolicyServer::GetCustomOids
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The GetCustomOids method is not implemented.

Syntax
HRESULT GetCustomOids(
[out, retval] IObjectIds **ppObjectIds
);

Parameters
[out, retval] ppObjectIds

Not used.

Return value
This function is not currently implemented and always returns E_NOTIMPL.

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Target Platform Windows

Header certenroll.h

See also
IX509EnrollmentPolicyServer
 IX509EnrollmentPolicyServer::GetFriendlyName
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The GetFriendlyName method retrieves a display name for the certificate enrollment policy (CEP) server.

Syntax
HRESULT GetFriendlyName(
[out, retval] BSTR *pValue
);

Parameters
[out, retval] pValue

Pointer to a BSTR variable that contains the display name.

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. Possible values include, but are not
limited to, those in the following table. For a list of common error codes, see Common HRESULT Values.

RET URN C O DE DESC RIP T IO N

The display name could not be found.

CERTSRV_E_PROPERTY_EMPTY

There was not sufficient memory available for the string

E_OUTOFMEMORY specified in the pValue parameter.

The pValue parameter cannot be NULL .

E_POINTER

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Target Platform Windows

Header certenroll.h
See also
IX509EnrollmentPolicyServer
 IX509EnrollmentPolicyServer::GetIsDefaultCEP
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The GetIsDefaultCEP method retrieves a Boolean value that specifies whether this is the default certificate
enrollment policy (CEP) server.

Syntax
HRESULT GetIsDefaultCEP(
[out, retval] VARIANT_BOOL *pValue
);

Parameters
[out, retval] pValue

Pointer to a Boolean value that specifies whether this is the default server.

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.

Remarks
The default server is set by the Initialize method on the ICertPropertyEnrollmentPolicyServer interface.

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Target Platform Windows

Header certenroll.h

See also
IX509EnrollmentPolicyServer
 IX509EnrollmentPolicyServer::GetLastUpdateTime
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The GetLastUpdateTime method retrieves the date and time at which the policy was last downloaded.

Syntax
HRESULT GetLastUpdateTime(
[out, retval] DATE *pDate
);

Parameters
[out, retval] pDate

Pointer to a DATE value that identifies the time.

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. Possible values include, but are not
limited to, those in the following table. For a list of common error codes, see Common HRESULT Values.

RET URN C O DE DESC RIP T IO N

The value could not be found.

CERTSRV_E_PROPERTY_EMPTY

The pDate parameter cannot be NULL .

E_POINTER

Remarks
The date is stored as an 8-byte real value that represents a Coordinated Universal Time (Greenwich Mean Time)
value between January 1, 1900 and December 31, 9999, inclusive. The value 2.0 represents January 1, 1900; 3.0
represents January 2, 1900. Adding 1 to the value increments the date by a day. The fractional part of the value
represents the time of day. Therefore, 2.5 represents 12:00 on January 1, 1900; 3.25 represents 06:00 on
January 2, 1900.

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]
 Target Platform Windows

Header certenroll.h

See also
IX509EnrollmentPolicyServer
 IX509EnrollmentPolicyServer::GetNextUpdateTime
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The GetNextUpdateTime method retrieves the date and time at which the policy expires and should be
refreshed.

Syntax
HRESULT GetNextUpdateTime(
[out, retval] DATE *pDate
);

Parameters
[out, retval] pDate

Pointer to a DATE value that identifies the time.

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. Possible values include, but are not
limited to, those in the following table. For a list of common error codes, see Common HRESULT Values.

RET URN C O DE DESC RIP T IO N

The value could not be found.

CERTSRV_E_PROPERTY_EMPTY

The pDate parameter cannot be NULL .

E_POINTER

Remarks
The date is stored as an 8-byte real value that represents a Coordinated Universal Time (Greenwich Mean Time)
value between January 1, 1900 and December 31, 9999, inclusive. The value 2.0 represents January 1, 1900; 3.0
represents January 2, 1900. Adding 1 to the value increments the date by a day. The fractional part of the value
represents the time of day. Therefore, 2.5 represents 12:00 on January 1, 1900; 3.25 represents 06:00 on
January 2, 1900.

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

 Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Target Platform Windows

Header certenroll.h

See also
IX509EnrollmentPolicyServer
 IX509EnrollmentPolicyServer::GetPolicyServerId
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The GetPolicySer verId method retrieves a string value that uniquely identifies the certificate enrollment policy
(CEP) server. This value is set in the Initialize method.

Syntax
HRESULT GetPolicyServerId(
[out, retval] BSTR *pValue
);

Parameters
[out, retval] pValue

Pointer to a BSTR variable that contains the ID string.

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. Possible values include, but are not
limited to, those in the following table. For a list of common error codes, see Common HRESULT Values.

RET URN C O DE DESC RIP T IO N

The ID could not be found.

CERTSRV_E_PROPERTY_EMPTY

There was not sufficient memory available for the string

E_OUTOFMEMORY specified in the pValue parameter.

The pValue parameter cannot be NULL .

E_POINTER

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Target Platform Windows

 Header certenroll.h

See also
IX509EnrollmentPolicyServer
 IX509EnrollmentPolicyServer::GetPolicyServerUrl
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The GetPolicySer verUrl method retrieves a string value that contains the URL for the certificate enrollment
policy (CEP) server. This value is set in the Initialize method.

Syntax
HRESULT GetPolicyServerUrl(
[out, retval] BSTR *pValue
);

Parameters
[out, retval] pValue

Pointer to a BSTR variable that contains the URL.

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. Possible values include, but are not
limited to, those in the following table. For a list of common error codes, see Common HRESULT Values.

RET URN C O DE DESC RIP T IO N

The URL could not be found.

CERTSRV_E_PROPERTY_EMPTY

There was not sufficient memory available for the string

E_OUTOFMEMORY specified in the pValue parameter.

The pValue parameter cannot be NULL .

E_POINTER

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Target Platform Windows

 Header certenroll.h

See also
IX509EnrollmentPolicyServer
 IX509EnrollmentPolicyServer::GetTemplates method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The GetTemplates method retrieves a collection of the templates supported by the certificate enrollment policy
(CEP) server.

Syntax
HRESULT GetTemplates(
[out, retval] IX509CertificateTemplates **pTemplates
);

Parameters
[out, retval] pTemplates

Address of a variable that receives a pointer to an IX509CertificateTemplates interface that represents the
template collection.

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. Possible values include, but are not
limited to, those in the following table. For a list of common error codes, see Common HRESULT Values.

RET URN C O DE DESC RIP T IO N

The IX509EnrollmentPolicyServer object has not been

OLE_E_BL ANK initialized.

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Target Platform Windows

Header certenroll.h

See also
IX509EnrollmentPolicyServer
 IX509EnrollmentPolicyServer::GetUseClientId
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The GetUseClientId method retrieves a value that specifies whether the ClientId attribute is set in the policy
server flags of the certificate enrollment policy (CEP) server.

Syntax
HRESULT GetUseClientId(
[out, retval] VARIANT_BOOL *pValue
);

Parameters
[out, retval] pValue

Pointer to a Boolean value that specifies whether the PsfUseClientId bit is set on the PolicyServerUrlFlags
enumeration for this certificate enrollment policy (CEP) server.

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. Possible values include, but are not
limited to, those in the following table. For a list of common error codes, see Common HRESULT Values.

RET URN C O DE DESC RIP T IO N

The pValue parameter cannot be NULL .

E_POINTER

Remarks
This method returns VARIANT_TRUE if the PsfUseClientId bit is set on the PolicyServerUrlFlags enumeration
for this CEP server. If this flag is set, the ClientID attribute is included in certificate requests during the
enrollment process and can be used by the certification authority for diagnostic or auditing purposes. Examples
of the type of information included in this attribute include the name of the cryptographic service provider, the
Windows version number, the user name, the computer DNS name, and the domain controller DNS name.

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]
 Target Platform Windows

Header certenroll.h

See also
IX509EnrollmentPolicyServer
 IX509EnrollmentPolicyServer::Initialize method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Initialize method initializes an IX509EnrollmentPolicyServer object.

Syntax
HRESULT Initialize(
[in] BSTR bstrPolicyServerUrl,
[in] BSTR bstrPolicyServerId,
[in] X509EnrollmentAuthFlags authFlags,
[in] VARIANT_BOOL fIsUnTrusted,
[in] X509CertificateEnrollmentContext context
);

Parameters
[in] bstrPolicyServerUrl

A BSTR variable that contains the URL for the certificate enrollment policy server.
[in] bstrPolicyServerId

A BSTR variable that contains a unique ID for the certificate enrollment policy server. If this value is not NULL , it
must match the ID string returned by the CEP response.
[in] authFlags

An X509EnrollmentAuthFlags enumeration value that specifies the client authentication type. This can be one of
the following values.

VA L UE M EA N IN G

Anonymous authentication.
X509AuthAnonymous

Kerberos authentication.
X509AuthKerberos

Clear text user name and password authentication.

X509AuthUsername
Note The user name and password are encrypted before
transmission and are stored securely in the credential vault
on the CEP server.

Client authentication certificate installed on the local

X509AuthCer tificate computer and used by the server to verify the identity of the
client.
[in] fIsUnTrusted

A Boolean value that specifies whether to allow an untrusted certification authority certificates.
[in] context

An X509CertificateEnrollmentContext enumeration value that specifies the nature of the end entity for which
certificate enrollment is intended. This can be one of the following values.

VA L UE M EA N IN G

The certificate is intended for an end user.

ContextUser

The certificate is intended for a computer.

ContextMachine

The certificate is being requested by an administrator acting

ContextAdministratorForceMachine on the behalf of a computer.

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. Possible values include, but are not
limited to, those in the following table. For a list of common error codes, see Common HRESULT Values.

RET URN C O DE DESC RIP T IO N

The bstrPolicyServerUrl parameter cannot be an empty

E_INVALIDARG string and must represent an HTTPS URL.

There was not sufficient memory available for the strings

E_OUTOFMEMORY specified in the bstrPolicyServerUrl or bstrPolicyServerId
parameters.

The IX509EnrollmentPolicyServer object has already been

HRESULT_FROM_WIN32(ERROR_ALREADY_INITIALIZE initialized.
D)

The value specified in the bstrPolicyServerId parameter is not

HRESULT_FROM_WIN32(ERROR_INVALID_DATA) NULL and does not equal the existing CEP ID value on the
CEP server.

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Target Platform Windows

 Header certenroll.h

See also
IX509EnrollmentPolicyServer
 IX509EnrollmentPolicyServer::InitializeImport
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The InitializeImpor t method initializes the certificate enrollment policy (CEP) server from a collection of
templates and object identifiers.

Syntax
HRESULT InitializeImport(
[in] VARIANT val
);

Parameters
[in] val

A VARIANT of type VT_ARRAY|VT_UI1 that contains the templates and object identifiers.

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. Possible values include, but are not
limited to, those in the following table. For a list of common error codes, see Common HRESULT Values.

RET URN C O DE DESC RIP T IO N

The IX509EnrollmentPolicyServer object has already been

HRESULT_FROM_WIN32(ERROR_ALREADY_INITIALIZE initialized.
D)

The VARIANT in the val parameter is not of type

HRESULT_FROM_WIN32(ERROR_INVALID_PARAMETE VT_ARRAY .
R)

Remarks
Call this method to import templates and OIDs previously written to a buffer by the Export method.

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]
 Target Platform Windows

Header certenroll.h

See also
IX509EnrollmentPolicyServer
 IX509EnrollmentPolicyServer::LoadPolicy method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The LoadPolicy method retrieves policy information from the certificate enrollment policy (CEP) server.

Syntax
HRESULT LoadPolicy(
[in] X509EnrollmentPolicyLoadOption option
);

Parameters
[in] option

A value of the X509EnrollmentPolicyLoadOption enumeration that specifies how to retrieve policy from the
policy server. This can be one of the following values.

VA L UE M EA N IN G

Reload if the cache has expired.

LoadOptionDefault

Always load from the cache even if it has expired. This option
LoadOptionCacheOnly is not currently supported.

Always reload.
LoadOptionReload

Registers a thread to update a sequence number if there are

LoadOptionRegisterForADChanges changes to the template or the certification authority
container. This value applies only to an Active Directory
policy server.

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. Possible values include, but are not
limited to, those in the following table. For a list of common error codes, see Common HRESULT Values.

RET URN C O DE DESC RIP T IO N

The load option requested in the option parameter does not

E_INVALIDARG match any supported by the CEP server or you specified
LoadOptionCacheOnly in the option parameter.
 There was a problem with the lightweight directory access
E_NOT_VALID_STATE protocol (LDAP) used to locate the CEP server.

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Target Platform Windows

Header certenroll.h

See also
IX509EnrollmentPolicyServer
 IX509EnrollmentPolicyServer::put_Cost method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Cost property specifies and retrieves an arbitrary cost for contacting the certificate enrollment policy
server.
This property is read/write.

Syntax
HRESULT put_Cost(
DWORD value
);

Parameters
value

Return value
None

Remarks
If multiple CEP servers have the same ID value (specified when the Initialize method is called), the server with
the lowest cost is contacted first.

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Target Platform Windows

Header certenroll.h

See also
IX509EnrollmentPolicyServer
 IX509EnrollmentPolicyServer::QueryChanges
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Quer yChanges method retrieves a value that specifies whether the template or certification authority
collections have changed in Active Directory.

Syntax
HRESULT QueryChanges(
[out, retval] VARIANT_BOOL *pValue
);

Parameters
[out, retval] pValue

Pointer to a Boolean value that specifies whether the collections have changed.

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. Possible values include, but are not
limited to, those in the following table. For a list of common error codes, see Common HRESULT Values.

RET URN C O DE DESC RIP T IO N

LoadOptionRegisterForADChanges was not specified in the

E_NOT_VALID_STATE option parameter of the LoadPolicy method.

The pValue parameter cannot be NULL .

E_POINTER

The IX509EnrollmentPolicyServer object has not been

OLE_E_BL ANK initialized.

Remarks
The Quer yChanges method is relevant only when you specify LoadOptionRegisterForADChanges in the
option parameter of the LoadPolicy method. The method returns VARIANT_TRUE for either of the following
cases:
The template collection in Active Directory has changed since the last time GetTemplates was called.
The certification authority collection in Active Directory has changed since the last time GetCAs was called.

Requirements
 Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Target Platform Windows

Header certenroll.h

See also
IX509EnrollmentPolicyServer
 IX509EnrollmentPolicyServer::SetCredential method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The SetCredential method sets the credential used to contact the certificate enrollment policy (CEP) server.

Syntax
HRESULT SetCredential(
[in] LONG hWndParent,
[in] X509EnrollmentAuthFlags flag,
[in] BSTR strCredential,
[in] BSTR strPassword
);

Parameters
[in] hWndParent

Parent window handle.

[in] flag

An X509EnrollmentAuthFlags enumeration value that specifies the authentication type. This can be one of the
following values.

VA L UE M EA N IN G

Anonymous authentication. Set the strCredential and

X509AuthAnonymous strPassword parameters to NULL .

Kerberos authentication. Set the strCredential and

X509AuthKerberos strPassword parameters to NULL .

Clear text user name and password authentication. Set the

X509AuthUsername strCredential and strPassword parameters to the user name
and associated password. These strings are encrypted before
transmission and are stored securely in the credential vault
on the CEP server.

Client authentication certificate installed on the local

X509AuthCer tificate computer and used by the server to verify the identity of the
client. Set the strPassword parameter to NULL and set the
certificate thumbprint, a 20-byte SHA1 hash of the
certificate, in the strCredential parameter.

[in] strCredential

A BSTR variable that contains the credential.

[in] strPassword
A BSTR variable that contains the password.

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. Possible values include, but are not
limited to, those in the following table. For a list of common error codes, see Common HRESULT Values.

RET URN C O DE DESC RIP T IO N

The flag parameter is not a supported value.

E_INVALIDARG

Remarks
The strCredential and strPassword arguments will change depending on the value specified in the flag argument
as shown in the following table.

FL A G PA RA M ET ER ST RC REDEN T IA L PA RA M ET ER ST RP A SSWO RD PA RA M ET ER

X509AuthAnonymous NULL NULL

X509AuthKerberos NULL NULL

X509AuthUsername Clear text user name recognized by the Clear text password associated with
CEP server. the user name.

X509AuthCertificate Contains a 20 byte SHA-1 hash NULL

(thumbprint) of the certificate.

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Target Platform Windows

Header certenroll.h

See also
IX509EnrollmentPolicyServer
 IX509EnrollmentPolicyServer::Validate method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Validate method validates the current policy information.

Syntax
HRESULT Validate();

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. Possible values include, but are not
limited to, those in the following table. For a list of common error codes, see Common HRESULT Values.

RET URN C O DE DESC RIP T IO N

There was a problem with the lightweight directory access

E_NOT_VALID_STATE protocol (LDAP) used to locate the CEP server.

The IX509EnrollmentPolicyServer has been initialized by

HRESULT_FROM_WIN32(ERROR_INVALID_STATE) calling the InitializeImport method.

Remarks
This method calls LoadPolicy with the input parameter set to LoadOptionReload .

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Target Platform Windows

Header certenroll.h

See also
IX509EnrollmentPolicyServer
 IX509EnrollmentStatus interface (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The IX509EnrollmentStatus interface can be used to specify or retrieve detailed error information about a
certificate enrollment transaction.

Inheritance
The IX509EnrollmentStatus interface inherits from the IDispatch interface. IX509EnrollmentStatus also has
these types of members:

Methods
The IX509EnrollmentStatus interface has these methods.

IX509EnrollmentStatus::AppendText

Appends a string to the status information contained in the Text property.

IX509EnrollmentStatus::get_Display

Specifies or retrieves a value that indicates whether to display the status information in a user interface.

IX509EnrollmentStatus::get_Error

Specifies and retrieves a value that identifies the error status of the certificate enrollment process.

IX509EnrollmentStatus::get_ErrorText

Retrieves a string that contains the message associated with the error result code returned by the Error property.

IX509EnrollmentStatus::get_Selected

Specifies or retrieves a value that indicates whether an item can be used during the enrollment process.

IX509EnrollmentStatus::get_Status

Specifies or retrieves a value that indicates the status of the enrollment process.

IX509EnrollmentStatus::get_Text

Specifies or retrieves a string that contains a message associated with the status of the enrollment process.

IX509EnrollmentStatus::put_Display

Specifies or retrieves a value that indicates whether to display the status information in a user interface.

IX509EnrollmentStatus::put_Error

Specifies and retrieves a value that identifies the error status of the certificate enrollment process.
 IX509EnrollmentStatus::put_Selected

Specifies or retrieves a value that indicates whether an item can be used during the enrollment process.

IX509EnrollmentStatus::put_Status

Specifies or retrieves a value that indicates the status of the enrollment process.

IX509EnrollmentStatus::put_Text

Specifies or retrieves a string that contains a message associated with the status of the enrollment process.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

See also
Certificate Enrollment API
IDispatch
IX509Enrollment
 IX509EnrollmentStatus::AppendText method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The AppendText method appends a string to the status information contained in the Text property.

Syntax
HRESULT AppendText(
[in] BSTR strText
);

Parameters
[in] strText

A BSTR variable that contains the text to add.

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509EnrollmentStatus
 IX509EnrollmentStatus::get_Display method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Display property specifies or retrieves a value that indicates whether to display the status information in a
user interface.
This property is read/write.

Syntax
HRESULT get_Display(
EnrollmentDisplayStatus *pValue
);

Parameters
pValue

Return value
None

Remarks
This property is used by the Certificate Enrollment wizard to determine whether to display the item with which it
is associated. Currently, setting this value does not affect enrollment behavior.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509EnrollmentStatus
 IX509EnrollmentStatus::get_Error method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Error property specifies and retrieves a value that identifies the error status of the certificate enrollment
process.
This property is read/write.

Syntax
HRESULT get_Error(
HRESULT *pValue
);

Parameters
pValue

Return value
None

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509EnrollmentStatus
 IX509EnrollmentStatus::get_ErrorText method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The ErrorText property retrieves a string that contains the message associated with the error result code
returned by the Error property.
This property is read-only.

Syntax
HRESULT get_ErrorText(
BSTR *pValue
);

Parameters
pValue

Return value
None

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509EnrollmentStatus
 IX509EnrollmentStatus::get_Selected method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Selected property specifies or retrieves a value that indicates whether an item can be used during the
enrollment process.
This property is read/write.

Syntax
HRESULT get_Selected(
EnrollmentSelectionStatus *pValue
);

Parameters
pValue

Return value
None

Remarks
This property is currently used only to identify which cryptographic provider/algorithm pairs can be used to
create a key. For more information, see the GetCspStatuses method on the IX509CertificateRequestPkcs10
interface.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509EnrollmentStatus
 IX509EnrollmentStatus::get_Status method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Status property specifies or retrieves a value that indicates the status of the enrollment process.
This property is read/write.

Syntax
HRESULT get_Status(
EnrollmentEnrollStatus *pValue
);

Parameters
pValue

Return value
None

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509EnrollmentStatus
 IX509EnrollmentStatus::get_Text method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Text property specifies or retrieves a string that contains a message associated with the status of the
enrollment process.
This property is read/write.

Syntax
HRESULT get_Text(
BSTR *pValue
);

Parameters
pValue

Return value
None

Remarks
You can call the AppendText method to add information to the message.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509EnrollmentStatus
 IX509EnrollmentStatus::put_Display method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Display property specifies or retrieves a value that indicates whether to display the status information in a
user interface.
This property is read/write.

Syntax
HRESULT put_Display(
EnrollmentDisplayStatus Value
);

Parameters
Value

Return value
None

Remarks
This property is used by the Certificate Enrollment wizard to determine whether to display the item with which it
is associated. Currently, setting this value does not affect enrollment behavior.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509EnrollmentStatus
 IX509EnrollmentStatus::put_Error method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Error property specifies and retrieves a value that identifies the error status of the certificate enrollment
process.
This property is read/write.

Syntax
HRESULT put_Error(
HRESULT Value
);

Parameters
Value

Return value
None

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509EnrollmentStatus
 IX509EnrollmentStatus::put_Selected method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Selected property specifies or retrieves a value that indicates whether an item can be used during the
enrollment process.
This property is read/write.

Syntax
HRESULT put_Selected(
EnrollmentSelectionStatus Value
);

Parameters
Value

Return value
None

Remarks
This property is currently used only to identify which cryptographic provider/algorithm pairs can be used to
create a key. For more information, see the GetCspStatuses method on the IX509CertificateRequestPkcs10
interface.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509EnrollmentStatus
 IX509EnrollmentStatus::put_Status method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Status property specifies or retrieves a value that indicates the status of the enrollment process.
This property is read/write.

Syntax
HRESULT put_Status(
EnrollmentEnrollStatus Value
);

Parameters
Value

Return value
None

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509EnrollmentStatus
 IX509EnrollmentStatus::put_Text method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Text property specifies or retrieves a string that contains a message associated with the status of the
enrollment process.
This property is read/write.

Syntax
HRESULT put_Text(
BSTR Value
);

Parameters
Value

Return value
None

Remarks
You can call the AppendText method to add information to the message.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509EnrollmentStatus
 IX509EnrollmentWebClassFactory interface
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The IX509EnrollmentWebClassFactor y interface can be used to create any of the following objects on a
webpage. These objects cannot be created directly inside a script. Only the
IX509EnrollmentWebClassFactor y can be directly created. You must call the CreateObject method for each
of the following:
ICertProperties
ICertPropertyDescription
ICertPropertyFriendlyName
ICspInformation
ICspInformations
ICspStatus
IObjectId
IObjectIds
IX500DistinguishedName
IX509CertificateRequestCmc
IX509CertificateRequestPkcs10
IX509CertificateRequestPkcs7
IX509Enrollment
IX509Extension
IX509ExtensionEnhancedKeyUsage
IX509ExtensionKeyUsage
IX509Extensions
IX509ExtensionTemplate
IX509ExtensionTemplateName
IX509PrivateKey
The CreateObject method suppresses most of the dialog boxes that Internet Explorer displays in zones with
limited trust.

Inheritance
The IX509EnrollmentWebClassFactor y interface inherits from the IDispatch interface.
IX509EnrollmentWebClassFactor y also has these types of members:

Methods
The IX509EnrollmentWebClassFactor y interface has these methods.

IX509EnrollmentWebClassFactory::CreateObject

Can be used to create an object in the user context on a webpage.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

See also
CertEnroll Interfaces
IDispatch
 IX509EnrollmentWebClassFactory::CreateObject
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The CreateObject method can be used to create an object in the user context on a webpage.

Syntax
HRESULT CreateObject(
[in] BSTR strProgID,
[out] IUnknown **ppIUnknown
);

Parameters
[in] strProgID

A BSTR variable that contains the Prog ID. The following table shows the strings you can use for each object that
can be created by using this method.

O B JEC T P RO G ID ST RIN G

"X509Enrollment.CCertProperties"
ICer tProper ties

"X509Enrollment.CCertPropertyDescription"
ICer tProper tyDescription

"X509Enrollment.CCertPropertyFriendlyName"
ICer tProper tyFriendlyName

"X509Enrollment.CCspInformation"
ICspInformation

"X509Enrollment.CCspInformations"
ICspInformations

"X509Enrollment.CCspStatus"
ICspStatus

"X509Enrollment.CObjectId"
IObjectId

"X509Enrollment.CObjectIds"
IObjectIds
 "X509Enrollment.CSignerCertificate"
ISignerCer tificate

"X509Enrollment.CX500DistinguishedName"
IX500DistinguishedName

"X509Enrollment.CX509CertificateRequestCmc"
IX509Cer tificateRequestCmc

"X509Enrollment.CX509CertificateRequestPkcs10"
IX509Cer tificateRequestPkcs10

"X509Enrollment.CX509CertificateRequestPkcs7"
IX509Cer tificateRequestPkcs7

"X509Enrollment.CX509Enrollment"
IX509Enrollment

"X509Enrollment.CX509EnrollmentHelper"
IX509EnrollmentHelper

"X509Enrollment.CX509Extension"
IX509Extension

"X509Enrollment.CX509ExtensionEnhancedKeyUsage"
IX509ExtensionEnhancedKeyUsage

"X509Enrollment.CX509ExtensionKeyUsage"
IX509ExtensionKeyUsage

"X509Enrollment.CX509Extensions"
IX509Extensions

"X509Enrollment.CX509ExtensionTemplate"
IX509ExtensionTemplate

"X509Enrollment.CX509ExtensionTemplateName"
IX509ExtensionTemplateName

"X509Enrollment.CX509PrivateKey"
IX509PrivateKey

[out] ppIUnknown

Address of a variable that receives a pointer to an IUnknown interface that represents the created object.

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. Possible values include, but are not
limited to, those in the following table. For a list of common error codes, see Common HRESULT Values.

RET URN C O DE DESC RIP T IO N

The Prog ID specified represents an object that cannot be

E_NOINTERFACE created by using this method.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509EnrollmentWebClassFactory
 IX509Extension interface (certenroll.h)
7/2/2022 • 4 minutes to read • Edit Online

The IX509Extension interface can be used to define an extension for a certificate request. Certificate extensions
provide information about key usage, certificate policies and constraints, alternative name forms, and more. An
extension consists of an object identifier (OID), a Boolean value that identifies whether the extension is critical,
and a byte array that contains the extension value as shown by the following Abstract Syntax Notation One
(ASN.1) syntax.

Extension ::= SEQUENCE

{
extnId OBJECT IDENTIFIER,
critical BOOLEAN DEFAULT FALSE,
extnValue OCTETSTRING
}

The Certificate Enrollment API contains the following interfaces, derived from IX509Extension , that you can
use to create the various extensions used most commonly in a public key infrastructure (PKI) that relies on a
Windows certificate server.

Note Do not use the IX509Extension base interface to represent any extension that can be represented by one of the
following interfaces. Enrollment behavior is undefined if the appropriate interface is not used.

IN T ERFA C E DESC RIP T IO N

IX509ExtensionAlternativeNames Defines an AlternativeNames extension that contains one

or more alternative name forms for the subject of the
certificate request.

IX509ExtensionAuthorityKeyIdentifier Defines an AuthorityKeyIdentifier extension that enables

identification of the certification authority public key that
corresponds to the certification authority private key that
signed an issued certificate. It is used by certificate path
building software on a Windows server to find the
certification authority certificate.

IX509ExtensionBasicConstraints Defines a BasicConstraints extension that identifies

whether the entity can be used as a certification authority
and, if so, the number of subordinate certification authorities
that can exist beneath it in the certificate chain.

IX509ExtensionCertificatePolicies Defines a Cer tificatePolicies extension that identifies the

policies under which the certificate has been issued and the
purposes for which it can be used.

IX509ExtensionEnhancedKeyUsage Defines an EnhancedKeyUsage extension that identifies

one or more uses of the public key contained in the
certificate.
 IX509ExtensionKeyUsage Defines a KeyUsage extension that restricts the operations
that can be performed by the public key contained in the
certificate.

IX509ExtensionMSApplicationPolicies Defines an MSApplicationPolicies extension that can be

used by an application to filter certificates on the basis of
permitted use. Permitted uses are identified by object
identifiers (OIDs).

IX509ExtensionSmimeCapabilities Defines an SmimeCapabilities extension that identifies the

decryption capabilities of an email recipient so that the
sender of the email can choose the most secure encryption
algorithm supported by both parties.

IX509ExtensionSubjectKeyIdentifier Defines a SubjectKeyIdentifier extension that

differentiates between multiple public keys held by the
certificate owner. The extension value is typically a SHA-1
hash of the key.

IX509ExtensionTemplate Defines a Template extension that identifies the version 2

template to use when issuing or renewing a certificate.

IX509ExtensionTemplateName Defines a TemplateName extension that identifies the

version 1 template to use when issuing or renewing a
certificate.

Most of the extensions that can be created by using the preceding interfaces are defined by the version 3 X.509
syntax standard. To create the version 3 extensions for which Microsoft does not provide a custom object, you
can use the IX509Extension interface. These extensions are identified in the following table.

EXT EN SIO N / O ID DESC RIP T IO N

AuthorityInformationAccess (XCN_OID_AUTHORITY_INF Identifies how to access certification authority information

O_ACCESS) and services. The extension value contains a sequence of
URIs.

CrlDistributionPoints (XCN_OID_CRL_DIST_POINTS) Contains the URI of the base certificate revocation list (CRL).

FreshestCRL (XCN_OID_FRESHEST_CRL) Contains the URI of the delta CRL. The same ASN.1 syntax is
used for this extension and the CrlDistributionPoints
extension.

NameConstraints (XCN_OID_NAME_CONSTRAINTS) Identifies the namespace within which all subject names of
certificates in a certificate hierarchy must be located. The
extension is used only in a certification authority certificate.

PolicyConstraints (XCN_OID_POLICY_CONSTRAINTS) Constrains path validation by prohibiting policy mapping or

by requiring that each certificate in the hierarchy contain an
acceptable policy identifier.

PolicyMappings (XCN_OID_POLICY_MAPPINGS) Identifies the policies in a subordinate certification authority

that correspond to policies in the issuing certification
authority. The extension value contains a sequence of issuing
certification authority and subordinate certification authority
policy mappings represented by object identifiers.
 PrivateKeyUsagePeriod (XCN_OID_PRIVATEKEY_USAGE_PE Specifies a different validity period for the private key than
RIOD) for the certificate with which the key is associated.

SubjectDirector yAttributes (XCN_OID_SUBJECT_DIR_ATT Conveys identification attributes such as nationality about

RS) the certificate subject. The extension value is a sequence of
OID-value pairs.

Finally, you can use the IX509Extension interface to define private extensions that contain information that is
unique to a specific community.
Extensions are added to the Attributes structure of a PKCS #10 request and to the TaggedAttributes structure
of a CMC request. To add extensions to either request format, you must first add them to an IX509Extensions
collection and use the collection to initialize an IX509AttributeExtensions object. For more information, see the
PKCS #10 Extensions and the CMC Extensions topics.

Inheritance
The IX509Extension interface inherits from the IDispatch interface. IX509Extension also has these types of
members:

Methods
The IX509Extension interface has these methods.

IX509Extension::get_Critical

Specifies and retrieves a Boolean value that identifies whether the certificate extension is critical.

IX509Extension::get_ObjectId

Retrieves the object identifier (OID) for the extension.

IX509Extension::get_RawData

Retrieves a byte array that contains the extension value.

IX509Extension::Initialize

Initializes an IX509Extension object by using an object identifier (OID) and a byte array that contains the Distinguished
Encoding Rules (DER) encoded extension.

IX509Extension::put_Critical

Specifies and retrieves a Boolean value that identifies whether the certificate extension is critical.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

 Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

See also
Certificate Enrollment API
ICryptAttribute
IDispatch
IX509AttributeExtensions
IX509Extensions
 IX509Extension::get_Critical method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Critical property specifies and retrieves a Boolean value that identifies whether the certificate extension is
critical. This property is web enabled on input.
This property is read/write.

Syntax
HRESULT get_Critical(
VARIANT_BOOL *pValue
);

Parameters
pValue

Return value
None

Remarks
A certificate extension consists of an object identifier (OID), a Boolean value that identifies whether the extension
is critical, and a byte array that contains the extension value. The criticality indicates whether an application that
uses a certificate can ignore the extension type and value. If an extension is identified as critical but the
application does not recognize the extension type, the application should reject the certificate.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509Extension
 IX509Extension::get_ObjectId method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The ObjectId property retrieves the object identifier (OID) for the extension.
This property is read-only.

Syntax
HRESULT get_ObjectId(
IObjectId **ppValue
);

Parameters
ppValue

Return value
None

Remarks
You can specify the OID when you call the Initialize method to create an extension value.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509Extension
 IX509Extension::get_RawData method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The RawData property retrieves a byte array that contains the extension value. The byte array is represented by
a Unicode-encoded string.
This property is read-only.

Syntax
HRESULT get_RawData(
EncodingType Encoding,
BSTR *pValue
);

Parameters
Encoding

pValue

Return value
None

Remarks
A certificate extension is defined by an Abstract Syntax Notation One (ASN.1) structure, and the extension is
encoded into a byte array by using DER. The byte array is returned in a string to simplify use in languages other
than C++. You can use the EncodingType enumeration to specify the type of Unicode encoding to apply to the
string. You can call the Initialize method to specify the extension.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509Extension
 IX509Extension::Initialize method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Initialize method initializes an IX509Extension object by using an object identifier (OID) and a byte array
that contains the Distinguished Encoding Rules (DER) encoded extension. The DER-encoded byte array is
represented by a Unicode-encoded string. This method is web enabled.

Syntax
HRESULT Initialize(
[in] IObjectId *pObjectId,
[in] EncodingType Encoding,
[in] BSTR strEncodedData
);

Parameters
[in] pObjectId

Pointer to an IObjectId interface that contains the extension OID.

[in] Encoding

An EncodingType enumeration value that specifies the type of Unicode encoding applied to the input string.
[in] strEncodedData

A BSTR variable that contains the DER-encoded extension value.

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. Possible values include, but are not
limited to, those in the following table. For a list of common error codes, see Common HRESULT Values.

RET URN C O DE/ VA L UE DESC RIP T IO N

The OID could not be found.

CERTSRV_E_PROPERTY_EMPTY

Remarks
A certificate extension consists of an OID, a Boolean value that identifies whether the extension is critical, and a
byte array that contains the extension value. The extension is defined by an Abstract Syntax Notation One
(ASN.1) standard and is encoded by using DER. You must specify the DER-encoded byte array as a string that is
either a pure binary sequence or is Unicode encoded. You can specify the type of encoding to apply to the string
by using the EncodingType enumeration.

Requirements
 Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509Extension
 IX509Extension::put_Critical method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Critical property specifies and retrieves a Boolean value that identifies whether the certificate extension is
critical. This property is web enabled on input.
This property is read/write.

Syntax
HRESULT put_Critical(
VARIANT_BOOL Value
);

Parameters
Value

Return value
None

Remarks
A certificate extension consists of an object identifier (OID), a Boolean value that identifies whether the extension
is critical, and a byte array that contains the extension value. The criticality indicates whether an application that
uses a certificate can ignore the extension type and value. If an extension is identified as critical but the
application does not recognize the extension type, the application should reject the certificate.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509Extension
 IX509ExtensionAlternativeNames interface
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The IX509ExtensionAlternativeNames interface enables you to specify one or more alternative name forms
for the subject of a certificate. A certification authority processes the extension by binding the names to the
certified public key. The following syntax shows the Abstract Syntax Notation One (ASN.1) structure of the
extension. The extension value is encoded by using Distinguished Encoding Rules (DER) and included in the
certificate request.

----------------------------------------------------------------------
-- AlternativeNames
-- XCN_OID_SUBJECT_ALT_NAME2 (2.5.29.17)
----------------------------------------------------------------------

AltNames ::= SEQUENCE --#public-- OF GeneralName

GeneralNames ::= AltNames

GeneralName ::= CHOICE

{
otherName [0] IMPLICIT OtherName,
rfc822Name [1] IMPLICIT IA5STRING,
dNSName [2] IMPLICIT IA5STRING,
x400Address [3] IMPLICIT SeqOfAny, -- Not supported
directoryName [4] EXPLICIT ANY,
ediPartyName [5] IMPLICIT SeqOfAny,
uniformResourceLocator [6] IMPLICIT IA5STRING,
iPAddress [7] IMPLICIT OCTETSTRING,
registeredID [8] IMPLICIT EncodedObjectID -- Not supported
}

OtherName ::= SEQUENCE

{
type EncodedObjectID,
value [0] EXPLICIT NOCOPYANY
}

If you initialize this extension by using an IAlternativeNames collection, the following name types are supported.

VA L UE DESC RIP T IO N

XCN_CERT_ALT_NAME_OTHER_NAME The name consists of an object identifier and a byte array

that contains the name.

XCN_CERT_ALT_NAME_RFC822_NAME The name is an email address.

XCN_CERT_ALT_NAME_DNS_NAME The name is a Domain Name System name.

XCN_CERT_ALT_NAME_DIRECTORY_NAME The name is an X.500 directory name.

XCN_CERT_ALT_NAME_URL The name is a URL.

 XCN_CERT_ALT_NAME_IP_ADDRESS The name is an Internet Protocol (IP) address.

XCN_CERT_ALT_NAME_REGISTERED_ID The name is a registered object identifier (OID).

XCN_CERT_ALT_NAME_GUID The name is a GUID. This is a form of otherName .

XCN_CERT_ALT_NAME_USER_PRINCIPLE_NAME The name is a user principal name (UPN). The UPN format is
based on RFC 822.

To add this extension object to a PKCS #10 request or a CMC request, you must first add it to an IX509Extensions
collection and use the collection to initialize an IX509AttributeExtensions object. For more information, see the
PKCS #10 Extensions and the CMC Extensions topics.

Inheritance
The IX509ExtensionAlternativeNames interface inherits from IX509Extension.
IX509ExtensionAlternativeNames also has these types of members:

Methods
The IX509ExtensionAlternativeNames interface has these methods.

IX509ExtensionAlternativeNames::get_AlternativeNames

Retrieves a collection of subject alternative names.

IX509ExtensionAlternativeNames::InitializeDecode

Initializes the extension from a Distinguished Encoding Rules (DER) encoded byte array that contains the extension value.

IX509ExtensionAlternativeNames::InitializeEncode

Initializes the extension from an IAlternativeNames collection.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

See also
Certificate Enrollment API
Extensions
IX509Extension
 IX509ExtensionAlternativeNames::get_AlternativeNames
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The AlternativeNames property retrieves a collection of subject alternative names.

This property is read-only.

Syntax
HRESULT get_AlternativeNames(
IAlternativeNames **ppValue
);

Parameters
ppValue

Return value
None

Remarks
Call the InitializeEncode method or the InitializeDecode method to initialize the collection. You can also call the
Critical property to specify and retrieve a Boolean value that identifies whether the extension is critical, and you
can call the ObjectId property to retrieve the object identifier (OID) associated with the extension.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509ExtensionAlternativeNames
 IX509ExtensionAlternativeNames::InitializeDecode
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The InitializeDecode method initializes the extension from a Distinguished Encoding Rules (DER) encoded byte
array that contains the extension value. The encoded byte array is represented by a Unicode encoded string.

Syntax
HRESULT InitializeDecode(
[in] EncodingType Encoding,
[in] BSTR strEncodedData
);

Parameters
[in] Encoding

An EncodingType enumeration value that specifies the type of Unicode encoding applied to the strEncodedData
value.
[in] strEncodedData

A BSTR variable that contains the DER-encoded extension.

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. Possible values include, but are not
limited to, those in the following table. For a list of common error codes, see Common HRESULT Values.

RET URN C O DE/ VA L UE DESC RIP T IO N

The object is already initialized.

HRESULT_FROM_WIN32(ERROR_ALREADY_INITIALIZE
D)

Remarks
You can use this method if you have a DER-encoded Abstract Syntax Notation One (ASN.1) object that contains
an AlternativeNames extension. You must supply the DER-encoded object in a Unicode encoded string. For
more information, see the IBinaryConverter interface.
You must call either InitializeEncode or InitializeDecode before you can use an
IX509ExtensionAlternativeNames object. The two methods complement each other. The InitializeEncode
method enables you to construct a DER-encoded ASN.1 extension object from raw data, and the
InitializeDecode method enables you to initialize the raw data from an encoded object.
You can retrieve the following properties for this extension:
 The Critical property identifies whether the extension is critical. You can also specify this property.
The ObjectId property retrieves the object identifier (OID).
The AlternativeNames property retrieves the collection of names (the raw extension data).

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509ExtensionAlternativeNames
 IX509ExtensionAlternativeNames::InitializeEncode
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The InitializeEncode method initializes the extension from an IAlternativeNames collection.

Syntax
HRESULT InitializeEncode(
[in] IAlternativeNames *pValue
);

Parameters
[in] pValue

Pointer to an IAlternativeNames interface.

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. Possible values include, but are not
limited to, those in the following table. For a list of common error codes, see Common HRESULT Values.

RET URN C O DE/ VA L UE DESC RIP T IO N

The object is already initialized.

HRESULT_FROM_WIN32(ERROR_ALREADY_INITIALIZE
D)

Remarks
The method associates the name collection with the XCN_OID_SUBJECT_ALT_NAME2 (2.5.29.17) object identifier
(OID) and encodes it by using Distinguished Encoding Rules (DER).
You must call either InitializeEncode or InitializeDecode before you can use an
IX509ExtensionAlternativeNames object. The two methods complement each other. The InitializeEncode
method enables you to construct a DER-encoded Abstract Syntax Notation One (ASN.1) extension object from
raw data, and the InitializeDecode method enables you to initialize the raw data from an encoded object.
You can retrieve the following properties for this extension:
The Critical property identifies whether the extension is critical. You can also specify this property.
The ObjectId property retrieves the OID.
The AlternativeNames property retrieves the collection of names (the raw extension data).

Requirements
 Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509ExtensionAlternativeNames
 IX509ExtensionAuthorityKeyIdentifier interface
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The IX509ExtensionAuthorityKeyIdentifier interface enables you to specify an AuthorityKeyIdentifier

extension. When a certification authority (CA) has multiple signing certificates, this extension can be used to
help identify which certification authority certificate was used to sign an issued certificate. The extension is
placed in all certificates other than that of the root. It has the following Abstract Syntax Notation One (ASN.1)
syntax. The extension value is encoded by using Distinguished Encoding Rules (DER) and included in the
certificate request.

----------------------------------------------------------------------
-- AuthorityKeyIdentifier
-- XCN_OID_AUTHORITY_KEY_IDENTIFIER2 (2.5.29.35)
----------------------------------------------------------------------

AuthorityKeyId2 ::= SEQUENCE

{
keyIdentifier [0] IMPLICIT KeyIdentifier OPTIONAL,
authorityCertIssuer [1] IMPLICIT GeneralNames OPTIONAL,
authorityCertSerialNumber [2] IMPLICIT CertificateSerialNumber OPTIONAL
}

KeyIdentifier ::= OCTETSTRING

The default certificate request behavior is to populate only the keyIdentifier field. Typically this value is a 20-
byte SHA-1 hash of the public key contained in the CA signing certificate. When the CA issues a certificate, it
copies the hash value into the SubjectKeyIdentifier extension of the issued certificate. Chain building software
searches the available CA certificates until it matches the SubjectKeyIdentifier extension value on the issued
certificate with the keyIdentifier field in the AuthorityKeyIdentifier extension on the CA certificate. For more
information about the SubjectKeyIdentifier extension, see IX509ExtensionSubjectKeyIdentifier.
To add this extension object to a PKCS #10 request or a CMC request, you must first add it to an IX509Extensions
collection and use the collection to initialize an IX509AttributeExtensions object. For more information, see the
PKCS #10 Extensions and the CMC Extensions topics.

Inheritance
The IX509ExtensionAuthorityKeyIdentifier interface inherits from IX509Extension.
IX509ExtensionAuthorityKeyIdentifier also has these types of members:

Methods
The IX509ExtensionAuthorityKeyIdentifier interface has these methods.
 IX509ExtensionAuthorityKeyIdentifier::get_AuthorityKeyIdentifier

Retrieves a byte array that contains the extension value.

IX509ExtensionAuthorityKeyIdentifier::InitializeDecode

Initializes the extension from a Distinguished Encoding Rules (DER) encoded byte array that contains the extension value.

IX509ExtensionAuthorityKeyIdentifier::InitializeEncode

Initializes the extension from a byte array.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

See also
Certificate Enrollment API
Extensions
IX509Extension
IX509ExtensionSubjectKeyIdentifier
 IX509ExtensionAuthorityKeyIdentifier::get_AuthorityKeyIdentifier
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The AuthorityKeyIdentifier property retrieves a byte array that contains the extension value. The byte array is
represented by a Unicode-encoded string.
This property is read-only.

Syntax
HRESULT get_AuthorityKeyIdentifier(
EncodingType Encoding,
BSTR *pValue
);

Parameters
Encoding

pValue

Return value
None

Remarks
Call the InitializeDecode method or the InitializeEncode method to initialize the
IX509ExtensionAuthorityKeyIdentifier object. You can also call the Critical property to specify and retrieve a
Boolean value that identifies whether the extension is critical, and you can call the ObjectId property to retrieve
the object identifier (OID) associated with the extension.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509ExtensionAuthorityKeyIdentifier
 IX509ExtensionAuthorityKeyIdentifier::InitializeDecode
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The InitializeDecode method initializes the extension from a Distinguished Encoding Rules (DER) encoded byte
array that contains the extension value. The encoded byte array is represented by a Unicode encoded string.

Syntax
HRESULT InitializeDecode(
[in] EncodingType Encoding,
[in] BSTR strEncodedData
);

Parameters
[in] Encoding

An EncodingType enumeration value that specifies the type of Unicode encoding applied to the input string.
[in] strEncodedData

A BSTR variable that contains the DER-encoded extension.

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. Possible values include, but are not
limited to, those in the following table. For a list of common error codes, see Common HRESULT Values.

RET URN C O DE/ VA L UE DESC RIP T IO N

The object is already initialized.

HRESULT_FROM_WIN32(ERROR_ALREADY_INITIALIZE
D)

Remarks
You can use this method if you have a DER-encoded Abstract Syntax Notation One (ASN.1) object that contains
an AuthorityKeyIdentifier extension. You must supply the DER-encoded object in a Unicode encoded string.
For more information, see the IBinaryConverter interface.
You must call either InitializeEncode or InitializeDecode before you can use an
IX509ExtensionAuthorityKeyIdentifier object. The two methods complement each other. The InitializeEncode
method enables you to construct a DER-encoded ASN.1 extension object from raw data, and the
InitializeDecode method enables you to initialize the raw data from an encoded object.
You can retrieve the following properties for this extension:
The Critical property identifies whether the extension is critical. You can also specify this property.
 The ObjectId property retrieves the object identifier (OID).
The AuthorityKeyIdentifier property retrieves the raw data.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509ExtensionAuthorityKeyIdentifier
 IX509ExtensionAuthorityKeyIdentifier::InitializeEncode
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The InitializeEncode method initializes the extension from a byte array. The byte array is represented by a
Unicode-encoded string.

Syntax
HRESULT InitializeEncode(
[in] EncodingType Encoding,
[in] BSTR strKeyIdentifier
);

Parameters
[in] Encoding

An EncodingType enumeration value that specifies the type of Unicode encoding applied to the strKeyIdentifier
value.
[in] strKeyIdentifier

A BSTR variable that contains the extension value.

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. Possible values include, but are not
limited to, those in the following table. For a list of common error codes, see Common HRESULT Values.

RET URN C O DE/ VA L UE DESC RIP T IO N

The object is already initialized.

HRESULT_FROM_WIN32(ERROR_ALREADY_INITIALIZE
D)

Remarks
Typically, the input value should be a SHA-1 hash of the public key contained in the signing certificate. The
method associates the value with the XCN_OID_AUTHORITY_KEY_IDENTIFIER2 (2.5.29.35) object identifier (OID)
and encodes it by using Distinguished Encoding Rules (DER).
You must call either InitializeEncode or InitializeDecode before you can use an
IX509ExtensionAuthorityKeyIdentifier object. The two methods complement each other. The InitializeEncode
method enables you to construct a DER-encoded Abstract Syntax Notation One (ASN.1) extension object from
raw data, and the InitializeDecode method enables you to initialize the raw data from an encoded object.
You can retrieve the following properties for this extension:
 The Critical property identifies whether the extension is critical. You can also specify this property.
The ObjectId property retrieves the OID.
The AuthorityKeyIdentifier property retrieves the raw data.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509ExtensionAuthorityKeyIdentifier
 IX509ExtensionBasicConstraints interface
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The IX509ExtensionBasicConstraints interface enables you to specify whether the certificate subject is a
certification authority and, if so, the depth of the subordinate certification authority chain that can exist beneath
the certification authority for which this extension ID is defined. This extension must be marked Critical in any
certification authority certificate that contains a public key used to validate a digital signature on a certificate.
The following syntax shows the Abstract Syntax Notation One (ASN.1) structure of the extension. The extension
value is encoded by using Distinguished Encoding Rules (DER) and is included in the certificate request.

----------------------------------------------------------------------
-- Basic Constraints
-- XCN_OID_BASIC_CONSTRAINTS2 (2.5.29.19)
----------------------------------------------------------------------

BasicConstraints2 ::= SEQUENCE

{
cA BOOLEAN DEFAULT FALSE,
pathLenConstraint INTEGER OPTIONAL
}

To add this extension object to a PKCS #10 request or a CMC request, you must first add it to an IX509Extensions
collection and use the collection to initialize an IX509AttributeExtensions object. For more information, see the
PKCS #10 Extensions and the CMC Extensions topics.

Inheritance
The IX509ExtensionBasicConstraints interface inherits from IX509Extension.
IX509ExtensionBasicConstraints also has these types of members:

Methods
The IX509ExtensionBasicConstraints interface has these methods.

IX509ExtensionBasicConstraints::get_IsCA

Retrieves a Boolean value that identifies whether the subject of the certificate is a certification authority (CA).

IX509ExtensionBasicConstraints::get_PathLenConstraint

Retrieves the depth of the subordinate certification authority chain.

IX509ExtensionBasicConstraints::InitializeDecode

Initializes the extension from a Distinguished Encoding Rules (DER) encoded byte array that contains the extension value.
 IX509ExtensionBasicConstraints::InitializeEncode

Initializes the extension from a Boolean value that indicates whether the certificate subject is a certification authority (CA) and
an integer that contains the depth of the subordinate CA chain.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

See also
Certificate Enrollment API
IX509Extension
 IX509ExtensionBasicConstraints::get_IsCA method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The IsCA property retrieves a Boolean value that identifies whether the subject of the certificate is a certification
authority (CA).
This property is read-only.

Syntax
HRESULT get_IsCA(
VARIANT_BOOL *pValue
);

Parameters
pValue

Return value
None

Remarks
Call the InitializeEncode method or the InitializeDecode method to initialize the IX509ExtensionBasicConstraints
object and specify the IsCA property. You can also call the Critical property to specify and retrieve a Boolean
value that identifies whether the extension is critical, and you can call the ObjectId property to retrieve the object
identifier (OID) associated with the extension.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509ExtensionBasicConstraints
 IX509ExtensionBasicConstraints::get_PathLenConstraint
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The PathLenConstraint property retrieves the depth of the subordinate certification authority chain.
This property is read-only.

Syntax
HRESULT get_PathLenConstraint(
LONG *pValue
);

Parameters
pValue

Return value
None

Remarks
Call the InitializeEncode method or the InitializeDecode method to initialize the IX509ExtensionBasicConstraints
object and specify the PathLenConstraint property. You can also call the Critical property to specify and
retrieve a Boolean value that identifies whether the extension is critical, and you can call the ObjectId property to
retrieve the object identifier (OID) associated with the extension.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509ExtensionBasicConstraints
 IX509ExtensionBasicConstraints::InitializeDecode
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The InitializeDecode method initializes the extension from a Distinguished Encoding Rules (DER) encoded byte
array that contains the extension value. The encoded byte array is represented by a Unicode encoded string.

Syntax
HRESULT InitializeDecode(
[in] EncodingType Encoding,
[in] BSTR strEncodedData
);

Parameters
[in] Encoding

An EncodingType enumeration value that specifies the type of Unicode encoding applied to the strEncodedData
value.
[in] strEncodedData

A BSTR variable that contains the DER-encoded extension.

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. Possible values include, but are not
limited to, those in the following table. For a list of common error codes, see Common HRESULT Values.

RET URN C O DE/ VA L UE DESC RIP T IO N

The object is already initialized.

HRESULT_FROM_WIN32(ERROR_ALREADY_INITIALIZE
D)

Remarks
You can use this method if you have a DER-encoded Abstract Syntax Notation One (ASN.1) object that contains a
BasicConstraints extension. You must supply the DER-encoded object in a Unicode encoded string. For more
information, see the IBinaryConverter interface.
You must call either InitializeEncode or InitializeDecode before you can use an IX509ExtensionBasicConstraints
object. The two methods complement each other. The InitializeEncode method enables you to construct a
DER-encoded ASN.1 extension object from raw data, and the InitializeDecode method enables you to initialize
the raw data from an encoded object.
You can retrieve the following properties for this extension:
 The Critical property identifies whether the extension is critical. You can also specify this property.
The ObjectId property retrieves the object identifier (OID).
The IsCA property identifies whether the certificate subject can be a certification authority.
The PathLenConstraint property identifies the depth of the subordinate certification authority chain.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509ExtensionBasicConstraints
 IX509ExtensionBasicConstraints::InitializeEncode
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The InitializeEncode method initializes the extension from a Boolean value that indicates whether the
certificate subject is a certification authority (CA) and an integer that contains the depth of the subordinate CA
chain.

Syntax
HRESULT InitializeEncode(
[in] VARIANT_BOOL IsCA,
[in] LONG PathLenConstraint
);

Parameters
[in] IsCA

A VARIANT_BOOL variable that specifies whether the certificate subject is a CA.

[in] PathLenConstraint

A LONG variable that contains the maximum number of certificates in the chain.

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. Possible values include, but are not
limited to, those in the following table. For a list of common error codes, see Common HRESULT Values.

RET URN C O DE/ VA L UE DESC RIP T IO N

The object is already initialized.

HRESULT_FROM_WIN32(ERROR_ALREADY_INITIALIZE
D)

Remarks
The method associates the name collection with the XCN_OID_BASIC_CONSTRAINTS2 (2.5.29.19) object
identifier (OID) and encodes it by using Distinguished Encoding Rules (DER).
You must call either InitializeEncode or InitializeDecode before you can use an IX509ExtensionBasicConstraints
object. The two methods complement each other. The InitializeEncode method enables you to construct a
DER-encoded Abstract Syntax Notation One (ASN.1) extension object from raw data, and the InitializeDecode
method enables you to initialize the raw data from an encoded object.
You can retrieve the following properties for this extension:
The Critical property identifies whether the extension is critical. You can also specify this property.
 The ObjectId property retrieves the OID.
The IsCA property identifies whether the certificate subject can be a certification authority.
The PathLenConstraint property identifies the depth of the subordinate certification authority chain.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509ExtensionBasicConstraints
 IX509ExtensionCertificatePolicies interface
(certenroll.h)
7/2/2022 • 3 minutes to read • Edit Online

The IX509ExtensionCer tificatePolicies interface enables you to specify a collection of policy information
terms, each of which consists of an object identifier (OID) and optional policy qualifiers. A single policy term is
defined by an ICertificatePolicy object. The following syntax shows the Abstract Syntax Notation One (ASN.1)
structure of the extension. The extension value is encoded by using Distinguished Encoding Rules (DER) and
included in the certificate request.
 ----------------------------------------------------------------------
-- CertificatePolicies
-- XCN_OID_CERT_POLICIES (2.5.29.32)
----------------------------------------------------------------------

CertificatePolicies ::= SEQUENCE OF PolicyInformation

PolicyInformation ::= SEQUENCE

{
policyIdentifier EncodedObjectID,
policyQualifiers PolicyQualifiers OPTIONAL
}

PolicyQualifiers ::= SEQUENCE OF PolicyQualifierInfo

PolicyQualifierInfo ::= SEQUENCE

{
policyQualifierId EncodedObjectID,
qualifier NOCOPYANY OPTIONAL
}

----------------------------------------------------------------------
-- UserNotice qualifier
-- XCN_OID_PKIX_POLICY_QUALIFIER_USERNOTICE (1.3.6.1.5.5.7.2.2)
----------------------------------------------------------------------

UserNotice ::= SEQUENCE

{
noticeRef, -- Not supported
explicitText -- Not supported
}

----------------------------------------------------------------------
-- Certification Practice Statement (CPS) qualifier
-- XCN_OID_PKIX_POLICY_QUALIFIER_CPS (1.3.6.1.5.5.7.2.1)
----------------------------------------------------------------------

CpsURLs ::= SEQUENCE OF SEQUENCE

{
url IA5String,
digestAlgorithmId, -- Not supported
digest -- Not supported
}

----------------------------------------------------------------------
-- CertificatePolicies95, XCN_OID_CERT_POLICIES_95 (2.5.29.3),
-- supports the deprecated definition of policies and qualifiers.
----------------------------------------------------------------------

CertificatePolicies95 ::= SEQUENCE OF PolicyQualifiers

When included in a certificate issued to an end entity, this extension identifies the policies under which the
certificate was issued and the purposes for which the certificate can be used. Applications that have specific
policy requirements should compare these to the collection of policy object identifiers (OIDs) in the certificate.
When included in a certification authority certificate, this extension limits the set of policies for the certification
paths extending from the certification authority certificate. If a certification authority does not want to limit this
set, it can assert XCN_OID_ANY_CERT_POLICY (2.5.29.32.0).
This extension is supported on Windows Server 2003 and later certification authorities. The following policies
are predefined. The x.y.z portion of each OID represents a randomly generated numeric sequence that is unique
for each forest. You can also create custom OIDs to represent custom issuance policies.

P O L IC Y DESC RIP T IO N

All Issuance(2.5.29.32.0) Contains all other policies. This is typically assigned only to
certification authority certificates. The OID is
XCN_OID_ANY_CERT_POLICY.

Low Assurance(1.3.6.1.4.1.311.21.8.x.y.z.1.400) Indicates that a certificate is issued with no additional

security requirements.

Medium Assurance (1.3.6.1.4.1.311.21.8.x.y.z.1.401) Indicates that a certificate issuance has additional security
requirements. For example, the policy might require that the
certificate subject physically appear before the certification
authority.

High Assurance (1.3.6.1.4.1.311.21.8.x.y.z.1.402)
Indicates that the certificate is issued with the highest
security. For example, the issuance of a key recovery agent
certificate can require additional background checks and a
digital signature from a designated approver because a
person holding this certificate can recover private key
material from the certification authority.

Policy qualifiers can be used when an OID is considered insufficient to fully identify a policy. Qualifiers are
defined by using the IPolicyQualifier interface and can be associated with a policy by adding qualifiers to the
IPolicyQualifiers collection retrieved from an ICertificatePolicy object. A Windows certification authority
supports the following qualifiers.

VA L UE DESC RIP T IO N

XCN_OID_PKIX_POLICY_QUALIFIER_USERNOTICE(1.3.6.1.5.5 Contains a notice to be displayed to any user who relies on

.7.2.2) the certificate.

XCN_OID_PKIX_POLICY_QUALIFIER_CPS(1.3.6.1.5.5.7.2.1) Identifies a pointer to a URI that contains the Certification

Practice Statement (CPS) defined by the certification
authority.

To add this extension object to a PKCS #10 request or a CMC request, you must first add it to an IX509Extensions
collection and use the collection to initialize an IX509AttributeExtensions object. For more information, see the
PKCS #10 Extensions and the CMC Extensions topics.

Inheritance
The IX509ExtensionCer tificatePolicies interface inherits from IX509Extension.
IX509ExtensionCer tificatePolicies also has these types of members:

Methods
The IX509ExtensionCer tificatePolicies interface has these methods.
 IX509ExtensionCertificatePolicies::get_Policies

Retrieves a collection of certificate policies.

IX509ExtensionCertificatePolicies::InitializeDecode

Initializes the object from a Distinguished Encoding Rules (DER) encoded byte array that contains the extension value.

IX509ExtensionCertificatePolicies::InitializeEncode

Initializes the object from an ICertificatePolicies collection.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

See also
Certificate Enrollment API
Extensions
IX509Extension
 IX509ExtensionCertificatePolicies::get_Policies
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Policies property retrieves a collection of certificate policies.

This property is read-only.

Syntax
HRESULT get_Policies(
ICertificatePolicies **ppValue
);

Parameters
ppValue

Return value
None

Remarks
Call the InitializeEncode method or the InitializeDecode method to initialize the collection. You can also call the
Critical property to specify and retrieve a Boolean value that identifies whether the extension is critical, and you
can call the ObjectId property to retrieve the object identifier (OID) associated with the extension.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509ExtensionCertificatePolicies
 IX509ExtensionCertificatePolicies::InitializeDecode
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The InitializeDecode method initializes the object from a Distinguished Encoding Rules (DER) encoded byte
array that contains the extension value. The DER-encoded byte array is represented by a Unicode encoded
string.

Syntax
HRESULT InitializeDecode(
[in] EncodingType Encoding,
[in] BSTR strEncodedData
);

Parameters
[in] Encoding

An EncodingType enumeration value that specifies the type of Unicode encoding applied to the strEncodedData
value.
[in] strEncodedData

A BSTR variable that contains the DER-encoded extension.

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. Possible values include, but are not
limited to, those in the following table. For a list of common error codes, see Common HRESULT Values.

RET URN C O DE/ VA L UE DESC RIP T IO N

The object is already initialized.

HRESULT_FROM_WIN32(ERROR_ALREADY_INITIALIZE
D)

Remarks
You can use this method if you have a DER-encoded Abstract Syntax Notation One (ASN.1) object that contains a
Cer tificatePolicies extension. You must supply the DER-encoded object in a Unicode encoded string. For more
information, see the IBinaryConverter interface.
You must call either InitializeEncode or InitializeDecode before you can use an
IX509ExtensionCertificatePolicies object. The two methods complement each other. The InitializeEncode
method enables you to construct a DER-encoded ASN.1 extension object from raw data, and the
InitializeDecode method enables you to initialize the raw data from an encoded object.
You can retrieve the following properties for this extension:
The Critical property identifies whether the extension is critical. You can also specify this property.
The ObjectId property retrieves the extension object identifier (OID).
The Policies property retrieves the collection of certificate policies (the raw extension data).

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509ExtensionCertificatePolicies
 IX509ExtensionCertificatePolicies::InitializeEncode
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The InitializeEncode method initializes the object from an ICertificatePolicies collection.

Syntax
HRESULT InitializeEncode(
[in] ICertificatePolicies *pValue
);

Parameters
[in] pValue

Pointer to the ICertificatePolicies interface.

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. Possible values include, but are not
limited to, those in the following table. For a list of common error codes, see Common HRESULT Values.

RET URN C O DE/ VA L UE DESC RIP T IO N

The object is already initialized.

HRESULT_FROM_WIN32(ERROR_ALREADY_INITIALIZE
D)

Remarks
The method associates the name collection with the XCN_OID_CERT_POLICIES (2.5.29.32) object identifier (OID)
and encodes it by using Distinguished Encoding Rules (DER).
You must call either InitializeEncode or InitializeDecode before you can use an
IX509ExtensionCertificatePolicies object. The two methods complement each other. The InitializeEncode
method enables you to construct a DER-encoded Abstract Syntax Notation One (ASN.1) extension object from
raw data, and the InitializeDecode method enables you to initialize the raw data from an encoded object. You
can retrieve the collection of policies (the raw data) by calling the Policies property.
You can retrieve the following properties for this extension:
The Critical property identifies whether the extension is critical. You can also specify this property.
The ObjectId property retrieves the extension OID.
The Policies property retrieves the collection of certificate policies (the raw extension data).

Requirements
 Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509ExtensionCertificatePolicies
 IX509ExtensionEnhancedKeyUsage interface
(certenroll.h)
7/2/2022 • 3 minutes to read • Edit Online

The IX509ExtensionEnhancedKeyUsage interface can be used to define a collection of object identifiers

(OIDs) that identify the intended uses of the public key contained in the certificate. The EnhancedKeyUsage
extension can be used in addition to or in place of the KeyUsage extension. Also, the EnhancedKeyUsage
extension and the MSApplicationPolicies extension defined by the IX509ExtensionMSApplicationPolicies
interface are similar. The following syntax shows the Abstract Syntax Notation One (ASN.1) structure of the
extension. The extension value is encoded by using Distinguished Encoding Rules (DER) and included in the
certificate request.

----------------------------------------------------------------------
-- EnhancedKeyUsage
-- XCN_OID_ENHANCED_KEY_USAGE (2.5.29.37)
----------------------------------------------------------------------

EnhancedKeyUsage ::= SEQUENCE OF UsageIdentifier

UsageIdentifier ::= EncodedObjectID

You can define your own OIDs or use any of the following EKU OIDs. The list is not complete.

VA L UE DESC RIP T IO N

XCN_OID_ANY_APPLICATION_POLICY(1.3.6.1.4.1.311.10.12. The applications that can use the certificate are not
1) restricted.

XCN_OID_AUTO_ENROLL_CTL_USAGE(1.3.6.1.4.1.311.20.1) The certificate can be used to sign a request for automatic

enrollment in a certificate trust list (CTL).

XCN_OID_DRM(1.3.6.1.4.1.311.10.5.1) The certificate can be used for digital rights management

applications.

XCN_OID_DS_EMAIL_REPLICATION(1.3.6.1.4.1.311.21.19) The certificate can be used for Directory Service email

replication.

XCN_OID_EFS_RECOVERY(1.3.6.1.4.1.311.10.3.4.1) The certificate can be used for recovery of documents

protected by using Encrypting File System (EFS).

XCN_OID_EMBEDDED_NT_CRYPTO(1.3.6.1.4.1.311.10.3.8) The certificate can be used for Windows NT Embedded

cryptography.

XCN_OID_ENROLLMENT_AGENT(1.3.6.1.4.1.311.20.2.1) The certificate can be used by an enrollment agent.

XCN_OID_IPSEC_KP_IKE_INTERMEDIATE(1.3.6.1.5.5.8.2.2) The certificate can be used for Internet Key Exchange (IKE).

XCN_OID_KP_CA_EXCHANGE(1.3.6.1.4.1.311.21.5) The certificate can be used for archiving a private key on a

certification authority.
XCN_OID_KP_CTL_USAGE_SIGNING(1.3.6.1.4.1.311.10.3.1) The certificate can be used to sign a CTL.

XCN_OID_KP_DOCUMENT_SIGNING(1.3.6.1.4.1.311.10.3.12) The certificate can be used for signing documents.

XCN_OID_KP_EFS(1.3.6.1.4.1.311.10.3.4) The certificate can be used to encrypt files by using the

Encrypting File System.

XCN_OID_KP_KEY_RECOVERY(1.3.6.1.4.1.311.10.3.11) The certificate can be used to encrypt and recover escrowed

keys.

XCN_OID_KP_KEY_RECOVERY_AGENT(1.3.6.1.4.1.311.21.6) The certificate is used to identify a key recovery agent.

XCN_OID_KP_LIFETIME_SIGNING(1.3.6.1.4.1.311.10.3.13) Limits the validity period of a signature to the validity period

of the certificate. This restriction is typically used with the
XCN_OID_PKIX_KP_CODE_SIGNING OID value to indicate
that new time stamp semantics should be used.

XCN_OID_KP_QUALIFIED_SUBORDINATION(1.3.6.1.4.1.311. The certificate can be used to sign cross certificate and

10.3.10) subordinate certification authority certificate requests.
Qualified subordination is implemented by applying basic
constraints, certificate policies, and application policies. Cross
certification typically requires policy mapping.

XCN_OID_KP_SMARTCARD_LOGON(1.3.6.1.4.1.311.20.2.2) The certificate enables an individual to log on to a computer

by using a smart card.

XCN_OID_KP_TIME_STAMP_SIGNING(1.3.6.1.4.1.311.10.3.2) The certificate can be used to sign a time stamp to be added

to a document. Time stamp signing is typically part of a time
stamping service.

XCN_OID_LICENSE_SERVER(1.3.6.1.4.1.311.10.6.2) The certificate can be used by a license server when

transacting with Microsoft to receive licenses for Terminal
Services clients.

XCN_OID_LICENSES(1.3.6.1.4.1.311.10.6.1) The certificate can be used for key pack licenses.

XCN_OID_NT5_CRYPTO(1.3.6.1.4.1.311.10.3.7) The certificate can be used for Windows Server 2003,

Windows XP, and Windows 2000 cryptography.

XCN_OID_OEM_WHQL_CRYPTO(1.3.6.1.4.1.311.10.3.7) The certificate can be used for used for Original Equipment
Manufacturers (OEM) Windows Hardware Quality Labs
(WHQL) cryptography.

XCN_OID_PKIX_KP_CLIENT_AUTH(1.3.6.1.5.5.7.3.2) The certificate can be used for authenticating a client.

XCN_OID_PKIX_KP_CODE_SIGNING(1.3.6.1.5.5.7.3.3) The certificate can be used for signing code.

XCN_OID_PKIX_KP_EMAIL_PROTECTION(1.3.6.1.5.5.7.3.4) The certificate can be used to encrypt email messages.

XCN_OID_PKIX_KP_IPSEC_END_SYSTEM(1.3.6.1.5.5.7.3.5) The certificate can be used for signing end-to-end Internet

Protocol Security (IPSEC) communication.

XCN_OID_PKIX_KP_IPSEC_TUNNEL(1.3.6.1.5.5.7.3.6) The certificate can be used for singing IPSEC communication

in tunnel mode.
 XCN_OID_PKIX_KP_IPSEC_USER(1.3.6.1.5.5.7.3.7) The certificate can be used for an IPSEC user.

XCN_OID_PKIX_KP_OCSP_SIGNING(1.3.6.1.5.5.7.3.9) The certificate can be used for Online Certificate Status

Protocol (OCSP) signing.

XCN_OID_PKIX_KP_SERVER_AUTH(1.3.6.1.5.5.7.3.1) The certificate can be used for OCSP authentication.

XCN_OID_PKIX_KP_TIMESTAMP_SIGNING(1.3.6.1.5.5.7.3.8) The certificate can be used for signing public key

infrastructure timestamps.

XCN_OID_ROOT_LIST_SIGNER(1.3.6.1.4.1.311.10.3.9) The certificate can be used to sign a certificate root list.

XCN_OID_WHQL_CRYPTO(1.3.6.1.4.1.311.10.3.5) The certificate can be used for Windows Hardware Quality

Labs (WHQL) cryptography.

To add this extension object to a PKCS #10 request or a CMC request, you must first add it to an IX509Extensions
collection and use the collection to initialize an IX509AttributeExtensions object. For more information, see PKCS
#10 Extensions and CMC Extensions.

Inheritance
The IX509ExtensionEnhancedKeyUsage interface inherits from IX509Extension.
IX509ExtensionEnhancedKeyUsage also has these types of members:

Methods
The IX509ExtensionEnhancedKeyUsage interface has these methods.

IX509ExtensionEnhancedKeyUsage::get_EnhancedKeyUsage

Retrieves a collection of key usage object identifiers (OIDs).

IX509ExtensionEnhancedKeyUsage::InitializeDecode

Initializes the extension from a Distinguished Encoding Rules (DER) encoded byte array that contains the extension value.

IX509ExtensionEnhancedKeyUsage::InitializeEncode

Initializes the extension from a collection of IObjectId object identifiers (OIDs) that specify the intended uses of the public key.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

 Header certenroll.h

See also
Certificate Enrollment API
IX509Extension
 IX509ExtensionEnhancedKeyUsage::get_EnhancedKeyUsage
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The EnhancedKeyUsage property retrieves a collection of key usage object identifiers (OIDs).
This property is read-only.

Syntax
HRESULT get_EnhancedKeyUsage(
IObjectIds **ppValue
);

Parameters
ppValue

Return value
None

Remarks
Call the InitializeEncode method or the InitializeDecode method to initialize the collection. You can also call the
Critical property to specify and retrieve a Boolean value that identifies whether the extension is critical, and you
can call the ObjectId property to retrieve the OID associated with the extension.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509ExtensionEnhancedKeyUsage
 IX509ExtensionEnhancedKeyUsage::InitializeDecode
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The InitializeDecode method initializes the extension from a Distinguished Encoding Rules (DER) encoded byte
array that contains the extension value. The encoded byte array is represented by a Unicode encoded string.

Syntax
HRESULT InitializeDecode(
[in] EncodingType Encoding,
[in] BSTR strEncodedData
);

Parameters
[in] Encoding

An EncodingType enumeration value that specifies the type of Unicode encoding applied to the strEncodedData
parameter.
[in] strEncodedData

A BSTR variable that contains the DER-encoded extension.

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. Possible values include, but are not
limited to, those in the following table. For a list of common error codes, see Common HRESULT Values.

RET URN C O DE/ VA L UE DESC RIP T IO N

The object is already initialized.

HRESULT_FROM_WIN32(ERROR_ALREADY_INITIALIZE
D)

Remarks
You can use this method if you have a DER-encoded Abstract Syntax Notation One (ASN.1) object that contains
an EnhancedKeyUsage extension. You must supply the DER-encoded object in a Unicode encoded string. For
more information, see the IBinaryConverter interface.
You must call either InitializeEncode or InitializeDecode before you can use an
IX509ExtensionEnhancedKeyUsage object. The two methods complement each other. The InitializeEncode
method enables you to construct a DER-encoded ASN.1 extension object from raw data, and the
InitializeDecode method enables you to initialize the raw data from an encoded object.
You can retrieve the following properties for this extension:
 The Critical property identifies whether the extension is critical. You can also specify this property.
The ObjectId property retrieves the extension object identifier (OID).
The EnhancedKeyUsage property retrieves the collection of OIDs that identify the intended uses of the public
key (the raw extension data).

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509ExtensionEnhancedKeyUsage
 IX509ExtensionEnhancedKeyUsage::InitializeEncode
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The InitializeEncode method initializes the extension from a collection of IObjectId object identifiers (OIDs)
that specify the intended uses of the public key. This method is web enabled.

Syntax
HRESULT InitializeEncode(
[in] IObjectIds *pValue
);

Parameters
[in] pValue

Pointer to an IObjectIds interface.

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. Possible values include, but are not
limited to, those in the following table. For a list of common error codes, see Common HRESULT Values.

RET URN C O DE/ VA L UE DESC RIP T IO N

The object is already initialized.

HRESULT_FROM_WIN32(ERROR_ALREADY_INITIALIZE
D)

Remarks
You must call either InitializeEncode or InitializeDecode before you can use an
IX509ExtensionEnhancedKeyUsage object. The two methods complement each other. The InitializeEncode
method enables you to construct a Distinguished Encoding Rules (DER) encoded Abstract Syntax Notation One
(ASN.1) extension object from raw data, and the InitializeDecode method enables you to initialize the raw data
from an encoded object.
You can retrieve the following properties for this extension:
The Critical property identifies whether the extension is critical. You can also specify this property.
The ObjectId property retrieves the extension object identifier (OID).
The EnhancedKeyUsage property retrieves the collection of OIDs that identify the intended uses of the public
key (the raw extension data).

Requirements
 Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509ExtensionEnhancedKeyUsage
 IX509ExtensionKeyUsage interface (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The IX509ExtensionKeyUsage interface can be used to define restrictions on the operations that can be
performed by the public key contained in the certificate. This is the same purpose as that served by the
EnhancedKeyUsage extension, but KeyUsage predates that extension and defines a more limited set of
restrictions. The following syntax shows the Abstract Syntax Notation One (ASN.1) structure of the extension.
The extension value is encoded by using Distinguished Encoding Rules (DER) and included in the certificate
request.

----------------------------------------------------------------------
-- KeyUsage
-- XCN_OID_KEY_USAGE (2.5.29.15)
----------------------------------------------------------------------

KeyUsageExtension ::= Bits

The possible restrictions are defined by using a bitwise-OR combination of the values in the
X509KeyUsageFlags enumeration.
To add this extension object to a PKCS #10 request or a CMC request, you must first add it to an IX509Extensions
collection and use the collection to initialize an IX509AttributeExtensions object. For more information, see the
PKCS #10 Extensions and the CMC Extensions topics.

Inheritance
The IX509ExtensionKeyUsage interface inherits from IX509Extension. IX509ExtensionKeyUsage also has
these types of members:

Methods
The IX509ExtensionKeyUsage interface has these methods.

IX509ExtensionKeyUsage::get_KeyUsage

Retrieves the restrictions placed on the public key.

IX509ExtensionKeyUsage::InitializeDecode

Initializes the extension from a Distinguished Encoding Rules (DER) encoded byte array that contains the extension value.

IX509ExtensionKeyUsage::InitializeEncode

Initializes the extension by using the X509KeyUsageFlags enumeration.

Requirements
 Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

See also
Certificate Enrollment API
IX509Extension
 IX509ExtensionKeyUsage::get_KeyUsage method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The KeyUsage property retrieves the restrictions placed on the public key.
This property is read-only.

Syntax
HRESULT get_KeyUsage(
X509KeyUsageFlags *pValue
);

Parameters
pValue

Return value
None

Remarks
Call the InitializeEncode method or the InitializeDecode method to initialize the collection. You can also call the
Critical property to specify and retrieve a Boolean value that identifies whether the extension is critical, and you
can call the ObjectId property to retrieve the object identifier (OID) associated with the extension.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509ExtensionKeyUsage
 IX509ExtensionKeyUsage::InitializeDecode method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The InitializeDecode method initializes the extension from a Distinguished Encoding Rules (DER) encoded byte
array that contains the extension value. The encoded byte array is represented by a Unicode encoded string.

Syntax
HRESULT InitializeDecode(
[in] EncodingType Encoding,
[in] BSTR strEncodedData
);

Parameters
[in] Encoding

An EncodingType enumeration value that specifies the type of Unicode encoding applied to the strEncodedData
parameter.
[in] strEncodedData

A BSTR variable that contains the DER-encoded extension.

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. Possible values include, but are not
limited to, those in the following table. For a list of common error codes, see Common HRESULT Values.

RET URN C O DE/ VA L UE DESC RIP T IO N

The object is already initialized.

HRESULT_FROM_WIN32(ERROR_ALREADY_INITIALIZE
D)

Remarks
You can use this method if you have a DER-encoded Abstract Syntax Notation One (ASN.1) object that contains a
KeyUsage extension. You must supply the DER-encoded object in a Unicode encoded string. For more
information, see the IBinaryConverter interface.
You must call either InitializeEncode or InitializeDecode before you can use an IX509ExtensionKeyUsage
object. The two methods complement each other. The InitializeEncode method enables you to construct a
DER-encoded ASN.1 extension object from raw data, and the InitializeDecode method enables you to initialize
the raw data from an encoded object.
You can retrieve the following properties for this extension:
 The Critical property identifies whether the extension is critical. You can also specify this property.
The ObjectId property retrieves the extension object identifier (OID).
The KeyUsage property retrieves the restrictions that identify the intended uses of the public key (the raw
extension data).

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509ExtensionKeyUsage
 IX509ExtensionKeyUsage::InitializeEncode method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The InitializeEncode method initializes the extension by using the X509KeyUsageFlags enumeration. This
method is web enabled.

Syntax
HRESULT InitializeEncode(
[in] X509KeyUsageFlags UsageFlags
);

Parameters
[in] UsageFlags

An X509KeyUsageFlags enumeration value. This can be a bitwise-OR combination of any of the following
values.

VA L UE M EA N IN G

The key is used with a Digital Signature Algorithm (DSA) to

XCN_CERT_DIGITAL_SIGNATURE_KEY_USAGE support services other than nonrepudiation, certificate
signing, or revocation list signing. DSAs are often used for
authentication.

The key is used to verify a digital signature as part of a

XCN_CERT_NON_REPUDIATION_KEY_USAGE nonrepudiation service that protects against false denial of
action by a signing entity.

The key is used for key transport. That is, the key is used to
XCN_CERT_KEY_ENCIPHERMENT_KEY_USAGE manage a key passed from its origination point to its point
of actual use.

The key is used to encrypt user data other than

XCN_CERT_DATA_ENCIPHERMENT_KEY_USAGE cryptographic keys.

The key is used for key agreement. The key agreement or

XCN_CERT_KEY_AGREEMENT_KEY_USAGE key exchange protocol enables two or more parties to
negotiate a key value without transferring the key and
without previously establishing a shared secret.

The key is used to verify a certificate signature. This value

XCN_CERT_KEY_CERT_SIGN_KEY_USAGE can only be used for certificates issued by certification
authorities.

The key is used to verify an offline certificate revocation list

XCN_CERT_OFFLINE_CRL_SIGN_KEY_USAGE (CRL) signature.
 The key is used to verify a CRL signature.
XCN_CERT_CRL_SIGN_KEY_USAGE

The key is used to encrypt data while performing key

XCN_CERT_ENCIPHER_ONLY_KEY_USAGE agreement. The
XCN_CERT_KEY_AGREEMENT_KEY_USAGE value must
also be specified.

The key is used to decrypt data while performing key

XCN_CERT_DECIPHER_ONLY_KEY_USAGE agreement. The
XCN_CERT_KEY_AGREEMENT_KEY_USAGE value must
also be specified.

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. Possible values include, but are not
limited to, those in the following table. For a list of common error codes, see Common HRESULT Values.

RET URN C O DE DESC RIP T IO N

The object is already initialized.

HRESULT_FROM_WIN32(ERROR_ALREADY_INITIALIZE
D)

Remarks
You must call either InitializeEncode or InitializeDecode before you can use an IX509ExtensionKeyUsage
object. The two methods complement each other. The InitializeEncode method enables you to construct a
Distinguished Encoding Rules (DER) encoded Abstract Syntax Notation One (ASN.1) extension object from raw
data, and the InitializeDecode method enables you to initialize the raw data from an encoded object.
You can retrieve the following properties for this extension:
The Critical property identifies whether the extension is critical. You can also specify this property.
The ObjectId property retrieves the extension object identifier (OID).
The KeyUsage property retrieves the restrictions that identify the intended uses of the public key (the raw
extension data).

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll
See also
IX509ExtensionKeyUsage
 IX509ExtensionMSApplicationPolicies interface
(certenroll.h)
7/2/2022 • 3 minutes to read • Edit Online

The IX509ExtensionMSApplicationPolicies interface enables you to specify a collection of object identifiers

(OIDs) that indicate how a certificate can be used by an application. It is therefore similar to the
EnhancedKeyUsage (EKU) extension. You can define your own OIDs or use any of the following EKU OIDs.

VA L UE DESC RIP T IO N

XCN_OID_ANY_APPLICATION_POLICY(1.3.6.1.4.1.311.10.12. The applications that can use the certificate are not
1) restricted.

XCN_OID_AUTO_ENROLL_CTL_USAGE(1.3.6.1.4.1.311.20.1) The certificate can be used to sign a request for automatic

enrollment in a certificate trust list (CTL).

XCN_OID_DRM(1.3.6.1.4.1.311.10.5.1) The certificate can be used for digital rights management

applications.

XCN_OID_DS_EMAIL_REPLICATION(1.3.6.1.4.1.311.21.19) The certificate can be used for Directory Service email

replication.

XCN_OID_EFS_RECOVERY(1.3.6.1.4.1.311.10.3.4.1) The certificate can be used for recovery of documents

protected by using Encrypting File System (EFS).

XCN_OID_EMBEDDED_NT_CRYPTO(1.3.6.1.4.1.311.10.3.8) The certificate can be used for Windows NT Embedded

cryptography.

XCN_OID_ENROLLMENT_AGENT(1.3.6.1.4.1.311.20.2.1) The certificate can be used by an enrollment agent.

XCN_OID_IPSEC_KP_IKE_INTERMEDIATE(1.3.6.1.5.5.8.2.2) The certificate can be used for Internet Key Exchange (IKE).

XCN_OID_KP_CA_EXCHANGE(1.3.6.1.4.1.311.21.5) The certificate can be used for archiving a private key on a

certification authority.

XCN_OID_KP_CTL_USAGE_SIGNING(1.3.6.1.4.1.311.10.3.1) The certificate can be used to sign a CTL.

XCN_OID_KP_DOCUMENT_SIGNING(1.3.6.1.4.1.311.10.3.12) The certificate can be used for signing documents.

XCN_OID_KP_EFS(1.3.6.1.4.1.311.10.3.4) The certificate can be used to encrypt files by using the

Encrypting File System.

XCN_OID_KP_KEY_RECOVERY(1.3.6.1.4.1.311.10.3.11) The certificate can be used to encrypt and recover escrowed

keys.

XCN_OID_KP_KEY_RECOVERY_AGENT(1.3.6.1.4.1.311.21.6) The certificate is used to identify a key recovery agent.

XCN_OID_KP_LIFETIME_SIGNING(1.3.6.1.4.1.311.10.3.13) Limits the validity period of a signature to the validity period
of the certificate. This restriction is typically used with the
XCN_OID_PKIX_KP_CODE_SIGNING OID value to indicate
that new time stamp semantics should be used.

XCN_OID_KP_QUALIFIED_SUBORDINATION(1.3.6.1.4.1.311. The certificate can be used to sign cross certificate and

10.3.10) subordinate certification authority certificate requests.
Qualified subordination is implemented by applying basic
constraints, certificate policies, and application policies. Cross
certification typically requires policy mapping.

XCN_OID_KP_SMARTCARD_LOGON(1.3.6.1.4.1.311.20.2.2) The certificate enables an individual to log on to a computer

by using a smart card.

XCN_OID_KP_TIME_STAMP_SIGNING(1.3.6.1.4.1.311.10.3.2) The certificate can be used to sign a time stamp to be added

to a document. Time stamp signing is typically part of a time
stamping service.

XCN_OID_LICENSE_SERVER(1.3.6.1.4.1.311.10.6.2) The certificate can be used by a license server when

transacting with Microsoft to receive licenses for Terminal
Services clients.

XCN_OID_LICENSES(1.3.6.1.4.1.311.10.6.1) The certificate can be used for key pack licenses.

XCN_OID_NT5_CRYPTO(1.3.6.1.4.1.311.10.3.7) The certificate can be used for Windows Server 2003,

Windows XP, and Windows 2000 cryptography.

XCN_OID_OEM_WHQL_CRYPTO(1.3.6.1.4.1.311.10.3.7) The certificate can be used for used for Original Equipment
Manufacturers (OEM) Windows Hardware Quality Labs
(WHQL) cryptography.

XCN_OID_PKIX_KP_CLIENT_AUTH(1.3.6.1.5.5.7.3.2) The certificate can be used for authenticating a client.

XCN_OID_PKIX_KP_CODE_SIGNING(1.3.6.1.5.5.7.3.3) The certificate can be used for signing code.

XCN_OID_PKIX_KP_EMAIL_PROTECTION(1.3.6.1.5.5.7.3.4) The certificate can be used to encrypt email messages.

XCN_OID_PKIX_KP_IPSEC_END_SYSTEM(1.3.6.1.5.5.7.3.5) The certificate can be used for signing end-to-end Internet

Protocol Security (IPSEC) communication.

XCN_OID_PKIX_KP_IPSEC_TUNNEL(1.3.6.1.5.5.7.3.6) The certificate can be used for singing IPSEC communication

in tunnel mode.

XCN_OID_PKIX_KP_IPSEC_USER(1.3.6.1.5.5.7.3.7) The certificate can be used for an IPSEC user.

XCN_OID_PKIX_KP_OCSP_SIGNING(1.3.6.1.5.5.7.3.9) The certificate can be used for Online Certificate Status

Protocol (OCSP) signing.

XCN_OID_PKIX_KP_SERVER_AUTH(1.3.6.1.5.5.7.3.1) The certificate can be used for OCSP authentication.

XCN_OID_PKIX_KP_TIMESTAMP_SIGNING(1.3.6.1.5.5.7.3.8) The certificate can be used for signing public key

infrastructure timestamps.

XCN_OID_ROOT_LIST_SIGNER(1.3.6.1.4.1.311.10.3.9) The certificate can be used sign a certificate root list.

 XCN_OID_WHQL_CRYPTO(1.3.6.1.4.1.311.10.3.5) The certificate can be used for Windows Hardware Quality
Labs (WHQL) cryptography.

A single policy is defined by an ICertificatePolicy object. A collection is defined by an ICertificatePolicies object.

You can use the collection to initialize an IX509ExtensionMSApplicationPolicies object.
You can use this extension to specify which applications can use a certificate or force an application to accept
only certificates for which certain OIDs have been listed. Typically, the application reviews the certificate to
ensure that the MSApplicationPolicies extension contains the required OIDs.
To add this extension object to a PKCS #10 request or a CMC request, you must first add it to an IX509Extensions
collection and use the collection to initialize an IX509AttributeExtensions object. For more information, see PKCS
#10 Extensions and CMC Extensions.

Inheritance
The IX509ExtensionMSApplicationPolicies interface inherits from IX509Extension.
IX509ExtensionMSApplicationPolicies also has these types of members:

Methods
The IX509ExtensionMSApplicationPolicies interface has these methods.

IX509ExtensionMSApplicationPolicies::get_Policies

Retrieves a collection of application policies.

IX509ExtensionMSApplicationPolicies::InitializeDecode

Initializes the extension from a Distinguished Encoding Rules (DER) encoded byte array that contains the extension value.

IX509ExtensionMSApplicationPolicies::InitializeEncode

Initializes the extension from an ICertificatePolicies collection.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

See also
Certificate Enrollment API
Extensions
IX509Extension
 IX509ExtensionMSApplicationPolicies::get_Policies
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Policies property retrieves a collection of application policies.

This property is read-only.

Syntax
HRESULT get_Policies(
ICertificatePolicies **ppValue
);

Parameters
ppValue

Return value
None

Remarks
Call the InitializeEncode method or the InitializeDecode method to initialize the collection. You can also call the
Critical property to specify and retrieve a Boolean value that identifies whether the extension is critical, and you
can call the ObjectId property to retrieve the object identifier (OID) associated with the extension.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509ExtensionMSApplicationPolicies
 IX509ExtensionMSApplicationPolicies::InitializeDecode
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The InitializeDecode method initializes the extension from a Distinguished Encoding Rules (DER) encoded byte
array that contains the extension value. The encoded byte array is represented by a Unicode encoded string.

Syntax
HRESULT InitializeDecode(
[in] EncodingType Encoding,
[in] BSTR strEncodedData
);

Parameters
[in] Encoding

An EncodingType enumeration value that specifies the type of Unicode encoding applied to the strEncodedData
value.
[in] strEncodedData

A BSTR variable that contains the DER-encoded extension.

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. Possible values include, but are not
limited to, those in the following table. For a list of common error codes, see Common HRESULT Values.

RET URN C O DE/ VA L UE DESC RIP T IO N

The object is already initialized.

HRESULT_FROM_WIN32(ERROR_ALREADY_INITIALIZE
D)

Remarks
You can use this method if you have a DER-encoded Abstract Syntax Notation One (ASN.1) object that contains a
Cer tificatePolicies extension. You must supply the DER-encoded object in a Unicode encoded string. For more
information, see the IBinaryConverter interface.
You must call either InitializeEncode or InitializeDecode before you can use an
IX509ExtensionMSApplicationPolicies object. The two methods complement each other. The InitializeEncode
method enables you to construct a DER-encoded ASN.1 extension object from raw data, and the
InitializeDecode method enables you to initialize the raw data from an encoded object.
You can retrieve the following properties for this extension:
 The Critical property identifies whether the extension is critical. You can also specify this property.
The ObjectId property retrieves the extension object identifier (OID).
The Policies property retrieves the collection of certificate policies (the raw extension data).

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509ExtensionMSApplicationPolicies
InitializeEncode
 IX509ExtensionMSApplicationPolicies::InitializeEncode
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The InitializeEncode method initializes the extension from an ICertificatePolicies collection.

Syntax
HRESULT InitializeEncode(
[in] ICertificatePolicies *pValue
);

Parameters
[in] pValue

Pointer to the ICertificatePolicies interface.

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. Possible values include, but are not
limited to, those in the following table. For a list of common error codes, see Common HRESULT Values.

RET URN C O DE/ VA L UE DESC RIP T IO N

The object is already initialized.

HRESULT_FROM_WIN32(ERROR_ALREADY_INITIALIZE
D)

Remarks
You must call either InitializeEncode or InitializeDecode before you can use an
IX509ExtensionMSApplicationPolicies object. The two methods complement each other. The InitializeEncode
method enables you to construct a Distinguished Encoding Rules (DER) encoded ASN.1 extension object from
raw data, and the InitializeDecode method enables you to initialize the raw data from an encoded object.
You can retrieve the following properties for this extension:
The Critical property identifies whether the extension is critical. You can also specify this property.
The ObjectId property retrieves the extension object identifier (OID).
The Policies property retrieves the collection of certificate policies (the raw extension data).

Requirements
 Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509ExtensionMSApplicationPolicies
InitializeDecode
 IX509Extensions interface (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The IX509Extensions interface defines the following methods and properties to manage a collection of
IX509Extension objects.

Inheritance
The IX509Extensions interface inherits from the IDispatch interface. IX509Extensions also has these types of
members:

Methods
The IX509Extensions interface has these methods.

IX509Extensions::Add

Adds an IX509Extension object to the collection.

IX509Extensions::AddRange

Adds a range of IX509Extension objects to the collection.

IX509Extensions::Clear

Removes all IX509Extension objects from the collection.

IX509Extensions::get__NewEnum

Retrieves the enumerator for the collection.

IX509Extensions::get_Count

Retrieves the number of IX509Extension objects in the collection.

IX509Extensions::get_IndexByObjectId

Retrieves the index of an extension in the collection by object identifier (OID).

IX509Extensions::get_ItemByIndex

Retrieves an IX509Extension object from the collection by index number.

IX509Extensions::Remove

Removes an IX509Extension object from the collection by index number.

Requirements
 Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

See also
CertEnroll Interfaces
IDispatch
IX509Extension
 IX509Extensions::Add method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Add method adds an IX509Extension object to the collection. This method is web enabled.

Syntax
HRESULT Add(
[in] IX509Extension *pVal
);

Parameters
[in] pVal

Pointer to an IX509Extension object to add to the collection.

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509Extension
IX509Extensions
 IX509Extensions::AddRange method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The AddRange method adds a range of IX509Extension objects to the collection.

Syntax
HRESULT AddRange(
[in] IX509Extensions *pValue
);

Parameters
[in] pValue

Pointer to an IX509Extensions interface that contains the collection to add.

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509Extension
IX509Extensions
 IX509Extensions::Clear method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Clear method removes all IX509Extension objects from the collection.

Syntax
HRESULT Clear();

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509Extension
IX509Extensions
 IX509Extensions::get__NewEnum method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The _NewEnum property retrieves the enumerator for the collection.

This property is read-only.

Syntax
HRESULT get__NewEnum(
LPUNKNOWN *pVal
);

Parameters
pVal

Return value
None

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509Extension
IX509Extensions
 IX509Extensions::get_Count method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Count property retrieves the number of IX509Extension objects in the collection. This property is web
enabled.
This property is read-only.

Syntax
HRESULT get_Count(
long *pVal
);

Parameters
pVal

Return value
None

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509Extension
IX509Extensions
 IX509Extensions::get_IndexByObjectId method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The IndexByObjectId property retrieves the index of an extension in the collection by object identifier (OID).
This property is read-only.

Syntax
HRESULT get_IndexByObjectId(
IObjectId *pObjectId,
LONG *pIndex
);

Parameters
pObjectId

pIndex

Return value
None

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509Extension
IX509Extensions
 IX509Extensions::Remove method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Remove method removes an IX509Extension object from the collection by index number.

Syntax
HRESULT Remove(
[in] LONG Index
);

Parameters
[in] Index

A LONG variable that contains the index of the object to remove.

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509Extension
IX509Extensions
 IX509ExtensionSmimeCapabilities interface
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The IX509ExtensionSmimeCapabilities interface can be used to report the decryption capabilities of an

email recipient to an email sender so that the sender can choose the most secure algorithm supported by both
parties. The following syntax shows the Abstract Syntax Notation One (ASN.1) structure of the extension. The
extension value is encoded by using Distinguished Encoding Rules (DER) and included in the certificate request.

----------------------------------------------------------------------
-- SMIMECapabilities
-- XCN_OID_RSA_SMIMECapabilities (1.2.840.113549.1.9.15)
----------------------------------------------------------------------

SMIMECapabilities ::= SEQUENCE OF SMIMECapability

SMIMECapability ::= SEQUENCE

{
capabilityID EncodedObjectID,
smimeParameters ANY OPTIONAL
}

The extension can be initialized from a collection of ISmimeCapability objects, each of which identifies a
symmetric encryption algorithm and optional key length. The following algorithms are supported.

O ID DESC RIP T IO N

XCN_OID_OIWSEC_desCBC(1.3.14.3.2.7) Data Encryption Standard (DES) in cipher block chaining

(CBC) mode. The key length is 56 bits.

XCN_OID_RSA_DES_EDE3_CBC(1.2.840.113549.3.7) Triple DES (3DES) in CBC mode. The key length is 168 bits.

XCN_OID_RSA_RC2CBC(1.2.840.113549.3.2) RC2 algorithm in CBC mode. The key length is variable from
40 to 128 bits.

XCN_OID_RSA_RC4(1.2.840.113549.3.4) RC4 algorithm. The key length is variable from 40 to 128

bits.

XCN_OID_RSA_SMIMEalgCMS3DESwrap(1.2.840.113549.1.9 3DES used for key wrapping. The key length is 168 bits.
.16.3.6)

XCN_OID_RSA_SMIMEalgCMSRC2wrap(1.2.840.113549.1.9. RC2 used for key wrapping. The key length is 128 bits.
16.3.7)

XCN_OID_NIST_AES128_CBC(2.16.840.1.101.3.4.1.2) Advanced Encryption Standard (AES) in CBC mode. The key

length is 128 bits.

XCN_OID_NIST_AES192_CBC(2.16.840.1.101.3.4.1.22) AES in CBC mode. The key length is 192 bits.

XCN_OID_NIST_AES256_CBC(2.16.840.1.101.3.4.1.42) AES in CBC mode. The key length is 256 bits.

 XCN_OID_NIST_AES128_WRAP(2.16.840.1.101.3.4.1.5) AES used for key wrapping. The key length is 128 bits.

XCN_OID_NIST_AES192_WRAP(2.16.840.1.101.3.4.1.25) AES used for key wrapping. The key length is 192 bits.

XCN_OID_NIST_AES256_WRAP(2.16.840.1.101.3.4.1.45) AES used for key wrapping. The key length is 256 bits.

To add this extension object to a PKCS #10 request or a CMC request, you must first add it to an IX509Extensions
collection and use the collection to initialize an IX509AttributeExtensions object. For more information, see the
PKCS #10 Extensions and the CMC Extensions topics.

Inheritance
The IX509ExtensionSmimeCapabilities interface inherits from IX509Extension.
IX509ExtensionSmimeCapabilities also has these types of members:

Methods
The IX509ExtensionSmimeCapabilities interface has these methods.

IX509ExtensionSmimeCapabilities::get_SmimeCapabilities

Retrieves a collection of ISmimeCapability objects.

IX509ExtensionSmimeCapabilities::InitializeDecode

Initializes the extension from a Distinguished Encoding Rules (DER) encoded byte array that contains the extension value.

IX509ExtensionSmimeCapabilities::InitializeEncode

Initializes the extension from an ISmimeCapabilities collection.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

See also
IX509Extension
 IX509ExtensionSmimeCapabilities::get_SmimeCapabilities
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The SmimeCapabilities property retrieves a collection of ISmimeCapability objects.

This property is read-only.

Syntax
HRESULT get_SmimeCapabilities(
ISmimeCapabilities **ppValue
);

Parameters
ppValue

Return value
None

Remarks
Call the InitializeEncode method or the InitializeDecode method to initialize the SMIMECapabilities extension.
You can also call the Critical property to specify and retrieve a Boolean value that identifies whether the
extension is critical, and you can call the ObjectId property to retrieve the OID associated with the extension.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509ExtensionSmimeCapabilities
 IX509ExtensionSmimeCapabilities::InitializeDecode
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The InitializeDecode method initializes the extension from a Distinguished Encoding Rules (DER) encoded byte
array that contains the extension value. The DER-encoded byte array is represented by a Unicode encoded
string.

Syntax
HRESULT InitializeDecode(
[in] EncodingType Encoding,
[in] BSTR strEncodedData
);

Parameters
[in] Encoding

An EncodingType enumeration value that specifies the type of Unicode encoding applied to the strEncodedData
parameter.
[in] strEncodedData

A BSTR variable that contains the DER-encoded extension.

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. Possible values include, but are not
limited to, those in the following table. For a list of common error codes, see Common HRESULT Values.

RET URN C O DE/ VA L UE DESC RIP T IO N

The object is already initialized.

HRESULT_FROM_WIN32(ERROR_ALREADY_INITIALIZE
D)

Remarks
You can use this method if you have a DER-encoded ASN.1 object that contains a SmimeCapabilities
extension. You must supply the DER-encoded object in a Unicode encoded string. For more information, see the
IBinaryConverter interface.
You must call either InitializeEncode or InitializeDecode before you can use an
IX509ExtensionSmimeCapabilities object. The two methods complement each other. The InitializeEncode
method enables you to construct a DER-encoded ASN.1 extension object from raw data, and the
InitializeDecode method enables you to initialize the raw data from an encoded object.
You can retrieve the following properties for this extension:
The Critical property identifies whether the extension is critical. You can also specify this property.
The ObjectId property retrieves the extension OID.
The SmimeCapabilities property retrieves the collection of capabilities (the raw extension data).

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509ExtensionSmimeCapabilities
 IX509ExtensionSmimeCapabilities::InitializeEncode
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The InitializeEncode method initializes the extension from an ISmimeCapabilities collection.

Syntax
HRESULT InitializeEncode(
[in] ISmimeCapabilities *pValue
);

Parameters
[in] pValue

Pointer to the ISmimeCapabilities interface.

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. Possible values include, but are not
limited to, those in the following table. For a list of common error codes, see Common HRESULT Values.

RET URN C O DE/ VA L UE DESC RIP T IO N

The object is already initialized.

HRESULT_FROM_WIN32(ERROR_ALREADY_INITIALIZE
D)

Remarks
You must call either InitializeEncode or InitializeDecode before you can use an
IX509ExtensionSmimeCapabilities object. The two methods complement each other. The InitializeEncode
method enables you to construct a Distinguished Encoding Rules (DER) encoded ASN.1 extension object from
raw data, and the InitializeDecode method enables you to initialize the raw data from an encoded object.
You can retrieve the following properties for this extension:
The Critical property identifies whether the extension is critical. You can also specify this property.
The ObjectId property retrieves the extension OID.
The SmimeCapabilities property retrieves the collection of capabilities (the raw extension data).

Requirements
 Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
ISmimeCapabilities
IX509ExtensionSmimeCapabilities
 IX509ExtensionSubjectKeyIdentifier interface
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The IX509ExtensionSubjectKeyIdentifier interface enables you to specify a SubjectKeyIdentifier extension.

When a subject has multiple signing certificates, this extension can be used to help identify which certificate
matches a specific certification authority (CA) signing certificate. The extension is placed in all certificates. The
following syntax shows the Abstract Syntax Notation One (ASN.1) structure of the extension. The extension
value is encoded by using Distinguished Encoding Rules (DER) and included in the certificate request.

----------------------------------------------------------------------
-- SubjectKeyIdentifier
-- XCN_OID_SUBJECT_KEY_IDENTIFIER (2.5.29.14)
----------------------------------------------------------------------

SubjectKeyIdentifier ::= KeyIdentifier

KeyIdentifier ::= OCTETSTRING

Typically the value is a 20-byte SHA-1 hash of the public key contained in the CA signing certificate. When the
CA issues a certificate, it copies the hash value into the SubjectKeyIdentifier extension. To find the end-entity
certificate signed by a particular CA certificate, chain building software searches until it matches the
keyIdentifier field in the AuthorityKeyIdentifier extension on the CA signing certificate with a
SubjectKeyIdentifier extension value on an issued certificate. For more information, see
IX509ExtensionAuthorityKeyIdentifier.
To add this extension object to a PKCS #10 request or a CMC request, you must first add it to an IX509Extensions
collection and use the collection to initialize an IX509AttributeExtensions object. For more information, see the
PKCS #10 Extensions and the CMC Extensions topics.

Inheritance
The IX509ExtensionSubjectKeyIdentifier interface inherits from IX509Extension.
IX509ExtensionSubjectKeyIdentifier also has these types of members:

Methods
The IX509ExtensionSubjectKeyIdentifier interface has these methods.

IX509ExtensionSubjectKeyIdentifier::get_SubjectKeyIdentifier

Retrieves a byte array that contains the key identifier.

IX509ExtensionSubjectKeyIdentifier::InitializeDecode

Initializes the extension from a Distinguished Encoding Rules (DER) encoded byte array that contains the extension value.
 IX509ExtensionSubjectKeyIdentifier::InitializeEncode

Initializes the extension from a byte array that contains the key identifier.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

See also
Certificate Enrollment API
Extensions
IX509Extension
 IX509ExtensionSubjectKeyIdentifier::get_SubjectKeyIdentifier
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The SubjectKeyIdentifier property retrieves a byte array that contains the key identifier. The byte array is
represented by a Unicode-encoded string.
This property is read-only.

Syntax
HRESULT get_SubjectKeyIdentifier(
EncodingType Encoding,
BSTR *pValue
);

Parameters
Encoding

pValue

Return value
None

Remarks
Call the InitializeDecode method or the InitializeEncode method to initialize the
IX509ExtensionSubjectKeyIdentifier object. You can also call the Critical property to specify and retrieve a
Boolean value that identifies whether the extension is critical, and you can call the ObjectId property to retrieve
the object identifier (OID) associated with the extension.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509ExtensionSubjectKeyIdentifier
 IX509ExtensionSubjectKeyIdentifier::InitializeDecode
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The InitializeDecode method initializes the extension from a Distinguished Encoding Rules (DER) encoded byte
array that contains the extension value. The encoded byte array is represented by a Unicode encoded string.

Syntax
HRESULT InitializeDecode(
[in] EncodingType Encoding,
[in] BSTR strEncodedData
);

Parameters
[in] Encoding

An EncodingType enumeration value that specifies the type of Unicode encoding applied to the strEncodedData
parameter.
[in] strEncodedData

A BSTR variable that contains the DER-encoded extension.

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. Possible values include, but are not
limited to, those in the following table. For a list of common error codes, see Common HRESULT Values.

RET URN C O DE/ VA L UE DESC RIP T IO N

The object is already initialized.

HRESULT_FROM_WIN32(ERROR_ALREADY_INITIALIZE
D)

Remarks
You can use this method if you have a DER-encoded Abstract Syntax Notation One (ASN.1) object that contains a
SubjectKeyIdentifier extension. You must supply the DER-encoded object in a Unicode encoded string. For
more information, see the IBinaryConverter interface.
You must call either InitializeEncode or InitializeDecode before you can use an
IX509ExtensionSubjectKeyIdentifier object. The two methods complement each other. The InitializeEncode
method enables you to construct a DER-encoded ASN.1 extension object from raw data, and the
InitializeDecode method enables you to initialize the raw data from an encoded object.
You can retrieve the following properties for this extension:
 The Critical property identifies whether the extension is critical. You can also specify this property.
The ObjectId property retrieves the object identifier (OID).
The SubjectKeyIdentifier property retrieves the raw data.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509ExtensionSubjectKeyIdentifier
 IX509ExtensionSubjectKeyIdentifier::InitializeEncode
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The InitializeEncode method initializes the extension from a byte array that contains the key identifier. The byte
array is represented by a Unicode-encoded string.

Syntax
HRESULT InitializeEncode(
[in] EncodingType Encoding,
[in] BSTR strKeyIdentifier
);

Parameters
[in] Encoding

An EncodingType enumeration value that specifies the type of Unicode encoding applied to the strKeyIdentifier
parameter.
[in] strKeyIdentifier

A BSTR variable that contains the key identifier.

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. Possible values include, but are not
limited to, those in the following table. For a list of common error codes, see Common HRESULT Values.

RET URN C O DE/ VA L UE DESC RIP T IO N

The object is already initialized.

HRESULT_FROM_WIN32(ERROR_ALREADY_INITIALIZE
D)

Remarks
Typically, the input value should be a SHA-1 hash of the public key contained in the certification authority
signing certificate. The method associates the value with the XCN_OID_SUBJECT_KEY_IDENTIFIER (2.5.29.14)
object identifier (OID) and encodes it by using Distinguished Encoding Rules (DER).
You must call either InitializeEncode or InitializeDecode before you can use an
IX509ExtensionSubjectKeyIdentifier object. The two methods complement each other. The InitializeEncode
method enables you to construct a DER-encoded Abstract Syntax Notation One (ASN.1) extension object from
raw data, and the InitializeDecode method enables you to initialize the raw data from an encoded object.
You can retrieve the following properties for this extension:
 The Critical property identifies whether the extension is critical. You can also specify this property.
The ObjectId property retrieves the OID.
The AuthorityKeyIdentifier property retrieves the raw data.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509ExtensionSubjectKeyIdentifier
 IX509ExtensionTemplate interface (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The IX509ExtensionTemplate interface defines methods and properties that can be used to initialize or
retrieve a Cer tificateTemplate extension. This extension can be placed in the certificate request to tell the
certification authority what template to use when issuing or renewing a certificate.

Note The Cer tificateTemplate extension is used to identify version 2 templates. To identify a version 1 template, you can
use the Cer tificateTemplateName extension defined by the IX509ExtensionTemplateName interface.

The following syntax shows the Abstract Syntax Notation One (ASN.1) structure of the extension. The extension
value is encoded by using Distinguished Encoding Rules (DER) and included in the certificate request.

----------------------------------------------------------------------
-- CertificateTemplate
-- XCN_OID_CERTIFICATE_TEMPLATE (1.3.6.1.4.1.311.21.7)
----------------------------------------------------------------------

CertificateTemplate ::= SEQUENCE

{
templateID EncodedObjectID,
templateMajorVersion TemplateVersion,
templateMinorVersion TemplateVersion OPTIONAL
}

TemplateVersion ::= INTEGER (0..4294967295)

To add this extension object to a PKCS #10 request or a CMC request, you must first add it to an IX509Extensions
collection and use the collection to initialize an IX509AttributeExtensions object. For more information, see the
PKCS #10 Extensions and the CMC Extensions topics.

Inheritance
The IX509ExtensionTemplate interface inherits from IX509Extension. IX509ExtensionTemplate also has
these types of members:

Methods
The IX509ExtensionTemplate interface has these methods.

IX509ExtensionTemplate::get_MajorVersion

Retrieves the minimum major version number of the certificate template.

IX509ExtensionTemplate::get_MinorVersion

Retrieves the minimum minor version number of the certificate template.

 IX509ExtensionTemplate::get_TemplateOid

Retrieves the template object identifier (OID).

IX509ExtensionTemplate::InitializeDecode

Initializes the extension from a DER-encoded byte array that contains the extension value.

IX509ExtensionTemplate::InitializeEncode

Initializes the extension from a template object identifier (OID) and from major and minor version numbers.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

See also
CertEnroll Interfaces
IX509Extension
 IX509ExtensionTemplate::get_MajorVersion method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The MajorVersion property retrieves the minimum major version number of the certificate template.
This property is read-only.

Syntax
HRESULT get_MajorVersion(
LONG *pValue
);

Parameters
pValue

Return value
None

Remarks
You must call either InitializeEncode or InitializeDecode before you can use an IX509ExtensionTemplate object.
You can retrieve the following additional properties for this extension:
The Critical property identifies whether the extension is critical. You can also specify this property.
The ObjectId property retrieves the object identifier (OID).
The MinorVersion property retrieves version information.
The TemplateOid property retrieves the OID of the template.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509ExtensionTemplate
 IX509ExtensionTemplate::get_MinorVersion method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The MinorVersion property retrieves the minimum minor version number of the certificate template.
This property is read-only.

Syntax
HRESULT get_MinorVersion(
LONG *pValue
);

Parameters
pValue

Return value
None

Remarks
You must call either InitializeEncode or InitializeDecode before you can use an IX509ExtensionTemplate object.
You can retrieve the following additional properties for this extension:
The Critical property identifies whether the extension is critical. You can also specify this property.
The ObjectId property retrieves the object identifier (OID).
The MajorVersion property retrieves version information.
The TemplateOid property retrieves the OID of the template.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509ExtensionTemplate
 IX509ExtensionTemplate::get_TemplateOid method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The TemplateOid property retrieves the template object identifier (OID).

This property is read-only.

Syntax
HRESULT get_TemplateOid(
IObjectId **ppValue
);

Parameters
ppValue

Return value
None

Remarks
You must call either InitializeEncode or InitializeDecode before you can use an IX509ExtensionTemplate object.
You can retrieve the following additional properties for this extension:
The Critical property identifies whether the extension is critical. You can also specify this property.
The ObjectId property retrieves the OID.
The MajorVersion and MinorVersion properties retrieve the version information.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509ExtensionTemplate
 IX509ExtensionTemplate::InitializeDecode method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The InitializeDecode method initializes the extension from a DER-encoded byte array that contains the
extension value. The encoded byte array is represented by a Unicode encoded string.

Syntax
HRESULT InitializeDecode(
[in] EncodingType Encoding,
[in] BSTR strEncodedData
);

Parameters
[in] Encoding

An EncodingType enumeration value that specifies the type of Unicode encoding applied to the strEncodedData
parameter.
[in] strEncodedData

A BSTR variable that contains the DER-encoded extension.

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. Possible values include, but are not
limited to, those in the following table. For a list of common error codes, see Common HRESULT Values.

RET URN C O DE/ VA L UE DESC RIP T IO N

The object is already initialized.

HRESULT_FROM_WIN32(ERROR_ALREADY_INITIALIZE
D)

Remarks
You can use this method if you have a Distinguished Encoding Rules (DER) encoded Abstract Syntax Notation
One (ASN.1) object that contains a Cer tificateTemplate extension. You must supply the DER-encoded object in
a Unicode encoded string. For more information, see the IBinaryConverter interface.
You must call either InitializeEncode or InitializeDecode before you can use an IX509ExtensionTemplate object.
The two methods complement each other. The InitializeEncode method enables you to construct a DER-
encoded ASN.1 extension object from raw data, and the InitializeDecode method enables you to initialize the
raw data from an encoded object.
You can retrieve the following properties for this extension:
 The Critical property identifies whether the extension is critical. You can also specify this property.
The ObjectId property retrieves the object identifier (OID).
The MajorVersion and MinorVersion properties retrieve the version information.
The TemplateOid property retrieves the OID of the template.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509ExtensionTemplate
 IX509ExtensionTemplate::InitializeEncode method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The InitializeEncode method initializes the extension from a template object identifier (OID) and from major
and minor version numbers. This method is web enabled.

Syntax
HRESULT InitializeEncode(
[in] IObjectId *pTemplateOid,
[in] LONG MajorVersion,
[in] LONG MinorVersion
);

Parameters
[in] pTemplateOid

Pointer to an IObjectId interface that represents the template OID.

[in] MajorVersion

A LONG variable that contains the major version number of the template. The default value is zero (0).
[in] MinorVersion

A LONG variable that contains the minor version number of the template. The default value is zero (0).

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. Possible values include, but are not
limited to, those in the following table. For a list of common error codes, see Common HRESULT Values.

RET URN C O DE/ VA L UE DESC RIP T IO N

The object is already initialized.

HRESULT_FROM_WIN32(ERROR_ALREADY_INITIALIZE
D)

Remarks
You must call either InitializeEncode or InitializeDecode before you can use an IX509ExtensionTemplate object.
The two methods complement each other. The InitializeEncode method enables you to construct a
Distinguished Encoding Rules (DER) encoded Abstract Syntax Notation One (ASN.1) extension object from raw
data, and the InitializeDecode method enables you to initialize the raw data from an encoded object.
You can retrieve the following properties for this extension:
 The Critical property identifies whether the extension is critical. You can also specify this property.
The ObjectId property retrieves the OID.
The MajorVersion and MinorVersion properties retrieve the version information.
The TemplateOid property retrieves the OID of the template.
You must call either InitializeEncode or InitializeDecode before you can use an IX509ExtensionBasicConstraints
object. The two methods complement each other. The InitializeEncode method enables you to construct an
encoded ASN.1 structure from raw data, and the InitializeDecode method enables you to initialize the raw
data from an encoded ASN.1 structure. You can retrieve the raw data for the extension by calling the
MajorVersion, MinorVersion, and TemplateOid properties.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509ExtensionTemplate
 IX509ExtensionTemplateName interface
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The IX509ExtensionTemplateName interface defines methods and properties that can be used to initialize or
retrieve a template name extension. This extension can be placed in the certificate request to tell the certification
authority what template to use when issuing or renewing a certificate. The template is identified by name.

Note The Cer tificateTemplateName extension is used to identify version 1 templates. To identify a version 2 template, you
can use the Cer tificateTemplate extension defined by the IX509ExtensionTemplate interface.

The extension is encoded as a name-value pair where name equals the Unicode string "CertificateTemplate" and
the associated value is the name of the template. The following syntax shows an example of the Abstract Syntax
Notation One (ASN.1) output for the template named "User". The extension value is encoded by using
Distinguished Encoding Rules (DER).

30 42 ; SEQUENCE (42 Bytes)

| 06 0a ; OBJECT_ID (a Bytes)
| | 2b 06 01 04 01 82 37 0d 02 01
| | ; 1.3.6.1.4.1.311.13.2.1 Enrollment Name Value Pair
| 31 34 ; SET (34 Bytes)
| 30 32 ; SEQUENCE (32 Bytes)
| 1e 26 ; UNICODE_STRING (26 Bytes)
| | 00 43 00 65 00 72 00 74 00 69 00 66 00 69 00 63 ; .C.e.r.t.i.f.i.c
| | 00 61 00 74 00 65 00 54 00 65 00 6d 00 70 00 6c ; .a.t.e.T.e.m.p.l
| | 00 61 00 74 00 65 ; .a.t.e
| | ; "CertificateTemplate"
| 1e 08 ; UNICODE_STRING (8 Bytes)
| 00 55 00 73 00 65 00 72 ; .U.s.e.r
| ; "User"

To add this extension object to a PKCS #10 request or a CMC request, you must first add it to an IX509Extensions
collection and use the collection to initialize an IX509AttributeExtensions object. For more information, see the
PKCS #10 Extensions and the CMC Extensions topics.

Inheritance
The IX509ExtensionTemplateName interface inherits from IX509Extension.
IX509ExtensionTemplateName also has these types of members:

Methods
The IX509ExtensionTemplateName interface has these methods.
 IX509ExtensionTemplateName::get_TemplateName

Retrieves the name of the template.

IX509ExtensionTemplateName::InitializeDecode

Initializes the extension from a Distinguished Encoding Rules (DER) encoded byte array that contains the extension value.

IX509ExtensionTemplateName::InitializeEncode

Initializes the extension from a string that contains the template name.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

See also
CertEnroll Interfaces
IX509Extension
 IX509ExtensionTemplateName::get_TemplateName
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The TemplateName property retrieves the name of the template.

This property is read-only.

Syntax
HRESULT get_TemplateName(
BSTR *pValue
);

Parameters
pValue

Return value
None

Remarks
You must call either InitializeEncode or InitializeDecode before you can use an IX509ExtensionTemplateName
object. You can retrieve the following additional properties for this extension:
The Critical property identifies whether the extension is critical. You can also specify this property.
The ObjectId property retrieves the object identifier (OID).

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509ExtensionTemplateName
 IX509ExtensionTemplateName::InitializeDecode
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The InitializeDecode method initializes the extension from a Distinguished Encoding Rules (DER) encoded byte
array that contains the extension value. The encoded byte array is represented by a Unicode encoded string.

Syntax
HRESULT InitializeDecode(
[in] EncodingType Encoding,
[in] BSTR strEncodedData
);

Parameters
[in] Encoding

An EncodingType enumeration value that specifies the type of Unicode encoding applied to the strEncodedData
parameter.
[in] strEncodedData

A BSTR variable that contains the DER-encoded extension.

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. Possible values include, but are not
limited to, those in the following table. For a list of common error codes, see Common HRESULT Values.

RET URN C O DE/ VA L UE DESC RIP T IO N

The object is already initialized.

HRESULT_FROM_WIN32(ERROR_ALREADY_INITIALIZE
D)

Remarks
You can use this method if you have a DER-encoded Abstract Syntax Notation One (ASN.1) object that contains a
Cer tificateTemplateName extension. You must supply the DER-encoded object in a Unicode encoded string.
For more information, see the IBinaryConverter interface.
You must call either InitializeEncode or InitializeDecode before you can use an IX509ExtensionTemplateName
object. The two methods complement each other. The InitializeEncode method enables you to construct a
DER-encoded ASN.1 extension object from raw data, and the InitializeDecode method enables you to initialize
the raw data from an encoded object.
You can retrieve the following properties for this extension:
 The Critical property identifies whether the extension is critical. You can also specify this property.
The ObjectId property retrieves the object identifier (OID).
The TemplateName property retrieves the template name (the raw extension data).

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509ExtensionTemplateName
 IX509ExtensionTemplateName::InitializeEncode
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The InitializeEncode method initializes the extension from a string that contains the template name. This
method is web enabled.

Syntax
HRESULT InitializeEncode(
[in] BSTR strTemplateName
);

Parameters
[in] strTemplateName

A BSTR variable that contains the name.

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. Possible values include, but are not
limited to, those in the following table. For a list of common error codes, see Common HRESULT Values.

RET URN C O DE/ VA L UE DESC RIP T IO N

The object is already initialized.

HRESULT_FROM_WIN32(ERROR_ALREADY_INITIALIZE
D)

Remarks
You must call either InitializeEncode or InitializeDecode before you can use an IX509ExtensionTemplateName
object. The two methods complement each other. The InitializeEncode method enables you to construct a
Distinguished Encoding Rules (DER) encoded Abstract Syntax Notation One (ASN.1) extension object from raw
data, and the InitializeDecode method enables you to initialize the raw data from an encoded object.
You can retrieve the following properties for this extension:
The Critical property identifies whether the extension is critical. You can also specify this property.
The ObjectId property retrieves the object identifier (OID).
The TemplateName property retrieves the template name (the raw extension data).

Requirements
 Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509ExtensionTemplateName
 IX509MachineEnrollmentFactory interface
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The IX509MachineEnrollmentFactor y interface can be used to create an IX509EnrollmentHelper object on a

webpage. This object cannot be created directly inside of a script.

Inheritance
The IX509MachineEnrollmentFactor y interface inherits from the IDispatch interface.
IX509MachineEnrollmentFactor y also has these types of members:

Methods
The IX509MachineEnrollmentFactor y interface has these methods.

IX509MachineEnrollmentFactory::CreateObject

Creates an IX509EnrollmentHelper object on a webpage.

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Target Platform Windows

Header certenroll.h
 IX509MachineEnrollmentFactory::CreateObject
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The CreateObject method creates an IX509EnrollmentHelper object on a webpage. This method is web
enabled.

Syntax
HRESULT CreateObject(
[in] BSTR strProgID,
[out, retval] IX509EnrollmentHelper **ppIHelper
);

Parameters
[in] strProgID

A BSTR variable that contains the ProgID value. This must be "X509Enrollment.CX509EnrollmentHelper".
[out, retval] ppIHelper

Address of a pointer to a variable that receives a pointer to an IX509EnrollmentHelper interface.

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. Possible values include, but are not
limited to, those in the following table. For a list of common error codes, see Common HRESULT Values.

RET URN C O DE DESC RIP T IO N

The strProgID parameter cannot be NULL or empty.

E_INVALIDARG

The strProgID parameter must contain

E_NOINTERFACE "X509Enrollment.CX509EnrollmentHelper".

The ppIHelper parameter cannot be NULL .

E_POINTER

The strProgID parameter exceed 64,000 characters or

HRESULT_FROM_WIN32(ERROR_ARITHMETIC_OVERF contains embedded null characters.
LOW)

Remarks
This method calls Initialize on the IX509EnrollmentHelper interface by using the
ContextAdministratorForceMachine context value, thereby specifying that all certificates to be enrolled by
the IX509Enrollment2 object will be requested by an administrator acting on behalf of a computer. To enroll a
user certificate, call CreateObject on the IX509EnrollmentWebClassFactory interface.

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Target Platform Windows

Header certenroll.h

See also
IX509MachineEnrollmentFactory
 IX509NameValuePair interface (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The IX509NameValuePair interface represents a generic name-value pair. Although there are a few common
name-value pairs created by the certificate request and enrollment process, you can use this object to specify
any name and value. An IX509NameValuePairs collection can be retrieved from an IX509Enrollment object and
an IX509CertificateRequestCmc object. The collections are not related.
name-value pairs and the enrollment object:
Before an IX509Enrollment object submits a certificate request to a certification authority (CA), the name-value
collection is encoded as a concatenated attribute string that has the format Name1:Value1\Name2:Value2\. You can
retrieve the collection by calling the NameValuePairs property. You can use the IX509NameValuePairs object to add
name-value pairs to the collection.
name-value pairs and the CMC request object:
A CMC request object (IX509CertificateRequestCmc) contains sequences of TaggedAttribute , TaggedRequest ,
and TaggedContentInfo ASN.1 structures. For more information, see CMC Attributes
The TaggedAttribute structure can contain a RegInfo attribute. This attribute consists of a byte array that
contains the name-value pair collection. The byte array is created in the following manner:
Each name-value string is standardized. For example, "%5C" escapes are substituted for backslash (\\)
characters.
Each name-value pair is concatenated by using an equal sign (=).
All of the pairs are concatenated by using an ampersand (&)between each pair.
The result is encoded as a UTF-8 string.
The following example shows the ASN.1 output for a CMC certificate that contains a RegInfo attribute that
contains a single name-value pair of "RequesterName=Domain\TargetUser".

...
30 33 ; SEQUENCE (33 Bytes)
02 01 ; INTEGER (1 Bytes)
| 02
06 08 ; OBJECT_ID (8 Bytes)
| 2b 06 01 05 05 07 07 12
| ; 1.3.6.1.5.5.7.7.18 Reg Info
31 24 ; SET (24 Bytes)
04 22 ; OCTET_STRING (22 Bytes)
52 65 71 75 65 73 74 65 72 4e 61 6d 65 3d 44 6f ; RequesterName=Do
6d 61 69 6e 25 35 43 54 61 72 67 65 74 55 73 65 ; main%5CTargetUse
72 26 ; r&amp;
...

Inheritance
The IX509NameValuePair interface inherits from the IDispatch interface. IX509NameValuePair also has
these types of members:

Methods
The IX509NameValuePair interface has these methods.

IX509NameValuePair::get_Name

Retrieves the name portion of the name-value pair.

IX509NameValuePair::get_Value

Retrieves the value portion of the name-value pair.

IX509NameValuePair::Initialize

Initializes the object from strings that contain the name and associated value.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

See also
CertEnroll Interfaces
IDispatch
IX509NameValuePairs
 IX509NameValuePair::get_Name method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Name property retrieves the name portion of the name-value pair.
This property is read-only.

Syntax
HRESULT get_Name(
BSTR *pValue
);

Parameters
pValue

Return value
None

Remarks
You must call the Initialize method before calling this property.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509NameValuePair
 IX509NameValuePair::get_Value method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Value property retrieves the value portion of the name-value pair.
This property is read-only.

Syntax
HRESULT get_Value(
BSTR *pValue
);

Parameters
pValue

Return value
None

Remarks
You must call the Initialize method before calling this property.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509NameValuePair
 IX509NameValuePair::Initialize method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Initialize method initializes the object from strings that contain the name and associated value.

Syntax
HRESULT Initialize(
[in] BSTR strName,
[in] BSTR strValue
);

Parameters
[in] strName

A BSTR variable that contains the name.

[in] strValue

A BSTR variable that contains the value.

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.

Remarks
You can call the Name and Value properties to retrieve the values initialized by calling this method.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509NameValuePair
Name
Value
 IX509NameValuePairs interface (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The IX509NameValuePairs interface defines the following methods and properties to manage a collection of
IX509NameValuePair objects.

Inheritance
The IX509NameValuePairs interface inherits from the IDispatch interface. IX509NameValuePairs also has
these types of members:

Methods
The IX509NameValuePairs interface has these methods.

IX509NameValuePairs::Add

Adds an IX509NameValuePair object to the collection.

IX509NameValuePairs::Clear

Removes all IX509NameValuePair objects from the collection.

IX509NameValuePairs::get__NewEnum

Retrieves the enumerator for the collection.

IX509NameValuePairs::get_Count

Retrieves the number of IX509NameValuePair objects in the collection.

IX509NameValuePairs::get_ItemByIndex

Retrieves an IX509NameValuePair object from the collection by index number.

IX509NameValuePairs::Remove

Removes an IX509NameValuePair object from the collection by index number.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

 Header certenroll.h

See also
CertEnroll Interfaces
IDispatch
IX509NameValuePair
 IX509NameValuePairs::Add method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Add method adds an IX509NameValuePair object to the collection.

Syntax
HRESULT Add(
[in] IX509NameValuePair *pVal
);

Parameters
[in] pVal

A pointer to an IX509NameValuePair interface that represents the name-value pair to add.

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509NameValuePair
IX509NameValuePairs
 IX509NameValuePairs::Clear method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Clear method removes all IX509NameValuePair objects from the collection.

Syntax
HRESULT Clear();

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509NameValuePair
IX509NameValuePairs
 IX509NameValuePairs::get__NewEnum method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The _NewEnum property retrieves the enumerator for the collection.

This property is read-only.

Syntax
HRESULT get__NewEnum(
LPUNKNOWN *pVal
);

Parameters
pVal

Return value
None

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509NameValuePair
IX509NameValuePairs
 IX509NameValuePairs::get_Count method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Count property retrieves the number of IX509NameValuePair objects in the collection.
This property is read-only.

Syntax
HRESULT get_Count(
long *pVal
);

Parameters
pVal

Return value
None

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509NameValuePair
IX509NameValuePairs
 IX509NameValuePairs::Remove method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Remove method removes an IX509NameValuePair object from the collection by index number.

Syntax
HRESULT Remove(
[in] LONG Index
);

Parameters
[in] Index

A LONG variable that contains the index of the object to remove.

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509NameValuePair
IX509NameValuePairs
 IX509PolicyServerListManager interface
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The IX509PolicySer verListManager interface defines the following methods and properties that enable you
to manage a collection of IX509PolicyServerUrl objects.

Inheritance
The IX509PolicySer verListManager interface inherits from the IDispatch interface.
IX509PolicySer verListManager also has these types of members:

Methods
The IX509PolicySer verListManager interface has these methods.

IX509PolicyServerListManager::Add

Adds an IX509PolicyServerUrl object to the collection.

IX509PolicyServerListManager::Clear

Removes all IX509PolicyServerUrl objects from the collection.

IX509PolicyServerListManager::get__NewEnum

Retrieves the enumerator for the collection.

IX509PolicyServerListManager::get_Count

Retrieves the number of IX509PolicyServerUrl objects in the collection.

IX509PolicyServerListManager::get_ItemByIndex

Retrieves an IX509PolicyServerUrl object from the collection by index number.

IX509PolicyServerListManager::Initialize

Initializes an IX509PolicyServerListManager object.

IX509PolicyServerListManager::Remove

Removes an IX509PolicyServerUrl object from the collection by index number.

Requirements
Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h
 IX509PolicyServerListManager::Add method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Add method adds an IX509PolicyServerUrl object to the collection.

Syntax
HRESULT Add(
[in] IX509PolicyServerUrl *pVal
);

Parameters
[in] pVal

Pointer to the IX509PolicyServerUrl object to add.

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509PolicyServerListManager
 IX509PolicyServerListManager::Clear method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Clear method removes all IX509PolicyServerUrl objects from the collection.

Syntax
HRESULT Clear();

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509PolicyServerListManager
 IX509PolicyServerListManager::get__NewEnum
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The _NewEnum property retrieves the enumerator for the collection.

This property is read-only.

Syntax
HRESULT get__NewEnum(
LPUNKNOWN *pVal
);

Parameters
pVal

Return value
None

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509PolicyServerListManager
 IX509PolicyServerListManager::get_Count method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Count property retrieves the number of IX509PolicyServerUrl objects in the collection.
This property is read-only.

Syntax
HRESULT get_Count(
long *pVal
);

Parameters
pVal

Return value
None

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509PolicyServerListManager
 IX509PolicyServerListManager::Initialize method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Initialize method initializes an IX509PolicyServerListManager object.

Syntax
HRESULT Initialize(
[in] X509CertificateEnrollmentContext context,
[in] PolicyServerUrlFlags Flags
);

Parameters
[in] context

An X509CertificateEnrollmentContext enumeration value that specifies the nature of the end entity for which an
issued certificate is intended. This can be one of the following values.

VA L UE M EA N IN G

The certificate is intended for an end user.

ContextUser

The certificate is intended for a computer.

ContextMachine

The certificate is being requested by an administrator acting

ContextAdministratorForceMachine on the behalf of a computer.

[in] Flags

A PolicyServerUrlFlags enumeration value that specifies where policy information is located. This can be a
bitwise OR of the following values.

VA L UE M EA N IN G

Policy information is specified in group policy by an

PsfLocationGroupPolicy administrator.

Policy information is specified in the registry.

PsfLocationRegistr y

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. Possible values include, but are not
limited to, those in the following table. For a list of common error codes, see Common HRESULT Values.

RET URN C O DE DESC RIP T IO N

The Flags parameter must contain a bitwise OR of

E_INVALIDARG PsfLocationGroupPolicy and PsfLocationRegistr y .

The IX509PolicyServerListManager has already been

HRESULT_FROM_WIN32(ERROR_ALREADY_INITIALIZE initialized.
D)

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509PolicyServerListManager
 IX509PolicyServerListManager::Remove method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Remove method removes an IX509PolicyServerUrl object from the collection by index number.

Syntax
HRESULT Remove(
[in] LONG Index
);

Parameters
[in] Index

A LONG variable that contains the index of the object to remove.

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509PolicyServerListManager
 IX509PolicyServerUrl interface (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The IX509PolicySer verUrl interface can be used to set or retrieve property values associated with the
certificate enrollment policy (CEP) server and to update associated registry values.

Inheritance
The IX509PolicySer verUrl interface inherits from the IDispatch interface. IX509PolicySer verUrl also has
these types of members:

Methods
The IX509PolicySer verUrl interface has these methods.

IX509PolicyServerUrl::get_AuthFlags

Specifies and retrieves a value that indicates the authentication type used by the client to authenticate itself to the certificate
enrollment policy (CEP) server.

IX509PolicyServerUrl::get_Cost

Specifies and retrieves an arbitrary cost for contacting the certificate enrollment policy server.

IX509PolicyServerUrl::get_Default

Specifies and retrieves a Boolean value that indicates whether this is the default certificate enrollment policy (CEP) server.

IX509PolicyServerUrl::get_Flags

Specifies or retrieves a value that indicates whether the certificate enrollment policy (CEP) server policy information can be
loaded from group policy, from the registry, or both.

IX509PolicyServerUrl::get_Url

Specifies or retrieves the URL for the certificate enrollment policy (CEP) server.

IX509PolicyServerUrl::GetStringProperty

Retrieves the certificate enrollment policy (CEP) server ID or the display name of the CEP server.

IX509PolicyServerUrl::Initialize

Initializes an IX509PolicyServerUrl object for a computer or user context.

IX509PolicyServerUrl::put_AuthFlags

Specifies and retrieves a value that indicates the authentication type used by the client to authenticate itself to the certificate
enrollment policy (CEP) server.
 IX509PolicyServerUrl::put_Cost

Specifies and retrieves an arbitrary cost for contacting the certificate enrollment policy server.

IX509PolicyServerUrl::put_Default

Specifies and retrieves a Boolean value that indicates whether this is the default certificate enrollment policy (CEP) server.

IX509PolicyServerUrl::put_Flags

Specifies or retrieves a value that indicates whether the certificate enrollment policy (CEP) server policy information can be
loaded from group policy, from the registry, or both.

IX509PolicyServerUrl::put_Url

Specifies or retrieves the URL for the certificate enrollment policy (CEP) server.

IX509PolicyServerUrl::RemoveFromRegistry

Unregisters a certificate enrollment policy (CEP) server.

IX509PolicyServerUrl::SetStringProperty

Specifies the certificate enrollment policy (CEP) server ID or the display name of the CEP server.

IX509PolicyServerUrl::UpdateRegistry

Registers a certificate enrollment policy (CEP) server.

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Target Platform Windows

Header certenroll.h
 IX509PolicyServerUrl::get_AuthFlags method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The AuthFlags property specifies and retrieves a value that indicates the authentication type used by the client
to authenticate itself to the certificate enrollment policy (CEP) server.
This property is read/write.

Syntax
HRESULT get_AuthFlags(
X509EnrollmentAuthFlags *pValue
);

Parameters
pValue

Return value
None

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Target Platform Windows

Header certenroll.h

See also
IX509PolicyServerUrl
 IX509PolicyServerUrl::get_Cost method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Cost property specifies and retrieves an arbitrary cost for contacting the certificate enrollment policy
server.
This property is read/write.

Syntax
HRESULT get_Cost(
DWORD *pValue
);

Parameters
pValue

Return value
None

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Target Platform Windows

Header certenroll.h

See also
IX509PolicyServerUrl
 IX509PolicyServerUrl::get_Default method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Default property specifies and retrieves a Boolean value that indicates whether this is the default certificate
enrollment policy (CEP) server.
This property is read/write.

Syntax
HRESULT get_Default(
VARIANT_BOOL *pValue
);

Parameters
pValue

Return value
None

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Target Platform Windows

Header certenroll.h

See also
IX509PolicyServerUrl
 IX509PolicyServerUrl::get_Flags method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Flags property specifies or retrieves a value that indicates whether the certificate enrollment policy (CEP)
server policy information can be loaded from group policy, from the registry, or both.
This property is read/write.

Syntax
HRESULT get_Flags(
PolicyServerUrlFlags *pValue
);

Parameters
pValue

Return value
None

Remarks
When the PsfLocationGroupPolicy and PsfLocationRegistry flags are combined, this method reads policy
information from the local registry and combines it with policy information specified by group policy.

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Target Platform Windows

Header certenroll.h

See also
IX509PolicyServerUrl
 IX509PolicyServerUrl::get_Url method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Url property specifies or retrieves the URL for the certificate enrollment policy (CEP) server.
This property is read/write.

Syntax
HRESULT get_Url(
BSTR *ppValue
);

Parameters
ppValue

Return value
None

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Target Platform Windows

Header certenroll.h

See also
IX509PolicyServerUrl
 IX509PolicyServerUrl::GetStringProperty method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The GetStringProper ty method retrieves the certificate enrollment policy (CEP) server ID or the display name
of the CEP server.

Syntax
HRESULT GetStringProperty(
[in] PolicyServerUrlPropertyID propertyId,
[out, retval] BSTR *ppValue
);

Parameters
[in] propertyId

A PolicyServerUrlPropertyID value that specifies the string to retrieve. This can be one of the following values.

VA L UE M EA N IN G

Retrieve an ID string for the policy server.

PsPolicyID

Retrieve a display name for the policy server.

PsFriendlyName

[out, retval] ppValue

Pointer to a BSTR variable that receives the property value.

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. Possible values include, but are not
limited to, those in the following table. For a list of common error codes, see Common HRESULT Values.

RET URN C O DE DESC RIP T IO N

The property value cannot be found.

CERTSRV_E_PROPERTY_EMPTY

The propertyId parameter cannot be NULL .

E_POINTER

Memory could not be allocated for the return value.

E_OUTOFMEMORY
Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Target Platform Windows

Header certenroll.h

See also
IX509PolicyServerUrl
 IX509PolicyServerUrl::Initialize method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Initialize method initializes an IX509PolicyServerUrl object for a computer or user context.

Syntax
HRESULT Initialize(
[in] X509CertificateEnrollmentContext context
);

Parameters
[in] context

An X509CertificateEnrollmentContext enumeration value that specifies the nature of the end entity for which an
issued certificate is intended. This can be one of the following values.

VA L UE M EA N IN G

The certificate is intended for an end user.

ContextUser

The certificate is intended for a computer.

ContextMachine

The certificate is being requested by an administrator acting

ContextAdministratorForceMachine on the behalf of a computer.

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. Possible values include, but are not
limited to, those in the following table. For a list of common error codes, see Common HRESULT Values.

RET URN C O DE DESC RIP T IO N

The IX509PolicyServerUrl has already been initialized.

HRESULT_FROM_WIN32(ERROR_ALREADY_INITIALIZE
D)

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

 Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Target Platform Windows

Header certenroll.h

See also
IX509PolicyServerUrl
 IX509PolicyServerUrl::put_AuthFlags method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The AuthFlags property specifies and retrieves a value that indicates the authentication type used by the client
to authenticate itself to the certificate enrollment policy (CEP) server.
This property is read/write.

Syntax
HRESULT put_AuthFlags(
X509EnrollmentAuthFlags Flags
);

Parameters
Flags

Return value
None

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Target Platform Windows

Header certenroll.h

See also
IX509PolicyServerUrl
 IX509PolicyServerUrl::put_Cost method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Cost property specifies and retrieves an arbitrary cost for contacting the certificate enrollment policy
server.
This property is read/write.

Syntax
HRESULT put_Cost(
DWORD value
);

Parameters
value

Return value
None

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Target Platform Windows

Header certenroll.h

See also
IX509PolicyServerUrl
 IX509PolicyServerUrl::put_Default method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Default property specifies and retrieves a Boolean value that indicates whether this is the default certificate
enrollment policy (CEP) server.
This property is read/write.

Syntax
HRESULT put_Default(
VARIANT_BOOL value
);

Parameters
value

Return value
None

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Target Platform Windows

Header certenroll.h

See also
IX509PolicyServerUrl
 IX509PolicyServerUrl::put_Flags method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Flags property specifies or retrieves a value that indicates whether the certificate enrollment policy (CEP)
server policy information can be loaded from group policy, from the registry, or both.
This property is read/write.

Syntax
HRESULT put_Flags(
PolicyServerUrlFlags Flags
);

Parameters
Flags

Return value
None

Remarks
When the PsfLocationGroupPolicy and PsfLocationRegistry flags are combined, this method reads policy
information from the local registry and combines it with policy information specified by group policy.

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Target Platform Windows

Header certenroll.h

See also
IX509PolicyServerUrl
 IX509PolicyServerUrl::put_Url method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Url property specifies or retrieves the URL for the certificate enrollment policy (CEP) server.
This property is read/write.

Syntax
HRESULT put_Url(
BSTR pValue
);

Parameters
pValue

Return value
None

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Target Platform Windows

Header certenroll.h

See also
IX509PolicyServerUrl
 IX509PolicyServerUrl::RemoveFromRegistry method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The RemoveFromRegistr y method unregisters a certificate enrollment policy (CEP) server.

Syntax
HRESULT RemoveFromRegistry(
[in] X509CertificateEnrollmentContext context
);

Parameters
[in] context

An X509CertificateEnrollmentContext enumeration value that specifies the nature of the end entity. This can be
one of the following values.

VA L UE M EA N IN G

An end user.
ContextUser

A computer.
ContextMachine

An administrator acting on the behalf of a computer.

ContextAdministratorForceMachine

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. Possible values include, but are not
limited to, those in the following table. For a list of common error codes, see Common HRESULT Values.

RET URN C O DE DESC RIP T IO N

You do not have sufficient access rights to unregister the

HRESULT_FROM_WIN32(ERROR_ACCESS_DISABLED_B CEP.
Y_POLICY)

Requirements
 Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Target Platform Windows

Header certenroll.h

See also
IX509PolicyServerUrl
 IX509PolicyServerUrl::SetStringProperty method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The SetStringProper ty method specifies the certificate enrollment policy (CEP) server ID or the display name
of the CEP server.

Syntax
HRESULT SetStringProperty(
[in] PolicyServerUrlPropertyID propertyId,
[in] BSTR pValue
);

Parameters
[in] propertyId

A PolicyServerUrlPropertyID value that specifies the string to set. This can be one of the following values.

VA L UE M EA N IN G

Set an ID string for the policy server. The string can be any
PsPolicyID value, but it should be unique.

Set a display name for the policy server.

PsFriendlyName

[in] pValue

A BSTR variable that receives the property value.

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. Possible values include, but are not
limited to, those in the following table. For a list of common error codes, see Common HRESULT Values.

RET URN C O DE DESC RIP T IO N

The pValue parameter cannot be NULL or empty.

E_INVALIDARG

Memory could not be allocated for the property value.

E_OUTOFMEMORY

Requirements
 Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Target Platform Windows

Header certenroll.h

See also
IX509PolicyServerUrl
 IX509PolicyServerUrl::UpdateRegistry method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The UpdateRegistr y method registers a certificate enrollment policy (CEP) server.

Syntax
HRESULT UpdateRegistry(
[in] X509CertificateEnrollmentContext context
);

Parameters
[in] context

An X509CertificateEnrollmentContext enumeration value that specifies the nature of the end entity for which the
policy server is being registered. This can be one of the following values.

VA L UE M EA N IN G

An end user.
ContextUser

A computer.
ContextMachine

An administrator acting on the behalf of a computer.

ContextAdministratorForceMachine

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. Possible values include, but are not
limited to, those in the following table. For a list of common error codes, see Common HRESULT Values.

RET URN C O DE DESC RIP T IO N

The URL of the policy server is empty.

E_INVALIDARG

You do not have sufficient access rights to register the CEP.

HRESULT_FROM_WIN32(ERROR_ACCESS_DISABLED_B
Y_POLICY)

Remarks
The UpdateRegistr y method is called by the AddPolicyServer method.

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Target Platform Windows

Header certenroll.h

See also
IX509PolicyServerUrl
 IX509PrivateKey interface (certenroll.h)
7/2/2022 • 4 minutes to read • Edit Online

The IX509PrivateKey interface represents an asymmetric private key that can be used for encryption, signing,
and key agreement. Private keys are referenced in the following objects:
ICertPropertyKeyProvInfo
ISignerCertificate
IX509AttributeArchiveKey
IX509CertificateRequestPkcs10

Inheritance
The IX509PrivateKey interface inherits from the IDispatch interface. IX509PrivateKey also has these types of
members:

Methods
The IX509PrivateKey interface has these methods.

IX509PrivateKey::Close

Releases the handle of the cryptographic service provider (CSP) or the handle of the Cryptography API:_Next Generation
(CNG) key storage provider (KSP).

IX509PrivateKey::Create

Creates an asymmetric private key.

IX509PrivateKey::Delete

Releases the handle of the cryptographic service provider (CSP) or the handle of the Cryptography API:_Next Generation
(CNG) key storage provider (KSP) and deletes the key from disk or smart card.

IX509PrivateKey::Export

Copies the private key to a byte array.

IX509PrivateKey::ExportPublicKey

Exports the public key portion of the asymmetric key pair.

IX509PrivateKey::get_Algorithm

Specifies or retrieves an object identifier (OID) for the public key algorithm.

IX509PrivateKey::get_Certificate

Specifies or retrieves a byte array that contains the certificate associated with the private key.
IX509PrivateKey::get_ContainerName

Specifies or retrieves the name of the key container.

IX509PrivateKey::get_ContainerNamePrefix

Specifies or retrieves a prefix added to the name of the key container.

IX509PrivateKey::get_CspInformations

Specifies or retrieves a collection of ICspInformation objects that contain information about the available cryptographic
providers that support the public key algorithm associated with the private key.

IX509PrivateKey::get_CspStatus

Specifies or retrieves an ICspStatus object that contains information about the cryptographic provider and algorithm pair
associated with the private key.

IX509PrivateKey::get_DefaultContainer

Retrieves a Boolean value that specifies whether the private key represents the default key container.

IX509PrivateKey::get_Description

Specifies or retrieves a string that contains a description of the private key.

IX509PrivateKey::get_Existing

Specifies or retrieves a Boolean value that indicates whether the private key has been created or imported.

IX509PrivateKey::get_ExportPolicy

Specifies or retrieves export constraints for a private key.

IX509PrivateKey::get_FriendlyName

Specifies or retrieves a display name for the private key.

IX509PrivateKey::get_KeyProtection

Specifies or retrieves a value that indicates how a private key is protected before use.

IX509PrivateKey::get_KeySpec

Specifies or retrieves a value that identifies whether a private key can be used for signing, or encryption, or both.

IX509PrivateKey::get_KeyUsage

Specifies or retrieves a value that identifies the specific purpose for which a private key can be used.

IX509PrivateKey::get_LegacyCsp

Specifies or retrieves a Boolean value that indicates whether the provider is a CryptoAPI (legacy) cryptographic service
provider (CSP).
IX509PrivateKey::get_Length

Specifies or retrieves the length, in bits, of the private key.

IX509PrivateKey::get_MachineContext

Specifies or retrieves a Boolean value that identifies the local certificate store context.

IX509PrivateKey::get_Opened

Retrieves a Boolean value that specifies whether the private key is open.

IX509PrivateKey::get_ParentWindow

Specifies or retrieves the ID of the window used to display key information.

IX509PrivateKey::get_ProviderName

Specifies or retrieves the name of the cryptographic provider.

IX509PrivateKey::get_ProviderType

Specifies or retrieves the type of cryptographic provider associated with the private key.

IX509PrivateKey::get_ReaderName

Specifies or retrieves the name of a smart card reader.

IX509PrivateKey::get_SecurityDescriptor

Specifies or retrieves the security descriptor for the private key.

IX509PrivateKey::get_Silent

Specifies or retrieves a Boolean value that indicates whether the Certificate Enrollment Control is allowed to display a dialog
box when the private key is accessed.

IX509PrivateKey::get_UIContextMessage

Specifies or retrieves a string that contains user interface text associated with the private key.

IX509PrivateKey::get_UniqueContainerName

Retrieves a unique name for the key container.

IX509PrivateKey::Import

Imports an existing private key into a key container within a cryptographic provider.

IX509PrivateKey::Open

Opens an existing private key.

IX509PrivateKey::put_Algorithm

Specifies or retrieves an object identifier (OID) for the public key algorithm.

IX509PrivateKey::put_Certificate

Specifies or retrieves a byte array that contains the certificate associated with the private key.

IX509PrivateKey::put_ContainerName

Specifies or retrieves the name of the key container.

IX509PrivateKey::put_ContainerNamePrefix

Specifies or retrieves a prefix added to the name of the key container.

IX509PrivateKey::put_CspInformations

Specifies or retrieves a collection of ICspInformation objects that contain information about the available cryptographic
providers that support the public key algorithm associated with the private key.

IX509PrivateKey::put_CspStatus

Specifies or retrieves an ICspStatus object that contains information about the cryptographic provider and algorithm pair
associated with the private key.

IX509PrivateKey::put_Description

Specifies or retrieves a string that contains a description of the private key.

IX509PrivateKey::put_Existing

Specifies or retrieves a Boolean value that indicates whether the private key has been created or imported.

IX509PrivateKey::put_ExportPolicy

Specifies or retrieves export constraints for a private key.

IX509PrivateKey::put_FriendlyName

Specifies or retrieves a display name for the private key.

IX509PrivateKey::put_KeyProtection

Specifies or retrieves a value that indicates how a private key is protected before use.

IX509PrivateKey::put_KeySpec

Specifies or retrieves a value that identifies whether a private key can be used for signing, or encryption, or both.

IX509PrivateKey::put_KeyUsage

Specifies or retrieves a value that identifies the specific purpose for which a private key can be used.
 IX509PrivateKey::put_LegacyCsp

Specifies or retrieves a Boolean value that indicates whether the provider is a CryptoAPI (legacy) cryptographic service
provider (CSP).

IX509PrivateKey::put_Length

Specifies or retrieves the length, in bits, of the private key.

IX509PrivateKey::put_MachineContext

Specifies or retrieves a Boolean value that identifies the local certificate store context.

IX509PrivateKey::put_ParentWindow

Specifies or retrieves the ID of the window used to display key information.

IX509PrivateKey::put_Pin

Specifies a personal identification number (PIN) that is used to authenticate users prior to accessing a private key container on
a smart card.

IX509PrivateKey::put_ProviderName

Specifies or retrieves the name of the cryptographic provider.

IX509PrivateKey::put_ProviderType

Specifies or retrieves the type of cryptographic provider associated with the private key.

IX509PrivateKey::put_ReaderName

Specifies or retrieves the name of a smart card reader.

IX509PrivateKey::put_SecurityDescriptor

Specifies or retrieves the security descriptor for the private key.

IX509PrivateKey::put_Silent

Specifies or retrieves a Boolean value that indicates whether the Certificate Enrollment Control is allowed to display a dialog
box when the private key is accessed.

IX509PrivateKey::put_UIContextMessage

Specifies or retrieves a string that contains user interface text associated with the private key.

IX509PrivateKey::Verify

Verifies that a private key exists and can be used by the client but does not open the key.

Requirements
 Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

See also
CertEnroll Interfaces
IDispatch
IX509PublicKey
 IX509PrivateKey::Close method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Close method releases the handle of the cryptographic service provider (CSP) or the handle of the
Cryptography API: Next Generation (CNG) key storage provider (KSP).

Syntax
HRESULT Close();

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.

Remarks
This method does not delete the key from storage or the IX509PrivateKey instance. For more information, see
the Delete method.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509PrivateKey
 IX509PrivateKey::Create method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Create method creates an asymmetric private key.

Syntax
HRESULT Create();

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. Possible values include, but are not
limited to, those in the following table. For a list of common error codes, see Common HRESULT Values.

RET URN C O DE/ VA L UE DESC RIP T IO N

The CSP handle is not NULL .

HRESULT_FROM_WIN32(ERROR_BUSY)

The key already exists.

HRESULT_FROM_WIN32(ERROR_FILE_EXISTS)

Remarks
If you do not set the CspStatus, the ProviderName, or ProviderType properties, this method uses the default
provider, key size, and KeySpec values when creating the key. On a new operating system installation, for
example, Microsoft Enhanced Cryptographic Provider v1.0 is the default provider.
If you do not set the ContainerName property, this method automatically generates a name. The generated
name includes a GUID and, if the ContainerNamePrefix property is not set, a prefix of "lp-". If the provider is a
smart card provider, the generated name will not exceed the MaxKeyContainerNameLength value specified by
the provider. If the generated name initially exceeds this value, it is truncated to forty characters.
You cannot set the following properties after calling the Create or Open methods. If you wish to specify them,
you must do so before calling either of these methods.
Algorithm
ContainerName
ContainerNamePrefix
CspInformations
CspStatus
Description
Existing
ExportPolicy
FriendlyName
KeyProtection
 KeySpec
KeyUsage
LegacyCsp
Length
MachineContext
ProviderName
ProviderType
Pin
ReaderName
Silent
UIContextMessage

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509PrivateKey
 IX509PrivateKey::Delete method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Delete method releases the handle of the cryptographic service provider (CSP) or the handle of the
Cryptography API: Next Generation (CNG) key storage provider (KSP) and deletes the key from disk or smart
card.

Syntax
HRESULT Delete();

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. Possible values include, but are not
limited to, those in the following table. For a list of common error codes, see Common HRESULT Values.

RET URN C O DE/ VA L UE DESC RIP T IO N

The CSP could not be found.

CERTSRV_E_PROPERTY_EMPTY

Remarks
Call the Close method if you only want to close the provider handles. The Delete method does not delete the
IX509PrivateKey instance.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509PrivateKey
 IX509PrivateKey::Export method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Expor t method copies the private key to a byte array. The byte array is represented by a Unicode-encoded
string.

Syntax
HRESULT Export(
[in] BSTR strExportType,
[in] EncodingType Encoding,
[out] BSTR *pstrEncodedKey
);

Parameters
[in] strExportType

A BSTR value that specifies how the private key is exported.

If the key was created by using a CNG KSP (Key Storage Provider), you can specify one of the values allowed by
the pszBlobType parameter in the NCryptExportKey function.
If the key was created by using a CryptoAPI CSP (Cryptographic Service Provider), you can specify one of the
following values from the Bcrypt.h header file included with Wincrypt.h.

VA L UE M EA N IN G

Exports only the public portion of the private key.

BCRYPT_PUBLIC_KEY_BLOB

Exports the entire private key.

BCRYPT_PRIVATE_KEY_BLOB

[in] Encoding

An EncodingType enumeration value that specifies the type of Unicode encoding to be applied to the string
contained in the pstrEncodedKey parameter. The default value is XCN_CRYPT_STRING_BASE64.
[out] pstrEncodedKey

Pointer to a BSTR variable that contains the private key.

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. Possible values include, but are not
limited to, those in the following table. For a list of common error codes, see Common HRESULT Values.

RET URN C O DE DESC RIP T IO N

 The key was created by a CryptoAPI CSP and you specified a
HRESULT_FROM_WIN32(ERROR_CALL_NOT_IMPLEME value other than BCRYPT_PRIVATE_KEY_BLOB or
NTED) BCRYPT_PUBLIC_KEY_BLOB for the strExportType parameter.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509PrivateKey
 IX509PrivateKey::ExportPublicKey method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Expor tPublicKey method exports the public key portion of the asymmetric key pair.

Syntax
HRESULT ExportPublicKey(
[out] IX509PublicKey **ppPublicKey
);

Parameters
[out] ppPublicKey

Address of a variable that receives a pointer to an IX509PublicKey interface that represents the key.

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.

Remarks
You must call Open or Create to open the private key before calling this method.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509PrivateKey
 IX509PrivateKey::get_Algorithm method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Algorithm property specifies or retrieves an object identifier (OID) for the public key algorithm. This
property is web enabled for both input and output.
This property is read/write.

Syntax
HRESULT get_Algorithm(
IObjectId **ppValue
);

Parameters
ppValue

Return value
None

Remarks
This property is automatically set when the CspStatus property is called.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509PrivateKey
 IX509PrivateKey::get_Certificate method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Cer tificate property specifies or retrieves a byte array that contains the certificate associated with the
private key. The byte array is represented by a Unicode-encoded string.
This property is read/write.

Syntax
HRESULT get_Certificate(
EncodingType Encoding,
BSTR *pValue
);

Parameters
Encoding

pValue

Return value
None

Remarks
If the key is not open when you specify a certificate, the certificate will be set when the key is opened. For more
information, see the Open method.
The Cer tificate property compares the public key associated with the IX509PrivateKey object to the public key
included in the certificate. The two keys must match.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll
See also
IX509PrivateKey
 IX509PrivateKey::get_ContainerName method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The ContainerName property specifies or retrieves the name of the key container. This property is web
enabled for both input and output.
This property is read/write.

Syntax
HRESULT get_ContainerName(
BSTR *pValue
);

Parameters
pValue

Return value
None

Remarks
If you do not specify a name, one is created when the Create method is called.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509PrivateKey
 IX509PrivateKey::get_ContainerNamePrefix method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The ContainerNamePrefix property specifies or retrieves a prefix added to the name of the key container.
This property is read/write.

Syntax
HRESULT get_ContainerNamePrefix(
BSTR *pValue
);

Parameters
pValue

Return value
None

Remarks
A prefix can contain any string limited to the maximum length of the key container name and to legal container
name characters. For example, if you do not call the ContainerName property to specify a key container name,
one is automatically created when the Create method is called, and the prefix to the container name will be the
string "lp". For another example, if you are creating a test harness and want to differentiate key containers by the
programs that generated them, you can use the name of the executable as the prefix.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509PrivateKey
 IX509PrivateKey::get_CspInformations method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The CspInformations property specifies or retrieves a collection of ICspInformation objects that contain
information about the available cryptographic providers that support the public key algorithm associated with
the private key. This property is web enabled for both input and output.
This property is read/write.

Syntax
HRESULT get_CspInformations(
ICspInformations **ppValue
);

Parameters
ppValue

Return value
None

Remarks
The enrollment process expects the ICspInformations collection to include all providers installed on the client
computer. You should therefore not attempt to set this property to a subset of the installed providers. We
recommend that you create an empty collection and call AddAvailableCsps to populate it. Build this collection
once and set it on all top level request objects (or the private key if you are using the IX509PrivateKey object
directly) to avoid the cost of creating multiple collections. An ICspInformations collection is large.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509PrivateKey
 IX509PrivateKey::get_CspStatus method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The CspStatus property specifies or retrieves an ICspStatus object that contains information about the
cryptographic provider and algorithm pair associated with the private key. This property is web enabled for both
input and output.
This property is read/write.

Syntax
HRESULT get_CspStatus(
ICspStatus **ppValue
);

Parameters
ppValue

Return value
None

Remarks
The Algorithm and ProviderName properties are automatically set when you call the CspStatus property. The
CspStatus property is typically set during the enrollment process. That is, when a request template specifies
multiple provider/algorithm pairs, the enrollment code sets the CspStatus property to the first enabled
ICspStatus object and tries to create a private key. If a key cannot be created, the enrollment code sets this
property to the next enabled ICspStatus object and tries again.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509PrivateKey
 IX509PrivateKey::get_DefaultContainer method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The DefaultContainer property retrieves a Boolean value that specifies whether the private key represents the
default key container.
This property is read-only.

Syntax
HRESULT get_DefaultContainer(
VARIANT_BOOL *pValue
);

Parameters
pValue

Return value
None

Remarks
Key containers are identified by name. The name can be specified by the client, or it can be a default value
supported by the CSP or KSP. For example, some CSPs use the logon name of the current user as the default
container name.
This property value is set when the Open or Create methods are called.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509PrivateKey
 IX509PrivateKey::get_Description method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Description property specifies or retrieves a string that contains a description of the private key.
This property is read/write.

Syntax
HRESULT get_Description(
BSTR *pValue
);

Parameters
pValue

Return value
None

Remarks
This property can contain any text and is intended to be displayed in a user interface to identify the nature and
uses of the private key.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509PrivateKey
 IX509PrivateKey::get_Existing method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Existing property specifies or retrieves a Boolean value that indicates whether the private key has been
created or imported. This property is web enabled for both input and output.
This property is read/write.

Syntax
HRESULT get_Existing(
VARIANT_BOOL *pValue
);

Parameters
pValue

Return value
None

Remarks
Call the Create method to create a new private key. Call the Open method to open an existing key.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509PrivateKey
 IX509PrivateKey::get_ExportPolicy method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Expor tPolicy property specifies or retrieves export constraints for a private key. This property is web
enabled for both input and output.
This property is read/write.

Syntax
HRESULT get_ExportPolicy(
X509PrivateKeyExportFlags *pValue
);

Parameters
pValue

Return value
None

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509PrivateKey
 IX509PrivateKey::get_FriendlyName method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The FriendlyName property specifies or retrieves a display name for the private key.
This property is read/write.

Syntax
HRESULT get_FriendlyName(
BSTR *pValue
);

Parameters
pValue

Return value
None

Remarks
This property can contain any text and is intended to be displayed in a user interface to identify the private key.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509PrivateKey
 IX509PrivateKey::get_KeyProtection method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The KeyProtection property specifies or retrieves a value that indicates how a private key is protected before
use. This property is web enabled for both input and output.
This property is read/write.

Syntax
HRESULT get_KeyProtection(
X509PrivateKeyProtection *pValue
);

Parameters
pValue

Return value
None

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509PrivateKey
 IX509PrivateKey::get_KeySpec method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The KeySpec property specifies or retrieves a value that identifies whether a private key can be used for
signing, or encryption, or both. This property is web enabled for both input and output.
This property is read/write.

Syntax
HRESULT get_KeySpec(
X509KeySpec *pValue
);

Parameters
pValue

Return value
None

Remarks
If you specify a value of XCN_AT_SIGNATURE, the KeySpec property automatically sets the KeyUsage property
to XCN_NCRYPT_ALLOW_SIGNING_FLAG. If you specify XCN_AT_KEYEXCHANGE, the KeyUsage property is set
to XCN_NCRYPT_ALLOW_DECRYPT_FLAG | XCN_NCRYPT_ALLOW_KEY_AGREEMENT_FLAG. The KeySpec
property only applies to [legacy] providers created by using CryptoAPI.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509PrivateKey
 IX509PrivateKey::get_KeyUsage method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The KeyUsage property specifies or retrieves a value that identifies the specific purpose for which a private key
can be used. This property is web enabled for both input and output.
This property is read/write.

Syntax
HRESULT get_KeyUsage(
X509PrivateKeyUsageFlags *pValue
);

Parameters
pValue

Return value
None

Remarks
If you set the KeySpec property for a legacy CSP to XCN_NCRYPT_ALLOW_SIGNING_FLAG, the KeyUsage
property to XCN_NCRYPT_ALLOW_SIGNING_FLAG. If you specify XCN_AT_KEYEXCHANGE, the KeyUsage
property is automatically set to XCN_NCRYPT_ALLOW_DECRYPT_FLAG |
XCN_NCRYPT_ALLOW_KEY_AGREEMENT_FLAG.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509PrivateKey
 IX509PrivateKey::get_LegacyCsp method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The LegacyCsp property specifies or retrieves a Boolean value that indicates whether the provider is a
CryptoAPI (legacy) cryptographic service provider (CSP). This property is web enabled for both input and
output.
This property is read/write.

Syntax
HRESULT get_LegacyCsp(
VARIANT_BOOL *pValue
);

Parameters
pValue

Return value
None

Remarks
Setting this property automatically sets the following properties to be consistent with the specified LegacyCsp
value:
KeySpec
ProviderType
These properties are set in the following manner:
If the LegacyCsp property is set to VARIANT_FALSE :
The ProviderType is set to XCN_PROV_NONE .
The KeySpec property is set to XCN_AT_NONE .
If the LegacyCsp property is set to VARIANT_TRUE :
The ProviderType is set to XCN_PROV_RSA_FULL if the current value is XCN_PROV_NONE .
The KeySpec property is set to XCN_AT_SIGNATURE if the current property is XCN_AT_NONE .
Because a previously specified ProviderName is not affected by setting the LegacyCsp property, setting a
LegacyCsp that is inconsistent with the ProviderName property will result in undefined behavior, likely a failure
when creating or opening a private key.

Requirements
 Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509PrivateKey
 IX509PrivateKey::get_Length method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Length property specifies or retrieves the length, in bits, of the private key. This property is web enabled for
both input and output.
This property is read/write.

Syntax
HRESULT get_Length(
LONG *pValue
);

Parameters
pValue

Return value
None

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509PrivateKey
 IX509PrivateKey::get_MachineContext method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The MachineContext property specifies or retrieves a Boolean value that identifies the local certificate store
context. This property is web enabled for both input and output.
This property is read/write.

Syntax
HRESULT get_MachineContext(
VARIANT_BOOL *pValue
);

Parameters
pValue

Return value
None

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509PrivateKey
 IX509PrivateKey::get_Opened method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Opened property retrieves a Boolean value that specifies whether the private key is open.
This property is read-only.

Syntax
HRESULT get_Opened(
VARIANT_BOOL *pValue
);

Parameters
pValue

Return value
None

Remarks
You can call the Create method to create a private key, and call the Open method to open one.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509PrivateKey
 IX509PrivateKey::get_ParentWindow method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The ParentWindow property specifies or retrieves the ID of the window used to display key information.
This property is read/write.

Syntax
HRESULT get_ParentWindow(
LONG *pValue
);

Parameters
pValue

Return value
None

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509PrivateKey
 IX509PrivateKey::get_ProviderName method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The ProviderName property specifies or retrieves the name of the cryptographic provider. This property is
web enabled for both input and output.
This property is read/write.

Syntax
HRESULT get_ProviderName(
BSTR *pValue
);

Parameters
pValue

Return value
None

Remarks
Setting this property automatically sets the following properties to be consistent with the specified
ProviderName value:
KeySpec
LegacyCsp
ProviderType
These properties are set in the following manner:
The provider configuration data is used, if available, to determine the appropriate ProviderType value.
If the specified provider is a CNG KSP:
The LegacyCsp property is set to VARIANT_FALSE .
The KeySpec property is set to XCN_AT_NONE .
If the specified provider is not a CNG KSP:
The LegacyCsp property is set to VARIANT_TRUE .
The KeySpec property is set to XCN_AT_SIGNATURE .
If you set the ProviderName property, we recommend that you do not set the LegacyCsp or ProviderType
properties.

Requirements
 Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509PrivateKey
 IX509PrivateKey::get_ProviderType method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The ProviderType property specifies or retrieves the type of cryptographic provider associated with the private
key. This property is web enabled for both input and output.
This property is read/write.

Syntax
HRESULT get_ProviderType(
X509ProviderType *pValue
);

Parameters
pValue

Return value
None

Remarks
You can use this property to force the use of the default provider for a given provider type. For example, to use
the PROV_RSA_SCHANNEL provider, set this property to the
XCN_PROV_RSA_SCHANNEL X509ProviderType enumeration value and do not specify a value for the
ProviderName property.
Setting this property automatically sets the following properties to be consistent with the specified
ProviderType value:
KeySpec
LegacyCsp
These properties are set in the following manner:
If the ProviderType is set to XCN_PROV_NONE :
The LegacyCsp property is set to VARIANT_FALSE .
The KeySpec property is set to XCN_AT_NONE .
If the ProviderType is not set to XCN_PROV_NONE :
The LegacyCsp property is set to VARIANT_TRUE .
The KeySpec property is set to XCN_AT_SIGNATURE if the current value is XCN_AT_NONE .
Because a previously specified ProviderName is not affected by setting the ProviderType property, setting a
ProviderType that is inconsistent with the ProviderName property will result in undefined behavior, likely a
failure when creating or opening a private key. We recommend that you set the ProviderType property only when
attempting to force the use of the default provider for the specified type as discussed above.
Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509PrivateKey
 IX509PrivateKey::get_ReaderName method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The ReaderName property specifies or retrieves the name of a smart card reader.
This property is read/write.

Syntax
HRESULT get_ReaderName(
BSTR *pValue
);

Parameters
pValue

Return value
None

Remarks
If you set this property before opening a key, the reader name is concatenated to the name of the key container.
The format is \.\Reader_Name\Container_Name. Prepending the reader name to the key container name
enables the name to be disambiguated in subsequent calls to a cryptographic provider. The private key is
typically stored in the smart card key container when a smart card is used.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509PrivateKey
 IX509PrivateKey::get_SecurityDescriptor method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The SecurityDescriptor property specifies or retrieves the security descriptor for the private key.
This property is read/write.

Syntax
HRESULT get_SecurityDescriptor(
BSTR *pValue
);

Parameters
pValue

Return value
None

Remarks
To use the security descriptor, you must call the ConvertStringSecurityDescriptorToSecurityDescriptor function
included with the Microsoft Authorization API and specify the string returned by the
GetDefaultSecurityDescriptor method.
The security descriptor is used to define access to private keys for the computer and user in the following
manner:
By default, only local administrators and services running under the LocalSystem account can access private
keys associated with the computer account.
When a CSP stores the private key of a user in an encrypted file in the user profile, it uses a security
descriptor to set access permissions to the file.
If the key is not open when you specify a descriptor, the property value will be set when the key is opened.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h
 DLL CertEnroll.dll

See also
IX509PrivateKey
 IX509PrivateKey::get_Silent method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Silent property specifies or retrieves a Boolean value that indicates whether the Certificate Enrollment
Control is allowed to display a dialog box when the private key is accessed.
This property is read/write.

Syntax
HRESULT get_Silent(
VARIANT_BOOL *pValue
);

Parameters
pValue

Return value
None

Remarks
If the user interface is not allowed but is required to access the private key, operations that require the user
interface will fail.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509PrivateKey
 IX509PrivateKey::get_UIContextMessage method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The UIContextMessage property specifies or retrieves a string that contains user interface text associated with
the private key.
This property is read/write.

Syntax
HRESULT get_UIContextMessage(
BSTR *pValue
);

Parameters
pValue

Return value
None

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509PrivateKey
 IX509PrivateKey::get_UniqueContainerName
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The UniqueContainerName property retrieves a unique name for the key container.
This property is read-only.

Syntax
HRESULT get_UniqueContainerName(
BSTR *pValue
);

Parameters
pValue

Return value
None

Remarks
This property retrieves an alternate name that can be used when accessing a key when you believe that the
ContainerName property value is not unique enough to provide adequate identification. Typically the key
container creates the name. For example, the Cryptography API: Next Generation (CNG) key storage provider
(KSP) returns the name of the encrypted file that contains the key.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509PrivateKey
 IX509PrivateKey::Import method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Impor t method imports an existing private key into a key container within a cryptographic provider.

Syntax
HRESULT Import(
[in] BSTR strExportType,
[in] BSTR strEncodedKey,
[in] EncodingType Encoding
);

Parameters
[in] strExportType

If the key was created by using a CNG KSP (Key Storage Provider), the Impor t method passes this argument to
the pszProperty parameter of the NCryptSetProperty function. That is, the value you specify will be used as the
name of a property to be set on the imported key.
If the key was created by using a CryptoAPI CSP (Cryptographic Service Provider), this argument specifies how
the private key is to be imported. This can be the following value.

VA L UE M EA N IN G

Imports the entire private key.

BCRYPT_PRIVATE_KEY_BLOB

[in] strEncodedKey

A BSTR variable that contains the key to import.

[in] Encoding

An EncodingType enumeration value that specifies the type of Unicode encoding to be applied to the string
contained in the strEncodedKey parameter. The default value is XCN_CRYPT_STRING_BASE64.

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. Possible values include, but are not
limited to, those in the following table. For a list of common error codes, see Common HRESULT Values.

RET URN C O DE DESC RIP T IO N

The key container is already open. You can receive this error
HRESULT_FROM_WIN32(ERROR_FILE_READ_ONLY) if you have already called Open or Create.
 The key was created by a CryptoAPI CSP and you specified a
HRESULT_FROM_WIN32(ERROR_CALL_NOT_IMPLEME value other than BCRYPT_PRIVATE_KEY_BLOB for the
NTED) strExportType parameter.

Remarks
The Impor t function automatically assumes that you are attempting to import a CNG KSP key if you specify a
value other than BCRYPT_PRIVATE_KEY_BLOB for the strExportType parameter and you do not set any of the
following properties:
CspStatus
KeySpec
LegacyCsp
ProviderName
ProviderType

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509PrivateKey
 IX509PrivateKey::Open method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Open method opens an existing private key.

Syntax
HRESULT Open();

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.

Remarks
If successful, this method sets the Opened property. You must call either the Open or Create methods before
calling the Export method or ExportPublicKey method.
You cannot set the following properties after calling the Open or Create methods. If you wish to specify them,
you must do so before calling either of these methods.
Algorithm
ContainerName
ContainerNamePrefix
CspInformations
CspStatus
Description
Existing
ExportPolicy
FriendlyName
KeyProtection
KeySpec
KeyUsage
LegacyCsp
Length
MachineContext
ProviderName
ProviderType
Pin
ReaderName
Silent
UIContextMessage
The following properties can be set regardless of whether the key is open:
 Certificate
ParentWindow
SecurityDescriptor

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509PrivateKey
 IX509PrivateKey::put_Algorithm method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Algorithm property specifies or retrieves an object identifier (OID) for the public key algorithm. This
property is web enabled for both input and output.
This property is read/write.

Syntax
HRESULT put_Algorithm(
IObjectId *pValue
);

Parameters
pValue

Return value
None

Remarks
This property is automatically set when the CspStatus property is called.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509PrivateKey
 IX509PrivateKey::put_Certificate method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Cer tificate property specifies or retrieves a byte array that contains the certificate associated with the
private key. The byte array is represented by a Unicode-encoded string.
This property is read/write.

Syntax
HRESULT put_Certificate(
EncodingType Encoding,
BSTR Value
);

Parameters
Encoding

Value

Return value
None

Remarks
If the key is not open when you specify a certificate, the certificate will be set when the key is opened. For more
information, see the Open method.
The Cer tificate property compares the public key associated with the IX509PrivateKey object to the public key
included in the certificate. The two keys must match.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll
See also
IX509PrivateKey
 IX509PrivateKey::put_ContainerName method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The ContainerName property specifies or retrieves the name of the key container. This property is web
enabled for both input and output.
This property is read/write.

Syntax
HRESULT put_ContainerName(
BSTR Value
);

Parameters
Value

Return value
None

Remarks
If you do not specify a name, one is created when the Create method is called.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509PrivateKey
 IX509PrivateKey::put_ContainerNamePrefix method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The ContainerNamePrefix property specifies or retrieves a prefix added to the name of the key container.
This property is read/write.

Syntax
HRESULT put_ContainerNamePrefix(
BSTR Value
);

Parameters
Value

Return value
None

Remarks
A prefix can contain any string limited to the maximum length of the key container name and to legal container
name characters. For example, if you do not call the ContainerName property to specify a key container name,
one is automatically created when the Create method is called, and the prefix to the container name will be the
string "lp". For another example, if you are creating a test harness and want to differentiate key containers by the
programs that generated them, you can use the name of the executable as the prefix.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509PrivateKey
 IX509PrivateKey::put_CspInformations method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The CspInformations property specifies or retrieves a collection of ICspInformation objects that contain
information about the available cryptographic providers that support the public key algorithm associated with
the private key. This property is web enabled for both input and output.
This property is read/write.

Syntax
HRESULT put_CspInformations(
ICspInformations *pValue
);

Parameters
pValue

Return value
None

Remarks
The enrollment process expects the ICspInformations collection to include all providers installed on the client
computer. You should therefore not attempt to set this property to a subset of the installed providers. We
recommend that you create an empty collection and call AddAvailableCsps to populate it. Build this collection
once and set it on all top level request objects (or the private key if you are using the IX509PrivateKey object
directly) to avoid the cost of creating multiple collections. An ICspInformations collection is large.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509PrivateKey
 IX509PrivateKey::put_CspStatus method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The CspStatus property specifies or retrieves an ICspStatus object that contains information about the
cryptographic provider and algorithm pair associated with the private key. This property is web enabled for both
input and output.
This property is read/write.

Syntax
HRESULT put_CspStatus(
ICspStatus *pValue
);

Parameters
pValue

Return value
None

Remarks
The Algorithm and ProviderName properties are automatically set when you call the CspStatus property. The
CspStatus property is typically set during the enrollment process. That is, when a request template specifies
multiple provider/algorithm pairs, the enrollment code sets the CspStatus property to the first enabled
ICspStatus object and tries to create a private key. If a key cannot be created, the enrollment code sets this
property to the next enabled ICspStatus object and tries again.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509PrivateKey
 IX509PrivateKey::put_Description method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Description property specifies or retrieves a string that contains a description of the private key.
This property is read/write.

Syntax
HRESULT put_Description(
BSTR Value
);

Parameters
Value

Return value
None

Remarks
This property can contain any text and is intended to be displayed in a user interface to identify the nature and
uses of the private key.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509PrivateKey
 IX509PrivateKey::put_Existing method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Existing property specifies or retrieves a Boolean value that indicates whether the private key has been
created or imported. This property is web enabled for both input and output.
This property is read/write.

Syntax
HRESULT put_Existing(
VARIANT_BOOL Value
);

Parameters
Value

Return value
None

Remarks
Call the Create method to create a new private key. Call the Open method to open an existing key.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509PrivateKey
 IX509PrivateKey::put_ExportPolicy method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Expor tPolicy property specifies or retrieves export constraints for a private key. This property is web
enabled for both input and output.
This property is read/write.

Syntax
HRESULT put_ExportPolicy(
X509PrivateKeyExportFlags Value
);

Parameters
Value

Return value
None

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509PrivateKey
 IX509PrivateKey::put_FriendlyName method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The FriendlyName property specifies or retrieves a display name for the private key.
This property is read/write.

Syntax
HRESULT put_FriendlyName(
BSTR Value
);

Parameters
Value

Return value
None

Remarks
This property can contain any text and is intended to be displayed in a user interface to identify the private key.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509PrivateKey
 IX509PrivateKey::put_KeyProtection method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The KeyProtection property specifies or retrieves a value that indicates how a private key is protected before
use. This property is web enabled for both input and output.
This property is read/write.

Syntax
HRESULT put_KeyProtection(
X509PrivateKeyProtection Value
);

Parameters
Value

Return value
None

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509PrivateKey
 IX509PrivateKey::put_KeySpec method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The KeySpec property specifies or retrieves a value that identifies whether a private key can be used for
signing, or encryption, or both. This property is web enabled for both input and output.
This property is read/write.

Syntax
HRESULT put_KeySpec(
X509KeySpec Value
);

Parameters
Value

Return value
None

Remarks
If you specify a value of XCN_AT_SIGNATURE, the KeySpec property automatically sets the KeyUsage property
to XCN_NCRYPT_ALLOW_SIGNING_FLAG. If you specify XCN_AT_KEYEXCHANGE, the KeyUsage property is set
to XCN_NCRYPT_ALLOW_DECRYPT_FLAG | XCN_NCRYPT_ALLOW_KEY_AGREEMENT_FLAG. The KeySpec
property only applies to [legacy] providers created by using CryptoAPI.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509PrivateKey
 IX509PrivateKey::put_KeyUsage method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The KeyUsage property specifies or retrieves a value that identifies the specific purpose for which a private key
can be used. This property is web enabled for both input and output.
This property is read/write.

Syntax
HRESULT put_KeyUsage(
X509PrivateKeyUsageFlags Value
);

Parameters
Value

Return value
None

Remarks
If you set the KeySpec property for a legacy CSP to XCN_NCRYPT_ALLOW_SIGNING_FLAG, the KeyUsage
property to XCN_NCRYPT_ALLOW_SIGNING_FLAG. If you specify XCN_AT_KEYEXCHANGE, the KeyUsage
property is automatically set to XCN_NCRYPT_ALLOW_DECRYPT_FLAG |
XCN_NCRYPT_ALLOW_KEY_AGREEMENT_FLAG.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509PrivateKey
 IX509PrivateKey::put_LegacyCsp method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The LegacyCsp property specifies or retrieves a Boolean value that indicates whether the provider is a
CryptoAPI (legacy) cryptographic service provider (CSP). This property is web enabled for both input and
output.
This property is read/write.

Syntax
HRESULT put_LegacyCsp(
VARIANT_BOOL Value
);

Parameters
Value

Return value
None

Remarks
Setting this property automatically sets the following properties to be consistent with the specified LegacyCsp
value:
KeySpec
ProviderType
These properties are set in the following manner:
If the LegacyCsp property is set to VARIANT_FALSE :
The ProviderType is set to XCN_PROV_NONE .
The KeySpec property is set to XCN_AT_NONE .
If the LegacyCsp property is set to VARIANT_TRUE :
The ProviderType is set to XCN_PROV_RSA_FULL if the current value is XCN_PROV_NONE .
The KeySpec property is set to XCN_AT_SIGNATURE if the current property is XCN_AT_NONE .
Because a previously specified ProviderName is not affected by setting the LegacyCsp property, setting a
LegacyCsp that is inconsistent with the ProviderName property will result in undefined behavior, likely a failure
when creating or opening a private key.

Requirements
 Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509PrivateKey
 IX509PrivateKey::put_Length method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Length property specifies or retrieves the length, in bits, of the private key. This property is web enabled for
both input and output.
This property is read/write.

Syntax
HRESULT put_Length(
LONG Value
);

Parameters
Value

Return value
None

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509PrivateKey
 IX509PrivateKey::put_MachineContext method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The MachineContext property specifies or retrieves a Boolean value that identifies the local certificate store
context. This property is web enabled for both input and output.
This property is read/write.

Syntax
HRESULT put_MachineContext(
VARIANT_BOOL Value
);

Parameters
Value

Return value
None

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509PrivateKey
 IX509PrivateKey::put_ParentWindow method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The ParentWindow property specifies or retrieves the ID of the window used to display key information.
This property is read/write.

Syntax
HRESULT put_ParentWindow(
LONG Value
);

Parameters
Value

Return value
None

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509PrivateKey
 IX509PrivateKey::put_Pin method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Pin property specifies a personal identification number (PIN) that is used to authenticate users prior to
accessing a private key container on a smart card.
This property is write-only.

Syntax
HRESULT put_Pin(
BSTR Value
);

Parameters
Value

Return value
None

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509PrivateKey
 IX509PrivateKey::put_ProviderName method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The ProviderName property specifies or retrieves the name of the cryptographic provider. This property is
web enabled for both input and output.
This property is read/write.

Syntax
HRESULT put_ProviderName(
BSTR Value
);

Parameters
Value

Return value
None

Remarks
Setting this property automatically sets the following properties to be consistent with the specified
ProviderName value:
KeySpec
LegacyCsp
ProviderType
These properties are set in the following manner:
The provider configuration data is used, if available, to determine the appropriate ProviderType value.
If the specified provider is a CNG KSP:
The LegacyCsp property is set to VARIANT_FALSE .
The KeySpec property is set to XCN_AT_NONE .
If the specified provider is not a CNG KSP:
The LegacyCsp property is set to VARIANT_TRUE .
The KeySpec property is set to XCN_AT_SIGNATURE .
If you set the ProviderName property, we recommend that you do not set the LegacyCsp or ProviderType
properties.

Requirements
 Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509PrivateKey
 IX509PrivateKey::put_ProviderType method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The ProviderType property specifies or retrieves the type of cryptographic provider associated with the private
key. This property is web enabled for both input and output.
This property is read/write.

Syntax
HRESULT put_ProviderType(
X509ProviderType Value
);

Parameters
Value

Return value
None

Remarks
You can use this property to force the use of the default provider for a given provider type. For example, to use
the PROV_RSA_SCHANNEL provider, set this property to the
XCN_PROV_RSA_SCHANNEL X509ProviderType enumeration value and do not specify a value for the
ProviderName property.
Setting this property automatically sets the following properties to be consistent with the specified
ProviderType value:
KeySpec
LegacyCsp
These properties are set in the following manner:
If the ProviderType is set to XCN_PROV_NONE :
The LegacyCsp property is set to VARIANT_FALSE .
The KeySpec property is set to XCN_AT_NONE .
If the ProviderType is not set to XCN_PROV_NONE :
The LegacyCsp property is set to VARIANT_TRUE .
The KeySpec property is set to XCN_AT_SIGNATURE if the current value is XCN_AT_NONE .
Because a previously specified ProviderName is not affected by setting the ProviderType property, setting a
ProviderType that is inconsistent with the ProviderName property will result in undefined behavior, likely a
failure when creating or opening a private key. We recommend that you set the ProviderType property only when
attempting to force the use of the default provider for the specified type as discussed above.
Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509PrivateKey
 IX509PrivateKey::put_ReaderName method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The ReaderName property specifies or retrieves the name of a smart card reader.
This property is read/write.

Syntax
HRESULT put_ReaderName(
BSTR Value
);

Parameters
Value

Return value
None

Remarks
If you set this property before opening a key, the reader name is concatenated to the name of the key container.
The format is \.\Reader_Name\Container_Name. Prepending the reader name to the key container name
enables the name to be disambiguated in subsequent calls to a cryptographic provider. The private key is
typically stored in the smart card key container when a smart card is used.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509PrivateKey
 IX509PrivateKey::put_SecurityDescriptor method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The SecurityDescriptor property specifies or retrieves the security descriptor for the private key.
This property is read/write.

Syntax
HRESULT put_SecurityDescriptor(
BSTR Value
);

Parameters
Value

Return value
None

Remarks
To use the security descriptor, you must call the ConvertStringSecurityDescriptorToSecurityDescriptor function
included with the Microsoft Authorization API and specify the string returned by the
GetDefaultSecurityDescriptor method.
The security descriptor is used to define access to private keys for the computer and user in the following
manner:
By default, only local administrators and services running under the LocalSystem account can access private
keys associated with the computer account.
When a CSP stores the private key of a user in an encrypted file in the user profile, it uses a security
descriptor to set access permissions to the file.
If the key is not open when you specify a descriptor, the property value will be set when the key is opened.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h
 DLL CertEnroll.dll

See also
IX509PrivateKey
 IX509PrivateKey::put_Silent method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Silent property specifies or retrieves a Boolean value that indicates whether the Certificate Enrollment
Control is allowed to display a dialog box when the private key is accessed.
This property is read/write.

Syntax
HRESULT put_Silent(
VARIANT_BOOL Value
);

Parameters
Value

Return value
None

Remarks
If the user interface is not allowed but is required to access the private key, operations that require the user
interface will fail.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509PrivateKey
 IX509PrivateKey::put_UIContextMessage method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The UIContextMessage property specifies or retrieves a string that contains user interface text associated with
the private key.
This property is read/write.

Syntax
HRESULT put_UIContextMessage(
BSTR Value
);

Parameters
Value

Return value
None

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509PrivateKey
 IX509PrivateKey::Verify method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Verify method verifies that a private key exists and can be used by the client but does not open the key.

Syntax
HRESULT Verify(
[in] X509PrivateKeyVerify VerifyType
);

Parameters
[in] VerifyType

An X509PrivateKeyVerify enumeration value that specifies execution options for the method. This can be one of
the following values.

VA L UE M EA N IN G

Does not verify.

VerifyNone

Does not verify if a user interface is required to open the

VerifySilent private key; otherwise verification occurs. For more
information, see Remarks.

Does not verify if the key is stored on a smart card;

VerifySmar tCardNone otherwise, this value is equivalent to VerifyAllowUI .

Does not verify if a user interface is required to open the

VerifySmar tCardSilent private key and the key is stored on a smart card; otherwise,
this value is equivalent to VerifyAllowUI . For more
information, see Remarks.

The method allows a user interface to be displayed.

VerifyAllowUI

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. Possible values include, but are not
limited to, those in the following table. Also, this method calls the CryptGetUserKey and CryptAcquireContext
CryptoAPI functions and can return errors identified in that documentation. For a list of common error codes,
see Common HRESULT Values.

RET URN C O DE DESC RIP T IO N

 Properties related to the CSP or KSP could not be found.
CERTSRV_E_PROPERTY_EMPTY

Remarks
If VerifySilent or VerifySmar tCardSilent values are set and the cryptographic provider specifies that a user
interface is necessary, the key will not be opened, but the method returns S_OK .

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509PrivateKey
 IX509PublicKey interface (certenroll.h)
7/2/2022 • 3 minutes to read • Edit Online

The IX509PublicKey interface represents a public key in a public/private key pair. The public key is included in
the certificate request sent to a certification authority (CA) and in the certificate received from the CA. For more
information, see Public/Private Key Pairs.
The Certificate Enrollment Control passes public and private keys in byte arrays. The following certificate
example shows a 1024-bit public key created by using the RSA signing algorithm, XCN_OID_RSA_RSA
(1.2.840.113549.1.1.1).

...
Public Key Algorithm:
Algorithm ObjectId: 1.2.840.113549.1.1.1 RSA (RSA_SIGN)
Algorithm Parameters:
05 00
Public Key Length: 1024 bits
Public Key: UnusedBits = 0
0000 30 81 89 02 81 81 00 8f e2 41 2a 08 e8 51 a8 8c
0010 b3 e8 53 e7 d5 49 50 b3 27 8a 2b cb ea b5 42 73
0020 ea 02 57 cc 65 33 ee 88 20 61 a1 17 56 c1 24 18
0030 e3 a8 08 d3 be d9 31 f3 37 0b 94 b8 cc 43 08 0b
0040 70 24 f7 9c b1 8d 5d d6 6d 82 d0 54 09 84 f8 9f
0050 97 01 75 05 9c 89 d4 d5 c9 1e c9 13 d7 2a 6b 30
0060 91 19 d6 d4 42 e0 c4 9d 7c 92 71 e1 b2 2f 5c 8d
0070 ee f0 f1 17 1e d2 5f 31 5b b1 9c bc 20 55 bf 3a
0080 37 42 45 75 dc 90 65 02 03 01 00 01
...

The public key consists of a 1024-bit modulus created by multiplying two large prime numbers and a 96-bit
exponent. The RSA algorithm uses the exponent and the prime numbers in the standard Euclidian formula to
create a private key. The modulus and exponent can be more clearly identified by examining the following ASN.1
output of the same public key. Because the modulus begins with a byte (0x8F) for which the sign bit is set, 0x00
is prepended to ensure that the integer remains unsigned. Other public key algorithms create public keys that
are made up from different constituent parts.

30 81 89 ; SEQUENCE (89 Bytes)

02 81 81 ; INTEGER (81 Bytes)
| 00 // Modulus
| 8f e2 41 2a 08 e8 51 a8 8c b3 e8 53 e7 d5 49 50
| b3 27 8a 2b cb ea b5 42 73 ea 02 57 cc 65 33 ee
| 88 20 61 a1 17 56 c1 24 18 e3 a8 08 d3 be d9 31
| f3 37 0b 94 b8 cc 43 08 0b 70 24 f7 9c b1 8d 5d
| d6 6d 82 d0 54 09 84 f8 9f 97 01 75 05 9c 89 d4
| d5 c9 1e c9 13 d7 2a 6b 30 91 19 d6 d4 42 e0 c4
| 9d 7c 92 71 e1 b2 2f 5c 8d ee f0 f1 17 1e d2 5f
| 31 5b b1 9c bc 20 55 bf 3a 37 42 45 75 dc 90 65
02 03 ; INTEGER (3 Bytes)
01 00 01 // Exponent
Inheritance
The IX509PublicKey interface inherits from the IDispatch interface. IX509PublicKey also has these types of
members:

Methods
The IX509PublicKey interface has these methods.

IX509PublicKey::ComputeKeyIdentifier

Creates an identifier from a 160-bit SHA-1 hash of the public key.

IX509PublicKey::get_Algorithm

Retrieves an object identifier (OID) for the public key algorithm.

IX509PublicKey::get_EncodedKey

Retrieves a byte array that contains the public key.

IX509PublicKey::get_EncodedParameters

Retrieves a byte array that contains the parameters associated with the public key algorithm.

IX509PublicKey::get_Length

Retrieves the length of the public key.

IX509PublicKey::Initialize

Initializes the object from a public key algorithm object identifier (OID) and from byte arrays that contain a public key and the
associated parameters, if any.

IX509PublicKey::InitializeFromEncodedPublicKeyInfo

Initializes the object from a byte array that contains a public key.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

See also
CertEnroll Interfaces
IDispatch
IX509PrivateKey
Public/Private Key Pairs
 IX509PublicKey::ComputeKeyIdentifier method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The ComputeKeyIdentifier method creates an identifier from a 160-bit SHA-1 hash of the public key.

Syntax
HRESULT ComputeKeyIdentifier(
[in] KeyIdentifierHashAlgorithm Algorithm,
[in] EncodingType Encoding,
[out] BSTR *pValue
);

Parameters
[in] Algorithm

A value of the KeyIdentifierHashAlgorithm enumeration that specifies what hash algorithm to use to create the
key identifier.
If this value is SKIHashDefault or SKIHashSha1, the identifier is created by hashing only the byte array that
contains the key and excluding the Distinguished Encoding Rules (DER) tag, length, and unused bits fields.
If this value is SKIHashCapiSha1, the identifier is created by hashing the DER-encoded byte array that contains
the tag, length, number of unused bits, and the public key.
[in] Encoding

An EncodingType enumeration value that specifies the type of Unicode-encoding to be applied to the hash
contained in the pValue parameter. The default value is XCN_CRYPT_STRING_BASE64.
[out] pValue

Pointer to a BSTR variable that contains the key identifier.

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. Possible values include, but are not
limited to, those in the following table. For a list of common error codes, see Common HRESULT Values.

RET URN C O DE/ VA L UE DESC RIP T IO N

The algorithm object identifier or the public key parameters

CERTSRV_E_PROPERTY_EMPTY could not be found.

Remarks
You must call the InitializeFromEncodedPublicKeyInfo method or the Initialize method to initialize the public key
object before calling ComputeKeyIdentifier .

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509PublicKey
 IX509PublicKey::get_Algorithm method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Algorithm property retrieves an object identifier (OID) for the public key algorithm.
This property is read-only.

Syntax
HRESULT get_Algorithm(
IObjectId **ppValue
);

Parameters
ppValue

Return value
None

Remarks
Call the InitializeFromEncodedPublicKeyInfo method or the Initialize method to initialize the public key object
before calling this property.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509PublicKey
 IX509PublicKey::get_EncodedKey method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The EncodedKey property retrieves a byte array that contains the public key. The byte array is represented by a
Unicode-encoded string.
This property is read-only.

Syntax
HRESULT get_EncodedKey(
EncodingType Encoding,
BSTR *pValue
);

Parameters
Encoding

pValue

Return value
None

Remarks
Call the InitializeFromEncodedPublicKeyInfo method or the Initialize method to initialize the public key object
before calling this property.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509PublicKey
 IX509PublicKey::get_EncodedParameters method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The EncodedParameters property retrieves a byte array that contains the parameters associated with the
public key algorithm. The byte array is represented by a Unicode-encoded string.
This property is read-only.

Syntax
HRESULT get_EncodedParameters(
EncodingType Encoding,
BSTR *pValue
);

Parameters
Encoding

pValue

Return value
None

Remarks
Call the InitializeFromEncodedPublicKeyInfo method or the Initialize method to initialize the public key object
before calling this property.
The AlgorithmIdentifier Abstract Syntax Notation One (ASN.1) object that is referenced by the
SubjectPublicKeyInfo object in an X.509 version 3 certificate contains an algorithm object identifier (OID) and
optional parameters.

SubjectPublicKeyInfo ::= SEQUENCE

{
algorithm AlgorithmIdentifier,
subjectPublicKey BIT STRING
}

AlgorithmIdentifier ::= SEQUENCE

{
algorithm OBJECT IDENTIFIER,
parameters ANY DEFINED BY algorithm OPTIONAL
}

The format and content of the parameters differs by algorithm. The Certificate Enrollment Control generates
parameter values for various algorithms as required. For more information, see the following sections:
 RSA Public Key Algorithm
Key Transpor t Using RSA-OAEP
Key Agreement Using ECDH
Content Encr yption Using AES
RSA Public Key Algorithm
RSA is often used to encrypt a private key and send it to a certification authority (CA) for archival. The
XCN_OID_RSA_RSA (1.2.840.113549.1.1.1) algorithm OID must have a NULL parameter value. The ASN.1 NULL
value is represented by two bytes. The tag number is 0x05 and the value associated with the tag is 0x00. This is
shown by the following certificate example.

...
Public Key Algorithm:
Algorithm ObjectId: 1.2.840.113549.1.1.1 RSA (RSA_KEYX)
Algorithm Parameters:
05 00
...

Key Transport Using RSA -OAEP

The RSA-OAEP algorithm, XCN_OID_RSAES_OAEP (1.2.840.113549.1.1.7), is also supported for key transport. The
parameters field has the following syntax.

RSAES-OAEP-params ::= SEQUENCE

{
hashFunc [0] AlgorithmIdentifier DEFAULT sha1OID,
maskGenFunc [1] AlgorithmIdentifier DEFAULT mgf1SHA1OID,
pSourceFunc [2] AlgorithmIdentifier DEFAULT pSpecifiedEmptyOID
}

Key Agreement Using ECDH

The single pass Elliptic Curve Diffie-Hellman algorithm, XCN_OID_DH_SINGLE_PASS_STDDH_SHA1_KDF
(1.3.133.16.840.63.0.2), is supported for key agreement. Key agreement uses two levels of encryption:
The message is encrypted by using a content encryption key (CEK) and a symmetric encryption algorithm.
The CEK is encrypted (wrapped) by using a symmetric key encryption key (KEK).
The KEK is computed from a shared secret number that is computed from the private key of one party and the
public key of the other party. The parameters field contains the OID of the KEK algorithm used to wrap or encrypt
the CEK. The following wrap algorithms are supported:
XCN_OID_RSA_SMIMEalgCMS3DESwrap (1.2.840.113549.1.9.16.3.)
XCN_OID_RSA_SMIMEalgCMSRC2wrap (1.2.840.113549.1.9.16.3.7)
XCN_OID_NIST_AES128_WRAP (2.16.840.1.101.3.4.1.5)
XCN_OID_NIST_AES192_WRAP (2.16.840.1.101.3.4.1.25)
XCN_OID_NIST_AES256_WRAP (2.16.840.1.101.3.4.1.45)
Content Encryption Using AES
The Advanced Encryption Standard (AES) is used to encrypt content. The following algorithms are supported:
XCN_OID_NIST_AES128_CBC (2.16.840.1.101.3.4.1.2)
XCN_OID_NIST_AES192_CBC (2.16.840.1.101.3.4.1.22)
XCN_OID_NIST_AES256_CBC (2.16.840.1.101.3.4.1.42)
The parameters field contains a random initialization vector, AES-IV.

AES-IV ::= OCTET STRING (SIZE(16))

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509PublicKey
 IX509PublicKey::get_Length method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Length property retrieves the length of the public key.

This property is read-only.

Syntax
HRESULT get_Length(
LONG *pValue
);

Parameters
pValue

Return value
None

Remarks
Call the InitializeFromEncodedPublicKeyInfo method or the Initialize method to initialize the public key object
before calling this property.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509PublicKey
 IX509PublicKey::Initialize method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Initialize method initializes the object from a public key algorithm object identifier (OID) and from byte
arrays that contain a public key and the associated parameters, if any. The byte arrays are represented by
Unicode-encoded strings.

Syntax
HRESULT Initialize(
[in] IObjectId *pObjectId,
[in] BSTR strEncodedKey,
[in] BSTR strEncodedParameters,
[in] EncodingType Encoding
);

Parameters
[in] pObjectId

Pointer to an IObjectId interface that represents the algorithm OID.

[in] strEncodedKey

A BSTR variable that contains the public key.

[in] strEncodedParameters

A BSTR variable that contains the parameters associated with the public key. For more information, see the
EncodedParameters property.
[in] Encoding

An EncodingType enumeration value that specifies the type of Unicode-encoding applied to the arguments
specified in the strEncodedKey and strEncodedParameters parameters. The default value is
XCN_CRYPT_STRING_BASE64.

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. Possible values include, but are not
limited to, those in the following table. For a list of common error codes, see Common HRESULT Values.

RET URN C O DE/ VA L UE DESC RIP T IO N

The object has already been initialized.

HRESULT_FROM_WIN32(ERROR_ALREADY_INITIALIZE
D)

Remarks
The Initialize method initializes the following property values:
Algorithm
EncodedKey
EncodedParameters
Length

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509PublicKey
 IX509PublicKey::InitializeFromEncodedPublicKeyInfo
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The InitializeFromEncodedPublicKeyInfo method initializes the object from a byte array that contains a
public key. The byte array is represented by a Unicode-encoded string.

Syntax
HRESULT InitializeFromEncodedPublicKeyInfo(
[in] BSTR strEncodedPublicKeyInfo,
[in] EncodingType Encoding
);

Parameters
[in] strEncodedPublicKeyInfo

A BSTR variable that contains the key.

[in] Encoding

An EncodingType enumeration value that specifies the type of Unicode encoding applied to the key contained in
the strEncodedPublicKeyInfo parameter. The default value is XCN_CRYPT_STRING_BASE64.

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. Possible values include, but are not
limited to, those in the following table. For a list of common error codes, see Common HRESULT Values.

RET URN C O DE/ VA L UE DESC RIP T IO N

The object has already been initialized.

HRESULT_FROM_WIN32(ERROR_ALREADY_INITIALIZE
D)

Remarks
The InitializeFromEncodedPublicKeyInfo method initializes the following property values from an existing
public key:
Algorithm
EncodedKey
EncodedParameters
Length

Requirements
 Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509PublicKey
 IX509SCEPEnrollment interface (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

X.509 Simple Computer Enrollment Protocol Interface

Inheritance
The IX509SCEPEnrollment interface inherits from the IDispatch interface. IX509SCEPEnrollment also has
these types of members:

Methods
The IX509SCEPEnrollment interface has these methods.

IX509SCEPEnrollment::CreateRequestMessage

Create a PKCS10 request message with a challenge password. The request message is in an enveloped PKCS7 encrypted with
the SCEP server encryption certificate and signed by the server signing certificate.

IX509SCEPEnrollment::CreateRetrieveCertificateMessage

Retrieve a previously issued certificate.

IX509SCEPEnrollment::CreateRetrievePendingMessage

Create a message for certificate polling (manual enrollment).

IX509SCEPEnrollment::DeleteRequest

Delete any certificates or keys created for the request.

IX509SCEPEnrollment::get_Certificate

Gets the certificate for the request.

IX509SCEPEnrollment::get_CertificateFriendlyName

Gets or sets the friendly name for the certificate.

IX509SCEPEnrollment::get_FailInfo

Gets information when the ProcessResponseMessage method detects a failed environment.

IX509SCEPEnrollment::get_OldCertificate

Gets or sets an old certificate that a request is intended to replace.

IX509SCEPEnrollment::get_Request

Gets the inner PKCS10 request.

 IX509SCEPEnrollment::get_SignerCertificate

Gets or sets the signer certificate for the request.

IX509SCEPEnrollment::get_Status

Gets the status of the request.

IX509SCEPEnrollment::get_TransactionId

Gets or sets the transaction id for the request.

IX509SCEPEnrollment::Initialize

Initialize the instance in preparation for a new request.

IX509SCEPEnrollment::InitializeForPending

Initialize the instance to prepare to generate a message to either retrieve an issued certificate, or install a response for a
previous request by the issuer.

IX509SCEPEnrollment::ProcessResponseMessage

Process a response message and return the disposition of the message.

IX509SCEPEnrollment::put_CertificateFriendlyName

Gets or sets the friendly name for the certificate.

IX509SCEPEnrollment::put_OldCertificate

Gets or sets an old certificate that a request is intended to replace.

IX509SCEPEnrollment::put_ServerCapabilities

Sets the preferred hash and encryption algorithms for the request.

IX509SCEPEnrollment::put_SignerCertificate

Gets or sets the signer certificate for the request.

IX509SCEPEnrollment::put_Silent

Gets or sets whether to allow UI during the request.

IX509SCEPEnrollment::put_TransactionId

Gets or sets the transaction id for the request.

Requirements

Target Platform Windows

Header certenroll.h
 IX509SCEPEnrollment::CreateRequestMessage
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

Create a PKCS10 request message with a challenge password. The request message is in an enveloped PKCS7
encrypted with the SCEP server encryption certificate and signed by the server signing certificate.

Syntax
HRESULT CreateRequestMessage(
[in] EncodingType Encoding,
[out, retval] BSTR *pValue
);

Parameters
[in] Encoding

[out, retval] pValue

Return value
If this method succeeds, it returns S_OK . Otherwise, it returns an HRESULT error code.

Remarks
You must call the Initialize method before calling this method.

Requirements

Target Platform Windows

Header certenroll.h

DLL Certenroll.dll

See also
IX509SCEPEnrollment
 IX509SCEPEnrollment::CreateRetrieveCertificateMessage
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

Retrieve a previously issued certificate.

Syntax
HRESULT CreateRetrieveCertificateMessage(
[in] X509CertificateEnrollmentContext Context,
[in] BSTR strIssuer,
[in] EncodingType IssuerEncoding,
[in] BSTR strSerialNumber,
[in] EncodingType SerialNumberEncoding,
[in] EncodingType Encoding,
[out, retval] BSTR *pValue
);

Parameters
[in] Context

[in] strIssuer

ASN.1 encoded issuer name.

[in] IssuerEncoding

[in] strSerialNumber

[in] SerialNumberEncoding

[in] Encoding

[out, retval] pValue

Return value
If this method succeeds, it returns S_OK . Otherwise, it returns an HRESULT error code.

Remarks
You must call the InitializeForPending method before calling this method.

Requirements

Target Platform Windows

Header certenroll.h
 DLL Certenroll.dll

See also
IX509SCEPEnrollment
 IX509SCEPEnrollment::CreateRetrievePendingMessage
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

Create a message for certificate polling (manual enrollment).

Syntax
HRESULT CreateRetrievePendingMessage(
[in] EncodingType Encoding,
[out, retval] BSTR *pValue
);

Parameters
[in] Encoding

[out, retval] pValue

Return value
If this method succeeds, it returns S_OK . Otherwise, it returns an HRESULT error code.

Remarks
You must call the InitializeForPending method before calling this method.

Requirements

Target Platform Windows

Header certenroll.h

DLL Certenroll.dll

See also
IX509SCEPEnrollment
 IX509SCEPEnrollment::DeleteRequest method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

Delete any certificates or keys created for the request.

Syntax
HRESULT DeleteRequest();

Return value
If this method succeeds, it returns S_OK . Otherwise, it returns an HRESULT error code.

Remarks
You must set the TransactionId property and call the InitializeForPending method before calling this method.

Requirements

Target Platform Windows

Header certenroll.h

DLL Certenroll.dll

See also
IX509SCEPEnrollment
 IX509SCEPEnrollment::get_Certificate method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

Gets the certificate for the request.

This property is read-only.

Syntax
HRESULT get_Certificate(
EncodingType Encoding,
BSTR *pValue
);

Parameters
Encoding

pValue

Return value
None

Requirements

Target Platform Windows

Header certenroll.h

DLL Certenroll.dll

See also
IX509SCEPEnrollment
 IX509SCEPEnrollment::get_CertificateFriendlyName
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

Gets or sets the friendly name for the certificate.

This property is read/write.

Syntax
HRESULT get_CertificateFriendlyName(
BSTR *pValue
);

Parameters
pValue

Return value
None

Requirements

Target Platform Windows

Header certenroll.h

DLL Certenroll.dll

See also
IX509SCEPEnrollment
 IX509SCEPEnrollment::get_FailInfo method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

Gets information when the ProcessResponseMessage method detects a failed environment.

This property is read-only.

Syntax
HRESULT get_FailInfo(
X509SCEPFailInfo *pValue
);

Parameters
pValue

Return value
None

Requirements

Target Platform Windows

Header certenroll.h

DLL Certenroll.dll

See also
IX509SCEPEnrollment
 IX509SCEPEnrollment::get_OldCertificate method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

Gets or sets an old certificate that a request is intended to replace.

This property is read/write.

Syntax
HRESULT get_OldCertificate(
ISignerCertificate **ppValue
);

Parameters
ppValue

Return value
None

Remarks
You must set this property before you call the CreateRequestMessage method.

Requirements

Target Platform Windows

Header certenroll.h

DLL Certenroll.dll

See also
IX509SCEPEnrollment
 IX509SCEPEnrollment::get_Request method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

Gets the inner PKCS10 request.

This property is read-only.

Syntax
HRESULT get_Request(
IX509CertificateRequestPkcs10 **ppValue
);

Parameters
ppValue

Return value
None

Remarks
You can use the inner PKCS10 request instance to set the subject, extensions, private key properties, encryption
algorithm and strength, and the hash algorithm before you call the CreateRequestMessage method.

Requirements

Target Platform Windows

Header certenroll.h

DLL Certenroll.dll

See also
IX509SCEPEnrollment
 IX509SCEPEnrollment::get_SignerCertificate method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

Gets or sets the signer certificate for the request.

This property is read/write.

Syntax
HRESULT get_SignerCertificate(
ISignerCertificate **ppValue
);

Parameters
ppValue

Return value
None

Remarks
To create a renewal request, you must set this property prior to calling the CreateRequestMessage method.
Otherwise, the CreateRequestMessage method will create a new request and generate a self-signed
certificate using the same private key as the inner PKCSV10 reqeust.

Requirements

Target Platform Windows

Header certenroll.h

DLL Certenroll.dll

See also
IX509SCEPEnrollment
 IX509SCEPEnrollment::get_Status method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

Gets the status of the request.

This property is read-only.

Syntax
HRESULT get_Status(
IX509EnrollmentStatus **ppValue
);

Parameters
ppValue

Return value
None

Requirements

Target Platform Windows

Header certenroll.h

DLL Certenroll.dll

See also
IX509SCEPEnrollment
 IX509SCEPEnrollment::get_TransactionId method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

Gets or sets the transaction id for the request.

This property is read/write.

Syntax
HRESULT get_TransactionId(
EncodingType Encoding,
BSTR *pValue
);

Parameters
Encoding

pValue

Return value
None

Remarks
If you do not specify a transaction id, then the CreateRequestMessage method will create one. If the transaction
id has not been set or the CreateRequestMessage method has not been called, then this property will return
CERTSRV_E_PROPERTY_EMPTY .
After processing a pending request, the caller must save this value for later use when calling the
CreateRetrievePendingMessage method to format a message to be sent to the SCEP server to poll for the issued
certificate.
Set this property before you call the ProcessResponseMessage method when you are using a new instance of
the IX509SCEPEnrollment interface to install the response.
Set this property before you call the CreateRetrievePendingMessage method when you are using a new instance
of the IX509SCEPEnrollment interface to create a retrieval message.

Requirements

Target Platform Windows

Header certenroll.h
 DLL Certenroll.dll

See also
IX509SCEPEnrollment
 IX509SCEPEnrollment::Initialize method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

Initialize the instance in preparation for a new request.

Syntax
HRESULT Initialize(
[in] IX509CertificateRequestPkcs10 *pRequest,
[in] BSTR strThumbprint,
[in] EncodingType ThumprintEncoding,
[in] BSTR strServerCertificates,
[in] EncodingType Encoding
);

Parameters
[in] pRequest

An instance of a request that has already been initialized.

[in] strThumbprint

The CA certificate thumbprint.

[in] ThumprintEncoding

The encoding of the CA certificate thumbprint.

[in] strServerCertificates

A PKCS7 request with CA and SCEP RA certificates.

[in] Encoding

The encoding type of the request.

Return value
If this method succeeds, it returns S_OK . Otherwise, it returns an HRESULT error code.

Remarks
This method expects an SCEP server signature EA certificate and an SCEP server encryption EA certificate, both
signed by the CA certificate.
This method fails if any of the expected certificates is missing, or if the thumbprint doesn't match the CA
certificate.

Requirements
 Target Platform Windows

Header certenroll.h

DLL Certenroll.dll

See also
IX509SCEPEnrollment
 IX509SCEPEnrollment::InitializeForPending method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

Initialize the instance to prepare to generate a message to either retrieve an issued certificate, or install a
response for a previous request by the issuer.

Syntax
HRESULT InitializeForPending(
[in] X509CertificateEnrollmentContext Context
);

Parameters
[in] Context

Return value
If this method succeeds, it returns S_OK . Otherwise, it returns an HRESULT error code.

Requirements

Target Platform Windows

Header certenroll.h

DLL Certenroll.dll

See also
IX509SCEPEnrollment
 IX509SCEPEnrollment::ProcessResponseMessage
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

Process a response message and return the disposition of the message.

Syntax
HRESULT ProcessResponseMessage(
[in] BSTR strResponse,
[in] EncodingType Encoding,
[out, retval] X509SCEPDisposition *pDisposition
);

Parameters
[in] strResponse

[in] Encoding

[out, retval] pDisposition

Return value
If this method succeeds, it returns S_OK . Otherwise, it returns an HRESULT error code.

Remarks
You must call the Initialize and CreateRequestMessage methods or the InitializeForPending method before
calling this method.

Requirements

Target Platform Windows

Header certenroll.h

DLL Certenroll.dll

See also
IX509SCEPEnrollment
 IX509SCEPEnrollment::put_CertificateFriendlyName
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

Gets or sets the friendly name for the certificate.

This property is read/write.

Syntax
HRESULT put_CertificateFriendlyName(
BSTR Value
);

Parameters
Value

Return value
None

Requirements

Target Platform Windows

Header certenroll.h

DLL Certenroll.dll

See also
IX509SCEPEnrollment
 IX509SCEPEnrollment::put_OldCertificate method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

Gets or sets an old certificate that a request is intended to replace.

This property is read/write.

Syntax
HRESULT put_OldCertificate(
ISignerCertificate *pValue
);

Parameters
pValue

Return value
None

Remarks
You must set this property before you call the CreateRequestMessage method.

Requirements

Target Platform Windows

Header certenroll.h

DLL Certenroll.dll

See also
IX509SCEPEnrollment
 IX509SCEPEnrollment::put_ServerCapabilities
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

Sets the preferred hash and encryption algorithms for the request.
This property is write-only.

Syntax
HRESULT put_ServerCapabilities(
BSTR Value
);

Parameters
Value

Return value
None

Remarks
If you do not set this property, then the default hash and encryption algorithms will be used.
This property must be set before calling the CreateRequestMessage, CreateRetrievePendingMessage, or
CreateRetrieveCertificateMessage methods.

Requirements

Target Platform Windows

Header certenroll.h

DLL Certenroll.dll

See also
IX509SCEPEnrollment
 IX509SCEPEnrollment::put_SignerCertificate method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

Gets or sets the signer certificate for the request.

This property is read/write.

Syntax
HRESULT put_SignerCertificate(
ISignerCertificate *pValue
);

Parameters
pValue

Return value
None

Remarks
To create a renewal request, you must set this property prior to calling the CreateRequestMessage method.
Otherwise, the CreateRequestMessage method will create a new request and generate a self-signed
certificate using the same private key as the inner PKCSV10 reqeust.

Requirements

Target Platform Windows

Header certenroll.h

DLL Certenroll.dll

See also
IX509SCEPEnrollment
 IX509SCEPEnrollment::put_Silent method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

Gets or sets whether to allow UI during the request.

This property is write-only.

Syntax
HRESULT put_Silent(
VARIANT_BOOL Value
);

Parameters
Value

Return value
None

Requirements

Target Platform Windows

Header certenroll.h

DLL Certenroll.dll

See also
IX509SCEPEnrollment
 IX509SCEPEnrollment::put_TransactionId method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

Gets or sets the transaction id for the request.

This property is read/write.

Syntax
HRESULT put_TransactionId(
EncodingType Encoding,
BSTR Value
);

Parameters
Encoding

Value

Return value
None

Remarks
If you do not specify a transaction id, then the CreateRequestMessage method will create one. If the transaction
id has not been set or the CreateRequestMessage method has not been called, then this property will return
CERTSRV_E_PROPERTY_EMPTY .
After processing a pending request, the caller must save this value for later use when calling the
CreateRetrievePendingMessage method to format a message to be sent to the SCEP server to poll for the issued
certificate.
Set this property before you call the ProcessResponseMessage method when you are using a new instance of
the IX509SCEPEnrollment interface to install the response.
Set this property before you call the CreateRetrievePendingMessage method when you are using a new instance
of the IX509SCEPEnrollment interface to create a retrieval message.

Requirements

Target Platform Windows

Header certenroll.h
 DLL Certenroll.dll

See also
IX509SCEPEnrollment
 IX509SignatureInformation interface (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The IX509SignatureInformation interface represents information used to sign a certificate request. This
includes signature, hash, and public key algorithms, and public key parameters. The signature process consists
of digesting the certificate request by using a hash algorithm, encoding the digest and the hash algorithm
identifier by using Distinguished Encoding Rules (DER), and signing (encrypting) the result.
The algorithms used in this process can be either discrete or combined. Discrete algorithms are represented by
separate object identifiers (OIDs) for the hashing algorithm and the signing algorithm. Discrete algorithms are
used when signing a PKCS #7 or CMC request. Examples include the following values.

DISC RET E A L GO RIT H M O ID DESC RIP T IO N

XCN_OID_NIST_sha256(2.16.840.1.101.3.4.2.1) National Institute of Standards and Technologies (NIST) 256-

bit SHA hashing algorithm.

XCN_OID_OIWSEC_rsaSign(1.3.14.3.2.11) NIST OSE Implementer Workshop Security (OIWSEC) RSA

signing algorithm.

Combined algorithms, which can be used to sign PKCS #10 requests, are represented by a single OID that
identifies both the hashing and the signing algorithm. Examples include the following values.

C O M B IN ED A L GO RIT H M O ID DESC RIP T IO N

XCN_OID_RSA_MD2RSA(1.2.840.113549.1.1.2) MD2 hashing algorithm combined with the RSA encryption

algorithm from RSA Laboratories.

XCN_OID_OIWSEC_md5RSA(1.3.14.3.2.3) OIWSEC MD5 hashing algorithm combined with the RSA

encryption algorithm.

The object is automatically initialized when an IX509CertificateRequestCmc, IX509CertificateRequestPkcs10, or

ISignerCertificate object is initialized.

Inheritance
The IX509SignatureInformation interface inherits from the IDispatch interface.
IX509SignatureInformation also has these types of members:

Methods
The IX509SignatureInformation interface has these methods.

IX509SignatureInformation::get_AlternateSignatureAlgorithm

Specifies and retrieves a Boolean value that specifies whether the GetSignatureAlgorithm method should retrieve a discrete or
combined algorithm object identifier (OID) for a PKCS
 IX509SignatureInformation::get_AlternateSignatureAlgorithmSet

Retrieves a Boolean value that specifies whether the AlternateSignatureAlgorithm property has been explicitly set by a caller.

IX509SignatureInformation::get_HashAlgorithm

Specifies and retrieves an object identifier (OID) for the hashing algorithm used in the GetSignatureAlgorithm method.

IX509SignatureInformation::get_NullSigned

Specifies and retrieves a Boolean value that indicates whether the certificate request is null-signed.

IX509SignatureInformation::get_Parameters

Retrieves a byte array that contains the parameters associated with the signature algorithm.

IX509SignatureInformation::get_PublicKeyAlgorithm

Specifies and retrieves an object identifier (OID) for the public key algorithm used in the GetSignatureAlgorithm method.

IX509SignatureInformation::GetSignatureAlgorithm

Retrieves the signing algorithm object identifier (OID).

IX509SignatureInformation::put_AlternateSignatureAlgorithm

Specifies and retrieves a Boolean value that specifies whether the GetSignatureAlgorithm method should retrieve a discrete or
combined algorithm object identifier (OID) for a PKCS

IX509SignatureInformation::put_HashAlgorithm

Specifies and retrieves an object identifier (OID) for the hashing algorithm used in the GetSignatureAlgorithm method.

IX509SignatureInformation::put_NullSigned

Specifies and retrieves a Boolean value that indicates whether the certificate request is null-signed.

IX509SignatureInformation::put_Parameters

Retrieves a byte array that contains the parameters associated with the signature algorithm.

IX509SignatureInformation::put_PublicKeyAlgorithm

Specifies and retrieves an object identifier (OID) for the public key algorithm used in the GetSignatureAlgorithm method.

IX509SignatureInformation::SetDefaultValues

Specifies a default hashing algorithm used to create a digest of the certificate request prior to signing.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

 Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

See also
Certificate Enrollment API
IDispatch
ISignerCertificate
IX509CertificateRequestCmc
IX509CertificateRequestPkcs10
 IX509SignatureInformation::get_AlternateSignatureAlgorithm
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The AlternateSignatureAlgorithm property specifies and retrieves a Boolean value that specifies whether the
GetSignatureAlgorithm method should retrieve a discrete or combined algorithm object identifier (OID) for a
PKCS #10 certificate request.
This property is read/write.

Syntax
HRESULT get_AlternateSignatureAlgorithm(
VARIANT_BOOL *pValue
);

Parameters
pValue

Return value
None

Remarks
PKCS #7 and CMC certificate requests always use a discrete signature algorithm OID and a separate hashing
algorithm OID. Only PKCS #10 certificate requests use combined algorithm OIDs. You can set the
AlternateSignatureAlgorithm property to retrieve a discrete signature algorithm OID from the
GetSignatureAlgorithm method for a PKCS #10 request. If you set this property, the hashing algorithm OID can
be retrieved from the Parameters property, and the AlternateSignatureAlgorithmSet property is also set. For
examples of discrete and combined OIDs, see IX509SignatureInformation

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509SignatureInformation
 IX509SignatureInformation::get_AlternateSignatureAlgorithmSet
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The AlternateSignatureAlgorithmSet property retrieves a Boolean value that specifies whether the
AlternateSignatureAlgorithm property has been explicitly set by a caller.
This property is read-only.

Syntax
HRESULT get_AlternateSignatureAlgorithmSet(
VARIANT_BOOL *pValue
);

Parameters
pValue

Return value
None

Remarks
The AlternateSignatureAlgorithmSet property is used by a CMC certificate request object. If the
AlternateSignatureAlgorithm property is explicitly set on a signer certificate, and the same property is set on the
IX509CertificateRequestCmc object, the CMC request will not override the property value on the signer
certificate.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
ISignerCertificate
IX509SignatureInformation
 IX509SignatureInformation::get_HashAlgorithm
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The HashAlgorithm property specifies and retrieves an object identifier (OID) for the hashing algorithm used
in the GetSignatureAlgorithm method.
This property is read/write.

Syntax
HRESULT get_HashAlgorithm(
IObjectId **ppValue
);

Parameters
ppValue

Return value
None

Remarks
You must set this property before calling the GetSignatureAlgorithm method. You must also set the
PublicKeyAlgorithm property unless you are retrieving a signature algorithm for a null-signed certificate
request. You can also set the NullSigned, AlternateSignatureAlgorithm, and Parameters properties.
The HashAlgorithm property validates whether the OID you specify represents a hashing algorithm. If the OID
is valid, the property also clears the signature property cache.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509SignatureInformation
 IX509SignatureInformation::get_NullSigned method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The NullSigned property specifies and retrieves a Boolean value that indicates whether the certificate request
is null-signed.
This property is read/write.

Syntax
HRESULT get_NullSigned(
VARIANT_BOOL *pValue
);

Parameters
pValue

Return value
None

Remarks
A null-signed certificate request is not really signed. That is, the request can be digested by using a digest
algorithm such as SHA-1, but it is not encrypted with a public key algorithm such as RSA. You must set this
property before calling the GetSignatureAlgorithm method.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509SignatureInformation
 IX509SignatureInformation::get_Parameters method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Parameters property retrieves a byte array that contains the parameters associated with the signature
algorithm. The byte array is represented by a Unicode-encoded string.
This property is read/write.

Syntax
HRESULT get_Parameters(
EncodingType Encoding,
BSTR *pValue
);

Parameters
Encoding

pValue

Return value
None

Remarks
The AlgorithmIdentifier ASN.1 object that is used in various fields of an X.509 version 3 certificate contains an
algorithm object identifier (OID) and optional parameters.

AlgorithmIdentifier ::= SEQUENCE

{
algorithm OBJECT IDENTIFIER,
parameters ANY DEFINED BY algorithm OPTIONAL
}

The format and content of the parameters differs by algorithm. The Certificate Enrollment Control generates
parameter information as required. Parameter values generated for various algorithms are discussed in the
following sections.
PKCS #1 version 1.5 signature algorithms:
The following OIDs must have a NULL parameter value.
XCN_OID_RSA_MD2RSA (1.2.840.113549.1.1.2)
XCN_OID_RSA_MD5RSA (1.2.840.113549.1.1.4)
XCN_OID_RSA_SHA1RSA (1.2.840.113549.1.1.5)
XCN_OID_RSA_SHA256RSA (1.2.840.113549.1.1.11)
 XCN_OID_RSA_SHA384RSA (1.2.840.113549.1.1.12)
XCN_OID_RSA_SHA512RSA (1.2.840.113549.1.1.13)
The ASN.1 NULL value is represented by two bytes. The tag number is 0x05 and the value associated with the
tag, representing the parameter length, is 0x00. This is shown by the following certificate example.

...
Public Key Algorithm:
Algorithm ObjectId: 1.2.840.113549.1.1.1 RSA (RSA_SIGN)
Algorithm Parameters:
05 00
...

RSASSA-PSS signatures:
The RSASSA-PSS (RSA Signature Scheme with Appendix - Probabilistic Signature Scheme),
XCN_OID_RSA_SSA_PSS (1.2.840.113549.1.1.10), generates the following parameter information. A signature
scheme with appendix consists of signature generation and signature verification operations. Verification of the
signature requires the original certificate request on which the signature was generated. For more information,
see the PKCS #1 v2.1 cryptography standard from RSA laboratories.

RSASSA-PSS-params ::= SEQUENCE

{
hashAlgorithm [0] HashAlgorithm DEFAULT sha1,
maskGenAlgorithm [1] MaskGenAlgorithm DEFAULT mgf1SHA1,
saltLength [2] INTEGER DEFAULT 20,
trailerField [3] TrailerField DEFAULT trailerFieldBC
}

ECDSA-SHA1 signature algorithms: When the XCN_OID_ECDSA_SHA1 (1.2.840.10045.4.1) is used to

create a signature, the parameters contains the OID of the hash algorithm. The following OIDs are supported:
XCN_OID_ECDSA_SHA256 (1.2.840.10045.4.3.2)
XCN_OID_ECDSA_SHA384 (1.2.840.10045.4.3.3)
XCN_OID_ECDSA_SHA512 (1.2.840.10045.4.3.4)

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll
See also
IX509SignatureInformation
 IX509SignatureInformation::get_PublicKeyAlgorithm
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The PublicKeyAlgorithm property specifies and retrieves an object identifier (OID) for the public key
algorithm used in the GetSignatureAlgorithm method.
This property is read/write.

Syntax
HRESULT get_PublicKeyAlgorithm(
IObjectId **ppValue
);

Parameters
ppValue

Return value
None

Remarks
Unless you are retrieving a signature algorithm for a null-signed certificate request, you must set this property
before calling the GetSignatureAlgorithm method. You must also set the HashAlgorithm property. You can also
set the AlternateSignatureAlgorithm and NullSigned properties.
The PublicKeyAlgorithm property validates whether the OID you specify represents a public key algorithm. If
the OID is valid, the property also clears the signature property cache.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509SignatureInformation
 IX509SignatureInformation::GetSignatureAlgorithm
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The GetSignatureAlgorithm method retrieves the signing algorithm object identifier (OID).

Syntax
HRESULT GetSignatureAlgorithm(
[in] VARIANT_BOOL Pkcs7Signature,
[in] VARIANT_BOOL SignatureKey,
[out] IObjectId **ppValue
);

Parameters
[in] Pkcs7Signature

A VARIANT_BOOL variable that specifies whether the algorithm will be used to sign a PKCS #7 or CMC
certificate request.
[in] SignatureKey

A VARIANT_BOOL variable that specifies whether an algorithm that is only used for signing is preferred when
an algorithm OID is associated with more than one purpose. For example, XCN_OID_RSA_RSA
(1.2.840.113549.1.1.1) can be used for both signing and key exchange.
[out] ppValue

Address of a variable that receives a pointer to an IObjectId interface that represents the algorithm OID.

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. Possible values include, but are not
limited to, those in the following table. For a list of common error codes, see Common HRESULT Values.

RET URN C O DE/ VA L UE DESC RIP T IO N

The hashing algorithm OID, or the NullSigned property has

CERTSRV_E_PROPERTY_EMPTY not been specified but the signing algorithm OID cannot be
found.

The combined signature algorithm could not be found.

CRYPT_E_UNKNOWN_ALGO

Remarks
This method searches for a cached signing algorithm that is consistent with the input parameters. If none is
found, the method uses the input parameters plus the values assigned to various IX509SignatureInformation
properties as indicated by the following list.
Pkcs7Signature = true, NullSigned = true
This case represents a null-signed PKCS #7 certificate request. The method returns the
XCN_OID_PKIX_NO_SIGNATURE (1.3.6.1.5.5.7.6.2) OID.
Pkcs7Signature = true, NullSigned = false
This case retrieves a discrete signature algorithm OID for a PKCS #7 request that is not null-signed. The
discrete signature requires that the HashAlgorithm and PublicKeyAlgorithm properties be set. In the
special case where the public key algorithm is XCN_OID_X957_DSA and the hashing algorithm is not
XCN_OID_OIWSEC_sha1, the signature algorithm OID retrieved is XCN_OID_X957_SHA1DSA
(1.2.840.10040.4.3).
Pkcs7Signature = false, NullSigned = false, AlternateSignatureAlgorithm = true
This case retrieves a discrete signature algorithm OID for a PKCS #10 request and encodes the hash
algorithm OID in the Parameters property. The HashAlgorithm and PublicKeyAlgorithm properties must
be set.
Pkcs7Signature = false, NullSigned = false, AlternateSignatureAlgorithm = false
This case retrieves a discrete signature algorithm OID for a PKCS #7 request. The HashAlgorithm and
PublicKeyAlgorithm properties must be set.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509SignatureInformation
 IX509SignatureInformation::put_AlternateSignatureAlgorithm
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The AlternateSignatureAlgorithm property specifies and retrieves a Boolean value that specifies whether the
GetSignatureAlgorithm method should retrieve a discrete or combined algorithm object identifier (OID) for a
PKCS #10 certificate request.
This property is read/write.

Syntax
HRESULT put_AlternateSignatureAlgorithm(
VARIANT_BOOL Value
);

Parameters
Value

Return value
None

Remarks
PKCS #7 and CMC certificate requests always use a discrete signature algorithm OID and a separate hashing
algorithm OID. Only PKCS #10 certificate requests use combined algorithm OIDs. You can set the
AlternateSignatureAlgorithm property to retrieve a discrete signature algorithm OID from the
GetSignatureAlgorithm method for a PKCS #10 request. If you set this property, the hashing algorithm OID can
be retrieved from the Parameters property, and the AlternateSignatureAlgorithmSet property is also set. For
examples of discrete and combined OIDs, see IX509SignatureInformation

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509SignatureInformation
 IX509SignatureInformation::put_HashAlgorithm
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The HashAlgorithm property specifies and retrieves an object identifier (OID) for the hashing algorithm used
in the GetSignatureAlgorithm method.
This property is read/write.

Syntax
HRESULT put_HashAlgorithm(
IObjectId *pValue
);

Parameters
pValue

Return value
None

Remarks
You must set this property before calling the GetSignatureAlgorithm method. You must also set the
PublicKeyAlgorithm property unless you are retrieving a signature algorithm for a null-signed certificate
request. You can also set the NullSigned, AlternateSignatureAlgorithm, and Parameters properties.
The HashAlgorithm property validates whether the OID you specify represents a hashing algorithm. If the OID
is valid, the property also clears the signature property cache.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509SignatureInformation
 IX509SignatureInformation::put_NullSigned method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The NullSigned property specifies and retrieves a Boolean value that indicates whether the certificate request
is null-signed.
This property is read/write.

Syntax
HRESULT put_NullSigned(
VARIANT_BOOL Value
);

Parameters
Value

Return value
None

Remarks
A null-signed certificate request is not really signed. That is, the request can be digested by using a digest
algorithm such as SHA-1, but it is not encrypted with a public key algorithm such as RSA. You must set this
property before calling the GetSignatureAlgorithm method.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509SignatureInformation
 IX509SignatureInformation::put_Parameters method
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Parameters property retrieves a byte array that contains the parameters associated with the signature
algorithm. The byte array is represented by a Unicode-encoded string.
This property is read/write.

Syntax
HRESULT put_Parameters(
EncodingType Encoding,
BSTR Value
);

Parameters
Encoding

Value

Return value
None

Remarks
The AlgorithmIdentifier ASN.1 object that is used in various fields of an X.509 version 3 certificate contains an
algorithm object identifier (OID) and optional parameters.

AlgorithmIdentifier ::= SEQUENCE

{
algorithm OBJECT IDENTIFIER,
parameters ANY DEFINED BY algorithm OPTIONAL
}

The format and content of the parameters differs by algorithm. The Certificate Enrollment Control generates
parameter information as required. Parameter values generated for various algorithms are discussed in the
following sections.
PKCS #1 version 1.5 signature algorithms:
The following OIDs must have a NULL parameter value.
XCN_OID_RSA_MD2RSA (1.2.840.113549.1.1.2)
XCN_OID_RSA_MD5RSA (1.2.840.113549.1.1.4)
XCN_OID_RSA_SHA1RSA (1.2.840.113549.1.1.5)
XCN_OID_RSA_SHA256RSA (1.2.840.113549.1.1.11)
 XCN_OID_RSA_SHA384RSA (1.2.840.113549.1.1.12)
XCN_OID_RSA_SHA512RSA (1.2.840.113549.1.1.13)
The ASN.1 NULL value is represented by two bytes. The tag number is 0x05 and the value associated with the
tag, representing the parameter length, is 0x00. This is shown by the following certificate example.

...
Public Key Algorithm:
Algorithm ObjectId: 1.2.840.113549.1.1.1 RSA (RSA_SIGN)
Algorithm Parameters:
05 00
...

RSASSA-PSS signatures:
The RSASSA-PSS (RSA Signature Scheme with Appendix - Probabilistic Signature Scheme),
XCN_OID_RSA_SSA_PSS (1.2.840.113549.1.1.10), generates the following parameter information. A signature
scheme with appendix consists of signature generation and signature verification operations. Verification of the
signature requires the original certificate request on which the signature was generated. For more information,
see the PKCS #1 v2.1 cryptography standard from RSA laboratories.

RSASSA-PSS-params ::= SEQUENCE

{
hashAlgorithm [0] HashAlgorithm DEFAULT sha1,
maskGenAlgorithm [1] MaskGenAlgorithm DEFAULT mgf1SHA1,
saltLength [2] INTEGER DEFAULT 20,
trailerField [3] TrailerField DEFAULT trailerFieldBC
}

ECDSA-SHA1 signature algorithms: When the XCN_OID_ECDSA_SHA1 (1.2.840.10045.4.1) is used to

create a signature, the parameters contains the OID of the hash algorithm. The following OIDs are supported:
XCN_OID_ECDSA_SHA256 (1.2.840.10045.4.3.2)
XCN_OID_ECDSA_SHA384 (1.2.840.10045.4.3.3)
XCN_OID_ECDSA_SHA512 (1.2.840.10045.4.3.4)

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll
See also
IX509SignatureInformation
 IX509SignatureInformation::put_PublicKeyAlgorithm
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The PublicKeyAlgorithm property specifies and retrieves an object identifier (OID) for the public key
algorithm used in the GetSignatureAlgorithm method.
This property is read/write.

Syntax
HRESULT put_PublicKeyAlgorithm(
IObjectId *pValue
);

Parameters
pValue

Return value
None

Remarks
Unless you are retrieving a signature algorithm for a null-signed certificate request, you must set this property
before calling the GetSignatureAlgorithm method. You must also set the HashAlgorithm property. You can also
set the AlternateSignatureAlgorithm and NullSigned properties.
The PublicKeyAlgorithm property validates whether the OID you specify represents a public key algorithm. If
the OID is valid, the property also clears the signature property cache.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509SignatureInformation
 IX509SignatureInformation::SetDefaultValues
method (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The SetDefaultValues method specifies a default hashing algorithm used to create a digest of the certificate
request prior to signing.

Syntax
HRESULT SetDefaultValues();

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. Possible values include, but are not
limited to, those in the following table. For a list of common error codes, see Common HRESULT Values.

RET URN C O DE/ VA L UE DESC RIP T IO N

The hashing algorithm OID could not be found.

CERTSRV_E_PROPERTY_EMPTY

Remarks
If the hash algorithm is already set, this method performs no action. If the hash algorithm has not been
specified, this method sets it to XCN_OID_OIWSEC_sha1 and clears the signature algorithm cache.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header certenroll.h

DLL CertEnroll.dll

See also
IX509SignatureInformation
 KeyIdentifierHashAlgorithm enumeration
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The KeyIdentifierHashAlgorithm enumeration type specifies the algorithm used to hash the public key in a
certificate request. This enumeration is used by the ComputeKeyIdentifier method on the IX509PublicKey
interface, and the key identifier can be used to initialize the IX509ExtensionSubjectKeyIdentifier and
IX509ExtensionAuthorityKeyIdentifier objects.

Syntax
typedef enum KeyIdentifierHashAlgorithm {
SKIHashDefault = 0,
SKIHashSha1 = 1,
SKIHashCapiSha1 = 2,
SKIHashSha256 = 3,
SKIHashHPKP = 5
} ;

Constants

SKIHashDefault
Value: 0
The default hash algorithm. This is redundant with the SKIHashSha1 value.

SKIHashSha1
Value: 1
A 160-bit SHA-1 hash of a Distinguished Encoding Rules (DER) encoded public key, excluding the tag, length, and number of
unused bits.

SKIHashCapiSha1
Value: 2
A 160-bit SHA-1 hash of a DER-encoded public key, including the tag, length, and number of unused bits.

SKIHashSha256
Value: 3
A 256-bit SHA256 (SHA-2) hash of a DER-encoded public key, including the tag, length, and number of unused bits.

SKIHashHPKP
Value: 5

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

 Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Header certenroll.h

See also
CertEnroll Enumerations
CertEnroll Interfaces
ComputeKeyIdentifier
IX509ExtensionAuthorityKeyIdentifier
IX509ExtensionSubjectKeyIdentifier
IX509PublicKey
 ObjectIdGroupId enumeration (certenroll.h)
7/2/2022 • 4 minutes to read • Edit Online

The ObjectIdGroupId enumeration type specifies the category or group to which an object identifier (OID)
belongs. This enumeration is used when calling InitializeFromAlgorithmName to initialize an IObjectId object.

Syntax
typedef enum ObjectIdGroupId {
XCN_CRYPT_ANY_GROUP_ID = 0,
XCN_CRYPT_HASH_ALG_OID_GROUP_ID = 1,
XCN_CRYPT_ENCRYPT_ALG_OID_GROUP_ID = 2,
XCN_CRYPT_PUBKEY_ALG_OID_GROUP_ID = 3,
XCN_CRYPT_SIGN_ALG_OID_GROUP_ID = 4,
XCN_CRYPT_RDN_ATTR_OID_GROUP_ID = 5,
XCN_CRYPT_EXT_OR_ATTR_OID_GROUP_ID = 6,
XCN_CRYPT_ENHKEY_USAGE_OID_GROUP_ID = 7,
XCN_CRYPT_POLICY_OID_GROUP_ID = 8,
XCN_CRYPT_TEMPLATE_OID_GROUP_ID = 9,
XCN_CRYPT_KDF_OID_GROUP_ID = 10,
XCN_CRYPT_LAST_OID_GROUP_ID = 10,
XCN_CRYPT_FIRST_ALG_OID_GROUP_ID = 1,
XCN_CRYPT_LAST_ALG_OID_GROUP_ID = 4,
XCN_CRYPT_GROUP_ID_MASK = 0xffff,
XCN_CRYPT_OID_PREFER_CNG_ALGID_FLAG = 0x40000000,
XCN_CRYPT_OID_DISABLE_SEARCH_DS_FLAG = 0x80000000,
XCN_CRYPT_OID_INFO_OID_GROUP_BIT_LEN_MASK = 0xfff0000,
XCN_CRYPT_OID_INFO_OID_GROUP_BIT_LEN_SHIFT = 16,
XCN_CRYPT_KEY_LENGTH_MASK = 0xfff0000
} ;

Constants

XCN_CRYPT_ANY_GROUP_ID
Value: 0
The group OID is not identified. All OID groups will be included when searching.

XCN_CRYPT_HASH_ALG_OID_GROUP_ID
Value: 1
Hashing algorithm group. This includes the following OIDs:

XCN_OID_OIWSEC_sha (1.3.14.3.2.18)

XCN_OID_OIWSEC_sha1 (1.3.14.3.2.26)

XCN_OID_RSA_MD2 (1.2.840.113549.2.2)

XCN_OID_RSA_MD4 (1.2.840.113549.2.4)

XCN_OID_RSA_MD5 (1.2.840.113549.2.5)
XCN_CRYPT_ENCRYPT_ALG_OID_GROUP_ID
Value: 2
Symmetric encryption algorithm group. This includes the following OIDs:

XCN_OID_NIST_AES128_CBC (2.16.840.1.101.3.4.1.2)

XCN_OID_NIST_AES192_CBC (2.16.840.1.101.3.4.1.22)

XCN_OID_NIST_AES256_CBC (2.16.840.1.101.3.4.1.42)

XCN_OID_NIST_AES128_WRAP (2.16.840.1.101.3.4.1.5)

XCN_OID_NIST_AES192_WRAP (2.16.840.1.101.3.4.1.25)

XCN_OID_NIST_AES256_WRAP (2.16.840.1.101.3.4.1.45)

XCN_OID_OIWSEC_desCBC (1.3.14.3.2.7)

XCN_OID_RSA_DES_EDE3_CBC (1.2.840.113549.3.7)

XCN_OID_RSA_RC2CBC (1.2.840.113549.3.2)

XCN_OID_RSA_RC4 (1.2.840.113549.3.4)

XCN_OID_RSA_SMIMEalgCMS3DESwrap (1.2.840.113549.1.9.16.3.6)

XCN_OID_RSA_SMIMEalgCMSRC2wrap (1.2.840.113549.1.9.16.3.7)
XCN_CRYPT_PUBKEY_ALG_OID_GROUP_ID
Value: 3
Asymmetric encryption algorithm group. This includes the following OIDs:

XCN_OID_ANSI_X942_DH (1.2.840.10046.2.1)

XCN_OID_DH_SINGLE_PASS_STDDH_SHA1_KDF (1.3.133.16.840.63.0.2)

XCN_OID_ECC_CURVE_P256 (1.2.840.10045.3.1.7)

XCN_OID_ECC_CURVE_P384 (1.3.132.0.34)

XCN_OID_ECC_CURVE_P521 (1.3.132.0.35)

XCN_OID_ECC_PUBLIC_KEY (1.2.840.10045.2.1)

XCN_OID_INFOSEC_mosaicKMandUpdSig (2.16.840.1.101.2.1.1.20)

XCN_OID_OIWSEC_dsa (1.3.14.3.2.12)

XCN_OID_OIWSEC_rsaXchg (1.3.14.3.2.22)

XCN_OID_PKIX_NO_SIGNATURE (1.3.6.1.5.5.7.6.2)

XCN_OID_RSA_DH (1.2.840.113549.1.3.1)

XCN_OID_RSA_RSA (1.2.840.113549.1.1.1)

XCN_OID_RSA_SMIMEalgESDH (1.2.840.113549.1.9.16.3.5)

XCN_OID_RSAES_OAEP (1.2.840.113549.1.1.7)

XCN_OID_X957_DSA (1.2.840.10040.4.1)
XCN_CRYPT_SIGN_ALG_OID_GROUP_ID
Value: 4
Signing algorithm group. This includes the following OIDs:

XCN_OID_ECDSA_SHA1 (1.2.840.10045.4.1)

XCN_OID_ECDSA_SHA256 (1.2.840.10045.4.3.2)

XCN_OID_ECDSA_SHA384 (1.2.840.10045.4.3.3)

XCN_OID_ECDSA_SHA512 (1.2.840.10045.4.3.4)

XCN_OID_ECDSA_SPECIFIED (1.2.840.10045.4.3)

XCN_OID_INFOSEC_mosaicUpdatedSig (2.16.840.1.101.2.1.1.19)

XCN_OID_NIST_sha256 (2.16.840.1.101.3.4.2.1)

XCN_OID_NIST_sha384 (2.16.840.1.101.3.4.2.2)

XCN_OID_NIST_sha512 (2.16.840.1.101.3.4.2.3)

XCN_OID_OIWDIR_md2RSA (1.3.14.7.2.3.1)

XCN_OID_OIWSEC_dsaSHA1 (1.3.14.3.2.27)

XCN_OID_OIWSEC_md4RSA (1.3.14.3.2.2)

XCN_OID_OIWSEC_md4RSA2 (1.3.14.3.2.4)

XCN_OID_OIWSEC_md5RSA (1.3.14.3.2.3)

XCN_OID_OIWSEC_sha1 (1.3.14.3.2.26)

XCN_OID_OIWSEC_sha1RSASign (1.3.14.3.2.29)

XCN_OID_OIWSEC_shaDSA (1.3.14.3.2.13)

XCN_OID_OIWSEC_shaRSA (1.3.14.3.2.15)

XCN_OID_RSA_MD2RSA (1.2.840.113549.1.1.2)

XCN_OID_RSA_MD4RSA (1.2.840.113549.1.1.3)

XCN_OID_RSA_MD5 (1.2.840.113549.2.5)

XCN_OID_RSA_MD5RSA (1.2.840.113549.1.1.4)

XCN_OID_RSA_SHA1RSA (1.2.840.113549.1.1.5)

XCN_OID_RSA_SHA256RSA (1.2.840.113549.1.1.11)

XCN_OID_RSA_SHA384RSA (1.2.840.113549.1.1.12)

XCN_OID_RSA_SHA512RSA (1.2.840.113549.1.1.13)

XCN_OID_RSA_SSA_PSS (1.2.840.113549.1.1.10)

XCN_OID_X957_SHA1DSA (1.2.840.10040.4.3)
XCN_CRYPT_RDN_ATTR_OID_GROUP_ID
Value: 5
Relative distinguished name (RDN) group. This includes the following OIDs:

XCN_OID_COMMON_NAME (2.5.4.3)

XCN_OID_LOCALITY_NAME (2.5.4.7)

XCN_OID_ORGANIZATION_NAME (2.5.4.10)

XCN_OID_ORGANIZATIONAL_UNIT_NAME (2.5.4.11)

XCN_OID_RSA_emailAddr (1.2.840.113549.1.9.1)

XCN_OID_COUNTRY_NAME (2.5.4.6)

XCN_OID_STATE_OR_PROVINCE_NAME (2.5.4.8)

XCN_OID_STREET_ADDRESS (2.5.4.9)

XCN_OID_TITLE (2.5.4.12)

XCN_OID_GIVEN_NAME (2.5.4.42)

XCN_OID_INITIALS (2.5.4.43)

XCN_OID_SUR_NAME (2.5.4.4)

XCN_OID_DEVICE_SERIAL_NUMBER (2.5.4.5)

XCN_OID_DOMAIN_COMPONENT (0.9.2342.19200300.100.1.25)

XCN_OID_DESCRIPTION (2.5.4.13)

XCN_OID_POSTAL_CODE (2.5.4.17)

XCN_OID_POST_OFFICE_BOX (2.5.4.18)

XCN_OID_TELEPHONE_NUMBER (2.5.4.20)

XCN_OID_X21_ADDRESS (2.5.4.24)

XCN_OID_DN_QUALIFIER (2.5.4.46)

XCN_CRYPT_EXT_OR_ATTR_OID_GROUP_ID
Value: 6
Extension and attribute group. This includes the following OIDs:

XCN_OID_CTL (1.3.6.1.4.1.311.10.1)

XCN_OID_CMC_ADD_ATTRIBUTES (1.3.6.1.4.1.311.10.10.1)

XCN_OID_NEXT_UPDATE_LOCATION (1.3.6.1.4.1.311.10.2)

XCN_OID_SERIALIZED (1.3.6.1.4.1.311.10.3.3.1)

XCN_OID_YESNO_TRUST_ATTR (1.3.6.1.4.1.311.10.4.1)
XCN_OID_CROSS_CERT_DIST_POINTS (1.3.6.1.4.1.311.10.9.1)

XCN_OID_ENROLLMENT_NAME_VALUE_PAIR (1.3.6.1.4.1.311.13.2.1)

XCN_OID_ENROLLMENT_CSP_PROVIDER (1.3.6.1.4.1.311.13.2.2)

XCN_OID_OS_VERSION (1.3.6.1.4.1.311.13.2.3)

XCN_OID_CERT_EXTENSIONS (1.3.6.1.4.1.311.2.1.14)

XCN_OID_ENROLL_CERTTYPE_EXTENSION (1.3.6.1.4.1.311.20.2)

XCN_OID_NT_PRINCIPAL_NAME (1.3.6.1.4.1.311.20.2.3)

XCN_OID_CERT_MANIFOLD (1.3.6.1.4.1.311.20.3)

XCN_OID_CERTSRV_CA_VERSION (1.3.6.1.4.1.311.21.1)

XCN_OID_APPLICATION_CERT_POLICIES (1.3.6.1.4.1.311.21.10)

XCN_OID_APPLICATION_POLICY_MAPPINGS (1.3.6.1.4.1.311.21.11)

XCN_OID_APPLICATION_POLICY_CONSTRAINTS (1.3.6.1.4.1.311.21.12)

XCN_OID_ARCHIVED_KEY_ATTR (1.3.6.1.4.1.311.21.13)

XCN_OID_CRL_SELF_CDP (1.3.6.1.4.1.311.21.14)

XCN_OID_REQUIRE_CERT_CHAIN_POLICY (1.3.6.1.4.1.311.21.15)

XCN_OID_ARCHIVED_KEY_CERT_HASH (1.3.6.1.4.1.311.21.16)

XCN_OID_CERTSRV_PREVIOUS_CERT_HASH (1.3.6.1.4.1.311.21.2)

XCN_OID_REQUEST_CLIENT_INFO (1.3.6.1.4.1.311.21.20)

XCN_OID_CERTSRV_CROSSCA_VERSION (1.3.6.1.4.1.311.21.22)

XCN_OID_CRL_VIRTUAL_BASE (1.3.6.1.4.1.311.21.3)

XCN_OID_CRL_NEXT_PUBLISH (1.3.6.1.4.1.311.21.4)

XCN_OID_KP_CA_EXCHANGE (1.3.6.1.4.1.311.21.5)

XCN_OID_KP_KEY_RECOVERY_AGENT (1.3.6.1.4.1.311.21.6)

XCN_OID_KP_KEY_RECOVERY_AGENT (1.3.6.1.4.1.311.21.7)

XCN_OID_ENTERPRISE_OID_ROOT (1.3.6.1.4.1.311.21.8)

XCN_OID_RDN_DUMMY_SIGNER (1.3.6.1.4.1.311.21.9)

XCN_OID_PRODUCT_UPDATE (1.3.6.1.4.1.311.31.1)

XCN_OID_AUTHORITY_INFO_ACCESS (1.3.6.1.5.5.7.1.1)

XCN_OID_LOGOTYPE_EXT (1.3.6.1.5.5.7.1.12)

XCN_OID_BIOMETRIC_EXT (1.3.6.1.5.5.7.1.2)

XCN_OID_CT_PKI_DATA (1.3.6.1.5.5.7.12.2)
XCN_OID_CT_PKI_RESPONSE (1.3.6.1.5.5.7.12.3)

XCN_OID_PKIX_POLICY_QUALIFIER_CPS (1.3.6.1.5.5.7.2.1)

XCN_OID_PKIX_POLICY_QUALIFIER_USERNOTICE (1.3.6.1.5.5.7.2.2)

XCN_OID_PKIX_OCSP (1.3.6.1.5.5.7.48.1)

XCN_OID_PKIX_OCSP_NOCHECK (1.3.6.1.5.5.7.48.1.5)

XCN_OID_PKIX_CA_ISSUERS (1.3.6.1.5.5.7.48.2)

XCN_OID_CMC (1.3.6.1.5.5.7.7)

XCN_OID_CMC_STATUS_INFO (1.3.6.1.5.5.7.7.1)

XCN_OID_CMC_GET_CERT (1.3.6.1.5.5.7.7.15)

XCN_OID_CMC_GET_CRL (1.3.6.1.5.5.7.7.16)

XCN_OID_CMC_REVOKE_REQUEST (1.3.6.1.5.5.7.7.17)

XCN_OID_CMC_REG_INFO (1.3.6.1.5.5.7.7.18)

XCN_OID_CMC_QUERY_PENDING (1.3.6.1.5.5.7.7.21)

XCN_OID_CMC_TRANSACTION_ID (1.3.6.1.5.5.7.7.5)

XCN_OID_CMC_SENDER_NONCE (1.3.6.1.5.5.7.7.6)

XCN_OID_CMC_RECIPIENT_NONCE (1.3.6.1.5.5.7.7.7)

XCN_OID_CMC_ADD_EXTENSIONS (1.3.6.1.5.5.7.7.8)

XCN_OID_AUTHORITY_KEY_IDENTIFIER (2.5.29.1)

XCN_OID_BASIC_CONSTRAINTS (2.5.29.10)

XCN_OID_SUBJECT_KEY_IDENTIFIER (2.5.29.14)

XCN_OID_KEY_USAGE (2.5.29.15)

XCN_OID_PRIVATEKEY_USAGE_PERIOD (2.5.29.16)

XCN_OID_SUBJECT_ALT_NAME2 (2.5.29.17)

XCN_OID_ISSUER_ALT_NAME2 (2.5.29.18)

XCN_OID_BASIC_CONSTRAINTS2 (2.5.29.19)

XCN_OID_KEY_ATTRIBUTES (2.5.29.2)

XCN_OID_CRL_NUMBER (2.5.29.20)

XCN_OID_CRL_REASON_CODE (2.5.29.21)

XCN_OID_DELTA_CRL_INDICATOR (2.5.29.27)

XCN_OID_ISSUING_DIST_POINT (2.5.29.28)

XCN_OID_NAME_CONSTRAINTS (2.5.29.30)
 XCN_OID_CRL_DIST_POINTS (2.5.29.31)

XCN_OID_CERT_POLICIES (2.5.29.32)

XCN_OID_POLICY_MAPPINGS (2.5.29.33)

XCN_OID_AUTHORITY_KEY_IDENTIFIER2 (2.5.29.35)

XCN_OID_POLICY_CONSTRAINTS (2.5.29.36)

XCN_OID_ENHANCED_KEY_USAGE (2.5.29.37)

XCN_OID_KEY_USAGE_RESTRICTION (2.5.29.4)

XCN_OID_FRESHEST_CRL (2.5.29.46)

XCN_OID_LEGACY_POLICY_MAPPINGS (2.5.29.5)

XCN_OID_SUBJECT_ALT_NAME (2.5.29.7)

XCN_OID_ISSUER_ALT_NAME (2.5.29.8)

XCN_OID_ORGANIZATION_NAME (2.5.4.10)

XCN_OID_ORGANIZATIONAL_UNIT_NAME (2.5.4.11)

XCN_OID_TITLE (2.5.4.12)

XCN_OID_COMMON_NAME (2.5.4.3)

XCN_OID_SUR_NAME (2.5.4.4)

XCN_OID_GIVEN_NAME (2.5.4.42)

XCN_OID_INITIALS (2.5.4.43)

XCN_OID_DEVICE_SERIAL_NUMBER (2.5.4.5)

XCN_OID_COUNTRY_NAME (2.5.4.6)

XCN_OID_LOCALITY_NAME (2.5.4.7)

XCN_OID_STATE_OR_PROVINCE_NAME (2.5.4.8)

XCN_OID_STREET_ADDRESS (2.5.4.9)

XCN_CRYPT_ENHKEY_USAGE_OID_GROUP_ID
Value: 7
Enhanced key usage (EKU) extension group. This includes the following OIDs:

XCN_OID_PKIX_KP_SERVER_AUTH (1.3.6.1.5.5.7.3.1)

XCN_OID_PKIX_KP_CLIENT_AUTH (1.3.6.1.5.5.7.3.2)

XCN_OID_PKIX_KP_CODE_SIGNING (1.3.6.1.5.5.7.3.3)

XCN_OID_PKIX_KP_EMAIL_PROTECTION (1.3.6.1.5.5.7.3.4)

XCN_OID_PKIX_KP_TIMESTAMP_SIGNING (1.3.6.1.5.5.7.3.8)
XCN_OID_KP_CTL_USAGE_SIGNING (1.3.6.1.4.1.311.10.3.1)

XCN_OID_KP_TIME_STAMP_SIGNING (1.3.6.1.4.1.311.10.3.2)

XCN_OID_PKIX_KP_IPSEC_END_SYSTEM (1.3.6.1.5.5.7.3.5)

XCN_OID_PKIX_KP_IPSEC_TUNNEL (1.3.6.1.5.5.7.3.6)

XCN_OID_PKIX_KP_IPSEC_USER (1.3.6.1.5.5.7.3.7)

XCN_OID_KP_EFS (1.3.6.1.4.1.311.10.3.4)

XCN_OID_WHQL_CRYPTO (1.3.6.1.4.1.311.10.3.5)

XCN_OID_NT5_CRYPTO (1.3.6.1.4.1.311.10.3.6)

XCN_OID_OEM_WHQL_CRYPTO (1.3.6.1.4.1.311.10.3.7)

XCN_OID_EMBEDDED_NT_CRYPTO (1.3.6.1.4.1.311.10.3.8)

XCN_OID_LICENSES (1.3.6.1.4.1.311.10.6.1)

XCN_OID_LICENSE_SERVER (1.3.6.1.4.1.311.10.6.2)

XCN_OID_KP_SMARTCARD_LOGON (1.3.6.1.4.1.311.20.2.2)

XCN_OID_DRM (1.3.6.1.4.1.311.10.5.1)

XCN_OID_KP_QUALIFIED_SUBORDINATION (1.3.6.1.4.1.311.10.3.10)

XCN_OID_KP_KEY_RECOVERY (1.3.6.1.4.1.311.10.3.11)

XCN_OID_KP_DOCUMENT_SIGNING (1.3.6.1.4.1.311.10.3.12)

XCN_OID_IPSEC_KP_IKE_INTERMEDIATE (1.3.6.1.5.5.8.2.2)

XCN_OID_EFS_RECOVERY (1.3.6.1.4.1.311.10.3.4.1)

XCN_OID_ROOT_LIST_SIGNER (1.3.6.1.4.1.311.10.3.9)

XCN_OID_ANY_APPLICATION_POLICY (1.3.6.1.4.1.311.10.12.1)

XCN_OID_DS_EMAIL_REPLICATION (1.3.6.1.4.1.311.21.19)

XCN_OID_ENROLLMENT_AGENT (1.3.6.1.4.1.311.20.2.1)

XCN_OID_KP_KEY_RECOVERY_AGENT (1.3.6.1.4.1.311.21.6)

XCN_OID_KP_CA_EXCHANGE (1.3.6.1.4.1.311.21.5)

XCN_OID_KP_LIFETIME_SIGNING (1.3.6.1.4.1.311.10.3.13)

XCN_OID_PKIX_KP_OCSP_SIGNING (1.3.6.1.5.5.7.3.9)
 XCN_CRYPT_POLICY_OID_GROUP_ID
Value: 8
Issuance policy group. This includes the following OIDs. The x.y.z portion of each OID represents a randomly generated
numeric sequence that is unique for each forest.

XCN_OID_ANY_CERT_POLICY (2.5.29.32.0)

Low Assurance (1.3.6.1.4.1.311.21.8.x.y.z.1.400)

Medium Assurance (1.3.6.1.4.1.311.21.8.x.y.z.1.401)

High Assurance (1.3.6.1.4.1.311.21.8.x.y.z.1.402)

XCN_CRYPT_TEMPLATE_OID_GROUP_ID
Value: 9
Certificate template group. The OIDs in this group identify the certificate templates that are available to the client, and all
begin with 1.3.6.1.4.1.311.21.8. but are completed by randomly generated numeric sequences that are unique for each forest.

XCN_CRYPT_KDF_OID_GROUP_ID
Value: 10

XCN_CRYPT_LAST_OID_GROUP_ID
Value: 10
Equivalent to XCN_CRYPT_TEMPLATE_OID_GROUP_ID. You can use this value to iterate through the group OIDs.

XCN_CRYPT_FIRST_ALG_OID_GROUP_ID
Value: 1
Equivalent to XCN_CRYPT_HASH_ALG_OID_GROUP_ID. You can use this value to iterate through the group algorithm OIDs.

XCN_CRYPT_LAST_ALG_OID_GROUP_ID
Value: 4
Equivalent to XCN_CRYPT_SIGN_ALG_OID_GROUP_ID. You can use this value to iterate through the group algorithm OIDs.

XCN_CRYPT_GROUP_ID_MASK
Value: 0xffff

XCN_CRYPT_OID_PREFER_CNG_ALGID_FLAG
Value: 0x40000000

XCN_CRYPT_OID_DISABLE_SEARCH_DS_FLAG
Value: 0x80000000
Not supported.

XCN_CRYPT_OID_INFO_OID_GROUP_BIT_LEN_MASK
Value: 0xfff0000

XCN_CRYPT_OID_INFO_OID_GROUP_BIT_LEN_SHIFT
Value: 16
 XCN_CRYPT_KEY_LENGTH_MASK
Value: 0xfff0000
Enables addition of a key length to the upper 16 bits of the XCN_CRYPT_ENCRYPT_ALG_OID_GROUP_ID group ID. For
example, to use the InitializeFromAlgorithmName method to initialize an IObjectId object from a 192-bit AES algorithm,
specify "AES" for the strAlgorithmName parameter, shift the length left by 16, and perform a bitwise-OR combination on the
shifted bit length and the GroupId value.

syntax<br>DWORD dwBitLen = 192;<br><br>ObjectIdGroupId GroupId = <br> (ObjectIdGroupId)

(XCN_CRYPT_ENCRYPT_ALG_OID_GROUP_ID | <br> (XCN_CRYPT_KEY_LENGTH_MASK &amp; (dwBitLen &lt;&lt; 16)));<br>
<br>

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Header certenroll.h

See also
CertEnroll Enumerations
 ObjectIdPublicKeyFlags enumeration (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The ObjectIdPublicKeyFlags enumeration type specifies whether a public key algorithm is used for signing or
for encryption. Some algorithms, such as RSA, can be used for both purposes. This enumeration is used by the
InitializeFromAlgorithmName method on the IObjectId interface to narrow and disambiguate the algorithm
search.

Syntax
typedef enum ObjectIdPublicKeyFlags {
XCN_CRYPT_OID_INFO_PUBKEY_ANY = 0,
XCN_CRYPT_OID_INFO_PUBKEY_SIGN_KEY_FLAG = 0x80000000,
XCN_CRYPT_OID_INFO_PUBKEY_ENCRYPT_KEY_FLAG = 0x40000000
} ;

Constants

XCN_CRYPT_OID_INFO_PUBKEY_ANY
Value: 0
The algorithm can be used for signing or encryption.

XCN_CRYPT_OID_INFO_PUBKEY_SIGN_KEY_FLAG
Value: 0x80000000
The algorithm is used for signing.

XCN_CRYPT_OID_INFO_PUBKEY_ENCRYPT_KEY_FLAG
Value: 0x40000000
The algorithm is used for encryption.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Header certenroll.h

See also
CertEnroll Enumerations
InitializeFromAlgorithmName
 PFXExportOptions enumeration (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The PFXExpor tOptions enumeration specifies how much of a certificate chain is included when creating a
Personal Information Exchange (PFX) message. The PFX message syntax is defined by the PKCS #12 standard.
PFX is a transfer syntax for personal identity information, including private keys and certificates. The
enumeration is used by the CreatePFX method on the IX509Enrollment interface.

Syntax
typedef enum PFXExportOptions {
PFXExportEEOnly = 0,
PFXExportChainNoRoot = 1,
PFXExportChainWithRoot = 2
} ;

Constants

PFXExportEEOnly
Value: 0
Includes only the end entity certificate.

PFXExportChainNoRoot
Value: 1
Includes the certificate chain without the root certification authority certificate.

PFXExportChainWithRoot
Value: 2
Includes the entire certificate chain, including the root certification authority certificate.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Header certenroll.h

See also
CertEnroll Enumerations
CertEnroll Interfaces
CreatePFX
 Pkcs10AllowedSignatureTypes enumeration
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The Pkcs10AllowedSignatureTypes enumeration type specifies the type of signature permitted when signing
a certificate request. This enumeration is used by the CheckSignature method on the
IX509CertificateRequestPkcs10 interface to determine whether a signature exists and is valid.

Syntax
typedef enum Pkcs10AllowedSignatureTypes {
AllowedKeySignature = 0x1,
AllowedNullSignature = 0x2
} ;

Constants

AllowedKeySignature
Value: 0x1
Signatures generated by using cryptographic keys are allowed.

AllowedNullSignature
Value: 0x2
Null signatures are allowed. A null signature is a SHA-1 hash.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Header certenroll.h

See also
CertEnroll Enumerations
CertEnroll Interfaces
CheckSignature
 PolicyQualifierType enumeration (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The PolicyQualifierType enumeration type specifies the type of qualifier applied to a certificate policy. This
enumeration is used by the InitializeEncode method and the Type property on the IPolicyQualifier interface.

Syntax
typedef enum PolicyQualifierType {
PolicyQualifierTypeUnknown = 0,
PolicyQualifierTypeUrl = 1,
PolicyQualifierTypeUserNotice = 2,
PolicyQualifierTypeFlags = 3
} ;

Constants

PolicyQualifierTypeUnknown
Value: 0
The qualifier type is not specified.

PolicyQualifierTypeUrl
Value: 1
The qualifier is a URL that points to a Certification Practice Statement (CPS) that has been defined by the certification authority
to outline the policies under which the certificate was issued and the purposes for which the certificate can be used.

PolicyQualifierTypeUserNotice
Value: 2
The qualifier is a text statement to be displayed by the application to any user who relies on the certificate. The user notice
identifies the permitted uses of the certificate.

PolicyQualifierTypeFlags
Value: 3

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Header certenroll.h

See also
CertEnroll Enumerations
IPolicyQualifier
IPolicyQualifiers
IX509ExtensionCertificatePolicies
 PolicyServerUrlFlags enumeration (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The PolicySer verUrlFlags enumeration contains certificate enrollment policy (CEP) server flags. It is used by
the Initialize method on the ICertPropertyEnrollmentPolicyServer interface.

Syntax
typedef enum PolicyServerUrlFlags {
PsfNone = 0,
PsfLocationGroupPolicy = 1,
PsfLocationRegistry = 2,
PsfUseClientId = 4,
PsfAutoEnrollmentEnabled = 16,
PsfAllowUnTrustedCA = 32
} ;

Constants

PsfNone
Value: 0
No flags are specified.

PsfLocationGroupPolicy
Value: 1
Policy information is specified in group policy by an administrator.

PsfLocationRegistry
Value: 2
Policy information is specified in the registry.

PsfUseClientId
Value: 4
Specifies that certificate enrollments and renewals include client specific data in a ClientId attribute. Examples include the
name of the cryptographic service provider, the Windows version number, the user name, the computer DNS name, and the
domain controller DNS name. This flag can be set by group policy.

This flag has been included to address privacy concerns that can arise during enrollment to servers that are managed by
administrators other than those who manage the forest in which the user resides. By not setting this flag, you can prevent
sending personal information to non-local administrators.

PsfAutoEnrollmentEnabled
Value: 16
Automatic certificate enrollment is enabled.

PsfAllowUnTrustedCA
Value: 32
Specifies that the certificate of the issuing CA need not be trusted by the client to install a certificate signed by the CA.
Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Header certenroll.h

See also
ICertPropertyEnrollmentPolicyServer
Initialize
 PolicyServerUrlPropertyID enumeration
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The PolicySer verUrlProper tyID enumeration contains values that specify the type of property value to be
returned by the GetStringProperty method or set by the SetStringProperty method on the IX509PolicyServerUrl
interface.

Syntax
typedef enum PolicyServerUrlPropertyID {
PsPolicyID = 0,
PsFriendlyName = 1
} ;

Constants

PsPolicyID
Value: 0
Specify or retrieve an ID for the policy server.

PsFriendlyName
Value: 1
Specify or retrieve a display name for the policy server.

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Header certenroll.h

See also
GetStringProperty
SetStringProperty
 RequestClientInfoClientId enumeration (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The RequestClientInfoClientId enumeration specifies the type of application that created a certificate request.
This can be used to initialize a IX509AttributeClientId object that contains information about the client. It is also
used by the IX509CertificateRequest interface.

Syntax
typedef enum RequestClientInfoClientId {
ClientIdNone = 0,
ClientIdXEnroll2003 = 1,
ClientIdAutoEnroll2003 = 2,
ClientIdWizard2003 = 3,
ClientIdCertReq2003 = 4,
ClientIdDefaultRequest = 5,
ClientIdAutoEnroll = 6,
ClientIdRequestWizard = 7,
ClientIdEOBO = 8,
ClientIdCertReq = 9,
ClientIdTest = 10,
ClientIdWinRT = 11,
ClientIdUserStart = 1000
} ;

Constants

ClientIdNone
Value: 0
No client identifier is specified.

ClientIdXEnroll2003
Value: 1
Specifies the Certificate Enrollment Control that is available on Windows Server 2003.

ClientIdAutoEnroll2003
Value: 2
Specifies the autoenrollment that is available on Windows Server 2003.

ClientIdWizard2003
Value: 3
Specifies the Certificate Request Wizard that is available on Windows Server 2003.

ClientIdCertReq2003
Value: 4
Specifies the Certreq.exe command-line tool that is available on Windows Server 2003.
 ClientIdDefaultRequest
Value: 5
Specifies the default certificate request object that is available starting with Windows Vista. This is represented by the
IX509CertificateRequest interface and is the default value if the client ID is not set by the caller.

ClientIdAutoEnroll
Value: 6
Specifies the autoenrollment that is available starting with Windows Vista.

ClientIdRequestWizard
Value: 7
Specifies the Certificate Request Wizard that is available starting with Windows Vista.

ClientIdEOBO
Value: 8
Specifies the Enroll-On-Behalf-Of (EOBO) Wizard that is available starting with Windows Vista.

ClientIdCertReq
Value: 9
Specifies the Certreq.exe command-line tool that is available starting with Windows Vista.

ClientIdTest
Value: 10
This value is not supported.

ClientIdWinRT
Value: 11

ClientIdUserStart
Value: 1000
This is the base value for custom applications.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Header certenroll.h

See also
CertEnroll Enumerations
CertEnroll Interfaces
IX509AttributeClientId
IX509CertificateRequest
 WebEnrollmentFlags enumeration (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The WebEnrollmentFlags enumeration specifies web enrollment behavior. It is used by the Enroll method on
the IX509EnrollmentHelper interface.

Syntax
typedef enum WebEnrollmentFlags {
EnrollPrompt = 0x1
} ;

Constants

EnrollPrompt
Value: 0x1
If this flag is set and no authentication credential is available for the certificate enrollment server, the certificate service
prompts for a credential. If there is no authentication credential and this flag is not set, the Enroll method fails.

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Header certenroll.h

See also
Enroll
IX509EnrollmentHelper
 WebSecurityLevel enumeration (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The WebSecurityLevel enumeration type specifies whether a web-enabled method or property is safe for
scripting.

Syntax
typedef enum WebSecurityLevel {
LevelUnsafe = 0,
LevelSafe = 1
} ;

Constants

LevelUnsafe
Value: 0
The method is not safe for scripting.

LevelSafe
Value: 1
The method is safe for scripting.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Header certenroll.h

See also
CertEnroll Enumerations
CertEnroll Interfaces
 X500NameFlags enumeration (certenroll.h)
7/2/2022 • 3 minutes to read • Edit Online

The X500NameFlags enumeration type specifies the display and encoding characteristics of a distinguished
name or relative distinguished name (RDN). This enumeration is used to initialize an IX500DistinguishedName
object.

Syntax
typedef enum X500NameFlags {
XCN_CERT_NAME_STR_NONE = 0,
XCN_CERT_SIMPLE_NAME_STR = 1,
XCN_CERT_OID_NAME_STR = 2,
XCN_CERT_X500_NAME_STR = 3,
XCN_CERT_XML_NAME_STR = 4,
XCN_CERT_NAME_STR_SEMICOLON_FLAG = 0x40000000,
XCN_CERT_NAME_STR_NO_PLUS_FLAG = 0x20000000,
XCN_CERT_NAME_STR_NO_QUOTING_FLAG = 0x10000000,
XCN_CERT_NAME_STR_CRLF_FLAG = 0x8000000,
XCN_CERT_NAME_STR_COMMA_FLAG = 0x4000000,
XCN_CERT_NAME_STR_REVERSE_FLAG = 0x2000000,
XCN_CERT_NAME_STR_FORWARD_FLAG = 0x1000000,
XCN_CERT_NAME_STR_AMBIGUOUS_SEPARATOR_FLAGS,
XCN_CERT_NAME_STR_DISABLE_IE4_UTF8_FLAG = 0x10000,
XCN_CERT_NAME_STR_ENABLE_T61_UNICODE_FLAG = 0x20000,
XCN_CERT_NAME_STR_ENABLE_UTF8_UNICODE_FLAG = 0x40000,
XCN_CERT_NAME_STR_FORCE_UTF8_DIR_STR_FLAG = 0x80000,
XCN_CERT_NAME_STR_DISABLE_UTF8_DIR_STR_FLAG = 0x100000,
XCN_CERT_NAME_STR_ENABLE_PUNYCODE_FLAG = 0x200000,
XCN_CERT_NAME_STR_DS_ESCAPED = 0x800000
} ;

Constants

XCN_CERT_NAME_STR_NONE
Value: 0
Display characteristics are not identified.

XCN_CERT_SIMPLE_NAME_STR
Value: 1
All object identifiers (OIDs) are discarded. Relative distinguished names (RDNs) are separated by commas followed by a space (,
). RDN attributes are separated by a plus sign enclosed within spaces ( + ).

XCN_CERT_OID_NAME_STR
Value: 2
OIDs are separated from their associated attribute value by using an equal sign (=). RDNs are separated by a comma followed
by a space (, ). RDN attributes are separated by a plus sign followed by a space (+ ).
XCN_CERT_X500_NAME_STR
Value: 3
OIDs are converted to their X.500 key names. They are separated from their associated attribute value by using an equal sign
(=). RDNs are separated by a comma followed by a space (, ). RDN attributes are separated by a plus sign followed by a space
(+ ).

If an OID does not have a corresponding X.500 name, the OID is used with a prefix of OID. The RDN is enclosed within
quotation marks (" ") if it contains leading or trailing white space or one of the following characters:

Comma (,)

Plus sign (+)

Equal sign (=)

Inch mark (")

Line feed (\n)

Less than sign (<)

Greater than sign (>)

Number sign (#)

Semicolon (;)

Embedded quotation mark (")

XCN_CERT_XML_NAME_STR
Value: 4
OIDs are treated in the same manner as that used to convert XCN_CERT_X500_NAME_ST values except that they are
formatted as a sequence of XML elements. This is shown in the following example.

syntax<br><br>&lt;CN&gt;cart.contoso.com&lt;/CN&gt;<br>&lt;OU&gt;Terms of use at www.verisign.com/rpa

(c)00&lt;/OU&gt;<br>&lt;OU rDNAttribute="true"&gt;IT Operations&lt;/OU&gt;<br>&lt;O&gt;Contoso.com&lt;/O&gt;
<br>&lt;L&gt;New York&lt;/L&gt;<br>&lt;S&gt;New York&lt;/S&gt;<br>&lt;C&gt;US&lt;/C&gt;<br>&lt;RDN
oid="1.2.3.4" type="string"&gt;name&lt;/RDN&gt;<br>&lt;RDN rDNAttribute="true" oid="1.2.1.3"
type="encoded"&gt;0500&lt;/RDN&gt;<br>&lt;RDN oid="1.2.1.4" type="encoded"&gt;020135&lt;/RDN&gt;<br>&lt;RDN
oid="1.2.2.5.3" type="octet"&gt;01FF7F&lt;/RDN&gt;<br>

The Unicode XML markup characters are escaped in the following manner. Characters greater than 0x7F are escaped by using
character references (L"&#xXXXX;").

& becomes L"&amp;"

< becomes L"&lt;"

> becomes L"&gt;"

' becomes L"&apos;"

" becomes L"&quot;"

 XCN_CERT_NAME_STR_SEMICOLON_FLAG
Value: 0x40000000
The comma (,) separator used between RDNs is replaced with a semicolon (;) character.

XCN_CERT_NAME_STR_NO_PLUS_FLAG
Value: 0x20000000
The (+) separator used between RDN attributes is replaced with a single space character.

XCN_CERT_NAME_STR_NO_QUOTING_FLAG
Value: 0x10000000
Inhibits the use of quotation marks for the XCN_CERT_X500_NAME_ST value.

XCN_CERT_NAME_STR_CRLF_FLAG
Value: 0x8000000
The comma (,) separator used between RDNs is replaced with a carriage return/line feed (\r\n) sequence.

XCN_CERT_NAME_STR_COMMA_FLAG
Value: 0x4000000
Specifies that the separator between RDNs is a comma (,).

XCN_CERT_NAME_STR_REVERSE_FLAG
Value: 0x2000000
Specifies that the order of the RDNs that make up the distinguished name (DN) is reversed for encoding. The typical DN
display order is CN=name,...,DC=com. Use this flag to change the encoding order to DC=com,...,CN=name. An
IX500DistinguishedName object sets this flag by default unless you specify XCN_CERT_NAME_STR_FORWARD_FLAG.

XCN_CERT_NAME_STR_FORWARD_FLAG
Value: 0x1000000
Use to undo the encoding order specified by setting the XCN_CERT_NAME_STR_REVERSE_FLAG value.

XCN_CERT_NAME_STR_AMBIGUOUS_SEPARATOR_FLAGS

XCN_CERT_NAME_STR_DISABLE_IE4_UTF8_FLAG
Value: 0x10000
Skips the initial attempt to decode T.61 Teletex character values to UTF-8 values. By default, T.61 values are initially decoded to
UTF-8, but if UTF-8 decoding fails, the values are decoded as 8-bit characters.

XCN_CERT_NAME_STR_ENABLE_T61_UNICODE_FLAG
Value: 0x20000
T.61 is used rather than Unicode character encoding for all characters less than 0xFF. LDAP, for example, uses T.61.

XCN_CERT_NAME_STR_ENABLE_UTF8_UNICODE_FLAG
Value: 0x40000
UTF-8 is used for the DN instead of Unicode character encoding.

XCN_CERT_NAME_STR_FORCE_UTF8_DIR_STR_FLAG
Value: 0x80000
Forces the following X.500 keys to be encoded as UTF-8 strings rather than printable Unicode strings.
KEY O ID

CN XCN_OID_COMMON_NAME

G XCN_OID_GIVEN_NAME
 GivenName XCN_OID_GIVEN_NAME

GN XCN_OID_GIVEN_NAME

I XCN_OID_INITIALS

Initials XCN_OID_INITIALS

L XCN_OID_LOCALITY_NAME

O XCN_ORGANIZATION_NAME

OU XCN_OID_ORGANIZATIONAL_UNIT_NAME

S XCN_OID_STATE_OR_PROVINCE_NAME

SN XCN_ID_SUR_NAME

ST XCN_OID_STATE_OR_PROVINCE_NAME

STREET XCN_OID_STREET_ADDRESS

T XCN_OID_TITLE

Title XCN_OID_TITLE

XCN_CERT_NAME_STR_DISABLE_UTF8_DIR_STR_FLAG
Value: 0x100000
Prevents forcing printable Unicode strings to be encoded by using UTF-8. Use when desired when
XCN_CERT_NAME_STR_FORCE_UTF8_DIR_STR_FLAG is the default behavior.

XCN_CERT_NAME_STR_ENABLE_PUNYCODE_FLAG
Value: 0x200000

XCN_CERT_NAME_STR_DS_ESCAPED
Value: 0x800000

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Header certenroll.h

See also
CertEnroll Enumerations
CertEnroll Interfaces
IX500DistinguishedName
 X509CertificateEnrollmentContext enumeration
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The X509Cer tificateEnrollmentContext enumeration specifies the nature of the end entity for which the
certificate is intended. This enumeration is used by the following interfaces:
IX509CertificateRequest
IX509CertificateRequestPkcs7
IX509CertificateRequestPkcs10
IX509Enrollment

Syntax
typedef enum X509CertificateEnrollmentContext {
ContextNone = 0,
ContextUser = 0x1,
ContextMachine = 0x2,
ContextAdministratorForceMachine = 0x3
} ;

Constants

ContextNone
Value: 0

ContextUser
Value: 0x1
The certificate is intended for an end user.

ContextMachine
Value: 0x2
The certificate is intended for a computer.

ContextAdministratorForceMachine
Value: 0x3
The certificate is being requested by an administrator acting on the behalf of a computer.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]
 Header certenroll.h

See also
CertEnroll Enumerations
CertEnroll Interfaces
 X509CertificateTemplateEnrollmentFlag
enumeration (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The X509Cer tificateTemplateEnrollmentFlag enumeration contains values that specify server and client
actions during enrollment.

Syntax
typedef enum X509CertificateTemplateEnrollmentFlag {
EnrollmentIncludeSymmetricAlgorithms = 0x1,
EnrollmentPendAllRequests = 0x2,
EnrollmentPublishToKRAContainer = 0x4,
EnrollmentPublishToDS = 0x8,
EnrollmentAutoEnrollmentCheckUserDSCertificate = 0x10,
EnrollmentAutoEnrollment = 0x20,
EnrollmentDomainAuthenticationNotRequired = 0x80,
EnrollmentPreviousApprovalValidateReenrollment = 0x40,
EnrollmentUserInteractionRequired = 0x100,
EnrollmentAddTemplateName = 0x200,
EnrollmentRemoveInvalidCertificateFromPersonalStore = 0x400,
EnrollmentAllowEnrollOnBehalfOf = 0x800,
EnrollmentAddOCSPNoCheck = 0x1000,
EnrollmentReuseKeyOnFullSmartCard = 0x2000,
EnrollmentNoRevocationInfoInCerts = 0x4000,
EnrollmentIncludeBasicConstraintsForEECerts = 0x8000,
EnrollmentPreviousApprovalKeyBasedValidateReenrollment = 0x10000,
EnrollmentCertificateIssuancePoliciesFromRequest = 0x20000,
EnrollmentSkipAutoRenewal = 0x40000
} ;

Constants

EnrollmentIncludeSymmetricAlgorithms
Value: 0x1
Instructs the client and server to include a Secure/Multipurpose Internet Mail Extensions (S/MIME) extension in the certificate
request and issued certificate.

EnrollmentPendAllRequests
Value: 0x2
Instructs the certification authority (CA) to place all certificate requests in a pending state.

EnrollmentPublishToKRAContainer
Value: 0x4
Instructs the certification authority to publish the issued certificate to the key recovery agent (KRA) container in Active
Directory.

EnrollmentPublishToDS
Value: 0x8
Instructs clients and servers to append the issued certificate to the userCer tificate attribute on the user object in Active
Directory.
 EnrollmentAutoEnrollmentCheckUserDSCertificate
Value: 0x10
Instructs clients to not automatically enroll a certificate based on this template if the userCer tificate attribute on the user
object in Active Directory already contains a valid certificate based on this template.

EnrollmentAutoEnrollment
Value: 0x20
Instructs clients to automatically enroll a certificate that is based on this template.

EnrollmentDomainAuthenticationNotRequired
Value: 0x80
Not used.

EnrollmentPreviousApprovalValidateReenrollment
Value: 0x40
Instructs clients to sign a certificate by using private keys whose public keys are contained in existing certificates.

EnrollmentUserInteractionRequired
Value: 0x100
Instructs the client to obtain user consent before attempting to enroll a certificate request based on this template.

EnrollmentAddTemplateName
Value: 0x200
Not used.

EnrollmentRemoveInvalidCertificateFromPersonalStore
Value: 0x400
Instructs the client to delete expired, revoked, or renewed certificates from the local certificate store.

EnrollmentAllowEnrollOnBehalfOf
Value: 0x800
Instructs the server to allow enroll-on-behalf-of (EOBO) functionality.

EnrollmentAddOCSPNoCheck
Value: 0x1000
Instructs the server to not include revocation information in the issued certificate, adding instead an id-pkix-ocsp-nocheck
extension that specifies that the certificate holder can be trusted for the life of the certificate.

EnrollmentReuseKeyOnFullSmartCard
Value: 0x2000
Instructs the client to reuse a private key for a smart card based certificate renewal if a new private key cannot be created on
the card.

EnrollmentNoRevocationInfoInCerts
Value: 0x4000
Instructs the server to not include revocation information in the issued certificate.

EnrollmentIncludeBasicConstraintsForEECerts
Value: 0x8000
Instructs the server to include the Basic Constraints extension in the issued certificate.

EnrollmentPreviousApprovalKeyBasedValidateReenrollment
Value: 0x10000
 EnrollmentCertificateIssuancePoliciesFromRequest
Value: 0x20000

EnrollmentSkipAutoRenewal
Value: 0x40000

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Header certenroll.h
 X509CertificateTemplateGeneralFlag enumeration
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The X509Cer tificateTemplateGeneralFlag enumeration contains use and modification information about
templates and associated certificates.

Syntax
typedef enum X509CertificateTemplateGeneralFlag {
GeneralMachineType = 0x40,
GeneralCA = 0x80,
GeneralCrossCA = 0x800,
GeneralDefault = 0x10000,
GeneralModified = 0x20000,
GeneralDonotPersist = 0x1000
} ;

Constants

GeneralMachineType
Value: 0x40
The template should be used to create a certificate request for a computer.

GeneralCA
Value: 0x80
The template should be used to create a request for a certification authority certificate.

GeneralCrossCA
Value: 0x800
The template should be used to create a request to cross certify a certificate.

GeneralDefault
Value: 0x10000
The template is not used by the client or server in the Windows Client Certificate Enrollment and should not be modified.

GeneralModified
Value: 0x20000
The template is not used by the client or server in the Windows Client Certificate Enrollment and can be modified if necessary.

GeneralDonotPersist
Value: 0x1000
The certification authority is not required to save a record of a certificate request for a certificate that has been issued.

Requirements
Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Header certenroll.h
 X509CertificateTemplatePrivateKeyFlag enumeration
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The X509Cer tificateTemplatePrivateKeyFlag enumeration contains values that specify client actions
regarding a private key.

Syntax
typedef enum X509CertificateTemplatePrivateKeyFlag {
PrivateKeyRequireArchival = 0x1,
PrivateKeyExportable = 0x10,
PrivateKeyRequireStrongKeyProtection = 0x20,
PrivateKeyRequireAlternateSignatureAlgorithm = 0x40,
PrivateKeyRequireSameKeyRenewal = 0x80,
PrivateKeyUseLegacyProvider = 0x100,
PrivateKeyEKTrustOnUse = 0x200,
PrivateKeyEKValidateCert = 0x400,
PrivateKeyEKValidateKey = 0x800,
PrivateKeyAttestNone = 0,
PrivateKeyAttestPreferred = 0x1000,
PrivateKeyAttestRequired = 0x2000,
PrivateKeyAttestMask = 0x3000,
PrivateKeyAttestWithoutPolicy = 0x4000,
PrivateKeyServerVersionMask = 0xf0000,
PrivateKeyServerVersionShift = 16,
PrivateKeyHelloKspKey = 0x100000,
PrivateKeyHelloLogonKey = 0x200000,
PrivateKeyClientVersionMask = 0xf000000,
PrivateKeyClientVersionShift = 24
} ;

Constants

PrivateKeyRequireArchival
Value: 0x1
Instructs the client to create a key archival certificate request.

PrivateKeyExportable
Value: 0x10
Instructs the client to allow other applications to export the private key to a Personal Information Exchange (PFX) message.
The message is typically saved in a file with a .pfx extension.

PrivateKeyRequireStrongKeyProtection
Value: 0x20
Instructs the client to use additional protection for the private key.
 PrivateKeyRequireAlternateSignatureAlgorithm
Value: 0x40
If this flag is defined, the client must sign the certificate request by using the PKCS #1 version 2.1 signature format which
requires that the hash algorithm OID be encoded into the signature parameters. If this flag is not defined the client must sign
the certificate request by using the PKCS #1 version 1.5 signature format which requires that the hash and asymmetric
algorithm object identifiers (OIDs) be combined into a single OID and that the signature parameters be set to NULL .

PrivateKeyRequireSameKeyRenewal
Value: 0x80

PrivateKeyUseLegacyProvider
Value: 0x100

PrivateKeyEKTrustOnUse
Value: 0x200

PrivateKeyEKValidateCert
Value: 0x400

PrivateKeyEKValidateKey
Value: 0x800

PrivateKeyAttestNone
Value: 0

PrivateKeyAttestPreferred
Value: 0x1000

PrivateKeyAttestRequired
Value: 0x2000

PrivateKeyAttestMask
Value: 0x3000

PrivateKeyAttestWithoutPolicy
Value: 0x4000

PrivateKeyServerVersionMask
Value: 0xf0000

PrivateKeyServerVersionShift
Value: 16

PrivateKeyHelloKspKey
Value: 0x100000

PrivateKeyHelloLogonKey
Value: 0x200000

PrivateKeyClientVersionMask
Value: 0xf000000
 PrivateKeyClientVersionShift
Value: 24

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Header certenroll.h
 X509CertificateTemplateSubjectNameFlag
enumeration (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The X509Cer tificateTemplateSubjectNameFlag enumeration contains values that specify server and client
actions concerning subject names.

Syntax
typedef enum X509CertificateTemplateSubjectNameFlag {
SubjectNameEnrolleeSupplies = 0x1,
SubjectNameRequireDirectoryPath = 0x80000000,
SubjectNameRequireCommonName = 0x40000000,
SubjectNameRequireEmail = 0x20000000,
SubjectNameRequireDNS = 0x10000000,
SubjectNameAndAlternativeNameOldCertSupplies = 0x8,
SubjectAlternativeNameEnrolleeSupplies = 0x10000,
SubjectAlternativeNameRequireDirectoryGUID = 0x1000000,
SubjectAlternativeNameRequireUPN = 0x2000000,
SubjectAlternativeNameRequireEmail = 0x4000000,
SubjectAlternativeNameRequireSPN = 0x800000,
SubjectAlternativeNameRequireDNS = 0x8000000,
SubjectAlternativeNameRequireDomainDNS = 0x400000
} ;

Constants

SubjectNameEnrolleeSupplies
Value: 0x1
Instructs the client to provide subject information in the certificate request.

SubjectNameRequireDirectoryPath
Value: 0x80000000
Instructs the certification authority (CA) to specify the requestor's Active Directory distinguished name as the subject name in
the issued certificate.

SubjectNameRequireCommonName
Value: 0x40000000
Instructs the certification authority (CA) to specify the requestor's Active Directory common name (CN) as the subject name in
the issued certificate.

SubjectNameRequireEmail
Value: 0x20000000
Instructs the CA to specify the value of the e-mail attribute in the requestor's Active Directory user object as the subject
name in the issued certificate.

SubjectNameRequireDNS
Value: 0x10000000
Instructs the CA to specify the value of the DNS attribute in the requestor's Active Directory user object as the subject name
in the issued certificate.
 SubjectNameAndAlternativeNameOldCertSupplies
Value: 0x8
Instructs the client to reuse the subject name and alternative subject name extensions from an existing valid certificate when
creating a renewal certificate request. This flag can only be used when the SubjectNameEnrolleeSupplies or the
SubjectAlternativeNameEnrolleeSupplies flag is specified.

SubjectAlternativeNameEnrolleeSupplies
Value: 0x10000
Instructs the client to provide subject alternative name information in the certificate request.

SubjectAlternativeNameRequireDirectoryGUID
Value: 0x1000000
Instructs the CA to add the value of the objectGUID attribute in the requestor's Active Directory user object to the Subject
Alternative Name extension in the issued certificate.

SubjectAlternativeNameRequireUPN
Value: 0x2000000
Instructs the CA to add the value of the UPN attribute in the requestor's Active Directory user object to the Subject
Alternative Name extension in the issued certificate.

SubjectAlternativeNameRequireEmail
Value: 0x4000000
Instructs the CA to add the value of the e-mail attribute in the requestor's Active Directory user object to the Subject
Alternative Name extension in the issued certificate.

SubjectAlternativeNameRequireSPN
Value: 0x800000
Instructs the CA to add the value of the SPN attribute in the requestor's Active Directory user object to the Subject
Alternative Name extension in the issued certificate.

SubjectAlternativeNameRequireDNS
Value: 0x8000000
Instructs the CA to add the value of the DNS attribute in the requestor's Active Directory user object to the Subject
Alternative Name extension in the issued certificate.

SubjectAlternativeNameRequireDomainDNS
Value: 0x400000
Instructs the CA to add the value of the DNS of the root domain to the Subject Alternative Name extension in the issued
certificate.

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Header certenroll.h
 X509EnrollmentPolicyExportFlags enumeration
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The X509EnrollmentPolicyExpor tFlags enumeration is used by the Export method on the

IX509EnrollmentPolicyServer interface to specify what items to export from the policy server.

Syntax
typedef enum X509EnrollmentPolicyExportFlags {
ExportTemplates = 0x1,
ExportOIDs = 0x2,
ExportCAs = 0x4
} ;

Constants

ExportTemplates
Value: 0x1
Export templates.

ExportOIDs
Value: 0x2
Export custom object identifiers.

ExportCAs
Value: 0x4
Not used.

Remarks
To export both templates and object identifiers, specify a bitwise OR of the Expor tTemplates and Expor tOIDs
values.

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Header certenroll.h

See also
Export
 X509EnrollmentPolicyLoadOption enumeration
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The X509EnrollmentPolicyLoadOption enumeration is used by the LoadPolicy method on the

IX509EnrollmentPolicyServer interface to specify how to retrieve policy from the policy server.

Syntax
typedef enum X509EnrollmentPolicyLoadOption {
LoadOptionDefault = 0,
LoadOptionCacheOnly = 1,
LoadOptionReload = 2,
LoadOptionRegisterForADChanges = 4
} ;

Constants

LoadOptionDefault
Value: 0
Reload if the cache has expired.

LoadOptionCacheOnly
Value: 1
Always load from the cache even if it has expired.

LoadOptionReload
Value: 2
Always reload.

LoadOptionRegisterForADChanges
Value: 4
Registers a thread to update a sequence number if there are changes to the template or the certification authority container.
This value applies only to an Active Directory policy server.

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Header certenroll.h

See also
LoadPolicy
 X509KeySpec enumeration (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The X509KeySpec enumeration type specifies the intended use of a key for a legacy cryptographic service
provider (CSP). Legacy CSPs can support at most one signature algorithm (XCN_AT_SIGNATURE) and one
encryption algorithm (XCN_AT_KEYEXCHANGE). This enumeration is used by the following interfaces:
ICspInformation
ICspInformations
IX509AttributeCspProvider
IX509CertificateRequestPkcs10
IX509PrivateKey

Syntax
typedef enum X509KeySpec {
XCN_AT_NONE = 0,
XCN_AT_KEYEXCHANGE = 1,
XCN_AT_SIGNATURE = 2
} ;

Constants

XCN_AT_NONE
Value: 0
The intended use is not identified. This value is set if the provider that supports the key is a Cryptography API: Next
Generation (CNG) key storage provider (KSP).

XCN_AT_KEYEXCHANGE
Value: 1
The key can be used to encrypt (including key exchange) or sign depending on the algorithm. For RSA algorithms, if this value
is set, the key can be used for both signing and encryption. For other algorithms, signing may not be supported. Further, only
encryption for key exchange may be supported.

Note The KEYEXCHANGE portion of the value name is a carryover from CryptoAPI where it originally referred to the
symmetric encryption of a private key used during key exchange. Use of the term ultimately expanded to cover all symmetric
encryption.

XCN_AT_SIGNATURE
Value: 2
The key can be used for signing.

Requirements
 Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Header certenroll.h

See also
CertEnroll Enumerations
CertEnroll Interfaces
IX509PrivateKey
 X509KeyUsageFlags enumeration (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The X509KeyUsageFlags enumeration type specifies the purpose of a key contained in a certificate. You can
use the enumeration to identify restrictions. For example, if a key should be used only for signing, you can select
the XCN_CERT_DIGITAL_SIGNATURE_KEY_USAGE or the XCN_CERT_NON_REPUDIATION_KEY_USAGE
values. Likewise, if a key should be used only for key management, you can select the
XCN_CERT_KEY_ENCIPHERMENT_KEY_USAGE value. This enumeration can be used to initialize an
IX509ExtensionKeyUsage object.

Syntax
typedef enum X509KeyUsageFlags {
XCN_CERT_NO_KEY_USAGE = 0,
XCN_CERT_DIGITAL_SIGNATURE_KEY_USAGE = 0x80,
XCN_CERT_NON_REPUDIATION_KEY_USAGE = 0x40,
XCN_CERT_KEY_ENCIPHERMENT_KEY_USAGE = 0x20,
XCN_CERT_DATA_ENCIPHERMENT_KEY_USAGE = 0x10,
XCN_CERT_KEY_AGREEMENT_KEY_USAGE = 0x8,
XCN_CERT_KEY_CERT_SIGN_KEY_USAGE = 0x4,
XCN_CERT_OFFLINE_CRL_SIGN_KEY_USAGE = 0x2,
XCN_CERT_CRL_SIGN_KEY_USAGE = 0x2,
XCN_CERT_ENCIPHER_ONLY_KEY_USAGE = 0x1,
XCN_CERT_DECIPHER_ONLY_KEY_USAGE = 0x8000
} ;

Constants

XCN_CERT_NO_KEY_USAGE
Value: 0
The purpose of the key is not defined.

XCN_CERT_DIGITAL_SIGNATURE_KEY_USAGE
Value: 0x80
The key is used with a Digital Signature Algorithm (DSA) to support services other than nonrepudiation, certificate signing, or
revocation list signing.

XCN_CERT_NON_REPUDIATION_KEY_USAGE
Value: 0x40
The key is used to verify a digital signature as part of a nonrepudiation service that protects against false denial of action by a
signing entity.

XCN_CERT_KEY_ENCIPHERMENT_KEY_USAGE
Value: 0x20
The key is used for key transport. That is, the key is used to manage a key passed from its point of origination to another
point of use.

XCN_CERT_DATA_ENCIPHERMENT_KEY_USAGE
Value: 0x10
The key is used to encrypt user data other than cryptographic keys.
 XCN_CERT_KEY_AGREEMENT_KEY_USAGE
Value: 0x8
The key is used for key agreement. The key agreement or key exchange protocol enables two or more parties to negotiate a
key value without transferring the key and without previously establishing a shared secret.

XCN_CERT_KEY_CERT_SIGN_KEY_USAGE
Value: 0x4
The key is used to verify a certificate signature. This value can only be used for certificates issued by certification authorities.

XCN_CERT_OFFLINE_CRL_SIGN_KEY_USAGE
Value: 0x2
The key is used to verify an offline certificate revocation list (CRL) signature.

XCN_CERT_CRL_SIGN_KEY_USAGE
Value: 0x2
The key is used to verify a CRL signature.

XCN_CERT_ENCIPHER_ONLY_KEY_USAGE
Value: 0x1
The key is used to encrypt data while performing key agreement. When this value is specified, the
XCN_CERT_KEY_AGREEMENT_KEY_USAGE value must also be specified.

XCN_CERT_DECIPHER_ONLY_KEY_USAGE
Value: 0x8000
The key is used to decrypt data while performing key agreement. When this value is specified, the
XCN_CERT_KEY_AGREEMENT_KEY_USAGE must also be specified.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Header certenroll.h

See also
CertEnroll Enumerations
CertEnroll Interfaces
IX509ExtensionKeyUsage
InitializeEncode
 X509PrivateKeyExportFlags enumeration
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The X509PrivateKeyExpor tFlags enumeration type specifies the export policy for a private key. For a
Cryptography API: Next Generation (CNG) key, the policy is stored by the key service provider (KSP), and it is the
responsibility of the KSP to enforce the policy. When a legacy cryptographic service provider (CSP) is specified,
the policy is used when creating the key, and it is the responsibility of the CSP to enforce the policy. This
enumeration is used when specifying and retrieving the ExportPolicy property on the IX509PrivateKey interface.

Syntax
typedef enum X509PrivateKeyExportFlags {
XCN_NCRYPT_ALLOW_EXPORT_NONE = 0,
XCN_NCRYPT_ALLOW_EXPORT_FLAG = 0x1,
XCN_NCRYPT_ALLOW_PLAINTEXT_EXPORT_FLAG = 0x2,
XCN_NCRYPT_ALLOW_ARCHIVING_FLAG = 0x4,
XCN_NCRYPT_ALLOW_PLAINTEXT_ARCHIVING_FLAG = 0x8
} ;

Constants

XCN_NCRYPT_ALLOW_EXPORT_NONE
Value: 0
Export is not allowed. This is the default value.

XCN_NCRYPT_ALLOW_EXPORT_FLAG
Value: 0x1
The private key can be exported.

XCN_NCRYPT_ALLOW_PLAINTEXT_EXPORT_FLAG
Value: 0x2
The private key can be exported in plaintext form.

XCN_NCRYPT_ALLOW_ARCHIVING_FLAG
Value: 0x4
The private key can be exported once for archiving.

XCN_NCRYPT_ALLOW_PLAINTEXT_ARCHIVING_FLAG
Value: 0x8
The private key can be exported once in plaintext form for archiving.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

 Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Header certenroll.h

See also
CertEnroll Enumerations
CertEnroll Interfaces
IX509PrivateKey
 X509PrivateKeyProtection enumeration (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The X509PrivateKeyProtection enumeration specifies the level of private key protection supported by a
cryptographic provider. For example, if strong key protection is enabled, the user is typically prompted to enter a
password when the key is created and whenever the key is used. The precise behavior is specified by the KSP or
CSP being used. The enumeration value can be specified or retrieved by using the KeyProtection property on the
IX509PrivateKey interface.

Syntax
typedef enum X509PrivateKeyProtection {
XCN_NCRYPT_UI_NO_PROTECTION_FLAG = 0,
XCN_NCRYPT_UI_PROTECT_KEY_FLAG = 0x1,
XCN_NCRYPT_UI_FORCE_HIGH_PROTECTION_FLAG = 0x2,
XCN_NCRYPT_UI_FINGERPRINT_PROTECTION_FLAG = 0x4,
XCN_NCRYPT_UI_APPCONTAINER_ACCESS_MEDIUM_FLAG = 0x8
} ;

Constants

XCN_NCRYPT_UI_NO_PROTECTION_FLAG
Value: 0
The protection level is not specified.

XCN_NCRYPT_UI_PROTECT_KEY_FLAG
Value: 0x1
A user interface is displayed to indicate that a process is attempting to use the key. The exact behavior is specified by the KSP
or CSP being used. Some Microsoft legacy CSPs allow the client to decide whether a password is required to use the key or
whether the user must only acknowledge a prompt.

XCN_NCRYPT_UI_FORCE_HIGH_PROTECTION_FLAG
Value: 0x2
Specifies strong key protection. The user is typically prompted to enter a password when the key is created and whenever the
key is used. The exact behavior is specified by the KSP being used. This value is not supported by the Certificate Enrollment
API for legacy CSPs.

XCN_NCRYPT_UI_FINGERPRINT_PROTECTION_FLAG
Value: 0x4

XCN_NCRYPT_UI_APPCONTAINER_ACCESS_MEDIUM_FLAG
Value: 0x8

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

 Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Header certenroll.h

See also
CertEnroll Enumerations
CertEnroll Interfaces
IX509PrivateKey
 X509PrivateKeyUsageFlags enumeration
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The X509PrivateKeyUsageFlags enumeration specifies the permitted uses of a private key. It is the
responsibility of the cryptographic provider. The enumeration value can be set and retrieved by using the
KeyUsage property on the IX509PrivateKey interface.

Syntax
typedef enum X509PrivateKeyUsageFlags {
XCN_NCRYPT_ALLOW_USAGES_NONE = 0,
XCN_NCRYPT_ALLOW_DECRYPT_FLAG = 0x1,
XCN_NCRYPT_ALLOW_SIGNING_FLAG = 0x2,
XCN_NCRYPT_ALLOW_KEY_AGREEMENT_FLAG = 0x4,
XCN_NCRYPT_ALLOW_KEY_IMPORT_FLAG = 0x8,
XCN_NCRYPT_ALLOW_ALL_USAGES = 0xffffff
} ;

Constants

XCN_NCRYPT_ALLOW_USAGES_NONE
Value: 0
The permitted uses are not defined.

XCN_NCRYPT_ALLOW_DECRYPT_FLAG
Value: 0x1
The key can be used to decrypt content. This maps to the following X509KeyUsageFlags values:

XCN_CERT_DATA_ENCIPHERMENT_KEY_USAGE

XCN_CERT_DECIPHER_ONLY_KEY_USAGE

XCN_CERT_ENCIPHER_ONLY_KEY_USAGE

XCN_CERT_KEY_ENCIPHERMENT_KEY_USAGE
 XCN_NCRYPT_ALLOW_SIGNING_FLAG
Value: 0x2
The key can be used for signing. This maps to the following X509KeyUsageFlags values:

XCN_CERT_CRL_SIGN_KEY_USAGE

XCN_CERT_DIGITAL_SIGNATURE_KEY_USAGE

XCN_CERT_KEY_CERT_SIGN_KEY_USAGE

XCN_NCRYPT_ALLOW_KEY_AGREEMENT_FLAG
Value: 0x4
The key can be used to establish key agreement between entities.

XCN_NCRYPT_ALLOW_KEY_IMPORT_FLAG
Value: 0x8

XCN_NCRYPT_ALLOW_ALL_USAGES
Value: 0xffffff
All of the uses defined for this enumeration are permitted.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Header certenroll.h

See also
CertEnroll Enumerations
CertEnroll Interfaces
IX509PrivateKey
 X509PrivateKeyVerify enumeration (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The X509PrivateKeyVerify enumeration specifies whether a user interface is displayed during private key
verification and whether verification can proceed if the cryptographic provider is a smart card provider. This
enumeration is used by the Verify method on the IX509PrivateKey interface.

Syntax
typedef enum X509PrivateKeyVerify {
VerifyNone = 0,
VerifySilent = 1,
VerifySmartCardNone = 2,
VerifySmartCardSilent = 3,
VerifyAllowUI = 4
} ;

Constants

VerifyNone
Value: 0
No option is identified.

VerifySilent
Value: 1
The method does not display a user interface.

VerifySmartCardNone
Value: 2
No verification occurs if the key is stored on a smart card (the CSP or KSP is a smart card provider).

VerifySmartCardSilent
Value: 3
The method does not display a user interface if the key is stored on a smart card (the CSP or KSP is a smart card provider).

VerifyAllowUI
Value: 4
The method displays a user interface.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]
 Header certenroll.h

See also
CertEnroll Enumerations
CertEnroll Interfaces
IX509PrivateKey
 X509ProviderType enumeration (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The X509ProviderType enumeration specifies the type of cryptographic provider. Providers implement
cryptographic standards and algorithms in software and hardware. This enumeration is used by the
ICspInformation and IX509PrivateKey interfaces.

Syntax
typedef enum X509ProviderType {
XCN_PROV_NONE = 0,
XCN_PROV_RSA_FULL = 1,
XCN_PROV_RSA_SIG = 2,
XCN_PROV_DSS = 3,
XCN_PROV_FORTEZZA = 4,
XCN_PROV_MS_EXCHANGE = 5,
XCN_PROV_SSL = 6,
XCN_PROV_RSA_SCHANNEL = 12,
XCN_PROV_DSS_DH = 13,
XCN_PROV_EC_ECDSA_SIG = 14,
XCN_PROV_EC_ECNRA_SIG = 15,
XCN_PROV_EC_ECDSA_FULL = 16,
XCN_PROV_EC_ECNRA_FULL = 17,
XCN_PROV_DH_SCHANNEL = 18,
XCN_PROV_SPYRUS_LYNKS = 20,
XCN_PROV_RNG = 21,
XCN_PROV_INTEL_SEC = 22,
XCN_PROV_REPLACE_OWF = 23,
XCN_PROV_RSA_AES = 24
} ;

Constants

XCN_PROV_NONE
Value: 0
No provider is identified.

XCN_PROV_RSA_FULL
Value: 1
Supports the following algorithms:

Encryption: RC2 and RC4

Hashing: MD5 and SHA

Key Exchange: RSA

Signatures: RSA
XCN_PROV_RSA_SIG
Value: 2
Supports the following algorithms:

Hashing: MD5 and SHA

Signatures: RSA

XCN_PROV_DSS
Value: 3
Supports the following algorithms. This is a subset of the XCN_PROV_DSS_DH provider type.

Hashing: MD5 and SHA

Signatures: Digital Signature Standard (DSS)

XCN_PROV_FORTEZZA
Value: 4
Supports the Fortezza cryptographic card developed by NSA. This includes support for the following algorithms:

Encryption: Skipjack

Hashing: SHA

Key Exchange: KEA

Signatures: DSS

XCN_PROV_MS_EXCHANGE
Value: 5
Supports cryptographic algorithms used by the Microsoft Exchange mail application and other applications compatible with
Microsoft Mail.
This includes the following:

Encryption: CAST

Hashing: MD5

Key Exchange: RSA

Signatures: RSA
XCN_PROV_SSL
Value: 6
Supports the Secure Sockets Layer protocol. This includes the following algorithms:

Encryption: variable

Hashing: variable

Key Exchange: RSA

Signatures: RSA

XCN_PROV_RSA_SCHANNEL
Value: 12
Supports RSA and Schannel protocols. This includes the following algorithms:

Encryption: RC4, Data Encryption Standard (DES), 3DES

Hashing: MD5, SHA

Key Exchange: RSA

Signatures: RSA

XCN_PROV_DSS_DH
Value: 13
Supports the following algorithms:

Encryption: CYLINK_MEK

Hashing: MD5, SHA

Key Exchange: Diffie-Hellman algorithm

Signatures: DSS

XCN_PROV_EC_ECDSA_SIG
Value: 14
Microsoft currently does not provide a CSP of this type.

XCN_PROV_EC_ECNRA_SIG
Value: 15
Microsoft currently does not provide a CSP of this type.

XCN_PROV_EC_ECDSA_FULL
Value: 16
Microsoft currently does not provide a CSP of this type.
 XCN_PROV_EC_ECNRA_FULL
Value: 17
Microsoft currently does not provide a CSP of this type.

XCN_PROV_DH_SCHANNEL
Value: 18
Supports the Diffie-Hellman and Schannel protocols. This includes the following algorithms:

Encryption: DES, 3DES

Hashing: MD5, SHA

Key Exchange: Diffie-Hellman algorithm

Signatures: DSS

XCN_PROV_SPYRUS_LYNKS
Value: 20
Microsoft currently does not provide a CSP of this type.

XCN_PROV_RNG
Value: 21
Microsoft currently does not provide a CSP of this type.

XCN_PROV_INTEL_SEC
Value: 22
Microsoft currently does not provide a CSP of this type.

XCN_PROV_REPLACE_OWF
Value: 23
Microsoft currently does not provide a CSP of this type.

XCN_PROV_RSA_AES
Value: 24
Supports the following algorithms:

Encryption: RC2, RC4, AES

Hashing: MD5, SHA

Key Exchange: RSA

Signatures: RSA

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

 Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Header certenroll.h

See also
CertEnroll Enumerations
CertEnroll Interfaces
ICspInformation
IX509PrivateKey
 X509RequestInheritOptions enumeration
(certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The X509RequestInheritOptions enumeration type specifies how keys, extension values, and external
properties are inherited when a new request is created from an existing certificate. This enumeration can be
used to initialize an IX509CertificateRequestPkcs7 or an IX509CertificateRequestPkcs10 object from an existing
certificate.
You can choose one of the following values to specify how keys are inherited:
InheritNewDefaultKey
InheritNewSimilarKey
InheritPrivateKey
InheritPublicKey
You can also use a bitwise-AND operation to combine the key inheritance choice with InheritNone or with any
combination of the following flags:
InheritRenewalCer tificateFlag
InheritTemplateFlag
InheritSubjectFlag
InheritExtensionsFlag
InheritSubjectAltNameFlag
InheritValidityPeriodFlag

Syntax
typedef enum X509RequestInheritOptions {
InheritDefault = 0,
InheritNewDefaultKey = 0x1,
InheritNewSimilarKey = 0x2,
InheritPrivateKey = 0x3,
InheritPublicKey = 0x4,
InheritKeyMask = 0xf,
InheritNone = 0x10,
InheritRenewalCertificateFlag = 0x20,
InheritTemplateFlag = 0x40,
InheritSubjectFlag = 0x80,
InheritExtensionsFlag = 0x100,
InheritSubjectAltNameFlag = 0x200,
InheritValidityPeriodFlag = 0x400,
InheritReserved80000000 = 0x80000000
} ;

Constants
 InheritDefault
Value: 0
Inheritance is not specified. For more information, see the InitializeFromCertificate method on the
IX509CertificateRequestPkcs10 interface.

InheritNewDefaultKey
Value: 0x1
Creates a new key but inherits the default cryptographic service provider (CSP) or KSP.

InheritNewSimilarKey
Value: 0x2
Creates a new key but inherits the CSP or KSP used to create the existing certificate.

InheritPrivateKey
Value: 0x3
Inherits the private and public keys.

InheritPublicKey
Value: 0x4
Inherits only the public key.

InheritKeyMask
Value: 0xf
Use to mask the lower-order 4 bits that identify key inheritance.

InheritNone
Value: 0x10
Prevents use of the following inheritance values:

InheritRenewalCer tificateFlag

InheritTemplateFlag

InheritSubjectFlag

InheritExtensionsFlag

InheritSubjectAltNameFlag

InheritValidityPeriodFlag

InheritRenewalCertificateFlag
Value: 0x20
Inherits the renewal certificate. Specifying this flag sets an ICertPropertyRenewal value.

InheritTemplateFlag
Value: 0x40
Inherits the certificate template.

InheritSubjectFlag
Value: 0x80
Inherits the subject distinguished name.
 InheritExtensionsFlag
Value: 0x100
Inherits the relevant extensions from the certificate. Extension values associated with the following object identifiers are not
inherited:

XCN_OID_CERTSRV_CA_VERSION

XCN_OID_AUTHORITY_INFO_ACCESS

XCN_OID_CRL_DIST_POINTS

XCN_OID_AUTHORITY_KEY_IDENTIFIER2

XCN_OID_CERTSRV_PREVIOUS_CERT_HASH

XCN_OID_ENROLL_CERTTYPE_EXTENSION

XCN_OID_CERTIFICATE_TEMPLATE

InheritSubjectAltNameFlag
Value: 0x200
Inherits the SubjectAlternativeName extension.

InheritValidityPeriodFlag
Value: 0x400
Inherits the validity period.

InheritReserved80000000
Value: 0x80000000

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Header certenroll.h

See also
CertEnroll Enumerations
CertEnroll Interfaces
IX509CertificateRequestPkcs10
IX509CertificateRequestPkcs7
 X509RequestType enumeration (certenroll.h)
7/2/2022 • 2 minutes to read • Edit Online

The X509RequestType enumeration specifies the certificate request type. This enumeration is returned by the
Type property on the IX509CertificateRequest interface.

Syntax
typedef enum X509RequestType {
TypeAny = 0,
TypePkcs10 = 1,
TypePkcs7 = 2,
TypeCmc = 3,
TypeCertificate = 4
} ;

Constants

TypeAny
Value: 0
The type is not defined.

TypePkcs10
Value: 1
A PKCS #10 request. For more information, see the IX509CertificateRequestPkcs10 interface.

TypePkcs7
Value: 2
A PKCS #7 request represented by an IX509CertificateRequestPkcs7 interface.

TypeCmc
Value: 3
A Certificate Management over CMS (CMC) request. For more information, see the IX509CertificateRequestCmc interface.

TypeCertificate
Value: 4
A self-signed certificate. For more information, see the IX509CertificateRequestCertificate interface.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Header certenroll.h
See also
CertEnroll Enumerations
CertEnroll Interfaces
 certexit.h header
7/2/2022 • 2 minutes to read • Edit Online

This header is used by Security and Identity. For more information, see:
Security and Identity
certexit.h contains the following programming interfaces:

Interfaces

ICertExit

Provides communications between the Certificate Services server and an exit module.

ICertExit2

Provide communications between the Certificate Services server and an exit module.
 ICertExit interface (certexit.h)
7/2/2022 • 2 minutes to read • Edit Online

The ICer tExit interface provides communications between the Certificate Services server and an exit module.

Note The exit module can communicate with the Certificate Services server by using the ICertServerExit interface.

The Certificate Services server calls the ICer tExit methods to perform the following tasks:
Initialize the Certificate Services server.
Notify the exit module of an event such as certificate issuance, certificate revocation list (CRL) issuance, or
server shutdown, has occurred.
Retrieve a description of the exit module.
ICer tExit is defined in Certexit.h. When you create your program, however, use Certsrv.h as the include file.
Certificate Services interfaces support both apartment-threading and free-threading models. For better
throughput, free threading is recommended.

Inheritance
The ICer tExit interface inherits from the IDispatch interface. ICer tExit also has these types of members:

Methods
The ICer tExit interface has these methods.

ICertExit::GetDescription

Returns a human-readable description of the exit module and its function.

ICertExit::Initialize

Called by the server engine when it initializes itself.

ICertExit::Notify

Called by the server engine to notify an exit module that an event has occurred.

Remarks
Implementers of ICer tExit should also implement ICertManageModule. Additionally, the ProgID for a class
implementing ICer tExit must conform to a naming convention. Specifically, the ProgID must be of the form:
" MyApp.Exit"
Where MyApp is a specifier that identifies the application. For example, in C++, the following code could be
used in the DECLARE_REGISTRY macro of a class (CMyCertExitModule) which implements ICer tExit .
 DECLARE_REGISTRY(
CMyCertExitModule,
L"MyCode.Exit.1",
L"MyCode.Exit",
IDS_CERTEXITMODULE_DESC,
THREADFLAGS_BOTH)

For the previous sample, the IDS_CERTEXITMODULE_DESC value is an application-specific identifier in the
resource file (.rc) for a string that describes the class.
String constants defined in Certmod.h can be used to simplify following the naming convention.

C O N STA N T VA L UE

wszCERTEXITMODULE_POSTFIX TEXT(".Exit")

No more than one Visual Basic Scripting Edition exit module may be registered on the Certificate Services
server at one time. If more than one Visual Basic Scripting Edition exit module is registered, the Certification
Authority MMC snap-in, Certificate Services application, or certutil command line program may produce errors.
Note that the Visual Basic Scripting Edition development environment automatically registers a DLL when it is
successfully built. As a result, you may encounter this situation when one Visual Basic Scripting Edition exit
module is already registered and another Visual Basic Scripting Edition exit module is created. To avoid this
situation, you must unregister one of the Visual Basic Scripting Edition exit modules, by means of the command-
line instruction regsvr32 /u FileName.dll , where FileName.dll is the name of the Visual Basic Scripting Edition
exit module that is not intended to be made active.
Implementers of ICer tExit in Visual Basic Scripting Edition must name their project in the form:
" MyApp"
Where MyApp is a specifier that identifies the application; further, the class implementing ICer tExit must be
named "Exit" .

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header certexit.h (include Certsrv.h)

See also
ICertServerExit
IDispatch
 ICertExit::GetDescription method (certexit.h)
7/2/2022 • 2 minutes to read • Edit Online

The GetDescription method returns a human-readable description of the exit module and its function. This
method was first defined in the ICertExit interface.

Syntax
HRESULT GetDescription(
[out] BSTR *pstrDescription
);

Parameters
[out] pstrDescription

A pointer to the BSTR that describes the exit module.

Return value
C++
If the method succeeds, the method returns S_OK.
If the method fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.
VB
Returns a string that describes the exit module and its function.

Remarks
When you write a custom exit module, implement this method.
Examples
 STDMETHODIMP
CCertExit::GetDescription(
/* [out, retval] */ BSTR __RPC_FAR *pstrDescription)
{
if (NULL == pstrDescription)
{
// Bad pointer address.
return (E_POINTER);
}
if (NULL != *pstrDescription)
{
SysFreeString(*pstrDescription);
*pstrDescription=NULL;
}
// wszMyExitModuleDesc defined elsewhere, for example:
// #define wszMyExitModuleDesc L"My Exit Module"
*pstrDescription = SysAllocString(wszMyExitModuleDesc);
if (NULL == *pstrDescription)
{
// Not enough memory
return ( E_OUTOFMEMORY );
}
// Success
return( S_OK );
}

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header certexit.h (include Certsrv.h)

See also
ICertExit
ICertExit2
 ICertExit::Initialize method (certexit.h)
7/2/2022 • 2 minutes to read • Edit Online

The Initialize method is called by the server engine when it initializes itself.
The call to the exit module's Initialize method allows the exit module to perform initialization and inform the
server engine which kinds of events it would like to be notified of.

Syntax
HRESULT Initialize(
[in] const BSTR strConfig,
[out, retval] LONG *pEventMask
);

Parameters
[in] strConfig

Represents the name of the certification authority, as entered during Certificate Services setup. For information
about the configuration string name, see ICertConfig2.
[out, retval] pEventMask

A pointer to the value that represents the events for which the exit module requests notification. This can be one
or more of the following values.

VA L UE M EA N IN G

Certificate denied.
EXITEVENT_CERTDENIED

Certificate issued.
EXITEVENT_CERTISSUED

Certificate pending.
EXITEVENT_CERTPENDING

Successful call to RetrievePending.

EXITEVENT_CERTRETRIEVEPENDING

Certificate revoked.
EXITEVENT_CERTREVOKED

Certificate revocation list issued.

EXITEVENT_CRLISSUED

Certificate Services shutdown.

EXITEVENT_SHUTDOWN
Return value
C++
If the method succeeds, the method returns S_OK and *pEventMask is set to a combination of the flags in the table
below (or EXITEVENT_INVALID if the exit module does not want to be notified of any events).
If the method fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.
If the exit module does not want to be notified of any events, then the flag EXITEVENT_INVALID should be set.
VB
The return value is a mask that contains flags that indicate the events for which the exit module requests
notification. After the call, all events of those types will be signaled by the server engine to the exit module through
a call to Notify. Any or all of the following flags may be set.
RET URN C O DE/ VA L UE DESC RIP T IO N

Certificate denied.
EXITEVENT_CERTDENIED
&H4

Certificate issued.
EXITEVENT_CERTISSUED
&H1

Certificate pending.
EXITEVENT_CERTPENDING
&H2

Successful call to RetrievePending.

EXITEVENT_CERTRETRIEVEPENDING
&H10

Certificate revoked.
EXITEVENT_CERTREVOKED
&H8

Certificate revocation list issued.

EXITEVENT_CRLISSUED
&H20

The event is currently not valid.

EXITEVENT_INVALID
0

Certificate Services shutdown.

EXITEVENT_SHUTDOWN
&H40

Remarks
When you write a custom exit module, implement this method.
Examples
 #include <windows.h>
#include <stdio.h>
#include <Certexit.h>

STDMETHODIMP CCertExit::Initialize(
/* [in] */ BSTR const strConfig,
/* [retval][out] */ LONG __RPC_FAR *pEventMask)
{
// Verify valid pointer passed in.
if (NULL == pEventMask)
return ( E_POINTER ); // Bad pointer

// strConfig can be used by the Exit module.

// Here, it is stored in a BSTR member variable.
// Remember to call SysFreeString to free m_strConfig when done.
m_strConfig = SysAllocString( strConfig );
// Check to determine whether there was enough memory.
if (NULL == m_strConfig)
return ( E_OUTOFMEMORY ); // Not enough memory

// Inform server engine (CA) that we're interested in

// the following events.
*pEventMask = EXITEVENT_CERTISSUED |
EXITEVENT_CERTPENDING |
EXITEVENT_CERTDENIED |
EXITEVENT_CERTREVOKED |
EXITEVENT_CERTRETRIEVEPENDING |
EXITEVENT_CRLISSUED |
EXITEVENT_SHUTDOWN;

if ( fDebug )
{
printf("Exit's Initialize member called\n");
printf("\tstrConfig = %ws\n", strConfig );
}

return( S_OK );
}

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header certexit.h (include Certsrv.h)

See also
ICertExit
ICertExit2
Notify
 ICertExit::Notify method (certexit.h)
7/2/2022 • 2 minutes to read • Edit Online

The Notify method is called by the server engine to notify an exit module that an event has occurred.

Syntax
HRESULT Notify(
[in] LONG ExitEvent,
[in] LONG Context
);

Parameters
[in] ExitEvent

A mask that indicates the kind of exit event that has occurred. The mask can have one of the following flag-bits
set.

VA L UE M EA N IN G

Certificate issued.
EXITEVENT_CERTISSUED

Certificate pending.
EXITEVENT_CERTPENDING

Certificate denied.
EXITEVENT_CERTDENIED

Certificate revoked.
EXITEVENT_CERTREVOKED

Successful call to ICertRequest::RetrievePending.

EXITEVENT_CERTRETRIEVEPENDING

Certificate revocation list (CRL) issued.

EXITEVENT_CRLISSUED

Certificate Services shutdown.

EXITEVENT_SHUTDOWN

[in] Context

Specifies a context handle that can be used to get properties associated with the event from the ICertServerExit
interface.

Return value
VB
If the method succeeds, the method returns S_OK.
If the method fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.

Remarks
If a certification authority is using multiple exit modules, Certificate Services will notify each exit module of the
event (provided the exit module requested notification by means of Initialize). The order in which the exit
modules are notified should not be assumed, nor should one exit module depend on the processing of another
exit module. Each notified exit module must return from Notify before the next exit module will be notified.
Examples
 #include <windows.h>
#include <stdio.h>
#include <Certexit.h>

STDMETHODIMP CCertExit::Notify(
/* [in] */ LONG ExitEvent,
/* [in] */ LONG Context)
{
char *pszEvent;
HRESULT hr = S_OK;

switch (ExitEvent)
{
case EXITEVENT_CERTISSUED:
// Call application-specific function for issued certs.
hr = MyEventCertIssued(Context);
pszEvent = "certissued";
break;

case EXITEVENT_CERTPENDING:
pszEvent = "certpending";
break;

case EXITEVENT_CERTDENIED:
pszEvent = "certdenied";
break;

case EXITEVENT_CERTREVOKED:
pszEvent = "certrevoked";
break;

case EXITEVENT_CERTRETRIEVEPENDING:
pszEvent = "retrievepending";
break;

case EXITEVENT_CRLISSUED:
pszEvent = "crlissued";
break;

case EXITEVENT_SHUTDOWN:
// Call application-specific function for shutdown.
hr = MyEventShutdown();
pszEvent = "shutdown";
break;

default:
pszEvent = "Unexpected event";
break;
}

if ( fDebug )
{
// Display what took place.
printf("Exit::Notify(%s=%x, context=%u) return=%x\n",
pszEvent,
ExitEvent,
Context,
hr);
}

return(hr);
}

Requirements
 Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header certexit.h (include Certsrv.h)

See also
ICertExit
ICertExit2
 ICertExit2 interface (certexit.h)
7/2/2022 • 2 minutes to read • Edit Online

The ICer tExit2 interface is one of two interfaces that provide communications between the Certificate Services
server and an exit module.

Note The exit module can communicate with the Certificate Services server by using the ICertServerExit interface.

The Certificate Services server calls the ICer tExit2 methods to perform the following tasks:
Initialize the Certificate Services server.
Notify the exit module of an event such as certificate issuance, CRL issuance, or server shutdown, has
occurred.
Retrieve a description of the exit module.
Retrieve the ICertManageModule interface implemented by the exit module. The methods of this interface
allows the Certificate Services server to configure the exit module as well as set and retrieve the exit module
properties.
ICer tExit2 is defined in Certexit.h. When you create your program, however, use Certsrv.h as the include file.
Certificate Services interfaces support both apartment-threading and free-threading models. For better
throughput, free threading is recommended.

Inheritance
The ICer tExit2 interface inherits from ICertExit and IDispatch. ICer tExit2 also has these types of members:

Methods
The ICer tExit2 interface has these methods.

ICertExit2::GetManageModule

Retrieves the ICertManageModule interface associated with the ICertExit2 interface by calling GetManageModule and passing
in the address of a pointer to an ICertManageModule.

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header certexit.h (include Certsrv.h)

 ICertExit2::GetManageModule method (certexit.h)
7/2/2022 • 2 minutes to read • Edit Online

The GetManageModule method retrieves the ICertManageModule interface associated with the ICertExit2
interface by calling GetManageModule and passing in the address of a pointer to an ICer tManageModule .

Syntax
HRESULT GetManageModule(
[out] ICertManageModule **ppManageModule
);

Parameters
[out] ppManageModule

Pointer to the ICertManageModule interface associated with the ICertExit2 interface.

Return value
C++
The return value is an HRESULT . A value of S_OK indicates the method was successful.
VB
The return value is a Variant containing the ICertManageModule interface associated with the ICertExit2 interface.

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header certexit.h (include Certsrv.h)

 certif.h header
7/2/2022 • 2 minutes to read • Edit Online

This header is used by Security and Identity. For more information, see:
Security and Identity
certif.h contains the following programming interfaces:

Interfaces

ICertServerExit

Exported by the server engine and is called by exit modules.

ICertServerPolicy

Allows the policy module to communicate with Certificate Services.

 ICertServerExit interface (certif.h)
7/2/2022 • 2 minutes to read • Edit Online

The ICer tSer verExit interface is exported by the server engine and is called by exit modules.
ICer tSer verExit allows exit modules to get and enumerate elements of requests and certificates.
ICer tSer verExit is defined in Certif.h. When you create your program, however, use Certsrv.h as the include
file. Certcli.dll provides the ICer tSer verExit interface. The type information for this interface is also in
Certclil.dll, which is shipped with the Platform Software Development Kit (SDK).
Certificate Services interfaces support both apartment-threading and free-threading models. For better
throughput, free threading is recommended.

Inheritance
The ICer tSer verExit interface inherits from the IDispatch interface. ICer tSer verExit also has these types of
members:

Methods
The ICer tSer verExit interface has these methods.

ICertServerExit::EnumerateAttributes

Returns the name of the next request attribute within the current context, then increments the internal pointer to the
following attribute.

ICertServerExit::EnumerateAttributesClose

Frees any resources connected with attribute enumeration.

ICertServerExit::EnumerateAttributesSetup

Initializes the internal enumeration pointer to the first request attribute associated with the current context.

ICertServerExit::EnumerateExtensions

Returns the object identifier (OID) string (also known as the extension name) of the next certificate extension to be
enumerated, then increments the internal pointer to the following extension.

ICertServerExit::EnumerateExtensionsClose

Frees any resources connected with extension enumeration.

ICertServerExit::EnumerateExtensionsSetup

Initializes the internal enumeration pointer to the first certificate extension associated with the current context.
 ICertServerExit::GetCertificateExtension

Gets a specified certificate extension.

ICertServerExit::GetCertificateExtensionFlags

Gets the flags from the extension acquired by the most recent call to ICertServerExit::GetCertificateExtension.

ICertServerExit::GetCertificateProperty

Returns a named property from a certificate.

ICertServerExit::GetRequestAttribute

Returns a named attribute value from a request.

ICertServerExit::GetRequestProperty

Returns a named property from a request.

ICertServerExit::SetContext

Causes the current instantiation of the interface to operate on the request referenced by Context.

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header certif.h (include Certsrv.h)

 ICertServerExit::EnumerateAttributes method
(certif.h)
7/2/2022 • 2 minutes to read • Edit Online

The EnumerateAttributes method returns the name of the next request attribute within the current context,
then increments the internal pointer to the following attribute.
Before calling EnumerateAttributes , an application calls ICertServerExit::EnumerateAttributesSetup. When
done enumerating, an application calls ICertServerExit::EnumerateAttributesClose.

Syntax
HRESULT EnumerateAttributes(
[out] BSTR *pstrAttributeName
);

Parameters
[out] pstrAttributeName

A pointer to the enumerated attribute name.

Return value
C++
If the method succeeds, the method returns S_OK, and *pstrAttributeName is set to the BSTR that contains the
name of the enumerated attribute. A value of S_FALSE is returned if the last attribute was already enumerated.
To use this method, create a variable of BSTR type, set the variable equal to NULL , and pass the address of this
variable as pstrAttributeName.
When you have finished using the BSTR , free it by calling the SysFreeString function.
If the method fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.
VB
Returns a string that contains the name of the enumerated attribute, or an empty string if the last attribute was
already enumerated.

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

 Header certif.h (include Certsrv.h)

Librar y Certidl.lib

DLL Certcli.dll

See also
ICertServerExit
ICertServerExit::EnumerateAttributesClose
ICertServerExit::EnumerateAttributesSetup
ICertServerExit::GetRequestAttribute
 ICertServerExit::EnumerateAttributesClose method
(certif.h)
7/2/2022 • 2 minutes to read • Edit Online

The EnumerateAttributesClose method frees any resources connected with attribute enumeration.
All applications that use ICertServerExit::EnumerateAttributesSetup or ICertServerExit::EnumerateAttributes
should call EnumerateAttributesClose when finished enumerating.

Syntax
HRESULT EnumerateAttributesClose();

Return value
VB
If the method succeeds, the method returns S_OK.
If the method fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header certif.h (include Certsrv.h)

Librar y Certidl.lib

DLL Certcli.dll

See also
ICertServerExit
ICertServerExit::EnumerateAttributes
ICertServerExit::EnumerateAttributesSetup
 ICertServerExit::EnumerateAttributesSetup method
(certif.h)
7/2/2022 • 2 minutes to read • Edit Online

The EnumerateAttributesSetup method initializes the internal enumeration pointer to the first request
attribute associated with the current context.

Syntax
HRESULT EnumerateAttributesSetup(
[in] LONG Flags
);

Parameters
[in] Flags

This parameter is reserved and must be set to zero.

Return value
VB
If the method succeeds, the method returns S_OK.
If the method fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.

Remarks
You must call ICertServerExit::SetContext prior to using this method.
Examples

// Set up the enumeration.

hr = pCertServerExit->EnumerateAttributesSetup(0);
if (FAILED(hr))
{
printf("Failed EnumerateAttributesSetup [%x]\n", hr);
goto error;
}

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]
 Target Platform Windows

Header certif.h (include Certsrv.h)

Librar y Certidl.lib

DLL Certcli.dll

See also
ICertServerExit
ICertServerExit::EnumerateAttributes
 ICertServerExit::EnumerateExtensions method
(certif.h)
7/2/2022 • 2 minutes to read • Edit Online

The EnumerateExtensions method returns the object identifier (OID) string (also known as the extension
name) of the next certificate extension to be enumerated, then increments the internal pointer to the following
extension.
Before calling EnumerateExtensions , an application calls ICertServerExit::EnumerateExtensionsSetup. When
done enumerating, an application calls ICertServerExit::EnumerateExtensionsClose.

Syntax
HRESULT EnumerateExtensions(
[out] BSTR *pstrExtensionName
);

Parameters
[out] pstrExtensionName

A pointer to the enumerated extension name.

Return value
C++
If the method succeeds, the method returns S_OK, and *pstrExtensionName is set to the BSTR that contains the
name of the enumerated extension. A value of S_FALSE is returned if the last extension was already enumerated.
To use this method, create a variable of BSTR type, set the variable equal to NULL , and pass the address of this
variable as pstrExtensionName.
When you have finished using the BSTR , free it by calling the SysFreeString function.
If the method fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.
VB
Returns a string that contains the name of the enumerated extension, or an empty string if the last extension was
already enumerated.

Remarks
This method enumerates certificate extensions recorded in the database, even those that are disabled and do
not appear in the certificate. To determine whether an extension is disabled, use
ICertServerExit::GetCertificateExtensionFlags to test the extension's EXTENSION_DISABLE_FLAG bit.
Examples
 BSTR bstrExt = NULL;
VARIANT varExt;
LONG ExtFlags;
HRESULT hr;

VariantInit(&varExt);

// Enumerate the extensions.

while (S_OK ==
(hr = pCertServerExit->EnumerateExtensions(&bstrExt)))
{
// Retrieve the extension data.
if (FAILED(pCertServerExit->GetCertificateExtension(
bstrExt,
PROPTYPE_BINARY,
&varExt)))
printf("Failed GetCertificateExtension\n");
else
{
// Retrieve the extension flags.
if (FAILED(pCertServerExit->GetCertificateExtensionFlags(
&ExtFlags)))
printf("Failed GetCertificateExtensionFlags\n");
else
// This sample will display the extension OID string,
// the extension flags (in hex) and
// the length of the BSTR binary ASN-encode extension.
printf("Extension: %ws\tFlags:%x\tLength:%u\n",
bstrExt,
ExtFlags,
SysStringByteLen(varExt.bstrVal));
}
}
// Determine if hr was S_FALSE, meaning the enumeration
// was completed, or some other error.
if (S_FALSE != hr)
printf("Failed EnumerateExtensions - %x\n", hr);
// Free BSTR resource.
if (NULL != bstrExt)
SysFreeString(bstrExt);
// Free VARIANT resource.
VariantClear(&varExt);

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header certif.h (include Certsrv.h)

Librar y Certidl.lib

DLL Certcli.dll

See also
ICertServerExit
ICertServerExit::EnumerateExtensionsClose
ICertServerExit::EnumerateExtensionsSetup
ICertServerExit::GetCertificateExtension
ICertServerExit::GetCertificateExtensionFlags
 ICertServerExit::EnumerateExtensionsClose method
(certif.h)
7/2/2022 • 2 minutes to read • Edit Online

The EnumerateExtensionsClose method frees any resources connected with extension enumeration.
All applications that use ICertServerExit::EnumerateExtensionsSetup and ICertServerExit::EnumerateExtensions
should call EnumerateExtensionsClose when finished enumerating.

Syntax
HRESULT EnumerateExtensionsClose();

Return value
None

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header certif.h (include Certsrv.h)

Librar y Certidl.lib

DLL Certcli.dll

See also
CCer tSer verExit
ICertServerExit
 ICertServerExit::EnumerateExtensionsSetup method
(certif.h)
7/2/2022 • 2 minutes to read • Edit Online

The EnumerateExtensionsSetup method initializes the internal enumeration pointer to the first certificate
extension associated with the current context.
The enumeration process enumerates certificate extensions recorded in the database, even those that are
disabled and do not appear in the certificate.

Syntax
HRESULT EnumerateExtensionsSetup(
[in] LONG Flags
);

Parameters
[in] Flags

This parameter is reserved and must be set to zero.

Return value
VB
If the method succeeds, the method returns S_OK.
If the method fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.

Remarks
You must call ICertServerExit::SetContext before using this method.
Examples

// Set the context. The value nContext (long) would be the same
// as the context parameter in ICertExit::Notify.
// hr is defined as an HRESULT.
hr = pCertServerExit->SetContext( nContext );
if (FAILED(hr))
{
printf("Failed SetContext [%x]\n", hr);
goto error;
}

// Setup the enumeration.

hr = pCertServerExit->EnumerateExtensionsSetup( 0 );
if (FAILED(hr))
{
printf("Failed EnumerateExtensionsSetup [%x]\n", hr);
goto error;
}
Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header certif.h (include Certsrv.h)

Librar y Certidl.lib

DLL Certcli.dll

See also
ICertServerExit
ICertServerExit::EnumerateExtensions
ICertServerExit::EnumerateExtensionsClose
 ICertServerExit::GetCertificateExtension method
(certif.h)
7/2/2022 • 2 minutes to read • Edit Online

The GetCer tificateExtension method gets a specified certificate extension.

Note that certificate extensions are distinct from certificate properties. Properties are generic data attached to
the request object. Some of these properties are encoded into the certificate (example: BeginDate), while others
are just used to mark requests in the queue and log. Extensions that are not disabled are encoded into the
certificate. Extensions are always marked with an object identifier and always have a critical/noncritical flag.

Syntax
HRESULT GetCertificateExtension(
[in] const BSTR strExtensionName,
[in] LONG Type,
[out] VARIANT *pvarValue
);

Parameters
[in] strExtensionName

A string that contains the name of the extension.

[in] Type

Specifies the type of the extension. The type can be one of the following types.

VA L UE M EA N IN G

Signed long data

PROPTYPE_LONG

Date/time
PROPTYPE_DATE

The extension value is retrieved as is and is ASN.1 encoded if

PROPTYPE_BINARY necessary.

The extension value is ASN.1 encoded as an IA5 string.

PROPTYPE_STRING

[out] pvarValue

A pointer to a VARIANT that receives the requested extension value.

Return value
C++
If the method succeeds, the method returns S_OK, and *pvarValue is set to the VARIANT that contains the
extension value.
If the method fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.
VB
The return value is the requested extension value.

Remarks
You must call ICertServerExit::SetContext prior to using this method.
Examples

VARIANT varExt;
HRESULT hr;

VariantInit(&varExt);
// Get the Extension value
// bstrExtName is BSTR assigned by EnumerateExtensions.
// pCertServerExit has been used to call SetContext previously.
hr = pCertServerExit->GetCertificateExtension(bstrExtName,
PROPTYPE_BINARY,
&varExt);

if (FAILED(hr))
{
printf("Failed GetCertificateExtension [%x]\n", hr);
goto error;
}
// Successful call; Use the value in varExt as needed.
// ...

// When done, clear the Variant

VariantClear(&varExt);

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header certif.h (include Certsrv.h)

Librar y Certidl.lib

DLL Certcli.dll

See also
ICertServerExit
ICertServerExit::GetCertificateExtensionFlags
ICertServerExit::SetContext
 ICertServerExit::GetCertificateExtensionFlags
method (certif.h)
7/2/2022 • 2 minutes to read • Edit Online

The GetCer tificateExtensionFlags method gets the flags from the extension acquired by the most recent call
to ICertServerExit::GetCertificateExtension.

Syntax
HRESULT GetCertificateExtensionFlags(
[out] LONG *pExtFlags
);

Parameters
[out] pExtFlags

A pointer to a LONG variable that will contain the extension flags.

Return value
C++
If the method succeeds, the method returns S_OK, and *pExtFlags is set to the variable that contains the flags from
the extension acquired by the most recent call to ICertServerExit::GetCertificateExtension.
If the method fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.
VB
The return value is the flags from the extension acquired by the most recent call to
ICertServerExit::GetCertificateExtension.

Remarks
There are two kinds of flags used in extensions: policy flags and origin flags.

FLAG T YPE EXP L A N AT IO N

Policy Provides information about the certificate extension. Policy

flags can be set by the policy module.

Origin Indicates the module that set the certificate extension.

Origin flags are only set by the server engine.

One or more policy flags can be returned from an extension. The following are predefined policy flags.

P O L IC Y F L A G VA L UE EXP L A N AT IO N
 EXTENSION_CRITICAL_FLAG This is a critical extension.

EXTENSION_DISABLE_FLAG Extension will not be used.

One of the following origin flags can also be returned.

O RIGIN F L A G VA L UE EXP L A N AT IO N

EXTENSION_ORIGIN_REQUEST The extension was extracted from an array of extensions

stored in the szOID_CERT_EXTENSIONS
(1.3.6.1.4.1.311.2.1.14) or szOID_RSA_certExtensions
(1.2.840.113549.1.9.14) attribute of a PKCS #10 request.

EXTENSION_ORIGIN_POLICY The policy module set the extension.

EXTENSION_ORIGIN_ADMIN The administrator set the extension. For more information,

see ICertAdmin::SetCertificateExtension.

EXTENSION_ORIGIN_SERVER The server engine set the extension.

EXTENSION_ORIGIN_RENEWALCERT The extension was extracted from the certificate stored in

the szOID_RENEWAL_CERTIFICATE (1.3.6.1.4.1.311.13.1)
attribute of a PKCS #10 renewal request.

EXTENSION_ORIGIN_IMPORTEDCERT The extension was extracted from an imported certificate

(the certificate was passed to ICertAdmin::ImportCertificate).

EXTENSION_ORIGIN_PKCS7 The extension was extracted from an array of extensions

stored in the szOID_CERT_EXTENSIONS
(1.3.6.1.4.1.311.2.1.14) or szOID_RSA_certExtensions
(1.2.840.113549.1.9.14) attribute of a PKCS #7 request.

Predefined masks are provided for ease of use in determining which flags are set in the return value. The
following masks are provided.

M A SK VA L UE EXP L A N AT IO N

EXTENSION_POLICY_MASK This value (0x0000FFFF) is used to examine policy flags.

EXTENSION_ORIGIN_MASK This value (0x000F0000) is used to examine origin flags.

It is safe to use the high 8 bits of EXTENSION_POLICY_MASK for custom data. These bits will be saved
persistently in the database but will not be written to the certificate extensions.
You must call ICertServerExit::SetContext prior to using this method.
Examples
 HRESULT hr;
LONG ExtFlags;

// pCertServerExit has been used to call SetContext previously.

hr = pCertServerExit->GetCertificateExtensionFlags(&ExtFlags);

// More than one policy flag may be set.

LONG ExtPolicyFlags = ExtFlags & EXTENSION_POLICY_MASK;

if (ExtPolicyFlags & EXTENSION_CRITICAL_FLAG)

{
// Perform the desired operation.
}

if (ExtPolicyFlags & EXTENSION_DISABLE_FLAG)

{
// Perform the desired operation.
}

// Only one origin flag can be set.

switch (ExtFlags & EXTENSION_ORIGIN_MASK)
{
case EXTENSION_ORIGIN_REQUEST:
// Extension was set in certificate request.
break;
case EXTENSION_ORIGIN_POLICY:
// Extension was set by policy module.
break;
case EXTENSION_ORIGIN_ADMIN:
// Extension was set by administrator.
break;
case EXTENSION_ORIGIN_SERVER:
// Extension was set by server engine.
break;
case EXTENSION_ORIGIN_RENEWALCERT:
// Extension was set by renewal certificate.
break;
case EXTENSION_ORIGIN_IMPORTEDCERT:
// Extension was set by imported certificate.
break;
case EXTENSION_ORIGIN_PKCS7:
// Extension was set by PKCS #7.
break;
default:
break;
}

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header certif.h (include Certsrv.h)

Librar y Certidl.lib
 DLL Certcli.dll

See also
CCer tSer verExit
ICertAdmin::SetCertificateExtension
ICertServerExit
ICertServerExit::GetCertificateExtension
IEnumCERTVIEWEXTENSION::GetFlags
 ICertServerExit::GetCertificateProperty method
(certif.h)
7/2/2022 • 5 minutes to read • Edit Online

The GetCer tificateProper ty method returns a named property from a certificate.

Syntax
HRESULT GetCertificateProperty(
[in] const BSTR strPropertyName,
[in] LONG PropertyType,
[out] VARIANT *pvarPropertyValue
);

Parameters
[in] strPropertyName

Specifies the named property to retrieve. There is a stock set of certificate properties, referred to as the
name properties, that are always valid and can be retrieved by calling this method. For information about these
properties, see Name Properties. Other properties that can be retrieved include the certificate properties.
The following properties are unique to certificates and can be read by GetCer tificateProper ty .

VA L UE M EA N IN G

Certificate start validity date

NotBefore
Date/Time

Certificate expiration date

NotAfter
Date/Time

Subject key algorithm object identifier (OID)

PublicKeyAlgorithm
String

Raw certificate bytes

RawCer tificate
Binary

Subject key
RawPublicKey
Binary

Subject key algorithm parameters

RawPublicKeyAlgorithmParameters
Binary
 Internal request ID
RequestID
Signed Long

Certificate serial number

SerialNumber
String

The certificate's DistinguishedName, RawName, and SerialNumber properties are accessible by

GetCer tificateProper ty only after the policy module has finished processing the request and the certificate is
issued.
The following properties apply to the certification authority. The context must be zero to read any of these
properties. The context is set to zero when the ICertServerExit object is initially created. It can also be set to zero
by invoking the SetContext method.

VA L UE M EA N IN G

Type of certification authority. This can be one of the

CAType following values (defined in Certsrv.h):
Long
ENUM_ENTERPRISE_ROOTCA
ENUM_ENTERPRISE_SUBCA
ENUM_STANDALONE_ROOTCA
ENUM_STANDALONE_SUBCA

Number of CA certificates. This value will be one plus the

Cer tCount number of times that the CA has been renewed. For
Long information about renewal, see Certification Authority
Renewal.

CA certificate state. This can be one of the following values:

Cer tState
Long CA_DISP_ERROR: The CA certificate was never issued.
CA_DISP_REVOKED: The CA certificate has been revoked.
CA_DISP_VALID: The CA certificate is still valid.
CA_DISP_INVALID: The CA certificate has expired.
This property name may be appended with '.#', where #
represents a CA certificate index (or, in the case of the
CRLSuffix property, a CRL index). For information about
certificate and CRL indices, see Certification Authority
Renewal.
 Suffix for the CA certificate. The suffix is an empty string for
Cer tSuffix CA certificates with an index of zero; otherwise, the suffix (in
String the form of "(nn)", where nn is the certificate index) is applied
to all URLs that point to CA certificates stored in files or
directory service objects. For non-LDAP URLs, the suffix
typically appears before the ".crt" text. For LDAP URLs, the
suffix is typically appended to the first 'CN=' in the full
distinguished name.
This property name may be appended with '.#', where #
represents a CA certificate index (or, in the case of the
CRLSuffix property, a CRL index). For information about
certificate and CRL indices, see Certification Authority
Renewal.

Certificate revocation list (CRL) index. Appending a certificate

CRLIndex index to this property name allows you to retrieve the CRL
Long index. The CRL index does not necessarily match the
certificate index. For more information, see Certification.
This property name may be appended with '.#', where #
represents a CA certificate index (or, in the case of the
CRLSuffix property, a CRL index). For information about
certificate and CRL indices, see Certification Authority
Renewal.

CRL state. This can be one of the following values:

CRLState
Long CA_DISP_ERROR: The CRL is managed by another CA
certificate.
CA_DISP_REVOKED: All unexpired CA certificates that use
this CA certificate's CRL have been revoked.
CA_DISP_VALID: The CA certificate is still being used to
publish CRLs as needed.
CA_DISP_INVALID: All CA certificates that use this CA
certificate's CRL are expired.
This property name may be appended with '.#', where #
represents a CA certificate index (or, in the case of the
CRLSuffix property, a CRL index). For information about
certificate and CRL indices, see Certification Authority
Renewal.

Suffix for the CA CRL. The suffix is an empty string for CRLs
CRLSuffix with an index of zero; otherwise, the suffix (in the form of "(
String nn)", where nn is the CRL index) is applied to all URLs
pointing to CRLs stored in files or directory service objects.
For non-LDAP URLs, the suffix typically appears before the
".crl" text. For LDAP URLs, the suffix typically is appended to
the first 'CN=' in the full distinguished name.
This property name may be appended with '.#', where #
represents a CA certificate index (or, in the case of the
CRLSuffix property, a CRL index). For information about
certificate and CRL indices, see Certification Authority
Renewal.

Indicates whether the CA uses a directory service. This can

fUseDS be either of the following values:
Long 0=no
1=yes
 DNS name of server hosting the CA.
MachineDNSName
String

Registry location available for use by the module.

ModuleRegistr yLocation
String

CA certificate.
RawCACer tificate
This property name may be appended with '.#', where #
Binary
represents a CA certificate index (or, in the case of the
CRLSuffix property, a CRL index). For information about
certificate and CRL indices, see Certification Authority
Renewal.

CA's certificate revocation list (CRL).

RawCRL
This property name may be appended with '.#', where #
Binary
represents a CA certificate index (or, in the case of the
CRLSuffix property, a CRL index). For information about
certificate and CRL indices, see Certification Authority
Renewal.

Indicates whether the requester is authorized to request the

RequesterCAAccess certificate. This can be either of the following values:
Long 0=no
1=yes
(The Certification Authority MMC snap-in can be used to
control certificate request permissions.)

Sanitized name for the CA. For information about sanitized

SanitizedCAName CA names, see ICertConfig::GetConfig.
String

Sanitized name for the CA, shortened and containing a hash

SanitizedShor tName value to ensure uniqueness.
String

[in] PropertyType

Specifies the property type. The type can be one of the following.

VA L UE M EA N IN G

Signed long data

PROPTYPE_LONG

Date/time
PROPTYPE_DATE

Binary data
PROPTYPE_BINARY
 Unicode string data
PROPTYPE_STRING

[out] pvarPropertyValue

A pointer to a VARIANT that will contain the property value. The returned value is encoded as a BSTR . Use the
SysStringByteLen function to retrieve the length of the BSTR . The binary BLOB is stored as a Distinguished
Encoding Rules encoded X.509 certificate.

Return value
C++
If the method succeeds, the method returns S_OK.
If the method fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.
VB
The return value is the requested property value.

Remarks
You must call ICertServerExit::SetContext prior to using this method.
Examples

BSTR bstrPropName = NULL;

VARIANT varProp;

VariantInit(&varProp);

// Set the property name to RequestID.

bstrPropName = SysAllocString(L"RequestID");

// Retrieve the certificate property.

// pCertServerExit has been used to call SetContext previously.
hr = pCertServerExit->GetCertificateProperty(bstrPropName,
PROPTYPE_LONG,
&varProp );
if (FAILED(hr))
{
printf("Failed GetCertificateProperty [%x]\n", hr);
goto error;
}
else
{
// Successfully retrieved property; use varProp as needed.
// ...
}

// Done processing.
if (NULL != bstrPropName)
SysFreeString(bstrPropName);
VariantClear(&varProp);

Requirements
 Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header certif.h (include Certsrv.h)

Librar y Certidl.lib

DLL Certcli.dll

See also
ICertServerExit
ICertServerExit::SetContext
Name Properties
 ICertServerExit::GetRequestAttribute method
(certif.h)
7/2/2022 • 2 minutes to read • Edit Online

The GetRequestAttribute method returns a named attribute value from a request.

Prior to calling this method, it is necessary to call ICertServerExit::SetContext.

Syntax
HRESULT GetRequestAttribute(
[in] const BSTR strAttributeName,
[out] BSTR *pstrAttributeValue
);

Parameters
[in] strAttributeName

The name of the attribute to retrieve.

[out] pstrAttributeValue

A pointer to a BSTR value that will contain the attribute value.

Return value
C++
If the method succeeds, the method returns S_OK, and *pstrAttributeValue is set to the BSTR that contains the
attribute value.
To use this method, create a variable of type BSTR , set the variable equal to NULL , and pass the address of this
variable as pstrAttributeValue.
When you have finished using the BSTR , free it by calling the SysFreeString function.
If the method fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.
VB
The return value is a string that represents the attribute value.

Remarks
You must call ICertServerExit::SetContext prior to using this method.
The following request attributes are unique to KEYGEN style requests.

P RO P ERT Y N A M E TYPE DESC RIP T IO N

Challenge String Challenge string that accompanies the

request.
 ExpectedChallenge String If the challenge string is incorrect, then
the server will set the value of this
request attribute to the expected
challenge so that failure can be
diagnosed.

Examples

BSTR bstrAttribValue = NULL;

HRESULT hr;

// Get the request attribute.

// bstrAttribName is a BSTR assigned by EnumerateAttributes.
// Also, ICertServerExit::SetContext has already been
// called by pCertServerExit.
hr = pCertServerExit->GetRequestAttribute(bstrAttribName,
&bstrAttribValue);

if (FAILED(hr))
{
printf("Failed GetRequestAttribute [%x]\n", hr);
goto error;
}
else
{

// Successful call. Use bstrAttribValue as needed.

// ...
}

// Done processing. Free BSTR.

if (NULL != bstrAttribValue)
SysFreeString(bstrAttribValue);

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header certif.h (include Certsrv.h)

Librar y Certidl.lib

DLL Certcli.dll

See also
ICertServerExit
ICertServerExit::SetContext
 ICertServerExit::GetRequestProperty method
(certif.h)
7/2/2022 • 2 minutes to read • Edit Online

The GetRequestProper ty method returns a named property from a request.

Note that the request is used to hold all associated states for the request and the eventual granted certificate
that is not a part of the certificate. Thus, data such as revocation times and disposition data are kept in the
request data object.

Syntax
HRESULT GetRequestProperty(
[in] const BSTR strPropertyName,
[in] LONG PropertyType,
[out] VARIANT *pvarPropertyValue
);

Parameters
[in] strPropertyName

Specifies the property to retrieve. There is a stock set of certificate properties, referred to as the name
properties, that are always valid and can be retrieved by calling this method. For information about these
properties, see Name Properties.
Other properties valid for certificate requests include the request properties.

Note The request's DistinguishedName and RawName properties are accessible by GetRequestProper ty only if the
certificate is requested by using a PKCS #10 certificate request or another supported request format that contains encoded
subject name information. Note that KeyGen requests do not contain encoded subject name information.

The following properties are unique to requests and can be accessed by using the GetRequestProper ty
method.

REQ UEST P RO P ERT Y M EA N IN G

Current request disposition

Disposition
Signed long

Informational disposition message

DispositionMessage
String

Certificate for the issuing certification authority

RawCACer tificate
Binary
 Raw request bytes
RawRequest
Binary

Attribute string (can be truncated)

RequestAttributes
String

The name of the requester in the form "DomainName\

RequesterName UserID"
String

Internal requestID
RequestID
Signed long

Indicates PKCS #10 or KeyGen request

RequestType
Signed long

When resolved
ResolvedWhen
Date/time

Windows error for last operation

StatusCode
Signed long

When arrived
SubmittedWhen
Date/time

The RequestType property will be one of the following values.

VA L UE M EA N IN G

PKCS #7 renewal or registration request

CR_IN_PKCS7

PKCS #10 request

CR_IN_PKCS10

Keygen request (Netscape format)

CR_IN_KEYGEN

In addition, other properties may be set by a specific request type, request extensions, or by named attributes
set in the header of a request.
[in] PropertyType

Specifies the property type. The type can be one of the following types.
 VA L UE M EA N IN G

Signed long data

PROPTYPE_LONG

Date/time
PROPTYPE_DATE

Binary data
PROPTYPE_BINARY

Unicode string data

PROPTYPE_STRING

[out] pvarPropertyValue

A pointer to the VARIANT that will contain the request property type.

Return value
C++
If the method succeeds, the method returns S_OK, and *pvarPropertyValue is set to the VARIANT that contains the
request property value.
If the method fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.
VB
The return value is the request property value.

Remarks
You must call ICertServerExit::SetContext prior to using this method.
Examples
 BSTR bstrPropName = NULL;
VARIANT varProp;

VariantInit( &varProp );

bstrPropName = SysAllocString(L"RequestID");

// Retrieve the request property.

// pCertServerExit has been used to call SetContext previously.
hr = pCertServerExit->GetRequestProperty( bstrPropName,
PROPTYPE_LONG,
&varProp );
if (FAILED(hr))
{
printf("Failed GetRequestProperty [%x]\n", hr);
goto error;
}
else
{
// Successfully retrieved property; use varProp as needed.
// ...
}

// Done processing.
VariantClear( &varProp );
if ( NULL != bstrPropName )
SysFreeString( bstrPropName );

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header certif.h (include Certsrv.h)

Librar y Certidl.lib

DLL Certcli.dll

See also
ICertServerExit
ICertServerExit::SetContext
Name Properties
 ICertServerExit::SetContext method (certif.h)
7/2/2022 • 2 minutes to read • Edit Online

The SetContext method causes the current instantiation of the interface to operate on the request referenced
by Context.
This must be identical to a value given by the Context parameter in ICertExit::Notify. This method must be called
before calling any of the other ICertServerExit methods, in order that the interface reference a valid request.

Syntax
HRESULT SetContext(
[in] LONG Context
);

Parameters
[in] Context

Specifies the request and associated certificate under construction.

Return value
VB
If the method succeeds, the method returns S_OK.
If the method fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header certif.h (include Certsrv.h)

Librar y Certidl.lib

DLL Certcli.dll

See also
ICertExit::Notify
ICertPolicy::VerifyRequest
ICertServerExit
 ICertServerPolicy interface (certif.h)
7/2/2022 • 2 minutes to read • Edit Online

The ICer tSer verPolicy interface allows the policy module to communicate with Certificate Services.

Note Certificate Services communicates with the policy module through the ICertPolicy2 interface.

The ICer tSer verPolicy interface is exported by the server engine and is called by the policy module to perform the
following tasks:
Specify which certificate request is used as the current context for subsequent operations.
Enumerate and retrieve the extensions (including extension flags) of a certificate request, and set the
extensions of the issued certificate.
Enumerate and retrieve request attributes.
Retrieve certificate request properties.
Retrieve and set certificate properties.
From the time the ICertPolicy::VerifyRequest method is called until it returns, the unresolved request and
certificate under construction can be accessed through a Context data object. Because the policy module can add
to or override request properties by calling ICertServerPolicy::SetCertificateProperty, certificate properties can
differ from request properties.
ICer tSer verPolicy is defined in Certif.h. When you create your program, however, use Certsrv.h as the include
file. Certcli.dll provides the ICer tSer verPolicy interface. The type information for this interface is also in
Certclil.dll, which is shipped with the Platform Software Development Kit (SDK).
Certificate Services interfaces support both apartment-threading and free-threading models. For better
throughput, free threading is recommended.

Inheritance
The ICer tSer verPolicy interface inherits from the IDispatch interface. ICer tSer verPolicy also has these types
of members:

Methods
The ICer tSer verPolicy interface has these methods.

ICertServerPolicy::EnumerateAttributes

Retrieves the name of the current attribute and moves the internal enumeration pointer to the next attribute.

ICertServerPolicy::EnumerateAttributesClose

Frees the resources connected with attribute enumeration.

 ICertServerPolicy::EnumerateAttributesSetup

Initializes the internal enumeration pointer to the first request attribute associated with the current context.

ICertServerPolicy::EnumerateExtensions

Retrieves the object identifier (OID) of the current extension and moves the internal enumeration pointer to the next
extension.

ICertServerPolicy::EnumerateExtensionsClose

Frees the resources connected with extension enumeration.

ICertServerPolicy::EnumerateExtensionsSetup

Initializes the internal enumeration pointer to the first certificate extension associated with the current context.

ICertServerPolicy::GetCertificateExtension

Retrieves a specific certificate extension.

ICertServerPolicy::GetCertificateExtensionFlags

Retrieves the flags associated with the extension acquired by the most recent call to GetCertificateExtension.

ICertServerPolicy::GetCertificateProperty

Returns a named property from a certificate.

ICertServerPolicy::GetRequestAttribute

Returns a named attribute from a request.

ICertServerPolicy::GetRequestProperty

Retrieves a specific property from a request.

ICertServerPolicy::SetCertificateExtension

Adds a new extension to the certificate.

ICertServerPolicy::SetCertificateProperty

To set a property associated with a certificate.

ICertServerPolicy::SetContext

Specifies the request to be used as the context for subsequent calls to Certificate Services.

Requirements

Minimum suppor ted client None supported

 Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header certif.h (include Certsrv.h)

See also
ICertAdmin::ResubmitRequest
ICertAdmin::SetRequestAttributes
ICertPolicy::VerifyRequest
ICertRequest
ICertRequest::Submit
IDispatch
 ICertServerPolicy::EnumerateAttributes method
(certif.h)
7/2/2022 • 2 minutes to read • Edit Online

The EnumerateAttributes method retrieves the name of the current attribute and moves the internal
enumeration pointer to the next attribute.

Syntax
HRESULT EnumerateAttributes(
[out] BSTR *pstrAttributeName
);

Parameters
[out] pstrAttributeName

A pointer to the attribute name.

Return value
C++
If the method succeeds, the method returns S_OK, and the pstrAttributeName parameter is set to a BSTR that
contains the name of the attribute. A value of S_FALSE is returned if the last attribute was already enumerated.
To use this method, create a variable of BSTR type, set the variable equal to NULL , and then pass the address of
this variable as pstrAttributeName.
When you have finished using the BSTR , free it by calling the SysFreeString function.
If the method fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.
VB
Returns a string that contains the name of the attribute, or an empty string if the last attribute was already
enumerated.

Remarks
Before calling the EnumerateAttributes method for the first time, call the EnumerateAttributesSetup method
to initialize the enumeration pointer to the first attribute.
When done enumerating, call
the EnumerateAttributesClose method to free resources used by the enumeration calls.

Requirements
 Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header certif.h (include Certsrv.h)

Librar y Certidl.lib

DLL Certcli.dll

See also
ICertServerPolicy
ICertServerPolicy::EnumerateAttributesClose
ICertServerPolicy::EnumerateAttributesSetup
 ICertServerPolicy::EnumerateAttributesClose
method (certif.h)
7/2/2022 • 2 minutes to read • Edit Online

The EnumerateAttributesClose method frees the resources connected with attribute enumeration.

Syntax
HRESULT EnumerateAttributesClose();

Return value
VB
If the method succeeds, the method returns S_OK.
If the method fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.

Remarks
All policy modules should call the EnumerateAttributesClose method after calling the
EnumerateAttributesSetup and
EnumerateAttributes methods.
Examples

// Close the enumeration.

// hr is defined as an HRESULT.
hr = pCertServerPolicy->EnumerateAttributesClose();
if (FAILED(hr))
{
printf("Failed EnumerateAttributesClose [%x]\n", hr);
goto error;
}

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header certif.h (include Certsrv.h)

Librar y Certidl.lib
 DLL Certcli.dll

See also
ICertServerPolicy
ICertServerPolicy::EnumerateAttributes
ICertServerPolicy::EnumerateAttributesSetup
 ICertServerPolicy::EnumerateAttributesSetup
method (certif.h)
7/2/2022 • 2 minutes to read • Edit Online

The EnumerateAttributesSetup method initializes the internal enumeration pointer to the first request
attribute associated with the current context.

Syntax
HRESULT EnumerateAttributesSetup(
[in] LONG Flags
);

Parameters
[in] Flags

This parameter is reserved and must be set to zero.

Return value
VB
If the method succeeds, the method returns S_OK.
If the method fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.

Remarks
The SetContext method must be called prior to calling this method. The call to SetContext specifies which
request to use as the current context.
To retrieve the attribute, call the EnumerateAttributes method. The call to EnumerateAttributes retrieves the
first attribute and moves the index to the next attribute if one exists.
Examples
 // Set the context. The value nContext (long) would be the same
// as the context parameter in ICertPolicy::VerifyRequest.
// hr is defined as an HRESULT.
// pCertServerPolicy has been used to call SetContext previously.
hr = pCertServerPolicy->SetContext(nContext);
if (FAILED(hr))
{
printf("Failed SetContext [%x]\n", hr);
goto error;
}

// Setup the enumeration.

hr = pCertServerPolicy->EnumerateAttributesSetup(0);
if (FAILED(hr))
{
printf("Failed EnumerateAttributesSetup [%x]\n", hr);
goto error;
}

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header certif.h (include Certsrv.h)

Librar y Certidl.lib

DLL Certcli.dll

See also
ICertServerPolicy
ICertServerPolicy::EnumerateAttributes
ICertServerPolicy::EnumerateAttributesClose
ICertServerPolicy::SetContext
 ICertServerPolicy::EnumerateExtensions method
(certif.h)
7/2/2022 • 2 minutes to read • Edit Online

The EnumerateExtensions method retrieves the object identifier (OID) of the current extension and moves the
internal enumeration pointer to the next extension.

Syntax
HRESULT EnumerateExtensions(
[out] BSTR *pstrExtensionName
);

Parameters
[out] pstrExtensionName

A pointer to a BSTR that contains the OID of the current extension.

Return value
C++
If the method succeeds, the method returns S_OK, and the pstrExtensionName parameter contains the OID of the
current extension. A value of S_FALSE is returned if the last extension was already enumerated.
To use this method, create a variable of BSTR type, set the variable equal to NULL , and pass the address of this
variable as pstrExtensionName.
When you have finished using the BSTR , free it by calling the SysFreeString function.
If the method fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.
VB
Returns a string that contains the OID of the extension, or an empty string if the last extension was already
enumerated.

Remarks
This method enumerates certificate extensions recorded in the database, even those that are disabled and do
not appear in the certificate. To determine whether an extension is disabled, use GetCertificateExtensionFlags to
test the extension's EXTENSION_DISABLE_FLAG bit.
When done enumerating, call the EnumerateExtensionsClose method to free resources used by the enumeration
calls.
Examples
 #include &lt;windows.h&gt;
#include &lt;stdio.h&gt;
#include &lt;Certif.h&gt;

BSTR bstrExt = NULL;

VARIANT varExt;
LONG ExtFlags;
HRESULT hr;

VariantInit(&amp;varExt);

// Enumerate the extensions.

while (S_OK ==
(hr = pCertServerPol-&gt;EnumerateExtensions(&amp;bstrExt)))
{
// Retrieve the extension data.
if (FAILED(pCertServerPol-&gt;GetCertificateExtension(
bstrExt,
PROPTYPE_BINARY,
&amp;varExt)))
printf("Failed GetCertificateExtension\n");
else
{
// Retrieve the extension flags.
if (FAILED(pCertServerPol-&gt;GetCertificateExtensionFlags(
&amp;ExtFlags)))
printf("Failed GetCertificateExtensionFlags\n");
else
// This sample will display the extension OID string,
// the extension flags (in hex) and
// the length of the BSTR binary ASN-encode extension.
printf("Extension: %ws\tFlags:%x\tLength:%u\n",
bstrExt,
ExtFlags,
SysStringByteLen(varExt.bstrVal));
}
}
// Determine if hr was S_FALSE, meaning the enumeration
// was completed, or some other error.
if (S_FALSE != hr)
printf("Failed EnumerateExtensions - %x\n", hr);
// Free BSTR resource.
if (NULL != bstrExt)
SysFreeString(bstrExt);
// Free VARIANT resource.
VariantClear(&amp;varExt);

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header certif.h (include Certsrv.h)

Librar y Certidl.lib
 DLL Certcli.dll

See also
EnumerateExtensionsClose
EnumerateExtensionsSetup
GetCertificateExtension
GetCertificateExtensionFlags
ICertServerPolicy
 ICertServerPolicy::EnumerateExtensionsClose
method (certif.h)
7/2/2022 • 2 minutes to read • Edit Online

The EnumerateExtensionsClose method frees the resources connected with extension enumeration.

Syntax
HRESULT EnumerateExtensionsClose();

Return value
VB
If the method succeeds, the method returns S_OK.
If the method fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.

Remarks
All policy modules should call the EnumerateExtensionsClose method after calling the
EnumerateExtensionsSetup and ICertServerPolicy::EnumerateExtensions methods.
Examples

// Close the enumeration.

// hr is defined as an HRESULT.
hr = pCertServerPolicy->EnumerateExtensionsClose();
if (FAILED(hr))
{
printf("Failed EnumerateExtensionsClose [%x]\n", hr);
goto error;
}

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header certif.h (include Certsrv.h)

Librar y Certidl.lib

DLL Certcli.dll
See also
ICertServerExit::EnumerateExtensionsSetup
ICertServerPolicy
ICertServerPolicy::EnumerateExtensions
 ICertServerPolicy::EnumerateExtensionsSetup
method (certif.h)
7/2/2022 • 2 minutes to read • Edit Online

The EnumerateExtensionsSetup method initializes the internal enumeration pointer to the first certificate
extension associated with the current context.

Syntax
HRESULT EnumerateExtensionsSetup(
[in] LONG Flags
);

Parameters
[in] Flags

This parameter is reserved and must be set to zero.

Return value
VB
If the method succeeds, the method returns S_OK.
If the method fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.

Remarks
The SetContext method must be called prior to calling this method. The call to SetContext specifies which
request is the current context.
To retrieve the extension, call the EnumerateExtensions method. The call to EnumerateExtensions retrieves the
first extension and moves the index to the next extension if one exists.
Examples
 // Set the context. The value nContext (long) would be the same
// as the context parameter in ICertPolicy::VerifyRequest.
// hr is defined as an HRESULT.
// pCertServerPolicy has been used to call SetContext previously.
hr = pCertServerPolicy->SetContext( nContext );
if (FAILED(hr))
{
printf("Failed SetContext [%x]\n", hr);
goto error;
}
// Setup the enumeration.
hr = pCertServerPolicy->EnumerateExtensionsSetup( 0 );
if (FAILED(hr))
{
printf("Failed EnumerateExtensionsSetup [%x]\n", hr);
goto error;
}

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header certif.h (include Certsrv.h)

Librar y Certidl.lib

DLL Certcli.dll

See also
EnumerateExtensions
ICertServerPolicy
SetContext
 ICertServerPolicy::GetCertificateExtension method
(certif.h)
7/2/2022 • 2 minutes to read • Edit Online

The GetCer tificateExtension method retrieves a specific certificate extension.

Syntax
HRESULT GetCertificateExtension(
[in] const BSTR strExtensionName,
[in] LONG Type,
[out] VARIANT *pvarValue
);

Parameters
[in] strExtensionName

A string that contains the name of the extension.

[in] Type

Specifies the type of the extension. The type can be one of the following values.

VA L UE M EA N IN G

Signed long data

PROPTYPE_LONG

Date/time
PROPTYPE_DATE

The extension value is retrieved as is and is ASN.1 encoded if

PROPTYPE_BINARY necessary.

The extension value is ASN.1 encoded as an IA5 string.

PROPTYPE_STRING

[out] pvarValue

A pointer to a VARIANT that receives the requested extension value.

Return value
C++
If the method succeeds, the method returns S_OK, and the pvarValue parameter contains the extension value.
If the method fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.
VB
The return value is the requested extension value.

Remarks
The SetContext method must be called prior to calling this method. The call to SetContext specifies which
request is used as the current context.
Certificate extensions are distinct from certificate properties. Properties are generic data that is attached to the
request. Some of these properties are encoded into the certificate (for example: BeginDate), while others are just
used to mark requests in the queue and log. Extensions that are not disabled are encoded into the certificate.
Extensions are always marked with an object identifier, and always have a critical/noncritical flag.
Examples

VARIANT varExt;
HRESULT hr;

VariantInit(&varExt);
// Get the Extension value.
// bstrExtName is BSTR assigned by EnumerateExtensions.
// pCertServerPolicy has been used to call SetContext previously.
hr = pCertServerPolicy->GetCertificateExtension(bstrExtName,
PROPTYPE_BINARY,
&varExt);

if (FAILED(hr))
{
printf("Failed GetCertificateExtension [%x]\n", hr);
goto error;
}
// Successful call; use the value in varExt as needed.
// ...

// When done, clear the Variant

VariantClear(&varExt);

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header certif.h (include Certsrv.h)

Librar y Certidl.lib

DLL Certcli.dll

See also
ICertServerPolicy
ICertServerPolicy::GetCertificateExtensionFlags
ICertServerPolicy::SetContext
 ICertServerPolicy::GetCertificateExtensionFlags
method (certif.h)
7/2/2022 • 2 minutes to read • Edit Online

The GetCer tificateExtensionFlags method retrieves the flags associated with the extension acquired by the
most recent call to GetCertificateExtension.

Syntax
HRESULT GetCertificateExtensionFlags(
[out] LONG *pExtFlags
);

Parameters
[out] pExtFlags

A pointer to a LONG variable that contains the extension flags.

Return value
C++
If the method succeeds, the method returns S_OK, and the pExtFlags parameter contains the flags from the
extension acquired by the most recent call to GetCertificateExtension.
If the method fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.
VB
The return value is the flags from the extension acquired by the most recent call to GetCertificateExtension.

Remarks
The SetContext and GetCertificateExtension methods must be called before GetCer tificateExtensionFlags .
The SetContext method specifies which request is used as the current context, and the
GetCer tificateExtension method retrieves the extensions for the request.
Extensions can contain policy and origin flags. Policy flags provide information about the certificate extension.
Policy flags can be set by the policy module. Origin flags indicate the module that set the certificate extension.
Origin flags are only set by the server engine.
One or more policy flags can be returned from an extension. The following are predefined policy flags.

P O L IC Y F L A G VA L UE EXP L A N AT IO N

EXTENSION_CRITICAL_FLAG This is a critical extension.

EXTENSION_DISABLE_FLAG Extension will not be used.

One of the following origin flags can also be returned.

O RIGIN F L A G VA L UE EXP L A N AT IO N

EXTENSION_ORIGIN_REQUEST The extension was extracted from an array of extensions

stored in the szOID_CERT_EXTENSIONS
(1.3.6.1.4.1.311.2.1.14) or szOID_RSA_certExtensions
(1.2.840.113549.1.9.14) attribute of a PKCS #10 request.

EXTENSION_ORIGIN_POLICY The policy module set the extension.

EXTENSION_ORIGIN_ADMIN The administrator set the extension. For more information,

see ICertAdmin::SetCertificateExtension.

EXTENSION_ORIGIN_SERVER The server engine set the extension.

EXTENSION_ORIGIN_RENEWALCERT The extension was extracted from the certificate stored in

the szOID_RENEWAL_CERTIFICATE (1.3.6.1.4.1.311.13.1)
attribute of a PKCS #10 renewal request.

EXTENSION_ORIGIN_IMPORTEDCERT The extension was extracted from an imported certificate

(the certificate was passed to ICertAdmin::ImportCertificate).

EXTENSION_ORIGIN_PKCS7 The extension was extracted from an array of extensions

stored in the szOID_CERT_EXTENSIONS
(1.3.6.1.4.1.311.2.1.14) or szOID_RSA_certExtensions
(1.2.840.113549.1.9.14) attribute of a PKCS #7 request.

Predefined masks are provided for ease of use in determining which flags are set in the return value. The
following masks are provided.

M A SK VA L UE EXP L A N AT IO N

EXTENSION_POLICY_MASK This value (0x0000FFFF) is used to examine policy flags.

EXTENSION_ORIGIN_MASK This value (0x000F0000) is used to examine origin flags.

It is safe to use the high 8 bits of EXTENSION_POLICY_MASK for custom data. These bits will be saved
persistently in the database, but will not be written to the certificate extensions.
Examples
 HRESULT hr;
LONG ExtFlags;
// pCertServerPolicy has been used to call SetContext previously.
hr = pCertServerPolicy->GetCertificateExtensionFlags( &ExtFlags);

// More than one policy flag might be set.

LONG ExtPolicyFlags = ExtFlags & EXTENSION_POLICY_MASK;

if (ExtPolicyFlags & EXTENSION_CRITICAL_FLAG)

{
// Do something.
}

if (ExtPolicyFlags & EXTENSION_DISABLE_FLAG)

{
// Do something.
}

// only one origin flag can be set

switch (ExtFlags & EXTENSION_ORIGIN_MASK)
{
case EXTENSION_ORIGIN_REQUEST:
// Extension was set in certificate request.
break;
case EXTENSION_ORIGIN_POLICY:
// Extension was set by policy module.
break;
case EXTENSION_ORIGIN_ADMIN:
// Extension was set by administrator.
break;
case EXTENSION_ORIGIN_SERVER:
// Extension was set by server engine.
break;
default:
break;
}

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header certif.h (include Certsrv.h)

Librar y Certidl.lib

DLL Certcli.dll

See also
ICertAdmin::SetCertificateExtension
ICertServerPolicy
ICertServerPolicy::GetCertificateExtension
ICertServerPolicy::SetContext
IEnumCERTVIEWEXTENSION::GetFlags
 ICertServerPolicy::GetCertificateProperty method
(certif.h)
7/2/2022 • 5 minutes to read • Edit Online

The GetCer tificateProper ty method returns a named property from a certificate.

You must call ICertServerPolicy::SetContext prior to using this method.

Syntax
HRESULT GetCertificateProperty(
[in] const BSTR strPropertyName,
[in] LONG PropertyType,
[out] VARIANT *pvarPropertyValue
);

Parameters
[in] strPropertyName

Specifies the named property to retrieve. There is a stock set of certificate properties, referred to as the
name properties, that are always valid and can be retrieved by calling this method. For information about these
properties, see Name Properties. Other properties beside name properties can also be retrieved.
The certificate's DistinguishedName and RawName properties are accessible by
ICertServerExit::GetCertificateProperty only after the policy module has finished processing the request and the
certificate is issued. The issued certificate's DistinguishedName and RawName properties can also be read by an
exit module by using ICer tSer verExit::GetCer tificateProper ty .
There are additional certificate properties that cannot be accessed by GetCer tificateProper ty . These
properties are not set until after the policy module returns VR_INSTANT_OK and the certificate is issued. For a
complete list of all the properties in an issued certificate, see GetCer tificateProper ty .
The following properties are unique to certificates and can be read by GetCer tificateProper ty .

C ERT IF IC AT E P RO P ERT Y M EA N IN G

Internal request ID
RequestID
Signed long

Certificate start validity date

NotBefore
Date/time

Certificate expiration date

NotAfter
Date/time
 Subject key
RawPublicKey
Binary

Subject key algorithm object ID (OID)

PublicKeyAlgorithm
String

Subject key algorithm parameters

RawPublicKeyAlgorithmParameters
Binary

GeneralFlags in the enrollment request. This is a bitwise OR

GeneralFlags of values. The only value of interest should be the flag value
PROPTYPE_LONG of 0x00000400, which tells the CA not to persist the request
in the database. If the CA is in databaseless mode (that is,
for Windows Server 2008 R2 and later CAs, the CA's
database has the
DBFL AGS_ENABLEVOL ATILEREQUESTS flag set), use
certutil -getreg DbFlags and
certutil -setreg DBFlags for configuring the CA in
databaseless mode.
Windows Vista and Windows Storage
Ser ver 2003: This field is not supported.

For renewal requests, returns the requester account name

RequesterNameFromOldCer tificate (for example, contoso\requester).
PROPTYPE_STRING

The following properties apply to the certification authority.

C A P RO P ERT Y M EA N IN G

The type of certification authority. This can be one of the

CAType following values (defined in Certsrv.h):
Long ENUM_ENTERPRISE_ROOTCA
ENUM_ENTERPRISE_SUBCA
ENUM_STANDALONE_ROOTCA
ENUM_STANDALONE_SUBCA

The number of CA certificates. This value will be one plus the

Cer tCount number of times that the CA has been renewed. For
Long information about renewal, see Certification.
 The CA certificate state. This can be one of the following
Cer tState values:
Long CA_DISP_ERROR: The CA certificate was never issued.
CA_DISP_REVOKED: The CA certificate has been
revoked.
CA_DISP_VALID: The CA certificate is still valid.
CA_DISP_INVALID: The CA certificate has expired.
This property name may be appended with '.#', where #
represents a CA certificate index (or, in the case of the
CRLSuffix property, a CRL index). For information about
certificate and CRL indices, see Certification Authority
Renewal.

The suffix for the CA certificate. The suffix is an empty string

Cer tSuffix for CA certificates with an index of zero; otherwise, the suffix
String (in the form of "(nn)", where nn is the certificate index) is
applied to all URLs that point to CA certificates stored in files
or directory service objects. For non-LDAP URLs, the suffix
typically appears before the ".crt" text. For LDAP URLs, the
suffix is typically appended to the first 'CN=' in the full
distinguished name.
This property name may be appended with '.#', where #
represents a CA certificate index (or, in the case of the
CRLSuffix property, a CRL index). For information about
certificate and CRL indices, see Certification Authority
Renewal.

The certificate revocation list (CRL) index. Appending a

CRLIndex certificate index to this property name allows you to retrieve
Long the CRL index. The CRL index does not necessarily match the
certificate index. For more information, see Certification.
This property name may be appended with '.#', where #
represents a CA certificate index (or, in the case of the
CRLSuffix property, a CRL index). For information about
certificate and CRL indices, see Certification Authority
Renewal.

The CRL state. This can be one of the following values:

CRLState CA_DISP_ERROR: The CRL is managed by another CA
Long certificate.
CA_DISP_REVOKED: All unexpired CA certificates
using this CA certificate's CRL have been revoked.
CA_DISP_VALID: The CA certificate is still being used
to publish CRLs as needed.
CA_DISP_INVALID: All CA certificates using this CA
certificate's CRL are expired.
This property name may be appended with '.#', where #
represents a CA certificate index (or, in the case of the
CRLSuffix property, a CRL index). For information about
certificate and CRL indices, see Certification Authority
Renewal.
 The suffix for the CA CRL. The suffix is an empty string for
CRLSuffix CRLs with an index of zero; otherwise, the suffix (in the form
String of "(nn)", where nn is the CRL index) is applied to all URLs
that point to CRLs stored in files or directory service objects.
For non-LDAP URLs, the suffix typically appears before the
.crl text. For LDAP URLs, the suffix typically is appended to
the first 'CN=' in the full distinguished name.
This property name may be appended with '.#', where #
represents a CA certificate index (or, in the case of the
CRLSuffix property, a CRL index). For information about
certificate and CRL indices, see Certification Authority
Renewal.

Indicates whether the CA uses a directory service. This can

fUseDS be either of the following values:
Long 0=no
1=yes

The DNS name of the server hosting the CA.

MachineDNSName
String

The registry location available for use by the module.

ModuleRegistr yLocation
String

The CA certificate.
RawCACer tificate
This property name may be appended with '.#', where #
Binary
represents a CA certificate index (or, in the case of the
CRLSuffix property, a CRL index). For information about
certificate and CRL indices, see Certification Authority
Renewal.

The certificate revocation list (CRL) of the CA.

RawCRL
This property name may be appended with '.#', where #
Binary
represents a CA certificate index (or, in the case of the
CRLSuffix property, a CRL index). For information about
certificate and CRL indices, see Certification Authority
Renewal.

Indicates whether the requester is authorized to request the

RequesterCAAccess certificate. This can be either of the following values:
Long 0=no
1=yes
(The Certification Authority MMC snap-in can be used to
control certificate request permissions.)

The sanitized name for the CA. For information about

SanitizedCAName sanitized CA names, see ICertConfig::GetConfig.
String

The sanitized name for the CA, which is shortened and

SanitizedShor tName which contains a hash value to ensure uniqueness.
String
[in] PropertyType

Specifies the property type. The type can be one of the following values.

TYPE M EA N IN G

Signed long data

PROPTYPE_LONG

Date/time
PROPTYPE_DATE

Binary data
PROPTYPE_BINARY

Unicode string data

PROPTYPE_STRING

[out] pvarPropertyValue

A pointer to VARIANT that will contain the property value.

Return value
If the method succeeds, the method returns S_OK, and *pvarPropertyValue is set to the VARIANT that contains
the requested property value.
If the method fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header certif.h (include Certsrv.h)

Librar y Certidl.lib

DLL Certcli.dll

See also
ICertServerPolicy
ICertServerPolicy::SetContext
Name Properties
 ICertServerPolicy::GetRequestAttribute method
(certif.h)
7/2/2022 • 2 minutes to read • Edit Online

The GetRequestAttribute method returns a named attribute from a request.

Syntax
HRESULT GetRequestAttribute(
[in] const BSTR strAttributeName,
[out] BSTR *pstrAttributeValue
);

Parameters
[in] strAttributeName

The name of the attribute to retrieve.

[out] pstrAttributeValue

A pointer to a BSTR value that will contain the attribute value.

Return value
C++
If the method succeeds, the method returns S_OK and *pstrAttributeValue is set to the BSTR that contains the
attribute value.
To use this method, create a variable of type BSTR , set the variable equal to NULL , and pass the address of this
variable as pstrAttributeValue.
When you have finished using the BSTR , free it by calling the SysFreeString function.
If the method fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.
VB
The return value is a string that represents the attribute value.

Remarks
You must call ICertServerPolicy::SetContext prior to using this method.
The following request attributes are unique to KEYGEN style requests.

P RO P ERT Y N A M E TYPE DESC RIP T IO N

Challenge String Challenge string that accompanies the

request.
 ExpectedChallenge String If the challenge string is incorrect, then
the server will set the value of this
request attribute to the expected
challenge so that failure can be
diagnosed.

Examples

BSTR bstrAttribValue = NULL;

HRESULT hr;

// Get the request attribute.

// bstrAttribName is BSTR assigned by EnumerateAttributes.
// pCertServerPolicy has been used to call SetContext previously.
hr = pCertServerPolicy->GetRequestAttribute(bstrAttribName,
&bstrAttribValue);

if (FAILED(hr))
{
printf("Failed GetRequestAttribute [%x]\n", hr);
goto error;
}
else
{

// Successful call. Use the bstrAttribValue as needed.

// ...
}

// Done processing. Free BSTR.

if (NULL != bstrAttribValue)
SysFreeString(bstrAttribValue);

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header certif.h (include Certsrv.h)

Librar y Certidl.lib

DLL Certcli.dll

See also
ICertServerPolicy
ICertServerPolicy::SetContext
 ICertServerPolicy::GetRequestProperty method
(certif.h)
7/2/2022 • 2 minutes to read • Edit Online

The GetRequestProper ty method retrieves a specific property from a request.

Syntax
HRESULT GetRequestProperty(
[in] const BSTR strPropertyName,
[in] LONG PropertyType,
[out] VARIANT *pvarPropertyValue
);

Parameters
[in] strPropertyName

Specifies the name of the property to retrieve. This parameter can be set to a name property or a request
property.
Name properties include a stock set of certificate properties that are always valid and can be retrieved by calling
this method. For information about these properties, see Name Properties.
Request properties are unique to requests and include the following possible values.

VA L UE M EA N IN G

Internal requestID.
RequestID
Signed long

Raw request bytes.

RawRequest
Binary

Attribute string (may be truncated).

RequestAttributes
String

Indicates PKCS #10 or KeyGen request. For more

RequestType information about this property, see Remarks.
Signed long

When arrived.
SubmittedWhen
Date/time
 The name of the requester in the form "DomainName\
RequesterName UserID".
String

Note There are additional request properties that cannot be accessed by GetRequestProper ty because they
are not set until after the policy module finishes processing the request.In addition, other properties may be set
by a specific request type, request extensions, or by named attributes set in the header of a request.
[in] PropertyType

Specifies the property type. The PropertyType parameter can be one of the following types.

VA L UE M EA N IN G

Signed long data.

PROPTYPE_LONG

Date/time.
PROPTYPE_DATE

Binary data.
PROPTYPE_BINARY

Unicode string data.

PROPTYPE_STRING

[out] pvarPropertyValue

A pointer to the VARIANT that contains the request property type.

Return value
C++
If the method succeeds, the method returns S_OK, and the pvarPropertyValue parameter contains the request
property.
If the method fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.
VB
The return value is the request property.

Remarks
The SetContext method must be called prior to calling this method. The call to SetContext specifies which
request is used as the current context.
Requests hold all the associated states for the request and the eventual granted certificate that is not a part of
the certificate. Thus, data such as revocation times and disposition data are kept in the request data object.
The RequestType property can be set to one of the following values.

VA L UE M EA N IN G
 CR_IN_PKCS The request is a PKCS #7 renewal or registration request.

CR_IN-PKCS10 The request is a PKCS #10 request.

CR_IN_KEYGEN The request is a Keygen request (Netscape format).

Examples

BSTR bstrPropName = NULL;

VARIANT varProp;

VariantInit( &varProp );

bstrPropName = SysAllocString(L"RequestID");

// Retrieve the request property.

// pCertServerPolicy has been used to call SetContext previously.
hr = pCertServerPolicy->GetRequestProperty( bstrPropName,
PROPTYPE_LONG,
&varProp );
if (FAILED(hr))
{
printf("Failed GetRequestProperty [%x]\n", hr);
goto error;
}
else
{
// Successfully retrieved property; use varProp as needed.
// ...
}

// Done processing.
VariantClear( &varProp );
if ( NULL != bstrPropName )
SysFreeString( bstrPropName );

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header certif.h (include Certsrv.h)

Librar y Certidl.lib

DLL Certcli.dll

See also
ICertServerPolicy
ICertServerPolicy::SetContext
Name Properties
 ICertServerPolicy::SetCertificateExtension method
(certif.h)
7/2/2022 • 2 minutes to read • Edit Online

The SetCer tificateExtension method adds a new extension to the certificate.

Syntax
HRESULT SetCertificateExtension(
[in] const BSTR strExtensionName,
[in] LONG Type,
[in] LONG ExtFlags,
[in] const VARIANT *pvarValue
);

Parameters
[in] strExtensionName

Specifies the object identifier (OID) for the extension to set. The string must be 31 or less nonnull characters in
length.
[in] Type

Specifies the type of extension being set. The Type parameter must agree with the data type of pvarValue that
is set in the vt field of the VARIANT structure. The Type parameter can be set to one of the following types.

VA L UE M EA N IN G

Signed long data.

PROPTYPE_LONG

Date/time.
PROPTYPE_DATE

The extension value is set as is and is assumed to be ASN.1

PROPTYPE_BINARY encoded if necessary.

The extension value will be ASN.1 encoded as an IA5 string

PROPTYPE_STRING before it is placed in the new certificate.

Note You should use PROPTYPE_STRING for an

extension value that consists of a single URL only if you
want the URL to be automatically encoded as an IA5 string.
Otherwise, encode the URL as an IA5 string yourself and
pass the encoded value as PROPTYPE_BINARY .

[in] ExtFlags
Specifies the flags for the extension being set. Use a value of zero if no flag is to be set, or use one of the
following flag values. You can join these flags together by using the OR operator, and you can also join them by
using the OR operator with policy private extension flags (the high 8 bits of the EXTENSION_POLICY_MASK
field).

Note When ExtFlags is set to EXTENSION_DISABLE_FLAG, the extension will be disabled in the server log and will not be
added to the certificate.

VA L UE M EA N IN G

This is a critical extension.

EXTENSION_CRITICAL_FL AG

Extension will not be used.

EXTENSION_DISABLE_FL AG

[in] pvarValue

Specifies the value associated with the extension. Note the value's VARIANT type must agree with the Type
parameter, as shown in the following table.

VA L UE M EA N IN G

VT_I4
PROPTYPE_LONG

VT_DATE
PROPTYPE_DATE

VT_BSTR
PROPTYPE_BINARY

VT_BSTR
PROPTYPE_STRING

Return value
VB
If the method succeeds, the method returns S_OK.
If the method fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.

Remarks
Use extensions to include additional information with the certificate, such as supplemental subject or usage
information. For more information, see Extension Handlers.
Call the SetCer tificateExtension method from your implementation of the ICertPolicy2::VerifyRequest
method. You must call the ICertServerPolicy::SetContext method before calling the SetCer tificateExtension
method.
Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header certif.h (include Certsrv.h)

Librar y Certidl.lib

DLL Certcli.dll

See also
ICertServerPolicy
ICertServerPolicy::SetContext
 ICertServerPolicy::SetCertificateProperty method
(certif.h)
7/2/2022 • 3 minutes to read • Edit Online

Use the SetCer tificateProper ty method to set a property associated with a certificate.

Syntax
HRESULT SetCertificateProperty(
[in] const BSTR strPropertyName,
[in] LONG PropertyType,
[in] const VARIANT *pvarPropertyValue
);

Parameters
[in] strPropertyName

Specifies the property to set. You can set any of the Name Properties associated with the certificate.
In addition, you can set the following certificate properties.

VA L UE M EA N IN G

The certificate is not valid before the given date.

NotBefore
Date/time

The certificate is not valid after the given date.

NotAfter
Date/time

Set this property to 0x00000400 to prevent the request

GeneralFlags from being persisted in the CA database.

Caution Do not overwrite any mask values returned by

GetCertificateProperty when setting this property. Set the
value by performing a bitwise OR with the existing values.

Windows Storage Ser ver 2003: This field is not

supported.

A Boolean value that specifies whether the CA should

CrossForest operate cross forest enrollment mode.
PROPTYPE_LONG
Windows Ser ver 2008 and Windows
Ser ver 2003: Cross forest enrollment is not
supported. Cross forest enrollment is supported
beginning with Windows Server 2008 R2.
 Tells the CA to set the requester account name
RequesterSAMName ("RequesterName") and distinguished name.
PROPTYPE_STRING

Tells the CA to convert the user principal name (UPN) of the

RequesterUPN requester to the requester name ("RequesterName") and to
PROPTYPE_STRING set the requester name and the requester distinguished
name.

Tells the CA to convert the FQDN 1779 name of the

RequesterDN requester to the requester name and to set the requester
PROPTYPE_STRING name ("RequesterName") and the requester distinguished
name.

[in] PropertyType

Specifies the type of the property being set. The Type parameter must agree with the data type of pvarValue that
is set in the vt field of the VARIANT structure. The Type parameter can be set to one of the following types.

VA L UE M EA N IN G

Signed long data.

PROPTYPE_LONG

Date/time data.
PROPTYPE_DATE

Binary data.
PROPTYPE_BINARY

Unicode string data

PROPTYPE_STRING

[in] pvarPropertyValue

Specifies the value to set the property to.

Return value
VB
If the method succeeds, the method returns S_OK.
If the method fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.

Remarks
You must call ICertServerPolicy::SetContext prior to using this method.
The NotBefore and NotAfter certificate properties constrain the lifetime during which a certificate is valid. The
data type for these properties is a floating-point VARIANT date derived from COleDateTime in Automation.
The following restrictions apply when setting the NotBefore and NotAfter certificate properties with
SetCer tificateProper ty :
The NotBefore date cannot be set to a date earlier than the certification authority (CA) certificate's NotBefore
 date.
The NotAfter date cannot be set to a date later than the CA certificate's NotAfter date.
The NotBefore date cannot be set to a date earlier than it already is set, even if the new date is later than the
CA certificate's NotBefore date.
The NotAfter date cannot be set to a date later than it already is set, even if the new date is before the CA
certificate's NotAfter date.
Examples
The following example calls the SetCer tificateProper ty method to set the NotBefore certificate property. The
example assumes pServer is valid and the ICertServerPolicy::SetContext method has been called.

HRESULT hr;
ICertServerPolicy *pServer;
SYSTEMTIME st;
BSTR bstrPropName;
VARIANT vPropValue;

bstrPropName = SysAllocString(L"NotBefore");
if (NULL == bstrPropName)
{
printf("Unable to allocate memory.\n");
return E_OUTOFMEMORY;
}

// Set the 'NotBefore' property to Noon on Jan. 1, 2000.

memset( &st, 0, sizeof(SYSTEMTIME));
st.wYear = 2000;
st.wMonth = 1; // Jan.
st.wDay = 1; // 1st day of month.
st.wHour = 12; // Noon.

// Place the date into VARIANT required format.

VariantInit( &vPropValue );
vPropValue.vt = VT_DATE;
if ( !SystemTimeToVariantTime( &st, &vPropValue.date))
{
printf("Unable to convert time.\n");
SysFreeString(bstrPropName);
return E_FAIL
}

// Set the NotBefore property in the certificate:

hr = pServer->SetCertificateProperty(bstrPropName,
PROPTYPE_DATE,
&vPropValue);
SysFreeString(bstrPropName);
VariantClear(&vPropValue);
if (FAILED(hr))
{
printf("SetCertificateProperty failed [%x]\n", hr);
return hr;
}

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]
 Target Platform Windows

Header certif.h (include Certsrv.h)

Librar y Certidl.lib

DLL Certcli.dll

See also
ICertServerExit::GetCertificateProperty
ICertServerPolicy
ICertServerPolicy::SetContext
Name Properties
 ICertServerPolicy::SetContext method (certif.h)
7/2/2022 • 2 minutes to read • Edit Online

The SetContext method specifies the request to be used as the context for subsequent calls to Certificate
Services.

Syntax
HRESULT SetContext(
[in] LONG Context
);

Parameters
[in] Context

Specifies the request. This parameter must be set to the identical value returned in the Context parameter of the
ICertPolicy::VerifyRequest method.

Return value
VB
If the method succeeds, the method returns S_OK.
If the method fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.

Remarks
The policy module must call the SetContext method first, before calls to any other ICertServerPolicy method,
so that the interface references a valid request.
Examples

// Set the context. The value nContext (long) would be the same
// as the context parameter in ICertPolicy::VerifyRequest.
// hr is defined as an HRESULT.
hr = pCertServerPolicy->SetContext( nContext );
if (FAILED(hr))
{
printf("Failed SetContext [%x]\n", hr);
goto error;
}

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]
 Target Platform Windows

Header certif.h (include Certsrv.h)

Librar y Certidl.lib

DLL Certcli.dll

See also
ICertPolicy::VerifyRequest
ICertServerPolicy
 certmod.h header
7/2/2022 • 2 minutes to read • Edit Online

This header is used by Security and Identity. For more information, see:
Security and Identity
certmod.h contains the following programming interfaces:

Interfaces

ICertManageModule

Provided to retrieve information about a Certificate Services Policy or Exit module.

 ICertManageModule interface (certmod.h)
7/2/2022 • 2 minutes to read • Edit Online

The ICer tManageModule interface is provided to retrieve information about a Certificate Services Policy or
Exit module.

Inheritance
The ICer tManageModule interface inherits from the IDispatch interface. ICer tManageModule also has these
types of members:

Methods
The ICer tManageModule interface has these methods.

ICertManageModule::Configure

Displays the module user interface.

ICertManageModule::GetProperty

Retrieves a module's property value.

ICertManageModule::SetProperty

Allows a module to set a property value.

Remarks
The ICer tManageModule interface provides a method to invoke the module user interface for setting and
viewing configuration settings. Writers of Policy and Exit modules should implement the ICer tManageModule
interface (in addition to the ICertPolicy and ICertExit interfaces, respectively). An enterprise certification authority
(CA) should always use the Microsoft-provided enterprise policy and exit modules; additional exit modules are
permitted for enterprise CAs.
The following is an example of what could be used in the DECLARE_REGISTRY macro of a class
(CMyCertManagePolicyModule) which implements ICer tManageModule .

DECLARE_REGISTRY(
CMyCertManagePolicyModule,
L"MyCode.PolicyManage.1",
L"MyCode.PolicyManage",
IDS_CERTMANAGEPOLICYMODULE_DESC,
THREADFLAGS_BOTH);

The IDS_CERTMANAGEPOLICYMODULE_DESC value is an application-specific identifier that identifies a string

table string in the resource file (.rc) which describes the class.
ICer tManageModule is defined in Certmod.h. When you create your program, however, use Certsrv.h as the
include file.
Certificate Services interfaces support both apartment-threading and free-threading models. For better
throughput, free threading is recommended.
In Visual Basic Scripting Edition, the name of the class that implements ICer tManageModule must be either
"PolicyManage" or "PolicyExit", depending on the type of module being created. The following string constants
defined in Certmod.h may be used to simplify following the naming convention.

C O N STA N T VA L UE

wszCERTMANAGEEXIT_POSTFIX TEXT(".ExitManage")

wszCERTMANAGEPOLICY_POSTFIX TEXT(".PolicyManage")

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header certmod.h (include Certsrv.h)

 ICertManageModule::Configure method
(certmod.h)
7/2/2022 • 2 minutes to read • Edit Online

The Configure method displays the module user interface.

Syntax
HRESULT Configure(
[in] const BSTR strConfig,
[in] BSTR strStorageLocation,
[in] LONG Flags
);

Parameters
[in] strConfig

Represents the configuration string for the Certificate Services server in the form COMPUTERNAME\CANAME,
where COMPUTERNAME is the Certificate Services server's network name, and CANAME is the common name
of the certification authority (CA) as entered for the CA during Certificate Services setup. For information about
the configuration string name, see ICertConfig.
[in] strStorageLocation

A location that provides storage for the property values, as described in the definition of strStorageLocation in
ICertManageModule::GetProperty.
[in] Flags

A value used to determine whether the configuration interface is to be presented to the user. If this value is zero,
the user will be presented with an interface for configuring the module. If this value is CMM_REFRESHONLY,
Certificate Services will not display the user interface, but the latest changes to the configuration of the module
will be in effect when future certificate requests are processed (this allows changes to be incorporated without
requiring a response to a user interface).

Return value
VB
If the method succeeds, the method returns S_OK.
If the method fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.

Remarks
The Configure method displays the module user interface (if one exists), which allows the user to view and
change the module's configurable items. A module that implements ICertManageModule can have its
Configure method called when the Certificate Services Manager Policy or Exit Module property page is active
and the user chooses the Configure button. The Certificate Services Manager will pass the location referenced
by strStorageLocation to this module, and the implementation of this method can then use this location as
needed. Note that it is possible that a module may not have configurable items (hence, a user interface would
not be necessary), but it would still be necessary to implement this method. The example below does not allow a
user to make a configuration change, but it does implement this method.
Examples

#include <windows.h>
#include <Certmod.h>

HRESULT CCertManagePolicyModule::Configure(
/* [in] */ const BSTR strConfig,
/* [in] */ BSTR strStorageLocation,
/* [in] */ LONG Flags)
{
if ( CMM_REFRESHONLY != Flags )
MessageBox(NULL,
L"This module has no configurable items",
L"MyModule",
(MB_OK|MB_ICONINFORMATION));

return S_OK;
}

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header certmod.h (include Certsrv.h)

Librar y Certidl.lib

See also
ICertConfig
ICertManageModule
 ICertManageModule::GetProperty method
(certmod.h)
7/2/2022 • 3 minutes to read • Edit Online

The GetProper ty method retrieves a module's property value.

Syntax
HRESULT GetProperty(
[in] const BSTR strConfig,
[in] BSTR strStorageLocation,
[in] BSTR strPropertyName,
[in] LONG Flags,
[out, retval] VARIANT *pvarProperty
);

Parameters
[in] strConfig

Represents the configuration string for the Certificate Services server in the form COMPUTERNAME\CANAME,
where COMPUTERNAME is the Certificate Services server's network name, and CANAME is the common name
of the certification authority (CA) as entered for the CA during Certificate Services setup. For information about
the configuration string name, see ICertConfig.
[in] strStorageLocation

A registry key that denotes the storage location in the HKEY_LOCAL_MACHINE hive for the property values.
This value is in the following form:

SYSTEM
CurrentControlSet
Services
CertSvc
Configuration
CAName
PolicyOrExitModules
MyModule.PolicyOrExit

The CAName is the name of the certification authority's configuration string, PolicyOrExitModules will be either
"Policy" or "Exit" (depending on whether a Policy or Exit module applies to this implementation of
ICer tManageModule ), and MyModule.PolicyOrExit is the application-specific identifier for the module. Note
that CAName is the sanitized name for the certification authority. For information about the sanitized name, see
ICertConfig::GetConfig. The use of this storage location is for future use.
[in] strPropertyName

The name of the property being queried. Policy and exit modules should support the following properties.

VA L UE M EA N IN G
 Name of the module.
Name

Description of the module.

Description

Copyright pertaining to the module.

Copyright

Version of the module file.

File Version

Version of the module.

Product Version

[in] Flags

This parameter is reserved and must be set to zero.

[out, retval] pvarProperty

A pointer to a VARIANT that is the retrieved value for the property specified by strPropertyName.

Return value
C++
If the method succeeds, the method returns S_OK.
If the method fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.
VB
The return value is a Variant that represents the value of the property named strPropertyName.

Remarks
Implementing ICer tManageModule allows the Certificate Services Manager to retrieve the module's
properties by calling GetProper ty . The properties can then be displayed in Certificate Services Manager
property pages for Policy and Exit Modules. The Certificate Services Manager will pass the location referenced
by strStorageLocation to this module, and in future versions the implementation of this method can then use
this location as needed. The following example does not use strStorageLocation but instead, maintains the
property values in memory.
Examples
 #include <windows.h>
#include <Certmod.h>

HRESULT CCertManagePolicyModule::GetProperty(
/* [in] */ const BSTR strConfig,
/* [in] */ BSTR strStorageLocation,
/* [in] */ BSTR strPropertyName,
/* [in] */ LONG Flags,
/* [retval][out] */ VARIANT *pvarProperty)
{
// Array of property Names.
// These values are defined in Certmod.h.
wchar_t const * awszPropName[] =
{
wszCMM_PROP_NAME,
wszCMM_PROP_DESCRIPTION,
wszCMM_PROP_COPYRIGHT,
wszCMM_PROP_FILEVER,
wszCMM_PROP_PRODUCTVER
};

// Array of property Values.

// These values are module-specific, and
// correspond to the property names in
// awszPropName (same index).
wchar_t const * awszPropValue[] =
{
L"MyModule", // NAME
L"Description of MyModule", // DESCRIPTION
L"Copyright 1998", // COPYRIGHT
L"1.0", // FILE VERSION
L"1.0" // PRODUCT VERSION
};
int i;
bool bFound = FALSE;
HRESULT hr;

// Return appropriate error if strPropertyName is NULL.

if (NULL == strPropertyName)
return E_INVALIDARG;

// Return appropriate error if pvarProperty is NULL.

if (NULL == pvarProperty)
return E_POINTER;
// Determine whether the requested property is in the Name array.
for (i=0; i<sizeof(awszPropName)/sizeof(wchar_t *); i++)
if (!wcscmp( strPropertyName, awszPropName[i]))
{
bFound = TRUE; // Found the index for the property.
break;
}
if ( !bFound )
return S_FALSE; // Requested property not found.

// Allocate storage for the property value.

pvarProperty->bstrVal = SysAllocString(awszPropValue[i]);
if (NULL == pvarProperty->bstrVal)
return E_OUTOFMEMORY;

pvarProperty->vt = VT_BSTR;

return S_OK;
}

Requirements
 Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header certmod.h (include Certsrv.h)

Librar y Certidl.lib

See also
CCer tManageModule
ICertConfig
ICertManageModule
ICertManageModule::SetProperty
 ICertManageModule::SetProperty method
(certmod.h)
7/2/2022 • 2 minutes to read • Edit Online

The SetProper ty method allows a module to set a property value.

Syntax
HRESULT SetProperty(
[in] const BSTR strConfig,
[in] BSTR strStorageLocation,
[in] BSTR strPropertyName,
[in] LONG Flags,
[in] const VARIANT *pvarProperty
);

Parameters
[in] strConfig

Represents the configuration string for the Certificate Services server in the form COMPUTERNAME\CANAME,
where COMPUTERNAME is the Certificate Services server's network name, and CANAME is the common name
of the certification authority (CA) as entered for the CA during Certificate Services setup. For information about
the configuration string name, see ICertConfig.
[in] strStorageLocation

The location that provides storage for the property values, as described in the definition of strStorageLocation in
ICertManageModule::GetProperty.
[in] strPropertyName

The name of the property whose value is being assigned. Policy and exit modules should support the following
properties, which are used by Certificate Services Manager.

VA L UE M EA N IN G

Name of the module.

Name

Description of the module.

Description

Copyright pertaining to the module.

Copyright

Version of the module file.

File Version
 Version of the module.
Product Version

[in] Flags

This parameter is reserved and must be set to zero.

[in] pvarProperty

A value that is being assigned to the property specified by strPropertyName.

Return value
VB
If the method succeeds, the method returns S_OK.
If the method fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.

Remarks
This method is intended for future functionality. A minimal implementation is required, however, to meet the
requirements of the ICertManageModule interface.
Examples

#include <windows.h>
#include <Certmod.h>

HRESULT CCertManagePolicyModule::SetProperty(
/* [in] */ const BSTR strConfig,
/* [in] */ BSTR strStorageLocation,
/* [in] */ BSTR strPropertyName,
/* [in] */ LONG Flags,
/* [in] */ const VARIANT *pvarProperty)
{
// This implementation fulfills the minimal requirement
// needed for ICertManageModule::SetProperty.
return S_OK;
}

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header certmod.h (include Certsrv.h)

Librar y Certidl.lib

See also
CCer tManageModule
ICertConfig
ICertManageModule
ICertManageModule::GetProperty
 certpol.h header
7/2/2022 • 2 minutes to read • Edit Online

This header is used by Security and Identity. For more information, see:
Security and Identity
certpol.h contains the following programming interfaces:

Interfaces

ICertPolicy

Provides communications between the Certificate Services server engine and the policy module.

ICertPolicy2

Provide communications between the Certificate Services server engine and the policy module.

INDESPolicy

The NDES Policy Module Interface. When installed against an enterprise CA, NDES generates a password after checking that
the user has enrollment permission on the configured NDES templates, both user and machine templates.

Enumerations

X509SCEPDisposition

Describes the resulting disposition of a request to process a response message.

X509SCEPFailInfo

Describes the nature of an SCEP certificate enrollment failure.

 ICertPolicy interface (certpol.h)
7/2/2022 • 2 minutes to read • Edit Online

The ICer tPolicy interface provides communications between the Certificate Services server engine and the
policy module.

Note The policy module can communicate with the Certificate Services server engine by using the ICertServerPolicy
interface.

The Certificate Services server engine calls the ICer tPolicy methods to perform the following tasks:
Initialize the policy module.
Notify the policy module that a new request has entered the system. The policy module can then use the
methods of the ICertServerPolicy interface to indicate that the request is good and should be issued, is bad
and should be denied, or should be held for later consideration.
Retrieve a description of the policy module and its functionality.
Notify the policy module that the Certificate Services server is being terminated.
Policy modules should implement both ICer tPolicy and ICertManageModule.
ICer tPolicy is defined in Certpol.h. When you create your program, however, use Certsrv.h as the include file.
Certificate Services interfaces support both apartment-threading and free-threading models. For better
throughput, free threading is recommended.

Inheritance
The ICer tPolicy interface inherits from the IDispatch interface. ICer tPolicy also has these types of members:

Methods
The ICer tPolicy interface has these methods.

ICertPolicy::GetDescription

Returns a human-readable description of the policy module and its function.

ICertPolicy::Initialize

Called by the server engine to allow the policy module to perform initialization tasks.

ICertPolicy::ShutDown

Called by the server engine before the server is terminated.

ICertPolicy::VerifyRequest

Notifies the policy module that a new request has entered the system.
Remarks
Only a stand-alone certification authority should use custom policy or exit modules; when running an enterprise
certification authority, the use of Microsoft-provided policy and exit modules is strongly recommended.
Implementers of ICer tPolicy should also implement ICertManageModule. Additionally, the ProgID for a class
implementing ICer tPolicy must conform to a naming convention. Specifically, the ProgID must be of the form:
" MyApp.Policy"
Where MyApp is a specifier that identifies the application. For example, in C++, the following code could be
used in the DECLARE_REGISTRY macro of a class (CMyCertPolicyModule) which implements ICer tPolicy .

DECLARE_REGISTRY(
CMyCertPolicyModule,
L"MyCode.Policy.1",
L"MyCode.Policy",
IDS_CERTPOLICYMODULE_DESC,
THREADFLAGS_BOTH);

For the previous example, the IDS_CERTPOLICYMODULE_DESC value is an application-specific identifier in the
resource file (.rc) for a string which describes the class.
String constants defined in Certmod.h can be used to simplify following the naming convention.

C O N STA N T VA L UE

wszCERTPOLICYMODULE_POSTFIX TEXT(".Policy")

No more than one Visual Basic Scripting Edition policy module may be registered on the Certificate Services
server at one time. If more than one such policy module is registered on the Certificate Services server, the
Certification Authority MMC snap-in, Certificate Services application, or certutil command line program may
produce errors. Note that the Visual Basic Scripting Edition development environment automatically registers a
DLL when it is successfully built. As a result, you may encounter this situation when one Visual Basic Scripting
Edition policy module is already registered and another Visual Basic Scripting Edition policy module is created.
To avoid this situation, you must unregister one of the Visual Basic Scripting Edition policy modules, by using the
command-line instruction regsvr32 /u FileName.dll, where FileName.dll is the name of the Visual Basic
Scripting Edition policy module that you do not intend to make active.
Implementers of ICer tPolicy in Visual Basic Scripting Edition must name their project in the form:
" MyApp"
Where MyApp is a specifier that identifies the application; further, the class implementing ICer tPolicy must be
named "Policy" .

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header certpol.h (include Certsrv.h)
 ICertPolicy::GetDescription method (certpol.h)
7/2/2022 • 2 minutes to read • Edit Online

The GetDescription method returns a human-readable description of the policy module and its function.

Syntax
HRESULT GetDescription(
[out] BSTR *pstrDescription
);

Parameters
[out] pstrDescription

A pointer to a BSTR that describes the policy module.

Return value
C++
If the method succeeds, the method returns S_OK.
If the method fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.
VB
Returns a string that describes the policy module and its function.

Remarks
When you write custom policy modules, implement this method.
Examples
 #include <windows.h>
#include <Certpol.h>

STDMETHODIMP CCertPolicy::GetDescription(
/* [out, retval] */ BSTR __RPC_FAR *pstrDescription)
{
if (NULL == pstrDescription)
{
// Bad pointer address
return ( E_POINTER );
}
if (NULL != *pstrDescription)
{
SysFreeString(*pstrDescription);
*pstrDescription=NULL;
}
// wszMyModuleDesc defined elsewhere, for example:
// #define wszMyModuleDesc L"My Policy Module"
*pstrDescription = SysAllocString(wszMyModuleDesc);
if (NULL == *pstrDescription)
{
// Not enough memory
return ( E_OUTOFMEMORY );
}
// Success
return( S_OK );
}

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header certpol.h (include Certsrv.h)

Librar y Certidl.lib

See also
ICertPolicy
ICertPolicy2
 ICertPolicy::Initialize method (certpol.h)
7/2/2022 • 2 minutes to read • Edit Online

The Initialize method is called by the server engine to allow the policy module to perform initialization tasks.

Syntax
HRESULT Initialize(
[in] const BSTR strConfig
);

Parameters
[in] strConfig

Represents the name of the certification authority, as entered during Certificate Services setup. For information
about the configuration string name, see ICertConfig2.

Return value
VB
If the method succeeds, the method returns S_OK.
If the method fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.

Remarks
When you write custom policy modules, implement this method.
Examples

#include <windows.h>
#include <Certpol.h>

STDMETHODIMP CCertPolicy::Initialize(
/* [in] */ BSTR const strConfig)
{
// strConfig can be used by the Policy module.
// Here, it is stored in a BSTR member variable.
// m_strConfig is an application-defined variable.
// Call SysFreeString to free m_strConfig when done.
m_strConfig = SysAllocString( strConfig );
// Check to determine whether there was enough memory.
if (NULL == m_strConfig)
return ( E_OUTOFMEMORY ); // Not enough memory

return( S_OK );
}

Requirements
 Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header certpol.h (include Certsrv.h)

Librar y Certidl.lib

See also
ICertConfig
ICertPolicy
ICertPolicy2
 ICertPolicy::ShutDown method (certpol.h)
7/2/2022 • 2 minutes to read • Edit Online

The ShutDown method is called by the server engine before the server is terminated.
When ShutDown is called, the policy module should clean up and stop. It is guaranteed that no requests will
arrive after ShutDown is called.

Syntax
HRESULT ShutDown();

Return value
VB
If the method succeeds, the method returns S_OK.
If the method fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.

Remarks
When you write custom policy modules, implement this method.
Examples

#include <windows.h>
#include <stdio.h>
#include <Certpol.h>

STDMETHODIMP CCertPolicy::ShutDown()
{
// Clean up resources used by this process.

// Display message that this method has been called.

if ( fDebug )
{
printf("Policy module Shutdown was called\n");
}
return( S_OK );
}

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

 Header certpol.h (include Certsrv.h)

Librar y Certidl.lib

See also
ICertPolicy
ICertPolicy2
 ICertPolicy::VerifyRequest method (certpol.h)
7/2/2022 • 3 minutes to read • Edit Online

The VerifyRequest method notifies the policy module that a new request has entered the system. The policy
module can then interact with that request by passing Context as a parameter when retrieving or setting
properties on the request or associated certificate.
The returned disposition value indicates whether the request has been accepted, denied, or has been sent to the
administration queue for later evaluation.

Syntax
HRESULT VerifyRequest(
[in] const BSTR strConfig,
[in] LONG Context,
[in] LONG bNewRequest,
[in] LONG Flags,
[out, retval] LONG *pDisposition
);

Parameters
[in] strConfig

Represents the name of the certification authority, as entered during Certificate Services setup. For information
about the configuration string name, see ICertConfig.
[in] Context

Identifies the request and associated certificate under construction. The certificate server passes the context to
this method.
[in] bNewRequest

If set to TRUE , specifies that the request is new. If set to FALSE , the request is being resubmitted to the policy
module as a result of an ICertAdmin::ResubmitRequest call. A value of FALSE can be used to indicate that the
administrator wants the request to be issued or that request properties set by the administrator should be
examined.
Note that TRUE is defined (in a Microsoft header file) for C/C++ programmers as one, while Visual Basic defines
the True keyword as negative one. As a result, Visual Basic developers must use one (instead of True ) to set this
parameter to TRUE . However, to set this parameter to FALSE , Visual Basic developers can use zero or False .
[in] Flags

This parameter is reserved and must be set to zero.

[out, retval] pDisposition

A pointer to the disposition value. The method sets one of the following dispositions.

VA L UE M EA N IN G
 Deny the request.
VR_INSTANT_BAD

Accept the request.

VR_INSTANT_OK

Add the request to the queue to accept or deny the request

VR_PENDING at a later time.

Return value
C++
If the method succeeds, the method returns S_OK.
If the method fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.
VB
The return value specifies the disposition, which must be one of the following values.
RET URN C O DE DESC RIP T IO N

Deny the request.

VR_INSTANT_BAD

Accept the request.

VR_INSTANT_OK

Add the request to the queue to accept or deny the request

VR_PENDING at a later time.

Remarks
VerifyRequest is free to spawn off other processes or access an external database to do the request
verification. If the verification requires out-of-band processing or human intervention, VerifyRequest can notify
another process or leave any notice of the incoming request required. After the out-of-band processing is
complete, a call to ResubmitRequest can be made, or the provided administration tool can be used to resubmit
the request to the Policy Module. The policy module can examine the request again, access any necessary
external data, and return a value to indicate the certificate should be issued or denied.
When you write custom policy modules, you must implement VerifyRequest functionality in your modules.
Examples
The following example shows a possible implementation of the VerifyRequest method.

#include <windows.h>
#include <stdio.h>
#include <Certpol.h>

STDMETHODIMP CCertPolicy::VerifyRequest(
BSTR const strConfig,
LONG Context,
LONG bNewRequest,
LONG Flags,
LONG __RPC_FAR *pDisposition)
{
HRESULT hr;
long nDisp = VR_INSTANT_BAD;
ICertServerPolicy *pServer = NULL;
BSTR bstrPropName = NULL;
VARIANT varProp;

// Verify that pointer is not NULL.

if ( NULL == pDisposition )
{
hr = E_POINTER; // E_POINTER is #defined in Winerror.h
goto error;
}

// Set disposition to pending.

*pDisposition = VR_PENDING;

// Obtain a pointer to the CertServerPolicy interface.

hr = CoCreateInstance( CLSID_CCertServerPolicy,
NULL,
CLSCTX_INPROC_SERVER,
IID_ICertServerPolicy,
(void **) &pServer);
if (FAILED( hr ))
{
printf("Failed CoCreateInstance for pServer - %x\n", hr );
goto error;
}

// Set the context to refer to this request.

hr = pServer->SetContext(Context);
if (FAILED( hr ))
{
printf("Failed SetContext(%u) - %x\n", Context, hr );
goto error;
}

// This policy will perform a database check on the CN.

// Set the property name to Subject.Commonname.
bstrPropName = SysAllocString(L"Subject.Commonname");
if ( NULL == bstrPropName )
{
hr = E_OUTOFMEMORY; // #defined in Winerror.h
printf("Failed SysAllocString (no memory)\n" );
goto error;
}

// Retrieve the certificate property for the CN.

// Actual implementations may want to examine other properties.
VariantInit( &varProp );
hr = pServer->GetCertificateProperty( bstrPropName,
PROPTYPE_STRING,
&varProp );
if (FAILED(hr))
{
printf("Failed GetCertificateProperty - %x\n", hr);
goto error;
}

// For this simple sample, merely check CN in a database.

// (Implementation not shown, as it is application-specific).
hr = MyDatabaseCheck( varProp.bstrVal );
if ( S_OK == hr )
*pDisposition = VR_INSTANT_OK; // Accepted.
else
*pDisposition = VR_INSTANT_BAD; // Denied.

error:
 // Free resources.
if (NULL != pServer)
pServer->Release();

VariantClear( &varProp );

if ( NULL != bstrPropName )
SysFreeString( bstrPropName );

return(hr);
}

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header certpol.h (include Certsrv.h)

Librar y Certidl.lib

See also
ICertConfig
ICertPolicy
ICertPolicy2
 ICertPolicy2 interface (certpol.h)
7/2/2022 • 2 minutes to read • Edit Online

The ICer tPolicy2 interface is one of two interfaces that provide communications between the Certificate
Services server engine and the policy module.

Note The policy module can communicate with the Certificate Services server engine by using the ICertServerPolicy
interface.

The Certificate Services server engine calls the ICer tPolicy2 methods to perform the following tasks:
Initialize the policy module.
Notify the policy module that a new request has entered the system. The policy module can then use the
methods of the ICertServerPolicy interface to indicate that the request is good and should be issued, is bad
and should be denied, or should be held for later consideration.
Retrieve a description of the policy module and its functionality.
Notify the policy module that the Certificate Services server is being terminated.
Certificate Services interfaces support both apartment-threading and free-threading models. For better
throughput, free threading is recommended.

Inheritance
The ICer tPolicy2 interface inherits from ICertPolicy and IDispatch. ICer tPolicy2 also has these types of
members:

Methods
The ICer tPolicy2 interface has these methods.

ICertPolicy2::GetManageModule

Retrieves the ICertManageModule interface associated with the ICertPolicy2 interface by calling GetManageModule and
passing in the address of a pointer to an ICertManageModule.

Remarks
Implementers of ICertPolicy should also implement ICertManageModule. Additionally, the ProgID for a class
implementing ICer tPolicy must conform to a naming convention. Specifically, the ProgID must be of the form:
" MyApp.Policy"
Where MyApp is a specifier that identifies the application. For example, in C++, the following could be used in
the DECLARE_REGISTRY macro of a class (CMyCertPolicyModule) which implements ICertPolicy.
 DECLARE_REGISTRY(
CMyCertPolicyModule,
L"MyCode.Policy.1",
L"MyCode.Policy",
IDS_CERTPOLICYMODULE_DESC,
THREADFLAGS_BOTH);

For the previous example, the IDS_CERTPOLICYMODULE_DESC value is an application-specific identifier in the
resource file (.rc) for a string which describes the class.
String constants defined in Certmod.h can be used to simplify following the naming convention.

C O N STA N T VA L UE

wszCERTPOLICYMODULE_POSTFIX TEXT(".Policy")

No more than one Visual Basic Scripting Edition policy module may be registered on the Certificate Services
server at one time. If more than one such policy module is registered on the Certificate Services server, the
Certification Authority MMC snap-in, Certificate Services application, or Certutil tool may produce errors. Note
that the Visual Basic Scripting Edition development environment automatically registers a DLL when it is
successfully built. As a result, you may encounter this situation when one Visual Basic Scripting Edition policy
module is already registered and another Visual Basic Scripting Edition policy module is created. To avoid this
situation, you must unregister one of the Visual Basic Scripting Edition policy modules, by using the command-
line instruction regsvr32 /u FileName.dll, where FileName.dll is the name of the Visual Basic Scripting Edition
policy module that you do not intend to make active.
Implementers of ICertPolicy in Visual Basic Scripting Edition must name their project in the form:
" MyApp"
Where MyApp is a specifier that identifies the application; further, the class implementing ICertPolicy must be
named "Policy" .

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header certpol.h (include Certsrv.h)

 ICertPolicy2::GetManageModule method (certpol.h)
7/2/2022 • 2 minutes to read • Edit Online

The GetManageModule method retrieves the ICertManageModule interface associated with the ICertPolicy2
interface by calling GetManageModule and passing in the address of a pointer to an ICer tManageModule .

Syntax
HRESULT GetManageModule(
[out] ICertManageModule **ppManageModule
);

Parameters
[out] ppManageModule

Pointer to the ICertManageModule interface associated with the ICertPolicy2 interface.

Return value
C++
The return value is an HRESULT . A value of S_OK indicates the method was successful.
VB
The return value is a Variant containing the ICertManageModule interface associated with the ICertPolicy2
interface.

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header certpol.h (include Certsrv.h)

Librar y Certidl.lib

See also
CCer tPolicy
ICertPolicy2
 INDESPolicy interface (certpol.h)
7/2/2022 • 2 minutes to read • Edit Online

The NDES Policy Module Interface. When installed against an enterprise CA, NDES generates a password after
checking that the user has enrollment permission on the configured NDES templates, both user and machine
templates.

Inheritance
The INDESPolicy interface inherits from the IUnknown interface. INDESPolicy also has these types of
members:

Methods
The INDESPolicy interface has these methods.

INDESPolicy::GenerateChallenge

Performs the policy decision whether to issue a challenge password to the SCEP client.

INDESPolicy::Initialize

Initializes the NDES policy module.

INDESPolicy::Notify

Notifies the plug-in of the transaction status of the SCEP certificate request.

INDESPolicy::Uninitialize

Uninitializes the NDES policy module.

INDESPolicy::VerifyRequest

Verifies the NDES certificate request for submission to the CA.

Requirements

Target Platform Windows

Header certpol.h
 INDESPolicy::GenerateChallenge method (certpol.h)
7/2/2022 • 2 minutes to read • Edit Online

Performs the policy decision whether to issue a challenge password to the SCEP client.

Syntax
HRESULT GenerateChallenge(
[in] PCWSTR pwszTemplate,
[in] PCWSTR pwszParams,
[out, retval] PWSTR *ppwszResponse
);

Parameters
[in] pwszTemplate

The template being requested for, as determined by NDES.

[in] pwszParams

Parameters specific to the policy module implementation.

[out, retval] ppwszResponse

After the user has been authenticated and authorized, the ppwsxResponse parameter contains the SCEP
challenge password for the user. NDES will free this resource.

Return value
If this method succeeds, it returns S_OK . Otherwise, it returns an HRESULT error code.

Requirements

Target Platform Windows

Header certpol.h

See also
INDESPolicy
 INDESPolicy::Initialize method (certpol.h)
7/2/2022 • 2 minutes to read • Edit Online

Initializes the NDES policy module.

Syntax
HRESULT Initialize();

Return value
If this method succeeds, it returns S_OK . Otherwise, it returns an HRESULT error code.

Requirements

Target Platform Windows

Header certpol.h

See also
INDESPolicy
 INDESPolicy::Notify method (certpol.h)
7/2/2022 • 2 minutes to read • Edit Online

Notifies the plug-in of the transaction status of the SCEP certificate request.

Syntax
HRESULT Notify(
[in] PCWSTR pwszChallenge,
[in] PCWSTR pwszTransactionId,
[in] X509SCEPDisposition disposition,
[in] LONG lastHResult,
[in] CERTTRANSBLOB *pctbIssuedCertEncoded
);

Parameters
[in] pwszChallenge

The authentication and authorization SCEP challenge password for the user.
[in] pwszTransactionId

The SCEP request transaction ID.

[in] disposition

The disposition of the transaction.

[in] lastHResult

The HRESULT of the last operation.

[in] pctbIssuedCertEncoded

The requested certificate, if issued.

Return value
If this method succeeds, it returns S_OK . Otherwise, it returns an HRESULT error code.

Requirements

Target Platform Windows

Header certpol.h

See also
INDESPolicy
 INDESPolicy::Uninitialize method (certpol.h)
7/2/2022 • 2 minutes to read • Edit Online

Uninitializes the NDES policy module.

Syntax
HRESULT Uninitialize();

Return value
If this method succeeds, it returns S_OK . Otherwise, it returns an HRESULT error code.

Requirements

Target Platform Windows

Header certpol.h

See also
INDESPolicy
 INDESPolicy::VerifyRequest method (certpol.h)
7/2/2022 • 2 minutes to read • Edit Online

Verifies the NDES certificate request for submission to the CA.

Syntax
HRESULT VerifyRequest(
[in] CERTTRANSBLOB *pctbRequest,
[in] CERTTRANSBLOB *pctbSigningCertEncoded,
[in] PCWSTR pwszTemplate,
[in] PCWSTR pwszTransactionId,
[out, retval] BOOL *pfVerified
);

Parameters
[in] pctbRequest

The encoded PKCS#10 request.

[in] pctbSigningCertEncoded

The valid signing certificate for a renewal request.

[in] pwszTemplate

The template being requested for, as determined by NDES.

[in] pwszTransactionId

The SCEP request transaction ID.

[out, retval] pfVerified

True if the challenge is verified; otherwise false.

Return value
If this method succeeds, it returns S_OK . Otherwise, it returns an HRESULT error code.

Requirements

Target Platform Windows

Header certpol.h

See also
INDESPolicy
 X509SCEPDisposition enumeration (certpol.h)
7/2/2022 • 2 minutes to read • Edit Online

The X509SCEPDisposition enumeration describes the resulting disposition of a request to process a response
message. This enumeration is used by the IX509SCEPEnrollment interface.

Syntax
typedef enum X509SCEPDisposition {
SCEPDispositionUnknown = -1,
SCEPDispositionSuccess = 0,
SCEPDispositionFailure = 2,
SCEPDispositionPending = 3,
SCEPDispositionPendingChallenge = 11
} ;

Constants

SCEPDispositionUnknown
Value: -1

SCEPDispositionSuccess
Value: 0
The request was successful.

SCEPDispositionFailure
Value: 2
The request failed.

SCEPDispositionPending
Value: 3
The request has not completed yet.

SCEPDispositionPendingChallenge
Value: 11

Requirements

Header certpol.h (include CertEnroll.h)

See also
ProcessResponseMessage
 X509SCEPFailInfo enumeration (certpol.h)
7/2/2022 • 2 minutes to read • Edit Online

The X509SCEPFailInfo enumeration describes the nature of an SCEP certificate enrollment failure. This
enumeration is used by the IX509SCEPEnrollment interface.

Syntax
typedef enum X509SCEPFailInfo {
SCEPFailUnknown = -1,
SCEPFailBadAlgorithm = 0,
SCEPFailBadMessageCheck = 1,
SCEPFailBadRequest = 2,
SCEPFailBadTime = 3,
SCEPFailBadCertId = 4
} ;

Constants

SCEPFailUnknown
Value: -1

SCEPFailBadAlgorithm
Value: 0
Failure due to an unrecognized or unsupported algorithm.

SCEPFailBadMessageCheck
Value: 1
The integrity check failed.

SCEPFailBadRequest
Value: 2
The transaction was not permitted or was not supported.

SCEPFailBadTime
Value: 3
The signing time attribute from the PKCS7 authenticated attributes was not sufficiently close to the system time.

SCEPFailBadCertId
Value: 4
No certificate could be identified.

Requirements

Header certpol.h (include CertEnroll.h)

See also
FailInfo
 certpoleng.h header
7/2/2022 • 2 minutes to read • Edit Online

This header is used by Security and Identity. For more information, see:
Security and Identity
certpoleng.h contains the following programming interfaces:

Functions

PstAcquirePrivateKey

Associates the caller's private key with the specified certificate.

PstGetCertificates

Retrieves certificate chains that specify certificates that can be used to authenticate a user on the specified server.

PstGetTrustAnchors

Retrieves a list of certification authorities (CAs) trusted by the specified server.

PstGetUserNameForCertificate

Retrieves the user name associated with the specified certificate.

PstMapCertificate

Retrieves a structure that specifies information that can be used to create a user token associated with the specified certificate.

PstValidate

Validates the specified certificate.

 PstAcquirePrivateKey function (certpoleng.h)
7/2/2022 • 2 minutes to read • Edit Online

Associates the caller's private key with the specified certificate.

Syntax
NTSTATUS PstAcquirePrivateKey(
[in] PCCERT_CONTEXT pCert
);

Parameters
[in] pCert

The certificate with which to associate the private key.

Return value
If the function succeeds, return STATUS_SUCCESS .
If the function fails, return an NTSTATUS code that indicates the reason it failed.

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Target Platform Windows

Header certpoleng.h

Librar y Certpoleng.lib

DLL Certpoleng.dll
 PstGetCertificates function (certpoleng.h)
7/2/2022 • 2 minutes to read • Edit Online

Retrieves certificate chains that specify certificates that can be used to authenticate a user on the specified
server.

Syntax
NTSTATUS PstGetCertificates(
[in] PUNICODE_STRING pTargetName,
[in] DWORD cCriteria,
[in, optional] PCCERT_SELECT_CRITERIA rgpCriteria,
[in] BOOL bIsClient,
[out] PDWORD pdwCertChainContextCount,
[out] PCCERT_CHAIN_CONTEXT **ppCertChainContexts
);

Parameters
[in] pTargetName

The name of the server to check.

[in] cCriteria

The number of elements in the rgpCriteria array.

[in, optional] rgpCriteria

A constant pointer to an array of CERT_SELECT_CRITERIA structures that specify the criteria used to select
certificate chains.
[in] bIsClient

TRUE if the caller is the client; otherwise, FALSE .

[out] pdwCertChainContextCount

The number of elements in the ppCertChainContexts array.

[out] ppCertChainContexts

The address of a pointer to an array of CERT_CHAIN_CONTEXT structures that specifies the certificate chains of
certificates that can be used to authenticate a user on the server specified by the pTargetName parameter.

Return value
If the function succeeds, return STATUS_SUCCESS .
If the function fails, return an NTSTATUS code that indicates the reason it failed.

Requirements
Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Target Platform Windows

Header certpoleng.h

Librar y Certpoleng.lib

DLL Certpoleng.dll
 PstGetTrustAnchors function (certpoleng.h)
7/2/2022 • 2 minutes to read • Edit Online

Retrieves a list of certification authorities (CAs) trusted by the specified server.

Syntax
NTSTATUS PstGetTrustAnchors(
[in] PUNICODE_STRING pTargetName,
[in] DWORD cCriteria,
[in, optional] PCCERT_SELECT_CRITERIA rgpCriteria,
[out] PSecPkgContext_IssuerListInfoEx *ppTrustedIssuers
);

Parameters
[in] pTargetName

The name of the server to check.

[in] cCriteria

The number of elements in the rgpCriteria array.

[in, optional] rgpCriteria

A constant pointer to an array of CERT_SELECT_CRITERIA structures that specify the criteria used to select
certificate chains.
[out] ppTrustedIssuers

A pointer to an array of SecPkgContext_IssuerListInfoEx structures that receive the CAs trusted by the server
specified by the pTargetName parameter.

Return value
If the function succeeds, return STATUS_SUCCESS.
If the function fails, return an NTSTATUS code that indicates the reason it failed.

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Target Platform Windows

Header certpoleng.h
Librar y Certpoleng.lib

DLL Certpoleng.dll
 PstGetUserNameForCertificate function
(certpoleng.h)
7/2/2022 • 2 minutes to read • Edit Online

Retrieves the user name associated with the specified certificate.

Syntax
NTSTATUS PstGetUserNameForCertificate(
[in] PCCERT_CONTEXT pCertContext,
[out] PUNICODE_STRING UserName
);

Parameters
[in] pCertContext

A constant pointer to a CERT_CONTEXT structure that specifies the certificate for which to obtain the user name.
[out] UserName

The user name associated with the certificate specified by the pCertContext parameter.

Return value
If the function succeeds, return STATUS_SUCCESS .
If the function fails, return an NTSTATUS code that indicates the reason it failed.

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Target Platform Windows

Header certpoleng.h

Librar y Certpoleng.lib

DLL Certpoleng.dll
 PstMapCertificate function (certpoleng.h)
7/2/2022 • 2 minutes to read • Edit Online

Retrieves a structure that specifies information that can be used to create a user token associated with the
specified certificate.

Syntax
NTSTATUS PstMapCertificate(
[in] PCCERT_CONTEXT pCert,
[out] LSA_TOKEN_INFORMATION_TYPE *pTokenInformationType,
[out] PVOID *ppTokenInformation
);

Parameters
[in] pCert

A constant pointer to a CERT_CONTEXT structure that specifies the certificate for which to obtain token
information.
[out] pTokenInformationType

A pointer to a value of the LSA_TOKEN_INFORMATION_TYPE enumeration that indicates the type of structure
pointed to by the ppTokenInformation parameter.
[out] ppTokenInformation

The address of a pointer to a structure that specifies information that can be used to create a user token.

Return value
If the function succeeds, return STATUS_SUCCESS .
If the function fails, return an NTSTATUS code that indicates the reason it failed.

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Target Platform Windows

Header certpoleng.h

Librar y Certpoleng.lib

DLL Certpoleng.dll
 PstValidate function (certpoleng.h)
7/2/2022 • 2 minutes to read • Edit Online

Validates the specified certificate.

Syntax
NTSTATUS PstValidate(
[in, optional] PUNICODE_STRING pTargetName,
[in] BOOL bIsClient,
[in, optional] CERT_USAGE_MATCH *pRequestedIssuancePolicy,
[in, optional] HCERTSTORE *phAdditionalCertStore,
[in] PCCERT_CONTEXT pCert,
[out, optional] GUID *pProvGUID
);

Parameters
[in, optional] pTargetName

The name of the server. If the caller is not the client, this parameter is NULL .
[in] bIsClient

TRUE if the caller is the client; otherwise, FALSE .

[in, optional] pRequestedIssuancePolicy

A pointer to a CERT_USAGE_MATCH structure that specifies identifiers that the certificate must match to be
validated.
[in, optional] phAdditionalCertStore

A handle to a certificate store that contains additional certificates used for the authentication.
[in] pCert

A pointer to a CERT_CONTEXT structure that specifies the certificate to validate.

[out, optional] pProvGUID

A pointer to a GUID structure that receives the security support provider (SSP) used for the authentication.

Return value
If the function succeeds, return STATUS_SUCCESS .
If the function fails, return an NTSTATUS code that indicates the reason it failed.

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Target Platform Windows

Header certpoleng.h

Librar y Certpoleng.lib

DLL Certpoleng.dll
 certsrv.h header
7/2/2022 • 2 minutes to read • Edit Online

This header is used by Security and Identity. For more information, see:
Security and Identity
certsrv.h contains the following programming interfaces:

Enumerations

ENUM_CATYPES

Specifies a certification authority (CA) type.

 ENUM_CATYPES enumeration (certsrv.h)
7/2/2022 • 2 minutes to read • Edit Online

The ENUM_CATYPES enumeration specifies a certification authority (CA) type.

Syntax
typedef enum {
ENUM_ENTERPRISE_ROOTCA = 0,
ENUM_ENTERPRISE_SUBCA = 1,
ENUM_STANDALONE_ROOTCA = 3,
ENUM_STANDALONE_SUBCA = 4,
ENUM_UNKNOWN_CA = 5
} ENUM_CATYPES;

Constants

ENUM_ENTERPRISE_ROOTCA
Value: 0
A root CA that is a member of an Active Directory domain and uses Directory Service to issue and manage certificates.

ENUM_ENTERPRISE_SUBCA
Value: 1
A CA that uses Directory Service to issue and manage certificates and is subordinate to an enterprise root CA.

ENUM_STANDALONE_ROOTCA
Value: 3
A root CA that does not use Directory Service to issue or manage certificates. It might or might not belong to a domain.

ENUM_STANDALONE_SUBCA
Value: 4
A CA that does not use Directory Service to issue or manage certificates and is subordinate to a standalone root CA.

ENUM_UNKNOWN_CA
Value: 5
An unknown CA type.

Requirements

Header certsrv.h
 certview.h header
7/2/2022 • 2 minutes to read • Edit Online

This header is used by Security and Identity. For more information, see:
Security and Identity
certview.h contains the following programming interfaces:

Interfaces

ICertView

Allows properly authorized clients to create a customized or complete view of the Certificate Services database.

ICertView2

Allow properly authorized clients to create a customized or complete view of the Certificate Services database.

IEnumCERTVIEWATTRIBUTE

Represents an attribute-enumeration sequence that contains the certificate attributes for the current row of the row-
enumeration sequence.

IEnumCERTVIEWCOLUMN

Represents a column-enumeration sequence that contains the column data for the current row of the enumeration sequence.

IEnumCERTVIEWEXTENSION

Represents an extension-enumeration sequence that contains the certificate extension data for the current row of the row-
enumeration sequence.

IEnumCERTVIEWROW

Represents a row-enumeration sequence that contains the data in the rows of the Certificate Services view, allowing further
access to the columns, attributes, and extensions associated with each row.
 ICertView interface (certview.h)
7/2/2022 • 2 minutes to read • Edit Online

The ICer tView interface allows properly authorized clients to create a customized or complete view of the
Certificate Services database.
The ICer tView interface is used to perform the following tasks:
Establish a connection with a Certificate Services server.
Obtain a row-enumeration sequence of the rows in the Certificate Services database.
Obtain a column-enumeration sequence for the columns of a row in the Certificate Services database.
Get the column count and index.
Specify sorting and qualifying restrictions for a column.
Specify the number of columns and a specific column in a customized view.
In C++, the ICer tView interface is instantiated through a call to the COM function CoCreateInstance. If, on the
other hand, you are using Visual Basic Scripting Edition, you will need to reference the CertAdm Type library in
your project and then instantiate the CCertView object by a call to 'New'. The sample code for the
ICertView::OpenConnection method illustrates the instantiation techniques.
The ICer tView interface is defined in Certview.h. When you create your program, however, use Certsrv.h as the
include file. Certadm.dll provides the ICer tView interface. The type information for this interface is also in
Certadml.dll, which is shipped with the Platform Software Development Kit (SDK).
Certificate Services interfaces support both apartment-threading and free-threading models. For better
throughput, free threading is recommended.

Inheritance
The ICer tView interface inherits from the IDispatch interface. ICer tView also has these types of members:

Methods
The ICer tView interface has these methods.

ICertView::EnumCertViewColumn

Obtains an instance of a column-enumeration sequence for the database schema.

ICertView::GetColumnCount

Retrieves the number of columns in the view of the Certificate Services database.

ICertView::GetColumnIndex

Retrieves the zero-based index of a column.

ICertView::OpenConnection

Establishes a connection with a Certificate Services server.

 ICertView::OpenView

Opens a view to a Certificate Services database and instantiates an instance of an IEnumCERTVIEWROW object.

ICertView::SetRestriction

Sets the sorting and qualifying restrictions on a column.

ICertView::SetResultColumn

Specifies a column for the result set of a customized view of the Certificate Services database.

ICertView::SetResultColumnCount

Specifies the maximum number of columns for the result set of a customized view of the Certificate Services database.

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header certview.h (include Certsrv.h)

See also
IDispatch
IEnumCERTVIEWCOLUMN
IEnumCERTVIEWROW
 ICertView::EnumCertViewColumn method
(certview.h)
7/2/2022 • 2 minutes to read • Edit Online

The EnumCer tViewColumn method obtains an instance of a column-enumeration sequence for the database
schema.
Note that this enumeration sequence cannot be used to enumerate the column values, only the database
schema. Use IEnumCERTVIEWROW::EnumCertViewColumn if you need to enumerate the data values of the
columns.

Syntax
HRESULT EnumCertViewColumn(
[in] LONG fResultColumn,
[out] IEnumCERTVIEWCOLUMN **ppenum
);

Parameters
[in] fResultColumn

Specifies the column. This parameter can be one of the following values.

VA L UE M EA N IN G

Schema column information.

CVRC_COLUMN_SCHEMA

Result column information.

CVRC_COLUMN_RESULT

Value column information.

CVRC_COLUMN_VALUE

Column information mask.

CVRC_COLUMN_MASK

[out] ppenum

A pointer to a pointer of IEnumCERTVIEWCOLUMN type. This method fails if the ppenum parameter is NULL .

Return value
C++
If the method succeeds, the method returns S_OK, and *ppenum is set to a pointer of IEnumCERTVIEWCOLUMN
type.
If the method fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.
VB
The return value is an IEnumCERTVIEWCOLUMN object.

Remarks
The IEnumCERTVIEWCOLUMN object can be used to enumerate the view's columns and retrieve each column's
information.

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header certview.h (include Certsrv.h)

Librar y Certidl.lib

DLL Certadm.dll

See also
EnumCERTVIEWCOLUMN
ICertView
ICertView2
 ICertView::GetColumnCount method (certview.h)
7/2/2022 • 2 minutes to read • Edit Online

The GetColumnCount method retrieves the number of columns in the view of the Certificate Services
database.

Syntax
HRESULT GetColumnCount(
[in] LONG fResultColumn,
[out] LONG *pcColumn
);

Parameters
[in] fResultColumn

Specifies the column. This parameter can be one of the following values.

VA L UE M EA N IN G

Schema column information.

CVRC_COLUMN_SCHEMA

Result column information.

CVRC_COLUMN_RESULT

Value column information.

CVRC_COLUMN_VALUE

Column information mask.

CVRC_COLUMN_MASK

[out] pcColumn

A pointer to a variable that contains the number of columns in the view. This function will fail if the pcColumn
parameter is NULL .

Return value
C++
If the method succeeds, the method returns S_OK, and the pcColumn parameter is set to the number of columns in
the view.
If the method fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.
VB
The return value is the number of columns in the view.
Remarks
This method is used to determine the number of columns in the view. The returned number represents the
count of a result set's columns if fResultColumn is TRUE or the count of the full database schema's columns if
fResultColumn is FALSE .

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header certview.h (include Certsrv.h)

Librar y Certidl.lib

DLL Certadm.dll

See also
CCertView
ICertView
ICertView::SetResultColumnCount
 ICertView::OpenConnection method (certview.h)
7/2/2022 • 2 minutes to read • Edit Online

The OpenConnection method establishes a connection with a Certificate Services server.

Syntax
HRESULT OpenConnection(
[in] const BSTR strConfig
);

Parameters
[in] strConfig

Represents a valid configuration string for the Certificate Services server. The configuration string is in the form
COMPUTERNAME\CANAME, where COMPUTERNAME is the server's network name, and CANAME is the
common name of the certification authority entered during Certificate Services setup. For information about the
configuration string name, see ICertConfig.

Return value
VB
If the method succeeds, the method returns S_OK.
If the method fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.

Remarks
Upon successful completion of this method, the ICertView object will have a connection to the Certificate
Services server specified in the strConfig parameter.
To close the connection, call the Release function.
Examples
 ICertView * pCertView = NULL;
BSTR strCertServ = NULL;
HRESULT hr;

// Initialize COM.
hr = CoInitializeEx(NULL, COINIT_APARTMENTTHREADED);

if (FAILED(hr))
{
printf("Failed CoInitializeEx\n");
goto error;
}
// Get pointer to the ICertView interface.
hr = CoCreateInstance(CLSID_CCertView,
NULL,
CLSCTX_INPROC_SERVER,
IID_ICertView,
(void **)&pCertView);
if (FAILED(hr))
{
printf("Failed CoCreateInstance\n");
goto error;
}
// The use of '\\' is necessary to represent a single backslash.
strCertServ = SysAllocString(TEXT("Server01\\ABCCertServ"));
// Open the connection to the Certificate Services server.
hr = pCertView->OpenConnection(strCertServ);
if (FAILED(hr))
{
printf("Failed OpenConnection!\n");
goto error;
}
else
// Established successful connection; use view as appropriate.
// ...
// Done using objects; free resources.
error:
if (NULL != pCertView)
pCertView->Release();
if (NULL != strCertServ)
SysFreeString(strCertServ);
// Free COM resources.
CoUninitialize();

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header certview.h (include Certsrv.h)

Librar y Certidl.lib

DLL Certadm.dll
See also
ICertConfig
ICertView
ICertView2
ICertView::OpenView
 ICertView::OpenView method (certview.h)
7/2/2022 • 2 minutes to read • Edit Online

The OpenView method opens a view to a Certificate Services database and instantiates an instance of an
IEnumCERTVIEWROW object.

Syntax
HRESULT OpenView(
[out] IEnumCERTVIEWROW **ppenum
);

Parameters
[out] ppenum

A pointer to a pointer of IEnumCERTVIEWROW type.

Return value
C++
If the method succeeds, the method returns S_OK.
If the method fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.
VB
The return value is an IEnumCERTVIEWROW object.

Remarks
Before calling the OpenView method, it is necessary to establish a connection with a Certificate Services server
by calling the OpenConnection method first.
The IEnumCERTVIEWROW object returned by this call represents a row-enumeration sequence whose internal
index is pointing to the beginning of the sequence. To look at the first row in the sequence, call the
IEnumCERTVIEWROW::Next method, which moves the internal index to the first row.
To view a nondefault column set or a subset of the rows, call SetResultColumnCount, SetResultColumn, and
SetRestriction after calling OpenConnection and before calling OpenView .
Examples
 // pCertView is previously instantiated pointer to ICertView.
IEnumCERTVIEWROW * pEnumRow = NULL;
HRESULT hr;

hr = pCertView->OpenView(&pEnumRow);
if (S_OK != hr)
printf("Failed ICertView::OpenView - %x\n", hr);
else
// use pEnumRow as needed, to enumerate data rows
// ...
// Done processing, free resources.
if (NULL != pEnumRow)
pEnumRow->Release();

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header certview.h (include Certsrv.h)

Librar y Certidl.lib

DLL Certadm.dll

See also
ICertView
ICertView2
ICertView::OpenConnection
IEnumCERTVIEWROW
IEnumCERTVIEWROW::Next
 ICertView::SetRestriction method (certview.h)
7/2/2022 • 2 minutes to read • Edit Online

The SetRestriction method sets the sorting and qualifying restrictions on a column.

Syntax
HRESULT SetRestriction(
[in] LONG ColumnIndex,
[in] LONG SeekOperator,
[in] LONG SortOrder,
[in] const VARIANT *pvarValue
);

Parameters
[in] ColumnIndex

A valid column index number for the view or a predefined column specifier. If the ColumnIndex parameter is not
negative, this value represents the zero-based index of the column that is receiving the restriction.
If the ColumnIndex parameter is negative, all other parameters are ignored, and this parameter must be one of
the following values.

VA L UE M EA N IN G

Restricts view to requests that have been resolved. A request

CV_COLUMN_LOG_DEFAULT is resolved if it has resulted in an issued certificate or a failed
request; revoked certificates are considered resolved.

Restricts view to requests that have failed.

CV_COLUMN_LOG_FAILED_DEFAULT

Restricts view to requests that have not been resolved; if a

CV_COLUMN_QUEUE_DEFAULT request has resulted in either an issued certificate or a failed
request, it will not be part of the view.

[in] SeekOperator

Specifies the logical operator of the data-query qualifier for the column. This parameter is used with the
pvarValue parameter to define the data-query qualifier. This parameter must be set to one of the following
values.

VA L UE M EA N IN G

Equal to
CVR_SEEK_EQ

Less than or equal to

CVR_SEEK_LE
 Less than
CVR_SEEK_LT

Greater than or equal to

CVR_SEEK_GE

Greater than
CVR_SEEK_GT

[in] SortOrder

Specifies the sort order for the column. Indexed columns with zero or one restriction can include a sort order of
CVR_SORT_ASCEND or CVR_SORT_DESCEND. Nonindexed columns or columns with two or more restrictions
must use CVR_SORT_NONE.

VA L UE M EA N IN G

Ascending
CVR_SORT_ASCEND

Descending
CVR_SORT_DESCEND

No sort order
CVR_SORT_NONE

[in] pvarValue

Specifies the data query qualifier applied to this column. This parameter, along with the SeekOperator
parameter, determines which data is returned to the Certificate Services view.

Return value
VB
If the method succeeds, the method returns S_OK.
If the method fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.

Remarks
The ICertView object maintains an array of restrictions, allowing each column to contain any number of
restrictions. After the column restrictions are established, a call to the ICertView::OpenView method will retrieve
the data, with each column's restrictions used as part of the database query.
Before the SetRestriction method is called, it is necessary to establish a connection with the Certificate Service
server by calling the ICertView::OpenConnection method.
Examples
 // This example restricts the data
// to rows that have RequestIDs greater than five.
// pCertView is a pointer to ICertView.
HRESULT hr;
VARIANT varRest;
LONG nIndex;
BSTR bstrCol = NULL;

// Use one column in the result set.

hr = pCertView->SetResultColumnCount(1);
if (FAILED(hr))
{
printf("Failed SetResultColumnCount - %x\n", hr);
goto error;
}
// Determine the column index for RequestID column.
bstrCol = SysAllocString(TEXT("RequestID"));
hr = pCertView->GetColumnIndex(FALSE, bstrCol, &nIndex);
if (FAILED(hr))
{
printf("Failed GetColumnIndex - %x\n", hr);
goto error;
}
// Place this column into the result set.
pCertView->SetResultColumn(nIndex);
// Set a restriction on this column.
VariantInit(&varRest);
varRest.vt = VT_I4;
varRest.lVal = 5;
// Restrict view to requests with ID greater than 5.
hr = pCertView->SetRestriction(nIndex,
CVR_SEEK_GT,
CVR_SORT_NONE,
&varRest);
if (S_OK != hr)
printf("Failed ICertView::SetRestriction - %x\n", hr);
else
{
// Call OpenView, process rows, release resources, and so on.
// ...
}
error:
// Done processing, clear resources.
VariantClear(&varRest);
if (NULL != bstrCol)
SysFreeString(bstrCol);

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header certview.h (include Certsrv.h)

Librar y Certidl.lib
 DLL Certadm.dll

See also
ICertView
ICertView2
ICertView::OpenConnection
ICertView::OpenView
ICertView::SetResultColumn
IEnumCertViewColumn::IsIndexed
 ICertView::SetResultColumn method (certview.h)
7/2/2022 • 2 minutes to read • Edit Online

The SetResultColumn method specifies a column for the result set of a customized view of the Certificate
Services database.

Syntax
HRESULT SetResultColumn(
[in] LONG ColumnIndex
);

Parameters
[in] ColumnIndex

A zero-based index of a column to include in the result set.

Return value
VB
If the method succeeds, the method returns S_OK.
If the method fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.

Remarks
Before calling the SetResultColumn method, the SetResultColumnCount method must be called to specify
how many columns will be in the result set. Calls to the SetResultColumn method will fail under the following
conditions:
The number of columns has not been specified.
SetResultColumn is called more times than the number of columns specified by the call to
SetResultColumnCount.
SetResultColumnCount specified a predefined set of columns. This method specifies a predefined set of
columns when its cResultColumnCount parameter is one of the following values:
CV_COLUMN_LOG_DEFAULT
CV_COLUMN_LOG_FAILED_DEFAULT
CV_COLUMN_QUEUE_DEFAULT
After a column is specified, an optional call to the SetRestriction method can be used to specify sorting and
qualifying restrictions for the column.
The SetResultColumn method must be called for each column that is needed in the result set. On successful
completion of these calls, the columns specified in each call will be included in the result set when the OpenView
method is called.
Examples
 HRESULT hr;
LONG nCount;
LONG i;

// Determine the number of columns in the entire database.

// pCertView is a pointer to ICertView.
hr = pCertView->GetColumnCount(FALSE, &nCount);
if (FAILED(hr))
{
printf("Failed GetColumnCount - %x\n", hr);
goto error;
}
hr = pCertView->SetResultColumnCount( nCount );
if (FAILED(hr))
{
printf("Failed SetResultColumnCount - %x\n", hr);
goto error;
}
// Place each column in the view.
for (i = 0; i < nCount; i++)
{
hr = pCertView->SetResultColumn(i);
if (FAILED(hr))
{
printf("Failed SetResultColumn (%d) - %x\n", i, hr );
goto error;
}
}
// Call ICertView::OpenView, and so on.
// ...

error:
{
// Clean up resources, and so on.
}

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header certview.h (include Certsrv.h)

Librar y Certidl.lib

DLL Certadm.dll

See also
ICertView
ICertView2
ICertView::OpenView
ICertView::SetRestriction
ICertView::SetResultColumnCount
 ICertView::SetResultColumnCount method
(certview.h)
7/2/2022 • 2 minutes to read • Edit Online

The SetResultColumnCount method specifies the maximum number of columns for the result set of a
customized view of the Certificate Services database.

Syntax
HRESULT SetResultColumnCount(
[in] LONG cResultColumn
);

Parameters
[in] cResultColumn

Specifies the maximum number of columns in the result set. This parameter can be set to a positive number, or
to zero if you are only interested in counting the rows of the Certificate Services database, or to one of the
following constants.

VA L UE M EA N IN G

The number of columns in the result set will be the number

CV_COLUMN_LOG_DEFAULT of columns in the Certificate Services' default result set for
requests that have been resolved. A request is resolved if it
has resulted in an issued certificate or a failed request;
revoked certificates are considered resolved.

The number of columns in the result set will be the number

CV_COLUMN_LOG_FAILED_DEFAULT of columns in the Certificate Services' default result set for
requests that have failed.

The number of columns in the result set will be the number

CV_COLUMN_QUEUE_DEFAULT of columns in the Certificate Services' default result set for
requests that have not been resolved.

Return value
VB
If the method succeeds, the method returns S_OK.
If the method fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.

Remarks
Before calling the SetResultColumnCount method, it is necessary to establish a connection with a Certificate
Services server by calling the OpenConnection method first. After the connection is established, this method can
be called once, and only once, to specify the maximum number of columns in the result set.
If the cResultColumn parameter is set to a positive number (not one of the predefined constants), the
SetResultColumn method must be called to specify which columns to include in the result set. Note that
SetResultColumn fails if it is called more than the number of columns specified by SetResultColumnCount .
Examples

HRESULT hr;
// Specify the result set for logged requests.
// pCertView is pointer to ICertView (which has an Open Connection)
hr = pCertView->SetResultColumnCount(CV_COLUMN_LOG_DEFAULT);
if (S_OK != hr)
printf("Failed ICertView::SetResultColumnCount - %x\n", hr);
else
{
// Retrieve data rows by means of ICertView::OpenView.
// ...
}

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header certview.h (include Certsrv.h)

Librar y Certidl.lib

DLL Certadm.dll

See also
ICertView
ICertView2
ICertView::OpenConnection
ICertView::SetRestriction
ICertView::SetResultColumn
 ICertView2 interface (certview.h)
7/2/2022 • 2 minutes to read • Edit Online

The ICer tView2 interface is one of two interfaces that allow properly authorized clients to create a customized
or complete view of the Certificate Services database.
The ICer tView2 interface is used to perform the following tasks:
Establish a connection with a Certificate Services server.
Obtain a row-enumeration sequence of the rows in the Certificate Services database.
Obtain a column-enumeration sequence for the schema in the Certificate Services database.
Get the column count and index.
Specify sorting and qualifying restrictions for a column.
Specify the number of columns and a specific column in a customized view.
Specify which tables are used by subsequent calls to ICer tView2 methods (introduced by ICer tView2 ).
In C++, the ICer tView2 interface is instantiated through a call to the COM function CoCreateInstance. If, on the
other hand, you are using Visual Basic Scripting Edition, you will need to reference the CertAdm Type library in
your project and then instantiate the CCer tView object by a call to 'New'. The sample code for the
OpenConnection method illustrates the instantiation techniques.
The ICer tView2 interface is defined in Certview.h. When you create your program, however, use Certsrv.h as
the include file. Certadm.dll provides the ICer tView2 interface. The type information for this interface is also in
Certadml.dll, which is shipped with the Platform Software Development Kit (SDK).
Certificate Services interfaces support both apartment-threading and free-threading models. For better
throughput, free threading is recommended.

Inheritance
The ICer tView2 interface inherits from ICertView and IDispatch. ICer tView2 also has these types of members:

Methods
The ICer tView2 interface has these methods.

ICertView2::SetTable

Specifies which Certificate Services database table is used for subsequent calls to the methods of the ICertView2 interface.

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]
Target Platform Windows

Header certview.h (include Certsrv.h)

 ICertView2::SetTable method (certview.h)
7/2/2022 • 2 minutes to read • Edit Online

The SetTable method specifies which Certificate Services database table is used for subsequent calls to the
methods of the ICertView2 interface.

Syntax
HRESULT SetTable(
[in] LONG Table
);

Parameters
[in] Table

Specifies the Certificate Services database table to use for subsequent calls. This parameter must be one of the
following values.

VA L UE M EA N IN G

The attributes table is used for subsequent calls.

CVRC_TABLE_ATTRIBUTES

The certificate revocation list (CRL) table is used for

CVRC_TABLE_CRL subsequent calls.

The extensions table is used for subsequent calls.

CVRC_TABLE_EXTENSIONS

The table of pending requests, denied requests, issued

CVRC_TABLE_REQCERT certificates, and revoked certificates is used for subsequent
calls.

Return value
VB
If the method succeeds, the method returns S_OK.
If the method fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.

Remarks
Before calling the SetTable method, it is necessary to establish a connection with a Certificate Services server
by calling the OpenConnection method first. After the OpenConnection and SetTable calls are made,
subsequent calls to the ICertView2 interface methods will use the Certificate Services database table specified
by the SetTable method.
If the SetTable method is not called, then the default table CVRC_TABLE_REQCERT is used.
Examples

HRESULT hr;

// Specify the certificate revocation list table.

hr = pCertView2->SetTable(CVRC_TABLE_CRL);
if (FAILED(hr))
{
printf("Failed SetTable\n");
exit(1); // Or other error action.
}

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header certview.h (include Certsrv.h)

Librar y Certidl.lib

DLL Certadm.dll
 IEnumCERTVIEWATTRIBUTE interface (certview.h)
7/2/2022 • 2 minutes to read • Edit Online

The IEnumCERTVIEWATTRIBUTE interface represents an attribute-enumeration sequence that contains the

certificate attributes for the current row of the row-enumeration sequence.
The attribute-enumeration sequence is obtained by a call to the IEnumCERTVIEWROW::EnumCertViewAttribute
method. After this enumeration sequence is obtained, the methods of the IEnumCERTVIEWATTRIBUTE
interface can be used to perform the following tasks:
Navigate through the enumeration of certificate attributes.
Retrieve the name and value of the attributes in the enumeration.
Clone an exact copy of the certificate attribute object.
IEnumCERTVIEWATTRIBUTE is defined in Certview.h. When you create your program, however, use Certsrv.h
as the include file. Certadm.dll provides the IEnumCERTVIEWATTRIBUTE interface. The type information for
this interface is also in Certadml.dll, which is shipped with the Platform Software Development Kit (SDK).
Certificate Services interfaces support both apartment-threading and free-threading models. For better
throughput, free threading is recommended.

Inheritance
The IEnumCERTVIEWATTRIBUTE interface inherits from the IDispatch interface.
IEnumCERTVIEWATTRIBUTE also has these types of members:

Methods
The IEnumCERTVIEWATTRIBUTE interface has these methods.

IEnumCERTVIEWATTRIBUTE::Clone

Creates a copy of the attribute-enumeration sequence object in its current state.

IEnumCERTVIEWATTRIBUTE::GetName

Retrieves the name of the current attribute in the attribute-enumeration sequence.

IEnumCERTVIEWATTRIBUTE::GetValue

Retrieves the value of the current attribute in the attribute-enumeration sequence.

IEnumCERTVIEWATTRIBUTE::Next

Moves to the next attribute in the attribute-enumeration sequence.

IEnumCERTVIEWATTRIBUTE::Reset

Moves to the beginning of the attribute-enumeration sequence.

 IEnumCERTVIEWATTRIBUTE::Skip

Skips a specified number of attributes in the attribute-enumeration sequence.

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header certview.h (include Certsrv.h)

See also
IDispatch
IEnumCERTVIEWROW::EnumCertViewAttribute
 IEnumCERTVIEWATTRIBUTE::Clone method
(certview.h)
7/2/2022 • 2 minutes to read • Edit Online

The Clone method creates a copy of the attribute-enumeration sequence object in its current state.

Syntax
HRESULT Clone(
[out] IEnumCERTVIEWATTRIBUTE **ppenum
);

Parameters
[out] ppenum

A pointer to a pointer of IEnumCERTVIEWATTRIBUTE type. This function will fail if ppenum is NULL .

Return value
C++
If the method succeeds, the method returns S_OK.
If the method fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.
VB
The return value is a cloned attribute-enumeration sequence object.

Remarks
The attribute-enumeration sequence object is obtained by a call to the
IEnumCERTVIEWROW::EnumCertViewAttribute method.
Examples

// pEnumAttr is previously instantiated IEnumCERTVIEWATTRIBUTE object

IEnumCERTVIEWATTRIBUTE * pEnumAttr2 = NULL;
HRESULT hr;
hr = pEnumAttr->Clone(&pEnumAttr2);
if (S_OK != hr)
printf("Unable to clone IEnumCERTVIEWATTRIBUTE\n");
else
{
// use cloned object as needed
// ...
}
// done using cloned object, free memory
if (NULL != pEnumAttr2)
pEnumAttr2->Release();
Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header certview.h (include Certsrv.h)

Librar y Certidl.lib

DLL Certadm.dll

See also
IEnumCERTVIEWATTRIBUTE
 IEnumCERTVIEWATTRIBUTE::GetName method
(certview.h)
7/2/2022 • 2 minutes to read • Edit Online

The GetName method retrieves the name of the current attribute in the attribute-enumeration sequence.

Syntax
HRESULT GetName(
[out] BSTR *pstrOut
);

Parameters
[out] pstrOut

A pointer to a variable of BSTR type that contains the name of the attribute.

Return value
C++
If the method succeeds, the method returns S_OK and the pstrOut parameter contains the name of the attribute.
To use this method, create a variable of BSTR type, set the variable equal to NULL , and pass the address of this
variable as pstrOut. When you have finished using the BSTR , free it by calling the SysFreeString function.
If the method fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.
VB
The return value is a String that contains the name of the attribute.

Remarks
This method is used to retrieve the name of the attribute currently referenced by the attribute-enumeration
sequence.
If the attribute-enumeration sequence is not referencing a valid attribute, GetName will fail. Use one of the
following methods to navigate through the enumeration:
IEnumCERTVIEWATTRIBUTE::Reset: Moves to the beginning of the enumeration sequence.
IEnumCERTVIEWATTRIBUTE::Next: Moves to the next attribute in the enumeration sequence.
IEnumCERTVIEWATTRIBUTE::Skip: Skips a specified number of attributes.
Examples
 BSTR bstrAttribName = NULL;

// pEnumAttr is previously instantiated IEnumCERTVIEWATTRIBUTE object

hr = pEnumAttr->GetName(&bstrAttribName);
if (S_OK != hr)
printf("Failed call to GetName - %x\n", hr);
else
printf("Attribute name is %ws\n", bstrAttribName );

// free memory when done

if (NULL != bstrAttribName)
SysFreeString(bstrAttribName);

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header certview.h (include Certsrv.h)

Librar y Certidl.lib

DLL Certadm.dll

See also
IEnumCERTVIEWATTRIBUTE
IEnumCERTVIEWATTRIBUTE::GetValue
IEnumCERTVIEWATTRIBUTE::Next
IEnumCERTVIEWATTRIBUTE::Reset
IEnumCERTVIEWATTRIBUTE::Skip
 IEnumCERTVIEWATTRIBUTE::GetValue method
(certview.h)
7/2/2022 • 2 minutes to read • Edit Online

The GetValue method retrieves the value of the current attribute in the attribute-enumeration sequence.

Syntax
HRESULT GetValue(
[out] BSTR *pstrOut
);

Parameters
[out] pstrOut

A pointer to a BSTR type that contains the value of the attribute.

Return value
C++
If the method succeeds, the method returns S_OK and the pstrOut is set to the value of the current attribute.
To use this method, create a variable of BSTR type, set the variable equal to NULL , and pass the address of this
variable as pstrOut. When you have finished using the BSTR , free it by calling the SysFreeString function.
If the method fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.
VB
The return value is a String that represents the value of the current attribute.

Remarks
This method is used to retrieve the data in the attribute currently referenced by the attribute-enumeration
sequence.
If the attribute-enumeration sequence is not referencing a valid attribute, GetValue will fail. Use one of the
following methods to navigate through the enumeration:
IEnumCERTVIEWATTRIBUTE::Reset: Moves to the beginning of the enumeration sequence.
IEnumCERTVIEWATTRIBUTE::Next: Moves to the next attribute in the enumeration sequence.
IEnumCERTVIEWATTRIBUTE::Skip: Skips a specified number of attributes.
Examples
 BSTR bstrAttribValue = NULL;

// pEnumAttr is previously instantiated IEnumCERTVIEWATTRIBUTE object

hr = pEnumAttr->GetValue(&bstrAttribValue);
if (S_OK != hr)
printf("Failed call to GetValue - %x\n", hr);
else
printf("Attribute value is %ws\n",bstrAttribValue);

// free memory when done

if (NULL != bstrAttribValue)
SysFreeString(bstrAttribValue);

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header certview.h (include Certsrv.h)

Librar y Certidl.lib

DLL Certadm.dll

See also
IEnumCERTVIEWATTRIBUTE
IEnumCERTVIEWATTRIBUTE::GetName
IEnumCERTVIEWATTRIBUTE::Next
IEnumCERTVIEWATTRIBUTE::Reset
IEnumCERTVIEWATTRIBUTE::Skip
 IEnumCERTVIEWATTRIBUTE::Next method
(certview.h)
7/2/2022 • 2 minutes to read • Edit Online

The Next method moves to the next attribute in the attribute-enumeration sequence.

Syntax
HRESULT Next(
[out] LONG *pIndex
);

Parameters
[out] pIndex

A pointer to a variable that contains the index value of the next attribute being referenced. If there are no more
attributes to enumerate, this variable is set to –1. This method fails if pIndex is NULL .

Return value
C++
If the method succeeds, the method returns S_OK and the next attribute is now being referenced by the attribute-
enumeration sequence. If there are no more attributes, the method returns S_FALSE, and pIndex is set to a value of –
1.
If the method fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.
VB
The return value is the index value of the attribute that is now referenced by the attribute-enumeration sequence. If
there are no more attributes to enumerate, the return value is –1.

Remarks
Upon successful completion of this method, the attribute name and value can be accessed through the following
methods:
IEnumCERTVIEWATTRIBUTE::GetName
IEnumCERTVIEWATTRIBUTE::GetValue
Examples
 LONG Index;
HRESULT hr;
BSTR bstrAttribName = NULL;

// pEnumAttr is previously instantiated IEnumCERTVIEWATTRIBUTE object

while (S_OK == pEnumAttr->Next(&Index))
{
// retrieve the attribute name
hr = pEnumAttr->GetName(&bstrAttribName);
if (FAILED(hr))
printf("Failed GetName - %x\n", hr );
else
printf("Attribute name: %ws\n", bstrAttribName);
}

// Free resources.
if (NULL != bstrAttribName)
SysFreeString(bstrAttribName);

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header certview.h (include Certsrv.h)

Librar y Certidl.lib

DLL Certadm.dll

See also
IEnumCERTVIEWATTRIBUTE
IEnumCERTVIEWATTRIBUTE::GetName
IEnumCERTVIEWATTRIBUTE::GetValue
IEnumCERTVIEWATTRIBUTE::Reset
IEnumCERTVIEWATTRIBUTE::Skip
 IEnumCERTVIEWATTRIBUTE::Reset method
(certview.h)
7/2/2022 • 2 minutes to read • Edit Online

The Reset method moves to the beginning of the attribute-enumeration sequence.

Syntax
HRESULT Reset();

Return value
VB
If the method succeeds, the method returns S_OK.
If the method fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.

Remarks
Upon successful completion of this method, call the IEnumCERTVIEWATTRIBUTE::Next method to reference the
first attribute in the attribute-enumeration sequence. The attribute name and value can be accessed by using the
following methods:
IEnumCERTVIEWATTRIBUTE::GetName
IEnumCERTVIEWATTRIBUTE::GetValue
Examples

// pEnumAttr is a previously instantiated

// IEnumCERTVIEWATTRIBUTE object.
HRESULT hr;
LONG Index;

hr = pEnumAttr->Reset();
if (S_OK != hr)
printf("Unable to reset pEnumAttr - %x\n", hr );

// Call the appropriate error handler and exit routine.

else
{

// Reset to the beginning of the attributes again.

while (S_OK == pEnumAttr->Next(&Index))
{

// Use each attribute as needed.

}
}

Requirements
 Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header certview.h (include Certsrv.h)

Librar y Certidl.lib

DLL Certadm.dll

See also
IEnumCERTVIEWATTRIBUTE
IEnumCERTVIEWATTRIBUTE::GetName
IEnumCERTVIEWATTRIBUTE::GetValue
IEnumCERTVIEWATTRIBUTE::Next
IEnumCERTVIEWATTRIBUTE::Skip
 IEnumCERTVIEWATTRIBUTE::Skip method
(certview.h)
7/2/2022 • 2 minutes to read • Edit Online

The Skip method skips a specified number of attributes in the attribute-enumeration sequence.

Syntax
HRESULT Skip(
[in] LONG celt
);

Parameters
[in] celt

The number of attributes to skip. A positive value for the celt parameter causes the attribute-enumeration
sequence to skip forward in the sequence. A negative value for the celt parameter causes the attribute-
enumeration sequence to skip backward in the sequence.

Return value
VB
If the method succeeds, the method returns S_OK.
A return value of E_INVALIDARG indicates that a negative value for the celt parameter caused the attribute-
enumeration sequence index to become less than zero.
If the method fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.

Remarks
Upon successful completion of this method, call the IEnumCERTVIEWATTRIBUTE::Next method to reference the
current attribute in the attribute-enumeration sequence. The attribute name and value can be accessed through
the following methods:
IEnumCERTVIEWATTRIBUTE::GetName
IEnumCERTVIEWATTRIBUTE::GetValue
The attribute-enumeration sequence maintains an internal zero-based index. The call to the Skip method causes this
index to increase or decrease by the number of attributes specified in the celt parameter.
If a negative value of the celt parameter causes the index to be less than zero, the behavior of subsequent calls
to IEnumCERTVIEWATTRIBUTE::Next is undefined.
If a positive value of the celt parameter causes the index to exceed the last attribute in the enumeration
sequence, a subsequent call to the IEnumCERTVIEWATTRIBUTE::Next method will fail.
Examples
 HRESULT hr;
LONG Index;

// pEnumAttr is previously instantiated IEnumCERTVIEWATTRIBUTE object

// skip the next 5 attributes
hr = pEnumAttr->Skip(5);
if (S_OK == hr)
{
// get the next attribute
hr = pEnumAttr->Next(&Index);
if (S_OK == hr)
{
// Use this attribute as needed.
}
}

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header certview.h (include Certsrv.h)

Librar y Certidl.lib

DLL Certadm.dll

See also
IEnumCERTVIEWATTRIBUTE
IEnumCERTVIEWATTRIBUTE::Reset
IEnumCERTVIEWATTRIBUTE:Next
 IEnumCERTVIEWCOLUMN interface (certview.h)
7/2/2022 • 2 minutes to read • Edit Online

The IEnumCERTVIEWCOLUMN interface represents a column-enumeration sequence that contains the

column data for the current row of the enumeration sequence.
The column-enumeration sequence is obtained by a call to the IEnumCERTVIEWROW::EnumCertViewColumn
method. After this enumeration sequence is obtained, the methods of the IEnumCERTVIEWCOLUMN interface
can be used to perform the following tasks:
Navigate through the enumeration.
Retrieve data from each column.
Clone an exact copy of the enumeration sequence.
IEnumCERTVIEWCOLUMN is defined in Certview.h. When you create your program, however, use Certsrv.h as
the include file. Certadm.dll provides the IEnumCERTVIEWCOLUMN interface. The type information for this
interface is also in Certadml.dll, which is shipped with the Platform Software Development Kit (SDK).
Certificate Services interfaces support both apartment-threading and free-threading models. For better
throughput, free threading is recommended.

Inheritance
The IEnumCERTVIEWCOLUMN interface inherits from the IDispatch interface. IEnumCERTVIEWCOLUMN
also has these types of members:

Methods
The IEnumCERTVIEWCOLUMN interface has these methods.

IEnumCERTVIEWCOLUMN::Clone

Creates a copy of the column-enumeration sequence.

IEnumCERTVIEWCOLUMN::GetDisplayName

Retrieves the localized name of the current column in the column-enumeration sequence.

IEnumCERTVIEWCOLUMN::GetMaxLength

Retrieves the maximum allowable length, in bytes, for the column data.

IEnumCERTVIEWCOLUMN::GetName

Retrieves the nonlocalized name of the current column in the column-enumeration sequence.

IEnumCERTVIEWCOLUMN::GetType

Retrieves the data type of the current column in the column-enumeration sequence.
 IEnumCERTVIEWCOLUMN::GetValue

Retrieves the data value contained in the current column in the column-enumeration sequence.

IEnumCERTVIEWCOLUMN::IsIndexed

Reports whether the data in the column is indexed.

IEnumCERTVIEWCOLUMN::Next

Moves to the next column in the column-enumeration sequence.

IEnumCERTVIEWCOLUMN::Reset

Moves to the beginning of the column-enumeration sequence.

IEnumCERTVIEWCOLUMN::Skip

Skips a specified number of columns in the column-enumeration sequence.

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header certview.h (include Certsrv.h)

See also
ICertView::EnumCertViewColumn
IDispatch
IEnumCERTVIEWROW::EnumCertViewColumn
 IEnumCERTVIEWCOLUMN::Clone method
(certview.h)
7/2/2022 • 2 minutes to read • Edit Online

The Clone method creates a copy of the column-enumeration sequence.

Syntax
HRESULT Clone(
[out] IEnumCERTVIEWCOLUMN **ppenum
);

Parameters
[out] ppenum

A pointer to a pointer of IEnumCERTVIEWCOLUMN type. This method will fail if the ppenum is NULL .

Return value
C++
If the method succeeds, the method returns S_OK.
If the method fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.
VB
The return value is a cloned column-enumeration sequence object.

Remarks
The column-enumeration sequence is obtained by a call to the IEnumCERTVIEWROW::EnumCertViewColumn
method.
Examples

// pEnumCol is previously instantiated IEnumCERTVIEWCOLUMN object

IEnumCERTVIEWCOLUMN * pEnumCol2 = NULL;
HRESULT hr;
hr = pEnumCol->Clone(&pEnumCol2);
if (S_OK != hr)
printf("Unable to clone IEnumCERTVIEWCOLUMN\n");
else
{
// use cloned object as needed
// ...
// done using cloned object, free memory
}
if (NULL != pEnumCol2)
pEnumCol2->Release();
Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header certview.h (include Certsrv.h)

Librar y Certidl.lib

DLL Certadm.dll

See also
IEnumCERTVIEWCOLUMN
IEnumCERTVIEWROW::EnumCertViewColumn
 IEnumCERTVIEWCOLUMN::GetDisplayName
method (certview.h)
7/2/2022 • 2 minutes to read • Edit Online

The GetDisplayName method retrieves the localized name of the current column in the column-enumeration
sequence.

Syntax
HRESULT GetDisplayName(
[out] BSTR *pstrOut
);

Parameters
[out] pstrOut

A pointer to a variable of BSTR type that contains the localized name of the column.

Return value
C++
If the method succeeds, the method returns S_OK and the pstrOut parameter contains the localized name of the
column.
To use this method, create a variable of BSTR type, set the variable equal to NULL , and pass the address of this
variable as pstrOut. When you have finished using the BSTR , free it by calling the SysFreeString function.
If the method fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.
VB
The return value is a String that contains the localized name of the column.

Remarks
This method is used to retrieve the localized name of the column currently referenced by the column-
enumeration sequence.
If the column-enumeration sequence is not referencing a valid column, GetDisplayName will fail. Use one of
the following methods to navigate through the enumeration:
IEnumCERTVIEWCOLUMN::Reset: Moves to the beginning of the enumeration sequence.
IEnumCERTVIEWCOLUMN::Next: Moves to the next column in the enumeration sequence.
IEnumCERTVIEWCOLUMN::Skip: Skips a specified number of columns.
Examples
 BSTR bstrDisplay = NULL;
HRESULT hr;

// pEnumCol is previously instantiated IEnumCERTVIEWCOLUMN object.

hr = pEnumCol->GetDisplayName(&bstrDisplay);
if (S_OK == hr)
printf("Column name is %ws\n", bstrDisplay);

// Done processing, clear resources.

if (NULL != bstrDisplay)
SysFreeString(bstrDisplay);

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header certview.h (include Certsrv.h)

Librar y Certidl.lib

DLL Certadm.dll

See also
IEnumCERTVIEWCOLUMN
IEnumCERTVIEWCOLUMN::Next
IEnumCERTVIEWCOLUMN::Reset
IEnumCERTVIEWCOLUMN::Skip
 IEnumCERTVIEWCOLUMN::GetMaxLength method
(certview.h)
7/2/2022 • 2 minutes to read • Edit Online

The GetMaxLength method retrieves the maximum allowable length, in bytes, for the column data.
If the column data's type is PROPTYPE_STRING , divide the number of bytes by sizeof(WCHAR) to determine
the maximum number of Unicode characters.

Syntax
HRESULT GetMaxLength(
[out] LONG *pMaxLength
);

Parameters
[out] pMaxLength

A pointer to a value of LONG type that contains the maximum allowable length for the column data. This
function will fail if pMaxLength is NULL .

Return value
C++
If the method succeeds, the method returns S_OK and the pMaxLength is set to the maximum allowable length for
the column data.
If the method fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.
VB
The return value is the maximum allowable length, in bytes, for the column data.

Remarks
This method is used to determine the maximum allowable data length for the column currently being
referenced by the column-enumeration sequence.
If the column-enumeration sequence is not referencing a valid column, GetMaxLength will fail. Use one of the
following methods to navigate through the enumeration:
IEnumCERTVIEWCOLUMN::Reset: Moves to the beginning of the enumeration sequence.
IEnumCERTVIEWCOLUMN::Next: Moves to the next column in the enumeration sequence.
IEnumCERTVIEWCOLUMN::Skip: Skips a specified number of columns.
To determine whether the column data is indexed, call the IEnumCERTVIEWCOLUMN::IsIndexed method.
Examples
 // pEnumCol is previously instantiated IEnumCERTVIEWCOLUMN object
HRESULT hr;
LONG nLength;

// determine database length

hr = pEnumCol->GetMaxLength(&nLength);
if (S_OK == hr)
printf("max length is %d\n", nLength);

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header certview.h (include Certsrv.h)

Librar y Certidl.lib

DLL Certadm.dll

See also
IEnumCERTVIEWCOLUMN
IEnumCERTVIEWCOLUMN::IsIndexed
IEnumCERTVIEWCOLUMN::Next
IEnumCERTVIEWCOLUMN::Reset
IEnumCERTVIEWCOLUMN::Skip
 IEnumCERTVIEWCOLUMN::GetName method
(certview.h)
7/2/2022 • 2 minutes to read • Edit Online

The GetName method retrieves the nonlocalized name of the current column in the column-enumeration
sequence.

Syntax
HRESULT GetName(
[out] BSTR *pstrOut
);

Parameters
[out] pstrOut

A pointer to a variable of BSTR type that contains the name of the column.

Return value
C++
If the method succeeds, the method returns S_OK and the pstrOut parameter contains the name of the column.
To use this method, create a variable of BSTR type, set the variable equal to NULL , and pass the address of this
variable as pstrOut. When you have finished using the BSTR , free it by calling the SysFreeString function.
If the method fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.
VB
The return value is a String that contains the name of the column.

Remarks
This method is used to retrieve the nonlocalized name of the column currently referenced by the column-
enumeration sequence.
If the column-enumeration sequence is not referencing a valid column, GetName will fail. Use one of the
following methods to navigate through the enumeration:
IEnumCERTVIEWCOLUMN::Reset: Moves to the beginning of the enumeration sequence.
IEnumCERTVIEWCOLUMN::Next: Moves to the next column in the enumeration sequence.
IEnumCERTVIEWCOLUMN::Skip: Skips a specified number of columns.
Examples
 BSTR bstrColName = NULL;
HRESULT hr;

// pEnumCol is previously instantiated IEnumCERTVIEWCOLUMN object

hr = pEnumCol->GetName(&bstrColName);
if (S_OK == hr)
printf("Column name is %ws\n", bstrColName);

// done processing, clear resources

if (NULL != bstrColName)
SysFreeString(bstrColName);

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header certview.h (include Certsrv.h)

Librar y Certidl.lib

DLL Certadm.dll

See also
IEnumCERTVIEWCOLUMN
IEnumCERTVIEWCOLUMN::Next
IEnumCERTVIEWCOLUMN::Reset
IEnumCERTVIEWCOLUMN::Skip
 IEnumCERTVIEWCOLUMN::GetType method
(certview.h)
7/2/2022 • 2 minutes to read • Edit Online

The GetType method retrieves the data type of the current column in the column-enumeration sequence.

Syntax
HRESULT GetType(
[out] LONG *pType
);

Parameters
[out] pType

A pointer to a variable of LONG type that denotes the data type of the column referenced by the column-
enumeration sequence. For a table of the valid data types, see Remarks. This method fails if the pType parameter
is set to NULL .

Return value
C++
If the method succeeds, the method returns S_OK.
If the method fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.
VB
The return value represents the data type of the column. For a table of the valid data types, see Remarks.

Remarks
This method is used to determine the data type of the column currently referenced by the column-enumeration
sequence. The valid data types are listed in the following table.

DATA T Y P E M EA N IN G

PROPTYPE_BINARY Binary data

PROPTYPE_DATE Date/time

PROPTYPE_LONG Signed long

PROPTYPE_STRING Unicode string

If the column-enumeration sequence is not referencing a valid column, GetType will fail. Use one of the
following methods to navigate through the enumeration:
 IEnumCERTVIEWCOLUMN::Reset: Moves to the beginning of the enumeration sequence.
IEnumCERTVIEWCOLUMN::Next: Moves to the next column in the enumeration sequence.
IEnumCERTVIEWCOLUMN::Skip: Skips a specified number of columns.
Examples

LONG nType;
HRESULT hr;

// pEnumCol is a previously instantiated IEnumCERTVIEWCOLUMN object.

hr = pEnumCol->GetType(&nType);
if (S_OK == hr)
{
switch (nType)
{
case PROPTYPE_BINARY:
printf("Type is Binary\n");
break;
case PROPTYPE_DATE:
printf("Type is Date+Time\n");
break;
case PROPTYPE_LONG:
printf("Type is Signed long\n");
break;
case PROPTYPE_STRING:
printf("Type is Unicode String\n");
break;
default:
printf("Type is unknown\n");
break;
}
}

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header certview.h (include Certsrv.h)

Librar y Certidl.lib

DLL Certadm.dll

See also
IEnumCERTVIEWCOLUMN
IEnumCERTVIEWCOLUMN::Next
IEnumCERTVIEWCOLUMN::Reset
IEnumCERTVIEWCOLUMN::Skip
 IEnumCERTVIEWCOLUMN::GetValue method
(certview.h)
7/2/2022 • 2 minutes to read • Edit Online

The GetValue method retrieves the data value contained in the current column in the column-enumeration
sequence.

Syntax
HRESULT GetValue(
[in] LONG Flags,
[out] VARIANT *pvarValue
);

Parameters
[in] Flags

An identifier that denotes the output format for the retrieved data. This parameter can be one of the following
values.

VA L UE M EA N IN G

BASE64 without BEGIN/END

CV_OUT_BASE64

BASE64 with BEGIN CERTIFICATE and END CERTIFICATE

CV_OUT_BASE64HEADER

BASE64 with BEGIN NEW CERTIFICATE REQUEST and END

CV_OUT_BASE64REQUESTHEADER NEW CERTIFICATE REQUEST

BASE64 with BEGIN X509 CRL and END X509 CRL

CV_OUT_BASE64X509CRLHEADER

Binary
CV_OUT_BINARY

Hexadecimal string
CV_OUT_HEX

Hexadecimal string with address/offset

CV_OUT_HEXADDR

Hexadecimal string with ASCII

CV_OUT_HEXASCII
 Hexadecimal string with ASCII and address/offset
CV_OUT_HEXASCIIADDR

[out] pvarValue

A pointer to value of VARIANT type that contains the data column. This method fails if pvarValue is NULL .
Upon successful completion of this method, pvarValue contains the data in the column. The caller is responsible
for calling VariantClear when done with this data.

Return value
C++
If the method succeeds, the method returns S_OK.
If the method fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.
VB
The return value is a Variant that represents the data in the column.

Remarks
This method is used to retrieve the data in the column currently being referenced by the column-enumeration
sequence.
If the column-enumeration sequence is not referencing a valid column, GetValue will fail. Use one of the
following methods to navigate through the enumeration:
IEnumCERTVIEWCOLUMN::Reset: Moves to the beginning of the enumeration sequence.
IEnumCERTVIEWCOLUMN::Next: Moves to the next column in the enumeration sequence.
IEnumCERTVIEWCOLUMN::Skip: Skips a specified number of columns.
Examples
 HRESULT hr;
VARIANT var;
SYSTEMTIME systime;

VariantInit(&var);

// pEnumCol is previously instantiated IEnumCERTVIEWCOLUMN object

hr = pEnumCol->GetValue(CV_OUT_HEX, &var);
if ( FAILED (hr) )
{
printf("Failed GetValue - %x\n", hr);
goto error;
}
switch( var.vt )
{
case VT_EMPTY:
printf( "VT_EMPTY\n" );
break;
case VT_BSTR:
printf("%ws\n", var.bstrVal );
break;
case VT_DATE:
VariantTimeToSystemTime( var.date, &systime );
printf("%d.%d.%d %02d:%02d:%02d\n",
systime.wMonth,
systime.wDay,
systime.wYear,
systime.wHour,
systime.wMinute,
systime.wSecond );
break;
case VT_I2:
printf("%d\n", var.iVal );
break;
case VT_I4:
printf("%d\n", var.lVal );
break;
default:
printf("type is:%i\n", var.vt );
break;
}
// done processing, clear resources
VariantClear( &var );

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header certview.h (include Certsrv.h)

Librar y Certidl.lib

DLL Certadm.dll
See also
IEnumCERTVIEWCOLUMN
IEnumCERTVIEWCOLUMN::Next
IEnumCERTVIEWCOLUMN::Reset
IEnumCERTVIEWCOLUMN::Skip
 IEnumCERTVIEWCOLUMN::IsIndexed method
(certview.h)
7/2/2022 • 2 minutes to read • Edit Online

The IsIndexed method reports whether the data in the column is indexed.

Syntax
HRESULT IsIndexed(
[out] LONG *pIndexed
);

Parameters
[out] pIndexed

A pointer to a variable of type LONG that indicates TRUE if the data is indexed and FALSE if the data is not
indexed. This method fails if pIndexed is set to NULL .

Return value
C++
If the method succeeds, the method returns S_OK and the pIndexed is set to TRUE or FALSE .
If the method fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.
VB
One if the column is indexed; otherwise, zero.

Remarks
This method is used to determine whether the data of the current column referenced by the column-
enumeration sequence is indexed.
If the column-enumeration sequence is not referencing a valid column, IsIndexed will fail. Use one of the
following methods to navigate through the enumeration:
IEnumCERTVIEWCOLUMN::Reset: Moves to the beginning of the enumeration sequence.
IEnumCERTVIEWCOLUMN::Next: Moves to the next column in the enumeration sequence.
IEnumCERTVIEWCOLUMN::Skip: Skips a specified number of columns.
Examples

HRESULT hr;
LONG bIsindexed;

// pEnumCol is previously instantiated IEnumCERTVIEWCOLUMN object

hr = pEnumCol->IsIndexed(&bIsindexed);
if (S_OK == hr)
printf( bIsindexed ? "Indexed\n" : "Not indexed\n");
Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header certview.h (include Certsrv.h)

Librar y Certidl.lib

DLL Certadm.dll

See also
IEnumCERTVIEWCOLUMN
IEnumCERTVIEWCOLUMN::Next
IEnumCERTVIEWCOLUMN::Reset
IEnumCERTVIEWCOLUMN::Skip
 IEnumCERTVIEWCOLUMN::Next method
(certview.h)
7/2/2022 • 2 minutes to read • Edit Online

The Next method moves to the next column in the column-enumeration sequence.

Syntax
HRESULT Next(
[out] LONG *pIndex
);

Parameters
[out] pIndex

A pointer to a variable that contains the index value of the next column referenced by the column-enumeration
sequence. If there are no more columns to enumerate, this variable is set to –1. This method will fail if pIndex is
NULL .

Return value
C++
If the method succeeds, the method returns S_OK and the next column in the column-enumeration sequence is now
being referenced. If there are no more columns to enumerate, the method returns S_FALSE, and the pIndex
parameter is set to a value of –1.
If the method fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.
VB
The return value is the index value of the column that is now referenced by the column-enumeration sequence. If
there are no more columns to enumerate, the return value is –1.

Remarks
Upon successful completion of this method, the information in the column can be obtained by calling one of the
following methods:
IEnumCERTVIEWCOLUMN::GetName: Retrieves the nonlocalized name of the column.
IEnumCERTVIEWCOLUMN::GetDisplayName: Retrieves the localized name of the column.
IEnumCERTVIEWCOLUMN::GetValue: Retrieves the data in the column.
IEnumCERTVIEWCOLUMN::GetType: Retrieves the type of data in the column.
IEnumCERTVIEWCOLUMN::GetMaxLength: Retrieves the maximum length, in bytes, of the column.
Examples

LONG nLength;
LONG nType;
LONG bIsindexed;
LONG Index;
LONG Index;

HRESULT hr;

BSTR bstrColName = NULL;

// pEnumCol is previously instantiated IEnumCERTVIEWCOLUMN object

// examine each column
while (S_OK == pEnumCol->Next(&Index))
{
// determine database length
hr = pEnumCol->GetMaxLength(&nLength);
if (FAILED(hr))
{
printf("Failed GetMaxLength %x\n", hr);
goto error;
}

// determine data type

hr = pEnumCol->GetType(&nType);
if (FAILED(hr))
{
printf("Failed GetType %x\n", hr);
goto error;
}

// determine whether column is indexed

hr = pEnumCol->IsIndexed(&bIsindexed);
if (FAILED(hr))
{
printf("Failed IsIndexed %x\n", hr);
goto error;
}

// retrieve column name

hr = pEnumCol->GetName(&bstrColName);
if (FAILED(hr))
{
printf("Failed GetName %x\n", hr);
goto error;
}

// print this column's info on one line

// print name and length
printf("Column %ws has max length %d",
bstrColName,
nLength);

// print data type

switch (nType)
{
case PROPTYPE_BINARY:
printf(" Type is Binary");
break;
case PROPTYPE_DATE:
printf(" Type is Date+Time");
break;
case PROPTYPE_LONG:
printf(" Type is Signed long");
break;
case PROPTYPE_STRING:
printf(" Type is Unicode String");
break;
default:
printf(" Type is unknown");
break;
}

// print index status

printf(bIsindexed ? " Indexed" : " Not indexed");
 printf(bIsindexed ? " Indexed" : " Not indexed");
// print new line marker
printf("\n");

error:

// done processing, clear resources

if (NULL != bstrColName)
SysFreeString(bstrColName);

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header certview.h (include Certsrv.h)

Librar y Certidl.lib

DLL Certadm.dll

See also
IEnumCERTVIEWCOLUMN
IEnumCERTVIEWCOLUMN::GetDisplayName
IEnumCERTVIEWCOLUMN::GetMaxLength
IEnumCERTVIEWCOLUMN::GetName
IEnumCERTVIEWCOLUMN::GetType
IEnumCERTVIEWCOLUMN::GetValue
 IEnumCERTVIEWCOLUMN::Reset method
(certview.h)
7/2/2022 • 2 minutes to read • Edit Online

The Reset method moves to the beginning of the column-enumeration sequence.

Syntax
HRESULT Reset();

Return value
VB
If the method succeeds, the method returns S_OK.
If the method fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.

Remarks
Upon successful completion of this method, call the IEnumCERTVIEWCOLUMN::Next method to reference the
first column in the enumeration. After this second call is made, the information in the column can be obtained
by calling one of the following methods:
IEnumCERTVIEWCOLUMN::GetName: Retrieves the nonlocalized name of the column.
IEnumCERTVIEWCOLUMN::GetDisplayName: Retrieves the localized name of the column.
IEnumCERTVIEWCOLUMN::GetValue: Retrieves the data in the column.
IEnumCERTVIEWCOLUMN::GetType: Retrieves the type of data in the column.
IEnumCERTVIEWCOLUMN::GetMaxLength: Retrieves the maximum length, in bytes, of the column.
Examples

// pEnumCol is previously instantiated IEnumCERTVIEWCOLUMN object

HRESULT hr;
LONG Index;
hr = pEnumCol->Reset();
if (S_OK != hr)
printf("Unable to reset pEnumCol\n");
// call appropriate error handler / exit routine
else
{
// now at the beginning of the columns
// enumerate each column
while (S_OK == pEnumCol->Next(&Index))
{
// Use each column as needed.
}
}

Requirements
 Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header certview.h (include Certsrv.h)

Librar y Certidl.lib

DLL Certadm.dll

See also
IEnumCERTVIEWCOLUMN
IEnumCERTVIEWCOLUMN::GetDisplayName
IEnumCERTVIEWCOLUMN::GetMaxLength
IEnumCERTVIEWCOLUMN::GetName
IEnumCERTVIEWCOLUMN::GetType
IEnumCERTVIEWCOLUMN::GetValue
 IEnumCERTVIEWCOLUMN::Skip method
(certview.h)
7/2/2022 • 2 minutes to read • Edit Online

The Skip method skips a specified number of columns in the column-enumeration sequence.

Syntax
HRESULT Skip(
[in] LONG celt
);

Parameters
[in] celt

The number of columns to skip. A positive value for the celt parameter causes the column-enumeration
sequence to skip forward in the enumeration sequence. A negative value causes column-enumeration to skip
backward in the enumeration sequence.

Return value
VB
If the method succeeds, the method returns S_OK.
A return value of E_INVALIDARG indicates that a negative value in the celt parameter caused the column-
enumeration sequence index to become less than zero.
If the method fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.

Remarks
Upon successful completion of this function, call the IEnumCERTVIEWCOLUMN::Next method to reference the
current column in the column-enumeration sequence. After this second call is made, the information in the
column can be obtained by calling one of the following methods:
IEnumCERTVIEWCOLUMN::GetName: Retrieves the nonlocalized name of the column.
IEnumCERTVIEWCOLUMN::GetDisplayName: Retrieves the localized name of the column.
IEnumCERTVIEWCOLUMN::GetValue: Retrieves the data in the column.
IEnumCERTVIEWCOLUMN::GetType: Retrieves the type of data in the column.
IEnumCERTVIEWCOLUMN::GetMaxLength: Retrieves the maximum length, in bytes, of the column.
The column-enumeration sequence maintains an internal zero-based index. The call to the Skip method causes this
index to increase or decrease based on the setting of the celt parameter.
If a negative value of the celt parameter causes the index to be less than zero, the behavior of subsequent calls
to Next is undefined.
If a positive value of the celt parameter causes the index to exceed the last row in the enumeration sequence, a
subsequent call to the Next method will fail.
Examples

HRESULT hr;
LONG Index;

// pEnumCol is previously instantiated IEnumCERTVIEWCOLUMN object

// skip the next five columns
hr = pEnumCol->Skip(5);
if (S_OK == hr)
{
// get the next column
hr = pEnumCol->Next(&Index);
if (S_OK == hr)
{
// Use this column as needed.
}
}

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header certview.h (include Certsrv.h)

Librar y Certidl.lib

DLL Certadm.dll

See also
IEnumCERTVIEWCOLUMN
IEnumCERTVIEWCOLUMN::Reset
IEnumCERTVIEWCOLUMN:Next
 IEnumCERTVIEWEXTENSION interface (certview.h)
7/2/2022 • 2 minutes to read • Edit Online

The IEnumCERTVIEWEXTENSION interface represents an extension-enumeration sequence that contains the

certificate extension data for the current row of the row-enumeration sequence.
The extension-enumeration sequence is obtained by a call to the
IEnumCERTVIEWROW::EnumCertViewExtension method. After this enumeration sequence is obtained, the
methods of the IEnumCERTVIEWEXTENSION interface can be used to perform the following tasks:
Navigate the extension-enumeration sequence.
Retrieve the name, value, and flags of the extension in the enumeration.
Clone an exact copy of the extension-enumeration sequence.
IEnumCERTVIEWEXTENSION is defined in Certview.h. When you create your program, however, use Certsrv.h
as the include file. Certadm.dll provides the IEnumCERTVIEWEXTENSION interface. The type information for
this interface is also in Certadml.dll, which is shipped with the Platform Software Development Kit (SDK).
Certificate Services interfaces support both apartment-threading and free-threading models. For better
throughput, free threading is recommended.

Inheritance
The IEnumCERTVIEWEXTENSION interface inherits from the IDispatch interface.
IEnumCERTVIEWEXTENSION also has these types of members:

Methods
The IEnumCERTVIEWEXTENSION interface has these methods.

IEnumCERTVIEWEXTENSION::Clone

Creates a copy of the extension-enumeration sequence.

IEnumCERTVIEWEXTENSION::GetFlags

Retrieves the policy and origin flags of the current extension in the extension-enumeration sequence.

IEnumCERTVIEWEXTENSION::GetName

Retrieves the name of the current extension in the extension-enumeration sequence.

IEnumCERTVIEWEXTENSION::GetValue

Retrieves the value of the current extension in the extension-enumeration sequence.

IEnumCERTVIEWEXTENSION::Next

Moves to the next extension in the extension-enumeration sequence.

 IEnumCERTVIEWEXTENSION::Reset

Moves to the beginning of the extension-enumeration sequence.

IEnumCERTVIEWEXTENSION::Skip

Skips a specified number of extensions in the extension-enumeration sequence.

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header certview.h (include Certsrv.h)

See also
IDispatch
IEnumCERTVIEWROW::IEnumCertViewExtension
 IEnumCERTVIEWEXTENSION::Clone method
(certview.h)
7/2/2022 • 2 minutes to read • Edit Online

The Clone method creates a copy of the extension-enumeration sequence.

Syntax
HRESULT Clone(
[out] IEnumCERTVIEWEXTENSION **ppenum
);

Parameters
[out] ppenum

A pointer to a pointer of IEnumCERTVIEWEXTENSION type. This method will fail if the ppenum parameter is
NULL .

Return value
C++
If the method succeeds, the method returns S_OK.
If the method fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.
VB
The return value is a cloned extension-enumeration sequence object.

Remarks
The extension-enumeration sequence object is obtained by a call to the
IEnumCERTVIEWROW::EnumCertViewExtension method.
Examples

IEnumCERTVIEWEXTENSION * pEnumExt2 = NULL;

HRESULT hr;

// pEnumExt is previously instantiated IEnumCERTVIEWEXTENSION object

hr = pEnumExt->Clone(&pEnumExt2);
if (S_OK != hr)
printf("Unable to clone IEnumCERTVIEWEXTENSION\n");
else
{
// use cloned object as needed
//...
}
// done using cloned object, free memory
if (NULL != pEnumExt2)
pEnumExt2->Release();
Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header certview.h (include Certsrv.h)

Librar y Certidl.lib

DLL Certadm.dll

See also
IEnumCERTVIEWEXTENSION
 IEnumCERTVIEWEXTENSION::GetFlags method
(certview.h)
7/2/2022 • 2 minutes to read • Edit Online

The GetFlags method retrieves the policy and origin flags of the current extension in the extension-
enumeration sequence.
Both the policy and origin flags are returned in one variable, and bitmasks are provided to retrieve the individual
values.

Syntax
HRESULT GetFlags(
[out] LONG *pFlags
);

Parameters
[out] pFlags

A pointer to a LONG type that contains the policy and origin flags of the extension. This method fails if the
pFlags parameter is set to NULL .

Return value
C++
If the method succeeds, the method returns S_OK.
If the method fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.
VB
The return value represents the policy and origin values of the extension.

Remarks
This method is used to retrieve the policy and origin flags of the extension currently referenced by the
extension-enumeration sequence.
Policy flags provide information about the certificate extension and can be set by the policy module.
Origin flags indicate the module that set the certificate extension and are set only by the server engine.
One or more policy flags can be returned from an extension. The following are predefined policy flags.

P O L IC Y F L A G VA L UE EXP L A N AT IO N

EXTENSION_CRITICAL_FLAG This is a critical extension.

EXTENSION_DISABLE_FLAG Extension will not be used.

One of the following origin flags can also be returned.

O RIGIN F L A G VA L UE EXP L A N AT IO N

EXTENSION_ORIGIN_REQUEST The extension was extracted from an array of extensions

stored in the szOID_CERT_EXTENSIONS
(1.3.6.1.4.1.311.2.1.14) or szOID_RSA_certExtensions
(1.2.840.113549.1.9.14) attribute of a PKCS #10 request.

EXTENSION_ORIGIN_POLICY The policy module set the extension.

EXTENSION_ORIGIN_ADMIN The administrator set the extension.

EXTENSION_ORIGIN_SERVER The server engine set the extension.

EXTENSION_ORIGIN_RENEWALCERT The extension was extracted from the certificate stored in

the szOID_RENEWAL_CERTIFICATE (1.3.6.1.4.1.311.13.1)
attribute of a PKCS #10 renewal request.

EXTENSION_ORIGIN_IMPORTEDCERT The extension was extracted from an imported certificate

(the certificate was passed to ICertAdmin::ImportCertificate).

EXTENSION_ORIGIN_PKCS7 The extension was extracted from an array of extensions

stored in the szOID_CERT_EXTENSIONS
(1.3.6.1.4.1.311.2.1.14) or szOID_RSA_certExtensions
(1.2.840.113549.1.9.14) attribute of a PKCS #7 request.

Predefined masks are provided for ease of use in determining which flags are set in the return value. The
following masks are provided.

M A SK VA L UE EXP L A N AT IO N

EXTENSION_POLICY_MASK This value (0x0000FFFF) is used to examine policy flags.

EXTENSION_ORIGIN_MASK This value (0x000F0000) is used to examine origin flags.

If the extension-enumeration sequence is not referencing a valid extension, GetFlags will fail. Use one of the
following methods to navigate through the enumeration:
IEnumCERTVIEWEXTENSION::Reset: Moves to the next extension in the enumeration sequence.
IEnumCERTVIEWEXTENSION::Next: Moves to the next extension in the enumeration sequence.
IEnumCERTVIEWEXTENSION::Skip: Skips a specified number of extensions.
Examples
 HRESULT hr;
LONG ExtFlags;

// pEnumExt is previously instantiated IEnumCERTVIEWEXTENSION object

hr = pEnumExt->GetFlags(&ExtFlags);
if (S_OK != hr)
printf("Failed GetFlags - %x\n", hr);
else
{
LONG ExtPol, ExtOrig;

ExtPol = ExtFlags & EXTENSION_POLICY_MASK;

if (ExtPol & EXTENSION_CRITICAL_FLAG)
printf("The extension is critical\n");
if (ExtPol & EXTENSION_DISABLE_FLAG )
printf("The extension is disabled\n");

ExtOrig = ExtFlags & EXTENSION_ORIGIN_MASK;

switch (ExtOrig)
{
case EXTENSION_ORIGIN_REQUEST:
printf("Extension originated by PKCS #10 Request\n");
break;
case EXTENSION_ORIGIN_POLICY:
printf("Extension originated by Policy\n");
break;
case EXTENSION_ORIGIN_ADMIN:
printf("Extension originated by Admin\n");
break;
case EXTENSION_ORIGIN_SERVER:
printf("Extension originated by Server\n");
break;
case EXTENSION_ORIGIN_RENEWALCERT:
printf("Extension originated by Renewal Request\n");
break;
case EXTENSION_ORIGIN_IMPORTEDCERT:
printf("Extension originated by an imported "
"certificate\n");
break;
case EXTENSION_ORIGIN_PKCS7:
printf("Extension originated by PKCS #7 Request\n");
break;
default:
printf("Unknown extension origin\n");
break;
}
}

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header certview.h (include Certsrv.h)

Librar y Certidl.lib
 DLL Certadm.dll

See also
IEnumCERTVIEWEXTENSION
IEnumCERTVIEWEXTENSION::GetName
IEnumCERTVIEWEXTENSION::GetValue
IEnumCERTVIEWEXTENSION::Next
 IEnumCERTVIEWEXTENSION::GetName method
(certview.h)
7/2/2022 • 2 minutes to read • Edit Online

The GetName method retrieves the name of the current extension in the extension-enumeration sequence.
The returned extension name is an object identifier (OID) string, as in L"2.5.29.31".

Syntax
HRESULT GetName(
[out] BSTR *pstrOut
);

Parameters
[out] pstrOut

A pointer to a value of BSTR type that contains the name of the extension.

Return value
C++
If the method succeeds, the method returns S_OK and tat the pstrOut parameter is set to the name of the extension.
To use this method, create a variable of BSTR type, set the variable equal to NULL , and pass the address of this
variable as pstrOut. When you have finished using the BSTR , free it by calling the SysFreeString function.
If the method fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.
VB
The return value is a String that contains the name of the extension.

Remarks
This function is used to retrieve the name of the extension currently referenced by the extension-enumeration
sequence.
If the extension-enumeration sequence is not referencing a valid extension, GetName will fail. Use one of the
following methods to navigate through the enumeration:
IEnumCERTVIEWEXTENSION::Reset: Moves to the next extension in the enumeration sequence.
IEnumCERTVIEWEXTENSION::Next: Moves to the next extension in the enumeration sequence.
IEnumCERTVIEWEXTENSION::Skip: Skips a specified number of extensions.
Examples
 BSTR bstrExtName = NULL;

// pEnumExt is previously instantiated IEnumCERTVIEWEXTENSION object

hr = pEnumExt->GetName(&bstrExtName);
if (S_OK == hr)
printf("Extension name is: %ws\n", bstrExtName);
else
printf("GetName failed: %x\n", hr);

// free memory when done

if (NULL != bstrExtName)
SysFreeString(bstrExtName);

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header certview.h (include Certsrv.h)

Librar y Certidl.lib

DLL Certadm.dll

See also
IEnumCERTVIEWEXTENSION
IEnumCERTVIEWEXTENSION::GetFlags
IEnumCERTVIEWEXTENSION::GetValue
IEnumCERTVIEWEXTENSION::Next
IEnumCERTVIEWEXTENSION::Reset
IEnumCERTVIEWEXTENSION::Skip
 IEnumCERTVIEWEXTENSION::GetValue method
(certview.h)
7/2/2022 • 2 minutes to read • Edit Online

The GetValue method retrieves the value of the current extension in the extension-enumeration sequence.

Syntax
HRESULT GetValue(
[in] LONG Type,
[in] LONG Flags,
[out] VARIANT *pvarValue
);

Parameters
[in] Type

Data type for the returned data. This parameter can be used to specify that the extension data be decoded before
being returned. If PROPTYPE_BINARY is specified, the data is not decoded but instead returned in its raw format.
Specify one of the following values.

VA L UE M EA N IN G

The extension value is retrieved as is and is ASN.1 encoded if

PROPTYPE_BINARY necessary.

Extension value is returned as a date/time.

PROPTYPE_DATE

Extension value is returned as a signed long.

PROPTYPE_LONG

The extension value is ASN.1 encoded as an IA5 string.

PROPTYPE_STRING

[in] Flags

Flag that denotes the output format for the returned data. This parameter can be one of the following values.

VA L UE M EA N IN G

BASE64 without BEGIN/END

CV_OUT_BASE64

BASE64 with BEGIN CERTIFICATE and END CERTIFICATE

CV_OUT_BASE64HEADER
 BASE64 with BEGIN NEW CERTIFICATE REQUEST and END
CV_OUT_BASE64REQUESTHEADER NEW CERTIFICATE REQUEST

Binary
CV_OUT_BINARY

Hexadecimal string
CV_OUT_HEX

Hexadecimal string with address/offset

CV_OUT_HEXADDR

Hexadecimal string with ASCII

CV_OUT_HEXASCII

Hexadecimal string with ASCII and address/offset

CV_OUT_HEXASCIIADDR

[out] pvarValue

A pointer to a value of VARIANT type that contains the data for the currently referenced extension. This method
fails if the pvarValue parameter is NULL . Upon successful completion of this function, pvarValue contains the
extension data currently referenced by the extension-enumeration sequence. The caller is responsible for calling
VariantClear when done with the data in pvarValue.

Return value
C++
If the method succeeds, the method returns S_OK.
If the method fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.
VB
The return value is a Variant that represents the data in the extension.

Remarks
This method is used to retrieve the data in the extension currently being referenced by the extension-
enumeration sequence.
If the extension-enumeration sequence is not referencing a valid extension, GetValue fails. Use one of the
following methods to navigate through the enumeration:
IEnumCERTVIEWEXTENSION::Reset: Moves to the next extension in the enumeration sequence.
IEnumCERTVIEWEXTENSION::Next: Moves to the next extension in the enumeration sequence.
IEnumCERTVIEWEXTENSION::Skip: Skips a specified number of extensions.
This method fails if the extension-enumeration sequence was obtained by a call to the
ICertView::EnumCertViewColumn method because enumeration sequences obtained by that method contain only
schema information.
Examples
 VARIANT var;
LONG Index;
HRESULT hr;
SYSTEMTIME systime;

VariantInit(&var);

// Enumerate each extension

// pEnumExt is previously instantiated IEnumCERTVIEWEXTENSION object
while (S_OK == pEnumExt->Next(&Index))
{
hr = pEnumExt->GetValue(PROPTYPE_BINARY, CV_OUT_HEX, &var);
if (FAILED(hr))
{
printf("Failed GetValue - %x\n", hr);
break;
}
switch(var.vt)
{
case VT_EMPTY:
printf("VT_EMPTY\n");
break;
case VT_BSTR:
printf("BSTR:%ws\n", var.bstrVal);
break;
case VT_DATE:
VariantTimeToSystemTime(var.date, &systime);
printf("%d.%d.%d %02d:%02d:%02d\n",
systime.wMonth,
systime.wDay,
systime.wYear,
systime.wHour,
systime.wMinute,
systime.wSecond );
break;
case VT_I2:
printf("%d\n", var.iVal);
break;
case VT_I4:
printf("%d\n", var.lVal);
break;
default:
printf("type is:%i\n", var.vt);
break;
}
}
// Free resources.
VariantClear( &var );

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header certview.h (include Certsrv.h)

 Librar y Certidl.lib

DLL Certadm.dll

See also
ICertView::EnumCertViewColumn
IEnumCERTVIEWEXTENSION
IEnumCERTVIEWEXTENSION::Next
IEnumCERTVIEWEXTENSION::Reset
IEnumCERTVIEWEXTENSION::Skip
 IEnumCERTVIEWEXTENSION::Next method
(certview.h)
7/2/2022 • 2 minutes to read • Edit Online

The Next method moves to the next extension in the extension-enumeration sequence.

Syntax
HRESULT Next(
[out] LONG *pIndex
);

Parameters
[out] pIndex

A pointer to a variable that contains the index value of the next extension being referenced. If there are no more
extensions to enumerate, this variable will be set to –1. This method fails if pIndex is NULL .

Return value
C++
If the method succeeds, the method returns S_OK and the next extension is now being referenced. If there are no
more extensions, S_FALSE is returned, and the pIndex parameter is set to a value of –1.
If the method fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.
VB
The return value is the index value of the extension that is now referenced by the extension-enumeration sequence.
If there are no more extensions to enumerate, the return value is –1.

Remarks
Upon successful completion of this method, the extension name, flags, and value can be accessed through the
following methods:
IEnumCERTVIEWEXTENSION::GetName
IEnumCERTVIEWEXTENSION::GetFlags
IEnumCERTVIEWEXTENSION::GetValue
Examples
 LONG Index;
LONG nCount;

// determine the number of extensions

nCount = 0;
// pEnumExt is previously instantiated IEnumCERTVIEWEXTENSION object
while (S_OK == pEnumExt->Next(&Index))
{
nCount++;
}
printf("Number of extensions is %d\n", nCount);

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header certview.h (include Certsrv.h)

Librar y Certidl.lib

DLL Certadm.dll

See also
IEnumCERTVIEWEXTENSION
IEnumCERTVIEWEXTENSION::GetFlags
IEnumCERTVIEWEXTENSION::GetName
IEnumCERTVIEWEXTENSION::GetValue
 IEnumCERTVIEWEXTENSION::Reset method
(certview.h)
7/2/2022 • 2 minutes to read • Edit Online

The Reset method moves to the beginning of the extension-enumeration sequence.

Syntax
HRESULT Reset();

Return value
VB
If the method succeeds, the method returns S_OK.
If the method fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.

Remarks
Upon successful completion of this method, call the IEnumCERTVIEWEXTENSION::Next method to reference the
first extension in the extension-enumeration sequence.
The extension name, flags, and value can be accessed through the following methods:
IEnumCERTVIEWEXTENSION::GetName
IEnumCERTVIEWEXTENSION::GetFlags
IEnumCERTVIEWEXTENSION::GetValue
Examples

HRESULT hr;
LONG Index;

// pEnumExt is previously instantiated IEnumCERTVIEWEXTENSION object

hr = pEnumExt->Reset();
if (S_OK != hr)
printf("Unable to reset pEnumExt - %x\n", hr);
// call appropriate error handler / exit routine
else
{
// reset to beginning of extensions again
while (S_OK == pEnumExt->Next(&Index))
{
// Use each extension as needed.
}
}

Requirements
 Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header certview.h (include Certsrv.h)

Librar y Certidl.lib

DLL Certadm.dll

See also
IEnumCERTVIEWEXTENSION
IEnumCERTVIEWEXTENSION::GetFlags
IEnumCERTVIEWEXTENSION::GetName
IEnumCERTVIEWEXTENSION::GetValue
IEnumCERTVIEWEXTENSION::Next
 IEnumCERTVIEWEXTENSION::Skip method
(certview.h)
7/2/2022 • 2 minutes to read • Edit Online

The Skip method skips a specified number of extensions in the extension-enumeration sequence.

Syntax
HRESULT Skip(
[in] LONG celt
);

Parameters
[in] celt

The number of extensions to skip. A positive value for the celt parameter causes the extension-enumeration
sequence to skip forward in the sequence. A negative value for the celt parameter causes the extension-
enumeration sequence to skip backward in the sequence.

Return value
VB
If the method succeeds, the method returns S_OK.
A return value of E_INVALIDARG indicates that a negative value for the celt parameter caused the extension-
enumeration sequence index to become less than zero.
If the method fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.

Remarks
Upon successful completion of this method, call the IEnumCERTVIEWEXTENSION::Next method to reference the
current extension in the extension-enumeration sequence. The extension name, flags, and value can be accessed
through the following methods:
IEnumCERTVIEWEXTENSION::GetName
IEnumCERTVIEWEXTENSION::GetFlags
IEnumCERTVIEWEXTENSION::GetValue
The extension-enumeration sequence maintains an internal zero-based index. The call to the Skip method causes
this index to increase or decrease by the number of extensions specified in the celt parameter.
If a negative value of the celt parameter causes the index to be less than zero, the behavior of subsequent calls
to IEnumCERTVIEWEXTENSION::Next is undefined.
If a positive value of the celt parameter causes the index to exceed the last extension in the enumeration
sequence, a subsequent call to the IEnumCERTVIEWEXTENSION::Next method will fail.
Examples
 HRESULT hr;
LONG Index;

// pEnumExt is previously instantiated IEnumCERTVIEWEXTENSION object

// skip the next 5 extensions
hr = pEnumExt->Skip(5);
if (S_OK == hr)
{
// get the next extension
hr = pEnumExt->Next(&Index);
if (S_OK == hr)
{
// Use this extension as needed.
}
}

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header certview.h (include Certsrv.h)

Librar y Certidl.lib

DLL Certadm.dll

See also
IEnumCERTVIEWEXTENSION
IEnumCERTVIEWEXTENSION::GetFlags
IEnumCERTVIEWEXTENSION::GetName
IEnumCERTVIEWEXTENSION::GetValue
IEnumCERTVIEWEXTENSION::Next
 IEnumCERTVIEWROW interface (certview.h)
7/2/2022 • 2 minutes to read • Edit Online

The IEnumCERTVIEWROW interface represents a row-enumeration sequence that contains the data in the
rows of the Certificate Services view, allowing further access to the columns, attributes, and extensions
associated with each row.
The row-enumeration sequence is obtained through a call to the ICertView::OpenView method. After this
enumeration sequence is obtained, the IEnumCERTVIEWROW methods can be used to perform the following
tasks:
Navigate through the enumeration sequence.
Obtain other objects for enumerating the columns, certificate extensions, or attributes associated with a
specific row.
Retrieve the maximum number of rows for the view.
IEnumCERTVIEWROW is defined in Certview.h. When you create your program, however, use Certsrv.h as the
include file. Certadm.dll provides the IEnumCERTVIEWROW interface. The type information for this interface is
also in Certadml.dll, which is shipped with the Platform Software Development Kit (SDK).
Certificate Services interfaces support both apartment-threading and free-threading models. For better
throughput, free threading is recommended.

Inheritance
The IEnumCERTVIEWROW interface inherits from the IDispatch interface. IEnumCERTVIEWROW also has
these types of members:

Methods
The IEnumCERTVIEWROW interface has these methods.

IEnumCERTVIEWROW::EnumCertViewAttribute

Obtains an instance of an attribute-enumeration sequence for the current row of the row-enumeration sequence.

IEnumCERTVIEWROW::EnumCertViewColumn

Obtains an instance of a column-enumeration sequence for the current row of the row-enumeration sequence.

IEnumCERTVIEWROW::EnumCertViewExtension

Obtains an instance of an extension-enumeration sequence for the current row of the row-enumeration sequence.

IEnumCERTVIEWROW::GetMaxIndex

Retrieves the maximum valid index value after all the rows in the row-enumeration sequence have been referenced.
 IEnumCERTVIEWROW::Next

Moves to the next row in the row-enumeration sequence.

IEnumCERTVIEWROW::Reset

Moves to the beginning of the row-enumeration sequence.

IEnumCERTVIEWROW::Skip

Skips a specified number of rows in the row enumeration sequence.

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header certview.h (include Certsrv.h)

See also
ICertView
IDispatch
 IEnumCERTVIEWROW::EnumCertViewAttribute
method (certview.h)
7/2/2022 • 2 minutes to read • Edit Online

The EnumCer tViewAttribute method obtains an instance of an attribute-enumeration sequence for the
current row of the row-enumeration sequence.

Syntax
HRESULT EnumCertViewAttribute(
[in] LONG Flags,
[out] IEnumCERTVIEWATTRIBUTE **ppenum
);

Parameters
[in] Flags

C++ A LONG value. Must be zero.

VB A Long value. Must be zero.

[out] ppenum

A pointer to a pointer of IEnumCERTVIEWATTRIBUTE type. Upon successful completion of this method, ppenum
is set to a pointer of IEnumCERTVIEWATTRIBUTE type.

Return value
C++
If the method succeeds, the method returns S_OK.
If the method fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.
VB
The returned value is an attribute-enumeration sequence object.

Remarks
The attribute-enumeration sequence obtained by this call can be used to enumerate the attributes associated
with the certificate in the current row. This enumeration can be accessed through the methods of the
IEnumCERTVIEWATTRIBUTE interface.
To reference a different row, call one of the following methods to navigate through the row-enumeration
sequence:
IEnumCERTVIEWROW::Reset: Moves to the beginning of the enumeration sequence.
IEnumCERTVIEWROW::Next: Moves to the next row in the enumeration sequence.
IEnumCERTVIEWROW::Skip: Skips a specified number of rows.
Examples

// pEnumRow is previously instantiated pointer to IEnumCERTVIEWROW

HRESULT hr;
LONG Index;
IEnumCERTVIEWATTRIBUTE * pEnumAttr = NULL;

// obtain enumerator for attributes

hr = pEnumRow->EnumCertViewAttribute(0, &pEnumAttr);
if (FAILED(hr))
{
printf("Failed EnumCertViewAttribute - %x\n", hr);
goto error;
}
// enumerate each attribute
while (S_OK == pEnumAttr->Next(&Index))
{
// Use this attribute as needed.
}
error:

// Free resources.
if (NULL != pEnumAttr)
pEnumAttr->Release();

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header certview.h (include Certsrv.h)

Librar y Certidl.lib

DLL Certadm.dll

See also
IEnumCERTVIEWATTRIBUTE
IEnumCERTVIEWROW
IEnumCERTVIEWROW::Next
IEnumCERTVIEWROW::Reset
IEnumCERTVIEWROW::Skip
 IEnumCERTVIEWROW::EnumCertViewColumn
method (certview.h)
7/2/2022 • 2 minutes to read • Edit Online

The EnumCer tViewColumn method obtains an instance of a column-enumeration sequence for the current
row of the row-enumeration sequence.

Syntax
HRESULT EnumCertViewColumn(
[out] IEnumCERTVIEWCOLUMN **ppenum
);

Parameters
[out] ppenum

A pointer to a pointer of IEnumCERTVIEWCOLUMN type.

Return value
C++
If the method succeeds, the method returns S_OK.
If the method fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.
VB
The return value is a column-enumeration sequence object.

Remarks
The column-enumeration sequence obtained by this call can be used to enumerate the columns associated with
the certificate in the current row. This enumeration can be accessed through the methods of the
IEnumCERTVIEWCOLUMN interface.
To reference a different row, call one of the following methods to navigate through the row-enumeration
sequence:
IEnumCERTVIEWROW::Reset: Moves to the beginning of the enumeration sequence.
IEnumCERTVIEWROW::Next: Moves to the next row in the enumeration sequence.
IEnumCERTVIEWROW::Skip: Skips a specified number of rows.
Examples
 // pEnumRow is previously instantiated pointer to IEnumCERTVIEWROW
HRESULT hr;
LONG Index;
IEnumCERTVIEWCOLUMN * pEnumCol = NULL;
// obtain enumerator for columns
hr = pEnumRow->EnumCertViewColumn(&pEnumCol);
if ( FAILED( hr ))
{
printf("Failed EnumCertViewColumn - %x\n", hr );
goto error;
}
// enumerate each column
while (S_OK == pEnumCol->Next(&Index))
{
// Use this column as needed.
}
error:

// Free resources.
if ( NULL != pEnumCol )
pEnumCol->Release();

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header certview.h (include Certsrv.h)

Librar y Certidl.lib

DLL Certadm.dll

See also
IEnumCERTVIEWCOLUMN
IEnumCERTVIEWROW
IEnumCERTVIEWROW::Next
IEnumCERTVIEWROW::Reset
IEnumCERTVIEWROW::Skip
 IEnumCERTVIEWROW::EnumCertViewExtension
method (certview.h)
7/2/2022 • 2 minutes to read • Edit Online

The EnumCer tViewExtension method obtains an instance of an extension-enumeration sequence for the
current row of the row-enumeration sequence.

Syntax
HRESULT EnumCertViewExtension(
[in] LONG Flags,
[out, retval] IEnumCERTVIEWEXTENSION **ppenum
);

Parameters
[in] Flags

C++ A LONG value. Must be zero.

VB A Long value. Must be zero.

[out, retval] ppenum

A pointer to a pointer of IEnumCERTVIEWEXTENSION type.

Return value
C++
If the method succeeds, the method returns S_OK.
If the method fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.
VB
The return value is an extension-enumeration sequence object.

Remarks
The extension-enumeration sequence obtained by this call can be used to enumerate the extensions associated
with the certificate in the current row. This enumeration can be accessed through the methods of the
IEnumCERTVIEWEXTENSION interface.
To reference a different row, call one of the following methods to navigate through the row-enumeration
sequence:
IEnumCERTVIEWROW::Reset: Moves to the beginning of the enumeration sequence.
IEnumCERTVIEWROW::Next: Moves to the next row in the enumeration sequence.
IEnumCERTVIEWROW::Skip: Skips a specified number of rows.
Examples

// pEnumRow is previously instantiated pointer to IEnumCERTVIEWROW.

LONG Index;
HRESULT hr;
IEnumCERTVIEWEXTENSION * pEnumExt = NULL;
// Obtain enumerator for extensions.
hr = pEnumRow->EnumCertViewExtension(0, &pEnumExt);
if (FAILED(hr))
{
printf("Failed EnumCertViewExtension - %x\n", hr);
goto error;
}
// Enumerate each extension.
while (S_OK == pEnumExt->Next(&Index))
{
// Use this extension as needed.
}
error:

// Free resources.
if (NULL != pEnumExt)
pEnumExt->Release();

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header certview.h (include Certsrv.h)

Librar y Certidl.lib

DLL Certadm.dll

See also
IEnumCERTVIEWEXTENSION
IEnumCERTVIEWROW
IEnumCERTVIEWROW::Next
IEnumCERTVIEWROW::Reset
IEnumCERTVIEWROW::Skip
 IEnumCERTVIEWROW::Next method (certview.h)
7/2/2022 • 2 minutes to read • Edit Online

The Next method moves to the next row in the row-enumeration sequence.

Syntax
HRESULT Next(
[out] LONG *pIndex
);

Parameters
[out] pIndex

A pointer to a variable that contains the index value of the next row being referenced. If there are no more rows
to enumerate, this variable will be set to –1. This method fails if pIndex is NULL .

Return value
C++
If the method succeeds, the method returns S_OK and the next row is now being referenced by the row-
enumeration sequence. If there are no more rows to enumerate, S_FALSE is returned, and pIndex is set to a value of
–1.
If the method fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.
VB
The return value is the index value of the row that is now being referenced by the row-enumeration sequence. If
there are no more rows to enumerate, the return value is –1.

Remarks
Upon successful completion of this method, the columns, attributes, and extensions associated with the
certificate in the row can be enumerated using the methods of the following interfaces:
IEnumCERTVIEWCOLUMN
IEnumCERTVIEWATTRIBUTE
IEnumCERTVIEWEXTENSION
Looping through all the rows in the enumeration sequence can be resource-intensive to compute, depending of the
query involved and the size of the sequence.
Examples
 // pEnumRow is previously instantiated pointer to IEnumCERTVIEWROW.
LONG Index;
LONG nCount;

// Ensure enumerator is at first row.

if (FAILED(pEnumRow->Reset()))
printf("Failed to Reset\n");
else
{
nCount = 0;
// Count the database records by enumerating the rows.
while (S_OK == pEnumRow->Next(&Index))
nCount++;
// Display number of records.
printf("Number of records is %d\n", nCount);
}

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header certview.h (include Certsrv.h)

Librar y Certidl.lib

DLL Certadm.dll

See also
IEnumCERTVIEWATTRIBUTE
IEnumCERTVIEWCOLUMN
IEnumCERTVIEWEXTENSION
IEnumCERTVIEWROW
 IEnumCERTVIEWROW::Reset method (certview.h)
7/2/2022 • 2 minutes to read • Edit Online

The Reset method moves to the beginning of the row-enumeration sequence.

Syntax
HRESULT Reset();

Return value
VB
If the method succeeds, the method returns S_OK.
If the method fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.

Remarks
Upon successful completion of this method, call the IEnumCERTVIEWROW::Next method to reference the first
row in the enumeration.
After this second call is made, the columns, attributes, and extensions associated with the certificate in the row
can be enumerated using the methods of the following interfaces:
IEnumCERTVIEWCOLUMN
IEnumCERTVIEWATTRIBUTE
IEnumCERTVIEWEXTENSION
Examples

// pEnumRow is previously instantiated pointer to IEnumCERTVIEWROW.

HRESULT hr;
LONG Index;

// Ensure enumerator is at first row.

hr = pEnumRow->Reset();
if (FAILED(hr))
printf("Failed to Reset\n");
else
{
printf("Reset to beginning\n");
// Retrieve first record.
hr = pEnumRow->Next(&Index);
// Examine hr for success and process row.
// ...
}

Requirements
 Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header certview.h (include Certsrv.h)

Librar y Certidl.lib

DLL Certadm.dll

See also
IEnumCERTVIEWATTRIBUTE
IEnumCERTVIEWCOLUMN
IEnumCERTVIEWEXTENSION
IEnumCERTVIEWROW
 IEnumCERTVIEWROW::Skip method (certview.h)
7/2/2022 • 2 minutes to read • Edit Online

The Skip method skips a specified number of rows in the row enumeration sequence.

Syntax
HRESULT Skip(
[in] LONG celt
);

Parameters
[in] celt

The number of rows to skip. A positive value for the celt parameter causes the row-enumeration sequence to
skip forward in the enumeration sequence. A negative value for the celt parameter causes the row enumeration
sequence to skip backward in the enumeration sequence.

Return value
VB
If the method succeeds, the method returns S_OK.
A return value of E_INVALIDARG indicates that the celt parameter was set to a negative number which caused
the row-enumeration sequence index to become less than zero.
If the method fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.

Remarks
Upon successful completion of this method, call the IEnumCERTVIEWROW::Skip method to reference the
current row in the row-enumeration sequence. After this second call is made, the columns, attributes, and
extensions associated with the certificate in the row can be enumerated using the methods of the following
interfaces:
IEnumCERTVIEWCOLUMN
IEnumCERTVIEWATTRIBUTE
IEnumCERTVIEWEXTENSION
The row-enumeration sequence maintains an internal zero-based index. The call to the Skip method causes this
index to increase or decrease based on the setting of the celt parameter.
If a negative value of the celt parameter causes the index to be less than zero, the behavior of subsequent calls
to Next is undefined.
If a positive value of the celt parameter causes the index to exceed the last row in the enumeration sequence, a
subsequent call to the Next method will fail.
Examples
 // pEnumRow is previously instantiated pointer to IEnumCERTVIEWROW.
HRESULT hr;
LONG Index;
// Reposition the row enumerator to the beginning of the rows.
hr = pEnumRow->Reset();
if (FAILED(hr))
{
printf("Unable to reset pEnumRow\n");
goto error;
}
// Skip some rows.
hr = pEnumRow->Skip(5);
if (FAILED(hr))
{
printf("Unable to skip rows\n");
goto error;
}

// Get the next row.

hr = pEnumRow->Next(&Index);
if (S_OK == hr)
{
// Use this row as needed.
}

error:

if (NULL != pEnumRow)
pEnumRow->Release();

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header certview.h (include Certsrv.h)

Librar y Certidl.lib

DLL Certadm.dll

See also
IEnumCERTVIEWATTRIBUTE
IEnumCERTVIEWCOLUMN
IEnumCERTVIEWEXTENSION
IEnumCERTVIEWROW
IEnumCERTVIEWROW::Next
IEnumCERTVIEWROW::Reset
 credssp.h header
7/2/2022 • 2 minutes to read • Edit Online

This header is used by Security and Identity. For more information, see:
Security and Identity
credssp.h contains the following programming interfaces:

Structures

CREDSSP_CRED

Specifies authentication data for both Schannel and Negotiate security packages.

SecPkgContext_ClientCreds

Specifies client credentials when calling the QueryContextAttributes (CredSSP) function.

Enumerations

CREDSPP_SUBMIT_TYPE

Specifies the type of credentials specified by a CREDSSP_CRED structure.

 CREDSPP_SUBMIT_TYPE enumeration (credssp.h)
7/2/2022 • 2 minutes to read • Edit Online

The CREDSPP_SUBMIT_TYPE enumeration specifies the type of credentials specified by a CREDSSP_CRED

structure.

Syntax
typedef enum _CREDSSP_SUBMIT_TYPE {
CredsspPasswordCreds = 2,
CredsspSchannelCreds = 4,
CredsspCertificateCreds = 13,
CredsspSubmitBufferBoth = 50,
CredsspSubmitBufferBothOld = 51,
CredsspCredEx = 100
} CREDSPP_SUBMIT_TYPE;

Constants

CredsspPasswordCreds
Value: 2
The credentials are a user name and password.

CredsspSchannelCreds
Value: 4
The credentials are Schannel credentials.

CredsspCertificateCreds
Value: 13
The credentials are in a certificate.

CredsspSubmitBufferBoth
Value: 50
The credentials contain both certificate and Schannel credentials.

CredsspSubmitBufferBothOld
Value: 51

CredsspCredEx
Value: 100

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]
 Header credssp.h

See also
CREDSSP_CRED
 CREDSSP_CRED structure (credssp.h)
7/2/2022 • 2 minutes to read • Edit Online

The CREDSSP_CRED structure specifies authentication data for both Schannel and Negotiate security
packages.

Syntax
typedef struct _CREDSSP_CRED {
CREDSPP_SUBMIT_TYPE Type;
PVOID pSchannelCred;
PVOID pSpnegoCred;
} CREDSSP_CRED, *PCREDSSP_CRED;

Members
Type

The CREDSPP_SUBMIT_TYPE enumeration value that specifies the type of credentials contained in this structure.
pSchannelCred

A pointer to a set of Schannel credentials.

pSpnegoCred

A pointer to a set of Negotiate credentials.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Header credssp.h

See also
AcquireCredentialsHandle (CredSSP)
CREDSPP_SUBMIT_TYPE
 SecPkgContext_ClientCreds structure (credssp.h)
7/2/2022 • 2 minutes to read • Edit Online

The SecPkgContext_ClientCreds structure specifies client credentials when calling the

QueryContextAttributes (CredSSP) function.
This structure is supported only on the server.

Syntax
typedef struct _SecPkgContext_ClientCreds {
ULONG AuthBufferLen;
PUCHAR AuthBuffer;
} SecPkgContext_ClientCreds, *PSecPkgContext_ClientCreds;

Members
AuthBufferLen

The size, in characters, of the AuthBuffer buffer.

AuthBuffer

A pointer to a buffer that represents the client credentials.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Header credssp.h

See also
QueryContextAttributes (CredSSP)
 cryptdlg.h header
7/2/2022 • 2 minutes to read • Edit Online

This header is used by Security and Identity. For more information, see:
Security and Identity
cryptdlg.h contains the following programming interfaces:

Functions

CertModifyCertificatesToTrust

Modifies the set of certificates in a certificate trust list (CTL) for a given purpose.

CertSelectCertificateA

Presents a dialog box that allows the user to select certificates from a set of certificates that match the given criteria.

CertSelectCertificateW

Presents a dialog box that allows the user to select certificates from a set of certificates that match the given criteria.

CertViewPropertiesA

The CertViewProperties function displays the properties for a certificate in a user interface (UI) dialog box. This function has no
associated import library. You must use the LoadLibrary and GetProcAddress functions to dynamically link to CryptDlg.dll.

CertViewPropertiesW

The CertViewProperties function displays the properties for a certificate in a user interface (UI) dialog box. This function has no
associated import library. You must use the LoadLibrary and GetProcAddress functions to dynamically link to CryptDlg.dll.

GetFriendlyNameOfCertA

Retrieves the display name for a certificate.

GetFriendlyNameOfCertW

Retrieves the display name for a certificate.

Callback functions

PFNCMFILTERPROC

Filters each certificate to determine whether it will appear in the certificate selection dialog box that is displayed by the
CertSelectCertificate function.
 PFNCMHOOKPROC

Called before messages are processed by the certificate selection dialog box produced by the CertSelectCertificate function.

Structures

CERT_SELECT_STRUCT_A

Contains criteria upon which to select certificates that are presented in a certificate selection dialog box. This structure is used
in the CertSelectCertificate function.

CERT_SELECT_STRUCT_W

Contains criteria upon which to select certificates that are presented in a certificate selection dialog box. This structure is used
in the CertSelectCertificate function.

CERT_VIEWPROPERTIES_STRUCT_A

The CERT_VIEWPROPERTIES_STRUCT structure defines information used when the CertViewProperties function is called to
display a certificate's properties.

CERT_VIEWPROPERTIES_STRUCT_W

The CERT_VIEWPROPERTIES_STRUCT structure defines information used when the CertViewProperties function is called to
display a certificate's properties.

CTL_MODIFY_REQUEST

Contains a request to modify a certificate trust list (CTL). This structure is used in the CertModifyCertificatesToTrust function.
 CERT_SELECT_STRUCT_A structure (cryptdlg.h)
7/2/2022 • 4 minutes to read • Edit Online

The CERT_SELECT_STRUCT structure contains criteria upon which to select certificates that are presented in a
certificate selection dialog box. This structure is used in the CertSelectCertificate function.

Syntax
typedef struct tagCSSA {
DWORD dwSize;
HWND hwndParent;
HINSTANCE hInstance;
LPCSTR pTemplateName;
DWORD dwFlags;
LPCSTR szTitle;
DWORD cCertStore;
HCERTSTORE *arrayCertStore;
LPCSTR szPurposeOid;
DWORD cCertContext;
PCCERT_CONTEXT *arrayCertContext;
LPARAM lCustData;
PFNCMHOOKPROC pfnHook;
PFNCMFILTERPROC pfnFilter;
LPCSTR szHelpFileName;
DWORD dwHelpId;
HCRYPTPROV hprov;
} CERT_SELECT_STRUCT_A, *PCERT_SELECT_STRUCT_A;

Members
dwSize

The size, in bytes, of this structure.

hwndParent

A handle to the parent window of any dialog boxes that CertSelectCertificate generates.
hInstance

A handle to the module whose executable file contains the dialog box template.
pTemplateName

If the CSS_ENABLETEMPL ATE flag is set in the dwFlags member, set pTemplateName to a pointer to a
global memory object that contains the template that DialogBoxIndirectParam uses to create the dialog box. A
dialog box template consists of a header that describes the dialog box. The header is followed by one or more
additional blocks of data that describe each of the controls in the dialog box. The template can use either the
standard format or the extended format.
If the CSS_ENABLETEMPL ATEHANDLE flag is set in dwFlags , pTemplateName specifies the dialog box
template. pTemplateName is either the pointer to a null-terminated character string that specifies the name of
the dialog box template or an integer value that specifies the resource identifier of the dialog box template. If the
specifies a resource identifier, its high-order word must be zero and its low-order word must contain the
identifier. One way to create this integer value is to use the MAKEINTRESOURCE macro.
dwFlags

This member can be one or more of the following values.

VA L UE M EA N IN G

Hide the Proper ties button.

CSS_HIDE_PROPERTIES

Pass a hook procedure in pfnHook .

CSS_ENABLEHOOK

Enable multi-selection of certificates. This option is not

CSS_ALLOWMULTISELECT currently supported and is ignored.

Show the Help button.

CSS_SHOW_HELP

Cause CertSelectCertificate function to call the

CSS_ENABLETEMPL ATE DialogBoxIndirectParam function to create a dialog box. For
more information, see pTemplateName .

Cause the CertSelectCertificate function to call the

CSS_ENABLETEMPL ATEHANDLE DialogBoxParam function to create a dialog box. For more
information, see pTemplateName .

szTitle

A pointer to a string that contains the text for the title of the dialog box.
cCertStore

The number of elements in arrayCer tStore array.

arrayCertStore

A pointer to the array of certificate stores that the dialog box enumerates and displays the certificates from. The
cCer tStore member contains the number of elements in this array.
szPurposeOid

A pointer to a string representation of an object identifier (OID) for an enhanced key usage (EKU). If an OID is
provided, only certificates that include this EKU will be displayed.
cCertContext

The number of elements in the arrayCer tContext array. After the CertSelectCertificate function returns, this
member contains the number of certificates that were selected by the user. Currently, only one certificate can be
selected by the user.
arrayCertContext

A pointer to an array of CERT_CONTEXT structures. The cCer tContext member specifies the number of
elements in this array. This array must contain at least one element.
The certificates represented by these structures are selected when the dialog box displayed by the
CertSelectCertificate function is initially displayed. Currently, only the first certificate in this array is used. The
first certificate in this array will be released with the CertFreeCertificateContext function if the
Cer tSelectCer tificate function is successful. If the first element in this array is NULL , no certificates are
initially selected in the dialog box.
After the CertSelectCertificate function returns, this array contains the certificates that were selected by the user.
Currently, only one certificate can be selected by the user.
lCustData

A pointer to an array of byte values that hold custom data that is passed through to the filter procedure
referenced by pfnFilter . This custom data is not used by the CertSelectCertificate function.
pfnHook

A PFNCMHOOKPROC function pointer to the Hook callback function. This function is called before messages are
processed by the dialog box. For more information, see Hooks.
pfnFilter

A PFNCMFILTERPROC function pointer to the filter callback function. This is called to determine which
certificates will be displayed by the dialog box.
szHelpFileName

A pointer to a null-terminated string that contains the full path to the Help file.
dwHelpId

The context identifier for the topic. For more information, see
WinHelp.
hprov

A handle to the Cryptographic Service Provider (CSP) to use for certificate verification.

Remarks
NOTE
The cryptdlg.h header defines CERT_SELECT_STRUCT as an alias which automatically selects the ANSI or Unicode version
of this function based on the definition of the UNICODE preprocessor constant. Mixing usage of the encoding-neutral
alias with code that not encoding-neutral can lead to mismatches that result in compilation or runtime errors. For more
information, see Conventions for Function Prototypes.

Requirements

Minimum suppor ted client Windows XP [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Header cryptdlg.h

See also
CertSelectCertificate
 CERT_SELECT_STRUCT_W structure (cryptdlg.h)
7/2/2022 • 4 minutes to read • Edit Online

The CERT_SELECT_STRUCT structure contains criteria upon which to select certificates that are presented in a
certificate selection dialog box. This structure is used in the CertSelectCertificate function.

Syntax
typedef struct tagCSSW {
DWORD dwSize;
HWND hwndParent;
HINSTANCE hInstance;
LPCWSTR pTemplateName;
DWORD dwFlags;
LPCWSTR szTitle;
DWORD cCertStore;
HCERTSTORE *arrayCertStore;
LPCSTR szPurposeOid;
DWORD cCertContext;
PCCERT_CONTEXT *arrayCertContext;
LPARAM lCustData;
PFNCMHOOKPROC pfnHook;
PFNCMFILTERPROC pfnFilter;
LPCWSTR szHelpFileName;
DWORD dwHelpId;
HCRYPTPROV hprov;
} CERT_SELECT_STRUCT_W, *PCERT_SELECT_STRUCT_W;

Members
dwSize

The size, in bytes, of this structure.

hwndParent

A handle to the parent window of any dialog boxes that CertSelectCertificate generates.
hInstance

A handle to the module whose executable file contains the dialog box template.
pTemplateName

If the CSS_ENABLETEMPL ATE flag is set in the dwFlags member, set pTemplateName to a pointer to a
global memory object that contains the template that DialogBoxIndirectParam uses to create the dialog box. A
dialog box template consists of a header that describes the dialog box. The header is followed by one or more
additional blocks of data that describe each of the controls in the dialog box. The template can use either the
standard format or the extended format.
If the CSS_ENABLETEMPL ATEHANDLE flag is set in dwFlags , pTemplateName specifies the dialog box
template. pTemplateName is either the pointer to a null-terminated character string that specifies the name of
the dialog box template or an integer value that specifies the resource identifier of the dialog box template. If the
specifies a resource identifier, its high-order word must be zero and its low-order word must contain the
identifier. One way to create this integer value is to use the MAKEINTRESOURCE macro.
dwFlags

This member can be one or more of the following values.

VA L UE M EA N IN G

Hide the Proper ties button.

CSS_HIDE_PROPERTIES

Pass a hook procedure in pfnHook .

CSS_ENABLEHOOK

Enable multi-selection of certificates. This option is not

CSS_ALLOWMULTISELECT currently supported and is ignored.

Show the Help button.

CSS_SHOW_HELP

Cause CertSelectCertificate function to call the

CSS_ENABLETEMPL ATE DialogBoxIndirectParam function to create a dialog box. For
more information, see pTemplateName .

Cause the CertSelectCertificate function to call the

CSS_ENABLETEMPL ATEHANDLE DialogBoxParam function to create a dialog box. For more
information, see pTemplateName .

szTitle

A pointer to a string that contains the text for the title of the dialog box.
cCertStore

The number of elements in arrayCer tStore array.

arrayCertStore

A pointer to the array of certificate stores that the dialog box enumerates and displays the certificates from. The
cCer tStore member contains the number of elements in this array.
szPurposeOid

A pointer to a string representation of an object identifier (OID) for an enhanced key usage (EKU). If an OID is
provided, only certificates that include this EKU will be displayed.
cCertContext

The number of elements in the arrayCer tContext array. After the CertSelectCertificate function returns, this
member contains the number of certificates that were selected by the user. Currently, only one certificate can be
selected by the user.
arrayCertContext

A pointer to an array of CERT_CONTEXT structures. The cCer tContext member specifies the number of
elements in this array. This array must contain at least one element.
The certificates represented by these structures are selected when the dialog box displayed by the
CertSelectCertificate function is initially displayed. Currently, only the first certificate in this array is used. The
first certificate in this array will be released with the CertFreeCertificateContext function if the
Cer tSelectCer tificate function is successful. If the first element in this array is NULL , no certificates are
initially selected in the dialog box.
After the CertSelectCertificate function returns, this array contains the certificates that were selected by the user.
Currently, only one certificate can be selected by the user.
lCustData

A pointer to an array of byte values that hold custom data that is passed through to the filter procedure
referenced by pfnFilter . This custom data is not used by the CertSelectCertificate function.
pfnHook

A PFNCMHOOKPROC function pointer to the Hook callback function. This function is called before messages are
processed by the dialog box. For more information, see Hooks.
pfnFilter

A PFNCMFILTERPROC function pointer to the filter callback function. This is called to determine which
certificates will be displayed by the dialog box.
szHelpFileName

A pointer to a null-terminated string that contains the full path to the Help file.
dwHelpId

The context identifier for the topic. For more information, see
WinHelp.
hprov

A handle to the Cryptographic Service Provider (CSP) to use for certificate verification.

Remarks
NOTE
The cryptdlg.h header defines CERT_SELECT_STRUCT as an alias which automatically selects the ANSI or Unicode version
of this function based on the definition of the UNICODE preprocessor constant. Mixing usage of the encoding-neutral
alias with code that not encoding-neutral can lead to mismatches that result in compilation or runtime errors. For more
information, see Conventions for Function Prototypes.

Requirements

Minimum suppor ted client Windows XP [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Header cryptdlg.h

See also
CertSelectCertificate
 CERT_VIEWPROPERTIES_STRUCT_A structure
(cryptdlg.h)
7/2/2022 • 2 minutes to read • Edit Online

[The CERT_VIEWPROPERTIES_STRUCT structure is available for use in the operating systems specified in the
Requirements section. It may be altered or unavailable in subsequent versions.]
The CERT_VIEWPROPERTIES_STRUCT structure defines information used when the CertViewProperties
function is called to display a certificate's properties.

Syntax
typedef struct tagCERT_VIEWPROPERTIES_STRUCT_A {
DWORD dwSize;
HWND hwndParent;
HINSTANCE hInstance;
DWORD dwFlags;
LPCSTR szTitle;
PCCERT_CONTEXT pCertContext;
LPSTR *arrayPurposes;
DWORD cArrayPurposes;
DWORD cRootStores;
HCERTSTORE *rghstoreRoots;
DWORD cStores;
HCERTSTORE *rghstoreCAs;
DWORD cTrustStores;
HCERTSTORE *rghstoreTrust;
HCRYPTPROV hprov;
LPARAM lCustData;
DWORD dwPad;
LPCSTR szHelpFileName;
DWORD dwHelpId;
DWORD nStartPage;
DWORD cArrayPropSheetPages;
PROPSHEETPAGE *arrayPropSheetPages;
} CERT_VIEWPROPERTIES_STRUCT_A, *PCERT_VIEWPROPERTIES_STRUCT_A;

Members
dwSize

The size, in bytes, of this structure.

hwndParent

A handle to the parent window.

hInstance

A handle to the module instance.

dwFlags

Bitwise combination of zero or more of the following values.

 VA L UE M EA N IN G

Specifies that a hook function is enabled.

CM_ENABLEHOOK
1 (0x1)

Specifies that a help file is used.

CM_SHOW_HELP
2 (0x2)

Specifies that a help icon is used.

CM_SHOW_HELPICON
4 (0x4)

Specifies that a template is enabled.

CM_ENABLETEMPL ATE
8 (0x8)

Specifies that the Advance tab is not displayed.

CM_HIDE_ADVANCEPAGE
16 (0x10)

Specifies that the Trust tab is not displayed.

CM_HIDE_TRUSTPAGE
32 (0x20)

Specifies that the name cannot be changed.

CM_NO_NAMECHANGE
64 (0x40)

Specifies that the trust cannot be edited.

CM_NO_EDITTRUST
128 (0x80)

Specifies that the Detail tab is not displayed.

CM_HIDE_DETAILPAGE
256 (0x100)

Specifies that certificate stores are opened.

CM_ADD_CERT_STORES
512 (0x200)

szTitle

A pointer to a null-terminated string for the title of the user interface.

pCertContext

Certificate context for the certificate to be shown.

arrayPurposes

A pointer to an array of null-terminated strings that specify the certificate purposes.

cArrayPurposes

Number of elements in the arrayPurposes array. If this value is zero, then no trust status is displayed.
cRootStores

Number of elements in the rghstoreRoots array.

rghstoreRoots

Array of Root certificate store handles.

cStores

Number of elements in the rghstoreCAs array.

rghstoreCAs

Array of other certificate store handles.

cTrustStores

Number of elements in the rghstoreTrust array.

rghstoreTrust

Array of trust certificate store handles.

hprov

A handle to the cryptographic service provider (CSP) to use for verification.

lCustData

Value used for custom data.

dwPad

Padding location.
szHelpFileName

A pointer to a null-terminated string for the Help file name.

dwHelpId

ID for the Help file topic.

nStartPage

Number of the first property page.

cArrayPropSheetPages

Number of elements in the arrayPropSheetPages array.

arrayPropSheetPages

A pointer to an array of PROPSHEETPAGE structures that specify the property pages.

Remarks
 NOTE
The cryptdlg.h header defines CERT_VIEWPROPERTIES_STRUCT as an alias which automatically selects the ANSI or
Unicode version of this function based on the definition of the UNICODE preprocessor constant. Mixing usage of the
encoding-neutral alias with code that not encoding-neutral can lead to mismatches that result in compilation or runtime
errors. For more information, see Conventions for Function Prototypes.

Requirements

Minimum suppor ted client Windows XP [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Header cryptdlg.h

See also
CertViewProperties
 CERT_VIEWPROPERTIES_STRUCT_W structure
(cryptdlg.h)
7/2/2022 • 2 minutes to read • Edit Online

[The CERT_VIEWPROPERTIES_STRUCT structure is available for use in the operating systems specified in the
Requirements section. It may be altered or unavailable in subsequent versions.]
The CERT_VIEWPROPERTIES_STRUCT structure defines information used when the CertViewProperties
function is called to display a certificate's properties.

Syntax
typedef struct tagCERT_VIEWPROPERTIES_STRUCT_W {
DWORD dwSize;
HWND hwndParent;
HINSTANCE hInstance;
DWORD dwFlags;
LPCWSTR szTitle;
PCCERT_CONTEXT pCertContext;
LPSTR *arrayPurposes;
DWORD cArrayPurposes;
DWORD cRootStores;
HCERTSTORE *rghstoreRoots;
DWORD cStores;
HCERTSTORE *rghstoreCAs;
DWORD cTrustStores;
HCERTSTORE *rghstoreTrust;
HCRYPTPROV hprov;
LPARAM lCustData;
DWORD dwPad;
LPCWSTR szHelpFileName;
DWORD dwHelpId;
DWORD nStartPage;
DWORD cArrayPropSheetPages;
PROPSHEETPAGE *arrayPropSheetPages;
} CERT_VIEWPROPERTIES_STRUCT_W, *PCERT_VIEWPROPERTIES_STRUCT_W;

Members
dwSize

The size, in bytes, of this structure.

hwndParent

A handle to the parent window.

hInstance

A handle to the module instance.

dwFlags

Bitwise combination of zero or more of the following values.

 VA L UE M EA N IN G

Specifies that a hook function is enabled.

CM_ENABLEHOOK
1 (0x1)

Specifies that a help file is used.

CM_SHOW_HELP
2 (0x2)

Specifies that a help icon is used.

CM_SHOW_HELPICON
4 (0x4)

Specifies that a template is enabled.

CM_ENABLETEMPL ATE
8 (0x8)

Specifies that the Advance tab is not displayed.

CM_HIDE_ADVANCEPAGE
16 (0x10)

Specifies that the Trust tab is not displayed.

CM_HIDE_TRUSTPAGE
32 (0x20)

Specifies that the name cannot be changed.

CM_NO_NAMECHANGE
64 (0x40)

Specifies that the trust cannot be edited.

CM_NO_EDITTRUST
128 (0x80)

Specifies that the Detail tab is not displayed.

CM_HIDE_DETAILPAGE
256 (0x100)

Specifies that certificate stores are opened.

CM_ADD_CERT_STORES
512 (0x200)

szTitle

A pointer to a null-terminated string for the title of the user interface.

pCertContext

Certificate context for the certificate to be shown.

arrayPurposes

A pointer to an array of null-terminated strings that specify the certificate purposes.

cArrayPurposes

Number of elements in the arrayPurposes array. If this value is zero, then no trust status is displayed.
cRootStores

Number of elements in the rghstoreRoots array.

rghstoreRoots

Array of Root certificate store handles.

cStores

Number of elements in the rghstoreCAs array.

rghstoreCAs

Array of other certificate store handles.

cTrustStores

Number of elements in the rghstoreTrust array.

rghstoreTrust

Array of trust certificate store handles.

hprov

A handle to the cryptographic service provider (CSP) to use for verification.

lCustData

Value used for custom data.

dwPad

Padding location.
szHelpFileName

A pointer to a null-terminated string for the Help file name.

dwHelpId

ID for the Help file topic.

nStartPage

Number of the first property page.

cArrayPropSheetPages

Number of elements in the arrayPropSheetPages array.

arrayPropSheetPages

A pointer to an array of PROPSHEETPAGE structures that specify the property pages.

Remarks
 NOTE
The cryptdlg.h header defines CERT_VIEWPROPERTIES_STRUCT as an alias which automatically selects the ANSI or
Unicode version of this function based on the definition of the UNICODE preprocessor constant. Mixing usage of the
encoding-neutral alias with code that not encoding-neutral can lead to mismatches that result in compilation or runtime
errors. For more information, see Conventions for Function Prototypes.

Requirements

Minimum suppor ted client Windows XP [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Header cryptdlg.h

See also
CertViewProperties
 CertModifyCertificatesToTrust function (cryptdlg.h)
7/2/2022 • 2 minutes to read • Edit Online

The Cer tModifyCer tificatesToTrust function modifies the set of certificates in a certificate trust list (CTL) for a
given purpose.

Note This function has no associated import library. You must use the LoadLibrary and GetProcAddress functions to
dynamically link to CryptDlg.dll.

Syntax
CRYPTDLGAPI HRESULT CertModifyCertificatesToTrust(
[in] int cCerts,
[in] PCTL_MODIFY_REQUEST rgCerts,
[in] LPCSTR szPurpose,
[in] HWND hwnd,
[in, optional] HCERTSTORE hcertstoreTrust,
[in, optional] PCCERT_CONTEXT pccertSigner
);

Parameters
[in] cCerts

The number of modification requests that are in the rgCerts parameter.

[in] rgCerts

A pointer to a CTL_MODIFY_REQUEST structure that contains an array of modification requests.

[in] szPurpose

A pointer to a null-terminated string that contains the string representation of an object identifier (OID). The OID
specifies the enhanced key usage (EKU) of the CTL to be modified.
[in] hwnd

A handle to the parent window of the dialog boxes that this function generates.
[in, optional] hcertstoreTrust

A handle to the certificate store in which to modify the list of trusted certificates. If NULL , the Trusted People
store is used with the Current User location.
[in, optional] pccertSigner

A pointer to a CERT_CONTEXT structure that contains a certificate. It is used to sign the trust list. The certificate
also restricts the set of trust lists that may be modified. If NULL , the trust list is not signed.

Return value
An HRESULT . A value of S_OK indicates success.
Requirements

Minimum suppor ted client Windows XP [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header cryptdlg.h

DLL CryptDlg.dll

See also
CTL_MODIFY_REQUEST
 CertSelectCertificateA function (cryptdlg.h)
7/2/2022 • 2 minutes to read • Edit Online

The Cer tSelectCer tificate function presents a dialog box that allows the user to select certificates from a set of
certificates that match the given criteria.

Note This function has no associated import library. You must use the LoadLibrary and GetProcAddress functions to
dynamically link to CryptDlg.dll.

Syntax
CRYPTDLGAPI BOOL CertSelectCertificateA(
[in, out] PCERT_SELECT_STRUCT_A pCertSelectInfo
);

Parameters
[in, out] pCertSelectInfo

A pointer to a CERT_SELECT_STRUCT structure that contains criteria that control the displayed certificates for
selection and receives the selected certificate.

Return value
If the function succeeds, the return value is TRUE .
If the function fails, the return value is FALSE . For extended error information, call the GetLastError function.

Remarks
NOTE
The cryptdlg.h header defines CertSelectCertificate as an alias which automatically selects the ANSI or Unicode version of
this function based on the definition of the UNICODE preprocessor constant. Mixing usage of the encoding-neutral alias
with code that not encoding-neutral can lead to mismatches that result in compilation or runtime errors. For more
information, see Conventions for Function Prototypes.

Requirements

Minimum suppor ted client Windows XP [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

 Header cryptdlg.h

DLL CryptDlg.dll

See also
CERT_SELECT_STRUCT
 CertSelectCertificateW function (cryptdlg.h)
7/2/2022 • 2 minutes to read • Edit Online

The Cer tSelectCer tificate function presents a dialog box that allows the user to select certificates from a set of
certificates that match the given criteria.

Note This function has no associated import library. You must use the LoadLibrary and GetProcAddress functions to
dynamically link to CryptDlg.dll.

Syntax
CRYPTDLGAPI BOOL CertSelectCertificateW(
[in, out] PCERT_SELECT_STRUCT_W pCertSelectInfo
);

Parameters
[in, out] pCertSelectInfo

A pointer to a CERT_SELECT_STRUCT structure that contains criteria that control the displayed certificates for
selection and receives the selected certificate.

Return value
If the function succeeds, the return value is TRUE .
If the function fails, the return value is FALSE . For extended error information, call the GetLastError function.

Remarks
NOTE
The cryptdlg.h header defines CertSelectCertificate as an alias which automatically selects the ANSI or Unicode version of
this function based on the definition of the UNICODE preprocessor constant. Mixing usage of the encoding-neutral alias
with code that not encoding-neutral can lead to mismatches that result in compilation or runtime errors. For more
information, see Conventions for Function Prototypes.

Requirements

Minimum suppor ted client Windows XP [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

 Header cryptdlg.h

DLL CryptDlg.dll

See also
CERT_SELECT_STRUCT
 CertViewPropertiesA function (cryptdlg.h)
7/2/2022 • 2 minutes to read • Edit Online

[The Cer tViewProper ties function is available for use in the operating systems specified in the Requirements
section. It may be altered or unavailable in subsequent versions. Instead, use the CryptUIDlgViewContext
function.]
The Cer tViewProper ties function displays the properties for a certificate in a user interface (UI) dialog box.
This function has no associated import library. You must use the LoadLibrary and GetProcAddress functions to
dynamically link to CryptDlg.dll.

Note This function has no associated import library. You must use the LoadLibrary and GetProcAddress functions to
dynamically link to CryptDlg.dll.

Syntax
CRYPTDLGAPI BOOL CertViewPropertiesA(
[in] PCERT_VIEWPROPERTIES_STRUCT_A pCertViewInfo
);

Parameters
[in] pCertViewInfo

A pointer to a CERT_VIEWPROPERTIES_STRUCT structure that contains the information about the certificate to
view.

Return value
The return value is TRUE if the function is successful; FALSE if the function fails.

Remarks
NOTE
The cryptdlg.h header defines CertViewProperties as an alias which automatically selects the ANSI or Unicode version of
this function based on the definition of the UNICODE preprocessor constant. Mixing usage of the encoding-neutral alias
with code that not encoding-neutral can lead to mismatches that result in compilation or runtime errors. For more
information, see Conventions for Function Prototypes.

Requirements

Minimum suppor ted client Windows XP [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header cryptdlg.h

DLL CryptDlg.dll
 CertViewPropertiesW function (cryptdlg.h)
7/2/2022 • 2 minutes to read • Edit Online

[The Cer tViewProper ties function is available for use in the operating systems specified in the Requirements
section. It may be altered or unavailable in subsequent versions. Instead, use the CryptUIDlgViewContext
function.]
The Cer tViewProper ties function displays the properties for a certificate in a user interface (UI) dialog box.
This function has no associated import library. You must use the LoadLibrary and GetProcAddress functions to
dynamically link to CryptDlg.dll.

Note This function has no associated import library. You must use the LoadLibrary and GetProcAddress functions to
dynamically link to CryptDlg.dll.

Syntax
CRYPTDLGAPI BOOL CertViewPropertiesW(
[in] PCERT_VIEWPROPERTIES_STRUCT_W pCertViewInfo
);

Parameters
[in] pCertViewInfo

A pointer to a CERT_VIEWPROPERTIES_STRUCT structure that contains the information about the certificate to
view.

Return value
The return value is TRUE if the function is successful; FALSE if the function fails.

Remarks
NOTE
The cryptdlg.h header defines CertViewProperties as an alias which automatically selects the ANSI or Unicode version of
this function based on the definition of the UNICODE preprocessor constant. Mixing usage of the encoding-neutral alias
with code that not encoding-neutral can lead to mismatches that result in compilation or runtime errors. For more
information, see Conventions for Function Prototypes.

Requirements

Minimum suppor ted client Windows XP [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header cryptdlg.h

DLL CryptDlg.dll
 CTL_MODIFY_REQUEST structure (cryptdlg.h)
7/2/2022 • 2 minutes to read • Edit Online

The CTL_MODIFY_REQUEST structure contains a request to modify a certificate trust list (CTL). This structure
is used in the CertModifyCertificatesToTrust function.

Syntax
typedef struct _CTL_MODIFY_REQUEST {
PCCERT_CONTEXT pccert;
DWORD dwOperation;
DWORD dwError;
} CTL_MODIFY_REQUEST, *PCTL_MODIFY_REQUEST;

Members
pccert

A pointer to a CERT_CONTEXT structure that contains the certificate to change the trust on.
dwOperation

The operation to be performed. This member can be one of the following values.

VA L UE M EA N IN G

Add the certificate to the CTL. The certificate is explicitly

CTL_MODIFY_REQUEST_ADD_TRUSTED trusted.

Add the certificate to the Untrusted Certificates certificate

CTL_MODIFY_REQUEST_ADD_NOT_TRUSTED store. The certificate is explicitly not trusted.

Remove the certificate from the CTL. The certificate is neither

CTL_MODIFY_REQUEST_REMOVE explicitly trusted nor untrusted. To be trusted, the certificate
must have a trusted root certificate at the root of its
certificate chain.

dwError

The error code generated for this operation.

Requirements

Minimum suppor ted client Windows XP [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Header cryptdlg.h
See also
CertModifyCertificatesToTrust
 GetFriendlyNameOfCertA function (cryptdlg.h)
7/2/2022 • 2 minutes to read • Edit Online

[The GetFriendlyNameOfCer t function is available for use in the operating systems specified in the
Requirements section. It may be altered or unavailable in subsequent versions. Instead, use the
CertGetNameString function with the CERT_NAME_FRIENDLY_DISPLAY_TYPE flag.]
The GetFriendlyNameOfCer t function retrieves the display name for a certificate.

Note This function has no associated import library. You must use the LoadLibrary and GetProcAddress functions to
dynamically link to CryptDlg.dll.

Syntax
CRYPTDLGAPI DWORD GetFriendlyNameOfCertA(
[in] PCCERT_CONTEXT pccert,
[out] LPSTR pch,
[in] DWORD cch
);

Parameters
[in] pccert

A pointer to the certificate context whose display name is being retrieved.

[out] pch

A pointer to a character string that receives the display name for the certificate.
[in] cch

Number of characters allocated for pchBuffer, including the terminating NULL character.

Return value
The return value is the number of characters, including the terminating NULL character, in the returned display
name.

Remarks
NOTE
The cryptdlg.h header defines GetFriendlyNameOfCert as an alias which automatically selects the ANSI or Unicode version
of this function based on the definition of the UNICODE preprocessor constant. Mixing usage of the encoding-neutral
alias with code that not encoding-neutral can lead to mismatches that result in compilation or runtime errors. For more
information, see Conventions for Function Prototypes.
Requirements

Minimum suppor ted client Windows XP [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header cryptdlg.h

DLL CryptDlg.dll
 GetFriendlyNameOfCertW function (cryptdlg.h)
7/2/2022 • 2 minutes to read • Edit Online

[The GetFriendlyNameOfCer t function is available for use in the operating systems specified in the
Requirements section. It may be altered or unavailable in subsequent versions. Instead, use the
CertGetNameString function with the CERT_NAME_FRIENDLY_DISPLAY_TYPE flag.]
The GetFriendlyNameOfCer t function retrieves the display name for a certificate.

Note This function has no associated import library. You must use the LoadLibrary and GetProcAddress functions to
dynamically link to CryptDlg.dll.

Syntax
CRYPTDLGAPI DWORD GetFriendlyNameOfCertW(
[in] PCCERT_CONTEXT pccert,
LPWSTR pwch,
DWORD cwch
);

Parameters
[in] pccert

A pointer to the certificate context whose display name is being retrieved.

pwch

A pointer to a character string that receives the display name for the certificate.
cwch

Number of characters allocated for pwch, including the terminating NULL character.

Return value
The return value is the number of characters, including the terminating NULL character, in the returned display
name.

Remarks
NOTE
The cryptdlg.h header defines GetFriendlyNameOfCert as an alias which automatically selects the ANSI or Unicode version
of this function based on the definition of the UNICODE preprocessor constant. Mixing usage of the encoding-neutral
alias with code that not encoding-neutral can lead to mismatches that result in compilation or runtime errors. For more
information, see Conventions for Function Prototypes.
Requirements

Minimum suppor ted client Windows XP [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header cryptdlg.h

DLL CryptDlg.dll
 PFNCMFILTERPROC callback function (cryptdlg.h)
7/2/2022 • 2 minutes to read • Edit Online

The PFNCMFILTERPROC function is a filter procedure that filters each certificate to determine whether it will
appear in the certificate selection dialog box that is displayed by the CertSelectCertificate function.
PFNCMFILTERPROC is an application-defined callback function that is specified in the CERT_SELECT_STRUCT
structure. The CERT_SELECT_STRUCT structure is a parameter in the CertSelectCertificate function. The
PFNCMFILTERPROC function must be implemented by the developer to suit each application.

Syntax
PFNCMFILTERPROC Pfncmfilterproc;

BOOL Pfncmfilterproc(
[in] PCCERT_CONTEXT pCertContext,
LPARAM unnamedParam2,
DWORD unnamedParam3,
DWORD unnamedParam4
)
{...}

Parameters
[in] pCertContext

A pointer to a CERT_CONTEXT structure that contains a certificate on which to make a filtering determination.
unnamedParam2

unnamedParam3

unnamedParam4

Return value
Return a nonzero value (TRUE ) to display the certificate. Return zero (FALSE ) to not display the certificate.

Remarks
The first DWORD parameter is dwFlags. The second is lCustData—the address of an array of byte values that
holds custom data. lCustData is passed to the PFNCMFILTERPROC function by the CertSelectCertificate
function.

Requirements

Minimum suppor ted client Windows XP [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]
 Target Platform Windows

Header cryptdlg.h

See also
CERT_SELECT_STRUCT
CertSelectCertificate
 PFNCMHOOKPROC callback function (cryptdlg.h)
7/2/2022 • 2 minutes to read • Edit Online

The PFNCMHOOKPROC function is a hook procedure that is called before messages are processed by the
certificate selection dialog box produced by the CertSelectCertificate function. The function allows the caller to
customize the dialog box. PFNCMHOOKPROC is an application-defined callback function specified in the
CERT_SELECT_STRUCT structure. The CERT_SELECT_STRUCT structure is a parameter in the
CertSelectCertificate function. The PFNCMHOOKPROC function must be implemented by the developer to suit
each application.

Syntax
PFNCMHOOKPROC Pfncmhookproc;

UINT Pfncmhookproc(
[in] HWND hwndDialog,
[in] UINT message,
[in] WPARAM wParam,
[in] LPARAM lParam
)
{...}

Parameters
[in] hwndDialog

A handle to a dialog box window.

[in] message

The message.
[in] wParam

Additional information about the message sent or posted.

[in] lParam

Additional information about the message sent or posted.

Return value
Return a nonzero value (TRUE ) if this function processes the message. Return zero (FALSE ) if this function does
not process the message.

Remarks
For information about hooks, see Hooks.

Requirements
 Minimum suppor ted client Windows XP [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header cryptdlg.h

See also
CERT_SELECT_STRUCT
CertSelectCertificate
 cryptuiapi.h header
7/2/2022 • 2 minutes to read • Edit Online

This header is used by Security and Identity. For more information, see:
Security and Identity
cryptuiapi.h contains the following programming interfaces:

Functions

CertSelectionGetSerializedBlob

A helper function used to retrieve a serialized certificate BLOB from a CERT_SELECTUI_INPUT structure.

CryptUIDlgCertMgr

Displays a dialog box that allows the user to manage certificates.

CryptUIDlgSelectCertificateFromStore

Displays a dialog box that allows the selection of a certificate from a specified store.

CryptUIDlgViewCertificateA

Presents a dialog box that displays a specified certificate.

CryptUIDlgViewCertificateW

Presents a dialog box that displays a specified certificate.

CryptUIDlgViewContext

Displays a certificate, CTL, or CRL context.

CryptUIWizDigitalSign

Digitally signs a document or BLOB.

CryptUIWizExport

Exports a certificate, a certificate trust list (CTL), a certificate revocation list (CRL), or a certificate store to a file.

CryptUIWizFreeDigitalSignContext

Frees the CRYPTUI_WIZ_DIGITAL_SIGN_CONTEXT structure allocated by the CryptUIWizDigitalSign function.

CryptUIWizImport

Imports a certificate, a certificate trust list (CTL), a certificate revocation list (CRL), or a certificate store to a certificate store.
Callback functions

PFNCFILTERPROC

An application-defined callback function that filters the certificates that appear in the digital signature wizard that are
displayed by the CryptUIWizDigitalSign function.

Structures

CERT_SELECTUI_INPUT

Used by the CertSelectionGetSerializedBlob function to serialize the certificates contained in a store or an array of certificate
chains. The returned serialized BLOB can be passed to the CredUIPromptForWindowsCredentials function.

CRYPTUI_CERT_MGR_STRUCT

Contains information about a certificate manager dialog box.

CRYPTUI_INITDIALOG_STRUCT

Supports the CRYPTUI_VIEWCERTIFICATE_STRUCT structure.

CRYPTUI_VIEWCERTIFICATE_STRUCTA

Contains information about a certificate to view. This structure is used in the CryptUIDlgViewCertificate function.

CRYPTUI_VIEWCERTIFICATE_STRUCTW

Contains information about a certificate to view. This structure is used in the CryptUIDlgViewCertificate function.

CRYPTUI_WIZ_DIGITAL_SIGN_BLOB_INFO

Contains information about the public key BLOB used by the CryptUIWizDigitalSign function.

CRYPTUI_WIZ_DIGITAL_SIGN_CERT_PVK_INFO

Contains information about the PVK file that contains the certificates used by the CryptUIWizDigitalSign function.

CRYPTUI_WIZ_DIGITAL_SIGN_CONTEXT

Used with the CryptUIWizDigitalSign function to contain information about a BLOB.

CRYPTUI_WIZ_DIGITAL_SIGN_EXTENDED_INFO

Used with the CRYPTUI_WIZ_DIGITAL_SIGN_INFO structure to contain extended information about a signature.

CRYPTUI_WIZ_DIGITAL_SIGN_INFO

Contains information about digital signing.

CRYPTUI_WIZ_DIGITAL_SIGN_PVK_FILE_INFO

Used with the CRYPTUI_WIZ_DIGITAL_SIGN_INFO structure to contain information about the PVK file used by the digital
signature wizard.

CRYPTUI_WIZ_DIGITAL_SIGN_STORE_INFO

Contains information about the certificate store used by the digital signature wizard.

CRYPTUI_WIZ_EXPORT_CERTCONTEXT_INFO

Contains information that controls the operation of the CryptUIWizExport function when a certificate is the object being
exported.

CRYPTUI_WIZ_EXPORT_INFO

Contains information that controls the operation of the CryptUIWizExport function.

CRYPTUI_WIZ_IMPORT_SRC_INFO

Contains the subject to import into the CryptUIWizImport function.

 CERT_SELECTUI_INPUT structure (cryptuiapi.h)
7/2/2022 • 2 minutes to read • Edit Online

The CERT_SELECTUI_INPUT structure is used by the CertSelectionGetSerializedBlob function to serialize the

certificates contained in a store or an array of certificate chains. The returned serialized BLOB can be passed to
the CredUIPromptForWindowsCredentials function.

Syntax
typedef struct {
HCERTSTORE hStore;
PCCERT_CHAIN_CONTEXT *prgpChain;
DWORD cChain;
} CERT_SELECTUI_INPUT, *PCERT_SELECTUI_INPUT;

Members
hStore

The handle of a certificate store created by the caller. The store contains the set of application preselected
certificates.
prgpChain

An array of pointers to CERT_CHAIN_CONTEXT structures. Applications provision this array by preselecting

certificate chains using the CertSelectCertificateChains function.
cChain

The number of CERT_CHAIN_CONTEXT structures that are in the array pointed to by the prgpChain member.

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Header cryptuiapi.h
 CertSelectionGetSerializedBlob function
(cryptuiapi.h)
7/2/2022 • 2 minutes to read • Edit Online

The Cer tSelectionGetSerializedBlob function is a helper function used to retrieve a serialized certificate
BLOB from a CERT_SELECTUI_INPUT structure.

Syntax
HRESULT CertSelectionGetSerializedBlob(
[in] PCERT_SELECTUI_INPUT pcsi,
[out] void **ppOutBuffer,
[out] ULONG *pulOutBufferSize
);

Parameters
[in] pcsi

A pointer to a CERT_SELECTUI_INPUT structure that contains the certificate store and certificate context chain
information.
[out] ppOutBuffer

The address of a pointer to a buffer that receives the serialized certificates BLOB.
[out] pulOutBufferSize

A pointer to a ULONG to receive the size, in bytes, of the BLOB received in the buffer pointed to by the
ppOutBuffer parameter.

Return value
If the function succeeds, the function returns S_OK .
If the function fails, it returns an HRESULT value that indicates the error. If both hStore and prgpChain
parameters are not NULL , return E_INVALIDARG . For a list of common error codes, see Common HRESULT
Values.

Remarks
The returned serialized BLOB is passed to the CredUIPromptForWindowsCredentials function in the
pvInAuthBuffer parameter to allow a user to select a certificate by using the credential selection UI.
The certificates that are serialized in the BLOB returned in the buffer pointed to by the ppOutBuffer parameter of
this function are dependent on the values of the hStore and prgpChain members of the
CERT_SELECTUI_INPUT structure.

H STO RE P RGP C H A IN C ERT IF IC AT ES SERIA L IZ ED

 NULL not NULL The certificates pointed to by the
prgpChain member are serialized.

not NULL NULL The certificates specified by the hStore

member are serialized.

NULL NULL An empty BLOB is returned.

not NULL not NULL The call fails and the function returns
E_INVALIDARG .

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Target Platform Windows

Header cryptuiapi.h

DLL Cryptui.dll
 CRYPTUI_CERT_MGR_STRUCT structure
(cryptuiapi.h)
7/2/2022 • 2 minutes to read • Edit Online

The CRYPTUI_CERT_MGR_STRUCT structure contains information about a certificate manager dialog box.

Syntax
typedef struct _CRYPTUI_CERT_MGR_STRUCT {
DWORD dwSize;
HWND hwndParent;
DWORD dwFlags;
LPCWSTR pwszTitle;
LPCSTR pszInitUsageOID;
} CRYPTUI_CERT_MGR_STRUCT, *PCRYPTUI_CERT_MGR_STRUCT;

Members
dwSize

The size, in bytes, of the structure. This value must be set to sizeof(CRYPTUI_CERT_MGR_STRUCT) .
hwndParent

Handle of the parent window of the dialog box.

dwFlags

Reserved. This value must be set to zero.

pwszTitle

Title of the dialog box.

pszInitUsageOID

Enhanced key usage object identifier (OID) of the certificates that will initially appear in the dialog box. The
default value is NULL , which displays all certificates.

Requirements

Minimum suppor ted client Windows XP [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Header cryptuiapi.h
 CRYPTUI_INITDIALOG_STRUCT structure
(cryptuiapi.h)
7/2/2022 • 2 minutes to read • Edit Online

The CRYPTUI_INITDIALOG_STRUCT structure supports the CRYPTUI_VIEWCERTIFICATE_STRUCT structure. It

is passed as the lParam in the WM_INITDIALOG call to each property sheet that is in the rgPropSheetPages
array of the CRYPTUI_VIEWCERTIFICATE_STRUCT structure. The CRYPTUI_VIEWCERTIFICATE_STRUCT
structure is used in the CryptUIDlgViewCertificate function.

Syntax
typedef struct tagCRYPTUI_INITDIALOG_STRUCT {
LPARAM lParam;
PCCERT_CONTEXT pCertContext;
} CRYPTUI_INITDIALOG_STRUCT, *PCRYPTUI_INITDIALOG_STRUCT;

Members
lParam

The lParam in the PROPSHEETPAGE structure.

pCertContext

A pointer to the CERT_CONTEXT structure for the certificate that CryptUIDlgViewCertificate is displaying.

Requirements

Minimum suppor ted client Windows XP [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Header cryptuiapi.h

See also
CRYPTUI_VIEWCERTIFICATE_STRUCT
CryptUIDlgViewCertificate
 CRYPTUI_VIEWCERTIFICATE_STRUCTA structure
(cryptuiapi.h)
7/2/2022 • 4 minutes to read • Edit Online

The CRYPTUI_VIEWCERTIFICATE_STRUCT structure contains information about a certificate to view. This

structure is used in the CryptUIDlgViewCertificate function.

Syntax
typedef struct tagCRYPTUI_VIEWCERTIFICATE_STRUCTA {
DWORD dwSize;
HWND hwndParent;
DWORD dwFlags;
LPCSTR szTitle;
PCCERT_CONTEXT pCertContext;
LPCSTR *rgszPurposes;
DWORD cPurposes;
union {
CRYPT_PROVIDER_DATA const *pCryptProviderData;
HANDLE hWVTStateData;
};
BOOL fpCryptProviderDataTrustedUsage;
DWORD idxSigner;
DWORD idxCert;
BOOL fCounterSigner;
DWORD idxCounterSigner;
DWORD cStores;
HCERTSTORE *rghStores;
DWORD cPropSheetPages;
LPCPROPSHEETPAGEA rgPropSheetPages;
DWORD nStartPage;
} CRYPTUI_VIEWCERTIFICATE_STRUCTA, *PCRYPTUI_VIEWCERTIFICATE_STRUCTA;

Members
dwSize

The size, in bytes, of the CRYPTUI_VIEWCERTIFICATE_STRUCT structure.

hwndParent

A handle to the window that is the parent of the dialog box produced by CryptUIDlgViewCertificate.
dwFlags

This member can be one or more of the following values.

VA L UE M EA N IN G

The Cer tification Path page is disabled.

CRYPTUI_HIDE_HIERARCHYPAGE

The Details page is disabled.

CRYPTUI_HIDE_DETAILPAGE
 The user is not allowed to change the properties.
CRYPTUI_DISABLE_EDITPROPERTIES

The user is allowed to change the properties.

CRYPTUI_ENABLE_EDITPROPERTIES

The Install button is disabled.

CRYPTUI_DISABLE_ADDTOSTORE

The Install button is enabled.

CRYPTUI_ENABLE_ADDTOSTORE

The pages or buttons that allow the user to accept or decline

CRYPTUI_ACCEPT_DECLINE_STYLE any decision are disabled.

An untrusted root error is ignored.

CRYPTUI_IGNORE_UNTRUSTED_ROOT

Known trusted stores will not be used to build the chain.

CRYPTUI_DONT_OPEN_STORES

A known trusted root store will not be used to build the

CRYPTUI_ONLY_OPEN_ROOT_STORE chain.

Use only when viewing certificates on remote computers. If

CRYPTUI_WARN_UNTRUSTED_ROOT this flag is used, the first element of rghStores must be the
handle of the root store on the remote computer.

Enable revocation checking with default behavior. The default

CRYPTUI_ENABLE_REVOCATION_CHECKING behavior is to enable revocation checking of the entire
certificate chain except the root certificate. Valid only if
neither the pCr yptProviderData nor the
hWVTStateData union member is passed in.

When building a certificate chain for a remote computer,

CRYPTUI_WARN_REMOTE_TRUST warn that the chain may not be trusted on the remote
computer.

If this flag is set, the Copy to file button will be disabled on

CRYPTUI_DISABLE_EXPORT the Detail page.

Enable revocation checking only on the leaf certificate in the

CRYPTUI_ENABLE_REVOCATION_CHECK_END_CERT certificate chain. Valid only if neither the
pCr yptProviderData nor the hWVTStateData union
member is passed in.

CRYPTUI_ENABLE_REVOCATION_CHECK_CHAIN
Enable revocation checking on each certificate in the
certificate chain. Valid only if neither the
pCr yptProviderData nor the hWVTStateData union
member is passed in.
Note Because root certificates rarely contain
information that allows revocation checking, it is
expected that use of this option will usually result in
failure of the CryptUIDlgViewCertificate function. The
recommended option is to use
CRYPTUI_ENABLE_REVOCATION_CHECK_CHAIN_EXCLU
DE_ROOT.

Enable revocation checking on each certificate in the

CRYPTUI_ENABLE_REVOCATION_CHECK_CHAIN_EXC certificate chain except for the root certificate. This is the
LUDE_ROOT recommended option to use for certificate revocation
checking. Valid only if neither the pCr yptProviderData nor
the hWVTStateData union member is passed in.
Note This flag is equivalent to
CRYPTUI_ENABLE_REVOCATION_CHECKING.

Disable the HTML Help button (? ) in the Cer tificate dialog

CRYPTUI_DISABLE_HTMLLINK box.

Disable the Issuer Statement button on the General tab

CRYPTUI_DISABLE_ISSUERSTATEMENT of the Cer tificate dialog box.

Disable online revocation checking. Set this flag to ensure

CRYPTUI_CACHE_ONLY_URL_RETRIEVAL
that the CryptUIDlgViewCertificate function uses the local
cache to retrieve the certificate and does not attempt to
retrieve the certificate from the network.
Windows Ser ver 2008, Windows Vista, Windows
Ser ver 2003 and Windows XP: This flag is not
supported.

szTitle

A pointer to a null-terminated string that contains the title for the window.
pCertContext

A pointer to the CERT_CONTEXT structure that contains the certificate context to display.
rgszPurposes

An array of pointers to null-terminated strings that contain the purposes for which this certificate will be
validated.
cPurposes

The number of purposes in the rgszPurposes array.

pCryptProviderData

If the WinVerifyTrust function has already been called for the certificate and the
WTHelperProvDataFromStateData function was also called, pass in a pointer to the state structure that was
acquired from the call to WTHelperProvDataFromStateData . If pCr yptProviderData is set,
fpCr yptProviderDataTrustedUsage , idxSigner , idxCer t , and fCounterSignature must also be set.
hWVTStateData

If WinVerifyTrust has already been called for the certificate and WTHelperProvDataFromStateData was not
called, pass in the hWVTStateData member of the WINTRUST_DATA structure. If hWVTStateData is set,
fpCr yptProviderDataTrustedUsage , idxSigner , idxCer t , and fCounterSignature must also be set.
fpCryptProviderDataTrustedUsage

If WinVerifyTrust was called, this is the result of whether the certificate was trusted.
idxSigner

The index of the signer to view.

idxCert

The index of the certificate that is being viewed within the signer chain. The certificate context of this cert must
match pCer tContext .
fCounterSigner

TRUE if a countersignature is being viewed. If this is TRUE , idxCounterSigner must be valid.

idxCounterSigner

The index of the countersigner to view.

cStores

The number of other stores in the rghStores array of certificate stores to search when building and validating
the certificate chain.
rghStores

An array of HCERTSTORE handles to other certificate stores to search when building and validating the
certificate chain.
cPropSheetPages

The number of property pages to add to the dialog box.

rgPropSheetPages

An array of property pages to add to the dialog box. Each page in this array will not receive the lParam in the
PROPSHEETPAGE structure as the lParam in the WM_INITDIALOG message. It will instead receive a pointer to a
CRYPTUI_INITDIALOG_STRUCT structure. It contains the lParam in PROPSHEETPAGE and the pointer to the
CERT_CONTEXT for which the page is being displayed.
nStartPage

The index of the initial page that will be displayed. If the highest bit (0x8000) is set, the index is assumed to index
rgPropSheetPages (after the highest bit has been stripped off, for example, 0x8000 will indicate the first page
in rgPropSheetPages ). If the highest bit is zero, nStar tPage will be the starting index of the default certificate
dialog box property pages.

Remarks
 NOTE
The cryptuiapi.h header defines CRYPTUI_VIEWCERTIFICATE_STRUCT as an alias which automatically selects the ANSI or
Unicode version of this function based on the definition of the UNICODE preprocessor constant. Mixing usage of the
encoding-neutral alias with code that not encoding-neutral can lead to mismatches that result in compilation or runtime
errors. For more information, see Conventions for Function Prototypes.

Requirements

Minimum suppor ted client Windows XP [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Header cryptuiapi.h

See also
CryptUIDlgViewCertificate
 CRYPTUI_VIEWCERTIFICATE_STRUCTW structure
(cryptuiapi.h)
7/2/2022 • 4 minutes to read • Edit Online

The CRYPTUI_VIEWCERTIFICATE_STRUCT structure contains information about a certificate to view. This

structure is used in the CryptUIDlgViewCertificate function.

Syntax
typedef struct tagCRYPTUI_VIEWCERTIFICATE_STRUCTW {
DWORD dwSize;
HWND hwndParent;
DWORD dwFlags;
LPCWSTR szTitle;
PCCERT_CONTEXT pCertContext;
LPCSTR *rgszPurposes;
DWORD cPurposes;
union {
CRYPT_PROVIDER_DATA const *pCryptProviderData;
HANDLE hWVTStateData;
};
BOOL fpCryptProviderDataTrustedUsage;
DWORD idxSigner;
DWORD idxCert;
BOOL fCounterSigner;
DWORD idxCounterSigner;
DWORD cStores;
HCERTSTORE *rghStores;
DWORD cPropSheetPages;
LPCPROPSHEETPAGEW rgPropSheetPages;
DWORD nStartPage;
} CRYPTUI_VIEWCERTIFICATE_STRUCTW, *PCRYPTUI_VIEWCERTIFICATE_STRUCTW;

Members
dwSize

The size, in bytes, of the CRYPTUI_VIEWCERTIFICATE_STRUCT structure.

hwndParent

A handle to the window that is the parent of the dialog box produced by CryptUIDlgViewCertificate.
dwFlags

This member can be one or more of the following values.

VA L UE M EA N IN G

The Cer tification Path page is disabled.

CRYPTUI_HIDE_HIERARCHYPAGE

The Details page is disabled.

CRYPTUI_HIDE_DETAILPAGE
 The user is not allowed to change the properties.
CRYPTUI_DISABLE_EDITPROPERTIES

The user is allowed to change the properties.

CRYPTUI_ENABLE_EDITPROPERTIES

The Install button is disabled.

CRYPTUI_DISABLE_ADDTOSTORE

The Install button is enabled.

CRYPTUI_ENABLE_ADDTOSTORE

The pages or buttons that allow the user to accept or decline

CRYPTUI_ACCEPT_DECLINE_STYLE any decision are disabled.

An untrusted root error is ignored.

CRYPTUI_IGNORE_UNTRUSTED_ROOT

Known trusted stores will not be used to build the chain.

CRYPTUI_DONT_OPEN_STORES

A known trusted root store will not be used to build the

CRYPTUI_ONLY_OPEN_ROOT_STORE chain.

Use only when viewing certificates on remote computers. If

CRYPTUI_WARN_UNTRUSTED_ROOT this flag is used, the first element of rghStores must be the
handle of the root store on the remote computer.

Enable revocation checking with default behavior. The default

CRYPTUI_ENABLE_REVOCATION_CHECKING behavior is to enable revocation checking of the entire
certificate chain except the root certificate. Valid only if
neither the pCr yptProviderData nor the
hWVTStateData union member is passed in.

When building a certificate chain for a remote computer,

CRYPTUI_WARN_REMOTE_TRUST warn that the chain may not be trusted on the remote
computer.

If this flag is set, the Copy to file button will be disabled on

CRYPTUI_DISABLE_EXPORT the Detail page.

Enable revocation checking only on the leaf certificate in the

CRYPTUI_ENABLE_REVOCATION_CHECK_END_CERT certificate chain. Valid only if neither the
pCr yptProviderData nor the hWVTStateData union
member is passed in.

CRYPTUI_ENABLE_REVOCATION_CHECK_CHAIN
Enable revocation checking on each certificate in the
certificate chain. Valid only if neither the
pCr yptProviderData nor the hWVTStateData union
member is passed in.
Note Because root certificates rarely contain
information that allows revocation checking, it is
expected that use of this option will usually result in
failure of the CryptUIDlgViewCertificate function. The
recommended option is to use
CRYPTUI_ENABLE_REVOCATION_CHECK_CHAIN_EXCLU
DE_ROOT.

Enable revocation checking on each certificate in the

CRYPTUI_ENABLE_REVOCATION_CHECK_CHAIN_EXC certificate chain except for the root certificate. This is the
LUDE_ROOT recommended option to use for certificate revocation
checking. Valid only if neither the pCr yptProviderData nor
the hWVTStateData union member is passed in.
Note This flag is equivalent to
CRYPTUI_ENABLE_REVOCATION_CHECKING.

Disable the HTML Help button (? ) in the Cer tificate dialog

CRYPTUI_DISABLE_HTMLLINK box.

Disable the Issuer Statement button on the General tab

CRYPTUI_DISABLE_ISSUERSTATEMENT of the Cer tificate dialog box.

Disable online revocation checking. Set this flag to ensure

CRYPTUI_CACHE_ONLY_URL_RETRIEVAL
that the CryptUIDlgViewCertificate function uses the local
cache to retrieve the certificate and does not attempt to
retrieve the certificate from the network.
Windows Ser ver 2008, Windows Vista, Windows
Ser ver 2003 and Windows XP: This flag is not
supported.

szTitle

A pointer to a null-terminated string that contains the title for the window.
pCertContext

A pointer to the CERT_CONTEXT structure that contains the certificate context to display.
rgszPurposes

An array of pointers to null-terminated strings that contain the purposes for which this certificate will be
validated.
cPurposes

The number of purposes in the rgszPurposes array.

pCryptProviderData

If the WinVerifyTrust function has already been called for the certificate and the
WTHelperProvDataFromStateData function was also called, pass in a pointer to the state structure that was
acquired from the call to WTHelperProvDataFromStateData . If pCr yptProviderData is set,
fpCr yptProviderDataTrustedUsage , idxSigner , idxCer t , and fCounterSignature must also be set.
hWVTStateData

If WinVerifyTrust has already been called for the certificate and WTHelperProvDataFromStateData was not
called, pass in the hWVTStateData member of the WINTRUST_DATA structure. If hWVTStateData is set,
fpCr yptProviderDataTrustedUsage , idxSigner , idxCer t , and fCounterSignature must also be set.
fpCryptProviderDataTrustedUsage

If WinVerifyTrust was called, this is the result of whether the certificate was trusted.
idxSigner

The index of the signer to view.

idxCert

The index of the certificate that is being viewed within the signer chain. The certificate context of this cert must
match pCer tContext .
fCounterSigner

TRUE if a countersignature is being viewed. If this is TRUE , idxCounterSigner must be valid.

idxCounterSigner

The index of the countersigner to view.

cStores

The number of other stores in the rghStores array of certificate stores to search when building and validating
the certificate chain.
rghStores

An array of HCERTSTORE handles to other certificate stores to search when building and validating the
certificate chain.
cPropSheetPages

The number of property pages to add to the dialog box.

rgPropSheetPages

An array of property pages to add to the dialog box. Each page in this array will not receive the lParam in the
PROPSHEETPAGE structure as the lParam in the WM_INITDIALOG message. It will instead receive a pointer to a
CRYPTUI_INITDIALOG_STRUCT structure. It contains the lParam in PROPSHEETPAGE and the pointer to the
CERT_CONTEXT for which the page is being displayed.
nStartPage

The index of the initial page that will be displayed. If the highest bit (0x8000) is set, the index is assumed to index
rgPropSheetPages (after the highest bit has been stripped off, for example, 0x8000 will indicate the first page
in rgPropSheetPages ). If the highest bit is zero, nStar tPage will be the starting index of the default certificate
dialog box property pages.

Remarks
 NOTE
The cryptuiapi.h header defines CRYPTUI_VIEWCERTIFICATE_STRUCT as an alias which automatically selects the ANSI or
Unicode version of this function based on the definition of the UNICODE preprocessor constant. Mixing usage of the
encoding-neutral alias with code that not encoding-neutral can lead to mismatches that result in compilation or runtime
errors. For more information, see Conventions for Function Prototypes.

Requirements

Minimum suppor ted client Windows XP [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Header cryptuiapi.h

See also
CryptUIDlgViewCertificate
 CRYPTUI_WIZ_DIGITAL_SIGN_BLOB_INFO structure
(cryptuiapi.h)
7/2/2022 • 2 minutes to read • Edit Online

[The CRYPTUI_WIZ_DIGITAL_SIGN_BLOB_INFO structure is available for use in the operating systems

specified in the Requirements section. It may be altered or unavailable in subsequent versions.]
The CRYPTUI_WIZ_DIGITAL_SIGN_BLOB_INFO structure contains information about the public key BLOB
used by the CryptUIWizDigitalSign function.

Syntax
typedef struct _CRYPTUI_WIZ_DIGITAL_SIGN_BLOB_INFO {
DWORD dwSize;
GUID *pGuidSubject;
DWORD cbBlob;
BYTE *pbBlob;
LPCWSTR pwszDisplayName;
} CRYPTUI_WIZ_DIGITAL_SIGN_BLOB_INFO, *PCRYPTUI_WIZ_DIGITAL_SIGN_BLOB_INFO;

Members
dwSize

The size, in bytes, of the structure.

pGuidSubject

A pointer to a GUID that contains the GUID that identifies the Session Initiation Protocol (SIP) functions to load.
cbBlob

The size, in bytes, of the BLOB pointed to by the pbBlob member.

pbBlob

A pointer to the BLOB to sign.

pwszDisplayName

A pointer to a null-terminated Unicode string that contains the display name of the BLOB to sign.

Requirements

Minimum suppor ted client Windows XP [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Header cryptuiapi.h
See also
CryptUIWizDigitalSign
 CRYPTUI_WIZ_DIGITAL_SIGN_CERT_PVK_INFO
structure (cryptuiapi.h)
7/2/2022 • 2 minutes to read • Edit Online

[The CRYPTUI_WIZ_DIGITAL_SIGN_CERT_PVK_INFO structure is available for use in the operating systems

specified in the Requirements section. It may be altered or unavailable in subsequent versions.]
The CRYPTUI_WIZ_DIGITAL_SIGN_CERT_PVK_INFO structure contains information about the PVK file that
contains the certificates used by the CryptUIWizDigitalSign function.

Syntax
typedef struct _CRYPTUI_WIZ_DIGITAL_SIGN_CERT_PVK_INFO {
DWORD dwSize;
LPWSTR pwszSigningCertFileName;
DWORD dwPvkChoice;
union {
PCCRYPTUI_WIZ_DIGITAL_SIGN_PVK_FILE_INFO pPvkFileInfo;
PCRYPT_KEY_PROV_INFO pPvkProvInfo;
};
} CRYPTUI_WIZ_DIGITAL_SIGN_CERT_PVK_INFO, *PCRYPTUI_WIZ_DIGITAL_SIGN_CERT_PVK_INFO;

Members
dwSize

The size, in bytes, of the structure.

pwszSigningCertFileName

A pointer to a null-terminated Unicode string that contains the path and file named of the file that contains the
signing certificates.
dwPvkChoice

Specifies the type of entity that contains the certificates. This can be one of the following values.

VA L UE M EA N IN G

The entity is a PVK file.

CRYPTUI_WIZ_DIGITAL_SIGN_PVK_FILE

The entity is a PVK provider.

CRYPTUI_WIZ_DIGITAL_SIGN_PVK_PROV

pPvkFileInfo

A pointer to a CRYPTUI_WIZ_DIGITAL_SIGN_PVK_FILE_INFO structure that contains the PVK file that contains the
certificates. This member is used if CRYPTUI_WIZ_DIGITAL_SIGN_PVK_FILE is specified for the
dwPvkChoice member.
pPvkProvInfo
A pointer to a CRYPT_KEY_PROV_INFO structure that contains information about the PVK provider that contains
the certificates. This member is used if CRYPTUI_WIZ_DIGITAL_SIGN_PVK_PROV is specified for the
dwPvkChoice member.

Requirements

Minimum suppor ted client Windows XP [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Header cryptuiapi.h

See also
CryptUIWizDigitalSign
 CRYPTUI_WIZ_DIGITAL_SIGN_CONTEXT structure
(cryptuiapi.h)
7/2/2022 • 2 minutes to read • Edit Online

[The CRYPTUI_WIZ_DIGITAL_SIGN_CONTEXT structure is available for use in the operating systems

specified in the Requirements section. It may be altered or unavailable in subsequent versions.]
The CRYPTUI_WIZ_DIGITAL_SIGN_CONTEXT structure is used with the CryptUIWizDigitalSign function to
contain information about a BLOB.

Syntax
typedef struct _CRYPTUI_WIZ_DIGITAL_SIGN_CONTEXT {
DWORD dwSize;
DWORD cbBlob;
BYTE *pbBlob;
} CRYPTUI_WIZ_DIGITAL_SIGN_CONTEXT, *PCRYPTUI_WIZ_DIGITAL_SIGN_CONTEXT;

Members
dwSize

The size, in bytes, of the structure.

cbBlob

The size, in bytes, of the BLOB pointed to by the pbBlob member.

pbBlob

A pointer to the signed BLOB.

Requirements

Minimum suppor ted client Windows XP [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Header cryptuiapi.h

See also
CryptUIWizDigitalSign
 CRYPTUI_WIZ_DIGITAL_SIGN_EXTENDED_INFO
structure (cryptuiapi.h)
7/2/2022 • 2 minutes to read • Edit Online

[The CRYPTUI_WIZ_DIGITAL_SIGN_EXTENDED_INFO structure is available for use in the operating systems

specified in the Requirements section. It may be altered or unavailable in subsequent versions.]
The CRYPTUI_WIZ_DIGITAL_SIGN_EXTENDED_INFO structure is used with the
CRYPTUI_WIZ_DIGITAL_SIGN_INFO structure to contain extended information about a signature.

Syntax
typedef struct _CRYPTUI_WIZ_DIGITAL_SIGN_EXTENDED_INFO {
DWORD dwSize;
DWORD dwAttrFlags;
LPCWSTR pwszDescription;
LPCWSTR pwszMoreInfoLocation;
LPCSTR pszHashAlg;
LPCWSTR pwszSigningCertDisplayString;
HCERTSTORE hAdditionalCertStore;
PCRYPT_ATTRIBUTES psAuthenticated;
PCRYPT_ATTRIBUTES psUnauthenticated;
} CRYPTUI_WIZ_DIGITAL_SIGN_EXTENDED_INFO, *PCRYPTUI_WIZ_DIGITAL_SIGN_EXTENDED_INFO;

Members
dwSize

The size, in bytes, of the structure.

dwAttrFlags

A value that indicates the type of the signature. This can be one of the following values.

VA L UE M EA N IN G

The signature is a commercial signature.

CRYPTUI_WIZ_DIGITAL_SIGN_COMMERCIAL

The signature is a personal signature.

CRYPTUI_WIZ_DIGITAL_SIGN_INDIVIDUAL

pwszDescription

A pointer to a null-terminated Unicode string that contains the description of the subject of the signature.
pwszMoreInfoLocation

A pointer to a null-terminated Unicode string that contains the location from which to get more information
about the file. This information will be displayed when the file is downloaded.
pszHashAlg
A pointer to a null-terminated ANSI string that contains the object identifier (OID) of the hash algorithm used for
the signature. The default value is NULL , which indicates that the SHA-1 hash algorithm is used.
pwszSigningCertDisplayString

A pointer to a null-terminated Unicode string that contains the string displayed on the digital signature wizard
page. The string should prompt the user to select a certificate for a specific purpose.
hAdditionalCertStore

A handle to an additional certificate store that will be added to the signature.

psAuthenticated

A pointer to a CRYPT_ATTRIBUTES structure that contains authenticated attributes supplied by the user.
psUnauthenticated

A pointer to a CRYPT_ATTRIBUTES structure that contains unauthenticated attributes supplied by the user.

Requirements

Minimum suppor ted client Windows XP [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Header cryptuiapi.h

See also
CRYPTUI_WIZ_DIGITAL_SIGN_INFO
 CRYPTUI_WIZ_DIGITAL_SIGN_INFO structure
(cryptuiapi.h)
7/2/2022 • 2 minutes to read • Edit Online

[The CRYPTUI_WIZ_DIGITAL_SIGN_INFO structure is available for use in the operating systems specified in
the Requirements section. It may be altered or unavailable in subsequent versions.]
The CRYPTUI_WIZ_DIGITAL_SIGN_INFO structure contains information about digital signing. This structure
is used by the CryptUIWizDigitalSign function.

Syntax
typedef struct _CRYPTUI_WIZ_DIGITAL_SIGN_INFO {
DWORD dwSize;
DWORD dwSubjectChoice;
union {
LPCWSTR pwszFileName;
PCCRYPTUI_WIZ_DIGITAL_SIGN_BLOB_INFO pSignBlobInfo;
};
DWORD dwSigningCertChoice;
union {
PCCERT_CONTEXT pSigningCertContext;
PCCRYPTUI_WIZ_DIGITAL_SIGN_STORE_INFO pSigningCertStore;
PCCRYPTUI_WIZ_DIGITAL_SIGN_CERT_PVK_INFO pSigningCertPvkInfo;
};
LPCWSTR pwszTimestampURL;
DWORD dwAdditionalCertChoice;
PCCRYPTUI_WIZ_DIGITAL_SIGN_EXTENDED_INFO pSignExtInfo;
} CRYPTUI_WIZ_DIGITAL_SIGN_INFO, *PCRYPTUI_WIZ_DIGITAL_SIGN_INFO;

Members
dwSize

The size, in bytes, of the structure.

dwSubjectChoice

A value that indicates the entity that is to be signed. This member is required if CRYPTUI_WIZ_NO_UI is
specified in the dwFlags parameter of the CryptUIWizDigitalSign function. This can be one of the following
values.

VA L UE M EA N IN G

The memory BLOB specified by the pSignBlobInfo member

CRYPTUI_WIZ_DIGITAL_SIGN_SUBJECT_BLOB is to be signed.

The file specified by the pwszFileName member is to be

CRYPTUI_WIZ_DIGITAL_SIGN_SUBJECT_FILE signed.

The user will be prompted for a file to sign.

0
pwszFileName

A pointer to a null-terminated Unicode string that contains the path and file name of the file to sign. This
member is used if CRYPTUI_WIZ_DIGITAL_SIGN_SUBJECT_FILE is specified for the dwSubjectChoice
member.
pSignBlobInfo

A pointer to a CRYPTUI_WIZ_DIGITAL_SIGN_BLOB_INFO structure that contains the BLOB to sign. This member is
used if CRYPTUI_WIZ_DIGITAL_SIGN_SUBJECT_BLOB is specified for the dwSubjectChoice member.
dwSigningCertChoice

A value that specifies the location of the certificate that is used to sign the entity. The default value is zero. This
can be one of the following values.

Note If CRYPTUI_WIZ_NO_UI is specified in the dwFlags parameter of the CryptUIWizDigitalSign function, this value must
be either CRYPTUI_WIZ_DIGITAL_SIGN_CERT or CRYPTUI_WIZ_DIGITAL_SIGN_PVK .

VA L UE M EA N IN G

The certificate is contained in the CERT_CONTEXT structure

CRYPTUI_WIZ_DIGITAL_SIGN_CERT pointed to by the pSigningCer tContext member.

The certificate is contained in the certificate store contained

CRYPTUI_WIZ_DIGITAL_SIGN_STORE in the CRYPTUI_WIZ_DIGITAL_SIGN_STORE_INFO structure
pointed to by the pSigningCer tStore member.

The certificate is contained in the PVK file contained in the

CRYPTUI_WIZ_DIGITAL_SIGN_PVK CRYPTUI_WIZ_DIGITAL_SIGN_CERT_PVK_INFO structure
pointed to by the pSigningCer tPvkInfo member.

The certificates in the My store are used.

0

pSigningCertContext

A pointer to a CERT_CONTEXT structure that contains the certificate to use to sign the entity. This member is
used if CRYPTUI_WIZ_DIGITAL_SIGN_CERT is specified for the dwSigningCer tChoice member.
pSigningCertStore

A pointer to a CRYPTUI_WIZ_DIGITAL_SIGN_STORE_INFO structure that contains the certificate to use to sign the
entity. This member is used if CRYPTUI_WIZ_DIGITAL_SIGN_STORE is specified for the
dwSigningCer tChoice member.
pSigningCertPvkInfo

A pointer to a CRYPTUI_WIZ_DIGITAL_SIGN_CERT_PVK_INFO structure that contains the certificate to use to sign

the entity. This member is used if CRYPTUI_WIZ_DIGITAL_SIGN_PVK is specified for the
dwSigningCer tChoice member.
pwszTimestampURL

A pointer to a null-terminated Unicode string that contains the URL for the time stamp.
dwAdditionalCertChoice

A value that indicates whether additional certificates will be included in the signature. The default value is zero.
This can be one of the following values.

VA L UE M EA N IN G

The entire certificate chain will be included in the signature.

CRYPTUI_WIZ_DIGITAL_SIGN_ADD_CHAIN

All certificates in the certificate chain except the root will be

CRYPTUI_WIZ_DIGITAL_SIGN_ADD_CHAIN_NO_ROOT included in the signature.

No additional certificates will be included in the signature.

0

pSignExtInfo

A pointer to a CRYPTUI_WIZ_DIGITAL_SIGN_EXTENDED_INFO structure that contains extended information

about the signature.

Requirements

Minimum suppor ted client Windows XP [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Header cryptuiapi.h

See also
CryptUIWizDigitalSign
 CRYPTUI_WIZ_DIGITAL_SIGN_PVK_FILE_INFO
structure (cryptuiapi.h)
7/2/2022 • 2 minutes to read • Edit Online

[The CRYPTUI_WIZ_DIGITAL_SIGN_PVK_FILE_INFO structure is available for use in the operating systems

specified in the Requirements section. It may be altered or unavailable in subsequent versions.]
The CRYPTUI_WIZ_DIGITAL_SIGN_PVK_FILE_INFO structure is used with the
CRYPTUI_WIZ_DIGITAL_SIGN_INFO structure to contain information about the PVK file used by the digital
signature wizard.

Syntax
typedef struct _CRYPTUI_WIZ_DIGITAL_SIGN_PVK_FILE_INFO {
DWORD dwSize;
LPWSTR pwszPvkFileName;
LPWSTR pwszProvName;
DWORD dwProvType;
} CRYPTUI_WIZ_DIGITAL_SIGN_PVK_FILE_INFO, *PCRYPTUI_WIZ_DIGITAL_SIGN_PVK_FILE_INFO;

Members
dwSize

The size, in bytes, of the structure.

pwszPvkFileName

A pointer to a null-terminated Unicode string that contains the path and file name of the PVK file.
pwszProvName

A pointer to a null-terminated Unicode string that contains the name of the provider.
dwProvType

Contains the provider type identifier. For more information about the provider types, see Cryptographic
Provider Types.

Requirements

Minimum suppor ted client Windows XP [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Header cryptuiapi.h

See also
CRYPTUI_WIZ_DIGITAL_SIGN_INFO
Cryptographic Provider Types
 CRYPTUI_WIZ_DIGITAL_SIGN_STORE_INFO
structure (cryptuiapi.h)
7/2/2022 • 2 minutes to read • Edit Online

[The CRYPTUI_WIZ_DIGITAL_SIGN_STORE_INFO structure is available for use in the operating systems

specified in the Requirements section. It may be altered or unavailable in subsequent versions.]
The CRYPTUI_WIZ_DIGITAL_SIGN_STORE_INFO structure contains information about the certificate store
used by the digital signature wizard.

Syntax
typedef struct _CRYPTUI_WIZ_DIGITAL_SIGN_STORE_INFO {
DWORD dwSize;
DWORD cCertStore;
HCERTSTORE *rghCertStore;
PFNCFILTERPROC pFilterCallback;
void *pvCallbackData;
} CRYPTUI_WIZ_DIGITAL_SIGN_STORE_INFO, *PCRYPTUI_WIZ_DIGITAL_SIGN_STORE_INFO;

Members
dwSize

The size, in bytes, of the structure. This value must be set to sizeof(CRYPTUI_WIZ_DIGITAL_SIGN_STORE_INFO) .
cCertStore

Number of certificates in the rghCer tStore member.

rghCertStore

A pointer to a handle to the certificate store that will be used by the digital signature wizard.
pFilterCallback

Filter callback function used to display the certificate.

pvCallbackData

A pointer to the callback data.

Requirements

Minimum suppor ted client Windows XP [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Header cryptuiapi.h
 CRYPTUI_WIZ_EXPORT_CERTCONTEXT_INFO
structure (cryptuiapi.h)
7/2/2022 • 2 minutes to read • Edit Online

[The CRYPTUI_WIZ_EXPORT_CERTCONTEXT_INFO structure is available for use in the operating systems

specified in the Requirements section. It may be altered or unavailable in subsequent versions.]
The CRYPTUI_WIZ_EXPORT_CERTCONTEXT_INFO structure contains information that controls the operation
of the CryptUIWizExport function when a certificate is the object being exported.

Syntax
typedef struct _CRYPTUI_WIZ_EXPORT_CERTCONTEXT_INFO {
DWORD dwSize;
DWORD dwExportFormat;
BOOL fExportChain;
BOOL fExportPrivateKeys;
LPCWSTR pwszPassword;
BOOL fStrongEncryption;
} CRYPTUI_WIZ_EXPORT_CERTCONTEXT_INFO, *PCRYPTUI_WIZ_EXPORT_CERTCONTEXT_INFO;

Members
dwSize

The size, in bytes, of this structure.

dwExportFormat

A value that indicates the export format of the certificate. This member can be one of the following values.

VA L UE M EA N IN G

Export in Abstract Syntax Notation One (ASN.1)

CRYPTUI_WIZ_EXPORT_FORMAT_DER Distinguished Encoding Rules (DER) format.

Export in Private Information Exchange (PFX) format.

CRYPTUI_WIZ_EXPORT_FORMAT_PFX

Export in Public Key Cryptography Standard #7 (PKCS #7)

CRYPTUI_WIZ_EXPORT_FORMAT_PKCS7 format.

Export in base 64 format.

CRYPTUI_WIZ_EXPORT_FORMAT_BASE64

Export in certificate revocation list (CRL) format.

CRYPTUI_WIZ_EXPORT_FORMAT_CRL
 Export in certificate trust list (CTL) format.
CRYPTUI_WIZ_EXPORT_FORMAT_CTL

fExportChain

Indicates whether the certificate chain should be exported in addition to the certificate. Contains nonzero to
export the chain or zero to not export the chain.
fExportPrivateKeys

Indicates whether the private key should be exported in addition to the certificate. Contains nonzero to export
the private key or zero to not export the private key.
pwszPassword

A pointer to a null-terminated Unicode string that contains the password used to access the private key. This is
required if fExpor tPrivateKeys is nonzero and is otherwise ignored.
fStrongEncryption

Indicates whether strong encryption should be used in the export process. Contains nonzero to use strong
encryption or zero to use weak encryption. This must be nonzero if dwExpor tFormat is
CRYPTUI_WIZ_EXPORT_FORMAT_PFX . If this is nonzero, the PFX BLOB produced is not compatible with
Internet Explorer 4.0 or earlier versions.
Note We recommend that you set this to nonzero; otherwise, a substantially weaker encryption algorithm is
used in the export process.

Requirements

Minimum suppor ted client Windows XP [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Header cryptuiapi.h

See also
CRYPTUI_WIZ_EXPORT_INFO
CryptUIWizExport
 CRYPTUI_WIZ_EXPORT_INFO structure
(cryptuiapi.h)
7/2/2022 • 2 minutes to read • Edit Online

[The CRYPTUI_WIZ_EXPORT_INFO structure is available for use in the operating systems specified in the
Requirements section. It may be altered or unavailable in subsequent versions.]
The CRYPTUI_WIZ_EXPORT_INFO structure contains information that controls the operation of the
CryptUIWizExport function.

Syntax
typedef struct _CRYPTUI_WIZ_EXPORT_INFO {
DWORD dwSize;
LPCWSTR pwszExportFileName;
DWORD dwSubjectChoice;
union {
PCCERT_CONTEXT pCertContext;
PCCTL_CONTEXT pCTLContext;
PCCRL_CONTEXT pCRLContext;
HCERTSTORE hCertStore;
};
DWORD cStores;
HCERTSTORE *rghStores;
} CRYPTUI_WIZ_EXPORT_INFO, *PCRYPTUI_WIZ_EXPORT_INFO;

Members
dwSize

The size, in bytes, of this structure.

pwszExportFileName

A pointer to a null-terminated Unicode string that contains the fully qualified file name to export to. If this
member is not NULL and the CRYPTUI_WIZ_NO_UI flag in the dwFlags parameter of the CryptUIWizExport
function is not set, this string is displayed to the user as the default file name. This member is required if the
CRYPTUI_WIZ_NO_UI flag is set. This member is otherwise optional.
dwSubjectChoice

Indicates the type of the subject to export. This member can be one of the following values.

VA L UE M EA N IN G

Export the certificate context that is specified in the

CRYPTUI_WIZ_EXPORT_CERT_CONTEXT pCer tContext member.

Export the certificate trust list (CTL) context that is specified

CRYPTUI_WIZ_EXPORT_CTL_CONTEXT in the pCTLContext member.
 Export the certificate revocation list (CRL) context that is
CRYPTUI_WIZ_EXPORT_CRL_CONTEXT specified in the pCRLContext member.

Export the certificate store that is specified in the

CRYPTUI_WIZ_EXPORT_CERT_STORE hCer tStore member.

Export only the certificates from the certificate store that is

CRYPTUI_WIZ_EXPORT_CERT_STORE_CERTIFICATES_ specified in the hCer tStore member.
ONLY

pCertContext

A pointer to the CERT_CONTEXT structure that contains the certificate to export. This member is used if the
dwSubjectChoice member contains CRYPTUI_WIZ_EXPORT_CERT_CONTEXT .
pCTLContext

A pointer to the CTL_CONTEXT structure that contains the CTL to export. This member is used if the
dwSubjectChoice member contains CRYPTUI_WIZ_EXPORT_CTL_CONTEXT .
pCRLContext

A pointer to the CRL_CONTEXT structure that contains the CRL to export. This member is used if the
dwSubjectChoice member contains CRYPTUI_WIZ_EXPORT_CRL_CONTEXT .
hCertStore

A handle to the certificate store to export. This member is used if the dwSubjectChoice member contains
CRYPTUI_WIZ_EXPORT_CERT_STORE or CRYPTUI_WIZ_EXPORT_CERT_STORE_CERTIFICATES_ONLY .
cStores

The number of elements in the rghStores array.

rghStores

An array of extra certificate stores to search for certificates in the trust chain if the chain is being exported with a
certificate. This member is ignored if dwSubjectChoice is anything other than the
CRYPTUI_WIZ_EXPORT_CERT_CONTEXT value. The cStores member contains the number of elements in
this array.

Requirements

Minimum suppor ted client Windows XP [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Header cryptuiapi.h

See also
CryptUIWizExport
 CRYPTUI_WIZ_IMPORT_SRC_INFO structure
(cryptuiapi.h)
7/2/2022 • 2 minutes to read • Edit Online

[The CRYPTUI_WIZ_IMPORT_SRC_INFO structure is available for use in the operating systems specified in
the Requirements section. It may be altered or unavailable in subsequent versions.]
The CRYPTUI_WIZ_IMPORT_SRC_INFO structure contains the subject to import into the CryptUIWizImport
function. The subject can be a certificate, a certificate trust list (CTL), or a certificate revocation list (CRL).

Syntax
typedef struct _CRYPTUI_WIZ_IMPORT_SUBJECT_INFO {
DWORD dwSize;
DWORD dwSubjectChoice;
union {
LPCWSTR pwszFileName;
PCCERT_CONTEXT pCertContext;
PCCTL_CONTEXT pCTLContext;
PCCRL_CONTEXT pCRLContext;
HCERTSTORE hCertStore;
};
DWORD dwFlags;
LPCWSTR pwszPassword;
} CRYPTUI_WIZ_IMPORT_SRC_INFO, *PCRYPTUI_WIZ_IMPORT_SRC_INFO;

Members
dwSize

The size, in bytes, of this structure.

dwSubjectChoice

Indicates the type of subject to import. This member can be one of the following values.

VA L UE M EA N IN G

Import the certificate stored in the file referenced in the

CRYPTUI_WIZ_IMPORT_SUBJECT_FILE pwszFileName member.

Import the certificate referenced in the pCer tContext

CRYPTUI_WIZ_IMPORT_SUBJECT_CERT_CONTEXT member.

Import the CTL referenced in the pCTLContext member.

CRYPTUI_WIZ_IMPORT_SUBJECT_CTL_CONTEXT

Import the CRL referenced in the pCRLContext member.

CRYPTUI_WIZ_IMPORT_SUBJECT_CRL_CONTEXT
 Import the certificate store referenced in the hCer tStore
CRYPTUI_WIZ_IMPORT_SUBJECT_CERT_STORE member.

pwszFileName

A pointer to a null-terminated Unicode string that contains the path and file name of the file that contains the
certificate to import. This member is used if the dwSubjectChoice member contains
CRYPTUI_WIZ_IMPORT_SUBJECT_FILE .
pCertContext

A pointer to the CERT_CONTEXT structure that contains the certificate to import. This member is used if the
dwSubjectChoice member contains CRYPTUI_WIZ_IMPORT_SUBJECT_CERT_CONTEXT .
pCTLContext

A pointer to the CTL_CONTEXT structure that contains the CTL to import. This member is used if the
dwSubjectChoice member contains CRYPTUI_WIZ_IMPORT_SUBJECT_CTL_CONTEXT .
pCRLContext

A pointer to the CRL_CONTEXT structure that contains the CRL to import. This member is used if the
dwSubjectChoice member contains CRYPTUI_WIZ_IMPORT_SUBJECT_CRL_CONTEXT .
hCertStore

A handle to the certificate store to import. This member is used if the dwSubjectChoice member contains
CRYPTUI_WIZ_IMPORT_SUBJECT_CERT_STORE .
dwFlags

Contains flags that modify the import operation. This member is required if pwszFileName contains a Personal
Information Exchange (PFX) BLOB. Otherwise, this member is ignored. This member can be zero or a
combination of one or more of the following values.

VA L UE M EA N IN G

Imported keys are marked as exportable. If this flag is not

CRYPT_EXPORTABLE used, calls to the CryptExportKey function with the key
handle fail.

The user is to be notified by means of a dialog box or some

CRYPT_USER_PROTECTED other manner when certain actions are attempting to use
this key. The precise behavior is specified by the
cryptographic service provider (CSP) that is being used.
Prior to Internet Explorer 4.0, Microsoft CSPs ignored
this flag. Starting with Internet Explorer 4.0, Microsoft
CSPs support this flag.
If the provider context was opened with the
CRYPT_SILENT flag set, using this flag causes a failure,
and the last error is set to NTE_SILENT_CONTEXT .

The private keys are stored under the local computer and
CRYPT_MACHINE_KEYSET not under the current user.
 The private keys are stored under the current user and not
CRYPT_USER_KEYSET under the local computer, even if the PFX BLOB specifies that
they should go under the local computer.

pwszPassword

Pointer to a null-terminated Unicode string that contains the password used to access the private key. A
password is required if pwszFileName contains a PFX BLOB. If a password is not required, the variable can be
an empty string. This member cannot be NULL .

Requirements

Minimum suppor ted client Windows XP [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Header cryptuiapi.h

See also
CRYPTUI_WIZ_EXPORT_INFO
CryptUIWizExport
 CryptUIDlgCertMgr function (cryptuiapi.h)
7/2/2022 • 2 minutes to read • Edit Online

The Cr yptUIDlgCer tMgr function displays a dialog box that allows the user to manage certificates.

Syntax
BOOL CryptUIDlgCertMgr(
[in] PCCRYPTUI_CERT_MGR_STRUCT pCryptUICertMgr
);

Parameters
[in] pCryptUICertMgr

A pointer to a CRYPTUI_CERT_MGR_STRUCT structure that contains information about how to create the dialog
box.

Return value
The return value is TRUE if the function succeeds; otherwise, FALSE.

Requirements

Minimum suppor ted client Windows XP [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header cryptuiapi.h

Librar y Cryptui.lib

DLL Cryptui.dll
 CryptUIDlgSelectCertificateFromStore function
(cryptuiapi.h)
7/2/2022 • 2 minutes to read • Edit Online

The Cr yptUIDlgSelectCer tificateFromStore function displays a dialog box that allows the selection of a
certificate from a specified store.

Syntax
PCCERT_CONTEXT CryptUIDlgSelectCertificateFromStore(
[in] HCERTSTORE hCertStore,
[in] HWND hwnd,
[in, optional] LPCWSTR pwszTitle,
[in, optional] LPCWSTR pwszDisplayString,
[in] DWORD dwDontUseColumn,
[in] DWORD dwFlags,
[in] void *pvReserved
);

Parameters
[in] hCertStore

Handle of the certificate store to be searched.

[in] hwnd

Handle of the window for the display. If NULL , defaults to the desktop window.
[in, optional] pwszTitle

String used as the title of the dialog box. If NULL , the default title, "Select Certificate," is used.
[in, optional] pwszDisplayString

Text statement in the selection dialog box. If NULL , the default phrase, "Select a certificate you want to use," is
used.
[in] dwDontUseColumn

Flags that can be combined to exclude columns of the display.

VA L UE M EA N IN G

Do not display the ISSUEDTO information.

CRYPTUI_SELECT_ISSUEDTO_COLUMN

Do not display the ISSUEDBY information.

CRYPTUI_SELECT_ISSUEDBY_COLUMN

Do not display IntendedUse information.

CRYPTUI_SELECT_INTENDEDUSE_COLUMN
 Do not display the display name information.
CRYPTUI_SELECT_FRIENDLYNAME_COLUMN

Do not display location information.

CRYPTUI_SELECT_LOCATION_COLUMN

Do not display expiration information.

CRYPTUI_SELECT_EXPIRATION_COLUMN

[in] dwFlags

Currently not used and should be set to 0.

[in] pvReserved

Reserved for future use.

Return value
Returns a pointer to the selected certificate context. If no certificate was selected, NULL is returned. When you
have finished using the certificate, free the certificate context by calling the CertFreeCertificateContext function.

Requirements

Minimum suppor ted client Windows XP [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header cryptuiapi.h

Librar y Cryptui.lib

DLL Cryptui.dll

See also
CryptUIDlgViewContext
 CryptUIDlgViewCertificateA function (cryptuiapi.h)
7/2/2022 • 2 minutes to read • Edit Online

The Cr yptUIDlgViewCer tificate function presents a dialog box that displays a specified certificate.

Syntax
BOOL CryptUIDlgViewCertificateA(
[in] PCCRYPTUI_VIEWCERTIFICATE_STRUCTA pCertViewInfo,
[out] BOOL *pfPropertiesChanged
);

Parameters
[in] pCertViewInfo

A pointer to a CRYPTUI_VIEWCERTIFICATE_STRUCT structure that contains information about the certificate to

view.
[out] pfPropertiesChanged

Indicates whether any certificate properties were modified by the caller.

Return value
If the function succeeds, the return value is nonzero (TRUE ).
If the function fails, the return value is zero (FALSE ). For extended error information, call the GetLastError
function.

Remarks
NOTE
The cryptuiapi.h header defines CryptUIDlgViewCertificate as an alias which automatically selects the ANSI or Unicode
version of this function based on the definition of the UNICODE preprocessor constant. Mixing usage of the encoding-
neutral alias with code that not encoding-neutral can lead to mismatches that result in compilation or runtime errors. For
more information, see Conventions for Function Prototypes.

Requirements

Minimum suppor ted client Windows XP [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

 Header cryptuiapi.h

Librar y Cryptui.lib

DLL Cryptui.dll

See also
CRYPTUI_VIEWCERTIFICATE_STRUCT
 CryptUIDlgViewCertificateW function (cryptuiapi.h)
7/2/2022 • 2 minutes to read • Edit Online

The Cr yptUIDlgViewCer tificate function presents a dialog box that displays a specified certificate.

Syntax
BOOL CryptUIDlgViewCertificateW(
[in] PCCRYPTUI_VIEWCERTIFICATE_STRUCTW pCertViewInfo,
[out] BOOL *pfPropertiesChanged
);

Parameters
[in] pCertViewInfo

A pointer to a CRYPTUI_VIEWCERTIFICATE_STRUCT structure that contains information about the certificate to

view.
[out] pfPropertiesChanged

Indicates whether any certificate properties were modified by the caller.

Return value
If the function succeeds, the return value is nonzero (TRUE ).
If the function fails, the return value is zero (FALSE ). For extended error information, call the GetLastError
function.

Remarks
NOTE
The cryptuiapi.h header defines CryptUIDlgViewCertificate as an alias which automatically selects the ANSI or Unicode
version of this function based on the definition of the UNICODE preprocessor constant. Mixing usage of the encoding-
neutral alias with code that not encoding-neutral can lead to mismatches that result in compilation or runtime errors. For
more information, see Conventions for Function Prototypes.

Requirements

Minimum suppor ted client Windows XP [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

 Header cryptuiapi.h

Librar y Cryptui.lib

DLL Cryptui.dll

See also
CRYPTUI_VIEWCERTIFICATE_STRUCT
 CryptUIDlgViewContext function (cryptuiapi.h)
7/2/2022 • 2 minutes to read • Edit Online

The Cr yptUIDlgViewContext function displays a certificate, CTL, or CRL context.

Syntax
BOOL CryptUIDlgViewContext(
[in] DWORD dwContextType,
[in] const void *pvContext,
[in] HWND hwnd,
[in] LPCWSTR pwszTitle,
[in] DWORD dwFlags,
[in] void *pvReserved
);

Parameters
[in] dwContextType

DWORD indicating whether pvContext is a pointer to a certificate, a CRL, or a CTL context as indicated in the
following table.

VA L UE M EA N IN G

PCCERT_CONTEXT
CERT_STORE_CERTIFICATE_CONTEXT

PCCRL_CONTEXT
CERT_STORE_CRL_CONTEXT

PCCTL_CONTEXT
CERT_STORE_CTL_CONTEXT

[in] pvContext

A pointer to a certificate, CRL, or CTL context to be displayed.

[in] hwnd

Handle of the window for the display. If NULL , the display defaults to the desktop window.
[in] pwszTitle

Display title string. If NULL , the default context type is used as the title.
[in] dwFlags

Currently not used and should be set to 0.

[in] pvReserved

Reserved for future use.

Return value
This function returns TRUE on success and FALSE on failure.

Requirements

Minimum suppor ted client Windows XP [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header cryptuiapi.h

Librar y Cryptui.lib

DLL Cryptui.dll

See also
CryptUIDlgSelectCertificateFromStore
 CryptUIWizDigitalSign function (cryptuiapi.h)
7/2/2022 • 2 minutes to read • Edit Online

[The Cr yptUIWizDigitalSign function is available for use in the operating systems specified in the
Requirements section. It may be altered or unavailable in subsequent versions.]
The Cr yptUIWizDigitalSign function digitally signs a document or BLOB. The document or BLOB can be
signed with or without user interaction.

Syntax
BOOL CryptUIWizDigitalSign(
[in] DWORD dwFlags,
[in, optional] HWND hwndParent,
[in, optional] LPCWSTR pwszWizardTitle,
[in] PCCRYPTUI_WIZ_DIGITAL_SIGN_INFO pDigitalSignInfo,
[out, optional] PCCRYPTUI_WIZ_DIGITAL_SIGN_CONTEXT *ppSignContext
);

Parameters
[in] dwFlags

Contains flags that modify the behavior of the function. This can be zero or the following value.

VA L UE M EA N IN G

This function will sign the document based on the

CRYPTUI_WIZ_NO_UI information in the CRYPTUI_WIZ_DIGITAL_SIGN_INFO
0x0001 structure pointed to by the pDigitalSignInfo parameter
without displaying any user interface. If this flag is not
specified, this function will display a wizard to guide the user
through the signing process.

[in, optional] hwndParent

The handle of the window to use as the parent of the dialog box that this function creates. This parameter is
ignored if the CRYPTUI_WIZ_NO_UI flag is set in dwFlags.
[in, optional] pwszWizardTitle

A pointer to a null-terminated Unicode string that contains the title to use in the dialog box that this function
creates. This parameter is ignored if the CRYPT_WIZ_NO_UI flag is set in dwFlags. If this parameter is NULL , a
default title is used.
[in] pDigitalSignInfo

A pointer to a CRYPTUI_WIZ_DIGITAL_SIGN_INFO structure that contains information about the signing process.
[out, optional] ppSignContext

A pointer to a CRYPTUI_WIZ_DIGITAL_SIGN_CONTEXT structure pointer that receives the signed BLOB. When
you have finished using this structure, you must free the memory by passing this pointer to the
CryptUIWizFreeDigitalSignContext function. This parameter can be NULL if the signed BLOB is not needed.
Return value
If the function succeeds, the function returns nonzero.
If the function fails, it returns zero.

Requirements

Minimum suppor ted client Windows XP [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header cryptuiapi.h

Librar y Cryptui.lib

DLL Cryptui.dll

See also
CRYPTUI_WIZ_DIGITAL_SIGN_CONTEXT
CRYPTUI_WIZ_DIGITAL_SIGN_INFO
CryptUIWizFreeDigitalSignContext
 CryptUIWizExport function (cryptuiapi.h)
7/2/2022 • 2 minutes to read • Edit Online

The Cr yptUIWizExpor t function exports a certificate, a certificate trust list (CTL), a certificate revocation list
(CRL), or a certificate store to a file. The export can be performed with or without user interaction.

Syntax
BOOL CryptUIWizExport(
[in] DWORD dwFlags,
[in] HWND hwndParent,
[in] LPCWSTR pwszWizardTitle,
[in] PCCRYPTUI_WIZ_EXPORT_INFO pExportInfo,
[in] void *pvoid
);

Parameters
[in] dwFlags

Contains flags that modify the behavior of the function. This can be zero or a combination of one or more of the
following values.

Note Except for CRYPTUI_WIZ_NO_UI , none of the following constants are defined in a published header file. To use these
constants, you must define them by using the specified values.

VA L UE M EA N IN G

This function will perform the export based on the

CRYPTUI_WIZ_NO_UI information in the CRYPTUI_WIZ_EXPORT_INFO structure
0x0001 pointed to by pExportInfo without displaying any user
interface. If this flag is not specified, this function will display
a wizard to guide the user through the export process.

Suppress all user interfaces generated by cryptographic

CRYPTUI_WIZ_IGNORE_NO_UI_FL AG_FOR_CSPS service providers (CSPs). This option can be overridden by
0x0002 the CRYPTUI_WIZ_NO_UI_EXCEPT_CSP option.

Suppress all user interfaces except those generated by CSPs.

CRYPTUI_WIZ_NO_UI_EXCEPT_CSP This option overrides the
0x0003 CRYPTUI_WIZ_IGNORE_NO_UI_FL AG_FOR_CSPS
option.

Skip the Expor t Private Key page and assume that the
CRYPTUI_WIZ_EXPORT_PRIVATE_KEY private key is to be exported.
0x0100
 Disable the Delete the private key check box in the
CRYPTUI_WIZ_EXPORT_NO_DELETE_PRIVATE_KEY Expor t File Format page.
0x0200

[in] hwndParent

The handle of the window to use as the parent of the dialog box that this function creates. This parameter is
ignored if the CRYPT_WIZ_NO_UI flag is set in dwFlags.
[in] pwszWizardTitle

A pointer to a null-terminated Unicode string that contains the title to use in the dialog box that this function
creates. This parameter is ignored if the CRYPT_WIZ_NO_UI flag is set in dwFlags.
[in] pExportInfo

A pointer to a CRYPTUI_WIZ_EXPORT_INFO structure that contains information about producing the export
wizard.
[in] pvoid

If the dwSubjectChoice member of the CRYPTUI_WIZ_EXPORT_INFO structure that pExportInfo references is

CRYPTUI_WIZ_EXPORT_CERT_CONTEXT , and if the CRYPTUI_WIZ_NO_UI flag is set in dwFlags, this
parameter is a pointer to a CRYPTUI_WIZ_EXPORT_CERTCONTEXT_INFO structure.
If the CRYPTUI_WIZ_NO_UI flag is not set in dwFlags, this parameter is optional and can be NULL . If this
parameter is not NULL , the CRYPTUI_WIZ_EXPORT_CERTCONTEXT_INFO structure contains the values that are
displayed to the user as the default choices.

Return value
If the function succeeds, the function returns nonzero.
If the function fails, it returns zero. For extended error information, call the GetLastError function.

Requirements

Minimum suppor ted client Windows XP [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header cryptuiapi.h

Librar y Cryptui.lib

DLL Cryptui.dll

See also
CRYPTUI_WIZ_EXPORT_CERTCONTEXT_INFO
CRYPTUI_WIZ_EXPORT_INFO
CryptUIWizImport
 CryptUIWizFreeDigitalSignContext function
(cryptuiapi.h)
7/2/2022 • 2 minutes to read • Edit Online

The Cr yptUIWizFreeDigitalSignContext function frees the CRYPTUI_WIZ_DIGITAL_SIGN_CONTEXT structure

allocated by the CryptUIWizDigitalSign function.

Syntax
BOOL CryptUIWizFreeDigitalSignContext(
[in] PCCRYPTUI_WIZ_DIGITAL_SIGN_CONTEXT pSignContext
);

Parameters
[in] pSignContext

A pointer to the CRYPTUI_WIZ_DIGITAL_SIGN_CONTEXT structure to be freed.

Return value
If the function succeeds, the function returns nonzero.
If the function fails, it returns zero.

Requirements

Minimum suppor ted client Windows XP [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header cryptuiapi.h

Librar y Cryptui.lib

DLL Cryptui.dll

See also
CRYPTUI_WIZ_DIGITAL_SIGN_CONTEXT
CryptUIWizDigitalSign
 CryptUIWizImport function (cryptuiapi.h)
7/2/2022 • 3 minutes to read • Edit Online

The function imports a certificate, a certificate trust list (CTL), a certificate revocation list (CRL), or a certificate
store to a certificate store. The import can be performed with or without user interaction.

Syntax
BOOL CryptUIWizImport(
[in] DWORD dwFlags,
[in] HWND hwndParent,
[in] LPCWSTR pwszWizardTitle,
[in] PCCRYPTUI_WIZ_IMPORT_SRC_INFO pImportSrc,
[in] HCERTSTORE hDestCertStore
);

Parameters
[in] dwFlags

Contains flags that modify the behavior of the function. This can be zero or a combination of one or more of the
following values.

Note Except for CRYPTUI_WIZ_NO_UI , none of the following constants are defined in a published header file. To use these
constants, you must define them by using the specified values.

VA L UE M EA N IN G

This function will perform the import based on the

CRYPTUI_WIZ_NO_UI information in the CRYPTUI_WIZ_IMPORT_SRC_INFO
0x0001 structure pointed to by pImportSrc into the store specified
by hDestCertStore without displaying any user interface. If
this flag is not specified, this function will display a wizard to
guide the user through the import process.
Beginning with Windows 8 and Windows Server 2012, if
you set this flag and are importing a certificate from a
PFX BLOB that was protected to an Active Directory
(AD) principal, and the current user, as part of that
principal, has permission to decrypt the password
embedded in the PFX packet, the importation will
succeed without requiring that a password be set in the
CRYPTUI_WIZ_IMPORT_SRC_INFO structure. For more
information about protecting PFX to an AD principal, see
the pvPara parameter and the
PKCS12_PROTECT_TO_DOMAIN_SIDS flag of the
PFXExportCertStoreEx function.

Suppress all user interfaces generated by cryptographic

CRYPTUI_WIZ_IGNORE_NO_UI_FL AG_FOR_CSPS service providers (CSPs). This option can be overridden by
0x0002 the CRYPTUI_WIZ_NO_UI_EXCEPT_CSP option.
 Suppress all user interfaces except those generated by CSPs.
CRYPTUI_WIZ_NO_UI_EXCEPT_CSP This option overrides the
0x0003 CRYPTUI_WIZ_IGNORE_NO_UI_FL AG_FOR_CSPS
option.

Allow certificates to be imported.

CRYPTUI_WIZ_IMPORT_ALLOW_CERT
0x00020000

Allow CRLs to be imported.

CRYPTUI_WIZ_IMPORT_ALLOW_CRL
0x00040000

Allow CTLs to be imported.

CRYPTUI_WIZ_IMPORT_ALLOW_CTL
0x00080000

Do not allow the user to change the destination certificate

CRYPTUI_WIZ_IMPORT_NO_CHANGE_DEST_STORE store represented by the hDestCertStore parameter.
0x00010000

Import the object to the certificate store for the local

CRYPTUI_WIZ_IMPORT_TO_LOCALMACHINE computer. This applies only to Personal Information
0x00100000 Exchange (PFX) imports.

Import the object to the certificate store for the current user.
CRYPTUI_WIZ_IMPORT_TO_CURRENTUSER This applies only to PFX imports.
0x00200000

Import the object to a remote certificate store. Set this flag if

CRYPTUI_WIZ_IMPORT_REMOTE_DEST_STORE the hDestCertStore parameter represents a remote
0x00400000 certificate store.

[in] hwndParent

The handle of the window to use as the parent of the dialog box that this function creates. This parameter is
ignored if the CRYPTUI_WIZ_NO_UI flag is set in dwFlags.
[in] pwszWizardTitle

A pointer to a null-terminated Unicode string that contains the title to use in the dialog box that this function
creates. This parameter is ignored if the CRYPTUI_WIZ_NO_UI flag is set in dwFlags.
[in] pImportSrc

A pointer to a CRYPTUI_WIZ_IMPORT_SRC_INFO structure that contains information about the object to import.
This parameter is required if CRYPTUI_WIZ_NO_UI is set in dwFlags and is optional otherwise.
[in] hDestCertStore

A handle to the certificate store to import to. If this parameter is NULL and the CRYPTUI_WIZ_NO_UI flag is
not set in dwFlags, the wizard will prompt the user to select a certificate store.

Return value
If the function succeeds, the function returns nonzero.
If the function fails, it returns zero. For extended error information, call the GetLastError function.

Remarks
If none of following three flags are set in dwFlags, import of any type of content is allowed:
CRYPTUI_WIZ_IMPORT_ALLOW_CERT
CRYPTUI_WIZ_IMPORT_ALLOW_CRL
CRYPTUI_WIZ_IMPORT_ALLOW_CTL
The CRYPTUI_WIZ_IMPORT_TO_LOCALMACHINE and CRYPTUI_WIZ_IMPORT_TO_CURRENTUSER flags are
used to force the content of a PFX BLOB into either the local machine store or the current user store. If neither of
these flags are set and hDestCertStore is NULL :
The private key in the PFX BLOB will be forced to be imported into the current user store.
And if CRYPTUI_WIZ_NO_UI is not set, the wizard prompts the user to select a certificate store from
among the current user certificate stores.

Requirements

Minimum suppor ted client Windows XP [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header cryptuiapi.h

Librar y Cryptui.lib

DLL Cryptui.dll

See also
CRYPTUI_WIZ_IMPORT_SRC_INFO
CryptUIWizExport
 PFNCFILTERPROC callback function (cryptuiapi.h)
7/2/2022 • 2 minutes to read • Edit Online

The PFNCFILTERPROC function is an application-defined callback function that filters the certificates that
appear in the digital signature wizard that are displayed by the CryptUIWizDigitalSign function.

Syntax
PFNCFILTERPROC Pfncfilterproc;

BOOL Pfncfilterproc(
[in] PCCERT_CONTEXT pCertContext,
[in] BOOL *pfInitialSelectedCert,
[in] void *pvCallbackData
)
{...}

Parameters
[in] pCertContext

A pointer to a CERT_CONTEXT structure that contains the certificate to filter.

[in] pfInitialSelectedCert

A Boolean value that specifies whether the certificate contained in the CERT_CONTEXT structure pointed to by
the pCertContext parameter should be initially selected in the dialog box. This parameter is used only if the filter
process returns TRUE .
[in] pvCallbackData

A pointer to user-defined data.

Return value
A Boolean value that specifies whether the certificate contained in the CERT_CONTEXT structure pointed to by
the pCertContext parameter should be displayed in the digital signature wizard.

Requirements

Minimum suppor ted client Windows XP [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header cryptuiapi.h
 cryptxml.h header
7/2/2022 • 3 minutes to read • Edit Online

This header is used by Security and Identity. For more information, see:
Security and Identity
cryptxml.h contains the following programming interfaces:

Functions

CryptXmlAddObject

Adds the Object element to the Signature in the Document Context opened for encoding.

CryptXmlClose

Closes a cryptographic XML object handle.

CryptXmlCreateReference

Creates a reference to an XML signature.

CryptXmlDigestReference

Is used by an application to digest the resolved reference. This function applies transforms before updating the digest.

CryptXmlEncode

Encodes signature data by using the supplied XML writer callback function.

CryptXmlGetAlgorithmInfo

Decodes the CRYPT_XML_ALGORITHM structure and returns information about the algorithm.

CryptXmlGetDocContext

Returns the document context specified by the supplied handle.

CryptXmlGetReference

Returns the Reference element specified by the supplied handle.

CryptXmlGetSignature

Returns an XML Signature element.

CryptXmlGetStatus

Returns a CRYPT_XML_STATUS structure that contains status information about the object specified by the supplied handle.
 CryptXmlGetTransforms

Returns information about the default transform chain engine.

CryptXmlImportPublicKey

Imports the public key specified by the supplied handle.

CryptXmlOpenToDecode

Opens an XML digital signature to decode and returns the handle of the document context that encapsulates a
CRYPT_XML_SIGNATURE structure. The document context can include one or more Signature elements.

CryptXmlOpenToEncode

Opens an XML digital signature to encode and returns a handle of the opened Signature element. The handle encapsulates a
document context with a single CRYPT_XML_SIGNATURE structure and remains open until the CryptXmlClose function is
called.

CryptXmlSetHMACSecret

Sets the HMAC secret on the handle before calling the CryptXmlSign or CryptXmlVerify function.

CryptXmlSign

Creates a cryptographic signature of a SignedInfo element.

CryptXmlVerifySignature

Performs a cryptographic signature validation of a SignedInfo element.

Callback functions

CryptXmlDllCloseDigest

Frees the CRYPT_XML_DIGEST allocated by the CryptXmlDllCreateDigest function.

CryptXmlDllCreateDigest

Creates a digest object for the specified method.

CryptXmlDllCreateKey

Parses the KeyValue element and creates a Cryptography API:_Next Generation (CNG) BCrypt key handle to verify a signature.

CryptXmlDllDigestData

Puts data into the digest.

CryptXmlDllEncodeAlgorithm

Encodes SignatureMethod or DigestMethod elements for agile algorithms with default parameters.
 CryptXmlDllEncodeKeyValue

Encodes a KeyValue element.

CryptXmlDllFinalizeDigest

Retrieves the digest value.

CryptXmlDllGetAlgorithmInfo

Decodes the XML algorithm and returns information about the algorithm.

CryptXmlDllGetInterface

Retrieves a pointer to the cryptographic extension functions for the specified algorithm.

CryptXmlDllSignData

Signs data.

CryptXmlDllVerifySignature

Verifies a signature.

PFN_CRYPT_XML_CREATE_TRANSFORM

Creates a transform for a specified data provider.

PFN_CRYPT_XML_DATA_PROVIDER_CLOSE

Releases the data provider.

PFN_CRYPT_XML_DATA_PROVIDER_READ

Reads XML data.

PFN_CRYPT_XML_ENUM_ALG_INFO

Enumerates predefined and registered CRYPT_XML_ALGORITHM_INFO entries.

PFN_CRYPT_XML_WRITE_CALLBACK

Writes XML data.

Structures

CRYPT_XML_ALGORITHM

Specifies the algorithm used to sign or transform the message.

CRYPT_XML_ALGORITHM_INFO

Contains algorithm information.

CRYPT_XML_BLOB

Contains an arbitrary array of bytes.

CRYPT_XML_CRYPTOGRAPHIC_INTERFACE

Exposes the implemented CryptXML functions.

CRYPT_XML_DATA_BLOB

Contains XML encoded data.

CRYPT_XML_DATA_PROVIDER

Specifies the interface to the XML data provider.

CRYPT_XML_DOC_CTXT

Defines document context information.

CRYPT_XML_ISSUER_SERIAL

Contains an X.509 issued distinguished name�serial number pair.

CRYPT_XML_KEY_DSA_KEY_VALUE

Defines a Digital Signature Algorithm (DSA) key value. The CRYPT_XML_KEY_DSA_KEY_VALUE structure is used as an element
of the key value union in the CRYPT_XML_KEY_VALUE structure.

CRYPT_XML_KEY_ECDSA_KEY_VALUE

Defines an Elliptic Curve Digital Signature Algorithm (ECDSA) key value. The CRYPT_XML_KEY_ECDSA_KEY_VALUE structure is
used as an element of the key value union in the CRYPT_XML_KEY_VALUE structure.

CRYPT_XML_KEY_INFO

Encapsulates key information data.

CRYPT_XML_KEY_INFO_ITEM

Encapsulates key information data that corresponds to a KeyInfo element. The KeyInfo element enables the recipient to obtain
the key needed to validate the signature.

CRYPT_XML_KEY_RSA_KEY_VALUE

Defines an RSA key value. The CRYPT_XML_KEY_RSA_KEY_VALUE structure is used as element of the key value union in the
CRYPT_XML_KEY_VALUE structure.

CRYPT_XML_KEY_VALUE

Contains a single public key that may be useful in validating the signature.
 CRYPT_XML_KEYINFO_PARAM

Is used by the CryptXmlSign function to specify the members of the KeyInfo element to be encoded.

CRYPT_XML_OBJECT

Describes an Object element in the signature.

CRYPT_XML_PROPERTY

Contains information about a CryptXML property.

CRYPT_XML_REFERENCE

Contains information used to populate the Reference element.

CRYPT_XML_REFERENCES

Defines an array of CRYPT_XML_REFERENCE structures.

CRYPT_XML_SIGNATURE

Contains information used to populate the Signature element.

CRYPT_XML_SIGNED_INFO

Describes an XML encoded SignedInfo element.

CRYPT_XML_STATUS

Returns information about the signature validation status, summary status information about a SignedInfo element, or
summary status information about an array of Reference elements.

CRYPT_XML_TRANSFORM_CHAIN_CONFIG

Contains application defined transforms that are allowed for use in the XML digital signature.

CRYPT_XML_TRANSFORM_INFO

Contains information that is used when applying the data transform.

CRYPT_XML_X509DATA

Represents the sequence of choices in the X509Data element.

CRYPT_XML_X509DATA_ITEM

Represents X.509 data that is to be encoded in an X509Data named element.

Enumerations
CRYPT_XML_CHARSET

Used to specify the character set used in the XML.

CRYPT_XML_KEYINFO_SPEC

Specifies values for the dwKeyInfoSpec parameter in the CryptXmlSign function.

CRYPT_XML_PROPERTY_ID

Specifies the type and usage of the XML property.

 CRYPT_XML_ALGORITHM structure (cryptxml.h)
7/2/2022 • 2 minutes to read • Edit Online

The CRYPT_XML_ALGORITHM structure specifies the algorithm used to sign or transform the message.

Syntax
typedef struct _CRYPT_XML_ALGORITHM {
ULONG cbSize;
LPCWSTR wszAlgorithm;
CRYPT_XML_BLOB Encoded;
} CRYPT_XML_ALGORITHM, *PCRYPT_XML_ALGORITHM;

Members
cbSize

The size, in bytes, of this structure.

wszAlgorithm

A pointer to a null-terminated Unicode string that contains the Algorithm attribute. When the Encoded
member contains an element that is proved by an application, this member is set to NULL .XML
Encoded

Optional. The XML encoded element. This member is set when an element tag is present in the XML signature.

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Header cryptxml.h

See also
Digital Signature Cryptographic Algorithms
 CRYPT_XML_ALGORITHM_INFO structure
(cryptxml.h)
7/2/2022 • 2 minutes to read • Edit Online

The CRYPT_XML_ALGORITHM_INFO structure contains algorithm information.

Syntax
typedef struct _CRYPT_XML_ALGORITHM_INFO {
DWORD cbSize;
WCHAR *wszAlgorithmURI;
WCHAR *wszName;
DWORD dwGroupId;
WCHAR *wszCNGAlgid;
WCHAR *wszCNGExtraAlgid;
DWORD dwSignFlags;
DWORD dwVerifyFlags;
void *pvPaddingInfo;
void *pvExtraInfo;
} CRYPT_XML_ALGORITHM_INFO, *PCRYPT_XML_ALGORITHM_INFO;

Members
cbSize

The size, in bytes, of this structure.

wszAlgorithmURI

A pointer to a null-terminated Unicode string that contains the URI associated with the attribute of the
SignatureMethod or DigestMethod element of the XML signature.
wszName

Optional. A pointer to a null-terminated Unicode string that contains the display name of the algorithm.
dwGroupId

A DWORD value that specifies the group type to which the algorithm belongs. This member can be one of the
following values.

VA L UE M EA N IN G

Hash algorithms
CRYPT_XML_GROUP_ID_HASH
1

Signature algorithms
CRYPT_XML_GROUP_ID_SIGN
2

wszCNGAlgid
A pointer to a null-terminated Unicode string that contains an algorithm identifier string that is passed to
Cryptography API: Next Generation (CNG) functions. CNG functions use algorithm identifier strings, such as
L"SHA1", instead of the ALG_ID data type constants, such as CALG_SHA1.

Note BCrypt* and NCrypt* functions are defined in Bcrypt.h and Ncrypt.h.

wszCNGExtraAlgid

A pointer to a null-terminated Unicode string that contains an extra algorithm string, other than the string in the
pwszCNGAlgid member, that is passed to CNG functions.

Note BCrypt* and NCrypt* functions are defined in Bcrypt.h and Ncrypt.h.

dwSignFlags

A DWORD value that contains flag values to be passed to the NCryptSignHash function.
dwVerifyFlags

A DWORD value that is passed to the BCryptVerifySignature function.

pvPaddingInfo

A pointer to a structure that contains padding information to be passed to the NCryptSignHash or

BCryptVerifySignature function. The actual type of structure this member points to depends on the value of the
dwGroupId member.
pvExtraInfo

Optional. A pointer to a structure that contains extra information that can be passed to the CNG functions.

Note BCrypt* and NCrypt* functions are defined in Bcrypt.h and Ncrypt.h.

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Header cryptxml.h

See also
Digital Signature Cryptographic Algorithms
 CRYPT_XML_BLOB structure (cryptxml.h)
7/2/2022 • 2 minutes to read • Edit Online

The CRYPT_XML_BLOB structure contains an arbitrary array of bytes.

Syntax
typedef struct _CRYPT_XML_BLOB {
CRYPT_XML_CHARSET dwCharset;
ULONG cbData;
BYTE *pbData;
} CRYPT_XML_BLOB, *PCRYPT_XML_BLOB;

Members
dwCharset

Specifies the character set used to encode the signature.

cbData

The size, in bytes, of this structure.

Range: 0–CRYPT_XML_BLOB_MAX) (value is 0x7FFFFFF8)
pbData

A pointer to encoded XML data.

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Header cryptxml.h
 CRYPT_XML_CHARSET enumeration (cryptxml.h)
7/2/2022 • 2 minutes to read • Edit Online

The CRYPT_XML_CHARSET enumeration is used to specify the character set used in the XML.

Syntax
typedef enum {
CRYPT_XML_CHARSET_AUTO = 0,
CRYPT_XML_CHARSET_UTF8 = 1,
CRYPT_XML_CHARSET_UTF16LE = 2,
CRYPT_XML_CHARSET_UTF16BE = 3
} CRYPT_XML_CHARSET;

Constants

CRYPT_XML_CHARSET_AUTO
Value: 0
This value is only supported in the CryptXmlOpenToDecode function. The encoded XML character set is determined by the
parser and is based on the XML declaration or the best guess on the characters.

CRYPT_XML_CHARSET_UTF8
Value: 1
Specifies the UTF-8 character set.

CRYPT_XML_CHARSET_UTF16LE
Value: 2
Specifies the UTF-16 little-endian character set.

CRYPT_XML_CHARSET_UTF16BE
Value: 3
Specifies the UTF-16 big-endian character set.

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Header cryptxml.h
 CRYPT_XML_CRYPTOGRAPHIC_INTERFACE
structure (cryptxml.h)
7/2/2022 • 2 minutes to read • Edit Online

The CRYPT_XML_CRYPTOGRAPHIC_INTERFACE structure is passed to the CryptXmlDllGetInterface function

pointer to expose the implemented CryptXML functions.

Syntax
typedef struct _CRYPT_XML_CRYPTOGRAPHIC_INTERFACE {
ULONG cbSize;
CryptXmlDllEncodeAlgorithm fpCryptXmlEncodeAlgorithm;
CryptXmlDllCreateDigest fpCryptXmlCreateDigest;
CryptXmlDllDigestData fpCryptXmlDigestData;
CryptXmlDllFinalizeDigest fpCryptXmlFinalizeDigest;
CryptXmlDllCloseDigest fpCryptXmlCloseDigest;
CryptXmlDllSignData fpCryptXmlSignData;
CryptXmlDllVerifySignature fpCryptXmlVerifySignature;
CryptXmlDllGetAlgorithmInfo fpCryptXmlGetAlgorithmInfo;
} CRYPT_XML_CRYPTOGRAPHIC_INTERFACE, *PCRYPT_XML_CRYPTO_PROVIDER, *PCRYPT_XML_CRYPTOGRAPHIC_INTERFACE;

Members
cbSize

The size, in bytes, of this structure.

fpCryptXmlEncodeAlgorithm

A pointer to the implementation of the CryptXmlDllEncodeAlgorithm function.

fpCryptXmlCreateDigest

A pointer to the implementation of the CryptXmlDllCreateDigest function.

fpCryptXmlDigestData

A pointer to the implementation of the CryptXmlDllDigestData function.

fpCryptXmlFinalizeDigest

A pointer to the implementation of the CryptXmlDllFinalizeDigest function.

fpCryptXmlCloseDigest

A pointer to the implementation of the CryptXmlDllCloseDigest function.

fpCryptXmlSignData

A pointer to the implementation of the CryptXmlDllSignData function.

fpCryptXmlVerifySignature

A pointer to the implementation of the CryptXmlDllVerifySignature function.

fpCryptXmlGetAlgorithmInfo
A pointer to the implementation of the CryptXmlDllGetAlgorithmInfo function.

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Header cryptxml.h
 CRYPT_XML_DATA_BLOB structure (cryptxml.h)
7/2/2022 • 2 minutes to read • Edit Online

The CRYPT_XML_DATA_BLOB structure contains XML encoded data.

Syntax
typedef struct _CRYPT_XML_DATA_BLOB {
ULONG cbData;
BYTE *pbData;
} CRYPT_XML_DATA_BLOB, *PCRYPT_XML_DATA_BLOB;

Members
cbData

The size, in bytes, of the data buffer pointed to by the pbData member.
pbData

A pointer to the XML data. The maximum length in the buffer cannot exceed CRYPT_XML_BLOB_MAX bytes.

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Header cryptxml.h
 CRYPT_XML_DATA_PROVIDER structure
(cryptxml.h)
7/2/2022 • 2 minutes to read • Edit Online

The CRYPT_XML_DATA_PROVIDER structure specifies the interface to the XML data provider.

Syntax
typedef struct _CRYPT_XML_DATA_PROVIDER {
void *pvCallbackState;
ULONG cbBufferSize;
PFN_CRYPT_XML_DATA_PROVIDER_READ pfnRead;
PFN_CRYPT_XML_DATA_PROVIDER_CLOSE pfnClose;
} CRYPT_XML_DATA_PROVIDER, *PCRYPT_XML_DATA_PROVIDER;

Members
pvCallbackState

An application-defined argument that is passed to the pfnRead and pfnClose callback functions.
cbBufferSize

The size, in bytes, of the data provider's buffer. The size can be zero if the size does not matter or if the size
cannot be determined by the provider. This value is used by a caller of pfnRead to determine the necessary size
of the receiving buffer.
pfnRead

A pointer to a PFN_CRYPT_XML_DATA_PROVIDER_READ callback function used to read data.

pfnClose

A pointer to a PFN_CRYPT_XML_DATA_PROVIDER_CLOSE callback function used to release the data provider.

When you have finished using the data provider, you must release it.

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Header cryptxml.h
 CRYPT_XML_DOC_CTXT structure (cryptxml.h)
7/2/2022 • 2 minutes to read • Edit Online

The CRYPT_XML_DOC_CTXT structure defines document context information.

Syntax
typedef struct _CRYPT_XML_DOC_CTXT {
ULONG cbSize;
HCRYPTXML hDocCtxt;
CRYPT_XML_TRANSFORM_CHAIN_CONFIG *pTransformsConfig;
ULONG cSignature;
PCRYPT_XML_SIGNATURE *rgpSignature;
} CRYPT_XML_DOC_CTXT, *PCRYPT_XML_DOC_CTXT;

Members
cbSize

The size, in bytes, of this structure.

hDocCtxt

The handle of the document context.

pTransformsConfig

A pointer to a CRYPT_XML_TRANSFORM_CHAIN_CONFIG structure that contains information about the

transform chain engine.
cSignature

The number of elements in the array pointed to by the rgpSignature member.

rgpSignature

A pointer to an array of CRYPT_XML_SIGNATURE structures that contain XML signature information.

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Header cryptxml.h
 CRYPT_XML_ISSUER_SERIAL structure (cryptxml.h)
7/2/2022 • 2 minutes to read • Edit Online

The CRYPT_XML_ISSUER_SERIAL structure contains an X.509 issued distinguished name–serial number pair.

Syntax
typedef struct _CRYPT_XML_ISSUER_SERIAL {
LPCWSTR wszIssuer;
LPCWSTR wszSerial;
} CRYPT_XML_ISSUER_SERIAL;

Members
wszIssuer

A pointer to a null-terminated wide character string that contains the issuer of the certificate.
wszSerial

A pointer to a null-terminated wide character string that contains the serial number of the certificate.

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Header cryptxml.h
 CRYPT_XML_KEY_DSA_KEY_VALUE structure
(cryptxml.h)
7/2/2022 • 2 minutes to read • Edit Online

The CRYPT_XML_KEY_DSA_KEY_VALUE structure defines a Digital Signature Algorithm (DSA) key value. The
CRYPT_XML_KEY_DSA_KEY_VALUE structure is used as an element of the key value union in the
CRYPT_XML_KEY_VALUE structure.

Syntax
typedef struct _CRYPT_XML_KEY_DSA_KEY_VALUE {
CRYPT_XML_DATA_BLOB P;
CRYPT_XML_DATA_BLOB Q;
CRYPT_XML_DATA_BLOB G;
CRYPT_XML_DATA_BLOB Y;
CRYPT_XML_DATA_BLOB J;
CRYPT_XML_DATA_BLOB Seed;
CRYPT_XML_DATA_BLOB Counter;
} CRYPT_XML_KEY_DSA_KEY_VALUE;

Members
P

Defines the P part of the DSA key.

Q

Defines the Q part of the DSA key.

G

Defines the G part of the DSA key.

Y

Defines the Y part of the DSA key.

J

Defines the J part of the DSA key.

Seed

The seed value, in big-endian format.

Counter

The count value, in big-endian format.

Requirements
Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Header cryptxml.h
 CRYPT_XML_KEY_ECDSA_KEY_VALUE structure
(cryptxml.h)
7/2/2022 • 2 minutes to read • Edit Online

The CRYPT_XML_KEY_ECDSA_KEY_VALUE structure defines an Elliptic Curve Digital Signature Algorithm

(ECDSA) key value. The CRYPT_XML_KEY_ECDSA_KEY_VALUE structure is used as an element of the key
value union in the CRYPT_XML_KEY_VALUE structure.

Syntax
typedef struct _CRYPT_XML_KEY_ECDSA_KEY_VALUE {
LPCWSTR wszNamedCurve;
CRYPT_XML_DATA_BLOB X;
CRYPT_XML_DATA_BLOB Y;
CRYPT_XML_BLOB ExplicitPara;
} CRYPT_XML_KEY_ECDSA_KEY_VALUE;

Members
wszNamedCurve

A pointer to a null-terminated Unicode string that contains the object identifier (OID) of the named curve.
X

Defines the X value of an ECDSA curve.

Y

Defines the Y value of an ECDSA curve.

ExplicitPara

A CRYPT_XML_BLOB value that defines the encoded parameters of an ECDSA curve.

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Header cryptxml.h
 CRYPT_XML_KEY_INFO structure (cryptxml.h)
7/2/2022 • 2 minutes to read • Edit Online

The CRYPT_XML_KEY_INFO structure encapsulates key information data.

Syntax
typedef struct _CRYPT_XML_KEY_INFO {
ULONG cbSize;
LPCWSTR wszId;
UINT cKeyInfo;
CRYPT_XML_KEY_INFO_ITEM *rgKeyInfo;
BCRYPT_KEY_HANDLE hVerifyKey;
} CRYPT_XML_KEY_INFO, *PCRYPT_XML_KEY_INFO;

Members
cbSize

The size, in bytes, of this structure.

wszId

A pointer to a null-terminated wide character string that specifies the value of the ID attribute of the key
information element.
cKeyInfo

The number of items in the array pointed to by the rgKeyInfo member.

rgKeyInfo

A pointer to an array of CRYPT_XML_KEY_INFO_ITEM structures that contain key information.

hVerifyKey

Optional. The handle of data derived from the first key value.

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Header cryptxml.h
 CRYPT_XML_KEY_INFO_ITEM structure (cryptxml.h)
7/2/2022 • 2 minutes to read • Edit Online

The CRYPT_XML_KEY_INFO_ITEM structure encapsulates key information data that corresponds to a KeyInfo
element. The KeyInfo element enables the recipient to obtain the key needed to validate the signature.

Syntax
typedef struct _CRYPT_XML_KEY_INFO_ITEM {
DWORD dwType;
union {
LPCWSTR wszKeyName;
CRYPT_XML_KEY_VALUE KeyValue;
CRYPT_XML_BLOB RetrievalMethod;
CRYPT_XML_X509DATA X509Data;
CRYPT_XML_BLOB Custom;
};
} CRYPT_XML_KEY_INFO_ITEM;

Members
dwType

Specifies the key information type encapsulated in this structure.

This member can be one of the following values.

VA L UE M EA N IN G

The structure specifies a key name.

CRYPT_XML_KEYINFO_TYPE_KEYNAME
0x00000001

The structure specifies the key value.

CRYPT_XML_KEYINFO_TYPE_KEYVALUE
0x00000002

The structure specifies an XML encoded element that

CRYPT_XML_KEYINFO_TYPE_RETRIEVAL contains the key retrieval method.
0x00000003

The structure specifies X.509 data that contains the key

CRYPT_XML_KEYINFO_TYPE_X509DATA information.
0x00000004

The structure specifies user defined information about the

CRYPT_XML_KEYINFO_TYPE_CUSTOM key information.
0x00000005

wszKeyName

A pointer to a null-terminated wide character string that contains the name of the key to retrieve.
KeyValue

A CRYPT_XML_KEY_VALUE structure that contains the key value.

RetrievalMethod

A CRYPT_XML_BLOB structure that contains XML encoded information about the key retrieval method.
X509Data

A CRYPT_XML_X509DATA structure that contains X.509 data that contains the key.
Custom

A CRYPT_XML_BLOB structure that contains user defined key information.

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Header cryptxml.h
 CRYPT_XML_KEY_RSA_KEY_VALUE structure
(cryptxml.h)
7/2/2022 • 2 minutes to read • Edit Online

The CRYPT_XML_KEY_RSA_KEY_VALUE structure defines an RSA key value. The

CRYPT_XML_KEY_RSA_KEY_VALUE structure is used as element of the key value union in the
CRYPT_XML_KEY_VALUE structure.

Syntax
typedef struct _CRYPT_XML_KEY_RSA_KEY_VALUE {
CRYPT_XML_DATA_BLOB Modulus;
CRYPT_XML_DATA_BLOB Exponent;
} CRYPT_XML_KEY_RSA_KEY_VALUE;

Members
Modulus

A CRYPT_XML_DATA_BLOB structure that contains the public key modulus data.

Exponent

A CRYPT_XML_DATA_BLOB structure that contains the public key exponent data.

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Header cryptxml.h
 CRYPT_XML_KEY_VALUE structure (cryptxml.h)
7/2/2022 • 2 minutes to read • Edit Online

The CRYPT_XML_KEY_VALUE structure contains a single public key that may be useful in validating the
signature.

Syntax
typedef struct _CRYPT_XML_KEY_VALUE {
DWORD dwType;
union {
CRYPT_XML_KEY_DSA_KEY_VALUE DSAKeyValue;
CRYPT_XML_KEY_RSA_KEY_VALUE RSAKeyValue;
CRYPT_XML_KEY_ECDSA_KEY_VALUE ECDSAKeyValue;
CRYPT_XML_BLOB Custom;
};
} CRYPT_XML_KEY_VALUE;

Members
dwType

Specifies the key value type.

This member can be one of the following values.

VA L UE M EA N IN G

The key is a DSA key.

CRYPT_XML_KEY_VALUE_TYPE_DSA
0x00000001

The key is an RSA key.

CRYPT_XML_KEY_VALUE_TYPE_RSA
0x00000002

The key is an Elliptic Curve Digital Signature Algorithm

CRYPT_XML_KEY_VALUE_TYPE_ECDSA (ECDSA) key.
0x00000003

The key is a custom key type.

CRYPT_XML_KEY_VALUE_TYPE_CUSTOM
0x00000004

DSAKeyValue

A CRYPT_XML_KEY_DSA_KEY_VALUE structure that contains Digital Signature Algorithm (DSA) key data.
RSAKeyValue

A CRYPT_XML_KEY_RSA_KEY_VALUE structure that contains RSA key data.

ECDSAKeyValue
A CRYPT_XML_KEY_ECDSA_KEY_VALUE structure that contains ECDSA key data.
Custom

A CRYPT_XML_BLOB structure that contains custom key data.

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Header cryptxml.h
 CRYPT_XML_KEYINFO_PARAM structure
(cryptxml.h)
7/2/2022 • 2 minutes to read • Edit Online

The CRYPT_XML_KEYINFO_PARAM structure is used by the CryptXmlSign function to specify the members of
the KeyInfo element to be encoded.

Syntax
typedef struct _CRYPT_XML_KEYINFO_PARAM {
LPCWSTR wszId;
LPCWSTR wszKeyName;
CERT_BLOB SKI;
LPCWSTR wszSubjectName;
ULONG cCertificate;
CERT_BLOB *rgCertificate;
ULONG cCRL;
CERT_BLOB *rgCRL;
} CRYPT_XML_KEYINFO_PARAM;

Members
wszId

A pointer to a null-terminated wide character string that contains the Id attribute of the KeyInfo element.
wszKeyName

A pointer to a null-terminated wide character string that contains the value in the KeyName element.
SKI

A CERT_BLOB structure that contains the value of the X509SKI element.

wszSubjectName

A pointer to a null-terminated wide character string that contains the value of the X509SubjectName element.
cCertificate

The number of elements in the array pointed to by the rgCer tificate member.
rgCertificate

A pointer to an array of CERT_BLOB structures that are used to populate the X509Cer tificate elements.
cCRL

The number of elements in the array pointed to by the rgCRL member.

rgCRL

A pointer to an array of CERT_BLOB structures that are used to populate the X509CRL elements.

Requirements
Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Header cryptxml.h
 CRYPT_XML_KEYINFO_SPEC enumeration
(cryptxml.h)
7/2/2022 • 2 minutes to read • Edit Online

The CRYPT_XML_KEYINFO_SPEC enumeration specifies values for the dwKeyInfoSpec parameter in the
CryptXmlSign function.

Syntax
typedef enum {
CRYPT_XML_KEYINFO_SPEC_NONE = 0,
CRYPT_XML_KEYINFO_SPEC_ENCODED = 1,
CRYPT_XML_KEYINFO_SPEC_PARAM = 2
} CRYPT_XML_KEYINFO_SPEC;

Constants

CRYPT_XML_KEYINFO_SPEC_NONE
Value: 0
The value of the KeyInfo member in the CRYPT_XML_SIGNATURE structure is null.

CRYPT_XML_KEYINFO_SPEC_ENCODED
Value: 1
The value of the encoded CRYPT_XML_KEY_INFO structure is specified in a CRYPT_XML_BLOB structure pointed to in the
pvKeyInfoSpec parameter.

CRYPT_XML_KEYINFO_SPEC_PARAM
Value: 2
The members of the CRYPT_XML_KEY_INFO structure to be encoded are specified in a CRYPT_XML_KEYINFO_PARAM
structure pointed by the pvKeyInfoSpec parameter.

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Header cryptxml.h
 CRYPT_XML_OBJECT structure (cryptxml.h)
7/2/2022 • 2 minutes to read • Edit Online

The CRYPT_XML_OBJECT structure describes an Object element in the signature.

Syntax
typedef struct _CRYPT_XML_OBJECT {
ULONG cbSize;
HCRYPTXML hObject;
LPCWSTR wszId;
LPCWSTR wszMimeType;
LPCWSTR wszEncoding;
CRYPT_XML_REFERENCES Manifest;
CRYPT_XML_BLOB Encoded;
} CRYPT_XML_OBJECT, *PCRYPT_XML_OBJECT;

Members
cbSize

The size, in bytes, of this structure.

hObject

The handle of the object.

wszId

Optional. A pointer to a null-terminated wide character string that contains the value of the unique identifier
attribute of the Object element.
wszMimeType

Optional. A pointer to a null-terminated wide character string that contains the value of the MIME-type attribute
of the Object element.
wszEncoding

Optional. A pointer to a null-terminated wide character string that contains the value of the encoding method
attribute of the Object element.
Manifest

Optional. A CRYPT_XML_REFERENCES structure that specifies an array of references.

Encoded

Optional. A CRYPT_XML_BLOB structure that contains the XML part of the entire Object element.

Note This field is empty when the Object element does not contain any elements. Applications can use the
CRYPT_XML_FL AG_ALWAYS_RETURN_ENCODED_OBJECT flag to always receive an encoded Object element.
Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Header cryptxml.h
 CRYPT_XML_PROPERTY structure (cryptxml.h)
7/2/2022 • 2 minutes to read • Edit Online

The CRYPT_XML_PROPERTY structure contains information about a CryptXML property.

Syntax
typedef struct _CRYPT_XML_PROPERTY {
CRYPT_XML_PROPERTY_ID dwPropId;
const void *pvValue;
ULONG cbValue;
} CRYPT_XML_PROPERTY, *PCRYPT_XML_PROPERTY;

Members
dwPropId

A value of the CRYPT_XML_PROPERTY_ID enumeration that specifies the property type.

pvValue

A pointer to a buffer that contains the property value.

cbValue

The size, in bytes, of the property value buffer pointed to by the pvValue member.

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Header cryptxml.h
 CRYPT_XML_PROPERTY_ID enumeration
(cryptxml.h)
7/2/2022 • 2 minutes to read • Edit Online

The CRYPT_XML_PROPERTY_ID enumeration specifies the type and usage of the XML property.

Syntax
typedef enum {
CRYPT_XML_PROPERTY_MAX_HEAP_SIZE = 1,
CRYPT_XML_PROPERTY_SIGNATURE_LOCATION = 2,
CRYPT_XML_PROPERTY_MAX_SIGNATURES = 3,
CRYPT_XML_PROPERTY_DOC_DECLARATION = 4,
CRYPT_XML_PROPERTY_XML_OUTPUT_CHARSET = 5
} CRYPT_XML_PROPERTY_ID;

Constants

CRYPT_XML_PROPERTY_MAX_HEAP_SIZE
Value: 1
Specifies the maximum heap size, in bytes, that the XML layer can use.
This property is applied to intermediate buffers used to parse or construct XML parts.
By default, the limit is equal to CRYPT_XML_BLOB_MAX .

CRYPT_XML_PROPERTY_SIGNATURE_LOCATION
Value: 2
Specifies the location in the XML document where the signature is to be created.

The following formats are supported:

#id

The Id attribute of the element to insert the signature.

/a/b/c

The absolute path of the element to insert the signature.

 CRYPT_XML_PROPERTY_MAX_SIGNATURES
Value: 3
Specifies the maximum number of Signature elements when parsing an XML document.
This property overrides the default CRYPT_XML_SIGNATURES_MAX value.

CRYPT_XML_PROPERTY_DOC_DECLARATION
Value: 4
Specifies whether to write an XML document declaration. This property is used with the
CryptXmlEncode function. The default property is TRUE .

CRYPT_XML_PROPERTY_XML_OUTPUT_CHARSET
Value: 5
Specifies an encoding character set of XML fragments for custom elements. This property is used with the
CryptXmlOpenToDecode function.
The default character set is inherited from the opened document.

Remarks
If a property value is defined as a pointer to data, then the pointer must be valid for the entire period of the
signature operation.

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Header cryptxml.h
 CRYPT_XML_REFERENCE structure (cryptxml.h)
7/2/2022 • 2 minutes to read • Edit Online

The CRYPT_XML_REFERENCE structure contains information used to populate the Reference element.

Syntax
typedef struct _CRYPT_XML_REFERENCE {
ULONG cbSize;
HCRYPTXML hReference;
LPCWSTR wszId;
LPCWSTR wszUri;
LPCWSTR wszType;
CRYPT_XML_ALGORITHM DigestMethod;
CRYPT_DATA_BLOB DigestValue;
ULONG cTransform;
CRYPT_XML_ALGORITHM *rgTransform;
} CRYPT_XML_REFERENCE, *PCRYPT_XML_REFERENCE;

Members
cbSize

The size, in bytes, of this structure.

hReference

The handle of the Reference element.

wszId

Optional. A pointer to a null-terminated Unicode string that contains the value of the Id attribute.
wszUri

A pointer to a null-terminated Unicode string that contains a URI attribute.

wszType

A pointer to a null-terminated Unicode string that contains the value of the Type attribute.
DigestMethod

A CRYPT_XML_ALGORITHM structure that specifies the digest method.

DigestValue

A CRYPT_DATA_BLOB structure that specifies the hash value.

cTransform

The number of elements in the array pointed to by the rgTransform member.

rgTransform

An array of CRYPT_XML_TRANSFORM_INFO structures that contain information about the transform applied to
the signed data.
Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Header cryptxml.h
 CRYPT_XML_REFERENCES structure (cryptxml.h)
7/2/2022 • 2 minutes to read • Edit Online

The CRYPT_XML_REFERENCES structure defines an array of CRYPT_XML_REFERENCE structures.

Syntax
typedef struct _CRYPT_XML_REFERENCES {
ULONG cReference;
PCRYPT_XML_REFERENCE *rgpReference;
} CRYPT_XML_REFERENCES, *PCRYPT_XML_REFERENCES;

Members
cReference

The number of elements in the array pointed to by the rgpReference member.

rgpReference

A pointer to an array of PCRYPT_XML_REFERENCE structures.

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Header cryptxml.h
 CRYPT_XML_SIGNATURE structure (cryptxml.h)
7/2/2022 • 2 minutes to read • Edit Online

The CRYPT_XML_SIGNATURE structure contains information used to populate the Signature element.

Syntax
typedef struct _CRYPT_XML_SIGNATURE {
ULONG cbSize;
HCRYPTXML hSignature;
LPCWSTR wszId;
CRYPT_XML_SIGNED_INFO SignedInfo;
CRYPT_DATA_BLOB SignatureValue;
CRYPT_XML_KEY_INFO *pKeyInfo;
ULONG cObject;
PCRYPT_XML_OBJECT *rgpObject;
} CRYPT_XML_SIGNATURE, *PCRYPT_XML_SIGNATURE;

Members
cbSize

The size, in bytes, of this structure.

hSignature

The handle of the signature to encode.

wszId

A pointer to a null-terminated Unicode string that contains the value of the Id attribute.
SignedInfo

A CRYPT_XML_SIGNED_INFO structure that contains the canonicalization algorithm, a signature algorithm, and
one or more references. The SignedInfo element can contain an optional ID attribute that will allow the
structure to be referenced by other signatures and objects.
SignatureValue

A CRYPT_DATA_BLOB structure that contains a cryptographic signature value used to populate the Signature
element.
pKeyInfo

Optional. A pointer to a CRYPT_XML_KEY_INFO structure that contains information that is encoded in the
KeyInfo element.
cObject

The number of items in the array pointed to by the rgpObject member.

rgpObject

Optional. A pointer to an array of pointers to CRYPT_XML_OBJECT structures that contain information that is
encoded in Object elements.
Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Header cryptxml.h
 CRYPT_XML_SIGNED_INFO structure (cryptxml.h)
7/2/2022 • 2 minutes to read • Edit Online

The CRYPT_XML_SIGNED_INFO structure describes an XML encoded SignedInfo element.

Syntax
typedef struct _CRYPT_XML_SIGNED_INFO {
ULONG cbSize;
LPCWSTR wszId;
CRYPT_XML_ALGORITHM Canonicalization;
CRYPT_XML_ALGORITHM SignatureMethod;
ULONG cReference;
PCRYPT_XML_REFERENCE *rgpReference;
CRYPT_XML_BLOB Encoded;
} CRYPT_XML_SIGNED_INFO, *PCRYPT_XML_SIGNED_INFO;

Members
cbSize

The size, in bytes, of this structure.

wszId

Optional. A pointer to a null-terminated Unicode string that contains the Id attribute.

Canonicalization

A CRYPT_XML_ALGORITHM structure that specifies the canonicalization algorithm.

SignatureMethod

A CRYPT_XML_ALGORITHM structure that specifies the signature algorithm.

cReference

The number of elements in the array pointed to by the rgpReference member.

rgpReference

A pointer to an array of pointers to CRYPT_XML_REFERENCE structures that contain information that is encoded
in Reference elements.
Encoded

A CRYPT_XML_BLOB structure that contains the XML encoded SignedInfo element.

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Header cryptxml.h
 CRYPT_XML_STATUS structure (cryptxml.h)
7/2/2022 • 2 minutes to read • Edit Online

The CRYPT_XML_STATUS structure returns information about the signature validation status, summary status
information about a SignedInfo element, or summary status information about an array of Reference
elements. The CRYPT_XML_STATUS structure is used by the CryptXmlGetStatus function.

Syntax
typedef struct _CRYPT_XML_STATUS {
ULONG cbSize;
DWORD dwErrorStatus;
DWORD dwInfoStatus;
} CRYPT_XML_STATUS, *PCRYPT_XML_STATUS;

Members
cbSize

The size, in bytes, of this structure.

dwErrorStatus

The retrieved error flags.

This member can be one of the following values.

VA L UE M EA N IN G

One of the references could not be resolved.

CRYPT_XML_STATUS_ERROR_NOT_RESOLVED
0x00000001

The digest value could not be verified.

CRYPT_XML_STATUS_ERROR_DIGEST_INVALID
0x0000002

One of the algorithm URIs specified in XML is not

CRYPT_XML_STATUS_ERROR_NOT_SUPPORTED_ALGO supported.
RITHM
0x00000005

One of the transform URIs specified in XML is not

CRYPT_XML_STATUS_ERROR_NOT_SUPPORTED_TRAN supported.
SFORM
0x00000008

The signature value could not be verified.

CRYPT_XML_STATUS_ERROR_SIGNATURE_INVALID
0x00010000
 Unable to parse the KeyInfo element.
CRYPT_XML_STATUS_ERROR_KEYINFO_NOT_PARSED
0x00020000

dwInfoStatus

The retrieved informational flags.

This member can be one of the following values.

VA L UE M EA N IN G

The reference URI points to an internal element in XML and

CRYPT_XML_STATUS_INTERNAL_REFERENCE can be resolved automatically.
0x00000001

The KeyValue element parsed, and a key handle imported

CRYPT_XML_STATUS_KEY_AVAIL ABLE successfully.
0x00000002

The reference is being added to the digest.

CRYPT_XML_STATUS_DIGESTING
0x00000004

The digest value was verified.

CRYPT_XML_STATUS_DIGEST_VALID
0x00000008

The signature value was verified.

CRYPT_XML_STATUS_SIGNATURE_VALID
0x00010000

The document is open for encoding.

CRYPT_XML_STATUS_OPENED_TO_ENCODE
0x80000000

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Header cryptxml.h
 CRYPT_XML_TRANSFORM_CHAIN_CONFIG
structure (cryptxml.h)
7/2/2022 • 2 minutes to read • Edit Online

The CRYPT_XML_TRANSFORM_CHAIN_CONFIG structure contains application defined transforms that are

allowed for use in the XML digital signature.

Syntax
typedef struct _CRYPT_XML_TRANSFORM_CHAIN_CONFIG {
ULONG cbSize;
ULONG cTransformInfo;
PCRYPT_XML_TRANSFORM_INFO *rgpTransformInfo;
} CRYPT_XML_TRANSFORM_CHAIN_CONFIG, *PCRYPT_XML_TRANSFORM_CHAIN_CONFIG;

Members
cbSize

The size, in bytes, of this structure.

cTransformInfo

The number of elements in the array pointed to by the rgpTransformInfo member.

rgpTransformInfo

A pointer to an array of pointers to CRYPT_XML_TRANSFORM_INFO structures that contain the transform

parameters.

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Header cryptxml.h
 CRYPT_XML_TRANSFORM_INFO structure
(cryptxml.h)
7/2/2022 • 2 minutes to read • Edit Online

The CRYPT_XML_TRANSFORM_INFO structure contains information that is used when applying the data
transform.

Syntax
typedef struct _CRYPT_XML_TRANSFORM_INFO {
ULONG cbSize;
LPCWSTR wszAlgorithm;
ULONG cbBufferSize;
DWORD dwFlags;
PFN_CRYPT_XML_CREATE_TRANSFORM pfnCreateTransform;
} CRYPT_XML_TRANSFORM_INFO, *PCRYPT_XML_TRANSFORM_INFO;

Members
cbSize

The size, in bytes, of this structure.

wszAlgorithm

A pointer to a null-terminated Unicode string that contains the Algorithm attribute.

cbBufferSize

The size, in bytes, of the data provider's buffer. The size can be zero if the size cannot be determined at
initialization time. This value is used by a caller of the structure pointed to by the pfnCreateTransform
member to determine the necessary size of the receiving buffer.
dwFlags

Specifies values that control how the transform is applied.

This member can be one or more of the following values.

VA L UE M EA N IN G

Specifies that the input to the transform is a stream of bytes.

CRYPT_XML_TRANSFORM_ON_STREAM
0x00000001

Specifies that the input to the transform is an XML node set.

CRYPT_XML_TRANSFORM_ON_NODESET
0x00000002
 Specifies that the URI comparison is to be performed on the
CRYPT_XML_TRANSFORM_URI_QUERY_STRING core URI without the QueryString.
0x00000003
In some cases, the URI may contain additional
information in the QueryString after the ampersand (&).
Use this flag to evaluate only the core URI.

pfnCreateTransform

A pointer to a PFN_CRYPT_XML_CREATE_TRANSFORM callback function used to create the transform.

Remarks
For XML canonicalization transforms, the buffer size specified by the cbBufferSize member must be large
enough to accommodate an entire Star t element with all attribute values.

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Header cryptxml.h

See also
Digital Signature Cryptographic Algorithms
 CRYPT_XML_X509DATA structure (cryptxml.h)
7/2/2022 • 2 minutes to read • Edit Online

The CRYPT_XML_X509DATA structure represents the sequence of choices in the X509Data element.

Syntax
typedef struct _CRYPT_XML_X509DATA {
UINT cX509Data;
CRYPT_XML_X509DATA_ITEM *rgX509Data;
} CRYPT_XML_X509DATA;

Members
cX509Data

The size, in bytes, of the buffer pointed to by the rgX509Data member.

rgX509Data

A pointer to a CRYPT_XML_X509DATA_ITEM structure that contains data to encode.

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Header cryptxml.h
 CRYPT_XML_X509DATA_ITEM structure (cryptxml.h)
7/2/2022 • 2 minutes to read • Edit Online

The CRYPT_XML_X509DATA_ITEM structure represents X.509 data that is to be encoded in an X509Data

named element.

Syntax
typedef struct _CRYPT_XML_X509DATA_ITEM {
DWORD dwType;
union {
CRYPT_XML_ISSUER_SERIAL IssuerSerial;
CRYPT_XML_DATA_BLOB SKI;
LPCWSTR wszSubjectName;
CRYPT_XML_DATA_BLOB Certificate;
CRYPT_XML_DATA_BLOB CRL;
CRYPT_XML_BLOB Custom;
};
} CRYPT_XML_X509DATA_ITEM;

Members
dwType

Specifies the data item type.

This member can be one of the following values.

VA L UE M EA N IN G

The X.509 data is an issuer serial number.

CRYPT_XML_X509DATA_TYPE_ISSUER_SERIAL
0x00000001

The X.509 data is a Subject Key Identifier (SKI).

CRYPT_XML_X509DATA_TYPE_SKI
0x00000002

The X.509 data is a subject name.

CRYPT_XML_X509DATA_TYPE_SUBJECT_NAME
0x00000003

The X.509 data is a certificate.

CRYPT_XML_X509DATA_TYPE_CERTIFICATE
0x00000004

The X.509 data is a certificate revocation list (CRL).

CRYPT_XML_X509DATA_TYPE_CRL
0x00000005
 The X.509 data is a custom format.
CRYPT_XML_X509DATA_TYPE_CUSTOM
0x00000006

IssuerSerial

A CRYPT_XML_ISSUER_SERIAL structure that contains serial number data.

SKI

A CRYPT_XML_DATA_BLOB structure that contains SKI data.

wszSubjectName

A pointer to a null-terminated Unicode string that contains the subject name.

Certificate

A CRYPT_XML_DATA_BLOB structure that contains certificate data.

CRL

A CRYPT_XML_DATA_BLOB that contains a CRL.

Custom

A CRYPT_XML_BLOB structure that contains custom data.

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Header cryptxml.h
 CryptXmlAddObject function (cryptxml.h)
7/2/2022 • 2 minutes to read • Edit Online

The Cr yptXmlAddObject function adds the Object element to the Signature in the Document Context opened
for encoding.

Syntax
HRESULT CryptXmlAddObject(
[in] HCRYPTXML hSignatureOrObject,
DWORD dwFlags,
[in, optional] const CRYPT_XML_PROPERTY *rgProperty,
[in] ULONG cProperty,
[in] const CRYPT_XML_BLOB *pEncoded,
[out, optional] const CRYPT_XML_OBJECT **ppObject
);

Parameters
[in] hSignatureOrObject

The handle of a Signature returned by the CryptXmlOpenToEncode function or the handle of a Reference
returned by the CryptXmlCreateReference function with the
CRYPT_XML_FL AG_CREATE_REFERENCE_AS_OBJECT flag set.
dwFlags

Specifies flags that control the manner in which the object is added.
Currently defined dwFlags values are shown in the following table .

VA L UE M EA N IN G

When set, an in-memory copy of the XML part is created

CRYPT_XML_ADD_OBJECT_CREATE_REFERENCE and included in the Object element.

[in, optional] rgProperty

A pointer to a CRYPT_XML_PROPERTY structure that specifies additional properties used to decode the Object
element.
[in] cProperty

The number of elements in the array pointed to by the rgProperty property.

[in] pEncoded

A pointer to a CRYPT_XML_BLOB structure that contains the Object element.

[out, optional] ppObject

A pointer to a pointer to a CRYPT_XML_OBJECT structure to receive the decoded structure. This parameter must
be NULL when the hSignatureOrObject parameter contains a handle to the Object.
Return value
If the function succeeds, the function returns zero.
If the function fails, it returns an HRESULT value that indicates the error.

Remarks
When the hSignatureOrObject parameter specifies a handle to a Reference returned by the
CryptXmlCreateReference function, the pEncoded parameter specifies XML content that is included in the
Object node after the optional Manifest element. The pointer contained in the pEncoded parameter must be
valid until the signature is complete. Otherwise, use the CRYPT_XML_FL AG_ADD_OBJECT_CREATE_COPY
flag to create an in-memory copy.

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Target Platform Windows

Header cryptxml.h

Librar y Cryptxml.lib

DLL Cryptxml.dll
 CryptXmlClose function (cryptxml.h)
7/2/2022 • 2 minutes to read • Edit Online

The Cr yptXmlClose function closes a cryptographic XML object handle.

Syntax
HRESULT CryptXmlClose(
[in] HCRYPTXML hCryptXml
);

Parameters
[in] hCryptXml

The handle of the cryptographic XML object to be closed.

Return value
If the function succeeds, the function returns zero.
If the function fails, it returns an HRESULT value that indicates the error.

Remarks
At each call to this function, the reference count on the handle is reduced by one. When the reference count
reaches zero, an object encapsulated by the handle is fully released.

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Target Platform Windows

Header cryptxml.h

Librar y Cryptxml.lib

DLL Cryptxml.dll
 CryptXmlCreateReference function (cryptxml.h)
7/2/2022 • 2 minutes to read • Edit Online

The Cr yptXmlCreateReference function creates a reference to an XML signature.

Syntax
HRESULT CryptXmlCreateReference(
[in] HCRYPTXML hCryptXml,
DWORD dwFlags,
[in, optional] LPCWSTR wszId,
[in, optional] LPCWSTR wszURI,
[in, optional] LPCWSTR wszType,
[in] const CRYPT_XML_ALGORITHM *pDigestMethod,
ULONG cTransform,
[in] const CRYPT_XML_ALGORITHM *rgTransform,
[out] HCRYPTXML *phReference
);

Parameters
[in] hCryptXml

The handle of the XML signature.

dwFlags

Specifies flags that affect how the reference is created.

Currently defined dwFlags values are shown in the following table.

VA L UE M EA N IN G

Set this flag to create an Object node and add it to the

CRYPT_XML_FL AG_CREATE_REFERENCE_AS_OBJECT Signature element. A reference to the Object node is
0x00000001 created in the SignedInfo element.
The returned handle is an encapsulated Object node
and can be used in subsequent calls to the
Cr yptXmlCreateReference function to create
references in the Manifest node.

[in, optional] wszId

A pointer to a null -terminated Unicode string that contains the value of the ID attribute of the Reference
element of the signature. If this parameter is NULL , then the ID attribute is not created. If this parameter is an
empty string, then the ID attribute with empty value is created.
[in, optional] wszURI

A pointer to a null -terminated Unicode string that contains the value of the URI attribute of the Reference
element of the signature. If this parameter is an empty string, then the URI attribute with an empty value is
created.
[in, optional] wszType
A pointer to a null -terminated Unicode string that contains the value of the Type attribute of the Reference
element of the signature. The processing engine does not check or use this attribute.
[in] pDigestMethod

A pointer to a CRYPT_XML_ALGORITHM structure that contains the digest method.

cTransform

The number of elements in the array pointed to by the rgTransform parameter.

[in] rgTransform

A pointer to an ordered array of CRYPT_XML_ALGORITHM structures that contain transform algorithms to be

applied to the reference data before the digest calculation.
[out] phReference

A pointer to a reference handle.

Return value
If the function succeeds, the function returns zero.
If the function fails, it returns an HRESULT value that indicates the error.

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Target Platform Windows

Header cryptxml.h

Librar y Cryptxml.lib

DLL Cryptxml.dll
 CryptXmlDigestReference function (cryptxml.h)
7/2/2022 • 2 minutes to read • Edit Online

The Cr yptXmlDigestReference function is used by an application to digest the resolved reference. This
function applies transforms before updating the digest.

Syntax
HRESULT CryptXmlDigestReference(
[in] HCRYPTXML hReference,
DWORD dwFlags,
[in] CRYPT_XML_DATA_PROVIDER *pDataProviderIn
);

Parameters
[in] hReference

The handle of a Reference element.

dwFlags

Specifies values that control how the process applies transforms.

Currently defined dwFlags are shown in the following table.

VA L UE M EA N IN G

Specifies that the processing engine will create the digest

CRYPT_XML_REFERENCE_DATA_TRANSFORMED without applying the transform chain engine.
0x00000001

[in] pDataProviderIn

A pointer to a CRYPT_XML_DATA_PROVIDER structure that specifies the data provider. The

Cr yptXmlDigestReference function always calls the fpnClose function on the data provider.

Return value
If the function succeeds, the function returns zero.
If the function fails, it returns an HRESULT value that indicates the error.

Remarks
When the CRYPT_XML_REFERENCE_DATA_TRANSFORMED flag is set, the processing engine adds received
data directly to the digest without applying the transform chain engine.

Note The Cr yptXmlDigestReference function always calls the function pointed to by the fpnClose member of the
CRYPT_XML_DATA_PROVIDER structure pointed to by the pDataProviderIn parameter.
Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Target Platform Windows

Header cryptxml.h

Librar y Cryptxml.lib

DLL Cryptxml.dll
 CryptXmlDllCloseDigest callback function
(cryptxml.h)
7/2/2022 • 2 minutes to read • Edit Online

The Cr yptXmlDllCloseDigest function frees the CRYPT_XML_DIGEST allocated by the

CryptXmlDllCreateDigest function.
The CryptXmlDllCloseDigest function is exposed through the Cryptographic Extensions DLL and is exposed
through the exported CryptXmlDllGetInterface function.

Syntax
CryptXmlDllCloseDigest Cryptxmldllclosedigest;

HRESULT Cryptxmldllclosedigest(
[in] CRYPT_XML_DIGEST hDigest
)
{...}

Parameters
[in] hDigest

The handle of the hash object. This handle is obtained by calling the CryptXmlCreateDigest function. After the
function has been called, the digest handle passed to this function is released and cannot be used again.

Return value
If the function succeeds, the function returns zero.
If the function fails, it returns an HRESULT value that indicates the error.

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Target Platform Windows

Header cryptxml.h
 CryptXmlDllCreateDigest callback function
(cryptxml.h)
7/2/2022 • 2 minutes to read • Edit Online

The Cr yptXmlDllCreateDigest function creates a digest object for the specified method.
The Cr yptXmlDllCreateDigest function is exposed through the exported CryptXmlDllGetInterface function.

Syntax
CryptXmlDllCreateDigest Cryptxmldllcreatedigest;

HRESULT Cryptxmldllcreatedigest(
[in] const CRYPT_XML_ALGORITHM *pDigestMethod,
[out] ULONG *pcbSize,
[out] CRYPT_XML_DIGEST *phDigest
)
{...}

Parameters
[in] pDigestMethod

A pointer to a CRYPT_XML_ALGORITHM structure that specifies the algorithm to use to create the digest.
[out] pcbSize

A pointer to a ULONG variable that receives the size, in bytes, of the digest.
[out] phDigest

A pointer to a CRYPT_XML_DIGEST variable that receives a pointer to the digest.

When you have finished using the resources allocated by the call to this function, you must free them by calling
the CryptXmlDllCloseDigest function.

Return value
If the function succeeds, the function returns zero.
If the function fails, it returns an HRESULT value that indicates the error.

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Target Platform Windows

Header cryptxml.h
 CryptXmlDllCreateKey callback function (cryptxml.h)
7/2/2022 • 2 minutes to read • Edit Online

the Cr yptXmlDllCreateKey function parses the KeyValue element and creates a Cryptography API: Next
Generation (CNG) BCrypt key handle to verify a signature.

Syntax
CryptXmlDllCreateKey Cryptxmldllcreatekey;

HRESULT Cryptxmldllcreatekey(
[in] const CRYPT_XML_BLOB *pEncoded,
[out] BCRYPT_KEY_HANDLE *phKey
)
{...}

Parameters
[in] pEncoded

A pointer to a CRYPT_XML_BLOB structure that contains the KeyValue element.

[out] phKey

A pointer to a BCRYPT_KEY_HANDLE variable that receives the handle of the key used to verify the signature.
When CryptXML has finished using the key, CryptXML frees it by calling the BCryptDestroyKey function.

Return value
If the function succeeds, the function returns zero.
If the function fails, it returns an HRESULT value that indicates the error.

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Target Platform Windows

Header cryptxml.h
 CryptXmlDllDigestData callback function
(cryptxml.h)
7/2/2022 • 2 minutes to read • Edit Online

The Cr yptXmlDllDigestData function puts data into the digest.

The Cr yptXmlDllDigestData function is exposed through the exported CryptXmlDllGetInterface function.

Syntax
CryptXmlDllDigestData Cryptxmldlldigestdata;

HRESULT Cryptxmldlldigestdata(
CRYPT_XML_DIGEST hDigest,
const BYTE *pbData,
ULONG cbData
)
{...}

Parameters
hDigest

The handle of the hash object used to put data into the digest. This handle is obtained by calling the
CryptXmlDllCreateDigest function.
pbData

A pointer to a block of data to be processed.

cbData

The size, in bytes, of the block of data pointed to by the pbData parameter.

Return value
If the function succeeds, the function returns zero.
If the function fails, it returns an HRESULT value that indicates the error.

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Target Platform Windows

Header cryptxml.h
 CryptXmlDllEncodeAlgorithm callback function
(cryptxml.h)
7/2/2022 • 2 minutes to read • Edit Online

The Cr yptXmlDllEncodeAlgorithm function encodes SignatureMethod or DigestMethod elements for

agile algorithms with default parameters.
The Cr yptXmlDllEncodeAlgorithm function is exposed through the exported CryptXmlDllGetInterface
function.

Syntax
CryptXmlDllEncodeAlgorithm Cryptxmldllencodealgorithm;

HRESULT Cryptxmldllencodealgorithm(
[in] const CRYPT_XML_ALGORITHM_INFO *pAlgInfo,
CRYPT_XML_CHARSET dwCharset,
[in, out] void *pvCallbackState,
[in] PFN_CRYPT_XML_WRITE_CALLBACK pfnWrite
)
{...}

Parameters
[in] pAlgInfo

A pointer to a CRYPT_XML_ALGORITHM_INFO structure.

dwCharset

A CRYPT_XML_CHARSET value that specifies the character set of the encoded XML.
[in, out] pvCallbackState

A pointer to an argument that is passed to the callback function pointed to by the pfnWrite parameter.
[in] pfnWrite

A PFN_CRYPT_XML_WRITE_CALLBACK callback function that receives the encoded XML.

Return value
If the function succeeds, the function returns zero.
If the function fails, it returns an HRESULT value that indicates the error.

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Target Platform Windows

Header cryptxml.h
 CryptXmlDllEncodeKeyValue callback function
(cryptxml.h)
7/2/2022 • 2 minutes to read • Edit Online

The Cr yptXmlDllEncodeKeyValue function encodes a KeyValue element.

Syntax
CryptXmlDllEncodeKeyValue Cryptxmldllencodekeyvalue;

HRESULT Cryptxmldllencodekeyvalue(
[in] NCRYPT_KEY_HANDLE hKey,
CRYPT_XML_CHARSET dwCharset,
[in, out] void *pvCallbackState,
[in] PFN_CRYPT_XML_WRITE_CALLBACK pfnWrite
)
{...}

Parameters
[in] hKey

The handle of the key value to encode.

dwCharset

A value of the CRYPT_XML_CHARSET enumeration that specifies the character set of the encoded XML.
[in, out] pvCallbackState

A pointer to an argument that is passed to the callback function pointed to by the pfnWrite parameter.
[in] pfnWrite

An application defined callback function that receives the encoded XML.

Return value
If the function succeeds, the function returns zero.
If the function fails, it returns an HRESULT value that indicates the error.

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Target Platform Windows

Header cryptxml.h
 CryptXmlDllFinalizeDigest callback function
(cryptxml.h)
7/2/2022 • 2 minutes to read • Edit Online

The Cr yptXmlDllFinalizeDigest function retrieves the digest value.

The Cr yptXmlDllFinalizeDigest function is exposed through the exported CryptXmlDllGetInterface function.

Syntax
CryptXmlDllFinalizeDigest Cryptxmldllfinalizedigest;

HRESULT Cryptxmldllfinalizedigest(
[in] CRYPT_XML_DIGEST hDigest,
[out] BYTE *pbDigest,
ULONG cbDigest
)
{...}

Parameters
[in] hDigest

The handle of the hash object used to put data into the digest. This handle is obtained by calling the
CryptXmlDllCreateDigest function.
[out] pbDigest

A pointer to a buffer that receives the digest value.

cbDigest

The size, in bytes, of the buffer pointed to by the pbDigest parameter.

Return value
If the function succeeds, the function returns zero.
If the function fails, it returns an HRESULT value that indicates the error.

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Target Platform Windows

Header cryptxml.h
 CryptXmlDllGetAlgorithmInfo callback function
(cryptxml.h)
7/2/2022 • 2 minutes to read • Edit Online

The Cr yptXmlDllGetAlgorithmInfo function decodes the XML algorithm and returns information about the
algorithm.
The Cr yptXmlDllGetAlgorithmInfo function is exposed through the exported CryptXmlDllGetInterface
function.

Syntax
CryptXmlDllGetAlgorithmInfo Cryptxmldllgetalgorithminfo;

HRESULT Cryptxmldllgetalgorithminfo(
[in] const CRYPT_XML_ALGORITHM *pXmlAlgorithm,
[out] CRYPT_XML_ALGORITHM_INFO **ppAlgInfo
)
{...}

Parameters
[in] pXmlAlgorithm

A pointer to a CRYPT_XML_ALGORITHM structure that specifies the algorithm.

[out] ppAlgInfo

A pointer to a pointer to a CRYPT_XML_ALGORITHM_INFO structure.

When you have finished using the memory pointed to by the ppAlgInfo parameter, free it by calling the
LocalFree function.

Return value
If the function succeeds, the function returns zero.
If the function fails, it returns an HRESULT value that indicates the error.

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Target Platform Windows

Header cryptxml.h
 CryptXmlDllGetInterface callback function
(cryptxml.h)
7/2/2022 • 2 minutes to read • Edit Online

The Cr yptXmlDllGetInterface function retrieves a pointer to the cryptographic extension functions for the
specified algorithm.

Syntax
CryptXmlDllGetInterface Cryptxmldllgetinterface;

HRESULT Cryptxmldllgetinterface(
DWORD dwFlags,
[in] const CRYPT_XML_ALGORITHM_INFO *pMethod,
[out] CRYPT_XML_CRYPTOGRAPHIC_INTERFACE *pInterface
)
{...}

Parameters
dwFlags

This parameter is reserved and must be set to zero.

[in] pMethod

A pointer to a CRYPT_XML_ALGORITHM_INFO structure to retrieve the interface of.

[out] pInterface

A pointer to a CRYPT_XML_ALGORITHM_INFO structure to receive the interface information.

Return value
If the function succeeds, the function returns zero.
If the function fails, it returns an HRESULT value that indicates the error.

Remarks
The cryptographic extensions DLL must export the Cr yptXmlDllGetInterface entry.
To get the CRYPT_XML_CRYPTOGRAPHIC_INTERFACE table, CryptXml loads the registered cryptographic
extensions DLL by using the LoadLibrary function, and then it calls the Cr yptXmlDllGetInterface function.

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Target Platform Windows

Header cryptxml.h
 CryptXmlDllSignData callback function (cryptxml.h)
7/2/2022 • 2 minutes to read • Edit Online

The CryptXmlDllSignData function signs data.

The CryptXmlDllSignData function is exposed through the exported CryptXmlDllGetInterface function.

Syntax
CryptXmlDllSignData Cryptxmldllsigndata;

HRESULT Cryptxmldllsigndata(
[in] const CRYPT_XML_ALGORITHM *pSignatureMethod,
[in] HCRYPTPROV_OR_NCRYPT_KEY_HANDLE hCryptProvOrNCryptKey,
[in] DWORD dwKeySpec,
[in] const BYTE *pbInput,
[in] ULONG cbInput,
[out, optional] BYTE *pbOutput,
[in] ULONG cbOutput,
[out] ULONG *pcbResult
)
{...}

Parameters
[in] pSignatureMethod

A pointer to a CRYPT_XML_ALGORITHM structure that specifies the algorithm.

[in] hCryptProvOrNCryptKey

The handle of the cryptographic service provider (CSP) that creates the signature. This handle must be an
HCRYPTPROV handle that was obtained from a call to the CryptAcquireContext function or an
NCRYPT_KEY_HANDLE handle that was created by using the NCryptOpenKey function. New applications
should pass in an NCRYPT_KEY_HANDLE handle.
[in] dwKeySpec

The private key to use from the provider's container. This key can be AT_KEYEXCHANGE or AT_SIGNATURE. This
parameter is ignored if an NCRYPT_KEY_HANDLE handle is used in the hCryptProvOrNCryptKey parameter.
[in] pbInput

A pointer to a buffer that contains the digest value to sign. The cbInput parameter contains the size of this buffer.
[in] cbInput

The size, in bytes, of the buffer pointed to by the pbInput parameter.

[out, optional] pbOutput

The address of a buffer to receive the signature produced by this function. The cbOutput parameter contains the
size of this buffer.
If this parameter is NULL , this function will calculate the size needed for the encrypted data and return the size
in the location pointed to by the pcbResult parameter.
[in] cbOutput

The size, in bytes, of the buffer pointed to by the pbOutput parameter.

[out] pcbResult

A pointer to a DWORD variable that receives the number of bytes copied to the pbOutput buffer. If pbOutput is
NULL , this receives the size, in bytes, required for the signature.

Return value
If the function succeeds, the function returns zero.
If the function fails, it returns an HRESULT value that indicates the error.

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Target Platform Windows

Header cryptxml.h
 CryptXmlDllVerifySignature callback function
(cryptxml.h)
7/2/2022 • 2 minutes to read • Edit Online

The Cr yptXmlDllVerifySignature function verifies a signature.

The Cr yptXmlDllVerifySignature function is exposed through the exported CryptXmlDllGetInterface function.

Syntax
CryptXmlDllVerifySignature Cryptxmldllverifysignature;

HRESULT Cryptxmldllverifysignature(
[in] const CRYPT_XML_ALGORITHM *pSignatureMethod,
[in] BCRYPT_KEY_HANDLE hKey,
[in] const BYTE *pbInput,
[in] ULONG cbInput,
[in] const BYTE *pbSignature,
[in] ULONG cbSignature
)
{...}

Parameters
[in] pSignatureMethod

A pointer to a CRYPT_XML_ALGORITHM structure that specifies the algorithm.

[in] hKey

A handle to the public key.

[in] pbInput

A pointer to a buffer that contains the signed data. The cbInput parameter contains the size of this buffer.
[in] cbInput

The size, in bytes, of the buffer pointed to by the pbInput parameter.

[in] pbSignature

A pointer to a buffer that contains the signature value to be verified. The cbSignature parameter contains the
size of this buffer.
[in] cbSignature

The size, in bytes, of the pbSignature buffer.

Return value
If the function succeeds, the function returns zero.
If the function fails, it returns an HRESULT value that indicates the error.
Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Target Platform Windows

Header cryptxml.h
 CryptXmlEncode function (cryptxml.h)
7/2/2022 • 2 minutes to read • Edit Online

The Cr yptXmlEncode function encodes signature data by using the supplied XML writer callback function.

Syntax
HRESULT CryptXmlEncode(
[in] HCRYPTXML hCryptXml,
CRYPT_XML_CHARSET dwCharset,
[in] const CRYPT_XML_PROPERTY *rgProperty,
[in] ULONG cProperty,
[in, out] void *pvCallbackState,
[in] PFN_CRYPT_XML_WRITE_CALLBACK pfnWrite
);

Parameters
[in] hCryptXml

The handle of the object to be serialized. The handle can be of Signature , Object , or Reference types.
dwCharset

A value of the CRYPT_XML_CHARSET enumeration that specifies the character set of the encoded XML.
[in] rgProperty

A pointer to an array of CRYPT_XML_PROPERTY structures that contain additional properties.

[in] cProperty

A ULONG value that specifies the number of entries in the array pointed to by the rgProperty parameter.
[in, out] pvCallbackState

A pointer to an application defined argument that is passed to the XML writer callback function pointed to by the
pfnWrite parameter.
[in] pfnWrite

An XML writer callback function to receive the application defined argument pointed to by the pvCallbackState
parameter.

Return value
If the function succeeds, the function returns zero.
If the function fails, it returns an HRESULT value that indicates the error.

Requirements
Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Target Platform Windows

Header cryptxml.h

Librar y Cryptxml.lib

DLL Cryptxml.dll
 CryptXmlGetAlgorithmInfo function (cryptxml.h)
7/2/2022 • 2 minutes to read • Edit Online

The Cr yptXmlGetAlgorithmInfo function decodes the CRYPT_XML_ALGORITHM structure and returns

information about the algorithm.

Syntax
HRESULT CryptXmlGetAlgorithmInfo(
[in] const CRYPT_XML_ALGORITHM *pXmlAlgorithm,
DWORD dwFlags,
[out] CRYPT_XML_ALGORITHM_INFO **ppAlgInfo
);

Parameters
[in] pXmlAlgorithm

A pointer to a CRYPT_XML_ALGORITHM structure that specifies the algorithm about which to return
information.
dwFlags

This parameter can be one of the following values.

VA L UE M EA N IN G

Only default implementations for the signature and digest

CRYPT_XML_FL AG_DISABLE_EXTENSIONS are used. When this flag is set, no other registered
0x10000000 extensions are loaded.

[out] ppAlgInfo

A pointer to a pointer to a CRYPT_XML_ALGORITHM_INFO structure. When you have finished using the memory
pointed to by the ppAlgInfo parameter, free it by calling the LocalFree function.

Return value
If the function succeeds, the function returns zero.
If the function fails, it returns an HRESULT value that indicates the error.

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Target Platform Windows

Header cryptxml.h

Librar y Cryptxml.lib

DLL Cryptxml.dll
 CryptXmlGetDocContext function (cryptxml.h)
7/2/2022 • 2 minutes to read • Edit Online

The Cr yptXmlGetDocContext function returns the document context specified by the supplied handle.

Syntax
HRESULT CryptXmlGetDocContext(
[in] HCRYPTXML hCryptXml,
[out] const CRYPT_XML_DOC_CTXT **ppStruct
);

Parameters
[in] hCryptXml

The handle of the document context to retrieve.

[out] ppStruct

A pointer to a pointer to a CRYPT_XML_DOC_CTXT structure that contains the returned document context.

Return value
If the function succeeds, the function returns zero.
If the function fails, it returns an HRESULT value that indicates the error.

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Target Platform Windows

Header cryptxml.h

Librar y Cryptxml.lib

DLL Cryptxml.dll
 CryptXmlGetReference function (cryptxml.h)
7/2/2022 • 2 minutes to read • Edit Online

The Cr yptXmlGetReference function returns the Reference element specified by the supplied handle.

Syntax
HRESULT CryptXmlGetReference(
[in] HCRYPTXML hCryptXml,
[out] const CRYPT_XML_REFERENCE **ppStruct
);

Parameters
[in] hCryptXml

The handle of the Reference element to retrieve.

[out] ppStruct

A pointer to a pointer to a CRYPT_XML_REFERENCE structure that contains the returned Reference element.

Return value
If the function succeeds, the function returns zero.
If the function fails, it returns an HRESULT value that indicates the error.

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Target Platform Windows

Header cryptxml.h

Librar y Cryptxml.lib

DLL Cryptxml.dll
 CryptXmlGetSignature function (cryptxml.h)
7/2/2022 • 2 minutes to read • Edit Online

The Cr yptXmlGetSignature function returns an XML Signature element.

Syntax
HRESULT CryptXmlGetSignature(
[in] HCRYPTXML hCryptXml,
[out] const CRYPT_XML_SIGNATURE **ppStruct
);

Parameters
[in] hCryptXml

The handle of the Signature element.

[out] ppStruct

A pointer to a pointer to a CRYPT_XML_SIGNATURE structure to receive the signature.

Return value
If the function succeeds, the function returns zero.
If the function fails, it returns an HRESULT value that indicates the error.

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Target Platform Windows

Header cryptxml.h

Librar y Cryptxml.lib

DLL Cryptxml.dll
 CryptXmlGetStatus function (cryptxml.h)
7/2/2022 • 2 minutes to read • Edit Online

The Cr yptXmlGetStatus function returns a CRYPT_XML_STATUS structure that contains status information
about the object specified by the supplied handle.

Syntax
HRESULT CryptXmlGetStatus(
HCRYPTXML hCryptXml,
CRYPT_XML_STATUS *pStatus
);

Parameters
hCryptXml

A handle to a CRYPT_XML_SIGNATURE structure, an array of CRYPT_XML_SIGNATURE structures , a

CRYPT_XML_REFERENCE structure, or a Manifest object about which to get status information.
pStatus

A pointer to a CRYPT_XML_STATUS structure to receive the returned status information.

Return value
If the function succeeds, the function returns zero.
If the function fails, it returns an HRESULT value that indicates the error.

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Target Platform Windows

Header cryptxml.h

Librar y Cryptxml.lib

DLL Cryptxml.dll
 CryptXmlGetTransforms function (cryptxml.h)
7/2/2022 • 2 minutes to read • Edit Online

The Cr yptXmlGetTransforms function returns information about the default transform chain engine.

Syntax
HRESULT CryptXmlGetTransforms(
[out] const CRYPT_XML_TRANSFORM_CHAIN_CONFIG **ppConfig
);

Parameters
[out] ppConfig

A pointer to a pointer to a CRYPT_XML_TRANSFORM_CHAIN_CONFIG structure to receive the returned

transform information.

Return value
If the function succeeds, the function returns zero.
If the function fails, it returns an HRESULT value that indicates the error.

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Target Platform Windows

Header cryptxml.h

Librar y Cryptxml.lib

DLL Cryptxml.dll
 CryptXmlImportPublicKey function (cryptxml.h)
7/2/2022 • 2 minutes to read • Edit Online

The CryptXmlImportPublicKey function imports the public key specified by the supplied handle.

Syntax
HRESULT CryptXmlImportPublicKey(
DWORD dwFlags,
[in] const CRYPT_XML_KEY_VALUE *pKeyValue,
[out] BCRYPT_KEY_HANDLE *phKey
);

Parameters
dwFlags

A DWORD value that controls which CryptXML extensions are loaded. This parameter can be one of the
following values.

VA L UE M EA N IN G

Only default implementations for the signature and digest

CRYPT_XML_FL AG_DISABLE_EXTENSIONS are used. When this flag is set, no other registered
0x10000000 extensions are loaded.

[in] pKeyValue

A pointer to a CRYPT_XML_KEY_VALUE structure to receive the imported key.

[out] phKey

A pointer to the handle of the key to import.

Return value
If the function succeeds, the function returns zero.
If the function fails, it returns an HRESULT value that indicates the error.

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Target Platform Windows

Header cryptxml.h
Librar y Cryptxml.lib

DLL Cryptxml.dll
 CryptXmlOpenToDecode function (cryptxml.h)
7/2/2022 • 2 minutes to read • Edit Online

The Cr yptXmlOpenToDecode function opens an XML digital signature to decode and returns the handle of
the document context that encapsulates a CRYPT_XML_SIGNATURE structure. The document context can include
one or more Signature elements.

Syntax
HRESULT CryptXmlOpenToDecode(
[in, optional] const CRYPT_XML_TRANSFORM_CHAIN_CONFIG *pConfig,
DWORD dwFlags,
[in] const CRYPT_XML_PROPERTY *rgProperty,
ULONG cProperty,
[in] const CRYPT_XML_BLOB *pEncoded,
HCRYPTXML *phCryptXml
);

Parameters
[in, optional] pConfig

The handle of the transform chain engine. If this parameter is NULL , then a default engine will be used to apply
transforms.
dwFlags

A DWORD value that controls which CryptXML extensions are loaded and whether the XML is serialized. This
parameter can be one of the following values.

VA L UE M EA N IN G

Inhibit serialization.
CRYPT_XML_FL AG_NO_SERIALIZE
0x80000000 Important Do not set this flag when multiple threads are
accessing a CryptXml object. Serialization ensures mutual
exclusion when two or more threads attempt to
simultaneously accept a CryptXml object or memory.

Only default implementations for the signature and digest

CRYPT_XML_FL AG_DISABLE_EXTENSIONS are used. When this flag is set, no other registered
0x10000000 extensions are loaded.

[in] rgProperty

A pointer to an array of CRYPT_XML_PROPERTY structures that contain additional properties.

cProperty

The number of items in the array pointed to by the rgProperty parameter.

[in] pEncoded
A pointer to CRYPT_XML_BLOB structure that contains the signature to decode.
phCryptXml

The handle of a Document Context object. When you have finished using the handle, release it by passing it to
the CryptXmlClose function.

Return value
If the function succeeds, the function returns zero.
If the function fails, it returns an HRESULT value that indicates the error.

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Target Platform Windows

Header cryptxml.h

Librar y Cryptxml.lib

DLL Cryptxml.dll
 CryptXmlOpenToEncode function (cryptxml.h)
7/2/2022 • 2 minutes to read • Edit Online

If Cr yptXmlOpenToEncode function opens an XML digital signature to encode and returns a handle of the
opened Signature element. The handle encapsulates a document context with a single
CRYPT_XML_SIGNATURE structure and remains open until the CryptXmlClose function is called.

Syntax
HRESULT CryptXmlOpenToEncode(
[in, optional] const CRYPT_XML_TRANSFORM_CHAIN_CONFIG *pConfig,
DWORD dwFlags,
[in, optional] LPCWSTR wszId,
[in] const CRYPT_XML_PROPERTY *rgProperty,
[in] ULONG cProperty,
[in, optional] const CRYPT_XML_BLOB *pEncoded,
[optional] HCRYPTXML *phSignature
);

Parameters
[in, optional] pConfig

The handle of the transform chain engine. If this parameter is NULL , then a default engine is used to apply
transforms.
dwFlags

A DWORD value that controls which CryptXML extensions are loaded and whether the XML is serialized. This
parameter can be one of the following values.

VA L UE M EA N IN G

Inhibit serialization.
CRYPT_XML_FL AG_NO_SERIALIZE
0x80000000 Note Do not set this flag when multiple threads are
accessing a CryptXml object. Serialization ensures mutual
exclusion when two or more threads attempt to
simultaneously accept a CryptXml object or memory.

Only default implementations for the signature and digest

CRYPT_XML_FL AG_DISABLE_EXTENSIONS are used. When this flag is set, no other registered
0x10000000 extensions are loaded.

[in, optional] wszId

A pointer to a null-terminated Unicode string that contains the Id attribute of the Signature element. If this
parameter is NULL , then a new GUID is generated. If this parameter is an empty string, then no Id attribute is
produced.
[in] rgProperty
A pointer to an array of CRYPT_XML_PROPERTY structures that specify additional properties.
[in] cProperty

The number of elements in the array pointed to by the rgProperty parameter.

[in, optional] pEncoded

A pointer to a CRYPT_XML_BLOB structure that contains the signature to encode.

[optional] phSignature

The handle to the Signature element.

Return value
If the function succeeds, the function returns zero.
If the function fails, it returns an HRESULT value that indicates the error.

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Target Platform Windows

Header cryptxml.h

Librar y Cryptxml.lib

DLL Cryptxml.dll
 CryptXmlSetHMACSecret function (cryptxml.h)
7/2/2022 • 2 minutes to read • Edit Online

The Cr yptXmlSetHMACSecret function sets the HMAC secret on the handle before calling the CryptXmlSign
or CryptXmlVerify function.

Syntax
HRESULT CryptXmlSetHMACSecret(
[in] HCRYPTXML hSignature,
[in] const BYTE *pbSecret,
ULONG cbSecret
);

Parameters
[in] hSignature

The handle of the XML Signature element.

[in] pbSecret

A pointer to a buffer that contains a block of bytes. The pointer must be valid during the call to the
CryptXmlSign or CryptXmlVerify function.
cbSecret

The size, in bytes, of the buffer pointed to by the pbSecret parameter.

Return value
If the function succeeds, the function returns zero.
If the function fails, it returns an HRESULT value that indicates the error.

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Target Platform Windows

Header cryptxml.h

Librar y Cryptxml.lib

DLL Cryptxml.dll
 CryptXmlSign function (cryptxml.h)
7/2/2022 • 2 minutes to read • Edit Online

The Cr yptXmlSign function creates a cryptographic signature of a SignedInfo element.

Syntax
HRESULT CryptXmlSign(
[in] HCRYPTXML hSignature,
[in, optional] HCRYPTPROV_OR_NCRYPT_KEY_HANDLE hKey,
DWORD dwKeySpec,
DWORD dwFlags,
CRYPT_XML_KEYINFO_SPEC dwKeyInfoSpec,
[in, optional] const void *pvKeyInfoSpec,
[in] const CRYPT_XML_ALGORITHM *pSignatureMethod,
[in] const CRYPT_XML_ALGORITHM *pCanonicalization
);

Parameters
[in] hSignature

The handle to a CRYPT_XML_SIGNATURE structure.

[in, optional] hKey

The handle of a private key used to sign the SignedInfo element. This parameter must be NULL for HMAC-
based signature algorithms.
dwKeySpec

A DWORD value that specifies the key type. This parameter can be one of the following values.

VA L UE M EA N IN G

The key pair is a key exchange pair.

AT_KEYEXCHANGE
1

The key pair is a signature pair.

AT_SIGNATURE
2

The key is a Cryptography API: Next Generation (CNG) key.

CERT_NCRYPT_KEY_SPEC
0xFFFFFFFF

dwFlags

A DWORD value that controls how the data is signed. This parameter can be one of the following values.

VA L UE M EA N IN G
 Populate the KeyValue element from the handle specified in
CRYPT_XML_SIGN_ADD_KEYVALUE the hKey parameter.
0x00000001
Important The CRYPT_XML_SIGN_ADD_KEYVALUE
flag cannot be used when the dwKeyInfoSpec parameter is
set to CRYPT_XML_KEYINFO_SPEC_ENCODED .

Only default implementations for the signature and digest

CRYPT_XML_FL AG_DISABLE_EXTENSIONS are used. When this flag is set, no other registered
0x10000000 extensions are loaded.

dwKeyInfoSpec

The type of data structure pointed to by the pvKeyInfoSpec parameter. Here are some possible combinations.

DWKEY IN FEC P VKEY IN FO SP EC

CRYPT_XML_KEYINFO_SPEC_NONE Is set to NULL

CRYPT_XML_KEYINFO_SPEC_ENCODED Points to a CRYPT_XML_BLOB structure

CRYPT_XML_KEYINFO_SPEC_PARAM Points to a CRYPT_XML_KEYINFO_PARAM structure

[in, optional] pvKeyInfoSpec

A pointer to a structure, the type of which is determined by the value of the dwKeyInfoSpec parameter.
[in] pSignatureMethod

A pointer to a CRYPT_XML_ALGORITHM structure that specifies the signature method.

[in] pCanonicalization

A pointer to a CRYPT_XML_ALGORITHM structure that specifies the canonicalization method.

Return value
If the function succeeds, the function returns zero.
If the function fails, it returns an HRESULT value that indicates the error.

Remarks
If a certificate cannot be found CryptXmlSign will create a UI for certificate selection. If this window is generated
from a process running in session 0, the application may unexpectedly terminate.

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]
Target Platform Windows

Header cryptxml.h

Librar y Cryptxml.lib

DLL Cryptxml.dll
 CryptXmlVerifySignature function (cryptxml.h)
7/2/2022 • 2 minutes to read • Edit Online

The Cr yptXmlVerifySignature function performs a cryptographic signature validation of a SignedInfo

element.

Syntax
HRESULT CryptXmlVerifySignature(
[in] HCRYPTXML hSignature,
[in, optional] BCRYPT_KEY_HANDLE hKey,
DWORD dwFlags
);

Parameters
[in] hSignature

The handle of a Signature element.

[in, optional] hKey

The handle of the public key to use to verify the signature value on the SignedInfo element. This parameter
must be NULL for HMAC-based signature algorithms.
dwFlags

A DWORD value that controls which implementations are used. This parameter can be one of the following
values.

VA L UE M EA N IN G

Only default implementations for the signature and digest

CRYPT_XML_FL AG_DISABLE_EXTENSIONS are used. When this flag is set, no other registered
0x10000000 extensions are loaded.

Return value
If the function succeeds, the function returns zero.
If the function fails, it returns an HRESULT value that indicates the error.

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Target Platform Windows

Header cryptxml.h

Librar y Cryptxml.lib

DLL Cryptxml.dll
 PFN_CRYPT_XML_CREATE_TRANSFORM callback
function (cryptxml.h)
7/2/2022 • 2 minutes to read • Edit Online

The PFN_CRYPT_XML_CREATE_TRANSFORM callback function creates a transform for a specified data provider.

Syntax
PFN_CRYPT_XML_CREATE_TRANSFORM PfnCryptXmlCreateTransform;

HRESULT PfnCryptXmlCreateTransform(
[in] const CRYPT_XML_ALGORITHM *pTransform,
[in] CRYPT_XML_DATA_PROVIDER *pProviderIn,
[out] CRYPT_XML_DATA_PROVIDER *pProviderOut
)
{...}

Parameters
[in] pTransform

A CRYPT_XML_ALGORITHM structure that specifies the transform to apply.

[in] pProviderIn

A pointer to a CRYPT_XML_DATA_PROVIDER structure that specifies the data provider to use as input for the
transform.
[out] pProviderOut

A pointer to a CRYPT_XML_DATA_PROVIDER structure to receive the data provider of the transform.

Return value
If the function succeeds, the function returns zero.
If the function fails, it returns an HRESULT value that indicates the error.

Remarks
In the transform chain, the output of a transform is the input of the next transform in the chain.
The implementation of the callback function is responsible for calling the provider close function on the input
transform to release the input provider.

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Target Platform Windows

Header cryptxml.h
 PFN_CRYPT_XML_DATA_PROVIDER_CLOSE
callback function (cryptxml.h)
7/2/2022 • 2 minutes to read • Edit Online

The PFN_CRYPT_XML_DATA_PROVIDER_CLOSE callback function releases the data provider.

Syntax
PFN_CRYPT_XML_DATA_PROVIDER_CLOSE PfnCryptXmlDataProviderClose;

HRESULT PfnCryptXmlDataProviderClose(
[in, out] void *pvCallbackState
)
{...}

Parameters
[in, out] pvCallbackState

An application defined argument for the callback function.

Return value
If the function succeeds, the function returns zero.
If the function fails, it returns an HRESULT value that indicates the error.

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Target Platform Windows

Header cryptxml.h
 PFN_CRYPT_XML_DATA_PROVIDER_READ callback
function (cryptxml.h)
7/2/2022 • 2 minutes to read • Edit Online

The PFN_CRYPT_XML_DATA_PROVIDER_READ callback function reads XML data.

Syntax
PFN_CRYPT_XML_DATA_PROVIDER_READ PfnCryptXmlDataProviderRead;

HRESULT PfnCryptXmlDataProviderRead(
[in, out] void *pvCallbackState,
[out] BYTE *pbData,
[in] ULONG cbData,
[out] ULONG *pcbRead
)
{...}

Parameters
[in, out] pvCallbackState

A pointer to an application defined argument that is passed to the calling function.

[out] pbData

A pointer to the buffer that receives the data to be read.

[in] cbData

The size, in bytes, of the data to be read.

[out] pcbRead

A pointer to a variable that receives the number of bytes actually read.

Return value
The PFN_CRYPT_XML_DATA_PROVIDER_READ callback function returns a value when one of the following
conditions occurs:
A write operation completes on the data provider
The number of bytes requested is read
An error occurs
If the function succeeds, the function returns NO_ERROR.
If the function fails, it returns an HRESULT value that indicates the error.
If the value of pcbRead equals zero, then there is no more data available.

Remarks
The callback function does not return a value unless the number of bytes specified in cbData is available or the
last block of data has been read.

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Target Platform Windows

Header cryptxml.h
 PFN_CRYPT_XML_ENUM_ALG_INFO callback
function (cryptxml.h)
7/2/2022 • 2 minutes to read • Edit Online

The PFN_CRYPT_XML_ENUM_ALG_INFO callback function enumerates predefined and registered

CRYPT_XML_ALGORITHM_INFO entries.

Syntax
PFN_CRYPT_XML_ENUM_ALG_INFO PfnCryptXmlEnumAlgInfo;

BOOL PfnCryptXmlEnumAlgInfo(
[in] const CRYPT_XML_ALGORITHM_INFO *pInfo,
[in, out, optional] void *pvArg
)
{...}

Parameters
[in] pInfo

A pointer to a CRYPT_XML_ALGORITHM_INFO structure.

[in, out, optional] pvArg

A pointer to an argument that is passed to the callback function from the calling function.

Return value
If the function succeeds, the function returns TRUE .
If the function fails, it returns FALSE .

Remarks
If the callback function returns FALSE , then stop the enumeration.
This function enumerates either the predefined and registered entries or the structures identified by a selected
URI group.

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Target Platform Windows

Header cryptxml.h
 PFN_CRYPT_XML_WRITE_CALLBACK callback
function (cryptxml.h)
7/2/2022 • 2 minutes to read • Edit Online

The PFN_CRYPT_XML_WRITE_CALLBACK callback function writes XML data.

Syntax
PFN_CRYPT_XML_WRITE_CALLBACK PfnCryptXmlWriteCallback;

HRESULT PfnCryptXmlWriteCallback(
[in, out] void *pvCallbackState,
[in] const BYTE *pbData,
ULONG cbData
)
{...}

Parameters
[in, out] pvCallbackState

A pointer to an argument that is passed to the callback function pointed to by the pfnWrite parameter of the
CryptXmlDllEncodeAlgorithm function.
[in] pbData

A pointer to a block of data to be written.

cbData

The size, in bytes, of the data pointed to by the pbData parameter.

Return value
If the function succeeds, the function returns zero.
If the function fails, it returns an HRESULT value that indicates the error.

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Target Platform Windows

Header cryptxml.h
 diagnosticdataquery.h header
7/2/2022 • 3 minutes to read • Edit Online

This header is used by Security and Identity. For more information, see:
Security and Identity
diagnosticdataquery.h contains the following programming interfaces:

Functions

DdqCancelDiagnosticRecordOperation

Cancels all outstanding Diagnostic Data Query API internal query operations for this session. This can be called from another
thread to interrupt long running Query APIs.

DdqCloseSession

Closes a Diagnostic Data Query session handle.

DdqCreateSession

Creates a Diagnostic Data Query API session handle to be used to uniquely identify a Diagnostic Data Query session.

DdqExtractDiagnosticReport

Used for retrieving Windows Error Reporting reports, this API extracts cabs to destination path specified. If the error report
does not contain any cabs, no work is performed.

DdqFreeDiagnosticRecordLocaleTags

Frees memory allocated for tag information referenced by HDIAGNOSTIC_EVENT_TAG_DESCRIPTION handle.

DdqFreeDiagnosticRecordPage

Frees memory allocated for the diagnostic record page referenced by HDIAGNOSTIC_RECORD handle.

DdqFreeDiagnosticRecordProducerCategories

Frees memory allocated for set of categories and the text representation of the categories referenced by
HDIAGNOSTIC_EVENT_CATEGORY_DESCRIPTION handle.

DdqFreeDiagnosticRecordProducers

Frees memory allocated for the set of producers referenced by HDIAGNOSTIC_EVENT_PRODUCER_DESCRIPTION handle.

DdqFreeDiagnosticReport

Frees memory allocated for error reports referenced by HDIAGNOSTIC_REPORT_DATA handle.

DdqGetDiagnosticDataAccessLevelAllowed

Returns the highest available data access level for the API caller. This can be NoData, CurrentUserData or AllUserData.

DdqGetDiagnosticRecordAtIndex

Fetches diagnostic data record information at the specified index in the resource pointed to by the
HDIAGNOSTIC_DATA_RECORD handle.

DdqGetDiagnosticRecordBinaryDistribution

Fetches binary name and associated estimated total upload of Diagnostic Data Events volume in bytes for top N noisiest
binaries based on total estimated upload size, where N is the value passed in for topNBinaries.

DdqGetDiagnosticRecordCategoryAtIndex

Fetches a diagnostic record category at the specified index in the resource pointed to by the
HDIAGNOSTIC_DATA_EVENT_CATEGORY_DESCRIPTION handle.

DdqGetDiagnosticRecordCategoryCount

Fetches the number (size) of diagnostic record categories in the resource pointed by the
HDIAGNOSTIC_EVENT_CATEGORY_DESCRIPTION handle.

DdqGetDiagnosticRecordCount

Fetches number (size) of elements in the resource pointed to by the HDIAGNOSTIC_DATA_RECORD handle.

DdqGetDiagnosticRecordLocaleTagAtIndex

Fetches tag description at the specified index in the resource pointed to by the
HDIAGNOSTIC_DATA_EVENT_TAG_DESCRIPTION handle.

DdqGetDiagnosticRecordLocaleTagCount

Fetches the number (size) of tags in the resource pointed to by the HDIAGNOSTIC_DATA_EVENT_TAG_DESCRIPTION handle.

DdqGetDiagnosticRecordLocaleTags

Fetches information for all known tags under the specified locale and provides a handle,
HDIAGNOSTIC_EVENT_TAG_DESCRIPTION, to the data. An example locale would be “en-US”. An example return value is a
DIAGNOSTIC_EVENT_TAG_DESCRIPTION resource that contains the following data: tag: 11, name: “Device Connectivity and
Configuration” and description: “Data that describes the connections and configuration of the devices connected to the service
and the network, including device identifiers (e.g IP addresses) configuration, setting and performance”.

DdqGetDiagnosticRecordPage

Fetches a page (batch) of filtered records. The filtering on records returned is performed internally using the input parameters
DIAGNOSTIC_DATA_SEARCH_CRITERIA searchCriteria, pageRecordCount, offset and baseRowId.

DdqGetDiagnosticRecordPayload

Fetches the payload text for the event record specified by rowId.
DdqGetDiagnosticRecordProducerAtIndex

Fetches the description of a producer at the specified index in the resource pointed to by the
HDIAGNOSTIC_EVENT_PRODUCER_DESCRIPTION handle.

DdqGetDiagnosticRecordProducerCategories

Producers and categories have a hierarchical relationship--that is, categories belong to producers. This function fetches the
available Category IDs and text representation of categories for a given diagnostic Producer Name.

DdqGetDiagnosticRecordProducerCount

Fetches the number (size) of producers in the resource pointed to by the HDIAGNOSTIC_EVENT_PRODUCER_DESCRIPTION.

DdqGetDiagnosticRecordProducers

Fetches Diagnostic Data Producers available for a Diagnostic Data Query session.

DdqGetDiagnosticRecordStats

Fetches the filtered event transcript Diagnostic Data record stats. The filtering on statistics returned is performed using the
input parameter, DIAGNOSTIC_DATA_SEARCH_CRITERIA filter. The record state describes how many records matching the
search criteria are available, and returns parameters used for further querying of data. One of the uses of this API is to check if
there have been changes since the last time data was queried for. A change in the output parameters indicate a change in
state of the event transcript record state.

DdqGetDiagnosticRecordSummary

Fetches general statistics about the diagnostic data records, filterable by producer.

DdqGetDiagnosticRecordTagDistribution

Fetches Diagnostic Data Events per privacy tag event distribution statistics based on the specified producer names.

DdqGetDiagnosticReport

Fetches error reports uploaded or enqueued for upload from this PC via HDIAGNOSTIC_REPORT_DATA handle.

DdqGetDiagnosticReportAtIndex

Fetches an error report and its information at the specified index in the resource pointed to by the
HDIAGNOSTIC_REPORT_DATA handle.

DdqGetDiagnosticReportCount

Fetches the number (size) of error reports in the resource pointed to by HDIAGNOSTIC_REPORT_DATA handle.

DdqGetDiagnosticReportStoreReportCount

Fetches the number (size) of reports stored in the requested store.

DdqGetSessionAccessLevel

Returns the data access level of the current Diagnostic Data Query session.
DdqGetTranscriptConfiguration

Gets event transcript configuration, such as maximum storage size and hours of data history.

DdqIsDiagnosticRecordSampledIn

Fetches the sampled-in state of the device for an event.

DdqSetTranscriptConfiguration

Sets event transcript configuration, such as maximum storage size and hours of data history. Note that setting the
configuration will fail if the user is not elevated.
 DdqCancelDiagnosticRecordOperation function
(diagnosticdataquery.h)
7/2/2022 • 2 minutes to read • Edit Online

Cancels all outstanding Diagnostic Data Query API internal query operations for this session. This can be called
from another thread to interrupt long running Query APIs.

Syntax
HRESULT DdqCancelDiagnosticRecordOperation(
HDIAGNOSTIC_DATA_QUERY_SESSION hSession
);

Parameters
hSession

Type: HANDLE Handle to the Diagnostic Data Query session.

Return value
Type: HRESULT Returns S_OK on successful completion.

Requirements

Minimum suppor ted client Windows 10, version 2004 (10.0; Build 19041)

Minimum suppor ted ser ver Windows Server, version 2004 (10.0; Build 19041)

Header diagnosticdataquery.h
 DdqCloseSession function (diagnosticdataquery.h)
7/2/2022 • 2 minutes to read • Edit Online

Closes a Diagnostic Data Query session handle.

Syntax
HRESULT DdqCloseSession(
HDIAGNOSTIC_DATA_QUERY_SESSION hSession
);

Parameters
hSession

Type: HANDLE Handle to the Diagnostic Data Query session.

Return value
Type: HRESULT Returns S_OK on successful completion.

Requirements

Minimum suppor ted client Windows 10, version 2004 (10.0; Build 19041)

Minimum suppor ted ser ver Windows Server, version 2004 (10.0; Build 19041)

Header diagnosticdataquery.h
 DdqCreateSession function (diagnosticdataquery.h)
7/2/2022 • 2 minutes to read • Edit Online

Creates a Diagnostic Data Query API session handle to be used to uniquely identify a Diagnostic Data Query
session.

Syntax
HRESULT DdqCreateSession(
DdqAccessLevel accessLevel,
HDIAGNOSTIC_DATA_QUERY_SESSION *hSession
);

Parameters
accessLevel

Type: DdqAccessLevel The access level desired for this session.

hSession

Type: HANDLE This output parameter is a handle to the created Diagnostic Data Query session.

Return value
Type: HRESULT Returns S_OK on successful completion.

Requirements

Minimum suppor ted client Windows 10, version 2004 (10.0; Build 19041)

Minimum suppor ted ser ver Windows Server, version 2004 (10.0; Build 19041)

Header diagnosticdataquery.h
 DdqExtractDiagnosticReport function
(diagnosticdataquery.h)
7/2/2022 • 2 minutes to read • Edit Online

Used for retrieving Windows Error Reporting reports, this API extracts cabs to destination path specified. If the
error report does not contain any cabs, no work is performed.

Syntax
HRESULT DdqExtractDiagnosticReport(
HDIAGNOSTIC_DATA_QUERY_SESSION hSession,
UINT32 reportStoreType,
PCWSTR reportKey,
PCWSTR destinationPath
);

Parameters
hSession

Type: HANDLE Handle to the current Diagnostic Data Query session

reportStoreType

Type: UINT32 The type of report store to extract from. See remarks.
reportKey

Type: PCWSTR A pointer to the report key string. See remarks.

destinationPath

Type: PCWSTR The destination path the report should be extracted to.

Return value
Type: HRESULT Returns S_OK on successful completion.

Remarks
For report store types, see the WER APIs . For report keys, see the WER APIs .

Requirements

Minimum suppor ted client Windows 10, version 2004 (10.0; Build 19041)

Minimum suppor ted ser ver Windows Server, version 2004 (10.0; Build 19041)

Header diagnosticdataquery.h
 DdqFreeDiagnosticRecordLocaleTags function
(diagnosticdataquery.h)
7/2/2022 • 2 minutes to read • Edit Online

Frees memory allocated for tag information referenced by HDIAGNOSTIC_EVENT_TAG_DESCRIPTION handle.

Syntax
HRESULT DdqFreeDiagnosticRecordLocaleTags(
HDIAGNOSTIC_EVENT_TAG_DESCRIPTION hTagDescription
);

Parameters
hTagDescription

Type: HANDLE Handle to the resource that contains the tag descriptions being freed.

Return value
Type: HRESULT Returns S_OK on successful completion.

Remarks
For more details about the tag description data type, see our
DIAGNOSTIC_DATA_EVENT_TAG_DESCRIPTION .

Requirements

Minimum suppor ted client Windows 10, version 2004 (10.0; Build 19041)

Minimum suppor ted ser ver Windows Server, version 2004 (10.0; Build 19041)

Header diagnosticdataquery.h
 DdqFreeDiagnosticRecordPage function
(diagnosticdataquery.h)
7/2/2022 • 2 minutes to read • Edit Online

Frees memory allocated for the diagnostic record page referenced by HDIAGNOSTIC_RECORD handle.

Syntax
HRESULT DdqFreeDiagnosticRecordPage(
HDIAGNOSTIC_RECORD hRecord
);

Parameters
hRecord

Type: HANDLE Handle to the resource that contains the set of diagnostic records to be freed.

Return value
Type: HRESULT Returns S_OK on successful completion.

Remarks
For more information about the DIAGNOSTIC_RECORD datatype, see here .

Requirements

Minimum suppor ted client Windows 10, version 2004 (10.0; Build 19041)

Minimum suppor ted ser ver Windows Server, version 2004 (10.0; Build 19041)

Header diagnosticdataquery.h
 DdqFreeDiagnosticRecordProducerCategories
function (diagnosticdataquery.h)
7/2/2022 • 2 minutes to read • Edit Online

Frees memory allocated for set of categories and the text representation of the categories referenced by
HDIAGNOSTIC_EVENT_CATEGORY_DESCRIPTION handle.

Syntax
HRESULT DdqFreeDiagnosticRecordProducerCategories(
HDIAGNOSTIC_EVENT_CATEGORY_DESCRIPTION hCategoryDescription
);

Parameters
hCategoryDescription

Type: HANDLE Handle to the resource that contains the set of categories and their descriptions to be freed.

Return value
Type: HRESULT Returns S_OK on successful completion.

Remarks
For more information about the data type DIAGNOSTIC_EVENT_CATEGORY_DESCRIPTION, see here .

Requirements

Minimum suppor ted client Windows 10, version 2004 (10.0; Build 19041)

Minimum suppor ted ser ver Windows Server, version 2004 (10.0; Build 19041)

Header diagnosticdataquery.h
 DdqFreeDiagnosticRecordProducers function
(diagnosticdataquery.h)
7/2/2022 • 2 minutes to read • Edit Online

Frees memory allocated for the set of producers referenced by

HDIAGNOSTIC_EVENT_PRODUCER_DESCRIPTION handle.

Syntax
HRESULT DdqFreeDiagnosticRecordProducers(
HDIAGNOSTIC_EVENT_PRODUCER_DESCRIPTION hProducerDescription
);

Parameters
hProducerDescription

Type: HANDLE Handle to the resource that contains the set of producers to be freed.

Return value
Type: HRESULT Returns S_OK on successful completion.

Remarks
For information about the data type DIAGNOSTIC_EVENT_PRODUCER_DESCRIPTION, see here

Requirements

Minimum suppor ted client Windows 10, version 2004 (10.0; Build 19041)

Minimum suppor ted ser ver Windows Server, version 2004 (10.0; Build 19041)

Header diagnosticdataquery.h
 DdqFreeDiagnosticReport function
(diagnosticdataquery.h)
7/2/2022 • 2 minutes to read • Edit Online

Frees memory allocated for error reports referenced by HDIAGNOSTIC_REPORT_DATA handle.

Syntax
HRESULT DdqFreeDiagnosticReport(
HDIAGNOSTIC_REPORT hReport
);

Parameters
hReport

Type: HANDLE The handle to the resource that contains the set of error reports to be freed.

Return value
Type: HRESULT Returns S_OK on successful completion.

Remarks
For information the datatype DIAGNOSTIC_REPORT_DATA, see here

Requirements

Minimum suppor ted client Windows 10, version 2004 (10.0; Build 19041)

Minimum suppor ted ser ver Windows Server, version 2004 (10.0; Build 19041)

Header diagnosticdataquery.h
 DdqGetDiagnosticDataAccessLevelAllowed function
(diagnosticdataquery.h)
7/2/2022 • 2 minutes to read • Edit Online

Returns the highest available data access level for the API caller. This can be NoData, CurrentUserData or
AllUserData.

Syntax
HRESULT DdqGetDiagnosticDataAccessLevelAllowed(
DdqAccessLevel *accessLevel
);

Parameters
accessLevel

Type: DdqAccessLevel* This output parameter is a pointer to the highest access level available for the API
caller.

Return value
Type: HRESULT Returns S_OK on successful completion.

Requirements

Minimum suppor ted client Windows 10, version 2004 (10.0; Build 19041)

Minimum suppor ted ser ver Windows Server, version 2004 (10.0; Build 19041)

Header diagnosticdataquery.h
 DdqGetDiagnosticRecordAtIndex function
(diagnosticdataquery.h)
7/2/2022 • 2 minutes to read • Edit Online

Fetches diagnostic data record information at the specified index in the resource pointed to by the
HDIAGNOSTIC_DATA_RECORD handle.

Syntax
HRESULT DdqGetDiagnosticRecordAtIndex(
HDIAGNOSTIC_RECORD hRecord,
UINT32 index,
DIAGNOSTIC_DATA_RECORD *record
);

Parameters
hRecord

Type: HANDLE Handle to the resource that contains the list of DIAGNOSTIC_DATA_RECORD items.
index

Type: UINT32 Index of the record to be fetched.

record

Type: DIAGNOSTIC_DATA_RECORD* This output parameter is a pointer to the record at the specified index.

Return value
Type: HRESULT Returns S_OK on successful completion.

Requirements

Minimum suppor ted client Windows 10, version 2004 (10.0; Build 19041)

Minimum suppor ted ser ver Windows Server, version 2004 (10.0; Build 19041)

Header diagnosticdataquery.h
 DdqGetDiagnosticRecordBinaryDistribution
function (diagnosticdataquery.h)
7/2/2022 • 2 minutes to read • Edit Online

Fetches binary name and associated estimated total upload of Diagnostic Data Events volume in bytes for top N
noisiest binaries based on total estimated upload size, where N is the value passed in for topNBinaries.

Syntax
HRESULT DdqGetDiagnosticRecordBinaryDistribution(
HDIAGNOSTIC_DATA_QUERY_SESSION hSession,
PCWSTR *producerNames,
UINT32 producerNameCount,
UINT32 topNBinaries,
DIAGNOSTIC_DATA_EVENT_BINARY_STATS **binaryStats,
UINT32 *statCount
);

Parameters
hSession

Type: HANDLE A handle to the current Diagnostic Data Query session.

producerNames

Type: PCWSTR* Pointer to the set of known producers names.

producerNameCount

Type: UINT32 Number of producer names

topNBinaries

Type: UINT32 The number of noisiest records to return

binaryStats

Type: DIAGNOSTIC_DATA_EVENT_BINARY_STATS This output parameter is the pointer to the list of top N
noisiest DIAGNOSTIC_DATA_EVENT_BINARY_STATS items.
statCount

Type: UINT32 The number of items in binaryStats.

Return value
Type: HRESULT Returns S_OK on successful completion.

Requirements
Minimum suppor ted client Windows 10, version 2004 (10.0; Build 19041)

Minimum suppor ted ser ver Windows Server, version 2004 (10.0; Build 19041)

Header diagnosticdataquery.h
 DdqGetDiagnosticRecordCategoryAtIndex function
(diagnosticdataquery.h)
7/2/2022 • 2 minutes to read • Edit Online

Fetches a diagnostic record category at the specified index in the resource pointed to bythe
HDIAGNOSTIC_DATA_EVENT_CATEGORY_DESCRIPTION handle.

Syntax
HRESULT DdqGetDiagnosticRecordCategoryAtIndex(
HDIAGNOSTIC_EVENT_CATEGORY_DESCRIPTION hCategoryDescription,
UINT32 index,
DIAGNOSTIC_DATA_EVENT_CATEGORY_DESCRIPTION *categoryDescription
);

Parameters
hCategoryDescription

Type: HANDLE Handle to the resource that contains the list of categories and their descriptions
index

Type: UINT32 The index of the category to be fetched.

categoryDescription

Type: DIAGNOSTIC_DATA_EVENT_CATEGORY_DESCRIPTION This outpoint parameter is a pointer to the

category and its description that was fetched.

Return value
Type: HRESULT Returns S_OK on successful completion.

Remarks
See DIAGNOSTIC_DATA_EVENT_CATEGORY_DESCRIPTION for documentation on how a category is
defined.

Requirements

Minimum suppor ted client Windows 10, version 2004 (10.0; Build 19041)

Minimum suppor ted ser ver Windows Server, version 2004 (10.0; Build 19041)

Header diagnosticdataquery.h
 DdqGetDiagnosticRecordCategoryCount function
(diagnosticdataquery.h)
7/2/2022 • 2 minutes to read • Edit Online

Fetches the number (size) of diagnostic record categories in the resource pointed by the
HDIAGNOSTIC_EVENT_CATEGORY_DESCRIPTION handle.

Syntax
HRESULT DdqGetDiagnosticRecordCategoryCount(
HDIAGNOSTIC_EVENT_CATEGORY_DESCRIPTION hCategoryDescription,
UINT32 *categoryDescriptionCount
);

Parameters
hCategoryDescription

Type: HANDLE Handle to the resource that contains the list of categories and their descriptions.
categoryDescriptionCount

Type: UINT32* This output parameter is a pointer to the number of categories in the diagnostic record category
array.

Return value
Type: HRESULT Returns S_OK on successful completion.

Remarks
See DIAGNOSTIC_DATA_EVENT_CATEGORY_DESCRIPTION for documentation on how a category is
defined.

Requirements

Minimum suppor ted client Windows 10, version 2004 (10.0; Build 19041)

Minimum suppor ted ser ver Windows Server, version 2004 (10.0; Build 19041)

Header diagnosticdataquery.h
 DdqGetDiagnosticRecordCount function
(diagnosticdataquery.h)
7/2/2022 • 2 minutes to read • Edit Online

Fetches number (size) of diagnostic records in the resource pointed to by the HDIAGNOSTIC_DATA_RECORD
handle.

Syntax
HRESULT DdqGetDiagnosticRecordCount(
HDIAGNOSTIC_RECORD hRecord,
UINT32 *recordCount
);

Parameters
hRecord

Type: HANDLE Handle to the resource that contains the DIAGNOSTIC_DATA_RECORD list.
recordCount

Type: UINT32 Number of items in the DIAGNOSTIC_DATA_RECORD list.

Return value
Type: HRESULT Returns S_OK on successful completion.

Remarks
For more information about diagnostic data record data type, see DIAGNOSTIC_DATA_RECORD

Requirements

Minimum suppor ted client Windows 10, version 2004 (10.0; Build 19041)

Minimum suppor ted ser ver Windows Server, version 2004 (10.0; Build 19041)

Header diagnosticdataquery.h
 DdqGetDiagnosticRecordLocaleTagAtIndex function
(diagnosticdataquery.h)
7/2/2022 • 2 minutes to read • Edit Online

Fetches tag description at the specified index in the resource pointed to by the
HDIAGNOSTIC_DATA_EVENT_TAG_DESCRIPTION resource.

Syntax
HRESULT DdqGetDiagnosticRecordLocaleTagAtIndex(
HDIAGNOSTIC_EVENT_TAG_DESCRIPTION hTagDescription,
UINT32 index,
DIAGNOSTIC_DATA_EVENT_TAG_DESCRIPTION *tagDescription
);

Parameters
hTagDescription

Type: HANDLE Handle to the resource that contains the list of tag descriptions.
index

Type: UINT32 The index of the tag description to be fetched.

tagDescription

Type: DIAGNOSTIC_DATA_EVENT_TAG_DESCRIPTION* This outpoint parameter is a pointer to the tag

description that was fetched.

Return value
Type: HRESULT Returns S_OK on successful completion.

Requirements

Minimum suppor ted client Windows 10, version 2004 (10.0; Build 19041)

Minimum suppor ted ser ver Windows Server, version 2004 (10.0; Build 19041)

Header diagnosticdataquery.h
 DdqGetDiagnosticRecordLocaleTagCount function
(diagnosticdataquery.h)
7/2/2022 • 2 minutes to read • Edit Online

Fetches the number (size) of tags in the resource pointed to by the

HDIAGNOSTIC_DATA_EVENT_TAG_DESCRIPTION handle.

Syntax
HRESULT DdqGetDiagnosticRecordLocaleTagCount(
HDIAGNOSTIC_EVENT_TAG_DESCRIPTION hTagDescription,
UINT32 *tagDescriptionCount
);

Parameters
hTagDescription

Type: HANDLE Handle to the resource that contains the list of tag descriptions.
tagDescriptionCount

Type: UINT32 This output parameter is the number of tags in the list of tag descriptions.

Return value
Type: HRESULT Returns S_OK on successful completion.

Remarks
For more details about the tag description data type, see our
DIAGNOSTIC_DATA_EVENT_TAG_DESCRIPTION . For details about what a privacy tag is, see our privacy
statement .

Requirements

Minimum suppor ted client Windows 10, version 2004 (10.0; Build 19041)

Minimum suppor ted ser ver Windows Server, version 2004 (10.0; Build 19041)

Header diagnosticdataquery.h
 DdqGetDiagnosticRecordLocaleTags function
(diagnosticdataquery.h)
7/2/2022 • 2 minutes to read • Edit Online

Fetches information for all known tags under the specified locale and provides a handle,
HDIAGNOSTIC_EVENT_TAG_DESCRIPTION, to the data. An example locale would be “en-US”. An example return
value is a DIAGNOSTIC_EVENT_TAG_DESCRIPTION resource that contains the following data: tag: 11, name:
“Device Connectivity and Configuration” and description: “Data that describes the connections and configuration
of the devices connected to the service and the network, including device identifiers (e.g IP addresses)
configuration, setting and performance”.

Syntax
HRESULT DdqGetDiagnosticRecordLocaleTags(
HDIAGNOSTIC_DATA_QUERY_SESSION hSession,
PCWSTR locale,
HDIAGNOSTIC_EVENT_TAG_DESCRIPTION *hTagDescription
);

Parameters
hSession

Type: HANDLE Handle to the Diagnostic Data Query session.

locale

Type: PCWSTR The locale for the tag descriptions.

hTagDescription

Type: HANDLE* This output parameter is a pointer to the handle for the resource that contains the list of tag
descriptions. The resource is of the form DIAGNOSTIC_DATA_EVENT_TAG_DESCRIPTION and contains the tag
name, description and the numeric tag value.

Return value
Type: HRESULT Returns S_OK on successful completion.

Remarks
For more details about the tag description data type, see our
DIAGNOSTIC_DATA_EVENT_TAG_DESCRIPTION .

Requirements

Minimum suppor ted client Windows 10, version 2004 (10.0; Build 19041)
Minimum suppor ted ser ver Windows Server, version 2004 (10.0; Build 19041)

Header diagnosticdataquery.h
 DdqGetDiagnosticRecordPage function
(diagnosticdataquery.h)
7/2/2022 • 2 minutes to read • Edit Online

Fetches a page (batch) of filtered records. The filtering on records returned is performed internally using the
input parameters DIAGNOSTIC_DATA_SEARCH_CRITERIA searchCriteria, pageRecordCount, offset and
baseRowId.

Syntax
HRESULT DdqGetDiagnosticRecordPage(
HDIAGNOSTIC_DATA_QUERY_SESSION hSession,
DIAGNOSTIC_DATA_SEARCH_CRITERIA * const searchCriteria,
UINT32 offset,
UINT32 pageRecordCount,
INT64 baseRowId,
HDIAGNOSTIC_RECORD *hRecord
);

Parameters
hSession

Type: HANDLE Handle to the Diagnostic Data Query session.

searchCriteria

Type: DIAGNOSTIC_DATA_SEARCH_CRITERIA* Pointer to the resource that contains the search criteria for
this operation. This resource contains criteria such as producers, categories, and tags.
offset

Type: UINT32 Filters results by returning records with rowId that start at the offset from the baseRowId.
pageRecordCount

Type: UINT32 The number of records in a desired record page

baseRowId

Type: INT64 Filters out new records by returning only records with rowId value less than or equal to baseRowId
(this is useful if querying code wants to limit results to only events that were available at the time of
DdqGetDiagnosticRecordStats call. The maxRowId parameter can be used as baseRowId). No filtering is applied
if –1 is passed for baseRowId.
hRecord

Type: HANDLE* This output parameter is a pointer to the handle for the resource that contains the list of
matching records.

Return value
Type: HRESULT Returns S_OK on successful completion.
Requirements

Minimum suppor ted client Windows 10, version 2004 (10.0; Build 19041)

Minimum suppor ted ser ver Windows Server, version 2004 (10.0; Build 19041)

Header diagnosticdataquery.h
 DdqGetDiagnosticRecordPayload function
(diagnosticdataquery.h)
7/2/2022 • 2 minutes to read • Edit Online

Fetches the payload text for the event record specified by rowId.

Syntax
HRESULT DdqGetDiagnosticRecordPayload(
HDIAGNOSTIC_DATA_QUERY_SESSION hSession,
INT64 rowId,
PCWSTR *payload
);

Parameters
hSession

Type: HANDLE Handle to the Diagnostic Data Query session.

rowId

Type: INT64 The row id for the event record of interest.

payload

Type: PCWSTR* This output parameter is a pointer to the payload text.

Return value
Type: HRESULT Returns S_OK on successful completion.

Requirements

Minimum suppor ted client Windows 10, version 2004 (10.0; Build 19041)

Minimum suppor ted ser ver Windows Server, version 2004 (10.0; Build 19041)

Header diagnosticdataquery.h
 DdqGetDiagnosticRecordProducerAtIndex function
(diagnosticdataquery.h)
7/2/2022 • 2 minutes to read • Edit Online

Fetches the description of a producer at the specified index in the resource pointed to by the
HDIAGNOSTIC_EVENT_PRODUCER_DESCRIPTION handle.

Syntax
HRESULT DdqGetDiagnosticRecordProducerAtIndex(
HDIAGNOSTIC_EVENT_PRODUCER_DESCRIPTION hProducerDescription,
UINT32 index,
DIAGNOSTIC_DATA_EVENT_PRODUCER_DESCRIPTION *producerDescription
);

Parameters
hProducerDescription

Type: HANDLE Handle to the resource that contains set of producers.

index

Type: UINT32 The index of the producer to fetch.

producerDescription

Type: DIAGNOSTIC_DATA_EVENT_PRODUCER_DESCRIPTION* This output parameter is the pointer to the

resource that describes the fetched producer.

Return value
Type: HRESULT Returns S_OK on successful completion.

Remarks
See DIAGNOSTIC_DATA_EVENT_PRODUCER_DESCRIPTION for documentation on how a producer is
defined.

Requirements

Minimum suppor ted client Windows 10, version 2004 (10.0; Build 19041)

Minimum suppor ted ser ver Windows Server, version 2004 (10.0; Build 19041)

Header diagnosticdataquery.h
 DdqGetDiagnosticRecordProducerCategories
function (diagnosticdataquery.h)
7/2/2022 • 2 minutes to read • Edit Online

Producers and categories have a hierarchical relationship--that is, categories belong to producers. This function
fetches the available Category IDs and text representation of categories for a given diagnostic Producer Name.

Syntax
HRESULT DdqGetDiagnosticRecordProducerCategories(
HDIAGNOSTIC_DATA_QUERY_SESSION hSession,
PCWSTR producerName,
HDIAGNOSTIC_EVENT_CATEGORY_DESCRIPTION *hCategoryDescription
);

Parameters
hSession

Type: HANDLE Handle to the Diagnostic Data Query session.

producerName

Type: PCWSTR The name of the producer of interest.

hCategoryDescription

Type: HANDLE Handle to the resource that contains the list of categories and their descriptions that belong to
the given producer.

Return value
Type: HRESULT Returns S_OK on successful completion.

Remarks
See DIAGNOSTIC_DATA_EVENT_CATEGORY_DESCRIPTION for documentation on how a category is
defined.

Requirements

Minimum suppor ted client Windows 10, version 2004 (10.0; Build 19041)

Minimum suppor ted ser ver Windows Server, version 2004 (10.0; Build 19041)

Header diagnosticdataquery.h
 DdqGetDiagnosticRecordProducerCount function
(diagnosticdataquery.h)
7/2/2022 • 2 minutes to read • Edit Online

Fetches the number (size) of producers in the resource pointed to by the

HDIAGNOSTIC_EVENT_PRODUCER_DESCRIPTION.

Syntax
HRESULT DdqGetDiagnosticRecordProducerCount(
HDIAGNOSTIC_EVENT_PRODUCER_DESCRIPTION hProducerDescription,
UINT32 *producerDescriptionCount
);

Parameters
hProducerDescription

Type: HANDLE Handle to the resource that contains list of producers.

producerDescriptionCount

Type: UNINT32* This output parameter is a pointer to the number of producers in provided resource.

Return value
Type: HRESULT Returns S_OK on successful completion.

Remarks
See DIAGNOSTIC_DATA_EVENT_PRODUCER_DESCRIPTION for documentation on how a producer is
defined.

Requirements

Minimum suppor ted client Windows 10, version 2004 (10.0; Build 19041)

Minimum suppor ted ser ver Windows Server, version 2004 (10.0; Build 19041)

Header diagnosticdataquery.h
 DdqGetDiagnosticRecordProducers function
(diagnosticdataquery.h)
7/2/2022 • 2 minutes to read • Edit Online

Fetches Diagnostic Data Producers available for a Diagnostic Data Query session.

Syntax
HRESULT DdqGetDiagnosticRecordProducers(
HDIAGNOSTIC_DATA_QUERY_SESSION hSession,
HDIAGNOSTIC_EVENT_PRODUCER_DESCRIPTION *hProducerDescription
);

Parameters
hSession

Type: HANDLE Handle to the Diagnostic Data Query session.

hProducerDescription

Type: HANDLE* This output parameter is a pointer to the handle for the resource that contains the list of
producers.

Return value
Type: HRESULT Returns S_OK on successful completion.

Remarks
See DIAGNOSTIC_DATA_EVENT_PRODUCER_DESCRIPTION for documentation on how a producer is
defined.

Requirements

Minimum suppor ted client Windows 10, version 2004 (10.0; Build 19041)

Minimum suppor ted ser ver Windows Server, version 2004 (10.0; Build 19041)

Header diagnosticdataquery.h
 DdqGetDiagnosticRecordStats function
(diagnosticdataquery.h)
7/2/2022 • 2 minutes to read • Edit Online

Fetches the filtered event transcript Diagnostic Data record stats. The filtering on statistics returned is performed
using the input parameter, DIAGNOSTIC_DATA_SEARCH_CRITERIA filter. The record state describes how many
records matching the search criteria are available, and returns parameters used for further querying of data.
One of the uses of this API is to check if there have been changes since the last time data was queried for. A
change in the output parameters indicate a change in state of the event transcript record state.

Syntax
HRESULT DdqGetDiagnosticRecordStats(
HDIAGNOSTIC_DATA_QUERY_SESSION hSession,
DIAGNOSTIC_DATA_SEARCH_CRITERIA const *searchCriteria,
UINT32 *recordCount,
INT64 *minRowId,
INT64 *maxRowId
);

Parameters
hSession

Type: HANDLE Handle to the Diagnostic Data Query session.

searchCriteria

Type: DIAGNOSTIC_DATA_SEARCH_CRITERIA* Pointer to the resource that contains the search criteria for
this operation. This resource contains criteria such as producers, categories, and tags.
recordCount

Type: UINT32* This output parameter is the pointer to the number of records that match on the search criteria.
minRowId

Type: INT64* This output parameter is the pointer to the minimum row id of the record that matches on the
search criteria.
maxRowId

Type: INT64* This output parameter is the pointer to the maximum row id of the record that matches on the
search criteria.

Return value
Type: HRESULT Returns S_OK on successful completion.

Requirements
Minimum suppor ted client Windows 10, version 2004 (10.0; Build 19041)

Minimum suppor ted ser ver Windows Server, version 2004 (10.0; Build 19041)

Header diagnosticdataquery.h
 DdqGetDiagnosticRecordSummary function
(diagnosticdataquery.h)
7/2/2022 • 2 minutes to read • Edit Online

Fetches general statistics about the diagnostic data records, filterable by producer.

Syntax
HRESULT DdqGetDiagnosticRecordSummary(
HDIAGNOSTIC_DATA_QUERY_SESSION hSession,
const PCWSTR *producerNames,
UINT32 producerNameCount,
DIAGNOSTIC_DATA_GENERAL_STATS *generalStats
);

Parameters
hSession

Type: HANDLE Handle to the Diagnostic Data Query session.

producerNames

Type: PCWSTR* List of producer names to search for. A diagnostic data record that matches at least one of the
producer names is included as a result in this search criteria. Use nullptr for this value to indicate no filter by
producers.
producerNameCount

Type: UINT32 The number of producer names in the list of producer names to search for. Use 0 for this value
to indicate no filter by producers.
generalStats

Type: DIAGNOSTIC_DATA_GENERAL_STATS* This output parameter is a pointer to the resource that contains
information about the general statistics for the diagnostic data records.

Return value
Type: HRESULT Returns S_OK on successful completion.

Requirements

Minimum suppor ted client Windows 10, version 2004 (10.0; Build 19041)

Minimum suppor ted ser ver Windows Server, version 2004 (10.0; Build 19041)

Header diagnosticdataquery.h
 DdqGetDiagnosticRecordTagDistribution function
(diagnosticdataquery.h)
7/2/2022 • 2 minutes to read • Edit Online

Fetches Diagnostic Data Events per privacy tag event distribution statistics based on the specified producer
names.

Syntax
HRESULT DdqGetDiagnosticRecordTagDistribution(
HDIAGNOSTIC_DATA_QUERY_SESSION hSession,
PCWSTR *producerNames,
UINT32 producerNameCount,
DIAGNOSTIC_DATA_EVENT_TAG_STATS **tagStats,
UINT32 *statCount
);

Parameters
hSession

Type: HANDLE Handle to the Diagnostic Data Query session.

producerNames

Type: PCWSTR* List of producer names to search for. A diagnostic data record that matches at least one of the
producer names is included as a result in this search criteria. Use nullptr for this value to indicate no filter by
producers.
producerNameCount

Type: UINT32 The number of producer names in the list of producer names to search for. Use 0 for this value
to indicate no filter by producers.
tagStats

Type: DIAGNOSTIC_DATA_TAG_STATS** This output parameter is a pointer to a list of

DIAGNOSTIC_DATA_TAG_STATS items. Each item is a resource that contains information about a privacy tag and
the number of events that have that tag.
statCount

Type: UINT32 The number of items in the DIAGNOSTIC_DATA_TAG_STATS list.

Return value
Type: HRESULT Returns S_OK on successful completion.

Remarks
See our privacy statement for information about diagnostic data privacy tags. For more details about the tag
description data type, see our DIAGNOSTIC_DATA_EVENT_TAG_DESCRIPTION .
Requirements

Minimum suppor ted client Windows 10, version 2004 (10.0; Build 19041)

Minimum suppor ted ser ver Windows Server, version 2004 (10.0; Build 19041)

Header diagnosticdataquery.h
 DdqGetDiagnosticReport function
(diagnosticdataquery.h)
7/2/2022 • 2 minutes to read • Edit Online

Fetches error reports uploaded or enqueued for upload from this PC via HDIAGNOSTIC_REPORT_DATA handle.

Syntax
HRESULT DdqGetDiagnosticReport(
HDIAGNOSTIC_DATA_QUERY_SESSION hSession,
UINT32 reportStoreType,
HDIAGNOSTIC_REPORT *hReport
);

Parameters
hSession

Type: HANDLE Handle to the Diagnostic Data Query session.

reportStoreType

Type: UINT32 The type of report store to extract from. See remarks.
hReport

Type: HANDLE* This output parameter is a pointer to the handle for the resource that contains the known set of
problem reports.

Return value
Type: HRESULT Returns S_OK on successful completion.

Remarks
For report store types, see the WER APIs .

Requirements

Minimum suppor ted client Windows 10, version 2004 (10.0; Build 19041)

Minimum suppor ted ser ver Windows Server, version 2004 (10.0; Build 19041)

Header diagnosticdataquery.h
 DdqGetDiagnosticReportAtIndex function
(diagnosticdataquery.h)
7/2/2022 • 2 minutes to read • Edit Online

Fetches an error report and its information at the specified index in the resource pointed to by the
HDIAGNOSTIC_REPORT_DATA handle.

Syntax
HRESULT DdqGetDiagnosticReportAtIndex(
HDIAGNOSTIC_REPORT hReport,
UINT32 index,
DIAGNOSTIC_REPORT_DATA *report
);

Parameters
hReport

Type: HANDLE Handle to the resource with the set of problem reports.
index

Type: UINT32 The index of the error report to fetch.

report

Type: DIAGNOSTIC_DATA_REPORT_DATA* This output parameter is a pointer to the resource that contains
information about the fetched diagnostic report.

Return value
Type: HRESULT Returns S_OK on successful completion.

Requirements

Minimum suppor ted client Windows 10, version 2004 (10.0; Build 19041)

Minimum suppor ted ser ver Windows Server, version 2004 (10.0; Build 19041)

Header diagnosticdataquery.h
 DdqGetDiagnosticReportCount function
(diagnosticdataquery.h)
7/2/2022 • 2 minutes to read • Edit Online

Fetches the number (size) of error reports in the resource pointed to by HDIAGNOSTIC_REPORT_DATA handle.

Syntax
HRESULT DdqGetDiagnosticReportCount(
HDIAGNOSTIC_REPORT hReport,
UINT32 *reportCount
);

Parameters
hReport

Type: HANDLE Handle to the resource that contains the set of error reports.
reportCount

Type: UINT32* Pointer to the number of error reports.

Return value
Type: HRESULT Returns S_OK on successful completion.

Requirements

Minimum suppor ted client Windows 10, version 2004 (10.0; Build 19041)

Minimum suppor ted ser ver Windows Server, version 2004 (10.0; Build 19041)

Header diagnosticdataquery.h
 DdqGetDiagnosticReportStoreReportCount
function (diagnosticdataquery.h)
7/2/2022 • 2 minutes to read • Edit Online

Fetches the number (size) of reports stored in the requested store.

Syntax
HRESULT DdqGetDiagnosticReportStoreReportCount(
HDIAGNOSTIC_DATA_QUERY_SESSION hSession,
UINT32 reportStoreType,
UINT32 *reportCount
);

Parameters
hSession

Type: HANDLE Handle to the Diagnostic Data Query session.

reportStoreType

Type: UINT32 The type of report store to extract from. See remarks.
reportCount

Type: UINT32* Pointer to the number of error reports.

Return value
Type: HRESULT Returns S_OK on successful completion.

Requirements

Minimum suppor ted client Windows 10, version 2004 (10.0; Build 19041)

Minimum suppor ted ser ver Windows Server, version 2004 (10.0; Build 19041)

Header diagnosticdataquery.h
 DdqGetSessionAccessLevel function
(diagnosticdataquery.h)
7/2/2022 • 2 minutes to read • Edit Online

Returns the data access level of the current Diagnostic Data Query session.

Syntax
HRESULT DdqGetSessionAccessLevel(
HDIAGNOSTIC_DATA_QUERY_SESSION hSession,
DdqAccessLevel *accessLevel
);

Parameters
hSession

Type: HANDLE Handle to the Diagnostic Data Query session.

accessLevel

Type: DdqAccessLevel* This output parameter is the pointer to the access level for this session.

Return value
Type: HRESULT Returns S_OK on successful completion.

Requirements

Minimum suppor ted client Windows 10, version 2004 (10.0; Build 19041)

Minimum suppor ted ser ver Windows Server, version 2004 (10.0; Build 19041)

Header diagnosticdataquery.h
 DdqGetTranscriptConfiguration function
(diagnosticdataquery.h)
7/2/2022 • 2 minutes to read • Edit Online

Gets event transcript configuration, such as maximum storage size hours of data history to keep.

Syntax
HRESULT DdqGetTranscriptConfiguration(
HDIAGNOSTIC_DATA_QUERY_SESSION hSession,
DIAGNOSTIC_DATA_EVENT_TRANSCRIPT_CONFIGURATION *currentConfig
);

Parameters
hSession

Type: HANDLE Handle to the Diagnostic Data Query session.

currentConfig

Type: DIAGNOSTIC_DATA_EVENT_TRANSCRIPT_CONFIGURATION* This output parameter is a pointer to

the resource that contains the event transcript configuration details.

Return value
Type: HRESULT Returns S_OK on successful completion.

Requirements

Minimum suppor ted client Windows 10, version 2004 (10.0; Build 19041)

Minimum suppor ted ser ver Windows Server, version 2004 (10.0; Build 19041)

Header diagnosticdataquery.h
 DdqIsDiagnosticRecordSampledIn function
(diagnosticdataquery.h)
7/2/2022 • 2 minutes to read • Edit Online

Fetches the sampled-in state of the device for an event.

Syntax
HRESULT DdqIsDiagnosticRecordSampledIn(
HDIAGNOSTIC_DATA_QUERY_SESSION hSession,
const GUID *providerGroup,
const GUID *providerId,
PCWSTR providerName,
const UINT32 *eventId,
PCWSTR eventName,
const UINT32 *eventVersion,
const UINT64 *eventKeywords,
BOOL *isSampledIn
);

Parameters
hSession

Type: HANDLE Handle to the Diagnostic Data Query session.

providerGroup

Type: GUID* Pointer to the provider group GUID.

providerId

Type: GUID* Pointer to the provider GUID.

providerName

Type: PCWSTR The name of the provider.

eventId

Type: UNI32* Pointer to the event ID.

eventName

Type: PCWSTR The name of the event.

eventVersion

Type: UINT32* The version of the event.

eventKeywords

Type: UINT64* Pointer to the event keywords.

isSampledIn
Type: BOOL* This output parameter is a pointer to a boolean value that is TRUE if the event is sampled in and
FALSE otherwise.

Return value
Type: HRESULT Returns S_OK on successful completion.

Remarks
For more information about events and providers, see Event Tracing .

Requirements

Minimum suppor ted client Windows 10, version 2004 (10.0; Build 19041)

Minimum suppor ted ser ver Windows Server, version 2004 (10.0; Build 19041)

Header diagnosticdataquery.h
 DdqSetTranscriptConfiguration function
(diagnosticdataquery.h)
7/2/2022 • 2 minutes to read • Edit Online

Sets event transcript configuration, such as maximum storage size and hours of data history. Note that setting
the configuration will fail if the user is not elevated.

Syntax
HRESULT DdqSetTranscriptConfiguration(
HDIAGNOSTIC_DATA_QUERY_SESSION hSession,
const DIAGNOSTIC_DATA_EVENT_TRANSCRIPT_CONFIGURATION *desiredConfig
);

Parameters
hSession

Type: HANDLE Handle to the Diagnostic Data Query session.

desiredConfig

Type: DIAGNOSTIC_DATA_EVENT_TRANSCRIPT_CONFIGURATION* Pointer to the resource that contains

the desired event transcript configuration.

Return value
Type: HRESULT Returns S_OK on successful completion.

Requirements

Minimum suppor ted client Windows 10, version 2004 (10.0; Build 19041)

Minimum suppor ted ser ver Windows Server, version 2004 (10.0; Build 19041)

Header diagnosticdataquery.h
 diagnosticdataquerytypes.h header
7/2/2022 • 2 minutes to read • Edit Online

This header is used by Security and Identity. For more information, see:
Security and Identity
diagnosticdataquerytypes.h contains the following programming interfaces:

Structures

DIAGNOSTIC_DATA_EVENT_BINARY_STATS

A resource that describes this binary and the amount of diagnostic data it has sent.

DIAGNOSTIC_DATA_EVENT_CATEGORY_DESCRIPTION

A resource that represents a category, defined by an identifier and a name. A category is an organizational construct to
categorize records for a given producer. For example, "Browsing Data" could be a category for the producer "Microsoft Edge".

DIAGNOSTIC_DATA_EVENT_PRODUCER_DESCRIPTION

A resource that represents a producer. A Producer is an OS component, application or service that emits events. For example,
“Microsoft Edge” is the Producer ID for the Microsoft Edge browser.

DIAGNOSTIC_DATA_EVENT_TAG_DESCRIPTION

A resource that describes a tag, defined by the tag's name and its description.

DIAGNOSTIC_DATA_EVENT_TAG_STATS

A resource that includes a privacy tag and how many events have this privacy tag.

DIAGNOSTIC_DATA_EVENT_TRANSCRIPT_CONFIGURATION

Event transcript configuration details such as maximum storage size and hours of data history.

DIAGNOSTIC_DATA_GENERAL_STATS

This resource contains general statistics about a set of diagnostic data records.

DIAGNOSTIC_DATA_RECORD

This resource describes an individual diagnostic data record (event).

DIAGNOSTIC_DATA_SEARCH_CRITERIA

This resource contains details of the search criteria when fetching a diagnostic data record.
 DIAGNOSTIC_REPORT_DATA

This resource contains information about a diagnostic report.

DIAGNOSTIC_REPORT_PARAMETER

Resource that describes the parameters for an error report.

DIAGNOSTIC_REPORT_SIGNATURE

This resource describes the signature for a diagnostic report.

Enumerations

DdqAccessLevel

This resource represents the privilege level for a Diagnostic Data Query session
 DdqAccessLevel enumeration
(diagnosticdataquerytypes.h)
7/2/2022 • 2 minutes to read • Edit Online

This resource represents the privilege level for a Diagnostic Data Query session.

Syntax
typedef enum tagDdqAccessLevel {
NoData = 0,
CurrentUserData = 1,
AllUserData = 2
} DdqAccessLevel;

Constants

NoData
Value: 0
No data can be accessed using this session.

CurrentUserData
Value: 1
Only the current user's data can be accessed using this session.

AllUserData
Value: 2
All User data can be accessed using this session.

Requirements

Minimum suppor ted client Windows 10, version 2004 (10.0; Build 19041)

Minimum suppor ted ser ver Windows Server, version 2004 (10.0; Build 19041)

Header diagnosticdataquerytypes.h
 DIAGNOSTIC_DATA_EVENT_BINARY_STATS
structure (diagnosticdataquerytypes.h)
7/2/2022 • 2 minutes to read • Edit Online

A resource that describes this binary and the amount of diagnostic data it has sent.

Syntax
typedef struct tagDIAGNOSTIC_DATA_EVENT_BINARY_STATS {
LPWSTR moduleName;
LPWSTR friendlyModuleName;
UINT32 eventCount;
UINT64 uploadSizeBytes;
} DIAGNOSTIC_DATA_EVENT_BINARY_STATS;

Members
moduleName

Type: LPWSTR The full name of the module or binary.

friendlyModuleName

Type: LPWSTR The friendly name of the module or binary.

eventCount

Type: UINT32 The number of events sent by this module or binary.

uploadSizeBytes

Type: UINT64 The number of bytes sent by this module or binary.

Requirements

Minimum suppor ted client Windows 10, version 2004 (10.0; Build 19041)

Minimum suppor ted ser ver Windows Server, version 2004 (10.0; Build 19041)

Header diagnosticdataquerytypes.h
 DIAGNOSTIC_DATA_EVENT_CATEGORY_DESCRIPTION
structure (diagnosticdataquerytypes.h)
7/2/2022 • 2 minutes to read • Edit Online

A resource that represents a category, defined by an identifier and a name. A category is an organizational
construct to categorize records for a given producer. For example, "Browsing Data" could be a category for the
producer "Microsoft Edge".

Syntax
typedef struct tagDIAGNOSTIC_DATA_EVENT_CATEGORY_DESCRIPTION {
INT32 id;
LPWSTR name;
} DIAGNOSTIC_DATA_EVENT_CATEGORY_DESCRIPTION;

Members
id

Type: INT32 An identifier to identify this category.

name

Type: LPWSTR The name of this category.

Requirements

Minimum suppor ted client Windows 10, version 2004 (10.0; Build 19041)

Minimum suppor ted ser ver Windows Server, version 2004 (10.0; Build 19041)

Header diagnosticdataquerytypes.h
 DIAGNOSTIC_DATA_EVENT_PRODUCER_DESCRIPTION
structure (diagnosticdataquerytypes.h)
7/2/2022 • 2 minutes to read • Edit Online

A resource that represents a producer. A Producer is an OS component, application or service that emits events.
For example, “Microsoft Edge” is the Producer ID for the Microsoft Edge browser.

Syntax
typedef struct tagDIAGNOSTIC_DATA_EVENT_PRODUCER_DESCRIPTION {
LPWSTR name;
} DIAGNOSTIC_DATA_EVENT_PRODUCER_DESCRIPTION;

Members
name

Type: LPWSTR The name of this producer.

Requirements

Minimum suppor ted client Windows 10, version 2004 (10.0; Build 19041)

Minimum suppor ted ser ver Windows Server, version 2004 (10.0; Build 19041)

Header diagnosticdataquerytypes.h
 DIAGNOSTIC_DATA_EVENT_TAG_DESCRIPTION
structure (diagnosticdataquerytypes.h)
7/2/2022 • 2 minutes to read • Edit Online

A resource that describes a tag, defined by the tag's name and its description.

Syntax
typedef struct tagDIAGNOSTIC_DATA_EVENT_TAG_DESCRIPTION {
INT32 privacyTag;
LPWSTR name;
LPWSTR description;
} DIAGNOSTIC_DATA_EVENT_TAG_DESCRIPTION;

Members
privacyTag

Type: INT32 A unique identifier for this tag.

name

Type: LPWSTR The name of this tag.

description

Type: LPWSTR The official description for this tag.

Remarks
For more details, see our privacy statement .

Requirements

Minimum suppor ted client Windows 10, version 2004 (10.0; Build 19041)

Minimum suppor ted ser ver Windows Server, version 2004 (10.0; Build 19041)

Header diagnosticdataquerytypes.h
 DIAGNOSTIC_DATA_EVENT_TAG_STATS structure
(diagnosticdataquerytypes.h)
7/2/2022 • 2 minutes to read • Edit Online

A resource that includes a privacy tag and how many events have this privacy tag.

Syntax
typedef struct tagDIAGNOSTIC_DATA_EVENT_TAG_STATS {
INT32 privacyTag;
UINT32 eventCount;
} DIAGNOSTIC_DATA_EVENT_TAG_STATS;

Members
privacyTag

Type: INT32 The numeric identifier for this privacy tag.

eventCount

Type: UINT32 The number of events that have this privacy tag.

Remarks
See our privacy statement for information about diagnostic data privacy tags.

Requirements

Minimum suppor ted client Windows 10, version 2004 (10.0; Build 19041)

Minimum suppor ted ser ver Windows Server, version 2004 (10.0; Build 19041)

Header diagnosticdataquerytypes.h
 DIAGNOSTIC_DATA_EVENT_TRANSCRIPT_CONFIGURATION
structure (diagnosticdataquerytypes.h)
7/2/2022 • 2 minutes to read • Edit Online

Event transcript configuration details such as maximum storage size and hours of data history.

Syntax
typedef struct tagDIAGNOSTIC_DATA_EVENT_TRANSCRIPT_CONFIGURATION {
UINT32 hoursOfHistoryToKeep;
UINT32 maxStoreMegabytes;
UINT32 requestedMaxStoreMegabytes;
} DIAGNOSTIC_DATA_EVENT_TRANSCRIPT_CONFIGURATION;

Members
hoursOfHistoryToKeep

Type: UINT32 Number of hours of event history to keep. When an event has been stored for longer than this
amount of time, it will be dropped.
maxStoreMegabytes

Type: UINT32 Maximum storage size (in megabytes) of event history to keep. When event store exceeds this
size, events will be removed from the store starting with the oldest event.
requestedMaxStoreMegabytes

Type: UINT32 The requested storage size (in megabytes) of event history to keep.

Remarks
For more details on how configurations work, see Diagnostic Data Viewer over view

Requirements

Minimum suppor ted client Windows 10, version 2004 (10.0; Build 19041)

Minimum suppor ted ser ver Windows Server, version 2004 (10.0; Build 19041)

Header diagnosticdataquerytypes.h
 DIAGNOSTIC_DATA_GENERAL_STATS structure
(diagnosticdataquerytypes.h)
7/2/2022 • 2 minutes to read • Edit Online

This resource contains general statistics about a set of diagnostic data records.

Syntax
typedef struct tagDIAGNOSTIC_DATA_GENERAL_STATS {
UINT32 optInLevel;
UINT64 transcriptSizeBytes;
UINT64 oldestEventTimestamp;
UINT32 totalEventCountLast24Hours;
FLOAT averageDailyEvents;
} DIAGNOSTIC_DATA_GENERAL_STATS;

Members
optInLevel

Type: UINT32 This identifies the device's current diagnostic data opt-in level (Security = 0, Basic = 1, Enhanced
= 2, and Full = 3). See remarks for more details.
transcriptSizeBytes

Type: UINT64 The collective size in bytes for the diagnostic data records.
oldestEventTimestamp

Type: UINT64 The timestamp of the oldest event among the diagnostic data records.
totalEventCountLast24Hours

Type: UINT32 Total number of events among the diagnostic data records within the last 24 hours.
averageDailyEvents

Type: FLOAT The average number of events sent per day in this set of diagnostic data records.

Remarks
See our privacy statement for information about diagnostic data opt-in levels.

Requirements

Minimum suppor ted client Windows 10, version 2004 (10.0; Build 19041)

Minimum suppor ted ser ver Windows Server, version 2004 (10.0; Build 19041)

Header diagnosticdataquerytypes.h
 DIAGNOSTIC_DATA_RECORD structure
(diagnosticdataquerytypes.h)
7/2/2022 • 2 minutes to read • Edit Online

This resource describes an individual diagnostic data record (event).

Syntax
typedef struct tagDIAGNOSTIC_DATA_RECORD {
INT64 rowId;
UINT64 timestamp;
UINT64 eventKeywords;
LPWSTR fullEventName;
LPWSTR providerGroupGuid;
LPWSTR producerName;
INT32 *privacyTags;
UINT32 privacyTagCount;
INT32 *categoryIds;
UINT32 categoryIdCount;
BOOL isCoreData;
LPWSTR extra1;
LPWSTR extra2;
LPWSTR extra3;
} DIAGNOSTIC_DATA_RECORD;

Members
rowId

Type: INT64 The row ID of the record.

timestamp

Type: UINT64 The timestamp for when the record was processed.
eventKeywords

Type: UINT64 The keywords associated with this event.

fullEventName

Type: LPWSTR The full event name.

providerGroupGuid

Type: LPWSTR The provider group GUID for this event.

producerName

Type: LPWSTR The name of the producer associated with this event.
privacyTags

Type: INT32* A list of privacy tag IDs for this event.

privacyTagCount
Type: UINT32 The number of privacy tags associated with this event.
categoryIds

Type: INT32* A list of the categories associated with this event.

categoryIdCount

Type: UINT32 The number of categories associated with this event.

isCoreData

Type: BOOL TRUE if this record is core data. FALSE otherwise.

extra1

extra2

extra3

Remarks
For more information about events and providers, see Event Tracing .
For information about how a producer is defined, see
DIAGNOSTIC_DATA_EVENT_PRODUCER_DESCRIPTION .
For information about how a tag is defined, see DIAGNOSTIC_DATA_EVENT_TAG_DESCRIPTION .
For information about how a category is defined, see
DIAGNOSTIC_DATA_EVENT_CATEGORY_DESCRIPTION .
For more details on what is core data, see our privacy statement .

Requirements

Minimum suppor ted client Windows 10, version 2004 (10.0; Build 19041)

Minimum suppor ted ser ver Windows Server, version 2004 (10.0; Build 19041)

Header diagnosticdataquerytypes.h
 DIAGNOSTIC_DATA_SEARCH_CRITERIA structure
(diagnosticdataquerytypes.h)
7/2/2022 • 2 minutes to read • Edit Online

This resource contains details of the search criteria when fetching a diagnostic data record.

Syntax
typedef struct tagDIAGNOSTIC_DATA_SEARCH_CRITERIA {
LPCWSTR *producerNames;
UINT32 producerNameCount;
LPCWSTR textToMatch;
const INT32 *categoryIds;
UINT32 categoryIdCount;
const INT32 *privacyTags;
UINT32 privacyTagCount;
BOOL coreDataOnly;
} DIAGNOSTIC_DATA_SEARCH_CRITERIA;

Members
producerNames

Type: LPCWSTR* List of producer names to search for. A diagnostic data record that matches at least one of the
producer names is included as a result in this search criteria. Use nullptr for this value to indicate no filter by
producers.
producerNameCount

Type: UINT32 The number of producer names in the list of producer names to search for. Use 0 for this value
to indicate no filter by producers.
textToMatch

Type: LPCWSTR The sub-string to search for within diagnostic data records. This text is case insensitive.
categoryIds

Type: INT32* List of category identifiers to search for. A diagnostic data record that matches at least one of the
category names is included as a result in this search criteria. Use nullptr for this value to indicate no filter by
categories.
categoryIdCount

Type: UINT32 The number of categories in the list of category identifiers. Use 0 for this value to indicate no
filter by categories.
privacyTags

Type: INT32* List of privacy tag identifiers to search for. A diagnostic data record that matches at least one of
the tags is included as a result in this search criteria. Use nullptr for this value to indicate no filter by privacy
tags.
privacyTagCount
Type: UINT32 The number of privacy tags in the list of privacy tag identifiers. Use 0 for this value to indicate
no filter by tags.
coreDataOnly

Type: BOOL TRUE to filter search results to only core data. FALSE to return both core and non-core data.

Remarks
For more details on how core data is defined, see our privacy statement .

Requirements

Minimum suppor ted client Windows 10, version 2004 (10.0; Build 19041)

Minimum suppor ted ser ver Windows Server, version 2004 (10.0; Build 19041)

Header diagnosticdataquerytypes.h
 DIAGNOSTIC_REPORT_DATA structure
(diagnosticdataquerytypes.h)
7/2/2022 • 2 minutes to read • Edit Online

This resource contains information about a diagnostic report.

Syntax
typedef struct tagDIAGNOSTIC_REPORT_DATA {
DIAGNOSTIC_REPORT_SIGNATURE signature;
GUID bucketId;
GUID reportId;
FILETIME creationTime;
ULONGLONG sizeInBytes;
LPWSTR cabId;
DWORD reportStatus;
GUID reportIntegratorId;
LPWSTR *fileNames;
DWORD fileCount;
LPWSTR friendlyEventName;
LPWSTR applicationName;
LPWSTR applicationPath;
LPWSTR description;
LPWSTR bucketIdString;
UINT64 legacyBucketId;
LPWSTR reportKey;
} DIAGNOSTIC_REPORT_DATA;

Members
signature

Type: DIAGNOSTIC_DATA_REPORT_SIGNATURE The signature for this report.

bucketId

Type: GUID A hash of the signature. Can be used to cross reference with other crash reports with the same
signature (currently not implemented).
reportId

Type: GUID A locally unique identifier for the report.

creationTime

Type: FILETIME A UTC time stamp of when the report was created.
sizeInBytes

Type: ULONGLONG The size (on disk) of the individual report and its constituent files. This value only counts
files directly contained in a report.
cabId

Type: LPWSTR The ID for the cab.

reportStatus

Type: DWORD The detailed status of the report. Use the ReportStatus decoder to track this bit-field.
reportIntegratorId

Type: GUID The integrator ID of the report.

fileNames

Type: LPWSTR* A pointer to hold the names of the files included in the report.
fileCount

Type: DWORD The number of data files included in the report.

friendlyEventName

Type: LPWSTR The display name of the application event.

applicationName

Type: LPWSTR The name of the application.

applicationPath

Type: LPWSTR The file path of the application.

description

Type: LPWSTR The description of the problem.

bucketIdString

Type: LPWSTR The bucket ID as a string (possibly truncated).

legacyBucketId

Type: UINT64 The legacy bucket ID.

reportKey

Type: LPWSTR The report key.

Remarks
For general questions about Windows Error Reporting, see the WER APIS . For report keys, see the WER APIs .

Requirements

Minimum suppor ted client Windows 10, version 2004 (10.0; Build 19041)

Minimum suppor ted ser ver Windows Server, version 2004 (10.0; Build 19041)

Header diagnosticdataquerytypes.h
 DIAGNOSTIC_REPORT_PARAMETER structure
(diagnosticdataquerytypes.h)
7/2/2022 • 2 minutes to read • Edit Online

Resource that describes the parameters for an error report.

Syntax
typedef struct tagDIAGNOSTIC_REPORT_PARAMETER {
WCHAR name[129];
WCHAR value[260];
} DIAGNOSTIC_REPORT_PARAMETER;

Members
name

Type: WCHAR[] The name of this parameter.

value

Type: WCHAR[] The value of this parameter.

Remarks
For more information about parameters, see the WER APIs .

Requirements

Minimum suppor ted client Windows 10, version 2004 (10.0; Build 19041)

Minimum suppor ted ser ver Windows Server, version 2004 (10.0; Build 19041)

Header diagnosticdataquerytypes.h
 DIAGNOSTIC_REPORT_SIGNATURE structure
(diagnosticdataquerytypes.h)
7/2/2022 • 2 minutes to read • Edit Online

This resource describes the signature for a diagnostic report.

Syntax
typedef struct tagDIAGNOSTIC_REPORT_SIGNATURE {
WCHAR eventName[65];
DIAGNOSTIC_REPORT_PARAMETER parameters[10];
} DIAGNOSTIC_REPORT_SIGNATURE;

Members
eventName

Type: WCHAR[] A string that specifies the name of this application event.
parameters

Type: DIAGNOSTIC_DATA_REPORT_PARAMETER[] A list of parameters for this report.

Requirements

Minimum suppor ted client Windows 10, version 2004 (10.0; Build 19041)

Minimum suppor ted ser ver Windows Server, version 2004 (10.0; Build 19041)

Header diagnosticdataquerytypes.h
 dpapi.h header
7/2/2022 • 2 minutes to read • Edit Online

This header is used by Security and Identity. For more information, see:
Security and Identity
dpapi.h contains the following programming interfaces:

Functions

CryptProtectData

Performs encryption on the data in a DATA_BLOB structure.

CryptProtectMemory

encrypts memory to prevent others from viewing sensitive information in your process.

CryptUnprotectData

Decrypts and does an integrity check of the data in a DATA_BLOB structure.

CryptUnprotectMemory

Decrypts memory that was encrypted using the CryptProtectMemory function.

CryptUpdateProtectedState

Migrates the current user's master keys after the user's security identifier (SID) has changed.

Structures

CRYPT_INTEGER_BLOB

The CryptoAPI CRYPT_INTEGER_BLOB structure is used for an arbitrary array of bytes. It is declared in Wincrypt.h and
provides flexibility for objects that can contain various data types.

CRYPTPROTECT_PROMPTSTRUCT

Provides the text of a prompt and information about when and where that prompt is to be displayed when using the
CryptProtectData and CryptUnprotectData functions.
 CRYPT_INTEGER_BLOB structure (dpapi.h)
7/2/2022 • 2 minutes to read • Edit Online

The CryptoAPI CRYPT_INTEGER_BLOB structure is used for an arbitrary array of bytes. It is declared in
Wincrypt.h and provides flexibility for objects that can contain various data types.

Syntax
typedef struct _CRYPTOAPI_BLOB {
DWORD cbData;
BYTE *pbData;
} CRYPT_INTEGER_BLOB, *PCRYPT_INTEGER_BLOB, CRYPT_UINT_BLOB, *PCRYPT_UINT_BLOB, CRYPT_OBJID_BLOB,
*PCRYPT_OBJID_BLOB, CERT_NAME_BLOB, *PCERT_NAME_BLOB, CERT_RDN_VALUE_BLOB, *PCERT_RDN_VALUE_BLOB, CERT_BLOB,
*PCERT_BLOB, CRL_BLOB, *PCRL_BLOB, DATA_BLOB, *PDATA_BLOB, CRYPT_DATA_BLOB, *PCRYPT_DATA_BLOB,
CRYPT_HASH_BLOB, *PCRYPT_HASH_BLOB, CRYPT_DIGEST_BLOB, *PCRYPT_DIGEST_BLOB, CRYPT_DER_BLOB,
*PCRYPT_DER_BLOB, CRYPT_ATTR_BLOB, *PCRYPT_ATTR_BLOB;

Members
cbData

The count of bytes in the buffer pointed to by pbData.

pbData

A pointer to a block of data bytes.

Requirements

Minimum suppor ted client Windows XP [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Header dpapi.h (include Wincrypt.h)

See also
CERT_EXTENSION
CERT_POLICY_QUALIFIER_INFO
CERT_REQUEST_INFO
CMSG_CTRL_ADD_SIGNER_UNAUTH_ATTR_PARA
CMSG_SIGNER_INFO
CRYPT_ATTRIBUTE_TYPE_VALUE
CRYPT_TIME_STAMP_REQUEST_INFO
CertCompareIntegerBlob
CertNameToStr
 CRYPTPROTECT_PROMPTSTRUCT structure
(dpapi.h)
7/2/2022 • 2 minutes to read • Edit Online

The CRYPTPROTECT_PROMPTSTRUCT structure provides the text of a prompt and information about when
and where that prompt is to be displayed when using the CryptProtectData and CryptUnprotectData functions.

Syntax
typedef struct _CRYPTPROTECT_PROMPTSTRUCT {
DWORD cbSize;
DWORD dwPromptFlags;
HWND hwndApp;
LPCWSTR szPrompt;
} CRYPTPROTECT_PROMPTSTRUCT, *PCRYPTPROTECT_PROMPTSTRUCT;

Members
cbSize

The size, in bytes, of this structure.

dwPromptFlags

DWORD flags that indicate when prompts to the user are to be displayed. Current dwPromptFlags values are
as follows.

VA L UE M EA N IN G

This flag is used to provide the prompt for the protect

CRYPTPROTECT_PROMPT_ON_PROTECT phase.

This flag can be combined with

CRYPTPROTECT_PROMPT_ON_UNPROTECT CRYPTPROTECT_PROMPT_ON_PROTECT to enforce the UI
(user interface) policy of the caller. When
CryptUnprotectData is called, the dwPromptFlags specified
in the CryptProtectData call are enforced.

hwndApp

Window handle to the parent window.

szPrompt

A string containing the text of a prompt to be displayed.

Requirements

Minimum suppor ted client Windows XP [desktop apps only]

 Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Header dpapi.h

See also
CryptProtectData
CryptUnprotectData
 CryptProtectData function (dpapi.h)
7/2/2022 • 3 minutes to read • Edit Online

The Cr yptProtectData function performs encryption on the data in a DATA_BLOB structure. Typically, only a
user with the same logon credential as the user who encrypted the data can decrypt the data. In addition, the
encryption and decryption usually must be done on the same computer. For information about exceptions, see
Remarks.

Syntax
DPAPI_IMP BOOL CryptProtectData(
[in] DATA_BLOB *pDataIn,
[in, optional] LPCWSTR szDataDescr,
[in, optional] DATA_BLOB *pOptionalEntropy,
[in] PVOID pvReserved,
[in, optional] CRYPTPROTECT_PROMPTSTRUCT *pPromptStruct,
[in] DWORD dwFlags,
[out] DATA_BLOB *pDataOut
);

Parameters
[in] pDataIn

A pointer to a DATA_BLOB structure that contains the plaintext to be encrypted.

[in, optional] szDataDescr

A string with a readable description of the data to be encrypted. This description string is included with the
encrypted data. This parameter is optional and can be set to NULL .
[in, optional] pOptionalEntropy

A pointer to a DATA_BLOB structure that contains a password or other additional entropy used to encrypt the
data. The DATA_BLOB structure used in the encryption phase must also be used in the decryption phase. This
parameter can be set to NULL for no additional entropy. For information about protecting passwords, see
Handling Passwords.
[in] pvReserved

Reserved for future use and must be set to NULL .

[in, optional] pPromptStruct

A pointer to a CRYPTPROTECT_PROMPTSTRUCT structure that provides information about where and when
prompts are to be displayed and what the content of those prompts should be. This parameter can be set to
NULL in both the encryption and decryption phases.
[in] dwFlags

This parameter can be one of the following flags.

VA L UE M EA N IN G
 When this flag is set, it associates the data encrypted with
CRYPTPROTECT_LOCAL_MACHINE the current computer instead of with an individual user. Any
user on the computer on which Cr yptProtectData is called
can use CryptUnprotectData to decrypt the data.

This flag is used for remote situations where presenting a

CRYPTPROTECT_UI_FORBIDDEN user interface (UI) is not an option. When this flag is set and
a UI is specified for either the protect or unprotect
operation, the operation fails and GetLastError returns the
ERROR_PASSWORD_RESTRICTION code.

This flag generates an audit on protect and unprotect

CRYPTPROTECT_AUDIT operations. Audit log entries are recorded only if
szDataDescr is not NULL and not empty.

[out] pDataOut

A pointer to a DATA_BLOB structure that receives the encrypted data. When you have finished using the
DATA_BLOB structure, free its pbData member by calling the LocalFree function.

Return value
If the function succeeds, the function returns TRUE .
If the function fails, it returns FALSE . For extended error information, call GetLastError.

Remarks
Typically, only a user with logon credentials that match those of the user who encrypted the data can decrypt the
data. In addition, decryption usually can only be done on the computer where the data was encrypted. However,
a user with a roaming profile can decrypt the data from another computer on the network.
If the CRYPTPROTECT_LOCAL_MACHINE flag is set when the data is encrypted, any user on the computer where
the encryption was done can decrypt the data.
The function creates a session key to perform the encryption. The session key is derived again when the data is
to be decrypted.
The function also adds a Message Authentication Code (MAC) (keyed integrity check) to the encrypted data to
guard against data tampering.
To encrypt memory for temporary use in the same process or across processes, call the CryptProtectMemory
function.
Examples
The following example shows encryption of the data in a DATA_BLOB structure. The Cr yptProtectData function
does the encryption by using a session key that the function creates by using the user's logon credentials. For
another example that uses this function, see Example C Program: Using CryptProtectData.
 // Encrypt data from DATA_BLOB DataIn to DATA_BLOB DataOut.

//--------------------------------------------------------------------
// Declare and initialize variables.

DATA_BLOB DataIn;
DATA_BLOB DataOut;
BYTE *pbDataInput =(BYTE *)"Hello world of data protection.";
DWORD cbDataInput = strlen((char *)pbDataInput)+1;

//--------------------------------------------------------------------
// Initialize the DataIn structure.

DataIn.pbData = pbDataInput;
DataIn.cbData = cbDataInput;

//--------------------------------------------------------------------
// Begin protect phase. Note that the encryption key is created
// by the function and is not passed.

if(CryptProtectData(
&DataIn,
L"This is the description string.", // A description string
// to be included with the
// encrypted data.
NULL, // Optional entropy not used.
NULL, // Reserved.
NULL, // Pass NULL for the
// prompt structure.
0,
&DataOut))
{
printf("The encryption phase worked.\n");
LocalFree(DataOut.pbData);
}
else
{
printf("Encryption error using CryptProtectData.\n");
exit(1);
}

Requirements

Minimum suppor ted client Windows XP [desktop apps | UWP apps]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps | UWP apps]

Target Platform Windows

Header dpapi.h

Librar y Crypt32.lib

DLL Crypt32.dll

See also
CryptProtectMemory
CryptUnprotectData
Data Encryption and Decryption Functions
LocalFree
 CryptProtectMemory function (dpapi.h)
7/2/2022 • 3 minutes to read • Edit Online

The Cr yptProtectMemor y function encrypts memory to prevent others from viewing sensitive information in
your process. For example, use the Cr yptProtectMemor y function to encrypt memory that contains a
password. Encrypting the password prevents others from viewing it when the process is paged out to the swap
file. Otherwise, the password is in plaintext and viewable by others.

Syntax
DPAPI_IMP BOOL CryptProtectMemory(
[in, out] LPVOID pDataIn,
[in] DWORD cbDataIn,
[in] DWORD dwFlags
);

Parameters
[in, out] pDataIn

A pointer to the block of memory to encrypt. The cbDataIn parameter specifies the number of bytes that will be
encrypted. If the data contained in the memory space is smaller than the number of bytes specified, data outside
of the intended block will be encrypted. If it is larger than cbDataIn bytes, then only the first cbDataIn bytes will
be encrypted.
[in] cbDataIn

Number of bytes of memory pointed to by the pData parameter to encrypt. The number of bytes must be a
multiple of the CRYPTPROTECTMEMORY_BLOCK_SIZE constant defined in Wincrypt.h.
[in] dwFlags

This parameter can be one of the following flags. You must specify the same flag when encrypting and
decrypting the memory.

VA L UE M EA N IN G

Encrypt and decrypt memory in the same process. An

CRYPTPROTECTMEMORY_SAME_PROCESS application running in a different process will not be able to
decrypt the data.

Encrypt and decrypt memory in different processes. An

CRYPTPROTECTMEMORY_CROSS_PROCESS application running in a different process will be able to
decrypt the data.

Use the same logon credentials to encrypt and decrypt

CRYPTPROTECTMEMORY_SAME_LOGON memory in different processes. An application running in a
different process will be able to decrypt the data. However,
the process must run as the same user that encrypted the
data and in the same logon session.

Return value
If the function succeeds, the function returns TRUE .
If the function fails, it returns FALSE . For extended error information, call GetLastError.

Remarks
Using CryptProtectMemory and CryptUnprotectMemory for password encryption is not secure because the
data exists as plaintext in memory before it is encrypted and at any time the caller decrypts it for use.
Typically, you use the Cr yptProtectMemor y function to encrypt sensitive information that you are going to
decrypt while your process is running. Do not use this function to save data that you want to decrypt later; you
will not be able to decrypt the data if the computer is restarted. To save encrypted data to a file to decrypt later,
use the CryptProtectData function.
Call the CryptUnprotectMemory function to decrypt memory encrypted with the Cr yptProtectMemor y
function. When you have finished using the sensitive information, clear it from memory by calling the
SecureZeroMemory function.
Use the CRYPTPROTECTMEMORY_CROSS_PROCESS or CRYPTPROTECTMEMORY_SAME_LOGON flag if you use
RPC or LRPC to pass encrypted data to another process. The receiving process must specify the same flag to
decrypt the data. Also, use these flags if you use shared memory.
If the client uses the CRYPTPROTECTMEMORY_SAME_LOGON flag, the server must impersonate the client
(RpcImpersonateClient) before decrypting the memory.
Examples
The following example calls the Cr yptProtectMemor y function to encrypt data that is in memory.
 #include <windows.h>
#include <stdio.h>
#include <Wincrypt.h>

#define SSN_STR_LEN 12 // includes null

void main()
{
HRESULT hr = S_OK;
LPWSTR pSensitiveText = NULL;
DWORD cbSensitiveText = 0;
DWORD cbPlainText = SSN_STR_LEN*sizeof(WCHAR);
DWORD dwMod = 0;

// Memory to encrypt must be a multiple of CRYPTPROTECTMEMORY_BLOCK_SIZE.

if (dwMod = cbPlainText % CRYPTPROTECTMEMORY_BLOCK_SIZE)
cbSensitiveText = cbPlainText +
(CRYPTPROTECTMEMORY_BLOCK_SIZE - dwMod);
else
cbSensitiveText = cbPlainText;

pSensitiveText = (LPWSTR)LocalAlloc(LPTR, cbSensitiveText);

if (NULL == pSensitiveText)
{
wprintf(L"Memory allocation failed.\n");
return E_OUTOFMEMORY;
}

// Place sensitive string to encrypt in pSensitiveText.

if (!CryptProtectMemory(pSensitiveText, cbSensitiveText,
CRYPTPROTECTMEMORY_SAME_PROCESS))
{
wprintf(L"CryptProtectMemory failed: %d\n", GetLastError());
SecureZeroMemory(pSensitiveText, cbSensitiveText);
LocalFree(pSensitiveText);
pSensitiveText = NULL;
return E_FAIL;
}

// Call CryptUnprotectMemory to decrypt and use the memory.

SecureZeroMemory(pSensitiveText, cbSensitiveText);
LocalFree(pSensitiveText);
pSensitiveText = NULL;

return hr;
}

Requirements

Minimum suppor ted client Windows Vista [desktop apps | UWP apps]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps | UWP apps]

Target Platform Windows

Header dpapi.h
 Librar y Crypt32.lib

DLL Crypt32.dll

See also
CryptProtectData
CryptUnprotectMemory
RtlDecryptMemory
RtlEncryptMemory
 CryptUnprotectData function (dpapi.h)
7/2/2022 • 3 minutes to read • Edit Online

The Cr yptUnprotectData function decrypts and does an integrity check of the data in a DATA_BLOB structure.
Usually, the only user who can decrypt the data is a user with the same logon credentials as the user who
encrypted the data. In addition, the encryption and decryption must be done on the same computer. For
information about exceptions, see the Remarks section of CryptProtectData.

Syntax
DPAPI_IMP BOOL CryptUnprotectData(
[in] DATA_BLOB *pDataIn,
[out, optional] LPWSTR *ppszDataDescr,
[in, optional] DATA_BLOB *pOptionalEntropy,
PVOID pvReserved,
[in, optional] CRYPTPROTECT_PROMPTSTRUCT *pPromptStruct,
[in] DWORD dwFlags,
[out] DATA_BLOB *pDataOut
);

Parameters
[in] pDataIn

A pointer to a DATA_BLOB structure that holds the encrypted data. The DATA_BLOB structure's cbData member
holds the length of the pbData member's byte string that contains the text to be encrypted.
[out, optional] ppszDataDescr

A pointer to a string-readable description of the encrypted data included with the encrypted data. This
parameter can be set to NULL . When you have finished using ppszDataDescr, free it by calling the LocalFree
function.
[in, optional] pOptionalEntropy

A pointer to a DATA_BLOB structure that contains a password or other additional entropy used when the data
was encrypted. This parameter can be set to NULL ; however, if an optional entropy DATA_BLOB structure was
used in the encryption phase, that same DATA_BLOB structure must be used for the decryption phase. For
information about protecting passwords, see Handling Passwords.
pvReserved

This parameter is reserved for future use and must be set to NULL .
[in, optional] pPromptStruct

A pointer to a CRYPTPROTECT_PROMPTSTRUCT structure that provides information about where and when
prompts are to be displayed and what the content of those prompts should be. This parameter can be set to
NULL .
[in] dwFlags

A DWORD value that specifies options for this function. This parameter can be zero, in which case no option is
set, or the following flag.
 VA L UE M EA N IN G

This flag is used for remote situations where the user

CRYPTPROTECT_UI_FORBIDDEN interface (UI) is not an option. When this flag is set and UI is
specified for either the protect or unprotect operation, the
operation fails and GetLastError returns the
ERROR_PASSWORD_RESTRICTION code.

This flag verifies the protection of a protected BLOB. If the

CRYPTPROTECT_VERIFY_PROTECTION
default protection level configured of the host is higher than
the current protection level for the BLOB, the function
returns CRYPT_I_NEW_PROTECTION_REQUIRED to
advise the caller to again protect the plaintext contained in
the BLOB.

[out] pDataOut

A pointer to a DATA_BLOB structure where the function stores the decrypted data. When you have finished using
the DATA_BLOB structure, free its pbData member by calling the LocalFree function.

Return value
If the function succeeds, the function returns TRUE .
If the function fails, it returns FALSE .

Remarks
The CryptProtectData function creates a session key when the data is encrypted. That key is derived again and
used to decrypt the data BLOB.
The Message Authentication Code (MAC) hash added to the encrypted data can be used to determine whether
the encrypted data was altered in any way. Any tampering results in the return of the ERROR_INVALID_DATA
code.
When you have finished using the DATA_BLOB structure, free its pbData member by calling the LocalFree
function. Any ppszDataDescr that is not NULL must also be freed by using LocalFree .
When you have finished using sensitive information, clear it from memory by calling the SecureZeroMemory
function.
Examples
The following example shows decrypting encrypted data in a DATA_BLOB structure. This function does the
decryption by using a session key that the function creates by using the user's logon credentials. For another
example that uses this function, see Example C Program: Using CryptProtectData.
 // Decrypt data from DATA_BLOB DataOut to DATA_BLOB DataVerify.

//--------------------------------------------------------------------
// Declare and initialize variables.

DATA_BLOB DataOut;
DATA_BLOB DataVerify;
LPWSTR pDescrOut = NULL;
//--------------------------------------------------------------------
// The buffer DataOut would be created using the CryptProtectData
// function. If may have been read in from a file.

//--------------------------------------------------------------------
// Begin unprotect phase.

if (CryptUnprotectData(
&DataOut,
&pDescrOut,
NULL, // Optional entropy
NULL, // Reserved
NULL, // Here, the optional
// prompt structure is not
// used.
0,
&DataVerify))
{
printf("The decrypted data is: %s\n", DataVerify.pbData);
printf("The description of the data was: %s\n",pDescrOut);
LocalFree(DataVerify.pbData);
LocalFree(pDescrOut);
}
else
{
printf("Decryption error!");
}

Requirements

Minimum suppor ted client Windows XP [desktop apps | UWP apps]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps | UWP apps]

Target Platform Windows

Header dpapi.h

Librar y Crypt32.lib

DLL Crypt32.dll

See also
CryptProtectData
CryptUnprotectMemory
Data Encryption and Decryption Functions
LocalFree
Microsoft Base Cryptographic Provider
 CryptUnprotectMemory function (dpapi.h)
7/2/2022 • 2 minutes to read • Edit Online

The Cr yptUnprotectMemor y function decrypts memory that was encrypted using the CryptProtectMemory
function.

Syntax
DPAPI_IMP BOOL CryptUnprotectMemory(
[in, out] LPVOID pDataIn,
[in] DWORD cbDataIn,
[in] DWORD dwFlags
);

Parameters
[in, out] pDataIn

A pointer to the block of memory to decrypt. The cbData parameter specifies the number of bytes that the
function will attempt to decrypt. If the data contained in the memory space is smaller than the number of bytes
specified, the function will attempt to decrypt data outside of the intended block. If it is larger than cbData bytes,
then only the first cbData bytes will be decrypted.
[in] cbDataIn

Number of bytes of memory pointed to by the pData parameter to decrypt. The number of bytes must be a
multiple of the CRYPTPROTECTMEMORY_BLOCK_SIZE constant defined in Wincrypt.h.
[in] dwFlags

This parameter can be one of the following flags. You must specify the same flag when encrypting and
decrypting the memory.

VA L UE M EA N IN G

Encrypt and decrypt memory in the same process. An

CRYPTPROTECTMEMORY_SAME_PROCESS application running in a different process will not be able to
decrypt the data.

Encrypt and decrypt memory in different processes. An

CRYPTPROTECTMEMORY_CROSS_PROCESS application running in a different process will be able to
decrypt the data.

Use the same logon credentials to encrypt and decrypt

CRYPTPROTECTMEMORY_SAME_LOGON memory in different processes. An application running in a
different process will be able to decrypt the data. However,
the process must run as the same user that encrypted the
data and in the same logon session.

Return value
If the function succeeds, the function returns TRUE .
If the function fails, it returns FALSE . For extended error information, call GetLastError.

Remarks
Using CryptProtectMemory and CryptUnprotectMemory for password encryption is not secure because the
data exists as plaintext in memory before it is encrypted and at any time the caller decrypts it for use.
You must encrypt and decrypt the memory during the same boot session. If the computer is restarted before
you call the Cr yptUnprotectMemor y function, you will not be able to decrypt the data.
You must pass the same flag to Cr yptUnprotectMemor y and CryptProtectMemory. If you pass different flags,
the Cr yptUnprotectMemor y function succeeds; however, the result is unpredictable.
When you have finished using the sensitive information, clear it from memory by calling the
SecureZeroMemory function.
Examples
The following example calls the Cr yptUnprotectMemor y function to decrypt data that is in memory. The
example assumes the variable pEncryptedText points to a string that has been encrypted using the
CryptProtectMemory function.

#include <windows.h>
#include <stdio.h>
#include <Wincrypt.h>
#include <strsafe.h>
#pragma comment(lib, "crypt32.lib")

void main()
{
LPWSTR pEncryptedText; // contains the encrypted text
DWORD cbEncryptedText; // number of bytes to which
// pEncryptedText points

if (CryptUnprotectMemory(pEncryptedText, cbEncryptedText,
CRYPTPROTECTMEMORY_SAME_PROCESS))
{
// Use the decrypted string.
}
else
{
wprintf(L"CryptUnprotectMemory failed: %d\n",
GetLastError());
}

// Clear and free memory after using

// the decrypted string or if an error occurs.
SecureZeroMemory(pEncryptedText, cbEncryptedText);
LocalFree(pEncryptedText);
pEncryptedText = NULL;
}

Requirements

Minimum suppor ted client Windows Vista [desktop apps | UWP apps]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps | UWP apps]
 Target Platform Windows

Header dpapi.h

Librar y Crypt32.lib

DLL Crypt32.dll

See also
CryptProtectMemory
CryptUnprotectData
RtlDecryptMemory
RtlEncryptMemory
 CryptUpdateProtectedState function (dpapi.h)
7/2/2022 • 2 minutes to read • Edit Online

The Cr yptUpdateProtectedState function migrates the current user's master keys after the user's security
identifier (SID) has changed. This function can be used to preserve encrypted data after a user has been moved
from one domain to another.

Syntax
DPAPI_IMP BOOL CryptUpdateProtectedState(
[in] PSID pOldSid,
[in] LPCWSTR pwszOldPassword,
[in] DWORD dwFlags,
[out] DWORD *pdwSuccessCount,
[out] DWORD *pdwFailureCount
);

Parameters
[in] pOldSid

The address of a SID structure that contains the user's previous SID. This SID is used to locate the old master
keys. If this parameter is NULL , the master keys for the current user SID are migrated.
Either this parameter or the pwszOldPassword parameter may be NULL , but not both.
[in] pwszOldPassword

A pointer to a null-terminated Unicode string that contains the user's password before the SID was changed.
This password is used to decrypt the old master keys. If this parameter is NULL , the password of the current
user will be used.
Either this parameter or the pOldSid parameter may be NULL , but not both.
[in] dwFlags

Not used. Must be zero.

[out] pdwSuccessCount

The address of a DWORD variable that receives the number of master keys that were successfully migrated.
[out] pdwFailureCount

The address of a DWORD variable that receives the number of master keys that could not be decrypted.
It is not necessarily an error if one or more master keys cannot be decrypted. Some users may possess master
keys that are stagnant and could not have been decrypted for a long time. One way that this can happen is when
the password of a local user has been administratively reset.

Return value
If the function succeeds, the return value is TRUE .
If the function fails, the return value is FALSE . For extended error information, call GetLastError. Some possible
error codes include the following.

RET URN C O DE DESC RIP T IO N

One of the parameters contains a value that is not valid.

ERROR_INVALID_PARAMETER

A memory allocation failure occurred.

ERROR_OUTOFMEMORY

The old password could not be encrypted.

ERROR_ENCRYPTION_FAILED

Remarks
This function decrypts all of the user's master keys in the old master key directory, using the previous password,
and stores them in the user's current master key directory, encrypted with the user's current password.
This function must be called from the user account that the keys are being migrated to.
If this function is able to successfully migrate an old master key, it will automatically delete the old master key.
Master keys that cannot be decrypted are not deleted.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header dpapi.h

Librar y Crypt32.lib

DLL Crypt32.dll
 dssec.h header
7/2/2022 • 2 minutes to read • Edit Online

This header is used by Security and Identity. For more information, see:
Security and Identity
dssec.h contains the following programming interfaces:

Functions

DSCreateISecurityInfoObject

Creates an instance of the ISecurityInformation interface associated with the specified directory service (DS) object.

DSCreateISecurityInfoObjectEx

Creates an instance of the ISecurityInformation interface associated with the specified directory service (DS) object on the
specified server.

DSCreateSecurityPage

Creates a security property page for an Active Directory object.

DSEditSecurity

Displays a modal dialog box for editing security on a Directory Services (DS) object.
 DSCreateISecurityInfoObject function (dssec.h)
7/2/2022 • 2 minutes to read • Edit Online

The DSCreateISecurityInfoObject function creates an instance of the ISecurityInformation interface

associated with the specified directory service (DS) object.

Syntax
HRESULT DSCreateISecurityInfoObject(
[in] LPCWSTR pwszObjectPath,
[in] LPCWSTR pwszObjectClass,
[in] DWORD dwFlags,
[out] LPSECURITYINFO *ppSI,
[in, optional] PFNREADOBJECTSECURITY pfnReadSD,
[in, optional] PFNWRITEOBJECTSECURITY pfnWriteSD,
[in] LPARAM lpContext
);

Parameters
[in] pwszObjectPath

The full path of the DS object for which to create an instance of the ISecurityInformation interface.
[in] pwszObjectClass

The class of the object specified by the pwszObjectPath parameter.

[in] dwFlags

Flags used for the security property page associated with the new instance of the ISecurityInformation interface.
This parameter can be any combination of the following flags.

VA L UE M EA N IN G

The security properties are read-only.

DSSI_READ_ONLY
0x00000001

No access check is performed.

DSSI_NO_ACCESS_CHECK
0x00000002

The system access control list (SACL) property is read-only.

DSSI_NO_EDIT_SACL
0x00000004

The object owner property is read-only.

DSSI_NO_EDIT_OWNER
0x00000008
 The object is a root object.
DSSI_IS_ROOT
0x00000010

Do not apply any filters.

DSSI_NO_FILTER
0x00000020

Suppress read-only popup messages.

DSSI_NO_READONLY_MESSAGE
0x00000040

[out] ppSI

A pointer to the instance of the ISecurityInformation interface this function creates.

[in, optional] pfnReadSD

A pointer to a function used to read the security descriptor of the object. This value can be NULL . If pfnReadSD
is not NULL , DSCreateISecurityInfoObject calls the function referenced by pfnReadSD to retrieve the
security descriptor of the object.
[in, optional] pfnWriteSD

A pointer to a function used to write the security descriptor of the object. This value can be NULL . If pfnWriteSD
is not NULL , DSCreateISecurityInfoObject calls the function referenced by pfnWriteSD to write the security
descriptor of the object.
[in] lpContext

Context to pass to the functions identified by the pfnReadSD and pfnWriteSD parameters.

Return value
If the function succeeds, the function returns S_OK.
If the function fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header dssec.h

Librar y DSSec.lib

DLL DSSec.dll
 DSCreateISecurityInfoObjectEx function (dssec.h)
7/2/2022 • 2 minutes to read • Edit Online

The DSCreateISecurityInfoObjectEx function creates an instance of the ISecurityInformation interface

associated with the specified directory service (DS) object on the specified server.

Syntax
HRESULT DSCreateISecurityInfoObjectEx(
[in] LPCWSTR pwszObjectPath,
[in] LPCWSTR pwszObjectClass,
[in] LPCWSTR pwszServer,
[in] LPCWSTR pwszUserName,
[in] LPCWSTR pwszPassword,
[in] DWORD dwFlags,
[out] LPSECURITYINFO *ppSI,
[in, optional] PFNREADOBJECTSECURITY pfnReadSD,
[in, optional] PFNWRITEOBJECTSECURITY pfnWriteSD,
[in] LPARAM lpContext
);

Parameters
[in] pwszObjectPath

The full path of the DS object for which to create an instance of the ISecurityInformation interface.
[in] pwszObjectClass

The class of the object specified by the pwszObjectPath parameter.

[in] pwszServer

The server of the object specified by the pwszObjectPath parameter. If the value of this parameter is NULL , the
server is obtained from the path specified by the pwszObjectPath parameter.
[in] pwszUserName

A user name to be associated with the new ISecurityInformation object. If the value of this parameter is
NULL , the Active Directory Services Interfaces (ADSI) default is used.
[in] pwszPassword

A password to be associated with the new ISecurityInformation object. If the value of this parameter is NULL ,
the Active Directory Services Interfaces (ADSI) default is used.
[in] dwFlags

Flags used for the security property page associated with the new instance of the ISecurityInformation interface.
This parameter can be any combination of the following flags.

VA L UE M EA N IN G
 The security properties are read-only.
DSSI_READ_ONLY
0x00000001

No access check is performed.

DSSI_NO_ACCESS_CHECK
0x00000002

The system access control list (SACL) property is read-only.

DSSI_NO_EDIT_SACL
0x00000004

The object owner property is read-only.

DSSI_NO_EDIT_OWNER
0x00000008

The object is a root object.

DSSI_IS_ROOT
0x00000010

Do not apply any filters.

DSSI_NO_FILTER
0x00000020

Suppress read-only popup messages.

DSSI_NO_READONLY_MESSAGE
0x00000040

[out] ppSI

A pointer to the instance of the ISecurityInformation interface this function creates.

[in, optional] pfnReadSD

A pointer to a function used to read the security descriptor of the object. This value can be NULL . If pfnReadSD
is not NULL , DSCreateISecurityInfoObject calls the function referenced by pfnReadSD to retrieve the security
descriptor of the object.
[in, optional] pfnWriteSD

A pointer to a function used to write the security descriptor of the object. This value can be NULL . If pfnWriteSD
is not NULL , DSCreateISecurityInfoObject calls the function referenced by pfnWriteSD to write the security
descriptor of the object.
[in] lpContext

Context to pass to the functions identified by the pfnReadSD and pfnWriteSD parameters.

Return value
If the function succeeds, the function returns S_OK.
If the function fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.
Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header dssec.h

Librar y DSSec.lib

DLL DSSec.dll
 DSCreateSecurityPage function (dssec.h)
7/2/2022 • 2 minutes to read • Edit Online

The DSCreateSecurityPage function creates a security property page for an Active Directory object. The
resulting property page can be added to a property sheet.

Syntax
HRESULT DSCreateSecurityPage(
[in] LPCWSTR pwszObjectPath,
[in, optional] LPCWSTR pwszObjectClass,
[in] DWORD dwFlags,
[out] HPROPSHEETPAGE *phPage,
[in, optional] PFNREADOBJECTSECURITY pfnReadSD,
[in, optional] PFNWRITEOBJECTSECURITY pfnWriteSD,
[in] LPARAM lpContext
);

Parameters
[in] pwszObjectPath

A pointer to a null -terminated wide character string that represents the full Active Directory path for the object.
[in, optional] pwszObjectClass

A pointer to a null -terminated wide character string that represents the object class. This value can be NULL .
[in] dwFlags

Flags used for the security property page. This parameter can be none or any combination of the following flags.

VA L UE M EA N IN G

The security properties are read-only.

DSSI_READ_ONLY
0x00000001

No access check is performed.

DSSI_NO_ACCESS_CHECK
0x00000002

The system access control list (SACL) property is read-only.

DSSI_NO_EDIT_SACL
0x00000004

The object owner property is read-only.

DSSI_NO_EDIT_OWNER
0x00000008
 The object is a root object.
DSSI_IS_ROOT
0x00000010

Do not apply any filters.

DSSI_NO_FILTER
0x00000020

Suppress read-only popup messages.

DSSI_NO_READONLY_MESSAGE
0x00000040

[out] phPage

A pointer to a HPROPSHEETPAGE that returns the created security property page.

[in, optional] pfnReadSD

A pointer to a function used to read the security descriptor of the object. This value can be NULL . If pfnReadSD
is not NULL , DSCreateSecurityPage calls the function referenced by pfnReadSD to retrieve the security
descriptor of the object.
[in, optional] pfnWriteSD

A pointer to a function used to write the security descriptor of the object. This value can be NULL . If pfnWriteSD
is not NULL , DSCreateSecurityPage calls the function referenced by pfnWriteSD to write the security
descriptor of the object.
[in] lpContext

Context to pass to the functions identified by pfnReadSD or pfnWriteSD.

Return value
If the function succeeds, the function returns S_OK.
If the function fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.

Remarks
The function pointed to by pfnReadSD is defined as follows.

#include <windows.h>

typedef HRESULT (WINAPI *PFNREADOBJECTSECURITY)(

LPCWSTR, // Active Directory path of object
SECURITY_INFORMATION, // the security information to read
PSECURITY_DESCRIPTOR*, // the returned security descriptor
LPARAM // context parameter
);

The DSCreateSecurityPage function will free the security descriptor returned in the third parameter above by
a call to the LocalFree function.
The function pointed to by pfnWriteSD is defined as follows.
 #include <windows.h>

typedef HRESULT (WINAPI *PFNWRITEOBJECTSECURITY)(

LPCWSTR, // Active Directory path of object
SECURITY_INFORMATION, // the security information to write
PSECURITY_DESCRIPTOR, // the security descriptor to write
LPARAM // context parameter
);

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header dssec.h

Librar y DSSec.lib

DLL DSSec.dll

See also
Basic Security Property Page
ISecurityInformation
 DSEditSecurity function (dssec.h)
7/2/2022 • 2 minutes to read • Edit Online

The DSEditSecurity function displays a modal dialog box for editing security on a Directory Services (DS)
object.

Syntax
HRESULT DSEditSecurity(
[in] HWND hwndOwner,
[in] LPCWSTR pwszObjectPath,
[in, optional] LPCWSTR pwszObjectClass,
[in] DWORD dwFlags,
[in, optional] LPCWSTR pwszCaption,
[in, optional] PFNREADOBJECTSECURITY pfnReadSD,
[in, optional] PFNWRITEOBJECTSECURITY pfnWriteSD,
[in] LPARAM lpContext
);

Parameters
[in] hwndOwner

The dialog box owner window.

[in] pwszObjectPath

The full Active Directory Services (ADS) path of the DS object.

[in, optional] pwszObjectClass

The class of the object.

[in] dwFlags

The combination of DSSI_* flags.

[in, optional] pwszCaption

The dialog box caption.

[in, optional] pfnReadSD

The function for reading the object.

[in, optional] pfnWriteSD

The function for writing the object.

[in] lpContext

The context passed into the read or write functions in the pfnReadSD and pfnWriteSD parameters.

Return value
If the function succeeds, the function returns S_OK.
If the function fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see
Common HRESULT Values.

Requirements

Minimum suppor ted client None supported

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header dssec.h

Librar y DSSec.lib

DLL DSSec.dll
 iads.h header
7/2/2022 • 9 minutes to read • Edit Online

This header is used by multiple technologies. For more information, see:

Active Directory Service Interfaces
Security and Identity
iads.h contains the following programming interfaces:

Interfaces

IADs

The IADs interface defines the basic object features, that is, properties and methods, of any ADSI object.

IADsAccessControlEntry

The IADsAccessControlEntry interface is a dual interface that enables directory clients to access and manipulate individual
access-control entries (ACEs) of the owning object.

IADsAccessControlList

The IADsAccessControlList interface is a dual interface that manages individual access-control entries (ACEs).

IADsAcl

The IADsAcl interface provides methods for an ADSI client to access and manipulate the ACL or Inherited ACL attribute values.
This interface manipulates the attributes.

IADsADSystemInfo

The IADsADSystemInfo interface retrieves data about the local computer if it is running a Windows operating system in a
Windows domain. For example, you can get the domain, site, and distinguished name of the local computer.

IADsBackLink

The IADsBackLink interface provides methods for an ADSI client to access the Back Link attribute. You can call the property
methods of this interface to obtain and modify the attribute.

IADsCaseIgnoreList

The IADsCaseIgnoreList interface provides methods for an ADSI client to access the Case Ignore List attribute. You can call the
property methods of this interface to obtain and modify the attribute.

IADsClass

The IADsClass interface is designed for managing schema class objects that provide class definitions for any ADSI object. Other
schema management interfaces include IADsProperty for attribute definitions and IADsSyntax for attribute syntax.
IADsCollection

The IADsCollection interface is a dual interface that enables its hosting ADSI object to define and manage an arbitrary set of
named data elements for a directory service.

IADsComputer

The IADsComputer interface is a dual interface that inherits from IADs.

IADsComputerOperations

The IADsComputerOperations interface is a dual interface that inherits from IADs.

IADsContainer

The IADsContainer interface enables an ADSI container object to create, delete, and manage contained ADSI objects.
Container objects represent hierarchical directory trees, such as in a file system, and to organize the directory hierarchy.

IADsDeleteOps

The IADsDeleteOps interface specifies a method an object can use to delete itself from the underlying directory. For a
container object, the method deletes its children and the entire subtree.

IADsDNWithBinary

The IADsDNWithBinary interface provides methods for an ADSI client to associate a distinguished name (DN) with the GUID
of an object.

IADsDNWithString

The IADsDNWithString interface provides methods for an ADSI client to associate a distinguished name (DN) to a string value.

IADsDomain

The IADsDomain interface is a dual interface that inherits from IADs.

IADsEmail

The IADsEmail interface provides methods for an ADSI client to access the Email Address attribute.

IADsExtension

The IADsExtension interface forms the basis of the ADSI application extension model.

IADsFaxNumber

The IADsFaxNumber interface provides methods for an ADSI client to access the Facsimile Telephone Number attribute.

IADsFileService

The IADsFileService interface is a dual interface that inherits from IADsService.

IADsFileServiceOperations

The IADsFileServiceOperations interface is a dual interface that inherits from IADsServiceOperations.

IADsFileShare

The IADsFileShare interface is a dual interface that inherits from IADs. It is designed for representing a published file share
across the network. Call the methods on IADsFileShare to access or publish data about a file share point.

IADsGroup

Manages group membership data in a directory service.

IADsHold

The IADsHold interface provides methods for an ADSI client to access the Hold attribute.

IADsLargeInteger

Used to manipulate 64-bit integers of the LargeInteger type.

IADsLocality

The IADsLocality interface is a dual interface that inherits from IADs.

IADsMembers

The IADsMembers interface is a dual interface.

IADsNamespaces

The IADsNamespaces interface is implemented by the ADs provider and is used for managing namespace objects.

IADsNameTranslate

The IADsNameTranslateinterface translates distinguished names (DNs) among various formats as defined in the
ADS_NAME_TYPE_ENUM enumeration. The feature is available to objects in Active Directory.

IADsNetAddress

The IADsNetAddress interface provides methods for an ADSI client to access the Net Address attribute.

IADsO

The IADsO interface is a dual interface that inherits from IADs.

IADsObjectOptions

Provides a direct mechanism to specify and obtain provider-specific options for manipulating an ADSI object.

IADsOctetList

The IADsOctetList interface provides methods for an ADSI client to access the Octet List attribute.

IADsOpenDSObject

The IADsOpenDSObject interface is designed to supply a security context for binding to an object in the underlying directory
store.
IADsOU

Used to manage organizationalUnit objects.

IADsPath

The IADsPath interface provides methods for an ADSI client to access the Path attribute.

IADsPathname

Parses the X.500 and Windows path in ADSI.

IADsPostalAddress

The IADsPostalAddress interface provides methods for an ADSI client to access the Postal Address attribute.

IADsPrintJob

The IADsPrintJob interface is a dual interface that inherits from IADs.

IADsPrintJobOperations

The IADsPrintJobOperations interface is a dual interface that inherits from IADs.

IADsPrintQueue

The IADsPrintQueue interface represents a printer on a network.

IADsPrintQueueOperations

Used to control a printer from across a network.

IADsProperty

The IADsProperty interface is designed to manage a single attribute definition for a schema class object.

IADsPropertyEntry

The IADsPropertyEntry interface is used to manage a property entry in the property cache.

IADsPropertyList

The IADsPropertyList interface is used to modify, read, and update a list of property entries in the property cache of an object.

IADsPropertyValue

Used to represent the value of an IADsPropertyEntry object in a predefined data type.

IADsPropertyValue2

Used to represent the value of an IADsPropertyEntry object in any data format.

IADsReplicaPointer

The IADsReplicaPointer interface provides methods for an ADSI client to access the Replica Pointer attribute.
IADsResource

The IADsResource interface is a dual interface that inherits from IADs. It is designed to manage an open resource for a file
service across a network.

IADsSecurityDescriptor

Provides access to properties on an ADSI security descriptor object.

IADsSecurityUtility

The IADsSecurityUtility interface is used to get, set, or retrieve the security descriptor on a file, fileshare, or registry key.

IADsService

The IADsService interface is a dual interface that inherits from IADs.

IADsServiceOperations

The IADsServiceOperations interface is a dual interface that inherits from IADs.

IADsSession

The IADsSession interface is a dual interface that inherits from IADs. It is designed to represent an active session for file service
across a network.

IADsSyntax

The IADsSyntax interface specifies methods to identify and modify the available Automation data types used to represent its
data.

IADsTimestamp

The IADsTimestamp interface provides methods for an ADSI client to access the Timestamp attribute.

IADsTypedName

The IADsTypedName interface provides methods for an ADSI client to access the Typed Name attribute.

IADsUser

The IADsUser interface is a dual interface that inherits from IADs.

IADsWinNTSystemInfo

The IADsWinNTSystemInfo interface retrieves the WinNT system information about a computer. Such system information
includes user account name, user domain, host name, and the primary domain controller of the host computer.

IDirectoryObject

The IDirectoryObject interface is a non-Automation COM interface that provides clients with direct access to directory service
objects.

IDirectorySchemaMgmt

Not currently implemented and should not be used.

 IDirectorySearch

The IDirectorySearch interface is a pure COM interface that provides a low overhead method that non-Automation clients can
use to perform queries in the underlying directory.

Structures

ADS_ATTR_DEF

The ADS_ATTR_DEF structure is used only as a part of IDirectorySchemaMgmt, which is an obsolete interface.

ADS_ATTR_INFO

Used to contain one or more attribute values for use with the IDirectoryObject::CreateDSObject,
IDirectoryObject::GetObjectAttributes, or IDirectoryObject::SetObjectAttributes method.

ADS_BACKLINK

The ADS_BACKLINK structure is an ADSI representation of the Back Link attribute syntax.

ADS_CASEIGNORE_LIST

The ADS_CASEIGNORE_LIST structure is an ADSI representation of the Case Ignore List attribute syntax.

ADS_CLASS_DEF

The ADS_CLASS_DEF structure is used only as a part of IDirectorySchemaMgmt, which is an obsolete interface. The
information that follows is provided for legacy purposes only. The ADS_CLASS_DEF structure holds the definitions of an object
class.

ADS_DN_WITH_BINARY

Used with the ADSVALUE structure to contain a distinguished name attribute value that also contains binary data.

ADS_DN_WITH_STRING

Used with the ADSVALUE structure to contain a distinguished name attribute value that also contains string data.

ADS_EMAIL

The ADS_EMAIL structure is an ADSI representation of the EMail Address attribute syntax.

ADS_FAXNUMBER

The ADS_FAXNUMBER structure is an ADSI representation of the Facsimile Telephone Number attribute syntax.

ADS_HOLD

The ADS_HOLD structure is an ADSI representation of the Hold attribute syntax.

ADS_NETADDRESS

The ADS_NETADDRESS structure is an ADSI representation of the Net Address attribute syntax.
ADS_NT_SECURITY_DESCRIPTOR

The ADS_NT_SECURITY_DESCRIPTOR structure defines the data type of the security descriptor for Windows.

ADS_OBJECT_INFO

The ADS_OBJECT_INFO structure specifies the data, including the identity and location, of a directory service object.

ADS_OCTET_LIST

The ADS_OCTET_LIST structure is an ADSI representation of an ordered sequence of single-byte strings.

ADS_OCTET_STRING

The ADS_OCTET_STRING structure is an ADSI representation of the Octet String attribute syntax used in Active Directory.

ADS_PATH

The ADS_PATH structure is an ADSI representation of the Path attribute syntax.

ADS_POSTALADDRESS

The ADS_POSTALADDRESS structure is an ADSI representation of the Postal Address attribute.

ADS_PROV_SPECIFIC

The ADS_PROV_SPECIFIC structure contains provider-specific data represented as a binary large object (BLOB).

ADS_REPLICAPOINTER

Represents an ADSI representation of the Replica Pointer attribute syntax.

ADS_SEARCH_COLUMN

The ADS_SEARCH_COLUMN structure specifies the contents of a search column in the query returned from the directory
service database.

ADS_SEARCHPREF_INFO

The ADS_SEARCHPREF_INFO structure specifies the query preferences.

ADS_SORTKEY

The ADS_SORTKEY structure specifies how to sort a query.

ADS_TIMESTAMP

The ADS_TIMESTAMP structure is an ADSI representation of the Timestamp attribute syntax.

ADS_TYPEDNAME

Represents an ADSI representation of Typed Name attribute syntax.

 ADS_VLV

Contains metadata used to conduct virtual list view (VLV) searches.

ADSVALUE

Contains a value specified as an ADSI data type.

Enumerations

ADS_ACEFLAG_ENUM

The ADS_ACEFLAG_ENUM enumeration is used to specify the behavior of an Access Control Entry (ACE) for an Active
Directory object.

ADS_ACETYPE_ENUM

Used to specify the type of an access-control entry for Active Directory objects.

ADS_AUTHENTICATION_ENUM

Specifies authentication options used in ADSI for binding to directory service objects.

ADS_CHASE_REFERRALS_ENUM

The ADS_CHASE_REFERRALS_ENUM enumeration specifies if, and how, referral chasing occurs.

ADS_DEREFENUM

The ADS_DEREFENUM enumeration specifies the process through which aliases are dereferenced.

ADS_DISPLAY_ENUM

The ADS_DISPLAY_ENUM enumeration specifies how a path is to be displayed.

ADS_ESCAPE_MODE_ENUM

Specifies how escape characters are displayed in a directory path.

ADS_FLAGTYPE_ENUM

The ADS_FLAGTYPE_ENUM enumeration specifies values that can be used to indicate the presence of the ObjectType or
InheritedObjectType fields in the access-control entry (ACE).

ADS_FORMAT_ENUM

Specifies the available path value types used by the IADsPathname::Retrieve method.

ADS_GROUP_TYPE_ENUM

Specifies the type of group objects in ADSI.

ADS_NAME_INITTYPE_ENUM

The ADS_NAME_INITTYPE_ENUM enumeration specifies the types of initialization to perform on a NameTranslate object. It is
used in the IADsNameTranslate interface.

ADS_NAME_TYPE_ENUM

Specifies the formats used for representing distinguished names.

ADS_OPTION_ENUM

Contains values that indicate the options that can be retrieved or set with the IADsObjectOptions.GetOption and
IADsObjectOptions.SetOption methods.

ADS_PASSWORD_ENCODING_ENUM

Identifies the type of password encoding used with the ADS_OPTION_PASSWORD_METHOD option in the
IADsObjectOptions::GetOption and IADsObjectOptions::SetOption methods.

ADS_PATHTYPE_ENUM

The ADS_PATHTYPE_ENUM enumeration specifies the type of object on which the IADsSecurityUtility interface is going to add
or modify a security descriptor.

ADS_PREFERENCES_ENUM

The ADS_PREFERENCES_ENUM enumeration specifies the query preferences of the OLE DB provider for ADSI.

ADS_PROPERTY_OPERATION_ENUM

Specifies ways to update a named property in the cache.

ADS_RIGHTS_ENUM

Specifies access rights assigned to an Active Directory object.

ADS_SCOPEENUM

Specifies the scope of a directory search.

ADS_SD_CONTROL_ENUM

The ADS_SD_CONTROL_ENUM enumeration specifies control flags for a security descriptor.

ADS_SD_FORMAT_ENUM

The ADS_SD_FORMAT_ENUM enumeration specifies the format that the security descriptor of an object will be converted to
by the IADsSecurityUtility interface.

ADS_SD_REVISION_ENUM

Specifies the revision number of the access-control entry (ACE), or the access-control list (ACL), for Active Directory.

ADS_SEARCHPREF_ENUM

Specifies preferences for an IDirectorySearch object.

ADS_SECURITY_INFO_ENUM

Specifies the available options for examining security data of an object.

ADS_SETTYPE_ENUM

The ADS_SETTYPE_ENUM enumeration specifies the available pathname format used by the IADsPathname::Set method.

ADS_STATUSENUM

Specifies the status of a search preference set with the IDirectorySearch::SetSearchPreference method.

ADS_SYSTEMFLAG_ENUM

The ADS_SYSTEMFLAG_ENUM enumeration defines some of the values that can be assigned to the systemFlags attribute.
Some of the values in the enumeration are specific to attributeSchema objects; other values can be set on objects of any class.

ADS_USER_FLAG_ENUM

Defines the flags used for setting user properties in the directory.

ADSI_DIALECT_ENUM

The ADSI_DIALECT_ENUM enumeration specifies query dialects used in the OLE DB provider for ADSI.

ADSTYPEENUM

Used to identify the data type of an ADSI property value.

 identitycommon.h header
7/2/2022 • 2 minutes to read • Edit Online

This header is used by Security and Identity. For more information, see:
Security and Identity
identitycommon.h contains the following programming interfaces:

Enumerations

IDENTITY_TYPE

Specifies the type of identities to enumerate.

 IDENTITY_TYPE enumeration (identitycommon.h)
7/2/2022 • 2 minutes to read • Edit Online

Specifies the type of identities to enumerate. This enumeration is used by the IIdentityProvider::GetIdentityEnum
and IIdentityStore::EnumerateIdentities methods.

Syntax
typedef enum _IdentityType {
IDENTITIES_ALL = 0,
IDENTITIES_ME_ONLY = 0x1
} IDENTITY_TYPE;

Constants

IDENTITIES_ALL
Value: 0
Enumerate all identities.

IDENTITIES_ME_ONLY
Value: 0x1
Enumerate only identities associated with the current user.

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Header identitycommon.h
 identityprovider.h header
7/2/2022 • 2 minutes to read • Edit Online

This header is used by Security and Identity. For more information, see:
Security and Identity
identityprovider.h contains the following programming interfaces:

Interfaces

IAssociatedIdentityProvider

Allows an identity provider to associate identities with local user accounts.

IConnectedIdentityProvider

Provides methods of interaction with a connected identity provider.

IIdentityAdvise

Allows an identity provider to notify a calling application when an identity is updated.

IIdentityProvider

Represents an identity provider.

 IAssociatedIdentityProvider interface
(identityprovider.h)
7/2/2022 • 2 minutes to read • Edit Online

The IAssociatedIdentityProvider interface allows an identity provider to associate identities with local user
accounts.

Inheritance
The IAssociatedIdentityProvider interface inherits from the IUnknown interface.
IAssociatedIdentityProvider also has these types of members:

Methods
The IAssociatedIdentityProvider interface has these methods.

IAssociatedIdentityProvider::AssociateIdentity

Associates an identity with a local user account.

IAssociatedIdentityProvider::ChangeCredential

Changes the credentials associated with the specified identity.

IAssociatedIdentityProvider::DisassociateIdentity

Disassociates the specified identity from a local user account.

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Target Platform Windows

Header identityprovider.h
 IAssociatedIdentityProvider::AssociateIdentity
method (identityprovider.h)
7/2/2022 • 2 minutes to read • Edit Online

The AssociateIdentity method associates an identity with a local user account.

Syntax
HRESULT AssociateIdentity(
[in] HWND hwndParent,
[out] IPropertyStore **ppPropertyStore
);

Parameters
[in] hwndParent

A handle to the parent of the window used to collect account credentials.

[out] ppPropertyStore

A pointer to the IProper tyStore interface associated with the identity.

Return value
If the method succeeds, it returns S_OK .
If the method fails, it returns an error code. For a list of common error codes, see Common HRESULT Values.

Remarks
This method should call CredUIPromptForWindowsCredentials to collect account credentials.

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Target Platform Windows

Header identityprovider.h

See also
IAssociatedIdentityProvider
 IAssociatedIdentityProvider::ChangeCredential
method (identityprovider.h)
7/2/2022 • 2 minutes to read • Edit Online

The ChangeCredential method changes the credentials associated with the specified identity.

Syntax
HRESULT ChangeCredential(
[in] HWND hwndParent,
[in] LPCWSTR lpszUniqueID
);

Parameters
[in] hwndParent

A handle to the parent of the window used to collect account credentials.

[in] lpszUniqueID

The identity for which to change the credentials.

Return value
If the method succeeds, it returns S_OK .
If the method fails, it returns an error code. For a list of common error codes, see Common HRESULT Values.

Remarks
This method should call CredUIPromptForWindowsCredentials to collect account credentials.

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Target Platform Windows

Header identityprovider.h

See also
IAssociatedIdentityProvider
 IAssociatedIdentityProvider::DisassociateIdentity
method (identityprovider.h)
7/2/2022 • 2 minutes to read • Edit Online

The DisassociateIdentity method disassociates the specified identity from a local user account.

Syntax
HRESULT DisassociateIdentity(
[in] HWND hwndParent,
[in] LPCWSTR lpszUniqueID
);

Parameters
[in] hwndParent

A handle to the parent of the window used to collect account credentials.

[in] lpszUniqueID

The identity to disassociate.

Return value
If the method succeeds, it returns S_OK .
If the method fails, it returns an error code. For a list of common error codes, see Common HRESULT Values.

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Target Platform Windows

Header identityprovider.h

See also
IAssociatedIdentityProvider
 IConnectedIdentityProvider interface
(identityprovider.h)
7/2/2022 • 2 minutes to read • Edit Online

Provides methods of interaction with a connected identity provider.

Inheritance
The IConnectedIdentityProvider interface inherits from the IUnknown interface.
IConnectedIdentityProvider also has these types of members:

Methods
The IConnectedIdentityProvider interface has these methods.

IConnectedIdentityProvider::ConnectIdentity

Connects an identity to a domain user.

IConnectedIdentityProvider::DisconnectIdentity

Disconnects an online identity from the current domain user.

IConnectedIdentityProvider::GetUrl

Returns the URL string for the specified wizard or webpage.

Requirements

Minimum suppor ted client Windows 8 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2012 [desktop apps only]

Target Platform Windows

Header identityprovider.h
 IConnectedIdentityProvider::ConnectIdentity
method (identityprovider.h)
7/2/2022 • 2 minutes to read • Edit Online

Connects an identity to a domain user.

Syntax
HRESULT ConnectIdentity(
[in] BYTE *AuthBuffer,
[in] ULONG AuthBufferSize
);

Parameters
[in] AuthBuffer

A marshaled authentication buffer SEC_WINNT_AUTH_IDENTITY_EX2 structure that contains the credential of

the online identity. The buffer can be constructed by the caller by using the CredPackAuthenticationBuffer
function with the CRED_PACK_ID_PROVIDER_CREDENTIALS option or returned by an online identity credential
provider from the CredUIPromptForWindowsCredentials function. The buffer can be optionally encrypted by
calling the SspiEncryptAuthIdentityEx function with the SEC_WINNT_AUTH_IDENTITY_ENCRYPT_SAME_LOGON
option.
[in] AuthBufferSize

Size, in bytes, of the AuthBuffer parameter.

Return value
If the method succeeds, returns S_OK.
If the method fails, returns a Win32 error code.

RET URN C O DE DESC RIP T IO N

The method succeeded.

S_OK

The user name or password is not correct.

ERROR_LOGON_FAILURE

The domain user is already connected or associated with an

ERROR_USER_EXISTS online identity from this provider.

The format of the online user name is not valid.

ERROR_INVALID_ACCOUNT_NAME
Remarks
The AuthBuffer parameter can be encrypted in the system context if the credential is collected on the secure
desktop. In that case, the identity provider cannot decrypt the credential in the current process. To decrypt the
buffer, the identity provider will need to send the credential to a process that is running in the system context.

Requirements

Minimum suppor ted client Windows 8 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2012 [desktop apps only]

Target Platform Windows

Header identityprovider.h

See also
IConnectedIdentityProvider
 IConnectedIdentityProvider::DisconnectIdentity
method (identityprovider.h)
7/2/2022 • 2 minutes to read • Edit Online

Disconnects an online identity from the current domain user.

Syntax
HRESULT DisconnectIdentity();

Return value
If the method succeeds, the method returns S_OK.
If the method fails, the method returns a Win32 error code.

RET URN C O DE DESC RIP T IO N

The method succeeded.

S_OK

The domain user is not connected to an online identity.

ERROR_NO_SUCH_USER

Requirements

Minimum suppor ted client Windows 8 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2012 [desktop apps only]

Target Platform Windows

Header identityprovider.h

See also
IConnectedIdentityProvider
 IConnectedIdentityProvider::GetUrl method
(identityprovider.h)
7/2/2022 • 2 minutes to read • Edit Online

Returns the URL string for the specified wizard or webpage.

Syntax
HRESULT GetUrl(
[in] IDENTITY_URL Identifier,
[in] IBindCtx *Context,
[out] VARIANT *PostData,
[out] LPWSTR *Url
);

Parameters
[in] Identifier

Identifies the wizard or webpage that should be returned.

[in] Context

Describes the context in which the URL will be displayed.

[out] PostData

A VARIANT of type VT_ARRAY and VT_UI1 that will be posted to the provided URL. If the post data is not
required, this parameter should be set to VT_EMPTY.
[out] Url

Returns a URL for the specified identity wizard or webpage. The URL must begin with https:// .

Return value
If the method succeeds, the method returns S_OK.
If the method fails, the method returns a Win32 error code.

Requirements

Minimum suppor ted client Windows 8 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2012 [desktop apps only]

Target Platform Windows

Header identityprovider.h
See also
IConnectedIdentityProvider
 IIdentityAdvise interface (identityprovider.h)
7/2/2022 • 2 minutes to read • Edit Online

The IIdentityAdvise interface allows an identity provider to notify a calling application when an identity is
updated.

Inheritance
The IIdentityAdvise interface inherits from the IUnknown interface. IIdentityAdvise also has these types of
members:

Methods
The IIdentityAdvise interface has these methods.

IIdentityAdvise::IdentityUpdated

Is called by an identity provider to notify a calling application that an identity event occurred.

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Target Platform Windows

Header identityprovider.h

See also
IIdentityProvider
IIdentityProvider::Advise
 IIdentityAdvise::IdentityUpdated method
(identityprovider.h)
7/2/2022 • 2 minutes to read • Edit Online

The IdentityUpdated method is called by an identity provider to notify a calling application that an identity
event occurred. An application calls the IIdentityProvider::Advise method to specify events for which it is to be
notified.

Syntax
HRESULT IdentityUpdated(
[in] DWORD dwIdentityUpdateEvents,
[in] LPCWSTR lpszUniqueID
);

Parameters
[in] dwIdentityUpdateEvents

The identity events that occurred. The value of this parameter can be zero or more of the following values
combined by using a bitwise-OR operation.

VA L UE M EA N IN G

An identity was associated with the identity provider.

IDENTITY_ASSOCIATED
0X0001

An identity was disassociated from the identity provider.

IDENTITY_DISASSOCIATED
0X0002

A new identity was created.

IDENTITY_CREATED
0X0004

An identity was imported from another identity provider.

IDENTITY_IMPORTED
0X0008

An identity was deleted from the identity store.

IDENTITY_DELETED
0X0010

The value of a property of an identity changed.

IDENTITY_PROPCHANGE
0X0020
 The identity is a connected identity.
IDENTITY_CONNECTED
0X0040

The identity was disconnected from the identity provider.

IDENTITY_DISCONNECTED
0X0080

[in] lpszUniqueID

The identity associated with the events that occurred.

Return value
If the method succeeds, it returns S_OK .
If the method fails, it returns an error code. For a list of common error codes, see Common HRESULT Values.

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Target Platform Windows

Header identityprovider.h

See also
IIdentityAdvise
 IIdentityProvider interface (identityprovider.h)
7/2/2022 • 2 minutes to read • Edit Online

The IIdentityProvider interface represents an identity provider.

Inheritance
The IIdentityProvider interface inherits from the IUnknown interface. IIdentityProvider also has these types
of members:

Methods
The IIdentityProvider interface has these methods.

IIdentityProvider::Advise

Allows a calling application to specify the list of identity events for which the application is to be notified.

IIdentityProvider::Create

Creates a new identity associated with the specified user name.

IIdentityProvider::Delete

Removes the specified identity from the identity store or the specified properties from the identity.

IIdentityProvider::FindByUniqueID

Retrieves a pointer to the IPropertyStore interface instance associated with the specified identity.

IIdentityProvider::GetIdentityEnum

Retrieves an IEnumUnknown interface pointer that can be used to enumerate identities.

IIdentityProvider::GetProviderPropertyStore

Retrieves a pointer to the IPropertyStore interface associated with the identity provider.

IIdentityProvider::Import

Imports an identity to the system.

IIdentityProvider::UnAdvise

Deletes a connection created by calling the Advise method.

Requirements
Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Target Platform Windows

Header identityprovider.h
 IIdentityProvider::Advise method (identityprovider.h)
7/2/2022 • 2 minutes to read • Edit Online

The Advise method allows a calling application to specify the list of identity events for which the application is
to be notified.

Syntax
HRESULT Advise(
[in] IIdentityAdvise *pIdentityAdvise,
[in] DWORD dwIdentityUpdateEvents,
[out] DWORD *pdwCookie
);

Parameters
[in] pIdentityAdvise

A pointer to the IIdentityAdvise interface implemented by the calling application. This interface provides a
method that the identity provider can call when one of the events specified by the dwIdentityUpdateEvents
parameter occurs.
[in] dwIdentityUpdateEvents

The identity events for which the calling application is to be notified. The value of this parameter can be zero or
more of the following values combined by using a bitwise-OR operation.

VA L UE M EA N IN G

An identity was associated with the identity provider.

IDENTITY_ASSOCIATED
0X0001

An identity was disassociated from the identity provider.

IDENTITY_DISASSOCIATED
0X0002

A new identity was created.

IDENTITY_CREATED
0X0004

An identity was imported from another identity provider.

IDENTITY_IMPORTED
0X0008

An identity was deleted from the identity store.

IDENTITY_DELETED
0X0010
 The value of a property of an identity changed.
IDENTITY_PROPCHANGE
0X0020

[out] pdwCookie

A pointer to a value that identifies this connection. When you have finished using this connection, delete it by
passing this value to the UnAdvise method.

Return value
If the method succeeds, it returns S_OK .
If the method fails, it returns an error code. For a list of common error codes, see Common HRESULT Values.

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Target Platform Windows

Header identityprovider.h

See also
IIdentityAdvise::IdentityUpdated
IIdentityProvider
 IIdentityProvider::Create method (identityprovider.h)
7/2/2022 • 2 minutes to read • Edit Online

The Create method creates a new identity associated with the specified user name.

Syntax
HRESULT Create(
[in] LPCWSTR lpszUserName,
[out] IPropertyStore **ppPropertyStore,
[in, optional] const PROPVARIANT *pKeywordsToAdd
);

Parameters
[in] lpszUserName

The user name with which to associate the new identity.

[out] ppPropertyStore

A pointer to the IPropertyStore interface that represents the property store associated with the new identity.
[in, optional] pKeywordsToAdd

The properties to associate with the new identity.

Return value
If the method succeeds, it returns S_OK .
If the method fails, it returns an error code. For a list of common error codes, see Common HRESULT Values.

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Target Platform Windows

Header identityprovider.h

See also
IIdentityProvider
 IIdentityProvider::Delete method (identityprovider.h)
7/2/2022 • 2 minutes to read • Edit Online

The Delete method removes the specified identity from the identity store or the specified properties from the
identity.

Syntax
HRESULT Delete(
[in] LPCWSTR lpszUniqueID,
[in, optional] const PROPVARIANT *pKeywordsToDelete
);

Parameters
[in] lpszUniqueID

The unique name associated with the identity.

[in, optional] pKeywordsToDelete

The names of properties to delete. If the value of this parameter is NULL , the identity is deleted.

Return value
If the method succeeds, it returns S_OK .
If the method fails, it returns an error code. For a list of common error codes, see Common HRESULT Values.

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Target Platform Windows

Header identityprovider.h

See also
IIdentityProvider
 IIdentityProvider::FindByUniqueID method
(identityprovider.h)
7/2/2022 • 2 minutes to read • Edit Online

The FindByUniqueID method retrieves a pointer to the IProper tyStore interface instance associated with the
specified identity.

Syntax
HRESULT FindByUniqueID(
[in] LPCWSTR lpszUniqueID,
[out] IPropertyStore **ppPropertyStore
);

Parameters
[in] lpszUniqueID

The unique identity to find.

[out] ppPropertyStore

A pointer to the instance of the IProper tyStore interface associated with the specified identity.

Return value
If the method succeeds, it returns S_OK .
If the method fails, it returns an error code. For a list of common error codes, see Common HRESULT Values.

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Target Platform Windows

Header identityprovider.h

See also
IIdentityProvider
 IIdentityProvider::GetIdentityEnum method
(identityprovider.h)
7/2/2022 • 2 minutes to read • Edit Online

The GetIdentityEnum method retrieves an IEnumUnknown interface pointer that can be used to enumerate
identities.

Syntax
HRESULT GetIdentityEnum(
[in] const IDENTITY_TYPE eIdentityType,
[in, optional] const PROPERTYKEY *pFilterkey,
[in, optional] const PROPVARIANT *pFilterPropVarValue,
[out] IEnumUnknown **ppIdentityEnum
);

Parameters
[in] eIdentityType

A value of the IDENTITY_TYPE enumeration that indicates the type of identities to enumerate.
[in, optional] pFilterkey

A pointer to a property key that specifies a property. If the value of this parameter is not NULL , only identities
that support the property specified by this parameter are enumerated.
[in, optional] pFilterPropVarValue

A pointer to a property value. If the values of this parameter and the pFilterkey parameter are not NULL , only
identities that have the property value specified by this parameter are enumerated.
[out] ppIdentityEnum

A pointer to an IEnumUnknown interface pointer that can be used to enumerate identities.

Return value
If the method succeeds, it returns S_OK .
If the method fails, it returns an error code. For a list of common error codes, see Common HRESULT Values.

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Target Platform Windows

 Header identityprovider.h

See also
IIdentityProvider
 IIdentityProvider::GetProviderPropertyStore method
(identityprovider.h)
7/2/2022 • 2 minutes to read • Edit Online

The GetProviderProper tyStore method retrieves a pointer to the IProper tyStore interface associated with
the identity provider.

Syntax
HRESULT GetProviderPropertyStore(
[out] IPropertyStore **ppPropertyStore
);

Parameters
[out] ppPropertyStore

A pointer to the global IProper tyStore interface associated with this identity provider.

Return value
If the method succeeds, it returns S_OK .
If the method fails, it returns an error code. For a list of common error codes, see Common HRESULT Values.

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Target Platform Windows

Header identityprovider.h

See also
IIdentityProvider
 IIdentityProvider::Import method (identityprovider.h)
7/2/2022 • 2 minutes to read • Edit Online

The Impor t method imports an identity to the system.

Syntax
HRESULT Import(
[in] IPropertyStore *pPropertyStore
);

Parameters
[in] pPropertyStore

A pointer to the IProper tyStore interface that specifies all information required to create the new identity on
the system.

Return value
If the method succeeds, it returns S_OK .
If the method fails, it returns an error code. For a list of common error codes, see Common HRESULT Values.

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Target Platform Windows

Header identityprovider.h

See also
IIdentityProvider
 IIdentityProvider::UnAdvise method
(identityprovider.h)
7/2/2022 • 2 minutes to read • Edit Online

The UnAdvise method deletes a connection created by calling the Advise method.

Syntax
HRESULT UnAdvise(
[in] const DWORD dwCookie
);

Parameters
[in] dwCookie

A value that identifies the connection to delete.

Return value
If the method succeeds, it returns S_OK .
If the method fails, it returns an error code. For a list of common error codes, see Common HRESULT Values.

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Target Platform Windows

Header identityprovider.h

See also
Advise
IIdentityProvider
 identitystore.h header
7/2/2022 • 2 minutes to read • Edit Online

This header is used by Security and Identity. For more information, see:
Security and Identity
identitystore.h contains the following programming interfaces:

Interfaces

IIdentityStore

Provides methods to enumerate and manage identities and identity providers.

 IIdentityStore interface (identitystore.h)
7/2/2022 • 2 minutes to read • Edit Online

The IIdentityStore interface provides methods to enumerate and manage identities and identity providers.

Inheritance
The IIdentityStore interface inherits from the IUnknown interface. IIdentityStore also has these types of
members:

Methods
The IIdentityStore interface has these methods.

IIdentityStore::AddToCache

Caches the specified identity in the registry.

IIdentityStore::ConvertToSid

Retrieves the security identifier (SID) associated with the specified identity and identity provider.

IIdentityStore::EnumerateIdentities

Gets a pointer to an IEnumUnknown interface pointer that can be used to enumerate identities across identity providers.

IIdentityStore::GetAt

Retrieves an IIdentityProvider interface pointer for the specified identity provider.

IIdentityStore::GetCount

Gets the number of identity providers registered on the system.

IIdentityStore::Reset

Sets the current index of the identity enumeration to zero.

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Target Platform Windows

Header identitystore.h
See also
IIdentityProvider
 IIdentityStore::AddToCache method (identitystore.h)
7/2/2022 • 2 minutes to read • Edit Online

The AddtoCache method caches the specified identity in the registry.

Syntax
HRESULT AddToCache(
[in] LPCWSTR lpszUniqueID,
[in] REFGUID ProviderGUID
);

Parameters
[in] lpszUniqueID

The identity to cache.

[in] ProviderGUID

The identity provider associated with the identity.

Return value
If the method succeeds, it returns S_OK .
If the method fails, it returns an error code. For a list of common error codes, see Common HRESULT Values.

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Target Platform Windows

Header identitystore.h

See also
IIdentityStore
 IIdentityStore::ConvertToSid method
(identitystore.h)
7/2/2022 • 2 minutes to read • Edit Online

The Conver tToSid method retrieves the security identifier (SID) associated with the specified identity and
identity provider.

Syntax
HRESULT ConvertToSid(
[in] LPCWSTR lpszUniqueID,
[in] REFGUID ProviderGUID,
[in] USHORT cbSid,
[in, out] BYTE *pSid,
[out] USHORT *pcbRequiredSid
);

Parameters
[in] lpszUniqueID

The identity for which to retrieve the SID.

[in] ProviderGUID

The GUID of the identity provider.

[in] cbSid

The size, in bytes, of the buffer pointed to by the pSid parameter.

[in, out] pSid

A pointer to the SID this method retrieves.

[out] pcbRequiredSid

The required length, in bytes, of the pSid buffer.

Return value
If the method succeeds, it returns S_OK .
If the method fails, it returns an error code. For a list of common error codes, see Common HRESULT Values.

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]
 Target Platform Windows

Header identitystore.h

See also
IIdentityStore
 IIdentityStore::EnumerateIdentities method
(identitystore.h)
7/2/2022 • 2 minutes to read • Edit Online

The EnumerateIdentities method gets a pointer to an IEnumUnknown interface pointer that can be used to
enumerate identities across identity providers.

Syntax
HRESULT EnumerateIdentities(
[in] const IDENTITY_TYPE eIdentityType,
[in, optional] const PROPERTYKEY *pFilterkey,
[in, optional] const PROPVARIANT *pFilterPropVarValue,
[out] IEnumUnknown **ppIdentityEnum
);

Parameters
[in] eIdentityType

A value of the IDENTITY_TYPE enumeration that indicates the type of identities to enumerate.
[in, optional] pFilterkey

A pointer to a PROPERTYKEY structure that specifies a property. If the value of this parameter is not NULL , only
identities that support the property specified by this parameter are enumerated.
[in, optional] pFilterPropVarValue

A pointer to a PROPVARIANT structure. If the values of this parameter and the pFilterkey parameters are not
NULL , only identities that have the property value specified by this parameter are enumerated.
[out] ppIdentityEnum

A pointer to an IEnumUnknown interface pointer that can be used to enumerate identities.

Return value
If the method succeeds, it returns S_OK .
If the method fails, it returns an error code. For a list of common error codes, see Common HRESULT Values.

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Target Platform Windows

 Header identitystore.h

See also
IIdentityStore
 IIdentityStore::GetAt method (identitystore.h)
7/2/2022 • 2 minutes to read • Edit Online

The GetAt method retrieves an IIdentityProvider interface pointer for the specified identity provider.

Syntax
HRESULT GetAt(
[in] const DWORD dwProvider,
[in, out] GUID *pProvGuid,
[out] IUnknown **ppIdentityProvider
);

Parameters
[in] dwProvider

The index of the identity provider to retrieve.

[in, out] pProvGuid

On output, this parameter receives a pointer to the GUID of the identity provider that this function retrieves.
[out] ppIdentityProvider

A pointer to the IIdentityProvider interface pointer that this method retrieves.

Return value
If the method succeeds, it returns S_OK .
If the method fails, it returns an error code. For a list of common error codes, see Common HRESULT Values.

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Target Platform Windows

Header identitystore.h

See also
IIdentityStore
 IIdentityStore::GetCount method (identitystore.h)
7/2/2022 • 2 minutes to read • Edit Online

The GetCount method gets the number of identity providers registered on the system.

Syntax
HRESULT GetCount(
[out] DWORD *pdwProviders
);

Parameters
[out] pdwProviders

The number of identity providers registered on the system.

Return value
If the method succeeds, it returns S_OK .
If the method fails, it returns an error code. For a list of common error codes, see Common HRESULT Values.

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Target Platform Windows

Header identitystore.h

See also
IIdentityStore
 IIdentityStore::Reset method (identitystore.h)
7/2/2022 • 2 minutes to read • Edit Online

The Reset method sets the current index of the identity enumeration to zero.

Syntax
HRESULT Reset();

Return value
If the method succeeds, it returns S_OK .
If the method fails, it returns an error code. For a list of common error codes, see Common HRESULT Values.

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Target Platform Windows

Header identitystore.h

See also
IIdentityStore
 keycredmgr.h header
7/2/2022 • 2 minutes to read • Edit Online

This header is used by Security and Identity. For more information, see:
Security and Identity
keycredmgr.h contains the following programming interfaces:

Functions

KeyCredentialManagerFreeInformation

API to free the KeyCredentialManagerInfo pointer variable from the KeyCredentialManagerGetInformation call.

KeyCredentialManagerGetInformation

API to get a unique identifier of the users enrollment.

KeyCredentialManagerGetOperationErrorStates

Prerequisite API to call to determine if the operation will be successful prior.

KeyCredentialManagerShowUIOperation

API to perform the requested WHFB operation.

Structures

KeyCredentialManagerInfo

Data structure returned from KeyCredentialManagerGetInformation.

Enumerations

KeyCredentialManagerOperationErrorStates

Enumeration of Error states returned by the function KeyCredentialManagerGetOperationErrorStates as flags.

KeyCredentialManagerOperationType

These are the operational enum values that are passed to KeyCredentialManagerShowUIOperation.
 KeyCredentialManagerFreeInformation function
(keycredmgr.h)
7/2/2022 • 2 minutes to read • Edit Online

API to free the KeyCredentialManagerInfo pointer variable from the KeyCredentialManagerGetInformation call.

Syntax
void KeyCredentialManagerFreeInformation(
[in] KeyCredentialManagerInfo *keyCredentialManagerInfo
);

Parameters
[in] keyCredentialManagerInfo

Pointer variable to KeyCredentialManagerInfo data structure returned by the

KeyCredentialManagerGetInformation API.

Return value
None

Requirements

Target Platform Windows

Header keycredmgr.h

Librar y Keycredmgr.lib
 KeyCredentialManagerGetInformation function
(keycredmgr.h)
7/2/2022 • 2 minutes to read • Edit Online

API to get a unique identifier of the users enrollment.

Syntax
HRESULT KeyCredentialManagerGetInformation(
[out] KeyCredentialManagerInfo **keyCredentialManagerInfo
);

Parameters
[out] keyCredentialManagerInfo

Pointer to a pointer variable that receives a KeyCredentialManagerFreeInformation function.

Return value
Returns an HRESULT.

Requirements

Target Platform Windows

Header keycredmgr.h

Librar y Keycredmgr.lib
 KeyCredentialManagerGetOperationErrorStates
function (keycredmgr.h)
7/2/2022 • 2 minutes to read • Edit Online

Prerequisite API to call to determine if the operation will be successful prior.

Syntax
HRESULT KeyCredentialManagerGetOperationErrorStates(
[in] KeyCredentialManagerOperationType keyCredentialManagerOperationType,
[out] BOOL *isReady,
[out] KeyCredentialManagerOperationErrorStates *keyCredentialManagerOperationErrorStates
);

Parameters
[in] keyCredentialManagerOperationType

The intended operation from the KeyCredentialManagerOperationType.

[out] isReady

If the operational prerequisite will succeed (True) or (False).

[out] keyCredentialManagerOperationErrorStates

Additional feedback about isReady represented by KeyCredentialManagerOperationErrorStates.

Return value
Returns an HRESULT.

Requirements

Target Platform Windows

Header keycredmgr.h

Librar y Keycredmgr.lib
 KeyCredentialManagerInfo structure (keycredmgr.h)
7/2/2022 • 2 minutes to read • Edit Online

Data structure returned from KeyCredentialManagerGetInformation.

Syntax
typedef struct KeyCredentialManagerInfo {
GUID containerId;
} KeyCredentialManagerInfo;

Members
containerId

Unique identifier of the users WHFB container. Only one container per Windows user profile.

Requirements

Header keycredmgr.h
 KeyCredentialManagerOperationErrorStates
enumeration (keycredmgr.h)
7/2/2022 • 2 minutes to read • Edit Online

Enumeration of Error states returned by the function KeyCredentialManagerGetOperationErrorStates as flags.

Syntax
typedef enum KeyCredentialManagerOperationErrorStates {
KeyCredentialManagerOperationErrorStateNone = 0x0,
KeyCredentialManagerOperationErrorStateDeviceJoinFailure = 0x01,
KeyCredentialManagerOperationErrorStateTokenFailure = 0x02,
KeyCredentialManagerOperationErrorStateCertificateFailure = 0x04,
KeyCredentialManagerOperationErrorStateRemoteSessionFailure = 0x08,
KeyCredentialManagerOperationErrorStatePolicyFailure = 0x10,
KeyCredentialManagerOperationErrorStateHardwareFailure = 0x20,
KeyCredentialManagerOperationErrorStatePinExistsFailure
} ;

Constants

KeyCredentialManagerOperationErrorStateNone
Value: 0x0
No Error equivalent to ERROR_SUCCESS.

KeyCredentialManagerOperationErrorStateDeviceJoinFailure
Value: 0x01
WHFB enrollment will successfully complete because the device is not properly joined to Azure or the Enterprise.

KeyCredentialManagerOperationErrorStateTokenFailure
Value: 0x02
WHFB enrollment will not successfully complete because the user could not get a token from Azure or the Enterprise.

KeyCredentialManagerOperationErrorStateCertificateFailure
Value: 0x04
WHFB enrollment will not successfully complete because the certificate authority and/or certificate template could not be
found.

KeyCredentialManagerOperationErrorStateRemoteSessionFailure
Value: 0x08
WHFB enrollment will not successfully complete because the current session is a remote session.

KeyCredentialManagerOperationErrorStatePolicyFailure
Value: 0x10
WHFB enrollment will not successfully complete because there was an error reading MDM or Group Policy.

KeyCredentialManagerOperationErrorStateHardwareFailure
Value: 0x20
WHFB enrollment will not successful complete because the device does not have the required hardware.
 KeyCredentialManagerOperationErrorStatePinExistsFailure
WHFB is already enrolled on this device.

Requirements

Header keycredmgr.h
 KeyCredentialManagerOperationType enumeration
(keycredmgr.h)
7/2/2022 • 2 minutes to read • Edit Online

These are the operational enum values that are passed to KeyCredentialManagerShowUIOperation.

Syntax
typedef enum KeyCredentialManagerOperationType {
KeyCredentialManagerProvisioning = 0,
KeyCredentialManagerPinChange = 1,
KeyCredentialManagerPinReset = 2
} ;

Constants

KeyCredentialManagerProvisioning
Value: 0
Start the Provisioning operation.

KeyCredentialManagerPinChange
Value: 1
Start the User Change PIN operation.

KeyCredentialManagerPinReset
Value: 2
Start the User PIN Reset operation.

Requirements

Header keycredmgr.h
 KeyCredentialManagerShowUIOperation function
(keycredmgr.h)
7/2/2022 • 2 minutes to read • Edit Online

API to perform the requested WHFB operation.

Syntax
HRESULT KeyCredentialManagerShowUIOperation(
[in] HWND hWndOwner,
[in] KeyCredentialManagerOperationType keyCredentialManagerOperationType
);

Parameters
[in] hWndOwner

Window handle of the calling app.

[in] keyCredentialManagerOperationType

The intended operation from the KeyCredentialManagerOperationType.

Return value
Returns an HRESULT

Requirements

Target Platform Windows

Header keycredmgr.h

Librar y Keycredmgr.lib
 lmaccess.h header
7/2/2022 • 13 minutes to read • Edit Online

This header is used by multiple technologies. For more information, see:

Developer Notes
Network Management
Security and Identity
lmaccess.h contains the following programming interfaces:

Functions

I_NetLogonControl2

Controls various aspects of the Netlogon service.

NetAccessAdd

Not supported.

NetAccessDel

Not supported.

NetAccessEnum

Not supported.

NetAccessGetInfo

Not supported.

NetAccessGetUserPerms

Not supported.

NetAccessSetInfo

Not supported.

NetAddServiceAccount

Creates a standalone managed service account (sMSA) or retrieves the credentials for a group managed service account
(gMSA) and stores the account information on the local computer.

NetEnumerateServiceAccounts

Enumerates the standalone managed service accounts (sMSA) on the specified server.
NetGetAnyDCName

The NetGetAnyDCName function returns the name of any domain controller (DC) for a domain that is directly trusted by the
specified server.

NetGetDCName

The NetGetDCName function returns the name of the primary domain controller (PDC). It does not return the name of the
backup domain controller (BDC) for the specified domain. Also, you cannot remote this function to a non-PDC server.

NetGetDisplayInformationIndex

The NetGetDisplayInformationIndex function returns the index of the first display information entry whose name begins with a
specified string or whose name alphabetically follows the string.

NetGroupAdd

The NetGroupAdd function creates a global group in the security database, which is the security accounts manager (SAM)
database or, in the case of domain controllers, the Active Directory.

NetGroupAddUser

The NetGroupAddUser function gives an existing user account membership in an existing global group in the security
database, which is the security accounts manager (SAM) database or, in the case of domain controllers, the Active Directory.

NetGroupDel

The NetGroupDel function deletes a global group from the security database, which is the security accounts manager (SAM)
database or, in the case of domain controllers, the Active Directory.

NetGroupDelUser

The NetGroupDelUser function removes a user from a particular global group in the security database, which is the security
accounts manager (SAM) database or, in the case of domain controllers, the Active Directory.

NetGroupEnum

The NetGroupEnum function retrieves information about each global group in the security database, which is the security
accounts manager (SAM) database or, in the case of domain controllers, the Active Directory.

NetGroupGetInfo

The NetGroupGetInfo function retrieves information about a particular global group in the security database, which is the
security accounts manager (SAM) database or, in the case of domain controllers, the Active Directory.

NetGroupGetUsers

The NetGroupGetUsers function retrieves a list of the members in a particular global group in the security database, which is
the security accounts manager (SAM) database or, in the case of domain controllers, the Active Directory.

NetGroupSetInfo

The NetGroupSetInfo function sets the parameters of a global group in the security database, which is the security accounts
manager (SAM) database or, in the case of domain controllers, the Active Directory.
NetGroupSetUsers

The NetGroupSetUsers function sets the membership for the specified global group.

NetIsServiceAccount

Tests whether the specified standalone managed service account (sMSA) or group managed service account (gMSA) exists in
the Netlogon store on the specified server.

NetLocalGroupAdd

The NetLocalGroupAdd function creates a local group in the security database, which is the security accounts manager (SAM)
database or, in the case of domain controllers, the Active Directory.

NetLocalGroupAddMember

The NetLocalGroupAddMember function is obsolete. You should use the NetLocalGroupAddMembers function instead.

NetLocalGroupAddMembers

The NetLocalGroupAddMembers function adds membership of one or more existing user accounts or global group accounts
to an existing local group.

NetLocalGroupDel

The NetLocalGroupDel function deletes a local group account and all its members from the security database, which is the
security accounts manager (SAM) database or, in the case of domain controllers, the Active Directory.

NetLocalGroupDelMember

The NetLocalGroupDelMember function is obsolete. You should use the NetLocalGroupDelMembers function instead.

NetLocalGroupDelMembers

The NetLocalGroupDelMembers function removes one or more members from an existing local group. Local group members
can be users or global groups.

NetLocalGroupEnum

The NetLocalGroupEnum function returns information about each local group account on the specified server.

NetLocalGroupGetInfo

The NetLocalGroupGetInfo function retrieves information about a particular local group account on a server.

NetLocalGroupGetMembers

The NetLocalGroupGetMembers function retrieves a list of the members of a particular local group in the security database,
which is the security accounts manager (SAM) database or, in the case of domain controllers, the Active Directory.

NetLocalGroupSetInfo

The NetLocalGroupSetInfo function changes the name of an existing local group. The function also associates a comment with
a local group.
NetLocalGroupSetMembers

The NetLocalGroupSetMembers function sets the membership for the specified local group.

NetQueryDisplayInformation

The NetQueryDisplayInformation function returns user account, computer, or group account information. Call this function to
quickly enumerate account information for display in user interfaces.

NetQueryServiceAccount

Gets information about the specified managed service account.

NetRemoveServiceAccount

Deletes the specified service account from the Active Directory database if the account is a standalone managed service
account (sMSA).

NetUserAdd

The NetUserAdd function adds a user account and assigns a password and privilege level.

NetUserChangePassword

The NetUserChangePassword function changes a user's password for a specified network server or domain.

NetUserDel

The NetUserDel function deletes a user account from a server.

NetUserEnum

The NetUserEnum function retrieves information about all user accounts on a server.

NetUserGetGroups

The NetUserGetGroups function retrieves a list of global groups to which a specified user belongs.

NetUserGetInfo

The NetUserGetInfo function retrieves information about a particular user account on a server.

NetUserGetLocalGroups

The NetUserGetLocalGroups function retrieves a list of local groups to which a specified user belongs.

NetUserModalsGet

The NetUserModalsGet function retrieves global information for all users and global groups in the security database, which is
the security accounts manager (SAM) database or, in the case of domain controllers, the Active Directory.

NetUserModalsSet

The NetUserModalsSet function sets global information for all users and global groups in the security database, which is the
security accounts manager (SAM) database or, in the case of domain controllers, the Active Directory.
 NetUserSetGroups

The NetUserSetGroups function sets global group memberships for a specified user account.

NetUserSetInfo

The NetUserSetInfo function sets the parameters of a user account.

NetValidatePasswordPolicy

The NetValidatePasswordPolicy function allows an application to check password compliance against an application-provided
account database and verify that passwords meet the complexity, aging, minimum length, and history reuse requirements of a
password policy.

NetValidatePasswordPolicyFree

The NetValidatePasswordPolicyFree function frees the memory that the NetValidatePasswordPolicy function allocates for the
OutputArg parameter, which is a NET_VALIDATE_OUTPUT_ARG structure.

Structures

GROUP_INFO_0

The GROUP_INFO_0 structure contains the name of a global group in the security database, which is the security accounts
manager (SAM) database or, in the case of domain controllers, the Active Directory.

GROUP_INFO_1

The GROUP_INFO_1 structure contains a global group name and a comment to associate with the group.

GROUP_INFO_1002

The GROUP_INFO_1002 structure contains a comment to associate with a global group.

GROUP_INFO_1005

The GROUP_INFO_1005 structure contains the resource attributes associated with a global group.

GROUP_INFO_2

The GROUP_INFO_2 structure contains information about a global group, including name, identifier, and resource attributes.

GROUP_INFO_3

The GROUP_INFO_3 structure contains information about a global group, including name, security identifier (SID), and
resource attributes.

GROUP_USERS_INFO_0

The GROUP_USERS_INFO_0 structure contains global group member information.

GROUP_USERS_INFO_1

The GROUP_USERS_INFO_1 structure contains global group member information.

LOCALGROUP_INFO_0

The LOCALGROUP_INFO_0 structure contains a local group name.

LOCALGROUP_INFO_1

The LOCALGROUP_INFO_1 structure contains a local group name and a comment describing the local group.

LOCALGROUP_INFO_1002

The LOCALGROUP_INFO_1002 structure contains a comment describing a local group.

LOCALGROUP_MEMBERS_INFO_0

The LOCALGROUP_MEMBERS_INFO_0 structure contains the security identifier (SID) associated with a local group member.
The member can be a user account or a global group account.

LOCALGROUP_MEMBERS_INFO_1

The LOCALGROUP_MEMBERS_INFO_1 structure contains the security identifier (SID) and account information associated with
the member of a local group.

LOCALGROUP_MEMBERS_INFO_2

The LOCALGROUP_MEMBERS_INFO_2 structure contains the security identifier (SID) and account information associated with
a local group member.

LOCALGROUP_MEMBERS_INFO_3

The LOCALGROUP_MEMBERS_INFO_3 structure contains the account name and domain name associated with a local group
member.

LOCALGROUP_USERS_INFO_0

The LOCALGROUP_USERS_INFO_0 structure contains local group member information.

MSA_INFO_0

Specifies information about a managed service account.

NET_DISPLAY_GROUP

The NET_DISPLAY_GROUP structure contains information that an account manager can access to determine information
about group accounts.

NET_DISPLAY_MACHINE

The NET_DISPLAY_MACHINE structure contains information that an account manager can access to determine information
about computers and their attributes.
NET_DISPLAY_USER

The NET_DISPLAY_USER structure contains information that an account manager can access to determine information about
user accounts.

NET_VALIDATE_AUTHENTICATION_INPUT_ARG

A client application passes the NET_VALIDATE_AUTHENTICATION_INPUT_ARG structure to the NetValidatePasswordPolicy

function when the application requests an authentication validation.

NET_VALIDATE_OUTPUT_ARG

The NET_VALIDATE_OUTPUT_ARG structure contains information about persistent password-related data that has changed
since the user's last logon as well as the result of the function's password validation check.

NET_VALIDATE_PASSWORD_CHANGE_INPUT_ARG

A client application passes the NET_VALIDATE_PASSWORD_CHANGE_INPUT_ARG structure to the NetValidatePasswordPolicy

function when the application requests a password change validation.

NET_VALIDATE_PASSWORD_HASH

The NET_VALIDATE_PASSWORD_HASH structure contains a password hash.

NET_VALIDATE_PASSWORD_RESET_INPUT_ARG

A client application passes the NET_VALIDATE_PASSWORD_RESET_INPUT_ARG structure to the NetValidatePasswordPolicy

function when the application requests a password reset validation.

NET_VALIDATE_PERSISTED_FIELDS

The NET_VALIDATE_PERSISTED_FIELDS structure contains information about a user's password properties.

NETLOGON_INFO_1

Defines a level-1 control query response from a domain controller.

NETLOGON_INFO_2

Defines a level-2 control query response from a domain controller.

NETLOGON_INFO_3

Defines a level-3 control query response from a domain controller.

NETLOGON_INFO_4

Defines a level-4 control query response from a domain controller.

USER_INFO_0

The USER_INFO_0 structure contains a user account name.

USER_INFO_1

The USER_INFO_1 structure contains information about a user account, including account name, password data, privilege level,
and the path to the user's home directory.

USER_INFO_10

The USER_INFO_10 structure contains information about a user account, including the account name, comments associated
with the account, and the user's full name.

USER_INFO_1003

The USER_INFO_1003 structure contains a user password. This information level is valid only when you call the NetUserSetInfo
function.

USER_INFO_1005

The USER_INFO_1005 structure contains a privilege level to assign to a user network account. This information level is valid
only when you call the NetUserSetInfo function.

USER_INFO_1006

The USER_INFO_1006 structure contains the user's home directory path. This information level is valid only when you call the
NetUserSetInfo function.

USER_INFO_1007

The USER_INFO_1007 structure contains a comment associated with a user network account. This information level is valid
only when you call the NetUserSetInfo function.

USER_INFO_1008

The USER_INFO_1008 structure contains a set of bit flags defining several user network account parameters. This information
level is valid only when you call the NetUserSetInfo function.

USER_INFO_1009

The USER_INFO_1009 structure contains the path for a user's logon script file. This information level is valid only when you call
the NetUserSetInfo function.

USER_INFO_1010

The USER_INFO_1010 structure contains a set of bit flags defining the operator privileges assigned to a user network account.
This information level is valid only when you call the NetUserSetInfo function.

USER_INFO_1011

The USER_INFO_1011 structure contains the full name of a network user. This information level is valid only when you call the
NetUserSetInfo function.

USER_INFO_1012

The USER_INFO_1012 structure contains a user comment. This information level is valid only when you call the NetUserSetInfo
function.
USER_INFO_1013

The USER_INFO_1013 structure contains reserved information for network accounts. This information level is valid only when
you call the NetUserSetInfo function.

USER_INFO_1014

The USER_INFO_1014 structure contains the names of workstations from which the user can log on. This information level is
valid only when you call the NetUserSetInfo function.

USER_INFO_1017

The USER_INFO_1017 structure contains expiration information for network user accounts. This information level is valid only
when you call the NetUserSetInfo function.

USER_INFO_1018

The USER_INFO_1018 structure contains the maximum amount of disk space available to a network user account. This
information level is valid only when you call the NetUserSetInfo function.

USER_INFO_1020

The USER_INFO_1020 structure contains the times during which a user can log on to the network. This information level is
valid only when you call the NetUserSetInfo function.

USER_INFO_1023

The USER_INFO_1023 structure contains the name of the server to which network logon requests should be sent. This
information level is valid only when you call the NetUserSetInfo function.

USER_INFO_1024

The USER_INFO_1024 structure contains the country/region code for a network user's language of choice. This information
level is valid only when you call the NetUserSetInfo function.

USER_INFO_1025

The USER_INFO_1025 structure contains the code page for a network user's language of choice. This information level is valid
only when you call the NetUserSetInfo function.

USER_INFO_1051

The USER_INFO_1051 structure contains the relative ID (RID) associated with the user account. This information level is valid
only when you call the NetUserSetInfo function.

USER_INFO_1052

The USER_INFO_1052 structure contains the path to a network user's profile. This information level is valid only when you call
the NetUserSetInfo function.

USER_INFO_1053

The USER_INFO_1053 structure contains user information for network accounts. This information level is valid only when you
call the NetUserSetInfo function.
USER_INFO_11

The USER_INFO_11 structure contains information about a user account, including the account name, privilege level, the path
to the user's home directory, and other user-related network statistics.

USER_INFO_2

The USER_INFO_2 structure contains information about a user account, including the account name, password data, privilege
level, the path to the user's home directory, and other user-related network statistics.

USER_INFO_20

Contains information about a user account, including the account name, the user's full name, a comment associated with the
account, and the user's relative ID (RID).

USER_INFO_21

The USER_INFO_21 structure contains a one-way encrypted LAN Manager 2.x-compatible password.

USER_INFO_22

The USER_INFO_22 structure contains information about a user account, including the account name, privilege level, the path
to the user's home directory, a one-way encrypted LAN Manager 2.x-compatible password, and other user-related network
statistics.

USER_INFO_23

Contains information about a user account, including the account name, the user's full name, a comment associated with the
account, and the user's security identifier (SID).

USER_INFO_24

Contains user account information on an account which is connected to an Internet identity. This information includes the
Internet provider name for the user, the user's Internet name, and the user's security identifier (SID).

USER_INFO_3

The USER_INFO_3 structure contains information about a user account, including the account name, password data, privilege
level, the path to the user's home directory, relative identifiers (RIDs), and other user-related network statistics.

USER_INFO_4

The USER_INFO_4 structure contains information about a user account, including the account name, password data, privilege
level, the path to the user's home directory, security identifier (SID), and other user-related network statistics.

USER_MODALS_INFO_0

The USER_MODALS_INFO_0 structure contains global password information for users and global groups in the security
database, which is the security accounts manager (SAM) database or, in the case of domain controllers, the Active Directory.

USER_MODALS_INFO_1

The USER_MODALS_INFO_1 structure contains logon server and domain controller information.
 USER_MODALS_INFO_1001

The USER_MODALS_INFO_1001 structure contains the minimum length for passwords in the security database, which is the
security accounts manager (SAM) database or, in the case of domain controllers, the Active Directory.

USER_MODALS_INFO_1002

The USER_MODALS_INFO_1002 structure contains the maximum duration for passwords in the security database, which is the
security accounts manager (SAM) database or, in the case of domain controllers, the Active Directory.

USER_MODALS_INFO_1003

The USER_MODALS_INFO_1003 structure contains the minimum duration for passwords in the security database, which is the
security accounts manager (SAM) database or, in the case of domain controllers, the Active Directory.

USER_MODALS_INFO_1004

The USER_MODALS_INFO_1004 structure contains forced logoff information for users and global groups in the security
database, which is the security accounts manager (SAM) database or, in the case of domain controllers, the Active Directory.

USER_MODALS_INFO_1005

The USER_MODALS_INFO_1005 structure contains password history information for users and global groups in the security
database, which is the security accounts manager (SAM) database or, in the case of domain controllers, the Active Directory.

USER_MODALS_INFO_1006

The USER_MODALS_INFO_1006 structure contains logon server information.

USER_MODALS_INFO_1007

The USER_MODALS_INFO_1007 structure contains domain controller information.

USER_MODALS_INFO_2

The USER_MODALS_INFO_2 structure contains the Security Account Manager (SAM) domain name and identifier.

USER_MODALS_INFO_3

The USER_MODALS_INFO_3 structure contains lockout information for users and global groups in the security database,
which is the security accounts manager (SAM) database or, in the case of domain controllers, the Active Directory.

Enumerations

MSA_INFO_LEVEL

Indicates the level of a managed service account.

MSA_INFO_STATE

Indicates the state of a managed service account.

 MSA_INFO_0 structure (lmaccess.h)
7/2/2022 • 2 minutes to read • Edit Online

Specifies information about a managed service account. This structure is used by the NetQueryServiceAccount
function.

Syntax
typedef struct _MSA_INFO_0 {
MSA_INFO_STATE State;
} MSA_INFO_0, *PMSA_INFO_0, *LPMSA_INFO_0;

Members
State

A value of the MSA_INFO_STATE enumeration that indicates the state of the service account specified in the call
to the NetQueryServiceAccount function.

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Header lmaccess.h
 MSA_INFO_LEVEL enumeration (lmaccess.h)
7/2/2022 • 2 minutes to read • Edit Online

The MSA_INFO_LEVEL enumeration indicates the level of a managed service account.

Syntax
typedef enum _MSA_INFO_LEVEL {
MsaInfoLevel0 = 0,
MsaInfoLevelMax
} MSA_INFO_LEVEL, *PMSA_INFO_LEVEL;

Constants

MsaInfoLevel0
Value: 0
The default level.

MsaInfoLevelMax
The maximum level.

Requirements

Minimum suppor ted client Windows 8 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2012 [desktop apps only]

Header lmaccess.h
 MSA_INFO_STATE enumeration (lmaccess.h)
7/2/2022 • 2 minutes to read • Edit Online

Indicates the state of a managed service account. A managed service account can be either a group managed
service account (gMSA) or a standalone managed service account (sMSA). A sMSA is limited to being deployed
to a single computer.

Syntax
typedef enum _MSA_INFO_STATE {
MsaInfoNotExist = 1,
MsaInfoNotService,
MsaInfoCannotInstall,
MsaInfoCanInstall,
MsaInfoInstalled
} MSA_INFO_STATE, *PMSA_INFO_STATE;

Constants

MsaInfoNotExist
Value: 1
The account does not exist.

MsaInfoNotService
The account exists, but it is not a group managed service account (gMSA) or a Windows Server 2008 R2 or Windows 7
managed service account.

Windows Ser ver 2008 R2 and Windows 7: The account is not a managed service account.

MsaInfoCannotInstall
If the managed service account is a gMSA, the credentials cannot be fetched from the active directory or the Kerberos
encryption types did not match.

Windows Ser ver 2008 R2 and Windows 7: The managed service account cannot be installed.

MsaInfoCanInstall
The sMSA can be installed. This constant will never be returned for a gMSA.

Windows Ser ver 2008 R2 and Windows 7: The managed service account can be installed.

MsaInfoInstalled
The gMSA managed service account is installed.

Windows Ser ver 2008 R2 and Windows 7: The managed service account is installed.

Remarks
Service accounts can be group managed and are called group managed service accounts (gMSA). Standalone
managed service accounts (sMSA) are limited to being deployed to a single computer.
Windows Ser ver 2008 R2 and Windows 7: The managed service account (MSA) is limited to being
deployed to a single computer.

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Header lmaccess.h

See also
MSA_INFO_0
 NetAddServiceAccount function (lmaccess.h)
7/2/2022 • 2 minutes to read • Edit Online

The NetAddSer viceAccount function creates a standalone managed service account (sMSA) or retrieves the
credentials for a group managed service account (gMSA) and stores the account information on the local
computer.
This function has no associated import library. You must use the LoadLibrary and GetProcAddress functions to
dynamically link to Logoncli.dll.
Windows Ser ver 2008 R2: Installing a managed service account by using the PowerShell command line
interface cmdlet to call this function fails with error code 0xC0000225 when the value of the AccountName
parameter does not match the corresponding Security Accounts Manager (SAM) name of the account.

Syntax
NTSTATUS NetAddServiceAccount(
[in, optional] LPWSTR ServerName,
[in] LPWSTR AccountName,
[in] LPWSTR Password,
[in] DWORD Flags
);

Parameters
[in, optional] ServerName

The value of this parameter must be NULL .

[in] AccountName

The name of the account to be created.

[in] Password

This parameter is reserved. Do not use it.

[in] Flags

This parameter can be the following value.

VA L UE M EA N IN G

No standalone managed service account is created. If a

SERVICE_ACCOUNT_FL AG_LINK_TO_HOST_ONLY service account with the specified name exists, it is linked to
0x00000001 the local computer. This flag is ignored if the account name is
an existing gMSA.

Return value
If the function succeeds, it returns STATUS_SUCCESS .
If the function fails, it returns an error code.
Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Target Platform Windows

Header lmaccess.h

DLL Netapi32.dll

See also
NetEnumerateServiceAccounts
NetIsServiceAccount
NetRemoveServiceAccount
 NetEnumerateServiceAccounts function (lmaccess.h)
7/2/2022 • 2 minutes to read • Edit Online

The NetEnumerateSer viceAccounts function enumerates the standalone managed service accounts (sMSA)
on the specified server. This function only enumerates sMSAs and not group managed service accounts (gMSA).
This function has no associated import library. You must use the LoadLibrary and GetProcAddress functions to
dynamically link to Logoncli.dll.

Syntax
NTSTATUS NetEnumerateServiceAccounts(
[in, optional] LPWSTR ServerName,
[in] DWORD Flags,
[out] DWORD *AccountsCount,
[out] PZPWSTR *Accounts
);

Parameters
[in, optional] ServerName

The value of this parameter must be NULL .

[in] Flags

This parameter is reserved. Do not use it.

[out] AccountsCount

The number of elements in the Accounts array.

[out] Accounts

A pointer to an array of the names of the service accounts on the specified server.
When you have finished using the names, free the array by calling the NetApiBufferFree function.

Return value
If the function succeeds, it returns STATUS_SUCCESS .
If the function fails, it returns an error code.

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Target Platform Windows

 Header lmaccess.h

DLL Netapi32.dll

See also
NetAddServiceAccount
NetIsServiceAccount
NetRemoveServiceAccount
 NetIsServiceAccount function (lmaccess.h)
7/2/2022 • 2 minutes to read • Edit Online

The NetIsSer viceAccount function tests whether the specified standalone managed service account (sMSA) or
group managed service account (gMSA) exists in the Netlogon store on the specified server.
This function has no associated import library. You must use the LoadLibrary and GetProcAddress functions to
dynamically link to Logoncli.dll.

Syntax
NTSTATUS NetIsServiceAccount(
[in, optional] LPWSTR ServerName,
[in] LPWSTR AccountName,
[out] BOOL *IsService
);

Parameters
[in, optional] ServerName

The value of this parameter must be NULL .

[in] AccountName

The name of the account to be tested.

[out] IsService

TRUE if the specified service account exists on the specified server; otherwise, FALSE .

Return value
If the function succeeds, it returns STATUS_SUCCESS .
If the function fails, it returns an error code.

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Target Platform Windows

Header lmaccess.h

DLL Netapi32.dll
See also
NetAddServiceAccount
NetEnumerateServiceAccounts
NetRemoveServiceAccount
 NetQueryServiceAccount function (lmaccess.h)
7/2/2022 • 2 minutes to read • Edit Online

Gets information about the specified managed service account.

Syntax
NTSTATUS NetQueryServiceAccount(
[in, optional] LPWSTR ServerName,
[in] LPWSTR AccountName,
[in] DWORD InfoLevel,
[out] PBYTE *Buffer
);

Parameters
[in, optional] ServerName

The value of this parameter must be NULL .

[in] AccountName

The name of the account to be created.

[in] InfoLevel

Specifies the format of the data returned in the Buffer parameter. This can be the following value.

VA L UE M EA N IN G

The Buffer parameter contains an MSA_INFO_0 structure.

0

[out] Buffer

Information about the specified service account.

When you have finished using this buffer, free it by calling the NetApiBufferFree function.

Return value
If the function succeeds, it returns STATUS_SUCCESS .
If the function fails, it returns an error code.

Requirements

Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]
 Target Platform Windows

Header lmaccess.h

DLL Netapi32.dll

See also
NetAddServiceAccount
NetEnumerateServiceAccounts
NetIsServiceAccount
NetRemoveServiceAccount
 NetRemoveServiceAccount function (lmaccess.h)
7/2/2022 • 2 minutes to read • Edit Online

The NetRemoveSer viceAccount function deletes the specified service account from the Active Directory
database if the account is a standalone managed service account (sMSA). For group managed service accounts
(gMSAs), this function does not delete the account from the Active Directory database. The secret stored in the
Local Security Authority (LSA) is deleted for both sMSAs and gMSAs, and the state is stored in the Netlogon
registry store.
This function has no associated import library. You must use the LoadLibrary and GetProcAddress functions to
dynamically link to Logoncli.dll.

Syntax
NTSTATUS NetRemoveServiceAccount(
[in, optional] LPWSTR ServerName,
[in] LPWSTR AccountName,
[in] DWORD Flags
);

Parameters
[in, optional] ServerName

The value of this parameter must be NULL .

[in] AccountName

The name of the account to be deleted.

[in] Flags

This parameter can have the following value.

VA L UE M EA N IN G

For sMSAs, the service account object is unlinked from the

SERVICE_ACCOUNT_FL AG_UNLINK_FROM_HOST_ON local computer and the secret stored in the LSA is deleted.
LY The service account object is not deleted from the Active
0x00000001 Directory database. This flag has no meaning for gMSAs.

Return value
If the function succeeds, it returns STATUS_SUCCESS .
If the function fails, it returns an error code.

Requirements
 Minimum suppor ted client Windows 7 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]

Target Platform Windows

Header lmaccess.h

DLL Netapi32.dll

See also
NetAddServiceAccount
NetEnumerateServiceAccounts
NetIsServiceAccount
 lsalookup.h header
7/2/2022 • 2 minutes to read • Edit Online

This header is used by Security and Identity. For more information, see:
Security and Identity
lsalookup.h contains the following programming interfaces:

Structures

LSA_OBJECT_ATTRIBUTES

The LSA_OBJECT_ATTRIBUTES structure is used with the LsaOpenPolicy function to specify the attributes of the connection to
the Policy object.

LSA_REFERENCED_DOMAIN_LIST

The LSA_REFERENCED_DOMAIN_LIST structure contains information about the domains referenced in a lookup operation.

LSA_STRING

Used by Local Security Authority (LSA) functions to specify an ANSI string.

LSA_TRANSLATED_NAME

Used with the LsaLookupSids function to return information about the account identified by a SID.

LSA_TRANSLATED_SID2

Contains SIDs that are retrieved based on account names.

LSA_TRUST_INFORMATION

Identifies a domain.

LSA_UNICODE_STRING

The LSA_UNICODE_STRING structure is used by various Local Security Authority (LSA) functions to specify a Unicode string.

POLICY_ACCOUNT_DOMAIN_INFO

Used to set and query the name and SID of the system's account domain.

POLICY_DNS_DOMAIN_INFO

The POLICY_DNS_DOMAIN_INFO structure is used to set and query Domain Name System (DNS) information about the
primary domain associated with a Policy object.
 LSA_OBJECT_ATTRIBUTES structure (lsalookup.h)
7/2/2022 • 2 minutes to read • Edit Online

The LSA_OBJECT_ATTRIBUTES structure is used with the LsaOpenPolicy function to specify the attributes of
the connection to the Policy object.
When you call LsaOpenPolicy, initialize the members of this structure to NULL or zero because the function
does not use the information.

Syntax
typedef struct _LSA_OBJECT_ATTRIBUTES {
ULONG Length;
HANDLE RootDirectory;
PLSA_UNICODE_STRING ObjectName;
ULONG Attributes;
PVOID SecurityDescriptor;
PVOID SecurityQualityOfService;
} LSA_OBJECT_ATTRIBUTES, *PLSA_OBJECT_ATTRIBUTES;

Members
Length

Specifies the size, in bytes, of the LSA_OBJECT_ATTRIBUTES structure.

RootDirectory

Should be NULL .
ObjectName

Should be NULL .
Attributes

Should be zero.
SecurityDescriptor

Should be NULL .
SecurityQualityOfService

Should be NULL .

Remarks
The LSA_OBJECT_ATTRIBUTES structure is defined in the LsaLookup.h header file.
Windows Ser ver 2008 with SP2 and earlier, Windows Vista with SP2 and earlier, Windows
Ser ver 2003, Windows XP/2000: The LSA_OBJECT_ATTRIBUTES structure is defined in the NTSecAPI.h
header file.
Requirements

Minimum suppor ted client Windows XP [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Header lsalookup.h

See also
LsaOpenPolicy
SECURITY_QUALITY_OF_SERVICE
 LSA_REFERENCED_DOMAIN_LIST structure
(lsalookup.h)
7/2/2022 • 2 minutes to read • Edit Online

The LSA_REFERENCED_DOMAIN_LIST structure contains information about the domains referenced in a

lookup operation.

Syntax
typedef struct _LSA_REFERENCED_DOMAIN_LIST {
ULONG Entries;
PLSA_TRUST_INFORMATION Domains;
} LSA_REFERENCED_DOMAIN_LIST, *PLSA_REFERENCED_DOMAIN_LIST;

Members
Entries

Specifies the number of entries in the Domains array.

Domains

Pointer to an array of LSA_TRUST_INFORMATION structures that identify the referenced domains.

Requirements

Minimum suppor ted client Windows XP [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Header lsalookup.h

See also
LSA_TRUST_INFORMATION
LsaLookupNames
LsaLookupSids
 LSA_STRING structure (lsalookup.h)
7/2/2022 • 2 minutes to read • Edit Online

The LSA_STRING structure is used by Local Security Authority (LSA) functions to specify an ANSI string.

Syntax
typedef struct _LSA_STRING {
USHORT Length;
USHORT MaximumLength;
PCHAR Buffer;
} LSA_STRING, *PLSA_STRING;

Members
Length

Specifies the length, in bytes, of the string in Buffer . This value does not include the terminating null character, if
any.
When the Length structure member is zero and the MaximumLength structure member is 1, the Buffer
structure member must not be an empty string or contain solely a null character.
Windows 7, Windows Ser ver 2008, Windows Vista, Windows Ser ver 2003 and Windows XP: When
the Length structure member is zero and the MaximumLength structure member is 1, the Buffer structure
member can be an empty string or contain solely a null character. This behavior changed beginning with
Windows Server 2008 R2 and Windows 7 with SP1.
MaximumLength

Specifies the total size, in bytes, of Buffer . Up to MaximumLength bytes may be written into the buffer without
trampling memory.
When the Length structure member is zero and the MaximumLength structure member is 1, the Buffer
structure member must not be an empty string or contain solely a null character.
Windows 7, Windows Ser ver 2008, Windows Vista, Windows Ser ver 2003 and Windows XP: When
the Length structure member is zero and the MaximumLength structure member is 1, the Buffer structure
member can be an empty string or contain solely a null character. This behavior changed beginning with
Windows Server 2008 R2 and Windows 7 with SP1.
Buffer

Pointer to an array of characters. Note that strings returned by the LSA may not be null-terminated.
When the Length structure member is zero and the MaximumLength structure member is 1, the Buffer
structure member must not be an empty string or contain solely a null character.
Windows 7, Windows Ser ver 2008, Windows Vista, Windows Ser ver 2003 and Windows XP: When
the Length structure member is zero and the MaximumLength structure member is 1, the Buffer structure
member can be an empty string or contain solely a null character. This behavior changed beginning with
Windows Server 2008 R2 and Windows 7 with SP1.
Requirements

Minimum suppor ted client Windows XP [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Header lsalookup.h
 LSA_TRANSLATED_NAME structure (lsalookup.h)
7/2/2022 • 2 minutes to read • Edit Online

The LSA_TRANSL ATED_NAME structure is used with the LsaLookupSids function to return information about
the account identified by a SID.

Syntax
typedef struct _LSA_TRANSLATED_NAME {
SID_NAME_USE Use;
LSA_UNICODE_STRING Name;
LONG DomainIndex;
} LSA_TRANSLATED_NAME, *PLSA_TRANSLATED_NAME;

Members
Use

A value from the SID_NAME_USE enumeration that identifies the type of SID.
If Use has one of the following values, one or both of the Name or DomainIndex members of
LSA_TRANSL ATED_NAME is not valid. These members are valid if Use has any other value.

VA L UE M EA N IN G

The DomainIndex member is valid, but the Name member

SidTypeDomain is not valid and must be ignored.

Both DomainIndex and Name are not valid and must be

SidTypeInvalid ignored.

Both DomainIndex and Name are not valid and must be

SidTypeUnknown ignored.

The Name member is valid, but the DomainIndex member

SidTypeWellKnownGroup is not valid and must be ignored.

Name

An LSA_UNICODE_STRING structure that contains the isolated name of the translated SID. An isolated name is a
user, group, or local group account name without the domain name (for example, user_name, rather than
Acctg\user_name).
DomainIndex

Specifies the zero-based index of an entry in the LSA_REFERENCED_DOMAIN_LIST structure returned by the
LsaLookupSids function. The entry contains the name and SID of the domain in which the account was found.
If there is no corresponding domain for an account, this member contains a negative value.

Requirements
 Minimum suppor ted client Windows XP [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Header lsalookup.h

See also
LSA_REFERENCED_DOMAIN_LIST
LSA_UNICODE_STRING
LsaLookupSids
SID_NAME_USE
 LSA_TRANSLATED_SID2 structure (lsalookup.h)
7/2/2022 • 2 minutes to read • Edit Online

The LSA_TRANSL ATED_SID2 structure contains SIDs that are retrieved based on account names. This
structure is used by the LsaLookupNames2 function.

Syntax
typedef struct _LSA_TRANSLATED_SID2 {
SID_NAME_USE Use;
PSID Sid;
LONG DomainIndex;
ULONG Flags;
} LSA_TRANSLATED_SID2, *PLSA_TRANSLATED_SID2;

Members
Use

An SID_NAME_USE enumeration value that identifies the use of the SID. If this value is SidTypeUnknown or
SidTypeInvalid, the rest of the information in the structure is not valid and should be ignored.
Sid

The complete SID of the account.

DomainIndex

The index of an entry in a related LSA_REFERENCED_DOMAIN_LIST data structure which describes the domain
that owns the account. If there is no corresponding reference domain for an entry, then DomainIndex will
contain a negative value.
Flags

Not used.

Requirements

Minimum suppor ted client Windows XP [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Header lsalookup.h
 LSA_TRUST_INFORMATION structure (lsalookup.h)
7/2/2022 • 2 minutes to read • Edit Online

The LSA_TRUST_INFORMATION structure identifies a domain.

Syntax
typedef struct _LSA_TRUST_INFORMATION {
LSA_UNICODE_STRING Name;
PSID Sid;
} LSA_TRUST_INFORMATION, *PLSA_TRUST_INFORMATION;

Members
Name

An LSA_UNICODE_STRING structure that contains the name of the domain.

Sid

Pointer to the SID of the domain.

Remarks
TRUSTED_DOMAIN_INFORMATION_BASIC is an alias for this structure.
The TRUSTED_DOMAIN_INFORMATION_BASIC structure identifies a domain. This structure is used by the
LsaQueryTrustedDomainInfo function when its InformationClass parameter is set to
TrustedDomainInformationBasic .

Requirements

Minimum suppor ted client Windows XP [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Header lsalookup.h

See also
LSA_REFERENCED_DOMAIN_LIST
LSA_UNICODE_STRING
 LSA_UNICODE_STRING structure (lsalookup.h)
7/2/2022 • 2 minutes to read • Edit Online

The LSA_UNICODE_STRING structure is used by various Local Security Authority (LSA) functions to specify a
Unicode string.

Syntax
typedef struct _LSA_UNICODE_STRING {
USHORT Length;
USHORT MaximumLength;
PWSTR Buffer;
} LSA_UNICODE_STRING, *PLSA_UNICODE_STRING;

Members
Length

Specifies the length, in bytes, of the string pointed to by the Buffer member, not including the terminating null
character, if any.
MaximumLength

Specifies the total size, in bytes, of the memory allocated for Buffer . Up to MaximumLength bytes can be
written into the buffer without trampling memory.
Buffer

Pointer to a wide character string. Note that the strings returned by the various LSA functions might not be null-
terminated.

Requirements

Minimum suppor ted client Windows XP [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Header lsalookup.h
 POLICY_ACCOUNT_DOMAIN_INFO structure
(lsalookup.h)
7/2/2022 • 2 minutes to read • Edit Online

The POLICY_ACCOUNT_DOMAIN_INFO structure is used to set and query the name and SID of the system's
account domain. The LsaQueryInformationPolicy and LsaSetInformationPolicy functions use this structure when
their InformationClass parameters are set to PolicyAccountDomainInformation .

Syntax
typedef struct _POLICY_ACCOUNT_DOMAIN_INFO {
LSA_UNICODE_STRING DomainName;
PSID DomainSid;
} POLICY_ACCOUNT_DOMAIN_INFO, *PPOLICY_ACCOUNT_DOMAIN_INFO;

Members
DomainName

An LSA_UNICODE_STRING structure that specifies the name of the account domain.

DomainSid

Pointer to the SID of the account domain.

Requirements

Minimum suppor ted client Windows XP [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Header lsalookup.h

See also
LSA_UNICODE_STRING
LsaQueryInformationPolicy
LsaSetInformationPolicy
POLICY_INFORMATION_CLASS
 POLICY_DNS_DOMAIN_INFO structure
(lsalookup.h)
7/2/2022 • 2 minutes to read • Edit Online

The POLICY_DNS_DOMAIN_INFO structure is used to set and query Domain Name System (DNS)
information about the primary domain associated with a Policy object. The LsaQueryInformationPolicy and
LsaSetInformationPolicy functions use this structure when their InformationClass parameters are set to
PolicyDnsDomainInformation .

Syntax
typedef struct _POLICY_DNS_DOMAIN_INFO {
LSA_UNICODE_STRING Name;
LSA_UNICODE_STRING DnsDomainName;
LSA_UNICODE_STRING DnsForestName;
GUID DomainGuid;
PSID Sid;
} POLICY_DNS_DOMAIN_INFO, *PPOLICY_DNS_DOMAIN_INFO;

Members
Name

An LSA_UNICODE_STRING structure that specifies the name of the primary domain. This is the same as the
primary domain name in the POLICY_PRIMARY_DOMAIN_INFO structure.
DnsDomainName

An LSA_UNICODE_STRING structure that specifies the DNS name of the primary domain.
DnsForestName

An LSA_UNICODE_STRING structure that specifies the DNS forest name of the primary domain. This is the DNS
name of the domain at the root of the enterprise.
DomainGuid

A GUID structure that contains the GUID of the primary domain.

Sid

Pointer to the SID of the primary domain. This is the same as the primary domain SID in the
POLICY_PRIMARY_DOMAIN_INFO structure.

Remarks
The POLICY_DNS_DOMAIN_INFO structure is an extended version of the POLICY_PRIMARY_DOMAIN_INFO
structure. Setting POLICY_DNS_DOMAIN_INFO information will overwrite the corresponding values in the
POLICY_PRIMARY_DOMAIN_INFO (name and SID), and vice versa.
If the computer associated with the Policy object is not a member of a domain, all structure members except
Name are NULL or zero.
Requirements

Minimum suppor ted client Windows XP [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Header lsalookup.h

See also
LSA_UNICODE_STRING
LsaQueryInformationPolicy
LsaSetInformationPolicy
POLICY_INFORMATION_CLASS
POLICY_PRIMARY_DOMAIN_INFO
 mmcobj.h header
7/2/2022 • 2 minutes to read • Edit Online

This header is used by multiple technologies. For more information, see:

Legacy Windows Environment Features
Microsoft Management Console 2.0
Security and Identity
mmcobj.h contains the following programming interfaces:

Interfaces

ISnapinProperties

The ISnapinProperties interface enables a snap-in to initialize the snap-in's properties and receive notification when a property
is added, changed, or deleted.

ISnapinPropertiesCallback

The ISnapinPropertiesCallback interface adds property names for the snap-in. This interface is implemented by MMC for the
snap-in.

Structures

MMC_SNAPIN_PROPERTY

The MMC_SNAPIN_PROPERTY structure is introduced in MMC 2.0.

Enumerations

_ColumnSortOrder

Used by IResultsViewer::SortOrderProperty to indicate or set how a query is to be sorted.

_DocumentMode

The DocumentMode enumeration is used by the Document.Mode property and specifies how the document is opened. This
enumeration applies to the MMC 2.0 Automation Object Model.

_ExportListOptions

The ExportListOptions enumeration is used by the View.ExportList method and specifies options when writing list view
contents to a file.
_ListViewMode

The ListViewMode enumeration is used by the View.ListViewMode property to define the list view.

_ViewOptions

The ViewOptions enumeration is used by the Views.Add method and specifies the visibility of the view, scope tree, and
toolbars, as well as the persistence state of the view.

MMC_PROPERTY_ACTION

The MMC_PROPERTY_ACTION enumeration specifies the operations that can occur to a property contained in an
MMC_SNAPIN_PROPERTY structure.
 mscat.h header
7/2/2022 • 2 minutes to read • Edit Online

This header is used by Security and Identity. For more information, see:
Security and Identity
mscat.h contains the following programming interfaces:

Functions

CryptCATAdminAcquireContext

Acquires a handle to a catalog administrator context.

CryptCATAdminAcquireContext2

Acquires a handle to a catalog administrator context for a given hash algorithm and hash policy.

CryptCATAdminAddCatalog

Adds a catalog to the catalog database.

CryptCATAdminCalcHashFromFileHandle

Calculates the hash for a file.

CryptCATAdminCalcHashFromFileHandle2

Calculates the hash for a file by using the specified algorithm.

CryptCATAdminEnumCatalogFromHash

Enumerates the catalogs that contain a specified hash.

CryptCATAdminReleaseCatalogContext

Releases a handle to a catalog context previously returned by the CryptCATAdminAddCatalog function.

CryptCATAdminReleaseContext

Releases the handle previously assigned by the CryptCATAdminAcquireContext function.

CryptCATAdminRemoveCatalog

Deletes a catalog file and removes that catalog's entry from the Windows catalog database.

CryptCATAdminResolveCatalogPath

Retrieves the fully qualified path of the specified catalog.

CryptCATCatalogInfoFromContext

Retrieves catalog information from a specified catalog context.

CryptCATCDFClose

Closes a catalog definition file (CDF) and frees the memory for the corresponding CRYPTCATCDF structure.

CryptCATCDFEnumCatAttributes

Enumerates catalog-level attributes within the CatalogHeader section of a catalog definition file (CDF).

CryptCATCDFOpen

Opens an existing catalog definition file (CDF) for reading and initializes a CRYPTCATCDF structure.

CryptCATClose

Closes a catalog handle opened previously by the CryptCATOpen function.

CryptCATEnumerateAttr

Enumerates the attributes associated with a member of a catalog. This function has no associated import library.

CryptCATEnumerateCatAttr

Enumerates the attributes associated with a catalog. This function has no associated import library.

CryptCATEnumerateMember

Enumerates the members of a catalog.

CryptCATGetAttrInfo

Retrieves information about an attribute of a member of a catalog.

CryptCATGetMemberInfo

Retrieves member information from the catalog's PKCS

CryptCATHandleFromStore

Retrieves a catalog handle from memory.

CryptCATOpen

Opens a catalog and returns a context handle to the open catalog.

CryptCATPersistStore

Saves the information in the specified catalog store to an unsigned catalog file.

CryptCATPutAttrInfo

Allocates memory for an attribute and adds it to a catalog member.

 CryptCATPutCatAttrInfo

Allocates memory for a catalog file attribute and adds it to the catalog.

CryptCATPutMemberInfo

Allocates memory for a catalog member and adds it to the catalog.

CryptCATStoreFromHandle

Retrieves a CRYPTCATSTORE structure from a catalog handle.

IsCatalogFile

Retrieves a Boolean value that indicates whether the specified file is a catalog file.

Callback functions

PFN_CDF_PARSE_ERROR_CALLBACK

Called for Catalog Definition Function errors while parsing a catalog definition file (CDF).

Structures

CATALOG_INFO

The CATALOG_INFO structure contains the name of a catalog file. This structure is used by the
CryptCATCatalogInfoFromContext function.

CRYPTCATATTRIBUTE

The CRYPTCATATTRIBUTE structure defines a catalog attribute. This structure is used by the CryptCATEnumerateAttr and
CryptCATEnumerateCatAttr functions.

CRYPTCATCDF

Contains information used to create a signed catalog file (.cat) from a catalog definition file (CDF).

CRYPTCATMEMBER

The CRYPTCATMEMBER structure provides information about a catalog member. This structure is used by the
CryptCATGetMemberInfo and CryptCATEnumerateAttr functions.

CRYPTCATSTORE

Represents a catalog file.

 CATALOG_INFO structure (mscat.h)
7/2/2022 • 2 minutes to read • Edit Online

[The CATALOG_INFO structure is available for use in the operating systems specified in the Requirements
section. It may be altered or unavailable in subsequent versions.]
The CATALOG_INFO structure contains the name of a catalog file. This structure is used by the
CryptCATCatalogInfoFromContext function.

Syntax
typedef struct CATALOG_INFO_ {
DWORD cbStruct;
WCHAR wszCatalogFile[MAX_PATH];
} CATALOG_INFO;

Members
cbStruct

Specifies the size, in bytes, of this structure.

wszCatalogFile

Name of the catalog file.

Requirements

Minimum suppor ted client Windows XP [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Header mscat.h

See also
CryptCATCatalogInfoFromContext
 CryptCATAdminAcquireContext function (mscat.h)
7/2/2022 • 2 minutes to read • Edit Online

[The Cr yptCATAdminAcquireContext function is available for use in the operating systems specified in the
Requirements section. It may be altered or unavailable in subsequent versions.]
The Cr yptCATAdminAcquireContext function acquires a handle to a catalog administrator context. This
handle can be used by subsequent calls to the CryptCATAdminAddCatalog,
CryptCATAdminEnumCatalogFromHash, and CryptCATAdminRemoveCatalog functions. This function has no
associated import library. You must use the LoadLibrary and GetProcAddress functions to dynamically link to
Wintrust.dll.

Syntax
BOOL CryptCATAdminAcquireContext(
[out] HCATADMIN *phCatAdmin,
[in] const GUID *pgSubsystem,
[in] DWORD dwFlags
);

Parameters
[out] phCatAdmin

A pointer to the catalog administrator context handle that is assigned by this function. When you have finished
using the handle, close it by calling the CryptCATAdminReleaseContext function.
[in] pgSubsystem

A pointer to the GUID that identifies the subsystem. DRIVER_ACTION_VERIFY represents the subsystem for
operating system components and third party drivers. This is the subsystem used by most implementations.
[in] dwFlags

Not used; set to zero.

Return value
The return value is TRUE if the function succeeds; FALSE if the function fails.
For extended error information, call the GetLastError function. For a complete list of error codes provided by the
operating system, see System Error Codes.

Requirements

Minimum suppor ted client Windows XP [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]
 Target Platform Windows

Header mscat.h

Librar y Wintrust.lib

DLL Wintrust.dll

See also
CryptCATAdminAddCatalog
CryptCATAdminReleaseContext
CryptCATAdminRemoveCatalog
 CryptCATAdminAcquireContext2 function (mscat.h)
7/2/2022 • 2 minutes to read • Edit Online

The Cr yptCATAdminAcquireContext2 function acquires a handle to a catalog administrator context for a

given hash algorithm and hash policy.
You can use this handle in subsequent calls to the following functions:
CryptCATAdminAddCatalog
CryptCATAdminEnumCatalogFromHash
CryptCATAdminRemoveCatalog
This function has no associated import library. You must use the LoadLibrary and GetProcAddress functions to
dynamically link to Wintrust.dll.

Syntax
BOOL CryptCATAdminAcquireContext2(
[out] HCATADMIN *phCatAdmin,
[in, optional] const GUID *pgSubsystem,
[in, optional] PCWSTR pwszHashAlgorithm,
[in, optional] PCCERT_STRONG_SIGN_PARA pStrongHashPolicy,
DWORD dwFlags
);

Parameters
[out] phCatAdmin

A pointer to the catalog administrator context handle that is assigned by this function. When you have finished
using the handle, close it by calling the CryptCATAdminReleaseContext function.
[in, optional] pgSubsystem

A pointer to the GUID that identifies the subsystem. DRIVER_ACTION_VERIFY represents the subsystem for
operating system components and third party drivers. This is the subsystem used by most implementations.
[in, optional] pwszHashAlgorithm

Optional null-terminated Unicode string that specifies the name of the hash algorithm to use when calculating
and verifying hashes. This value can be NULL . If it is NULL , the default hashing algorithm may be chosen,
depending on the value you set for the pStrongHashPolicy parameter. The default algorithm in Windows 8 is
SHA1. The default may change in future Windows versions. For more information, see Remarks.
[in, optional] pStrongHashPolicy

Pointer to a CERT_STRONG_SIGN_PARA structure that contains the parameters used to check for strong
signatures. The function chooses the lowest common hashing algorithm that satisfies the specified policy and
the algorithm specified by the pwszHashAlgorithm parameter or the system default algorithm (if no algorithm is
specified).
dwFlags

Reserved. This value must be zero.

Return value
If the function succeeds, the return value is nonzero (TRUE ).
If the function fails, the return value is zero (FALSE ). For extended error information, call GetLastError.
The following table lists the error codes most commonly returned by the GetLastError function.

RET URN C O DE DESC RIP T IO N

The phCatAdmin parameter cannot be NULL .

ERROR_INVALID_PARAMETER
The dwFlags parameter must be zero (0).

There was insufficient memory to create a new catalog

ERROR_NOT_ENOUGH_MEMORY administrator object.

The hash algorithm specified by the pwszHashAlgorithm

NTE_BAD_ALGID parameter cannot be found.

Remarks
This function enables you to choose, or chooses for you, the hash algorithm to be used in functions that require
the catalog administrator context. Although you can set the name of the hashing algorithm, we recommend that
you let the function determine the algorithm. Doing so protects your application from hard coding algorithms
that may become untrusted in the future.

Requirements

Minimum suppor ted client Windows 8 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2012 [desktop apps only]

Target Platform Windows

Header mscat.h

Librar y Wintrust.lib

DLL Wintrust.dll

See also
CryptCATAdminAddCatalog
CryptCATAdminReleaseContext
CryptCATAdminRemoveCatalog
 CryptCATAdminAddCatalog function (mscat.h)
7/2/2022 • 2 minutes to read • Edit Online

[The Cr yptCATAdminAddCatalog function is available for use in the operating systems specified in the
Requirements section. It may be altered or unavailable in subsequent versions.]
The Cr yptCATAdminAddCatalog function adds a catalog to the catalog database. The catalog database is an
index that associates file hashes with the catalogs that contain them. It is used to speed the identification of the
catalogs when verifying the file signature. This function is the only supported way to programmatically add
catalogs to the Windows catalog database. The function has no associated import library. You must use the
LoadLibrary and GetProcAddress functions to dynamically link to Wintrust.dll.

Syntax
HCATINFO CryptCATAdminAddCatalog(
[in] HCATADMIN hCatAdmin,
[in] PWSTR pwszCatalogFile,
[in] PWSTR pwszSelectBaseName,
[in] DWORD dwFlags
);

Parameters
[in] hCatAdmin

Handle previously assigned by the CryptCATAdminAcquireContext function.

[in] pwszCatalogFile

A pointer to a null -terminated string for the fully qualified path of the catalog to be added.
[in] pwszSelectBaseName

A pointer to a null -terminated string for the name of the catalog when it is stored. If the parameter is NULL ,
then a unique name will be generated for the catalog.
[in] dwFlags

If the CRYPTCAT_ADDCATALOG_HARDLINK (0x00000001) flag is specified, the catalog specified in the call will
be hard-linked to rather than copied. Hard-linking instead of copying a catalog reduces the amount of disk
space required by Windows.

Return value
If the function succeeds, the return value is a handle to the catalog information context. If the function fails, the
return value is NULL . After you have finished using the returned handle, free it by calling the
CryptCATAdminReleaseCatalogContext function.
For extended error information, call the GetLastError function. For a complete list of error codes provided by the
operating system, see System Error Codes.

Requirements
 Minimum suppor ted client Windows XP [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header mscat.h

Librar y Wintrust.lib

DLL Wintrust.dll

See also
CryptCATAdminAcquireContext
CryptCATAdminReleaseCatalogContext
 CryptCATAdminCalcHashFromFileHandle function
(mscat.h)
7/2/2022 • 2 minutes to read • Edit Online

[The Cr yptCATAdminCalcHashFromFileHandle function is available for use in the operating systems

specified in the Requirements section. It may be altered or unavailable in subsequent versions.]
The Cr yptCATAdminCalcHashFromFileHandle function calculates the hash for a file. This function has no
associated import library. You must use the LoadLibrary and GetProcAddress functions to dynamically link to
Wintrust.dll.

Syntax
BOOL CryptCATAdminCalcHashFromFileHandle(
[in] HANDLE hFile,
[in, out] DWORD *pcbHash,
[in] BYTE *pbHash,
[in] DWORD dwFlags
);

Parameters
[in] hFile

A handle to the file whose hash is being calculated. This parameter cannot be NULL and must be a valid file
handle.
[in, out] pcbHash

A pointer to a DWORD variable that contains the number of bytes in pbHash. Upon input, set pcbHash to the
number of bytes allocated for pbHash. Upon return, pcbHash contains the number of returned bytes in pbHash.
If pbHash is passed as NULL , then pcbHash contains the number of bytes to allocate for pbHash.
[in] pbHash

A pointer to a BYTE buffer that receives the hash. If this parameter is passed in as NULL , then pcbHash contains
the number of bytes to allocate for pbHash, and a subsequent call can be made to retrieve the hash.
[in] dwFlags

This parameter is reserved for future use and must be set to zero.

Return value
The return value is TRUE if the function succeeds; FALSE if the function fails. If FALSE is returned, call the
GetLastError function to determine the reason for failure. If not enough memory has been allocated for
pbHash, the Cr yptCATAdminCalcHashFromFileHandle function will set the last error to
ERROR_INSUFFICIENT_BUFFER.

Requirements
Minimum suppor ted client Windows XP [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header mscat.h

Librar y Wintrust.lib

DLL Wintrust.dll
 CryptCATAdminCalcHashFromFileHandle2 function
(mscat.h)
7/2/2022 • 2 minutes to read • Edit Online

The Cr yptCATAdminCalcHashFromFileHandle2 function calculates the hash for a file by using the specified
algorithm.
This function has no associated import library. You must use the LoadLibrary and GetProcAddress functions to
dynamically link to Wintrust.dll.

Syntax
BOOL CryptCATAdminCalcHashFromFileHandle2(
[in] HCATADMIN hCatAdmin,
[in] HANDLE hFile,
[in, out] DWORD *pcbHash,
BYTE *pbHash,
DWORD dwFlags
);

Parameters
[in] hCatAdmin

Handle of an open catalog administrator context. For more information, see CryptCATAdminAcquireContext2.
[in] hFile

A handle to the file whose hash is being calculated. This parameter cannot be NULL and must be a valid file
handle.
[in, out] pcbHash

Pointer to a DWORD variable that contains the number of bytes in the pbHash parameter. Upon input, set
pcbHash to the number of bytes allocated for pbHash. Upon return, pcbHash contains the number of returned
bytes in pbHash. If pbHash is set to NULL , then pcbHash contains the number of bytes to allocate for pbHash.
pbHash

Pointer to a BYTE buffer that receives the hash. If you set this parameter to NULL , then pcbHash will contain the
number of bytes to allocate for pbHash, and a subsequent call can be made to retrieve the hash.
dwFlags

Reserved. This value must be zero.

Return value
If the function succeeds, the return value is nonzero (TRUE ).
If the function fails, the return value is zero (FALSE ). For extended error information, call GetLastError.
The following table lists the error codes most commonly returned by the GetLastError function.
 RET URN C O DE DESC RIP T IO N

The hFile parameter must not be NULL .

ERROR_INVALID_PARAMETER
The hFile parameter must be a valid file handle.
The pcbHash parameter must not be NULL .
The dwFlags parameter must be zero (0).

The buffer pointed to by the pbHash parameter was not

ERROR_INSUFFICIENT_BUFFER NULL but was not large enough to be written. The correct
size of the required buffer is contained in the value pointed
to by the pcbHash parameter.

The hash algorithm specified by the pwszHashAlgorithm

NTE_BAD_ALGID parameter cannot be found.

Remarks
The amount of time this function takes to execute depends on the length of the file being hashed, the algorithm
being used, and the file location. For example, it takes several seconds to calculate the hash of a local file that is
very large (a few hundred megabytes).

Requirements

Minimum suppor ted client Windows 8 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2012 [desktop apps only]

Target Platform Windows

Header mscat.h

Librar y Wintrust.lib

DLL Wintrust.dll

See also
CryptCATAdminCalcHashFromFileHandle
CryptCATAdminCalcHashFromFileHandle2
 CryptCATAdminEnumCatalogFromHash function
(mscat.h)
7/2/2022 • 2 minutes to read • Edit Online

[The Cr yptCATAdminEnumCatalogFromHash function is available for use in the operating systems specified
in the Requirements section. It may be altered or unavailable in subsequent versions.]
The Cr yptCATAdminEnumCatalogFromHash function enumerates the catalogs that contain a specified hash.
The hash is typically returned from the CryptCATAdminCalcHashFromFileHandle function. This function has no
associated import library. You must use the LoadLibrary and GetProcAddress functions to dynamically link to
Wintrust.dll. After the final call to this function, call CryptCATAdminReleaseCatalogContext to release allocated
memory.

Syntax
HCATINFO CryptCATAdminEnumCatalogFromHash(
[in] HCATADMIN hCatAdmin,
[in] BYTE *pbHash,
[in] DWORD cbHash,
[in] DWORD dwFlags,
[in] HCATINFO *phPrevCatInfo
);

Parameters
[in] hCatAdmin

A handle to a catalog administrator context previously assigned by the CryptCATAdminAcquireContext function.

[in] pbHash

A pointer to the buffer that contains the hash retrieved by calling CryptCATAdminCalcHashFromFileHandle.
[in] cbHash

Number of bytes in the buffer allocated for pbHash.

[in] dwFlags

This parameter is reserved for future use and must be set to zero.
[in] phPrevCatInfo

A pointer to the handle to the previous catalog context or NULL , if an enumeration is re-queried. If NULL is
passed in for this parameter, then the caller gets information only for the first catalog that contains the hash; an
enumeration is not made. If phPrevCatInfo contains NULL , then an enumeration of the catalogs that contain the
hash is started, and subsequent calls to Cr yptCATAdminEnumCatalogFromHash must set phPrevCatInfo to
the return value from the previous call.

Return value
The return value is a handle to the catalog context or NULL , if there are no more catalogs to enumerate or
retrieve.
For extended error information, call the GetLastError function. For a complete list of error codes provided by the
operating system, see System Error Codes.

Requirements

Minimum suppor ted client Windows XP [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header mscat.h

Librar y Wintrust.lib

DLL Wintrust.dll
 CryptCATAdminReleaseCatalogContext function
(mscat.h)
7/2/2022 • 2 minutes to read • Edit Online

[The Cr yptCATAdminReleaseCatalogContext function is available for use in the operating systems specified
in the Requirements section. It may be altered or unavailable in subsequent versions.]
The Cr yptCATAdminReleaseCatalogContext function releases a handle to a catalog context previously
returned by the CryptCATAdminAddCatalog function. This function has no associated import library. You must
use the LoadLibrary and GetProcAddress functions to dynamically link to Wintrust.dll.

Syntax
BOOL CryptCATAdminReleaseCatalogContext(
[in] HCATADMIN hCatAdmin,
[in] HCATINFO hCatInfo,
[in] DWORD dwFlags
);

Parameters
[in] hCatAdmin

Handle previously assigned by the CryptCATAdminAcquireContext function.

[in] hCatInfo

Handle previously assigned by the CryptCATAdminAddCatalog function or the

CryptCATAdminEnumCatalogFromHash function.
[in] dwFlags

This parameter is reserved for future use and must be set to zero.

Return value
The return value is TRUE if the function succeeds; FALSE if the function fails.

Requirements

Minimum suppor ted client Windows XP [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header mscat.h
 Librar y Wintrust.lib

DLL Wintrust.dll

See also
CryptCATAdminAddCatalog
 CryptCATAdminReleaseContext function (mscat.h)
7/2/2022 • 2 minutes to read • Edit Online

[The Cr yptCATAdminReleaseContext function is available for use in the operating systems specified in the
Requirements section. It may be altered or unavailable in subsequent versions.]
The Cr yptCATAdminReleaseContext function releases the handle previously assigned by the
CryptCATAdminAcquireContext function. This function has no associated import library. You must use the
LoadLibrary and GetProcAddress functions to dynamically link to Wintrust.dll.

Syntax
BOOL CryptCATAdminReleaseContext(
[in] HCATADMIN hCatAdmin,
[in] DWORD dwFlags
);

Parameters
[in] hCatAdmin

Catalog administrator context handle previously assigned by a call to the CryptCATAdminAcquireContext

function.
[in] dwFlags

Not used; set to zero.

Return value
The return value is TRUE if the function succeeds; FALSE if the function fails.

Requirements

Minimum suppor ted client Windows XP [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header mscat.h

Librar y Wintrust.lib

DLL Wintrust.dll

See also
CryptCATAdminAcquireContext
 CryptCATAdminRemoveCatalog function (mscat.h)
7/2/2022 • 2 minutes to read • Edit Online

[The Cr yptCATAdminRemoveCatalog function is available for use in the operating systems specified in the
Requirements section. It may be altered or unavailable in subsequent versions.]
The Cr yptCATAdminRemoveCatalog function deletes a catalog file and removes that catalog's entry from the
Windows catalog database. This function is the only supported way to remove catalogs from the database while
ensuring the integrity of the database. The function has no associated import library. You must use the
LoadLibrary and GetProcAddress functions to dynamically link to Wintrust.dll.

Syntax
BOOL CryptCATAdminRemoveCatalog(
[in] HCATADMIN hCatAdmin,
[in] LPCWSTR pwszCatalogFile,
[in] DWORD dwFlags
);

Parameters
[in] hCatAdmin

Handle previously assigned by the CryptCATAdminAcquireContext function.

[in] pwszCatalogFile

A pointer to a null-terminated string for the name of the catalog to remove. This string must contain only the
name, without any path information.
[in] dwFlags

This parameter is reserved for future use and must be set to zero.

Return value
The return value is TRUE if the function succeeds; FALSE if the function fails.
For extended error information, call the GetLastError function. For a complete list of error codes provided by the
operating system, see System Error Codes.

Requirements

Minimum suppor ted client Windows XP [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

 Header mscat.h

Librar y Wintrust.lib

DLL Wintrust.dll

See also
CryptCATAdminAddCatalog
 CryptCATAdminResolveCatalogPath function
(mscat.h)
7/2/2022 • 2 minutes to read • Edit Online

[The Cr yptCATAdminResolveCatalogPath function is available for use in the operating systems specified in
the Requirements section. It may be altered or unavailable in subsequent versions.]
The Cr yptCATAdminResolveCatalogPath function retrieves the fully qualified path of the specified catalog.

Note This function has no associated import library. You must use the LoadLibrary and GetProcAddress functions to
dynamically link to Wintrust.dll.

Syntax
BOOL CryptCATAdminResolveCatalogPath(
[in] HCATADMIN hCatAdmin,
[in] WCHAR *pwszCatalogFile,
[in, out] CATALOG_INFO *psCatInfo,
[in] DWORD dwFlags
);

Parameters
[in] hCatAdmin

A handle that was previously assigned by the CryptCATAdminAcquireContext function.

[in] pwszCatalogFile

The name of the catalog file for which to retrieve the fully qualified path.
[in, out] psCatInfo

A pointer to the CATALOG_INFO structure. This value cannot be NULL . Upon return from this function, the
wszCatalogFile member of the CATALOG_INFO structure contains the catalog file name.
[in] dwFlags

This parameter is reserved and must be set to zero.

Return value
Returns nonzero if successful or zero otherwise.
For extended error information, call the GetLastError function. For a complete list of error codes provided by the
operating system, see System Error Codes.

Requirements
Minimum suppor ted client Windows XP [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header mscat.h

DLL Wintrust.dll
 CRYPTCATATTRIBUTE structure (mscat.h)
7/2/2022 • 2 minutes to read • Edit Online

[The CRYPTCATATTRIBUTE structure is available for use in the operating systems specified in the
Requirements section. It may be altered or unavailable in subsequent versions.]
The CRYPTCATATTRIBUTE structure defines a catalog attribute. This structure is used by the
CryptCATEnumerateAttr and CryptCATEnumerateCatAttr functions.

Syntax
typedef struct CRYPTCATATTRIBUTE_ {
DWORD cbStruct;
LPWSTR pwszReferenceTag;
DWORD dwAttrTypeAndAction;
DWORD cbValue;
BYTE *pbValue;
DWORD dwReserved;
} CRYPTCATATTRIBUTE;

Members
cbStruct

The size, in bytes, of this structure.

pwszReferenceTag

A pointer to a null-terminated string that contains the reference tag value.

dwAttrTypeAndAction

Bitwise combination of the following flags.

VA L UE M EA N IN G

The attribute is authenticated.

CRYPTCAT_ATTR_AUTHENTICATED
0x10000000

The attribute is unauthenticated.

CRYPTCAT_ATTR_UNAUTHENTICATED
0x20000000

The attribute is an ASCII string.

CRYPTCAT_ATTR_NAMEASCII
0x00000001

The attribute is a cryptographic object identifier (OID).

CRYPTCAT_ATTR_NAMEOBJID
0x00000002
 The attribute contains simple ASCII characters that should
CRYPTCAT_ATTR_DATAASCII not be decoded.
0x00010000

The attribute is in base 64 format.

CRYPTCAT_ATTR_DATABASE64
0x00020000

The attribute replaces the value for an existing attribute.

CRYPTCAT_ATTR_DATAREPL ACE
0x00040000

cbValue

Number of bytes used by pbValue .

pbValue

A pointer to the encoded bytes.

dwReserved

Reserved; do not use.

Requirements

Minimum suppor ted client Windows XP [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Header mscat.h

See also
CryptCATEnumerateAttr
CryptCATEnumerateCatAttr
 CryptCATCatalogInfoFromContext function
(mscat.h)
7/2/2022 • 2 minutes to read • Edit Online

[The Cr yptCATCatalogInfoFromContext function is available for use in the operating systems specified in the
Requirements section. It may be altered or unavailable in subsequent versions.]
The Cr yptCATCatalogInfoFromContext function retrieves catalog information from a specified catalog
context. This function has no associated import library. You must use the LoadLibrary and GetProcAddress
functions to dynamically link to Wintrust.dll.

Syntax
BOOL CryptCATCatalogInfoFromContext(
[in] HCATINFO hCatInfo,
[in, out] CATALOG_INFO *psCatInfo,
[in] DWORD dwFlags
);

Parameters
[in] hCatInfo

A handle to the catalog context. This value cannot be NULL .

[in, out] psCatInfo

A pointer to the CATALOG_INFO structure. This value cannot be NULL . Upon return from this function, the
wszCatalogFile member of the CATALOG_INFO structure contains the catalog file name.
[in] dwFlags

Unused; set to zero.

Return value
The return value is TRUE if the function succeeds; FALSE if the function fails.
For extended error information, call the GetLastError function. For a complete list of error codes provided by the
operating system, see System Error Codes.

Requirements

Minimum suppor ted client Windows XP [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header mscat.h

Librar y Wintrust.lib

DLL Wintrust.dll
 CRYPTCATCDF structure (mscat.h)
7/2/2022 • 2 minutes to read • Edit Online

[The CRYPTCATCDF structure is available for use in the operating systems specified in the Requirements
section. It may be altered or unavailable in subsequent versions.]
The CRYPTCATCDF structure contains information used to create a signed catalog file (.cat) from a catalog
definition file (CDF). This structure is used by the MakeCat tool.

Syntax
typedef struct CRYPTCATCDF_ {
DWORD cbStruct;
HANDLE hFile;
DWORD dwCurFilePos;
DWORD dwLastMemberOffset;
BOOL fEOF;
LPWSTR pwszResultDir;
HANDLE hCATStore;
} CRYPTCATCDF;

Members
cbStruct

The size, in bytes, of this structure.

hFile

A handle to the catalog definition file (.cdf).

dwCurFilePos

A value that specifies the current position of the parser measured in bytes from the beginning of the catalog
definition file.
dwLastMemberOffset

A value that specifies the number of bytes to the position of the last member parsed in the catalog definition file.
fEOF

An integer that indicates whether the parser finished reading the file. TRUE indicates that the last read operation
returned zero bytes.
pwszResultDir

A pointer to a null-terminated string that contains the name of a directory where the catalog file (.cat) will be
written.
hCATStore

A handle to the catalog file (.cat).

Remarks
A parser can update dwCurFilePos and dwLastMemberOffset as it reads the CDF. A user-defined callback
function can use this information for recoverable parse errors in the CDF.

Requirements

Minimum suppor ted client Windows XP [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Header mscat.h

See also
CryptCATCDFClose
CryptCATCDFEnumAttributesWithCDFTag
CryptCATCDFEnumCatAttributes
CryptCATCDFEnumMembersByCDFTagEx
CryptCATCDFOpen
MakeCat
 CryptCATCDFClose function (mscat.h)
7/2/2022 • 2 minutes to read • Edit Online

[The Cr yptCATCDFClose function is available for use in the operating systems specified in the Requirements
section. It may be altered or unavailable in subsequent versions.]
The CRYPTCATCDF structure. Cr yptCATCDFClose is called by MakeCat.

Syntax
BOOL CryptCATCDFClose(
[in] CRYPTCATCDF *pCDF
);

Parameters
[in] pCDF

A pointer to a CRYPTCATCDF structure.

Return value
Upon success, this function returns TRUE . The Cr yptCATCDFClose function returns FALSE with an
ERROR_INVALID_PARAMETER error if it fails.

Remarks
Before closing the catalog output file specified in pCDF, the Cr yptCATCDFClose function signs and persists it
to the file system.

Requirements

Minimum suppor ted client Windows XP [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header mscat.h

DLL Wintrust.dll

See also
CRYPTCATCDF
MakeCat
 CryptCATCDFEnumCatAttributes function (mscat.h)
7/2/2022 • 2 minutes to read • Edit Online

[The Cr yptCATCDFEnumCatAttributes function is available for use in the operating systems specified in the
Requirements section. It may be altered or unavailable in subsequent versions.]
The Cr yptCATCDFEnumCatAttributes function enumerates catalog-level attributes within the
CatalogHeader section of a catalog definition file (CDF). Cr yptCATCDFEnumCatAttributes is called by
MakeCat.

Syntax
CRYPTCATATTRIBUTE * CryptCATCDFEnumCatAttributes(
[in] CRYPTCATCDF *pCDF,
[in] CRYPTCATATTRIBUTE *pPrevAttr,
[in] PFN_CDF_PARSE_ERROR_CALLBACK pfnParseError
);

Parameters
[in] pCDF

A pointer to a CRYPTCATCDF structure.

[in] pPrevAttr

A pointer to a CRYPTCATATTRIBUTE structure for a catalog attribute in the CDF pointed to by pCDF.
[in] pfnParseError

A pointer to a user-defined function to handle file parse errors.

Return value
Upon success, this function returns a pointer to a CRYPTCATATTRIBUTE structure. The
Cr yptCATCDFEnumCatAttributes function returns a NULL pointer if it fails.

Remarks
You typically call this function in a loop to enumerate all of the catalog header attributes in a CDF. Before
entering the loop, set pPrevAttr to NULL . The function returns a pointer to the first attribute. Set pPrevAttr to the
return value of the function for subsequent iterations of the loop.
Examples
The following example shows the correct sequence of assignments for the pPrevAttr parameter ( pAttr ).
 CRYPTCATCDF *pCDF;
CRYPTCATATTRIBUTE *pAttr;

pCDF = CryptCATCDFOpen(L"myCDF", NULL);

pAttr = NULL;

while (pAttr = CryptCATCDFEnumCatAttributes(pCDF, pAttr, NULL))

{
//do something with pAttr
}

CryptCATCDFClose(pCDF);

Requirements

Minimum suppor ted client Windows XP [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header mscat.h

DLL Wintrust.dll

See also
CRYPTCATATTRIBUTE
CRYPTCATCDF
MakeCat
 CryptCATCDFOpen function (mscat.h)
7/2/2022 • 2 minutes to read • Edit Online

[The Cr yptCATCDFOpen function is available for use in the operating systems specified in the Requirements
section. It may be altered or unavailable in subsequent versions.]
The CRYPTCATCDF structure. Cr yptCATCDFOpen is called by MakeCat.

Syntax
CRYPTCATCDF * CryptCATCDFOpen(
[in] LPWSTR pwszFilePath,
[in, optional] PFN_CDF_PARSE_ERROR_CALLBACK pfnParseError
);

Parameters
[in] pwszFilePath

A pointer to a null-terminated string that contains the path of the CDF file to open.
[in, optional] pfnParseError

A pointer to a user-defined function to handle file parse errors.

Return value
Upon success, this function returns a pointer to the newly created CRYPTCATCDF structure. The
Cr yptCATCDFOpen function returns a NULL pointer if it fails.

Remarks
The following default values are used by the Cr yptCATCDFOpen function for given conditions in the CDF
CatalogHeader section.

C ATA LO GH EA DER C O N DIT IO N DEFA ULT VA L UE

No Name value is specified. The file name in pwszFilePath is used for the catalog (.cat)
output file.

No PublicVersion value is specified. 0x00000001

No EncodingType value is specified. PKCS_7_ASN_ENCODING or X509_ASN_ENCODING

(0x00010001)

The following actions are performed by the Cr yptCATCDFOpen function for given error conditions.

ERRO R C O N DIT IO N A C T IO N P ERF O RM ED

 No CatalogHeader or Name tags are found in CDF. If specified by the caller, the Cr yptCATCDFOpen function
calls the function specified by pfnParseError and returns a
NULL pointer.

The Cr yptCATCDFOpen function calls the CryptCATOpen Calls the CryptCATCDFClose function and returns a NULL
function to get a handle to the catalog (.cat) output file, but pointer.
it gets an invalid or NULL handle.

A DDIT IO N A L O IDS F O R T H E C ATA LO G B RA N C H DEF IN IT IO N

szOID_CATALOG_LIST_MEMBER_V2 1.3.6.1.4.1.311.12.1.3

CAT_MEMBERINFO2_OBJID 1.3.6.1.4.1.311.12.2.3

Windows Ser ver 2008 R2, Windows 7, Windows Ser ver 2008, Windows Vista, Windows
Ser ver 2003 and Windows XP: The additional Catalog OIDs are not available.

Requirements

Minimum suppor ted client Windows XP [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header mscat.h

DLL Wintrust.dll

See also
CRYPTCATCDF
CryptCATCDFClose
CryptCATOpen
MakeCat
 CryptCATClose function (mscat.h)
7/2/2022 • 2 minutes to read • Edit Online

[The Cr yptCATClose function is available for use in the operating systems specified in the Requirements
section. It may be altered or unavailable in subsequent versions.]
The Cr yptCATClose function closes a catalog handle opened previously by the CryptCATOpen function. This
function has no associated import library. You must use the LoadLibrary and GetProcAddress functions to
dynamically link to Wintrust.dll.

Syntax
BOOL CryptCATClose(
[in] HANDLE hCatalog
);

Parameters
[in] hCatalog

Handle opened previously by a call to the CryptCATOpen function.

Return value
The return value is TRUE if the function succeeds; FALSE if the function fails.

Requirements

Minimum suppor ted client Windows XP [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header mscat.h

Librar y Wintrust.lib

DLL Wintrust.dll

See also
CryptCATOpen
 CryptCATEnumerateAttr function (mscat.h)
7/2/2022 • 2 minutes to read • Edit Online

[The Cr yptCATEnumerateAttr function is available for use in the operating systems specified in the
Requirements section. It may be altered or unavailable in subsequent versions.]
The Cr yptCATEnumerateAttr function enumerates the attributes associated with a member of a catalog. This
function has no associated import library. You must use the LoadLibrary and GetProcAddress functions to
dynamically link to Wintrust.dll.

Syntax
CRYPTCATATTRIBUTE * CryptCATEnumerateAttr(
[in] HANDLE hCatalog,
[in] CRYPTCATMEMBER *pCatMember,
[in] CRYPTCATATTRIBUTE *pPrevAttr
);

Parameters
[in] hCatalog

Handle for the catalog that contains the member identified by pCatMember. This value cannot be NULL .
[in] pCatMember

A pointer to the CRYPTCATMEMBER structure that identifies which member of the catalog is being enumerated.
[in] pPrevAttr

A pointer to the previously returned value from this function or pointer to NULL to start the enumeration.

Return value
The return value is a pointer to the CRYPTCATATTRIBUTE structure that contains the attribute information or
NULL , if no more attributes are in the enumeration or if an error is encountered. The returned pointer is passed
in as the pPrevAttr parameter for subsequent calls to this function.

Remarks
Do not free the returned pointer nor any of the members pointed to by the returned pointer.

Requirements

Minimum suppor ted client Windows XP [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

 Header mscat.h

Librar y Wintrust.lib

DLL Wintrust.dll

See also
CryptCATEnumerateCatAttr
 CryptCATEnumerateCatAttr function (mscat.h)
7/2/2022 • 2 minutes to read • Edit Online

[The Cr yptCATEnumerateCatAttr function is available for use in the operating systems specified in the
Requirements section. It may be altered or unavailable in subsequent versions.]
The Cr yptCATEnumerateCatAttr function enumerates the attributes associated with a catalog. This function
has no associated import library. You must use the LoadLibrary and GetProcAddress functions to dynamically
link to Wintrust.dll.

Syntax
CRYPTCATATTRIBUTE * CryptCATEnumerateCatAttr(
[in] HANDLE hCatalog,
[in] CRYPTCATATTRIBUTE *pPrevAttr
);

Parameters
[in] hCatalog

Handle for the catalog whose attributes are being enumerated. This value cannot be NULL .
[in] pPrevAttr

A pointer to the previously returned pointer to the CRYPTCATATTRIBUTE structure from this function or pointer
to NULL to start the enumeration.

Return value
The return value is a pointer to the CRYPTCATATTRIBUTE structure that contains the attribute information or
NULL , if no more attributes are in the enumeration or if an error is encountered. The returned pointer is passed
in as the pPrevAttr parameter for subsequent calls to this function.

Remarks
Do not free the returned pointer nor any of the members pointed to by the returned pointer.

Requirements

Minimum suppor ted client Windows XP [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header mscat.h
 Librar y Wintrust.lib

DLL Wintrust.dll

See also
CryptCATEnumerateAttr
 CryptCATEnumerateMember function (mscat.h)
7/2/2022 • 2 minutes to read • Edit Online

[The Cr yptCATEnumerateMember function is available for use in the operating systems specified in the
Requirements section. It may be altered or unavailable in subsequent versions.]
The Cr yptCATEnumerateMember function enumerates the members of a catalog.

Syntax
CRYPTCATMEMBER * CryptCATEnumerateMember(
[in] HANDLE hCatalog,
[in] CRYPTCATMEMBER *pPrevMember
);

Parameters
[in] hCatalog

The handle of the catalog that contains the members to enumerate. This value cannot be NULL .
[in] pPrevMember

A pointer to a CRYPTCATMEMBER structure that identifies which member of the catalog was last retrieved. If this
parameter is NULL , this function will retrieve the first member of the catalog.

Return value
This function returns a pointer to a CRYPTCATMEMBER structure that represents the next member of the catalog.
If there are no more members in the catalog to enumerate, this function returns NULL .

Remarks
Do not free the returned pointer nor any of the members pointed to by the returned pointer.
Examples
The following pseudocode example shows how to use this function to enumerate all of the members of a
catalog.

CRYPTCATMEMBER *pMember = NULL;

for(pMember = CryptCATEnumerateMember(hCatalog, pMember);

NULL != pMember;
pMember = CryptCATEnumerateMember(hCatalog, pMember))
{
// Use the catalog member.
}

Requirements
 Minimum suppor ted client Windows XP [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header mscat.h

Librar y Wintrust.lib

DLL Wintrust.dll

See also
CRYPTCATMEMBER
 CryptCATGetAttrInfo function (mscat.h)
7/2/2022 • 2 minutes to read • Edit Online

[The Cr yptCATGetAttrInfo function is available for use in the operating systems specified in the Requirements
section. It may be altered or unavailable in subsequent versions.]
The Cr yptCATGetAttrInfo function retrieves information about an attribute of a member of a catalog.

Syntax
CRYPTCATATTRIBUTE * CryptCATGetAttrInfo(
[in] HANDLE hCatalog,
[in] CRYPTCATMEMBER *pCatMember,
[in] LPWSTR pwszReferenceTag
);

Parameters
[in] hCatalog

The handle of the catalog that contains the member to retrieve the attribute information for. This handle is
obtained by calling the CryptCATOpen function. This parameter is required and cannot be NULL .
[in] pCatMember

A pointer to a CRYPTCATMEMBER structure that represents the member to retrieve the attribute information for.
This can be obtained by calling the CryptCATGetMemberInfo function. This parameter is required and cannot be
NULL .
[in] pwszReferenceTag

A pointer to a null-terminated Unicode string that contains the name of the attribute to retrieve the information
for. This parameter is required and cannot be NULL .

Return value
This function returns a pointer to a CRYPTCATATTRIBUTE structure that contains the attribute information. If the
function fails, it returns NULL .

Impor tant Do not free the returned pointer nor any of the members pointed to by the returned pointer.

If this function returns NULL , additional error information can be obtained by calling the GetLastError function.
GetLastError will return one of the following error codes.

RET URN C O DE DESC RIP T IO N

The member or the attribute could not be found.

CRYPT_E_NOT_FOUND
 One or more of the parameters are not valid.
ERROR_INVALID_PARAMETER

Requirements

Minimum suppor ted client Windows XP [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header mscat.h

Librar y Wintrust.lib

DLL Wintrust.dll

See also
CRYPTCATATTRIBUTE
CRYPTCATMEMBER
CryptCATGetMemberInfo
CryptCATOpen
 CryptCATGetMemberInfo function (mscat.h)
7/2/2022 • 2 minutes to read • Edit Online

[The Cr yptCATGetMemberInfo function is available for use in the operating systems specified in the
Requirements section. It may be altered or unavailable in subsequent versions.]
The Cr yptCATGetMemberInfo function retrieves member information from the catalog's PKCS #7. In addition
to retrieving the member information for a specified reference tag, this function opens a member context. This
function has no associated import library. You must use the LoadLibrary and GetProcAddress functions to
dynamically link to Wintrust.dll.

Syntax
CRYPTCATMEMBER * CryptCATGetMemberInfo(
[in] HANDLE hCatalog,
[in] LPWSTR pwszReferenceTag
);

Parameters
[in] hCatalog

A handle to the catalog. This parameter cannot be NULL .

[in] pwszReferenceTag

A pointer to a null -terminated string that represents the reference tag for the member information being
retrieved.

Return value
A pointer to the CRYPTCATMEMBER structure that contains the member information or NULL , if no information
can be found.

Remarks
Do not free the returned pointer nor any of the members pointed to by the returned pointer.

Requirements

Minimum suppor ted client Windows XP [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header mscat.h
Librar y Wintrust.lib

DLL Wintrust.dll
 CryptCATHandleFromStore function (mscat.h)
7/2/2022 • 2 minutes to read • Edit Online

[The Cr yptCATHandleFromStore function is available for use in the operating systems specified in the
Requirements section. It may be altered or unavailable in subsequent versions.]
The Cr yptCATHandleFromStore function retrieves a catalog handle from memory.

Syntax
HANDLE CryptCATHandleFromStore(
[in] CRYPTCATSTORE *pCatStore
);

Parameters
[in] pCatStore

A pointer to a CRYPTCATSTORE structure that contains the handle to retrieve.

Return value
A handle to the catalog.

Requirements

Minimum suppor ted client Windows XP [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header mscat.h

Librar y Wintrust.lib

DLL Wintrust.dll
 CRYPTCATMEMBER structure (mscat.h)
7/2/2022 • 2 minutes to read • Edit Online

[The CRYPTCATMEMBER structure is available for use in the operating systems specified in the Requirements
section. It may be altered or unavailable in subsequent versions.]
The CRYPTCATMEMBER structure provides information about a catalog member. This structure is used by the
CryptCATGetMemberInfo and CryptCATEnumerateAttr functions.

Syntax
typedef struct CRYPTCATMEMBER_ {
DWORD cbStruct;
LPWSTR pwszReferenceTag;
LPWSTR pwszFileName;
GUID gSubjectType;
DWORD fdwMemberFlags;
struct SIP_INDIRECT_DATA_ *pIndirectData;
DWORD dwCertVersion;
DWORD dwReserved;
HANDLE hReserved;
CRYPT_ATTR_BLOB sEncodedIndirectData;
CRYPT_ATTR_BLOB sEncodedMemberInfo;
} CRYPTCATMEMBER;

Members
cbStruct

The size, in bytes, of this structure.

pwszReferenceTag

A pointer to a null-terminated string that contains the reference tag value.

pwszFileName

A pointer to a null-terminated string that contains the file name.

gSubjectType

GUID that identifies the subject type.

fdwMemberFlags

Value that specifies the member flags.

pIndirectData

A pointer to a SIP_INDIRECT_DATA structure.

dwCertVersion

Value that specifies the certificate version.

dwReserved
Reserved; do not use.
hReserved

Reserved; do not use.

sEncodedIndirectData

A CRYPT_ATTR_BLOB structure that contains encoded indirect data.

sEncodedMemberInfo

A CRYPT_ATTR_BLOB structure that contains encoded member information.

Requirements

Minimum suppor ted client Windows XP [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Header mscat.h

See also
CryptCATEnumerateAttr
CryptCATGetMemberInfo
 CryptCATOpen function (mscat.h)
7/2/2022 • 2 minutes to read • Edit Online

[The Cr yptCATOpen function is available for use in the operating systems specified in the Requirements
section. It may be altered or unavailable in subsequent versions.]
The Cr yptCATOpen function opens a catalog and returns a context handle to the open catalog.

Note Some older versions of Wintrust.lib do not contain the export information for this function. In this case, you must use
the LoadLibrary and GetProcAddress functions to dynamically link to Wintrust.dll.

Syntax
HANDLE CryptCATOpen(
[in] LPWSTR pwszFileName,
[in] DWORD fdwOpenFlags,
[in] HCRYPTPROV hProv,
[in] DWORD dwPublicVersion,
[in] DWORD dwEncodingType
);

Parameters
[in] pwszFileName

A pointer to a null-terminated string for the catalog file name.

[in] fdwOpenFlags

Zero, to open an existing catalog file, or a bitwise combination of one or more of the following values.

VA L UE M EA N IN G

Opens the file, if it exists, or creates a new file, if needed.

CRYPTCAT_OPEN_ALWAYS

A new catalog file is created. If a previously created file exists,

CRYPTCAT_OPEN_CREATENEW it is overwritten.

An existing catalog file is opened.

CRYPTCAT_OPEN_EXISTING

An existing catalog file is opened. Exclude page hashes in

CRYPTCAT_OPEN_EXCLUDE_PAGE_HASHES SPC_INDIRECT_DATA.
 An existing catalog file is opened. Include page hashes in
CRYPTCAT_OPEN_INCLUDE_PAGE_HASHES SPC_INDIRECT_DATA. The above
CRYPTCAT_OPEN_EXCLUDE_PAGE_HASHES takes
precedence if also set.

An existing catalog file is opened. Verifies the signature, not

CRYPTCAT_OPEN_VERIFYSIGHASH the certificates.

An existing catalog file is opened. Does CryptMsgDecode

CRYPTCAT_OPEN_NO_CONTENT_HCRYPTMSG without content.

An existing catalog file is opened. Does

CRYPTCAT_OPEN_SORTED CertCreateContext(CERT_CREATE_CONTEXT_SORTED_FLAG).

[in] hProv

A handle to a cryptographic service provider (CSP).

[in] dwPublicVersion

Version of the file. This can be one of the following values.

VA L UE M EA N IN G

Version 1 file format.

CRYPTCAT_VERSION_1
0x100

Version 2 file format.

CRYPTCAT_VERSION_2
Windows 8 and Windows Ser ver 2012: Support
0x200
for this value begins.

[in] dwEncodingType

Encoding type used for the file. If this value is 0, then the encoding type is set to PKCS_7_ASN_ENCODING |
X509_ASN_ENCODING.

Return value
Upon success, this function returns a handle to the open catalog. When you have finished using the handle,
close it by calling the CryptCATClose function. The Cr yptCATOpen function returns INVALID_HANDLE_VALUE if
it fails.

Requirements

Minimum suppor ted client Windows XP [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header mscat.h
 Librar y Wintrust.lib

DLL Wintrust.dll

See also
CryptCATClose
 CryptCATPersistStore function (mscat.h)
7/2/2022 • 2 minutes to read • Edit Online

[The Cr yptCATPersistStore function is available for use in the operating systems specified in the
Requirements section. It may be altered or unavailable in subsequent versions.]
The Cr yptCATPersistStore function saves the information in the specified catalog store to an unsigned catalog
file.

Syntax
BOOL CryptCATPersistStore(
[in] HANDLE hCatalog
);

Parameters
[in] hCatalog

A handle to the catalog obtained from CryptCATHandleFromStore or CryptCATOpen function. Beginning with
Windows 8 you must use only Cr yptCATOpen to retrieve a handle.

Return value
The return value is TRUE if the function succeeds; otherwise, FALSE .
If this function returns FALSE , additional error information can be obtained by calling the GetLastError function.
GetLastError will return the following error code.

RET URN C O DE DESC RIP T IO N

One or more of the parameters are not valid.

ERROR_INVALID_PARAMETER

Beginning with Windows 8 and Windows Server 2012, you

ERROR_NOT_SUPPORTED must retrieve a handle by calling the CryptCATOpen function
with the dwPublicVersion parameter set to 0x100 or 0x200.
For more information, see Remarks.

Remarks
The CRYPTCATSTORE structure must be initialized before you call Cr yptCATPersistStore .
Beginning with Windows 8 and Windows Server 2012, the following changes apply to this function:
If CryptCATOpen was called with a dwPublicVersion parameter of 0x200, the catalog is written by using the
v2 format.
If CryptCATOpen was called with a dwPublicVersion parameter of 0x100, the catalog is written by using the
v1 format.
If CryptCATOpen was called with a dwPublicVersion parameter other than 0x200 or 0x100, the
Cr yptCATPersistStore function returns FALSE and the error code is set to ERROR_NOT_SUPPORTED .
Requirements

Minimum suppor ted client Windows XP [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header mscat.h

Librar y Wintrust.lib

DLL Wintrust.dll
 CryptCATPutAttrInfo function (mscat.h)
7/2/2022 • 2 minutes to read • Edit Online

[The Cr yptCATPutAttrInfo function is available for use in the operating systems specified in the Requirements
section. It may be altered or unavailable in subsequent versions.]
The Cr yptCATPutAttrInfo function allocates memory for an attribute and adds it to a catalog member.

Syntax
CRYPTCATATTRIBUTE * CryptCATPutAttrInfo(
[in] HANDLE hCatalog,
[in] CRYPTCATMEMBER *pCatMember,
[in] LPWSTR pwszReferenceTag,
[in] DWORD dwAttrTypeAndAction,
[in] DWORD cbData,
[in] BYTE *pbData
);

Parameters
[in] hCatalog

A handle to the catalog obtained from the CryptCATOpen or CryptCATHandleFromStore function.

[in] pCatMember

A pointer to a CRYPTCATMEMBER structure that contains the catalog member.

[in] pwszReferenceTag

A pointer to a null-terminated string that contains the name of the attribute.

[in] dwAttrTypeAndAction

A value that represents a bitwise combination of the following flags. The caller must at least specify
CRYPTCAT_ATTR_DATABASE64 or CRYPTCAT_ATTR_DATAASCII .

VA L UE M EA N IN G

The attribute is authenticated.

CRYPTCAT_ATTR_AUTHENTICATED
0x10000000

The attribute is unauthenticated.

CRYPTCAT_ATTR_UNAUTHENTICATED
0x20000000

The attribute is an ASCII string.

CRYPTCAT_ATTR_NAMEASCII
0x00000001
 The attribute is a cryptographic object identifier (OID).
CRYPTCAT_ATTR_NAMEOBJID
0x00000002

The attribute contains simple ASCII characters that should

CRYPTCAT_ATTR_DATAASCII not be decoded.
0x00010000

The attribute is in base 64 format.

CRYPTCAT_ATTR_DATABASE64
0x00020000

The attribute replaces the value for an existing attribute.

CRYPTCAT_ATTR_DATAREPL ACE
0x00040000

[in] cbData

A value that specifies the number of bytes in the pbData buffer.

[in] pbData

A pointer to a memory buffer that contains the attribute value.

Return value
Upon success, this function returns a pointer to a CRYPTCATATTRIBUTE structure that contains the assigned
attribute. The caller must not free this pointer or any of its members.
If this function returns NULL , additional error information can be obtained by calling the GetLastError function.
GetLastError will return one of the following error codes.

RET URN C O DE DESC RIP T IO N

One or more of the parameters are not valid.

ERROR_INVALID_PARAMETER

The operating system ran out of memory during the

ERROR_NOT_ENOUGH_MEMORY operation.

Requirements

Minimum suppor ted client Windows XP [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header mscat.h

Librar y Wintrust.lib
DLL Wintrust.dll
 CryptCATPutCatAttrInfo function (mscat.h)
7/2/2022 • 2 minutes to read • Edit Online

[The Cr yptCATPutCatAttrInfo function is available for use in the operating systems specified in the
Requirements section. It may be altered or unavailable in subsequent versions.]
The Cr yptCATPutCatAttrInfo function allocates memory for a catalog file attribute and adds it to the catalog.

Syntax
CRYPTCATATTRIBUTE * CryptCATPutCatAttrInfo(
[in] HANDLE hCatalog,
[in] LPWSTR pwszReferenceTag,
[in] DWORD dwAttrTypeAndAction,
[in] DWORD cbData,
[in] BYTE *pbData
);

Parameters
[in] hCatalog

A handle to the catalog obtained from the CryptCATOpen or CryptCATHandleFromStore functions.

[in] pwszReferenceTag

A pointer to a null-terminated string for the name of the attribute.

[in] dwAttrTypeAndAction

A value that represents a bitwise combination of the following flags. The caller must at least specify
CRYPTCAT_ATTR_DATAASCII or CRYPTCAT_ATTR_DATABASE64 .

VA L UE M EA N IN G

The attribute is authenticated.

CRYPTCAT_ATTR_AUTHENTICATED
0x10000000

The attribute is unauthenticated.

CRYPTCAT_ATTR_UNAUTHENTICATED
0x20000000

The attribute is an ASCII string.

CRYPTCAT_ATTR_NAMEASCII
0x00000001

The attribute is a cryptographic object identifier (OID).

CRYPTCAT_ATTR_NAMEOBJID
0x00000002
 The attribute contains simple ASCII characters that should
CRYPTCAT_ATTR_DATAASCII not be decoded.
0x00010000

The attribute is in base 64 format.

CRYPTCAT_ATTR_DATABASE64
0x00020000

The attribute replaces the value for an existing attribute.

CRYPTCAT_ATTR_DATAREPL ACE
0x00040000

[in] cbData

A value that specifies the number of bytes in the pbData buffer.

[in] pbData

A pointer to a memory buffer that contains the attribute value.

Return value
A pointer to a CRYPTCATATTRIBUTE structure that contains the catalog attribute. The caller must not free this
pointer or any of its members.
If this function returns NULL , additional error information can be obtained by calling the GetLastError function.
GetLastError will return one of the following error codes.

RET URN C O DE DESC RIP T IO N

One or more of the parameters are not valid.

ERROR_INVALID_PARAMETER

The operating system ran out of memory during the

ERROR_NOT_ENOUGH_MEMORY operation.

Requirements

Minimum suppor ted client Windows XP [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header mscat.h

Librar y Wintrust.lib

DLL Wintrust.dll
 CryptCATPutMemberInfo function (mscat.h)
7/2/2022 • 2 minutes to read • Edit Online

[The Cr yptCATPutMemberInfo function is available for use in the operating systems specified in the
Requirements section. It may be altered or unavailable in subsequent versions.]
The Cr yptCATPutMemberInfo function allocates memory for a catalog member and adds it to the catalog.

Syntax
CRYPTCATMEMBER * CryptCATPutMemberInfo(
[in] HANDLE hCatalog,
[in, optional] LPWSTR pwszFileName,
[in] LPWSTR pwszReferenceTag,
[in] GUID *pgSubjectType,
[in] DWORD dwCertVersion,
[in] DWORD cbSIPIndirectData,
[in] BYTE *pbSIPIndirectData
);

Parameters
[in] hCatalog

A handle to the catalog obtained from the CryptCATOpen or CryptCATHandleFromStore function.

[in, optional] pwszFileName

A pointer to a null-terminated string for the catalog file name.

[in] pwszReferenceTag

A pointer to a null-terminated string that contains the name of the member.

[in] pgSubjectType

A GUID for the subject type of the member.

[in] dwCertVersion

A value that specifies the certificate version.

[in] cbSIPIndirectData

A value that specifies the number of bytes in the pbSIPIndirectData buffer.

[in] pbSIPIndirectData

A pointer to a memory buffer for subject interface package (SIP)-indirect data.

Return value
A pointer to a CRYPTCATMEMBER structure that contains the assigned member. The caller must not free this
pointer or any of its members.
If this function returns NULL , additional error information can be obtained by calling the GetLastError function.
GetLastError will return one of the following error codes.

RET URN C O DE DESC RIP T IO N

One or more of the parameters are not valid.

ERROR_INVALID_PARAMETER

The operating system ran out of memory during the

ERROR_NOT_ENOUGH_MEMORY operation.

Requirements

Minimum suppor ted client Windows XP [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header mscat.h

Librar y Wintrust.lib

DLL Wintrust.dll
 CRYPTCATSTORE structure (mscat.h)
7/2/2022 • 2 minutes to read • Edit Online

[The CRYPTCATSTORE structure is available for use in the operating systems specified in the Requirements
section. It may be altered or unavailable in subsequent versions.]
The CRYPTCATSTORE structure represents a catalog file. The CryptCATStoreFromHandle function populates
this structure by using the handle returned by CryptCATOpen.

Syntax
typedef struct CRYPTCATSTORE_ {
DWORD cbStruct;
DWORD dwPublicVersion;
LPWSTR pwszP7File;
HCRYPTPROV hProv;
DWORD dwEncodingType;
DWORD fdwStoreFlags;
HANDLE hReserved;
HANDLE hAttrs;
HCRYPTMSG hCryptMsg;
HANDLE hSorted;
} CRYPTCATSTORE;

Members
cbStruct

The size, in bytes, of this structure.

dwPublicVersion

A value that specifies the "PublicVersion" of the catalog file.

pwszP7File

A pointer to a null-terminated string that contains the name of the catalog file. This member must be initialized
before a call to the CryptCATPersistStore function.
hProv

A handle to the cryptographic service provider (CSP).

dwEncodingType

A value that specifies the encoding type used for the file. Currently, only X509_ASN_ENCODING and
PKCS_7_ASN_ENCODING are being used; however, additional encoding types may be added in the future. For
either current encoding type, use: X509_ASN_ENCODING | PKCS_7_ASN_ENCODING.
fdwStoreFlags

A bitwise combination of the following values.

VA L UE M EA N IN G
 Exclude page hashes in SPC_INDIRECT_DATA.
CRYPTCAT_OPEN_EXCLUDE_PAGE_HASHES
0x00010000

For all flags with a value in the upper word, set or clear the
CRYPTCAT_OPEN_FL AGS_MASK flag.
0xffff0000

Include page hashes in SPC_INDIRECT_DATA. The

CRYPTCAT_OPEN_INCLUDE_PAGE_HASHES CRYPTCAT_OPEN_EXCLUDE_PAGE_HASHES flag takes
0x00020000 precedence if it is also set.

Open the file for decoding without detached content.

CRYPTCAT_OPEN_NO_CONTENT_HCRYPTMSG
0x20000000

Open the catalog with the entries sorted alphabetically by

CRYPTCAT_OPEN_SORTED subject.
0x40000000

Verify the signature hash but not the certificate chain.

CRYPTCAT_OPEN_VERIFYSIGHASH
0x10000000

hReserved

This member is reserved and must be NULL .

hAttrs

This member is reserved and must be NULL .

hCryptMsg

A handle to the decoded bytes. This member is only set if the file was opened with the
CRYPTCAT_OPEN_NO_CONTENT_HCRYPTMSG flag set.
hSorted

This member is reserved and must be NULL .

Requirements

Minimum suppor ted client Windows XP [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Header mscat.h
 CryptCATStoreFromHandle function (mscat.h)
7/2/2022 • 2 minutes to read • Edit Online

[The Cr yptCATStoreFromHandle function is available for use in the operating systems specified in the
Requirements section. It may be altered or unavailable in subsequent versions.]
The CRYPTCATSTORE structure from a catalog handle.

Syntax
CRYPTCATSTORE * CryptCATStoreFromHandle(
[in] HANDLE hCatalog
);

Parameters
[in] hCatalog

A handle to the catalog obtained from the CryptCATOpen or CryptCATHandleFromStore function.

Return value
A pointer to a CRYPTCATSTORE structure that contains the catalog store. The caller must not free this pointer or
any of its members.

Requirements

Minimum suppor ted client Windows XP [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header mscat.h

Librar y Wintrust.lib

DLL Wintrust.dll
 IsCatalogFile function (mscat.h)
7/2/2022 • 2 minutes to read • Edit Online

[The IsCatalogFile function is available for use in the operating systems specified in the Requirements section.
It may be altered or unavailable in subsequent versions.]
The IsCatalogFile function retrieves a Boolean value that indicates whether the specified file is a catalog file.

Note This function has no associated import library. You must use the LoadLibrary and GetProcAddress functions to
dynamically link to Wintrust.dll.

Syntax
BOOL IsCatalogFile(
[in, optional] HANDLE hFile,
[in, optional] WCHAR *pwszFileName
);

Parameters
[in, optional] hFile

A handle to the file to check. This parameter is optional, but it must contain a valid handle if the pwszFileName
parameter is NULL .
[in, optional] pwszFileName

A pointer to a null-terminated wide character string that contains the name of the file to check. This parameter is
optional, but it must contain a valid file name if the hFile parameter is NULL .

Return value
Returns nonzero if the specified file is a catalog file or zero otherwise.

Requirements

Minimum suppor ted client Windows XP [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header mscat.h

Librar y Wintrust.lib
DLL Wintrust.dll
 PFN_CDF_PARSE_ERROR_CALLBACK callback
function (mscat.h)
7/2/2022 • 2 minutes to read • Edit Online

The PFN_CDF_PARSE_ERROR_CALLBACK function is called for Catalog Definition Function errors while
parsing a catalog definition file (CDF).

Syntax
PFN_CDF_PARSE_ERROR_CALLBACK PfnCdfParseErrorCallback;

void PfnCdfParseErrorCallback(
[in] DWORD dwErrorArea,
[in] DWORD dwLocalError,
[in] WCHAR *pwszLine
)
{...}

Parameters
[in] dwErrorArea

A value that indicates in which area of the CDF the error occurred.
[in] dwLocalError

A value that indicates the type of error.

[in] pwszLine

A pointer to a null-terminated string that contains the CDF line in which the error occurred.

Return value
None

Remarks
The dwErrorArea parameter can have the following possible values.

VA L UE DESC RIP T IO N

CRYPTCAT_E_AREA_HEADER The header section of the CDF

CRYPTCAT_E_AREA_MEMBER A member file entry in the CatalogFiles section of the CDF

CRYPTCAT_E_AREA_ATTRIBUTE An attribute entry in the CDF

The dwLocalError parameter can have the following possible values.

 VA L UE DESC RIP T IO N

CRYPTCAT_E_CDF_UNSUPPORTED The function does not support the attribute.

CRYPTCAT_E_CDF_DUPLICATE The file member already exists.

CRYPTCAT_E_CDF_TAGNOTFOUND The CatalogHeader or Name tag is missing.

CRYPTCAT_E_CDF_MEMBER_FILE_PATH The member file name or path is missing.

CRYPTCAT_E_CDF_MEMBER_INDIRECTDATA The function failed to create a hash of the member subject.

CRYPTCAT_E_CDF_MEMBER_FILENOTFOUND The function failed to find the member file.

CRYPTCAT_E_CDF_BAD_GUID_CONV The function failed to convert the subject string to a GUID.

CRYPTCAT_E_CDF_ATTR_TOOFEWVALUES The attribute line is missing one or more elements of its

composition including type, object identifier (OID) or name,
or value.

CRYPTCAT_E_CDF_ATTR_TYPECOMBO The attribute contains an invalid OID, or the combination of

type, name or OID, and value is not valid.

Requirements

Minimum suppor ted client Windows XP [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header mscat.h

See also
Catalog Definition Function
 mssip.h header
7/2/2022 • 2 minutes to read • Edit Online

This header is used by Security and Identity. For more information, see:
Security and Identity
mssip.h contains the following programming interfaces:

Functions

CryptSIPAddProvider

The CryptSIPAddProvider function registers functions that are exported by a given DLL file that implements a Subject Interface
Package (SIP).

CryptSIPCreateIndirectData

Returns a SIP_INDIRECT_DATA structure that contains a hash of the supplied SIP_SUBJECTINFO structure, the digest
algorithm, and an encoding attribute. The hash can be used as an indirect reference to the data.

CryptSIPGetCaps

Retrieves the capabilities of a subject interface package (SIP).

CryptSIPGetSignedDataMsg

Retrieves an Authenticode signature from the file.

CryptSIPLoad

Loads the dynamic-link library (DLL) that implements a subject interface package (SIP) and assigns appropriate library export
functions to a SIP_DISPATCH_INFO structure.

CryptSIPPutSignedDataMsg

Stores an Authenticode signature in the target file.

CryptSIPRemoveProvider

Removes registry details of a Subject Interface Package (SIP) DLL file added by a previous call to the CryptSIPAddProvider
function.

CryptSIPRemoveSignedDataMsg

Removes a specified Authenticode signature.

CryptSIPRetrieveSubjectGuid

Retrieves a GUID based on the header information in a specified file.

 CryptSIPRetrieveSubjectGuidForCatalogFile

Retrieves the subject GUID associated with the specified file.

CryptSIPVerifyIndirectData

Validates the indirect hashed data against the supplied subject.

Callback functions

pCryptSIPGetCaps

Is implemented by a subject interface package (SIP) to report capabilities.

pfnIsFileSupported

Queries the subject interface packages (SIPs) listed in the registry to determine which SIP handles the file type.

pfnIsFileSupportedName

Queries the subject interface packages (SIPs) listed in the registry to determine which SIP handles the file type.

Structures

MS_ADDINFO_BLOB

Provides additional information for in-memory BLOB subject types.

MS_ADDINFO_CATALOGMEMBER

Provides additional information for catalog member subject types.

MS_ADDINFO_FLAT

Provides additional information about flat or end-to-end subject types.

SIP_ADD_NEWPROVIDER

Defines a subject interface package (SIP). This structure is used by the CryptSIPAddProvider function.

SIP_CAP_SET_V2

Defines the capabilities of a subject interface package (SIP).

SIP_CAP_SET_V3

Defines the capabilities of a subject interface package (SIP).

SIP_DISPATCH_INFO

Contains a set of function pointers assigned by the CryptSIPLoad function that your application uses to perform subject
interface package (SIP) operations.

SIP_INDIRECT_DATA

Contains the digest of the hashed subject information.

SIP_SUBJECTINFO

Specifies subject information data to the subject interface package (SIP) APIs.
 CryptSIPAddProvider function (mssip.h)
7/2/2022 • 2 minutes to read • Edit Online

The Cr yptSIPAddProvider function registers functions that are exported by a given DLL file that implements a
Subject Interface Package (SIP).

Syntax
BOOL CryptSIPAddProvider(
[in] SIP_ADD_NEWPROVIDER *psNewProv
);

Parameters
[in] psNewProv

A pointer to a SIP_ADD_NEWPROVIDER structure that specifies the DLL file and function names to register.

Return value
The return value is TRUE if the function succeeds; FALSE if the function fails. If the function fails, call the
GetLastError function to determine the reason for failure.

Remarks
Typically, you call this function as part of an in-process COM server registration. The Cr yptSIPAddProvider
function persists the appropriate Registry entries for the SIP provider functions.
When you have finished using the added SIP provider, remove it by calling the CryptSIPRemoveProvider
function.

Requirements

Minimum suppor ted client Windows XP [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header mssip.h

Librar y Crypt32.lib

DLL Crypt32.dll

See also
CryptSIPRemoveProvider
 CryptSIPCreateIndirectData function (mssip.h)
7/2/2022 • 2 minutes to read • Edit Online

The SIP_SUBJECTINFO structure, the digest algorithm, and an encoding attribute. The hash can be used as an
indirect reference to the data.

Syntax
BOOL CryptSIPCreateIndirectData(
[in] SIP_SUBJECTINFO *pSubjectInfo,
[in, out] DWORD *pcbIndirectData,
[out] SIP_INDIRECT_DATA *pIndirectData
);

Parameters
[in] pSubjectInfo

A pointer to a SIP_SUBJECTINFO structure that contains the subject to which the indirect data reference will
point.
[in, out] pcbIndirectData

A pointer to a SIP_INDIRECT_DATA structure.

[out] pIndirectData

A pointer to a SIP_INDIRECT_DATA structure to receive the catalog item.

Return value
The return value is TRUE if the function succeeds; otherwise, FALSE .
If this function returns FALSE , additional error information can be obtained by calling the GetLastError function.
GetLastError will return one of the following error codes.

RET URN C O DE DESC RIP T IO N

The file or data format is not correct for the specified subject
ERROR_BAD_FORMAT interface package (SIP) type.

One or more of the parameters are not valid.

ERROR_INVALID_PARAMETER

There was an error allocating memory.

ERROR_NOT_ENOUGH_MEMORY

The specified algorithm is not supported by the SIP.

NTE_BAD_ALGID
 The subject type is not recognized.
TRUST_E_SUBJECT_FORM_UNKNOWN

Remarks
If pcbIndirectData points to a DWORD and pIndirectData points to NULL , the size of the data will be returned in
pcbIndirectData.

Requirements

Minimum suppor ted client Windows XP [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header mssip.h

Librar y Crypt32.lib

DLL Crypt32.dll
 CryptSIPGetCaps function (mssip.h)
7/2/2022 • 2 minutes to read • Edit Online

The Cr yptSIPGetCaps function retrieves the capabilities of a subject interface package (SIP).

Syntax
BOOL CryptSIPGetCaps(
[in] SIP_SUBJECTINFO *pSubjInfo,
[in, out] SIP_CAP_SET *pCaps
);

Parameters
[in] pSubjInfo

Pointer to a SIP_SUBJECTINFO structure that specifies subject information data to the SIP APIs.
[in, out] pCaps

Pointer to a SIP_CAP_SET structure that defines the capabilities of an SIP.

Return value
None

Remarks
Unlike other SIP functions, SIP_DISPATCH_INFO structure. Instead, callers must map the object identifier (OID) to
the function entry point.

Requirements

Minimum suppor ted client Windows 8 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2012 [desktop apps only]

Target Platform Windows

Header mssip.h

Librar y Crypt32.lib

DLL Crypt32.dll

See also
SIP_CAP_SET
SIP_SUBJECTINFO
pCryptSIPGetCaps
 CryptSIPGetSignedDataMsg function (mssip.h)
7/2/2022 • 2 minutes to read • Edit Online

The Cr yptSIPGetSignedDataMsg function retrieves an Authenticode signature from the file.

Syntax
BOOL CryptSIPGetSignedDataMsg(
[in] SIP_SUBJECTINFO *pSubjectInfo,
[out] DWORD *pdwEncodingType,
[in] DWORD dwIndex,
[in, out] DWORD *pcbSignedDataMsg,
[out] BYTE *pbSignedDataMsg
);

Parameters
[in] pSubjectInfo

A pointer to a SIP_SUBJECTINFO structure that contains information about the message subject.
[out] pdwEncodingType

The encoding type of the Authenticode signature.

This parameter can be a combination of one or more of the following values.

VA L UE M EA N IN G

Specifies PKCS #7 message encoding.

PKCS_7_ASN_ENCODING
65536 (0x10000)

Specifies X.509 certificate encoding.

X509_ASN_ENCODING
1 (0x1)

[in] dwIndex

This parameter is reserved and should be set to zero.

[in, out] pcbSignedDataMsg

The length, in bytes, of the buffer pointed to by the pbSignedDataMsg parameter.

[out] pbSignedDataMsg

A pointer to a buffer to receive the returned Authenticode signature.

To determine the size of the buffer needed, set the pbSignedDataMsg parameter to NULL and call the
Cr yptSIPGetSignedDataMsg function. This function will place the required size of the buffer, in bytes, in the
value pointed to by pcbSignedDataMsg. For more information, see Retrieving Data of Unknown Length.
Return value
If the function succeeds, the function returns TRUE .
If the function fails, it returns FALSE . For extended error information, call GetLastError. Some possible error
codes follow.

RET URN C O DE DESC RIP T IO N

The signature specified by the index could not be found.

CRYPT_E_NO_MATCH

The specified data or file format of the subject interface

ERROR_BAD_FORMAT package (SIP) is not valid.

The [SIP_SUBJECTINFO](/windows/desktop/api/mssip/ns-
ERROR_INVALID_PARAMETER mssip-sip_subjectinfo) structure is a null pointer.

The size of the message buffer was insufficient to hold the

ERROR_INSUFFICIENT_BUFFER retrieved data, the pcbSignedDataMsg parameter has been
set to indicate the required buffer size.

The specified subject type is not valid.

TRUST_E_SUBJECT_FORM_UNKNOWN

Remarks
Subjects include, but are not limited to, portable executable images (.exe), cabinet (.cab) images, flat files, and
catalog files. Each subject type uses a different subset of its data for hash calculation and requires a different
procedure for storage and retrieval. Therefore, each subject type has a unique SIP specification.

Requirements

Minimum suppor ted client Windows XP [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header mssip.h

Librar y Crypt32.lib

DLL Crypt32.dll

See also
CryptSIPPutSignedDataMsg
CryptSIPRemoveSignedDataMsg
 CryptSIPLoad function (mssip.h)
7/2/2022 • 2 minutes to read • Edit Online

The SIP_DISPATCH_INFO structure. The exported functions must have been previously registered by calling the
CryptSIPAddProvider function.

Syntax
BOOL CryptSIPLoad(
[in] const GUID *pgSubject,
[in] DWORD dwFlags,
[in, out] SIP_DISPATCH_INFO *pSipDispatch
);

Parameters
[in] pgSubject

A pointer to a GUID returned by calling the CryptSIPRetrieveSubjectGuid function.

[in] dwFlags

This parameter is reserved and must be set to zero.

[in, out] pSipDispatch

A pointer to a SIP_DISPATCH_INFO structure that contains pointers to SIP provider functions that are specific to
the subject type. The caller must initialize this structure to binary zeros, and set the cbSize member to
sizeof(SIP_DISPATCH_INFO) before calling the Cr yptSIPLoad function.

Return value
If the function succeeds, the function returns TRUE .
If the function fails, it returns FALSE . For extended error information, call GetLastError.

Requirements

Minimum suppor ted client Windows XP [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header mssip.h

Librar y Crypt32.lib

DLL Crypt32.dll
 CryptSIPPutSignedDataMsg function (mssip.h)
7/2/2022 • 2 minutes to read • Edit Online

The Cr yptSIPPutSignedDataMsg function stores an Authenticode signature in the target file.

Syntax
BOOL CryptSIPPutSignedDataMsg(
[in] SIP_SUBJECTINFO *pSubjectInfo,
[in] DWORD dwEncodingType,
[out] DWORD *pdwIndex,
[in] DWORD cbSignedDataMsg,
[in] BYTE *pbSignedDataMsg
);

Parameters
[in] pSubjectInfo

Pointer to a SIP_SUBJECTINFO structure that contains information about the message subject.
[in] dwEncodingType

The encoding type of the message. This can be a combination of one or more of the following values.

VA L UE M EA N IN G

Specifies PKCS #7 message encoding.

PKCS_7_ASN_ENCODING
65536 (0x10000)

Specifies X.509 certificate encoding.

X509_ASN_ENCODING
1 (0x1)

[out] pdwIndex

Pointer to the message index.

[in] cbSignedDataMsg

Length, in bytes, of the buffer pointed to by the pbSignedDataMsg parameter.

[in] pbSignedDataMsg

Pointer to the buffer that contains the message.

Return value
If the function succeeds, the function returns TRUE .
If the function fails, it returns FALSE . For extended error information, call GetLastError. Some possible error
codes follow.
 RET URN C O DE DESC RIP T IO N

The specified data or file format of the subject interface

ERROR_BAD_FORMAT package (SIP) is not valid.

This code can be returned for the following reasons:

ERROR_INVALID_PARAMETER The pSubjectInfo is NULL .
The pdwIndex is NULL .
The pbSignedDataMsg is NULL .
The value of the cbSignedDataMsg parameter is less
than one.
[SIP_SUBJECTINFO](/windows/desktop/api/mssip/ns-
mssip-sip_subjectinfo) structure. [SIP_SUBJECTINFO]
(/windows/desktop/api/mssip/ns-mssip-sip_subjectinfo)
structure.

The specified subject type is not valid.

TRUST_E_SUBJECT_FORM_UNKNOWN

Remarks
Each subject type uses a different subset of its data for hash calculation and requires a different procedure for
storage and retrieval. Therefore, each subject type has a unique SIP specification.

Requirements

Minimum suppor ted client Windows XP [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header mssip.h

Librar y Crypt32.lib

DLL Crypt32.dll

See also
CryptSIPGetSignedDataMsg
CryptSIPRemoveSignedDataMsg
 CryptSIPRemoveProvider function (mssip.h)
7/2/2022 • 2 minutes to read • Edit Online

The Cr yptSIPRemoveProvider function removes registry details of a Subject Interface Package (SIP) DLL file
added by a previous call to the CryptSIPAddProvider function.

Syntax
BOOL CryptSIPRemoveProvider(
[in] GUID *pgProv
);

Parameters
[in] pgProv

A pointer to the GUID that identifies the SIP DLL to remove.

Return value
The return value is TRUE if the function succeeds; FALSE if the function fails. If the function fails, call the
GetLastError function to determine the reason for failure.

Remarks
Typically you call this function to unregister an in-process COM server. The Cr yptSIPRemoveProvider
function removes the appropriate Registry entries for the SIP provider functions.

Requirements

Minimum suppor ted client Windows XP [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header mssip.h

Librar y Crypt32.lib

DLL Crypt32.dll

See also
CryptSIPAddProvider
 CryptSIPRemoveSignedDataMsg function (mssip.h)
7/2/2022 • 2 minutes to read • Edit Online

The Cr yptSIPRemoveSignedDataMsg function removes a specified Authenticode signature.

Syntax
BOOL CryptSIPRemoveSignedDataMsg(
[in] SIP_SUBJECTINFO *pSubjectInfo,
[in] DWORD dwIndex
);

Parameters
[in] pSubjectInfo

A pointer to a SIP_SUBJECTINFO structure that contains information about the message subject.
[in] dwIndex

This parameter is reserved and should be set to zero.

Return value
If the function succeeds, the function returns TRUE .
If the function fails, it returns FALSE . For extended error information, call GetLastError.

Requirements

Minimum suppor ted client Windows XP [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header mssip.h

Librar y Crypt32.lib

DLL Crypt32.dll

See also
CryptSIPGetSignedDataMsg
CryptSIPPutSignedDataMsg
 CryptSIPRetrieveSubjectGuid function (mssip.h)
7/2/2022 • 2 minutes to read • Edit Online

The Cr yptSIPRetrieveSubjectGuid function retrieves a GUID based on the header information in a specified
file. The GUID is used by the CryptSIPLoad function to load the subject interface package (SIP) implementation
for the given file type.

Syntax
BOOL CryptSIPRetrieveSubjectGuid(
[in] LPCWSTR FileName,
[in, optional] HANDLE hFileIn,
[out] GUID *pgSubject
);

Parameters
[in] FileName

The name of the file.

[in, optional] hFileIn

A handle to the file to check.

[out] pgSubject

A GUID that identifies the subject.

Return value
If the function succeeds, the function returns TRUE .
If the function fails, it returns FALSE . For extended error information, call GetLastError.

Requirements

Minimum suppor ted client Windows XP [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header mssip.h

Librar y Crypt32.lib

DLL Crypt32.dll
 CryptSIPRetrieveSubjectGuidForCatalogFile
function (mssip.h)
7/2/2022 • 2 minutes to read • Edit Online

The Cr yptSIPRetrieveSubjectGuidForCatalogFile function retrieves the subject GUID associated with the
specified file.

Syntax
BOOL CryptSIPRetrieveSubjectGuidForCatalogFile(
[in] LPCWSTR FileName,
[in, optional] HANDLE hFileIn,
[out] GUID *pgSubject
);

Parameters
[in] FileName

The name of the file. If the hFileIn parameter is set, the value in this parameter is ignored.
[in, optional] hFileIn

A handle to the file to check. This parameter must contain a valid handle if the FileName parameter is NULL .
[out] pgSubject

A globally unique ID that identifies the subject.

Return value
The return value is TRUE if the function succeeds; otherwise, FALSE .
If this function returns FALSE , additional error information can be obtained by calling the GetLastError function.
GetLastError will return one of the following error codes.

RET URN C O DE DESC RIP T IO N

One or more of the parameters are not valid.

ERROR_INVALID_PARAMETER

Remarks
This function only supports subject interface packages (SIPs) that are used for portable executable images (.exe),
cabinet (.cab) images, and flat files.

Requirements
Minimum suppor ted client Windows XP [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header mssip.h

Librar y Crypt32.lib

DLL Crypt32.dll
 CryptSIPVerifyIndirectData function (mssip.h)
7/2/2022 • 2 minutes to read • Edit Online

The Cr yptSIPVerifyIndirectData function validates the indirect hashed data against the supplied subject.

Syntax
BOOL CryptSIPVerifyIndirectData(
[in] SIP_SUBJECTINFO *pSubjectInfo,
[in] SIP_INDIRECT_DATA *pIndirectData
);

Parameters
[in] pSubjectInfo

A pointer to a SIP_SUBJECTINFO structure that contains information about the message subject.
[in] pIndirectData

A pointer to a SIP_INDIRECT_DATA structure that contains information about the hashed subject information.

Return value
The return value is TRUE if the function succeeds; otherwise, FALSE .
If this function returns FALSE , additional error information can be obtained by calling the GetLastError function.
GetLastError will return one of the following error codes.

RET URN C O DE DESC RIP T IO N

One or more of the parameters are not valid.

ERROR_INVALID_PARAMETER

The subject type is an unknown type.

TRUST_E_SUBJECT_FORM_UNKNOWN

Remarks
Subjects include, but are not limited to, portable executable images (.exe), cabinet (.cab) images, flat files, and
catalog files. Each subject type uses a different subset of its data for hash calculation and requires a different
procedure for storage and retrieval. Therefore each subject type has a unique subject interface package
specification.

Requirements

Minimum suppor ted client Windows XP [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header mssip.h

Librar y Crypt32.lib

DLL Crypt32.dll
 MS_ADDINFO_BLOB structure (mssip.h)
7/2/2022 • 2 minutes to read • Edit Online

The MS_ADDINFO_BLOB structure provides additional information for in-memory BLOB subject types.

Syntax
typedef struct MS_ADDINFO_BLOB_ {
DWORD cbStruct;
DWORD cbMemObject;
BYTE *pbMemObject;
DWORD cbMemSignedMsg;
BYTE *pbMemSignedMsg;
} MS_ADDINFO_BLOB, *PMS_ADDINFO_BLOB;

Members
cbStruct

The size, in bytes, of this structure.

cbMemObject

The size, in bytes, of the data in the pbMemObject member.

pbMemObject

A pointer to the in-memory BLOB subject.

cbMemSignedMsg

The size, in bytes, of the data in the pbMemSignedMsg member.

pbMemSignedMsg

A pointer to the signed message.

Requirements

Minimum suppor ted client Windows XP [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Header mssip.h
 MS_ADDINFO_CATALOGMEMBER structure
(mssip.h)
7/2/2022 • 2 minutes to read • Edit Online

The MS_ADDINFO_CATALOGMEMBER structure provides additional information for catalog member subject
types.

Syntax
typedef struct MS_ADDINFO_CATALOGMEMBER_ {
DWORD cbStruct;
struct CRYPTCATSTORE_ *pStore;
struct CRYPTCATMEMBER_ *pMember;
} MS_ADDINFO_CATALOGMEMBER, *PMS_ADDINFO_CATALOGMEMBER;

Members
cbStruct

The size, in bytes, of this structure.

pStore

A CRYPTCATSTORE structure that contains a catalog file store.

pMember

A CRYPTCATMEMBER structure that contains a catalog member.

Requirements

Minimum suppor ted client Windows XP [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Header mssip.h
 MS_ADDINFO_FLAT structure (mssip.h)
7/2/2022 • 2 minutes to read • Edit Online

The MS_ADDINFO_FL AT structure provides additional information about flat or end-to-end subject types.

Syntax
typedef struct MS_ADDINFO_FLAT_ {
DWORD cbStruct;
struct SIP_INDIRECT_DATA_ *pIndirectData;
} MS_ADDINFO_FLAT, *PMS_ADDINFO_FLAT;

Members
cbStruct

The size, in bytes, of this structure.

pIndirectData

A SIP_INDIRECT_DATA structure that contains the hash of a flat file subject.

Requirements

Minimum suppor ted client Windows XP [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Header mssip.h
 pCryptSIPGetCaps callback function (mssip.h)
7/2/2022 • 2 minutes to read • Edit Online

The pCr yptSIPGetCaps function is implemented by an subject interface package (SIP) to report capabilities.

Syntax
pCryptSIPGetCaps Pcryptsipgetcaps;

BOOL Pcryptsipgetcaps(
[in] SIP_SUBJECTINFO *pSubjInfo,
[in, out] SIP_CAP_SET *pCaps
)
{...}

Parameters
[in] pSubjInfo

Pointer to a SIP_SUBJECTINFO structure that specifies subject information data to the SIP APIs.
[in, out] pCaps

Pointer to a SIP_CAP_SET structure that defines the capabilities of an SIP.

Return value
None

Requirements

Minimum suppor ted client Windows 8 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2012 [desktop apps only]

Target Platform Windows

Header mssip.h

See also
CryptSIPGetCaps
SIP_CAP_SET
SIP_SUBJECTINFO
 pfnIsFileSupported callback function (mssip.h)
7/2/2022 • 2 minutes to read • Edit Online

The pfnIsFileSuppor ted callback function queries the subject interface packages (SIPs) listed in the registry to
determine which SIP handles the file type.

Syntax
pfnIsFileSupported Pfnisfilesupported;

BOOL Pfnisfilesupported(
[in] HANDLE hFile,
[out] GUID *pgSubject
)
{...}

Parameters
[in] hFile

A handle to the file.

[out] pgSubject

The GUID that identifies the SIP that handles the file type.

Return value
If the function succeeds, the function returns TRUE .
If the function fails, it returns FALSE . For extended error information, call GetLastError.

Remarks
If the SIP supports the file type passed by hfile, the function returns TRUE , and sets pgSubject to the GUID that
identifies the SIP for handling the file type.
Each SIP implements its own version of the function that determines whether the file type is supported. The
specific name of the function may vary depending on the implementation of the SIP, but the signature of the
function will match that of the SIP_ADD_NEWPROVIDER structure.

Requirements

Minimum suppor ted client Windows XP [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header mssip.h
 pfnIsFileSupportedName callback function (mssip.h)
7/2/2022 • 2 minutes to read • Edit Online

The pfnIsFileSuppor tedName callback function queries the subject interface packages (SIPs) listed in the
registry to determine which SIP handles the file type.

Syntax
pfnIsFileSupportedName Pfnisfilesupportedname;

BOOL Pfnisfilesupportedname(
[in] WCHAR *pwszFileName,
[out] GUID *pgSubject
)
{...}

Parameters
[in] pwszFileName

A pointer to a null -terminated string that contains the absolute path to the file to be processed by the SIP.
[out] pgSubject

The GUID identifying the SIP that handles the file type.

Return value
The return value is TRUE if the function succeeds; FALSE if the function fails. If the function fails, call the
GetLastError function to determine the reason for failure.

Remarks
If the SIP supports the file type passed by hfile, the function returns TRUE , and sets pgSubject to the GUID that
identifies the SIP for handling the file type.
Each SIP implements its own version of the function that determines if the file type is supported. The specific
name of the function may vary depending on the implementation of the SIP, but the signature of the function
will match that of the SIP_ADD_NEWPROVIDER structure.
SIPs must support a limited set of file types and file extensions. The fileSupportedName function must check
that the provided file matches one of the file extensions supported by the SIP. For instance, the WSH SIP
supports only the following list of file extensions and checks that the file under validation is a member of the
following list: .js, .jse, .vbe, .vbs, or .wsf.

Requirements

Minimum suppor ted client Windows XP [desktop apps only]

 Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header mssip.h

See also
pfnIsFileSupported
 SIP_ADD_NEWPROVIDER structure (mssip.h)
7/2/2022 • 2 minutes to read • Edit Online

The SIP_ADD_NEWPROVIDER structure defines a subject interface package (SIP). This structure is used by the
CryptSIPAddProvider function.

Syntax
typedef struct SIP_ADD_NEWPROVIDER_ {
DWORD cbStruct;
GUID *pgSubject;
WCHAR *pwszDLLFileName;
WCHAR *pwszMagicNumber;
WCHAR *pwszIsFunctionName;
WCHAR *pwszGetFuncName;
WCHAR *pwszPutFuncName;
WCHAR *pwszCreateFuncName;
WCHAR *pwszVerifyFuncName;
WCHAR *pwszRemoveFuncName;
WCHAR *pwszIsFunctionNameFmt2;
PWSTR pwszGetCapFuncName;
} SIP_ADD_NEWPROVIDER, *PSIP_ADD_NEWPROVIDER;

Members
cbStruct

The size, in bytes, of this structure. Set this value to sizeof(SIP_ADD_NEWPROVIDER) .

pgSubject

Pointer to the GUID that identifies the SIP.

pwszDLLFileName

Pointer to a null-terminated string that contains the name of the DLL file.
pwszMagicNumber

This member is not used.

pwszIsFunctionName

Pointer to a null-terminated string that contains the name of the function that determines whether the file
contents are supported by this SIP. This member can be NULL . The signature for this function pointer is
described in pfnIsFileSupported.
pwszGetFuncName

Pointer to a null-terminated string that contains the name of the function that retrieves the signed data. The
signature for this function pointer is described in CryptSIPGetSignedDataMsg.
pwszPutFuncName

Pointer to a null-terminated string that contains the name of the function that stores the Authenticode signature
in the target file. The signature for this function pointer is described in CryptSIPPutSignedDataMsg.
pwszCreateFuncName

Pointer to a null-terminated string that contains the name of the function that creates the hash. The signature for
this function pointer is described in CryptSIPCreateIndirectData.
pwszVerifyFuncName

Pointer to a null-terminated string that contains the name of the function that verifies the hash. The signature for
this function pointer is described in CryptSIPVerifyIndirectData.
pwszRemoveFuncName

Pointer to a null-terminated string that contains the name of the function that removes the signed data. The
signature for this function pointer is described in CryptSIPRemoveSignedDataMsg.
pwszIsFunctionNameFmt2

Pointer to a null-terminated string that contains the name of the function that determines whether the file name
extension is supported by this SIP. This member can be NULL . The signature for this function pointer is
described in pfnIsFileSupportedName.
pwszGetCapFuncName

Pointer to a null-terminated string that contains the name of the function that determines the capabilities of the
SIP. If this parameter is set to NULL , multiple signatures are not available for this SIP. The signature for this
function pointer is described in pCryptSIPGetCaps.
Windows Ser ver 2008 R2, Windows 7, Windows Ser ver 2008, Windows Vista, Windows
Ser ver 2003 and Windows XP: This member is not available.

Requirements

Minimum suppor ted client Windows XP [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Header mssip.h

See also
CryptSIPAddProvider
 SIP_CAP_SET_V2 structure (mssip.h)
7/2/2022 • 2 minutes to read • Edit Online

The SIP_CAP_SET structure defines the capabilities of a subject interface package (SIP).

Syntax
typedef struct _SIP_CAP_SET_V2 {
DWORD cbSize;
DWORD dwVersion;
BOOL isMultiSign;
DWORD dwReserved;
} SIP_CAP_SET_V2, *PSIP_CAP_SET_V2;

Members
cbSize

Size, in bytes, of this structure.

dwVersion

The SIP version. By default, this value is two (2).

isMultiSign

A value of one (1) indicates that the SIP supports multiple embedded signatures. Otherwise, set this value to
zero (0).
dwReserved

Reserved for future use. Set this value to zero (0).

Requirements

Minimum suppor ted client Windows 8 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2012 [desktop apps only]

Header mssip.h
 SIP_CAP_SET_V3 structure (mssip.h)
7/2/2022 • 2 minutes to read • Edit Online

The SIP_CAP_SET structure defines the capabilities of a subject interface package (SIP).

Syntax
typedef struct _SIP_CAP_SET_V3 {
DWORD cbSize;
DWORD dwVersion;
BOOL isMultiSign;
union {
DWORD dwFlags;
DWORD dwReserved;
};
} SIP_CAP_SET_V3, *PSIP_CAP_SET_V3;

Members
cbSize

Size, in bytes, of this structure.

dwVersion

The SIP version. By default, this value is two (2).

isMultiSign

A value of one (1) indicates that the SIP supports multiple embedded signatures. Otherwise, set this value to
zero (0).
dwFlags

dwReserved

Reserved for future use. Set this value to zero (0).

Requirements

Minimum suppor ted client Windows 8 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2012 [desktop apps only]

Header mssip.h
 SIP_DISPATCH_INFO structure (mssip.h)
7/2/2022 • 2 minutes to read • Edit Online

The SIP_DISPATCH_INFO structure contains a set of function pointers assigned by the CryptSIPLoad function
that your application uses to perform subject interface package (SIP) operations.

Syntax
typedef struct SIP_DISPATCH_INFO_ {
DWORD cbSize;
HANDLE hSIP;
pCryptSIPGetSignedDataMsg pfGet;
pCryptSIPPutSignedDataMsg pfPut;
pCryptSIPCreateIndirectData pfCreate;
pCryptSIPVerifyIndirectData pfVerify;
pCryptSIPRemoveSignedDataMsg pfRemove;
} SIP_DISPATCH_INFO, *LPSIP_DISPATCH_INFO;

Members
cbSize

The size, in bytes, of this structure.

hSIP

This member is reserved and must be set to NULL .

pfGet

A pointer to the function that retrieves the signed data for the subject. The signature for this function pointer is
described in CryptSIPGetSignedDataMsg.
pfPut

A pointer to the function that stores the signed data for the subject. The signature for this function pointer is
described in CryptSIPPutSignedDataMsg.
pfCreate

A pointer to the function that returns a SIP_INDIRECT_DATA structure that contains the subject data. This
structure contains the hash of the target. The signature for this function pointer is described in
CryptSIPCreateIndirectData.
pfVerify

A pointer to the function that verifies the SIP_INDIRECT_DATA structure that contains the subject data. This
structure contains the hash of the target. The signature for this function pointer is described in
CryptSIPVerifyIndirectData.
pfRemove

A pointer to the function that removes the signed data for the subject. The signature for this function pointer is
described in CryptSIPRemoveSignedDataMsg.
Remarks
Your application must initialize this structure to binary zeros and set cbSize to sizeof(SIP_DISPATCH_INFO) by
calling the memset function before calling the CryptSIPLoad function. Your application can use the function
pointers in the returned SIP_DISPATCH_INFO structure to perform the necessary SIP operations. The function
pointers can point to functions exported by third party SIPs.

Requirements

Minimum suppor ted client Windows XP [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Header mssip.h

See also
CryptSIPCreateIndirectData
CryptSIPGetSignedDataMsg
CryptSIPPutSignedDataMsg
CryptSIPRemoveSignedDataMsg
CryptSIPVerifyIndirectData
 SIP_INDIRECT_DATA structure (mssip.h)
7/2/2022 • 2 minutes to read • Edit Online

The SIP_INDIRECT_DATA structure contains the digest of the hashed subject information.

Syntax
typedef struct SIP_INDIRECT_DATA_ {
CRYPT_ATTRIBUTE_TYPE_VALUE Data;
CRYPT_ALGORITHM_IDENTIFIER DigestAlgorithm;
CRYPT_HASH_BLOB Digest;
} SIP_INDIRECT_DATA, *PSIP_INDIRECT_DATA;

Members
Data

A CRYPT_ATTRIBUTE_TYPE_VALUE structure used to encode the attribute.

DigestAlgorithm

A CRYPT_ALGORITHM_IDENTIFIER structure that contains the digest algorithm to use to create the hash.
Digest

A CRYPT_HASH_BLOB structure that contains the hash of the subject. For information about
CRYPT_HASH_BLOB , see CRYPT_INTEGER_BLOB .

Requirements

Minimum suppor ted client Windows XP [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Header mssip.h
 SIP_SUBJECTINFO structure (mssip.h)
7/2/2022 • 2 minutes to read • Edit Online

The SIP_SUBJECTINFO structure specifies subject information data to the subject interface package (SIP) APIs.

Syntax
typedef struct SIP_SUBJECTINFO_ {
DWORD cbSize;
GUID *pgSubjectType;
HANDLE hFile;
LPCWSTR pwsFileName;
LPCWSTR pwsDisplayName;
DWORD dwReserved1;
DWORD dwIntVersion;
HCRYPTPROV hProv;
CRYPT_ALGORITHM_IDENTIFIER DigestAlgorithm;
DWORD dwFlags;
DWORD dwEncodingType;
DWORD dwReserved2;
DWORD fdwCAPISettings;
DWORD fdwSecuritySettings;
DWORD dwIndex;
DWORD dwUnionChoice;
union {
#if ...
MS_ADDINFO_FLAT_ *psFlat;
#else
struct MS_ADDINFO_FLAT_ *psFlat;
#endif
#if ...
MS_ADDINFO_CATALOGMEMBER_ *psCatMember;
#else
struct MS_ADDINFO_CATALOGMEMBER_ *psCatMember;
#endif
#if ...
MS_ADDINFO_BLOB_ *psBlob;
#else
struct MS_ADDINFO_BLOB_ *psBlob;
#endif
};
LPVOID pClientData;
} SIP_SUBJECTINFO, *LPSIP_SUBJECTINFO;

Members
cbSize

The size, in bytes, of this structure.

pgSubjectType

A pointer to a GUID structure that identifies the subject type.

hFile

A file handle that represents the subject. If the storage type of the subject is a file, set hFile to
INVALID_HANDLE_VALUE and set the pwsFileName parameter to the name of the file.
pwsFileName

A pointer to a null-terminated Unicode string that contains the file name of the subject.
pwsDisplayName

A pointer to a null-terminated Unicode string that contains the display name of the subject.
dwReserved1

This member is reserved for future use.

dwIntVersion

This member is reserved. Do not modify this member. It is used by the SIP to pass the internal version number
between get and verify functions.
hProv

An HCRYPTPROV handle to the cryptography provider.

DigestAlgorithm

A CRYPT_ALGORITHM_IDENTIFIER structure that contains the identifier for the hash algorithm used to hash the
file.
dwFlags

A value that modifies the behavior of the functions that use this structure. For more information about possible
values for this member, see the dwFlags parameter of SignerSignEx.
dwEncodingType

A value that specifies the encoding type used for the file. Currently, only X509_ASN_ENCODING and
PKCS_7_ASN_ENCODING are being used; however, additional encoding types may be added in the future. For
either current encoding type, use: X509_ASN_ENCODING | PKCS_7_ASN_ENCODING .
dwReserved2

This member is reserved for future use.

fdwCAPISettings

This member is not used.

fdwSecuritySettings

This member is not used.

dwIndex

The message index of the last call to Cr yptSIPGetSignedDataMsg . operation.

dwUnionChoice

Specifies the type of additional information provided.

DEF IN ED C O N STA N T / VA L UE M EA N IN G

There is no additional information about the subject.

MSSIP_ADDINFO_NONE
0
 The additional information is a flat file.
MSSIP_ADDINFO_FL AT
1

The additional information is a catalog member.

MSSIP_ADDINFO_CATMEMBER
2

The additional information is a BLOB.

MSSIP_ADDINFO_BLOB
3

The additional information is in a user defined format.

MSSIP_ADDINFO_NONMSSIP
500

psFlat

An MS_ADDINFO_FLAT structure that contains additional information for flat file subject types.
psCatMember

An MS_ADDINFO_CATALOGMEMBER structure that contains additional information for catalog member subject
types.
psBlob

An MS_ADDINFO_BLOB structure that contains additional information for BLOB subject types.
pClientData

A pointer to SIP-specific data.

Remarks
Upon first use of the SIP_SUBJECTINFO structure, initialize the entire structure to binary zero. Do not initialize
the structure between SIP function calls.
Subjects include, but are not limited to, portable executable images (.exe), cabinet (.cab) images, flat files, and
catalog files. Each subject type uses a different subset of its data for hash calculation and requires a different
procedure for storage and retrieval. Therefore each subject type has a unique subject interface package
specification.

Requirements

Minimum suppor ted client Windows XP [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Header mssip.h
 namedpipeapi.h header
7/2/2022 • 2 minutes to read • Edit Online

This header is used by multiple technologies. For more information, see:

Security and Identity
System Services
namedpipeapi.h contains the following programming interfaces:

Functions

CallNamedPipeW

Connects to a message-type pipe (and waits if an instance of the pipe is not available), writes to and reads from the pipe, and
then closes the pipe.

ConnectNamedPipe

Enables a named pipe server process to wait for a client process to connect to an instance of a named pipe.

CreateNamedPipeW

Creates an instance of a named pipe and returns a handle for subsequent pipe operations.

CreatePipe

Creates an anonymous pipe, and returns handles to the read and write ends of the pipe.

DisconnectNamedPipe

Disconnects the server end of a named pipe instance from a client process.

GetNamedPipeClientComputerNameW

Retrieves the client computer name for the specified named pipe.

GetNamedPipeHandleStateW

Retrieves information about a specified named pipe.

GetNamedPipeInfo

Retrieves information about the specified named pipe.

ImpersonateNamedPipeClient

Impersonates a named-pipe client application.

PeekNamedPipe

Copies data from a named or anonymous pipe into a buffer without removing it from the pipe.

SetNamedPipeHandleState

Sets the read mode and the blocking mode of the specified named pipe. If the specified handle is to the client end of a named
pipe and if the named pipe server process is on a remote computer, the function can also be used to control local buffering.

TransactNamedPipe

Combines the functions that write a message to and read a message from the specified named pipe into a single network
operation.

WaitNamedPipeW

Waits until either a time-out interval elapses or an instance of the specified named pipe is available for connection (that is, the
pipe's server process has a pending ConnectNamedPipe operation on the pipe).
 ImpersonateNamedPipeClient function
(namedpipeapi.h)
7/2/2022 • 2 minutes to read • Edit Online

The ImpersonateNamedPipeClient function impersonates a named-pipe client application.

Syntax
BOOL ImpersonateNamedPipeClient(
[in] HANDLE hNamedPipe
);

Parameters
[in] hNamedPipe

A handle to a named pipe.

Return value
If the function succeeds, the return value is nonzero.
If the function fails, the return value is zero. To get extended error information, call GetLastError.

Remarks
The ImpersonateNamedPipeClient function allows the server end of a named pipe to impersonate the client
end. When this function is called, the named-pipe file system changes the thread of the calling process to start
impersonating the security context of the last message read from the pipe. Only the server end of the pipe can
call this function.
The server can call the RevertToSelf function when the impersonation is complete.

Impor tant If the ImpersonateNamedPipeClient function fails, the client is not impersonated, and all subsequent client
requests are made in the security context of the process that called the function. If the calling process is running as a
privileged account, it can perform actions that the client would not be allowed to perform. To avoid security risks, the calling
process should always check the return value. If the return value indicates that the function call failed, no client requests
should be executed.

All impersonate functions, including ImpersonateNamedPipeClient allow the requested impersonation if one of
the following is true:
The requested impersonation level of the token is less than SecurityImpersonation , such as
SecurityIdentification or SecurityAnonymous .
The caller has the SeImpersonatePrivilege privilege.
A process (or another process in the caller's logon session) created the token using explicit credentials
through LogonUser or LsaLogonUser function.
The authenticated identity is same as the caller.
Windows XP with SP1 and earlier : The SeImpersonatePrivilege privilege is not supported.
Examples
For an example that uses this function, see Verifying Client Access with ACLs.

Requirements

Minimum suppor ted client Windows XP [desktop apps only]

Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]

Target Platform Windows

Header namedpipeapi.h

Librar y Advapi32.lib

DLL Advapi32.dll

See also
Authorization functions
Client/Server Access Control Overview
DdeImpersonateClient
DuplicateToken
RevertToSelf
 ncrypt.h header
7/2/2022 • 2 minutes to read • Edit Online

This header is used by Security and Identity. For more information, see:
Security and Identity

Aliases
NCryptBuffer (alias of BCryptBuffer)
NCryptBufferDesc (alias of BCryptBufferDesc)

ncrypt.h contains the following programming interfaces:

Functions

NCryptCreateClaim

Creates a key attestation claim.

NCryptCreatePersistedKey

Creates a new key and stores it in the specified key storage provider.

NCryptDecrypt

Decrypts a block of encrypted data.

NCryptDeleteKey

Deletes a CNG key.

NCryptDeriveKey

Derives a key from a secret agreement value.

NCryptEncrypt

Encrypts a block of data.

NCryptEnumAlgorithms

Obtains the names of the algorithms that are supported by the specified key storage provider.

NCryptEnumKeys

Obtains the names of the keys that are stored by the provider.
NCryptEnumStorageProviders

Obtains the names of the registered key storage providers.

NCryptExportKey

Exports a CNG key to a memory BLOB.

NCryptFinalizeKey

Completes a CNG key storage key.

NCryptFreeBuffer

Releases a block of memory allocated by a CNG key storage provider.

NCryptFreeObject

Frees a CNG key storage object.

NCryptGetProperty

Retrieves the value of a named property for a key storage object.

NCryptImportKey

Imports a Cryptography API:_Next Generation (CNG) key from a memory BLOB.

NCryptIsAlgSupported

Determines if a CNG key storage provider supports a specific cryptographic algorithm.

NCryptIsKeyHandle

Determines if the specified handle is a CNG key handle.

NCryptKeyDerivation

Creates a key from another key by using the specified key derivation function.

NCryptNotifyChangeKey

Creates or removes a key change notification.

NCryptOpenKey

Opens a key that exists in the specified CNG key storage provider.

NCryptOpenStorageProvider

Loads and initializes a CNG key storage provider.

NCryptSecretAgreement

Creates a secret agreement value from a private and a public key.

 NCryptSetProperty

Sets the value for a named property for a CNG key storage object.

NCryptSignHash

Creates a signature of a hash value.

NCryptTranslateHandle

Translates a CryptoAPI handle into a CNG key handle.

NCryptVerifyClaim

Verifies a key attestation claim.

NCryptVerifySignature

Verifies that the specified signature matches the specified hash.

Structures

NCRYPT_ALLOC_PARA

Enables you to specify custom functions that can be used to allocate and free data.

NCRYPT_KEY_BLOB_HEADER

Contains a key BLOB.

NCRYPT_SUPPORTED_LENGTHS

Used with the NCRYPT_LENGTHS_PROPERTY property to contain length information for a key.

NCRYPT_UI_POLICY

Used with the NCRYPT_UI_POLICY_PROPERTY property to contain strong key user interface information for a key.

NCryptAlgorithmName

Used to contain information about a CNG algorithm.

NCryptKeyName

Used to contain information about a CNG key.

NCryptProviderName

Used to contain the name of a CNG key storage provider.

 NCRYPT_ALLOC_PARA structure (ncrypt.h)
7/2/2022 • 2 minutes to read • Edit Online

The NCRYPT_ALLOC_PARA structure enables you to specify custom functions that can be used to allocate and
free data. This structure is used in the following functions:
NCryptGetProtectionDescriptorInfo
NCryptProtectSecret
NCryptUnprotectSecret

Syntax
typedef struct NCRYPT_ALLOC_PARA {
DWORD cbSize;
PFN_NCRYPT_ALLOC pfnAlloc;
PFN_NCRYPT_FREE pfnFree;
} NCRYPT_ALLOC_PARA;

Members
cbSize

The size, in bytes, of this structure.

pfnAlloc

Address of a custom function that can allocate memory.

pfnFree

Address of a function that can free memory allocated by the function specified by the pfnAlloc member.

Requirements

Minimum suppor ted client Windows 8 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2012 [desktop apps only]

Header ncrypt.h

See also
NCryptGetProtectionDescriptorInfo
NCryptProtectSecret
NCryptUnprotectSecret
 NCRYPT_KEY_BLOB_HEADER structure (ncrypt.h)
7/2/2022 • 2 minutes to read • Edit Online

The NCRYPT_KEY_BLOB_HEADER structure contains a key BLOB . This structure is used by the
NCryptExportKey and NCryptImportKey functions.

Syntax
typedef struct _NCRYPT_KEY_BLOB_HEADER {
ULONG cbSize;
ULONG dwMagic;
ULONG cbAlgName;
ULONG cbKeyData;
} NCRYPT_KEY_BLOB_HEADER, *PNCRYPT_KEY_BLOB_HEADER;

Members
cbSize

The size, in bytes, of this structure.

dwMagic

Identifies the BLOB type. This can be one of the following values.
NCRYPT_CIPHER_KEY_BLOB_MAGIC
NCRYPT_PROTECTED_KEY_BLOB_MAGIC
cbAlgName

Size, in bytes, of the null-terminated algorithm name, including the terminating zero.
cbKeyData

Size, in bytes, of the BLOB .

Requirements

Minimum suppor ted client Windows 8 [desktop apps only]

Minimum suppor ted ser ver Windows Server 2012 [desktop apps only]

Header ncrypt.h

See also
NCryptExportKey
NCryptImportKey
 NCRYPT_SUPPORTED_LENGTHS structure
(ncrypt.h)
7/2/2022 • 2 minutes to read • Edit Online

The NCRYPT_SUPPORTED_LENGTHS structure is used with the NCRYPT_LENGTHS_PROPERTY property to

contain length information for a key.

Syntax
typedef struct __NCRYPT_SUPPORTED_LENGTHS {
DWORD dwMinLength;
DWORD dwMaxLength;
DWORD dwIncrement;
DWORD dwDefaultLength;
} NCRYPT_SUPPORTED_LENGTHS;

Members
dwMinLength

The minimum length, in bits, of a key.

dwMaxLength

The maximum length, in bits, of a key.

dwIncrement

The number of bits that the key size can be incremented between dwMinLength and dwMaxLength .
dwDefaultLength

The default length, in bits, of a key.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Header ncrypt.h
 NCRYPT_UI_POLICY structure (ncrypt.h)
7/2/2022 • 2 minutes to read • Edit Online

The NCRYPT_UI_POLICY structure is used with the NCRYPT_UI_POLICY_PROPERTY property to contain strong
key user interface information for a key. This structure is used with the NCryptSetProperty and
NCryptGetProperty functions with the NCRYPT_UI_POLICY_PROPERTY property.

Syntax
typedef struct __NCRYPT_UI_POLICY {
DWORD dwVersion;
DWORD dwFlags;
LPCWSTR pszCreationTitle;
LPCWSTR pszFriendlyName;
LPCWSTR pszDescription;
} NCRYPT_UI_POLICY;

Members
dwVersion

The version number of the structure. This member must contain 1.

dwFlags

A set of flags that provide additional user interface information or requirements.

VA L UE M EA N IN G

Display the strong key user interface as needed.

NCRYPT_UI_PROTECT_KEY_FL AG
0x00000001

Force high protection.

NCRYPT_UI_FORCE_HIGH_PROTECTION_FL AG
0x00000002

An app container has accessed a medium key that is not

NCRYPT_UI_APPCONTAINER_ACCESS_MEDIUM_FL AG strongly protected. For example, a key that is for user
0x00000008 consent only, or is password or fingerprint protected.

pszCreationTitle

A pointer to a null-terminated Unicode string that contains the text that will be used in the title of the strong key
dialog box when the key is completed. If this member is NULL , a default creation title will be used in the strong
key dialog box. This member is only used on key finalization.
pszFriendlyName

A pointer to a null-terminated Unicode string that contains the text that will be displayed in the strong key
dialog box as the name of the key. If this member is NULL , a default name will be used in the strong key dialog
box. This member is used both when the key is completed and when the key is used.
pszDescription

A pointer to a null-terminated Unicode string that contains the text that will be displayed in the strong key
dialog box as the description of the key. If this member is NULL , a default description will be used in the strong
key dialog box. This member is used both when the key is completed and when the key is used.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Header ncrypt.h
 NCryptAlgorithmName structure (ncrypt.h)
7/2/2022 • 2 minutes to read • Edit Online

The NCr yptAlgorithmName structure is used to contain information about a CNG algorithm.

Syntax
typedef struct _NCryptAlgorithmName {
LPWSTR pszName;
DWORD dwClass;
DWORD dwAlgOperations;
DWORD dwFlags;
} NCryptAlgorithmName;

Members
pszName

A pointer to a null-terminated Unicode string that contains the name of the algorithm. This can be one of the
standard CNG Algorithm Identifiers or the identifier for another registered algorithm.
dwClass

A DWORD value that defines which algorithm class this algorithm belongs to. This can be one of the following
values.

VA L UE M EA N IN G

The algorithm belongs to the asymmetric encryption class of

NCRYPT_ASYMMETRIC_ENCRYPTION_INTERFACE algorithms.
0x00000003

The algorithm belongs to the secret agreement (Diffie-

NCRYPT_SECRET_AGREEMENT_INTERFACE Hellman) class of algorithms.
0x00000004

The algorithm belongs to the signature class of algorithms.

NCRYPT_SIGNATURE_INTERFACE
0x00000005

dwAlgOperations

A DWORD value that defines which operational classes this algorithm belongs to. This can be a combination of
one or more of the following values.

VA L UE M EA N IN G

The algorithm is an asymmetric encryption algorithm.

NCRYPT_ASYMMETRIC_ENCRYPTION_OPERATION
0x00000004
 The algorithm is a secret agreement (Diffie-Hellman)
NCRYPT_SECRET_AGREEMENT_OPERATION algorithm.
0x00000008

The algorithm is a digital signature algorithm.

NCRYPT_SIGNATURE_OPERATION
0x00000010

dwFlags

A set of flags that provide more information about the algorithm.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Header ncrypt.h

See also
NCryptEnumAlgorithms
 NCryptCreateClaim function (ncrypt.h)
7/2/2022 • 2 minutes to read • Edit Online

Creates a key attestation claim.

Syntax
SECURITY_STATUS NCryptCreateClaim(
[in] NCRYPT_KEY_HANDLE hSubjectKey,
[in, optional] NCRYPT_KEY_HANDLE hAuthorityKey,
[in] DWORD dwClaimType,
[in, optional] NCryptBufferDesc *pParameterList,
[out] PBYTE pbClaimBlob,
[in] DWORD cbClaimBlob,
[out] DWORD *pcbResult,
[in] DWORD dwFlags
);

Parameters
[in] hSubjectKey

The subject key handle that the claim is created for.

[in, optional] hAuthorityKey

The authority key handle that the claim is based on.

[in] dwClaimType

The type of claim.

[in, optional] pParameterList

An optional parameter list.

[out] pbClaimBlob

Output of the created claim blob.

[in] cbClaimBlob

[out] pcbResult

The output of the created claim blob.

[in] dwFlags

As of Windows 10, no flags are defined. This parameter should be set to 0.

Return value
Returns a status code that indicates the success or failure of the function.

Requirements
Minimum suppor ted client Windows 10 [desktop apps | UWP apps]

Minimum suppor ted ser ver Windows Server 2016 [desktop apps | UWP apps]

Target Platform Windows

Header ncrypt.h

Librar y Ncrypt.lib

DLL Ncrypt.dll
 NCryptCreatePersistedKey function (ncrypt.h)
7/2/2022 • 2 minutes to read • Edit Online

The NCr yptCreatePersistedKey function creates a new key and stores it in the specified key storage provider.
After you create a key by using this function, you can use the NCryptSetProperty function to set its properties;
however, the key cannot be used until the NCryptFinalizeKey function is called.

Syntax
SECURITY_STATUS NCryptCreatePersistedKey(
[in] NCRYPT_PROV_HANDLE hProvider,
[out] NCRYPT_KEY_HANDLE *phKey,
[in] LPCWSTR pszAlgId,
[in, optional] LPCWSTR pszKeyName,
[in] DWORD dwLegacyKeySpec,
[in] DWORD dwFlags
);

Parameters
[in] hProvider

The handle of the key storage provider to create the key in. This handle is obtained by using the
NCryptOpenStorageProvider function.
[out] phKey

The address of an NCRYPT_KEY_HANDLE variable that receives the handle of the key. When you have finished
using this handle, release it by passing it to the NCryptFreeObject function.
[in] pszAlgId

A pointer to a null-terminated Unicode string that contains the identifier of the cryptographic algorithm to
create the key. This can be one of the standard CNG Algorithm Identifiers or the identifier for another registered
algorithm.
[in, optional] pszKeyName

A pointer to a null-terminated Unicode string that contains the name of the key. If this parameter is NULL , this
function will create an ephemeral key that is not persisted.
[in] dwLegacyKeySpec

A legacy identifier that specifies the type of key. This can be one of the following values.

VA L UE M EA N IN G

The key is a key exchange key.

AT_KEYEXCHANGE

The key is a signature key.

AT_SIGNATURE
 The key is none of the above types.
0

[in] dwFlags

A set of flags that modify the behavior of this function. This can be zero or a combination of one or more of the
following values.

VA L UE M EA N IN G

The key applies to the local computer. If this flag is not

NCRYPT_MACHINE_KEY_FL AG present, the key applies to the current user.

If a key already exists in the container with the specified

NCRYPT_OVERWRITE_KEY_FL AG name, the existing key will be overwritten. If this flag is not
specified and a key with the specified name already exists,
this function will return NTE_EXISTS.

Return value
Returns a status code that indicates the success or failure of the function.
Possible return codes include, but are not limited to, the following.

RET URN C O DE DESC RIP T IO N

The function was successful.

ERROR_SUCCESS

The dwFlags parameter contains a value that is not valid.

NTE_BAD_FL AGS

A key with the specified name already exists and the

NTE_EXISTS NCRYPT_OVERWRITE_KEY_FL AG was not specified.

The hProvider parameter is not valid.

NTE_INVALID_HANDLE

One or more parameters are not valid.

NTE_INVALID_PARAMETER

A memory allocation failure occurred.

NTE_NO_MEMORY

Remarks
If you are creating an RSA key pair, you can also have the key stored in legacy storage so that it can be used with
the CryptoAPI by passing the NCRYPT_WRITE_KEY_TO_LEGACY_STORE_FL AG flag to the
NCryptFinalizeKey function when the key is finalized.
A service must not call this function from its StartService Function. If a service calls this function from its
StartService function, a deadlock can occur, and the service may stop responding.
Requirements

Minimum suppor ted client Windows Vista [desktop apps | UWP apps]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps | UWP apps]

Target Platform Windows

Header ncrypt.h

Librar y Ncrypt.lib

DLL Ncrypt.dll

See also
NCryptDeleteKey
NCryptFinalizeKey
 NCryptDecrypt function (ncrypt.h)
7/2/2022 • 2 minutes to read • Edit Online

The NCr yptDecr ypt function decrypts a block of encrypted data.

Syntax
SECURITY_STATUS NCryptDecrypt(
[in] NCRYPT_KEY_HANDLE hKey,
[in] PBYTE pbInput,
[in] DWORD cbInput,
[in, optional] VOID *pPaddingInfo,
[out] PBYTE pbOutput,
[in] DWORD cbOutput,
[out] DWORD *pcbResult,
[in] DWORD dwFlags
);

Parameters
[in] hKey

The handle of the key to use to decrypt the data.

[in] pbInput

The address of a buffer that contains the data to be decrypted. The cbInput parameter contains the size of the
data to decrypt. For more information, see Remarks.
[in] cbInput

The number of bytes in the pbInput buffer to decrypt.

[in, optional] pPaddingInfo

A pointer to a structure that contains padding information. The actual type of structure this parameter points to
depends on the value of the dwFlags parameter. This parameter is only used with asymmetric keys and must be
NULL otherwise.
[out] pbOutput

The address of a buffer that will receive the decrypted data produced by this function. The cbOutput parameter
contains the size of this buffer. For more information, see Remarks.
If this parameter is NULL , this function will calculate the size needed for the decrypted data and return the size
in the location pointed to by the pcbResult parameter.
[in] cbOutput

The size, in bytes, of the pbOutput buffer. This parameter is ignored if the pbOutput parameter is NULL .
[out] pcbResult

A pointer to a DWORD variable that receives the number of bytes copied to the pbOutput buffer. If pbOutput is
NULL , this receives the size, in bytes, required for the decrypted data.
[in] dwFlags

Flags that modify function behavior. The allowed set of flags depends on the type of key specified by the hKey
parameter.
If the key is an asymmetric key, this can be one of the following values.

VA L UE M EA N IN G

No padding was used when the data was encrypted. The

NCRYPT_NO_PADDING_FL AG pPaddingInfo parameter is not used.

The Optimal Asymmetric Encryption Padding (OAEP) scheme

NCRYPT_PAD_OAEP_FL AG was used when the data was encrypted. The pPaddingInfo
parameter is a pointer to a BCRYPT_OAEP_PADDING_INFO
structure.

The data was padded with a random number to round out

NCRYPT_PAD_PKCS1_FL AG the block size when the data was encrypted. The
pPaddingInfo parameter is not used.

The following value can be used for any key.

VA L UE M EA N IN G

Requests that the key service provider (KSP) not display any
NCRYPT_SILENT_FL AG user interface. If the provider must display the UI to operate,
the call fails and the KSP should set the
NTE_SILENT_CONTEXT error code as the last error.

Return value
Returns a status code that indicates the success or failure of the function.
Possible return codes include, but are not limited to, the following.

RET URN C O DE DESC RIP T IO N

The function was successful.

ERROR_SUCCESS

The dwFlags parameter contains a value that is not valid.

NTE_BAD_FL AGS

The size specified by the cbOutput parameter is not large

NTE_BUFFER_TOO_SMALL enough to hold the decrypted data.

The hKey parameter is not valid.

NTE_INVALID_HANDLE

One or more parameters are not valid.

NTE_INVALID_PARAMETER
 The key identified by the hKey parameter cannot be used for
NTE_PERM decryption.

Remarks
The pbInput and pbOutput parameters can point to the same buffer. In this case, this function will perform the
decryption in place.
A service must not call this function from its StartService Function. If a service calls this function from its
StartService function, a deadlock can occur, and the service may stop responding.

Requirements

Minimum suppor ted client Windows Vista [desktop apps | UWP apps]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps | UWP apps]

Target Platform Windows

Header ncrypt.h

Librar y Ncrypt.lib

DLL Ncrypt.dll

See also
NCryptEncrypt
 NCryptDeleteKey function (ncrypt.h)
7/2/2022 • 2 minutes to read • Edit Online

The NCr yptDeleteKey function deletes a CNG key.

Syntax
SECURITY_STATUS NCryptDeleteKey(
[in] NCRYPT_KEY_HANDLE hKey,
[in] DWORD dwFlags
);

Parameters
[in] hKey

The handle of the key to delete. This handle is obtained by using the NCryptOpenKey function.

Note The NCr yptDeleteKey function frees the handle. Applications must not use the handle or attempt to call the
NCryptFreeObject function on it after calling the NCr yptDeleteKey function.

[in] dwFlags

Flags that modify function behavior. This can be zero or a combination of values that is specific to each key
storage provider.

VA L UE M EA N IN G

Requests that the key service provider (KSP) not display any
NCRYPT_SILENT_FL AG user interface. If the provider must display the UI to operate,
the call fails and the KSP should set the
NTE_SILENT_CONTEXT error code as the last error.

Return value
Returns a status code that indicates the success or failure of the function.
Possible return codes include, but are not limited to, the following.

RET URN C O DE DESC RIP T IO N

The function was successful.

ERROR_SUCCESS

The dwFlags parameter contains a value that is not valid.

NTE_BAD_FL AGS
 The hKey parameter is not valid.
NTE_INVALID_HANDLE

Remarks
A service must not call this function from its StartService Function. If a service calls this function from its
StartService function, a deadlock can occur, and the service may stop responding.

Requirements

Minimum suppor ted client Windows Vista [desktop apps | UWP apps]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps | UWP apps]

Target Platform Windows

Header ncrypt.h

Librar y Ncrypt.lib

DLL Ncrypt.dll

See also
NCryptOpenKey
 NCryptDeriveKey function (ncrypt.h)
7/2/2022 • 6 minutes to read • Edit Online

The NCr yptDeriveKey function derives a key from a secret agreement value. This function is intended to be
used as part of a secret agreement procedure using persisted secret agreement keys. To derive key material by
using a persisted secret instead, use the NCryptKeyDerivation function.

Syntax
SECURITY_STATUS NCryptDeriveKey(
[in] NCRYPT_SECRET_HANDLE hSharedSecret,
[in] LPCWSTR pwszKDF,
[in, optional] NCryptBufferDesc *pParameterList,
[out, optional] PBYTE pbDerivedKey,
[in] DWORD cbDerivedKey,
[out] DWORD *pcbResult,
[in] ULONG dwFlags
);

Parameters
[in] hSharedSecret

The secret agreement handle to create the key from. This handle is obtained from the NCryptSecretAgreement
function.
[in] pwszKDF

A pointer to a null-terminated Unicode string that identifies the key derivation function (KDF) to use to derive
the key. This can be one of the following strings.
BCRYPT_KDF_HASH (L"HASH")
Use the hash key derivation function.
If the cbDerivedKey parameter is less than the size of the derived key, this function will only copy the specified
number of bytes to the pbDerivedKey buffer. If the cbDerivedKey parameter is greater than the size of the
derived key, this function will copy the key to the pbDerivedKey buffer and set the variable pointed to by the
pcbResult to the actual number of bytes copied.
The parameters identified by the pParameterList parameter either can or must contain the following parameters,
as indicated by the Required or optional column.

PA RA M ET ER DESC RIP T IO N REQ UIRED O R O P T IO N A L

KDF_HASH_ALGORITHM A null-terminated Unicode string that Optional

identifies the hash algorithm to use.
This can be one of the standard hash
algorithm identifiers from CNG
Algorithm Identifiers or the identifier
for another registered hash algorithm.
If this parameter is not specified,
the SHA1 hash algorithm is used.
 KDF_SECRET_PREPEND A value to add to the beginning of the Optional
message input to the hash function.
For more information, see Remarks.

KDF_SECRET_APPEND A value to add to the end of the Optional

message input to the hash function.
For more information, see Remarks.

The call to the KDF is made as shown in the following pseudocode.

KDF-Prepend = KDF_SECRET_PREPEND[0] +
KDF_SECRET_PREPEND[1] +
... +
KDF_SECRET_PREPEND[n]

KDF-Append = KDF_SECRET_APPEND[0] +
KDF_SECRET_APPEND[1] +
... +
KDF_SECRET_APPEND[n]

KDF-Output = Hash(
KDF-Prepend +
hSharedSecret +
KDF-Append)

BCRYPT_KDF_HMAC (L"HMAC")
Use the Hash-Based Message Authentication Code (HMAC) key derivation function.
If the cbDerivedKey parameter is less than the size of the derived key, this function will only copy the specified
number of bytes to the pbDerivedKey buffer. If the cbDerivedKey parameter is greater than the size of the
derived key, this function will copy the key to the pbDerivedKey buffer and set the variable pointed to by the
pcbResult to the actual number of bytes copied.
The parameters identified by the pParameterList parameter either can or must contain the following parameters,
as indicated by the Required or optional column.

PA RA M ET ER DESC RIP T IO N REQ UIRED O R O P T IO N A L

KDF_HASH_ALGORITHM A null-terminated Unicode string that Optional

identifies the hash algorithm to use.
This can be one of the standard hash
algorithm identifiers from CNG
Algorithm Identifiers or the identifier
for another registered hash algorithm.
If this parameter is not specified,
the SHA1 hash algorithm is used.

KDF_HMAC_KEY The key to use for the pseudo-random Optional

function (PRF).

KDF_SECRET_PREPEND A value to add to the beginning of the Optional

message input to the hash function.
For more information, see Remarks.

KDF_SECRET_APPEND A value to add to the end of the Optional

message input to the hash function.
For more information, see Remarks.
The call to the KDF is made as shown in the following pseudocode.

KDF-Prepend = KDF_SECRET_PREPEND[0] +
KDF_SECRET_PREPEND[1] +
... +
KDF_SECRET_PREPEND[n]

KDF-Append = KDF_SECRET_APPEND[0] +
KDF_SECRET_APPEND[1] +
... +
KDF_SECRET_APPEND[n]

KDF-Output = HMAC-Hash(
KDF_HMAC_KEY,
KDF-Prepend +
hSharedSecret +
KDF-Append)

BCRYPT_KDF_TLS_PRF (L"TLS_PRF")
Use the transport layer security (TLS) pseudo-random function (PRF) key derivation function. The size of the
derived key is always 48 bytes, so the cbDerivedKey parameter must be 48.
The parameters identified by the pParameterList parameter either can or must contain the following parameters,
as indicated by the Required or optional column.

PA RA M ET ER DESC RIP T IO N REQ UIRED O R O P T IO N A L

KDF_TLS_PRF_L ABEL An ANSI string that contains the PRF Required

label.

KDF_TLS_PRF_SEED The PRF seed. The seed must be 64 Required

bytes long.

The call to the KDF is made as shown in the following pseudocode.

KDF-Output = PRF(
hSharedSecret,
KDF_TLS_PRF_LABEL,
KDF_TLS_PRF_SEED)

BCRYPT_KDF_SP80056A_CONCAT (L"SP800_56A_CONCAT")
Use the SP800-56A key derivation function.
The parameters identified by the pParameterList parameter either can or must contain the following parameters,
as indicated by the Required or optional column. All parameter values are treated as opaque byte arrays.

PA RA M ET ER DESC RIP T IO N REQ UIRED O R O P T IO N A L

KDF_ALGORITHMID Specifies the AlgorithmID subfield of Required

the OtherInfo field in the SP800-56A
key derivation function. Indicates the
intended purpose of the derived key.
 KDF_PARTYUINFO Specifies the Par tyUInfo subfield of Required
the OtherInfo field in the SP800-56A
key derivation function. The field
contains public information
contributed by the initiator.

KDF_PARTYVINFO Specifies the Par tyVInfo subfield of Required

the OtherInfo field in the SP800-56A
key derivation function. The field
contains public information
contributed by the responder.

KDF_SUPPPUBINFO Specifies the SuppPubInfo subfield of Optional

the OtherInfo field in the SP800-56A
key derivation function. The field
contains public information known to
both initiator and responder.

KDF_SUPPPRIVINFO Specifies the SuppPrivInfo subfield of Optional

the OtherInfo field in the SP800-56A
key derivation function. It contains
private information known to both
initiator and responder, such as a
shared secret.

The call to the KDF is made as shown in the following pseudocode.

KDF-Output = SP_800-56A_KDF(
hSharedSecret,
KDF_ALGORITHMID,
KDF_PARTYUINFO,
KDF_PARTYVINFO,
KDF_SUPPPUBINFO,
KDF_SUPPPRIVINFO)

Windows Ser ver 2008, Windows Vista, Windows Ser ver 2003 and Windows XP: This value is not
supported.

[in, optional] pParameterList

The address of a NCryptBufferDesc structure that contains the KDF parameters. This parameter is optional and
can be NULL if it is not needed.
[out, optional] pbDerivedKey

The address of a buffer that receives the key. The cbDerivedKey parameter contains the size of this buffer. If this
parameter is NULL , this function will place the required size, in bytes, in the DWORD pointed to by the
pcbResult parameter.
[in] cbDerivedKey

The size, in bytes, of the pbDerivedKey buffer.

[out] pcbResult

A pointer to a DWORD that receives the number of bytes that were copied to the pbDerivedKey buffer. If the
pbDerivedKey parameter is NULL , this function will place the required size, in bytes, in the DWORD pointed to
by this parameter.
[in] dwFlags

A set of flags that modify the behavior of this function. This can be zero or the following value.

VA L UE M EA N IN G

KDF_USE_SECRET_AS_HMAC_KEY_FL AG
The secret agreement value will also serve as the HMAC key.
If this flag is specified, the KDF_HMAC_KEY parameter
should not be included in the set of parameters in the
pParameterList parameter. This flag is only used by the
BCRYPT_KDF_HMAC key derivation function.

Return value
Returns a status code that indicates the success or failure of the function.
Possible return codes include, but are not limited to, the following.

RET URN C O DE DESC RIP T IO N

The function was successful.

ERROR_SUCCESS

The hSharedSecret parameter is not valid.

NTE_INVALID_HANDLE

One or more parameters are not valid.

NTE_INVALID_PARAMETER

Remarks
The BCryptBufferDesc structure in the pParameterList parameter can contain more than one of the
KDF_SECRET_PREPEND and KDF_SECRET_APPEND parameters. If more than one of these parameters is
specified, the parameter values are concatenated in the order in which they are contained in the array before the
KDF is called. For example, assume the following parameter values are specified.

BYTE pbValue0[1] = {0x01};

BYTE pbValue1[2] = {0x04, 0x05};
BYTE pbValue2[3] = {0x10, 0x11, 0x12};
BYTE pbValue3[4] = {0x20, 0x21, 0x22, 0x23};

Parameter[0].type = KDF_SECRET_APPEND
Parameter[0].value = pbValue0;
Parameter[0].length = sizeof (pbValue0);
Parameter[1].type = KDF_SECRET_PREPEND
Parameter[1].value = pbValue1;
Parameter[1].length = sizeof (pbValue1);
Parameter[2].type = KDF_SECRET_APPEND
Parameter[2].value = pbValue2;
Parameter[2].length = sizeof (pbValue2);
Parameter[3].type = KDF_SECRET_PREPEND
Parameter[3].value = pbValue3;
Parameter[3].length = sizeof (pbValue3);

If the above parameter values are specified, the concatenated values to the actual KDF are as follows.
 Type: KDF_SECRET_PREPEND
Value: {0x04, 0x05, 0x20, 0x21, 0x22, 0x23}, length 6

Type: KDF_SECRET_APPEND
Value: {0x01, 0x10, 0x11, 0x12}, length 4

A service must not call this function from its StartService Function. If a service calls this function from its
StartService function, a deadlock can occur, and the service may stop responding.

Requirements

Minimum suppor ted client Windows Vista [desktop apps | UWP apps]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps | UWP apps]

Target Platform Windows

Header ncrypt.h

Librar y Ncrypt.lib

DLL Ncrypt.dll

See also
NCryptBufferDesc
 NCryptEncrypt function (ncrypt.h)
7/2/2022 • 3 minutes to read • Edit Online

The NCr yptEncr ypt function encrypts a block of data.

Syntax
SECURITY_STATUS NCryptEncrypt(
[in] NCRYPT_KEY_HANDLE hKey,
[in] PBYTE pbInput,
[in] DWORD cbInput,
[in, optional] VOID *pPaddingInfo,
[out] PBYTE pbOutput,
[in] DWORD cbOutput,
[out] DWORD *pcbResult,
[in] DWORD dwFlags
);

Parameters
[in] hKey

The handle of the key to use to encrypt the data.

[in] pbInput

The address of a buffer that contains the data to be encrypted. The cbInput parameter contains the size of the
data to encrypt. For more information, see Remarks.
[in] cbInput

The number of bytes in the pbInput buffer to encrypt.

[in, optional] pPaddingInfo

A pointer to a structure that contains padding information. The actual type of structure this parameter points to
depends on the value of the dwFlags parameter. This parameter is only used with asymmetric keys and must be
NULL otherwise.
[out] pbOutput

The address of a buffer that will receive the encrypted data produced by this function. The cbOutput parameter
contains the size of this buffer. For more information, see Remarks.
If this parameter is NULL , this function will calculate the size needed for the encrypted data and return the size
in the location pointed to by the pcbResult parameter.
[in] cbOutput

The size, in bytes, of the pbOutput buffer. This parameter is ignored if the pbOutput parameter is NULL .
[out] pcbResult

A pointer to a DWORD variable that receives the number of bytes copied to the pbOutput buffer. If pbOutput is
NULL , this receives the size, in bytes, required for the ciphertext.
[in] dwFlags

Flags that modify function behavior. The allowed set of flags depends on the type of key specified by the hKey
parameter.
If the key is an asymmetric key, this can be one of the following values.

VA L UE M EA N IN G

Do not use any padding. The pPaddingInfo parameter is not

NCRYPT_NO_PADDING_FL AG used.
If you specify the NCRYPT_NO_PADDING_FL AG ,
then the NCr yptEncr ypt function only encrypts the
first N bits, where N is the length of the key that was
passed as the hKey parameter. Any bits after the first N
bits are ignored.

Use the Optimal Asymmetric Encryption Padding (OAEP)

NCRYPT_PAD_OAEP_FL AG scheme. The pPaddingInfo parameter is a pointer to a
BCRYPT_OAEP_PADDING_INFO structure.

The data will be padded with a random number to round

NCRYPT_PAD_PKCS1_FL AG out the block size. The pPaddingInfo parameter is not used.

Requests that the key service provider (KSP) not display any
NCRYPT_SILENT_FL AG user interface. If the provider must display the UI to operate,
the call fails and the KSP should set the
NTE_SILENT_CONTEXT error code as the last error.

Return value
Returns a status code that indicates the success or failure of the function.
Possible return codes include, but are not limited to, the following.

RET URN C O DE DESC RIP T IO N

The function was successful.

ERROR_SUCCESS

The dwFlags parameter contains a value that is not valid.

NTE_BAD_FL AGS

The key identified by the hKey parameter has not been

NTE_BAD_KEY_STATE finalized or is incomplete.

The size specified by the cbOutput parameter is not large

NTE_BUFFER_TOO_SMALL enough to hold the encrypted data.

The hKey parameter is not valid.

NTE_INVALID_HANDLE

One or more parameters are not valid.

NTE_INVALID_PARAMETER
Remarks
The pbInput and pbOutput parameters can point to the same buffer. In this case, this function will perform the
encryption in place. It is possible that the encrypted data size will be larger than the unencrypted data size, so
the buffer must be large enough to hold the encrypted data.
A service must not call this function from its StartService Function. If a service calls this function from its
StartService function, a deadlock can occur, and the service may stop responding.

Requirements

Minimum suppor ted client Windows Vista [desktop apps | UWP apps]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps | UWP apps]

Target Platform Windows

Header ncrypt.h

Librar y Ncrypt.lib

DLL Ncrypt.dll
 NCryptEnumAlgorithms function (ncrypt.h)
7/2/2022 • 2 minutes to read • Edit Online

The NCr yptEnumAlgorithms function obtains the names of the algorithms that are supported by the
specified key storage provider.

Syntax
SECURITY_STATUS NCryptEnumAlgorithms(
[in] NCRYPT_PROV_HANDLE hProvider,
[in] DWORD dwAlgOperations,
[out] DWORD *pdwAlgCount,
[out] NCryptAlgorithmName **ppAlgList,
[in] DWORD dwFlags
);

Parameters
[in] hProvider

The handle of the key storage provider to enumerate the algorithms for. This handle is obtained with the
NCryptOpenStorageProvider function.
[in] dwAlgOperations

A set of values that determine which algorithm classes to enumerate. This can be zero or a combination of one
or more of the following values. If dwAlgOperations is zero, all algorithms are enumerated.

VA L UE M EA N IN G

Enumerate the cipher (symmetric encryption) algorithms.

NCRYPT_CIPHER_OPERATION
0x00000001

Enumerate the hashing algorithms.

NCRYPT_HASH_OPERATION
0x00000002

Enumerate the asymmetric encryption algorithms.

NCRYPT_ASYMMETRIC_ENCRYPTION_OPERATION
0x00000004

Enumerate the secret agreement algorithms.

NCRYPT_SECRET_AGREEMENT_OPERATION
0x00000008

Enumerate the digital signature algorithms.

NCRYPT_SIGNATURE_OPERATION
0x00000010

[out] pdwAlgCount
The address of a DWORD that receives the number of elements in the ppAlgList array.
[out] ppAlgList

The address of an NCryptAlgorithmName structure pointer that receives an array of the registered algorithm
names. The variable pointed to by the pdwAlgCount parameter receives the number of elements in this array.
When this memory is no longer needed, it must be freed by passing this pointer to the NCryptFreeBuffer
function.
[in] dwFlags

Flags that modify function behavior. This can be zero (0) or the following value.

VA L UE M EA N IN G

Requests that the key service provider (KSP) not display any
NCRYPT_SILENT_FL AG user interface. If the provider must display the UI to operate,
the call fails and the KSP should set the
NTE_SILENT_CONTEXT error code as the last error.

Return value
Returns a status code that indicates the success or failure of the function.
Possible return codes include, but are not limited to, the following.

RET URN C O DE DESC RIP T IO N

The function was successful.

ERROR_SUCCESS

The dwFlags parameter contains a value that is not valid.

NTE_BAD_FL AGS

The hProvider parameter is not valid.

NTE_INVALID_HANDLE

One or more parameters are not valid.

NTE_INVALID_PARAMETER

A memory allocation failure occurred.

NTE_NO_MEMORY

Remarks
A service must not call this function from its StartService Function. If a service calls this function from its
StartService function, a deadlock can occur, and the service may stop responding.

Requirements

Minimum suppor ted client Windows Vista [desktop apps | UWP apps]
Minimum suppor ted ser ver Windows Server 2008 [desktop apps | UWP apps]

Target Platform Windows

Header ncrypt.h

Librar y Ncrypt.lib

DLL Ncrypt.dll
 NCryptEnumKeys function (ncrypt.h)
7/2/2022 • 2 minutes to read • Edit Online

The NCr yptEnumKeys function obtains the names of the keys that are stored by the provider.

Syntax
SECURITY_STATUS NCryptEnumKeys(
[in] NCRYPT_PROV_HANDLE hProvider,
[in, optional] LPCWSTR pszScope,
[out] NCryptKeyName **ppKeyName,
[in, out] PVOID *ppEnumState,
[in] DWORD dwFlags
);

Parameters
[in] hProvider

The handle of the key storage provider to enumerate the keys for. This handle is obtained with the
NCryptOpenStorageProvider function.
[in, optional] pszScope

This parameter is not currently used and must be NULL .

[out] ppKeyName

The address of a pointer to an NCryptKeyName structure that receives the name of the retrieved key. When the
application has finished using this memory, free it by calling the NCryptFreeBuffer function.
[in, out] ppEnumState

The address of a VOID pointer that receives enumeration state information that is used in subsequent calls to
this function. This information only has meaning to the key storage provider and is opaque to the caller. The key
storage provider uses this information to determine which item is next in the enumeration. If the variable
pointed to by this parameter contains NULL , the enumeration is started from the beginning.
When this memory is no longer needed, it must be freed by passing this pointer to the NCryptFreeBuffer
function.
[in] dwFlags

Flags that modify function behavior. This can be zero or a combination of one or more of the following values.

VA L UE M EA N IN G

Enumerate the keys for the local computer. If this flag is not
NCRYPT_MACHINE_KEY_FL AG present, the current user keys are enumerated.
 Requests that the key service provider (KSP) not display any
NCRYPT_SILENT_FL AG user interface. If the provider must display the UI to operate,
the call fails and the KSP should set the
NTE_SILENT_CONTEXT error code as the last error.

Return value
Returns a status code that indicates the success or failure of the function.
Possible return codes include, but are not limited to, the following.

RET URN C O DE DESC RIP T IO N

The function was successful.

ERROR_SUCCESS

The dwFlags parameter contains a value that is not valid.

NTE_BAD_FL AGS

The hProvider parameter is not valid.

NTE_INVALID_HANDLE

One or more parameters are not valid.

NTE_INVALID_PARAMETER

A memory allocation failure occurred.

NTE_NO_MEMORY

The end of the enumeration has been reached.

NTE_NO_MORE_ITEMS

The dwFlags parameter contains the

NTE_SILENT_CONTEXT NCRYPT_SILENT_FL AG flag, but the key being
enumerated requires user interaction.

Remarks
This function retrieves only one item each time it is called. The state of the enumeration is stored in the variable
pointed to by the ppEnumState parameter, so this must be preserved between calls to this function. When the
last key stored by the provider has been retrieved, this function will return NTE_NO_MORE_ITEMS the next
time it is called. To start the enumeration over, set the variable pointed to by the ppEnumState parameter to
NULL , free the memory pointed to by the ppKeyName parameter, if it is not NULL , and call this function again.
A service must not call this function from its StartService Function. If a service calls this function from its
StartService function, a deadlock can occur, and the service may stop responding.

Requirements

Minimum suppor ted client Windows Vista [desktop apps | UWP apps]
Minimum suppor ted ser ver Windows Server 2008 [desktop apps | UWP apps]

Target Platform Windows

Header ncrypt.h

Librar y Ncrypt.lib

DLL Ncrypt.dll
 NCryptEnumStorageProviders function (ncrypt.h)
7/2/2022 • 2 minutes to read • Edit Online

The NCr yptEnumStorageProviders function obtains the names of the registered key storage providers.

Syntax
SECURITY_STATUS NCryptEnumStorageProviders(
[out] DWORD *pdwProviderCount,
[out] NCryptProviderName **ppProviderList,
[in] DWORD dwFlags
);

Parameters
[out] pdwProviderCount

The address of a DWORD to receive the number of elements in the ppProviderList array.
[out] ppProviderList

The address of an NCryptProviderName structure pointer to receive an array of the registered key storage
provider names. The variable pointed to by the pdwProviderCount parameter receives the number of elements
in this array.
When this memory is no longer needed, free it by passing this pointer to the NCryptFreeBuffer function.
[in] dwFlags

Flags that modify function behavior. This can be zero (0) or the following value.

VA L UE M EA N IN G

Requests that the key service provider (KSP) not display any
NCRYPT_SILENT_FL AG user interface. If the provider must display the UI to operate,
the call fails and the KSP should set the
NTE_SILENT_CONTEXT error code as the last error.

Return value
Returns a status code that indicates the success or failure of the function.
Possible return codes include, but are not limited to, the following.

RET URN C O DE DESC RIP T IO N

The function was successful.

ERROR_SUCCESS

The dwFlags parameter contains a value that is not valid.

NTE_BAD_FL AGS
 One or more parameters are not valid.
NTE_INVALID_PARAMETER

A memory allocation failure occurred.

NTE_NO_MEMORY

Remarks
A service must not call this function from its StartService Function. If a service calls this function from its
StartService function, a deadlock can occur, and the service may stop responding.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header ncrypt.h

Librar y Ncrypt.lib

DLL Ncrypt.dll

See also
NCryptFreeBuffer
 NCryptExportKey function (ncrypt.h)
7/2/2022 • 5 minutes to read • Edit Online

The NCr yptExpor tKey function exports a CNG key to a memory BLOB.

Syntax
SECURITY_STATUS NCryptExportKey(
[in] NCRYPT_KEY_HANDLE hKey,
[in, optional] NCRYPT_KEY_HANDLE hExportKey,
[in] LPCWSTR pszBlobType,
[in, optional] NCryptBufferDesc *pParameterList,
[out, optional] PBYTE pbOutput,
[in] DWORD cbOutput,
[out] DWORD *pcbResult,
[in] DWORD dwFlags
);

Parameters
[in] hKey

A handle of the key to export.

[in, optional] hExportKey

A handle to a cryptographic key of the destination user. The key data within the exported key BLOB is encrypted
by using this key. This ensures that only the destination user is able to make use of the key BLOB.
[in] pszBlobType

A null-terminated Unicode string that contains an identifier that specifies the type of BLOB to export. This can be
one of the following values.
BCRYPT_DH_PRIVATE_BLOB
Export a Diffie-Hellman public/private key pair. The pbOutput buffer receives a BCRYPT_DH_KEY_BLOB structure
immediately followed by the key data.
BCRYPT_DH_PUBLIC_BLOB
Export a Diffie-Hellman public key. The pbOutput buffer receives a BCRYPT_DH_KEY_BLOB structure
immediately followed by the key data.
BCRYPT_DSA_PRIVATE_BLOB
Export a DSA public/private key pair. The pbOutput buffer receives a BCRYPT_DSA_KEY_BLOB structure
immediately followed by the key data.
BCRYPT_DSA_PUBLIC_BLOB
Export a DSA public key. The pbOutput buffer receives a BCRYPT_DSA_KEY_BLOB structure immediately
followed by the key data.
BCRYPT_ECCPRIVATE_BLOB
Export an elliptic curve cryptography (ECC) private key. The pbOutput buffer receives a BCRYPT_ECCKEY_BLOB
structure immediately followed by the key data.
BCRYPT_ECCPUBLIC_BLOB
Export an ECC public key. The pbOutput buffer receives a BCRYPT_ECCKEY_BLOB structure immediately followed
by the key data.
BCRYPT_PUBLIC_KEY_BLOB
Export a generic public key of any type. The type of key in this BLOB is determined by the Magic member of the
BCRYPT_KEY_BLOB structure.
BCRYPT_PRIVATE_KEY_BLOB
Export a generic private key of any type. The private key does not necessarily contain the public key. The type of
key in this BLOB is determined by the Magic member of the BCRYPT_KEY_BLOB structure.
BCRYPT_RSAFULLPRIVATE_BLOB
Export a full RSA public/private key pair. The pbOutput buffer receives a BCRYPT_RSAKEY_BLOB structure
immediately followed by the key data. This BLOB will include additional key material compared to the
BCRYPT_RSAPRIVATE_BLOB type.
BCRYPT_RSAPRIVATE_BLOB
Export an RSA public/private key pair. The pbOutput buffer receives a BCRYPT_RSAKEY_BLOB structure
immediately followed by the key data.
BCRYPT_RSAPUBLIC_BLOB
Export an RSA public key. The pbOutput buffer receives a BCRYPT_RSAKEY_BLOB structure immediately
followed by the key data.
LEGACY_DH_PRIVATE_BLOB
Export a legacy Diffie-Hellman Version 3 Private Key BLOB that contains a Diffie-Hellman public/private key pair
that can be imported by using CryptoAPI.
LEGACY_DH_PUBLIC_BLOB
Export a legacy Diffie-Hellman Version 3 Private Key BLOB that contains a Diffie-Hellman public key that can be
imported by using CryptoAPI.
LEGACY_DSA_PRIVATE_BLOB
Export a DSA public/private key pair in a form that can be imported by using CryptoAPI.
LEGACY_DSA_PUBLIC_BLOB
Export a DSA public key in a form that can be imported by using CryptoAPI.
LEGACY_RSAPRIVATE_BLOB
Export an RSA public/private key pair in a form that can be imported by using CryptoAPI.
LEGACY_RSAPUBLIC_BLOB
Export an RSA public key in a form that can be imported by using CryptoAPI.
NCRYPT_CIPHER_KEY_BLOB
Export a cipher key in a NCRYPT_KEY_BLOB_HEADER structure.
Windows 8 and Windows Ser ver 2012: Support for this value begins.
NCRYPT_OPAQUETRANSPORT_BLOB
Export a key in a format that is specific to a single CSP and is suitable for transport. Opaque BLOBs are not
transferable and must be imported by using the same CSP that generated the BLOB.
NCRYPT_PKCS7_ENVELOPE_BLOB
Export a PKCS #7 envelope BLOB. The parameters identified by the pParameterList parameter either can or must
contain the following parameters, as indicated by the Required or optional column.

PA RA M ET ER REQ UIRED O R O P T IO N A L
 NCRYPTBUFFER_CERT_BLOB Required

NCRYPTBUFFER_PKCS_ALG_OID Required

NCRYPTBUFFER_PKCS_ALG_PARAM Optional

NCRYPT_PKCS8_PRIVATE_KEY_BLOB
Export a PKCS #8 private key BLOB. The parameters identified by the pParameterList parameter either can or
must contain the following parameters, as indicated by the Required or optional column.

PA RA M ET ER REQ UIRED O R O P T IO N A L

NCRYPTBUFFER_PKCS_ALG_OID Optional

NCRYPTBUFFER_PKCS_ALG_PARAM Optional

NCRYPTBUFFER_PKCS_SECRET Optional

NCRYPT_PROTECTED_KEY_BLOB
Export a protected key in a NCRYPT_KEY_BLOB_HEADER structure.
Windows 8 and Windows Ser ver 2012: Support for this value begins.
[in, optional] pParameterList

The address of an NCryptBufferDesc structure that receives parameter information for the key. This parameter
can be NULL if this information is not needed.
[out, optional] pbOutput

The address of a buffer that receives the key BLOB. The cbOutput parameter contains the size of this buffer. If
this parameter is NULL , this function will place the required size, in bytes, in the DWORD pointed to by the
pcbResult parameter.
[in] cbOutput

The size, in bytes, of the pbOutput buffer.

[out] pcbResult

The address of a DWORD variable that receives the number of bytes copied to the pbOutput buffer. If the
pbOutput parameter is NULL , this function will place the required size, in bytes, in the DWORD pointed to by
this parameter.
[in] dwFlags

Flags that modify function behavior. This can be zero or a combination of one or more of the following values.
The set of valid flags is specific to each key storage provider. The following flag applies to all providers.

VA L UE M EA N IN G
 Requests that the key service provider (KSP) not display any
NCRYPT_SILENT_FL AG user interface. If the provider must display the UI to operate,
the call fails and the KSP should set the
NTE_SILENT_CONTEXT error code as the last error.

Return value
Returns a status code that indicates the success or failure of the function.
Possible return codes include, but are not limited to, the following.

RET URN C O DE DESC RIP T IO N

The function was successful.

ERROR_SUCCESS

The dwFlags parameter contains a value that is not valid.

NTE_BAD_FL AGS

The key specified by the hKey parameter is not valid. The

NTE_BAD_KEY_STATE most common cause of this error is that the key was not
completed by using the NCryptFinalizeKey function.

The key specified by the hKey parameter cannot be exported

NTE_BAD_TYPE into the BLOB type specified by the pszBlobType parameter.

The hKey or the hExportKey parameter is not valid.

NTE_INVALID_HANDLE

One or more parameters are not valid.

NTE_INVALID_PARAMETER

Remarks
A service must not call this function from its StartService Function. If a service calls this function from its
StartService function, a deadlock can occur, and the service may stop responding.

Requirements

Minimum suppor ted client Windows Vista [desktop apps | UWP apps]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps | UWP apps]

Target Platform Windows

Header ncrypt.h

Librar y Ncrypt.lib

DLL Ncrypt.dll
See also
NCryptBuffer
 NCryptFinalizeKey function (ncrypt.h)
7/2/2022 • 2 minutes to read • Edit Online

The NCr yptFinalizeKey function completes a CNG key storage key. The key cannot be used until this function
has been called.

Syntax
SECURITY_STATUS NCryptFinalizeKey(
[in] NCRYPT_KEY_HANDLE hKey,
[in] DWORD dwFlags
);

Parameters
[in] hKey

The handle of the key to complete. This handle is obtained by calling the NCryptCreatePersistedKey function.
[in] dwFlags

Flags that modify function behavior. This can be zero or a combination of one or more of the following values.

VA L UE M EA N IN G

Do not validate the public portion of the key pair. This flag
NCRYPT_NO_KEY_VALIDATION only applies to public/private key pairs.

Also save the key in legacy storage. This allows the key to be
NCRYPT_WRITE_KEY_TO_LEGACY_STORE_FL AG used with CryptoAPI. This flag only applies to RSA keys.

Requests that the key service provider (KSP) not display any
NCRYPT_SILENT_FL AG user interface. If the provider must display the UI to operate,
the call fails and the KSP should set the
NTE_SILENT_CONTEXT error code as the last error.

Return value
Returns a status code that indicates the success or failure of the function.
Possible return codes include, but are not limited to, the following.

RET URN C O DE DESC RIP T IO N

The function was successful.

ERROR_SUCCESS

The dwFlags parameter contains a value that is not valid.

NTE_BAD_FL AGS
 The hKey parameter is not valid.
NTE_INVALID_HANDLE

Remarks
A service must not call this function from its StartService Function. If a service calls this function from its
StartService function, a deadlock can occur, and the service may stop responding.

Requirements

Minimum suppor ted client Windows Vista [desktop apps | UWP apps]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps | UWP apps]

Target Platform Windows

Header ncrypt.h

Librar y Ncrypt.lib

DLL Ncrypt.dll
 NCryptFreeBuffer function (ncrypt.h)
7/2/2022 • 2 minutes to read • Edit Online

The NCr yptFreeBuffer function releases a block of memory allocated by a CNG key storage provider.

Syntax
SECURITY_STATUS NCryptFreeBuffer(
[in] PVOID pvInput
);

Parameters
[in] pvInput

The address of the memory to be released.

Return value
Returns a status code that indicates the success or failure of the function.
Possible return codes include, but are not limited to, the following.

RET URN C O DE DESC RIP T IO N

The function was successful.

ERROR_SUCCESS

The pvInput parameter is not valid.

NTE_INVALID_PARAMETER

Remarks
A service must not call this function from its StartService Function. If a service calls this function from its
StartService function, a deadlock can occur, and the service may stop responding.

Requirements

Minimum suppor ted client Windows Vista [desktop apps | UWP apps]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps | UWP apps]

Target Platform Windows

Header ncrypt.h
Librar y Ncrypt.lib

DLL Ncrypt.dll
 NCryptFreeObject function (ncrypt.h)
7/2/2022 • 2 minutes to read • Edit Online

The NCr yptFreeObject function frees a CNG key storage object.

Syntax
SECURITY_STATUS NCryptFreeObject(
[in] NCRYPT_HANDLE hObject
);

Parameters
[in] hObject

The handle of the object to free. This can be either a provider handle (NCRYPT_PROV_HANDLE ) or a key
handle (NCRYPT_KEY_HANDLE ).

Return value
Returns a status code that indicates the success or failure of the function.
Possible return codes include, but are not limited to, the following.

RET URN C O DE DESC RIP T IO N

The function was successful.

ERROR_SUCCESS

The handle in the hObject parameter is not valid.

NTE_INVALID_HANDLE

Remarks
A service must not call this function from its StartService Function. If a service calls this function from its
StartService function, a deadlock can occur, and the service may stop responding.

Requirements

Minimum suppor ted client Windows Vista [desktop apps | UWP apps]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps | UWP apps]

Target Platform Windows

Header ncrypt.h
 Librar y Ncrypt.lib

DLL Ncrypt.dll

See also
NCryptOpenStorageProvider
 NCryptGetProperty function (ncrypt.h)
7/2/2022 • 2 minutes to read • Edit Online

The NCr yptGetProper ty function retrieves the value of a named property for a key storage object.

Syntax
SECURITY_STATUS NCryptGetProperty(
[in] NCRYPT_HANDLE hObject,
[in] LPCWSTR pszProperty,
[out] PBYTE pbOutput,
[in] DWORD cbOutput,
[out] DWORD *pcbResult,
[in] DWORD dwFlags
);

Parameters
[in] hObject

The handle of the object to get the property for. This can be a provider handle (NCRYPT_PROV_HANDLE ) or a
key handle (NCRYPT_KEY_HANDLE ).
[in] pszProperty

A pointer to a null-terminated Unicode string that contains the name of the property to retrieve. This can be one
of the predefined Key Storage Property Identifiers or a custom property identifier.
[out] pbOutput

The address of a buffer that receives the property value. The cbOutput parameter contains the size of this buffer.
To calculate the size required for the buffer, set this parameter to NULL . The size, in bytes, required is returned in
the location pointed to by the pcbResult parameter.
[in] cbOutput

The size, in bytes, of the pbOutput buffer.

[out] pcbResult

A pointer to a DWORD variable that receives the number of bytes that were copied to the pbOutput buffer.
If the pbOutput parameter is NULL , the size, in bytes, required for the buffer is placed in the location pointed to
by this parameter.
[in] dwFlags

Flags that modify function behavior. This can be zero or the following value.

VA L UE M EA N IN G
 Ignore any built in values for this property and only retrieve
NCRYPT_PERSIST_ONLY_FL AG the user-persisted properties of the key. The maximum size
of the data for any persisted property is
NCRYPT_MAX_PROPERTY_DATA bytes.

Requests that the key service provider (KSP) not display any
NCRYPT_SILENT_FL AG user interface. If the provider must display the UI to operate,
the call fails and the KSP should set the
NTE_SILENT_CONTEXT error code as the last error.

For the NCRYPT_SECURITY_DESCR_PROPERTY property, this parameter must also contain one of the
following values, which identifies the part of the security descriptor to retrieve.

VA L UE M EA N IN G

Retrieve the security identifier (SID) of the object's owner. Use

OWNER_SECURITY_INFORMATION the GetSecurityDescriptorOwner function to obtain the
owner SID from the SECURITY_DESCRIPTOR structure.

Retrieve the SID of the object's primary group. Use the

GROUP_SECURITY_INFORMATION GetSecurityDescriptorGroup function to obtain the group
SID from the SECURITY_DESCRIPTOR structure.

Retrieve the discretionary access control list (DACL). Use the

DACL_SECURITY_INFORMATION GetSecurityDescriptorSacl function to obtain the DACL from
the SECURITY_DESCRIPTOR structure.

Retrieve the system access control list (SACL). Use the

SACL_SECURITY_INFORMATION GetSecurityDescriptorDacl function to obtain the SACL from
the SECURITY_DESCRIPTOR structure.

Return value
Returns a status code that indicates the success or failure of the function.
Possible return codes include, but are not limited to, the following.

RET URN C O DE DESC RIP T IO N

The function was successful.

ERROR_SUCCESS

The dwFlags parameter contains a value that is not valid.

NTE_BAD_FL AGS

The hObject parameter is not valid.

NTE_INVALID_HANDLE

One or more parameters are not valid.

NTE_INVALID_PARAMETER

A memory allocation failure occurred.

NTE_NO_MEMORY
 The specified property is not supported for the object.
NTE_NOT_SUPPORTED

Remarks
A service must not call this function from its StartService Function. If a service calls this function from its
StartService function, a deadlock can occur, and the service may stop responding.

Requirements

Minimum suppor ted client Windows Vista [desktop apps | UWP apps]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps | UWP apps]

Target Platform Windows

Header ncrypt.h

Librar y Ncrypt.lib

DLL Ncrypt.dll
 NCryptImportKey function (ncrypt.h)
7/2/2022 • 4 minutes to read • Edit Online

The NCr yptImpor tKey function imports a Cryptography API: Next Generation (CNG) key from a memory
BLOB.

Syntax
SECURITY_STATUS NCryptImportKey(
[in] NCRYPT_PROV_HANDLE hProvider,
[in, optional] NCRYPT_KEY_HANDLE hImportKey,
[in] LPCWSTR pszBlobType,
[in, optional] NCryptBufferDesc *pParameterList,
[out] NCRYPT_KEY_HANDLE *phKey,
[in] PBYTE pbData,
[in] DWORD cbData,
[in] DWORD dwFlags
);

Parameters
[in] hProvider

The handle of the key storage provider.

[in, optional] hImportKey

The handle of the cryptographic key with which the key data within the imported key BLOB was encrypted. This
must be a handle to the same key that was passed in the hExportKey parameter of the NCryptExportKey
function. If this parameter is NULL , the key BLOB is assumed to not be encrypted.
[in] pszBlobType

A null-terminated Unicode string that contains an identifier that specifies the format of the key BLOB. These
formats are specific to a particular key storage provider. For the BLOB formats supported by Microsoft
providers, see Remarks.
[in, optional] pParameterList

The address of an NCryptBufferDesc structure that points to an array of buffers that contain parameter
information for the key.
[out] phKey

The address of an NCRYPT_KEY_HANDLE variable that receives the handle of the key. When you have finished
using this handle, release it by passing it to the NCryptFreeObject function.
[in] pbData

The address of a buffer that contains the key BLOB to be imported. The cbData parameter contains the size of
this buffer.
[in] cbData

The size, in bytes, of the pbData buffer.

[in] dwFlags

Flags that modify function behavior. This can be zero or a combination of one or more of the following values.
The set of valid flags is specific to each key storage provider.

VA L UE M EA N IN G

Requests that the key service provider (KSP) not display any
NCRYPT_SILENT_FL AG user interface. If the provider must display the UI to operate,
the call fails and the KSP should set the
NTE_SILENT_CONTEXT error code as the last error.

Return value
Returns a status code that indicates the success or failure of the function.
Possible return codes include, but are not limited to, the following.

RET URN C O DE DESC RIP T IO N

The function was successful.

ERROR_SUCCESS

The dwFlags parameter contains a value that is not valid.

NTE_BAD_FL AGS

A key with the specified name already exists and the

NTE_EXISTS NCRYPT_OVERWRITE_KEY_FL AG was not specified.

The hProvider parameter is not valid.

NTE_INVALID_HANDLE

One or more parameters are not valid.

NTE_INVALID_PARAMETER

A memory allocation failure occurred.

NTE_NO_MEMORY

Remarks
A service must not call this function from its StartService Function. If a service calls this function from its
StartService function, a deadlock can occur, and the service may stop responding.
The following sections describe behaviors specific to the Microsoft key storage providers:
Microsoft Software KSP
Microsoft Smar t Card KSP
Microsoft Software KSP
The following constants are supported by the Microsoft software KSP for the pszBlobType parameter.
If a key name is not supplied, the Microsoft Software KSP treats the key as ephemeral and does not store it
persistently. For the NCRYPT_OPAQUETRANSPORT_BLOB type, the key name is stored within the BLOB when
it is exported. For other BLOB formats, the name can be supplied in an NCRYPTBUFFER_PKCS_KEY_NAME
buffer parameter within the pParameterList parameter.
On Windows Server 2008 and Windows Vista, only keys imported as PKCS #7 envelope BLOBs
(NCRYPT_PKCS7_ENVELOPE_BLOB ) or PKCS #8 private key BLOBs (NCRYPT_PKCS8_PRIVATE_KEY_BLOB )
can be persisted by using the above method. To persist keys imported through other BLOB types on these
platforms, use the method documented in Key Import and Export.
The following flags are supported by this KSP.

T ERM DESC RIP T IO N

NCRYPT_NO_KEY_VALIDATION Do not validate the public portion of the key pair. This flag
only applies to public/private key pairs.

NCRYPT_DO_NOT_FINALIZE_FLAG Do not finalize the key. This option is useful when you need
to add or modify properties of the key after importing it.
You must finalize the key before it can be used by passing
the key handle to the NCryptFinalizeKey function. This flag is
supported for the private keys PKCS #7 and PKCS #8 but
not public keys.

NCRYPT_MACHINE_KEY_FLAG The key applies to the local computer. If this flag is not
present, the key applies to the current user.

NCRYPT_OVERWRITE_KEY_FLAG If a key already exists in the container with the specified

name, the existing key will be overwritten. If this flag is not
specified and a key with the specified name already exists,
this function will return NTE_EXISTS.

NCRYPT_WRITE_KEY_TO_LEGACY_STORE_FLAG Also save the key in legacy storage. This allows the key to be
used with the CryptoAPI. This flag only applies to RSA keys.

Microsoft Smart Card KSP

The set of key BLOB formats and flags supported by this KSP is identical to the set supported by the Microsoft
Software KSP.
On Windows Server 2008 and Windows Vista, the Microsoft Smart Card KSP imports all keys into the Microsoft
Software KSP. Thus, keys cannot be persisted on to a smart card by using this API, and the guidance in the above
section applies when trying to persist keys within the Microsoft Software KSP.
On Windows Server 2008 R2 and Windows 7, the Microsoft Smart Card Key Storage Provider can import a
private key to a smart card, provided the following conditions are met:
The key container name on the card is valid.
Importing private keys is supported by the smart card.
The following two registry keys are set to a DWORD of 0x1:
HKLM \SOFTWARE \Microsoft \Cr yptography \Defaults \Provider \Microsoft Base Smar t Card
Cr ypto Provider \AllowPrivateExchangeKeyImpor t
HKLM \SOFTWARE \Microsoft \Cr yptography \Defaults \Provider \Microsoft Base Smar t Card
Cr ypto Provider \AllowPrivateSignatureKeyImpor t
If the key container name is NULL , the Microsoft Smart Card KSP treats the key as ephemeral and imports it
into the Microsoft Software KSP.

Requirements
 Minimum suppor ted client Windows Vista [desktop apps | UWP apps]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps | UWP apps]

Target Platform Windows

Header ncrypt.h

Librar y Ncrypt.lib

DLL Ncrypt.dll

See also
NCryptBuffer
 NCryptIsAlgSupported function (ncrypt.h)
7/2/2022 • 2 minutes to read • Edit Online

The NCr yptIsAlgSuppor ted function determines if a CNG key storage provider supports a specific
cryptographic algorithm.

Syntax
SECURITY_STATUS NCryptIsAlgSupported(
[in] NCRYPT_PROV_HANDLE hProvider,
[in] LPCWSTR pszAlgId,
[in] DWORD dwFlags
);

Parameters
[in] hProvider

The handle of the key storage provider. This handle is obtained with the NCryptOpenStorageProvider function.
[in] pszAlgId

A pointer to a null-terminated Unicode string that identifies the cryptographic algorithm in question. This can be
one of the standard CNG Algorithm Identifiers or the identifier for another registered algorithm.
[in] dwFlags

Flags that modify function behavior. This can be zero (0) or the following value.

VA L UE M EA N IN G

Requests that the key service provider (KSP) not display any
NCRYPT_SILENT_FL AG user interface. If the provider must display the UI to operate,
the call fails and the KSP should set the
NTE_SILENT_CONTEXT error code as the last error.

Return value
Returns a status code that indicates the success or failure of the function.
Possible return codes include, but are not limited to, the following.

RET URN C O DE DESC RIP T IO N

The provider supports the specified algorithm.

ERROR_SUCCESS

The dwFlags parameter contains one or more flags that are

NTE_BAD_FL AGS not supported.
 The handle specified by the hProvider parameter is not valid.
NTE_INVALID_HANDLE

One or more parameters are not valid.

NTE_INVALID_PARAMETER

The provider does not support the specified algorithm.

NTE_NOT_SUPPORTED

Remarks
If the provider supports the algorithm, this function returns ERROR_SUCCESS . If the provider does not
support the algorithm, and no other errors occurred, this function returns NTE_NOT_SUPPORTED .
A service must not call this function from its StartService Function. If a service calls this function from its
StartService function, a deadlock can occur, and the service may stop responding.

Requirements

Minimum suppor ted client Windows Vista [desktop apps | UWP apps]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps | UWP apps]

Target Platform Windows

Header ncrypt.h

Librar y Ncrypt.lib

DLL Ncrypt.dll
 NCryptIsKeyHandle function (ncrypt.h)
7/2/2022 • 2 minutes to read • Edit Online

The NCr yptIsKeyHandle function determines if the specified handle is a CNG key handle.

Syntax
BOOL NCryptIsKeyHandle(
[in] NCRYPT_KEY_HANDLE hKey
);

Parameters
[in] hKey

The handle of the key to test.

Return value
Returns a nonzero value if the handle is a key handle or zero otherwise.

Remarks
A service must not call this function from its StartService Function. If a service calls this function from its
StartService function, a deadlock can occur, and the service may stop responding.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header ncrypt.h

Librar y Ncrypt.lib

DLL Ncrypt.dll
 NCryptKeyDerivation function (ncrypt.h)
7/2/2022 • 2 minutes to read • Edit Online

The NCr yptKeyDerivation function creates a key from another key by using the specified key derivation
function. The function returns the key in a byte array.

Syntax
SECURITY_STATUS NCryptKeyDerivation(
[in] NCRYPT_KEY_HANDLE hKey,
[in] NCryptBufferDesc *pParameterList,
[out] PUCHAR pbDerivedKey,
[in] DWORD cbDerivedKey,
[out] DWORD *pcbResult,
[in] ULONG dwFlags
);

Parameters
[in] hKey

Handle of the key derivation function (KDF) key.

[in] pParameterList

The address of a NCryptBufferDesc structure that contains the KDF parameters. The parameters can be specific
to a KDF or generic. The following table shows the required and optional parameters for specific KDFs
implemented by the Microsoft software key storage provider.

K DF PA RA M ET ER REQ UIRED

SP800-108 HMAC in counter mode KDF_LABEL yes

KDF_CONTEXT yes

KDF_HASH_ALGORITHM yes

SP800-56A KDF_ALGORITHMID yes

KDF_PARTYUINFO yes

KDF_PARTYVINFO yes

KDF_HASH_ALGORITHM yes

KDF_SUPPPUBINFO no

KDF_SUPPPRIVINFO no

PBKDF2 KDF_HASH_ALGORITHM yes

 KDF_SALT yes

KDF_ITERATION_COUNT no

CAPI_KDF KDF_HASH_ALGORITHM yes

The following generic parameter can be used:

KDF_GENERIC_PARAMETER
Generic parameters map to KDF specific parameters in the following manner:
SP800-108 HMAC in counter mode:
KDF_GENERIC_PARAMETER = KDF_LABEL||0x00||KDF_CONTEXT
SP800-56A
KDF_GENERIC_PARAMETER = KDF_ALGORITHMID || KDF_PARTYUINFO || KDF_PARTYVINFO {||
KDF_SUPPPUBINFO } {|| KDF_SUPPPRIVINFO }
PBKDF2
KDF_GENERIC_PARAMETER = KDF_SALT
KDF_ITERATION_COUNT – defaults to 10000
CAPI_KDF
KDF_GENERIC_PARAMETER = Not Used
[out] pbDerivedKey

Address of a buffer that receives the key. The cbDerivedKey parameter contains the size, in bytes, of the key
buffer.
[in] cbDerivedKey

Size, in bytes, of the buffer pointed to by the pbDerivedKey parameter.

[out] pcbResult

Pointer to a DWORD that receives the number of bytes copied to the buffer pointed to by the pbDerivedKey
parameter.
[in] dwFlags

Flags that modify function behavior. The following value can be used with the Microsoft software key storage
provider.

VA L UE M EA N IN G

Specifies that the target algorithm is AES and that the key
BCRYPT_CAPI_AES_FL AG therefore must be double expanded. This flag is only valid
with the CAPI_KDF algorithm.

Requests that the key service provider (KSP) not display any
NCRYPT_SILENT_FL AG user interface. If the provider must display the UI to operate,
the call fails and the KSP should set the
NTE_SILENT_CONTEXT error code as the last error.
Return value
Returns a status code that indicates the success or failure of the function.
Possible return codes include, but are not limited to, the following.

RET URN C O DE DESC RIP T IO N

The function was successful.

ERROR_SUCCESS

The hProvider or hKey handles are not valid.

NTE_INVALID_HANDLE

The pwszDerivedKeyAlg and pParameterList parameters

NTE_INVALID_PARAMETER cannot be NULL .

There was not enough memory to create the key.

NTE_NO_MEMORY

This function is not supported by the key storage provider.

NTE_NOT_SUPPORTED

Remarks
You can use the following algorithm identifiers in the NCryptCreatePersistedKey function before calling
NCr yptKeyDerivation :
BCRYPT_CAPI_KDF_ALGORITHM
BCRYPT_SP800108_CTR_HMAC_ALGORITHM
BCRYPT_SP80056A_CONCAT_ALGORITHM
BCRYPT_PBKDF2_ALGORITHM

Requirements

Minimum suppor ted client Windows 8 [desktop apps | UWP apps]

Minimum suppor ted ser ver Windows Server 2012 [desktop apps | UWP apps]

Target Platform Windows

Header ncrypt.h

Librar y Ncrypt.lib

DLL Ncrypt.dll

See also
BCryptKeyDerivation
NCryptDeriveKey
 NCryptKeyName structure (ncrypt.h)
7/2/2022 • 2 minutes to read • Edit Online

The NCr yptKeyName structure is used to contain information about a CNG key.

Syntax
typedef struct NCryptKeyName {
LPWSTR pszName;
LPWSTR pszAlgid;
DWORD dwLegacyKeySpec;
DWORD dwFlags;
} NCryptKeyName;

Members
pszName

A pointer to a null-terminated Unicode string that contains the name of the key.
pszAlgid

A pointer to a null-terminated Unicode string that contains the identifier of the cryptographic algorithm that the
key was created with. This can be one of the standard CNG Algorithm Identifiers or the identifier for another
registered algorithm.
dwLegacyKeySpec

A legacy identifier that specifies the type of key. This can be one of the following values.

VA L UE M EA N IN G

The key is a key exchange key.

AT_KEYEXCHANGE

The key is a signature key.

AT_SIGNATURE

The key is none of the above types.

0

dwFlags

A set of flags that provide more information about the key. This can be zero or the following value.

VA L UE M EA N IN G

The key applies to the local computer. If this flag is not

NCRYPT_MACHINE_KEY_FL AG present, the key applies to the current user.

Requirements
 Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Header ncrypt.h

See also
NCryptEnumKeys
 NCryptNotifyChangeKey function (ncrypt.h)
7/2/2022 • 2 minutes to read • Edit Online

The NCr yptNotifyChangeKey function creates or removes a key change notification.

The handle provided by this function is the same handle that is returned by the FindFirstChangeNotification
function. You use the wait functions to wait for the notification handle to be signaled.

Syntax
SECURITY_STATUS NCryptNotifyChangeKey(
[in] NCRYPT_PROV_HANDLE hProvider,
[in, out] HANDLE *phEvent,
[in] DWORD dwFlags
);

Parameters
[in] hProvider

The handle of the key storage provider. This handle is obtained by using the NCryptOpenStorageProvider
function.
[in, out] phEvent

The address of a HANDLE variable that either receives or contains the key change notification event handle.
This is the same handle that is returned by the FindFirstChangeNotification function. For more information, see
the dwFlags parameter description.
[in] dwFlags

A set of flags that modify the behavior of this function. This parameter contains a combination of one or more of
the following values.

VA L UE M EA N IN G

Create a new change notification. The phEvent parameter

NCRYPT_REGISTER_NOTIFY_FL AG will receive the key change notification handle.
0x00000001

Remove an existing change notification. The phEvent

NCRYPT_UNREGISTER_NOTIFY_FL AG parameter must contain a valid key change notification
0x00000002 handle. This handle is no longer valid after this function is
called with this flag and the INVALID_HANDLE_VALUE
value is placed in this handle.

Receive change notifications for keys in the machine key

NCRYPT_MACHINE_KEY_FL AG store. If this flag is not specified, the change notification
0x00000020 events will only occur for keys in the calling user's key store.
This flag is only valid when combined with the
NCRYPT_REGISTER_NOTIFY_FL AG flag.
Return value
Returns a status code that indicates the success or failure of the function.
Possible return codes include, but are not limited to, the following.

RET URN C O DE DESC RIP T IO N

The function was successful.

ERROR_SUCCESS

The dwFlags parameter contains a value that is not valid.

NTE_BAD_FL AGS

The hProvider parameter is not valid.

NTE_INVALID_HANDLE

One or more parameters are not valid.

NTE_INVALID_PARAMETER

Remarks
A service must not call this function from its StartService Function. If a service calls this function from its
StartService function, a deadlock can occur, and the service may stop responding.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header ncrypt.h

Librar y Ncrypt.lib

DLL Ncrypt.dll

See also
FindFirstChangeNotification
 NCryptOpenKey function (ncrypt.h)
7/2/2022 • 2 minutes to read • Edit Online

The NCr yptOpenKey function opens a key that exists in the specified CNG key storage provider.

Syntax
SECURITY_STATUS NCryptOpenKey(
[in] NCRYPT_PROV_HANDLE hProvider,
[out] NCRYPT_KEY_HANDLE *phKey,
[in] LPCWSTR pszKeyName,
[in] DWORD dwLegacyKeySpec,
[in] DWORD dwFlags
);

Parameters
[in] hProvider

The handle of the key storage provider to open the key from.
[out] phKey

A pointer to a NCRYPT_KEY_HANDLE variable that receives the key handle. When you have finished using this
handle, release it by passing it to the NCryptFreeObject function.
[in] pszKeyName

A pointer to a null-terminated Unicode string that contains the name of the key to retrieve.
[in] dwLegacyKeySpec

A legacy identifier that specifies the type of key. This can be one of the following values.

VA L UE M EA N IN G

The key is a key exchange key.

AT_KEYEXCHANGE

The key is a signature key.

AT_SIGNATURE

The key is none of the above types.

0

[in] dwFlags

Flags that modify function behavior. This can be zero or a combination of one or more of the following values.

VA L UE M EA N IN G
 Open the key for the local computer. If this flag is not
NCRYPT_MACHINE_KEY_FL AG present, the current user key is opened.

Requests that the key service provider (KSP) not display any
NCRYPT_SILENT_FL AG user interface. If the provider must display the UI to operate,
the call fails and the KSP should set the
NTE_SILENT_CONTEXT error code as the last error.

Return value
Returns a status code that indicates the success or failure of the function.
Possible return codes include, but are not limited to, the following.

RET URN C O DE DESC RIP T IO N

The function was successful.

ERROR_SUCCESS

The dwFlags parameter contains a value that is not valid.

NTE_BAD_FL AGS

The specified key was not found.

NTE_BAD_KEYSET

The hProvider parameter is not valid.

NTE_INVALID_HANDLE

One or more parameters are not valid.

NTE_INVALID_PARAMETER

A memory allocation failure occurred.

NTE_NO_MEMORY

Remarks
A service must not call this function from its StartService Function. If a service calls this function from its
StartService function, a deadlock can occur, and the service may stop responding.
For performance reasons, Microsoft software-based KSPs cache private key material in the Local Security
Authority (LSA) for as long as a handle to the key is open. The LSA is a privileged system process. Therefore,
other users cannot access this cached copy of the key unless the user possesses administrator privileges on the
system. This behavior cannot be altered through configuration.

Requirements

Minimum suppor ted client Windows Vista [desktop apps | UWP apps]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps | UWP apps]
Target Platform Windows

Header ncrypt.h

Librar y Ncrypt.lib

DLL Ncrypt.dll
 NCryptOpenStorageProvider function (ncrypt.h)
7/2/2022 • 2 minutes to read • Edit Online

The NCr yptOpenStorageProvider function loads and initializes a CNG key storage provider.

Syntax
SECURITY_STATUS NCryptOpenStorageProvider(
[out] NCRYPT_PROV_HANDLE *phProvider,
[in, optional] LPCWSTR pszProviderName,
[in] DWORD dwFlags
);

Parameters
[out] phProvider

A pointer to a NCRYPT_PROV_HANDLE variable that receives the provider handle. When you have finished
using this handle, release it by passing it to the NCryptFreeObject function.
[in, optional] pszProviderName

A pointer to a null-terminated Unicode string that identifies the key storage provider to load. This is the
registered alias of the key storage provider. This parameter is optional and can be NULL . If this parameter is
NULL , the default key storage provider is loaded. The following values identify the built-in key storage
providers.

VA L UE M EA N IN G

Identifies the software key storage provider that is provided

MS_KEY_STORAGE_PROVIDER by Microsoft.
L"Microsoft Software Key Storage Provider"

Identifies the smart card key storage provider that is

MS_SMART_CARD_KEY_STORAGE_PROVIDER provided by Microsoft.
L"Microsoft Smart Card Key Storage Provider"

Identifies the TPM key storage provider that is provided by

MS_PL ATFORM_CRYPTO_PROVIDER Microsoft.
L"Microsoft Platform Crypto Provider"

[in] dwFlags

Flags that modify the behavior of the function. No flags are defined for this function.

Return value
Returns a status code that indicates the success or failure of the function.
Possible return codes include, but are not limited to, the following.
 RET URN C O DE DESC RIP T IO N

The function was successful.

ERROR_SUCCESS

The dwFlags parameter contains one or more flags that are

NTE_BAD_FL AGS not supported.

One or more parameters are not valid.

NTE_INVALID_PARAMETER

A memory allocation failure occurred.

NTE_NO_MEMORY

Remarks
In the case that an error condition is returned, the provider will have been unloaded from memory. Functions
within the provider must not be called after a failure error is returned.
A service must not call this function from its StartService Function. If a service calls this function from its
StartService function, a deadlock can occur, and the service may stop responding.

Requirements

Minimum suppor ted client Windows Vista [desktop apps | UWP apps]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps | UWP apps]

Target Platform Windows

Header ncrypt.h

Librar y Ncrypt.lib

DLL Ncrypt.dll
 NCryptProviderName structure (ncrypt.h)
7/2/2022 • 2 minutes to read • Edit Online

The NCr yptProviderName structure is used to contain the name of a CNG key storage provider. This structure
is used with the NCryptEnumStorageProviders function to return the names of the registered CNG key storage
providers.

Syntax
typedef struct NCryptProviderName {
LPWSTR pszName;
LPWSTR pszComment;
} NCryptProviderName;

Members
pszName

A pointer to a null-terminated Unicode string that contains the name of the provider.
pszComment

A pointer to a null-terminated Unicode string that contains optional text for the provider.

Requirements

Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Header ncrypt.h

See also
NCryptEnumStorageProviders
 NCryptSecretAgreement function (ncrypt.h)
7/2/2022 • 2 minutes to read • Edit Online

The NCr yptSecretAgreement function creates a secret agreement value from a private and a public key.

Syntax
SECURITY_STATUS NCryptSecretAgreement(
[in] NCRYPT_KEY_HANDLE hPrivKey,
[in] NCRYPT_KEY_HANDLE hPubKey,
[out] NCRYPT_SECRET_HANDLE *phAgreedSecret,
[in] DWORD dwFlags
);

Parameters
[in] hPrivKey

The handle of the private key to use to create the secret agreement value. This key and the hPubKey key must
come from the same key storage provider.
[in] hPubKey

The handle of the public key to use to create the secret agreement value. This key and the hPrivKey key must
come from the same key storage provider.
[out] phAgreedSecret

A pointer to an NCRYPT_SECRET_HANDLE variable that receives a handle that represents the secret
agreement value. When this handle is no longer needed, release it by passing it to the NCryptFreeObject
function.
[in] dwFlags

Flags that modify function behavior. This can be zero or a combination of one or more of the following values.
The set of valid flags is specific to each key storage provider. The following flag applies to all providers.

VA L UE M EA N IN G

Requests that the key service provider (KSP) not display any
NCRYPT_SILENT_FL AG user interface. If the provider must display the UI to operate,
the call fails and the KSP should set the
NTE_SILENT_CONTEXT error code as the last error.

Return value
Returns a status code that indicates the success or failure of the function.
Possible return codes include, but are not limited to, the following.

RET URN C O DE DESC RIP T IO N

 The function was successful.
ERROR_SUCCESS

The hPrivKey or the hPubKey parameter is not valid.

NTE_INVALID_HANDLE

One or more parameters are not valid.

NTE_INVALID_PARAMETER

A memory allocation failure occurred.

NTE_NO_MEMORY

Remarks
A service must not call this function from its StartService Function. If a service calls this function from its
StartService function, a deadlock can occur, and the service may stop responding.

Requirements

Minimum suppor ted client Windows Vista [desktop apps | UWP apps]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps | UWP apps]

Target Platform Windows

Header ncrypt.h

Librar y Ncrypt.lib

DLL Ncrypt.dll

See also
NCryptFreeObject
 NCryptSetProperty function (ncrypt.h)
7/2/2022 • 2 minutes to read • Edit Online

The NCr yptSetProper ty function sets the value for a named property for a CNG key storage object.

Syntax
SECURITY_STATUS NCryptSetProperty(
[in] NCRYPT_HANDLE hObject,
[in] LPCWSTR pszProperty,
[in] PBYTE pbInput,
[in] DWORD cbInput,
[in] DWORD dwFlags
);

Parameters
[in] hObject

The handle of the key storage object to set the property for.
[in] pszProperty

A pointer to a null-terminated Unicode string that contains the name of the property to set. This can be one of
the predefined Key Storage Property Identifiers or a custom property identifier.
[in] pbInput

The address of a buffer that contains the new property value. The cbInput parameter contains the size of this
buffer.
[in] cbInput

The size, in bytes, of the pbInput buffer.

[in] dwFlags

Flags that modify function behavior. This can be zero or a combination of one or more of the following values.

VA L UE M EA N IN G

The property should be stored in key storage along with the

NCRYPT_PERSIST_FL AG key material. This flag can only be used when the hObject
parameter is the handle of a persisted key. The maximum
size of the data for any persisted property is
NCRYPT_MAX_PROPERTY_DATA bytes.

Do not overwrite any built-in values for this property and

NCRYPT_PERSIST_ONLY_FL AG only set the user-persisted properties of the key. The
maximum size of the data for any persisted property is
NCRYPT_MAX_PROPERTY_DATA bytes. This flag cannot
be used with the NCRYPT_SECURITY_DESCR_PROPERTY
property.
 Requests that the key service provider (KSP) not display any
NCRYPT_SILENT_FL AG user interface. If the provider must display the UI to operate,
the call fails and the KSP should set the
NTE_SILENT_CONTEXT error code as the last error.

For the NCRYPT_SECURITY_DESCR_PROPERTY property, this parameter must also contain one of the
following values, which identifies the part of the security descriptor to set.

VA L UE M EA N IN G

Set the security identifier (SID) of the object's owner. Use the
OWNER_SECURITY_INFORMATION SetSecurityDescriptorOwner function to set the owner SID in
the SECURITY_DESCRIPTOR structure.

Set the SID of the object's primary group. Use the

GROUP_SECURITY_INFORMATION SetSecurityDescriptorGroup function to set the group SID in
the SECURITY_DESCRIPTOR structure.

Set the discretionary access control list (DACL). Use the

DACL_SECURITY_INFORMATION SetSecurityDescriptorDacl function to set the DACL in the
SECURITY_DESCRIPTOR structure.

Set the system access control list (SACL). Use the

SACL_SECURITY_INFORMATION SetSecurityDescriptorSacl function to set the SACL in the
SECURITY_DESCRIPTOR structure.

Set the mandatory label access control entry in the SACL of

L ABEL_SECURITY_INFORMATION the object. Use the SetSecurityDescriptorSacl function to set
the SACL in the SECURITY_DESCRIPTOR structure. For more
information about the mandatory label access control entry,
see Windows Integrity Mechanism Design.

Return value
Returns a status code that indicates the success or failure of the function.
Possible return codes include, but are not limited to, the following.

RET URN C O DE DESC RIP T IO N

The function was successful.

ERROR_SUCCESS

The dwFlags parameter contains a value that is not valid.

NTE_BAD_FL AGS

The hObject parameter is not valid.

NTE_INVALID_HANDLE

One or more parameters are not valid.

NTE_INVALID_PARAMETER
 A memory allocation failure occurred.
NTE_NO_MEMORY

The specified property is not supported for the object.

NTE_NOT_SUPPORTED

Remarks
A service must not call this function from its StartService Function. If a service calls this function from its
StartService function, a deadlock can occur, and the service may stop responding.

Requirements

Minimum suppor ted client Windows Vista [desktop apps | UWP apps]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps | UWP apps]

Target Platform Windows

Header ncrypt.h

Librar y Ncrypt.lib

DLL Ncrypt.dll
 NCryptSignHash function (ncrypt.h)
7/2/2022 • 2 minutes to read • Edit Online

The NCr yptSignHash function creates a signature of a hash value.

Syntax
SECURITY_STATUS NCryptSignHash(
[in] NCRYPT_KEY_HANDLE hKey,
[in, optional] VOID *pPaddingInfo,
[in] PBYTE pbHashValue,
[in] DWORD cbHashValue,
[out] PBYTE pbSignature,
[in] DWORD cbSignature,
[out] DWORD *pcbResult,
[in] DWORD dwFlags
);

Parameters
[in] hKey

The handle of the key to use to sign the hash.

[in, optional] pPaddingInfo

A pointer to a structure that contains padding information. The actual type of structure this parameter points to
depends on the value of the dwFlags parameter. This parameter is only used with asymmetric keys and must be
NULL otherwise.
[in] pbHashValue

A pointer to a buffer that contains the hash value to sign. The cbInput parameter contains the size of this buffer.
[in] cbHashValue

The number of bytes in the pbHashValue buffer to sign.

[out] pbSignature

The address of a buffer to receive the signature produced by this function. The cbSignature parameter contains
the size of this buffer.
If this parameter is NULL , this function will calculate the size required for the signature and return the size in the
location pointed to by the pcbResult parameter.
[in] cbSignature

The size, in bytes, of the pbSignature buffer. This parameter is ignored if the pbSignature parameter is NULL .
[out] pcbResult

A pointer to a DWORD variable that receives the number of bytes copied to the pbSignature buffer.
If pbSignature is NULL , this receives the size, in bytes, required for the signature.
[in] dwFlags

Flags that modify function behavior. The allowed set of flags depends on the type of key specified by the hKey
parameter.
If the key is a symmetric key, this parameter is not used and should be set to zero.
If the key is an asymmetric key, this can be one of the following values.

VA L UE M EA N IN G

Use the PKCS1 padding scheme. The pPaddingInfo

BCRYPT_PAD_PKCS1 parameter is a pointer to a BCRYPT_PKCS1_PADDING_INFO
structure.

Use the Probabilistic Signature Scheme (PSS) padding

BCRYPT_PAD_PSS scheme. The pPaddingInfo parameter is a pointer to a
BCRYPT_PSS_PADDING_INFO structure.

Requests that the key service provider (KSP) not display any
NCRYPT_SILENT_FL AG user interface. If the provider must display the UI to operate,
the call fails and the KSP should set the
NTE_SILENT_CONTEXT error code as the last error.

Return value
Returns a status code that indicates the success or failure of the function.
Possible return codes include, but are not limited to, the following.

RET URN C O DE DESC RIP T IO N

The function was successful.

ERROR_SUCCESS

The key represented by the hKey parameter does not

NTE_BAD_ALGID support signing.

The dwFlags parameter contains a value that is not valid.

NTE_BAD_FL AGS

The hKey parameter is not valid.

NTE_INVALID_HANDLE

One or more parameters are not valid.

NTE_INVALID_PARAMETER

A memory allocation failure occurred.

NTE_NO_MEMORY

Remarks
A service must not call this function from its StartService Function. If a service calls this function from its
StartService function, a deadlock can occur, and the service may stop responding.
Requirements

Minimum suppor ted client Windows Vista [desktop apps | UWP apps]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps | UWP apps]

Target Platform Windows

Header ncrypt.h

Librar y Ncrypt.lib

DLL Ncrypt.dll
 NCryptTranslateHandle function (ncrypt.h)
7/2/2022 • 2 minutes to read • Edit Online

The NCr yptTranslateHandle function translates a CryptoAPI handle into a CNG key handle.

Syntax
SECURITY_STATUS NCryptTranslateHandle(
[out, optional] NCRYPT_PROV_HANDLE *phProvider,
[out] NCRYPT_KEY_HANDLE *phKey,
[in] HCRYPTPROV hLegacyProv,
[in, optional] HCRYPTKEY hLegacyKey,
[in, optional] DWORD dwLegacyKeySpec,
[in] DWORD dwFlags
);

Parameters
[out, optional] phProvider

A pointer to an NCRYPT_PROV_HANDLE variable that receives the handle of the CNG key storage provider
that owns the CNG key placed in the phKey parameter. This parameter can be NULL if this handle is not needed.
[out] phKey

A pointer to a NCRYPT_KEY_HANDLE variable that receives the CNG key handle.

[in] hLegacyProv

The handle of the CryptoAPI provider that contains the key to translate. This function will translate the
CryptoAPI key that is in the container in this provider.
[in, optional] hLegacyKey

The handle of a CryptoAPI key to use to help determine the key specification for the returned key. This
parameter is ignored if the dwLegacyKeySpec parameter contains a value other than zero.
If hLegacyKey is NULL and dwLegacyKeySpec is zero, this function will attempt to determine the key
specification from the hLegacyProv handle.
[in, optional] dwLegacyKeySpec

Specifies the key specification for the key. This can be one of the following values.

VA L UE M EA N IN G

The key is none of the types below.

0

The key is a key exchange key.

AT_KEYEXCHANGE
1
 The key is a signature key.
AT_SIGNATURE
2

If hLegacyKey is NULL and dwLegacyKeySpec is zero, this function will attempt to determine the key
specification from the hLegacyProv handle.
[in] dwFlags

A set of flags that modify the behavior of this function. No flags are defined for this function.

Return value
Returns a status code that indicates the success or failure of the function.
Possible return codes include, but are not limited to, the following.

RET URN C O DE DESC RIP T IO N

The function was successful.

ERROR_SUCCESS

The dwFlags parameter contains a value that is not valid.

NTE_BAD_FL AGS

One or more parameters are not valid.

NTE_INVALID_PARAMETER

A memory allocation failure occurred.

NTE_NO_MEMORY

Remarks
This is a helper function intended to help applications and system components that currently use the CryptoAPI
to make a graceful transition to using CNG.
This function will only be successful if a CNG key storage provider is registered with a name or alias that is
identical to the name of the cryptographic service provider (CSP) referred to by the hLegacyProv parameter.
This function will perform the following steps to translate the CSP handle into a CNG key handle:
1. Obtain the name of the CSP from the hLegacyProv handle.
2. Open the CNG provider whose name or alias is identical to the CSP name.
3. Obtain the name of the current key container in the CSP.
4. Obtain the CryptoAPI key, translate it into a CNG key, and return it in the phKey parameter.
A service must not call this function from its StartService Function. If a service calls this function from its
StartService function, a deadlock can occur, and the service may stop responding.

Requirements
Minimum suppor ted client Windows Vista [desktop apps only]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]

Target Platform Windows

Header ncrypt.h

Librar y Ncrypt.lib

DLL Ncrypt.dll
 NCryptVerifyClaim function (ncrypt.h)
7/2/2022 • 2 minutes to read • Edit Online

Verifies a key attestation claim.

Syntax
SECURITY_STATUS NCryptVerifyClaim(
[in] NCRYPT_KEY_HANDLE hSubjectKey,
[in, optional] NCRYPT_KEY_HANDLE hAuthorityKey,
[in] DWORD dwClaimType,
[in, optional] NCryptBufferDesc *pParameterList,
[in] PBYTE pbClaimBlob,
[in] DWORD cbClaimBlob,
[out] NCryptBufferDesc *pOutput,
[in] DWORD dwFlags
);

Parameters
[in] hSubjectKey

The subject key handle for the claim.

[in, optional] hAuthorityKey

The authority key handle to use when verifying the claim. This parameter is optional because the authority key is
self-contained for certain claim types.
[in] dwClaimType

The type of claim.

[in, optional] pParameterList

An optional parameter list.

[in] pbClaimBlob

The input claim blob.

[in] cbClaimBlob

[out] pOutput

The output blob.

[in] dwFlags

As of Windows 10, no flags are defined. This parameter should be set to 0.

Return value
Returns a status code that indicates the success or failure of the function.
Requirements

Minimum suppor ted client Windows 10 [desktop apps | UWP apps]

Minimum suppor ted ser ver Windows Server 2016 [desktop apps | UWP apps]

Target Platform Windows

Header ncrypt.h

Librar y Ncrypt.lib

DLL Ncrypt.dll
 NCryptVerifySignature function (ncrypt.h)
7/2/2022 • 2 minutes to read • Edit Online

The NCr yptVerifySignature function verifies that the specified signature matches the specified hash.

Syntax
SECURITY_STATUS NCryptVerifySignature(
[in] NCRYPT_KEY_HANDLE hKey,
[in, optional] VOID *pPaddingInfo,
[in] PBYTE pbHashValue,
[in] DWORD cbHashValue,
[in] PBYTE pbSignature,
[in] DWORD cbSignature,
[in] DWORD dwFlags
);

Parameters
[in] hKey

The handle of the key to use to decrypt the signature. This must be an identical key or the public key portion of
the key pair used to sign the data with the NCryptSignHash function.
[in, optional] pPaddingInfo

A pointer to a structure that contains padding information. The actual type of structure this parameter points to
depends on the value of the dwFlags parameter. This parameter is only used with asymmetric keys and must be
NULL otherwise.
[in] pbHashValue

The address of a buffer that contains the hash of the data. The cbHash parameter contains the size of this buffer.
[in] cbHashValue

The size, in bytes, of the pbHash buffer.

[in] pbSignature

The address of a buffer that contains the signed hash of the data. The NCryptSignHash function is used to create
the signature. The cbSignature parameter contains the size of this buffer.
[in] cbSignature

The size, in bytes, of the pbSignature buffer. The NCryptSignHash function is used to create the signature.
[in] dwFlags

Flags that modify function behavior. The allowed set of flags depends on the type of key specified by the hKey
parameter.
If the key is a symmetric key, this parameter is not used and should be zero.
If the key is an asymmetric key, this can be one of the following values.
 VA L UE M EA N IN G

The PKCS1 padding scheme was used when the signature

NCRYPT_PAD_PKCS1_FL AG was created. The pPaddingInfo parameter is a pointer to a
BCRYPT_PKCS1_PADDING_INFO structure.

The Probabilistic Signature Scheme (PSS) padding scheme

NCRYPT_PAD_PSS_FL AG was used when the signature was created. The pPaddingInfo
parameter is a pointer to a BCRYPT_PSS_PADDING_INFO
structure.

Requests that the key service provider (KSP) not display any
NCRYPT_SILENT_FL AG user interface. If the provider must display the UI to operate,
the call fails and the KSP should set the
NTE_SILENT_CONTEXT error code as the last error.

Return value
Returns a status code that indicates the success or failure of the function.
Possible return codes include, but are not limited to, the following.

RET URN C O DE DESC RIP T IO N

The function was successful.

ERROR_SUCCESS

The signature was not verified.

NTE_BAD_SIGNATURE

The hKey parameter is not valid.

NTE_INVALID_HANDLE

A memory allocation failure occurred.

NTE_NO_MEMORY

The algorithm provider used to create the key handle

NTE_NOT_SUPPORTED specified by the hKey parameter is not a signing algorithm.

Remarks
A service must not call this function from its StartService Function. If a service calls this function from its
StartService function, a deadlock can occur, and the service may stop responding.

Requirements

Minimum suppor ted client Windows Vista [desktop apps | UWP apps]

Minimum suppor ted ser ver Windows Server 2008 [desktop apps | UWP apps]

Target Platform Windows

 Header ncrypt.h

Librar y Ncrypt.lib

DLL Ncrypt.dll

See also
NCryptSignHash
 ncryptprotect.h header
7/2/2022 • 2 minutes to read • Edit Online

This header is used by Security and Identity. For more information, see:
Security and Identity
ncryptprotect.h contains the following programming interfaces:

Functions

NCryptCloseProtectionDescriptor

Zeros and frees a protection descriptor object and releases its handle.

NCryptCreateProtectionDescriptor

Retrieves a handle to a protection descriptor object.

NCryptGetProtectionDescriptorInfo

Retrieves a protection descriptor rule string.

NCryptProtectSecret

Encrypts data to a specified protection descriptor.

NCryptQueryProtectionDescriptorName

Retrieves the protection descriptor rule string associated with a registered descriptor display name.

NCryptRegisterProtectionDescriptorName

Registers the display name and the associated rule string for a protection descriptor.

NCryptStreamClose

Closes a data protection stream object opened by using the NCryptStreamOpenToProtect or NCryptStreamOpenToUnprotect
functions.

NCryptStreamOpenToProtect

Opens a stream object that can be used to encrypt large amounts of data to a given protection descriptor.

NCryptStreamOpenToUnprotect

Opens a stream object that can be used to decrypt large amounts of data to the same protection descriptor used for
encryption.
 NCryptStreamOpenToUnprotectEx

Opens a stream object that can be used to decrypt large amounts of data to the same protection descriptor used for
encryption.

NCryptStreamUpdate

Encrypts and decrypts blocks of data.

NCryptUnprotectSecret

Decrypts data to a specified protection descriptor.

Callback functions

PFNCryptStreamOutputCallback

Receives encrypted or decrypted data from tasks started by using the NCryptStreamOpenToProtect or
NCryptStreamOpenToUnprotect functions.

Structures

NCRYPT_PROTECT_STREAM_INFO

Is used by the NCryptStreamOpenToProtect and NCryptStreamOpenToUnprotect functions to pass blocks of processed data
to your application.
 NCRYPT_PROTECT_STREAM_INFO structure
(ncryptprotect.h)
7/2/2022 • 2 minutes to read • Edit Online

The NCRYPT_PROTECT_STREAM_INFO structure is used by the NCryptStreamOpenToProtect and

NCryptStreamOpenToUnprotect functions to pass blocks of processed data to your application.

Syntax
typedef struct NCRYPT_PROTECT_STREAM_INFO {
PFNCryptStreamOutputCallback pfnStreamOutput;
void *pvCallbackCtxt;
} NCRYPT_PROTECT_STREAM