3.1.4.2.14 ICertAdminD2::GetConfigEntry (Opnum 44)

  • Article

The GetConfigEntry method retrieves the CAs that persisted the configuration data listed in section 3.1.1.10. Configuration data is represented as a hierarchical data structure with the following format: [\pwszAuthority][\pwszNodePath][\pwszEntry].

 HRESULT GetConfigEntry(
   [in, string, unique] wchar_t const* pwszAuthority,
   [in, string, unique] wchar_t const* pwszNodePath,
   [in, string, ref] wchar_t const* pwszEntry,
   [out, ref] VARIANT* pVariant
 );

pwszAuthority: See the pwszAuthority definition in section 3.1.4.1.1.

pwszNodePath: A string value that represents the node path for the configuration information. This parameter can be an empty string and MUST NOT be NULL.<72>

pwszEntry: A string value that represents the name of the leaf entry whose information is being retrieved. This value can be an EMPTY string and MUST NOT be NULL.<73>

pVariant: A pointer to a VARIANT that receives the requested information.

On Windows, the CA uses these datatypes to set the data that it stores in the registry:

REG_BINARY – The vt member of VARIANT is set to VT_ARRAY|VT_UI1 and the pArray member references a single dimension SAFEARRAY the binary data. The number of elements of the SAFEARRAY reference by pArray is equal to the length of binary data.

REG_DWORD – The vt member of VARIANT is set to VT_I4 and the lVal member is the registry value.

REG_SZ – The vt member of VARIANT is set to VT_BSTR and the bstrVal member is set to BSTR for Unicode string in the registry value.

REG_MULTI_SZ – The vt member of VARIANT is set to VT_ARRAY|VT_BSTR and the pArray member references a single dimension SAFEARRAY. The number of elements of the SAFEARRAY referenced by pArray is equal to the number of the strings in the registry value. For each string, there is an element in the SAFEARRAY referenced by pArray containing the BSTR for Unicode string value in the registry.

The GetConfigEntry method retrieves the CA configuration data or configuration data hierarchy information.

The following processing rules apply:

  1. If pwszAuthority parameter is EMPTY and pwszNodePath parameter is EMPTY and pwszNodeEntry is EMPTY, the CA MUST return all available leaf properties' names that exist in the configuration's root node as a VARIANT array.

  2. If pwszAuthority is EMPTY and pwszNodePath is EMPTY and pwszNodeEntry is not EMPTY, the CA must return the leaf property value identified by pwszNodeEntry that exists under the Configuration root node as a VARIANT.

  3. If pwszAuthority is EMPTY and pwszNodePath is not EMPTY, for any value of pwszNodeEntry the CA MUST fail the call with an error code of 0x80070057.

  4. If pwszAuthority parameter is not EMPTY and pwszNodePath is EMPTY and pwszNodeEntry is EMPTY, the CA MUST return all available leaf properties' names that exist under the pwszAuthority node as a VARIANT array.

  5. If pwszAuthority parameter is not EMPTY and pwszNodePath is EMPTY and pwszNodeEntry is not EMPTY, the CA MUST return the leaf property value identified by pwszNodeEntry that exists under the pwszAuthority node as a VARIANT array.

  6. If pwszAuthority parameter is not EMPTY and pwszNodePath is not EMPTY and pwszEntry is EMPTY, the CA MUST return all available leaf properties' names that exist under the pwszNodePath node as a VARIANT array.

  7. If pwszAuthority parameter is not EMPTY and pwszNodePath is not EMPTY and pwszEntry is not EMPTY, the CA MUST return the leaf property value identified by pwszNodeEntry that exists under the pwszNodePath node as a VARIANT array.

  8. For each input in the left column of the table below, the CA MUST perform the processing rules in the corresponding cell in the right column.

    Input Parameters

    Processing rule for pVariant

    pwszNodePath is EMPTY and pwszEntry is "Security"

    The CA MUST return the value of the OnNextRestart_Config_Permissions_CA_Security ADM element as a VARIANT.

    The vt member of VARIANT MUST be set to VT_ARRAY|VT_UI1 and the pArray member MUST reference a single dimension safearray. The number of elements of the safearray reference by pArray MUST be equal to the length of marshaled Security Descriptor.

    Security Descriptor is as specified in [MS-DTYP] section 2.4.6.

    pwszAuthority is EMPTY and pwszNodePath is EMPTY and pwszEntry is "SetupStatus"

    The CA MUST return the value of the OnNextRestart_Config_Setup_Status ADM element as a VARIANT.

    The vt member of the VARIANT MUST be set to VT_I4 and the lVal member MUST be either 0 or a bitwise OR of the following values:

    0x00000001 – server installed

    0x00000002 – client installed

    0x00000004 – incomplete installation

    0x00000008 – new cert requested

    0x00000010 – requested online

    0x00000020 – request denied

    0x00000040 – create a new DB

    0x00000080 – try to create vroots

    0x00000100 – force new CRLs to be generated

    0x00000200 – add server type to the CA DS object ‘flags’ attribute

    0x00000400 – server was upgraded

    0x00000800 – still need to upgrade security from Windows 2000 operating system

    0x00001000 – permissions changed while the CA was down and the CA will need to update the directory service when it restarts

    0x00002000 – global DCOM security has been fixed (in Windows 2000 operating system Service Pack 1 (SP1))

    0x00004000 – server is up-to-date

    pwszNodePath is EMPTY and pwszEntry is "UseDS"

    The CA MUST return the value of the OnNextRestart_Config_CA_Use_DS ADM element as a VARIANT.

    The vt member of the VARIANT MUST be set to VT_I4 and the lVal member MUST be set to one of the following values:

    0 – The CA is not using Active Directory for CRL publication

    Any nonzero value: The CA is using AD for CRL publication

    pwszNodePath is EMPTY and pwszEntry is "CAType"

    The CA MUST return the value of the OnNextRestart_Config_CA_Type ADM element as a VARIANT.

    The vt member of the VARIANT MUST be set to VT_I4 and the lVal member MUST be set to one of the CAType values specified in [MS-WCCE] section 2.2.2.4.

    pwszNodePath is EMPTY and pwszEntry is "KRAFlags"

    The CA MUST return the value of the OnNextRestart_Config_CA_KRA_Flags ADM element as a VARIANT.

    The vt member of the VARIANT MUST be set to VT_I4 and the lVal member MUST be one the following values:

    0

    0x00000001 – allow foreign certificate key archival

    pwszAuthority is EMPTY and pwszNodePath is EMPTY and pwszEntry is "Version"

    The CA MUST return the value of the OnNextRestart_Config_Product_Version ADM element as a VARIANT.

    The vt member of the VARIANT MUST be set to VT_I4 and the lVal member MUST be set to the one of the following values:

    0x00010001 – Server is Windows 2000 Server operating system

    0x00020002 – Server is Windows Server 2003 operating system

    0x00030001 – Server is Windows Server 2008 operating system

    0x00040001 – Server is Windows Server 2008 R2 operating system

    0x00050001 – Server is Windows Server 2012 operating system

    0x00060001 – Server is Windows Server 2012 R2 operating system <74>

    0x00070001 – Server is Windows Server 2016 operating system or Windows Server 2019 operating system

    pwszNodePath is EMPTY and pwszEntry is "CommonName"

    The CA MUST return the value of the OnNextRestart_Config_CA_Common_Name ADM element as a VARIANT.

    The vt member of the VARIANT MUST be set to VT_BSTR and the bstrVal member MUST be BSTR for the Unicode string value of the common name of the CA.

    pwszNodePath is EMPTY and pwszEntry is "InterfaceFlags"

    The CA MUST return the value of the OnNextRestart_Config_CA_Interface_Flags ADM element as a VARIANT.

    The vt member of the VARIANT MUST be set to VT_I4 and the lVal member MUST be either 0 or a bitwise-OR of the following values:

    IF_LOCKICERTREQUEST = 0x1

    This value has no effect.

    IF_NOREMOTEICERTREQUEST = 0x2

    The CA will not issue any certificates or hold pending any requests for remote users.

    IF_NOLOCALICERTREQUEST = 0x4

    The CA will not issue any certificates or hold pending any requests for local users.

    IF_NORPCICERTREQUEST = 0x8

    The CA will not issue any certificates or hold pending any requests for callers using the ICertPassage interface.

    IF_NOREMOTEICERTADMIN = 0x10 (16)

    No access to Certificate Services Remote Administration Protocol methods for remote callers.

    IF_NOLOCALICERTADMIN = 0x20 (32)

    No access to Certificate Services Remote Administration Protocol methods for local callers.

    IF_NOREMOTEICERTADMINBACKUP = 0x40 (64)

    The CA restricts access to the backup-related methods of this protocol for remote callers.

    IF_NOLOCALICERTADMINBACKUP = 0x80 (128)

    The CA restricts access to the backup-related methods of this protocol for local callers.

    IF_NOSNAPSHOTBACKUP = 0x100 (256)

    The database files cannot be backed up using a mechanism other than the methods of this interface.

    IF_ENFORCEENCRYPTICERTREQUEST = 0x200 (512)

    RPC_C_AUTHN_LEVEL_PKT_PRIVACY, as defined in [MS-RPCE] section 2.2.1.1.8, must be defined for all RPC connections to the server for certificate-request operations.

    IF_ENFORCEENCRYPTICERTADMIN = 0x400 (1024)

    RPC_C_AUTHN_LEVEL_PKT_PRIVACY, as defined in [MS-RPCE] section 2.2.1.1.8, must be defined for all RPC connections to the server for certificate administrative operations (the methods defined in this interface).

    IF_ENABLEEXITKEYRETRIEVAL = 0x800 (2048)

    Enables an exit algorithm to retrieve the Encrypted private-Key Blob.

    IF_ENABLEADMINASAUDITOR = 0x1000 (4096)

    Only CA administrators can update the CA audit filter settings.

    pwszNodePath is EMPTY and pwszEntry is "HighSerial"

    If the value of the OnNextRestart_Config_High_Serial_String is not empty, the CA MUST return the value of the OnNextRestart_Config_High_Serial_String. Otherwise, the CA MUST return the value of the OnNextRestart_Config_High_Serial_Number.

    pwszEntry is "Provider" and pwszNodePath is "CSP"

    The CA MUST return the value of the OnNextRestart_Config_CSP_Provider ADM element as a VARIANT.

    The vt member of the VARIANT MUST be set to VT_BSTR and the bstrVal member MUST be BSTR for the Unicode string value of the provider.

    pwszEntry is "ProviderType" and pwszNodePath is "CSP"

    The CA MUST return the value of the OnNextRestart_Config_CSP_ProviderType ADM element as a VARIANT.

    The vt member of VARIANT MUST be set to VT_I4 and the lVal member MUST be set to the provider type.

    pwszEntry is "HashAlgorithm" and pwszNodePath is "CSP"

    The CA MUST return the value of the OnNextRestart_Config_CSP_Hash_Algorithm ADM element as a VARIANT.

    The vt member of the VARIANT MUST be set to VT_I4 and the lVal member MUST be set to the algid (algorithm identifier) that corresponds to the hash algorithm used by the CA.

    pwszEntry is "CNGHashAlgorithm" and pwszNodePath is "CSP"

    The CA MUST return the value of the OnNextRestart_Config_CSP_CNG_Hash_Algorithm ADM element as a VARIANT.

    The vt member of the VARIANT MUST be set to VT_BSTR and the bstrVal member MUST be BSTR for the Unicode string value of the name of the CNG hash algorithm used by the CA.

    pwszNodePath is EMPTY and pwszEntry is "CRLPeriodUnits"

    The CA MUST return the numeric value of the Config_Base_CRL_Validity_Period ADM element as a VARIANT.

    The vt member of the VARIANT MUST be set to VT_I4 and the lVal member MUST be set to the CRL publication period value.

    A value of 0 means CRL publishing is disabled.

    pwszNodePath is EMPTY and pwszEntry is "CRLPeriod"

    The CA MUST return the value of the units of time with which the Config_Base_CRL_Validity_Period ADM element is counted as a VARIANT.

    The vt member of the VARIANT MUST be set to VT_BSTR and the bstrVal member MUST be BSTR for the Unicode string value of one of following:

    Years

    Months

    Weeks

    Days

    Hours

    Minutes

    Seconds

    pwszNodePath is EMPTY and pwszEntry is "CRLDeltaPeriodUnits"

    The CA MUST return the numeric value of the Config_Delta_CRL_Validity_Period ADM element as a VARIANT.

    The vt member of the VARIANT MUST be set to VT_I4 and the lVal member MUST be set to the delta CRL publication period.

    A value of 0 for means Delta CRL publishing is disabled.

    pwszNodePath is EMPTY and pwszEntry is "CRLDeltaPeriod"

    The CA MUST return the value of the units of time with which the Config_Delta_CRL_Validity_Period ADM element is counted as a VARIANT.

    The vt member of the VARIANT MUST be set to VT_BSTR and the bstrVal member MUST be BSTR for the Unicode string value of one of following:

    Years

    Months

    Weeks

    Days

    Hours

    Minutes

    Seconds

    pwszNodePath is EMPTY and pwszEntry is "CRLNextPublish"

    The CA MUST return the value of the ADM element OnNextRestart_Config_CA_CRL_Next_Publish as a VARIANT.

    The vt member of the VARIANT MUST be set to VT_ARRAY|VT_UI1 and the pArray member MUST reference a single dimension safearray. The number of elements of the safearray reference by pArray SHOULD be equal to 8 bytes. The value of the bytes must contain a 64-bit value that represents the number of 100-nanosecond intervals since January 1, 1601, according to Coordinated Universal Time (UTC) (encoded in little endian).

    pwszNodePath is EMPTY and pwszEntry is "CRLDeltaNextPublish"

    The CA MUST return the value of the ADM element OnNextRestart_Config_CA_CRL_Delta_Next_Publish as a VARIANT.

    The vt member of the VARIANT MUST be set to VT_ARRAY|VT_UI1 and the pArray member MUST reference a single dimension safearray. The number of elements of the safearray reference by pArray SHOULD be equal to 8 bytes. The value of the bytes must contain a 64-bit value that represents the number of 100-nanosecond intervals since January 1, 1601, according to Coordinated Universal Time (UTC) (encoded in little endian).

    pwszNodePath is EMPTY and pwszEntry is "AuditFilter"

    The CA MUST return the value of the OnNextRestart_Config_CA_Audit_Filter ADM element as a VARIANT.

    The vt member of VARIANT MUST be set to VT_I4 and the lVal member MUST be either 0 or bitwise OR of the following values.

    0x00000001 – Audit start/stop of the service.

    0x00000002 – Audit operations associated with backup/restore of the CA database.

    0x00000004 – Audit operations associated with certificate issuance.

    0x00000008 – Audit operations associated with certificate revocation.

    0x00000010 – Audit changes to the security settings on the Certificate Authority Service.

    0x00000020 – Audit operations associated with Key Recovery.

    0x00000040 – Audit operations associated with Changes in CA configuration.

    pwszEntry is "Active" and pwszNodePath is "PolicyModules"

    The CA MUST return the value of the OnNextRestart_Config_CA_Policy_Algorithm_Implementation ADM element as a VARIANT.

    The vt member of the VARIANT MUST be set to VT_BSTR and the bstrVal member MUST be BSTR for the Unicode string value of the name (progid) of the policy algorithm

    By default the Microsoft CA uses a policy module called "CertificateAuthority_MicrosoftDefault.Policy" as the policy algorithm. For more information on the policy algorithm, see [MS-WCCE] section 3.2.1.4.2.1.4.5.

    pwszEntry is "Active" and pwszNodePath is "ExitModules"

    The CA MUST return the value of the OnNextRestart_Config_CA_Exit_Algorithm_Implementation_List ADM element as a VARIANT.

    The vt member of the VARIANT MUST be set to VT_ARRAY|VT_BSTR and the pArray member MUST reference a single dimension safearray.

    The number of elements of the safearray referenced by pArray MUST be equal to the number of active exit algorithms on the CA. For each exit algorithm, there MUST be an element in the safearray referenced by pArray containing the BSTR for the Unicode string value of the name (progid) of the exit algorithm.

    By default, the Microsoft CA uses an exit module called "CertificateAuthority_MicrosoftDefault.Exit" as the default active exit algorithm. For more information on the exit algorithm, see [MS-WCCE] section 3.2.1.4.2.1.4.9.

    pwszNodePath is EMPTY and pwszEntry is "CRLPublicationURLs"

    The CA MUST use the values of the following ADM elements to create the VARIANT returned:

    OnNextRestart_Config_CA_CDP_Publish_To_Base

    OnNextRestart_Config_CA_CDP_Publish_To_Delta

    OnNextRestart_Config_CA_CDP_Include_In_Cert

    OnNextRestart_Config_CA_CDP_Include_In_CRL_Publish_Locations_Extension

    OnNextRestart_Config_CA_CDP_Include_In_CRL_Freshest_CRL_Extension

    OnNextRestart_Config_CA_CDP_Include_In_CRL_IDP_Extension

    The vt member of the VARIANT MUST be set to VT_ARRAY | VT_BSTR and the pArray member MUST reference a single dimension safearray.

    The number of elements of the safearray referenced by pArray MUST be equal to the number of URLs. For each URL, there MUST be an element in the safearray referenced by pArray containing the BSTR for the Unicode string value of the URI.

    Each URI is of the format "NumericPrefix:URI", where NumericPrefix is the decimal value corresponding to the combination of following flags:

    0x00000001 – The CA must publish the CRL to the URI (OnNextRestart_Config_CA_CDP_Publish_To_Base).

    0x00000002 – The URI is to be added in the CDP extension of the certificate issued by the CA (OnNextRestart_Config_CA_CDP_Include_In_Cert).

    0x00000004 – The URI is to be added in the FreshestCRL extension of the CRL issued by the CA (OnNextRestart_Config_CA_CDP_Include_In_CRL_Freshest_CRL_Extension).

    0x00000008 – The URI is to be added in the CDP extension of the CRL issued by the CA (OnNextRestart_Config_CA_CDP_Include_In_CRL_Publish_Locations_Extension).

    0x00000010 – Not Used.

    0x00000040 – The CA must publish the Delta CRL to the URI (OnNextRestart_Config_CA_CDP_Publish_To_Delta).

    0x00000080 – The URI is to be added in the IDP extension of the CRL issued by the CA (OnNextRestart_Config_CA_CDP_Include_In_CRL_IDP_Extension).

    pwszNodePath is EMPTY and pwszEntry is "CACertPublicationURLs"

    The CA MUST use the values of the following ADM elements to create the VARIANT returned:

    OnNextRestart_Config_CA_AIA_Include_In_Cert

    OnNextRestart_Config_CA_CACert_Publish_To

    The vt member of the VARIANT MUST be set to VT_ARRAY | VT_BSTR and the pArray member MUST reference a single dimension safearray.

    The number of elements of the safearray referenced by pArray MUST be equal to the number of URLs. For each URL, there MUST be an element in the safearray referenced by pArray containing the BSTR for the Unicode string value of the URI.

    Each URI is of the format "NumericPrefix:URI", where NumericPrefix is the decimal value corresponding to the combination of following flags:

    0x00000001 – The CA must publish the CA certificate(s) to the URI (OnNextRestart_Config_CA_CACert_Publish_To).

    0x00000002 – The URI is to be added in the AIA extension of the certificates issued by the CA (OnNextRestart_Config_CA_AIA_Include_In_Cert).

    pwszNodePath is "PolicyModules\CertificateAuthority_MicrosoftDefault.Policy" and pwszEntry is "RequestDisposition"

    The CA MUST return the value of the OnNextRestart_Config_CA_Requests_Disposition as a VARIANT. The vt member of VARIANT MUST be set to VT_I4 and the lVal member MUST be the value of the OnNextRestart_Config_CA_Requests_Disposition ADM element. The value of this ADM element determines whether the CA sets all requests to pending, accepts all requests, or denies all requests.